Merge tag 'upstream/2.3.2'

Upstream version 2.3.2

5 files changed, 0 insertions, 17232 deletions

diff --git a/debian/patches/java_ignore_nonexistent_files.patch b/debian/patches/java_ignore_nonexistent_files.patch
deleted file mode 100644
index 5ba4713..0000000
--- a/debian/patches/java_ignore_nonexistent_files.patch
+++ /dev/null
@@ -1,21 +0,0 @@
-Description:	Ignore nonexistent files before trying to use them in Java()
-Origin:		Debian
-Bug-Debian:	http://bugs.debian.org/338232
-Forwarded:	http://scons.tigris.org/issues/show_bug.cgi?id=2207
-
-Index: scons/engine/SCons/Tool/JavaCommon.py
-===================================================================
---- scons.orig/engine/SCons/Tool/JavaCommon.py	2013-03-23 03:19:25.394200546 +0100
-+++ scons/engine/SCons/Tool/JavaCommon.py	2013-03-23 03:28:01.158216345 +0100
-@@ -282,7 +282,10 @@
-             return self.outer_state
- 
-     def parse_java_file(fn, version=default_java_version):
--        return parse_java(open(fn, 'r').read(), version)
-+        try:
-+            return parse_java(open(fn, 'r').read(), version)
-+        except IOError:
-+            return (None, [])
- 
-     def parse_java(contents, version=default_java_version, trace=None):
-         """Parse a .java file and return a double of package directory,
diff --git a/debian/patches/manpages.patch b/debian/patches/manpages.patch
deleted file mode 100644
index 38506ce..0000000
--- a/debian/patches/manpages.patch
+++ /dev/null
@@ -1,17138 +0,0 @@
-Description: Restore man pages from version 2.3.0
-Author: Luca Falavigna <dktrkranz@debian.org>
-
-Index: scons/scons-time.1
-===================================================================
---- /dev/null	1970-01-01 00:00:00.000000000 +0000
-+++ scons/scons-time.1	2014-04-26 12:21:47.051232252 +0200
-@@ -0,0 +1,1017 @@
-+.\" Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013 The SCons Foundation
-+.\"
-+.\" 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.
-+.\"
-+.\" doc/man/scons-time.1  2013/03/03 09:48:35 garyo
-+.\"
-+.\" 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 "March 2013"
-+.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 committed 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 conjunction 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 conjunction 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>
-Index: scons/scons.1
-===================================================================
---- /dev/null	1970-01-01 00:00:00.000000000 +0000
-+++ scons/scons.1	2014-04-26 12:21:47.059232201 +0200
-@@ -0,0 +1,15895 @@
-+.\" Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013 The SCons Foundation
-+.\"
-+.\" 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.
-+.\"
-+.\" doc/man/scons.1  2013/03/03 09:48:35 garyo
-+.\"
-+.TH SCONS 1 "March 2013"
-+.\" 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
-+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-+
-+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-+.IP CFile()
-+.IP env.CFile()
-+Builds a C source file given a lex (\fB.l\fP)
-+or yacc (\fB.y\fP) input file.
-+The suffix specified by the \fB$CFILESUFFIX\fP construction variable
-+(\fB.c\fP by default)
-+is automatically added to the target
-+if it is not already present.
-+Example:
-+
-+.ES
-+# builds foo.c
-+env.CFile(target = 'foo.c', source = 'foo.l')
-+# builds bar.c
-+env.CFile(target = 'bar', source = 'bar.y')
-+.EE
-+
-+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-+.IP Command()
-+.IP env.Command()
-+The \fBCommand\fP() "Builder" is actually implemented
-+as a function that looks like a Builder,
-+but actually takes an additional argument of the action
-+from which the Builder should be made.
-+See the \fBCommand\fP() function description
-+for the calling syntax and details.
-+
-+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-+.IP CXXFile()
-+.IP env.CXXFile()
-+Builds a C++ source file given a lex (\fB.ll\fP)
-+or yacc (\fB.yy\fP)
-+input file.
-+The suffix specified by the \fB$CXXFILESUFFIX\fP construction variable
-+(\fB.cc\fP by default)
-+is automatically added to the target
-+if it is not already present.
-+Example:
-+
-+.ES
-+# builds foo.cc
-+env.CXXFile(target = 'foo.cc', source = 'foo.ll')
-+# builds bar.cc
-+env.CXXFile(target = 'bar', source = 'bar.yy')
-+.EE
-+
-+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-+.IP DVI()
-+.IP env.DVI()
-+Builds a \fB.dvi\fP file
-+from a \fB.tex\fP,
-+\fB.ltx\fP or \fB.latex\fP input file.
-+If the source file suffix is \fB.tex\fP,
-+.B scons
-+will examine the contents of the file;
-+if the string
-+.B \\documentclass
-+or
-+.B \\documentstyle
-+is found, the file is assumed to be a LaTeX file and
-+the target is built by invoking the \fB$LATEXCOM\fP command line;
-+otherwise, the \fB$TEXCOM\fP command line is used.
-+If the file is a LaTeX file,
-+the
-+.BR DVI ()
-+builder method will also examine the contents
-+of the
-+.B .aux
-+file and invoke the \fB$BIBTEX\fP command line
-+if the string
-+.B bibdata
-+is found,
-+start \fB$MAKEINDEX\fP to generate an index if a
-+.B .ind
-+file is found
-+and will examine the contents
-+.B .log
-+file and re-run the \fB$LATEXCOM\fP command
-+if the log file says it is necessary.
-+
-+The suffix \fB.dvi\fP
-+(hard-coded within TeX itself)
-+is automatically added to the target
-+if it is not already present.
-+Examples:
-+
-+.ES
-+# builds from aaa.tex
-+env.DVI(target = 'aaa.dvi', source = 'aaa.tex')
-+# builds bbb.dvi
-+env.DVI(target = 'bbb', source = 'bbb.ltx')
-+# builds from ccc.latex
-+env.DVI(target = 'ccc.dvi', source = 'ccc.latex')
-+.EE
-+
-+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-+.IP Install()
-+.IP env.Install()
-+Installs one or more source files or directories
-+in the specified target,
-+which must be a directory.
-+The names of the specified source files or directories
-+remain the same within the destination directory. The
-+sources may be given as a string or as a node returned by
-+a builder.
-+
-+.ES
-+env.Install('/usr/local/bin', source = ['foo', 'bar'])
-+.EE
-+
-+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-+.IP InstallAs()
-+.IP env.InstallAs()
-+Installs one or more source files or directories
-+to specific names,
-+allowing changing a file or directory name
-+as part of the installation.
-+It is an error if the
-+target
-+and
-+source
-+arguments list different numbers of files or directories.
-+
-+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-+.IP InstallVersionedLib()
-+.IP env.InstallVersionedLib()
-+Installs a versioned shared library. The \fB$SHLIBVERSION\fP
-+construction variable should be defined in the environment
-+to confirm the version number in the library name.
-+The symlinks appropriate to the architecture will be generated.
-+
-+.ES
-+env.InstallAs(target = '/usr/local/bin/foo',
-+              source = 'foo_debug')
-+env.InstallAs(target = ['../lib/libfoo.a', '../lib/libbar.a'],
-+              source = ['libFOO.a', 'libBAR.a'])
-+.EE
-+
-+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-+.IP Jar()
-+.IP env.Jar()
-+Builds a Java archive (\fB.jar\fP) file
-+from the specified list of sources.
-+Any directories in the source list
-+will be searched for \fB.class\fP files).
-+Any \fB.java\fP files in the source list
-+will be compiled  to \fB.class\fP files
-+by calling the \fBJava\fP() Builder.
-+
-+If the \fB$JARCHDIR\fP value is set, the
-+.B jar
-+command will change to the specified directory using the
-+.B \-C
-+option.
-+If \fB$JARCHDIR\fP is not set explicitly,
-+&SCons; will use the top of any subdirectory tree
-+in which Java \fB.class\fP
-+were built by the \fBJava\fP() Builder.
-+
-+If the contents any of the source files begin with the string
-+.BR Manifest-Version ,
-+the file is assumed to be a manifest
-+and is passed to the
-+.B jar
-+command with the
-+.B m
-+option set.
-+
-+.ES
-+env.Jar(target = 'foo.jar', source = 'classes')
-+
-+env.Jar(target = 'bar.jar',
-+        source = ['bar1.java', 'bar2.java'])
-+.EE
-+
-+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-+.IP Java()
-+.IP env.Java()
-+Builds one or more Java class files.
-+The sources may be any combination of explicit
-+\fB.java\fP files,
-+or directory trees which will be scanned
-+for \fB.java\fP files.
-+
-+SCons will parse each source \fB.java\fP file
-+to find the classes
-+(including inner classes)
-+defined within that file,
-+and from that figure out the
-+target \fB.class\fP files that will be created.
-+The class files will be placed underneath
-+the specified target directory.
-+
-+SCons will also search each Java file
-+for the Java package name,
-+which it assumes can be found on a line
-+beginning with the string
-+.B package
-+in the first column;
-+the resulting \fB.class\fP files
-+will be placed in a directory reflecting
-+the specified package name.
-+For example,
-+the file
-+.B Foo.java
-+defining a single public
-+.I Foo
-+class and
-+containing a package name of
-+.I sub.dir
-+will generate a corresponding
-+.B sub/dir/Foo.class
-+class file.
-+
-+Examples:
-+
-+.ES
-+env.Java(target = 'classes', source = 'src')
-+env.Java(target = 'classes', source = ['src1', 'src2'])
-+env.Java(target = 'classes', source = ['File1.java', 'File2.java'])
-+.EE
-+.IP
-+Java source files can use the native encoding for the underlying OS.
-+Since SCons compiles in simple ASCII mode by default,
-+the compiler will generate warnings about unmappable characters,
-+which may lead to errors as the file is processed further.
-+In this case, the user must specify the \fBLANG\fP
-+environment variable to tell the compiler what encoding is used.
-+For portibility, it's best if the encoding is hard-coded
-+so that the compile will work if it is done on a system
-+with a different encoding.
-+
-+.ES
-+env = Environment()
-+env['ENV']['LANG'] = 'en_GB.UTF-8'
-+.EE
-+
-+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-+.IP JavaH()
-+.IP env.JavaH()
-+Builds C header and source files for
-+implementing Java native methods.
-+The target can be either a directory
-+in which the header files will be written,
-+or a header file name which
-+will contain all of the definitions.
-+The source can be the names of \fB.class\fP files,
-+the names of \fB.java\fP files
-+to be compiled into \fB.class\fP files
-+by calling the \fBJava\fP() builder method,
-+or the objects returned from the
-+.BR Java ()
-+builder method.
-+
-+If the construction variable
-+.B $JAVACLASSDIR
-+is set, either in the environment
-+or in the call to the
-+.BR JavaH ()
-+builder method itself,
-+then the value of the variable
-+will be stripped from the
-+beginning of any \fB.class\fP file names.
-+
-+Examples:
-+
-+.ES
-+# builds java_native.h
-+classes = env.Java(target = 'classdir', source = 'src')
-+env.JavaH(target = 'java_native.h', source = classes)
-+
-+# builds include/package_foo.h and include/package_bar.h
-+env.JavaH(target = 'include',
-+          source = ['package/foo.class', 'package/bar.class'])
-+
-+# builds export/foo.h and export/bar.h
-+env.JavaH(target = 'export',
-+          source = ['classes/foo.class', 'classes/bar.class'],
-+          JAVACLASSDIR = 'classes')
-+.EE
-+
-+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-+.IP Library()
-+.IP env.Library()
-+A synonym for the
-+.BR StaticLibrary ()
-+builder method.
-+
-+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-+.IP LoadableModule()
-+.IP env.LoadableModule()
-+On most systems,
-+this is the same as
-+.BR SharedLibrary ().
-+On Mac OS X (Darwin) platforms,
-+this creates a loadable module bundle.
-+
-+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-+.IP M4()
-+.IP env.M4()
-+Builds an output file from an M4 input file.
-+This uses a default \fB$M4FLAGS\fP value of
-+.BR \-E ,
-+which considers all warnings to be fatal
-+and stops on the first warning
-+when using the GNU version of m4.
-+Example:
-+
-+.ES
-+env.M4(target = 'foo.c', source = 'foo.c.m4')
-+.EE
-+
-+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-+.IP Moc()
-+.IP env.Moc()
-+Builds an output file from a moc input file. Moc input files are either
-+header files or cxx files. This builder is only available after using the
-+tool 'qt'. See the \fB$QTDIR\fP variable for more information.
-+Example:
-+
-+.ES
-+env.Moc('foo.h') # generates moc_foo.cc
-+env.Moc('foo.cpp') # generates foo.moc
-+.EE
-+
-+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-+.IP MOFiles()
-+.IP env.MOFiles()
-+This builder belongs to &t-link-msgfmt; tool. The builder compiles
-+\fBPO\fP files to \fBMO\fP files.
-+
-+.IR Example 1 .
-+Create \fBpl.mo\fP and \fBen.mo\fP by compiling
-+.BR pl.po\fP and \fBen.po :
-+.ES
-+  # ...
-+  env.MOFiles(['pl', 'en'])
-+.EE
-+.IP
-+.IR Example 2 .
-+Compile files for languages defined in \fBLINGUAS\fP file:
-+.ES
-+  # ...
-+  env.MOFiles(LINGUAS_FILE = 1)
-+.EE
-+.IP
-+.IR Example 3 .
-+Create \fBpl.mo\fP and \fBen.mo\fP by compiling
-+\fBpl.po\fP and \fBen.po\fP plus files for
-+languages defined in \fBLINGUAS\fP file:
-+.ES
-+  # ...
-+  env.MOFiles(['pl', 'en'], LINGUAS_FILE = 1)
-+.EE
-+.IP
-+.IR Example 4 .
-+Compile files for languages defined in \fBLINGUAS\fP file 
-+(another version):
-+.ES
-+  # ...
-+  env['LINGUAS_FILE'] = 1
-+  env.MOFiles()
-+.EE
-+
-+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-+.IP MSVSProject()
-+.IP env.MSVSProject()
-+Builds a Microsoft Visual Studio project file,
-+and by default builds a solution file as well.
-+
-+This builds a Visual Studio project file, based on the version of
-+Visual Studio that is configured (either the latest installed version,
-+or the version specified by
-+.B $MSVS_VERSION
-+in the Environment constructor).
-+For Visual Studio 6, it will generate a
-+.B .dsp
-+file.
-+For Visual Studio 7 (.NET) and later versions, it will generate a
-+.B .vcproj
-+file.
-+
-+By default,
-+this also generates a solution file
-+for the specified project,
-+a
-+.B .dsw
-+file for Visual Studio 6
-+or a
-+.B .sln
-+file for Visual Studio 7 (.NET).
-+This behavior may be disabled by specifying
-+.B auto_build_solution=0
-+when you call
-+.BR MSVSProject (),
-+in which case you presumably want to
-+build the solution file(s)
-+by calling the
-+.BR MSVSSolution ()
-+Builder (see below).
-+
-+The \fBMSVSProject\fP() builder
-+takes several lists of filenames
-+to be placed into the project file.
-+These are currently limited to
-+.BR srcs ,
-+.BR incs ,
-+.BR localincs ,
-+.BR resources ,
-+and
-+.BR misc .
-+These are pretty self-explanatory, but it should be noted that these
-+lists are added to the \fB$SOURCES\fP construction variable as strings,
-+NOT as SCons File Nodes.  This is because they represent file
-+names to be added to the project file, not the source files used to
-+build the project file.
-+
-+The above filename lists are all optional,
-+although at least one must be specified
-+for the resulting project file to be non-empty.
-+
-+In addition to the above lists of values,
-+the following values may be specified:
-+
-+.BR target :
-+The name of the target
-+.B .dsp
-+or
-+.B .vcproj
-+file.
-+The correct
-+suffix for the version of Visual Studio must be used,
-+but the
-+.B $MSVSPROJECTSUFFIX
-+construction variable
-+will be defined to the correct value (see example below).
-+
-+.BR variant :
-+The name of this particular variant.
-+For Visual Studio 7 projects,
-+this can also be a list of variant names.
-+These are typically things like "Debug" or "Release", but really
-+can be anything you want.
-+For Visual Studio 7 projects,
-+they may also specify a target platform
-+separated from the variant name by a
-+.B |
-+(vertical pipe)
-+character:
-+.BR Debug|Xbox .
-+The default target platform is Win32.
-+Multiple calls to
-+.BR MSVSProject ()
-+with different variants are allowed;
-+all variants will be added to the project file with their appropriate
-+build targets and sources.
-+
-+.BR buildtarget :
-+An optional string, node, or list of strings or nodes
-+(one per build variant), to tell the Visual Studio debugger
-+what output target to use in what build variant.
-+The number of
-+.B buildtarget
-+entries must match the number of
-+.B variant
-+entries.
-+
-+.BR runfile :
-+The name of the file that Visual Studio 7 and later
-+will run and debug.
-+This appears as the value of the
-+.B Output
-+field in the resutling Visual Studio project file.
-+If this is not specified,
-+the default is the same as the specified
-+.B buildtarget
-+value.
-+
-+Note that because &SCons; always executes its build commands
-+from the directory in which the \fBSConstruct\fP file is located,
-+if you generate a project file in a different directory
-+than the \fBSConstruct\fP directory,
-+users will not be able to double-click
-+on the file name in compilation error messages
-+displayed in the Visual Studio console output window.
-+This can be remedied by adding the
-+Visual C/C++
-+.B /FC
-+compiler option to the \fB$CCFLAGS\fP  variable
-+so that the compiler will print
-+the full path name of any
-+files that cause compilation errors.
-+
-+Example usage:
-+
-+.ES
-+barsrcs = ['bar.cpp'],
-+barincs = ['bar.h'],
-+barlocalincs = ['StdAfx.h']
-+barresources = ['bar.rc','resource.h']
-+barmisc = ['bar_readme.txt']
-+
-+dll = env.SharedLibrary(target = 'bar.dll',
-+                        source = barsrcs)
-+
-+env.MSVSProject(target = 'Bar' + env['MSVSPROJECTSUFFIX'],
-+                srcs = barsrcs,
-+                incs = barincs,
-+                localincs = barlocalincs,
-+                resources = barresources,
-+                misc = barmisc,
-+                buildtarget = dll,
-+                variant = 'Release')
-+.EE
-+
-+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-+.IP MSVSSolution()
-+.IP env.MSVSSolution()
-+Builds a Microsoft Visual Studio solution file.
-+
-+This builds a Visual Studio solution file,
-+based on the version of Visual Studio that is configured
-+(either the latest installed version,
-+or the version specified by
-+.B $MSVS_VERSION
-+in the construction environment).
-+For Visual Studio 6, it will generate a
-+.B .dsw
-+file.
-+For Visual Studio 7 (.NET), it will
-+generate a
-+.B .sln
-+file.
-+
-+The following values must be specified:
-+
-+.BR target :
-+The name of the target .dsw or .sln file.  The correct
-+suffix for the version of Visual Studio must be used, but the value
-+.B $MSVSSOLUTIONSUFFIX
-+will be defined to the correct value (see example below).
-+
-+.BR variant :
-+The name of this particular variant, or a list of variant
-+names (the latter is only supported for MSVS 7 solutions). These are
-+typically things like "Debug" or "Release", but really can be anything
-+you want. For MSVS 7 they may also specify target platform, like this
-+"Debug|Xbox". Default platform is Win32.
-+
-+.BR projects :
-+A list of project file names, or Project nodes returned by calls to the
-+.BR MSVSProject ()
-+Builder,
-+to be placed into the solution file.
-+It should be noted that these file names are NOT added to the $SOURCES
-+environment variable in form of files, but rather as strings.   This
-+is because they represent file names to be added to the solution file,
-+not the source files used to build the solution file.
-+
-+Example Usage:
-+
-+.ES
-+env.MSVSSolution(target = 'Bar' + env['MSVSSOLUTIONSUFFIX'],
-+                 projects = ['bar' + env['MSVSPROJECTSUFFIX']],
-+                 variant = 'Release')
-+.EE
-+
-+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-+.IP Object()
-+.IP env.Object()
-+A synonym for the
-+.BR StaticObject ()
-+builder method.
-+
-+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-+.IP Package()
-+.IP env.Package()
-+Builds software distribution packages.
-+Packages consist of files to install and packaging information.
-+The former may be specified with the \fIsource\fP parameter and may be left out,
-+in which case the &FindInstalledFiles; function will collect
-+all files that have an \fBInstall\fP() or \fBInstallAs\fP() Builder attached.
-+If the \fItarget\fP is not specified
-+it will be deduced from additional information given to this Builder.
-+
-+The packaging information is specified
-+with the help of construction variables documented below.
-+This information is called a tag to stress that
-+some of them can also be attached to files with the &Tag; function.
-+The mandatory ones will complain if they were not specified.
-+They vary depending on chosen target packager.
-+
-+The target packager may be selected with the "PACKAGETYPE" command line
-+option or with the \fB$PACKAGETYPE\fP construction variable. Currently
-+the following packagers available:
-+
-+ * msi - Microsoft Installer
-+ * rpm - Redhat Package Manger
-+ * ipkg - Itsy Package Management System
-+ * tarbz2 - compressed tar
-+ * targz - compressed tar
-+ * zip - zip file
-+ * src_tarbz2 - compressed tar source
-+ * src_targz - compressed tar source
-+ * src_zip - zip file source
-+
-+An updated list is always available under the "package_type" option when
-+running "scons --help" on a project that has packaging activated.
-+.ES
-+env = Environment(tools=['default', 'packaging'])
-+env.Install('/bin/', 'my_program')
-+env.Package( NAME           = 'foo',
-+             VERSION        = '1.2.3',
-+             PACKAGEVERSION = 0,
-+             PACKAGETYPE    = 'rpm',
-+             LICENSE        = 'gpl',
-+             SUMMARY        = 'balalalalal',
-+             DESCRIPTION    = 'this should be really really long',
-+             X_RPM_GROUP    = 'Application/fu',
-+             SOURCE_URL     = 'http://foo.org/foo-1.2.3.tar.gz'
-+        )
-+.EE
-+
-+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-+.IP PCH()
-+.IP env.PCH()
-+Builds a Microsoft Visual C++ precompiled header.
-+Calling this builder method
-+returns a list of two targets: the PCH as the first element, and the object
-+file as the second element. Normally the object file is ignored.
-+This builder method is only
-+provided when Microsoft Visual C++ is being used as the compiler.
-+The PCH builder method is generally used in
-+conjunction with the PCH construction variable to force object files to use
-+the precompiled header:
-+
-+.ES
-+env['PCH'] = env.PCH('StdAfx.cpp')[0]
-+.EE
-+
-+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-+.IP PDF()
-+.IP env.PDF()
-+Builds a \fB.pdf\fP file
-+from a \fB.dvi\fP input file
-+(or, by extension, a \fB.tex\fP,
-+.BR .ltx ,
-+or
-+\fB.latex\fP input file).
-+The suffix specified by the \fB$PDFSUFFIX\fP construction variable
-+(\fB.pdf\fP by default)
-+is added automatically to the target
-+if it is not already present.  Example:
-+
-+.ES
-+# builds from aaa.tex
-+env.PDF(target = 'aaa.pdf', source = 'aaa.tex')
-+# builds bbb.pdf from bbb.dvi
-+env.PDF(target = 'bbb', source = 'bbb.dvi')
-+.EE
-+
-+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-+.IP POInit()
-+.IP env.POInit()
-+This builder belongs to &t-link-msginit; tool. The builder initializes missing
-+\fBPO\fP file(s) if \fB$POAUTOINIT\fP is set.  If
-+\fB$POAUTOINIT\fP is not set (default), \fBPOInit\fP() prints instruction for
-+user (that is supposed to be a translator), telling how the
-+\fBPO\fP file should be initialized. In normal projects
-+.IR you should not use \fBPOInit\fP() and use \fBPOUpdate ()
-+instead\fP. \fBPOUpdate\fP() chooses intelligently between
-+.BR msgmerge(1)\fP and \fBmsginit(1)\fP. \fBPOInit ()
-+always uses \fBmsginit(1)\fP and should be regarded as builder for
-+special purposes or for temporary use (e.g. for quick, one time initialization
-+of a bunch of \fBPO\fP files) or for tests.
-+
-+Target nodes defined through \fBPOInit\fP() are not built by default (they're
-+\fBIgnore\fPd from \fB'.'\fP node) but are added to
-+special \fBAlias\fP (\fB'po-create'\fP by default).
-+The alias name may be changed through the \fB$POCREATE_ALIAS\fP
-+construction variable. All \fBPO\fP files defined through
-+.BR POInit\fP() may be easily initialized by \fBscons po-create .
-+
-+.IR Example 1 .
-+Initialize \fBen.po\fP and \fBpl.po\fP from
-+.BR messages.pot :
-+.ES
-+  # ...
-+  env.POInit(['en', 'pl']) # messages.pot --> [en.po, pl.po] 
-+.EE
-+.IP
-+.IR Example 2 .
-+Initialize \fBen.po\fP and \fBpl.po\fP from
-+.BR foo.pot :
-+.ES
-+  # ...
-+  env.POInit(['en', 'pl'], ['foo']) # foo.pot --> [en.po, pl.po] 
-+.EE
-+.IP
-+.IR Example 3 .
-+Initialize \fBen.po\fP and \fBpl.po\fP from
-+\fBfoo.pot\fP but using \fB$POTDOMAIN\fP construction
-+variable:
-+.ES
-+  # ...
-+  env.POInit(['en', 'pl'], POTDOMAIN='foo') # foo.pot --> [en.po, pl.po] 
-+.EE
-+.IP
-+.IR Example 4 .
-+Initialize \fBPO\fP files for languages defined in
-+\fBLINGUAS\fP file. The files will be initialized from template
-+.BR messages.pot :
-+.ES
-+  # ...
-+  env.POInit(LINGUAS_FILE = 1) # needs 'LINGUAS' file
-+.EE
-+.IP
-+.IR Example 5 .
-+Initialize \fBen.po\fP and \fBpl.pl\fP
-+\fBPO\fP files plus files for languages defined in
-+\fBLINGUAS\fP file. The files will be initialized from template
-+.BR messages.pot :
-+.ES
-+  # ...
-+  env.POInit(['en', 'pl'], LINGUAS_FILE = 1)
-+.EE
-+.IP
-+.IR Example 6 .
-+You may preconfigure your environment first, and then initialize
-+\fBPO\fP files:
-+.ES
-+  # ...
-+  env['POAUTOINIT'] = 1
-+  env['LINGUAS_FILE'] = 1
-+  env['POTDOMAIN'] = 'foo'
-+  env.POInit()
-+.EE
-+which has same efect as:
-+.ES
-+  # ...
-+  env.POInit(POAUTOINIT = 1, LINGUAS_FILE = 1, POTDOMAIN = 'foo')
-+.EE
-+
-+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-+.IP PostScript()
-+.IP env.PostScript()
-+Builds a \fB.ps\fP file
-+from a \fB.dvi\fP input file
-+(or, by extension, a \fB.tex\fP,
-+.BR .ltx ,
-+or
-+\fB.latex\fP input file).
-+The suffix specified by the \fB$PSSUFFIX\fP construction variable
-+(\fB.ps\fP by default)
-+is added automatically to the target
-+if it is not already present.  Example:
-+
-+.ES
-+# builds from aaa.tex
-+env.PostScript(target = 'aaa.ps', source = 'aaa.tex')
-+# builds bbb.ps from bbb.dvi
-+env.PostScript(target = 'bbb', source = 'bbb.dvi')
-+.EE
-+
-+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-+.IP POTUpdate()
-+.IP env.POTUpdate()
-+The builder belongs to &t-link-xgettext; tool. The builder updates target
-+\fBPOT\fP file if exists or creates one if it doesn't. The node is
-+not built by default (i.e. it is \fBIgnore\fPd from
-+\fB'.'\fP), but only on demand (i.e.  when given
-+\fBPOT\fP file is required or when special alias is invoked). This
-+builder adds its targe node (\fBmessages.pot\fP, say) to a
-+special alias (\fBpot-update\fP by default, see
-+\fB$POTUPDATE_ALIAS\fP) so you can update/create them easily with
-+\fBscons pot-update\fP. The file is not written until there is no
-+real change in internationalized messages (or in comments that enter
-+\fBPOT\fP file). 
-+
-+<note> 
-+You may see \fBxgettext(1)\fP being invoked by the
-+&t-link-xgettext; tool even if there is no real change in internationalized
-+messages (so the \fBPOT\fP file is not being updated).  This
-+happens every time  a source file has changed. In such case we invoke
-+\fBxgettext(1)\fP and compare its output with the content of
-+\fBPOT\fP file to decide whether the file should be updated or
-+not.</para></note>
-+
-+.I "Example 1."
-+Let's create \fBpo/\fP directory and place following
-+\fBSConstruct\fP script there:
-+.ES
-+  # SConstruct in 'po/' subdir
-+  env = Environment( tools = ['default', 'xgettext'] )
-+  env.POTUpdate(['foo'], ['../a.cpp', '../b.cpp'])
-+  env.POTUpdate(['bar'], ['../c.cpp', '../d.cpp'])
-+.EE
-+.IP
-+      
-+Then invoke scons few times:
-+.ES
-+  user@host:$ scons             # Does not create foo.pot nor bar.pot
-+  user@host:$ scons foo.pot     # Updates or creates foo.pot
-+  user@host:$ scons pot-update  # Updates or creates foo.pot and bar.pot
-+  user@host:$ scons -c          # Does not clean foo.pot nor bar.pot.
-+.EE
-+the results shall be as the comments above say.
-+
-+.I "Example 2."
-+The \fBPOTUpdate\fP() builder may be used with no target specified, in which
-+case default target \fBmessages.pot\fP will be used. The
-+default target may also be overridden by setting \fB$POTDOMAIN\fP construction
-+variable or providing it as an override to \fBPOTUpdate\fP() builder:
-+.ES    
-+  # SConstruct script
-+  env = Environment( tools = ['default', 'xgettext'] )
-+  env['POTDOMAIN'] = "foo"
-+  env.POTUpdate(source = ["a.cpp", "b.cpp"]) # Creates foo.pot ...
-+  env.POTUpdate(POTDOMAIN = "bar", source = ["c.cpp", "d.cpp"]) # and bar.pot
-+.EE
-+.IP
-+.I "Example 3."
-+The sources may be specified within separate file, for example
-+.BR POTFILES.in :
-+.ES      
-+  # POTFILES.in in 'po/' subdirectory
-+  ../a.cpp
-+  ../b.cpp
-+  # end of file
-+.EE
-+.IP
-+    
-+The name of the file (\fBPOTFILES.in\fP) containing the list of
-+sources is provided via \fB$XGETTEXTFROM\fP:
-+.ES      
-+  # SConstruct file in 'po/' subdirectory
-+  env = Environment( tools = ['default', 'xgettext'] )
-+  env.POTUpdate(XGETTEXTFROM = 'POTFILES.in')
-+.EE
-+.IP
-+    
-+
-+.I "Example 4."
-+You may use \fB$XGETTEXTPATH\fP to define source search path. Assume, for
-+example, that you have files \fBa.cpp\fP,
-+.BR b.cpp\fP, \fBpo/SConstruct ,
-+.BR po/POTFILES.in\fP. Then your \fBPOT -related
-+files could look as below:
-+.ES
-+  # POTFILES.in in 'po/' subdirectory
-+  a.cpp
-+  b.cpp
-+  # end of file
-+.EE
-+
-+.ES
-+  # SConstruct file in 'po/' subdirectory
-+  env = Environment( tools = ['default', 'xgettext'] )
-+  env.POTUpdate(XGETTEXTFROM = 'POTFILES.in', XGETTEXTPATH='../')
-+.EE
-+.IP
-+.I "Example 5."
-+Multiple search directories may be defined within a list, i.e.
-+\fBXGETTEXTPATH = ['dir1', 'dir2', ...]\fP. The order in the list
-+determines the search order of source files. The path to the first file found
-+is used.
-+
-+Let's create \fB0/1/po/SConstruct\fP script:
-+.ES
-+  # SConstruct file in '0/1/po/' subdirectory
-+  env = Environment( tools = ['default', 'xgettext'] )
-+  env.POTUpdate(XGETTEXTFROM = 'POTFILES.in', XGETTEXTPATH=['../', '../../'])
-+.EE
-+and \fB0/1/po/POTFILES.in\fP:
-+.ES
-+  # POTFILES.in in '0/1/po/' subdirectory
-+  a.cpp
-+  # end of file
-+.EE
-+Write two \fB*.cpp\fP files, the first one is
-+.BR 0/a.cpp :
-+.ES
-+  /* 0/a.cpp */
-+  gettext("Hello from ../../a.cpp")
-+.EE
-+and the second is \fB0/1/a.cpp\fP:
-+.ES
-+  /* 0/1/a.cpp */
-+  gettext("Hello from ../a.cpp")
-+.EE
-+then run scons. You'll obtain \fB0/1/po/messages.pot\fP with the
-+message \fB"Hello from ../a.cpp"\fP. When you reverse order in
-+\fI$XGETTEXTFOM\fP, i.e. when you write SConscript as
-+.ES
-+  # SConstruct file in '0/1/po/' subdirectory
-+  env = Environment( tools = ['default', 'xgettext'] )
-+  env.POTUpdate(XGETTEXTFROM = 'POTFILES.in', XGETTEXTPATH=['../../', '../'])
-+.EE
-+.IP
-+ then the \fBmessages.pot\fP will contain
-+\fBmsgid "Hello from ../../a.cpp"\fP line and not 
-+.BR msgid "Hello from ../a.cpp" .
-+
-+
-+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-+.IP POUpdate()
-+.IP env.POUpdate()
-+The builder belongs to &t-link-msgmerge; tool. The builder updates
-+\fBPO\fP files with \fBmsgmerge(1)\fP, or initializes
-+missing \fBPO\fP files as described in documentation of
-+&t-link-msginit; tool and \fBPOInit\fP() builder (see also
-+\fB$POAUTOINIT\fP). Note, that \fBPOUpdate\fP() \fIdoes not add its
-+targets to \fBpo-create\fP alias\fP as \fBPOInit\fP()
-+does.
-+
-+Target nodes defined through \fBPOUpdate\fP() are not built by default
-+(they're \fBIgnore\fPd from \fB'.'\fP node). Instead,
-+they are added automatically to special \fBAlias\fP 
-+(\fB'po-update'\fP by default). The alias name may be changed
-+through the \fB$POUPDATE_ALIAS\fP construction variable.  You can easily
-+update \fBPO\fP files in your project by \fBscons
-+po-update\fP.
-+
-+.I "Example 1."
-+Update \fBen.po\fP and \fBpl.po\fP from
-+.BR messages.pot\fP template (see also \fB$POTDOMAIN ),
-+assuming that the later one exists or there is rule to build it (see
-+.BR POTUpdate ()):
-+.ES
-+  # ...
-+  env.POUpdate(['en','pl']) # messages.pot --> [en.po, pl.po]
-+.EE
-+.IP
-+.I "Example 2."
-+Update \fBen.po\fP and \fBpl.po\fP from
-+\fBfoo.pot\fP template:
-+.ES
-+  # ...
-+  env.POUpdate(['en', 'pl'], ['foo']) # foo.pot -->  [en.po, pl.pl]
-+.EE
-+.IP
-+.I "Example 3."
-+Update \fBen.po\fP and \fBpl.po\fP from
-+\fBfoo.pot\fP (another version):
-+.ES
-+  # ...
-+  env.POUpdate(['en', 'pl'], POTDOMAIN='foo') # foo.pot -- > [en.po, pl.pl]
-+.EE
-+.IP
-+.I "Example 4."
-+Update files for languages defined in \fBLINGUAS\fP file. The
-+files are updated from \fBmessages.pot\fP template:
-+.ES
-+  # ...
-+  env.POUpdate(LINGUAS_FILE = 1) # needs 'LINGUAS' file
-+.EE
-+.IP
-+.I "Example 5."
-+Same as above, but update from \fBfoo.pot\fP template:
-+.ES
-+  # ...
-+  env.POUpdate(LINGUAS_FILE = 1, source = ['foo'])
-+.EE
-+.IP
-+.I "Example 6."
-+Update \fBen.po\fP and \fBpl.po\fP plus files for
-+languages defined in \fBLINGUAS\fP file. The files are updated
-+from \fBmessages.pot\fP template:
-+.ES
-+  # produce 'en.po', 'pl.po' + files defined in 'LINGUAS':
-+  env.POUpdate(['en', 'pl' ], LINGUAS_FILE = 1) 
-+.EE
-+.IP
-+.I "Example 7."
-+Use \fB$POAUTOINIT\fP to automatically initialize \fBPO\fP file
-+if it doesn't exist:
-+.ES
-+  # ...
-+  env.POUpdate(LINGUAS_FILE = 1, POAUTOINIT = 1)
-+.EE
-+.IP
-+.I "Example 8."
-+Update \fBPO\fP files for languages defined in
-+\fBLINGUAS\fP file. The files are updated from
-+\fBfoo.pot\fP template. All necessary settings are
-+pre-configured via environment.
-+.ES
-+  # ...
-+  env['POAUTOINIT'] = 1
-+  env['LINGUAS_FILE'] = 1
-+  env['POTDOMAIN'] = 'foo'
-+  env.POUpdate()
-+.EE
-+
-+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-+.IP Program()
-+.IP env.Program()
-+Builds an executable given one or more object files
-+or C, C++, D, or Fortran source files.
-+If any C, C++, D or Fortran source files are specified,
-+then they will be automatically
-+compiled to object files using the
-+.BR Object ()
-+builder method;
-+see that builder method's description for
-+a list of legal source file suffixes
-+and how they are interpreted.
-+The target executable file prefix
-+(specified by the \fB$PROGPREFIX\fP construction variable; nothing by default)
-+and suffix
-+(specified by the \fB$PROGSUFFIX\fP construction variable;
-+by default, \fB.exe\fP on Windows systems,
-+nothing on POSIX systems)
-+are automatically added to the target if not already present.
-+Example:
-+
-+.ES
-+env.Program(target = 'foo', source = ['foo.o', 'bar.c', 'baz.f'])
-+.EE
-+
-+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-+.IP RES()
-+.IP env.RES()
-+Builds a Microsoft Visual C++ resource file.
-+This builder method is only provided
-+when Microsoft Visual C++ or MinGW is being used as the compiler. The
-+.B .res
-+(or
-+.B .o
-+for MinGW) suffix is added to the target name if no other suffix is given.
-+The source
-+file is scanned for implicit dependencies as though it were a C file.
-+Example:
-+
-+.ES
-+env.RES('resource.rc')
-+.EE
-+
-+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-+.IP RMIC()
-+.IP env.RMIC()
-+Builds stub and skeleton class files
-+for remote objects
-+from Java \fB.class\fP files.
-+The target is a directory
-+relative to which the stub
-+and skeleton class files will be written.
-+The source can be the names of \fB.class\fP files,
-+or the objects return from the
-+.BR Java ()
-+builder method.
-+
-+If the construction variable
-+.B $JAVACLASSDIR
-+is set, either in the environment
-+or in the call to the
-+.BR RMIC ()
-+builder method itself,
-+then the value of the variable
-+will be stripped from the
-+beginning of any \fB.class \fP
-+file names.
-+
-+.ES
-+classes = env.Java(target = 'classdir', source = 'src')
-+env.RMIC(target = 'outdir1', source = classes)
-+
-+env.RMIC(target = 'outdir2',
-+         source = ['package/foo.class', 'package/bar.class'])
-+
-+env.RMIC(target = 'outdir3',
-+         source = ['classes/foo.class', 'classes/bar.class'],
-+         JAVACLASSDIR = 'classes')
-+.EE
-+
-+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-+.IP RPCGenClient()
-+.IP env.RPCGenClient()
-+Generates an RPC client stub (\fB_clnt.c\fP) file
-+from a specified RPC (\fB.x\fP) source file.
-+Because rpcgen only builds output files
-+in the local directory,
-+the command will be executed
-+in the source file's directory by default.
-+
-+.ES
-+# Builds src/rpcif_clnt.c
-+env.RPCGenClient('src/rpcif.x')
-+.EE
-+
-+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-+.IP RPCGenHeader()
-+.IP env.RPCGenHeader()
-+Generates an RPC header (\fB.h\fP) file
-+from a specified RPC (\fB.x\fP) source file.
-+Because rpcgen only builds output files
-+in the local directory,
-+the command will be executed
-+in the source file's directory by default.
-+
-+.ES
-+# Builds src/rpcif.h
-+env.RPCGenHeader('src/rpcif.x')
-+.EE
-+
-+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-+.IP RPCGenService()
-+.IP env.RPCGenService()
-+Generates an RPC server-skeleton (\fB_svc.c\fP) file
-+from a specified RPC (\fB.x\fP) source file.
-+Because rpcgen only builds output files
-+in the local directory,
-+the command will be executed
-+in the source file's directory by default.
-+
-+.ES
-+# Builds src/rpcif_svc.c
-+env.RPCGenClient('src/rpcif.x')
-+.EE
-+
-+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-+.IP RPCGenXDR()
-+.IP env.RPCGenXDR()
-+Generates an RPC XDR routine (\fB_xdr.c\fP) file
-+from a specified RPC (\fB.x\fP) source file.
-+Because rpcgen only builds output files
-+in the local directory,
-+the command will be executed
-+in the source file's directory by default.
-+
-+.ES
-+# Builds src/rpcif_xdr.c
-+env.RPCGenClient('src/rpcif.x')
-+.EE
-+
-+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-+.IP SharedLibrary()
-+.IP env.SharedLibrary()
-+Builds a shared library
-+(\fB.so\fP on a POSIX system,
-+\fB.dll\fP on Windows)
-+given one or more object files
-+or C, C++, D or Fortran source files.
-+If any source files are given,
-+then they will be automatically
-+compiled to object files.
-+The static library prefix and suffix (if any)
-+are automatically added to the target.
-+The target library file prefix
-+(specified by the \fB$SHLIBPREFIX\fP construction variable;
-+by default, \fBlib\fP on POSIX systems,
-+nothing on Windows systems)
-+and suffix
-+(specified by the \fB$SHLIBSUFFIX\fP construction variable;
-+by default, \fB.dll\fP on Windows systems,
-+\fB.so\fP on POSIX systems)
-+are automatically added to the target if not already present.
-+Example:
-+
-+.ES
-+env.SharedLibrary(target = 'bar', source = ['bar.c', 'foo.o'])
-+.EE
-+.IP
-+On Windows systems, the
-+.BR SharedLibrary ()
-+builder method will always build an import
-+(\fB.lib\fP) library
-+in addition to the shared (\fB.dll\fP) library,
-+adding a \fB.lib\fP library with the same basename
-+if there is not already a \fB.lib\fP file explicitly
-+listed in the targets.
-+
-+Any object files listed in the
-+.B source
-+must have been built for a shared library
-+(that is, using the
-+.BR SharedObject ()
-+builder method).
-+.B scons
-+will raise an error if there is any mismatch.
-+
-+On some platforms, there is a distinction between a shared library
-+(loaded automatically by the system to resolve external references)
-+and a loadable module (explicitly loaded by user action).
-+For maximum portability, use the \fBLoadableModule\fP() builder for the latter.
-+
-+When the \fB$SHLIBVERSION\fP construction variable is defined a versioned
-+shared library is created. This modifies the \fB$SHLINKFLAGS\fP as required,
-+adds the version number to the library name, and creates the symlinks that
-+are needed. \fB$SHLIBVERSION\fP needs to be of the form X.Y.Z, where X
-+and Y are numbers, and Z is a number but can also contain letters to designate
-+alpha, beta, or release candidate patch levels.
-+
-+This builder may create multiple links to the library. On a POSIX system,
-+for the shared library libbar.so.2.3.1, the links created would be
-+libbar.so, libbar.so.2, and libbar.so.2.3; on a Darwin (OSX) system
-+the library would be libbar.2.3.1.dylib and the link would be
-+libbar.dylib.
-+
-+On Windows systems, specifying
-+.B register=1
-+will cause the \fB.dll\fP to be
-+registered after it is built using REGSVR32.
-+The command that is run
-+("regsvr32" by default) is determined by \fB$REGSVR\fP construction
-+variable, and the flags passed are determined by \fB$REGSVRFLAGS\fP.  By
-+default, \fB$REGSVRFLAGS\fP includes the \fB/s\fP option,
-+to prevent dialogs from popping
-+up and requiring user attention when it is run.  If you change
-+\fB$REGSVRFLAGS\fP, be sure to include the \fB/s\fP option.
-+For example,
-+
-+.ES
-+env.SharedLibrary(target = 'bar',
-+                  source = ['bar.cxx', 'foo.obj'],
-+                  register=1)
-+.EE
-+.IP
-+will register \fBbar.dll\fP as a COM object
-+when it is done linking it.
-+
-+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-+.IP SharedObject()
-+.IP env.SharedObject()
-+Builds an object file for
-+inclusion in a shared library.
-+Source files must have one of the same set of extensions
-+specified above for the
-+.BR StaticObject ()
-+builder method.
-+On some platforms building a shared object requires additional
-+compiler option
-+(e.g. \fB\-fPIC\fP for gcc)
-+in addition to those needed to build a
-+normal (static) object, but on some platforms there is no difference between a
-+shared object and a normal (static) one. When there is a difference, SCons
-+will only allow shared objects to be linked into a shared library, and will
-+use a different suffix for shared objects. On platforms where there is no
-+difference, SCons will allow both normal (static)
-+and shared objects to be linked into a
-+shared library, and will use the same suffix for shared and normal
-+(static) objects.
-+The target object file prefix
-+(specified by the \fB$SHOBJPREFIX\fP construction variable;
-+by default, the same as \fB$OBJPREFIX\fP)
-+and suffix
-+(specified by the \fB$SHOBJSUFFIX\fP construction variable)
-+are automatically added to the target if not already present.
-+Examples:
-+
-+.ES
-+env.SharedObject(target = 'ddd', source = 'ddd.c')
-+env.SharedObject(target = 'eee.o', source = 'eee.cpp')
-+env.SharedObject(target = 'fff.obj', source = 'fff.for')
-+.EE
-+.IP
-+Note that the source files will be scanned
-+according to the suffix mappings in the
-+.B SourceFileScanner
-+object.
-+See the section "Scanner Objects,"
-+below, for more information.
-+
-+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-+.IP StaticLibrary()
-+.IP env.StaticLibrary()
-+Builds a static library given one or more object files
-+or C, C++, D or Fortran source files.
-+If any source files are given,
-+then they will be automatically
-+compiled to object files.
-+The static library prefix and suffix (if any)
-+are automatically added to the target.
-+The target library file prefix
-+(specified by the \fB$LIBPREFIX\fP construction variable;
-+by default, \fBlib\fP on POSIX systems,
-+nothing on Windows systems)
-+and suffix
-+(specified by the \fB$LIBSUFFIX\fP construction variable;
-+by default, \fB.lib\fP on Windows systems,
-+\fB.a\fP on POSIX systems)
-+are automatically added to the target if not already present.
-+Example:
-+
-+.ES
-+env.StaticLibrary(target = 'bar', source = ['bar.c', 'foo.o'])
-+.EE
-+.IP
-+Any object files listed in the
-+.B source
-+must have been built for a static library
-+(that is, using the
-+.BR StaticObject ()
-+builder method).
-+.B scons
-+will raise an error if there is any mismatch.
-+
-+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-+.IP StaticObject()
-+.IP env.StaticObject()
-+Builds a static object file
-+from one or more C, C++, D, or Fortran source files.
-+Source files must have one of the following extensions:
-+
-+.ES
-+  .asm    assembly language file
-+  .ASM    assembly language file
-+  .c      C file
-+  .C      Windows:  C file
-+          POSIX:  C++ file
-+  .cc     C++ file
-+  .cpp    C++ file
-+  .cxx    C++ file
-+  .cxx    C++ file
-+  .c++    C++ file
-+  .C++    C++ file
-+  .d      D file
-+  .f      Fortran file
-+  .F      Windows:  Fortran file
-+          POSIX:  Fortran file + C pre-processor
-+  .for    Fortran file
-+  .FOR    Fortran file
-+  .fpp    Fortran file + C pre-processor
-+  .FPP    Fortran file + C pre-processor
-+  .m      Object C file
-+  .mm     Object C++ file
-+  .s      assembly language file
-+  .S      Windows:  assembly language file
-+          ARM: CodeSourcery Sourcery Lite
-+  .sx     assembly language file + C pre-processor
-+          POSIX:  assembly language file + C pre-processor
-+  .spp    assembly language file + C pre-processor
-+  .SPP    assembly language file + C pre-processor
-+.EE
-+.IP
-+The target object file prefix
-+(specified by the \fB$OBJPREFIX\fP construction variable; nothing by default)
-+and suffix
-+(specified by the \fB$OBJSUFFIX\fP construction variable;
-+\fB.obj\fP on Windows systems,
-+\fB.o\fP on POSIX systems)
-+are automatically added to the target if not already present.
-+Examples:
-+
-+.ES
-+env.StaticObject(target = 'aaa', source = 'aaa.c')
-+env.StaticObject(target = 'bbb.o', source = 'bbb.c++')
-+env.StaticObject(target = 'ccc.obj', source = 'ccc.f')
-+.EE
-+.IP
-+Note that the source files will be scanned
-+according to the suffix mappings in
-+.B SourceFileScanner
-+object.
-+See the section "Scanner Objects,"
-+below, for more information.
-+
-+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-+.IP Substfile()
-+.IP env.Substfile()
-+The \fBSubstfile\fP() builder generates a single text file
-+by concatenating the source files.
-+Nested lists of sources are flattened. 
-+\fB$LINESEPARATOR\fP is used to separate the source files;
-+see the description of \fBTextfile\fP() for details.
-+
-+If a single source file is present with an \fB.in\fP suffix,
-+the suffix is stripped and the remainder is used as the default target name.
-+
-+The prefix and suffix specified by the \fB$SUBSTFILEPREFIX\fP
-+and \fB$SUBSTFILESUFFIX\fP construction variables
-+(the null string by default in both cases)
-+are automatically added to the target if they are not already present.
-+
-+If a construction variable named \fB$SUBST_DICT\fP is present,
-+it may be either a Python dictionary or a sequence of (key,value) tuples.
-+If the former,
-+the dictionary is converted into a list of tuples in an arbitrary order,
-+so if one key is a prefix of another key
-+or if one substitution could be further expanded by another subsitition,
-+it is unpredictible whether the expansion will occur.
-+
-+Any occurences in the source of a key
-+are replaced by the corresponding value,
-+which may be a Python callable function or a string.
-+If a value is a function,
-+it is first called (with no arguments) to produce a string.
-+The string is \fIsubst\fP-expanded
-+and the result replaces the key.
-+
-+.ES
-+env = Environment(tools = ['default', 'textfile'])
-+
-+env['prefix'] = '/usr/bin'
-+script_dict = {'@prefix@': '/bin', @exec_prefix@: '$prefix'}
-+env.Substfile('script.in', SUBST_DICT = script_dict)
-+
-+conf_dict = {'%VERSION%': '1.2.3', '%BASE%': 'MyProg'}
-+env.Substfile('config.h.in', conf_dict, SUBST_DICT = conf_dict)
-+
-+# UNPREDICTABLE - one key is a prefix of another
-+bad_foo = {'$foo': '$foo', '$foobar': '$foobar'}
-+env.Substfile('foo.in', SUBST_DICT = bad_foo)
-+
-+# PREDICTABLE - keys are applied longest first
-+good_foo = [('$foobar', '$foobar'), ('$foo', '$foo')]
-+env.Substfile('foo.in', SUBST_DICT = good_foo)
-+
-+# UNPREDICTABLE - one substitution could be futher expanded
-+bad_bar = {'@bar@': '@soap@', '@soap@': 'lye'}
-+env.Substfile('bar.in', SUBST_DICT = bad_bar)
-+
-+# PREDICTABLE - substitutions are expanded in order
-+good_bar = (('@bar@', '@soap@'), ('@soap@', 'lye'))
-+env.Substfile('bar.in', SUBST_DICT = good_bar)
-+
-+# the SUBST_DICT may be in common (and not an override)
-+substutions = {}
-+subst = Environment(tools = ['textfile'], SUBST_DICT = substitutions)
-+substitutions['@foo@'] = 'foo'
-+subst['SUBST_DICT']['@bar@'] = 'bar'
-+subst.Substfile('pgm1.c', [Value('#include "@foo@.h"'),
-+                           Value('#include "@bar@.h"'),
-+                           "common.in",
-+                           "pgm1.in"
-+                          ])
-+subst.Substfile('pgm2.c', [Value('#include "@foo@.h"'),
-+                           Value('#include "@bar@.h"'),
-+                           "common.in",
-+                           "pgm2.in"
-+                          ])
-+
-+.EE
-+
-+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-+.IP Tar()
-+.IP env.Tar()
-+Builds a tar archive of the specified files
-+and/or directories.
-+Unlike most builder methods,
-+the
-+.BR Tar ()
-+builder method may be called multiple times
-+for a given target;
-+each additional call
-+adds to the list of entries
-+that will be built into the archive.
-+Any source directories will
-+be scanned for changes to
-+any on-disk files,
-+regardless of whether or not
-+.B scons
-+knows about them from other Builder or function calls.
-+
-+.ES
-+env.Tar('src.tar', 'src')
-+
-+# Create the stuff.tar file.
-+env.Tar('stuff', ['subdir1', 'subdir2'])
-+# Also add "another" to the stuff.tar file.
-+env.Tar('stuff', 'another')
-+
-+# Set TARFLAGS to create a gzip-filtered archive.
-+env = Environment(TARFLAGS = '-c -z')
-+env.Tar('foo.tar.gz', 'foo')
-+
-+# Also set the suffix to .tgz.
-+env = Environment(TARFLAGS = '-c -z',
-+                  TARSUFFIX = '.tgz')
-+env.Tar('foo')
-+.EE
-+
-+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-+.IP Textfile()
-+.IP env.Textfile()
-+The \fBTextfile\fP() builder generates a single text file.
-+The source strings constitute the lines;
-+nested lists of sources are flattened. 
-+\fB$LINESEPARATOR\fP is used to separate the strings.
-+
-+If present, the \fB$SUBST_DICT\fP construction variable
-+is used to modify the strings before they are written;
-+see the \fBSubstfile\fP() description for details.
-+
-+The prefix and suffix specified by the \fB$TEXTFILEPREFIX\fP
-+and \fB$TEXTFILESUFFIX\fP construction variables
-+(the null string and \fB.txt\fP by default, respectively)
-+are automatically added to the target if they are not already present.
-+Examples:
-+
-+.ES
-+# builds/writes foo.txt
-+env.Textfile(target = 'foo.txt', source = ['Goethe', 42, 'Schiller'])
-+
-+# builds/writes bar.txt
-+env.Textfile(target = 'bar',
-+             source = ['lalala', 'tanteratei'],
-+             LINESEPARATOR='|*')
-+
-+# nested lists are flattened automatically
-+env.Textfile(target = 'blob', 
-+             source = ['lalala', ['Goethe', 42 'Schiller'], 'tanteratei'])
-+
-+# files may be used as input by wraping them in File()
-+env.Textfile(target = 'concat',  # concatenate files with a marker between
-+             source = [File('concat1'), File('concat2')],
-+             LINESEPARATOR = '====================\\n')
-+
-+Results are:
-+foo.txt
-+  ....8<----
-+  Goethe
-+  42
-+  Schiller
-+  ....8<---- (no linefeed at the end)
-+
-+bar.txt:
-+  ....8<----
-+  lalala|*tanteratei
-+  ....8<---- (no linefeed at the end)
-+
-+blob.txt
-+  ....8<----
-+  lalala
-+  Goethe
-+  42
-+  Schiller
-+  tanteratei
-+  ....8<---- (no linefeed at the end)
-+.EE
-+
-+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-+.IP Translate()
-+.IP env.Translate()
-+This pseudo-builder belongs to &t-link-gettext; toolset. The builder extracts
-+internationalized messages from source files, updates \fBPOT\fP
-+template (if necessary) and then updates \fBPO\fP translations (if
-+necessary). If \fB$POAUTOINIT\fP is set, missing \fBPO\fP files
-+will be automatically created (i.e. without translator person intervention).
-+The variables \fB$LINGUAS_FILE\fP and \fB$POTDOMAIN\fP are taken into
-+acount too. All other construction variables used by \fBPOTUpdate\fP(), and
-+\fBPOUpdate\fP() work here too.
-+
-+.IR Example 1 .
-+The simplest way is to specify input files and output languages inline in
-+a SCons script when invoking \fBTranslate\fP()
-+.ES
-+# SConscript in 'po/' directory
-+env = Environment( tools = ["default", "gettext"] )
-+env['POAUTOINIT'] = 1
-+env.Translate(['en','pl'], ['../a.cpp','../b.cpp']) 
-+.EE
-+.IP
-+.IR Example 2 .
-+If you wish, you may also stick to conventional style known from
-+<productname>autotools</productname>, i.e. using
-+\fBPOTFILES.in\fP and \fBLINGUAS\fP files
-+.ES
-+# LINGUAS
-+en pl 
-+#end
-+.EE
-+
-+.ES
-+# POTFILES.in
-+a.cpp
-+b.cpp
-+# end
-+.EE
-+
-+.ES
-+# SConscript
-+env = Environment( tools = ["default", "gettext"] )
-+env['POAUTOINIT'] = 1
-+env['XGETTEXTPATH'] = ['../']
-+env.Translate(LINGUAS_FILE = 1, XGETTEXTFROM = 'POTFILES.in') 
-+.EE
-+.IP
-+The last approach is perhaps the recommended one. It allows easily split
-+internationalization/localization onto separate SCons scripts, where a script
-+in source tree is responsible for translations (from sources to
-+\fBPO\fP files) and script(s) under variant directories are
-+responsible for compilation of \fBPO\fP to \fBMO\fP
-+files to and for installation of \fBMO\fP files. The "gluing
-+factor" synchronizing these two scripts is then the content of
-+\fBLINGUAS\fP file.  Note, that the updated
-+\fBPOT\fP and \fBPO\fP files are usually going to be
-+committed back to the repository, so they must be updated within the source
-+directory (and not in variant directories). Additionally, the file listing of
-+\fBpo/\fP directory contains \fBLINGUAS\fP file,
-+so the source tree looks familiar to translators, and they may work with the
-+project in their usual way.
-+
-+.IR Example 3 .
-+Let's prepare a development tree as below
-+.ES
-+ project/
-+  + SConstruct
-+  + build/        
-+  + src/
-+      + po/
-+          + SConscript
-+          + SConscript.i18n
-+          + POTFILES.in
-+          + LINGUAS
-+.EE
-+with \fBbuild\fP being variant directory. Write the top-level
-+\fBSConstruct\fP script as follows
-+.ES
-+  # SConstruct
-+  env = Environment( tools = ["default", "gettext"] )
-+  VariantDir('build', 'src', duplicate = 0)
-+  env['POAUTOINIT'] = 1
-+  SConscript('src/po/SConscript.i18n', exports = 'env')
-+  SConscript('build/po/SConscript', exports = 'env')
-+.EE
-+the \fBsrc/po/SConscript.i18n\fP as
-+.ES
-+  # src/po/SConscript.i18n
-+  Import('env')
-+  env.Translate(LINGUAS_FILE=1, XGETTEXTFROM='POTFILES.in', XGETTEXTPATH=['../'])
-+.EE
-+and the \fBsrc/po/SConscript\fP
-+.ES
-+  # src/po/SConscript
-+  Import('env')
-+  env.MOFiles(LINGUAS_FILE = 1)
-+.EE
-+Such setup produces \fBPOT\fP and \fBPO\fP files
-+under source tree in \fBsrc/po/\fP and binary
-+\fBMO\fP files under variant tree in
-+\fBbuild/po/\fP. This way the \fBPOT\fP and
-+\fBPO\fP files are separated from other output files, which must
-+not be committed back to source repositories (e.g. \fBMO\fP
-+files).
-+
-+<note>
-+In above example, the \fBPO\fP files are not updated,
-+nor created automatically when you issue \fBscons '.'\fP command.
-+The files must be updated (created) by hand via \fBscons
-+po-update\fP and then \fBMO\fP files can be compiled by
-+running \fBscons '.'\fP.</para></note>
-+
-+
-+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-+.IP TypeLibrary()
-+.IP env.TypeLibrary()
-+Builds a Windows type library (\fB.tlb\fP)
-+file from an input IDL file (\fB.idl\fP).
-+In addition, it will build the associated inteface stub and
-+proxy source files,
-+naming them according to the base name of the \fB.idl\fP file.
-+For example,
-+
-+.ES
-+env.TypeLibrary(source="foo.idl")
-+.EE
-+.IP
-+Will create \fBfoo.tlb\fP,
-+.BR foo.h ,
-+.BR foo_i.c ,
-+.B foo_p.c
-+and
-+.B foo_data.c
-+files.
-+
-+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-+.IP Uic()
-+.IP env.Uic()
-+Builds a header file, an implementation file and a moc file from an ui file.
-+and returns the corresponding nodes in the above order.
-+This builder is only available after using the tool 'qt'. Note: you can
-+specify \fB.ui\fP files directly as source
-+files to the \fBProgram\fP(),
-+\fBLibrary\fP() and \fBSharedLibrary\fP() builders
-+without using this builder. Using this builder lets you override the standard
-+naming conventions (be careful: prefixes are always prepended to names of
-+built files; if you don't want prefixes, you may set them to ``).
-+See the \fB$QTDIR\fP variable for more information.
-+Example:
-+
-+.ES
-+env.Uic('foo.ui') # -> ['foo.h', 'uic_foo.cc', 'moc_foo.cc']
-+env.Uic(target = Split('include/foo.h gen/uicfoo.cc gen/mocfoo.cc'),
-+        source = 'foo.ui') # -> ['include/foo.h', 'gen/uicfoo.cc', 'gen/mocfoo.cc']
-+.EE
-+
-+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-+.IP Zip()
-+.IP env.Zip()
-+Builds a zip archive of the specified files
-+and/or directories.
-+Unlike most builder methods,
-+the
-+.BR Zip ()
-+builder method may be called multiple times
-+for a given target;
-+each additional call
-+adds to the list of entries
-+that will be built into the archive.
-+Any source directories will
-+be scanned for changes to
-+any on-disk files,
-+regardless of whether or not
-+.B scons
-+knows about them from other Builder or function calls.
-+
-+.ES
-+env.Zip('src.zip', 'src')
-+
-+# Create the stuff.zip file.
-+env.Zip('stuff', ['subdir1', 'subdir2'])
-+# Also add "another" to the stuff.tar file.
-+env.Zip('stuff', 'another')
-+.EE
-+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-+'\" 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
-+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-+
-+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-+.TP
-+.RI Action( action ", [" cmd/str/fun ", [" var ", ...]] [option=" value ", ...])"
-+.TP
-+.IR env .Action( action ", [" cmd/str/fun ", [" var ", ...]] [option=" value ", ...])"
-+Creates an Action object for
-+the specified
-+.IR action .
-+See the section "Action Objects,"
-+below, for a complete explanation of the arguments and behavior.
-+
-+Note that the
-+.BR env.Action ()
-+form of the invocation will expand
-+construction variables in any argument strings,
-+including the
-+.I action
-+argument, at the time it is called
-+using the construction variables in the
-+.I env
-+construction environment through which
-+.BR env.Action ()
-+was called.
-+The
-+.BR Action ()
-+form delays all variable expansion
-+until the Action object is actually used.
-+
-+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-+.TP
-+.RI AddMethod( object ", " function ", [" name ])
-+.TP
-+.IR env .AddMethod( function ", [" name ])
-+When called with the
-+.BR AddMethod ()
-+form,
-+adds the specified
-+.I function
-+to the specified
-+.I object
-+as the specified method
-+.IR name .
-+When called with the
-+.BR env.AddMethod ()
-+form,
-+adds the specified
-+.I function
-+to the construction environment
-+.I env
-+as the specified method
-+.IR name .
-+In both cases, if
-+.I name
-+is omitted or
-+.BR None ,
-+the name of the
-+specified
-+.I function
-+itself is used for the method name.
-+
-+Examples:
-+
-+.ES
-+# Note that the first argument to the function to
-+# be attached as a method must be the object through
-+# which the method will be called; the Python
-+# convention is to call it 'self'.
-+def my_method(self, arg):
-+    print "my_method() got", arg
-+
-+# Use the global AddMethod() function to add a method
-+# to the Environment class.  This
-+AddMethod(Environment, my_method)
-+env = Environment()
-+env.my_method('arg')
-+
-+# Add the function as a method, using the function
-+# name for the method call.
-+env = Environment()
-+env.AddMethod(my_method, 'other_method_name')
-+env.other_method_name('another arg')
-+.EE
-+
-+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-+.TP
-+.RI AddOption( arguments )
-+This function adds a new command-line option to be recognized.
-+The specified
-+.I arguments
-+are the same as supported by the standard Python
-+.BR optparse.add_option ()
-+method (with a few additional capabilities noted below);
-+see the documentation for
-+.B optparse
-+for a thorough discussion of its option-processing capabities.
-+
-+In addition to the arguments and values supported by the
-+.BR optparse.add_option ()
-+method,
-+the SCons
-+.BR AddOption ()
-+function allows you to set the
-+.B nargs
-+keyword value to
-+.B '?'
-+(a string with just the question mark)
-+to indicate that the specified long option(s) take(s) an
-+.I optional
-+argument.
-+When
-+.B "nargs = '?'"
-+is passed to the
-+.BR AddOption ()
-+function, the
-+.B const
-+keyword argument
-+may be used to supply the "default"
-+value that should be used when the
-+option is specified on the command line
-+without an explicit argument.
-+
-+If no
-+.B default=
-+keyword argument is supplied when calling
-+.BR AddOption (),
-+the option will have a default value of
-+.BR None .
-+
-+Once a new command-line option has been added with
-+.BR AddOption (),
-+the option value may be accessed using
-+.BR GetOption ()
-+or
-+.BR env.GetOption ().
-+The value may also be set, using
-+.BR SetOption ()
-+or
-+.BR env.SetOption (),
-+if conditions in a
-+.B SConscript
-+require overriding any default value.
-+Note, however, that a
-+value specified on the command line will
-+.I always
-+override a value set by any SConscript file.
-+
-+Any specified
-+.B help=
-+strings for the new option(s)
-+will be displayed by the
-+.B \-H
-+or
-+.B \-h
-+options
-+(the latter only if no other help text is
-+specified in the SConscript files).
-+The help text for the local options specified by
-+.BR AddOption ()
-+will appear below the SCons options themselves,
-+under a separate
-+.B "Local Options"
-+heading.
-+The options will appear in the help text
-+in the order in which the
-+.BR AddOption ()
-+calls occur.
-+
-+Example:
-+
-+.ES
-+AddOption('--prefix',
-+          dest='prefix',
-+          nargs=1, type='string',
-+          action='store',
-+          metavar='DIR',
-+          help='installation prefix')
-+env = Environment(PREFIX = GetOption('prefix'))
-+.EE
-+
-+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-+.TP
-+.RI AddPostAction( target ", " action )
-+.TP
-+.IR env .AddPostAction( target ", " action )
-+Arranges for the specified
-+.I action
-+to be performed
-+after the specified
-+.I target
-+has been built.
-+The specified action(s) may be
-+an Action object, or anything that
-+can be converted into an Action object
-+(see below).
-+
-+When multiple targets are supplied,
-+the action may be called multiple times,
-+once after each action that generates
-+one or more targets in the list.
-+
-+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-+.TP
-+.RI AddPreAction( target ", " action )
-+.TP
-+.IR env .AddPreAction( target ", " action )
-+Arranges for the specified
-+.I action
-+to be performed
-+before the specified
-+.I target
-+is built.
-+The specified action(s) may be
-+an Action object, or anything that
-+can be converted into an Action object
-+(see below).
-+
-+When multiple targets are specified,
-+the action(s) may be called multiple times,
-+once before each action that generates
-+one or more targets in the list.
-+
-+Note that if any of the targets are built in multiple steps,
-+the action will be invoked just
-+before the "final" action that specifically
-+generates the specified target(s).
-+For example, when building an executable program
-+from a specified source
-+.B .c
-+file via an intermediate object file:
-+
-+.ES
-+foo = Program('foo.c')
-+AddPreAction(foo, 'pre_action')
-+.EE
-+.IP
-+The specified
-+.B pre_action
-+would be executed before
-+.B scons
-+calls the link command that actually
-+generates the executable program binary
-+.BR foo ,
-+not before compiling the
-+.B foo.c
-+file into an object file.
-+
-+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-+.TP
-+.RI Alias( alias ", [" targets ", [" action ]])
-+.TP
-+.IR env .Alias( alias ", [" targets ", [" action ]])
-+Creates one or more phony targets that
-+expand to one or more other targets.
-+An optional
-+.I action
-+(command)
-+or list of actions
-+can be specified that will be executed
-+whenever the any of the alias targets are out-of-date.
-+Returns the Node object representing the alias,
-+which exists outside of any file system.
-+This Node object, or the alias name,
-+may be used as a dependency of any other target,
-+including another alias.
-+.BR Alias ()
-+can be called multiple times for the same
-+alias to add additional targets to the alias,
-+or additional actions to the list for this alias.
-+
-+Examples:
-+
-+.ES
-+Alias('install')
-+Alias('install', '/usr/bin')
-+Alias(['install', 'install-lib'], '/usr/local/lib')
-+
-+env.Alias('install', ['/usr/local/bin', '/usr/local/lib'])
-+env.Alias('install', ['/usr/local/man'])
-+
-+env.Alias('update', ['file1', 'file2'], "update_database $SOURCES")
-+.EE
-+
-+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-+.TP
-+.RI AllowSubstExceptions([ exception ", ...])"
-+Specifies the exceptions that will be allowed
-+when expanding construction variables.
-+By default,
-+any construction variable expansions that generate a
-+.B NameError
-+or
-+.B IndexError
-+exception will expand to a
-+.B ''
-+(a null string) and not cause scons to fail.
-+All exceptions not in the specified list
-+will generate an error message
-+and terminate processing.
-+
-+If
-+.BR AllowSubstExceptions ()
-+is called multiple times,
-+each call completely overwrites the previous list
-+of allowed exceptions.
-+
-+Example:
-+
-+.ES
-+# Requires that all construction variable names exist.
-+# (You may wish to do this if you want to enforce strictly
-+# that all construction variables must be defined before use.)
-+AllowSubstExceptions()
-+
-+# Also allow a string containing a zero-division expansion
-+# like '${1 / 0}' to evalute to ''.
-+AllowSubstExceptions(IndexError, NameError, ZeroDivisionError)
-+.EE
-+
-+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-+.TP
-+.RI AlwaysBuild( target ", ...)"
-+.TP
-+.IR env .AlwaysBuild( target ", ...)"
-+Marks each given
-+.I target
-+so that it is always assumed to be out of date,
-+and will always be rebuilt if needed.
-+Note, however, that
-+.BR AlwaysBuild ()
-+does not add its target(s) to the default target list,
-+so the targets will only be built
-+if they are specified on the command line,
-+or are a dependent of a target specified on the command line--but
-+they will
-+.I always
-+be built if so specified.
-+Multiple targets can be passed in to a single call to
-+.BR AlwaysBuild ().
-+
-+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-+.TP
-+.IR env .Append(key= val ", [...])"
-+Appends the specified keyword arguments
-+to the end of construction variables in the environment.
-+If the Environment does not have
-+the specified construction variable,
-+it is simply added to the environment.
-+If the values of the construction variable
-+and the keyword argument are the same type,
-+then the two values will be simply added together.
-+Otherwise, the construction variable
-+and the value of the keyword argument
-+are both coerced to lists,
-+and the lists are added together.
-+(See also the Prepend method, below.)
-+
-+Example:
-+
-+.ES
-+env.Append(CCFLAGS = ' -g', FOO = ['foo.yyy'])
-+.EE
-+
-+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-+.TP
-+.IR env .AppendENVPath( name ", " newpath ", [" envname ", " sep ", " delete_existing ])
-+This appends new path elements to the given path in the
-+specified external environment
-+.RB ( ENV
-+by default).
-+This will only add
-+any particular path once (leaving the last one it encounters and
-+ignoring the rest, to preserve path order),
-+and to help assure this,
-+will normalize all paths (using
-+.B os.path.normpath
-+and
-+.BR os.path.normcase ).
-+This can also handle the
-+case where the given old path variable is a list instead of a
-+string, in which case a list will be returned instead of a string.
-+
-+If 
-+.I delete_existing
-+is 0, then adding a path that already exists
-+will not move it to the end; it will stay where it is in the list.
-+
-+Example:
-+
-+.ES
-+print 'before:',env['ENV']['INCLUDE']
-+include_path = '/foo/bar:/foo'
-+env.AppendENVPath('INCLUDE', include_path)
-+print 'after:',env['ENV']['INCLUDE']
-+
-+yields:
-+before: /foo:/biz
-+after: /biz:/foo/bar:/foo
-+.EE
-+
-+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-+.TP
-+.IR env .AppendUnique(key= val ", [...], delete_existing=" 0)
-+Appends the specified keyword arguments
-+to the end of construction variables in the environment.
-+If the Environment does not have
-+the specified construction variable,
-+it is simply added to the environment.
-+If the construction variable being appended to is a list,
-+then any value(s) that already exist in the
-+construction variable will
-+.I not
-+be added again to the list.
-+However, if delete_existing is 1, 
-+existing matching values are removed first, so
-+existing values in the arg list move to the end of the list.
-+
-+Example:
-+
-+.ES
-+env.AppendUnique(CCFLAGS = '-g', FOO = ['foo.yyy'])
-+.EE
-+
-+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-+.TP
-+.IR env .BitKeeper()
-+A factory function that
-+returns a Builder object
-+to be used to fetch source files
-+using BitKeeper.
-+The returned Builder
-+is intended to be passed to the
-+.BR SourceCode ()
-+function.
-+
-+This function is deprecated.  For details, see the entry for the
-+.BR SourceCode ()
-+function.
-+
-+Example:
-+
-+.ES
-+env.SourceCode('.', env.BitKeeper())
-+.EE
-+
-+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-+.TP
-+.RI BuildDir( build_dir ", " src_dir ", [" duplicate ])
-+.TP
-+.IR env .BuildDir( build_dir ", " src_dir ", [" duplicate ])
-+Deprecated synonyms for
-+.BR VariantDir ()
-+and
-+.BR env.VariantDir ().
-+The
-+.I build_dir
-+argument becomes the
-+.I variant_dir
-+argument of
-+.BR VariantDir ()
-+or
-+.BR env.VariantDir ().
-+
-+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-+.TP
-+.RI Builder( action ", [" arguments ])
-+.TP
-+.IR env .Builder( action ", [" arguments ])
-+Creates a Builder object for
-+the specified
-+.IR action .
-+See the section "Builder Objects,"
-+below, for a complete explanation of the arguments and behavior.
-+
-+Note that the
-+.BR env.Builder ()
-+form of the invocation will expand
-+construction variables in any arguments strings,
-+including the
-+.I action
-+argument,
-+at the time it is called
-+using the construction variables in the
-+.I env
-+construction environment through which
-+.BR env.Builder ()
-+was called.
-+The
-+.BR Builder ()
-+form delays all variable expansion
-+until after the Builder object is actually called.
-+
-+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-+.TP
-+.RI CacheDir( cache_dir )
-+.TP
-+.IR env .CacheDir( cache_dir )
-+Specifies that
-+.B scons
-+will maintain a cache of derived files in
-+.IR cache_dir .
-+The derived files in the cache will be shared
-+among all the builds using the same
-+.BR CacheDir ()
-+call.
-+Specifying a
-+.I cache_dir
-+of
-+.B None
-+disables derived file caching.
-+
-+Calling
-+.BR env.CacheDir ()
-+will only affect targets built
-+through the specified construction environment.
-+Calling
-+.BR CacheDir ()
-+sets a global default
-+that will be used by all targets built
-+through construction environments
-+that do
-+.I not
-+have an
-+.BR env.CacheDir ()
-+specified.
-+
-+When a
-+.BR CacheDir ()
-+is being used and
-+.B scons
-+finds a derived file that needs to be rebuilt,
-+it will first look in the cache to see if a
-+derived file has already been built
-+from identical input files and an identical build action
-+(as incorporated into the MD5 build signature).
-+If so,
-+.B scons
-+will retrieve the file from the cache.
-+If the derived file is not present in the cache,
-+.B scons
-+will rebuild it and
-+then place a copy of the built file in the cache
-+(identified by its MD5 build signature),
-+so that it may be retrieved by other
-+builds that need to build the same derived file
-+from identical inputs.
-+
-+Use of a specified
-+.BR CacheDir ()
-+may be disabled for any invocation
-+by using the
-+.B \-\-cache-disable
-+option.
-+
-+If the
-+.B \-\-cache-force
-+option is used,
-+.B scons
-+will place a copy of
-+.I all
-+derived files in the cache,
-+even if they already existed
-+and were not built by this invocation.
-+This is useful to populate a cache
-+the first time
-+.BR CacheDir ()
-+is added to a build,
-+or after using the
-+.B \-\-cache-disable
-+option.
-+
-+When using
-+.BR CacheDir (),
-+.B scons
-+will report,
-+"Retrieved `file' from cache,"
-+unless the
-+.B \-\-cache-show
-+option is being used.
-+When the
-+.B \-\-cache-show
-+option is used,
-+.B scons
-+will print the action that
-+.I would
-+have been used to build the file,
-+without any indication that
-+the file was actually retrieved from the cache.
-+This is useful to generate build logs
-+that are equivalent regardless of whether
-+a given derived file has been built in-place
-+or retrieved from the cache.
-+
-+The
-+.BR NoCache ()
-+method can be used to disable caching of specific files.  This can be
-+useful if inputs and/or outputs of some tool are impossible to
-+predict or prohibitively large.
-+
-+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-+.TP
-+.RI Clean( targets ", " files_or_dirs )
-+.TP
-+.IR env .Clean( targets ", " files_or_dirs )
-+This specifies a list of files or directories which should be removed
-+whenever the targets are specified with the
-+.B \-c
-+command line option.
-+The specified targets may be a list
-+or an individual target.
-+Multiple calls to
-+.BR Clean ()
-+are legal,
-+and create new targets or add files and directories to the
-+clean list for the specified targets.
-+
-+Multiple files or directories should be specified
-+either as separate arguments to the
-+.BR Clean ()
-+method, or as a list.
-+.BR Clean ()
-+will also accept the return value of any of the construction environment
-+Builder methods.
-+Examples:
-+
-+The related
-+.BR NoClean ()
-+function overrides calling
-+.BR Clean ()
-+for the same target,
-+and any targets passed to both functions will
-+.I not
-+be removed by the
-+.B \-c
-+option.
-+
-+Examples:
-+
-+.ES
-+Clean('foo', ['bar', 'baz'])
-+Clean('dist', env.Program('hello', 'hello.c'))
-+Clean(['foo', 'bar'], 'something_else_to_clean')
-+.EE
-+.IP
-+In this example,
-+installing the project creates a subdirectory for the documentation.
-+This statement causes the subdirectory to be removed
-+if the project is deinstalled.
-+.ES
-+Clean(docdir, os.path.join(docdir, projectname))
-+.EE
-+
-+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-+.TP
-+.IR env .Clone([key= val ", ...])"
-+Returns a separate copy of a construction environment.
-+If there are any keyword arguments specified,
-+they are added to the returned copy,
-+overwriting any existing values
-+for the keywords.
-+
-+Example:
-+
-+.ES
-+env2 = env.Clone()
-+env3 = env.Clone(CCFLAGS = '-g')
-+.EE
-+.IP
-+Additionally, a list of tools and a toolpath may be specified, as in
-+the Environment constructor:
-+
-+.ES
-+def MyTool(env): env['FOO'] = 'bar'
-+env4 = env.Clone(tools = ['msvc', MyTool])
-+.EE
-+.IP
-+The
-+.I parse_flags
-+keyword argument is also recognized:
-+
-+.ES
-+# create an environment for compiling programs that use wxWidgets
-+wx_env = env.Clone(parse_flags = '!wx-config --cflags --cxxflags')
-+.EE
-+
-+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-+.TP
-+.RI Command( target ", " source ", " action ", [key=" val ", ...])"
-+.TP
-+.IR env .Command( target ", " source ", " action ", [key=" val ", ...])"
-+Executes a specific action
-+(or list of actions)
-+to build a target file or files.
-+This is more convenient
-+than defining a separate Builder object
-+for a single special-case build.
-+
-+As a special case, the
-+.I source_scanner
-+keyword argument can
-+be used to specify
-+a Scanner object
-+that will be used to scan the sources.
-+(The global
-+.B DirScanner
-+object can be used
-+if any of the sources will be directories
-+that must be scanned on-disk for
-+changes to files that aren't
-+already specified in other Builder of function calls.)
-+
-+Any other keyword arguments specified override any
-+same-named existing construction variables.
-+
-+An action can be an external command,
-+specified as a string,
-+or a callable Python object;
-+see "Action Objects," below,
-+for more complete information.
-+Also note that a string specifying an external command
-+may be preceded by an
-+.B @
-+(at-sign)
-+to suppress printing the command in question,
-+or by a
-+.B \-
-+(hyphen)
-+to ignore the exit status of the external command.
-+
-+Examples:
-+
-+.ES
-+env.Command('foo.out', 'foo.in',
-+            "$FOO_BUILD < $SOURCES > $TARGET")
-+
-+env.Command('bar.out', 'bar.in',
-+            ["rm -f $TARGET",
-+             "$BAR_BUILD < $SOURCES > $TARGET"],
-+            ENV = {'PATH' : '/usr/local/bin/'})
-+
-+def rename(env, target, source):
-+    import os
-+    os.rename('.tmp', str(target[0]))
-+
-+env.Command('baz.out', 'baz.in',
-+            ["$BAZ_BUILD < $SOURCES > .tmp",
-+	     rename ])
-+.EE
-+.IP
-+Note that the
-+.BR Command ()
-+function will usually assume, by default,
-+that the specified targets and/or sources are Files,
-+if no other part of the configuration
-+identifies what type of entry it is.
-+If necessary, you can explicitly specify
-+that targets or source nodes should
-+be treated as directoriese
-+by using the
-+.BR Dir ()
-+or
-+.BR env.Dir ()
-+functions.
-+
-+Examples:
-+
-+.ES
-+env.Command('ddd.list', Dir('ddd'), 'ls -l $SOURCE > $TARGET')
-+
-+env['DISTDIR'] = 'destination/directory'
-+env.Command(env.Dir('$DISTDIR')), None, make_distdir)
-+.EE
-+.IP
-+(Also note that SCons will usually
-+automatically create any directory necessary to hold a target file,
-+so you normally don't need to create directories by hand.)
-+
-+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-+.TP
-+.RI Configure( env ", [" custom_tests ", " conf_dir ", " log_file ", " config_h ])
-+.TP
-+.IR env .Configure([ custom_tests ", " conf_dir ", " log_file ", " config_h ])
-+Creates a Configure object for integrated
-+functionality similar to GNU autoconf.
-+See the section "Configure Contexts,"
-+below, for a complete explanation of the arguments and behavior.
-+
-+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-+.TP
-+.IR env .Copy([key= val ", ...])"
-+A now-deprecated synonym for
-+.BR env.Clone ().
-+
-+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-+.TP
-+.IR env .CVS( repository ", " module )
-+A factory function that
-+returns a Builder object
-+to be used to fetch source files
-+from the specified
-+CVS
-+.IR repository .
-+The returned Builder
-+is intended to be passed to the
-+.BR SourceCode ()
-+function.
-+
-+This function is deprecated.  For details, see the entry for the
-+.BR SourceCode ()
-+function.
-+
-+The optional specified
-+.I module
-+will be added to the beginning
-+of all repository path names;
-+this can be used, in essence,
-+to strip initial directory names
-+from the repository path names,
-+so that you only have to
-+replicate part of the repository
-+directory hierarchy in your
-+local build directory.
-+
-+Examples:
-+
-+.ES
-+# Will fetch foo/bar/src.c
-+# from /usr/local/CVSROOT/foo/bar/src.c.
-+env.SourceCode('.', env.CVS('/usr/local/CVSROOT'))
-+
-+# Will fetch bar/src.c
-+# from /usr/local/CVSROOT/foo/bar/src.c.
-+env.SourceCode('.', env.CVS('/usr/local/CVSROOT', 'foo'))
-+
-+# Will fetch src.c
-+# from /usr/local/CVSROOT/foo/bar/src.c.
-+env.SourceCode('.', env.CVS('/usr/local/CVSROOT', 'foo/bar'))
-+.EE
-+
-+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-+.TP
-+.RI Decider( function )
-+.TP
-+.IR env .Decider( function )
-+Specifies that all up-to-date decisions for
-+targets built through this construction environment
-+will be handled by the specified
-+.IR function .
-+The
-+.I function
-+can be one of the following strings
-+that specify the type of decision function
-+to be performed:
-+
-+.RS 10
-+.TP 6
-+.B timestamp-newer
-+Specifies that a target shall be considered out of date and rebuilt
-+if the dependency's timestamp is newer than the target file's timestamp.
-+This is the behavior of the classic Make utility,
-+and
-+.B make
-+can be used a synonym for
-+.BR timestamp-newer .
-+.TP 6
-+.B timestamp-match
-+Specifies that a target shall be considered out of date and rebuilt
-+if the dependency's timestamp is different than the
-+timestamp recorded the last time the target was built.
-+This provides behavior very similar to the classic Make utility
-+(in particular, files are not opened up so that their
-+contents can be checksummed)
-+except that the target will also be rebuilt if a
-+dependency file has been restored to a version with an
-+.I earlier
-+timestamp, such as can happen when restoring files from backup archives.
-+.TP 6
-+.B MD5
-+Specifies that a target shall be considered out of date and rebuilt
-+if the dependency's content has changed sine the last time
-+the target was built,
-+as determined be performing an MD5 checksum
-+on the dependency's contents
-+and comparing it to the checksum recorded the
-+last time the target was built.
-+.B content
-+can be used as a synonym for
-+.BR MD5 .
-+.TP 6
-+.B MD5-timestamp
-+Specifies that a target shall be considered out of date and rebuilt
-+if the dependency's content has changed sine the last time
-+the target was built,
-+except that dependencies with a timestamp that matches
-+the last time the target was rebuilt will be
-+assumed to be up-to-date and
-+.I not
-+rebuilt.
-+This provides behavior very similar
-+to the
-+.B MD5
-+behavior of always checksumming file contents,
-+with an optimization of not checking
-+the contents of files whose timestamps haven't changed.
-+The drawback is that SCons will
-+.I not
-+detect if a file's content has changed
-+but its timestamp is the same,
-+as might happen in an automated script
-+that runs a build,
-+updates a file,
-+and runs the build again,
-+all within a single second.
-+.RE
-+
-+Examples:
-+
-+.ES
-+# Use exact timestamp matches by default.
-+Decider('timestamp-match')
-+
-+# Use MD5 content signatures for any targets built
-+# with the attached construction environment.
-+env.Decider('content')
-+.EE
-+.IP
-+In addition to the above already-available functions,
-+the
-+.I function
-+argument may be an actual Python function
-+that takes the following three arguments:
-+
-+.RS 10
-+.IP dependency
-+The Node (file) which
-+should cause the
-+.I target
-+to be rebuilt
-+if it has "changed" since the last tme
-+.I target
-+was built.
-+.IP target
-+The Node (file) being built.
-+In the normal case,
-+this is what should get rebuilt
-+if the
-+.I dependency
-+has "changed."
-+.IP prev_ni
-+Stored information about the state of the
-+.I dependency
-+the last time the
-+.I target
-+was built.
-+This can be consulted to match various
-+file characteristics
-+such as the timestamp,
-+size, or content signature.
-+.RE
-+
-+The
-+.I function
-+should return a
-+.B True
-+(non-zero)
-+value if the
-+.I dependency
-+has "changed" since the last time
-+the
-+.I target
-+was built
-+(indicating that the target
-+.I should
-+be rebuilt),
-+and
-+.B False
-+(zero)
-+otherwise
-+(indicating that the target should
-+.I not
-+be rebuilt).
-+Note that the decision can be made
-+using whatever criteria are appopriate.
-+Ignoring some or all of the function arguments
-+is perfectly normal.
-+
-+Example:
-+
-+.ES
-+def my_decider(dependency, target, prev_ni):
-+    return not os.path.exists(str(target))
-+
-+env.Decider(my_decider)
-+.EE
-+
-+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-+.TP
-+.RI Default( targets )
-+.TP
-+.IR env .Default( targets )
-+This specifies a list of default targets,
-+which will be built by
-+.B scons
-+if no explicit targets are given on the command line.
-+Multiple calls to
-+.BR Default ()
-+are legal,
-+and add to the list of default targets.
-+
-+Multiple targets should be specified as
-+separate arguments to the
-+.BR Default ()
-+method, or as a list.
-+.BR Default ()
-+will also accept the Node returned by any
-+of a construction environment's
-+builder methods.
-+
-+Examples:
-+
-+.ES
-+Default('foo', 'bar', 'baz')
-+env.Default(['a', 'b', 'c'])
-+hello = env.Program('hello', 'hello.c')
-+env.Default(hello)
-+.EE
-+.IP
-+An argument to
-+.BR Default ()
-+of
-+.B None
-+will clear all default targets.
-+Later calls to
-+.BR Default ()
-+will add to the (now empty) default-target list
-+like normal.
-+
-+The current list of targets added using the
-+.BR Default ()
-+function or method is available in the
-+.B DEFAULT_TARGETS
-+list;
-+see below.
-+
-+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-+.TP
-+.RI DefaultEnvironment([ args ])
-+Creates and returns a default construction environment object.
-+This construction environment is used internally by SCons
-+in order to execute many of the global functions in this list,
-+and to fetch source files transparently
-+from source code management systems.
-+
-+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-+.TP
-+.RI Depends( target ", " dependency )
-+.TP
-+.IR env .Depends( target ", " dependency )
-+Specifies an explicit dependency;
-+the
-+.I target
-+will be rebuilt
-+whenever the
-+.I dependency
-+has changed.
-+Both the specified
-+.I target
-+and
-+.I dependency
-+can be a string
-+(usually the path name of a file or directory)
-+or Node objects,
-+or a list of strings or Node objects
-+(such as returned by a Builder call).
-+This should only be necessary
-+for cases where the dependency
-+is not caught by a Scanner
-+for the file.
-+
-+Example:
-+
-+.ES
-+env.Depends('foo', 'other-input-file-for-foo')
-+
-+mylib = env.Library('mylib.c')
-+installed_lib = env.Install('lib', mylib)
-+bar = env.Program('bar.c')
-+
-+# Arrange for the library to be copied into the installation
-+# directory before trying to build the "bar" program.
-+# (Note that this is for example only.  A "real" library
-+# dependency would normally be configured through the $LIBS
-+# and $LIBPATH variables, not using an env.Depends() call.)
-+
-+env.Depends(bar, installed_lib)
-+.EE
-+
-+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-+.TP
-+.IR env .Dictionary([ vars ])
-+Returns a dictionary object
-+containing copies of all of the
-+construction variables in the environment.
-+If there are any variable names specified,
-+only the specified construction
-+variables are returned in the dictionary.
-+
-+Example:
-+
-+.ES
-+dict = env.Dictionary()
-+cc_dict = env.Dictionary('CC', 'CCFLAGS', 'CCCOM')
-+.EE
-+
-+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-+.TP
-+.RI Dir( name ", [" directory ])
-+.TP
-+.IR env .Dir( name ", [" directory ])
-+This returns a Directory Node,
-+an object that represents the specified directory
-+.IR name .
-+.I name
-+can be a relative or absolute path.
-+.I directory
-+is an optional directory that will be used as the parent directory.
-+If no
-+.I directory
-+is specified, the current script's directory is used as the parent.
-+
-+If
-+.I name
-+is a list, SCons returns a list of Dir nodes.
-+Construction variables are expanded in
-+.IR name .
-+
-+Directory Nodes can be used anywhere you
-+would supply a string as a directory name
-+to a Builder method or function.
-+Directory Nodes have attributes and methods
-+that are useful in many situations;
-+see "File and Directory Nodes," below.
-+
-+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-+.TP
-+.IR env .Dump([ key ])
-+Returns a pretty printable representation of the environment.
-+.IR key ,
-+if not
-+.BR None ,
-+should be a string containing the name of the variable of interest.
-+
-+This SConstruct:
-+
-+.ES
-+env=Environment()
-+print env.Dump('CCCOM')
-+.EE
-+.IP
-+will print:
-+
-+.ES
-+\'$CC -c -o $TARGET $CCFLAGS $CPPFLAGS $_CPPDEFFLAGS $_CPPINCFLAGS $SOURCES'
-+.EE
-+.IP
-+While this SConstruct:
-+
-+.ES
-+env=Environment()
-+print env.Dump()
-+.EE
-+.IP
-+will print:
-+.ES
-+{ 'AR': 'ar',
-+  'ARCOM': '$AR $ARFLAGS $TARGET $SOURCES\\n$RANLIB $RANLIBFLAGS $TARGET',
-+  'ARFLAGS': ['r'],
-+  'AS': 'as',
-+  'ASCOM': '$AS $ASFLAGS -o $TARGET $SOURCES',
-+  'ASFLAGS': [],
-+  ...
-+.EE
-+
-+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-+.TP
-+.RI EnsurePythonVersion( major ", " minor )
-+.TP
-+.IR env .EnsurePythonVersion( major ", " minor )
-+Ensure that the Python version is at least
-+.IR major\fP.\fIminor .
-+This function will
-+print out an error message and exit SCons with a non-zero exit code if the
-+actual Python version is not late enough.
-+
-+Example:
-+
-+.ES
-+EnsurePythonVersion(2,2)
-+.EE
-+
-+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-+.TP
-+.RI EnsureSConsVersion( major ", " minor ", [" revision ])
-+.TP
-+.IR env .EnsureSConsVersion( major ", " minor ", [" revision ])
-+Ensure that the SCons version is at least
-+.IR major.minor ,
-+or
-+.IR major.minor.revision .
-+if
-+.I revision
-+is specified.
-+This function will
-+print out an error message and exit SCons with a non-zero exit code if the
-+actual SCons version is not late enough.
-+
-+Examples:
-+
-+.ES
-+EnsureSConsVersion(0,14)
-+
-+EnsureSConsVersion(0,96,90)
-+.EE
-+
-+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-+.TP
-+.RI Environment([key= value ", ...])"
-+.TP
-+.IR env .Environment([key= value ", ...])"
-+Return a new construction environment
-+initialized with the specified
-+.IR key = value
-+pairs.
-+
-+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-+.TP
-+.RI Execute( action ", [" strfunction ", " varlist ])
-+.TP
-+.IR env .Execute( action ", [" strfunction ", " varlist ])
-+Executes an Action object.
-+The specified
-+.I action
-+may be an Action object
-+(see the section "Action Objects,"
-+below, for a complete explanation of the arguments and behavior),
-+or it may be a command-line string,
-+list of commands,
-+or executable Python function,
-+each of which will be converted
-+into an Action object
-+and then executed.
-+The exit value of the command
-+or return value of the Python function
-+will be returned.
-+
-+Note that
-+.B scons
-+will print an error message if the executed
-+.I action
-+fails--that is,
-+exits with or returns a non-zero value.
-+.B scons
-+will
-+.IR not ,
-+however,
-+automatically terminate the build
-+if the specified
-+.I action
-+fails.
-+If you want the build to stop in response to a failed
-+.BR Execute ()
-+call,
-+you must explicitly check for a non-zero return value:
-+
-+.ES
-+Execute(Copy('file.out', 'file.in'))
-+
-+if Execute("mkdir sub/dir/ectory"):
-+    # The mkdir failed, don't try to build.
-+    Exit(1)
-+.EE
-+
-+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-+.TP
-+.RI Exit([ value ])
-+.TP
-+.IR env .Exit([ value ])
-+This tells
-+.B scons
-+to exit immediately
-+with the specified
-+.IR value .
-+A default exit value of
-+.B 0
-+(zero)
-+is used if no value is specified.
-+
-+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-+.TP
-+.RI Export( vars )
-+.TP
-+.IR env .Export( vars )
-+This tells
-+.B scons
-+to export a list of variables from the current
-+SConscript file to all other SConscript files.
-+The exported variables are kept in a global collection,
-+so subsequent calls to
-+.BR Export ()
-+will over-write previous exports that have the same name.
-+Multiple variable names can be passed to
-+.BR Export ()
-+as separate arguments or as a list.
-+Keyword arguments can be used to provide names and their values.
-+A dictionary can be used to map variables to a different name when exported.
-+Both local variables and global variables can be exported.
-+
-+Examples:
-+
-+.ES
-+env = Environment()
-+# Make env available for all SConscript files to Import().
-+Export("env")
-+
-+package = 'my_name'
-+# Make env and package available for all SConscript files:.
-+Export("env", "package")
-+
-+# Make env and package available for all SConscript files:
-+Export(["env", "package"])
-+
-+# Make env available using the name debug:
-+Export(debug = env)
-+
-+# Make env available using the name debug:
-+Export({"debug":env})
-+.EE
-+.IP
-+Note that the
-+.BR SConscript ()
-+function supports an
-+.I exports
-+argument that makes it easier to to export a variable or
-+set of variables to a single SConscript file.
-+See the description of the
-+.BR SConscript ()
-+function, below.
-+
-+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-+.TP
-+.RI File( name ", [" directory ])
-+.TP
-+.IR env .File( name ", [" directory ])
-+This returns a
-+File Node,
-+an object that represents the specified file
-+.IR name .
-+.I name
-+can be a relative or absolute path.
-+.I directory
-+is an optional directory that will be used as the parent directory.
-+
-+If
-+.I name
-+is a list, SCons returns a list of File nodes.
-+Construction variables are expanded in
-+.IR name .
-+
-+File Nodes can be used anywhere you
-+would supply a string as a file name
-+to a Builder method or function.
-+File Nodes have attributes and methods
-+that are useful in many situations;
-+see "File and Directory Nodes," below.
-+
-+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-+.TP
-+.RI FindFile( file ", " dirs )
-+.TP
-+.IR env .FindFile( file ", " dirs )
-+Search for
-+.I file
-+in the path specified by
-+.IR dirs .
-+.I dirs
-+may be a list of directory names or a single directory name.
-+In addition to searching for files that exist in the filesystem,
-+this function also searches for derived files
-+that have not yet been built.
-+
-+Example:
-+
-+.ES
-+foo = env.FindFile('foo', ['dir1', 'dir2'])
-+.EE
-+
-+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-+.TP
-+.RI FindInstalledFiles()
-+.TP
-+.IR env .FindInstalledFiles()
-+Returns the list of targets set up by the
-+.BR Install ()
-+or
-+.BR InstallAs ()
-+builders.
-+
-+This function serves as a convenient method to select the contents of
-+a binary package.
-+
-+Example:
-+
-+.ES
-+Install( '/bin', [ 'executable_a', 'executable_b' ] )
-+
-+# will return the file node list
-+# [ '/bin/executable_a', '/bin/executable_b' ]
-+FindInstalledFiles()
-+
-+Install( '/lib', [ 'some_library' ] )
-+
-+# will return the file node list
-+# [ '/bin/executable_a', '/bin/executable_b', '/lib/some_library' ]
-+FindInstalledFiles()
-+.EE
-+
-+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-+.TP
-+.RI FindPathDirs( variable )
-+Returns a function
-+(actually a callable Python object)
-+intended to be used as the
-+.I path_function
-+of a Scanner object.
-+The returned object will look up the specified
-+.I variable
-+in a construction environment
-+and treat the construction variable's value as a list of
-+directory paths that should be searched
-+(like
-+.BR $CPPPATH ,
-+.BR $LIBPATH ,
-+etc.).
-+
-+Note that use of
-+.BR FindPathDirs ()
-+is generally preferable to
-+writing your own
-+.I path_function
-+for the following reasons:
-+1) The returned list will contain all appropriate directories
-+found in source trees
-+(when
-+.BR VariantDir ()
-+is used)
-+or in code repositories
-+(when
-+.BR Repository ()
-+or the
-+.B \-Y
-+option are used).
-+2) scons will identify expansions of
-+.I variable
-+that evaluate to the same list of directories as,
-+in fact, the same list,
-+and avoid re-scanning the directories for files,
-+when possible.
-+
-+Example:
-+
-+.ES
-+def my_scan(node, env, path, arg):
-+    # Code to scan file contents goes here...
-+    return include_files
-+
-+scanner = Scanner(name = 'myscanner',
-+                  function = my_scan,
-+                  path_function = FindPathDirs('MYPATH'))
-+.EE
-+
-+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-+.TP
-+.RI FindSourceFiles(node= '"."')
-+.TP
-+.IR env .FindSourceFiles(node= '"."')
-+Returns the list of nodes which serve as the source of the built files.
-+It does so by inspecting the dependency tree starting at the optional
-+argument
-+.I node
-+which defaults to the '"."'-node. It will then return all leaves of
-+.IR node .
-+These are all children which have no further children.
-+
-+This function is a convenient method to select the contents of a Source
-+Package.
-+
-+Example:
-+
-+.ES
-+Program( 'src/main_a.c' )
-+Program( 'src/main_b.c' )
-+Program( 'main_c.c' )
-+
-+# returns ['main_c.c', 'src/main_a.c', 'SConstruct', 'src/main_b.c']
-+FindSourceFiles()
-+
-+# returns ['src/main_b.c', 'src/main_a.c' ]
-+FindSourceFiles( 'src' )
-+.EE
-+.IP
-+As you can see build support files (SConstruct in the above example)
-+will also be returned by this function.
-+
-+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-+.TP
-+.RI Flatten( sequence )
-+.TP
-+.IR env .Flatten( sequence )
-+Takes a sequence (that is, a Python list or tuple)
-+that may contain nested sequences
-+and returns a flattened list containing
-+all of the individual elements in any sequence.
-+This can be helpful for collecting
-+the lists returned by calls to Builders;
-+other Builders will automatically
-+flatten lists specified as input,
-+but direct Python manipulation of
-+these lists does not.
-+
-+Examples:
-+
-+.ES
-+foo = Object('foo.c')
-+bar = Object('bar.c')
-+
-+# Because `foo' and `bar' are lists returned by the Object() Builder,
-+# `objects' will be a list containing nested lists:
-+objects = ['f1.o', foo, 'f2.o', bar, 'f3.o']
-+
-+# Passing such a list to another Builder is all right because
-+# the Builder will flatten the list automatically:
-+Program(source = objects)
-+
-+# If you need to manipulate the list directly using Python, you need to
-+# call Flatten() yourself, or otherwise handle nested lists:
-+for object in Flatten(objects):
-+    print str(object)
-+.EE
-+
-+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-+.TP
-+.RI GetBuildFailures()
-+Returns a list of exceptions for the
-+actions that failed while
-+attempting to build targets.
-+Each element in the returned list is a
-+.I BuildError
-+object
-+with the following attributes
-+that record various aspects
-+of the build failure:
-+
-+.B .node
-+The node that was being built
-+when the build failure occurred.
-+
-+.B .status
-+The numeric exit status
-+returned by the command or Python function
-+that failed when trying to build the
-+specified Node.
-+
-+.B .errstr
-+The SCons error string
-+describing the build failure.
-+(This is often a generic
-+message like "Error 2"
-+to indicate that an executed
-+command exited with a status of 2.)
-+
-+.B .filename
-+The name of the file or
-+directory that actually caused the failure.
-+This may be different from the
-+.B .node
-+attribute.
-+For example,
-+if an attempt to build a target named
-+.B sub/dir/target
-+fails because the
-+.B sub/dir
-+directory could not be created,
-+then the
-+.B .node
-+attribute will be
-+.B sub/dir/target
-+but the
-+.B .filename
-+attribute will be
-+.BR sub/dir .
-+
-+.B .executor
-+The SCons Executor object
-+for the target Node
-+being built.
-+This can be used to retrieve
-+the construction environment used
-+for the failed action.
-+
-+.B .action
-+The actual SCons Action object that failed.
-+This will be one specific action
-+out of the possible list of
-+actions that would have been
-+executed to build the target.
-+
-+.B .command
-+The actual expanded command that was executed and failed,
-+after expansion of
-+.BR $TARGET ,
-+.BR $SOURCE ,
-+and other construction variables.
-+
-+Note that the
-+.BR GetBuildFailures ()
-+function
-+will always return an empty list
-+until any build failure has occurred,
-+which means that
-+.BR GetBuildFailures ()
-+will always return an empty list
-+while the
-+.B SConscript
-+files are being read.
-+Its primary intended use is
-+for functions that will be
-+executed before SCons exits
-+by passing them to the
-+standard Python
-+.BR atexit.register ()
-+function.
-+Example:
-+
-+.ES
-+import atexit
-+
-+def print_build_failures():
-+    from SCons.Script import GetBuildFailures
-+    for bf in GetBuildFailures():
-+        print "%s failed: %s" % (bf.node, bf.errstr)
-+
-+atexit.register(print_build_failures)
-+.EE
-+
-+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-+.TP
-+.RI GetBuildPath( file ", [...])"
-+.TP
-+.IR env .GetBuildPath( file ", [...])"
-+Returns the
-+.B scons
-+path name (or names) for the specified
-+.I file
-+(or files).
-+The specified
-+.I file
-+or files
-+may be
-+.B scons
-+Nodes or strings representing path names.
-+
-+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-+.TP
-+.RI GetLaunchDir()
-+.TP
-+.IR env .GetLaunchDir()
-+Returns the absolute path name of the directory from which
-+.B scons
-+was initially invoked.
-+This can be useful when using the
-+.BR \-u ,
-+.B \-U
-+or
-+.B \-D
-+options, which internally
-+change to the directory in which the
-+.B SConstruct
-+file is found.
-+
-+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-+.TP
-+.RI GetOption( name )
-+.TP
-+.IR env .GetOption( name )
-+This function provides a way to query the value of
-+SCons options set on scons command line
-+(or set using the
-+.BR SetOption ()
-+function).
-+The options supported are:
-+
-+.RS 10
-+.TP 6
-+.B cache_debug
-+which corresponds to --cache-debug;
-+.TP 6
-+.B cache_disable
-+which corresponds to --cache-disable;
-+.TP 6
-+.B cache_force
-+which corresponds to --cache-force;
-+.TP 6
-+.B cache_show
-+which corresponds to --cache-show;
-+.TP 6
-+.B clean
-+which corresponds to -c, --clean and --remove;
-+.TP 6
-+.B config
-+which corresponds to --config;
-+.TP 6
-+.B directory
-+which corresponds to -C and --directory;
-+.TP 6
-+.B diskcheck
-+which corresponds to --diskcheck
-+.TP 6
-+.B duplicate
-+which corresponds to --duplicate;
-+.TP 6
-+.B file
-+which corresponds to -f, --file, --makefile and --sconstruct;
-+.TP 6
-+.B help
-+which corresponds to -h and --help;
-+.TP 6
-+.B ignore_errors
-+which corresponds to --ignore-errors;
-+.TP 6
-+.B implicit_cache
-+which corresponds to --implicit-cache;
-+.TP 6
-+.B implicit_deps_changed
-+which corresponds to --implicit-deps-changed;
-+.TP 6
-+.B implicit_deps_unchanged
-+which corresponds to --implicit-deps-unchanged;
-+.TP 6
-+.B interactive
-+which corresponds to --interact and --interactive;
-+.TP 6
-+.B keep_going
-+which corresponds to -k and --keep-going;
-+.TP 6
-+.B max_drift
-+which corresponds to --max-drift;
-+.TP 6
-+.B no_exec
-+which corresponds to -n, --no-exec, --just-print, --dry-run and --recon;
-+.TP 6
-+.B no_site_dir
-+which corresponds to --no-site-dir;
-+.TP 6
-+.B num_jobs
-+which corresponds to -j and --jobs;
-+.TP 6
-+.B profile_file
-+which corresponds to --profile;
-+.TP 6
-+.B question
-+which corresponds to -q and --question;
-+.TP 6
-+.B random
-+which corresponds to --random;
-+.TP 6
-+.B repository
-+which corresponds to -Y, --repository and --srcdir;
-+.TP 6
-+.B silent
-+which corresponds to -s, --silent and --quiet;
-+.TP 6
-+.B site_dir
-+which corresponds to --site-dir;
-+.TP 6
-+.B stack_size
-+which corresponds to --stack-size;
-+.TP 6
-+.B taskmastertrace_file
-+which corresponds to --taskmastertrace; and
-+.TP 6
-+.B warn
-+which corresponds to --warn and --warning.
-+.RE
-+
-+See the documentation for the
-+corresponding command line object for information about each specific
-+option.
-+
-+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-+.TP
-+.RI Glob( pattern ", [" ondisk ", " source ", " strings ])
-+.TP
-+.IR env .Glob( pattern ", [" ondisk ", " source ", " strings ])
-+Returns Nodes (or strings) that match the specified
-+.IR pattern ,
-+relative to the directory of the current
-+.B SConscript
-+file.
-+The
-+.BR env.Glob ()
-+form performs string substition on
-+.I pattern
-+and returns whatever matches
-+the resulting expanded pattern.
-+
-+The specified
-+.I pattern
-+uses Unix shell style metacharacters for matching:
-+
-+.ES
-+  *       matches everything
-+  ?       matches any single character
-+  [seq]   matches any character in seq
-+  [!seq]  matches any char not in seq
-+.EE
-+.IP
-+If the first character of a filename is a dot,
-+it must be matched explicitly.
-+Character matches do
-+.I not
-+span directory separators.
-+
-+The
-+.BR Glob ()
-+knows about
-+repositories
-+(see the
-+.BR Repository ()
-+function)
-+and source directories
-+(see the
-+.BR VariantDir ()
-+function)
-+and
-+returns a Node (or string, if so configured)
-+in the local (SConscript) directory
-+if matching Node is found
-+anywhere in a corresponding
-+repository or source directory.
-+
-+The
-+.I ondisk
-+argument may be set to
-+.B False
-+(or any other non-true value)
-+to disable the search for matches on disk,
-+thereby only returning matches among
-+already-configured File or Dir Nodes.
-+The default behavior is to
-+return corresponding Nodes
-+for any on-disk matches found.
-+
-+The
-+.I source
-+argument may be set to
-+.B True
-+(or any equivalent value)
-+to specify that,
-+when the local directory is a
-+.BR VariantDir (),
-+the returned Nodes should be from the
-+corresponding source directory,
-+not the local directory.
-+
-+The
-+.I strings
-+argument may be set to
-+.B True
-+(or any equivalent value)
-+to have the
-+.BR Glob ()
-+function return strings, not Nodes,
-+that represent the matched files or directories.
-+The returned strings will be relative to
-+the local (SConscript) directory.
-+(Note that This may make it easier to perform
-+arbitrary manipulation of file names,
-+but if the returned strings are
-+passed to a different
-+.B SConscript
-+file,
-+any Node translation will be relative
-+to the other
-+.B SConscript
-+directory,
-+not the original
-+.B SConscript
-+directory.)
-+
-+Examples:
-+
-+.ES
-+Program('foo', Glob('*.c'))
-+Zip('/tmp/everything', Glob('.??*') + Glob('*'))
-+.EE
-+
-+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-+.TP
-+.RI Help( text )
-+.TP
-+.IR env .Help( text )
-+This specifies help text to be printed if the
-+.B \-h
-+argument is given to
-+.BR scons .
-+If
-+.BR Help ()
-+is called multiple times, the text is appended together in the order
-+that
-+.BR Help ()
-+is called.
-+
-+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-+.TP
-+.RI Ignore( target ", " dependency )
-+.TP
-+.IR env .Ignore( target ", " dependency )
-+The specified dependency file(s)
-+will be ignored when deciding if
-+the target file(s) need to be rebuilt.
-+
-+You can also use
-+.BR Ignore ()
-+to remove a target from the default build.
-+In order to do this you must specify the directory the target will
-+be built in as the target, and the file you want to skip building
-+as the dependency.
-+
-+Note that this will only remove the dependencies listed from 
-+the files built by default.  It will still be built if that 
-+dependency is needed by another object being built. 
-+See the third and forth examples below.
-+
-+Examples:
-+
-+.ES
-+env.Ignore('foo', 'foo.c')
-+env.Ignore('bar', ['bar1.h', 'bar2.h'])
-+env.Ignore('.','foobar.obj')
-+env.Ignore('bar','bar/foobar.obj')
-+.EE
-+
-+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-+.TP
-+.RI Import( vars )
-+.TP
-+.IR env .Import( vars )
-+This tells
-+.B scons
-+to import a list of variables into the current SConscript file. This
-+will import variables that were exported with
-+.BR Export ()
-+or in the
-+.I exports
-+argument to
-+.BR SConscript ().
-+Variables exported by
-+.BR SConscript ()
-+have precedence.
-+Multiple variable names can be passed to
-+.BR Import ()
-+as separate arguments or as a list. The variable "*" can be used
-+to import all variables.
-+
-+Examples:
-+
-+.ES
-+Import("env")
-+Import("env", "variable")
-+Import(["env", "variable"])
-+Import("*")
-+.EE
-+
-+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-+.TP
-+.RI Literal( string )
-+.TP
-+.IR env .Literal( string )
-+The specified
-+.I string
-+will be preserved as-is
-+and not have construction variables expanded.
-+
-+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-+.TP
-+.RI Local( targets )
-+.TP
-+.IR env .Local( targets )
-+The specified
-+.I targets
-+will have copies made in the local tree,
-+even if an already up-to-date copy
-+exists in a repository.
-+Returns a list of the target Node or Nodes.
-+
-+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-+.TP
-+.IR env .MergeFlags( arg ", [" unique ])
-+Merges the specified
-+.I arg
-+values to the construction environment's construction variables.
-+If the
-+.I arg
-+argument is not a dictionary,
-+it is converted to one by calling
-+.BR env.ParseFlags ()
-+on the argument
-+before the values are merged.
-+Note that
-+.I arg
-+must be a single value,
-+so multiple strings must
-+be passed in as a list,
-+not as separate arguments to
-+.BR env.MergeFlags ().
-+
-+By default,
-+duplicate values are eliminated;
-+you can, however, specify
-+.B unique=0
-+to allow duplicate
-+values to be added.
-+When eliminating duplicate values,
-+any construction variables that end with
-+the string
-+.B PATH
-+keep the left-most unique value.
-+All other construction variables keep
-+the right-most unique value.
-+
-+Examples:
-+
-+.ES
-+# Add an optimization flag to $CCFLAGS.
-+env.MergeFlags('-O3')
-+
-+# Combine the flags returned from running pkg-config with an optimization
-+# flag and merge the result into the construction variables.
-+env.MergeFlags(['!pkg-config gtk+-2.0 --cflags', '-O3'])
-+
-+# Combine an optimization flag with the flags returned from running pkg-config
-+# twice and merge the result into the construction variables.
-+env.MergeFlags(['-O3',
-+               '!pkg-config gtk+-2.0 --cflags --libs',
-+               '!pkg-config libpng12 --cflags --libs'])
-+.EE
-+
-+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-+.TP
-+.RI NoCache( target ", ...)"
-+.TP
-+.IR env .NoCache( target ", ...)"
-+Specifies a list of files which should
-+.I not
-+be cached whenever the
-+.BR CacheDir ()
-+method has been activated.
-+The specified targets may be a list
-+or an individual target.
-+
-+Multiple files should be specified
-+either as separate arguments to the
-+.BR NoCache ()
-+method, or as a list.
-+.BR NoCache ()
-+will also accept the return value of any of the construction environment
-+Builder methods.
-+
-+Calling
-+.BR NoCache ()
-+on directories and other non-File Node types has no effect because
-+only File Nodes are cached.
-+
-+Examples:
-+
-+.ES
-+NoCache('foo.elf')
-+NoCache(env.Program('hello', 'hello.c'))
-+.EE
-+
-+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-+.TP
-+.RI NoClean( target ", ...)"
-+.TP
-+.IR env .NoClean( target ", ...)"
-+Specifies a list of files or directories which should
-+.I not
-+be removed whenever the targets (or their dependencies)
-+are specified with the
-+.B \-c
-+command line option.
-+The specified targets may be a list
-+or an individual target.
-+Multiple calls to
-+.BR NoClean ()
-+are legal,
-+and prevent each specified target
-+from being removed by calls to the
-+.B \-c
-+option.
-+
-+Multiple files or directories should be specified
-+either as separate arguments to the
-+.BR NoClean ()
-+method, or as a list.
-+.BR NoClean ()
-+will also accept the return value of any of the construction environment
-+Builder methods.
-+
-+Calling
-+.BR NoClean ()
-+for a target overrides calling
-+.BR Clean ()
-+for the same target,
-+and any targets passed to both functions will
-+.I not
-+be removed by the
-+.B \-c
-+option.
-+
-+Examples:
-+
-+.ES
-+NoClean('foo.elf')
-+NoClean(env.Program('hello', 'hello.c'))
-+.EE
-+
-+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-+.TP
-+.IR env .ParseConfig( command ", [" function ", " unique ])
-+Calls the specified
-+.I function
-+to modify the environment as specified by the output of
-+.IR command .
-+The default
-+.I function
-+is
-+.BR env.MergeFlags (),
-+which expects the output of a typical
-+.B *-config
-+command
-+(for example,
-+.BR gtk-config )
-+and adds the options
-+to the appropriate construction variables.
-+By default,
-+duplicate values are not
-+added to any construction variables;
-+you can specify
-+.B unique=0
-+to allow duplicate
-+values to be added.
-+
-+Interpreted options
-+and the construction variables they affect
-+are as specified for the
-+.BR env.ParseFlags ()
-+method (which this method calls).
-+See that method's description, below,
-+for a table of options and construction variables.
-+
-+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-+.TP
-+.RI ParseDepends( filename ", [" must_exist ", " only_one ])
-+.TP
-+.IR env .ParseDepends( filename ", [" must_exist ", " only_one ])
-+Parses the contents of the specified
-+.I filename
-+as a list of dependencies in the style of
-+.B Make
-+or
-+.BR mkdep ,
-+and explicitly establishes all of the listed dependencies.
-+
-+By default,
-+it is not an error
-+if the specified
-+.I filename
-+does not exist.
-+The optional
-+.I must_exist
-+argument may be set to a non-zero
-+value to have
-+scons
-+throw an exception and
-+generate an error if the file does not exist,
-+or is otherwise inaccessible.
-+
-+The optional
-+.I only_one
-+argument may be set to a non-zero
-+value to have
-+scons
-+thrown an exception and
-+generate an error
-+if the file contains dependency
-+information for more than one target.
-+This can provide a small sanity check
-+for files intended to be generated
-+by, for example, the
-+.B "gcc -M"
-+flag,
-+which should typically only
-+write dependency information for
-+one output file into a corresponding
-+.B .d
-+file.
-+
-+The
-+.I filename
-+and all of the files listed therein
-+will be interpreted relative to
-+the directory of the
-+.B SConscript
-+file which calls the
-+.BR ParseDepends ()
-+function.
-+
-+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-+.TP
-+.IR env .ParseFlags( flags ", ...)"
-+Parses one or more strings containing
-+typical command-line flags for GCC tool chains
-+and returns a dictionary with the flag values
-+separated into the appropriate SCons construction variables.
-+This is intended as a companion to the
-+.BR env.MergeFlags ()
-+method, but allows for the values in the returned dictionary
-+to be modified, if necessary,
-+before merging them into the construction environment.
-+(Note that
-+.BR env.MergeFlags ()
-+will call this method if its argument is not a dictionary,
-+so it is usually not necessary to call
-+.BR env.ParseFlags ()
-+directly unless you want to manipulate the values.)
-+
-+If the first character in any string is
-+an exclamation mark (!),
-+the rest of the string is executed as a command,
-+and the output from the command is
-+parsed as GCC tool chain command-line flags
-+and added to the resulting dictionary.
-+
-+Flag values are translated accordig to the prefix found,
-+and added to the following construction variables:
-+
-+.ES
-+-arch               CCFLAGS, LINKFLAGS
-+-D                  CPPDEFINES
-+-framework          FRAMEWORKS
-+-frameworkdir=      FRAMEWORKPATH
-+-include            CCFLAGS
-+-isysroot           CCFLAGS, LINKFLAGS
-+-I                  CPPPATH
-+-l                  LIBS
-+-L                  LIBPATH
-+-mno-cygwin         CCFLAGS, LINKFLAGS
-+-mwindows           LINKFLAGS
-+-pthread            CCFLAGS, LINKFLAGS
-+-std=               CFLAGS
-+-Wa,                ASFLAGS, CCFLAGS
-+-Wl,-rpath=         RPATH
-+-Wl,-R,             RPATH
-+-Wl,-R              RPATH
-+-Wl,                LINKFLAGS
-+-Wp,                CPPFLAGS
-+-                   CCFLAGS
-++                   CCFLAGS, LINKFLAGS
-+.EE
-+.IP
-+Any other strings not associated with options
-+are assumed to be the names of libraries
-+and added to the
-+.B $LIBS
-+construction variable.
-+
-+Examples (all of which produce the same result):
-+
-+.ES
-+dict = env.ParseFlags('-O2 -Dfoo -Dbar=1')
-+dict = env.ParseFlags('-O2', '-Dfoo', '-Dbar=1')
-+dict = env.ParseFlags(['-O2', '-Dfoo -Dbar=1'])
-+dict = env.ParseFlags('-O2', '!echo -Dfoo -Dbar=1')
-+.EE
-+
-+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-+.TP
-+.IR env .Perforce()
-+A factory function that
-+returns a Builder object
-+to be used to fetch source files
-+from the Perforce source code management system.
-+The returned Builder
-+is intended to be passed to the
-+.BR SourceCode ()
-+function.
-+
-+This function is deprecated.  For details, see the entry for the
-+.BR SourceCode ()
-+function.
-+
-+Example:
-+
-+.ES
-+env.SourceCode('.', env.Perforce())
-+.EE
-+.IP
-+Perforce uses a number of external
-+environment variables for its operation.
-+Consequently, this function adds the
-+following variables from the user's external environment
-+to the construction environment's
-+ENV dictionary:
-+P4CHARSET,
-+P4CLIENT,
-+P4LANGUAGE,
-+P4PASSWD,
-+P4PORT,
-+P4USER,
-+SystemRoot,
-+USER,
-+and
-+USERNAME.
-+
-+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-+.TP
-+.RI Platform( string )
-+The
-+.BR Platform ()
-+form returns a callable object
-+that can be used to initialize
-+a construction environment using the
-+platform keyword of the
-+.BR Environment ()
-+function.
-+
-+Example:
-+
-+.ES
-+env = Environment(platform = Platform('win32'))
-+.EE
-+.IP
-+The
-+.BR env.Platform ()
-+form applies the callable object for the specified platform
-+.I string
-+to the environment through which the method was called.
-+
-+.ES
-+env.Platform('posix')
-+.EE
-+.IP
-+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.
-+
-+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-+.TP
-+.RI Precious( target ", ...)"
-+.TP
-+.IR env .Precious( target ", ...)"
-+Marks each given
-+.I target
-+as precious so it is not deleted before it is rebuilt. Normally
-+.B scons
-+deletes a target before building it.
-+Multiple targets can be passed in to a single call to
-+.BR Precious ().
-+
-+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-+.TP
-+.IR env .Prepend(key= val ", [...])"
-+Appends the specified keyword arguments
-+to the beginning of construction variables in the environment.
-+If the Environment does not have
-+the specified construction variable,
-+it is simply added to the environment.
-+If the values of the construction variable
-+and the keyword argument are the same type,
-+then the two values will be simply added together.
-+Otherwise, the construction variable
-+and the value of the keyword argument
-+are both coerced to lists,
-+and the lists are added together.
-+(See also the Append method, above.)
-+
-+Example:
-+
-+.ES
-+env.Prepend(CCFLAGS = '-g ', FOO = ['foo.yyy'])
-+.EE
-+
-+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-+.TP
-+.IR env .PrependENVPath( name ", " newpath ", [" envname ", " sep ", " delete_existing ])
-+This appends new path elements to the given path in the
-+specified external environment
-+.RB ( $ENV
-+by default).
-+This will only add
-+any particular path once (leaving the first one it encounters and
-+ignoring the rest, to preserve path order),
-+and to help assure this,
-+will normalize all paths (using
-+.B os.path.normpath
-+and
-+.BR os.path.normcase ).
-+This can also handle the
-+case where the given old path variable is a list instead of a
-+string, in which case a list will be returned instead of a string.
-+
-+If
-+.I delete_existing
-+is 0, then adding a path that already exists
-+will not move it to the beginning;
-+it will stay where it is in the list.
-+
-+Example:
-+
-+.ES
-+print 'before:',env['ENV']['INCLUDE']
-+include_path = '/foo/bar:/foo'
-+env.PrependENVPath('INCLUDE', include_path)
-+print 'after:',env['ENV']['INCLUDE']
-+.EE
-+.IP
-+The above example will print:
-+
-+.ES
-+before: /biz:/foo
-+after: /foo/bar:/foo:/biz
-+.EE
-+
-+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-+.TP
-+.IR env .PrependUnique(key= val ", delete_existing=" "0, [...])"
-+Appends the specified keyword arguments
-+to the beginning of construction variables in the environment.
-+If the Environment does not have
-+the specified construction variable,
-+it is simply added to the environment.
-+If the construction variable being appended to is a list,
-+then any value(s) that already exist in the
-+construction variable will
-+.I not
-+be added again to the list.
-+However, if delete_existing is 1, 
-+existing matching values are removed first, so
-+existing values in the arg list move to the front of the list.
-+
-+Example:
-+
-+.ES
-+env.PrependUnique(CCFLAGS = '-g', FOO = ['foo.yyy'])
-+.EE
-+
-+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-+.TP
-+.RI Progress( callable ", [" interval ])
-+.TP
-+.RI Progress( string ", [" interval ", " file ", " overwrite ])
-+.TP
-+.RI Progress( list_of_strings ", [" interval ", " file ", " overwrite ])
-+Allows SCons to show progress made during the build
-+by displaying a string or calling a function while
-+evaluating Nodes (e.g. files).
-+
-+If the first specified argument is a Python callable
-+(a function or an object that has a
-+.BR __call__ ()
-+method),
-+the function will be called
-+once every
-+.I interval
-+times a Node is evaluated.
-+The callable will be passed the evaluated Node
-+as its only argument.
-+(For future compatibility,
-+it's a good idea to also add
-+.B *args
-+and
-+.B **kw
-+as arguments to your function or method.
-+This will prevent the code from breaking
-+if SCons ever changes the interface
-+to call the function with additional arguments in the future.)
-+
-+An example of a simple custom progress function
-+that prints a string containing the Node name
-+every 10 Nodes:
-+
-+.ES
-+def my_progress_function(node, *args, **kw):
-+    print 'Evaluating node %s!' % node
-+Progress(my_progress_function, interval=10)
-+.EE
-+.IP
-+A more complicated example of a custom progress display object
-+that prints a string containing a count
-+every 100 evaluated Nodes.
-+Note the use of
-+.B \\r
-+(a carriage return)
-+at the end so that the string
-+will overwrite itself on a display:
-+
-+.ES
-+import sys
-+class ProgressCounter(object):
-+    count = 0
-+    def __call__(self, node, *args, **kw):
-+        self.count += 100
-+        sys.stderr.write('Evaluated %s nodes\\r' % self.count)
-+Progress(ProgressCounter(), interval=100)
-+.EE
-+.IP
-+If the first argument
-+.BR Progress ()
-+is a string,
-+the string will be displayed
-+every
-+.I interval
-+evaluated Nodes.
-+The default is to print the string on standard output;
-+an alternate output stream
-+may be specified with the
-+.B file=
-+argument.
-+The following will print a series of dots
-+on the error output,
-+one dot for every 100 evaluated Nodes:
-+
-+.ES
-+import sys
-+Progress('.', interval=100, file=sys.stderr)
-+.EE
-+.IP
-+If the string contains the verbatim substring
-+.BR $TARGET ,
-+it will be replaced with the Node.
-+Note that, for performance reasons, this is
-+.I not
-+a regular SCons variable substition,
-+so you can not use other variables
-+or use curly braces.
-+The following example will print the name of
-+every evaluated Node,
-+using a
-+.B \\r
-+(carriage return) to cause each line to overwritten by the next line,
-+and the
-+.B overwrite=
-+keyword argument to make sure the previously-printed
-+file name is overwritten with blank spaces:
-+
-+.ES
-+import sys
-+Progress('$TARGET\\r', overwrite=True)
-+.EE
-+.IP
-+If the first argument to
-+.BR Progress ()
-+is a list of strings,
-+then each string in the list will be displayed
-+in rotating fashion every
-+.I interval
-+evaluated Nodes.
-+This can be used to implement a "spinner"
-+on the user's screen as follows:
-+
-+.ES
-+Progress(['-\\r', '\\\\\\r', '|\\r', '/\\r'], interval=5)
-+.EE
-+
-+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-+.TP
-+.IR env .RCS()
-+A factory function that
-+returns a Builder object
-+to be used to fetch source files
-+from RCS.
-+The returned Builder
-+is intended to be passed to the
-+.BR SourceCode ()
-+function:
-+
-+This function is deprecated.  For details, see the entry for the
-+.BR SourceCode ()
-+function.
-+
-+Examples:
-+
-+.ES
-+env.SourceCode('.', env.RCS())
-+.EE
-+.IP
-+Note that
-+.B scons
-+will fetch source files
-+from RCS subdirectories automatically,
-+so configuring RCS
-+as demonstrated in the above example
-+should only be necessary if
-+you are fetching from
-+RCS,v
-+files in the same
-+directory as the source files,
-+or if you need to explicitly specify RCS
-+for a specific subdirectory.
-+
-+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-+.TP
-+.IR env .Replace(key= val ", [...])"
-+Replaces construction variables in the Environment
-+with the specified keyword arguments.
-+
-+Example:
-+
-+.ES
-+env.Replace(CCFLAGS = '-g', FOO = 'foo.xxx')
-+.EE
-+
-+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-+.TP
-+.RI Repository( directory )
-+.TP
-+.IR env .Repository( directory )
-+Specifies that
-+.I directory
-+is a repository to be searched for files.
-+Multiple calls to
-+.BR Repository ()
-+are legal,
-+and each one adds to the list of
-+repositories that will be searched.
-+
-+To
-+.BR scons ,
-+a repository is a copy of the source tree,
-+from the top-level directory on down,
-+which may contain
-+both source files and derived files
-+that can be used to build targets in
-+the local source tree.
-+The canonical example would be an
-+official source tree maintained by an integrator.
-+If the repository contains derived files,
-+then the derived files should have been built using
-+.BR scons ,
-+so that the repository contains the necessary
-+signature information to allow
-+.B scons
-+to figure out when it is appropriate to
-+use the repository copy of a derived file,
-+instead of building one locally.
-+
-+Note that if an up-to-date derived file
-+already exists in a repository,
-+.B scons
-+will
-+.I not
-+make a copy in the local directory tree.
-+In order to guarantee that a local copy
-+will be made,
-+use the
-+.BR Local ()
-+method.
-+
-+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-+.TP
-+.RI Requires( target ", " prerequisite )
-+.TP
-+.IR env .Requires( target ", " prerequisite )
-+Specifies an order-only relationship
-+between the specified target file(s)
-+and the specified prerequisite file(s).
-+The prerequisite file(s)
-+will be (re)built, if necessary,
-+.I before
-+the target file(s),
-+but the target file(s) do not actually
-+depend on the prerequisites
-+and will not be rebuilt simply because
-+the prerequisite file(s) change.
-+
-+Example:
-+
-+.ES
-+env.Requires('foo', 'file-that-must-be-built-before-foo')
-+.EE
-+
-+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-+.TP
-+.RI Return([ vars "..., stop=" ])
-+By default,
-+this stops processing the current SConscript
-+file and returns to the calling SConscript file
-+the values of the variables named in the
-+.I vars
-+string arguments.
-+Multiple strings contaning variable names may be passed to
-+.BR Return ().
-+Any strings that contain white space
-+
-+The optional
-+.B stop=
-+keyword argument may be set to a false value
-+to continue processing the rest of the SConscript
-+file after the
-+.BR Return ()
-+call.
-+This was the default behavior prior to SCons 0.98.
-+However, the values returned
-+are still the values of the variables in the named
-+.I vars
-+at the point
-+.BR Return ()
-+is called.
-+
-+Examples:
-+
-+.ES
-+# Returns without returning a value.
-+Return()
-+
-+# Returns the value of the 'foo' Python variable.
-+Return("foo")
-+
-+# Returns the values of the Python variables 'foo' and 'bar'.
-+Return("foo", "bar")
-+
-+# Returns the values of Python variables 'val1' and 'val2'.
-+Return('val1 val2')
-+.EE
-+
-+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-+.TP
-+.RI Scanner( function ", [" argument ", " keys ", " path_function ", " node_class ", " node_factory ", " scan_check ", " recursive ])
-+.TP
-+.IR env .Scanner( function ", [" argument ", " keys ", " path_function ", " node_class ", " node_factory ", " scan_check ", " recursive ])
-+Creates a Scanner object for
-+the specified
-+.IR function .
-+See the section "Scanner Objects,"
-+below, for a complete explanation of the arguments and behavior.
-+
-+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-+.TP
-+.IR env .SCCS()
-+A factory function that
-+returns a Builder object
-+to be used to fetch source files
-+from SCCS.
-+The returned Builder
-+is intended to be passed to the
-+.BR SourceCode ()
-+function.
-+
-+Example:
-+
-+.ES
-+env.SourceCode('.', env.SCCS())
-+.EE
-+.IP
-+Note that
-+.B scons
-+will fetch source files
-+from SCCS subdirectories automatically,
-+so configuring SCCS
-+as demonstrated in the above example
-+should only be necessary if
-+you are fetching from
-+.B s.SCCS
-+files in the same
-+directory as the source files,
-+or if you need to explicitly specify SCCS
-+for a specific subdirectory.
-+
-+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-+.TP
-+.RI SConscript( scripts ", [" exports ", " variant_dir ", " duplicate ])
-+.TP
-+.IR env .SConscript( scripts ", [" exports ", " variant_dir ", " duplicate ])
-+.TP
-+.RI SConscript(dirs= subdirs ", [name=" script ", " exports ", " variant_dir ", " duplicate ])
-+.TP
-+.IR env .SConscript(dirs= subdirs ", [name=" script ", " exports ", " variant_dir ", " duplicate ])
-+This tells
-+.B scons
-+to execute
-+one or more subsidiary SConscript (configuration) files.
-+Any variables returned by a called script using
-+.BR Return ()
-+will be returned by the call to
-+.BR SConscript ().
-+There are two ways to call the
-+.BR SConscript ()
-+function.
-+
-+The first way you can call
-+.BR SConscript ()
-+is to explicitly specify one or more
-+.I scripts
-+as the first argument.
-+A single script may be specified as a string;
-+multiple scripts must be specified as a list
-+(either explicitly or as created by
-+a function like
-+.BR Split ()).
-+Examples:
-+.ES
-+SConscript('SConscript')      # run SConscript in the current directory
-+SConscript('src/SConscript')  # run SConscript in the src directory
-+SConscript(['src/SConscript', 'doc/SConscript'])
-+config = SConscript('MyConfig.py')
-+.EE
-+.IP
-+The second way you can call
-+.BR SConscript ()
-+is to specify a list of (sub)directory names
-+as a
-+.BI dirs= subdirs
-+keyword argument.
-+In this case,
-+.B scons
-+will, by default,
-+execute a subsidiary configuration file named
-+.B SConscript
-+in each of the specified directories.
-+You may specify a name other than
-+.B SConscript
-+by supplying an optional
-+.BI name= script
-+keyword argument.
-+The first three examples below have the same effect
-+as the first three examples above:
-+.ES
-+SConscript(dirs='.')      # run SConscript in the current directory
-+SConscript(dirs='src')    # run SConscript in the src directory
-+SConscript(dirs=['src', 'doc'])
-+SConscript(dirs=['sub1', 'sub2'], name='MySConscript')
-+.EE
-+.IP
-+The optional
-+.I exports
-+argument provides a list of variable names or a dictionary of
-+named values to export to the
-+.IR script(s) .
-+These variables are locally exported only to the specified
-+.IR script(s) ,
-+and do not affect the global pool of variables used by the
-+.BR Export ()
-+function.
-+The subsidiary
-+.I script(s)
-+must use the
-+.BR Import ()
-+function to import the variables.
-+Examples:
-+.ES
-+foo = SConscript('sub/SConscript', exports='env')
-+SConscript('dir/SConscript', exports=['env', 'variable'])
-+SConscript(dirs='subdir', exports='env variable')
-+SConscript(dirs=['one', 'two', 'three'], exports='shared_info')
-+.EE
-+.IP
-+If the optional
-+.I variant_dir
-+argument is present, it causes an effect equivalent to the
-+.BR VariantDir ()
-+method described below.
-+(If
-+.I variant_dir
-+is not present, the
-+.I duplicate
-+argument is ignored.)
-+The
-+.I variant_dir
-+argument is interpreted relative to the directory of the calling
-+.B SConscript
-+file.
-+See the description of the
-+.BR VariantDir ()
-+function below for additional details and restrictions.
-+
-+If
-+.I variant_dir
-+is present,
-+the source directory is the directory in which the
-+.B SConscript
-+file resides and the
-+.B SConscript
-+file is evaluated as if it were in the
-+.I variant_dir
-+directory:
-+.ES
-+SConscript('src/SConscript', variant_dir = 'build')
-+.EE
-+.IP
-+is equivalent to
-+
-+.ES
-+VariantDir('build', 'src')
-+SConscript('build/SConscript')
-+.EE
-+.IP
-+This later paradigm is often used when the sources are
-+in the same directory as the
-+.BR SConstruct :
-+
-+.ES
-+SConscript('SConscript', variant_dir = 'build')
-+.EE
-+.IP
-+is equivalent to
-+
-+.ES
-+VariantDir('build', '.')
-+SConscript('build/SConscript')
-+.EE
-+.IP
-+Here are some composite examples:
-+
-+.ES
-+# collect the configuration information and use it to build src and doc
-+shared_info = SConscript('MyConfig.py')
-+SConscript('src/SConscript', exports='shared_info')
-+SConscript('doc/SConscript', exports='shared_info')
-+.EE
-+
-+.ES
-+# build debugging and production versions.  SConscript
-+# can use Dir('.').path to determine variant.
-+SConscript('SConscript', variant_dir='debug', duplicate=0)
-+SConscript('SConscript', variant_dir='prod', duplicate=0)
-+.EE
-+
-+.ES
-+# build debugging and production versions.  SConscript
-+# is passed flags to use.
-+opts = { 'CPPDEFINES' : ['DEBUG'], 'CCFLAGS' : '-pgdb' }
-+SConscript('SConscript', variant_dir='debug', duplicate=0, exports=opts)
-+opts = { 'CPPDEFINES' : ['NODEBUG'], 'CCFLAGS' : '-O' }
-+SConscript('SConscript', variant_dir='prod', duplicate=0, exports=opts)
-+.EE
-+
-+.ES
-+# build common documentation and compile for different architectures
-+SConscript('doc/SConscript', variant_dir='build/doc', duplicate=0)
-+SConscript('src/SConscript', variant_dir='build/x86', duplicate=0)
-+SConscript('src/SConscript', variant_dir='build/ppc', duplicate=0)
-+.EE
-+
-+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-+.TP
-+.RI SConscriptChdir( value )
-+.TP
-+.IR env .SConscriptChdir( value )
-+By default,
-+.B scons
-+changes its working directory
-+to the directory in which each
-+subsidiary SConscript file lives.
-+This behavior may be disabled
-+by specifying either:
-+
-+.ES
-+SConscriptChdir(0)
-+env.SConscriptChdir(0)
-+.EE
-+.IP
-+in which case
-+.B scons
-+will stay in the top-level directory
-+while reading all SConscript files.
-+(This may be necessary when building from repositories,
-+when all the directories in which SConscript files may be found
-+don't necessarily exist locally.)
-+You may enable and disable
-+this ability by calling
-+SConscriptChdir()
-+multiple times.
-+
-+Example:
-+
-+.ES
-+env = Environment()
-+SConscriptChdir(0)
-+SConscript('foo/SConscript')	# will not chdir to foo
-+env.SConscriptChdir(1)
-+SConscript('bar/SConscript')	# will chdir to bar
-+.EE
-+
-+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-+.TP
-+.RI SConsignFile([ file ", " dbm_module ])
-+.TP
-+.IR env .SConsignFile([ file ", " dbm_module ])
-+This tells
-+.B scons
-+to store all file signatures
-+in the specified database
-+.IR file .
-+If the
-+.I file
-+name is omitted,
-+.B .sconsign
-+is used by default.
-+(The actual file name(s) stored on disk
-+may have an appropriated suffix appended
-+by the
-+.IR  dbm_module .)
-+If
-+.I file
-+is not an absolute path name,
-+the file is placed in the same directory as the top-level
-+.B SConstruct
-+file.
-+
-+If
-+.I file
-+is
-+.BR None ,
-+then
-+.B scons
-+will store file signatures
-+in a separate
-+.B .sconsign
-+file in each directory,
-+not in one global database file.
-+(This was the default behavior
-+prior to SCons 0.96.91 and 0.97.)
-+
-+The optional
-+.I dbm_module
-+argument can be used to specify
-+which Python database module
-+The default is to use a custom
-+.B SCons.dblite
-+module that uses pickled
-+Python data structures,
-+and which works on all Python versions.
-+
-+Examples:
-+
-+.ES
-+# Explicitly stores signatures in ".sconsign.dblite"
-+# in the top-level SConstruct directory (the
-+# default behavior).
-+SConsignFile()
-+
-+# Stores signatures in the file "etc/scons-signatures"
-+# relative to the top-level SConstruct directory.
-+SConsignFile("etc/scons-signatures")
-+
-+# Stores signatures in the specified absolute file name.
-+SConsignFile("/home/me/SCons/signatures")
-+
-+# Stores signatures in a separate .sconsign file
-+# in each directory.
-+SConsignFile(None)
-+.EE
-+
-+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-+.TP
-+.IR env .SetDefault(key= val ", [...])"
-+Sets construction variables to default values specified with the keyword
-+arguments if (and only if) the variables are not already set.
-+The following statements are equivalent:
-+
-+.ES
-+env.SetDefault(FOO = 'foo')
-+
-+if 'FOO' not in env: env['FOO'] = 'foo'
-+.EE
-+
-+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-+.TP
-+.RI SetOption( name ", " value )
-+.TP
-+.IR env .SetOption( name ", " value )
-+This function provides a way to set a select subset of the scons command
-+line options from a SConscript file. The options supported are:
-+
-+.RS 10
-+.TP 6
-+.B clean
-+which corresponds to -c, --clean and --remove;
-+.TP 6
-+.B duplicate
-+which corresponds to --duplicate;
-+.TP 6
-+.B help
-+which corresponds to -h and --help;
-+.TP 6
-+.B implicit_cache
-+which corresponds to --implicit-cache;
-+.TP 6
-+.B max_drift
-+which corresponds to --max-drift;
-+.TP 6
-+.B no_exec
-+which corresponds to -n, --no-exec, --just-print, --dry-run and --recon;
-+.TP 6
-+.B num_jobs
-+which corresponds to -j and --jobs;
-+.TP 6
-+.B random
-+which corresponds to --random; and
-+.TP 6
-+.B stack_size
-+which corresponds to --stack-size.
-+.RE
-+
-+See the documentation for the
-+corresponding command line object for information about each specific
-+option.
-+
-+Example:
-+
-+.ES
-+SetOption('max_drift', 1)
-+.EE
-+
-+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-+.TP
-+.RI SideEffect( side_effect ", " target )
-+.TP
-+.IR env .SideEffect( side_effect ", " target )
-+Declares
-+.I side_effect
-+as a side effect of building
-+.IR target .
-+Both
-+.I side_effect
-+and
-+.I target
-+can be a list, a file name, or a node.
-+A side effect is a target file that is created or updated
-+as a side effect of building other targets.
-+For example, a Windows PDB
-+file is created as a side effect of building the .obj
-+files for a static library,
-+and various log files are created updated
-+as side effects of various TeX commands.
-+If a target is a side effect of multiple build commands,
-+.B scons
-+will ensure that only one set of commands
-+is executed at a time.
-+Consequently, you only need to use this method
-+for side-effect targets that are built as a result of
-+multiple build commands.
-+
-+Because multiple build commands may update
-+the same side effect file,
-+by default the
-+.I side_effect
-+target is
-+.I not
-+automatically removed
-+when the
-+.I target
-+is removed by the
-+.B \-c
-+option.
-+(Note, however, that the
-+.I side_effect
-+might be removed as part of
-+cleaning the directory in which it lives.)
-+If you want to make sure the
-+.I side_effect
-+is cleaned whenever a specific
-+.I target
-+is cleaned,
-+you must specify this explicitly
-+with the
-+.BR Clean ()
-+or
-+.BR env.Clean ()
-+function.
-+
-+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-+.TP
-+.RI SourceCode( entries ", " builder )
-+.TP
-+.IR env .SourceCode( entries ", " builder )
-+This function and its associate factory functions are deprecated.
-+There is no replacement.
-+The intended use was to keep a local tree in sync with an archive,
-+but in actuality the function only causes the archive
-+to be fetched on the first run.
-+Synchronizing with the archive is best done external to &SCons;.
-+
-+Arrange for non-existent source files to
-+be fetched from a source code management system
-+using the specified
-+.IR builder .
-+The specified
-+.I entries
-+may be a Node, string or list of both,
-+and may represent either individual
-+source files or directories in which
-+source files can be found.
-+
-+For any non-existent source files,
-+.B scons
-+will search up the directory tree
-+and use the first
-+.BR SourceCode ()
-+builder it finds.
-+The specified
-+.I builder
-+may be
-+.BR None ,
-+in which case
-+.B scons
-+will not use a builder to fetch
-+source files for the specified
-+.IR entries ,
-+even if a
-+.BR SourceCode ()
-+builder has been specified
-+for a directory higher up the tree.
-+
-+.B scons
-+will, by default,
-+fetch files from SCCS or RCS subdirectories
-+without explicit configuration.
-+This takes some extra processing time
-+to search for the necessary
-+source code management files on disk.
-+You can avoid these extra searches
-+and speed up your build a little
-+by disabling these searches as follows:
-+
-+.ES
-+env.SourceCode('.', None)
-+.EE
-+.IP
-+Note that if the specified
-+.I builder
-+is one you create by hand,
-+it must have an associated
-+construction environment to use
-+when fetching a source file.
-+
-+.B scons
-+provides a set of canned factory
-+functions that return appropriate
-+Builders for various popular
-+source code management systems.
-+Canonical examples of invocation include:
-+
-+.ES
-+env.SourceCode('.', env.BitKeeper('/usr/local/BKsources'))
-+env.SourceCode('src', env.CVS('/usr/local/CVSROOT'))
-+env.SourceCode('/', env.RCS())
-+env.SourceCode(['f1.c', 'f2.c'], env.SCCS())
-+env.SourceCode('no_source.c', None)
-+.EE
-+
-+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-+.TP
-+.RI SourceSignatures( type )
-+.TP
-+.IR env .SourceSignatures( type )
-+Note:  Although it is not yet officially deprecated,
-+use of this function is discouraged.
-+See the
-+.BR Decider ()
-+function for a more flexible and straightforward way
-+to configure SCons' decision-making.
-+
-+The
-+.BR SourceSignatures ()
-+function tells
-+.B scons
-+how to decide if a source file
-+(a file that is not built from any other files)
-+has changed since the last time it
-+was used to build a particular target file.
-+Legal values are
-+.B MD5
-+or
-+.BR timestamp .
-+
-+If the environment method is used,
-+the specified type of source signature
-+is only used when deciding whether targets
-+built with that environment are up-to-date or must be rebuilt.
-+If the global function is used,
-+the specified type of source signature becomes the default
-+used for all decisions
-+about whether targets are up-to-date.
-+
-+.B MD5
-+means
-+.B scons
-+decides that a source file has changed
-+if the MD5 checksum of its contents has changed since
-+the last time it was used to rebuild a particular target file.
-+
-+.B timestamp
-+means
-+.B scons
-+decides that a source file has changed
-+if its timestamp (modification time) has changed since
-+the last time it was used to rebuild a particular target file.
-+(Note that although this is similar to the behavior of Make,
-+by default it will also rebuild if the dependency is
-+.I older
-+than the last time it was used to rebuild the target file.)
-+
-+There is no different between the two behaviors
-+for Python
-+.BR Value ()
-+node objects.
-+
-+.B MD5
-+signatures take longer to compute,
-+but are more accurate than
-+.B timestamp
-+signatures.
-+The default value is
-+.BR MD5 .
-+
-+Note that the default
-+.BR TargetSignatures ()
-+setting (see below)
-+is to use this
-+.BR SourceSignatures ()
-+setting for any target files that are used
-+to build other target files.
-+Consequently, changing the value of
-+.BR SourceSignatures ()
-+will, by default,
-+affect the up-to-date decision for all files in the build
-+(or all files built with a specific construction environment
-+when
-+.BR env.SourceSignatures ()
-+is used).
-+
-+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-+.TP
-+.RI Split( arg )
-+.TP
-+.IR env .Split( arg )
-+Returns a list of file names or other objects.
-+If arg is a string,
-+it will be split on strings of white-space characters
-+within the string,
-+making it easier to write long lists of file names.
-+If arg is already a list,
-+the list will be returned untouched.
-+If arg is any other type of object,
-+it will be returned as a list
-+containing just the object.
-+
-+Example:
-+
-+.ES
-+files = Split("f1.c f2.c f3.c")
-+files = env.Split("f4.c f5.c f6.c")
-+files = Split("""
-+	f7.c
-+	f8.c
-+	f9.c
-+""")
-+.EE
-+
-+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-+.TP
-+.IR env .subst( input ", [" raw ", " target ", " source ", " conv ])
-+Performs construction variable interpolation
-+on the specified string or sequence argument
-+.IR input .
-+
-+By default,
-+leading or trailing white space will
-+be removed from the result.
-+and all sequences of white space
-+will be compressed to a single space character.
-+Additionally, any
-+.B $(
-+and
-+.B $)
-+character sequences will be stripped from the returned string,
-+The optional
-+.I raw
-+argument may be set to
-+.B 1
-+if you want to preserve white space and
-+.BR $( - $)
-+sequences.
-+The
-+.I raw
-+argument may be set to
-+.B 2
-+if you want to strip
-+all characters between
-+any
-+.B $(
-+and
-+.B $)
-+pairs
-+(as is done for signature calculation).
-+
-+If the input is a sequence
-+(list or tuple),
-+the individual elements of
-+the sequence will be expanded,
-+and the results will be returned as a list.
-+
-+The optional
-+.I target
-+and
-+.I source
-+keyword arguments
-+must be set to lists of
-+target and source nodes, respectively,
-+if you want the
-+.BR $TARGET ,
-+.BR $TARGETS ,
-+.B $SOURCE
-+and
-+.B $SOURCES
-+to be available for expansion.
-+This is usually necessary if you are
-+calling
-+.BR env.subst ()
-+from within a Python function used
-+as an SCons action.
-+
-+Returned string values or sequence elements
-+are converted to their string representation by default.
-+The optional
-+.I conv
-+argument
-+may specify a conversion function
-+that will be used in place of
-+the default.
-+For example, if you want Python objects
-+(including SCons Nodes)
-+to be returned as Python objects,
-+you can use the Python
-+.B lambda
-+idiom to pass in an unnamed function
-+that simply returns its unconverted argument.
-+
-+Example:
-+
-+.ES
-+print env.subst("The C compiler is: $CC")
-+
-+def compile(target, source, env):
-+    sourceDir = env.subst("${SOURCE.srcdir}",
-+                          target=target,
-+                          source=source)
-+
-+source_nodes = env.subst('$EXPAND_TO_NODELIST',
-+                         conv=lambda x: x)
-+.EE
-+
-+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-+.TP
-+.RI Tag( node ", " tags )
-+Annotates file or directory Nodes with
-+information about how the
-+.BR Package ()
-+Builder should package those files or directories.
-+All tags are optional.
-+
-+Examples:
-+
-+.ES
-+# makes sure the built library will be installed with 0644 file
-+# access mode
-+Tag( Library( 'lib.c' ), UNIX_ATTR="0644" )
-+
-+# marks file2.txt to be a documentation file
-+Tag( 'file2.txt', DOC )
-+.EE
-+
-+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-+.TP
-+.RI TargetSignatures( type )
-+.TP
-+.IR env .TargetSignatures( type )
-+Note:  Although it is not yet officially deprecated,
-+use of this function is discouraged.
-+See the
-+.BR Decider ()
-+function for a more flexible and straightforward way
-+to configure SCons' decision-making.
-+
-+The
-+.BR TargetSignatures ()
-+function tells
-+.B scons
-+how to decide if a target file
-+(a file that
-+.I is
-+built from any other files)
-+has changed since the last time it
-+was used to build some other target file.
-+Legal values are
-+.BR "build" ;
-+.B "content"
-+(or its synonym
-+.BR "MD5" );
-+.BR "timestamp" ;
-+or
-+.BR "source" .
-+
-+If the environment method is used,
-+the specified type of target signature is only used
-+for targets built with that environment.
-+If the global function is used,
-+the specified type of signature becomes the default
-+used for all target files that
-+don't have an explicit target signature type
-+specified for their environments.
-+
-+.B "content"
-+(or its synonym
-+.BR "MD5" )
-+means
-+.B scons
-+decides that a target file has changed
-+if the MD5 checksum of its contents has changed since
-+the last time it was used to rebuild some other target file.
-+This means
-+.B scons
-+will open up
-+MD5 sum the contents
-+of target files after they're built,
-+and may decide that it does not need to rebuild
-+"downstream" target files if a file was
-+rebuilt with exactly the same contents as the last time.
-+
-+.B "timestamp"
-+means
-+.B scons
-+decides that a target file has changed
-+if its timestamp (modification time) has changed since
-+the last time it was used to rebuild some other target file.
-+(Note that although this is similar to the behavior of Make,
-+by default it will also rebuild if the dependency is
-+.I older
-+than the last time it was used to rebuild the target file.)
-+
-+.B "source"
-+means
-+.B scons
-+decides that a target file has changed
-+as specified by the corresponding
-+.BR SourceSignatures ()
-+setting
-+.RB ( "MD5"
-+or
-+.BR "timestamp" ).
-+This means that
-+.B scons
-+will treat all input files to a target the same way,
-+regardless of whether they are source files
-+or have been built from other files.
-+
-+.B "build"
-+means
-+.B scons
-+decides that a target file has changed
-+if it has been rebuilt in this invocation
-+or if its content or timestamp have changed
-+as specified by the corresponding
-+.BR SourceSignatures ()
-+setting.
-+This "propagates" the status of a rebuilt file
-+so that other "downstream" target files
-+will always be rebuilt,
-+even if the contents or the timestamp
-+have not changed.
-+
-+.B "build"
-+signatures are fastest because
-+.B "content"
-+(or
-+.BR "MD5" )
-+signatures take longer to compute,
-+but are more accurate than
-+.B "timestamp"
-+signatures,
-+and can prevent unnecessary "downstream" rebuilds
-+when a target file is rebuilt to the exact same contents
-+as the previous build.
-+The
-+.B "source"
-+setting provides the most consistent behavior
-+when other target files may be rebuilt from
-+both source and target input files.
-+The default value is
-+.BR "source" .
-+
-+Because the default setting is
-+.BR "source" ,
-+using
-+.BR SourceSignatures ()
-+is generally preferable to
-+.BR TargetSignatures (),
-+so that the up-to-date decision
-+will be consistent for all files
-+(or all files built with a specific construction environment).
-+Use of
-+.BR TargetSignatures ()
-+provides specific control for how built target files
-+affect their "downstream" dependencies.
-+
-+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-+.TP
-+.RI Tool( string ", [" toolpath ", **" kw ])
-+.TP
-+.IR env .Tool( string ", [" toolpath ", **" kw ])
-+The
-+.BR Tool ()
-+form of the function
-+returns a callable object
-+that can be used to initialize
-+a construction environment using the
-+tools keyword of the Environment() method.
-+The object may be called with a construction
-+environment as an argument,
-+in which case the object will
-+add the necessary variables
-+to the construction environment
-+and the name of the tool will be added to the
-+.B $TOOLS
-+construction variable.
-+
-+Additional keyword arguments are passed to the tool's
-+.BR generate ()
-+method.
-+
-+Examples:
-+
-+.ES
-+env = Environment(tools = [ Tool('msvc') ])
-+
-+env = Environment()
-+t = Tool('msvc')
-+t(env)  # adds 'msvc' to the TOOLS variable
-+u = Tool('opengl', toolpath = ['tools'])
-+u(env)  # adds 'opengl' to the TOOLS variable
-+.EE
-+.IP
-+The
-+.BR env.Tool ()
-+form of the function
-+applies the callable object for the specified tool
-+.I string
-+to the environment through which the method was called.
-+
-+Additional keyword arguments are passed to the tool's
-+.BR generate ()
-+method.
-+
-+.ES
-+env.Tool('gcc')
-+env.Tool('opengl', toolpath = ['build/tools'])
-+.EE
-+
-+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-+.TP
-+.RI Value( value ", [" built_value ])
-+.TP
-+.IR env .Value( value ", [" built_value ])
-+Returns a Node object representing the specified Python value.  Value
-+Nodes can be used as dependencies of targets.  If the result of
-+calling
-+.BI str( value )
-+changes between SCons runs, any targets depending on
-+.BI Value( value )
-+will be rebuilt.
-+(This is true even when using timestamps to decide if
-+files are up-to-date.)
-+When using timestamp source signatures, Value Nodes'
-+timestamps are equal to the system time when the Node is created.
-+
-+The returned Value Node object has a
-+.BR write ()
-+method that can be used to "build" a Value Node
-+by setting a new value.
-+The optional
-+.I built_value
-+argument can be specified
-+when the Value Node is created
-+to indicate the Node should already be considered
-+"built."
-+There is a corresponding
-+.BR read ()
-+method that will return the built value of the Node.
-+
-+Examples:
-+
-+.ES
-+env = Environment()
-+
-+def create(target, source, env):
-+    # A function that will write a 'prefix=$SOURCE'
-+    # string into the file name specified as the
-+    # $TARGET.
-+    f = open(str(target[0]), 'wb')
-+    f.write('prefix=' + source[0].get_contents())
-+
-+# Fetch the prefix= argument, if any, from the command
-+# line, and use /usr/local as the default.
-+prefix = ARGUMENTS.get('prefix', '/usr/local')
-+
-+# Attach a .Config() builder for the above function action
-+# to the construction environment.
-+env['BUILDERS']['Config'] = Builder(action = create)
-+env.Config(target = 'package-config', source = Value(prefix))
-+
-+def build_value(target, source, env):
-+    # A function that "builds" a Python Value by updating
-+    # the the Python value with the contents of the file
-+    # specified as the source of the Builder call ($SOURCE).
-+    target[0].write(source[0].get_contents())
-+
-+output = env.Value('before')
-+input = env.Value('after')
-+
-+# Attach a .UpdateValue() builder for the above function
-+# action to the construction environment.
-+env['BUILDERS']['UpdateValue'] = Builder(action = build_value)
-+env.UpdateValue(target = Value(output), source = Value(input))
-+.EE
-+
-+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-+.TP
-+.RI VariantDir( variant_dir ", " src_dir ", [" duplicate ])
-+.TP
-+.IR env .VariantDir( variant_dir ", " src_dir ", [" duplicate ])
-+Use the
-+.BR VariantDir ()
-+function to create a copy of your sources in another location:
-+if a name under
-+.I variant_dir
-+is not found but exists under
-+.IR src_dir ,
-+the file or directory is copied to
-+.IR variant_dir .
-+Target files can be built in a different directory
-+than the original sources by simply refering to the sources (and targets)
-+within the variant tree.
-+
-+.BR VariantDir ()
-+can be called multiple times with the same
-+.I src_dir
-+to set up multiple builds with different options
-+.RI ( variants ).
-+The
-+.I src_dir
-+location must be in or underneath the SConstruct file's directory, and
-+.I variant_dir
-+may not be underneath
-+.IR src_dir .
-+
-+The default behavior is for
-+.B scons
-+to physically duplicate the source files in the variant tree.
-+Thus, a build performed in the variant tree is guaranteed to be identical
-+to a build performed in the source tree even if
-+intermediate source files are generated during the build,
-+or preprocessors or other scanners search for included files
-+relative to the source file,
-+or individual compilers or other invoked tools are hard-coded
-+to put derived files in the same directory as source files.
-+
-+If possible on the platform,
-+the duplication is performed by linking rather than copying;
-+see also the
-+.B \-\-duplicate
-+command-line option.
-+Moreover, only the files needed for the build are duplicated;
-+files and directories that are not used are not present in
-+.IR variant_dir .
-+
-+Duplicating the source tree may be disabled by setting the
-+.B duplicate
-+argument to
-+.B 0
-+(zero).
-+This will cause
-+.B scons
-+to invoke Builders using the path names of source files in
-+.I src_dir
-+and the path names of derived files within
-+.IR variant_dir .
-+This is always more efficient than
-+.BR duplicate=1 ,
-+and is usually safe for most builds
-+(but see above for cases that may cause problems).
-+
-+Note that
-+.BR VariantDir ()
-+works most naturally with a subsidiary SConscript file.
-+However, you would then call the subsidiary SConscript file
-+not in the source directory, but in the
-+.IR variant_dir ,
-+regardless of the value of
-+.BR duplicate .
-+This is how you tell
-+.B scons
-+which variant of a source tree to build:
-+
-+.ES
-+# run src/SConscript in two variant directories
-+VariantDir('build/variant1', 'src')
-+SConscript('build/variant1/SConscript')
-+VariantDir('build/variant2', 'src')
-+SConscript('build/variant2/SConscript')
-+.EE
-+.IP
-+See also the
-+.BR SConscript ()
-+function, described above,
-+for another way to specify a variant directory
-+in conjunction with calling a subsidiary SConscript file.
-+
-+Examples:
-+
-+.ES
-+# use names in the build directory, not the source directory
-+VariantDir('build', 'src', duplicate=0)
-+Program('build/prog', 'build/source.c')
-+.EE
-+
-+.ES
-+# this builds both the source and docs in a separate subtree
-+VariantDir('build', '.', duplicate=0)
-+SConscript(dirs=['build/src','build/doc'])
-+.EE
-+
-+.ES
-+# same as previous example, but only uses SConscript
-+SConscript(dirs='src', variant_dir='build/src', duplicate=0)
-+SConscript(dirs='doc', variant_dir='build/doc', duplicate=0)
-+.EE
-+
-+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-+.TP
-+.RI WhereIs( program ", [" path ", " pathext ", " reject ])
-+.TP
-+.IR env .WhereIs( program ", [" path ", " pathext ", " reject ])
-+Searches for the specified executable
-+.IR program ,
-+returning the full path name to the program
-+if it is found,
-+and returning None if not.
-+Searches the specified
-+.IR path ,
-+the value of the calling environment's PATH
-+.RB ( env['ENV']['PATH'] ),
-+or the user's current external PATH
-+.RB ( os.environ['PATH'] )
-+by default.
-+On Windows systems, searches for executable
-+programs with any of the file extensions
-+listed in the specified
-+.IR pathext ,
-+the calling environment's PATHEXT
-+.RB ( env['ENV']['PATHEXT'] )
-+or the user's current PATHEXT
-+.RB ( os.environ['PATHEXT'] )
-+by default.
-+Will not select any
-+path name or names
-+in the specified
-+.I reject
-+list, if any.
-+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-+'\" 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
-+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-+
-+.IP AR
-+The static library archiver.
-+
-+.IP ARCHITECTURE
-+Specifies the system architecture for which
-+the package is being built.
-+The default is the system architecture
-+of the machine on which SCons is running.
-+This is used to fill in the
-+.B Architecture:
-+field in an Ipkg
-+\fBcontrol\fP file,
-+and as part of the name of a generated RPM file.
-+
-+.IP ARCOM
-+The command line used to generate a static library from object files.
-+
-+.IP ARCOMSTR
-+The string displayed when an object file
-+is generated from an assembly-language source file.
-+If this is not set, then \fB$ARCOM\fP (the command line) is displayed.
-+
-+.ES
-+env = Environment(ARCOMSTR = "Archiving $TARGET")
-+.EE
-+
-+.IP ARFLAGS
-+General options passed to the static library archiver.
-+
-+.IP AS
-+The assembler.
-+
-+.IP ASCOM
-+The command line used to generate an object file
-+from an assembly-language source file.
-+
-+.IP ASCOMSTR
-+The string displayed when an object file
-+is generated from an assembly-language source file.
-+If this is not set, then \fB$ASCOM\fP (the command line) is displayed.
-+
-+.ES
-+env = Environment(ASCOMSTR = "Assembling $TARGET")
-+.EE
-+
-+.IP ASFLAGS
-+General options passed to the assembler.
-+
-+.IP ASPPCOM
-+The command line used to assemble an assembly-language
-+source file into an object file
-+after first running the file through the C preprocessor.
-+Any options specified
-+in the \fB$ASFLAGS\fP and \fB$CPPFLAGS\fP construction variables
-+are included on this command line.
-+
-+.IP ASPPCOMSTR
-+The string displayed when an object file
-+is generated from an assembly-language source file
-+after first running the file through the C preprocessor.
-+If this is not set, then \fB$ASPPCOM\fP (the command line) is displayed.
-+
-+.ES
-+env = Environment(ASPPCOMSTR = "Assembling $TARGET")
-+.EE
-+
-+.IP ASPPFLAGS
-+General options when an assembling an assembly-language
-+source file into an object file
-+after first running the file through the C preprocessor.
-+The default is to use the value of \fB$ASFLAGS\fP.
-+
-+.IP BIBTEX
-+The bibliography generator for the TeX formatter and typesetter and the
-+LaTeX structured formatter and typesetter.
-+
-+.IP BIBTEXCOM
-+The command line used to call the bibliography generator for the
-+TeX formatter and typesetter and the LaTeX structured formatter and
-+typesetter.
-+
-+.IP BIBTEXCOMSTR
-+The string displayed when generating a bibliography
-+for TeX or LaTeX.
-+If this is not set, then \fB$BIBTEXCOM\fP (the command line) is displayed.
-+
-+.ES
-+env = Environment(BIBTEXCOMSTR = "Generating bibliography $TARGET")
-+.EE
-+
-+.IP BIBTEXFLAGS
-+General options passed to the bibliography generator for the TeX formatter
-+and typesetter and the LaTeX structured formatter and typesetter.
-+
-+.IP BITKEEPER
-+The BitKeeper executable.
-+
-+.IP BITKEEPERCOM
-+The command line for
-+fetching source files using BitKeeper.
-+
-+.IP BITKEEPERCOMSTR
-+The string displayed when fetching
-+a source file using BitKeeper.
-+If this is not set, then \fB$BITKEEPERCOM\fP
-+(the command line) is displayed.
-+
-+.IP BITKEEPERGET
-+The command (\fB$BITKEEPER\fP) and subcommand
-+for fetching source files using BitKeeper.
-+
-+.IP BITKEEPERGETFLAGS
-+Options that are passed to the BitKeeper
-+.B get
-+subcommand.
-+
-+.IP BUILDERS
-+A dictionary mapping the names of the builders
-+available through this environment
-+to underlying Builder objects.
-+Builders named
-+Alias, CFile, CXXFile, DVI, Library, Object, PDF, PostScript, and Program
-+are available by default.
-+If you initialize this variable when an
-+Environment is created:
-+
-+.ES
-+env = Environment(BUILDERS = {'NewBuilder' : foo})
-+.EE
-+.IP
-+the default Builders will no longer be available.
-+To use a new Builder object in addition to the default Builders,
-+add your new Builder object like this:
-+
-+.ES
-+env = Environment()
-+env.Append(BUILDERS = {'NewBuilder' : foo})
-+.EE
-+.IP
-+or this:
-+
-+.ES
-+env = Environment()
-+env['BUILDERS]['NewBuilder'] = foo
-+.EE
-+
-+.IP CC
-+The C compiler.
-+
-+.IP CCCOM
-+The command line used to compile a C source file to a (static) object
-+file.  Any options specified in the \fB$CFLAGS\fP, \fB$CCFLAGS\fP and
-+\fB$CPPFLAGS\fP construction variables are included on this command
-+line.
-+
-+.IP CCCOMSTR
-+The string displayed when a C source file
-+is compiled to a (static) object file.
-+If this is not set, then \fB$CCCOM\fP (the command line) is displayed.
-+
-+.ES
-+env = Environment(CCCOMSTR = "Compiling static object $TARGET")
-+.EE
-+
-+.IP CCFLAGS
-+General options that are passed to the C and C++ compilers.
-+
-+.IP CCPCHFLAGS
-+Options added to the compiler command line
-+to support building with precompiled headers.
-+The default value expands expands to the appropriate
-+Microsoft Visual C++ command-line options
-+when the \fB$PCH\fP construction variable is set.
-+
-+.IP CCPDBFLAGS
-+Options added to the compiler command line
-+to support storing debugging information in a
-+Microsoft Visual C++ PDB file.
-+The default value expands expands to appropriate
-+Microsoft Visual C++ command-line options
-+when the \fB$PDB\fP construction variable is set.
-+
-+The Visual C++ compiler option that SCons uses by default
-+to generate PDB information is \fB/Z7\fP.
-+This works correctly with parallel (\fB\-j\fP) builds
-+because it embeds the debug information in the intermediate object files,
-+as opposed to sharing a single PDB file between multiple object files.
-+This is also the only way to get debug information
-+embedded into a static library.
-+Using the \fB/Zi\fP instead may yield improved
-+link-time performance,
-+although parallel builds will no longer work.
-+
-+You can generate PDB files with the \fB/Zi\fP
-+switch by overriding the default \fB$CCPDBFLAGS\fP variable as follows:
-+
-+.ES
-+env['CCPDBFLAGS'] = ['${(PDB and "/Zi /Fd%s" % File(PDB)) or ""}']
-+.EE
-+.IP
-+An alternative would be to use the \fB/Zi\fP
-+to put the debugging information in a separate \fB.pdb\fP
-+file for each object file by overriding
-+the \fB$CCPDBFLAGS\fP variable as follows:
-+
-+.ES
-+env['CCPDBFLAGS'] = '/Zi /Fd${TARGET}.pdb'
-+.EE
-+
-+.IP CCVERSION
-+The version number of the C compiler.
-+This may or may not be set,
-+depending on the specific C compiler being used.
-+
-+.IP CFILESUFFIX
-+The suffix for C source files.
-+This is used by the internal CFile builder
-+when generating C files from Lex (.l) or YACC (.y) input files.
-+The default suffix, of course, is
-+.B .c
-+(lower case).
-+On case-insensitive systems (like Windows),
-+SCons also treats
-+.B .C
-+(upper case) files
-+as C files.
-+
-+.IP CFLAGS
-+General options that are passed to the C compiler (C only; not C++).
-+
-+.IP CHANGE_SPECFILE
-+A hook for modifying the file that controls the packaging build
-+(the \fB.spec\fP for RPM,
-+the \fBcontrol\fP for Ipkg,
-+the \fB.wxs\fP for MSI).
-+If set, the function will be called
-+after the SCons template for the file has been written.
-+XXX
-+
-+.IP CHANGED_SOURCES
-+A reserved variable name
-+that may not be set or used in a construction environment.
-+(See "Variable Substitution," below.)
-+
-+.IP CHANGED_TARGETS
-+A reserved variable name
-+that may not be set or used in a construction environment.
-+(See "Variable Substitution," below.)
-+
-+.IP CHANGELOG
-+The name of a file containing the change log text
-+to be included in the package.
-+This is included as the
-+.B %changelog
-+section of the RPM
-+\fB.spec\fP file.
-+
-+.IP _concat
-+A function used to produce variables like \fB$_CPPINCFLAGS\fP. It takes
-+four or five
-+arguments: a prefix to concatenate onto each element, a list of
-+elements, a suffix to concatenate onto each element, an environment
-+for variable interpolation, and an optional function that will be
-+called to transform the list before concatenation.
-+
-+.ES
-+env['_CPPINCFLAGS'] = '$( ${_concat(INCPREFIX, CPPPATH, INCSUFFIX, __env__, RDirs)} $)',
-+.EE
-+
-+.IP CONFIGUREDIR
-+The name of the directory in which
-+Configure context test files are written.
-+The default is
-+.B .sconf_temp
-+in the top-level directory
-+containing the
-+.B SConstruct
-+file.
-+
-+.IP CONFIGURELOG
-+The name of the Configure context log file.
-+The default is
-+.B config.log
-+in the top-level directory
-+containing the
-+.B SConstruct
-+file.
-+
-+.IP _CPPDEFFLAGS
-+An automatically-generated construction variable
-+containing the C preprocessor command-line options
-+to define values.
-+The value of \fB$_CPPDEFFLAGS\fP is created
-+by appending \fB$CPPDEFPREFIX\fP and \fB$CPPDEFSUFFIX\fP
-+to the beginning and end
-+of each definition in \fB$CPPDEFINES\fP.
-+
-+.IP CPPDEFINES
-+A platform independent specification of C preprocessor definitions.
-+The definitions will be added to command lines
-+through the automatically-generated
-+\fB$_CPPDEFFLAGS\fP construction variable (see above),
-+which is constructed according to
-+the type of value of \fB$CPPDEFINES\fP:
-+
-+If \fB$CPPDEFINES\fP is a string,
-+the values of the
-+.BR $CPPDEFPREFIX  and  $CPPDEFSUFFIX
-+construction variables
-+will be added to the beginning and end.
-+
-+.ES
-+# Will add -Dxyz to POSIX compiler command lines,
-+# and /Dxyz to Microsoft Visual C++ command lines.
-+env = Environment(CPPDEFINES='xyz')
-+.EE
-+.IP
-+If \fB$CPPDEFINES\fP is a list,
-+the values of the
-+.BR $CPPDEFPREFIX  and  $CPPDEFSUFFIX
-+construction variables
-+will be appended to the beginning and end
-+of each element in the list.
-+If any element is a list or tuple,
-+then the first item is the name being
-+defined and the second item is its value:
-+
-+.ES
-+# Will add -DB=2 -DA to POSIX compiler command lines,
-+# and /DB=2 /DA to Microsoft Visual C++ command lines.
-+env = Environment(CPPDEFINES=[('B', 2), 'A'])
-+.EE
-+.IP
-+If \fB$CPPDEFINES\fP is a dictionary,
-+the values of the
-+.BR $CPPDEFPREFIX  and  $CPPDEFSUFFIX
-+construction variables
-+will be appended to the beginning and end
-+of each item from the dictionary.
-+The key of each dictionary item
-+is a name being defined
-+to the dictionary item's corresponding value;
-+if the value is
-+.BR None ,
-+then the name is defined without an explicit value.
-+Note that the resulting flags are sorted by keyword
-+to ensure that the order of the options on the
-+command line is consistent each time
-+.B scons
-+is run.
-+
-+.ES
-+# Will add -DA -DB=2 to POSIX compiler command lines,
-+# and /DA /DB=2 to Microsoft Visual C++ command lines.
-+env = Environment(CPPDEFINES={'B':2, 'A':None})
-+.EE
-+
-+.IP CPPDEFPREFIX
-+The prefix used to specify preprocessor definitions
-+on the C compiler command line.
-+This will be appended to the beginning of each definition
-+in the \fB$CPPDEFINES\fP construction variable
-+when the \fB$_CPPDEFFLAGS\fP variable is automatically generated.
-+
-+.IP CPPDEFSUFFIX
-+The suffix used to specify preprocessor definitions
-+on the C compiler command line.
-+This will be appended to the end of each definition
-+in the \fB$CPPDEFINES\fP construction variable
-+when the \fB$_CPPDEFFLAGS\fP variable is automatically generated.
-+
-+.IP CPPFLAGS
-+User-specified C preprocessor options.
-+These will be included in any command that uses the C preprocessor,
-+including not just compilation of C and C++ source files
-+via the \fB$CCCOM\fP,
-+.BR $SHCCCOM ,
-+\fB$CXXCOM\fP and
-+\fB$SHCXXCOM\fP command lines,
-+but also the \fB$FORTRANPPCOM\fP,
-+.BR $SHFORTRANPPCOM ,
-+\fB$F77PPCOM\fP and
-+\fB$SHF77PPCOM\fP command lines
-+used to compile a Fortran source file,
-+and the \fB$ASPPCOM\fP command line
-+used to assemble an assembly language source file,
-+after first running each file through the C preprocessor.
-+Note that this variable does
-+.I not
-+contain
-+.B \-I
-+(or similar) include search path options
-+that scons generates automatically from \fB$CPPPATH\fP.
-+See \fB$_CPPINCFLAGS\fP, below,
-+for the variable that expands to those options.
-+
-+.IP _CPPINCFLAGS
-+An automatically-generated construction variable
-+containing the C preprocessor command-line options
-+for specifying directories to be searched for include files.
-+The value of \fB$_CPPINCFLAGS\fP is created
-+by appending \fB$INCPREFIX\fP and \fB$INCSUFFIX\fP
-+to the beginning and end
-+of each directory in \fB$CPPPATH\fP.
-+
-+.IP CPPPATH
-+The list of directories that the C preprocessor will search for include
-+directories. The C/C++ implicit dependency scanner will search these
-+directories for include files. Don't explicitly put include directory
-+arguments in CCFLAGS or CXXFLAGS because the result will be non-portable
-+and the directories will not be searched by the dependency scanner. Note:
-+directory names in CPPPATH will be looked-up relative to the SConscript
-+directory when they are used in a command. To force
-+.B scons
-+to look-up a directory relative to the root of the source tree use #:
-+
-+.ES
-+env = Environment(CPPPATH='#/include')
-+.EE
-+.IP
-+The directory look-up can also be forced using the
-+.BR Dir ()
-+function:
-+
-+.ES
-+include = Dir('include')
-+env = Environment(CPPPATH=include)
-+.EE
-+.IP
-+The directory list will be added to command lines
-+through the automatically-generated
-+.B $_CPPINCFLAGS
-+construction variable,
-+which is constructed by
-+appending the values of the
-+.BR $INCPREFIX  and  $INCSUFFIX
-+construction variables
-+to the beginning and end
-+of each directory in \fB$CPPPATH\fP.
-+Any command lines you define that need
-+the CPPPATH directory list should
-+include \fB$_CPPINCFLAGS\fP:
-+
-+.ES
-+env = Environment(CCCOM="my_compiler $_CPPINCFLAGS -c -o $TARGET $SOURCE")
-+.EE
-+
-+.IP CPPSUFFIXES
-+The list of suffixes of files that will be scanned
-+for C preprocessor implicit dependencies
-+(#include lines).
-+The default list is:
-+
-+.ES
-+[".c", ".C", ".cxx", ".cpp", ".c++", ".cc",
-+ ".h", ".H", ".hxx", ".hpp", ".hh",
-+ ".F", ".fpp", ".FPP",
-+ ".m", ".mm",
-+ ".S", ".spp", ".SPP"]
-+.EE
-+
-+.IP CVS
-+The CVS executable.
-+
-+.IP CVSCOFLAGS
-+Options that are passed to the CVS checkout subcommand.
-+
-+.IP CVSCOM
-+The command line used to
-+fetch source files from a CVS repository.
-+
-+.IP CVSCOMSTR
-+The string displayed when fetching
-+a source file from a CVS repository.
-+If this is not set, then \fB$CVSCOM\fP
-+(the command line) is displayed.
-+
-+.IP CVSFLAGS
-+General options that are passed to CVS.
-+By default, this is set to
-+.B "-d $CVSREPOSITORY"
-+to specify from where the files must be fetched.
-+
-+.IP CVSREPOSITORY
-+The path to the CVS repository.
-+This is referenced in the default
-+\fB$CVSFLAGS\fP value.
-+
-+.IP CXX
-+The C++ compiler.
-+
-+.IP CXXCOM
-+The command line used to compile a C++ source file to an object file.
-+Any options specified in the \fB$CXXFLAGS\fP and
-+\fB$CPPFLAGS\fP construction variables
-+are included on this command line.
-+
-+.IP CXXCOMSTR
-+The string displayed when a C++ source file
-+is compiled to a (static) object file.
-+If this is not set, then \fB$CXXCOM\fP (the command line) is displayed.
-+
-+.ES
-+env = Environment(CXXCOMSTR = "Compiling static object $TARGET")
-+.EE
-+
-+.IP CXXFILESUFFIX
-+The suffix for C++ source files.
-+This is used by the internal CXXFile builder
-+when generating C++ files from Lex (.ll) or YACC (.yy) input files.
-+The default suffix is
-+.BR .cc .
-+SCons also treats files with the suffixes
-+.BR .cpp ,
-+.BR .cxx ,
-+.BR .c++ ,
-+and
-+.B .C++
-+as C++ files,
-+and files with
-+.B .mm
-+suffixes as Objective C++ files.
-+On case-sensitive systems (Linux, UNIX, and other POSIX-alikes),
-+SCons also treats
-+.B .C
-+(upper case) files
-+as C++ files.
-+
-+.IP CXXFLAGS
-+General options that are passed to the C++ compiler.
-+By default, this includes the value of \fB$CCFLAGS\fP,
-+so that setting \fB$CCFLAGS\fP affects both C and C++ compilation.
-+If you want to add C++-specific flags,
-+you must set or override the value of \fB$CXXFLAGS\fP.
-+
-+.IP CXXVERSION
-+The version number of the C++ compiler.
-+This may or may not be set,
-+depending on the specific C++ compiler being used.
-+
-+.IP DESCRIPTION
-+A long description of the project being packaged.
-+This is included in the relevant section
-+of the file that controls the packaging build.
-+
-+.IP DESCRIPTION_lang
-+A language-specific long description for
-+the specified \fIlang\fP.
-+This is used to populate a
-+.B "%description -l"
-+section of an RPM
-+\fB.spec\fP file.
-+
-+.IP Dir
-+A function that converts a string
-+into a Dir instance relative to the target being built.
-+
-+.IP Dirs
-+A function that converts a list of strings
-+into a list of Dir instances relative to the target being built.
-+
-+.IP DSUFFIXES
-+The list of suffixes of files that will be scanned
-+for imported D package files.
-+The default list is:
-+
-+.ES
-+['.d']
-+.EE
-+
-+.IP DVIPDF
-+The TeX DVI file to PDF file converter.
-+
-+.IP DVIPDFCOM
-+The command line used to convert TeX DVI files into a PDF file.
-+
-+.IP DVIPDFCOMSTR
-+The string displayed when a TeX DVI file
-+is converted into a PDF file.
-+If this is not set, then \fB$DVIPDFCOM\fP (the command line) is displayed.
-+
-+.IP DVIPDFFLAGS
-+General options passed to the TeX DVI file to PDF file converter.
-+
-+.IP DVIPS
-+The TeX DVI file to PostScript converter.
-+
-+.IP DVIPSFLAGS
-+General options passed to the TeX DVI file to PostScript converter.
-+
-+.IP ENV
-+A dictionary of environment variables
-+to use when invoking commands. When
-+\fB$ENV\fP is used in a command all list
-+values will be joined using the path separator and any other non-string
-+values will simply be coerced to a string.
-+Note that, by default,
-+.B scons
-+does
-+.I not
-+propagate the environment in force when you
-+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.
-+
-+If you want to propagate your
-+environment variables
-+to the commands executed
-+to build target files,
-+you must do so explicitly:
-+
-+.ES
-+import os
-+env = Environment(ENV = os.environ)
-+.EE
-+.IP
-+Note that you can choose only to propagate
-+certain environment variables.
-+A common example is
-+the system
-+.B PATH
-+environment variable,
-+so that
-+.B scons
-+uses the same utilities
-+as the invoking shell (or other process):
-+
-+.ES
-+import os
-+env = Environment(ENV = {'PATH' : os.environ['PATH']})
-+.EE
-+
-+.IP ESCAPE
-+A function that will be called to escape shell special characters in
-+command lines. The function should take one argument: the command line
-+string to escape; and should return the escaped command line.
-+
-+.IP F77
-+The Fortran 77 compiler.
-+You should normally set the \fB$FORTRAN\fP variable,
-+which specifies the default Fortran compiler
-+for all Fortran versions.
-+You only need to set \fB$F77\fP if you need to use a specific compiler
-+or compiler version for Fortran 77 files.
-+
-+.IP F77COM
-+The command line used to compile a Fortran 77 source file to an object file.
-+You only need to set \fB$F77COM\fP if you need to use a specific
-+command line for Fortran 77 files.
-+You should normally set the \fB$FORTRANCOM\fP variable,
-+which specifies the default command line
-+for all Fortran versions.
-+
-+.IP F77COMSTR
-+The string displayed when a Fortran 77 source file
-+is compiled to an object file.
-+If this is not set, then \fB$F77COM\fP or \fB$FORTRANCOM\fP
-+(the command line) is displayed.
-+
-+.IP F77FILESUFFIXES
-+The list of file extensions for which the F77 dialect will be used. By
-+default, this is ['.f77']
-+
-+.IP F77FLAGS
-+General user-specified options that are passed to the Fortran 77 compiler.
-+Note that this variable does
-+.I not
-+contain
-+.B \-I
-+(or similar) include search path options
-+that scons generates automatically from \fB$F77PATH\fP.
-+See
-+.B $_F77INCFLAGS
-+below,
-+for the variable that expands to those options.
-+You only need to set \fB$F77FLAGS\fP if you need to define specific
-+user options for Fortran 77 files.
-+You should normally set the \fB$FORTRANFLAGS\fP variable,
-+which specifies the user-specified options
-+passed to the default Fortran compiler
-+for all Fortran versions.
-+
-+.IP _F77INCFLAGS
-+An automatically-generated construction variable
-+containing the Fortran 77 compiler command-line options
-+for specifying directories to be searched for include files.
-+The value of \fB$_F77INCFLAGS\fP is created
-+by appending \fB$INCPREFIX\fP and \fB$INCSUFFIX\fP
-+to the beginning and end
-+of each directory in \fB$F77PATH\fP.
-+
-+.IP F77PATH
-+The list of directories that the Fortran 77 compiler will search for include
-+directories. The implicit dependency scanner will search these
-+directories for include files. Don't explicitly put include directory
-+arguments in \fB$F77FLAGS\fP because the result will be non-portable
-+and the directories will not be searched by the dependency scanner. Note:
-+directory names in \fB$F77PATH\fP will be looked-up relative to the SConscript
-+directory when they are used in a command. To force
-+.B scons
-+to look-up a directory relative to the root of the source tree use #:
-+You only need to set \fB$F77PATH\fP if you need to define a specific
-+include path for Fortran 77 files.
-+You should normally set the \fB$FORTRANPATH\fP variable,
-+which specifies the include path
-+for the default Fortran compiler
-+for all Fortran versions.
-+
-+.ES
-+env = Environment(F77PATH='#/include')
-+.EE
-+.IP
-+The directory look-up can also be forced using the
-+.BR Dir ()
-+function:
-+
-+.ES
-+include = Dir('include')
-+env = Environment(F77PATH=include)
-+.EE
-+.IP
-+The directory list will be added to command lines
-+through the automatically-generated
-+.B $_F77INCFLAGS
-+construction variable,
-+which is constructed by
-+appending the values of the
-+.BR $INCPREFIX  and  $INCSUFFIX
-+construction variables
-+to the beginning and end
-+of each directory in \fB$F77PATH\fP.
-+Any command lines you define that need
-+the F77PATH directory list should
-+include \fB$_F77INCFLAGS\fP:
-+
-+.ES
-+env = Environment(F77COM="my_compiler $_F77INCFLAGS -c -o $TARGET $SOURCE")
-+.EE
-+
-+.IP F77PPCOM
-+The command line used to compile a Fortran 77 source file to an object file
-+after first running the file through the C preprocessor.
-+Any options specified in the \fB$F77FLAGS\fP and \fB$CPPFLAGS\fP construction variables
-+are included on this command line.
-+You only need to set \fB$F77PPCOM\fP if you need to use a specific
-+C-preprocessor command line for Fortran 77 files.
-+You should normally set the \fB$FORTRANPPCOM\fP variable,
-+which specifies the default C-preprocessor command line
-+for all Fortran versions.
-+
-+.IP F77PPCOMSTR
-+The string displayed when a Fortran 77 source file
-+is compiled to an object file
-+after first running the file through the C preprocessor.
-+If this is not set, then \fB$F77PPCOM\fP or \fB$FORTRANPPCOM\fP
-+(the command line) is displayed.
-+
-+.IP F77PPFILESUFFIXES
-+The list of file extensions for which the compilation + preprocessor pass for
-+F77 dialect will be used. By default, this is empty
-+
-+.IP F90
-+The Fortran 90 compiler.
-+You should normally set the \fB$FORTRAN\fP variable,
-+which specifies the default Fortran compiler
-+for all Fortran versions.
-+You only need to set \fB$F90\fP if you need to use a specific compiler
-+or compiler version for Fortran 90 files.
-+
-+.IP F90COM
-+The command line used to compile a Fortran 90 source file to an object file.
-+You only need to set \fB$F90COM\fP if you need to use a specific
-+command line for Fortran 90 files.
-+You should normally set the \fB$FORTRANCOM\fP variable,
-+which specifies the default command line
-+for all Fortran versions.
-+
-+.IP F90COMSTR
-+The string displayed when a Fortran 90 source file
-+is compiled to an object file.
-+If this is not set, then \fB$F90COM\fP or \fB$FORTRANCOM\fP
-+(the command line) is displayed.
-+
-+.IP F90FILESUFFIXES
-+The list of file extensions for which the F90 dialect will be used. By
-+default, this is ['.f90']
-+
-+.IP F90FLAGS
-+General user-specified options that are passed to the Fortran 90 compiler.
-+Note that this variable does
-+.I not
-+contain
-+.B \-I
-+(or similar) include search path options
-+that scons generates automatically from \fB$F90PATH\fP.
-+See
-+.B $_F90INCFLAGS
-+below,
-+for the variable that expands to those options.
-+You only need to set \fB$F90FLAGS\fP if you need to define specific
-+user options for Fortran 90 files.
-+You should normally set the \fB$FORTRANFLAGS\fP variable,
-+which specifies the user-specified options
-+passed to the default Fortran compiler
-+for all Fortran versions.
-+
-+.IP _F90INCFLAGS
-+An automatically-generated construction variable
-+containing the Fortran 90 compiler command-line options
-+for specifying directories to be searched for include files.
-+The value of \fB$_F90INCFLAGS\fP is created
-+by appending \fB$INCPREFIX\fP and \fB$INCSUFFIX\fP
-+to the beginning and end
-+of each directory in \fB$F90PATH\fP.
-+
-+.IP F90PATH
-+The list of directories that the Fortran 90 compiler will search for include
-+directories. The implicit dependency scanner will search these
-+directories for include files. Don't explicitly put include directory
-+arguments in \fB$F90FLAGS\fP because the result will be non-portable
-+and the directories will not be searched by the dependency scanner. Note:
-+directory names in \fB$F90PATH\fP will be looked-up relative to the SConscript
-+directory when they are used in a command. To force
-+.B scons
-+to look-up a directory relative to the root of the source tree use #:
-+You only need to set \fB$F90PATH\fP if you need to define a specific
-+include path for Fortran 90 files.
-+You should normally set the \fB$FORTRANPATH\fP variable,
-+which specifies the include path
-+for the default Fortran compiler
-+for all Fortran versions.
-+
-+.ES
-+env = Environment(F90PATH='#/include')
-+.EE
-+.IP
-+The directory look-up can also be forced using the
-+.BR Dir ()
-+function:
-+
-+.ES
-+include = Dir('include')
-+env = Environment(F90PATH=include)
-+.EE
-+.IP
-+The directory list will be added to command lines
-+through the automatically-generated
-+.B $_F90INCFLAGS
-+construction variable,
-+which is constructed by
-+appending the values of the
-+.BR $INCPREFIX  and  $INCSUFFIX
-+construction variables
-+to the beginning and end
-+of each directory in \fB$F90PATH\fP.
-+Any command lines you define that need
-+the F90PATH directory list should
-+include \fB$_F90INCFLAGS\fP:
-+
-+.ES
-+env = Environment(F90COM="my_compiler $_F90INCFLAGS -c -o $TARGET $SOURCE")
-+.EE
-+
-+.IP F90PPCOM
-+The command line used to compile a Fortran 90 source file to an object file
-+after first running the file through the C preprocessor.
-+Any options specified in the \fB$F90FLAGS\fP and \fB$CPPFLAGS\fP construction variables
-+are included on this command line.
-+You only need to set \fB$F90PPCOM\fP if you need to use a specific
-+C-preprocessor command line for Fortran 90 files.
-+You should normally set the \fB$FORTRANPPCOM\fP variable,
-+which specifies the default C-preprocessor command line
-+for all Fortran versions.
-+
-+.IP F90PPCOMSTR
-+The string displayed when a Fortran 90 source file
-+is compiled after first running the file through the C preprocessor.
-+If this is not set, then \fB$F90PPCOM\fP or \fB$FORTRANPPCOM\fP
-+(the command line) is displayed.
-+
-+.IP F90PPFILESUFFIXES
-+The list of file extensions for which the compilation + preprocessor pass for
-+F90 dialect will be used. By default, this is empty
-+
-+.IP F95
-+The Fortran 95 compiler.
-+You should normally set the \fB$FORTRAN\fP variable,
-+which specifies the default Fortran compiler
-+for all Fortran versions.
-+You only need to set \fB$F95\fP if you need to use a specific compiler
-+or compiler version for Fortran 95 files.
-+
-+.IP F95COM
-+The command line used to compile a Fortran 95 source file to an object file.
-+You only need to set \fB$F95COM\fP if you need to use a specific
-+command line for Fortran 95 files.
-+You should normally set the \fB$FORTRANCOM\fP variable,
-+which specifies the default command line
-+for all Fortran versions.
-+
-+.IP F95COMSTR
-+The string displayed when a Fortran 95 source file
-+is compiled to an object file.
-+If this is not set, then \fB$F95COM\fP or \fB$FORTRANCOM\fP
-+(the command line) is displayed.
-+
-+.IP F95FILESUFFIXES
-+The list of file extensions for which the F95 dialect will be used. By
-+default, this is ['.f95']
-+
-+.IP F95FLAGS
-+General user-specified options that are passed to the Fortran 95 compiler.
-+Note that this variable does
-+.I not
-+contain
-+.B \-I
-+(or similar) include search path options
-+that scons generates automatically from \fB$F95PATH\fP.
-+See
-+.B $_F95INCFLAGS
-+below,
-+for the variable that expands to those options.
-+You only need to set \fB$F95FLAGS\fP if you need to define specific
-+user options for Fortran 95 files.
-+You should normally set the \fB$FORTRANFLAGS\fP variable,
-+which specifies the user-specified options
-+passed to the default Fortran compiler
-+for all Fortran versions.
-+
-+.IP _F95INCFLAGS
-+An automatically-generated construction variable
-+containing the Fortran 95 compiler command-line options
-+for specifying directories to be searched for include files.
-+The value of \fB$_F95INCFLAGS\fP is created
-+by appending \fB$INCPREFIX\fP and \fB$INCSUFFIX\fP
-+to the beginning and end
-+of each directory in \fB$F95PATH\fP.
-+
-+.IP F95PATH
-+The list of directories that the Fortran 95 compiler will search for include
-+directories. The implicit dependency scanner will search these
-+directories for include files. Don't explicitly put include directory
-+arguments in \fB$F95FLAGS\fP because the result will be non-portable
-+and the directories will not be searched by the dependency scanner. Note:
-+directory names in \fB$F95PATH\fP will be looked-up relative to the SConscript
-+directory when they are used in a command. To force
-+.B scons
-+to look-up a directory relative to the root of the source tree use #:
-+You only need to set \fB$F95PATH\fP if you need to define a specific
-+include path for Fortran 95 files.
-+You should normally set the \fB$FORTRANPATH\fP variable,
-+which specifies the include path
-+for the default Fortran compiler
-+for all Fortran versions.
-+
-+.ES
-+env = Environment(F95PATH='#/include')
-+.EE
-+.IP
-+The directory look-up can also be forced using the
-+.BR Dir ()
-+function:
-+
-+.ES
-+include = Dir('include')
-+env = Environment(F95PATH=include)
-+.EE
-+.IP
-+The directory list will be added to command lines
-+through the automatically-generated
-+.B $_F95INCFLAGS
-+construction variable,
-+which is constructed by
-+appending the values of the
-+.BR $INCPREFIX  and  $INCSUFFIX
-+construction variables
-+to the beginning and end
-+of each directory in \fB$F95PATH\fP.
-+Any command lines you define that need
-+the F95PATH directory list should
-+include \fB$_F95INCFLAGS\fP:
-+
-+.ES
-+env = Environment(F95COM="my_compiler $_F95INCFLAGS -c -o $TARGET $SOURCE")
-+.EE
-+
-+.IP F95PPCOM
-+The command line used to compile a Fortran 95 source file to an object file
-+after first running the file through the C preprocessor.
-+Any options specified in the \fB$F95FLAGS\fP and \fB$CPPFLAGS\fP construction variables
-+are included on this command line.
-+You only need to set \fB$F95PPCOM\fP if you need to use a specific
-+C-preprocessor command line for Fortran 95 files.
-+You should normally set the \fB$FORTRANPPCOM\fP variable,
-+which specifies the default C-preprocessor command line
-+for all Fortran versions.
-+
-+.IP F95PPCOMSTR
-+The string displayed when a Fortran 95 source file
-+is compiled to an object file
-+after first running the file through the C preprocessor.
-+If this is not set, then \fB$F95PPCOM\fP or \fB$FORTRANPPCOM\fP
-+(the command line) is displayed.
-+
-+.IP F95PPFILESUFFIXES
-+The list of file extensions for which the compilation + preprocessor pass for
-+F95 dialect will be used. By default, this is empty
-+
-+.IP File
-+A function that converts a string into a File instance relative to the
-+target being built.
-+
-+.IP FORTRAN
-+The default Fortran compiler
-+for all versions of Fortran.
-+
-+.IP FORTRANCOM
-+The command line used to compile a Fortran source file to an object file.
-+By default, any options specified
-+in the \fB$FORTRANFLAGS\fP,
-+.BR $CPPFLAGS ,
-+.BR $_CPPDEFFLAGS ,
-+\fB$_FORTRANMODFLAG\fP, and
-+\fB$_FORTRANINCFLAGS\fP construction variables
-+are included on this command line.
-+
-+.IP FORTRANCOMSTR
-+The string displayed when a Fortran source file
-+is compiled to an object file.
-+If this is not set, then \fB$FORTRANCOM\fP
-+(the command line) is displayed.
-+
-+.IP FORTRANFILESUFFIXES
-+The list of file extensions for which the FORTRAN dialect will be used. By
-+default, this is ['.f', '.for', '.ftn']
-+
-+.IP FORTRANFLAGS
-+General user-specified options that are passed to the Fortran compiler.
-+Note that this variable does
-+.I not
-+contain
-+.B \-I
-+(or similar) include or module search path options
-+that scons generates automatically from \fB$FORTRANPATH\fP.
-+See
-+.BR $_FORTRANINCFLAGS\fP and \fB$_FORTRANMODFLAG ,
-+below,
-+for the variables that expand those options.
-+
-+.IP _FORTRANINCFLAGS
-+An automatically-generated construction variable
-+containing the Fortran compiler command-line options
-+for specifying directories to be searched for include
-+files and module files.
-+The value of \fB$_FORTRANINCFLAGS\fP is created
-+by prepending/appending \fB$INCPREFIX\fP and \fB$INCSUFFIX\fP
-+to the beginning and end
-+of each directory in \fB$FORTRANPATH\fP.
-+
-+.IP FORTRANMODDIR
-+Directory location where the Fortran compiler should place
-+any module files it generates.  This variable is empty, by default. Some
-+Fortran compilers will internally append this directory in the search path
-+for module files, as well.
-+
-+.IP FORTRANMODDIRPREFIX
-+The prefix used to specify a module directory on the Fortran compiler command
-+line.
-+This will be appended to the beginning of the directory
-+in the \fB$FORTRANMODDIR\fP construction variables
-+when the \fB$_FORTRANMODFLAG\fP variables is automatically generated.
-+
-+.IP FORTRANMODDIRSUFFIX
-+The suffix used to specify a module directory on the Fortran compiler command
-+line.
-+This will be appended to the beginning of the directory
-+in the \fB$FORTRANMODDIR\fP construction variables
-+when the \fB$_FORTRANMODFLAG\fP variables is automatically generated.
-+
-+.IP _FORTRANMODFLAG
-+An automatically-generated construction variable
-+containing the Fortran compiler command-line option
-+for specifying the directory location where the Fortran
-+compiler should place any module files that happen to get
-+generated during compilation.
-+The value of \fB$_FORTRANMODFLAG\fP is created
-+by prepending/appending \fB$FORTRANMODDIRPREFIX\fP and
-+.B $FORTRANMODDIRSUFFIX
-+to the beginning and end of the directory in \fB$FORTRANMODDIR\fP.
-+
-+.IP FORTRANMODPREFIX
-+The module file prefix used by the Fortran compiler.  SCons assumes that
-+the Fortran compiler follows the quasi-standard naming convention for
-+module files of
-+.BR module_name.mod .
-+As a result, this variable is left empty, by default.  For situations in
-+which the compiler does not necessarily follow the normal convention,
-+the user may use this variable.  Its value will be appended to every
-+module file name as scons attempts to resolve dependencies.
-+
-+.IP FORTRANMODSUFFIX
-+The module file suffix used by the Fortran compiler.  SCons assumes that
-+the Fortran compiler follows the quasi-standard naming convention for
-+module files of
-+.BR module_name.mod .
-+As a result, this variable is set to ".mod", by default.  For situations
-+in which the compiler does not necessarily follow the normal convention,
-+the user may use this variable.  Its value will be appended to every
-+module file name as scons attempts to resolve dependencies.
-+
-+.IP FORTRANPATH
-+The list of directories that the Fortran compiler will search for
-+include files and (for some compilers) module files. The Fortran implicit
-+dependency scanner will search these directories for include files (but
-+not module files since they are autogenerated and, as such, may not
-+actually exist at the time the scan takes place). Don't explicitly put
-+include directory arguments in FORTRANFLAGS because the result will be
-+non-portable and the directories will not be searched by the dependency
-+scanner. Note: directory names in FORTRANPATH will be looked-up relative
-+to the SConscript directory when they are used in a command. To force
-+.B scons
-+to look-up a directory relative to the root of the source tree use #:
-+
-+.ES
-+env = Environment(FORTRANPATH='#/include')
-+.EE
-+.IP
-+The directory look-up can also be forced using the
-+.BR Dir ()
-+function:
-+
-+.ES
-+include = Dir('include')
-+env = Environment(FORTRANPATH=include)
-+.EE
-+.IP
-+The directory list will be added to command lines
-+through the automatically-generated
-+.B $_FORTRANINCFLAGS
-+construction variable,
-+which is constructed by
-+appending the values of the
-+.BR $INCPREFIX  and  $INCSUFFIX
-+construction variables
-+to the beginning and end
-+of each directory in \fB$FORTRANPATH\fP.
-+Any command lines you define that need
-+the FORTRANPATH directory list should
-+include \fB$_FORTRANINCFLAGS\fP:
-+
-+.ES
-+env = Environment(FORTRANCOM="my_compiler $_FORTRANINCFLAGS -c -o $TARGET $SOURCE")
-+.EE
-+
-+.IP FORTRANPPCOM
-+The command line used to compile a Fortran source file to an object file
-+after first running the file through the C preprocessor.
-+By default, any options specified in the \fB$FORTRANFLAGS\fP,
-+.BR $CPPFLAGS ,
-+.BR $_CPPDEFFLAGS ,
-+\fB$_FORTRANMODFLAG\fP, and
-+.B $_FORTRANINCFLAGS
-+construction variables are included on this command line.
-+
-+.IP FORTRANPPCOMSTR
-+The string displayed when a Fortran source file
-+is compiled to an object file
-+after first running the file through the C preprocessor.
-+If this is not set, then \fB$FORTRANPPCOM\fP
-+(the command line) is displayed.
-+
-+.IP FORTRANPPFILESUFFIXES
-+The list of file extensions for which the compilation + preprocessor pass for
-+FORTRAN dialect will be used. By default, this is ['.fpp', '.FPP']
-+
-+.IP FORTRANSUFFIXES
-+The list of suffixes of files that will be scanned
-+for Fortran implicit dependencies
-+(INCLUDE lines and USE statements).
-+The default list is:
-+
-+.ES
-+[".f", ".F", ".for", ".FOR", ".ftn", ".FTN", ".fpp", ".FPP",
-+".f77", ".F77", ".f90", ".F90", ".f95", ".F95"]
-+.EE
-+
-+.IP FRAMEWORKPATH
-+On Mac OS X with gcc,
-+a list containing the paths to search for frameworks.
-+Used by the compiler to find framework-style includes like
-+#include <Fmwk/Header.h>.
-+Used by the linker to find user-specified frameworks when linking (see
-+.BR $FRAMEWORKS ).
-+For example:
-+
-+.ES
-+ env.AppendUnique(FRAMEWORKPATH='#myframeworkdir')
-+.EE
-+.IP
-+will add
-+
-+.ES
-+  ... -Fmyframeworkdir
-+.EE
-+.IP
-+to the compiler and linker command lines.
-+
-+.IP _FRAMEWORKPATH
-+On Mac OS X with gcc, an automatically-generated construction variable
-+containing the linker command-line options corresponding to
-+.BR $FRAMEWORKPATH .
-+
-+.IP FRAMEWORKPATHPREFIX
-+On Mac OS X with gcc, the prefix to be used for the FRAMEWORKPATH entries.
-+(see \fB$FRAMEWORKPATH\fP).
-+The default value is
-+.BR \-F .
-+
-+.IP FRAMEWORKPREFIX
-+On Mac OS X with gcc,
-+the prefix to be used for linking in frameworks
-+(see \fB$FRAMEWORKS\fP).
-+The default value is
-+.BR \-framework .
-+
-+.IP _FRAMEWORKS
-+On Mac OS X with gcc,
-+an automatically-generated construction variable
-+containing the linker command-line options
-+for linking with FRAMEWORKS.
-+
-+.IP FRAMEWORKS
-+On Mac OS X with gcc, a list of the framework names to be linked into a
-+program or shared library or bundle.
-+The default value is the empty list.
-+For example:
-+
-+.ES
-+ env.AppendUnique(FRAMEWORKS=Split('System Cocoa SystemConfiguration'))
-+.EE
-+.IP
-+
-+.IP FRAMEWORKSFLAGS
-+On Mac OS X with gcc,
-+general user-supplied frameworks options to be added at
-+the end of a command
-+line building a loadable module.
-+(This has been largely superseded by
-+the \fB$FRAMEWORKPATH\fP, \fB$FRAMEWORKPATHPREFIX\fP,
-+\fB$FRAMEWORKPREFIX\fP and \fB$FRAMEWORKS\fP variables
-+described above.)
-+
-+.IP GS
-+The Ghostscript program used to convert PostScript to PDF files.
-+
-+.IP GSCOM
-+The Ghostscript command line used to convert PostScript to PDF files.
-+
-+.IP GSCOMSTR
-+The string displayed when
-+Ghostscript is used to convert
-+a PostScript file to a PDF file.
-+If this is not set, then \fB$GSCOM\fP (the command line) is displayed.
-+
-+.IP GSFLAGS
-+General options passed to the Ghostscript program
-+when converting PostScript to PDF files.
-+
-+.IP HOST_ARCH
-+Sets the host architecture for Visual Studio compiler. If not set,
-+default to the detected host architecture: note that this may depend
-+on the python you are using.
-+This variable must be passed as an argument to the Environment()
-+constructor; setting it later has no effect. 
-+
-+Valid values are the same as for \fB$TARGET_ARCH\fP.
-+
-+This is currently only used on Windows, but in the future it will be
-+used on other OSes as well.
-+
-+.IP HOST_OS
-+        The name of the host operating system used to create the Environment.
-+        If a platform is specified when creating the Environment, then
-+        that Platform's logic will handle setting this value.
-+        This value is immutable, and should not be changed by the user after
-+        the Environment is initialized.
-+        Currently only set for Win32.
-+    
-+.IP IDLSUFFIXES
-+The list of suffixes of files that will be scanned
-+for IDL implicit dependencies
-+(#include or import lines).
-+The default list is:
-+
-+.ES
-+[".idl", ".IDL"]
-+.EE
-+
-+.IP IMPLICIT_COMMAND_DEPENDENCIES
-+Controls whether or not SCons will
-+add implicit dependencies for the commands
-+executed to build targets.
-+
-+By default, SCons will add
-+to each target
-+an implicit dependency on the command
-+represented by the first argument on any
-+command line it executes.
-+The specific file for the dependency is
-+found by searching the
-+.I PATH
-+variable in the
-+.I ENV
-+environment used to execute the command.
-+
-+If the construction variable
-+.B $IMPLICIT_COMMAND_DEPENDENCIES
-+is set to a false value
-+.RB ( None ,
-+.BR False ,
-+.BR 0 ,
-+etc.),
-+then the implicit dependency will
-+not be added to the targets
-+built with that construction environment.
-+
-+.ES
-+env = Environment(IMPLICIT_COMMAND_DEPENDENCIES = 0)
-+.EE
-+
-+.IP INCPREFIX
-+The prefix used to specify an include directory on the C compiler command
-+line.
-+This will be appended to the beginning of each directory
-+in the \fB$CPPPATH\fP and \fB$FORTRANPATH\fP construction variables
-+when the \fB$_CPPINCFLAGS\fP and \fB$_FORTRANINCFLAGS\fP
-+variables are automatically generated.
-+
-+.IP INCSUFFIX
-+The suffix used to specify an include directory on the C compiler command
-+line.
-+This will be appended to the end of each directory
-+in the \fB$CPPPATH\fP and \fB$FORTRANPATH\fP construction variables
-+when the \fB$_CPPINCFLAGS\fP and \fB$_FORTRANINCFLAGS\fP
-+variables are automatically generated.
-+
-+.IP INSTALL
-+A function to be called to install a file into a
-+destination file name.
-+The default function copies the file into the destination
-+(and sets the destination file's mode and permission bits
-+to match the source file's).
-+The function takes the following arguments:
-+
-+.ES
-+def install(dest, source, env):
-+.EE
-+.IP
-+.I dest
-+is the path name of the destination file.
-+.I source
-+is the path name of the source file.
-+.I env
-+is the construction environment
-+(a dictionary of construction values)
-+in force for this file installation.
-+
-+.IP INSTALLSTR
-+The string displayed when a file is
-+installed into a destination file name.
-+The default is:
-+.ES
-+Install file: "$SOURCE" as "$TARGET"
-+.EE
-+
-+.IP INTEL_C_COMPILER_VERSION
-+Set by the "intelc" Tool
-+to the major version number of the Intel C compiler
-+selected for use.
-+
-+.IP JAR
-+The Java archive tool.
-+
-+.IP JARCHDIR
-+The directory to which the Java archive tool should change
-+(using the
-+.B \-C
-+option).
-+
-+.IP JARCOM
-+The command line used to call the Java archive tool.
-+
-+.IP JARCOMSTR
-+The string displayed when the Java archive tool
-+is called
-+If this is not set, then \fB$JARCOM\fP (the command line) is displayed.
-+
-+.ES
-+env = Environment(JARCOMSTR = "JARchiving $SOURCES into $TARGET")
-+.EE
-+
-+.IP JARFLAGS
-+General options passed to the Java archive tool.
-+By default this is set to
-+.B cf
-+to create the necessary
-+.B jar
-+file.
-+
-+.IP JARSUFFIX
-+The suffix for Java archives:
-+.B .jar
-+by default.
-+
-+.IP JAVABOOTCLASSPATH
-+Specifies the list of directories that
-+will be added to the
-+&javac; command line
-+via the \fB\-bootclasspath\fP option.
-+The individual directory names will be
-+separated by the operating system's path separate character
-+(\fB:\fP on UNIX/Linux/POSIX,
-+\fB;\fP on Windows).
-+
-+.IP JAVAC
-+The Java compiler.
-+
-+.IP JAVACCOM
-+The command line used to compile a directory tree containing
-+Java source files to
-+corresponding Java class files.
-+Any options specified in the \fB$JAVACFLAGS\fP construction variable
-+are included on this command line.
-+
-+.IP JAVACCOMSTR
-+The string displayed when compiling
-+a directory tree of Java source files to
-+corresponding Java class files.
-+If this is not set, then \fB$JAVACCOM\fP (the command line) is displayed.
-+
-+.ES
-+env = Environment(JAVACCOMSTR = "Compiling class files $TARGETS from $SOURCES")
-+.EE
-+
-+.IP JAVACFLAGS
-+General options that are passed to the Java compiler.
-+
-+.IP JAVACLASSDIR
-+The directory in which Java class files may be found.
-+This is stripped from the beginning of any Java .class
-+file names supplied to the
-+.B JavaH
-+builder.
-+
-+.IP JAVACLASSPATH
-+Specifies the list of directories that
-+will be searched for Java
-+\fB.class\fP file.
-+The directories in this list will be added to the
-+&javac; and &javah; command lines
-+via the \fB\-classpath\fP option.
-+The individual directory names will be
-+separated by the operating system's path separate character
-+(\fB:\fP on UNIX/Linux/POSIX,
-+\fB;\fP on Windows).
-+
-+Note that this currently just adds the specified
-+directory via the \fB\-classpath\fP option.
-+&SCons; does not currently search the
-+\fB$JAVACLASSPATH\fP directories for dependency
-+\fB.class\fP files.
-+
-+.IP JAVACLASSSUFFIX
-+The suffix for Java class files;
-+.B .class
-+by default.
-+
-+.IP JAVAH
-+The Java generator for C header and stub files.
-+
-+.IP JAVAHCOM
-+The command line used to generate C header and stub files
-+from Java classes.
-+Any options specified in the \fB$JAVAHFLAGS\fP construction variable
-+are included on this command line.
-+
-+.IP JAVAHCOMSTR
-+The string displayed when C header and stub files
-+are generated from Java classes.
-+If this is not set, then \fB$JAVAHCOM\fP (the command line) is displayed.
-+
-+.ES
-+env = Environment(JAVAHCOMSTR = "Generating header/stub file(s) $TARGETS from $SOURCES")
-+.EE
-+
-+.IP JAVAHFLAGS
-+General options passed to the C header and stub file generator
-+for Java classes.
-+
-+.IP JAVASOURCEPATH
-+Specifies the list of directories that
-+will be searched for input
-+\fB.java\fP file.
-+The directories in this list will be added to the
-+&javac; command line
-+via the \fB\-sourcepath\fP option.
-+The individual directory names will be
-+separated by the operating system's path separate character
-+(\fB:\fP on UNIX/Linux/POSIX,
-+\fB;\fP on Windows).
-+
-+Note that this currently just adds the specified
-+directory via the \fB\-sourcepath\fP option.
-+&SCons; does not currently search the
-+\fB$JAVASOURCEPATH\fP directories for dependency
-+\fB.java\fP files.
-+
-+.IP JAVASUFFIX
-+The suffix for Java files;
-+.B .java
-+by default.
-+
-+.IP JAVAVERSION
-+Specifies the Java version being used by the \fBJava\fP() builder.
-+This is \fInot\fP currently used to select one
-+version of the Java compiler vs. another.
-+Instead, you should set this to specify the version of Java
-+supported by your &javac; compiler.
-+The default is \fB1.4\fP.
-+
-+This is sometimes necessary because
-+Java 1.5 changed the file names that are created
-+for nested anonymous inner classes,
-+which can cause a mismatch with the files
-+that &SCons; expects will be generated by the &javac; compiler.
-+Setting \fB$JAVAVERSION\fP to \fB1.5\fP
-+(or \fB1.6\fP, as appropriate)
-+can make &SCons; realize that a Java 1.5 or 1.6
-+build is actually up to date.
-+
-+.IP LATEX
-+The LaTeX structured formatter and typesetter.
-+
-+.IP LATEXCOM
-+The command line used to call the LaTeX structured formatter and typesetter.
-+
-+.IP LATEXCOMSTR
-+The string displayed when calling
-+the LaTeX structured formatter and typesetter.
-+If this is not set, then \fB$LATEXCOM\fP (the command line) is displayed.
-+
-+.ES
-+env = Environment(LATEXCOMSTR = "Building $TARGET from LaTeX input $SOURCES")
-+.EE
-+
-+.IP LATEXFLAGS
-+General options passed to the LaTeX structured formatter and typesetter.
-+
-+.IP LATEXRETRIES
-+The maximum number of times that LaTeX
-+will be re-run if the
-+.B .log
-+generated by the \fB$LATEXCOM\fP command
-+indicates that there are undefined references.
-+The default is to try to resolve undefined references
-+by re-running LaTeX up to three times.
-+
-+.IP LATEXSUFFIXES
-+The list of suffixes of files that will be scanned
-+for LaTeX implicit dependencies
-+(\fB\\include\fP or \fB\\import\fP files).
-+The default list is:
-+
-+.ES
-+[".tex", ".ltx", ".latex"]
-+.EE
-+
-+.IP LDMODULE
-+The linker for building loadable modules.
-+By default, this is the same as \fB$SHLINK\fP.
-+
-+.IP LDMODULECOM
-+The command line for building loadable modules.
-+On Mac OS X, this uses the \fB$LDMODULE\fP,
-+\fB$LDMODULEFLAGS\fP and
-+\fB$FRAMEWORKSFLAGS\fP variables.
-+On other systems, this is the same as \fB$SHLINK\fP.
-+
-+.IP LDMODULECOMSTR
-+The string displayed when building loadable modules.
-+If this is not set, then \fB$LDMODULECOM\fP (the command line) is displayed.
-+
-+.IP LDMODULEFLAGS
-+General user options passed to the linker for building loadable modules.
-+
-+.IP LDMODULEPREFIX
-+The prefix used for loadable module file names.
-+On Mac OS X, this is null;
-+on other systems, this is
-+the same as \fB$SHLIBPREFIX\fP.
-+
-+.IP LDMODULESUFFIX
-+The suffix used for loadable module file names.
-+On Mac OS X, this is null;
-+on other systems, this is
-+the same as $SHLIBSUFFIX.
-+
-+.IP LEX
-+The lexical analyzer generator.
-+
-+.IP LEXCOM
-+The command line used to call the lexical analyzer generator
-+to generate a source file.
-+
-+.IP LEXCOMSTR
-+The string displayed when generating a source file
-+using the lexical analyzer generator.
-+If this is not set, then \fB$LEXCOM\fP (the command line) is displayed.
-+
-+.ES
-+env = Environment(LEXCOMSTR = "Lex'ing $TARGET from $SOURCES")
-+.EE
-+
-+.IP LEXFLAGS
-+General options passed to the lexical analyzer generator.
-+
-+.IP _LIBDIRFLAGS
-+An automatically-generated construction variable
-+containing the linker command-line options
-+for specifying directories to be searched for library.
-+The value of \fB$_LIBDIRFLAGS\fP is created
-+by appending \fB$LIBDIRPREFIX\fP and \fB$LIBDIRSUFFIX\fP
-+to the beginning and end
-+of each directory in \fB$LIBPATH\fP.
-+
-+.IP LIBDIRPREFIX
-+The prefix used to specify a library directory on the linker command line.
-+This will be appended to the beginning of each directory
-+in the \fB$LIBPATH\fP construction variable
-+when the \fB$_LIBDIRFLAGS\fP variable is automatically generated.
-+
-+.IP LIBDIRSUFFIX
-+The suffix used to specify a library directory on the linker command line.
-+This will be appended to the end of each directory
-+in the \fB$LIBPATH\fP construction variable
-+when the \fB$_LIBDIRFLAGS\fP variable is automatically generated.
-+
-+.IP LIBEMITTER
-+TODO
-+
-+.IP _LIBFLAGS
-+An automatically-generated construction variable
-+containing the linker command-line options
-+for specifying libraries to be linked with the resulting target.
-+The value of \fB$_LIBFLAGS\fP is created
-+by appending \fB$LIBLINKPREFIX\fP and \fB$LIBLINKSUFFIX\fP
-+to the beginning and end
-+of each filename in \fB$LIBS\fP.
-+
-+.IP LIBLINKPREFIX
-+The prefix used to specify a library to link on the linker command line.
-+This will be appended to the beginning of each library
-+in the \fB$LIBS\fP construction variable
-+when the \fB$_LIBFLAGS\fP variable is automatically generated.
-+
-+.IP LIBLINKSUFFIX
-+The suffix used to specify a library to link on the linker command line.
-+This will be appended to the end of each library
-+in the \fB$LIBS\fP construction variable
-+when the \fB$_LIBFLAGS\fP variable is automatically generated.
-+
-+.IP LIBPATH
-+The list of directories that will be searched for libraries.
-+The implicit dependency scanner will search these
-+directories for include files. Don't explicitly put include directory
-+arguments in \fB$LINKFLAGS\fP or \fB$SHLINKFLAGS\fP
-+because the result will be non-portable
-+and the directories will not be searched by the dependency scanner. Note:
-+directory names in LIBPATH will be looked-up relative to the SConscript
-+directory when they are used in a command. To force
-+.B scons
-+to look-up a directory relative to the root of the source tree use #:
-+
-+.ES
-+env = Environment(LIBPATH='#/libs')
-+.EE
-+.IP
-+The directory look-up can also be forced using the
-+.BR Dir ()
-+function:
-+
-+.ES
-+libs = Dir('libs')
-+env = Environment(LIBPATH=libs)
-+.EE
-+.IP
-+The directory list will be added to command lines
-+through the automatically-generated
-+.B $_LIBDIRFLAGS
-+construction variable,
-+which is constructed by
-+appending the values of the
-+.BR $LIBDIRPREFIX  and  $LIBDIRSUFFIX
-+construction variables
-+to the beginning and end
-+of each directory in \fB$LIBPATH\fP.
-+Any command lines you define that need
-+the LIBPATH directory list should
-+include \fB$_LIBDIRFLAGS\fP:
-+
-+.ES
-+env = Environment(LINKCOM="my_linker $_LIBDIRFLAGS $_LIBFLAGS -o $TARGET $SOURCE")
-+.EE
-+
-+.IP LIBPREFIX
-+The prefix used for (static) library file names.
-+A default value is set for each platform
-+(posix, win32, os2, etc.),
-+but the value is overridden by individual tools
-+(ar, mslib, sgiar, sunar, tlib, etc.)
-+to reflect the names of the libraries they create.
-+
-+.IP LIBPREFIXES
-+A list of all legal prefixes for library file names.
-+When searching for library dependencies,
-+SCons will look for files with these prefixes,
-+the base library name,
-+and suffixes in the \fB$LIBSUFFIXES\fP list.
-+
-+.IP LIBS
-+A list of one or more libraries
-+that will be linked with
-+any executable programs
-+created by this environment.
-+
-+The library list will be added to command lines
-+through the automatically-generated
-+.B $_LIBFLAGS
-+construction variable,
-+which is constructed by
-+appending the values of the
-+.BR $LIBLINKPREFIX  and  $LIBLINKSUFFIX
-+construction variables
-+to the beginning and end
-+of each filename in \fB$LIBS\fP.
-+Any command lines you define that need
-+the LIBS library list should
-+include \fB$_LIBFLAGS\fP:
-+
-+.ES
-+env = Environment(LINKCOM="my_linker $_LIBDIRFLAGS $_LIBFLAGS -o $TARGET $SOURCE")
-+.EE
-+.IP
-+If you add a
-+File
-+object to the
-+.B $LIBS
-+list, the name of that file will be added to
-+.BR $_LIBFLAGS ,
-+and thus the link line, as is, without
-+.B $LIBLINKPREFIX
-+or
-+.BR $LIBLINKSUFFIX .
-+For example:
-+
-+.ES
-+env.Append(LIBS=File('/tmp/mylib.so'))
-+.EE
-+.IP
-+In all cases, scons will add dependencies from the executable program to
-+all the libraries in this list.
-+
-+.IP LIBSUFFIX
-+The suffix used for (static) library file names.
-+A default value is set for each platform
-+(posix, win32, os2, etc.),
-+but the value is overridden by individual tools
-+(ar, mslib, sgiar, sunar, tlib, etc.)
-+to reflect the names of the libraries they create.
-+
-+.IP LIBSUFFIXES
-+A list of all legal suffixes for library file names.
-+When searching for library dependencies,
-+SCons will look for files with prefixes, in the \fB$LIBPREFIXES\fP list,
-+the base library name,
-+and these suffixes.
-+
-+.IP LICENSE
-+The abbreviated name of the license under which
-+this project is released (gpl, lpgl, bsd etc.).
-+See http://www.opensource.org/licenses/alphabetical
-+for a list of license names.
-+
-+.IP LINESEPARATOR
-+The separator used by the \fBSubstfile\fP() and \fBTextfile\fP() builders.
-+This value is used between sources when constructing the target.
-+It defaults to the current system line separator.
-+
-+.IP LINGUAS_FILE
-+The \fB$LINGUAS_FILE\fP defines file(s) containing list of additional linguas
-+to be processed by \fBPOInit\fP(), \fBPOUpdate\fP() or \fBMOFiles\fP()
-+builders. It also affects \fBTranslate\fP() builder. If the variable contains
-+a string, it defines name of the list file. The \fB$LINGUAS_FILE\fP may be a
-+list of file names as well. If \fB$LINGUAS_FILE\fP is set to
-+\fBTrue\fP (or non-zero numeric value), the list will be read from
-+default file named
-+.BR LINGUAS .
-+
-+
-+.IP LINK
-+The linker.
-+
-+.IP LINKCOM
-+The command line used to link object files into an executable.
-+
-+.IP LINKCOMSTR
-+The string displayed when object files
-+are linked into an executable.
-+If this is not set, then \fB$LINKCOM\fP (the command line) is displayed.
-+
-+.ES
-+env = Environment(LINKCOMSTR = "Linking $TARGET")
-+.EE
-+
-+.IP LINKFLAGS
-+General user options passed to the linker.
-+Note that this variable should
-+.I not
-+contain
-+.B \-l
-+(or similar) options for linking with the libraries listed in \fB$LIBS\fP,
-+nor
-+.B \-L
-+(or similar) library search path options
-+that scons generates automatically from \fB$LIBPATH\fP.
-+See
-+.B $_LIBFLAGS
-+above,
-+for the variable that expands to library-link options,
-+and
-+.B $_LIBDIRFLAGS
-+above,
-+for the variable that expands to library search path options.
-+
-+.IP M4
-+The M4 macro preprocessor.
-+
-+.IP M4COM
-+The command line used to pass files through the M4 macro preprocessor.
-+
-+.IP M4COMSTR
-+The string displayed when
-+a file is passed through the M4 macro preprocessor.
-+If this is not set, then \fB$M4COM\fP (the command line) is displayed.
-+
-+.IP M4FLAGS
-+General options passed to the M4 macro preprocessor.
-+
-+.IP MAKEINDEX
-+The makeindex generator for the TeX formatter and typesetter and the
-+LaTeX structured formatter and typesetter.
-+
-+.IP MAKEINDEXCOM
-+The command line used to call the makeindex generator for the
-+TeX formatter and typesetter and the LaTeX structured formatter and
-+typesetter.
-+
-+.IP MAKEINDEXCOMSTR
-+The string displayed when calling the makeindex generator for the
-+TeX formatter and typesetter
-+and the LaTeX structured formatter and typesetter.
-+If this is not set, then \fB$MAKEINDEXCOM\fP (the command line) is displayed.
-+
-+.IP MAKEINDEXFLAGS
-+General options passed to the makeindex generator for the TeX formatter
-+and typesetter and the LaTeX structured formatter and typesetter.
-+
-+.IP MAXLINELENGTH
-+The maximum number of characters allowed on an external command line.
-+On Win32 systems,
-+link lines longer than this many characters
-+are linked via a temporary file name.
-+
-+.IP MIDL
-+The Microsoft IDL compiler.
-+
-+.IP MIDLCOM
-+The command line used to pass files to the Microsoft IDL compiler.
-+
-+.IP MIDLCOMSTR
-+The string displayed when
-+the Microsoft IDL copmiler is called.
-+If this is not set, then \fB$MIDLCOM\fP (the command line) is displayed.
-+
-+.IP MIDLFLAGS
-+General options passed to the Microsoft IDL compiler.
-+
-+.IP MOSUFFIX
-+Suffix used for \fBMO\fP files (default: \fB'.mo'\fP).
-+See &t-link-msgfmt; tool and \fBMOFiles\fP() builder.
-+
-+.IP MSGFMT
-+Absolute path to \fBmsgfmt(1)\fP binary, found by
-+.BR Detect() .
-+See &t-link-msgfmt; tool and \fBMOFiles\fP() builder.
-+
-+.IP MSGFMTCOM
-+Complete command line to run \fBmsgfmt(1)\fP program.
-+See &t-link-msgfmt; tool and \fBMOFiles\fP() builder.
-+
-+.IP MSGFMTCOMSTR
-+String to display when \fBmsgfmt(1)\fP is invoked 
-+(default: \fB''\fP, which means ``print \fB$MSGFMTCOM\fP'').
-+See &t-link-msgfmt; tool and \fBMOFiles\fP() builder.
-+
-+.IP MSGFMTFLAGS
-+Additional flags to \fBmsgfmt(1)\fP.
-+See &t-link-msgfmt; tool and \fBMOFiles\fP() builder.
-+
-+.IP MSGINIT
-+Path to \fBmsginit(1)\fP program (found via
-+.BR Detect() ).
-+See &t-link-msginit; tool and \fBPOInit\fP() builder.
-+
-+.IP MSGINITCOM
-+Complete command line to run \fBmsginit(1)\fP program.
-+See &t-link-msginit; tool and \fBPOInit\fP() builder.
-+
-+.IP MSGINITCOMSTR
-+String to display when \fBmsginit(1)\fP is invoked 
-+(default: \fB''\fP, which means ``print \fB$MSGINITCOM\fP'').
-+See &t-link-msginit; tool and \fBPOInit\fP() builder.
-+
-+.IP MSGINITFLAGS
-+List of additional flags to \fBmsginit(1)\fP (default:
-+.BR [] ).
-+See &t-link-msginit; tool and \fBPOInit\fP() builder.
-+
-+.IP _MSGINITLOCALE
-+Internal ``macro''. Computes locale (language) name based on target filename
-+(default: \fB'${TARGET.filebase}' \fP).
-+
-+.IP MSGMERGE
-+Absolute path to \fBmsgmerge(1)\fP binary as found by
-+.BR Detect() .
-+See &t-link-msgmerge; tool and \fBPOUpdate\fP() builder.
-+
-+.IP MSGMERGECOM
-+Complete command line to run \fBmsgmerge(1)\fP command.
-+See &t-link-msgmerge; tool and \fBPOUpdate\fP() builder.
-+
-+.IP MSGMERGECOMSTR
-+String to be displayed when \fBmsgmerge(1)\fP is invoked
-+(default: \fB''\fP, which means ``print \fB$MSGMERGECOM\fP'').
-+See &t-link-msgmerge; tool and \fBPOUpdate\fP() builder.
-+
-+.IP MSGMERGEFLAGS
-+Additional flags to \fBmsgmerge(1)\fP command.
-+See &t-link-msgmerge; tool and \fBPOUpdate\fP() builder.
-+
-+.IP MSSDK_DIR
-+The directory containing the Microsoft SDK
-+(either Platform SDK or Windows SDK)
-+to be used for compilation.
-+
-+.IP MSSDK_VERSION
-+The version string of the Microsoft SDK
-+(either Platform SDK or Windows SDK)
-+to be used for compilation.
-+Supported versions include
-+.BR 6.1 ,
-+.BR 6.0A ,
-+.BR 6.0 ,
-+.B 2003R2
-+and 
-+.BR 2003R1 .
-+
-+.IP MSVC_BATCH
-+When set to any true value,
-+specifies that SCons should batch
-+compilation of object files
-+when calling the Microsoft Visual C/C++ compiler.
-+All compilations of source files from the same source directory
-+that generate target files in a same output directory
-+and were configured in SCons using the same construction environment
-+will be built in a single call to the compiler.
-+Only source files that have changed since their
-+object files were built will be passed to each compiler invocation
-+(via the \fB$CHANGED_SOURCES\fP construction variable).
-+Any compilations where the object (target) file base name
-+(minus the \fB.obj\fP)
-+does not match the source file base name
-+will be compiled separately.
-+
-+.IP MSVC_USE_SCRIPT
-+Use a batch script to set up Microsoft Visual Studio compiler
-+
-+.BR $MSVC_USE_SCRIPT\fP overrides \fB$MSVC_VERSION\fP and \fB$TARGET_ARCH .
-+If set to the name of a Visual Studio .bat file (e.g. vcvars.bat),
-+SCons will run that bat file and extract the relevant variables from
-+the result (typically %INCLUDE%, %LIB%, and %PATH%).  Setting
-+MSVC_USE_SCRIPT to None bypasses the Visual Studio autodetection
-+entirely; use this if you are running SCons in a Visual Studio cmd
-+window and importing the shell's environment variables.
-+
-+.IP MSVC_VERSION
-+Sets the preferred  version of Microsoft Visual C/C++ to use.
-+
-+If \fB$MSVC_VERSION\fP is not set, SCons will (by default) select the
-+latest version of Visual C/C++ installed on your system.  If the
-+specified version isn't installed, tool initialization will fail.
-+This variable must be passed as an argument to the Environment()
-+constructor; setting it later has no effect.  Set it to an unexpected
-+value (e.g. "XXX") to see the valid values on your system.
-+
-+.IP MSVS
-+When the Microsoft Visual Studio tools are initialized, they set up
-+this dictionary with the following keys:
-+
-+.BR VERSION :
-+the version of MSVS being used (can be set via
-+.BR $MSVS_VERSION )
-+
-+.BR VERSIONS :
-+the available versions of MSVS installed
-+
-+.BR VCINSTALLDIR :
-+installed directory of Visual C++
-+
-+.BR VSINSTALLDIR :
-+installed directory of Visual Studio
-+
-+.BR FRAMEWORKDIR :
-+installed directory of the .NET framework
-+
-+.BR FRAMEWORKVERSIONS :
-+list of installed versions of the .NET framework, sorted latest to oldest.
-+
-+.BR FRAMEWORKVERSION :
-+latest installed version of the .NET framework
-+
-+.BR FRAMEWORKSDKDIR :
-+installed location of the .NET SDK.
-+
-+.BR PLATFORMSDKDIR :
-+installed location of the Platform SDK.
-+
-+.BR PLATFORMSDK_MODULES :
-+dictionary of installed Platform SDK modules,
-+where the dictionary keys are keywords for the various modules, and
-+the values are 2-tuples where the first is the release date, and the
-+second is the version number.
-+
-+If a value isn't set, it wasn't available in the registry.
-+
-+.IP MSVS_ARCH
-+Sets the architecture for which the generated project(s) should build.
-+
-+The default value is \fBx86\fP.
-+\fBamd64\fP is also supported
-+by &SCons; for some Visual Studio versions.
-+Trying to set \fB$MSVS_ARCH\fP to an architecture that's not
-+supported for a given Visual Studio version
-+will generate an error.
-+
-+.IP MSVS_PROJECT_GUID
-+The string
-+placed in a generated Microsoft Visual Studio project file
-+as the value of the
-+.B ProjectGUID
-+attribute.
-+There is no default value. If not defined, a new GUID is generated.
-+
-+.IP MSVS_SCC_AUX_PATH
-+The path name
-+placed in a generated Microsoft Visual Studio project file
-+as the value of the
-+.B SccAuxPath
-+attribute
-+if the
-+.B MSVS_SCC_PROVIDER
-+construction variable is also set.
-+There is no default value.
-+
-+.IP MSVS_SCC_CONNECTION_ROOT
-+The root path of projects in your SCC workspace, i.e the path under which
-+all project and solution files will be generated. It is used as a
-+reference path from which the relative paths of the generated
-+Microsoft Visual Studio project and solution files are computed.
-+The relative project file path is placed as the value of the
-+.B SccLocalPath
-+attribute
-+of the project file
-+and as the values of the
-+.B SccProjectFilePathRelativizedFromConnection[i]
-+(where [i] ranges from 0 to the number of projects in the solution)
-+attributes of the
-+.B GlobalSection(SourceCodeControl)
-+section of the Microsoft Visual Studio solution file.
-+Similarly the relative solution file path is placed as the values of the
-+.B SccLocalPath[i]
-+(where [i] ranges from 0 to the number of projects in the solution)
-+attributes of the
-+.B GlobalSection(SourceCodeControl)
-+section of the Microsoft Visual Studio solution file.
-+This is used only
-+if the
-+.B MSVS_SCC_PROVIDER
-+construction variable is also set.
-+The default value is the current working directory.
-+
-+.IP MSVS_SCC_PROJECT_NAME
-+The project name
-+placed in a generated Microsoft Visual Studio project file
-+as the value of the
-+.B SccProjectName
-+attribute
-+if the
-+.B MSVS_SCC_PROVIDER
-+construction variable is also set.
-+In this case the string is also placed in the
-+.B SccProjectName0
-+attribute of the
-+.B GlobalSection(SourceCodeControl)
-+section of the Microsoft Visual Studio solution file.
-+There is no default value.
-+
-+.IP MSVS_SCC_PROVIDER
-+The string
-+placed in a generated Microsoft Visual Studio project file
-+as the value of the
-+.B SccProvider
-+attribute.
-+The string is also placed in the
-+.B SccProvider0
-+attribute of the
-+.B GlobalSection(SourceCodeControl)
-+section of the Microsoft Visual Studio solution file.
-+There is no default value.
-+
-+.IP MSVS_VERSION
-+Sets the preferred version of Microsoft Visual Studio to use.
-+
-+If \fB$MSVS_VERSION\fP is not set,
-+&SCons; will (by default) select the latest version
-+of Visual Studio installed on your system.
-+So, if you have version 6 and version 7 (MSVS .NET) installed,
-+it will prefer version 7.
-+You can override this by
-+specifying the
-+.B MSVS_VERSION
-+variable in the Environment initialization, setting it to the
-+appropriate version ('6.0' or '7.0', for example).
-+If the specified version isn't installed,
-+tool initialization will fail.
-+
-+This is obsolete: use \fB$MSVC_VERSION\fP instead. If \fB$MSVS_VERSION\fP is set and
-+.BR $MSVC_VERSION\fP is not, \fB$MSVC_VERSION\fP will be set automatically to \fB$MSVS_VERSION .
-+If both are set to different values, scons will raise an error.
-+
-+.IP MSVSBUILDCOM
-+The build command line placed in
-+a generated Microsoft Visual Studio project file.
-+The default is to have Visual Studio invoke SCons with any specified
-+build targets.
-+
-+.IP MSVSCLEANCOM
-+The clean command line placed in
-+a generated Microsoft Visual Studio project file.
-+The default is to have Visual Studio invoke SCons with the -c option
-+to remove any specified targets.
-+
-+.IP MSVSENCODING
-+The encoding string placed in
-+a generated Microsoft Visual Studio project file.
-+The default is encoding
-+.BR Windows-1252 .
-+
-+.IP MSVSPROJECTCOM
-+The action used to generate Microsoft Visual Studio project files.
-+
-+.IP MSVSPROJECTSUFFIX
-+The suffix used for Microsoft Visual Studio project (DSP) files.
-+The default value is
-+.B .vcproj
-+when using Visual Studio version 7.x (.NET)
-+or later version,
-+and
-+.B .dsp
-+when using earlier versions of Visual Studio.
-+
-+.IP MSVSREBUILDCOM
-+The rebuild command line placed in
-+a generated Microsoft Visual Studio project file.
-+The default is to have Visual Studio invoke SCons with any specified
-+rebuild targets.
-+
-+.IP MSVSSCONS
-+The SCons used in generated Microsoft Visual Studio project files.
-+The default is the version of SCons being
-+used to generate the project file.
-+
-+.IP MSVSSCONSCOM
-+The default SCons command used in generated Microsoft Visual Studio
-+project files.
-+
-+.IP MSVSSCONSCRIPT
-+The sconscript file
-+(that is,
-+.B SConstruct
-+or
-+.B SConscript
-+file)
-+that will be invoked by Visual Studio
-+project files
-+(through the
-+.B $MSVSSCONSCOM
-+variable).
-+The default is the same sconscript file
-+that contains the call to
-+.BR MSVSProject ()
-+to build the project file.
-+
-+.IP MSVSSCONSFLAGS
-+The SCons flags used in generated Microsoft Visual Studio
-+project files.
-+
-+.IP MSVSSOLUTIONCOM
-+The action used to generate Microsoft Visual Studio solution files.
-+
-+.IP MSVSSOLUTIONSUFFIX
-+The suffix used for Microsoft Visual Studio solution (DSW) files.
-+The default value is
-+.B .sln
-+when using Visual Studio version 7.x (.NET),
-+and
-+.B .dsw
-+when using earlier versions of Visual Studio.
-+
-+.IP MT
-+The program used on Windows systems to embed manifests into DLLs and EXEs.
-+See also \fB$WINDOWS_EMBED_MANIFEST\fP.
-+
-+.IP MTEXECOM
-+The Windows command line used to embed manifests into executables.
-+See also \fB$MTSHLIBCOM\fP.
-+
-+.IP MTFLAGS
-+Flags passed to the \fB$MT\fP manifest embedding program (Windows only).
-+
-+.IP MTSHLIBCOM
-+The Windows command line used to embed manifests into shared libraries (DLLs).
-+See also \fB$MTEXECOM\fP.
-+
-+.IP MWCW_VERSION
-+The version number of the MetroWerks CodeWarrior C compiler
-+to be used.
-+
-+.IP MWCW_VERSIONS
-+A list of installed versions of the MetroWerks CodeWarrior C compiler
-+on this system.
-+
-+.IP NAME
-+Specfies the name of the project to package.
-+
-+.IP no_import_lib
-+When set to non-zero,
-+suppresses creation of a corresponding Windows static import lib by the
-+.B SharedLibrary
-+builder when used with
-+MinGW, Microsoft Visual Studio or Metrowerks.
-+This also suppresses creation
-+of an export (.exp) file
-+when using Microsoft Visual Studio.
-+
-+.IP OBJPREFIX
-+The prefix used for (static) object file names.
-+
-+.IP OBJSUFFIX
-+The suffix used for (static) object file names.
-+
-+.IP P4
-+The Perforce executable.
-+
-+.IP P4COM
-+The command line used to
-+fetch source files from Perforce.
-+
-+.IP P4COMSTR
-+The string displayed when
-+fetching a source file from Perforce.
-+If this is not set, then \fB$P4COM\fP (the command line) is displayed.
-+
-+.IP P4FLAGS
-+General options that are passed to Perforce.
-+
-+.IP PACKAGEROOT
-+Specifies the directory where all files in resulting archive will be
-+placed if applicable.  The default value is "$NAME-$VERSION".
-+
-+.IP PACKAGETYPE
-+Selects the package type to build.  Currently these are available:
-+
-+ * msi - Microsoft Installer
-+ * rpm - Redhat Package Manger
-+ * ipkg - Itsy Package Management System
-+ * tarbz2 - compressed tar
-+ * targz - compressed tar
-+ * zip - zip file
-+ * src_tarbz2 - compressed tar source
-+ * src_targz - compressed tar source
-+ * src_zip - zip file source
-+
-+This may be overridden with the "package_type" command line option.
-+
-+.IP PACKAGEVERSION
-+The version of the package (not the underlying project).
-+This is currently only used by the rpm packager
-+and should reflect changes in the packaging,
-+not the underlying project code itself.
-+
-+.IP PCH
-+The Microsoft Visual C++ precompiled header that will be used when compiling
-+object files. This variable is ignored by tools other than Microsoft Visual C++.
-+When this variable is
-+defined SCons will add options to the compiler command line to
-+cause it to use the precompiled header, and will also set up the
-+dependencies for the PCH file.
-+Example:
-+
-+.ES
-+env['PCH'] = 'StdAfx.pch'
-+.EE
-+
-+.IP PCHCOM
-+The command line used by the
-+.BR PCH ()
-+builder to generated a precompiled header.
-+
-+.IP PCHCOMSTR
-+The string displayed when generating a precompiled header.
-+If this is not set, then \fB$PCHCOM\fP (the command line) is displayed.
-+
-+.IP PCHPDBFLAGS
-+A construction variable that, when expanded,
-+adds the \fB/yD\fP flag to the command line
-+only if the \fB$PDB\fP construction variable is set.
-+
-+.IP PCHSTOP
-+This variable specifies how much of a source file is precompiled. This
-+variable is ignored by tools other than Microsoft Visual C++, or when
-+the PCH variable is not being used. When this variable is define it
-+must be a string that is the name of the header that
-+is included at the end of the precompiled portion of the source files, or
-+the empty string if the "#pragma hrdstop" construct is being used:
-+
-+.ES
-+env['PCHSTOP'] = 'StdAfx.h'
-+.EE
-+
-+.IP PDB
-+The Microsoft Visual C++ PDB file that will store debugging information for
-+object files, shared libraries, and programs. This variable is ignored by
-+tools other than Microsoft Visual C++.
-+When this variable is
-+defined SCons will add options to the compiler and linker command line to
-+cause them to generate external debugging information, and will also set up the
-+dependencies for the PDB file.
-+Example:
-+
-+.ES
-+env['PDB'] = 'hello.pdb'
-+.EE
-+.IP
-+The Visual C++ compiler switch that SCons uses by default
-+to generate PDB information is \fB/Z7\fP.
-+This works correctly with parallel (\fB\-j\fP) builds
-+because it embeds the debug information in the intermediate object files,
-+as opposed to sharing a single PDB file between multiple object files.
-+This is also the only way to get debug information
-+embedded into a static library.
-+Using the \fB/Zi\fP instead may yield improved
-+link-time performance,
-+although parallel builds will no longer work.
-+You can generate PDB files with the \fB/Zi\fP
-+switch by overriding the default \fB$CCPDBFLAGS\fP variable;
-+see the entry for that variable for specific examples.
-+
-+.IP PDFCOM
-+A deprecated synonym for \fB$DVIPDFCOM\fP.
-+
-+.IP PDFLATEX
-+The &pdflatex; utility.
-+
-+.IP PDFLATEXCOM
-+The command line used to call the &pdflatex; utility.
-+
-+.IP PDFLATEXCOMSTR
-+The string displayed when calling the &pdflatex; utility.
-+If this is not set, then \fB$PDFLATEXCOM\fP (the command line) is displayed.
-+
-+.ES
-+env = Environment(PDFLATEX;COMSTR = "Building $TARGET from LaTeX input $SOURCES")
-+.EE
-+
-+.IP PDFLATEXFLAGS
-+General options passed to the &pdflatex; utility.
-+
-+.IP PDFPREFIX
-+The prefix used for PDF file names.
-+
-+.IP PDFSUFFIX
-+The suffix used for PDF file names.
-+
-+.IP PDFTEX
-+The &pdftex; utility.
-+
-+.IP PDFTEXCOM
-+The command line used to call the &pdftex; utility.
-+
-+.IP PDFTEXCOMSTR
-+The string displayed when calling the &pdftex; utility.
-+If this is not set, then \fB$PDFTEXCOM\fP (the command line) is displayed.
-+
-+.ES
-+env = Environment(PDFTEXCOMSTR = "Building $TARGET from TeX input $SOURCES")
-+.EE
-+
-+.IP PDFTEXFLAGS
-+General options passed to the &pdftex; utility.
-+
-+.IP PKGCHK
-+On Solaris systems,
-+the package-checking program that will
-+be used (along with \fB$PKGINFO\fP)
-+to look for installed versions of
-+the Sun PRO C++ compiler.
-+The default is
-+.BR /usr/sbin/pgkchk .
-+
-+.IP PKGINFO
-+On Solaris systems,
-+the package information program that will
-+be used (along with \fB$PKGCHK\fP)
-+to look for installed versions of
-+the Sun PRO C++ compiler.
-+The default is
-+.BR pkginfo .
-+
-+.IP PLATFORM
-+The name of the platform used to create the Environment.  If no platform is
-+specified when the Environment is created,
-+.B scons
-+autodetects the platform.
-+
-+.ES
-+env = Environment(tools = [])
-+if env['PLATFORM'] == 'cygwin':
-+    Tool('mingw')(env)
-+else:
-+    Tool('msvc')(env)
-+.EE
-+
-+.IP POAUTOINIT
-+The \fB$POAUTOINIT\fP variable, if set to \fBTrue\fP (on non-zero
-+numeric value), let the &t-link-msginit; tool to automatically initialize
-+\fImissing\fP \fBPO\fP files with
-+\fBmsginit(1)\fP.  This applies to both,
-+\fBPOInit\fP() and \fBPOUpdate\fP() builders (and others that use any of
-+them).
-+
-+.IP POCREATE_ALIAS
-+Common alias for all \fBPO\fP files created with \fBPOInit\fP()
-+builder (default: \fB'po-create'\fP).
-+See &t-link-msginit; tool and \fBPOInit\fP() builder.
-+
-+.IP POSUFFIX
-+Suffix used for \fBPO\fP files (default: \fB'.po'\fP)
-+See &t-link-msginit; tool and \fBPOInit\fP() builder.
-+
-+.IP POTDOMAIN
-+The \fB$POTDOMAIN\fP defines default domain, used to generate
-+\fBPOT\fP filename as \fB\fB$POTDOMAIN\fP.pot\fP when
-+no \fBPOT\fP file name is provided by the user. This applies to
-+\fBPOTUpdate\fP(), \fBPOInit\fP() and \fBPOUpdate\fP() builders (and
-+builders, that use them, e.g. \fBTranslate\fP()). Normally (if \fB$POTDOMAIN\fP is
-+not defined), the builders use \fBmessages.pot\fP as default
-+\fBPOT\fP file name.
-+
-+.IP POTSUFFIX
-+Suffix used for PO Template files (default: \fB'.pot'\fP).
-+See &t-link-xgettext; tool and \fBPOTUpdate\fP() builder.
-+
-+.IP POTUPDATE_ALIAS
-+Name of the common phony target for all PO Templates created with
-+.BR POUpdate\fP() (default: \fB'pot-update' ).
-+See &t-link-xgettext; tool and \fBPOTUpdate\fP() builder.
-+
-+.IP POUPDATE_ALIAS
-+Common alias for all \fBPO\fP files being defined with
-+.BR POUpdate\fP() builder (default: \fB'po-update' ).
-+See &t-link-msgmerge; tool and \fBPOUpdate\fP() builder.
-+
-+.IP PRINT_CMD_LINE_FUNC
-+A Python function used to print the command lines as they are executed
-+(assuming command printing is not disabled by the
-+.B \-q
-+or
-+.B \-s
-+options or their equivalents).
-+The function should take four arguments:
-+.IR s ,
-+the command being executed (a string),
-+.IR target ,
-+the target being built (file node, list, or string name(s)),
-+.IR source ,
-+the source(s) used (file node, list, or string name(s)), and
-+.IR env ,
-+the environment being used.
-+
-+The function must do the printing itself.  The default implementation,
-+used if this variable is not set or is None, is:
-+.ES
-+def print_cmd_line(s, target, source, env):
-+  sys.stdout.write(s + "\\n")
-+.EE
-+.IP
-+Here's an example of a more interesting function:
-+
-+.ES
-+def print_cmd_line(s, target, source, env):
-+   sys.stdout.write("Building %s -> %s...\\n" %
-+    (' and '.join([str(x) for x in source]),
-+     ' and '.join([str(x) for x in target])))
-+env=Environment(PRINT_CMD_LINE_FUNC=print_cmd_line)
-+env.Program('foo', 'foo.c')
-+.EE
-+.IP
-+This just prints "Building \fItargetname\fP from \fIsourcename\fP..." instead
-+of the actual commands.
-+Such a function could also log the actual commands to a log file,
-+for example.
-+
-+.IP PROGEMITTER
-+TODO
-+
-+.IP PROGPREFIX
-+The prefix used for executable file names.
-+
-+.IP PROGSUFFIX
-+The suffix used for executable file names.
-+
-+.IP PSCOM
-+The command line used to convert TeX DVI files into a PostScript file.
-+
-+.IP PSCOMSTR
-+The string displayed when a TeX DVI file
-+is converted into a PostScript file.
-+If this is not set, then \fB$PSCOM\fP (the command line) is displayed.
-+
-+.IP PSPREFIX
-+The prefix used for PostScript file names.
-+
-+.IP PSSUFFIX
-+The prefix used for PostScript file names.
-+
-+.IP QT_AUTOSCAN
-+Turn off scanning for mocable files. Use the Moc Builder to explicitly
-+specify files to run moc on.
-+
-+.IP QT_BINPATH
-+The path where the qt binaries are installed.
-+The default value is '\fB$QTDIR\fP/bin'.
-+
-+.IP QT_CPPPATH
-+The path where the qt header files are installed.
-+The default value is '\fB$QTDIR\fP/include'.
-+Note: If you set this variable to None,
-+the tool won't change the \fB$CPPPATH\fP
-+construction variable.
-+
-+.IP QT_DEBUG
-+Prints lots of debugging information while scanning for moc files.
-+
-+.IP QT_LIB
-+Default value is 'qt'. You may want to set this to 'qt-mt'. Note: If you set
-+this variable to None, the tool won't change the \fB$LIBS\fP variable.
-+
-+.IP QT_LIBPATH
-+The path where the qt libraries are installed.
-+The default value is '\fB$QTDIR\fP/lib'.
-+Note: If you set this variable to None,
-+the tool won't change the \fB$LIBPATH\fP
-+construction variable.
-+
-+.IP QT_MOC
-+Default value is '\fB$QT_BINPATH\fP/moc'.
-+
-+.IP QT_MOCCXXPREFIX
-+Default value is ''. Prefix for moc output files, when source is a cxx file.
-+
-+.IP QT_MOCCXXSUFFIX
-+Default value is '.moc'. Suffix for moc output files, when source is a cxx
-+file.
-+
-+.IP QT_MOCFROMCXXCOM
-+Command to generate a moc file from a cpp file.
-+
-+.IP QT_MOCFROMCXXCOMSTR
-+The string displayed when generating a moc file from a cpp file.
-+If this is not set, then \fB$QT_MOCFROMCXXCOM\fP (the command line) is displayed.
-+
-+.IP QT_MOCFROMCXXFLAGS
-+Default value is '-i'. These flags are passed to moc, when moccing a
-+C++ file.
-+
-+.IP QT_MOCFROMHCOM
-+Command to generate a moc file from a header.
-+
-+.IP QT_MOCFROMHCOMSTR
-+The string displayed when generating a moc file from a cpp file.
-+If this is not set, then \fB$QT_MOCFROMHCOM\fP (the command line) is displayed.
-+
-+.IP QT_MOCFROMHFLAGS
-+Default value is ''. These flags are passed to moc, when moccing a header
-+file.
-+
-+.IP QT_MOCHPREFIX
-+Default value is 'moc_'. Prefix for moc output files, when source is a header.
-+
-+.IP QT_MOCHSUFFIX
-+Default value is '\fB$CXXFILESUFFIX\fP'. Suffix for moc output files, when source is
-+a header.
-+
-+.IP QT_UIC
-+Default value is '\fB$QT_BINPATH\fP/uic'.
-+
-+.IP QT_UICCOM
-+Command to generate header files from .ui files.
-+
-+.IP QT_UICCOMSTR
-+The string displayed when generating header files from .ui files.
-+If this is not set, then \fB$QT_UICCOM\fP (the command line) is displayed.
-+
-+.IP QT_UICDECLFLAGS
-+Default value is ''. These flags are passed to uic, when creating a a h
-+file from a .ui file.
-+
-+.IP QT_UICDECLPREFIX
-+Default value is ''. Prefix for uic generated header files.
-+
-+.IP QT_UICDECLSUFFIX
-+Default value is '.h'. Suffix for uic generated header files.
-+
-+.IP QT_UICIMPLFLAGS
-+Default value is ''. These flags are passed to uic, when creating a cxx
-+file from a .ui file.
-+
-+.IP QT_UICIMPLPREFIX
-+Default value is 'uic_'. Prefix for uic generated implementation files.
-+
-+.IP QT_UICIMPLSUFFIX
-+Default value is '\fB$CXXFILESUFFIX\fP'. Suffix for uic generated implementation
-+files.
-+
-+.IP QT_UISUFFIX
-+Default value is '.ui'. Suffix of designer input files.
-+
-+.IP QTDIR
-+The qt tool tries to take this from os.environ.
-+It also initializes all QT_*
-+construction variables listed below.
-+(Note that all paths are constructed
-+with python's os.path.join() method,
-+but are listed here with the '/' separator
-+for easier reading.)
-+In addition, the construction environment
-+variables \fB$CPPPATH\fP,
-+\fB$LIBPATH\fP and
-+\fB$LIBS\fP may be modified
-+and the variables
-+.BR $PROGEMITTER\fP, \fB$SHLIBEMITTER  and  $LIBEMITTER
-+are modified. Because the build-performance is affected when using this tool,
-+you have to explicitly specify it at Environment creation:
-+
-+.ES
-+Environment(tools=['default','qt'])
-+.EE
-+.IP
-+The qt tool supports the following operations:
-+
-+.I "Automatic moc file generation from header files."
-+You do not have to specify moc files explicitly, the tool does it for you.
-+However, there are a few preconditions to do so: Your header file must have
-+the same filebase as your implementation file and must stay in the same
-+directory. It must have one of the suffixes .h, .hpp, .H, .hxx, .hh. You
-+can turn off automatic moc file generation by setting QT_AUTOSCAN to 0.
-+See also the corresponding
-+.BR Moc() ()
-+builder method.
-+
-+.I "Automatic moc file generation from cxx files."
-+As stated in the qt documentation, include the moc file at the end of
-+the cxx file. Note that you have to include the file, which is generated
-+by the transformation ${QT_MOCCXXPREFIX}<basename>${QT_MOCCXXSUFFIX}, by default
-+<basename>.moc. A warning is generated after building the moc file, if you
-+do not include the correct file. If you are using VariantDir, you may
-+need to specify duplicate=1. You can turn off automatic moc file generation
-+by setting QT_AUTOSCAN to 0. See also the corresponding
-+.BR Moc ()
-+builder method.
-+
-+.I "Automatic handling of .ui files."
-+The implementation files generated from .ui files are handled much the same
-+as yacc or lex files. Each .ui file given as a source of Program, Library or
-+SharedLibrary will generate three files, the declaration file, the
-+implementation file and a moc file. Because there are also generated headers,
-+you may need to specify duplicate=1 in calls to VariantDir.
-+See also the corresponding
-+.BR Uic ()
-+builder method.
-+
-+.IP RANLIB
-+The archive indexer.
-+
-+.IP RANLIBCOM
-+The command line used to index a static library archive.
-+
-+.IP RANLIBCOMSTR
-+The string displayed when a static library archive is indexed.
-+If this is not set, then \fB$RANLIBCOM\fP (the command line) is displayed.
-+
-+.ES
-+env = Environment(RANLIBCOMSTR = "Indexing $TARGET")
-+.EE
-+
-+.IP RANLIBFLAGS
-+General options passed to the archive indexer.
-+
-+.IP RC
-+The resource compiler used to build
-+a Microsoft Visual C++ resource file.
-+
-+.IP RCCOM
-+The command line used to build
-+a Microsoft Visual C++ resource file.
-+
-+.IP RCCOMSTR
-+The string displayed when invoking the resource compiler
-+to build a Microsoft Visual C++ resource file.
-+If this is not set, then \fB$RCCOM\fP (the command line) is displayed.
-+
-+.IP RCFLAGS
-+The flags passed to the resource compiler by the RES builder.
-+
-+.IP RCINCFLAGS
-+An automatically-generated construction variable
-+containing the command-line options
-+for specifying directories to be searched
-+by the resource compiler.
-+The value of \fB$RCINCFLAGS\fP is created
-+by appending \fB$RCINCPREFIX\fP and \fB$RCINCSUFFIX\fP
-+to the beginning and end
-+of each directory in \fB$CPPPATH\fP.
-+
-+.IP RCINCPREFIX
-+The prefix (flag) used to specify an include directory
-+on the resource compiler command line.
-+This will be appended to the beginning of each directory
-+in the \fB$CPPPATH\fP construction variable
-+when the \fB$RCINCFLAGS\fP variable is expanded.
-+
-+.IP RCINCSUFFIX
-+The suffix used to specify an include directory
-+on the resource compiler command line.
-+This will be appended to the end of each directory
-+in the \fB$CPPPATH\fP construction variable
-+when the \fB$RCINCFLAGS\fP variable is expanded.
-+
-+.IP RCS
-+The RCS executable.
-+Note that this variable is not actually used
-+for the command to fetch source files from RCS;
-+see the
-+.B $RCS_CO
-+construction variable, below.
-+
-+.IP RCS_CO
-+The RCS "checkout" executable,
-+used to fetch source files from RCS.
-+
-+.IP RCS_COCOM
-+The command line used to
-+fetch (checkout) source files from RCS.
-+
-+.IP RCS_COCOMSTR
-+The string displayed when fetching
-+a source file from RCS.
-+If this is not set, then \fB$RCS_COCOM\fP
-+(the command line) is displayed.
-+
-+.IP RCS_COFLAGS
-+Options that are passed to the \fB$RCS_CO\fP command.
-+
-+.IP RDirs
-+A function that converts a string into a list of Dir instances by
-+searching the repositories.
-+
-+.IP REGSVR
-+The program used on Windows systems
-+to register a newly-built DLL library
-+whenever the \fBSharedLibrary\fP() builder
-+is passed a keyword argument of \fBregister=1\fP.
-+
-+.IP REGSVRCOM
-+The command line used on Windows systems
-+to register a newly-built DLL library
-+whenever the \fBSharedLibrary\fP() builder
-+is passed a keyword argument of \fBregister=1\fP.
-+
-+.IP REGSVRCOMSTR
-+The string displayed when registering a newly-built DLL file.
-+If this is not set, then \fB$REGSVRCOM\fP (the command line) is displayed.
-+
-+.IP REGSVRFLAGS
-+Flags passed to the DLL registration program
-+on Windows systems when a newly-built DLL library is registered.
-+By default,
-+this includes the \fB/s\fP
-+that prevents dialog boxes from popping up
-+and requiring user attention.
-+
-+.IP RMIC
-+The Java RMI stub compiler.
-+
-+.IP RMICCOM
-+The command line used to compile stub
-+and skeleton class files
-+from Java classes that contain RMI implementations.
-+Any options specified in the \fB$RMICFLAGS\fP construction variable
-+are included on this command line.
-+
-+.IP RMICCOMSTR
-+The string displayed when compiling
-+stub and skeleton class files
-+from Java classes that contain RMI implementations.
-+If this is not set, then \fB$RMICCOM\fP (the command line) is displayed.
-+
-+.ES
-+env = Environment(RMICCOMSTR = "Generating stub/skeleton class files $TARGETS from $SOURCES")
-+.EE
-+
-+.IP RMICFLAGS
-+General options passed to the Java RMI stub compiler.
-+
-+.IP _RPATH
-+An automatically-generated construction variable
-+containing the rpath flags to be used when linking
-+a program with shared libraries.
-+The value of \fB$_RPATH\fP is created
-+by appending \fB$RPATHPREFIX\fP and \fB$RPATHSUFFIX\fP
-+to the beginning and end
-+of each directory in \fB$RPATH\fP.
-+
-+.IP RPATH
-+A list of paths to search for shared libraries when running programs.
-+Currently only used in the GNU (gnulink),
-+IRIX (sgilink) and Sun (sunlink) linkers.
-+Ignored on platforms and toolchains that don't support it.
-+Note that the paths added to RPATH
-+are not transformed by
-+.B scons
-+in any way:  if you want an absolute
-+path, you must make it absolute yourself.
-+
-+.IP RPATHPREFIX
-+The prefix used to specify a directory to be searched for
-+shared libraries when running programs.
-+This will be appended to the beginning of each directory
-+in the \fB$RPATH\fP construction variable
-+when the \fB$_RPATH\fP variable is automatically generated.
-+
-+.IP RPATHSUFFIX
-+The suffix used to specify a directory to be searched for
-+shared libraries when running programs.
-+This will be appended to the end of each directory
-+in the \fB$RPATH\fP construction variable
-+when the \fB$_RPATH\fP variable is automatically generated.
-+
-+.IP RPCGEN
-+The RPC protocol compiler.
-+
-+.IP RPCGENCLIENTFLAGS
-+Options passed to the RPC protocol compiler
-+when generating client side stubs.
-+These are in addition to any flags specified in the
-+.B $RPCGENFLAGS
-+construction variable.
-+
-+.IP RPCGENFLAGS
-+General options passed to the RPC protocol compiler.
-+
-+.IP RPCGENHEADERFLAGS
-+Options passed to the RPC protocol compiler
-+when generating a header file.
-+These are in addition to any flags specified in the
-+.B $RPCGENFLAGS
-+construction variable.
-+
-+.IP RPCGENSERVICEFLAGS
-+Options passed to the RPC protocol compiler
-+when generating server side stubs.
-+These are in addition to any flags specified in the
-+.B $RPCGENFLAGS
-+construction variable.
-+
-+.IP RPCGENXDRFLAGS
-+Options passed to the RPC protocol compiler
-+when generating XDR routines.
-+These are in addition to any flags specified in the
-+.B $RPCGENFLAGS
-+construction variable.
-+
-+.IP SCANNERS
-+A list of the available implicit dependency scanners.
-+New file scanners may be added by
-+appending to this list,
-+although the more flexible approach
-+is to associate scanners
-+with a specific Builder.
-+See the sections "Builder Objects"
-+and "Scanner Objects,"
-+below, for more information.
-+
-+.IP SCCS
-+The SCCS executable.
-+
-+.IP SCCSCOM
-+The command line used to
-+fetch source files from SCCS.
-+
-+.IP SCCSCOMSTR
-+The string displayed when fetching
-+a source file from a CVS repository.
-+If this is not set, then \fB$SCCSCOM\fP
-+(the command line) is displayed.
-+
-+.IP SCCSFLAGS
-+General options that are passed to SCCS.
-+
-+.IP SCCSGETFLAGS
-+Options that are passed specifically to the SCCS "get" subcommand.
-+This can be set, for example, to
-+.B \-e
-+to check out editable files from SCCS.
-+
-+.IP SCONS_HOME
-+The (optional) path to the SCons library directory,
-+initialized from the external environment.
-+If set, this is used to construct a shorter and more
-+efficient search path in the
-+.B $MSVSSCONS
-+command line executed
-+from Microsoft Visual Studio project files.
-+
-+.IP SHCC
-+The C compiler used for generating shared-library objects.
-+
-+.IP SHCCCOM
-+The command line used to compile a C source file
-+to a shared-library object file.
-+Any options specified in the \fB$SHCFLAGS\fP,
-+\fB$SHCCFLAGS\fP and
-+\fB$CPPFLAGS\fP construction variables
-+are included on this command line.
-+
-+.IP SHCCCOMSTR
-+The string displayed when a C source file
-+is compiled to a shared object file.
-+If this is not set, then \fB$SHCCCOM\fP (the command line) is displayed.
-+
-+.ES
-+env = Environment(SHCCCOMSTR = "Compiling shared object $TARGET")
-+.EE
-+
-+.IP SHCCFLAGS
-+Options that are passed to the C and C++ compilers
-+to generate shared-library objects.
-+
-+.IP SHCFLAGS
-+Options that are passed to the C compiler (only; not C++)
-+to generate shared-library objects.
-+
-+.IP SHCXX
-+The C++ compiler used for generating shared-library objects.
-+
-+.IP SHCXXCOM
-+The command line used to compile a C++ source file
-+to a shared-library object file.
-+Any options specified in the \fB$SHCXXFLAGS\fP and
-+\fB$CPPFLAGS\fP construction variables
-+are included on this command line.
-+
-+.IP SHCXXCOMSTR
-+The string displayed when a C++ source file
-+is compiled to a shared object file.
-+If this is not set, then \fB$SHCXXCOM\fP (the command line) is displayed.
-+
-+.ES
-+env = Environment(SHCXXCOMSTR = "Compiling shared object $TARGET")
-+.EE
-+
-+.IP SHCXXFLAGS
-+Options that are passed to the C++ compiler
-+to generate shared-library objects.
-+
-+.IP SHELL
-+A string naming the shell program that will be passed to the
-+.B $SPAWN
-+function.
-+See the
-+.B $SPAWN
-+construction variable for more information.
-+
-+.IP SHF77
-+The Fortran 77 compiler used for generating shared-library objects.
-+You should normally set the \fB$SHFORTRAN\fP variable,
-+which specifies the default Fortran compiler
-+for all Fortran versions.
-+You only need to set \fB$SHF77\fP if you need to use a specific compiler
-+or compiler version for Fortran 77 files.
-+
-+.IP SHF77COM
-+The command line used to compile a Fortran 77 source file
-+to a shared-library object file.
-+You only need to set \fB$SHF77COM\fP if you need to use a specific
-+command line for Fortran 77 files.
-+You should normally set the \fB$SHFORTRANCOM\fP variable,
-+which specifies the default command line
-+for all Fortran versions.
-+
-+.IP SHF77COMSTR
-+The string displayed when a Fortran 77 source file
-+is compiled to a shared-library object file.
-+If this is not set, then \fB$SHF77COM\fP or \fB$SHFORTRANCOM\fP
-+(the command line) is displayed.
-+
-+.IP SHF77FLAGS
-+Options that are passed to the Fortran 77 compiler
-+to generated shared-library objects.
-+You only need to set \fB$SHF77FLAGS\fP if you need to define specific
-+user options for Fortran 77 files.
-+You should normally set the \fB$SHFORTRANFLAGS\fP variable,
-+which specifies the user-specified options
-+passed to the default Fortran compiler
-+for all Fortran versions.
-+
-+.IP SHF77PPCOM
-+The command line used to compile a Fortran 77 source file to a
-+shared-library object file
-+after first running the file through the C preprocessor.
-+Any options specified in the \fB$SHF77FLAGS\fP and \fB$CPPFLAGS\fP construction variables
-+are included on this command line.
-+You only need to set \fB$SHF77PPCOM\fP if you need to use a specific
-+C-preprocessor command line for Fortran 77 files.
-+You should normally set the \fB$SHFORTRANPPCOM\fP variable,
-+which specifies the default C-preprocessor command line
-+for all Fortran versions.
-+
-+.IP SHF77PPCOMSTR
-+The string displayed when a Fortran 77 source file
-+is compiled to a shared-library object file
-+after first running the file through the C preprocessor.
-+If this is not set, then \fB$SHF77PPCOM\fP or \fB$SHFORTRANPPCOM\fP
-+(the command line) is displayed.
-+
-+.IP SHF90
-+The Fortran 90 compiler used for generating shared-library objects.
-+You should normally set the \fB$SHFORTRAN\fP variable,
-+which specifies the default Fortran compiler
-+for all Fortran versions.
-+You only need to set \fB$SHF90\fP if you need to use a specific compiler
-+or compiler version for Fortran 90 files.
-+
-+.IP SHF90COM
-+The command line used to compile a Fortran 90 source file
-+to a shared-library object file.
-+You only need to set \fB$SHF90COM\fP if you need to use a specific
-+command line for Fortran 90 files.
-+You should normally set the \fB$SHFORTRANCOM\fP variable,
-+which specifies the default command line
-+for all Fortran versions.
-+
-+.IP SHF90COMSTR
-+The string displayed when a Fortran 90 source file
-+is compiled to a shared-library object file.
-+If this is not set, then \fB$SHF90COM\fP or \fB$SHFORTRANCOM\fP
-+(the command line) is displayed.
-+
-+.IP SHF90FLAGS
-+Options that are passed to the Fortran 90 compiler
-+to generated shared-library objects.
-+You only need to set \fB$SHF90FLAGS\fP if you need to define specific
-+user options for Fortran 90 files.
-+You should normally set the \fB$SHFORTRANFLAGS\fP variable,
-+which specifies the user-specified options
-+passed to the default Fortran compiler
-+for all Fortran versions.
-+
-+.IP SHF90PPCOM
-+The command line used to compile a Fortran 90 source file to a
-+shared-library object file
-+after first running the file through the C preprocessor.
-+Any options specified in the \fB$SHF90FLAGS\fP and \fB$CPPFLAGS\fP construction variables
-+are included on this command line.
-+You only need to set \fB$SHF90PPCOM\fP if you need to use a specific
-+C-preprocessor command line for Fortran 90 files.
-+You should normally set the \fB$SHFORTRANPPCOM\fP variable,
-+which specifies the default C-preprocessor command line
-+for all Fortran versions.
-+
-+.IP SHF90PPCOMSTR
-+The string displayed when a Fortran 90 source file
-+is compiled to a shared-library object file
-+after first running the file through the C preprocessor.
-+If this is not set, then \fB$SHF90PPCOM\fP or \fB$SHFORTRANPPCOM\fP
-+(the command line) is displayed.
-+
-+.IP SHF95
-+The Fortran 95 compiler used for generating shared-library objects.
-+You should normally set the \fB$SHFORTRAN\fP variable,
-+which specifies the default Fortran compiler
-+for all Fortran versions.
-+You only need to set \fB$SHF95\fP if you need to use a specific compiler
-+or compiler version for Fortran 95 files.
-+
-+.IP SHF95COM
-+The command line used to compile a Fortran 95 source file
-+to a shared-library object file.
-+You only need to set \fB$SHF95COM\fP if you need to use a specific
-+command line for Fortran 95 files.
-+You should normally set the \fB$SHFORTRANCOM\fP variable,
-+which specifies the default command line
-+for all Fortran versions.
-+
-+.IP SHF95COMSTR
-+The string displayed when a Fortran 95 source file
-+is compiled to a shared-library object file.
-+If this is not set, then \fB$SHF95COM\fP or \fB$SHFORTRANCOM\fP
-+(the command line) is displayed.
-+
-+.IP SHF95FLAGS
-+Options that are passed to the Fortran 95 compiler
-+to generated shared-library objects.
-+You only need to set \fB$SHF95FLAGS\fP if you need to define specific
-+user options for Fortran 95 files.
-+You should normally set the \fB$SHFORTRANFLAGS\fP variable,
-+which specifies the user-specified options
-+passed to the default Fortran compiler
-+for all Fortran versions.
-+
-+.IP SHF95PPCOM
-+The command line used to compile a Fortran 95 source file to a
-+shared-library object file
-+after first running the file through the C preprocessor.
-+Any options specified in the \fB$SHF95FLAGS\fP and \fB$CPPFLAGS\fP construction variables
-+are included on this command line.
-+You only need to set \fB$SHF95PPCOM\fP if you need to use a specific
-+C-preprocessor command line for Fortran 95 files.
-+You should normally set the \fB$SHFORTRANPPCOM\fP variable,
-+which specifies the default C-preprocessor command line
-+for all Fortran versions.
-+
-+.IP SHF95PPCOMSTR
-+The string displayed when a Fortran 95 source file
-+is compiled to a shared-library object file
-+after first running the file through the C preprocessor.
-+If this is not set, then \fB$SHF95PPCOM\fP or \fB$SHFORTRANPPCOM\fP
-+(the command line) is displayed.
-+
-+.IP SHFORTRAN
-+The default Fortran compiler used for generating shared-library objects.
-+
-+.IP SHFORTRANCOM
-+The command line used to compile a Fortran source file
-+to a shared-library object file.
-+
-+.IP SHFORTRANCOMSTR
-+The string displayed when a Fortran source file
-+is compiled to a shared-library object file.
-+If this is not set, then \fB$SHFORTRANCOM\fP
-+(the command line) is displayed.
-+
-+.IP SHFORTRANFLAGS
-+Options that are passed to the Fortran compiler
-+to generate shared-library objects.
-+
-+.IP SHFORTRANPPCOM
-+The command line used to compile a Fortran source file to a
-+shared-library object file
-+after first running the file through the C preprocessor.
-+Any options specified
-+in the \fB$SHFORTRANFLAGS\fP and
-+\fB$CPPFLAGS\fP construction variables
-+are included on this command line.
-+
-+.IP SHFORTRANPPCOMSTR
-+The string displayed when a Fortran source file
-+is compiled to a shared-library object file
-+after first running the file through the C preprocessor.
-+If this is not set, then \fB$SHFORTRANPPCOM\fP
-+(the command line) is displayed.
-+
-+.IP SHLIBEMITTER
-+TODO
-+
-+.IP SHLIBPREFIX
-+The prefix used for shared library file names.
-+
-+.IP SHLIBSUFFIX
-+The suffix used for shared library file names.
-+
-+.IP SHLIBVERSION
-+When this construction variable is defined, a versioned shared library
-+is created. This modifies the \fB$SHLINKFLAGS\fP as required, adds
-+the version number to the library name, and creates the symlinks that
-+are needed. \fB$SHLIBVERSION\fP needs to be of the form X.Y.Z,
-+where X and Y are numbers, and Z is a number but can also contain
-+letters to designate alpha, beta, or release candidate patch levels.
-+
-+.IP SHLINK
-+The linker for programs that use shared libraries.
-+
-+.IP SHLINKCOM
-+The command line used to link programs using shared libraries.
-+
-+.IP SHLINKCOMSTR
-+The string displayed when programs using shared libraries are linked.
-+If this is not set, then \fB$SHLINKCOM\fP (the command line) is displayed.
-+
-+.ES
-+env = Environment(SHLINKCOMSTR = "Linking shared $TARGET")
-+.EE
-+
-+.IP SHLINKFLAGS
-+General user options passed to the linker for programs using shared libraries.
-+Note that this variable should
-+.I not
-+contain
-+.B \-l
-+(or similar) options for linking with the libraries listed in \fB$LIBS\fP,
-+nor
-+.B \-L
-+(or similar) include search path options
-+that scons generates automatically from \fB$LIBPATH\fP.
-+See
-+.B $_LIBFLAGS
-+above,
-+for the variable that expands to library-link options,
-+and
-+.B $_LIBDIRFLAGS
-+above,
-+for the variable that expands to library search path options.
-+
-+.IP SHOBJPREFIX
-+The prefix used for shared object file names.
-+
-+.IP SHOBJSUFFIX
-+The suffix used for shared object file names.
-+
-+.IP SOURCE
-+A reserved variable name
-+that may not be set or used in a construction environment.
-+(See "Variable Substitution," below.)
-+
-+.IP SOURCE_URL
-+The URL
-+(web address)
-+of the location from which the project was retrieved.
-+This is used to fill in the
-+.B Source:
-+field in the controlling information for Ipkg and RPM packages.
-+
-+.IP SOURCES
-+A reserved variable name
-+that may not be set or used in a construction environment.
-+(See "Variable Substitution," below.)
-+
-+.IP SPAWN
-+A command interpreter function that will be called to execute command line
-+strings. The function must expect the following arguments:
-+
-+.ES
-+def spawn(shell, escape, cmd, args, env):
-+.EE
-+.IP
-+.I sh
-+is a string naming the shell program to use.
-+.I escape
-+is a function that can be called to escape shell special characters in
-+the command line.
-+.I cmd
-+is the path to the command to be executed.
-+.I args
-+is the arguments to the command.
-+.I env
-+is a dictionary of the environment variables
-+in which the command should be executed.
-+
-+.IP SUBST_DICT
-+The dictionary used by the \fBSubstfile\fP() or \fBTextfile\fP() builders
-+for substitution values.
-+It can be anything acceptable to the dict() constructor,
-+so in addition to a dictionary,
-+lists of tuples are also acceptable.
-+
-+.IP SUBSTFILEPREFIX
-+The prefix used for \fBSubstfile\fP() file names,
-+the null string by default.
-+
-+.IP SUBSTFILESUFFIX
-+The suffix used for \fBSubstfile\fP() file names,
-+the null string by default.
-+
-+.IP SUMMARY
-+A short summary of what the project is about.
-+This is used to fill in the
-+.B Summary:
-+field in the controlling information for Ipkg and RPM packages,
-+and as the
-+.B Description:
-+field in MSI packages.
-+
-+.IP SWIG
-+The scripting language wrapper and interface generator.
-+
-+.IP SWIGCFILESUFFIX
-+The suffix that will be used for intermediate C
-+source files generated by
-+the scripting language wrapper and interface generator.
-+The default value is
-+.BR _wrap\fP\fB$CFILESUFFIX .
-+By default, this value is used whenever the
-+.B \-c++
-+option is
-+.I not
-+specified as part of the
-+.B $SWIGFLAGS
-+construction variable.
-+
-+.IP SWIGCOM
-+The command line used to call
-+the scripting language wrapper and interface generator.
-+
-+.IP SWIGCOMSTR
-+The string displayed when calling
-+the scripting language wrapper and interface generator.
-+If this is not set, then \fB$SWIGCOM\fP (the command line) is displayed.
-+
-+.IP SWIGCXXFILESUFFIX
-+The suffix that will be used for intermediate C++
-+source files generated by
-+the scripting language wrapper and interface generator.
-+The default value is
-+.BR _wrap\fP\fB$CFILESUFFIX .
-+By default, this value is used whenever the
-+.B \-c++
-+option is specified as part of the
-+.B $SWIGFLAGS
-+construction variable.
-+
-+.IP SWIGDIRECTORSUFFIX
-+The suffix that will be used for intermediate C++ header
-+files generated by the scripting language wrapper and interface generator.
-+These are only generated for C++ code when the SWIG 'directors' feature is
-+turned on.
-+The default value is
-+.BR _wrap.h .
-+
-+.IP SWIGFLAGS
-+General options passed to
-+the scripting language wrapper and interface generator.
-+This is where you should set
-+.BR \-python ,
-+.BR \-perl5 ,
-+.BR \-tcl ,
-+or whatever other options you want to specify to SWIG.
-+If you set the
-+.B \-c++
-+option in this variable,
-+.B scons
-+will, by default,
-+generate a C++ intermediate source file
-+with the extension that is specified as the
-+.B $CXXFILESUFFIX
-+variable.
-+
-+.IP _SWIGINCFLAGS
-+An automatically-generated construction variable
-+containing the SWIG command-line options
-+for specifying directories to be searched for included files.
-+The value of \fB$_SWIGINCFLAGS\fP is created
-+by appending \fB$SWIGINCPREFIX\fP and \fB$SWIGINCSUFFIX\fP
-+to the beginning and end
-+of each directory in \fB$SWIGPATH\fP.
-+
-+.IP SWIGINCPREFIX
-+The prefix used to specify an include directory on the SWIG command line.
-+This will be appended to the beginning of each directory
-+in the \fB$SWIGPATH\fP construction variable
-+when the \fB$_SWIGINCFLAGS\fP variable is automatically generated.
-+
-+.IP SWIGINCSUFFIX
-+The suffix used to specify an include directory on the SWIG command line.
-+This will be appended to the end of each directory
-+in the \fB$SWIGPATH\fP construction variable
-+when the \fB$_SWIGINCFLAGS\fP variable is automatically generated.
-+
-+.IP SWIGOUTDIR
-+Specifies the output directory in which
-+the scripting language wrapper and interface generator
-+should place generated language-specific files.
-+This will be used by SCons to identify
-+the files that will be generated by the &swig; call,
-+and translated into the
-+\fBswig -outdir\fP option on the command line.
-+
-+.IP SWIGPATH
-+The list of directories that the scripting language wrapper
-+and interface generate will search for included files.
-+The SWIG implicit dependency scanner will search these
-+directories for include files.
-+The default is to use the same path
-+specified as \fB$CPPPATH\fP.
-+
-+Don't explicitly put include directory
-+arguments in SWIGFLAGS;
-+the result will be non-portable
-+and the directories will not be searched by the dependency scanner.
-+Note: directory names in SWIGPATH will be looked-up relative to the SConscript
-+directory when they are used in a command.
-+To force
-+.B scons
-+to look-up a directory relative to the root of the source tree use #:
-+
-+.ES
-+env = Environment(SWIGPATH='#/include')
-+.EE
-+.IP
-+The directory look-up can also be forced using the
-+.BR Dir ()
-+function:
-+
-+.ES
-+include = Dir('include')
-+env = Environment(SWIGPATH=include)
-+.EE
-+.IP
-+The directory list will be added to command lines
-+through the automatically-generated
-+.B $_SWIGINCFLAGS
-+construction variable,
-+which is constructed by
-+appending the values of the
-+.BR $SWIGINCPREFIX  and  $SWIGINCSUFFIX
-+construction variables
-+to the beginning and end
-+of each directory in \fB$SWIGPATH\fP.
-+Any command lines you define that need
-+the SWIGPATH directory list should
-+include \fB$_SWIGINCFLAGS\fP:
-+
-+.ES
-+env = Environment(SWIGCOM="my_swig -o $TARGET $_SWIGINCFLAGS $SORUCES")
-+.EE
-+
-+.IP SWIGVERSION
-+The version number of the SWIG tool.
-+
-+.IP TAR
-+The tar archiver.
-+
-+.IP TARCOM
-+The command line used to call the tar archiver.
-+
-+.IP TARCOMSTR
-+The string displayed when archiving files
-+using the tar archiver.
-+If this is not set, then \fB$TARCOM\fP (the command line) is displayed.
-+
-+.ES
-+env = Environment(TARCOMSTR = "Archiving $TARGET")
-+.EE
-+
-+.IP TARFLAGS
-+General options passed to the tar archiver.
-+
-+.IP TARGET
-+A reserved variable name
-+that may not be set or used in a construction environment.
-+(See "Variable Substitution," below.)
-+
-+.IP TARGET_ARCH
-+Sets the target architecture for Visual Studio compiler (i.e. the arch
-+of the binaries generated by the compiler). If not set, default to
-+\fB$HOST_ARCH\fP, or, if that is unset, to the architecture of the
-+running machine's OS (note that the python build or architecture has no
-+effect).
-+This variable must be passed as an argument to the Environment()
-+constructor; setting it later has no effect.  
-+This is currently only used on Windows, but in the future it will be
-+used on other OSes as well.
-+
-+Valid values for Windows are
-+.BR x86 ,
-+.B i386
-+(for 32 bits); 
-+.BR amd64 ,
-+.BR emt64 ,
-+.B x86_64
-+(for 64 bits);
-+and \fBia64\fP (Itanium).
-+For example, if you want to compile 64-bit binaries, you would set
-+\fBTARGET_ARCH='x86_64'\fP in your SCons environment.
-+
-+.IP TARGET_OS
-+        The name of the target operating system for the compiled objects
-+        created by this Environment.
-+        This defaults to the value of HOST_OS, and the user can override it.
-+        Currently only set for Win32.
-+    
-+.IP TARGETS
-+A reserved variable name
-+that may not be set or used in a construction environment.
-+(See "Variable Substitution," below.)
-+
-+.IP TARSUFFIX
-+The suffix used for tar file names.
-+
-+.IP TEMPFILEPREFIX
-+The prefix for a temporary file used
-+to execute lines longer than $MAXLINELENGTH.
-+The default is '@'.
-+This may be set for toolchains that use other values,
-+such as '-@' for the diab compiler
-+or '-via' for ARM toolchain.
-+
-+.IP TEX
-+The TeX formatter and typesetter.
-+
-+.IP TEXCOM
-+The command line used to call the TeX formatter and typesetter.
-+
-+.IP TEXCOMSTR
-+The string displayed when calling
-+the TeX formatter and typesetter.
-+If this is not set, then \fB$TEXCOM\fP (the command line) is displayed.
-+
-+.ES
-+env = Environment(TEXCOMSTR = "Building $TARGET from TeX input $SOURCES")
-+.EE
-+
-+.IP TEXFLAGS
-+General options passed to the TeX formatter and typesetter.
-+
-+.IP TEXINPUTS
-+List of directories that the LaTeX program will search
-+for include directories.
-+The LaTeX implicit dependency scanner will search these
-+directories for \\include and \\import files.
-+
-+.IP TEXTFILEPREFIX
-+The prefix used for \fBTextfile\fP() file names,
-+the null string by default.
-+
-+.IP TEXTFILESUFFIX
-+The suffix used for \fBTextfile\fP() file names;
-+\fB.txt\fP by default.
-+
-+.IP TOOLS
-+A list of the names of the Tool specifications
-+that are part of this construction environment.
-+
-+.IP UNCHANGED_SOURCES
-+A reserved variable name
-+that may not be set or used in a construction environment.
-+(See "Variable Substitution," below.)
-+
-+.IP UNCHANGED_TARGETS
-+A reserved variable name
-+that may not be set or used in a construction environment.
-+(See "Variable Substitution," below.)
-+
-+.IP VENDOR
-+The person or organization who supply the packaged software.
-+This is used to fill in the
-+.B Vendor:
-+field in the controlling information for RPM packages,
-+and the
-+.B Manufacturer:
-+field in the controlling information for MSI packages.
-+
-+.IP VERSION
-+The version of the project, specified as a string.
-+
-+.IP WIN32_INSERT_DEF
-+A deprecated synonym for \fB$WINDOWS_INSERT_DEF\fP.
-+
-+.IP WIN32DEFPREFIX
-+A deprecated synonym for \fB$WINDOWSDEFPREFIX\fP.
-+
-+.IP WIN32DEFSUFFIX
-+A deprecated synonym for \fB$WINDOWSDEFSUFFIX\fP.
-+
-+.IP WIN32EXPPREFIX
-+A deprecated synonym for \fB$WINDOWSEXPSUFFIX\fP.
-+
-+.IP WIN32EXPSUFFIX
-+A deprecated synonym for \fB$WINDOWSEXPSUFFIX\fP.
-+
-+.IP WINDOWS_EMBED_MANIFEST
-+Set this variable to True or 1 to embed the compiler-generated manifest
-+(normally \fB${TARGET}.manifest\fP)
-+into all Windows exes and DLLs built with this environment,
-+as a resource during their link step.
-+This is done using \fB$MT\fP and \fB$MTEXECOM\fP and \fB$MTSHLIBCOM\fP.
-+
-+.IP WINDOWS_INSERT_DEF
-+When this is set to true,
-+a library build of a Windows shared library
-+(\fB.dll\fP file)
-+will also build a corresponding \fB.def\fP file
-+at the same time,
-+if a \fB.def\fP file
-+is not already listed as a build target.
-+The default is 0 (do not build a \fB.def\fP file).
-+
-+.IP WINDOWS_INSERT_MANIFEST
-+When this is set to true,
-+.B scons
-+will be aware of the
-+.B .manifest
-+files generated by Microsoft Visua C/C++ 8.
-+
-+.IP WINDOWSDEFPREFIX
-+The prefix used for Windows \fB.def\fP file names.
-+
-+.IP WINDOWSDEFSUFFIX
-+The suffix used for Windows \fB.def\fP file names.
-+
-+.IP WINDOWSEXPPREFIX
-+The prefix used for Windows \fB.exp\fP file names.
-+
-+.IP WINDOWSEXPSUFFIX
-+The suffix used for Windows \fB.exp\fP file names.
-+
-+.IP WINDOWSPROGMANIFESTPREFIX
-+The prefix used for executable program \fB.manifest\fP files
-+generated by Microsoft Visual C/C++.
-+
-+.IP WINDOWSPROGMANIFESTSUFFIX
-+The suffix used for executable program \fB.manifest\fP files
-+generated by Microsoft Visual C/C++.
-+
-+.IP WINDOWSSHLIBMANIFESTPREFIX
-+The prefix used for shared library \fB.manifest\fP files
-+generated by Microsoft Visual C/C++.
-+
-+.IP WINDOWSSHLIBMANIFESTSUFFIX
-+The suffix used for shared library \fB.manifest\fP files
-+generated by Microsoft Visual C/C++.
-+
-+.IP X_IPK_DEPENDS
-+This is used to fill in the
-+.B Depends:
-+field in the controlling information for Ipkg packages.
-+
-+.IP X_IPK_DESCRIPTION
-+This is used to fill in the
-+.B Description:
-+field in the controlling information for Ipkg packages.
-+The default value is
-+.B "$SUMMARY\\n$DESCRIPTION"
-+.IP X_IPK_MAINTAINER
-+This is used to fill in the
-+.B Maintainer:
-+field in the controlling information for Ipkg packages.
-+
-+.IP X_IPK_PRIORITY
-+This is used to fill in the
-+.B Priority:
-+field in the controlling information for Ipkg packages.
-+
-+.IP X_IPK_SECTION
-+This is used to fill in the
-+.B Section:
-+field in the controlling information for Ipkg packages.
-+
-+.IP X_MSI_LANGUAGE
-+This is used to fill in the
-+.B Language:
-+attribute in the controlling information for MSI packages.
-+
-+.IP X_MSI_LICENSE_TEXT
-+The text of the software license in RTF format.
-+Carriage return characters will be
-+replaced with the RTF equivalent \\\\par.
-+
-+.IP X_MSI_UPGRADE_CODE
-+TODO
-+
-+.IP X_RPM_AUTOREQPROV
-+This is used to fill in the
-+.B AutoReqProv:
-+field in the RPM
-+\fB.spec\fP file.
-+
-+.IP X_RPM_BUILD
-+internal, but overridable
-+
-+.IP X_RPM_BUILDREQUIRES
-+This is used to fill in the
-+.B BuildRequires:
-+field in the RPM
-+\fB.spec\fP file.
-+
-+.IP X_RPM_BUILDROOT
-+internal, but overridable
-+
-+.IP X_RPM_CLEAN
-+internal, but overridable
-+
-+.IP X_RPM_CONFLICTS
-+This is used to fill in the
-+.B Conflicts:
-+field in the RPM
-+\fB.spec\fP file.
-+
-+.IP X_RPM_DEFATTR
-+This value is used as the default attributes
-+for the files in the RPM package.
-+The default value is
-+.BR (-,root,root) .
-+
-+.IP X_RPM_DISTRIBUTION
-+This is used to fill in the
-+.B Distribution:
-+field in the RPM
-+\fB.spec\fP file.
-+
-+.IP X_RPM_EPOCH
-+This is used to fill in the
-+.B Epoch:
-+field in the controlling information for RPM packages.
-+
-+.IP X_RPM_EXCLUDEARCH
-+This is used to fill in the
-+.B ExcludeArch:
-+field in the RPM
-+\fB.spec\fP file.
-+
-+.IP X_RPM_EXLUSIVEARCH
-+This is used to fill in the
-+.B ExclusiveArch:
-+field in the RPM
-+\fB.spec\fP file.
-+
-+.IP X_RPM_GROUP
-+This is used to fill in the
-+.B Group:
-+field in the RPM
-+\fB.spec\fP file.
-+
-+.IP X_RPM_GROUP_lang
-+This is used to fill in the
-+.B Group(lang):
-+field in the RPM
-+\fB.spec\fP file.
-+Note that
-+.I lang
-+is not literal
-+and should be replaced by
-+the appropriate language code.
-+
-+.IP X_RPM_ICON
-+This is used to fill in the
-+.B Icon:
-+field in the RPM
-+\fB.spec\fP file.
-+
-+.IP X_RPM_INSTALL
-+internal, but overridable
-+
-+.IP X_RPM_PACKAGER
-+This is used to fill in the
-+.B Packager:
-+field in the RPM
-+\fB.spec\fP file.
-+
-+.IP X_RPM_POSTINSTALL
-+This is used to fill in the
-+.B %post:
-+section in the RPM
-+\fB.spec\fP file.
-+
-+.IP X_RPM_POSTUNINSTALL
-+This is used to fill in the
-+.B %postun:
-+section in the RPM
-+\fB.spec\fP file.
-+
-+.IP X_RPM_PREFIX
-+This is used to fill in the
-+.B Prefix:
-+field in the RPM
-+\fB.spec\fP file.
-+
-+.IP X_RPM_PREINSTALL
-+This is used to fill in the
-+.B %pre:
-+section in the RPM
-+\fB.spec\fP file.
-+
-+.IP X_RPM_PREP
-+internal, but overridable
-+
-+.IP X_RPM_PREUNINSTALL
-+This is used to fill in the
-+.B %preun:
-+section in the RPM
-+\fB.spec\fP file.
-+
-+.IP X_RPM_PROVIDES
-+This is used to fill in the
-+.B Provides:
-+field in the RPM
-+\fB.spec\fP file.
-+
-+.IP X_RPM_REQUIRES
-+This is used to fill in the
-+.B Requires:
-+field in the RPM
-+\fB.spec\fP file.
-+
-+.IP X_RPM_SERIAL
-+This is used to fill in the
-+.B Serial:
-+field in the RPM
-+\fB.spec\fP file.
-+
-+.IP X_RPM_URL
-+This is used to fill in the
-+.B Url:
-+field in the RPM
-+\fB.spec\fP file.
-+
-+.IP XGETTEXT
-+Path to \fBxgettext(1)\fP program (found via
-+.BR Detect() ).
-+See &t-link-xgettext; tool and \fBPOTUpdate\fP() builder.
-+
-+.IP XGETTEXTCOM
-+Complete xgettext command line.
-+See &t-link-xgettext; tool and \fBPOTUpdate\fP() builder.
-+
-+.IP XGETTEXTCOMSTR
-+A string that is shown when \fBxgettext(1)\fP command is invoked
-+(default: \fB''\fP, which means "print \fB$XGETTEXTCOM\fP").
-+See &t-link-xgettext; tool and \fBPOTUpdate\fP() builder.
-+
-+.IP _XGETTEXTDOMAIN
-+Internal "macro". Generates \fBxgettext\fP domain name
-+form source and target (default: \fB'${TARGET.filebase}'\fP).
-+
-+.IP XGETTEXTFLAGS
-+Additional flags to \fBxgettext(1)\fP.
-+See &t-link-xgettext; tool and \fBPOTUpdate\fP() builder.
-+
-+.IP XGETTEXTFROM
-+Name of file containing list of \fBxgettext(1)\fP's source
-+files. Autotools' users know this as \fBPOTFILES.in\fP so they
-+will in most cases set \fBXGETTEXTFROM="POTFILES.in"\fP here.
-+The \fB$XGETTEXTFROM\fP files have same syntax and semantics as the well known
-+GNU \fBPOTFILES.in\fP.
-+See &t-link-xgettext; tool and \fBPOTUpdate\fP() builder.
-+
-+.IP _XGETTEXTFROMFLAGS
-+Internal "macro". Genrates list of \fB\-D<dir>\fP flags
-+from the \fB$XGETTEXTPATH\fP list.
-+
-+.IP XGETTEXTFROMPREFIX
-+This flag is used to add single \fB$XGETTEXTFROM\fP file to
-+\fBxgettext(1)\fP's commandline (default:
-+.BR '-f' ).
-+
-+.IP XGETTEXTFROMSUFFIX
-+(default: \fB''\fP)
-+
-+.IP XGETTEXTPATH
-+List of directories, there \fBxgettext(1)\fP will look for
-+source files (default: \fB[]\fP).
-+<note>This variable works only together with \fB$XGETTEXTFROM\fP
-+</para></note>
-+See also &t-link-xgettext; tool and \fBPOTUpdate\fP() builder.
-+
-+.IP _XGETTEXTPATHFLAGS
-+Internal "macro". Generates list of \fB\-f<file>\fP flags
-+from \fB$XGETTEXTFROM\fP.
-+
-+.IP XGETTEXTPATHPREFIX
-+This flag is used to add single search path to
-+\fBxgettext(1)\fP's commandline (default:
-+.BR '-D' ).
-+
-+.IP XGETTEXTPATHSUFFIX
-+(default: \fB''\fP)
-+
-+.IP YACC
-+The parser generator.
-+
-+.IP YACCCOM
-+The command line used to call the parser generator
-+to generate a source file.
-+
-+.IP YACCCOMSTR
-+The string displayed when generating a source file
-+using the parser generator.
-+If this is not set, then \fB$YACCCOM\fP (the command line) is displayed.
-+
-+.ES
-+env = Environment(YACCCOMSTR = "Yacc'ing $TARGET from $SOURCES")
-+.EE
-+
-+.IP YACCFLAGS
-+General options passed to the parser generator.
-+If \fB$YACCFLAGS\fP contains a \fB\-d\fP option,
-+SCons assumes that the call will also create a .h file
-+(if the yacc source file ends in a .y suffix)
-+or a .hpp file
-+(if the yacc source file ends in a .yy suffix)
-+
-+.IP YACCHFILESUFFIX
-+The suffix of the C
-+header file generated by the parser generator
-+when the
-+.B \-d
-+option is used.
-+Note that setting this variable does not cause
-+the parser generator to generate a header
-+file with the specified suffix,
-+it exists to allow you to specify
-+what suffix the parser generator will use of its own accord.
-+The default value is
-+.BR .h .
-+
-+.IP YACCHXXFILESUFFIX
-+The suffix of the C++
-+header file generated by the parser generator
-+when the
-+.B \-d
-+option is used.
-+Note that setting this variable does not cause
-+the parser generator to generate a header
-+file with the specified suffix,
-+it exists to allow you to specify
-+what suffix the parser generator will use of its own accord.
-+The default value is
-+.BR .hpp ,
-+except on Mac OS X,
-+where the default is
-+.BR ${TARGET.suffix}.h .
-+because the default &bison; parser generator just
-+appends \fB.h\fP
-+to the name of the generated C++ file.
-+
-+.IP YACCVCGFILESUFFIX
-+The suffix of the file
-+containing the VCG grammar automaton definition
-+when the
-+.B \-\-graph=
-+option is used.
-+Note that setting this variable does not cause
-+the parser generator to generate a VCG
-+file with the specified suffix,
-+it exists to allow you to specify
-+what suffix the parser generator will use of its own accord.
-+The default value is
-+.BR .vcg .
-+
-+.IP ZIP
-+The zip compression and file packaging utility.
-+
-+.IP ZIPCOM
-+The command line used to call the zip utility,
-+or the internal Python function used to create a
-+zip archive.
-+
-+.IP ZIPCOMPRESSION
-+The
-+.I compression
-+flag
-+from the Python
-+.B zipfile
-+module used by the internal Python function
-+to control whether the zip archive
-+is compressed or not.
-+The default value is
-+.BR zipfile.ZIP_DEFLATED ,
-+which creates a compressed zip archive.
-+This value has no effect if the
-+.B zipfile
-+module is unavailable.
-+
-+.IP ZIPCOMSTR
-+The string displayed when archiving files
-+using the zip utility.
-+If this is not set, then \fB$ZIPCOM\fP
-+(the command line or internal Python function) is displayed.
-+
-+.ES
-+env = Environment(ZIPCOMSTR = "Zipping $TARGET")
-+.EE
-+
-+.IP ZIPFLAGS
-+General options passed to the zip utility.
-+
-+.IP ZIPSUFFIX
-+The suffix used for zip file names.
-+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-+'\" 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 explicitly 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>
-+
-Index: scons/sconsign.1
-===================================================================
---- /dev/null	1970-01-01 00:00:00.000000000 +0000
-+++ scons/sconsign.1	2014-04-26 12:20:51.007589417 +0200
-@@ -0,0 +1,208 @@
-+.\" Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013 The SCons Foundation
-+.\"
-+.\" 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.
-+.\"
-+.\" doc/man/sconsign.1  2013/03/03 09:48:35 garyo
-+.\"
-+.\" 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 "March 2013"
-+.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/debian/patches/parallel_build.patch b/debian/patches/parallel_build.patch
deleted file mode 100644
index 3af9a90..0000000
--- a/debian/patches/parallel_build.patch
+++ /dev/null
@@ -1,38 +0,0 @@
-Description:    Disable parallel build on sparc machines
-Origin:         Debian
-Bug-Debian:     http://bugs.debian.org/632228
-Forwarded:      no
-
-Index: scons/engine/SCons/Job.py
-===================================================================
---- scons.orig/engine/SCons/Job.py	2011-07-02 13:09:20.281651892 +0200
-+++ scons/engine/SCons/Job.py	2011-07-02 13:12:49.925651735 +0200
-@@ -83,7 +83,7 @@
-         """
- 
-         self.job = None
--        if num > 1:
-+        if num > 1 and not self._check_sparc_machine():
-             stack_size = explicit_stack_size
-             if stack_size is None:
-                 stack_size = default_stack_size
-@@ -163,6 +163,19 @@
-         except AttributeError:
-             pass
- 
-+    def _check_sparc_machine(self):
-+        """ Check whether machine is sparc"""
-+        try:
-+            from platform import machine
-+        except ImportError:
-+            pass
-+        else:
-+            if 'sparc' in machine():
-+                SCons.Warnings.warn(SCons.Warnings.StackSizeWarning,
-+                                    'Parallel build disabled on sparc, '
-+                                    'see Debian bug #632228')
-+                return True
-+
- class Serial(object):
-     """This class is used to execute tasks in series, and is more efficient
-     than Parallel, but is only appropriate for non-parallel builds. Only
diff --git a/debian/patches/remove_stale_files.patch b/debian/patches/remove_stale_files.patch
deleted file mode 100644
index 1422d91..0000000
--- a/debian/patches/remove_stale_files.patch
+++ /dev/null
@@ -1,31 +0,0 @@
-Description:    Remove stale files created by SCons when building Debian packages
-Origin:         Debian
-Bug-Debian:     http://bugs.debian.org/519948
-Forwarded:      http://scons.tigris.org/issues/show_bug.cgi?id=1571
-
-Index: b/engine/SCons/Script/Main.py
-===================================================================
---- a/engine/SCons/Script/Main.py	2010-01-23 15:11:19.624932557 +0100
-+++ b/engine/SCons/Script/Main.py	2010-01-23 15:11:35.084931903 +0100
-@@ -1087,6 +1087,21 @@
-             print 'Found nothing to build'
-             exit_status = 2
- 
-+        # Remove temporary files left by SCons
-+        if options.clean:
-+            if os.environ.has_key('DH_INTERNAL_OPTIONS'):
-+                import shutil
-+                for path in ('.sconsign.dblite', '.sconf_temp'):
-+                    try:
-+                        if os.path.isfile(path):
-+                            print 'Removing autogenerated file %s' % path
-+                            os.remove(path)
-+                        if os.path.isdir(path):
-+                            print 'Removing autogenerated directory %s' % path
-+                            shutil.rmtree(path)
-+                    except OSError:
-+                        pass
-+
- def _build_targets(fs, options, targets, target_top):
- 
-     global this_build_status
diff --git a/debian/patches/series b/debian/patches/series
deleted file mode 100644
index bb71714..0000000
--- a/debian/patches/series
+++ /dev/null
@@ -1,4 +0,0 @@
-java_ignore_nonexistent_files.patch
-remove_stale_files.patch
-parallel_build.patch
-manpages.patch