qfcc - The QuakeForge Code Compiler
compiles Ruamoko source into a form that the QuakeForge engine can
takes the following arguments:
- Use advanced Ruamoko features. This is the default when using separate
- -C, --code OPTION,...
- Set code generation options. See CODE GENERATION OPTIONS for
- Only compile, do not link. Can be used in either progs.src or
separate compilation modes.
- --cpp CPPSPEC
- cpp execution command line. See CPP NAME for details.
- -D, --define SYMBOL[=VAL]
- Define a symbol for the preprocessor, if it is in use.
- Only preprocess. No compilation or linking is done.
- Allow extended keywords in traditional mode.
- -F, --files
- Generate files.dat. This list is created by checking the parameters
to the precache_* functions.
- Generate <source>.frame files. For each source file (listed
either on the command line, or in progs.src, write a file whose
name is the base name of the source file with an extension of
.frame, and contains a list of frame macro names with their
associated frame numbers. Eg, player.qc will produce
player.framea. Note that files that do not create frame macros will
not generate a frame file. At this time, the file is always written to the
- Generate debugging info. Synonym for --code debug.
- -h, --help
- Show summary of options.
- -I DIR
- Add DIR to the list of directories for the preprocessor to search when
looking for include files.
- --include FILE
- Process FILE as if #include "FILE" appeared as the first
line of the primary source file. See the cpp man page
(-include) for details.
- -L DIR
- Add DIR to the search path used for finding libraries specified with
- -l LIB
- Add libLIB.a to the list of libraries to be used for resolving undefined
symbols. qfcc expects libraries to be pak files of
qfcc object files built using the pak utility.
- -M, -MD, -MMD
- Generate dependency info. Dependent on cpp version, so check
- Do not use default paths for include files or libraries.
- -N, --notice OPTION,...
- Set notice options. See NOTICE OPTIONS for details.
- -o, --output-file FILE
- Specify output file name. In progs.src mode, this overrides the
output file in progs.src.
- Generate progdefs.h. Forces --code crc.
- -P, --progs-src FILE
- File to use instead of progs.src. No effect in separate compilation
- Use QCCX escape sequences instead of standard C/QuakeForge sequences in
strings. See ESCAPE SEQUENCES for details.
- -p, --strip-path NUM
- Strip NUM leading path elements from file names. eg. -p 3 will strip the
../../../ from ../../../src/foo.r when embedding the source
file name in the output code.
- -q, --quiet
- Inhibit some of qfcc's normal output. Specifying this option
multiple times further inhibits qfcc's output. Counteracts the
effects of -v.
- -r, --relocatable
- Incremental linking. Generate a larger object file from other object files
- -S, --save-temps
- Do not delete temporary files.
- -s, --source DIR
- Look for progs.src in DIR instead of the current
- Use traditional QuakeC syntax, semantics and “bugs”. Also
implies the v6only, no-short-circuit and
no-local-merging code generation options (see CODE GENERATION
OPTIONS). This is the default when using progs.src mode.
- -U, --undefine SYMBOL
- Undefine a preprocessor symbol, if the preprocessor is in use.
- -V, --version
- Show the version of qfcc.
- -v, --verbose
- Display more output than usual. Specifying this option multiple times
further increases qfcc's output. Counteracts the effects of
- -W, --warn OPTION,...
- Set warning options. See WARNING OPTIONS for details.
- Compress object files when writing them. This is especially useful when
creating libraries, especially if using the object oriented features, but
can be quite slow. This has no effect when creating progs.dat.
Code generation options are processed in the order of their appearance on the
command line. Unsupported options are ignored. The following options are
supported by qfcc
- Allow assignment to initialized globals. In Quake-C and Ruamoko, a global
that has been initialized to a value is not a variable, but a named
constant. However, qcc never really enforced this. The cow
option allows qfcc to gracefully cope with QuakeC source that
assigns values to initialized globals in this manner. (also known as
“copy on write”—never mind the bovine
- Preprocess all input files with cpp. This includes the
progs.src file when used.
- Write the CRC of progdefs.h to “progs.dat”. Default
for v6 progs, otherwise defaults to off. However, --progdefs has
the effect of forcing this option.
- Generate debug code for QuakeForge engines. The QuakeForge engine has the
ability to load line number and other debugging information for use in
diagnosing progs crashes. This option tells qfcc to generate this
information. It is written to a secondary file with the extension
“sym”—if your output file is
“progs.dat”, the symbol file will be
- Use float values directly in “if” statements. Defaults to
on. This option is always enabled when using version 6 progs (
v6only is in effect).
- Clump the local variables from all functions into one block of data the
size of the largest group of locals, resulting in large savings of global
data space. When off, each function's local variable block is separate
from the others, preserving the behaviour of traditional qcc, but
using much more global data. This can be a problem because instructions
can access addresses up to 32767 in older servers or 65535 in most modern
servers. Defaults to off for traditional mode, and on for advanced
- Generate short circuit code for logical operators (&& and
||). For A && B, if A is false, the
expression is known to be false and the code for B will not be
executed. Similar for A || B, but if A is true, the
expression is known to be true and the code for B will not be
executed. Defaults to off for traditional mode, and on for advanced
- In progs.src mode, when cpp is used, produce an intermediate
file that is a series of #include directives, one for each source
file. This file is then passed to cpp and the resulting output is
compiled in one go. This results in preprocessor directives in early files
affecting later files, as would be expected in progs.src mode.
Without this option, each source file is independent with respect to the
preprocessor. Has no effect in separate compilation mode. Defaults to
- When a function is passed a constant vector, this causes the vector to be
passed using three float copy instructions instead of one vector copy
instruction. This can save a good number of pr_globals where those vectors
contain many duplicate coordinates but do not match entirely. However,
this will generate slower code for such calls.
- Create extra symbols for accessing the components of a vector variable or
field. For example, vector vel will also create vel_x,
vel_y, and vel_z. Defaults to on for traditional code and
off for advanced.
- Restrict the compiler to only version 6 progs (original Quake/QuakeWorld)
features. This means that the compiled data file should be able to run on
older servers, as long as you have not used any QuakeForge-specific
built-in functions. Also disables compiler features (such as integers and
string manipulation support) that require extensions. Defaults to on for
traditional mode and off for advanced mode.
Any of the above can be prefixed with no-
to negate its meaning.
Warning options are processed in the order of their appearance on the command
line. Unsupported options are ignored. The following options are supported by
- Emit a warning when the source assigns a value to a named constant. See
the description of the cow code generation option above for a
description of what this means.
- Promote warnings to errors.
- Emit a warning when non-executable statements (eg, == used for
assignment) are encountered.
- Emit a warning when too many structure/array initializer elements are
- Emit a warning when both constants in a division operation are
- Emit a warning when a method is declared in an implementation but not in
the interface for a class.
- Emit a warning when potentially ambiguous logic is used without
- Emit a warning when a local variable is redeclared.
- Emit a warning when code that should be an error is allowed by traditional
qcc. Has effect only in traditional mode.
- Emit a warning when a function is called, but has not yet been
- Emit a warning when a class method has not been implemented.
- Emit a warning for unused local variables.
- Emit a warning when a variable is read from that has not been initialized
to a value.
- Emit a warning when a function that takes a variable number of arguments
is passed a constant of an integer type.
Any of the above can be prefixed with no-
to negate its meaning. There
are also two special options:
- Turns on all warning options except error.
- Turns off all warning options except error.
Notices are used to flag code constructs that may have changed semantics but
shouldn't be treated as warnings. They are also used for internal debugging
purposes, so if you see any cryptic notices, please report them as a bug
(normal notices should be fairly self-explanatory).
- Silences all notice messages.
- Promote notices to warnings. If warnings are being treated as errors, so
will notices. Disabling warnings has no effect on this option.
When preprocessing source files, qfcc
preprocessor) with a configurable command line. This is useful when you wish
to use an alternative preprocessor (though it must be command line compatible
) or when qfcc
has been misconfigured to call cpp
incorrectly for your operating system. If the latter is the case, please
report the details (operating system, detection methods, correct execution
specification). The base default execution spec (on most Linux systems) is
cpp %d -o %o %i
. This spec is similar in concept to a printf
string. The name of the program may be either absolute (eg /lib/cpp
relative as the PATH
will be searched. Available substitutions:
- Mainly for defines (-D, -U and -I) but %d will be replaced by all
cpp options that qfcc passes to cpp
- This will be replaced by the output file path. Could be either absolute or
relative, depending on whether qfcc is deleting temporary files or
- This will be replaced by the input file path. Generally as given to
has two, mutually exclusive, modes of operation: progs.src
mode and “separate compilation” mode.
This is the traditional method of compiling QuakeC programs. It is selected when
no file arguments are given to qfcc
. Note that the -lLIB
is considered to be a file argument.
In this mode, the file progs.src
is used to specify the output file name
and the input source files. While it is customary to write each file name on a
separate line, file names are really just white-space separated strings (use
double quotes around files with spaces, though using files with spaces is a
gibbing offence). //
is used to denote a comment. The comment extends
to the end of the current line. The first file name in the file specified the
output file name. This may be overridden using the -o
subsequent file names specify QuakeC source files.
The source files are cumulatively compiled in the order they are listed in
. Cumulatively compiled means that all symbols other than
frame macros defined in earlier source files are visible in later source
files. Once the all source files have been compiled, the finished program is
written to the output file as a normal progs.dat
If the -c
option is given, instead of a progs.dat
file, an object
file is written. This object file can then be linked against other object
files to produce the progs.dat
file. This is useful when mod extensions
are in library form and converting the main mod from progs.src
separate compilation is undesirable.
mode implies --traditional
. However, this can be
overridden using --advanced
has not been disabled, progs.src
is first passed through
. The result is then parsed as above, but unless the
code option has been given, rather than compiling each
source file, an intermediate file is generated containing a series of frame
macro reset and #include
directives, one for each file. This
intermediate file is then passed to cpp
and the resulting single file
containing all of the preprocessed source code is then compiled.
This mode is more generally useful. It is particularly well suited to building
object libraries for use in other programs. Separate compilation mode is
automatically selected when any file arguments (including -lLIB
given on the command line.
Each file argument is processed in the order given. Files ending in .r
, or .c
(part of an experimental hack to put qfcc support
into automake) are treated as sources and compiled to object file. All other
files (including -lLIB
) are passed untouched to the linker unless the
is given. If -c
is given, then object files are ignored and
the linking stage will be skipped. Each source file is fully independent of
the others. When linking ( -c
has not been given), any generated object
files will be deleted unless -S
is on the command line. However, no
object file given on the command line will be deleted.
When linking, if the -r
option is given, instead of the output file being
a normal progs file, it will be an object file that can be linked against
other object files.
While separate compilation mode implies --advanced
, this can be
overridden using --traditional
When using cpp
, each source file is passed through the preprocessor
individually. Each file is truly independent of any other file on the command
supports a variety of string escape sequences. This includes those
(which are a subset of those in standard C), standard C and
. There are some conflicts between the escape sequences, but
selects which set to use.
- Line feed.
- Double quote.
- Single quote.
- Octal character code, up to three digits. This conflicts with qccx.
In qccx, this produces gold digits. Use --qccx-escapes to
select qccx behaviour.
- Produce gold digits.
- Hexadecimal character code, any number of digits, but only the least
significant byte will be used.
- Bell character (not in quake engines). Equivalent to \x07.
- Backspace character (not in quake engines). Equivalent to \x08. This
conflicts with qccx. In qccx, this toggles bronze
characters. Use --qccx-escapes to select qccx
- Escape character (not in quake engines). Equivalent to \x1b (dull 9).
- Formfeed character (not in quake engines). Equivalent to \x0c.
- Carriage return. Equivalent to \x0d.
- Toggle "bold" characters (add 0x80). \t Tab character.
Equivalent to \x09.
- Vertical tab. Equivalent to \x0b.
- Make the next character "bold" (add 0x80).
- Gold [ character. Equivalent to \x90.
- Gold ] character. Equivalent to \x91.
- Center dot. Equivalent to \x1c.
- Turn on "bold" characters (add 0x80). This conflicts with
qccx. In qccx, this produces the brown left end. Equivalent
to \x1d. Use --qccx-escapes to select qccx behaviour.
- Brown center bit. Equivalent to \x1e.
- Turn off "bold" characters (add 0x80). This conflicts with
qccx. In qccx, this produces the brown right end. Equivalent
to \x1f. Use --qccx-escapes to select qccx behaviour.
- Left slider end. Equivalent to \x80.
- Slider center. Equivalent to \x81.
- Right slider end. Equivalent to \x82.
- Decimal character code.
has no effect on sequences that do not conflict.
Compared to qcc
has many advanced features and is much
stricter about type checking. qfcc
also uses the same operator
semantics and precedence rules as standard C
. Unfortunately, this means
that most older QuakeC code will not compile, or even worse, will compile
To address this situation, qfcc
has a “traditional” mode
for compiling old progs. This mode, enabled with --traditional
default in progs.src
mode, removes the new keywords required by
's advanced features, converts new errors to warnings, some
warnings to notices and inverts precedence order where required (eg, (!var
& flag)). Traditional mode also affects several code generation options
(as always, this can be overridden):
- code output is restricted to version 6 progs instructions
- short circuit boolean logic is disabled
- each function has a private area of data for its local variables (this
wastes a lot of data space).
Advanced mode is simply qfcc
in its natural state. Using
can be put in to advanced mode while using the
- Where did the name Ruamoko come from?
- In Maori mythology, Ruamoko is the youngest child of Ranginui, the
Sky-father, and Papatuanuku, the Earth-mother. Ruamoko is the god of
volcanoes and earthquakes. For more information, see the Web site at <
- qfcc hangs
- This is almost always caused by qfcc incorrectly invoking cpp.
Using the --cpp option (refer to the CPP NAME section
above), the correct method for invoking cpp can be specified. Once
you have found this, please send the correct cpp command line,
preferably along with the output of config.guess, to the team.
- qfcc is singing a bad 80s rap song to me. What's going on?
- “ice ice baby” is QuakeForge-speak for “Internal
Compiler Error”. It usually means there's a bug in qfcc, so
please report it to the team.
- qfcc is mooing at me. What's wrong with you people?
- The compiler doesn't like being treated like a slab of beef. Seriously,
the code you are trying to compile is using constants as if they weren't.
Normally, qfcc would just stop and tell the code to sit in the corner for
a while, but you told it not to do that by passing the cow option
to --code, so it has its revenge by mooing out a warning. Or
something like that. To disable the warning, pass no-cow to
The original qcc
program, for compiling the QuakeC language, was written
by Id Software, Inc. The members of the QuakeForge Project have modified it to
work with a new, but very similar language called Ruamoko