1 .\" Process with groff -man -Tascii file.3
2 .TH GMQCC 1 2012-07-12 "" "gmqcc Manual"
4 gmqcc \- A Quake C compiler built from the NIH realm of sarcastic wit
7 [\fIOPTIONS\fR] [\fIfiles...\fR]
9 Traditionally, a QC compiler reads the file \fIprogs.src\fR which
10 in its first line contains the output filename, and the rest is a
11 list of QC source files that are to be compiled in order.
12 \fBgmqcc\fR optionally takes options to specify the output and
13 input files on the commandline, and also accepts assembly files.
15 \fBgmqcc\fR mostly tries to mimic gcc's commandline handling, though
16 there are also traditional long-options available.
19 Show a usage message and exit.
22 Turn on some compiler debugging mechanisms.
25 Turn on compiler mem-check. (Shows allocations and checks for leaks.)
27 .BI "-o, --output=" filename
28 Specify the output filename. Defaults to progs.dat. This will overwrite
29 the output file listed in a \fIprogs.src\fR file in case such a file is used.
32 Specify the optimization level
35 Highest optimization level
37 Default optimization level
39 Minimal optimization level
41 Disable optimization entirely
44 .BI "-O" name "\fR, " "" -Ono- name
45 Enable or disable a specific optimization. Note that these options
46 must be used after setting the optimization level, otherwise they'll
50 List all possible optimizations and the optimization level they're
54 Be less verbose. In particular removes the messages about which files
55 are being processed, and which compilation mode is being used, and
56 some others. Warnings and errors will of course still be displayed.
58 .BI -W warning "\fR, " "" -Wno- warning
59 Enable or disable a warning.
62 Enable almost all warnings. Overrides preceding -W parameters.
64 The following warnings will \fBnot\fR be anbled:
67 -Wuninitialized-global
71 .BR -Werror ", " -Wno-error
72 Controls whether or not all warnings should be treated as errors.
74 .BI -Werror- warning "\fR, " "" -Wno-error- warning
75 Controls whether a specific warning should be an error.
78 List all possible warn flags.
80 .BI -f flag "\fR, " "" -fno- flag
81 Enable or disable a specific compile flag. See the list of flags
85 List all possible compile flags.
88 Disables colored output
91 Use an ini file to read all the -O, -W and -f flag from. See the
92 CONFIG section about the file format.
95 Redirects standard output to a \fIfile\fR
98 Redirects standard error to a \fIfile\fR
101 Use the specified standard for parsing QC code. The following standards
103 .IR gmqcc , qcc , fteqcc
104 Selecting a standard also implies some -f options and behaves as if
105 those options have been written right after the -std option, meaning
106 if you changed them before the -std option, you're now overwriting
109 .BR -std=gmqcc " includes:"
112 -fadjust-vector-fields
116 -finitialized-nonconstants
117 -ftranslatable-strings
118 -f\fIno-\fRfalse-empty-strings
119 -Winvalid-parameter-count
120 -Wmissing-returnvalues
121 -fcorrect-ternary (cannot be turned off)
125 .BR -std=qcc " includes:"
128 -fassign-function-types
129 -f\fIno-\fRadjust-vector-fields
133 .BR -std=fteqcc " includes:"
137 -ftranslatable-strings
138 -fassign-function-types
140 -f\fIno-\fRadjust-vector-fields
141 -f\fIno-\fRcorrect-ternary
146 Adds compiler information to the generated binary file. Currently
147 this includes the following globals:
149 .IP "reserved:version"
150 String containing the compiler version as printed by the --version
155 DEBUG OPTION. Print the code's intermediate representation before the
156 optimization and finalization passes to stdout before generating the
160 DEBUG OPTION. Print the code's intermediate representation after the
161 optimization and finalization passes to stdout before generating the
162 binary. The instructions will be enumerated, and values will contain a
167 Generate a warning about variables which are declared but never used.
168 This can be avoided by adding the \fInoref\fR keyword in front of the
169 variable declaration. Additionally a complete section of unreferenced
170 variables can be opened using \fI#pragma noref 1\fR, and closed via
171 \fI#pragma noref 0\fR.
173 .B -Wused-uninitialized
174 Generate a warning if it is possible that a variable can be used
175 without prior initialization. Note that this warning is not
176 necessarily reliable if the initialization happens only under certain
177 conditions. The other way is \fInot\fR possible: that the warning is
178 \fInot\fR generated when uninitialized use \fIis possible\fR.
180 .B -Wunknown-control-sequence
181 Generate an error when an unrecognized control sequence in a string is
182 used. Meaning: when there's a character after a backslash in a string
183 which has no known meaning.
186 Warn when using special extensions which are not part of the selected
189 .B -Wfield-redeclared
190 Generally QC compilers ignore redeclaration of fields. Here you can
191 optionally enable a warning.
193 .B -Wmissing-return-values
194 Functions which aren't of type \fIvoid\fR will warn if it possible to
195 reach the end without returning an actual value.
197 .B -Winvalid-parameter-count
198 Warn about a function call with an invalid number of parameters.
201 Warn when a locally declared variable shadows variable.
204 Warn when the initialization of a local variable turns the variable
205 into a constant. This is default behaviour unless
206 \fI-finitialized-nonconstants\fR is used.
209 There are only 2 known global variables of type void: end_sys_globals
210 and end_sys_fields. Any other void-variable will warn.
212 .B -Wimplicit-function-pointer
213 A global function which is not declared with the \fIvar\fR keyword is
214 expected to have an implementing body, or be a builtin. If neither is
215 the case, it implicitly becomes a function pointer, and a warning is
218 .B -Wvariadic-function
219 Currently there's no way for an in QC implemented function to access
220 variadic parameters. If a function with variadic parameters has an
221 implementing body, a warning will be generated.
224 Generate warnings about \fI$frame\fR commands, for instance about
225 duplicate frame definitions.
227 .B -Weffectless-statement
228 Warn about statements which have no effect. Any expression which does
229 not call a function or assigns a variable.
232 The \fIend_sys_fields\fR variable is supposed to be a global variable
233 of type \fIvoid\fR. It is also recognized as a \fIfield\fR but this
234 will generate a warning.
236 .B -Wassign-function-types
237 Warn when assigning to a function pointer with an unmatching
238 signature. This usually happens in cases like assigning the null
239 function to an entity's .think function pointer.
242 Enable warnings coming from the preprocessor. Like duplicate macro
243 declarations. This warning triggers when there's a problem with the
244 way the preprocessor has been used, it will \fBnot\fR affect warnings
245 generated with the '#warning' directive. See -Wcpp.
248 Show warnings created using the preprocessor's '#warning' directive.
251 Warn if there's a preprocessor \fI#if\fR spanning across several
254 .B -Wdouble-declaration
255 Warn about multiple declarations of globals. This seems pretty common
256 in QC code so you probably do not want this unless you want to clean
260 The combination of \fIconst\fR and \fIvar\fR is not illegal, however
261 different compilers may handle them differently. We were told, the
262 intention is to create a function-pointer which is not assignable.
263 This is exactly how we interpret it. However for this interpretation
264 the \fIvar\fR keyword is considered superfluous (and philosophically
265 wrong), so it is possible to generate a warning about this.
267 .B -Wmultibyte-character
268 Warn about multibyte character constants, they do not work right now.
270 .B -Wternary-precedence
271 Warn if a ternary expression which contains a comma operator is used
272 without enclosing parenthesis, since this is most likely not what you
273 actually want. We recommend the \fI-fcorrect-ternary\fR option.
276 Warn when encountering an unrecognized \fI#pragma\fR line.
278 .B -Wunreachable-code
279 Warn about unreachable code. That is: code after a return statement,
280 or code after a call to a function marked as 'noreturn'.
283 Enable some warnings added in order to help debugging in the compiler.
285 .B -Wunknown-attribute
286 Warn on an unknown attribute. The warning will inlclude only the first
287 token inside the enclosing attribute-brackets. This may change when
288 the actual attribute syntax is better defined.
291 Warn when using reserved names such as 'nil'.
293 .B -Wuninitialized-constant
294 Warn about global constants (using the 'const' keyword) with no
297 .B -Wuninitialized-global
298 Warn about global variables with no initializing value. This is off by
299 default, and is added mostly to help find null-values which are
300 supposed to be replaced by the untyped 'nil' constant.
302 .B -Wdifferent-qualifiers
303 Warn when a variables is redeclared with a different qualifier. For
304 example when redeclaring a variable as \'var\' which was previously
307 .B -Wdifferent-attributes
308 Similar to the above but for attributes like "[[noreturn]]".
311 Warn when a function is marked with the attribute
312 "[[deprecated]]". This flag enables a warning on calls to functions
316 Warn about possible mistakes caused by missing or wrong parenthesis,
317 like an assignment in an 'if' condition when there's no additional set
318 of parens around the assignment.
321 .B -fdarkplaces-string-table-bug
322 Add some additional characters to the string table in order to
323 compensate for a wrong boundcheck in some specific version of the
326 .B -fadjust-vector-fields
327 When assigning to field pointers of type \fI.vector\fR the common
328 behaviour in compilers like \fIfteqcc\fR is to only assign the
329 x-component of the pointer. This means that you can use the vector as
330 such, but you cannot use its y and z components directly. This flag
331 fixes this behaviour. Before using it make sure your code does not
332 depend on the buggy behaviour.
335 Enable a partially fteqcc-compatible preprocessor. It supports all the
336 features used in the Xonotic codebase. If you need more, write a
340 Enable some predefined macros. This only works in combination with
341 \'-fftepp' and is currently not included by '-std=fteqcc'. The
342 following macros will be added:
355 Note that fteqcc also defines __NULL__ which is not implemented yet.
356 (See -funtyped-nil about gmqcc's alternative to __NULL__).
359 Allow switch cases to use non constant variables.
362 Perform early out in logical AND and OR expressions. The final result
363 will be either a 0 or a 1, see the next flag for more possibilities.
366 In many languages, logical expressions perform early out in a special
367 way: If the left operand of an AND yeilds true, or the one of an OR
368 yields false, the complete expression evaluates to the right side.
369 Thus \fItrue && 5\fI evaluates to 5 rather than 1.
371 .B -ftranslatable-strings
372 Enable the underscore intrinsic: Using \fI_("A string constant")\fR
373 will cause the string immediate to get a name with a "dotranslate_"
374 prefix. The darkplaces engine recognizes these and translates them in
375 a way similar to how gettext works.
377 .B -finitialized-nonconstants
378 Don't implicitly convert initialized variables to constants. With this
379 flag, the \fIconst\fR keyword is required to make a constant.
381 .B -fassign-function-types
382 If this flag is not set, (and it is set by default in the qcc and
383 fteqcc standards), assigning function pointers of mismatching
384 signatures will result in an error rather than a warning.
387 Produce a linenumber file along with the output .dat file.
390 Use C's operator precedence for ternary expressions. Unless your code
391 depends on fteqcc-compatible behaviour, you'll want to use thi
394 .B -fsingle-vector-defs
395 Normally vectors generate 4 defs, once for the vector, and once for
396 its components with _x, _y, _z suffixes. This option
397 prevents components from being listed.
400 Most QC compilers translate if(a_vector) directly as an IF on the
401 vector, which means only the x-component is checked. This causes
402 vectors to be cast to actual booleans via a NOT_V and, if necessary, a
406 if (a_vector) // becomes
409 a = a_vector && a_float // becomes
410 a = !!a_vector && a_float
414 .B -ftrue-empty-strings
415 An empty string is considered to be true everywhere. The NOT_S
416 instruction usually considers an empty string to be false, this option
417 effectively causes the unary not in strings to use NOT_F instead.
419 .B -ffalse-empty-strings
420 An empty string is considered to be false everywhere. This means loops
421 and if statements which depend on a string will perform a NOT_S
422 instruction on the string before using it.
425 Enable utf8 characters. This allows utf-8 encoded character constants,
426 and escape sequence codepoints in the valid utf-8 range. Effectively
427 enabling escape sequences like '\\{x2211}'.
430 When a warning is treated as an error, and this option is set (which
431 it is by default), it is like any other error and will cause
432 compilation to stop. When disabling this flag by using
433 \-fno-bail-on-werror, compilation will continue until the end, but no
434 output is generated. Instead the first such error message's context is
438 Allow loops to be labeled, and allow 'break' and 'continue' to take an
439 optional label to decide which loop to actually jump out of or
444 for :outer (i = 0; i < n; ++i) {
455 Adds a global named 'nil' which is of no type and can be assigned to
456 anything. No typechecking will be performed on assignments. Assigning
457 to it is forbidden, using it in any other kind of expression is also
460 Note that this is different from fteqcc's __NULL__: In fteqcc,
461 __NULL__ maps to the integer written as '0i'. It's can be assigned to
462 function pointers and integers, but it'll error about invalid
463 instructions when assigning it to floats without enabling the FTE
464 instruction set. There's also a bug which allows it to be assigned to
465 vectors, for which the source will be the global at offset 0, meaning
466 the vector's y and z components will contain the OFS_RETURN x and y
469 In that gmqcc the nil global is an actual global filled with zeroes,
470 and can be assigned to anything including fields, vectors or function
471 pointers, and they end up becoming zeroed.
474 Various effects, usually to weaken some conditions.
476 .IP "with -funtyped-nil"
477 Allow local variables named 'nil'. (This will not allow declaring a
478 global of that name.)
483 Some general peephole optimizations. For instance the code `a = b + c`
484 typically generates 2 instructions, an ADD and a STORE. This
485 optimization removes the STORE and lets the ADD write directly into A.
488 Tail recursive function calls will be turned into loops to avoid the
489 overhead of the CALL and RETURN instructions.
492 Make all functions which use neither local arrays nor have locals
493 which are seen as possibly uninitialized use the same local section.
494 This should be pretty safe compared to other compilers which do not
495 check for uninitialized values properly. The problem is that there's
496 QC code out there which really doesn't initialize some values. This is
497 fine as long as this kind of optimization isn't used, but also, only
498 as long as the functions cannot be called in a recursive manner. Since
499 it's hard to know whether or not an array is actually fully
500 initialized, especially when initializing it via a loop, we assume
501 functions with arrays to be too dangerous for this optimization.
504 This promotes locally declared variables to "temps". Meaning when a
505 temporary result of an operation has to be stored somewhere, a local
506 variable which is not 'alive' at that point can be used to keep the
507 result. This can reduce the size of the global section.
508 This will not have declared variables overlap, even if it was
512 Causes temporary values which do not need to be backed up on a CALL to
513 not be stored in the function's locals-area. With this, a CALL to a
514 function may need to back up fewer values and thus execute faster.
516 .B -Ostrip-constant-names
517 Don't generate defs for immediate values or even declared constants.
518 Meaning variables which are implicitly constant or qualified as such
519 using the 'const' keyword.
522 Aggressively reuse strings in the string section. When a string should
523 be added which is the trailing substring of an already existing
524 string, the existing string's tail will be returned instead of the new
527 For example the following code will only generate 1 string:
531 print("Hell you!\\n");
532 print("you!\\n"); // trailing substring of "Hello you!\\n"
535 There's however one limitation. Strings are still processed in order,
536 so if the above print statements were reversed, this optimization
540 By default, all parameters of a CALL are copied into the
541 parameter-globals right before the CALL instructions. This is the
542 easiest and safest way to translate calls, but also adds a lot of
543 unnecessary copying and unnecessary temporary values. This
544 optimization makes operations which are used as a parameter evaluate
545 directly into the parameter-global if that is possible, which is when
546 there's no other CALL instruction in between.
549 Usually an empty RETURN instruction is added to the end of a void
550 typed function. However, additionally after every function a DONE
551 instruction is added for several reasons. (For example the qcvm's
552 disassemble switch uses it to know when the function ends.). This
553 optimization replaces that last RETURN with DONE rather than adding
554 the DONE additionally.
556 .B -Ovector-components
557 Because traditional QC code doesn't allow you to access individual
558 vector components of a computed vector without storing it in a local
559 first, sometimes people multiply it by a constant like '0 1 0' to get,
560 in this case, the y component of a vector. This optimization will turn
561 such a multiplication into a direct component access. If the factor is
562 anything other than 1, a float-multiplication will be added, which is
563 still faster than a vector multiplication.
565 The configuration file is similar to regular .ini files. Comments
566 start with hashtags or semicolons, sections are written in square
567 brackets and in each section there can be arbitrary many key-value
570 There are 3 sections currently:
571 .IR flags ", " warnings ", and " optimizations .
572 They contain a list of boolean values of the form `VARNAME = true` or
573 `VARNAME = false`. The variable names are the same as for the
574 corresponding -W, -f or -O flag written with only capital letters and
575 dashes replaced by underscores.
580 # a GMQCC configuration file
583 ADJUST_VECTOR_FIELDS = false
587 UNUSED_VARIABLE = false
588 USED_UNINITIALIZED = true
592 TAIL_RECURSION = true
596 Currently the '-fftepp-predefs' flag is not included by '-std=fteqcc',
597 partially because it is not entirely conformant to fteqcc.
600 Please report bugs on <http://github.com/graphitemaster/gmqcc/issues>,
601 or see <http://graphitemaster.github.com/gmqcc> on how to contact us.
605 A documented example for a gmqcc.ini file.
609 See <http://graphitemaster.github.com/gmqcc>.
projects / xonotic / gmqcc.git / blob