X-Git-Url: https://git.xonotic.org/?p=xonotic%2Fgmqcc.git;a=blobdiff_plain;f=doc%2Fgmqcc.1;h=a87d465758e4087e2cc987603bb28a6272401838;hp=161811bf5c7bbadf9e7fcf2d55a0056c6cc98c0d;hb=365fe400b09777aba86a95950f1717a514f76edd;hpb=b360245b45856d709213a255af225c840cb08882 diff --git a/doc/gmqcc.1 b/doc/gmqcc.1 index 161811b..a87d465 100644 --- a/doc/gmqcc.1 +++ b/doc/gmqcc.1 @@ -38,7 +38,7 @@ Default optimization level .IP 1 Minimal optimization level .IP 0 -Disable optimization entierly +Disable optimization entirely .RE .TP .BI "-O" name "\fR, " "" -Ono- name @@ -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. @@ -196,7 +212,12 @@ function to an entity's .think function pointer. .TP .B -Wpreprocessor Enable warnings coming from the preprocessor. Like duplicate macro -declarations. +declarations. This warning triggers when there's a problem with the +way the preprocessor has been used, it will \fBnot\fR affect warnings +generated with the '#warning' directive. See -Wcpp. +.TP +.B -Wcpp +Show warnings created using the preprocessor's '#warning' directive. .TP .B -Wmultifile-if Warn if there's a preprocessor \fI#if\fR spanning across several @@ -233,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 @@ -257,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 @@ -297,6 +335,106 @@ soption. Normally vectors generate 4 defs, once for the vector, and once for its components with _x, _y, _z suffixes. This option 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 +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 +if not(!a_vector) +// likewise +a = a_vector && a_float // becomes +a = !!a_vector && a_float +.fi +.in +.TP +.B -ftrue-empty-strings +An empty string is considered to be true everywhere. The NOT_S +instruction usually considers an empty string to be false, this option +effectively causes the unary not in strings to use NOT_F instead. +.TP +.B -ffalse-empty-strings +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 @@ -329,8 +467,16 @@ 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 +.TP 20 +.B gmqcc.ini.example +A documented example for a gmqcc.ini file. .SH SEE ALSO .IR qcvm (1) .SH AUTHOR