qf/quakeforge
0
0
Fork 0
mirror of https://git.code.sf.net/p/quake/quakeforge synced 2025-06-01 17:12:15 +00:00
Code Issues Projects Releases Packages Wiki Activity

follow some of the roff rules...

Browse source
This commit is contained in:
Bill Currie 2007-04-11 12:04:53 +00:00 • committed by Jeff Teunissen
parent bac4096708
commit 7c938b3e91
1 changed files with 143 additions and 111 deletions
Download patch file Download diff file Expand all files Collapse all files

254
tools/qfcc/doc/man/qfcc.1
View file

@ -43,31 +43,35 @@ understand.
\fBqfcc\fP takes the following arguments: \fBqfcc\fP takes the following arguments:
.TP .TP
.B \-\-advanced .B \-\-advanced
Use advanced Ruamoko features. This is the default when using separate Use advanced Ruamoko features.
compilation. This is the default when using separate compilation.
.TP .TP
.B \-C, \-\-code OPTION,... .B \-C, \-\-code OPTION,...
Set code generation options. See \fBCODE GENERATION OPTIONS\fP for details. Set code generation options.
See \fBCODE GENERATION OPTIONS\fP for details.
.TP .TP
.B \-c .B \-c
Compile only, do not link. Can be used in either \fBprogs.src\fP or separate Compile only, do not link.
compilation modes. Can be used in either \fBprogs.src\fP or separate compilation modes.
.TP .TP
.B \-\-cpp CPPSPEC .B \-\-cpp CPPSPEC
\fBcpp\fP execution command line. See \fBCPP NAME\fP for details. \fBcpp\fP execution command line.
See \fBCPP NAME\fP for details.
.TP .TP
.B \-D, \-\-define SYMBOL[=VAL] .B \-D, \-\-define SYMBOL[=VAL]
Define a symbol for the preprocessor, if it is in use. Define a symbol for the preprocessor, if it is in use.
.TP .TP
.B \-E .B \-E
Preprocessor only. No compilation or linking is done. Preprocessor only.
No compilation or linking is done.
.TP .TP
.B \-F, \-\-files .B \-F, \-\-files
Generate files.dat. This list is created by checking the parameters to the Generate \fIfiles.dat\fP.
precache_* functions. This list is created by checking the parameters to the precache_* functions.
.TP .TP
.B \-g .B \-g
Generate debugging info. Synonym for \fB\-\-code debug\fP. Generate debugging info.
Synonym for \fB\-\-code debug\fP.
.TP .TP
.B \-h, \-\-help .B \-h, \-\-help
Show summary of options. Show summary of options.
@ -100,32 +104,35 @@ Set notice options. See \fBNOTICE OPTIONS\fP for details.
Specify output file name. Specify output file name.
.TP .TP
.B \-P, \-\-progs\-src FILE .B \-P, \-\-progs\-src FILE
File to use instead of \fBprogs.src\fP File to use instead of \fIprogs.src\fP.
.TP .TP
.B \-p, \-\-strip\-path NUM .B \-p, \-\-strip\-path NUM
Strip NUM leading path elements from file names. eg. -p 3 will strip Strip NUM leading path elements from file names. eg. -p 3 will strip the
the ../../../ from ../../../src/foo.r when embedding the source file name in .I ../../../
the output code. from
.I ../../../src/foo.r
when embedding the source file name in the output code.
.TP .TP
.B \-q, \-\-quiet .B \-q, \-\-quiet
Inhibit some of \fBqfcc\fP's normal output. Inhibit some of \fBqfcc\fP's normal output.
.TP .TP
.B \-r, \-\-relocatable .B \-r, \-\-relocatable
Incremental linking. Generate a larger object file from other object files Incremental linking.
and libraries. (\fBFIXME\fP: add section describing the linker and its Generate a larger object file from other object files and libraries.
operation) (\fBFIXME\fP: add section describing the linker and its operation)
.TP .TP
.B \-S, \-\-save\-temps .B \-S, \-\-save\-temps
Do not delete temporary files. Do not delete temporary files.
.TP .TP
.B \-s, \-\-source DIR .B \-s, \-\-source DIR
look for \fBprogs.src\fP in DIR instead of the current directory. look for \fIprogs.src\fP in DIR instead of the current directory.
.TP .TP
.B \-\-traditional .B \-\-traditional
Use traditional QuakeC syntax, semantics and \*(lqbugs\*(rq. Also implies the Use traditional QuakeC syntax, semantics and \*(lqbugs\*(rq.
\fBv6only\fP, \fBno-short-circuit\fP and \fBno-local-merging\fP code Also implies the \fBv6only\fP, \fBno-short-circuit\fP and
generation options (see \fBCODE GENERATION OPTIONS\fP). This is the default \fBno-local-merging\fP code generation options (see
when using \fBprogs.src\fP. \fBCODE GENERATION OPTIONS\fP).
This is the default when using \fBprogs.src\fP mode.
.TP .TP
.B \-U, \-\-undefine SYMBOL .B \-U, \-\-undefine SYMBOL
Undefine a preprocessor symbol, if the preprocessor is in use. Undefine a preprocessor symbol, if the preprocessor is in use.
@ -137,87 +144,100 @@ Show the version of \fBqfcc\fP.
Display more output than usual. Display more output than usual.
.TP .TP
.B \-W, \-\-warn OPTION,... .B \-W, \-\-warn OPTION,...
Set warning options. See \fBWARNING OPTIONS\fP for details. Set warning options.
See \fBWARNING OPTIONS\fP for details.
.TP .TP
.B \-z .B \-z
Compress object files when writing them. This is especially useful when Compress object files when writing them.
creating libraries, especially if using the object oriented features, but can This is especially useful when creating libraries, especially if using the
be quite slow. This has no effect when writing \fBprogs.dat\fP. object oriented features, but can be quite slow.
This has no effect when writing \fBprogs.dat\fP.
.SH "CODE GENERATION OPTIONS" .SH "CODE GENERATION OPTIONS"
Code generation options are processed in the order of their appearance on the Code generation options are processed in the order of their appearance on the
command line. Unsupported options are ignored. The following options are command line.
supported by \fBqfcc\fP's \fB\-\-code\fP argument: Unsupported options are ignored.
The following options are supported by \fBqfcc\fP's \fB\-\-code\fP argument:
.TP .TP
.B cow .B cow
Allow assignment to initialized globals. In Quake-C and Ruamoko, a global Allow assignment to initialized globals.
that has been initialized to a value is not a variable, but a named constant. In Quake-C and Ruamoko, a global that has been initialized to a value is not
However, \fBqcc\fP never really enforced this. The \fBcow\fP option allows a variable, but a named constant.
\fBqfcc\fP to gracefully cope with QuakeC source that assigns values to However, \fBqcc\fP never really enforced this.
initialized globals in this manner. (also known as \*(lqcopy on The \fBcow\fP option allows \fBqfcc\fP to gracefully cope with QuakeC source
write\*(rq\(emnever mind the bovine connotations) that assigns values to initialized globals in this manner.
(also known as \*(lqcopy on write\*(rq\(emnever mind the bovine connotations)
.TP .TP
.B cpp .B cpp
Preprocess all input files with \fBcpp\fP. This includes the \fBprogs.src\fB Preprocess all input files with \fBcpp\fP.
file when used. This includes the \fIprogs.src\fP file when used.
.TP .TP
.B debug .B debug
Generate debug code for QuakeForge engines. The QuakeForge engine has the Generate debug code for QuakeForge engines.
ability to load line number and other debugging information for use in The QuakeForge engine has the ability to load line number and other debugging
diagnosing progs crashes. This option tells \fBqfcc\fP to generate this information for use in diagnosing progs crashes.
information. It is written to a secondary file with the extension This option tells \fBqfcc\fP to generate this information.
\*(lqsym\*(rq\(emif your output file is \*(lqprogs.dat\*(rq, the symbol file It is written to a secondary file with the extension \*(lqsym\*(rq\(emif your
will be \*(lqprogs.sym\*(rq. output file is \*(lqprogs.dat\*(rq, the symbol file will be
\*(lqprogs.sym\*(rq.
.TP .TP
.B fast\-float .B fast\-float
Use float values directly in \*(lqif\*(rq statements. Defaults to on. This Use float values directly in \*(lqif\*(rq statements.
option is always enabled when using version 6 progs. Defaults to on.
This option is always enabled when using version 6 progs.
.TP .TP
.B local-merging .B local-merging
Clump the local variables from all functions into one block of data the size 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 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 space.
others, preserving the behaviour of traditional \fBqcc\fP, but using much more When off, each function's local variable block is separate from the others,
global data. Defaults to off for traditional mode, and on for advanced mode. 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 .TP
.B short\-circuit .B short\-circuit
Generate short circuit code for logical operators (\fB&&\fP and \fB||\fP). For Generate short circuit code for logical operators (\fB&&\fP and \fB||\fP).
\fBA && B\fP, if \fBA\fP is false, the expression is known to be false and the For \fBA && B\fP, if \fBA\fP is false, the expression is known to be false and
code for \fBB\fP will not be executed. Similar for \fBA || B\fP, but if the code for \fBB\fP will not be executed.
\fBA\fP is true, the expression is known to be true and the code for \fBB\fP Similar for \fBA || B\fP, but if \fBA\fP is true, the expression is known to
will not be executed. Defaults to off for traditional mode, and on for advanced be true and the code for \fBB\fP will not be executed.
mode. Defaults to off for traditional mode, and on for advanced mode.
.TP .TP
.B single-cpp .B single-cpp
In \fBprogs.src\fP mode, when \fBcpp\fP is used, produce an intermediate file 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 that is a series of \fB#include\fP directives, one for each source file.
file is then passed to \fBcpp\fP and the resulting output is compiled in one This file is then passed to \fBcpp\fP and the resulting output is compiled in
go. This results in preprocessor directives in early files affecting later one go.
files, as would be expected in \fBprogs.src\fP mode. Without this option, This results in preprocessor directives in early files affecting later files,
each source file is independent with respect to the preprocessor. Defaults to as would be expected in \fBprogs.src\fP mode.
on. Without this option, each source file is independent with respect to the
preprocessor.
Defaults to on.
.TP .TP
.B vector\-calls .B vector\-calls
Where a function is called with just a vector, this causes the function call to 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 store three floats instead of one vector.
pr_globals where those vectors contain many duplicate coordinates but do not This can save a good number of pr_globals where those vectors contain many
match entirely. However, this will generate slower code for such calls. duplicate coordinates but do not match entirely.
However, this will generate slower code for such calls.
.TP .TP
.B v6only .B v6only
Restrict the compiler to only version 6 progs (original Quake/QuakeWorld) 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 features.
older servers, as long as you have not used any QuakeForge-specific built-in This means that the compiled data file should be able to run on older servers,
functions. Also disables some of the compiler's features (like integers and as long as you have not used any QuakeForge-specific built-in functions.
string manipulation support). Defaults to on for traditional mode and off for Also disables some of the compiler's features (like integers and string
advanced mode. manipulation support).
Defaults to on for traditional mode and off for advanced mode.
.SH "WARNING OPTIONS" .SH "WARNING OPTIONS"
Warning options are processed in the order of their appearance on the command Warning options are processed in the order of their appearance on the command
line. Unsupported options are ignored. The following options are supported by line.
\fBqfcc\fP's \fB\-\-warn\fP argument: Unsupported options are ignored.
The following options are supported by \fBqfcc\fP's \fB\-\-warn\fP argument:
.TP .TP
.B cow .B cow
Emit a warning when the source assigns a value to a named constant. See the Emit a warning when the source assigns a value to a named constant.
description of the \fBcow\fP code generation option above for a description See the description of the \fBcow\fP code generation option above for a
of what this means. description of what this means.
.TP .TP
.B error .B error
Promote warnings to errors. Promote warnings to errors.
@ -241,7 +261,8 @@ Emit a warning when potentially ambiguous logic is used without parentheses.
.TP .TP
.B traditional .B traditional
Emit a warning when code that should be an error is allowed by traditional Emit a warning when code that should be an error is allowed by traditional
\fBqcc\fP. Has effect only in traditional mode. \fBqcc\fP.
Has effect only in traditional mode.
.TP .TP
.B undef\-function .B undef\-function
Emit a warning when a function is called, but has not yet been defined. Emit a warning when a function is called, but has not yet been defined.
@ -260,8 +281,8 @@ value.
Emit a warning when a function that takes a variable number of arguments is Emit a warning when a function that takes a variable number of arguments is
passed a constant of an integer type. passed a constant of an integer type.
.PP .PP
Any of the above can be prefixed with \fBno\-\fP to negate its meaning. There Any of the above can be prefixed with \fBno\-\fP to negate its meaning.
are also two special options: There are also two special options:
.TP .TP
.B all .B all
Turns on all warning options except \fBerror\fP. Turns on all warning options except \fBerror\fP.
@ -270,70 +291,81 @@ Turns on all warning options except \fBerror\fP.
Turns off all warning options except \fBerror\fP. Turns off all warning options except \fBerror\fP.
.SH "NOTICE OPTIONS" .SH "NOTICE OPTIONS"
Notices are used to flag code constructs that may have changed semantics but 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 shouldn't be treated as warnings.
purposes, so if you see any cryptic notices, please report them as a bug They are also used for internal debugging purposes, so if you see any cryptic
(normal notices should be fairly self-explanatory). notices, please report them as a bug (normal notices should be fairly
self-explanatory).
.TP .TP
.B none .B none
Silences all notice messages. Silences all notice messages.
.TP .TP
.B warn .B warn
Promote notices to warnings. If warnings are being treated as errors, so will Promote notices to warnings.
notices. If warnings are being treated as errors, so will notices.
Disabling warnings has no effect on this option.
.SH "CPP NAME" .SH "CPP NAME"
When preprocessing source files, \fBqfcc\fP calls \fBcpp\fP (the C When preprocessing source files, \fBqfcc\fP calls \fBcpp\fP (the C
preprocessor) with a configurable command line. This is useful when you wish preprocessor) with a configurable command line.
to use an alternative preprocessor (though it must be command line compatible This is useful when you wish to use an alternative preprocessor (though it
with \fBcpp\fP) or when \fBqfcc\fP has been misconfigured to call \fBcpp\fP must be command line compatible with \fBcpp\fP) or when \fBqfcc\fP has been
incorrectly for your operating system. If the latter is the case, please misconfigured to call \fBcpp\fP incorrectly for your operating system.
report the details (operating system, detection methods, correct execution If the latter is the case, please report the details (operating system,
specification). The base default execution spec (on most Linux systems) is detection methods, correct execution specification).
\fBcpp %d -o %o %i\fP. This spec is similar in concept to a \fBprintf\fP The base default execution spec (on most Linux systems) is
string. The name of the program may be either absolute (eg \fB/lib/cpp\fP) or \fBcpp %d -o %o %i\fP.
relative as the \fBPATH\fP will be searched. Available substitutions: 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 .TP
.B %d .B %d
Mainly for defines (\-D, \-U and \-I) but \fB%d\fP will be replaced by all 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. \fBcpp\fP options that \fBqfcc\fP passes to \fBcpp\fP
.TP .TP
.B %o .B %o
This will be replaced by the output file path. Could be either absolute or This will be replaced by the output file path.
relative, depending on whether \fBqfcc\fP is deleting temporary files or not. Could be either absolute or relative, depending on whether \fBqfcc\fP is
deleting temporary files or not.
.TP .TP
.B %i .B %i
This will be replaced by the input file path. Generally as given to \fBqfcc\fP. This will be replaced by the input file path.
Generally as given to \fBqfcc\fP.
.SH "FAQ" .SH "FAQ"
.TP .TP
.B Where did the name Ruamoko come from? .B Where did the name Ruamoko come from?
In Maori mythology, Ruamoko is the youngest child of Ranginui, the In Maori mythology, Ruamoko is the youngest child of Ranginui, the
Sky-father, and Papatuanuku, the Earth-mother. Ruamoko is the god of Sky-father, and Papatuanuku, the Earth-mother.
volcanoes and earthquakes \fB(Quake, get it?)\fP. For more information, see Ruamoko is the god of volcanoes and earthquakes \fB(Quake, get it?)\fP.
the Web site at <\fBhttp://maori.com/kmst1.htm\fP>. For more information, see the Web site at <\fBhttp://maori.com/kmst1.htm\fP>.
.TP .TP
.B qfcc hangs .B qfcc hangs
This is almost always caused by qfcc incorrectly invoking \fBcpp\fP. Using the This is almost always caused by qfcc incorrectly invoking \fBcpp\fP.
\fB--cpp\fP option (refer to the \fBCPP NAME\fP section above), the correct Using the \fB--cpp\fP option (refer to the \fBCPP NAME\fP section above), the
method for invoking \fBcpp\fP can be specified. Once you have found this, correct method for invoking \fBcpp\fP can be specified.
please send the correct \fBcpp\fP command line, preferably along with the Once you have found this, please send the correct \fBcpp\fP command line,
output of \fBconfig.guess\fP, to the team. preferably along with the output of \fBconfig.guess\fP, to the team.
.TP .TP
.B qfcc is singing a bad 80s rap song to me. What's going on? .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 \*(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 Error\*(rq.
to the team. It usually means there's a bug in \fBqfcc\fP, so please report it to the team.
.TP .TP
.B qfcc is mooing at me. What's wrong with you people? .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 The compiler doesn't like being treated like a slab of beef.
code you are trying to compile is using constants as if they weren't. 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 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 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 \fB\-\-code\fP, so it has its revenge by mooing out a warning.
like that. To disable the warning, pass \fBno-cow\fP to \fB\-\-warn\fP. Or something like that.
To disable the warning, pass \fBno-cow\fP to \fB\-\-warn\fP.
.SH "FILES" .SH "FILES"
\fBprogs.src\fP .I progs.src
.SH "SEE ALSO" .SH "SEE ALSO"
.BR quakeforge (1), pak (1) .BR quakeforge (1),
.BR pak (1)
.SH AUTHORS .SH AUTHORS
The original \fBqcc\fP program, for compiling the QuakeC language, was written 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 by Id Software, Inc.
work with a new, but very similar language called \fBRuamoko\fP. The members of the QuakeForge Project have modified it to work with a new,
but very similar language called \fBRuamoko\fP.