<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="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="download"><a href="https://github.com/graphitemaster/gmqcc/archive/0.1.zip">Download v0.1</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>
</ul>
</header>
<section>
- <h2>Defaults Flag</h2>
+ <ul class="wiki">
+ <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>
<p>
The <i>-show-defaults</i> flag instructs the compiler to print out the defaults used related to
the standard, optimization, and code generation. When this flag is specified, the compiler
will just print the defaults and quit. No compilation is performed.
</p>
<pre>$ gmqcc -show-defaults</pre>
- <h2>Compiling for an alternitive standard</h2>
+ <h3>Compiling for an alternitive standard</h3>
To compile with a different dialect of the QuakeC programming language the <i>-std</i>
flag can be instructed to select one of the following options:
<table border="0">
<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>Selects the standard dialect</td>
</tr>
</table>
- <h2>Predefined Macros</h2>
+ <h3>Predefined Macros</h3>
<table border="0">
<tr>
<td>Macro</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>Specifies the current selected stanadards major version number.</td>
</tr>
</table>
- <h2>Unsupported compatability options</h2>
+ <h3>Unsupported compatability options</h3>
<p>
GMQCC strives hard for compatability with standard dialects, but not all
features of those standards might be implemented. The unsupported features
</tr>
</table>
</p>
- <h1>Less common compiler options</h1>
- <h2>Code generation options</h2>
+ <h2>Less common compiler options</h2>
+ <h3>Code generation options</h3>
<table border="0">
<tr>
<td>Option</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>
</table>
- <h2>Warning options</h2>
+ <h3>Warning options</h3>
<table border="0">
<tr>
<td>Option</td>
<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>Enabled warnings about unknown pragmas</td>
+ </tr>
+ </table>
+ <table border="0">
+ <tr><td>Options</td><td>What it does</td></tr>
+ <tr>
+ <td>-Otail-recursion</td>
+ <td>Enables tail recursion optimization</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>
- <h2>Miscellaneous options</h2>
+ <h3>Miscellaneous options</h3>
<table border="0">
<tr>
<td>Option</td>
<td>-memchk</td>
<td>Turns on compiler memory leak checker</td>
</tr>
-
<tr>
<td>-Whelp or -W?</td>
<td>Lists all warning options</td>
</tr>
-
<tr>
<td>-fhelp or -f?</td>
- <td>Liss all code generation options</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>
+ <h2>Building on BSD/NIX</h2>
+ <p>
+ To compile GMQCC on BSD/NIX the following things are
+ required:
+
+ <ul>
+ <li>GIT</li>
+ <li>Make</li>
+ <li>Any C90+ C compiler</li>
+ </ul>
+
+ Once obtained you may checkout the development repository
+ with the following shell commands
+
+<pre>$ git clone git://github.com/graphitemaster/gmqcc.git
+$ cd gmqcc
+</pre>
+
+ The Makefile contains a few rules, depending on what you
+ want to compile, the following rules are:
+
+ <table border="0">
+ <tr>
+ <td>Rule</td>
+ <td>What it does</td>
+ </tr>
+ <tr>
+ <td>gmqcc</td>
+ <td>Builds the gmqcc compiler</td>
+ </tr>
+ <tr>
+ <td>qcvm</td>
+ <td>Builds a standable QuakeC VM</td>
+ </tr>
+ <tr>
+ <td>testsuite</td>
+ <td>Builds the testsuite for GMQCC</td>
+ </tr>
+ <tr>
+ <td>all</td>
+ <td>Builds gmqcc, qcvm, and testsuite</td>
+ </tr>
+ <tr>
+ <td>install</td>
+ <td>Installs gmqcc to /usr/local/</td>
+ </tr>
+ <tr>
+ <td>check</td>
+ <td>Runs the testsuite to verify correctness</td>
+ </tr>
+ </table>
+ </p>
+ <h2>Building on Windows</h2>
+ <p>
+ To compile GMQCC on windows the following things are
+ required:
+
+ <ul>
+ <li><a href="http://msysgit.googlecode.com/files/Git-1.8.0-preview20121022.exe">msysGit</a></li>
+ <li><a href="http://www.microsoft.com/visualstudio/eng/downloads">Visual Studio</a></li>
+ </ul>
+
+ Once obtained you may checkout the development repository
+ with the following msysGit commands from a msysGit shell.
+ <pre>$ git clone git://github.com/graphitemaster/gmqcc.git</pre>
+ Included is a VS project file.
+ </p>
+
+ <h1><a name="tdoc">Testsuite Documentation</a></h1>
+ <h2>Running The Testsuite</h2>
+ <p>
+ To run the testsuite you can either use
+ <pre>$ make check</pre>
+ Or if you're on windows or have already compiled the
+ testsuite from source:
+ <pre>$ ./testsuite </pre>
+
+ Optionally you may provide the testsuite with additional
+ arguments:
+
+ <table border="0">
+ <tr>
+ <td>Argument</td>
+ <td>What it does</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>-debug</td>
+ <td>Turn on testsuite debug messages.</td>
+ </tr>
+ <tr>
+ <td>-memchk</td>
+ <td>Turn on testsuite memleak checker.</td>
+ </tr>
+ <tr>
+ <td>-nocolor</td>
+ <td>Turn off colored stdout/stderr.</td>
+ </tr>
+ </table>
+ </p>
+ <h2>Writing Tests</h2>
+ <p>
+ GMQCC comes with a complete testsuite for verifying semantics
+ and syntatics. The testsuite executes files from the test/
+ directory, by reading task template files.
+ </p>
+ <p>
+ templates are rules for a specific test, used to create a "task" that
+ is executed with those set of rules (arguments, and what not). Tests
+ that don't have a template with them cannot become tasks, since without
+ the information for that test there is no way to properly "test" them.
+ Rules for these templates are described in a template file, using a
+ task template language.
+ </p>
+ <p>
+ The languge is composed entierly of "tags" which describe a string of
+ text for a task. Think of it much like a configuration file. Except
+ it's been designed to allow flexibility and future support for prodecual
+ semantics.
+ <p>
+ <p>
+ The following "tags" are suported by the language:
+ </p>
+ <table border="0">
+ <tr>
+ <td>Tag</td>
+ <td>Description of what the tag does</td>
+ </tr>
+ <tr>
+ <td>D:</td>
+ <td>Used to set a description of the current test, this must be
+ provided, this tag is NOT optional.</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>
+ </tr>
+ <tr>
+ <td>T:</td>
+ <td>Used to set the procedure for the given task, there are two
+ options for this:
+ <ul>
+ <li>-compile
+ This simply performs compilation only</li>
+ <li>-execute
+ This will perform compilation and execution</li>
+ </ul>
+
+ This tag must be provided, this tag is NOT optional.
+ </td>
+ </tr>
+ <tr>
+ <td>C:</td>
+ <td>Used to set the compilation flags for the given task, this
+ must be provided, this tag is NOT optional.</td>
+ </tr>
+ <tr>
+ <td>E:</td>
+ <td>Used to set the execution flags for the given task. This tag
+ must be provided if T == -execute, otherwise it's erroneous
+ as compilation only takes place.</td>
+ </tr>
+ <tr>
+ <td>M:</td>
+ <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
+ takes place. Multiple M tags are required for multi-line comparision
+ </td>
+ </tr>
+ <tr>
+ <td>I:</td>
+ <td>Used to specify the INPUT source file to operate on, this must be
+ provided, this tag is NOT optional</td>
+ </tr>
+ </table>
+ <h3>Notes</h3>
+ <p>
+ These tags (with exception to M) have one-time use, using them more
+ than once will result in template compilation errors,
+ </p>
+ <p>
+ Lines beginning with # or // in the template file are comments and
+ are ignored by the template parser.
+ Whitespace is optional, with exception to the colon ':' between the
+ tag and it's assignment value.
+ </p>
+ The template compiler will detect erronrous tags (optional tags
+ 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>-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>-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>
+ </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>
+ </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