QFCC(1)

NAME
qfcc - The QuakeForge Code Compiler

SYNOPSIS
qfcc [options] [files]

DESCRIPTION
qfcc compiles Ruamoko source into a form that the QuakeForge engine can understand.

OPTIONS
qfcc takes the following arguments:

--advanced
    Use advanced Ruamoko language features limited to the v6p ISA. This provides access to structs, arrays, pointers, integers, quaternions, doubles and object-oriented features mostly compatible with Objective-C (ie, Objective-QuakeC). For access to SIMD vector types, see --ruamoko.

-C, --code OPTION,...
    Set code generation options. See CODE GENERATION OPTIONS for details.

-c  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.

-E  Only preprocess. No compilation or linking is done.

--extended
    Allow extended keywords in traditional mode. Otherwise, it has all the implications of --traditional.

-F, --files
    Generate files.dat. This list is created by checking the parameters to the precache_* functions.

--frames
    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.frame. 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 current directory.

-g  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.

-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 cpp's documentation.

--no-default-paths
    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.

--progdefs
    Generate progdefs.h. Forces --code crc.

-P, --progs-src FILE
    File to use instead of progs.src. No effect in separate compilation mode.

--qccx-escapes
    Use QCCX escape sequences instead of standard C/QuakeForge sequences in strings. See ESCAPE SEQUENCES for details.

-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 and libraries.

--raumoko, --ruamoko
    In addition to the Ruamoko language features added by --advanced, this option provides access to SIMD vector types (and instructions), a data stack for local variables and parameters (allowing pointers to local variables to be passed to other functions!), and other features still under development. This is the default when using separate compilation.

-S, --save-temps
    Do not delete temporary files.

-s, --source DIR
    Look for progs.src in DIR instead of the current directory.

--traditional
    Use traditional QuakeC syntax, semantics and “bugs”. Also implies the target=v6, no-short-circuit, const-initializers 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 -q.

-W, --warn OPTION,...
    Set warning options. See WARNING OPTIONS for details.

-z  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
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's --code argument:

const-initializers
    Treat initialized globals as constants. This option is implied by --traditional and --extended, and is turned off by --advanced.

cow Allow assignment to initialized globals. When initialized globals are treated as constants (traditional Quake-C, or when const-initializers is activated), 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”—lo and behold the bovine connotations)

cpp Preprocess all input files with cpp. This includes the progs.src file when used.

crc 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.

debug
    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 “progs.sym”.

fast-float
    Use float values directly in “if” statements. Defaults to on. This option is always enabled when targeting v6 progs (target=v6 is in effect).

local-merging
    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 mode.

promote-float
    Promote float when passed to a function that takes a variable number of arguements. Defaults to enabled for advanced code (v6p or ruamoko), is forced off for traditional or v6 code (mostly because such code does not have doubles).

short-circuit
    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 mode.

single-cpp
    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 on.

vector-calls
    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.

vector-components
    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.

Any of the above can be prefixed with no- to negate its meaning.

target=v6|v6p|ruamoko
    Specify the target for which the compiler is to produce code.

    v6  Standard Quake VM (qcc compatible). 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.

    v6p QuakeForge extended v6 instructions. This is not compatible with older servers, nor with most (any?) other Quake engines. It adds a variety of instructions and types, including integers, quaternions, pointers, doubles, structs, arrays and Objective-C style classes.

    ruamoko
        QuakeForge SIMD and stack instructions.
Defaults to v6 for traditional mode, v6p for advanced mode, and ruamoko for Ruamoko mode (actually, trying to take Ruamoko's power after granting it may not end well).

WARNING OPTIONS
Warning options are processed in the order of their appearance on the command line. Unsupported options are ignored. The following options are supported by qfcc's --warn argument:

cow 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.

error
    Promote warnings to errors.

executable
    Emit a warning when non-executable statements (eg, == used for assignment) are encountered.

initializer
    Emit a warning when too many structure/array initializer elements are given.

integer-divide
    Emit a warning when both constants in a division operation are integers.

interface-check
    Emit a warning when a method is declared in an implementation but not in the interface for a class.

precedence
    Emit a warning when potentially ambiguous logic is used without parentheses.

redeclared
    Emit a warning when a local variable is redeclared.

switch
    Emit a warning when an enum value is not handled in a switch statement that tests an enum. Using a default label will cause all otherwise unhandled enum values to be handled (for good or evil).

traditional
    Emit a warning when code that should be an error is allowed by traditional qcc. Has effect only in traditional mode.

undef-function
    Emit a warning when a function is called, but has not yet been defined.

unimplemented
    Emit a warning when a class method has not been implemented.

unused
    Emit a warning for unused local variables.

uninited-var
    Emit a warning when a variable is read from that has not been initialized to a value.

vararg-integer
    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:

all Turns on all warning options except error.

none
    Turns off all warning options except error.

NOTICE OPTIONS
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).

none
    Silences all notice messages.

warn
    Promote notices to warnings. If warnings are being treated as errors, so will notices. Disabling warnings has no effect on this option.

CPP NAME
When preprocessing source files, qfcc calls cpp (the C preprocessor) with a configurable command line. This is useful when you wish to use an alternative preprocessor (though it must be command line compatible with cpp) 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) or relative as the PATH will be searched. Available substitutions:

%d  Mainly for defines (-D, -U and -I) but %d will be replaced by all cpp options that qfcc passes to cpp

%o  This will be replaced by the output file path. Could be either absolute or relative, depending on whether qfcc is deleting temporary files or not.

%i  This will be replaced by the input file path. Generally as given to qfcc.

COMPILATION MODES
qfcc has two, mutually exclusive, modes of operation: progs.src mode and “separate compilation” mode.

  progs.src 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 option 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 specifies the output file name. This may be overridden using the -o option. All subsequent file names specify QuakeC source files.

The source files are cumulatively compiled in the order they are listed in progs.src. 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 file.

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 style to separate compilation is undesirable.

progs.src mode implies --traditional. However, this can be overridden using --advanced.

When cpp has not been disabled, progs.src is first passed through cpp. The result is then parsed as above, but unless the no-single-cpp 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.

  “separate compilation” mode
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) are given on the command line.

Each file argument is processed in the order given. Files ending in .r, .qc, 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 -c 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 line.

ESCAPE SEQUENCES
qfcc supports a variety of string escape sequences. This includes those of qcc (which are a subset of those in standard C), standard C and qccx. There are some conflicts between the escape sequences, but --qccx-escapes selects which set to use.

  Standard escape sequences:
These are the supported escape sequences from standard C, with the addition of \e (escape), which would be nice if it was in standard C.

\a  Bell character (not in quake engines). Equivalent to \x07.

\b  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 behaviour.

\e  Escape character (not in quake engines). Equivalent to \x1b. Not actually standard, but it should be.

\f  Formfeed character (not in quake engines). Equivalent to \x0c.

\n  Line feed.

\r  Carriage return. Equivalent to \x0d.

\t  Tab character. Equivalent to \x09.

\v  Vertical tab. Equivalent to \x0b.

\\  Backslash.

\'  Single quote.

\"  Double quote.

\?  Question mark. Avoids trigraphs in standard C, but supported for compatibility.

\0-7
    Octal character code, up to three digits. This conflicts with qccx. In qccx, this produces gold digits. Use --qccx-escapes to select qccx behaviour.

\8-9
    Produce gold digits.

\x0-9A-Fa-f
    Hexadecimal character code, any number of digits, but only the least significant byte will be used.

  Quake character set extension escape sequences:

\b  Toggle bronze characters. Requires --qccx-escapes.

\s  Toggle "bold" characters (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 separator left end. Equivalent to \x1d. Use --qccx-escapes to select qccx behaviour.

\-  Separator center. Equivalent to \x1e.

\>  Turn off "bold" characters (add 0x80). This conflicts with qccx. In qccx, this produces the separator right end. Equivalent to \x1f. Use --qccx-escapes to select qccx behaviour.

\^  Make the next character "bold" (add 0x80).

\0-9
    Produce gold digits. Requires --qccx-escapes (except \8 and \9: they are always available).

\(  Slider left end. Equivalent to \x80.

\=  Slider center. Equivalent to \x81.

\)  Slider right end. Equivalent to \x82.

\{0-255}
    Decimal character code. Quake specific as qccx added this to allow specifying the character code directly as \0-\9 were already used for specifying gold digits.

--qccx-escapes has no effect on sequences that do not conflict.

TRADITIONAL VS ADVANCED VS RUAMOKO
Compared to qcc, qfcc 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 incorrectly.

To address this situation, qfcc has a “traditional” mode for compiling old progs. This mode, enabled with --traditional or by default in progs.src mode, removes the new keywords required by qfcc'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 qfcc in what was its natural state until the introduction of Ruamoko mode. Advanced mode adds several data types and Objective-C object oriented programming. Using --advanced, qfcc can be put in to advanced mode while using the progs.src compilation mode.

Ruamoko mode is qfcc in its natural state. On top of the features added by Advanced mode, Ruamoko mode adds SIMD types and instructions, and a data stack for locals and parameters.

RUAMOKO PROGRAMMING LANGUAGE
Ruamoko evolved from the original QuakeC language, gaining standard C syntax and most features (the char type is not supported, and function pointers are a little weird (design bug?)), Objective-C object oriented extensions, and (with the Ruamoko ISA) SIMD vectors and the ability to pass pointers to local variables to other functions.

FAQ

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 <http://maori.com/kmst1.htm>.

Why both Ruamoko and Raumoko?
    They are alternative spellings and pronunciations. Use whichever one you prefer.

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 --warn.

FILES
progs.src

SEE ALSO
quakeforge(1), pak(1)

AUTHORS
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.