Restore man pages from version 2.3.0

1 files changed, 17138 insertions, 0 deletions

diff --git a/debian/patches/manpages.patch b/debian/patches/manpages.patch
new file mode 100644
index 0000000..88414d2
--- /dev/null
+++ b/debian/patches/manpages.patch
@@ -0,0 +1,17138 @@
+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:12:55.641711527 +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 commited changes to the
++SCons code base on a particular
++configuration over time.
++.P
++The other way is to profile incremental changes to a
++local SCons code base during a development cycle--that is,
++to look at the performance impact of changes
++you're making in the local tree.
++In this mode,
++you run the
++.B scons-time run
++subcommand
++.I without
++the
++.B --svn=
++option,
++in which case it simply looks in the profile/log file output directory
++(the current directory by default)
++and automatically figures out the
++.I next
++run number for the output profile and log file.
++Used in this way,
++the development cycle goes something like:
++make a change to SCons;
++run
++.B scons-time run
++to profile it against a specific configuration;
++make another change to SCons;
++run
++.B scons-time run
++again to profile it;
++etc.
++'\"==========================================================================
++.SH OPTIONS
++The
++.B scons-time
++command only supports a few global options:
++.TP
++-h, --help
++Displays the global help text and exits,
++identical to the
++.B scons-time help
++subcommand.
++.TP
++-V, --version
++Displays the
++.B scons-time
++version and exits.
++.P
++Most functionality is controlled by options
++to the individual subcommands.
++See the next section for information
++about individual subcommand options.
++'\"==========================================================================
++.SH SUBCOMMANDS
++The
++.B scons-time
++command supports the following
++individual subcommands.
++'\"--------------------------------------------------------------------------
++.SS "The func Subcommand"
++.SF
++.P
++The
++.B scons-time func
++subcommand displays timing information
++for a specific Python function within SCons.
++By default, it extracts information about the
++.BR _main ()
++function,
++which includes the Python profiler timing
++for all of SCons.
++.P
++The
++.B scons-time func
++subcommand extracts function timing information
++from all the specified file arguments,
++which should be Python profiler output files.
++(Normally, these would be
++.B *.prof
++files generated by the
++.B scons-time run
++subcommand,
++but they can actually be generated
++by any Python profiler invocation.)
++All file name arguments will be
++globbed for on-disk files.
++.P
++If no arguments are specified,
++then function timing information
++will be extracted from all
++.B *.prof
++files,
++or the subset of them
++with a prefix specified by the
++.B -p
++option.
++.P
++Options include:
++.TP
++-C DIRECTORY, --chdir=DIRECTORY
++Changes to the specified
++.I DIRECTORY
++before looking for the specified files
++(or files that match the specified patterns).
++.TP
++-f FILE, --file=FILE
++Reads configuration information from the specified
++.IR FILE .
++.TP
++-fmt=FORMAT, --format=FORMAT
++Reports the output in the specified
++.IR FORMAT .
++The formats currently supported are
++.B ascii
++(the default)
++and
++.BR gnuplot .
++.TP
++--func=NAME
++Extracts timings for the specified function
++.IR NAME .
++The default is to report cumulative timings for the
++.BR _main ()
++function,
++which contains the entire SCons run.
++.TP
++-h, --help
++Displays help text for the
++.B scons-time func
++subcommand.
++.TP
++-p STRING, --prefix=STRING
++Specifies the prefix string for profiles
++from which to extract function timing information.
++This will be used to search for profiles
++if no arguments are specified on the command line.
++.TP
++-t NUMBER, --tail=NUMBER
++Only extracts function timings from the last
++.I NUMBER
++files.
++'\"--------------------------------------------------------------------------
++.SS "The help Subcommand"
++.B scons-time help
++.I SUBCOMMAND
++[...]
++The
++.B help
++subcommand prints help text for any
++other subcommands listed as later arguments on the command line.
++'\"--------------------------------------------------------------------------
++.SS "The mem Subcommand"
++.SY
++.P
++The
++.B scons-time mem
++subcommand displays how much memory SCons uses.
++.P
++The
++.B scons-time mem
++subcommand extracts memory use information
++from all the specified file arguments,
++which should be files containing output from
++running SCons with the
++.B --debug=memory
++option.
++(Normally, these would be
++.B *.log
++files generated by the
++.B scons-time run
++subcommand.)
++All file name arguments will be
++globbed for on-disk files.
++.P
++If no arguments are specified,
++then memory information
++will be extracted from all
++.B *.log
++files,
++or the subset of them
++with a prefix specified by the
++.B -p
++option.
++.P
++.TP
++-C DIR, --chdir=DIR
++Changes to the specified
++.I DIRECTORY
++before looking for the specified files
++(or files that match the specified patterns).
++.TP
++-f FILE, --file=FILE
++Reads configuration information from the specified
++.IR FILE .
++.TP
++-fmt=FORMAT, --format=FORMAT
++Reports the output in the specified
++.IR FORMAT .
++The formats currently supported are
++.B ascii
++(the default)
++and
++.BR gnuplot .
++.TP
++-h, --help
++Displays help text for the
++.B scons-time mem
++subcommand.
++.TP
++-p STRING, --prefix=STRING
++Specifies the prefix string for log files
++from which to extract memory usage information.
++This will be used to search for log files
++if no arguments are specified on the command line.
++.TP
++--stage=STAGE
++Prints the memory used at the end of the specified
++.IR STAGE :
++.B pre-read
++(before the SConscript files are read),
++.B post-read ,
++(after the SConscript files are read),
++.B pre-build
++(before any targets are built)
++or
++.B post-build
++(after any targets are built).
++If no
++.B --stage
++option is specified,
++the default behavior is
++.BR post-build ,
++which reports the final amount of memory
++used by SCons during each run.
++.TP
++-t NUMBER, --tail=NUMBER
++Only reports memory statistics from the last
++.I NUMBER
++files.
++'\"--------------------------------------------------------------------------
++.SS "The obj Subcommand"
++.SO
++.P
++The
++.B scons-time obj
++subcommand displays how many objects of a specific named type
++are created by SCons.
++.P
++The
++.B scons-time obj
++subcommand extracts object counts
++from all the specified file arguments,
++which should be files containing output from
++running SCons with the
++.B --debug=count
++option.
++(Normally, these would be
++.B *.log
++files generated by the
++.B scons-time run
++subcommand.)
++All file name arguments will be
++globbed for on-disk files.
++.P
++If no arguments are specified,
++then object counts
++will be extracted from all
++.B *.log
++files,
++or the subset of them
++with a prefix specified by the
++.B -p
++option.
++.TP
++-C DIR, --chdir=DIR
++Changes to the specified
++.I DIRECTORY
++before looking for the specified files
++(or files that match the specified patterns).
++.TP
++-f FILE, --file=FILE
++Reads configuration information from the specified
++.IR FILE .
++.TP
++-fmt=FORMAT, --format=FORMAT
++Reports the output in the specified
++.IR FORMAT .
++The formats currently supported are
++.B ascii
++(the default)
++and
++.BR gnuplot .
++.TP
++-h, --help
++Displays help text for the
++.B scons-time obj
++subcommand.
++.TP
++-p STRING, --prefix=STRING
++Specifies the prefix string for log files
++from which to extract object counts.
++This will be used to search for log files
++if no arguments are specified on the command line.
++.TP
++--stage=STAGE
++Prints the object count at the end of the specified
++.IR STAGE :
++.B pre-read
++(before the SConscript files are read),
++.B post-read ,
++(after the SConscript files are read),
++.B pre-build
++(before any targets are built)
++or
++.B post-build
++(after any targets are built).
++If no
++.B --stage
++option is specified,
++the default behavior is
++.BR post-build ,
++which reports the final object count during each run.
++.TP
++-t NUMBER, --tail=NUMBER
++Only reports object counts from the last
++.I NUMBER
++files.
++'\"--------------------------------------------------------------------------
++.SS "The run Subcommand"
++.SR
++The
++.B scons-time run
++subcommand is the basic subcommand
++for profiling a specific configuration
++against a version of SCons.
++.P
++The configuration to be tested
++is specified as a list of files
++or directories that will be unpacked or copied
++into a temporary directory
++in which SCons will be invoked.
++The
++.B scons-time run
++subcommand understands file suffixes like
++.BR .tar ,
++.BR .tar.gz ,
++.BR .tgz
++and
++.BR .zip
++and will unpack their contents into a temporary directory.
++If more than one argument is specified,
++each one will be unpacked or copied
++into the temporary directory "on top of"
++the previous archives or directories,
++so the expectation is that multiple
++specified archives share the same directory layout.
++.P
++Once the file or directory arguments are unpacked or
++copied to the temporary directory,
++the
++.B scons-time run
++subcommand runs the
++requested version of SCons
++against the configuration
++three times:
++.TP
++Startup
++SCons is run with the
++.B --help
++option so that just the SConscript files are read,
++and then the default help text is printed.
++This profiles just the perceived "overhead" of starting up SCons
++and processing the SConscript files.
++.TP
++Full build
++SCons is run to build everything specified in the configuration.
++Specific targets to be passed in on the command l ine
++may be specified by the
++.B targets
++keyword in a configuration file; see below for details.
++.TP
++Rebuild
++SCons is run again on the same just-built directory.
++If the dependencies in the SCons configuration are correct,
++this should be an up-to-date, "do nothing" rebuild.
++.P
++Each invocation captures the output log file and a profile.
++.P
++The
++.B scons-time run
++subcommand supports the following options:
++.TP
++--aegis=PROJECT
++Specifies the Aegis
++.I PROJECT
++from which the
++version(s) of
++.B scons
++being timed will be extracted.
++When
++.B --aegis
++is specified, the
++.BI --number= NUMBER
++option specifies delta numbers
++that will be tested.
++Output from each invocation run will be placed in file
++names that match the Aegis delta numbers.
++If the
++.B --number=
++option is not specified,
++then the default behavior is to time the
++tip of the specified
++.IR PROJECT .
++.TP
++-f FILE, --file=FILE
++Reads configuration information from the specified
++.IR FILE .
++This often provides a more convenient way to specify and
++collect parameters associated with a specific timing configuration
++than specifying them on the command line.
++See the
++.B CONFIGURATION FILE
++section below
++for information about the configuration file parameters.
++.TP
++-h, --help
++Displays help text for the
++.B scons-time run
++subcommand.
++.TP
++-n, --no-exec
++Do not execute commands,
++just printing the command-line equivalents of what would be executed.
++Note that the
++.B scons-time
++script actually executes its actions in Python,
++where possible,
++for portability.
++The commands displayed are UNIX
++.I equivalents
++of what it's doing.
++.TP
++--number=NUMBER
++Specifies the run number to be used in the names of
++the log files and profile outputs generated by this run.
++.IP
++When used in conjuction with the
++.BI --aegis= PROJECT
++option,
++.I NUMBER
++specifies one or more comma-separated Aegis delta numbers
++that will be retrieved automatically from the specified Aegis
++.IR PROJECT .
++.IP
++When used in conjuction with the
++.BI --svn= URL
++option,
++.I NUMBER
++specifies one or more comma-separated Subversion revision numbers
++that will be retrieved automatically from the Subversion
++repository at the specified
++.IR URL .
++Ranges of delta or revision numbers
++may be specified be separating two numbers
++with a hyphen
++.RB ( \- ).
++.P
++Example:
++.ES
++% scons-time run --svn=http://scons.tigris.org/svn/trunk --num=1247,1249-1252 .
++.EE
++.TP
++-p STRING, --prefix=STRING
++Specifies the prefix string to be used for all of the log files
++and profiles generated by this run.
++The default is derived from the first
++specified argument:
++if the first argument is a directory,
++the default prefix is the name of the directory;
++if the first argument is an archive
++(tar or zip file),
++the default prefix is the the base name of the archive,
++that is, what remains after stripping the archive suffix
++.RB ( .tgz ", " .tar.gz " or " .zip ).
++.TP
++--python=PYTHON
++Specifies a path to the Python executable to be used
++for the timing runs.
++The default is to use the same Python executable that
++is running the
++.B scons-time
++command itself.
++.TP
++-q, --quiet
++Suppresses display of the command lines being executed.
++.TP
++-s DIR, --subdir=DIR
++Specifies the name of directory or subdirectory
++from which the commands should be executed.
++The default is XXX
++.TP
++--scons=SCONS
++Specifies a path to the SCons script to be used
++for the timing runs.
++The default is XXX
++.TP
++--svn=URL, --subversion=URL
++Specifies the
++.I URL
++of the Subversion repository from which the
++version(s) of
++.B scons
++being timed will be extracted.
++When
++.B --svn
++is specified, the
++.BI --number= NUMBER
++option specifies revision numbers
++that will be tested.
++Output from each invocation run will be placed in file
++names that match the Subversion revision numbers.
++If the
++.B --number=
++option is not specified,
++then the default behavior is to time the
++.B HEAD
++of the specified
++.IR URL .
++.TP
++-v, --verbose
++Displays the output from individual commands to the screen
++(in addition to capturing the output in log files).
++'\"--------------------------------------------------------------------------
++.SS "The time Subcommand"
++.ST
++.P
++The
++.B scons-time time
++subcommand displays SCons execution times
++as reported by the
++.B scons --debug=time
++option.
++.P
++The
++.B scons-time time
++subcommand extracts SCons timing
++from all the specified file arguments,
++which should be files containing output from
++running SCons with the
++.B --debug=time
++option.
++(Normally, these would be
++.B *.log
++files generated by the
++.B scons-time run
++subcommand.)
++All file name arguments will be
++globbed for on-disk files.
++.P
++If no arguments are specified,
++then execution timings
++will be extracted from all
++.B *.log
++files,
++or the subset of them
++with a prefix specified by the
++.B -p
++option.
++.TP
++-C DIR, --chdir=DIR
++Changes to the specified
++.I DIRECTORY
++before looking for the specified files
++(or files that match the specified patterns).
++.TP
++-f FILE, --file=FILE
++Reads configuration information from the specified
++.IR FILE .
++.TP
++-fmt=FORMAT, --format=FORMAT
++Reports the output in the specified
++.IR FORMAT .
++The formats currently supported are
++.B ascii
++(the default)
++and
++.BR gnuplot .
++.TP
++-h, --help
++Displays help text for the
++.B scons-time time
++subcommand.
++.TP
++-p STRING, --prefix=STRING
++Specifies the prefix string for log files
++from which to extract execution timings.
++This will be used to search for log files
++if no arguments are specified on the command line.
++.TP
++-t NUMBER, --tail=NUMBER
++Only reports object counts from the last
++.I NUMBER
++files.
++.TP
++--which=WHICH
++Prints the execution time for the specified
++.IR WHICH
++value:
++.B total
++(the total execution time),
++.B SConscripts
++(total execution time for the SConscript files themselves),
++.B SCons
++(exectuion time in SCons code itself)
++or
++.B commands
++(execution time of the commands and other actions
++used to build targets).
++If no
++.B --which
++option is specified,
++the default behavior is
++.BR total ,
++which reports the total execution time for each run.
++'\"==========================================================================
++.SH CONFIGURATION FILE
++Various
++.B scons-time
++subcommands can read information from a specified
++configuration file when passed the
++.B \-f
++or
++.B \--file
++options.
++The configuration file is actually executed as a Python script.
++Setting Python variables in the configuration file
++controls the behavior of the
++.B scons-time
++script more conveniently than having to specify
++command-line options or arguments for every run,
++and provides a handy way to "shrink-wrap"
++the necessary information for producing (and reporting)
++consistent timing runs for a given configuration.
++.TP
++.B aegis
++The Aegis executable for extracting deltas.
++The default is simply
++.BR aegis .
++.TP
++.B aegis_project
++The Aegis project from which deltas should be extracted.
++The default is whatever is specified
++with the
++.B --aegis=
++command-line option.
++.TP
++.B archive_list
++A list of archives (files or directories)
++that will be copied to the temporary directory
++in which SCons will be invoked.
++.BR .tar ,
++.BR .tar.gz ,
++.BR .tgz
++and
++.BR .zip
++files will have their contents unpacked in
++the temporary directory.
++Directory trees and files will be copied as-is.
++.TP
++.B initial_commands
++A list of commands that will be executed
++before the actual timed
++.B scons
++runs.
++This can be used for commands that are necessary
++to prepare the source tree\-for example,
++creating a configuration file
++that should not be part of the timed run.
++.TP
++.B key_location
++The location of the key on Gnuplot graphing information
++generated with the
++.BR --format=gnuplot
++option.
++The default is
++.BR "bottom left" .
++.TP
++.B prefix
++The file name prefix to be used when
++running or extracting timing for this configuration.
++.TP
++.B python
++The path name of the Python executable
++to be used when running or extracting information
++for this configuration.
++The default is the same version of Python
++used to run the SCons
++.TP
++.B scons
++The path name of the SCons script to be used
++when running or extracting information
++for this configuration.
++The default is simply
++.BR scons .
++.TP
++.B scons_flags
++The
++.B scons
++flags used when running SCons to collect timing information.
++The default value is
++.BR "--debug=count --debug=memory --debug=time --debug=memoizer" .
++.TP
++.B scons_lib_dir
++.TP
++.B scons_wrapper
++.TP
++.B startup_targets
++.TP
++.B subdir
++The subdirectory of the project into which the
++.B scons-time
++script should change
++before executing the SCons commands to time.
++.TP
++.B subversion_url
++The Subversion URL from
++.TP
++.B svn
++The subversion executable used to
++check out revisions of SCons to be timed.
++The default is simple
++.BR svn .
++.TP
++.B svn_co_flag
++.TP
++.B tar
++.TP
++.B targets
++A string containing the targets that should be added to
++the command line of every timed
++.B scons
++run.
++This can be used to restrict what's being timed to a
++subset of the full build for the configuration.
++.TP
++.B targets0
++.TP
++.B targets1
++.TP
++.B targets2
++.TP
++.B title
++.TP
++.B unzip
++.TP
++.B verbose
++.TP
++.B vertical_bars
++'\"--------------------------------------------------------------------------
++.SS Example
++Here is an example
++.B scons-time
++configuration file
++for a hypothetical sample project:
++.P
++.ES
++# The project doesn't use SCons natively (yet), so we're
++# timing a separate set of SConscript files that we lay
++# on top of the vanilla unpacked project tarball.
++arguments = ['project-1.2.tgz', 'project-SConscripts.tar']
++
++# The subdirectory name contains the project version number,
++# so tell scons-time to chdir there before building.
++subdir = 'project-1.2'
++
++# Set the prefix so output log files and profiles are named:
++#     project-000-[012].{log,prof}
++#     project-001-[012].{log,prof}
++# etc.
++prefix = 'project'
++
++# The SConscript files being tested don't do any SConf
++# configuration, so run their normal ./configure script
++# before we invoke SCons.
++initial_commands = [
++    './configure',
++]
++
++# Only time building the bin/project executable.
++targets = 'bin/project'
++
++# Time against SCons revisions of the branches/core branch
++subversion_url = 'http://scons.tigris.org/svn/scons/branches/core'
++.EE
++'\"==========================================================================
++.SH ENVIRONMENT
++The
++.B scons-time
++script uses the following environment variables:
++.TP
++.B PRESERVE
++If this value is set,
++the
++.B scons-time
++script will
++.I not
++remove the temporary directory or directories
++in which it builds the specified configuration
++or downloads a specific version of SCons.
++'\"==========================================================================
++.SH "SEE ALSO"
++.BR gnuplot (1),
++.BR scons (1)
++
++.SH AUTHORS
++Steven Knight <knight at baldmt dot com>
+Index: scons/scons.1
+===================================================================
+--- /dev/null	1970-01-01 00:00:00.000000000 +0000
++++ scons/scons.1	2014-04-26 12:12:44.853737230 +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
++conjuction 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 overriden 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 easilly 
++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). Additionaly, 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 explictly tell SCons to use MinGW by passing
++
++.ES
++tools=['mingw']
++.EE
++
++to the Environment() function, because SCons will prefer the MSVC tools
++over the MinGW tools.
++
++.SH EXAMPLES
++
++To help you get started using SCons,
++this section contains a brief overview of some common tasks.
++
++.SS Basic Compilation From a Single Source File
++
++.ES
++env = Environment()
++env.Program(target = 'foo', source = 'foo.c')
++.EE
++
++Note:  Build the file by specifying
++the target as an argument
++("scons foo" or "scons foo.exe").
++or by specifying a dot ("scons .").
++
++.SS Basic Compilation From Multiple Source Files
++
++.ES
++env = Environment()
++env.Program(target = 'foo', source = Split('f1.c f2.c f3.c'))
++.EE
++
++.SS Setting a Compilation Flag
++
++.ES
++env = Environment(CCFLAGS = '-g')
++env.Program(target = 'foo', source = 'foo.c')
++.EE
++
++.SS Search The Local Directory For .h Files
++
++Note:  You do
++.I not
++need to set CCFLAGS to specify -I options by hand.
++SCons will construct the right -I options from CPPPATH.
++
++.ES
++env = Environment(CPPPATH = ['.'])
++env.Program(target = 'foo', source = 'foo.c')
++.EE
++
++.SS Search Multiple Directories For .h Files
++
++.ES
++env = Environment(CPPPATH = ['include1', 'include2'])
++env.Program(target = 'foo', source = 'foo.c')
++.EE
++
++.SS Building a Static Library
++
++.ES
++env = Environment()
++env.StaticLibrary(target = 'foo', source = Split('l1.c l2.c'))
++env.StaticLibrary(target = 'bar', source = ['l3.c', 'l4.c'])
++.EE
++
++.SS Building a Shared Library
++
++.ES
++env = Environment()
++env.SharedLibrary(target = 'foo', source = ['l5.c', 'l6.c'])
++env.SharedLibrary(target = 'bar', source = Split('l7.c l8.c'))
++.EE
++
++.SS Linking a Local Library Into a Program
++
++.ES
++env = Environment(LIBS = 'mylib', LIBPATH = ['.'])
++env.Library(target = 'mylib', source = Split('l1.c l2.c'))
++env.Program(target = 'prog', source = ['p1.c', 'p2.c'])
++.EE
++
++.SS Defining Your Own Builder Object
++
++Notice that when you invoke the Builder,
++you can leave off the target file suffix,
++and SCons will add it automatically.
++
++.ES
++bld = Builder(action = 'pdftex < $SOURCES > $TARGET'
++              suffix = '.pdf',
++              src_suffix = '.tex')
++env = Environment(BUILDERS = {'PDFBuilder' : bld})
++env.PDFBuilder(target = 'foo.pdf', source = 'foo.tex')
++
++# The following creates "bar.pdf" from "bar.tex"
++env.PDFBuilder(target = 'bar', source = 'bar')
++.EE
++
++Note also that the above initialization
++overwrites the default Builder objects,
++so the Environment created above
++can not be used call Builders like env.Program(),
++env.Object(), env.StaticLibrary(), etc.
++
++.SS Adding Your Own Builder Object to an Environment
++
++.ES
++bld = Builder(action = 'pdftex < $SOURCES > $TARGET'
++              suffix = '.pdf',
++              src_suffix = '.tex')
++env = Environment()
++env.Append(BUILDERS = {'PDFBuilder' : bld})
++env.PDFBuilder(target = 'foo.pdf', source = 'foo.tex')
++env.Program(target = 'bar', source = 'bar.c')
++.EE
++
++You also can use other Pythonic techniques to add
++to the BUILDERS construction variable, such as:
++
++.ES
++env = Environment()
++env['BUILDERS]['PDFBuilder'] = bld
++.EE
++
++.SS Defining Your Own Scanner Object
++
++The following example shows an extremely simple scanner (the
++.BR kfile_scan ()
++function)
++that doesn't use a search path at all
++and simply returns the
++file names present on any
++.B include
++lines in the scanned file.
++This would implicitly assume that all included
++files live in the top-level directory:
++
++.ES
++import re
++
++'\" Note:  the \\ in the following are for the benefit of nroff/troff,
++'\" not inappropriate doubled escape characters within the r'' raw string.
++include_re = re.compile(r'^include\\s+(\\S+)$', re.M)
++
++def kfile_scan(node, env, path, arg):
++    contents = node.get_text_contents()
++    includes = include_re.findall(contents)
++    return env.File(includes)
++
++kscan = Scanner(name = 'kfile',
++                function = kfile_scan,
++                argument = None,
++                skeys = ['.k'])
++scanners = Environment().Dictionary('SCANNERS')
++env = Environment(SCANNERS = scanners + [kscan])
++
++env.Command('foo', 'foo.k', 'kprocess < $SOURCES > $TARGET')
++
++bar_in = File('bar.in')
++env.Command('bar', bar_in, 'kprocess $SOURCES > $TARGET')
++bar_in.target_scanner = kscan
++.EE
++
++It is important to note that you
++have to return a list of File nodes from the scan function, simple
++strings for the file names won't do. As in the examples we are showing here,
++you can use the
++.BR File()
++function of your current Environment in order to create nodes on the fly from
++a sequence of file names with relative paths.
++
++Here is a similar but more complete example that searches
++a path of directories
++(specified as the
++.B MYPATH
++construction variable)
++for files that actually exist:
++
++.ES
++import re
++import os
++include_re = re.compile(r'^include\\s+(\\S+)$', re.M)
++
++def my_scan(node, env, path, arg):
++    contents = node.get_text_contents()
++    includes = include_re.findall(contents)
++    if includes == []:
++        return []
++    results = []
++    for inc in includes:
++        for dir in path:
++            file = str(dir) + os.sep + inc
++            if os.path.exists(file):
++                results.append(file)
++                break
++    return env.File(results)
++
++scanner = Scanner(name = 'myscanner',
++                 function = my_scan,
++                 argument = None,
++                 skeys = ['.x'],
++                 path_function = FindPathDirs('MYPATH')
++                 )
++scanners = Environment().Dictionary('SCANNERS')
++env = Environment(SCANNERS = scanners + [scanner],
++                  MYPATH = ['incs'])
++
++env.Command('foo', 'foo.x', 'xprocess < $SOURCES > $TARGET')
++.EE
++
++The
++.BR FindPathDirs ()
++function used in the previous example returns a function
++(actually a callable Python object)
++that will return a list of directories
++specified in the
++.B $MYPATH
++construction variable. It lets SCons detect the file
++.B incs/foo.inc
++, even if 
++.B foo.x 
++contains the line
++.B include foo.inc 
++only.
++If you need to customize how the search path is derived,
++you would provide your own
++.B path_function
++argument when creating the Scanner object,
++as follows:
++
++.ES
++# MYPATH is a list of directories to search for files in
++def pf(env, dir, target, source, arg):
++    top_dir = Dir('#').abspath
++    results = []
++    if 'MYPATH' in env:
++        for p in env['MYPATH']:
++            results.append(top_dir + os.sep + p)
++    return results
++
++scanner = Scanner(name = 'myscanner',
++                 function = my_scan,
++                 argument = None,
++                 skeys = ['.x'],
++                 path_function = pf
++                 )
++.EE
++
++.SS Creating a Hierarchical Build
++
++Notice that the file names specified in a subdirectory's
++SConscript
++file are relative to that subdirectory.
++
++.ES
++SConstruct:
++
++    env = Environment()
++    env.Program(target = 'foo', source = 'foo.c')
++
++    SConscript('sub/SConscript')
++
++sub/SConscript:
++
++    env = Environment()
++    # Builds sub/foo from sub/foo.c
++    env.Program(target = 'foo', source = 'foo.c')
++
++    SConscript('dir/SConscript')
++
++sub/dir/SConscript:
++
++    env = Environment()
++    # Builds sub/dir/foo from sub/dir/foo.c
++    env.Program(target = 'foo', source = 'foo.c')
++.EE
++
++.SS Sharing Variables Between SConscript Files
++
++You must explicitly Export() and Import() variables that
++you want to share between SConscript files.
++
++.ES
++SConstruct:
++
++    env = Environment()
++    env.Program(target = 'foo', source = 'foo.c')
++
++    Export("env")
++    SConscript('subdirectory/SConscript')
++
++subdirectory/SConscript:
++
++    Import("env")
++    env.Program(target = 'foo', source = 'foo.c')
++.EE
++
++.SS Building Multiple Variants From the Same Source
++
++Use the variant_dir keyword argument to
++the SConscript function to establish
++one or more separate variant build directory trees
++for a given source directory:
++
++.ES
++SConstruct:
++
++    cppdefines = ['FOO']
++    Export("cppdefines")
++    SConscript('src/SConscript', variant_dir='foo')
++
++    cppdefines = ['BAR']
++    Export("cppdefines")
++    SConscript('src/SConscript', variant_dir='bar')
++
++src/SConscript:
++
++    Import("cppdefines")
++    env = Environment(CPPDEFINES = cppdefines)
++    env.Program(target = 'src', source = 'src.c')
++.EE
++
++Note the use of the Export() method
++to set the "cppdefines" variable to a different
++value each time we call the SConscript function.
++
++.SS Hierarchical Build of Two Libraries Linked With a Program
++
++.ES
++SConstruct:
++
++    env = Environment(LIBPATH = ['#libA', '#libB'])
++    Export('env')
++    SConscript('libA/SConscript')
++    SConscript('libB/SConscript')
++    SConscript('Main/SConscript')
++
++libA/SConscript:
++
++    Import('env')
++    env.Library('a', Split('a1.c a2.c a3.c'))
++
++libB/SConscript:
++
++    Import('env')
++    env.Library('b', Split('b1.c b2.c b3.c'))
++
++Main/SConscript:
++
++    Import('env')
++    e = env.Copy(LIBS = ['a', 'b'])
++    e.Program('foo', Split('m1.c m2.c m3.c'))
++.EE
++
++The '#' in the LIBPATH directories specify that they're relative to the
++top-level directory, so they don't turn into "Main/libA" when they're
++used in Main/SConscript.
++
++Specifying only 'a' and 'b' for the library names
++allows SCons to append the appropriate library
++prefix and suffix for the current platform
++(for example, 'liba.a' on POSIX systems,
++\&'a.lib' on Windows).
++
++.SS Customizing construction variables from the command line.
++
++The following would allow the C compiler to be specified on the command
++line or in the file custom.py.
++
++.ES
++vars = Variables('custom.py')
++vars.Add('CC', 'The C compiler.')
++env = Environment(variables=vars)
++Help(vars.GenerateHelpText(env))
++.EE
++
++The user could specify the C compiler on the command line:
++
++.ES
++scons "CC=my_cc"
++.EE
++
++or in the custom.py file:
++
++.ES
++CC = 'my_cc'
++.EE
++
++or get documentation on the options:
++
++.ES
++$ scons -h
++
++CC: The C compiler.
++    default: None
++    actual: cc
++
++.EE
++
++.SS Using Microsoft Visual C++ precompiled headers
++
++Since windows.h includes everything and the kitchen sink, it can take quite
++some time to compile it over and over again for a bunch of object files, so
++Microsoft provides a mechanism to compile a set of headers once and then
++include the previously compiled headers in any object file. This
++technology is called precompiled headers. The general recipe is to create a
++file named "StdAfx.cpp" that includes a single header named "StdAfx.h", and
++then include every header you want to precompile in "StdAfx.h", and finally
++include "StdAfx.h" as the first header in all the source files you are
++compiling to object files. For example:
++
++StdAfx.h:
++.ES
++#include <windows.h>
++#include <my_big_header.h>
++.EE
++
++StdAfx.cpp:
++.ES
++#include <StdAfx.h>
++.EE
++
++Foo.cpp:
++.ES
++#include <StdAfx.h>
++
++/* do some stuff */
++.EE
++
++Bar.cpp:
++.ES
++#include <StdAfx.h>
++
++/* do some other stuff */
++.EE
++
++SConstruct:
++.ES
++env=Environment()
++env['PCHSTOP'] = 'StdAfx.h'
++env['PCH'] = env.PCH('StdAfx.cpp')[0]
++env.Program('MyApp', ['Foo.cpp', 'Bar.cpp'])
++.EE
++
++For more information see the document for the PCH builder, and the PCH and
++PCHSTOP construction variables. To learn about the details of precompiled
++headers consult the MSDN documention for /Yc, /Yu, and /Yp.
++
++.SS Using Microsoft Visual C++ external debugging information
++
++Since including debugging information in programs and shared libraries can
++cause their size to increase significantly, Microsoft provides a mechanism
++for including the debugging information in an external file called a PDB
++file. SCons supports PDB files through the PDB construction
++variable.
++
++SConstruct:
++.ES
++env=Environment()
++env['PDB'] = 'MyApp.pdb'
++env.Program('MyApp', ['Foo.cpp', 'Bar.cpp'])
++.EE
++
++For more information see the document for the PDB construction variable.
++
++.SH ENVIRONMENT
++
++.IP SCONS_LIB_DIR
++Specifies the directory that contains the SCons Python module directory
++(e.g. /home/aroach/scons-src-0.01/src/engine).
++
++.IP SCONSFLAGS
++A string of options that will be used by scons in addition to those passed
++on the command line.
++
++.SH "SEE ALSO"
++.B scons
++User Manual,
++.B scons
++Design Document,
++.B scons
++source code.
++
++.SH AUTHORS
++Steven Knight <knight@baldmt.com>
++.br
++Anthony Roach <aroach@electriceyeball.com>
++
+Index: scons/sconsign.1
+===================================================================
+--- /dev/null	1970-01-01 00:00:00.000000000 +0000
++++ scons/sconsign.1	2014-04-26 12:12:51.305721997 +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>