<head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="chrome=1">
- <title>GMQCC by graphitemaster</title>
+ <title>GMQCC</title>
<link rel="stylesheet" href="stylesheets/styles.css">
<link rel="stylesheet" href="stylesheets/pygment_trac.css">
<h1 class="header">GMQCC</h1>
<p class="header">An Improved Quake C Compiler</p>
<ul>
- <li class="buttons"><a href=index.html">Index</a></li>
- <li class="download"><a href="https://github.com/graphitemaster/gmqcc/zipball/master">Download ZIP</a></li>
- <li class="download"><a href="https://github.com/graphitemaster/gmqcc/tarball/master">Download TAR</a></li>
+ <li class="buttons"><a href=index.html>Index</a></li>
<li class="buttons"><a href="https://github.com/graphitemaster/gmqcc/issues">Issues</a></li>
<li class="buttons"><a href="doc.html">Documentation</a></li>
<li class="buttons"><a href="https://github.com/graphitemaster/gmqcc">View On GitHub</a></li>
<li class="wiki"><a class="wiki" href="#cdoc">Compiler Documentation</a></li>
<li class="wiki"><a class="wiki" href="#bdoc">Building Documentation</a></li>
<li class="wiki"><a class="wiki" href="#tdoc">Testsuite Documentation</a></li>
+ <li class="wiki"><a class="wiki" href="#vdoc">Virtual Machine Documentation</a></li>
</ul>
<h1><a name="cdoc">Compiler Documentation</a></h1>
<h3>Defaults Flag</h3>
<td>-O<level></td>
<td>Specfies the optimization level: highest being 3, lowest being 0 (no optimization).</td>
</tr>
+ <tr>
+ <td>-g</td>
+ <td>Enables generation of debug info for engine backtraces (turns on -flno)</td>
+ </tr>
<tr>
<td>-E</td>
<td>Instructs the compiler to only preprocess the input, writing the preprocessed output to stdout</td>
</tr>
+ <tr>
+ <td>-D</td>
+ <td>
+ "define" a macro. Optionally you may supply
+ a value to the macro with "=". Implicitally turns on -fftepp
+ </td>
+ </tr>
<tr>
<td>-Wall</td>
<td>Enables all compiled warnings for the selcted standard</td>
<td>What it represents</td>
</tr>
<tr>
- <td>GMQCC</td>
+ <td>__STD_GMQCC__</td>
<td>Specifies the current selected standard is gmqcc.</td>
</tr>
<tr>
- <td>FTEQCC</td>
+ <td>__STD_FTEQCC__</td>
<td>Specifies the current selected standard is fteqcc.</td>
</tr>
<tr>
- <td>QCC</td>
+ <td>__STD_QCC__</td>
<td>Specifies the current selected standard is qcc.</td>
</tr>
-
+ <tr>
+ <td>GMQCC</td>
+ <td>Defined always regardless of the selected standard</td>
+ </tr>
<tr>
<td>__STD_VERSION_MINOR__</td>
<td>Specifies the current selected stanadards minor version number.</td>
<td>__STD_VERSION_MAJOR__</td>
<td>Specifies the current selected stanadards major version number.</td>
</tr>
+ <tr>
+ <td>__FILE__</td>
+ <td>Expands to a const string literal of the current file (requires -fftepp-predef)</td>
+ </tr>
+ <tr>
+ <td>__LINE__</td>
+ <td>Expands to the current line number (requires -fftepp-predef)</td>
+ </tr>
+ <tr>
+ <td>__RANDOM__</td>
+ <td>Expands to a random number between [0, 256) (requires -fftepp-predef)</td>
+ </tr>
+ <tr>
+ <td>__COUNTER__</td>
+ <td>Expands to a unique number, each expansion causes it to increment (requires -fftepp-predef) </td>
+ </tr>
+ <tr>
+ <td>__RANDOM_LAST__</td>
+ <td>Expands to the last random number (requires -fftepp-predef)</td>
+ </tr>
+ <tr>
+ <td>__COUNTER_LAST__</td>
+ <td>Expands to the last counter number (requires -fftepp-predef)</td>
+ </tr>
</table>
<h3>Unsupported compatability options</h3>
<p>
<td>-fftepp</td>
<td>Enables FTEQ preprocessor</td>
</tr>
+ <tr>
+ <td>-fftepp-predef</td>
+ <td>Enables additional predefined macros for the FTEQ preprocessor</td>
+ </tr>
<tr>
<td>-frelaxted-switch</td>
<td>Relaxes switch statement semantics</td>
<td>-fperl-logic</td>
<td>Enables perl evalutaion/logic</td>
</tr>
+ <tr>
+ <td>-ftranslatable-strings</td>
+ <td>Enables translatable strings via .po file</td>
+ </tr>
+ <tr>
+ <td>-finitialized-nonconstants</td>
+ <td>Prevents initializations from becoming constant unless 'const' is specified as a qualifer</td>
+ </tr>
+ <tr>
+ <td>-fassign-function-types</td>
+ <td>Allows function types to be assignable even if their signature is invariant</td>
+ </tr>
+ <tr>
+ <td>-flno</td>
+ <td>Enables generation of progs.lno for engine VM backtraces (enabled with -g as well)</td>
+ </tr>
+ <tr>
+ <td>-fcorrect-ternary</td>
+ <td>Enabling this corrects the ternary percedecce bugs present in fteqcc</td>
+ </tr>
+ <tr>
+ <td>-fsingle-vector-defs</td>
+ <td>Prevents the creation of progdefs for vectors</td>
+ </tr>
+ <tr>
+ <td>-fcorrect-logic</td>
+ <td>Use cast vector to real booleans when used in logic expressions</td>
+ </tr>
+ <tr>
+ <td>-ftrue-empty-strings</td>
+ <td>Always treat empty strings as true</td>
+ </tr>
+ <tr>
+ <td>-ffalse-empty-strings</td>
+ <td>Opposite of above, empty strings always false</td>
+ </tr>
+ <tr>
+ <td>-futf8</td>
+ <td>Recognize utf-8 characters in character constants, and encode codepoint escape sequences in strings as utf-8</td>
+ </tr>
+ <tr>
+ <td>-fbail-on-werror</td>
+ <td>When a warning is printed and it is set to be treated as error via -Werror, compilation will be stopped.</td>
+ </tr>
+ <tr>
+ <td>-floop-labels</td>
+ <td>Allow loops and switches to be labeled and break and continue to take optional label to target it.</td>
+ </tr>
+ <tr>
+ <td>-funtyped-nil</td>
+ <td>Enable the 'nil' null constant, which has no type. It can be used as the right hand of any assignment.</td>
+ </tr>
+ <tr>
+ <td>-fpermissive</td>
+ <td>Be "permissive", e.g with -funtyped-nil, this will allow local variables with the name 'nil'</td>
+ </tr>
</table>
<h3>Warning options</h3>
<table border="0">
<td>-Wmultifile-if</td>
<td>Enables warnings about multifile if statements</td>
</tr>
+ <tr>
+ <td>-Wdouble-declaration</td>
+ <td>Enables warnings about double declarations</td>
+ </tr>
+ <tr>
+ <td>-Wconst-var</td>
+ <td>Enables warnings about 'const var' and 'var const'</td>
+ </tr>
+ <tr>
+ <td>-Wmultibyte-character</td>
+ <td>Enables warnings about use of multibyte characters</td>
+ </tr>
+ <tr>
+ <td>-Wternary-precedence</td>
+ <td>Enables warnings about ternary expressions whos precedence may be not what expected</td>
+ </tr>
+ <tr>
+ <td>-Wunknown-pragmas</td>
+ <td>Enables warnings about unknown pragmas</td>
+ </tr>
+ <tr>
+ <td>-Wunreachable-code</td>
+ <td>Enables warnings about unreachable code</td>
+ </tr>
+ <tr>
+ <td>-Wcpp</td>
+ <td>Enables warnings about the preprocessor</td>
+ </tr>
+ <tr>
+ <td>Wunknown-attribute</td>
+ <td>Enables warnings for when an unknown attribute is encountered.</td>
+ </tr>
+ <tr>
+ <td>-Wreserved-names</td>
+ <td>Enables warnings for variables or fields that are named with a reserved name</td>
+ </tr>
+ <tr>
+ <td>-Wuninitialized-constant</td>
+ <td>Enables warnings about const global variables with no initializing value</td>
+ </tr>
+ <tr>
+ <td>-Wuninitialized-global</td>
+ <td>Enables warnings about non-const gloal variable with no initializing value</td>
+ </tr>
+ <tr>
+ <td>-Wdeprecated</td>
+ <td>Enables warnings about calls to functions marked deprecated</td>
+ </tr>
+ </table>
+ <table border="0">
+ <tr><td>Options</td><td>What it does</td></tr>
+ <tr>
+ <td>-Opeephole</td>
+ <td>Enables peephole optimizations</td>
+ </tr>
+ <tr>
+ <td>-Olocal-temps</td>
+ <td>Enables local-temp omission optimizations</td>
+ </tr>
+ <tr>
+ <td>-Oglobal-temps</td>
+ <td>Enables global-temp omission optimizations</td>
+ </tr>
+ <tr>
+ <td>-Otail-recursion</td>
+ <td>Enables tail recursion optimization</td>
+ </tr>
+ <tr>
+ <td>-Otail-calls</td>
+ <td>Enables tail-call optimizations</td>
+ </tr>
+ <tr>
+ <td>-Ooverlap-locals</td>
+ <td>
+ Every function where it's safe to do so will share its local
+ section with others. The critera being that the function must
+ have any possibly uninitialized locals, or local arrays regardless
+ of how they are initialized.
+ </td>
+ </tr>
+ <tr>
+ <td>-Ostrip-constant-names</td>
+ <td>Strip the names of constants</td>
+ </tr>
+ <tr>
+ <td>-Ooverlap-strings</td>
+ <td>Agressivly reuse strings in the string-section.</td>
+ </tr>
+ <tr>
+ <td>-Ocall-stores</td>
+ <td>
+ Have expressions which are used as function parameters evaluate directly
+ into the parameter-globals if possible. This avoids copying.
+ </td>
+ </tr>
+ <tr>
+ <td>-Ovoid-return</td>
+ <td>Do not create a return instruction at the end of return-type void functions</td>
+ </tr>
</table>
<p>
- Individual warnings may be disabled with -Wno<warning>
+ Individual warnings may be disabled with -Wno-<warning>
<pre>$ gmqcc -Wno-frame-macros # disables frame duplication warning</pre>
</p>
<h3>Miscellaneous options</h3>
<td>-memchk</td>
<td>Turns on compiler memory leak checker</td>
</tr>
-
+ <tr>
+ <td>-dump</td>
+ <td>Dump IR before optimizing and finalizing</td>
+ </tr>
+ <tr>
+ <td>-dumpfin</td>
+ <td>Dump IR after optimizing and finalizing</td>
+ </tr>
<tr>
<td>-Whelp or -W?</td>
<td>Lists all warning options</td>
</tr>
-
<tr>
<td>-fhelp or -f?</td>
<td>Lists all code generation options</td>
</tr>
+ <tr>
+ <td>-redirout=<file></td>
+ <td>Redirect stdout to any file.</td>
+ </tr>
+ <tr>
+ <td>-redirerr=<file></td>
+ <td>Redirect stderr to any file.</td>
+ </tr>
+ <tr>
+ <td>-nocolor</td>
+ <td>Turn off colored stdout/stderr.</td>
+ </tr>
+ <tr>
+ <td>-config=<file></td>
+ <td>
+ Supply a configuration file to set options.
+ Note: If a file named <b>gmqcc.ini</b> or
+ <b>gmqcc.cfg</b> is found it will be loaded
+ implicitally.
+ </td>
+ </tr>
</table>
<h1><a name="bdoc">Building Documentation</a></h1>
<td>testsuite</td>
<td>Builds the testsuite for GMQCC</td>
</tr>
+ <tr>
+ <td>check, test</td>
+ <td>Build and executes the testsuite for GMQCC</td>
+ </tr>
+ <tr>
+ <td>pak</td>
+ <td>Builds the pak utility</td>
+ </tr>
+ <tr>
+ <td>splint</td>
+ <td>Runs splint (static analysis) on the source</td>
+ </tr>
+ <tr>
+ <td>gource</td>
+ <td>Runs gource visualization on the source</td>
+ </tr>
+ <tr>
+ <td>gource-record</td>
+ <td>Runs gource visualization and produces a rendered mp4</td>
+ </tr>
+ <tr>
+ <td>depend</td>
+ <td>Builds dependinces into the Makefile</td>
+ </tr>
<tr>
<td>all</td>
- <td>Builds gmqcc, qcvm, and testsuite</td>
+ <td>Builds gmqcc, qcvm, pak, and testsuite</td>
</tr>
<tr>
<td>install</td>
- <td>Installs gmqcc to /usr/local/</td>
+ <td>Installs gmqcc, qcvm, and documentaion</td>
+ </tr>
+ <tr>
+ <td>uninstall</td>
+ <td>Uninstalls gmqcc, qcvm, and documentation</td>
</tr>
<tr>
<td>check</td>
</tr>
<tr>
<td>F:</td>
- <td>Used to set a failure message, this message will be displayed
- if the test fails, this tag is optional.</td>
- </tr>
- <tr>
- <td>S:</td>
- <td>Used to set a success message, this message will be displayed
- if the test succeeds, this tag is optional.
- </td>
+ <td>Used to set test-suite specific flags, currently
+ the only supported flag is -no-defs which tells the
+ testsuite to exclude defs.qh.
+ </td>
</tr>
<tr>
<td>T:</td>
- <td>Used to set the procedure for the given task, there are two
+ <td>Used to set the procedure for the given task, there are four
options for this:
<ul>
<li>-compile
This simply performs compilation only</li>
<li>-execute
This will perform compilation and execution</li>
+ <li>-fail
+ This will perform compilation on the requirement it fails, otherwise
+ the test fails</li>
+ <li>-pp
+ This will perform preprocessing only</li>
</ul>
This tag must be provided, this tag is NOT optional.
<td>Used to describe a string of text that should be matched from
the output of executing the task. If this doesn't match the
task fails. This tag must be provided at least once if
- T == -execute, otherwise it's erroneous as compilation only
+ T == -execute or T == -pp, otherwise it's erroneous as compilation only
takes place. Multiple M tags are required for multi-line comparision
</td>
</tr>
that need not be set), as well as missing tags, and error accordingly
which will result in that task failing.
</p>
-
+ <h1><a name="vdoc">Quake C Virtual Machine Documentation</a></h1>
+ <p>
+ Included with GMQCC is a minimal implementation of the QCVM used in many game
+ engines. It's primarly used for the testsuite, but you may also use it as a
+ standalone runtime, or even embed it with existing appliciations.
+ </p>
+ <h2>Running The Standalone VM</h2>
+ <p>
+ To run the standalone application you need to have a compiled progs.dat, with an
+ entry function named main The main function can have any amount of arguments
+ as the standalone executor allows main to be invoked with your choice of arguments.
+ An example of invoking the VM:
+ <pre>$ ./qcvm progs.dat -float 200 #execute passing in 200 as a float to main</pre>
+ If main doesn't require arguments:
+ <pre>$ ./qcvm progs.dat #call main with no arguments</pre>
+
+ The standalone executor supports the following arguments for passing arguments to main 
+
+ <table border="0">
+ <tr>
+ <td>Argument</td>
+ <td>What it does</td>
+ </tr>
+ <tr>
+ <td>-string</td>
+ <td>Passes in a string to main</td>
+ </tr>
+ <tr>
+ <td>-float</td>
+ <td>Passes in a float to main</td>
+ </tr>
+ <tr>
+ <td>-vector</td>
+ <td>Passes in a vector to main</td>
+ </tr>
+ </table>
+
+ The order in which the arguments are expected for main, must be preserved, for
+ example if main 's signature is the following:
+ <pre>void main(float a, vector b)</pre>
+
+ Then to pass the arguments you'd use the same order:
+ <pre>$ ./qcvm -float 200 -vector '1 2 3'</pre>
+
+ <h3>Additional Arguments</h3>
+ The standalone virtual machine has the following optional command line arguments:
+ <table border="0">
+ <tr>
+ <td>Argument</td>
+ <td>What it does</td>
+ </tr>
+ <tr>
+ <td>-h, --help</td>
+ <td>Print help message</td>
+ </tr>
+ <tr>
+ <td>-trace</td>
+ <td>Trace the execution call hierarchy.</td>
+ </tr>
+ <tr>
+ <td>-profile</td>
+ <td>Profile the bytecode to find hotspots.</td>
+ </tr>
+ <tr>
+ <td>-info</td>
+ <td>Get info of the running bytecode.</td>
+ </tr>
+ <tr>
+ <td>-disasm</td>
+ <td>Dissasemble the bytecode into assembly.</td>
+ </tr>
+ <tr>
+ <td>-diasm-func</td>
+ <td>Dissasmble function</td>
+ </tr>
+ <tr>
+ <td>-printdefs</td>
+ <td>Prints all definitions for the bytecode running.</td>
+ </tr>
+ <tr>
+ <td>-printfields</td>
+ <td>Prints all fields for the bytecode running.</td>
+ </tr>
+ <tr>
+ <td>-printfuns</td>
+ <td>Prints all functions for the bytecode running.</td>
+ </tr>
+ <tr>
+ <td>-v</td>
+ <td>Be verbose</td>
+ </tr>
+ <tr>
+ <td>-v</td>
+ <td>Be even more verbose</td>
+ </tr>
+ <tr>
+ <td>-version, --version</td>
+ <td>Print version information</td>
+ </tr>
+ </table>
+
+ <h3>Builtins</h3>
+ The standalone virtual machine includes the following builtins.
+ <table border="0">
+ <tr>
+ <td>Builtin</td>
+ <td>Number</td>
+ </tr>
+ <tr><td>print</td><td>1</td></tr>
+ <tr><td>ftos</td><td>2</td></tr>
+ <tr><td>spawn</td><td>3</td></tr>
+ <tr><td>kill</td><td>4</td></tr>
+ <tr><td>vtos</td><td>5</td></tr>
+ <tr><td>error</td><td>6</td></tr>
+ <tr><td>vlen</td><td>7</td></tr>
+ <tr><td>etos</td><td>8</td></tr>
+ <tr><td>stof</td><td>9</td></tr>
+ <tr><td>strcat</td><td>10</td></tr>
+ <tr><td>strcmp</td><td>11</td></tr>
+ <tr><td>normalize</td><td>12</td></tr>
+ <tr><td>sqrt</td><td>13</td></tr>
+ <tr><td>floor</td><td>14</td></tr>
+ </table>
+ </p>
<h3>Support or Contact</h3>
<p>Having trouble with GMQCC? Join our IRC channel at #kf-engine on irc.freenode.net or contact <a href="mailto:cube2killfild@gmail.com">Us</a>
</section>
projects / xonotic / gmqcc.git / blobdiff