summaryrefslogtreecommitdiff
path: root/scons.1
diff options
context:
space:
mode:
authorLuca Falavigna <dktrkranz@debian.org>2014-04-26 11:52:25 +0200
committerLuca Falavigna <dktrkranz@debian.org>2014-04-26 11:52:25 +0200
commit599d55e3999ad29f72fdc3a61d7c4bafc3171452 (patch)
tree9192ad293f1b2bb4d8b57a45660b5f2da69700df /scons.1
parentcc58c8587a4e67f389b00e5d3278fae049ac7399 (diff)
Imported Upstream version 2.3.1upstream/2.3.1
Diffstat (limited to 'scons.1')
-rw-r--r--scons.115895
1 files changed, 0 insertions, 15895 deletions
diff --git a/scons.1 b/scons.1
index 67f777d..e69de29 100644
--- a/scons.1
+++ b/scons.1
@@ -1,15895 +0,0 @@
-.\" Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013 The SCons Foundation
-.\"
-.\" Permission is hereby granted, free of charge, to any person obtaining
-.\" a copy of this software and associated documentation files (the
-.\" "Software"), to deal in the Software without restriction, including
-.\" without limitation the rights to use, copy, modify, merge, publish,
-.\" distribute, sublicense, and/or sell copies of the Software, and to
-.\" permit persons to whom the Software is furnished to do so, subject to
-.\" the following conditions:
-.\"
-.\" The above copyright notice and this permission notice shall be included
-.\" in all copies or substantial portions of the Software.
-.\"
-.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY
-.\" KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
-.\" WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
-.\" NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
-.\" LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
-.\" OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
-.\" WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
-.\"
-.\" doc/man/scons.1 2013/03/03 09:48:35 garyo
-.\"
-.TH SCONS 1 "March 2013"
-.\" ES - Example Start - indents and turns off line fill
-.rm ES
-.de ES
-.RS
-.nf
-..
-.\" EE - Example End - ends indent and turns line fill back on
-.rm EE
-.de EE
-.fi
-.RE
-..
-.SH NAME
-scons \- a software construction tool
-.SH SYNOPSIS
-.B scons
-[
-.IR options ...
-]
-[
-.IR name = val ...
-]
-[
-.IR targets ...
-]
-.SH DESCRIPTION
-
-The
-.B scons
-utility builds software (or other files) by determining which
-component pieces must be rebuilt and executing the necessary commands to
-rebuild them.
-
-By default,
-.B scons
-searches for a file named
-.IR SConstruct ,
-.IR Sconstruct ,
-or
-.I sconstruct
-(in that order) in the current directory and reads its
-configuration from the first file found.
-An alternate file name may be
-specified via the
-.B -f
-option.
-
-The
-.I SConstruct
-file can specify subsidiary
-configuration files using the
-.BR SConscript ()
-function.
-By convention,
-these subsidiary files are named
-.IR SConscript ,
-although any name may be used.
-(Because of this naming convention,
-the term "SConscript files"
-is sometimes used to refer
-generically to all
-.B scons
-configuration files,
-regardless of actual file name.)
-
-The configuration files
-specify the target files to be built, and
-(optionally) the rules to build those targets. Reasonable default
-rules exist for building common software components (executable
-programs, object files, libraries), so that for most software
-projects, only the target and input files need be specified.
-
-Before reading the
-.I SConstruct
-file,
-.B scons
-looks for a directory named
-.I site_scons
-in various system directories (see below) and the directory containing the
-.I SConstruct
-file; for each of those dirs which exists,
-.I site_scons
-is prepended to sys.path,
-the file
-.IR site_scons/site_init.py ,
-is evaluated if it exists,
-and the directory
-.I site_scons/site_tools
-is prepended to the default toolpath if it exists.
-See the
-.I --no-site-dir
-and
-.I --site-dir
-options for more details.
-
-.B scons
-reads and executes the SConscript files as Python scripts,
-so you may use normal Python scripting capabilities
-(such as flow control, data manipulation, and imported Python libraries)
-to handle complicated build situations.
-.BR scons ,
-however, reads and executes all of the SConscript files
-.I before
-it begins building any targets.
-To make this obvious,
-.B scons
-prints the following messages about what it is doing:
-
-.ES
-$ scons foo.out
-scons: Reading SConscript files ...
-scons: done reading SConscript files.
-scons: Building targets ...
-cp foo.in foo.out
-scons: done building targets.
-$
-.EE
-
-The status messages
-(everything except the line that reads "cp foo.in foo.out")
-may be suppressed using the
-.B -Q
-option.
-
-.B scons
-does not automatically propagate
-the external environment used to execute
-.B scons
-to the commands used to build target files.
-This is so that builds will be guaranteed
-repeatable regardless of the environment
-variables set at the time
-.B scons
-is invoked.
-This also means that if the compiler or other commands
-that you want to use to build your target files
-are not in standard system locations,
-.B scons
-will not find them unless
-you explicitly set the PATH
-to include those locations.
-Whenever you create an
-.B scons
-construction environment,
-you can propagate the value of PATH
-from your external environment as follows:
-
-.ES
-import os
-env = Environment(ENV = {'PATH' : os.environ['PATH']})
-.EE
-
-Similarly, if the commands use external environment variables
-like $PATH, $HOME, $JAVA_HOME, $LANG, $SHELL, $TERM, etc.,
-these variables can also be explicitly propagated:
-
-.ES
-import os
-env = Environment(ENV = {'PATH' : os.environ['PATH'],
- 'HOME' : os.environ['HOME']})
-.EE
-
-Or you may explicitly propagate the invoking user's
-complete external environment:
-
-.ES
-import os
-env = Environment(ENV = os.environ)
-.EE
-
-This comes at the expense of making your build
-dependent on the user's environment being set correctly,
-but it may be more convenient for many configurations.
-
-.B scons
-can scan known input files automatically for dependency
-information (for example, #include statements
-in C or C++ files) and will rebuild dependent files appropriately
-whenever any "included" input file changes.
-.B scons
-supports the
-ability to define new scanners for unknown input file types.
-
-.B scons
-knows how to fetch files automatically from
-SCCS or RCS subdirectories
-using SCCS, RCS or BitKeeper.
-
-.B scons
-is normally executed in a top-level directory containing a
-.I SConstruct
-file, optionally specifying
-as command-line arguments
-the target file or files to be built.
-
-By default, the command
-
-.ES
-scons
-.EE
-
-will build all target files in or below the current directory.
-Explicit default targets
-(to be built when no targets are specified on the command line)
-may be defined the SConscript file(s)
-using the
-.B Default()
-function, described below.
-
-Even when
-.B Default()
-targets are specified in the SConscript file(s),
-all target files in or below the current directory
-may be built by explicitly specifying
-the current directory (.)
-as a command-line target:
-
-.ES
-scons .
-.EE
-
-Building all target files,
-including any files outside of the current directory,
-may be specified by supplying a command-line target
-of the root directory (on POSIX systems):
-
-.ES
-scons /
-.EE
-
-or the path name(s) of the volume(s) in which all the targets
-should be built (on Windows systems):
-
-.ES
-scons C:\\ D:\\
-.EE
-
-To build only specific targets,
-supply them as command-line arguments:
-
-.ES
-scons foo bar
-.EE
-
-in which case only the specified targets will be built
-(along with any derived files on which they depend).
-
-Specifying "cleanup" targets in SConscript files is not usually necessary.
-The
-.B -c
-flag removes all files
-necessary to build the specified target:
-
-.ES
-scons -c .
-.EE
-
-to remove all target files, or:
-
-.ES
-scons -c build export
-.EE
-
-to remove target files under build and export.
-Additional files or directories to remove can be specified using the
-.BR Clean()
-function.
-Conversely, targets that would normally be removed by the
-.B -c
-invocation
-can be prevented from being removed by using the
-.BR NoClean ()
-function.
-
-A subset of a hierarchical tree may be built by
-remaining at the top-level directory (where the
-.I SConstruct
-file lives) and specifying the subdirectory as the target to be
-built:
-
-.ES
-scons src/subdir
-.EE
-
-or by changing directory and invoking scons with the
-.B -u
-option, which traverses up the directory
-hierarchy until it finds the
-.I SConstruct
-file, and then builds
-targets relatively to the current subdirectory:
-
-.ES
-cd src/subdir
-scons -u .
-.EE
-
-.B scons
-supports building multiple targets in parallel via a
-.B -j
-option that takes, as its argument, the number
-of simultaneous tasks that may be spawned:
-
-.ES
-scons -j 4
-.EE
-
-builds four targets in parallel, for example.
-
-.B scons
-can maintain a cache of target (derived) files that can
-be shared between multiple builds. When caching is enabled in a
-SConscript file, any target files built by
-.B scons
-will be copied
-to the cache. If an up-to-date target file is found in the cache, it
-will be retrieved from the cache instead of being rebuilt locally.
-Caching behavior may be disabled and controlled in other ways by the
-.BR --cache-force ,
-.BR --cache-disable ,
-and
-.B --cache-show
-command-line options. The
-.B --random
-option is useful to prevent multiple builds
-from trying to update the cache simultaneously.
-
-Values of variables to be passed to the SConscript file(s)
-may be specified on the command line:
-
-.ES
-scons debug=1 .
-.EE
-
-These variables are available in SConscript files
-through the ARGUMENTS dictionary,
-and can be used in the SConscript file(s) to modify
-the build in any way:
-
-.ES
-if ARGUMENTS.get('debug', 0):
- env = Environment(CCFLAGS = '-g')
-else:
- env = Environment()
-.EE
-
-The command-line variable arguments are also available
-in the ARGLIST list,
-indexed by their order on the command line.
-This allows you to process them in order rather than by name,
-if necessary.
-ARGLIST[0] returns a tuple
-containing (argname, argvalue).
-A Python exception is thrown if you
-try to access a list member that
-does not exist.
-
-.B scons
-requires Python version 2.4 or later.
-There should be no other dependencies or requirements to run
-.B scons.
-
-.\" The following paragraph reflects the default tool search orders
-.\" currently in SCons/Tool/__init__.py. If any of those search orders
-.\" change, this documentation should change, too.
-By default,
-.B scons
-knows how to search for available programming tools
-on various systems.
-On Windows systems,
-.B scons
-searches in order for the
-Microsoft Visual C++ tools,
-the MinGW tool chain,
-the Intel compiler tools,
-and the PharLap ETS compiler.
-On OS/2 systems,
-.B scons
-searches in order for the
-OS/2 compiler,
-the GCC tool chain,
-and the Microsoft Visual C++ tools,
-On SGI IRIX, IBM AIX, Hewlett Packard HP-UX, and Sun Solaris systems,
-.B scons
-searches for the native compiler tools
-(MIPSpro, Visual Age, aCC, and Forte tools respectively)
-and the GCC tool chain.
-On all other platforms,
-including POSIX (Linux and UNIX) platforms,
-.B scons
-searches in order
-for the GCC tool chain,
-the Microsoft Visual C++ tools,
-and the Intel compiler tools.
-You may, of course, override these default values
-by appropriate configuration of
-Environment construction variables.
-
-.SH OPTIONS
-In general,
-.B scons
-supports the same command-line options as GNU
-.BR make ,
-and many of those supported by
-.BR cons .
-
-.TP
--b
-Ignored for compatibility with non-GNU versions of
-.BR make.
-
-.TP
--c, --clean, --remove
-Clean up by removing all target files for which a construction
-command is specified.
-Also remove any files or directories associated to the construction command
-using the
-.BR Clean ()
-function.
-Will not remove any targets specified by the
-.BR NoClean ()
-function.
-
-.TP
-.RI --cache-debug= file
-Print debug information about the
-.BR CacheDir ()
-derived-file caching
-to the specified
-.IR file .
-If
-.I file
-is
-.B \-
-(a hyphen),
-the debug information are printed to the standard output.
-The printed messages describe what signature file names are
-being looked for in, retrieved from, or written to the
-.BR CacheDir ()
-directory tree.
-
-.TP
---cache-disable, --no-cache
-Disable the derived-file caching specified by
-.BR CacheDir ().
-.B scons
-will neither retrieve files from the cache
-nor copy files to the cache.
-
-.TP
---cache-force, --cache-populate
-When using
-.BR CacheDir (),
-populate a cache by copying any already-existing, up-to-date
-derived files to the cache,
-in addition to files built by this invocation.
-This is useful to populate a new cache with
-all the current derived files,
-or to add to the cache any derived files
-recently built with caching disabled via the
-.B --cache-disable
-option.
-
-.TP
---cache-show
-When using
-.BR CacheDir ()
-and retrieving a derived file from the cache,
-show the command
-that would have been executed to build the file,
-instead of the usual report,
-"Retrieved `file' from cache."
-This will produce consistent output for build logs,
-regardless of whether a target
-file was rebuilt or retrieved from the cache.
-
-.TP
-.RI --config= mode
-This specifies how the
-.B Configure
-call should use or generate the
-results of configuration tests.
-The option should be specified from
-among the following choices:
-
-.TP
---config=auto
-scons will use its normal dependency mechanisms
-to decide if a test must be rebuilt or not.
-This saves time by not running the same configuration tests
-every time you invoke scons,
-but will overlook changes in system header files
-or external commands (such as compilers)
-if you don't specify those dependecies explicitly.
-This is the default behavior.
-
-.TP
---config=force
-If this option is specified,
-all configuration tests will be re-run
-regardless of whether the
-cached results are out of date.
-This can be used to explicitly
-force the configuration tests to be updated
-in response to an otherwise unconfigured change
-in a system header file or compiler.
-
-.TP
---config=cache
-If this option is specified,
-no configuration tests will be rerun
-and all results will be taken from cache.
-Note that scons will still consider it an error
-if --config=cache is specified
-and a necessary test does not
-yet have any results in the cache.
-
-.TP
-.RI "-C" " directory" ", --directory=" directory
-Change to the specified
-.I directory
-before searching for the
-.IR SConstruct ,
-.IR Sconstruct ,
-or
-.I sconstruct
-file, or doing anything
-else. Multiple
-.B -C
-options are interpreted
-relative to the previous one, and the right-most
-.B -C
-option wins. (This option is nearly
-equivalent to
-.BR "-f directory/SConstruct" ,
-except that it will search for
-.IR SConstruct ,
-.IR Sconstruct ,
-or
-.I sconstruct
-in the specified directory.)
-
-.\" .TP
-.\" -d
-.\" Display dependencies while building target files. Useful for
-.\" figuring out why a specific file is being rebuilt, as well as
-.\" general debugging of the build process.
-
-.TP
--D
-Works exactly the same way as the
-.B -u
-option except for the way default targets are handled.
-When this option is used and no targets are specified on the command line,
-all default targets are built, whether or not they are below the current
-directory.
-
-.TP
-.RI --debug= type
-Debug the build process.
-.I type
-specifies what type of debugging:
-
-.TP
---debug=count
-Print how many objects are created
-of the various classes used internally by SCons
-before and after reading the SConscript files
-and before and after building targets.
-This is not supported when SCons is executed with the Python
-.B -O
-(optimized) option
-or when the SCons modules
-have been compiled with optimization
-(that is, when executing from
-.B *.pyo
-files).
-
-.TP
---debug=duplicate
-Print a line for each unlink/relink (or copy) of a variant file from
-its source file. Includes debugging info for unlinking stale variant
-files, as well as unlinking old targets before building them.
-
-.TP
---debug=dtree
-A synonym for the newer
-.B --tree=derived
-option.
-This will be deprecated in some future release
-and ultimately removed.
-
-.TP
---debug=explain
-Print an explanation of precisely why
-.B scons
-is deciding to (re-)build any targets.
-(Note: this does not print anything
-for targets that are
-.I not
-rebuilt.)
-
-.TP
---debug=findlibs
-Instruct the scanner that searches for libraries
-to print a message about each potential library
-name it is searching for,
-and about the actual libraries it finds.
-
-.TP
---debug=includes
-Print the include tree after each top-level target is built.
-This is generally used to find out what files are included by the sources
-of a given derived file:
-
-.ES
-$ scons --debug=includes foo.o
-.EE
-
-.TP
---debug=memoizer
-Prints a summary of hits and misses using the Memoizer,
-an internal subsystem that counts
-how often SCons uses cached values in memory
-instead of recomputing them each time they're needed.
-
-.TP
---debug=memory
-Prints how much memory SCons uses
-before and after reading the SConscript files
-and before and after building targets.
-
-.TP
---debug=nomemoizer
-A deprecated option preserved for backwards compatibility.
-
-.TP
---debug=objects
-Prints a list of the various objects
-of the various classes used internally by SCons.
-
-.TP
---debug=pdb
-Re-run SCons under the control of the
-.RI pdb
-Python debugger.
-
-.TP
---debug=prepare
-Print a line each time any target (internal or external)
-is prepared for building.
-.B scons
-prints this for each target it considers, even if that
-target is up to date (see also --debug=explain).
-This can help debug problems with targets that aren't being
-built; it shows whether
-.B scons
-is at least considering them or not.
-
-.TP
---debug=presub
-Print the raw command line used to build each target
-before the construction environment variables are substituted.
-Also shows which targets are being built by this command.
-Output looks something like this:
-.ES
-$ scons --debug=presub
-Building myprog.o with action(s):
- $SHCC $SHCFLAGS $SHCCFLAGS $CPPFLAGS $_CPPINCFLAGS -c -o $TARGET $SOURCES
-\&...
-.EE
-
-.TP
---debug=stacktrace
-Prints an internal Python stack trace
-when encountering an otherwise unexplained error.
-
-.TP
---debug=stree
-A synonym for the newer
-.B --tree=all,status
-option.
-This will be deprecated in some future release
-and ultimately removed.
-
-.TP
---debug=time
-Prints various time profiling information:
-the time spent executing each individual build command;
-the total build time (time SCons ran from beginning to end);
-the total time spent reading and executing SConscript files;
-the total time spent SCons itself spend running
-(that is, not counting reading and executing SConscript files);
-and both the total time spent executing all build commands
-and the elapsed wall-clock time spent executing those build commands.
-(When
-.B scons
-is executed without the
-.B -j
-option,
-the elapsed wall-clock time will typically
-be slightly longer than the total time spent
-executing all the build commands,
-due to the SCons processing that takes place
-in between executing each command.
-When
-.B scons
-is executed
-.I with
-the
-.B -j
-option,
-and your build configuration allows good parallelization,
-the elapsed wall-clock time should
-be significantly smaller than the
-total time spent executing all the build commands,
-since multiple build commands and
-intervening SCons processing
-should take place in parallel.)
-
-.TP
---debug=tree
-A synonym for the newer
-.B --tree=all
-option.
-This will be deprecated in some future release
-and ultimately removed.
-
-.TP
-.RI --diskcheck= types
-Enable specific checks for
-whether or not there is a file on disk
-where the SCons configuration expects a directory
-(or vice versa),
-and whether or not RCS or SCCS sources exist
-when searching for source and include files.
-The
-.I types
-argument can be set to:
-.BR all ,
-to enable all checks explicitly
-(the default behavior);
-.BR none ,
-to disable all such checks;
-.BR match ,
-to check that files and directories on disk
-match SCons' expected configuration;
-.BR rcs ,
-to check for the existence of an RCS source
-for any missing source or include files;
-.BR sccs ,
-to check for the existence of an SCCS source
-for any missing source or include files.
-Multiple checks can be specified separated by commas;
-for example,
-.B --diskcheck=sccs,rcs
-would still check for SCCS and RCS sources,
-but disable the check for on-disk matches of files and directories.
-Disabling some or all of these checks
-can provide a performance boost for large configurations,
-or when the configuration will check for files and/or directories
-across networked or shared file systems,
-at the slight increased risk of an incorrect build
-or of not handling errors gracefully
-(if include files really should be
-found in SCCS or RCS, for example,
-or if a file really does exist
-where the SCons configuration expects a directory).
-
-.TP
-.RI --duplicate= ORDER
-There are three ways to duplicate files in a build tree: hard links,
-soft (symbolic) links and copies. The default behaviour of SCons is to
-prefer hard links to soft links to copies. You can specify different
-behaviours with this option.
-.IR ORDER
-must be one of
-.IR hard-soft-copy
-(the default),
-.IR soft-hard-copy ,
-.IR hard-copy ,
-.IR soft-copy
-or
-.IR copy .
-SCons will attempt to duplicate files using
-the mechanisms in the specified order.
-
-.\" .TP
-.\" -e, --environment-overrides
-.\" Variables from the execution environment override construction
-.\" variables from the SConscript files.
-
-.TP
-.RI -f " file" ", --file=" file ", --makefile=" file ", --sconstruct=" file
-Use
-.I file
-as the initial SConscript file.
-Multiple
-.B -f
-options may be specified,
-in which case
-.B scons
-will read all of the specified files.
-
-.TP
--h, --help
-Print a local help message for this build, if one is defined in
-the SConscript file(s), plus a line that describes the
-.B -H
-option for command-line option help. If no local help message
-is defined, prints the standard help message about command-line
-options. Exits after displaying the appropriate message.
-
-.TP
--H, --help-options
-Print the standard help message about command-line options and
-exit.
-
-.TP
--i, --ignore-errors
-Ignore all errors from commands executed to rebuild files.
-
-.TP
-.RI -I " directory" ", --include-dir=" directory
-Specifies a
-.I directory
-to search for
-imported Python modules. If several
-.B -I
-options
-are used, the directories are searched in the order specified.
-
-.TP
---implicit-cache
-Cache implicit dependencies.
-This causes
-.B scons
-to use the implicit (scanned) dependencies
-from the last time it was run
-instead of scanning the files for implicit dependencies.
-This can significantly speed up SCons,
-but with the following limitations:
-.IP
-.B scons
-will not detect changes to implicit dependency search paths
-(e.g.
-.BR CPPPATH ", " LIBPATH )
-that would ordinarily
-cause different versions of same-named files to be used.
-.IP
-.B scons
-will miss changes in the implicit dependencies
-in cases where a new implicit
-dependency is added earlier in the implicit dependency search path
-(e.g.
-.BR CPPPATH ", " LIBPATH )
-than a current implicit dependency with the same name.
-
-.TP
---implicit-deps-changed
-Forces SCons to ignore the cached implicit dependencies. This causes the
-implicit dependencies to be rescanned and recached. This implies
-.BR --implicit-cache .
-
-.TP
---implicit-deps-unchanged
-Force SCons to ignore changes in the implicit dependencies.
-This causes cached implicit dependencies to always be used.
-This implies
-.BR --implicit-cache .
-
-.TP
---interactive
-Starts SCons in interactive mode.
-The SConscript files are read once and a
-.B "scons>>>"
-prompt is printed.
-Targets may now be rebuilt by typing commands at interactive prompt
-without having to re-read the SConscript files
-and re-initialize the dependency graph from scratch.
-
-SCons interactive mode supports the following commands:
-
-.RS 10
-.TP 6
-.BI build "[OPTIONS] [TARGETS] ..."
-Builds the specified
-.I TARGETS
-(and their dependencies)
-with the specified
-SCons command-line
-.IR OPTIONS .
-.B b
-and
-.B scons
-are synonyms.
-
-The following SCons command-line options affect the
-.B build
-command:
-
-.ES
---cache-debug=FILE
---cache-disable, --no-cache
---cache-force, --cache-populate
---cache-show
---debug=TYPE
--i, --ignore-errors
--j N, --jobs=N
--k, --keep-going
--n, --no-exec, --just-print, --dry-run, --recon
--Q
--s, --silent, --quiet
---taskmastertrace=FILE
---tree=OPTIONS
-.EE
-
-.IP "" 6
-Any other SCons command-line options that are specified
-do not cause errors
-but have no effect on the
-.B build
-command
-(mainly because they affect how the SConscript files are read,
-which only happens once at the beginning of interactive mode).
-
-.TP 6
-.BI clean "[OPTIONS] [TARGETS] ..."
-Cleans the specified
-.I TARGETS
-(and their dependencies)
-with the specified options.
-.B c
-is a synonym.
-This command is itself a synonym for
-.B "build --clean"
-
-.TP 6
-.BI exit
-Exits SCons interactive mode.
-You can also exit by terminating input
-(CTRL+D on UNIX or Linux systems,
-CTRL+Z on Windows systems).
-
-.TP 6
-.BI help "[COMMAND]"
-Provides a help message about
-the commands available in SCons interactive mode.
-If
-.I COMMAND
-is specified,
-.B h
-and
-.B ?
-are synonyms.
-
-.TP 6
-.BI shell "[COMMANDLINE]"
-Executes the specified
-.I COMMANDLINE
-in a subshell.
-If no
-.I COMMANDLINE
-is specified,
-executes the interactive command interpreter
-specified in the
-.B SHELL
-environment variable
-(on UNIX and Linux systems)
-or the
-.B COMSPEC
-environment variable
-(on Windows systems).
-.B sh
-and
-.B !
-are synonyms.
-
-.TP 6
-.B version
-Prints SCons version information.
-.RE
-
-.IP
-An empty line repeats the last typed command.
-Command-line editing can be used if the
-.B readline
-module is available.
-
-.ES
-$ scons --interactive
-scons: Reading SConscript files ...
-scons: done reading SConscript files.
-scons>>> build -n prog
-scons>>> exit
-.EE
-
-.TP
-.RI -j " N" ", --jobs=" N
-Specifies the number of jobs (commands) to run simultaneously.
-If there is more than one
-.B -j
-option, the last one is effective.
-.\" ??? If the
-.\" .B -j
-.\" option
-.\" is specified without an argument,
-.\" .B scons
-.\" will not limit the number of
-.\" simultaneous jobs.
-
-.TP
--k, --keep-going
-Continue as much as possible after an error. The target that
-failed and those that depend on it will not be remade, but other
-targets specified on the command line will still be processed.
-
-.\" .TP
-.\" .RI -l " N" ", --load-average=" N ", --max-load=" N
-.\" No new jobs (commands) will be started if
-.\" there are other jobs running and the system load
-.\" average is at least
-.\" .I N
-.\" (a floating-point number).
-
-.\"
-.\" .TP
-.\" --list-derived
-.\" List derived files (targets, dependencies) that would be built,
-.\" but do not build them.
-.\" [XXX This can probably go away with the right
-.\" combination of other options. Revisit this issue.]
-.\"
-.\" .TP
-.\" --list-actions
-.\" List derived files that would be built, with the actions
-.\" (commands) that build them. Does not build the files.
-.\" [XXX This can probably go away with the right
-.\" combination of other options. Revisit this issue.]
-.\"
-.\" .TP
-.\" --list-where
-.\" List derived files that would be built, plus where the file is
-.\" defined (file name and line number). Does not build the files.
-.\" [XXX This can probably go away with the right
-.\" combination of other options. Revisit this issue.]
-
-.TP
--m
-Ignored for compatibility with non-GNU versions of
-.BR make .
-
-.TP
-.RI --max-drift= SECONDS
-Set the maximum expected drift in the modification time of files to
-.IR SECONDS .
-This value determines how long a file must be unmodified
-before its cached content signature
-will be used instead of
-calculating a new content signature (MD5 checksum)
-of the file's contents.
-The default value is 2 days, which means a file must have a
-modification time of at least two days ago in order to have its
-cached content signature used.
-A negative value means to never cache the content
-signature and to ignore the cached value if there already is one. A value
-of 0 means to always use the cached signature,
-no matter how old the file is.
-
-.TP
-.RI --md5-chunksize= KILOBYTES
-Set the block size used to compute MD5 signatures to
-.IR KILOBYTES .
-This value determines the size of the chunks which are read in at once when
-computing MD5 signatures. Files below that size are fully stored in memory
-before performing the signature computation while bigger files are read in
-block-by-block. A huge block-size leads to high memory consumption while a very
-small block-size slows down the build considerably.
-
-The default value is to use a chunk size of 64 kilobytes, which should
-be appropriate for most uses.
-
-.TP
--n, --just-print, --dry-run, --recon
-No execute. Print the commands that would be executed to build
-any out-of-date target files, but do not execute the commands.
-
-.TP
-.RI --no-site-dir
-Prevents the automatic addition of the standard
-.I site_scons
-dirs to
-.IR sys.path .
-Also prevents loading the
-.I site_scons/site_init.py
-modules if they exist, and prevents adding their
-.I site_scons/site_tools
-dirs to the toolpath.
-
-.\" .TP
-.\" .RI -o " file" ", --old-file=" file ", --assume-old=" file
-.\" Do not rebuild
-.\" .IR file ,
-.\" and do
-.\" not rebuild anything due to changes in the contents of
-.\" .IR file .
-.\" .TP
-.\" .RI --override " file"
-.\" Read values to override specific build environment variables
-.\" from the specified
-.\" .IR file .
-.\" .TP
-.\" -p
-.\" Print the data base (construction environments,
-.\" Builder and Scanner objects) that are defined
-.\" after reading the SConscript files.
-.\" After printing, a normal build is performed
-.\" as usual, as specified by other command-line options.
-.\" This also prints version information
-.\" printed by the
-.\" .B -v
-.\" option.
-.\"
-.\" To print the database without performing a build do:
-.\"
-.\" .ES
-.\" scons -p -q
-.\" .EE
-
-.TP
-.RI --profile= file
-Run SCons under the Python profiler
-and save the results in the specified
-.IR file .
-The results may be analyzed using the Python
-pstats module.
-
-.TP
--q, --question
-Do not run any commands, or print anything. Just return an exit
-status that is zero if the specified targets are already up to
-date, non-zero otherwise.
-.TP
--Q
-Quiets SCons status messages about
-reading SConscript files,
-building targets
-and entering directories.
-Commands that are executed
-to rebuild target files are still printed.
-
-.\" .TP
-.\" -r, -R, --no-builtin-rules, --no-builtin-variables
-.\" Clear the default construction variables. Construction
-.\" environments that are created will be completely empty.
-
-.TP
---random
-Build dependencies in a random order. This is useful when
-building multiple trees simultaneously with caching enabled,
-to prevent multiple builds from simultaneously trying to build
-or retrieve the same target files.
-
-.TP
--s, --silent, --quiet
-Silent. Do not print commands that are executed to rebuild
-target files.
-Also suppresses SCons status messages.
-
-.TP
--S, --no-keep-going, --stop
-Ignored for compatibility with GNU
-.BR make .
-
-.TP
-.RI --site-dir= dir
-Uses the named dir as the site dir rather than the default
-.I site_scons
-dirs. This dir will get prepended to
-.IR sys.path ,
-the module
-.IR dir /site_init.py
-will get loaded if it exists, and
-.IR dir /site_tools
-will get added to the default toolpath.
-
-The default set of
-.I site_scons
-dirs used when
-.I --site-dir
-is not specified depends on the system platform, as follows. Note
-that the directories are examined in the order given, from most
-generic to most specific, so the last-executed site_init.py file is
-the most specific one (which gives it the chance to override
-everything else), and the dirs are prepended to the paths, again so
-the last dir examined comes first in the resulting path.
-
-.IP "Windows:"
-.nf
- %ALLUSERSPROFILE/Application Data/scons/site_scons
- %USERPROFILE%/Local Settings/Application Data/scons/site_scons
- %APPDATA%/scons/site_scons
- %HOME%/.scons/site_scons
- ./site_scons
-.fi
-.IP "Mac OS X:"
-.nf
- /Library/Application Support/SCons/site_scons
- /opt/local/share/scons/site_scons (for MacPorts)
- /sw/share/scons/site_scons (for Fink)
- $HOME/Library/Application Support/SCons/site_scons
- $HOME/.scons/site_scons
- ./site_scons
-.fi
-.IP "Solaris:"
-.nf
- /opt/sfw/scons/site_scons
- /usr/share/scons/site_scons
- $HOME/.scons/site_scons
- ./site_scons
-.fi
-.IP "Linux, HPUX, and other Posix-like systems:"
-.nf
- /usr/share/scons/site_scons
- $HOME/.scons/site_scons
- ./site_scons
-.fi
-
-.TP
-.RI --stack-size= KILOBYTES
-Set the size stack used to run threads to
-.IR KILOBYTES .
-This value determines the stack size of the threads used to run jobs.
-These are the threads that execute the actions of the builders for the
-nodes that are out-of-date.
-Note that this option has no effect unless the
-.B num_jobs
-option, which corresponds to -j and --jobs, is larger than one. Using
-a stack size that is too small may cause stack overflow errors. This
-usually shows up as segmentation faults that cause scons to abort
-before building anything. Using a stack size that is too large will
-cause scons to use more memory than required and may slow down the entire
-build process.
-
-The default value is to use a stack size of 256 kilobytes, which should
-be appropriate for most uses. You should not need to increase this value
-unless you encounter stack overflow errors.
-
-.TP
--t, --touch
-Ignored for compatibility with GNU
-.BR make .
-(Touching a file to make it
-appear up-to-date is unnecessary when using
-.BR scons .)
-
-.TP
-.RI --taskmastertrace= file
-Prints trace information to the specified
-.I file
-about how the internal Taskmaster object
-evaluates and controls the order in which Nodes are built.
-A file name of
-.B -
-may be used to specify the standard output.
-
-.TP
-.RI -tree= options
-Prints a tree of the dependencies
-after each top-level target is built.
-This prints out some or all of the tree,
-in various formats,
-depending on the
-.I options
-specified:
-
-.TP
---tree=all
-Print the entire dependency tree
-after each top-level target is built.
-This prints out the complete dependency tree,
-including implicit dependencies and ignored dependencies.
-
-.TP
---tree=derived
-Restricts the tree output to only derived (target) files,
-not source files.
-
-.TP
---tree=status
-Prints status information for each displayed node.
-
-.TP
---tree=prune
-Prunes the tree to avoid repeating dependency information
-for nodes that have already been displayed.
-Any node that has already been displayed
-will have its name printed in
-.BR "[square brackets]" ,
-as an indication that the dependencies
-for that node can be found by searching
-for the relevant output higher up in the tree.
-
-.IP
-Multiple options may be specified,
-separated by commas:
-
-.ES
-# Prints only derived files, with status information:
-scons --tree=derived,status
-
-# Prints all dependencies of target, with status information
-# and pruning dependencies of already-visited Nodes:
-scons --tree=all,prune,status target
-.EE
-
-.TP
--u, --up, --search-up
-Walks up the directory structure until an
-.I SConstruct ,
-.I Sconstruct
-or
-.I sconstruct
-file is found, and uses that
-as the top of the directory tree.
-If no targets are specified on the command line,
-only targets at or below the
-current directory will be built.
-
-.TP
--U
-Works exactly the same way as the
-.B -u
-option except for the way default targets are handled.
-When this option is used and no targets are specified on the command line,
-all default targets that are defined in the SConscript(s) in the current
-directory are built, regardless of what directory the resultant targets end
-up in.
-
-.TP
--v, --version
-Print the
-.B scons
-version, copyright information,
-list of authors, and any other relevant information.
-Then exit.
-
-.TP
--w, --print-directory
-Print a message containing the working directory before and
-after other processing.
-
-.TP
---no-print-directory
-Turn off -w, even if it was turned on implicitly.
-
-.TP
-.RI --warn= type ", --warn=no-" type
-Enable or disable warnings.
-.I type
-specifies the type of warnings to be enabled or disabled:
-
-.TP
---warn=all, --warn=no-all
-Enables or disables all warnings.
-
-.TP
---warn=cache-write-error, --warn=no-cache-write-error
-Enables or disables warnings about errors trying to
-write a copy of a built file to a specified
-.BR CacheDir ().
-These warnings are disabled by default.
-
-.TP
---warn=corrupt-sconsign, --warn=no-corrupt-sconsign
-Enables or disables warnings about unfamiliar signature data in
-.B .sconsign
-files.
-These warnings are enabled by default.
-
-.TP
---warn=dependency, --warn=no-dependency
-Enables or disables warnings about dependencies.
-These warnings are disabled by default.
-
-.TP
---warn=deprecated, --warn=no-deprecated
-Enables or disables all warnings about use of
-currently deprecated features.
-These warnings are enabled by default.
-Note that the
-.B --warn=no-deprecated
-option does not disable warnings about absolutely all deprecated features.
-Warnings for some deprecated features that have already been through
-several releases with deprecation warnings
-may be mandatory for a release or two
-before they are officially no longer supported by SCons.
-Warnings for some specific deprecated features
-may be enabled or disabled individually;
-see below.
-
-.RS
-.TP
---warn=deprecated-copy, --warn=no-deprecated-copy
-Enables or disables warnings about use of the deprecated
-.B env.Copy()
-method.
-
-.TP
---warn=deprecated-source-signatures, --warn=no-deprecated-source-signatures
-Enables or disables warnings about use of the deprecated
-.B SourceSignatures()
-function or
-.B env.SourceSignatures()
-method.
-
-.TP
---warn=deprecated-target-signatures, --warn=no-deprecated-target-signatures
-Enables or disables warnings about use of the deprecated
-.B TargetSignatures()
-function or
-.B env.TargetSignatures()
-method.
-.RE
-
-.TP
---warn=duplicate-environment, --warn=no-duplicate-environment
-Enables or disables warnings about attempts to specify a build
-of a target with two different construction environments
-that use the same action.
-These warnings are enabled by default.
-
-.TP
---warn=fortran-cxx-mix, --warn=no-fortran-cxx-mix
-Enables or disables the specific warning about linking
-Fortran and C++ object files in a single executable,
-which can yield unpredictable behavior with some compilers.
-
-.TP
---warn=future-deprecated, --warn=no-future-deprecated
-Enables or disables warnings about features
-that will be deprecated in the future.
-These warnings are disabled by default.
-Enabling this warning is especially
-recommended for projects that redistribute
-SCons configurations for other users to build,
-so that the project can be warned as soon as possible
-about to-be-deprecated features
-that may require changes to the configuration.
-
-.TP
---warn=link, --warn=no-link
-Enables or disables warnings about link steps.
-
-.TP
---warn=misleading-keywords, --warn=no-misleading-keywords
-Enables or disables warnings about use of the misspelled keywords
-.B targets
-and
-.B sources
-when calling Builders.
-(Note the last
-.B s
-characters, the correct spellings are
-.B target
-and
-.B source.)
-These warnings are enabled by default.
-
-.TP
---warn=missing-sconscript, --warn=no-missing-sconscript
-Enables or disables warnings about missing SConscript files.
-These warnings are enabled by default.
-
-.TP
---warn=no-md5-module, --warn=no-no-md5-module
-Enables or disables warnings about the version of Python
-not having an MD5 checksum module available.
-These warnings are enabled by default.
-
-.TP
---warn=no-metaclass-support, --warn=no-no-metaclass-support
-Enables or disables warnings about the version of Python
-not supporting metaclasses when the
-.B --debug=memoizer
-option is used.
-These warnings are enabled by default.
-
-.TP
---warn=no-object-count, --warn=no-no-object-count
-Enables or disables warnings about the
-.B --debug=object
-feature not working when
-.B scons
-is run with the python
-.B \-O
-option or from optimized Python (.pyo) modules.
-
-.TP
---warn=no-parallel-support, --warn=no-no-parallel-support
-Enables or disables warnings about the version of Python
-not being able to support parallel builds when the
-.B -j
-option is used.
-These warnings are enabled by default.
-
-.TP
---warn=python-version, --warn=no-python-version
-Enables or disables the warning about running
-SCons with a deprecated version of Python.
-These warnings are enabled by default.
-
-.TP
---warn=reserved-variable, --warn=no-reserved-variable
-Enables or disables warnings about attempts to set the
-reserved construction variable names
-.BR CHANGED_SOURCES ,
-.BR CHANGED_TARGETS ,
-.BR TARGET ,
-.BR TARGETS ,
-.BR SOURCE ,
-.BR SOURCES ,
-.BR UNCHANGED_SOURCES
-or
-.BR UNCHANGED_TARGETS .
-These warnings are disabled by default.
-
-.TP
---warn=stack-size, --warn=no-stack-size
-Enables or disables warnings about requests to set the stack size
-that could not be honored.
-These warnings are enabled by default.
-
-.\" .TP
-.\" .RI --write-filenames= file
-.\" Write all filenames considered into
-.\" .IR file .
-.\"
-.\" .TP
-.\" .RI -W " file" ", --what-if=" file ", --new-file=" file ", --assume-new=" file
-.\" Pretend that the target
-.\" .I file
-.\" has been
-.\" modified. When used with the
-.\" .B -n
-.\" option, this
-.\" show you what would be rebuilt if you were to modify that file.
-.\" Without
-.\" .B -n
-.\" ... what? XXX
-.\"
-.\" .TP
-.\" --warn-undefined-variables
-.\" Warn when an undefined variable is referenced.
-
-.TP
-.RI -Y " repository" ", --repository=" repository ", --srcdir=" repository
-Search the specified repository for any input and target
-files not found in the local directory hierarchy. Multiple
-.B -Y
-options may be specified, in which case the
-repositories are searched in the order specified.
-
-.SH CONFIGURATION FILE REFERENCE
-.\" .SS Python Basics
-.\" XXX Adding this in the future would be a help.
-.SS Construction Environments
-A construction environment is the basic means by which the SConscript
-files communicate build information to
-.BR scons .
-A new construction environment is created using the
-.B Environment
-function:
-
-.ES
-env = Environment()
-.EE
-
-Variables, called
-.I construction
-.IR variables ,
-may be set in a construction environment
-either by specifying them as keywords when the object is created
-or by assigning them a value after the object is created:
-
-.ES
-env = Environment(FOO = 'foo')
-env['BAR'] = 'bar'
-.EE
-
-As a convenience,
-construction variables may also be set or modified by the
-.I parse_flags
-keyword argument, which applies the
-.B ParseFlags
-method (described below) to the argument value
-after all other processing is completed.
-This is useful either if the exact content of the flags is unknown
-(for example, read from a control file)
-or if the flags are distributed to a number of construction variables.
-
-.ES
-env = Environment(parse_flags = '-Iinclude -DEBUG -lm')
-.EE
-
-This example adds 'include' to
-.BR CPPPATH ,
-\&'EBUG' to
-.BR CPPDEFINES ,
-and 'm' to
-.BR LIBS .
-
-By default, a new construction environment is
-initialized with a set of builder methods
-and construction variables that are appropriate
-for the current platform.
-An optional platform keyword argument may be
-used to specify that an environment should
-be initialized for a different platform:
-
-.ES
-env = Environment(platform = 'cygwin')
-env = Environment(platform = 'os2')
-env = Environment(platform = 'posix')
-env = Environment(platform = 'win32')
-.EE
-
-Specifying a platform initializes the appropriate
-construction variables in the environment
-to use and generate file names with prefixes
-and suffixes appropriate for the platform.
-
-Note that the
-.B win32
-platform adds the
-.B SystemDrive
-and
-.B SystemRoot
-variables from the user's external environment
-to the construction environment's
-.B ENV
-dictionary.
-This is so that any executed commands
-that use sockets to connect with other systems
-(such as fetching source files from
-external CVS repository specifications like
-.BR :pserver:anonymous@cvs.sourceforge.net:/cvsroot/scons )
-will work on Windows systems.
-
-The platform argument may be function or callable object,
-in which case the Environment() method
-will call the specified argument to update
-the new construction environment:
-
-.ES
-def my_platform(env):
- env['VAR'] = 'xyzzy'
-
-env = Environment(platform = my_platform)
-.EE
-
-Additionally, a specific set of tools
-with which to initialize the environment
-may be specified as an optional keyword argument:
-
-.ES
-env = Environment(tools = ['msvc', 'lex'])
-.EE
-
-Non-built-in tools may be specified using the toolpath argument:
-
-.ES
-env = Environment(tools = ['default', 'foo'], toolpath = ['tools'])
-.EE
-
-This looks for a tool specification in tools/foo.py (as well as
-using the ordinary default tools for the platform). foo.py should
-have two functions: generate(env, **kw) and exists(env).
-The
-.B generate()
-function
-modifies the passed-in environment
-to set up variables so that the tool
-can be executed;
-it may use any keyword arguments
-that the user supplies (see below)
-to vary its initialization.
-The
-.B exists()
-function should return a true
-value if the tool is available.
-Tools in the toolpath are used before
-any of the built-in ones. For example, adding gcc.py to the toolpath
-would override the built-in gcc tool.
-Also note that the toolpath is
-stored in the environment for use
-by later calls to
-.BR Clone ()
-and
-.BR Tool ()
-methods:
-
-.ES
-base = Environment(toolpath=['custom_path'])
-derived = base.Clone(tools=['custom_tool'])
-derived.CustomBuilder()
-.EE
-
-The elements of the tools list may also
-be functions or callable objects,
-in which case the Environment() method
-will call the specified elements
-to update the new construction environment:
-
-.ES
-def my_tool(env):
- env['XYZZY'] = 'xyzzy'
-
-env = Environment(tools = [my_tool])
-.EE
-
-The individual elements of the tools list
-may also themselves be two-element lists of the form
-.RI ( toolname ", " kw_dict ).
-SCons searches for the
-.I toolname
-specification file as described above, and
-passes
-.IR kw_dict ,
-which must be a dictionary, as keyword arguments to the tool's
-.B generate
-function.
-The
-.B generate
-function can use the arguments to modify the tool's behavior
-by setting up the environment in different ways
-or otherwise changing its initialization.
-
-.ES
-# in tools/my_tool.py:
-def generate(env, **kw):
- # Sets MY_TOOL to the value of keyword argument 'arg1' or 1.
- env['MY_TOOL'] = kw.get('arg1', '1')
-def exists(env):
- return 1
-
-# in SConstruct:
-env = Environment(tools = ['default', ('my_tool', {'arg1': 'abc'})],
- toolpath=['tools'])
-.EE
-
-The tool definition (i.e. my_tool()) can use the PLATFORM variable from
-the environment it receives to customize the tool for different platforms.
-
-If no tool list is specified, then SCons will auto-detect the installed
-tools using the PATH variable in the ENV construction variable and the
-platform name when the Environment is constructed. Changing the PATH
-variable after the Environment is constructed will not cause the tools to
-be redetected.
-
-SCons supports the following tool specifications out of the box:
-
-.ES
-386asm
-aixc++
-aixcc
-aixf77
-aixlink
-ar
-as
-bcc32
-c++
-cc
-cvf
-dmd
-dvipdf
-dvips
-f77
-f90
-f95
-fortran
-g++
-g77
-gas
-gcc
-gfortran
-gnulink
-gs
-hpc++
-hpcc
-hplink
-icc
-icl
-ifl
-ifort
-ilink
-ilink32
-intelc
-jar
-javac
-javah
-latex
-lex
-link
-linkloc
-m4
-masm
-midl
-mingw
-mslib
-mslink
-mssdk
-msvc
-msvs
-mwcc
-mwld
-nasm
-pdflatex
-pdftex
-qt
-rmic
-rpcgen
-sgiar
-sgic++
-sgicc
-sgilink
-sunar
-sunc++
-suncc
-sunf77
-sunf90
-sunf95
-sunlink
-swig
-tar
-tex
-textfile
-tlib
-yacc
-zip
-.EE
-
-Additionally, there is a "tool" named
-.B default
-which configures the
-environment with a default set of tools for the current platform.
-
-On posix and cygwin platforms
-the GNU tools (e.g. gcc) are preferred by SCons,
-on Windows the Microsoft tools (e.g. msvc)
-followed by MinGW are preferred by SCons,
-and in OS/2 the IBM tools (e.g. icc) are preferred by SCons.
-
-.SS Builder Methods
-
-Build rules are specified by calling a construction
-environment's builder methods.
-The arguments to the builder methods are
-.B target
-(a list of targets to be built,
-usually file names)
-and
-.B source
-(a list of sources to be built,
-usually file names).
-
-Because long lists of file names
-can lead to a lot of quoting,
-.B scons
-supplies a
-.B Split()
-global function
-and a same-named environment method
-that split a single string
-into a list, separated on
-strings of white-space characters.
-(These are similar to the split() member function of Python strings
-but work even if the input isn't a string.)
-
-Like all Python arguments,
-the target and source arguments to a builder method
-can be specified either with or without
-the "target" and "source" keywords.
-When the keywords are omitted,
-the target is first,
-followed by the source.
-The following are equivalent examples of calling the Program builder method:
-
-.ES
-env.Program('bar', ['bar.c', 'foo.c'])
-env.Program('bar', Split('bar.c foo.c'))
-env.Program('bar', env.Split('bar.c foo.c'))
-env.Program(source = ['bar.c', 'foo.c'], target = 'bar')
-env.Program(target = 'bar', Split('bar.c foo.c'))
-env.Program(target = 'bar', env.Split('bar.c foo.c'))
-env.Program('bar', source = 'bar.c foo.c'.split())
-.EE
-
-Target and source file names
-that are not absolute path names
-(that is, do not begin with
-.B /
-on POSIX systems
-or
-.B \\
-on Windows systems,
-with or without
-an optional drive letter)
-are interpreted relative to the directory containing the
-.B SConscript
-file being read.
-An initial
-.B #
-(hash mark)
-on a path name means that the rest of the file name
-is interpreted relative to
-the directory containing
-the top-level
-.B SConstruct
-file,
-even if the
-.B #
-is followed by a directory separator character
-(slash or backslash).
-
-Examples:
-
-.ES
-# The comments describing the targets that will be built
-# assume these calls are in a SConscript file in the
-# a subdirectory named "subdir".
-
-# Builds the program "subdir/foo" from "subdir/foo.c":
-env.Program('foo', 'foo.c')
-
-# Builds the program "/tmp/bar" from "subdir/bar.c":
-env.Program('/tmp/bar', 'bar.c')
-
-# An initial '#' or '#/' are equivalent; the following
-# calls build the programs "foo" and "bar" (in the
-# top-level SConstruct directory) from "subdir/foo.c" and
-# "subdir/bar.c", respectively:
-env.Program('#foo', 'foo.c')
-env.Program('#/bar', 'bar.c')
-
-# Builds the program "other/foo" (relative to the top-level
-# SConstruct directory) from "subdir/foo.c":
-env.Program('#other/foo', 'foo.c')
-.EE
-
-When the target shares the same base name
-as the source and only the suffix varies,
-and if the builder method has a suffix defined for the target file type,
-then the target argument may be omitted completely,
-and
-.B scons
-will deduce the target file name from
-the source file name.
-The following examples all build the
-executable program
-.B bar
-(on POSIX systems)
-or
-.B bar.exe
-(on Windows systems)
-from the bar.c source file:
-
-.ES
-env.Program(target = 'bar', source = 'bar.c')
-env.Program('bar', source = 'bar.c')
-env.Program(source = 'bar.c')
-env.Program('bar.c')
-.EE
-
-As a convenience, a
-.B srcdir
-keyword argument may be specified
-when calling a Builder.
-When specified,
-all source file strings that are not absolute paths
-will be interpreted relative to the specified
-.BR srcdir .
-The following example will build the
-.B build/prog
-(or
-.B build/prog.exe
-on Windows)
-program from the files
-.B src/f1.c
-and
-.BR src/f2.c :
-
-.ES
-env.Program('build/prog', ['f1.c', 'f2.c'], srcdir='src')
-.EE
-
-It is possible to override or add construction variables when calling a
-builder method by passing additional keyword arguments.
-These overridden or added
-variables will only be in effect when building the target, so they will not
-affect other parts of the build. For example, if you want to add additional
-libraries for just one program:
-
-.ES
-env.Program('hello', 'hello.c', LIBS=['gl', 'glut'])
-.EE
-
-or generate a shared library with a non-standard suffix:
-
-.ES
-env.SharedLibrary('word', 'word.cpp',
- SHLIBSUFFIX='.ocx',
- LIBSUFFIXES=['.ocx'])
-.EE
-
-(Note that both the $SHLIBSUFFIX and $LIBSUFFIXES variables must be set
-if you want SCons to search automatically
-for dependencies on the non-standard library names;
-see the descriptions of these variables, below, for more information.)
-
-It is also possible to use the
-.I parse_flags
-keyword argument in an override:
-
-.ES
-env = Program('hello', 'hello.c', parse_flags = '-Iinclude -DEBUG -lm')
-.EE
-
-This example adds 'include' to
-.BR CPPPATH ,
-\&'EBUG' to
-.BR CPPDEFINES ,
-and 'm' to
-.BR LIBS .
-
-Although the builder methods defined by
-.B scons
-are, in fact,
-methods of a construction environment object,
-they may also be called without an explicit environment:
-
-.ES
-Program('hello', 'hello.c')
-SharedLibrary('word', 'word.cpp')
-.EE
-
-In this case,
-the methods are called internally using a default construction
-environment that consists of the tools and values that
-.B scons
-has determined are appropriate for the local system.
-
-Builder methods that can be called without an explicit
-environment may be called from custom Python modules that you
-import into an SConscript file by adding the following
-to the Python module:
-
-.ES
-from SCons.Script import *
-.EE
-
-All builder methods return a list-like object
-containing Nodes that
-represent the target or targets that will be built.
-A
-.I Node
-is an internal SCons object
-which represents
-build targets or sources.
-
-The returned Node-list object
-can be passed to other builder methods as source(s)
-or passed to any SCons function or method
-where a filename would normally be accepted.
-For example, if it were necessary
-to add a specific
-.B -D
-flag when compiling one specific object file:
-
-.ES
-bar_obj_list = env.StaticObject('bar.c', CPPDEFINES='-DBAR')
-env.Program(source = ['foo.c', bar_obj_list, 'main.c'])
-.EE
-
-Using a Node in this way
-makes for a more portable build
-by avoiding having to specify
-a platform-specific object suffix
-when calling the Program() builder method.
-
-Note that Builder calls will automatically "flatten"
-the source and target file lists,
-so it's all right to have the bar_obj list
-return by the StaticObject() call
-in the middle of the source file list.
-If you need to manipulate a list of lists returned by Builders
-directly using Python,
-you can either build the list by hand:
-
-.ES
-foo = Object('foo.c')
-bar = Object('bar.c')
-objects = ['begin.o'] + foo + ['middle.o'] + bar + ['end.o']
-for object in objects:
- print str(object)
-.EE
-
-Or you can use the
-.BR Flatten ()
-function supplied by scons
-to create a list containing just the Nodes,
-which may be more convenient:
-
-.ES
-foo = Object('foo.c')
-bar = Object('bar.c')
-objects = Flatten(['begin.o', foo, 'middle.o', bar, 'end.o'])
-for object in objects:
- print str(object)
-.EE
-
-Note also that because Builder calls return
-a list-like object, not an actual Python list,
-you should
-.I not
-use the Python
-.B +=
-operator to append Builder results to a Python list.
-Because the list and the object are different types,
-Python will not update the original list in place,
-but will instead create a new Node-list object
-containing the concatenation of the list
-elements and the Builder results.
-This will cause problems for any other Python variables
-in your SCons configuration
-that still hold on to a reference to the original list.
-Instead, use the Python
-.B .extend()
-method to make sure the list is updated in-place.
-Example:
-
-.ES
-object_files = []
-
-# Do NOT use += as follows:
-#
-# object_files += Object('bar.c')
-#
-# It will not update the object_files list in place.
-#
-# Instead, use the .extend() method:
-object_files.extend(Object('bar.c'))
-
-.EE
-
-The path name for a Node's file may be used
-by passing the Node to the Python-builtin
-.B str()
-function:
-
-.ES
-bar_obj_list = env.StaticObject('bar.c', CPPDEFINES='-DBAR')
-print "The path to bar_obj is:", str(bar_obj_list[0])
-.EE
-
-Note again that because the Builder call returns a list,
-we have to access the first element in the list
-.B (bar_obj_list[0])
-to get at the Node that actually represents
-the object file.
-
-Builder calls support a
-.B chdir
-keyword argument that
-specifies that the Builder's action(s)
-should be executed
-after changing directory.
-If the
-.B chdir
-argument is
-a string or a directory Node,
-scons will change to the specified directory.
-If the
-.B chdir
-is not a string or Node
-and is non-zero,
-then scons will change to the
-target file's directory.
-
-.ES
-# scons will change to the "sub" subdirectory
-# before executing the "cp" command.
-env.Command('sub/dir/foo.out', 'sub/dir/foo.in',
- "cp dir/foo.in dir/foo.out",
- chdir='sub')
-
-# Because chdir is not a string, scons will change to the
-# target's directory ("sub/dir") before executing the
-# "cp" command.
-env.Command('sub/dir/foo.out', 'sub/dir/foo.in',
- "cp foo.in foo.out",
- chdir=1)
-.EE
-
-Note that scons will
-.I not
-automatically modify
-its expansion of
-construction variables like
-.B $TARGET
-and
-.B $SOURCE
-when using the chdir
-keyword argument--that is,
-the expanded file names
-will still be relative to
-the top-level SConstruct directory,
-and consequently incorrect
-relative to the chdir directory.
-If you use the chdir keyword argument,
-you will typically need to supply a different
-command line using
-expansions like
-.B ${TARGET.file}
-and
-.B ${SOURCE.file}
-to use just the filename portion of the
-targets and source.
-
-.B scons
-provides the following builder methods:
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-'\" BEGIN GENERATED BUILDER DESCRIPTIONS
-'\"
-'\" The descriptions below of the various SCons Builders are generated
-'\" from the .xml files that live next to the various Python modules in
-'\" the build enginer library. If you're reading this [gnt]roff file
-'\" with an eye towards patching this man page, you can still submit
-'\" a diff against this text, but it will have to be translated to a
-'\" diff against the underlying .xml file before the patch is actually
-'\" accepted. If you do that yourself, it will make it easier to
-'\" integrate the patch.
-'\"
-'\" BEGIN GENERATED BUILDER DESCRIPTIONS
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.IP CFile()
-.IP env.CFile()
-Builds a C source file given a lex (\fB.l\fP)
-or yacc (\fB.y\fP) input file.
-The suffix specified by the \fB$CFILESUFFIX\fP construction variable
-(\fB.c\fP by default)
-is automatically added to the target
-if it is not already present.
-Example:
-
-.ES
-# builds foo.c
-env.CFile(target = 'foo.c', source = 'foo.l')
-# builds bar.c
-env.CFile(target = 'bar', source = 'bar.y')
-.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.IP Command()
-.IP env.Command()
-The \fBCommand\fP() "Builder" is actually implemented
-as a function that looks like a Builder,
-but actually takes an additional argument of the action
-from which the Builder should be made.
-See the \fBCommand\fP() function description
-for the calling syntax and details.
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.IP CXXFile()
-.IP env.CXXFile()
-Builds a C++ source file given a lex (\fB.ll\fP)
-or yacc (\fB.yy\fP)
-input file.
-The suffix specified by the \fB$CXXFILESUFFIX\fP construction variable
-(\fB.cc\fP by default)
-is automatically added to the target
-if it is not already present.
-Example:
-
-.ES
-# builds foo.cc
-env.CXXFile(target = 'foo.cc', source = 'foo.ll')
-# builds bar.cc
-env.CXXFile(target = 'bar', source = 'bar.yy')
-.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.IP DVI()
-.IP env.DVI()
-Builds a \fB.dvi\fP file
-from a \fB.tex\fP,
-\fB.ltx\fP or \fB.latex\fP input file.
-If the source file suffix is \fB.tex\fP,
-.B scons
-will examine the contents of the file;
-if the string
-.B \\documentclass
-or
-.B \\documentstyle
-is found, the file is assumed to be a LaTeX file and
-the target is built by invoking the \fB$LATEXCOM\fP command line;
-otherwise, the \fB$TEXCOM\fP command line is used.
-If the file is a LaTeX file,
-the
-.BR DVI ()
-builder method will also examine the contents
-of the
-.B .aux
-file and invoke the \fB$BIBTEX\fP command line
-if the string
-.B bibdata
-is found,
-start \fB$MAKEINDEX\fP to generate an index if a
-.B .ind
-file is found
-and will examine the contents
-.B .log
-file and re-run the \fB$LATEXCOM\fP command
-if the log file says it is necessary.
-
-The suffix \fB.dvi\fP
-(hard-coded within TeX itself)
-is automatically added to the target
-if it is not already present.
-Examples:
-
-.ES
-# builds from aaa.tex
-env.DVI(target = 'aaa.dvi', source = 'aaa.tex')
-# builds bbb.dvi
-env.DVI(target = 'bbb', source = 'bbb.ltx')
-# builds from ccc.latex
-env.DVI(target = 'ccc.dvi', source = 'ccc.latex')
-.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.IP Install()
-.IP env.Install()
-Installs one or more source files or directories
-in the specified target,
-which must be a directory.
-The names of the specified source files or directories
-remain the same within the destination directory. The
-sources may be given as a string or as a node returned by
-a builder.
-
-.ES
-env.Install('/usr/local/bin', source = ['foo', 'bar'])
-.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.IP InstallAs()
-.IP env.InstallAs()
-Installs one or more source files or directories
-to specific names,
-allowing changing a file or directory name
-as part of the installation.
-It is an error if the
-target
-and
-source
-arguments list different numbers of files or directories.
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.IP InstallVersionedLib()
-.IP env.InstallVersionedLib()
-Installs a versioned shared library. The \fB$SHLIBVERSION\fP
-construction variable should be defined in the environment
-to confirm the version number in the library name.
-The symlinks appropriate to the architecture will be generated.
-
-.ES
-env.InstallAs(target = '/usr/local/bin/foo',
- source = 'foo_debug')
-env.InstallAs(target = ['../lib/libfoo.a', '../lib/libbar.a'],
- source = ['libFOO.a', 'libBAR.a'])
-.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.IP Jar()
-.IP env.Jar()
-Builds a Java archive (\fB.jar\fP) file
-from the specified list of sources.
-Any directories in the source list
-will be searched for \fB.class\fP files).
-Any \fB.java\fP files in the source list
-will be compiled to \fB.class\fP files
-by calling the \fBJava\fP() Builder.
-
-If the \fB$JARCHDIR\fP value is set, the
-.B jar
-command will change to the specified directory using the
-.B \-C
-option.
-If \fB$JARCHDIR\fP is not set explicitly,
-&SCons; will use the top of any subdirectory tree
-in which Java \fB.class\fP
-were built by the \fBJava\fP() Builder.
-
-If the contents any of the source files begin with the string
-.BR Manifest-Version ,
-the file is assumed to be a manifest
-and is passed to the
-.B jar
-command with the
-.B m
-option set.
-
-.ES
-env.Jar(target = 'foo.jar', source = 'classes')
-
-env.Jar(target = 'bar.jar',
- source = ['bar1.java', 'bar2.java'])
-.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.IP Java()
-.IP env.Java()
-Builds one or more Java class files.
-The sources may be any combination of explicit
-\fB.java\fP files,
-or directory trees which will be scanned
-for \fB.java\fP files.
-
-SCons will parse each source \fB.java\fP file
-to find the classes
-(including inner classes)
-defined within that file,
-and from that figure out the
-target \fB.class\fP files that will be created.
-The class files will be placed underneath
-the specified target directory.
-
-SCons will also search each Java file
-for the Java package name,
-which it assumes can be found on a line
-beginning with the string
-.B package
-in the first column;
-the resulting \fB.class\fP files
-will be placed in a directory reflecting
-the specified package name.
-For example,
-the file
-.B Foo.java
-defining a single public
-.I Foo
-class and
-containing a package name of
-.I sub.dir
-will generate a corresponding
-.B sub/dir/Foo.class
-class file.
-
-Examples:
-
-.ES
-env.Java(target = 'classes', source = 'src')
-env.Java(target = 'classes', source = ['src1', 'src2'])
-env.Java(target = 'classes', source = ['File1.java', 'File2.java'])
-.EE
-.IP
-Java source files can use the native encoding for the underlying OS.
-Since SCons compiles in simple ASCII mode by default,
-the compiler will generate warnings about unmappable characters,
-which may lead to errors as the file is processed further.
-In this case, the user must specify the \fBLANG\fP
-environment variable to tell the compiler what encoding is used.
-For portibility, it's best if the encoding is hard-coded
-so that the compile will work if it is done on a system
-with a different encoding.
-
-.ES
-env = Environment()
-env['ENV']['LANG'] = 'en_GB.UTF-8'
-.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.IP JavaH()
-.IP env.JavaH()
-Builds C header and source files for
-implementing Java native methods.
-The target can be either a directory
-in which the header files will be written,
-or a header file name which
-will contain all of the definitions.
-The source can be the names of \fB.class\fP files,
-the names of \fB.java\fP files
-to be compiled into \fB.class\fP files
-by calling the \fBJava\fP() builder method,
-or the objects returned from the
-.BR Java ()
-builder method.
-
-If the construction variable
-.B $JAVACLASSDIR
-is set, either in the environment
-or in the call to the
-.BR JavaH ()
-builder method itself,
-then the value of the variable
-will be stripped from the
-beginning of any \fB.class\fP file names.
-
-Examples:
-
-.ES
-# builds java_native.h
-classes = env.Java(target = 'classdir', source = 'src')
-env.JavaH(target = 'java_native.h', source = classes)
-
-# builds include/package_foo.h and include/package_bar.h
-env.JavaH(target = 'include',
- source = ['package/foo.class', 'package/bar.class'])
-
-# builds export/foo.h and export/bar.h
-env.JavaH(target = 'export',
- source = ['classes/foo.class', 'classes/bar.class'],
- JAVACLASSDIR = 'classes')
-.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.IP Library()
-.IP env.Library()
-A synonym for the
-.BR StaticLibrary ()
-builder method.
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.IP LoadableModule()
-.IP env.LoadableModule()
-On most systems,
-this is the same as
-.BR SharedLibrary ().
-On Mac OS X (Darwin) platforms,
-this creates a loadable module bundle.
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.IP M4()
-.IP env.M4()
-Builds an output file from an M4 input file.
-This uses a default \fB$M4FLAGS\fP value of
-.BR \-E ,
-which considers all warnings to be fatal
-and stops on the first warning
-when using the GNU version of m4.
-Example:
-
-.ES
-env.M4(target = 'foo.c', source = 'foo.c.m4')
-.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.IP Moc()
-.IP env.Moc()
-Builds an output file from a moc input file. Moc input files are either
-header files or cxx files. This builder is only available after using the
-tool 'qt'. See the \fB$QTDIR\fP variable for more information.
-Example:
-
-.ES
-env.Moc('foo.h') # generates moc_foo.cc
-env.Moc('foo.cpp') # generates foo.moc
-.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.IP MOFiles()
-.IP env.MOFiles()
-This builder belongs to &t-link-msgfmt; tool. The builder compiles
-\fBPO\fP files to \fBMO\fP files.
-
-.IR Example 1 .
-Create \fBpl.mo\fP and \fBen.mo\fP by compiling
-.BR pl.po\fP and \fBen.po :
-.ES
- # ...
- env.MOFiles(['pl', 'en'])
-.EE
-.IP
-.IR Example 2 .
-Compile files for languages defined in \fBLINGUAS\fP file:
-.ES
- # ...
- env.MOFiles(LINGUAS_FILE = 1)
-.EE
-.IP
-.IR Example 3 .
-Create \fBpl.mo\fP and \fBen.mo\fP by compiling
-\fBpl.po\fP and \fBen.po\fP plus files for
-languages defined in \fBLINGUAS\fP file:
-.ES
- # ...
- env.MOFiles(['pl', 'en'], LINGUAS_FILE = 1)
-.EE
-.IP
-.IR Example 4 .
-Compile files for languages defined in \fBLINGUAS\fP file
-(another version):
-.ES
- # ...
- env['LINGUAS_FILE'] = 1
- env.MOFiles()
-.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.IP MSVSProject()
-.IP env.MSVSProject()
-Builds a Microsoft Visual Studio project file,
-and by default builds a solution file as well.
-
-This builds a Visual Studio project file, based on the version of
-Visual Studio that is configured (either the latest installed version,
-or the version specified by
-.B $MSVS_VERSION
-in the Environment constructor).
-For Visual Studio 6, it will generate a
-.B .dsp
-file.
-For Visual Studio 7 (.NET) and later versions, it will generate a
-.B .vcproj
-file.
-
-By default,
-this also generates a solution file
-for the specified project,
-a
-.B .dsw
-file for Visual Studio 6
-or a
-.B .sln
-file for Visual Studio 7 (.NET).
-This behavior may be disabled by specifying
-.B auto_build_solution=0
-when you call
-.BR MSVSProject (),
-in which case you presumably want to
-build the solution file(s)
-by calling the
-.BR MSVSSolution ()
-Builder (see below).
-
-The \fBMSVSProject\fP() builder
-takes several lists of filenames
-to be placed into the project file.
-These are currently limited to
-.BR srcs ,
-.BR incs ,
-.BR localincs ,
-.BR resources ,
-and
-.BR misc .
-These are pretty self-explanatory, but it should be noted that these
-lists are added to the \fB$SOURCES\fP construction variable as strings,
-NOT as SCons File Nodes. This is because they represent file
-names to be added to the project file, not the source files used to
-build the project file.
-
-The above filename lists are all optional,
-although at least one must be specified
-for the resulting project file to be non-empty.
-
-In addition to the above lists of values,
-the following values may be specified:
-
-.BR target :
-The name of the target
-.B .dsp
-or
-.B .vcproj
-file.
-The correct
-suffix for the version of Visual Studio must be used,
-but the
-.B $MSVSPROJECTSUFFIX
-construction variable
-will be defined to the correct value (see example below).
-
-.BR variant :
-The name of this particular variant.
-For Visual Studio 7 projects,
-this can also be a list of variant names.
-These are typically things like "Debug" or "Release", but really
-can be anything you want.
-For Visual Studio 7 projects,
-they may also specify a target platform
-separated from the variant name by a
-.B |
-(vertical pipe)
-character:
-.BR Debug|Xbox .
-The default target platform is Win32.
-Multiple calls to
-.BR MSVSProject ()
-with different variants are allowed;
-all variants will be added to the project file with their appropriate
-build targets and sources.
-
-.BR buildtarget :
-An optional string, node, or list of strings or nodes
-(one per build variant), to tell the Visual Studio debugger
-what output target to use in what build variant.
-The number of
-.B buildtarget
-entries must match the number of
-.B variant
-entries.
-
-.BR runfile :
-The name of the file that Visual Studio 7 and later
-will run and debug.
-This appears as the value of the
-.B Output
-field in the resutling Visual Studio project file.
-If this is not specified,
-the default is the same as the specified
-.B buildtarget
-value.
-
-Note that because &SCons; always executes its build commands
-from the directory in which the \fBSConstruct\fP file is located,
-if you generate a project file in a different directory
-than the \fBSConstruct\fP directory,
-users will not be able to double-click
-on the file name in compilation error messages
-displayed in the Visual Studio console output window.
-This can be remedied by adding the
-Visual C/C++
-.B /FC
-compiler option to the \fB$CCFLAGS\fP variable
-so that the compiler will print
-the full path name of any
-files that cause compilation errors.
-
-Example usage:
-
-.ES
-barsrcs = ['bar.cpp'],
-barincs = ['bar.h'],
-barlocalincs = ['StdAfx.h']
-barresources = ['bar.rc','resource.h']
-barmisc = ['bar_readme.txt']
-
-dll = env.SharedLibrary(target = 'bar.dll',
- source = barsrcs)
-
-env.MSVSProject(target = 'Bar' + env['MSVSPROJECTSUFFIX'],
- srcs = barsrcs,
- incs = barincs,
- localincs = barlocalincs,
- resources = barresources,
- misc = barmisc,
- buildtarget = dll,
- variant = 'Release')
-.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.IP MSVSSolution()
-.IP env.MSVSSolution()
-Builds a Microsoft Visual Studio solution file.
-
-This builds a Visual Studio solution file,
-based on the version of Visual Studio that is configured
-(either the latest installed version,
-or the version specified by
-.B $MSVS_VERSION
-in the construction environment).
-For Visual Studio 6, it will generate a
-.B .dsw
-file.
-For Visual Studio 7 (.NET), it will
-generate a
-.B .sln
-file.
-
-The following values must be specified:
-
-.BR target :
-The name of the target .dsw or .sln file. The correct
-suffix for the version of Visual Studio must be used, but the value
-.B $MSVSSOLUTIONSUFFIX
-will be defined to the correct value (see example below).
-
-.BR variant :
-The name of this particular variant, or a list of variant
-names (the latter is only supported for MSVS 7 solutions). These are
-typically things like "Debug" or "Release", but really can be anything
-you want. For MSVS 7 they may also specify target platform, like this
-"Debug|Xbox". Default platform is Win32.
-
-.BR projects :
-A list of project file names, or Project nodes returned by calls to the
-.BR MSVSProject ()
-Builder,
-to be placed into the solution file.
-It should be noted that these file names are NOT added to the $SOURCES
-environment variable in form of files, but rather as strings. This
-is because they represent file names to be added to the solution file,
-not the source files used to build the solution file.
-
-Example Usage:
-
-.ES
-env.MSVSSolution(target = 'Bar' + env['MSVSSOLUTIONSUFFIX'],
- projects = ['bar' + env['MSVSPROJECTSUFFIX']],
- variant = 'Release')
-.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.IP Object()
-.IP env.Object()
-A synonym for the
-.BR StaticObject ()
-builder method.
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.IP Package()
-.IP env.Package()
-Builds software distribution packages.
-Packages consist of files to install and packaging information.
-The former may be specified with the \fIsource\fP parameter and may be left out,
-in which case the &FindInstalledFiles; function will collect
-all files that have an \fBInstall\fP() or \fBInstallAs\fP() Builder attached.
-If the \fItarget\fP is not specified
-it will be deduced from additional information given to this Builder.
-
-The packaging information is specified
-with the help of construction variables documented below.
-This information is called a tag to stress that
-some of them can also be attached to files with the &Tag; function.
-The mandatory ones will complain if they were not specified.
-They vary depending on chosen target packager.
-
-The target packager may be selected with the "PACKAGETYPE" command line
-option or with the \fB$PACKAGETYPE\fP construction variable. Currently
-the following packagers available:
-
- * msi - Microsoft Installer
- * rpm - Redhat Package Manger
- * ipkg - Itsy Package Management System
- * tarbz2 - compressed tar
- * targz - compressed tar
- * zip - zip file
- * src_tarbz2 - compressed tar source
- * src_targz - compressed tar source
- * src_zip - zip file source
-
-An updated list is always available under the "package_type" option when
-running "scons --help" on a project that has packaging activated.
-.ES
-env = Environment(tools=['default', 'packaging'])
-env.Install('/bin/', 'my_program')
-env.Package( NAME = 'foo',
- VERSION = '1.2.3',
- PACKAGEVERSION = 0,
- PACKAGETYPE = 'rpm',
- LICENSE = 'gpl',
- SUMMARY = 'balalalalal',
- DESCRIPTION = 'this should be really really long',
- X_RPM_GROUP = 'Application/fu',
- SOURCE_URL = 'http://foo.org/foo-1.2.3.tar.gz'
- )
-.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.IP PCH()
-.IP env.PCH()
-Builds a Microsoft Visual C++ precompiled header.
-Calling this builder method
-returns a list of two targets: the PCH as the first element, and the object
-file as the second element. Normally the object file is ignored.
-This builder method is only
-provided when Microsoft Visual C++ is being used as the compiler.
-The PCH builder method is generally used in
-conjuction with the PCH construction variable to force object files to use
-the precompiled header:
-
-.ES
-env['PCH'] = env.PCH('StdAfx.cpp')[0]
-.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.IP PDF()
-.IP env.PDF()
-Builds a \fB.pdf\fP file
-from a \fB.dvi\fP input file
-(or, by extension, a \fB.tex\fP,
-.BR .ltx ,
-or
-\fB.latex\fP input file).
-The suffix specified by the \fB$PDFSUFFIX\fP construction variable
-(\fB.pdf\fP by default)
-is added automatically to the target
-if it is not already present. Example:
-
-.ES
-# builds from aaa.tex
-env.PDF(target = 'aaa.pdf', source = 'aaa.tex')
-# builds bbb.pdf from bbb.dvi
-env.PDF(target = 'bbb', source = 'bbb.dvi')
-.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.IP POInit()
-.IP env.POInit()
-This builder belongs to &t-link-msginit; tool. The builder initializes missing
-\fBPO\fP file(s) if \fB$POAUTOINIT\fP is set. If
-\fB$POAUTOINIT\fP is not set (default), \fBPOInit\fP() prints instruction for
-user (that is supposed to be a translator), telling how the
-\fBPO\fP file should be initialized. In normal projects
-.IR you should not use \fBPOInit\fP() and use \fBPOUpdate ()
-instead\fP. \fBPOUpdate\fP() chooses intelligently between
-.BR msgmerge(1)\fP and \fBmsginit(1)\fP. \fBPOInit ()
-always uses \fBmsginit(1)\fP and should be regarded as builder for
-special purposes or for temporary use (e.g. for quick, one time initialization
-of a bunch of \fBPO\fP files) or for tests.
-
-Target nodes defined through \fBPOInit\fP() are not built by default (they're
-\fBIgnore\fPd from \fB'.'\fP node) but are added to
-special \fBAlias\fP (\fB'po-create'\fP by default).
-The alias name may be changed through the \fB$POCREATE_ALIAS\fP
-construction variable. All \fBPO\fP files defined through
-.BR POInit\fP() may be easily initialized by \fBscons po-create .
-
-.IR Example 1 .
-Initialize \fBen.po\fP and \fBpl.po\fP from
-.BR messages.pot :
-.ES
- # ...
- env.POInit(['en', 'pl']) # messages.pot --> [en.po, pl.po]
-.EE
-.IP
-.IR Example 2 .
-Initialize \fBen.po\fP and \fBpl.po\fP from
-.BR foo.pot :
-.ES
- # ...
- env.POInit(['en', 'pl'], ['foo']) # foo.pot --> [en.po, pl.po]
-.EE
-.IP
-.IR Example 3 .
-Initialize \fBen.po\fP and \fBpl.po\fP from
-\fBfoo.pot\fP but using \fB$POTDOMAIN\fP construction
-variable:
-.ES
- # ...
- env.POInit(['en', 'pl'], POTDOMAIN='foo') # foo.pot --> [en.po, pl.po]
-.EE
-.IP
-.IR Example 4 .
-Initialize \fBPO\fP files for languages defined in
-\fBLINGUAS\fP file. The files will be initialized from template
-.BR messages.pot :
-.ES
- # ...
- env.POInit(LINGUAS_FILE = 1) # needs 'LINGUAS' file
-.EE
-.IP
-.IR Example 5 .
-Initialize \fBen.po\fP and \fBpl.pl\fP
-\fBPO\fP files plus files for languages defined in
-\fBLINGUAS\fP file. The files will be initialized from template
-.BR messages.pot :
-.ES
- # ...
- env.POInit(['en', 'pl'], LINGUAS_FILE = 1)
-.EE
-.IP
-.IR Example 6 .
-You may preconfigure your environment first, and then initialize
-\fBPO\fP files:
-.ES
- # ...
- env['POAUTOINIT'] = 1
- env['LINGUAS_FILE'] = 1
- env['POTDOMAIN'] = 'foo'
- env.POInit()
-.EE
-which has same efect as:
-.ES
- # ...
- env.POInit(POAUTOINIT = 1, LINGUAS_FILE = 1, POTDOMAIN = 'foo')
-.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.IP PostScript()
-.IP env.PostScript()
-Builds a \fB.ps\fP file
-from a \fB.dvi\fP input file
-(or, by extension, a \fB.tex\fP,
-.BR .ltx ,
-or
-\fB.latex\fP input file).
-The suffix specified by the \fB$PSSUFFIX\fP construction variable
-(\fB.ps\fP by default)
-is added automatically to the target
-if it is not already present. Example:
-
-.ES
-# builds from aaa.tex
-env.PostScript(target = 'aaa.ps', source = 'aaa.tex')
-# builds bbb.ps from bbb.dvi
-env.PostScript(target = 'bbb', source = 'bbb.dvi')
-.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.IP POTUpdate()
-.IP env.POTUpdate()
-The builder belongs to &t-link-xgettext; tool. The builder updates target
-\fBPOT\fP file if exists or creates one if it doesn't. The node is
-not built by default (i.e. it is \fBIgnore\fPd from
-\fB'.'\fP), but only on demand (i.e. when given
-\fBPOT\fP file is required or when special alias is invoked). This
-builder adds its targe node (\fBmessages.pot\fP, say) to a
-special alias (\fBpot-update\fP by default, see
-\fB$POTUPDATE_ALIAS\fP) so you can update/create them easily with
-\fBscons pot-update\fP. The file is not written until there is no
-real change in internationalized messages (or in comments that enter
-\fBPOT\fP file).
-
-<note>
-You may see \fBxgettext(1)\fP being invoked by the
-&t-link-xgettext; tool even if there is no real change in internationalized
-messages (so the \fBPOT\fP file is not being updated). This
-happens every time a source file has changed. In such case we invoke
-\fBxgettext(1)\fP and compare its output with the content of
-\fBPOT\fP file to decide whether the file should be updated or
-not.</para></note>
-
-.I "Example 1."
-Let's create \fBpo/\fP directory and place following
-\fBSConstruct\fP script there:
-.ES
- # SConstruct in 'po/' subdir
- env = Environment( tools = ['default', 'xgettext'] )
- env.POTUpdate(['foo'], ['../a.cpp', '../b.cpp'])
- env.POTUpdate(['bar'], ['../c.cpp', '../d.cpp'])
-.EE
-.IP
-
-Then invoke scons few times:
-.ES
- user@host:$ scons # Does not create foo.pot nor bar.pot
- user@host:$ scons foo.pot # Updates or creates foo.pot
- user@host:$ scons pot-update # Updates or creates foo.pot and bar.pot
- user@host:$ scons -c # Does not clean foo.pot nor bar.pot.
-.EE
-the results shall be as the comments above say.
-
-.I "Example 2."
-The \fBPOTUpdate\fP() builder may be used with no target specified, in which
-case default target \fBmessages.pot\fP will be used. The
-default target may also be overriden by setting \fB$POTDOMAIN\fP construction
-variable or providing it as an override to \fBPOTUpdate\fP() builder:
-.ES
- # SConstruct script
- env = Environment( tools = ['default', 'xgettext'] )
- env['POTDOMAIN'] = "foo"
- env.POTUpdate(source = ["a.cpp", "b.cpp"]) # Creates foo.pot ...
- env.POTUpdate(POTDOMAIN = "bar", source = ["c.cpp", "d.cpp"]) # and bar.pot
-.EE
-.IP
-.I "Example 3."
-The sources may be specified within separate file, for example
-.BR POTFILES.in :
-.ES
- # POTFILES.in in 'po/' subdirectory
- ../a.cpp
- ../b.cpp
- # end of file
-.EE
-.IP
-
-The name of the file (\fBPOTFILES.in\fP) containing the list of
-sources is provided via \fB$XGETTEXTFROM\fP:
-.ES
- # SConstruct file in 'po/' subdirectory
- env = Environment( tools = ['default', 'xgettext'] )
- env.POTUpdate(XGETTEXTFROM = 'POTFILES.in')
-.EE
-.IP
-
-
-.I "Example 4."
-You may use \fB$XGETTEXTPATH\fP to define source search path. Assume, for
-example, that you have files \fBa.cpp\fP,
-.BR b.cpp\fP, \fBpo/SConstruct ,
-.BR po/POTFILES.in\fP. Then your \fBPOT -related
-files could look as below:
-.ES
- # POTFILES.in in 'po/' subdirectory
- a.cpp
- b.cpp
- # end of file
-.EE
-
-.ES
- # SConstruct file in 'po/' subdirectory
- env = Environment( tools = ['default', 'xgettext'] )
- env.POTUpdate(XGETTEXTFROM = 'POTFILES.in', XGETTEXTPATH='../')
-.EE
-.IP
-.I "Example 5."
-Multiple search directories may be defined within a list, i.e.
-\fBXGETTEXTPATH = ['dir1', 'dir2', ...]\fP. The order in the list
-determines the search order of source files. The path to the first file found
-is used.
-
-Let's create \fB0/1/po/SConstruct\fP script:
-.ES
- # SConstruct file in '0/1/po/' subdirectory
- env = Environment( tools = ['default', 'xgettext'] )
- env.POTUpdate(XGETTEXTFROM = 'POTFILES.in', XGETTEXTPATH=['../', '../../'])
-.EE
-and \fB0/1/po/POTFILES.in\fP:
-.ES
- # POTFILES.in in '0/1/po/' subdirectory
- a.cpp
- # end of file
-.EE
-Write two \fB*.cpp\fP files, the first one is
-.BR 0/a.cpp :
-.ES
- /* 0/a.cpp */
- gettext("Hello from ../../a.cpp")
-.EE
-and the second is \fB0/1/a.cpp\fP:
-.ES
- /* 0/1/a.cpp */
- gettext("Hello from ../a.cpp")
-.EE
-then run scons. You'll obtain \fB0/1/po/messages.pot\fP with the
-message \fB"Hello from ../a.cpp"\fP. When you reverse order in
-\fI$XGETTEXTFOM\fP, i.e. when you write SConscript as
-.ES
- # SConstruct file in '0/1/po/' subdirectory
- env = Environment( tools = ['default', 'xgettext'] )
- env.POTUpdate(XGETTEXTFROM = 'POTFILES.in', XGETTEXTPATH=['../../', '../'])
-.EE
-.IP
- then the \fBmessages.pot\fP will contain
-\fBmsgid "Hello from ../../a.cpp"\fP line and not
-.BR msgid "Hello from ../a.cpp" .
-
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.IP POUpdate()
-.IP env.POUpdate()
-The builder belongs to &t-link-msgmerge; tool. The builder updates
-\fBPO\fP files with \fBmsgmerge(1)\fP, or initializes
-missing \fBPO\fP files as described in documentation of
-&t-link-msginit; tool and \fBPOInit\fP() builder (see also
-\fB$POAUTOINIT\fP). Note, that \fBPOUpdate\fP() \fIdoes not add its
-targets to \fBpo-create\fP alias\fP as \fBPOInit\fP()
-does.
-
-Target nodes defined through \fBPOUpdate\fP() are not built by default
-(they're \fBIgnore\fPd from \fB'.'\fP node). Instead,
-they are added automatically to special \fBAlias\fP
-(\fB'po-update'\fP by default). The alias name may be changed
-through the \fB$POUPDATE_ALIAS\fP construction variable. You can easilly
-update \fBPO\fP files in your project by \fBscons
-po-update\fP.
-
-.I "Example 1."
-Update \fBen.po\fP and \fBpl.po\fP from
-.BR messages.pot\fP template (see also \fB$POTDOMAIN ),
-assuming that the later one exists or there is rule to build it (see
-.BR POTUpdate ()):
-.ES
- # ...
- env.POUpdate(['en','pl']) # messages.pot --> [en.po, pl.po]
-.EE
-.IP
-.I "Example 2."
-Update \fBen.po\fP and \fBpl.po\fP from
-\fBfoo.pot\fP template:
-.ES
- # ...
- env.POUpdate(['en', 'pl'], ['foo']) # foo.pot --> [en.po, pl.pl]
-.EE
-.IP
-.I "Example 3."
-Update \fBen.po\fP and \fBpl.po\fP from
-\fBfoo.pot\fP (another version):
-.ES
- # ...
- env.POUpdate(['en', 'pl'], POTDOMAIN='foo') # foo.pot -- > [en.po, pl.pl]
-.EE
-.IP
-.I "Example 4."
-Update files for languages defined in \fBLINGUAS\fP file. The
-files are updated from \fBmessages.pot\fP template:
-.ES
- # ...
- env.POUpdate(LINGUAS_FILE = 1) # needs 'LINGUAS' file
-.EE
-.IP
-.I "Example 5."
-Same as above, but update from \fBfoo.pot\fP template:
-.ES
- # ...
- env.POUpdate(LINGUAS_FILE = 1, source = ['foo'])
-.EE
-.IP
-.I "Example 6."
-Update \fBen.po\fP and \fBpl.po\fP plus files for
-languages defined in \fBLINGUAS\fP file. The files are updated
-from \fBmessages.pot\fP template:
-.ES
- # produce 'en.po', 'pl.po' + files defined in 'LINGUAS':
- env.POUpdate(['en', 'pl' ], LINGUAS_FILE = 1)
-.EE
-.IP
-.I "Example 7."
-Use \fB$POAUTOINIT\fP to automatically initialize \fBPO\fP file
-if it doesn't exist:
-.ES
- # ...
- env.POUpdate(LINGUAS_FILE = 1, POAUTOINIT = 1)
-.EE
-.IP
-.I "Example 8."
-Update \fBPO\fP files for languages defined in
-\fBLINGUAS\fP file. The files are updated from
-\fBfoo.pot\fP template. All necessary settings are
-pre-configured via environment.
-.ES
- # ...
- env['POAUTOINIT'] = 1
- env['LINGUAS_FILE'] = 1
- env['POTDOMAIN'] = 'foo'
- env.POUpdate()
-.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.IP Program()
-.IP env.Program()
-Builds an executable given one or more object files
-or C, C++, D, or Fortran source files.
-If any C, C++, D or Fortran source files are specified,
-then they will be automatically
-compiled to object files using the
-.BR Object ()
-builder method;
-see that builder method's description for
-a list of legal source file suffixes
-and how they are interpreted.
-The target executable file prefix
-(specified by the \fB$PROGPREFIX\fP construction variable; nothing by default)
-and suffix
-(specified by the \fB$PROGSUFFIX\fP construction variable;
-by default, \fB.exe\fP on Windows systems,
-nothing on POSIX systems)
-are automatically added to the target if not already present.
-Example:
-
-.ES
-env.Program(target = 'foo', source = ['foo.o', 'bar.c', 'baz.f'])
-.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.IP RES()
-.IP env.RES()
-Builds a Microsoft Visual C++ resource file.
-This builder method is only provided
-when Microsoft Visual C++ or MinGW is being used as the compiler. The
-.B .res
-(or
-.B .o
-for MinGW) suffix is added to the target name if no other suffix is given.
-The source
-file is scanned for implicit dependencies as though it were a C file.
-Example:
-
-.ES
-env.RES('resource.rc')
-.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.IP RMIC()
-.IP env.RMIC()
-Builds stub and skeleton class files
-for remote objects
-from Java \fB.class\fP files.
-The target is a directory
-relative to which the stub
-and skeleton class files will be written.
-The source can be the names of \fB.class\fP files,
-or the objects return from the
-.BR Java ()
-builder method.
-
-If the construction variable
-.B $JAVACLASSDIR
-is set, either in the environment
-or in the call to the
-.BR RMIC ()
-builder method itself,
-then the value of the variable
-will be stripped from the
-beginning of any \fB.class \fP
-file names.
-
-.ES
-classes = env.Java(target = 'classdir', source = 'src')
-env.RMIC(target = 'outdir1', source = classes)
-
-env.RMIC(target = 'outdir2',
- source = ['package/foo.class', 'package/bar.class'])
-
-env.RMIC(target = 'outdir3',
- source = ['classes/foo.class', 'classes/bar.class'],
- JAVACLASSDIR = 'classes')
-.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.IP RPCGenClient()
-.IP env.RPCGenClient()
-Generates an RPC client stub (\fB_clnt.c\fP) file
-from a specified RPC (\fB.x\fP) source file.
-Because rpcgen only builds output files
-in the local directory,
-the command will be executed
-in the source file's directory by default.
-
-.ES
-# Builds src/rpcif_clnt.c
-env.RPCGenClient('src/rpcif.x')
-.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.IP RPCGenHeader()
-.IP env.RPCGenHeader()
-Generates an RPC header (\fB.h\fP) file
-from a specified RPC (\fB.x\fP) source file.
-Because rpcgen only builds output files
-in the local directory,
-the command will be executed
-in the source file's directory by default.
-
-.ES
-# Builds src/rpcif.h
-env.RPCGenHeader('src/rpcif.x')
-.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.IP RPCGenService()
-.IP env.RPCGenService()
-Generates an RPC server-skeleton (\fB_svc.c\fP) file
-from a specified RPC (\fB.x\fP) source file.
-Because rpcgen only builds output files
-in the local directory,
-the command will be executed
-in the source file's directory by default.
-
-.ES
-# Builds src/rpcif_svc.c
-env.RPCGenClient('src/rpcif.x')
-.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.IP RPCGenXDR()
-.IP env.RPCGenXDR()
-Generates an RPC XDR routine (\fB_xdr.c\fP) file
-from a specified RPC (\fB.x\fP) source file.
-Because rpcgen only builds output files
-in the local directory,
-the command will be executed
-in the source file's directory by default.
-
-.ES
-# Builds src/rpcif_xdr.c
-env.RPCGenClient('src/rpcif.x')
-.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.IP SharedLibrary()
-.IP env.SharedLibrary()
-Builds a shared library
-(\fB.so\fP on a POSIX system,
-\fB.dll\fP on Windows)
-given one or more object files
-or C, C++, D or Fortran source files.
-If any source files are given,
-then they will be automatically
-compiled to object files.
-The static library prefix and suffix (if any)
-are automatically added to the target.
-The target library file prefix
-(specified by the \fB$SHLIBPREFIX\fP construction variable;
-by default, \fBlib\fP on POSIX systems,
-nothing on Windows systems)
-and suffix
-(specified by the \fB$SHLIBSUFFIX\fP construction variable;
-by default, \fB.dll\fP on Windows systems,
-\fB.so\fP on POSIX systems)
-are automatically added to the target if not already present.
-Example:
-
-.ES
-env.SharedLibrary(target = 'bar', source = ['bar.c', 'foo.o'])
-.EE
-.IP
-On Windows systems, the
-.BR SharedLibrary ()
-builder method will always build an import
-(\fB.lib\fP) library
-in addition to the shared (\fB.dll\fP) library,
-adding a \fB.lib\fP library with the same basename
-if there is not already a \fB.lib\fP file explicitly
-listed in the targets.
-
-Any object files listed in the
-.B source
-must have been built for a shared library
-(that is, using the
-.BR SharedObject ()
-builder method).
-.B scons
-will raise an error if there is any mismatch.
-
-On some platforms, there is a distinction between a shared library
-(loaded automatically by the system to resolve external references)
-and a loadable module (explicitly loaded by user action).
-For maximum portability, use the \fBLoadableModule\fP() builder for the latter.
-
-When the \fB$SHLIBVERSION\fP construction variable is defined a versioned
-shared library is created. This modifies the \fB$SHLINKFLAGS\fP as required,
-adds the version number to the library name, and creates the symlinks that
-are needed. \fB$SHLIBVERSION\fP needs to be of the form X.Y.Z, where X
-and Y are numbers, and Z is a number but can also contain letters to designate
-alpha, beta, or release candidate patch levels.
-
-This builder may create multiple links to the library. On a POSIX system,
-for the shared library libbar.so.2.3.1, the links created would be
-libbar.so, libbar.so.2, and libbar.so.2.3; on a Darwin (OSX) system
-the library would be libbar.2.3.1.dylib and the link would be
-libbar.dylib.
-
-On Windows systems, specifying
-.B register=1
-will cause the \fB.dll\fP to be
-registered after it is built using REGSVR32.
-The command that is run
-("regsvr32" by default) is determined by \fB$REGSVR\fP construction
-variable, and the flags passed are determined by \fB$REGSVRFLAGS\fP. By
-default, \fB$REGSVRFLAGS\fP includes the \fB/s\fP option,
-to prevent dialogs from popping
-up and requiring user attention when it is run. If you change
-\fB$REGSVRFLAGS\fP, be sure to include the \fB/s\fP option.
-For example,
-
-.ES
-env.SharedLibrary(target = 'bar',
- source = ['bar.cxx', 'foo.obj'],
- register=1)
-.EE
-.IP
-will register \fBbar.dll\fP as a COM object
-when it is done linking it.
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.IP SharedObject()
-.IP env.SharedObject()
-Builds an object file for
-inclusion in a shared library.
-Source files must have one of the same set of extensions
-specified above for the
-.BR StaticObject ()
-builder method.
-On some platforms building a shared object requires additional
-compiler option
-(e.g. \fB\-fPIC\fP for gcc)
-in addition to those needed to build a
-normal (static) object, but on some platforms there is no difference between a
-shared object and a normal (static) one. When there is a difference, SCons
-will only allow shared objects to be linked into a shared library, and will
-use a different suffix for shared objects. On platforms where there is no
-difference, SCons will allow both normal (static)
-and shared objects to be linked into a
-shared library, and will use the same suffix for shared and normal
-(static) objects.
-The target object file prefix
-(specified by the \fB$SHOBJPREFIX\fP construction variable;
-by default, the same as \fB$OBJPREFIX\fP)
-and suffix
-(specified by the \fB$SHOBJSUFFIX\fP construction variable)
-are automatically added to the target if not already present.
-Examples:
-
-.ES
-env.SharedObject(target = 'ddd', source = 'ddd.c')
-env.SharedObject(target = 'eee.o', source = 'eee.cpp')
-env.SharedObject(target = 'fff.obj', source = 'fff.for')
-.EE
-.IP
-Note that the source files will be scanned
-according to the suffix mappings in the
-.B SourceFileScanner
-object.
-See the section "Scanner Objects,"
-below, for more information.
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.IP StaticLibrary()
-.IP env.StaticLibrary()
-Builds a static library given one or more object files
-or C, C++, D or Fortran source files.
-If any source files are given,
-then they will be automatically
-compiled to object files.
-The static library prefix and suffix (if any)
-are automatically added to the target.
-The target library file prefix
-(specified by the \fB$LIBPREFIX\fP construction variable;
-by default, \fBlib\fP on POSIX systems,
-nothing on Windows systems)
-and suffix
-(specified by the \fB$LIBSUFFIX\fP construction variable;
-by default, \fB.lib\fP on Windows systems,
-\fB.a\fP on POSIX systems)
-are automatically added to the target if not already present.
-Example:
-
-.ES
-env.StaticLibrary(target = 'bar', source = ['bar.c', 'foo.o'])
-.EE
-.IP
-Any object files listed in the
-.B source
-must have been built for a static library
-(that is, using the
-.BR StaticObject ()
-builder method).
-.B scons
-will raise an error if there is any mismatch.
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.IP StaticObject()
-.IP env.StaticObject()
-Builds a static object file
-from one or more C, C++, D, or Fortran source files.
-Source files must have one of the following extensions:
-
-.ES
- .asm assembly language file
- .ASM assembly language file
- .c C file
- .C Windows: C file
- POSIX: C++ file
- .cc C++ file
- .cpp C++ file
- .cxx C++ file
- .cxx C++ file
- .c++ C++ file
- .C++ C++ file
- .d D file
- .f Fortran file
- .F Windows: Fortran file
- POSIX: Fortran file + C pre-processor
- .for Fortran file
- .FOR Fortran file
- .fpp Fortran file + C pre-processor
- .FPP Fortran file + C pre-processor
- .m Object C file
- .mm Object C++ file
- .s assembly language file
- .S Windows: assembly language file
- ARM: CodeSourcery Sourcery Lite
- .sx assembly language file + C pre-processor
- POSIX: assembly language file + C pre-processor
- .spp assembly language file + C pre-processor
- .SPP assembly language file + C pre-processor
-.EE
-.IP
-The target object file prefix
-(specified by the \fB$OBJPREFIX\fP construction variable; nothing by default)
-and suffix
-(specified by the \fB$OBJSUFFIX\fP construction variable;
-\fB.obj\fP on Windows systems,
-\fB.o\fP on POSIX systems)
-are automatically added to the target if not already present.
-Examples:
-
-.ES
-env.StaticObject(target = 'aaa', source = 'aaa.c')
-env.StaticObject(target = 'bbb.o', source = 'bbb.c++')
-env.StaticObject(target = 'ccc.obj', source = 'ccc.f')
-.EE
-.IP
-Note that the source files will be scanned
-according to the suffix mappings in
-.B SourceFileScanner
-object.
-See the section "Scanner Objects,"
-below, for more information.
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.IP Substfile()
-.IP env.Substfile()
-The \fBSubstfile\fP() builder generates a single text file
-by concatenating the source files.
-Nested lists of sources are flattened.
-\fB$LINESEPARATOR\fP is used to separate the source files;
-see the description of \fBTextfile\fP() for details.
-
-If a single source file is present with an \fB.in\fP suffix,
-the suffix is stripped and the remainder is used as the default target name.
-
-The prefix and suffix specified by the \fB$SUBSTFILEPREFIX\fP
-and \fB$SUBSTFILESUFFIX\fP construction variables
-(the null string by default in both cases)
-are automatically added to the target if they are not already present.
-
-If a construction variable named \fB$SUBST_DICT\fP is present,
-it may be either a Python dictionary or a sequence of (key,value) tuples.
-If the former,
-the dictionary is converted into a list of tuples in an arbitrary order,
-so if one key is a prefix of another key
-or if one substitution could be further expanded by another subsitition,
-it is unpredictible whether the expansion will occur.
-
-Any occurences in the source of a key
-are replaced by the corresponding value,
-which may be a Python callable function or a string.
-If a value is a function,
-it is first called (with no arguments) to produce a string.
-The string is \fIsubst\fP-expanded
-and the result replaces the key.
-
-.ES
-env = Environment(tools = ['default', 'textfile'])
-
-env['prefix'] = '/usr/bin'
-script_dict = {'@prefix@': '/bin', @exec_prefix@: '$prefix'}
-env.Substfile('script.in', SUBST_DICT = script_dict)
-
-conf_dict = {'%VERSION%': '1.2.3', '%BASE%': 'MyProg'}
-env.Substfile('config.h.in', conf_dict, SUBST_DICT = conf_dict)
-
-# UNPREDICTABLE - one key is a prefix of another
-bad_foo = {'$foo': '$foo', '$foobar': '$foobar'}
-env.Substfile('foo.in', SUBST_DICT = bad_foo)
-
-# PREDICTABLE - keys are applied longest first
-good_foo = [('$foobar', '$foobar'), ('$foo', '$foo')]
-env.Substfile('foo.in', SUBST_DICT = good_foo)
-
-# UNPREDICTABLE - one substitution could be futher expanded
-bad_bar = {'@bar@': '@soap@', '@soap@': 'lye'}
-env.Substfile('bar.in', SUBST_DICT = bad_bar)
-
-# PREDICTABLE - substitutions are expanded in order
-good_bar = (('@bar@', '@soap@'), ('@soap@', 'lye'))
-env.Substfile('bar.in', SUBST_DICT = good_bar)
-
-# the SUBST_DICT may be in common (and not an override)
-substutions = {}
-subst = Environment(tools = ['textfile'], SUBST_DICT = substitutions)
-substitutions['@foo@'] = 'foo'
-subst['SUBST_DICT']['@bar@'] = 'bar'
-subst.Substfile('pgm1.c', [Value('#include "@foo@.h"'),
- Value('#include "@bar@.h"'),
- "common.in",
- "pgm1.in"
- ])
-subst.Substfile('pgm2.c', [Value('#include "@foo@.h"'),
- Value('#include "@bar@.h"'),
- "common.in",
- "pgm2.in"
- ])
-
-.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.IP Tar()
-.IP env.Tar()
-Builds a tar archive of the specified files
-and/or directories.
-Unlike most builder methods,
-the
-.BR Tar ()
-builder method may be called multiple times
-for a given target;
-each additional call
-adds to the list of entries
-that will be built into the archive.
-Any source directories will
-be scanned for changes to
-any on-disk files,
-regardless of whether or not
-.B scons
-knows about them from other Builder or function calls.
-
-.ES
-env.Tar('src.tar', 'src')
-
-# Create the stuff.tar file.
-env.Tar('stuff', ['subdir1', 'subdir2'])
-# Also add "another" to the stuff.tar file.
-env.Tar('stuff', 'another')
-
-# Set TARFLAGS to create a gzip-filtered archive.
-env = Environment(TARFLAGS = '-c -z')
-env.Tar('foo.tar.gz', 'foo')
-
-# Also set the suffix to .tgz.
-env = Environment(TARFLAGS = '-c -z',
- TARSUFFIX = '.tgz')
-env.Tar('foo')
-.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.IP Textfile()
-.IP env.Textfile()
-The \fBTextfile\fP() builder generates a single text file.
-The source strings constitute the lines;
-nested lists of sources are flattened.
-\fB$LINESEPARATOR\fP is used to separate the strings.
-
-If present, the \fB$SUBST_DICT\fP construction variable
-is used to modify the strings before they are written;
-see the \fBSubstfile\fP() description for details.
-
-The prefix and suffix specified by the \fB$TEXTFILEPREFIX\fP
-and \fB$TEXTFILESUFFIX\fP construction variables
-(the null string and \fB.txt\fP by default, respectively)
-are automatically added to the target if they are not already present.
-Examples:
-
-.ES
-# builds/writes foo.txt
-env.Textfile(target = 'foo.txt', source = ['Goethe', 42, 'Schiller'])
-
-# builds/writes bar.txt
-env.Textfile(target = 'bar',
- source = ['lalala', 'tanteratei'],
- LINESEPARATOR='|*')
-
-# nested lists are flattened automatically
-env.Textfile(target = 'blob',
- source = ['lalala', ['Goethe', 42 'Schiller'], 'tanteratei'])
-
-# files may be used as input by wraping them in File()
-env.Textfile(target = 'concat', # concatenate files with a marker between
- source = [File('concat1'), File('concat2')],
- LINESEPARATOR = '====================\\n')
-
-Results are:
-foo.txt
- ....8<----
- Goethe
- 42
- Schiller
- ....8<---- (no linefeed at the end)
-
-bar.txt:
- ....8<----
- lalala|*tanteratei
- ....8<---- (no linefeed at the end)
-
-blob.txt
- ....8<----
- lalala
- Goethe
- 42
- Schiller
- tanteratei
- ....8<---- (no linefeed at the end)
-.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.IP Translate()
-.IP env.Translate()
-This pseudo-builder belongs to &t-link-gettext; toolset. The builder extracts
-internationalized messages from source files, updates \fBPOT\fP
-template (if necessary) and then updates \fBPO\fP translations (if
-necessary). If \fB$POAUTOINIT\fP is set, missing \fBPO\fP files
-will be automatically created (i.e. without translator person intervention).
-The variables \fB$LINGUAS_FILE\fP and \fB$POTDOMAIN\fP are taken into
-acount too. All other construction variables used by \fBPOTUpdate\fP(), and
-\fBPOUpdate\fP() work here too.
-
-.IR Example 1 .
-The simplest way is to specify input files and output languages inline in
-a SCons script when invoking \fBTranslate\fP()
-.ES
-# SConscript in 'po/' directory
-env = Environment( tools = ["default", "gettext"] )
-env['POAUTOINIT'] = 1
-env.Translate(['en','pl'], ['../a.cpp','../b.cpp'])
-.EE
-.IP
-.IR Example 2 .
-If you wish, you may also stick to conventional style known from
-<productname>autotools</productname>, i.e. using
-\fBPOTFILES.in\fP and \fBLINGUAS\fP files
-.ES
-# LINGUAS
-en pl
-#end
-.EE
-
-.ES
-# POTFILES.in
-a.cpp
-b.cpp
-# end
-.EE
-
-.ES
-# SConscript
-env = Environment( tools = ["default", "gettext"] )
-env['POAUTOINIT'] = 1
-env['XGETTEXTPATH'] = ['../']
-env.Translate(LINGUAS_FILE = 1, XGETTEXTFROM = 'POTFILES.in')
-.EE
-.IP
-The last approach is perhaps the recommended one. It allows easily split
-internationalization/localization onto separate SCons scripts, where a script
-in source tree is responsible for translations (from sources to
-\fBPO\fP files) and script(s) under variant directories are
-responsible for compilation of \fBPO\fP to \fBMO\fP
-files to and for installation of \fBMO\fP files. The "gluing
-factor" synchronizing these two scripts is then the content of
-\fBLINGUAS\fP file. Note, that the updated
-\fBPOT\fP and \fBPO\fP files are usually going to be
-committed back to the repository, so they must be updated within the source
-directory (and not in variant directories). Additionaly, the file listing of
-\fBpo/\fP directory contains \fBLINGUAS\fP file,
-so the source tree looks familiar to translators, and they may work with the
-project in their usual way.
-
-.IR Example 3 .
-Let's prepare a development tree as below
-.ES
- project/
- + SConstruct
- + build/
- + src/
- + po/
- + SConscript
- + SConscript.i18n
- + POTFILES.in
- + LINGUAS
-.EE
-with \fBbuild\fP being variant directory. Write the top-level
-\fBSConstruct\fP script as follows
-.ES
- # SConstruct
- env = Environment( tools = ["default", "gettext"] )
- VariantDir('build', 'src', duplicate = 0)
- env['POAUTOINIT'] = 1
- SConscript('src/po/SConscript.i18n', exports = 'env')
- SConscript('build/po/SConscript', exports = 'env')
-.EE
-the \fBsrc/po/SConscript.i18n\fP as
-.ES
- # src/po/SConscript.i18n
- Import('env')
- env.Translate(LINGUAS_FILE=1, XGETTEXTFROM='POTFILES.in', XGETTEXTPATH=['../'])
-.EE
-and the \fBsrc/po/SConscript\fP
-.ES
- # src/po/SConscript
- Import('env')
- env.MOFiles(LINGUAS_FILE = 1)
-.EE
-Such setup produces \fBPOT\fP and \fBPO\fP files
-under source tree in \fBsrc/po/\fP and binary
-\fBMO\fP files under variant tree in
-\fBbuild/po/\fP. This way the \fBPOT\fP and
-\fBPO\fP files are separated from other output files, which must
-not be committed back to source repositories (e.g. \fBMO\fP
-files).
-
-<note>
-In above example, the \fBPO\fP files are not updated,
-nor created automatically when you issue \fBscons '.'\fP command.
-The files must be updated (created) by hand via \fBscons
-po-update\fP and then \fBMO\fP files can be compiled by
-running \fBscons '.'\fP.</para></note>
-
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.IP TypeLibrary()
-.IP env.TypeLibrary()
-Builds a Windows type library (\fB.tlb\fP)
-file from an input IDL file (\fB.idl\fP).
-In addition, it will build the associated inteface stub and
-proxy source files,
-naming them according to the base name of the \fB.idl\fP file.
-For example,
-
-.ES
-env.TypeLibrary(source="foo.idl")
-.EE
-.IP
-Will create \fBfoo.tlb\fP,
-.BR foo.h ,
-.BR foo_i.c ,
-.B foo_p.c
-and
-.B foo_data.c
-files.
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.IP Uic()
-.IP env.Uic()
-Builds a header file, an implementation file and a moc file from an ui file.
-and returns the corresponding nodes in the above order.
-This builder is only available after using the tool 'qt'. Note: you can
-specify \fB.ui\fP files directly as source
-files to the \fBProgram\fP(),
-\fBLibrary\fP() and \fBSharedLibrary\fP() builders
-without using this builder. Using this builder lets you override the standard
-naming conventions (be careful: prefixes are always prepended to names of
-built files; if you don't want prefixes, you may set them to ``).
-See the \fB$QTDIR\fP variable for more information.
-Example:
-
-.ES
-env.Uic('foo.ui') # -> ['foo.h', 'uic_foo.cc', 'moc_foo.cc']
-env.Uic(target = Split('include/foo.h gen/uicfoo.cc gen/mocfoo.cc'),
- source = 'foo.ui') # -> ['include/foo.h', 'gen/uicfoo.cc', 'gen/mocfoo.cc']
-.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.IP Zip()
-.IP env.Zip()
-Builds a zip archive of the specified files
-and/or directories.
-Unlike most builder methods,
-the
-.BR Zip ()
-builder method may be called multiple times
-for a given target;
-each additional call
-adds to the list of entries
-that will be built into the archive.
-Any source directories will
-be scanned for changes to
-any on-disk files,
-regardless of whether or not
-.B scons
-knows about them from other Builder or function calls.
-
-.ES
-env.Zip('src.zip', 'src')
-
-# Create the stuff.zip file.
-env.Zip('stuff', ['subdir1', 'subdir2'])
-# Also add "another" to the stuff.tar file.
-env.Zip('stuff', 'another')
-.EE
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-'\" END GENERATED BUILDER DESCRIPTIONS
-'\"
-'\" The descriptions above of the various SCons Builders are generated
-'\" from the .xml files that live next to the various Python modules in
-'\" the build enginer library. If you're reading this [gnt]roff file
-'\" with an eye towards patching this man page, you can still submit
-'\" a diff against this text, but it will have to be translated to a
-'\" diff against the underlying .xml file before the patch is actually
-'\" accepted. If you do that yourself, it will make it easier to
-'\" integrate the patch.
-'\"
-'\" END GENERATED BUILDER DESCRIPTIONS
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-
-.P
-All
-targets of builder methods automatically depend on their sources.
-An explicit dependency can
-be specified using the
-.B Depends
-method of a construction environment (see below).
-
-In addition,
-.B scons
-automatically scans
-source files for various programming languages,
-so the dependencies do not need to be specified explicitly.
-By default, SCons can
-C source files,
-C++ source files,
-Fortran source files with
-.B .F
-(POSIX systems only),
-.B .fpp,
-or
-.B .FPP
-file extensions,
-and assembly language files with
-.B .S
-(POSIX systems only),
-.B .spp,
-or
-.B .SPP
-files extensions
-for C preprocessor dependencies.
-SCons also has default support
-for scanning D source files,
-You can also write your own Scanners
-to add support for additional source file types.
-These can be added to the default
-Scanner object used by the
-.BR Object (),
-.BR StaticObject (),
-and
-.BR SharedObject ()
-Builders by adding them
-to the
-.B SourceFileScanner
-object.
-See the section "Scanner Objects"
-below, for more information about
-defining your own Scanner objects
-and using the
-.B SourceFileScanner
-object.
-
-.SS Methods and Functions to Do Things
-In addition to Builder methods,
-.B scons
-provides a number of other construction environment methods
-and global functions to
-manipulate the build configuration.
-
-Usually, a construction environment method
-and global function with the same name both exist
-so that you don't have to remember whether
-to a specific bit of functionality
-must be called with or without a construction environment.
-In the following list,
-if you call something as a global function
-it looks like:
-.ES
-.RI Function( arguments )
-.EE
-and if you call something through a construction
-environment it looks like:
-.ES
-.RI env.Function( arguments )
-.EE
-If you can call the functionality in both ways,
-then both forms are listed.
-
-Global functions may be called from custom Python modules that you
-import into an SConscript file by adding the following
-to the Python module:
-
-.ES
-from SCons.Script import *
-.EE
-
-Except where otherwise noted,
-the same-named
-construction environment method
-and global function
-provide the exact same functionality.
-The only difference is that,
-where appropriate,
-calling the functionality through a construction environment will
-substitute construction variables into
-any supplied strings.
-For example:
-
-.ES
-env = Environment(FOO = 'foo')
-Default('$FOO')
-env.Default('$FOO')
-.EE
-
-In the above example,
-the first call to the global
-.B Default()
-function will actually add a target named
-.B $FOO
-to the list of default targets,
-while the second call to the
-.B env.Default()
-construction environment method
-will expand the value
-and add a target named
-.B foo
-to the list of default targets.
-For more on construction variable expansion,
-see the next section on
-construction variables.
-
-Construction environment methods
-and global functions supported by
-.B scons
-include:
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-'\" BEGIN GENERATED FUNCTION DESCRIPTIONS
-'\"
-'\" The descriptions below of the various SCons functions are generated
-'\" from the .xml files that live next to the various Python modules in
-'\" the build enginer library. If you're reading this [gnt]roff file
-'\" with an eye towards patching this man page, you can still submit
-'\" a diff against this text, but it will have to be translated to a
-'\" diff against the underlying .xml file before the patch is actually
-'\" accepted. If you do that yourself, it will make it easier to
-'\" integrate the patch.
-'\"
-'\" BEGIN GENERATED FUNCTION DESCRIPTIONS
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI Action( action ", [" cmd/str/fun ", [" var ", ...]] [option=" value ", ...])"
-.TP
-.IR env .Action( action ", [" cmd/str/fun ", [" var ", ...]] [option=" value ", ...])"
-Creates an Action object for
-the specified
-.IR action .
-See the section "Action Objects,"
-below, for a complete explanation of the arguments and behavior.
-
-Note that the
-.BR env.Action ()
-form of the invocation will expand
-construction variables in any argument strings,
-including the
-.I action
-argument, at the time it is called
-using the construction variables in the
-.I env
-construction environment through which
-.BR env.Action ()
-was called.
-The
-.BR Action ()
-form delays all variable expansion
-until the Action object is actually used.
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI AddMethod( object ", " function ", [" name ])
-.TP
-.IR env .AddMethod( function ", [" name ])
-When called with the
-.BR AddMethod ()
-form,
-adds the specified
-.I function
-to the specified
-.I object
-as the specified method
-.IR name .
-When called with the
-.BR env.AddMethod ()
-form,
-adds the specified
-.I function
-to the construction environment
-.I env
-as the specified method
-.IR name .
-In both cases, if
-.I name
-is omitted or
-.BR None ,
-the name of the
-specified
-.I function
-itself is used for the method name.
-
-Examples:
-
-.ES
-# Note that the first argument to the function to
-# be attached as a method must be the object through
-# which the method will be called; the Python
-# convention is to call it 'self'.
-def my_method(self, arg):
- print "my_method() got", arg
-
-# Use the global AddMethod() function to add a method
-# to the Environment class. This
-AddMethod(Environment, my_method)
-env = Environment()
-env.my_method('arg')
-
-# Add the function as a method, using the function
-# name for the method call.
-env = Environment()
-env.AddMethod(my_method, 'other_method_name')
-env.other_method_name('another arg')
-.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI AddOption( arguments )
-This function adds a new command-line option to be recognized.
-The specified
-.I arguments
-are the same as supported by the standard Python
-.BR optparse.add_option ()
-method (with a few additional capabilities noted below);
-see the documentation for
-.B optparse
-for a thorough discussion of its option-processing capabities.
-
-In addition to the arguments and values supported by the
-.BR optparse.add_option ()
-method,
-the SCons
-.BR AddOption ()
-function allows you to set the
-.B nargs
-keyword value to
-.B '?'
-(a string with just the question mark)
-to indicate that the specified long option(s) take(s) an
-.I optional
-argument.
-When
-.B "nargs = '?'"
-is passed to the
-.BR AddOption ()
-function, the
-.B const
-keyword argument
-may be used to supply the "default"
-value that should be used when the
-option is specified on the command line
-without an explicit argument.
-
-If no
-.B default=
-keyword argument is supplied when calling
-.BR AddOption (),
-the option will have a default value of
-.BR None .
-
-Once a new command-line option has been added with
-.BR AddOption (),
-the option value may be accessed using
-.BR GetOption ()
-or
-.BR env.GetOption ().
-The value may also be set, using
-.BR SetOption ()
-or
-.BR env.SetOption (),
-if conditions in a
-.B SConscript
-require overriding any default value.
-Note, however, that a
-value specified on the command line will
-.I always
-override a value set by any SConscript file.
-
-Any specified
-.B help=
-strings for the new option(s)
-will be displayed by the
-.B \-H
-or
-.B \-h
-options
-(the latter only if no other help text is
-specified in the SConscript files).
-The help text for the local options specified by
-.BR AddOption ()
-will appear below the SCons options themselves,
-under a separate
-.B "Local Options"
-heading.
-The options will appear in the help text
-in the order in which the
-.BR AddOption ()
-calls occur.
-
-Example:
-
-.ES
-AddOption('--prefix',
- dest='prefix',
- nargs=1, type='string',
- action='store',
- metavar='DIR',
- help='installation prefix')
-env = Environment(PREFIX = GetOption('prefix'))
-.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI AddPostAction( target ", " action )
-.TP
-.IR env .AddPostAction( target ", " action )
-Arranges for the specified
-.I action
-to be performed
-after the specified
-.I target
-has been built.
-The specified action(s) may be
-an Action object, or anything that
-can be converted into an Action object
-(see below).
-
-When multiple targets are supplied,
-the action may be called multiple times,
-once after each action that generates
-one or more targets in the list.
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI AddPreAction( target ", " action )
-.TP
-.IR env .AddPreAction( target ", " action )
-Arranges for the specified
-.I action
-to be performed
-before the specified
-.I target
-is built.
-The specified action(s) may be
-an Action object, or anything that
-can be converted into an Action object
-(see below).
-
-When multiple targets are specified,
-the action(s) may be called multiple times,
-once before each action that generates
-one or more targets in the list.
-
-Note that if any of the targets are built in multiple steps,
-the action will be invoked just
-before the "final" action that specifically
-generates the specified target(s).
-For example, when building an executable program
-from a specified source
-.B .c
-file via an intermediate object file:
-
-.ES
-foo = Program('foo.c')
-AddPreAction(foo, 'pre_action')
-.EE
-.IP
-The specified
-.B pre_action
-would be executed before
-.B scons
-calls the link command that actually
-generates the executable program binary
-.BR foo ,
-not before compiling the
-.B foo.c
-file into an object file.
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI Alias( alias ", [" targets ", [" action ]])
-.TP
-.IR env .Alias( alias ", [" targets ", [" action ]])
-Creates one or more phony targets that
-expand to one or more other targets.
-An optional
-.I action
-(command)
-or list of actions
-can be specified that will be executed
-whenever the any of the alias targets are out-of-date.
-Returns the Node object representing the alias,
-which exists outside of any file system.
-This Node object, or the alias name,
-may be used as a dependency of any other target,
-including another alias.
-.BR Alias ()
-can be called multiple times for the same
-alias to add additional targets to the alias,
-or additional actions to the list for this alias.
-
-Examples:
-
-.ES
-Alias('install')
-Alias('install', '/usr/bin')
-Alias(['install', 'install-lib'], '/usr/local/lib')
-
-env.Alias('install', ['/usr/local/bin', '/usr/local/lib'])
-env.Alias('install', ['/usr/local/man'])
-
-env.Alias('update', ['file1', 'file2'], "update_database $SOURCES")
-.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI AllowSubstExceptions([ exception ", ...])"
-Specifies the exceptions that will be allowed
-when expanding construction variables.
-By default,
-any construction variable expansions that generate a
-.B NameError
-or
-.B IndexError
-exception will expand to a
-.B ''
-(a null string) and not cause scons to fail.
-All exceptions not in the specified list
-will generate an error message
-and terminate processing.
-
-If
-.BR AllowSubstExceptions ()
-is called multiple times,
-each call completely overwrites the previous list
-of allowed exceptions.
-
-Example:
-
-.ES
-# Requires that all construction variable names exist.
-# (You may wish to do this if you want to enforce strictly
-# that all construction variables must be defined before use.)
-AllowSubstExceptions()
-
-# Also allow a string containing a zero-division expansion
-# like '${1 / 0}' to evalute to ''.
-AllowSubstExceptions(IndexError, NameError, ZeroDivisionError)
-.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI AlwaysBuild( target ", ...)"
-.TP
-.IR env .AlwaysBuild( target ", ...)"
-Marks each given
-.I target
-so that it is always assumed to be out of date,
-and will always be rebuilt if needed.
-Note, however, that
-.BR AlwaysBuild ()
-does not add its target(s) to the default target list,
-so the targets will only be built
-if they are specified on the command line,
-or are a dependent of a target specified on the command line--but
-they will
-.I always
-be built if so specified.
-Multiple targets can be passed in to a single call to
-.BR AlwaysBuild ().
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.IR env .Append(key= val ", [...])"
-Appends the specified keyword arguments
-to the end of construction variables in the environment.
-If the Environment does not have
-the specified construction variable,
-it is simply added to the environment.
-If the values of the construction variable
-and the keyword argument are the same type,
-then the two values will be simply added together.
-Otherwise, the construction variable
-and the value of the keyword argument
-are both coerced to lists,
-and the lists are added together.
-(See also the Prepend method, below.)
-
-Example:
-
-.ES
-env.Append(CCFLAGS = ' -g', FOO = ['foo.yyy'])
-.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.IR env .AppendENVPath( name ", " newpath ", [" envname ", " sep ", " delete_existing ])
-This appends new path elements to the given path in the
-specified external environment
-.RB ( ENV
-by default).
-This will only add
-any particular path once (leaving the last one it encounters and
-ignoring the rest, to preserve path order),
-and to help assure this,
-will normalize all paths (using
-.B os.path.normpath
-and
-.BR os.path.normcase ).
-This can also handle the
-case where the given old path variable is a list instead of a
-string, in which case a list will be returned instead of a string.
-
-If
-.I delete_existing
-is 0, then adding a path that already exists
-will not move it to the end; it will stay where it is in the list.
-
-Example:
-
-.ES
-print 'before:',env['ENV']['INCLUDE']
-include_path = '/foo/bar:/foo'
-env.AppendENVPath('INCLUDE', include_path)
-print 'after:',env['ENV']['INCLUDE']
-
-yields:
-before: /foo:/biz
-after: /biz:/foo/bar:/foo
-.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.IR env .AppendUnique(key= val ", [...], delete_existing=" 0)
-Appends the specified keyword arguments
-to the end of construction variables in the environment.
-If the Environment does not have
-the specified construction variable,
-it is simply added to the environment.
-If the construction variable being appended to is a list,
-then any value(s) that already exist in the
-construction variable will
-.I not
-be added again to the list.
-However, if delete_existing is 1,
-existing matching values are removed first, so
-existing values in the arg list move to the end of the list.
-
-Example:
-
-.ES
-env.AppendUnique(CCFLAGS = '-g', FOO = ['foo.yyy'])
-.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.IR env .BitKeeper()
-A factory function that
-returns a Builder object
-to be used to fetch source files
-using BitKeeper.
-The returned Builder
-is intended to be passed to the
-.BR SourceCode ()
-function.
-
-This function is deprecated. For details, see the entry for the
-.BR SourceCode ()
-function.
-
-Example:
-
-.ES
-env.SourceCode('.', env.BitKeeper())
-.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI BuildDir( build_dir ", " src_dir ", [" duplicate ])
-.TP
-.IR env .BuildDir( build_dir ", " src_dir ", [" duplicate ])
-Deprecated synonyms for
-.BR VariantDir ()
-and
-.BR env.VariantDir ().
-The
-.I build_dir
-argument becomes the
-.I variant_dir
-argument of
-.BR VariantDir ()
-or
-.BR env.VariantDir ().
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI Builder( action ", [" arguments ])
-.TP
-.IR env .Builder( action ", [" arguments ])
-Creates a Builder object for
-the specified
-.IR action .
-See the section "Builder Objects,"
-below, for a complete explanation of the arguments and behavior.
-
-Note that the
-.BR env.Builder ()
-form of the invocation will expand
-construction variables in any arguments strings,
-including the
-.I action
-argument,
-at the time it is called
-using the construction variables in the
-.I env
-construction environment through which
-.BR env.Builder ()
-was called.
-The
-.BR Builder ()
-form delays all variable expansion
-until after the Builder object is actually called.
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI CacheDir( cache_dir )
-.TP
-.IR env .CacheDir( cache_dir )
-Specifies that
-.B scons
-will maintain a cache of derived files in
-.IR cache_dir .
-The derived files in the cache will be shared
-among all the builds using the same
-.BR CacheDir ()
-call.
-Specifying a
-.I cache_dir
-of
-.B None
-disables derived file caching.
-
-Calling
-.BR env.CacheDir ()
-will only affect targets built
-through the specified construction environment.
-Calling
-.BR CacheDir ()
-sets a global default
-that will be used by all targets built
-through construction environments
-that do
-.I not
-have an
-.BR env.CacheDir ()
-specified.
-
-When a
-.BR CacheDir ()
-is being used and
-.B scons
-finds a derived file that needs to be rebuilt,
-it will first look in the cache to see if a
-derived file has already been built
-from identical input files and an identical build action
-(as incorporated into the MD5 build signature).
-If so,
-.B scons
-will retrieve the file from the cache.
-If the derived file is not present in the cache,
-.B scons
-will rebuild it and
-then place a copy of the built file in the cache
-(identified by its MD5 build signature),
-so that it may be retrieved by other
-builds that need to build the same derived file
-from identical inputs.
-
-Use of a specified
-.BR CacheDir ()
-may be disabled for any invocation
-by using the
-.B \-\-cache-disable
-option.
-
-If the
-.B \-\-cache-force
-option is used,
-.B scons
-will place a copy of
-.I all
-derived files in the cache,
-even if they already existed
-and were not built by this invocation.
-This is useful to populate a cache
-the first time
-.BR CacheDir ()
-is added to a build,
-or after using the
-.B \-\-cache-disable
-option.
-
-When using
-.BR CacheDir (),
-.B scons
-will report,
-"Retrieved `file' from cache,"
-unless the
-.B \-\-cache-show
-option is being used.
-When the
-.B \-\-cache-show
-option is used,
-.B scons
-will print the action that
-.I would
-have been used to build the file,
-without any indication that
-the file was actually retrieved from the cache.
-This is useful to generate build logs
-that are equivalent regardless of whether
-a given derived file has been built in-place
-or retrieved from the cache.
-
-The
-.BR NoCache ()
-method can be used to disable caching of specific files. This can be
-useful if inputs and/or outputs of some tool are impossible to
-predict or prohibitively large.
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI Clean( targets ", " files_or_dirs )
-.TP
-.IR env .Clean( targets ", " files_or_dirs )
-This specifies a list of files or directories which should be removed
-whenever the targets are specified with the
-.B \-c
-command line option.
-The specified targets may be a list
-or an individual target.
-Multiple calls to
-.BR Clean ()
-are legal,
-and create new targets or add files and directories to the
-clean list for the specified targets.
-
-Multiple files or directories should be specified
-either as separate arguments to the
-.BR Clean ()
-method, or as a list.
-.BR Clean ()
-will also accept the return value of any of the construction environment
-Builder methods.
-Examples:
-
-The related
-.BR NoClean ()
-function overrides calling
-.BR Clean ()
-for the same target,
-and any targets passed to both functions will
-.I not
-be removed by the
-.B \-c
-option.
-
-Examples:
-
-.ES
-Clean('foo', ['bar', 'baz'])
-Clean('dist', env.Program('hello', 'hello.c'))
-Clean(['foo', 'bar'], 'something_else_to_clean')
-.EE
-.IP
-In this example,
-installing the project creates a subdirectory for the documentation.
-This statement causes the subdirectory to be removed
-if the project is deinstalled.
-.ES
-Clean(docdir, os.path.join(docdir, projectname))
-.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.IR env .Clone([key= val ", ...])"
-Returns a separate copy of a construction environment.
-If there are any keyword arguments specified,
-they are added to the returned copy,
-overwriting any existing values
-for the keywords.
-
-Example:
-
-.ES
-env2 = env.Clone()
-env3 = env.Clone(CCFLAGS = '-g')
-.EE
-.IP
-Additionally, a list of tools and a toolpath may be specified, as in
-the Environment constructor:
-
-.ES
-def MyTool(env): env['FOO'] = 'bar'
-env4 = env.Clone(tools = ['msvc', MyTool])
-.EE
-.IP
-The
-.I parse_flags
-keyword argument is also recognized:
-
-.ES
-# create an environment for compiling programs that use wxWidgets
-wx_env = env.Clone(parse_flags = '!wx-config --cflags --cxxflags')
-.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI Command( target ", " source ", " action ", [key=" val ", ...])"
-.TP
-.IR env .Command( target ", " source ", " action ", [key=" val ", ...])"
-Executes a specific action
-(or list of actions)
-to build a target file or files.
-This is more convenient
-than defining a separate Builder object
-for a single special-case build.
-
-As a special case, the
-.I source_scanner
-keyword argument can
-be used to specify
-a Scanner object
-that will be used to scan the sources.
-(The global
-.B DirScanner
-object can be used
-if any of the sources will be directories
-that must be scanned on-disk for
-changes to files that aren't
-already specified in other Builder of function calls.)
-
-Any other keyword arguments specified override any
-same-named existing construction variables.
-
-An action can be an external command,
-specified as a string,
-or a callable Python object;
-see "Action Objects," below,
-for more complete information.
-Also note that a string specifying an external command
-may be preceded by an
-.B @
-(at-sign)
-to suppress printing the command in question,
-or by a
-.B \-
-(hyphen)
-to ignore the exit status of the external command.
-
-Examples:
-
-.ES
-env.Command('foo.out', 'foo.in',
- "$FOO_BUILD < $SOURCES > $TARGET")
-
-env.Command('bar.out', 'bar.in',
- ["rm -f $TARGET",
- "$BAR_BUILD < $SOURCES > $TARGET"],
- ENV = {'PATH' : '/usr/local/bin/'})
-
-def rename(env, target, source):
- import os
- os.rename('.tmp', str(target[0]))
-
-env.Command('baz.out', 'baz.in',
- ["$BAZ_BUILD < $SOURCES > .tmp",
- rename ])
-.EE
-.IP
-Note that the
-.BR Command ()
-function will usually assume, by default,
-that the specified targets and/or sources are Files,
-if no other part of the configuration
-identifies what type of entry it is.
-If necessary, you can explicitly specify
-that targets or source nodes should
-be treated as directoriese
-by using the
-.BR Dir ()
-or
-.BR env.Dir ()
-functions.
-
-Examples:
-
-.ES
-env.Command('ddd.list', Dir('ddd'), 'ls -l $SOURCE > $TARGET')
-
-env['DISTDIR'] = 'destination/directory'
-env.Command(env.Dir('$DISTDIR')), None, make_distdir)
-.EE
-.IP
-(Also note that SCons will usually
-automatically create any directory necessary to hold a target file,
-so you normally don't need to create directories by hand.)
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI Configure( env ", [" custom_tests ", " conf_dir ", " log_file ", " config_h ])
-.TP
-.IR env .Configure([ custom_tests ", " conf_dir ", " log_file ", " config_h ])
-Creates a Configure object for integrated
-functionality similar to GNU autoconf.
-See the section "Configure Contexts,"
-below, for a complete explanation of the arguments and behavior.
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.IR env .Copy([key= val ", ...])"
-A now-deprecated synonym for
-.BR env.Clone ().
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.IR env .CVS( repository ", " module )
-A factory function that
-returns a Builder object
-to be used to fetch source files
-from the specified
-CVS
-.IR repository .
-The returned Builder
-is intended to be passed to the
-.BR SourceCode ()
-function.
-
-This function is deprecated. For details, see the entry for the
-.BR SourceCode ()
-function.
-
-The optional specified
-.I module
-will be added to the beginning
-of all repository path names;
-this can be used, in essence,
-to strip initial directory names
-from the repository path names,
-so that you only have to
-replicate part of the repository
-directory hierarchy in your
-local build directory.
-
-Examples:
-
-.ES
-# Will fetch foo/bar/src.c
-# from /usr/local/CVSROOT/foo/bar/src.c.
-env.SourceCode('.', env.CVS('/usr/local/CVSROOT'))
-
-# Will fetch bar/src.c
-# from /usr/local/CVSROOT/foo/bar/src.c.
-env.SourceCode('.', env.CVS('/usr/local/CVSROOT', 'foo'))
-
-# Will fetch src.c
-# from /usr/local/CVSROOT/foo/bar/src.c.
-env.SourceCode('.', env.CVS('/usr/local/CVSROOT', 'foo/bar'))
-.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI Decider( function )
-.TP
-.IR env .Decider( function )
-Specifies that all up-to-date decisions for
-targets built through this construction environment
-will be handled by the specified
-.IR function .
-The
-.I function
-can be one of the following strings
-that specify the type of decision function
-to be performed:
-
-.RS 10
-.TP 6
-.B timestamp-newer
-Specifies that a target shall be considered out of date and rebuilt
-if the dependency's timestamp is newer than the target file's timestamp.
-This is the behavior of the classic Make utility,
-and
-.B make
-can be used a synonym for
-.BR timestamp-newer .
-.TP 6
-.B timestamp-match
-Specifies that a target shall be considered out of date and rebuilt
-if the dependency's timestamp is different than the
-timestamp recorded the last time the target was built.
-This provides behavior very similar to the classic Make utility
-(in particular, files are not opened up so that their
-contents can be checksummed)
-except that the target will also be rebuilt if a
-dependency file has been restored to a version with an
-.I earlier
-timestamp, such as can happen when restoring files from backup archives.
-.TP 6
-.B MD5
-Specifies that a target shall be considered out of date and rebuilt
-if the dependency's content has changed sine the last time
-the target was built,
-as determined be performing an MD5 checksum
-on the dependency's contents
-and comparing it to the checksum recorded the
-last time the target was built.
-.B content
-can be used as a synonym for
-.BR MD5 .
-.TP 6
-.B MD5-timestamp
-Specifies that a target shall be considered out of date and rebuilt
-if the dependency's content has changed sine the last time
-the target was built,
-except that dependencies with a timestamp that matches
-the last time the target was rebuilt will be
-assumed to be up-to-date and
-.I not
-rebuilt.
-This provides behavior very similar
-to the
-.B MD5
-behavior of always checksumming file contents,
-with an optimization of not checking
-the contents of files whose timestamps haven't changed.
-The drawback is that SCons will
-.I not
-detect if a file's content has changed
-but its timestamp is the same,
-as might happen in an automated script
-that runs a build,
-updates a file,
-and runs the build again,
-all within a single second.
-.RE
-
-Examples:
-
-.ES
-# Use exact timestamp matches by default.
-Decider('timestamp-match')
-
-# Use MD5 content signatures for any targets built
-# with the attached construction environment.
-env.Decider('content')
-.EE
-.IP
-In addition to the above already-available functions,
-the
-.I function
-argument may be an actual Python function
-that takes the following three arguments:
-
-.RS 10
-.IP dependency
-The Node (file) which
-should cause the
-.I target
-to be rebuilt
-if it has "changed" since the last tme
-.I target
-was built.
-.IP target
-The Node (file) being built.
-In the normal case,
-this is what should get rebuilt
-if the
-.I dependency
-has "changed."
-.IP prev_ni
-Stored information about the state of the
-.I dependency
-the last time the
-.I target
-was built.
-This can be consulted to match various
-file characteristics
-such as the timestamp,
-size, or content signature.
-.RE
-
-The
-.I function
-should return a
-.B True
-(non-zero)
-value if the
-.I dependency
-has "changed" since the last time
-the
-.I target
-was built
-(indicating that the target
-.I should
-be rebuilt),
-and
-.B False
-(zero)
-otherwise
-(indicating that the target should
-.I not
-be rebuilt).
-Note that the decision can be made
-using whatever criteria are appopriate.
-Ignoring some or all of the function arguments
-is perfectly normal.
-
-Example:
-
-.ES
-def my_decider(dependency, target, prev_ni):
- return not os.path.exists(str(target))
-
-env.Decider(my_decider)
-.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI Default( targets )
-.TP
-.IR env .Default( targets )
-This specifies a list of default targets,
-which will be built by
-.B scons
-if no explicit targets are given on the command line.
-Multiple calls to
-.BR Default ()
-are legal,
-and add to the list of default targets.
-
-Multiple targets should be specified as
-separate arguments to the
-.BR Default ()
-method, or as a list.
-.BR Default ()
-will also accept the Node returned by any
-of a construction environment's
-builder methods.
-
-Examples:
-
-.ES
-Default('foo', 'bar', 'baz')
-env.Default(['a', 'b', 'c'])
-hello = env.Program('hello', 'hello.c')
-env.Default(hello)
-.EE
-.IP
-An argument to
-.BR Default ()
-of
-.B None
-will clear all default targets.
-Later calls to
-.BR Default ()
-will add to the (now empty) default-target list
-like normal.
-
-The current list of targets added using the
-.BR Default ()
-function or method is available in the
-.B DEFAULT_TARGETS
-list;
-see below.
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI DefaultEnvironment([ args ])
-Creates and returns a default construction environment object.
-This construction environment is used internally by SCons
-in order to execute many of the global functions in this list,
-and to fetch source files transparently
-from source code management systems.
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI Depends( target ", " dependency )
-.TP
-.IR env .Depends( target ", " dependency )
-Specifies an explicit dependency;
-the
-.I target
-will be rebuilt
-whenever the
-.I dependency
-has changed.
-Both the specified
-.I target
-and
-.I dependency
-can be a string
-(usually the path name of a file or directory)
-or Node objects,
-or a list of strings or Node objects
-(such as returned by a Builder call).
-This should only be necessary
-for cases where the dependency
-is not caught by a Scanner
-for the file.
-
-Example:
-
-.ES
-env.Depends('foo', 'other-input-file-for-foo')
-
-mylib = env.Library('mylib.c')
-installed_lib = env.Install('lib', mylib)
-bar = env.Program('bar.c')
-
-# Arrange for the library to be copied into the installation
-# directory before trying to build the "bar" program.
-# (Note that this is for example only. A "real" library
-# dependency would normally be configured through the $LIBS
-# and $LIBPATH variables, not using an env.Depends() call.)
-
-env.Depends(bar, installed_lib)
-.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.IR env .Dictionary([ vars ])
-Returns a dictionary object
-containing copies of all of the
-construction variables in the environment.
-If there are any variable names specified,
-only the specified construction
-variables are returned in the dictionary.
-
-Example:
-
-.ES
-dict = env.Dictionary()
-cc_dict = env.Dictionary('CC', 'CCFLAGS', 'CCCOM')
-.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI Dir( name ", [" directory ])
-.TP
-.IR env .Dir( name ", [" directory ])
-This returns a Directory Node,
-an object that represents the specified directory
-.IR name .
-.I name
-can be a relative or absolute path.
-.I directory
-is an optional directory that will be used as the parent directory.
-If no
-.I directory
-is specified, the current script's directory is used as the parent.
-
-If
-.I name
-is a list, SCons returns a list of Dir nodes.
-Construction variables are expanded in
-.IR name .
-
-Directory Nodes can be used anywhere you
-would supply a string as a directory name
-to a Builder method or function.
-Directory Nodes have attributes and methods
-that are useful in many situations;
-see "File and Directory Nodes," below.
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.IR env .Dump([ key ])
-Returns a pretty printable representation of the environment.
-.IR key ,
-if not
-.BR None ,
-should be a string containing the name of the variable of interest.
-
-This SConstruct:
-
-.ES
-env=Environment()
-print env.Dump('CCCOM')
-.EE
-.IP
-will print:
-
-.ES
-'$CC -c -o $TARGET $CCFLAGS $CPPFLAGS $_CPPDEFFLAGS $_CPPINCFLAGS $SOURCES'
-.EE
-.IP
-While this SConstruct:
-
-.ES
-env=Environment()
-print env.Dump()
-.EE
-.IP
-will print:
-.ES
-{ 'AR': 'ar',
- 'ARCOM': '$AR $ARFLAGS $TARGET $SOURCES\\n$RANLIB $RANLIBFLAGS $TARGET',
- 'ARFLAGS': ['r'],
- 'AS': 'as',
- 'ASCOM': '$AS $ASFLAGS -o $TARGET $SOURCES',
- 'ASFLAGS': [],
- ...
-.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI EnsurePythonVersion( major ", " minor )
-.TP
-.IR env .EnsurePythonVersion( major ", " minor )
-Ensure that the Python version is at least
-.IR major\fP.\fIminor .
-This function will
-print out an error message and exit SCons with a non-zero exit code if the
-actual Python version is not late enough.
-
-Example:
-
-.ES
-EnsurePythonVersion(2,2)
-.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI EnsureSConsVersion( major ", " minor ", [" revision ])
-.TP
-.IR env .EnsureSConsVersion( major ", " minor ", [" revision ])
-Ensure that the SCons version is at least
-.IR major.minor ,
-or
-.IR major.minor.revision .
-if
-.I revision
-is specified.
-This function will
-print out an error message and exit SCons with a non-zero exit code if the
-actual SCons version is not late enough.
-
-Examples:
-
-.ES
-EnsureSConsVersion(0,14)
-
-EnsureSConsVersion(0,96,90)
-.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI Environment([key= value ", ...])"
-.TP
-.IR env .Environment([key= value ", ...])"
-Return a new construction environment
-initialized with the specified
-.IR key = value
-pairs.
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI Execute( action ", [" strfunction ", " varlist ])
-.TP
-.IR env .Execute( action ", [" strfunction ", " varlist ])
-Executes an Action object.
-The specified
-.I action
-may be an Action object
-(see the section "Action Objects,"
-below, for a complete explanation of the arguments and behavior),
-or it may be a command-line string,
-list of commands,
-or executable Python function,
-each of which will be converted
-into an Action object
-and then executed.
-The exit value of the command
-or return value of the Python function
-will be returned.
-
-Note that
-.B scons
-will print an error message if the executed
-.I action
-fails--that is,
-exits with or returns a non-zero value.
-.B scons
-will
-.IR not ,
-however,
-automatically terminate the build
-if the specified
-.I action
-fails.
-If you want the build to stop in response to a failed
-.BR Execute ()
-call,
-you must explicitly check for a non-zero return value:
-
-.ES
-Execute(Copy('file.out', 'file.in'))
-
-if Execute("mkdir sub/dir/ectory"):
- # The mkdir failed, don't try to build.
- Exit(1)
-.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI Exit([ value ])
-.TP
-.IR env .Exit([ value ])
-This tells
-.B scons
-to exit immediately
-with the specified
-.IR value .
-A default exit value of
-.B 0
-(zero)
-is used if no value is specified.
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI Export( vars )
-.TP
-.IR env .Export( vars )
-This tells
-.B scons
-to export a list of variables from the current
-SConscript file to all other SConscript files.
-The exported variables are kept in a global collection,
-so subsequent calls to
-.BR Export ()
-will over-write previous exports that have the same name.
-Multiple variable names can be passed to
-.BR Export ()
-as separate arguments or as a list.
-Keyword arguments can be used to provide names and their values.
-A dictionary can be used to map variables to a different name when exported.
-Both local variables and global variables can be exported.
-
-Examples:
-
-.ES
-env = Environment()
-# Make env available for all SConscript files to Import().
-Export("env")
-
-package = 'my_name'
-# Make env and package available for all SConscript files:.
-Export("env", "package")
-
-# Make env and package available for all SConscript files:
-Export(["env", "package"])
-
-# Make env available using the name debug:
-Export(debug = env)
-
-# Make env available using the name debug:
-Export({"debug":env})
-.EE
-.IP
-Note that the
-.BR SConscript ()
-function supports an
-.I exports
-argument that makes it easier to to export a variable or
-set of variables to a single SConscript file.
-See the description of the
-.BR SConscript ()
-function, below.
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI File( name ", [" directory ])
-.TP
-.IR env .File( name ", [" directory ])
-This returns a
-File Node,
-an object that represents the specified file
-.IR name .
-.I name
-can be a relative or absolute path.
-.I directory
-is an optional directory that will be used as the parent directory.
-
-If
-.I name
-is a list, SCons returns a list of File nodes.
-Construction variables are expanded in
-.IR name .
-
-File Nodes can be used anywhere you
-would supply a string as a file name
-to a Builder method or function.
-File Nodes have attributes and methods
-that are useful in many situations;
-see "File and Directory Nodes," below.
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI FindFile( file ", " dirs )
-.TP
-.IR env .FindFile( file ", " dirs )
-Search for
-.I file
-in the path specified by
-.IR dirs .
-.I dirs
-may be a list of directory names or a single directory name.
-In addition to searching for files that exist in the filesystem,
-this function also searches for derived files
-that have not yet been built.
-
-Example:
-
-.ES
-foo = env.FindFile('foo', ['dir1', 'dir2'])
-.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI FindInstalledFiles()
-.TP
-.IR env .FindInstalledFiles()
-Returns the list of targets set up by the
-.BR Install ()
-or
-.BR InstallAs ()
-builders.
-
-This function serves as a convenient method to select the contents of
-a binary package.
-
-Example:
-
-.ES
-Install( '/bin', [ 'executable_a', 'executable_b' ] )
-
-# will return the file node list
-# [ '/bin/executable_a', '/bin/executable_b' ]
-FindInstalledFiles()
-
-Install( '/lib', [ 'some_library' ] )
-
-# will return the file node list
-# [ '/bin/executable_a', '/bin/executable_b', '/lib/some_library' ]
-FindInstalledFiles()
-.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI FindPathDirs( variable )
-Returns a function
-(actually a callable Python object)
-intended to be used as the
-.I path_function
-of a Scanner object.
-The returned object will look up the specified
-.I variable
-in a construction environment
-and treat the construction variable's value as a list of
-directory paths that should be searched
-(like
-.BR $CPPPATH ,
-.BR $LIBPATH ,
-etc.).
-
-Note that use of
-.BR FindPathDirs ()
-is generally preferable to
-writing your own
-.I path_function
-for the following reasons:
-1) The returned list will contain all appropriate directories
-found in source trees
-(when
-.BR VariantDir ()
-is used)
-or in code repositories
-(when
-.BR Repository ()
-or the
-.B \-Y
-option are used).
-2) scons will identify expansions of
-.I variable
-that evaluate to the same list of directories as,
-in fact, the same list,
-and avoid re-scanning the directories for files,
-when possible.
-
-Example:
-
-.ES
-def my_scan(node, env, path, arg):
- # Code to scan file contents goes here...
- return include_files
-
-scanner = Scanner(name = 'myscanner',
- function = my_scan,
- path_function = FindPathDirs('MYPATH'))
-.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI FindSourceFiles(node= '"."')
-.TP
-.IR env .FindSourceFiles(node= '"."')
-Returns the list of nodes which serve as the source of the built files.
-It does so by inspecting the dependency tree starting at the optional
-argument
-.I node
-which defaults to the '"."'-node. It will then return all leaves of
-.IR node .
-These are all children which have no further children.
-
-This function is a convenient method to select the contents of a Source
-Package.
-
-Example:
-
-.ES
-Program( 'src/main_a.c' )
-Program( 'src/main_b.c' )
-Program( 'main_c.c' )
-
-# returns ['main_c.c', 'src/main_a.c', 'SConstruct', 'src/main_b.c']
-FindSourceFiles()
-
-# returns ['src/main_b.c', 'src/main_a.c' ]
-FindSourceFiles( 'src' )
-.EE
-.IP
-As you can see build support files (SConstruct in the above example)
-will also be returned by this function.
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI Flatten( sequence )
-.TP
-.IR env .Flatten( sequence )
-Takes a sequence (that is, a Python list or tuple)
-that may contain nested sequences
-and returns a flattened list containing
-all of the individual elements in any sequence.
-This can be helpful for collecting
-the lists returned by calls to Builders;
-other Builders will automatically
-flatten lists specified as input,
-but direct Python manipulation of
-these lists does not.
-
-Examples:
-
-.ES
-foo = Object('foo.c')
-bar = Object('bar.c')
-
-# Because `foo' and `bar' are lists returned by the Object() Builder,
-# `objects' will be a list containing nested lists:
-objects = ['f1.o', foo, 'f2.o', bar, 'f3.o']
-
-# Passing such a list to another Builder is all right because
-# the Builder will flatten the list automatically:
-Program(source = objects)
-
-# If you need to manipulate the list directly using Python, you need to
-# call Flatten() yourself, or otherwise handle nested lists:
-for object in Flatten(objects):
- print str(object)
-.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI GetBuildFailures()
-Returns a list of exceptions for the
-actions that failed while
-attempting to build targets.
-Each element in the returned list is a
-.I BuildError
-object
-with the following attributes
-that record various aspects
-of the build failure:
-
-.B .node
-The node that was being built
-when the build failure occurred.
-
-.B .status
-The numeric exit status
-returned by the command or Python function
-that failed when trying to build the
-specified Node.
-
-.B .errstr
-The SCons error string
-describing the build failure.
-(This is often a generic
-message like "Error 2"
-to indicate that an executed
-command exited with a status of 2.)
-
-.B .filename
-The name of the file or
-directory that actually caused the failure.
-This may be different from the
-.B .node
-attribute.
-For example,
-if an attempt to build a target named
-.B sub/dir/target
-fails because the
-.B sub/dir
-directory could not be created,
-then the
-.B .node
-attribute will be
-.B sub/dir/target
-but the
-.B .filename
-attribute will be
-.BR sub/dir .
-
-.B .executor
-The SCons Executor object
-for the target Node
-being built.
-This can be used to retrieve
-the construction environment used
-for the failed action.
-
-.B .action
-The actual SCons Action object that failed.
-This will be one specific action
-out of the possible list of
-actions that would have been
-executed to build the target.
-
-.B .command
-The actual expanded command that was executed and failed,
-after expansion of
-.BR $TARGET ,
-.BR $SOURCE ,
-and other construction variables.
-
-Note that the
-.BR GetBuildFailures ()
-function
-will always return an empty list
-until any build failure has occurred,
-which means that
-.BR GetBuildFailures ()
-will always return an empty list
-while the
-.B SConscript
-files are being read.
-Its primary intended use is
-for functions that will be
-executed before SCons exits
-by passing them to the
-standard Python
-.BR atexit.register ()
-function.
-Example:
-
-.ES
-import atexit
-
-def print_build_failures():
- from SCons.Script import GetBuildFailures
- for bf in GetBuildFailures():
- print "%s failed: %s" % (bf.node, bf.errstr)
-
-atexit.register(print_build_failures)
-.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI GetBuildPath( file ", [...])"
-.TP
-.IR env .GetBuildPath( file ", [...])"
-Returns the
-.B scons
-path name (or names) for the specified
-.I file
-(or files).
-The specified
-.I file
-or files
-may be
-.B scons
-Nodes or strings representing path names.
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI GetLaunchDir()
-.TP
-.IR env .GetLaunchDir()
-Returns the absolute path name of the directory from which
-.B scons
-was initially invoked.
-This can be useful when using the
-.BR \-u ,
-.B \-U
-or
-.B \-D
-options, which internally
-change to the directory in which the
-.B SConstruct
-file is found.
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI GetOption( name )
-.TP
-.IR env .GetOption( name )
-This function provides a way to query the value of
-SCons options set on scons command line
-(or set using the
-.BR SetOption ()
-function).
-The options supported are:
-
-.RS 10
-.TP 6
-.B cache_debug
-which corresponds to --cache-debug;
-.TP 6
-.B cache_disable
-which corresponds to --cache-disable;
-.TP 6
-.B cache_force
-which corresponds to --cache-force;
-.TP 6
-.B cache_show
-which corresponds to --cache-show;
-.TP 6
-.B clean
-which corresponds to -c, --clean and --remove;
-.TP 6
-.B config
-which corresponds to --config;
-.TP 6
-.B directory
-which corresponds to -C and --directory;
-.TP 6
-.B diskcheck
-which corresponds to --diskcheck
-.TP 6
-.B duplicate
-which corresponds to --duplicate;
-.TP 6
-.B file
-which corresponds to -f, --file, --makefile and --sconstruct;
-.TP 6
-.B help
-which corresponds to -h and --help;
-.TP 6
-.B ignore_errors
-which corresponds to --ignore-errors;
-.TP 6
-.B implicit_cache
-which corresponds to --implicit-cache;
-.TP 6
-.B implicit_deps_changed
-which corresponds to --implicit-deps-changed;
-.TP 6
-.B implicit_deps_unchanged
-which corresponds to --implicit-deps-unchanged;
-.TP 6
-.B interactive
-which corresponds to --interact and --interactive;
-.TP 6
-.B keep_going
-which corresponds to -k and --keep-going;
-.TP 6
-.B max_drift
-which corresponds to --max-drift;
-.TP 6
-.B no_exec
-which corresponds to -n, --no-exec, --just-print, --dry-run and --recon;
-.TP 6
-.B no_site_dir
-which corresponds to --no-site-dir;
-.TP 6
-.B num_jobs
-which corresponds to -j and --jobs;
-.TP 6
-.B profile_file
-which corresponds to --profile;
-.TP 6
-.B question
-which corresponds to -q and --question;
-.TP 6
-.B random
-which corresponds to --random;
-.TP 6
-.B repository
-which corresponds to -Y, --repository and --srcdir;
-.TP 6
-.B silent
-which corresponds to -s, --silent and --quiet;
-.TP 6
-.B site_dir
-which corresponds to --site-dir;
-.TP 6
-.B stack_size
-which corresponds to --stack-size;
-.TP 6
-.B taskmastertrace_file
-which corresponds to --taskmastertrace; and
-.TP 6
-.B warn
-which corresponds to --warn and --warning.
-.RE
-
-See the documentation for the
-corresponding command line object for information about each specific
-option.
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI Glob( pattern ", [" ondisk ", " source ", " strings ])
-.TP
-.IR env .Glob( pattern ", [" ondisk ", " source ", " strings ])
-Returns Nodes (or strings) that match the specified
-.IR pattern ,
-relative to the directory of the current
-.B SConscript
-file.
-The
-.BR env.Glob ()
-form performs string substition on
-.I pattern
-and returns whatever matches
-the resulting expanded pattern.
-
-The specified
-.I pattern
-uses Unix shell style metacharacters for matching:
-
-.ES
- * matches everything
- ? matches any single character
- [seq] matches any character in seq
- [!seq] matches any char not in seq
-.EE
-.IP
-If the first character of a filename is a dot,
-it must be matched explicitly.
-Character matches do
-.I not
-span directory separators.
-
-The
-.BR Glob ()
-knows about
-repositories
-(see the
-.BR Repository ()
-function)
-and source directories
-(see the
-.BR VariantDir ()
-function)
-and
-returns a Node (or string, if so configured)
-in the local (SConscript) directory
-if matching Node is found
-anywhere in a corresponding
-repository or source directory.
-
-The
-.I ondisk
-argument may be set to
-.B False
-(or any other non-true value)
-to disable the search for matches on disk,
-thereby only returning matches among
-already-configured File or Dir Nodes.
-The default behavior is to
-return corresponding Nodes
-for any on-disk matches found.
-
-The
-.I source
-argument may be set to
-.B True
-(or any equivalent value)
-to specify that,
-when the local directory is a
-.BR VariantDir (),
-the returned Nodes should be from the
-corresponding source directory,
-not the local directory.
-
-The
-.I strings
-argument may be set to
-.B True
-(or any equivalent value)
-to have the
-.BR Glob ()
-function return strings, not Nodes,
-that represent the matched files or directories.
-The returned strings will be relative to
-the local (SConscript) directory.
-(Note that This may make it easier to perform
-arbitrary manipulation of file names,
-but if the returned strings are
-passed to a different
-.B SConscript
-file,
-any Node translation will be relative
-to the other
-.B SConscript
-directory,
-not the original
-.B SConscript
-directory.)
-
-Examples:
-
-.ES
-Program('foo', Glob('*.c'))
-Zip('/tmp/everything', Glob('.??*') + Glob('*'))
-.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI Help( text )
-.TP
-.IR env .Help( text )
-This specifies help text to be printed if the
-.B \-h
-argument is given to
-.BR scons .
-If
-.BR Help ()
-is called multiple times, the text is appended together in the order
-that
-.BR Help ()
-is called.
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI Ignore( target ", " dependency )
-.TP
-.IR env .Ignore( target ", " dependency )
-The specified dependency file(s)
-will be ignored when deciding if
-the target file(s) need to be rebuilt.
-
-You can also use
-.BR Ignore ()
-to remove a target from the default build.
-In order to do this you must specify the directory the target will
-be built in as the target, and the file you want to skip building
-as the dependency.
-
-Note that this will only remove the dependencies listed from
-the files built by default. It will still be built if that
-dependency is needed by another object being built.
-See the third and forth examples below.
-
-Examples:
-
-.ES
-env.Ignore('foo', 'foo.c')
-env.Ignore('bar', ['bar1.h', 'bar2.h'])
-env.Ignore('.','foobar.obj')
-env.Ignore('bar','bar/foobar.obj')
-.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI Import( vars )
-.TP
-.IR env .Import( vars )
-This tells
-.B scons
-to import a list of variables into the current SConscript file. This
-will import variables that were exported with
-.BR Export ()
-or in the
-.I exports
-argument to
-.BR SConscript ().
-Variables exported by
-.BR SConscript ()
-have precedence.
-Multiple variable names can be passed to
-.BR Import ()
-as separate arguments or as a list. The variable "*" can be used
-to import all variables.
-
-Examples:
-
-.ES
-Import("env")
-Import("env", "variable")
-Import(["env", "variable"])
-Import("*")
-.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI Literal( string )
-.TP
-.IR env .Literal( string )
-The specified
-.I string
-will be preserved as-is
-and not have construction variables expanded.
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI Local( targets )
-.TP
-.IR env .Local( targets )
-The specified
-.I targets
-will have copies made in the local tree,
-even if an already up-to-date copy
-exists in a repository.
-Returns a list of the target Node or Nodes.
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.IR env .MergeFlags( arg ", [" unique ])
-Merges the specified
-.I arg
-values to the construction environment's construction variables.
-If the
-.I arg
-argument is not a dictionary,
-it is converted to one by calling
-.BR env.ParseFlags ()
-on the argument
-before the values are merged.
-Note that
-.I arg
-must be a single value,
-so multiple strings must
-be passed in as a list,
-not as separate arguments to
-.BR env.MergeFlags ().
-
-By default,
-duplicate values are eliminated;
-you can, however, specify
-.B unique=0
-to allow duplicate
-values to be added.
-When eliminating duplicate values,
-any construction variables that end with
-the string
-.B PATH
-keep the left-most unique value.
-All other construction variables keep
-the right-most unique value.
-
-Examples:
-
-.ES
-# Add an optimization flag to $CCFLAGS.
-env.MergeFlags('-O3')
-
-# Combine the flags returned from running pkg-config with an optimization
-# flag and merge the result into the construction variables.
-env.MergeFlags(['!pkg-config gtk+-2.0 --cflags', '-O3'])
-
-# Combine an optimization flag with the flags returned from running pkg-config
-# twice and merge the result into the construction variables.
-env.MergeFlags(['-O3',
- '!pkg-config gtk+-2.0 --cflags --libs',
- '!pkg-config libpng12 --cflags --libs'])
-.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI NoCache( target ", ...)"
-.TP
-.IR env .NoCache( target ", ...)"
-Specifies a list of files which should
-.I not
-be cached whenever the
-.BR CacheDir ()
-method has been activated.
-The specified targets may be a list
-or an individual target.
-
-Multiple files should be specified
-either as separate arguments to the
-.BR NoCache ()
-method, or as a list.
-.BR NoCache ()
-will also accept the return value of any of the construction environment
-Builder methods.
-
-Calling
-.BR NoCache ()
-on directories and other non-File Node types has no effect because
-only File Nodes are cached.
-
-Examples:
-
-.ES
-NoCache('foo.elf')
-NoCache(env.Program('hello', 'hello.c'))
-.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI NoClean( target ", ...)"
-.TP
-.IR env .NoClean( target ", ...)"
-Specifies a list of files or directories which should
-.I not
-be removed whenever the targets (or their dependencies)
-are specified with the
-.B \-c
-command line option.
-The specified targets may be a list
-or an individual target.
-Multiple calls to
-.BR NoClean ()
-are legal,
-and prevent each specified target
-from being removed by calls to the
-.B \-c
-option.
-
-Multiple files or directories should be specified
-either as separate arguments to the
-.BR NoClean ()
-method, or as a list.
-.BR NoClean ()
-will also accept the return value of any of the construction environment
-Builder methods.
-
-Calling
-.BR NoClean ()
-for a target overrides calling
-.BR Clean ()
-for the same target,
-and any targets passed to both functions will
-.I not
-be removed by the
-.B \-c
-option.
-
-Examples:
-
-.ES
-NoClean('foo.elf')
-NoClean(env.Program('hello', 'hello.c'))
-.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.IR env .ParseConfig( command ", [" function ", " unique ])
-Calls the specified
-.I function
-to modify the environment as specified by the output of
-.IR command .
-The default
-.I function
-is
-.BR env.MergeFlags (),
-which expects the output of a typical
-.B *-config
-command
-(for example,
-.BR gtk-config )
-and adds the options
-to the appropriate construction variables.
-By default,
-duplicate values are not
-added to any construction variables;
-you can specify
-.B unique=0
-to allow duplicate
-values to be added.
-
-Interpreted options
-and the construction variables they affect
-are as specified for the
-.BR env.ParseFlags ()
-method (which this method calls).
-See that method's description, below,
-for a table of options and construction variables.
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI ParseDepends( filename ", [" must_exist ", " only_one ])
-.TP
-.IR env .ParseDepends( filename ", [" must_exist ", " only_one ])
-Parses the contents of the specified
-.I filename
-as a list of dependencies in the style of
-.B Make
-or
-.BR mkdep ,
-and explicitly establishes all of the listed dependencies.
-
-By default,
-it is not an error
-if the specified
-.I filename
-does not exist.
-The optional
-.I must_exist
-argument may be set to a non-zero
-value to have
-scons
-throw an exception and
-generate an error if the file does not exist,
-or is otherwise inaccessible.
-
-The optional
-.I only_one
-argument may be set to a non-zero
-value to have
-scons
-thrown an exception and
-generate an error
-if the file contains dependency
-information for more than one target.
-This can provide a small sanity check
-for files intended to be generated
-by, for example, the
-.B "gcc -M"
-flag,
-which should typically only
-write dependency information for
-one output file into a corresponding
-.B .d
-file.
-
-The
-.I filename
-and all of the files listed therein
-will be interpreted relative to
-the directory of the
-.B SConscript
-file which calls the
-.BR ParseDepends ()
-function.
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.IR env .ParseFlags( flags ", ...)"
-Parses one or more strings containing
-typical command-line flags for GCC tool chains
-and returns a dictionary with the flag values
-separated into the appropriate SCons construction variables.
-This is intended as a companion to the
-.BR env.MergeFlags ()
-method, but allows for the values in the returned dictionary
-to be modified, if necessary,
-before merging them into the construction environment.
-(Note that
-.BR env.MergeFlags ()
-will call this method if its argument is not a dictionary,
-so it is usually not necessary to call
-.BR env.ParseFlags ()
-directly unless you want to manipulate the values.)
-
-If the first character in any string is
-an exclamation mark (!),
-the rest of the string is executed as a command,
-and the output from the command is
-parsed as GCC tool chain command-line flags
-and added to the resulting dictionary.
-
-Flag values are translated accordig to the prefix found,
-and added to the following construction variables:
-
-.ES
--arch CCFLAGS, LINKFLAGS
--D CPPDEFINES
--framework FRAMEWORKS
--frameworkdir= FRAMEWORKPATH
--include CCFLAGS
--isysroot CCFLAGS, LINKFLAGS
--I CPPPATH
--l LIBS
--L LIBPATH
--mno-cygwin CCFLAGS, LINKFLAGS
--mwindows LINKFLAGS
--pthread CCFLAGS, LINKFLAGS
--std= CFLAGS
--Wa, ASFLAGS, CCFLAGS
--Wl,-rpath= RPATH
--Wl,-R, RPATH
--Wl,-R RPATH
--Wl, LINKFLAGS
--Wp, CPPFLAGS
-- CCFLAGS
-+ CCFLAGS, LINKFLAGS
-.EE
-.IP
-Any other strings not associated with options
-are assumed to be the names of libraries
-and added to the
-.B $LIBS
-construction variable.
-
-Examples (all of which produce the same result):
-
-.ES
-dict = env.ParseFlags('-O2 -Dfoo -Dbar=1')
-dict = env.ParseFlags('-O2', '-Dfoo', '-Dbar=1')
-dict = env.ParseFlags(['-O2', '-Dfoo -Dbar=1'])
-dict = env.ParseFlags('-O2', '!echo -Dfoo -Dbar=1')
-.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.IR env .Perforce()
-A factory function that
-returns a Builder object
-to be used to fetch source files
-from the Perforce source code management system.
-The returned Builder
-is intended to be passed to the
-.BR SourceCode ()
-function.
-
-This function is deprecated. For details, see the entry for the
-.BR SourceCode ()
-function.
-
-Example:
-
-.ES
-env.SourceCode('.', env.Perforce())
-.EE
-.IP
-Perforce uses a number of external
-environment variables for its operation.
-Consequently, this function adds the
-following variables from the user's external environment
-to the construction environment's
-ENV dictionary:
-P4CHARSET,
-P4CLIENT,
-P4LANGUAGE,
-P4PASSWD,
-P4PORT,
-P4USER,
-SystemRoot,
-USER,
-and
-USERNAME.
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI Platform( string )
-The
-.BR Platform ()
-form returns a callable object
-that can be used to initialize
-a construction environment using the
-platform keyword of the
-.BR Environment ()
-function.
-
-Example:
-
-.ES
-env = Environment(platform = Platform('win32'))
-.EE
-.IP
-The
-.BR env.Platform ()
-form applies the callable object for the specified platform
-.I string
-to the environment through which the method was called.
-
-.ES
-env.Platform('posix')
-.EE
-.IP
-Note that the
-.B win32
-platform adds the
-.B SystemDrive
-and
-.B SystemRoot
-variables from the user's external environment
-to the construction environment's
-.B $ENV
-dictionary.
-This is so that any executed commands
-that use sockets to connect with other systems
-(such as fetching source files from
-external CVS repository specifications like
-.BR :pserver:anonymous@cvs.sourceforge.net:/cvsroot/scons )
-will work on Windows systems.
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI Precious( target ", ...)"
-.TP
-.IR env .Precious( target ", ...)"
-Marks each given
-.I target
-as precious so it is not deleted before it is rebuilt. Normally
-.B scons
-deletes a target before building it.
-Multiple targets can be passed in to a single call to
-.BR Precious ().
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.IR env .Prepend(key= val ", [...])"
-Appends the specified keyword arguments
-to the beginning of construction variables in the environment.
-If the Environment does not have
-the specified construction variable,
-it is simply added to the environment.
-If the values of the construction variable
-and the keyword argument are the same type,
-then the two values will be simply added together.
-Otherwise, the construction variable
-and the value of the keyword argument
-are both coerced to lists,
-and the lists are added together.
-(See also the Append method, above.)
-
-Example:
-
-.ES
-env.Prepend(CCFLAGS = '-g ', FOO = ['foo.yyy'])
-.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.IR env .PrependENVPath( name ", " newpath ", [" envname ", " sep ", " delete_existing ])
-This appends new path elements to the given path in the
-specified external environment
-.RB ( $ENV
-by default).
-This will only add
-any particular path once (leaving the first one it encounters and
-ignoring the rest, to preserve path order),
-and to help assure this,
-will normalize all paths (using
-.B os.path.normpath
-and
-.BR os.path.normcase ).
-This can also handle the
-case where the given old path variable is a list instead of a
-string, in which case a list will be returned instead of a string.
-
-If
-.I delete_existing
-is 0, then adding a path that already exists
-will not move it to the beginning;
-it will stay where it is in the list.
-
-Example:
-
-.ES
-print 'before:',env['ENV']['INCLUDE']
-include_path = '/foo/bar:/foo'
-env.PrependENVPath('INCLUDE', include_path)
-print 'after:',env['ENV']['INCLUDE']
-.EE
-.IP
-The above example will print:
-
-.ES
-before: /biz:/foo
-after: /foo/bar:/foo:/biz
-.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.IR env .PrependUnique(key= val ", delete_existing=" "0, [...])"
-Appends the specified keyword arguments
-to the beginning of construction variables in the environment.
-If the Environment does not have
-the specified construction variable,
-it is simply added to the environment.
-If the construction variable being appended to is a list,
-then any value(s) that already exist in the
-construction variable will
-.I not
-be added again to the list.
-However, if delete_existing is 1,
-existing matching values are removed first, so
-existing values in the arg list move to the front of the list.
-
-Example:
-
-.ES
-env.PrependUnique(CCFLAGS = '-g', FOO = ['foo.yyy'])
-.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI Progress( callable ", [" interval ])
-.TP
-.RI Progress( string ", [" interval ", " file ", " overwrite ])
-.TP
-.RI Progress( list_of_strings ", [" interval ", " file ", " overwrite ])
-Allows SCons to show progress made during the build
-by displaying a string or calling a function while
-evaluating Nodes (e.g. files).
-
-If the first specified argument is a Python callable
-(a function or an object that has a
-.BR __call__ ()
-method),
-the function will be called
-once every
-.I interval
-times a Node is evaluated.
-The callable will be passed the evaluated Node
-as its only argument.
-(For future compatibility,
-it's a good idea to also add
-.B *args
-and
-.B **kw
-as arguments to your function or method.
-This will prevent the code from breaking
-if SCons ever changes the interface
-to call the function with additional arguments in the future.)
-
-An example of a simple custom progress function
-that prints a string containing the Node name
-every 10 Nodes:
-
-.ES
-def my_progress_function(node, *args, **kw):
- print 'Evaluating node %s!' % node
-Progress(my_progress_function, interval=10)
-.EE
-.IP
-A more complicated example of a custom progress display object
-that prints a string containing a count
-every 100 evaluated Nodes.
-Note the use of
-.B \\r
-(a carriage return)
-at the end so that the string
-will overwrite itself on a display:
-
-.ES
-import sys
-class ProgressCounter(object):
- count = 0
- def __call__(self, node, *args, **kw):
- self.count += 100
- sys.stderr.write('Evaluated %s nodes\\r' % self.count)
-Progress(ProgressCounter(), interval=100)
-.EE
-.IP
-If the first argument
-.BR Progress ()
-is a string,
-the string will be displayed
-every
-.I interval
-evaluated Nodes.
-The default is to print the string on standard output;
-an alternate output stream
-may be specified with the
-.B file=
-argument.
-The following will print a series of dots
-on the error output,
-one dot for every 100 evaluated Nodes:
-
-.ES
-import sys
-Progress('.', interval=100, file=sys.stderr)
-.EE
-.IP
-If the string contains the verbatim substring
-.BR $TARGET ,
-it will be replaced with the Node.
-Note that, for performance reasons, this is
-.I not
-a regular SCons variable substition,
-so you can not use other variables
-or use curly braces.
-The following example will print the name of
-every evaluated Node,
-using a
-.B \\r
-(carriage return) to cause each line to overwritten by the next line,
-and the
-.B overwrite=
-keyword argument to make sure the previously-printed
-file name is overwritten with blank spaces:
-
-.ES
-import sys
-Progress('$TARGET\\r', overwrite=True)
-.EE
-.IP
-If the first argument to
-.BR Progress ()
-is a list of strings,
-then each string in the list will be displayed
-in rotating fashion every
-.I interval
-evaluated Nodes.
-This can be used to implement a "spinner"
-on the user's screen as follows:
-
-.ES
-Progress(['-\\r', '\\\\\\r', '|\\r', '/\\r'], interval=5)
-.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.IR env .RCS()
-A factory function that
-returns a Builder object
-to be used to fetch source files
-from RCS.
-The returned Builder
-is intended to be passed to the
-.BR SourceCode ()
-function:
-
-This function is deprecated. For details, see the entry for the
-.BR SourceCode ()
-function.
-
-Examples:
-
-.ES
-env.SourceCode('.', env.RCS())
-.EE
-.IP
-Note that
-.B scons
-will fetch source files
-from RCS subdirectories automatically,
-so configuring RCS
-as demonstrated in the above example
-should only be necessary if
-you are fetching from
-RCS,v
-files in the same
-directory as the source files,
-or if you need to explicitly specify RCS
-for a specific subdirectory.
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.IR env .Replace(key= val ", [...])"
-Replaces construction variables in the Environment
-with the specified keyword arguments.
-
-Example:
-
-.ES
-env.Replace(CCFLAGS = '-g', FOO = 'foo.xxx')
-.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI Repository( directory )
-.TP
-.IR env .Repository( directory )
-Specifies that
-.I directory
-is a repository to be searched for files.
-Multiple calls to
-.BR Repository ()
-are legal,
-and each one adds to the list of
-repositories that will be searched.
-
-To
-.BR scons ,
-a repository is a copy of the source tree,
-from the top-level directory on down,
-which may contain
-both source files and derived files
-that can be used to build targets in
-the local source tree.
-The canonical example would be an
-official source tree maintained by an integrator.
-If the repository contains derived files,
-then the derived files should have been built using
-.BR scons ,
-so that the repository contains the necessary
-signature information to allow
-.B scons
-to figure out when it is appropriate to
-use the repository copy of a derived file,
-instead of building one locally.
-
-Note that if an up-to-date derived file
-already exists in a repository,
-.B scons
-will
-.I not
-make a copy in the local directory tree.
-In order to guarantee that a local copy
-will be made,
-use the
-.BR Local ()
-method.
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI Requires( target ", " prerequisite )
-.TP
-.IR env .Requires( target ", " prerequisite )
-Specifies an order-only relationship
-between the specified target file(s)
-and the specified prerequisite file(s).
-The prerequisite file(s)
-will be (re)built, if necessary,
-.I before
-the target file(s),
-but the target file(s) do not actually
-depend on the prerequisites
-and will not be rebuilt simply because
-the prerequisite file(s) change.
-
-Example:
-
-.ES
-env.Requires('foo', 'file-that-must-be-built-before-foo')
-.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI Return([ vars "..., stop=" ])
-By default,
-this stops processing the current SConscript
-file and returns to the calling SConscript file
-the values of the variables named in the
-.I vars
-string arguments.
-Multiple strings contaning variable names may be passed to
-.BR Return ().
-Any strings that contain white space
-
-The optional
-.B stop=
-keyword argument may be set to a false value
-to continue processing the rest of the SConscript
-file after the
-.BR Return ()
-call.
-This was the default behavior prior to SCons 0.98.
-However, the values returned
-are still the values of the variables in the named
-.I vars
-at the point
-.BR Return ()
-is called.
-
-Examples:
-
-.ES
-# Returns without returning a value.
-Return()
-
-# Returns the value of the 'foo' Python variable.
-Return("foo")
-
-# Returns the values of the Python variables 'foo' and 'bar'.
-Return("foo", "bar")
-
-# Returns the values of Python variables 'val1' and 'val2'.
-Return('val1 val2')
-.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI Scanner( function ", [" argument ", " keys ", " path_function ", " node_class ", " node_factory ", " scan_check ", " recursive ])
-.TP
-.IR env .Scanner( function ", [" argument ", " keys ", " path_function ", " node_class ", " node_factory ", " scan_check ", " recursive ])
-Creates a Scanner object for
-the specified
-.IR function .
-See the section "Scanner Objects,"
-below, for a complete explanation of the arguments and behavior.
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.IR env .SCCS()
-A factory function that
-returns a Builder object
-to be used to fetch source files
-from SCCS.
-The returned Builder
-is intended to be passed to the
-.BR SourceCode ()
-function.
-
-Example:
-
-.ES
-env.SourceCode('.', env.SCCS())
-.EE
-.IP
-Note that
-.B scons
-will fetch source files
-from SCCS subdirectories automatically,
-so configuring SCCS
-as demonstrated in the above example
-should only be necessary if
-you are fetching from
-.B s.SCCS
-files in the same
-directory as the source files,
-or if you need to explicitly specify SCCS
-for a specific subdirectory.
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI SConscript( scripts ", [" exports ", " variant_dir ", " duplicate ])
-.TP
-.IR env .SConscript( scripts ", [" exports ", " variant_dir ", " duplicate ])
-.TP
-.RI SConscript(dirs= subdirs ", [name=" script ", " exports ", " variant_dir ", " duplicate ])
-.TP
-.IR env .SConscript(dirs= subdirs ", [name=" script ", " exports ", " variant_dir ", " duplicate ])
-This tells
-.B scons
-to execute
-one or more subsidiary SConscript (configuration) files.
-Any variables returned by a called script using
-.BR Return ()
-will be returned by the call to
-.BR SConscript ().
-There are two ways to call the
-.BR SConscript ()
-function.
-
-The first way you can call
-.BR SConscript ()
-is to explicitly specify one or more
-.I scripts
-as the first argument.
-A single script may be specified as a string;
-multiple scripts must be specified as a list
-(either explicitly or as created by
-a function like
-.BR Split ()).
-Examples:
-.ES
-SConscript('SConscript') # run SConscript in the current directory
-SConscript('src/SConscript') # run SConscript in the src directory
-SConscript(['src/SConscript', 'doc/SConscript'])
-config = SConscript('MyConfig.py')
-.EE
-.IP
-The second way you can call
-.BR SConscript ()
-is to specify a list of (sub)directory names
-as a
-.BI dirs= subdirs
-keyword argument.
-In this case,
-.B scons
-will, by default,
-execute a subsidiary configuration file named
-.B SConscript
-in each of the specified directories.
-You may specify a name other than
-.B SConscript
-by supplying an optional
-.BI name= script
-keyword argument.
-The first three examples below have the same effect
-as the first three examples above:
-.ES
-SConscript(dirs='.') # run SConscript in the current directory
-SConscript(dirs='src') # run SConscript in the src directory
-SConscript(dirs=['src', 'doc'])
-SConscript(dirs=['sub1', 'sub2'], name='MySConscript')
-.EE
-.IP
-The optional
-.I exports
-argument provides a list of variable names or a dictionary of
-named values to export to the
-.IR script(s) .
-These variables are locally exported only to the specified
-.IR script(s) ,
-and do not affect the global pool of variables used by the
-.BR Export ()
-function.
-The subsidiary
-.I script(s)
-must use the
-.BR Import ()
-function to import the variables.
-Examples:
-.ES
-foo = SConscript('sub/SConscript', exports='env')
-SConscript('dir/SConscript', exports=['env', 'variable'])
-SConscript(dirs='subdir', exports='env variable')
-SConscript(dirs=['one', 'two', 'three'], exports='shared_info')
-.EE
-.IP
-If the optional
-.I variant_dir
-argument is present, it causes an effect equivalent to the
-.BR VariantDir ()
-method described below.
-(If
-.I variant_dir
-is not present, the
-.I duplicate
-argument is ignored.)
-The
-.I variant_dir
-argument is interpreted relative to the directory of the calling
-.B SConscript
-file.
-See the description of the
-.BR VariantDir ()
-function below for additional details and restrictions.
-
-If
-.I variant_dir
-is present,
-the source directory is the directory in which the
-.B SConscript
-file resides and the
-.B SConscript
-file is evaluated as if it were in the
-.I variant_dir
-directory:
-.ES
-SConscript('src/SConscript', variant_dir = 'build')
-.EE
-.IP
-is equivalent to
-
-.ES
-VariantDir('build', 'src')
-SConscript('build/SConscript')
-.EE
-.IP
-This later paradigm is often used when the sources are
-in the same directory as the
-.BR SConstruct :
-
-.ES
-SConscript('SConscript', variant_dir = 'build')
-.EE
-.IP
-is equivalent to
-
-.ES
-VariantDir('build', '.')
-SConscript('build/SConscript')
-.EE
-.IP
-Here are some composite examples:
-
-.ES
-# collect the configuration information and use it to build src and doc
-shared_info = SConscript('MyConfig.py')
-SConscript('src/SConscript', exports='shared_info')
-SConscript('doc/SConscript', exports='shared_info')
-.EE
-
-.ES
-# build debugging and production versions. SConscript
-# can use Dir('.').path to determine variant.
-SConscript('SConscript', variant_dir='debug', duplicate=0)
-SConscript('SConscript', variant_dir='prod', duplicate=0)
-.EE
-
-.ES
-# build debugging and production versions. SConscript
-# is passed flags to use.
-opts = { 'CPPDEFINES' : ['DEBUG'], 'CCFLAGS' : '-pgdb' }
-SConscript('SConscript', variant_dir='debug', duplicate=0, exports=opts)
-opts = { 'CPPDEFINES' : ['NODEBUG'], 'CCFLAGS' : '-O' }
-SConscript('SConscript', variant_dir='prod', duplicate=0, exports=opts)
-.EE
-
-.ES
-# build common documentation and compile for different architectures
-SConscript('doc/SConscript', variant_dir='build/doc', duplicate=0)
-SConscript('src/SConscript', variant_dir='build/x86', duplicate=0)
-SConscript('src/SConscript', variant_dir='build/ppc', duplicate=0)
-.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI SConscriptChdir( value )
-.TP
-.IR env .SConscriptChdir( value )
-By default,
-.B scons
-changes its working directory
-to the directory in which each
-subsidiary SConscript file lives.
-This behavior may be disabled
-by specifying either:
-
-.ES
-SConscriptChdir(0)
-env.SConscriptChdir(0)
-.EE
-.IP
-in which case
-.B scons
-will stay in the top-level directory
-while reading all SConscript files.
-(This may be necessary when building from repositories,
-when all the directories in which SConscript files may be found
-don't necessarily exist locally.)
-You may enable and disable
-this ability by calling
-SConscriptChdir()
-multiple times.
-
-Example:
-
-.ES
-env = Environment()
-SConscriptChdir(0)
-SConscript('foo/SConscript') # will not chdir to foo
-env.SConscriptChdir(1)
-SConscript('bar/SConscript') # will chdir to bar
-.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI SConsignFile([ file ", " dbm_module ])
-.TP
-.IR env .SConsignFile([ file ", " dbm_module ])
-This tells
-.B scons
-to store all file signatures
-in the specified database
-.IR file .
-If the
-.I file
-name is omitted,
-.B .sconsign
-is used by default.
-(The actual file name(s) stored on disk
-may have an appropriated suffix appended
-by the
-.IR dbm_module .)
-If
-.I file
-is not an absolute path name,
-the file is placed in the same directory as the top-level
-.B SConstruct
-file.
-
-If
-.I file
-is
-.BR None ,
-then
-.B scons
-will store file signatures
-in a separate
-.B .sconsign
-file in each directory,
-not in one global database file.
-(This was the default behavior
-prior to SCons 0.96.91 and 0.97.)
-
-The optional
-.I dbm_module
-argument can be used to specify
-which Python database module
-The default is to use a custom
-.B SCons.dblite
-module that uses pickled
-Python data structures,
-and which works on all Python versions.
-
-Examples:
-
-.ES
-# Explicitly stores signatures in ".sconsign.dblite"
-# in the top-level SConstruct directory (the
-# default behavior).
-SConsignFile()
-
-# Stores signatures in the file "etc/scons-signatures"
-# relative to the top-level SConstruct directory.
-SConsignFile("etc/scons-signatures")
-
-# Stores signatures in the specified absolute file name.
-SConsignFile("/home/me/SCons/signatures")
-
-# Stores signatures in a separate .sconsign file
-# in each directory.
-SConsignFile(None)
-.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.IR env .SetDefault(key= val ", [...])"
-Sets construction variables to default values specified with the keyword
-arguments if (and only if) the variables are not already set.
-The following statements are equivalent:
-
-.ES
-env.SetDefault(FOO = 'foo')
-
-if 'FOO' not in env: env['FOO'] = 'foo'
-.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI SetOption( name ", " value )
-.TP
-.IR env .SetOption( name ", " value )
-This function provides a way to set a select subset of the scons command
-line options from a SConscript file. The options supported are:
-
-.RS 10
-.TP 6
-.B clean
-which corresponds to -c, --clean and --remove;
-.TP 6
-.B duplicate
-which corresponds to --duplicate;
-.TP 6
-.B help
-which corresponds to -h and --help;
-.TP 6
-.B implicit_cache
-which corresponds to --implicit-cache;
-.TP 6
-.B max_drift
-which corresponds to --max-drift;
-.TP 6
-.B no_exec
-which corresponds to -n, --no-exec, --just-print, --dry-run and --recon;
-.TP 6
-.B num_jobs
-which corresponds to -j and --jobs;
-.TP 6
-.B random
-which corresponds to --random; and
-.TP 6
-.B stack_size
-which corresponds to --stack-size.
-.RE
-
-See the documentation for the
-corresponding command line object for information about each specific
-option.
-
-Example:
-
-.ES
-SetOption('max_drift', 1)
-.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI SideEffect( side_effect ", " target )
-.TP
-.IR env .SideEffect( side_effect ", " target )
-Declares
-.I side_effect
-as a side effect of building
-.IR target .
-Both
-.I side_effect
-and
-.I target
-can be a list, a file name, or a node.
-A side effect is a target file that is created or updated
-as a side effect of building other targets.
-For example, a Windows PDB
-file is created as a side effect of building the .obj
-files for a static library,
-and various log files are created updated
-as side effects of various TeX commands.
-If a target is a side effect of multiple build commands,
-.B scons
-will ensure that only one set of commands
-is executed at a time.
-Consequently, you only need to use this method
-for side-effect targets that are built as a result of
-multiple build commands.
-
-Because multiple build commands may update
-the same side effect file,
-by default the
-.I side_effect
-target is
-.I not
-automatically removed
-when the
-.I target
-is removed by the
-.B \-c
-option.
-(Note, however, that the
-.I side_effect
-might be removed as part of
-cleaning the directory in which it lives.)
-If you want to make sure the
-.I side_effect
-is cleaned whenever a specific
-.I target
-is cleaned,
-you must specify this explicitly
-with the
-.BR Clean ()
-or
-.BR env.Clean ()
-function.
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI SourceCode( entries ", " builder )
-.TP
-.IR env .SourceCode( entries ", " builder )
-This function and its associate factory functions are deprecated.
-There is no replacement.
-The intended use was to keep a local tree in sync with an archive,
-but in actuality the function only causes the archive
-to be fetched on the first run.
-Synchronizing with the archive is best done external to &SCons;.
-
-Arrange for non-existent source files to
-be fetched from a source code management system
-using the specified
-.IR builder .
-The specified
-.I entries
-may be a Node, string or list of both,
-and may represent either individual
-source files or directories in which
-source files can be found.
-
-For any non-existent source files,
-.B scons
-will search up the directory tree
-and use the first
-.BR SourceCode ()
-builder it finds.
-The specified
-.I builder
-may be
-.BR None ,
-in which case
-.B scons
-will not use a builder to fetch
-source files for the specified
-.IR entries ,
-even if a
-.BR SourceCode ()
-builder has been specified
-for a directory higher up the tree.
-
-.B scons
-will, by default,
-fetch files from SCCS or RCS subdirectories
-without explicit configuration.
-This takes some extra processing time
-to search for the necessary
-source code management files on disk.
-You can avoid these extra searches
-and speed up your build a little
-by disabling these searches as follows:
-
-.ES
-env.SourceCode('.', None)
-.EE
-.IP
-Note that if the specified
-.I builder
-is one you create by hand,
-it must have an associated
-construction environment to use
-when fetching a source file.
-
-.B scons
-provides a set of canned factory
-functions that return appropriate
-Builders for various popular
-source code management systems.
-Canonical examples of invocation include:
-
-.ES
-env.SourceCode('.', env.BitKeeper('/usr/local/BKsources'))
-env.SourceCode('src', env.CVS('/usr/local/CVSROOT'))
-env.SourceCode('/', env.RCS())
-env.SourceCode(['f1.c', 'f2.c'], env.SCCS())
-env.SourceCode('no_source.c', None)
-.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI SourceSignatures( type )
-.TP
-.IR env .SourceSignatures( type )
-Note: Although it is not yet officially deprecated,
-use of this function is discouraged.
-See the
-.BR Decider ()
-function for a more flexible and straightforward way
-to configure SCons' decision-making.
-
-The
-.BR SourceSignatures ()
-function tells
-.B scons
-how to decide if a source file
-(a file that is not built from any other files)
-has changed since the last time it
-was used to build a particular target file.
-Legal values are
-.B MD5
-or
-.BR timestamp .
-
-If the environment method is used,
-the specified type of source signature
-is only used when deciding whether targets
-built with that environment are up-to-date or must be rebuilt.
-If the global function is used,
-the specified type of source signature becomes the default
-used for all decisions
-about whether targets are up-to-date.
-
-.B MD5
-means
-.B scons
-decides that a source file has changed
-if the MD5 checksum of its contents has changed since
-the last time it was used to rebuild a particular target file.
-
-.B timestamp
-means
-.B scons
-decides that a source file has changed
-if its timestamp (modification time) has changed since
-the last time it was used to rebuild a particular target file.
-(Note that although this is similar to the behavior of Make,
-by default it will also rebuild if the dependency is
-.I older
-than the last time it was used to rebuild the target file.)
-
-There is no different between the two behaviors
-for Python
-.BR Value ()
-node objects.
-
-.B MD5
-signatures take longer to compute,
-but are more accurate than
-.B timestamp
-signatures.
-The default value is
-.BR MD5 .
-
-Note that the default
-.BR TargetSignatures ()
-setting (see below)
-is to use this
-.BR SourceSignatures ()
-setting for any target files that are used
-to build other target files.
-Consequently, changing the value of
-.BR SourceSignatures ()
-will, by default,
-affect the up-to-date decision for all files in the build
-(or all files built with a specific construction environment
-when
-.BR env.SourceSignatures ()
-is used).
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI Split( arg )
-.TP
-.IR env .Split( arg )
-Returns a list of file names or other objects.
-If arg is a string,
-it will be split on strings of white-space characters
-within the string,
-making it easier to write long lists of file names.
-If arg is already a list,
-the list will be returned untouched.
-If arg is any other type of object,
-it will be returned as a list
-containing just the object.
-
-Example:
-
-.ES
-files = Split("f1.c f2.c f3.c")
-files = env.Split("f4.c f5.c f6.c")
-files = Split("""
- f7.c
- f8.c
- f9.c
-""")
-.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.IR env .subst( input ", [" raw ", " target ", " source ", " conv ])
-Performs construction variable interpolation
-on the specified string or sequence argument
-.IR input .
-
-By default,
-leading or trailing white space will
-be removed from the result.
-and all sequences of white space
-will be compressed to a single space character.
-Additionally, any
-.B $(
-and
-.B $)
-character sequences will be stripped from the returned string,
-The optional
-.I raw
-argument may be set to
-.B 1
-if you want to preserve white space and
-.BR $( - $)
-sequences.
-The
-.I raw
-argument may be set to
-.B 2
-if you want to strip
-all characters between
-any
-.B $(
-and
-.B $)
-pairs
-(as is done for signature calculation).
-
-If the input is a sequence
-(list or tuple),
-the individual elements of
-the sequence will be expanded,
-and the results will be returned as a list.
-
-The optional
-.I target
-and
-.I source
-keyword arguments
-must be set to lists of
-target and source nodes, respectively,
-if you want the
-.BR $TARGET ,
-.BR $TARGETS ,
-.B $SOURCE
-and
-.B $SOURCES
-to be available for expansion.
-This is usually necessary if you are
-calling
-.BR env.subst ()
-from within a Python function used
-as an SCons action.
-
-Returned string values or sequence elements
-are converted to their string representation by default.
-The optional
-.I conv
-argument
-may specify a conversion function
-that will be used in place of
-the default.
-For example, if you want Python objects
-(including SCons Nodes)
-to be returned as Python objects,
-you can use the Python
-.B lambda
-idiom to pass in an unnamed function
-that simply returns its unconverted argument.
-
-Example:
-
-.ES
-print env.subst("The C compiler is: $CC")
-
-def compile(target, source, env):
- sourceDir = env.subst("${SOURCE.srcdir}",
- target=target,
- source=source)
-
-source_nodes = env.subst('$EXPAND_TO_NODELIST',
- conv=lambda x: x)
-.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI Tag( node ", " tags )
-Annotates file or directory Nodes with
-information about how the
-.BR Package ()
-Builder should package those files or directories.
-All tags are optional.
-
-Examples:
-
-.ES
-# makes sure the built library will be installed with 0644 file
-# access mode
-Tag( Library( 'lib.c' ), UNIX_ATTR="0644" )
-
-# marks file2.txt to be a documentation file
-Tag( 'file2.txt', DOC )
-.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI TargetSignatures( type )
-.TP
-.IR env .TargetSignatures( type )
-Note: Although it is not yet officially deprecated,
-use of this function is discouraged.
-See the
-.BR Decider ()
-function for a more flexible and straightforward way
-to configure SCons' decision-making.
-
-The
-.BR TargetSignatures ()
-function tells
-.B scons
-how to decide if a target file
-(a file that
-.I is
-built from any other files)
-has changed since the last time it
-was used to build some other target file.
-Legal values are
-.BR "build" ;
-.B "content"
-(or its synonym
-.BR "MD5" );
-.BR "timestamp" ;
-or
-.BR "source" .
-
-If the environment method is used,
-the specified type of target signature is only used
-for targets built with that environment.
-If the global function is used,
-the specified type of signature becomes the default
-used for all target files that
-don't have an explicit target signature type
-specified for their environments.
-
-.B "content"
-(or its synonym
-.BR "MD5" )
-means
-.B scons
-decides that a target file has changed
-if the MD5 checksum of its contents has changed since
-the last time it was used to rebuild some other target file.
-This means
-.B scons
-will open up
-MD5 sum the contents
-of target files after they're built,
-and may decide that it does not need to rebuild
-"downstream" target files if a file was
-rebuilt with exactly the same contents as the last time.
-
-.B "timestamp"
-means
-.B scons
-decides that a target file has changed
-if its timestamp (modification time) has changed since
-the last time it was used to rebuild some other target file.
-(Note that although this is similar to the behavior of Make,
-by default it will also rebuild if the dependency is
-.I older
-than the last time it was used to rebuild the target file.)
-
-.B "source"
-means
-.B scons
-decides that a target file has changed
-as specified by the corresponding
-.BR SourceSignatures ()
-setting
-.RB ( "MD5"
-or
-.BR "timestamp" ).
-This means that
-.B scons
-will treat all input files to a target the same way,
-regardless of whether they are source files
-or have been built from other files.
-
-.B "build"
-means
-.B scons
-decides that a target file has changed
-if it has been rebuilt in this invocation
-or if its content or timestamp have changed
-as specified by the corresponding
-.BR SourceSignatures ()
-setting.
-This "propagates" the status of a rebuilt file
-so that other "downstream" target files
-will always be rebuilt,
-even if the contents or the timestamp
-have not changed.
-
-.B "build"
-signatures are fastest because
-.B "content"
-(or
-.BR "MD5" )
-signatures take longer to compute,
-but are more accurate than
-.B "timestamp"
-signatures,
-and can prevent unnecessary "downstream" rebuilds
-when a target file is rebuilt to the exact same contents
-as the previous build.
-The
-.B "source"
-setting provides the most consistent behavior
-when other target files may be rebuilt from
-both source and target input files.
-The default value is
-.BR "source" .
-
-Because the default setting is
-.BR "source" ,
-using
-.BR SourceSignatures ()
-is generally preferable to
-.BR TargetSignatures (),
-so that the up-to-date decision
-will be consistent for all files
-(or all files built with a specific construction environment).
-Use of
-.BR TargetSignatures ()
-provides specific control for how built target files
-affect their "downstream" dependencies.
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI Tool( string ", [" toolpath ", **" kw ])
-.TP
-.IR env .Tool( string ", [" toolpath ", **" kw ])
-The
-.BR Tool ()
-form of the function
-returns a callable object
-that can be used to initialize
-a construction environment using the
-tools keyword of the Environment() method.
-The object may be called with a construction
-environment as an argument,
-in which case the object will
-add the necessary variables
-to the construction environment
-and the name of the tool will be added to the
-.B $TOOLS
-construction variable.
-
-Additional keyword arguments are passed to the tool's
-.BR generate ()
-method.
-
-Examples:
-
-.ES
-env = Environment(tools = [ Tool('msvc') ])
-
-env = Environment()
-t = Tool('msvc')
-t(env) # adds 'msvc' to the TOOLS variable
-u = Tool('opengl', toolpath = ['tools'])
-u(env) # adds 'opengl' to the TOOLS variable
-.EE
-.IP
-The
-.BR env.Tool ()
-form of the function
-applies the callable object for the specified tool
-.I string
-to the environment through which the method was called.
-
-Additional keyword arguments are passed to the tool's
-.BR generate ()
-method.
-
-.ES
-env.Tool('gcc')
-env.Tool('opengl', toolpath = ['build/tools'])
-.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI Value( value ", [" built_value ])
-.TP
-.IR env .Value( value ", [" built_value ])
-Returns a Node object representing the specified Python value. Value
-Nodes can be used as dependencies of targets. If the result of
-calling
-.BI str( value )
-changes between SCons runs, any targets depending on
-.BI Value( value )
-will be rebuilt.
-(This is true even when using timestamps to decide if
-files are up-to-date.)
-When using timestamp source signatures, Value Nodes'
-timestamps are equal to the system time when the Node is created.
-
-The returned Value Node object has a
-.BR write ()
-method that can be used to "build" a Value Node
-by setting a new value.
-The optional
-.I built_value
-argument can be specified
-when the Value Node is created
-to indicate the Node should already be considered
-"built."
-There is a corresponding
-.BR read ()
-method that will return the built value of the Node.
-
-Examples:
-
-.ES
-env = Environment()
-
-def create(target, source, env):
- # A function that will write a 'prefix=$SOURCE'
- # string into the file name specified as the
- # $TARGET.
- f = open(str(target[0]), 'wb')
- f.write('prefix=' + source[0].get_contents())
-
-# Fetch the prefix= argument, if any, from the command
-# line, and use /usr/local as the default.
-prefix = ARGUMENTS.get('prefix', '/usr/local')
-
-# Attach a .Config() builder for the above function action
-# to the construction environment.
-env['BUILDERS']['Config'] = Builder(action = create)
-env.Config(target = 'package-config', source = Value(prefix))
-
-def build_value(target, source, env):
- # A function that "builds" a Python Value by updating
- # the the Python value with the contents of the file
- # specified as the source of the Builder call ($SOURCE).
- target[0].write(source[0].get_contents())
-
-output = env.Value('before')
-input = env.Value('after')
-
-# Attach a .UpdateValue() builder for the above function
-# action to the construction environment.
-env['BUILDERS']['UpdateValue'] = Builder(action = build_value)
-env.UpdateValue(target = Value(output), source = Value(input))
-.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI VariantDir( variant_dir ", " src_dir ", [" duplicate ])
-.TP
-.IR env .VariantDir( variant_dir ", " src_dir ", [" duplicate ])
-Use the
-.BR VariantDir ()
-function to create a copy of your sources in another location:
-if a name under
-.I variant_dir
-is not found but exists under
-.IR src_dir ,
-the file or directory is copied to
-.IR variant_dir .
-Target files can be built in a different directory
-than the original sources by simply refering to the sources (and targets)
-within the variant tree.
-
-.BR VariantDir ()
-can be called multiple times with the same
-.I src_dir
-to set up multiple builds with different options
-.RI ( variants ).
-The
-.I src_dir
-location must be in or underneath the SConstruct file's directory, and
-.I variant_dir
-may not be underneath
-.IR src_dir .
-
-The default behavior is for
-.B scons
-to physically duplicate the source files in the variant tree.
-Thus, a build performed in the variant tree is guaranteed to be identical
-to a build performed in the source tree even if
-intermediate source files are generated during the build,
-or preprocessors or other scanners search for included files
-relative to the source file,
-or individual compilers or other invoked tools are hard-coded
-to put derived files in the same directory as source files.
-
-If possible on the platform,
-the duplication is performed by linking rather than copying;
-see also the
-.B \-\-duplicate
-command-line option.
-Moreover, only the files needed for the build are duplicated;
-files and directories that are not used are not present in
-.IR variant_dir .
-
-Duplicating the source tree may be disabled by setting the
-.B duplicate
-argument to
-.B 0
-(zero).
-This will cause
-.B scons
-to invoke Builders using the path names of source files in
-.I src_dir
-and the path names of derived files within
-.IR variant_dir .
-This is always more efficient than
-.BR duplicate=1 ,
-and is usually safe for most builds
-(but see above for cases that may cause problems).
-
-Note that
-.BR VariantDir ()
-works most naturally with a subsidiary SConscript file.
-However, you would then call the subsidiary SConscript file
-not in the source directory, but in the
-.IR variant_dir ,
-regardless of the value of
-.BR duplicate .
-This is how you tell
-.B scons
-which variant of a source tree to build:
-
-.ES
-# run src/SConscript in two variant directories
-VariantDir('build/variant1', 'src')
-SConscript('build/variant1/SConscript')
-VariantDir('build/variant2', 'src')
-SConscript('build/variant2/SConscript')
-.EE
-.IP
-See also the
-.BR SConscript ()
-function, described above,
-for another way to specify a variant directory
-in conjunction with calling a subsidiary SConscript file.
-
-Examples:
-
-.ES
-# use names in the build directory, not the source directory
-VariantDir('build', 'src', duplicate=0)
-Program('build/prog', 'build/source.c')
-.EE
-
-.ES
-# this builds both the source and docs in a separate subtree
-VariantDir('build', '.', duplicate=0)
-SConscript(dirs=['build/src','build/doc'])
-.EE
-
-.ES
-# same as previous example, but only uses SConscript
-SConscript(dirs='src', variant_dir='build/src', duplicate=0)
-SConscript(dirs='doc', variant_dir='build/doc', duplicate=0)
-.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI WhereIs( program ", [" path ", " pathext ", " reject ])
-.TP
-.IR env .WhereIs( program ", [" path ", " pathext ", " reject ])
-Searches for the specified executable
-.IR program ,
-returning the full path name to the program
-if it is found,
-and returning None if not.
-Searches the specified
-.IR path ,
-the value of the calling environment's PATH
-.RB ( env['ENV']['PATH'] ),
-or the user's current external PATH
-.RB ( os.environ['PATH'] )
-by default.
-On Windows systems, searches for executable
-programs with any of the file extensions
-listed in the specified
-.IR pathext ,
-the calling environment's PATHEXT
-.RB ( env['ENV']['PATHEXT'] )
-or the user's current PATHEXT
-.RB ( os.environ['PATHEXT'] )
-by default.
-Will not select any
-path name or names
-in the specified
-.I reject
-list, if any.
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-'\" END GENERATED FUNCTION DESCRIPTIONS
-'\"
-'\" The descriptions above of the various SCons functions are generated
-'\" from the .xml files that live next to the various Python modules in
-'\" the build enginer library. If you're reading this [gnt]roff file
-'\" with an eye towards patching this man page, you can still submit
-'\" a diff against this text, but it will have to be translated to a
-'\" diff against the underlying .xml file before the patch is actually
-'\" accepted. If you do that yourself, it will make it easier to
-'\" integrate the patch.
-'\"
-'\" END GENERATED FUNCTION DESCRIPTIONS
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-
-.SS SConscript Variables
-In addition to the global functions and methods,
-.B scons
-supports a number of Python variables
-that can be used in SConscript files
-to affect how you want the build to be performed.
-These variables may be accessed from custom Python modules that you
-import into an SConscript file by adding the following
-to the Python module:
-
-.ES
-from SCons.Script import *
-.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-ARGLIST
-A list
-.IR keyword = value
-arguments specified on the command line.
-Each element in the list is a tuple
-containing the
-.RI ( keyword , value )
-of the argument.
-The separate
-.I keyword
-and
-.I value
-elements of the tuple
-can be accessed by
-subscripting for element
-.B [0]
-and
-.B [1]
-of the tuple, respectively.
-
-Example:
-
-.ES
-print "first keyword, value =", ARGLIST[0][0], ARGLIST[0][1]
-print "second keyword, value =", ARGLIST[1][0], ARGLIST[1][1]
-third_tuple = ARGLIST[2]
-print "third keyword, value =", third_tuple[0], third_tuple[1]
-for key, value in ARGLIST:
- # process key and value
-.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-ARGUMENTS
-A dictionary of all the
-.IR keyword = value
-arguments specified on the command line.
-The dictionary is not in order,
-and if a given keyword has
-more than one value assigned to it
-on the command line,
-the last (right-most) value is
-the one in the
-.B ARGUMENTS
-dictionary.
-
-Example:
-
-.ES
-if ARGUMENTS.get('debug', 0):
- env = Environment(CCFLAGS = '-g')
-else:
- env = Environment()
-.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-BUILD_TARGETS
-A list of the targets which
-.B scons
-will actually try to build,
-regardless of whether they were specified on
-the command line or via the
-.BR Default ()
-function or method.
-The elements of this list may be strings
-.I or
-nodes, so you should run the list through the Python
-.B str
-function to make sure any Node path names
-are converted to strings.
-
-Because this list may be taken from the
-list of targets specified using the
-.BR Default ()
-function or method,
-the contents of the list may change
-on each successive call to
-.BR Default ().
-See the
-.B DEFAULT_TARGETS
-list, below,
-for additional information.
-
-Example:
-
-.ES
-if 'foo' in BUILD_TARGETS:
- print "Don't forget to test the `foo' program!"
-if 'special/program' in BUILD_TARGETS:
- SConscript('special')
-.EE
-.IP
-Note that the
-.B BUILD_TARGETS
-list only contains targets expected listed
-on the command line or via calls to the
-.BR Default ()
-function or method.
-It does
-.I not
-contain all dependent targets that will be built as
-a result of making the sure the explicitly-specified
-targets are up to date.
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-COMMAND_LINE_TARGETS
-A list of the targets explicitly specified on
-the command line.
-If there are no targets specified on the command line,
-the list is empty.
-This can be used, for example,
-to take specific actions only
-when a certain target or targets
-is explicitly being built.
-
-Example:
-
-.ES
-if 'foo' in COMMAND_LINE_TARGETS:
- print "Don't forget to test the `foo' program!"
-if 'special/program' in COMMAND_LINE_TARGETS:
- SConscript('special')
-.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-DEFAULT_TARGETS
-A list of the target
-.I nodes
-that have been specified using the
-.BR Default ()
-function or method.
-The elements of the list are nodes,
-so you need to run them through the Python
-.B str
-function to get at the path name for each Node.
-
-Example:
-
-.ES
-print str(DEFAULT_TARGETS[0])
-if 'foo' in map(str, DEFAULT_TARGETS):
- print "Don't forget to test the `foo' program!"
-.EE
-.IP
-The contents of the
-.B DEFAULT_TARGETS
-list change on on each successive call to the
-.BR Default ()
-function:
-
-.ES
-print map(str, DEFAULT_TARGETS) # originally []
-Default('foo')
-print map(str, DEFAULT_TARGETS) # now a node ['foo']
-Default('bar')
-print map(str, DEFAULT_TARGETS) # now a node ['foo', 'bar']
-Default(None)
-print map(str, DEFAULT_TARGETS) # back to []
-.EE
-.IP
-Consequently, be sure to use
-.B DEFAULT_TARGETS
-only after you've made all of your
-.BR Default ()
-calls,
-or else simply be careful of the order
-of these statements in your SConscript files
-so that you don't look for a specific
-default target before it's actually been added to the list.
-
-.SS Construction Variables
-.\" XXX From Gary Ruben, 23 April 2002:
-.\" I think it would be good to have an example with each construction
-.\" variable description in the documentation.
-.\" eg.
-.\" CC The C compiler
-.\" Example: env["CC"] = "c68x"
-.\" Default: env["CC"] = "cc"
-.\"
-.\" CCCOM The command line ...
-.\" Example:
-.\" To generate the compiler line c68x -ps -qq -mr -o $TARGET $SOURCES
-.\" env["CC"] = "c68x"
-.\" env["CFLAGS"] = "-ps -qq -mr"
-.\" env["CCCOM"] = "$CC $CFLAGS -o $TARGET $SOURCES
-.\" Default:
-.\" (I dunno what this is ;-)
-A construction environment has an associated dictionary of
-.I construction variables
-that are used by built-in or user-supplied build rules.
-Construction variables must follow the same rules for
-Python identifiers:
-the initial character must be an underscore or letter,
-followed by any number of underscores, letters, or digits.
-
-A number of useful construction variables are automatically defined by
-scons for each supported platform, and additional construction variables
-can be defined by the user. The following is a list of the automatically
-defined construction variables:
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-'\" BEGIN GENERATED CONSTRUCTION VARIABLE DESCRIPTIONS
-'\"
-'\" The descriptions below of the various SCons construction variables
-'\" are generated from the .xml files that live next to the various
-'\" Python modules in the build enginer library. If you're reading
-'\" this [gnt]roff file with an eye towards patching this man page,
-'\" you can still submit a diff against this text, but it will have to
-'\" be translated to a diff against the underlying .xml file before the
-'\" patch is actually accepted. If you do that yourself, it will make
-'\" it easier to integrate the patch.
-'\"
-'\" BEGIN GENERATED CONSTRUCTION VARIABLE DESCRIPTIONS
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-
-.IP AR
-The static library archiver.
-
-.IP ARCHITECTURE
-Specifies the system architecture for which
-the package is being built.
-The default is the system architecture
-of the machine on which SCons is running.
-This is used to fill in the
-.B Architecture:
-field in an Ipkg
-\fBcontrol\fP file,
-and as part of the name of a generated RPM file.
-
-.IP ARCOM
-The command line used to generate a static library from object files.
-
-.IP ARCOMSTR
-The string displayed when an object file
-is generated from an assembly-language source file.
-If this is not set, then \fB$ARCOM\fP (the command line) is displayed.
-
-.ES
-env = Environment(ARCOMSTR = "Archiving $TARGET")
-.EE
-
-.IP ARFLAGS
-General options passed to the static library archiver.
-
-.IP AS
-The assembler.
-
-.IP ASCOM
-The command line used to generate an object file
-from an assembly-language source file.
-
-.IP ASCOMSTR
-The string displayed when an object file
-is generated from an assembly-language source file.
-If this is not set, then \fB$ASCOM\fP (the command line) is displayed.
-
-.ES
-env = Environment(ASCOMSTR = "Assembling $TARGET")
-.EE
-
-.IP ASFLAGS
-General options passed to the assembler.
-
-.IP ASPPCOM
-The command line used to assemble an assembly-language
-source file into an object file
-after first running the file through the C preprocessor.
-Any options specified
-in the \fB$ASFLAGS\fP and \fB$CPPFLAGS\fP construction variables
-are included on this command line.
-
-.IP ASPPCOMSTR
-The string displayed when an object file
-is generated from an assembly-language source file
-after first running the file through the C preprocessor.
-If this is not set, then \fB$ASPPCOM\fP (the command line) is displayed.
-
-.ES
-env = Environment(ASPPCOMSTR = "Assembling $TARGET")
-.EE
-
-.IP ASPPFLAGS
-General options when an assembling an assembly-language
-source file into an object file
-after first running the file through the C preprocessor.
-The default is to use the value of \fB$ASFLAGS\fP.
-
-.IP BIBTEX
-The bibliography generator for the TeX formatter and typesetter and the
-LaTeX structured formatter and typesetter.
-
-.IP BIBTEXCOM
-The command line used to call the bibliography generator for the
-TeX formatter and typesetter and the LaTeX structured formatter and
-typesetter.
-
-.IP BIBTEXCOMSTR
-The string displayed when generating a bibliography
-for TeX or LaTeX.
-If this is not set, then \fB$BIBTEXCOM\fP (the command line) is displayed.
-
-.ES
-env = Environment(BIBTEXCOMSTR = "Generating bibliography $TARGET")
-.EE
-
-.IP BIBTEXFLAGS
-General options passed to the bibliography generator for the TeX formatter
-and typesetter and the LaTeX structured formatter and typesetter.
-
-.IP BITKEEPER
-The BitKeeper executable.
-
-.IP BITKEEPERCOM
-The command line for
-fetching source files using BitKeeper.
-
-.IP BITKEEPERCOMSTR
-The string displayed when fetching
-a source file using BitKeeper.
-If this is not set, then \fB$BITKEEPERCOM\fP
-(the command line) is displayed.
-
-.IP BITKEEPERGET
-The command (\fB$BITKEEPER\fP) and subcommand
-for fetching source files using BitKeeper.
-
-.IP BITKEEPERGETFLAGS
-Options that are passed to the BitKeeper
-.B get
-subcommand.
-
-.IP BUILDERS
-A dictionary mapping the names of the builders
-available through this environment
-to underlying Builder objects.
-Builders named
-Alias, CFile, CXXFile, DVI, Library, Object, PDF, PostScript, and Program
-are available by default.
-If you initialize this variable when an
-Environment is created:
-
-.ES
-env = Environment(BUILDERS = {'NewBuilder' : foo})
-.EE
-.IP
-the default Builders will no longer be available.
-To use a new Builder object in addition to the default Builders,
-add your new Builder object like this:
-
-.ES
-env = Environment()
-env.Append(BUILDERS = {'NewBuilder' : foo})
-.EE
-.IP
-or this:
-
-.ES
-env = Environment()
-env['BUILDERS]['NewBuilder'] = foo
-.EE
-
-.IP CC
-The C compiler.
-
-.IP CCCOM
-The command line used to compile a C source file to a (static) object
-file. Any options specified in the \fB$CFLAGS\fP, \fB$CCFLAGS\fP and
-\fB$CPPFLAGS\fP construction variables are included on this command
-line.
-
-.IP CCCOMSTR
-The string displayed when a C source file
-is compiled to a (static) object file.
-If this is not set, then \fB$CCCOM\fP (the command line) is displayed.
-
-.ES
-env = Environment(CCCOMSTR = "Compiling static object $TARGET")
-.EE
-
-.IP CCFLAGS
-General options that are passed to the C and C++ compilers.
-
-.IP CCPCHFLAGS
-Options added to the compiler command line
-to support building with precompiled headers.
-The default value expands expands to the appropriate
-Microsoft Visual C++ command-line options
-when the \fB$PCH\fP construction variable is set.
-
-.IP CCPDBFLAGS
-Options added to the compiler command line
-to support storing debugging information in a
-Microsoft Visual C++ PDB file.
-The default value expands expands to appropriate
-Microsoft Visual C++ command-line options
-when the \fB$PDB\fP construction variable is set.
-
-The Visual C++ compiler option that SCons uses by default
-to generate PDB information is \fB/Z7\fP.
-This works correctly with parallel (\fB\-j\fP) builds
-because it embeds the debug information in the intermediate object files,
-as opposed to sharing a single PDB file between multiple object files.
-This is also the only way to get debug information
-embedded into a static library.
-Using the \fB/Zi\fP instead may yield improved
-link-time performance,
-although parallel builds will no longer work.
-
-You can generate PDB files with the \fB/Zi\fP
-switch by overriding the default \fB$CCPDBFLAGS\fP variable as follows:
-
-.ES
-env['CCPDBFLAGS'] = ['${(PDB and "/Zi /Fd%s" % File(PDB)) or ""}']
-.EE
-.IP
-An alternative would be to use the \fB/Zi\fP
-to put the debugging information in a separate \fB.pdb\fP
-file for each object file by overriding
-the \fB$CCPDBFLAGS\fP variable as follows:
-
-.ES
-env['CCPDBFLAGS'] = '/Zi /Fd${TARGET}.pdb'
-.EE
-
-.IP CCVERSION
-The version number of the C compiler.
-This may or may not be set,
-depending on the specific C compiler being used.
-
-.IP CFILESUFFIX
-The suffix for C source files.
-This is used by the internal CFile builder
-when generating C files from Lex (.l) or YACC (.y) input files.
-The default suffix, of course, is
-.B .c
-(lower case).
-On case-insensitive systems (like Windows),
-SCons also treats
-.B .C
-(upper case) files
-as C files.
-
-.IP CFLAGS
-General options that are passed to the C compiler (C only; not C++).
-
-.IP CHANGE_SPECFILE
-A hook for modifying the file that controls the packaging build
-(the \fB.spec\fP for RPM,
-the \fBcontrol\fP for Ipkg,
-the \fB.wxs\fP for MSI).
-If set, the function will be called
-after the SCons template for the file has been written.
-XXX
-
-.IP CHANGED_SOURCES
-A reserved variable name
-that may not be set or used in a construction environment.
-(See "Variable Substitution," below.)
-
-.IP CHANGED_TARGETS
-A reserved variable name
-that may not be set or used in a construction environment.
-(See "Variable Substitution," below.)
-
-.IP CHANGELOG
-The name of a file containing the change log text
-to be included in the package.
-This is included as the
-.B %changelog
-section of the RPM
-\fB.spec\fP file.
-
-.IP _concat
-A function used to produce variables like \fB$_CPPINCFLAGS\fP. It takes
-four or five
-arguments: a prefix to concatenate onto each element, a list of
-elements, a suffix to concatenate onto each element, an environment
-for variable interpolation, and an optional function that will be
-called to transform the list before concatenation.
-
-.ES
-env['_CPPINCFLAGS'] = '$( ${_concat(INCPREFIX, CPPPATH, INCSUFFIX, __env__, RDirs)} $)',
-.EE
-
-.IP CONFIGUREDIR
-The name of the directory in which
-Configure context test files are written.
-The default is
-.B .sconf_temp
-in the top-level directory
-containing the
-.B SConstruct
-file.
-
-.IP CONFIGURELOG
-The name of the Configure context log file.
-The default is
-.B config.log
-in the top-level directory
-containing the
-.B SConstruct
-file.
-
-.IP _CPPDEFFLAGS
-An automatically-generated construction variable
-containing the C preprocessor command-line options
-to define values.
-The value of \fB$_CPPDEFFLAGS\fP is created
-by appending \fB$CPPDEFPREFIX\fP and \fB$CPPDEFSUFFIX\fP
-to the beginning and end
-of each definition in \fB$CPPDEFINES\fP.
-
-.IP CPPDEFINES
-A platform independent specification of C preprocessor definitions.
-The definitions will be added to command lines
-through the automatically-generated
-\fB$_CPPDEFFLAGS\fP construction variable (see above),
-which is constructed according to
-the type of value of \fB$CPPDEFINES\fP:
-
-If \fB$CPPDEFINES\fP is a string,
-the values of the
-.BR $CPPDEFPREFIX and $CPPDEFSUFFIX
-construction variables
-will be added to the beginning and end.
-
-.ES
-# Will add -Dxyz to POSIX compiler command lines,
-# and /Dxyz to Microsoft Visual C++ command lines.
-env = Environment(CPPDEFINES='xyz')
-.EE
-.IP
-If \fB$CPPDEFINES\fP is a list,
-the values of the
-.BR $CPPDEFPREFIX and $CPPDEFSUFFIX
-construction variables
-will be appended to the beginning and end
-of each element in the list.
-If any element is a list or tuple,
-then the first item is the name being
-defined and the second item is its value:
-
-.ES
-# Will add -DB=2 -DA to POSIX compiler command lines,
-# and /DB=2 /DA to Microsoft Visual C++ command lines.
-env = Environment(CPPDEFINES=[('B', 2), 'A'])
-.EE
-.IP
-If \fB$CPPDEFINES\fP is a dictionary,
-the values of the
-.BR $CPPDEFPREFIX and $CPPDEFSUFFIX
-construction variables
-will be appended to the beginning and end
-of each item from the dictionary.
-The key of each dictionary item
-is a name being defined
-to the dictionary item's corresponding value;
-if the value is
-.BR None ,
-then the name is defined without an explicit value.
-Note that the resulting flags are sorted by keyword
-to ensure that the order of the options on the
-command line is consistent each time
-.B scons
-is run.
-
-.ES
-# Will add -DA -DB=2 to POSIX compiler command lines,
-# and /DA /DB=2 to Microsoft Visual C++ command lines.
-env = Environment(CPPDEFINES={'B':2, 'A':None})
-.EE
-
-.IP CPPDEFPREFIX
-The prefix used to specify preprocessor definitions
-on the C compiler command line.
-This will be appended to the beginning of each definition
-in the \fB$CPPDEFINES\fP construction variable
-when the \fB$_CPPDEFFLAGS\fP variable is automatically generated.
-
-.IP CPPDEFSUFFIX
-The suffix used to specify preprocessor definitions
-on the C compiler command line.
-This will be appended to the end of each definition
-in the \fB$CPPDEFINES\fP construction variable
-when the \fB$_CPPDEFFLAGS\fP variable is automatically generated.
-
-.IP CPPFLAGS
-User-specified C preprocessor options.
-These will be included in any command that uses the C preprocessor,
-including not just compilation of C and C++ source files
-via the \fB$CCCOM\fP,
-.BR $SHCCCOM ,
-\fB$CXXCOM\fP and
-\fB$SHCXXCOM\fP command lines,
-but also the \fB$FORTRANPPCOM\fP,
-.BR $SHFORTRANPPCOM ,
-\fB$F77PPCOM\fP and
-\fB$SHF77PPCOM\fP command lines
-used to compile a Fortran source file,
-and the \fB$ASPPCOM\fP command line
-used to assemble an assembly language source file,
-after first running each file through the C preprocessor.
-Note that this variable does
-.I not
-contain
-.B \-I
-(or similar) include search path options
-that scons generates automatically from \fB$CPPPATH\fP.
-See \fB$_CPPINCFLAGS\fP, below,
-for the variable that expands to those options.
-
-.IP _CPPINCFLAGS
-An automatically-generated construction variable
-containing the C preprocessor command-line options
-for specifying directories to be searched for include files.
-The value of \fB$_CPPINCFLAGS\fP is created
-by appending \fB$INCPREFIX\fP and \fB$INCSUFFIX\fP
-to the beginning and end
-of each directory in \fB$CPPPATH\fP.
-
-.IP CPPPATH
-The list of directories that the C preprocessor will search for include
-directories. The C/C++ implicit dependency scanner will search these
-directories for include files. Don't explicitly put include directory
-arguments in CCFLAGS or CXXFLAGS because the result will be non-portable
-and the directories will not be searched by the dependency scanner. Note:
-directory names in CPPPATH will be looked-up relative to the SConscript
-directory when they are used in a command. To force
-.B scons
-to look-up a directory relative to the root of the source tree use #:
-
-.ES
-env = Environment(CPPPATH='#/include')
-.EE
-.IP
-The directory look-up can also be forced using the
-.BR Dir ()
-function:
-
-.ES
-include = Dir('include')
-env = Environment(CPPPATH=include)
-.EE
-.IP
-The directory list will be added to command lines
-through the automatically-generated
-.B $_CPPINCFLAGS
-construction variable,
-which is constructed by
-appending the values of the
-.BR $INCPREFIX and $INCSUFFIX
-construction variables
-to the beginning and end
-of each directory in \fB$CPPPATH\fP.
-Any command lines you define that need
-the CPPPATH directory list should
-include \fB$_CPPINCFLAGS\fP:
-
-.ES
-env = Environment(CCCOM="my_compiler $_CPPINCFLAGS -c -o $TARGET $SOURCE")
-.EE
-
-.IP CPPSUFFIXES
-The list of suffixes of files that will be scanned
-for C preprocessor implicit dependencies
-(#include lines).
-The default list is:
-
-.ES
-[".c", ".C", ".cxx", ".cpp", ".c++", ".cc",
- ".h", ".H", ".hxx", ".hpp", ".hh",
- ".F", ".fpp", ".FPP",
- ".m", ".mm",
- ".S", ".spp", ".SPP"]
-.EE
-
-.IP CVS
-The CVS executable.
-
-.IP CVSCOFLAGS
-Options that are passed to the CVS checkout subcommand.
-
-.IP CVSCOM
-The command line used to
-fetch source files from a CVS repository.
-
-.IP CVSCOMSTR
-The string displayed when fetching
-a source file from a CVS repository.
-If this is not set, then \fB$CVSCOM\fP
-(the command line) is displayed.
-
-.IP CVSFLAGS
-General options that are passed to CVS.
-By default, this is set to
-.B "-d $CVSREPOSITORY"
-to specify from where the files must be fetched.
-
-.IP CVSREPOSITORY
-The path to the CVS repository.
-This is referenced in the default
-\fB$CVSFLAGS\fP value.
-
-.IP CXX
-The C++ compiler.
-
-.IP CXXCOM
-The command line used to compile a C++ source file to an object file.
-Any options specified in the \fB$CXXFLAGS\fP and
-\fB$CPPFLAGS\fP construction variables
-are included on this command line.
-
-.IP CXXCOMSTR
-The string displayed when a C++ source file
-is compiled to a (static) object file.
-If this is not set, then \fB$CXXCOM\fP (the command line) is displayed.
-
-.ES
-env = Environment(CXXCOMSTR = "Compiling static object $TARGET")
-.EE
-
-.IP CXXFILESUFFIX
-The suffix for C++ source files.
-This is used by the internal CXXFile builder
-when generating C++ files from Lex (.ll) or YACC (.yy) input files.
-The default suffix is
-.BR .cc .
-SCons also treats files with the suffixes
-.BR .cpp ,
-.BR .cxx ,
-.BR .c++ ,
-and
-.B .C++
-as C++ files,
-and files with
-.B .mm
-suffixes as Objective C++ files.
-On case-sensitive systems (Linux, UNIX, and other POSIX-alikes),
-SCons also treats
-.B .C
-(upper case) files
-as C++ files.
-
-.IP CXXFLAGS
-General options that are passed to the C++ compiler.
-By default, this includes the value of \fB$CCFLAGS\fP,
-so that setting \fB$CCFLAGS\fP affects both C and C++ compilation.
-If you want to add C++-specific flags,
-you must set or override the value of \fB$CXXFLAGS\fP.
-
-.IP CXXVERSION
-The version number of the C++ compiler.
-This may or may not be set,
-depending on the specific C++ compiler being used.
-
-.IP DESCRIPTION
-A long description of the project being packaged.
-This is included in the relevant section
-of the file that controls the packaging build.
-
-.IP DESCRIPTION_lang
-A language-specific long description for
-the specified \fIlang\fP.
-This is used to populate a
-.B "%description -l"
-section of an RPM
-\fB.spec\fP file.
-
-.IP Dir
-A function that converts a string
-into a Dir instance relative to the target being built.
-
-.IP Dirs
-A function that converts a list of strings
-into a list of Dir instances relative to the target being built.
-
-.IP DSUFFIXES
-The list of suffixes of files that will be scanned
-for imported D package files.
-The default list is:
-
-.ES
-['.d']
-.EE
-
-.IP DVIPDF
-The TeX DVI file to PDF file converter.
-
-.IP DVIPDFCOM
-The command line used to convert TeX DVI files into a PDF file.
-
-.IP DVIPDFCOMSTR
-The string displayed when a TeX DVI file
-is converted into a PDF file.
-If this is not set, then \fB$DVIPDFCOM\fP (the command line) is displayed.
-
-.IP DVIPDFFLAGS
-General options passed to the TeX DVI file to PDF file converter.
-
-.IP DVIPS
-The TeX DVI file to PostScript converter.
-
-.IP DVIPSFLAGS
-General options passed to the TeX DVI file to PostScript converter.
-
-.IP ENV
-A dictionary of environment variables
-to use when invoking commands. When
-\fB$ENV\fP is used in a command all list
-values will be joined using the path separator and any other non-string
-values will simply be coerced to a string.
-Note that, by default,
-.B scons
-does
-.I not
-propagate the environment in force when you
-execute
-.B scons
-to the commands used to build target files.
-This is so that builds will be guaranteed
-repeatable regardless of the environment
-variables set at the time
-.B scons
-is invoked.
-
-If you want to propagate your
-environment variables
-to the commands executed
-to build target files,
-you must do so explicitly:
-
-.ES
-import os
-env = Environment(ENV = os.environ)
-.EE
-.IP
-Note that you can choose only to propagate
-certain environment variables.
-A common example is
-the system
-.B PATH
-environment variable,
-so that
-.B scons
-uses the same utilities
-as the invoking shell (or other process):
-
-.ES
-import os
-env = Environment(ENV = {'PATH' : os.environ['PATH']})
-.EE
-
-.IP ESCAPE
-A function that will be called to escape shell special characters in
-command lines. The function should take one argument: the command line
-string to escape; and should return the escaped command line.
-
-.IP F77
-The Fortran 77 compiler.
-You should normally set the \fB$FORTRAN\fP variable,
-which specifies the default Fortran compiler
-for all Fortran versions.
-You only need to set \fB$F77\fP if you need to use a specific compiler
-or compiler version for Fortran 77 files.
-
-.IP F77COM
-The command line used to compile a Fortran 77 source file to an object file.
-You only need to set \fB$F77COM\fP if you need to use a specific
-command line for Fortran 77 files.
-You should normally set the \fB$FORTRANCOM\fP variable,
-which specifies the default command line
-for all Fortran versions.
-
-.IP F77COMSTR
-The string displayed when a Fortran 77 source file
-is compiled to an object file.
-If this is not set, then \fB$F77COM\fP or \fB$FORTRANCOM\fP
-(the command line) is displayed.
-
-.IP F77FILESUFFIXES
-The list of file extensions for which the F77 dialect will be used. By
-default, this is ['.f77']
-
-.IP F77FLAGS
-General user-specified options that are passed to the Fortran 77 compiler.
-Note that this variable does
-.I not
-contain
-.B \-I
-(or similar) include search path options
-that scons generates automatically from \fB$F77PATH\fP.
-See
-.B $_F77INCFLAGS
-below,
-for the variable that expands to those options.
-You only need to set \fB$F77FLAGS\fP if you need to define specific
-user options for Fortran 77 files.
-You should normally set the \fB$FORTRANFLAGS\fP variable,
-which specifies the user-specified options
-passed to the default Fortran compiler
-for all Fortran versions.
-
-.IP _F77INCFLAGS
-An automatically-generated construction variable
-containing the Fortran 77 compiler command-line options
-for specifying directories to be searched for include files.
-The value of \fB$_F77INCFLAGS\fP is created
-by appending \fB$INCPREFIX\fP and \fB$INCSUFFIX\fP
-to the beginning and end
-of each directory in \fB$F77PATH\fP.
-
-.IP F77PATH
-The list of directories that the Fortran 77 compiler will search for include
-directories. The implicit dependency scanner will search these
-directories for include files. Don't explicitly put include directory
-arguments in \fB$F77FLAGS\fP because the result will be non-portable
-and the directories will not be searched by the dependency scanner. Note:
-directory names in \fB$F77PATH\fP will be looked-up relative to the SConscript
-directory when they are used in a command. To force
-.B scons
-to look-up a directory relative to the root of the source tree use #:
-You only need to set \fB$F77PATH\fP if you need to define a specific
-include path for Fortran 77 files.
-You should normally set the \fB$FORTRANPATH\fP variable,
-which specifies the include path
-for the default Fortran compiler
-for all Fortran versions.
-
-.ES
-env = Environment(F77PATH='#/include')
-.EE
-.IP
-The directory look-up can also be forced using the
-.BR Dir ()
-function:
-
-.ES
-include = Dir('include')
-env = Environment(F77PATH=include)
-.EE
-.IP
-The directory list will be added to command lines
-through the automatically-generated
-.B $_F77INCFLAGS
-construction variable,
-which is constructed by
-appending the values of the
-.BR $INCPREFIX and $INCSUFFIX
-construction variables
-to the beginning and end
-of each directory in \fB$F77PATH\fP.
-Any command lines you define that need
-the F77PATH directory list should
-include \fB$_F77INCFLAGS\fP:
-
-.ES
-env = Environment(F77COM="my_compiler $_F77INCFLAGS -c -o $TARGET $SOURCE")
-.EE
-
-.IP F77PPCOM
-The command line used to compile a Fortran 77 source file to an object file
-after first running the file through the C preprocessor.
-Any options specified in the \fB$F77FLAGS\fP and \fB$CPPFLAGS\fP construction variables
-are included on this command line.
-You only need to set \fB$F77PPCOM\fP if you need to use a specific
-C-preprocessor command line for Fortran 77 files.
-You should normally set the \fB$FORTRANPPCOM\fP variable,
-which specifies the default C-preprocessor command line
-for all Fortran versions.
-
-.IP F77PPCOMSTR
-The string displayed when a Fortran 77 source file
-is compiled to an object file
-after first running the file through the C preprocessor.
-If this is not set, then \fB$F77PPCOM\fP or \fB$FORTRANPPCOM\fP
-(the command line) is displayed.
-
-.IP F77PPFILESUFFIXES
-The list of file extensions for which the compilation + preprocessor pass for
-F77 dialect will be used. By default, this is empty
-
-.IP F90
-The Fortran 90 compiler.
-You should normally set the \fB$FORTRAN\fP variable,
-which specifies the default Fortran compiler
-for all Fortran versions.
-You only need to set \fB$F90\fP if you need to use a specific compiler
-or compiler version for Fortran 90 files.
-
-.IP F90COM
-The command line used to compile a Fortran 90 source file to an object file.
-You only need to set \fB$F90COM\fP if you need to use a specific
-command line for Fortran 90 files.
-You should normally set the \fB$FORTRANCOM\fP variable,
-which specifies the default command line
-for all Fortran versions.
-
-.IP F90COMSTR
-The string displayed when a Fortran 90 source file
-is compiled to an object file.
-If this is not set, then \fB$F90COM\fP or \fB$FORTRANCOM\fP
-(the command line) is displayed.
-
-.IP F90FILESUFFIXES
-The list of file extensions for which the F90 dialect will be used. By
-default, this is ['.f90']
-
-.IP F90FLAGS
-General user-specified options that are passed to the Fortran 90 compiler.
-Note that this variable does
-.I not
-contain
-.B \-I
-(or similar) include search path options
-that scons generates automatically from \fB$F90PATH\fP.
-See
-.B $_F90INCFLAGS
-below,
-for the variable that expands to those options.
-You only need to set \fB$F90FLAGS\fP if you need to define specific
-user options for Fortran 90 files.
-You should normally set the \fB$FORTRANFLAGS\fP variable,
-which specifies the user-specified options
-passed to the default Fortran compiler
-for all Fortran versions.
-
-.IP _F90INCFLAGS
-An automatically-generated construction variable
-containing the Fortran 90 compiler command-line options
-for specifying directories to be searched for include files.
-The value of \fB$_F90INCFLAGS\fP is created
-by appending \fB$INCPREFIX\fP and \fB$INCSUFFIX\fP
-to the beginning and end
-of each directory in \fB$F90PATH\fP.
-
-.IP F90PATH
-The list of directories that the Fortran 90 compiler will search for include
-directories. The implicit dependency scanner will search these
-directories for include files. Don't explicitly put include directory
-arguments in \fB$F90FLAGS\fP because the result will be non-portable
-and the directories will not be searched by the dependency scanner. Note:
-directory names in \fB$F90PATH\fP will be looked-up relative to the SConscript
-directory when they are used in a command. To force
-.B scons
-to look-up a directory relative to the root of the source tree use #:
-You only need to set \fB$F90PATH\fP if you need to define a specific
-include path for Fortran 90 files.
-You should normally set the \fB$FORTRANPATH\fP variable,
-which specifies the include path
-for the default Fortran compiler
-for all Fortran versions.
-
-.ES
-env = Environment(F90PATH='#/include')
-.EE
-.IP
-The directory look-up can also be forced using the
-.BR Dir ()
-function:
-
-.ES
-include = Dir('include')
-env = Environment(F90PATH=include)
-.EE
-.IP
-The directory list will be added to command lines
-through the automatically-generated
-.B $_F90INCFLAGS
-construction variable,
-which is constructed by
-appending the values of the
-.BR $INCPREFIX and $INCSUFFIX
-construction variables
-to the beginning and end
-of each directory in \fB$F90PATH\fP.
-Any command lines you define that need
-the F90PATH directory list should
-include \fB$_F90INCFLAGS\fP:
-
-.ES
-env = Environment(F90COM="my_compiler $_F90INCFLAGS -c -o $TARGET $SOURCE")
-.EE
-
-.IP F90PPCOM
-The command line used to compile a Fortran 90 source file to an object file
-after first running the file through the C preprocessor.
-Any options specified in the \fB$F90FLAGS\fP and \fB$CPPFLAGS\fP construction variables
-are included on this command line.
-You only need to set \fB$F90PPCOM\fP if you need to use a specific
-C-preprocessor command line for Fortran 90 files.
-You should normally set the \fB$FORTRANPPCOM\fP variable,
-which specifies the default C-preprocessor command line
-for all Fortran versions.
-
-.IP F90PPCOMSTR
-The string displayed when a Fortran 90 source file
-is compiled after first running the file through the C preprocessor.
-If this is not set, then \fB$F90PPCOM\fP or \fB$FORTRANPPCOM\fP
-(the command line) is displayed.
-
-.IP F90PPFILESUFFIXES
-The list of file extensions for which the compilation + preprocessor pass for
-F90 dialect will be used. By default, this is empty
-
-.IP F95
-The Fortran 95 compiler.
-You should normally set the \fB$FORTRAN\fP variable,
-which specifies the default Fortran compiler
-for all Fortran versions.
-You only need to set \fB$F95\fP if you need to use a specific compiler
-or compiler version for Fortran 95 files.
-
-.IP F95COM
-The command line used to compile a Fortran 95 source file to an object file.
-You only need to set \fB$F95COM\fP if you need to use a specific
-command line for Fortran 95 files.
-You should normally set the \fB$FORTRANCOM\fP variable,
-which specifies the default command line
-for all Fortran versions.
-
-.IP F95COMSTR
-The string displayed when a Fortran 95 source file
-is compiled to an object file.
-If this is not set, then \fB$F95COM\fP or \fB$FORTRANCOM\fP
-(the command line) is displayed.
-
-.IP F95FILESUFFIXES
-The list of file extensions for which the F95 dialect will be used. By
-default, this is ['.f95']
-
-.IP F95FLAGS
-General user-specified options that are passed to the Fortran 95 compiler.
-Note that this variable does
-.I not
-contain
-.B \-I
-(or similar) include search path options
-that scons generates automatically from \fB$F95PATH\fP.
-See
-.B $_F95INCFLAGS
-below,
-for the variable that expands to those options.
-You only need to set \fB$F95FLAGS\fP if you need to define specific
-user options for Fortran 95 files.
-You should normally set the \fB$FORTRANFLAGS\fP variable,
-which specifies the user-specified options
-passed to the default Fortran compiler
-for all Fortran versions.
-
-.IP _F95INCFLAGS
-An automatically-generated construction variable
-containing the Fortran 95 compiler command-line options
-for specifying directories to be searched for include files.
-The value of \fB$_F95INCFLAGS\fP is created
-by appending \fB$INCPREFIX\fP and \fB$INCSUFFIX\fP
-to the beginning and end
-of each directory in \fB$F95PATH\fP.
-
-.IP F95PATH
-The list of directories that the Fortran 95 compiler will search for include
-directories. The implicit dependency scanner will search these
-directories for include files. Don't explicitly put include directory
-arguments in \fB$F95FLAGS\fP because the result will be non-portable
-and the directories will not be searched by the dependency scanner. Note:
-directory names in \fB$F95PATH\fP will be looked-up relative to the SConscript
-directory when they are used in a command. To force
-.B scons
-to look-up a directory relative to the root of the source tree use #:
-You only need to set \fB$F95PATH\fP if you need to define a specific
-include path for Fortran 95 files.
-You should normally set the \fB$FORTRANPATH\fP variable,
-which specifies the include path
-for the default Fortran compiler
-for all Fortran versions.
-
-.ES
-env = Environment(F95PATH='#/include')
-.EE
-.IP
-The directory look-up can also be forced using the
-.BR Dir ()
-function:
-
-.ES
-include = Dir('include')
-env = Environment(F95PATH=include)
-.EE
-.IP
-The directory list will be added to command lines
-through the automatically-generated
-.B $_F95INCFLAGS
-construction variable,
-which is constructed by
-appending the values of the
-.BR $INCPREFIX and $INCSUFFIX
-construction variables
-to the beginning and end
-of each directory in \fB$F95PATH\fP.
-Any command lines you define that need
-the F95PATH directory list should
-include \fB$_F95INCFLAGS\fP:
-
-.ES
-env = Environment(F95COM="my_compiler $_F95INCFLAGS -c -o $TARGET $SOURCE")
-.EE
-
-.IP F95PPCOM
-The command line used to compile a Fortran 95 source file to an object file
-after first running the file through the C preprocessor.
-Any options specified in the \fB$F95FLAGS\fP and \fB$CPPFLAGS\fP construction variables
-are included on this command line.
-You only need to set \fB$F95PPCOM\fP if you need to use a specific
-C-preprocessor command line for Fortran 95 files.
-You should normally set the \fB$FORTRANPPCOM\fP variable,
-which specifies the default C-preprocessor command line
-for all Fortran versions.
-
-.IP F95PPCOMSTR
-The string displayed when a Fortran 95 source file
-is compiled to an object file
-after first running the file through the C preprocessor.
-If this is not set, then \fB$F95PPCOM\fP or \fB$FORTRANPPCOM\fP
-(the command line) is displayed.
-
-.IP F95PPFILESUFFIXES
-The list of file extensions for which the compilation + preprocessor pass for
-F95 dialect will be used. By default, this is empty
-
-.IP File
-A function that converts a string into a File instance relative to the
-target being built.
-
-.IP FORTRAN
-The default Fortran compiler
-for all versions of Fortran.
-
-.IP FORTRANCOM
-The command line used to compile a Fortran source file to an object file.
-By default, any options specified
-in the \fB$FORTRANFLAGS\fP,
-.BR $CPPFLAGS ,
-.BR $_CPPDEFFLAGS ,
-\fB$_FORTRANMODFLAG\fP, and
-\fB$_FORTRANINCFLAGS\fP construction variables
-are included on this command line.
-
-.IP FORTRANCOMSTR
-The string displayed when a Fortran source file
-is compiled to an object file.
-If this is not set, then \fB$FORTRANCOM\fP
-(the command line) is displayed.
-
-.IP FORTRANFILESUFFIXES
-The list of file extensions for which the FORTRAN dialect will be used. By
-default, this is ['.f', '.for', '.ftn']
-
-.IP FORTRANFLAGS
-General user-specified options that are passed to the Fortran compiler.
-Note that this variable does
-.I not
-contain
-.B \-I
-(or similar) include or module search path options
-that scons generates automatically from \fB$FORTRANPATH\fP.
-See
-.BR $_FORTRANINCFLAGS\fP and \fB$_FORTRANMODFLAG ,
-below,
-for the variables that expand those options.
-
-.IP _FORTRANINCFLAGS
-An automatically-generated construction variable
-containing the Fortran compiler command-line options
-for specifying directories to be searched for include
-files and module files.
-The value of \fB$_FORTRANINCFLAGS\fP is created
-by prepending/appending \fB$INCPREFIX\fP and \fB$INCSUFFIX\fP
-to the beginning and end
-of each directory in \fB$FORTRANPATH\fP.
-
-.IP FORTRANMODDIR
-Directory location where the Fortran compiler should place
-any module files it generates. This variable is empty, by default. Some
-Fortran compilers will internally append this directory in the search path
-for module files, as well.
-
-.IP FORTRANMODDIRPREFIX
-The prefix used to specify a module directory on the Fortran compiler command
-line.
-This will be appended to the beginning of the directory
-in the \fB$FORTRANMODDIR\fP construction variables
-when the \fB$_FORTRANMODFLAG\fP variables is automatically generated.
-
-.IP FORTRANMODDIRSUFFIX
-The suffix used to specify a module directory on the Fortran compiler command
-line.
-This will be appended to the beginning of the directory
-in the \fB$FORTRANMODDIR\fP construction variables
-when the \fB$_FORTRANMODFLAG\fP variables is automatically generated.
-
-.IP _FORTRANMODFLAG
-An automatically-generated construction variable
-containing the Fortran compiler command-line option
-for specifying the directory location where the Fortran
-compiler should place any module files that happen to get
-generated during compilation.
-The value of \fB$_FORTRANMODFLAG\fP is created
-by prepending/appending \fB$FORTRANMODDIRPREFIX\fP and
-.B $FORTRANMODDIRSUFFIX
-to the beginning and end of the directory in \fB$FORTRANMODDIR\fP.
-
-.IP FORTRANMODPREFIX
-The module file prefix used by the Fortran compiler. SCons assumes that
-the Fortran compiler follows the quasi-standard naming convention for
-module files of
-.BR module_name.mod .
-As a result, this variable is left empty, by default. For situations in
-which the compiler does not necessarily follow the normal convention,
-the user may use this variable. Its value will be appended to every
-module file name as scons attempts to resolve dependencies.
-
-.IP FORTRANMODSUFFIX
-The module file suffix used by the Fortran compiler. SCons assumes that
-the Fortran compiler follows the quasi-standard naming convention for
-module files of
-.BR module_name.mod .
-As a result, this variable is set to ".mod", by default. For situations
-in which the compiler does not necessarily follow the normal convention,
-the user may use this variable. Its value will be appended to every
-module file name as scons attempts to resolve dependencies.
-
-.IP FORTRANPATH
-The list of directories that the Fortran compiler will search for
-include files and (for some compilers) module files. The Fortran implicit
-dependency scanner will search these directories for include files (but
-not module files since they are autogenerated and, as such, may not
-actually exist at the time the scan takes place). Don't explicitly put
-include directory arguments in FORTRANFLAGS because the result will be
-non-portable and the directories will not be searched by the dependency
-scanner. Note: directory names in FORTRANPATH will be looked-up relative
-to the SConscript directory when they are used in a command. To force
-.B scons
-to look-up a directory relative to the root of the source tree use #:
-
-.ES
-env = Environment(FORTRANPATH='#/include')
-.EE
-.IP
-The directory look-up can also be forced using the
-.BR Dir ()
-function:
-
-.ES
-include = Dir('include')
-env = Environment(FORTRANPATH=include)
-.EE
-.IP
-The directory list will be added to command lines
-through the automatically-generated
-.B $_FORTRANINCFLAGS
-construction variable,
-which is constructed by
-appending the values of the
-.BR $INCPREFIX and $INCSUFFIX
-construction variables
-to the beginning and end
-of each directory in \fB$FORTRANPATH\fP.
-Any command lines you define that need
-the FORTRANPATH directory list should
-include \fB$_FORTRANINCFLAGS\fP:
-
-.ES
-env = Environment(FORTRANCOM="my_compiler $_FORTRANINCFLAGS -c -o $TARGET $SOURCE")
-.EE
-
-.IP FORTRANPPCOM
-The command line used to compile a Fortran source file to an object file
-after first running the file through the C preprocessor.
-By default, any options specified in the \fB$FORTRANFLAGS\fP,
-.BR $CPPFLAGS ,
-.BR $_CPPDEFFLAGS ,
-\fB$_FORTRANMODFLAG\fP, and
-.B $_FORTRANINCFLAGS
-construction variables are included on this command line.
-
-.IP FORTRANPPCOMSTR
-The string displayed when a Fortran source file
-is compiled to an object file
-after first running the file through the C preprocessor.
-If this is not set, then \fB$FORTRANPPCOM\fP
-(the command line) is displayed.
-
-.IP FORTRANPPFILESUFFIXES
-The list of file extensions for which the compilation + preprocessor pass for
-FORTRAN dialect will be used. By default, this is ['.fpp', '.FPP']
-
-.IP FORTRANSUFFIXES
-The list of suffixes of files that will be scanned
-for Fortran implicit dependencies
-(INCLUDE lines and USE statements).
-The default list is:
-
-.ES
-[".f", ".F", ".for", ".FOR", ".ftn", ".FTN", ".fpp", ".FPP",
-".f77", ".F77", ".f90", ".F90", ".f95", ".F95"]
-.EE
-
-.IP FRAMEWORKPATH
-On Mac OS X with gcc,
-a list containing the paths to search for frameworks.
-Used by the compiler to find framework-style includes like
-#include <Fmwk/Header.h>.
-Used by the linker to find user-specified frameworks when linking (see
-.BR $FRAMEWORKS ).
-For example:
-
-.ES
- env.AppendUnique(FRAMEWORKPATH='#myframeworkdir')
-.EE
-.IP
-will add
-
-.ES
- ... -Fmyframeworkdir
-.EE
-.IP
-to the compiler and linker command lines.
-
-.IP _FRAMEWORKPATH
-On Mac OS X with gcc, an automatically-generated construction variable
-containing the linker command-line options corresponding to
-.BR $FRAMEWORKPATH .
-
-.IP FRAMEWORKPATHPREFIX
-On Mac OS X with gcc, the prefix to be used for the FRAMEWORKPATH entries.
-(see \fB$FRAMEWORKPATH\fP).
-The default value is
-.BR \-F .
-
-.IP FRAMEWORKPREFIX
-On Mac OS X with gcc,
-the prefix to be used for linking in frameworks
-(see \fB$FRAMEWORKS\fP).
-The default value is
-.BR \-framework .
-
-.IP _FRAMEWORKS
-On Mac OS X with gcc,
-an automatically-generated construction variable
-containing the linker command-line options
-for linking with FRAMEWORKS.
-
-.IP FRAMEWORKS
-On Mac OS X with gcc, a list of the framework names to be linked into a
-program or shared library or bundle.
-The default value is the empty list.
-For example:
-
-.ES
- env.AppendUnique(FRAMEWORKS=Split('System Cocoa SystemConfiguration'))
-.EE
-.IP
-
-.IP FRAMEWORKSFLAGS
-On Mac OS X with gcc,
-general user-supplied frameworks options to be added at
-the end of a command
-line building a loadable module.
-(This has been largely superseded by
-the \fB$FRAMEWORKPATH\fP, \fB$FRAMEWORKPATHPREFIX\fP,
-\fB$FRAMEWORKPREFIX\fP and \fB$FRAMEWORKS\fP variables
-described above.)
-
-.IP GS
-The Ghostscript program used to convert PostScript to PDF files.
-
-.IP GSCOM
-The Ghostscript command line used to convert PostScript to PDF files.
-
-.IP GSCOMSTR
-The string displayed when
-Ghostscript is used to convert
-a PostScript file to a PDF file.
-If this is not set, then \fB$GSCOM\fP (the command line) is displayed.
-
-.IP GSFLAGS
-General options passed to the Ghostscript program
-when converting PostScript to PDF files.
-
-.IP HOST_ARCH
-Sets the host architecture for Visual Studio compiler. If not set,
-default to the detected host architecture: note that this may depend
-on the python you are using.
-This variable must be passed as an argument to the Environment()
-constructor; setting it later has no effect.
-
-Valid values are the same as for \fB$TARGET_ARCH\fP.
-
-This is currently only used on Windows, but in the future it will be
-used on other OSes as well.
-
-.IP HOST_OS
- The name of the host operating system used to create the Environment.
- If a platform is specified when creating the Environment, then
- that Platform's logic will handle setting this value.
- This value is immutable, and should not be changed by the user after
- the Environment is initialized.
- Currently only set for Win32.
-
-.IP IDLSUFFIXES
-The list of suffixes of files that will be scanned
-for IDL implicit dependencies
-(#include or import lines).
-The default list is:
-
-.ES
-[".idl", ".IDL"]
-.EE
-
-.IP IMPLICIT_COMMAND_DEPENDENCIES
-Controls whether or not SCons will
-add implicit dependencies for the commands
-executed to build targets.
-
-By default, SCons will add
-to each target
-an implicit dependency on the command
-represented by the first argument on any
-command line it executes.
-The specific file for the dependency is
-found by searching the
-.I PATH
-variable in the
-.I ENV
-environment used to execute the command.
-
-If the construction variable
-.B $IMPLICIT_COMMAND_DEPENDENCIES
-is set to a false value
-.RB ( None ,
-.BR False ,
-.BR 0 ,
-etc.),
-then the implicit dependency will
-not be added to the targets
-built with that construction environment.
-
-.ES
-env = Environment(IMPLICIT_COMMAND_DEPENDENCIES = 0)
-.EE
-
-.IP INCPREFIX
-The prefix used to specify an include directory on the C compiler command
-line.
-This will be appended to the beginning of each directory
-in the \fB$CPPPATH\fP and \fB$FORTRANPATH\fP construction variables
-when the \fB$_CPPINCFLAGS\fP and \fB$_FORTRANINCFLAGS\fP
-variables are automatically generated.
-
-.IP INCSUFFIX
-The suffix used to specify an include directory on the C compiler command
-line.
-This will be appended to the end of each directory
-in the \fB$CPPPATH\fP and \fB$FORTRANPATH\fP construction variables
-when the \fB$_CPPINCFLAGS\fP and \fB$_FORTRANINCFLAGS\fP
-variables are automatically generated.
-
-.IP INSTALL
-A function to be called to install a file into a
-destination file name.
-The default function copies the file into the destination
-(and sets the destination file's mode and permission bits
-to match the source file's).
-The function takes the following arguments:
-
-.ES
-def install(dest, source, env):
-.EE
-.IP
-.I dest
-is the path name of the destination file.
-.I source
-is the path name of the source file.
-.I env
-is the construction environment
-(a dictionary of construction values)
-in force for this file installation.
-
-.IP INSTALLSTR
-The string displayed when a file is
-installed into a destination file name.
-The default is:
-.ES
-Install file: "$SOURCE" as "$TARGET"
-.EE
-
-.IP INTEL_C_COMPILER_VERSION
-Set by the "intelc" Tool
-to the major version number of the Intel C compiler
-selected for use.
-
-.IP JAR
-The Java archive tool.
-
-.IP JARCHDIR
-The directory to which the Java archive tool should change
-(using the
-.B \-C
-option).
-
-.IP JARCOM
-The command line used to call the Java archive tool.
-
-.IP JARCOMSTR
-The string displayed when the Java archive tool
-is called
-If this is not set, then \fB$JARCOM\fP (the command line) is displayed.
-
-.ES
-env = Environment(JARCOMSTR = "JARchiving $SOURCES into $TARGET")
-.EE
-
-.IP JARFLAGS
-General options passed to the Java archive tool.
-By default this is set to
-.B cf
-to create the necessary
-.B jar
-file.
-
-.IP JARSUFFIX
-The suffix for Java archives:
-.B .jar
-by default.
-
-.IP JAVABOOTCLASSPATH
-Specifies the list of directories that
-will be added to the
-&javac; command line
-via the \fB\-bootclasspath\fP option.
-The individual directory names will be
-separated by the operating system's path separate character
-(\fB:\fP on UNIX/Linux/POSIX,
-\fB;\fP on Windows).
-
-.IP JAVAC
-The Java compiler.
-
-.IP JAVACCOM
-The command line used to compile a directory tree containing
-Java source files to
-corresponding Java class files.
-Any options specified in the \fB$JAVACFLAGS\fP construction variable
-are included on this command line.
-
-.IP JAVACCOMSTR
-The string displayed when compiling
-a directory tree of Java source files to
-corresponding Java class files.
-If this is not set, then \fB$JAVACCOM\fP (the command line) is displayed.
-
-.ES
-env = Environment(JAVACCOMSTR = "Compiling class files $TARGETS from $SOURCES")
-.EE
-
-.IP JAVACFLAGS
-General options that are passed to the Java compiler.
-
-.IP JAVACLASSDIR
-The directory in which Java class files may be found.
-This is stripped from the beginning of any Java .class
-file names supplied to the
-.B JavaH
-builder.
-
-.IP JAVACLASSPATH
-Specifies the list of directories that
-will be searched for Java
-\fB.class\fP file.
-The directories in this list will be added to the
-&javac; and &javah; command lines
-via the \fB\-classpath\fP option.
-The individual directory names will be
-separated by the operating system's path separate character
-(\fB:\fP on UNIX/Linux/POSIX,
-\fB;\fP on Windows).
-
-Note that this currently just adds the specified
-directory via the \fB\-classpath\fP option.
-&SCons; does not currently search the
-\fB$JAVACLASSPATH\fP directories for dependency
-\fB.class\fP files.
-
-.IP JAVACLASSSUFFIX
-The suffix for Java class files;
-.B .class
-by default.
-
-.IP JAVAH
-The Java generator for C header and stub files.
-
-.IP JAVAHCOM
-The command line used to generate C header and stub files
-from Java classes.
-Any options specified in the \fB$JAVAHFLAGS\fP construction variable
-are included on this command line.
-
-.IP JAVAHCOMSTR
-The string displayed when C header and stub files
-are generated from Java classes.
-If this is not set, then \fB$JAVAHCOM\fP (the command line) is displayed.
-
-.ES
-env = Environment(JAVAHCOMSTR = "Generating header/stub file(s) $TARGETS from $SOURCES")
-.EE
-
-.IP JAVAHFLAGS
-General options passed to the C header and stub file generator
-for Java classes.
-
-.IP JAVASOURCEPATH
-Specifies the list of directories that
-will be searched for input
-\fB.java\fP file.
-The directories in this list will be added to the
-&javac; command line
-via the \fB\-sourcepath\fP option.
-The individual directory names will be
-separated by the operating system's path separate character
-(\fB:\fP on UNIX/Linux/POSIX,
-\fB;\fP on Windows).
-
-Note that this currently just adds the specified
-directory via the \fB\-sourcepath\fP option.
-&SCons; does not currently search the
-\fB$JAVASOURCEPATH\fP directories for dependency
-\fB.java\fP files.
-
-.IP JAVASUFFIX
-The suffix for Java files;
-.B .java
-by default.
-
-.IP JAVAVERSION
-Specifies the Java version being used by the \fBJava\fP() builder.
-This is \fInot\fP currently used to select one
-version of the Java compiler vs. another.
-Instead, you should set this to specify the version of Java
-supported by your &javac; compiler.
-The default is \fB1.4\fP.
-
-This is sometimes necessary because
-Java 1.5 changed the file names that are created
-for nested anonymous inner classes,
-which can cause a mismatch with the files
-that &SCons; expects will be generated by the &javac; compiler.
-Setting \fB$JAVAVERSION\fP to \fB1.5\fP
-(or \fB1.6\fP, as appropriate)
-can make &SCons; realize that a Java 1.5 or 1.6
-build is actually up to date.
-
-.IP LATEX
-The LaTeX structured formatter and typesetter.
-
-.IP LATEXCOM
-The command line used to call the LaTeX structured formatter and typesetter.
-
-.IP LATEXCOMSTR
-The string displayed when calling
-the LaTeX structured formatter and typesetter.
-If this is not set, then \fB$LATEXCOM\fP (the command line) is displayed.
-
-.ES
-env = Environment(LATEXCOMSTR = "Building $TARGET from LaTeX input $SOURCES")
-.EE
-
-.IP LATEXFLAGS
-General options passed to the LaTeX structured formatter and typesetter.
-
-.IP LATEXRETRIES
-The maximum number of times that LaTeX
-will be re-run if the
-.B .log
-generated by the \fB$LATEXCOM\fP command
-indicates that there are undefined references.
-The default is to try to resolve undefined references
-by re-running LaTeX up to three times.
-
-.IP LATEXSUFFIXES
-The list of suffixes of files that will be scanned
-for LaTeX implicit dependencies
-(\fB\\include\fP or \fB\\import\fP files).
-The default list is:
-
-.ES
-[".tex", ".ltx", ".latex"]
-.EE
-
-.IP LDMODULE
-The linker for building loadable modules.
-By default, this is the same as \fB$SHLINK\fP.
-
-.IP LDMODULECOM
-The command line for building loadable modules.
-On Mac OS X, this uses the \fB$LDMODULE\fP,
-\fB$LDMODULEFLAGS\fP and
-\fB$FRAMEWORKSFLAGS\fP variables.
-On other systems, this is the same as \fB$SHLINK\fP.
-
-.IP LDMODULECOMSTR
-The string displayed when building loadable modules.
-If this is not set, then \fB$LDMODULECOM\fP (the command line) is displayed.
-
-.IP LDMODULEFLAGS
-General user options passed to the linker for building loadable modules.
-
-.IP LDMODULEPREFIX
-The prefix used for loadable module file names.
-On Mac OS X, this is null;
-on other systems, this is
-the same as \fB$SHLIBPREFIX\fP.
-
-.IP LDMODULESUFFIX
-The suffix used for loadable module file names.
-On Mac OS X, this is null;
-on other systems, this is
-the same as $SHLIBSUFFIX.
-
-.IP LEX
-The lexical analyzer generator.
-
-.IP LEXCOM
-The command line used to call the lexical analyzer generator
-to generate a source file.
-
-.IP LEXCOMSTR
-The string displayed when generating a source file
-using the lexical analyzer generator.
-If this is not set, then \fB$LEXCOM\fP (the command line) is displayed.
-
-.ES
-env = Environment(LEXCOMSTR = "Lex'ing $TARGET from $SOURCES")
-.EE
-
-.IP LEXFLAGS
-General options passed to the lexical analyzer generator.
-
-.IP _LIBDIRFLAGS
-An automatically-generated construction variable
-containing the linker command-line options
-for specifying directories to be searched for library.
-The value of \fB$_LIBDIRFLAGS\fP is created
-by appending \fB$LIBDIRPREFIX\fP and \fB$LIBDIRSUFFIX\fP
-to the beginning and end
-of each directory in \fB$LIBPATH\fP.
-
-.IP LIBDIRPREFIX
-The prefix used to specify a library directory on the linker command line.
-This will be appended to the beginning of each directory
-in the \fB$LIBPATH\fP construction variable
-when the \fB$_LIBDIRFLAGS\fP variable is automatically generated.
-
-.IP LIBDIRSUFFIX
-The suffix used to specify a library directory on the linker command line.
-This will be appended to the end of each directory
-in the \fB$LIBPATH\fP construction variable
-when the \fB$_LIBDIRFLAGS\fP variable is automatically generated.
-
-.IP LIBEMITTER
-TODO
-
-.IP _LIBFLAGS
-An automatically-generated construction variable
-containing the linker command-line options
-for specifying libraries to be linked with the resulting target.
-The value of \fB$_LIBFLAGS\fP is created
-by appending \fB$LIBLINKPREFIX\fP and \fB$LIBLINKSUFFIX\fP
-to the beginning and end
-of each filename in \fB$LIBS\fP.
-
-.IP LIBLINKPREFIX
-The prefix used to specify a library to link on the linker command line.
-This will be appended to the beginning of each library
-in the \fB$LIBS\fP construction variable
-when the \fB$_LIBFLAGS\fP variable is automatically generated.
-
-.IP LIBLINKSUFFIX
-The suffix used to specify a library to link on the linker command line.
-This will be appended to the end of each library
-in the \fB$LIBS\fP construction variable
-when the \fB$_LIBFLAGS\fP variable is automatically generated.
-
-.IP LIBPATH
-The list of directories that will be searched for libraries.
-The implicit dependency scanner will search these
-directories for include files. Don't explicitly put include directory
-arguments in \fB$LINKFLAGS\fP or \fB$SHLINKFLAGS\fP
-because the result will be non-portable
-and the directories will not be searched by the dependency scanner. Note:
-directory names in LIBPATH will be looked-up relative to the SConscript
-directory when they are used in a command. To force
-.B scons
-to look-up a directory relative to the root of the source tree use #:
-
-.ES
-env = Environment(LIBPATH='#/libs')
-.EE
-.IP
-The directory look-up can also be forced using the
-.BR Dir ()
-function:
-
-.ES
-libs = Dir('libs')
-env = Environment(LIBPATH=libs)
-.EE
-.IP
-The directory list will be added to command lines
-through the automatically-generated
-.B $_LIBDIRFLAGS
-construction variable,
-which is constructed by
-appending the values of the
-.BR $LIBDIRPREFIX and $LIBDIRSUFFIX
-construction variables
-to the beginning and end
-of each directory in \fB$LIBPATH\fP.
-Any command lines you define that need
-the LIBPATH directory list should
-include \fB$_LIBDIRFLAGS\fP:
-
-.ES
-env = Environment(LINKCOM="my_linker $_LIBDIRFLAGS $_LIBFLAGS -o $TARGET $SOURCE")
-.EE
-
-.IP LIBPREFIX
-The prefix used for (static) library file names.
-A default value is set for each platform
-(posix, win32, os2, etc.),
-but the value is overridden by individual tools
-(ar, mslib, sgiar, sunar, tlib, etc.)
-to reflect the names of the libraries they create.
-
-.IP LIBPREFIXES
-A list of all legal prefixes for library file names.
-When searching for library dependencies,
-SCons will look for files with these prefixes,
-the base library name,
-and suffixes in the \fB$LIBSUFFIXES\fP list.
-
-.IP LIBS
-A list of one or more libraries
-that will be linked with
-any executable programs
-created by this environment.
-
-The library list will be added to command lines
-through the automatically-generated
-.B $_LIBFLAGS
-construction variable,
-which is constructed by
-appending the values of the
-.BR $LIBLINKPREFIX and $LIBLINKSUFFIX
-construction variables
-to the beginning and end
-of each filename in \fB$LIBS\fP.
-Any command lines you define that need
-the LIBS library list should
-include \fB$_LIBFLAGS\fP:
-
-.ES
-env = Environment(LINKCOM="my_linker $_LIBDIRFLAGS $_LIBFLAGS -o $TARGET $SOURCE")
-.EE
-.IP
-If you add a
-File
-object to the
-.B $LIBS
-list, the name of that file will be added to
-.BR $_LIBFLAGS ,
-and thus the link line, as is, without
-.B $LIBLINKPREFIX
-or
-.BR $LIBLINKSUFFIX .
-For example:
-
-.ES
-env.Append(LIBS=File('/tmp/mylib.so'))
-.EE
-.IP
-In all cases, scons will add dependencies from the executable program to
-all the libraries in this list.
-
-.IP LIBSUFFIX
-The suffix used for (static) library file names.
-A default value is set for each platform
-(posix, win32, os2, etc.),
-but the value is overridden by individual tools
-(ar, mslib, sgiar, sunar, tlib, etc.)
-to reflect the names of the libraries they create.
-
-.IP LIBSUFFIXES
-A list of all legal suffixes for library file names.
-When searching for library dependencies,
-SCons will look for files with prefixes, in the \fB$LIBPREFIXES\fP list,
-the base library name,
-and these suffixes.
-
-.IP LICENSE
-The abbreviated name of the license under which
-this project is released (gpl, lpgl, bsd etc.).
-See http://www.opensource.org/licenses/alphabetical
-for a list of license names.
-
-.IP LINESEPARATOR
-The separator used by the \fBSubstfile\fP() and \fBTextfile\fP() builders.
-This value is used between sources when constructing the target.
-It defaults to the current system line separator.
-
-.IP LINGUAS_FILE
-The \fB$LINGUAS_FILE\fP defines file(s) containing list of additional linguas
-to be processed by \fBPOInit\fP(), \fBPOUpdate\fP() or \fBMOFiles\fP()
-builders. It also affects \fBTranslate\fP() builder. If the variable contains
-a string, it defines name of the list file. The \fB$LINGUAS_FILE\fP may be a
-list of file names as well. If \fB$LINGUAS_FILE\fP is set to
-\fBTrue\fP (or non-zero numeric value), the list will be read from
-default file named
-.BR LINGUAS .
-
-
-.IP LINK
-The linker.
-
-.IP LINKCOM
-The command line used to link object files into an executable.
-
-.IP LINKCOMSTR
-The string displayed when object files
-are linked into an executable.
-If this is not set, then \fB$LINKCOM\fP (the command line) is displayed.
-
-.ES
-env = Environment(LINKCOMSTR = "Linking $TARGET")
-.EE
-
-.IP LINKFLAGS
-General user options passed to the linker.
-Note that this variable should
-.I not
-contain
-.B \-l
-(or similar) options for linking with the libraries listed in \fB$LIBS\fP,
-nor
-.B \-L
-(or similar) library search path options
-that scons generates automatically from \fB$LIBPATH\fP.
-See
-.B $_LIBFLAGS
-above,
-for the variable that expands to library-link options,
-and
-.B $_LIBDIRFLAGS
-above,
-for the variable that expands to library search path options.
-
-.IP M4
-The M4 macro preprocessor.
-
-.IP M4COM
-The command line used to pass files through the M4 macro preprocessor.
-
-.IP M4COMSTR
-The string displayed when
-a file is passed through the M4 macro preprocessor.
-If this is not set, then \fB$M4COM\fP (the command line) is displayed.
-
-.IP M4FLAGS
-General options passed to the M4 macro preprocessor.
-
-.IP MAKEINDEX
-The makeindex generator for the TeX formatter and typesetter and the
-LaTeX structured formatter and typesetter.
-
-.IP MAKEINDEXCOM
-The command line used to call the makeindex generator for the
-TeX formatter and typesetter and the LaTeX structured formatter and
-typesetter.
-
-.IP MAKEINDEXCOMSTR
-The string displayed when calling the makeindex generator for the
-TeX formatter and typesetter
-and the LaTeX structured formatter and typesetter.
-If this is not set, then \fB$MAKEINDEXCOM\fP (the command line) is displayed.
-
-.IP MAKEINDEXFLAGS
-General options passed to the makeindex generator for the TeX formatter
-and typesetter and the LaTeX structured formatter and typesetter.
-
-.IP MAXLINELENGTH
-The maximum number of characters allowed on an external command line.
-On Win32 systems,
-link lines longer than this many characters
-are linked via a temporary file name.
-
-.IP MIDL
-The Microsoft IDL compiler.
-
-.IP MIDLCOM
-The command line used to pass files to the Microsoft IDL compiler.
-
-.IP MIDLCOMSTR
-The string displayed when
-the Microsoft IDL copmiler is called.
-If this is not set, then \fB$MIDLCOM\fP (the command line) is displayed.
-
-.IP MIDLFLAGS
-General options passed to the Microsoft IDL compiler.
-
-.IP MOSUFFIX
-Suffix used for \fBMO\fP files (default: \fB'.mo'\fP).
-See &t-link-msgfmt; tool and \fBMOFiles\fP() builder.
-
-.IP MSGFMT
-Absolute path to \fBmsgfmt(1)\fP binary, found by
-.BR Detect() .
-See &t-link-msgfmt; tool and \fBMOFiles\fP() builder.
-
-.IP MSGFMTCOM
-Complete command line to run \fBmsgfmt(1)\fP program.
-See &t-link-msgfmt; tool and \fBMOFiles\fP() builder.
-
-.IP MSGFMTCOMSTR
-String to display when \fBmsgfmt(1)\fP is invoked
-(default: \fB''\fP, which means ``print \fB$MSGFMTCOM\fP'').
-See &t-link-msgfmt; tool and \fBMOFiles\fP() builder.
-
-.IP MSGFMTFLAGS
-Additional flags to \fBmsgfmt(1)\fP.
-See &t-link-msgfmt; tool and \fBMOFiles\fP() builder.
-
-.IP MSGINIT
-Path to \fBmsginit(1)\fP program (found via
-.BR Detect() ).
-See &t-link-msginit; tool and \fBPOInit\fP() builder.
-
-.IP MSGINITCOM
-Complete command line to run \fBmsginit(1)\fP program.
-See &t-link-msginit; tool and \fBPOInit\fP() builder.
-
-.IP MSGINITCOMSTR
-String to display when \fBmsginit(1)\fP is invoked
-(default: \fB''\fP, which means ``print \fB$MSGINITCOM\fP'').
-See &t-link-msginit; tool and \fBPOInit\fP() builder.
-
-.IP MSGINITFLAGS
-List of additional flags to \fBmsginit(1)\fP (default:
-.BR [] ).
-See &t-link-msginit; tool and \fBPOInit\fP() builder.
-
-.IP _MSGINITLOCALE
-Internal ``macro''. Computes locale (language) name based on target filename
-(default: \fB'${TARGET.filebase}' \fP).
-
-.IP MSGMERGE
-Absolute path to \fBmsgmerge(1)\fP binary as found by
-.BR Detect() .
-See &t-link-msgmerge; tool and \fBPOUpdate\fP() builder.
-
-.IP MSGMERGECOM
-Complete command line to run \fBmsgmerge(1)\fP command.
-See &t-link-msgmerge; tool and \fBPOUpdate\fP() builder.
-
-.IP MSGMERGECOMSTR
-String to be displayed when \fBmsgmerge(1)\fP is invoked
-(default: \fB''\fP, which means ``print \fB$MSGMERGECOM\fP'').
-See &t-link-msgmerge; tool and \fBPOUpdate\fP() builder.
-
-.IP MSGMERGEFLAGS
-Additional flags to \fBmsgmerge(1)\fP command.
-See &t-link-msgmerge; tool and \fBPOUpdate\fP() builder.
-
-.IP MSSDK_DIR
-The directory containing the Microsoft SDK
-(either Platform SDK or Windows SDK)
-to be used for compilation.
-
-.IP MSSDK_VERSION
-The version string of the Microsoft SDK
-(either Platform SDK or Windows SDK)
-to be used for compilation.
-Supported versions include
-.BR 6.1 ,
-.BR 6.0A ,
-.BR 6.0 ,
-.B 2003R2
-and
-.BR 2003R1 .
-
-.IP MSVC_BATCH
-When set to any true value,
-specifies that SCons should batch
-compilation of object files
-when calling the Microsoft Visual C/C++ compiler.
-All compilations of source files from the same source directory
-that generate target files in a same output directory
-and were configured in SCons using the same construction environment
-will be built in a single call to the compiler.
-Only source files that have changed since their
-object files were built will be passed to each compiler invocation
-(via the \fB$CHANGED_SOURCES\fP construction variable).
-Any compilations where the object (target) file base name
-(minus the \fB.obj\fP)
-does not match the source file base name
-will be compiled separately.
-
-.IP MSVC_USE_SCRIPT
-Use a batch script to set up Microsoft Visual Studio compiler
-
-.BR $MSVC_USE_SCRIPT\fP overrides \fB$MSVC_VERSION\fP and \fB$TARGET_ARCH .
-If set to the name of a Visual Studio .bat file (e.g. vcvars.bat),
-SCons will run that bat file and extract the relevant variables from
-the result (typically %INCLUDE%, %LIB%, and %PATH%). Setting
-MSVC_USE_SCRIPT to None bypasses the Visual Studio autodetection
-entirely; use this if you are running SCons in a Visual Studio cmd
-window and importing the shell's environment variables.
-
-.IP MSVC_VERSION
-Sets the preferred version of Microsoft Visual C/C++ to use.
-
-If \fB$MSVC_VERSION\fP is not set, SCons will (by default) select the
-latest version of Visual C/C++ installed on your system. If the
-specified version isn't installed, tool initialization will fail.
-This variable must be passed as an argument to the Environment()
-constructor; setting it later has no effect. Set it to an unexpected
-value (e.g. "XXX") to see the valid values on your system.
-
-.IP MSVS
-When the Microsoft Visual Studio tools are initialized, they set up
-this dictionary with the following keys:
-
-.BR VERSION :
-the version of MSVS being used (can be set via
-.BR $MSVS_VERSION )
-
-.BR VERSIONS :
-the available versions of MSVS installed
-
-.BR VCINSTALLDIR :
-installed directory of Visual C++
-
-.BR VSINSTALLDIR :
-installed directory of Visual Studio
-
-.BR FRAMEWORKDIR :
-installed directory of the .NET framework
-
-.BR FRAMEWORKVERSIONS :
-list of installed versions of the .NET framework, sorted latest to oldest.
-
-.BR FRAMEWORKVERSION :
-latest installed version of the .NET framework
-
-.BR FRAMEWORKSDKDIR :
-installed location of the .NET SDK.
-
-.BR PLATFORMSDKDIR :
-installed location of the Platform SDK.
-
-.BR PLATFORMSDK_MODULES :
-dictionary of installed Platform SDK modules,
-where the dictionary keys are keywords for the various modules, and
-the values are 2-tuples where the first is the release date, and the
-second is the version number.
-
-If a value isn't set, it wasn't available in the registry.
-
-.IP MSVS_ARCH
-Sets the architecture for which the generated project(s) should build.
-
-The default value is \fBx86\fP.
-\fBamd64\fP is also supported
-by &SCons; for some Visual Studio versions.
-Trying to set \fB$MSVS_ARCH\fP to an architecture that's not
-supported for a given Visual Studio version
-will generate an error.
-
-.IP MSVS_PROJECT_GUID
-The string
-placed in a generated Microsoft Visual Studio project file
-as the value of the
-.B ProjectGUID
-attribute.
-There is no default value. If not defined, a new GUID is generated.
-
-.IP MSVS_SCC_AUX_PATH
-The path name
-placed in a generated Microsoft Visual Studio project file
-as the value of the
-.B SccAuxPath
-attribute
-if the
-.B MSVS_SCC_PROVIDER
-construction variable is also set.
-There is no default value.
-
-.IP MSVS_SCC_CONNECTION_ROOT
-The root path of projects in your SCC workspace, i.e the path under which
-all project and solution files will be generated. It is used as a
-reference path from which the relative paths of the generated
-Microsoft Visual Studio project and solution files are computed.
-The relative project file path is placed as the value of the
-.B SccLocalPath
-attribute
-of the project file
-and as the values of the
-.B SccProjectFilePathRelativizedFromConnection[i]
-(where [i] ranges from 0 to the number of projects in the solution)
-attributes of the
-.B GlobalSection(SourceCodeControl)
-section of the Microsoft Visual Studio solution file.
-Similarly the relative solution file path is placed as the values of the
-.B SccLocalPath[i]
-(where [i] ranges from 0 to the number of projects in the solution)
-attributes of the
-.B GlobalSection(SourceCodeControl)
-section of the Microsoft Visual Studio solution file.
-This is used only
-if the
-.B MSVS_SCC_PROVIDER
-construction variable is also set.
-The default value is the current working directory.
-
-.IP MSVS_SCC_PROJECT_NAME
-The project name
-placed in a generated Microsoft Visual Studio project file
-as the value of the
-.B SccProjectName
-attribute
-if the
-.B MSVS_SCC_PROVIDER
-construction variable is also set.
-In this case the string is also placed in the
-.B SccProjectName0
-attribute of the
-.B GlobalSection(SourceCodeControl)
-section of the Microsoft Visual Studio solution file.
-There is no default value.
-
-.IP MSVS_SCC_PROVIDER
-The string
-placed in a generated Microsoft Visual Studio project file
-as the value of the
-.B SccProvider
-attribute.
-The string is also placed in the
-.B SccProvider0
-attribute of the
-.B GlobalSection(SourceCodeControl)
-section of the Microsoft Visual Studio solution file.
-There is no default value.
-
-.IP MSVS_VERSION
-Sets the preferred version of Microsoft Visual Studio to use.
-
-If \fB$MSVS_VERSION\fP is not set,
-&SCons; will (by default) select the latest version
-of Visual Studio installed on your system.
-So, if you have version 6 and version 7 (MSVS .NET) installed,
-it will prefer version 7.
-You can override this by
-specifying the
-.B MSVS_VERSION
-variable in the Environment initialization, setting it to the
-appropriate version ('6.0' or '7.0', for example).
-If the specified version isn't installed,
-tool initialization will fail.
-
-This is obsolete: use \fB$MSVC_VERSION\fP instead. If \fB$MSVS_VERSION\fP is set and
-.BR $MSVC_VERSION\fP is not, \fB$MSVC_VERSION\fP will be set automatically to \fB$MSVS_VERSION .
-If both are set to different values, scons will raise an error.
-
-.IP MSVSBUILDCOM
-The build command line placed in
-a generated Microsoft Visual Studio project file.
-The default is to have Visual Studio invoke SCons with any specified
-build targets.
-
-.IP MSVSCLEANCOM
-The clean command line placed in
-a generated Microsoft Visual Studio project file.
-The default is to have Visual Studio invoke SCons with the -c option
-to remove any specified targets.
-
-.IP MSVSENCODING
-The encoding string placed in
-a generated Microsoft Visual Studio project file.
-The default is encoding
-.BR Windows-1252 .
-
-.IP MSVSPROJECTCOM
-The action used to generate Microsoft Visual Studio project files.
-
-.IP MSVSPROJECTSUFFIX
-The suffix used for Microsoft Visual Studio project (DSP) files.
-The default value is
-.B .vcproj
-when using Visual Studio version 7.x (.NET)
-or later version,
-and
-.B .dsp
-when using earlier versions of Visual Studio.
-
-.IP MSVSREBUILDCOM
-The rebuild command line placed in
-a generated Microsoft Visual Studio project file.
-The default is to have Visual Studio invoke SCons with any specified
-rebuild targets.
-
-.IP MSVSSCONS
-The SCons used in generated Microsoft Visual Studio project files.
-The default is the version of SCons being
-used to generate the project file.
-
-.IP MSVSSCONSCOM
-The default SCons command used in generated Microsoft Visual Studio
-project files.
-
-.IP MSVSSCONSCRIPT
-The sconscript file
-(that is,
-.B SConstruct
-or
-.B SConscript
-file)
-that will be invoked by Visual Studio
-project files
-(through the
-.B $MSVSSCONSCOM
-variable).
-The default is the same sconscript file
-that contains the call to
-.BR MSVSProject ()
-to build the project file.
-
-.IP MSVSSCONSFLAGS
-The SCons flags used in generated Microsoft Visual Studio
-project files.
-
-.IP MSVSSOLUTIONCOM
-The action used to generate Microsoft Visual Studio solution files.
-
-.IP MSVSSOLUTIONSUFFIX
-The suffix used for Microsoft Visual Studio solution (DSW) files.
-The default value is
-.B .sln
-when using Visual Studio version 7.x (.NET),
-and
-.B .dsw
-when using earlier versions of Visual Studio.
-
-.IP MT
-The program used on Windows systems to embed manifests into DLLs and EXEs.
-See also \fB$WINDOWS_EMBED_MANIFEST\fP.
-
-.IP MTEXECOM
-The Windows command line used to embed manifests into executables.
-See also \fB$MTSHLIBCOM\fP.
-
-.IP MTFLAGS
-Flags passed to the \fB$MT\fP manifest embedding program (Windows only).
-
-.IP MTSHLIBCOM
-The Windows command line used to embed manifests into shared libraries (DLLs).
-See also \fB$MTEXECOM\fP.
-
-.IP MWCW_VERSION
-The version number of the MetroWerks CodeWarrior C compiler
-to be used.
-
-.IP MWCW_VERSIONS
-A list of installed versions of the MetroWerks CodeWarrior C compiler
-on this system.
-
-.IP NAME
-Specfies the name of the project to package.
-
-.IP no_import_lib
-When set to non-zero,
-suppresses creation of a corresponding Windows static import lib by the
-.B SharedLibrary
-builder when used with
-MinGW, Microsoft Visual Studio or Metrowerks.
-This also suppresses creation
-of an export (.exp) file
-when using Microsoft Visual Studio.
-
-.IP OBJPREFIX
-The prefix used for (static) object file names.
-
-.IP OBJSUFFIX
-The suffix used for (static) object file names.
-
-.IP P4
-The Perforce executable.
-
-.IP P4COM
-The command line used to
-fetch source files from Perforce.
-
-.IP P4COMSTR
-The string displayed when
-fetching a source file from Perforce.
-If this is not set, then \fB$P4COM\fP (the command line) is displayed.
-
-.IP P4FLAGS
-General options that are passed to Perforce.
-
-.IP PACKAGEROOT
-Specifies the directory where all files in resulting archive will be
-placed if applicable. The default value is "$NAME-$VERSION".
-
-.IP PACKAGETYPE
-Selects the package type to build. Currently these are available:
-
- * msi - Microsoft Installer
- * rpm - Redhat Package Manger
- * ipkg - Itsy Package Management System
- * tarbz2 - compressed tar
- * targz - compressed tar
- * zip - zip file
- * src_tarbz2 - compressed tar source
- * src_targz - compressed tar source
- * src_zip - zip file source
-
-This may be overridden with the "package_type" command line option.
-
-.IP PACKAGEVERSION
-The version of the package (not the underlying project).
-This is currently only used by the rpm packager
-and should reflect changes in the packaging,
-not the underlying project code itself.
-
-.IP PCH
-The Microsoft Visual C++ precompiled header that will be used when compiling
-object files. This variable is ignored by tools other than Microsoft Visual C++.
-When this variable is
-defined SCons will add options to the compiler command line to
-cause it to use the precompiled header, and will also set up the
-dependencies for the PCH file.
-Example:
-
-.ES
-env['PCH'] = 'StdAfx.pch'
-.EE
-
-.IP PCHCOM
-The command line used by the
-.BR PCH ()
-builder to generated a precompiled header.
-
-.IP PCHCOMSTR
-The string displayed when generating a precompiled header.
-If this is not set, then \fB$PCHCOM\fP (the command line) is displayed.
-
-.IP PCHPDBFLAGS
-A construction variable that, when expanded,
-adds the \fB/yD\fP flag to the command line
-only if the \fB$PDB\fP construction variable is set.
-
-.IP PCHSTOP
-This variable specifies how much of a source file is precompiled. This
-variable is ignored by tools other than Microsoft Visual C++, or when
-the PCH variable is not being used. When this variable is define it
-must be a string that is the name of the header that
-is included at the end of the precompiled portion of the source files, or
-the empty string if the "#pragma hrdstop" construct is being used:
-
-.ES
-env['PCHSTOP'] = 'StdAfx.h'
-.EE
-
-.IP PDB
-The Microsoft Visual C++ PDB file that will store debugging information for
-object files, shared libraries, and programs. This variable is ignored by
-tools other than Microsoft Visual C++.
-When this variable is
-defined SCons will add options to the compiler and linker command line to
-cause them to generate external debugging information, and will also set up the
-dependencies for the PDB file.
-Example:
-
-.ES
-env['PDB'] = 'hello.pdb'
-.EE
-.IP
-The Visual C++ compiler switch that SCons uses by default
-to generate PDB information is \fB/Z7\fP.
-This works correctly with parallel (\fB\-j\fP) builds
-because it embeds the debug information in the intermediate object files,
-as opposed to sharing a single PDB file between multiple object files.
-This is also the only way to get debug information
-embedded into a static library.
-Using the \fB/Zi\fP instead may yield improved
-link-time performance,
-although parallel builds will no longer work.
-You can generate PDB files with the \fB/Zi\fP
-switch by overriding the default \fB$CCPDBFLAGS\fP variable;
-see the entry for that variable for specific examples.
-
-.IP PDFCOM
-A deprecated synonym for \fB$DVIPDFCOM\fP.
-
-.IP PDFLATEX
-The &pdflatex; utility.
-
-.IP PDFLATEXCOM
-The command line used to call the &pdflatex; utility.
-
-.IP PDFLATEXCOMSTR
-The string displayed when calling the &pdflatex; utility.
-If this is not set, then \fB$PDFLATEXCOM\fP (the command line) is displayed.
-
-.ES
-env = Environment(PDFLATEX;COMSTR = "Building $TARGET from LaTeX input $SOURCES")
-.EE
-
-.IP PDFLATEXFLAGS
-General options passed to the &pdflatex; utility.
-
-.IP PDFPREFIX
-The prefix used for PDF file names.
-
-.IP PDFSUFFIX
-The suffix used for PDF file names.
-
-.IP PDFTEX
-The &pdftex; utility.
-
-.IP PDFTEXCOM
-The command line used to call the &pdftex; utility.
-
-.IP PDFTEXCOMSTR
-The string displayed when calling the &pdftex; utility.
-If this is not set, then \fB$PDFTEXCOM\fP (the command line) is displayed.
-
-.ES
-env = Environment(PDFTEXCOMSTR = "Building $TARGET from TeX input $SOURCES")
-.EE
-
-.IP PDFTEXFLAGS
-General options passed to the &pdftex; utility.
-
-.IP PKGCHK
-On Solaris systems,
-the package-checking program that will
-be used (along with \fB$PKGINFO\fP)
-to look for installed versions of
-the Sun PRO C++ compiler.
-The default is
-.BR /usr/sbin/pgkchk .
-
-.IP PKGINFO
-On Solaris systems,
-the package information program that will
-be used (along with \fB$PKGCHK\fP)
-to look for installed versions of
-the Sun PRO C++ compiler.
-The default is
-.BR pkginfo .
-
-.IP PLATFORM
-The name of the platform used to create the Environment. If no platform is
-specified when the Environment is created,
-.B scons
-autodetects the platform.
-
-.ES
-env = Environment(tools = [])
-if env['PLATFORM'] == 'cygwin':
- Tool('mingw')(env)
-else:
- Tool('msvc')(env)
-.EE
-
-.IP POAUTOINIT
-The \fB$POAUTOINIT\fP variable, if set to \fBTrue\fP (on non-zero
-numeric value), let the &t-link-msginit; tool to automatically initialize
-\fImissing\fP \fBPO\fP files with
-\fBmsginit(1)\fP. This applies to both,
-\fBPOInit\fP() and \fBPOUpdate\fP() builders (and others that use any of
-them).
-
-.IP POCREATE_ALIAS
-Common alias for all \fBPO\fP files created with \fBPOInit\fP()
-builder (default: \fB'po-create'\fP).
-See &t-link-msginit; tool and \fBPOInit\fP() builder.
-
-.IP POSUFFIX
-Suffix used for \fBPO\fP files (default: \fB'.po'\fP)
-See &t-link-msginit; tool and \fBPOInit\fP() builder.
-
-.IP POTDOMAIN
-The \fB$POTDOMAIN\fP defines default domain, used to generate
-\fBPOT\fP filename as \fB\fB$POTDOMAIN\fP.pot\fP when
-no \fBPOT\fP file name is provided by the user. This applies to
-\fBPOTUpdate\fP(), \fBPOInit\fP() and \fBPOUpdate\fP() builders (and
-builders, that use them, e.g. \fBTranslate\fP()). Normally (if \fB$POTDOMAIN\fP is
-not defined), the builders use \fBmessages.pot\fP as default
-\fBPOT\fP file name.
-
-.IP POTSUFFIX
-Suffix used for PO Template files (default: \fB'.pot'\fP).
-See &t-link-xgettext; tool and \fBPOTUpdate\fP() builder.
-
-.IP POTUPDATE_ALIAS
-Name of the common phony target for all PO Templates created with
-.BR POUpdate\fP() (default: \fB'pot-update' ).
-See &t-link-xgettext; tool and \fBPOTUpdate\fP() builder.
-
-.IP POUPDATE_ALIAS
-Common alias for all \fBPO\fP files being defined with
-.BR POUpdate\fP() builder (default: \fB'po-update' ).
-See &t-link-msgmerge; tool and \fBPOUpdate\fP() builder.
-
-.IP PRINT_CMD_LINE_FUNC
-A Python function used to print the command lines as they are executed
-(assuming command printing is not disabled by the
-.B \-q
-or
-.B \-s
-options or their equivalents).
-The function should take four arguments:
-.IR s ,
-the command being executed (a string),
-.IR target ,
-the target being built (file node, list, or string name(s)),
-.IR source ,
-the source(s) used (file node, list, or string name(s)), and
-.IR env ,
-the environment being used.
-
-The function must do the printing itself. The default implementation,
-used if this variable is not set or is None, is:
-.ES
-def print_cmd_line(s, target, source, env):
- sys.stdout.write(s + "\\n")
-.EE
-.IP
-Here's an example of a more interesting function:
-
-.ES
-def print_cmd_line(s, target, source, env):
- sys.stdout.write("Building %s -> %s...\\n" %
- (' and '.join([str(x) for x in source]),
- ' and '.join([str(x) for x in target])))
-env=Environment(PRINT_CMD_LINE_FUNC=print_cmd_line)
-env.Program('foo', 'foo.c')
-.EE
-.IP
-This just prints "Building \fItargetname\fP from \fIsourcename\fP..." instead
-of the actual commands.
-Such a function could also log the actual commands to a log file,
-for example.
-
-.IP PROGEMITTER
-TODO
-
-.IP PROGPREFIX
-The prefix used for executable file names.
-
-.IP PROGSUFFIX
-The suffix used for executable file names.
-
-.IP PSCOM
-The command line used to convert TeX DVI files into a PostScript file.
-
-.IP PSCOMSTR
-The string displayed when a TeX DVI file
-is converted into a PostScript file.
-If this is not set, then \fB$PSCOM\fP (the command line) is displayed.
-
-.IP PSPREFIX
-The prefix used for PostScript file names.
-
-.IP PSSUFFIX
-The prefix used for PostScript file names.
-
-.IP QT_AUTOSCAN
-Turn off scanning for mocable files. Use the Moc Builder to explicitly
-specify files to run moc on.
-
-.IP QT_BINPATH
-The path where the qt binaries are installed.
-The default value is '\fB$QTDIR\fP/bin'.
-
-.IP QT_CPPPATH
-The path where the qt header files are installed.
-The default value is '\fB$QTDIR\fP/include'.
-Note: If you set this variable to None,
-the tool won't change the \fB$CPPPATH\fP
-construction variable.
-
-.IP QT_DEBUG
-Prints lots of debugging information while scanning for moc files.
-
-.IP QT_LIB
-Default value is 'qt'. You may want to set this to 'qt-mt'. Note: If you set
-this variable to None, the tool won't change the \fB$LIBS\fP variable.
-
-.IP QT_LIBPATH
-The path where the qt libraries are installed.
-The default value is '\fB$QTDIR\fP/lib'.
-Note: If you set this variable to None,
-the tool won't change the \fB$LIBPATH\fP
-construction variable.
-
-.IP QT_MOC
-Default value is '\fB$QT_BINPATH\fP/moc'.
-
-.IP QT_MOCCXXPREFIX
-Default value is ''. Prefix for moc output files, when source is a cxx file.
-
-.IP QT_MOCCXXSUFFIX
-Default value is '.moc'. Suffix for moc output files, when source is a cxx
-file.
-
-.IP QT_MOCFROMCXXCOM
-Command to generate a moc file from a cpp file.
-
-.IP QT_MOCFROMCXXCOMSTR
-The string displayed when generating a moc file from a cpp file.
-If this is not set, then \fB$QT_MOCFROMCXXCOM\fP (the command line) is displayed.
-
-.IP QT_MOCFROMCXXFLAGS
-Default value is '-i'. These flags are passed to moc, when moccing a
-C++ file.
-
-.IP QT_MOCFROMHCOM
-Command to generate a moc file from a header.
-
-.IP QT_MOCFROMHCOMSTR
-The string displayed when generating a moc file from a cpp file.
-If this is not set, then \fB$QT_MOCFROMHCOM\fP (the command line) is displayed.
-
-.IP QT_MOCFROMHFLAGS
-Default value is ''. These flags are passed to moc, when moccing a header
-file.
-
-.IP QT_MOCHPREFIX
-Default value is 'moc_'. Prefix for moc output files, when source is a header.
-
-.IP QT_MOCHSUFFIX
-Default value is '\fB$CXXFILESUFFIX\fP'. Suffix for moc output files, when source is
-a header.
-
-.IP QT_UIC
-Default value is '\fB$QT_BINPATH\fP/uic'.
-
-.IP QT_UICCOM
-Command to generate header files from .ui files.
-
-.IP QT_UICCOMSTR
-The string displayed when generating header files from .ui files.
-If this is not set, then \fB$QT_UICCOM\fP (the command line) is displayed.
-
-.IP QT_UICDECLFLAGS
-Default value is ''. These flags are passed to uic, when creating a a h
-file from a .ui file.
-
-.IP QT_UICDECLPREFIX
-Default value is ''. Prefix for uic generated header files.
-
-.IP QT_UICDECLSUFFIX
-Default value is '.h'. Suffix for uic generated header files.
-
-.IP QT_UICIMPLFLAGS
-Default value is ''. These flags are passed to uic, when creating a cxx
-file from a .ui file.
-
-.IP QT_UICIMPLPREFIX
-Default value is 'uic_'. Prefix for uic generated implementation files.
-
-.IP QT_UICIMPLSUFFIX
-Default value is '\fB$CXXFILESUFFIX\fP'. Suffix for uic generated implementation
-files.
-
-.IP QT_UISUFFIX
-Default value is '.ui'. Suffix of designer input files.
-
-.IP QTDIR
-The qt tool tries to take this from os.environ.
-It also initializes all QT_*
-construction variables listed below.
-(Note that all paths are constructed
-with python's os.path.join() method,
-but are listed here with the '/' separator
-for easier reading.)
-In addition, the construction environment
-variables \fB$CPPPATH\fP,
-\fB$LIBPATH\fP and
-\fB$LIBS\fP may be modified
-and the variables
-.BR $PROGEMITTER\fP, \fB$SHLIBEMITTER and $LIBEMITTER
-are modified. Because the build-performance is affected when using this tool,
-you have to explicitly specify it at Environment creation:
-
-.ES
-Environment(tools=['default','qt'])
-.EE
-.IP
-The qt tool supports the following operations:
-
-.I "Automatic moc file generation from header files."
-You do not have to specify moc files explicitly, the tool does it for you.
-However, there are a few preconditions to do so: Your header file must have
-the same filebase as your implementation file and must stay in the same
-directory. It must have one of the suffixes .h, .hpp, .H, .hxx, .hh. You
-can turn off automatic moc file generation by setting QT_AUTOSCAN to 0.
-See also the corresponding
-.BR Moc() ()
-builder method.
-
-.I "Automatic moc file generation from cxx files."
-As stated in the qt documentation, include the moc file at the end of
-the cxx file. Note that you have to include the file, which is generated
-by the transformation ${QT_MOCCXXPREFIX}<basename>${QT_MOCCXXSUFFIX}, by default
-<basename>.moc. A warning is generated after building the moc file, if you
-do not include the correct file. If you are using VariantDir, you may
-need to specify duplicate=1. You can turn off automatic moc file generation
-by setting QT_AUTOSCAN to 0. See also the corresponding
-.BR Moc ()
-builder method.
-
-.I "Automatic handling of .ui files."
-The implementation files generated from .ui files are handled much the same
-as yacc or lex files. Each .ui file given as a source of Program, Library or
-SharedLibrary will generate three files, the declaration file, the
-implementation file and a moc file. Because there are also generated headers,
-you may need to specify duplicate=1 in calls to VariantDir.
-See also the corresponding
-.BR Uic ()
-builder method.
-
-.IP RANLIB
-The archive indexer.
-
-.IP RANLIBCOM
-The command line used to index a static library archive.
-
-.IP RANLIBCOMSTR
-The string displayed when a static library archive is indexed.
-If this is not set, then \fB$RANLIBCOM\fP (the command line) is displayed.
-
-.ES
-env = Environment(RANLIBCOMSTR = "Indexing $TARGET")
-.EE
-
-.IP RANLIBFLAGS
-General options passed to the archive indexer.
-
-.IP RC
-The resource compiler used to build
-a Microsoft Visual C++ resource file.
-
-.IP RCCOM
-The command line used to build
-a Microsoft Visual C++ resource file.
-
-.IP RCCOMSTR
-The string displayed when invoking the resource compiler
-to build a Microsoft Visual C++ resource file.
-If this is not set, then \fB$RCCOM\fP (the command line) is displayed.
-
-.IP RCFLAGS
-The flags passed to the resource compiler by the RES builder.
-
-.IP RCINCFLAGS
-An automatically-generated construction variable
-containing the command-line options
-for specifying directories to be searched
-by the resource compiler.
-The value of \fB$RCINCFLAGS\fP is created
-by appending \fB$RCINCPREFIX\fP and \fB$RCINCSUFFIX\fP
-to the beginning and end
-of each directory in \fB$CPPPATH\fP.
-
-.IP RCINCPREFIX
-The prefix (flag) used to specify an include directory
-on the resource compiler command line.
-This will be appended to the beginning of each directory
-in the \fB$CPPPATH\fP construction variable
-when the \fB$RCINCFLAGS\fP variable is expanded.
-
-.IP RCINCSUFFIX
-The suffix used to specify an include directory
-on the resource compiler command line.
-This will be appended to the end of each directory
-in the \fB$CPPPATH\fP construction variable
-when the \fB$RCINCFLAGS\fP variable is expanded.
-
-.IP RCS
-The RCS executable.
-Note that this variable is not actually used
-for the command to fetch source files from RCS;
-see the
-.B $RCS_CO
-construction variable, below.
-
-.IP RCS_CO
-The RCS "checkout" executable,
-used to fetch source files from RCS.
-
-.IP RCS_COCOM
-The command line used to
-fetch (checkout) source files from RCS.
-
-.IP RCS_COCOMSTR
-The string displayed when fetching
-a source file from RCS.
-If this is not set, then \fB$RCS_COCOM\fP
-(the command line) is displayed.
-
-.IP RCS_COFLAGS
-Options that are passed to the \fB$RCS_CO\fP command.
-
-.IP RDirs
-A function that converts a string into a list of Dir instances by
-searching the repositories.
-
-.IP REGSVR
-The program used on Windows systems
-to register a newly-built DLL library
-whenever the \fBSharedLibrary\fP() builder
-is passed a keyword argument of \fBregister=1\fP.
-
-.IP REGSVRCOM
-The command line used on Windows systems
-to register a newly-built DLL library
-whenever the \fBSharedLibrary\fP() builder
-is passed a keyword argument of \fBregister=1\fP.
-
-.IP REGSVRCOMSTR
-The string displayed when registering a newly-built DLL file.
-If this is not set, then \fB$REGSVRCOM\fP (the command line) is displayed.
-
-.IP REGSVRFLAGS
-Flags passed to the DLL registration program
-on Windows systems when a newly-built DLL library is registered.
-By default,
-this includes the \fB/s\fP
-that prevents dialog boxes from popping up
-and requiring user attention.
-
-.IP RMIC
-The Java RMI stub compiler.
-
-.IP RMICCOM
-The command line used to compile stub
-and skeleton class files
-from Java classes that contain RMI implementations.
-Any options specified in the \fB$RMICFLAGS\fP construction variable
-are included on this command line.
-
-.IP RMICCOMSTR
-The string displayed when compiling
-stub and skeleton class files
-from Java classes that contain RMI implementations.
-If this is not set, then \fB$RMICCOM\fP (the command line) is displayed.
-
-.ES
-env = Environment(RMICCOMSTR = "Generating stub/skeleton class files $TARGETS from $SOURCES")
-.EE
-
-.IP RMICFLAGS
-General options passed to the Java RMI stub compiler.
-
-.IP _RPATH
-An automatically-generated construction variable
-containing the rpath flags to be used when linking
-a program with shared libraries.
-The value of \fB$_RPATH\fP is created
-by appending \fB$RPATHPREFIX\fP and \fB$RPATHSUFFIX\fP
-to the beginning and end
-of each directory in \fB$RPATH\fP.
-
-.IP RPATH
-A list of paths to search for shared libraries when running programs.
-Currently only used in the GNU (gnulink),
-IRIX (sgilink) and Sun (sunlink) linkers.
-Ignored on platforms and toolchains that don't support it.
-Note that the paths added to RPATH
-are not transformed by
-.B scons
-in any way: if you want an absolute
-path, you must make it absolute yourself.
-
-.IP RPATHPREFIX
-The prefix used to specify a directory to be searched for
-shared libraries when running programs.
-This will be appended to the beginning of each directory
-in the \fB$RPATH\fP construction variable
-when the \fB$_RPATH\fP variable is automatically generated.
-
-.IP RPATHSUFFIX
-The suffix used to specify a directory to be searched for
-shared libraries when running programs.
-This will be appended to the end of each directory
-in the \fB$RPATH\fP construction variable
-when the \fB$_RPATH\fP variable is automatically generated.
-
-.IP RPCGEN
-The RPC protocol compiler.
-
-.IP RPCGENCLIENTFLAGS
-Options passed to the RPC protocol compiler
-when generating client side stubs.
-These are in addition to any flags specified in the
-.B $RPCGENFLAGS
-construction variable.
-
-.IP RPCGENFLAGS
-General options passed to the RPC protocol compiler.
-
-.IP RPCGENHEADERFLAGS
-Options passed to the RPC protocol compiler
-when generating a header file.
-These are in addition to any flags specified in the
-.B $RPCGENFLAGS
-construction variable.
-
-.IP RPCGENSERVICEFLAGS
-Options passed to the RPC protocol compiler
-when generating server side stubs.
-These are in addition to any flags specified in the
-.B $RPCGENFLAGS
-construction variable.
-
-.IP RPCGENXDRFLAGS
-Options passed to the RPC protocol compiler
-when generating XDR routines.
-These are in addition to any flags specified in the
-.B $RPCGENFLAGS
-construction variable.
-
-.IP SCANNERS
-A list of the available implicit dependency scanners.
-New file scanners may be added by
-appending to this list,
-although the more flexible approach
-is to associate scanners
-with a specific Builder.
-See the sections "Builder Objects"
-and "Scanner Objects,"
-below, for more information.
-
-.IP SCCS
-The SCCS executable.
-
-.IP SCCSCOM
-The command line used to
-fetch source files from SCCS.
-
-.IP SCCSCOMSTR
-The string displayed when fetching
-a source file from a CVS repository.
-If this is not set, then \fB$SCCSCOM\fP
-(the command line) is displayed.
-
-.IP SCCSFLAGS
-General options that are passed to SCCS.
-
-.IP SCCSGETFLAGS
-Options that are passed specifically to the SCCS "get" subcommand.
-This can be set, for example, to
-.B \-e
-to check out editable files from SCCS.
-
-.IP SCONS_HOME
-The (optional) path to the SCons library directory,
-initialized from the external environment.
-If set, this is used to construct a shorter and more
-efficient search path in the
-.B $MSVSSCONS
-command line executed
-from Microsoft Visual Studio project files.
-
-.IP SHCC
-The C compiler used for generating shared-library objects.
-
-.IP SHCCCOM
-The command line used to compile a C source file
-to a shared-library object file.
-Any options specified in the \fB$SHCFLAGS\fP,
-\fB$SHCCFLAGS\fP and
-\fB$CPPFLAGS\fP construction variables
-are included on this command line.
-
-.IP SHCCCOMSTR
-The string displayed when a C source file
-is compiled to a shared object file.
-If this is not set, then \fB$SHCCCOM\fP (the command line) is displayed.
-
-.ES
-env = Environment(SHCCCOMSTR = "Compiling shared object $TARGET")
-.EE
-
-.IP SHCCFLAGS
-Options that are passed to the C and C++ compilers
-to generate shared-library objects.
-
-.IP SHCFLAGS
-Options that are passed to the C compiler (only; not C++)
-to generate shared-library objects.
-
-.IP SHCXX
-The C++ compiler used for generating shared-library objects.
-
-.IP SHCXXCOM
-The command line used to compile a C++ source file
-to a shared-library object file.
-Any options specified in the \fB$SHCXXFLAGS\fP and
-\fB$CPPFLAGS\fP construction variables
-are included on this command line.
-
-.IP SHCXXCOMSTR
-The string displayed when a C++ source file
-is compiled to a shared object file.
-If this is not set, then \fB$SHCXXCOM\fP (the command line) is displayed.
-
-.ES
-env = Environment(SHCXXCOMSTR = "Compiling shared object $TARGET")
-.EE
-
-.IP SHCXXFLAGS
-Options that are passed to the C++ compiler
-to generate shared-library objects.
-
-.IP SHELL
-A string naming the shell program that will be passed to the
-.B $SPAWN
-function.
-See the
-.B $SPAWN
-construction variable for more information.
-
-.IP SHF77
-The Fortran 77 compiler used for generating shared-library objects.
-You should normally set the \fB$SHFORTRAN\fP variable,
-which specifies the default Fortran compiler
-for all Fortran versions.
-You only need to set \fB$SHF77\fP if you need to use a specific compiler
-or compiler version for Fortran 77 files.
-
-.IP SHF77COM
-The command line used to compile a Fortran 77 source file
-to a shared-library object file.
-You only need to set \fB$SHF77COM\fP if you need to use a specific
-command line for Fortran 77 files.
-You should normally set the \fB$SHFORTRANCOM\fP variable,
-which specifies the default command line
-for all Fortran versions.
-
-.IP SHF77COMSTR
-The string displayed when a Fortran 77 source file
-is compiled to a shared-library object file.
-If this is not set, then \fB$SHF77COM\fP or \fB$SHFORTRANCOM\fP
-(the command line) is displayed.
-
-.IP SHF77FLAGS
-Options that are passed to the Fortran 77 compiler
-to generated shared-library objects.
-You only need to set \fB$SHF77FLAGS\fP if you need to define specific
-user options for Fortran 77 files.
-You should normally set the \fB$SHFORTRANFLAGS\fP variable,
-which specifies the user-specified options
-passed to the default Fortran compiler
-for all Fortran versions.
-
-.IP SHF77PPCOM
-The command line used to compile a Fortran 77 source file to a
-shared-library object file
-after first running the file through the C preprocessor.
-Any options specified in the \fB$SHF77FLAGS\fP and \fB$CPPFLAGS\fP construction variables
-are included on this command line.
-You only need to set \fB$SHF77PPCOM\fP if you need to use a specific
-C-preprocessor command line for Fortran 77 files.
-You should normally set the \fB$SHFORTRANPPCOM\fP variable,
-which specifies the default C-preprocessor command line
-for all Fortran versions.
-
-.IP SHF77PPCOMSTR
-The string displayed when a Fortran 77 source file
-is compiled to a shared-library object file
-after first running the file through the C preprocessor.
-If this is not set, then \fB$SHF77PPCOM\fP or \fB$SHFORTRANPPCOM\fP
-(the command line) is displayed.
-
-.IP SHF90
-The Fortran 90 compiler used for generating shared-library objects.
-You should normally set the \fB$SHFORTRAN\fP variable,
-which specifies the default Fortran compiler
-for all Fortran versions.
-You only need to set \fB$SHF90\fP if you need to use a specific compiler
-or compiler version for Fortran 90 files.
-
-.IP SHF90COM
-The command line used to compile a Fortran 90 source file
-to a shared-library object file.
-You only need to set \fB$SHF90COM\fP if you need to use a specific
-command line for Fortran 90 files.
-You should normally set the \fB$SHFORTRANCOM\fP variable,
-which specifies the default command line
-for all Fortran versions.
-
-.IP SHF90COMSTR
-The string displayed when a Fortran 90 source file
-is compiled to a shared-library object file.
-If this is not set, then \fB$SHF90COM\fP or \fB$SHFORTRANCOM\fP
-(the command line) is displayed.
-
-.IP SHF90FLAGS
-Options that are passed to the Fortran 90 compiler
-to generated shared-library objects.
-You only need to set \fB$SHF90FLAGS\fP if you need to define specific
-user options for Fortran 90 files.
-You should normally set the \fB$SHFORTRANFLAGS\fP variable,
-which specifies the user-specified options
-passed to the default Fortran compiler
-for all Fortran versions.
-
-.IP SHF90PPCOM
-The command line used to compile a Fortran 90 source file to a
-shared-library object file
-after first running the file through the C preprocessor.
-Any options specified in the \fB$SHF90FLAGS\fP and \fB$CPPFLAGS\fP construction variables
-are included on this command line.
-You only need to set \fB$SHF90PPCOM\fP if you need to use a specific
-C-preprocessor command line for Fortran 90 files.
-You should normally set the \fB$SHFORTRANPPCOM\fP variable,
-which specifies the default C-preprocessor command line
-for all Fortran versions.
-
-.IP SHF90PPCOMSTR
-The string displayed when a Fortran 90 source file
-is compiled to a shared-library object file
-after first running the file through the C preprocessor.
-If this is not set, then \fB$SHF90PPCOM\fP or \fB$SHFORTRANPPCOM\fP
-(the command line) is displayed.
-
-.IP SHF95
-The Fortran 95 compiler used for generating shared-library objects.
-You should normally set the \fB$SHFORTRAN\fP variable,
-which specifies the default Fortran compiler
-for all Fortran versions.
-You only need to set \fB$SHF95\fP if you need to use a specific compiler
-or compiler version for Fortran 95 files.
-
-.IP SHF95COM
-The command line used to compile a Fortran 95 source file
-to a shared-library object file.
-You only need to set \fB$SHF95COM\fP if you need to use a specific
-command line for Fortran 95 files.
-You should normally set the \fB$SHFORTRANCOM\fP variable,
-which specifies the default command line
-for all Fortran versions.
-
-.IP SHF95COMSTR
-The string displayed when a Fortran 95 source file
-is compiled to a shared-library object file.
-If this is not set, then \fB$SHF95COM\fP or \fB$SHFORTRANCOM\fP
-(the command line) is displayed.
-
-.IP SHF95FLAGS
-Options that are passed to the Fortran 95 compiler
-to generated shared-library objects.
-You only need to set \fB$SHF95FLAGS\fP if you need to define specific
-user options for Fortran 95 files.
-You should normally set the \fB$SHFORTRANFLAGS\fP variable,
-which specifies the user-specified options
-passed to the default Fortran compiler
-for all Fortran versions.
-
-.IP SHF95PPCOM
-The command line used to compile a Fortran 95 source file to a
-shared-library object file
-after first running the file through the C preprocessor.
-Any options specified in the \fB$SHF95FLAGS\fP and \fB$CPPFLAGS\fP construction variables
-are included on this command line.
-You only need to set \fB$SHF95PPCOM\fP if you need to use a specific
-C-preprocessor command line for Fortran 95 files.
-You should normally set the \fB$SHFORTRANPPCOM\fP variable,
-which specifies the default C-preprocessor command line
-for all Fortran versions.
-
-.IP SHF95PPCOMSTR
-The string displayed when a Fortran 95 source file
-is compiled to a shared-library object file
-after first running the file through the C preprocessor.
-If this is not set, then \fB$SHF95PPCOM\fP or \fB$SHFORTRANPPCOM\fP
-(the command line) is displayed.
-
-.IP SHFORTRAN
-The default Fortran compiler used for generating shared-library objects.
-
-.IP SHFORTRANCOM
-The command line used to compile a Fortran source file
-to a shared-library object file.
-
-.IP SHFORTRANCOMSTR
-The string displayed when a Fortran source file
-is compiled to a shared-library object file.
-If this is not set, then \fB$SHFORTRANCOM\fP
-(the command line) is displayed.
-
-.IP SHFORTRANFLAGS
-Options that are passed to the Fortran compiler
-to generate shared-library objects.
-
-.IP SHFORTRANPPCOM
-The command line used to compile a Fortran source file to a
-shared-library object file
-after first running the file through the C preprocessor.
-Any options specified
-in the \fB$SHFORTRANFLAGS\fP and
-\fB$CPPFLAGS\fP construction variables
-are included on this command line.
-
-.IP SHFORTRANPPCOMSTR
-The string displayed when a Fortran source file
-is compiled to a shared-library object file
-after first running the file through the C preprocessor.
-If this is not set, then \fB$SHFORTRANPPCOM\fP
-(the command line) is displayed.
-
-.IP SHLIBEMITTER
-TODO
-
-.IP SHLIBPREFIX
-The prefix used for shared library file names.
-
-.IP SHLIBSUFFIX
-The suffix used for shared library file names.
-
-.IP SHLIBVERSION
-When this construction variable is defined, a versioned shared library
-is created. This modifies the \fB$SHLINKFLAGS\fP as required, adds
-the version number to the library name, and creates the symlinks that
-are needed. \fB$SHLIBVERSION\fP needs to be of the form X.Y.Z,
-where X and Y are numbers, and Z is a number but can also contain
-letters to designate alpha, beta, or release candidate patch levels.
-
-.IP SHLINK
-The linker for programs that use shared libraries.
-
-.IP SHLINKCOM
-The command line used to link programs using shared libraries.
-
-.IP SHLINKCOMSTR
-The string displayed when programs using shared libraries are linked.
-If this is not set, then \fB$SHLINKCOM\fP (the command line) is displayed.
-
-.ES
-env = Environment(SHLINKCOMSTR = "Linking shared $TARGET")
-.EE
-
-.IP SHLINKFLAGS
-General user options passed to the linker for programs using shared libraries.
-Note that this variable should
-.I not
-contain
-.B \-l
-(or similar) options for linking with the libraries listed in \fB$LIBS\fP,
-nor
-.B \-L
-(or similar) include search path options
-that scons generates automatically from \fB$LIBPATH\fP.
-See
-.B $_LIBFLAGS
-above,
-for the variable that expands to library-link options,
-and
-.B $_LIBDIRFLAGS
-above,
-for the variable that expands to library search path options.
-
-.IP SHOBJPREFIX
-The prefix used for shared object file names.
-
-.IP SHOBJSUFFIX
-The suffix used for shared object file names.
-
-.IP SOURCE
-A reserved variable name
-that may not be set or used in a construction environment.
-(See "Variable Substitution," below.)
-
-.IP SOURCE_URL
-The URL
-(web address)
-of the location from which the project was retrieved.
-This is used to fill in the
-.B Source:
-field in the controlling information for Ipkg and RPM packages.
-
-.IP SOURCES
-A reserved variable name
-that may not be set or used in a construction environment.
-(See "Variable Substitution," below.)
-
-.IP SPAWN
-A command interpreter function that will be called to execute command line
-strings. The function must expect the following arguments:
-
-.ES
-def spawn(shell, escape, cmd, args, env):
-.EE
-.IP
-.I sh
-is a string naming the shell program to use.
-.I escape
-is a function that can be called to escape shell special characters in
-the command line.
-.I cmd
-is the path to the command to be executed.
-.I args
-is the arguments to the command.
-.I env
-is a dictionary of the environment variables
-in which the command should be executed.
-
-.IP SUBST_DICT
-The dictionary used by the \fBSubstfile\fP() or \fBTextfile\fP() builders
-for substitution values.
-It can be anything acceptable to the dict() constructor,
-so in addition to a dictionary,
-lists of tuples are also acceptable.
-
-.IP SUBSTFILEPREFIX
-The prefix used for \fBSubstfile\fP() file names,
-the null string by default.
-
-.IP SUBSTFILESUFFIX
-The suffix used for \fBSubstfile\fP() file names,
-the null string by default.
-
-.IP SUMMARY
-A short summary of what the project is about.
-This is used to fill in the
-.B Summary:
-field in the controlling information for Ipkg and RPM packages,
-and as the
-.B Description:
-field in MSI packages.
-
-.IP SWIG
-The scripting language wrapper and interface generator.
-
-.IP SWIGCFILESUFFIX
-The suffix that will be used for intermediate C
-source files generated by
-the scripting language wrapper and interface generator.
-The default value is
-.BR _wrap\fP\fB$CFILESUFFIX .
-By default, this value is used whenever the
-.B \-c++
-option is
-.I not
-specified as part of the
-.B $SWIGFLAGS
-construction variable.
-
-.IP SWIGCOM
-The command line used to call
-the scripting language wrapper and interface generator.
-
-.IP SWIGCOMSTR
-The string displayed when calling
-the scripting language wrapper and interface generator.
-If this is not set, then \fB$SWIGCOM\fP (the command line) is displayed.
-
-.IP SWIGCXXFILESUFFIX
-The suffix that will be used for intermediate C++
-source files generated by
-the scripting language wrapper and interface generator.
-The default value is
-.BR _wrap\fP\fB$CFILESUFFIX .
-By default, this value is used whenever the
-.B \-c++
-option is specified as part of the
-.B $SWIGFLAGS
-construction variable.
-
-.IP SWIGDIRECTORSUFFIX
-The suffix that will be used for intermediate C++ header
-files generated by the scripting language wrapper and interface generator.
-These are only generated for C++ code when the SWIG 'directors' feature is
-turned on.
-The default value is
-.BR _wrap.h .
-
-.IP SWIGFLAGS
-General options passed to
-the scripting language wrapper and interface generator.
-This is where you should set
-.BR \-python ,
-.BR \-perl5 ,
-.BR \-tcl ,
-or whatever other options you want to specify to SWIG.
-If you set the
-.B \-c++
-option in this variable,
-.B scons
-will, by default,
-generate a C++ intermediate source file
-with the extension that is specified as the
-.B $CXXFILESUFFIX
-variable.
-
-.IP _SWIGINCFLAGS
-An automatically-generated construction variable
-containing the SWIG command-line options
-for specifying directories to be searched for included files.
-The value of \fB$_SWIGINCFLAGS\fP is created
-by appending \fB$SWIGINCPREFIX\fP and \fB$SWIGINCSUFFIX\fP
-to the beginning and end
-of each directory in \fB$SWIGPATH\fP.
-
-.IP SWIGINCPREFIX
-The prefix used to specify an include directory on the SWIG command line.
-This will be appended to the beginning of each directory
-in the \fB$SWIGPATH\fP construction variable
-when the \fB$_SWIGINCFLAGS\fP variable is automatically generated.
-
-.IP SWIGINCSUFFIX
-The suffix used to specify an include directory on the SWIG command line.
-This will be appended to the end of each directory
-in the \fB$SWIGPATH\fP construction variable
-when the \fB$_SWIGINCFLAGS\fP variable is automatically generated.
-
-.IP SWIGOUTDIR
-Specifies the output directory in which
-the scripting language wrapper and interface generator
-should place generated language-specific files.
-This will be used by SCons to identify
-the files that will be generated by the &swig; call,
-and translated into the
-\fBswig -outdir\fP option on the command line.
-
-.IP SWIGPATH
-The list of directories that the scripting language wrapper
-and interface generate will search for included files.
-The SWIG implicit dependency scanner will search these
-directories for include files.
-The default is to use the same path
-specified as \fB$CPPPATH\fP.
-
-Don't explicitly put include directory
-arguments in SWIGFLAGS;
-the result will be non-portable
-and the directories will not be searched by the dependency scanner.
-Note: directory names in SWIGPATH will be looked-up relative to the SConscript
-directory when they are used in a command.
-To force
-.B scons
-to look-up a directory relative to the root of the source tree use #:
-
-.ES
-env = Environment(SWIGPATH='#/include')
-.EE
-.IP
-The directory look-up can also be forced using the
-.BR Dir ()
-function:
-
-.ES
-include = Dir('include')
-env = Environment(SWIGPATH=include)
-.EE
-.IP
-The directory list will be added to command lines
-through the automatically-generated
-.B $_SWIGINCFLAGS
-construction variable,
-which is constructed by
-appending the values of the
-.BR $SWIGINCPREFIX and $SWIGINCSUFFIX
-construction variables
-to the beginning and end
-of each directory in \fB$SWIGPATH\fP.
-Any command lines you define that need
-the SWIGPATH directory list should
-include \fB$_SWIGINCFLAGS\fP:
-
-.ES
-env = Environment(SWIGCOM="my_swig -o $TARGET $_SWIGINCFLAGS $SORUCES")
-.EE
-
-.IP SWIGVERSION
-The version number of the SWIG tool.
-
-.IP TAR
-The tar archiver.
-
-.IP TARCOM
-The command line used to call the tar archiver.
-
-.IP TARCOMSTR
-The string displayed when archiving files
-using the tar archiver.
-If this is not set, then \fB$TARCOM\fP (the command line) is displayed.
-
-.ES
-env = Environment(TARCOMSTR = "Archiving $TARGET")
-.EE
-
-.IP TARFLAGS
-General options passed to the tar archiver.
-
-.IP TARGET
-A reserved variable name
-that may not be set or used in a construction environment.
-(See "Variable Substitution," below.)
-
-.IP TARGET_ARCH
-Sets the target architecture for Visual Studio compiler (i.e. the arch
-of the binaries generated by the compiler). If not set, default to
-\fB$HOST_ARCH\fP, or, if that is unset, to the architecture of the
-running machine's OS (note that the python build or architecture has no
-effect).
-This variable must be passed as an argument to the Environment()
-constructor; setting it later has no effect.
-This is currently only used on Windows, but in the future it will be
-used on other OSes as well.
-
-Valid values for Windows are
-.BR x86 ,
-.B i386
-(for 32 bits);
-.BR amd64 ,
-.BR emt64 ,
-.B x86_64
-(for 64 bits);
-and \fBia64\fP (Itanium).
-For example, if you want to compile 64-bit binaries, you would set
-\fBTARGET_ARCH='x86_64'\fP in your SCons environment.
-
-.IP TARGET_OS
- The name of the target operating system for the compiled objects
- created by this Environment.
- This defaults to the value of HOST_OS, and the user can override it.
- Currently only set for Win32.
-
-.IP TARGETS
-A reserved variable name
-that may not be set or used in a construction environment.
-(See "Variable Substitution," below.)
-
-.IP TARSUFFIX
-The suffix used for tar file names.
-
-.IP TEMPFILEPREFIX
-The prefix for a temporary file used
-to execute lines longer than $MAXLINELENGTH.
-The default is '@'.
-This may be set for toolchains that use other values,
-such as '-@' for the diab compiler
-or '-via' for ARM toolchain.
-
-.IP TEX
-The TeX formatter and typesetter.
-
-.IP TEXCOM
-The command line used to call the TeX formatter and typesetter.
-
-.IP TEXCOMSTR
-The string displayed when calling
-the TeX formatter and typesetter.
-If this is not set, then \fB$TEXCOM\fP (the command line) is displayed.
-
-.ES
-env = Environment(TEXCOMSTR = "Building $TARGET from TeX input $SOURCES")
-.EE
-
-.IP TEXFLAGS
-General options passed to the TeX formatter and typesetter.
-
-.IP TEXINPUTS
-List of directories that the LaTeX program will search
-for include directories.
-The LaTeX implicit dependency scanner will search these
-directories for \\include and \\import files.
-
-.IP TEXTFILEPREFIX
-The prefix used for \fBTextfile\fP() file names,
-the null string by default.
-
-.IP TEXTFILESUFFIX
-The suffix used for \fBTextfile\fP() file names;
-\fB.txt\fP by default.
-
-.IP TOOLS
-A list of the names of the Tool specifications
-that are part of this construction environment.
-
-.IP UNCHANGED_SOURCES
-A reserved variable name
-that may not be set or used in a construction environment.
-(See "Variable Substitution," below.)
-
-.IP UNCHANGED_TARGETS
-A reserved variable name
-that may not be set or used in a construction environment.
-(See "Variable Substitution," below.)
-
-.IP VENDOR
-The person or organization who supply the packaged software.
-This is used to fill in the
-.B Vendor:
-field in the controlling information for RPM packages,
-and the
-.B Manufacturer:
-field in the controlling information for MSI packages.
-
-.IP VERSION
-The version of the project, specified as a string.
-
-.IP WIN32_INSERT_DEF
-A deprecated synonym for \fB$WINDOWS_INSERT_DEF\fP.
-
-.IP WIN32DEFPREFIX
-A deprecated synonym for \fB$WINDOWSDEFPREFIX\fP.
-
-.IP WIN32DEFSUFFIX
-A deprecated synonym for \fB$WINDOWSDEFSUFFIX\fP.
-
-.IP WIN32EXPPREFIX
-A deprecated synonym for \fB$WINDOWSEXPSUFFIX\fP.
-
-.IP WIN32EXPSUFFIX
-A deprecated synonym for \fB$WINDOWSEXPSUFFIX\fP.
-
-.IP WINDOWS_EMBED_MANIFEST
-Set this variable to True or 1 to embed the compiler-generated manifest
-(normally \fB${TARGET}.manifest\fP)
-into all Windows exes and DLLs built with this environment,
-as a resource during their link step.
-This is done using \fB$MT\fP and \fB$MTEXECOM\fP and \fB$MTSHLIBCOM\fP.
-
-.IP WINDOWS_INSERT_DEF
-When this is set to true,
-a library build of a Windows shared library
-(\fB.dll\fP file)
-will also build a corresponding \fB.def\fP file
-at the same time,
-if a \fB.def\fP file
-is not already listed as a build target.
-The default is 0 (do not build a \fB.def\fP file).
-
-.IP WINDOWS_INSERT_MANIFEST
-When this is set to true,
-.B scons
-will be aware of the
-.B .manifest
-files generated by Microsoft Visua C/C++ 8.
-
-.IP WINDOWSDEFPREFIX
-The prefix used for Windows \fB.def\fP file names.
-
-.IP WINDOWSDEFSUFFIX
-The suffix used for Windows \fB.def\fP file names.
-
-.IP WINDOWSEXPPREFIX
-The prefix used for Windows \fB.exp\fP file names.
-
-.IP WINDOWSEXPSUFFIX
-The suffix used for Windows \fB.exp\fP file names.
-
-.IP WINDOWSPROGMANIFESTPREFIX
-The prefix used for executable program \fB.manifest\fP files
-generated by Microsoft Visual C/C++.
-
-.IP WINDOWSPROGMANIFESTSUFFIX
-The suffix used for executable program \fB.manifest\fP files
-generated by Microsoft Visual C/C++.
-
-.IP WINDOWSSHLIBMANIFESTPREFIX
-The prefix used for shared library \fB.manifest\fP files
-generated by Microsoft Visual C/C++.
-
-.IP WINDOWSSHLIBMANIFESTSUFFIX
-The suffix used for shared library \fB.manifest\fP files
-generated by Microsoft Visual C/C++.
-
-.IP X_IPK_DEPENDS
-This is used to fill in the
-.B Depends:
-field in the controlling information for Ipkg packages.
-
-.IP X_IPK_DESCRIPTION
-This is used to fill in the
-.B Description:
-field in the controlling information for Ipkg packages.
-The default value is
-.B "$SUMMARY\\n$DESCRIPTION"
-.IP X_IPK_MAINTAINER
-This is used to fill in the
-.B Maintainer:
-field in the controlling information for Ipkg packages.
-
-.IP X_IPK_PRIORITY
-This is used to fill in the
-.B Priority:
-field in the controlling information for Ipkg packages.
-
-.IP X_IPK_SECTION
-This is used to fill in the
-.B Section:
-field in the controlling information for Ipkg packages.
-
-.IP X_MSI_LANGUAGE
-This is used to fill in the
-.B Language:
-attribute in the controlling information for MSI packages.
-
-.IP X_MSI_LICENSE_TEXT
-The text of the software license in RTF format.
-Carriage return characters will be
-replaced with the RTF equivalent \\\\par.
-
-.IP X_MSI_UPGRADE_CODE
-TODO
-
-.IP X_RPM_AUTOREQPROV
-This is used to fill in the
-.B AutoReqProv:
-field in the RPM
-\fB.spec\fP file.
-
-.IP X_RPM_BUILD
-internal, but overridable
-
-.IP X_RPM_BUILDREQUIRES
-This is used to fill in the
-.B BuildRequires:
-field in the RPM
-\fB.spec\fP file.
-
-.IP X_RPM_BUILDROOT
-internal, but overridable
-
-.IP X_RPM_CLEAN
-internal, but overridable
-
-.IP X_RPM_CONFLICTS
-This is used to fill in the
-.B Conflicts:
-field in the RPM
-\fB.spec\fP file.
-
-.IP X_RPM_DEFATTR
-This value is used as the default attributes
-for the files in the RPM package.
-The default value is
-.BR (-,root,root) .
-
-.IP X_RPM_DISTRIBUTION
-This is used to fill in the
-.B Distribution:
-field in the RPM
-\fB.spec\fP file.
-
-.IP X_RPM_EPOCH
-This is used to fill in the
-.B Epoch:
-field in the controlling information for RPM packages.
-
-.IP X_RPM_EXCLUDEARCH
-This is used to fill in the
-.B ExcludeArch:
-field in the RPM
-\fB.spec\fP file.
-
-.IP X_RPM_EXLUSIVEARCH
-This is used to fill in the
-.B ExclusiveArch:
-field in the RPM
-\fB.spec\fP file.
-
-.IP X_RPM_GROUP
-This is used to fill in the
-.B Group:
-field in the RPM
-\fB.spec\fP file.
-
-.IP X_RPM_GROUP_lang
-This is used to fill in the
-.B Group(lang):
-field in the RPM
-\fB.spec\fP file.
-Note that
-.I lang
-is not literal
-and should be replaced by
-the appropriate language code.
-
-.IP X_RPM_ICON
-This is used to fill in the
-.B Icon:
-field in the RPM
-\fB.spec\fP file.
-
-.IP X_RPM_INSTALL
-internal, but overridable
-
-.IP X_RPM_PACKAGER
-This is used to fill in the
-.B Packager:
-field in the RPM
-\fB.spec\fP file.
-
-.IP X_RPM_POSTINSTALL
-This is used to fill in the
-.B %post:
-section in the RPM
-\fB.spec\fP file.
-
-.IP X_RPM_POSTUNINSTALL
-This is used to fill in the
-.B %postun:
-section in the RPM
-\fB.spec\fP file.
-
-.IP X_RPM_PREFIX
-This is used to fill in the
-.B Prefix:
-field in the RPM
-\fB.spec\fP file.
-
-.IP X_RPM_PREINSTALL
-This is used to fill in the
-.B %pre:
-section in the RPM
-\fB.spec\fP file.
-
-.IP X_RPM_PREP
-internal, but overridable
-
-.IP X_RPM_PREUNINSTALL
-This is used to fill in the
-.B %preun:
-section in the RPM
-\fB.spec\fP file.
-
-.IP X_RPM_PROVIDES
-This is used to fill in the
-.B Provides:
-field in the RPM
-\fB.spec\fP file.
-
-.IP X_RPM_REQUIRES
-This is used to fill in the
-.B Requires:
-field in the RPM
-\fB.spec\fP file.
-
-.IP X_RPM_SERIAL
-This is used to fill in the
-.B Serial:
-field in the RPM
-\fB.spec\fP file.
-
-.IP X_RPM_URL
-This is used to fill in the
-.B Url:
-field in the RPM
-\fB.spec\fP file.
-
-.IP XGETTEXT
-Path to \fBxgettext(1)\fP program (found via
-.BR Detect() ).
-See &t-link-xgettext; tool and \fBPOTUpdate\fP() builder.
-
-.IP XGETTEXTCOM
-Complete xgettext command line.
-See &t-link-xgettext; tool and \fBPOTUpdate\fP() builder.
-
-.IP XGETTEXTCOMSTR
-A string that is shown when \fBxgettext(1)\fP command is invoked
-(default: \fB''\fP, which means "print \fB$XGETTEXTCOM\fP").
-See &t-link-xgettext; tool and \fBPOTUpdate\fP() builder.
-
-.IP _XGETTEXTDOMAIN
-Internal "macro". Generates \fBxgettext\fP domain name
-form source and target (default: \fB'${TARGET.filebase}'\fP).
-
-.IP XGETTEXTFLAGS
-Additional flags to \fBxgettext(1)\fP.
-See &t-link-xgettext; tool and \fBPOTUpdate\fP() builder.
-
-.IP XGETTEXTFROM
-Name of file containing list of \fBxgettext(1)\fP's source
-files. Autotools' users know this as \fBPOTFILES.in\fP so they
-will in most cases set \fBXGETTEXTFROM="POTFILES.in"\fP here.
-The \fB$XGETTEXTFROM\fP files have same syntax and semantics as the well known
-GNU \fBPOTFILES.in\fP.
-See &t-link-xgettext; tool and \fBPOTUpdate\fP() builder.
-
-.IP _XGETTEXTFROMFLAGS
-Internal "macro". Genrates list of \fB\-D<dir>\fP flags
-from the \fB$XGETTEXTPATH\fP list.
-
-.IP XGETTEXTFROMPREFIX
-This flag is used to add single \fB$XGETTEXTFROM\fP file to
-\fBxgettext(1)\fP's commandline (default:
-.BR '-f' ).
-
-.IP XGETTEXTFROMSUFFIX
-(default: \fB''\fP)
-
-.IP XGETTEXTPATH
-List of directories, there \fBxgettext(1)\fP will look for
-source files (default: \fB[]\fP).
-<note>This variable works only together with \fB$XGETTEXTFROM\fP
-</para></note>
-See also &t-link-xgettext; tool and \fBPOTUpdate\fP() builder.
-
-.IP _XGETTEXTPATHFLAGS
-Internal "macro". Generates list of \fB\-f<file>\fP flags
-from \fB$XGETTEXTFROM\fP.
-
-.IP XGETTEXTPATHPREFIX
-This flag is used to add single search path to
-\fBxgettext(1)\fP's commandline (default:
-.BR '-D' ).
-
-.IP XGETTEXTPATHSUFFIX
-(default: \fB''\fP)
-
-.IP YACC
-The parser generator.
-
-.IP YACCCOM
-The command line used to call the parser generator
-to generate a source file.
-
-.IP YACCCOMSTR
-The string displayed when generating a source file
-using the parser generator.
-If this is not set, then \fB$YACCCOM\fP (the command line) is displayed.
-
-.ES
-env = Environment(YACCCOMSTR = "Yacc'ing $TARGET from $SOURCES")
-.EE
-
-.IP YACCFLAGS
-General options passed to the parser generator.
-If \fB$YACCFLAGS\fP contains a \fB\-d\fP option,
-SCons assumes that the call will also create a .h file
-(if the yacc source file ends in a .y suffix)
-or a .hpp file
-(if the yacc source file ends in a .yy suffix)
-
-.IP YACCHFILESUFFIX
-The suffix of the C
-header file generated by the parser generator
-when the
-.B \-d
-option is used.
-Note that setting this variable does not cause
-the parser generator to generate a header
-file with the specified suffix,
-it exists to allow you to specify
-what suffix the parser generator will use of its own accord.
-The default value is
-.BR .h .
-
-.IP YACCHXXFILESUFFIX
-The suffix of the C++
-header file generated by the parser generator
-when the
-.B \-d
-option is used.
-Note that setting this variable does not cause
-the parser generator to generate a header
-file with the specified suffix,
-it exists to allow you to specify
-what suffix the parser generator will use of its own accord.
-The default value is
-.BR .hpp ,
-except on Mac OS X,
-where the default is
-.BR ${TARGET.suffix}.h .
-because the default &bison; parser generator just
-appends \fB.h\fP
-to the name of the generated C++ file.
-
-.IP YACCVCGFILESUFFIX
-The suffix of the file
-containing the VCG grammar automaton definition
-when the
-.B \-\-graph=
-option is used.
-Note that setting this variable does not cause
-the parser generator to generate a VCG
-file with the specified suffix,
-it exists to allow you to specify
-what suffix the parser generator will use of its own accord.
-The default value is
-.BR .vcg .
-
-.IP ZIP
-The zip compression and file packaging utility.
-
-.IP ZIPCOM
-The command line used to call the zip utility,
-or the internal Python function used to create a
-zip archive.
-
-.IP ZIPCOMPRESSION
-The
-.I compression
-flag
-from the Python
-.B zipfile
-module used by the internal Python function
-to control whether the zip archive
-is compressed or not.
-The default value is
-.BR zipfile.ZIP_DEFLATED ,
-which creates a compressed zip archive.
-This value has no effect if the
-.B zipfile
-module is unavailable.
-
-.IP ZIPCOMSTR
-The string displayed when archiving files
-using the zip utility.
-If this is not set, then \fB$ZIPCOM\fP
-(the command line or internal Python function) is displayed.
-
-.ES
-env = Environment(ZIPCOMSTR = "Zipping $TARGET")
-.EE
-
-.IP ZIPFLAGS
-General options passed to the zip utility.
-
-.IP ZIPSUFFIX
-The suffix used for zip file names.
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-'\" END GENERATED CONSTRUCTION VARIABLE DESCRIPTIONS
-'\"
-'\" The descriptions above of the various SCons construction variables
-'\" are generated from the .xml files that live next to the various
-'\" Python modules in the build enginer library. If you're reading
-'\" this [gnt]roff file with an eye towards patching this man page,
-'\" you can still submit a diff against this text, but it will have to
-'\" be translated to a diff against the underlying .xml file before the
-'\" patch is actually accepted. If you do that yourself, it will make
-'\" it easier to integrate the patch.
-'\"
-'\" END GENERATED CONSTRUCTION VARIABLE DESCRIPTIONS
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-
-.LP
-Construction variables can be retrieved and set using the
-.B Dictionary
-method of the construction environment:
-
-.ES
-dict = env.Dictionary()
-dict["CC"] = "cc"
-.EE
-
-or using the [] operator:
-
-.ES
-env["CC"] = "cc"
-.EE
-
-Construction variables can also be passed to the construction environment
-constructor:
-
-.ES
-env = Environment(CC="cc")
-.EE
-
-or when copying a construction environment using the
-.B Clone
-method:
-
-.ES
-env2 = env.Clone(CC="cl.exe")
-.EE
-
-.SS Configure Contexts
-
-.B scons
-supports
-.I configure contexts,
-an integrated mechanism similar to the
-various AC_CHECK macros in GNU autoconf
-for testing for the existence of C header
-files, libraries, etc.
-In contrast to autoconf,
-.B scons
-does not maintain an explicit cache of the tested values,
-but uses its normal dependency tracking to keep the checked values
-up to date. However, users may override this behaviour with the
-.B --config
-command line option.
-
-The following methods can be used to perform checks:
-
-.TP
-.RI Configure( env ", [" custom_tests ", " conf_dir ", " log_file ", " config_h ", " clean ", " help])
-.TP
-.RI env.Configure([ custom_tests ", " conf_dir ", " log_file ", " config_h ", " clean ", " help])
-This creates a configure context, which can be used to perform checks.
-.I env
-specifies the environment for building the tests.
-This environment may be modified when performing checks.
-.I custom_tests
-is a dictionary containing custom tests.
-See also the section about custom tests below.
-By default, no custom tests are added to the configure context.
-.I conf_dir
-specifies a directory where the test cases are built.
-Note that this directory is not used for building
-normal targets.
-The default value is the directory
-#/.sconf_temp.
-.I log_file
-specifies a file which collects the output from commands
-that are executed to check for the existence of header files, libraries, etc.
-The default is the file #/config.log.
-If you are using the
-.BR VariantDir ()
-method,
-you may want to specify a subdirectory under your variant directory.
-.I config_h
-specifies a C header file where the results of tests
-will be written, e.g. #define HAVE_STDIO_H, #define HAVE_LIBM, etc.
-The default is to not write a
-.B config.h
-file.
-You can specify the same
-.B config.h
-file in multiple calls to Configure,
-in which case
-.B scons
-will concatenate all results in the specified file.
-Note that SCons
-uses its normal dependency checking
-to decide if it's necessary to rebuild
-the specified
-.I config_h
-file.
-This means that the file is not necessarily re-built each
-time scons is run,
-but is only rebuilt if its contents will have changed
-and some target that depends on the
-.I config_h
-file is being built.
-
-The optional
-.B clean
-and
-.B help
-arguments can be used to suppress execution of the configuration
-tests when the
-.B -c/--clean
-or
-.B -H/-h/--help
-options are used, respectively.
-The default behavior is always to execute
-configure context tests,
-since the results of the tests may
-affect the list of targets to be cleaned
-or the help text.
-If the configure tests do not affect these,
-then you may add the
-.B clean=False
-or
-.B help=False
-arguments
-(or both)
-to avoid unnecessary test execution.
-
-.EE
-A created
-.B Configure
-instance has the following associated methods:
-
-.TP
-.RI SConf.Finish( context )
-.TP
-.IR sconf .Finish()
-This method should be called after configuration is done.
-It returns the environment as modified
-by the configuration checks performed.
-After this method is called, no further checks can be performed
-with this configuration context.
-However, you can create a new
-.RI Configure
-context to perform additional checks.
-Only one context should be active at a time.
-
-The following Checks are predefined.
-(This list will likely grow larger as time
-goes by and developers contribute new useful tests.)
-
-.TP
-.RI SConf.CheckHeader( context ", " header ", [" include_quotes ", " language ])
-.TP
-.IR sconf .CheckHeader( header ", [" include_quotes ", " language ])
-Checks if
-.I header
-is usable in the specified language.
-.I header
-may be a list,
-in which case the last item in the list
-is the header file to be checked,
-and the previous list items are
-header files whose
-.B #include
-lines should precede the
-header line being checked for.
-The optional argument
-.I include_quotes
-must be
-a two character string, where the first character denotes the opening
-quote and the second character denotes the closing quote.
-By default, both characters are " (double quote).
-The optional argument
-.I language
-should be either
-.B C
-or
-.B C++
-and selects the compiler to be used for the check.
-Returns 1 on success and 0 on failure.
-
-.TP
-.RI SConf.CheckCHeader( context ", " header ", [" include_quotes ])
-.TP
-.IR sconf .CheckCHeader( header ", [" include_quotes ])
-This is a wrapper around
-.B SConf.CheckHeader
-which checks if
-.I header
-is usable in the C language.
-.I header
-may be a list,
-in which case the last item in the list
-is the header file to be checked,
-and the previous list items are
-header files whose
-.B #include
-lines should precede the
-header line being checked for.
-The optional argument
-.I include_quotes
-must be
-a two character string, where the first character denotes the opening
-quote and the second character denotes the closing quote (both default
-to \N'34').
-Returns 1 on success and 0 on failure.
-
-.TP
-.RI SConf.CheckCXXHeader( context ", " header ", [" include_quotes ])
-.TP
-.IR sconf .CheckCXXHeader( header ", [" include_quotes ])
-This is a wrapper around
-.B SConf.CheckHeader
-which checks if
-.I header
-is usable in the C++ language.
-.I header
-may be a list,
-in which case the last item in the list
-is the header file to be checked,
-and the previous list items are
-header files whose
-.B #include
-lines should precede the
-header line being checked for.
-The optional argument
-.I include_quotes
-must be
-a two character string, where the first character denotes the opening
-quote and the second character denotes the closing quote (both default
-to \N'34').
-Returns 1 on success and 0 on failure.
-
-.TP
-.RI SConf.CheckFunc( context, ", " function_name ", [" header ", " language ])
-.TP
-.IR sconf .CheckFunc( function_name ", [" header ", " language ])
-Checks if the specified
-C or C++ function is available.
-.I function_name
-is the name of the function to check for.
-The optional
-.I header
-argument is a string
-that will be
-placed at the top
-of the test file
-that will be compiled
-to check if the function exists;
-the default is:
-.ES
-#ifdef __cplusplus
-extern "C"
-#endif
-char function_name();
-.EE
-The optional
-.I language
-argument should be
-.B C
-or
-.B C++
-and selects the compiler to be used for the check;
-the default is "C".
-
-.TP
-.RI SConf.CheckLib( context ", [" library ", " symbol ", " header ", " language ", " autoadd=1 ])
-.TP
-.IR sconf .CheckLib([ library ", " symbol ", " header ", " language ", " autoadd=1 ])
-Checks if
-.I library
-provides
-.IR symbol .
-If the value of
-.I autoadd
-is 1 and the library provides the specified
-.IR symbol ,
-appends the library to the LIBS construction environment variable.
-.I library
-may also be None (the default),
-in which case
-.I symbol
-is checked with the current LIBS variable,
-or a list of library names,
-in which case each library in the list
-will be checked for
-.IR symbol .
-If
-.I symbol
-is not set or is
-.BR None ,
-then
-.BR SConf.CheckLib ()
-just checks if
-you can link against the specified
-.IR library .
-The optional
-.I language
-argument should be
-.B C
-or
-.B C++
-and selects the compiler to be used for the check;
-the default is "C".
-The default value for
-.I autoadd
-is 1.
-This method returns 1 on success and 0 on error.
-
-.TP
-.RI SConf.CheckLibWithHeader( context ", " library ", " header ", " language ", [" call ", " autoadd ])
-.TP
-.IR sconf .CheckLibWithHeader( library ", " header ", " language ", [" call ", " autoadd ])
-
-In contrast to the
-.RI SConf.CheckLib
-call, this call provides a more sophisticated way to check against libraries.
-Again,
-.I library
-specifies the library or a list of libraries to check.
-.I header
-specifies a header to check for.
-.I header
-may be a list,
-in which case the last item in the list
-is the header file to be checked,
-and the previous list items are
-header files whose
-.B #include
-lines should precede the
-header line being checked for.
-.I language
-may be one of 'C','c','CXX','cxx','C++' and 'c++'.
-.I call
-can be any valid expression (with a trailing ';').
-If
-.I call
-is not set,
-the default simply checks that you
-can link against the specified
-.IR library .
-.I autoadd
-specifies whether to add the library to the environment (only if the check
-succeeds). This method returns 1 on success and 0 on error.
-
-.TP
-.RI SConf.CheckType( context ", " type_name ", [" includes ", " language ])
-.TP
-.IR sconf .CheckType( type_name ", [" includes ", " language ])
-Checks for the existence of a type defined by
-.BR typedef .
-.I type_name
-specifies the typedef name to check for.
-.I includes
-is a string containing one or more
-.B #include
-lines that will be inserted into the program
-that will be run to test for the existence of the type.
-The optional
-.I language
-argument should be
-.B C
-or
-.B C++
-and selects the compiler to be used for the check;
-the default is "C".
-Example:
-.ES
-sconf.CheckType('foo_type', '#include "my_types.h"', 'C++')
-.EE
-
-.TP
-.RI Configure.CheckCC( self )
-Checks whether the C compiler (as defined by the CC construction variable) works
-by trying to compile a small source file.
-
-By default, SCons only detects if there is a program with the correct name, not
-if it is a functioning compiler.
-
-This uses the exact same command than the one used by the object builder for C
-source file, so it can be used to detect if a particular compiler flag works or
-not.
-
-.TP
-.RI Configure.CheckCXX( self )
-Checks whether the C++ compiler (as defined by the CXX construction variable)
-works by trying to compile a small source file. By default, SCons only detects
-if there is a program with the correct name, not if it is a functioning compiler.
-
-This uses the exact same command than the one used by the object builder for
-CXX source files, so it can be used to detect if a particular compiler flag
-works or not.
-
-.TP
-.RI Configure.CheckSHCC( self )
-Checks whether the C compiler (as defined by the SHCC construction variable) works
-by trying to compile a small source file. By default, SCons only detects if
-there is a program with the correct name, not if it is a functioning compiler.
-
-This uses the exact same command than the one used by the object builder for C
-source file, so it can be used to detect if a particular compiler flag works or
-not. This does not check whether the object code can be used to build a shared
-library, only that the compilation (not link) succeeds.
-
-.TP
-.RI Configure.CheckSHCXX( self )
-Checks whether the C++ compiler (as defined by the SHCXX construction variable)
-works by trying to compile a small source file. By default, SCons only detects
-if there is a program with the correct name, not if it is a functioning compiler.
-
-This uses the exact same command than the one used by the object builder for
-CXX source files, so it can be used to detect if a particular compiler flag
-works or not. This does not check whether the object code can be used to build
-a shared library, only that the compilation (not link) succeeds.
-
-.EE
-Example of a typical Configure usage:
-
-.ES
-env = Environment()
-conf = Configure( env )
-if not conf.CheckCHeader( 'math.h' ):
- print 'We really need math.h!'
- Exit(1)
-if conf.CheckLibWithHeader( 'qt', 'qapp.h', 'c++',
- 'QApplication qapp(0,0);' ):
- # do stuff for qt - usage, e.g.
- conf.env.Append( CPPFLAGS = '-DWITH_QT' )
-env = conf.Finish()
-.EE
-
-.TP
-.RI SConf.CheckTypeSize( context ", " type_name ", [" header ", " language ", " expect ])
-.TP
-.IR sconf .CheckTypeSize( type_name ", [" header ", " language ", " expect ])
-Checks for the size of a type defined by
-.BR typedef .
-.I type_name
-specifies the typedef name to check for.
-The optional
-.I header
-argument is a string
-that will be
-placed at the top
-of the test file
-that will be compiled
-to check if the function exists;
-the default is empty.
-The optional
-.I language
-argument should be
-.B C
-or
-.B C++
-and selects the compiler to be used for the check;
-the default is "C".
-The optional
-.I expect
-argument should be an integer.
-If this argument is used,
-the function will only check whether the type
-given in type_name has the expected size (in bytes).
-For example,
-.B "CheckTypeSize('short', expect = 2)"
-will return success only if short is two bytes.
-
-.ES
-.EE
-
-.TP
-.RI SConf.CheckDeclaration( context ", " symbol ", [" includes ", " language ])
-.TP
-.IR sconf .CheckDeclaration( symbol ", [" includes ", " language ])
-Checks if the specified
-.I symbol
-is declared.
-.I includes
-is a string containing one or more
-.B #include
-lines that will be inserted into the program
-that will be run to test for the existence of the type.
-The optional
-.I language
-argument should be
-.B C
-or
-.B C++
-and selects the compiler to be used for the check;
-the default is "C".
-
-.TP
-.RI SConf.Define( context ", " symbol ", [" value ", " comment ])
-.TP
-.IR sconf .Define( symbol ", [" value ", " comment ])
-This function does not check for anything, but defines a
-preprocessor symbol that will be added to the configuration header file.
-It is the equivalent of AC_DEFINE,
-and defines the symbol
-.I name
-with the optional
-.B value
-and the optional comment
-.BR comment .
-
-.IP
-Examples:
-
-.ES
-env = Environment()
-conf = Configure( env )
-
-# Puts the following line in the config header file:
-# #define A_SYMBOL
-conf.Define('A_SYMBOL')
-
-# Puts the following line in the config header file:
-# #define A_SYMBOL 1
-conf.Define('A_SYMBOL', 1)
-.EE
-
-.IP
-Be careful about quoting string values, though:
-
-.ES
-env = Environment()
-conf = Configure( env )
-
-# Puts the following line in the config header file:
-# #define A_SYMBOL YA
-conf.Define('A_SYMBOL', "YA")
-
-# Puts the following line in the config header file:
-# #define A_SYMBOL "YA"
-conf.Define('A_SYMBOL', '"YA"')
-.EE
-
-.IP
-For comment:
-
-.ES
-env = Environment()
-conf = Configure( env )
-
-# Puts the following lines in the config header file:
-# /* Set to 1 if you have a symbol */
-# #define A_SYMBOL 1
-conf.Define('A_SYMBOL', 1, 'Set to 1 if you have a symbol')
-.EE
-
-.EE
-You can define your own custom checks.
-in addition to the predefined checks.
-These are passed in a dictionary to the Configure function.
-This dictionary maps the names of the checks
-to user defined Python callables
-(either Python functions or class instances implementing the
-.I __call__
-method).
-The first argument of the call is always a
-.I CheckContext
-instance followed by the arguments,
-which must be supplied by the user of the check.
-These CheckContext instances define the following methods:
-
-.TP
-.RI CheckContext.Message( self ", " text )
-
-Usually called before the check is started.
-.I text
-will be displayed to the user, e.g. 'Checking for library X...'
-
-.TP
-.RI CheckContext.Result( self, ", " res )
-
-Usually called after the check is done.
-.I res
-can be either an integer or a string. In the former case, 'yes' (res != 0)
-or 'no' (res == 0) is displayed to the user, in the latter case the
-given string is displayed.
-
-.TP
-.RI CheckContext.TryCompile( self ", " text ", " extension )
-Checks if a file with the specified
-.I extension
-(e.g. '.c') containing
-.I text
-can be compiled using the environment's
-.B Object
-builder. Returns 1 on success and 0 on failure.
-
-.TP
-.RI CheckContext.TryLink( self ", " text ", " extension )
-Checks, if a file with the specified
-.I extension
-(e.g. '.c') containing
-.I text
-can be compiled using the environment's
-.B Program
-builder. Returns 1 on success and 0 on failure.
-
-.TP
-.RI CheckContext.TryRun( self ", " text ", " extension )
-Checks, if a file with the specified
-.I extension
-(e.g. '.c') containing
-.I text
-can be compiled using the environment's
-.B Program
-builder. On success, the program is run. If the program
-executes successfully
-(that is, its return status is 0),
-a tuple
-.I (1, outputStr)
-is returned, where
-.I outputStr
-is the standard output of the
-program.
-If the program fails execution
-(its return status is non-zero),
-then (0, '') is returned.
-
-.TP
-.RI CheckContext.TryAction( self ", " action ", [" text ", " extension ])
-Checks if the specified
-.I action
-with an optional source file (contents
-.I text
-, extension
-.I extension
-= ''
-) can be executed.
-.I action
-may be anything which can be converted to a
-.B scons
-.RI Action.
-On success,
-.I (1, outputStr)
-is returned, where
-.I outputStr
-is the content of the target file.
-On failure
-.I (0, '')
-is returned.
-
-.TP
-.RI CheckContext.TryBuild( self ", " builder ", [" text ", " extension ])
-Low level implementation for testing specific builds;
-the methods above are based on this method.
-Given the Builder instance
-.I builder
-and the optional
-.I text
-of a source file with optional
-.IR extension ,
-this method returns 1 on success and 0 on failure. In addition,
-.I self.lastTarget
-is set to the build target node, if the build was successful.
-
-.EE
-Example for implementing and using custom tests:
-
-.ES
-def CheckQt(context, qtdir):
- context.Message( 'Checking for qt ...' )
- lastLIBS = context.env['LIBS']
- lastLIBPATH = context.env['LIBPATH']
- lastCPPPATH= context.env['CPPPATH']
- context.env.Append(LIBS = 'qt', LIBPATH = qtdir + '/lib', CPPPATH = qtdir + '/include' )
- ret = context.TryLink("""
-#include <qapp.h>
-int main(int argc, char **argv) {
- QApplication qapp(argc, argv);
- return 0;
-}
-""")
- if not ret:
- context.env.Replace(LIBS = lastLIBS, LIBPATH=lastLIBPATH, CPPPATH=lastCPPPATH)
- context.Result( ret )
- return ret
-
-env = Environment()
-conf = Configure( env, custom_tests = { 'CheckQt' : CheckQt } )
-if not conf.CheckQt('/usr/lib/qt'):
- print 'We really need qt!'
- Exit(1)
-env = conf.Finish()
-.EE
-
-.SS Command-Line Construction Variables
-
-Often when building software,
-some variables must be specified at build time.
-For example, libraries needed for the build may be in non-standard
-locations, or site-specific compiler options may need to be passed to the
-compiler.
-.B scons
-provides a
-.B Variables
-object to support overriding construction variables
-on the command line:
-.ES
-$ scons VARIABLE=foo
-.EE
-The variable values can also be specified in a text-based SConscript file.
-To create a Variables object, call the Variables() function:
-
-.TP
-.RI Variables([ files "], [" args ])
-This creates a Variables object that will read construction variables from
-the file or list of filenames specified in
-.IR files .
-If no files are specified,
-or the
-.I files
-argument is
-.BR None ,
-then no files will be read.
-The optional argument
-.I args
-is a dictionary of
-values that will override anything read from the specified files;
-it is primarily intended to be passed the
-.B ARGUMENTS
-dictionary that holds variables
-specified on the command line.
-Example:
-
-.ES
-vars = Variables('custom.py')
-vars = Variables('overrides.py', ARGUMENTS)
-vars = Variables(None, {FOO:'expansion', BAR:7})
-.EE
-
-Variables objects have the following methods:
-
-.TP
-.RI Add( key ", [" help ", " default ", " validator ", " converter ])
-This adds a customizable construction variable to the Variables object.
-.I key
-is the name of the variable.
-.I help
-is the help text for the variable.
-.I default
-is the default value of the variable;
-if the default value is
-.B None
-and there is no explicit value specified,
-the construction variable will
-.I not
-be added to the construction environment.
-.I validator
-is called to validate the value of the variable, and should take three
-arguments: key, value, and environment.
-The recommended way to handle an invalid value is
-to raise an exception (see example below).
-.I converter
-is called to convert the value before putting it in the environment, and
-should take either a value, or the value and environment, as parameters.
-The
-.I converter
-must return a value,
-which will be converted into a string
-before being validated by the
-.I validator
-(if any)
-and then added to the environment.
-
-Examples:
-
-.ES
-vars.Add('CC', 'The C compiler')
-
-def validate_color(key, val, env):
- if not val in ['red', 'blue', 'yellow']:
- raise Exception("Invalid color value '%s'" % val)
-vars.Add('COLOR', validator=valid_color)
-.EE
-
-.TP
-.RI AddVariables( list )
-A wrapper script that adds
-multiple customizable construction variables
-to a Variables object.
-.I list
-is a list of tuple or list objects
-that contain the arguments
-for an individual call to the
-.B Add
-method.
-
-.ES
-opt.AddVariables(
- ('debug', '', 0),
- ('CC', 'The C compiler'),
- ('VALIDATE', 'An option for testing validation',
- 'notset', validator, None),
- )
-.EE
-
-.TP
-.RI Update( env ", [" args ])
-This updates a construction environment
-.I env
-with the customized construction variables.
-Any specified variables that are
-.I not
-configured for the Variables object
-will be saved and may be
-retrieved with the
-.BR UnknownVariables ()
-method, below.
-
-Normally this method is not called directly,
-but is called indirectly by passing the Variables object to
-the Environment() function:
-
-.ES
-env = Environment(variables=vars)
-.EE
-
-.IP
-The text file(s) that were specified
-when the Variables object was created
-are executed as Python scripts,
-and the values of (global) Python variables set in the file
-are added to the construction environment.
-
-Example:
-
-.ES
-CC = 'my_cc'
-.EE
-
-.TP
-.RI UnknownVariables( )
-Returns a dictionary containing any
-variables that were specified
-either in the files or the dictionary
-with which the Variables object was initialized,
-but for which the Variables object was
-not configured.
-
-.ES
-env = Environment(variables=vars)
-for key, value in vars.UnknownVariables():
- print "unknown variable: %s=%s" % (key, value)
-.EE
-
-.TP
-.RI Save( filename ", " env )
-This saves the currently set variables into a script file named
-.I filename
-that can be used on the next invocation to automatically load the current
-settings. This method combined with the Variables method can be used to
-support caching of variables between runs.
-
-.ES
-env = Environment()
-vars = Variables(['variables.cache', 'custom.py'])
-vars.Add(...)
-vars.Update(env)
-vars.Save('variables.cache', env)
-.EE
-
-.TP
-.RI GenerateHelpText( env ", [" sort ])
-This generates help text documenting the customizable construction
-variables suitable to passing in to the Help() function.
-.I env
-is the construction environment that will be used to get the actual values
-of customizable variables. Calling with
-an optional
-.I sort
-function
-will cause the output to be sorted
-by the specified argument.
-The specific
-.I sort
-function
-should take two arguments
-and return
--1, 0 or 1
-(like the standard Python
-.I cmp
-function).
-
-.ES
-Help(vars.GenerateHelpText(env))
-Help(vars.GenerateHelpText(env, sort=cmp))
-.EE
-
-.TP
-.RI FormatVariableHelpText( env ", " opt ", " help ", " default ", " actual )
-This method returns a formatted string
-containing the printable help text
-for one option.
-It is normally not called directly,
-but is called by the
-.IR GenerateHelpText ()
-method to create the returned help text.
-It may be overridden with your own
-function that takes the arguments specified above
-and returns a string of help text formatted to your liking.
-Note that the
-.IR GenerateHelpText ()
-will not put any blank lines or extra
-characters in between the entries,
-so you must add those characters to the returned
-string if you want the entries separated.
-
-.ES
-def my_format(env, opt, help, default, actual):
- fmt = "\n%s: default=%s actual=%s (%s)\n"
- return fmt % (opt, default. actual, help)
-vars.FormatVariableHelpText = my_format
-.EE
-
-To make it more convenient to work with customizable Variables,
-.B scons
-provides a number of functions
-that make it easy to set up
-various types of Variables:
-
-.TP
-.RI BoolVariable( key ", " help ", " default )
-Return a tuple of arguments
-to set up a Boolean option.
-The option will use
-the specified name
-.IR key ,
-have a default value of
-.IR default ,
-and display the specified
-.I help
-text.
-The option will interpret the values
-.BR y ,
-.BR yes ,
-.BR t ,
-.BR true ,
-.BR 1 ,
-.B on
-and
-.B all
-as true,
-and the values
-.BR n ,
-.BR no ,
-.BR f ,
-.BR false ,
-.BR 0 ,
-.B off
-and
-.B none
-as false.
-
-.TP
-.RI EnumVariable( key ", " help ", " default ", " allowed_values ", [" map ", " ignorecase ])
-Return a tuple of arguments
-to set up an option
-whose value may be one
-of a specified list of legal enumerated values.
-The option will use
-the specified name
-.IR key ,
-have a default value of
-.IR default ,
-and display the specified
-.I help
-text.
-The option will only support those
-values in the
-.I allowed_values
-list.
-The optional
-.I map
-argument is a dictionary
-that can be used to convert
-input values into specific legal values
-in the
-.I allowed_values
-list.
-If the value of
-.I ignore_case
-is
-.B 0
-(the default),
-then the values are case-sensitive.
-If the value of
-.I ignore_case
-is
-.BR 1 ,
-then values will be matched
-case-insensitive.
-If the value of
-.I ignore_case
-is
-.BR 1 ,
-then values will be matched
-case-insensitive,
-and all input values will be
-converted to lower case.
-
-.TP
-.RI ListVariable( key ", " help ", " default ", " names ", [", map ])
-Return a tuple of arguments
-to set up an option
-whose value may be one or more
-of a specified list of legal enumerated values.
-The option will use
-the specified name
-.IR key ,
-have a default value of
-.IR default ,
-and display the specified
-.I help
-text.
-The option will only support the values
-.BR all ,
-.BR none ,
-or the values in the
-.I names
-list.
-More than one value may be specified,
-with all values separated by commas.
-The default may be a string of
-comma-separated default values,
-or a list of the default values.
-The optional
-.I map
-argument is a dictionary
-that can be used to convert
-input values into specific legal values
-in the
-.I names
-list.
-
-.TP
-.RI PackageVariable( key ", " help ", " default )
-Return a tuple of arguments
-to set up an option
-whose value is a path name
-of a package that may be
-enabled, disabled or
-given an explicit path name.
-The option will use
-the specified name
-.IR key ,
-have a default value of
-.IR default ,
-and display the specified
-.I help
-text.
-The option will support the values
-.BR yes ,
-.BR true ,
-.BR on ,
-.BR enable
-or
-.BR search ,
-in which case the specified
-.I default
-will be used,
-or the option may be set to an
-arbitrary string
-(typically the path name to a package
-that is being enabled).
-The option will also support the values
-.BR no ,
-.BR false ,
-.BR off
-or
-.BR disable
-to disable use of the specified option.
-
-.TP
-.RI PathVariable( key ", " help ", " default ", [" validator ])
-Return a tuple of arguments
-to set up an option
-whose value is expected to be a path name.
-The option will use
-the specified name
-.IR key ,
-have a default value of
-.IR default ,
-and display the specified
-.I help
-text.
-An additional
-.I validator
-may be specified
-that will be called to
-verify that the specified path
-is acceptable.
-SCons supplies the
-following ready-made validators:
-.BR PathVariable.PathExists
-(the default),
-which verifies that the specified path exists;
-.BR PathVariable.PathIsFile ,
-which verifies that the specified path is an existing file;
-.BR PathVariable.PathIsDir ,
-which verifies that the specified path is an existing directory;
-.BR PathVariable.PathIsDirCreate ,
-which verifies that the specified path is a directory
-and will create the specified directory if the path does not exist;
-and
-.BR PathVariable.PathAccept ,
-which simply accepts the specific path name argument without validation,
-and which is suitable if you want your users
-to be able to specify a directory path that will be
-created as part of the build process, for example.
-You may supply your own
-.I validator
-function,
-which must take three arguments
-.RI ( key ,
-the name of the variable to be set;
-.IR val ,
-the specified value being checked;
-and
-.IR env ,
-the construction environment)
-and should raise an exception
-if the specified value is not acceptable.
-
-.RE
-These functions make it
-convenient to create a number
-of variables with consistent behavior
-in a single call to the
-.B AddVariables
-method:
-
-.ES
-vars.AddVariables(
- BoolVariable('warnings', 'compilation with -Wall and similiar', 1),
- EnumVariable('debug', 'debug output and symbols', 'no'
- allowed_values=('yes', 'no', 'full'),
- map={}, ignorecase=0), # case sensitive
- ListVariable('shared',
- 'libraries to build as shared libraries',
- 'all',
- names = list_of_libs),
- PackageVariable('x11',
- 'use X11 installed here (yes = search some places)',
- 'yes'),
- PathVariable('qtdir', 'where the root of Qt is installed', qtdir),
- PathVariable('foopath', 'where the foo library is installed', foopath,
- PathVariable.PathIsDir),
-
-)
-.EE
-
-.SS File and Directory Nodes
-
-The
-.IR File ()
-and
-.IR Dir ()
-functions return
-.I File
-and
-.I Dir
-Nodes, respectively.
-python objects, respectively.
-Those objects have several user-visible attributes
-and methods that are often useful:
-
-.IP path
-The build path
-of the given
-file or directory.
-This path is relative to the top-level directory
-(where the
-.B SConstruct
-file is found).
-The build path is the same as the source path if
-.I variant_dir
-is not being used.
-
-.IP abspath
-The absolute build path of the given file or directory.
-
-.IP srcnode()
-The
-.IR srcnode ()
-method
-returns another
-.I File
-or
-.I Dir
-object representing the
-.I source
-path of the given
-.I File
-or
-.IR Dir .
-The
-
-.ES
-# Get the current build dir's path, relative to top.
-Dir('.').path
-# Current dir's absolute path
-Dir('.').abspath
-# Next line is always '.', because it is the top dir's path relative to itself.
-Dir('#.').path
-File('foo.c').srcnode().path # source path of the given source file.
-
-# Builders also return File objects:
-foo = env.Program('foo.c')
-print "foo will be built in %s"%foo.path
-.EE
-
-A
-.I Dir
-Node or
-.I File
-Node can also be used to create
-file and subdirectory Nodes relative to the generating Node.
-A
-.I Dir
-Node will place the new Nodes within the directory it represents.
-A
-.I File
-node will place the new Nodes within its parent directory
-(that is, "beside" the file in question).
-If
-.I d
-is a
-.I Dir
-(directory) Node and
-.I f
-is a
-.I File
-(file) Node,
-then these methods are available:
-
-.TP
-.IR d .Dir( name )
-Returns a directory Node for a subdirectory of
-.I d
-named
-.IR name .
-
-.TP
-.IR d .File( name )
-Returns a file Node for a file within
-.I d
-named
-.IR name .
-
-.TP
-.IR d .Entry( name )
-Returns an unresolved Node within
-.I d
-named
-.IR name .
-
-.TP
-.IR f .Dir( name )
-Returns a directory named
-.I name
-within the parent directory of
-.IR f .
-
-.TP
-.IR f .File( name )
-Returns a file named
-.I name
-within the parent directory of
-.IR f .
-
-.TP
-.IR f .Entry( name )
-Returns an unresolved Node named
-.I name
-within the parent directory of
-.IR f .
-
-.RE
-For example:
-
-.ES
-# Get a Node for a file within a directory
-incl = Dir('include')
-f = incl.File('header.h')
-
-# Get a Node for a subdirectory within a directory
-dist = Dir('project-3.2.1)
-src = dist.Dir('src')
-
-# Get a Node for a file in the same directory
-cfile = File('sample.c')
-hfile = cfile.File('sample.h')
-
-# Combined example
-docs = Dir('docs')
-html = docs.Dir('html')
-index = html.File('index.html')
-css = index.File('app.css')
-.EE
-
-.SH EXTENDING SCONS
-.SS Builder Objects
-.B scons
-can be extended to build different types of targets
-by adding new Builder objects
-to a construction environment.
-.IR "In general" ,
-you should only need to add a new Builder object
-when you want to build a new type of file or other external target.
-If you just want to invoke a different compiler or other tool
-to build a Program, Object, Library, or any other
-type of output file for which
-.B scons
-already has an existing Builder,
-it is generally much easier to
-use those existing Builders
-in a construction environment
-that sets the appropriate construction variables
-(CC, LINK, etc.).
-
-Builder objects are created
-using the
-.B Builder
-function.
-The
-.B Builder
-function accepts the following arguments:
-
-.IP action
-The command line string used to build the target from the source.
-.B action
-can also be:
-a list of strings representing the command
-to be executed and its arguments
-(suitable for enclosing white space in an argument),
-a dictionary
-mapping source file name suffixes to
-any combination of command line strings
-(if the builder should accept multiple source file extensions),
-a Python function;
-an Action object
-(see the next section);
-or a list of any of the above.
-
-An action function
-takes three arguments:
-.I source
-- a list of source nodes,
-.I target
-- a list of target nodes,
-.I env
-- the construction environment.
-
-.IP prefix
-The prefix that will be prepended to the target file name.
-This may be specified as a:
-
-.RS 10
-.HP 6
-*
-.IR string ,
-
-.HP 6
-*
-.I callable object
-- a function or other callable that takes
-two arguments (a construction environment and a list of sources)
-and returns a prefix,
-
-.HP 6
-*
-.I dictionary
-- specifies a mapping from a specific source suffix (of the first
-source specified) to a corresponding target prefix. Both the source
-suffix and target prefix specifications may use environment variable
-substitution, and the target prefix (the 'value' entries in the
-dictionary) may also be a callable object. The default target prefix
-may be indicated by a dictionary entry with a key value of None.
-.RE
-.P
-
-.ES
-b = Builder("build_it < $SOURCE > $TARGET",
- prefix = "file-")
-
-def gen_prefix(env, sources):
- return "file-" + env['PLATFORM'] + '-'
-b = Builder("build_it < $SOURCE > $TARGET",
- prefix = gen_prefix)
-
-b = Builder("build_it < $SOURCE > $TARGET",
- suffix = { None: "file-",
- "$SRC_SFX_A": gen_prefix })
-.EE
-
-.IP suffix
-The suffix that will be appended to the target file name.
-This may be specified in the same manner as the prefix above.
-If the suffix is a string, then
-.B scons
-will append a '.' to the beginning of the suffix if it's not already
-there. The string returned by callable object (or obtained from the
-dictionary) is untouched and must append its own '.' to the beginning
-if one is desired.
-
-.ES
-b = Builder("build_it < $SOURCE > $TARGET"
- suffix = "-file")
-
-def gen_suffix(env, sources):
- return "." + env['PLATFORM'] + "-file"
-b = Builder("build_it < $SOURCE > $TARGET",
- suffix = gen_suffix)
-
-b = Builder("build_it < $SOURCE > $TARGET",
- suffix = { None: ".sfx1",
- "$SRC_SFX_A": gen_suffix })
-.EE
-
-.IP ensure_suffix
-When set to any true value, causes
-.B scons
-to add the target suffix specified by the
-.I suffix
-keyword to any target strings
-that have a different suffix.
-(The default behavior is to leave untouched
-any target file name that looks like it already has any suffix.)
-
-.ES
-b1 = Builder("build_it < $SOURCE > $TARGET"
- suffix = ".out")
-b2 = Builder("build_it < $SOURCE > $TARGET"
- suffix = ".out",
- ensure_suffix)
-env = Environment()
-env['BUILDERS']['B1'] = b1
-env['BUILDERS']['B2'] = b2
-
-# Builds "foo.txt" because ensure_suffix is not set.
-env.B1('foo.txt', 'foo.in')
-
-# Builds "bar.txt.out" because ensure_suffix is set.
-env.B2('bar.txt', 'bar.in')
-.EE
-
-.IP src_suffix
-The expected source file name suffix. This may be a string or a list
-of strings.
-
-.IP target_scanner
-A Scanner object that
-will be invoked to find
-implicit dependencies for this target file.
-This keyword argument should be used
-for Scanner objects that find
-implicit dependencies
-based only on the target file
-and the construction environment,
-.I not
-for implicit dependencies based on source files.
-(See the section "Scanner Objects" below,
-for information about creating Scanner objects.)
-
-.IP source_scanner
-A Scanner object that
-will be invoked to
-find implicit dependencies in
-any source files
-used to build this target file.
-This is where you would
-specify a scanner to
-find things like
-.B #include
-lines in source files.
-The pre-built
-.B DirScanner
-Scanner object may be used to
-indicate that this Builder
-should scan directory trees
-for on-disk changes to files
-that
-.B scons
-does not know about from other Builder or function calls.
-(See the section "Scanner Objects" below,
-for information about creating your own Scanner objects.)
-
-.IP target_factory
-A factory function that the Builder will use
-to turn any targets specified as strings into SCons Nodes.
-By default,
-SCons assumes that all targets are files.
-Other useful target_factory
-values include
-.BR Dir ,
-for when a Builder creates a directory target,
-and
-.BR Entry ,
-for when a Builder can create either a file
-or directory target.
-
-Example:
-
-.ES
-MakeDirectoryBuilder = Builder(action=my_mkdir, target_factory=Dir)
-env = Environment()
-env.Append(BUILDERS = {'MakeDirectory':MakeDirectoryBuilder})
-env.MakeDirectory('new_directory', [])
-.EE
-
-.IP
-Note that the call to the MakeDirectory Builder
-needs to specify an empty source list
-to make the string represent the builder's target;
-without that, it would assume the argument is the source,
-and would try to deduce the target name from it,
-which in the absence of an automatically-added prefix or suffix
-would lead to a matching target and source name
-and a circular dependency.
-
-.IP source_factory
-A factory function that the Builder will use
-to turn any sources specified as strings into SCons Nodes.
-By default,
-SCons assumes that all source are files.
-Other useful source_factory
-values include
-.BR Dir ,
-for when a Builder uses a directory as a source,
-and
-.BR Entry ,
-for when a Builder can use files
-or directories (or both) as sources.
-
-Example:
-
-.ES
-CollectBuilder = Builder(action=my_mkdir, source_factory=Entry)
-env = Environment()
-env.Append(BUILDERS = {'Collect':CollectBuilder})
-env.Collect('archive', ['directory_name', 'file_name'])
-.EE
-
-.IP emitter
-A function or list of functions to manipulate the target and source
-lists before dependencies are established
-and the target(s) are actually built.
-.B emitter
-can also be a string containing a construction variable to expand
-to an emitter function or list of functions,
-or a dictionary mapping source file suffixes
-to emitter functions.
-(Only the suffix of the first source file
-is used to select the actual emitter function
-from an emitter dictionary.)
-
-An emitter function
-takes three arguments:
-.I source
-- a list of source nodes,
-.I target
-- a list of target nodes,
-.I env
-- the construction environment.
-An emitter must return a tuple containing two lists,
-the list of targets to be built by this builder,
-and the list of sources for this builder.
-
-Example:
-
-.ES
-def e(target, source, env):
- return (target + ['foo.foo'], source + ['foo.src'])
-
-# Simple association of an emitter function with a Builder.
-b = Builder("my_build < $TARGET > $SOURCE",
- emitter = e)
-
-def e2(target, source, env):
- return (target + ['bar.foo'], source + ['bar.src'])
-
-# Simple association of a list of emitter functions with a Builder.
-b = Builder("my_build < $TARGET > $SOURCE",
- emitter = [e, e2])
-
-# Calling an emitter function through a construction variable.
-env = Environment(MY_EMITTER = e)
-b = Builder("my_build < $TARGET > $SOURCE",
- emitter = '$MY_EMITTER')
-
-# Calling a list of emitter functions through a construction variable.
-env = Environment(EMITTER_LIST = [e, e2])
-b = Builder("my_build < $TARGET > $SOURCE",
- emitter = '$EMITTER_LIST')
-
-# Associating multiple emitters with different file
-# suffixes using a dictionary.
-def e_suf1(target, source, env):
- return (target + ['another_target_file'], source)
-def e_suf2(target, source, env):
- return (target, source + ['another_source_file'])
-b = Builder("my_build < $TARGET > $SOURCE",
- emitter = {'.suf1' : e_suf1,
- '.suf2' : e_suf2})
-.EE
-
-.IP multi
-Specifies whether this builder is allowed to be called multiple times for
-the same target file(s). The default is 0, which means the builder
-can not be called multiple times for the same target file(s). Calling a
-builder multiple times for the same target simply adds additional source
-files to the target; it is not allowed to change the environment associated
-with the target, specify addition environment overrides, or associate a different
-builder with the target.
-
-.IP env
-A construction environment that can be used
-to fetch source code using this Builder.
-(Note that this environment is
-.I not
-used for normal builds of normal target files,
-which use the environment that was
-used to call the Builder for the target file.)
-
-.IP generator
-A function that returns a list of actions that will be executed to build
-the target(s) from the source(s).
-The returned action(s) may be
-an Action object, or anything that
-can be converted into an Action object
-(see the next section).
-
-The generator function
-takes four arguments:
-.I source
-- a list of source nodes,
-.I target
-- a list of target nodes,
-.I env
-- the construction environment,
-.I for_signature
-- a Boolean value that specifies
-whether the generator is being called
-for generating a build signature
-(as opposed to actually executing the command).
-Example:
-
-.ES
-def g(source, target, env, for_signature):
- return [["gcc", "-c", "-o"] + target + source]
-
-b = Builder(generator=g)
-.EE
-
-.IP
-The
-.I generator
-and
-.I action
-arguments must not both be used for the same Builder.
-
-.IP src_builder
-Specifies a builder to use when a source file name suffix does not match
-any of the suffixes of the builder. Using this argument produces a
-multi-stage builder.
-
-.IP single_source
-Specifies that this builder expects exactly one source file per call. Giving
-more than one source file without target files results in implicitely calling
-the builder multiple times (once for each source given). Giving multiple
-source files together with target files results in a UserError exception.
-
-.RE
-.IP
-The
-.I generator
-and
-.I action
-arguments must not both be used for the same Builder.
-
-.IP source_ext_match
-When the specified
-.I action
-argument is a dictionary,
-the default behavior when a builder is passed
-multiple source files is to make sure that the
-extensions of all the source files match.
-If it is legal for this builder to be
-called with a list of source files with different extensions,
-this check can be suppressed by setting
-.B source_ext_match
-to
-.B None
-or some other non-true value.
-When
-.B source_ext_match
-is disable,
-.B scons
-will use the suffix of the first specified
-source file to select the appropriate action from the
-.I action
-dictionary.
-
-In the following example,
-the setting of
-.B source_ext_match
-prevents
-.B scons
-from exiting with an error
-due to the mismatched suffixes of
-.B foo.in
-and
-.BR foo.extra .
-
-.ES
-b = Builder(action={'.in' : 'build $SOURCES > $TARGET'},
- source_ext_match = None)
-
-env = Environment(BUILDERS = {'MyBuild':b})
-env.MyBuild('foo.out', ['foo.in', 'foo.extra'])
-.EE
-
-.IP env
-A construction environment that can be used
-to fetch source code using this Builder.
-(Note that this environment is
-.I not
-used for normal builds of normal target files,
-which use the environment that was
-used to call the Builder for the target file.)
-
-.ES
-b = Builder(action="build < $SOURCE > $TARGET")
-env = Environment(BUILDERS = {'MyBuild' : b})
-env.MyBuild('foo.out', 'foo.in', my_arg = 'xyzzy')
-.EE
-
-.IP chdir
-A directory from which scons
-will execute the
-action(s) specified
-for this Builder.
-If the
-.B chdir
-argument is
-a string or a directory Node,
-scons will change to the specified directory.
-If the
-.B chdir
-is not a string or Node
-and is non-zero,
-then scons will change to the
-target file's directory.
-
-Note that scons will
-.I not
-automatically modify
-its expansion of
-construction variables like
-.B $TARGET
-and
-.B $SOURCE
-when using the chdir
-keyword argument--that is,
-the expanded file names
-will still be relative to
-the top-level SConstruct directory,
-and consequently incorrect
-relative to the chdir directory.
-Builders created using chdir keyword argument,
-will need to use construction variable
-expansions like
-.B ${TARGET.file}
-and
-.B ${SOURCE.file}
-to use just the filename portion of the
-targets and source.
-
-.ES
-b = Builder(action="build < ${SOURCE.file} > ${TARGET.file}",
- chdir=1)
-env = Environment(BUILDERS = {'MyBuild' : b})
-env.MyBuild('sub/dir/foo.out', 'sub/dir/foo.in')
-.EE
-
-.B WARNING:
-Python only keeps one current directory
-location for all of the threads.
-This means that use of the
-.B chdir
-argument
-will
-.I not
-work with the SCons
-.B -j
-option,
-because individual worker threads spawned
-by SCons interfere with each other
-when they start changing directory.
-
-.RE
-Any additional keyword arguments supplied
-when a Builder object is created
-(that is, when the Builder() function is called)
-will be set in the executing construction
-environment when the Builder object is called.
-The canonical example here would be
-to set a construction variable to
-the repository of a source code system.
-
-Any additional keyword arguments supplied
-when a Builder
-.I object
-is called
-will only be associated with the target
-created by that particular Builder call
-(and any other files built as a
-result of the call).
-
-These extra keyword arguments are passed to the
-following functions:
-command generator functions,
-function Actions,
-and emitter functions.
-
-.SS Action Objects
-
-The
-.BR Builder ()
-function will turn its
-.B action
-keyword argument into an appropriate
-internal Action object.
-You can also explicity create Action objects
-using the
-.BR Action ()
-global function,
-which can then be passed to the
-.BR Builder ()
-function.
-This can be used to configure
-an Action object more flexibly,
-or it may simply be more efficient
-than letting each separate Builder object
-create a separate Action
-when multiple
-Builder objects need to do the same thing.
-
-The
-.BR Action ()
-global function
-returns an appropriate object for the action
-represented by the type of the first argument:
-
-.IP Action
-If the first argument is already an Action object,
-the object is simply returned.
-
-.IP String
-If the first argument is a string,
-a command-line Action is returned.
-Note that the command-line string
-may be preceded by an
-.B @
-(at-sign)
-to suppress printing of the specified command line,
-or by a
-.B \-
-(hyphen)
-to ignore the exit status from the specified command:
-
-.ES
-Action('$CC -c -o $TARGET $SOURCES')
-
-# Doesn't print the line being executed.
-Action('@build $TARGET $SOURCES')
-
-# Ignores return value
-Action('-build $TARGET $SOURCES')
-.EE
-.\" XXX From Gary Ruben, 23 April 2002:
-.\" What would be useful is a discussion of how you execute command
-.\" shell commands ie. what is the process used to spawn the shell, pass
-.\" environment variables to it etc., whether there is one shell per
-.\" environment or one per command etc. It might help to look at the Gnu
-.\" make documentation to see what they think is important to discuss about
-.\" a build system. I'm sure you can do a better job of organising the
-.\" documentation than they have :-)
-
-.IP List
-If the first argument is a list,
-then a list of Action objects is returned.
-An Action object is created as necessary
-for each element in the list.
-If an element
-.I within
-the list is itself a list,
-the internal list is the
-command and arguments to be executed via
-the command line.
-This allows white space to be enclosed
-in an argument by defining
-a command in a list within a list:
-
-.ES
-Action([['cc', '-c', '-DWHITE SPACE', '-o', '$TARGET', '$SOURCES']])
-.EE
-
-.IP Function
-If the first argument is a Python function,
-a function Action is returned.
-The Python function must take three keyword arguments,
-.B target
-(a Node object representing the target file),
-.B source
-(a Node object representing the source file)
-and
-.B env
-(the construction environment
-used for building the target file).
-The
-.B target
-and
-.B source
-arguments may be lists of Node objects if there is
-more than one target file or source file.
-The actual target and source file name(s) may
-be retrieved from their Node objects
-via the built-in Python str() function:
-
-.ES
-target_file_name = str(target)
-source_file_names = map(lambda x: str(x), source)
-.EE
-.IP
-The function should return
-.B 0
-or
-.B None
-to indicate a successful build of the target file(s).
-The function may raise an exception
-or return a non-zero exit status
-to indicate an unsuccessful build.
-
-.ES
-def build_it(target = None, source = None, env = None):
- # build the target from the source
- return 0
-
-a = Action(build_it)
-.EE
-
-If the action argument is not one of the above,
-None is returned.
-.PP
-
-The second argument is optional and is used to define the output
-which is printed when the Action is actually performed.
-In the absence of this parameter,
-or if it's an empty string,
-a default output depending on the type of the action is used.
-For example, a command-line action will print the executed command.
-The argument must be either a Python function or a string.
-
-In the first case,
-it's a function that returns a string to be printed
-to describe the action being executed.
-The function may also be specified by the
-.IR strfunction =
-keyword argument.
-Like a function to build a file,
-this function must take three keyword arguments:
-.B target
-(a Node object representing the target file),
-.B source
-(a Node object representing the source file)
-and
-.BR env
-(a construction environment).
-The
-.B target
-and
-.B source
-arguments may be lists of Node objects if there is
-more than one target file or source file.
-
-In the second case, you provide the string itself.
-The string may also be specified by the
-.IR cmdstr =
-keyword argument.
-The string typically contains variables, notably
-$TARGET(S) and $SOURCE(S), or consists of just a single
-variable, which is optionally defined somewhere else.
-SCons itself heavily uses the latter variant.
-
-Examples:
-
-.ES
-def build_it(target, source, env):
- # build the target from the source
- return 0
-
-def string_it(target, source, env):
- return "building '%s' from '%s'" % (target[0], source[0])
-
-# Use a positional argument.
-f = Action(build_it, string_it)
-s = Action(build_it, "building '$TARGET' from '$SOURCE'")
-
-# Alternatively, use a keyword argument.
-f = Action(build_it, strfunction=string_it)
-s = Action(build_it, cmdstr="building '$TARGET' from '$SOURCE'")
-
-# You can provide a configurable variable.
-l = Action(build_it, '$STRINGIT')
-.EE
-
-The third and succeeding arguments, if present,
-may either be a construction variable or a list of construction variables
-whose values will be included in the signature of the Action
-when deciding whether a target should be rebuilt because the action changed.
-The variables may also be specified by a
-.IR varlist =
-keyword parameter;
-if both are present, they are combined.
-This is necessary whenever you want a target to be rebuilt
-when a specific construction variable changes.
-This is not often needed for a string action,
-as the expanded variables will normally be part of the command line,
-but may be needed if a Python function action uses
-the value of a construction variable when generating the command line.
-
-.ES
-def build_it(target, source, env):
- # build the target from the 'XXX' construction variable
- open(target[0], 'w').write(env['XXX'])
- return 0
-
-# Use positional arguments.
-a = Action(build_it, '$STRINGIT', ['XXX'])
-
-# Alternatively, use a keyword argument.
-a = Action(build_it, varlist=['XXX'])
-.EE
-
-The
-.BR Action ()
-global function
-can be passed the following
-optional keyword arguments
-to modify the Action object's behavior:
-
-.IP
-.B chdir
-The
-.B chdir
-keyword argument specifies that
-scons will execute the action
-after changing to the specified directory.
-If the
-.B chdir
-argument is
-a string or a directory Node,
-scons will change to the specified directory.
-If the
-.B chdir
-argument
-is not a string or Node
-and is non-zero,
-then scons will change to the
-target file's directory.
-
-Note that scons will
-.I not
-automatically modify
-its expansion of
-construction variables like
-.B $TARGET
-and
-.B $SOURCE
-when using the chdir
-keyword argument--that is,
-the expanded file names
-will still be relative to
-the top-level SConstruct directory,
-and consequently incorrect
-relative to the chdir directory.
-Builders created using chdir keyword argument,
-will need to use construction variable
-expansions like
-.B ${TARGET.file}
-and
-.B ${SOURCE.file}
-to use just the filename portion of the
-targets and source.
-
-.ES
-a = Action("build < ${SOURCE.file} > ${TARGET.file}",
- chdir=1)
-.EE
-
-.IP
-.B exitstatfunc
-The
-.BR Action ()
-global function
-also takes an
-.B exitstatfunc
-keyword argument
-which specifies a function
-that is passed the exit status
-(or return value)
-from the specified action
-and can return an arbitrary
-or modified value.
-This can be used, for example,
-to specify that an Action object's
-return value should be ignored
-under special conditions
-and SCons should, therefore,
-consider that the action always suceeds:
-
-.ES
-def always_succeed(s):
- # Always return 0, which indicates success.
- return 0
-a = Action("build < ${SOURCE.file} > ${TARGET.file}",
- exitstatfunc=always_succeed)
-.EE
-
-.IP
-.B batch_key
-The
-.B batch_key
-keyword argument can be used
-to specify that the Action can create multiple target files
-by processing multiple independent source files simultaneously.
-(The canonical example is "batch compilation"
-of multiple object files
-by passing multiple source files
-to a single invocation of a compiler
-such as Microsoft's Visual C / C++ compiler.)
-If the
-.B batch_key
-argument is any non-False, non-callable Python value,
-the configured Action object will cause
-.B scons
-to collect all targets built with the Action object
-and configured with the same construction environment
-into single invocations of the Action object's
-command line or function.
-Command lines will typically want to use the
-.BR CHANGED_SOURCES
-construction variable
-(and possibly
-.BR CHANGED_TARGETS
-as well)
-to only pass to the command line those sources that
-have actually changed since their targets were built.
-
-Example:
-
-.ES
-a = Action('build $CHANGED_SOURCES', batch_key=True)
-.EE
-
-The
-.B batch_key
-argument may also be
-a callable function
-that returns a key that
-will be used to identify different
-"batches" of target files to be collected
-for batch building.
-A
-.B batch_key
-function must take the following arguments:
-
-.IP action
-The action object.
-
-.IP env
-The construction environment
-configured for the target.
-
-.IP target
-The list of targets for a particular configured action.
-
-.IP source
-The list of source for a particular configured action.
-
-The returned key should typically
-be a tuple of values derived from the arguments,
-using any appropriate logic to decide
-how multiple invocations should be batched.
-For example, a
-.B batch_key
-function may decide to return
-the value of a specific construction
-variable from the
-.B env
-argument
-which will cause
-.B scons
-to batch-build targets
-with matching values of that variable,
-or perhaps return the
-.BR id ()
-of the entire construction environment,
-in which case
-.B scons
-will batch-build
-all targets configured with the same construction environment.
-Returning
-.B None
-indicates that
-the particular target should
-.I not
-be part of any batched build,
-but instead will be built
-by a separate invocation of action's
-command or function.
-Example:
-
-.ES
-def batch_key(action, env, target, source):
- tdir = target[0].dir
- if tdir.name == 'special':
- # Don't batch-build any target
- # in the special/ subdirectory.
- return None
- return (id(action), id(env), tdir)
-a = Action('build $CHANGED_SOURCES', batch_key=batch_key)
-.EE
-
-.SS Miscellaneous Action Functions
-
-.B scons
-supplies a number of functions
-that arrange for various common
-file and directory manipulations
-to be performed.
-These are similar in concept to "tasks" in the
-Ant build tool,
-although the implementation is slightly different.
-These functions do not actually
-perform the specified action
-at the time the function is called,
-but instead return an Action object
-that can be executed at the
-appropriate time.
-(In Object-Oriented terminology,
-these are actually
-Action
-.I Factory
-functions
-that return Action objects.)
-
-In practice,
-there are two natural ways
-that these
-Action Functions
-are intended to be used.
-
-First,
-if you need
-to perform the action
-at the time the SConscript
-file is being read,
-you can use the
-.B Execute
-global function to do so:
-.ES
-Execute(Touch('file'))
-.EE
-
-Second,
-you can use these functions
-to supply Actions in a list
-for use by the
-.B Command
-method.
-This can allow you to
-perform more complicated
-sequences of file manipulation
-without relying
-on platform-specific
-external commands:
-that
-.ES
-env = Environment(TMPBUILD = '/tmp/builddir')
-env.Command('foo.out', 'foo.in',
- [Mkdir('$TMPBUILD'),
- Copy('$TMPBUILD', '${SOURCE.dir}'),
- "cd $TMPBUILD && make",
- Delete('$TMPBUILD')])
-.EE
-
-.TP
-.RI Chmod( dest ", " mode )
-Returns an Action object that
-changes the permissions on the specified
-.I dest
-file or directory to the specified
-.IR mode .
-Examples:
-
-.ES
-Execute(Chmod('file', 0755))
-
-env.Command('foo.out', 'foo.in',
- [Copy('$TARGET', '$SOURCE'),
- Chmod('$TARGET', 0755)])
-.EE
-
-.TP
-.RI Copy( dest ", " src )
-Returns an Action object
-that will copy the
-.I src
-source file or directory to the
-.I dest
-destination file or directory.
-Examples:
-
-.ES
-Execute(Copy('foo.output', 'foo.input'))
-
-env.Command('bar.out', 'bar.in',
- Copy('$TARGET', '$SOURCE'))
-.EE
-
-.TP
-.RI Delete( entry ", [" must_exist ])
-Returns an Action that
-deletes the specified
-.IR entry ,
-which may be a file or a directory tree.
-If a directory is specified,
-the entire directory tree
-will be removed.
-If the
-.I must_exist
-flag is set,
-then a Python error will be thrown
-if the specified entry does not exist;
-the default is
-.BR must_exist=0 ,
-that is, the Action will silently do nothing
-if the entry does not exist.
-Examples:
-
-.ES
-Execute(Delete('/tmp/buildroot'))
-
-env.Command('foo.out', 'foo.in',
- [Delete('${TARGET.dir}'),
- MyBuildAction])
-
-Execute(Delete('file_that_must_exist', must_exist=1))
-.EE
-
-.TP
-.RI Mkdir( dir )
-Returns an Action
-that creates the specified
-directory
-.I dir .
-Examples:
-
-.ES
-Execute(Mkdir('/tmp/outputdir'))
-
-env.Command('foo.out', 'foo.in',
- [Mkdir('/tmp/builddir'),
- Copy('/tmp/builddir/foo.in', '$SOURCE'),
- "cd /tmp/builddir && make",
- Copy('$TARGET', '/tmp/builddir/foo.out')])
-.EE
-
-.TP
-.RI Move( dest ", " src )
-Returns an Action
-that moves the specified
-.I src
-file or directory to
-the specified
-.I dest
-file or directory.
-Examples:
-
-.ES
-Execute(Move('file.destination', 'file.source'))
-
-env.Command('output_file', 'input_file',
- [MyBuildAction,
- Move('$TARGET', 'file_created_by_MyBuildAction')])
-.EE
-
-.TP
-.RI Touch( file )
-Returns an Action
-that updates the modification time
-on the specified
-.IR file .
-Examples:
-
-.ES
-Execute(Touch('file_to_be_touched'))
-
-env.Command('marker', 'input_file',
- [MyBuildAction,
- Touch('$TARGET')])
-.EE
-
-.SS Variable Substitution
-
-Before executing a command,
-.B scons
-performs construction variable interpolation on the strings that make up
-the command line of builders.
-Variables are introduced by a
-.B $
-prefix.
-Besides construction variables, scons provides the following
-variables for each command execution:
-
-.IP CHANGED_SOURCES
-The file names of all sources of the build command
-that have changed since the target was last built.
-
-.IP CHANGED_TARGETS
-The file names of all targets that would be built
-from sources that have changed since the target was last built.
-
-.IP SOURCE
-The file name of the source of the build command,
-or the file name of the first source
-if multiple sources are being built.
-
-.IP SOURCES
-The file names of the sources of the build command.
-
-.IP TARGET
-The file name of the target being built,
-or the file name of the first target
-if multiple targets are being built.
-
-.IP TARGETS
-The file names of all targets being built.
-
-.IP UNCHANGED_SOURCES
-The file names of all sources of the build command
-that have
-.I not
-changed since the target was last built.
-
-.IP UNCHANGED_TARGETS
-The file names of all targets that would be built
-from sources that have
-.I not
-changed since the target was last built.
-
-(Note that the above variables are reserved
-and may not be set in a construction environment.)
-
-.LP
-For example, given the construction variable CC='cc', targets=['foo'], and
-sources=['foo.c', 'bar.c']:
-
-.ES
-action='$CC -c -o $TARGET $SOURCES'
-.EE
-
-would produce the command line:
-
-.ES
-cc -c -o foo foo.c bar.c
-.EE
-
-Variable names may be surrounded by curly braces ({})
-to separate the name from the trailing characters.
-Within the curly braces, a variable name may have
-a Python slice subscript appended to select one
-or more items from a list.
-In the previous example, the string:
-
-.ES
-${SOURCES[1]}
-.EE
-
-would produce:
-
-.ES
-bar.c
-.EE
-
-Additionally, a variable name may
-have the following special
-modifiers appended within the enclosing curly braces
-to modify the interpolated string:
-
-.IP base
-The base path of the file name,
-including the directory path
-but excluding any suffix.
-
-.IP dir
-The name of the directory in which the file exists.
-
-.IP file
-The file name,
-minus any directory portion.
-
-.IP filebase
-Just the basename of the file,
-minus any suffix
-and minus the directory.
-
-.IP suffix
-Just the file suffix.
-
-.IP abspath
-The absolute path name of the file.
-
-.IP posix
-The POSIX form of the path,
-with directories separated by
-.B /
-(forward slashes)
-not backslashes.
-This is sometimes necessary on Windows systems
-when a path references a file on other (POSIX) systems.
-
-.IP srcpath
-The directory and file name to the source file linked to this file through
-.BR VariantDir ().
-If this file isn't linked,
-it just returns the directory and filename unchanged.
-
-.IP srcdir
-The directory containing the source file linked to this file through
-.BR VariantDir ().
-If this file isn't linked,
-it just returns the directory part of the filename.
-
-.IP rsrcpath
-The directory and file name to the source file linked to this file through
-.BR VariantDir ().
-If the file does not exist locally but exists in a Repository,
-the path in the Repository is returned.
-If this file isn't linked, it just returns the
-directory and filename unchanged.
-
-.IP rsrcdir
-The Repository directory containing the source file linked to this file through
-.BR VariantDir ().
-If this file isn't linked,
-it just returns the directory part of the filename.
-
-.LP
-For example, the specified target will
-expand as follows for the corresponding modifiers:
-
-.ES
-$TARGET => sub/dir/file.x
-${TARGET.base} => sub/dir/file
-${TARGET.dir} => sub/dir
-${TARGET.file} => file.x
-${TARGET.filebase} => file
-${TARGET.suffix} => .x
-${TARGET.abspath} => /top/dir/sub/dir/file.x
-
-SConscript('src/SConscript', variant_dir='sub/dir')
-$SOURCE => sub/dir/file.x
-${SOURCE.srcpath} => src/file.x
-${SOURCE.srcdir} => src
-
-Repository('/usr/repository')
-$SOURCE => sub/dir/file.x
-${SOURCE.rsrcpath} => /usr/repository/src/file.x
-${SOURCE.rsrcdir} => /usr/repository/src
-.EE
-
-Note that curly braces braces may also be used
-to enclose arbitrary Python code to be evaluated.
-(In fact, this is how the above modifiers are substituted,
-they are simply attributes of the Python objects
-that represent TARGET, SOURCES, etc.)
-See the section "Python Code Substitution" below,
-for more thorough examples of
-how this can be used.
-
-Lastly, a variable name
-may be a callable Python function
-associated with a
-construction variable in the environment.
-The function should
-take four arguments:
-.I target
-- a list of target nodes,
-.I source
-- a list of source nodes,
-.I env
-- the construction environment,
-.I for_signature
-- a Boolean value that specifies
-whether the function is being called
-for generating a build signature.
-SCons will insert whatever
-the called function returns
-into the expanded string:
-
-.ES
-def foo(target, source, env, for_signature):
- return "bar"
-
-# Will expand $BAR to "bar baz"
-env=Environment(FOO=foo, BAR="$FOO baz")
-.EE
-
-You can use this feature to pass arguments to a
-Python function by creating a callable class
-that stores one or more arguments in an object,
-and then uses them when the
-.B __call__()
-method is called.
-Note that in this case,
-the entire variable expansion must
-be enclosed by curly braces
-so that the arguments will
-be associated with the
-instantiation of the class:
-
-.ES
-class foo(object):
- def __init__(self, arg):
- self.arg = arg
-
- def __call__(self, target, source, env, for_signature):
- return self.arg + " bar"
-
-# Will expand $BAR to "my argument bar baz"
-env=Environment(FOO=foo, BAR="${FOO('my argument')} baz")
-.EE
-
-.LP
-The special pseudo-variables
-.B "$("
-and
-.B "$)"
-may be used to surround parts of a command line
-that may change
-.I without
-causing a rebuild--that is,
-which are not included in the signature
-of target files built with this command.
-All text between
-.B "$("
-and
-.B "$)"
-will be removed from the command line
-before it is added to file signatures,
-and the
-.B "$("
-and
-.B "$)"
-will be removed before the command is executed.
-For example, the command line:
-
-.ES
-echo Last build occurred $( $TODAY $). > $TARGET
-.EE
-
-.LP
-would execute the command:
-
-.ES
-echo Last build occurred $TODAY. > $TARGET
-.EE
-
-.LP
-but the command signature added to any target files would be:
-
-.ES
-echo Last build occurred . > $TARGET
-.EE
-
-.SS Python Code Substitution
-
-Any python code within
-.BR "${" - "}"
-pairs gets evaluated by python 'eval', with the python globals set to
-the current environment's set of construction variables.
-So in the following case:
-.ES
-env['COND'] = 0
-env.Command('foo.out', 'foo.in',
- '''echo ${COND==1 and 'FOO' or 'BAR'} > $TARGET''')
-.EE
-the command executed will be either
-.ES
-echo FOO > foo.out
-.EE
-or
-.ES
-echo BAR > foo.out
-.EE
-according to the current value of env['COND'] when the command is
-executed. The evaluation occurs when the target is being
-built, not when the SConscript is being read. So if env['COND'] is changed
-later in the SConscript, the final value will be used.
-
-Here's a more interesting example. Note that all of COND, FOO, and
-BAR are environment variables, and their values are substituted into
-the final command. FOO is a list, so its elements are interpolated
-separated by spaces.
-
-.ES
-env=Environment()
-env['COND'] = 0
-env['FOO'] = ['foo1', 'foo2']
-env['BAR'] = 'barbar'
-env.Command('foo.out', 'foo.in',
- 'echo ${COND==1 and FOO or BAR} > $TARGET')
-
-# Will execute this:
-# echo foo1 foo2 > foo.out
-.EE
-
-SCons uses the following rules when converting construction variables into
-command lines:
-
-.IP String
-When the value is a string it is interpreted as a space delimited list of
-command line arguments.
-
-.IP List
-When the value is a list it is interpreted as a list of command line
-arguments. Each element of the list is converted to a string.
-
-.IP Other
-Anything that is not a list or string is converted to a string and
-interpreted as a single command line argument.
-
-.IP Newline
-Newline characters (\\n) delimit lines. The newline parsing is done after
-all other parsing, so it is not possible for arguments (e.g. file names) to
-contain embedded newline characters. This limitation will likely go away in
-a future version of SCons.
-
-.SS Scanner Objects
-
-You can use the
-.B Scanner
-function to define
-objects to scan
-new file types for implicit dependencies.
-The
-.B Scanner
-function accepts the following arguments:
-
-.IP function
-This can be either:
-1) a Python function that will process
-the Node (file)
-and return a list of File Nodes
-representing the implicit
-dependencies (file names) found in the contents;
-or:
-2) a dictionary that maps keys
-(typically the file suffix, but see below for more discussion)
-to other Scanners that should be called.
-
-If the argument is actually a Python function,
-the function must take three or four arguments:
-
- def scanner_function(node, env, path):
-
- def scanner_function(node, env, path, arg=None):
-
-The
-.B node
-argument is the internal
-SCons node representing the file.
-Use
-.B str(node)
-to fetch the name of the file, and
-.B node.get_contents()
-to fetch contents of the file.
-Note that the file is
-.I not
-guaranteed to exist before the scanner is called,
-so the scanner function should check that
-if there's any chance that the scanned file
-might not exist
-(for example, if it's built from other files).
-
-The
-.B env
-argument is the construction environment for the scan.
-Fetch values from it using the
-.B env.Dictionary()
-method.
-
-The
-.B path
-argument is a tuple (or list)
-of directories that can be searched
-for files.
-This will usually be the tuple returned by the
-.B path_function
-argument (see below).
-
-The
-.B arg
-argument is the argument supplied
-when the scanner was created, if any.
-
-.IP name
-The name of the Scanner.
-This is mainly used
-to identify the Scanner internally.
-
-.IP argument
-An optional argument that, if specified,
-will be passed to the scanner function
-(described above)
-and the path function
-(specified below).
-
-.IP skeys
-An optional list that can be used to
-determine which scanner should be used for
-a given Node.
-In the usual case of scanning for file names,
-this argument will be a list of suffixes
-for the different file types that this
-Scanner knows how to scan.
-If the argument is a string,
-then it will be expanded
-into a list by the current environment.
-
-.IP path_function
-A Python function that takes four or five arguments:
-a construction environment,
-a Node for the directory containing
-the SConscript file in which
-the first target was defined,
-a list of target nodes,
-a list of source nodes,
-and an optional argument supplied
-when the scanner was created.
-The
-.B path_function
-returns a tuple of directories
-that can be searched for files to be returned
-by this Scanner object.
-(Note that the
-.BR FindPathDirs ()
-function can be used to return a ready-made
-.B path_function
-for a given construction variable name,
-instead of having to write your own function from scratch.)
-
-.IP node_class
-The class of Node that should be returned
-by this Scanner object.
-Any strings or other objects returned
-by the scanner function
-that are not of this class
-will be run through the
-.B node_factory
-function.
-
-.IP node_factory
-A Python function that will take a string
-or other object
-and turn it into the appropriate class of Node
-to be returned by this Scanner object.
-
-.IP scan_check
-An optional Python function that takes two arguments,
-a Node (file) and a construction environment,
-and returns whether the
-Node should, in fact,
-be scanned for dependencies.
-This check can be used to eliminate unnecessary
-calls to the scanner function when,
-for example, the underlying file
-represented by a Node does not yet exist.
-
-.IP recursive
-An optional flag that
-specifies whether this scanner should be re-invoked
-on the dependency files returned by the scanner.
-When this flag is not set,
-the Node subsystem will
-only invoke the scanner on the file being scanned,
-and not (for example) also on the files
-specified by the #include lines
-in the file being scanned.
-.I recursive
-may be a callable function,
-in which case it will be called with a list of
-Nodes found and
-should return a list of Nodes
-that should be scanned recursively;
-this can be used to select a specific subset of
-Nodes for additional scanning.
-
-.RE
-Note that
-.B scons
-has a global
-.B SourceFileScanner
-object that is used by
-the
-.BR Object (),
-.BR SharedObject (),
-and
-.BR StaticObject ()
-builders to decide
-which scanner should be used
-for different file extensions.
-You can using the
-.BR SourceFileScanner.add_scanner ()
-method to add your own Scanner object
-to the
-.B scons
-infrastructure
-that builds target programs or
-libraries from a list of
-source files of different types:
-
-.ES
-def xyz_scan(node, env, path):
- contents = node.get_text_contents()
- # Scan the contents and return the included files.
-
-XYZScanner = Scanner(xyz_scan)
-
-SourceFileScanner.add_scanner('.xyz', XYZScanner)
-
-env.Program('my_prog', ['file1.c', 'file2.f', 'file3.xyz'])
-.EE
-
-.SH SYSTEM-SPECIFIC BEHAVIOR
-SCons and its configuration files are very portable,
-due largely to its implementation in Python.
-There are, however, a few portability
-issues waiting to trap the unwary.
-.SS .C file suffix
-SCons handles the upper-case
-.B .C
-file suffix differently,
-depending on the capabilities of
-the underlying system.
-On a case-sensitive system
-such as Linux or UNIX,
-SCons treats a file with a
-.B .C
-suffix as a C++ source file.
-On a case-insensitive system
-such as Windows,
-SCons treats a file with a
-.B .C
-suffix as a C source file.
-.SS .F file suffix
-SCons handles the upper-case
-.B .F
-file suffix differently,
-depending on the capabilities of
-the underlying system.
-On a case-sensitive system
-such as Linux or UNIX,
-SCons treats a file with a
-.B .F
-suffix as a Fortran source file
-that is to be first run through
-the standard C preprocessor.
-On a case-insensitive system
-such as Windows,
-SCons treats a file with a
-.B .F
-suffix as a Fortran source file that should
-.I not
-be run through the C preprocessor.
-.SS Windows: Cygwin Tools and Cygwin Python vs. Windows Pythons
-Cygwin supplies a set of tools and utilities
-that let users work on a
-Windows system using a more POSIX-like environment.
-The Cygwin tools, including Cygwin Python,
-do this, in part,
-by sharing an ability to interpret UNIX-like path names.
-For example, the Cygwin tools
-will internally translate a Cygwin path name
-like /cygdrive/c/mydir
-to an equivalent Windows pathname
-of C:/mydir (equivalent to C:\\mydir).
-
-Versions of Python
-that are built for native Windows execution,
-such as the python.org and ActiveState versions,
-do not have the Cygwin path name semantics.
-This means that using a native Windows version of Python
-to build compiled programs using Cygwin tools
-(such as gcc, bison, and flex)
-may yield unpredictable results.
-"Mixing and matching" in this way
-can be made to work,
-but it requires careful attention to the use of path names
-in your SConscript files.
-
-In practice, users can sidestep
-the issue by adopting the following rules:
-When using gcc,
-use the Cygwin-supplied Python interpreter
-to run SCons;
-when using Microsoft Visual C/C++
-(or some other Windows compiler)
-use the python.org or ActiveState version of Python
-to run SCons.
-.SS Windows: scons.bat file
-On Windows systems,
-SCons is executed via a wrapper
-.B scons.bat
-file.
-This has (at least) two ramifications:
-
-First, Windows command-line users
-that want to use variable assignment
-on the command line
-may have to put double quotes
-around the assignments:
-
-.ES
-scons "FOO=BAR" "BAZ=BLEH"
-.EE
-
-Second, the Cygwin shell does not
-recognize this file as being the same
-as an
-.B scons
-command issued at the command-line prompt.
-You can work around this either by
-executing
-.B scons.bat
-from the Cygwin command line,
-or by creating a wrapper shell
-script named
-.B scons .
-
-.SS MinGW
-
-The MinGW bin directory must be in your PATH environment variable or the
-PATH variable under the ENV construction variable for SCons
-to detect and use the MinGW tools. When running under the native Windows
-Python interpreter, SCons will prefer the MinGW tools over the Cygwin
-tools, if they are both installed, regardless of the order of the bin
-directories in the PATH variable. If you have both MSVC and MinGW
-installed and you want to use MinGW instead of MSVC,
-then you must explictly tell SCons to use MinGW by passing
-
-.ES
-tools=['mingw']
-.EE
-
-to the Environment() function, because SCons will prefer the MSVC tools
-over the MinGW tools.
-
-.SH EXAMPLES
-
-To help you get started using SCons,
-this section contains a brief overview of some common tasks.
-
-.SS Basic Compilation From a Single Source File
-
-.ES
-env = Environment()
-env.Program(target = 'foo', source = 'foo.c')
-.EE
-
-Note: Build the file by specifying
-the target as an argument
-("scons foo" or "scons foo.exe").
-or by specifying a dot ("scons .").
-
-.SS Basic Compilation From Multiple Source Files
-
-.ES
-env = Environment()
-env.Program(target = 'foo', source = Split('f1.c f2.c f3.c'))
-.EE
-
-.SS Setting a Compilation Flag
-
-.ES
-env = Environment(CCFLAGS = '-g')
-env.Program(target = 'foo', source = 'foo.c')
-.EE
-
-.SS Search The Local Directory For .h Files
-
-Note: You do
-.I not
-need to set CCFLAGS to specify -I options by hand.
-SCons will construct the right -I options from CPPPATH.
-
-.ES
-env = Environment(CPPPATH = ['.'])
-env.Program(target = 'foo', source = 'foo.c')
-.EE
-
-.SS Search Multiple Directories For .h Files
-
-.ES
-env = Environment(CPPPATH = ['include1', 'include2'])
-env.Program(target = 'foo', source = 'foo.c')
-.EE
-
-.SS Building a Static Library
-
-.ES
-env = Environment()
-env.StaticLibrary(target = 'foo', source = Split('l1.c l2.c'))
-env.StaticLibrary(target = 'bar', source = ['l3.c', 'l4.c'])
-.EE
-
-.SS Building a Shared Library
-
-.ES
-env = Environment()
-env.SharedLibrary(target = 'foo', source = ['l5.c', 'l6.c'])
-env.SharedLibrary(target = 'bar', source = Split('l7.c l8.c'))
-.EE
-
-.SS Linking a Local Library Into a Program
-
-.ES
-env = Environment(LIBS = 'mylib', LIBPATH = ['.'])
-env.Library(target = 'mylib', source = Split('l1.c l2.c'))
-env.Program(target = 'prog', source = ['p1.c', 'p2.c'])
-.EE
-
-.SS Defining Your Own Builder Object
-
-Notice that when you invoke the Builder,
-you can leave off the target file suffix,
-and SCons will add it automatically.
-
-.ES
-bld = Builder(action = 'pdftex < $SOURCES > $TARGET'
- suffix = '.pdf',
- src_suffix = '.tex')
-env = Environment(BUILDERS = {'PDFBuilder' : bld})
-env.PDFBuilder(target = 'foo.pdf', source = 'foo.tex')
-
-# The following creates "bar.pdf" from "bar.tex"
-env.PDFBuilder(target = 'bar', source = 'bar')
-.EE
-
-Note also that the above initialization
-overwrites the default Builder objects,
-so the Environment created above
-can not be used call Builders like env.Program(),
-env.Object(), env.StaticLibrary(), etc.
-
-.SS Adding Your Own Builder Object to an Environment
-
-.ES
-bld = Builder(action = 'pdftex < $SOURCES > $TARGET'
- suffix = '.pdf',
- src_suffix = '.tex')
-env = Environment()
-env.Append(BUILDERS = {'PDFBuilder' : bld})
-env.PDFBuilder(target = 'foo.pdf', source = 'foo.tex')
-env.Program(target = 'bar', source = 'bar.c')
-.EE
-
-You also can use other Pythonic techniques to add
-to the BUILDERS construction variable, such as:
-
-.ES
-env = Environment()
-env['BUILDERS]['PDFBuilder'] = bld
-.EE
-
-.SS Defining Your Own Scanner Object
-
-The following example shows an extremely simple scanner (the
-.BR kfile_scan ()
-function)
-that doesn't use a search path at all
-and simply returns the
-file names present on any
-.B include
-lines in the scanned file.
-This would implicitly assume that all included
-files live in the top-level directory:
-
-.ES
-import re
-
-'\" Note: the \\ in the following are for the benefit of nroff/troff,
-'\" not inappropriate doubled escape characters within the r'' raw string.
-include_re = re.compile(r'^include\\s+(\\S+)$', re.M)
-
-def kfile_scan(node, env, path, arg):
- contents = node.get_text_contents()
- includes = include_re.findall(contents)
- return env.File(includes)
-
-kscan = Scanner(name = 'kfile',
- function = kfile_scan,
- argument = None,
- skeys = ['.k'])
-scanners = Environment().Dictionary('SCANNERS')
-env = Environment(SCANNERS = scanners + [kscan])
-
-env.Command('foo', 'foo.k', 'kprocess < $SOURCES > $TARGET')
-
-bar_in = File('bar.in')
-env.Command('bar', bar_in, 'kprocess $SOURCES > $TARGET')
-bar_in.target_scanner = kscan
-.EE
-
-It is important to note that you
-have to return a list of File nodes from the scan function, simple
-strings for the file names won't do. As in the examples we are showing here,
-you can use the
-.BR File()
-function of your current Environment in order to create nodes on the fly from
-a sequence of file names with relative paths.
-
-Here is a similar but more complete example that searches
-a path of directories
-(specified as the
-.B MYPATH
-construction variable)
-for files that actually exist:
-
-.ES
-import re
-import os
-include_re = re.compile(r'^include\\s+(\\S+)$', re.M)
-
-def my_scan(node, env, path, arg):
- contents = node.get_text_contents()
- includes = include_re.findall(contents)
- if includes == []:
- return []
- results = []
- for inc in includes:
- for dir in path:
- file = str(dir) + os.sep + inc
- if os.path.exists(file):
- results.append(file)
- break
- return env.File(results)
-
-scanner = Scanner(name = 'myscanner',
- function = my_scan,
- argument = None,
- skeys = ['.x'],
- path_function = FindPathDirs('MYPATH')
- )
-scanners = Environment().Dictionary('SCANNERS')
-env = Environment(SCANNERS = scanners + [scanner],
- MYPATH = ['incs'])
-
-env.Command('foo', 'foo.x', 'xprocess < $SOURCES > $TARGET')
-.EE
-
-The
-.BR FindPathDirs ()
-function used in the previous example returns a function
-(actually a callable Python object)
-that will return a list of directories
-specified in the
-.B $MYPATH
-construction variable. It lets SCons detect the file
-.B incs/foo.inc
-, even if
-.B foo.x
-contains the line
-.B include foo.inc
-only.
-If you need to customize how the search path is derived,
-you would provide your own
-.B path_function
-argument when creating the Scanner object,
-as follows:
-
-.ES
-# MYPATH is a list of directories to search for files in
-def pf(env, dir, target, source, arg):
- top_dir = Dir('#').abspath
- results = []
- if 'MYPATH' in env:
- for p in env['MYPATH']:
- results.append(top_dir + os.sep + p)
- return results
-
-scanner = Scanner(name = 'myscanner',
- function = my_scan,
- argument = None,
- skeys = ['.x'],
- path_function = pf
- )
-.EE
-
-.SS Creating a Hierarchical Build
-
-Notice that the file names specified in a subdirectory's
-SConscript
-file are relative to that subdirectory.
-
-.ES
-SConstruct:
-
- env = Environment()
- env.Program(target = 'foo', source = 'foo.c')
-
- SConscript('sub/SConscript')
-
-sub/SConscript:
-
- env = Environment()
- # Builds sub/foo from sub/foo.c
- env.Program(target = 'foo', source = 'foo.c')
-
- SConscript('dir/SConscript')
-
-sub/dir/SConscript:
-
- env = Environment()
- # Builds sub/dir/foo from sub/dir/foo.c
- env.Program(target = 'foo', source = 'foo.c')
-.EE
-
-.SS Sharing Variables Between SConscript Files
-
-You must explicitly Export() and Import() variables that
-you want to share between SConscript files.
-
-.ES
-SConstruct:
-
- env = Environment()
- env.Program(target = 'foo', source = 'foo.c')
-
- Export("env")
- SConscript('subdirectory/SConscript')
-
-subdirectory/SConscript:
-
- Import("env")
- env.Program(target = 'foo', source = 'foo.c')
-.EE
-
-.SS Building Multiple Variants From the Same Source
-
-Use the variant_dir keyword argument to
-the SConscript function to establish
-one or more separate variant build directory trees
-for a given source directory:
-
-.ES
-SConstruct:
-
- cppdefines = ['FOO']
- Export("cppdefines")
- SConscript('src/SConscript', variant_dir='foo')
-
- cppdefines = ['BAR']
- Export("cppdefines")
- SConscript('src/SConscript', variant_dir='bar')
-
-src/SConscript:
-
- Import("cppdefines")
- env = Environment(CPPDEFINES = cppdefines)
- env.Program(target = 'src', source = 'src.c')
-.EE
-
-Note the use of the Export() method
-to set the "cppdefines" variable to a different
-value each time we call the SConscript function.
-
-.SS Hierarchical Build of Two Libraries Linked With a Program
-
-.ES
-SConstruct:
-
- env = Environment(LIBPATH = ['#libA', '#libB'])
- Export('env')
- SConscript('libA/SConscript')
- SConscript('libB/SConscript')
- SConscript('Main/SConscript')
-
-libA/SConscript:
-
- Import('env')
- env.Library('a', Split('a1.c a2.c a3.c'))
-
-libB/SConscript:
-
- Import('env')
- env.Library('b', Split('b1.c b2.c b3.c'))
-
-Main/SConscript:
-
- Import('env')
- e = env.Copy(LIBS = ['a', 'b'])
- e.Program('foo', Split('m1.c m2.c m3.c'))
-.EE
-
-The '#' in the LIBPATH directories specify that they're relative to the
-top-level directory, so they don't turn into "Main/libA" when they're
-used in Main/SConscript.
-
-Specifying only 'a' and 'b' for the library names
-allows SCons to append the appropriate library
-prefix and suffix for the current platform
-(for example, 'liba.a' on POSIX systems,
-\&'a.lib' on Windows).
-
-.SS Customizing construction variables from the command line.
-
-The following would allow the C compiler to be specified on the command
-line or in the file custom.py.
-
-.ES
-vars = Variables('custom.py')
-vars.Add('CC', 'The C compiler.')
-env = Environment(variables=vars)
-Help(vars.GenerateHelpText(env))
-.EE
-
-The user could specify the C compiler on the command line:
-
-.ES
-scons "CC=my_cc"
-.EE
-
-or in the custom.py file:
-
-.ES
-CC = 'my_cc'
-.EE
-
-or get documentation on the options:
-
-.ES
-$ scons -h
-
-CC: The C compiler.
- default: None
- actual: cc
-
-.EE
-
-.SS Using Microsoft Visual C++ precompiled headers
-
-Since windows.h includes everything and the kitchen sink, it can take quite
-some time to compile it over and over again for a bunch of object files, so
-Microsoft provides a mechanism to compile a set of headers once and then
-include the previously compiled headers in any object file. This
-technology is called precompiled headers. The general recipe is to create a
-file named "StdAfx.cpp" that includes a single header named "StdAfx.h", and
-then include every header you want to precompile in "StdAfx.h", and finally
-include "StdAfx.h" as the first header in all the source files you are
-compiling to object files. For example:
-
-StdAfx.h:
-.ES
-#include <windows.h>
-#include <my_big_header.h>
-.EE
-
-StdAfx.cpp:
-.ES
-#include <StdAfx.h>
-.EE
-
-Foo.cpp:
-.ES
-#include <StdAfx.h>
-
-/* do some stuff */
-.EE
-
-Bar.cpp:
-.ES
-#include <StdAfx.h>
-
-/* do some other stuff */
-.EE
-
-SConstruct:
-.ES
-env=Environment()
-env['PCHSTOP'] = 'StdAfx.h'
-env['PCH'] = env.PCH('StdAfx.cpp')[0]
-env.Program('MyApp', ['Foo.cpp', 'Bar.cpp'])
-.EE
-
-For more information see the document for the PCH builder, and the PCH and
-PCHSTOP construction variables. To learn about the details of precompiled
-headers consult the MSDN documention for /Yc, /Yu, and /Yp.
-
-.SS Using Microsoft Visual C++ external debugging information
-
-Since including debugging information in programs and shared libraries can
-cause their size to increase significantly, Microsoft provides a mechanism
-for including the debugging information in an external file called a PDB
-file. SCons supports PDB files through the PDB construction
-variable.
-
-SConstruct:
-.ES
-env=Environment()
-env['PDB'] = 'MyApp.pdb'
-env.Program('MyApp', ['Foo.cpp', 'Bar.cpp'])
-.EE
-
-For more information see the document for the PDB construction variable.
-
-.SH ENVIRONMENT
-
-.IP SCONS_LIB_DIR
-Specifies the directory that contains the SCons Python module directory
-(e.g. /home/aroach/scons-src-0.01/src/engine).
-
-.IP SCONSFLAGS
-A string of options that will be used by scons in addition to those passed
-on the command line.
-
-.SH "SEE ALSO"
-.B scons
-User Manual,
-.B scons
-Design Document,
-.B scons
-source code.
-
-.SH AUTHORS
-Steven Knight <knight@baldmt.com>
-.br
-Anthony Roach <aroach@electriceyeball.com>
-