7 .Nd A Quake C compiler built from the NIH realm of sarcastic wit
13 Traditionally, a QC compiler reads the file
15 which in its first line contains the output filename, and the rest is a
16 list of QC source files that are to be compiled in order.
18 optionally takes options to specify the output and
19 input files on the commandline, and also accepts assembly files.
22 mostly tries to mimic gcc's commandline handling, though
23 there are also traditional long-options available.
26 Show a usage message and exit.
27 .It Fl o , Fl -output= Ns Ar filename
28 Specify the output filename. Defaults to progs.dat. This will overwrite
29 the output file listed in a
31 file in case such a file is used.
32 .Bl -tag -width indent
34 Specify the optimization level
36 Highest optimization level
38 Default optimization level
40 Minimal optimization level
42 Disable optimization entirely
45 .It Fl O Ns Ar name , Fl Ono- Ns Ar name
46 Enable or disable a specific optimization. Note that these options
47 must be used after setting the optimization level, otherwise they'll
50 List all possible optimizations and the optimization level they're
53 Be less verbose. In particular removes the messages about which files
54 are being processed, and which compilation mode is being used, and
55 some others. Warnings and errors will of course still be displayed.
56 .It Fl D Ns Ar macroname , Fl D Ns Ar macroname Ns = Ns Ar value
57 Predefine a macro, optionally with a optional value.
59 Run only the preprocessor as if
61 was used and print the preprocessed code to stdout.
62 .It Fl W Ns Ar warning , Fl Wno- Ns Ar warning
63 Enable or disable a warning.
65 Enable almost all warnings. Overrides preceding
69 The following warnings will
72 .Bl -tag -width indent -offset indent
73 .It Fl W Ns Cm uninitialized-global
75 .It Fl W Ns Cm error , Fl Wno- Ns Cm error
76 Controls whether or not all warnings should be treated as errors.
77 .It Fl Werror- Ns Ar warning , Fl Wno-error- Ns Ar warning
78 Controls whether a specific warning should be an error.
80 List all possible warn flags.
81 .It Fl f Ns Ar flag , Fl fno- Ns Ar flag
82 Enable or disable a specific compile flag. See the list of flags
85 List all possible compile flags.
87 Disables colored output
88 .It Fl config= Ns Ar file
89 Use an ini file to read all the
95 Turn on some compiler debugging mechanisms.
97 Turn on compiler mem-check. (Shows allocations and checks for leaks.)
98 .It Fl -memdumpcols Ns Ar columns
99 Changes the number of columns to use for the debug memory dump, defaults to 16.
101 section about the file format.
102 .It Fl redirout= Ns Ar file
103 Redirects standard output to a
105 .It Fl redirerr= Ns Ar file
106 Redirects standard error to a
108 .It Fl std= Ns Ar standard
109 Use the specified standard for parsing QC code. The following standards
111 .Ar gmqcc , Ar qcc , Ar fteqcc
112 Selecting a standard also implies some
114 options and behaves as if
115 those options have been written right after the
118 if you changed them before the
120 option, you're now overwriting them.
122 .Fl std= Ns Cm gmqcc No includes:
123 .Bl -tag -width indent -compact -offset Ds
124 .It Fl f Ns Cm adjust-vector-fields
125 .It Fl f Ns Cm correct-logic
126 .It Fl f Ns Cm true-empty-strings
127 .It Fl f Ns Cm loop-labels
128 .It Fl f Ns Cm initialized-nonconstants
129 .It Fl f Ns Cm translatable-strings
130 .It Fl fno- Ns Cm false-empty-strings
131 .It Fl W Ns Cm invalid-parameter-count
132 .It Fl W Ns Cm missing-returnvalues
133 .It Fl f Ns Cm correct-ternary Li (cannot be turned off)
136 .Fl std= Ns Cm qcc No includes:
137 .Bl -tag -width indent -compact -offset Ds
138 .It Fl f Ns Cm assign-function-types
139 .It Fl fIno- Ns Cm adjust-vector-fields
142 .Fl std= Ns Cm fteqcc No includes:
143 .Bl -tag -width indent -compact -offset Ds
145 .It Fl f Ns Cm translatable-strings
146 .It Fl f Ns Cm assign-function-types
147 .It Fl W Ns Cm ternary-precedence
148 .It Fl fno- Ns Cm adjust-vector-fields
149 .It Fl fno- Ns Cm correct-ternary
152 Adds compiler information to the generated binary file. Currently
153 this includes the following globals:
154 .Bl -tag -width indent -compact
155 .It Li reserved:version
156 String containing the compiler version as printed by the --version
159 .It Fl -correct , Fl -no-correct
160 When enabled, errors about undefined values try to suggest an existing
161 value via spell checking.
163 DEBUG OPTION. Print the code's intermediate representation before the
164 optimization and finalization passes to stdout before generating the
167 DEBUG OPTION. Print the code's intermediate representation after the
168 optimization and finalization passes to stdout before generating the
169 binary. The instructions will be enumerated, and values will contain a
174 .It Fl W Ns Cm unused-variable
175 Generate a warning about variables which are declared but never used.
176 This can be avoided by adding the
178 keyword in front of the
179 variable declaration. Additionally a complete section of unreferenced
180 variables can be opened using
183 .Ql #pragma noref 0 Ns .
184 .It Fl W Ns Cm used-uninitialized
185 Generate a warning if it is possible that a variable can be used
186 without prior initialization. Note that this warning is not
187 necessarily reliable if the initialization happens only under certain
188 conditions. The other way is
190 possible: that the warning is
192 generated when uninitialized use
195 .It Fl W Ns Cm unknown-control-sequence
196 Generate an error when an unrecognized control sequence in a string is
197 used. Meaning: when there's a character after a backslash in a string
198 which has no known meaning.
199 .It Fl W Ns Cm extensions
200 Warn when using special extensions which are not part of the selected
202 .It Fl W Ns Cm field-redeclared
203 Generally QC compilers ignore redeclaration of fields. Here you can
204 optionally enable a warning.
205 .It Fl W Ns Cm missing-return-values
206 Functions which aren't of type
208 will warn if it possible to
209 reach the end without returning an actual value.
210 .It Fl W Ns Cm invalid-parameter-count
211 Warn about a function call with an invalid number of parameters.
212 .It Fl W Ns Cm local-shadows
213 Warn when a locally declared variable shadows variable.
214 .It Fl W Ns Cm local-constants
215 Warn when the initialization of a local variable turns the variable
216 into a constant. This is default behaviour unless
217 .Fl f Ns Cm initialized-nonconstants
219 .It Fl W Ns Cm void-variables
220 There are only 2 known global variables of type void:
223 .Ql end_sys_fields Ns .
224 Any other void-variable will warn.
225 .It Fl W Ns Cm implicit-function-pointer
226 A global function which is not declared with the
229 expected to have an implementing body, or be a builtin. If neither is
230 the case, it implicitly becomes a function pointer, and a warning is
232 .It Fl W Ns Cm variadic-function
233 Currently there's no way for an in QC implemented function to access
234 variadic parameters. If a function with variadic parameters has an
235 implementing body, a warning will be generated.
236 .It Fl W Ns Cm frame-macros
237 Generate warnings about
239 commands, for instance about
240 duplicate frame definitions.
241 .It Fl W Ns Cm effectless-statement
242 Warn about statements which have no effect. Any expression which does
243 not call a function or assigns a variable.
244 .It Fl W Ns Cm end-sys-fields
247 variable is supposed to be a global variable
250 It is also recognized as a \fIfield\fR but this
251 will generate a warning.
252 .It Fl W Ns Cm assign-function-types
253 Warn when assigning to a function pointer with an unmatching
254 signature. This usually happens in cases like assigning the null
255 function to an entity's .think function pointer.
257 Show warnings created using the preprocessor's '#warning' directive.
258 .It Fl W Ns Cm multifile-if
259 Warn if there's a preprocessor \fI#if\fR spanning across several
261 .It Fl W Ns Cm double-declaration
262 Warn about multiple declarations of globals. This seems pretty common
263 in QC code so you probably do not want this unless you want to clean
265 .It Fl W Ns Cm const-var
266 The combination of \fIconst\fR and \fIvar\fR is not illegal, however
267 different compilers may handle them differently. We were told, the
268 intention is to create a function-pointer which is not assignable.
269 This is exactly how we interpret it. However for this interpretation
272 keyword is considered superfluous (and philosophically
273 wrong), so it is possible to generate a warning about this.
274 .It Fl W Ns Cm multibyte-character
275 Warn about multibyte character constants, they do not work right now.
276 .It Fl W Ns Cm ternary-precedence
277 Warn if a ternary expression which contains a comma operator is used
278 without enclosing parenthesis, since this is most likely not what you
279 actually want. We recommend the
280 .Fl f Ns Cm correct-ternary
282 .It Fl W Ns Cm unknown-pragmas
283 Warn when encountering an unrecognized
286 .It Fl W Ns Cm unreachable-code
287 Warn about unreachable code. That is: code after a return statement,
288 or code after a call to a function marked as 'noreturn'.
290 Enable some warnings added in order to help debugging in the compiler.
292 .It Fl W Ns Cm unknown-attribute
293 Warn on an unknown attribute. The warning will inlclude only the first
294 token inside the enclosing attribute-brackets. This may change when
295 the actual attribute syntax is better defined.
296 .It Fl W Ns Cm reserved-names
297 Warn when using reserved names such as
299 .It Fl W Ns Cm uninitialized-constant
300 Warn about global constants (using the
304 .It Fl W Ns Cm uninitialized-global
305 Warn about global variables with no initializing value. This is off by
306 default, and is added mostly to help find null-values which are
307 supposed to be replaced by the untyped 'nil' constant.
308 .It Fl W Ns Cm different-qualifiers
309 Warn when a variables is redeclared with a different qualifier. For
310 example when redeclaring a variable as \'var\' which was previously
312 .It Fl W Ns Cm different-attributes
313 Similar to the above but for attributes like
314 .Ql [[noreturn]] Ns .
315 .It Fl W Ns Cm deprecated
316 Warn when a function is marked with the attribute
317 "[[deprecated]]". This flag enables a warning on calls to functions
319 .It Fl W Ns Cm parenthesis
320 Warn about possible mistakes caused by missing or wrong parenthesis,
321 like an assignment in an 'if' condition when there's no additional set
322 of parens around the assignment.
326 .It Fl f Ns Cm darkplaces-string-table-bug
327 Add some additional characters to the string table in order to
328 compensate for a wrong boundcheck in some specific version of the
330 .It Fl f Ns Cm adjust-vector-fields
331 When assigning to field pointers of type \fI.vector\fR the common
332 behaviour in compilers like \fIfteqcc\fR is to only assign the
333 x-component of the pointer. This means that you can use the vector as
334 such, but you cannot use its y and z components directly. This flag
335 fixes this behaviour. Before using it make sure your code does not
336 depend on the buggy behaviour.
338 Enable a partially fteqcc-compatible preprocessor. It supports all the
339 features used in the Xonotic codebase. If you need more, write a
341 .It Fl f Ns Cm ftepp-predefs
342 Enable some predefined macros. This only works in combination with
343 \'-fftepp' and is currently not included by '-std=fteqcc'. The
344 following macros will be added:
345 .Bd -literal -offset indent
356 Note that fteqcc also defines
358 which is not implemented yet.
360 .Fl f Ns Cm untyped-nil
361 about gmqcc's alternative to
363 .It Fl f Ns Cm relaxed-switch
364 Allow switch cases to use non constant variables.
365 .It Fl f Ns Cm short-logic
366 Perform early out in logical AND and OR expressions. The final result
367 will be either a 0 or a 1, see the next flag for more possibilities.
368 .It Fl f Ns Cm perl-logic
369 In many languages, logical expressions perform early out in a special
370 way: If the left operand of an AND yeilds true, or the one of an OR
371 yields false, the complete expression evaluates to the right side.
374 evaluates to 5 rather than 1.
375 .It Fl f Ns Cm translatable-strings
376 Enable the underscore intrinsic: Using
377 .Ql _("A string constant")
378 will cause the string immediate to get a name with a "dotranslate_"
379 prefix. The darkplaces engine recognizes these and translates them in
380 a way similar to how gettext works.
381 .It Fl f Ns Cm initialized-nonconstants
382 Don't implicitly convert initialized variables to constants. With this
383 flag, the \fIconst\fR keyword is required to make a constant.
384 .It Fl f Ns Cm assign-function-types
385 If this flag is not set, (and it is set by default in the qcc and
386 fteqcc standards), assigning function pointers of mismatching
387 signatures will result in an error rather than a warning.
389 Produce a linenumber file along with the output .dat file.
390 .It Fl f Ns Cm correct-ternary
391 Use C's operator precedence for ternary expressions. Unless your code
392 depends on fteqcc-compatible behaviour, you'll want to use thi
394 .It Fl f Ns Cm single-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.
398 .It Fl f Ns Cm correct-logic
399 Most QC compilers translate
401 directly as an IF on the
402 vector, which means only the x-component is checked. This option causes
403 vectors to be cast to actual booleans via a NOT_V and, if necessary, a
405 .Bd -literal -offset indent
406 if (a_vector) // becomes
409 a = a_vector && a_float // becomes
410 a = !!a_vector && a_float
412 .It Fl f Ns Cm true-empty-strings
413 An empty string is considered to be true everywhere. The NOT_S
414 instruction usually considers an empty string to be false, this option
415 effectively causes the unary not in strings to use NOT_F instead.
416 .It Fl f Ns Cm false-empty-strings
417 An empty string is considered to be false everywhere. This means loops
418 and if statements which depend on a string will perform a NOT_S
419 instruction on the string before using it.
421 Enable utf8 characters. This allows utf-8 encoded character constants,
422 and escape sequence codepoints in the valid utf-8 range. Effectively
423 enabling escape sequences like '\\{x2211}'.
424 .It Fl f Ns Cm bail-on-werror
425 When a warning is treated as an error, and this option is set (which
426 it is by default), it is like any other error and will cause
427 compilation to stop. When disabling this flag by using
428 \-fno-bail-on-werror, compilation will continue until the end, but no
429 output is generated. Instead the first such error message's context is
431 .It Fl f Ns Cm loop-labels
432 Allow loops to be labeled, and allow 'break' and 'continue' to take an
433 optional label to decide which loop to actually jump out of or
435 .Bd -literal -offset indent
436 for :outer (i = 0; i < n; ++i) {
444 .It Fl f Ns Cm untyped-nil
445 Adds a global named 'nil' which is of no type and can be assigned to
446 anything. No typechecking will be performed on assignments. Assigning
447 to it is forbidden, using it in any other kind of expression is also
450 Note that this is different from fteqcc's __NULL__: In fteqcc,
451 __NULL__ maps to the integer written as '0i'. It's can be assigned to
452 function pointers and integers, but it'll error about invalid
453 instructions when assigning it to floats without enabling the FTE
454 instruction set. There's also a bug which allows it to be assigned to
455 vectors, for which the source will be the global at offset 0, meaning
456 the vector's y and z components will contain the OFS_RETURN x and y
459 In that gmqcc the nil global is an actual global filled with zeroes,
460 and can be assigned to anything including fields, vectors or function
461 pointers, and they end up becoming zeroed.
462 .It Fl f Ns Cm permissive
463 Various effects, usually to weaken some conditions.
464 .Bl -tag -width indent -offset indent
465 .It with Fl f Ns Cm untyped-nil
466 Allow local variables named
468 (This will not allow declaring a global of that name.)
470 .It Fl f Ns Cm variadic-args
471 Allow variadic parameters to be accessed by QC code. This can be
472 achieved via the '...' function, which takes a parameter index and a
476 .Bd -literal -offset indent
477 void vafunc(string...count) {
479 for (i = 0; i < count; ++i)
480 print(...(i, string), "\\n");
483 .It Fl f Ns Cm legacy-vector-maths
484 Most Quake VMs, including the one from FTEQW or up till recently
485 Darkplaces, do not cope well with vector instructions with overlapping
486 input and output. This option will avoid producing such code.
490 .It Fl O Ns Cm peephole
491 Some general peephole optimizations. For instance the code `a = b + c`
492 typically generates 2 instructions, an ADD and a STORE. This
493 optimization removes the STORE and lets the ADD write directly into A.
494 .It Fl O Ns Cm tail-recursion
495 Tail recursive function calls will be turned into loops to avoid the
496 overhead of the CALL and RETURN instructions.
497 .It Fl O Ns Cm overlap-locals
498 Make all functions which use neither local arrays nor have locals
499 which are seen as possibly uninitialized use the same local section.
500 This should be pretty safe compared to other compilers which do not
501 check for uninitialized values properly. The problem is that there's
502 QC code out there which really doesn't initialize some values. This is
503 fine as long as this kind of optimization isn't used, but also, only
504 as long as the functions cannot be called in a recursive manner. Since
505 it's hard to know whether or not an array is actually fully
506 initialized, especially when initializing it via a loop, we assume
507 functions with arrays to be too dangerous for this optimization.
508 .It Fl O Ns Cm local-temps
509 This promotes locally declared variables to "temps". Meaning when a
510 temporary result of an operation has to be stored somewhere, a local
511 variable which is not 'alive' at that point can be used to keep the
512 result. This can reduce the size of the global section.
513 This will not have declared variables overlap, even if it was
515 .It Fl O Ns Cm global-temps
516 Causes temporary values which do not need to be backed up on a CALL to
517 not be stored in the function's locals-area. With this, a CALL to a
518 function may need to back up fewer values and thus execute faster.
519 .It Fl O Ns Cm strip-constant-names
520 Don't generate defs for immediate values or even declared constants.
521 Meaning variables which are implicitly constant or qualified as such
522 using the 'const' keyword.
523 .It Fl O Ns Cm overlap-strings
524 Aggressively reuse strings in the string section. When a string should
525 be added which is the trailing substring of an already existing
526 string, the existing string's tail will be returned instead of the new
529 For example the following code will only generate 1 string:
530 .Bd -literal -offset indent
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
538 .It Fl O Ns Cm call-stores
539 By default, all parameters of a CALL are copied into the
540 parameter-globals right before the CALL instructions. This is the
541 easiest and safest way to translate calls, but also adds a lot of
542 unnecessary copying and unnecessary temporary values. This
543 optimization makes operations which are used as a parameter evaluate
544 directly into the parameter-global if that is possible, which is when
545 there's no other CALL instruction in between.
546 .It Fl O Ns Cm void-return
547 Usually an empty RETURN instruction is added to the end of a void
548 typed function. However, additionally after every function a DONE
549 instruction is added for several reasons. (For example the qcvm's
550 disassemble switch uses it to know when the function ends.). This
551 optimization replaces that last RETURN with DONE rather than adding
552 the DONE additionally.
553 .It Fl O Ns Cm vector-components
554 Because traditional QC code doesn't allow you to access individual
555 vector components of a computed vector without storing it in a local
556 first, sometimes people multiply it by a constant like
559 in this case, the y component of a vector. This optimization will turn
560 such a multiplication into a direct component access. If the factor is
561 anything other than 1, a float-multiplication will be added, which is
562 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:
573 .Ql optimizations Ns .
574 They contain a list of boolean values of the form
577 .Ql VARNAME = false Ns .
578 The variable names are the same as for the
583 flag written with only capital letters and
584 dashes replaced by underscores.
587 .Bd -literal -offset indent
588 # a GMQCC configuration file
591 ADJUST_VECTOR_FIELDS = false
595 UNUSED_VARIABLE = false
596 USED_UNINITIALIZED = true
600 TAIL_RECURSION = true
604 .It gmqcc.ini.example
605 A documented example for a gmqcc.ini file.
610 See <http://graphitemaster.github.com/gmqcc>.
612 Currently the '-fftepp-predefs' flag is not included by '-std=fteqcc',
613 partially because it is not entirely conformant to fteqcc.
615 Please report bugs on <http://github.com/graphitemaster/gmqcc/issues>,
616 or see <http://graphitemaster.github.com/gmqcc> on how to contact us.