1GMQCC(1) Programmer's Manual GMQCC(1)
2
4 gmqcc — A Quake C compiler built from the NIH realm of sarcastic wit
5
7 gmqcc [options] [files...]
8
10 Traditionally, a QC compiler reads the file progs.src which in its first
11 line contains the output filename, and the rest is a list of QC source
12 files that are to be compiled in order. gmqcc optionally takes options
13 to specify the output and input files on the commandline, and also
14 accepts assembly files.
15
17 gmqcc mostly tries to mimic gcc's commandline handling, though there are
18 also traditional long-options available.
19 -h, --help
21 Show a usage message and exit.
22 -o, --output=filename
24 Specify the output filename. Defaults to progs.dat. This will
25 overwrite the output file listed in a progs.src file in case such
26 a file is used.
27 -Onumber
29 Specify the optimization level
30 3 Highest optimization level
32 2 Default optimization level
34 1 Minimal optimization level
36 0 Disable optimization entirely
38 -Oname, -Ono-name
40 Enable or disable a specific optimization. Note that these
41 options must be used after setting the optimization level, other‐
42 wise they'll be overwritten.
43 -Ohelp List all possible optimizations and the optimization level
45 they're activated at.
46 -q, --quiet
48 Be less verbose. In particular removes the messages about which
49 files are being processed, and which compilation mode is being
50 used, and some others. Warnings and errors will of course still
51 be displayed.
52 -Dmacroname, -Dmacroname=value
54 Predefine a macro, optionally with a optional value.
55 -E Run only the preprocessor as if -fftepp was used and print the
57 preprocessed code to stdout.
58 -Wwarning, -Wno-warning
60 Enable or disable a warning.
61 -Wall Enable almost all warnings. Overrides preceding -W parameters.
63 The following warnings will not be enabled:
65 -Wuninitialized-global
67 -Werror, -Wno-error
69 Controls whether or not all warnings should be treated as errors.
70 -Werror-warning, -Wno-error-warning
72 Controls whether a specific warning should be an error.
73 -Whelp List all possible warn flags.
75 -fflag, -fno-flag
77 Enable or disable a specific compile flag. See the list of flags
78 below.
79 -fhelp List all possible compile flags.
81 -nocolor
83 Disables colored output
84 -config=file
86 Use an ini file to read all the -O, -W and -f flag from. See the
87 -debug Turn on some compiler debugging mechanisms.
89 -memchk
91 Turn on compiler mem-check. (Shows allocations and checks for
92 leaks.)
93 --memdumpcolscolumns
95 Changes the number of columns to use for the debug memory dump,
96 defaults to 16. CONFIG section about the file format.
97 -redirout=file
99 Redirects standard output to a file
100 -redirerr=file
102 Redirects standard error to a file
103 -std=standard
105 Use the specified standard for parsing QC code. The following
106 standards are available: gmqcc, qcc, fteqcc Selecting a standard
107 also implies some -f options and behaves as if those options have
108 been written right after the -std option, meaning if you changed
109 them before the --std option, you're now overwriting them.
110 -std=gmqcc includes:
112 -fadjust-vector-fields
113 -fcorrect-logic
114 -ftrue-empty-strings
115 -floop-labels
116 -finitialized-nonconstants
117 -ftranslatable-strings
118 -fno-false-empty-strings
119 -Winvalid-parameter-count
120 -Wmissing-returnvalues
121 -fcorrect-ternary (cannot be turned off)
122 -std=qcc includes:
124 -fassign-function-types
125 -fIno-adjust-vector-fields
126 -std=fteqcc includes:
128 -fftepp
129 -ftranslatable-strings
130 -fassign-function-types
131 -Wternary-precedence
132 -fno-adjust-vector-fields
133 -fno-correct-ternary
134 --add-info
136 Adds compiler information to the generated binary file. Currently
137 this includes the following globals:
138 reserved:version
139 String containing the compiler version as printed by the
140 --version parameter.
141 --correct, --no-correct
143 When enabled, errors about undefined values try to suggest an
144 existing value via spell checking.
145 -dump DEBUG OPTION. Print the code's intermediate representation before
147 the optimization and finalization passes to stdout before gener‐
148 ating the binary.
149 -dumpfin
151 DEBUG OPTION. Print the code's intermediate representation after
152 the optimization and finalization passes to stdout before gener‐
153 ating the binary. The instructions will be enumerated, and values
154 will contain a list of liferanges.
155
157 -Wunused-variable
158 Generate a warning about variables which are declared but never
159 used. This can be avoided by adding the ‘noref’ keyword in front
160 of the variable declaration. Additionally a complete section of
161 unreferenced variables can be opened using ‘#pragma noref 1’ and
162 closed via ‘#pragma noref 0’.
163 -Wused-uninitialized
165 Generate a warning if it is possible that a variable can be used
166 without prior initialization. Note that this warning is not nec‐
167 essarily reliable if the initialization happens only under cer‐
168 tain conditions. The other way is not possible: that the warning
169 is not generated when uninitialized use is possible.
170 -Wunknown-control-sequence
172 Generate an error when an unrecognized control sequence in a
173 string is used. Meaning: when there's a character after a back‐
174 slash in a string which has no known meaning.
175 -Wextensions
177 Warn when using special extensions which are not part of the
178 selected standard.
179 -Wfield-redeclared
181 Generally QC compilers ignore redeclaration of fields. Here you
182 can optionally enable a warning.
183 -Wmissing-return-values
185 Functions which aren't of type void will warn if it possible to
186 reach the end without returning an actual value.
187 -Winvalid-parameter-count
189 Warn about a function call with an invalid number of parameters.
190 -Wlocal-shadows
192 Warn when a locally declared variable shadows variable.
193 -Wlocal-constants
195 Warn when the initialization of a local variable turns the vari‐
196 able into a constant. This is default behaviour unless
197 -finitialized-nonconstants is used.
198 -Wvoid-variables
200 There are only 2 known global variables of type void:
201 ‘end_sys_globals’ and ‘end_sys_fields’. Any other void-variable
202 will warn.
203 -Wimplicit-function-pointer
205 A global function which is not declared with the ‘var’ keyword is
206 expected to have an implementing body, or be a builtin. If nei‐
207 ther is the case, it implicitly becomes a function pointer, and a
208 warning is generated.
209 -Wvariadic-function
211 Currently there's no way for an in QC implemented function to
212 access variadic parameters. If a function with variadic parame‐
213 ters has an implementing body, a warning will be generated.
214 -Wframe-macros
216 Generate warnings about ‘$frame’ commands, for instance about
217 duplicate frame definitions.
218 -Weffectless-statement
220 Warn about statements which have no effect. Any expression which
221 does not call a function or assigns a variable.
222 -Wend-sys-fields
224 The ‘end_sys_fields’ variable is supposed to be a global variable
225 of type void. It is also recognized as a field but this will
226 generate a warning.
227 -Wassign-function-types
229 Warn when assigning to a function pointer with an unmatching sig‐
230 nature. This usually happens in cases like assigning the null
231 function to an entity's .think function pointer.
232 -Wcpp Show warnings created using the preprocessor's '#warning' direc‐
234 tive.
235 -Wmultifile-if
237 Warn if there's a preprocessor #if spanning across several files.
238 -Wdouble-declaration
240 Warn about multiple declarations of globals. This seems pretty
241 common in QC code so you probably do not want this unless you
242 want to clean up your code.
243 -Wconst-var
245 The combination of const and var is not illegal, however differ‐
246 ent compilers may handle them differently. We were told, the
247 intention is to create a function-pointer which is not assigna‐
248 ble. This is exactly how we interpret it. However for this
249 interpretation the ‘var’ keyword is considered superfluous (and
250 philosophically wrong), so it is possible to generate a warning
251 about this.
252 -Wmultibyte-character
254 Warn about multibyte character constants, they do not work right
255 now.
256 -Wternary-precedence
258 Warn if a ternary expression which contains a comma operator is
259 used without enclosing parenthesis, since this is most likely not
260 what you actually want. We recommend the -fcorrect-ternary
261 option.
262 -Wunknown-pragmas
264 Warn when encountering an unrecognized ‘#pragma’ line.
265 -Wunreachable-code
267 Warn about unreachable code. That is: code after a return state‐
268 ment, or code after a call to a function marked as 'noreturn'.
269 -Wdebug
271 Enable some warnings added in order to help debugging in the com‐
272 piler. You won't need this.
273 -Wunknown-attribute
275 Warn on an unknown attribute. The warning will inlclude only the
276 first token inside the enclosing attribute-brackets. This may
277 change when the actual attribute syntax is better defined.
278 -Wreserved-names
280 Warn when using reserved names such as ‘nil’.
281 -Wuninitialized-constant
283 Warn about global constants (using the ‘const’ keyword) with no
284 assigned value.
285 -Wuninitialized-global
287 Warn about global variables with no initializing value. This is
288 off by default, and is added mostly to help find null-values
289 which are supposed to be replaced by the untyped 'nil' constant.
290 -Wdifferent-qualifiers
292 Warn when a variables is redeclared with a different qualifier.
293 For example when redeclaring a variable as ´var´ which was previ‐
294 ously marked ´const´.
295 -Wdifferent-attributes
297 Similar to the above but for attributes like ‘[[noreturn]]’.
298 -Wdeprecated
300 Warn when a function is marked with the attribute "[[depre‐
301 cated]]". This flag enables a warning on calls to functions
302 marked as such.
303 -Wparenthesis
305 Warn about possible mistakes caused by missing or wrong parenthe‐
306 sis, like an assignment in an 'if' condition when there's no
307 additional set of parens around the assignment.
308 -Wunsafe-types
310 When passing variadic parameters via ...(N) it can happen that
311 incompatible types are passed to functions. This enables several
312 warnings when static typechecking cannot guarantee consistent
313 behavior.
314 -Wbreakdef
316 When compiling original id1 QC there is a definition for `break`
317 which conflicts with the 'break' keyword in GMQCC. Enabling this
318 will print a warning when the definition occurs. The definition
319 is ignored for both cases.
320 -Wconst-overwrite
322 When compiling original QuakeWorld QC there are instances where
323 code overwrites constants. This is considered an error, however
324 for QuakeWorld to compile it needs to be treated as a warning
325 instead, as such this warning only works when -std=qcc.
326 -Wdirective-inmacro
328 Warn about the use of preprocessor directives inside macros.
329
331 -fdarkplaces-string-table-bug
332 Add some additional characters to the string table in order to
333 compensate for a wrong boundcheck in some specific version of the
334 darkplaces engine.
335 -fadjust-vector-fields
337 When assigning to field pointers of type .vector the common be‐
338 haviour in compilers like fteqcc is to only assign the x-compo‐
339 nent of the pointer. This means that you can use the vector as
340 such, but you cannot use its y and z components directly. This
341 flag fixes this behaviour. Before using it make sure your code
342 does not depend on the buggy behaviour.
343 -fftepp
345 Enable a partially fteqcc-compatible preprocessor. It supports
346 all the features used in the Xonotic codebase. If you need more,
347 write a ticket.
348 -fftepp-predefs
350 Enable some predefined macros. This only works in combination
351 with ´-fftepp' and is currently not included by '-std=fteqcc'.
352 The following macros will be added:
353 __LINE__
355 __FILE__
356 __COUNTER__
357 __COUNTER_LAST__
358 __RANDOM__
359 __RANDOM_LAST__
360 __DATE__
361 __TIME__
362 __FUNC__
363 Note that __FUNC__ is not actually a preprocessor macro, but is
365 recognized by the parser even with the preprocessor disabled.
366 Note that fteqcc also defines __NULL__ which becomes the first
368 global. Assigning it to a vector does not yield the same result
369 as in gmqcc where __NULL__ is defined to nil (See -funtyped-nil
370 ), which will cause the vector to be zero in all components. With
371 fteqcc only the first component will be 0, while the other two
372 will become the first to of the global return value. This behav‐
373 ior is odd and relying on it should be discouraged, and thus is
374 not supported by gmqcc.
375 -frelaxed-switch
377 Allow switch cases to use non constant variables.
378 -fshort-logic
380 Perform early out in logical AND and OR expressions. The final
381 result will be either a 0 or a 1, see the next flag for more pos‐
382 sibilities.
383 -fperl-logic
385 In many languages, logical expressions perform early out in a
386 special way: If the left operand of an AND yeilds true, or the
387 one of an OR yields false, the complete expression evaluates to
388 the right side. Thus ‘true && 5’ evaluates to 5 rather than 1.
389 -ftranslatable-strings
391 Enable the underscore intrinsic: Using ‘_("A string constant")’
392 will cause the string immediate to get a name with a "dotrans‐
393 late_" prefix. The darkplaces engine recognizes these and trans‐
394 lates them in a way similar to how gettext works.
395 -finitialized-nonconstants
397 Don't implicitly convert initialized variables to constants. With
398 this flag, the const keyword is required to make a constant.
399 -fassign-function-types
401 If this flag is not set, (and it is set by default in the qcc and
402 fteqcc standards), assigning function pointers of mismatching
403 signatures will result in an error rather than a warning.
404 -flno Produce a linenumber file along with the output .dat file.
406 -fcorrect-ternary
408 Use C's operator precedence for ternary expressions. Unless your
409 code depends on fteqcc-compatible behaviour, you'll want to use
410 thi soption.
411 -fsingle-vector-defs
413 Normally vectors generate 4 defs, once for the vector, and once
414 for its components with _x, _y, _z suffixes. This option prevents
415 components from being listed.
416 -fcorrect-logic
418 Most QC compilers translate ‘if(a_vector)’ directly as an IF on
419 the vector, which means only the x-component is checked. This
420 option causes vectors to be cast to actual booleans via a NOT_V
421 and, if necessary, a NOT_F chained to it.
422 if (a_vector) // becomes
424 if not(!a_vector)
425 // likewise
426 a = a_vector && a_float // becomes
427 a = !!a_vector && a_float
428 -ftrue-empty-strings
430 An empty string is considered to be true everywhere. The NOT_S
431 instruction usually considers an empty string to be false, this
432 option effectively causes the unary not in strings to use NOT_F
433 instead.
434 -ffalse-empty-strings
436 An empty string is considered to be false everywhere. This means
437 loops and if statements which depend on a string will perform a
438 NOT_S instruction on the string before using it.
439 -futf8 Enable utf8 characters. This allows utf-8 encoded character con‐
441 stants, and escape sequence codepoints in the valid utf-8 range.
442 Effectively enabling escape sequences like '\{x2211}'.
443 -fbail-on-werror
445 When a warning is treated as an error, and this option is set
446 (which it is by default), it is like any other error and will
447 cause compilation to stop. When disabling this flag by using
448 -fno-bail-on-werror, compilation will continue until the end, but
449 no output is generated. Instead the first such error message's
450 context is shown.
451 -floop-labels
453 Allow loops to be labeled, and allow 'break' and 'continue' to
454 take an optional label to decide which loop to actually jump out
455 of or continue.
456 for :outer (i = 0; i < n; ++i) {
458 while (inner) {
459 ...;
460 if (something)
461 continue outer;
462 }
463 }
464 -funtyped-nil
466 Adds a global named 'nil' which is of no type and can be assigned
467 to anything. No typechecking will be performed on assignments.
468 Assigning to it is forbidden, using it in any other kind of
469 expression is also not allowed.
470 Note that this is different from fteqcc's __NULL__: In fteqcc,
472 __NULL__ maps to the integer written as '0i'. It's can be
473 assigned to function pointers and integers, but it'll error about
474 invalid instructions when assigning it to floats without enabling
475 the FTE instruction set. There's also a bug which allows it to be
476 assigned to vectors, for which the source will be the global at
477 offset 0, meaning the vector's y and z components will contain
478 the OFS_RETURN x and y components.
479 In that gmqcc the nil global is an actual global filled with
481 zeroes, and can be assigned to anything including fields, vectors
482 or function pointers, and they end up becoming zeroed.
483 -fpermissive
485 Various effects, usually to weaken some conditions.
486 with -funtyped-nil
488 Allow local variables named ‘nil’. (This will not
489 allow declaring a global of that name.)
490 -fvariadic-args
492 Allow variadic parameters to be accessed by QC code. This can be
493 achieved via the '...' function, which takes a parameter index
494 and a typename.
495 Example:
497 void vafunc(string...count) {
499 float i;
500 for (i = 0; i < count; ++i)
501 print(...(i, string), "\n");
502 }
503 -flegacy-vector-maths
505 Most Quake VMs, including the one from FTEQW or up till recently
506 Darkplaces, do not cope well with vector instructions with over‐
507 lapping input and output. This option will avoid producing such
508 code.
509 -fexpressions-for-builtins
511 Usually builtin-numbers are just immediate constants. With this
512 flag expressions can be used, as long as they are compile-time
513 constant.
514 Example:
516 void printA() = #1; // the usual way
518 void printB() = #2-1; // with a constant expression
519 -freturn-assignments
521 Enabiling this option will allow assigning values or expressions
522 to the return keyword as if it were a local variable of the same
523 type as the function's signature's return type.
524 Example:
526 float bar() { return 1024; }
528 float fun() {
529 return = bar();
530 return; // returns value of bar
531 }
532 -funsafe-varargs
534 When passing on varargs to a different functions, this turns some
535 static error cases into warnings. Like when the caller's varargs
536 are restricted to a different type than the callee's parameter.
537 Or a list of unrestricted varargs is passed into restricted
538 varargs.
539 -ftypeless-stores
541 Always use STORE_F, LOAD_F, STOREP_F when accessing scalar vari‐
542 ables. This is somewhat incorrect assembly instruction use, but
543 in all engines they do exactly the same. This makes disassembly
544 output harder to read, breaks decompilers, but causes the output
545 file to be better compressible.
546 -fsort-operands
548 In commutative instructions, always put the lower-numbered oper‐
549 and first. This shaves off 1 byte of entropy from all these
550 instructions, reducing compressed size of the output file.
551
553 -Opeephole
554 Some general peephole optimizations. For instance the code `a = b
555 + c` typically generates 2 instructions, an ADD and a STORE. This
556 optimization removes the STORE and lets the ADD write directly
557 into A.
558 -Otail-recursion
560 Tail recursive function calls will be turned into loops to avoid
561 the overhead of the CALL and RETURN instructions.
562 -Ooverlap-locals
564 Make all functions which use neither local arrays nor have locals
565 which are seen as possibly uninitialized use the same local sec‐
566 tion. This should be pretty safe compared to other compilers
567 which do not check for uninitialized values properly. The problem
568 is that there's QC code out there which really doesn't initialize
569 some values. This is fine as long as this kind of optimization
570 isn't used, but also, only as long as the functions cannot be
571 called in a recursive manner. Since it's hard to know whether or
572 not an array is actually fully initialized, especially when ini‐
573 tializing it via a loop, we assume functions with arrays to be
574 too dangerous for this optimization.
575 -Olocal-temps
577 This promotes locally declared variables to "temps". Meaning when
578 a temporary result of an operation has to be stored somewhere, a
579 local variable which is not 'alive' at that point can be used to
580 keep the result. This can reduce the size of the global section.
581 This will not have declared variables overlap, even if it was
582 possible.
583 -Oglobal-temps
585 Causes temporary values which do not need to be backed up on a
586 CALL to not be stored in the function's locals-area. With this, a
587 CALL to a function may need to back up fewer values and thus exe‐
588 cute faster.
589 -Ostrip-constant-names
591 Don't generate defs for immediate values or even declared con‐
592 stants. Meaning variables which are implicitly constant or qual‐
593 ified as such using the 'const' keyword.
594 -Ooverlap-strings
596 Aggressively reuse strings in the string section. When a string
597 should be added which is the trailing substring of an already
598 existing string, the existing string's tail will be returned
599 instead of the new string being added.
600 For example the following code will only generate 1 string:
602 print("Hello you!\n");
604 print("you!\n"); // trailing substring of "Hello you!\n"
605 There's however one limitation. Strings are still processed in
607 order, so if the above print statements were reversed, this opti‐
608 mization would not happen.
609 -Ocall-stores
611 By default, all parameters of a CALL are copied into the parame‐
612 ter-globals right before the CALL instructions. This is the easi‐
613 est and safest way to translate calls, but also adds a lot of
614 unnecessary copying and unnecessary temporary values. This opti‐
615 mization makes operations which are used as a parameter evaluate
616 directly into the parameter-global if that is possible, which is
617 when there's no other CALL instruction in between.
618 -Ovoid-return
620 Usually an empty RETURN instruction is added to the end of a void
621 typed function. However, additionally after every function a DONE
622 instruction is added for several reasons. (For example the qcvm's
623 disassemble switch uses it to know when the function ends.). This
624 optimization replaces that last RETURN with DONE rather than
625 adding the DONE additionally.
626 -Ovector-components
628 Because traditional QC code doesn't allow you to access individ‐
629 ual vector components of a computed vector without storing it in
630 a local first, sometimes people multiply it by a constant like
631 ‘'0 1 0'’ to get, in this case, the y component of a vector. This
632 optimization will turn such a multiplication into a direct compo‐
633 nent access. If the factor is anything other than 1, a float-mul‐
634 tiplication will be added, which is still faster than a vector
635 multiplication.
636 -Oconst-fold-dce
638 For constant expressions that result in dead code (such as a
639 branch whos condition can be evaluated at compile-time), this
640 will eliminate the branch and else body (if present) to produce
641 more optimal code.
642
644 The configuration file is similar to regular .ini files. Comments start
645 with hashtags or semicolons, sections are written in square brackets and
646 in each section there can be arbitrary many key-value pairs.
647 There are 3 sections currently: ‘flags’, ‘warnings’, ‘optimizations’.
649 They contain a list of boolean values of the form ‘VARNAME = true’ or
650 ‘VARNAME = false’. The variable names are the same as for the corre‐
651 sponding -W, -f or -O flag written with only capital letters and dashes
652 replaced by underscores.
653 Here's an example:
655 # a GMQCC configuration file
657 [flags]
658 FTEPP = true
659 ADJUST_VECTOR_FIELDS = false
660 LNO = true
661 [warnings]
663 UNUSED_VARIABLE = false
664 USED_UNINITIALIZED = true
665 [optimizations]
667 PEEPHOLE = true
668 TAIL_RECURSION = true
669
671 gmqcc.ini.example
672 A documented example for a gmqcc.ini file.
673
675 qcvm(1)
676
678 See <http://graphitemaster.github.com/gmqcc>.
679
681 Currently the '-fftepp-predefs' flag is not included by '-std=fteqcc',
682 partially because it is not entirely conformant to fteqcc.
683 Please report bugs on <http://github.com/graphitemaster/gmqcc/issues>, or
685 see <http://graphitemaster.github.com/gmqcc> on how to contact us.
686BSD January 24, 2013 BSD