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
.\" the Free Software Foundation, 675 Mass Ave, Cambridge, MA 02139, USA.
.\"
.TH QFCC 1 "October 26, 2001" QuakeForge "QuakeForge Developer's Manual"
.\" Please update the above date whenever this man page is modified.
.\"
.\" 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)
.SH NAME
qfcc \- The QuakeForge Code Compiler
.SH SYNOPSIS
.B qfcc
.RI [ options ]
.SH DESCRIPTION
\fBqfcc\fP compiles GameC 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 \-\-code OPTION,...
Set code generation options. See \fBCODE GENERATION OPTIONS\fP for details.
.TP
.B \-\-warn OPTION,...
Set warning options. See \fBWARNING OPTIONS\fP for details.
.TP
.B \-g, \-\-debug
Synonym for \fB\-\-code debug\fP.
.TP
.B \-h, \-\-help
Show summary of options.
.TP
.B \-V, \-\-version
Show the version of qfcc.
.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.
.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 QuakeC, 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 "FAQ"
.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)
.SH AUTHORS
The original \fBqcc\fP program was written by Id Software, Inc. The members of
the QuakeForge Project have modified it to work with extensions to the QuakeC
language. To minimize confusion, the name of the language compiled by \fBqfcc\fP
is called GameC.