1 #This configuration file is similar to a regular .ini file. Comments start
2 #with hashtags or semicolons, sections are written in square brackets and
3 #in each section there can be arbitrary many key-value pairs.
5 #There are 3 sections currently: ‘flags’, ‘warnings’, ‘optimizations’.
6 #They contain a list of boolean values of the form ‘VARNAME = true’ or
7 #‘VARNAME = false’. The variable names are the same as for the corre‐
8 #sponding -W, -f or -O flag written with only capital letters and dashes
9 #replaced by underscores.
12 #Add some additional characters to the string table in order to
13 #compensate for a wrong boundcheck in some specific version of the
16 DARKPLACES_STRING_TABLE_BUG = true
19 #When assigning to field pointers of type .vector the common be‐
20 #haviour in compilers like fteqcc is to only assign the x-compo‐
21 #nent of the pointer. This means that you can use the vector as
22 #such, but you cannot use its y and z components directly. This
23 #flag fixes this behaviour. Before using it make sure your code
24 #does not depend on the buggy behaviour.
26 ADJUST_VECTOR_FIELDS = true
29 #Enable a partially fteqcc-compatible preprocessor. It supports
30 #all the features used in the Xonotic codebase. If you need more,
36 #Enable some predefined macros. This only works in combination
37 #with '-fftepp' and is currently not included by '-std=fteqcc'.
38 #The following macros will be added:
50 #Note that __FUNC__ is not actually a preprocessor macro, but is
51 #recognized by the parser even with the preprocessor disabled.
53 #Note that fteqcc also defines __NULL__ which becomes the first
54 #global. Assigning it to a vector does not yield the same result
55 #as in gmqcc where __NULL__ is defined to nil (See -funtyped-nil
56 #), which will cause the vector to be zero in all components. With
57 #fteqcc only the first component will be 0, while the other two
58 #will become the first to of the global return value. This behav‐
59 #ior is odd and relying on it should be discouraged, and thus is
60 #not supported by gmqcc.
65 #Enable math constant definitions. This only works in combination
66 #with '-fftepp' and is currently not included by '-std=fteqcc'.
67 #The following macros will be added:
84 FTEPP_MATHDEFS = false
87 #Enable indirect macro expansion. This only works in combination
88 #with '-fftepp' and is currently not included by '-std=fteqcc'.
89 #Enabling this behavior will allow the preprocessor to operate more
90 #like the standard C preprocessor in that it will allow arguments
91 #of macros which are macro-expanded to be substituted into the
92 #definition of the macro. As an example:
95 # #define STR2(x) STR1(x)
96 # #define THE_ANSWER 42
97 # #define THE_ANSWER_STR STR2(THE_ANSWER) /* "42" */
99 #With this enabled, an expansion of THE_ANSWER_STR will yield
100 #the string "42". With this disabled an expansion of THE_ANSWER_STR
101 #will yield "THE_ANSWER"
103 FTEPP_INDIRECT_EXPANSION = false
106 #Allow switch cases to use non constant variables.
108 RELAXED_SWITCH = true
111 #Perform early out in logical AND and OR expressions. The final
112 #result will be either a 0 or a 1, see the next flag for more pos‐
118 #In many languages, logical expressions perform early out in a
119 #special way: If the left operand of an AND yeilds true, or the
120 #one of an OR yields false, the complete expression evaluates to
121 #the right side. Thus ‘true && 5’ evaluates to 5 rather than 1.
126 #Enable the underscore intrinsic: Using ‘_("A string constant")’
127 #will cause the string immediate to get a name with a "dotrans‐
128 #late_" prefix. The darkplaces engine recognizes these and trans‐
129 #lates them in a way similar to how gettext works.
131 TRANSLATABLE_STRINGS = true
134 #Don't implicitly convert initialized variables to constants. With
135 #this flag, the const keyword is required to make a constant.
137 INITIALIZED_NONCONSTANTS = false
140 #If this flag is not set, (and it is set by default in the qcc and
141 #fteqcc standards), assigning function pointers of mismatching
142 #signatures will result in an error rather than a warning.
144 ASSIGN_FUNCTION_TYPES = true
147 #Produce a linenumber file along with the output .dat file.
152 #Use C's operator precedence for ternary expressions. Unless your
153 #code depends on fteqcc-compatible behaviour, you'll want to use
156 CORRECT_TERNARY = true
159 #Normally vectors generate 4 defs, once for the vector, and once
160 #for its components with _x, _y, _z suffixes. This option prevents
161 #components from being listed.
164 SINGLE_VECTOR_DEFS = true
167 #Most QC compilers translate ‘if(a_vector)’ directly as an IF on
168 #the vector, which means only the x-component is checked. This
169 #option causes vectors to be cast to actual booleans via a NOT_V
170 #and, if necessary, a NOT_F chained to it.
172 # if (a_vector) // becomes
175 # a = a_vector && a_float // becomes
176 # a = !!a_vector && a_float
181 #An empty string is considered to be true everywhere. The NOT_S
182 #instruction usually considers an empty string to be false, this
183 #option effectively causes the unary not in strings to use NOT_F
186 TRUE_EMPTY_STRINGS = false
189 #An empty string is considered to be false everywhere. This means
190 #loops and if statements which depend on a string will perform a
191 #NOT_S instruction on the string before using it.
193 FALSE_EMPTY_STRINGS = true
196 #Enable utf8 characters. This allows utf-8 encoded character con‐
197 #stants, and escape sequence codepoints in the valid utf-8 range.
198 #Effectively enabling escape sequences like '\{x2211}'.
203 #When a warning is treated as an error, and this option is set
204 #(which it is by default), it is like any other error and will
205 #cause compilation to stop. When disabling this flag by using
206 #-fno-bail-on-werror, compilation will continue until the end, but
207 #no output is generated. Instead the first such error message's
210 BAIL_ON_WERROR = false
213 #Allow loops to be labeled, and allow 'break' and 'continue' to
214 #take an optional label to decide which loop to actually jump out
217 # for :outer (i = 0; i < n; ++i) {
228 #Adds a global named 'nil' which is of no type and can be assigned
229 #to anything. No typechecking will be performed on assignments.
230 #Assigning to it is forbidden, using it in any other kind of
231 #expression is also not allowed.
233 #Note that this is different from fteqcc's __NULL__: In fteqcc,
234 #__NULL__ maps to the integer written as '0i'. It's can be
235 #assigned to function pointers and integers, but it'll error about
236 #invalid instructions when assigning it to floats without enabling
237 #the FTE instruction set. There's also a bug which allows it to be
238 #assigned to vectors, for which the source will be the global at
239 #offset 0, meaning the vector's y and z components will contain
240 #the OFS_RETURN x and y components.#
242 #In that gmqcc the nil global is an actual global filled with
243 #zeroes, and can be assigned to anything including fields, vectors
244 #or function pointers, and they end up becoming zeroed.
250 #Various effects, usually to weaken some conditions.
252 # Allow local variables named ‘nil’. (This will not
253 # allow declaring a global of that name.)
258 #Allow variadic parameters to be accessed by QC code. This can be
259 #achieved via the '...' function, which takes a parameter index
264 # void vafunc(string...count) {
266 # for (i = 0; i < count; ++i)
267 # print(...(i, string), "\n");
273 #Most Quake VMs, including the one from FTEQW or up till recently
274 #Darkplaces, do not cope well with vector instructions with over‐
275 #lapping input and output. This option will avoid producing such
278 LEGACY_VECTOR_MATHS = false
281 #Usually builtin-numbers are just immediate constants. With this
282 #flag expressions can be used, as long as they are compile-time
287 # void printA() = #1; // the usual way
288 # void printB() = #2-1; // with a constant expression
290 EXPRESSIONS_FOR_BUILTINS = true
293 #Enabiling this option will allow assigning values or expressions
294 #to the return keyword as if it were a local variable of the same
295 #type as the function's signature's return type.
299 # float bar() { return 1024; }
302 # return; // returns value of bar (this can be omitted)
305 RETURN_ASSIGNMENTS = true
308 #When passing on varargs to a different functions, this turns some
309 #static error cases into warnings. Like when the caller's varargs
310 #are restricted to a different type than the callee's parameter.
311 #Or a list of unrestricted varargs is passed into restricted
314 UNSAFE_VARARGS = false
317 #Always use STORE_F, LOAD_F, STOREP_F when accessing scalar variables.
318 #This is somewhat incorrect assembly instruction use, but in all engines
319 #they do exactly the same. This makes disassembly output harder to read,
320 #breaks decompilers, but causes the output file to be better compressible.
322 TYPELESS_STORES = false
325 #In commutative instructions, always put the lower-numbered operand first.
326 #This shaves off 1 byte of entropy from all these instructions, reducing
327 #compressed size of the output file.
329 SORT_OPERANDS = false
332 #Emulate OP_STATE operations in code rather than using the instruction.
333 #The desired fps can be set via -state-fps=NUM, defaults to 10.
335 EMULATE_STATE = false
338 #Turn on arithmetic exception tests in the compiler. In constant expressions
339 #which trigger exceptions like division by zero, overflow, underflow, etc,
340 #the following flag will produce diagnostics for what triggered that
342 ARITHMETIC_EXCEPTIONS = false
344 #Split vector-literals which are only used dirctly as function parameters
345 #into 3 floats stored separately to reduce the number of globals at the
346 #expense of additional instructions.
347 SPLIT_VECTOR_PARAMETERS = false
349 #Force all expressions to be "eraseable" which permits the compiler
350 #to remove unused functions, variables and statements. This is
351 #equivlant to putting [[eraseable]] on all definitions. This is
352 #dangerous as it breaks auto cvars, definitions for functions the
353 #engine may be looking for and translatable strings. Instead, you
354 #can mark a definition with [[noerase]] to prevent this from happening.
355 DEFAULT_ERASEABLE = false
358 #Generate a warning about variables which are declared but never
359 #used. This can be avoided by adding the ‘noref’ keyword in front
360 #of the variable declaration. Additionally a complete section of
361 #unreferenced variables can be opened using ‘#pragma noref 1’ and
362 #closed via ‘#pragma noref 0’.
364 UNUSED_VARIABLE = false
367 #Generate a warning about vector variables which are declared but
368 #components of it are never used.
370 UNUSED_COMPONENT = false
372 #Generate a warning if it is possible that a variable can be used
373 #without prior initialization. Note that this warning is not nec‐
374 #essarily reliable if the initialization happens only under cer‐
375 #tain conditions. The other way is not possible: that the warning
376 #is not generated when uninitialized use is possible.
378 USED_UNINITIALIZED = false
381 #Generate an error when an unrecognized control sequence in a
382 #string is used. Meaning: when there's a character after a back‐
383 #slash in a string which has no known meaning.
385 UNKNOWN_CONTROL_SEQUENCE = false
388 #Warn when using special extensions which are not part of the
394 #Generally QC compilers ignore redeclaration of fields. Here you
395 #can optionally enable a warning.
397 FIELD_REDECLARED = false
400 #Functions which aren't of type void will warn if it possible to
401 #reach the end without returning an actual value.
403 MISSING_RETURN_VALUES = false
406 #Warn about a function call with an invalid number of parameters.
408 INVALID_PARAMETER_COUNT = false
411 #Warn when a locally declared variable shadows variable.
413 LOCAL_SHADOWS = false
416 #Warn when the initialization of a local variable turns the vari‐
417 #able into a constant. This is default behaviour unless
418 #-finitialized-nonconstants is used.
420 LOCAL_CONSTANTS = false
423 #There are only 2 known global variables of type void:
424 #‘end_sys_globals’ and ‘end_sys_fields’. Any other void-variable
427 VOID_VARIABLES = false
430 #A global function which is not declared with the ‘var’ keyword is
431 #expected to have an implementing body, or be a builtin. If nei‐
432 #ther is the case, it implicitly becomes a function pointer, and a
433 #warning is generated.
435 IMPLICIT_FUNCTION_POINTER = false
438 #Currently there's no way for an in QC implemented function to
439 #access variadic parameters. If a function with variadic parame‐
440 #ters has an implementing body, a warning will be generated.
442 VARIADIC_FUNCTION = false
445 #Generate warnings about ‘$frame’ commands, for instance about
446 #duplicate frame definitions.
451 #Warn about statements which have no effect. Any expression which
452 #does not call a function or assigns a variable.
454 EFFECTLESS_STATEMENT = false
457 #The ‘end_sys_fields’ variable is supposed to be a global variable
458 #of type void. It is also recognized as a field but this will
461 END_SYS_FIELDS = false
464 #Warn when assigning to a function pointer with an unmatching sig‐
465 #nature. This usually happens in cases like assigning the null
466 #function to an entity's .think function pointer.
468 ASSIGN_FUNCTION_TYPES = false
471 #Show warnings created using the preprocessor's '#warning' directive
476 #Warn if there's a preprocessor #if spanning across several files.
481 #Warn about multiple declarations of globals. This seems pretty
482 #common in QC code so you probably do not want this unless you
483 #want to clean up your code.
485 DOUBLE_DECLARATION = false
488 #The combination of const and var is not illegal, however differ‐
489 #ent compilers may handle them differently. We were told, the
490 #intention is to create a function-pointer which is not assigna‐
491 #ble. This is exactly how we interpret it. However for this
492 #interpretation the ‘var’ keyword is considered superfluous (and
493 #philosophically wrong), so it is possible to generate a warning
499 #Warn about multibyte character constants, they do not work right
502 MULTIBYTE_CHARACTER = false
505 #Warn if a ternary expression which contains a comma operator is
506 #used without enclosing parenthesis, since this is most likely not
507 #what you actually want. We recommend the -fcorrect-ternary
510 TERNARY_PRECEDENCE = false
513 #Warn when encountering an unrecognized ‘#pragma’ line.
515 UNKNOWN_PRAGMAS = true
518 #Warn about unreachable code. That is: code after a return state‐
519 #ment, or code after a call to a function marked as 'noreturn'.
521 UNREACHABLE_CODE = true
524 #Enable some warnings added in order to help debugging in the com‐
525 #piler. You won't need this.
530 #Warn on an unknown attribute. The warning will inlclude only the
531 #first token inside the enclosing attribute-brackets. This may
532 #change when the actual attribute syntax is better defined.
534 UNKNOWN_ATTRIBUTE = true
537 #Warn when using reserved names such as ‘nil’.
539 RESERVED_NAMES = true
542 #Warn about global constants (using the ‘const’ keyword) with no
545 UNINITIALIZED_CONSTANT = true
548 #Warn about global variables with no initializing value. This is
549 #off by default, and is added mostly to help find null-values
550 #which are supposed to be replaced by the untyped 'nil' constant.
552 UNINITIALIZED_GLOBAL = true
555 #Warn when a variables is redeclared with a different qualifier.
556 #For example when redeclaring a variable as 'var' which was previ‐
557 #ously marked 'const'.
559 DIFFERENT_QUALIFIERS = true
562 #Similar to the above but for attributes like ‘[[noreturn]]’.
564 DIFFERENT_ATTRIBUTES = true
567 #Warn when a function is marked with the attribute "[[depre‐
568 #cated]]". This flag enables a warning on calls to functions
574 #Warn about possible mistakes caused by missing or wrong parenthe‐
575 #sis, like an assignment in an 'if' condition when there's no
576 #additional set of parens around the assignment.
581 #When passing variadic parameters via ...(N) it can happen that
582 #incompatible types are passed to functions. This enables several
583 #warnings when static typechecking cannot guarantee consistent
589 #When compiling original id1 QC there is a definition for `break`
590 #which conflicts with the 'break' keyword in GMQCC. Enabling this
591 #print a warning when the definition occurs. The definition is
592 #ignored for both cases.
597 #When compiling original QuakeWorld QC there are instances where
598 #code overwrites constants. This is considered an error, however
599 #for QuakeWorld to compile it needs to be treated as a warning
600 #instead, as such this warning only works when -std=qcc.
602 CONST_OVERWRITE = true
605 #Warn about the use of preprocessor directives inside macros.
607 DIRECTIVE_INMACRO = true
610 #When using a function that is not explicitly defined, the compiler
611 #will search its intrinsics table for something that matches that
612 #function name by appending "__builtin_" to it. This behaviour may
613 #be unexpected, so enabling this will produce a diagnostic when
614 #such a function is resolved to a builtin.
619 #When comparing an inexact value such as `1.0/3.0' the result is
620 #pathologically wrong. Enabling this will trigger a compiler warning
621 #on such expressions.
622 INEXACT_COMPARES = true
626 #Some general peephole optimizations. For instance the code `a = b
627 #+ c` typically generates 2 instructions, an ADD and a STORE. This
628 #optimization removes the STORE and lets the ADD write directly
634 #Tail recursive function calls will be turned into loops to avoid
635 #the overhead of the CALL and RETURN instructions.
637 TAIL_RECURSION = true
640 #Make all functions which use neither local arrays nor have locals
641 #which are seen as possibly uninitialized use the same local sec‐
642 #tion. This should be pretty safe compared to other compilers
643 #which do not check for uninitialized values properly. The problem
644 #is that there's QC code out there which really doesn't initialize
645 #some values. This is fine as long as this kind of optimization
646 #isn't used, but also, only as long as the functions cannot be
647 #called in a recursive manner. Since it's hard to know whether or
648 #not an array is actually fully initialized, especially when ini‐
649 #tializing it via a loop, we assume functions with arrays to be
650 #too dangerous for this optimization.
652 OVERLAP_LOCALS = true
655 #This promotes locally declared variables to "temps". Meaning when
656 #a temporary result of an operation has to be stored somewhere, a
657 #local variable which is not 'alive' at that point can be used to
658 #keep the result. This can reduce the size of the global section.
659 #This will not have declared variables overlap, even if it was
665 #Causes temporary values which do not need to be backed up on a
666 #CALL to not be stored in the function's locals-area. With this, a
667 #CALL to a function may need to back up fewer values and thus exe‐
673 #Don't generate defs for immediate values or even declared con‐
674 #stants. Meaning variables which are implicitly constant or qual‐
675 #ified as such using the 'const' keyword.
677 STRIP_CONSTANT_NAMES = true
680 #Aggressively reuse strings in the string section. When a string
681 #should be added which is the trailing substring of an already
682 #existing string, the existing string's tail will be returned
683 #instead of the new string being added.
685 #For example the following code will only generate 1 string:
687 # print("Hello you!\n");
688 # print("you!\n"); // trailing substring of "Hello you!\n"
690 #There's however one limitation. Strings are still processed in
691 #order, so if the above print statements were reversed, this opti‐
692 #mization would not happen.
694 OVERLAP_STRINGS = true
697 #By default, all parameters of a CALL are copied into the parame‐
698 #ter-globals right before the CALL instructions. This is the easi‐
699 #est and safest way to translate calls, but also adds a lot of
700 #unnecessary copying and unnecessary temporary values. This opti‐
701 #mization makes operations which are used as a parameter evaluate
702 #directly into the parameter-global if that is possible, which is
703 #when there's no other CALL instruction in between.
708 #Usually an empty RETURN instruction is added to the end of a void
709 #typed function. However, additionally after every function a DONE
710 #instruction is added for several reasons. (For example the qcvm's
711 #disassemble switch uses it to know when the function ends.). This
712 #optimization replaces that last RETURN with DONE rather than
713 #adding the DONE additionally.
718 #Because traditional QC code doesn't allow you to access individ‐
719 #ual vector components of a computed vector without storing it in
720 #a local first, sometimes people multiply it by a constant like
721 #‘'0 1 0'’ to get, in this case, the y component of a vector. This
722 #optimization will turn such a multiplication into a direct compo‐
723 #nent access. If the factor is anything other than 1, a float-mul‐
724 #tiplication will be added, which is still faster than a vector
727 VECTOR_COMPONENTS = true
730 #For constant expressions that result in dead code (such as a
731 #branch whos condition can be evaluated at compile-time), this
732 #will eliminate the branch and else body (if present) to produce
735 CONST_FOLD_DCE = true
738 #For constant expressions we can fold them to immediate values.
739 #this option cannot be disabled or enabled, the compiler forces
740 #it to stay enabled by ignoring the value entierly. There are
741 #plans to enable some level of constant fold disabling, but right
742 #now the language can't function without it. This is merley here
743 #as an exercise to the reader.