e88acd9882f33134845987a3e6ac4faf525886a6
[xonotic/gmqcc.git] / doc / gmqcc.1
1 .\"mdoc
2 .Dd January 24, 2013
3 .Dt GMQCC 1 PRM
4 .Os
5 .Sh NAME
6 .Nm gmqcc
7 .Nd A Quake C compiler built from the NIH realm of sarcastic wit
8 .Sh SYNOPSIS
9 .Nm gmqcc
10 .Op Cm options
11 .Op Ar files...
12 .Sh DESCRIPTION
13 Traditionally, a QC compiler reads the file
14 .Pa progs.src
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.
17 .Nm gmqcc
18 optionally takes options to specify the output and
19 input files on the commandline, and also accepts assembly files.
20 .Sh OPTIONS
21 .Nm gmqcc
22 mostly tries to mimic gcc's commandline handling, though
23 there are also traditional long-options available.
24 .Bl -tag -width Ds
25 .It Fl h , Fl -help
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
30 .Pa progs.src
31 file in case such a file is used.
32 .Bl -tag -width indent
33 .It Fl O Ns Ar number
34 Specify the optimization level
35 .It Ar 3
36 Highest optimization level
37 .It Ar 2
38 Default optimization level
39 .It Ar 1
40 Minimal optimization level
41 .It Ar 0
42 Disable optimization entirely
43 .El
44 .Pp
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
48 be overwritten.
49 .It Fl O Ns Cm help
50 List all possible optimizations and the optimization level they're
51 activated at.
52 .It Fl q , Fl -quiet
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.
58 .It Fl E
59 Run only the preprocessor as if
60 .Fl f Ns Cm ftepp
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.
64 .It Fl W Ns Cm all
65 Enable almost all warnings. Overrides preceding
66 .Fl W
67 parameters.
68 .Pp
69 The following warnings will
70 .Em not
71 be enabled:
72 .Bl -tag -width indent -offset indent
73 .It Fl W Ns Cm uninitialized-global
74 .El
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.
79 .It Fl W Ns Cm help
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
83 below.
84 .It Fl f Ns Cm help
85 List all possible compile flags.
86 .It Fl nocolor
87 Disables colored output
88 .It Fl config= Ns Ar file
89 Use an ini file to read all the
90 .Fl O , Fl W
91 and
92 .Fl f
93 flag from. See the
94 .It Fl "debug"
95 Turn on some compiler debugging mechanisms.
96 .It Fl memchk
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.
100 .Sx CONFIG
101 section about the file format.
102 .It Fl redirout= Ns Ar file
103 Redirects standard output to a
104 .Ar file
105 .It Fl redirerr= Ns Ar file
106 Redirects standard error to a
107 .Ar file
108 .It Fl std= Ns Ar standard
109 Use the specified standard for parsing QC code. The following standards
110 are available:
111 .Ar gmqcc , Ar qcc , Ar fteqcc
112 Selecting a standard also implies some
113 .Fl f
114 options and behaves as if
115 those options have been written right after the
116 .Fl std
117 option, meaning
118 if you changed them before the
119 .Fl -std
120 option, you're now overwriting them.
121 .Pp
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)
134 .El
135 .Pp
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
140 .El
141 .Pp
142 .Fl std= Ns Cm fteqcc No includes:
143 .Bl -tag -width indent -compact -offset Ds
144 .It Fl f Ns Cm ftepp
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
150 .El
151 .It Fl -add-info
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
157 parameter.
158 .El
159 .It Fl -correct , Fl -no-correct
160 When enabled, errors about undefined values try to suggest an existing
161 value via spell checking.
162 .It Fl dump
163 DEBUG OPTION. Print the code's intermediate representation before the
164 optimization and finalization passes to stdout before generating the
165 binary.
166 .It Fl dumpfin
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
170 list of liferanges.
171 .El
172 .Sh COMPILE WARNINGS
173 .Bl -tag -width Ds
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
177 .Ql noref
178 keyword in front of the
179 variable declaration. Additionally a complete section of unreferenced
180 variables can be opened using
181 .Ql #pragma noref 1
182 and closed via
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
189 .Em not
190 possible: that the warning is
191 .Em not
192 generated when uninitialized use
193 .Em is
194 possible.
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
201 standard.
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
207 .Ft void
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
218 is used.
219 .It Fl W Ns Cm void-variables
220 There are only 2 known global variables of type void:
221 .Ql end_sys_globals
222 and
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
227 .Ql var
228 keyword is
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
231 generated.
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
238 .Ql $frame
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
245 The
246 .Ql end_sys_fields
247 variable is supposed to be a global variable
248 of type
249 .Ft void Ns .
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.
256 .It Fl W Ns Cm cpp
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
260 files.
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
264 up your code.
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
270 the
271 .Ql var
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
281 option.
282 .It Fl W Ns Cm unknown-pragmas
283 Warn when encountering an unrecognized
284 .Ql #pragma
285 line.
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'.
289 .It Fl W Ns Cm debug
290 Enable some warnings added in order to help debugging in the compiler.
291 You won't need this.
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
298 .Ql nil Ns .
299 .It Fl W Ns Cm uninitialized-constant
300 Warn about global constants (using the
301 .Ql const
302 keyword) with no
303 assigned value.
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
311 marked \'const\'.
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
318 marked as such.
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.
323 .It Fl W Ns Cm unsafe-types
324 When passing variadic parameters via
325 .Li ...(N)
326 it can happen that incompatible types are passed to functions. This
327 enables several warnings when static typechecking cannot guarantee
328 consistent behavior.
329 .It Fl W Ns Cm breakdef
330 When compiling original id1 QC there is a definition for `break`
331 which conflicts with the 'break' keyword in GMQCC. Enabling this
332 will print a warning when the definition occurs. The definition is
333 ignored for both cases.
334 .It Fl W Ns Cm const-overwrite
335 When compiling original QuakeWorld QC there are instances where
336 code overwrites constants. This is considered an error, however
337 for QuakeWorld to compile it needs to be treated as a warning
338 instead, as such this warning only works when \-std=qcc.
339 .It Fl W Ns Cm directive-inmacro
340 Warn about the use of preprocessor directives inside macros.
341 .It Fl W Ns Cm builtins
342 When using a function that is not explicitly defined, the compiler
343 will search its intrinsics table for something that matches that
344 function name by appending "__builtin_" to it. This behaviour may
345 be unexpected, so enabling this will produce a diagnostic when
346 such a function is resolved to a builtin.
347 .It Fl W Ns Cm inexact-compares
348 When comparing an inexact value such as `1.0/3.0' the result is
349 pathologically wrong. Enabling this will trigger a compiler warning
350 on such expressions.
351 .El
352 .Sh COMPILE FLAGS
353 .Bl -tag -width Ds
354 .It Fl f Ns Cm darkplaces-string-table-bug
355 Add some additional characters to the string table in order to
356 compensate for a wrong boundcheck in some specific version of the
357 darkplaces engine.
358 .It Fl f Ns Cm adjust-vector-fields
359 When assigning to field pointers of type \fI.vector\fR the common
360 behaviour in compilers like \fIfteqcc\fR is to only assign the
361 x-component of the pointer. This means that you can use the vector as
362 such, but you cannot use its y and z components directly. This flag
363 fixes this behaviour. Before using it make sure your code does not
364 depend on the buggy behaviour.
365 .It Fl f Ns Cm ftepp
366 Enable a partially fteqcc-compatible preprocessor. It supports all the
367 features used in the Xonotic codebase. If you need more, write a
368 ticket.
369 .It Fl f Ns Cm ftepp-predefs
370 Enable some predefined macros. This only works in combination with
371 \'\-fftepp' and is currently not included by '\-std=fteqcc'. The
372 following macros will be added:
373 .Bd -literal -offset indent
374 __LINE__
375 __FILE__
376 __COUNTER__
377 __COUNTER_LAST__
378 __RANDOM__
379 __RANDOM_LAST__
380 __DATE__
381 __TIME__
382 __FUNC__
383 .Ed
384 .Pp
385 Note that
386 .Li __FUNC__
387 is not actually a preprocessor macro, but is recognized by the parser
388 even with the preprocessor disabled.
389 .Pp
390 Note that fteqcc also defines
391 .Li __NULL__
392 which becomes the first global. Assigning it to a vector does not
393 yield the same result as in gmqcc where
394 .Li __NULL__
395 is defined to
396 .Li nil
397 (See
398 .Fl f Ns Cm untyped-nil
399 ), which will cause the vector to be zero in all components. With fteqcc
400 only the first component will be 0, while the other two will become
401 the first to of the global return value. This behavior is odd and
402 relying on it should be discouraged, and thus is not supported by
403 gmqcc.
404 .It Fl f Ns Cm ftepp-mathdefs
405 Enable math constant definitions. This only works in combination
406 with \'\-fftepp' and is currently not included by '\-std=fteqcc'.
407 The following macros will be added:
408 .Bd -literal -offset indent
409 M_E
410 M_LOG2E
411 M_LOG10E
412 M_LN2
413 M_LN10
414 M_PI
415 M_PI_2
416 M_PI_4
417 M_1_PI
418 M_2_PI
419 M_2_SQRTPI
420 M_SQRT2
421 M_SQRT1_2
422 M_TAU
423 .Ed
424 .It Fl f Ns Cm relaxed-switch
425 Allow switch cases to use non constant variables.
426 .It Fl f Ns Cm short-logic
427 Perform early out in logical AND and OR expressions. The final result
428 will be either a 0 or a 1, see the next flag for more possibilities.
429 .It Fl f Ns Cm perl-logic
430 In many languages, logical expressions perform early out in a special
431 way: If the left operand of an AND yeilds true, or the one of an OR
432 yields false, the complete expression evaluates to the right side.
433 Thus
434 .Ql true && 5
435 evaluates to 5 rather than 1.
436 .It Fl f Ns Cm translatable-strings
437 Enable the underscore intrinsic: Using
438 .Ql _("A string constant")
439 will cause the string immediate to get a name with a "dotranslate_"
440 prefix. The darkplaces engine recognizes these and translates them in
441 a way similar to how gettext works.
442 .It Fl f Ns Cm initialized-nonconstants
443 Don't implicitly convert initialized variables to constants. With this
444 flag, the \fIconst\fR keyword is required to make a constant.
445 .It Fl f Ns Cm assign-function-types
446 If this flag is not set, (and it is set by default in the qcc and
447 fteqcc standards), assigning function pointers of mismatching
448 signatures will result in an error rather than a warning.
449 .It Fl f Ns Cm lno
450 Produce a linenumber file along with the output .dat file.
451 .It Fl f Ns Cm correct-ternary
452 Use C's operator precedence for ternary expressions. Unless your code
453 depends on fteqcc-compatible behaviour, you'll want to use thi
454 soption.
455 .It Fl f Ns Cm single-vector-defs
456 Normally vectors generate 4 defs, once for the vector, and once for
457 its components with _x, _y, _z suffixes. This option
458 prevents components from being listed.
459 .It Fl f Ns Cm correct-logic
460 Most QC compilers translate
461 .Ql if(a_vector)
462 directly as an IF on the
463 vector, which means only the x-component is checked. This option causes
464 vectors to be cast to actual booleans via a NOT_V and, if necessary, a
465 NOT_F chained to it.
466 .Bd -literal -offset indent
467 if (a_vector) // becomes
468 if not(!a_vector)
469 // likewise
470 a = a_vector && a_float // becomes
471 a = !!a_vector && a_float
472 .Ed
473 .It Fl f Ns Cm true-empty-strings
474 An empty string is considered to be true everywhere. The NOT_S
475 instruction usually considers an empty string to be false, this option
476 effectively causes the unary not in strings to use NOT_F instead.
477 .It Fl f Ns Cm false-empty-strings
478 An empty string is considered to be false everywhere. This means loops
479 and if statements which depend on a string will perform a NOT_S
480 instruction on the string before using it.
481 .It Fl f Ns Cm utf8
482 Enable utf8 characters. This allows utf-8 encoded character constants,
483 and escape sequence codepoints in the valid utf-8 range. Effectively
484 enabling escape sequences like '\\{x2211}'.
485 .It Fl f Ns Cm bail-on-werror
486 When a warning is treated as an error, and this option is set (which
487 it is by default), it is like any other error and will cause
488 compilation to stop. When disabling this flag by using
489 \-fno-bail-on-werror, compilation will continue until the end, but no
490 output is generated. Instead the first such error message's context is
491 shown.
492 .It Fl f Ns Cm loop-labels
493 Allow loops to be labeled, and allow 'break' and 'continue' to take an
494 optional label to decide which loop to actually jump out of or
495 continue.
496 .Bd -literal -offset indent
497 for :outer (i = 0; i < n; ++i) {
498     while (inner) {
499         ...;
500         if (something)
501             continue outer;
502     }
503 }
504 .Ed
505 .It Fl f Ns Cm untyped-nil
506 Adds a global named 'nil' which is of no type and can be assigned to
507 anything. No typechecking will be performed on assignments. Assigning
508 to it is forbidden, using it in any other kind of expression is also
509 not allowed.
510 .sp
511 Note that this is different from fteqcc's __NULL__: In fteqcc,
512 __NULL__ maps to the integer written as '0i'. It's can be assigned to
513 function pointers and integers, but it'll error about invalid
514 instructions when assigning it to floats without enabling the FTE
515 instruction set. There's also a bug which allows it to be assigned to
516 vectors, for which the source will be the global at offset 0, meaning
517 the vector's y and z components will contain the OFS_RETURN x and y
518 components.
519 .sp
520 In that gmqcc the nil global is an actual global filled with zeroes,
521 and can be assigned to anything including fields, vectors or function
522 pointers, and they end up becoming zeroed.
523 .It Fl f Ns Cm permissive
524 Various effects, usually to weaken some conditions.
525 .Bl -tag -width indent -offset indent
526 .It with Fl f Ns Cm untyped-nil
527 Allow local variables named
528 .Ql nil Ns .
529 (This will not allow declaring a global of that name.)
530 .El
531 .It Fl f Ns Cm variadic-args
532 Allow variadic parameters to be accessed by QC code. This can be
533 achieved via the '...' function, which takes a parameter index and a
534 typename.
535 .Pp
536 Example:
537 .Bd -literal -offset indent
538 void vafunc(string...count) {
539     float i;
540     for (i = 0; i < count; ++i)
541         print(...(i, string), "\\n");
542 }
543 .Ed
544 .It Fl f Ns Cm legacy-vector-maths
545 Most Quake VMs, including the one from FTEQW or up till recently
546 Darkplaces, do not cope well with vector instructions with overlapping
547 input and output. This option will avoid producing such code.
548 .It Fl f Ns Cm expressions-for-builtins
549 Usually builtin-numbers are just immediate constants. With this flag
550 expressions can be used, as long as they are compile-time constant.
551 .Pp
552 Example:
553 .Bd -literal -offset indent
554 void printA() = #1; // the usual way
555 void printB() = #2-1; // with a constant expression
556 .Ed
557 .It Fl f Ns Cm return-assignments
558 Enabiling this option will allow assigning values or expressions to the
559 return keyword as if it were a local variable of the same type as the
560 function's signature's return type.
561 .Pp
562 Example:
563 .Bd -literal -offset indent
564 float bar() { return 1024; }
565 float fun() {
566     return = bar();
567     return; // returns value of bar
568 }
569 .Ed
570 .It Fl f Ns Cm unsafe-varargs
571 When passing on varargs to a different functions, this turns some
572 static error cases into warnings. Like when the caller's varargs are
573 restricted to a different type than the callee's parameter. Or a list
574 of unrestricted varargs is passed into restricted varargs.
575 .It Fl f Ns Cm typeless-stores
576 Always use STORE_F, LOAD_F, STOREP_F when accessing scalar variables.
577 This is somewhat incorrect assembly instruction use, but in all engines
578 they do exactly the same. This makes disassembly output harder to read,
579 breaks decompilers, but causes the output file to be better compressible.
580 .It Fl f Ns Cm sort-operands
581 In commutative instructions, always put the lower-numbered operand first.
582 This shaves off 1 byte of entropy from all these instructions, reducing
583 compressed size of the output file.
584 .El
585 .Sh OPTIMIZATIONS
586 .Bl -tag -width Ds
587 .It Fl O Ns Cm peephole
588 Some general peephole optimizations. For instance the code `a = b + c`
589 typically generates 2 instructions, an ADD and a STORE. This
590 optimization removes the STORE and lets the ADD write directly into A.
591 .It Fl O Ns Cm tail-recursion
592 Tail recursive function calls will be turned into loops to avoid the
593 overhead of the CALL and RETURN instructions.
594 .It Fl O Ns Cm overlap-locals
595 Make all functions which use neither local arrays nor have locals
596 which are seen as possibly uninitialized use the same local section.
597 This should be pretty safe compared to other compilers which do not
598 check for uninitialized values properly. The problem is that there's
599 QC code out there which really doesn't initialize some values. This is
600 fine as long as this kind of optimization isn't used, but also, only
601 as long as the functions cannot be called in a recursive manner. Since
602 it's hard to know whether or not an array is actually fully
603 initialized, especially when initializing it via a loop, we assume
604 functions with arrays to be too dangerous for this optimization.
605 .It Fl O Ns Cm local-temps
606 This promotes locally declared variables to "temps". Meaning when a
607 temporary result of an operation has to be stored somewhere, a local
608 variable which is not 'alive' at that point can be used to keep the
609 result. This can reduce the size of the global section.
610 This will not have declared variables overlap, even if it was
611 possible.
612 .It Fl O Ns Cm global-temps
613 Causes temporary values which do not need to be backed up on a CALL to
614 not be stored in the function's locals-area. With this, a CALL to a
615 function may need to back up fewer values and thus execute faster.
616 .It Fl O Ns Cm strip-constant-names
617 Don't generate defs for immediate values or even declared constants.
618 Meaning variables which are implicitly constant or qualified as such
619 using the 'const' keyword.
620 .It Fl O Ns Cm overlap-strings
621 Aggressively reuse strings in the string section. When a string should
622 be added which is the trailing substring of an already existing
623 string, the existing string's tail will be returned instead of the new
624 string being added.
625 .Pp
626 For example the following code will only generate 1 string:
627 .Bd -literal -offset indent
628 print("Hello you!\\n");
629 print("you!\\n"); // trailing substring of "Hello you!\\n"
630 .Ed
631 .Pp
632 There's however one limitation. Strings are still processed in order,
633 so if the above print statements were reversed, this optimization
634 would not happen.
635 .It Fl O Ns Cm call-stores
636 By default, all parameters of a CALL are copied into the
637 parameter-globals right before the CALL instructions. This is the
638 easiest and safest way to translate calls, but also adds a lot of
639 unnecessary copying and unnecessary temporary values. This
640 optimization makes operations which are used as a parameter evaluate
641 directly into the parameter-global if that is possible, which is when
642 there's no other CALL instruction in between.
643 .It Fl O Ns Cm void-return
644 Usually an empty RETURN instruction is added to the end of a void
645 typed function. However, additionally after every function a DONE
646 instruction is added for several reasons. (For example the qcvm's
647 disassemble switch uses it to know when the function ends.). This
648 optimization replaces that last RETURN with DONE rather than adding
649 the DONE additionally.
650 .It Fl O Ns Cm vector-components
651 Because traditional QC code doesn't allow you to access individual
652 vector components of a computed vector without storing it in a local
653 first, sometimes people multiply it by a constant like
654 .Ql '0 1 0'
655 to get,
656 in this case, the y component of a vector. This optimization will turn
657 such a multiplication into a direct component access. If the factor is
658 anything other than 1, a float-multiplication will be added, which is
659 still faster than a vector multiplication.
660 .It Fl O Ns Cm const-fold-dce
661 For constant expressions that result in dead code (such as a branch whos
662 condition can be evaluated at compile-time), this will eliminate the branch
663 and else body (if present) to produce more optimal code.
664 .El
665 .Sh CONFIG
666 The configuration file is similar to regular .ini files. Comments
667 start with hashtags or semicolons, sections are written in square
668 brackets and in each section there can be arbitrary many key-value
669 pairs.
670 .Pp
671 There are 3 sections currently:
672 .Ql flags Ns ,
673 .Ql warnings Ns ,
674 .Ql optimizations Ns .
675 They contain a list of boolean values of the form
676 .Ql VARNAME = true
677 or
678 .Ql VARNAME = false Ns .
679 The variable names are the same as for the
680 corresponding
681 .Fl W , Fl f
682 or
683 .Fl O
684 flag written with only capital letters and
685 dashes replaced by underscores.
686 .Pp
687 Here's an example:
688 .Bd -literal -offset indent
689 # a GMQCC configuration file
690 [flags]
691     FTEPP = true
692     ADJUST_VECTOR_FIELDS = false
693     LNO = true
694
695 [warnings]
696     UNUSED_VARIABLE = false
697     USED_UNINITIALIZED = true
698
699 [optimizations]
700     PEEPHOLE = true
701     TAIL_RECURSION = true
702 .Ed
703 .Sh FILES
704 .Bl -tag -width Ds
705 .It gmqcc.ini.example
706 A documented example for a gmqcc.ini file.
707 .El
708 .Sh SEE ALSO
709 .Xr qcvm 1
710 .Sh AUTHOR
711 See <http://graphitemaster.github.com/gmqcc>.
712 .Sh BUGS
713 Currently the '\-fftepp-predefs' flag is not included by '\-std=fteqcc',
714 partially because it is not entirely conformant to fteqcc.
715 .Pp
716 Please report bugs on <http://github.com/graphitemaster/gmqcc/issues>,
717 or see <http://graphitemaster.github.com/gmqcc> on how to contact us.