+ <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>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, pak, and testsuite</td>
+ </tr>
+ <tr>
+ <td>install</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>
+ <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 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 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>
+ </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 or T == -pp, 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>-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>