.\"
.\" __FILE__ __REVISION__ __DATE__ __DEVELOPER__
.\"
+.TH SCONS 1 "__MONTH_YEAR__"
.\" ES - Example Start - indents and turns off line fill
+.rm ES
.de ES
.RS
.nf
..
.\" EE - Example End - ends indent and turns line fill back on
+.rm EE
.de EE
.fi
.RE
..
-.TH SCONS 1 "January 2005"
.SH NAME
scons \- a software construction tool
.SH SYNOPSIS
]
.SH DESCRIPTION
-The
-.B scons
+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
+By default,
+.B scons
+searches for a file named
.IR SConstruct ,
.IR Sconstruct ,
or
(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
+specified via the
.B -f
option.
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
+adds looks for a dir named
+.I site_scons
+in the dir containing the
+.I SConstruct
+file; it adds that
+.I site_scons
+to sys.path, reads the file
+.IR site_scons/site_init.py ,
+and adds the directory
+.I site_scons/site_tools
+to the default toolpath, if those exist. See the
+.I --no-site-dir
+and
+.I --site-dir
+options for more details.
+
.B scons
reads and executes the SConscript files as Python scripts,
so you may use normal Python scripting capabilities
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.
+whenever any "included" input file changes.
.B scons
supports the
ability to define new scanners for unknown input file types.
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
-necessary. The
+Specifying "cleanup" targets in SConscript files is not usually necessary.
+The
.B -c
flag removes all files
necessary to build the specified target:
to remove target files under build and export.
Additional files or directories to remove can be specified using the
-Clean() function.
+.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
+remaining at the top-level directory (where the
.I SConstruct
file lives) and specifying the subdirectory as the target to be
built:
or by changing directory and invoking scons with the
.B -u
option, which traverses up the directory
-hierarchy until it finds the
+hierarchy until it finds the
.I SConstruct
file, and then builds
targets relatively to the current subdirectory:
.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
+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-force ,
.BR --cache-disable ,
and
.B --cache-show
.B scons
knows how to search for available programming tools
on various systems.
-On WIN32 systems,
+On Windows systems,
.B scons
searches in order for the
Microsoft Visual C++ tools,
and the PharLap ETS compiler.
On OS/2 systems,
.B scons
-searches in order for the
+searches in order for the
OS/2 compiler,
the GCC tool chain,
and the Microsoft Visual C++ tools,
Environment construction variables.
.SH OPTIONS
-In general,
-.B scons
+In general,
+.B scons
supports the same command-line options as GNU
-.BR make ,
-and many of those supported by
+.BR make ,
+and many of those supported by
.BR cons .
.TP
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 Clean() function.
+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
and a necessary test does not
yet have any results in the cache.
-.TP
+.TP
.RI "-C" " directory" ", --directory=" directory
-Change to the specified
+Change to the specified
.I directory
-before searching for the
+before searching for the
.IR SConstruct ,
.IR Sconstruct ,
or
.I sconstruct
file, or doing anything
-else. Multiple
+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
+equivalent to
.BR "-f directory/SConstruct" ,
except that it will search for
.IR SConstruct ,
-.IR Sconstruct ,
+.IR Sconstruct ,
or
.I sconstruct
in the specified directory.)
of the various classes used internally by SCons
before and after reading the SConscript files
and before and after building targets.
-This only works when run under Python 2.1 or later.
+This is not supported when run under Python versions earlier than 2.1,
+when SCons is executed with the Python
+.B -O
+(optimized) option,
+or when the SCons modules
+have been compiled with optimization
+(that is, when executing from
+.B *.pyo
+files).
.TP
--debug=dtree
-Print the dependency tree
-after each top-level target is built. This prints out only derived files.
+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
.TP
--debug=includes
-Print the include tree after each top-level target is built.
+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:
.TP
--debug=memoizer
-Prints a summary of hits and misses in the Memoizer,
-the internal SCons subsystem for caching
-various values in memory instead of
-recomputing them each time they're needed.
+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.
+Only available when using Python 2.2 or later.
.TP
--debug=memory
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
Re-run SCons under the control of the
.RI pdb
Python debugger.
-.EE
.TP
--debug=presub
.ES
$ scons --debug=presub
Building myprog.o with action(s):
- $SHCC $SHCCFLAGS $CPPFLAGS $_CPPINCFLAGS -c -o $TARGET $SOURCES
-...
+ $SHCC $SHCFLAGS $SHCCFLAGS $CPPFLAGS $_CPPINCFLAGS -c -o $TARGET $SOURCES
+\&...
.EE
.TP
.TP
--debug=stree
-Print the dependency tree along with status information. This is the
-same as the debug=tree option, but additional status information is
-provided for each node in the tree.
+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 build command, the total build time, the total time spent
-executing build commands, the total time spent executing SConstruct and
-SConscript files, and the total time spent executing SCons itself.
+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
-Print the dependency tree
-after each top-level target is built. This prints out the complete
-dependency tree including implicit dependencies and ignored
-dependencies.
+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
.TP
.RI -f " file" ", --file=" file ", --makefile=" file ", --sconstruct=" file
-Use
-.I file
+Use
+.I file
as the initial SConscript file.
-.TP
+.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
+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
-i, --ignore-errors
Ignore all errors from commands executed to rebuild files.
-.TP
+.TP
.RI -I " directory" ", --include-dir=" directory
-Specifies a
+Specifies a
.I directory
to search for
-imported Python modules. If several
+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 can cause
+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
-to miss changes in the implicit dependencies in cases where a new implicit
+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. CPPPATH) than a current implicit dependency with the same name.
+(e.g.
+.BR CPPPATH ", " LIBPATH )
+than a current implicit dependency with the same name.
.TP
--implicit-deps-changed
-Force SCons to ignore the cached implicit dependencies. This causes the
+Forces SCons to ignore the cached implicit dependencies. This causes the
implicit dependencies to be rescanned and recached. This implies
.BR --implicit-cache .
--implicit-deps-unchanged
Force SCons to ignore changes in the implicit dependencies.
This causes cached implicit dependencies to always be used.
-This implies
+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
+If there is more than one
+.B -j
option, the last one is effective.
-.\" ??? If the
-.\" .B -j
+.\" ??? If the
+.\" .B -j
.\" option
.\" is specified without an argument,
-.\" .B scons
+.\" .B scons
.\" will not limit the number of
.\" simultaneous jobs.
.\" .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
+.\" average is at least
.\" .I N
.\" (a floating-point number).
-.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
.\" --list-derived
.TP
.RI --max-drift= SECONDS
-Set the maximum expected drift in the modification time of files to
+Set the maximum expected drift in the modification time of files to
.IR SECONDS .
-This value determines how old a file must be before its content signature
-is cached. 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 content
-signature cached. A negative value means to never cache the content
+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 cache the signature, no matter how old the file is.
+of 0 means to always use the cached signature,
+no matter how old the file is.
.TP
-n, --just-print, --dry-run, --recon
No execute. Print the commands that would be executed to build
any out-of-date target files, but do not execute the commands.
+.TP
+.RI --no-site-dir
+Prevents the automatic addition of the standard
+.I site_scons
+dir to
+.IR sys.path .
+Also prevents loading the
+.I site_scons/site_init.py
+module if it exists, and prevents adding
+.I site_scons/site_tools
+to the toolpath.
+
.\" .TP
.\" .RI -o " file" ", --old-file=" file ", --assume-old=" file
-.\" Do not rebuild
+.\" Do not rebuild
.\" .IR file ,
.\" and do
.\" not rebuild anything due to changes in the contents of
.\" .IR file .
-.\" .TP
+.\" .TP
.\" .RI --override " file"
.\" Read values to override specific build environment variables
-.\" from the specified
+.\" from the specified
.\" .IR file .
.\" .TP
.\" -p
.\" After printing, a normal build is performed
.\" as usual, as specified by other command-line options.
.\" This also prints version information
-.\" printed by the
+.\" printed by the
.\" .B -v
.\" option.
.\"
.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
.TP
-S, --no-keep-going, --stop
-Ignored for compatibility with GNU
+Ignored for compatibility with GNU
.BR make .
+.TP
+.RI --site-dir= dir
+Uses the named dir as the site dir rather than the default
+.I site_scons
+dir. This dir will get prepended to
+.IR sys.path ,
+the module
+.IR dir /site_init.py
+will get loaded if it exists, and
+.IR dir /site_tools
+will get added to the default toolpath.
+
+.TP
+.RI --stack-size= KILOBYTES
+Set the size stack used to run threads to
+.IR KILOBYTES .
+This value determines the stack size of the threads used to run jobs.
+These are the threads that execute the actions of the builders for the
+nodes that are out-of-date.
+Note that this option has no effect unless the
+.B num_jobs
+option, which corresponds to -j and --jobs, is larger than one. Using
+a stack size that is too small may cause stack overflow errors. This
+usually shows up as segmentation faults that cause scons to abort
+before building anything. Using a stack size that is too large will
+cause scons to use more memory than required and may slow down the entire
+build process.
+
+The default value is to use a stack size of 256 kilobytes, which should
+be appropriate for most uses. You should not need to increase this value
+unless you encounter stack overflow errors.
+
.TP
-t, --touch
Ignored for compatibility with GNU
-.BR make .
+.BR make .
(Touching a file to make it
-appear up-to-date is unnecessary when using
+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
+Walks up the directory structure until an
.I SConstruct ,
.I Sconstruct
-or
+or
.I sconstruct
file is found, and uses that
as the top of the directory tree.
.TP
-v, --version
-Print the
+Print the
.B scons
version, copyright information,
list of authors, and any other relevant information.
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.
--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.
.TP
--warn=deprecated, --warn=no-deprecated
-Enables or disables warnings about use of deprecated features.
+Enables or disables all warnings about use of deprecated features.
+These warnings are enabled by default.
+Warnings for some specific deprecated features
+may be enabled or disabled individually;
+see below.
+
+--warn=deprecated-copy, --warn=no-deprecated-copy
+Enables or disables warnings about use of the deprecated
+.B env.Copy()
+method.
+
+--warn=deprecated-source-signatures, --warn=no-deprecated-source-signatures
+Enables or disables warnings about use of the deprecated
+SourceSignatures() function
+or
+.B env.SourceSignatures()
+method.
+
+--warn=deprecated-target-signatures, --warn=no-deprecated-target-signatures
+Enables or disables warnings about use of the deprecated
+TargetSignatures() function
+or
+.B env.TargetSignatures()
+method.
+
+.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=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
These warnings are enabled by default.
.TP
---no-print-directory
-Turn off -w, even if it was turned on implicitly.
+--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 TARGET ,
+.BR TARGETS ,
+.BR SOURCE
+or
+.BR SOURCES .
+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
.\"
.\" .TP
.\" .RI -W " file" ", --what-if=" file ", --new-file=" file ", --assume-new=" file
-.\" Pretend that the target
-.\" .I file
+.\" Pretend that the target
+.\" .I file
.\" has been
-.\" modified. When used with the
+.\" modified. When used with the
.\" .B -n
.\" option, this
.\" show you what would be rebuilt if you were to modify that file.
-.\" Without
+.\" Without
.\" .B -n
.\" ... what? XXX
.\"
.\" --warn-undefined-variables
.\" Warn when an undefined variable is referenced.
-.TP
-.RI -Y " repository" ", --repository=" repository
+.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 specified, in which case the
+options may be specified, in which case the
repositories are searched in the order specified.
.SH CONFIGURATION FILE REFERENCE
.\" 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
+files communicate build information to
.BR scons .
-A new construction environment is created using the
-.B Environment
+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
Note that the
.B win32
platform adds the
+.B SYSTEMDRIVE
+and
.B SYSTEMROOT
-variable from the user's external environment
+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
+external CVS repository specifications like
.BR :pserver:anonymous@cvs.sourceforge.net:/cvsroot/scons )
-will work on Win32 systems.
+will work on Windows systems.
The platform argument may be function or callable object,
in which case the Environment() method
Additionally, a specific set of tools
with which to initialize the environment
-may specified as an optional keyword argument:
+may be specified as an optional keyword argument:
.ES
env = Environment(tools = ['msvc', 'lex'])
Also note that the toolpath is
stored in the environment for use
by later calls to
-.BR Copy ()
+.BR Clone ()
and
.BR Tool ()
methods:
.ES
base = Environment(toolpath=['custom_path'])
-derived = base.Copy(tools=['custom_tool'])
+derived = base.Clone(tools=['custom_tool'])
derived.CustomBuilder()
.EE
g77
gas
gcc
+gfortran
gnulink
gs
hpc++
sunar
sunc++
suncc
+sunf77
+sunf90
+sunf95
sunlink
swig
tar
On posix and cygwin platforms
the GNU tools (e.g. gcc) are preferred by SCons,
-on win32 the Microsoft tools (e.g. msvc)
+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.
environment's builder methods.
The arguments to the builder methods are
.B target
-(a list of target files)
+(a list of targets to be built,
+usually file names)
and
.B source
-(a list of source files).
+(a list of sources to be built,
+usually file names).
Because long lists of file names
can lead to a lot of quoting,
env.Program('bar', source = string.split('bar.c foo.c'))
.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,
executable program
.B bar
(on POSIX systems)
-or
+or
.B bar.exe
(on Windows systems)
from the bar.c source file:
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
env.Program('hello', 'hello.c', LIBS=['gl', 'glut'])
.EE
-or generate a shared library with a nonstandard suffix:
+or generate a shared library with a non-standard suffix:
.ES
-env.SharedLibrary('word', 'word.cpp', SHLIBSUFFIX='.ocx')
+env.SharedLibrary('word', 'word.cpp',
+ SHLIBSUFFIX='.ocx',
+ LIBSUFFIXES=['.ocx'])
.EE
-Although the builder methods defined by
-.B scons
-are, in fact,
+(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:
from SCons.Script import *
.EE
-All builder methods return a list of Nodes
-that represent the target or targets that will be built.
+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(s)
+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.
Or you can use the
.BR Flatten ()
-supplied by scons
+function supplied by scons
to create a list containing just the Nodes,
which may be more convenient:
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()
provides the following builder methods:
'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.IP CFile()
-.IP env.CFile()
-Builds a C source file given a lex (.l) or yacc (.y) input file.
-The suffix specified by the $CFILESUFFIX construction variable
-(.c by default)
-is automatically added to the target
-if it is not already present. Example:
-
-.ES
-# builds foo.c
-env.CFile(target = 'foo.c', source = 'foo.l')
-# builds bar.c
-env.CFile(target = 'bar', source = 'bar.y')
-.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.IP CXXFile()
-.IP env.CXXFile()
-Builds a C++ source file given a lex (.ll) or yacc (.yy)
-input file.
-The suffix specified by the $CXXFILESUFFIX construction variable
-(.cc 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 .dvi file from a .tex, .ltx or .latex input file.
-If the source file suffix is .tex,
-.B scons
-will examine the contents of the file;
-if the string
-.B \\documentclass
-or
-.B \\documentstyle
-is found, the file is assumed to be a LaTeX file and
-the target is built by invoking the $LATEXCOM command line;
-otherwise, the $TEXCOM command line is used.
-If the file is a LaTeX file,
-the
-.B DVI
-builder method will also examine the contents
-of the
-.B .aux file
-and invoke the $BIBTEX command line
-if the string
-.B bibdata
-is found,
-and will examine the contents
-.B .log
-file and re-run the $LATEXCOM command
-if the log file says it is necessary.
-
-The suffix .dvi
-(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 Jar()
-.IP env.Jar()
-Builds a Java archive (.jar) file
-from a source tree of .class files.
-If the $JARCHDIR value is set, the
-.B jar
-command will change to the specified directory using the
-.B \-C
-option.
-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')
-.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.IP Java()
-.IP env.Java()
-Builds one or more Java class files
-from one or more source trees of .java files.
-The class files will be placed underneath
-the specified target directory.
-SCons will parse each source .java file
-to find the classes
-(including inner classes)
-defined within that file,
-and from that figure out the
-target .class files that will be created.
-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 .class files
-will be placed in a directory reflecting
-the specified package name.
-For example,
-the file
-.I Foo.java
-defining a single public
-.I Foo
-class and
-containing a package name of
-.I sub.dir
-will generate a corresponding
-.IR sub/dir/Foo.class
-class file.
-
-Example:
-
-.ES
-env.Java(target = 'classes', source = 'src')
-env.Java(target = 'classes', source = ['src1', 'src2'])
-.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 either the names of .class files,
-or the objects returned from the
-.B Java
-builder method.
-
-If the construction variable
-.B JAVACLASSDIR
-is set, either in the environment
-or in the call to the
-.B JavaH
-builder method itself,
-then the value of the variable
-will be stripped from the
-beginning of any .class 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
-.B StaticLibrary
-builder method.
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.IP LoadableModule()
-.IP env.LoadableModule()
-On most systems,
-this is the same as
-.BR SharedLibrary ().
-On Mac OS X (Darwin) platforms,
-this creates a loadable module bundle.
-
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.IP M4()
-.IP env.M4()
-Builds an output file from an M4 input file.
-This uses a default $M4FLAGS value of
-.BR -E ,
-which considers all warnings to be fatal
-and stops on the first warning
-when using the GNU version of m4.
-Example:
-
-.ES
-env.M4(target = 'foo.c', source = 'foo.c.m4')
-.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.IP Moc()
-.IP env.Moc()
-Builds an output file from a moc input file. Moc input files are either
-header files or cxx files. This builder is only available after using the
-tool 'qt'. See the QTDIR variable for more information.
-Example:
-
-.ES
-env.Moc('foo.h') # generates moc_foo.cc
-env.Moc('foo.cpp') # generates foo.moc
-.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.IP MSVSProject()
-.IP env.MSVSProject()
-Builds Microsoft Visual Studio project files.
-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 set by
-.B MSVS_VERSION
-in the Environment constructor).
-For VS 6, it will generate
-.B .dsp
-and
-.B .dsw
-files, for VS 7, it will
-generate
-.B .vcproj
-and
-.B .sln
-files.
-
-It takes several lists of filenames to be placed into the project
-file, currently these are limited to
-.B srcs, incs, localincs, resources,
-and
-.B misc.
-These are pretty self explanatory, but it
-should be noted that the 'srcs' list is NOT added to the $SOURCES
-environment variable. This is because it represents a list of files
-to be added to the project file, not the source used to build the
-project file (in this case, the 'source' is the SConscript file used
-to call MSVSProject).
-
-In addition to these values (which are all optional, although not
-specifying any of them results in an empty project file), the
-following values must be specified:
-
-target: The name of the target .dsp or .vcproj file. The correct
-suffix for the version of Visual Studio must be used, but the value
-
-env['MSVSPROJECTSUFFIX']
-
-will be defined to the correct value (see example below).
-
-variant: The name of this particular variant. These are typically
-things like "Debug" or "Release", but really can be anything you want.
-Multiple calls to MSVSProject with different variants are allowed: all
-variants will be added to the project file with their appropriate
-build targets and sources.
-
-buildtarget: A list of SCons.Node.FS objects which is returned from
-the command which builds the target. This is used to tell SCons what
-to build when the 'build' button is pressed inside of the IDE.
-
-Example Usage:
-
-.ES
- barsrcs = ['bar.cpp'],
- barincs = ['bar.h'],
- barlocalincs = ['StdAfx.h']
- barresources = ['bar.rc','resource.h']
- barmisc = ['bar_readme.txt']
-
- dll = local.SharedLibrary(target = 'bar.dll',
- source = barsrcs)
-
- local.MSVSProject(target = 'Bar' + env['MSVSPROJECTSUFFIX'],
- srcs = barsrcs,
- incs = barincs,
- localincs = barlocalincs,
- resources = barresources,
- misc = barmisc,
- buildtarget = dll,
- variant = 'Release')
-.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.IP Object()
-.IP env.Object()
-A synonym for the
-.B StaticObject
-builder method.
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.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 .pdf file from a .dvi input file
-(or, by extension, a .tex, .ltx, or .latex input file).
-The suffix specified by the $PDFSUFFIX construction variable
-(.pdf by default)
-is added automatically to the target
-if it is not already present. Example:
-
-.ES
-# builds from aaa.tex
-env.PDF(target = 'aaa.pdf', source = 'aaa.tex')
-# builds bbb.pdf from bbb.dvi
-env.PDF(target = 'bbb', source = 'bbb.dvi')
-.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.IP PostScript()
-.IP env.PostScript()
-Builds a .ps file from a .dvi input file
-(or, by extension, a .tex, .ltx, or .latex input file).
-The suffix specified by the $PSSUFFIX construction variable
-(.ps by default)
-is added automatically to the target
-if it is not already present. Example:
-
-.ES
-# builds from aaa.tex
-env.PostScript(target = 'aaa.ps', source = 'aaa.tex')
-# builds bbb.ps from bbb.dvi
-env.PostScript(target = 'bbb', source = 'bbb.dvi')
-.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.IP Program()
-.IP env.Program()
-Builds an executable given one or more object files
-or C, C++, D, or Fortran source files.
-If any C, C++, D or Fortran source files are specified,
-then they will be automatically
-compiled to object files using the
-.B Object
-builder method;
-see that builder method's description for
-a list of legal source file suffixes
-and how they are interpreted.
-The target executable file prefix
-(specified by the $PROGPREFIX construction variable; nothing by default)
-and suffix
-(specified by the $PROGSUFFIX construction variable;
-by default, .exe 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
-.I .res
-(or
-.I .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 .class 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 .class files,
-or the objects return from the
-.B Java
-builder method.
-
-If the construction variable
-.B JAVACLASSDIR
-is set, either in the environment
-or in the call to the
-.B RMIC
-builder method itself,
-then the value of the variable
-will be stripped from the
-beginning of any .class 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 (_clnt.c) file
-from a specified RPC (.x) 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 (.h) file
-from a specified RPC (.x) 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 (_svc.c) file
-from a specified RPC (.x) 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 (_xdr.c) file
-from a specified RPC (.x) 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
-(.so on a POSIX system, .dll on WIN32)
-given one or more object files
-or C, C++, D or Fortran source files.
-If any source files are given,
-then they will be automatically
-compiled to object files.
-The static library prefix and suffix (if any)
-are automatically added to the target.
-The target library file prefix
-(specified by the $SHLIBPREFIX construction variable;
-by default, lib on POSIX systems, nothing on Windows systems)
-and suffix
-(specified by the $SHLIBSUFFIX construction variable;
-by default, .dll on Windows systems, .so 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 WIN32 systems, the
-.B SharedLibrary
-builder method will always build an import (.lib) library
-in addition to the shared (.dll) library,
-adding a .lib library with the same basename
-if there is not already a .lib 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
-.B SharedObject
-builder method).
-.B scons
-will raise an error if there is any mismatch.
-.IP
-On WIN32 systems, specifying "register=1" will cause the dll to be
-registered after it is built using REGSVR32. The command that is run
-("regsvr32" by default) is determined by $REGSVR construction
-variable, and the flags passed are determined by $REGSVRFLAGS. By
-default, $REGSVRFLAGS includes "/s", to prevent dialogs from popping
-up and requiring user attention when it is run. If you change
-$REGSVRFLAGS, be sure to include "/s". For example,
-
-.ES
-env.SharedLibrary(target = 'bar',
- source = ['bar.cxx', 'foo.obj'],
- register=1)
-.EE
-
-.IP
-will register "bar.dll" 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
-.B StaticObject
-builder method.
-On some platforms building a shared object requires additional
-compiler options (e.g. -fPIC for gcc) in addition to those needed to build a
-normal (static) object, but on some platforms there is no difference between a
-shared object and a normal (static) one. When there is a difference, SCons
-will only allow shared objects to be linked into a shared library, and will
-use a different suffix for shared objects. On platforms where there is no
-difference, SCons will allow both normal (static)
-and shared objects to be linked into a
-shared library, and will use the same suffix for shared and normal
-(static) objects.
-The target object file prefix
-(specified by the $SHOBJPREFIX construction variable;
-by default, the same as $OBJPREFIX)
-and suffix
-(specified by the $SHOBJSUFFIX construction variable)
-are automatically added to the target if not already present.
-Examples:
-
-.ES
-env.SharedObject(target = 'ddd', source = 'ddd.c')
-env.SharedObject(target = 'eee.o', source = 'eee.cpp')
-env.SharedObject(target = 'fff.obj', source = 'fff.for')
-.EE
-
-Note that the source files will be scanned
-according to the suffix mappings in
-.B SourceFileScanner
-object.
-See the section "Scanner Objects,"
-below, for a more information.
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.IP StaticLibrary()
-.IP env.StaticLibrary()
-Builds a static library given one or more object files
-or C, C++, D or Fortran source files.
-If any source files are given,
-then they will be automatically
-compiled to object files.
-The static library prefix and suffix (if any)
-are automatically added to the target.
-The target library file prefix
-(specified by the $LIBPREFIX construction variable;
-by default, lib on POSIX systems, nothing on Windows systems)
-and suffix
-(specified by the $LIBSUFFIX construction variable;
-by default, .lib on Windows systems, .a 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
-.B 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 WIN32: 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 WIN32: 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 Objective C file
- .mm Objective C++ file
- .s assembly language file
- .S WIN32: assembly language file
- POSIX: assembly language file + C pre-processor
- .spp assembly language file + C pre-processor
- .SPP assembly language file + C pre-processor
-.EE
-.IP
-The target object file prefix
-(specified by the $OBJPREFIX construction variable; nothing by default)
-and suffix
-(specified by the $OBJSUFFIX construction variable;
-\.obj on Windows systems, .o 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
-
-Note that the source files will be scanned
-according to the suffix mappings in
-.B SourceFileScanner
-object.
-See the section "Scanner Objects,"
-below, for a more information.
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.IP Tar()
-.IP env.Tar()
-Builds a tar archive of the specified files
-and/or directories.
-Unlike most builder methods,
-the
-.B 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
-
+'\" 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 TypeLibrary()
-.IP env.TypeLibrary()
-Builds a Windows type library (.tlb) file from and input IDL file
-(.idl). In addition, it will build the associated inteface stub and
-proxy source files. It names them according to the base name of the .idl file.
-.IP
-For example,
-
-.ES
-env.TypeLibrary(source="foo.idl")
-.EE
-.IP
-Will create foo.tlb, foo.h, foo_i.c, foo_p.c, and foo_data.c.
-
+.so builders.man
'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.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 .ui files directly as inputs for Program, Library and SharedLibrary
-without using this builder. Using the builder lets you override the standard
-naming conventions (be careful: prefixes are always prepended to names of
-built files; if you don't want prefixes, you may set them to ``).
-See the QTDIR variable for more information.
-Example:
-
-.ES
-env.Uic('foo.ui') # -> ['foo.h', 'uic_foo.cc', 'moc_foo.cc']
-env.Uic(target = Split('include/foo.h gen/uicfoo.cc gen/mocfoo.cc'),
- source = 'foo.ui') # -> ['include/foo.h', 'gen/uicfoo.cc', 'gen/mocfoo.cc']
-.EE
-
+'\" 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
'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.IP Zip()
-.IP env.Zip()
-Builds a zip archive of the specified files
-and/or directories.
-Unlike most builder methods,
-the
-.B 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
+.P
All
targets of builder methods automatically depend on their sources.
An explicit dependency can
-be specified using the
-.B Depends
+be specified using the
+.B Depends
method of a construction environment (see below).
In addition,
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 ()
+Scanner object used by the
+.BR Object (),
+.BR StaticObject (),
and
.BR SharedObject ()
Builders by adding them
Except where otherwise noted,
the same-named
construction environment method
-and global function
+and global function
provide the exact same functionality.
The only difference is that,
where appropriate,
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
include:
'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
+.TP
.RI Action( action ", [" strfunction ", " varlist ])
.TP
.RI env.Action( action ", [" strfunction ", " varlist ])
See the section "Action Objects,"
below, for a complete explanation of the arguments and behavior.
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI AddPostAction( target ", " action )
-.TP
-.RI env.AddPostAction( target ", " action )
-Arranges for the specified
+Note that the
+.BR env.Action ()
+form of the invocation will expand
+construction variables in any arguments strings,
+including the
.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).
+argument,
+at the time it is called
+using the construction variables in the
+.B 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 AddPreAction( target ", " action )
.TP
-.RI env.AddPreAction( target ", " action )
-Arranges for the specified
-.I action
-to be performed
-before the specified
-.I target
-is built.
-The specified action(s) may be
-an Action object, or anything that
-can be converted into an Action object
+.RI AddMethod( object, function ", [" name ])
+.TP
+.RI env.AddMethod( function ", [" name ])
+When called with the
+.BR AddMethod ()
+form,
+adds the specified
+.I function
+to the specified
+.I object
+as the specified method
+.IR name .
+When called with the
+.BR env.AddMethod ()
+form,
+adds the specified
+.I function
+to the construction environment
+.I env
+as the specified method
+.IR name .
+In both cases, if
+.I name
+is omitted or
+.BR None ,
+the name of the
+specified
+.I function
+itself is used for the method name.
+
+Examples:
+
+.ES
+# Note that the first argument to the function to
+# be attached as a method must be the object through
+# which the method will be called; the Python
+# convention is to call it 'self'.
+def my_method(self, arg):
+ print "my_method() got", arg
+
+# Use the global AddMethod() function to add a method
+# to the Environment class. This
+AddMethod(Environment, my_method)
+env = Environment()
+env.my_method('arg')
+
+# Add the function as a method, using the function
+# name for the method call.
+env = Environment()
+env.AddMethod(my_method, 'other_method_name')
+env.other_method_name('another arg')
+.EE
+
+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.TP
+.RI AddOption( arguments )
+This function adds a new command-line option to be recognized.
+The specified
+.I arguments
+are the same as supported by the standard Python
+.BR optparse.add_option ()
+method (with a few additional capabilities noted below);
+see the documentation for
+.B optparse
+for a thorough discussion of its option-processing capabities.
+(Note that although the
+.B optparse
+module was not a standard module until Python 2.3,
+.B scons
+contains a compatible version of the module
+that is used to provide identical functionality
+when run by earlier Python versions.)
+
+In addition to the arguments and values supported by the
+.B optparse.add_option ()
+method,
+the SCons
+.BR AddOption ()
+function allows you to set the
+.B nargs
+keyword value to
+.B '?'
+(a string with just the question mark)
+to indicate that the specified long option(s) take(s) an
+.I optional
+argument.
+When
+.B "nargs = '?'"
+is passed to the
+.BR AddOption ()
+function, the
+.B const
+keyword argument
+may be used to supply the "default"
+value that should be used when the
+option is specified on the command line
+without an explicit argument.
+
+If no
+.B default=
+keyword argument is supplied when calling
+.BR AddOption (),
+the option will have a default value of
+.BR None .
+
+Once a new command-line option has been added with
+.BR AddOption (),
+the option value may be accessed using
+.BR GetOption ()
+or
+.BR env.GetOption ().
+\" NOTE: in SCons 1.x or 2.0, user options will be settable, but not yet.
+\" Uncomment this when that works. See tigris issue 2105.
+\" The value may also be set, using
+\" .BR SetOption ()
+\" or
+\" .BR env.SetOption (),
+\" if conditions in a
+\" .B SConscript
+\" require overriding any default value.
+\" Note, however, that a
+\" value specified on the command line will
+\" .I always
+\" override a value set by any SConscript file.
+
+Any specified
+.B help=
+strings for the new option(s)
+will be displayed by the
+.B -H
+or
+.B -h
+options
+(the latter only if no other help text is
+specified in the SConscript files).
+The help text for the local options specified by
+.BR AddOption ()
+will appear below the SCons options themselves,
+under a separate
+.B "Local Options"
+heading.
+The options will appear in the help text
+in the order in which the
+.BR AddOption ()
+calls occur.
+
+Example:
+
+.ES
+AddOption('--prefix',
+ dest='prefix',
+ nargs=1, type='string',
+ action='store',
+ metavar='DIR',
+ help='installation prefix')
+env = Environment(PREFIX = GetOption('prefix'))
+.EE
+
+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.TP
+.RI AddPostAction( target ", " action )
+.TP
+.RI env.AddPostAction( target ", " action )
+Arranges for the specified
+.I action
+to be performed
+after the specified
+.I target
+has been built.
+The specified action(s) may be
+an Action object, or anything that
+can be converted into an Action object
+(see below).
+
+When multiple targets are supplied,
+the action may be called multiple times,
+once after each action that generates
+one or more targets in the list.
+
+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.TP
+.RI AddPreAction( target ", " action )
+.TP
+.RI env.AddPreAction( target ", " action )
+Arranges for the specified
+.I action
+to be performed
+before the specified
+.I target
+is built.
+The specified action(s) may be
+an Action object, or anything that
+can be converted into an Action object
(see below).
+When multiple targets are specified,
+the action(s) may be called multiple times,
+once before each action that generates
+one or more targets in the list.
+
+Note that if any of the targets are built in multiple steps,
+the action will be invoked just
+before the "final" action that specifically
+generates the specified target(s).
+For example, when building an executable program
+from a specified source
+.B .c
+file via an intermediate object file:
+
+.ES
+foo = Program('foo.c')
+AddPreAction(foo, 'pre_action')
+.EE
+
+The specified
+.B pre_action
+would be executed before
+.B scons
+calls the link command that actually
+generates the executable program binary
+.BR foo ,
+not before compiling the
+.B foo.c
+file into an object file.
+
'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.TP
.RI Alias( alias ", [" targets ", [" action ]])
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')
env.Alias('update', ['file1', 'file2'], "update_database $SOURCES")
.EE
+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.TP
+.RI AllowSubstExceptions([ exception ", ...])"
+Specifies the exceptions that will be allowed
+when expanding construction variables.
+By default,
+any construction variable expansions that generate a
+.B NameError
+or
+.BR IndexError
+exception will expand to a
+.B ''
+(a null string) and not cause scons to fail.
+All exceptions not in the specified list
+will generate an error message
+and terminate processing.
+
+If
+.B AllowSubstExceptions
+is called multiple times,
+each call completely overwrites the previous list
+of allowed exceptions.
+
+Example:
+
+.ES
+# Requires that all construction variable names exist.
+# (You may wish to do this if you want to enforce strictly
+# that all construction variables must be defined before use.)
+AllowSubstExceptions()
+
+# Also allow a string containing a zero-division expansion
+# like '${1 / 0}' to evalute to ''.
+AllowSubstExceptions(IndexError, NameError, ZeroDivisionError)
+.EE
+
'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.TP
.RI AlwaysBuild( target ", ...)"
and the lists are added together.
(See also the Prepend method, below.)
+Example:
+
.ES
env.Append(CCFLAGS = ' -g', FOO = ['foo.yyy'])
.EE
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.
+
Example:
.ES
print 'before:',env['ENV']['INCLUDE']
include_path = '/foo/bar:/foo'
-env.PrependENVPath('INCLUDE', include_path)
+env.AppendENVPath('INCLUDE', include_path)
print 'after:',env['ENV']['INCLUDE']
yields:
.I not
be added again to the list.
+Example:
+
.ES
env.AppendUnique(CCFLAGS = '-g', FOO = ['foo.yyy'])
.EE
.B SourceCode
function.
+Example:
+
.ES
env.SourceCode('.', env.BitKeeper())
.EE
.RI BuildDir( build_dir ", " src_dir ", [" duplicate ])
.TP
.RI env.BuildDir( build_dir ", " src_dir ", [" duplicate ])
-This specifies a build directory
-.I build_dir
-in which to build all derived files
-that would normally be built under
-.IR src_dir .
-Multiple build directories can be set up for multiple build variants, for
-example.
-.I src_dir
-must be underneath the SConstruct file's directory,
+Deprecated synonyms for
+.BR VariantDir ()
and
+.BR env.VariantDir ().
+The
.I build_dir
-may not be underneath the
-.I src_dir .
-
-The default behavior is for
-.B scons
-to duplicate all of the files in the tree underneath
-.I src_dir
-into
-.IR build_dir ,
-and then build the derived files within the copied tree.
-(The duplication is performed by
-linking or copying,
-depending on the platform; see also the
-.IR --duplicate
-option.)
-This guarantees correct builds
-regardless of whether intermediate source files
-are generated during the build,
-where preprocessors or other scanners search
-for included files,
-or whether individual compilers or other invoked tools
-are hard-coded to put derived files in the same directory as source files.
-
-This behavior of making a complete copy of the source tree
-may be disabled by setting
-.I duplicate
-to 0.
-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 build_dir .
-This is always more efficient than
-.IR duplicate =1,
-and is usually safe for most builds.
-Specifying
-.IR duplicate =0,
-however,
-may cause build problems
-if source files are generated during the build,
-if any invoked tools are hard-coded to
-put derived files in the same directory as the source files.
-
-Note that specifying a
-.B BuildDir
-works most naturally
-with a subsidiary SConscript file
-in the source directory.
-However,
-you would then call the subsidiary SConscript file
-not in the source directory,
-but in the
-.I build_dir ,
-as if
-.B scons
-had made a virtual copy of the source tree
-regardless of the value of
-.IR duplicate .
-This is how you tell
-.B scons
-which variant of a source tree to build.
-For example:
-
-.ES
-BuildDir('build-variant1', 'src')
-SConscript('build-variant1/SConscript')
-BuildDir('build-variant2', 'src')
-SConscript('build-variant2/SConscript')
-.EE
-
-.IP
-See also the
-.BR SConscript ()
-function, described below,
-for another way to
-specify a build directory
-in conjunction with calling a subsidiary
-SConscript file.)
+argument becomes the
+.I variant_dir
+argument of
+.BR VariantDir ()
+or
+.BR env.VariantDir ().
'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
+.TP
.RI Builder( action ", [" arguments ])
-.TP
+.TP
.RI env.Builder( action ", [" arguments ])
Creates a Builder object for
the specified
See the section "Builder Objects,"
below, for a complete explanation of the arguments and behavior.
+Note that the
+.BR env.Builder ()
+form of the invocation will expand
+construction variables in any arguments strings,
+including the
+.I action
+argument,
+at the time it is called
+using the construction variables in the
+.B env
+construction environment through which
+.BR env.Builder ()
+was called.
+The
+.BR Builder ()
+form delays all variable expansion
+until after the Builder object is actually called.
+
'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
+.TP
.RI CacheDir( cache_dir )
-.TP
+.TP
.RI env.CacheDir( cache_dir )
Specifies that
.B scons
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 ()
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
+.TP
.RI Clean( targets ", " files_or_dirs )
-.TP
+.TP
.RI env.Clean( targets ", " files_or_dirs )
This specifies a list of files or directories which should be removed
whenever the targets are specified with the
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'))
'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.TP
-.RI Command( target ", " source ", " commands ", [" key = val ", ...])"
+.RI Command( target ", " source ", " action ", [" key = val ", ...])"
.TP
-.RI env.Command( target ", " source ", " commands ", [" key = val ", ...])"
+.RI env.Command( target ", " source ", " action ", [" key = val ", ...])"
Executes a specific action
(or list of actions)
to build a target file or files.
Any other keyword arguments specified override any
same-named existing construction variables.
-Note that an action can be an external command,
+An action can be an external command,
specified as a string,
or a callable Python object;
-see "Action Objects," below.
+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
rename ])
.EE
+.IP
+Note that the
+.BR Command ()
+function will usually assume, by default,
+that the specified targets and/or sources are Files,
+if no other part of the configuration
+identifies what type of entry it is.
+If necessary, you can explicitly specify
+that targets or source nodes should
+be treated as directoriese
+by using the
+.BR Dir ()
+or
+.BR env.Dir ()
+functions.
+
+Examples:
+
+.ES
+env.Command('ddd.list', Dir('ddd'), 'ls -l $SOURCE > $TARGET')
+
+env['DISTDIR'] = 'destination/directory'
+env.Command(env.Dir('$DISTDIR')), None, make_distdir)
+.EE
+
+.IP
+(Also note that SCons will usually
+automatically create any directory necessary to hold a target file,
+so you normally don't need to create directories by hand.)
+
'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.TP
.RI Configure( env ", [" custom_tests ", " conf_dir ", " log_file ", " config_h ])
'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.TP
-.RI env.Copy([ key = val ", ...])"
+.RI env.Clone([ key = val ", ...])"
Return a separate copy of a construction environment.
If there are any keyword arguments specified,
they are added to the returned copy,
overwriting any existing values
for the keywords.
+Example:
+
.ES
-env2 = env.Copy()
-env3 = env.Copy(CCFLAGS = '-g')
+env2 = env.Clone()
+env3 = env.Clone(CCFLAGS = '-g')
.EE
.IP
Additionally, a list of tools and a toolpath may be specified, as in
.ES
def MyTool(env): env['FOO'] = 'bar'
-env4 = env.Copy(tools = ['msvc', MyTool])
+env4 = env.Clone(tools = ['msvc', MyTool])
+.EE
+
+The
+.I parse_flags
+keyword argument is also recognized:
+
+.ES
+# create an environment for compiling programs that use wxWidgets
+wx_env = env.Clone(parse_flags = '!wx-config --cflags --cxxflags')
.EE
+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.TP
+.RI env.Copy([ key = val ", ...])"
+A now-deprecated synonym for
+.BR env.Clone() .
+
'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.TP
.RI env.CVS( repository ", " module )
so that you only have to
replicate part of the repository
directory hierarchy in your
-local build directory:
+local build directory.
+
+Examples:
.ES
# Will fetch foo/bar/src.c
.EE
'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
+.TP
+.RI Decider( function )
+.TP
+.RI env.Decider( function )
+Specifies that all up-to-date decisions for
+targets built through this construction environment
+will be handled by the specified
+.IR function .
+The
+.I function
+can be one of the following strings
+that specify the type of decision function
+to be performed:
+
+.RS 10
+.HP 6
+.B timestamp-newer
+Specifies that a target shall be considered out of date and rebuilt
+if the dependency's timestamp is newer than the target file's timestamp.
+This is the behavior of the classic Make utility,
+and
+.B make
+can be used a synonym for
+.BR timestamp-newer .
+
+.HP 6
+.B timestamp-match
+Specifies that a target shall be considered out of date and rebuilt
+if the dependency's timestamp is different than the
+timestamp recorded the last time the target was built.
+This provides behavior very similar to the classic Make utility
+(in particular, files are not opened up so that their
+contents can be checksummed)
+except that the target will also be rebuilt if a
+dependency file has been restored to a version with an
+.I earlier
+timestamp, such as can happen when restoring files from backup archives.
+
+.HP 6
+.B MD5
+Specifies that a target shall be considered out of date and rebuilt
+if the dependency's content has changed sine the last time
+the target was built,
+as determined be performing an MD5 checksum
+on the dependency's contents
+and comparing it to the checksum recorded the
+last time the target was built.
+.B content
+can be used as a synonym for
+.BR MD5 .
+
+.HP 6
+.B MD5-timestamp
+Specifies that a target shall be considered out of date and rebuilt
+if the dependency's content has changed sine the last time
+the target was built,
+except that dependencies with a timestamp that matches
+the last time the target was rebuilt will be
+assumed to be up-to-date and
+.I not
+rebuilt.
+This provides behavior very similar
+to the
+.B MD5
+behavior of always checksumming file contents,
+with an optimization of not checking
+the contents of files whose timestamps haven't changed.
+The drawback is that SCons will
+.I not
+detect if a file's content has changed
+but its timestamp is the same,
+as might happen in an automated script
+that runs a build,
+updates a file,
+and runs the build again,
+all within a single second.
+.RE
+
+.IP
+Examples:
+
+.ES
+# Use exact timestamp matches by default.
+Decider('timestamp-match')
+
+# Use MD5 content signatures for any targets built
+# with the attached construction environment.
+env.Decider('content')
+.EE
+
+.IP
+In addition to the above already-available functions,
+the
+.I function
+argument may be an actual Python function
+that takes the following three arguments:
+
+.RS 10
+.IP dependency
+The Node (file) which
+should cause the
+.I target
+to be rebuilt
+if it has "changed" since the last tme
+.I target was built.
+
+.IP target
+The Node (file) being built.
+In the normal case,
+this is what should get rebuilt
+if the
+.I dependency
+has "changed."
+
+.IP prev_ni
+Stored information about the state of the
+.I dependency
+the last time the
+.I target
+was built.
+This can be consulted to match various
+file characteristics
+such as the timestamp,
+size, or content signature.
+.RE
+
+.IP
+The
+.I function
+should return a
+.B True
+(non-zero)
+value if the
+.I dependency
+has "changed" since the last time
+the
+.I target
+was built
+(indicating that the target
+.I should
+be rebuilt),
+and
+.B False
+(zero)
+otherwise
+(indicating that the target should
+.I not
+be rebuilt).
+Note that the decision can be made
+using whatever criteria are appopriate.
+Ignoring some or all of the function arguments
+is perfectly normal.
+
+Example:
+
+.ES
+def my_decider(dependency, target, prev_ni):
+ return not os.path.exists(str(target))
+
+env.Decider(my_decider)
+.EE
+
+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.TP
.RI Default( targets )
.TP
.RI env.Default( targets )
will also accept the Node returned by any
of a construction environment's
builder methods.
+
Examples:
.ES
.TP
.RI env.Depends( target ", " dependency )
Specifies an explicit dependency;
-the target file(s) will be rebuilt
-whenever the dependency file(s) has changed.
+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
'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
only the specified construction
variables are returned in the dictionary.
+Example:
+
.ES
dict = env.Dictionary()
cc_dict = env.Dictionary('CC', 'CCFLAGS', 'CCCOM')
.RI env.Dir( name ", [" directory ])
This returns a Directory Node,
an object that represents the specified directory
-.IR name .
+.IR name .
.I name
-can be a relative or absolute path.
+can be a relative or absolute path.
.I directory
-is an optional directory that will be used as the parent 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.
env=Environment()
print env.Dump('CCCOM')
.EE
+.IP
will print:
.ES
-'$CC $CCFLAGS $CPPFLAGS $_CPPDEFFLAGS $_CPPINCFLAGS -c -o $TARGET $SOURCES'
+\&'$CC $CCFLAGS $CPPFLAGS $_CPPDEFFLAGS $_CPPINCFLAGS -c -o $TARGET $SOURCES'
.EE
.ES
env=Environment()
print env.Dump()
.EE
+.IP
will print:
.ES
{ 'AR': 'ar',
.RI EnsurePythonVersion( major ", " minor )
.TP
.RI env.EnsurePythonVersion( major ", " minor )
-Ensure that the Python version is at least
-.IR major . minor .
+Ensure that the Python version is at least
+.IR major . minor .
This function will
print out an error message and exit SCons with a non-zero exit code if the
actual Python version is not late enough.
+Example:
+
.ES
EnsurePythonVersion(2,2)
.EE
'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.TP
-.RI EnsureSConsVersion( major ", " minor )
+.RI EnsureSConsVersion( major ", " minor ", [" revision ])
.TP
-.RI env.EnsureSConsVersion( major ", " minor )
-Ensure that the SCons version is at least
-.IR major . minor .
+.RI env.EnsureSConsVersion( major ", " minor ", [" revision ])
+Ensure that the SCons version is at least
+.IR major.minor ,
+or
+.IR major.minor.revision .
+if
+.I revision
+is specified.
This function will
print out an error message and exit SCons with a non-zero exit code if the
actual SCons version is not late enough.
+Examples:
+
.ES
-EnsureSConsVersion(0,9)
+EnsureSConsVersion(0,14)
+
+EnsureSConsVersion(0,96,90)
.EE
'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
pairs.
'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
+.TP
.RI Execute( action ", [" strfunction ", " varlist ])
.TP
.RI env.Execute( action ", [" strfunction ", " varlist ])
.RI Export( vars )
.TP
.RI env.Export( vars )
-This tells
+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.
+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. 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
function, below.
'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
+.TP
.RI File( name ", [" directory ])
-.TP
+.TP
.RI env.File( name ", [" directory ])
This returns a
File Node,
an object that represents the specified file
-.IR name .
+.IR name .
.I name
-can be a relative or absolute path.
+can be a relative or absolute path.
.I directory
-is an optional directory that will be used as the parent 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
.RI FindFile( file ", " dirs )
.TP
.RI env.FindFile( file ", " dirs )
-Search for
-.I file
-in the path specified by
+Search for
+.I file
+in the path specified by
.IR dirs .
.I file
may be a list of file names or a single file name. In addition to searching
for files that exist in the filesytem, this function also searches for
derived files that have not yet been built.
+Example:
+
.ES
foo = env.FindFile('foo', ['dir1', 'dir2'])
.EE
+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.TP
+.RI FindInstalledFiles( )
+.TP
+.RI env.FindInstalledFiles( )
+Returns the list of targets set up by the
+.B Install()
+or
+.B InstallAs()
+builders.
+
+This function serves as a convenient method to select the contents of
+a binary package.
+
+Example:
+
+.ES
+Install( '/bin', [ 'executable_a', 'executable_b' ] )
+
+# will return the file node list
+# [ '/bin/executable_a', '/bin/executable_b' ]
+FindInstalledFiles()
+
+Install( '/lib', [ 'some_library' ] )
+
+# will return the file node list
+# [ '/bin/executable_a', '/bin/executable_b', '/lib/some_library' ]
+FindInstalledFiles()
+.EE
+
+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.TP
+.RI FindSourceFiles( node = '"."' )
+.TP
+.RI env.FindSourceFiles( node = '"."' )
+
+Returns the list of nodes which serve as the source of the built files.
+It does so by inspecting the dependency tree starting at the optional
+argument
+.B node
+which defaults to the '"."'-node. It will then return all leaves of
+.B node.
+These are all children which have no further children.
+
+This function is a convenient method to select the contents of a Source
+Package.
+
+Example:
+
+.ES
+Program( 'src/main_a.c' )
+Program( 'src/main_b.c' )
+Program( 'main_c.c' )
+
+# returns ['main_c.c', 'src/main_a.c', 'SConstruct', 'src/main_b.c']
+FindSourceFiles()
+
+# returns ['src/main_b.c', 'src/main_a.c' ]
+FindSourceFiles( 'src' )
+.EE
+
+.IP
+As you can see build support files (SConstruct in the above example)
+will also be returned by this function.
+
+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.TP
+.RI FindPathDirs( variable )
+Returns a function
+(actually a callable Python object)
+intended to be used as the
+.B path_function
+of a Scanner object.
+The returned object will look up the specified
+.I variable
+in a construction environment
+and treat the construction variable's value as a list of
+directory paths that should be searched
+(like
+.BR CPPPATH ,
+.BR LIBPATH ,
+etc.).
+
+Note that use of
+.BR FindPathDirs ()
+is generally preferable to
+writing your own
+.B path_function
+for the following reasons:
+1) The returned list will contain all appropriate directories
+found in source trees
+(when
+.BR VariantDir ()
+is used)
+or in code repositories
+(when
+.BR Repository ()
+or the
+.B \-Y
+option are used).
+2) scons will identify expansions of
+.I variable
+that evaluate to the same list of directories as,
+in fact, the same list,
+and avoid re-scanning the directories for files,
+when possible.
+
+Example:
+
+.ES
+def my_scan(node, env, path, arg):
+ # Code to scan file contents goes here...
+ return include_files
+
+scanner = Scanner(name = 'myscanner',
+ function = my_scan,
+ path_function = FindPathDirs('MYPATH'))
+.EE
+
'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.TP
.RI Flatten( sequence )
other Builders will automatically
flatten lists specified as input,
but direct Python manipulation of
-these lists does not:
+these lists does not.
+
+Examples:
.ES
foo = Object('foo.c')
print str(object)
.EE
+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.TP
+.RI GetBuildFailures()
+Returns a list of exceptions for the
+actions that failed while
+attempting to build targets.
+Each element in the returned list is a
+.B BuildError
+object
+with the following attributes
+that record various aspects
+of the build failure:
+
+.B .node
+The node that was being built
+when the build failure occurred.
+
+.B .status
+The numeric exit status
+returned by the command or Python function
+that failed when trying to build the
+specified Node.
+
+.B .errstr
+The SCons error string
+describing the build failure.
+(This is often a generic
+message like "Error 2"
+to indicate that an executed
+command exited with a status of 2.)
+
+.B .filename
+The name of the file or
+directory that actually caused the failure.
+This may be different from the
+.B .node
+attribute.
+For example,
+if an attempt to build a target named
+.B sub/dir/target
+fails because the
+.B sub/dir
+directory could not be created,
+then the
+.B .node
+attribute will be
+.B sub/dir/target
+but the
+.B .filename
+attribute will be
+.BR sub/dir .
+
+.B .executor
+The SCons Executor object
+for the target Node
+being built.
+This can be used to retrieve
+the construction environment used
+for the failed action.
+
+.B .action
+The actual SCons Action object that failed.
+This will be one specific action
+out of the possible list of
+actions that would have been
+executed to build the target.
+
+.B .command
+The actual expanded command that was executed and failed,
+after expansion of
+.BR $TARGET ,
+.BR $SOURCE ,
+and other construction variables.
+
+Note that the
+.BR GetBuildFailures ()
+function
+will always return an empty list
+until any build failure has occurred,
+which means that
+.BR GetBuildFailures ()
+will always return an empty list
+while the
+.B SConscript
+files are being read.
+Its primary intended use is
+for functions that will be
+executed before SCons exits
+by passing them to the
+standard Python
+.BR atexit.register ()
+function.
+Example:
+
+.ES
+import atexit
+
+def print_build_failures():
+ from SCons.Script import GetBuildFailures
+ for bf in GetBuildFailures():
+ print "%s failed: %s" % (bf.node, bf.errstr)
+
+atexit.register(print_build_failures)
+.EE
+
'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.TP
.RI GetBuildPath( file ", [" ... ])
.TP
.RI env.GetLaunchDir()
Returns the absolute path name of the directory from which
-.B
-scons
+.B scons
was initially invoked.
This can be useful when using the
.BR \-u ,
.RI GetOption( name )
.TP
.RI env.GetOption( name )
-This function provides a way to query a select subset of the scons command line
-options from a SConscript file. See
-.IR SetOption ()
-for a description of the options available.
+This function provides a way to query the value of
+SCons options set on scons command line
+(or set using the
+.IR SetOption ()
+function).
+The options supported are:
+
+.RS 10
+.TP 6
+.B cache_debug
+.TP 6
+which corresponds to --cache-debug;
+.TP 6
+.B cache_disable
+which corresponds to --cache-disable;
+.TP 6
+.B cache_force
+which corresponds to --cache-force;
+.TP 6
+.B cache_show
+which corresponds to --cache-show;
+.TP 6
+.B clean
+which corresponds to -c, --clean and --remove;
+.TP 6
+.B config
+which corresponds to --config;
+.TP 6
+.B directory
+which corresponds to -C and --directory;
+.TP 6
+.B diskcheck
+which corresponds to --diskcheck
+.TP 6
+.B duplicate
+which corresponds to --duplicate;
+.TP 6
+.B file
+which corresponds to -f, --file, --makefile and --sconstruct;
+.TP 6
+.B help
+which corresponds to -h and --help;
+.TP 6
+.B ignore_errors
+which corresponds to --ignore-errors;
+.TP 6
+.B implicit_cache
+which corresponds to --implicit-cache;
+.TP 6
+.B implicit_deps_changed
+which corresponds to --implicit-deps-changed;
+.TP 6
+.B implicit_deps_unchanged
+which corresponds to --implicit-deps-unchanged;
+.TP 6
+.B interactive
+which corresponds to --interact and --interactive;
+.TP 6
+.B keep_going
+which corresponds to -k and --keep-going;
+.TP 6
+.B max_drift
+which corresponds to --max-drift;
+.TP 6
+.B no_exec
+which corresponds to -n, --no-exec, --just-print, --dry-run and --recon;
+.TP 6
+.B no_site_dir
+which corresponds to --no-site-dir;
+.TP 6
+.B num_jobs
+which corresponds to -j and --jobs;
+.TP 6
+.B profile_file
+which corresponds to --profile;
+.TP 6
+.B question
+which corresponds to -q and --question;
+.TP 6
+.B random
+which corresponds to --random;
+.TP 6
+.B repository
+which corresponds to -Y, --repository and --srcdir;
+.TP 6
+.B silent
+which corresponds to -s, --silent and --quiet;
+.TP 6
+.B site_dir
+which corresponds to --site-dir;
+.TP 6
+.B stack_size
+which corresponds to --stack-size;
+.TP 6
+.B taskmastertrace_file
+which corresponds to --taskmastertrace; and
+.TP 6
+.B warn
+which corresponds to --warn and --warning.
+.RE
+
+.IP
+See the documentation for the
+corresponding command line object for information about each specific
+option.
+
+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.TP
+.RI Glob( pattern ", [" ondisk ", " source ", " strings ])
+.TP
+.RI env.Glob( pattern ", [" ondisk ", " source ", " strings ])
+Returns Nodes (or strings) that match the specified
+.IR pattern ,
+relative to the directory of the current
+.B SConscript
+file.
+The
+.BR env.Glob ()
+form performs string substition on
+.I pattern
+and returns whatever matches
+the resulting expanded pattern.
+
+The specified
+.I pattern
+uses Unix shell style metacharacters for matching:
+
+.ES
+ * matches everything
+ ? matches any single character
+ [seq] matches any character in seq
+ [!seq] matches any char not in seq
+.EE
+
+.IP
+Character matches do
+.I not
+span directory separators.
+
+The
+.BR Glob ()
+knows about
+repositories
+(see the
+.BR Repository ()
+function)
+and source directories
+(see the
+.BR VariantDir ()
+function)
+and
+returns a Node (or string, if so configured)
+in the local (SConscript) directory
+if matching Node is found
+anywhere in a corresponding
+repository or source directory.
+
+The
+.B ondisk
+argument may be set to
+.B False
+(or any other non-true value)
+to disable the search for matches on disk,
+thereby only returning matches among
+already-configured File or Dir Nodes.
+The default behavior is to
+return corresponding Nodes
+for any on-disk matches found.
+
+The
+.B source
+argument may be set to
+.B True
+(or any equivalent value)
+to specify that,
+when the local directory is a
+.BR VariantDir (),
+the returned Nodes should be from the
+corresponding source directory,
+not the local directory.
+
+The
+.B strings
+argument may be set to
+.B True
+(or any equivalent value)
+to have the
+.BR Glob ()
+function return strings, not Nodes,
+that represent the matched files or directories.
+The returned strings will be relative to
+the local (SConscript) directory.
+(Note that This may make it easier to perform
+arbitrary manipulation of file names,
+but if the returned strings are
+passed to a different
+.B SConscript
+file,
+any Node translation will be relative
+to the other
+.B SConscript
+directory,
+not the original
+.B SConscript
+directory.)
+
+Example:
+
+.ES
+Program('foo', Glob('*.c'))
+.EE
'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
'\".TP
.RI Help( text )
.TP
.RI env.Help( text )
-This specifies help text to be printed if the
-.B -h
+This specifies help text to be printed if the
+.B -h
argument is given to
.BR scons .
If
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
+.TP
.RI Import( vars )
-.TP
+.TP
.RI env.Import( vars )
-This tells
+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
+or in the
.I exports
-argument to
+argument to
.BR SConscript ().
-Variables exported by
+Variables exported by
.BR SConscript ()
have precedence.
-Multiple variable names can be passed to
+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("*")
.EE
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI Install( dir ", " source )
-.TP
-.RI env.Install( dir ", " source )
-Installs one or more files in a destination directory.
-The file names remain the same.
-
-.ES
-env.Install(dir = '/usr/local/bin', source = ['foo', 'bar'])
-.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI InstallAs( target ", " source )
-.TP
-.RI env.InstallAs( target ", " source )
-Installs one or more files as specific file names,
-allowing changing a file name as part of the
-installation.
-It is an error if the target and source
-list different numbers of files.
-
-.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
-
'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.TP
.RI Literal( string )
exists in a repository.
Returns a list of the target Node or Nodes.
+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.TP
+.RI env.MergeFlags( arg ", [" unique ])
+Merges the specified
+.I arg
+values to the construction envrionment's construction variables.
+If the
+.I arg
+argument is not a dictionary,
+it is converted to one by calling
+.B env.ParseFlags()
+on the argument
+before the values are merged.
+Note that
+.I arg
+must be a single value,
+so multiple strings must
+be passed in as a list,
+not as separate arguments to
+.BR env.MergeFlags ().
+
+By default,
+duplicate values are eliminated;
+you can, however, specify
+.B unique=0
+to allow duplicate
+values to be added.
+When eliminating duplicate values,
+any construction variables that end with
+the string
+.B PATH
+keep the left-most unique value.
+All other construction variables keep
+the right-most unique value.
+
+Examples:
+
+.ES
+# Add an optimization flag to $CCFLAGS.
+env.MergeFlags('-O3')
+
+# Combine the flags returned from running pkg-config with an optimization
+# flag and merge the result into the construction variables.
+env.MergeFlags(['!pkg-config gtk+-2.0 --cflags', '-O3'])
+
+# Combine an optimization flag with the flags returned from running pkg-config
+# twice and merge the result into the construction variables.
+env.MergeFlags(['-O3',
+ '!pkg-config gtk+-2.0 --cflags --libs',
+ '!pkg-config libpng12 --cflags --libs'])
+.EE
+
+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.TP
+.RI NoCache( target ", ...)"
+.TP
+.RI env.NoCache( target ", ...)"
+Specifies a list of files which should
+.I not
+be cached whenever the
+.BR CacheDir ()
+method has been activated.
+The specified targets may be a list
+or an individual target.
+
+Multiple files should be specified
+either as separate arguments to the
+.BR NoCache ()
+method, or as a list.
+.BR NoCache ()
+will also accept the return value of any of the construction environment
+Builder methods.
+
+Calling
+.BR NoCache ()
+on directories and other non-File Node types has no effect because
+only File Nodes are cached.
+
+Examples:
+
+.ES
+NoCache('foo.elf')
+NoCache(env.Program('hello', 'hello.c'))
+.EE
+
+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.TP
+.RI NoClean( target ", ...)"
+.TP
+.RI env.NoClean( target ", ...)"
+Specifies a list of files or directories which should
+.I not
+be removed whenever the targets (or their dependencies)
+are specified with the
+.B -c
+command line option.
+The specified targets may be a list
+or an individual target.
+Multiple calls to
+.BR NoClean ()
+are legal,
+and prevent each specified target
+from being removed by calls to the
+.B -c
+option.
+
+Multiple files or directories should be specified
+either as separate arguments to the
+.BR NoClean ()
+method, or as a list.
+.BR NoClean ()
+will also accept the return value of any of the construction environment
+Builder methods.
+
+Calling
+.BR NoClean ()
+for a target overrides calling
+.BR Clean ()
+for the same target,
+and any targets passed to both functions will
+.I not
+be removed by the
+.B -c
+option.
+
+Examples:
+
+.ES
+NoClean('foo.elf')
+NoClean(env.Program('hello', 'hello.c'))
+.EE
+
'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.TP
.RI env.ParseConfig( command ", [" function ", " unique ])
.I command .
The default
.I function
-expects the output of a typical
+is
+.BR env.MergeFlags (),
+which expects the output of a typical
.I *-config command
(for example,
.BR gtk-config )
and adds the options
to the appropriate construction variables.
-By default,
+By default,
duplicate values are not
added to any construction variables;
you can specify
to allow duplicate
values to be added.
-By default,
-.BR -L ,
-.BR -l ,
-.BR -Wa ,
-.BR -Wl ,
-.BR -Wp ,
-.B -I
-and other options,
-are add to the
-.BR LIBPATH ,
-.BR LIBS ,
-.BR ASFLAGS ,
-.BR LINKFLAGS ,
-.BR CPPFLAGS ,
-.B CPPPATH
-and
-.B CCFLAGS
-construction variables,
-respectively.
-A returned
-.B -pthread
-option gets added to both the
-.B CCFLAGS
-and
-.B LINKFLAGS
-variables.
-A returned
-.B -framework
-option gets added to the
-.B LINKFLAGS
-variable.
-Any other strings not associated with options
-are assumed to be the names of libraries
-and added to the
-.B LIBS
-construction variable.
+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 ])
+.RI ParseDepends( filename ", [" must_exist ", " only_one ])
.TP
-.RI env.ParseDepends( filename ", [" must_exist " " only_one ])
+.RI env.ParseDepends( filename ", [" must_exist ", " only_one ])
Parses the contents of the specified
.I filename
as a list of dependencies in the style of
.I filename
does not exist.
The optional
-.I must_exit
+.I must_exist
argument may be set to a non-zero
value to have
scons
.B ParseDepends
function.
+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.TP
+.RI env.ParseFlags( flags ", ...)"
+Parses one or more strings containing
+typical command-line flags for GCC tool chains
+and returns a dictionary with the flag values
+separated into the appropriate SCons construction variables.
+This is intended as a companion to the
+.BR env.MergeFlags ()
+method, but allows for the values in the returned dictionary
+to be modified, if necessary,
+before merging them into the construction environment.
+(Note that
+.BR env.MergeFlags ()
+will call this method if its argument is not a dictionary,
+so it is usually not necessary to call
+.BR env.ParseFlags ()
+directly unless you want to manipulate the values.)
+
+If the first character in any string is
+an exclamation mark (!),
+the rest of the string is executed as a command,
+and the output from the command is
+parsed as GCC tool chain command-line flags
+and added to the resulting dictionary.
+
+Flag values are translated accordig to the prefix found,
+and added to the following construction variables:
+
+.ES
+-arch CCFLAGS, LINKFLAGS
+-D CPPDEFINES
+-framework FRAMEWORKS
+-frameworkdir= FRAMEWORKPATH
+-include CCFLAGS
+-isysroot CCFLAGS, LINKFLAGS
+-I CPPPATH
+-l LIBS
+-L LIBPATH
+-mno-cygwin CCFLAGS, LINKFLAGS
+-mwindows LINKFLAGS
+-pthread CCFLAGS, LINKFLAGS
+-std= CFLAGS
+-Wa, ASFLAGS, CCFLAGS
+-Wl,-rpath= RPATH
+-Wl,-R, RPATH
+-Wl,-R RPATH
+-Wl, LINKFLAGS
+-Wp, CPPFLAGS
+- CCFLAGS
++ CCFLAGS, LINKFLAGS
+.EE
+
+.IP
+Any other strings not associated with options
+are assumed to be the names of libraries
+and added to the
+.B LIBS
+construction variable.
+
+Examples (all of which produce the same result):
+
+.ES
+dict = env.ParseFlags('-O2 -Dfoo -Dbar=1')
+dict = env.ParseFlags('-O2', '-Dfoo', '-Dbar=1')
+dict = env.ParseFlags(['-O2', '-Dfoo -Dbar=1'])
+dict = env.ParseFlags('-O2', '!echo -Dfoo -Dbar=1')
+.EE
+
'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.TP
env.Perforce()
The returned Builder
is intended to be passed to the
.B SourceCode
-function:
+function.
+
+Example:
.ES
env.SourceCode('.', env.Perforce())
Returns a callable object
that can be used to initialize
a construction environment using the
-platform keyword of the Environment() method:
+platform keyword of the Environment() method.
+
+Example:
.ES
env = Environment(platform = Platform('win32'))
Note that the
.B win32
platform adds the
+.B SYSTEMDRIVE
+and
.B SYSTEMROOT
-variable from the user's external environment
+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
+external CVS repository specifications like
.BR :pserver:anonymous@cvs.sourceforge.net:/cvsroot/scons )
-will work on Win32 systems.
+will work on Windows systems.
'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.TP
-.RI Precious( target ", ...)"
-.TP
-.RI env.Precious( target ", ...)"
+.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:
+ count = 0
+ def __call__(self, node, *args, **kw):
+ self.count += 100
+ sys.stderr.write('Evaluated %s nodes\\r' % self.count)
+Progress(ProgressCounter(), interval=100)
+.EE
+.IP
+If the first argument
+.BR Progress ()
+is a string,
+the string will be displayed
+every
+.I interval
+evaluated Nodes.
+The default is to print the string on standard output;
+an alternate output stream
+may be specified with the
+.B file=
+argument.
+The following will print a series of dots
+on the error output,
+one dot for every 100 evaluated Nodes:
+
+.ES
+import sys
+Progress('.', interval=100, file=sys.stderr)
+.EE
+.IP
+If the string contains the verbatim substring
+.B $TARGET,
+it will be replaced with the Node.
+Note that, for performance reasons, this is
+.I not
+a regular SCons variable substition,
+so you can not use other variables
+or use curly braces.
+The following example will print the name of
+every evaluated Node,
+using a
+.B \\\\r
+(carriage return) to cause each line to overwritten by the next line,
+and the
+.B overwrite=
+keyword argument to make sure the previously-printed
+file name is overwritten with blank spaces:
+
+.ES
+import sys
+Progress('$TARGET\\r', overwrite=True)
+.EE
+.IP
+If the first argument to
+.BR Progress ()
+is a list of strings,
+then each string in the list will be displayed
+in rotating fashion every
+.I interval
+evaluated Nodes.
+This can be used to implement a "spinner"
+on the user's screen as follows:
+
+.ES
+Progress(['-\\r', '\\\\\\r', '|\\r', '/\\r'], interval=5)
+.EE
+
+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.TP
+.RI Precious( target ", ...)"
+.TP
+.RI env.Precious( target ", ...)"
Marks each given
.I target
as precious so it is not deleted before it is rebuilt. Normally
and the lists are added together.
(See also the Append method, above.)
+Example:
+
.ES
env.Prepend(CCFLAGS = '-g ', FOO = ['foo.yyy'])
.EE
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.
+
Example:
.ES
include_path = '/foo/bar:/foo'
env.PrependENVPath('INCLUDE', include_path)
print 'after:',env['ENV']['INCLUDE']
+.EE
-yields:
+The above exmaple will print:
+
+.ES
before: /biz:/foo
after: /foo/bar:/foo:/biz
.EE
'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.TP
-.RI env.AppendUnique( key = val ", [...])"
+.RI env.PrependUnique( key = val ", [...])"
Appends the specified keyword arguments
to the beginning of construction variables in the environment.
If the Environment does not have
.I not
be added again to the list.
+Example:
+
.ES
env.PrependUnique(CCFLAGS = '-g', FOO = ['foo.yyy'])
.EE
.B SourceCode
function:
+Examples:
+
.ES
env.SourceCode('.', env.RCS())
.EE
Replaces construction variables in the Environment
with the specified keyword arguments.
+Example:
+
.ES
env.Replace(CCFLAGS = '-g', FOO = 'foo.xxx')
.EE
'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.TP
-.RI Return( vars )
-This tells
-.B scons
-what variable(s) to use as the return value(s) of the current SConscript
-file. These variables will be returned to the "calling" SConscript file
-as the return value(s) of
-.BR SConscript ().
-Multiple variable names should be passed to
+.RI Requires( target ", " prerequisite )
+.TP
+.RI env.Requires( target ", " prerequisite )
+Specifies an order-only relationship
+between the specified target file(s)
+and the specified prerequisite file(s).
+The prerequisite file(s)
+will be (re)built, if necessary,
+.I before
+the target file(s),
+but the target file(s) do not actually
+depend on the prerequisites
+and will not be rebuilt simply because
+the prerequisite file(s) change.
+
+Example:
+
+.ES
+env.Requires('foo', 'file-that-must-be-built-before-foo')
+.EE
+
+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.TP
+.RI Return([ vars "... , " stop= ])
+By default,
+this stops processing the current SConscript
+file and returns to the calling SConscript file
+the values of the variables named in the
+.I vars
+string arguments.
+Multiple strings contaning variable names may be passed to
+.BR Return ().
+Any strings that contain white space
+
+The optional
+.B stop=
+keyword argument may be set to a false value
+to continue processing the rest of the SConscript
+file after the
+.BR Return ()
+call.
+This was the default behavior prior to SCons 0.98.
+However, the values returned
+are still the values of the variables in the named
+.I vars
+at the point
.BR Return ()
-as a list. Example:
+is called.
+
+Examples:
.ES
+# Returns without returning a value.
+Return()
+
+# Returns the value of the 'foo' Python variable.
Return("foo")
-Return(["foo", "bar"])
+
+# 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
+.TP
.RI Scanner( function ", [" argument ", " keys ", " path_function ", " node_class ", " node_factory ", " scan_check ", " recursive ])
-.TP
+.TP
.RI env.Scanner( function ", [" argument ", " keys ", " path_function ", " node_class ", " node_factory ", " scan_check ", " recursive ])
Creates a Scanner object for
the specified
The returned Builder
is intended to be passed to the
.B SourceCode
-function:
+function.
+
+Example:
.ES
env.SourceCode('.', env.SCCS())
'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.TP
-.RI SConscript( scripts ", [" exports ", " build_dir ", " src_dir ", " duplicate ])
+.RI SConscript( scripts ", [" exports ", " variant_dir ", " duplicate ])
+'\" .RI SConscript( scripts ", [" exports ", " variant_dir ", " src_dir ", " duplicate ])
.TP
-.RI env.SConscript( scripts ", [" exports ", " build_dir ", " src_dir ", " duplicate ])
+.RI env.SConscript( scripts ", [" exports ", " variant_dir ", " duplicate ])
+'\" .RI env.SConscript( scripts ", [" exports ", " variant_dir ", " src_dir ", " duplicate ])
.TP
-.RI SConscript(dirs= subdirs ", [name=" script ", " exports ", " build_dir ", " src_dir ", " duplicate ])
+.RI SConscript(dirs= subdirs ", [name=" script ", " exports ", " variant_dir ", " duplicate ])
+'\" .RI SConscript(dirs= subdirs ", [name=" script ", " exports ", " variant_dir ", " src_dir ", " duplicate ])
.TP
-.RI env.SConscript(dirs= subdirs ", [name=" script ", " exports ", " build_dir ", " src_dir ", " duplicate ])
+.RI env.SConscript(dirs= subdirs ", [name=" script ", " exports ", " variant_dir ", " duplicate ])
+'\" .RI env.SConscript(dirs= subdirs ", [name=" script ", " exports ", " variant_dir ", " src_dir ", " duplicate ])
This tells
.B scons
to execute
one or more subsidiary SConscript (configuration) files.
+Any variables returned by a called script using
+.BR Return ()
+will be returned by the call to
+.BR SConscript ().
There are two ways to call the
.BR SConscript ()
function.
(either explicitly or as created by
a function like
.BR Split ()).
+Examples:
+.ES
+SConscript('SConscript') # run SConscript in the current directory
+SConscript('src/SConscript') # run SConscript in the src directory
+SConscript(['src/SConscript', 'doc/SConscript'])
+config = SConscript('MyConfig.py')
+.EE
The second way you can call
.BR SConscript ()
by supplying an optional
.RI name= script
keyword argument.
+The first three examples below have the same effect
+as the first three examples above:
+.ES
+SConscript(dirs='.') # run SConscript in the current directory
+SConscript(dirs='src') # run SConscript in the src directory
+SConscript(dirs=['src', 'doc'])
+SConscript(dirs=['sub1', 'sub2'], name='MySConscript')
+.EE
-The optional
+The optional
.I exports
argument provides a list of variable names or a dictionary of
named values to export to the
-.IR script(s) ". "
+.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
+and do not affect the global pool of variables used by the
.BR Export ()
function.
-'\"If multiple dirs are provided,
-'\"each script gets a fresh export.
+'\"If multiple dirs are provided, each script gets a fresh export.
The subsidiary
.I script(s)
must use the
.BR Import ()
function to import the variables.
+Examples:
+.ES
+foo = SConscript('sub/SConscript', exports='env')
+SConscript('dir/SConscript', exports=['env', 'variable'])
+SConscript(dirs='subdir', exports='env variable')
+SConscript(dirs=['one', 'two', 'three'], exports='shared_info')
+.EE
+
+If the optional
+.I variant_dir
+argument is present, it causes an effect equivalent to the
+.BR VariantDir ()
+method described below.
+(If
+.I variant_dir
+is not present, the
+'\" .IR src_dir and
+.I duplicate
+'\" arguments are ignored.)
+argument is ignored.)
+The
+.I variant_dir
+'\" and
+'\" .I src_dir
+'\" arguments are interpreted relative to the directory of the calling
+argument is interpreted relative to the directory of the calling
+.BR SConscript file.
+See the description of the
+.BR VariantDir ()
+function below for additional details and restrictions.
-The optional
-.I build_dir
-argument specifies that all of the target files
-(for example, object files and executables)
-that would normally be built in the subdirectory in which
-.I script
-resides should actually
-be built in
-.IR build_dir .
-.I build_dir
-is interpreted relative to the directory
-of the calling SConscript file.
+If
+'\" .IR variant_dir " is present, but"
+'\" .IR src_dir " is not,"
+.IR variant_dir " is present,"
+the source directory is relative to the called
+.BR SConscript " file."
+.ES
+SConscript('src/SConscript', variant_dir = 'build')
+.EE
+is equivalent to
+.ES
+VariantDir('build', 'src')
+SConscript('build/SConscript')
+.EE
+This later paradigm is often used when the sources are
+in the same directory as the
+.BR SConstruct file:
+.ES
+SConscript('SConscript', variant_dir = 'build')
+.EE
+is equivalent to
+.ES
+VariantDir('build', '.')
+SConscript('build/SConscript')
+.EE
-The optional
-.I src_dir
-argument specifies that the
-source files from which
-the target files should be built
-can be found in
-.IR src_dir .
-.I src_dir
-is interpreted relative to the directory
-of the calling SConscript file.
+'\" If
+'\" .IR variant_dir " and"
+'\" .IR src_dir " are both present,"
+'\" xxxxx everything is in a state of confusion.
+'\" .ES
+'\" SConscript(dirs = 'src', variant_dir = 'build', src_dir = '.')
+'\" runs src/SConscript in build/src, but
+'\" SConscript(dirs = 'lib', variant_dir = 'build', src_dir = 'src')
+'\" runs lib/SConscript (in lib!). However,
+'\" SConscript(dirs = 'src', variant_dir = 'build', src_dir = 'src')
+'\" runs src/SConscript in build. Moreover,
+'\" SConscript(dirs = 'src/lib', variant_dir = 'build', src_dir = 'src')
+'\" runs src/lib/SConscript in build/lib. Moreover,
+'\" SConscript(dirs = 'build/src/lib', variant_dir = 'build', src_dir = 'src')
+'\" can't find build/src/lib/SConscript, even though it ought to exist.
+'\" .EE
+'\" is equivalent to
+'\" .ES
+'\" ????????????????
+'\" .EE
+'\" and what about this alternative?
+'\"TODO??? SConscript('build/SConscript', src_dir='src')
-By default,
-.B scons
-will link or copy (depending on the platform)
-all the source files into the build directory.
-This behavior may be disabled by
-setting the optional
-.I duplicate
-argument to 0
-(it is set to 1 by default),
-in which case
-.B scons
-will refer directly to
-the source files in their source directory
-when building target files.
-(Setting
-.IR duplicate =0
-is usually safe, and always more efficient
-than the default of
-.IR duplicate =1,
-but it may cause build problems in certain end-cases,
-such as compiling from source files that
-are generated by the build.)
+Here are some composite examples:
-Any variables returned by
-.I script
-using
-.BR Return ()
-will be returned by the call to
-.BR SConscript ().
+.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
-Examples:
+.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
-SConscript('subdir/SConscript')
-foo = SConscript('sub/SConscript', exports='env')
-SConscript('dir/SConscript', exports=['env', 'variable'])
-SConscript('src/SConscript', build_dir='build', duplicate=0)
-SConscript('bld/SConscript', src_dir='src', exports='env variable')
-SConscript(dirs=['sub1', 'sub2'])
-SConscript(dirs=['sub3', 'sub4'], name='MySConscript')
+# 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
'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
(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:
+multiple times.
+
+Example:
.ES
env = Environment()
This tells
.B scons
to store all file signatures
-in the specified
+in the specified database
.IR file .
If the
.I file
-is omitted,
-.B .sconsign.dbm
+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,
.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
Examples:
.ES
-# Stores signatures in ".sconsign.dbm"
-# in the top-level SConstruct directory.
+# Explicitly stores signatures in ".sconsign.dblite"
+# in the top-level SConstruct directory (the
+# default behavior).
SConsignFile()
# Stores signatures in the file "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
'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.RI env.SetOption( name ", " value )
This function provides a way to set a select subset of the scons command
line options from a SConscript file. The options supported are:
+
+.RS 10
+.TP 6
.B clean
-which corresponds to -c, --clean, and --remove;
+which corresponds to -c, --clean and --remove;
+.TP 6
.B duplicate
-which
-corresponds to --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.
+which corresponds to -j and --jobs;
+.TP 6
+.B random
+which corresponds to --random; and
+.TP 6
+.B stack_size
+which corresponds to --stack-size.
+.RE
+
+.IP
See the documentation for the
corresponding command line object for information about each specific
-option. Example:
+option.
+
+Example:
.ES
SetOption('max_drift', 1)
Declares
.I side_effect
as a side effect of building
-.IR target .
-Both
-.I side_effect
+.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 that is created
+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.
+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
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 )
env.SourceCode('no_source.c', None)
.EE
'\"env.SourceCode('.', env.Subversion('file:///usr/local/Subversion'))
-'\"
+
+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.TP
+.RI env.subst( input ", [" raw ", " target ", " source ", " conv ])
+Performs construction variable interpolation
+on the specified string or sequence argument
+.IR input .
+
+By default,
+leading or trailing white space will
+be removed from the result.
+and all sequences of white space
+will be compressed to a single space character.
+Additionally, any
+.B $(
+and
+.B $)
+character sequences will be stripped from the returned string,
+The optional
+.I raw
+argument may be set to
+.B 1
+if you want to preserve white space and
+.BR $( - $)
+sequences.
+The
+.I raw
+argument may be set to
+.B 2
+if you want to strip
+all characters between
+any
+.B $(
+and
+.B $)
+pairs
+(as is done for signature calculation).
+
+If the input is a sequence
+(list or tuple),
+the individual elements of
+the sequence will be expanded,
+and the results will be returned as a list.
+
+The optional
+.I target
+and
+.I source
+keyword arguments
+must be set to lists of
+target and source nodes, respectively,
+if you want the
+.BR $TARGET ,
+.BR $TARGETS ,
+.BR $SOURCE
+and
+.BR $SOURCES
+to be available for expansion.
+This is usually necessary if you are
+calling
+.BR env.subst ()
+from within a Python function used
+as an SCons action.
+
+Returned string values or sequence elements
+are converted to their string representation by default.
+The optional
+.I conv
+argument
+may specify a conversion function
+that will be used in place of
+the default.
+For example, if you want Python objects
+(including SCons Nodes)
+to be returned as Python objects,
+you can use the Python
+.B lambda
+idiom to pass in an unnamed function
+that simply returns its unconverted argument.
+
+Example:
+
+.ES
+print env.subst("The C compiler is: $CC")
+
+def compile(target, source, env):
+ sourceDir = env.subst("${SOURCE.srcdir}",
+ target=target,
+ source=source)
+
+source_nodes = env.subst('$EXPAND_TO_NODELIST',
+ conv=lambda x: x)
+.EE
+
'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
'\".TP
'\".RI Subversion( repository ", " module )
'\"so that you only have to
'\"replicate part of the repository
'\"directory hierarchy in your
-'\"local build directory:
+'\"local build directory.
+'\"
+'\"Example:
'\"
'\".ES
'\"# Will fetch foo/bar/src.c
.RI SourceSignatures( type )
.TP
.RI env.SourceSignatures( type )
-This function tells SCons what type of signature to use for source files:
+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
used for all decisions
about whether targets are up-to-date.
-"MD5" means the signature of a source file
-is the MD5 checksum of its contents.
-"timestamp" means the signature of a source file
-is its timestamp (modification time).
+.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.
-"MD5" signatures take longer to compute,
-but are more accurate than "timestamp" signatures.
-The default is "MD5".
+
+.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
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")
""")
.EE
+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.TP
+.RI Tag( node ", " tags )
+Annotates file or directory Nodes with
+information about how the
+.BR Package ()
+Builder should package those files or directories.
+All tags are optional.
+
+Examples:
+
+.ES
+# makes sure the built library will be installed with 0644 file
+# access mode
+Tag( Library( 'lib.c' ), UNIX_ATTR="0644" )
+
+# marks file2.txt to be a documentation file
+Tag( 'file2.txt', DOC )
+.EE
+
'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.TP
.RI TargetSignatures( type )
.TP
.RI env.TargetSignatures( type )
-This function tells SCons what type of signatures to use
-for target files:
-.B "build"
+Note: Although it is not yet officially deprecated,
+use of this function is discouraged.
+See the
+.BR Decider ()
+function for a more flexible and straightforward way
+to configure SCons' decision-making.
+
+The
+.BR TargetSignatures ()
+function tells
+.B scons
+how to decide if a target file
+(a file that
+.I is
+built from any other files)
+has changed since the last time it
+was used to build some other target file.
+Legal values are
+.BR "build" ;
+.BR "content"
+(or its synonym
+.BR "MD5" );
+.BR "timestamp" ;
or
-.BR "content" .
+.BR "source" .
+
If the environment method is used,
-the specified type of signature is only 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
don't have an explicit target signature type
specified for their environments.
-"build" means the signature of a target file
-is made by concatenating all of the
-signatures of all its source files.
-"content" means the signature of a target
-file is an MD5 checksum of its contents.
-"build" signatures are usually faster to compute,
-but "content" signatures can prevent unnecessary rebuilds
+.B "content"
+(or its synonym
+.BR "MD5" )
+means
+.B scons
+decides that a target file has changed
+if the MD5 checksum of its contents has changed since
+the last time it was used to rebuild some other target file.
+This means
+.B scons
+will open up
+MD5 sum the contents
+of target files after they're built,
+and may decide that it does not need to rebuild
+"downstream" target files if a file was
+rebuilt with exactly the same contents as the last time.
+
+.B "timestamp"
+means
+.B scons
+decides that a target file has changed
+if its timestamp (modification time) has changed since
+the last time it was used to rebuild some other target file.
+(Note that although this is similar to the behavior of Make,
+by default it will also rebuild if the dependency is
+.I older
+than the last time it was used to rebuild the target file.)
+
+.B "source"
+means
+.B scons
+decides that a target file has changed
+as specified by the corresponding
+.BR SourceSignatures ()
+setting
+.BR "" ( "MD5"
+or
+.BR "timestamp" ).
+This means that
+.B scons
+will treat all input files to a target the same way,
+regardless of whether they are source files
+or have been built from other files.
+
+.B "build"
+means
+.B scons
+decides that a target file has changed
+if it has been rebuilt in this invocation
+or if its content or timestamp have changed
+as specified by the corresponding
+.BR SourceSignatures ()
+setting.
+This "propagates" the status of a rebuilt file
+so that other "downstream" target files
+will always be rebuilt,
+even if the contents or the timestamp
+have not changed.
+
+.B "build"
+signatures are fastest because
+.B "content"
+(or
+.BR "MD5" )
+signatures take longer to compute,
+but are more accurate than
+.B "timestamp"
+signatures,
+and can prevent unnecessary "downstream" rebuilds
when a target file is rebuilt to the exact same contents
as the previous build.
-The default is "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
.B generate()
method.
+Examples:
+
.ES
env = Environment(tools = [ Tool('msvc') ])
'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.TP
-.RI Value( value )
+.RI Value( value ", [" built_value ])
.TP
-.RI env.Value( value )
+.RI env.Value( value ", [" built_value ])
Returns a Node object representing the specified Python value. Value
-nodes can be used as dependencies of targets. If the result of
+Nodes can be used as dependencies of targets. If the result of
calling
.BR str( value )
changes between SCons runs, any targets depending on
.BR Value( value )
-will be rebuilt. When using timestamp source signatures, Value nodes'
-timestamps are equal to the system time when the node is created.
+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')
-env = Environment()
+
+# 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 WhereIs( program ", [" path ", " pathext ", " reject ])
-.TP
-.RI env.WhereIs( program ", [" path ", " pathext ", " reject ])
+.RI VariantDir( variant_dir ", " src_dir ", [" duplicate ])
+.TP
+.RI env.VariantDir( variant_dir ", " src_dir ", [" duplicate ])
+Use the
+.BR VariantDir ()
+function to create a copy of your sources in another location:
+if a name under
+.IR variant_dir
+is not found but exists under
+.IR src_dir ,
+the file or directory is copied to
+.IR variant_dir .
+Target files can be built in a different directory
+than the original sources by simply refering to the sources (and targets)
+within the variant tree.
+
+.BR VariantDir ()
+can be called multiple times with the same
+.I src_dir
+to set up multiple builds with different options
+.RI ( variants ).
+The
+.I src_dir
+location must be in or underneath the SConstruct file's directory, and
+.I variant_dir
+may not be underneath
+.IR src_dir .
+'\"TODO: Can the above restrictions be clarified or relaxed?
+'\"TODO: The latter restriction is clearly not completely right;
+'\"TODO: src_dir = '.' works fine with a build dir under it.
-Searches for the specified executable
-.I program,
-returning the full path name to the program
-if it is found,
-and returning None if not.
-Searches the specified
-.I path,
-the value of the calling environment's PATH
-(env['ENV']['PATH']),
-or the user's current external PATH
-(os.environ['PATH'])
+The default behavior is for
+.B scons
+to physically duplicate the source files in the variant tree.
+Thus, a build performed in the variant tree is guaranteed to be identical
+to a build performed in the source tree even if
+intermediate source files are generated during the build,
+or preprocessors or other scanners search for included files
+relative to the source file,
+or individual compilers or other invoked tools are hard-coded
+to put derived files in the same directory as source files.
+
+If possible on the platform,
+the duplication is performed by linking rather than copying;
+see also the
+.IR --duplicate
+command-line option.
+Moreover, only the files needed for the build are duplicated;
+files and directories that are not used are not present in
+.IR variant_dir .
+
+Duplicating the source tree may be disabled by setting the
+.I duplicate
+argument to 0 (zero).
+This will cause
+.B scons
+to invoke Builders using the path names of source files in
+.I src_dir
+and the path names of derived files within
+.IR variant_dir .
+This is always more efficient than
+.IR duplicate =1,
+and is usually safe for most builds
+(but see above for cases that may cause problems).
+
+Note that
+.BR VariantDir ()
+works most naturally with a subsidiary SConscript file.
+However, you would then call the subsidiary SConscript file
+not in the source directory, but in the
+.I variant_dir ,
+regardless of the value of
+.IR duplicate .
+This is how you tell
+.B scons
+which variant of a source tree to build:
+
+.ES
+# run src/SConscript in two variant directories
+VariantDir('build/variant1', 'src')
+SConscript('build/variant1/SConscript')
+VariantDir('build/variant2', 'src')
+SConscript('build/variant2/SConscript')
+.EE
+
+.IP
+See also the
+.BR SConscript ()
+function, described above,
+for another way to specify a variant directory
+in conjunction with calling a subsidiary SConscript file.
+
+Examples:
+
+.ES
+# use names in the build directory, not the source directory
+VariantDir('build', 'src', duplicate=0)
+Program('build/prog', 'build/source.c')
+.EE
+
+.ES
+# this builds both the source and docs in a separate subtree
+VariantDir('build', '.', duplicate=0)
+SConscript(dirs=['build/src','build/doc'])
+.EE
+
+.ES
+# same as previous example, but only uses SConscript
+SConscript(dirs='src', variant_dir='build/src', duplicate=0)
+SConscript(dirs='doc', variant_dir='build/doc', duplicate=0)
+.EE
+
+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.TP
+.RI WhereIs( program ", [" path ", " pathext ", " reject ])
+.TP
+.RI env.WhereIs( program ", [" path ", " pathext ", " reject ])
+
+Searches for the specified executable
+.I program,
+returning the full path name to the program
+if it is found,
+and returning None if not.
+Searches the specified
+.I path,
+the value of the calling environment's PATH
+(env['ENV']['PATH']),
+or the user's current external PATH
+(os.environ['PATH'])
by default.
-On Win32 systems, searches for executable
+On Windows systems, searches for executable
programs with any of the file extensions
listed in the specified
.I pathext,
.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]
.B ARGUMENTS
dictionary.
+Example:
+
.ES
if ARGUMENTS.get('debug', 0):
env = Environment(CCFLAGS = '-g')
list, below,
for additional information.
+Example:
+
.ES
if 'foo' in BUILD_TARGETS:
print "Don't forget to test the `foo' program!"
This can be used, for example,
to take specific actions only
when a certain target or targets
-is explicitly being built:
+is explicitly being built.
+
+Example:
.ES
if 'foo' in COMMAND_LINE_TARGETS:
.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):
.\" 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
can be defined by the user. The following is a list of the automatically
defined construction variables:
-.IP AR
-The static library archiver.
-
-.IP ARCOM
-The command line used to generate a static library from object files.
-
-.IP ARCOMSTR
-The string displayed when an object file
-is generated from an assembly-language source file.
-If this is not set, then $ARCOM (the command line) is displayed.
-
-.ES
-env = Environment(ARCOMSTR = "Archiving $TARGET")
-.EE
-
-.IP ARFLAGS
-General options passed to the static library archiver.
-
-.IP AS
-The assembler.
-
-.IP ASCOM
-The command line used to generate an object file
-from an assembly-language source file.
-
-.IP ASCOMSTR
-The string displayed when an object file
-is generated from an assembly-language source file.
-If this is not set, then $ASCOM (the command line) is displayed.
-
-.ES
-env = Environment(ASCOMSTR = "Assembling $TARGET")
-.EE
-
-.IP ASFLAGS
-General options passed to the assembler.
-
-.IP ASPPCOM
-The command line used to assemble an assembly-language
-source file into an object file
-after first running the file through the C preprocessor.
-Any options specified in the $ASFLAGS and $CPPFLAGS construction variables
-are included on this command line.
-
-.IP ASPPCOMSTR
-The string displayed when an object file
-is generated from an assembly-language source file
-after first running the file through the C preprocessor.
-If this is not set, then $ASPPCOM (the command line) is displayed.
-
-.ES
-env = Environment(ASPPCOMSTR = "Assembling $TARGET")
-.EE
-
-.IP ASPPFLAGS
-General options when an assembling an assembly-language
-source file into an object file
-after first running the file through the C preprocessor.
-The default is to use the value of $ASFLAGS.
-
-.IP BIBTEX
-The bibliography generator for the TeX formatter and typesetter and the
-LaTeX structured formatter and typesetter.
-
-.IP BIBTEXCOM
-The command line used to call the bibliography generator for the
-TeX formatter and typesetter and the LaTeX structured formatter and
-typesetter.
-
-.IP BIBTEXCOMSTR
-The string displayed when generating a bibliography
-for TeX or LaTeX.
-If this is not set, then $BIBTEXCOM (the command line) is displayed.
-
-.ES
-env = Environment(BIBTEXCOMSTR = "Generating bibliography $TARGET")
-.EE
-
-
-.IP BIBTEXFLAGS
-General options passed to the bibliography generator for the TeX formatter
-and typesetter and the LaTeX structured formatter and typesetter.
-
-.IP BITKEEPER
-The BitKeeper executable.
-
-.IP BITKEEPERCOM
-The command line for
-fetching source files using BitKeeper.
-
-.IP BITKEEPERCOMSTR
-The string displayed when fetching
-a source file using BitKeeper.
-If this is not set, then $BITKEEPERCOM
-(the command line) is displayed.
-
-.IP BITKEEPERGET
-The command ($BITKEEPER) and subcommand
-for fetching source files using BitKeeper.
-
-.IP BITKEEPERGETFLAGS
-Options that are passed to the BitKeeper
-.B get
-subcommand.
-
-.IP BUILDERS
-A dictionary mapping the names of the builders
-available through this environment
-to underlying Builder objects.
-Builders named
-Alias, CFile, CXXFile, DVI, Library, Object, PDF, PostScript, and Program
-are available by default.
-If you initialize this variable when an
-Environment is created:
-
-.ES
-env = Environment(BUILDERS = {'NewBuilder' : foo})
-.EE
-.IP
-the default Builders will no longer be available.
-To use a new Builder object in addition to the default Builders,
-add your new Builder object like this:
+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+'\" BEGIN GENERATED CONSTRUCTION VARIABLE DESCRIPTIONS
+'\"
+'\" The descriptions below of the various SCons construction variables
+'\" are generated from the .xml files that live next to the various
+'\" Python modules in the build enginer library. If you're reading
+'\" this [gnt]roff file with an eye towards patching this man page,
+'\" you can still submit a diff against this text, but it will have to
+'\" be translated to a diff against the underlying .xml file before the
+'\" patch is actually accepted. If you do that yourself, it will make
+'\" it easier to integrate the patch.
+'\"
+'\" BEGIN GENERATED CONSTRUCTION VARIABLE DESCRIPTIONS
+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.so variables.man
+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+'\" END GENERATED CONSTRUCTION VARIABLE DESCRIPTIONS
+'\"
+'\" The descriptions above of the various SCons construction variables
+'\" are generated from the .xml files that live next to the various
+'\" Python modules in the build enginer library. If you're reading
+'\" this [gnt]roff file with an eye towards patching this man page,
+'\" you can still submit a diff against this text, but it will have to
+'\" be translated to a diff against the underlying .xml file before the
+'\" patch is actually accepted. If you do that yourself, it will make
+'\" it easier to integrate the patch.
+'\"
+'\" END GENERATED CONSTRUCTION VARIABLE DESCRIPTIONS
+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.ES
-env = Environment()
-env.Append(BUILDERS = {'NewBuilder' : foo})
-.EE
-.IP
-or this:
+.LP
+Construction variables can be retrieved and set using the
+.B Dictionary
+method of the construction environment:
.ES
-env = Environment()
-env['BUILDERS]['NewBuilder'] = foo
+dict = env.Dictionary()
+dict["CC"] = "cc"
.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 $CCFLAGS and $CPPFLAGS construction variables
-are included on this command line.
-
-.IP CCCOMSTR
-The string displayed when a C source file
-is compiled to a (static) object file.
-If this is not set, then $CCCOM (the command line) is displayed.
+or using the [] operator:
.ES
-env = Environment(CCCOMSTR = "Compiling static object $TARGET")
+env["CC"] = "cc"
.EE
-.IP CCFLAGS
-General options that are passed to the C compiler.
-
-.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
-.I .c
-(lower case).
-On case-insensitive systems (like Win32),
-SCons also treats
-.I .C
-(upper case) files
-as C files.
-
-.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 _concat
-A function used to produce variables like $_CPPINCFLAGS. It takes
-four or five
-arguments: a prefix to concatenate onto each element, a list of
-elements, a suffix to concatenate onto each element, an environment
-for variable interpolation, and an optional function that will be
-called to transform the list before concatenation.
+Construction variables can also be passed to the construction environment
+constructor:
.ES
-env['_CPPINCFLAGS'] = '$( ${_concat(INCPREFIX, CPPPATH, INCSUFFIX, __env__, RDirs)} $)',
+env = Environment(CC="cc")
.EE
-.IP CPPDEFINES
-A platform independent specification of C preprocessor definitions.
-The definitions will be added to command lines
-through the automatically-generated
-$_CPPDEFFLAGS construction variable (see below),
-which is constructed according to
-the type of value of $CPPDEFINES:
-
-.IP
-If $CPPDEFINES is a string,
-the values of the
-$CPPDEFPREFIX and $CPPDEFSUFFIX
-construction variables
-will be added to the beginning and end.
+or when copying a construction environment using the
+.B Clone
+method:
.ES
-# Will add -Dxyz to POSIX compiler command lines,
-# and /Dxyz to Microsoft Visual C++ command lines.
-env = Environment(CPPDEFINES='xyz')
+env2 = env.Clone(CC="cl.exe")
.EE
-.IP
-If $CPPDEFINES is a list,
-the values of the
-$CPPDEFPREFIX and $CPPDEFSUFFIX
-construction variables
-will be appended to the beginning and end
-of each element in the list.
-If any element is a list or tuple,
-then the first item is the name being
-defined and the second item is its value:
-
-.ES
-# Will add -DB=2 -DA to POSIX compiler command lines,
-# and /DB=2 /DA to Microsoft Visual C++ command lines.
-env = Environment(CPPDEFINES=[('B', 2), 'A'])
-.EE
+.SS Configure Contexts
-.IP
-If $CPPDEFINES is a dictionary,
-the values of the
-$CPPDEFPREFIX and $CPPDEFSUFFIX
-construction variables
-will be appended to the beginning and end
-of each item from the dictionary.
-The key of each dictionary item
-is a name being defined
-to the dictionary item's corresponding value;
-if the value is
-.BR None ,
-then the name is defined without an explicit value.
-Note that the resulting flags are sorted by keyword
-to ensure that the order of the options on the
-command line is consistent each time
.B scons
- is run.
-
-.ES
-# Will add -DA -DB=2 to POSIX compiler command lines,
-# and /DA /DB=2 to Microsoft Visual C++ command lines.
-env = Environment(CPPDEFINES={'B':2, 'A':None})
-.EE
-
-.IP _CPPDEFFLAGS
-An automatically-generated construction variable
-containing the C preprocessor command-line options
-to define values.
-The value of $_CPPDEFFLAGS is created
-by appending $CPPDEFPREFIX and $CPPDEFSUFFIX
-to the beginning and end
-of each directory in $CPPDEFINES.
-
-.IP CPPDEFPREFIX
-The prefix used to specify preprocessor definitions
-on the C compiler command line.
-This will be appended to the beginning of each definition
-in the $CPPDEFINES construction variable
-when the $_CPPDEFFLAGS variable is automatically generated.
-
-.IP CPPDEFSUFFIX
-The suffix used to specify preprocessor definitions
-on the C compiler command line.
-This will be appended to the end of each definition
-in the $CPPDEFINES construction variable
-when the $_CPPDEFFLAGS variable is automatically generated.
-
-.IP CPPFLAGS
-User-specified C preprocessor options.
-These will be included in any command that uses the C preprocessor,
-including not just compilation of C and C++ source files
-via the $CCCOM, $SHCCCOM, $CXXCOM and $SHCXXCOM command lines,
-but also the $FORTRANPPCOM, $SHFORTRANPPCOM,
-$F77PPCOM and $SHF77PPCOM command lines
-used to compile a Fortran source file,
-and the $ASPPCOM command line
-used to assemble an assembly language source file,
-after first running each file through the C preprocessor.
-Note that this variable does
-.I not
-contain
-.B -I
-(or similar) include search path options
-that scons generates automatically from $CPPPATH.
-See
-.BR _CPPINCFLAGS ,
-below,
-for the variable that expands to those options.
-
-.IP _CPPINCFLAGS
-An automatically-generated construction variable
-containing the C preprocessor command-line options
-for specifying directories to be searched for include files.
-The value of $_CPPINCFLAGS is created
-by appending $INCPREFIX and $INCSUFFIX
-to the beginning and end
-of each directory in $CPPPATH.
-
-.IP CPPPATH
-The list of directories that the C preprocessor will search for include
-directories. The C/C++ implicit dependency scanner will search these
-directories for include files. Don't explicitly put include directory
-arguments in CCFLAGS or CXXFLAGS because the result will be non-portable
-and the directories will not be searched by the dependency scanner. Note:
-directory names in CPPPATH will be looked-up relative to the SConscript
-directory when they are used in a command. To force
+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
-to look-up a directory relative to the root of the source tree use #:
-
-.ES
-env = Environment(CPPPATH='#/include')
-.EE
+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.
-.IP
-The directory look-up can also be forced using the
-.BR Dir ()
-function:
+The following methods can be used to perform checks:
-.ES
-include = Dir('include')
-env = Environment(CPPPATH=include)
-.EE
+.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.
-.IP
-The directory list will be added to command lines
-through the automatically-generated
-$_CPPINCFLAGS
-construction variable,
-which is constructed by
-appending the values of the
-$INCPREFIX and $INCSUFFIX
-construction variables
-to the beginning and end
-of each directory in $CPPPATH.
-Any command lines you define that need
-the CPPPATH directory list should
-include $_CPPINCFLAGS:
-
-.ES
-env = Environment(CCCOM="my_compiler $_CPPINCFLAGS -c -o $TARGET $SOURCE")
-.EE
-
-.IP CPPSUFFIXES
-The list of suffixes of files that will be scanned
-for C preprocessor implicit dependencies
-(#include lines).
-The default list is:
-
-.ES
-[".c", ".C", ".cxx", ".cpp", ".c++", ".cc",
- ".h", ".H", ".hxx", ".hpp", ".hh",
- ".F", ".fpp", ".FPP",
- ".m", ".mm",
- ".S", ".spp", ".SPP"]
-.EE
-
-.IP CVS
-The CVS executable.
-
-.IP CVSCOFLAGS
-Options that are passed to the CVS checkout subcommand.
-
-.IP CVSCOM
-The command line used to
-fetch source files from a CVS repository.
-
-.IP CVSCOMSTR
-The string displayed when fetching
-a source file from a CVS repository.
-If this is not set, then $CVSCOM
-(the command line) is displayed.
-
-.IP CVSFLAGS
-General options that are passed to CVS.
-By default, this is set to
-"-d $CVSREPOSITORY"
-to specify from where the files must be fetched.
-
-.IP CVSREPOSITORY
-The path to the CVS repository.
-This is referenced in the default
-$CVSFLAGS value.
-
-.IP CXX
-The C++ compiler.
-
-.IP 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
-.IR .cc .
-SCons also treats files with the suffixes
-.IR .cpp ,
-.IR .cxx ,
-.IR .c++ ,
+The optional
+.B clean
and
-.I .C++
-as C++ files,
-and files with
-.I .mm
-suffixes as Objective C++ files.
-On case-sensitive systems (Linux, UNIX, and other POSIX-alikes),
-SCons also treats
-.I .C
-(upper case) files
-as C++ files.
-
-.IP CXXCOM
-The command line used to compile a C++ source file to an object file.
-Any options specified in the $CXXFLAGS and $CPPFLAGS construction variables
-are included on this command line.
-
-.IP CXXCOMSTR
-The string displayed when a C++ source file
-is compiled to a (static) object file.
-If this is not set, then $CXXCOM (the command line) is displayed.
+.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.
-.ES
-env = Environment(CXXCOMSTR = "Compiling static object $TARGET")
.EE
+A created
+.B Configure
+instance has the following associated methods:
-.IP CXXFLAGS
-General options that are passed to the C++ compiler.
-By default, this includes the value of $CCFLAGS,
-so that setting $CCFLAGS affects both C and C++ compilation.
-If you want to add C++-specific flags,
-you must set or override the value of $CXXFLAGS.
-
-.IP CXXVERSION
-The version number of the C++ compiler.
-This may or may not be set,
-depending on the specific C++ compiler being used.
-
-.IP Dir
-A function that converts a file name into a Dir instance 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:
+.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.
-.ES
-['.d']
-.EE
+The following Checks are predefined.
+(This list will likely grow larger as time
+goes by and developers contribute new useful tests.)
-.IP DVIPDF
-The TeX DVI file to PDF file converter.
-
-.IP DVIPDFFLAGS
-General options passed to the TeX DVI file to PDF file converter.
-
-.IP DVIPDFCOM
-The command line used to convert TeX DVI files into a PDF file.
-
-.IP DVIPDFCOMSTR
-The string displayed when a TeX DVI file
-is converted into a PDF file.
-If this is not set, then $DVIPDFCOM (the command line) is displayed.
-
-.IP DVIPS
-The TeX DVI file to PostScript converter.
-
-.IP DVIPSFLAGS
-General options passed to the TeX DVI file to PostScript converter.
-
-.IP ENV
-A dictionary of environment variables
-to use when invoking commands. When ENV is used in a command all list
-values will be joined using the path separator and any other non-string
-values will simply be coerced to a string.
-Note that, by default,
-.B scons
-does
-.I not
-propagate the environment in force when you
-execute
-.B scons
-to the commands used to build target files.
-This is so that builds will be guaranteed
-repeatable regardless of the environment
-variables set at the time
-.B scons
-is invoked.
-
-If you want to propagate your
-environment variables
-to the commands executed
-to build target files,
-you must do so explicitly:
-
-.ES
-import os
-env = Environment(ENV = os.environ)
-.EE
-
-.RS
-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):
-.RE
-
-.ES
-import os
-env = Environment(ENV = {'PATH' : os.environ['PATH']})
-.EE
-
-.IP ESCAPE
-A function that will be called to escape shell special characters in
-command lines. The function should take one argument: the command line
-string to escape; and should return the escaped command line.
-
-.IP F77
-The Fortran 77 compiler.
-You should normally set the $FORTRAN variable,
-which specifies the default Fortran compiler
-for all Fortran versions.
-You only need to set $F77 if you need to use a specific compiler
-or compiler version for Fortran 77 files.
-
-.IP F77COM
-The command line used to compile a Fortran 77 source file to an object file.
-You only need to set $F77COM if you need to use a specific
-command line for Fortran 77 files.
-You should normally set the $FORTRANCOM variable,
-which specifies the default command line
-for all Fortran versions.
-
-.IP F77COMSTR
-The string displayed when a Fortran 77 source file
-is compiled to an object file.
-If this is not set, then $F77COM or $FORTRANCOM (the command line) is displayed.
-
-.IP F77FLAGS
-General user-specified options that are passed to the Fortran 77 compiler.
-Note that this variable does
-.I not
-contain
-.B -I
-(or similar) include search path options
-that scons generates automatically from $F77PATH.
-See
-.BR _F77INCFLAGS ,
-below,
-for the variable that expands to those options.
-You only need to set $F77FLAGS if you need to define specific
-user options for Fortran 77 files.
-You should normally set the $FORTRANFLAGS variable,
-which specifies the user-specified options
-passed to the default Fortran compiler
-for all Fortran versions.
-
-.IP _F77INCFLAGS
-An automatically-generated construction variable
-containing the Fortran 77 compiler command-line options
-for specifying directories to be searched for include files.
-The value of $_F77INCFLAGS is created
-by appending $INCPREFIX and $INCSUFFIX
-to the beginning and end
-of each directory in $F77PATH.
-
-.IP F77PATH
-The list of directories that the Fortran 77 compiler will search for include
-directories. The implicit dependency scanner will search these
-directories for include files. Don't explicitly put include directory
-arguments in $F77FLAGS because the result will be non-portable
-and the directories will not be searched by the dependency scanner. Note:
-directory names in $F77PATH will be looked-up relative to the SConscript
-directory when they are used in a command. To force
-.B scons
-to look-up a directory relative to the root of the source tree use #:
-You only need to set $F77PATH if you need to define a specific
-include path for Fortran 77 files.
-You should normally set the $FORTRANPATH variable,
-which specifies the include path
-for the default Fortran compiler
-for all Fortran versions.
-
-.ES
-env = Environment(F77PATH='#/include')
-.EE
-
-.IP
-The directory look-up can also be forced using the
-.BR Dir ()
-function:
-
-.ES
-include = Dir('include')
-env = Environment(F77PATH=include)
-.EE
-
-.IP
-The directory list will be added to command lines
-through the automatically-generated
-$_F77INCFLAGS
-construction variable,
-which is constructed by
-appending the values of the
-$INCPREFIX and $INCSUFFIX
-construction variables
-to the beginning and end
-of each directory in $F77PATH.
-Any command lines you define that need
-the F77PATH directory list should
-include $_F77INCFLAGS:
-
-.ES
-env = Environment(F77COM="my_compiler $_F77INCFLAGS -c -o $TARGET $SOURCE")
-.EE
-
-.IP F77PPCOM
-The command line used to compile a Fortran 77 source file to an object file
-after first running the file through the C preprocessor.
-Any options specified in the $F77FLAGS and $CPPFLAGS construction variables
-are included on this command line.
-You only need to set $F77PPCOM if you need to use a specific
-C-preprocessor command line for Fortran 77 files.
-You should normally set the $FORTRANPPCOM variable,
-which specifies the default C-preprocessor command line
-for all Fortran versions.
-
-.IP F90
-The Fortran 90 compiler.
-You should normally set the $FORTRAN variable,
-which specifies the default Fortran compiler
-for all Fortran versions.
-You only need to set $F90 if you need to use a specific compiler
-or compiler version for Fortran 90 files.
-
-.IP F90COM
-The command line used to compile a Fortran 90 source file to an object file.
-You only need to set $F90COM if you need to use a specific
-command line for Fortran 90 files.
-You should normally set the $FORTRANCOM variable,
-which specifies the default command line
-for all Fortran versions.
-
-.IP F90COMSTR
-The string displayed when a Fortran 90 source file
-is compiled to an object file.
-If this is not set, then $F90COM or $FORTRANCOM
-(the command line) is displayed.
-
-.IP F90FLAGS
-General user-specified options that are passed to the Fortran 90 compiler.
-Note that this variable does
-.I not
-contain
-.B -I
-(or similar) include search path options
-that scons generates automatically from $F90PATH.
-See
-.BR _F90INCFLAGS ,
-below,
-for the variable that expands to those options.
-You only need to set $F90FLAGS if you need to define specific
-user options for Fortran 90 files.
-You should normally set the $FORTRANFLAGS variable,
-which specifies the user-specified options
-passed to the default Fortran compiler
-for all Fortran versions.
-
-.IP _F90INCFLAGS
-An automatically-generated construction variable
-containing the Fortran 90 compiler command-line options
-for specifying directories to be searched for include files.
-The value of $_F90INCFLAGS is created
-by appending $INCPREFIX and $INCSUFFIX
-to the beginning and end
-of each directory in $F90PATH.
-
-.IP F90PATH
-The list of directories that the Fortran 90 compiler will search for include
-directories. The implicit dependency scanner will search these
-directories for include files. Don't explicitly put include directory
-arguments in $F90FLAGS because the result will be non-portable
-and the directories will not be searched by the dependency scanner. Note:
-directory names in $F90PATH will be looked-up relative to the SConscript
-directory when they are used in a command. To force
-.B scons
-to look-up a directory relative to the root of the source tree use #:
-You only need to set $F90PATH if you need to define a specific
-include path for Fortran 90 files.
-You should normally set the $FORTRANPATH variable,
-which specifies the include path
-for the default Fortran compiler
-for all Fortran versions.
-
-.ES
-env = Environment(F90PATH='#/include')
-.EE
-
-.IP
-The directory look-up can also be forced using the
-.BR Dir ()
-function:
-
-.ES
-include = Dir('include')
-env = Environment(F90PATH=include)
-.EE
-
-.IP
-The directory list will be added to command lines
-through the automatically-generated
-$_F90INCFLAGS
-construction variable,
-which is constructed by
-appending the values of the
-$INCPREFIX and $INCSUFFIX
-construction variables
-to the beginning and end
-of each directory in $F90PATH.
-Any command lines you define that need
-the F90PATH directory list should
-include $_F90INCFLAGS:
-
-.ES
-env = Environment(F90COM="my_compiler $_F90INCFLAGS -c -o $TARGET $SOURCE")
-.EE
-
-.IP F90PPCOM
-The command line used to compile a Fortran 90 source file to an object file
-after first running the file through the C preprocessor.
-Any options specified in the $F90FLAGS and $CPPFLAGS construction variables
-are included on this command line.
-You only need to set $F90PPCOM if you need to use a specific
-C-preprocessor command line for Fortran 90 files.
-You should normally set the $FORTRANPPCOM variable,
-which specifies the default C-preprocessor command line
-for all Fortran versions.
-
-.IP F95
-The Fortran 95 compiler.
-You should normally set the $FORTRAN variable,
-which specifies the default Fortran compiler
-for all Fortran versions.
-You only need to set $F95 if you need to use a specific compiler
-or compiler version for Fortran 95 files.
-
-.IP F95COM
-The command line used to compile a Fortran 95 source file to an object file.
-You only need to set $F95COM if you need to use a specific
-command line for Fortran 95 files.
-You should normally set the $FORTRANCOM variable,
-which specifies the default command line
-for all Fortran versions.
-
-.IP F95COMSTR
-The string displayed when a Fortran 95 source file
-is compiled to an object file.
-If this is not set, then $F95COM or $FORTRANCOM
-(the command line) is displayed.
-
-.IP F95FLAGS
-General user-specified options that are passed to the Fortran 95 compiler.
-Note that this variable does
-.I not
-contain
-.B -I
-(or similar) include search path options
-that scons generates automatically from $F95PATH.
-See
-.BR _F95INCFLAGS ,
-below,
-for the variable that expands to those options.
-You only need to set $F95FLAGS if you need to define specific
-user options for Fortran 95 files.
-You should normally set the $FORTRANFLAGS variable,
-which specifies the user-specified options
-passed to the default Fortran compiler
-for all Fortran versions.
-
-.IP _F95INCFLAGS
-An automatically-generated construction variable
-containing the Fortran 95 compiler command-line options
-for specifying directories to be searched for include files.
-The value of $_F95INCFLAGS is created
-by appending $INCPREFIX and $INCSUFFIX
-to the beginning and end
-of each directory in $F95PATH.
-
-.IP F95PATH
-The list of directories that the Fortran 95 compiler will search for include
-directories. The implicit dependency scanner will search these
-directories for include files. Don't explicitly put include directory
-arguments in $F95FLAGS because the result will be non-portable
-and the directories will not be searched by the dependency scanner. Note:
-directory names in $F95PATH will be looked-up relative to the SConscript
-directory when they are used in a command. To force
-.B scons
-to look-up a directory relative to the root of the source tree use #:
-You only need to set $F95PATH if you need to define a specific
-include path for Fortran 95 files.
-You should normally set the $FORTRANPATH variable,
-which specifies the include path
-for the default Fortran compiler
-for all Fortran versions.
-
-.ES
-env = Environment(F95PATH='#/include')
-.EE
-
-.IP
-The directory look-up can also be forced using the
-.BR Dir ()
-function:
-
-.ES
-include = Dir('include')
-env = Environment(F95PATH=include)
-.EE
-
-.IP
-The directory list will be added to command lines
-through the automatically-generated
-$_F95INCFLAGS
-construction variable,
-which is constructed by
-appending the values of the
-$INCPREFIX and $INCSUFFIX
-construction variables
-to the beginning and end
-of each directory in $F95PATH.
-Any command lines you define that need
-the F95PATH directory list should
-include $_F95INCFLAGS:
-
-.ES
-env = Environment(F95COM="my_compiler $_F95INCFLAGS -c -o $TARGET $SOURCE")
-.EE
-
-.IP F95PPCOM
-The command line used to compile a Fortran 95 source file to an object file
-after first running the file through the C preprocessor.
-Any options specified in the $F95FLAGS and $CPPFLAGS construction variables
-are included on this command line.
-You only need to set $F95PPCOM if you need to use a specific
-C-preprocessor command line for Fortran 95 files.
-You should normally set the $FORTRANPPCOM variable,
-which specifies the default C-preprocessor command line
-for all Fortran versions.
-
-.IP FORTRAN
-The default Fortran compiler
-for all versions of Fortran.
-
-.IP FORTRANCOM
-The command line used to compile a Fortran source file to an object file.
-By default, any options specified
-in the $FORTRANFLAGS, $CPPFLAGS, $_CPPDEFFLAGS,
-$_FORTRANMODFLAG, and $_FORTRANINCFLAGS construction variables
-are included on this command line.
-
-.IP FORTRANCOMSTR
-The string displayed when a Fortran source file
-is compiled to an object file.
-If this is not set, then $FORTRANCOM
-(the command line) is displayed.
-
-.IP FORTRANFLAGS
-General user-specified options that are passed to the Fortran compiler.
-Note that this variable does
-.I not
-contain
-.B -I
-(or similar) include or module search path options
-that scons generates automatically from $FORTRANPATH.
-See
-.BR _FORTRANINCFLAGS and _FORTRANMODFLAGS,
-below,
-for the variables that expand those options.
-
-.IP _FORTRANINCFLAGS
-An automatically-generated construction variable
-containing the Fortran compiler command-line options
-for specifying directories to be searched for include
-files and module files.
-The value of $_FORTRANINCFLAGS is created
-by prepending/appending $INCPREFIX and $INCSUFFIX
-to the beginning and end
-of each directory in $FORTRANPATH.
-
-.IP FORTRANMODDIR
-Directory location where the Fortran compiler should place
-any module files it generates. This variable is empty, by default. Some
-Fortran compilers will internally append this directory in the search path
-for module files, as well
-
-.IP FORTRANMODDIRPREFIX
-The prefix used to specify a module directory on the Fortran compiler command
-line.
-This will be appended to the beginning of the directory
-in the $FORTRANMODDIR construction variables
-when the $_FORTRANMODFLAG variables is automatically generated.
-
-.IP FORTRANMODDIRSUFFIX
-The suffix used to specify a module directory on the Fortran compiler command
-line.
-This will be appended to the beginning of the directory
-in the $FORTRANMODDIR construction variables
-when the $_FORTRANMODFLAG variables is automatically generated.
-
-.IP FORTRANMODFLAG
-An automatically-generated construction variable
-containing the Fortran compiler command-line option
-for specifying the directory location where the Fortran
-compiler should place any module files that happen to get
-generated during compilation.
-The value of $_FORTRANMODFLAG is created
-by prepending/appending $FORTRANMODDIRPREFIX and $FORTRANMODDIRSUFFIX
-to the beginning and end of the directory in $FORTRANMODDIR.
-
-.IP FORTRANMODPREFIX
-The module file prefix used by the Fortran compiler. SCons assumes that
-the Fortran compiler follows the quasi-standard naming convention for
-module files of
-.I <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
-.I <module_name>.mod.
-As a result, this variable is set to ".mod", by default. For situations
-in which the compiler does not necessarily follow the normal convention,
-the user may use this variable. Its value will be appended to every
-module file name as scons attempts to resolve dependencies.
-
-.IP FORTRANPATH
-The list of directories that the Fortran compiler will search for
-include files and (for some compilers) module files. The Fortran implicit
-dependency scanner will search these directories for include files (but
-not module files since they are autogenerated and, as such, may not
-actually exist at the time the scan takes place). Don't explicitly put
-include directory arguments in FORTRANFLAGS because the result will be
-non-portable and the directories will not be searched by the dependency
-scanner. Note: directory names in FORTRANPATH will be looked-up relative
-to the SConscript directory when they are used in a command. To force
-.B scons
-to look-up a directory relative to the root of the source tree use #:
-
-.ES
-env = Environment(FORTRANPATH='#/include')
-.EE
-
-.IP
-The directory look-up can also be forced using the
-.BR Dir ()
-function:
-
-.ES
-include = Dir('include')
-env = Environment(FORTRANPATH=include)
-.EE
-
-.IP
-The directory list will be added to command lines
-through the automatically-generated
-$_FORTRANINCFLAGS
-construction variable,
-which is constructed by
-appending the values of the
-$INCPREFIX and $INCSUFFIX
-construction variables
-to the beginning and end
-of each directory in $FORTRANPATH.
-Any command lines you define that need
-the FORTRANPATH directory list should
-include $_FORTRANINCFLAGS:
-
-.ES
-env = Environment(FORTRANCOM="my_compiler $_FORTRANINCFLAGS -c -o $TARGET $SOURCE")
-.EE
-
-.IP FORTRANPPCOM
-The command line used to compile a Fortran source file to an object file
-after first running the file through the C preprocessor.
-By default, any options specified in the $FORTRANFLAGS, $CPPFLAGS,
-_CPPDEFFLAGS, $_FORTRANMODFLAG, and $_FORTRANINCFLAGS
-construction variables are included on this command line.
-
-.IP FORTRANSUFFIXES
-The list of suffixes of files that will be scanned
-for Fortran implicit dependencies
-(INCLUDE lines & USE statements).
-The default list is:
-
-.ES
-[".f", ".F", ".for", ".FOR", ".ftn", ".FTN", ".fpp", ".FPP",
-".f77", ".F77", ".f90", ".F90", ".f95", ".F95"]
-.EE
-
-.IP File
-A function that converts a file name into a File instance relative to the
-target being built.
-
-.IP FRAMEWORKSFLAGS
-On Mac OS X,
-frameworks options to be added at
-the end of a command
-line building a loadable module.
-
-.IP GS
-The Ghostscript program used to convert PostScript to PDF files.
-
-.IP GSFLAGS
-General options passed to the Ghostscript program
-when converting PostScript to PDF files.
-
-.IP GSCOM
-The Ghostscript command line used to convert PostScript to PDF files.
-
-.IP GSCOMSTR
-The string displayed when
-Ghostscript is used to convert
-a PostScript file to a PDF file.
-If this is not set, then $GSCOM (the command line) is displayed.
-
-.IP 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 INCPREFIX
-The prefix used to specify an include directory on the C compiler command
-line.
-This will be appended to the beginning of each directory
-in the $CPPPATH and $FORTRANPATH construction variables
-when the $_CPPINCFLAGS and $_FORTRANINCFLAGS
-variables are automatically generated.
-
-.IP INCSUFFIX
-The suffix used to specify an include directory on the C compiler command
-line.
-This will be appended to the end of each directory
-in the $CPPPATH and $FORTRANPATH construction variables
-when the $_CPPINCFLAGS and $_FORTRANINCFLAGS
-variables are automatically generated.
-
-.IP INSTALL
-A function to be called to install a file into a
-destination file name.
-The default function copies the file into the destination
-(and sets the destination file's mode and permission bits
-to match the source file's).
-The function takes the following arguments:
-
-.ES
-def install(dest, source, env):
-.EE
-.IP
-.I dest
-is the path name of the destination file.
-.I source
-is the path name of the source file.
-.I env
-is the construction environment
-(a dictionary of construction values)
-in force for this file installation.
-
-.IP INTEL_C_COMPILER_VERSION
-Set by the "intelc" Tool
-to the major version number of the Intel C compiler
-selected for use.
-
-.IP JAR
-The Java archive tool.
-
-.IP JARCHDIR
-The directory to which the Java archive tool should change
-(using the
-.B \-C
-option).
-
-.IP JARCOM
-The command line used to call the Java archive tool.
-
-.IP JARCOMSTR
-The string displayed when the Java archive tool
-is called
-If this is not set, then $JARCOM (the command line) is displayed.
-
-.ES
-env = Environment(JARCOMSTR = "JARchiving $SOURCES into $TARGET")
-.EE
-
-.IP JARFLAGS
-General options passed to the Java archive tool.
-By default this is set to
-.B cf
-to create the necessary
-.I jar
-file.
-
-.IP JARSUFFIX
-The suffix for Java archives:
-.B .jar
-by default.
-
-.IP JAVAC
-The Java compiler.
-
-.IP JAVACCOM
-The command line used to compile a directory tree containing
-Java source files to
-corresponding Java class files.
-Any options specified in the $JAVACFLAGS construction variable
-are included on this command line.
-
-.IP JAVACCOMSTR
-The string displayed when compiling
-a directory tree of Java source files to
-corresponding Java class files.
-If this is not set, then $JAVACCOM (the command line) is displayed.
-
-.ES
-env = Environment(JAVACCOMSTR = "Compiling class files $TARGETS from $SOURCES")
-.EE
-
-.IP JAVACFLAGS
-General options that are passed to the Java compiler.
-
-.IP JAVACLASSDIR
-The directory in which Java class files may be found.
-This is stripped from the beginning of any Java .class
-file names supplied to the
-.B JavaH
-builder.
-
-.IP JAVACLASSSUFFIX
-The suffix for Java class files;
-.B .class
-by default.
-
-.IP JAVAH
-The Java generator for C header and stub files.
-
-.IP JAVAHCOM
-The command line used to generate C header and stub files
-from Java classes.
-Any options specified in the $JAVAHFLAGS construction variable
-are included on this command line.
-
-.IP JAVAHCOMSTR
-The string displayed when C header and stub files
-are generated from Java classes.
-If this is not set, then $JAVAHCOM (the command line) is displayed.
-
-.ES
-env = Environment(JAVAHCOMSTR = "Generating header/stub file(s) $TARGETS from $SOURCES")
-.EE
-
-.IP JAVAHFLAGS
-General options passed to the C header and stub file generator
-for Java classes.
-
-.IP JAVASUFFIX
-The suffix for Java files;
-.B .java
-by default.
-
-.IP LATEX
-The LaTeX structured formatter and typesetter.
-
-.IP LATEXCOM
-The command line used to call the LaTeX structured formatter and typesetter.
-
-.IP LATEXCOMSTR
-The string displayed when calling
-the LaTeX structured formatter and typesetter.
-If this is not set, then $LATEXCOM (the command line) is displayed.
-
-.ES
-env = Environment(LATEXCOMSTR = "Building $TARGET from LaTeX input $SOURCES")
-.EE
-
-.IP LATEXFLAGS
-General options passed to the LaTeX structured formatter and typesetter.
-
-.IP LDMODULE
-The linker for building loadable modules.
-By default, this is the same as $SHLINK.
-
-.IP LDMODULECOM
-The command line for building loadable modules.
-On Mac OS X, this uses the $LDMODULE,
-$LDMODULEFLAGS and $FRAMEWORKSFLAGS variables.
-On other systems, this is the same as $SHLINK.
-
-.IP LDMODULECOMSTR
-The string displayed when building loadable modules.
-If this is not set, then $LDMODULECOM (the command line) is displayed.
-
-.IP LDMODULEFLAGS
-General user options passed to the linker for building loadable modules.
-
-.IP LDMODULEPREFIX
-The prefix used for loadable module file names.
-On Mac OS X, this is null;
-on other systems, this is
-the same as $SHLIBPREFIX.
-
-.IP LDMODULESUFFIX
-The suffix used for loadable module file names.
-On Mac OS X, this is null;
-on other systems, this is
-the same as $SHLIBSUFFIX.
-
-.IP LEX
-The lexical analyzer generator.
-
-.IP LEXFLAGS
-General options passed to the lexical analyzer generator.
-
-.IP LEXCOM
-The command line used to call the lexical analyzer generator
-to generate a source file.
-
-.IP LEXCOMSTR
-The string displayed when generating a source file
-using the lexical analyzer generator.
-If this is not set, then $LEXCOM (the command line) is displayed.
-
-.ES
-env = Environment(LEXCOMSTR = "Lex'ing $TARGET from $SOURCES")
-.EE
-
-.IP _LIBDIRFLAGS
-An automatically-generated construction variable
-containing the linker command-line options
-for specifying directories to be searched for library.
-The value of $_LIBDIRFLAGS is created
-by appending $LIBDIRPREFIX and $LIBDIRSUFFIX
-to the beginning and end
-of each directory in $LIBPATH.
-
-.IP LIBDIRPREFIX
-The prefix used to specify a library directory on the linker command line.
-This will be appended to the beginning of each directory
-in the $LIBPATH construction variable
-when the $_LIBDIRFLAGS variable is automatically generated.
-
-.IP LIBDIRSUFFIX
-The suffix used to specify a library directory on the linker command line.
-This will be appended to the end of each directory
-in the $LIBPATH construction variable
-when the $_LIBDIRFLAGS variable is automatically generated.
-
-.IP _LIBFLAGS
-An automatically-generated construction variable
-containing the linker command-line options
-for specifying libraries to be linked with the resulting target.
-The value of $_LIBFLAGS is created
-by appending $LIBLINKPREFIX and $LIBLINKSUFFIX
-to the beginning and end
-of each filename in $LIBS.
-
-.IP LIBLINKPREFIX
-The prefix used to specify a library to link on the linker command line.
-This will be appended to the beginning of each library
-in the $LIBS construction variable
-when the $_LIBFLAGS variable is automatically generated.
-
-.IP LIBLINKSUFFIX
-The suffix used to specify a library to link on the linker command line.
-This will be appended to the end of each library
-in the $LIBS construction variable
-when the $_LIBFLAGS variable is automatically generated.
-
-.IP LIBPATH
-The list of directories that will be searched for libraries.
-The implicit dependency scanner will search these
-directories for include files. Don't explicitly put include directory
-arguments in $LINKFLAGS or $SHLINKFLAGS
-because the result will be non-portable
-and the directories will not be searched by the dependency scanner. Note:
-directory names in LIBPATH will be looked-up relative to the SConscript
-directory when they are used in a command. To force
-.B scons
-to look-up a directory relative to the root of the source tree use #:
-
-.ES
-env = Environment(LIBPATH='#/libs')
-.EE
-
-.IP
-The directory look-up can also be forced using the
-.BR Dir ()
-function:
-
-.ES
-libs = Dir('libs')
-env = Environment(LIBPATH=libs)
-.EE
-
-.IP
-The directory list will be added to command lines
-through the automatically-generated
-$_LIBDIRFLAGS
-construction variable,
-which is constructed by
-appending the values of the
-$LIBDIRPREFIX and $LIBDIRSUFFIX
-construction variables
-to the beginning and end
-of each directory in $LIBPATH.
-Any command lines you define that need
-the LIBPATH directory list should
-include $_LIBDIRFLAGS:
-
-.ES
-env = Environment(LINKCOM="my_linker $_LIBDIRFLAGS $_LIBFLAGS -o $TARGET $SOURCE")
-.EE
-
-.IP LIBPREFIX
-The prefix used for (static) library file names.
-A default value is set for each platform
-(posix, win32, os2, etc.),
-but the value is overridden by individual tools
-(ar, mslib, sgiar, sunar, tlib, etc.)
-to reflect the names of the libraries they create.
-
-.IP LIBPREFIXES
-An array of legal prefixes for library file names.
-
-.IP LIBS
-A list of one or more libraries
-that will be linked with
-any executable programs
-created by this environment.
-
-.IP
-The library list will be added to command lines
-through the automatically-generated
-$_LIBFLAGS
-construction variable,
-which is constructed by
-appending the values of the
-$LIBLINKPREFIX and $LIBLINKSUFFIX
-construction variables
-to the beginning and end
-of each filename in $LIBS.
-Any command lines you define that need
-the LIBS library list should
-include $_LIBFLAGS:
-
-.ES
-env = Environment(LINKCOM="my_linker $_LIBDIRFLAGS $_LIBFLAGS -o $TARGET $SOURCE")
-.EE
-
-.IP
-If you add a
-File
-object to the
-LIBS
-list, the name of that file will be added to
-$_LIBFLAGS,
-and thus the link line, as is, without
-$LIBLINKPREFIX
-or
-$LIBLINKSUFFIX.
-For example:
-.ES
-env.Append(LIBS=File('/tmp/mylib.so'))
-.EE
-
-.IP
-In all cases, scons will add dependencies from the executable program to
-all the libraries in this list.
-
-.IP LIBSUFFIX
-The suffix used for (static) library file names.
-A default value is set for each platform
-(posix, win32, os2, etc.),
-but the value is overridden by individual tools
-(ar, mslib, sgiar, sunar, tlib, etc.)
-to reflect the names of the libraries they create.
-
-.IP LIBSUFFIXES
-An array of legal suffixes for library file names.
-
-.IP LINK
-The linker.
-
-.IP LINKFLAGS
-General user options passed to the linker.
-Note that this variable should
-.I not
-contain
-.B -l
-(or similar) options for linking with the libraries listed in $LIBS,
-nor
-.B -L
-(or similar) library search path options
-that scons generates automatically from $LIBPATH.
-See
-.BR _LIBFLAGS ,
-above,
-for the variable that expands to library-link options,
-and
-.BR _LIBDIRFLAGS ,
-above,
-for the variable that expands to library search path options.
-
-.IP LINKCOM
-The command line used to link object files into an executable.
-
-.IP LINKCOMSTR
-The string displayed when object files
-are linked into an executable.
-If this is not set, then $LINKCOM (the command line) is displayed.
-
-.ES
-env = Environment(LINKCOMSTR = "Linking $TARGET")
-.EE
-
-.IP M4
-The M4 macro preprocessor.
-
-.IP M4FLAGS
-General options passed to the M4 macro preprocessor.
-
-.IP M4COM
-The command line used to pass files through the M4 macro preprocessor.
-
-.IP M4COMSTR
-The string displayed when
-a file is passed through the M4 macro preprocessor.
-If this is not set, then $M4COM (the command line) is displayed.
-
-.IP MAXLINELENGTH
-The maximum number of characters allowed on an external command line.
-On Win32 systems,
-link lines longer than this many characters
-are linke via a temporary file name.
-
-.IP MSVS
-When the Microsoft Visual Studio tools are initialized, they set up
-this dictionary with the following keys:
-
-.B VERSION:
-the version of MSVS being used (can be set via
-MSVS_VERSION)
-
-.B VERSIONS:
-the available versions of MSVS installed
-
-.B VCINSTALLDIR:
-installed directory of Visual C++
-
-.B VSINSTALLDIR:
-installed directory of Visual Studio
-
-.B FRAMEWORKDIR:
-installed directory of the .NET framework
-
-.B FRAMEWORKVERSIONS:
-list of installed versions of the .NET framework, sorted latest to oldest.
-
-.B FRAMEWORKVERSION:
-latest installed version of the .NET framework
-
-.B FRAMEWORKSDKDIR:
-installed location of the .NET SDK.
-
-.B PLATFORMSDKDIR:
-installed location of the Platform SDK.
-
-.B 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_IGNORE_IDE_PATHS
-Tells the MS Visual Studio tools to use minimal INCLUDE, LIB, and PATH settings,
-instead of the settings from the IDE.
-
-For Visual Studio, SCons will (by default) automatically determine
-where MSVS is installed, and use the LIB, INCLUDE, and PATH variables
-set by the IDE. You can override this behavior by setting these
-variables after Environment initialization, or by setting
-.B MSVS_IGNORE_IDE_PATHS = 1
-in the Environment initialization.
-Specifying this will not leave these unset, but will set them to a
-minimal set of paths needed to run the tools successfully.
-
-.ES
-For VS6, the mininimal set is:
- INCLUDE:'<VSDir>\\VC98\\ATL\\include;<VSDir>\\VC98\\MFC\\include;<VSDir>\\VC98\\include'
- LIB:'<VSDir>\\VC98\\MFC\\lib;<VSDir>\\VC98\\lib'
- PATH:'<VSDir>\\Common\\MSDev98\\bin;<VSDir>\\VC98\\bin'
-For VS7, it is:
- INCLUDE:'<VSDir>\\Vc7\\atlmfc\\include;<VSDir>\\Vc7\\include'
- LIB:'<VSDir>\\Vc7\\atlmfc\\lib;<VSDir>\\Vc7\\lib'
- PATH:'<VSDir>\\Common7\\Tools\\bin;<VSDir>\\Common7\\Tools;<VSDir>\\Vc7\\bin'
-.EE
-
-.IP
-Where '<VSDir>' is the installed location of Visual Studio.
-
-.IP MSVS_USE_MFC_DIRS
-Tells the MS Visual Studio tool(s) to use
-the MFC directories in its default paths
-for compiling and linking.
-Under MSVS version 6,
-setting
-.B MSVS_USE_MFC_DIRS
-to a non-zero value
-adds the
-.B "ATL\\\\include"
-and
-.B "MFC\\\\include"
-directories to
-the default
-.B INCLUDE
-external environment variable,
-and adds the
-.B "MFC\\\\lib"
-directory to
-the default
-.B LIB
-external environment variable.
-Under MSVS version 7,
-setting
-.B MSVS_USE_MFC_DIRS
-to a non-zero value
-adds the
-.B "atlmfc\\\\include"
-directory to the default
-.B INCLUDE
-external environment variable,
-and adds the
-.B "atlmfc\\\\lib"
-directory to the default
-.B LIB
-external environment variable.
-The current default value is
-.BR 1 ,
-which means these directories
-are added to the paths by default.
-This default value is likely to change
-in a future release,
-so users who want the ATL and MFC
-values included in their paths
-are encouraged to enable the
-.B MSVS_USE_MFC_DIRS
-value explicitly
-to avoid future incompatibility.
-This variable has no effect if the
-.BR INCLUDE
-or
-.BR LIB
-environment variables are set explictly.
-
-.IP MSVS_VERSION
-Sets the preferred version of MSVS to use.
-
-SCons will (by default) select the latest version of MSVS
-installed on your machine. 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 given version isn't installed, tool initialization will fail.
-
-.IP MSVSPROJECTCOM
-The action used to generate Microsoft Visual Studio
-project and solution 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),
-and
-.B .dsp
-when using earlier versions of Visual Studio.
-
-.IP MSVSSOLUTIONSUFFIX
-The suffix used for Microsoft Visual Studio solution (DSW) files.
-The default value is
-.B .sln
-when using Visual Studio version 7.x (.NET),
-and
-.B .dsw
-when using earlier versions of Visual Studio.
-
-.IP MWCW_VERSION
-The version number of the MetroWerks CodeWarrior C compiler
-to be used.
-
-.IP MWCW_VERSIONS
-A list of installed versions of the MetroWerks CodeWarrior C compiler
-on this system.
-
-.IP no_import_lib
-When set to non-zero,
-suppresses creation of a corresponding Win32 static import lib by the
-.B SharedLibrary
-builder when used with
-MinGW or Microsoft Visual Studio.
-This also suppresses creation
-of an export (.exp) file
-when using Microsoft Visual Studio.
-
-.IP OBJPREFIX
-The prefix used for (static) object file names.
-
-.IP OBJSUFFIX
-The suffix used for (static) object file names.
-
-.IP P4
-The Perforce executable.
-
-.IP P4COM
-The command line used to
-fetch source files from Perforce.
-
-.IP P4COMSTR
-The string displayed when
-fetching a source file from Perforce.
-If this is not set, then $P4COM (the command line) is displayed.
-
-.IP P4FLAGS
-General options that are passed to Perforce.
-
-.IP 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
-.B PCH
-builder to generated a precompiled header.
-
-.IP PCHCOMSTR
-The string displayed when generating a precompiled header.
-If this is not set, then $PCHCOM (the command line) is displayed.
-
-.IP 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 PDFCOM
-A deprecated synonym for $DVIPDFCOM.
-
-.IP PDFPREFIX
-The prefix used for PDF file names.
-
-.IP PDFSUFFIX
-The suffix used for PDF file names.
-
-.IP PLATFORM
-The name of the platform used to create the Environment. If no platform is
-specified when the Environment is created,
-.B SCons
-autodetects the platform.
-
-.ES
-env = Environment(tools = [])
-if env['PLATFORM'] == 'cygwin':
- Tool('mingw')(env)
-else:
- Tool('msvc')(env)
-.EE
-
-.IP PRINT_CMD_LINE_FUNC
-A Python function used to print the command lines as they are executed
-(assuming command printing is not disabled by the
-.B -q
-or
-.B -s
-options or their equivalents).
-The function should take four arguments:
-.IR s ,
-the command being executed (a string),
-.IR target ,
-the target being built (file node, list, or string name(s)),
-.IR source ,
-the source(s) used (file node, list, or string name(s)), and
-.IR env ,
-the environment being used.
-
-The function must do the printing itself. The default implementation,
-used if this variable is not set or is None, is:
-.ES
-def print_cmd_line(s, target, source, env):
- sys.stdout.write(s + "\n")
-.EE
-
-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
-
-This just prints "Building <targetname> from <sourcename>..." instead
-of the actual commands.
-Such a function could also log the actual commands to a log file,
-for example.
-
-.IP PROGPREFIX
-The prefix used for executable file names.
-
-.IP PROGSUFFIX
-The suffix used for executable file names.
-
-.IP PSCOM
-The command line used to convert TeX DVI files into a PostScript file.
-
-.IP PSCOMSTR
-The string displayed when a TeX DVI file
-is converted into a PostScript file.
-If this is not set, then $PSCOM (the command line) is displayed.
-
-.IP PSPREFIX
-The prefix used for PostScript file names.
-
-.IP PSSUFFIX
-The prefix used for PostScript file names.
-
-.IP QTDIR
-The qt tool tries to take this from os.environ.
-It also initializes all QT_*
-construction variables listed below.
-(Note that all paths are constructed
-with python's os.path.join() method,
-but are listed here with the '/' separator
-for easier reading.)
-In addition, the construction environment
-variables CPPPATH, LIBPATH and LIBS may be modified
-and the variables
-PROGEMITTER, SHLIBEMITTER and LIBEMITTER
-are modified. Because the build-performance is affected when using this tool,
-you have to explicitly specify it at Environment creation:
-
-.ES
-Environment(tools=['default','qt'])
-.EE
-.IP
-The qt tool supports the following operations:
-
-.B Automatic moc file generation from header files.
-You do not have to specify moc files explicitly, the tool does it for you.
-However, there are a few preconditions to do so: Your header file must have
-the same filebase as your implementation file and must stay in the same
-directory. It must have one of the suffixes .h, .hpp, .H, .hxx, .hh. You
-can turn off automatic moc file generation by setting QT_AUTOSCAN to 0.
-See also the corresponding builder method
-.B Moc()
-
-.B 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 BuildDir, 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 builder method
-.B Moc()
-
-.B 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 BuildDir. See also the corresponding builder method
-.B Uic()
-
-.IP QT_AUTOSCAN
-Turn off scanning for mocable files. Use the Moc Builder to explicitely
-specify files to run moc on.
-
-.IP QT_BINPATH
-The path where the qt binaries are installed.
-The default value is '$QTDIR/bin'.
-
-.IP QT_CPPPATH
-The path where the qt header files are installed.
-The default value is '$QTDIR/include'.
-Note: If you set this variable to None, the tool won't change the CPPPATH
-construction variable.
-
-.IP QT_DEBUG
-Prints lots of debugging information while scanning for moc files.
-
-.IP QT_LIBPATH
-The path where the qt libraries are installed.
-The default value is '$QTDIR/lib'.
-Note: If you set this variable to None, the tool won't change the LIBPATH
-construction variable.
-
-.IP QT_LIB
-Default value is 'qt'. You may want to set this to 'qt-mt'. Note: If you set
-this variable to None, the tool won't change the LIBS variable.
-
-.IP QT_MOC
-Default value is '$QT_BINPATH/moc'.
-
-.IP QT_MOCCXXPREFIX
-Default value is ''. Prefix for moc output files, when source is a cxx file.
-
-.IP QT_MOCCXXSUFFIX
-Default value is '.moc'. Suffix for moc output files, when source is a cxx
-file.
-
-.IP QT_MOCFROMCPPFLAGS
-Default value is '-i'. These flags are passed to moc, when moccing a
-cpp file.
-
-.IP QT_MOCFROMCXXCOM
-Command to generate a moc file from a cpp file.
-
-.IP QT_MOCFROMCXXCOMSTR
-The string displayed when generating a moc file from a cpp file.
-If this is not set, then $QT_MOCFROMCXXCOM (the command line) is displayed.
-
-.IP QT_MOCFROMHCOM
-Command to generate a moc file from a header.
-
-.IP QT_MOCFROMHCOMSTR
-The string displayed when generating a moc file from a cpp file.
-If this is not set, then $QT_MOCFROMHCOM (the command line) is displayed.
-
-.IP QT_MOCFROMHFLAGS
-Default value is ''. These flags are passed to moc, when moccing a header
-file.
-
-.IP QT_MOCHPREFIX
-Default value is 'moc_'. Prefix for moc output files, when source is a header.
-
-.IP QT_MOCHSUFFIX
-Default value is '$CXXFILESUFFIX'. Suffix for moc output files, when source is
-a header.
-
-.IP QT_UIC
-Default value is '$QT_BINPATH/uic'.
-
-.IP QT_UICCOM
-Command to generate header files from .ui files.
-
-.IP QT_UICCOMSTR
-The string displayed when generating header files from .ui files.
-If this is not set, then $QT_UICCOM (the command line) is displayed.
-
-.IP QT_UICDECLFLAGS
-Default value is ''. These flags are passed to uic, when creating a a h
-file from a .ui file.
-
-.IP QT_UICDECLPREFIX
-Default value is ''. Prefix for uic generated header files.
-
-.IP QT_UICDECLSUFFIX
-Default value is '.h'. Suffix for uic generated header files.
-
-.IP QT_UICIMPLFLAGS
-Default value is ''. These flags are passed to uic, when creating a cxx
-file from a .ui file.
-
-.IP QT_UICIMPLPREFIX
-Default value is 'uic_'. Prefix for uic generated implementation files.
-
-.IP QT_UICIMPLSUFFIX
-Default value is '$CXXFILESUFFIX'. Suffix for uic generated implementation
-files.
-
-.IP QT_UISUFFIX
-Default value is '.ui'. Suffix of designer input files.
-
-.IP RANLIB
-The archive indexer.
-
-.IP RANLIBFLAGS
-General options passed to the archive indexer.
-
-.IP RC
-The resource compiler used by the RES builder.
-
-.IP RCCOM
-The command line used by the RES builder.
-
-.IP RCCOMSTR
-The string displayed when invoking the resource compiler.
-If this is not set, then $RCCOM (the command line) is displayed.
-
-.IP RCFLAGS
-The flags passed to the resource compiler by the RES builder.
-
-.IP 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 $RCS_COCOM
-(the command line) is displayed.
-
-.IP RCS_COFLAGS
-Options that are passed to the $RCS_CO command.
-
-.IP REGSVR
-The program used to register DLLs on Windows systems.
-
-.IP REGSVRCOM
-The command line used to register a newly-built DLL file
-on Windows systems.
-Invoked when the "register=1"
-keyword argument is passed to the
-.B SharedLibrary
-Builder.
-
-.IP REGSVRCOMSTR
-The string displayed when registering a newly-built DLL file.
-If this is not set, then $REGSVRCOM (the command line) is displayed.
-
-.IP RDirs
-A function that converts a file name into a list of Dir instances by
-searching the repositories.
-
-.IP RMIC
-The Java RMI stub compiler.
-
-.IP RMICCOM
-The command line used to compile stub
-and skeleton class files
-from Java classes that contain RMI implementations.
-Any options specified in the $RMICFLAGS construction variable
-are included on this command line.
-
-.IP RMICCOMSTR
-The string displayed when compiling
-stub and skeleton class files
-from Java classes that contain RMI implementations.
-If this is not set, then $RMICCOM (the command line) is displayed.
-
-.ES
-env = Environment(RMICCOMSTR = "Generating stub/skeleton class files $TARGETS from $SOURCES")
-.EE
-
-.IP RMICFLAGS
-General options passed to the Java RMI stub compiler.
-
-.IP 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 RPATH
-A list of paths to search for shared libraries when running programs.
-Currently only used in the GNU linker (gnulink) and IRIX linker (sgilink).
-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 SCANNERS
-A list of the available implicit dependency scanners.
-New file scanners may be added by
-appending to this list,
-although the more flexible approach
-is to associate scanners
-with a specific Builder.
-See the sections "Builder Objects"
-and "Scanner Objects,"
-below, for more information.
-
-.IP SCCS
-The SCCS executable.
-
-.IP SCCSCOM
-The command line used to
-fetch source files from SCCS.
-
-.IP SCCSCOMSTR
-The string displayed when fetching
-a source file from a CVS repository.
-If this is not set, then $SCCSCOM
-(the command line) is displayed.
-
-.IP SCCSFLAGS
-General options that are passed to SCCS.
-
-.IP SCCSGETFLAGS
-Options that are passed specifically to the SCCS "get" subcommand.
-This can be set, for example, to
-.I -e
-to check out editable files from SCCS.
-
-.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 $SHCCFLAGS and $CPPFLAGS construction variables
-are included on this command line.
-
-.IP SHCCCOMSTR
-The string displayed when a C source file
-is compiled to a shared object file.
-If this is not set, then $SHCCCOM (the command line) is displayed.
-
-.ES
-env = Environment(SHCCCOMSTR = "Compiling shared object $TARGET")
-.EE
-
-.IP SHCCFLAGS
-Options that are passed to the C compiler
-to generate shared-library objects.
-
-.IP SHCXX
-The C++ compiler used for generating shared-library objects.
-
-.IP SHCXXCOM
-The command line used to compile a C++ source file
-to a shared-library object file.
-Any options specified in the $SHCXXFLAGS and $CPPFLAGS construction variables
-are included on this command line.
-
-.IP SHCXXCOMSTR
-The string displayed when a C++ source file
-is compiled to a shared object file.
-If this is not set, then $SHCXXCOM (the command line) is displayed.
-
-.ES
-env = Environment(SHCXXCOMSTR = "Compiling shared object $TARGET")
-.EE
-
-.IP SHCXXFLAGS
-Options that are passed to the C++ compiler
-to generate shared-library objects.
-
-.IP SHELL
-A string naming the shell program that will be passed to the
-.I SPAWN
-function.
-See the
-.I SPAWN
-construction variable for more information.
-
-.IP SHF77
-The Fortran 77 compiler used for generating shared-library objects.
-You should normally set the $SHFORTRANC variable,
-which specifies the default Fortran compiler
-for all Fortran versions.
-You only need to set $SHF77 if you need to use a specific compiler
-or compiler version for Fortran 77 files.
-
-.IP SHF77COM
-The command line used to compile a Fortran 77 source file
-to a shared-library object file.
-You only need to set $SHF77COM if you need to use a specific
-command line for Fortran 77 files.
-You should normally set the $SHFORTRANCOM variable,
-which specifies the default command line
-for all Fortran versions.
-
-.IP SHF77COMSTR
-The string displayed when a Fortran 77 source file
-is compiled to a shared-library object file.
-If this is not set, then $SHF77COM or $SHFORTRANCOM
-(the command line) is displayed.
-
-.IP SHF77FLAGS
-Options that are passed to the Fortran 77 compiler
-to generated shared-library objects.
-You only need to set $SHF77FLAGS if you need to define specific
-user options for Fortran 77 files.
-You should normally set the $SHFORTRANFLAGS variable,
-which specifies the user-specified options
-passed to the default Fortran compiler
-for all Fortran versions.
-
-.IP SHF77PPCOM
-The command line used to compile a Fortran 77 source file to a
-shared-library object file
-after first running the file through the C preprocessor.
-Any options specified in the $SHF77FLAGS and $CPPFLAGS construction variables
-are included on this command line.
-You only need to set $SHF77PPCOM if you need to use a specific
-C-preprocessor command line for Fortran 77 files.
-You should normally set the $SHFORTRANPPCOM variable,
-which specifies the default C-preprocessor command line
-for all Fortran versions.
-
-.IP SHF90
-The Fortran 90 compiler used for generating shared-library objects.
-You should normally set the $SHFORTRANC variable,
-which specifies the default Fortran compiler
-for all Fortran versions.
-You only need to set $SHF90 if you need to use a specific compiler
-or compiler version for Fortran 90 files.
-
-.IP SHF90COM
-The command line used to compile a Fortran 90 source file
-to a shared-library object file.
-You only need to set $SHF90COM if you need to use a specific
-command line for Fortran 90 files.
-You should normally set the $SHFORTRANCOM variable,
-which specifies the default command line
-for all Fortran versions.
-
-.IP SHF90COMSTR
-The string displayed when a Fortran 90 source file
-is compiled to a shared-library object file.
-If this is not set, then $SHF90COM or $SHFORTRANCOM
-(the command line) is displayed.
-
-.IP SHF90FLAGS
-Options that are passed to the Fortran 90 compiler
-to generated shared-library objects.
-You only need to set $SHF90FLAGS if you need to define specific
-user options for Fortran 90 files.
-You should normally set the $SHFORTRANFLAGS variable,
-which specifies the user-specified options
-passed to the default Fortran compiler
-for all Fortran versions.
-
-.IP SHF90PPCOM
-The command line used to compile a Fortran 90 source file to a
-shared-library object file
-after first running the file through the C preprocessor.
-Any options specified in the $SHF90FLAGS and $CPPFLAGS construction variables
-are included on this command line.
-You only need to set $SHF90PPCOM if you need to use a specific
-C-preprocessor command line for Fortran 90 files.
-You should normally set the $SHFORTRANPPCOM variable,
-which specifies the default C-preprocessor command line
-for all Fortran versions.
-
-.IP SHF95
-The Fortran 95 compiler used for generating shared-library objects.
-You should normally set the $SHFORTRANC variable,
-which specifies the default Fortran compiler
-for all Fortran versions.
-You only need to set $SHF95 if you need to use a specific compiler
-or compiler version for Fortran 95 files.
-
-.IP SHF95COM
-The command line used to compile a Fortran 95 source file
-to a shared-library object file.
-You only need to set $SHF95COM if you need to use a specific
-command line for Fortran 95 files.
-You should normally set the $SHFORTRANCOM variable,
-which specifies the default command line
-for all Fortran versions.
-
-.IP SHF95COMSTR
-The string displayed when a Fortran 95 source file
-is compiled to a shared-library object file.
-If this is not set, then $SHF95COM or $SHFORTRANCOM
-(the command line) is displayed.
-
-.IP SHF95FLAGS
-Options that are passed to the Fortran 95 compiler
-to generated shared-library objects.
-You only need to set $SHF95FLAGS if you need to define specific
-user options for Fortran 95 files.
-You should normally set the $SHFORTRANFLAGS variable,
-which specifies the user-specified options
-passed to the default Fortran compiler
-for all Fortran versions.
-
-.IP SHF95PPCOM
-The command line used to compile a Fortran 95 source file to a
-shared-library object file
-after first running the file through the C preprocessor.
-Any options specified in the $SHF95FLAGS and $CPPFLAGS construction variables
-are included on this command line.
-You only need to set $SHF95PPCOM if you need to use a specific
-C-preprocessor command line for Fortran 95 files.
-You should normally set the $SHFORTRANPPCOM variable,
-which specifies the default C-preprocessor command line
-for all Fortran versions.
-
-.IP 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 FORTRANCOMSTR
-The string displayed when a Fortran source file
-is compiled to a shared-library object file.
-If this is not set, then $SHFORTRANCOM
-(the command line) is displayed.
-
-.IP SHFORTRANFLAGS
-Options that are passed to the Fortran compiler
-to generate shared-library objects.
-
-.IP SHFORTRANPPCOM
-The command line used to compile a Fortran source file to a
-shared-library object file
-after first running the file through the C preprocessor.
-Any options specified
-in the $SHFORTRANFLAGS and $CPPFLAGS construction variables
-are included on this command line.
-
-.IP SHLIBPREFIX
-The prefix used for shared library file names.
-
-.IP SHLIBSUFFIX
-The suffix used for shared library file names.
-
-.IP SHLINK
-The linker for programs that use shared libraries.
-
-.IP SHLINKCOM
-The command line used to link programs using shared libaries.
-
-.IP SHLINKCOMSTR
-The string displayed when programs using shared libraries are linked.
-If this is not set, then $SHLINKCOM (the command line) is displayed.
-
-.ES
-env = Environment(SHLINKCOMSTR = "Linking shared $TARGET")
-.EE
-
-.IP SHLINKFLAGS
-General user options passed to the linker for programs using shared libraries.
-Note that this variable should
-.I not
-contain
-.B -l
-(or similar) options for linking with the libraries listed in $LIBS,
-nor
-.B -L
-(or similar) include search path options
-that scons generates automatically from $LIBPATH.
-See
-.BR _LIBFLAGS ,
-above,
-for the variable that expands to library-link options,
-and
-.BR _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 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 SVN
-'\"The Subversion executable (usually named
-'\".BR svn ).
-'\"
-'\".IP SVNCOM
-'\"The command line used to
-'\"fetch source files from a Subversion repository.
-'\"
-'\".IP SVNFLAGS
-'\"General options that are passed to Subversion.
-
-.IP SWIG
-The scripting language wrapper and interface generator.
-
-.IP SWIGCFILESUFFIX
-The suffix that will be used for intermediate C
-source files generated by
-the scripting language wrapper and interface generator.
-The default value is
-.BR _wrap$CFILESUFFIX .
-By default, this value is used whenever the
-.B -c++
-option is
-.I not
-specified as part of the
-.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 $SWIGCOM (the command line) is displayed.
-
-.IP SWIGCXXFILESUFFIX
-The suffix that will be used for intermediate C++
-source files generated by
-the scripting language wrapper and interface generator.
-The default value is
-.BR _wrap$CFILESUFFIX .
-By default, this value is used whenever the
-.B -c++
-option is specified as part of the
-.B SWIGFLAGS
-construction variable.
-
-.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 TAR
-The tar archiver.
-
-.IP TARCOM
-The command line used to call the tar archiver.
-
-.IP TARCOMSTR
-The string displayed when archiving files
-using the tar archiver.
-If this is not set, then $TARCOM (the command line) is displayed.
-
-.ES
-env = Environment(TARCOMSTR = "Archiving $TARGET")
-.EE
-
-.IP TARFLAGS
-General options passed to the tar archiver.
-
-.IP TARGET
-A reserved variable name
-that may not be set or used in a construction environment.
-(See "Variable Substitution," below.)
-
-.IP 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 TEX
-The TeX formatter and typesetter.
-
-.IP TEXCOM
-The command line used to call the TeX formatter and typesetter.
-
-.IP TEXCOMSTR
-The string displayed when calling
-the TeX formatter and typesetter.
-If this is not set, then $TEXCOM (the command line) is displayed.
-
-.ES
-env = Environment(TEXCOMSTR = "Building $TARGET from TeX input $SOURCES")
-.EE
-
-.IP TEXFLAGS
-General options passed to the TeX formatter and typesetter.
-
-.IP TOOLS
-A list of the names of the Tool specifications
-that are part of this construction environment.
-
-.IP WIN32_INSERT_DEF
-When this is set to true,
-a library build of a WIN32 shared library (.dll file)
-will also build a corresponding .def file at the same time,
-if a .def file is not already listed as a build target.
-The default is 0 (do not build a .def file).
-
-.IP WIN32DEFPREFIX
-The prefix used for WIN32 .def file names.
-
-.IP WIN32DEFSUFFIX
-The suffix used for WIN32 .def file names.
-
-.IP YACC
-The parser generator.
-
-.IP YACCCOM
-The command line used to call the parser generator
-to generate a source file.
-
-.IP YACCCOMSTR
-The string displayed when generating a source file
-using the parser generator.
-If this is not set, then $YACCCOM (the command line) is displayed.
-
-.ES
-env = Environment(YACCCOMSTR = "Yacc'ing $TARGET from $SOURCES")
-.EE
-
-.IP YACCFLAGS
-General options passed to the parser generator.
-If $YACCFLAGS contains a \-d 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 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 ZIPCOMSTR
-The string displayed when archiving files
-using the zip utility.
-If this is not set, then $ZIPCOM
-(the command line or internal Python function) is displayed.
-
-.ES
-env = Environment(ZIPCOMSTR = "Zipping $TARGET")
-.EE
-
-.IP 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 when using Python 1.5.2
-or if the
-.B zipfile
-module is otherwise unavailable.
-
-.IP ZIPFLAGS
-General options passed to the zip utility.
-
-.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 Copy
-method:
-
-.ES
-env2 = env.Copy(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 ])
-.TP
-.RI env.Configure([ custom_tests ", " conf_dir ", " log_file ", " config_h ])
-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
-.B BuildDir
-method,
-you may want to specify a subdirectory under your build 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.
-
-.EE
-A created
-.B Configure
-instance has the following associated methods:
-
-.TP
-.RI Configure.Finish( self )
-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 Configure.CheckHeader( self ", " 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.
-
+.RI SConf.CheckCHeader( context ", " header ", [" include_quotes ])
.TP
-.RI Configure.CheckCHeader( self ", " header ", [" include_quotes ])
+.IR sconf .CheckCHeader( header ", [" include_quotes ])
This is a wrapper around
-.B Configure.CheckHeader
-which checks if
+.B SConf.CheckHeader
+which checks if
.I header
is usable in the C language.
.I header
.B #include
lines should precede the
header line being checked for.
-The optional argument
-.I include_quotes
+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
Returns 1 on success and 0 on failure.
.TP
-.RI Configure.CheckCXXHeader( self ", " header ", [" include_quotes ])
+.RI SConf.CheckCXXHeader( context ", " header ", [" include_quotes ])
+.TP
+.IR sconf .CheckCXXHeader( header ", [" include_quotes ])
This is a wrapper around
-.B Configure.CheckHeader
-which checks if
+.B SConf.CheckHeader
+which checks if
.I header
is usable in the C++ language.
.I header
.B #include
lines should precede the
header line being checked for.
-The optional argument
-.I include_quotes
+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.
+Returns 1 on success and 0 on failure.
.TP
-.RI Configure.CheckFunc( self ", " function_name ", [" header ", " language ])
+.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
and selects the compiler to be used for the check;
the default is "C".
-.TP
-.RI Configure.CheckLib( self ", [" library ", " symbol ", " header ", " language ", " autoadd=1 ])
-Checks if
-.I library
-provides
+.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
+.I library
may also be None (the default),
-in which case
-.I symbol
+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 .
-The default
+If
.I symbol
-is "main",
-which just check if
+is not set or is
+.BR None ,
+then
+.BR SConf.CheckLib ()
+just checks if
you can link against the specified
.IR library .
The optional
The default value for
.I autoadd
is 1.
-It is assumed, that the C-language is used.
This method returns 1 on success and 0 on error.
-.TP
-.RI Configure.CheckLibWithHeader( self ", " library ", " header ", " language ", [" call ", " autoadd ])
+.TP
+.RI SConf.CheckLibWithHeader( context ", " library ", " header ", " language ", [" call ", " autoadd ])
+.TP
+.IR sconf .CheckLibWithHeader( library ", " header ", " language ", [" call ", " autoadd ])
-In contrast to the
-.RI Configure.CheckLib
+In contrast to the
+.RI SConf.CheckLib
call, this call provides a more sophisticated way to check against libraries.
-Again,
+Again,
.I library
-specifies the library or a list of libraries to check.
+specifies the library or a list of libraries to check.
.I header
specifies a header to check for.
.I header
.I language
may be one of 'C','c','CXX','cxx','C++' and 'c++'.
.I call
-can be any valid expression (with a trailing ';'). The default is 'main();'.
+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
+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 Configure.CheckType( self ", " type_name ", [" includes ", " language ])
+.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
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);' ):
+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()
+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.
+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
+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
+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
+.TP
.RI CheckContext.Message( self ", " text )
-Usually called before the check is started.
+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.
+Usually called after the check is done.
.I res
-can be either an integer or a string. In the former case, 'ok' (res != 0)
-or 'failed' (res == 0) is displayed to the user, in the latter case the
+can be either an integer or a string. In the former case, 'ok' (res != 0)
+or 'failed' (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
+Checks if a file with the specified
.I extension
-(e.g. '.c') containing
-.I text
+(e.g. '.c') containing
+.I text
can be compiled using the environment's
-.B Object
+.B Object
builder. Returns 1 on success and 0 on failure.
-.TP
+.TP
.RI CheckContext.TryLink( self ", " text ", " extension )
Checks, if a file with the specified
.I extension
-(e.g. '.c') containing
-.I text
+(e.g. '.c') containing
+.I text
can be compiled using the environment's
.B Program
builder. Returns 1 on success and 0 on failure.
.RI CheckContext.TryRun( self ", " text ", " extension )
Checks, if a file with the specified
.I extension
-(e.g. '.c') containing
-.I text
+(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
.TP
.RI CheckContext.TryAction( self ", " action ", [" text ", " extension ])
Checks if the specified
-.I action
+.I action
with an optional source file (contents
.I text
-, extension
+, extension
.I extension
= ''
-) can be executed.
-.I action
-may be anything which can be converted to a
+) can be executed.
+.I action
+may be anything which can be converted to a
.B scons
.RI Action.
On success,
the methods above are based on this method.
Given the Builder instance
.I builder
-and the optional
+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
+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
context.env.Append(LIBS = 'qt', LIBPATH = qtdir + '/lib', CPPPATH = qtdir + '/include' )
ret = context.TryLink("""
#include <qapp.h>
-int main(int argc, char **argv) {
+int main(int argc, char **argv) {
QApplication qapp(argc, argv);
return 0;
}
if not conf.CheckQt('/usr/lib/qt'):
print 'We really need qt!'
Exit(1)
-env = conf.Finish()
+env = conf.Finish()
.EE
-.SS Construction Variable Options
+.SS Command-Line Construction Variables
-Often when building software, various options need to be specified at build
-time that are not known when the SConstruct/SConscript files are
-written. For example, libraries needed for the build may be in non-standard
+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.
+compiler.
.B scons
-provides a mechanism for overridding construction variables from the
-command line or a text-based SConscript file through an Options
-object. To create an Options object, call the Options() function:
+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 Options([ files "], [" args ])
-This creates an Options object that will read construction variables from
+.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,
Example:
.ES
-opts = Options('custom.py')
-opts = Options('overrides.py', ARGUMENTS)
-opts = Options(None, {FOO:'expansion', BAR:7})
+vars = Variables('custom.py')
+vars = Variables('overrides.py', ARGUMENTS)
+vars = Variables(None, {FOO:'expansion', BAR:7})
.EE
-Options objects have the following methods:
+Variables objects have the following methods:
.TP
.RI Add( key ", [" help ", " default ", " validator ", " converter ])
-This adds a customizable construction variable to the Options object.
+This adds a customizable construction variable to the Variables object.
.I key
-is the name of the variable.
-.I help
+is the name of the variable.
+.I help
is the help text for the variable.
-.I default
+.I default
is the default value of the variable;
if the default value is
.B None
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
+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 a single argument: value. Example:
+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
-opts.Add('CC', 'The C compiler')
+vars.Add('CC', 'The C compiler')
+
+def validate_color(key, val, env):
+ if not val in ['red', 'blue', 'yellow']:
+ raise "Invalid color value '%s'" % val
+vars.Add('COLOR', validator=valid_color)
.EE
.TP
-.RI AddOptions( list )
+.RI AddVariables( list )
A wrapper script that adds
multiple customizable construction variables
-to an Options object.
+to a Variables object.
.I list
is a list of tuple or list objects
that contain the arguments
method.
.ES
-opt.AddOptions(
+opt.AddVariables(
('debug', '', 0),
('CC', 'The C compiler'),
('VALIDATE', 'An option for testing validation',
.RI Update( env ", [" args ])
This updates a construction environment
.I env
-with the customized construction variables. Normally this method is not
-called directly, but is called indirectly by passing the Options object to
+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(options=opts)
+env = Environment(variables=vars)
.EE
.IP
The text file(s) that were specified
-when the Options object was created
+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 options into a script file named
+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 Options method can be used to
-support caching of options between runs.
+settings. This method combined with the Variables method can be used to
+support caching of variables between runs.
.ES
env = Environment()
-opts = Options(['options.cache', 'custom.py'])
-opts.Add(...)
-opts.Update(env)
-opts.Save('options.cache', env)
+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.
+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
+of customizable variables. Calling with
an optional
.I sort
function
function).
.ES
-Help(opts.GenerateHelpText(env))
-Help(opts.GenerateHelpText(env, sort=cmp))
+Help(vars.GenerateHelpText(env))
+Help(vars.GenerateHelpText(env, sort=cmp))
.EE
.TP
-.RI FormatOptionHelpText( env ", " opt ", " help ", " default ", " actual )
+.RI FormatVariableHelpText( env ", " opt ", " help ", " default ", " actual )
This method returns a formatted string
containing the printable help text
for one option.
def my_format(env, opt, help, default, actual):
fmt = "\n%s: default=%s actual=%s (%s)\n"
return fmt % (opt, default. actual, help)
-opts.FormatOptionHelpText = my_format
+vars.FormatVariableHelpText = my_format
.EE
-To make it more convenient to work with customizable Options,
+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 Options:
+various types of Variables:
.TP
-.RI BoolOption( key ", " help ", " default )
+.RI BoolVariable( key ", " help ", " default )
Return a tuple of arguments
to set up a Boolean option.
The option will use
as false.
.TP
-.RI EnumOption( key ", " help ", " default ", " allowed_values ", [" map ", " ignorecase ])
+.RI EnumVariable( key ", " help ", " default ", " allowed_values ", [" map ", " ignorecase ])
Return a tuple of arguments
to set up an option
whose value may be one
converted to lower case.
.TP
-.RI ListOption( key ", " help ", " default ", " names ", [", map ])
+.RI ListVariable( key ", " help ", " default ", " names ", [", map ])
Return a tuple of arguments
to set up an option
whose value may be one or more
list.
.TP
-.RI PackageOption( key ", " help ", " default )
+.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
+enabled, disabled or
given an explicit path name.
The option will use
the specified name
to disable use of the specified option.
.TP
-.RI PathOption( key ", " help ", " default ", [" validator ])
+.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.
is acceptable.
SCons supplies the
following ready-made validators:
-.BR PathOption.PathExists
+.BR PathVariable.PathExists
(the default),
which verifies that the specified path exists;
-.BR PathOption.PathIsFile ,
+.BR PathVariable.PathIsFile ,
which verifies that the specified path is an existing file;
-.BR PathOption.PathIsDir ,
+.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 PathOption.PathIsDirCreate ,
-which verifies that the specified path is a directory,
-and will create the specified directory if the path does not exist.
+.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 options variable to be set;
+the name of the variable to be set;
.IR val ,
the specified value being checked;
and
.RE
These functions make it
convenient to create a number
-of options with consistent behavior
+of variables with consistent behavior
in a single call to the
-.B AddOptions
+.B AddVariables
method:
.ES
-opts.AddOptions(
- BoolOption('warnings', 'compilation with -Wall and similiar', 1),
- EnumOption('debug', 'debug output and symbols', 'no'
+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
- ListOption('shared',
+ ListVariable('shared',
'libraries to build as shared libraries',
'all',
names = list_of_libs),
- PackageOption('x11',
+ PackageVariable('x11',
'use X11 installed here (yes = search some places)',
'yes'),
- PathOption('qtdir', 'where the root of Qt is installed', qtdir),
- PathOption('foopath', 'where the foo library is installed', foopath,
- PathOption.PathIsDir),
+ PathVariable('qtdir', 'where the root of Qt is installed', qtdir),
+ PathVariable('foopath', 'where the foo library is installed', foopath,
+ PathVariable.PathIsDir),
)
.EE
.B SConstruct
file is found).
The build path is the same as the source path if
-.I build_dir
+.I variant_dir
is not being used.
.IP abspath
.I File
or
.IR Dir .
-The
+The
.ES
# Get the current build dir's path, relative to top.
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
Builder objects are created
using the
-.B Builder
+.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.
+The command line string used to build the target from the source.
.B action
can also be:
a list of strings representing the command
An action function
takes three arguments:
-.I source
-- a list of source nodes,
+.I source
+- a list of source nodes,
.I target
- a list of target nodes,
.I env
- the construction environment.
-.IP prefix
+.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
+- 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
"$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.
implicit dependencies
based only on the target file
and the construction environment,
-.I not
+.I not
for implicit
(See the section "Scanner Objects," below,
for information about creating Scanner objects.)
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;
An emitter function
takes three arguments:
-.I source
-- a list of source nodes,
+.I source
+- a list of source nodes,
.I target
- a list of target nodes,
.I env
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.
+builder with the target.
.IP env
A construction environment that can be used
The generator function
takes four arguments:
-.I source
-- a list of source nodes,
+.I source
+- a list of source nodes,
.I target
- a list of target nodes,
.I env
.ES
def g(source, target, env, for_signature):
- return [["gcc", "-c", "-o"] + target + source]
+ return [["gcc", "-c", "-o"] + target + source]
b = Builder(generator=g)
.EE
.IP
-The
+The
.I generator
and
.I action
.IP single_source
Specifies that this builder expects exactly one source file per call. Giving
more than one source files without target files results in implicitely calling
-the builder multiple times (once for each source given). Giving multiple
+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
+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.
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
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
+to set a construction variable to
the repository of a source code system.
Any additional keyword arguments supplied
.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.
+Examples:
.ES
Action('$CC -c -o $TARGET $SOURCES')
+
+# Doesn't print the line being executed.
+Action('@build $TARGET $SOURCES')
+
+# Ignores
+Action('-build $TARGET $SOURCES')
.EE
.\" XXX From Gary Ruben, 23 April 2002:
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, optional argument
-is a Python function that returns
+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 is 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.
Like a function to build a file,
this function takes three arguments:
.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 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
return "building '%s' from '%s'" % (target[0], source[0])
# Use a positional argument.
-a = Action(build_it, string_it)
+f = Action(build_it, string_it)
+s = Action(build_it, "building '$TARGET' from '$SOURCE'")
# Alternatively, use a keyword argument.
-a = Action(build_it, strfunction=string_it)
+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, also optional argument
open(target[0], 'w').write(env['XXX'])
return 0
-def string_it(target, source):
- return "building '%s' from '%s'" % (target[0], source[0])
-
# Use positional arguments.
-a = Action(build_it, string_it, ['XXX'])
+a = Action(build_it, '$STRINGIT', ['XXX'])
# Alternatively, use a keyword argument.
a = Action(build_it, varlist=['XXX'])
.EE
-.PP
The
.BR Action ()
chdir=1)
.EE
+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
+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
+
.SS Miscellaneous Action Functions
.B scons
that arrange for various common
file and directory manipulations
to be performed.
-These are similar in concept to "tasks" in the
+These are similar in concept to "tasks" in the
Ant build tool,
although the implementation is slightly different.
These functions do not actually
without relying
on platform-specific
external commands:
-that
+that
.ES
env = Environment(TMPBUILD = '/tmp/builddir')
env.Command('foo.out', 'foo.in',
[Mkdir('$TMPBUILD'),
- Copy('${SOURCE.dir}', '$TMPBUILD')
+ Copy('$TMPBUILD', '${SOURCE.dir}'),
"cd $TMPBUILD && make",
Delete('$TMPBUILD')])
.EE
env.Command('foo.out', 'foo.in',
[Mkdir('/tmp/builddir',
- Copy('$SOURCE', '/tmp/builddir')
- "cd /tmp/builddir && ])
-
+ Copy('$SOURCE', '/tmp/builddir/foo.in')
+ "cd /tmp/builddir && make",
+ Copy('/tmp/builddir/foo.out', '$TARGET')])
.EE
.TP
variables for each command execution:
.IP TARGET
-The file name of the target being built, or the file name of the first
+The file name of the target being built, or the file name of the first
target if multiple targets are being built.
.IP TARGETS
(Note that the above variables are reserved
and may not be set in a construction environment.)
-.LP
+.LP
For example, given the construction variable CC='cc', targets=['foo'], and
sources=['foo.c', 'bar.c']:
.B /
(forward slashes)
not backslashes.
-This is sometimes necessary on Win32 systems
+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 BuildDir. If this file isn't linked, it just returns the
-directory and filename unchanged.
+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 BuildDir. If this file isn't linked, it just returns the
-directory part of the filename.
+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 BuildDir. If the file does not exist locally but exists in
-a Repository, the path in the Repository is returned.
+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 BuildDir. If this file isn't linked, it just returns the
-directory part of the filename.
+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
${TARGET.suffix} => .x
${TARGET.abspath} => /top/dir/sub/dir/file.x
-SConscript('src/SConscript', build_dir='sub/dir')
+SConscript('src/SConscript', variant_dir='sub/dir')
$SOURCE => sub/dir/file.x
${SOURCE.srcpath} => src/file.x
${SOURCE.srcdir} => src
${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
take four arguments:
.I target
- a list of target nodes,
-.I source
-- a list of source nodes,
+.I source
+- a list of source nodes,
.I env
- the construction environment,
.I for_signature
self.arg = arg
def __call__(self, target, source, env, for_signature):
- return arg + " bar"
+ return self.arg + " bar"
# Will expand $BAR to "my argument bar baz"
env=Environment(FOO=foo, BAR="${FOO('my argument')} baz")
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.
+command line arguments.
.IP List
When the value is a list it is interpreted as a list of command line
Scanner accepts the following arguments:
.IP function
-A Python function that will process
+This can be either:
+1) a Python function that will process
the Node (file)
and return a list of strings (file names)
representing the implicit
-dependencies found in the contents.
-The function takes three or four arguments:
+dependencies found in the contents;
+or:
+2) a dictionary that maps keys
+(typically the file suffix, but see below for more discussion)
+to other Scanners that should be called.
+
+If the argument is actually a Python function,
+the function must take three or four arguments:
def scanner_function(node, env, path):
- def scanner_function(node, env, path, arg):
+ def scanner_function(node, env, path, arg=None):
The
.B 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
for the different file types that this
Scanner knows how to scan.
If the argument is a string,
-then it will be expanded
+then it will be expanded
into a list by the current environment.
.IP path_function
-A Python function that takes
-two or three arguments:
-a construction environment, directory Node,
-and optional argument supplied
+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
the
.BR Object (),
.BR SharedObject (),
-and
+and
.BR StaticObject ()
builders to decide
which scanner should be used
the underlying system.
On a case-sensitive system
such as Linux or UNIX,
-SCons treats a file with a
+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
+SCons treats a file with a
.B .C
suffix as a C source file.
.SS .F file suffix
the underlying system.
On a case-sensitive system
such as Linux or UNIX,
-SCons treats a file with a
+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
+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 WIN32: Cygwin Tools and Cygwin Python vs. Windows Pythons
+.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.
(or some other Windows compiler)
use the python.org or ActiveState version of Python
to run SCons.
-.SS WIN32: scons.bat file
-On WIN32 systems,
+.SS Windows: scons.bat file
+On Windows systems,
SCons is executed via a wrapper
.B scons.bat
file.
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
+then you must explictly tell SCons to use MinGW by passing
.ES
tools=['mingw']
.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):
bar_in.target_scanner = kscan
.EE
+Here is a similar but more complete example that searches
+a path of directories
+(specified as the
+.B MYPATH
+construction variable)
+for files that actually exist:
+
+.ES
+include_re = re.compile(r'^include\\s+(\\S+)$', re.M)
+
+def my_scan(node, env, path, arg):
+ contents = node.get_contents()
+ includes = include_re.findall(contents)
+ if includes == []:
+ return []
+ results = []
+ for inc in includes:
+ for dir in path:
+ file = dir + os.sep + inc
+ if os.path.exists(file):
+ results.append(file)
+ break
+ return results
+
+scanner = Scanner(name = 'myscanner',
+ function = my_scan,
+ argument = None,
+ skeys = ['.x'],
+ path_function = FindPathDirs('MYPATH'),
+ )
+scanners = Environment().Dictionary('SCANNERS')
+env = Environment(SCANNERS = scanners + [scanner])
+.EE
+
+The
+.BR FindPathDirs ()
+function used in the previous example returns a function
+(actually a callable Python object)
+that will return a list of directories
+specified in the
+.B $MYPATH
+construction variable.
+If you need to customize how the search path is derived,
+you would provide your own
+.B path_function
+argument when creating the Scanner object,
+as follows:
+
+.ES
+# MYPATH is a list of directories to search for files in
+def pf(env, dir, target, source, arg):
+ top_dir = Dir('#').abspath
+ results = []
+ if env.has_key('MYPATH'):
+ 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
.SS Building Multiple Variants From the Same Source
-Use the build_dir keyword argument to
+Use the variant_dir keyword argument to
the SConscript function to establish
-one or more separate build directories for
-a given source directory:
+one or more separate variant build directory trees
+for a given source directory:
.ES
SConstruct:
cppdefines = ['FOO']
Export("cppdefines")
- SConscript('src/SConscript', build_dir='foo')
+ SConscript('src/SConscript', variant_dir='foo')
cppdefines = ['BAR']
Export("cppdefines")
- SConscript('src/SConscript', build_dir='bar')
+ SConscript('src/SConscript', variant_dir='bar')
src/SConscript:
Import('env')
env.Library('a', Split('a1.c a2.c a3.c'))
-libB/SConscript:
+libB/SConscript:
Import('env')
env.Library('b', Split('b1.c b2.c b3.c'))
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).
+\&'a.lib' on Windows).
-.SS Customizing contruction variables from the command line.
+.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.
+line or in the file custom.py.
.ES
-opts = Options('custom.py')
-opts.Add('CC', 'The C compiler.')
-env = Environment(options=opts)
-Help(opts.GenerateHelpText(env))
+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:
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.
+variable.
SConstruct:
.ES
projects / scons.git / blobdiff