.\" Process with groff -man -Tascii file.3
.TH GMQCC 1 2012-07-12 "" "gmqcc Manual"
.SH NAME
-gmqcc \- A Quake C compiler which tries to reduce suckiness.
+gmqcc \- A Quake C compiler built from the NIH realm of sarcastic wit
.SH SYNOPSIS
.B gmqcc
[\fIOPTIONS\fR] [\fIfiles...\fR]
\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"
Show a usage message and exit.
.TP
+.B "-debug"
+Turn on some compiler debugging mechanisms.
+.TP
+.B "-memchk"
+Turn on compiler mem-check. (Shows allocations and checks for leaks.)
+.TP
.BI "-o, --output=" filename
Specify the output filename. Defaults to progs.dat. This will overwrite
the output file listed in a \fIprogs.src\fR file in case such a file is used.
.TP
-.BI "-O" n
-Specify the optimization level, similar to gcc.
+.BI "-O" number
+Specify the optimization level
+.RS
+.IP 3
+Highest optimization level
+.IP 2
+Default optimization level
+.IP 1
+Minimal optimization level
+.IP 0
+Disable optimization entirely
+.RE
+.TP
+.BI "-O" name "\fR, " "" -Ono- name
+Enable or disable a specific optimization. Note that these options
+must be used after setting the optimization level, otherwise they'll
+be overwritten.
+.TP
+.B -Ohelp
+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.
+.TP
+.BR -Werror ", " -Wno-error
+Controls whether or not all warnings should be treated as errors.
+.TP
+.BI -Werror- warning "\fR, " "" -Wno-error- warning
+Controls whether a specific warning should be an error.
+.TP
+.B -Whelp
+List all possible warn flags.
.TP
-.BI "-a" filename
-Append the specified files to the list of files to assemble using the QC-Assembler.
+.BI -f flag "\fR, " "" -fno- flag
+Enable or disable a specific compile flag. See the list of flags
+below.
.TP
-.BI "-s" filename
-Append the specified file which is to be interpreted as a \fIprogs.src\fR file.
+.B -fhelp
+List all possible compile flags.
+.TP
+.B -nocolor
+Disables colored output
+.TP
+.BI -config= file
+Use an ini file to read all the -O, -W and -f flag from. See the
+CONFIG section about the file format.
+.TP
+.BI "-redirout=" file
+Redirects standard output to a \fIfile\fR
+.TP
+.BI "-redirerr=" file
+Redirects standard error to a \fIfile\fR
.TP
.BI "-std=" standard
-Use the specified standard for parsing QC code. The following standards are available:
+Use the specified standard for parsing QC code. The following standards
+are available:
.IR gmqcc , qcc , fteqcc
+Selecting a standard also implies some -f options and behaves as if
+those options have been written right after the -std option, meaning
+if you changed them before the -std option, you're now overwriting
+them.
+.sp
+.BR -std=gmqcc " includes:"
+.in +4
+-fadjust-vector-fields
+.in
+.BR -std=qcc " includes:"
+.in +4
+.nf
+-fassign-function-types
+-f\fIno-\fRadjust-vector-fields
+.fi
+.in
+.BR -std=fteqcc " includes:"
+.in +4
+.nf
+-fftepp
+-ftranslatable-strings
+-fassign-function-types
+-Wternary-precedence
+-f\fIno-\fRadjust-vector-fields
+-f\fIno-\fRcorrect-ternary
+.fi
+.in
+.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
+Generate a warning about variables which are declared but never used.
+This can be avoided by adding the \fInoref\fR keyword in front of the
+variable declaration. Additionally a complete section of unreferenced
+variables can be opened using \fI#pragma noref 1\fR, and closed via
+\fI#pragma noref 0\fR.
+.TP
+.B -Wused-uninitialized
+Generate a warning if it is possible that a variable can be used
+without prior initialization. Note that this warning is not
+necessarily reliable if the initialization happens only under certain
+conditions. The other way is \fInot\fR possible: that the warning is
+\fInot\fR generated when uninitialized use \fIis possible\fR.
+.TP
+.B -Wunknown-control-sequence
+Generate an error when an unrecognized control sequence in a string is
+used. Meaning: when there's a character after a backslash in a string
+which has no known meaning.
+.TP
+.B -Wextensions
+Warn when using special extensions which are not part of the selected
+standard.
+.TP
+.B -Wfield-redeclared
+Generally QC compilers ignore redeclaration of fields. Here you can
+optionally enable a warning.
+.TP
+.B -Wmissing-return-values
+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.
+.TP
+.B -Wlocal-shadows
+Warn when a locally declared variable shadows variable.
+.TP
+.B -Wlocal-constants
+Warn when the initialization of a local variable turns the variable
+into a constant. This is default behaviour unless
+\fI-finitialized-nonconstants\fR is used.
+.TP
+.B -Wvoid-variables
+There are only 2 known global variables of type void: end_sys_globals
+and end_sys_fields. Any other void-variable will warn.
+.TP
+.B -Wimplicit-function-pointer
+A global function which is not declared with the \fIvar\fR keyword is
+expected to have an implementing body, or be a builtin. If neither is
+the case, it implicitly becomes a function pointer, and a warning is
+generated.
+.TP
+.B -Wvariadic-function
+Currently there's no way for an in QC implemented function to access
+variadic parameters. If a function with variadic parameters has an
+implementing body, a warning will be generated.
+.TP
+.B -Wframe-macros
+Generate warnings about \fI$frame\fR commands, for instance about
+duplicate frame definitions.
+.TP
+.B -Weffectless-statement
+Warn about statements which have no effect. Any expression which does
+not call a function or assigns a variable.
+.TP
+.B -Wend-sys-fields
+The \fIend_sys_fields\fR variable is supposed to be a global variable
+of type \fIvoid\fR. It is also recognized as a \fIfield\fR but this
+will generate a warning.
+.TP
+.B -Wassign-function-types
+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.
+.TP
+.B -Wpreprocessor
+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.
+.TP
+.B -Wcpp
+Show warnings created using the preprocessor's '#warning' directive.
+.TP
+.B -Wmultifile-if
+Warn if there's a preprocessor \fI#if\fR spanning across several
+files.
+.TP
+.B -Wdouble-declaration
+Warn about multiple declarations of globals. This seems pretty common
+in QC code so you probably do not want this unless you want to clean
+up your code.
+.TP
+.B -Wconst-var
+The combination of \fIconst\fR and \fIvar\fR is not illegal, however
+different compilers may handle them differently. We were told, the
+intention is to create a function-pointer which is not assignable.
+This is exactly how we interpret it. However for this interpretation
+the \fIvar\fR keyword is considered superfluous (and philosophically
+wrong), so it is possible to generate a warning about this.
+.TP
+.B -Wmultibyte-character
+Warn about multibyte character constants, they do not work right now.
+.TP
+.B -Wternary-precedence
+Warn if a ternary expression which contains a comma operator is used
+without enclosing parenthesis, since this is most likely not what you
+actually want. We recommend the \fI-fcorrect-ternary\fR option.
+.TP
+.B -Wunknown-pragmas
+Warn when encountering an unrecognized \fI#pragma\fR line.
+.TP
+.B -Wunreachable-code
+Warn about unreachable code. That is: code after a return statement,
+or code after a call to a function marked as 'noreturn'.
+.TP
+.B -Wdebug
+Enable some warnings added in order to help debugging in the compiler.
+You won't need this.
+.B -Wunknown-attribute
+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.
+.SH COMPILE FLAGS
.TP
.B -fdarkplaces-string-table-bug
-Patch the output file to work around a string-table bug in certain darkplaces versions.
+Add some additional characters to the string table in order to
+compensate for a wrong boundcheck in some specific version of the
+darkplaces engine.
+.TP
+.B -fadjust-vector-fields
+When assigning to field pointers of type \fI.vector\fR the common
+behaviour in compilers like \fIfteqcc\fR is to only assign the
+x-component of the pointer. This means that you can use the vector as
+such, but you cannot use its y and z components directly. This flag
+fixes this behaviour. Before using it make sure your code does not
+depend on the buggy behaviour.
+.TP
+.B -fftepp
+Enable a partially fteqcc-compatible preprocessor. It supports all the
+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__
+.fi
+.in
+Note that fteqcc also defines __FUNC__, __TIME__, __DATE__ and
+__NULL__, which are not yet implemented.
+.TP
+.B -frelaxed-switch
+Allow switch cases to use non constant variables.
+.TP
+.B -fshort-logic
+Perform early out in logical AND and OR expressions. The final result
+will be either a 0 or a 1, see the next flag for more possibilities.
+.TP
+.B -fperl-logic
+In many languages, logical expressions perform early out in a special
+way: If the left operand of an AND yeilds true, or the one of an OR
+yields false, the complete expression evaluates to the right side.
+Thus \fItrue && 5\fI evaluates to 5 rather than 1.
+.TP
+.B -ftranslatable-strings
+Enable the underscore intrinsic: Using \fI_("A string constant")\fR
+will cause the string immediate to get a name with a "dotranslate_"
+prefix. The darkplaces engine recognizes these and translates them in
+a way similar to how gettext works.
+.TP
+.B -finitialized-nonconstants
+Don't implicitly convert initialized variables to constants. With this
+flag, the \fIconst\fR keyword is required to make a constant.
+.TP
+.B -fassign-function-types
+If this flag is not set, (and it is set by default in the qcc and
+fteqcc standards), assigning function pointers of mismatching
+signatures will result in an error rather than a warning.
+.TP
+.B -flno
+Produce a linenumber file along with the output .dat file.
+.TP
+.B -fcorrect-ternary
+Use C's operator precedence for ternary expressions. Unless your code
+depends on fteqcc-compatible behaviour, you'll want to use thi
+soption.
+.TP
+.B -fsingle-vector-defs
+Normally vectors generate 4 defs, once for the vector, and once for
+its components with _x, _y, _z suffixes. This option
+prevents components from being listed.
+.TP
+.B -fcorrect-logic
+Most QC compilers translate if(a_vector) directly as an IF on the
+vector, which means only the x-component is checked. This causes
+vectors to be cast to actual booleans via a NOT_V and, if necessary, a
+NOT_F chained to it.
+.in +4
+.nf
+if (a_vector) // becomes
+if not(!a_vector)
+// likewise
+a = a_vector && a_float // becomes
+a = !!a_vector && a_float
+.fi
+.in
+.TP
+.B -ftrue-empty-strings
+An empty string is considered to be true everywhere. The NOT_S
+instruction usually considers an empty string to be false, this option
+effectively causes the unary not in strings to use NOT_F instead.
+.TP
+.B -ffalse-empty-strings
+An empty string is considered to be false everywhere. This means loops
+and if statements which depend on a string will perform a NOT_S
+instruction on the string before using it.
+.TP
+.B -futf8
+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.
+.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.)
+.SH OPTIMIZATIONS
+.TP
+.B -Opeephole
+Some general peephole optimizations. For instance the code `a = b + c`
+typically generates 2 instructions, an ADD and a STORE. This
+optimization removes the STORE and lets the ADD write directly into A.
+.TP
+.B -Otail-recursion
+Tail recursive function calls will be turned into loops to avoid the
+overhead of the CALL and RETURN instructions.
+.TP
+.B -Ooverlap-locals
+Make all functions which use neither local arrays nor have locals
+which are seen as possibly uninitialized use the same local section.
+This should be pretty safe compared to other compilers which do not
+check for uninitialized values properly. The problem is that there's
+QC code out there which really doesn't initialize some values. This is
+fine as long as this kind of optimization isn't used, but also, only
+as long as the functions cannot be called in a recursive manner. Since
+it's hard to know whether or not an array is actually fully
+initialized, especially when initializing it via a loop, we assume
+functions with arrays to be too dangerous for this optimization.
+.TP
+.B -Olocal-temps
+This promotes locally declared variables to "temps". Meaning when a
+temporary result of an operation has to be stored somewhere, a local
+variable which is not 'alive' at that point can be used to keep the
+result. This can reduce the size of the global section.
+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 -fomit-nullbytes
-Changes the output format to be more efficient. Requires a patched engine. See the
-proposal for a better file structure in the gmqcc source tree.
+.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.
+.SH CONFIG
+The configuration file is similar to regular .ini files. Comments
+start with hashtags or semicolons, sections are written in square
+brackets and in each section there can be arbitrary many key-value
+pairs.
+.sp
+There are 3 sections currently:
+.IR flags ", " warnings ", and " optimizations .
+They contain a list of boolean values of the form `VARNAME = true` or
+`VARNAME = false`. The variable names are the same as for the
+corresponding -W, -f or -O flag written with only capital letters and
+dashes replaced by underscores.
+.sp
+Here's an example:
+.in +4
+.nf
+# a GMQCC configuration file
+[flags]
+ FTEPP = true
+ ADJUST_VECTOR_FIELDS = false
+ LNO = true
+
+[warnings]
+ UNUSED_VARIABLE = false
+ USED_UNINITIALIZED = true
+
+[optimizations]
+ PEEPHOLE = true
+ TAIL_RECURSION = true
+.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
+.TP 20
+.B gmqcc.ini.example
+A documented example for a gmqcc.ini file.
+.SH SEE ALSO
+.IR qcvm (1)
+.SH AUTHOR
+See <http://graphitemaster.github.com/gmqcc>.
projects / xonotic / gmqcc.git / blobdiff