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="download"><a href="https://github.com/graphitemaster/gmqcc/zipball/master">Download ZIP</a></li>
  25                     <li class="download"><a href="https://github.com/graphitemaster/gmqcc/tarball/master">Download TAR</a></li>
  26                     <li class="buttons"><a href="https://github.com/graphitemaster/gmqcc/issues">Issues</a></li>
  27                     <li class="buttons"><a href="doc.html">Documentation</a></li>
  28                     <li class="buttons"><a href="https://github.com/graphitemaster/gmqcc">View On GitHub</a></li>
  29                 </ul>
  30             </header>
  31             <section>
  32                 <ul class="wiki">
  33                     <li class="wiki"><a class="wiki" href="#cdoc">Compiler Documentation</a></li>
  34                     <li class="wiki"><a class="wiki" href="#bdoc">Building Documentation</a></li>
  35                     <li class="wiki"><a class="wiki" href="#tdoc">Testsuite Documentation</a></li>
  36                     <li class="wiki"><a class="wiki" href="#vdoc">Virtual Machine Documentation</a></li>
  37                 </ul>
  38                 <h1><a name="cdoc">Compiler Documentation</a></h1>
  39                 <h3>Defaults Flag</h3>
  40                 <p>
  41                     The <i>-show-defaults</i> flag instructs the compiler to print out the defaults used related to
  42                     the standard, optimization, and code generation.  When this flag is specified, the compiler
  43                     will just print the defaults and quit.  No compilation is performed.
  44                 </p>
  45                 <pre>$ gmqcc -show-defaults</pre>
  46                 <h3>Compiling for an alternitive standard</h3>
  47                 To compile with a different dialect of the QuakeC programming language the <i>-std</i>
  48                 flag can be instructed to select one of the following options:
  49                 <table border="0">
  50                     <tr>
  51                         <td>gmqcc</td>
  52                         <td>default standard</td>
  53                     </tr>
  54                     <tr>
  55                         <td>fteqcc</td>
  56                         <td>fteqcc standard</td>
  57                     </tr>
  58                     <tr>
  59                         <td>qcc</td>
  60                         <td>vanila QuakeC standard</td>
  61                     </tr>
  62                 </table>
  63                 <h2>Common compiler options</h2>
  64                 <table border="0">
  65                     <tr>
  66                         <td>Options</td>
  67                         <td>What it does</td>
  68                     </tr>
  69                     <tr>
  70                         <td>-l&lt;path&gt;</td>
  71                         <td>Adds &lt;path&gt; to the directories searched by the preprocessor for include file resolution.</td>
  72                     </tr>
  73                     <tr>
  74                         <td>-o &lt;file&gt;</td>
  75                         <td>Generates the named executable (progs.src) file (when not specified default is progs.src).</td>
  76                     </tr>
  77
  78                     <tr>
  79                         <td>-O&lt;level&gt;</td>
  80                         <td>Specfies the optimization level: highest being 3, lowest being 0 (no optimization).</td>
  81                     </tr>
  82                     <tr>
  83                         <td>-E</td>
  84                         <td>Instructs the compiler to only preprocess the input, writing the preprocessed output to stdout</td>
  85                     </tr>
  86                     <tr>
  87                         <td>-Wall</td>
  88                         <td>Enables all compiled warnings for the selcted standard</td>
  89                     </tr>
  90                     <tr>
  91                         <td>-Werror</td>
  92                         <td>Instruct the compiler to treat all warnings as errors</td>
  93                     </tr>
  94                     <tr>
  95                         <td>-std=&lt;standard&gt;</td>
  96                         <td>Selects the standard dialect</td>
  97                     </tr>
  98                 </table>
  99                 <h3>Predefined Macros</h3>
 100                 <table border="0">
 101                     <tr>
 102                         <td>Macro</td>
 103                         <td>What it represents</td>
 104                     </tr>
 105                     <tr>
 106                         <td>GMQCC</td>
 107                         <td>Specifies the current selected standard is gmqcc.</td>
 108                     </tr>
 109                     <tr>
 110                         <td>FTEQCC</td>
 111                         <td>Specifies the current selected standard is fteqcc.</td>
 112                     </tr>
 113                     <tr>
 114                         <td>QCC</td>
 115                         <td>Specifies the current selected standard is qcc.</td>
 116                     </tr>
 117
 118                     <tr>
 119                         <td>__STD_VERSION_MINOR__</td>
 120                         <td>Specifies the current selected stanadards minor version number.</td>
 121                     </tr>
 122                     <tr>
 123                         <td>__STD_VERSION_MAJOR__</td>
 124                         <td>Specifies the current selected stanadards major version number.</td>
 125                     </tr>
 126                 </table>
 127                 <h3>Unsupported compatability options</h3>
 128                 <p>
 129                     GMQCC strives hard for compatability with standard dialects, but not all
 130                     features of those standards might be implemented. The unsupported features
 131                     are presented below:
 132                     <table border="0">
 133                         <tr>
 134                             <td>Feature</td>
 135                             <td>Standard</td>
 136                         </tr>
 137                         <tr>
 138                             <td>Inline Assembly</td>
 139                             <td>FTEQCC</td>
 140                         </tr>
 141                         <tr>
 142                             <td>Macro expansion in strings</td>
 143                             <td>FTEQCC</td>
 144                         </tr>
 145                     </table>
 146                 </p>
 147                 <h2>Less common compiler options</h2>
 148                 <h3>Code generation options</h3>
 149                 <table border="0">
 150                     <tr>
 151                         <td>Option</td>
 152                         <td>What it does</td>
 153                     </tr>
 154                     <tr>
 155                         <td>-foverlap-locals</td>
 156                         <td>Reduces codesize by overlapping locals where possible</td>
 157                     </tr>
 158                     <tr>
 159                         <td>-fdarkplaces-string-table-bug</td>
 160                         <td>Works around a bug in older Darkplaces engine builds where the stringtable size is computed wrong</td>
 161                     </tr>
 162                     <tr>
 163                         <td>-fadjust-vector-fields</td>
 164                         <td>corrects assignment of vector field pointers (STORE_V instead of STORE_FLD)</td>
 165                     </tr>
 166                     <tr>
 167                         <td>-fftepp</td>
 168                         <td>Enables FTEQ preprocessor</td>
 169                     </tr>
 170                     <tr>
 171                         <td>-frelaxted-switch</td>
 172                         <td>Relaxes switch statement semantics</td>
 173                     </tr>
 174                     <tr>
 175                         <td>-fshort-logic</td>
 176                         <td>Enables short circut evaluation/logic</td>
 177                     </tr>
 178                     <tr>
 179                         <td>-fperl-logic</td>
 180                         <td>Enables perl evalutaion/logic</td>
 181                     </tr>
 182                 </table>
 183                 <h3>Warning options</h3>
 184                 <table border="0">
 185                     <tr>
 186                         <td>Option</td>
 187                         <td>What it does</td>
 188                     </tr>
 189                     <tr>
 190                         <td>-Wunused-uninitialized</td>
 191                         <td>Enables warnings about unused or uninitialized variables</td>
 192                     </tr>
 193                     <tr>
 194                         <td>-Wunknwon-control-sequence</td>
 195                         <td>Enables warnings about unknown control sequences</td>
 196                     </tr>
 197                     <tr>
 198                         <td>-Wextension</td>
 199                         <td>Enables warnings about the use of (an) extension(s)</td>
 200                     </tr>
 201                     <tr>
 202                         <td>-Wfield-redeclared</td>
 203                         <td>Enables warnings about redeclared fields</td>
 204                     </tr>
 205                     <tr>
 206                         <td>-Wmissing-return-values</td>
 207                         <td>Enables warnings about missing return values</td>
 208                     </tr>
 209                     <tr>
 210                         <td>-Wtoo-few-paramaters</td>
 211                         <td>Enables warnings about missing paramaters for function calls</td>
 212                     </tr>
 213                     <tr>
 214                         <td>-Wlocal-shadows</td>
 215                         <td>Enables warnings about locals shadowing paramaters or other locals</td>
 216                     </tr>
 217                     <tr>
 218                         <td>-Wlocal-constants</td>
 219                         <td>Enables warnings about constants specified as locals</td>
 220                     </tr>
 221                     <tr>
 222                         <td>-Wvoid-variables</td>
 223                         <td>Enables warnings about variables declared as type void</td>
 224                     </tr>
 225                     <tr>
 226                         <td>-Wimplicit-function-pointer</td>
 227                         <td>Enables warnings about implicitly declared function pointers</td>
 228                     </tr>
 229                     <tr>
 230                         <td>-Wvariadic-function</td>
 231                         <td>Enables warnings for use of varadics for non-builtin functions</td>
 232                     </tr>
 233                     <tr>
 234                         <td>-Wframe-macros</td>
 235                         <td>Enables warnings about duplicated frame macros</td>
 236                     </tr>
 237                     <tr>
 238                         <td>-Weffectless-statement</td>
 239                         <td>Enables warnings about effectiveless statements</td>
 240                     </tr>
 241                     <tr>
 242                         <td>-Wend-sys-field</td>
 243                         <td>Enables warnings of end_sys_fields being declared a field</td>
 244                     </tr>
 245                     <tr>
 246                         <td>-Wassign-function-types</td>
 247                         <td>Enables warnings for incompatible function pointer signatures used in assignment</td>
 248                     </tr>
 249                     <tr>
 250                         <td>-Wpreprocessor</td>
 251                         <td>Enables warnings about redefined macros</td>
 252                     </tr>
 253                     <tr>
 254                         <td>-Wmultifile-if</td>
 255                         <td>Enables warnings about multifile if statements</td>
 256                     </tr>
 257                 </table>
 258                 <p>
 259                     Individual warnings may be disabled with &nbsp;-Wno&lt;warning&gt;
 260                     <pre>$ gmqcc -Wno-frame-macros # disables frame duplication warning</pre>
 261                 </p>
 262                 <h3>Miscellaneous options</h3>
 263                 <table border="0">
 264                     <tr>
 265                         <td>Option</td>
 266                         <td>What it does</td>
 267                     </tr>
 268                     <tr>
 269                         <td>-force-crc=&lt;num&gt;</td>
 270                         <td>Forces a specific checsum into the header</td>
 271                     </tr>
 272                     <tr>
 273                         <td>-debug</td>
 274                         <td>Turns on compiler debug messages</td>
 275                     </tr>
 276                     <tr>
 277                         <td>-memchk</td>
 278                         <td>Turns on compiler memory leak checker</td>
 279                     </tr>
 280
 281                     <tr>
 282                         <td>-Whelp or -W?</td>
 283                         <td>Lists all warning options</td>
 284                     </tr>
 285
 286                     <tr>
 287                         <td>-fhelp or -f?</td>
 288                         <td>Lists all code generation options</td>
 289                     </tr>
 290                 </table>
 291
 292                 <h1><a name="bdoc">Building Documentation</a></h1>
 293                 <h2>Building on BSD/NIX</h2>
 294                 <p>
 295                     To compile GMQCC on BSD/NIX the following things are
 296                     required:
 297
 298                     <ul>
 299                         <li>GIT</li>
 300                         <li>Make</li>
 301                         <li>Any C90+ C compiler</li>
 302                     </ul>
 303
 304                     Once obtained you may checkout the development repository
 305                     with the following shell commands
 306
 307 <pre>$ git clone git://github.com/graphitemaster/gmqcc.git
 308 $ cd gmqcc
 309 </pre>
 310
 311                     The Makefile contains a few rules, depending on what you
 312                     want to compile, the following rules are:
 313
 314                     <table border="0">
 315                         <tr>
 316                             <td>Rule</td>
 317                             <td>What it does</td>
 318                         </tr>
 319                         <tr>
 320                             <td>gmqcc</td>
 321                             <td>Builds the gmqcc compiler</td>
 322                         </tr>
 323                         <tr>
 324                             <td>qcvm</td>
 325                             <td>Builds a standable QuakeC VM</td>
 326                         </tr>
 327                         <tr>
 328                             <td>testsuite</td>
 329                             <td>Builds the testsuite for GMQCC</td>
 330                         </tr>
 331                         <tr>
 332                             <td>all</td>
 333                             <td>Builds gmqcc, qcvm, and testsuite</td>
 334                         </tr>
 335                         <tr>
 336                             <td>install</td>
 337                             <td>Installs gmqcc to /usr/local/</td>
 338                         </tr>
 339                         <tr>
 340                             <td>check</td>
 341                             <td>Runs the testsuite to verify correctness</td>
 342                         </tr>
 343                     </table>
 344                 </p>
 345                 <h2>Building on Windows</h2>
 346                 <p>
 347                     To compile GMQCC on windows the following things are
 348                     required:
 349
 350                     <ul>
 351                         <li><a href="http://msysgit.googlecode.com/files/Git-1.8.0-preview20121022.exe">msysGit</a></li>
 352                         <li><a href="http://www.microsoft.com/visualstudio/eng/downloads">Visual Studio</a></li>
 353                     </ul>
 354
 355                     Once obtained you may checkout the development repository
 356                     with the following msysGit commands from a msysGit shell.
 357                     <pre>$ git clone git://github.com/graphitemaster/gmqcc.git</pre>
 358                     Included is a VS project file.
 359                 </p>
 360
 361                 <h1><a name="tdoc">Testsuite Documentation</a></h1>
 362                 <h2>Running The Testsuite</h2>
 363                 <p>
 364                     To run the testsuite you can either use
 365                     <pre>$ make check</pre>
 366                     Or if you're on windows or have already compiled the
 367                     testsuite from source:
 368                     <pre>$ ./testsuite </pre>
 369
 370                     Optionally you may provide the testsuite with additional
 371                     arguments:
 372
 373                     <table border="0">
 374                         <tr>
 375                             <td>Argument</td>
 376                             <td>What it does</td>
 377                         </tr>
 378                         <tr>
 379                             <td>-redirout=&lt;file&gt;</td>
 380                             <td>Redirect stdout to any file.</td>
 381                         </tr>
 382                         <tr>
 383                             <td>-redirerr=&lt;file&gt;</td>
 384                             <td>Redirect stderr to any file.</td>
 385                         </tr>
 386                         <tr>
 387                             <td>-debug</td>
 388                             <td>Turn on testsuite debug messages.</td>
 389                         </tr>
 390                         <tr>
 391                             <td>-memchk</td>
 392                             <td>Turn on testsuite memleak checker.</td>
 393                         </tr>
 394                         <tr>
 395                             <td>-nocolor</td>
 396                             <td>Turn off colored stdout/stderr.</td>
 397                         </tr>
 398                     </table>
 399                 </p>
 400                 <h2>Writing Tests</h2>
 401                 <p>
 402                     GMQCC comes with a complete testsuite for verifying semantics
 403                     and syntatics.  The testsuite executes files from the test/
 404                     directory, by reading task template files.
 405                 </p>
 406                 <p>
 407                    templates are rules for a specific test, used to create a "task" that
 408                    is executed with those set of rules (arguments, and what not). Tests
 409                    that don't have a template with them cannot become tasks, since without
 410                    the information for that test there is no way to properly "test" them.
 411                    Rules for these templates are described in a template file, using a
 412                    task template language.
 413                 </p>
 414                 <p>
 415                    The languge is composed entierly of "tags" which describe a string of
 416                    text for a task.  Think of it much like a configuration file.  Except
 417                    it's been designed to allow flexibility and future support for prodecual
 418                    semantics.
 419                 <p>
 420                 <p>
 421                    The following "tags" are suported by the language:
 422                 </p>
 423                 <table border="0">
 424                     <tr>
 425                         <td>Tag</td>
 426                         <td>Description of what the tag does</td>
 427                     </tr>
 428                     <tr>
 429                        <td>D:</td>
 430                          <td>Used to set a description of the current test, this must be
 431                            provided, this tag is NOT optional.</td>
 432                     </tr>
 433                     <tr>
 434                         <td>F:</td>
 435                          <td>Used to set a failure message, this message will be displayed
 436                            if the test fails, this tag is optional.</td>
 437                     </tr>
 438                     <tr>
 439                         <td>S:</td>
 440                             <td>Used to set a success message, this message will be displayed
 441                            if the test succeeds, this tag is optional.
 442                            </td>
 443                     </tr>
 444                     <tr>
 445                        <td>T:</td>
 446                             <td>Used to set the procedure for the given task, there are two
 447                            options for this:
 448                            <ul>
 449                                <li>-compile&nbsp;
 450                                    This simply performs compilation only</li>
 451                                <li>-execute&nbsp;
 452                                    This will perform compilation and execution</li>
 453                             </ul>
 454
 455                            This tag must be provided, this tag is NOT optional.
 456                            </td>
 457                     </tr>
 458                     <tr>
 459                        <td>C:</td>
 460                         <td>Used to set the compilation flags for the given task, this
 461                            must be provided, this tag is NOT optional.</td>
 462                     </tr>
 463                     <tr>
 464                        <td>E:</td>
 465                         <td>Used to set the execution flags for the given task. This tag
 466                            must be provided if T == -execute, otherwise it's erroneous
 467                            as compilation only takes place.</td>
 468                     </tr>
 469                     <tr>
 470                        <td>M:</td>
 471                         <td>Used to describe a string of text that should be matched from
 472                            the output of executing the task.  If this doesn't match the
 473                            task fails.  This tag must be provided at least once if
 474                            T == -execute, otherwise it's erroneous as compilation only
 475                            takes place. Multiple M tags are required for multi-line comparision
 476                         </td>
 477                     </tr>
 478                     <tr>
 479                        <td>I:</td>
 480                        <td>Used to specify the INPUT source file to operate on, this must be
 481                        provided, this tag is NOT optional</td>
 482                     </tr>
 483                  </table>
 484                 <h3>Notes</h3>
 485                 <p>
 486                    These tags (with exception to M) have one-time use, using them more
 487                    than once will result in template compilation errors,
 488                 </p>
 489                 <p>
 490                    Lines beginning with # or // in the template file are comments and
 491                    are ignored by the template parser.
 492                    Whitespace is optional, with exception to the colon ':' between the
 493                    tag and it's assignment value.
 494                 </p>
 495                    The template compiler will detect erronrous tags (optional tags
 496                    that need not be set), as well as missing tags, and error accordingly
 497                    which will result in that task failing.
 498                 </p>
 499                 <h1><a name="vdoc">Quake C Virtual Machine Documentation</a></h1>
 500                 <p>
 501                     Included with GMQCC is a minimal implementation of the QCVM used in many game
 502                     engines.  It's primarly used for the testsuite, but you may also use it as a
 503                     standalone runtime, or even embed it with existing appliciations.
 504                 </p>
 505                 <h2>Running The Standalone VM</h2>
 506                 <p>
 507                     To run the standalone application you need to have a compiled progs.dat, with an
 508                     entry function named &nbsp;main&nbsp;  The main function can have any amount of arguments
 509                     as the standalone executor allows main to be invoked with your choice of arguments.
 510                     An example of invoking the VM:
 511                     <pre>$ ./qcvm progs.dat -float 200 #execute passing in 200 as a float to main</pre>
 512                     If &nbsp;main&nbsp; doesn't require arguments:
 513                     <pre>$ ./qcvm progs.dat #call main with no arguments</pre>
 514
 515                     The standalone executor supports the following arguments for passing arguments to &nbsp;main&nbsp
 516
 517                     <table border="0">
 518                         <tr>
 519                             <td>Argument</td>
 520                             <td>What it does</td>
 521                         </tr>
 522                         <tr>
 523                             <td>-string</td>
 524                             <td>Passes in a string to main</td>
 525                         </tr>
 526                         <tr>
 527                             <td>-float</td>
 528                             <td>Passes in a float to main</td>
 529                         </tr>
 530                         <tr>
 531                             <td>-vector</td>
 532                             <td>Passes in a vector to main</td>
 533                         </tr>
 534                     </table>
 535
 536                     The order in which the arguments are expected for main, must be preserved, for
 537                     example if &nbsp;main&nbsp;'s signature is the following:
 538                     <pre>void main(float a, vector b)</pre>
 539
 540                     Then to pass the arguments you'd use the same order:
 541                     <pre>$ ./qcvm -float 200 -vector '1 2 3'</pre>
 542
 543                     <h3>Additional Arguments</h3>
 544                     The standalone virtual machine has the following optional command line arguments:
 545                     <table border="0">
 546                         <tr>
 547                             <td>Argument</td>
 548                             <td>What it does</td>
 549                         </tr>
 550                         <tr>
 551                             <td>-trace</td>
 552                             <td>Trace the execution call hierarchy.</td>
 553                         </tr>
 554                         <tr>
 555                             <td>-profile</td>
 556                             <td>Profile the bytecode to find hotspots.</td>
 557                         </tr>
 558                         <tr>
 559                             <td>-info</td>
 560                             <td>Get info of the running bytecode.</td>
 561                         </tr>
 562                         <tr>
 563                             <td>-disasm</td>
 564                             <td>Dissasemble the bytecode into assembly.</td>
 565                         </tr>
 566                         <tr>
 567                             <td>-printdefs</td>
 568                             <td>Prints all definitions for the bytecode running.</td>
 569                         </tr>
 570                         <tr>
 571                             <td>-printfields</td>
 572                             <td>Prints all fields for the bytecode running.</td>
 573                         </tr>
 574                     </table>
 575
 576                     <h3>Builtins</h3>
 577                     The standalone virtual machine includes the following builtins.
 578                     <table border="0">
 579                         <tr>
 580                             <td>Builtin</td>
 581                             <td>Number</td>
 582                         </tr>
 583                             <tr><td>print</td><td>1</td></tr>
 584                             <tr><td>ftos</td><td>2</td></tr>
 585                             <tr><td>spawn</td><td>3</td></tr>
 586                             <tr><td>kill</td><td>4</td></tr>
 587                             <tr><td>vtos</td><td>5</td></tr>
 588                             <tr><td>error</td><td>6</td></tr>
 589                             <tr><td>vlen</td><td>7</td></tr>
 590                             <tr><td>etos</td><td>8</td></tr>
 591                     </table>
 592                 </p>
 593                 <h3>Support or Contact</h3>
 594                 <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>
 595             </section>
 596             <footer>
 597                 <script type="text/javascript" src="http://www.ohloh.net/p/602517/widgets/project_partner_badge.js"></script>
 598             </footer>
 599         </div>
 600         <!--[if !IE]><script>fixScale(document);</script><![endif]-->
 601     </body>
 602 </html>