.\" hey, Emacs: -*- nroff -*- .\" qfcc is free software; you can redistribute it and/or modify .\" it under the terms of the GNU General Public License as published by .\" the Free Software Foundation; either version 2 of the License, or .\" (at your option) any later version. .\" .\" This program is distributed in the hope that it will be useful, .\" but WITHOUT ANY WARRANTY; without even the implied warranty of .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. .\" .\" See the GNU General Public License for more details. .\" .\" You should have received a copy of the GNU General Public License .\" along with this program; see the file COPYING. If not, write to: .\" .\" Free Software Foundation, Inc. .\" 59 Temple Place, Suite 330 .\" Boston, MA 02111-1307, USA .\" .\" Some roff macros, for reference: .\" .nh disable hyphenation .\" .hy enable hyphenation .\" .ad l left justify .\" .ad b justify to both left and right margins (default) .\" .nf disable filling .\" .fi enable filling .\" .br insert line break .\" .sp insert n+1 empty lines .\" for manpage-specific macros, see man(7) .\" .TH QFCC 1 "14 December, 2001" QuakeForge "QuakeForge Developer's Manual" .\" Please update the above date whenever this man page is modified. .SH NAME qfcc \- The QuakeForge Code Compiler .SH SYNOPSIS .B qfcc .RI [ options ] .RI [ files ] .SH DESCRIPTION \fBqfcc\fP compiles Ruamoko source into a form that the QuakeForge server can understand. .SH OPTIONS \fBqfcc\fP takes the following arguments: .TP .B \-s, \-\-source DIR look for progs.src in DIR instead of the current directory. .TP .B \-q, \-\-quiet Inhibit some of qfcc's normal output. .TP .B \-v, \-\-verbose Display more output than usual. .TP .B \-g Generate debugging info. Synonym for \fB\-\-code debug\fP. .TP .B \-o, \-\0output\-file FILE Secify output file name. .TP .B \-P, \-\-progs\-src FILE File to use instead of progs.src .TP .B \-F, \-\-files Generate files.dat. This list is created by checking the parameters to the precache_* functions. .TP .B \-t, \-\-traditional Use traditional QuakeC syntax, semantics and "bugs". Also implies v6only. .TP .B \-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. .TP .B \-C, \-\-code OPTION,... Set code generation options. See \fBCODE GENERATION OPTIONS\fP for details. .TP .B \-W, \-\-warn OPTION,... Set warning options. See \fBWARNING OPTIONS\fP for details. .TP .B \-N, \-\-notice OPTION,... Set notice options. See \fBNOTICE OPTIONS\fP for details. .TP .B \-h, \-\-help Show summary of options. .TP .B \-V, \-\-version Show the version of qfcc. .TP .B \-S, \-\-save\-temps Do not delete temporary files. .TP .B \-D, \-\-define SYMBOL[=VAL],... Define symbols for the preprocessor, if it is in use. .TP .B \-I, \-\-include DIR,... Add DIR to the list of directories for the preprocessor to search when looking for include files. .TP .B \-U, \-\-undefine SYMBOL,... Undefine preprocessor symbols, if the preprocessor is in use. .TP .B \-\-cpp CPPSPEC cpp execution command line. See \fBCPP NAME\fP for details. .TP .B \-L DIR Add DIR to the search path used for -l. .TP .B \-l LIB Add libLIB.a to the list of libraries to be used for resolving undefined symbols. \fBqfcc\fP's libraries are really \fBpak\fP files of \fBqfcc\fP object files built using the \fBpak\fP utility. .TP .B \-c Compile only, do not link. Can be used in either progs.src or separate compilation modes. .TP .B \-r Incremental linking. Generate a larger object files from other object files and libraries. .TP .B \-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. .SH "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 \fBqfcc\fP's \fB\-\-code\fP argument: .TP .B cow 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, \fBqcc\fP never really enforced this. The \fBcow\fP option allows \fBqfcc\fP to gracefully cope with QuakeC source that assigns values to initialized globals in this manner. (also known as "copy on write" \(em never mind the bovine connotations) .TP .B debug Generate debug code for QuakeForge engines. The QuakeForge engine has the ability to load line number info and other debugging information for use in diagnosing progs crashes. This option tells \fBqfcc\fP to generate this information. It is written to a secondary file with the extension "sym" \(em if your output file is "progs.dat", the symbol file will be "progs.sym". .TP .B v6only 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 some of the compiler's features (like integers and string manipulation support). .SH "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 \fBqfcc\fP's \fB\-\-warn\fP argument: .TP .B cow Emit a warning when the source assigns a value to a named constant. See the description of the \fBcow\fP code option above for a description of what this means. .TP .B undef\-function Emit a warning when a function is called, but has not yet been defined. .TP .B uninited\-var Emit a warning when a variable is read from that has not been initalized to a value. .TP .B vararg\-integer Emit a warning when a function that takes a variable number of arguments is passed a constant of an integer type. .TP .B error Promote warnings to errors. .PP Any of the above can be prefixed with \fBno\-\fP to negate its meaning. There are also two special options: .TP .B all Turns on all warning options except \fBerror\fP. .TP .B none Turns off all warning options except \fBerror\fP. .SH "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 will be fairly self explanatory). .TP .B none Silences all notice messages. .TP .B warn Promote notices to warnings. If warnings are being treated as errors, so will notices. .SH "CPP NAME" When preprocessing source files, \fBqfcc\fP calls cpp (the C preprocessor) with a configurable command line. This is useful when wishing to use an alternative preprocessor (though it must be command line compatable with cpp) and when \fBqfcc\fP has been mis-configured to call cpp incorrectly for your operating system. If the latter is the case, please report the details (operating system, detection methods, correct execution specificaiton). The base default execution spec (on most Linux systems) is \fBcpp %d -o %o %i\fP. 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 substituions: .TP .B %d Mainly for defines (-D, -U and -I) but %d will be replaced by all cpp options that \fBqfcc\fP will be passing. .TP .B %o This will be replaced by the output file path. Could be either absolute or relative, depending on whether \fBqfcc\fP is deleting temporary files or not. .TP .B %i This will be replaced by the input file path. Generally as given to \fBqfcc\fP. .SH "FAQ" .TP .B 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 \fB(Quake, get it?)\fP. For more information, see the Web site at <\fBhttp://maori.com/kmst1.htm\fP>. .TP .B 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. .TP .B 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 \fBcow\fP option to \fB\-\-code\fP, so it has its revenge by mooing out a warning. Or something like that. To disable the warning, pass \fBno-cow\fP to \fB\-\-warn\fP. .SH "FILES" progs.src .SH "SEE ALSO" .BR quakeforge (1), pak (1) .SH AUTHORS The original \fBqcc\fP 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 \fBRuamoko\fP.