GMQCC

An Improved Quake C Compiler

Compiler Documentation

Defaults Flag

The -show-defaults flag instructs the compiler to print out the defaults used related to the standard, optimization, and code generation. When this flag is specified, the compiler will just print the defaults and quit. No compilation is performed.

$ gmqcc -show-defaults

Compiling for an alternitive standard

To compile with a different dialect of the QuakeC programming language the -std flag can be instructed to select one of the following options:
gmqcc default standard
fteqcc fteqcc standard
qcc vanila QuakeC standard

Common compiler options

Options What it does
-l<path> Adds <path> to the directories searched by the preprocessor for include file resolution.
-o <file> Generates the named executable (progs.src) file (when not specified default is progs.src).
-O<level> Specfies the optimization level: highest being 3, lowest being 0 (no optimization).
-g Enables generation of debug info for engine backtraces (turns on -flno)
-E Instructs the compiler to only preprocess the input, writing the preprocessed output to stdout
-D "define" a macro. Optionally you may supply a value to the macro with "=". Implicitally turns on -fftepp
-Wall Enables all compiled warnings for the selcted standard
-Werror Instruct the compiler to treat all warnings as errors
-std=<standard> Selects the standard dialect

Predefined Macros

Macro What it represents
__STD_GMQCC__ Specifies the current selected standard is gmqcc.
__STD_FTEQCC__ Specifies the current selected standard is fteqcc.
__STD_QCC__ Specifies the current selected standard is qcc.
GMQCC Defined always regardless of the selected standard
__STD_VERSION_MINOR__ Specifies the current selected stanadards minor version number.
__STD_VERSION_MAJOR__ Specifies the current selected stanadards major version number.
__FILE__ Expands to a const string literal of the current file (requires -fftepp-predef)
__LINE__ Expands to the current line number (requires -fftepp-predef)
__RANDOM__ Expands to a random number between [0, 256) (requires -fftepp-predef)
__COUNTER__ Expands to a unique number, each expansion causes it to increment (requires -fftepp-predef)
__RANDOM_LAST__ Expands to the last random number (requires -fftepp-predef)
__COUNTER_LAST__ Expands to the last counter number (requires -fftepp-predef)

Unsupported compatability options

GMQCC strives hard for compatability with standard dialects, but not all features of those standards might be implemented. The unsupported features are presented below:

Feature Standard
Inline Assembly FTEQCC
Macro expansion in strings FTEQCC

Less common compiler options

Code generation options

Option What it does
-foverlap-locals Reduces codesize by overlapping locals where possible
-fdarkplaces-string-table-bug Works around a bug in older Darkplaces engine builds where the stringtable size is computed wrong
-fadjust-vector-fields corrects assignment of vector field pointers (STORE_V instead of STORE_FLD)
-fftepp Enables FTEQ preprocessor
-fftepp-predef Enables additional predefined macros for the FTEQ preprocessor
-frelaxted-switch Relaxes switch statement semantics
-fshort-logic Enables short circut evaluation/logic
-fperl-logic Enables perl evalutaion/logic
-ftranslatable-strings Enables translatable strings via .po file
-finitialized-nonconstants Prevents initializations from becoming constant unless 'const' is specified as a qualifer
-fassign-function-types Allows function types to be assignable even if their signature is invariant
-flno Enables generation of progs.lno for engine VM backtraces (enabled with -g as well)
-fcorrect-ternary Enabling this corrects the ternary percedecce bugs present in fteqcc
-fsingle-vector-defs Prevents the creation of progdefs for vectors
-fcorrect-logic Use cast vector to real booleans when used in logic expressions
-ftrue-empty-strings Always treat empty strings as true
-ffalse-empty-strings Opposite of above, empty strings always false
-futf8 Recognize utf-8 characters in character constants, and encode codepoint escape sequences in strings as utf-8
-fbail-on-werror When a warning is printed and it is set to be treated as error via -Werror, compilation will be stopped.
-floop-labels Allow loops and switches to be labeled and break and continue to take optional label to target it.
-funtyped-nil Enable the 'nil' null constant, which has no type. It can be used as the right hand of any assignment.
-fpermissive Be "permissive", e.g with -funtyped-nil, this will allow local variables with the name 'nil'

Warning options

Option What it does
-Wunused-uninitialized Enables warnings about unused or uninitialized variables
-Wunknwon-control-sequence Enables warnings about unknown control sequences
-Wextension Enables warnings about the use of (an) extension(s)
-Wfield-redeclared Enables warnings about redeclared fields
-Wmissing-return-values Enables warnings about missing return values
-Wtoo-few-paramaters Enables warnings about missing paramaters for function calls
-Wlocal-shadows Enables warnings about locals shadowing paramaters or other locals
-Wlocal-constants Enables warnings about constants specified as locals
-Wvoid-variables Enables warnings about variables declared as type void
-Wimplicit-function-pointer Enables warnings about implicitly declared function pointers
-Wvariadic-function Enables warnings for use of varadics for non-builtin functions
-Wframe-macros Enables warnings about duplicated frame macros
-Weffectless-statement Enables warnings about effectiveless statements
-Wend-sys-field Enables warnings of end_sys_fields being declared a field
-Wassign-function-types Enables warnings for incompatible function pointer signatures used in assignment
-Wpreprocessor Enables warnings about redefined macros
-Wmultifile-if Enables warnings about multifile if statements
-Wdouble-declaration Enables warnings about double declarations
-Wconst-var Enables warnings about 'const var' and 'var const'
-Wmultibyte-character Enables warnings about use of multibyte characters
-Wternary-precedence Enables warnings about ternary expressions whos precedence may be not what expected
-Wunknown-pragmas Enables warnings about unknown pragmas
-Wunreachable-code Enables warnings about unreachable code
-Wcpp Enables warnings about the preprocessor
Wunknown-attribute Enables warnings for when an unknown attribute is encountered.
-Wreserved-names Enables warnings for variables or fields that are named with a reserved name
-Wuninitialized-constant Enables warnings about const global variables with no initializing value
-Wuninitialized-global Enables warnings about non-const gloal variable with no initializing value
-Wdeprecated Enables warnings about calls to functions marked deprecated
OptionsWhat it does
-Opeephole Enables peephole optimizations
-Olocal-temps Enables local-temp omission optimizations
-Oglobal-temps Enables global-temp omission optimizations
-Otail-recursion Enables tail recursion optimization
-Otail-calls Enables tail-call optimizations
-Ooverlap-locals Every function where it's safe to do so will share its local section with others. The critera being that the function must have any possibly uninitialized locals, or local arrays regardless of how they are initialized.
-Ostrip-constant-names Strip the names of constants
-Ooverlap-strings Agressivly reuse strings in the string-section.
-Ocall-stores Have expressions which are used as function parameters evaluate directly into the parameter-globals if possible. This avoids copying.
-Ovoid-return Do not create a return instruction at the end of return-type void functions

Individual warnings may be disabled with  -Wno-<warning>

$ gmqcc -Wno-frame-macros # disables frame duplication warning

Miscellaneous options

Option What it does
-force-crc=<num> Forces a specific checsum into the header
-debug Turns on compiler debug messages
-memchk Turns on compiler memory leak checker
-dump Dump IR before optimizing and finalizing
-dumpfin Dump IR after optimizing and finalizing
-Whelp or -W? Lists all warning options
-fhelp or -f? Lists all code generation options
-redirout=<file> Redirect stdout to any file.
-redirerr=<file> Redirect stderr to any file.
-nocolor Turn off colored stdout/stderr.
-config=<file> Supply a configuration file to set options. Note: If a file named gmqcc.ini or gmqcc.cfg is found it will be loaded implicitally.

Building Documentation

Building on BSD/NIX

To compile GMQCC on BSD/NIX the following things are required:

Once obtained you may checkout the development repository with the following shell commands
$ git clone git://github.com/graphitemaster/gmqcc.git
$ cd gmqcc
The Makefile contains a few rules, depending on what you want to compile, the following rules are:
Rule What it does
gmqcc Builds the gmqcc compiler
qcvm Builds a standable QuakeC VM
testsuite Builds the testsuite for GMQCC
check, test Build and executes the testsuite for GMQCC
pak Builds the pak utility
splint Runs splint (static analysis) on the source
gource Runs gource visualization on the source
gource-record Runs gource visualization and produces a rendered mp4
depend Builds dependinces into the Makefile
all Builds gmqcc, qcvm, pak, and testsuite
install Installs gmqcc, qcvm, and documentaion
uninstall Uninstalls gmqcc, qcvm, and documentation
check Runs the testsuite to verify correctness

Building on Windows

To compile GMQCC on windows the following things are required:

Once obtained you may checkout the development repository with the following msysGit commands from a msysGit shell.
$ git clone git://github.com/graphitemaster/gmqcc.git
Included is a VS project file.

Testsuite Documentation

Running The Testsuite

To run the testsuite you can either use

$ make check
Or if you're on windows or have already compiled the testsuite from source:
$ ./testsuite 
Optionally you may provide the testsuite with additional arguments:
Argument What it does
-redirout=<file> Redirect stdout to any file.
-redirerr=<file> Redirect stderr to any file.
-debug Turn on testsuite debug messages.
-memchk Turn on testsuite memleak checker.
-nocolor Turn off colored stdout/stderr.

Writing Tests

GMQCC comes with a complete testsuite for verifying semantics and syntatics. The testsuite executes files from the test/ directory, by reading task template files.

templates are rules for a specific test, used to create a "task" that is executed with those set of rules (arguments, and what not). Tests that don't have a template with them cannot become tasks, since without the information for that test there is no way to properly "test" them. Rules for these templates are described in a template file, using a task template language.

The languge is composed entierly of "tags" which describe a string of text for a task. Think of it much like a configuration file. Except it's been designed to allow flexibility and future support for prodecual semantics.

The following "tags" are suported by the language:

Tag Description of what the tag does
D: Used to set a description of the current test, this must be provided, this tag is NOT optional.
F: Used to set test-suite specific flags, currently the only supported flag is -no-defs which tells the testsuite to exclude defs.qh.
T: Used to set the procedure for the given task, there are four options for this:
  • -compile  This simply performs compilation only
  • -execute  This will perform compilation and execution
  • -fail  This will perform compilation on the requirement it fails, otherwise the test fails
  • -pp  This will perform preprocessing only
This tag must be provided, this tag is NOT optional.
C: Used to set the compilation flags for the given task, this must be provided, this tag is NOT optional.
E: Used to set the execution flags for the given task. This tag must be provided if T == -execute, otherwise it's erroneous as compilation only takes place.
M: Used to describe a string of text that should be matched from the output of executing the task. If this doesn't match the task fails. This tag must be provided at least once if T == -execute or T == -pp, otherwise it's erroneous as compilation only takes place. Multiple M tags are required for multi-line comparision
I: Used to specify the INPUT source file to operate on, this must be provided, this tag is NOT optional

Notes

These tags (with exception to M) have one-time use, using them more than once will result in template compilation errors,

Lines beginning with # or // in the template file are comments and are ignored by the template parser. Whitespace is optional, with exception to the colon ':' between the tag and it's assignment value.

The template compiler will detect erronrous tags (optional tags that need not be set), as well as missing tags, and error accordingly which will result in that task failing.

Quake C Virtual Machine Documentation

Included with GMQCC is a minimal implementation of the QCVM used in many game engines. It's primarly used for the testsuite, but you may also use it as a standalone runtime, or even embed it with existing appliciations.

Running The Standalone VM

To run the standalone application you need to have a compiled progs.dat, with an entry function named  main  The main function can have any amount of arguments as the standalone executor allows main to be invoked with your choice of arguments. An example of invoking the VM:

$ ./qcvm progs.dat -float 200 #execute passing in 200 as a float to main
If  main  doesn't require arguments:
$ ./qcvm progs.dat #call main with no arguments
The standalone executor supports the following arguments for passing arguments to  main 
Argument What it does
-string Passes in a string to main
-float Passes in a float to main
-vector Passes in a vector to main
The order in which the arguments are expected for main, must be preserved, for example if  main 's signature is the following:
void main(float a, vector b)
Then to pass the arguments you'd use the same order:
$ ./qcvm -float 200 -vector '1 2 3'

Additional Arguments

The standalone virtual machine has the following optional command line arguments:
Argument What it does
-h, --help Print help message
-trace Trace the execution call hierarchy.
-profile Profile the bytecode to find hotspots.
-info Get info of the running bytecode.
-disasm Dissasemble the bytecode into assembly.
-diasm-func Dissasmble function
-printdefs Prints all definitions for the bytecode running.
-printfields Prints all fields for the bytecode running.
-printfuns Prints all functions for the bytecode running.
-v Be verbose
-v Be even more verbose
-version, --version Print version information

Builtins

The standalone virtual machine includes the following builtins.
Builtin Number
print1
ftos2
spawn3
kill4
vtos5
error6
vlen7
etos8
stof9
strcat10
strcmp11
normalize12
sqrt13
floor14

Support or Contact

Having trouble with GMQCC? Join our IRC channel at #kf-engine on irc.freenode.net or contact Us