update irc channel
[xonotic/gmqcc.git] / doc.html
1 <!doctype html>
2 <html>
3     <head>
4         <meta charset="utf-8">
5         <meta http-equiv="X-UA-Compatible" content="chrome=1">
6         <title>GMQCC</title>
7
8         <link rel="stylesheet" href="stylesheets/styles.css">
9         <link rel="stylesheet" href="stylesheets/pygment_trac.css">
10         <script src="javascripts/scale.fix.js"></script>
11         <meta name="viewport" content="width=device-width, initial-scale=1, user-scalable=no">
12         <!--[if lt IE 9]>
13         <script src="//html5shiv.googlecode.com/svn/trunk/html5.js"></script>
14         <![endif]-->
15     </head>
16     <body>
17         <a href="https://github.com/graphitemaster/gmqcc"><div class="fork"></div></a>
18         <div class="wrapper">
19             <header>
20                 <h1 class="header">GMQCC</h1>
21                 <p class="header">An Improved Quake C Compiler</p>
22                 <ul>
23                     <li class="buttons"><a href=index.html>Index</a></li>
24                     <li class="buttons"><a href="https://github.com/graphitemaster/gmqcc/issues">Issues</a></li>
25                     <li class="buttons"><a href="doc.html">Documentation</a></li>
26                     <li class="buttons"><a href="https://github.com/graphitemaster/gmqcc">View On GitHub</a></li>
27                 </ul>
28             </header>
29             <section>
30                 <ul class="wiki">
31                     <li class="wiki"><a class="wiki" href="#cdoc">Compiler Documentation</a></li>
32                     <li class="wiki"><a class="wiki" href="#bdoc">Building Documentation</a></li>
33                     <li class="wiki"><a class="wiki" href="#tdoc">Testsuite Documentation</a></li>
34                     <li class="wiki"><a class="wiki" href="#vdoc">Virtual Machine Documentation</a></li>
35                 </ul>
36                 <h1><a name="cdoc">Compiler Documentation</a></h1>
37                 <h3>Defaults Flag</h3>
38                 <p>
39                     The <i>-show-defaults</i> flag instructs the compiler to print out the defaults used related to
40                     the standard, optimization, and code generation.  When this flag is specified, the compiler
41                     will just print the defaults and quit.  No compilation is performed.
42                 </p>
43                 <pre>$ gmqcc -show-defaults</pre>
44                 <h3>Compiling for an alternitive standard</h3>
45                 To compile with a different dialect of the QuakeC programming language the <i>-std</i>
46                 flag can be instructed to select one of the following options:
47                 <table border="0">
48                     <tr>
49                         <td>gmqcc</td>
50                         <td>default standard</td>
51                     </tr>
52                     <tr>
53                         <td>fteqcc</td>
54                         <td>fteqcc standard</td>
55                     </tr>
56                     <tr>
57                         <td>qcc</td>
58                         <td>vanila QuakeC standard</td>
59                     </tr>
60                 </table>
61                 <h2>Common compiler options</h2>
62                 <table border="0">
63                     <tr>
64                         <td>Options</td>
65                         <td>What it does</td>
66                     </tr>
67                     <tr>
68                         <td>-l&lt;path&gt;</td>
69                         <td>Adds &lt;path&gt; to the directories searched by the preprocessor for include file resolution.</td>
70                     </tr>
71                     <tr>
72                         <td>-o &lt;file&gt;</td>
73                         <td>Generates the named executable (progs.src) file (when not specified default is progs.src).</td>
74                     </tr>
75                     
76                     <tr>
77                         <td>-O&lt;level&gt;</td>
78                         <td>Specfies the optimization level: highest being 3, lowest being 0 (no optimization).</td>
79                     </tr>
80                     <tr>
81                         <td>-g</td>
82                         <td>Enables generation of debug info for engine backtraces (turns on -flno)</td>
83                     </tr>
84                     <tr>
85                         <td>-E</td>
86                         <td>Instructs the compiler to only preprocess the input, writing the preprocessed output to stdout</td>
87                     </tr>
88                     <tr>
89                         <td>-D</td>
90                         <td>
91                             &quot;define&quot; a macro. Optionally you may supply
92                             a value to the macro with &quot;=&quot;. Implicitally turns on -fftepp
93                         </td>
94                     </tr>
95                     <tr>
96                         <td>-Wall</td>
97                         <td>Enables all compiled warnings for the selcted standard</td>
98                     </tr>
99                     <tr>
100                         <td>-Werror</td>
101                         <td>Instruct the compiler to treat all warnings as errors</td>
102                     </tr>
103                     <tr>
104                         <td>-std=&lt;standard&gt;</td>
105                         <td>Selects the standard dialect</td>
106                     </tr>
107                 </table>
108                 <h3>Predefined Macros</h3>
109                 <table border="0">
110                     <tr>
111                         <td>Macro</td>
112                         <td>What it represents</td>
113                     </tr>
114                     <tr>
115                         <td>__STD_GMQCC__</td>
116                         <td>Specifies the current selected standard is gmqcc.</td>
117                     </tr>
118                     <tr>
119                         <td>__STD_FTEQCC__</td>
120                         <td>Specifies the current selected standard is fteqcc.</td>
121                     </tr>
122                     <tr>
123                         <td>__STD_QCC__</td>
124                         <td>Specifies the current selected standard is qcc.</td>
125                     </tr>
126                     <tr>
127                         <td>GMQCC</td>
128                         <td>Defined always regardless of the selected standard</td>
129                     </tr>
130                     <tr>
131                         <td>__STD_VERSION_MINOR__</td>
132                         <td>Specifies the current selected stanadards minor version number.</td>
133                     </tr>
134                     <tr>
135                         <td>__STD_VERSION_MAJOR__</td>
136                         <td>Specifies the current selected stanadards major version number.</td>
137                     </tr>
138                     <tr>
139                         <td>__FILE__</td>
140                         <td>Expands to a const string literal of the current file (requires -fftepp-predef)</td>
141                     </tr>
142                     <tr>
143                         <td>__LINE__</td>
144                         <td>Expands to the current line number (requires -fftepp-predef)</td>
145                     </tr>
146                     <tr>
147                         <td>__RANDOM__</td>
148                         <td>Expands to a random number between [0, 256) (requires -fftepp-predef)</td>
149                     </tr>
150                     <tr>
151                         <td>__COUNTER__</td>
152                         <td>Expands to a unique number, each expansion causes it to increment (requires -fftepp-predef) </td>
153                     </tr>
154                     <tr>
155                         <td>__RANDOM_LAST__</td>
156                         <td>Expands to the last random number (requires -fftepp-predef)</td>
157                     </tr>
158                     <tr>
159                         <td>__COUNTER_LAST__</td>
160                         <td>Expands to the last counter number (requires -fftepp-predef)</td>
161                     </tr>
162                 </table>
163                 <h3>Unsupported compatability options</h3>
164                 <p>
165                     GMQCC strives hard for compatability with standard dialects, but not all
166                     features of those standards might be implemented. The unsupported features
167                     are presented below:
168                     <table border="0">
169                         <tr>
170                             <td>Feature</td>
171                             <td>Standard</td>
172                         </tr>
173                         <tr>
174                             <td>Inline Assembly</td>
175                             <td>FTEQCC</td>
176                         </tr>
177                         <tr>
178                             <td>Macro expansion in strings</td>
179                             <td>FTEQCC</td>
180                         </tr>
181                     </table>
182                 </p>
183                 <h2>Less common compiler options</h2>
184                 <h3>Code generation options</h3>
185                 <table border="0">
186                     <tr>
187                         <td>Option</td>
188                         <td>What it does</td>
189                     </tr>
190                     <tr>
191                         <td>-foverlap-locals</td>
192                         <td>Reduces codesize by overlapping locals where possible</td>
193                     </tr>
194                     <tr>
195                         <td>-fdarkplaces-string-table-bug</td>
196                         <td>Works around a bug in older Darkplaces engine builds where the stringtable size is computed wrong</td>
197                     </tr>
198                     <tr>
199                         <td>-fadjust-vector-fields</td>
200                         <td>corrects assignment of vector field pointers (STORE_V instead of STORE_FLD)</td>
201                     </tr>
202                     <tr>
203                         <td>-fftepp</td>
204                         <td>Enables FTEQ preprocessor</td>
205                     </tr>
206                     <tr>
207                         <td>-fftepp-predef</td>
208                         <td>Enables additional predefined macros for the FTEQ preprocessor</td>
209                     </tr>
210                     <tr>
211                         <td>-frelaxted-switch</td>
212                         <td>Relaxes switch statement semantics</td>
213                     </tr>
214                     <tr>
215                         <td>-fshort-logic</td>
216                         <td>Enables short circut evaluation/logic</td>
217                     </tr>
218                     <tr>
219                         <td>-fperl-logic</td>
220                         <td>Enables perl evalutaion/logic</td>
221                     </tr>
222                     <tr>
223                         <td>-ftranslatable-strings</td>
224                         <td>Enables translatable strings via .po file</td>
225                     </tr>
226                     <tr>
227                         <td>-finitialized-nonconstants</td>
228                         <td>Prevents initializations from becoming constant unless 'const' is specified as a qualifer</td>
229                     </tr>
230                     <tr>
231                         <td>-fassign-function-types</td>
232                         <td>Allows function types to be assignable even if their signature is invariant</td>
233                     </tr>
234                     <tr>
235                         <td>-flno</td>
236                         <td>Enables generation of progs.lno for engine VM backtraces (enabled with -g as well)</td>
237                     </tr>
238                     <tr>
239                         <td>-fcorrect-ternary</td>
240                         <td>Enabling this corrects the ternary percedecce bugs present in fteqcc</td>
241                     </tr>
242                     <tr>
243                         <td>-fsingle-vector-defs</td>
244                         <td>Prevents the creation of progdefs for vectors</td>
245                     </tr>
246                     <tr>
247                         <td>-fcorrect-logic</td>
248                         <td>Use cast vector to real booleans when used in logic expressions</td>
249                     </tr>
250                     <tr>
251                         <td>-ftrue-empty-strings</td>
252                         <td>Always treat empty strings as true</td>
253                     </tr>
254                     <tr>
255                         <td>-ffalse-empty-strings</td>
256                         <td>Opposite of above, empty strings always false</td>
257                     </tr>
258                     <tr>
259                         <td>-futf8</td>
260                         <td>Recognize utf-8 characters in character constants, and encode codepoint escape sequences in strings as utf-8</td>
261                     </tr>
262                     <tr>
263                         <td>-fbail-on-werror</td>
264                         <td>When a warning is printed and it is set to be treated as error via -Werror, compilation will be stopped.</td>
265                     </tr>
266                     <tr>
267                         <td>-floop-labels</td>
268                         <td>Allow loops and switches to be labeled and break and continue to take optional label to target it.</td>
269                     </tr>
270                     <tr>
271                         <td>-funtyped-nil</td>
272                         <td>Enable the 'nil' null constant, which has no type.  It can be used as the right hand of any assignment.</td>
273                     </tr>
274                     <tr>
275                         <td>-fpermissive</td>
276                         <td>Be "permissive", e.g with -funtyped-nil, this will allow local variables with the name 'nil'</td>
277                     </tr>
278                 </table>
279                 <h3>Warning options</h3>
280                 <table border="0">
281                     <tr>
282                         <td>Option</td>
283                         <td>What it does</td>
284                     </tr>
285                     <tr>
286                         <td>-Wunused-uninitialized</td>
287                         <td>Enables warnings about unused or uninitialized variables</td>
288                     </tr>
289                     <tr>
290                         <td>-Wunknwon-control-sequence</td>
291                         <td>Enables warnings about unknown control sequences</td>
292                     </tr>
293                     <tr>
294                         <td>-Wextension</td>
295                         <td>Enables warnings about the use of (an) extension(s)</td>
296                     </tr>
297                     <tr>
298                         <td>-Wfield-redeclared</td>
299                         <td>Enables warnings about redeclared fields</td>
300                     </tr>
301                     <tr>
302                         <td>-Wmissing-return-values</td>
303                         <td>Enables warnings about missing return values</td>
304                     </tr>
305                     <tr>
306                         <td>-Wtoo-few-paramaters</td>
307                         <td>Enables warnings about missing paramaters for function calls</td>
308                     </tr>
309                     <tr>
310                         <td>-Wlocal-shadows</td>
311                         <td>Enables warnings about locals shadowing paramaters or other locals</td>
312                     </tr>
313                     <tr>
314                         <td>-Wlocal-constants</td>
315                         <td>Enables warnings about constants specified as locals</td>
316                     </tr>
317                     <tr>
318                         <td>-Wvoid-variables</td>
319                         <td>Enables warnings about variables declared as type void</td>
320                     </tr>
321                     <tr>
322                         <td>-Wimplicit-function-pointer</td>
323                         <td>Enables warnings about implicitly declared function pointers</td>
324                     </tr>
325                     <tr>
326                         <td>-Wvariadic-function</td>
327                         <td>Enables warnings for use of varadics for non-builtin functions</td>
328                     </tr>
329                     <tr>
330                         <td>-Wframe-macros</td>
331                         <td>Enables warnings about duplicated frame macros</td>
332                     </tr>
333                     <tr>
334                         <td>-Weffectless-statement</td>
335                         <td>Enables warnings about effectiveless statements</td>
336                     </tr>
337                     <tr>
338                         <td>-Wend-sys-field</td>
339                         <td>Enables warnings of end_sys_fields being declared a field</td>
340                     </tr>
341                     <tr>
342                         <td>-Wassign-function-types</td>
343                         <td>Enables warnings for incompatible function pointer signatures used in assignment</td>
344                     </tr>
345                     <tr>
346                         <td>-Wpreprocessor</td>
347                         <td>Enables warnings about redefined macros</td>
348                     </tr>
349                     <tr>
350                         <td>-Wmultifile-if</td>
351                         <td>Enables warnings about multifile if statements</td>
352                     </tr>
353                     <tr>
354                         <td>-Wdouble-declaration</td>
355                         <td>Enables warnings about double declarations</td>
356                     </tr>
357                     <tr>
358                         <td>-Wconst-var</td>
359                         <td>Enables warnings about 'const var' and 'var const'</td>
360                     </tr>
361                     <tr>
362                         <td>-Wmultibyte-character</td>
363                         <td>Enables warnings about use of multibyte characters</td>
364                     </tr>
365                     <tr>
366                         <td>-Wternary-precedence</td>
367                         <td>Enables warnings about ternary expressions whos precedence may be not what expected</td>
368                     </tr>
369                     <tr>
370                         <td>-Wunknown-pragmas</td>
371                         <td>Enables warnings about unknown pragmas</td>
372                     </tr>
373                     <tr>
374                         <td>-Wunreachable-code</td>
375                         <td>Enables warnings about unreachable code</td>
376                     </tr>
377                     <tr>
378                         <td>-Wcpp</td>
379                         <td>Enables warnings about the preprocessor</td>
380                     </tr>
381                     <tr>
382                         <td>Wunknown-attribute</td>
383                         <td>Enables warnings for when an unknown attribute is encountered.</td>
384                     </tr>
385                     <tr>
386                         <td>-Wreserved-names</td>
387                         <td>Enables warnings for variables or fields that are named with a reserved name</td>
388                     </tr>
389                     <tr>
390                         <td>-Wuninitialized-constant</td>
391                         <td>Enables warnings about const global variables with no initializing value</td>
392                     </tr>
393                     <tr>
394                         <td>-Wuninitialized-global</td>
395                         <td>Enables warnings about non-const gloal variable with no initializing value</td>
396                     </tr>
397                     <tr>
398                         <td>-Wdeprecated</td>
399                         <td>Enables warnings about calls to functions marked deprecated</td>
400                     </tr>
401                 </table>
402                 <table border="0">
403                     <tr><td>Options</td><td>What it does</td></tr>
404                     <tr>
405                         <td>-Opeephole</td>
406                         <td>Enables peephole optimizations</td>
407                     </tr>
408                     <tr>
409                         <td>-Olocal-temps</td>
410                         <td>Enables local-temp omission optimizations</td>
411                     </tr>
412                     <tr>
413                         <td>-Oglobal-temps</td>
414                         <td>Enables global-temp omission optimizations</td>
415                     </tr>
416                     <tr>
417                         <td>-Otail-recursion</td>
418                         <td>Enables tail recursion optimization</td>
419                     </tr>
420                     <tr>
421                         <td>-Otail-calls</td>
422                         <td>Enables tail-call optimizations</td>
423                     </tr>
424                     <tr>
425                         <td>-Ooverlap-locals</td>
426                         <td>
427                             Every function where it's safe to do so will share its local
428                             section with others.  The critera being that the function must
429                             have any possibly uninitialized locals, or local arrays regardless
430                             of how they are initialized.
431                         </td>
432                     </tr>
433                     <tr>
434                         <td>-Ostrip-constant-names</td>
435                         <td>Strip the names of constants</td>
436                     </tr>
437                     <tr>
438                         <td>-Ooverlap-strings</td>
439                         <td>Agressivly reuse strings in the string-section.</td>
440                     </tr>
441                     <tr>
442                         <td>-Ocall-stores</td>
443                         <td>
444                             Have expressions which are used as function parameters evaluate directly
445                             into the parameter-globals if possible.  This avoids copying.
446                         </td>
447                     </tr>
448                     <tr>
449                         <td>-Ovoid-return</td>
450                         <td>Do not create a return instruction at the end of return-type void functions</td>
451                     </tr>
452                 </table>
453                 <p>
454                     Individual warnings may be disabled with &nbsp;-Wno-&lt;warning&gt;
455                     <pre>$ gmqcc -Wno-frame-macros # disables frame duplication warning</pre>
456                 </p>
457                 <h3>Miscellaneous options</h3>
458                 <table border="0">
459                     <tr>
460                         <td>Option</td>
461                         <td>What it does</td>
462                     </tr>
463                     <tr>
464                         <td>-force-crc=&lt;num&gt;</td>
465                         <td>Forces a specific checsum into the header</td>
466                     </tr>
467                     <tr>
468                         <td>-debug</td>
469                         <td>Turns on compiler debug messages</td>
470                     </tr>
471                     <tr>
472                         <td>-memchk</td>
473                         <td>Turns on compiler memory leak checker</td>
474                     </tr>
475                     <tr>
476                         <td>-dump</td>
477                         <td>Dump IR before optimizing and finalizing</td>
478                     </tr>
479                     <tr>
480                         <td>-dumpfin</td>
481                         <td>Dump IR after optimizing and finalizing</td>
482                     </tr>
483                     <tr>
484                         <td>-Whelp or -W?</td>
485                         <td>Lists all warning options</td>
486                     </tr>
487                     <tr>
488                         <td>-fhelp or -f?</td>
489                         <td>Lists all code generation options</td>
490                     </tr>
491                     <tr>
492                         <td>-redirout=&lt;file&gt;</td>
493                         <td>Redirect stdout to any file.</td>
494                     </tr>
495                     <tr>
496                         <td>-redirerr=&lt;file&gt;</td>
497                         <td>Redirect stderr to any file.</td>
498                     </tr>
499                     <tr>
500                         <td>-nocolor</td>
501                         <td>Turn off colored stdout/stderr.</td>
502                     </tr>
503                     <tr>
504                         <td>-config=&lt;file&gt;</td>
505                         <td>
506                             Supply a configuration file to set options.
507                             Note: If a file named <b>gmqcc.ini</b> or
508                             <b>gmqcc.cfg</b> is found it will be loaded
509                             implicitally.
510                         </td>
511                     </tr>
512                 </table>
513                 
514                 <h1><a name="bdoc">Building Documentation</a></h1>
515                 <h2>Building on BSD/NIX</h2>
516                 <p>
517                     To compile GMQCC on BSD/NIX the following things are
518                     required:
519                     
520                     <ul>
521                         <li>GIT</li>
522                         <li>Make</li>
523                         <li>Any C90+ C compiler</li>
524                     </ul>
525                     
526                     Once obtained you may checkout the development repository
527                     with the following shell commands
528                     
529 <pre>$ git clone git://github.com/graphitemaster/gmqcc.git
530 $ cd gmqcc
531 </pre>
532
533                     The Makefile contains a few rules, depending on what you
534                     want to compile, the following rules are:
535                     
536                     <table border="0">
537                         <tr>
538                             <td>Rule</td>
539                             <td>What it does</td>
540                         </tr>
541                         <tr>
542                             <td>gmqcc</td>
543                             <td>Builds the gmqcc compiler</td>
544                         </tr>
545                         <tr>
546                             <td>qcvm</td>
547                             <td>Builds a standable QuakeC VM</td>
548                         </tr>
549                         <tr>
550                             <td>testsuite</td>
551                             <td>Builds the testsuite for GMQCC</td>
552                         </tr>
553                         <tr>
554                             <td>check, test</td>
555                             <td>Build and executes the testsuite for GMQCC</td>
556                         </tr>
557                         <tr>
558                             <td>pak</td>
559                             <td>Builds the pak utility</td>
560                         </tr>
561                         <tr>
562                             <td>splint</td>
563                             <td>Runs splint (static analysis) on the source</td>
564                         </tr>
565                         <tr>
566                             <td>gource</td>
567                             <td>Runs gource visualization on the source</td>
568                         </tr>
569                         <tr>
570                             <td>gource-record</td>
571                             <td>Runs gource visualization and produces a rendered mp4</td>
572                         </tr>
573                         <tr>
574                             <td>depend</td>
575                             <td>Builds dependinces into the Makefile</td>
576                         </tr>
577                         <tr>
578                             <td>all</td>
579                             <td>Builds gmqcc, qcvm, pak, and testsuite</td>
580                         </tr>
581                         <tr>
582                             <td>install</td>
583                             <td>Installs gmqcc, qcvm, and documentaion</td>
584                         </tr>
585                         <tr>
586                             <td>uninstall</td>
587                             <td>Uninstalls gmqcc, qcvm, and documentation</td>
588                         </tr>
589                         <tr>
590                             <td>check</td>
591                             <td>Runs the testsuite to verify correctness</td>
592                         </tr>
593                     </table>
594                 </p>
595                 <h2>Building on Windows</h2>
596                 <p>
597                     To compile GMQCC on windows the following things are
598                     required:
599                     
600                     <ul>
601                         <li><a href="http://msysgit.googlecode.com/files/Git-1.8.0-preview20121022.exe">msysGit</a></li>
602                         <li><a href="http://www.microsoft.com/visualstudio/eng/downloads">Visual Studio</a></li>
603                     </ul>
604                     
605                     Once obtained you may checkout the development repository
606                     with the following msysGit commands from a msysGit shell.
607                     <pre>$ git clone git://github.com/graphitemaster/gmqcc.git</pre>
608                     Included is a VS project file.
609                 </p>
610                 
611                 <h1><a name="tdoc">Testsuite Documentation</a></h1>
612                 <h2>Running The Testsuite</h2>
613                 <p>
614                     To run the testsuite you can either use
615                     <pre>$ make check</pre>
616                     Or if you're on windows or have already compiled the
617                     testsuite from source:
618                     <pre>$ ./testsuite </pre>
619                     
620                     Optionally you may provide the testsuite with additional
621                     arguments:
622                     
623                     <table border="0">
624                         <tr>
625                             <td>Argument</td>
626                             <td>What it does</td>
627                         </tr>
628                         <tr>
629                             <td>-redirout=&lt;file&gt;</td>
630                             <td>Redirect stdout to any file.</td>
631                         </tr>
632                         <tr>
633                             <td>-redirerr=&lt;file&gt;</td>
634                             <td>Redirect stderr to any file.</td>
635                         </tr>
636                         <tr>
637                             <td>-debug</td>
638                             <td>Turn on testsuite debug messages.</td>
639                         </tr>
640                         <tr>
641                             <td>-memchk</td>
642                             <td>Turn on testsuite memleak checker.</td>
643                         </tr>
644                         <tr>
645                             <td>-nocolor</td>
646                             <td>Turn off colored stdout/stderr.</td>
647                         </tr>
648                     </table>
649                 </p>
650                 <h2>Writing Tests</h2>
651                 <p>
652                     GMQCC comes with a complete testsuite for verifying semantics
653                     and syntatics.  The testsuite executes files from the test/
654                     directory, by reading task template files.
655                 </p>
656                 <p>
657                    templates are rules for a specific test, used to create a "task" that
658                    is executed with those set of rules (arguments, and what not). Tests
659                    that don't have a template with them cannot become tasks, since without
660                    the information for that test there is no way to properly "test" them.
661                    Rules for these templates are described in a template file, using a
662                    task template language.
663                 </p>
664                 <p>
665                    The languge is composed entierly of "tags" which describe a string of
666                    text for a task.  Think of it much like a configuration file.  Except
667                    it's been designed to allow flexibility and future support for prodecual
668                    semantics.
669                 <p>
670                 <p>
671                    The following "tags" are suported by the language:
672                 </p>
673                 <table border="0">
674                     <tr>
675                         <td>Tag</td>
676                         <td>Description of what the tag does</td>
677                     </tr>
678                     <tr>
679                        <td>D:</td>
680                          <td>Used to set a description of the current test, this must be
681                            provided, this tag is NOT optional.</td>
682                     </tr>
683                     <tr>
684                         <td>F:</td>
685                          <td>Used to set test-suite specific flags, currently
686                             the only supported flag is -no-defs which tells the
687                             testsuite to exclude defs.qh.
688                         </td>
689                     </tr>
690                     <tr>
691                        <td>T:</td>
692                             <td>Used to set the procedure for the given task, there are four
693                            options for this:
694                            <ul>
695                                <li>-compile&nbsp;
696                                    This simply performs compilation only</li>
697                                <li>-execute&nbsp;
698                                    This will perform compilation and execution</li>
699                                <li>-fail&nbsp;
700                                    This will perform compilation on the requirement it fails, otherwise
701                                    the test fails</li>
702                                 <li>-pp&nbsp;
703                                     This will perform preprocessing only</li>
704                             </ul>
705                   
706                            This tag must be provided, this tag is NOT optional.
707                            </td>
708                     </tr>
709                     <tr>
710                        <td>C:</td>
711                         <td>Used to set the compilation flags for the given task, this
712                            must be provided, this tag is NOT optional.</td>
713                     </tr>
714                     <tr>
715                        <td>E:</td>
716                         <td>Used to set the execution flags for the given task. This tag
717                            must be provided if T == -execute, otherwise it's erroneous
718                            as compilation only takes place.</td>
719                     </tr>
720                     <tr>
721                        <td>M:</td>
722                         <td>Used to describe a string of text that should be matched from
723                            the output of executing the task.  If this doesn't match the
724                            task fails.  This tag must be provided at least once if
725                            T == -execute or T == -pp, otherwise it's erroneous as compilation only
726                            takes place. Multiple M tags are required for multi-line comparision
727                         </td>
728                     </tr>
729                     <tr>
730                        <td>I:</td>
731                        <td>Used to specify the INPUT source file to operate on, this must be
732                        provided, this tag is NOT optional</td>
733                     </tr>
734                  </table>
735                 <h3>Notes</h3>
736                 <p>
737                    These tags (with exception to M) have one-time use, using them more
738                    than once will result in template compilation errors,
739                 </p>
740                 <p>
741                    Lines beginning with # or // in the template file are comments and
742                    are ignored by the template parser.
743                    Whitespace is optional, with exception to the colon ':' between the
744                    tag and it's assignment value.
745                 </p>
746                    The template compiler will detect erronrous tags (optional tags
747                    that need not be set), as well as missing tags, and error accordingly
748                    which will result in that task failing.
749                 </p>
750                 <h1><a name="vdoc">Quake C Virtual Machine Documentation</a></h1>
751                 <p>
752                     Included with GMQCC is a minimal implementation of the QCVM used in many game
753                     engines.  It's primarly used for the testsuite, but you may also use it as a
754                     standalone runtime, or even embed it with existing appliciations.
755                 </p>
756                 <h2>Running The Standalone VM</h2>
757                 <p>
758                     To run the standalone application you need to have a compiled progs.dat, with an
759                     entry function named &nbsp;main&nbsp;  The main function can have any amount of arguments
760                     as the standalone executor allows main to be invoked with your choice of arguments.
761                     An example of invoking the VM:
762                     <pre>$ ./qcvm progs.dat -float 200 #execute passing in 200 as a float to main</pre>
763                     If &nbsp;main&nbsp; doesn't require arguments:
764                     <pre>$ ./qcvm progs.dat #call main with no arguments</pre>
765                     
766                     The standalone executor supports the following arguments for passing arguments to &nbsp;main&nbsp
767                     
768                     <table border="0">
769                         <tr>
770                             <td>Argument</td>
771                             <td>What it does</td>
772                         </tr>
773                         <tr>
774                             <td>-string</td>
775                             <td>Passes in a string to main</td>
776                         </tr>
777                         <tr>
778                             <td>-float</td>
779                             <td>Passes in a float to main</td>
780                         </tr>
781                         <tr>
782                             <td>-vector</td>
783                             <td>Passes in a vector to main</td>
784                         </tr>
785                     </table>
786                     
787                     The order in which the arguments are expected for main, must be preserved, for
788                     example if &nbsp;main&nbsp;'s signature is the following:
789                     <pre>void main(float a, vector b)</pre>
790                     
791                     Then to pass the arguments you'd use the same order:
792                     <pre>$ ./qcvm -float 200 -vector '1 2 3'</pre>
793                     
794                     <h3>Additional Arguments</h3>
795                     The standalone virtual machine has the following optional command line arguments:
796                     <table border="0">
797                         <tr>
798                             <td>Argument</td>
799                             <td>What it does</td>
800                         </tr>
801                         <tr>
802                             <td>-h, --help</td>
803                             <td>Print help message</td>
804                         </tr>
805                         <tr>
806                             <td>-trace</td>
807                             <td>Trace the execution call hierarchy.</td>
808                         </tr>
809                         <tr>
810                             <td>-profile</td>
811                             <td>Profile the bytecode to find hotspots.</td>
812                         </tr>
813                         <tr>
814                             <td>-info</td>
815                             <td>Get info of the running bytecode.</td>
816                         </tr>
817                         <tr>
818                             <td>-disasm</td>
819                             <td>Dissasemble the bytecode into assembly.</td>
820                         </tr>
821                         <tr>
822                             <td>-diasm-func</td>
823                             <td>Dissasmble function</td>
824                         </tr>
825                         <tr>
826                             <td>-printdefs</td>
827                             <td>Prints all definitions for the bytecode running.</td>
828                         </tr>
829                         <tr>
830                             <td>-printfields</td>
831                             <td>Prints all fields for the bytecode running.</td>
832                         </tr>
833                         <tr>
834                             <td>-printfuns</td>
835                             <td>Prints all functions for the bytecode running.</td>
836                         </tr>
837                         <tr>
838                             <td>-v</td>
839                             <td>Be verbose</td>
840                         </tr>
841                         <tr>
842                             <td>-v</td>
843                             <td>Be even more verbose</td>
844                         </tr>
845                         <tr>
846                             <td>-version, --version</td>
847                             <td>Print version information</td>
848                         </tr>
849                     </table>
850                     
851                     <h3>Builtins</h3>
852                     The standalone virtual machine includes the following builtins.
853                     <table border="0">
854                         <tr>
855                             <td>Builtin</td>
856                             <td>Number</td>
857                         </tr>
858                             <tr><td>print</td><td>1</td></tr>
859                             <tr><td>ftos</td><td>2</td></tr>
860                             <tr><td>spawn</td><td>3</td></tr>
861                             <tr><td>kill</td><td>4</td></tr>
862                             <tr><td>vtos</td><td>5</td></tr>
863                             <tr><td>error</td><td>6</td></tr>
864                             <tr><td>vlen</td><td>7</td></tr>
865                             <tr><td>etos</td><td>8</td></tr>
866                             <tr><td>stof</td><td>9</td></tr>
867                             <tr><td>strcat</td><td>10</td></tr>
868                             <tr><td>strcmp</td><td>11</td></tr>
869                             <tr><td>normalize</td><td>12</td></tr>
870                             <tr><td>sqrt</td><td>13</td></tr>
871                             <tr><td>floor</td><td>14</td></tr>
872                     </table>
873                 </p>
874                 <h3>Support or Contact</h3>
875                 <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> 
876             </section>
877             <footer>
878                 <script type="text/javascript" src="http://www.ohloh.net/p/602517/widgets/project_partner_badge.js"></script>
879             </footer>
880         </div>
881         <!--[if !IE]><script>fixScale(document);</script><![endif]-->
882     </body>
883 </html>