quakeforge/tools/qfcc/doc/man/qfcc.1

.\"                              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 <n>    insert n+1 empty lines
.\" for manpage-specific macros, see man(7)
.\"
.TH QFCC 1 "28 April, 2004" 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 engine can
understand.
.SH OPTIONS
\fBqfcc\fP takes the following arguments:
.TP
.B \-\-advanced
Use advanced Ruamoko features. This is the default when using separate
compilation.
.TP
.B \-C, \-\-code OPTION,...
Set code generation options. See \fBCODE GENERATION OPTIONS\fP for details.
.TP
.B \-c
Compile only, do not link. Can be used in either \fBprogs.src\fP or separate
compilation modes.
.TP
.B \-\-cpp CPPSPEC
\fBcpp\fP execution command line. See \fBCPP NAME\fP for details.
.TP
.B \-D, \-\-define SYMBOL[=VAL]
Define a symbol for the preprocessor, if it is in use.
.TP
.B \-E
Preprocessor only. No compilation or linking is done.
.TP
.B \-F, \-\-files
Generate files.dat. This list is created by checking the parameters to the
precache_* functions.
.TP
.B \-g
Generate debugging info. Synonym for \fB\-\-code debug\fP.
.TP
.B \-h, \-\-help
Show summary of options.
.TP
.B \-I DIR
Add DIR to the list of directories for the preprocessor to search when looking
for include files.
.TP
.B \-\-include FILE
Process FILE as if \fB#include "FILE"\fP appeared as the first line of the
primary source file. See the \fBcpp\fP man page (\fB\-include\fP) for details.
.TP
.B \-L DIR
Add DIR to the search path used for finding libraries specified with \fB-l\fP.
.TP
.B \-l LIB
Add libLIB.a to the list of libraries to be used for resolving undefined
symbols. \fBqfcc\fP expects libraries to be \fBpak\fP files of \fBqfcc\fP
object files built using the \fBpak\fP utility. (\fBFIXME\fP: add sections
on object files and library files)
.TP
.B \-M, \-MD, \-MMD
Generate dependency info. Dependent on \fBcpp\fP version, so check \fBcpp\fP's
documentation.
.TP
.B \-N, \-\-notice OPTION,...
Set notice options. See \fBNOTICE OPTIONS\fP for details.
.TP
.B \-o, \-\-output\-file FILE
Specify output file name.
.TP
.B \-P, \-\-progs\-src FILE
File to use instead of \fBprogs.src\fP
.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 \-q, \-\-quiet
Inhibit some of \fBqfcc\fP's normal output.
.TP
.B \-r, \-\-relocatable
Incremental linking. Generate a larger object file from other object files
and libraries. (\fBFIXME\fP: add section describing the linker and its
operation)
.TP
.B \-S, \-\-save\-temps
Do not delete temporary files.
.TP
.B \-s, \-\-source DIR
look for \fBprogs.src\fP in DIR instead of the current directory.
.TP
.B \-\-traditional
Use traditional QuakeC syntax, semantics and \*(lqbugs\*(rq. Also implies the
\fBv6only\fP, \fBno-short-circuit\fP and \fBno-local-merging\fP code
generation options (see \fBCODE GENERATION OPTIONS\fP). This is the default
when using \fBprogs.src\fP.
.TP
.B \-U, \-\-undefine SYMBOL
Undefine a preprocessor symbol, if the preprocessor is in use.
.TP
.B \-V, \-\-version
Show the version of \fBqfcc\fP.
.TP
.B \-v, \-\-verbose
Display more output than usual.
.TP
.B \-W, \-\-warn OPTION,...
Set warning options. See \fBWARNING OPTIONS\fP for details.
.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. This has no effect when writing \fBprogs.dat\fP.
.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 \*(lqcopy on
write\*(rq\(emnever mind the bovine connotations)
.TP
.B cpp
Preprocess all input files with \fBcpp\fP. This includes the \fBprogs.src\fB
file when used.
.TP
.B 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 \fBqfcc\fP to generate this
information. It is written to a secondary file with the extension
\*(lqsym\*(rq\(emif your output file is \*(lqprogs.dat\*(rq, the symbol file
will be \*(lqprogs.sym\*(rq.
.TP
.B fast\-float
Use float values directly in \*(lqif\*(rq statements. Defaults to on. This
option is always enabled when using version 6 progs.
.TP
.B 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 \fBqcc\fP, but using much more
global data. Defaults to off for traditional mode, and on for advanced mode.
.TP
.B short\-circuit
Generate short circuit code for logical operators (\fB&&\fP and \fB||\fP). For
\fBA && B\fP, if \fBA\fP is false, the expression is known to be false and the
code for \fBB\fP will not be executed. Similar for \fBA || B\fP, but if
\fBA\fP is true, the expression is known to be true and the code for \fBB\fP
will not be executed. Defaults to off for traditional mode, and on for advanced
mode.
.TP
.B single-cpp
In \fBprogs.src\fP mode, when \fBcpp\fP is used, produce an intermediate file
that is a series of \fB#include\fP directives, one for each source file. This
file is then passed to \fBcpp\fP 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 \fBprogs.src\fP mode. Without this option,
each source file is independent with respect to the preprocessor. Defaults to
on.
.TP
.B vector\-calls
Where a function is called with just a vector, this causes the function call to
store three floats instead of one vector. 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.
.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). Defaults to on for traditional mode and off for
advanced mode.
.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 generation option above for a description
of what this means. 
.TP
.B error
Promote warnings to errors.
.TP
.B executable
Emit a warning when non-executable statements (eg, \fB==\fP used for
assignment) are encountered.
.TP
.B initializer
Emit a warning when too many structure/array initializer elements are given.
.TP
.B integer-divide
Emit a warning when both constants in a division operation are integers.
.TP
.B interface\-check
Emit a warning when a method is declared in an implementation but not in the
interface for a class.
.TP
.B precedence
Emit a warning when potentially ambiguous logic is used without parentheses.
.TP
.B traditional
Emit a warning when code that should be an error is allowed by traditional
\fBqcc\fP. Has effect only in traditional mode.
.TP
.B undef\-function
Emit a warning when a function is called, but has not yet been defined.
.TP
.B unimplemented
Emit a warning when a class method has not been implemented.
.TP
.B unused
Emit a warning for unused local variables.
.TP
.B uninited\-var
Emit a warning when a variable is read from that has not been initialized 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.
.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 should 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 \fBcpp\fP (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 \fBcpp\fP) or when \fBqfcc\fP has been misconfigured to call \fBcpp\fP
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
\fBcpp %d -o %o %i\fP.  This spec is similar in concept to a \fBprintf\fP
string. The name of the program may be either absolute (eg \fB/lib/cpp\fP) or
relative as the \fBPATH\fP will be searched.  Available substitutions:
.TP
.B %d
Mainly for defines (\-D, \-U and \-I) but \fB%d\fP will be replaced by all
\fBcpp\fP 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 hangs
This is almost always caused by qfcc incorrectly invoking \fBcpp\fP. Using the
\fB--cpp\fP option (refer to the \fBCPP NAME\fP section above), the correct
method for invoking \fBcpp\fP can be specified. Once you have found this,
please send the correct \fBcpp\fP command line, preferably along with the
output of \fBconfig.guess\fP, to the team.
.TP
.B qfcc is singing a bad 80s rap song to me. What's going on?
\*(lqice ice baby\*(rq is QuakeForge-speak for \*(lqInternal Compiler
Error\*(rq. It usually means there's a bug in \fBqfcc\fP, 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"
\fBprogs.src\fP
.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.