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 by graphitemaster</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="download"><a href="https://github.com/graphitemaster/gmqcc/zipball/master">Download ZIP</a></li>
  24                     <li class="download"><a href="https://github.com/graphitemaster/gmqcc/tarball/master">Download TAR</a></li>
  25                     <li class="buttons"><a href="https://github.com/graphitemaster/gmqcc/issues">Issues</a></li>
  26                     <li class="buttons"><a href="doc.html">Documentation</a></li>
  27                     <li class="buttons"><a href="https://github.com/graphitemaster/gmqcc">View On GitHub</a></li>
  28                 </ul>
  29             </header>
  30             <section>
  31                 <ul class="wiki">
  32                     <li class="wiki"><a class="wiki" href="#cdoc">Compiler Documentation</a></li>
  33                     <li class="wiki"><a class="wiki" href="#bdoc">Building Documentation</a></li>
  34                     <li class="wiki"><a class="wiki" href="#tdoc">Testsuite 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>-E</td>
  82                         <td>Instructs the compiler to only preprocess the input, writing the preprocessed output to stdout</td>
  83                     </tr>
  84                     <tr>
  85                         <td>-Wall</td>
  86                         <td>Enables all compiled warnings for the selcted standard</td>
  87                     </tr>
  88                     <tr>
  89                         <td>-Werror</td>
  90                         <td>Instruct the compiler to treat all warnings as errors</td>
  91                     </tr>
  92                     <tr>
  93                         <td>-std=&lt;standard&gt;</td>
  94                         <td>Selects the standard dialect</td>
  95                     </tr>
  96                 </table>
  97                 <h3>Predefined Macros</h3>
  98                 <table border="0">
  99                     <tr>
 100                         <td>Macro</td>
 101                         <td>What it represents</td>
 102                     </tr>
 103                     <tr>
 104                         <td>GMQCC</td>
 105                         <td>Specifies the current selected standard is gmqcc.</td>
 106                     </tr>
 107                     <tr>
 108                         <td>FTEQCC</td>
 109                         <td>Specifies the current selected standard is fteqcc.</td>
 110                     </tr>
 111                     <tr>
 112                         <td>QCC</td>
 113                         <td>Specifies the current selected standard is qcc.</td>
 114                     </tr>
 115
 116                     <tr>
 117                         <td>__STD_VERSION_MINOR__</td>
 118                         <td>Specifies the current selected stanadards minor version number.</td>
 119                     </tr>
 120                     <tr>
 121                         <td>__STD_VERSION_MAJOR__</td>
 122                         <td>Specifies the current selected stanadards major version number.</td>
 123                     </tr>
 124                 </table>
 125                 <h3>Unsupported compatability options</h3>
 126                 <p>
 127                     GMQCC strives hard for compatability with standard dialects, but not all
 128                     features of those standards might be implemented. The unsupported features
 129                     are presented below:
 130                     <table border="0">
 131                         <tr>
 132                             <td>Feature</td>
 133                             <td>Standard</td>
 134                         </tr>
 135                         <tr>
 136                             <td>Inline Assembly</td>
 137                             <td>FTEQCC</td>
 138                         </tr>
 139                         <tr>
 140                             <td>Macro expansion in strings</td>
 141                             <td>FTEQCC</td>
 142                         </tr>
 143                     </table>
 144                 </p>
 145                 <h2>Less common compiler options</h2>
 146                 <h3>Code generation options</h3>
 147                 <table border="0">
 148                     <tr>
 149                         <td>Option</td>
 150                         <td>What it does</td>
 151                     </tr>
 152                     <tr>
 153                         <td>-foverlap-locals</td>
 154                         <td>Reduces codesize by overlapping locals where possible</td>
 155                     </tr>
 156                     <tr>
 157                         <td>-fdarkplaces-string-table-bug</td>
 158                         <td>Works around a bug in older Darkplaces engine builds where the stringtable size is computed wrong</td>
 159                     </tr>
 160                     <tr>
 161                         <td>-fadjust-vector-fields</td>
 162                         <td>corrects assignment of vector field pointers (STORE_V instead of STORE_FLD)</td>
 163                     </tr>
 164                     <tr>
 165                         <td>-fftepp</td>
 166                         <td>Enables FTEQ preprocessor</td>
 167                     </tr>
 168                     <tr>
 169                         <td>-frelaxted-switch</td>
 170                         <td>Relaxes switch statement semantics</td>
 171                     </tr>
 172                     <tr>
 173                         <td>-fshort-logic</td>
 174                         <td>Enables short circut evaluation/logic</td>
 175                     </tr>
 176                     <tr>
 177                         <td>-fperl-logic</td>
 178                         <td>Enables perl evalutaion/logic</td>
 179                     </tr>
 180                 </table>
 181                 <h3>Warning options</h3>
 182                 <table border="0">
 183                     <tr>
 184                         <td>Option</td>
 185                         <td>What it does</td>
 186                     </tr>
 187                     <tr>
 188                         <td>-Wunused-uninitialized</td>
 189                         <td>Enables warnings about unused or uninitialized variables</td>
 190                     </tr>
 191                     <tr>
 192                         <td>-Wunknwon-control-sequence</td>
 193                         <td>Enables warnings about unknown control sequences</td>
 194                     </tr>
 195                     <tr>
 196                         <td>-Wextension</td>
 197                         <td>Enables warnings about the use of (an) extension(s)</td>
 198                     </tr>
 199                     <tr>
 200                         <td>-Wfield-redeclared</td>
 201                         <td>Enables warnings about redeclared fields</td>
 202                     </tr>
 203                     <tr>
 204                         <td>-Wmissing-return-values</td>
 205                         <td>Enables warnings about missing return values</td>
 206                     </tr>
 207                     <tr>
 208                         <td>-Wtoo-few-paramaters</td>
 209                         <td>Enables warnings about missing paramaters for function calls</td>
 210                     </tr>
 211                     <tr>
 212                         <td>-Wlocal-shadows</td>
 213                         <td>Enables warnings about locals shadowing paramaters or other locals</td>
 214                     </tr>
 215                     <tr>
 216                         <td>-Wlocal-constants</td>
 217                         <td>Enables warnings about constants specified as locals</td>
 218                     </tr>
 219                     <tr>
 220                         <td>-Wvoid-variables</td>
 221                         <td>Enables warnings about variables declared as type void</td>
 222                     </tr>
 223                     <tr>
 224                         <td>-Wimplicit-function-pointer</td>
 225                         <td>Enables warnings about implicitly declared function pointers</td>
 226                     </tr>
 227                     <tr>
 228                         <td>-Wvariadic-function</td>
 229                         <td>Enables warnings for use of varadics for non-builtin functions</td>
 230                     </tr>
 231                     <tr>
 232                         <td>-Wframe-macros</td>
 233                         <td>Enables warnings about duplicated frame macros</td>
 234                     </tr>
 235                     <tr>
 236                         <td>-Weffectless-statement</td>
 237                         <td>Enables warnings about effectiveless statements</td>
 238                     </tr>
 239                     <tr>
 240                         <td>-Wend-sys-field</td>
 241                         <td>Enables warnings of end_sys_fields being declared a field</td>
 242                     </tr>
 243                     <tr>
 244                         <td>-Wassign-function-types</td>
 245                         <td>Enables warnings for incompatible function pointer signatures used in assignment</td>
 246                     </tr>
 247                     <tr>
 248                         <td>-Wpreprocessor</td>
 249                         <td>Enables warnings about redefined macros</td>
 250                     </tr>
 251                     <tr>
 252                         <td>-Wmultifile-if</td>
 253                         <td>Enables warnings about multifile if statements</td>
 254                     </tr>
 255                 </table>
 256                 <p>
 257                     Individual warnings may be disabled with &nbsp;-Wno&lt;warning&gt;
 258                     <pre>$ gmqcc -Wno-frame-macros # disables frame duplication warning</pre>
 259                 </p>
 260                 <h3>Miscellaneous options</h3>
 261                 <table border="0">
 262                     <tr>
 263                         <td>Option</td>
 264                         <td>What it does</td>
 265                     </tr>
 266                     <tr>
 267                         <td>-force-crc=&lt;num&gt;</td>
 268                         <td>Forces a specific checsum into the header</td>
 269                     </tr>
 270                     <tr>
 271                         <td>-debug</td>
 272                         <td>Turns on compiler debug messages</td>
 273                     </tr>
 274                     <tr>
 275                         <td>-memchk</td>
 276                         <td>Turns on compiler memory leak checker</td>
 277                     </tr>
 278
 279                     <tr>
 280                         <td>-Whelp or -W?</td>
 281                         <td>Lists all warning options</td>
 282                     </tr>
 283
 284                     <tr>
 285                         <td>-fhelp or -f?</td>
 286                         <td>Lists all code generation options</td>
 287                     </tr>
 288                 </table>
 289
 290                 <h1><a name="bdoc">Building Documentation</a></h1>
 291                 <h2>Building on BSD/NIX</h2>
 292                 <p>
 293                     To compile GMQCC on BSD/NIX the following things are
 294                     required:
 295
 296                     <ul>
 297                         <li>GIT</li>
 298                         <li>Make</li>
 299                         <li>Any C90+ C compiler</li>
 300                     </ul>
 301
 302                     Once obtained you may checkout the development repository
 303                     with the following shell commands
 304
 305 <pre>$ git clone git://github.com/graphitemaster/gmqcc.git
 306 $ cd gmqcc
 307 </pre>
 308
 309                     The Makefile contains a few rules, depending on what you
 310                     want to compile, the following rules are:
 311
 312                     <table border="0">
 313                         <tr>
 314                             <td>Rule</td>
 315                             <td>What it does</td>
 316                         </tr>
 317                         <tr>
 318                             <td>gmqcc</td>
 319                             <td>Builds the gmqcc compiler</td>
 320                         </tr>
 321                         <tr>
 322                             <td>qcvm</td>
 323                             <td>Builds a standable QuakeC VM</td>
 324                         </tr>
 325                         <tr>
 326                             <td>testsuite</td>
 327                             <td>Builds the testsuite for GMQCC</td>
 328                         </tr>
 329                         <tr>
 330                             <td>all</td>
 331                             <td>Builds gmqcc, qcvm, and testsuite</td>
 332                         </tr>
 333                         <tr>
 334                             <td>install</td>
 335                             <td>Installs gmqcc to /usr/local/</td>
 336                         </tr>
 337                         <tr>
 338                             <td>check</td>
 339                             <td>Runs the testsuite to verify correctness</td>
 340                         </tr>
 341                     </table>
 342                 </p>
 343                 <h2>Building on Windows</h2>
 344                 <p>
 345                     To compile GMQCC on windows the following things are
 346                     required:
 347
 348                     <ul>
 349                         <li><a href="http://msysgit.googlecode.com/files/Git-1.8.0-preview20121022.exe">msysGit</a></li>
 350                         <li><a href="http://www.microsoft.com/visualstudio/eng/downloads">Visual Studio</a></li>
 351                     </ul>
 352
 353                     Once obtained you may checkout the development repository
 354                     with the following msysGit commands from a msysGit shell.
 355                     <pre>$ git clone git://github.com/graphitemaster/gmqcc.git</pre>
 356                     Included is a VS project file.
 357                 </p>
 358
 359                 <h1><a name="tdoc">Testsuite Documentation</a></h1>
 360                 <p>
 361                     GMQCC comes with a complete testsuite system for verifying semantics
 362                     and syntatics, TODO explain more and how to use it, write your own
 363                     tests etc....
 364                 </p>
 365
 366                 <h3>Support or Contact</h3>
 367                 <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>
 368             </section>
 369             <footer>
 370                 <script type="text/javascript" src="http://www.ohloh.net/p/602517/widgets/project_partner_badge.js"></script>
 371             </footer>
 372         </div>
 373         <!--[if !IE]><script>fixScale(document);</script><![endif]-->
 374     </body>
 375 </html>