Cleanups

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

diff --git a/doc/gmqcc.1 b/doc/gmqcc.1
index 59afdb99dd85abc5bce9239c2697ecbe2e968cf0..9220e242eca811432d11e41b7f36fe8b2c956643 100644 (file)
--- a/doc/gmqcc.1
+++ b/doc/gmqcc.1
@@ -24,10 +24,6 @@ there are also traditional long-options available.
 .Bl -tag -width Ds
 .It Fl h , Fl -help
 Show a usage message and exit.
-.It Fl "debug"
-Turn on some compiler debugging mechanisms.
-.It Fl memchk
-Turn on compiler mem-check. (Shows allocations and checks for leaks.)
 .It Fl o , Fl -output= Ns Ar filename
 Specify the output filename. Defaults to progs.dat. This will overwrite
 the output file listed in a
@@ -46,7 +42,7 @@ Minimal optimization level
 Disable optimization entirely
 .El
 .Pp
-.It Fl O Ns Ar name Fl Ono- Ns Ar name
+.It Fl O Ns Ar name , Fl Ono- Ns Ar name
 Enable or disable a specific optimization. Note that these options
 must be used after setting the optimization level, otherwise they'll
 be overwritten.
@@ -57,6 +53,8 @@ activated at.
 Be less verbose. In particular removes the messages about which files
 are being processed, and which compilation mode is being used, and
 some others. Warnings and errors will of course still be displayed.
+.It Fl D Ns Ar macroname , Fl D Ns Ar macroname Ns = Ns Ar value
+Predefine a macro, optionally with a optional value.
 .It Fl E
 Run only the preprocessor as if
 .Fl f Ns Cm ftepp
@@ -93,6 +91,12 @@ Use an ini file to read all the
 and
 .Fl f
 flag from. See the
+.It Fl "debug"
+Turn on some compiler debugging mechanisms.
+.It Fl memchk
+Turn on compiler mem-check. (Shows allocations and checks for leaks.)
+.It Fl -memdumpcols Ns Ar columns
+Changes the number of columns to use for the debug memory dump, defaults to 16.
 .Sx CONFIG
 section about the file format.
 .It Fl redirout= Ns Ar file
@@ -316,6 +320,12 @@ 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.
 .El
 .Sh COMPILE FLAGS
 .Bl -tag -width Ds
@@ -347,15 +357,28 @@ __RANDOM__
 __RANDOM_LAST__
 __DATE__
 __TIME__
+__FUNC__
 .Ed
 .Pp
+Note that
+.Li __FUNC__
+is not actually a preprocessor macro, but is recognized by the parser
+even with the preprocessor disabled.
+.Pp
 Note that fteqcc also defines
 .Li __NULL__
-which is not implemented yet.
+which becomes the first global. Assigning it to a vector does not
+yield the same result as in gmqcc where
+.Li __NULL__
+is defined to
+.Li nil
 (See
 .Fl f Ns Cm untyped-nil
-about gmqcc's alternative to
-.Li __NULL__ Ns ).
+), which will cause the vector to be zero in all components. With fteqcc
+only the first component will be 0, while the other two will become
+the first to of the global return value. This behavior is odd and
+relying on it should be discouraged, and thus is not supported by
+gmqcc.
 .It Fl f Ns Cm relaxed-switch
 Allow switch cases to use non constant variables.
 .It Fl f Ns Cm short-logic
@@ -480,6 +503,33 @@ void vafunc(string...count) {
 Most Quake VMs, including the one from FTEQW or up till recently
 Darkplaces, do not cope well with vector instructions with overlapping
 input and output. This option will avoid producing such code.
+.It Fl f Ns Cm expressions-for-builtins
+Usually builtin-numbers are just immediate constants. With this flag
+expressions can be used, as long as they are compile-time constant.
+.Pp
+Example:
+.Bd -literal -offset indent
+void printA() = #1; // the usual way
+void printB() = #2-1; // with a constant expression
+.Ed
+.It Fl f Ns Cm return-assignments
+Enabiling this option will allow assigning values or expressions to the
+return keyword as if it were a local variable of the same type as the
+function's signature's return type.
+.Pp
+Example:
+.Bd -literal -offset indent
+float bar() { return 1024; }
+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.
 .El
 .Sh OPTIMIZATIONS
 .Bl -tag -width Ds
@@ -556,6 +606,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