1GMQCC(1)                      Programmer's Manual                     GMQCC(1)
2

NAME

4     gmqcc — A Quake C compiler built from the NIH realm of sarcastic wit
5

SYNOPSIS

7     gmqcc [options] [files...]
8

DESCRIPTION

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

OPTIONS

17     gmqcc mostly tries to mimic gcc's commandline handling, though there are
18     also traditional long-options available.
19
20     -h, --help
21             Show a usage message and exit.
22
23     -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
28             -Onumber
29                     Specify the optimization level
30
31             3       Highest optimization level
32
33             2       Default optimization level
34
35             1       Minimal optimization level
36
37             0       Disable optimization entirely
38
39     -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
44     -Ohelp  List all possible optimizations and the optimization level
45             they're activated at.
46
47     -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
53     -Dmacroname, -Dmacroname=value
54             Predefine a macro, optionally with a optional value.
55
56     -E      Run only the preprocessor as if -fftepp was used and print the
57             preprocessed code to stdout.
58
59     -Wwarning, -Wno-warning
60             Enable or disable a warning.
61
62     -Wall   Enable almost all warnings. Overrides preceding -W parameters.
63
64             The following warnings will not be enabled:
65
66                   -Wuninitialized-global
67
68     -Werror, -Wno-error
69             Controls whether or not all warnings should be treated as errors.
70
71     -Werror-warning, -Wno-error-warning
72             Controls whether a specific warning should be an error.
73
74     -Whelp  List all possible warn flags.
75
76     -fflag, -fno-flag
77             Enable or disable a specific compile flag. See the list of flags
78             below.
79
80     -fhelp  List all possible compile flags.
81
82     -nocolor
83             Disables colored output
84
85     -config=file
86             Use an ini file to read all the -O, -W and -f flag from. See the
87
88     -debug  Turn on some compiler debugging mechanisms.
89
90     -memchk
91             Turn on compiler mem-check. (Shows allocations and checks for
92             leaks.)
93
94     --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
98     -redirout=file
99             Redirects standard output to a file
100
101     -redirerr=file
102             Redirects standard error to a file
103
104     -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
111             -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
123             -std=qcc includes:
124                   -fassign-function-types
125                   -fIno-adjust-vector-fields
126
127             -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
135     --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
142     --correct, --no-correct
143             When enabled, errors about undefined values try to suggest an
144             existing value via spell checking.
145
146     -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
150     -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

COMPILE WARNINGS

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
164     -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
171     -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
176     -Wextensions
177             Warn when using special extensions which are not part of the
178             selected standard.
179
180     -Wfield-redeclared
181             Generally QC compilers ignore redeclaration of fields. Here you
182             can optionally enable a warning.
183
184     -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
188     -Winvalid-parameter-count
189             Warn about a function call with an invalid number of parameters.
190
191     -Wlocal-shadows
192             Warn when a locally declared variable shadows variable.
193
194     -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
199     -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
204     -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
210     -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
215     -Wframe-macros
216             Generate warnings about ‘$frame’ commands, for instance about
217             duplicate frame definitions.
218
219     -Weffectless-statement
220             Warn about statements which have no effect. Any expression which
221             does not call a function or assigns a variable.
222
223     -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
228     -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
233     -Wcpp   Show warnings created using the preprocessor's '#warning' direc‐
234             tive.
235
236     -Wmultifile-if
237             Warn if there's a preprocessor #if spanning across several files.
238
239     -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
244     -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
253     -Wmultibyte-character
254             Warn about multibyte character constants, they do not work right
255             now.
256
257     -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
263     -Wunknown-pragmas
264             Warn when encountering an unrecognized ‘#pragma’ line.
265
266     -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
270     -Wdebug
271             Enable some warnings added in order to help debugging in the com‐
272             piler.  You won't need this.
273
274     -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
279     -Wreserved-names
280             Warn when using reserved names such as ‘nil’.
281
282     -Wuninitialized-constant
283             Warn about global constants (using the ‘const’ keyword) with no
284             assigned value.
285
286     -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
291     -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
296     -Wdifferent-attributes
297             Similar to the above but for attributes like ‘[[noreturn]]’.
298
299     -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
304     -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
309     -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
315     -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
321     -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
327     -Wdirective-inmacro
328             Warn about the use of preprocessor directives inside macros.
329

COMPILE FLAGS

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
336     -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
344     -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
349     -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
354                   __LINE__
355                   __FILE__
356                   __COUNTER__
357                   __COUNTER_LAST__
358                   __RANDOM__
359                   __RANDOM_LAST__
360                   __DATE__
361                   __TIME__
362                   __FUNC__
363
364             Note that __FUNC__ is not actually a preprocessor macro, but is
365             recognized by the parser even with the preprocessor disabled.
366
367             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
376     -frelaxed-switch
377             Allow switch cases to use non constant variables.
378
379     -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
384     -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
390     -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
396     -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
400     -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
405     -flno   Produce a linenumber file along with the output .dat file.
406
407     -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
412     -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
417     -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
423                   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
429     -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
435     -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
440     -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
444     -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
452     -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
457                   for :outer (i = 0; i < n; ++i) {
458                       while (inner) {
459                           ...;
460                           if (something)
461                               continue outer;
462                       }
463                   }
464
465     -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
471             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
480             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
484     -fpermissive
485             Various effects, usually to weaken some conditions.
486
487                   with -funtyped-nil
488                           Allow local variables named ‘nil’.  (This will not
489                           allow declaring a global of that name.)
490
491     -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
496             Example:
497
498                   void vafunc(string...count) {
499                       float i;
500                       for (i = 0; i < count; ++i)
501                           print(...(i, string), "\n");
502                   }
503
504     -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
510     -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
515             Example:
516
517                   void printA() = #1; // the usual way
518                   void printB() = #2-1; // with a constant expression
519
520     -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
525             Example:
526
527                   float bar() { return 1024; }
528                   float fun() {
529                       return = bar();
530                       return; // returns value of bar
531                   }
532
533     -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
540     -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
547     -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

OPTIMIZATIONS

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
559     -Otail-recursion
560             Tail recursive function calls will be turned into loops to avoid
561             the overhead of the CALL and RETURN instructions.
562
563     -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
576     -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
584     -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
590     -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
595     -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
601             For example the following code will only generate 1 string:
602
603                   print("Hello you!\n");
604                   print("you!\n"); // trailing substring of "Hello you!\n"
605
606             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
610     -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
619     -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
627     -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
637     -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

CONFIG

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
648     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
654     Here's an example:
655
656           # a GMQCC configuration file
657           [flags]
658               FTEPP = true
659               ADJUST_VECTOR_FIELDS = false
660               LNO = true
661
662           [warnings]
663               UNUSED_VARIABLE = false
664               USED_UNINITIALIZED = true
665
666           [optimizations]
667               PEEPHOLE = true
668               TAIL_RECURSION = true
669

FILES

671     gmqcc.ini.example
672             A documented example for a gmqcc.ini file.
673

SEE ALSO

675     qcvm(1)
676

AUTHOR

678     See <http://graphitemaster.github.com/gmqcc>.
679

BUGS

681     Currently the '-fftepp-predefs' flag is not included by '-std=fteqcc',
682     partially because it is not entirely conformant to fteqcc.
683
684     Please report bugs on <http://github.com/graphitemaster/gmqcc/issues>, or
685     see <http://graphitemaster.github.com/gmqcc> on how to contact us.
686
687BSD                            January 24, 2013                            BSD
Impressum