X-Git-Url: https://git.xonotic.org/?a=blobdiff_plain;ds=sidebyside;f=doc%2Fgmqcc.1;h=66fa92fcf0794f03f532bc4a5161f7e32626d854;hb=35ba2dcaf99f4352869ad8519c35fefb1c53dd93;hp=db5ccf6cd3cf612323ac2617f575dfce3e63e9ff;hpb=244e6a0a4db55516a774722c4c438f4548eac320;p=xonotic%2Fgmqcc.git diff --git a/doc/gmqcc.1 b/doc/gmqcc.1 index db5ccf6..66fa92f 100644 --- a/doc/gmqcc.1 +++ b/doc/gmqcc.1 @@ -1,7 +1,7 @@ .\" Process with groff -man -Tascii file.3 .TH GMQCC 1 2012-07-12 "" "gmqcc Manual" .SH NAME -gmqcc \- A Quake C compiler which tries to reduce suckiness. +gmqcc \- A Quake C compiler built from the NIH realm of sarcastic wit .SH SYNOPSIS .B gmqcc [\fIOPTIONS\fR] [\fIfiles...\fR] @@ -18,26 +18,438 @@ there are also traditional long-options available. .B "-h, --help" Show a usage message and exit. .TP +.B "-debug" +Turn on some compiler debugging mechanisms. +.TP +.B "-memchk" +Turn on compiler mem-check. (Shows allocations and checks for leaks.) +.TP .BI "-o, --output=" filename Specify the output filename. Defaults to progs.dat. This will overwrite the output file listed in a \fIprogs.src\fR file in case such a file is used. .TP -.BI "-O" n -Specify the optimization level, similar to gcc. +.BI "-O" number +Specify the optimization level +.RS +.IP 3 +Highest optimization level +.IP 2 +Default optimization level +.IP 1 +Minimal optimization level +.IP 0 +Disable optimization entirely +.RE +.TP +.BI "-O" name "\fR, " "" -Ono- name +Enable or disable a specific optimization. Note that these options +must be used after setting the optimization level, otherwise they'll +be overwritten. +.TP +.B -Ohelp +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 +.B -Wall +Enable all warnings. Overrides preceding -W parameters. +.TP +.BR -Werror ", " -Wno-error +Controls whether or not all warnings should be treated as errors. .TP -.BI "-a" filename -Append the specified files to the list of files to assemble using the QC-Assembler. +.BI -Werror- warning "\fR, " "" -Wno-error- warning +Controls whether a specific warning should be an error. .TP -.BI "-s" filename -Append the specified file which is to be interpreted as a \fIprogs.src\fR file. +.B -Whelp +List all possible warn flags. +.TP +.BI -f flag "\fR, " "" -fno- flag +Enable or disable a specific compile flag. See the list of flags +below. +.TP +.B -fhelp +List all possible compile flags. +.TP +.B -nocolor +Disables colored output +.TP +.BI -config= file +Use an ini file to read all the -O, -W and -f flag from. See the +CONFIG section about the file format. +.TP +.BI "-redirout=" file +Redirects standard output to a \fIfile\fR +.TP +.BI "-redirerr=" file +Redirects standard error to a \fIfile\fR .TP .BI "-std=" standard -Use the specified standard for parsing QC code. The following standards are available: +Use the specified standard for parsing QC code. The following standards +are available: .IR gmqcc , qcc , fteqcc +Selecting a standard also implies some -f options and behaves as if +those options have been written right after the -std option, meaning +if you changed them before the -std option, you're now overwriting +them. +.sp +.BR -std=gmqcc " includes:" +.in +4 +-fadjust-vector-fields +.in +.BR -std=qcc " includes:" +.in +4 +.nf +-fassign-function-types +-f\fIno-\fRadjust-vector-fields +.fi +.in +.BR -std=fteqcc " includes:" +.in +4 +.nf +-fftepp +-ftranslatable-strings +-fassign-function-types +-Wternary-precedence +-f\fIno-\fRadjust-vector-fields +-f\fIno-\fRcorrect-ternary +.fi +.in +.SH COMPILE WARNINGS +.TP +.B -Wunused-variable +Generate a warning about variables which are declared but never used. +This can be avoided by adding the \fInoref\fR keyword in front of the +variable declaration. Additionally a complete section of unreferenced +variables can be opened using \fI#pragma noref 1\fR, and closed via +\fI#pragma noref 0\fR. +.TP +.B -Wused-uninitialized +Generate a warning if it is possible that a variable can be used +without prior initialization. Note that this warning is not +necessarily reliable if the initialization happens only under certain +conditions. The other way is \fInot\fR possible: that the warning is +\fInot\fR generated when uninitialized use \fIis possible\fR. +.TP +.B -Wunknown-control-sequence +Generate an error when an unrecognized control sequence in a string is +used. Meaning: when there's a character after a backslash in a string +which has no known meaning. +.TP +.B -Wextensions +Warn when using special extensions which are not part of the selected +standard. +.TP +.B -Wfield-redeclared +Generally QC compilers ignore redeclaration of fields. Here you can +optionally enable a warning. +.TP +.B -Wmissing-return-values +Functions which aren't of type \fIvoid\fR will warn if it possible to +reach the end without returning an actual value. +.TP +.B -Wtoo-few-parameters +Warn about a function call with fewer parameters than the function +expects. +.TP +.B -Wlocal-shadows +Warn when a locally declared variable shadows variable. +.TP +.B -Wlocal-constants +Warn when the initialization of a local variable turns the variable +into a constant. This is default behaviour unless +\fI-finitialized-nonconstants\fR is used. +.TP +.B -Wvoid-variables +There are only 2 known global variables of type void: end_sys_globals +and end_sys_fields. Any other void-variable will warn. +.TP +.B -Wimplicit-function-pointer +A global function which is not declared with the \fIvar\fR keyword is +expected to have an implementing body, or be a builtin. If neither is +the case, it implicitly becomes a function pointer, and a warning is +generated. +.TP +.B -Wvariadic-function +Currently there's no way for an in QC implemented function to access +variadic parameters. If a function with variadic parameters has an +implementing body, a warning will be generated. +.TP +.B -Wframe-macros +Generate warnings about \fI$frame\fR commands, for instance about +duplicate frame definitions. +.TP +.B -Weffectless-statement +Warn about statements which have no effect. Any expression which does +not call a function or assigns a variable. +.TP +.B -Wend-sys-fields +The \fIend_sys_fields\fR variable is supposed to be a global variable +of type \fIvoid\fR. It is also recognized as a \fIfield\fR but this +will generate a warning. +.TP +.B -Wassign-function-types +Warn when assigning to a function pointer with an unmatching +signature. This usually happens in cases like assigning the null +function to an entity's .think function pointer. +.TP +.B -Wpreprocessor +Enable warnings coming from the preprocessor. Like duplicate macro +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 +files. +.TP +.B -Wdouble-declaration +Warn about multiple declarations of globals. This seems pretty common +in QC code so you probably do not want this unless you want to clean +up your code. +.TP +.B -Wconst-var +The combination of \fIconst\fR and \fIvar\fR is not illegal, however +different compilers may handle them differently. We were told, the +intention is to create a function-pointer which is not assignable. +This is exactly how we interpret it. However for this interpretation +the \fIvar\fR keyword is considered superfluous (and philosophically +wrong), so it is possible to generate a warning about this. +.TP +.B -Wmultibyte-character +Warn about multibyte character constants, they do not work right now. +.TP +.B -Wternary-precedence +Warn if a ternary expression which contains a comma operator is used +without enclosing parenthesis, since this is most likely not what you +actually want. We recommend the \fI-fcorrect-ternary\fR option. +.TP +.B -Wunknown-pragmas +Warn when encountering an unrecognized \fI#pragma\fR line. +.TP +.B -Wunreachable-code +Warn about unreachable code. That is: code after a return statement, +or code after a call to a function marked as 'noreturn'. +.TP +.B -Wdebug +Enable some warnings added in order to help debugging in the compiler. +You won't need this. +.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 -Patch the output file to work around a string-table bug in certain darkplaces versions. +Add some additional characters to the string table in order to +compensate for a wrong boundcheck in some specific version of the +darkplaces engine. +.TP +.B -fadjust-vector-fields +When assigning to field pointers of type \fI.vector\fR the common +behaviour in compilers like \fIfteqcc\fR is to only assign the +x-component of the pointer. This means that you can use the vector as +such, but you cannot use its y and z components directly. This flag +fixes this behaviour. Before using it make sure your code does not +depend on the buggy behaviour. +.TP +.B -fftepp +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 +.B -fshort-logic +Perform early out in logical AND and OR expressions. The final result +will be either a 0 or a 1, see the next flag for more possibilities. +.TP +.B -fperl-logic +In many languages, logical expressions perform early out in a special +way: If the left operand of an AND yeilds true, or the one of an OR +yields false, the complete expression evaluates to the right side. +Thus \fItrue && 5\fI evaluates to 5 rather than 1. +.TP +.B -ftranslatable-strings +Enable the underscore intrinsic: Using \fI_("A string constant")\fR +will cause the string immediate to get a name with a "dotranslate_" +prefix. The darkplaces engine recognizes these and translates them in +a way similar to how gettext works. +.TP +.B -finitialized-nonconstants +Don't implicitly convert initialized variables to constants. With this +flag, the \fIconst\fR keyword is required to make a constant. +.TP +.B -fassign-function-types +If this flag is not set, (and it is set by default in the qcc and +fteqcc standards), assigning function pointers of mismatching +signatures will result in an error rather than a warning. +.TP +.B -flno +Produce a linenumber file along with the output .dat file. +.TP +.B -fcorrect-ternary +Use C's operator precedence for ternary expressions. Unless your code +depends on fteqcc-compatible behaviour, you'll want to use thi +soption. +.TP +.B -fsingle-vector-defs +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 -fomit-nullbytes -Changes the output format to be more efficient. Requires a patched engine. See the -proposal for a better file structure in the gmqcc source tree. +.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. +.SH CONFIG +The configuration file is similar to regular .ini files. Comments +start with hashtags or semicolons, sections are written in square +brackets and in each section there can be arbitrary many key-value +pairs. +.sp +There are 3 sections currently: +.IR flags ", " warnings ", and " optimizations . +They contain a list of boolean values of the form `VARNAME = true` or +`VARNAME = false`. The variable names are the same as for the +corresponding -W, -f or -O flag written with only capital letters and +dashes replaced by underscores. +.sp +Here's an example: +.in +4 +.nf +# a GMQCC configuration file +[flags] + FTEPP = true + ADJUST_VECTOR_FIELDS = false + LNO = true + +[warnings] + UNUSED_VARIABLE = false + USED_UNINITIALIZED = true + +[optimizations] + PEEPHOLE = true + TAIL_RECURSION = true +.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 +See .