.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
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.
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
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
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
optimization and finalization passes to stdout before generating the
binary. The instructions will be enumerated, and values will contain a
list of liferanges.
+.It Fl force-crc= Ns Ar CRC
+Force the produced progs file to use the specified CRC.
+.It Fl state-fps= Ns Ar NUM
+Activate \-femulate-state and set the emulated FPS to
+.Ar NUM Ns .
.El
.Sh COMPILE WARNINGS
.Bl -tag -width Ds
.Ql #pragma noref 1
and closed via
.Ql #pragma noref 0 Ns .
+.It Fl W Ns Cm unused-component
+Generate a warning about vector variables which are declared but not all their
+components are used.
.It Fl W Ns Cm used-uninitialized
Generate a warning if it is possible that a variable can be used
without prior initialization. Note that this warning is not
Warn when assigning to a function pointer with an unmatching
signature. This usually happens in cases like assigning the null
function to an entity's .think function pointer.
-.It Fl W Ns Cm preprocessor
-Enable warnings coming from the preprocessor. Like duplicate macro
-declarations. This warning triggers when there's a problem with the
-way the preprocessor has been used, it will \fBnot\fR affect warnings
-generated with the '#warning' directive. See -Wcpp.
.It Fl W Ns Cm cpp
Show warnings created using the preprocessor's '#warning' directive.
.It Fl W Ns Cm multifile-if
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.
+.It Fl W Ns Cm inexact-compares
+When comparing an inexact value such as `1.0/3.0' the result is
+pathologically wrong. Enabling this will trigger a compiler warning
+on such expressions.
.El
.Sh COMPILE FLAGS
.Bl -tag -width Ds
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__
__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 ftepp-mathdefs
+Enable math constant definitions. This only works in combination
+with \'\-fftepp' and is currently not included by '\-std=fteqcc'.
+The following macros will be added:
+.Bd -literal -offset indent
+M_E
+M_LOG2E
+M_LOG10E
+M_LN2
+M_LN10
+M_PI
+M_PI_2
+M_PI_4
+M_1_PI
+M_2_PI
+M_2_SQRTPI
+M_SQRT2
+M_SQRT1_2
+M_TAU
+.Ed
+.It Fl f Ns Cm ftepp-indirect-expansion
+Enable indirect macro expansion. This only works in combination
+with '-fftepp' and is currently not included by '-std=fteqcc'.
+Enabling this behavior will allow the preprocessor to operate more
+like the standard C preprocessor in that it will allow arguments
+of macros which are macro-expanded to be substituted into the
+definition of the macro.
+.Pp
+As an example:
+.Bd -literal -offset indent
+#define STR1(x) #x
+#define STR2(x) STR1(x)
+#define THE_ANSWER 42
+#define THE_ANSWER_STR STR2(THE_ANSWER) /* "42" */
+
+.Ed
+With this enabled, an expansion of THE_ANSWER_STR will yield
+the string "42". With this disabled an expansion of THE_ANSWER_STR
+will yield "THE_ANSWER"
.It Fl f Ns Cm relaxed-switch
Allow switch cases to use non constant variables.
.It Fl f Ns Cm short-logic
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.
+.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.
+.It Fl f Ns Cm emulate-state
+Emulate OP_STATE operations in code rather than using the instruction.
+The desired fps can be set via -state-fps=NUM, defaults to 10.
+Specifying \-state-fps implicitly sets this flag. Defaults to off in all
+standards.
+.It Fl f Ns Cm arithmetic-exceptions
+Turn on arithmetic exception tests in the compiler. In constant expressions
+which trigger exceptions like division by zero, overflow, underflow, etc,
+the following flag will produce diagnostics for what triggered that
+exception.
+.It Fl f Ns Cm split-vector-parameters
+With this flag immediate vector literals which only ever appear as function
+parameters won't be stored as vector immediates. Instead, the 3 floats making
+up the vector will be copied separately. Essentially this turns a vector-store
+instruction into 3 float-store instructions for such cases. This increases
+code size but can dramatically reduce the amount of vector globals, which is
+after all limited to 64k. There's at least one known codebase where this
+lowers the number of globals from over 80k down to around 3k. In other code
+bases it doesn't reduce the globals at all but only increases code size.
+Just try it and see whether it helps you.
.El
.Sh OPTIMIZATIONS
.Bl -tag -width Ds
.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
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
.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>,
projects / xonotic / gmqcc.git / blobdiff