Merge branch 'master' into cooking

[xonotic/gmqcc.git] / doc / gmqcc.1

diff --git a/doc/gmqcc.1 b/doc/gmqcc.1
index 6ede944f1ffb68be44140899140e0ae7ba1e8439..2a205bbbeef634870e788eec0abfad1aa90185b9 100644 (file)
--- a/doc/gmqcc.1
+++ b/doc/gmqcc.1
@@ -153,7 +153,7 @@ Adds compiler information to the generated binary file. Currently
 this includes the following globals:
 .Bl -tag -width indent -compact
 .It Li reserved:version
-String containing the compiler version as printed by the --version
+String containing the compiler version as printed by the \-\-version
 parameter.
 .El
 .It Fl -correct , Fl -no-correct
@@ -320,6 +320,30 @@ marked as such.
 Warn about possible mistakes caused by missing or wrong parenthesis,
 like an assignment in an 'if' condition when there's no additional set
 of parens around the assignment.
+.It Fl W Ns Cm unsafe-types
+When passing variadic parameters via
+.Li ...(N)
+it can happen that incompatible types are passed to functions. This
+enables several warnings when static typechecking cannot guarantee
+consistent behavior.
+.It Fl W Ns Cm breakdef
+When compiling original id1 QC there is a definition for `break`
+which conflicts with the 'break' keyword in GMQCC. Enabling this
+will print a warning when the definition occurs. The definition is
+ignored for both cases.
+.It Fl W Ns Cm const-overwrite
+When compiling original QuakeWorld QC there are instances where
+code overwrites constants. This is considered an error, however
+for QuakeWorld to compile it needs to be treated as a warning
+instead, as such this warning only works when -std=qcc.
+.It Fl W Ns Cm directive-inmacro
+Warn about the use of preprocessor directives inside macros.
+.It Fl W Ns Cm builtins
+When using a function that is not explicitly defined, the compiler
+will search its intrinsics table for something that matches that
+function name by appending "__builtin_" to it. This behaviour may
+be unexpected, so enabling this will produce a diagnostic when
+such a function is resolved to a builtin.
 .El
 .Sh COMPILE FLAGS
 .Bl -tag -width Ds
@@ -340,7 +364,7 @@ features used in the Xonotic codebase. If you need more, write a
 ticket.
 .It Fl f Ns Cm ftepp-predefs
 Enable some predefined macros. This only works in combination with
-\'-fftepp' and is currently not included by '-std=fteqcc'. The
+\'\-fftepp' and is currently not included by '\-std=fteqcc'. The
 following macros will be added:
 .Bd -literal -offset indent
 __LINE__
@@ -518,6 +542,21 @@ float fun() {
     return = bar();
     return; // returns value of bar
 }
+.Ed
+.It Fl f Ns Cm unsafe-varargs
+When passing on varargs to a different functions, this turns some
+static error cases into warnings. Like when the caller's varargs are
+restricted to a different type than the callee's parameter. Or a list
+of unrestricted varargs is passed into restricted varargs.
+.It Fl f Ns Cm typeless-stores
+Always use STORE_F, LOAD_F, STOREP_F when accessing scalar variables.
+This is somewhat incorrect assembly instruction use, but in all engines
+they do exactly the same. This makes disassembly output harder to read,
+breaks decompilers, but causes the output file to be better compressible.
+.It Fl f Ns Cm sort-operands
+In commutative instructions, always put the lower-numbered operand first.
+This shaves off 1 byte of entropy from all these instructions, reducing
+compressed size of the output file.
 .El
 .Sh OPTIMIZATIONS
 .Bl -tag -width Ds
@@ -562,7 +601,7 @@ string being added.
 .Pp
 For example the following code will only generate 1 string:
 .Bd -literal -offset indent
-print("Hell you!\\n");
+print("Hello you!\\n");
 print("you!\\n"); // trailing substring of "Hello you!\\n"
 .Ed
 .Pp
@@ -594,6 +633,10 @@ in this case, the y component of a vector. This optimization will turn
 such a multiplication into a direct component access. If the factor is
 anything other than 1, a float-multiplication will be added, which is
 still faster than a vector multiplication.
+.It Fl O Ns Cm const-fold-dce
+For constant expressions that result in dead code (such as a branch whos
+condition can be evaluated at compile-time), this will eliminate the branch
+and else body (if present) to produce more optimal code.
 .El
 .Sh CONFIG
 The configuration file is similar to regular .ini files. Comments
@@ -643,7 +686,7 @@ A documented example for a gmqcc.ini file.
 .Sh AUTHOR
 See <http://graphitemaster.github.com/gmqcc>.
 .Sh BUGS
-Currently the '-fftepp-predefs' flag is not included by '-std=fteqcc',
+Currently the '\-fftepp-predefs' flag is not included by '\-std=fteqcc',
 partially because it is not entirely conformant to fteqcc.
 .Pp
 Please report bugs on <http://github.com/graphitemaster/gmqcc/issues>,