- switching MAN pages from troff format to Docbook/refentry

7 files changed, 8652 insertions, 7471 deletions

diff --git a/doc/man/MANIFEST b/doc/man/MANIFEST
index 8e69d1c..86a6b14 100644
--- a/doc/man/MANIFEST
+++ b/doc/man/MANIFEST
@@ -1,2 +1,2 @@
-scons.1
-sconsign.1
+scons.xml
+sconsign.xml
diff --git a/doc/man/scons-time.1 b/doc/man/scons-time.1
deleted file mode 100644
index feb66c5..0000000
--- a/doc/man/scons-time.1
+++ /dev/null
@@ -1,1017 +0,0 @@
-.\" __COPYRIGHT__
-.\"
-.\" Permission is hereby granted, free of charge, to any person obtaining
-.\" a copy of this software and associated documentation files (the
-.\" "Software"), to deal in the Software without restriction, including
-.\" without limitation the rights to use, copy, modify, merge, publish,
-.\" distribute, sublicense, and/or sell copies of the Software, and to
-.\" permit persons to whom the Software is furnished to do so, subject to
-.\" the following conditions:
-.\"
-.\" The above copyright notice and this permission notice shall be included
-.\" in all copies or substantial portions of the Software.
-.\"
-.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY
-.\" KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
-.\" WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
-.\" NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
-.\" LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
-.\" OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
-.\" WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
-.\"
-.\" __FILE__ __REVISION__ __DATE__ __DEVELOPER__
-.\"
-.\" ES - Example Start - indents and turns off line fill
-.de ES
-.RS
-.nf
-..
-.\" EE - Example End - ends indent and turns line fill back on
-.de EE
-.RE
-.fi
-..
-'\"==========================================================================
-.de SF
-.B scons-time func
-[\fB-h\fR]
-[\fB--chdir=\fIDIR\fR]
-[\fB-f \fIFILE\fR]
-[\fB--fmt=\fIFORMAT\fR]
-[\fB--func=\fINAME\fR]
-[\fB-p \fISTRING\fR]
-[\fB-t \fINUMBER\fR]
-[\fB--title= TITLE\fR]
-[\fIARGUMENTS\fR]
-..
-'\"--------------------------------------------------------------------------
-.de SY
-.B scons-time mem
-[\fB-h\fR]
-[\fB--chdir=\fIDIR\fR]
-[\fB-f \fIFILE\fR]
-[\fB--fmt=\fIFORMAT\fR]
-[\fB-p \fISTRING\fR]
-[\fB--stage=\fISTAGE\fR]
-[\fB-t \fINUMBER\fR]
-[\fB--title=\fITITLE\fR]
-[\fIARGUMENTS\fR]
-..
-'\"--------------------------------------------------------------------------
-.de SO
-.B scons-time obj
-[\fB-h\fR]
-[\fB--chdir=\fIDIR\fR]
-[\fB-f \fIFILE\fR]
-[\fB--fmt=\fIFORMAT\fR]
-[\fB-p \fISTRING\fR]
-[\fB--stage=\fISTAGE\fR]
-[\fB-t \fINUMBER\fR]
-[\fB--title=\fITITLE\fR]
-[\fIARGUMENTS\fR]
-..
-'\"--------------------------------------------------------------------------
-.de SR
-.B scons-time run
-[\fB-hnqv\fR]
-[\fB--aegis=\fIPROJECT\fR]
-[\fB-f \fIFILE\fR]
-[\fB--number=\fINUMBER\fR]
-[\fB--outdir=\fIOUTDIR\fR]
-[\fB-p \fISTRING\fR]
-[\fB--python=\fIPYTHON\fR]
-[\fB-s \fIDIR\fR]
-[\fB--scons=\fISCONS\fR]
-[\fB--svn=\fIURL\fR]
-[\fIARGUMENTS\fR]
-..
-'\"--------------------------------------------------------------------------
-.de ST
-.B scons-time time
-[\fB-h\fR]
-[\fB--chdir=\fIDIR\fR]
-[\fB-f \fIFILE\fR]
-[\fB--fmt=\fIFORMAT\fR]
-[\fB-p \fISTRING\fR]
-[\fB-t \fINUMBER\fR]
-[\fB--title=\fITITLE\fR]
-[\fB--which=\fIWHICH\fR]
-[\fIARGUMENTS\fR]
-..
-.TH SCONS-TIME 1 "__MONTH_YEAR__"
-.SH NAME
-scons-time \- generate and display SCons timing information
-'\"==========================================================================
-.SH SYNOPSIS
-.B scons-time
-.IR subcommand
-[
-.IR options ...
-]
-[
-.IR arguments ...
-]
-'\"--------------------------------------------------------------------------
-.SS "Generating Timing Information"
-.SR
-'\"--------------------------------------------------------------------------
-.SS "Extracting Function Timings"
-.SF
-'\"--------------------------------------------------------------------------
-.SS "Extracting Memory Statistics"
-.SY
-'\"--------------------------------------------------------------------------
-.SS "Extracting Object Counts"
-.SO
-'\"--------------------------------------------------------------------------
-.SS "Extracting Execution Times"
-.ST
-'\"--------------------------------------------------------------------------
-.SS "Help Text"
-.B scons-time help
-.I SUBCOMMAND
-[...]
-'\"==========================================================================
-.SH DESCRIPTION
-The 
-.B scons-time
-command runs an SCons configuration
-through a standard set of profiled timings
-and can extract and graph information from the
-resulting profiles and log files of those timings.
-The action to be performed by the
-.B scons-time
-script is specified
-by a subcommand, the first argument on the command line.
-See the
-.B SUBCOMMANDS
-section below for information about the operation
-of specific subcommands.
-.P
-The basic way to use
-.B scons-time
-is to run the
-.B scons-time run
-subcommand
-(possibly multiple times)
-to generate profile and log file output,
-and then use one of the other
-subcommands to display the results
-captured in the profiles and log files
-for a particular kind of information:
-function timings
-(the
-.B scons-time func
-subcommand),
-total memory used
-(the
-.B scons-time mem
-subcommand),
-object counts
-(the
-.B scons-time obj
-subcommand)
-and overall execution time
-(the
-.B scons-time time
-subcommand).
-Options exist to place and find the
-profiles and log files in separate directories,
-to generate the output in a format suitable
-for graphing with the
-.BR gnuplot (1)
-program,
-and so on.
-.P
-There are two basic ways the
-.B scons-time run
-subcommand
-is intended to be used
-to gather timing statistics
-for a configuration.
-One is to use the
-.B --svn=
-option to test a configuration against
-a list of revisions from the SCons Subversion repository.
-This will generate a profile and timing log file
-for every revision listed with the
-.B --number=
-option,
-and can be used to look at the
-impact of commited changes to the
-SCons code base on a particular
-configuration over time.
-.P
-The other way is to profile incremental changes to a
-local SCons code base during a development cycle--that is,
-to look at the performance impact of changes
-you're making in the local tree.
-In this mode,
-you run the
-.B scons-time run
-subcommand
-.I without
-the
-.B --svn=
-option,
-in which case it simply looks in the profile/log file output directory
-(the current directory by default)
-and automatically figures out the
-.I next
-run number for the output profile and log file.
-Used in this way,
-the development cycle goes something like:
-make a change to SCons;
-run
-.B scons-time run
-to profile it against a specific configuration;
-make another change to SCons;
-run
-.B scons-time run
-again to profile it;
-etc.
-'\"==========================================================================
-.SH OPTIONS
-The
-.B scons-time
-command only supports a few global options:
-.TP
--h, --help
-Displays the global help text and exits,
-identical to the
-.B scons-time help
-subcommand.
-.TP
--V, --version
-Displays the
-.B scons-time
-version and exits.
-.P
-Most functionality is controlled by options
-to the individual subcommands.
-See the next section for information
-about individual subcommand options.
-'\"==========================================================================
-.SH SUBCOMMANDS
-The
-.B scons-time
-command supports the following
-individual subcommands.
-'\"--------------------------------------------------------------------------
-.SS "The func Subcommand"
-.SF
-.P
-The
-.B scons-time func
-subcommand displays timing information
-for a specific Python function within SCons.
-By default, it extracts information about the
-.BR _main ()
-function,
-which includes the Python profiler timing
-for all of SCons.
-.P
-The
-.B scons-time func
-subcommand extracts function timing information
-from all the specified file arguments,
-which should be Python profiler output files.
-(Normally, these would be
-.B *.prof
-files generated by the
-.B scons-time run
-subcommand,
-but they can actually be generated
-by any Python profiler invocation.)
-All file name arguments will be
-globbed for on-disk files.
-.P
-If no arguments are specified,
-then function timing information
-will be extracted from all
-.B *.prof
-files,
-or the subset of them
-with a prefix specified by the
-.B -p
-option.
-.P
-Options include:
-.TP
--C DIRECTORY, --chdir=DIRECTORY
-Changes to the specified
-.I DIRECTORY
-before looking for the specified files
-(or files that match the specified patterns).
-.TP
--f FILE, --file=FILE
-Reads configuration information from the specified
-.IR FILE .
-.TP
--fmt=FORMAT, --format=FORMAT
-Reports the output in the specified
-.IR FORMAT .
-The formats currently supported are
-.B ascii
-(the default)
-and
-.BR gnuplot .
-.TP
---func=NAME
-Extracts timings for the specified function
-.IR NAME .
-The default is to report cumulative timings for the
-.BR _main ()
-function,
-which contains the entire SCons run.
-.TP
--h, --help
-Displays help text for the
-.B scons-time func
-subcommand.
-.TP
--p STRING, --prefix=STRING
-Specifies the prefix string for profiles
-from which to extract function timing information.
-This will be used to search for profiles
-if no arguments are specified on the command line.
-.TP
--t NUMBER, --tail=NUMBER
-Only extracts function timings from the last
-.I NUMBER
-files.
-'\"--------------------------------------------------------------------------
-.SS "The help Subcommand"
-.B scons-time help
-.I SUBCOMMAND
-[...]
-The
-.B help
-subcommand prints help text for any
-other subcommands listed as later arguments on the command line.
-'\"--------------------------------------------------------------------------
-.SS "The mem Subcommand"
-.SY
-.P
-The
-.B scons-time mem
-subcommand displays how much memory SCons uses.
-.P
-The
-.B scons-time mem
-subcommand extracts memory use information
-from all the specified file arguments,
-which should be files containing output from
-running SCons with the
-.B --debug=memory
-option.
-(Normally, these would be
-.B *.log
-files generated by the
-.B scons-time run
-subcommand.)
-All file name arguments will be
-globbed for on-disk files.
-.P
-If no arguments are specified,
-then memory information
-will be extracted from all
-.B *.log
-files,
-or the subset of them
-with a prefix specified by the
-.B -p
-option.
-.P
-.TP
--C DIR, --chdir=DIR
-Changes to the specified
-.I DIRECTORY
-before looking for the specified files
-(or files that match the specified patterns).
-.TP
--f FILE, --file=FILE
-Reads configuration information from the specified
-.IR FILE .
-.TP
--fmt=FORMAT, --format=FORMAT
-Reports the output in the specified
-.IR FORMAT .
-The formats currently supported are
-.B ascii
-(the default)
-and
-.BR gnuplot .
-.TP
--h, --help
-Displays help text for the
-.B scons-time mem
-subcommand.
-.TP
--p STRING, --prefix=STRING
-Specifies the prefix string for log files
-from which to extract memory usage information.
-This will be used to search for log files
-if no arguments are specified on the command line.
-.TP
---stage=STAGE
-Prints the memory used at the end of the specified
-.IR STAGE :
-.B pre-read
-(before the SConscript files are read),
-.B post-read ,
-(after the SConscript files are read),
-.B pre-build
-(before any targets are built)
-or
-.B post-build
-(after any targets are built).
-If no
-.B --stage
-option is specified,
-the default behavior is
-.BR post-build ,
-which reports the final amount of memory
-used by SCons during each run.
-.TP
--t NUMBER, --tail=NUMBER
-Only reports memory statistics from the last
-.I NUMBER
-files.
-'\"--------------------------------------------------------------------------
-.SS "The obj Subcommand"
-.SO
-.P
-The
-.B scons-time obj
-subcommand displays how many objects of a specific named type
-are created by SCons.
-.P
-The
-.B scons-time obj
-subcommand extracts object counts
-from all the specified file arguments,
-which should be files containing output from
-running SCons with the
-.B --debug=count
-option.
-(Normally, these would be
-.B *.log
-files generated by the
-.B scons-time run
-subcommand.)
-All file name arguments will be
-globbed for on-disk files.
-.P
-If no arguments are specified,
-then object counts
-will be extracted from all
-.B *.log
-files,
-or the subset of them
-with a prefix specified by the
-.B -p
-option.
-.TP
--C DIR, --chdir=DIR
-Changes to the specified
-.I DIRECTORY
-before looking for the specified files
-(or files that match the specified patterns).
-.TP
--f FILE, --file=FILE
-Reads configuration information from the specified
-.IR FILE .
-.TP
--fmt=FORMAT, --format=FORMAT
-Reports the output in the specified
-.IR FORMAT .
-The formats currently supported are
-.B ascii
-(the default)
-and
-.BR gnuplot .
-.TP
--h, --help
-Displays help text for the
-.B scons-time obj
-subcommand.
-.TP
--p STRING, --prefix=STRING
-Specifies the prefix string for log files
-from which to extract object counts.
-This will be used to search for log files
-if no arguments are specified on the command line.
-.TP
---stage=STAGE
-Prints the object count at the end of the specified
-.IR STAGE :
-.B pre-read
-(before the SConscript files are read),
-.B post-read ,
-(after the SConscript files are read),
-.B pre-build
-(before any targets are built)
-or
-.B post-build
-(after any targets are built).
-If no
-.B --stage
-option is specified,
-the default behavior is
-.BR post-build ,
-which reports the final object count during each run.
-.TP
--t NUMBER, --tail=NUMBER
-Only reports object counts from the last
-.I NUMBER
-files.
-'\"--------------------------------------------------------------------------
-.SS "The run Subcommand"
-.SR
-The
-.B scons-time run
-subcommand is the basic subcommand
-for profiling a specific configuration
-against a version of SCons.
-.P
-The configuration to be tested
-is specified as a list of files
-or directories that will be unpacked or copied
-into a temporary directory
-in which SCons will be invoked.
-The
-.B scons-time run
-subcommand understands file suffixes like
-.BR .tar ,
-.BR .tar.gz ,
-.BR .tgz
-and
-.BR .zip
-and will unpack their contents into a temporary directory.
-If more than one argument is specified,
-each one will be unpacked or copied
-into the temporary directory "on top of"
-the previous archives or directories,
-so the expectation is that multiple
-specified archives share the same directory layout.
-.P
-Once the file or directory arguments are unpacked or
-copied to the temporary directory,
-the
-.B scons-time run
-subcommand runs the
-requested version of SCons
-against the configuration
-three times:
-.TP
-Startup
-SCons is run with the
-.B --help
-option so that just the SConscript files are read,
-and then the default help text is printed.
-This profiles just the perceived "overhead" of starting up SCons
-and processing the SConscript files.
-.TP
-Full build
-SCons is run to build everything specified in the configuration.
-Specific targets to be passed in on the command l ine
-may be specified by the
-.B targets
-keyword in a configuration file; see below for details.
-.TP
-Rebuild
-SCons is run again on the same just-built directory.
-If the dependencies in the SCons configuration are correct,
-this should be an up-to-date, "do nothing" rebuild.
-.P
-Each invocation captures the output log file and a profile.
-.P
-The
-.B scons-time run
-subcommand supports the following options:
-.TP
---aegis=PROJECT
-Specifies the Aegis
-.I PROJECT
-from which the
-version(s) of
-.B scons
-being timed will be extracted.
-When
-.B --aegis
-is specified, the
-.BI --number= NUMBER
-option specifies delta numbers
-that will be tested.
-Output from each invocation run will be placed in file
-names that match the Aegis delta numbers.
-If the
-.B --number=
-option is not specified,
-then the default behavior is to time the
-tip of the specified
-.IR PROJECT .
-.TP
--f FILE, --file=FILE
-Reads configuration information from the specified
-.IR FILE .
-This often provides a more convenient way to specify and
-collect parameters associated with a specific timing configuration
-than specifying them on the command line.
-See the
-.B CONFIGURATION FILE
-section below
-for information about the configuration file parameters.
-.TP
--h, --help
-Displays help text for the
-.B scons-time run
-subcommand.
-.TP
--n, --no-exec
-Do not execute commands,
-just printing the command-line equivalents of what would be executed.
-Note that the
-.B scons-time
-script actually executes its actions in Python,
-where possible,
-for portability.
-The commands displayed are UNIX
-.I equivalents
-of what it's doing.
-.TP
---number=NUMBER
-Specifies the run number to be used in the names of
-the log files and profile outputs generated by this run.
-.IP
-When used in conjuction with the
-.BI --aegis= PROJECT
-option,
-.I NUMBER
-specifies one or more comma-separated Aegis delta numbers
-that will be retrieved automatically from the specified Aegis
-.IR PROJECT .
-.IP
-When used in conjuction with the
-.BI --svn= URL
-option,
-.I NUMBER
-specifies one or more comma-separated Subversion revision numbers
-that will be retrieved automatically from the Subversion
-repository at the specified
-.IR URL .
-Ranges of delta or revision numbers
-may be specified be separating two numbers
-with a hyphen
-.RB ( \- ).
-.P
-Example:
-.ES
-% scons-time run --svn=http://scons.tigris.org/svn/trunk --num=1247,1249-1252 .
-.EE
-.TP
--p STRING, --prefix=STRING
-Specifies the prefix string to be used for all of the log files
-and profiles generated by this run.
-The default is derived from the first
-specified argument:
-if the first argument is a directory,
-the default prefix is the name of the directory;
-if the first argument is an archive
-(tar or zip file),
-the default prefix is the the base name of the archive,
-that is, what remains after stripping the archive suffix
-.RB ( .tgz ", " .tar.gz " or " .zip ).
-.TP
---python=PYTHON
-Specifies a path to the Python executable to be used
-for the timing runs.
-The default is to use the same Python executable that
-is running the
-.B scons-time
-command itself.
-.TP
--q, --quiet
-Suppresses display of the command lines being executed.
-.TP
--s DIR, --subdir=DIR
-Specifies the name of directory or subdirectory
-from which the commands should be executed.
-The default is XXX
-.TP
---scons=SCONS
-Specifies a path to the SCons script to be used
-for the timing runs.
-The default is XXX
-.TP
---svn=URL, --subversion=URL
-Specifies the
-.I URL
-of the Subversion repository from which the
-version(s) of
-.B scons
-being timed will be extracted.
-When
-.B --svn
-is specified, the
-.BI --number= NUMBER
-option specifies revision numbers
-that will be tested.
-Output from each invocation run will be placed in file
-names that match the Subversion revision numbers.
-If the
-.B --number=
-option is not specified,
-then the default behavior is to time the
-.B HEAD
-of the specified
-.IR URL .
-.TP
--v, --verbose
-Displays the output from individual commands to the screen
-(in addition to capturing the output in log files).
-'\"--------------------------------------------------------------------------
-.SS "The time Subcommand"
-.ST
-.P
-The
-.B scons-time time
-subcommand displays SCons execution times
-as reported by the
-.B scons --debug=time
-option.
-.P
-The
-.B scons-time time
-subcommand extracts SCons timing
-from all the specified file arguments,
-which should be files containing output from
-running SCons with the
-.B --debug=time
-option.
-(Normally, these would be
-.B *.log
-files generated by the
-.B scons-time run
-subcommand.)
-All file name arguments will be
-globbed for on-disk files.
-.P
-If no arguments are specified,
-then execution timings
-will be extracted from all
-.B *.log
-files,
-or the subset of them
-with a prefix specified by the
-.B -p
-option.
-.TP
--C DIR, --chdir=DIR
-Changes to the specified
-.I DIRECTORY
-before looking for the specified files
-(or files that match the specified patterns).
-.TP
--f FILE, --file=FILE
-Reads configuration information from the specified
-.IR FILE .
-.TP
--fmt=FORMAT, --format=FORMAT
-Reports the output in the specified
-.IR FORMAT .
-The formats currently supported are
-.B ascii
-(the default)
-and
-.BR gnuplot .
-.TP
--h, --help
-Displays help text for the
-.B scons-time time
-subcommand.
-.TP
--p STRING, --prefix=STRING
-Specifies the prefix string for log files
-from which to extract execution timings.
-This will be used to search for log files
-if no arguments are specified on the command line.
-.TP
--t NUMBER, --tail=NUMBER
-Only reports object counts from the last
-.I NUMBER
-files.
-.TP
---which=WHICH
-Prints the execution time for the specified
-.IR WHICH
-value:
-.B total
-(the total execution time),
-.B SConscripts
-(total execution time for the SConscript files themselves),
-.B SCons
-(exectuion time in SCons code itself)
-or
-.B commands
-(execution time of the commands and other actions
-used to build targets).
-If no
-.B --which
-option is specified,
-the default behavior is
-.BR total ,
-which reports the total execution time for each run.
-'\"==========================================================================
-.SH CONFIGURATION FILE
-Various
-.B scons-time
-subcommands can read information from a specified
-configuration file when passed the
-.B \-f
-or
-.B \--file
-options.
-The configuration file is actually executed as a Python script.
-Setting Python variables in the configuration file
-controls the behavior of the
-.B scons-time
-script more conveniently than having to specify
-command-line options or arguments for every run,
-and provides a handy way to "shrink-wrap"
-the necessary information for producing (and reporting)
-consistent timing runs for a given configuration.
-.TP
-.B aegis
-The Aegis executable for extracting deltas.
-The default is simply
-.BR aegis .
-.TP
-.B aegis_project
-The Aegis project from which deltas should be extracted.
-The default is whatever is specified
-with the
-.B --aegis=
-command-line option.
-.TP
-.B archive_list
-A list of archives (files or directories)
-that will be copied to the temporary directory
-in which SCons will be invoked.
-.BR .tar ,
-.BR .tar.gz ,
-.BR .tgz
-and
-.BR .zip
-files will have their contents unpacked in
-the temporary directory.
-Directory trees and files will be copied as-is.
-.TP
-.B initial_commands
-A list of commands that will be executed
-before the actual timed
-.B scons
-runs.
-This can be used for commands that are necessary
-to prepare the source tree\-for example,
-creating a configuration file
-that should not be part of the timed run.
-.TP
-.B key_location
-The location of the key on Gnuplot graphing information
-generated with the
-.BR --format=gnuplot
-option.
-The default is
-.BR "bottom left" .
-.TP
-.B prefix
-The file name prefix to be used when
-running or extracting timing for this configuration.
-.TP
-.B python
-The path name of the Python executable
-to be used when running or extracting information
-for this configuration.
-The default is the same version of Python
-used to run the SCons
-.TP
-.B scons
-The path name of the SCons script to be used
-when running or extracting information
-for this configuration.
-The default is simply
-.BR scons .
-.TP
-.B scons_flags
-The
-.B scons
-flags used when running SCons to collect timing information.
-The default value is
-.BR "--debug=count --debug=memory --debug=time --debug=memoizer" .
-.TP
-.B scons_lib_dir
-.TP
-.B scons_wrapper
-.TP
-.B startup_targets
-.TP
-.B subdir
-The subdirectory of the project into which the
-.B scons-time
-script should change
-before executing the SCons commands to time.
-.TP
-.B subversion_url
-The Subversion URL from
-.TP
-.B svn
-The subversion executable used to
-check out revisions of SCons to be timed.
-The default is simple
-.BR svn .
-.TP
-.B svn_co_flag
-.TP
-.B tar
-.TP
-.B targets
-A string containing the targets that should be added to
-the command line of every timed
-.B scons
-run.
-This can be used to restrict what's being timed to a
-subset of the full build for the configuration.
-.TP
-.B targets0
-.TP
-.B targets1
-.TP
-.B targets2
-.TP
-.B title
-.TP
-.B unzip
-.TP
-.B verbose
-.TP
-.B vertical_bars
-'\"--------------------------------------------------------------------------
-.SS Example
-Here is an example
-.B scons-time
-configuration file
-for a hypothetical sample project:
-.P
-.ES
-# The project doesn't use SCons natively (yet), so we're
-# timing a separate set of SConscript files that we lay
-# on top of the vanilla unpacked project tarball.
-arguments = ['project-1.2.tgz', 'project-SConscripts.tar']
-
-# The subdirectory name contains the project version number,
-# so tell scons-time to chdir there before building.
-subdir = 'project-1.2'
-
-# Set the prefix so output log files and profiles are named:
-#     project-000-[012].{log,prof}
-#     project-001-[012].{log,prof}
-# etc.
-prefix = 'project'
-
-# The SConscript files being tested don't do any SConf
-# configuration, so run their normal ./configure script
-# before we invoke SCons.
-initial_commands = [
-    './configure',
-]
-
-# Only time building the bin/project executable.
-targets = 'bin/project'
-
-# Time against SCons revisions of the branches/core branch
-subversion_url = 'http://scons.tigris.org/svn/scons/branches/core'
-.EE
-'\"==========================================================================
-.SH ENVIRONMENT
-The
-.B scons-time
-script uses the following environment variables:
-.TP
-.B PRESERVE
-If this value is set,
-the
-.B scons-time
-script will
-.I not
-remove the temporary directory or directories
-in which it builds the specified configuration
-or downloads a specific version of SCons.
-'\"==========================================================================
-.SH "SEE ALSO"
-.BR gnuplot (1),
-.BR scons (1)
-
-.SH AUTHORS
-Steven Knight <knight at baldmt dot com>
diff --git a/doc/man/scons-time.xml b/doc/man/scons-time.xml
new file mode 100644
index 0000000..6227e25
--- /dev/null
+++ b/doc/man/scons-time.xml
@@ -0,0 +1,1283 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+                   "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
+<!-- lifted from troff+man by doclifter -->
+<refentry id='sconstime1'>
+<!--  __COPYRIGHT__ -->
+
+<!--  Permission is hereby granted, free of charge, to any person obtaining -->
+<!--  a copy of this software and associated documentation files (the -->
+<!--  "Software"), to deal in the Software without restriction, including -->
+<!--  without limitation the rights to use, copy, modify, merge, publish, -->
+<!--  distribute, sublicense, and/or sell copies of the Software, and to -->
+<!--  permit persons to whom the Software is furnished to do so, subject to -->
+<!--  the following conditions: -->
+
+<!--  The above copyright notice and this permission notice shall be included -->
+<!--  in all copies or substantial portions of the Software. -->
+
+<!--  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY -->
+<!--  KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE -->
+<!--  WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND -->
+<!--  NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE -->
+<!--  LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION -->
+<!--  OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION -->
+<!--  WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. -->
+
+<!--  __FILE__ __REVISION__ __DATE__ __DEVELOPER__ -->
+
+<!--  ES \- Example Start \- indents and turns off line fill -->
+<!--  EE \- Example End \- ends indent and turns line fill back on -->
+<!-- '\"========================================================================== -->
+<!-- '\"\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- -->
+<!-- '\"\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- -->
+<!-- '\"\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- -->
+<!-- '\"\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- -->
+<refmeta>
+<refentrytitle>SCONS-TIME</refentrytitle>
+<manvolnum>1</manvolnum>
+<refmiscinfo class='source'>__MONTH_YEAR__</refmiscinfo>
+</refmeta>
+<refnamediv id='name'>
+<refname>scons-time</refname>
+<refpurpose>generate and display SCons timing information</refpurpose>
+</refnamediv>
+<refsynopsisdiv id='synopsis'>
+<cmdsynopsis>
+  <command>scons-time</command>    
+    <arg choice='plain'><replaceable>subcommand</replaceable></arg>
+    <arg choice='opt' rep='repeat'><replaceable>options</replaceable></arg>
+    <arg choice='opt' rep='repeat'><replaceable>arguments</replaceable></arg>
+</cmdsynopsis>
+</refsynopsisdiv>
+
+<!-- body begins here -->
+
+<refsect1 id='generating_timing_information'><title>Generating Timing Information</title>
+<para><emphasis remap='B'>scons-time run</emphasis>
+[<option>-hnqv</option>]
+[<option>--aegis=</option><replaceable>PROJECT</replaceable>]
+[<option>-f </option><emphasis remap='I'>FILE</emphasis>]
+[<option>--number=</option><replaceable>NUMBER</replaceable>]
+[<option>--outdir=</option><replaceable>OUTDIR</replaceable>]
+[<option>-p </option><emphasis remap='I'>STRING</emphasis>]
+[<option>--python=</option><replaceable>PYTHON</replaceable>]
+[<option>-s </option><emphasis remap='I'>DIR</emphasis>]
+[<option>--scons=</option><replaceable>SCONS</replaceable>]
+[<option>--svn=</option><replaceable>URL</replaceable>]
+[<emphasis remap='I'>ARGUMENTS</emphasis>]</para>
+<!-- '\"\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- -->
+
+<refsect2 id='extracting_function_timings'><title>Extracting Function Timings</title>
+<para><emphasis remap='B'>scons-time func</emphasis>
+[<option>-h</option>]
+[<option>--chdir=</option><replaceable>DIR</replaceable>]
+[<option>-f </option><emphasis remap='I'>FILE</emphasis>]
+[<option>--fmt=</option><replaceable>FORMAT</replaceable>]
+[<option>--func=</option><replaceable>NAME</replaceable>]
+[<option>-p </option><emphasis remap='I'>STRING</emphasis>]
+[<option>-t </option><emphasis remap='I'>NUMBER</emphasis>]
+[<option>--title= TITLE</option>]
+[<emphasis remap='I'>ARGUMENTS</emphasis>]</para>
+<!-- '\"\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- -->
+</refsect2>
+
+<refsect2 id='extracting_memory_statistics'><title>Extracting Memory Statistics</title>
+<para><emphasis remap='B'>scons-time mem</emphasis>
+[<option>-h</option>]
+[<option>--chdir=</option><replaceable>DIR</replaceable>]
+[<option>-f </option><emphasis remap='I'>FILE</emphasis>]
+[<option>--fmt=</option><replaceable>FORMAT</replaceable>]
+[<option>-p </option><emphasis remap='I'>STRING</emphasis>]
+[<option>--stage=</option><replaceable>STAGE</replaceable>]
+[<option>-t </option><emphasis remap='I'>NUMBER</emphasis>]
+[<option>--title=</option><replaceable>TITLE</replaceable>]
+[<emphasis remap='I'>ARGUMENTS</emphasis>]</para>
+<!-- '\"\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- -->
+</refsect2>
+
+<refsect2 id='extracting_object_counts'><title>Extracting Object Counts</title>
+<para><emphasis remap='B'>scons-time obj</emphasis>
+[<option>-h</option>]
+[<option>--chdir=</option><replaceable>DIR</replaceable>]
+[<option>-f </option><emphasis remap='I'>FILE</emphasis>]
+[<option>--fmt=</option><replaceable>FORMAT</replaceable>]
+[<option>-p </option><emphasis remap='I'>STRING</emphasis>]
+[<option>--stage=</option><replaceable>STAGE</replaceable>]
+[<option>-t </option><emphasis remap='I'>NUMBER</emphasis>]
+[<option>--title=</option><replaceable>TITLE</replaceable>]
+[<emphasis remap='I'>ARGUMENTS</emphasis>]</para>
+<!-- '\"\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- -->
+</refsect2>
+
+<refsect2 id='extracting_execution_times'><title>Extracting Execution Times</title>
+<para><emphasis remap='B'>scons-time time</emphasis>
+[<option>-h</option>]
+[<option>--chdir=</option><replaceable>DIR</replaceable>]
+[<option>-f </option><emphasis remap='I'>FILE</emphasis>]
+[<option>--fmt=</option><replaceable>FORMAT</replaceable>]
+[<option>-p </option><emphasis remap='I'>STRING</emphasis>]
+[<option>-t </option><emphasis remap='I'>NUMBER</emphasis>]
+[<option>--title=</option><replaceable>TITLE</replaceable>]
+[<option>--which=</option><replaceable>WHICH</replaceable>]
+[<emphasis remap='I'>ARGUMENTS</emphasis>]</para>
+<!-- '\"\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- -->
+</refsect2>
+
+<refsect2 id='help_text'><title>Help Text</title>
+<para><emphasis remap='B'>scons-time help</emphasis>
+<emphasis remap='I'>SUBCOMMAND</emphasis>
+[...]</para>
+<!-- '\"========================================================================== -->
+</refsect2>
+</refsect1>
+
+<refsect1 id='description'><title>DESCRIPTION</title>
+<para>The 
+<command>scons-time</command>
+command runs an SCons configuration
+through a standard set of profiled timings
+and can extract and graph information from the
+resulting profiles and log files of those timings.
+The action to be performed by the
+<command>scons-time</command>
+script is specified
+by a subcommand, the first argument on the command line.
+See the
+<link linkend="subcommands">SUBCOMMANDS</link>
+section below for information about the operation
+of specific subcommands.</para>
+
+<para>The basic way to use
+<command>scons-time</command>
+is to run the
+<emphasis remap='B'>scons-time run</emphasis>
+subcommand
+(possibly multiple times)
+to generate profile and log file output,
+and then use one of the other
+subcommands to display the results
+captured in the profiles and log files
+for a particular kind of information:
+function timings
+(the
+<emphasis remap='B'>scons-time func</emphasis>
+subcommand),
+total memory used
+(the
+<emphasis remap='B'>scons-time mem</emphasis>
+subcommand),
+object counts
+(the
+<emphasis remap='B'>scons-time obj</emphasis>
+subcommand)
+and overall execution time
+(the
+<emphasis remap='B'>scons-time time</emphasis>
+subcommand).
+Options exist to place and find the
+profiles and log files in separate directories,
+to generate the output in a format suitable
+for graphing with the
+<citerefentry><refentrytitle>gnuplot</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+program,
+and so on.</para>
+
+<para>There are two basic ways the
+<emphasis remap='B'>scons-time run</emphasis>
+subcommand
+is intended to be used
+to gather timing statistics
+for a configuration.
+One is to use the
+<option>--svn=</option>
+option to test a configuration against
+a list of revisions from the SCons Subversion repository.
+This will generate a profile and timing log file
+for every revision listed with the
+<option>--number=</option>
+option,
+and can be used to look at the
+impact of commited changes to the
+SCons code base on a particular
+configuration over time.</para>
+
+<para>The other way is to profile incremental changes to a
+local SCons code base during a development cycle--that is,
+to look at the performance impact of changes
+you're making in the local tree.
+In this mode,
+you run the
+<emphasis remap='B'>scons-time run</emphasis>
+subcommand
+<emphasis remap='I'>without</emphasis>
+the
+<option>--svn=</option>
+option,
+in which case it simply looks in the profile/log file output directory
+(the current directory by default)
+and automatically figures out the
+<emphasis remap='I'>next</emphasis>
+run number for the output profile and log file.
+Used in this way,
+the development cycle goes something like:
+make a change to SCons;
+run
+<emphasis remap='B'>scons-time run</emphasis>
+to profile it against a specific configuration;
+make another change to SCons;
+run
+<emphasis remap='B'>scons-time run</emphasis>
+again to profile it;
+etc.</para>
+<!-- '\"========================================================================== -->
+</refsect1>
+
+<refsect1 id='options'><title>OPTIONS</title>
+<para>The
+<command>scons-time</command>
+command only supports a few global options:</para>
+<variablelist remap='TP'>
+  <varlistentry>
+  <term>-h, --help</term>
+  <listitem>
+<para>Displays the global help text and exits,
+identical to the
+<emphasis remap='B'>scons-time help</emphasis>
+subcommand.</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>-V, --version</term>
+  <listitem>
+<para>Displays the
+<command>scons-time</command>
+version and exits.</para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+
+<para>Most functionality is controlled by options
+to the individual subcommands.
+See the next section for information
+about individual subcommand options.</para>
+<!-- '\"========================================================================== -->
+</refsect1>
+
+<refsect1 id='subcommands'><title>SUBCOMMANDS</title>
+<para>The
+<command>scons-time</command>
+command supports the following
+individual subcommands.</para>
+<!-- '\"\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- -->
+
+<refsect2 id='the_func_subcommand'><title>The func Subcommand</title>
+<para><emphasis remap='B'>scons-time func</emphasis>
+[<option>-h</option>]
+[<option>--chdir=</option><replaceable>DIR</replaceable>]
+[<option>-f </option><emphasis remap='I'>FILE</emphasis>]
+[<option>--fmt=</option><replaceable>FORMAT</replaceable>]
+[<option>--func=</option><replaceable>NAME</replaceable>]
+[<option>-p </option><emphasis remap='I'>STRING</emphasis>]
+[<option>-t </option><emphasis remap='I'>NUMBER</emphasis>]
+[<option>--title= TITLE</option>]
+[<emphasis remap='I'>ARGUMENTS</emphasis>]</para>
+
+<para>The
+<emphasis remap='B'>scons-time func</emphasis>
+subcommand displays timing information
+for a specific Python function within SCons.
+By default, it extracts information about the
+<emphasis remap='B'>_main</emphasis>()
+function,
+which includes the Python profiler timing
+for all of SCons.</para>
+
+<para>The
+<emphasis remap='B'>scons-time func</emphasis>
+subcommand extracts function timing information
+from all the specified file arguments,
+which should be Python profiler output files.
+(Normally, these would be
+<emphasis remap='B'>*.prof</emphasis>
+files generated by the
+<emphasis remap='B'>scons-time run</emphasis>
+subcommand,
+but they can actually be generated
+by any Python profiler invocation.)
+All file name arguments will be
+globbed for on-disk files.</para>
+
+<para>If no arguments are specified,
+then function timing information
+will be extracted from all
+<emphasis remap='B'>*.prof</emphasis>
+files,
+or the subset of them
+with a prefix specified by the
+<option>-p</option>
+option.</para>
+
+<para>Options include:</para>
+<variablelist remap='TP'>
+  <varlistentry>
+  <term>-C DIRECTORY, --chdir=DIRECTORY</term>
+  <listitem>
+<para>Changes to the specified
+<emphasis remap='I'>DIRECTORY</emphasis>
+before looking for the specified files
+(or files that match the specified patterns).</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>-f FILE, --file=FILE</term>
+  <listitem>
+<para>Reads configuration information from the specified
+<emphasis remap='I'>FILE</emphasis>.</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>-fmt=FORMAT, --format=FORMAT</term>
+  <listitem>
+<para>Reports the output in the specified
+<emphasis remap='I'>FORMAT</emphasis>.
+The formats currently supported are
+<emphasis remap='B'>ascii</emphasis>
+(the default)
+and
+<emphasis remap='B'>gnuplot</emphasis>.</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>--func=NAME</term>
+  <listitem>
+<para>Extracts timings for the specified function
+<emphasis remap='I'>NAME</emphasis>.
+The default is to report cumulative timings for the
+<emphasis remap='B'>_main</emphasis>()
+function,
+which contains the entire SCons run.</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>-h, --help</term>
+  <listitem>
+<para>Displays help text for the
+<emphasis remap='B'>scons-time func</emphasis>
+subcommand.</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>-p STRING, --prefix=STRING</term>
+  <listitem>
+<para>Specifies the prefix string for profiles
+from which to extract function timing information.
+This will be used to search for profiles
+if no arguments are specified on the command line.</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>-t NUMBER, --tail=NUMBER</term>
+  <listitem>
+<para>Only extracts function timings from the last
+<emphasis remap='I'>NUMBER</emphasis>
+files.</para>
+<!-- '\"\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- -->
+  </listitem>
+  </varlistentry>
+</variablelist>
+</refsect2>
+
+<refsect2 id='the_help_subcommand'><title>The help Subcommand</title>
+<para><emphasis remap='B'>scons-time help</emphasis>
+<emphasis remap='I'>SUBCOMMAND</emphasis>
+[...]
+The
+<emphasis remap='B'>help</emphasis>
+subcommand prints help text for any
+other subcommands listed as later arguments on the command line.</para>
+<!-- '\"\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- -->
+</refsect2>
+
+<refsect2 id='the_mem_subcommand'><title>The mem Subcommand</title>
+<para><emphasis remap='B'>scons-time mem</emphasis>
+[<option>-h</option>]
+[<option>--chdir=</option><replaceable>DIR</replaceable>]
+[<option>-f </option><emphasis remap='I'>FILE</emphasis>]
+[<option>--fmt=</option><replaceable>FORMAT</replaceable>]
+[<option>-p </option><emphasis remap='I'>STRING</emphasis>]
+[<option>--stage=</option><replaceable>STAGE</replaceable>]
+[<option>-t </option><emphasis remap='I'>NUMBER</emphasis>]
+[<option>--title=</option><replaceable>TITLE</replaceable>]
+[<emphasis remap='I'>ARGUMENTS</emphasis>]</para>
+
+<para>The
+<emphasis remap='B'>scons-time mem</emphasis>
+subcommand displays how much memory SCons uses.</para>
+
+<para>The
+<emphasis remap='B'>scons-time mem</emphasis>
+subcommand extracts memory use information
+from all the specified file arguments,
+which should be files containing output from
+running SCons with the
+<option>--debug=memory</option>
+option.
+(Normally, these would be
+<emphasis remap='B'>*.log</emphasis>
+files generated by the
+<emphasis remap='B'>scons-time run</emphasis>
+subcommand.)
+All file name arguments will be
+globbed for on-disk files.</para>
+
+<para>If no arguments are specified,
+then memory information
+will be extracted from all
+<emphasis remap='B'>*.log</emphasis>
+files,
+or the subset of them
+with a prefix specified by the
+<option>-p</option>
+option.</para>
+
+<variablelist remap='TP'>
+  <varlistentry>
+  <term>-C DIR, --chdir=DIR</term>
+  <listitem>
+<para>Changes to the specified
+<emphasis remap='I'>DIRECTORY</emphasis>
+before looking for the specified files
+(or files that match the specified patterns).</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>-f FILE, --file=FILE</term>
+  <listitem>
+<para>Reads configuration information from the specified
+<emphasis remap='I'>FILE</emphasis>.</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>-fmt=FORMAT, --format=FORMAT</term>
+  <listitem>
+<para>Reports the output in the specified
+<emphasis remap='I'>FORMAT</emphasis>.
+The formats currently supported are
+<emphasis remap='B'>ascii</emphasis>
+(the default)
+and
+<emphasis remap='B'>gnuplot</emphasis>.</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>-h, --help</term>
+  <listitem>
+<para>Displays help text for the
+<emphasis remap='B'>scons-time mem</emphasis>
+subcommand.</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>-p STRING, --prefix=STRING</term>
+  <listitem>
+<para>Specifies the prefix string for log files
+from which to extract memory usage information.
+This will be used to search for log files
+if no arguments are specified on the command line.</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>--stage=STAGE</term>
+  <listitem>
+<para>Prints the memory used at the end of the specified
+<emphasis remap='I'>STAGE</emphasis>:
+<emphasis remap='B'>pre-read</emphasis>
+(before the SConscript files are read),
+<emphasis remap='B'>post-read ,</emphasis>
+(after the SConscript files are read),
+<emphasis remap='B'>pre-build</emphasis>
+(before any targets are built)
+or
+<emphasis remap='B'>post-build</emphasis>
+(after any targets are built).
+If no
+<option>--stage</option>
+option is specified,
+the default behavior is
+<emphasis remap='B'>post-build</emphasis>,
+which reports the final amount of memory
+used by SCons during each run.</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>-t NUMBER, --tail=NUMBER</term>
+  <listitem>
+<para>Only reports memory statistics from the last
+<emphasis remap='I'>NUMBER</emphasis>
+files.</para>
+<!-- '\"\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- -->
+  </listitem>
+  </varlistentry>
+</variablelist>
+</refsect2>
+
+<refsect2 id='the_obj_subcommand'><title>The obj Subcommand</title>
+<para><emphasis remap='B'>scons-time obj</emphasis>
+[<option>-h</option>]
+[<option>--chdir=</option><replaceable>DIR</replaceable>]
+[<option>-f </option><emphasis remap='I'>FILE</emphasis>]
+[<option>--fmt=</option><replaceable>FORMAT</replaceable>]
+[<option>-p </option><emphasis remap='I'>STRING</emphasis>]
+[<option>--stage=</option><replaceable>STAGE</replaceable>]
+[<option>-t </option><emphasis remap='I'>NUMBER</emphasis>]
+[<option>--title=</option><replaceable>TITLE</replaceable>]
+[<emphasis remap='I'>ARGUMENTS</emphasis>]</para>
+
+<para>The
+<emphasis remap='B'>scons-time obj</emphasis>
+subcommand displays how many objects of a specific named type
+are created by SCons.</para>
+
+<para>The
+<emphasis remap='B'>scons-time obj</emphasis>
+subcommand extracts object counts
+from all the specified file arguments,
+which should be files containing output from
+running SCons with the
+<option>--debug=count</option>
+option.
+(Normally, these would be
+<emphasis remap='B'>*.log</emphasis>
+files generated by the
+<emphasis remap='B'>scons-time run</emphasis>
+subcommand.)
+All file name arguments will be
+globbed for on-disk files.</para>
+
+<para>If no arguments are specified,
+then object counts
+will be extracted from all
+<emphasis remap='B'>*.log</emphasis>
+files,
+or the subset of them
+with a prefix specified by the
+<option>-p</option>
+option.</para>
+<variablelist remap='TP'>
+  <varlistentry>
+  <term>-C DIR, --chdir=DIR</term>
+  <listitem>
+<para>Changes to the specified
+<emphasis remap='I'>DIRECTORY</emphasis>
+before looking for the specified files
+(or files that match the specified patterns).</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>-f FILE, --file=FILE</term>
+  <listitem>
+<para>Reads configuration information from the specified
+<emphasis remap='I'>FILE</emphasis>.</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>-fmt=FORMAT, --format=FORMAT</term>
+  <listitem>
+<para>Reports the output in the specified
+<emphasis remap='I'>FORMAT</emphasis>.
+The formats currently supported are
+<emphasis remap='B'>ascii</emphasis>
+(the default)
+and
+<emphasis remap='B'>gnuplot</emphasis>.</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>-h, --help</term>
+  <listitem>
+<para>Displays help text for the
+<emphasis remap='B'>scons-time obj</emphasis>
+subcommand.</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>-p STRING, --prefix=STRING</term>
+  <listitem>
+<para>Specifies the prefix string for log files
+from which to extract object counts.
+This will be used to search for log files
+if no arguments are specified on the command line.</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>--stage=STAGE</term>
+  <listitem>
+<para>Prints the object count at the end of the specified
+<emphasis remap='I'>STAGE</emphasis>:
+<emphasis remap='B'>pre-read</emphasis>
+(before the SConscript files are read),
+<emphasis remap='B'>post-read ,</emphasis>
+(after the SConscript files are read),
+<emphasis remap='B'>pre-build</emphasis>
+(before any targets are built)
+or
+<emphasis remap='B'>post-build</emphasis>
+(after any targets are built).
+If no
+<option>--stage</option>
+option is specified,
+the default behavior is
+<emphasis remap='B'>post-build</emphasis>,
+which reports the final object count during each run.</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>-t NUMBER, --tail=NUMBER</term>
+  <listitem>
+<para>Only reports object counts from the last
+<emphasis remap='I'>NUMBER</emphasis>
+files.</para>
+<!-- '\"\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- -->
+  </listitem>
+  </varlistentry>
+</variablelist>
+</refsect2>
+
+<refsect2 id='the_run_subcommand'><title>The run Subcommand</title>
+<para><emphasis remap='B'>scons-time run</emphasis>
+[<option>-hnqv</option>]
+[<option>--aegis=</option><replaceable>PROJECT</replaceable>]
+[<option>-f </option><emphasis remap='I'>FILE</emphasis>]
+[<option>--number=</option><replaceable>NUMBER</replaceable>]
+[<option>--outdir=</option><replaceable>OUTDIR</replaceable>]
+[<option>-p </option><emphasis remap='I'>STRING</emphasis>]
+[<option>--python=</option><replaceable>PYTHON</replaceable>]
+[<option>-s </option><emphasis remap='I'>DIR</emphasis>]
+[<option>--scons=</option><replaceable>SCONS</replaceable>]
+[<option>--svn=</option><replaceable>URL</replaceable>]
+[<emphasis remap='I'>ARGUMENTS</emphasis>]
+The
+<emphasis remap='B'>scons-time run</emphasis>
+subcommand is the basic subcommand
+for profiling a specific configuration
+against a version of SCons.</para>
+
+<para>The configuration to be tested
+is specified as a list of files
+or directories that will be unpacked or copied
+into a temporary directory
+in which SCons will be invoked.
+The
+<emphasis remap='B'>scons-time run</emphasis>
+subcommand understands file suffixes like
+<markup>.tar</markup>,
+<markup>.tar.gz</markup>,
+<markup>.tgz</markup>
+and
+<markup>.zip</markup>
+and will unpack their contents into a temporary directory.
+If more than one argument is specified,
+each one will be unpacked or copied
+into the temporary directory "on top of"
+the previous archives or directories,
+so the expectation is that multiple
+specified archives share the same directory layout.</para>
+
+<para>Once the file or directory arguments are unpacked or
+copied to the temporary directory,
+the
+<emphasis remap='B'>scons-time run</emphasis>
+subcommand runs the
+requested version of SCons
+against the configuration
+three times:</para>
+<variablelist remap='TP'>
+  <varlistentry>
+  <term>Startup</term>
+  <listitem>
+<para>SCons is run with the
+<option>--help</option>
+option so that just the SConscript files are read,
+and then the default help text is printed.
+This profiles just the perceived "overhead" of starting up SCons
+and processing the SConscript files.</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>Full build</term>
+  <listitem>
+<para>SCons is run to build everything specified in the configuration.
+Specific targets to be passed in on the command l ine
+may be specified by the
+<emphasis remap='B'>targets</emphasis>
+keyword in a configuration file; see below for details.</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>Rebuild</term>
+  <listitem>
+<para>SCons is run again on the same just-built directory.
+If the dependencies in the SCons configuration are correct,
+this should be an up-to-date, "do nothing" rebuild.</para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+
+<para>Each invocation captures the output log file and a profile.</para>
+
+<para>The
+<emphasis remap='B'>scons-time run</emphasis>
+subcommand supports the following options:</para>
+<variablelist remap='TP'>
+  <varlistentry>
+  <term>--aegis=PROJECT</term>
+  <listitem>
+<para>Specifies the Aegis
+<emphasis remap='I'>PROJECT</emphasis>
+from which the
+version(s) of
+<emphasis remap='B'>scons</emphasis>
+being timed will be extracted.
+When
+<option>--aegis</option>
+is specified, the
+<option>--number=</option><replaceable>NUMBER</replaceable>
+option specifies delta numbers
+that will be tested.
+Output from each invocation run will be placed in file
+names that match the Aegis delta numbers.
+If the
+<option>--number=</option>
+option is not specified,
+then the default behavior is to time the
+tip of the specified
+<emphasis remap='I'>PROJECT</emphasis>.</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>-f FILE, --file=FILE</term>
+  <listitem>
+<para>Reads configuration information from the specified
+<emphasis remap='I'>FILE</emphasis>.
+This often provides a more convenient way to specify and
+collect parameters associated with a specific timing configuration
+than specifying them on the command line.
+See the
+<link linkend="configuration_file">CONFIGURATION FILE</link>
+section below
+for information about the configuration file parameters.</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>-h, --help</term>
+  <listitem>
+<para>Displays help text for the
+<emphasis remap='B'>scons-time run</emphasis>
+subcommand.</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>-n, --no-exec</term>
+  <listitem>
+<para>Do not execute commands,
+just printing the command-line equivalents of what would be executed.
+Note that the
+<command>scons-time</command>
+script actually executes its actions in Python,
+where possible,
+for portability.
+The commands displayed are UNIX
+<emphasis remap='I'>equivalents</emphasis>
+of what it's doing.</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>--number=NUMBER</term>
+  <listitem>
+<para>Specifies the run number to be used in the names of
+the log files and profile outputs generated by this run.</para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+
+<para>When used in conjuction with the
+<option>--aegis=</option><replaceable>PROJECT</replaceable>
+option,
+<emphasis remap='I'>NUMBER</emphasis>
+specifies one or more comma-separated Aegis delta numbers
+that will be retrieved automatically from the specified Aegis
+<emphasis remap='I'>PROJECT</emphasis>.</para>
+
+<para>When used in conjuction with the
+<option>--svn=</option><replaceable>URL</replaceable>
+option,
+<emphasis remap='I'>NUMBER</emphasis>
+specifies one or more comma-separated Subversion revision numbers
+that will be retrieved automatically from the Subversion
+repository at the specified
+<emphasis remap='I'>URL</emphasis>.
+Ranges of delta or revision numbers
+may be specified be separating two numbers
+with a hyphen
+(<emphasis remap='B'>-</emphasis>).</para>
+
+<para>Example:</para>
+<literallayout remap='.nf'>
+% scons-time run --svn=<ulink url='http://scons.tigris.org/svn/trunk'>http://scons.tigris.org/svn/trunk</ulink> --num=1247,1249-1252 .
+</literallayout> <!-- .fi -->
+<variablelist remap='TP'>
+  <varlistentry>
+  <term>-p STRING, --prefix=STRING</term>
+  <listitem>
+<para>Specifies the prefix string to be used for all of the log files
+and profiles generated by this run.
+The default is derived from the first
+specified argument:
+if the first argument is a directory,
+the default prefix is the name of the directory;
+if the first argument is an archive
+(tar or zip file),
+the default prefix is the the base name of the archive,
+that is, what remains after stripping the archive suffix
+(<markup>.tgz</markup>, <markup>.tar.gz</markup> or <markup>.zip</markup>).</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>--python=PYTHON</term>
+  <listitem>
+<para>Specifies a path to the Python executable to be used
+for the timing runs.
+The default is to use the same Python executable that
+is running the
+<command>scons-time</command>
+command itself.</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>-q, --quiet</term>
+  <listitem>
+<para>Suppresses display of the command lines being executed.</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>-s DIR, --subdir=DIR</term>
+  <listitem>
+<para>Specifies the name of directory or subdirectory
+from which the commands should be executed.
+The default is XXX</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>--scons=SCONS</term>
+  <listitem>
+<para>Specifies a path to the SCons script to be used
+for the timing runs.
+The default is XXX</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>--svn=URL, --subversion=URL</term>
+  <listitem>
+<para>Specifies the
+<emphasis remap='I'>URL</emphasis>
+of the Subversion repository from which the
+version(s) of
+<emphasis remap='B'>scons</emphasis>
+being timed will be extracted.
+When
+<option>--svn</option>
+is specified, the
+<option>--number=</option><replaceable>NUMBER</replaceable>
+option specifies revision numbers
+that will be tested.
+Output from each invocation run will be placed in file
+names that match the Subversion revision numbers.
+If the
+<option>--number=</option>
+option is not specified,
+then the default behavior is to time the
+<emphasis remap='B'>HEAD</emphasis>
+of the specified
+<emphasis remap='I'>URL</emphasis>.</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>-v, --verbose</term>
+  <listitem>
+<para>Displays the output from individual commands to the screen
+(in addition to capturing the output in log files).</para>
+<!-- '\"\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- -->
+  </listitem>
+  </varlistentry>
+</variablelist>
+</refsect2>
+
+<refsect2 id='the_time_subcommand'><title>The time Subcommand</title>
+<para><emphasis remap='B'>scons-time time</emphasis>
+[<option>-h</option>]
+[<option>--chdir=</option><replaceable>DIR</replaceable>]
+[<option>-f </option><emphasis remap='I'>FILE</emphasis>]
+[<option>--fmt=</option><replaceable>FORMAT</replaceable>]
+[<option>-p </option><emphasis remap='I'>STRING</emphasis>]
+[<option>-t </option><emphasis remap='I'>NUMBER</emphasis>]
+[<option>--title=</option><replaceable>TITLE</replaceable>]
+[<option>--which=</option><replaceable>WHICH</replaceable>]
+[<emphasis remap='I'>ARGUMENTS</emphasis>]</para>
+
+<para>The
+<emphasis remap='B'>scons-time time</emphasis>
+subcommand displays SCons execution times
+as reported by the
+<userinput>scons --debug=time</userinput>
+option.</para>
+
+<para>The
+<emphasis remap='B'>scons-time time</emphasis>
+subcommand extracts SCons timing
+from all the specified file arguments,
+which should be files containing output from
+running SCons with the
+<option>--debug=time</option>
+option.
+(Normally, these would be
+<emphasis remap='B'>*.log</emphasis>
+files generated by the
+<emphasis remap='B'>scons-time run</emphasis>
+subcommand.)
+All file name arguments will be
+globbed for on-disk files.</para>
+
+<para>If no arguments are specified,
+then execution timings
+will be extracted from all
+<emphasis remap='B'>*.log</emphasis>
+files,
+or the subset of them
+with a prefix specified by the
+<option>-p</option>
+option.</para>
+<variablelist remap='TP'>
+  <varlistentry>
+  <term>-C DIR, --chdir=DIR</term>
+  <listitem>
+<para>Changes to the specified
+<emphasis remap='I'>DIRECTORY</emphasis>
+before looking for the specified files
+(or files that match the specified patterns).</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>-f FILE, --file=FILE</term>
+  <listitem>
+<para>Reads configuration information from the specified
+<emphasis remap='I'>FILE</emphasis>.</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>-fmt=FORMAT, --format=FORMAT</term>
+  <listitem>
+<para>Reports the output in the specified
+<emphasis remap='I'>FORMAT</emphasis>.
+The formats currently supported are
+<emphasis remap='B'>ascii</emphasis>
+(the default)
+and
+<emphasis remap='B'>gnuplot</emphasis>.</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>-h, --help</term>
+  <listitem>
+<para>Displays help text for the
+<emphasis remap='B'>scons-time time</emphasis>
+subcommand.</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>-p STRING, --prefix=STRING</term>
+  <listitem>
+<para>Specifies the prefix string for log files
+from which to extract execution timings.
+This will be used to search for log files
+if no arguments are specified on the command line.</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>-t NUMBER, --tail=NUMBER</term>
+  <listitem>
+<para>Only reports object counts from the last
+<emphasis remap='I'>NUMBER</emphasis>
+files.</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>--which=WHICH</term>
+  <listitem>
+<para>Prints the execution time for the specified
+<emphasis remap='I'>WHICH</emphasis>
+value:
+<emphasis remap='B'>total</emphasis>
+(the total execution time),
+<emphasis remap='B'>SConscripts</emphasis>
+(total execution time for the SConscript files themselves),
+<emphasis remap='B'>SCons</emphasis>
+(exectuion time in SCons code itself)
+or
+<emphasis remap='B'>commands</emphasis>
+(execution time of the commands and other actions
+used to build targets).
+If no
+<option>--which</option>
+option is specified,
+the default behavior is
+<emphasis remap='B'>total</emphasis>,
+which reports the total execution time for each run.</para>
+<!-- '\"========================================================================== -->
+  </listitem>
+  </varlistentry>
+</variablelist>
+</refsect2>
+</refsect1>
+
+<refsect1 id='configuration_file'><title>CONFIGURATION FILE</title>
+<para>Various
+<command>scons-time</command>
+subcommands can read information from a specified
+configuration file when passed the
+<option>-f</option>
+or
+<option>--file</option>
+options.
+The configuration file is actually executed as a Python script.
+Setting Python variables in the configuration file
+controls the behavior of the
+<command>scons-time</command>
+script more conveniently than having to specify
+command-line options or arguments for every run,
+and provides a handy way to "shrink-wrap"
+the necessary information for producing (and reporting)
+consistent timing runs for a given configuration.</para>
+<variablelist remap='TP'>
+  <varlistentry>
+  <term><emphasis remap='B'>aegis</emphasis></term>
+  <listitem>
+<para>The Aegis executable for extracting deltas.
+The default is simply
+<emphasis remap='B'>aegis</emphasis>.</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term><emphasis remap='B'>aegis_project</emphasis></term>
+  <listitem>
+<para>The Aegis project from which deltas should be extracted.
+The default is whatever is specified
+with the
+<option>--aegis=</option>
+command-line option.</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term><emphasis remap='B'>archive_list</emphasis></term>
+  <listitem>
+<para>A list of archives (files or directories)
+that will be copied to the temporary directory
+in which SCons will be invoked.
+<markup>.tar</markup>,
+<markup>.tar.gz</markup>,
+<markup>.tgz</markup>
+and
+<markup>.zip</markup>
+files will have their contents unpacked in
+the temporary directory.
+Directory trees and files will be copied as-is.</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term><emphasis remap='B'>initial_commands</emphasis></term>
+  <listitem>
+<para>A list of commands that will be executed
+before the actual timed
+<emphasis remap='B'>scons</emphasis>
+runs.
+This can be used for commands that are necessary
+to prepare the source tree-for example,
+creating a configuration file
+that should not be part of the timed run.</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term><emphasis remap='B'>key_location</emphasis></term>
+  <listitem>
+<para>The location of the key on Gnuplot graphing information
+generated with the
+<option>--format=gnuplot</option>
+option.
+The default is
+<emphasis remap='B'>bottom left</emphasis>.</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term><emphasis remap='B'>prefix</emphasis></term>
+  <listitem>
+<para>The file name prefix to be used when
+running or extracting timing for this configuration.</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term><emphasis remap='B'>python</emphasis></term>
+  <listitem>
+<para>The path name of the Python executable
+to be used when running or extracting information
+for this configuration.
+The default is the same version of Python
+used to run the SCons</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term><emphasis remap='B'>scons</emphasis></term>
+  <listitem>
+<para>The path name of the SCons script to be used
+when running or extracting information
+for this configuration.
+The default is simply
+<emphasis remap='B'>scons</emphasis>.</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term><emphasis remap='B'>scons_flags</emphasis></term>
+  <listitem>
+<para>The
+<emphasis remap='B'>scons</emphasis>
+flags used when running SCons to collect timing information.
+The default value is
+<option>--debug=count --debug=memory --debug=time --debug=memoizer</option>.</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term><emphasis remap='B'>scons_lib_dir</emphasis></term>
+  <term><emphasis remap='B'>scons_wrapper</emphasis></term>
+  <term><emphasis remap='B'>startup_targets</emphasis></term>
+  <term><emphasis remap='B'>subdir</emphasis></term>
+  <listitem>
+<para>The subdirectory of the project into which the
+<command>scons-time</command>
+script should change
+before executing the SCons commands to time.</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term><emphasis remap='B'>subversion_url</emphasis></term>
+  <listitem>
+<para>The Subversion URL from</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term><emphasis remap='B'>svn</emphasis></term>
+  <listitem>
+<para>The subversion executable used to
+check out revisions of SCons to be timed.
+The default is simple
+<emphasis remap='B'>svn</emphasis>.</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term><emphasis remap='B'>svn_co_flag</emphasis></term>
+  <term><emphasis remap='B'>tar</emphasis></term>
+  <term><emphasis remap='B'>targets</emphasis></term>
+  <listitem>
+<para>A string containing the targets that should be added to
+the command line of every timed
+<emphasis remap='B'>scons</emphasis>
+run.
+This can be used to restrict what's being timed to a
+subset of the full build for the configuration.</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term><emphasis remap='B'>targets0</emphasis></term>
+  <term><emphasis remap='B'>targets1</emphasis></term>
+  <term><emphasis remap='B'>targets2</emphasis></term>
+  <term><emphasis remap='B'>title</emphasis></term>
+  <term><emphasis remap='B'>unzip</emphasis></term>
+  <term><emphasis remap='B'>verbose</emphasis></term>
+  <term><emphasis remap='B'>vertical_bars</emphasis></term>
+  <listitem>
+<!-- '\"\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- -->
+<para></para> <!-- FIXME: blank list item -->
+  </listitem>
+  </varlistentry>
+</variablelist>
+
+<refsect2 id='example'><title>Example</title>
+<para>Here is an example
+<command>scons-time</command>
+configuration file
+for a hypothetical sample project:</para>
+
+<literallayout remap='.nf'>
+# The project doesn't use SCons natively (yet), so we're
+# timing a separate set of SConscript files that we lay
+# on top of the vanilla unpacked project tarball.
+arguments = ['project-1.2.tgz', 'project-SConscripts.tar']
+
+# The subdirectory name contains the project version number,
+# so tell scons-time to chdir there before building.
+subdir = 'project-1.2'
+
+# Set the prefix so output log files and profiles are named:
+#     project-000-[012].{log,prof}
+#     project-001-[012].{log,prof}
+# etc.
+prefix = 'project'
+
+# The SConscript files being tested don't do any SConf
+# configuration, so run their normal ./configure script
+# before we invoke SCons.
+initial_commands = [
+    './configure',
+]
+
+# Only time building the bin/project executable.
+targets = 'bin/project'
+
+# Time against SCons revisions of the branches/core branch
+subversion_url = '<ulink url='http://scons.tigris.org/svn/scons/branches/core'>http://scons.tigris.org/svn/scons/branches/core</ulink>'
+</literallayout> <!-- .fi -->
+<!-- '\"========================================================================== -->
+</refsect2>
+</refsect1>
+
+<refsect1 id='environment'><title>ENVIRONMENT</title>
+<para>The
+<command>scons-time</command>
+script uses the following environment variables:</para>
+<variablelist remap='TP'>
+  <varlistentry>
+  <term><emphasis remap='B'>PRESERVE</emphasis></term>
+  <listitem>
+<para>If this value is set,
+the
+<command>scons-time</command>
+script will
+<emphasis remap='I'>not</emphasis>
+remove the temporary directory or directories
+in which it builds the specified configuration
+or downloads a specific version of SCons.</para>
+<!-- '\"========================================================================== -->
+  </listitem>
+  </varlistentry>
+</variablelist>
+</refsect1>
+
+<refsect1 id='see_also'><title>SEE ALSO</title>
+<para><citerefentry><refentrytitle>gnuplot</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
+<citerefentry><refentrytitle>scons</refentrytitle><manvolnum>1</manvolnum></citerefentry></para>
+
+</refsect1>
+
+<refsect1 id='authors'><title>AUTHORS</title>
+<para>Steven Knight &lt;knight at baldmt dot com&gt;</para>
+</refsect1>
+</refentry>
+
diff --git a/doc/man/scons.1 b/doc/man/scons.1
deleted file mode 100644
index 3651351..0000000
--- a/doc/man/scons.1
+++ /dev/null
@@ -1,6244 +0,0 @@
-.\" __COPYRIGHT__
-.\"
-.\" Permission is hereby granted, free of charge, to any person obtaining
-.\" a copy of this software and associated documentation files (the
-.\" "Software"), to deal in the Software without restriction, including
-.\" without limitation the rights to use, copy, modify, merge, publish,
-.\" distribute, sublicense, and/or sell copies of the Software, and to
-.\" permit persons to whom the Software is furnished to do so, subject to
-.\" the following conditions:
-.\"
-.\" The above copyright notice and this permission notice shall be included
-.\" in all copies or substantial portions of the Software.
-.\"
-.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY
-.\" KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
-.\" WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
-.\" NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
-.\" LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
-.\" OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
-.\" WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
-.\"
-.\" __FILE__ __REVISION__ __DATE__ __DEVELOPER__
-.\"
-.TH SCONS 1 "__MONTH_YEAR__"
-.\" ES - Example Start - indents and turns off line fill
-.rm ES
-.de ES
-.RS
-.nf
-..
-.\" EE - Example End - ends indent and turns line fill back on
-.rm EE
-.de EE
-.fi
-.RE
-..
-.SH NAME
-scons \- a software construction tool
-.SH SYNOPSIS
-.B scons
-[
-.IR options ...
-]
-[
-.IR name = val ...
-]
-[
-.IR targets ...
-]
-.SH DESCRIPTION
-
-The
-.B scons
-utility builds software (or other files) by determining which
-component pieces must be rebuilt and executing the necessary commands to
-rebuild them.
-
-By default,
-.B scons
-searches for a file named
-.IR SConstruct ,
-.IR Sconstruct ,
-or
-.I sconstruct
-(in that order) in the current directory and reads its
-configuration from the first file found.
-An alternate file name may be
-specified via the
-.B -f
-option.
-
-The
-.I SConstruct
-file can specify subsidiary
-configuration files using the
-.BR SConscript ()
-function.
-By convention,
-these subsidiary files are named
-.IR SConscript ,
-although any name may be used.
-(Because of this naming convention,
-the term "SConscript files"
-is sometimes used to refer
-generically to all
-.B scons
-configuration files,
-regardless of actual file name.)
-
-The configuration files
-specify the target files to be built, and
-(optionally) the rules to build those targets.  Reasonable default
-rules exist for building common software components (executable
-programs, object files, libraries), so that for most software
-projects, only the target and input files need be specified.
-
-Before reading the
-.I SConstruct
-file,
-.B scons
-looks for a directory named
-.I site_scons
-in various system directories (see below) and the directory containing the
-.I SConstruct
-file; for each of those dirs which exists,
-.I site_scons
-is prepended to sys.path,
-the file
-.IR site_scons/site_init.py ,
-is evaluated if it exists,
-and the directory
-.I site_scons/site_tools
-is prepended to the default toolpath if it exists.
-See the
-.I --no-site-dir
-and
-.I --site-dir
-options for more details.
-
-.B scons
-reads and executes the SConscript files as Python scripts,
-so you may use normal Python scripting capabilities
-(such as flow control, data manipulation, and imported Python libraries)
-to handle complicated build situations.
-.BR scons ,
-however, reads and executes all of the SConscript files
-.I before
-it begins building any targets.
-To make this obvious,
-.B scons
-prints the following messages about what it is doing:
-
-.ES
-$ scons foo.out
-scons: Reading SConscript files ...
-scons: done reading SConscript files.
-scons: Building targets  ...
-cp foo.in foo.out
-scons: done building targets.
-$
-.EE
-
-The status messages
-(everything except the line that reads "cp foo.in foo.out")
-may be suppressed using the
-.B -Q
-option.
-
-.B scons
-does not automatically propagate
-the external environment used to execute
-.B scons
-to the commands used to build target files.
-This is so that builds will be guaranteed
-repeatable regardless of the environment
-variables set at the time
-.B scons
-is invoked.
-This also means that if the compiler or other commands
-that you want to use to build your target files
-are not in standard system locations,
-.B scons
-will not find them unless
-you explicitly set the PATH
-to include those locations.
-Whenever you create an
-.B scons
-construction environment,
-you can propagate the value of PATH
-from your external environment as follows:
-
-.ES
-import os
-env = Environment(ENV = {'PATH' : os.environ['PATH']})
-.EE
-
-Similarly, if the commands use external environment variables
-like $PATH, $HOME, $JAVA_HOME, $LANG, $SHELL, $TERM, etc.,
-these variables can also be explicitly propagated:
-
-.ES
-import os
-env = Environment(ENV = {'PATH' : os.environ['PATH'],
-                         'HOME' : os.environ['HOME']})
-.EE
-
-Or you may explicitly propagate the invoking user's
-complete external environment:
-
-.ES
-import os
-env = Environment(ENV = os.environ)
-.EE
-
-This comes at the expense of making your build
-dependent on the user's environment being set correctly,
-but it may be more convenient for many configurations.
-
-.B scons
-can scan known input files automatically for dependency
-information (for example, #include statements
-in C or C++ files) and will rebuild dependent files appropriately
-whenever any "included" input file changes.
-.B scons
-supports the
-ability to define new scanners for unknown input file types.
-
-.B scons
-knows how to fetch files automatically from
-SCCS or RCS subdirectories
-using SCCS, RCS or BitKeeper.
-
-.B scons
-is normally executed in a top-level directory containing a
-.I SConstruct
-file, optionally specifying
-as command-line arguments
-the target file or files to be built.
-
-By default, the command
-
-.ES
-scons
-.EE
-
-will build all target files in or below the current directory.
-Explicit default targets
-(to be built when no targets are specified on the command line)
-may be defined the SConscript file(s)
-using the
-.B Default()
-function, described below.
-
-Even when
-.B Default()
-targets are specified in the SConscript file(s),
-all target files in or below the current directory
-may be built by explicitly specifying
-the current directory (.)
-as a command-line target:
-
-.ES
-scons .
-.EE
-
-Building all target files,
-including any files outside of the current directory,
-may be specified by supplying a command-line target
-of the root directory (on POSIX systems):
-
-.ES
-scons /
-.EE
-
-or the path name(s) of the volume(s) in which all the targets
-should be built (on Windows systems):
-
-.ES
-scons C:\\ D:\\
-.EE
-
-To build only specific targets,
-supply them as command-line arguments:
-
-.ES
-scons foo bar
-.EE
-
-in which case only the specified targets will be built
-(along with any derived files on which they depend).
-
-Specifying "cleanup" targets in SConscript files is not usually necessary.
-The
-.B -c
-flag removes all files
-necessary to build the specified target:
-
-.ES
-scons -c .
-.EE
-
-to remove all target files, or:
-
-.ES
-scons -c build export
-.EE
-
-to remove target files under build and export.
-Additional files or directories to remove can be specified using the
-.BR Clean()
-function.
-Conversely, targets that would normally be removed by the
-.B -c
-invocation
-can be prevented from being removed by using the
-.BR NoClean ()
-function.
-
-A subset of a hierarchical tree may be built by
-remaining at the top-level directory (where the
-.I SConstruct
-file lives) and specifying the subdirectory as the target to be
-built:
-
-.ES
-scons src/subdir
-.EE
-
-or by changing directory and invoking scons with the
-.B -u
-option, which traverses up the directory
-hierarchy until it finds the
-.I SConstruct
-file, and then builds
-targets relatively to the current subdirectory:
-
-.ES
-cd src/subdir
-scons -u .
-.EE
-
-.B scons
-supports building multiple targets in parallel via a
-.B -j
-option that takes, as its argument, the number
-of simultaneous tasks that may be spawned:
-
-.ES
-scons -j 4
-.EE
-
-builds four targets in parallel, for example.
-
-.B scons
-can maintain a cache of target (derived) files that can
-be shared between multiple builds.  When caching is enabled in a
-SConscript file, any target files built by
-.B scons
-will be copied
-to the cache.  If an up-to-date target file is found in the cache, it
-will be retrieved from the cache instead of being rebuilt locally.
-Caching behavior may be disabled and controlled in other ways by the
-.BR --cache-force ,
-.BR --cache-disable ,
-and
-.B --cache-show
-command-line options.  The
-.B --random
-option is useful to prevent multiple builds
-from trying to update the cache simultaneously.
-
-Values of variables to be passed to the SConscript file(s)
-may be specified on the command line:
-
-.ES
-scons debug=1 .
-.EE
-
-These variables are available in SConscript files
-through the ARGUMENTS dictionary,
-and can be used in the SConscript file(s) to modify
-the build in any way:
-
-.ES
-if ARGUMENTS.get('debug', 0):
-    env = Environment(CCFLAGS = '-g')
-else:
-    env = Environment()
-.EE
-
-The command-line variable arguments are also available
-in the ARGLIST list,
-indexed by their order on the command line.
-This allows you to process them in order rather than by name,
-if necessary.
-ARGLIST[0] returns a tuple
-containing (argname, argvalue).
-A Python exception is thrown if you
-try to access a list member that
-does not exist.
-
-.B scons
-requires Python version 2.4 or later.
-There should be no other dependencies or requirements to run
-.B scons.
-
-.\" The following paragraph reflects the default tool search orders
-.\" currently in SCons/Tool/__init__.py.  If any of those search orders
-.\" change, this documentation should change, too.
-By default,
-.B scons
-knows how to search for available programming tools
-on various systems.
-On Windows systems,
-.B scons
-searches in order for the
-Microsoft Visual C++ tools,
-the MinGW tool chain,
-the Intel compiler tools,
-and the PharLap ETS compiler.
-On OS/2 systems,
-.B scons
-searches in order for the
-OS/2 compiler,
-the GCC tool chain,
-and the Microsoft Visual C++ tools,
-On SGI IRIX, IBM AIX, Hewlett Packard HP-UX, and Sun Solaris systems,
-.B scons
-searches for the native compiler tools
-(MIPSpro, Visual Age, aCC, and Forte tools respectively)
-and the GCC tool chain.
-On all other platforms,
-including POSIX (Linux and UNIX) platforms,
-.B scons
-searches in order
-for the GCC tool chain,
-the Microsoft Visual C++ tools,
-and the Intel compiler tools.
-You may, of course, override these default values
-by appropriate configuration of
-Environment construction variables.
-
-.SH OPTIONS
-In general,
-.B scons
-supports the same command-line options as GNU
-.BR make ,
-and many of those supported by
-.BR cons .
-
-.TP
--b
-Ignored for compatibility with non-GNU versions of
-.BR make.
-
-.TP
--c, --clean, --remove
-Clean up by removing all target files for which a construction
-command is specified.
-Also remove any files or directories associated to the construction command
-using the
-.BR Clean ()
-function.
-Will not remove any targets specified by the
-.BR NoClean ()
-function.
-
-.TP
-.RI --cache-debug= file
-Print debug information about the
-.BR CacheDir ()
-derived-file caching
-to the specified
-.IR file .
-If
-.I file
-is
-.B \-
-(a hyphen),
-the debug information are printed to the standard output.
-The printed messages describe what signature file names are
-being looked for in, retrieved from, or written to the
-.BR CacheDir ()
-directory tree.
-
-.TP
---cache-disable, --no-cache
-Disable the derived-file caching specified by
-.BR CacheDir ().
-.B scons
-will neither retrieve files from the cache
-nor copy files to the cache.
-
-.TP
---cache-force, --cache-populate
-When using
-.BR CacheDir (),
-populate a cache by copying any already-existing, up-to-date
-derived files to the cache,
-in addition to files built by this invocation.
-This is useful to populate a new cache with
-all the current derived files,
-or to add to the cache any derived files
-recently built with caching disabled via the
-.B --cache-disable
-option.
-
-.TP
---cache-show
-When using
-.BR CacheDir ()
-and retrieving a derived file from the cache,
-show the command
-that would have been executed to build the file,
-instead of the usual report,
-"Retrieved `file' from cache."
-This will produce consistent output for build logs,
-regardless of whether a target
-file was rebuilt or retrieved from the cache.
-
-.TP
-.RI --config= mode
-This specifies how the
-.B Configure
-call should use or generate the
-results of configuration tests.
-The option should be specified from
-among the following choices:
-
-.TP
---config=auto
-scons will use its normal dependency mechanisms
-to decide if a test must be rebuilt or not.
-This saves time by not running the same configuration tests
-every time you invoke scons,
-but will overlook changes in system header files
-or external commands (such as compilers)
-if you don't specify those dependecies explicitly.
-This is the default behavior.
-
-.TP
---config=force
-If this option is specified,
-all configuration tests will be re-run
-regardless of whether the
-cached results are out of date.
-This can be used to explicitly
-force the configuration tests to be updated
-in response to an otherwise unconfigured change
-in a system header file or compiler.
-
-.TP
---config=cache
-If this option is specified,
-no configuration tests will be rerun
-and all results will be taken from cache.
-Note that scons will still consider it an error
-if --config=cache is specified
-and a necessary test does not
-yet have any results in the cache.
-
-.TP
-.RI "-C" " directory" ",  --directory=" directory
-Change to the specified
-.I directory
-before searching for the
-.IR SConstruct ,
-.IR Sconstruct ,
-or
-.I sconstruct
-file, or doing anything
-else.  Multiple
-.B -C
-options are interpreted
-relative to the previous one, and the right-most
-.B -C
-option wins. (This option is nearly
-equivalent to
-.BR "-f directory/SConstruct" ,
-except that it will search for
-.IR SConstruct ,
-.IR Sconstruct ,
-or
-.I sconstruct
-in the specified directory.)
-
-.\" .TP
-.\" -d
-.\" Display dependencies while building target files.  Useful for
-.\" figuring out why a specific file is being rebuilt, as well as
-.\" general debugging of the build process.
-
-.TP
--D
-Works exactly the same way as the
-.B -u
-option except for the way default targets are handled.
-When this option is used and no targets are specified on the command line,
-all default targets are built, whether or not they are below the current
-directory.
-
-.TP
-.RI --debug= type
-Debug the build process.
-.I type
-specifies what type of debugging:
-
-.TP
---debug=count
-Print how many objects are created
-of the various classes used internally by SCons
-before and after reading the SConscript files
-and before and after building targets.
-This is not supported when SCons is executed with the Python
-.B -O
-(optimized) option
-or when the SCons modules
-have been compiled with optimization
-(that is, when executing from
-.B *.pyo
-files).
-
-.TP
---debug=duplicate
-Print a line for each unlink/relink (or copy) of a variant file from
-its source file.  Includes debugging info for unlinking stale variant
-files, as well as unlinking old targets before building them.
-
-.TP
---debug=dtree
-A synonym for the newer
-.B --tree=derived
-option.
-This will be deprecated in some future release
-and ultimately removed.
-
-.TP
---debug=explain
-Print an explanation of precisely why
-.B scons
-is deciding to (re-)build any targets.
-(Note:  this does not print anything
-for targets that are
-.I not
-rebuilt.)
-
-.TP
---debug=findlibs
-Instruct the scanner that searches for libraries
-to print a message about each potential library
-name it is searching for,
-and about the actual libraries it finds.
-
-.TP
---debug=includes
-Print the include tree after each top-level target is built.
-This is generally used to find out what files are included by the sources
-of a given derived file:
-
-.ES
-$ scons --debug=includes foo.o
-.EE
-
-.TP
---debug=memoizer
-Prints a summary of hits and misses using the Memoizer,
-an internal subsystem that counts
-how often SCons uses cached values in memory
-instead of recomputing them each time they're needed.
-
-.TP
---debug=memory
-Prints how much memory SCons uses
-before and after reading the SConscript files
-and before and after building targets.
-
-.TP
---debug=nomemoizer
-A deprecated option preserved for backwards compatibility.
-
-.TP
---debug=objects
-Prints a list of the various objects
-of the various classes used internally by SCons.
-
-.TP
---debug=pdb
-Re-run SCons under the control of the
-.RI pdb
-Python debugger.
-
-.TP
---debug=prepare
-Print a line each time any target (internal or external)
-is prepared for building.
-.B scons
-prints this for each target it considers, even if that
-target is up to date (see also --debug=explain).
-This can help debug problems with targets that aren't being
-built; it shows whether
-.B scons
-is at least considering them or not.
-
-.TP
---debug=presub
-Print the raw command line used to build each target
-before the construction environment variables are substituted.
-Also shows which targets are being built by this command.
-Output looks something like this:
-.ES
-$ scons --debug=presub
-Building myprog.o with action(s):
-  $SHCC $SHCFLAGS $SHCCFLAGS $CPPFLAGS $_CPPINCFLAGS -c -o $TARGET $SOURCES
-\&...
-.EE
-
-.TP
---debug=stacktrace
-Prints an internal Python stack trace
-when encountering an otherwise unexplained error.
-
-.TP
---debug=stree
-A synonym for the newer
-.B --tree=all,status
-option.
-This will be deprecated in some future release
-and ultimately removed.
-
-.TP
---debug=time
-Prints various time profiling information:
-the time spent executing each individual build command;
-the total build time (time SCons ran from beginning to end);
-the total time spent reading and executing SConscript files;
-the total time spent SCons itself spend running
-(that is, not counting reading and executing SConscript files);
-and both the total time spent executing all build commands
-and the elapsed wall-clock time spent executing those build commands.
-(When
-.B scons
-is executed without the
-.B -j
-option,
-the elapsed wall-clock time will typically
-be slightly longer than the total time spent
-executing all the build commands,
-due to the SCons processing that takes place
-in between executing each command.
-When
-.B scons
-is executed
-.I with
-the
-.B -j
-option,
-and your build configuration allows good parallelization,
-the elapsed wall-clock time should
-be significantly smaller than the
-total time spent executing all the build commands,
-since multiple build commands and
-intervening SCons processing
-should take place in parallel.)
-
-.TP
---debug=tree
-A synonym for the newer
-.B --tree=all
-option.
-This will be deprecated in some future release
-and ultimately removed.
-
-.TP
-.RI --diskcheck= types
-Enable specific checks for
-whether or not there is a file on disk
-where the SCons configuration expects a directory
-(or vice versa),
-and whether or not RCS or SCCS sources exist
-when searching for source and include files.
-The
-.I types
-argument can be set to:
-.BR all ,
-to enable all checks explicitly
-(the default behavior);
-.BR none ,
-to disable all such checks;
-.BR match ,
-to check that files and directories on disk
-match SCons' expected configuration;
-.BR rcs ,
-to check for the existence of an RCS source
-for any missing source or include files;
-.BR sccs ,
-to check for the existence of an SCCS source
-for any missing source or include files.
-Multiple checks can be specified separated by commas;
-for example,
-.B --diskcheck=sccs,rcs
-would still check for SCCS and RCS sources,
-but disable the check for on-disk matches of files and directories.
-Disabling some or all of these checks
-can provide a performance boost for large configurations,
-or when the configuration will check for files and/or directories
-across networked or shared file systems,
-at the slight increased risk of an incorrect build
-or of not handling errors gracefully
-(if include files really should be
-found in SCCS or RCS, for example,
-or if a file really does exist
-where the SCons configuration expects a directory).
-
-.TP
-.RI --duplicate= ORDER
-There are three ways to duplicate files in a build tree: hard links,
-soft (symbolic) links and copies. The default behaviour of SCons is to
-prefer hard links to soft links to copies. You can specify different
-behaviours with this option.
-.IR ORDER
-must be one of
-.IR hard-soft-copy
-(the default),
-.IR soft-hard-copy ,
-.IR hard-copy ,
-.IR soft-copy
-or
-.IR copy .
-SCons will attempt to duplicate files using
-the mechanisms in the specified order.
-
-.\" .TP
-.\" -e, --environment-overrides
-.\" Variables from the execution environment override construction
-.\" variables from the SConscript files.
-
-.TP
-.RI -f " file" ", --file=" file ", --makefile=" file ", --sconstruct=" file
-Use
-.I file
-as the initial SConscript file.
-Multiple
-.B -f
-options may be specified,
-in which case
-.B scons
-will read all of the specified files.
-
-.TP
--h, --help
-Print a local help message for this build, if one is defined in
-the SConscript file(s), plus a line that describes the
-.B -H
-option for command-line option help.  If no local help message
-is defined, prints the standard help message about command-line
-options.  Exits after displaying the appropriate message.
-
-.TP
--H, --help-options
-Print the standard help message about command-line options and
-exit.
-
-.TP
--i, --ignore-errors
-Ignore all errors from commands executed to rebuild files.
-
-.TP
-.RI -I " directory" ", --include-dir=" directory
-Specifies a
-.I directory
-to search for
-imported Python modules.  If several
-.B -I
-options
-are used, the directories are searched in the order specified.
-
-.TP
---implicit-cache
-Cache implicit dependencies.
-This causes
-.B scons
-to use the implicit (scanned) dependencies
-from the last time it was run
-instead of scanning the files for implicit dependencies.
-This can significantly speed up SCons,
-but with the following limitations:
-.IP
-.B scons
-will not detect changes to implicit dependency search paths
-(e.g.
-.BR CPPPATH ", " LIBPATH )
-that would ordinarily
-cause different versions of same-named files to be used.
-.IP
-.B scons
-will miss changes in the implicit dependencies
-in cases where a new implicit
-dependency is added earlier in the implicit dependency search path
-(e.g.
-.BR CPPPATH ", " LIBPATH )
-than a current implicit dependency with the same name.
-
-.TP
---implicit-deps-changed
-Forces SCons to ignore the cached implicit dependencies. This causes the
-implicit dependencies to be rescanned and recached. This implies
-.BR --implicit-cache .
-
-.TP
---implicit-deps-unchanged
-Force SCons to ignore changes in the implicit dependencies.
-This causes cached implicit dependencies to always be used.
-This implies
-.BR --implicit-cache .
-
-.TP
---interactive
-Starts SCons in interactive mode.
-The SConscript files are read once and a
-.B "scons>>>"
-prompt is printed.
-Targets may now be rebuilt by typing commands at interactive prompt
-without having to re-read the SConscript files
-and re-initialize the dependency graph from scratch.
-
-SCons interactive mode supports the following commands:
-
-.RS 10
-.TP 6
-.BI build "[OPTIONS] [TARGETS] ..."
-Builds the specified
-.I TARGETS
-(and their dependencies)
-with the specified
-SCons command-line
-.IR OPTIONS .
-.B b
-and
-.B scons
-are synonyms.
-
-The following SCons command-line options affect the
-.B build
-command:
-
-.ES
---cache-debug=FILE
---cache-disable, --no-cache
---cache-force, --cache-populate
---cache-show
---debug=TYPE
--i, --ignore-errors
--j N, --jobs=N
--k, --keep-going
--n, --no-exec, --just-print, --dry-run, --recon
--Q
--s, --silent, --quiet
---taskmastertrace=FILE
---tree=OPTIONS
-.EE
-
-.IP "" 6
-Any other SCons command-line options that are specified
-do not cause errors
-but have no effect on the
-.B build
-command
-(mainly because they affect how the SConscript files are read,
-which only happens once at the beginning of interactive mode).
-
-.TP 6
-.BI clean "[OPTIONS] [TARGETS] ..."
-Cleans the specified
-.I TARGETS
-(and their dependencies)
-with the specified options.
-.B c
-is a synonym.
-This command is itself a synonym for
-.B "build --clean"
-
-.TP 6
-.BI exit
-Exits SCons interactive mode.
-You can also exit by terminating input
-(CTRL+D on UNIX or Linux systems,
-CTRL+Z on Windows systems).
-
-.TP 6
-.BI help "[COMMAND]"
-Provides a help message about
-the commands available in SCons interactive mode.
-If
-.I COMMAND
-is specified,
-.B h
-and
-.B ?
-are synonyms.
-
-.TP 6
-.BI shell "[COMMANDLINE]"
-Executes the specified
-.I COMMANDLINE
-in a subshell.
-If no
-.I COMMANDLINE
-is specified,
-executes the interactive command interpreter
-specified in the
-.B SHELL
-environment variable
-(on UNIX and Linux systems)
-or the
-.B COMSPEC
-environment variable
-(on Windows systems).
-.B sh
-and
-.B !
-are synonyms.
-
-.TP 6
-.B version
-Prints SCons version information.
-.RE
-
-.IP
-An empty line repeats the last typed command.
-Command-line editing can be used if the
-.B readline
-module is available.
-
-.ES
-$ scons --interactive
-scons: Reading SConscript files ...
-scons: done reading SConscript files.
-scons>>> build -n prog
-scons>>> exit
-.EE
-
-.TP
-.RI -j " N" ", --jobs=" N
-Specifies the number of jobs (commands) to run simultaneously.
-If there is more than one
-.B -j
-option, the last one is effective.
-.\" ??? If the
-.\" .B -j
-.\" option
-.\" is specified without an argument,
-.\" .B scons
-.\" will not limit the number of
-.\" simultaneous jobs.
-
-.TP
--k, --keep-going
-Continue as much as possible after an error.  The target that
-failed and those that depend on it will not be remade, but other
-targets specified on the command line will still be processed.
-
-.\" .TP
-.\" .RI  -l " N" ", --load-average=" N ", --max-load=" N
-.\" No new jobs (commands) will be started if
-.\" there are other jobs running and the system load
-.\" average is at least
-.\" .I N
-.\" (a floating-point number).
-
-.\"
-.\" .TP
-.\" --list-derived
-.\" List derived files (targets, dependencies) that would be built,
-.\" but do not build them.
-.\" [XXX This can probably go away with the right
-.\" combination of other options.  Revisit this issue.]
-.\"
-.\" .TP
-.\" --list-actions
-.\" List derived files that would be built, with the actions
-.\" (commands) that build them.  Does not build the files.
-.\" [XXX This can probably go away with the right
-.\" combination of other options.  Revisit this issue.]
-.\"
-.\" .TP
-.\" --list-where
-.\" List derived files that would be built, plus where the file is
-.\" defined (file name and line number).  Does not build the files.
-.\" [XXX This can probably go away with the right
-.\" combination of other options.  Revisit this issue.]
-
-.TP
--m
-Ignored for compatibility with non-GNU versions of
-.BR make .
-
-.TP
-.RI --max-drift= SECONDS
-Set the maximum expected drift in the modification time of files to
-.IR SECONDS .
-This value determines how long a file must be unmodified
-before its cached content signature
-will be used instead of
-calculating a new content signature (MD5 checksum)
-of the file's contents.
-The default value is 2 days, which means a file must have a
-modification time of at least two days ago in order to have its
-cached content signature used.
-A negative value means to never cache the content
-signature and to ignore the cached value if there already is one. A value
-of 0 means to always use the cached signature,
-no matter how old the file is.
-
-.TP
-.RI --md5-chunksize= KILOBYTES
-Set the block size used to compute MD5 signatures to
-.IR KILOBYTES . 
-This value determines the size of the chunks which are read in at once when
-computing MD5 signatures.  Files below that size are fully stored in memory
-before performing the signature computation while bigger files are read in
-block-by-block. A huge block-size leads to high memory consumption while a very
-small block-size slows down the build considerably.
-
-The default value is to use a chunk size of 64 kilobytes, which should
-be appropriate for most uses.
-
-.TP
--n, --just-print, --dry-run, --recon
-No execute.  Print the commands that would be executed to build
-any out-of-date target files, but do not execute the commands.
-
-.TP
-.RI --no-site-dir
-Prevents the automatic addition of the standard
-.I site_scons
-dirs to
-.IR sys.path .
-Also prevents loading the
-.I site_scons/site_init.py
-modules if they exist, and prevents adding their
-.I site_scons/site_tools
-dirs to the toolpath.
-
-.\" .TP
-.\" .RI -o " file" ", --old-file=" file ", --assume-old=" file
-.\" Do not rebuild
-.\" .IR file ,
-.\" and do
-.\" not rebuild anything due to changes in the contents of
-.\" .IR file .
-.\" .TP
-.\" .RI --override " file"
-.\" Read values to override specific build environment variables
-.\" from the specified
-.\" .IR file .
-.\" .TP
-.\" -p
-.\" Print the data base (construction environments,
-.\" Builder and Scanner objects) that are defined
-.\" after reading the SConscript files.
-.\" After printing, a normal build is performed
-.\" as usual, as specified by other command-line options.
-.\" This also prints version information
-.\" printed by the
-.\" .B -v
-.\" option.
-.\"
-.\" To print the database without performing a build do:
-.\"
-.\" .ES
-.\" scons -p -q
-.\" .EE
-
-.TP
-.RI --profile= file
-Run SCons under the Python profiler
-and save the results in the specified
-.IR file .
-The results may be analyzed using the Python
-pstats module.
-
-.TP
--q, --question
-Do not run any commands, or print anything.  Just return an exit
-status that is zero if the specified targets are already up to
-date, non-zero otherwise.
-.TP
--Q
-Quiets SCons status messages about
-reading SConscript files,
-building targets
-and entering directories.
-Commands that are executed
-to rebuild target files are still printed.
-
-.\" .TP
-.\" -r, -R, --no-builtin-rules, --no-builtin-variables
-.\" Clear the default construction variables.  Construction
-.\" environments that are created will be completely empty.
-
-.TP
---random
-Build dependencies in a random order.  This is useful when
-building multiple trees simultaneously with caching enabled,
-to prevent multiple builds from simultaneously trying to build
-or retrieve the same target files.
-
-.TP
--s, --silent, --quiet
-Silent.  Do not print commands that are executed to rebuild
-target files.
-Also suppresses SCons status messages.
-
-.TP
--S, --no-keep-going, --stop
-Ignored for compatibility with GNU
-.BR make .
-
-.TP
-.RI --site-dir= dir
-Uses the named dir as the site dir rather than the default
-.I site_scons
-dirs.  This dir will get prepended to
-.IR sys.path ,
-the module
-.IR dir /site_init.py
-will get loaded if it exists, and
-.IR dir /site_tools
-will get added to the default toolpath.
-
-The default set of
-.I site_scons
-dirs used when
-.I --site-dir
-is not specified depends on the system platform, as follows.  Note
-that the directories are examined in the order given, from most
-generic to most specific, so the last-executed site_init.py file is
-the most specific one (which gives it the chance to override
-everything else), and the dirs are prepended to the paths, again so
-the last dir examined comes first in the resulting path.
-
-.IP "Windows:"
-.nf
-    %ALLUSERSPROFILE/Application Data/scons/site_scons
-    %USERPROFILE%/Local Settings/Application Data/scons/site_scons
-    %APPDATA%/scons/site_scons
-    %HOME%/.scons/site_scons
-    ./site_scons
-.fi
-.IP "Mac OS X:"
-.nf
-    /Library/Application Support/SCons/site_scons
-    /opt/local/share/scons/site_scons (for MacPorts)
-    /sw/share/scons/site_scons (for Fink)
-    $HOME/Library/Application Support/SCons/site_scons
-    $HOME/.scons/site_scons
-    ./site_scons
-.fi
-.IP "Solaris:"
-.nf
-    /opt/sfw/scons/site_scons
-    /usr/share/scons/site_scons
-    $HOME/.scons/site_scons
-    ./site_scons
-.fi
-.IP "Linux, HPUX, and other Posix-like systems:"
-.nf
-    /usr/share/scons/site_scons
-    $HOME/.scons/site_scons
-    ./site_scons
-.fi
-
-.TP
-.RI --stack-size= KILOBYTES
-Set the size stack used to run threads to
-.IR KILOBYTES .
-This value determines the stack size of the threads used to run jobs.
-These are the threads that execute the actions of the builders for the
-nodes that are out-of-date.
-Note that this option has no effect unless the
-.B num_jobs
-option, which corresponds to -j and --jobs, is larger than one.  Using
-a stack size that is too small may cause stack overflow errors.  This
-usually shows up as segmentation faults that cause scons to abort
-before building anything.  Using a stack size that is too large will
-cause scons to use more memory than required and may slow down the entire
-build process.
-
-The default value is to use a stack size of 256 kilobytes, which should
-be appropriate for most uses.  You should not need to increase this value
-unless you encounter stack overflow errors.
-
-.TP
--t, --touch
-Ignored for compatibility with GNU
-.BR make .
-(Touching a file to make it
-appear up-to-date is unnecessary when using
-.BR scons .)
-
-.TP
-.RI --taskmastertrace= file
-Prints trace information to the specified
-.I file
-about how the internal Taskmaster object
-evaluates and controls the order in which Nodes are built.
-A file name of
-.B -
-may be used to specify the standard output.
-
-.TP
-.RI -tree= options
-Prints a tree of the dependencies
-after each top-level target is built.
-This prints out some or all of the tree,
-in various formats,
-depending on the
-.I options
-specified:
-
-.TP
---tree=all
-Print the entire dependency tree
-after each top-level target is built.
-This prints out the complete dependency tree,
-including implicit dependencies and ignored dependencies.
-
-.TP
---tree=derived
-Restricts the tree output to only derived (target) files,
-not source files.
-
-.TP
---tree=status
-Prints status information for each displayed node.
-
-.TP
---tree=prune
-Prunes the tree to avoid repeating dependency information
-for nodes that have already been displayed.
-Any node that has already been displayed
-will have its name printed in
-.BR "[square brackets]" ,
-as an indication that the dependencies
-for that node can be found by searching
-for the relevant output higher up in the tree.
-
-.IP
-Multiple options may be specified,
-separated by commas:
-
-.ES
-# Prints only derived files, with status information:
-scons --tree=derived,status
-
-# Prints all dependencies of target, with status information
-# and pruning dependencies of already-visited Nodes:
-scons --tree=all,prune,status target
-.EE
-
-.TP
--u, --up, --search-up
-Walks up the directory structure until an
-.I SConstruct ,
-.I Sconstruct
-or
-.I sconstruct
-file is found, and uses that
-as the top of the directory tree.
-If no targets are specified on the command line,
-only targets at or below the
-current directory will be built.
-
-.TP
--U
-Works exactly the same way as the
-.B -u
-option except for the way default targets are handled.
-When this option is used and no targets are specified on the command line,
-all default targets that are defined in the SConscript(s) in the current
-directory are built, regardless of what directory the resultant targets end
-up in.
-
-.TP
--v, --version
-Print the
-.B scons
-version, copyright information,
-list of authors, and any other relevant information.
-Then exit.
-
-.TP
--w, --print-directory
-Print a message containing the working directory before and
-after other processing.
-
-.TP
---no-print-directory
-Turn off -w, even if it was turned on implicitly.
-
-.TP
-.RI --warn= type ", --warn=no-" type
-Enable or disable warnings.
-.I type
-specifies the type of warnings to be enabled or disabled:
-
-.TP
---warn=all, --warn=no-all
-Enables or disables all warnings.
-
-.TP
---warn=cache-write-error, --warn=no-cache-write-error
-Enables or disables warnings about errors trying to
-write a copy of a built file to a specified
-.BR CacheDir ().
-These warnings are disabled by default.
-
-.TP
---warn=corrupt-sconsign, --warn=no-corrupt-sconsign
-Enables or disables warnings about unfamiliar signature data in
-.B .sconsign
-files.
-These warnings are enabled by default.
-
-.TP
---warn=dependency, --warn=no-dependency
-Enables or disables warnings about dependencies.
-These warnings are disabled by default.
-
-.TP
---warn=deprecated, --warn=no-deprecated
-Enables or disables all warnings about use of
-currently deprecated features.
-These warnings are enabled by default.
-Note that the
-.B --warn=no-deprecated
-option does not disable warnings about absolutely all deprecated features.
-Warnings for some deprecated features that have already been through
-several releases with deprecation warnings
-may be mandatory for a release or two
-before they are officially no longer supported by SCons.
-Warnings for some specific deprecated features
-may be enabled or disabled individually;
-see below.
-
-.RS
-.TP
---warn=deprecated-copy, --warn=no-deprecated-copy
-Enables or disables warnings about use of the deprecated
-.B env.Copy()
-method.
-
-.TP
---warn=deprecated-source-signatures, --warn=no-deprecated-source-signatures
-Enables or disables warnings about use of the deprecated
-.B SourceSignatures()
-function or
-.B env.SourceSignatures()
-method.
-
-.TP
---warn=deprecated-target-signatures, --warn=no-deprecated-target-signatures
-Enables or disables warnings about use of the deprecated
-.B TargetSignatures()
-function or
-.B env.TargetSignatures()
-method.
-.RE
-
-.TP
---warn=duplicate-environment, --warn=no-duplicate-environment
-Enables or disables warnings about attempts to specify a build
-of a target with two different construction environments
-that use the same action.
-These warnings are enabled by default.
-
-.TP
---warn=fortran-cxx-mix, --warn=no-fortran-cxx-mix
-Enables or disables the specific warning about linking
-Fortran and C++ object files in a single executable,
-which can yield unpredictable behavior with some compilers.
-
-.TP
---warn=future-deprecated, --warn=no-future-deprecated
-Enables or disables warnings about features
-that will be deprecated in the future.
-These warnings are disabled by default.
-Enabling this warning is especially
-recommended for projects that redistribute
-SCons configurations for other users to build,
-so that the project can be warned as soon as possible
-about to-be-deprecated features
-that may require changes to the configuration.
-
-.TP
---warn=link, --warn=no-link
-Enables or disables warnings about link steps.
-
-.TP
---warn=misleading-keywords, --warn=no-misleading-keywords
-Enables or disables warnings about use of the misspelled keywords
-.B targets
-and
-.B sources
-when calling Builders.
-(Note the last
-.B s
-characters, the correct spellings are
-.B target
-and
-.B source.)
-These warnings are enabled by default.
-
-.TP
---warn=missing-sconscript, --warn=no-missing-sconscript
-Enables or disables warnings about missing SConscript files.
-These warnings are enabled by default.
-
-.TP
---warn=no-md5-module, --warn=no-no-md5-module
-Enables or disables warnings about the version of Python
-not having an MD5 checksum module available.
-These warnings are enabled by default.
-
-.TP
---warn=no-metaclass-support, --warn=no-no-metaclass-support
-Enables or disables warnings about the version of Python
-not supporting metaclasses when the
-.B --debug=memoizer
-option is used.
-These warnings are enabled by default.
-
-.TP
---warn=no-object-count, --warn=no-no-object-count
-Enables or disables warnings about the
-.B --debug=object
-feature not working when
-.B scons
-is run with the python
-.B \-O
-option or from optimized Python (.pyo) modules.
-
-.TP
---warn=no-parallel-support, --warn=no-no-parallel-support
-Enables or disables warnings about the version of Python
-not being able to support parallel builds when the
-.B -j
-option is used.
-These warnings are enabled by default.
-
-.TP
---warn=python-version, --warn=no-python-version
-Enables or disables the warning about running
-SCons with a deprecated version of Python.
-These warnings are enabled by default.
-
-.TP
---warn=reserved-variable, --warn=no-reserved-variable
-Enables or disables warnings about attempts to set the
-reserved construction variable names
-.BR CHANGED_SOURCES ,
-.BR CHANGED_TARGETS ,
-.BR TARGET ,
-.BR TARGETS ,
-.BR SOURCE ,
-.BR SOURCES ,
-.BR UNCHANGED_SOURCES
-or
-.BR UNCHANGED_TARGETS .
-These warnings are disabled by default.
-
-.TP
---warn=stack-size, --warn=no-stack-size
-Enables or disables warnings about requests to set the stack size
-that could not be honored.
-These warnings are enabled by default.
-
-.\" .TP
-.\" .RI --write-filenames= file
-.\" Write all filenames considered into
-.\" .IR file .
-.\"
-.\" .TP
-.\" .RI -W " file" ", --what-if=" file ", --new-file=" file ", --assume-new=" file
-.\" Pretend that the target
-.\" .I file
-.\" has been
-.\" modified.  When used with the
-.\" .B -n
-.\" option, this
-.\" show you what would be rebuilt if you were to modify that file.
-.\" Without
-.\" .B -n
-.\" ... what? XXX
-.\"
-.\" .TP
-.\" --warn-undefined-variables
-.\" Warn when an undefined variable is referenced.
-
-.TP
-.RI -Y " repository" ", --repository=" repository ", --srcdir=" repository
-Search the specified repository for any input and target
-files not found in the local directory hierarchy.  Multiple
-.B -Y
-options may be specified, in which case the
-repositories are searched in the order specified.
-
-.SH CONFIGURATION FILE REFERENCE
-.\" .SS Python Basics
-.\" XXX Adding this in the future would be a help.
-.SS Construction Environments
-A construction environment is the basic means by which the SConscript
-files communicate build information to
-.BR scons .
-A new construction environment is created using the
-.B Environment
-function:
-
-.ES
-env = Environment()
-.EE
-
-Variables, called
-.I construction
-.IR variables ,
-may be set in a construction environment
-either by specifying them as keywords when the object is created
-or by assigning them a value after the object is created:
-
-.ES
-env = Environment(FOO = 'foo')
-env['BAR'] = 'bar'
-.EE
-
-As a convenience,
-construction variables may also be set or modified by the
-.I parse_flags
-keyword argument, which applies the
-.B ParseFlags
-method (described below) to the argument value
-after all other processing is completed.
-This is useful either if the exact content of the flags is unknown
-(for example, read from a control file)
-or if the flags are distributed to a number of construction variables.
-
-.ES
-env = Environment(parse_flags = '-Iinclude -DEBUG -lm')
-.EE
-
-This example adds 'include' to
-.BR CPPPATH ,
-\&'EBUG' to
-.BR CPPDEFINES ,
-and 'm' to
-.BR LIBS .
-
-By default, a new construction environment is
-initialized with a set of builder methods
-and construction variables that are appropriate
-for the current platform.
-An optional platform keyword argument may be
-used to specify that an environment should
-be initialized for a different platform:
-
-.ES
-env = Environment(platform = 'cygwin')
-env = Environment(platform = 'os2')
-env = Environment(platform = 'posix')
-env = Environment(platform = 'win32')
-.EE
-
-Specifying a platform initializes the appropriate
-construction variables in the environment
-to use and generate file names with prefixes
-and suffixes appropriate for the platform.
-
-Note that the
-.B win32
-platform adds the
-.B SystemDrive
-and
-.B SystemRoot
-variables from the user's external environment
-to the construction environment's
-.B ENV
-dictionary.
-This is so that any executed commands
-that use sockets to connect with other systems
-(such as fetching source files from
-external CVS repository specifications like
-.BR :pserver:anonymous@cvs.sourceforge.net:/cvsroot/scons )
-will work on Windows systems.
-
-The platform argument may be function or callable object,
-in which case the Environment() method
-will call the specified argument to update
-the new construction environment:
-
-.ES
-def my_platform(env):
-    env['VAR'] = 'xyzzy'
-
-env = Environment(platform = my_platform)
-.EE
-
-Additionally, a specific set of tools
-with which to initialize the environment
-may be specified as an optional keyword argument:
-
-.ES
-env = Environment(tools = ['msvc', 'lex'])
-.EE
-
-Non-built-in tools may be specified using the toolpath argument:
-
-.ES
-env = Environment(tools = ['default', 'foo'], toolpath = ['tools'])
-.EE
-
-This looks for a tool specification in tools/foo.py (as well as
-using the ordinary default tools for the platform).  foo.py should
-have two functions: generate(env, **kw) and exists(env).
-The
-.B generate()
-function
-modifies the passed-in environment
-to set up variables so that the tool
-can be executed;
-it may use any keyword arguments
-that the user supplies (see below)
-to vary its initialization.
-The
-.B exists()
-function should return a true
-value if the tool is available.
-Tools in the toolpath are used before
-any of the built-in ones.  For example, adding gcc.py to the toolpath
-would override the built-in gcc tool.
-Also note that the toolpath is
-stored in the environment for use
-by later calls to
-.BR Clone ()
-and
-.BR Tool ()
-methods:
-
-.ES
-base = Environment(toolpath=['custom_path'])
-derived = base.Clone(tools=['custom_tool'])
-derived.CustomBuilder()
-.EE
-
-The elements of the tools list may also
-be functions or callable objects,
-in which case the Environment() method
-will call the specified elements
-to update the new construction environment:
-
-.ES
-def my_tool(env):
-    env['XYZZY'] = 'xyzzy'
-
-env = Environment(tools = [my_tool])
-.EE
-
-The individual elements of the tools list
-may also themselves be two-element lists of the form
-.RI ( toolname ", " kw_dict ).
-SCons searches for the
-.I toolname
-specification file as described above, and
-passes
-.IR kw_dict ,
-which must be a dictionary, as keyword arguments to the tool's
-.B generate
-function.
-The
-.B generate
-function can use the arguments to modify the tool's behavior
-by setting up the environment in different ways
-or otherwise changing its initialization.
-
-.ES
-# in tools/my_tool.py:
-def generate(env, **kw):
-  # Sets MY_TOOL to the value of keyword argument 'arg1' or 1.
-  env['MY_TOOL'] = kw.get('arg1', '1')
-def exists(env):
-  return 1
-
-# in SConstruct:
-env = Environment(tools = ['default', ('my_tool', {'arg1': 'abc'})],
-                  toolpath=['tools'])
-.EE
-
-The tool definition (i.e. my_tool()) can use the PLATFORM variable from
-the environment it receives to customize the tool for different platforms.
-
-If no tool list is specified, then SCons will auto-detect the installed
-tools using the PATH variable in the ENV construction variable and the
-platform name when the Environment is constructed. Changing the PATH
-variable after the Environment is constructed will not cause the tools to
-be redetected.
-
-SCons supports the following tool specifications out of the box:
-
-.ES
-386asm
-aixc++
-aixcc
-aixf77
-aixlink
-ar
-as
-bcc32
-c++
-cc
-cvf
-dmd
-dvipdf
-dvips
-f77
-f90
-f95
-fortran
-g++
-g77
-gas
-gcc
-gfortran
-gnulink
-gs
-hpc++
-hpcc
-hplink
-icc
-icl
-ifl
-ifort
-ilink
-ilink32
-intelc
-jar
-javac
-javah
-latex
-lex
-link
-linkloc
-m4
-masm
-midl
-mingw
-mslib
-mslink
-mssdk
-msvc
-msvs
-mwcc
-mwld
-nasm
-pdflatex
-pdftex
-qt
-rmic
-rpcgen
-sgiar
-sgic++
-sgicc
-sgilink
-sunar
-sunc++
-suncc
-sunf77
-sunf90
-sunf95
-sunlink
-swig
-tar
-tex
-textfile
-tlib
-yacc
-zip
-.EE
-
-Additionally, there is a "tool" named
-.B default
-which configures the
-environment with a default set of tools for the current platform.
-
-On posix and cygwin platforms
-the GNU tools (e.g. gcc) are preferred by SCons,
-on Windows the Microsoft tools (e.g. msvc)
-followed by MinGW are preferred by SCons,
-and in OS/2 the IBM tools (e.g. icc) are preferred by SCons.
-
-.SS Builder Methods
-
-Build rules are specified by calling a construction
-environment's builder methods.
-The arguments to the builder methods are
-.B target
-(a list of targets to be built,
-usually file names)
-and
-.B source
-(a list of sources to be built,
-usually file names).
-
-Because long lists of file names
-can lead to a lot of quoting,
-.B scons
-supplies a
-.B Split()
-global function
-and a same-named environment method
-that split a single string
-into a list, separated on
-strings of white-space characters.
-(These are similar to the split() member function of Python strings
-but work even if the input isn't a string.)
-
-Like all Python arguments,
-the target and source arguments to a builder method
-can be specified either with or without
-the "target" and "source" keywords.
-When the keywords are omitted,
-the target is first,
-followed by the source.
-The following are equivalent examples of calling the Program builder method:
-
-.ES
-env.Program('bar', ['bar.c', 'foo.c'])
-env.Program('bar', Split('bar.c foo.c'))
-env.Program('bar', env.Split('bar.c foo.c'))
-env.Program(source =  ['bar.c', 'foo.c'], target = 'bar')
-env.Program(target = 'bar', Split('bar.c foo.c'))
-env.Program(target = 'bar', env.Split('bar.c foo.c'))
-env.Program('bar', source = 'bar.c foo.c'.split())
-.EE
-
-Target and source file names
-that are not absolute path names
-(that is, do not begin with
-.B /
-on POSIX systems
-or
-.B \\
-on Windows systems,
-with or without
-an optional drive letter)
-are interpreted relative to the directory containing the
-.B SConscript
-file being read.
-An initial
-.B #
-(hash mark)
-on a path name means that the rest of the file name
-is interpreted relative to
-the directory containing
-the top-level
-.B SConstruct
-file,
-even if the
-.B #
-is followed by a directory separator character
-(slash or backslash).
-
-Examples:
-
-.ES
-# The comments describing the targets that will be built
-# assume these calls are in a SConscript file in the
-# a subdirectory named "subdir".
-
-# Builds the program "subdir/foo" from "subdir/foo.c":
-env.Program('foo', 'foo.c')
-
-# Builds the program "/tmp/bar" from "subdir/bar.c":
-env.Program('/tmp/bar', 'bar.c')
-
-# An initial '#' or '#/' are equivalent; the following
-# calls build the programs "foo" and "bar" (in the
-# top-level SConstruct directory) from "subdir/foo.c" and
-# "subdir/bar.c", respectively:
-env.Program('#foo', 'foo.c')
-env.Program('#/bar', 'bar.c')
-
-# Builds the program "other/foo" (relative to the top-level
-# SConstruct directory) from "subdir/foo.c":
-env.Program('#other/foo', 'foo.c')
-.EE
-
-When the target shares the same base name
-as the source and only the suffix varies,
-and if the builder method has a suffix defined for the target file type,
-then the target argument may be omitted completely,
-and
-.B scons
-will deduce the target file name from
-the source file name.
-The following examples all build the
-executable program
-.B bar
-(on POSIX systems)
-or
-.B bar.exe
-(on Windows systems)
-from the bar.c source file:
-
-.ES
-env.Program(target = 'bar', source = 'bar.c')
-env.Program('bar', source = 'bar.c')
-env.Program(source = 'bar.c')
-env.Program('bar.c')
-.EE
-
-As a convenience, a
-.B srcdir
-keyword argument may be specified
-when calling a Builder.
-When specified,
-all source file strings that are not absolute paths
-will be interpreted relative to the specified
-.BR srcdir .
-The following example will build the
-.B build/prog
-(or
-.B build/prog.exe
-on Windows)
-program from the files
-.B src/f1.c
-and
-.BR src/f2.c :
-
-.ES
-env.Program('build/prog', ['f1.c', 'f2.c'], srcdir='src')
-.EE
-
-It is possible to override or add construction variables when calling a
-builder method by passing additional keyword arguments.
-These overridden or added
-variables will only be in effect when building the target, so they will not
-affect other parts of the build. For example, if you want to add additional
-libraries for just one program:
-
-.ES
-env.Program('hello', 'hello.c', LIBS=['gl', 'glut'])
-.EE
-
-or generate a shared library with a non-standard suffix:
-
-.ES
-env.SharedLibrary('word', 'word.cpp',
-                  SHLIBSUFFIX='.ocx',
-                  LIBSUFFIXES=['.ocx'])
-.EE
-
-(Note that both the $SHLIBSUFFIX and $LIBSUFFIXES variables must be set
-if you want SCons to search automatically
-for dependencies on the non-standard library names;
-see the descriptions of these variables, below, for more information.)
-
-It is also possible to use the
-.I parse_flags
-keyword argument in an override:
-
-.ES
-env = Program('hello', 'hello.c', parse_flags = '-Iinclude -DEBUG -lm')
-.EE
-
-This example adds 'include' to
-.BR CPPPATH ,
-\&'EBUG' to
-.BR CPPDEFINES ,
-and 'm' to
-.BR LIBS .
-
-Although the builder methods defined by
-.B scons
-are, in fact,
-methods of a construction environment object,
-they may also be called without an explicit environment:
-
-.ES
-Program('hello', 'hello.c')
-SharedLibrary('word', 'word.cpp')
-.EE
-
-In this case,
-the methods are called internally using a default construction
-environment that consists of the tools and values that
-.B scons
-has determined are appropriate for the local system.
-
-Builder methods that can be called without an explicit
-environment may be called from custom Python modules that you
-import into an SConscript file by adding the following
-to the Python module:
-
-.ES
-from SCons.Script import *
-.EE
-
-All builder methods return a list-like object
-containing Nodes that
-represent the target or targets that will be built.
-A
-.I Node
-is an internal SCons object
-which represents
-build targets or sources.
-
-The returned Node-list object
-can be passed to other builder methods as source(s)
-or passed to any SCons function or method
-where a filename would normally be accepted.
-For example, if it were necessary
-to add a specific
-.B -D
-flag when compiling one specific object file:
-
-.ES
-bar_obj_list = env.StaticObject('bar.c', CPPDEFINES='-DBAR')
-env.Program(source = ['foo.c', bar_obj_list, 'main.c'])
-.EE
-
-Using a Node in this way
-makes for a more portable build
-by avoiding having to specify
-a platform-specific object suffix
-when calling the Program() builder method.
-
-Note that Builder calls will automatically "flatten"
-the source and target file lists,
-so it's all right to have the bar_obj list
-return by the StaticObject() call
-in the middle of the source file list.
-If you need to manipulate a list of lists returned by Builders
-directly using Python,
-you can either build the list by hand:
-
-.ES
-foo = Object('foo.c')
-bar = Object('bar.c')
-objects = ['begin.o'] + foo + ['middle.o'] + bar + ['end.o']
-for object in objects:
-    print str(object)
-.EE
-
-Or you can use the
-.BR Flatten ()
-function supplied by scons
-to create a list containing just the Nodes,
-which may be more convenient:
-
-.ES
-foo = Object('foo.c')
-bar = Object('bar.c')
-objects = Flatten(['begin.o', foo, 'middle.o', bar, 'end.o'])
-for object in objects:
-    print str(object)
-.EE
-
-Note also that because Builder calls return
-a list-like object, not an actual Python list,
-you should
-.I not
-use the Python
-.B +=
-operator to append Builder results to a Python list.
-Because the list and the object are different types,
-Python will not update the original list in place,
-but will instead create a new Node-list object
-containing the concatenation of the list
-elements and the Builder results.
-This will cause problems for any other Python variables
-in your SCons configuration
-that still hold on to a reference to the original list.
-Instead, use the Python
-.B .extend()
-method to make sure the list is updated in-place.
-Example:
-
-.ES
-object_files = []
-
-# Do NOT use += as follows:
-#
-#    object_files += Object('bar.c')
-#
-# It will not update the object_files list in place.
-#
-# Instead, use the .extend() method:
-object_files.extend(Object('bar.c'))
-
-.EE
-
-The path name for a Node's file may be used
-by passing the Node to the Python-builtin
-.B str()
-function:
-
-.ES
-bar_obj_list = env.StaticObject('bar.c', CPPDEFINES='-DBAR')
-print "The path to bar_obj is:", str(bar_obj_list[0])
-.EE
-
-Note again that because the Builder call returns a list,
-we have to access the first element in the list
-.B (bar_obj_list[0])
-to get at the Node that actually represents
-the object file.
-
-Builder calls support a
-.B chdir
-keyword argument that
-specifies that the Builder's action(s)
-should be executed
-after changing directory.
-If the
-.B chdir
-argument is
-a string or a directory Node,
-scons will change to the specified directory.
-If the
-.B chdir
-is not a string or Node
-and is non-zero,
-then scons will change to the
-target file's directory.
-
-.ES
-# scons will change to the "sub" subdirectory
-# before executing the "cp" command.
-env.Command('sub/dir/foo.out', 'sub/dir/foo.in',
-            "cp dir/foo.in dir/foo.out",
-            chdir='sub')
-
-# Because chdir is not a string, scons will change to the
-# target's directory ("sub/dir") before executing the
-# "cp" command.
-env.Command('sub/dir/foo.out', 'sub/dir/foo.in',
-            "cp foo.in foo.out",
-            chdir=1)
-.EE
-
-Note that scons will
-.I not
-automatically modify
-its expansion of
-construction variables like
-.B $TARGET
-and
-.B $SOURCE
-when using the chdir
-keyword argument--that is,
-the expanded file names
-will still be relative to
-the top-level SConstruct directory,
-and consequently incorrect
-relative to the chdir directory.
-If you use the chdir keyword argument,
-you will typically need to supply a different
-command line using
-expansions like
-.B ${TARGET.file}
-and
-.B ${SOURCE.file}
-to use just the filename portion of the
-targets and source.
-
-.B scons
-provides the following builder methods:
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-'\" BEGIN GENERATED BUILDER DESCRIPTIONS
-'\"
-'\" The descriptions below of the various SCons Builders are generated
-'\" from the .xml files that live next to the various Python modules in
-'\" the build enginer library.  If you're reading this [gnt]roff file
-'\" with an eye towards patching this man page, you can still submit
-'\" a diff against this text, but it will have to be translated to a
-'\" diff against the underlying .xml file before the patch is actually
-'\" accepted.  If you do that yourself, it will make it easier to
-'\" integrate the patch.
-'\"
-'\" BEGIN GENERATED BUILDER DESCRIPTIONS
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.so builders.man
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-'\" END GENERATED BUILDER DESCRIPTIONS
-'\"
-'\" The descriptions above of the various SCons Builders are generated
-'\" from the .xml files that live next to the various Python modules in
-'\" the build enginer library.  If you're reading this [gnt]roff file
-'\" with an eye towards patching this man page, you can still submit
-'\" a diff against this text, but it will have to be translated to a
-'\" diff against the underlying .xml file before the patch is actually
-'\" accepted.  If you do that yourself, it will make it easier to
-'\" integrate the patch.
-'\"
-'\" END GENERATED BUILDER DESCRIPTIONS
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-
-.P
-All
-targets of builder methods automatically depend on their sources.
-An explicit dependency can
-be specified using the
-.B Depends
-method of a construction environment (see below).
-
-In addition,
-.B scons
-automatically scans
-source files for various programming languages,
-so the dependencies do not need to be specified explicitly.
-By default, SCons can
-C source files,
-C++ source files,
-Fortran source files with
-.B .F
-(POSIX systems only),
-.B .fpp,
-or
-.B .FPP
-file extensions,
-and assembly language files with
-.B .S
-(POSIX systems only),
-.B .spp,
-or
-.B .SPP
-files extensions
-for C preprocessor dependencies.
-SCons also has default support
-for scanning D source files,
-You can also write your own Scanners
-to add support for additional source file types.
-These can be added to the default
-Scanner object used by the
-.BR Object (),
-.BR StaticObject (),
-and
-.BR SharedObject ()
-Builders by adding them
-to the
-.B SourceFileScanner
-object.
-See the section "Scanner Objects"
-below, for more information about
-defining your own Scanner objects
-and using the
-.B SourceFileScanner
-object.
-
-.SS Methods and Functions to Do Things
-In addition to Builder methods,
-.B scons
-provides a number of other construction environment methods
-and global functions to
-manipulate the build configuration.
-
-Usually, a construction environment method
-and global function with the same name both exist
-so that you don't have to remember whether
-to a specific bit of functionality
-must be called with or without a construction environment.
-In the following list,
-if you call something as a global function
-it looks like:
-.ES
-.RI Function( arguments )
-.EE
-and if you call something through a construction
-environment it looks like:
-.ES
-.RI env.Function( arguments )
-.EE
-If you can call the functionality in both ways,
-then both forms are listed.
-
-Global functions may be called from custom Python modules that you
-import into an SConscript file by adding the following
-to the Python module:
-
-.ES
-from SCons.Script import *
-.EE
-
-Except where otherwise noted,
-the same-named
-construction environment method
-and global function
-provide the exact same functionality.
-The only difference is that,
-where appropriate,
-calling the functionality through a construction environment will
-substitute construction variables into
-any supplied strings.
-For example:
-
-.ES
-env = Environment(FOO = 'foo')
-Default('$FOO')
-env.Default('$FOO')
-.EE
-
-In the above example,
-the first call to the global
-.B Default()
-function will actually add a target named
-.B $FOO
-to the list of default targets,
-while the second call to the
-.B env.Default()
-construction environment method
-will expand the value
-and add a target named
-.B foo
-to the list of default targets.
-For more on construction variable expansion,
-see the next section on
-construction variables.
-
-Construction environment methods
-and global functions supported by
-.B scons
-include:
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-'\" BEGIN GENERATED FUNCTION DESCRIPTIONS
-'\"
-'\" The descriptions below of the various SCons functions are generated
-'\" from the .xml files that live next to the various Python modules in
-'\" the build enginer library.  If you're reading this [gnt]roff file
-'\" with an eye towards patching this man page, you can still submit
-'\" a diff against this text, but it will have to be translated to a
-'\" diff against the underlying .xml file before the patch is actually
-'\" accepted.  If you do that yourself, it will make it easier to
-'\" integrate the patch.
-'\"
-'\" BEGIN GENERATED FUNCTION DESCRIPTIONS
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.so functions.man
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-'\" END GENERATED FUNCTION DESCRIPTIONS
-'\"
-'\" The descriptions above of the various SCons functions are generated
-'\" from the .xml files that live next to the various Python modules in
-'\" the build enginer library.  If you're reading this [gnt]roff file
-'\" with an eye towards patching this man page, you can still submit
-'\" a diff against this text, but it will have to be translated to a
-'\" diff against the underlying .xml file before the patch is actually
-'\" accepted.  If you do that yourself, it will make it easier to
-'\" integrate the patch.
-'\"
-'\" END GENERATED FUNCTION DESCRIPTIONS
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-
-.SS SConscript Variables
-In addition to the global functions and methods,
-.B scons
-supports a number of Python variables
-that can be used in SConscript files
-to affect how you want the build to be performed.
-These variables may be accessed from custom Python modules that you
-import into an SConscript file by adding the following
-to the Python module:
-
-.ES
-from SCons.Script import *
-.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-ARGLIST
-A list
-.IR keyword = value
-arguments specified on the command line.
-Each element in the list is a tuple
-containing the
-.RI ( keyword , value )
-of the argument.
-The separate
-.I keyword
-and
-.I value
-elements of the tuple
-can be accessed by
-subscripting for element
-.B [0]
-and
-.B [1]
-of the tuple, respectively.
-
-Example:
-
-.ES
-print "first keyword, value =", ARGLIST[0][0], ARGLIST[0][1]
-print "second keyword, value =", ARGLIST[1][0], ARGLIST[1][1]
-third_tuple = ARGLIST[2]
-print "third keyword, value =", third_tuple[0], third_tuple[1]
-for key, value in ARGLIST:
-    # process key and value
-.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-ARGUMENTS
-A dictionary of all the
-.IR keyword = value
-arguments specified on the command line.
-The dictionary is not in order,
-and if a given keyword has
-more than one value assigned to it
-on the command line,
-the last (right-most) value is
-the one in the
-.B ARGUMENTS
-dictionary.
-
-Example:
-
-.ES
-if ARGUMENTS.get('debug', 0):
-    env = Environment(CCFLAGS = '-g')
-else:
-    env = Environment()
-.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-BUILD_TARGETS
-A list of the targets which
-.B scons
-will actually try to build,
-regardless of whether they were specified on
-the command line or via the
-.BR Default ()
-function or method.
-The elements of this list may be strings
-.I or
-nodes, so you should run the list through the Python
-.B str
-function to make sure any Node path names
-are converted to strings.
-
-Because this list may be taken from the
-list of targets specified using the
-.BR Default ()
-function or method,
-the contents of the list may change
-on each successive call to
-.BR Default ().
-See the
-.B DEFAULT_TARGETS
-list, below,
-for additional information.
-
-Example:
-
-.ES
-if 'foo' in BUILD_TARGETS:
-    print "Don't forget to test the `foo' program!"
-if 'special/program' in BUILD_TARGETS:
-    SConscript('special')
-.EE
-.IP
-Note that the
-.B BUILD_TARGETS
-list only contains targets expected listed
-on the command line or via calls to the
-.BR Default ()
-function or method.
-It does
-.I not
-contain all dependent targets that will be built as
-a result of making the sure the explicitly-specified
-targets are up to date.
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-COMMAND_LINE_TARGETS
-A list of the targets explicitly specified on
-the command line.
-If there are no targets specified on the command line,
-the list is empty.
-This can be used, for example,
-to take specific actions only
-when a certain target or targets
-is explicitly being built.
-
-Example:
-
-.ES
-if 'foo' in COMMAND_LINE_TARGETS:
-    print "Don't forget to test the `foo' program!"
-if 'special/program' in COMMAND_LINE_TARGETS:
-    SConscript('special')
-.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-DEFAULT_TARGETS
-A list of the target
-.I nodes
-that have been specified using the
-.BR Default ()
-function or method.
-The elements of the list are nodes,
-so you need to run them through the Python
-.B str
-function to get at the path name for each Node.
-
-Example:
-
-.ES
-print str(DEFAULT_TARGETS[0])
-if 'foo' in map(str, DEFAULT_TARGETS):
-    print "Don't forget to test the `foo' program!"
-.EE
-.IP
-The contents of the
-.B DEFAULT_TARGETS
-list change on on each successive call to the
-.BR Default ()
-function:
-
-.ES
-print map(str, DEFAULT_TARGETS)   # originally []
-Default('foo')
-print map(str, DEFAULT_TARGETS)   # now a node ['foo']
-Default('bar')
-print map(str, DEFAULT_TARGETS)   # now a node ['foo', 'bar']
-Default(None)
-print map(str, DEFAULT_TARGETS)   # back to []
-.EE
-.IP
-Consequently, be sure to use
-.B DEFAULT_TARGETS
-only after you've made all of your
-.BR Default ()
-calls,
-or else simply be careful of the order
-of these statements in your SConscript files
-so that you don't look for a specific
-default target before it's actually been added to the list.
-
-.SS Construction Variables
-.\" XXX From Gary Ruben, 23 April 2002:
-.\" I think it would be good to have an example with each construction
-.\" variable description in the documentation.
-.\" eg.
-.\" CC     The C compiler
-.\"    Example: env["CC"] = "c68x"
-.\"    Default: env["CC"] = "cc"
-.\"
-.\" CCCOM  The command line ...
-.\"    Example:
-.\"        To generate the compiler line c68x -ps -qq -mr -o $TARGET $SOURCES
-.\"        env["CC"] = "c68x"
-.\"        env["CFLAGS"] = "-ps -qq -mr"
-.\"        env["CCCOM"] = "$CC $CFLAGS -o $TARGET $SOURCES
-.\"    Default:
-.\"        (I dunno what this is ;-)
-A construction environment has an associated dictionary of
-.I construction variables
-that are used by built-in or user-supplied build rules.
-Construction variables must follow the same rules for
-Python identifiers:
-the initial character must be an underscore or letter,
-followed by any number of underscores, letters, or digits.
-
-A number of useful construction variables are automatically defined by
-scons for each supported platform, and additional construction variables
-can be defined by the user. The following is a list of the automatically
-defined construction variables:
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-'\" BEGIN GENERATED CONSTRUCTION VARIABLE DESCRIPTIONS
-'\"
-'\" The descriptions below of the various SCons construction variables
-'\" are generated from the .xml files that live next to the various
-'\" Python modules in the build enginer library.  If you're reading
-'\" this [gnt]roff file with an eye towards patching this man page,
-'\" you can still submit a diff against this text, but it will have to
-'\" be translated to a diff against the underlying .xml file before the
-'\" patch is actually accepted.  If you do that yourself, it will make
-'\" it easier to integrate the patch.
-'\"
-'\" BEGIN GENERATED CONSTRUCTION VARIABLE DESCRIPTIONS
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.so variables.man
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-'\" END GENERATED CONSTRUCTION VARIABLE DESCRIPTIONS
-'\"
-'\" The descriptions above of the various SCons construction variables
-'\" are generated from the .xml files that live next to the various
-'\" Python modules in the build enginer library.  If you're reading
-'\" this [gnt]roff file with an eye towards patching this man page,
-'\" you can still submit a diff against this text, but it will have to
-'\" be translated to a diff against the underlying .xml file before the
-'\" patch is actually accepted.  If you do that yourself, it will make
-'\" it easier to integrate the patch.
-'\"
-'\" END GENERATED CONSTRUCTION VARIABLE DESCRIPTIONS
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-
-.LP
-Construction variables can be retrieved and set using the
-.B Dictionary
-method of the construction environment:
-
-.ES
-dict = env.Dictionary()
-dict["CC"] = "cc"
-.EE
-
-or using the [] operator:
-
-.ES
-env["CC"] = "cc"
-.EE
-
-Construction variables can also be passed to the construction environment
-constructor:
-
-.ES
-env = Environment(CC="cc")
-.EE
-
-or when copying a construction environment using the
-.B Clone
-method:
-
-.ES
-env2 = env.Clone(CC="cl.exe")
-.EE
-
-.SS Configure Contexts
-
-.B scons
-supports
-.I configure contexts,
-an integrated mechanism similar to the
-various AC_CHECK macros in GNU autoconf
-for testing for the existence of C header
-files, libraries, etc.
-In contrast to autoconf,
-.B scons
-does not maintain an explicit cache of the tested values,
-but uses its normal dependency tracking to keep the checked values
-up to date. However, users may override this behaviour with the
-.B --config
-command line option.
-
-The following methods can be used to perform checks:
-
-.TP
-.RI Configure( env ", [" custom_tests ", " conf_dir ", " log_file ", " config_h ", " clean ", " help])
-.TP
-.RI env.Configure([ custom_tests ", " conf_dir ", " log_file ", " config_h ", " clean ", " help])
-This creates a configure context, which can be used to perform checks.
-.I env
-specifies the environment for building the tests.
-This environment may be modified when performing checks.
-.I custom_tests
-is a dictionary containing custom tests.
-See also the section about custom tests below.
-By default, no custom tests are added to the configure context.
-.I conf_dir
-specifies a directory where the test cases are built.
-Note that this directory is not used for building
-normal targets.
-The default value is the directory
-#/.sconf_temp.
-.I log_file
-specifies a file which collects the output from commands
-that are executed to check for the existence of header files, libraries, etc.
-The default is the file #/config.log.
-If you are using the
-.BR VariantDir ()
-method,
-you may want to specify a subdirectory under your variant directory.
-.I config_h
-specifies a C header file where the results of tests
-will be written, e.g. #define HAVE_STDIO_H, #define HAVE_LIBM, etc.
-The default is to not write a
-.B config.h
-file.
-You can specify the same
-.B config.h
-file in multiple calls to Configure,
-in which case
-.B scons
-will concatenate all results in the specified file.
-Note that SCons
-uses its normal dependency checking
-to decide if it's necessary to rebuild
-the specified
-.I config_h
-file.
-This means that the file is not necessarily re-built each
-time scons is run,
-but is only rebuilt if its contents will have changed
-and some target that depends on the
-.I config_h
-file is being built.
-
-The optional
-.B clean
-and
-.B help
-arguments can be used to suppress execution of the configuration
-tests when the
-.B -c/--clean
-or
-.B -H/-h/--help
-options are used, respectively.
-The default behavior is always to execute
-configure context tests,
-since the results of the tests may
-affect the list of targets to be cleaned
-or the help text.
-If the configure tests do not affect these,
-then you may add the
-.B clean=False
-or
-.B help=False
-arguments
-(or both)
-to avoid unnecessary test execution.
-
-.EE
-A created
-.B Configure
-instance has the following associated methods:
-
-.TP
-.RI SConf.Finish( context )
-.TP
-.IR sconf .Finish()
-This method should be called after configuration is done.
-It returns the environment as modified
-by the configuration checks performed.
-After this method is called, no further checks can be performed
-with this configuration context.
-However, you can create a new
-.RI Configure
-context to perform additional checks.
-Only one context should be active at a time.
-
-The following Checks are predefined.
-(This list will likely grow larger as time
-goes by and developers contribute new useful tests.)
-
-.TP
-.RI SConf.CheckHeader( context ", " header ", [" include_quotes ", " language ])
-.TP
-.IR sconf .CheckHeader( header ", [" include_quotes ", " language ])
-Checks if
-.I header
-is usable in the specified language.
-.I header
-may be a list,
-in which case the last item in the list
-is the header file to be checked,
-and the previous list items are
-header files whose
-.B #include
-lines should precede the
-header line being checked for.
-The optional argument
-.I include_quotes
-must be
-a two character string, where the first character denotes the opening
-quote and the second character denotes the closing quote.
-By default, both characters  are " (double quote).
-The optional argument
-.I language
-should be either
-.B C
-or
-.B C++
-and selects the compiler to be used for the check.
-Returns 1 on success and 0 on failure.
-
-.TP
-.RI SConf.CheckCHeader( context ", " header ", [" include_quotes ])
-.TP
-.IR sconf .CheckCHeader( header ", [" include_quotes ])
-This is a wrapper around
-.B SConf.CheckHeader
-which checks if
-.I header
-is usable in the C language.
-.I header
-may be a list,
-in which case the last item in the list
-is the header file to be checked,
-and the previous list items are
-header files whose
-.B #include
-lines should precede the
-header line being checked for.
-The optional argument
-.I include_quotes
-must be
-a two character string, where the first character denotes the opening
-quote and the second character denotes the closing quote (both default
-to \N'34').
-Returns 1 on success and 0 on failure.
-
-.TP
-.RI SConf.CheckCXXHeader( context ", " header ", [" include_quotes ])
-.TP
-.IR sconf .CheckCXXHeader( header ", [" include_quotes ])
-This is a wrapper around
-.B SConf.CheckHeader
-which checks if
-.I header
-is usable in the C++ language.
-.I header
-may be a list,
-in which case the last item in the list
-is the header file to be checked,
-and the previous list items are
-header files whose
-.B #include
-lines should precede the
-header line being checked for.
-The optional argument
-.I include_quotes
-must be
-a two character string, where the first character denotes the opening
-quote and the second character denotes the closing quote (both default
-to \N'34').
-Returns 1 on success and 0 on failure.
-
-.TP
-.RI SConf.CheckFunc( context, ", " function_name ", [" header ", " language ])
-.TP
-.IR sconf .CheckFunc( function_name ", [" header ", " language ])
-Checks if the specified
-C or C++ function is available.
-.I function_name
-is the name of the function to check for.
-The optional
-.I header
-argument is a string
-that will be
-placed at the top
-of the test file
-that will be compiled
-to check if the function exists;
-the default is:
-.ES
-#ifdef __cplusplus
-extern "C"
-#endif
-char function_name();
-.EE
-The optional
-.I language
-argument should be
-.B C
-or
-.B C++
-and selects the compiler to be used for the check;
-the default is "C".
-
-.TP
-.RI SConf.CheckLib( context ", [" library ", " symbol ", " header ", " language ", " autoadd=1 ])
-.TP
-.IR sconf .CheckLib([ library ", " symbol ", " header ", " language ", " autoadd=1 ])
-Checks if
-.I library
-provides
-.IR symbol .
-If the value of
-.I autoadd
-is 1 and the library provides the specified
-.IR symbol ,
-appends the library to the LIBS construction environment variable.
-.I library
-may also be None (the default),
-in which case
-.I symbol
-is checked with the current LIBS variable,
-or a list of library names,
-in which case each library in the list
-will be checked for
-.IR symbol .
-If
-.I symbol
-is not set or is
-.BR None ,
-then
-.BR SConf.CheckLib ()
-just checks if
-you can link against the specified
-.IR library .
-The optional
-.I language
-argument should be
-.B C
-or
-.B C++
-and selects the compiler to be used for the check;
-the default is "C".
-The default value for
-.I autoadd
-is 1.
-This method returns 1 on success and 0 on error.
-
-.TP
-.RI SConf.CheckLibWithHeader( context ", " library ", " header ", " language ", [" call ", " autoadd ])
-.TP
-.IR sconf .CheckLibWithHeader( library ", " header ", " language ", [" call ", " autoadd ])
-
-In contrast to the
-.RI SConf.CheckLib
-call, this call provides a more sophisticated way to check against libraries.
-Again,
-.I library
-specifies the library or a list of libraries to check.
-.I header
-specifies a header to check for.
-.I header
-may be a list,
-in which case the last item in the list
-is the header file to be checked,
-and the previous list items are
-header files whose
-.B #include
-lines should precede the
-header line being checked for.
-.I language
-may be one of 'C','c','CXX','cxx','C++' and 'c++'.
-.I call
-can be any valid expression (with a trailing ';').
-If
-.I call
-is not set,
-the default simply checks that you
-can link against the specified
-.IR library .
-.I autoadd
-specifies whether to add the library to the environment (only if the check
-succeeds). This method returns 1 on success and 0 on error.
-
-.TP
-.RI SConf.CheckType( context ", " type_name ", [" includes ", " language ])
-.TP
-.IR sconf .CheckType( type_name ", [" includes ", " language ])
-Checks for the existence of a type defined by
-.BR typedef .
-.I type_name
-specifies the typedef name to check for.
-.I includes
-is a string containing one or more
-.B #include
-lines that will be inserted into the program
-that will be run to test for the existence of the type.
-The optional
-.I language
-argument should be
-.B C
-or
-.B C++
-and selects the compiler to be used for the check;
-the default is "C".
-Example:
-.ES
-sconf.CheckType('foo_type', '#include "my_types.h"', 'C++')
-.EE
-
-.TP
-.RI Configure.CheckCC( self )
-Checks whether the C compiler (as defined by the CC construction variable) works
-by trying to compile a small source file.
-
-By default, SCons only detects if there is a program with the correct name, not
-if it is a functioning compiler.
-
-This uses the exact same command than the one used by the object builder for C
-source file, so it can be used to detect if a particular compiler flag works or
-not.
-
-.TP
-.RI Configure.CheckCXX( self )
-Checks whether the C++ compiler (as defined by the CXX construction variable)
-works by trying to compile a small source file. By default, SCons only detects
-if there is a program with the correct name, not if it is a functioning compiler.
-
-This uses the exact same command than the one used by the object builder for
-CXX source files, so it can be used to detect if a particular compiler flag
-works or not.
-
-.TP
-.RI Configure.CheckSHCC( self )
-Checks whether the C compiler (as defined by the SHCC construction variable) works
-by trying to compile a small source file. By default, SCons only detects if
-there is a program with the correct name, not if it is a functioning compiler.
-
-This uses the exact same command than the one used by the object builder for C
-source file, so it can be used to detect if a particular compiler flag works or
-not. This does not check whether the object code can be used to build a shared
-library, only that the compilation (not link) succeeds.
-
-.TP
-.RI Configure.CheckSHCXX( self )
-Checks whether the C++ compiler (as defined by the SHCXX construction variable)
-works by trying to compile a small source file. By default, SCons only detects
-if there is a program with the correct name, not if it is a functioning compiler.
-
-This uses the exact same command than the one used by the object builder for
-CXX source files, so it can be used to detect if a particular compiler flag
-works or not. This does not check whether the object code can be used to build
-a shared library, only that the compilation (not link) succeeds.
-
-.EE
-Example of a typical Configure usage:
-
-.ES
-env = Environment()
-conf = Configure( env )
-if not conf.CheckCHeader( 'math.h' ):
-    print 'We really need math.h!'
-    Exit(1)
-if conf.CheckLibWithHeader( 'qt', 'qapp.h', 'c++',
-        'QApplication qapp(0,0);' ):
-    # do stuff for qt - usage, e.g.
-    conf.env.Append( CPPFLAGS = '-DWITH_QT' )
-env = conf.Finish()
-.EE
-
-.TP
-.RI SConf.CheckTypeSize( context ", " type_name ", [" header ", " language ", " expect ])
-.TP
-.IR sconf .CheckTypeSize( type_name ", [" header ", " language ", " expect ])
-Checks for the size of a type defined by
-.BR typedef .
-.I type_name
-specifies the typedef name to check for.
-The optional
-.I header
-argument is a string
-that will be
-placed at the top
-of the test file
-that will be compiled
-to check if the function exists;
-the default is empty.
-The optional
-.I language
-argument should be
-.B C
-or
-.B C++
-and selects the compiler to be used for the check;
-the default is "C".
-The optional
-.I expect
-argument should be an integer.
-If this argument is used,
-the function will only check whether the type
-given in type_name has the expected size (in bytes).
-For example,
-.B "CheckTypeSize('short', expect = 2)"
-will return success only if short is two bytes.
-
-.ES
-.EE
-
-.TP
-.RI SConf.CheckDeclaration( context ", " symbol ", [" includes ", " language ])
-.TP
-.IR sconf .CheckDeclaration( symbol ", [" includes ", " language ])
-Checks if the specified
-.I symbol
-is declared.
-.I includes
-is a string containing one or more
-.B #include
-lines that will be inserted into the program
-that will be run to test for the existence of the type.
-The optional
-.I language
-argument should be
-.B C
-or
-.B C++
-and selects the compiler to be used for the check;
-the default is "C".
-
-.TP
-.RI SConf.Define( context ", " symbol ", [" value ", " comment ])
-.TP
-.IR sconf .Define( symbol ", [" value ", " comment ])
-This function does not check for anything, but defines a
-preprocessor symbol that will be added to the configuration header file.
-It is the equivalent of AC_DEFINE,
-and defines the symbol
-.I name
-with the optional
-.B value
-and the optional comment
-.BR comment .
-
-.IP
-Examples:
-
-.ES
-env = Environment()
-conf = Configure( env )
-
-# Puts the following line in the config header file:
-#    #define A_SYMBOL
-conf.Define('A_SYMBOL')
-
-# Puts the following line in the config header file:
-#    #define A_SYMBOL 1
-conf.Define('A_SYMBOL', 1)
-.EE
-
-.IP
-Be careful about quoting string values, though:
-
-.ES
-env = Environment()
-conf = Configure( env )
-
-# Puts the following line in the config header file:
-#    #define A_SYMBOL YA
-conf.Define('A_SYMBOL', "YA")
-
-# Puts the following line in the config header file:
-#    #define A_SYMBOL "YA"
-conf.Define('A_SYMBOL', '"YA"')
-.EE
-
-.IP
-For comment:
-
-.ES
-env = Environment()
-conf = Configure( env )
-
-# Puts the following lines in the config header file:
-#    /* Set to 1 if you have a symbol */
-#    #define A_SYMBOL 1
-conf.Define('A_SYMBOL', 1, 'Set to 1 if you have a symbol')
-.EE
-
-.EE
-You can define your own custom checks.
-in addition to the predefined checks.
-These are passed in a dictionary to the Configure function.
-This dictionary maps the names of the checks
-to user defined Python callables
-(either Python functions or class instances implementing the
-.I __call__
-method).
-The first argument of the call is always a
-.I CheckContext
-instance followed by the arguments,
-which must be supplied by the user of the check.
-These CheckContext instances define the following methods:
-
-.TP
-.RI CheckContext.Message( self ", " text )
-
-Usually called before the check is started.
-.I text
-will be displayed to the user, e.g. 'Checking for library X...'
-
-.TP
-.RI CheckContext.Result( self, ", " res )
-
-Usually called after the check is done.
-.I res
-can be either an integer or a string. In the former case, 'yes' (res != 0)
-or 'no' (res == 0) is displayed to the user, in the latter case the
-given string is displayed.
-
-.TP
-.RI CheckContext.TryCompile( self ", " text ", " extension )
-Checks if a file with the specified
-.I extension
-(e.g. '.c') containing
-.I text
-can be compiled using the environment's
-.B Object
-builder. Returns 1 on success and 0 on failure.
-
-.TP
-.RI CheckContext.TryLink( self ", " text ", " extension )
-Checks, if a file with the specified
-.I extension
-(e.g. '.c') containing
-.I text
-can be compiled using the environment's
-.B Program
-builder. Returns 1 on success and 0 on failure.
-
-.TP
-.RI CheckContext.TryRun( self ", " text ", " extension )
-Checks, if a file with the specified
-.I extension
-(e.g. '.c') containing
-.I text
-can be compiled using the environment's
-.B Program
-builder. On success, the program is run. If the program
-executes successfully
-(that is, its return status is 0),
-a tuple
-.I (1, outputStr)
-is returned, where
-.I outputStr
-is the standard output of the
-program.
-If the program fails execution
-(its return status is non-zero),
-then (0, '') is returned.
-
-.TP
-.RI CheckContext.TryAction( self ", " action ", [" text ", " extension ])
-Checks if the specified
-.I action
-with an optional source file (contents
-.I text
-, extension
-.I extension
-= ''
-) can be executed.
-.I action
-may be anything which can be converted to a
-.B scons
-.RI Action.
-On success,
-.I (1, outputStr)
-is returned, where
-.I outputStr
-is the content of the target file.
-On failure
-.I (0, '')
-is returned.
-
-.TP
-.RI CheckContext.TryBuild( self ", " builder ", [" text ", " extension ])
-Low level implementation for testing specific builds;
-the methods above are based on this method.
-Given the Builder instance
-.I builder
-and the optional
-.I text
-of a source file with optional
-.IR extension ,
-this method returns 1 on success and 0 on failure. In addition,
-.I self.lastTarget
-is set to the build target node, if the build was successful.
-
-.EE
-Example for implementing and using custom tests:
-
-.ES
-def CheckQt(context, qtdir):
-    context.Message( 'Checking for qt ...' )
-    lastLIBS = context.env['LIBS']
-    lastLIBPATH = context.env['LIBPATH']
-    lastCPPPATH= context.env['CPPPATH']
-    context.env.Append(LIBS = 'qt', LIBPATH = qtdir + '/lib', CPPPATH = qtdir + '/include' )
-    ret = context.TryLink("""
-#include <qapp.h>
-int main(int argc, char **argv) {
-  QApplication qapp(argc, argv);
-  return 0;
-}
-""")
-    if not ret:
-        context.env.Replace(LIBS = lastLIBS, LIBPATH=lastLIBPATH, CPPPATH=lastCPPPATH)
-    context.Result( ret )
-    return ret
-
-env = Environment()
-conf = Configure( env, custom_tests = { 'CheckQt' : CheckQt } )
-if not conf.CheckQt('/usr/lib/qt'):
-    print 'We really need qt!'
-    Exit(1)
-env = conf.Finish()
-.EE
-
-.SS Command-Line Construction Variables
-
-Often when building software,
-some variables must be specified at build time.
-For example, libraries needed for the build may be in non-standard
-locations, or site-specific compiler options may need to be passed to the
-compiler.
-.B scons
-provides a
-.B Variables
-object to support overriding construction variables
-on the command line:
-.ES
-$ scons VARIABLE=foo
-.EE
-The variable values can also be specified in a text-based SConscript file.
-To create a Variables object, call the Variables() function:
-
-.TP
-.RI Variables([ files "], [" args ])
-This creates a Variables object that will read construction variables from
-the file or list of filenames specified in
-.IR files .
-If no files are specified,
-or the
-.I files
-argument is
-.BR None ,
-then no files will be read.
-The optional argument
-.I args
-is a dictionary of
-values that will override anything read from the specified files;
-it is primarily intended to be passed the
-.B ARGUMENTS
-dictionary that holds variables
-specified on the command line.
-Example:
-
-.ES
-vars = Variables('custom.py')
-vars = Variables('overrides.py', ARGUMENTS)
-vars = Variables(None, {FOO:'expansion', BAR:7})
-.EE
-
-Variables objects have the following methods:
-
-.TP
-.RI Add( key ", [" help ", " default ", " validator ", " converter ])
-This adds a customizable construction variable to the Variables object.
-.I key
-is the name of the variable.
-.I help
-is the help text for the variable.
-.I default
-is the default value of the variable;
-if the default value is
-.B None
-and there is no explicit value specified,
-the construction variable will
-.I not
-be added to the construction environment.
-.I validator
-is called to validate the value of the variable, and should take three
-arguments: key, value, and environment.
-The recommended way to handle an invalid value is
-to raise an exception (see example below).
-.I converter
-is called to convert the value before putting it in the environment, and
-should take either a value, or the value and environment, as parameters.
-The
-.I converter
-must return a value,
-which will be converted into a string
-before being validated by the
-.I validator
-(if any)
-and then added to the environment.
-
-Examples:
-
-.ES
-vars.Add('CC', 'The C compiler')
-
-def validate_color(key, val, env):
-    if not val in ['red', 'blue', 'yellow']:
-        raise Exception("Invalid color value '%s'" % val)
-vars.Add('COLOR', validator=valid_color)
-.EE
-
-.TP
-.RI AddVariables( list )
-A wrapper script that adds
-multiple customizable construction variables
-to a Variables object.
-.I list
-is a list of tuple or list objects
-that contain the arguments
-for an individual call to the
-.B Add
-method.
-
-.ES
-opt.AddVariables(
-       ('debug', '', 0),
-       ('CC', 'The C compiler'),
-       ('VALIDATE', 'An option for testing validation',
-        'notset', validator, None),
-    )
-.EE
-
-.TP
-.RI Update( env ", [" args ])
-This updates a construction environment
-.I env
-with the customized construction variables.
-Any specified variables that are
-.I not
-configured for the Variables object
-will be saved and may be
-retrieved with the
-.BR UnknownVariables ()
-method, below.
-
-Normally this method is not called directly,
-but is called indirectly by passing the Variables object to
-the Environment() function:
-
-.ES
-env = Environment(variables=vars)
-.EE
-
-.IP
-The text file(s) that were specified
-when the Variables object was created
-are executed as Python scripts,
-and the values of (global) Python variables set in the file
-are added to the construction environment.
-
-Example:
-
-.ES
-CC = 'my_cc'
-.EE
-
-.TP
-.RI UnknownVariables( )
-Returns a dictionary containing any
-variables that were specified
-either in the files or the dictionary
-with which the Variables object was initialized,
-but for which the Variables object was
-not configured.
-
-.ES
-env = Environment(variables=vars)
-for key, value in vars.UnknownVariables():
-    print "unknown variable:  %s=%s" % (key, value)
-.EE
-
-.TP
-.RI Save( filename ", " env )
-This saves the currently set variables into a script file named
-.I filename
-that can be used on the next invocation to automatically load the current
-settings.  This method combined with the Variables method can be used to
-support caching of variables between runs.
-
-.ES
-env = Environment()
-vars = Variables(['variables.cache', 'custom.py'])
-vars.Add(...)
-vars.Update(env)
-vars.Save('variables.cache', env)
-.EE
-
-.TP
-.RI GenerateHelpText( env ", [" sort ])
-This generates help text documenting the customizable construction
-variables suitable to passing in to the Help() function.
-.I env
-is the construction environment that will be used to get the actual values
-of customizable variables. Calling with
-an optional
-.I sort
-function
-will cause the output to be sorted
-by the specified argument.
-The specific
-.I sort
-function
-should take two arguments
-and return
--1, 0 or 1
-(like the standard Python
-.I cmp
-function).
-
-.ES
-Help(vars.GenerateHelpText(env))
-Help(vars.GenerateHelpText(env, sort=cmp))
-.EE
-
-.TP
-.RI FormatVariableHelpText( env ", " opt ", " help ", " default ", " actual )
-This method returns a formatted string
-containing the printable help text
-for one option.
-It is normally not called directly,
-but is called by the
-.IR GenerateHelpText ()
-method to create the returned help text.
-It may be overridden with your own
-function that takes the arguments specified above
-and returns a string of help text formatted to your liking.
-Note that the
-.IR GenerateHelpText ()
-will not put any blank lines or extra
-characters in between the entries,
-so you must add those characters to the returned
-string if you want the entries separated.
-
-.ES
-def my_format(env, opt, help, default, actual):
-    fmt = "\n%s: default=%s actual=%s (%s)\n"
-    return fmt % (opt, default. actual, help)
-vars.FormatVariableHelpText = my_format
-.EE
-
-To make it more convenient to work with customizable Variables,
-.B scons
-provides a number of functions
-that make it easy to set up
-various types of Variables:
-
-.TP
-.RI BoolVariable( key ", " help ", " default )
-Return a tuple of arguments
-to set up a Boolean option.
-The option will use
-the specified name
-.IR key ,
-have a default value of
-.IR default ,
-and display the specified
-.I help
-text.
-The option will interpret the values
-.BR y ,
-.BR yes ,
-.BR t ,
-.BR true ,
-.BR 1 ,
-.B on
-and
-.B all
-as true,
-and the values
-.BR n ,
-.BR no ,
-.BR f ,
-.BR false ,
-.BR 0 ,
-.B off
-and
-.B none
-as false.
-
-.TP
-.RI EnumVariable( key ", " help ", " default ", " allowed_values ", [" map ", " ignorecase ])
-Return a tuple of arguments
-to set up an option
-whose value may be one
-of a specified list of legal enumerated values.
-The option will use
-the specified name
-.IR key ,
-have a default value of
-.IR default ,
-and display the specified
-.I help
-text.
-The option will only support those
-values in the
-.I allowed_values
-list.
-The optional
-.I map
-argument is a dictionary
-that can be used to convert
-input values into specific legal values
-in the
-.I allowed_values
-list.
-If the value of
-.I ignore_case
-is
-.B 0
-(the default),
-then the values are case-sensitive.
-If the value of
-.I ignore_case
-is
-.BR 1 ,
-then values will be matched
-case-insensitive.
-If the value of
-.I ignore_case
-is
-.BR 1 ,
-then values will be matched
-case-insensitive,
-and all input values will be
-converted to lower case.
-
-.TP
-.RI ListVariable( key ", " help ", " default ", " names ", [", map ])
-Return a tuple of arguments
-to set up an option
-whose value may be one or more
-of a specified list of legal enumerated values.
-The option will use
-the specified name
-.IR key ,
-have a default value of
-.IR default ,
-and display the specified
-.I help
-text.
-The option will only support the values
-.BR all ,
-.BR none ,
-or the values in the
-.I names
-list.
-More than one value may be specified,
-with all values separated by commas.
-The default may be a string of
-comma-separated default values,
-or a list of the default values.
-The optional
-.I map
-argument is a dictionary
-that can be used to convert
-input values into specific legal values
-in the
-.I names
-list.
-
-.TP
-.RI PackageVariable( key ", " help ", " default )
-Return a tuple of arguments
-to set up an option
-whose value is a path name
-of a package that may be
-enabled, disabled or
-given an explicit path name.
-The option will use
-the specified name
-.IR key ,
-have a default value of
-.IR default ,
-and display the specified
-.I help
-text.
-The option will support the values
-.BR yes ,
-.BR true ,
-.BR on ,
-.BR enable
-or
-.BR search ,
-in which case the specified
-.I default
-will be used,
-or the option may be set to an
-arbitrary string
-(typically the path name to a package
-that is being enabled).
-The option will also support the values
-.BR no ,
-.BR false ,
-.BR off
-or
-.BR disable
-to disable use of the specified option.
-
-.TP
-.RI PathVariable( key ", " help ", " default ", [" validator ])
-Return a tuple of arguments
-to set up an option
-whose value is expected to be a path name.
-The option will use
-the specified name
-.IR key ,
-have a default value of
-.IR default ,
-and display the specified
-.I help
-text.
-An additional
-.I validator
-may be specified
-that will be called to
-verify that the specified path
-is acceptable.
-SCons supplies the
-following ready-made validators:
-.BR PathVariable.PathExists
-(the default),
-which verifies that the specified path exists;
-.BR PathVariable.PathIsFile ,
-which verifies that the specified path is an existing file;
-.BR PathVariable.PathIsDir ,
-which verifies that the specified path is an existing directory;
-.BR PathVariable.PathIsDirCreate ,
-which verifies that the specified path is a directory
-and will create the specified directory if the path does not exist;
-and
-.BR PathVariable.PathAccept ,
-which simply accepts the specific path name argument without validation,
-and which is suitable if you want your users
-to be able to specify a directory path that will be
-created as part of the build process, for example.
-You may supply your own
-.I validator
-function,
-which must take three arguments
-.RI ( key ,
-the name of the variable to be set;
-.IR val ,
-the specified value being checked;
-and
-.IR env ,
-the construction environment)
-and should raise an exception
-if the specified value is not acceptable.
-
-.RE
-These functions make it
-convenient to create a number
-of variables with consistent behavior
-in a single call to the
-.B AddVariables
-method:
-
-.ES
-vars.AddVariables(
-    BoolVariable('warnings', 'compilation with -Wall and similiar', 1),
-    EnumVariable('debug', 'debug output and symbols', 'no'
-               allowed_values=('yes', 'no', 'full'),
-               map={}, ignorecase=0),  # case sensitive
-    ListVariable('shared',
-               'libraries to build as shared libraries',
-               'all',
-               names = list_of_libs),
-    PackageVariable('x11',
-                  'use X11 installed here (yes = search some places)',
-                  'yes'),
-    PathVariable('qtdir', 'where the root of Qt is installed', qtdir),
-    PathVariable('foopath', 'where the foo library is installed', foopath,
-               PathVariable.PathIsDir),
-
-)
-.EE
-
-.SS File and Directory Nodes
-
-The
-.IR File ()
-and
-.IR Dir ()
-functions return
-.I File
-and
-.I Dir
-Nodes, respectively.
-python objects, respectively.
-Those objects have several user-visible attributes
-and methods that are often useful:
-
-.IP path
-The build path
-of the given
-file or directory.
-This path is relative to the top-level directory
-(where the
-.B SConstruct
-file is found).
-The build path is the same as the source path if
-.I variant_dir
-is not being used.
-
-.IP abspath
-The absolute build path of the given file or directory.
-
-.IP srcnode()
-The
-.IR srcnode ()
-method
-returns another
-.I File
-or
-.I Dir
-object representing the
-.I source
-path of the given
-.I File
-or
-.IR Dir .
-The
-
-.ES
-# Get the current build dir's path, relative to top.
-Dir('.').path
-# Current dir's absolute path
-Dir('.').abspath
-# Next line is always '.', because it is the top dir's path relative to itself.
-Dir('#.').path
-File('foo.c').srcnode().path   # source path of the given source file.
-
-# Builders also return File objects:
-foo = env.Program('foo.c')
-print "foo will be built in %s"%foo.path
-.EE
-
-A
-.I Dir
-Node or
-.I File
-Node can also be used to create
-file and subdirectory Nodes relative to the generating Node.
-A
-.I Dir
-Node will place the new Nodes within the directory it represents.
-A
-.I File
-node will place the new Nodes within its parent directory
-(that is, "beside" the file in question).
-If
-.I d
-is a
-.I Dir
-(directory) Node and
-.I f
-is a
-.I File
-(file) Node,
-then these methods are available:
-
-.TP
-.IR d .Dir( name )
-Returns a directory Node for a subdirectory of
-.I d
-named
-.IR name .
-
-.TP
-.IR d .File( name )
-Returns a file Node for a file within
-.I d
-named
-.IR name .
-
-.TP
-.IR d .Entry( name )
-Returns an unresolved Node within
-.I d
-named
-.IR name .
-
-.TP
-.IR f .Dir( name )
-Returns a directory named
-.I name
-within the parent directory of
-.IR f .
-
-.TP
-.IR f .File( name )
-Returns a file named
-.I name
-within the parent directory of
-.IR f .
-
-.TP
-.IR f .Entry( name )
-Returns an unresolved Node named
-.I name
-within the parent directory of
-.IR f .
-
-.RE
-For example:
-
-.ES
-# Get a Node for a file within a directory
-incl = Dir('include')
-f = incl.File('header.h')
-
-# Get a Node for a subdirectory within a directory
-dist = Dir('project-3.2.1)
-src = dist.Dir('src')
-
-# Get a Node for a file in the same directory
-cfile = File('sample.c')
-hfile = cfile.File('sample.h')
-
-# Combined example
-docs = Dir('docs')
-html = docs.Dir('html')
-index = html.File('index.html')
-css = index.File('app.css')
-.EE
-
-.SH EXTENDING SCONS
-.SS Builder Objects
-.B scons
-can be extended to build different types of targets
-by adding new Builder objects
-to a construction environment.
-.IR "In general" ,
-you should only need to add a new Builder object
-when you want to build a new type of file or other external target.
-If you just want to invoke a different compiler or other tool
-to build a Program, Object, Library, or any other
-type of output file for which
-.B scons
-already has an existing Builder,
-it is generally much easier to
-use those existing Builders
-in a construction environment
-that sets the appropriate construction variables
-(CC, LINK, etc.).
-
-Builder objects are created
-using the
-.B Builder
-function.
-The
-.B Builder
-function accepts the following arguments:
-
-.IP action
-The command line string used to build the target from the source.
-.B action
-can also be:
-a list of strings representing the command
-to be executed and its arguments
-(suitable for enclosing white space in an argument),
-a dictionary
-mapping source file name suffixes to
-any combination of command line strings
-(if the builder should accept multiple source file extensions),
-a Python function;
-an Action object
-(see the next section);
-or a list of any of the above.
-
-An action function
-takes three arguments:
-.I source
-- a list of source nodes,
-.I target
-- a list of target nodes,
-.I env
-- the construction environment.
-
-.IP prefix
-The prefix that will be prepended to the target file name.
-This may be specified as a:
-
-.RS 10
-.HP 6
-*
-.IR string ,
-
-.HP 6
-*
-.I callable object
-- a function or other callable that takes
-two arguments (a construction environment and a list of sources)
-and returns a prefix,
-
-.HP 6
-*
-.I dictionary
-- specifies a mapping from a specific source suffix (of the first
-source specified) to a corresponding target prefix.  Both the source
-suffix and target prefix specifications may use environment variable
-substitution, and the target prefix (the 'value' entries in the
-dictionary) may also be a callable object.  The default target prefix
-may be indicated by a dictionary entry with a key value of None.
-.RE
-.P
-
-.ES
-b = Builder("build_it < $SOURCE > $TARGET",
-            prefix = "file-")
-
-def gen_prefix(env, sources):
-    return "file-" + env['PLATFORM'] + '-'
-b = Builder("build_it < $SOURCE > $TARGET",
-            prefix = gen_prefix)
-
-b = Builder("build_it < $SOURCE > $TARGET",
-            suffix = { None: "file-",
-                       "$SRC_SFX_A": gen_prefix })
-.EE
-
-.IP suffix
-The suffix that will be appended to the target file name.
-This may be specified in the same manner as the prefix above.
-If the suffix is a string, then
-.B scons
-will append a '.' to the beginning of the suffix if it's not already
-there.  The string returned by callable object (or obtained from the
-dictionary) is untouched and must append its own '.'  to the beginning
-if one is desired.
-
-.ES
-b = Builder("build_it < $SOURCE > $TARGET"
-            suffix = "-file")
-
-def gen_suffix(env, sources):
-    return "." + env['PLATFORM'] + "-file"
-b = Builder("build_it < $SOURCE > $TARGET",
-            suffix = gen_suffix)
-
-b = Builder("build_it < $SOURCE > $TARGET",
-            suffix = { None: ".sfx1",
-                       "$SRC_SFX_A": gen_suffix })
-.EE
-
-.IP ensure_suffix
-When set to any true value, causes
-.B scons
-to add the target suffix specified by the
-.I suffix
-keyword to any target strings
-that have a different suffix.
-(The default behavior is to leave untouched
-any target file name that looks like it already has any suffix.)
-
-.ES
-b1 = Builder("build_it < $SOURCE > $TARGET"
-             suffix = ".out")
-b2 = Builder("build_it < $SOURCE > $TARGET"
-             suffix = ".out",
-             ensure_suffix)
-env = Environment()
-env['BUILDERS']['B1'] = b1
-env['BUILDERS']['B2'] = b2
-
-# Builds "foo.txt" because ensure_suffix is not set.
-env.B1('foo.txt', 'foo.in')
-
-# Builds "bar.txt.out" because ensure_suffix is set.
-env.B2('bar.txt', 'bar.in')
-.EE
-
-.IP src_suffix
-The expected source file name suffix.  This may be a string or a list
-of strings.
-
-.IP target_scanner
-A Scanner object that
-will be invoked to find
-implicit dependencies for this target file.
-This keyword argument should be used
-for Scanner objects that find
-implicit dependencies
-based only on the target file
-and the construction environment,
-.I not
-for implicit dependencies based on source files.
-(See the section "Scanner Objects" below,
-for information about creating Scanner objects.)
-
-.IP source_scanner
-A Scanner object that
-will be invoked to
-find implicit dependencies in
-any source files
-used to build this target file.
-This is where you would
-specify a scanner to
-find things like
-.B #include
-lines in source files.
-The pre-built
-.B DirScanner
-Scanner object may be used to
-indicate that this Builder
-should scan directory trees
-for on-disk changes to files
-that
-.B scons
-does not know about from other Builder or function calls.
-(See the section "Scanner Objects" below,
-for information about creating your own Scanner objects.)
-
-.IP target_factory
-A factory function that the Builder will use
-to turn any targets specified as strings into SCons Nodes.
-By default,
-SCons assumes that all targets are files.
-Other useful target_factory
-values include
-.BR Dir ,
-for when a Builder creates a directory target,
-and
-.BR Entry ,
-for when a Builder can create either a file
-or directory target.
-
-Example:
-
-.ES
-MakeDirectoryBuilder = Builder(action=my_mkdir, target_factory=Dir)
-env = Environment()
-env.Append(BUILDERS = {'MakeDirectory':MakeDirectoryBuilder})
-env.MakeDirectory('new_directory', [])
-.EE
-
-.IP
-Note that the call to the MakeDirectory Builder
-needs to specify an empty source list
-to make the string represent the builder's target;
-without that, it would assume the argument is the source,
-and would try to deduce the target name from it,
-which in the absence of an automatically-added prefix or suffix
-would lead to a matching target and source name
-and a circular dependency.
-
-.IP source_factory
-A factory function that the Builder will use
-to turn any sources specified as strings into SCons Nodes.
-By default,
-SCons assumes that all source are files.
-Other useful source_factory
-values include
-.BR Dir ,
-for when a Builder uses a directory as a source,
-and
-.BR Entry ,
-for when a Builder can use files
-or directories (or both) as sources.
-
-Example:
-
-.ES
-CollectBuilder = Builder(action=my_mkdir, source_factory=Entry)
-env = Environment()
-env.Append(BUILDERS = {'Collect':CollectBuilder})
-env.Collect('archive', ['directory_name', 'file_name'])
-.EE
-
-.IP emitter
-A function or list of functions to manipulate the target and source
-lists before dependencies are established
-and the target(s) are actually built.
-.B emitter
-can also be a string containing a construction variable to expand
-to an emitter function or list of functions,
-or a dictionary mapping source file suffixes
-to emitter functions.
-(Only the suffix of the first source file
-is used to select the actual emitter function
-from an emitter dictionary.)
-
-An emitter function
-takes three arguments:
-.I source
-- a list of source nodes,
-.I target
-- a list of target nodes,
-.I env
-- the construction environment.
-An emitter must return a tuple containing two lists,
-the list of targets to be built by this builder,
-and the list of sources for this builder.
-
-Example:
-
-.ES
-def e(target, source, env):
-    return (target + ['foo.foo'], source + ['foo.src'])
-
-# Simple association of an emitter function with a Builder.
-b = Builder("my_build < $TARGET > $SOURCE",
-            emitter = e)
-
-def e2(target, source, env):
-    return (target + ['bar.foo'], source + ['bar.src'])
-
-# Simple association of a list of emitter functions with a Builder.
-b = Builder("my_build < $TARGET > $SOURCE",
-            emitter = [e, e2])
-
-# Calling an emitter function through a construction variable.
-env = Environment(MY_EMITTER = e)
-b = Builder("my_build < $TARGET > $SOURCE",
-            emitter = '$MY_EMITTER')
-
-# Calling a list of emitter functions through a construction variable.
-env = Environment(EMITTER_LIST = [e, e2])
-b = Builder("my_build < $TARGET > $SOURCE",
-            emitter = '$EMITTER_LIST')
-
-# Associating multiple emitters with different file
-# suffixes using a dictionary.
-def e_suf1(target, source, env):
-    return (target + ['another_target_file'], source)
-def e_suf2(target, source, env):
-    return (target, source + ['another_source_file'])
-b = Builder("my_build < $TARGET > $SOURCE",
-            emitter = {'.suf1' : e_suf1,
-                       '.suf2' : e_suf2})
-.EE
-
-.IP multi
-Specifies whether this builder is allowed to be called multiple times for
-the same target file(s). The default is 0, which means the builder
-can not be called multiple times for the same target file(s). Calling a
-builder multiple times for the same target simply adds additional source
-files to the target; it is not allowed to change the environment associated
-with the target, specify addition environment overrides, or associate a different
-builder with the target.
-
-.IP env
-A construction environment that can be used
-to fetch source code using this Builder.
-(Note that this environment is
-.I not
-used for normal builds of normal target files,
-which use the environment that was
-used to call the Builder for the target file.)
-
-.IP generator
-A function that returns a list of actions that will be executed to build
-the target(s) from the source(s).
-The returned action(s) may be
-an Action object, or anything that
-can be converted into an Action object
-(see the next section).
-
-The generator function
-takes four arguments:
-.I source
-- a list of source nodes,
-.I target
-- a list of target nodes,
-.I env
-- the construction environment,
-.I for_signature
-- a Boolean value that specifies
-whether the generator is being called
-for generating a build signature
-(as opposed to actually executing the command).
-Example:
-
-.ES
-def g(source, target, env, for_signature):
-    return [["gcc", "-c", "-o"] + target + source]
-
-b = Builder(generator=g)
-.EE
-
-.IP
-The
-.I generator
-and
-.I action
-arguments must not both be used for the same Builder.
-
-.IP src_builder
-Specifies a builder to use when a source file name suffix does not match
-any of the suffixes of the builder. Using this argument produces a
-multi-stage builder.
-
-.IP single_source
-Specifies that this builder expects exactly one source file per call. Giving
-more than one source file without target files results in implicitely calling
-the builder multiple times (once for each source given). Giving multiple
-source files together with target files results in a UserError exception.
-
-.RE
-.IP
-The
-.I generator
-and
-.I action
-arguments must not both be used for the same Builder.
-
-.IP source_ext_match
-When the specified
-.I action
-argument is a dictionary,
-the default behavior when a builder is passed
-multiple source files is to make sure that the
-extensions of all the source files match.
-If it is legal for this builder to be
-called with a list of source files with different extensions,
-this check can be suppressed by setting
-.B source_ext_match
-to
-.B None
-or some other non-true value.
-When
-.B source_ext_match
-is disable,
-.B scons
-will use the suffix of the first specified
-source file to select the appropriate action from the
-.I action
-dictionary.
-
-In the following example,
-the setting of
-.B source_ext_match
-prevents
-.B scons
-from exiting with an error
-due to the mismatched suffixes of
-.B foo.in
-and
-.BR foo.extra .
-
-.ES
-b = Builder(action={'.in' : 'build $SOURCES > $TARGET'},
-            source_ext_match = None)
-
-env = Environment(BUILDERS = {'MyBuild':b})
-env.MyBuild('foo.out', ['foo.in', 'foo.extra'])
-.EE
-
-.IP env
-A construction environment that can be used
-to fetch source code using this Builder.
-(Note that this environment is
-.I not
-used for normal builds of normal target files,
-which use the environment that was
-used to call the Builder for the target file.)
-
-.ES
-b = Builder(action="build < $SOURCE > $TARGET")
-env = Environment(BUILDERS = {'MyBuild' : b})
-env.MyBuild('foo.out', 'foo.in', my_arg = 'xyzzy')
-.EE
-
-.IP chdir
-A directory from which scons
-will execute the
-action(s) specified
-for this Builder.
-If the
-.B chdir
-argument is
-a string or a directory Node,
-scons will change to the specified directory.
-If the
-.B chdir
-is not a string or Node
-and is non-zero,
-then scons will change to the
-target file's directory.
-
-Note that scons will
-.I not
-automatically modify
-its expansion of
-construction variables like
-.B $TARGET
-and
-.B $SOURCE
-when using the chdir
-keyword argument--that is,
-the expanded file names
-will still be relative to
-the top-level SConstruct directory,
-and consequently incorrect
-relative to the chdir directory.
-Builders created using chdir keyword argument,
-will need to use construction variable
-expansions like
-.B ${TARGET.file}
-and
-.B ${SOURCE.file}
-to use just the filename portion of the
-targets and source.
-
-.ES
-b = Builder(action="build < ${SOURCE.file} > ${TARGET.file}",
-            chdir=1)
-env = Environment(BUILDERS = {'MyBuild' : b})
-env.MyBuild('sub/dir/foo.out', 'sub/dir/foo.in')
-.EE
-
-.B WARNING:
-Python only keeps one current directory
-location for all of the threads.
-This means that use of the
-.B chdir
-argument
-will
-.I not
-work with the SCons
-.B -j
-option,
-because individual worker threads spawned
-by SCons interfere with each other
-when they start changing directory.
-
-.RE
-Any additional keyword arguments supplied
-when a Builder object is created
-(that is, when the Builder() function is called)
-will be set in the executing construction
-environment when the Builder object is called.
-The canonical example here would be
-to set a construction variable to
-the repository of a source code system.
-
-Any additional keyword arguments supplied
-when a Builder
-.I object
-is called
-will only be associated with the target
-created by that particular Builder call
-(and any other files built as a
-result of the call).
-
-These extra keyword arguments are passed to the
-following functions:
-command generator functions,
-function Actions,
-and emitter functions.
-
-.SS Action Objects
-
-The
-.BR Builder ()
-function will turn its
-.B action
-keyword argument into an appropriate
-internal Action object.
-You can also explicity create Action objects
-using the
-.BR Action ()
-global function,
-which can then be passed to the
-.BR Builder ()
-function.
-This can be used to configure
-an Action object more flexibly,
-or it may simply be more efficient
-than letting each separate Builder object
-create a separate Action
-when multiple
-Builder objects need to do the same thing.
-
-The
-.BR Action ()
-global function
-returns an appropriate object for the action
-represented by the type of the first argument:
-
-.IP Action
-If the first argument is already an Action object,
-the object is simply returned.
-
-.IP String
-If the first argument is a string,
-a command-line Action is returned.
-Note that the command-line string
-may be preceded by an
-.B @
-(at-sign)
-to suppress printing of the specified command line,
-or by a
-.B \-
-(hyphen)
-to ignore the exit status from the specified command:
-
-.ES
-Action('$CC -c -o $TARGET $SOURCES')
-
-# Doesn't print the line being executed.
-Action('@build $TARGET $SOURCES')
-
-# Ignores return value
-Action('-build $TARGET $SOURCES')
-.EE
-.\" XXX From Gary Ruben, 23 April 2002:
-.\" What would be useful is a discussion of how you execute command
-.\" shell commands ie. what is the process used to spawn the shell, pass
-.\" environment variables to it etc., whether there is one shell per
-.\" environment or one per command etc.  It might help to look at the Gnu
-.\" make documentation to see what they think is important to discuss about
-.\" a build system. I'm sure you can do a better job of organising the
-.\" documentation than they have :-)
-
-.IP List
-If the first argument is a list,
-then a list of Action objects is returned.
-An Action object is created as necessary
-for each element in the list.
-If an element
-.I within
-the list is itself a list,
-the internal list is the
-command and arguments to be executed via
-the command line.
-This allows white space to be enclosed
-in an argument by defining
-a command in a list within a list:
-
-.ES
-Action([['cc', '-c', '-DWHITE SPACE', '-o', '$TARGET', '$SOURCES']])
-.EE
-
-.IP Function
-If the first argument is a Python function,
-a function Action is returned.
-The Python function must take three keyword arguments,
-.B target
-(a Node object representing the target file),
-.B source
-(a Node object representing the source file)
-and
-.B env
-(the construction environment
-used for building the target file).
-The
-.B target
-and
-.B source
-arguments may be lists of Node objects if there is
-more than one target file or source file.
-The actual target and source file name(s) may
-be retrieved from their Node objects
-via the built-in Python str() function:
-
-.ES
-target_file_name = str(target)
-source_file_names = map(lambda x: str(x), source)
-.EE
-.IP
-The function should return
-.B 0
-or
-.B None
-to indicate a successful build of the target file(s).
-The function may raise an exception
-or return a non-zero exit status
-to indicate an unsuccessful build.
-
-.ES
-def build_it(target = None, source = None, env = None):
-    # build the target from the source
-    return 0
-
-a = Action(build_it)
-.EE
-
-If the action argument is not one of the above,
-None is returned.
-.PP
-
-The second argument is optional and is used to define the output
-which is printed when the Action is actually performed.
-In the absence of this parameter,
-or if it's an empty string,
-a default output depending on the type of the action is used.
-For example, a command-line action will print the executed command.
-The argument must be either a Python function or a string.
-
-In the first case,
-it's a function that returns a string to be printed
-to describe the action being executed.
-The function may also be specified by the
-.IR strfunction =
-keyword argument.
-Like a function to build a file,
-this function must take three keyword arguments:
-.B target
-(a Node object representing the target file),
-.B source
-(a Node object representing the source file)
-and
-.BR env
-(a construction environment).
-The
-.B target
-and
-.B source
-arguments may be lists of Node objects if there is
-more than one target file or source file.
-
-In the second case, you provide the string itself.
-The string may also be specified by the
-.IR cmdstr =
-keyword argument.
-The string typically contains variables, notably
-$TARGET(S) and $SOURCE(S), or consists of just a single
-variable, which is optionally defined somewhere else.
-SCons itself heavily uses the latter variant.
-
-Examples:
-
-.ES
-def build_it(target, source, env):
-    # build the target from the source
-    return 0
-
-def string_it(target, source, env):
-    return "building '%s' from '%s'" % (target[0], source[0])
-
-# Use a positional argument.
-f = Action(build_it, string_it)
-s = Action(build_it, "building '$TARGET' from '$SOURCE'")
-
-# Alternatively, use a keyword argument.
-f = Action(build_it, strfunction=string_it)
-s = Action(build_it, cmdstr="building '$TARGET' from '$SOURCE'")
-
-# You can provide a configurable variable.
-l = Action(build_it, '$STRINGIT')
-.EE
-
-The third and succeeding arguments, if present,
-may either be a construction variable or a list of construction variables
-whose values will be included in the signature of the Action
-when deciding whether a target should be rebuilt because the action changed.
-The variables may also be specified by a
-.IR varlist =
-keyword parameter;
-if both are present, they are combined.
-This is necessary whenever you want a target to be rebuilt
-when a specific construction variable changes.
-This is not often needed for a string action,
-as the expanded variables will normally be part of the command line,
-but may be needed if a Python function action uses
-the value of a construction variable when generating the command line.
-
-.ES
-def build_it(target, source, env):
-    # build the target from the 'XXX' construction variable
-    open(target[0], 'w').write(env['XXX'])
-    return 0
-
-# Use positional arguments.
-a = Action(build_it, '$STRINGIT', ['XXX'])
-
-# Alternatively, use a keyword argument.
-a = Action(build_it, varlist=['XXX'])
-.EE
-
-The
-.BR Action ()
-global function
-can be passed the following
-optional keyword arguments
-to modify the Action object's behavior:
-
-.IP
-.B chdir
-The
-.B chdir
-keyword argument specifies that
-scons will execute the action
-after changing to the specified directory.
-If the
-.B chdir
-argument is
-a string or a directory Node,
-scons will change to the specified directory.
-If the
-.B chdir
-argument
-is not a string or Node
-and is non-zero,
-then scons will change to the
-target file's directory.
-
-Note that scons will
-.I not
-automatically modify
-its expansion of
-construction variables like
-.B $TARGET
-and
-.B $SOURCE
-when using the chdir
-keyword argument--that is,
-the expanded file names
-will still be relative to
-the top-level SConstruct directory,
-and consequently incorrect
-relative to the chdir directory.
-Builders created using chdir keyword argument,
-will need to use construction variable
-expansions like
-.B ${TARGET.file}
-and
-.B ${SOURCE.file}
-to use just the filename portion of the
-targets and source.
-
-.ES
-a = Action("build < ${SOURCE.file} > ${TARGET.file}",
-           chdir=1)
-.EE
-
-.IP
-.B exitstatfunc
-The
-.BR Action ()
-global function
-also takes an
-.B exitstatfunc
-keyword argument
-which specifies a function
-that is passed the exit status
-(or return value)
-from the specified action
-and can return an arbitrary
-or modified value.
-This can be used, for example,
-to specify that an Action object's
-return value should be ignored
-under special conditions
-and SCons should, therefore,
-consider that the action always suceeds:
-
-.ES
-def always_succeed(s):
-    # Always return 0, which indicates success.
-    return 0
-a = Action("build < ${SOURCE.file} > ${TARGET.file}",
-           exitstatfunc=always_succeed)
-.EE
-
-.IP
-.B batch_key
-The
-.B batch_key
-keyword argument can be used
-to specify that the Action can create multiple target files
-by processing multiple independent source files simultaneously.
-(The canonical example is "batch compilation"
-of multiple object files
-by passing multiple source files
-to a single invocation of a compiler
-such as Microsoft's Visual C / C++ compiler.)
-If the
-.B batch_key
-argument is any non-False, non-callable Python value,
-the configured Action object will cause
-.B scons
-to collect all targets built with the Action object
-and configured with the same construction environment
-into single invocations of the Action object's
-command line or function.
-Command lines will typically want to use the
-.BR CHANGED_SOURCES
-construction variable
-(and possibly
-.BR CHANGED_TARGETS
-as well)
-to only pass to the command line those sources that
-have actually changed since their targets were built.
-
-Example:
-
-.ES
-a = Action('build $CHANGED_SOURCES', batch_key=True)
-.EE
-
-The
-.B batch_key
-argument may also be
-a callable function
-that returns a key that
-will be used to identify different
-"batches" of target files to be collected
-for batch building.
-A
-.B batch_key
-function must take the following arguments:
-
-.IP action
-The action object.
-
-.IP env
-The construction environment
-configured for the target.
-
-.IP target
-The list of targets for a particular configured action.
-
-.IP source
-The list of source for a particular configured action.
-
-The returned key should typically
-be a tuple of values derived from the arguments,
-using any appropriate logic to decide
-how multiple invocations should be batched.
-For example, a
-.B batch_key
-function may decide to return
-the value of a specific construction
-variable from the
-.B env
-argument
-which will cause
-.B scons
-to batch-build targets
-with matching values of that variable,
-or perhaps return the
-.BR id ()
-of the entire construction environment,
-in which case
-.B scons
-will batch-build
-all targets configured with the same construction environment.
-Returning
-.B None
-indicates that
-the particular target should
-.I not
-be part of any batched build,
-but instead will be built
-by a separate invocation of action's
-command or function.
-Example:
-
-.ES
-def batch_key(action, env, target, source):
-    tdir = target[0].dir
-    if tdir.name == 'special':
-        # Don't batch-build any target
-        # in the special/ subdirectory.
-        return None
-    return (id(action), id(env), tdir)
-a = Action('build $CHANGED_SOURCES', batch_key=batch_key)
-.EE
-
-.SS Miscellaneous Action Functions
-
-.B scons
-supplies a number of functions
-that arrange for various common
-file and directory manipulations
-to be performed.
-These are similar in concept to "tasks" in the
-Ant build tool,
-although the implementation is slightly different.
-These functions do not actually
-perform the specified action
-at the time the function is called,
-but instead return an Action object
-that can be executed at the
-appropriate time.
-(In Object-Oriented terminology,
-these are actually
-Action
-.I Factory
-functions
-that return Action objects.)
-
-In practice,
-there are two natural ways
-that these
-Action Functions
-are intended to be used.
-
-First,
-if you need
-to perform the action
-at the time the SConscript
-file is being read,
-you can use the
-.B Execute
-global function to do so:
-.ES
-Execute(Touch('file'))
-.EE
-
-Second,
-you can use these functions
-to supply Actions in a list
-for use by the
-.B Command
-method.
-This can allow you to
-perform more complicated
-sequences of file manipulation
-without relying
-on platform-specific
-external commands:
-that
-.ES
-env = Environment(TMPBUILD = '/tmp/builddir')
-env.Command('foo.out', 'foo.in',
-            [Mkdir('$TMPBUILD'),
-             Copy('$TMPBUILD', '${SOURCE.dir}'),
-             "cd $TMPBUILD && make",
-             Delete('$TMPBUILD')])
-.EE
-
-.TP
-.RI Chmod( dest ", " mode )
-Returns an Action object that
-changes the permissions on the specified
-.I dest
-file or directory to the specified
-.IR mode .
-Examples:
-
-.ES
-Execute(Chmod('file', 0755))
-
-env.Command('foo.out', 'foo.in',
-            [Copy('$TARGET', '$SOURCE'),
-             Chmod('$TARGET', 0755)])
-.EE
-
-.TP
-.RI Copy( dest ", " src )
-Returns an Action object
-that will copy the
-.I src
-source file or directory to the
-.I dest
-destination file or directory.
-Examples:
-
-.ES
-Execute(Copy('foo.output', 'foo.input'))
-
-env.Command('bar.out', 'bar.in',
-            Copy('$TARGET', '$SOURCE'))
-.EE
-
-.TP
-.RI Delete( entry ", [" must_exist ])
-Returns an Action that
-deletes the specified
-.IR entry ,
-which may be a file or a directory tree.
-If a directory is specified,
-the entire directory tree
-will be removed.
-If the
-.I must_exist
-flag is set,
-then a Python error will be thrown
-if the specified entry does not exist;
-the default is
-.BR must_exist=0 ,
-that is, the Action will silently do nothing
-if the entry does not exist.
-Examples:
-
-.ES
-Execute(Delete('/tmp/buildroot'))
-
-env.Command('foo.out', 'foo.in',
-            [Delete('${TARGET.dir}'),
-             MyBuildAction])
-
-Execute(Delete('file_that_must_exist', must_exist=1))
-.EE
-
-.TP
-.RI Mkdir( dir )
-Returns an Action
-that creates the specified
-directory
-.I dir .
-Examples:
-
-.ES
-Execute(Mkdir('/tmp/outputdir'))
-
-env.Command('foo.out', 'foo.in',
-            [Mkdir('/tmp/builddir'),
-             Copy('/tmp/builddir/foo.in', '$SOURCE'),
-             "cd /tmp/builddir && make",
-             Copy('$TARGET', '/tmp/builddir/foo.out')])
-.EE
-
-.TP
-.RI Move( dest ", " src )
-Returns an Action
-that moves the specified
-.I src
-file or directory to
-the specified
-.I dest
-file or directory.
-Examples:
-
-.ES
-Execute(Move('file.destination', 'file.source'))
-
-env.Command('output_file', 'input_file',
-            [MyBuildAction,
-             Move('$TARGET', 'file_created_by_MyBuildAction')])
-.EE
-
-.TP
-.RI Touch( file )
-Returns an Action
-that updates the modification time
-on the specified
-.IR file .
-Examples:
-
-.ES
-Execute(Touch('file_to_be_touched'))
-
-env.Command('marker', 'input_file',
-            [MyBuildAction,
-             Touch('$TARGET')])
-.EE
-
-.SS Variable Substitution
-
-Before executing a command,
-.B scons
-performs construction variable interpolation on the strings that make up
-the command line of builders.
-Variables are introduced by a
-.B $
-prefix.
-Besides construction variables, scons provides the following
-variables for each command execution:
-
-.IP CHANGED_SOURCES
-The file names of all sources of the build command
-that have changed since the target was last built.
-
-.IP CHANGED_TARGETS
-The file names of all targets that would be built
-from sources that have changed since the target was last built.
-
-.IP SOURCE
-The file name of the source of the build command,
-or the file name of the first source
-if multiple sources are being built.
-
-.IP SOURCES
-The file names of the sources of the build command.
-
-.IP TARGET
-The file name of the target being built,
-or the file name of the first target
-if multiple targets are being built.
-
-.IP TARGETS
-The file names of all targets being built.
-
-.IP UNCHANGED_SOURCES
-The file names of all sources of the build command
-that have
-.I not
-changed since the target was last built.
-
-.IP UNCHANGED_TARGETS
-The file names of all targets that would be built
-from sources that have
-.I not
-changed since the target was last built.
-
-(Note that the above variables are reserved
-and may not be set in a construction environment.)
-
-.LP
-For example, given the construction variable CC='cc', targets=['foo'], and
-sources=['foo.c', 'bar.c']:
-
-.ES
-action='$CC -c -o $TARGET $SOURCES'
-.EE
-
-would produce the command line:
-
-.ES
-cc -c -o foo foo.c bar.c
-.EE
-
-Variable names may be surrounded by curly braces ({})
-to separate the name from the trailing characters.
-Within the curly braces, a variable name may have
-a Python slice subscript appended to select one
-or more items from a list.
-In the previous example, the string:
-
-.ES
-${SOURCES[1]}
-.EE
-
-would produce:
-
-.ES
-bar.c
-.EE
-
-Additionally, a variable name may
-have the following special
-modifiers appended within the enclosing curly braces
-to modify the interpolated string:
-
-.IP base
-The base path of the file name,
-including the directory path
-but excluding any suffix.
-
-.IP dir
-The name of the directory in which the file exists.
-
-.IP file
-The file name,
-minus any directory portion.
-
-.IP filebase
-Just the basename of the file,
-minus any suffix
-and minus the directory.
-
-.IP suffix
-Just the file suffix.
-
-.IP abspath
-The absolute path name of the file.
-
-.IP posix
-The POSIX form of the path,
-with directories separated by
-.B /
-(forward slashes)
-not backslashes.
-This is sometimes necessary on Windows systems
-when a path references a file on other (POSIX) systems.
-
-.IP srcpath
-The directory and file name to the source file linked to this file through
-.BR VariantDir ().
-If this file isn't linked,
-it just returns the directory and filename unchanged.
-
-.IP srcdir
-The directory containing the source file linked to this file through
-.BR VariantDir ().
-If this file isn't linked,
-it just returns the directory part of the filename.
-
-.IP rsrcpath
-The directory and file name to the source file linked to this file through
-.BR VariantDir ().
-If the file does not exist locally but exists in a Repository,
-the path in the Repository is returned.
-If this file isn't linked, it just returns the
-directory and filename unchanged.
-
-.IP rsrcdir
-The Repository directory containing the source file linked to this file through
-.BR VariantDir ().
-If this file isn't linked,
-it just returns the directory part of the filename.
-
-.LP
-For example, the specified target will
-expand as follows for the corresponding modifiers:
-
-.ES
-$TARGET              => sub/dir/file.x
-${TARGET.base}       => sub/dir/file
-${TARGET.dir}        => sub/dir
-${TARGET.file}       => file.x
-${TARGET.filebase}   => file
-${TARGET.suffix}     => .x
-${TARGET.abspath}    => /top/dir/sub/dir/file.x
-
-SConscript('src/SConscript', variant_dir='sub/dir')
-$SOURCE              => sub/dir/file.x
-${SOURCE.srcpath}    => src/file.x
-${SOURCE.srcdir}     => src
-
-Repository('/usr/repository')
-$SOURCE              => sub/dir/file.x
-${SOURCE.rsrcpath}   => /usr/repository/src/file.x
-${SOURCE.rsrcdir}    => /usr/repository/src
-.EE
-
-Note that curly braces braces may also be used
-to enclose arbitrary Python code to be evaluated.
-(In fact, this is how the above modifiers are substituted,
-they are simply attributes of the Python objects
-that represent TARGET, SOURCES, etc.)
-See the section "Python Code Substitution" below,
-for more thorough examples of
-how this can be used.
-
-Lastly, a variable name
-may be a callable Python function
-associated with a
-construction variable in the environment.
-The function should
-take four arguments:
-.I target
-- a list of target nodes,
-.I source
-- a list of source nodes,
-.I env
-- the construction environment,
-.I for_signature
-- a Boolean value that specifies
-whether the function is being called
-for generating a build signature.
-SCons will insert whatever
-the called function returns
-into the expanded string:
-
-.ES
-def foo(target, source, env, for_signature):
-    return "bar"
-
-# Will expand $BAR to "bar baz"
-env=Environment(FOO=foo, BAR="$FOO baz")
-.EE
-
-You can use this feature to pass arguments to a
-Python function by creating a callable class
-that stores one or more arguments in an object,
-and then uses them when the
-.B __call__()
-method is called.
-Note that in this case,
-the entire variable expansion must
-be enclosed by curly braces
-so that the arguments will
-be associated with the
-instantiation of the class:
-
-.ES
-class foo(object):
-    def __init__(self, arg):
-        self.arg = arg
-
-    def __call__(self, target, source, env, for_signature):
-        return self.arg + " bar"
-
-# Will expand $BAR to "my argument bar baz"
-env=Environment(FOO=foo, BAR="${FOO('my argument')} baz")
-.EE
-
-.LP
-The special pseudo-variables
-.B "$("
-and
-.B "$)"
-may be used to surround parts of a command line
-that may change
-.I without
-causing a rebuild--that is,
-which are not included in the signature
-of target files built with this command.
-All text between
-.B "$("
-and
-.B "$)"
-will be removed from the command line
-before it is added to file signatures,
-and the
-.B "$("
-and
-.B "$)"
-will be removed before the command is executed.
-For example, the command line:
-
-.ES
-echo Last build occurred $( $TODAY $). > $TARGET
-.EE
-
-.LP
-would execute the command:
-
-.ES
-echo Last build occurred $TODAY. > $TARGET
-.EE
-
-.LP
-but the command signature added to any target files would be:
-
-.ES
-echo Last build occurred  . > $TARGET
-.EE
-
-.SS Python Code Substitution
-
-Any python code within
-.BR "${" - "}"
-pairs gets evaluated by python 'eval', with the python globals set to
-the current environment's set of construction variables.
-So in the following case:
-.ES
-env['COND'] = 0
-env.Command('foo.out', 'foo.in',
-   '''echo ${COND==1 and 'FOO' or 'BAR'} > $TARGET''')
-.EE
-the command executed will be either
-.ES
-echo FOO > foo.out
-.EE
-or
-.ES
-echo BAR > foo.out
-.EE
-according to the current value of env['COND'] when the command is
-executed.  The evaluation occurs when the target is being
-built, not when the SConscript is being read.  So if env['COND'] is changed
-later in the SConscript, the final value will be used.
-
-Here's a more interesting example.  Note that all of COND, FOO, and
-BAR are environment variables, and their values are substituted into
-the final command.  FOO is a list, so its elements are interpolated
-separated by spaces.
-
-.ES
-env=Environment()
-env['COND'] = 0
-env['FOO'] = ['foo1', 'foo2']
-env['BAR'] = 'barbar'
-env.Command('foo.out', 'foo.in',
-    'echo ${COND==1 and FOO or BAR} > $TARGET')
-
-# Will execute this:
-#  echo foo1 foo2 > foo.out
-.EE
-
-SCons uses the following rules when converting construction variables into
-command lines:
-
-.IP String
-When the value is a string it is interpreted as a space delimited list of
-command line arguments.
-
-.IP List
-When the value is a list it is interpreted as a list of command line
-arguments. Each element of the list is converted to a string.
-
-.IP Other
-Anything that is not a list or string is converted to a string and
-interpreted as a single command line argument.
-
-.IP Newline
-Newline characters (\\n) delimit lines. The newline parsing is done after
-all other parsing, so it is not possible for arguments (e.g. file names) to
-contain embedded newline characters. This limitation will likely go away in
-a future version of SCons.
-
-.SS Scanner Objects
-
-You can use the
-.B Scanner
-function to define
-objects to scan
-new file types for implicit dependencies.
-The
-.B Scanner
-function accepts the following arguments:
-
-.IP function
-This can be either:
-1) a Python function that will process
-the Node (file)
-and return a list of File Nodes
-representing the implicit
-dependencies (file names) found in the contents;
-or:
-2) a dictionary that maps keys
-(typically the file suffix, but see below for more discussion)
-to other Scanners that should be called.
-
-If the argument is actually a Python function,
-the function must take three or four arguments:
-
-    def scanner_function(node, env, path):
-
-    def scanner_function(node, env, path, arg=None):
-
-The
-.B node
-argument is the internal
-SCons node representing the file.
-Use
-.B str(node)
-to fetch the name of the file, and
-.B node.get_contents()
-to fetch contents of the file.
-Note that the file is
-.I not
-guaranteed to exist before the scanner is called,
-so the scanner function should check that
-if there's any chance that the scanned file
-might not exist
-(for example, if it's built from other files).
-
-The
-.B env
-argument is the construction environment for the scan.
-Fetch values from it using the
-.B env.Dictionary()
-method.
-
-The
-.B path
-argument is a tuple (or list)
-of directories that can be searched
-for files.
-This will usually be the tuple returned by the
-.B path_function
-argument (see below).
-
-The
-.B arg
-argument is the argument supplied
-when the scanner was created, if any.
-
-.IP name
-The name of the Scanner.
-This is mainly used
-to identify the Scanner internally.
-
-.IP argument
-An optional argument that, if specified,
-will be passed to the scanner function
-(described above)
-and the path function
-(specified below).
-
-.IP skeys
-An optional list that can be used to
-determine which scanner should be used for
-a given Node.
-In the usual case of scanning for file names,
-this argument will be a list of suffixes
-for the different file types that this
-Scanner knows how to scan.
-If the argument is a string,
-then it will be expanded
-into a list by the current environment.
-
-.IP path_function
-A Python function that takes four or five arguments:
-a construction environment,
-a Node for the directory containing
-the SConscript file in which
-the first target was defined,
-a list of target nodes,
-a list of source nodes,
-and an optional argument supplied
-when the scanner was created.
-The
-.B path_function
-returns a tuple of directories
-that can be searched for files to be returned
-by this Scanner object.
-(Note that the
-.BR FindPathDirs ()
-function can be used to return a ready-made
-.B path_function
-for a given construction variable name,
-instead of having to write your own function from scratch.)
-
-.IP node_class
-The class of Node that should be returned
-by this Scanner object.
-Any strings or other objects returned
-by the scanner function
-that are not of this class
-will be run through the
-.B node_factory
-function.
-
-.IP node_factory
-A Python function that will take a string
-or other object
-and turn it into the appropriate class of Node
-to be returned by this Scanner object.
-
-.IP scan_check
-An optional Python function that takes two arguments,
-a Node (file) and a construction environment,
-and returns whether the
-Node should, in fact,
-be scanned for dependencies.
-This check can be used to eliminate unnecessary
-calls to the scanner function when,
-for example, the underlying file
-represented by a Node does not yet exist.
-
-.IP recursive
-An optional flag that
-specifies whether this scanner should be re-invoked
-on the dependency files returned by the scanner.
-When this flag is not set,
-the Node subsystem will
-only invoke the scanner on the file being scanned,
-and not (for example) also on the files
-specified by the #include lines
-in the file being scanned.
-.I recursive
-may be a callable function,
-in which case it will be called with a list of
-Nodes found and
-should return a list of Nodes
-that should be scanned recursively;
-this can be used to select a specific subset of
-Nodes for additional scanning.
-
-.RE
-Note that
-.B scons
-has a global
-.B SourceFileScanner
-object that is used by
-the
-.BR Object (),
-.BR SharedObject (),
-and
-.BR StaticObject ()
-builders to decide
-which scanner should be used
-for different file extensions.
-You can using the
-.BR SourceFileScanner.add_scanner ()
-method to add your own Scanner object
-to the
-.B scons
-infrastructure
-that builds target programs or
-libraries from a list of
-source files of different types:
-
-.ES
-def xyz_scan(node, env, path):
-    contents = node.get_text_contents()
-    # Scan the contents and return the included files.
-
-XYZScanner = Scanner(xyz_scan)
-
-SourceFileScanner.add_scanner('.xyz', XYZScanner)
-
-env.Program('my_prog', ['file1.c', 'file2.f', 'file3.xyz'])
-.EE
-
-.SH SYSTEM-SPECIFIC BEHAVIOR
-SCons and its configuration files are very portable,
-due largely to its implementation in Python.
-There are, however, a few portability
-issues waiting to trap the unwary.
-.SS .C file suffix
-SCons handles the upper-case
-.B .C
-file suffix differently,
-depending on the capabilities of
-the underlying system.
-On a case-sensitive system
-such as Linux or UNIX,
-SCons treats a file with a
-.B .C
-suffix as a C++ source file.
-On a case-insensitive system
-such as Windows,
-SCons treats a file with a
-.B .C
-suffix as a C source file.
-.SS .F file suffix
-SCons handles the upper-case
-.B .F
-file suffix differently,
-depending on the capabilities of
-the underlying system.
-On a case-sensitive system
-such as Linux or UNIX,
-SCons treats a file with a
-.B .F
-suffix as a Fortran source file
-that is to be first run through
-the standard C preprocessor.
-On a case-insensitive system
-such as Windows,
-SCons treats a file with a
-.B .F
-suffix as a Fortran source file that should
-.I not
-be run through the C preprocessor.
-.SS Windows:  Cygwin Tools and Cygwin Python vs. Windows Pythons
-Cygwin supplies a set of tools and utilities
-that let users work on a
-Windows system using a more POSIX-like environment.
-The Cygwin tools, including Cygwin Python,
-do this, in part,
-by sharing an ability to interpret UNIX-like path names.
-For example, the Cygwin tools
-will internally translate a Cygwin path name
-like /cygdrive/c/mydir
-to an equivalent Windows pathname
-of C:/mydir (equivalent to C:\\mydir).
-
-Versions of Python
-that are built for native Windows execution,
-such as the python.org and ActiveState versions,
-do not have the Cygwin path name semantics.
-This means that using a native Windows version of Python
-to build compiled programs using Cygwin tools
-(such as gcc, bison, and flex)
-may yield unpredictable results.
-"Mixing and matching" in this way
-can be made to work,
-but it requires careful attention to the use of path names
-in your SConscript files.
-
-In practice, users can sidestep
-the issue by adopting the following rules:
-When using gcc,
-use the Cygwin-supplied Python interpreter
-to run SCons;
-when using Microsoft Visual C/C++
-(or some other Windows compiler)
-use the python.org or ActiveState version of Python
-to run SCons.
-.SS Windows:  scons.bat file
-On Windows systems,
-SCons is executed via a wrapper
-.B scons.bat
-file.
-This has (at least) two ramifications:
-
-First, Windows command-line users
-that want to use variable assignment
-on the command line
-may have to put double quotes
-around the assignments:
-
-.ES
-scons "FOO=BAR" "BAZ=BLEH"
-.EE
-
-Second, the Cygwin shell does not
-recognize this file as being the same
-as an
-.B scons
-command issued at the command-line prompt.
-You can work around this either by
-executing
-.B scons.bat
-from the Cygwin command line,
-or by creating a wrapper shell
-script named
-.B scons .
-
-.SS MinGW
-
-The MinGW bin directory must be in your PATH environment variable or the
-PATH variable under the ENV construction variable for SCons
-to detect and use the MinGW tools. When running under the native Windows
-Python interpreter, SCons will prefer the MinGW tools over the Cygwin
-tools, if they are both installed, regardless of the order of the bin
-directories in the PATH variable. If you have both MSVC and MinGW
-installed and you want to use MinGW instead of MSVC,
-then you must explictly tell SCons to use MinGW by passing
-
-.ES
-tools=['mingw']
-.EE
-
-to the Environment() function, because SCons will prefer the MSVC tools
-over the MinGW tools.
-
-.SH EXAMPLES
-
-To help you get started using SCons,
-this section contains a brief overview of some common tasks.
-
-.SS Basic Compilation From a Single Source File
-
-.ES
-env = Environment()
-env.Program(target = 'foo', source = 'foo.c')
-.EE
-
-Note:  Build the file by specifying
-the target as an argument
-("scons foo" or "scons foo.exe").
-or by specifying a dot ("scons .").
-
-.SS Basic Compilation From Multiple Source Files
-
-.ES
-env = Environment()
-env.Program(target = 'foo', source = Split('f1.c f2.c f3.c'))
-.EE
-
-.SS Setting a Compilation Flag
-
-.ES
-env = Environment(CCFLAGS = '-g')
-env.Program(target = 'foo', source = 'foo.c')
-.EE
-
-.SS Search The Local Directory For .h Files
-
-Note:  You do
-.I not
-need to set CCFLAGS to specify -I options by hand.
-SCons will construct the right -I options from CPPPATH.
-
-.ES
-env = Environment(CPPPATH = ['.'])
-env.Program(target = 'foo', source = 'foo.c')
-.EE
-
-.SS Search Multiple Directories For .h Files
-
-.ES
-env = Environment(CPPPATH = ['include1', 'include2'])
-env.Program(target = 'foo', source = 'foo.c')
-.EE
-
-.SS Building a Static Library
-
-.ES
-env = Environment()
-env.StaticLibrary(target = 'foo', source = Split('l1.c l2.c'))
-env.StaticLibrary(target = 'bar', source = ['l3.c', 'l4.c'])
-.EE
-
-.SS Building a Shared Library
-
-.ES
-env = Environment()
-env.SharedLibrary(target = 'foo', source = ['l5.c', 'l6.c'])
-env.SharedLibrary(target = 'bar', source = Split('l7.c l8.c'))
-.EE
-
-.SS Linking a Local Library Into a Program
-
-.ES
-env = Environment(LIBS = 'mylib', LIBPATH = ['.'])
-env.Library(target = 'mylib', source = Split('l1.c l2.c'))
-env.Program(target = 'prog', source = ['p1.c', 'p2.c'])
-.EE
-
-.SS Defining Your Own Builder Object
-
-Notice that when you invoke the Builder,
-you can leave off the target file suffix,
-and SCons will add it automatically.
-
-.ES
-bld = Builder(action = 'pdftex < $SOURCES > $TARGET'
-              suffix = '.pdf',
-              src_suffix = '.tex')
-env = Environment(BUILDERS = {'PDFBuilder' : bld})
-env.PDFBuilder(target = 'foo.pdf', source = 'foo.tex')
-
-# The following creates "bar.pdf" from "bar.tex"
-env.PDFBuilder(target = 'bar', source = 'bar')
-.EE
-
-Note also that the above initialization
-overwrites the default Builder objects,
-so the Environment created above
-can not be used call Builders like env.Program(),
-env.Object(), env.StaticLibrary(), etc.
-
-.SS Adding Your Own Builder Object to an Environment
-
-.ES
-bld = Builder(action = 'pdftex < $SOURCES > $TARGET'
-              suffix = '.pdf',
-              src_suffix = '.tex')
-env = Environment()
-env.Append(BUILDERS = {'PDFBuilder' : bld})
-env.PDFBuilder(target = 'foo.pdf', source = 'foo.tex')
-env.Program(target = 'bar', source = 'bar.c')
-.EE
-
-You also can use other Pythonic techniques to add
-to the BUILDERS construction variable, such as:
-
-.ES
-env = Environment()
-env['BUILDERS]['PDFBuilder'] = bld
-.EE
-
-.SS Defining Your Own Scanner Object
-
-The following example shows an extremely simple scanner (the
-.BR kfile_scan ()
-function)
-that doesn't use a search path at all
-and simply returns the
-file names present on any
-.B include
-lines in the scanned file.
-This would implicitly assume that all included
-files live in the top-level directory:
-
-.ES
-import re
-
-'\" Note:  the \\ in the following are for the benefit of nroff/troff,
-'\" not inappropriate doubled escape characters within the r'' raw string.
-include_re = re.compile(r'^include\\s+(\\S+)$', re.M)
-
-def kfile_scan(node, env, path, arg):
-    contents = node.get_text_contents()
-    includes = include_re.findall(contents)
-    return env.File(includes)
-
-kscan = Scanner(name = 'kfile',
-                function = kfile_scan,
-                argument = None,
-                skeys = ['.k'])
-scanners = Environment().Dictionary('SCANNERS')
-env = Environment(SCANNERS = scanners + [kscan])
-
-env.Command('foo', 'foo.k', 'kprocess < $SOURCES > $TARGET')
-
-bar_in = File('bar.in')
-env.Command('bar', bar_in, 'kprocess $SOURCES > $TARGET')
-bar_in.target_scanner = kscan
-.EE
-
-It is important to note that you
-have to return a list of File nodes from the scan function, simple
-strings for the file names won't do. As in the examples we are showing here,
-you can use the
-.BR File()
-function of your current Environment in order to create nodes on the fly from
-a sequence of file names with relative paths.
-
-Here is a similar but more complete example that searches
-a path of directories
-(specified as the
-.B MYPATH
-construction variable)
-for files that actually exist:
-
-.ES
-import re
-import os
-include_re = re.compile(r'^include\\s+(\\S+)$', re.M)
-
-def my_scan(node, env, path, arg):
-    contents = node.get_text_contents()
-    includes = include_re.findall(contents)
-    if includes == []:
-        return []
-    results = []
-    for inc in includes:
-        for dir in path:
-            file = str(dir) + os.sep + inc
-            if os.path.exists(file):
-                results.append(file)
-                break
-    return env.File(results)
-
-scanner = Scanner(name = 'myscanner',
-                 function = my_scan,
-                 argument = None,
-                 skeys = ['.x'],
-                 path_function = FindPathDirs('MYPATH')
-                 )
-scanners = Environment().Dictionary('SCANNERS')
-env = Environment(SCANNERS = scanners + [scanner],
-                  MYPATH = ['incs'])
-
-env.Command('foo', 'foo.x', 'xprocess < $SOURCES > $TARGET')
-.EE
-
-The
-.BR FindPathDirs ()
-function used in the previous example returns a function
-(actually a callable Python object)
-that will return a list of directories
-specified in the
-.B $MYPATH
-construction variable. It lets SCons detect the file
-.B incs/foo.inc
-, even if 
-.B foo.x 
-contains the line
-.B include foo.inc 
-only.
-If you need to customize how the search path is derived,
-you would provide your own
-.B path_function
-argument when creating the Scanner object,
-as follows:
-
-.ES
-# MYPATH is a list of directories to search for files in
-def pf(env, dir, target, source, arg):
-    top_dir = Dir('#').abspath
-    results = []
-    if 'MYPATH' in env:
-        for p in env['MYPATH']:
-            results.append(top_dir + os.sep + p)
-    return results
-
-scanner = Scanner(name = 'myscanner',
-                 function = my_scan,
-                 argument = None,
-                 skeys = ['.x'],
-                 path_function = pf
-                 )
-.EE
-
-.SS Creating a Hierarchical Build
-
-Notice that the file names specified in a subdirectory's
-SConscript
-file are relative to that subdirectory.
-
-.ES
-SConstruct:
-
-    env = Environment()
-    env.Program(target = 'foo', source = 'foo.c')
-
-    SConscript('sub/SConscript')
-
-sub/SConscript:
-
-    env = Environment()
-    # Builds sub/foo from sub/foo.c
-    env.Program(target = 'foo', source = 'foo.c')
-
-    SConscript('dir/SConscript')
-
-sub/dir/SConscript:
-
-    env = Environment()
-    # Builds sub/dir/foo from sub/dir/foo.c
-    env.Program(target = 'foo', source = 'foo.c')
-.EE
-
-.SS Sharing Variables Between SConscript Files
-
-You must explicitly Export() and Import() variables that
-you want to share between SConscript files.
-
-.ES
-SConstruct:
-
-    env = Environment()
-    env.Program(target = 'foo', source = 'foo.c')
-
-    Export("env")
-    SConscript('subdirectory/SConscript')
-
-subdirectory/SConscript:
-
-    Import("env")
-    env.Program(target = 'foo', source = 'foo.c')
-.EE
-
-.SS Building Multiple Variants From the Same Source
-
-Use the variant_dir keyword argument to
-the SConscript function to establish
-one or more separate variant build directory trees
-for a given source directory:
-
-.ES
-SConstruct:
-
-    cppdefines = ['FOO']
-    Export("cppdefines")
-    SConscript('src/SConscript', variant_dir='foo')
-
-    cppdefines = ['BAR']
-    Export("cppdefines")
-    SConscript('src/SConscript', variant_dir='bar')
-
-src/SConscript:
-
-    Import("cppdefines")
-    env = Environment(CPPDEFINES = cppdefines)
-    env.Program(target = 'src', source = 'src.c')
-.EE
-
-Note the use of the Export() method
-to set the "cppdefines" variable to a different
-value each time we call the SConscript function.
-
-.SS Hierarchical Build of Two Libraries Linked With a Program
-
-.ES
-SConstruct:
-
-    env = Environment(LIBPATH = ['#libA', '#libB'])
-    Export('env')
-    SConscript('libA/SConscript')
-    SConscript('libB/SConscript')
-    SConscript('Main/SConscript')
-
-libA/SConscript:
-
-    Import('env')
-    env.Library('a', Split('a1.c a2.c a3.c'))
-
-libB/SConscript:
-
-    Import('env')
-    env.Library('b', Split('b1.c b2.c b3.c'))
-
-Main/SConscript:
-
-    Import('env')
-    e = env.Copy(LIBS = ['a', 'b'])
-    e.Program('foo', Split('m1.c m2.c m3.c'))
-.EE
-
-The '#' in the LIBPATH directories specify that they're relative to the
-top-level directory, so they don't turn into "Main/libA" when they're
-used in Main/SConscript.
-
-Specifying only 'a' and 'b' for the library names
-allows SCons to append the appropriate library
-prefix and suffix for the current platform
-(for example, 'liba.a' on POSIX systems,
-\&'a.lib' on Windows).
-
-.SS Customizing construction variables from the command line.
-
-The following would allow the C compiler to be specified on the command
-line or in the file custom.py.
-
-.ES
-vars = Variables('custom.py')
-vars.Add('CC', 'The C compiler.')
-env = Environment(variables=vars)
-Help(vars.GenerateHelpText(env))
-.EE
-
-The user could specify the C compiler on the command line:
-
-.ES
-scons "CC=my_cc"
-.EE
-
-or in the custom.py file:
-
-.ES
-CC = 'my_cc'
-.EE
-
-or get documentation on the options:
-
-.ES
-$ scons -h
-
-CC: The C compiler.
-    default: None
-    actual: cc
-
-.EE
-
-.SS Using Microsoft Visual C++ precompiled headers
-
-Since windows.h includes everything and the kitchen sink, it can take quite
-some time to compile it over and over again for a bunch of object files, so
-Microsoft provides a mechanism to compile a set of headers once and then
-include the previously compiled headers in any object file. This
-technology is called precompiled headers. The general recipe is to create a
-file named "StdAfx.cpp" that includes a single header named "StdAfx.h", and
-then include every header you want to precompile in "StdAfx.h", and finally
-include "StdAfx.h" as the first header in all the source files you are
-compiling to object files. For example:
-
-StdAfx.h:
-.ES
-#include <windows.h>
-#include <my_big_header.h>
-.EE
-
-StdAfx.cpp:
-.ES
-#include <StdAfx.h>
-.EE
-
-Foo.cpp:
-.ES
-#include <StdAfx.h>
-
-/* do some stuff */
-.EE
-
-Bar.cpp:
-.ES
-#include <StdAfx.h>
-
-/* do some other stuff */
-.EE
-
-SConstruct:
-.ES
-env=Environment()
-env['PCHSTOP'] = 'StdAfx.h'
-env['PCH'] = env.PCH('StdAfx.cpp')[0]
-env.Program('MyApp', ['Foo.cpp', 'Bar.cpp'])
-.EE
-
-For more information see the document for the PCH builder, and the PCH and
-PCHSTOP construction variables. To learn about the details of precompiled
-headers consult the MSDN documention for /Yc, /Yu, and /Yp.
-
-.SS Using Microsoft Visual C++ external debugging information
-
-Since including debugging information in programs and shared libraries can
-cause their size to increase significantly, Microsoft provides a mechanism
-for including the debugging information in an external file called a PDB
-file. SCons supports PDB files through the PDB construction
-variable.
-
-SConstruct:
-.ES
-env=Environment()
-env['PDB'] = 'MyApp.pdb'
-env.Program('MyApp', ['Foo.cpp', 'Bar.cpp'])
-.EE
-
-For more information see the document for the PDB construction variable.
-
-.SH ENVIRONMENT
-
-.IP SCONS_LIB_DIR
-Specifies the directory that contains the SCons Python module directory
-(e.g. /home/aroach/scons-src-0.01/src/engine).
-
-.IP SCONSFLAGS
-A string of options that will be used by scons in addition to those passed
-on the command line.
-
-.SH "SEE ALSO"
-.B scons
-User Manual,
-.B scons
-Design Document,
-.B scons
-source code.
-
-.SH AUTHORS
-Steven Knight <knight@baldmt.com>
-.br
-Anthony Roach <aroach@electriceyeball.com>
-
diff --git a/doc/man/scons.xml b/doc/man/scons.xml
new file mode 100644
index 0000000..e1bbcd1
--- /dev/null
+++ b/doc/man/scons.xml
@@ -0,0 +1,7101 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<!DOCTYPE refentry [
+<!ENTITY % scons SYSTEM '../scons.mod'>
+%scons;
+<!ENTITY % builders-mod SYSTEM '../generated/builders.mod'>
+%builders-mod;
+<!ENTITY % functions-mod SYSTEM '../generated/functions.mod'>
+%functions-mod;
+<!ENTITY % tools-mod SYSTEM '../generated/tools.mod'>
+%tools-mod;
+<!ENTITY % variables-mod SYSTEM '../generated/variables.mod'>
+%variables-mod;
+]>
+<!-- lifted from troff+man by doclifter -->
+<refentry id='scons1' 
+          xmlns="http://www.scons.org/dbxsd/v1.0"
+          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+          xsi:schemaLocation="http://www.scons.org/dbxsd/v1.0 scons.xsd">
+<!--  __COPYRIGHT__ -->
+
+<!--  Permission is hereby granted, free of charge, to any person obtaining -->
+<!--  a copy of this software and associated documentation files (the -->
+<!--  "Software"), to deal in the Software without restriction, including -->
+<!--  without limitation the rights to use, copy, modify, merge, publish, -->
+<!--  distribute, sublicense, and/or sell copies of the Software, and to -->
+<!--  permit persons to whom the Software is furnished to do so, subject to -->
+<!--  the following conditions: -->
+
+<!--  The above copyright notice and this permission notice shall be included -->
+<!--  in all copies or substantial portions of the Software. -->
+
+<!--  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY -->
+<!--  KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE -->
+<!--  WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND -->
+<!--  NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE -->
+<!--  LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION -->
+<!--  OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION -->
+<!--  WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. -->
+
+<!--  __FILE__ __REVISION__ __DATE__ __DEVELOPER__ -->
+
+<refmeta>
+<refentrytitle>SCONS</refentrytitle>
+<manvolnum>1</manvolnum>
+<refmiscinfo class='source'>__MONTH_YEAR__</refmiscinfo>
+</refmeta>
+<refnamediv id='name'>
+<refname>scons</refname>
+<refpurpose>a software construction tool</refpurpose>
+</refnamediv>
+<!-- body begins here -->
+<refsynopsisdiv id='synopsis'>
+<cmdsynopsis>
+  <command>scons</command>    
+    <arg choice='opt' rep='repeat'><replaceable>options</replaceable></arg>
+    <arg choice='opt' rep='repeat'><replaceable>name=val</replaceable></arg>
+    <arg choice='opt' rep='repeat'><replaceable>targets</replaceable></arg>
+</cmdsynopsis>
+</refsynopsisdiv>
+
+
+<refsect1 id='description'><title>DESCRIPTION</title>
+<para>The
+<command>scons</command>
+utility builds software (or other files) by determining which
+component pieces must be rebuilt and executing the necessary commands to
+rebuild them.</para>
+
+<para>By default,
+<command>scons</command>
+searches for a file named
+<emphasis remap='I'>SConstruct</emphasis>,
+<emphasis remap='I'>Sconstruct</emphasis>,
+or
+<emphasis remap='I'>sconstruct</emphasis>
+(in that order) in the current directory and reads its
+configuration from the first file found.
+An alternate file name may be
+specified via the
+<option>-f</option>
+option.</para>
+
+<para>The
+<emphasis remap='I'>SConstruct</emphasis>
+file can specify subsidiary
+configuration files using the
+<emphasis remap='B'>SConscript</emphasis>()
+function.
+By convention,
+these subsidiary files are named
+<emphasis remap='I'>SConscript</emphasis>,
+although any name may be used.
+(Because of this naming convention,
+the term "SConscript files"
+is sometimes used to refer
+generically to all
+<command>scons</command>
+configuration files,
+regardless of actual file name.)</para>
+
+<para>The configuration files
+specify the target files to be built, and
+(optionally) the rules to build those targets.  Reasonable default
+rules exist for building common software components (executable
+programs, object files, libraries), so that for most software
+projects, only the target and input files need be specified.</para>
+
+<para>Before reading the
+<emphasis remap='I'>SConstruct</emphasis>
+file,
+<command>scons</command>
+looks for a directory named
+<emphasis remap='I'>site_scons</emphasis>
+in various system directories (see below) and the directory containing the
+<emphasis remap='I'>SConstruct</emphasis>
+file; for each of those dirs which exists,
+<emphasis remap='I'>site_scons</emphasis>
+is prepended to sys.path,
+the file
+<emphasis remap='I'>site_scons/site_init.py</emphasis>,
+is evaluated if it exists,
+and the directory
+<emphasis remap='I'>site_scons/site_tools</emphasis>
+is prepended to the default toolpath if it exists.
+See the
+<option>--no-site-dir</option>
+and
+<option>--site-dir</option>
+options for more details.</para>
+
+<para><command>scons</command>
+reads and executes the SConscript files as Python scripts,
+so you may use normal Python scripting capabilities
+(such as flow control, data manipulation, and imported Python libraries)
+to handle complicated build situations.
+<command>scons</command>,
+however, reads and executes all of the SConscript files
+<emphasis remap='I'>before</emphasis>
+it begins building any targets.
+To make this obvious,
+<command>scons</command>
+prints the following messages about what it is doing:</para>
+
+<literallayout remap='.nf'>
+$ scons foo.out
+scons: Reading SConscript files ...
+scons: done reading SConscript files.
+scons: Building targets  ...
+cp foo.in foo.out
+scons: done building targets.
+$
+</literallayout> <!-- .fi -->
+
+<para>The status messages
+(everything except the line that reads "cp foo.in foo.out")
+may be suppressed using the
+<option>-Q</option>
+option.</para>
+
+<para><command>scons</command>
+does not automatically propagate
+the external environment used to execute
+<command>scons</command>
+to the commands used to build target files.
+This is so that builds will be guaranteed
+repeatable regardless of the environment
+variables set at the time
+<command>scons</command>
+is invoked.
+This also means that if the compiler or other commands
+that you want to use to build your target files
+are not in standard system locations,
+<command>scons</command>
+will not find them unless
+you explicitly set the PATH
+to include those locations.
+Whenever you create an
+<command>scons</command>
+construction environment,
+you can propagate the value of PATH
+from your external environment as follows:</para>
+
+<literallayout remap='.nf'>
+import os
+env = Environment(ENV = {'PATH' : os.environ['PATH']})
+</literallayout> <!-- .fi -->
+
+<para>Similarly, if the commands use external environment variables
+like $PATH, $HOME, $JAVA_HOME, $LANG, $SHELL, $TERM, etc.,
+these variables can also be explicitly propagated:</para>
+
+<literallayout remap='.nf'>
+import os
+env = Environment(ENV = {'PATH' : os.environ['PATH'],
+                         'HOME' : os.environ['HOME']})
+</literallayout> <!-- .fi -->
+
+<para>Or you may explicitly propagate the invoking user's
+complete external environment:</para>
+
+<literallayout remap='.nf'>
+import os
+env = Environment(ENV = os.environ)
+</literallayout> <!-- .fi -->
+
+<para>This comes at the expense of making your build
+dependent on the user's environment being set correctly,
+but it may be more convenient for many configurations.</para>
+
+<para><command>scons</command>
+can scan known input files automatically for dependency
+information (for example, #include statements
+in C or C++ files) and will rebuild dependent files appropriately
+whenever any "included" input file changes.
+<command>scons</command>
+supports the
+ability to define new scanners for unknown input file types.</para>
+
+<para><command>scons</command>
+knows how to fetch files automatically from
+SCCS or RCS subdirectories
+using SCCS, RCS or BitKeeper.</para>
+
+<para><command>scons</command>
+is normally executed in a top-level directory containing a
+<emphasis remap='I'>SConstruct</emphasis>
+file, optionally specifying
+as command-line arguments
+the target file or files to be built.</para>
+
+<para>By default, the command</para>
+
+<literallayout remap='.nf'>
+scons
+</literallayout> <!-- .fi -->
+
+<para>will build all target files in or below the current directory.
+Explicit default targets
+(to be built when no targets are specified on the command line)
+may be defined the SConscript file(s)
+using the
+<emphasis remap='B'>Default()</emphasis>
+function, described below.</para>
+
+<para>Even when
+<emphasis remap='B'>Default()</emphasis>
+targets are specified in the SConscript file(s),
+all target files in or below the current directory
+may be built by explicitly specifying
+the current directory (.)
+as a command-line target:</para>
+
+<literallayout remap='.nf'>
+scons .
+</literallayout> <!-- .fi -->
+
+<para>Building all target files,
+including any files outside of the current directory,
+may be specified by supplying a command-line target
+of the root directory (on POSIX systems):</para>
+
+<literallayout remap='.nf'>
+scons /
+</literallayout> <!-- .fi -->
+
+<para>or the path name(s) of the volume(s) in which all the targets
+should be built (on Windows systems):</para>
+
+<literallayout remap='.nf'>
+scons C:\ D:\
+</literallayout> <!-- .fi -->
+
+<para>To build only specific targets,
+supply them as command-line arguments:</para>
+
+<literallayout remap='.nf'>
+scons foo bar
+</literallayout> <!-- .fi -->
+
+<para>in which case only the specified targets will be built
+(along with any derived files on which they depend).</para>
+
+<para>Specifying "cleanup" targets in SConscript files is not usually necessary.
+The
+<option>-c</option>
+flag removes all files
+necessary to build the specified target:</para>
+
+<literallayout remap='.nf'>
+scons -c .
+</literallayout> <!-- .fi -->
+
+<para>to remove all target files, or:</para>
+
+<literallayout remap='.nf'>
+scons -c build export
+</literallayout> <!-- .fi -->
+
+<para>to remove target files under build and export.
+Additional files or directories to remove can be specified using the
+<emphasis remap='B'>Clean()</emphasis>
+function.
+Conversely, targets that would normally be removed by the
+<option>-c</option>
+invocation
+can be prevented from being removed by using the
+<emphasis remap='B'>NoClean</emphasis>()
+function.</para>
+
+<para>A subset of a hierarchical tree may be built by
+remaining at the top-level directory (where the
+<emphasis remap='I'>SConstruct</emphasis>
+file lives) and specifying the subdirectory as the target to be
+built:</para>
+
+<literallayout remap='.nf'>
+scons src/subdir
+</literallayout> <!-- .fi -->
+
+<para>or by changing directory and invoking scons with the
+<option>-u</option>
+option, which traverses up the directory
+hierarchy until it finds the
+<emphasis remap='I'>SConstruct</emphasis>
+file, and then builds
+targets relatively to the current subdirectory:</para>
+
+<literallayout remap='.nf'>
+cd src/subdir
+scons -u .
+</literallayout> <!-- .fi -->
+
+<para><command>scons</command>
+supports building multiple targets in parallel via a
+<option>-j</option>
+option that takes, as its argument, the number
+of simultaneous tasks that may be spawned:</para>
+
+<literallayout remap='.nf'>
+scons -j 4
+</literallayout> <!-- .fi -->
+
+<para>builds four targets in parallel, for example.</para>
+
+<para><command>scons</command>
+can maintain a cache of target (derived) files that can
+be shared between multiple builds.  When caching is enabled in a
+SConscript file, any target files built by
+<command>scons</command>
+will be copied
+to the cache.  If an up-to-date target file is found in the cache, it
+will be retrieved from the cache instead of being rebuilt locally.
+Caching behavior may be disabled and controlled in other ways by the
+<option>--cache-force</option>,
+<option>--cache-disable</option>,
+and
+<option>--cache-show</option>
+command-line options.  The
+<option>--random</option>
+option is useful to prevent multiple builds
+from trying to update the cache simultaneously.</para>
+
+<para>Values of variables to be passed to the SConscript file(s)
+may be specified on the command line:</para>
+
+<literallayout remap='.nf'>
+scons debug=1 .
+</literallayout> <!-- .fi -->
+
+<para>These variables are available in SConscript files
+through the ARGUMENTS dictionary,
+and can be used in the SConscript file(s) to modify
+the build in any way:</para>
+
+<literallayout remap='.nf'>
+if ARGUMENTS.get('debug', 0):
+    env = Environment(CCFLAGS = '-g')
+else:
+    env = Environment()
+</literallayout> <!-- .fi -->
+
+<para>The command-line variable arguments are also available
+in the ARGLIST list,
+indexed by their order on the command line.
+This allows you to process them in order rather than by name,
+if necessary.
+ARGLIST[0] returns a tuple
+containing (argname, argvalue).
+A Python exception is thrown if you
+try to access a list member that
+does not exist.</para>
+
+<para><command>scons</command>
+requires Python version 2.4 or later.
+There should be no other dependencies or requirements to run
+<emphasis remap='B'>scons.</emphasis></para>
+
+<!--  The following paragraph reflects the default tool search orders -->
+<!--  currently in SCons/Tool/__init__.py.  If any of those search orders -->
+<!--  change, this documentation should change, too. -->
+<para>By default,
+<command>scons</command>
+knows how to search for available programming tools
+on various systems.
+On Windows systems,
+<command>scons</command>
+searches in order for the
+Microsoft Visual C++ tools,
+the MinGW tool chain,
+the Intel compiler tools,
+and the PharLap ETS compiler.
+On OS/2 systems,
+<command>scons</command>
+searches in order for the
+OS/2 compiler,
+the GCC tool chain,
+and the Microsoft Visual C++ tools,
+On SGI IRIX, IBM AIX, Hewlett Packard HP-UX, and Sun Solaris systems,
+<command>scons</command>
+searches for the native compiler tools
+(MIPSpro, Visual Age, aCC, and Forte tools respectively)
+and the GCC tool chain.
+On all other platforms,
+including POSIX (Linux and UNIX) platforms,
+<command>scons</command>
+searches in order
+for the GCC tool chain,
+the Microsoft Visual C++ tools,
+and the Intel compiler tools.
+You may, of course, override these default values
+by appropriate configuration of
+Environment construction variables.</para>
+
+</refsect1>
+
+<refsect1 id='options'><title>OPTIONS</title>
+<para>In general,
+<command>scons</command>
+supports the same command-line options as GNU
+<emphasis remap='B'>make</emphasis>,
+and many of those supported by
+<emphasis remap='B'>cons</emphasis>.</para>
+
+<variablelist remap='TP'>
+  <varlistentry>
+  <term>-b</term>
+  <listitem>
+<para>Ignored for compatibility with non-GNU versions of
+<emphasis remap='B'>make.</emphasis></para>
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>-c, --clean, --remove</term>
+  <listitem>
+<para>Clean up by removing all target files for which a construction
+command is specified.
+Also remove any files or directories associated to the construction command
+using the
+<emphasis remap='B'>Clean</emphasis>()
+function.
+Will not remove any targets specified by the
+<emphasis remap='B'>NoClean</emphasis>()
+function.</para>
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>--cache-debug=<emphasis remap='I'>file</emphasis></term>
+  <listitem>
+<para>Print debug information about the
+<emphasis remap='B'>CacheDir</emphasis>()
+derived-file caching
+to the specified
+<emphasis remap='I'>file</emphasis>.
+If
+<emphasis remap='I'>file</emphasis>
+is
+<emphasis remap='B'>-</emphasis>
+(a hyphen),
+the debug information are printed to the standard output.
+The printed messages describe what signature file names are
+being looked for in, retrieved from, or written to the
+<emphasis remap='B'>CacheDir</emphasis>()
+directory tree.</para>
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>--cache-disable, --no-cache</term>
+  <listitem>
+<para>Disable the derived-file caching specified by
+<emphasis remap='B'>CacheDir</emphasis>().
+<command>scons</command>
+will neither retrieve files from the cache
+nor copy files to the cache.</para>
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>--cache-force, --cache-populate</term>
+  <listitem>
+<para>When using
+<emphasis remap='B'>CacheDir</emphasis>(),
+populate a cache by copying any already-existing, up-to-date
+derived files to the cache,
+in addition to files built by this invocation.
+This is useful to populate a new cache with
+all the current derived files,
+or to add to the cache any derived files
+recently built with caching disabled via the
+<option>--cache-disable</option>
+option.</para>
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>--cache-show</term>
+  <listitem>
+<para>When using
+<emphasis remap='B'>CacheDir</emphasis>()
+and retrieving a derived file from the cache,
+show the command
+that would have been executed to build the file,
+instead of the usual report,
+"Retrieved `file' from cache."
+This will produce consistent output for build logs,
+regardless of whether a target
+file was rebuilt or retrieved from the cache.</para>
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>--config=<emphasis remap='I'>mode</emphasis></term>
+  <listitem>
+<para>This specifies how the
+<emphasis remap='B'>Configure</emphasis>
+call should use or generate the
+results of configuration tests.
+The option should be specified from
+among the following choices:</para>
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>--config=auto</term>
+  <listitem>
+<para>scons will use its normal dependency mechanisms
+to decide if a test must be rebuilt or not.
+This saves time by not running the same configuration tests
+every time you invoke scons,
+but will overlook changes in system header files
+or external commands (such as compilers)
+if you don't specify those dependecies explicitly.
+This is the default behavior.</para>
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>--config=force</term>
+  <listitem>
+<para>If this option is specified,
+all configuration tests will be re-run
+regardless of whether the
+cached results are out of date.
+This can be used to explicitly
+force the configuration tests to be updated
+in response to an otherwise unconfigured change
+in a system header file or compiler.</para>
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>--config=cache</term>
+  <listitem>
+<para>If this option is specified,
+no configuration tests will be rerun
+and all results will be taken from cache.
+Note that scons will still consider it an error
+if --config=cache is specified
+and a necessary test does not
+yet have any results in the cache.</para>
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>-C<emphasis remap='I'> directory</emphasis>, --directory=<emphasis remap='I'>directory</emphasis></term>
+  <listitem>
+<para>Change to the specified
+<emphasis remap='I'>directory</emphasis>
+before searching for the
+<emphasis remap='I'>SConstruct</emphasis>,
+<emphasis remap='I'>Sconstruct</emphasis>,
+or
+<emphasis remap='I'>sconstruct</emphasis>
+file, or doing anything
+else.  Multiple
+<option>-C</option>
+options are interpreted
+relative to the previous one, and the right-most
+<option>-C</option>
+option wins. (This option is nearly
+equivalent to
+<option>-f directory/SConstruct</option>,
+except that it will search for
+<emphasis remap='I'>SConstruct</emphasis>,
+<emphasis remap='I'>Sconstruct</emphasis>,
+or
+<emphasis remap='I'>sconstruct</emphasis>
+in the specified directory.)</para>
+
+<!--  .TP -->
+<!--  \-d -->
+<!--  Display dependencies while building target files.  Useful for -->
+<!--  figuring out why a specific file is being rebuilt, as well as -->
+<!--  general debugging of the build process. -->
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>-D</term>
+  <listitem>
+<para>Works exactly the same way as the
+<option>-u</option>
+option except for the way default targets are handled.
+When this option is used and no targets are specified on the command line,
+all default targets are built, whether or not they are below the current
+directory.</para>
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>--debug=<emphasis remap='I'>type</emphasis></term>
+  <listitem>
+<para>Debug the build process.
+<emphasis remap='I'>type</emphasis>
+specifies what type of debugging:</para>
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>--debug=count</term>
+  <listitem>
+<para>Print how many objects are created
+of the various classes used internally by SCons
+before and after reading the SConscript files
+and before and after building targets.
+This is not supported when SCons is executed with the Python
+<option>-O</option>
+(optimized) option
+or when the SCons modules
+have been compiled with optimization
+(that is, when executing from
+<emphasis remap='B'>*.pyo</emphasis>
+files).</para>
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>--debug=duplicate</term>
+  <listitem>
+<para>Print a line for each unlink/relink (or copy) of a variant file from
+its source file.  Includes debugging info for unlinking stale variant
+files, as well as unlinking old targets before building them.</para>
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>--debug=dtree</term>
+  <listitem>
+<para>A synonym for the newer
+<option>--tree=derived</option>
+option.
+This will be deprecated in some future release
+and ultimately removed.</para>
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>--debug=explain</term>
+  <listitem>
+<para>Print an explanation of precisely why
+<command>scons</command>
+is deciding to (re-)build any targets.
+(Note:  this does not print anything
+for targets that are
+<emphasis remap='I'>not</emphasis>
+rebuilt.)</para>
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>--debug=findlibs</term>
+  <listitem>
+<para>Instruct the scanner that searches for libraries
+to print a message about each potential library
+name it is searching for,
+and about the actual libraries it finds.</para>
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>--debug=includes</term>
+  <listitem>
+<para>Print the include tree after each top-level target is built.
+This is generally used to find out what files are included by the sources
+of a given derived file:</para>
+
+<literallayout remap='.nf'>
+$ scons --debug=includes foo.o
+</literallayout> <!-- .fi -->
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>--debug=memoizer</term>
+  <listitem>
+<para>Prints a summary of hits and misses using the Memoizer,
+an internal subsystem that counts
+how often SCons uses cached values in memory
+instead of recomputing them each time they're needed.</para>
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>--debug=memory</term>
+  <listitem>
+<para>Prints how much memory SCons uses
+before and after reading the SConscript files
+and before and after building targets.</para>
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>--debug=nomemoizer</term>
+  <listitem>
+<para>A deprecated option preserved for backwards compatibility.</para>
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>--debug=objects</term>
+  <listitem>
+<para>Prints a list of the various objects
+of the various classes used internally by SCons.</para>
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>--debug=pdb</term>
+  <listitem>
+<para>Re-run SCons under the control of the
+pdb
+Python debugger.</para>
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>--debug=prepare</term>
+  <listitem>
+<para>Print a line each time any target (internal or external)
+is prepared for building.
+<command>scons</command>
+prints this for each target it considers, even if that
+target is up to date (see also --debug=explain).
+This can help debug problems with targets that aren't being
+built; it shows whether
+<command>scons</command>
+is at least considering them or not.</para>
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>--debug=presub</term>
+  <listitem>
+<para>Print the raw command line used to build each target
+before the construction environment variables are substituted.
+Also shows which targets are being built by this command.
+Output looks something like this:</para>
+<literallayout remap='.nf'>
+$ scons --debug=presub
+Building myprog.o with action(s):
+  $SHCC $SHCFLAGS $SHCCFLAGS $CPPFLAGS $_CPPINCFLAGS -c -o $TARGET $SOURCES
+...
+</literallayout> <!-- .fi -->
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>--debug=stacktrace</term>
+  <listitem>
+<para>Prints an internal Python stack trace
+when encountering an otherwise unexplained error.</para>
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>--debug=stree</term>
+  <listitem>
+<para>A synonym for the newer
+<option>--tree=all,status</option>
+option.
+This will be deprecated in some future release
+and ultimately removed.</para>
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>--debug=time</term>
+  <listitem>
+<para>Prints various time profiling information:
+the time spent executing each individual build command;
+the total build time (time SCons ran from beginning to end);
+the total time spent reading and executing SConscript files;
+the total time spent SCons itself spend running
+(that is, not counting reading and executing SConscript files);
+and both the total time spent executing all build commands
+and the elapsed wall-clock time spent executing those build commands.
+(When
+<command>scons</command>
+is executed without the
+<option>-j</option>
+option,
+the elapsed wall-clock time will typically
+be slightly longer than the total time spent
+executing all the build commands,
+due to the SCons processing that takes place
+in between executing each command.
+When
+<command>scons</command>
+is executed
+<emphasis remap='I'>with</emphasis>
+the
+<option>-j</option>
+option,
+and your build configuration allows good parallelization,
+the elapsed wall-clock time should
+be significantly smaller than the
+total time spent executing all the build commands,
+since multiple build commands and
+intervening SCons processing
+should take place in parallel.)</para>
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>--debug=tree</term>
+  <listitem>
+<para>A synonym for the newer
+<option>--tree=all</option>
+option.
+This will be deprecated in some future release
+and ultimately removed.</para>
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>--diskcheck=<emphasis remap='I'>types</emphasis></term>
+  <listitem>
+<para>Enable specific checks for
+whether or not there is a file on disk
+where the SCons configuration expects a directory
+(or vice versa),
+and whether or not RCS or SCCS sources exist
+when searching for source and include files.
+The
+<emphasis remap='I'>types</emphasis>
+argument can be set to:
+<emphasis remap='B'>all</emphasis>,
+to enable all checks explicitly
+(the default behavior);
+<emphasis remap='B'>none</emphasis>,
+to disable all such checks;
+<emphasis remap='B'>match</emphasis>,
+to check that files and directories on disk
+match SCons' expected configuration;
+<emphasis remap='B'>rcs</emphasis>,
+to check for the existence of an RCS source
+for any missing source or include files;
+<emphasis remap='B'>sccs</emphasis>,
+to check for the existence of an SCCS source
+for any missing source or include files.
+Multiple checks can be specified separated by commas;
+for example,
+<option>--diskcheck=sccs,rcs</option>
+would still check for SCCS and RCS sources,
+but disable the check for on-disk matches of files and directories.
+Disabling some or all of these checks
+can provide a performance boost for large configurations,
+or when the configuration will check for files and/or directories
+across networked or shared file systems,
+at the slight increased risk of an incorrect build
+or of not handling errors gracefully
+(if include files really should be
+found in SCCS or RCS, for example,
+or if a file really does exist
+where the SCons configuration expects a directory).</para>
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>--duplicate=<emphasis remap='I'>ORDER</emphasis></term>
+  <listitem>
+<para>There are three ways to duplicate files in a build tree: hard links,
+soft (symbolic) links and copies. The default behaviour of SCons is to
+prefer hard links to soft links to copies. You can specify different
+behaviours with this option.
+<emphasis remap='I'>ORDER</emphasis>
+must be one of
+<emphasis remap='I'>hard-soft-copy</emphasis>
+(the default),
+<emphasis remap='I'>soft-hard-copy</emphasis>,
+<emphasis remap='I'>hard-copy</emphasis>,
+<emphasis remap='I'>soft-copy</emphasis>
+or
+<emphasis remap='I'>copy</emphasis>.
+SCons will attempt to duplicate files using
+the mechanisms in the specified order.</para>
+
+<!--  .TP -->
+<!--  \-e, \-\-environment\-overrides -->
+<!--  Variables from the execution environment override construction -->
+<!--  variables from the SConscript files. -->
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>-f<emphasis remap='I'> file</emphasis>, --file=<emphasis remap='I'>file</emphasis>, --makefile=<emphasis remap='I'>file</emphasis>, --sconstruct=<emphasis remap='I'>file</emphasis></term>
+  <listitem>
+<para>Use
+<emphasis remap='I'>file</emphasis>
+as the initial SConscript file.
+Multiple
+<option>-f</option>
+options may be specified,
+in which case
+<command>scons</command>
+will read all of the specified files.</para>
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>-h, --help</term>
+  <listitem>
+<para>Print a local help message for this build, if one is defined in
+the SConscript file(s), plus a line that describes the
+<option>-H</option>
+option for command-line option help.  If no local help message
+is defined, prints the standard help message about command-line
+options.  Exits after displaying the appropriate message.</para>
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>-H, --help-options</term>
+  <listitem>
+<para>Print the standard help message about command-line options and
+exit.</para>
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>-i, --ignore-errors</term>
+  <listitem>
+<para>Ignore all errors from commands executed to rebuild files.</para>
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>-I<emphasis remap='I'> directory</emphasis>, --include-dir=<emphasis remap='I'>directory</emphasis></term>
+  <listitem>
+<para>Specifies a
+<emphasis remap='I'>directory</emphasis>
+to search for
+imported Python modules.  If several
+<option>-I</option>
+options
+are used, the directories are searched in the order specified.</para>
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>--implicit-cache</term>
+  <listitem>
+<para>Cache implicit dependencies.
+This causes
+<command>scons</command>
+to use the implicit (scanned) dependencies
+from the last time it was run
+instead of scanning the files for implicit dependencies.
+This can significantly speed up SCons,
+but with the following limitations:</para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+
+<para><command>scons</command>
+will not detect changes to implicit dependency search paths
+(e.g.
+<emphasis remap='B'>CPPPATH</emphasis>, <emphasis remap='B'>LIBPATH</emphasis>)
+that would ordinarily
+cause different versions of same-named files to be used.</para>
+
+<para><command>scons</command>
+will miss changes in the implicit dependencies
+in cases where a new implicit
+dependency is added earlier in the implicit dependency search path
+(e.g.
+<emphasis remap='B'>CPPPATH</emphasis>, <emphasis remap='B'>LIBPATH</emphasis>)
+than a current implicit dependency with the same name.</para>
+
+<variablelist remap='TP'>
+  <varlistentry>
+  <term>--implicit-deps-changed</term>
+  <listitem>
+<para>Forces SCons to ignore the cached implicit dependencies. This causes the
+implicit dependencies to be rescanned and recached. This implies
+<option>--implicit-cache</option>.</para>
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>--implicit-deps-unchanged</term>
+  <listitem>
+<para>Force SCons to ignore changes in the implicit dependencies.
+This causes cached implicit dependencies to always be used.
+This implies
+<option>--implicit-cache</option>.</para>
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>--interactive</term>
+  <listitem>
+<para>Starts SCons in interactive mode.
+The SConscript files are read once and a
+<emphasis remap='B'>scons&gt;&gt;&gt;</emphasis>
+prompt is printed.
+Targets may now be rebuilt by typing commands at interactive prompt
+without having to re-read the SConscript files
+and re-initialize the dependency graph from scratch.</para>
+
+<para>SCons interactive mode supports the following commands:</para>
+
+  <blockquote remap='RS'>
+    <variablelist remap='TP'>
+      <varlistentry>
+      <term><emphasis remap='B'>build</emphasis><emphasis remap='I'>[OPTIONS] [TARGETS] ...</emphasis></term>
+      <listitem>
+<para>Builds the specified
+<emphasis remap='I'>TARGETS</emphasis>
+(and their dependencies)
+with the specified
+SCons command-line
+<emphasis remap='I'>OPTIONS</emphasis>.
+<emphasis remap='B'>b</emphasis>
+and
+<command>scons</command>
+are synonyms.</para>
+
+<para>The following SCons command-line options affect the
+<emphasis remap='B'>build</emphasis>
+command:</para>
+
+<literallayout remap='.nf'>
+--cache-debug=FILE
+--cache-disable, --no-cache
+--cache-force, --cache-populate
+--cache-show
+--debug=TYPE
+-i, --ignore-errors
+-j N, --jobs=N
+-k, --keep-going
+-n, --no-exec, --just-print, --dry-run, --recon
+-Q
+-s, --silent, --quiet
+--taskmastertrace=FILE
+--tree=OPTIONS
+</literallayout> <!-- .fi -->
+
+      </listitem>
+      </varlistentry>
+    </variablelist>
+
+<para>Any other SCons command-line options that are specified
+do not cause errors
+but have no effect on the
+<emphasis remap='B'>build</emphasis>
+command
+(mainly because they affect how the SConscript files are read,
+which only happens once at the beginning of interactive mode).</para>
+
+    <variablelist remap='TP'>
+      <varlistentry>
+      <term><emphasis remap='B'>clean</emphasis><emphasis remap='I'>[OPTIONS] [TARGETS] ...</emphasis></term>
+      <listitem>
+<para>Cleans the specified
+<emphasis remap='I'>TARGETS</emphasis>
+(and their dependencies)
+with the specified options.
+<emphasis remap='B'>c</emphasis>
+is a synonym.
+This command is itself a synonym for
+<userinput>build --clean</userinput></para>
+
+      </listitem>
+      </varlistentry>
+      <varlistentry>
+      <term><emphasis remap='B'>exit</emphasis></term>
+      <listitem>
+<para>Exits SCons interactive mode.
+You can also exit by terminating input
+(CTRL+D on UNIX or Linux systems,
+CTRL+Z on Windows systems).</para>
+
+      </listitem>
+      </varlistentry>
+      <varlistentry>
+      <term><emphasis remap='B'>help</emphasis><emphasis remap='I'>[COMMAND]</emphasis></term>
+      <listitem>
+<para>Provides a help message about
+the commands available in SCons interactive mode.
+If
+<emphasis remap='I'>COMMAND</emphasis>
+is specified,
+<emphasis remap='B'>h</emphasis>
+and
+<emphasis remap='B'>?</emphasis>
+are synonyms.</para>
+
+      </listitem>
+      </varlistentry>
+      <varlistentry>
+      <term><emphasis remap='B'>shell</emphasis><emphasis remap='I'>[COMMANDLINE]</emphasis></term>
+      <listitem>
+<para>Executes the specified
+<emphasis remap='I'>COMMANDLINE</emphasis>
+in a subshell.
+If no
+<emphasis remap='I'>COMMANDLINE</emphasis>
+is specified,
+executes the interactive command interpreter
+specified in the
+<envar>SHELL</envar>
+environment variable
+(on UNIX and Linux systems)
+or the
+<emphasis remap='B'>COMSPEC</emphasis>
+environment variable
+(on Windows systems).
+<emphasis remap='B'>sh</emphasis>
+and
+<emphasis remap='B'>!</emphasis>
+are synonyms.</para>
+
+      </listitem>
+      </varlistentry>
+      <varlistentry>
+      <term><emphasis remap='B'>version</emphasis></term>
+      <listitem>
+<para>Prints SCons version information.</para>
+      </listitem>
+      </varlistentry>
+    </variablelist>
+    </blockquote> <!-- remap='RE' -->
+
+  </listitem>
+  </varlistentry>
+</variablelist>
+
+<para>An empty line repeats the last typed command.
+Command-line editing can be used if the
+<emphasis remap='B'>readline</emphasis>
+module is available.</para>
+
+<literallayout remap='.nf'>
+$ scons --interactive
+scons: Reading SConscript files ...
+scons: done reading SConscript files.
+scons&gt;&gt;&gt; build -n prog
+scons&gt;&gt;&gt; exit
+</literallayout> <!-- .fi -->
+
+<variablelist remap='TP'>
+  <varlistentry>
+  <term>-j<emphasis remap='I'> N</emphasis>, --jobs=<emphasis remap='I'>N</emphasis></term>
+  <listitem>
+<para>Specifies the number of jobs (commands) to run simultaneously.
+If there is more than one
+<option>-j</option>
+option, the last one is effective.</para>
+<!--  ??? If the -->
+<!--  .B \-j -->
+<!--  option -->
+<!--  is specified without an argument, -->
+<!--  .B scons -->
+<!--  will not limit the number of -->
+<!--  simultaneous jobs. -->
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>-k, --keep-going</term>
+  <listitem>
+<para>Continue as much as possible after an error.  The target that
+failed and those that depend on it will not be remade, but other
+targets specified on the command line will still be processed.</para>
+
+<!--  .TP -->
+<!--  .RI  \-l " N" ", \-\-load\-average=" N ", \-\-max\-load=" N -->
+<!--  No new jobs (commands) will be started if -->
+<!--  there are other jobs running and the system load -->
+<!--  average is at least -->
+<!--  .I N -->
+<!--  (a floating\-point number). -->
+
+
+<!--  .TP -->
+<!--  \-\-list\-derived -->
+<!--  List derived files (targets, dependencies) that would be built, -->
+<!--  but do not build them. -->
+<!--  [XXX This can probably go away with the right -->
+<!--  combination of other options.  Revisit this issue.] -->
+
+<!--  .TP -->
+<!--  \-\-list\-actions -->
+<!--  List derived files that would be built, with the actions -->
+<!--  (commands) that build them.  Does not build the files. -->
+<!--  [XXX This can probably go away with the right -->
+<!--  combination of other options.  Revisit this issue.] -->
+
+<!--  .TP -->
+<!--  \-\-list\-where -->
+<!--  List derived files that would be built, plus where the file is -->
+<!--  defined (file name and line number).  Does not build the files. -->
+<!--  [XXX This can probably go away with the right -->
+<!--  combination of other options.  Revisit this issue.] -->
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>-m</term>
+  <listitem>
+<para>Ignored for compatibility with non-GNU versions of
+<emphasis remap='B'>make</emphasis>.</para>
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>--max-drift=<emphasis remap='I'>SECONDS</emphasis></term>
+  <listitem>
+<para>Set the maximum expected drift in the modification time of files to
+<emphasis remap='I'>SECONDS</emphasis>.
+This value determines how long a file must be unmodified
+before its cached content signature
+will be used instead of
+calculating a new content signature (MD5 checksum)
+of the file's contents.
+The default value is 2 days, which means a file must have a
+modification time of at least two days ago in order to have its
+cached content signature used.
+A negative value means to never cache the content
+signature and to ignore the cached value if there already is one. A value
+of 0 means to always use the cached signature,
+no matter how old the file is.</para>
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>--md5-chunksize=<emphasis remap='I'>KILOBYTES</emphasis></term>
+  <listitem>
+<para>Set the block size used to compute MD5 signatures to
+<emphasis remap='I'>KILOBYTES</emphasis>.
+This value determines the size of the chunks which are read in at once when
+computing MD5 signatures.  Files below that size are fully stored in memory
+before performing the signature computation while bigger files are read in
+block-by-block. A huge block-size leads to high memory consumption while a very
+small block-size slows down the build considerably.</para>
+
+<para>The default value is to use a chunk size of 64 kilobytes, which should
+be appropriate for most uses.</para>
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>-n, --just-print, --dry-run, --recon</term>
+  <listitem>
+<para>No execute.  Print the commands that would be executed to build
+any out-of-date target files, but do not execute the commands.</para>
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>--no-site-dir</term>
+  <listitem>
+<para>Prevents the automatic addition of the standard
+<emphasis remap='I'>site_scons</emphasis>
+dirs to
+<emphasis remap='I'>sys.path</emphasis>.
+Also prevents loading the
+<emphasis remap='I'>site_scons/site_init.py</emphasis>
+modules if they exist, and prevents adding their
+<emphasis remap='I'>site_scons/site_tools</emphasis>
+dirs to the toolpath.</para>
+
+<!--  .TP -->
+<!--  .RI \-o " file" ", \-\-old\-file=" file ", \-\-assume\-old=" file -->
+<!--  Do not rebuild -->
+<!--  .IR file , -->
+<!--  and do -->
+<!--  not rebuild anything due to changes in the contents of -->
+<!--  .IR file . -->
+<!--  .TP -->
+<!--  .RI \-\-override " file" -->
+<!--  Read values to override specific build environment variables -->
+<!--  from the specified -->
+<!--  .IR file . -->
+<!--  .TP -->
+<!--  \-p -->
+<!--  Print the data base (construction environments, -->
+<!--  Builder and Scanner objects) that are defined -->
+<!--  after reading the SConscript files. -->
+<!--  After printing, a normal build is performed -->
+<!--  as usual, as specified by other command\-line options. -->
+<!--  This also prints version information -->
+<!--  printed by the -->
+<!--  .B \-v -->
+<!--  option. -->
+
+<!--  To print the database without performing a build do: -->
+
+<!--  .ES -->
+<!--  scons \-p \-q -->
+<!--  .EE -->
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>--profile=<emphasis remap='I'>file</emphasis></term>
+  <listitem>
+<para>Run SCons under the Python profiler
+and save the results in the specified
+<emphasis remap='I'>file</emphasis>.
+The results may be analyzed using the Python
+pstats module.</para>
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>-q, --question</term>
+  <listitem>
+<para>Do not run any commands, or print anything.  Just return an exit
+status that is zero if the specified targets are already up to
+date, non-zero otherwise.</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>-Q</term>
+  <listitem>
+<para>Quiets SCons status messages about
+reading SConscript files,
+building targets
+and entering directories.
+Commands that are executed
+to rebuild target files are still printed.</para>
+
+<!--  .TP -->
+<!--  \-r, \-R, \-\-no\-builtin\-rules, \-\-no\-builtin\-variables -->
+<!--  Clear the default construction variables.  Construction -->
+<!--  environments that are created will be completely empty. -->
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>--random</term>
+  <listitem>
+<para>Build dependencies in a random order.  This is useful when
+building multiple trees simultaneously with caching enabled,
+to prevent multiple builds from simultaneously trying to build
+or retrieve the same target files.</para>
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>-s, --silent, --quiet</term>
+  <listitem>
+<para>Silent.  Do not print commands that are executed to rebuild
+target files.
+Also suppresses SCons status messages.</para>
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>-S, --no-keep-going, --stop</term>
+  <listitem>
+<para>Ignored for compatibility with GNU
+<emphasis remap='B'>make</emphasis>.</para>
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>--site-dir=<emphasis remap='I'>dir</emphasis></term>
+  <listitem>
+<para>Uses the named dir as the site dir rather than the default
+<emphasis remap='I'>site_scons</emphasis>
+dirs.  This dir will get prepended to
+<emphasis remap='I'>sys.path</emphasis>,
+the module
+<emphasis remap='I'>dir</emphasis>/site_init.py
+will get loaded if it exists, and
+<emphasis remap='I'>dir</emphasis>/site_tools
+will get added to the default toolpath.</para>
+
+<para>The default set of
+<emphasis remap='I'>site_scons</emphasis>
+dirs used when
+<option>--site-dir</option>
+is not specified depends on the system platform, as follows.  Note
+that the directories are examined in the order given, from most
+generic to most specific, so the last-executed site_init.py file is
+the most specific one (which gives it the chance to override
+everything else), and the dirs are prepended to the paths, again so
+the last dir examined comes first in the resulting path.</para>
+
+  </listitem>
+  </varlistentry>
+</variablelist>
+<variablelist remap='IP'>
+  <varlistentry>
+  <term>Windows:</term>
+  <listitem>
+<literallayout remap='.nf'>
+    %ALLUSERSPROFILE/Application Data/scons/site_scons
+    %USERPROFILE%/Local Settings/Application Data/scons/site_scons
+    %APPDATA%/scons/site_scons
+    %HOME%/.scons/site_scons
+    ./site_scons
+</literallayout> <!-- .fi -->
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>Mac OS X:</term>
+  <listitem>
+<literallayout remap='.nf'>
+    /Library/Application Support/SCons/site_scons
+    /opt/local/share/scons/site_scons (for MacPorts)
+    /sw/share/scons/site_scons (for Fink)
+    $HOME/Library/Application Support/SCons/site_scons
+    $HOME/.scons/site_scons
+    ./site_scons
+</literallayout> <!-- .fi -->
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>Solaris:</term>
+  <listitem>
+<literallayout remap='.nf'>
+    /opt/sfw/scons/site_scons
+    /usr/share/scons/site_scons
+    $HOME/.scons/site_scons
+    ./site_scons
+</literallayout> <!-- .fi -->
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>Linux, HPUX, and other Posix-like systems:</term>
+  <listitem>
+<literallayout remap='.nf'>
+    /usr/share/scons/site_scons
+    $HOME/.scons/site_scons
+    ./site_scons
+</literallayout> <!-- .fi -->
+
+  </listitem>
+  </varlistentry>
+</variablelist>
+<variablelist remap='TP'>
+  <varlistentry>
+  <term>--stack-size=<emphasis remap='I'>KILOBYTES</emphasis></term>
+  <listitem>
+<para>Set the size stack used to run threads to
+<emphasis remap='I'>KILOBYTES</emphasis>.
+This value determines the stack size of the threads used to run jobs.
+These are the threads that execute the actions of the builders for the
+nodes that are out-of-date.
+Note that this option has no effect unless the
+<emphasis remap='B'>num_jobs</emphasis>
+option, which corresponds to -j and --jobs, is larger than one.  Using
+a stack size that is too small may cause stack overflow errors.  This
+usually shows up as segmentation faults that cause scons to abort
+before building anything.  Using a stack size that is too large will
+cause scons to use more memory than required and may slow down the entire
+build process.</para>
+
+<para>The default value is to use a stack size of 256 kilobytes, which should
+be appropriate for most uses.  You should not need to increase this value
+unless you encounter stack overflow errors.</para>
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>-t, --touch</term>
+  <listitem>
+<para>Ignored for compatibility with GNU
+<emphasis remap='B'>make</emphasis>.
+(Touching a file to make it
+appear up-to-date is unnecessary when using
+<command>scons</command>.)</para>
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>--taskmastertrace=<emphasis remap='I'>file</emphasis></term>
+  <listitem>
+<para>Prints trace information to the specified
+<emphasis remap='I'>file</emphasis>
+about how the internal Taskmaster object
+evaluates and controls the order in which Nodes are built.
+A file name of
+<emphasis remap='B'>-</emphasis>
+may be used to specify the standard output.</para>
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>-tree=<emphasis remap='I'>options</emphasis></term>
+  <listitem>
+<para>Prints a tree of the dependencies
+after each top-level target is built.
+This prints out some or all of the tree,
+in various formats,
+depending on the
+<emphasis remap='I'>options</emphasis>
+specified:</para>
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>--tree=all</term>
+  <listitem>
+<para>Print the entire dependency tree
+after each top-level target is built.
+This prints out the complete dependency tree,
+including implicit dependencies and ignored dependencies.</para>
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>--tree=derived</term>
+  <listitem>
+<para>Restricts the tree output to only derived (target) files,
+not source files.</para>
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>--tree=status</term>
+  <listitem>
+<para>Prints status information for each displayed node.</para>
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>--tree=prune</term>
+  <listitem>
+<para>Prunes the tree to avoid repeating dependency information
+for nodes that have already been displayed.
+Any node that has already been displayed
+will have its name printed in
+<emphasis remap='B'>[square brackets]</emphasis>,
+as an indication that the dependencies
+for that node can be found by searching
+for the relevant output higher up in the tree.</para>
+
+  </listitem>
+  </varlistentry>
+</variablelist>
+
+<para>Multiple options may be specified,
+separated by commas:</para>
+
+<literallayout remap='.nf'>
+# Prints only derived files, with status information:
+scons --tree=derived,status
+
+# Prints all dependencies of target, with status information
+# and pruning dependencies of already-visited Nodes:
+scons --tree=all,prune,status target
+</literallayout> <!-- .fi -->
+
+<variablelist remap='TP'>
+  <varlistentry>
+  <term>-u, --up, --search-up</term>
+  <listitem>
+<para>Walks up the directory structure until an
+<emphasis remap='I'>SConstruct ,</emphasis>
+<emphasis remap='I'>Sconstruct</emphasis>
+or
+<emphasis remap='I'>sconstruct</emphasis>
+file is found, and uses that
+as the top of the directory tree.
+If no targets are specified on the command line,
+only targets at or below the
+current directory will be built.</para>
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>-U</term>
+  <listitem>
+<para>Works exactly the same way as the
+<option>-u</option>
+option except for the way default targets are handled.
+When this option is used and no targets are specified on the command line,
+all default targets that are defined in the SConscript(s) in the current
+directory are built, regardless of what directory the resultant targets end
+up in.</para>
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>-v, --version</term>
+  <listitem>
+<para>Print the
+<command>scons</command>
+version, copyright information,
+list of authors, and any other relevant information.
+Then exit.</para>
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>-w, --print-directory</term>
+  <listitem>
+<para>Print a message containing the working directory before and
+after other processing.</para>
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>--no-print-directory</term>
+  <listitem>
+<para>Turn off -w, even if it was turned on implicitly.</para>
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>--warn=<emphasis remap='I'>type</emphasis>, --warn=no-<emphasis remap='I'>type</emphasis></term>
+  <listitem>
+<para>Enable or disable warnings.
+<emphasis remap='I'>type</emphasis>
+specifies the type of warnings to be enabled or disabled:</para>
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>--warn=all, --warn=no-all</term>
+  <listitem>
+<para>Enables or disables all warnings.</para>
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>--warn=cache-write-error, --warn=no-cache-write-error</term>
+  <listitem>
+<para>Enables or disables warnings about errors trying to
+write a copy of a built file to a specified
+<emphasis remap='B'>CacheDir</emphasis>().
+These warnings are disabled by default.</para>
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>--warn=corrupt-sconsign, --warn=no-corrupt-sconsign</term>
+  <listitem>
+<para>Enables or disables warnings about unfamiliar signature data in
+<markup>.sconsign</markup>
+files.
+These warnings are enabled by default.</para>
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>--warn=dependency, --warn=no-dependency</term>
+  <listitem>
+<para>Enables or disables warnings about dependencies.
+These warnings are disabled by default.</para>
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>--warn=deprecated, --warn=no-deprecated</term>
+  <listitem>
+<para>Enables or disables all warnings about use of
+currently deprecated features.
+These warnings are enabled by default.
+Note that the
+<option>--warn=no-deprecated</option>
+option does not disable warnings about absolutely all deprecated features.
+Warnings for some deprecated features that have already been through
+several releases with deprecation warnings
+may be mandatory for a release or two
+before they are officially no longer supported by SCons.
+Warnings for some specific deprecated features
+may be enabled or disabled individually;
+see below.</para>
+
+  <blockquote remap='RS'>
+    <variablelist remap='TP'>
+      <varlistentry>
+      <term>--warn=deprecated-copy, --warn=no-deprecated-copy</term>
+      <listitem>
+<para>Enables or disables warnings about use of the deprecated
+<emphasis remap='B'>env.Copy()</emphasis>
+method.</para>
+
+      </listitem>
+      </varlistentry>
+      <varlistentry>
+      <term>--warn=deprecated-source-signatures, --warn=no-deprecated-source-signatures</term>
+      <listitem>
+<para>Enables or disables warnings about use of the deprecated
+<emphasis remap='B'>SourceSignatures()</emphasis>
+function or
+<emphasis remap='B'>env.SourceSignatures()</emphasis>
+method.</para>
+
+      </listitem>
+      </varlistentry>
+      <varlistentry>
+      <term>--warn=deprecated-target-signatures, --warn=no-deprecated-target-signatures</term>
+      <listitem>
+<para>Enables or disables warnings about use of the deprecated
+<emphasis remap='B'>TargetSignatures()</emphasis>
+function or
+<emphasis remap='B'>env.TargetSignatures()</emphasis>
+method.</para>
+      </listitem>
+      </varlistentry>
+    </variablelist>
+    </blockquote> <!-- remap='RE' -->
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>--warn=duplicate-environment, --warn=no-duplicate-environment</term>
+  <listitem>
+<para>Enables or disables warnings about attempts to specify a build
+of a target with two different construction environments
+that use the same action.
+These warnings are enabled by default.</para>
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>--warn=fortran-cxx-mix, --warn=no-fortran-cxx-mix</term>
+  <listitem>
+<para>Enables or disables the specific warning about linking
+Fortran and C++ object files in a single executable,
+which can yield unpredictable behavior with some compilers.</para>
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>--warn=future-deprecated, --warn=no-future-deprecated</term>
+  <listitem>
+<para>Enables or disables warnings about features
+that will be deprecated in the future.
+These warnings are disabled by default.
+Enabling this warning is especially
+recommended for projects that redistribute
+SCons configurations for other users to build,
+so that the project can be warned as soon as possible
+about to-be-deprecated features
+that may require changes to the configuration.</para>
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>--warn=link, --warn=no-link</term>
+  <listitem>
+<para>Enables or disables warnings about link steps.</para>
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>--warn=misleading-keywords, --warn=no-misleading-keywords</term>
+  <listitem>
+<para>Enables or disables warnings about use of the misspelled keywords
+<emphasis remap='B'>targets</emphasis>
+and
+<emphasis remap='B'>sources</emphasis>
+when calling Builders.
+(Note the last
+<emphasis remap='B'>s</emphasis>
+characters, the correct spellings are
+<emphasis remap='B'>target</emphasis>
+and
+<emphasis remap='B'>source.)</emphasis>
+These warnings are enabled by default.</para>
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>--warn=missing-sconscript, --warn=no-missing-sconscript</term>
+  <listitem>
+<para>Enables or disables warnings about missing SConscript files.
+These warnings are enabled by default.</para>
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>--warn=no-md5-module, --warn=no-no-md5-module</term>
+  <listitem>
+<para>Enables or disables warnings about the version of Python
+not having an MD5 checksum module available.
+These warnings are enabled by default.</para>
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>--warn=no-metaclass-support, --warn=no-no-metaclass-support</term>
+  <listitem>
+<para>Enables or disables warnings about the version of Python
+not supporting metaclasses when the
+<option>--debug=memoizer</option>
+option is used.
+These warnings are enabled by default.</para>
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>--warn=no-object-count, --warn=no-no-object-count</term>
+  <listitem>
+<para>Enables or disables warnings about the
+<option>--debug=object</option>
+feature not working when
+<command>scons</command>
+is run with the python
+<option>-O</option>
+option or from optimized Python (.pyo) modules.</para>
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>--warn=no-parallel-support, --warn=no-no-parallel-support</term>
+  <listitem>
+<para>Enables or disables warnings about the version of Python
+not being able to support parallel builds when the
+<option>-j</option>
+option is used.
+These warnings are enabled by default.</para>
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>--warn=python-version, --warn=no-python-version</term>
+  <listitem>
+<para>Enables or disables the warning about running
+SCons with a deprecated version of Python.
+These warnings are enabled by default.</para>
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>--warn=reserved-variable, --warn=no-reserved-variable</term>
+  <listitem>
+<para>Enables or disables warnings about attempts to set the
+reserved construction variable names
+<emphasis remap='B'>CHANGED_SOURCES</emphasis>,
+<emphasis remap='B'>CHANGED_TARGETS</emphasis>,
+<emphasis remap='B'>TARGET</emphasis>,
+<emphasis remap='B'>TARGETS</emphasis>,
+<emphasis remap='B'>SOURCE</emphasis>,
+<emphasis remap='B'>SOURCES</emphasis>,
+<emphasis remap='B'>UNCHANGED_SOURCES</emphasis>
+or
+<emphasis remap='B'>UNCHANGED_TARGETS</emphasis>.
+These warnings are disabled by default.</para>
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>--warn=stack-size, --warn=no-stack-size</term>
+  <listitem>
+<para>Enables or disables warnings about requests to set the stack size
+that could not be honored.
+These warnings are enabled by default.</para>
+
+<!--  .TP -->
+<!--  .RI \-\-write\-filenames= file -->
+<!--  Write all filenames considered into -->
+<!--  .IR file . -->
+
+<!--  .TP -->
+<!--  .RI \-W " file" ", \-\-what\-if=" file ", \-\-new\-file=" file ", \-\-assume\-new=" file -->
+<!--  Pretend that the target -->
+<!--  .I file -->
+<!--  has been -->
+<!--  modified.  When used with the -->
+<!--  .B \-n -->
+<!--  option, this -->
+<!--  show you what would be rebuilt if you were to modify that file. -->
+<!--  Without -->
+<!--  .B \-n -->
+<!--  ... what? XXX -->
+
+<!--  .TP -->
+<!--  \-\-warn\-undefined\-variables -->
+<!--  Warn when an undefined variable is referenced. -->
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>-Y<emphasis remap='I'> repository</emphasis>, --repository=<emphasis remap='I'>repository</emphasis>, --srcdir=<emphasis remap='I'>repository</emphasis></term>
+  <listitem>
+<para>Search the specified repository for any input and target
+files not found in the local directory hierarchy.  Multiple
+<option>-Y</option>
+options may be specified, in which case the
+repositories are searched in the order specified.</para>
+
+  </listitem>
+  </varlistentry>
+</variablelist>
+</refsect1>
+
+<refsect1 id='configuration_file_reference'><title>CONFIGURATION FILE REFERENCE</title>
+<!--  .SS Python Basics -->
+<!--  XXX Adding this in the future would be a help. -->
+
+<refsect2 id='construction_environments'><title>Construction Environments</title>
+<para>A construction environment is the basic means by which the SConscript
+files communicate build information to
+<command>scons</command>.
+A new construction environment is created using the
+<emphasis remap='B'>Environment</emphasis>
+function:</para>
+
+<literallayout remap='.nf'>
+env = Environment()
+</literallayout> <!-- .fi -->
+
+<para>Variables, called
+<emphasis remap='I'>construction</emphasis>
+<emphasis remap='I'>variables</emphasis>,
+may be set in a construction environment
+either by specifying them as keywords when the object is created
+or by assigning them a value after the object is created:</para>
+
+<literallayout remap='.nf'>
+env = Environment(FOO = 'foo')
+env['BAR'] = 'bar'
+</literallayout> <!-- .fi -->
+
+<para>As a convenience,
+construction variables may also be set or modified by the
+<emphasis remap='I'>parse_flags</emphasis>
+keyword argument, which applies the
+<emphasis remap='B'>ParseFlags</emphasis>
+method (described below) to the argument value
+after all other processing is completed.
+This is useful either if the exact content of the flags is unknown
+(for example, read from a control file)
+or if the flags are distributed to a number of construction variables.</para>
+
+<literallayout remap='.nf'>
+env = Environment(parse_flags = '-Iinclude -DEBUG -lm')
+</literallayout> <!-- .fi -->
+
+<para>This example adds 'include' to
+<emphasis remap='B'>CPPPATH</emphasis>,
+'EBUG' to
+<emphasis remap='B'>CPPDEFINES</emphasis>,
+and 'm' to
+<emphasis remap='B'>LIBS</emphasis>.</para>
+
+<para>By default, a new construction environment is
+initialized with a set of builder methods
+and construction variables that are appropriate
+for the current platform.
+An optional platform keyword argument may be
+used to specify that an environment should
+be initialized for a different platform:</para>
+
+<literallayout remap='.nf'>
+env = Environment(platform = 'cygwin')
+env = Environment(platform = 'os2')
+env = Environment(platform = 'posix')
+env = Environment(platform = 'win32')
+</literallayout> <!-- .fi -->
+
+<para>Specifying a platform initializes the appropriate
+construction variables in the environment
+to use and generate file names with prefixes
+and suffixes appropriate for the platform.</para>
+
+<para>Note that the
+<emphasis remap='B'>win32</emphasis>
+platform adds the
+<emphasis remap='B'>SystemDrive</emphasis>
+and
+<emphasis remap='B'>SystemRoot</emphasis>
+variables from the user's external environment
+to the construction environment's
+<emphasis remap='B'>ENV</emphasis>
+dictionary.
+This is so that any executed commands
+that use sockets to connect with other systems
+(such as fetching source files from
+external CVS repository specifications like
+<emphasis remap='B'>:pserver:anonymous@cvs.sourceforge.net:/cvsroot/scons</emphasis>)
+will work on Windows systems.</para>
+
+<para>The platform argument may be function or callable object,
+in which case the Environment() method
+will call the specified argument to update
+the new construction environment:</para>
+
+<programlisting remap='.nf'>
+def my_platform(env):
+    env['VAR'] = 'xyzzy'
+
+env = Environment(platform = my_platform)
+</programlisting> <!-- .fi -->
+
+<para>Additionally, a specific set of tools
+with which to initialize the environment
+may be specified as an optional keyword argument:</para>
+
+<literallayout remap='.nf'>
+env = Environment(tools = ['msvc', 'lex'])
+</literallayout> <!-- .fi -->
+
+<para>Non-built-in tools may be specified using the toolpath argument:</para>
+
+<literallayout remap='.nf'>
+env = Environment(tools = ['default', 'foo'], toolpath = ['tools'])
+</literallayout> <!-- .fi -->
+
+<para>This looks for a tool specification in tools/foo.py (as well as
+using the ordinary default tools for the platform).  foo.py should
+have two functions: generate(env, **kw) and exists(env).
+The
+<function>generate()</function>
+function
+modifies the passed-in environment
+to set up variables so that the tool
+can be executed;
+it may use any keyword arguments
+that the user supplies (see below)
+to vary its initialization.
+The
+<function>exists()</function>
+function should return a true
+value if the tool is available.
+Tools in the toolpath are used before
+any of the built-in ones.  For example, adding gcc.py to the toolpath
+would override the built-in gcc tool.
+Also note that the toolpath is
+stored in the environment for use
+by later calls to
+<emphasis remap='B'>Clone</emphasis>()
+and
+<emphasis remap='B'>Tool</emphasis>()
+methods:</para>
+
+<literallayout remap='.nf'>
+base = Environment(toolpath=['custom_path'])
+derived = base.Clone(tools=['custom_tool'])
+derived.CustomBuilder()
+</literallayout> <!-- .fi -->
+
+<para>The elements of the tools list may also
+be functions or callable objects,
+in which case the Environment() method
+will call the specified elements
+to update the new construction environment:</para>
+
+<programlisting remap='.nf'>
+def my_tool(env):
+    env['XYZZY'] = 'xyzzy'
+
+env = Environment(tools = [my_tool])
+</programlisting> <!-- .fi -->
+
+<para>The individual elements of the tools list
+may also themselves be two-element lists of the form
+(<emphasis remap='I'>toolname</emphasis>, <emphasis remap='I'>kw_dict</emphasis>).
+SCons searches for the
+<emphasis remap='I'>toolname</emphasis>
+specification file as described above, and
+passes
+<emphasis remap='I'>kw_dict</emphasis>,
+which must be a dictionary, as keyword arguments to the tool's
+<emphasis remap='B'>generate</emphasis>
+function.
+The
+<emphasis remap='B'>generate</emphasis>
+function can use the arguments to modify the tool's behavior
+by setting up the environment in different ways
+or otherwise changing its initialization.</para>
+
+<programlisting remap='.nf'>
+# in tools/my_tool.py:
+def generate(env, **kw):
+  # Sets MY_TOOL to the value of keyword argument 'arg1' or 1.
+  env['MY_TOOL'] = kw.get('arg1', '1')
+def exists(env):
+  return 1
+
+# in SConstruct:
+env = Environment(tools = ['default', ('my_tool', {'arg1': 'abc'})],
+                  toolpath=['tools'])
+</programlisting> <!-- .fi -->
+
+<para>The tool definition (i.e. my_tool()) can use the PLATFORM variable from
+the environment it receives to customize the tool for different platforms.</para>
+
+<para>If no tool list is specified, then SCons will auto-detect the installed
+tools using the PATH variable in the ENV construction variable and the
+platform name when the Environment is constructed. Changing the PATH
+variable after the Environment is constructed will not cause the tools to
+be redetected.</para>
+
+<para>SCons supports the following tool specifications out of the box:</para>
+
+<literallayout remap='.nf'>
+386asm
+aixc++
+aixcc
+aixf77
+aixlink
+ar
+as
+bcc32
+c++
+cc
+cvf
+dmd
+dvipdf
+dvips
+f77
+f90
+f95
+fortran
+g++
+g77
+gas
+gcc
+gfortran
+gnulink
+gs
+hpc++
+hpcc
+hplink
+icc
+icl
+ifl
+ifort
+ilink
+ilink32
+intelc
+jar
+javac
+javah
+latex
+lex
+link
+linkloc
+m4
+masm
+midl
+mingw
+mslib
+mslink
+mssdk
+msvc
+msvs
+mwcc
+mwld
+nasm
+pdflatex
+pdftex
+qt
+rmic
+rpcgen
+sgiar
+sgic++
+sgicc
+sgilink
+sunar
+sunc++
+suncc
+sunf77
+sunf90
+sunf95
+sunlink
+swig
+tar
+tex
+textfile
+tlib
+yacc
+zip
+</literallayout> <!-- .fi -->
+
+<para>Additionally, there is a "tool" named
+<emphasis remap='B'>default</emphasis>
+which configures the
+environment with a default set of tools for the current platform.</para>
+
+<para>On posix and cygwin platforms
+the GNU tools (e.g. gcc) are preferred by SCons,
+on Windows the Microsoft tools (e.g. msvc)
+followed by MinGW are preferred by SCons,
+and in OS/2 the IBM tools (e.g. icc) are preferred by SCons.</para>
+
+</refsect2>
+
+<refsect2 id='builder_methods'><title>Builder Methods</title>
+
+<para>Build rules are specified by calling a construction
+environment's builder methods.
+The arguments to the builder methods are
+<emphasis remap='B'>target</emphasis>
+(a list of targets to be built,
+usually file names)
+and
+<emphasis remap='B'>source</emphasis>
+(a list of sources to be built,
+usually file names).</para>
+
+<para>Because long lists of file names
+can lead to a lot of quoting,
+<command>scons</command>
+supplies a
+<emphasis remap='B'>Split()</emphasis>
+global function
+and a same-named environment method
+that split a single string
+into a list, separated on
+strings of white-space characters.
+(These are similar to the split() member function of Python strings
+but work even if the input isn't a string.)</para>
+
+<para>Like all Python arguments,
+the target and source arguments to a builder method
+can be specified either with or without
+the "target" and "source" keywords.
+When the keywords are omitted,
+the target is first,
+followed by the source.
+The following are equivalent examples of calling the Program builder method:</para>
+
+<literallayout remap='.nf'>
+env.Program('bar', ['bar.c', 'foo.c'])
+env.Program('bar', Split('bar.c foo.c'))
+env.Program('bar', env.Split('bar.c foo.c'))
+env.Program(source =  ['bar.c', 'foo.c'], target = 'bar')
+env.Program(target = 'bar', Split('bar.c foo.c'))
+env.Program(target = 'bar', env.Split('bar.c foo.c'))
+env.Program('bar', source = 'bar.c foo.c'.split())
+</literallayout> <!-- .fi -->
+
+<para>Target and source file names
+that are not absolute path names
+(that is, do not begin with
+<emphasis remap='B'>/</emphasis>
+on POSIX systems
+or
+<emphasis remap='B'>\fR
+on Windows systems,
+with or without
+an optional drive letter)
+are interpreted relative to the directory containing the
+SConscript</emphasis>
+file being read.
+An initial
+<emphasis remap='B'>#</emphasis>
+(hash mark)
+on a path name means that the rest of the file name
+is interpreted relative to
+the directory containing
+the top-level
+<emphasis remap='B'>SConstruct</emphasis>
+file,
+even if the
+<emphasis remap='B'>#</emphasis>
+is followed by a directory separator character
+(slash or backslash).</para>
+
+<para>Examples:</para>
+
+<programlisting remap='.nf'>
+# The comments describing the targets that will be built
+# assume these calls are in a SConscript file in the
+# a subdirectory named "subdir".
+
+# Builds the program "subdir/foo" from "subdir/foo.c":
+env.Program('foo', 'foo.c')
+
+# Builds the program "/tmp/bar" from "subdir/bar.c":
+env.Program('/tmp/bar', 'bar.c')
+
+# An initial '#' or '#/' are equivalent; the following
+# calls build the programs "foo" and "bar" (in the
+# top-level SConstruct directory) from "subdir/foo.c" and
+# "subdir/bar.c", respectively:
+env.Program('#foo', 'foo.c')
+env.Program('#/bar', 'bar.c')
+
+# Builds the program "other/foo" (relative to the top-level
+# SConstruct directory) from "subdir/foo.c":
+env.Program('#other/foo', 'foo.c')
+</programlisting> <!-- .fi -->
+
+<para>When the target shares the same base name
+as the source and only the suffix varies,
+and if the builder method has a suffix defined for the target file type,
+then the target argument may be omitted completely,
+and
+<command>scons</command>
+will deduce the target file name from
+the source file name.
+The following examples all build the
+executable program
+<emphasis remap='B'>bar</emphasis>
+(on POSIX systems)
+or
+<emphasis remap='B'>bar.exe</emphasis>
+(on Windows systems)
+from the bar.c source file:</para>
+
+<literallayout remap='.nf'>
+env.Program(target = 'bar', source = 'bar.c')
+env.Program('bar', source = 'bar.c')
+env.Program(source = 'bar.c')
+env.Program('bar.c')
+</literallayout> <!-- .fi -->
+
+<para>As a convenience, a
+<emphasis remap='B'>srcdir</emphasis>
+keyword argument may be specified
+when calling a Builder.
+When specified,
+all source file strings that are not absolute paths
+will be interpreted relative to the specified
+<emphasis remap='B'>srcdir</emphasis>.
+The following example will build the
+<emphasis remap='B'>build/prog</emphasis>
+(or
+<emphasis remap='B'>build/prog.exe</emphasis>
+on Windows)
+program from the files
+<emphasis remap='B'>src/f1.c</emphasis>
+and
+<emphasis remap='B'>src/f2.c</emphasis>:</para>
+
+<literallayout remap='.nf'>
+env.Program('build/prog', ['f1.c', 'f2.c'], srcdir='src')
+</literallayout> <!-- .fi -->
+
+<para>It is possible to override or add construction variables when calling a
+builder method by passing additional keyword arguments.
+These overridden or added
+variables will only be in effect when building the target, so they will not
+affect other parts of the build. For example, if you want to add additional
+libraries for just one program:</para>
+
+<literallayout remap='.nf'>
+env.Program('hello', 'hello.c', LIBS=['gl', 'glut'])
+</literallayout> <!-- .fi -->
+
+<para>or generate a shared library with a non-standard suffix:</para>
+
+<literallayout remap='.nf'>
+env.SharedLibrary('word', 'word.cpp',
+                  SHLIBSUFFIX='.ocx',
+                  LIBSUFFIXES=['.ocx'])
+</literallayout> <!-- .fi -->
+
+<para>(Note that both the $SHLIBSUFFIX and $LIBSUFFIXES variables must be set
+if you want SCons to search automatically
+for dependencies on the non-standard library names;
+see the descriptions of these variables, below, for more information.)</para>
+
+<para>It is also possible to use the
+<emphasis remap='I'>parse_flags</emphasis>
+keyword argument in an override:</para>
+
+<literallayout remap='.nf'>
+env = Program('hello', 'hello.c', parse_flags = '-Iinclude -DEBUG -lm')
+</literallayout> <!-- .fi -->
+
+<para>This example adds 'include' to
+<emphasis remap='B'>CPPPATH</emphasis>,
+'EBUG' to
+<emphasis remap='B'>CPPDEFINES</emphasis>,
+and 'm' to
+<emphasis remap='B'>LIBS</emphasis>.</para>
+
+<para>Although the builder methods defined by
+<command>scons</command>
+are, in fact,
+methods of a construction environment object,
+they may also be called without an explicit environment:</para>
+
+<literallayout remap='.nf'>
+Program('hello', 'hello.c')
+SharedLibrary('word', 'word.cpp')
+</literallayout> <!-- .fi -->
+
+<para>In this case,
+the methods are called internally using a default construction
+environment that consists of the tools and values that
+<command>scons</command>
+has determined are appropriate for the local system.</para>
+
+<para>Builder methods that can be called without an explicit
+environment may be called from custom Python modules that you
+import into an SConscript file by adding the following
+to the Python module:</para>
+
+<literallayout remap='.nf'>
+from SCons.Script import *
+</literallayout> <!-- .fi -->
+
+<para>All builder methods return a list-like object
+containing Nodes that
+represent the target or targets that will be built.
+A
+<emphasis remap='I'>Node</emphasis>
+is an internal SCons object
+which represents
+build targets or sources.</para>
+
+<para>The returned Node-list object
+can be passed to other builder methods as source(s)
+or passed to any SCons function or method
+where a filename would normally be accepted.
+For example, if it were necessary
+to add a specific
+<option>-D</option>
+flag when compiling one specific object file:</para>
+
+<literallayout remap='.nf'>
+bar_obj_list = env.StaticObject('bar.c', CPPDEFINES='-DBAR')
+env.Program(source = ['foo.c', bar_obj_list, 'main.c'])
+</literallayout> <!-- .fi -->
+
+<para>Using a Node in this way
+makes for a more portable build
+by avoiding having to specify
+a platform-specific object suffix
+when calling the Program() builder method.</para>
+
+<para>Note that Builder calls will automatically "flatten"
+the source and target file lists,
+so it's all right to have the bar_obj list
+return by the StaticObject() call
+in the middle of the source file list.
+If you need to manipulate a list of lists returned by Builders
+directly using Python,
+you can either build the list by hand:</para>
+
+<literallayout remap='.nf'>
+foo = Object('foo.c')
+bar = Object('bar.c')
+objects = ['begin.o'] + foo + ['middle.o'] + bar + ['end.o']
+for object in objects:
+    print str(object)
+</literallayout> <!-- .fi -->
+
+<para>Or you can use the
+<emphasis remap='B'>Flatten</emphasis>()
+function supplied by scons
+to create a list containing just the Nodes,
+which may be more convenient:</para>
+
+<literallayout remap='.nf'>
+foo = Object('foo.c')
+bar = Object('bar.c')
+objects = Flatten(['begin.o', foo, 'middle.o', bar, 'end.o'])
+for object in objects:
+    print str(object)
+</literallayout> <!-- .fi -->
+
+<para>Note also that because Builder calls return
+a list-like object, not an actual Python list,
+you should
+<emphasis remap='I'>not</emphasis>
+use the Python
+<emphasis remap='B'>+=</emphasis>
+operator to append Builder results to a Python list.
+Because the list and the object are different types,
+Python will not update the original list in place,
+but will instead create a new Node-list object
+containing the concatenation of the list
+elements and the Builder results.
+This will cause problems for any other Python variables
+in your SCons configuration
+that still hold on to a reference to the original list.
+Instead, use the Python
+<markup>.extend()</markup>
+method to make sure the list is updated in-place.
+Example:</para>
+
+<literallayout remap='.nf'>
+object_files = []
+
+# Do NOT use += as follows:
+#
+#    object_files += Object('bar.c')
+#
+# It will not update the object_files list in place.
+#
+# Instead, use the .extend() method:
+object_files.extend(Object('bar.c'))
+
+</literallayout> <!-- .fi -->
+
+<para>The path name for a Node's file may be used
+by passing the Node to the Python-builtin
+<function>str()</function>
+function:</para>
+
+<literallayout remap='.nf'>
+bar_obj_list = env.StaticObject('bar.c', CPPDEFINES='-DBAR')
+print "The path to bar_obj is:", str(bar_obj_list[0])
+</literallayout> <!-- .fi -->
+
+<para>Note again that because the Builder call returns a list,
+we have to access the first element in the list
+<emphasis remap='B'>(bar_obj_list[0])</emphasis>
+to get at the Node that actually represents
+the object file.</para>
+
+<para>Builder calls support a
+<emphasis remap='B'>chdir</emphasis>
+keyword argument that
+specifies that the Builder's action(s)
+should be executed
+after changing directory.
+If the
+<emphasis remap='B'>chdir</emphasis>
+argument is
+a string or a directory Node,
+scons will change to the specified directory.
+If the
+<emphasis remap='B'>chdir</emphasis>
+is not a string or Node
+and is non-zero,
+then scons will change to the
+target file's directory.</para>
+
+<literallayout remap='.nf'>
+# scons will change to the "sub" subdirectory
+# before executing the "cp" command.
+env.Command('sub/dir/foo.out', 'sub/dir/foo.in',
+            "cp dir/foo.in dir/foo.out",
+            chdir='sub')
+
+# Because chdir is not a string, scons will change to the
+# target's directory ("sub/dir") before executing the
+# "cp" command.
+env.Command('sub/dir/foo.out', 'sub/dir/foo.in',
+            "cp foo.in foo.out",
+            chdir=1)
+</literallayout> <!-- .fi -->
+
+<para>Note that scons will
+<emphasis remap='I'>not</emphasis>
+automatically modify
+its expansion of
+construction variables like
+<emphasis remap='B'>$TARGET</emphasis>
+and
+<emphasis remap='B'>$SOURCE</emphasis>
+when using the chdir
+keyword argument--that is,
+the expanded file names
+will still be relative to
+the top-level SConstruct directory,
+and consequently incorrect
+relative to the chdir directory.
+If you use the chdir keyword argument,
+you will typically need to supply a different
+command line using
+expansions like
+<emphasis remap='B'>${TARGET.file}</emphasis>
+and
+<emphasis remap='B'>${SOURCE.file}</emphasis>
+to use just the filename portion of the
+targets and source.</para>
+
+<para><command>scons</command>
+provides the following builder methods:</para>
+
+<!-- '\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -->
+<!-- '\" BEGIN GENERATED BUILDER DESCRIPTIONS -->
+
+<!-- '\" The descriptions below of the various SCons Builders are generated -->
+<!-- '\" from the .xml files that live next to the various Python modules in -->
+<!-- '\" the build enginer library.  If you're reading this [gnt]roff file -->
+<!-- '\" with an eye towards patching this man page, you can still submit -->
+<!-- '\" a diff against this text, but it will have to be translated to a -->
+<!-- '\" diff against the underlying .xml file before the patch is actually -->
+<!-- '\" accepted.  If you do that yourself, it will make it easier to -->
+<!-- '\" integrate the patch. -->
+
+<!-- '\" BEGIN GENERATED BUILDER DESCRIPTIONS -->
+<!-- '\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -->
+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../generated/builders.gen"/>
+<!-- '\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -->
+<!-- '\" END GENERATED BUILDER DESCRIPTIONS -->
+
+<!-- '\" The descriptions above of the various SCons Builders are generated -->
+<!-- '\" from the .xml files that live next to the various Python modules in -->
+<!-- '\" the build enginer library.  If you're reading this [gnt]roff file -->
+<!-- '\" with an eye towards patching this man page, you can still submit -->
+<!-- '\" a diff against this text, but it will have to be translated to a -->
+<!-- '\" diff against the underlying .xml file before the patch is actually -->
+<!-- '\" accepted.  If you do that yourself, it will make it easier to -->
+<!-- '\" integrate the patch. -->
+
+<!-- '\" END GENERATED BUILDER DESCRIPTIONS -->
+<!-- '\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -->
+
+
+<para>All
+targets of builder methods automatically depend on their sources.
+An explicit dependency can
+be specified using the
+<emphasis remap='B'>Depends</emphasis>
+method of a construction environment (see below).</para>
+
+<para>In addition,
+<command>scons</command>
+automatically scans
+source files for various programming languages,
+so the dependencies do not need to be specified explicitly.
+By default, SCons can
+C source files,
+C++ source files,
+Fortran source files with
+<markup>.F</markup>
+(POSIX systems only),
+<markup>.fpp,</markup>
+or
+<markup>.FPP</markup>
+file extensions,
+and assembly language files with
+<markup>.S</markup>
+(POSIX systems only),
+<markup>.spp,</markup>
+or
+<markup>.SPP</markup>
+files extensions
+for C preprocessor dependencies.
+SCons also has default support
+for scanning D source files,
+You can also write your own Scanners
+to add support for additional source file types.
+These can be added to the default
+Scanner object used by the
+<emphasis remap='B'>Object</emphasis>(),
+<emphasis remap='B'>StaticObject</emphasis>(),
+and
+<emphasis remap='B'>SharedObject</emphasis>()
+Builders by adding them
+to the
+<emphasis remap='B'>SourceFileScanner</emphasis>
+object.
+See the section "Scanner Objects"
+below, for more information about
+defining your own Scanner objects
+and using the
+<emphasis remap='B'>SourceFileScanner</emphasis>
+object.</para>
+
+</refsect2>
+
+<refsect2 id='methods_and_functions_to_do_things'><title>Methods and Functions to Do Things</title>
+<para>In addition to Builder methods,
+<command>scons</command>
+provides a number of other construction environment methods
+and global functions to
+manipulate the build configuration.</para>
+
+<para>Usually, a construction environment method
+and global function with the same name both exist
+so that you don't have to remember whether
+to a specific bit of functionality
+must be called with or without a construction environment.
+In the following list,
+if you call something as a global function
+it looks like:</para>
+<literallayout remap='.nf'>
+Function(<emphasis remap='I'>arguments</emphasis>)
+</literallayout> <!-- .fi -->
+<para>and if you call something through a construction
+environment it looks like:</para>
+<literallayout remap='.nf'>
+env.Function(<emphasis remap='I'>arguments</emphasis>)
+</literallayout> <!-- .fi -->
+<para>If you can call the functionality in both ways,
+then both forms are listed.</para>
+
+<para>Global functions may be called from custom Python modules that you
+import into an SConscript file by adding the following
+to the Python module:</para>
+
+<literallayout remap='.nf'>
+from SCons.Script import *
+</literallayout> <!-- .fi -->
+
+<para>Except where otherwise noted,
+the same-named
+construction environment method
+and global function
+provide the exact same functionality.
+The only difference is that,
+where appropriate,
+calling the functionality through a construction environment will
+substitute construction variables into
+any supplied strings.
+For example:</para>
+
+<literallayout remap='.nf'>
+env = Environment(FOO = 'foo')
+Default('$FOO')
+env.Default('$FOO')
+</literallayout> <!-- .fi -->
+
+<para>In the above example,
+the first call to the global
+<emphasis remap='B'>Default()</emphasis>
+function will actually add a target named
+<emphasis remap='B'>$FOO</emphasis>
+to the list of default targets,
+while the second call to the
+<emphasis remap='B'>env.Default()</emphasis>
+construction environment method
+will expand the value
+and add a target named
+<emphasis remap='B'>foo</emphasis>
+to the list of default targets.
+For more on construction variable expansion,
+see the next section on
+construction variables.</para>
+
+<para>Construction environment methods
+and global functions supported by
+<command>scons</command>
+include:</para>
+
+<!-- '\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -->
+<!-- '\" BEGIN GENERATED FUNCTION DESCRIPTIONS -->
+
+<!-- '\" The descriptions below of the various SCons functions are generated -->
+<!-- '\" from the .xml files that live next to the various Python modules in -->
+<!-- '\" the build enginer library.  If you're reading this [gnt]roff file -->
+<!-- '\" with an eye towards patching this man page, you can still submit -->
+<!-- '\" a diff against this text, but it will have to be translated to a -->
+<!-- '\" diff against the underlying .xml file before the patch is actually -->
+<!-- '\" accepted.  If you do that yourself, it will make it easier to -->
+<!-- '\" integrate the patch. -->
+
+<!-- '\" BEGIN GENERATED FUNCTION DESCRIPTIONS -->
+<!-- '\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -->
+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../generated/functions.gen"/>
+<!-- '\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -->
+<!-- '\" END GENERATED FUNCTION DESCRIPTIONS -->
+
+<!-- '\" The descriptions above of the various SCons functions are generated -->
+<!-- '\" from the .xml files that live next to the various Python modules in -->
+<!-- '\" the build enginer library.  If you're reading this [gnt]roff file -->
+<!-- '\" with an eye towards patching this man page, you can still submit -->
+<!-- '\" a diff against this text, but it will have to be translated to a -->
+<!-- '\" diff against the underlying .xml file before the patch is actually -->
+<!-- '\" accepted.  If you do that yourself, it will make it easier to -->
+<!-- '\" integrate the patch. -->
+
+<!-- '\" END GENERATED FUNCTION DESCRIPTIONS -->
+<!-- '\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -->
+
+</refsect2>
+
+<refsect2 id='sconscript_variables'><title>SConscript Variables</title>
+<para>In addition to the global functions and methods,
+<command>scons</command>
+supports a number of Python variables
+that can be used in SConscript files
+to affect how you want the build to be performed.
+These variables may be accessed from custom Python modules that you
+import into an SConscript file by adding the following
+to the Python module:</para>
+
+<literallayout remap='.nf'>
+from SCons.Script import *
+</literallayout> <!-- .fi -->
+
+<!-- '\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -->
+<variablelist remap='TP'>
+  <varlistentry>
+  <term>ARGLIST</term>
+  <listitem>
+<para>A list
+<emphasis remap='I'>keyword</emphasis>=<emphasis remap='I'>value</emphasis>
+arguments specified on the command line.
+Each element in the list is a tuple
+containing the
+(<emphasis remap='I'>keyword</emphasis>,<emphasis remap='I'>value</emphasis>)
+of the argument.
+The separate
+<emphasis remap='I'>keyword</emphasis>
+and
+<emphasis remap='I'>value</emphasis>
+elements of the tuple
+can be accessed by
+subscripting for element
+<emphasis remap='B'>[0]</emphasis>
+and
+<emphasis remap='B'>[1]</emphasis>
+of the tuple, respectively.</para>
+
+<para>Example:</para>
+
+<literallayout remap='.nf'>
+print "first keyword, value =", ARGLIST[0][0], ARGLIST[0][1]
+print "second keyword, value =", ARGLIST[1][0], ARGLIST[1][1]
+third_tuple = ARGLIST[2]
+print "third keyword, value =", third_tuple[0], third_tuple[1]
+for key, value in ARGLIST:
+    # process key and value
+</literallayout> <!-- .fi -->
+
+<!-- '\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -->
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>ARGUMENTS</term>
+  <listitem>
+<para>A dictionary of all the
+<emphasis remap='I'>keyword</emphasis>=<emphasis remap='I'>value</emphasis>
+arguments specified on the command line.
+The dictionary is not in order,
+and if a given keyword has
+more than one value assigned to it
+on the command line,
+the last (right-most) value is
+the one in the
+<emphasis remap='B'>ARGUMENTS</emphasis>
+dictionary.</para>
+
+<para>Example:</para>
+
+<literallayout remap='.nf'>
+if ARGUMENTS.get('debug', 0):
+    env = Environment(CCFLAGS = '-g')
+else:
+    env = Environment()
+</literallayout> <!-- .fi -->
+
+<!-- '\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -->
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>BUILD_TARGETS</term>
+  <listitem>
+<para>A list of the targets which
+<command>scons</command>
+will actually try to build,
+regardless of whether they were specified on
+the command line or via the
+<emphasis remap='B'>Default</emphasis>()
+function or method.
+The elements of this list may be strings
+<emphasis remap='I'>or</emphasis>
+nodes, so you should run the list through the Python
+<emphasis remap='B'>str</emphasis>
+function to make sure any Node path names
+are converted to strings.</para>
+
+<para>Because this list may be taken from the
+list of targets specified using the
+<emphasis remap='B'>Default</emphasis>()
+function or method,
+the contents of the list may change
+on each successive call to
+<emphasis remap='B'>Default</emphasis>().
+See the
+<emphasis remap='B'>DEFAULT_TARGETS</emphasis>
+list, below,
+for additional information.</para>
+
+<para>Example:</para>
+
+<literallayout remap='.nf'>
+if 'foo' in BUILD_TARGETS:
+    print "Don't forget to test the `foo' program!"
+if 'special/program' in BUILD_TARGETS:
+    SConscript('special')
+</literallayout> <!-- .fi -->
+  </listitem>
+  </varlistentry>
+</variablelist>
+
+<para>Note that the
+<emphasis remap='B'>BUILD_TARGETS</emphasis>
+list only contains targets expected listed
+on the command line or via calls to the
+<emphasis remap='B'>Default</emphasis>()
+function or method.
+It does
+<emphasis remap='I'>not</emphasis>
+contain all dependent targets that will be built as
+a result of making the sure the explicitly-specified
+targets are up to date.</para>
+
+<!-- '\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -->
+<variablelist remap='TP'>
+  <varlistentry>
+  <term>COMMAND_LINE_TARGETS</term>
+  <listitem>
+<para>A list of the targets explicitly specified on
+the command line.
+If there are no targets specified on the command line,
+the list is empty.
+This can be used, for example,
+to take specific actions only
+when a certain target or targets
+is explicitly being built.</para>
+
+<para>Example:</para>
+
+<literallayout remap='.nf'>
+if 'foo' in COMMAND_LINE_TARGETS:
+    print "Don't forget to test the `foo' program!"
+if 'special/program' in COMMAND_LINE_TARGETS:
+    SConscript('special')
+</literallayout> <!-- .fi -->
+
+<!-- '\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -->
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>DEFAULT_TARGETS</term>
+  <listitem>
+<para>A list of the target
+<emphasis remap='I'>nodes</emphasis>
+that have been specified using the
+<emphasis remap='B'>Default</emphasis>()
+function or method.
+The elements of the list are nodes,
+so you need to run them through the Python
+<emphasis remap='B'>str</emphasis>
+function to get at the path name for each Node.</para>
+
+<para>Example:</para>
+
+<literallayout remap='.nf'>
+print str(DEFAULT_TARGETS[0])
+if 'foo' in map(str, DEFAULT_TARGETS):
+    print "Don't forget to test the `foo' program!"
+</literallayout> <!-- .fi -->
+  </listitem>
+  </varlistentry>
+</variablelist>
+
+<para>The contents of the
+<emphasis remap='B'>DEFAULT_TARGETS</emphasis>
+list change on on each successive call to the
+<emphasis remap='B'>Default</emphasis>()
+function:</para>
+
+<literallayout remap='.nf'>
+print map(str, DEFAULT_TARGETS)   # originally []
+Default('foo')
+print map(str, DEFAULT_TARGETS)   # now a node ['foo']
+Default('bar')
+print map(str, DEFAULT_TARGETS)   # now a node ['foo', 'bar']
+Default(None)
+print map(str, DEFAULT_TARGETS)   # back to []
+</literallayout> <!-- .fi -->
+
+<para>Consequently, be sure to use
+<emphasis remap='B'>DEFAULT_TARGETS</emphasis>
+only after you've made all of your
+<emphasis remap='B'>Default</emphasis>()
+calls,
+or else simply be careful of the order
+of these statements in your SConscript files
+so that you don't look for a specific
+default target before it's actually been added to the list.</para>
+
+</refsect2>
+
+<refsect2 id='construction_variables'><title>Construction Variables</title>
+<!--  XXX From Gary Ruben, 23 April 2002: -->
+<!--  I think it would be good to have an example with each construction -->
+<!--  variable description in the documentation. -->
+<!--  eg. -->
+<!--  CC     The C compiler -->
+<!--     Example: env["CC"] = "c68x" -->
+<!--     Default: env["CC"] = "cc" -->
+
+<!--  CCCOM  The command line ... -->
+<!--     Example: -->
+<!--         To generate the compiler line c68x \-ps \-qq \-mr \-o $TARGET $SOURCES -->
+<!--         env["CC"] = "c68x" -->
+<!--         env["CFLAGS"] = "\-ps \-qq \-mr" -->
+<!--         env["CCCOM"] = "$CC $CFLAGS \-o $TARGET $SOURCES -->
+<!--     Default: -->
+<!--         (I dunno what this is ;\-) -->
+<para>A construction environment has an associated dictionary of
+<emphasis remap='I'>construction variables</emphasis>
+that are used by built-in or user-supplied build rules.
+Construction variables must follow the same rules for
+Python identifiers:
+the initial character must be an underscore or letter,
+followed by any number of underscores, letters, or digits.</para>
+
+<para>A number of useful construction variables are automatically defined by
+scons for each supported platform, and additional construction variables
+can be defined by the user. The following is a list of the automatically
+defined construction variables:</para>
+
+<!-- '\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -->
+<!-- '\" BEGIN GENERATED CONSTRUCTION VARIABLE DESCRIPTIONS -->
+
+<!-- '\" The descriptions below of the various SCons construction variables -->
+<!-- '\" are generated from the .xml files that live next to the various -->
+<!-- '\" Python modules in the build enginer library.  If you're reading -->
+<!-- '\" this [gnt]roff file with an eye towards patching this man page, -->
+<!-- '\" you can still submit a diff against this text, but it will have to -->
+<!-- '\" be translated to a diff against the underlying .xml file before the -->
+<!-- '\" patch is actually accepted.  If you do that yourself, it will make -->
+<!-- '\" it easier to integrate the patch. -->
+
+<!-- '\" BEGIN GENERATED CONSTRUCTION VARIABLE DESCRIPTIONS -->
+<!-- '\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -->
+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../generated/variables.gen"/>
+<!-- '\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -->
+<!-- '\" END GENERATED CONSTRUCTION VARIABLE DESCRIPTIONS -->
+
+<!-- '\" The descriptions above of the various SCons construction variables -->
+<!-- '\" are generated from the .xml files that live next to the various -->
+<!-- '\" Python modules in the build enginer library.  If you're reading -->
+<!-- '\" this [gnt]roff file with an eye towards patching this man page, -->
+<!-- '\" you can still submit a diff against this text, but it will have to -->
+<!-- '\" be translated to a diff against the underlying .xml file before the -->
+<!-- '\" patch is actually accepted.  If you do that yourself, it will make -->
+<!-- '\" it easier to integrate the patch. -->
+
+<!-- '\" END GENERATED CONSTRUCTION VARIABLE DESCRIPTIONS -->
+<!-- '\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -->
+
+
+<para>Construction variables can be retrieved and set using the
+<emphasis remap='B'>Dictionary</emphasis>
+method of the construction environment:</para>
+
+<literallayout remap='.nf'>
+dict = env.Dictionary()
+dict["CC"] = "cc"
+</literallayout> <!-- .fi -->
+
+<para>or using the [] operator:</para>
+
+<literallayout remap='.nf'>
+env["CC"] = "cc"
+</literallayout> <!-- .fi -->
+
+<para>Construction variables can also be passed to the construction environment
+constructor:</para>
+
+<literallayout remap='.nf'>
+env = Environment(CC="cc")
+</literallayout> <!-- .fi -->
+
+<para>or when copying a construction environment using the
+<emphasis remap='B'>Clone</emphasis>
+method:</para>
+
+<literallayout remap='.nf'>
+env2 = env.Clone(CC="cl.exe")
+</literallayout> <!-- .fi -->
+
+</refsect2>
+
+<refsect2 id='configure_contexts'><title>Configure Contexts</title>
+
+<para><command>scons</command>
+supports
+<emphasis remap='I'>configure contexts,</emphasis>
+an integrated mechanism similar to the
+various AC_CHECK macros in GNU autoconf
+for testing for the existence of C header
+files, libraries, etc.
+In contrast to autoconf,
+<command>scons</command>
+does not maintain an explicit cache of the tested values,
+but uses its normal dependency tracking to keep the checked values
+up to date. However, users may override this behaviour with the
+<option>--config</option>
+command line option.</para>
+
+<para>The following methods can be used to perform checks:</para>
+
+<variablelist remap='TP'>
+  <varlistentry>
+  <term>Configure(<emphasis remap='I'>env</emphasis>, [<emphasis remap='I'>custom_tests</emphasis>, <emphasis remap='I'>conf_dir</emphasis>, <emphasis remap='I'>log_file</emphasis>, <emphasis remap='I'>config_h</emphasis>, <emphasis remap='I'>clean</emphasis>, <emphasis remap='I'>help])</emphasis></term>
+  <term>env.Configure([<emphasis remap='I'>custom_tests</emphasis>, <emphasis remap='I'>conf_dir</emphasis>, <emphasis remap='I'>log_file</emphasis>, <emphasis remap='I'>config_h</emphasis>, <emphasis remap='I'>clean</emphasis>, <emphasis remap='I'>help])</emphasis></term>
+  <listitem>
+<para>This creates a configure context, which can be used to perform checks.
+<emphasis remap='I'>env</emphasis>
+specifies the environment for building the tests.
+This environment may be modified when performing checks.
+<emphasis remap='I'>custom_tests</emphasis>
+is a dictionary containing custom tests.
+See also the section about custom tests below.
+By default, no custom tests are added to the configure context.
+<emphasis remap='I'>conf_dir</emphasis>
+specifies a directory where the test cases are built.
+Note that this directory is not used for building
+normal targets.
+The default value is the directory
+#/.sconf_temp.
+<emphasis remap='I'>log_file</emphasis>
+specifies a file which collects the output from commands
+that are executed to check for the existence of header files, libraries, etc.
+The default is the file #/config.log.
+If you are using the
+<emphasis remap='B'>VariantDir</emphasis>()
+method,
+you may want to specify a subdirectory under your variant directory.
+<emphasis remap='I'>config_h</emphasis>
+specifies a C header file where the results of tests
+will be written, e.g. #define HAVE_STDIO_H, #define HAVE_LIBM, etc.
+The default is to not write a
+<emphasis remap='B'>config.h</emphasis>
+file.
+You can specify the same
+<emphasis remap='B'>config.h</emphasis>
+file in multiple calls to Configure,
+in which case
+<command>scons</command>
+will concatenate all results in the specified file.
+Note that SCons
+uses its normal dependency checking
+to decide if it's necessary to rebuild
+the specified
+<emphasis remap='I'>config_h</emphasis>
+file.
+This means that the file is not necessarily re-built each
+time scons is run,
+but is only rebuilt if its contents will have changed
+and some target that depends on the
+<emphasis remap='I'>config_h</emphasis>
+file is being built.</para>
+
+<para>The optional
+<emphasis remap='B'>clean</emphasis>
+and
+<emphasis remap='B'>help</emphasis>
+arguments can be used to suppress execution of the configuration
+tests when the
+<option>-c/--clean</option>
+or
+<option>-H/-h/--help</option>
+options are used, respectively.
+The default behavior is always to execute
+configure context tests,
+since the results of the tests may
+affect the list of targets to be cleaned
+or the help text.
+If the configure tests do not affect these,
+then you may add the
+<emphasis remap='B'>clean=False</emphasis>
+or
+<emphasis remap='B'>help=False</emphasis>
+arguments
+(or both)
+to avoid unnecessary test execution.</para>
+
+  </listitem>
+  </varlistentry>
+</variablelist>
+<para>A created
+<emphasis remap='B'>Configure</emphasis>
+instance has the following associated methods:</para>
+
+<variablelist remap='TP'>
+  <varlistentry>
+  <term>SConf.Finish(<emphasis remap='I'>context</emphasis>)</term>
+  <term><emphasis remap='I'>sconf</emphasis>.Finish()</term>
+  <listitem>
+<para>This method should be called after configuration is done.
+It returns the environment as modified
+by the configuration checks performed.
+After this method is called, no further checks can be performed
+with this configuration context.
+However, you can create a new
+Configure
+context to perform additional checks.
+Only one context should be active at a time.</para>
+
+<para>The following Checks are predefined.
+(This list will likely grow larger as time
+goes by and developers contribute new useful tests.)</para>
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>SConf.CheckHeader(<emphasis remap='I'>context</emphasis>, <emphasis remap='I'>header</emphasis>, [<emphasis remap='I'>include_quotes</emphasis>, <emphasis remap='I'>language</emphasis>])</term>
+  <term><emphasis remap='I'>sconf</emphasis>.CheckHeader(<emphasis remap='I'>header</emphasis>, [<emphasis remap='I'>include_quotes</emphasis>, <emphasis remap='I'>language</emphasis>])</term>
+  <listitem>
+<para>Checks if
+<emphasis remap='I'>header</emphasis>
+is usable in the specified language.
+<emphasis remap='I'>header</emphasis>
+may be a list,
+in which case the last item in the list
+is the header file to be checked,
+and the previous list items are
+header files whose
+<emphasis remap='B'>#include</emphasis>
+lines should precede the
+header line being checked for.
+The optional argument
+<emphasis remap='I'>include_quotes</emphasis>
+must be
+a two character string, where the first character denotes the opening
+quote and the second character denotes the closing quote.
+By default, both characters  are " (double quote).
+The optional argument
+<emphasis remap='I'>language</emphasis>
+should be either
+<emphasis remap='B'>C</emphasis>
+or
+<emphasis remap='B'>C++</emphasis>
+and selects the compiler to be used for the check.
+Returns 1 on success and 0 on failure.</para>
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>SConf.CheckCHeader(<emphasis remap='I'>context</emphasis>, <emphasis remap='I'>header</emphasis>, [<emphasis remap='I'>include_quotes</emphasis>])</term>
+  <term><emphasis remap='I'>sconf</emphasis>.CheckCHeader(<emphasis remap='I'>header</emphasis>, [<emphasis remap='I'>include_quotes</emphasis>])</term>
+  <listitem>
+<para>This is a wrapper around
+<emphasis remap='B'>SConf.CheckHeader</emphasis>
+which checks if
+<emphasis remap='I'>header</emphasis>
+is usable in the C language.
+<emphasis remap='I'>header</emphasis>
+may be a list,
+in which case the last item in the list
+is the header file to be checked,
+and the previous list items are
+header files whose
+<emphasis remap='B'>#include</emphasis>
+lines should precede the
+header line being checked for.
+The optional argument
+<emphasis remap='I'>include_quotes</emphasis>
+must be
+a two character string, where the first character denotes the opening
+quote and the second character denotes the closing quote (both default
+to \N'34').
+Returns 1 on success and 0 on failure.</para>
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>SConf.CheckCXXHeader(<emphasis remap='I'>context</emphasis>, <emphasis remap='I'>header</emphasis>, [<emphasis remap='I'>include_quotes</emphasis>])</term>
+  <term><emphasis remap='I'>sconf</emphasis>.CheckCXXHeader(<emphasis remap='I'>header</emphasis>, [<emphasis remap='I'>include_quotes</emphasis>])</term>
+  <listitem>
+<para>This is a wrapper around
+<emphasis remap='B'>SConf.CheckHeader</emphasis>
+which checks if
+<emphasis remap='I'>header</emphasis>
+is usable in the C++ language.
+<emphasis remap='I'>header</emphasis>
+may be a list,
+in which case the last item in the list
+is the header file to be checked,
+and the previous list items are
+header files whose
+<emphasis remap='B'>#include</emphasis>
+lines should precede the
+header line being checked for.
+The optional argument
+<emphasis remap='I'>include_quotes</emphasis>
+must be
+a two character string, where the first character denotes the opening
+quote and the second character denotes the closing quote (both default
+to \N'34').
+Returns 1 on success and 0 on failure.</para>
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>SConf.CheckFunc(<emphasis remap='I'>context,</emphasis>, <emphasis remap='I'>function_name</emphasis>, [<emphasis remap='I'>header</emphasis>, <emphasis remap='I'>language</emphasis>])</term>
+  <term><emphasis remap='I'>sconf</emphasis>.CheckFunc(<emphasis remap='I'>function_name</emphasis>, [<emphasis remap='I'>header</emphasis>, <emphasis remap='I'>language</emphasis>])</term>
+  <listitem>
+<para>Checks if the specified
+C or C++ function is available.
+<emphasis remap='I'>function_name</emphasis>
+is the name of the function to check for.
+The optional
+<emphasis remap='I'>header</emphasis>
+argument is a string
+that will be
+placed at the top
+of the test file
+that will be compiled
+to check if the function exists;
+the default is:</para>
+<literallayout remap='.nf'>
+#ifdef __cplusplus
+extern "C"
+#endif
+char function_name();
+</literallayout> <!-- .fi -->
+<para>The optional
+<emphasis remap='I'>language</emphasis>
+argument should be
+<emphasis remap='B'>C</emphasis>
+or
+<emphasis remap='B'>C++</emphasis>
+and selects the compiler to be used for the check;
+the default is "C".</para>
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>SConf.CheckLib(<emphasis remap='I'>context</emphasis>, [<emphasis remap='I'>library</emphasis>, <emphasis remap='I'>symbol</emphasis>, <emphasis remap='I'>header</emphasis>, <emphasis remap='I'>language</emphasis>, <emphasis remap='I'>autoadd=1</emphasis>])</term>
+  <term><emphasis remap='I'>sconf</emphasis>.CheckLib([<emphasis remap='I'>library</emphasis>, <emphasis remap='I'>symbol</emphasis>, <emphasis remap='I'>header</emphasis>, <emphasis remap='I'>language</emphasis>, <emphasis remap='I'>autoadd=1</emphasis>])</term>
+  <listitem>
+<para>Checks if
+<emphasis remap='I'>library</emphasis>
+provides
+<emphasis remap='I'>symbol</emphasis>.
+If the value of
+<emphasis remap='I'>autoadd</emphasis>
+is 1 and the library provides the specified
+<emphasis remap='I'>symbol</emphasis>,
+appends the library to the LIBS construction environment variable.
+<emphasis remap='I'>library</emphasis>
+may also be None (the default),
+in which case
+<emphasis remap='I'>symbol</emphasis>
+is checked with the current LIBS variable,
+or a list of library names,
+in which case each library in the list
+will be checked for
+<emphasis remap='I'>symbol</emphasis>.
+If
+<emphasis remap='I'>symbol</emphasis>
+is not set or is
+<emphasis remap='B'>None</emphasis>,
+then
+<emphasis remap='B'>SConf.CheckLib</emphasis>()
+just checks if
+you can link against the specified
+<emphasis remap='I'>library</emphasis>.
+The optional
+<emphasis remap='I'>language</emphasis>
+argument should be
+<emphasis remap='B'>C</emphasis>
+or
+<emphasis remap='B'>C++</emphasis>
+and selects the compiler to be used for the check;
+the default is "C".
+The default value for
+<emphasis remap='I'>autoadd</emphasis>
+is 1.
+This method returns 1 on success and 0 on error.</para>
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>SConf.CheckLibWithHeader(<emphasis remap='I'>context</emphasis>, <emphasis remap='I'>library</emphasis>, <emphasis remap='I'>header</emphasis>, <emphasis remap='I'>language</emphasis>, [<emphasis remap='I'>call</emphasis>, <emphasis remap='I'>autoadd</emphasis>])</term>
+  <term><emphasis remap='I'>sconf</emphasis>.CheckLibWithHeader(<emphasis remap='I'>library</emphasis>, <emphasis remap='I'>header</emphasis>, <emphasis remap='I'>language</emphasis>, [<emphasis remap='I'>call</emphasis>, <emphasis remap='I'>autoadd</emphasis>])</term>
+  <listitem>
+
+<para>In contrast to the
+SConf.CheckLib
+call, this call provides a more sophisticated way to check against libraries.
+Again,
+<emphasis remap='I'>library</emphasis>
+specifies the library or a list of libraries to check.
+<emphasis remap='I'>header</emphasis>
+specifies a header to check for.
+<emphasis remap='I'>header</emphasis>
+may be a list,
+in which case the last item in the list
+is the header file to be checked,
+and the previous list items are
+header files whose
+<emphasis remap='B'>#include</emphasis>
+lines should precede the
+header line being checked for.
+<emphasis remap='I'>language</emphasis>
+may be one of 'C','c','CXX','cxx','C++' and 'c++'.
+<emphasis remap='I'>call</emphasis>
+can be any valid expression (with a trailing ';').
+If
+<emphasis remap='I'>call</emphasis>
+is not set,
+the default simply checks that you
+can link against the specified
+<emphasis remap='I'>library</emphasis>.
+<emphasis remap='I'>autoadd</emphasis>
+specifies whether to add the library to the environment (only if the check
+succeeds). This method returns 1 on success and 0 on error.</para>
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>SConf.CheckType(<emphasis remap='I'>context</emphasis>, <emphasis remap='I'>type_name</emphasis>, [<emphasis remap='I'>includes</emphasis>, <emphasis remap='I'>language</emphasis>])</term>
+  <term><emphasis remap='I'>sconf</emphasis>.CheckType(<emphasis remap='I'>type_name</emphasis>, [<emphasis remap='I'>includes</emphasis>, <emphasis remap='I'>language</emphasis>])</term>
+  <listitem>
+<para>Checks for the existence of a type defined by
+<emphasis remap='B'>typedef</emphasis>.
+<emphasis remap='I'>type_name</emphasis>
+specifies the typedef name to check for.
+<emphasis remap='I'>includes</emphasis>
+is a string containing one or more
+<emphasis remap='B'>#include</emphasis>
+lines that will be inserted into the program
+that will be run to test for the existence of the type.
+The optional
+<emphasis remap='I'>language</emphasis>
+argument should be
+<emphasis remap='B'>C</emphasis>
+or
+<emphasis remap='B'>C++</emphasis>
+and selects the compiler to be used for the check;
+the default is "C".
+Example:</para>
+<literallayout remap='.nf'>
+sconf.CheckType('foo_type', '#include "my_types.h"', 'C++')
+</literallayout> <!-- .fi -->
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>Configure.CheckCC(<emphasis remap='I'>self</emphasis>)</term>
+  <listitem>
+<para>Checks whether the C compiler (as defined by the CC construction variable) works
+by trying to compile a small source file.</para>
+
+<para>By default, SCons only detects if there is a program with the correct name, not
+if it is a functioning compiler.</para>
+
+<para>This uses the exact same command than the one used by the object builder for C
+source file, so it can be used to detect if a particular compiler flag works or
+not.</para>
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>Configure.CheckCXX(<emphasis remap='I'>self</emphasis>)</term>
+  <listitem>
+<para>Checks whether the C++ compiler (as defined by the CXX construction variable)
+works by trying to compile a small source file. By default, SCons only detects
+if there is a program with the correct name, not if it is a functioning compiler.</para>
+
+<para>This uses the exact same command than the one used by the object builder for
+CXX source files, so it can be used to detect if a particular compiler flag
+works or not.</para>
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>Configure.CheckSHCC(<emphasis remap='I'>self</emphasis>)</term>
+  <listitem>
+<para>Checks whether the C compiler (as defined by the SHCC construction variable) works
+by trying to compile a small source file. By default, SCons only detects if
+there is a program with the correct name, not if it is a functioning compiler.</para>
+
+<para>This uses the exact same command than the one used by the object builder for C
+source file, so it can be used to detect if a particular compiler flag works or
+not. This does not check whether the object code can be used to build a shared
+library, only that the compilation (not link) succeeds.</para>
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>Configure.CheckSHCXX(<emphasis remap='I'>self</emphasis>)</term>
+  <listitem>
+<para>Checks whether the C++ compiler (as defined by the SHCXX construction variable)
+works by trying to compile a small source file. By default, SCons only detects
+if there is a program with the correct name, not if it is a functioning compiler.</para>
+
+<para>This uses the exact same command than the one used by the object builder for
+CXX source files, so it can be used to detect if a particular compiler flag
+works or not. This does not check whether the object code can be used to build
+a shared library, only that the compilation (not link) succeeds.</para>
+
+  </listitem>
+  </varlistentry>
+</variablelist>
+<para>Example of a typical Configure usage:</para>
+
+<literallayout remap='.nf'>
+env = Environment()
+conf = Configure( env )
+if not conf.CheckCHeader( 'math.h' ):
+    print 'We really need math.h!'
+    Exit(1)
+if conf.CheckLibWithHeader( 'qt', 'qapp.h', 'c++',
+        'QApplication qapp(0,0);' ):
+    # do stuff for qt - usage, e.g.
+    conf.env.Append( CPPFLAGS = '-DWITH_QT' )
+env = conf.Finish()
+</literallayout> <!-- .fi -->
+
+<variablelist remap='TP'>
+  <varlistentry>
+  <term>SConf.CheckTypeSize(<emphasis remap='I'>context</emphasis>, <emphasis remap='I'>type_name</emphasis>, [<emphasis remap='I'>header</emphasis>, <emphasis remap='I'>language</emphasis>, <emphasis remap='I'>expect</emphasis>])</term>
+  <term><emphasis remap='I'>sconf</emphasis>.CheckTypeSize(<emphasis remap='I'>type_name</emphasis>, [<emphasis remap='I'>header</emphasis>, <emphasis remap='I'>language</emphasis>, <emphasis remap='I'>expect</emphasis>])</term>
+  <listitem>
+<para>Checks for the size of a type defined by
+<emphasis remap='B'>typedef</emphasis>.
+<emphasis remap='I'>type_name</emphasis>
+specifies the typedef name to check for.
+The optional
+<emphasis remap='I'>header</emphasis>
+argument is a string
+that will be
+placed at the top
+of the test file
+that will be compiled
+to check if the function exists;
+the default is empty.
+The optional
+<emphasis remap='I'>language</emphasis>
+argument should be
+<emphasis remap='B'>C</emphasis>
+or
+<emphasis remap='B'>C++</emphasis>
+and selects the compiler to be used for the check;
+the default is "C".
+The optional
+<emphasis remap='I'>expect</emphasis>
+argument should be an integer.
+If this argument is used,
+the function will only check whether the type
+given in type_name has the expected size (in bytes).
+For example,
+<emphasis remap='B'>CheckTypeSize('short', expect = 2)</emphasis>
+will return success only if short is two bytes.</para>
+
+<literallayout remap='.nf'>
+</literallayout> <!-- .fi -->
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>SConf.CheckDeclaration(<emphasis remap='I'>context</emphasis>, <emphasis remap='I'>symbol</emphasis>, [<emphasis remap='I'>includes</emphasis>, <emphasis remap='I'>language</emphasis>])</term>
+  <term><emphasis remap='I'>sconf</emphasis>.CheckDeclaration(<emphasis remap='I'>symbol</emphasis>, [<emphasis remap='I'>includes</emphasis>, <emphasis remap='I'>language</emphasis>])</term>
+  <listitem>
+<para>Checks if the specified
+<emphasis remap='I'>symbol</emphasis>
+is declared.
+<emphasis remap='I'>includes</emphasis>
+is a string containing one or more
+<emphasis remap='B'>#include</emphasis>
+lines that will be inserted into the program
+that will be run to test for the existence of the type.
+The optional
+<emphasis remap='I'>language</emphasis>
+argument should be
+<emphasis remap='B'>C</emphasis>
+or
+<emphasis remap='B'>C++</emphasis>
+and selects the compiler to be used for the check;
+the default is "C".</para>
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>SConf.Define(<emphasis remap='I'>context</emphasis>, <emphasis remap='I'>symbol</emphasis>, [<emphasis remap='I'>value</emphasis>, <emphasis remap='I'>comment</emphasis>])</term>
+  <term><emphasis remap='I'>sconf</emphasis>.Define(<emphasis remap='I'>symbol</emphasis>, [<emphasis remap='I'>value</emphasis>, <emphasis remap='I'>comment</emphasis>])</term>
+  <listitem>
+<para>This function does not check for anything, but defines a
+preprocessor symbol that will be added to the configuration header file.
+It is the equivalent of AC_DEFINE,
+and defines the symbol
+<emphasis remap='I'>name</emphasis>
+with the optional
+<emphasis remap='B'>value</emphasis>
+and the optional comment
+<emphasis remap='B'>comment</emphasis>.</para>
+
+  </listitem>
+  </varlistentry>
+</variablelist>
+
+<para>Examples:</para>
+
+<programlisting remap='.nf'>
+env = Environment()
+conf = Configure( env )
+
+# Puts the following line in the config header file:
+#    #define A_SYMBOL
+conf.Define('A_SYMBOL')
+
+# Puts the following line in the config header file:
+#    #define A_SYMBOL 1
+conf.Define('A_SYMBOL', 1)
+</programlisting> <!-- .fi -->
+
+
+<para>Be careful about quoting string values, though:</para>
+
+<programlisting remap='.nf'>
+env = Environment()
+conf = Configure( env )
+
+# Puts the following line in the config header file:
+#    #define A_SYMBOL YA
+conf.Define('A_SYMBOL', "YA")
+
+# Puts the following line in the config header file:
+#    #define A_SYMBOL "YA"
+conf.Define('A_SYMBOL', '"YA"')
+</programlisting> <!-- .fi -->
+
+
+<para>For comment:</para>
+
+<programlisting remap='.nf'>
+env = Environment()
+conf = Configure( env )
+
+# Puts the following lines in the config header file:
+#    /* Set to 1 if you have a symbol */
+#    #define A_SYMBOL 1
+conf.Define('A_SYMBOL', 1, 'Set to 1 if you have a symbol')
+</programlisting> <!-- .fi -->
+
+<para>You can define your own custom checks.
+in addition to the predefined checks.
+These are passed in a dictionary to the Configure function.
+This dictionary maps the names of the checks
+to user defined Python callables
+(either Python functions or class instances implementing the
+<emphasis remap='I'>__call__</emphasis>
+method).
+The first argument of the call is always a
+<emphasis remap='I'>CheckContext</emphasis>
+instance followed by the arguments,
+which must be supplied by the user of the check.
+These CheckContext instances define the following methods:</para>
+
+<variablelist remap='TP'>
+  <varlistentry>
+  <term>CheckContext.Message(<emphasis remap='I'>self</emphasis>, <emphasis remap='I'>text</emphasis>)</term>
+  <listitem>
+
+<para>Usually called before the check is started.
+<emphasis remap='I'>text</emphasis>
+will be displayed to the user, e.g. 'Checking for library X...'</para>
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>CheckContext.Result(<emphasis remap='I'>self,</emphasis>, <emphasis remap='I'>res</emphasis>)</term>
+  <listitem>
+
+<para>Usually called after the check is done.
+<emphasis remap='I'>res</emphasis>
+can be either an integer or a string. In the former case, 'yes' (res != 0)
+or 'no' (res == 0) is displayed to the user, in the latter case the
+given string is displayed.</para>
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>CheckContext.TryCompile(<emphasis remap='I'>self</emphasis>, <emphasis remap='I'>text</emphasis>, <emphasis remap='I'>extension</emphasis>)</term>
+  <listitem>
+<para>Checks if a file with the specified
+<emphasis remap='I'>extension</emphasis>
+(e.g. '.c') containing
+<emphasis remap='I'>text</emphasis>
+can be compiled using the environment's
+<emphasis remap='B'>Object</emphasis>
+builder. Returns 1 on success and 0 on failure.</para>
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>CheckContext.TryLink(<emphasis remap='I'>self</emphasis>, <emphasis remap='I'>text</emphasis>, <emphasis remap='I'>extension</emphasis>)</term>
+  <listitem>
+<para>Checks, if a file with the specified
+<emphasis remap='I'>extension</emphasis>
+(e.g. '.c') containing
+<emphasis remap='I'>text</emphasis>
+can be compiled using the environment's
+<emphasis remap='B'>Program</emphasis>
+builder. Returns 1 on success and 0 on failure.</para>
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>CheckContext.TryRun(<emphasis remap='I'>self</emphasis>, <emphasis remap='I'>text</emphasis>, <emphasis remap='I'>extension</emphasis>)</term>
+  <listitem>
+<para>Checks, if a file with the specified
+<emphasis remap='I'>extension</emphasis>
+(e.g. '.c') containing
+<emphasis remap='I'>text</emphasis>
+can be compiled using the environment's
+<emphasis remap='B'>Program</emphasis>
+builder. On success, the program is run. If the program
+executes successfully
+(that is, its return status is 0),
+a tuple
+<emphasis remap='I'>(1, outputStr)</emphasis>
+is returned, where
+<emphasis remap='I'>outputStr</emphasis>
+is the standard output of the
+program.
+If the program fails execution
+(its return status is non-zero),
+then (0, '') is returned.</para>
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>CheckContext.TryAction(<emphasis remap='I'>self</emphasis>, <emphasis remap='I'>action</emphasis>, [<emphasis remap='I'>text</emphasis>, <emphasis remap='I'>extension</emphasis>])</term>
+  <listitem>
+<para>Checks if the specified
+<emphasis remap='I'>action</emphasis>
+with an optional source file (contents
+<emphasis remap='I'>text</emphasis>
+, extension
+<emphasis remap='I'>extension</emphasis>
+= ''
+) can be executed.
+<emphasis remap='I'>action</emphasis>
+may be anything which can be converted to a
+<command>scons</command>
+Action.
+On success,
+<emphasis remap='I'>(1, outputStr)</emphasis>
+is returned, where
+<emphasis remap='I'>outputStr</emphasis>
+is the content of the target file.
+On failure
+<emphasis remap='I'>(0, '')</emphasis>
+is returned.</para>
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>CheckContext.TryBuild(<emphasis remap='I'>self</emphasis>, <emphasis remap='I'>builder</emphasis>, [<emphasis remap='I'>text</emphasis>, <emphasis remap='I'>extension</emphasis>])</term>
+  <listitem>
+<para>Low level implementation for testing specific builds;
+the methods above are based on this method.
+Given the Builder instance
+<emphasis remap='I'>builder</emphasis>
+and the optional
+<emphasis remap='I'>text</emphasis>
+of a source file with optional
+<emphasis remap='I'>extension</emphasis>,
+this method returns 1 on success and 0 on failure. In addition,
+<emphasis remap='I'>self.lastTarget</emphasis>
+is set to the build target node, if the build was successful.</para>
+
+  </listitem>
+  </varlistentry>
+</variablelist>
+<para>Example for implementing and using custom tests:</para>
+
+<programlisting remap='.nf'>
+def CheckQt(context, qtdir):
+    context.Message( 'Checking for qt ...' )
+    lastLIBS = context.env['LIBS']
+    lastLIBPATH = context.env['LIBPATH']
+    lastCPPPATH= context.env['CPPPATH']
+    context.env.Append(LIBS = 'qt', LIBPATH = qtdir + '/lib', CPPPATH = qtdir + '/include' )
+    ret = context.TryLink("""
+#include &lt;qapp.h&gt;
+int main(int argc, char **argv) {
+  QApplication qapp(argc, argv);
+  return 0;
+}
+""")
+    if not ret:
+        context.env.Replace(LIBS = lastLIBS, LIBPATH=lastLIBPATH, CPPPATH=lastCPPPATH)
+    context.Result( ret )
+    return ret
+
+env = Environment()
+conf = Configure( env, custom_tests = { 'CheckQt' : CheckQt } )
+if not conf.CheckQt('/usr/lib/qt'):
+    print 'We really need qt!'
+    Exit(1)
+env = conf.Finish()
+</programlisting> <!-- .fi -->
+
+</refsect2>
+
+<refsect2 id='commandline_construction_variables'><title>Command-Line Construction Variables</title>
+
+<para>Often when building software,
+some variables must be specified at build time.
+For example, libraries needed for the build may be in non-standard
+locations, or site-specific compiler options may need to be passed to the
+compiler.
+<command>scons</command>
+provides a
+<emphasis remap='B'>Variables</emphasis>
+object to support overriding construction variables
+on the command line:</para>
+<literallayout remap='.nf'>
+$ scons VARIABLE=foo
+</literallayout> <!-- .fi -->
+<para>The variable values can also be specified in a text-based SConscript file.
+To create a Variables object, call the Variables() function:</para>
+
+<variablelist remap='TP'>
+  <varlistentry>
+  <term>Variables([<emphasis remap='I'>files</emphasis>], [<emphasis remap='I'>args</emphasis>])</term>
+  <listitem>
+<para>This creates a Variables object that will read construction variables from
+the file or list of filenames specified in
+<emphasis remap='I'>files</emphasis>.
+If no files are specified,
+or the
+<emphasis remap='I'>files</emphasis>
+argument is
+<emphasis remap='B'>None</emphasis>,
+then no files will be read.
+The optional argument
+<emphasis remap='I'>args</emphasis>
+is a dictionary of
+values that will override anything read from the specified files;
+it is primarily intended to be passed the
+<emphasis remap='B'>ARGUMENTS</emphasis>
+dictionary that holds variables
+specified on the command line.
+Example:</para>
+
+<literallayout remap='.nf'>
+vars = Variables('custom.py')
+vars = Variables('overrides.py', ARGUMENTS)
+vars = Variables(None, {FOO:'expansion', BAR:7})
+</literallayout> <!-- .fi -->
+
+<para>Variables objects have the following methods:</para>
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>Add(<emphasis remap='I'>key</emphasis>, [<emphasis remap='I'>help</emphasis>, <emphasis remap='I'>default</emphasis>, <emphasis remap='I'>validator</emphasis>, <emphasis remap='I'>converter</emphasis>])</term>
+  <listitem>
+<para>This adds a customizable construction variable to the Variables object.
+<emphasis remap='I'>key</emphasis>
+is the name of the variable.
+<emphasis remap='I'>help</emphasis>
+is the help text for the variable.
+<emphasis remap='I'>default</emphasis>
+is the default value of the variable;
+if the default value is
+<emphasis remap='B'>None</emphasis>
+and there is no explicit value specified,
+the construction variable will
+<emphasis remap='I'>not</emphasis>
+be added to the construction environment.
+<emphasis remap='I'>validator</emphasis>
+is called to validate the value of the variable, and should take three
+arguments: key, value, and environment.
+The recommended way to handle an invalid value is
+to raise an exception (see example below).
+<emphasis remap='I'>converter</emphasis>
+is called to convert the value before putting it in the environment, and
+should take either a value, or the value and environment, as parameters.
+The
+<emphasis remap='I'>converter</emphasis>
+must return a value,
+which will be converted into a string
+before being validated by the
+<emphasis remap='I'>validator</emphasis>
+(if any)
+and then added to the environment.</para>
+
+<para>Examples:</para>
+
+<programlisting remap='.nf'>
+vars.Add('CC', 'The C compiler')
+
+def validate_color(key, val, env):
+    if not val in ['red', 'blue', 'yellow']:
+        raise Exception("Invalid color value '%s'" % val)
+vars.Add('COLOR', validator=valid_color)
+</programlisting> <!-- .fi -->
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>AddVariables(<emphasis remap='I'>list</emphasis>)</term>
+  <listitem>
+<para>A wrapper script that adds
+multiple customizable construction variables
+to a Variables object.
+<emphasis remap='I'>list</emphasis>
+is a list of tuple or list objects
+that contain the arguments
+for an individual call to the
+<emphasis remap='B'>Add</emphasis>
+method.</para>
+
+<literallayout remap='.nf'>
+opt.AddVariables(
+       ('debug', '', 0),
+       ('CC', 'The C compiler'),
+       ('VALIDATE', 'An option for testing validation',
+        'notset', validator, None),
+    )
+</literallayout> <!-- .fi -->
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>Update(<emphasis remap='I'>env</emphasis>, [<emphasis remap='I'>args</emphasis>])</term>
+  <listitem>
+<para>This updates a construction environment
+<emphasis remap='I'>env</emphasis>
+with the customized construction variables.
+Any specified variables that are
+<emphasis remap='I'>not</emphasis>
+configured for the Variables object
+will be saved and may be
+retrieved with the
+<emphasis remap='B'>UnknownVariables</emphasis>()
+method, below.</para>
+
+<para>Normally this method is not called directly,
+but is called indirectly by passing the Variables object to
+the Environment() function:</para>
+
+<literallayout remap='.nf'>
+env = Environment(variables=vars)
+</literallayout> <!-- .fi -->
+
+  </listitem>
+  </varlistentry>
+</variablelist>
+
+<para>The text file(s) that were specified
+when the Variables object was created
+are executed as Python scripts,
+and the values of (global) Python variables set in the file
+are added to the construction environment.</para>
+
+<para>Example:</para>
+
+<literallayout remap='.nf'>
+CC = 'my_cc'
+</literallayout> <!-- .fi -->
+
+<variablelist remap='TP'>
+  <varlistentry>
+  <term>UnknownVariables(<emphasis remap='I'>)</emphasis></term>
+  <listitem>
+<para>Returns a dictionary containing any
+variables that were specified
+either in the files or the dictionary
+with which the Variables object was initialized,
+but for which the Variables object was
+not configured.</para>
+
+<literallayout remap='.nf'>
+env = Environment(variables=vars)
+for key, value in vars.UnknownVariables():
+    print "unknown variable:  %s=%s" % (key, value)
+</literallayout> <!-- .fi -->
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>Save(<emphasis remap='I'>filename</emphasis>, <emphasis remap='I'>env</emphasis>)</term>
+  <listitem>
+<para>This saves the currently set variables into a script file named
+<emphasis remap='I'>filename</emphasis>
+that can be used on the next invocation to automatically load the current
+settings.  This method combined with the Variables method can be used to
+support caching of variables between runs.</para>
+
+<literallayout remap='.nf'>
+env = Environment()
+vars = Variables(['variables.cache', 'custom.py'])
+vars.Add(...)
+vars.Update(env)
+vars.Save('variables.cache', env)
+</literallayout> <!-- .fi -->
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>GenerateHelpText(<emphasis remap='I'>env</emphasis>, [<emphasis remap='I'>sort</emphasis>])</term>
+  <listitem>
+<para>This generates help text documenting the customizable construction
+variables suitable to passing in to the Help() function.
+<emphasis remap='I'>env</emphasis>
+is the construction environment that will be used to get the actual values
+of customizable variables. Calling with
+an optional
+<emphasis remap='I'>sort</emphasis>
+function
+will cause the output to be sorted
+by the specified argument.
+The specific
+<emphasis remap='I'>sort</emphasis>
+function
+should take two arguments
+and return
+-1, 0 or 1
+(like the standard Python
+<emphasis remap='I'>cmp</emphasis>
+function).</para>
+
+<literallayout remap='.nf'>
+Help(vars.GenerateHelpText(env))
+Help(vars.GenerateHelpText(env, sort=cmp))
+</literallayout> <!-- .fi -->
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>FormatVariableHelpText(<emphasis remap='I'>env</emphasis>, <emphasis remap='I'>opt</emphasis>, <emphasis remap='I'>help</emphasis>, <emphasis remap='I'>default</emphasis>, <emphasis remap='I'>actual</emphasis>)</term>
+  <listitem>
+<para>This method returns a formatted string
+containing the printable help text
+for one option.
+It is normally not called directly,
+but is called by the
+<emphasis remap='I'>GenerateHelpText</emphasis>()
+method to create the returned help text.
+It may be overridden with your own
+function that takes the arguments specified above
+and returns a string of help text formatted to your liking.
+Note that the
+<emphasis remap='I'>GenerateHelpText</emphasis>()
+will not put any blank lines or extra
+characters in between the entries,
+so you must add those characters to the returned
+string if you want the entries separated.</para>
+
+<programlisting remap='.nf'>
+def my_format(env, opt, help, default, actual):
+    fmt = "\n%s: default=%s actual=%s (%s)\n"
+    return fmt % (opt, default. actual, help)
+vars.FormatVariableHelpText = my_format
+</programlisting> <!-- .fi -->
+
+<para>To make it more convenient to work with customizable Variables,
+<command>scons</command>
+provides a number of functions
+that make it easy to set up
+various types of Variables:</para>
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>BoolVariable(<emphasis remap='I'>key</emphasis>, <emphasis remap='I'>help</emphasis>, <emphasis remap='I'>default</emphasis>)</term>
+  <listitem>
+<para>Return a tuple of arguments
+to set up a Boolean option.
+The option will use
+the specified name
+<emphasis remap='I'>key</emphasis>,
+have a default value of
+<emphasis remap='I'>default</emphasis>,
+and display the specified
+<emphasis remap='I'>help</emphasis>
+text.
+The option will interpret the values
+<emphasis remap='B'>y</emphasis>,
+<emphasis remap='B'>yes</emphasis>,
+<emphasis remap='B'>t</emphasis>,
+<emphasis remap='B'>true</emphasis>,
+<literal>1</literal>,
+<emphasis remap='B'>on</emphasis>
+and
+<emphasis remap='B'>all</emphasis>
+as true,
+and the values
+<emphasis remap='B'>n</emphasis>,
+<emphasis remap='B'>no</emphasis>,
+<emphasis remap='B'>f</emphasis>,
+<emphasis remap='B'>false</emphasis>,
+<literal>0</literal>,
+<emphasis remap='B'>off</emphasis>
+and
+<emphasis remap='B'>none</emphasis>
+as false.</para>
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>EnumVariable(<emphasis remap='I'>key</emphasis>, <emphasis remap='I'>help</emphasis>, <emphasis remap='I'>default</emphasis>, <emphasis remap='I'>allowed_values</emphasis>, [<emphasis remap='I'>map</emphasis>, <emphasis remap='I'>ignorecase</emphasis>])</term>
+  <listitem>
+<para>Return a tuple of arguments
+to set up an option
+whose value may be one
+of a specified list of legal enumerated values.
+The option will use
+the specified name
+<emphasis remap='I'>key</emphasis>,
+have a default value of
+<emphasis remap='I'>default</emphasis>,
+and display the specified
+<emphasis remap='I'>help</emphasis>
+text.
+The option will only support those
+values in the
+<emphasis remap='I'>allowed_values</emphasis>
+list.
+The optional
+<emphasis remap='I'>map</emphasis>
+argument is a dictionary
+that can be used to convert
+input values into specific legal values
+in the
+<emphasis remap='I'>allowed_values</emphasis>
+list.
+If the value of
+<emphasis remap='I'>ignore_case</emphasis>
+is
+<literal>0</literal>
+(the default),
+then the values are case-sensitive.
+If the value of
+<emphasis remap='I'>ignore_case</emphasis>
+is
+<literal>1</literal>,
+then values will be matched
+case-insensitive.
+If the value of
+<emphasis remap='I'>ignore_case</emphasis>
+is
+<literal>1</literal>,
+then values will be matched
+case-insensitive,
+and all input values will be
+converted to lower case.</para>
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>ListVariable(<emphasis remap='I'>key</emphasis>, <emphasis remap='I'>help</emphasis>, <emphasis remap='I'>default</emphasis>, <emphasis remap='I'>names</emphasis>, [<emphasis remap='I'>,</emphasis>map<emphasis remap='I'>])</emphasis></term>
+  <listitem>
+<para>Return a tuple of arguments
+to set up an option
+whose value may be one or more
+of a specified list of legal enumerated values.
+The option will use
+the specified name
+<emphasis remap='I'>key</emphasis>,
+have a default value of
+<emphasis remap='I'>default</emphasis>,
+and display the specified
+<emphasis remap='I'>help</emphasis>
+text.
+The option will only support the values
+<emphasis remap='B'>all</emphasis>,
+<emphasis remap='B'>none</emphasis>,
+or the values in the
+<emphasis remap='I'>names</emphasis>
+list.
+More than one value may be specified,
+with all values separated by commas.
+The default may be a string of
+comma-separated default values,
+or a list of the default values.
+The optional
+<emphasis remap='I'>map</emphasis>
+argument is a dictionary
+that can be used to convert
+input values into specific legal values
+in the
+<emphasis remap='I'>names</emphasis>
+list.</para>
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>PackageVariable(<emphasis remap='I'>key</emphasis>, <emphasis remap='I'>help</emphasis>, <emphasis remap='I'>default</emphasis>)</term>
+  <listitem>
+<para>Return a tuple of arguments
+to set up an option
+whose value is a path name
+of a package that may be
+enabled, disabled or
+given an explicit path name.
+The option will use
+the specified name
+<emphasis remap='I'>key</emphasis>,
+have a default value of
+<emphasis remap='I'>default</emphasis>,
+and display the specified
+<emphasis remap='I'>help</emphasis>
+text.
+The option will support the values
+<emphasis remap='B'>yes</emphasis>,
+<emphasis remap='B'>true</emphasis>,
+<emphasis remap='B'>on</emphasis>,
+<emphasis remap='B'>enable</emphasis>
+or
+<emphasis remap='B'>search</emphasis>,
+in which case the specified
+<emphasis remap='I'>default</emphasis>
+will be used,
+or the option may be set to an
+arbitrary string
+(typically the path name to a package
+that is being enabled).
+The option will also support the values
+<emphasis remap='B'>no</emphasis>,
+<emphasis remap='B'>false</emphasis>,
+<emphasis remap='B'>off</emphasis>
+or
+<emphasis remap='B'>disable</emphasis>
+to disable use of the specified option.</para>
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>PathVariable(<emphasis remap='I'>key</emphasis>, <emphasis remap='I'>help</emphasis>, <emphasis remap='I'>default</emphasis>, [<emphasis remap='I'>validator</emphasis>])</term>
+  <listitem>
+<para>Return a tuple of arguments
+to set up an option
+whose value is expected to be a path name.
+The option will use
+the specified name
+<emphasis remap='I'>key</emphasis>,
+have a default value of
+<emphasis remap='I'>default</emphasis>,
+and display the specified
+<emphasis remap='I'>help</emphasis>
+text.
+An additional
+<emphasis remap='I'>validator</emphasis>
+may be specified
+that will be called to
+verify that the specified path
+is acceptable.
+SCons supplies the
+following ready-made validators:
+<emphasis remap='B'>PathVariable.PathExists</emphasis>
+(the default),
+which verifies that the specified path exists;
+<emphasis remap='B'>PathVariable.PathIsFile</emphasis>,
+which verifies that the specified path is an existing file;
+<emphasis remap='B'>PathVariable.PathIsDir</emphasis>,
+which verifies that the specified path is an existing directory;
+<emphasis remap='B'>PathVariable.PathIsDirCreate</emphasis>,
+which verifies that the specified path is a directory
+and will create the specified directory if the path does not exist;
+and
+<emphasis remap='B'>PathVariable.PathAccept</emphasis>,
+which simply accepts the specific path name argument without validation,
+and which is suitable if you want your users
+to be able to specify a directory path that will be
+created as part of the build process, for example.
+You may supply your own
+<emphasis remap='I'>validator</emphasis>
+function,
+which must take three arguments
+(<emphasis remap='I'>key</emphasis>,
+the name of the variable to be set;
+<emphasis remap='I'>val</emphasis>,
+the specified value being checked;
+and
+<emphasis remap='I'>env</emphasis>,
+the construction environment)
+and should raise an exception
+if the specified value is not acceptable.</para>
+
+  </listitem>
+  </varlistentry>
+</variablelist>
+<para>These functions make it
+convenient to create a number
+of variables with consistent behavior
+in a single call to the
+<emphasis remap='B'>AddVariables</emphasis>
+method:</para>
+
+<literallayout remap='.nf'>
+vars.AddVariables(
+    BoolVariable('warnings', 'compilation with -Wall and similiar', 1),
+    EnumVariable('debug', 'debug output and symbols', 'no'
+               allowed_values=('yes', 'no', 'full'),
+               map={}, ignorecase=0),  # case sensitive
+    ListVariable('shared',
+               'libraries to build as shared libraries',
+               'all',
+               names = list_of_libs),
+    PackageVariable('x11',
+                  'use X11 installed here (yes = search some places)',
+                  'yes'),
+    PathVariable('qtdir', 'where the root of Qt is installed', qtdir),
+    PathVariable('foopath', 'where the foo library is installed', foopath,
+               PathVariable.PathIsDir),
+
+)
+</literallayout> <!-- .fi -->
+
+</refsect2>
+
+<refsect2 id='file_and_directory_nodes'><title>File and Directory Nodes</title>
+
+<para>The
+<emphasis remap='I'>File</emphasis>()
+and
+<emphasis remap='I'>Dir</emphasis>()
+functions return
+<emphasis remap='I'>File</emphasis>
+and
+<emphasis remap='I'>Dir</emphasis>
+Nodes, respectively.
+python objects, respectively.
+Those objects have several user-visible attributes
+and methods that are often useful:</para>
+
+<variablelist remap='IP'>
+  <varlistentry>
+  <term>path</term>
+  <listitem>
+<para>The build path
+of the given
+file or directory.
+This path is relative to the top-level directory
+(where the
+<emphasis remap='B'>SConstruct</emphasis>
+file is found).
+The build path is the same as the source path if
+<emphasis remap='I'>variant_dir</emphasis>
+is not being used.</para>
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>abspath</term>
+  <listitem>
+<para>The absolute build path of the given file or directory.</para>
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>srcnode()</term>
+  <listitem>
+<para>The
+<emphasis remap='I'>srcnode</emphasis>()
+method
+returns another
+<emphasis remap='I'>File</emphasis>
+or
+<emphasis remap='I'>Dir</emphasis>
+object representing the
+<emphasis remap='I'>source</emphasis>
+path of the given
+<emphasis remap='I'>File</emphasis>
+or
+<emphasis remap='I'>Dir</emphasis>.
+The</para>
+
+<literallayout remap='.nf'>
+# Get the current build dir's path, relative to top.
+Dir('.').path
+# Current dir's absolute path
+Dir('.').abspath
+# Next line is always '.', because it is the top dir's path relative to itself.
+Dir('#.').path
+File('foo.c').srcnode().path   # source path of the given source file.
+
+# Builders also return File objects:
+foo = env.Program('foo.c')
+print "foo will be built in %s"%foo.path
+</literallayout> <!-- .fi -->
+
+<para>A
+<emphasis remap='I'>Dir</emphasis>
+Node or
+<emphasis remap='I'>File</emphasis>
+Node can also be used to create
+file and subdirectory Nodes relative to the generating Node.
+A
+<emphasis remap='I'>Dir</emphasis>
+Node will place the new Nodes within the directory it represents.
+A
+<emphasis remap='I'>File</emphasis>
+node will place the new Nodes within its parent directory
+(that is, "beside" the file in question).
+If
+<emphasis remap='I'>d</emphasis>
+is a
+<emphasis remap='I'>Dir</emphasis>
+(directory) Node and
+<emphasis remap='I'>f</emphasis>
+is a
+<emphasis remap='I'>File</emphasis>
+(file) Node,
+then these methods are available:</para>
+
+  </listitem>
+  </varlistentry>
+</variablelist>
+<variablelist remap='TP'>
+  <varlistentry>
+  <term><emphasis remap='I'>d</emphasis>.Dir(<emphasis remap='I'>name</emphasis>)</term>
+  <listitem>
+<para>Returns a directory Node for a subdirectory of
+<emphasis remap='I'>d</emphasis>
+named
+<emphasis remap='I'>name</emphasis>.</para>
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term><emphasis remap='I'>d</emphasis>.File(<emphasis remap='I'>name</emphasis>)</term>
+  <listitem>
+<para>Returns a file Node for a file within
+<emphasis remap='I'>d</emphasis>
+named
+<emphasis remap='I'>name</emphasis>.</para>
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term><emphasis remap='I'>d</emphasis>.Entry(<emphasis remap='I'>name</emphasis>)</term>
+  <listitem>
+<para>Returns an unresolved Node within
+<emphasis remap='I'>d</emphasis>
+named
+<emphasis remap='I'>name</emphasis>.</para>
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term><emphasis remap='I'>f</emphasis>.Dir(<emphasis remap='I'>name</emphasis>)</term>
+  <listitem>
+<para>Returns a directory named
+<emphasis remap='I'>name</emphasis>
+within the parent directory of
+<emphasis remap='I'>f</emphasis>.</para>
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term><emphasis remap='I'>f</emphasis>.File(<emphasis remap='I'>name</emphasis>)</term>
+  <listitem>
+<para>Returns a file named
+<emphasis remap='I'>name</emphasis>
+within the parent directory of
+<emphasis remap='I'>f</emphasis>.</para>
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term><emphasis remap='I'>f</emphasis>.Entry(<emphasis remap='I'>name</emphasis>)</term>
+  <listitem>
+<para>Returns an unresolved Node named
+<emphasis remap='I'>name</emphasis>
+within the parent directory of
+<emphasis remap='I'>f</emphasis>.</para>
+
+  </listitem>
+  </varlistentry>
+</variablelist>
+<para>For example:</para>
+
+<literallayout remap='.nf'>
+# Get a Node for a file within a directory
+incl = Dir('include')
+f = incl.File('header.h')
+
+# Get a Node for a subdirectory within a directory
+dist = Dir('project-3.2.1)
+src = dist.Dir('src')
+
+# Get a Node for a file in the same directory
+cfile = File('sample.c')
+hfile = cfile.File('sample.h')
+
+# Combined example
+docs = Dir('docs')
+html = docs.Dir('html')
+index = html.File('index.html')
+css = index.File('app.css')
+</literallayout> <!-- .fi -->
+
+</refsect2>
+</refsect1>
+
+<refsect1 id='extending_scons'><title>EXTENDING SCONS</title>
+
+<refsect2 id='builder_objects'><title>Builder Objects</title>
+<para><command>scons</command>
+can be extended to build different types of targets
+by adding new Builder objects
+to a construction environment.
+<emphasis remap='I'>In general</emphasis>,
+you should only need to add a new Builder object
+when you want to build a new type of file or other external target.
+If you just want to invoke a different compiler or other tool
+to build a Program, Object, Library, or any other
+type of output file for which
+<command>scons</command>
+already has an existing Builder,
+it is generally much easier to
+use those existing Builders
+in a construction environment
+that sets the appropriate construction variables
+(CC, LINK, etc.).</para>
+
+<para>Builder objects are created
+using the
+<emphasis remap='B'>Builder</emphasis>
+function.
+The
+<emphasis remap='B'>Builder</emphasis>
+function accepts the following arguments:</para>
+
+<variablelist remap='IP'>
+  <varlistentry>
+  <term>action</term>
+  <listitem>
+<para>The command line string used to build the target from the source.
+<emphasis remap='B'>action</emphasis>
+can also be:
+a list of strings representing the command
+to be executed and its arguments
+(suitable for enclosing white space in an argument),
+a dictionary
+mapping source file name suffixes to
+any combination of command line strings
+(if the builder should accept multiple source file extensions),
+a Python function;
+an Action object
+(see the next section);
+or a list of any of the above.</para>
+
+<para>An action function
+takes three arguments:
+<emphasis remap='I'>source</emphasis>
+- a list of source nodes,
+<emphasis remap='I'>target</emphasis>
+- a list of target nodes,
+<emphasis remap='I'>env</emphasis>
+- the construction environment.</para>
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>prefix</term>
+  <listitem>
+<para>The prefix that will be prepended to the target file name.
+This may be specified as a:</para>
+
+  <blockquote remap='RS'>
+
+<para>*
+<emphasis remap='I'>string</emphasis>,</para>
+
+
+<para>*
+<emphasis remap='I'>callable object</emphasis>
+- a function or other callable that takes
+two arguments (a construction environment and a list of sources)
+and returns a prefix,</para>
+
+
+<para>*
+<emphasis remap='I'>dictionary</emphasis>
+- specifies a mapping from a specific source suffix (of the first
+source specified) to a corresponding target prefix.  Both the source
+suffix and target prefix specifications may use environment variable
+substitution, and the target prefix (the 'value' entries in the
+dictionary) may also be a callable object.  The default target prefix
+may be indicated by a dictionary entry with a key value of None.
+    </para></blockquote> <!-- remap='RE' -->
+  </listitem>
+  </varlistentry>
+</variablelist>
+
+
+<programlisting remap='.nf'>
+b = Builder("build_it &lt; $SOURCE &gt; $TARGET",
+            prefix = "file-")
+
+def gen_prefix(env, sources):
+    return "file-" + env['PLATFORM'] + '-'
+b = Builder("build_it &lt; $SOURCE &gt; $TARGET",
+            prefix = gen_prefix)
+
+b = Builder("build_it &lt; $SOURCE &gt; $TARGET",
+            suffix = { None: "file-",
+                       "$SRC_SFX_A": gen_prefix })
+</programlisting> <!-- .fi -->
+
+<variablelist remap='IP'>
+  <varlistentry>
+  <term>suffix</term>
+  <listitem>
+<para>The suffix that will be appended to the target file name.
+This may be specified in the same manner as the prefix above.
+If the suffix is a string, then
+<command>scons</command>
+will append a '.' to the beginning of the suffix if it's not already
+there.  The string returned by callable object (or obtained from the
+dictionary) is untouched and must append its own '.'  to the beginning
+if one is desired.</para>
+
+<programlisting remap='.nf'>
+b = Builder("build_it &lt; $SOURCE &gt; $TARGET"
+            suffix = "-file")
+
+def gen_suffix(env, sources):
+    return "." + env['PLATFORM'] + "-file"
+b = Builder("build_it &lt; $SOURCE &gt; $TARGET",
+            suffix = gen_suffix)
+
+b = Builder("build_it &lt; $SOURCE &gt; $TARGET",
+            suffix = { None: ".sfx1",
+                       "$SRC_SFX_A": gen_suffix })
+</programlisting> <!-- .fi -->
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>ensure_suffix</term>
+  <listitem>
+<para>When set to any true value, causes
+<command>scons</command>
+to add the target suffix specified by the
+<emphasis remap='I'>suffix</emphasis>
+keyword to any target strings
+that have a different suffix.
+(The default behavior is to leave untouched
+any target file name that looks like it already has any suffix.)</para>
+
+<literallayout remap='.nf'>
+b1 = Builder("build_it &lt; $SOURCE &gt; $TARGET"
+             suffix = ".out")
+b2 = Builder("build_it &lt; $SOURCE &gt; $TARGET"
+             suffix = ".out",
+             ensure_suffix)
+env = Environment()
+env['BUILDERS']['B1'] = b1
+env['BUILDERS']['B2'] = b2
+
+# Builds "foo.txt" because ensure_suffix is not set.
+env.B1('foo.txt', 'foo.in')
+
+# Builds "bar.txt.out" because ensure_suffix is set.
+env.B2('bar.txt', 'bar.in')
+</literallayout> <!-- .fi -->
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>src_suffix</term>
+  <listitem>
+<para>The expected source file name suffix.  This may be a string or a list
+of strings.</para>
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>target_scanner</term>
+  <listitem>
+<para>A Scanner object that
+will be invoked to find
+implicit dependencies for this target file.
+This keyword argument should be used
+for Scanner objects that find
+implicit dependencies
+based only on the target file
+and the construction environment,
+<emphasis remap='I'>not</emphasis>
+for implicit dependencies based on source files.
+(See the section "Scanner Objects" below,
+for information about creating Scanner objects.)</para>
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>source_scanner</term>
+  <listitem>
+<para>A Scanner object that
+will be invoked to
+find implicit dependencies in
+any source files
+used to build this target file.
+This is where you would
+specify a scanner to
+find things like
+<emphasis remap='B'>#include</emphasis>
+lines in source files.
+The pre-built
+<emphasis remap='B'>DirScanner</emphasis>
+Scanner object may be used to
+indicate that this Builder
+should scan directory trees
+for on-disk changes to files
+that
+<command>scons</command>
+does not know about from other Builder or function calls.
+(See the section "Scanner Objects" below,
+for information about creating your own Scanner objects.)</para>
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>target_factory</term>
+  <listitem>
+<para>A factory function that the Builder will use
+to turn any targets specified as strings into SCons Nodes.
+By default,
+SCons assumes that all targets are files.
+Other useful target_factory
+values include
+<emphasis remap='B'>Dir</emphasis>,
+for when a Builder creates a directory target,
+and
+<emphasis remap='B'>Entry</emphasis>,
+for when a Builder can create either a file
+or directory target.</para>
+
+<para>Example:</para>
+
+<literallayout remap='.nf'>
+MakeDirectoryBuilder = Builder(action=my_mkdir, target_factory=Dir)
+env = Environment()
+env.Append(BUILDERS = {'MakeDirectory':MakeDirectoryBuilder})
+env.MakeDirectory('new_directory', [])
+</literallayout> <!-- .fi -->
+
+
+<para>Note that the call to the MakeDirectory Builder
+needs to specify an empty source list
+to make the string represent the builder's target;
+without that, it would assume the argument is the source,
+and would try to deduce the target name from it,
+which in the absence of an automatically-added prefix or suffix
+would lead to a matching target and source name
+and a circular dependency.</para>
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>source_factory</term>
+  <listitem>
+<para>A factory function that the Builder will use
+to turn any sources specified as strings into SCons Nodes.
+By default,
+SCons assumes that all source are files.
+Other useful source_factory
+values include
+<emphasis remap='B'>Dir</emphasis>,
+for when a Builder uses a directory as a source,
+and
+<emphasis remap='B'>Entry</emphasis>,
+for when a Builder can use files
+or directories (or both) as sources.</para>
+
+<para>Example:</para>
+
+<programlisting remap='.nf'>
+CollectBuilder = Builder(action=my_mkdir, source_factory=Entry)
+env = Environment()
+env.Append(BUILDERS = {'Collect':CollectBuilder})
+env.Collect('archive', ['directory_name', 'file_name'])
+</programlisting> <!-- .fi -->
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>emitter</term>
+  <listitem>
+<para>A function or list of functions to manipulate the target and source
+lists before dependencies are established
+and the target(s) are actually built.
+<emphasis remap='B'>emitter</emphasis>
+can also be a string containing a construction variable to expand
+to an emitter function or list of functions,
+or a dictionary mapping source file suffixes
+to emitter functions.
+(Only the suffix of the first source file
+is used to select the actual emitter function
+from an emitter dictionary.)</para>
+
+<para>An emitter function
+takes three arguments:
+<emphasis remap='I'>source</emphasis>
+- a list of source nodes,
+<emphasis remap='I'>target</emphasis>
+- a list of target nodes,
+<emphasis remap='I'>env</emphasis>
+- the construction environment.
+An emitter must return a tuple containing two lists,
+the list of targets to be built by this builder,
+and the list of sources for this builder.</para>
+
+<para>Example:</para>
+
+<programlisting remap='.nf'>
+def e(target, source, env):
+    return (target + ['foo.foo'], source + ['foo.src'])
+
+# Simple association of an emitter function with a Builder.
+b = Builder("my_build &lt; $TARGET &gt; $SOURCE",
+            emitter = e)
+
+def e2(target, source, env):
+    return (target + ['bar.foo'], source + ['bar.src'])
+
+# Simple association of a list of emitter functions with a Builder.
+b = Builder("my_build &lt; $TARGET &gt; $SOURCE",
+            emitter = [e, e2])
+
+# Calling an emitter function through a construction variable.
+env = Environment(MY_EMITTER = e)
+b = Builder("my_build &lt; $TARGET &gt; $SOURCE",
+            emitter = '$MY_EMITTER')
+
+# Calling a list of emitter functions through a construction variable.
+env = Environment(EMITTER_LIST = [e, e2])
+b = Builder("my_build &lt; $TARGET &gt; $SOURCE",
+            emitter = '$EMITTER_LIST')
+
+# Associating multiple emitters with different file
+# suffixes using a dictionary.
+def e_suf1(target, source, env):
+    return (target + ['another_target_file'], source)
+def e_suf2(target, source, env):
+    return (target, source + ['another_source_file'])
+b = Builder("my_build &lt; $TARGET &gt; $SOURCE",
+            emitter = {'.suf1' : e_suf1,
+                       '.suf2' : e_suf2})
+</programlisting> <!-- .fi -->
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>multi</term>
+  <listitem>
+<para>Specifies whether this builder is allowed to be called multiple times for
+the same target file(s). The default is 0, which means the builder
+can not be called multiple times for the same target file(s). Calling a
+builder multiple times for the same target simply adds additional source
+files to the target; it is not allowed to change the environment associated
+with the target, specify addition environment overrides, or associate a different
+builder with the target.</para>
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>env</term>
+  <listitem>
+<para>A construction environment that can be used
+to fetch source code using this Builder.
+(Note that this environment is
+<emphasis remap='I'>not</emphasis>
+used for normal builds of normal target files,
+which use the environment that was
+used to call the Builder for the target file.)</para>
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>generator</term>
+  <listitem>
+<para>A function that returns a list of actions that will be executed to build
+the target(s) from the source(s).
+The returned action(s) may be
+an Action object, or anything that
+can be converted into an Action object
+(see the next section).</para>
+
+<para>The generator function
+takes four arguments:
+<emphasis remap='I'>source</emphasis>
+- a list of source nodes,
+<emphasis remap='I'>target</emphasis>
+- a list of target nodes,
+<emphasis remap='I'>env</emphasis>
+- the construction environment,
+<emphasis remap='I'>for_signature</emphasis>
+- a Boolean value that specifies
+whether the generator is being called
+for generating a build signature
+(as opposed to actually executing the command).
+Example:</para>
+
+<programlisting remap='.nf'>
+def g(source, target, env, for_signature):
+    return [["gcc", "-c", "-o"] + target + source]
+
+b = Builder(generator=g)
+</programlisting> <!-- .fi -->
+
+
+<para>The
+<emphasis remap='I'>generator</emphasis>
+and
+<emphasis remap='I'>action</emphasis>
+arguments must not both be used for the same Builder.</para>
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>src_builder</term>
+  <listitem>
+<para>Specifies a builder to use when a source file name suffix does not match
+any of the suffixes of the builder. Using this argument produces a
+multi-stage builder.</para>
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>single_source</term>
+  <listitem>
+<para>Specifies that this builder expects exactly one source file per call. Giving
+more than one source file without target files results in implicitely calling
+the builder multiple times (once for each source given). Giving multiple
+source files together with target files results in a UserError exception.</para>
+
+  </listitem>
+  </varlistentry>
+</variablelist>
+
+<para>The
+<emphasis remap='I'>generator</emphasis>
+and
+<emphasis remap='I'>action</emphasis>
+arguments must not both be used for the same Builder.</para>
+
+<variablelist remap='IP'>
+  <varlistentry>
+  <term>source_ext_match</term>
+  <listitem>
+<para>When the specified
+<emphasis remap='I'>action</emphasis>
+argument is a dictionary,
+the default behavior when a builder is passed
+multiple source files is to make sure that the
+extensions of all the source files match.
+If it is legal for this builder to be
+called with a list of source files with different extensions,
+this check can be suppressed by setting
+<emphasis remap='B'>source_ext_match</emphasis>
+to
+<emphasis remap='B'>None</emphasis>
+or some other non-true value.
+When
+<emphasis remap='B'>source_ext_match</emphasis>
+is disable,
+<command>scons</command>
+will use the suffix of the first specified
+source file to select the appropriate action from the
+<emphasis remap='I'>action</emphasis>
+dictionary.</para>
+
+<para>In the following example,
+the setting of
+<emphasis remap='B'>source_ext_match</emphasis>
+prevents
+<command>scons</command>
+from exiting with an error
+due to the mismatched suffixes of
+<emphasis remap='B'>foo.in</emphasis>
+and
+<emphasis remap='B'>foo.extra</emphasis>.</para>
+
+<literallayout remap='.nf'>
+b = Builder(action={'.in' : 'build $SOURCES &gt; $TARGET'},
+            source_ext_match = None)
+
+env = Environment(BUILDERS = {'MyBuild':b})
+env.MyBuild('foo.out', ['foo.in', 'foo.extra'])
+</literallayout> <!-- .fi -->
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>env</term>
+  <listitem>
+<para>A construction environment that can be used
+to fetch source code using this Builder.
+(Note that this environment is
+<emphasis remap='I'>not</emphasis>
+used for normal builds of normal target files,
+which use the environment that was
+used to call the Builder for the target file.)</para>
+
+<literallayout remap='.nf'>
+b = Builder(action="build &lt; $SOURCE &gt; $TARGET")
+env = Environment(BUILDERS = {'MyBuild' : b})
+env.MyBuild('foo.out', 'foo.in', my_arg = 'xyzzy')
+</literallayout> <!-- .fi -->
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>chdir</term>
+  <listitem>
+<para>A directory from which scons
+will execute the
+action(s) specified
+for this Builder.
+If the
+<emphasis remap='B'>chdir</emphasis>
+argument is
+a string or a directory Node,
+scons will change to the specified directory.
+If the
+<emphasis remap='B'>chdir</emphasis>
+is not a string or Node
+and is non-zero,
+then scons will change to the
+target file's directory.</para>
+
+<para>Note that scons will
+<emphasis remap='I'>not</emphasis>
+automatically modify
+its expansion of
+construction variables like
+<emphasis remap='B'>$TARGET</emphasis>
+and
+<emphasis remap='B'>$SOURCE</emphasis>
+when using the chdir
+keyword argument--that is,
+the expanded file names
+will still be relative to
+the top-level SConstruct directory,
+and consequently incorrect
+relative to the chdir directory.
+Builders created using chdir keyword argument,
+will need to use construction variable
+expansions like
+<emphasis remap='B'>${TARGET.file}</emphasis>
+and
+<emphasis remap='B'>${SOURCE.file}</emphasis>
+to use just the filename portion of the
+targets and source.</para>
+
+<literallayout remap='.nf'>
+b = Builder(action="build &lt; ${SOURCE.file} &gt; ${TARGET.file}",
+            chdir=1)
+env = Environment(BUILDERS = {'MyBuild' : b})
+env.MyBuild('sub/dir/foo.out', 'sub/dir/foo.in')
+</literallayout> <!-- .fi -->
+
+<para><emphasis remap='B'>WARNING:</emphasis>
+Python only keeps one current directory
+location for all of the threads.
+This means that use of the
+<emphasis remap='B'>chdir</emphasis>
+argument
+will
+<emphasis remap='I'>not</emphasis>
+work with the SCons
+<option>-j</option>
+option,
+because individual worker threads spawned
+by SCons interfere with each other
+when they start changing directory.</para>
+
+  </listitem>
+  </varlistentry>
+</variablelist>
+<para>Any additional keyword arguments supplied
+when a Builder object is created
+(that is, when the Builder() function is called)
+will be set in the executing construction
+environment when the Builder object is called.
+The canonical example here would be
+to set a construction variable to
+the repository of a source code system.</para>
+
+<para>Any additional keyword arguments supplied
+when a Builder
+<emphasis remap='I'>object</emphasis>
+is called
+will only be associated with the target
+created by that particular Builder call
+(and any other files built as a
+result of the call).</para>
+
+<para>These extra keyword arguments are passed to the
+following functions:
+command generator functions,
+function Actions,
+and emitter functions.</para>
+
+</refsect2>
+
+<refsect2 id='action_objects'><title>Action Objects</title>
+
+<para>The
+<emphasis remap='B'>Builder</emphasis>()
+function will turn its
+<emphasis remap='B'>action</emphasis>
+keyword argument into an appropriate
+internal Action object.
+You can also explicity create Action objects
+using the
+<emphasis remap='B'>Action</emphasis>()
+global function,
+which can then be passed to the
+<emphasis remap='B'>Builder</emphasis>()
+function.
+This can be used to configure
+an Action object more flexibly,
+or it may simply be more efficient
+than letting each separate Builder object
+create a separate Action
+when multiple
+Builder objects need to do the same thing.</para>
+
+<para>The
+<emphasis remap='B'>Action</emphasis>()
+global function
+returns an appropriate object for the action
+represented by the type of the first argument:</para>
+
+<variablelist remap='IP'>
+  <varlistentry>
+  <term>Action</term>
+  <listitem>
+<para>If the first argument is already an Action object,
+the object is simply returned.</para>
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>String</term>
+  <listitem>
+<para>If the first argument is a string,
+a command-line Action is returned.
+Note that the command-line string
+may be preceded by an
+<emphasis remap='B'>@</emphasis>
+(at-sign)
+to suppress printing of the specified command line,
+or by a
+<emphasis remap='B'>-</emphasis>
+(hyphen)
+to ignore the exit status from the specified command:</para>
+
+<literallayout remap='.nf'>
+Action('$CC -c -o $TARGET $SOURCES')
+
+# Doesn't print the line being executed.
+Action('@build $TARGET $SOURCES')
+
+# Ignores return value
+Action('-build $TARGET $SOURCES')
+</literallayout> <!-- .fi -->
+<!--  XXX From Gary Ruben, 23 April 2002: -->
+<!--  What would be useful is a discussion of how you execute command -->
+<!--  shell commands ie. what is the process used to spawn the shell, pass -->
+<!--  environment variables to it etc., whether there is one shell per -->
+<!--  environment or one per command etc.  It might help to look at the Gnu -->
+<!--  make documentation to see what they think is important to discuss about -->
+<!--  a build system. I'm sure you can do a better job of organising the -->
+<!--  documentation than they have :\-) -->
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>List</term>
+  <listitem>
+<para>If the first argument is a list,
+then a list of Action objects is returned.
+An Action object is created as necessary
+for each element in the list.
+If an element
+<emphasis remap='I'>within</emphasis>
+the list is itself a list,
+the internal list is the
+command and arguments to be executed via
+the command line.
+This allows white space to be enclosed
+in an argument by defining
+a command in a list within a list:</para>
+
+<literallayout remap='.nf'>
+Action([['cc', '-c', '-DWHITE SPACE', '-o', '$TARGET', '$SOURCES']])
+</literallayout> <!-- .fi -->
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>Function</term>
+  <listitem>
+<para>If the first argument is a Python function,
+a function Action is returned.
+The Python function must take three keyword arguments,
+<emphasis remap='B'>target</emphasis>
+(a Node object representing the target file),
+<emphasis remap='B'>source</emphasis>
+(a Node object representing the source file)
+and
+<emphasis remap='B'>env</emphasis>
+(the construction environment
+used for building the target file).
+The
+<emphasis remap='B'>target</emphasis>
+and
+<emphasis remap='B'>source</emphasis>
+arguments may be lists of Node objects if there is
+more than one target file or source file.
+The actual target and source file name(s) may
+be retrieved from their Node objects
+via the built-in Python str() function:</para>
+
+<literallayout remap='.nf'>
+target_file_name = str(target)
+source_file_names = map(lambda x: str(x), source)
+</literallayout> <!-- .fi -->
+
+<para>The function should return
+<literal>0</literal>
+or
+<emphasis remap='B'>None</emphasis>
+to indicate a successful build of the target file(s).
+The function may raise an exception
+or return a non-zero exit status
+to indicate an unsuccessful build.</para>
+
+<programlisting remap='.nf'>
+def build_it(target = None, source = None, env = None):
+    # build the target from the source
+    return 0
+
+a = Action(build_it)
+</programlisting> <!-- .fi -->
+
+<para>If the action argument is not one of the above,
+None is returned.</para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+
+
+<para>The second argument is optional and is used to define the output
+which is printed when the Action is actually performed.
+In the absence of this parameter,
+or if it's an empty string,
+a default output depending on the type of the action is used.
+For example, a command-line action will print the executed command.
+The argument must be either a Python function or a string.</para>
+
+<para>In the first case,
+it's a function that returns a string to be printed
+to describe the action being executed.
+The function may also be specified by the
+<emphasis remap='I'>strfunction</emphasis>=
+keyword argument.
+Like a function to build a file,
+this function must take three keyword arguments:
+<emphasis remap='B'>target</emphasis>
+(a Node object representing the target file),
+<emphasis remap='B'>source</emphasis>
+(a Node object representing the source file)
+and
+<emphasis remap='B'>env</emphasis>
+(a construction environment).
+The
+<emphasis remap='B'>target</emphasis>
+and
+<emphasis remap='B'>source</emphasis>
+arguments may be lists of Node objects if there is
+more than one target file or source file.</para>
+
+<para>In the second case, you provide the string itself.
+The string may also be specified by the
+<emphasis remap='I'>cmdstr</emphasis>=
+keyword argument.
+The string typically contains variables, notably
+$TARGET(S) and $SOURCE(S), or consists of just a single
+variable, which is optionally defined somewhere else.
+SCons itself heavily uses the latter variant.</para>
+
+<para>Examples:</para>
+
+<programlisting remap='.nf'>
+def build_it(target, source, env):
+    # build the target from the source
+    return 0
+
+def string_it(target, source, env):
+    return "building '%s' from '%s'" % (target[0], source[0])
+
+# Use a positional argument.
+f = Action(build_it, string_it)
+s = Action(build_it, "building '$TARGET' from '$SOURCE'")
+
+# Alternatively, use a keyword argument.
+f = Action(build_it, strfunction=string_it)
+s = Action(build_it, cmdstr="building '$TARGET' from '$SOURCE'")
+
+# You can provide a configurable variable.
+l = Action(build_it, '$STRINGIT')
+</programlisting> <!-- .fi -->
+
+<para>The third and succeeding arguments, if present,
+may either be a construction variable or a list of construction variables
+whose values will be included in the signature of the Action
+when deciding whether a target should be rebuilt because the action changed.
+The variables may also be specified by a
+<emphasis remap='I'>varlist</emphasis>=
+keyword parameter;
+if both are present, they are combined.
+This is necessary whenever you want a target to be rebuilt
+when a specific construction variable changes.
+This is not often needed for a string action,
+as the expanded variables will normally be part of the command line,
+but may be needed if a Python function action uses
+the value of a construction variable when generating the command line.</para>
+
+<programlisting remap='.nf'>
+def build_it(target, source, env):
+    # build the target from the 'XXX' construction variable
+    open(target[0], 'w').write(env['XXX'])
+    return 0
+
+# Use positional arguments.
+a = Action(build_it, '$STRINGIT', ['XXX'])
+
+# Alternatively, use a keyword argument.
+a = Action(build_it, varlist=['XXX'])
+</programlisting> <!-- .fi -->
+
+<para>The
+<emphasis remap='B'>Action</emphasis>()
+global function
+can be passed the following
+optional keyword arguments
+to modify the Action object's behavior:</para>
+
+
+<para><emphasis remap='B'>chdir</emphasis>
+The
+<emphasis remap='B'>chdir</emphasis>
+keyword argument specifies that
+scons will execute the action
+after changing to the specified directory.
+If the
+<emphasis remap='B'>chdir</emphasis>
+argument is
+a string or a directory Node,
+scons will change to the specified directory.
+If the
+<emphasis remap='B'>chdir</emphasis>
+argument
+is not a string or Node
+and is non-zero,
+then scons will change to the
+target file's directory.</para>
+
+<para>Note that scons will
+<emphasis remap='I'>not</emphasis>
+automatically modify
+its expansion of
+construction variables like
+<emphasis remap='B'>$TARGET</emphasis>
+and
+<emphasis remap='B'>$SOURCE</emphasis>
+when using the chdir
+keyword argument--that is,
+the expanded file names
+will still be relative to
+the top-level SConstruct directory,
+and consequently incorrect
+relative to the chdir directory.
+Builders created using chdir keyword argument,
+will need to use construction variable
+expansions like
+<emphasis remap='B'>${TARGET.file}</emphasis>
+and
+<emphasis remap='B'>${SOURCE.file}</emphasis>
+to use just the filename portion of the
+targets and source.</para>
+
+<literallayout remap='.nf'>
+a = Action("build &lt; ${SOURCE.file} &gt; ${TARGET.file}",
+           chdir=1)
+</literallayout> <!-- .fi -->
+
+
+<para><emphasis remap='B'>exitstatfunc</emphasis>
+The
+<emphasis remap='B'>Action</emphasis>()
+global function
+also takes an
+<emphasis remap='B'>exitstatfunc</emphasis>
+keyword argument
+which specifies a function
+that is passed the exit status
+(or return value)
+from the specified action
+and can return an arbitrary
+or modified value.
+This can be used, for example,
+to specify that an Action object's
+return value should be ignored
+under special conditions
+and SCons should, therefore,
+consider that the action always suceeds:</para>
+
+<programlisting remap='.nf'>
+def always_succeed(s):
+    # Always return 0, which indicates success.
+    return 0
+a = Action("build &lt; ${SOURCE.file} &gt; ${TARGET.file}",
+           exitstatfunc=always_succeed)
+</programlisting> <!-- .fi -->
+
+
+<para><emphasis remap='B'>batch_key</emphasis>
+The
+<emphasis remap='B'>batch_key</emphasis>
+keyword argument can be used
+to specify that the Action can create multiple target files
+by processing multiple independent source files simultaneously.
+(The canonical example is "batch compilation"
+of multiple object files
+by passing multiple source files
+to a single invocation of a compiler
+such as Microsoft's Visual C / C++ compiler.)
+If the
+<emphasis remap='B'>batch_key</emphasis>
+argument is any non-False, non-callable Python value,
+the configured Action object will cause
+<command>scons</command>
+to collect all targets built with the Action object
+and configured with the same construction environment
+into single invocations of the Action object's
+command line or function.
+Command lines will typically want to use the
+<emphasis remap='B'>CHANGED_SOURCES</emphasis>
+construction variable
+(and possibly
+<emphasis remap='B'>CHANGED_TARGETS</emphasis>
+as well)
+to only pass to the command line those sources that
+have actually changed since their targets were built.</para>
+
+<para>Example:</para>
+
+<literallayout remap='.nf'>
+a = Action('build $CHANGED_SOURCES', batch_key=True)
+</literallayout> <!-- .fi -->
+
+<para>The
+<emphasis remap='B'>batch_key</emphasis>
+argument may also be
+a callable function
+that returns a key that
+will be used to identify different
+"batches" of target files to be collected
+for batch building.
+A
+<emphasis remap='B'>batch_key</emphasis>
+function must take the following arguments:</para>
+
+<variablelist remap='IP'>
+  <varlistentry>
+  <term>action</term>
+  <listitem>
+<para>The action object.</para>
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>env</term>
+  <listitem>
+<para>The construction environment
+configured for the target.</para>
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>target</term>
+  <listitem>
+<para>The list of targets for a particular configured action.</para>
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>source</term>
+  <listitem>
+<para>The list of source for a particular configured action.</para>
+
+<para>The returned key should typically
+be a tuple of values derived from the arguments,
+using any appropriate logic to decide
+how multiple invocations should be batched.
+For example, a
+<emphasis remap='B'>batch_key</emphasis>
+function may decide to return
+the value of a specific construction
+variable from the
+<emphasis remap='B'>env</emphasis>
+argument
+which will cause
+<command>scons</command>
+to batch-build targets
+with matching values of that variable,
+or perhaps return the
+<emphasis remap='B'>id</emphasis>()
+of the entire construction environment,
+in which case
+<command>scons</command>
+will batch-build
+all targets configured with the same construction environment.
+Returning
+<emphasis remap='B'>None</emphasis>
+indicates that
+the particular target should
+<emphasis remap='I'>not</emphasis>
+be part of any batched build,
+but instead will be built
+by a separate invocation of action's
+command or function.
+Example:</para>
+
+<programlisting remap='.nf'>
+def batch_key(action, env, target, source):
+    tdir = target[0].dir
+    if tdir.name == 'special':
+        # Don't batch-build any target
+        # in the special/ subdirectory.
+        return None
+    return (id(action), id(env), tdir)
+a = Action('build $CHANGED_SOURCES', batch_key=batch_key)
+</programlisting> <!-- .fi -->
+
+  </listitem>
+  </varlistentry>
+</variablelist>
+</refsect2>
+
+<refsect2 id='miscellaneous_action_functions'><title>Miscellaneous Action Functions</title>
+
+<para><command>scons</command>
+supplies a number of functions
+that arrange for various common
+file and directory manipulations
+to be performed.
+These are similar in concept to "tasks" in the
+Ant build tool,
+although the implementation is slightly different.
+These functions do not actually
+perform the specified action
+at the time the function is called,
+but instead return an Action object
+that can be executed at the
+appropriate time.
+(In Object-Oriented terminology,
+these are actually
+Action
+<emphasis remap='I'>Factory</emphasis>
+functions
+that return Action objects.)</para>
+
+<para>In practice,
+there are two natural ways
+that these
+Action Functions
+are intended to be used.</para>
+
+<para>First,
+if you need
+to perform the action
+at the time the SConscript
+file is being read,
+you can use the
+<emphasis remap='B'>Execute</emphasis>
+global function to do so:</para>
+<literallayout remap='.nf'>
+Execute(Touch('file'))
+</literallayout> <!-- .fi -->
+
+<para>Second,
+you can use these functions
+to supply Actions in a list
+for use by the
+<emphasis remap='B'>Command</emphasis>
+method.
+This can allow you to
+perform more complicated
+sequences of file manipulation
+without relying
+on platform-specific
+external commands:
+that</para>
+<literallayout remap='.nf'>
+env = Environment(TMPBUILD = '/tmp/builddir')
+env.Command('foo.out', 'foo.in',
+            [Mkdir('$TMPBUILD'),
+             Copy('$TMPBUILD', '${SOURCE.dir}'),
+             "cd $TMPBUILD &amp;&amp; make",
+             Delete('$TMPBUILD')])
+</literallayout> <!-- .fi -->
+
+<variablelist remap='TP'>
+  <varlistentry>
+  <term>Chmod(<emphasis remap='I'>dest</emphasis>, <emphasis remap='I'>mode</emphasis>)</term>
+  <listitem>
+<para>Returns an Action object that
+changes the permissions on the specified
+<emphasis remap='I'>dest</emphasis>
+file or directory to the specified
+<emphasis remap='I'>mode</emphasis>.
+Examples:</para>
+
+<literallayout remap='.nf'>
+Execute(Chmod('file', 0755))
+
+env.Command('foo.out', 'foo.in',
+            [Copy('$TARGET', '$SOURCE'),
+             Chmod('$TARGET', 0755)])
+</literallayout> <!-- .fi -->
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>Copy(<emphasis remap='I'>dest</emphasis>, <emphasis remap='I'>src</emphasis>)</term>
+  <listitem>
+<para>Returns an Action object
+that will copy the
+<emphasis remap='I'>src</emphasis>
+source file or directory to the
+<emphasis remap='I'>dest</emphasis>
+destination file or directory.
+Examples:</para>
+
+<literallayout remap='.nf'>
+Execute(Copy('foo.output', 'foo.input'))
+
+env.Command('bar.out', 'bar.in',
+            Copy('$TARGET', '$SOURCE'))
+</literallayout> <!-- .fi -->
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>Delete(<emphasis remap='I'>entry</emphasis>, [<emphasis remap='I'>must_exist</emphasis>])</term>
+  <listitem>
+<para>Returns an Action that
+deletes the specified
+<emphasis remap='I'>entry</emphasis>,
+which may be a file or a directory tree.
+If a directory is specified,
+the entire directory tree
+will be removed.
+If the
+<emphasis remap='I'>must_exist</emphasis>
+flag is set,
+then a Python error will be thrown
+if the specified entry does not exist;
+the default is
+<emphasis remap='B'>must_exist=0</emphasis>,
+that is, the Action will silently do nothing
+if the entry does not exist.
+Examples:</para>
+
+<literallayout remap='.nf'>
+Execute(Delete('/tmp/buildroot'))
+
+env.Command('foo.out', 'foo.in',
+            [Delete('${TARGET.dir}'),
+             MyBuildAction])
+
+Execute(Delete('file_that_must_exist', must_exist=1))
+</literallayout> <!-- .fi -->
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>Mkdir(<emphasis remap='I'>dir</emphasis>)</term>
+  <listitem>
+<para>Returns an Action
+that creates the specified
+directory
+<emphasis remap='I'>dir .</emphasis>
+Examples:</para>
+
+<literallayout remap='.nf'>
+Execute(Mkdir('/tmp/outputdir'))
+
+env.Command('foo.out', 'foo.in',
+            [Mkdir('/tmp/builddir'),
+             Copy('/tmp/builddir/foo.in', '$SOURCE'),
+             "cd /tmp/builddir &amp;&amp; make",
+             Copy('$TARGET', '/tmp/builddir/foo.out')])
+</literallayout> <!-- .fi -->
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>Move(<emphasis remap='I'>dest</emphasis>, <emphasis remap='I'>src</emphasis>)</term>
+  <listitem>
+<para>Returns an Action
+that moves the specified
+<emphasis remap='I'>src</emphasis>
+file or directory to
+the specified
+<emphasis remap='I'>dest</emphasis>
+file or directory.
+Examples:</para>
+
+<literallayout remap='.nf'>
+Execute(Move('file.destination', 'file.source'))
+
+env.Command('output_file', 'input_file',
+            [MyBuildAction,
+             Move('$TARGET', 'file_created_by_MyBuildAction')])
+</literallayout> <!-- .fi -->
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>Touch(<emphasis remap='I'>file</emphasis>)</term>
+  <listitem>
+<para>Returns an Action
+that updates the modification time
+on the specified
+<emphasis remap='I'>file</emphasis>.
+Examples:</para>
+
+<literallayout remap='.nf'>
+Execute(Touch('file_to_be_touched'))
+
+env.Command('marker', 'input_file',
+            [MyBuildAction,
+             Touch('$TARGET')])
+</literallayout> <!-- .fi -->
+
+  </listitem>
+  </varlistentry>
+</variablelist>
+</refsect2>
+
+<refsect2 id='variable_substitution'><title>Variable Substitution</title>
+
+<para>Before executing a command,
+<command>scons</command>
+performs construction variable interpolation on the strings that make up
+the command line of builders.
+Variables are introduced by a
+<emphasis remap='B'>$</emphasis>
+prefix.
+Besides construction variables, scons provides the following
+variables for each command execution:</para>
+
+<variablelist remap='IP'>
+  <varlistentry>
+  <term>CHANGED_SOURCES</term>
+  <listitem>
+<para>The file names of all sources of the build command
+that have changed since the target was last built.</para>
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>CHANGED_TARGETS</term>
+  <listitem>
+<para>The file names of all targets that would be built
+from sources that have changed since the target was last built.</para>
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>SOURCE</term>
+  <listitem>
+<para>The file name of the source of the build command,
+or the file name of the first source
+if multiple sources are being built.</para>
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>SOURCES</term>
+  <listitem>
+<para>The file names of the sources of the build command.</para>
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>TARGET</term>
+  <listitem>
+<para>The file name of the target being built,
+or the file name of the first target
+if multiple targets are being built.</para>
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>TARGETS</term>
+  <listitem>
+<para>The file names of all targets being built.</para>
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>UNCHANGED_SOURCES</term>
+  <listitem>
+<para>The file names of all sources of the build command
+that have
+<emphasis remap='I'>not</emphasis>
+changed since the target was last built.</para>
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>UNCHANGED_TARGETS</term>
+  <listitem>
+<para>The file names of all targets that would be built
+from sources that have
+<emphasis remap='I'>not</emphasis>
+changed since the target was last built.</para>
+
+<para>(Note that the above variables are reserved
+and may not be set in a construction environment.)</para>
+
+  </listitem>
+  </varlistentry>
+</variablelist>
+
+<para>For example, given the construction variable CC='cc', targets=['foo'], and
+sources=['foo.c', 'bar.c']:</para>
+
+<literallayout remap='.nf'>
+action='$CC -c -o $TARGET $SOURCES'
+</literallayout> <!-- .fi -->
+
+<para>would produce the command line:</para>
+
+<literallayout remap='.nf'>
+cc -c -o foo foo.c bar.c
+</literallayout> <!-- .fi -->
+
+<para>Variable names may be surrounded by curly braces ({})
+to separate the name from the trailing characters.
+Within the curly braces, a variable name may have
+a Python slice subscript appended to select one
+or more items from a list.
+In the previous example, the string:</para>
+
+<literallayout remap='.nf'>
+${SOURCES[1]}
+</literallayout> <!-- .fi -->
+
+<para>would produce:</para>
+
+<literallayout remap='.nf'>
+bar.c
+</literallayout> <!-- .fi -->
+
+<para>Additionally, a variable name may
+have the following special
+modifiers appended within the enclosing curly braces
+to modify the interpolated string:</para>
+
+<variablelist remap='IP'>
+  <varlistentry>
+  <term>base</term>
+  <listitem>
+<para>The base path of the file name,
+including the directory path
+but excluding any suffix.</para>
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>dir</term>
+  <listitem>
+<para>The name of the directory in which the file exists.</para>
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>file</term>
+  <listitem>
+<para>The file name,
+minus any directory portion.</para>
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>filebase</term>
+  <listitem>
+<para>Just the basename of the file,
+minus any suffix
+and minus the directory.</para>
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>suffix</term>
+  <listitem>
+<para>Just the file suffix.</para>
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>abspath</term>
+  <listitem>
+<para>The absolute path name of the file.</para>
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>posix</term>
+  <listitem>
+<para>The POSIX form of the path,
+with directories separated by
+<emphasis remap='B'>/</emphasis>
+(forward slashes)
+not backslashes.
+This is sometimes necessary on Windows systems
+when a path references a file on other (POSIX) systems.</para>
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>srcpath</term>
+  <listitem>
+<para>The directory and file name to the source file linked to this file through
+<emphasis remap='B'>VariantDir</emphasis>().
+If this file isn't linked,
+it just returns the directory and filename unchanged.</para>
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>srcdir</term>
+  <listitem>
+<para>The directory containing the source file linked to this file through
+<emphasis remap='B'>VariantDir</emphasis>().
+If this file isn't linked,
+it just returns the directory part of the filename.</para>
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>rsrcpath</term>
+  <listitem>
+<para>The directory and file name to the source file linked to this file through
+<emphasis remap='B'>VariantDir</emphasis>().
+If the file does not exist locally but exists in a Repository,
+the path in the Repository is returned.
+If this file isn't linked, it just returns the
+directory and filename unchanged.</para>
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>rsrcdir</term>
+  <listitem>
+<para>The Repository directory containing the source file linked to this file through
+<emphasis remap='B'>VariantDir</emphasis>().
+If this file isn't linked,
+it just returns the directory part of the filename.</para>
+
+  </listitem>
+  </varlistentry>
+</variablelist>
+
+<para>For example, the specified target will
+expand as follows for the corresponding modifiers:</para>
+
+<literallayout remap='.nf'>
+$TARGET              =&gt; sub/dir/file.x
+${TARGET.base}       =&gt; sub/dir/file
+${TARGET.dir}        =&gt; sub/dir
+${TARGET.file}       =&gt; file.x
+${TARGET.filebase}   =&gt; file
+${TARGET.suffix}     =&gt; .x
+${TARGET.abspath}    =&gt; /top/dir/sub/dir/file.x
+
+SConscript('src/SConscript', variant_dir='sub/dir')
+$SOURCE              =&gt; sub/dir/file.x
+${SOURCE.srcpath}    =&gt; src/file.x
+${SOURCE.srcdir}     =&gt; src
+
+Repository('/usr/repository')
+$SOURCE              =&gt; sub/dir/file.x
+${SOURCE.rsrcpath}   =&gt; /usr/repository/src/file.x
+${SOURCE.rsrcdir}    =&gt; /usr/repository/src
+</literallayout> <!-- .fi -->
+
+<para>Note that curly braces braces may also be used
+to enclose arbitrary Python code to be evaluated.
+(In fact, this is how the above modifiers are substituted,
+they are simply attributes of the Python objects
+that represent TARGET, SOURCES, etc.)
+See the section "Python Code Substitution" below,
+for more thorough examples of
+how this can be used.</para>
+
+<para>Lastly, a variable name
+may be a callable Python function
+associated with a
+construction variable in the environment.
+The function should
+take four arguments:
+<emphasis remap='I'>target</emphasis>
+- a list of target nodes,
+<emphasis remap='I'>source</emphasis>
+- a list of source nodes,
+<emphasis remap='I'>env</emphasis>
+- the construction environment,
+<emphasis remap='I'>for_signature</emphasis>
+- a Boolean value that specifies
+whether the function is being called
+for generating a build signature.
+SCons will insert whatever
+the called function returns
+into the expanded string:</para>
+
+<programlisting remap='.nf'>
+def foo(target, source, env, for_signature):
+    return "bar"
+
+# Will expand $BAR to "bar baz"
+env=Environment(FOO=foo, BAR="$FOO baz")
+</programlisting> <!-- .fi -->
+
+<para>You can use this feature to pass arguments to a
+Python function by creating a callable class
+that stores one or more arguments in an object,
+and then uses them when the
+<function>__call__()</function>
+method is called.
+Note that in this case,
+the entire variable expansion must
+be enclosed by curly braces
+so that the arguments will
+be associated with the
+instantiation of the class:</para>
+
+<literallayout remap='.nf'>
+class foo(object):
+    def __init__(self, arg):
+        self.arg = arg
+
+    def __call__(self, target, source, env, for_signature):
+        return self.arg + " bar"
+
+# Will expand $BAR to "my argument bar baz"
+env=Environment(FOO=foo, BAR="${FOO('my argument')} baz")
+</literallayout> <!-- .fi -->
+
+
+<para>The special pseudo-variables
+<emphasis remap='B'>$(</emphasis>
+and
+<emphasis remap='B'>$)</emphasis>
+may be used to surround parts of a command line
+that may change
+<emphasis remap='I'>without</emphasis>
+causing a rebuild--that is,
+which are not included in the signature
+of target files built with this command.
+All text between
+<emphasis remap='B'>$(</emphasis>
+and
+<emphasis remap='B'>$)</emphasis>
+will be removed from the command line
+before it is added to file signatures,
+and the
+<emphasis remap='B'>$(</emphasis>
+and
+<emphasis remap='B'>$)</emphasis>
+will be removed before the command is executed.
+For example, the command line:</para>
+
+<literallayout remap='.nf'>
+echo Last build occurred $( $TODAY $). &gt; $TARGET
+</literallayout> <!-- .fi -->
+
+
+<para>would execute the command:</para>
+
+<literallayout remap='.nf'>
+echo Last build occurred $TODAY. &gt; $TARGET
+</literallayout> <!-- .fi -->
+
+
+<para>but the command signature added to any target files would be:</para>
+
+<literallayout remap='.nf'>
+echo Last build occurred  . &gt; $TARGET
+</literallayout> <!-- .fi -->
+
+</refsect2>
+
+<refsect2 id='python_code_substitution'><title>Python Code Substitution</title>
+
+<para>Any python code within
+<emphasis remap='B'>${</emphasis>-<emphasis remap='B'>}</emphasis>
+pairs gets evaluated by python 'eval', with the python globals set to
+the current environment's set of construction variables.
+So in the following case:</para>
+<literallayout remap='.nf'>
+env['COND'] = 0
+env.Command('foo.out', 'foo.in',
+<!--    '''echo ${COND==1 and 'FOO' or 'BAR'} &gt; $TARGET''') -->
+</literallayout> <!-- .fi -->
+<para>the command executed will be either</para>
+<literallayout remap='.nf'>
+echo FOO &gt; foo.out
+</literallayout> <!-- .fi -->
+<para>or</para>
+<literallayout remap='.nf'>
+echo BAR &gt; foo.out
+</literallayout> <!-- .fi -->
+<para>according to the current value of env['COND'] when the command is
+executed.  The evaluation occurs when the target is being
+built, not when the SConscript is being read.  So if env['COND'] is changed
+later in the SConscript, the final value will be used.</para>
+
+<para>Here's a more interesting example.  Note that all of COND, FOO, and
+BAR are environment variables, and their values are substituted into
+the final command.  FOO is a list, so its elements are interpolated
+separated by spaces.</para>
+
+<literallayout remap='.nf'>
+env=Environment()
+env['COND'] = 0
+env['FOO'] = ['foo1', 'foo2']
+env['BAR'] = 'barbar'
+env.Command('foo.out', 'foo.in',
+    'echo ${COND==1 and FOO or BAR} &gt; $TARGET')
+
+# Will execute this:
+#  echo foo1 foo2 &gt; foo.out
+</literallayout> <!-- .fi -->
+
+<para>SCons uses the following rules when converting construction variables into
+command lines:</para>
+
+<variablelist remap='IP'>
+  <varlistentry>
+  <term>String</term>
+  <listitem>
+<para>When the value is a string it is interpreted as a space delimited list of
+command line arguments.</para>
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>List</term>
+  <listitem>
+<para>When the value is a list it is interpreted as a list of command line
+arguments. Each element of the list is converted to a string.</para>
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>Other</term>
+  <listitem>
+<para>Anything that is not a list or string is converted to a string and
+interpreted as a single command line argument.</para>
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>Newline</term>
+  <listitem>
+<para>Newline characters (\n) delimit lines. The newline parsing is done after
+all other parsing, so it is not possible for arguments (e.g. file names) to
+contain embedded newline characters. This limitation will likely go away in
+a future version of SCons.</para>
+
+  </listitem>
+  </varlistentry>
+</variablelist>
+</refsect2>
+
+<refsect2 id='scanner_objects'><title>Scanner Objects</title>
+
+<para>You can use the
+<emphasis remap='B'>Scanner</emphasis>
+function to define
+objects to scan
+new file types for implicit dependencies.
+The
+<emphasis remap='B'>Scanner</emphasis>
+function accepts the following arguments:</para>
+
+<variablelist remap='IP'>
+  <varlistentry>
+  <term>function</term>
+  <listitem>
+<para>This can be either:
+1) a Python function that will process
+the Node (file)
+and return a list of File Nodes
+representing the implicit
+dependencies (file names) found in the contents;
+or:
+2) a dictionary that maps keys
+(typically the file suffix, but see below for more discussion)
+to other Scanners that should be called.</para>
+
+<para>If the argument is actually a Python function,
+the function must take three or four arguments:</para>
+
+<para>    def scanner_function(node, env, path):</para>
+
+<para>    def scanner_function(node, env, path, arg=None):</para>
+
+<para>The
+<emphasis remap='B'>node</emphasis>
+argument is the internal
+SCons node representing the file.
+Use
+<emphasis remap='B'>str(node)</emphasis>
+to fetch the name of the file, and
+<emphasis remap='B'>node.get_contents()</emphasis>
+to fetch contents of the file.
+Note that the file is
+<emphasis remap='I'>not</emphasis>
+guaranteed to exist before the scanner is called,
+so the scanner function should check that
+if there's any chance that the scanned file
+might not exist
+(for example, if it's built from other files).</para>
+
+<para>The
+<emphasis remap='B'>env</emphasis>
+argument is the construction environment for the scan.
+Fetch values from it using the
+<emphasis remap='B'>env.Dictionary()</emphasis>
+method.</para>
+
+<para>The
+<emphasis remap='B'>path</emphasis>
+argument is a tuple (or list)
+of directories that can be searched
+for files.
+This will usually be the tuple returned by the
+<emphasis remap='B'>path_function</emphasis>
+argument (see below).</para>
+
+<para>The
+<emphasis remap='B'>arg</emphasis>
+argument is the argument supplied
+when the scanner was created, if any.</para>
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>name</term>
+  <listitem>
+<para>The name of the Scanner.
+This is mainly used
+to identify the Scanner internally.</para>
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>argument</term>
+  <listitem>
+<para>An optional argument that, if specified,
+will be passed to the scanner function
+(described above)
+and the path function
+(specified below).</para>
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>skeys</term>
+  <listitem>
+<para>An optional list that can be used to
+determine which scanner should be used for
+a given Node.
+In the usual case of scanning for file names,
+this argument will be a list of suffixes
+for the different file types that this
+Scanner knows how to scan.
+If the argument is a string,
+then it will be expanded
+into a list by the current environment.</para>
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>path_function</term>
+  <listitem>
+<para>A Python function that takes four or five arguments:
+a construction environment,
+a Node for the directory containing
+the SConscript file in which
+the first target was defined,
+a list of target nodes,
+a list of source nodes,
+and an optional argument supplied
+when the scanner was created.
+The
+<emphasis remap='B'>path_function</emphasis>
+returns a tuple of directories
+that can be searched for files to be returned
+by this Scanner object.
+(Note that the
+<emphasis remap='B'>FindPathDirs</emphasis>()
+function can be used to return a ready-made
+<emphasis remap='B'>path_function</emphasis>
+for a given construction variable name,
+instead of having to write your own function from scratch.)</para>
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>node_class</term>
+  <listitem>
+<para>The class of Node that should be returned
+by this Scanner object.
+Any strings or other objects returned
+by the scanner function
+that are not of this class
+will be run through the
+<emphasis remap='B'>node_factory</emphasis>
+function.</para>
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>node_factory</term>
+  <listitem>
+<para>A Python function that will take a string
+or other object
+and turn it into the appropriate class of Node
+to be returned by this Scanner object.</para>
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>scan_check</term>
+  <listitem>
+<para>An optional Python function that takes two arguments,
+a Node (file) and a construction environment,
+and returns whether the
+Node should, in fact,
+be scanned for dependencies.
+This check can be used to eliminate unnecessary
+calls to the scanner function when,
+for example, the underlying file
+represented by a Node does not yet exist.</para>
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>recursive</term>
+  <listitem>
+<para>An optional flag that
+specifies whether this scanner should be re-invoked
+on the dependency files returned by the scanner.
+When this flag is not set,
+the Node subsystem will
+only invoke the scanner on the file being scanned,
+and not (for example) also on the files
+specified by the #include lines
+in the file being scanned.
+<emphasis remap='I'>recursive</emphasis>
+may be a callable function,
+in which case it will be called with a list of
+Nodes found and
+should return a list of Nodes
+that should be scanned recursively;
+this can be used to select a specific subset of
+Nodes for additional scanning.</para>
+
+  </listitem>
+  </varlistentry>
+</variablelist>
+<para>Note that
+<command>scons</command>
+has a global
+<emphasis remap='B'>SourceFileScanner</emphasis>
+object that is used by
+the
+<emphasis remap='B'>Object</emphasis>(),
+<emphasis remap='B'>SharedObject</emphasis>(),
+and
+<emphasis remap='B'>StaticObject</emphasis>()
+builders to decide
+which scanner should be used
+for different file extensions.
+You can using the
+<emphasis remap='B'>SourceFileScanner.add_scanner</emphasis>()
+method to add your own Scanner object
+to the
+<command>scons</command>
+infrastructure
+that builds target programs or
+libraries from a list of
+source files of different types:</para>
+
+<programlisting remap='.nf'>
+def xyz_scan(node, env, path):
+    contents = node.get_text_contents()
+    # Scan the contents and return the included files.
+
+XYZScanner = Scanner(xyz_scan)
+
+SourceFileScanner.add_scanner('.xyz', XYZScanner)
+
+env.Program('my_prog', ['file1.c', 'file2.f', 'file3.xyz'])
+</programlisting> <!-- .fi -->
+
+</refsect2>
+</refsect1>
+
+<refsect1 id='systemspecific_behavior'><title>SYSTEM-SPECIFIC BEHAVIOR</title>
+<para>SCons and its configuration files are very portable,
+due largely to its implementation in Python.
+There are, however, a few portability
+issues waiting to trap the unwary.</para>
+
+<refsect2 id='c_file_suffix'><title>.C file suffix</title>
+<para>SCons handles the upper-case
+<markup>.C</markup>
+file suffix differently,
+depending on the capabilities of
+the underlying system.
+On a case-sensitive system
+such as Linux or UNIX,
+SCons treats a file with a
+<markup>.C</markup>
+suffix as a C++ source file.
+On a case-insensitive system
+such as Windows,
+SCons treats a file with a
+<markup>.C</markup>
+suffix as a C source file.</para>
+</refsect2>
+
+<refsect2 id='f_file_suffix'><title>.F file suffix</title>
+<para>SCons handles the upper-case
+<markup>.F</markup>
+file suffix differently,
+depending on the capabilities of
+the underlying system.
+On a case-sensitive system
+such as Linux or UNIX,
+SCons treats a file with a
+<markup>.F</markup>
+suffix as a Fortran source file
+that is to be first run through
+the standard C preprocessor.
+On a case-insensitive system
+such as Windows,
+SCons treats a file with a
+<markup>.F</markup>
+suffix as a Fortran source file that should
+<emphasis remap='I'>not</emphasis>
+be run through the C preprocessor.</para>
+</refsect2>
+
+<refsect2 id='windows_cygwin_tools_and_cygwin_python_v'><title>Windows: Cygwin Tools and Cygwin Python vs. Windows Pythons</title>
+<para>Cygwin supplies a set of tools and utilities
+that let users work on a
+Windows system using a more POSIX-like environment.
+The Cygwin tools, including Cygwin Python,
+do this, in part,
+by sharing an ability to interpret UNIX-like path names.
+For example, the Cygwin tools
+will internally translate a Cygwin path name
+like /cygdrive/c/mydir
+to an equivalent Windows pathname
+of C:/mydir (equivalent to C:\mydir).</para>
+
+<para>Versions of Python
+that are built for native Windows execution,
+such as the python.org and ActiveState versions,
+do not have the Cygwin path name semantics.
+This means that using a native Windows version of Python
+to build compiled programs using Cygwin tools
+(such as gcc, bison, and flex)
+may yield unpredictable results.
+"Mixing and matching" in this way
+can be made to work,
+but it requires careful attention to the use of path names
+in your SConscript files.</para>
+
+<para>In practice, users can sidestep
+the issue by adopting the following rules:
+When using gcc,
+use the Cygwin-supplied Python interpreter
+to run SCons;
+when using Microsoft Visual C/C++
+(or some other Windows compiler)
+use the python.org or ActiveState version of Python
+to run SCons.</para>
+</refsect2>
+
+<refsect2 id='windows_sconsbat_file'><title>Windows: scons.bat file</title>
+<para>On Windows systems,
+SCons is executed via a wrapper
+<emphasis remap='B'>scons.bat</emphasis>
+file.
+This has (at least) two ramifications:</para>
+
+<para>First, Windows command-line users
+that want to use variable assignment
+on the command line
+may have to put double quotes
+around the assignments:</para>
+
+<literallayout remap='.nf'>
+scons "FOO=BAR" "BAZ=BLEH"
+</literallayout> <!-- .fi -->
+
+<para>Second, the Cygwin shell does not
+recognize this file as being the same
+as an
+<command>scons</command>
+command issued at the command-line prompt.
+You can work around this either by
+executing
+<emphasis remap='B'>scons.bat</emphasis>
+from the Cygwin command line,
+or by creating a wrapper shell
+script named
+<emphasis remap='B'>scons .</emphasis></para>
+
+</refsect2>
+
+<refsect2 id='mingw'><title>MinGW</title>
+
+<para>The MinGW bin directory must be in your PATH environment variable or the
+PATH variable under the ENV construction variable for SCons
+to detect and use the MinGW tools. When running under the native Windows
+Python interpreter, SCons will prefer the MinGW tools over the Cygwin
+tools, if they are both installed, regardless of the order of the bin
+directories in the PATH variable. If you have both MSVC and MinGW
+installed and you want to use MinGW instead of MSVC,
+then you must explictly tell SCons to use MinGW by passing</para>
+
+<literallayout remap='.nf'>
+tools=['mingw']
+</literallayout> <!-- .fi -->
+
+<para>to the Environment() function, because SCons will prefer the MSVC tools
+over the MinGW tools.</para>
+
+</refsect2>
+</refsect1>
+
+<refsect1 id='examples'><title>EXAMPLES</title>
+<para>To help you get started using SCons,
+this section contains a brief overview of some common tasks.</para>
+
+
+<refsect2 id='basic_compilation_from_a_single_source_f'><title>Basic Compilation From a Single Source File</title>
+
+<literallayout remap='.nf'>
+env = Environment()
+env.Program(target = 'foo', source = 'foo.c')
+</literallayout> <!-- .fi -->
+
+<para>Note:  Build the file by specifying
+the target as an argument
+("scons foo" or "scons foo.exe").
+or by specifying a dot ("scons .").</para>
+
+</refsect2>
+
+<refsect2 id='basic_compilation_from_multiple_source_f'><title>Basic Compilation From Multiple Source Files</title>
+
+<literallayout remap='.nf'>
+env = Environment()
+env.Program(target = 'foo', source = Split('f1.c f2.c f3.c'))
+</literallayout> <!-- .fi -->
+
+</refsect2>
+
+<refsect2 id='setting_a_compilation_flag'><title>Setting a Compilation Flag</title>
+
+<literallayout remap='.nf'>
+env = Environment(CCFLAGS = '-g')
+env.Program(target = 'foo', source = 'foo.c')
+</literallayout> <!-- .fi -->
+
+</refsect2>
+
+<refsect2 id='search_the_local_directory_for_h_files'><title>Search The Local Directory For .h Files</title>
+
+<para>Note:  You do
+<emphasis remap='I'>not</emphasis>
+need to set CCFLAGS to specify -I options by hand.
+SCons will construct the right -I options from CPPPATH.</para>
+
+<literallayout remap='.nf'>
+env = Environment(CPPPATH = ['.'])
+env.Program(target = 'foo', source = 'foo.c')
+</literallayout> <!-- .fi -->
+
+</refsect2>
+
+<refsect2 id='search_multiple_directories_for_h_files'><title>Search Multiple Directories For .h Files</title>
+
+<literallayout remap='.nf'>
+env = Environment(CPPPATH = ['include1', 'include2'])
+env.Program(target = 'foo', source = 'foo.c')
+</literallayout> <!-- .fi -->
+
+</refsect2>
+
+<refsect2 id='building_a_static_library'><title>Building a Static Library</title>
+
+<literallayout remap='.nf'>
+env = Environment()
+env.StaticLibrary(target = 'foo', source = Split('l1.c l2.c'))
+env.StaticLibrary(target = 'bar', source = ['l3.c', 'l4.c'])
+</literallayout> <!-- .fi -->
+
+</refsect2>
+
+<refsect2 id='building_a_shared_library'><title>Building a Shared Library</title>
+
+<literallayout remap='.nf'>
+env = Environment()
+env.SharedLibrary(target = 'foo', source = ['l5.c', 'l6.c'])
+env.SharedLibrary(target = 'bar', source = Split('l7.c l8.c'))
+</literallayout> <!-- .fi -->
+
+</refsect2>
+
+<refsect2 id='linking_a_local_library_into_a_program'><title>Linking a Local Library Into a Program</title>
+
+<literallayout remap='.nf'>
+env = Environment(LIBS = 'mylib', LIBPATH = ['.'])
+env.Library(target = 'mylib', source = Split('l1.c l2.c'))
+env.Program(target = 'prog', source = ['p1.c', 'p2.c'])
+</literallayout> <!-- .fi -->
+
+</refsect2>
+
+<refsect2 id='defining_your_own_builder_object'><title>Defining Your Own Builder Object</title>
+
+<para>Notice that when you invoke the Builder,
+you can leave off the target file suffix,
+and SCons will add it automatically.</para>
+
+<literallayout remap='.nf'>
+bld = Builder(action = 'pdftex &lt; $SOURCES &gt; $TARGET'
+              suffix = '.pdf',
+              src_suffix = '.tex')
+env = Environment(BUILDERS = {'PDFBuilder' : bld})
+env.PDFBuilder(target = 'foo.pdf', source = 'foo.tex')
+
+# The following creates "bar.pdf" from "bar.tex"
+env.PDFBuilder(target = 'bar', source = 'bar')
+</literallayout> <!-- .fi -->
+
+<para>Note also that the above initialization
+overwrites the default Builder objects,
+so the Environment created above
+can not be used call Builders like env.Program(),
+env.Object(), env.StaticLibrary(), etc.</para>
+
+</refsect2>
+
+<refsect2 id='adding_your_own_builder_object_to_an_env'><title>Adding Your Own Builder Object to an Environment</title>
+
+<literallayout remap='.nf'>
+bld = Builder(action = 'pdftex &lt; $SOURCES &gt; $TARGET'
+              suffix = '.pdf',
+              src_suffix = '.tex')
+env = Environment()
+env.Append(BUILDERS = {'PDFBuilder' : bld})
+env.PDFBuilder(target = 'foo.pdf', source = 'foo.tex')
+env.Program(target = 'bar', source = 'bar.c')
+</literallayout> <!-- .fi -->
+
+<para>You also can use other Pythonic techniques to add
+to the BUILDERS construction variable, such as:</para>
+
+<literallayout remap='.nf'>
+env = Environment()
+env['BUILDERS]['PDFBuilder'] = bld
+</literallayout> <!-- .fi -->
+
+</refsect2>
+
+<refsect2 id='defining_your_own_scanner_object'><title>Defining Your Own Scanner Object</title>
+
+<para>The following example shows an extremely simple scanner (the
+<emphasis remap='B'>kfile_scan</emphasis>()
+function)
+that doesn't use a search path at all
+and simply returns the
+file names present on any
+<emphasis remap='B'>include</emphasis>
+lines in the scanned file.
+This would implicitly assume that all included
+files live in the top-level directory:</para>
+
+<literallayout remap='.nf'>
+import re
+
+include_re = re.compile(r'^include\s+(\S+)$', re.M)
+
+def kfile_scan(node, env, path, arg):
+    contents = node.get_text_contents()
+    includes = include_re.findall(contents)
+    return env.File(includes)
+
+kscan = Scanner(name = 'kfile',
+                function = kfile_scan,
+                argument = None,
+                skeys = ['.k'])
+scanners = Environment().Dictionary('SCANNERS')
+env = Environment(SCANNERS = scanners + [kscan])
+
+env.Command('foo', 'foo.k', 'kprocess &lt; $SOURCES &gt; $TARGET')
+
+bar_in = File('bar.in')
+env.Command('bar', bar_in, 'kprocess $SOURCES &gt; $TARGET')
+bar_in.target_scanner = kscan
+</literallayout> <!-- .fi -->
+
+<para>It is important to note that you
+have to return a list of File nodes from the scan function, simple
+strings for the file names won't do. As in the examples we are showing here,
+you can use the
+<emphasis remap='B'>File()</emphasis>
+function of your current Environment in order to create nodes on the fly from
+a sequence of file names with relative paths.</para>
+
+<para>Here is a similar but more complete example that searches
+a path of directories
+(specified as the
+<emphasis remap='B'>MYPATH</emphasis>
+construction variable)
+for files that actually exist:</para>
+
+<programlisting remap='.nf'>
+import re
+import os
+include_re = re.compile(r'^include\s+(\S+)$', re.M)
+
+def my_scan(node, env, path, arg):
+    contents = node.get_text_contents()
+    includes = include_re.findall(contents)
+    if includes == []:
+        return []
+    results = []
+    for inc in includes:
+        for dir in path:
+            file = str(dir) + os.sep + inc
+            if os.path.exists(file):
+                results.append(file)
+                break
+    return env.File(results)
+
+scanner = Scanner(name = 'myscanner',
+                 function = my_scan,
+                 argument = None,
+                 skeys = ['.x'],
+                 path_function = FindPathDirs('MYPATH')
+                 )
+scanners = Environment().Dictionary('SCANNERS')
+env = Environment(SCANNERS = scanners + [scanner],
+                  MYPATH = ['incs'])
+
+env.Command('foo', 'foo.x', 'xprocess &lt; $SOURCES &gt; $TARGET')
+</programlisting> <!-- .fi -->
+
+<para>The
+<emphasis remap='B'>FindPathDirs</emphasis>()
+function used in the previous example returns a function
+(actually a callable Python object)
+that will return a list of directories
+specified in the
+<emphasis remap='B'>$MYPATH</emphasis>
+construction variable. It lets SCons detect the file
+<emphasis remap='B'>incs/foo.inc</emphasis>
+, even if 
+<emphasis remap='B'>foo.x</emphasis>
+contains the line
+<emphasis remap='B'>include foo.inc</emphasis>
+only.
+If you need to customize how the search path is derived,
+you would provide your own
+<emphasis remap='B'>path_function</emphasis>
+argument when creating the Scanner object,
+as follows:</para>
+
+<programlisting remap='.nf'>
+# MYPATH is a list of directories to search for files in
+def pf(env, dir, target, source, arg):
+    top_dir = Dir('#').abspath
+    results = []
+    if 'MYPATH' in env:
+        for p in env['MYPATH']:
+            results.append(top_dir + os.sep + p)
+    return results
+
+scanner = Scanner(name = 'myscanner',
+                 function = my_scan,
+                 argument = None,
+                 skeys = ['.x'],
+                 path_function = pf
+                 )
+</programlisting> <!-- .fi -->
+
+</refsect2>
+
+<refsect2 id='creating_a_hierarchical_build'><title>Creating a Hierarchical Build</title>
+
+<para>Notice that the file names specified in a subdirectory's
+SConscript
+file are relative to that subdirectory.</para>
+
+<programlisting remap='.nf'>
+SConstruct:
+
+    env = Environment()
+    env.Program(target = 'foo', source = 'foo.c')
+
+    SConscript('sub/SConscript')
+
+sub/SConscript:
+
+    env = Environment()
+    # Builds sub/foo from sub/foo.c
+    env.Program(target = 'foo', source = 'foo.c')
+
+    SConscript('dir/SConscript')
+
+sub/dir/SConscript:
+
+    env = Environment()
+    # Builds sub/dir/foo from sub/dir/foo.c
+    env.Program(target = 'foo', source = 'foo.c')
+</programlisting> <!-- .fi -->
+
+</refsect2>
+
+<refsect2 id='sharing_variables_between_sconscript_fil'><title>Sharing Variables Between SConscript Files</title>
+
+<para>You must explicitly Export() and Import() variables that
+you want to share between SConscript files.</para>
+
+<programlisting remap='.nf'>
+SConstruct:
+
+    env = Environment()
+    env.Program(target = 'foo', source = 'foo.c')
+
+    Export("env")
+    SConscript('subdirectory/SConscript')
+
+subdirectory/SConscript:
+
+    Import("env")
+    env.Program(target = 'foo', source = 'foo.c')
+</programlisting> <!-- .fi -->
+
+</refsect2>
+
+<refsect2 id='building_multiple_variants_from_the_same'><title>Building Multiple Variants From the Same Source</title>
+
+<para>Use the variant_dir keyword argument to
+the SConscript function to establish
+one or more separate variant build directory trees
+for a given source directory:</para>
+
+<programlisting remap='.nf'>
+SConstruct:
+
+    cppdefines = ['FOO']
+    Export("cppdefines")
+    SConscript('src/SConscript', variant_dir='foo')
+
+    cppdefines = ['BAR']
+    Export("cppdefines")
+    SConscript('src/SConscript', variant_dir='bar')
+
+src/SConscript:
+
+    Import("cppdefines")
+    env = Environment(CPPDEFINES = cppdefines)
+    env.Program(target = 'src', source = 'src.c')
+</programlisting> <!-- .fi -->
+
+<para>Note the use of the Export() method
+to set the "cppdefines" variable to a different
+value each time we call the SConscript function.</para>
+
+</refsect2>
+
+<refsect2 id='hierarchical_build_of_two_libraries_link'><title>Hierarchical Build of Two Libraries Linked With a Program</title>
+
+<programlisting remap='.nf'>
+SConstruct:
+
+    env = Environment(LIBPATH = ['#libA', '#libB'])
+    Export('env')
+    SConscript('libA/SConscript')
+    SConscript('libB/SConscript')
+    SConscript('Main/SConscript')
+
+libA/SConscript:
+
+    Import('env')
+    env.Library('a', Split('a1.c a2.c a3.c'))
+
+libB/SConscript:
+
+    Import('env')
+    env.Library('b', Split('b1.c b2.c b3.c'))
+
+Main/SConscript:
+
+    Import('env')
+    e = env.Copy(LIBS = ['a', 'b'])
+    e.Program('foo', Split('m1.c m2.c m3.c'))
+</programlisting> <!-- .fi -->
+
+<para>The '#' in the LIBPATH directories specify that they're relative to the
+top-level directory, so they don't turn into "Main/libA" when they're
+used in Main/SConscript.</para>
+
+<para>Specifying only 'a' and 'b' for the library names
+allows SCons to append the appropriate library
+prefix and suffix for the current platform
+(for example, 'liba.a' on POSIX systems,
+'a.lib' on Windows).</para>
+
+</refsect2>
+
+<refsect2 id='customizing_construction_variables_from_'><title>Customizing construction variables from the command line.</title>
+
+<para>The following would allow the C compiler to be specified on the command
+line or in the file custom.py.</para>
+
+<literallayout remap='.nf'>
+vars = Variables('custom.py')
+vars.Add('CC', 'The C compiler.')
+env = Environment(variables=vars)
+Help(vars.GenerateHelpText(env))
+</literallayout> <!-- .fi -->
+
+<para>The user could specify the C compiler on the command line:</para>
+
+<literallayout remap='.nf'>
+scons "CC=my_cc"
+</literallayout> <!-- .fi -->
+
+<para>or in the custom.py file:</para>
+
+<literallayout remap='.nf'>
+CC = 'my_cc'
+</literallayout> <!-- .fi -->
+
+<para>or get documentation on the options:</para>
+
+<literallayout remap='.nf'>
+$ scons -h
+
+CC: The C compiler.
+    default: None
+    actual: cc
+
+</literallayout> <!-- .fi -->
+
+</refsect2>
+
+<refsect2 id='using_microsoft_visual_c_precompiled_hea'><title>Using Microsoft Visual C++ precompiled headers</title>
+
+<para>Since windows.h includes everything and the kitchen sink, it can take quite
+some time to compile it over and over again for a bunch of object files, so
+Microsoft provides a mechanism to compile a set of headers once and then
+include the previously compiled headers in any object file. This
+technology is called precompiled headers. The general recipe is to create a
+file named "StdAfx.cpp" that includes a single header named "StdAfx.h", and
+then include every header you want to precompile in "StdAfx.h", and finally
+include "StdAfx.h" as the first header in all the source files you are
+compiling to object files. For example:</para>
+
+<para>StdAfx.h:</para>
+<literallayout remap='.nf'>
+#include &lt;windows.h&gt;
+#include &lt;my_big_header.h&gt;
+</literallayout> <!-- .fi -->
+
+<para>StdAfx.cpp:</para>
+<literallayout remap='.nf'>
+#include &lt;StdAfx.h&gt;
+</literallayout> <!-- .fi -->
+
+<para>Foo.cpp:</para>
+<literallayout remap='.nf'>
+#include &lt;StdAfx.h&gt;
+
+/* do some stuff */
+</literallayout> <!-- .fi -->
+
+<para>Bar.cpp:</para>
+<literallayout remap='.nf'>
+#include &lt;StdAfx.h&gt;
+
+/* do some other stuff */
+</literallayout> <!-- .fi -->
+
+<para>SConstruct:</para>
+<literallayout remap='.nf'>
+env=Environment()
+env['PCHSTOP'] = 'StdAfx.h'
+env['PCH'] = env.PCH('StdAfx.cpp')[0]
+env.Program('MyApp', ['Foo.cpp', 'Bar.cpp'])
+</literallayout> <!-- .fi -->
+
+<para>For more information see the document for the PCH builder, and the PCH and
+PCHSTOP construction variables. To learn about the details of precompiled
+headers consult the MSDN documention for /Yc, /Yu, and /Yp.</para>
+
+</refsect2>
+
+<refsect2 id='using_microsoft_visual_c_external_debugg'><title>Using Microsoft Visual C++ external debugging information</title>
+
+<para>Since including debugging information in programs and shared libraries can
+cause their size to increase significantly, Microsoft provides a mechanism
+for including the debugging information in an external file called a PDB
+file. SCons supports PDB files through the PDB construction
+variable.</para>
+
+<para>SConstruct:</para>
+<literallayout remap='.nf'>
+env=Environment()
+env['PDB'] = 'MyApp.pdb'
+env.Program('MyApp', ['Foo.cpp', 'Bar.cpp'])
+</literallayout> <!-- .fi -->
+
+<para>For more information see the document for the PDB construction variable.</para>
+
+</refsect2>
+</refsect1>
+
+<refsect1 id='environment'><title>ENVIRONMENT</title>
+<variablelist remap='IP'>
+  <varlistentry>
+  <term>SCONS_LIB_DIR</term>
+  <listitem>
+<para>Specifies the directory that contains the SCons Python module directory
+(e.g. /home/aroach/scons-src-0.01/src/engine).</para>
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>SCONSFLAGS</term>
+  <listitem>
+<para>A string of options that will be used by scons in addition to those passed
+on the command line.</para>
+
+  </listitem>
+  </varlistentry>
+</variablelist>
+</refsect1>
+
+<refsect1 id='see_also'><title>SEE ALSO</title>
+<para><command>scons</command>
+User Manual,
+<command>scons</command>
+Design Document,
+<command>scons</command>
+source code.</para>
+
+</refsect1>
+
+<refsect1 id='authors'><title>AUTHORS</title>
+<para>Steven Knight &lt;knight@baldmt.com&gt;
+<!-- .br -->
+Anthony Roach &lt;aroach@electriceyeball.com&gt;</para>
+</refsect1>
+</refentry>
+
diff --git a/doc/man/sconsign.1 b/doc/man/sconsign.1
deleted file mode 100644
index 7c80327..0000000
--- a/doc/man/sconsign.1
+++ /dev/null
@@ -1,208 +0,0 @@
-.\" __COPYRIGHT__
-.\"
-.\" Permission is hereby granted, free of charge, to any person obtaining
-.\" a copy of this software and associated documentation files (the
-.\" "Software"), to deal in the Software without restriction, including
-.\" without limitation the rights to use, copy, modify, merge, publish,
-.\" distribute, sublicense, and/or sell copies of the Software, and to
-.\" permit persons to whom the Software is furnished to do so, subject to
-.\" the following conditions:
-.\"
-.\" The above copyright notice and this permission notice shall be included
-.\" in all copies or substantial portions of the Software.
-.\"
-.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY
-.\" KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
-.\" WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
-.\" NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
-.\" LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
-.\" OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
-.\" WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
-.\"
-.\" __FILE__ __REVISION__ __DATE__ __DEVELOPER__
-.\"
-.\" ES - Example Start - indents and turns off line fill
-.de ES
-.RS
-.nf
-..
-.\" EE - Example End - ends indent and turns line fill back on
-.de EE
-.RE
-.fi
-..
-.TH SCONSIGN 1 "__MONTH_YEAR__"
-.SH NAME
-sconsign \- print SCons .sconsign file information
-.SH SYNOPSIS
-.B sconsign
-[
-.IR options ...
-]
-.IR file
-[ ... ]
-.SH DESCRIPTION
-
-The 
-.B sconsign
-command
-displays the contents of one or more
-.B .sconsign
-files specified by the user.
-
-By default,
-.B sconsign
-dumps the entire contents of the
-specified file(s).
-Each entry is printed in the following format:
-
-    file: signature timestamp length
-            implicit_dependency_1: signature timestamp length
-            implicit_dependency_2: signature timestamp length
-            action_signature [action string]
-
-.B None
-is printed
-in place of any missing timestamp, bsig, or csig
-values for
-any entry
-or any of its dependencies.
-If the entry has no implicit dependencies,
-or no build action,
-the lines are simply omitted.
-
-By default,
-.B sconsign
-assumes that any
-.I file
-arguments that end with a
-.B .dbm
-suffix contains
-signature entries for
-more than one directory
-(that is,
-was specified by the
-.B SConsignFile ()
-function).
-Any
-.I file
-argument that does not end in
-.B .dbm
-is assumed to be a traditional
-.B .sconsign
-file containing the signature entries
-for a single directory.
-An explicit format
-may be specified using the
-.B -f
-or
-.B --file=
-options.
-
-.SH OPTIONS
-
-Various options control what information is printed
-and the format:
-
-.TP
--a, --act, --action
-Prints the build action information
-for all entries or the specified entries.
-
-.TP
--c, --csig
-Prints the content signature (csig) information
-for all entries or the specified entries.
-
-.TP
--d DIRECTORY, --dir=DIRECTORY
-When the signatures are being
-read from a
-.B .dbm
-file, or the
-.B -f dbm
-or
-.B --format=dbm
-options are used,
-prints information about
-only the signatures
-for entries in the specified
-.IR DIRECTORY .
-
-.TP
--e ENTRY, --entry=ENTRY
-Prints information about only the specified
-.IR ENTRY .
-Multiple -e options may be used,
-in which case information about each
-.I ENTRY
-is printed in the order in which the
-options are specified on the command line.
-
-.TP
--f FORMAT, --format=FORMAT
-The file(s) to be printed
-are in the specified
-.IR FORMAT .
-Legal values are
-.B dbm
-(the DBM format used
-when the
-.BR SConsignFile ()
-function is used)
-or
-.B sconsign
-(the default format
-used for an individual
-.B .sconsign
-file in each directory).
-
-.TP
--h, --help
-Prints a help message and exits.
-
-.TP
--i, --implicit
-Prints the list of cached implicit dependencies
-for all entries or the the specified entries.
-
-.TP
---raw
-Prints a pretty-printed representation
-of the raw Python dictionary that holds
-build information about individual entry
-(both the entry itself or its implicit dependencies).
-An entry's build action is still printed in its usual format.
-
-.TP
--r, --readable
-Prints timestamps in a human-readable string,
-enclosed in single quotes.
-
-.TP
--t, --timestamp
-Prints the timestamp information
-for all entries or the specified entries.
-
-.TP
--v, --verbose
-Prints labels identifying each field being printed.
-
-.SH ENVIRONMENT
-
-.IP SCONS_LIB_DIR
-Specifies the directory that contains the SCons Python module directory
-(e.g. /home/aroach/scons-src-0.01/src/engine).
-on the command line.
-
-.SH "SEE ALSO"
-.BR scons ,
-.B scons
-User Manual,
-.B scons
-Design Document,
-.B scons
-source code.
-
-.SH AUTHORS
-Steven Knight <knight at baldmt dot com>
diff --git a/doc/man/sconsign.xml b/doc/man/sconsign.xml
new file mode 100644
index 0000000..99bfd11
--- /dev/null
+++ b/doc/man/sconsign.xml
@@ -0,0 +1,266 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+                   "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
+<!-- lifted from troff+man by doclifter -->
+<refentry id='sconsign1'>
+<!--  __COPYRIGHT__ -->
+
+<!--  Permission is hereby granted, free of charge, to any person obtaining -->
+<!--  a copy of this software and associated documentation files (the -->
+<!--  "Software"), to deal in the Software without restriction, including -->
+<!--  without limitation the rights to use, copy, modify, merge, publish, -->
+<!--  distribute, sublicense, and/or sell copies of the Software, and to -->
+<!--  permit persons to whom the Software is furnished to do so, subject to -->
+<!--  the following conditions: -->
+
+<!--  The above copyright notice and this permission notice shall be included -->
+<!--  in all copies or substantial portions of the Software. -->
+
+<!--  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY -->
+<!--  KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE -->
+<!--  WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND -->
+<!--  NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE -->
+<!--  LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION -->
+<!--  OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION -->
+<!--  WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. -->
+
+<!--  __FILE__ __REVISION__ __DATE__ __DEVELOPER__ -->
+
+<!--  ES \- Example Start \- indents and turns off line fill -->
+<!-- ES listing suppressed (not used) -->
+<!--  EE \- Example End \- ends indent and turns line fill back on -->
+<!-- EE listing suppressed (not used) -->
+<refmeta>
+<refentrytitle>SCONSIGN</refentrytitle>
+<manvolnum>1</manvolnum>
+<refmiscinfo class='source'>__MONTH_YEAR__</refmiscinfo>
+</refmeta>
+<refnamediv id='name'>
+<refname>sconsign</refname>
+<refpurpose>print SCons .sconsign file information</refpurpose>
+</refnamediv>
+<!-- body begins here -->
+<refsynopsisdiv id='synopsis'>
+<cmdsynopsis>
+  <command>sconsign</command>    
+    <arg choice='opt' rep='repeat'><replaceable>options</replaceable></arg>
+    <arg choice='plain'><replaceable>file</replaceable></arg>
+    <arg choice='opt'><replaceable>...</replaceable></arg>
+</cmdsynopsis>
+</refsynopsisdiv>
+
+
+<refsect1 id='description'><title>DESCRIPTION</title>
+<para>The 
+<command>sconsign</command>
+command
+displays the contents of one or more
+<markup>.sconsign</markup>
+files specified by the user.</para>
+
+<para>By default,
+<command>sconsign</command>
+dumps the entire contents of the
+specified file(s).
+Each entry is printed in the following format:</para>
+
+<para>    file: signature timestamp length
+            implicit_dependency_1: signature timestamp length
+            implicit_dependency_2: signature timestamp length
+            action_signature [action string]</para>
+
+<para><emphasis remap='B'>None</emphasis>
+is printed
+in place of any missing timestamp, bsig, or csig
+values for
+any entry
+or any of its dependencies.
+If the entry has no implicit dependencies,
+or no build action,
+the lines are simply omitted.</para>
+
+<para>By default,
+<command>sconsign</command>
+assumes that any
+<emphasis remap='I'>file</emphasis>
+arguments that end with a
+<markup>.dbm</markup>
+suffix contains
+signature entries for
+more than one directory
+(that is,
+was specified by the
+<emphasis remap='B'>SConsignFile ()</emphasis>
+function).
+Any
+<emphasis remap='I'>file</emphasis>
+argument that does not end in
+<markup>.dbm</markup>
+is assumed to be a traditional
+<markup>.sconsign</markup>
+file containing the signature entries
+for a single directory.
+An explicit format
+may be specified using the
+<option>-f</option>
+or
+<option>--file=</option>
+options.</para>
+
+</refsect1>
+
+<refsect1 id='options'><title>OPTIONS</title>
+<para>Various options control what information is printed
+and the format:</para>
+
+<variablelist remap='TP'>
+  <varlistentry>
+  <term>-a, --act, --action</term>
+  <listitem>
+<para>Prints the build action information
+for all entries or the specified entries.</para>
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>-c, --csig</term>
+  <listitem>
+<para>Prints the content signature (csig) information
+for all entries or the specified entries.</para>
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>-d DIRECTORY, --dir=DIRECTORY</term>
+  <listitem>
+<para>When the signatures are being
+read from a
+<markup>.dbm</markup>
+file, or the
+<option>-f dbm</option>
+or
+<option>--format=dbm</option>
+options are used,
+prints information about
+only the signatures
+for entries in the specified
+<emphasis remap='I'>DIRECTORY</emphasis>.</para>
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>-e ENTRY, --entry=ENTRY</term>
+  <listitem>
+<para>Prints information about only the specified
+<emphasis remap='I'>ENTRY</emphasis>.
+Multiple -e options may be used,
+in which case information about each
+<emphasis remap='I'>ENTRY</emphasis>
+is printed in the order in which the
+options are specified on the command line.</para>
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>-f FORMAT, --format=FORMAT</term>
+  <listitem>
+<para>The file(s) to be printed
+are in the specified
+<emphasis remap='I'>FORMAT</emphasis>.
+Legal values are
+<emphasis remap='B'>dbm</emphasis>
+(the DBM format used
+when the
+<emphasis remap='B'>SConsignFile</emphasis>()
+function is used)
+or
+<command>sconsign</command>
+(the default format
+used for an individual
+<markup>.sconsign</markup>
+file in each directory).</para>
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>-h, --help</term>
+  <listitem>
+<para>Prints a help message and exits.</para>
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>-i, --implicit</term>
+  <listitem>
+<para>Prints the list of cached implicit dependencies
+for all entries or the the specified entries.</para>
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>--raw</term>
+  <listitem>
+<para>Prints a pretty-printed representation
+of the raw Python dictionary that holds
+build information about individual entry
+(both the entry itself or its implicit dependencies).
+An entry's build action is still printed in its usual format.</para>
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>-r, --readable</term>
+  <listitem>
+<para>Prints timestamps in a human-readable string,
+enclosed in single quotes.</para>
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>-t, --timestamp</term>
+  <listitem>
+<para>Prints the timestamp information
+for all entries or the specified entries.</para>
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>-v, --verbose</term>
+  <listitem>
+<para>Prints labels identifying each field being printed.</para>
+
+  </listitem>
+  </varlistentry>
+</variablelist>
+</refsect1>
+
+<refsect1 id='environment'><title>ENVIRONMENT</title>
+<variablelist remap='IP'>
+  <varlistentry>
+  <term>SCONS_LIB_DIR</term>
+  <listitem>
+<para>Specifies the directory that contains the SCons Python module directory
+(e.g. /home/aroach/scons-src-0.01/src/engine).
+on the command line.</para>
+
+  </listitem>
+  </varlistentry>
+</variablelist>
+</refsect1>
+
+<refsect1 id='see_also'><title>SEE ALSO</title>
+<para><emphasis remap='B'>scons</emphasis>,
+<emphasis remap='B'>scons</emphasis>
+User Manual,
+<emphasis remap='B'>scons</emphasis>
+Design Document,
+<emphasis remap='B'>scons</emphasis>
+source code.</para>
+
+</refsect1>
+
+<refsect1 id='authors'><title>AUTHORS</title>
+<para>Steven Knight &lt;knight at baldmt dot com&gt;</para>
+</refsect1>
+</refentry>
+