\fBgmqcc\fR optionally takes options to specify the output and
input files on the commandline, and also accepts assembly files.
.SH OPTIONS
-\fBgmqcc\fR mostly tries to mimick gcc's commandline handling, though
+\fBgmqcc\fR mostly tries to mimic gcc's commandline handling, though
there are also traditional long-options available.
.TP
.B "-h, --help"
List all possible optimizations and the optimization level they're
activated at.
.TP
+.BR -q ", " --quiet
+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.
+.TP
.BI -W warning "\fR, " "" -Wno- warning
Enable or disable a warning.
.TP
.B -Wall
-Enable all warnings. Overrides preceding -W parameters.
+Enable almost all warnings. Overrides preceding -W parameters.
+.sp
+The following warnings will \fBnot\fR be anbled:
+.in +4
+.nf
+-Wuninitialized-global
+.fi
+.in
.TP
.BR -Werror ", " -Wno-error
Controls whether or not all warnings should be treated as errors.
.sp
.BR -std=gmqcc " includes:"
.in +4
+.nf
-fadjust-vector-fields
+-fcorrect-logic
+-ftrue-empty-strings
+-floop-labels
+-finitialized-nonconstants
+-ftranslatable-strings
+-f\fIno-\fRfalse-empty-strings
+-Winvalid-parameter-count
+-Wmissing-returnvalues
+-fcorrect-ternary (cannot be turned off)
+.fi
.in
+.sp
.BR -std=qcc " includes:"
.in +4
.nf
-f\fIno-\fRadjust-vector-fields
.fi
.in
+.sp
.BR -std=fteqcc " includes:"
.in +4
.nf
-f\fIno-\fRcorrect-ternary
.fi
.in
+.TP
+.B "--add-info"
+Adds compiler information to the generated binary file. Currently
+this includes the following globals:
+.RS
+.IP "reserved:version"
+String containing the compiler version as printed by the --version
+parameter.
+.RE
+.TP
+.B "-dump"
+DEBUG OPTION. Print the code's intermediate representation before the
+optimization and finalization passes to stdout before generating the
+binary.
+.TP
+.B "-dumpfin"
+DEBUG OPTION. Print the code's intermediate representation after the
+optimization and finalization passes to stdout before generating the
+binary. The instructions will be enumerated, and values will contain a
+list of liferanges.
.SH COMPILE WARNINGS
.TP
.B -Wunused-variable
Functions which aren't of type \fIvoid\fR will warn if it possible to
reach the end without returning an actual value.
.TP
-.B -Wtoo-few-parameters
-Warn about a function call with fewer parameters than the function
-expects.
+.B -Winvalid-parameter-count
+Warn about a function call with an invalid number of parameters.
.TP
.B -Wlocal-shadows
Warn when a locally declared variable shadows variable.
Warn on an unknown attribute. The warning will inlclude only the first
token inside the enclosing attribute-brackets. This may change when
the actual attribute syntax is better defined.
+.TP
+.B -Wreserved-names
+Warn when using reserved names such as 'nil'.
+.TP
+.B -Wuninitialized-constant
+Warn about global constants (using the 'const' keyword) with no
+assigned value.
+.TP
+.B -Wuninitialized-global
+Warn about global variables with no initializing value. This is off by
+default, and is added mostly to help find null-values which are
+supposed to be replaced by the untyped 'nil' constant.
+.TP
+.B -Wdifferent-qualifiers
+Warn when a variables is redeclared with a different qualifier. For
+example when redeclaring a variable as \'var\' which was previously
+marked \'const\'.
+.TP
+.B -Wdifferent-attributes
+Similar to the above but for attributes like "[[noreturn]]".
+.TP
+.B -Wdeprecated
+Warn when a function is marked with the attribute
+"[[deprecated]]". This flag enables a warning on calls to functions
+marked as such.
+.TP
+.B -Wparenthesis
+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.
.SH COMPILE FLAGS
.TP
.B -fdarkplaces-string-table-bug
features used in the Xonotic codebase. If you need more, write a
ticket.
.TP
+.B -fftepp-predefs
+Enable some predefined macros. This only works in combination with
+\'-fftepp' and is currently not included by '-std=fteqcc'. The
+following macros will be added:
+.in +4
+.nf
+__LINE__
+__FILE__
+__COUNTER__
+__COUNTER_LAST__
+__RANDOM__
+__RANDOM_LAST__
+__DATE__
+__TIME__
+.fi
+.in
+Note that fteqcc also defines __NULL__ which is not implemented yet.
+(See -funtyped-nil about gmqcc's alternative to __NULL__).
+.TP
.B -frelaxed-switch
Allow switch cases to use non constant variables.
.TP
Enable utf8 characters. This allows utf-8 encoded character constants,
and escape sequence codepoints in the valid utf-8 range. Effectively
enabling escape sequences like '\\{x2211}'.
+.TP
+.B -fbail-on-werror
+When a warning is treated as an error, and this option is set (which
+it is by default), it is like any other error and will cause
+compilation to stop. When disabling this flag by using
+\-fno-bail-on-werror, compilation will continue until the end, but no
+output is generated. Instead the first such error message's context is
+shown.
+.TP
+.B -floop-labels
+Allow loops to be labeled, and allow 'break' and 'continue' to take an
+optional label to decide which loop to actually jump out of or
+continue.
+.sp
+.in +4
+.nf
+for :outer (i = 0; i < n; ++i) {
+ while (inner) {
+ ...;
+ if (something)
+ continue outer;
+ }
+}
+.fi
+.in
+.TP
+.B -funtyped-nil
+Adds a global named 'nil' which is of no type and can be assigned to
+anything. No typechecking will be performed on assignments. Assigning
+to it is forbidden, using it in any other kind of expression is also
+not allowed.
+.sp
+Note that this is different from fteqcc's __NULL__: In fteqcc,
+__NULL__ maps to the integer written as '0i'. It's can be assigned to
+function pointers and integers, but it'll error about invalid
+instructions when assigning it to floats without enabling the FTE
+instruction set. There's also a bug which allows it to be assigned to
+vectors, for which the source will be the global at offset 0, meaning
+the vector's y and z components will contain the OFS_RETURN x and y
+components.
+.sp
+In that gmqcc the nil global is an actual global filled with zeroes,
+and can be assigned to anything including fields, vectors or function
+pointers, and they end up becoming zeroed.
+.TP
+.B -fpermissive
+Various effects, usually to weaken some conditions.
+.RS
+.IP "with -funtyped-nil"
+Allow local variables named 'nil'. (This will not allow declaring a
+global of that name.)
+.RE
.SH OPTIMIZATIONS
.TP
.B -Opeephole
This will not have declared variables overlap, even if it was
possible.
.TP
+.B -Oglobal-temps
+Causes temporary values which do not need to be backed up on a CALL to
+not be stored in the function's locals-area. With this, a CALL to a
+function may need to back up fewer values and thus execute faster.
+.TP
.B -Ostrip-constant-names
Don't generate defs for immediate values or even declared constants.
Meaning variables which are implicitly constant or qualified as such
using the 'const' keyword.
+.TP
+.B -Ooverlap-strings
+Aggressively reuse strings in the string section. When a string should
+be added which is the trailing substring of an already existing
+string, the existing string's tail will be returned instead of the new
+string being added.
+
+For example the following code will only generate 1 string:
+
+.in +4
+.nf
+print("Hell you!\\n");
+print("you!\\n"); // trailing substring of "Hello you!\\n"
+.fi
+.in
+There's however one limitation. Strings are still processed in order,
+so if the above print statements were reversed, this optimization
+would not happen.
+.TP
+.B -Ocall-stores
+By default, all parameters of a CALL are copied into the
+parameter-globals right before the CALL instructions. This is the
+easiest and safest way to translate calls, but also adds a lot of
+unnecessary copying and unnecessary temporary values. This
+optimization makes operations which are used as a parameter evaluate
+directly into the parameter-global if that is possible, which is when
+there's no other CALL instruction in between.
+.TP
+.B -Ovoid-return
+Usually an empty RETURN instruction is added to the end of a void
+typed function. However, additionally after every function a DONE
+instruction is added for several reasons. (For example the qcvm's
+disassemble switch uses it to know when the function ends.). This
+optimization replaces that last RETURN with DONE rather than adding
+the DONE additionally.
+.TP
+.B -Ovector-components
+Because traditional QC code doesn't allow you to access individual
+vector components of a computed vector without storing it in a local
+first, sometimes people multiply it by a constant like '0 1 0' to get,
+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.
.SH CONFIG
The configuration file is similar to regular .ini files. Comments
start with hashtags or semicolons, sections are written in square
.fi
.in
.SH BUGS
+Currently the '-fftepp-predefs' flag is not included by '-std=fteqcc',
+partially because it is not entirely conformant to fteqcc.
+.sp
+
Please report bugs on <http://github.com/graphitemaster/gmqcc/issues>,
or see <http://graphitemaster.github.com/gmqcc> on how to contact us.
.SH FILES
projects / xonotic / gmqcc.git / blobdiff