Added an unmodified copy of SCons to third_party.

scons-2.0.1/scons.1

+.\" Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 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 5134 2010/08/16 23:02:40 bdeegan
+.\"
+.TH SCONS 1 "August 2010"
+.\" 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 the directory containing the
+.I SConstruct
+file; if it exists,
+.I site_scons
+is added 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 added to the default toolpath if it exist.
+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=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=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
+dir to
+.IR sys.path .
+Also prevents loading the
+.I site_scons/site_init.py
+module if it exists, and prevents adding
+.I site_scons/site_tools
+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
+dir.  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.
+
+.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 $CFILESUFFIX 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 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 $CXXFILESUFFIX 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 $LATEXCOM command line;
+otherwise, the $TEXCOM 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 $BIBTEX command line
+if the string
+.B bibdata
+is found,
+start $MAKEINDEX to generate an index if a
+.B .ind
+file is found
+and will examine the contents
+.B .log
+file and re-run the $LATEXCOM 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.
+
+.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.
+
+.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 $JARCHDIR value is set, the
+.B jar
+command will change to the specified directory using the
+.B \-C
+option.
+If $JARCHDIR 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
+$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 $M4FLAGS 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 $QTDIR variable for more information.
+Example:
+
+.ES
+env.Moc('foo.h') # generates moc_foo.cc
+env.Moc('foo.cpp') # generates foo.moc
+.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
+$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 $SOURCES 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
+$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 $CCFLAGS  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
+$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
+$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.
+
+(NOTE: Currently only one project is supported per solution.)
+
+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 $PACKAGETYPE 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 $PDFSUFFIX 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 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 $PSSUFFIX 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 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 $PROGPREFIX construction variable; nothing by default)
+and suffix
+(specified by the $PROGSUFFIX 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
+$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 $SHLIBPREFIX construction variable;
+by default, \fBlib\fP on POSIX systems,
+nothing on Windows systems)
+and suffix
+(specified by the $SHLIBSUFFIX 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.
+
+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 $REGSVR construction
+variable, and the flags passed are determined by $REGSVRFLAGS.  By
+default, $REGSVRFLAGS includes the \fB/s\fP option,
+to prevent dialogs from popping
+up and requiring user attention when it is run.  If you change
+$REGSVRFLAGS, 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 $SHOBJPREFIX construction variable;
+by default, the same as $OBJPREFIX)
+and suffix
+(specified by the $SHOBJSUFFIX 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 $LIBPREFIX construction variable;
+by default, \fBlib\fP on POSIX systems,
+nothing on Windows systems)
+and suffix
+(specified by the $LIBSUFFIX 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 $OBJPREFIX construction variable; nothing by default)
+and suffix
+(specified by the $OBJSUFFIX 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. 
+$LINESEPARATOR 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 $SUBSTFILEPREFIX
+and $SUBSTFILESUFFIX 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 $SUBST_DICT 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. 
+$LINESEPARATOR is used to separate the strings.
+
+If present, the $SUBST_DICT 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 $TEXTFILEPREFIX
+and $TEXTFILESUFFIX 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 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 $QTDIR 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:
+
+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.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
+.RI 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
+.B 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 ().
+\" NOTE: in SCons 1.x or 2.0, user options will be settable, but not yet.
+\" Uncomment this when that works.  See tigris issue 2105.
+\" 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
+.RI 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
+.RI 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
+
+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
+.RI 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.
+.B 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
+.BR 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
+.B 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
+.RI 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
+.RI 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
+.RI 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
+.RI 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
+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
+.B SourceCode
+function.
+
+This function is deprecated.  For details, see the entry for the
+.B SourceCode
+function.
+
+Example:
+
+.ES
+env.SourceCode('.', env.BitKeeper())
+.EE
+
+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.TP
+.RI BuildDir( build_dir ", " src_dir ", [" duplicate ])
+.TP
+.RI 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
+.RI 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
+.B 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
+.RI env.CacheDir( cache_dir )
+Specifies that
+.B scons
+will maintain a cache of derived files in
+.I 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
+.RI 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
+
+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
+.RI Command( target ", " source ", " action ", [" key = val ", ...])"
+.TP
+.RI 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
+.B 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
+.RI 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
+.RI env.Clone([ key = val ", ...])"
+Return 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
+
+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 env.Copy([ key = val ", ...])"
+A now-deprecated synonym for
+.BR env.Clone() .
+
+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.TP
+.RI 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
+.B 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.
+
+This function is deprecated.  For details, see the entry for the
+.B SourceCode
+function.
+
+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
+.RI 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
+.HP 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 .
+
+.HP 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.
+
+.HP 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 .
+
+.HP 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
+
+.IP
+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
+
+.IP
+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
+.RI 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
+.RI 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
+.RI 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
+.RI 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
+.RI env.Dump([ key ])
+Returns a pretty printable representation of the environment.
+.IR key ,
+if not
+.IR 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
+
+.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
+.RI env.EnsurePythonVersion( major ", " minor )
+Ensure that the Python version is at least
+.IR major . minor .
+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
+.RI 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
+.RI env.Environment([ key = value ", ...])"
+Return a new construction environment
+initialized with the specified
+.IR key = value
+pairs.
+
+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.TP
+.RI Execute( action ", [" strfunction ", " varlist ])
+.TP
+.RI env.Execute( action ", [" strfunction ", " varlist ])
+Executes an Action object.
+The specified
+.IR 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
+.I 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
+.RI 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
+.RI 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
+.RI 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
+.RI 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
+.RI env.FindInstalledFiles( )
+Returns the list of targets set up by the
+.B Install()
+or
+.B 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 FindSourceFiles( node = '"."' )
+.TP
+.RI 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
+.B node
+which defaults to the '"."'-node. It will then return all leaves of
+.B 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 FindPathDirs( variable )
+Returns a function
+(actually a callable Python object)
+intended to be used as the
+.B 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
+.B 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 Flatten( sequence )
+.TP
+.RI 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
+.B 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
+.RI 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
+.RI 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 ,
+.BR \-U
+or
+.BR \-D
+options, which internally
+change to the directory in which the
+.B SConstruct
+file is found.
+
+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.TP
+.RI GetOption( name )
+.TP
+.RI env.GetOption( name )
+This function provides a way to query the value of
+SCons options set on scons command line
+(or set using the
+.IR 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
+
+.IP
+See the documentation for the
+corresponding command line object for information about each specific
+option.
+
+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.TP
+.RI Glob( pattern ", [" ondisk ", " source ", " strings ])
+.TP
+.RI 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
+.B 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
+.B 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
+.B 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 GlobalBuilders( flag )
+'\"When
+'\".B flag
+'\"is non-zero,
+'\"adds the names of the default builders
+'\"(Program, Library, etc.)
+'\"to the global name space
+'\"so they can be called without an explicit construction environment.
+'\"(This is the default.)
+'\"When
+'\".B
+'\"flag is zero,
+'\"the names of the default builders are removed
+'\"from the global name space
+'\"so that an explicit construction environment is required
+'\"to call all builders.
+
+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.TP
+.RI Help( text )
+.TP
+.RI 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
+.RI 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
+.RI 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
+.RI env.Literal( string )
+The specified
+.I string
+will be preserved as-is
+and not have construction variables expanded.
+
+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.TP
+.RI Local( targets )
+.TP
+.RI 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
+\" .RI env.MergeShellPaths( arg ", [" prepend ])
+\" Merges the elements of the specified
+\" .IR arg ,
+\" which must be a dictionary, to the construction
+\" environment's copy of the shell environment
+\" in env['ENV'].
+\" (This is the environment which is passed
+\" to subshells spawned by SCons.)
+\" 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.MergeShellPaths ().
+
+\" New values are prepended to the environment variable by default,
+\" unless prepend=0 is specified.  
+\" Duplicate values are always eliminated, 
+\" since this function calls
+\" .B AppendENVPath
+\" or
+\" .B PrependENVPath
+\" depending on the
+\" .I prepend
+\" argument.  See those functions for more details.
+
+\" Examples:
+
+\" .ES
+\" # Prepend a path to the shell PATH.
+\" env.MergeShellPaths({'PATH':'/usr/local/bin'} )
+\" # Append two dirs to the shell INCLUDE.
+\" env.MergeShellPaths({'INCLUDE':['c:/inc1', 'c:/inc2']}, prepend=0 )
+
+.EE
+
+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.TP
+.RI 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
+.B 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
+.RI 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
+.RI 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
+.RI env.ParseConfig( command ", [" function ", " unique ])
+Calls the specified
+.I function
+to modify the environment as specified by the output of
+.I command .
+The default
+.I function
+is
+.BR env.MergeFlags (),
+which expects the output of a typical
+.I *-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
+.RI env.ParseDepends( filename ", [" must_exist ", " only_one ])
+Parses the contents of the specified
+.I filename
+as a list of dependencies in the style of
+.BR 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
+.I SConscript
+file which calls the
+.B ParseDepends
+function.
+
+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.TP
+.RI 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
+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
+.B SourceCode
+function.
+
+This function is deprecated.  For details, see the entry for the
+.B 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 )
+Returns a callable object
+that can be used to initialize
+a construction environment using the
+platform keyword of the Environment() method.
+
+Example:
+
+.ES
+env = Environment(platform = Platform('win32'))
+.EE
+.TP
+.RI env.Platform( string )
+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 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
+.B $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
+.RI Precious( target ", ...)"
+.TP
+.RI 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
+.RI 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
+.RI 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
+
+The above exmaple will print:
+
+.ES
+before: /biz:/foo
+after: /foo/bar:/foo:/biz
+.EE
+
+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.TP
+.RI 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
+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
+.B SourceCode
+function:
+
+This function is deprecated.  For details, see the entry for the
+.B 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
+.RI 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
+.RI 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
+.B Local()
+method.
+
+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.TP
+.RI Requires( target ", " prerequisite )
+.TP
+.RI 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
+.RI 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
+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
+.B SourceCode
+function.
+
+This function is deprecated.  For details, see the entry for the
+.B 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
+.I 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 ])
+'\" .RI SConscript( scripts ", [" exports ", " variant_dir ", " src_dir ", " duplicate ])
+.TP
+.RI env.SConscript( scripts ", [" exports ", " variant_dir ", " duplicate ])
+'\" .RI env.SConscript( scripts ", [" exports ", " variant_dir ", " src_dir ", " duplicate ])
+.TP
+.RI SConscript(dirs= subdirs ", [name=" script ", " exports ", " variant_dir ", " duplicate ])
+'\" .RI SConscript(dirs= subdirs ", [name=" script ", " exports ", " variant_dir ", " src_dir ", " duplicate ])
+.TP
+.RI env.SConscript(dirs= subdirs ", [name=" script ", " exports ", " variant_dir ", " duplicate ])
+'\" .RI env.SConscript(dirs= subdirs ", [name=" script ", " exports ", " variant_dir ", " src_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
+
+The second way you can call
+.BR SConscript ()
+is to specify a list of (sub)directory names
+as a
+.RI 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
+.RI 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
+
+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.
+'\"If multiple dirs are provided, each script gets a fresh export.
+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
+
+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
+'\" .IR src_dir and
+.I duplicate
+'\" arguments are ignored.)
+argument is ignored.)
+The
+.I variant_dir
+'\" and
+'\" .I src_dir
+'\" arguments are interpreted relative to the directory of the calling
+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,
+'\" but
+'\" .IR src_dir " is not,"
+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
+is equivalent to
+.ES
+VariantDir('build', 'src')
+SConscript('build/SConscript')
+.EE
+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
+is equivalent to
+.ES
+VariantDir('build', '.')
+SConscript('build/SConscript')
+.EE
+
+'\" If
+'\" .IR variant_dir " and"
+'\" .IR src_dir " are both present,"
+'\" xxxxx everything is in a state of confusion.
+'\" .ES
+'\" SConscript(dirs = 'src', variant_dir = 'build', src_dir = '.')
+'\" runs src/SConscript in build/src, but
+'\" SConscript(dirs = 'lib', variant_dir = 'build', src_dir = 'src')
+'\" runs lib/SConscript (in lib!).  However,
+'\" SConscript(dirs = 'src', variant_dir = 'build', src_dir = 'src')
+'\" runs src/SConscript in build.  Moreover,
+'\" SConscript(dirs = 'src/lib', variant_dir = 'build', src_dir = 'src')
+'\" runs src/lib/SConscript in build/lib.  Moreover,
+'\" SConscript(dirs = 'build/src/lib', variant_dir = 'build', src_dir = 'src')
+'\" can't find build/src/lib/SConscript, even though it ought to exist.
+'\" .EE
+'\" is equivalent to
+'\" .ES
+'\" ????????????????
+'\" .EE
+'\" and what about this alternative?
+'\"TODO??? SConscript('build/SConscript', src_dir='src')
+
+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
+.RI 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
+.RI 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
+.RI 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
+.RI 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
+
+.IP
+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
+.RI 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
+.RI 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
+.B 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
+.B 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
+'\"env.SourceCode('.', env.Subversion('file:///usr/local/Subversion'))
+
+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.TP
+.RI 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 ,
+.BR $SOURCE
+and
+.BR $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 Subversion( repository ", " module )
+'\"A factory function that
+'\"returns a Builder object
+'\"to be used to fetch source files
+'\"from the specified Subversion
+'\".IR repository .
+'\"The returned Builder
+'\"is intended to be passed to the
+'\".B 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.
+'\"
+'\"This function is deprecated.  For details, see the entry for the
+'\".B SourceCode
+'\"function.
+'\"
+'\"Example:
+'\"
+'\".ES
+'\"# Will fetch foo/bar/src.c
+'\"# from /usr/local/Subversion/foo/bar/src.c.
+'\"env.SourceCode('.', env.Subversion('file:///usr/local/Subversion'))
+'\"
+'\"# Will fetch bar/src.c
+'\"# from /usr/local/Subversion/foo/bar/src.c.
+'\"env.SourceCode('.', env.Subversion('file:///usr/local/Subversion', 'foo'))
+'\"
+'\"# Will fetch src.c
+'\"# from /usr/local/Subversion/foo/bar/src.c.
+'\"env.SourceCode('.', env.Subversion('file:///usr/local/Subversion', 'foo/bar'))
+'\".EE
+
+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.TP
+.RI SourceSignatures( type )
+.TP
+.RI 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
+.RI 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
+.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
+.RI 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" ;
+.BR "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
+.BR "" ( "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 ])
+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
+.B 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
+.TP
+.RI env.Tool( string [, toolpath ", " **kw ])
+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
+.B generate()
+method.
+
+.ES
+env.Tool('gcc')
+env.Tool('opengl', toolpath = ['build/tools'])
+.EE
+
+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.TP
+.RI Value( value ", [" built_value ])
+.TP
+.RI 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
+.BR str( value )
+changes between SCons runs, any targets depending on
+.BR 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
+.RI 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
+.IR 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 .
+'\"TODO: Can the above restrictions be clarified or relaxed?
+'\"TODO: The latter restriction is clearly not completely right;
+'\"TODO: src_dir = '.' works fine with a build dir under it.
+
+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
+.IR --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
+.I duplicate
+argument to 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
+.IR 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
+.I variant_dir ,
+regardless of the value of
+.IR 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
+.RI env.WhereIs( program ", [" path  ", " pathext ", " reject ])
+
+Searches for the specified executable
+.I program,
+returning the full path name to the program
+if it is found,
+and returning None if not.
+Searches the specified
+.I path,
+the value of the calling environment's PATH
+(env['ENV']['PATH']),
+or the user's current external PATH
+(os.environ['PATH'])
+by default.
+On Windows systems, searches for executable
+programs with any of the file extensions
+listed in the specified
+.I pathext,
+the calling environment's PATHEXT
+(env['ENV']['PATHEXT'])
+or the user's current PATHEXT
+(os.environ['PATHEXT'])
+by default.
+Will not select any
+path name or names
+in the specified
+.I reject
+list, if any.
+
+.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 $ARCOM (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 $ASCOM (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 $ASFLAGS and $CPPFLAGS 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 $ASPPCOM (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 $ASFLAGS.
+
+.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 $BIBTEXCOM (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 $BITKEEPERCOM
+(the command line) is displayed.
+
+.IP BITKEEPERGET
+The command ($BITKEEPER) 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 $CFLAGS, $CCFLAGS and
+$CPPFLAGS 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 $CCCOM (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 $PCH 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 $PDB 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 $CCPDBFLAGS 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 $CCPDBFLAGS 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 $_CPPINCFLAGS. 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 $_CPPDEFFLAGS is created
+by appending $CPPDEFPREFIX and $CPPDEFSUFFIX
+to the beginning and end
+of each definition in $CPPDEFINES.
+
+.IP CPPDEFINES
+A platform independent specification of C preprocessor definitions.
+The definitions will be added to command lines
+through the automatically-generated
+$_CPPDEFFLAGS construction variable (see above),
+which is constructed according to
+the type of value of $CPPDEFINES:
+
+If $CPPDEFINES is a string,
+the values of the
+$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 $CPPDEFINES is a list,
+the values of the
+$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 $CPPDEFINES is a dictionary,
+the values of the
+$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 $CPPDEFINES construction variable
+when the $_CPPDEFFLAGS 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 $CPPDEFINES construction variable
+when the $_CPPDEFFLAGS 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 $CCCOM,
+$SHCCCOM,
+$CXXCOM and
+$SHCXXCOM command lines,
+but also the $FORTRANPPCOM,
+$SHFORTRANPPCOM,
+$F77PPCOM and
+$SHF77PPCOM command lines
+used to compile a Fortran source file,
+and the $ASPPCOM 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 $CPPPATH.
+See $_CPPINCFLAGS, 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 $_CPPINCFLAGS is created
+by appending $INCPREFIX and $INCSUFFIX
+to the beginning and end
+of each directory in $CPPPATH.
+
+.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
+$_CPPINCFLAGS
+construction variable,
+which is constructed by
+appending the values of the
+$INCPREFIX and $INCSUFFIX
+construction variables
+to the beginning and end
+of each directory in $CPPPATH.
+Any command lines you define that need
+the CPPPATH directory list should
+include $_CPPINCFLAGS:
+
+.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 $CVSCOM
+(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
+$CVSFLAGS 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 $CXXFLAGS and
+$CPPFLAGS 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 $CXXCOM (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 $CCFLAGS,
+so that setting $CCFLAGS affects both C and C++ compilation.
+If you want to add C++-specific flags,
+you must set or override the value of $CXXFLAGS.
+
+.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 $DVIPDFCOM (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
+$ENV 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 $FORTRAN variable,
+which specifies the default Fortran compiler
+for all Fortran versions.
+You only need to set $F77 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 $F77COM if you need to use a specific
+command line for Fortran 77 files.
+You should normally set the $FORTRANCOM 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 $F77COM or $FORTRANCOM
+(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 $F77PATH.
+See
+$_F77INCFLAGS
+below,
+for the variable that expands to those options.
+You only need to set $F77FLAGS if you need to define specific
+user options for Fortran 77 files.
+You should normally set the $FORTRANFLAGS 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 $_F77INCFLAGS is created
+by appending $INCPREFIX and $INCSUFFIX
+to the beginning and end
+of each directory in $F77PATH.
+
+.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 $F77FLAGS because the result will be non-portable
+and the directories will not be searched by the dependency scanner. Note:
+directory names in $F77PATH 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 $F77PATH if you need to define a specific
+include path for Fortran 77 files.
+You should normally set the $FORTRANPATH 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
+$_F77INCFLAGS
+construction variable,
+which is constructed by
+appending the values of the
+$INCPREFIX and $INCSUFFIX
+construction variables
+to the beginning and end
+of each directory in $F77PATH.
+Any command lines you define that need
+the F77PATH directory list should
+include $_F77INCFLAGS:
+
+.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 $F77FLAGS and $CPPFLAGS construction variables
+are included on this command line.
+You only need to set $F77PPCOM if you need to use a specific
+C-preprocessor command line for Fortran 77 files.
+You should normally set the $FORTRANPPCOM 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 $F77PPCOM or $FORTRANPPCOM
+(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 $FORTRAN variable,
+which specifies the default Fortran compiler
+for all Fortran versions.
+You only need to set $F90 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 $F90COM if you need to use a specific
+command line for Fortran 90 files.
+You should normally set the $FORTRANCOM 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 $F90COM or $FORTRANCOM
+(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 $F90PATH.
+See
+$_F90INCFLAGS
+below,
+for the variable that expands to those options.
+You only need to set $F90FLAGS if you need to define specific
+user options for Fortran 90 files.
+You should normally set the $FORTRANFLAGS 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 $_F90INCFLAGS is created
+by appending $INCPREFIX and $INCSUFFIX
+to the beginning and end
+of each directory in $F90PATH.
+
+.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 $F90FLAGS because the result will be non-portable
+and the directories will not be searched by the dependency scanner. Note:
+directory names in $F90PATH 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 $F90PATH if you need to define a specific
+include path for Fortran 90 files.
+You should normally set the $FORTRANPATH 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
+$_F90INCFLAGS
+construction variable,
+which is constructed by
+appending the values of the
+$INCPREFIX and $INCSUFFIX
+construction variables
+to the beginning and end
+of each directory in $F90PATH.
+Any command lines you define that need
+the F90PATH directory list should
+include $_F90INCFLAGS:
+
+.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 $F90FLAGS and $CPPFLAGS construction variables
+are included on this command line.
+You only need to set $F90PPCOM if you need to use a specific
+C-preprocessor command line for Fortran 90 files.
+You should normally set the $FORTRANPPCOM 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 $F90PPCOM or $FORTRANPPCOM
+(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 $FORTRAN variable,
+which specifies the default Fortran compiler
+for all Fortran versions.
+You only need to set $F95 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 $F95COM if you need to use a specific
+command line for Fortran 95 files.
+You should normally set the $FORTRANCOM 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 $F95COM or $FORTRANCOM
+(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 $F95PATH.
+See
+$_F95INCFLAGS
+below,
+for the variable that expands to those options.
+You only need to set $F95FLAGS if you need to define specific
+user options for Fortran 95 files.
+You should normally set the $FORTRANFLAGS 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 $_F95INCFLAGS is created
+by appending $INCPREFIX and $INCSUFFIX
+to the beginning and end
+of each directory in $F95PATH.
+
+.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 $F95FLAGS because the result will be non-portable
+and the directories will not be searched by the dependency scanner. Note:
+directory names in $F95PATH 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 $F95PATH if you need to define a specific
+include path for Fortran 95 files.
+You should normally set the $FORTRANPATH 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
+$_F95INCFLAGS
+construction variable,
+which is constructed by
+appending the values of the
+$INCPREFIX and $INCSUFFIX
+construction variables
+to the beginning and end
+of each directory in $F95PATH.
+Any command lines you define that need
+the F95PATH directory list should
+include $_F95INCFLAGS:
+
+.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 $F95FLAGS and $CPPFLAGS construction variables
+are included on this command line.
+You only need to set $F95PPCOM if you need to use a specific
+C-preprocessor command line for Fortran 95 files.
+You should normally set the $FORTRANPPCOM 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 $F95PPCOM or $FORTRANPPCOM
+(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 $FORTRANFLAGS,
+$CPPFLAGS,
+$_CPPDEFFLAGS,
+$_FORTRANMODFLAG, and
+$_FORTRANINCFLAGS 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 $FORTRANCOM
+(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 $FORTRANPATH.
+See
+$_FORTRANINCFLAGS and $_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 $_FORTRANINCFLAGS is created
+by prepending/appending $INCPREFIX and $INCSUFFIX
+to the beginning and end
+of each directory in $FORTRANPATH.
+
+.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 $FORTRANMODDIR construction variables
+when the $_FORTRANMODFLAG 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 $FORTRANMODDIR construction variables
+when the $_FORTRANMODFLAG 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 $_FORTRANMODFLAG is created
+by prepending/appending $FORTRANMODDIRPREFIX and
+$FORTRANMODDIRSUFFIX
+to the beginning and end of the directory in $FORTRANMODDIR.
+
+.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
+$_FORTRANINCFLAGS
+construction variable,
+which is constructed by
+appending the values of the
+$INCPREFIX and $INCSUFFIX
+construction variables
+to the beginning and end
+of each directory in $FORTRANPATH.
+Any command lines you define that need
+the FORTRANPATH directory list should
+include $_FORTRANINCFLAGS:
+
+.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 $FORTRANFLAGS,
+$CPPFLAGS,
+$_CPPDEFFLAGS,
+$_FORTRANMODFLAG, and
+$_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 $FORTRANPPCOM
+(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
+$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
+$FRAMEWORKPATH.
+
+.IP FRAMEWORKPATHPREFIX
+On Mac OS X with gcc, the prefix to be used for the FRAMEWORKPATH entries.
+(see $FRAMEWORKPATH).
+The default value is
+.BR \-F .
+
+.IP FRAMEWORKPREFIX
+On Mac OS X with gcc,
+the prefix to be used for linking in frameworks
+(see $FRAMEWORKS).
+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 $FRAMEWORKPATH, $FRAMEWORKPATHPREFIX,
+$FRAMEWORKPREFIX and $FRAMEWORKS 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 $GSCOM (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 $TARGET_ARCH.
+
+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
+$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 $CPPPATH and $FORTRANPATH construction variables
+when the $_CPPINCFLAGS and $_FORTRANINCFLAGS
+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 $CPPPATH and $FORTRANPATH construction variables
+when the $_CPPINCFLAGS and $_FORTRANINCFLAGS
+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 $JARCOM (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 $JAVACFLAGS 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 $JAVACCOM (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
+$JAVACLASSPATH 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 $JAVAHFLAGS 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 $JAVAHCOM (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
+$JAVASOURCEPATH 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 $JAVAVERSION 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 $LATEXCOM (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 $LATEXCOM 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 $SHLINK.
+
+.IP LDMODULECOM
+The command line for building loadable modules.
+On Mac OS X, this uses the $LDMODULE,
+$LDMODULEFLAGS and
+$FRAMEWORKSFLAGS variables.
+On other systems, this is the same as $SHLINK.
+
+.IP LDMODULECOMSTR
+The string displayed when building loadable modules.
+If this is not set, then $LDMODULECOM (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 $SHLIBPREFIX.
+
+.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 $LEXCOM (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 $_LIBDIRFLAGS is created
+by appending $LIBDIRPREFIX and $LIBDIRSUFFIX
+to the beginning and end
+of each directory in $LIBPATH.
+
+.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 $LIBPATH construction variable
+when the $_LIBDIRFLAGS 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 $LIBPATH construction variable
+when the $_LIBDIRFLAGS variable is automatically generated.
+
+.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 $_LIBFLAGS is created
+by appending $LIBLINKPREFIX and $LIBLINKSUFFIX
+to the beginning and end
+of each filename in $LIBS.
+
+.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 $LIBS construction variable
+when the $_LIBFLAGS 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 $LIBS construction variable
+when the $_LIBFLAGS 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 $LINKFLAGS or $SHLINKFLAGS
+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
+$_LIBDIRFLAGS
+construction variable,
+which is constructed by
+appending the values of the
+$LIBDIRPREFIX and $LIBDIRSUFFIX
+construction variables
+to the beginning and end
+of each directory in $LIBPATH.
+Any command lines you define that need
+the LIBPATH directory list should
+include $_LIBDIRFLAGS:
+
+.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 $LIBSUFFIXES 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
+$_LIBFLAGS
+construction variable,
+which is constructed by
+appending the values of the
+$LIBLINKPREFIX and $LIBLINKSUFFIX
+construction variables
+to the beginning and end
+of each filename in $LIBS.
+Any command lines you define that need
+the LIBS library list should
+include $_LIBFLAGS:
+
+.ES
+env = Environment(LINKCOM="my_linker $_LIBDIRFLAGS $_LIBFLAGS -o $TARGET $SOURCE")
+.EE
+.IP
+If you add a
+File
+object to the
+$LIBS
+list, the name of that file will be added to
+$_LIBFLAGS,
+and thus the link line, as is, without
+$LIBLINKPREFIX
+or
+$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 $LIBPREFIXES 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 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 $LINKCOM (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 $LIBS,
+nor
+.B \-L
+(or similar) library search path options
+that scons generates automatically from $LIBPATH.
+See
+$_LIBFLAGS
+above,
+for the variable that expands to library-link options,
+and
+$_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 $M4COM (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 $MAKEINDEXCOM (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 $MIDLCOM (the command line) is displayed.
+
+.IP MIDLFLAGS
+General options passed to the Microsoft IDL compiler.
+
+.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 $CHANGED_SOURCES 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
+
+$MSVC_USE_SCRIPT overrides $MSVC_VERSION and $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 $MSVC_VERSION 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
+$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 $MSVS_ARCH to an architecture that's not
+supported for a given Visual Studio version
+will generate an error.
+
+.IP MSVS_PROJECT_BASE_PATH
+The string
+placed in a generated Microsoft Visual Studio solution file
+as the value of the
+.B SccProjectFilePathRelativizedFromConnection0
+and
+.B SccProjectFilePathRelativizedFromConnection1
+attributes of the
+.B GlobalSection(SourceCodeControl)
+section.
+There is no default value.
+
+.IP MSVS_PROJECT_GUID
+The string
+placed in a generated Microsoft Visual Studio project file
+as the value of the
+.B ProjectGUID
+attribute.
+The string is also placed in the
+.B SolutionUniqueID
+attribute of the
+.B GlobalSection(SourceCodeControl)
+section of the Microsoft Visual Studio solution file.
+There is no default value.
+
+.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_LOCAL_PATH
+The path name
+placed in a generated Microsoft Visual Studio project file
+as the value of the
+.B SccLocalPath
+attribute
+if the
+.B MSVS_SCC_PROVIDER
+construction variable is also set.
+The path name is also placed in the
+.B SccLocalPath0
+and
+.B SccLocalPath1
+attributes of the
+.B GlobalSection(SourceCodeControl)
+section of the Microsoft Visual Studio solution file.
+There is no default value.
+
+.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.
+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 SccProvider1
+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 $MSVS_VERSION 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 $MSVC_VERSION instead. If $MSVS_VERSION is set and
+$MSVC_VERSION is not, $MSVC_VERSION will be set automatically to $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
+$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 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 $P4COM (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 $PCHCOM (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 $PDB 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 $CCPDBFLAGS variable;
+see the entry for that variable for specific examples.
+
+.IP PDFCOM
+A deprecated synonym for $DVIPDFCOM.
+
+.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 $PDFLATEXCOM (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 $PDFTEXCOM (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 $PKGINFO)
+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 $PKGCHK)
+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 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 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 $PSCOM (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 '$QTDIR/bin'.
+
+.IP QT_CPPPATH
+The path where the qt header files are installed.
+The default value is '$QTDIR/include'.
+Note: If you set this variable to None,
+the tool won't change the $CPPPATH
+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 $LIBS variable.
+
+.IP QT_LIBPATH
+The path where the qt libraries are installed.
+The default value is '$QTDIR/lib'.
+Note: If you set this variable to None,
+the tool won't change the $LIBPATH
+construction variable.
+
+.IP QT_MOC
+Default value is '$QT_BINPATH/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 $QT_MOCFROMCXXCOM (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 $QT_MOCFROMHCOM (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 '$CXXFILESUFFIX'. Suffix for moc output files, when source is
+a header.
+
+.IP QT_UIC
+Default value is '$QT_BINPATH/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 $QT_UICCOM (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 '$CXXFILESUFFIX'. 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 $CPPPATH,
+$LIBPATH and
+$LIBS may be modified
+and the variables
+PROGEMITTER, 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 builder method
+.B Moc()
+
+.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 $RANLIBCOM (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 $RCCOM (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 $RCINCFLAGS is created
+by appending $RCINCPREFIX and $RCINCSUFFIX
+to the beginning and end
+of each directory in $CPPPATH.
+
+.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 $CPPPATH construction variable
+when the $RCINCFLAGS 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 $CPPPATH construction variable
+when the $RCINCFLAGS 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
+$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 $RCS_COCOM
+(the command line) is displayed.
+
+.IP RCS_COFLAGS
+Options that are passed to the $RCS_CO 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 $REGSVRCOM (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 $RMICFLAGS 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 $RMICCOM (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 $_RPATH is created
+by appending $RPATHPREFIX and $RPATHSUFFIX
+to the beginning and end
+of each directory in $RPATH.
+
+.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 $RPATH construction variable
+when the $_RPATH 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 $RPATH construction variable
+when the $_RPATH 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
+$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
+$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
+$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
+$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 $SCCSCOM
+(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
+$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 $SHCFLAGS,
+$SHCCFLAGS and
+$CPPFLAGS 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 $SHCCCOM (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 $SHCXXFLAGS and
+$CPPFLAGS 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 $SHCXXCOM (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
+$SPAWN
+function.
+See the
+$SPAWN
+construction variable for more information.
+
+.IP SHF77
+The Fortran 77 compiler used for generating shared-library objects.
+You should normally set the $SHFORTRAN variable,
+which specifies the default Fortran compiler
+for all Fortran versions.
+You only need to set $SHF77 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 $SHF77COM if you need to use a specific
+command line for Fortran 77 files.
+You should normally set the $SHFORTRANCOM 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 $SHF77COM or $SHFORTRANCOM
+(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 $SHF77FLAGS if you need to define specific
+user options for Fortran 77 files.
+You should normally set the $SHFORTRANFLAGS 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 $SHF77FLAGS and $CPPFLAGS construction variables
+are included on this command line.
+You only need to set $SHF77PPCOM if you need to use a specific
+C-preprocessor command line for Fortran 77 files.
+You should normally set the $SHFORTRANPPCOM 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 $SHF77PPCOM or $SHFORTRANPPCOM
+(the command line) is displayed.
+
+.IP SHF90
+The Fortran 90 compiler used for generating shared-library objects.
+You should normally set the $SHFORTRAN variable,
+which specifies the default Fortran compiler
+for all Fortran versions.
+You only need to set $SHF90 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 $SHF90COM if you need to use a specific
+command line for Fortran 90 files.
+You should normally set the $SHFORTRANCOM 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 $SHF90COM or $SHFORTRANCOM
+(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 $SHF90FLAGS if you need to define specific
+user options for Fortran 90 files.
+You should normally set the $SHFORTRANFLAGS 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 $SHF90FLAGS and $CPPFLAGS construction variables
+are included on this command line.
+You only need to set $SHF90PPCOM if you need to use a specific
+C-preprocessor command line for Fortran 90 files.
+You should normally set the $SHFORTRANPPCOM 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 $SHF90PPCOM or $SHFORTRANPPCOM
+(the command line) is displayed.
+
+.IP SHF95
+The Fortran 95 compiler used for generating shared-library objects.
+You should normally set the $SHFORTRAN variable,
+which specifies the default Fortran compiler
+for all Fortran versions.
+You only need to set $SHF95 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 $SHF95COM if you need to use a specific
+command line for Fortran 95 files.
+You should normally set the $SHFORTRANCOM 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 $SHF95COM or $SHFORTRANCOM
+(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 $SHF95FLAGS if you need to define specific
+user options for Fortran 95 files.
+You should normally set the $SHFORTRANFLAGS 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 $SHF95FLAGS and $CPPFLAGS construction variables
+are included on this command line.
+You only need to set $SHF95PPCOM if you need to use a specific
+C-preprocessor command line for Fortran 95 files.
+You should normally set the $SHFORTRANPPCOM 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 $SHF95PPCOM or $SHFORTRANPPCOM
+(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 $SHFORTRANCOM
+(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 $SHFORTRANFLAGS and
+$CPPFLAGS 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 $SHFORTRANPPCOM
+(the command line) is displayed.
+
+.IP SHLIBPREFIX
+The prefix used for shared library file names.
+
+.IP SHLIBSUFFIX
+The suffix used for shared library file names.
+
+.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 $SHLINKCOM (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 $LIBS,
+nor
+.B \-L
+(or similar) include search path options
+that scons generates automatically from $LIBPATH.
+See
+$_LIBFLAGS
+above,
+for the variable that expands to library-link options,
+and
+$_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 $CFILESUFFIX.
+By default, this value is used whenever the
+.B \-c++
+option is
+.I not
+specified as part of the
+$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 $SWIGCOM (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 $CFILESUFFIX.
+By default, this value is used whenever the
+.B \-c++
+option is specified as part of the
+$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
+$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 $_SWIGINCFLAGS is created
+by appending $SWIGINCPREFIX and $SWIGINCSUFFIX
+to the beginning and end
+of each directory in $SWIGPATH.
+
+.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 $SWIGPATH construction variable
+when the $_SWIGINCFLAGS 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 $SWIGPATH construction variable
+when the $_SWIGINCFLAGS 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 $CPPPATH.
+
+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
+$_SWIGINCFLAGS
+construction variable,
+which is constructed by
+appending the values of the
+$SWIGINCPREFIX and $SWIGINCSUFFIX
+construction variables
+to the beginning and end
+of each directory in $SWIGPATH.
+Any command lines you define that need
+the SWIGPATH directory list should
+include $_SWIGINCFLAGS:
+
+.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 $TARCOM (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
+$HOST_ARCH, 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 $TEXCOM (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 $WINDOWS_INSERT_DEF.
+
+.IP WIN32DEFPREFIX
+A deprecated synonym for $WINDOWSDEFPREFIX.
+
+.IP WIN32DEFSUFFIX
+A deprecated synonym for $WINDOWSDEFSUFFIX.
+
+.IP WIN32EXPPREFIX
+A deprecated synonym for $WINDOWSEXPSUFFIX.
+
+.IP WIN32EXPSUFFIX
+A deprecated synonym for $WINDOWSEXPSUFFIX.
+
+.IP WINDOWS_INSERT_DEF
+When this is set to true,
+a library build of a Windows shared library
+.RB ( .dll 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\fPfile 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\\\\$SUMMARY"
+.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 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 $YACCCOM (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 $YACCFLAGS 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 $ZIPCOM
+(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
+(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 dependences 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 strings (file names)
+representing the implicit
+dependencies 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('.xyx', 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 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
+
+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
+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 = dir + os.sep + inc
+            if os.path.exists(file):
+                results.append(file)
+                break
+    return 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])
+.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.
+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>
+