Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
QFCC(1)			 QuakeForge Developer's	Manual		       QFCC(1)

       qfcc - The QuakeForge Code Compiler

       qfcc [options] [files]

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

       qfcc takes the following	arguments:

	      Use advanced Ruamoko features.  This is the default  when	 using
	      separate compilation.

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

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

	      Allow extended keywords in traditional mode.

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

	      Generate _source_.frame files.  For each source file (listed ei-
	      ther  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 as-
	      sociated	 frame	 numbers.   Eg,	  player.qc    will    produce
	      player.framea.  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

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

	      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.

	      Generate progdefs.h. Forces --code crc.

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

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

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

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

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

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

	      Use traditional QuakeC syntax, semantics and "bugs".   Also  im-
	      plies  the  v6only,  no-short-circuit  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 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:

       cow    Allow assignment to initialized globals.	 In  Quake-C  and  Ru-
	      amoko,  a	 global	 that has been initialized to a	value is not a
	      variable,	but a named constant.  However,	qcc never  really  en-
	      forced 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"--never mind the	bovine

       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 en-
	      gine has the ability to load line	number and other debugging in-
	      formation	 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".

	      Use float	values directly	in "if"	statements.  Defaults  to  on.
	      This option is always enabled when using version 6 progs (v6only
	      is in effect).

	      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 be-
	      haviour 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.

	      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	tradi-
	      tional mode, and on for advanced mode.

	      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 di-
	      rectives in early	files affecting	later files, as	would  be  ex-
	      pected 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.

	      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  coordi-
	      nates  but  do  not match	entirely.  However, this will generate
	      slower code for such calls.

	      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.

       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  dis-
	      ables  compiler  features	(such as integers and string manipula-
	      tion support) that require extensions.  Defaults to on for  tra-
	      ditional mode and	off for	advanced mode.

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

       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 con-
	      stant.  See the description of the cow  code  generation	option
	      above for	a description of what this means.

       error  Promote warnings to errors.

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

	      Emit a warning when too many  structure/array  initializer  ele-
	      ments are	given.

	      Emit  a  warning when both constants in a	division operation are

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

	      Emit  a warning when potentially ambiguous logic is used without

	      Emit a warning when a local variable is redeclared.

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

	      Emit  a  warning when a function is called, but has not yet been

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

       unused Emit a warning for unused	local variables.

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

	      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.

       Notices	are  used to flag code constructs that may have	changed	seman-
       tics but	shouldn't be treated as	warnings.  They	are also used for  in-
       ternal  debugging  purposes,  so	if you see any cryptic notices,	please
       report them as a	bug (normal notices  should  be	 fairly	 self-explana-

       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.

       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 sys-
       tems) 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 tem-
	      porary files or not.

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

       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 se-
       lected 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 specified 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  fin-
       ished 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	exten-
       sions 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  in-
       termediate  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 compila-
       tion 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 ob-
       ject 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 be-
       ing 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 over-
       ridden using --traditional.

       When using cpp, each source file	is passed through the preprocessor in-
       dividually.   Each  file	 is truly independent of any other file	on the
       command line.

       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.

       \\     Backslash.

       \n     Line feed.

       \"     Double quote.

       \'     Single quote.

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

	      Hexadecimal  character  code, any	number of digits, but only the
	      least significant	byte will be used.

       \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 charac-
	      ters. Use	--qccx-escapes to select qccx behaviour.

       \e     Escape character (not in	quake  engines).  Equivalent  to  \x1b
	      (dull 9).

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

       \r     Carriage return. Equivalent to \x0d.

       \s     Toggle  "bold" characters	(add 0x80).  \t	Tab character. Equiva-
	      lent to \x09.

       \v     Vertical tab. Equivalent to \x0b.

       \^     Make the next character "bold" (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 brown left end. Equivalent to \x1d.
	      Use --qccx-escapes to select qccx	behaviour.

       \-     Brown center bit.	Equivalent to \x1e.

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

       \(     Left slider end. Equivalent to \x80.

       \=     Slider center. Equivalent	to \x81.

       \)     Right slider end.	Equivalent to \x82.

	      Decimal character	code.

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

       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	incor-

       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)).	Tradi-
       tional  mode  also  affects several code	generation options (as always,
       this can	be overridden):

       o   code	output is restricted to	version	6 progs	instructions

       o   short circuit boolean logic is disabled

       o   each	function has a private area of data for	 its  local  variables
	   (this wastes	a lot of data space).

       Advanced	 mode  is simply qfcc in its natural state.  Using --advanced,
       qfcc can	be put in to advanced mode while using the progs.src  compila-
       tion mode.

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

       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  Er-
	      ror".   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.


       quakeforge(1), pak(1)

       The original qcc	program, for compiling the QuakeC language, was	 writ-
       ten  by	Id  Software, Inc.  The	members	of the QuakeForge Project have
       modified	it to work with	a new, but very	similar	 language  called  Ru-

QuakeForge			28 April, 2004			       QFCC(1)


Want to link to this manual page? Use this URL:

home | help