Merge pull request #187 from divVerent/patch-1
[xonotic/gmqcc.git] / gmqcc.ini.example
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.
4
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.
10
11 [flags]
12     #Add some additional characters to the string table in order to
13     #compensate for a wrong boundcheck in some specific version of the
14     #darkplaces engine.
15
16     DARKPLACES_STRING_TABLE_BUG = true
17
18
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.
25
26     ADJUST_VECTOR_FIELDS = true
27
28
29     #Enable a partially fteqcc-compatible preprocessor. It supports
30     #all the features used in the Xonotic codebase. If you need more,
31     #write a ticket.
32
33     FTEPP = true
34
35
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:
39     #
40     #   __LINE__
41     #   __FILE__
42     #   __COUNTER__
43     #   __COUNTER_LAST__
44     #   __RANDOM__
45     #   __RANDOM_LAST__
46     #   __DATE__
47     #   __TIME__
48     #   __FUNC__
49     #
50     #Note that __FUNC__ is not actually a preprocessor macro, but is
51     #recognized by the parser even with the preprocessor disabled.
52     #
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.
61
62     FTEPP_PREDEFS = false
63
64
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:
68     #
69     # M_E
70     # M_LOG2E
71     # M_LOG10E
72     # M_LN2
73     # M_LN10
74     # M_PI
75     # M_PI_2
76     # M_PI_4
77     # M_1_PI
78     # M_2_PI
79     # M_2_SQRTPI
80     # M_SQRT2
81     # M_SQRT1_2
82     # M_TAU
83
84     FTEPP_MATHDEFS = false
85
86
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:
93     #
94     #   #define STR1(x) #x
95     #   #define STR2(x) STR1(x)
96     #   #define THE_ANSWER 42
97     #   #define THE_ANSWER_STR STR2(THE_ANSWER) /* "42" */
98     #
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"
102
103     FTEPP_INDIRECT_EXPANSION = false
104
105
106     #Allow switch cases to use non constant variables.
107
108     RELAXED_SWITCH = true
109
110
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‐
113     #sibilities.
114
115     SHORT_LOGIC = true
116
117
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.
122
123     PERL_LOGIC = false
124
125
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.
130
131     TRANSLATABLE_STRINGS = true
132
133
134     #Don't implicitly convert initialized variables to constants. With
135     #this flag, the const keyword is required to make a constant.
136
137     INITIALIZED_NONCONSTANTS = false
138
139
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.
143
144     ASSIGN_FUNCTION_TYPES = true
145
146
147     #Produce a linenumber file along with the output .dat file.
148
149     LNO = false
150
151
152     #Use C's operator precedence for ternary expressions. Unless your
153     #code depends on fteqcc-compatible behaviour, you'll want to use
154     #this option.
155
156     CORRECT_TERNARY = true
157
158
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.
162
163
164     SINGLE_VECTOR_DEFS = true
165
166
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.
171     #
172     #   if (a_vector) // becomes
173     #   if not(!a_vector)
174     #   // likewise
175     #   a = a_vector && a_float // becomes
176     #   a = !!a_vector && a_float
177
178     CORRECT_LOGIC = true
179
180
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
184     #instead.
185
186     TRUE_EMPTY_STRINGS = false
187
188
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.
192
193     FALSE_EMPTY_STRINGS = true
194
195
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}'.
199
200     UTF8 = true
201
202
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
208     #context is shown.
209
210     BAIL_ON_WERROR = false
211
212
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
215     #of or continue.
216     #
217     #   for :outer (i = 0; i < n; ++i) {
218     #       while (inner) {
219     #           ...;
220     #           if (something)
221     #               continue outer;
222     #       }
223     #   }
224
225     LOOP_LABELS = true
226
227
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.
232     #
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.#
241     #
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.
245
246
247     UNTYPED_NIL = true
248
249
250     #Various effects, usually to weaken some conditions.
251     #   with -funtyped-nil
252     #       Allow local variables named ‘nil’.  (This will not
253     #       allow declaring a global of that name.)
254
255     PERMISSIVE = false
256
257
258     #Allow variadic parameters to be accessed by QC code. This can be
259     #achieved via the '...' function, which takes a parameter index
260     #and a typename.
261     #
262     #Example:
263     #
264     #   void vafunc(string...count) {
265     #       float i;
266     #       for (i = 0; i < count; ++i)
267     #           print(...(i, string), "\n");
268     #   }
269
270     VARIADIC_ARGS = true
271
272
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
276     #code.
277
278     LEGACY_VECTOR_MATHS = false
279
280
281     #Usually builtin-numbers are just immediate constants. With this
282     #flag expressions can be used, as long as they are compile-time
283     #constant.
284     #
285     #Example:
286     #
287     #   void printA() = #1;   // the usual way
288     #   void printB() = #2-1; // with a constant expression
289
290     EXPRESSIONS_FOR_BUILTINS = true
291
292
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.
296     #
297     #Example:
298     #
299     #   float bar() { return 1024; }
300     #   float fun() {
301     #       return = bar();
302     #       return; // returns value of bar (this can be omitted)
303     #   }
304
305     RETURN_ASSIGNMENTS = true
306
307
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
312     #varargs.
313
314     UNSAFE_VARARGS = false
315
316
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.
321
322     TYPELESS_STORES = false
323
324
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.
328
329     SORT_OPERANDS = false
330
331
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.
334
335     EMULATE_STATE = false
336
337
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
341     #exception.
342     ARITHMETIC_EXCEPTIONS = false
343
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
348
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
356
357 [warnings]
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’.
363
364     UNUSED_VARIABLE = false
365
366
367     #Generate a warning about vector variables which are declared but
368     #components of it are never used.
369
370     UNUSED_COMPONENT = false
371
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.
377
378     USED_UNINITIALIZED = false
379
380
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.
384
385     UNKNOWN_CONTROL_SEQUENCE = false
386
387
388     #Warn when using special extensions which are not part of the
389     #selected standard.
390
391     EXTENSIONS = false
392
393
394     #Generally QC compilers ignore redeclaration of fields. Here you
395     #can optionally enable a warning.
396
397     FIELD_REDECLARED = false
398
399
400     #Functions which aren't of type void will warn if it possible to
401     #reach the end without returning an actual value.
402
403     MISSING_RETURN_VALUES = false
404
405
406     #Warn about a function call with an invalid number of parameters.
407
408     INVALID_PARAMETER_COUNT = false
409
410
411     #Warn when a locally declared variable shadows variable.
412
413     LOCAL_SHADOWS = false
414
415
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.
419
420     LOCAL_CONSTANTS = false
421
422
423     #There are only 2 known global variables of type void:
424     #‘end_sys_globals’ and ‘end_sys_fields’.  Any other void-variable
425     #will warn.
426
427     VOID_VARIABLES = false
428
429
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.
434
435     IMPLICIT_FUNCTION_POINTER = false
436
437
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.
441
442     VARIADIC_FUNCTION = false
443
444
445     #Generate warnings about ‘$frame’ commands, for instance about
446     #duplicate frame definitions.
447
448     FRAME_MACROS = false
449
450
451     #Warn about statements which have no effect. Any expression which
452     #does not call a function or assigns a variable.
453
454     EFFECTLESS_STATEMENT = false
455
456
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
459     #generate a warning.
460
461     END_SYS_FIELDS = false
462
463
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.
467
468     ASSIGN_FUNCTION_TYPES = false
469
470
471     #Show warnings created using the preprocessor's '#warning' directive
472
473     CPP = true
474
475
476     #Warn if there's a preprocessor #if spanning across several files.
477
478     MULTIFILE_IF = true
479
480
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.
484
485     DOUBLE_DECLARATION = false
486
487
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
494     #about this.
495
496     CONST_VAR = true
497
498
499     #Warn about multibyte character constants, they do not work right
500     #now.
501
502     MULTIBYTE_CHARACTER = false
503
504
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
508     #option.
509
510     TERNARY_PRECEDENCE = false
511
512
513     #Warn when encountering an unrecognized ‘#pragma’ line.
514
515     UNKNOWN_PRAGMAS = true
516
517
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'.
520
521     UNREACHABLE_CODE = true
522
523
524     #Enable some warnings added in order to help debugging in the com‐
525     #piler.  You won't need this.
526
527     DEBUG = false
528
529
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.
533
534     UNKNOWN_ATTRIBUTE = true
535
536
537     #Warn when using reserved names such as ‘nil’.
538
539     RESERVED_NAMES = true
540
541
542     #Warn about global constants (using the ‘const’ keyword) with no
543     #assigned value.
544
545     UNINITIALIZED_CONSTANT = true
546
547
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.
551
552     UNINITIALIZED_GLOBAL = true
553
554
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'.
558
559     DIFFERENT_QUALIFIERS = true
560
561
562     #Similar to the above but for attributes like ‘[[noreturn]]’.
563
564     DIFFERENT_ATTRIBUTES = true
565
566
567     #Warn when a function is marked with the attribute "[[depre‐
568     #cated]]". This flag enables a warning on calls to functions
569     #marked as such.
570
571     DEPRECATED = true
572
573
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.
577
578     PARENTHESIS = true
579
580
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
584     #behavior.
585
586     UNSAFE_TYPES = true
587
588
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.
593
594     BREAKDEF = true
595
596
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.
601
602     CONST_OVERWRITE = true
603
604
605     #Warn about the use of preprocessor directives inside macros.
606
607     DIRECTIVE_INMACRO = true
608
609
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.
615
616     BUILTINS = true
617
618
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
623
624
625 [optimizations]
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
629     #into A.
630
631     PEEPHOLE = true
632
633
634     #Tail recursive function calls will be turned into loops to avoid
635     #the overhead of the CALL and RETURN instructions.
636
637     TAIL_RECURSION = true
638
639
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.
651
652     OVERLAP_LOCALS = true
653
654
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
660     #possible.
661
662     LOCAL_TEMPS = true
663
664
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‐
668     #cute faster.
669
670     GLOBAL_TEMPS = true
671
672
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.
676
677     STRIP_CONSTANT_NAMES = true
678
679
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.
684     #
685     #For example the following code will only generate 1 string:
686     #
687     #   print("Hello you!\n");
688     #   print("you!\n"); // trailing substring of "Hello you!\n"
689     #
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.
693
694     OVERLAP_STRINGS = true
695
696
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.
704
705     CALL_STORES = true
706
707
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.
714
715     VOID_RETURN = true
716
717
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
725     #multiplication.
726
727     VECTOR_COMPONENTS = true
728
729
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
733     #more optimal code.
734
735     CONST_FOLD_DCE = true
736
737
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.
744
745     CONST_FOLD = true