X-Git-Url: https://git.xonotic.org/?p=xonotic%2Fgmqcc.git;a=blobdiff_plain;f=doc%2Fgmqcc.1;h=a87d465758e4087e2cc987603bb28a6272401838;hp=89605fe233a1a6d2f2e12026c12015c99ca54ea3;hb=365fe400b09777aba86a95950f1717a514f76edd;hpb=06ea71d5beb91f3205cb9120d05b9ebd92b6bd5d diff --git a/doc/gmqcc.1 b/doc/gmqcc.1 index 89605fe..a87d465 100644 --- a/doc/gmqcc.1 +++ b/doc/gmqcc.1 @@ -50,6 +50,11 @@ be overwritten. List all possible optimizations and the optimization level they're activated at. .TP +.BR -q ", " --quiet +Be less verbose. In particular removes the messages about which files +are being processed, and which compilation mode is being used, and +some others. Warnings and errors will of course still be displayed. +.TP .BI -W warning "\fR, " "" -Wno- warning Enable or disable a warning. .TP @@ -116,7 +121,18 @@ them. -f\fIno-\fRcorrect-ternary .fi .in -.SH Warnings +.TP +.B "-dump" +DEBUG OPTION. Print the code's intermediate representation before the +optimization and finalization passes to stdout before generating the +binary. +.TP +.B "-dumpfin" +DEBUG OPTION. Print the code's intermediate representation after the +optimization and finalization passes to stdout before generating the +binary. The instructions will be enumerated, and values will contain a +list of liferanges. +.SH COMPILE WARNINGS .TP .B -Wunused-variable Generate a warning about variables which are declared but never used. @@ -238,11 +254,11 @@ or code after a call to a function marked as 'noreturn'. .B -Wdebug Enable some warnings added in order to help debugging in the compiler. You won't need this. -.SH Compile Flags -.TP -.B -foverlap-locals -Allow local variables to overlap with each other if they don't -interfer with each other. (Not implemented right now) +.B -Wunknown-attribute +Warn on an unknown attribute. The warning will inlclude only the first +token inside the enclosing attribute-brackets. This may change when +the actual attribute syntax is better defined. +.SH COMPILE FLAGS .TP .B -fdarkplaces-string-table-bug Add some additional characters to the string table in order to @@ -262,6 +278,23 @@ Enable a partially fteqcc-compatible preprocessor. It supports all the features used in the Xonotic codebase. If you need more, write a ticket. .TP +.B -fftepp-predefs +Enable some predefined macros. This only works in combination with +\'-fftepp' and is currently not included by '-std=fteqcc'. The +following macros will be added: +.in +4 +.nf +__LINE__ +__FILE__ +__COUNTER__ +__COUNTER_LAST__ +__RANDOM__ +__RANDOM_LAST__ +.fi +.in +Note that fteqcc also defines __FUNC__, __TIME__, __DATE__ and +__NULL__, which are not yet implemented. +.TP .B -frelaxed-switch Allow switch cases to use non constant variables. .TP @@ -305,9 +338,9 @@ prevents components from being listed. .TP .B -fcorrect-logic Most QC compilers translate if(a_vector) directly as an IF on the -vector, which means only the x-component is checked. This causes all -non-float types to use an appropriate NOT instruction on all logic -operations and invert their use. +vector, which means only the x-component is checked. This causes +vectors to be cast to actual booleans via a NOT_V and, if necessary, a +NOT_F chained to it. .in +4 .nf if (a_vector) // becomes @@ -327,6 +360,81 @@ effectively causes the unary not in strings to use NOT_F instead. An empty string is considered to be false everywhere. This means loops and if statements which depend on a string will perform a NOT_S instruction on the string before using it. +.TP +.B -futf8 +Enable utf8 characters. This allows utf-8 encoded character constants, +and escape sequence codepoints in the valid utf-8 range. Effectively +enabling escape sequences like '\\{x2211}'. +.SH OPTIMIZATIONS +.TP +.B -Opeephole +Some general peephole optimizations. For instance the code `a = b + c` +typically generates 2 instructions, an ADD and a STORE. This +optimization removes the STORE and lets the ADD write directly into A. +.TP +.B -Otail-recursion +Tail recursive function calls will be turned into loops to avoid the +overhead of the CALL and RETURN instructions. +.TP +.B -Ooverlap-locals +Make all functions which use neither local arrays nor have locals +which are seen as possibly uninitialized use the same local section. +This should be pretty safe compared to other compilers which do not +check for uninitialized values properly. The problem is that there's +QC code out there which really doesn't initialize some values. This is +fine as long as this kind of optimization isn't used, but also, only +as long as the functions cannot be called in a recursive manner. Since +it's hard to know whether or not an array is actually fully +initialized, especially when initializing it via a loop, we assume +functions with arrays to be too dangerous for this optimization. +.TP +.B -Olocal-temps +This promotes locally declared variables to "temps". Meaning when a +temporary result of an operation has to be stored somewhere, a local +variable which is not 'alive' at that point can be used to keep the +result. This can reduce the size of the global section. +This will not have declared variables overlap, even if it was +possible. +.TP +.B -Ostrip-constant-names +Don't generate defs for immediate values or even declared constants. +Meaning variables which are implicitly constant or qualified as such +using the 'const' keyword. +.TP +.B -Ooverlap-strings +Aggressively reuse strings in the string section. When a string should +be added which is the trailing substring of an already existing +string, the existing string's tail will be returned instead of the new +string being added. + +For example the following code will only generate 1 string: + +.in +4 +.nf +print("Hell you!\\n"); +print("you!\\n"); // trailing substring of "Hello you!\\n" +.fi +.in +There's however one limitation. Strings are still processed in order, +so if the above print statements were reversed, this optimization +would not happen. +.TP +.B -Ocall-stores +By default, all parameters of a CALL are copied into the +parameter-globals right before the CALL instructions. This is the +easiest and safest way to translate calls, but also adds a lot of +unnecessary copying and unnecessary temporary values. This +optimization makes operations which are used as a parameter evaluate +directly into the parameter-global if that is possible, which is when +there's no other CALL instruction in between. +.TP +.B -Ovoid-return +Usually an empty RETURN instruction is added to the end of a void +typed function. However, additionally after every function a DONE +instruction is added for several reasons. (For example the qcvm's +disassemble switch uses it to know when the function ends.). This +optimization replaces that last RETURN with DONE rather than adding +the DONE additionally. .SH CONFIG The configuration file is similar to regular .ini files. Comments start with hashtags or semicolons, sections are written in square @@ -359,6 +467,10 @@ Here's an example: .fi .in .SH BUGS +Currently the '-fftepp-predefs' flag is not included by '-std=fteqcc', +partially because it is not entirely conformant to fteqcc. +.sp + Please report bugs on , or see on how to contact us. .SH FILES