diff options
Diffstat (limited to 'scons.1')
| -rw-r--r-- | scons.1 | 15268 |
1 files changed, 15268 insertions, 0 deletions
@@ -0,0 +1,15268 @@ +.\" Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 The SCons Foundation +.\" +.\" Permission is hereby granted, free of charge, to any person obtaining +.\" a copy of this software and associated documentation files (the +.\" "Software"), to deal in the Software without restriction, including +.\" without limitation the rights to use, copy, modify, merge, publish, +.\" distribute, sublicense, and/or sell copies of the Software, and to +.\" permit persons to whom the Software is furnished to do so, subject to +.\" the following conditions: +.\" +.\" The above copyright notice and this permission notice shall be included +.\" in all copies or substantial portions of the Software. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY +.\" KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE +.\" WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND +.\" NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE +.\" LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION +.\" OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION +.\" WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. +.\" +.\" doc/man/scons.1 4577 2009/12/27 19:43:56 scons +.\" +.TH SCONS 1 "December 2009" +.\" ES - Example Start - indents and turns off line fill +.rm ES +.de ES +.RS +.nf +.. +.\" EE - Example End - ends indent and turns line fill back on +.rm EE +.de EE +.fi +.RE +.. +.SH NAME +scons \- a software construction tool +.SH SYNOPSIS +.B scons +[ +.IR options ... +] +[ +.IR name = val ... +] +[ +.IR targets ... +] +.SH DESCRIPTION + +The +.B scons +utility builds software (or other files) by determining which +component pieces must be rebuilt and executing the necessary commands to +rebuild them. + +By default, +.B scons +searches for a file named +.IR SConstruct , +.IR Sconstruct , +or +.I sconstruct +(in that order) in the current directory and reads its +configuration from the first file found. +An alternate file name may be +specified via the +.B -f +option. + +The +.I SConstruct +file can specify subsidiary +configuration files using the +.B SConscript() +function. +By convention, +these subsidiary files are named +.IR SConscript , +although any name may be used. +(Because of this naming convention, +the term "SConscript files" +is sometimes used to refer +generically to all +.B scons +configuration files, +regardless of actual file name.) + +The configuration files +specify the target files to be built, and +(optionally) the rules to build those targets. Reasonable default +rules exist for building common software components (executable +programs, object files, libraries), so that for most software +projects, only the target and input files need be specified. + +Before reading the +.I SConstruct +file, +.B scons +looks for a directory named +.I site_scons +in the directory containing the +.I SConstruct +file; if it exists, +.I site_scons +is added to sys.path, +the file +.IR site_scons/site_init.py , +is evaluated if it exists, +and the directory +.I site_scons/site_tools +is added to the default toolpath if it exist. +See the +.I --no-site-dir +and +.I --site-dir +options for more details. + +.B scons +reads and executes the SConscript files as Python scripts, +so you may use normal Python scripting capabilities +(such as flow control, data manipulation, and imported Python libraries) +to handle complicated build situations. +.BR scons , +however, reads and executes all of the SConscript files +.I before +it begins building any targets. +To make this obvious, +.B scons +prints the following messages about what it is doing: + +.ES +$ scons foo.out +scons: Reading SConscript files ... +scons: done reading SConscript files. +scons: Building targets ... +cp foo.in foo.out +scons: done building targets. +$ +.EE + +The status messages +(everything except the line that reads "cp foo.in foo.out") +may be suppressed using the +.B -Q +option. + +.B scons +does not automatically propagate +the external environment used to execute +.B scons +to the commands used to build target files. +This is so that builds will be guaranteed +repeatable regardless of the environment +variables set at the time +.B scons +is invoked. +This also means that if the compiler or other commands +that you want to use to build your target files +are not in standard system locations, +.B scons +will not find them unless +you explicitly set the PATH +to include those locations. +Whenever you create an +.B scons +construction environment, +you can propagate the value of PATH +from your external environment as follows: + +.ES +import os +env = Environment(ENV = {'PATH' : os.environ['PATH']}) +.EE + +Similarly, if the commands use external environment variables +like $PATH, $HOME, $JAVA_HOME, $LANG, $SHELL, $TERM, etc., +these variables can also be explicitly propagated: + +.ES +import os +env = Environment(ENV = {'PATH' : os.environ['PATH'], + 'HOME' : os.environ['HOME']}) +.EE + +Or you may explicitly propagate the invoking user's +complete external environment: + +.ES +import os +env = Environment(ENV = os.environ) +.EE + +This comes at the expense of making your build +dependent on the user's environment being set correctly, +but it may be more convenient for many configurations. + +.B scons +can scan known input files automatically for dependency +information (for example, #include statements +in C or C++ files) and will rebuild dependent files appropriately +whenever any "included" input file changes. +.B scons +supports the +ability to define new scanners for unknown input file types. + +.B scons +knows how to fetch files automatically from +SCCS or RCS subdirectories +using SCCS, RCS or BitKeeper. + +.B scons +is normally executed in a top-level directory containing a +.I SConstruct +file, optionally specifying +as command-line arguments +the target file or files to be built. + +By default, the command + +.ES +scons +.EE + +will build all target files in or below the current directory. +Explicit default targets +(to be built when no targets are specified on the command line) +may be defined the SConscript file(s) +using the +.B Default() +function, described below. + +Even when +.B Default() +targets are specified in the SConscript file(s), +all target files in or below the current directory +may be built by explicitly specifying +the current directory (.) +as a command-line target: + +.ES +scons . +.EE + +Building all target files, +including any files outside of the current directory, +may be specified by supplying a command-line target +of the root directory (on POSIX systems): + +.ES +scons / +.EE + +or the path name(s) of the volume(s) in which all the targets +should be built (on Windows systems): + +.ES +scons C:\\ D:\\ +.EE + +To build only specific targets, +supply them as command-line arguments: + +.ES +scons foo bar +.EE + +in which case only the specified targets will be built +(along with any derived files on which they depend). + +Specifying "cleanup" targets in SConscript files is not usually necessary. +The +.B -c +flag removes all files +necessary to build the specified target: + +.ES +scons -c . +.EE + +to remove all target files, or: + +.ES +scons -c build export +.EE + +to remove target files under build and export. +Additional files or directories to remove can be specified using the +.BR Clean() +function. +Conversely, targets that would normally be removed by the +.B -c +invocation +can be prevented from being removed by using the +.BR NoClean () +function. + +A subset of a hierarchical tree may be built by +remaining at the top-level directory (where the +.I SConstruct +file lives) and specifying the subdirectory as the target to be +built: + +.ES +scons src/subdir +.EE + +or by changing directory and invoking scons with the +.B -u +option, which traverses up the directory +hierarchy until it finds the +.I SConstruct +file, and then builds +targets relatively to the current subdirectory: + +.ES +cd src/subdir +scons -u . +.EE + +.B scons +supports building multiple targets in parallel via a +.B -j +option that takes, as its argument, the number +of simultaneous tasks that may be spawned: + +.ES +scons -j 4 +.EE + +builds four targets in parallel, for example. + +.B scons +can maintain a cache of target (derived) files that can +be shared between multiple builds. When caching is enabled in a +SConscript file, any target files built by +.B scons +will be copied +to the cache. If an up-to-date target file is found in the cache, it +will be retrieved from the cache instead of being rebuilt locally. +Caching behavior may be disabled and controlled in other ways by the +.BR --cache-force , +.BR --cache-disable , +and +.B --cache-show +command-line options. The +.B --random +option is useful to prevent multiple builds +from trying to update the cache simultaneously. + +Values of variables to be passed to the SConscript file(s) +may be specified on the command line: + +.ES +scons debug=1 . +.EE + +These variables are available in SConscript files +through the ARGUMENTS dictionary, +and can be used in the SConscript file(s) to modify +the build in any way: + +.ES +if ARGUMENTS.get('debug', 0): + env = Environment(CCFLAGS = '-g') +else: + env = Environment() +.EE + +The command-line variable arguments are also available +in the ARGLIST list, +indexed by their order on the command line. +This allows you to process them in order rather than by name, +if necessary. +ARGLIST[0] returns a tuple +containing (argname, argvalue). +A Python exception is thrown if you +try to access a list member that +does not exist. + +.B scons +requires Python version 1.5.2 or later. +There should be no other dependencies or requirements to run +.B scons. + +.\" The following paragraph reflects the default tool search orders +.\" currently in SCons/Tool/__init__.py. If any of those search orders +.\" change, this documentation should change, too. +By default, +.B scons +knows how to search for available programming tools +on various systems. +On Windows systems, +.B scons +searches in order for the +Microsoft Visual C++ tools, +the MinGW tool chain, +the Intel compiler tools, +and the PharLap ETS compiler. +On OS/2 systems, +.B scons +searches in order for the +OS/2 compiler, +the GCC tool chain, +and the Microsoft Visual C++ tools, +On SGI IRIX, IBM AIX, Hewlett Packard HP-UX, and Sun Solaris systems, +.B scons +searches for the native compiler tools +(MIPSpro, Visual Age, aCC, and Forte tools respectively) +and the GCC tool chain. +On all other platforms, +including POSIX (Linux and UNIX) platforms, +.B scons +searches in order +for the GCC tool chain, +the Microsoft Visual C++ tools, +and the Intel compiler tools. +You may, of course, override these default values +by appropriate configuration of +Environment construction variables. + +.SH OPTIONS +In general, +.B scons +supports the same command-line options as GNU +.BR make , +and many of those supported by +.BR cons . + +.TP +-b +Ignored for compatibility with non-GNU versions of +.BR make. + +.TP +-c, --clean, --remove +Clean up by removing all target files for which a construction +command is specified. +Also remove any files or directories associated to the construction command +using the +.BR Clean () +function. +Will not remove any targets specified by the +.BR NoClean () +function. + +.TP +.RI --cache-debug= file +Print debug information about the +.BR CacheDir () +derived-file caching +to the specified +.IR file . +If +.I file +is +.B \- +(a hyphen), +the debug information are printed to the standard output. +The printed messages describe what signature file names are +being looked for in, retrieved from, or written to the +.BR CacheDir () +directory tree. + +.TP +--cache-disable, --no-cache +Disable the derived-file caching specified by +.BR CacheDir (). +.B scons +will neither retrieve files from the cache +nor copy files to the cache. + +.TP +--cache-force, --cache-populate +When using +.BR CacheDir (), +populate a cache by copying any already-existing, up-to-date +derived files to the cache, +in addition to files built by this invocation. +This is useful to populate a new cache with +all the current derived files, +or to add to the cache any derived files +recently built with caching disabled via the +.B --cache-disable +option. + +.TP +--cache-show +When using +.BR CacheDir () +and retrieving a derived file from the cache, +show the command +that would have been executed to build the file, +instead of the usual report, +"Retrieved `file' from cache." +This will produce consistent output for build logs, +regardless of whether a target +file was rebuilt or retrieved from the cache. + +.TP +.RI --config= mode +This specifies how the +.B Configure +call should use or generate the +results of configuration tests. +The option should be specified from +among the following choices: + +.TP +--config=auto +scons will use its normal dependency mechanisms +to decide if a test must be rebuilt or not. +This saves time by not running the same configuration tests +every time you invoke scons, +but will overlook changes in system header files +or external commands (such as compilers) +if you don't specify those dependecies explicitly. +This is the default behavior. + +.TP +--config=force +If this option is specified, +all configuration tests will be re-run +regardless of whether the +cached results are out of date. +This can be used to explicitly +force the configuration tests to be updated +in response to an otherwise unconfigured change +in a system header file or compiler. + +.TP +--config=cache +If this option is specified, +no configuration tests will be rerun +and all results will be taken from cache. +Note that scons will still consider it an error +if --config=cache is specified +and a necessary test does not +yet have any results in the cache. + +.TP +.RI "-C" " directory" ", --directory=" directory +Change to the specified +.I directory +before searching for the +.IR SConstruct , +.IR Sconstruct , +or +.I sconstruct +file, or doing anything +else. Multiple +.B -C +options are interpreted +relative to the previous one, and the right-most +.B -C +option wins. (This option is nearly +equivalent to +.BR "-f directory/SConstruct" , +except that it will search for +.IR SConstruct , +.IR Sconstruct , +or +.I sconstruct +in the specified directory.) + +.\" .TP +.\" -d +.\" Display dependencies while building target files. Useful for +.\" figuring out why a specific file is being rebuilt, as well as +.\" general debugging of the build process. + +.TP +-D +Works exactly the same way as the +.B -u +option except for the way default targets are handled. +When this option is used and no targets are specified on the command line, +all default targets are built, whether or not they are below the current +directory. + +.TP +.RI --debug= type +Debug the build process. +.I type +specifies what type of debugging: + +.TP +--debug=count +Print how many objects are created +of the various classes used internally by SCons +before and after reading the SConscript files +and before and after building targets. +This is not supported when 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 +A synonym for the newer +.B --tree=derived +option. +This will be deprecated in some future release +and ultimately removed. + +.TP +--debug=explain +Print an explanation of precisely why +.B scons +is deciding to (re-)build any targets. +(Note: this does not print anything +for targets that are +.I not +rebuilt.) + +.TP +--debug=findlibs +Instruct the scanner that searches for libraries +to print a message about each potential library +name it is searching for, +and about the actual libraries it finds. + +.TP +--debug=includes +Print the include tree after each top-level target is built. +This is generally used to find out what files are included by the sources +of a given derived file: + +.ES +$ scons --debug=includes foo.o +.EE + +.TP +--debug=memoizer +Prints a summary of hits and misses using the Memoizer, +an internal subsystem that counts +how often SCons uses cached values in memory +instead of recomputing them each time they're needed. +Only available when using Python 2.2 or later. + +.TP +--debug=memory +Prints how much memory SCons uses +before and after reading the SConscript files +and before and after building targets. + +.TP +--debug=nomemoizer +A deprecated option preserved for backwards compatibility. + +.TP +--debug=objects +Prints a list of the various objects +of the various classes used internally by SCons. +This only works when run under Python 2.1 or later. + +.TP +--debug=pdb +Re-run SCons under the control of the +.RI pdb +Python debugger. + +.TP +--debug=presub +Print the raw command line used to build each target +before the construction environment variables are substituted. +Also shows which targets are being built by this command. +Output looks something like this: +.ES +$ scons --debug=presub +Building myprog.o with action(s): + $SHCC $SHCFLAGS $SHCCFLAGS $CPPFLAGS $_CPPINCFLAGS -c -o $TARGET $SOURCES +\&... +.EE + +.TP +--debug=stacktrace +Prints an internal Python stack trace +when encountering an otherwise unexplained error. + +.TP +--debug=stree +A synonym for the newer +.B --tree=all,status +option. +This will be deprecated in some future release +and ultimately removed. + +.TP +--debug=time +Prints various time profiling information: +the time spent executing each individual build command; +the total build time (time SCons ran from beginning to end); +the total time spent reading and executing SConscript files; +the total time spent SCons itself spend running +(that is, not counting reading and executing SConscript files); +and both the total time spent executing all build commands +and the elapsed wall-clock time spent executing those build commands. +(When +.B scons +is executed without the +.B -j +option, +the elapsed wall-clock time will typically +be slightly longer than the total time spent +executing all the build commands, +due to the SCons processing that takes place +in between executing each command. +When +.B scons +is executed +.I with +the +.B -j +option, +and your build configuration allows good parallelization, +the elapsed wall-clock time should +be significantly smaller than the +total time spent executing all the build commands, +since multiple build commands and +intervening SCons processing +should take place in parallel.) + +.TP +--debug=tree +A synonym for the newer +.B --tree=all +option. +This will be deprecated in some future release +and ultimately removed. + +.TP +.RI --diskcheck= types +Enable specific checks for +whether or not there is a file on disk +where the SCons configuration expects a directory +(or vice versa), +and whether or not RCS or SCCS sources exist +when searching for source and include files. +The +.I types +argument can be set to: +.BR all , +to enable all checks explicitly +(the default behavior); +.BR none , +to disable all such checks; +.BR match , +to check that files and directories on disk +match SCons' expected configuration; +.BR rcs , +to check for the existence of an RCS source +for any missing source or include files; +.BR sccs , +to check for the existence of an SCCS source +for any missing source or include files. +Multiple checks can be specified separated by commas; +for example, +.B --diskcheck=sccs,rcs +would still check for SCCS and RCS sources, +but disable the check for on-disk matches of files and directories. +Disabling some or all of these checks +can provide a performance boost for large configurations, +or when the configuration will check for files and/or directories +across networked or shared file systems, +at the slight increased risk of an incorrect build +or of not handling errors gracefully +(if include files really should be +found in SCCS or RCS, for example, +or if a file really does exist +where the SCons configuration expects a directory). + +.TP +.RI --duplicate= ORDER +There are three ways to duplicate files in a build tree: hard links, +soft (symbolic) links and copies. The default behaviour of SCons is to +prefer hard links to soft links to copies. You can specify different +behaviours with this option. +.IR ORDER +must be one of +.IR hard-soft-copy +(the default), +.IR soft-hard-copy , +.IR hard-copy , +.IR soft-copy +or +.IR copy . +SCons will attempt to duplicate files using +the mechanisms in the specified order. + +.\" .TP +.\" -e, --environment-overrides +.\" Variables from the execution environment override construction +.\" variables from the SConscript files. + +.TP +.RI -f " file" ", --file=" file ", --makefile=" file ", --sconstruct=" file +Use +.I file +as the initial SConscript file. +Multiple +.B -f +options may be specified, +in which case +.B scons +will read all of the specified files. + +.TP +-h, --help +Print a local help message for this build, if one is defined in +the SConscript file(s), plus a line that describes the +.B -H +option for command-line option help. If no local help message +is defined, prints the standard help message about command-line +options. Exits after displaying the appropriate message. + +.TP +-H, --help-options +Print the standard help message about command-line options and +exit. + +.TP +-i, --ignore-errors +Ignore all errors from commands executed to rebuild files. + +.TP +.RI -I " directory" ", --include-dir=" directory +Specifies a +.I directory +to search for +imported Python modules. If several +.B -I +options +are used, the directories are searched in the order specified. + +.TP +--implicit-cache +Cache implicit dependencies. +This causes +.B scons +to use the implicit (scanned) dependencies +from the last time it was run +instead of scanning the files for implicit dependencies. +This can significantly speed up SCons, +but with the following limitations: +.IP +.B scons +will not detect changes to implicit dependency search paths +(e.g. +.BR CPPPATH ", " LIBPATH ) +that would ordinarily +cause different versions of same-named files to be used. +.IP +.B scons +will miss changes in the implicit dependencies +in cases where a new implicit +dependency is added earlier in the implicit dependency search path +(e.g. +.BR CPPPATH ", " LIBPATH ) +than a current implicit dependency with the same name. + +.TP +--implicit-deps-changed +Forces SCons to ignore the cached implicit dependencies. This causes the +implicit dependencies to be rescanned and recached. This implies +.BR --implicit-cache . + +.TP +--implicit-deps-unchanged +Force SCons to ignore changes in the implicit dependencies. +This causes cached implicit dependencies to always be used. +This implies +.BR --implicit-cache . + +.TP +--interactive +Starts SCons in interactive mode. +The SConscript files are read once and a +.B "scons>>>" +prompt is printed. +Targets may now be rebuilt by typing commands at interactive prompt +without having to re-read the SConscript files +and re-initialize the dependency graph from scratch. + +SCons interactive mode supports the following commands: + +.RS 10 +.TP 6 +.BI build "[OPTIONS] [TARGETS] ..." +Builds the specified +.I TARGETS +(and their dependencies) +with the specified +SCons command-line +.IR OPTIONS . +.B b +and +.B scons +are synonyms. + +The following SCons command-line options affect the +.B build +command: + +.ES +--cache-debug=FILE +--cache-disable, --no-cache +--cache-force, --cache-populate +--cache-show +--debug=TYPE +-i, --ignore-errors +-j N, --jobs=N +-k, --keep-going +-n, --no-exec, --just-print, --dry-run, --recon +-Q +-s, --silent, --quiet +--taskmastertrace=FILE +--tree=OPTIONS +.EE + +.IP "" 6 +Any other SCons command-line options that are specified +do not cause errors +but have no effect on the +.B build +command +(mainly because they affect how the SConscript files are read, +which only happens once at the beginning of interactive mode). + +.TP 6 +.BI clean "[OPTIONS] [TARGETS] ..." +Cleans the specified +.I TARGETS +(and their dependencies) +with the specified options. +.B c +is a synonym. +This command is itself a synonym for +.B "build --clean" + +.TP 6 +.BI exit +Exits SCons interactive mode. +You can also exit by terminating input +(CTRL+D on UNIX or Linux systems, +CTRL+Z on Windows systems). + +.TP 6 +.BI help "[COMMAND]" +Provides a help message about +the commands available in SCons interactive mode. +If +.I COMMAND +is specified, +.B h +and +.B ? +are synonyms. + +.TP 6 +.BI shell "[COMMANDLINE]" +Executes the specified +.I COMMANDLINE +in a subshell. +If no +.I COMMANDLINE +is specified, +executes the interactive command interpreter +specified in the +.B SHELL +environment variable +(on UNIX and Linux systems) +or the +.B COMSPEC +environment variable +(on Windows systems). +.B sh +and +.B ! +are synonyms. + +.TP 6 +.B version +Prints SCons version information. +.RE + +.IP +An empty line repeats the last typed command. +Command-line editing can be used if the +.B readline +module is available. + +.ES +$ scons --interactive +scons: Reading SConscript files ... +scons: done reading SConscript files. +scons>>> build -n prog +scons>>> exit +.EE + +.TP +.RI -j " N" ", --jobs=" N +Specifies the number of jobs (commands) to run simultaneously. +If there is more than one +.B -j +option, the last one is effective. +.\" ??? If the +.\" .B -j +.\" option +.\" is specified without an argument, +.\" .B scons +.\" will not limit the number of +.\" simultaneous jobs. + +.TP +-k, --keep-going +Continue as much as possible after an error. The target that +failed and those that depend on it will not be remade, but other +targets specified on the command line will still be processed. + +.\" .TP +.\" .RI -l " N" ", --load-average=" N ", --max-load=" N +.\" No new jobs (commands) will be started if +.\" there are other jobs running and the system load +.\" average is at least +.\" .I N +.\" (a floating-point number). + +.\" +.\" .TP +.\" --list-derived +.\" List derived files (targets, dependencies) that would be built, +.\" but do not build them. +.\" [XXX This can probably go away with the right +.\" combination of other options. Revisit this issue.] +.\" +.\" .TP +.\" --list-actions +.\" List derived files that would be built, with the actions +.\" (commands) that build them. Does not build the files. +.\" [XXX This can probably go away with the right +.\" combination of other options. Revisit this issue.] +.\" +.\" .TP +.\" --list-where +.\" List derived files that would be built, plus where the file is +.\" defined (file name and line number). Does not build the files. +.\" [XXX This can probably go away with the right +.\" combination of other options. Revisit this issue.] + +.TP +-m +Ignored for compatibility with non-GNU versions of +.BR make . + +.TP +.RI --max-drift= SECONDS +Set the maximum expected drift in the modification time of files to +.IR SECONDS . +This value determines how long a file must be unmodified +before its cached content signature +will be used instead of +calculating a new content signature (MD5 checksum) +of the file's contents. +The default value is 2 days, which means a file must have a +modification time of at least two days ago in order to have its +cached content signature used. +A negative value means to never cache the content +signature and to ignore the cached value if there already is one. A value +of 0 means to always use the cached signature, +no matter how old the file is. + +.TP +.RI --md5-chunksize= KILOBYTES +Set the block size used to compute MD5 signatures to +.IR KILOBYTES . +This value determines the size of the chunks which are read in at once when +computing MD5 signatures. Files below that size are fully stored in memory +before performing the signature computation while bigger files are read in +block-by-block. A huge block-size leads to high memory consumption while a very +small block-size slows down the build considerably. + +The default value is to use a chunk size of 64 kilobytes, which should +be appropriate for most uses. + +.TP +-n, --just-print, --dry-run, --recon +No execute. Print the commands that would be executed to build +any out-of-date target files, but do not execute the commands. + +.TP +.RI --no-site-dir +Prevents the automatic addition of the standard +.I site_scons +dir to +.IR sys.path . +Also prevents loading the +.I site_scons/site_init.py +module if it exists, and prevents adding +.I site_scons/site_tools +to the toolpath. + +.\" .TP +.\" .RI -o " file" ", --old-file=" file ", --assume-old=" file +.\" Do not rebuild +.\" .IR file , +.\" and do +.\" not rebuild anything due to changes in the contents of +.\" .IR file . +.\" .TP +.\" .RI --override " file" +.\" Read values to override specific build environment variables +.\" from the specified +.\" .IR file . +.\" .TP +.\" -p +.\" Print the data base (construction environments, +.\" Builder and Scanner objects) that are defined +.\" after reading the SConscript files. +.\" After printing, a normal build is performed +.\" as usual, as specified by other command-line options. +.\" This also prints version information +.\" printed by the +.\" .B -v +.\" option. +.\" +.\" To print the database without performing a build do: +.\" +.\" .ES +.\" scons -p -q +.\" .EE + +.TP +.RI --profile= file +Run SCons under the Python profiler +and save the results in the specified +.IR file . +The results may be analyzed using the Python +pstats module. + +.TP +-q, --question +Do not run any commands, or print anything. Just return an exit +status that is zero if the specified targets are already up to +date, non-zero otherwise. +.TP +-Q +Quiets SCons status messages about +reading SConscript files, +building targets +and entering directories. +Commands that are executed +to rebuild target files are still printed. + +.\" .TP +.\" -r, -R, --no-builtin-rules, --no-builtin-variables +.\" Clear the default construction variables. Construction +.\" environments that are created will be completely empty. + +.TP +--random +Build dependencies in a random order. This is useful when +building multiple trees simultaneously with caching enabled, +to prevent multiple builds from simultaneously trying to build +or retrieve the same target files. + +.TP +-s, --silent, --quiet +Silent. Do not print commands that are executed to rebuild +target files. +Also suppresses SCons status messages. + +.TP +-S, --no-keep-going, --stop +Ignored for compatibility with GNU +.BR make . + +.TP +.RI --site-dir= dir +Uses the named dir as the site dir rather than the default +.I site_scons +dir. This dir will get prepended to +.IR sys.path , +the module +.IR dir /site_init.py +will get loaded if it exists, and +.IR dir /site_tools +will get added to the default toolpath. + +.TP +.RI --stack-size= KILOBYTES +Set the size stack used to run threads to +.IR KILOBYTES . +This value determines the stack size of the threads used to run jobs. +These are the threads that execute the actions of the builders for the +nodes that are out-of-date. +Note that this option has no effect unless the +.B num_jobs +option, which corresponds to -j and --jobs, is larger than one. Using +a stack size that is too small may cause stack overflow errors. This +usually shows up as segmentation faults that cause scons to abort +before building anything. Using a stack size that is too large will +cause scons to use more memory than required and may slow down the entire +build process. + +The default value is to use a stack size of 256 kilobytes, which should +be appropriate for most uses. You should not need to increase this value +unless you encounter stack overflow errors. + +.TP +-t, --touch +Ignored for compatibility with GNU +.BR make . +(Touching a file to make it +appear up-to-date is unnecessary when using +.BR scons .) + +.TP +.RI --taskmastertrace= file +Prints trace information to the specified +.I file +about how the internal Taskmaster object +evaluates and controls the order in which Nodes are built. +A file name of +.B - +may be used to specify the standard output. + +.TP +.RI -tree= options +Prints a tree of the dependencies +after each top-level target is built. +This prints out some or all of the tree, +in various formats, +depending on the +.I options +specified: + +.TP +--tree=all +Print the entire dependency tree +after each top-level target is built. +This prints out the complete dependency tree, +including implicit dependencies and ignored dependencies. + +.TP +--tree=derived +Restricts the tree output to only derived (target) files, +not source files. + +.TP +--tree=status +Prints status information for each displayed node. + +.TP +--tree=prune +Prunes the tree to avoid repeating dependency information +for nodes that have already been displayed. +Any node that has already been displayed +will have its name printed in +.BR "[square brackets]" , +as an indication that the dependencies +for that node can be found by searching +for the relevant output higher up in the tree. + +.IP +Multiple options may be specified, +separated by commas: + +.ES +# Prints only derived files, with status information: +scons --tree=derived,status + +# Prints all dependencies of target, with status information +# and pruning dependencies of already-visited Nodes: +scons --tree=all,prune,status target +.EE + +.TP +-u, --up, --search-up +Walks up the directory structure until an +.I SConstruct , +.I Sconstruct +or +.I sconstruct +file is found, and uses that +as the top of the directory tree. +If no targets are specified on the command line, +only targets at or below the +current directory will be built. + +.TP +-U +Works exactly the same way as the +.B -u +option except for the way default targets are handled. +When this option is used and no targets are specified on the command line, +all default targets that are defined in the SConscript(s) in the current +directory are built, regardless of what directory the resultant targets end +up in. + +.TP +-v, --version +Print the +.B scons +version, copyright information, +list of authors, and any other relevant information. +Then exit. + +.TP +-w, --print-directory +Print a message containing the working directory before and +after other processing. + +.TP +--no-print-directory +Turn off -w, even if it was turned on implicitly. + +.TP +.RI --warn= type ", --warn=no-" type +Enable or disable warnings. +.I type +specifies the type of warnings to be enabled or disabled: + +.TP +--warn=all, --warn=no-all +Enables or disables all warnings. + +.TP +--warn=cache-write-error, --warn=no-cache-write-error +Enables or disables warnings about errors trying to +write a copy of a built file to a specified +.BR CacheDir (). +These warnings are disabled by default. + +.TP +--warn=corrupt-sconsign, --warn=no-corrupt-sconsign +Enables or disables warnings about unfamiliar signature data in +.B .sconsign +files. +These warnings are enabled by default. + +.TP +--warn=dependency, --warn=no-dependency +Enables or disables warnings about dependencies. +These warnings are disabled by default. + +.TP +--warn=deprecated, --warn=no-deprecated +Enables or disables all warnings about use of +currently deprecated features. +These warnings are enabled by default. +Note that the +.B --warn=no-deprecated +option does not disable warnings about absolutely all deprecated features. +Warnings for some deprecated features that have already been through +several releases with deprecation warnings +may be mandatory for a release or two +before they are officially no longer supported by SCons. +Warnings for some specific deprecated features +may be enabled or disabled individually; +see below. + +.RS +.TP +--warn=deprecated-copy, --warn=no-deprecated-copy +Enables or disables warnings about use of the deprecated +.B env.Copy() +method. + +.TP +--warn=deprecated-source-signatures, --warn=no-deprecated-source-signatures +Enables or disables warnings about use of the deprecated +.B SourceSignatures() +function or +.B env.SourceSignatures() +method. + +.TP +--warn=deprecated-target-signatures, --warn=no-deprecated-target-signatures +Enables or disables warnings about use of the deprecated +.B TargetSignatures() +function or +.B env.TargetSignatures() +method. +.RE + +.TP +--warn=duplicate-environment, --warn=no-duplicate-environment +Enables or disables warnings about attempts to specify a build +of a target with two different construction environments +that use the same action. +These warnings are enabled by default. + +.TP +--warn=fortran-cxx-mix, --warn=no-fortran-cxx-mix +Enables or disables the specific warning about linking +Fortran and C++ object files in a single executable, +which can yield unpredictable behavior with some compilers. + +.TP +--warn=future-deprecated, --warn=no-future-deprecated +Enables or disables warnings about features +that will be deprecated in the future. +These warnings are disabled by default. +Enabling this warning is especially +recommended for projects that redistribute +SCons configurations for other users to build, +so that the project can be warned as soon as possible +about to-be-deprecated features +that may require changes to the configuration. + +.TP +--warn=link, --warn=no-link +Enables or disables warnings about link steps. + +.TP +--warn=misleading-keywords, --warn=no-misleading-keywords +Enables or disables warnings about use of the misspelled keywords +.B targets +and +.B sources +when calling Builders. +(Note the last +.B s +characters, the correct spellings are +.B target +and +.B source.) +These warnings are enabled by default. + +.TP +--warn=missing-sconscript, --warn=no-missing-sconscript +Enables or disables warnings about missing SConscript files. +These warnings are enabled by default. + +.TP +--warn=no-md5-module, --warn=no-no-md5-module +Enables or disables warnings about the version of Python +not having an MD5 checksum module available. +These warnings are enabled by default. + +.TP +--warn=no-metaclass-support, --warn=no-no-metaclass-support +Enables or disables warnings about the version of Python +not supporting metaclasses when the +.B --debug=memoizer +option is used. +These warnings are enabled by default. + +.TP +--warn=no-object-count, --warn=no-no-object-count +Enables or disables warnings about the +.B --debug=object +feature not working when +.B scons +is run with the python +.B \-O +option or from optimized Python (.pyo) modules. + +.TP +--warn=no-parallel-support, --warn=no-no-parallel-support +Enables or disables warnings about the version of Python +not being able to support parallel builds when the +.B -j +option is used. +These warnings are enabled by default. + +.TP +--warn=python-version, --warn=no-python-version +Enables or disables the warning about running +SCons with a deprecated version of Python. +These warnings are enabled by default. + +.TP +--warn=reserved-variable, --warn=no-reserved-variable +Enables or disables warnings about attempts to set the +reserved construction variable names +.BR CHANGED_SOURCES , +.BR CHANGED_TARGETS , +.BR TARGET , +.BR TARGETS , +.BR SOURCE , +.BR SOURCES , +.BR UNCHANGED_SOURCES +or +.BR UNCHANGED_TARGETS . +These warnings are disabled by default. + +.TP +--warn=stack-size, --warn=no-stack-size +Enables or disables warnings about requests to set the stack size +that could not be honored. +These warnings are enabled by default. + +.\" .TP +.\" .RI --write-filenames= file +.\" Write all filenames considered into +.\" .IR file . +.\" +.\" .TP +.\" .RI -W " file" ", --what-if=" file ", --new-file=" file ", --assume-new=" file +.\" Pretend that the target +.\" .I file +.\" has been +.\" modified. When used with the +.\" .B -n +.\" option, this +.\" show you what would be rebuilt if you were to modify that file. +.\" Without +.\" .B -n +.\" ... what? XXX +.\" +.\" .TP +.\" --warn-undefined-variables +.\" Warn when an undefined variable is referenced. + +.TP +.RI -Y " repository" ", --repository=" repository ", --srcdir=" repository +Search the specified repository for any input and target +files not found in the local directory hierarchy. Multiple +.B -Y +options may be specified, in which case the +repositories are searched in the order specified. + +.SH CONFIGURATION FILE REFERENCE +.\" .SS Python Basics +.\" XXX Adding this in the future would be a help. +.SS Construction Environments +A construction environment is the basic means by which the SConscript +files communicate build information to +.BR scons . +A new construction environment is created using the +.B Environment +function: + +.ES +env = Environment() +.EE + +Variables, called +.I construction +.IR variables , +may be set in a construction environment +either by specifying them as keywords when the object is created +or by assigning them a value after the object is created: + +.ES +env = Environment(FOO = 'foo') +env['BAR'] = 'bar' +.EE + +As a convenience, +construction variables may also be set or modified by the +.I parse_flags +keyword argument, which applies the +.B ParseFlags +method (described below) to the argument value +after all other processing is completed. +This is useful either if the exact content of the flags is unknown +(for example, read from a control file) +or if the flags are distributed to a number of construction variables. + +.ES +env = Environment(parse_flags = '-Iinclude -DEBUG -lm') +.EE + +This example adds 'include' to +.BR CPPPATH , +\&'EBUG' to +.BR CPPDEFINES , +and 'm' to +.BR LIBS . + +By default, a new construction environment is +initialized with a set of builder methods +and construction variables that are appropriate +for the current platform. +An optional platform keyword argument may be +used to specify that an environment should +be initialized for a different platform: + +.ES +env = Environment(platform = 'cygwin') +env = Environment(platform = 'os2') +env = Environment(platform = 'posix') +env = Environment(platform = 'win32') +.EE + +Specifying a platform initializes the appropriate +construction variables in the environment +to use and generate file names with prefixes +and suffixes appropriate for the platform. + +Note that the +.B win32 +platform adds the +.B SystemDrive +and +.B SystemRoot +variables from the user's external environment +to the construction environment's +.B ENV +dictionary. +This is so that any executed commands +that use sockets to connect with other systems +(such as fetching source files from +external CVS repository specifications like +.BR :pserver:anonymous@cvs.sourceforge.net:/cvsroot/scons ) +will work on Windows systems. + +The platform argument may be function or callable object, +in which case the Environment() method +will call the specified argument to update +the new construction environment: + +.ES +def my_platform(env): + env['VAR'] = 'xyzzy' + +env = Environment(platform = my_platform) +.EE + +Additionally, a specific set of tools +with which to initialize the environment +may be specified as an optional keyword argument: + +.ES +env = Environment(tools = ['msvc', 'lex']) +.EE + +Non-built-in tools may be specified using the toolpath argument: + +.ES +env = Environment(tools = ['default', 'foo'], toolpath = ['tools']) +.EE + +This looks for a tool specification in tools/foo.py (as well as +using the ordinary default tools for the platform). foo.py should +have two functions: generate(env, **kw) and exists(env). +The +.B generate() +function +modifies the passed-in environment +to set up variables so that the tool +can be executed; +it may use any keyword arguments +that the user supplies (see below) +to vary its initialization. +The +.B exists() +function should return a true +value if the tool is available. +Tools in the toolpath are used before +any of the built-in ones. For example, adding gcc.py to the toolpath +would override the built-in gcc tool. +Also note that the toolpath is +stored in the environment for use +by later calls to +.BR Clone () +and +.BR Tool () +methods: + +.ES +base = Environment(toolpath=['custom_path']) +derived = base.Clone(tools=['custom_tool']) +derived.CustomBuilder() +.EE + +The elements of the tools list may also +be functions or callable objects, +in which case the Environment() method +will call the specified elements +to update the new construction environment: + +.ES +def my_tool(env): + env['XYZZY'] = 'xyzzy' + +env = Environment(tools = [my_tool]) +.EE + +The individual elements of the tools list +may also themselves be two-element lists of the form +.RI ( toolname ", " kw_dict ). +SCons searches for the +.I toolname +specification file as described above, and +passes +.IR kw_dict , +which must be a dictionary, as keyword arguments to the tool's +.B generate +function. +The +.B generate +function can use the arguments to modify the tool's behavior +by setting up the environment in different ways +or otherwise changing its initialization. + +.ES +# in tools/my_tool.py: +def generate(env, **kw): + # Sets MY_TOOL to the value of keyword argument 'arg1' or 1. + env['MY_TOOL'] = kw.get('arg1', '1') +def exists(env): + return 1 + +# in SConstruct: +env = Environment(tools = ['default', ('my_tool', {'arg1': 'abc'})], + toolpath=['tools']) +.EE + +The tool definition (i.e. my_tool()) can use the PLATFORM variable from +the environment it receives to customize the tool for different platforms. + +If no tool list is specified, then SCons will auto-detect the installed +tools using the PATH variable in the ENV construction variable and the +platform name when the Environment is constructed. Changing the PATH +variable after the Environment is constructed will not cause the tools to +be redetected. + +SCons supports the following tool specifications out of the box: + +.ES +386asm +aixc++ +aixcc +aixf77 +aixlink +ar +as +bcc32 +c++ +cc +cvf +dmd +dvipdf +dvips +f77 +f90 +f95 +fortran +g++ +g77 +gas +gcc +gfortran +gnulink +gs +hpc++ +hpcc +hplink +icc +icl +ifl +ifort +ilink +ilink32 +intelc +jar +javac +javah +latex +lex +link +linkloc +m4 +masm +midl +mingw +mslib +mslink +mssdk +msvc +msvs +mwcc +mwld +nasm +pdflatex +pdftex +qt +rmic +rpcgen +sgiar +sgic++ +sgicc +sgilink +sunar +sunc++ +suncc +sunf77 +sunf90 +sunf95 +sunlink +swig +tar +tex +textfile +tlib +yacc +zip +.EE + +Additionally, there is a "tool" named +.B default +which configures the +environment with a default set of tools for the current platform. + +On posix and cygwin platforms +the GNU tools (e.g. gcc) are preferred by SCons, +on Windows the Microsoft tools (e.g. msvc) +followed by MinGW are preferred by SCons, +and in OS/2 the IBM tools (e.g. icc) are preferred by SCons. + +.SS Builder Methods + +Build rules are specified by calling a construction +environment's builder methods. +The arguments to the builder methods are +.B target +(a list of targets to be built, +usually file names) +and +.B source +(a list of sources to be built, +usually file names). + +Because long lists of file names +can lead to a lot of quoting, +.B scons +supplies a +.B Split() +global function +and a same-named environment method +that split a single string +into a list, separated on +strings of white-space characters. +(These are similar to the +string.split() method +from the standard Python library, +but work even if the input isn't a string.) + +Like all Python arguments, +the target and source arguments to a builder method +can be specified either with or without +the "target" and "source" keywords. +When the keywords are omitted, +the target is first, +followed by the source. +The following are equivalent examples of calling the Program builder method: + +.ES +env.Program('bar', ['bar.c', 'foo.c']) +env.Program('bar', Split('bar.c foo.c')) +env.Program('bar', env.Split('bar.c foo.c')) +env.Program(source = ['bar.c', 'foo.c'], target = 'bar') +env.Program(target = 'bar', Split('bar.c foo.c')) +env.Program(target = 'bar', env.Split('bar.c foo.c')) +env.Program('bar', source = 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, +then the target argument may be omitted completely, +and +.B scons +will deduce the target file name from +the source file name. +The following examples all build the +executable program +.B bar +(on POSIX systems) +or +.B bar.exe +(on Windows systems) +from the bar.c source file: + +.ES +env.Program(target = 'bar', source = 'bar.c') +env.Program('bar', source = 'bar.c') +env.Program(source = 'bar.c') +env.Program('bar.c') +.EE + +As a convenience, a +.B srcdir +keyword argument may be specified +when calling a Builder. +When specified, +all source file strings that are not absolute paths +will be interpreted relative to the specified +.BR srcdir . +The following example will build the +.B build/prog +(or +.B build/prog.exe +on Windows) +program from the files +.B src/f1.c +and +.BR src/f2.c : + +.ES +env.Program('build/prog', ['f1.c', 'f2.c'], srcdir='src') +.EE + +It is possible to override or add construction variables when calling a +builder method by passing additional keyword arguments. +These overridden or added +variables will only be in effect when building the target, so they will not +affect other parts of the build. For example, if you want to add additional +libraries for just one program: + +.ES +env.Program('hello', 'hello.c', LIBS=['gl', 'glut']) +.EE + +or generate a shared library with a non-standard suffix: + +.ES +env.SharedLibrary('word', 'word.cpp', + SHLIBSUFFIX='.ocx', + LIBSUFFIXES=['.ocx']) +.EE + +(Note that both the $SHLIBSUFFIX and $LIBSUFFIXES variables must be set +if you want SCons to search automatically +for dependencies on the non-standard library names; +see the descriptions of these variables, below, for more information.) + +It is also possible to use the +.I parse_flags +keyword argument in an override: + +.ES +env = Program('hello', 'hello.c', parse_flags = '-Iinclude -DEBUG -lm') +.EE + +This example adds 'include' to +.BR CPPPATH , +\&'EBUG' to +.BR CPPDEFINES , +and 'm' to +.BR LIBS . + +Although the builder methods defined by +.B scons +are, in fact, +methods of a construction environment object, +they may also be called without an explicit environment: + +.ES +Program('hello', 'hello.c') +SharedLibrary('word', 'word.cpp') +.EE + +In this case, +the methods are called internally using a default construction +environment that consists of the tools and values that +.B scons +has determined are appropriate for the local system. + +Builder methods that can be called without an explicit +environment may be called from custom Python modules that you +import into an SConscript file by adding the following +to the Python module: + +.ES +from SCons.Script import * +.EE + +All builder methods return a list-like object +containing Nodes that +represent the target or targets that will be built. +A +.I Node +is an internal SCons object +which represents +build targets or sources. + +The returned Node-list object +can be passed to other builder methods as source(s) +or passed to any SCons function or method +where a filename would normally be accepted. +For example, if it were necessary +to add a specific +.B -D +flag when compiling one specific object file: + +.ES +bar_obj_list = env.StaticObject('bar.c', CPPDEFINES='-DBAR') +env.Program(source = ['foo.c', bar_obj_list, 'main.c']) +.EE + +Using a Node in this way +makes for a more portable build +by avoiding having to specify +a platform-specific object suffix +when calling the Program() builder method. + +Note that Builder calls will automatically "flatten" +the source and target file lists, +so it's all right to have the bar_obj list +return by the StaticObject() call +in the middle of the source file list. +If you need to manipulate a list of lists returned by Builders +directly using Python, +you can either build the list by hand: + +.ES +foo = Object('foo.c') +bar = Object('bar.c') +objects = ['begin.o'] + foo + ['middle.o'] + bar + ['end.o'] +for object in objects: + print str(object) +.EE + +Or you can use the +.BR Flatten () +function supplied by scons +to create a list containing just the Nodes, +which may be more convenient: + +.ES +foo = Object('foo.c') +bar = Object('bar.c') +objects = Flatten(['begin.o', foo, 'middle.o', bar, 'end.o']) +for object in objects: + print str(object) +.EE + +Note also that because Builder calls return +a list-like object, not an actual Python list, +you should +.I not +use the Python +.B += +operator to append Builder results to a Python list. +Because the list and the object are different types, +Python will not update the original list in place, +but will instead create a new Node-list object +containing the concatenation of the list +elements and the Builder results. +This will cause problems for any other Python variables +in your SCons configuration +that still hold on to a reference to the original list. +Instead, use the Python +.B .extend() +method to make sure the list is updated in-place. +Example: + +.ES +object_files = [] + +# Do NOT use += as follows: +# +# object_files += Object('bar.c') +# +# It will not update the object_files list in place. +# +# Instead, use the .extend() method: +object_files.extend(Object('bar.c')) + +.EE + +The path name for a Node's file may be used +by passing the Node to the Python-builtin +.B str() +function: + +.ES +bar_obj_list = env.StaticObject('bar.c', CPPDEFINES='-DBAR') +print "The path to bar_obj is:", str(bar_obj_list[0]) +.EE + +Note again that because the Builder call returns a list, +we have to access the first element in the list +.B (bar_obj_list[0]) +to get at the Node that actually represents +the object file. + +Builder calls support a +.B chdir +keyword argument that +specifies that the Builder's action(s) +should be executed +after changing directory. +If the +.B chdir +argument is +a string or a directory Node, +scons will change to the specified directory. +If the +.B chdir +is not a string or Node +and is non-zero, +then scons will change to the +target file's directory. + +.ES +# scons will change to the "sub" subdirectory +# before executing the "cp" command. +env.Command('sub/dir/foo.out', 'sub/dir/foo.in', + "cp dir/foo.in dir/foo.out", + chdir='sub') + +# Because chdir is not a string, scons will change to the +# target's directory ("sub/dir") before executing the +# "cp" command. +env.Command('sub/dir/foo.out', 'sub/dir/foo.in', + "cp foo.in foo.out", + chdir=1) +.EE + +Note that scons will +.I not +automatically modify +its expansion of +construction variables like +.B $TARGET +and +.B $SOURCE +when using the chdir +keyword argument--that is, +the expanded file names +will still be relative to +the top-level SConstruct directory, +and consequently incorrect +relative to the chdir directory. +If you use the chdir keyword argument, +you will typically need to supply a different +command line using +expansions like +.B ${TARGET.file} +and +.B ${SOURCE.file} +to use just the filename portion of the +targets and source. + +.B scons +provides the following builder methods: + +'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +'\" BEGIN GENERATED BUILDER DESCRIPTIONS +'\" +'\" The descriptions below of the various SCons Builders are generated +'\" from the .xml files that live next to the various Python modules in +'\" the build enginer library. If you're reading this [gnt]roff file +'\" with an eye towards patching this man page, you can still submit +'\" a diff against this text, but it will have to be translated to a +'\" diff against the underlying .xml file before the patch is actually +'\" accepted. If you do that yourself, it will make it easier to +'\" integrate the patch. +'\" +'\" BEGIN GENERATED BUILDER DESCRIPTIONS +'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" + +'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.IP CFile() +.IP env.CFile() +Builds a C source file given a lex (\fB.l\fP) +or yacc (\fB.y\fP) input file. +The suffix specified by the $CFILESUFFIX construction variable +(\fB.c\fP by default) +is automatically added to the target +if it is not already present. +Example: + +.ES +# builds foo.c +env.CFile(target = 'foo.c', source = 'foo.l') +# builds bar.c +env.CFile(target = 'bar', source = 'bar.y') +.EE +.IP +'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.IP CXXFile() +.IP env.CXXFile() +Builds a C++ source file given a lex (\fB.ll\fP) +or yacc (\fB.yy\fP) +input file. +The suffix specified by the $CXXFILESUFFIX construction variable +(\fB.cc\fP by default) +is automatically added to the target +if it is not already present. +Example: + +.ES +# builds foo.cc +env.CXXFile(target = 'foo.cc', source = 'foo.ll') +# builds bar.cc +env.CXXFile(target = 'bar', source = 'bar.yy') +.EE +.IP +'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.IP DVI() +.IP env.DVI() +Builds a \fB.dvi\fP file +from a \fB.tex\fP, +\fB.ltx\fP or \fB.latex\fP input file. +If the source file suffix is \fB.tex\fP, +.B scons +will examine the contents of the file; +if the string +.B \\documentclass +or +.B \\documentstyle +is found, the file is assumed to be a LaTeX file and +the target is built by invoking the $LATEXCOM command line; +otherwise, the $TEXCOM command line is used. +If the file is a LaTeX file, +the +.BR DVI () +builder method will also examine the contents +of the +.B .aux +file and invoke the $BIBTEX command line +if the string +.B bibdata +is found, +start $MAKEINDEX to generate an index if a +.B .ind +file is found +and will examine the contents +.B .log +file and re-run the $LATEXCOM command +if the log file says it is necessary. + +The suffix \fB.dvi\fP +(hard-coded within TeX itself) +is automatically added to the target +if it is not already present. +Examples: + +.ES +# builds from aaa.tex +env.DVI(target = 'aaa.dvi', source = 'aaa.tex') +# builds bbb.dvi +env.DVI(target = 'bbb', source = 'bbb.ltx') +# builds from ccc.latex +env.DVI(target = 'ccc.dvi', source = 'ccc.latex') +.EE +.IP +'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.IP Install() +.IP env.Install() +Installs one or more source files or directories +in the specified target, +which must be a directory. +The names of the specified source files or directories +remain the same within the destination directory. + +.ES +env.Install('/usr/local/bin', source = ['foo', 'bar']) +.EE +.IP +'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.IP InstallAs() +.IP env.InstallAs() +Installs one or more source files or directories +to specific names, +allowing changing a file or directory name +as part of the installation. +It is an error if the +target +and +source +arguments list different numbers of files or directories. + +.ES +env.InstallAs(target = '/usr/local/bin/foo', + source = 'foo_debug') +env.InstallAs(target = ['../lib/libfoo.a', '../lib/libbar.a'], + source = ['libFOO.a', 'libBAR.a']) +.EE +.IP +'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.IP Jar() +.IP env.Jar() +Builds a Java archive (\fB.jar\fP) file +from the specified list of sources. +Any directories in the source list +will be searched for \fB.class\fP files). +Any \fB.java\fP files in the source list +will be compiled to \fB.class\fP files +by calling the \fBJava\fP() Builder. + +If the $JARCHDIR value is set, the +.B jar +command will change to the specified directory using the +.B \-C +option. +If $JARCHDIR is not set explicitly, +&SCons; will use the top of any subdirectory tree +in which Java \fB.class\fP +were built by the \fBJava\fP() Builder. + +If the contents any of the source files begin with the string +.BR Manifest-Version , +the file is assumed to be a manifest +and is passed to the +.B jar +command with the +.B m +option set. + +.ES +env.Jar(target = 'foo.jar', source = 'classes') + +env.Jar(target = 'bar.jar', + source = ['bar1.java', 'bar2.java']) +.EE +.IP +'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.IP Java() +.IP env.Java() +Builds one or more Java class files. +The sources may be any combination of explicit +\fB.java\fP files, +or directory trees which will be scanned +for \fB.java\fP files. + +SCons will parse each source \fB.java\fP file +to find the classes +(including inner classes) +defined within that file, +and from that figure out the +target \fB.class\fP files that will be created. +The class files will be placed underneath +the specified target directory. + +SCons will also search each Java file +for the Java package name, +which it assumes can be found on a line +beginning with the string +.B package +in the first column; +the resulting \fB.class\fP files +will be placed in a directory reflecting +the specified package name. +For example, +the file +.B Foo.java +defining a single public +.I Foo +class and +containing a package name of +.I sub.dir +will generate a corresponding +.B sub/dir/Foo.class +class file. + +Examples: + +.ES +env.Java(target = 'classes', source = 'src') +env.Java(target = 'classes', source = ['src1', 'src2']) +env.Java(target = 'classes', source = ['File1.java', 'File2.java']) +.EE +.IP +Java source files can use the native encoding for the underlying OS. +Since SCons compiles in simple ASCII mode by default, +the compiler will generate warnings about unmappable characters, +which may lead to errors as the file is processed further. +In this case, the user must specify the \fBLANG\fP +environment variable to tell the compiler what encoding is used. +For portibility, it's best if the encoding is hard-coded +so that the compile will work if it is done on a system +with a different encoding. + +.ES +env = Environment() +env['ENV']['LANG'] = 'en_GB.UTF-8' +.EE +.IP +'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.IP JavaH() +.IP env.JavaH() +Builds C header and source files for +implementing Java native methods. +The target can be either a directory +in which the header files will be written, +or a header file name which +will contain all of the definitions. +The source can be the names of \fB.class\fP files, +the names of \fB.java\fP files +to be compiled into \fB.class\fP files +by calling the \fBJava\fP() builder method, +or the objects returned from the +.BR Java () +builder method. + +If the construction variable +$JAVACLASSDIR +is set, either in the environment +or in the call to the +.BR JavaH () +builder method itself, +then the value of the variable +will be stripped from the +beginning of any \fB.class\fP file names. + +Examples: + +.ES +# builds java_native.h +classes = env.Java(target = 'classdir', source = 'src') +env.JavaH(target = 'java_native.h', source = classes) + +# builds include/package_foo.h and include/package_bar.h +env.JavaH(target = 'include', + source = ['package/foo.class', 'package/bar.class']) + +# builds export/foo.h and export/bar.h +env.JavaH(target = 'export', + source = ['classes/foo.class', 'classes/bar.class'], + JAVACLASSDIR = 'classes') +.EE +.IP +'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.IP Library() +.IP env.Library() +A synonym for the +.BR StaticLibrary () +builder method. + +'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.IP LoadableModule() +.IP env.LoadableModule() +On most systems, +this is the same as +.BR SharedLibrary (). +On Mac OS X (Darwin) platforms, +this creates a loadable module bundle. + +'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.IP M4() +.IP env.M4() +Builds an output file from an M4 input file. +This uses a default $M4FLAGS value of +.BR \-E , +which considers all warnings to be fatal +and stops on the first warning +when using the GNU version of m4. +Example: + +.ES +env.M4(target = 'foo.c', source = 'foo.c.m4') +.EE +.IP +'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.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 +'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.IP MSVSProject() +.IP env.MSVSProject() +Builds a Microsoft Visual Studio project file, +and by default builds a solution file as well. + +This builds a Visual Studio project file, based on the version of +Visual Studio that is configured (either the latest installed version, +or the version specified by +$MSVS_VERSION +in the Environment constructor). +For Visual Studio 6, it will generate a +.B .dsp +file. +For Visual Studio 7 (.NET) and later versions, it will generate a +.B .vcproj +file. + +By default, +this also generates a solution file +for the specified project, +a +.B .dsw +file for Visual Studio 6 +or a +.B .sln +file for Visual Studio 7 (.NET). +This behavior may be disabled by specifying +.B auto_build_solution=0 +when you call +.BR MSVSProject (), +in which case you presumably want to +build the solution file(s) +by calling the +.BR MSVSSolution () +Builder (see below). + +The \fBMSVSProject\fP() builder +takes several lists of filenames +to be placed into the project file. +These are currently limited to +.BR srcs , +.BR incs , +.BR localincs , +.BR resources , +and +.BR misc . +These are pretty self-explanatory, but it should be noted that these +lists are added to the $SOURCES construction variable as strings, +NOT as SCons File Nodes. This is because they represent file +names to be added to the project file, not the source files used to +build the project file. + +The above filename lists are all optional, +although at least one must be specified +for the resulting project file to be non-empty. + +In addition to the above lists of values, +the following values may be specified: + +.BR target : +The name of the target +.B .dsp +or +.B .vcproj +file. +The correct +suffix for the version of Visual Studio must be used, +but the +$MSVSPROJECTSUFFIX +construction variable +will be defined to the correct value (see example below). + +.BR variant : +The name of this particular variant. +For Visual Studio 7 projects, +this can also be a list of variant names. +These are typically things like "Debug" or "Release", but really +can be anything you want. +For Visual Studio 7 projects, +they may also specify a target platform +separated from the variant name by a +.B | +(vertical pipe) +character: +.BR Debug|Xbox . +The default target platform is Win32. +Multiple calls to +.BR MSVSProject () +with different variants are allowed; +all variants will be added to the project file with their appropriate +build targets and sources. + +.BR buildtarget : +An optional string, node, or list of strings or nodes +(one per build variant), to tell the Visual Studio debugger +what output target to use in what build variant. +The number of +.B buildtarget +entries must match the number of +.B variant +entries. + +.BR runfile : +The name of the file that Visual Studio 7 and later +will run and debug. +This appears as the value of the +.B Output +field in the resutling Visual Studio project file. +If this is not specified, +the default is the same as the specified +.B buildtarget +value. + +Note that because &SCons; always executes its build commands +from the directory in which the \fBSConstruct\fP file is located, +if you generate a project file in a different directory +than the \fBSConstruct\fP directory, +users will not be able to double-click +on the file name in compilation error messages +displayed in the Visual Studio console output window. +This can be remedied by adding the +Visual C/C++ +.B /FC +compiler option to the $CCFLAGS variable +so that the compiler will print +the full path name of any +files that cause compilation errors. + +Example usage: + +.ES +barsrcs = ['bar.cpp'], +barincs = ['bar.h'], +barlocalincs = ['StdAfx.h'] +barresources = ['bar.rc','resource.h'] +barmisc = ['bar_readme.txt'] + +dll = env.SharedLibrary(target = 'bar.dll', + source = barsrcs) + +env.MSVSProject(target = 'Bar' + env['MSVSPROJECTSUFFIX'], + srcs = barsrcs, + incs = barincs, + localincs = barlocalincs, + resources = barresources, + misc = barmisc, + buildtarget = dll, + variant = 'Release') +.EE +.IP +'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.IP MSVSSolution() +.IP env.MSVSSolution() +Builds a Microsoft Visual Studio solution file. + +This builds a Visual Studio solution file, +based on the version of Visual Studio that is configured +(either the latest installed version, +or the version specified by +$MSVS_VERSION +in the construction environment). +For Visual Studio 6, it will generate a +.B .dsw +file. +For Visual Studio 7 (.NET), it will +generate a +.B .sln +file. + +The following values must be specified: + +.BR target : +The name of the target .dsw or .sln file. The correct +suffix for the version of Visual Studio must be used, but the value +$MSVSSOLUTIONSUFFIX +will be defined to the correct value (see example below). + +.BR variant : +The name of this particular variant, or a list of variant +names (the latter is only supported for MSVS 7 solutions). These are +typically things like "Debug" or "Release", but really can be anything +you want. For MSVS 7 they may also specify target platform, like this +"Debug|Xbox". Default platform is Win32. + +.BR projects : +A list of project file names, or Project nodes returned by calls to the +.BR MSVSProject () +Builder, +to be placed into the solution file. +It should be noted that these file names are NOT added to the $SOURCES +environment variable in form of files, but rather as strings. This +is because they represent file names to be added to the solution file, +not the source files used to build the solution file. + +(NOTE: Currently only one project is supported per solution.) + +Example Usage: + +.ES +env.MSVSSolution(target = 'Bar' + env['MSVSSOLUTIONSUFFIX'], + projects = ['bar' + env['MSVSPROJECTSUFFIX']], + variant = 'Release') +.EE +.IP +'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.IP Object() +.IP env.Object() +A synonym for the +.BR StaticObject () +builder method. + +'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.IP Package() +.IP env.Package() +Builds software distribution packages. +Packages consist of files to install and packaging information. +The former may be specified with the \fIsource\fP parameter and may be left out, +in which case the &FindInstalledFiles; function will collect +all files that have an \fBInstall\fP() or \fBInstallAs\fP() Builder attached. +If the \fItarget\fP is not specified +it will be deduced from additional information given to this Builder. + +The packaging information is specified +with the help of construction variables documented below. +This information is called a tag to stress that +some of them can also be attached to files with the &Tag; function. +The mandatory ones will complain if they were not specified. +They vary depending on chosen target packager. + +The target packager may be selected with the "PACKAGETYPE" command line +option or with the $PACKAGETYPE construction variable. Currently +the following packagers available: + + * msi - Microsoft Installer + * rpm - Redhat Package Manger + * ipkg - Itsy Package Management System + * tarbz2 - compressed tar + * targz - compressed tar + * zip - zip file + * src_tarbz2 - compressed tar source + * src_targz - compressed tar source + * src_zip - zip file source + +An updated list is always available under the "package_type" option when +running "scons --help" on a project that has packaging activated. +.ES +env = Environment(tools=['default', 'packaging']) +env.Install('/bin/', 'my_program') +env.Package( NAME = 'foo', + VERSION = '1.2.3', + PACKAGEVERSION = 0, + PACKAGETYPE = 'rpm', + LICENSE = 'gpl', + SUMMARY = 'balalalalal', + DESCRIPTION = 'this should be really really long', + X_RPM_GROUP = 'Application/fu', + SOURCE_URL = 'http://foo.org/foo-1.2.3.tar.gz' + ) +.EE +.IP +'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.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 +'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.IP PDF() +.IP env.PDF() +Builds a \fB.pdf\fP file +from a \fB.dvi\fP input file +(or, by extension, a \fB.tex\fP, +.BR .ltx , +or +\fB.latex\fP input file). +The suffix specified by the $PDFSUFFIX construction variable +(\fB.pdf\fP by default) +is added automatically to the target +if it is not already present. Example: + +.ES +# builds from aaa.tex +env.PDF(target = 'aaa.pdf', source = 'aaa.tex') +# builds bbb.pdf from bbb.dvi +env.PDF(target = 'bbb', source = 'bbb.dvi') +.EE +.IP +'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.IP PostScript() +.IP env.PostScript() +Builds a \fB.ps\fP file +from a \fB.dvi\fP input file +(or, by extension, a \fB.tex\fP, +.BR .ltx , +or +\fB.latex\fP input file). +The suffix specified by the $PSSUFFIX construction variable +(\fB.ps\fP by default) +is added automatically to the target +if it is not already present. Example: + +.ES +# builds from aaa.tex +env.PostScript(target = 'aaa.ps', source = 'aaa.tex') +# builds bbb.ps from bbb.dvi +env.PostScript(target = 'bbb', source = 'bbb.dvi') +.EE +.IP +'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.IP Program() +.IP env.Program() +Builds an executable given one or more object files +or C, C++, D, or Fortran source files. +If any C, C++, D or Fortran source files are specified, +then they will be automatically +compiled to object files using the +.BR Object () +builder method; +see that builder method's description for +a list of legal source file suffixes +and how they are interpreted. +The target executable file prefix +(specified by the $PROGPREFIX construction variable; nothing by default) +and suffix +(specified by the $PROGSUFFIX construction variable; +by default, \fB.exe\fP on Windows systems, +nothing on POSIX systems) +are automatically added to the target if not already present. +Example: + +.ES +env.Program(target = 'foo', source = ['foo.o', 'bar.c', 'baz.f']) +.EE +.IP +'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.IP RES() +.IP env.RES() +Builds a Microsoft Visual C++ resource file. +This builder method is only provided +when Microsoft Visual C++ or MinGW is being used as the compiler. The +.B .res +(or +.B .o +for MinGW) suffix is added to the target name if no other suffix is given. +The source +file is scanned for implicit dependencies as though it were a C file. +Example: + +.ES +env.RES('resource.rc') +.EE +.IP +'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.IP RMIC() +.IP env.RMIC() +Builds stub and skeleton class files +for remote objects +from Java \fB.class\fP files. +The target is a directory +relative to which the stub +and skeleton class files will be written. +The source can be the names of \fB.class\fP files, +or the objects return from the +.BR Java () +builder method. + +If the construction variable +$JAVACLASSDIR +is set, either in the environment +or in the call to the +.BR RMIC () +builder method itself, +then the value of the variable +will be stripped from the +beginning of any \fB.class \fP +file names. + +.ES +classes = env.Java(target = 'classdir', source = 'src') +env.RMIC(target = 'outdir1', source = classes) + +env.RMIC(target = 'outdir2', + source = ['package/foo.class', 'package/bar.class']) + +env.RMIC(target = 'outdir3', + source = ['classes/foo.class', 'classes/bar.class'], + JAVACLASSDIR = 'classes') +.EE +.IP +'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.IP RPCGenClient() +.IP env.RPCGenClient() +Generates an RPC client stub (\fB_clnt.c\fP) file +from a specified RPC (\fB.x\fP) source file. +Because rpcgen only builds output files +in the local directory, +the command will be executed +in the source file's directory by default. + +.ES +# Builds src/rpcif_clnt.c +env.RPCGenClient('src/rpcif.x') +.EE +.IP +'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.IP RPCGenHeader() +.IP env.RPCGenHeader() +Generates an RPC header (\fB.h\fP) file +from a specified RPC (\fB.x\fP) source file. +Because rpcgen only builds output files +in the local directory, +the command will be executed +in the source file's directory by default. + +.ES +# Builds src/rpcif.h +env.RPCGenHeader('src/rpcif.x') +.EE +.IP +'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.IP RPCGenService() +.IP env.RPCGenService() +Generates an RPC server-skeleton (\fB_svc.c\fP) file +from a specified RPC (\fB.x\fP) source file. +Because rpcgen only builds output files +in the local directory, +the command will be executed +in the source file's directory by default. + +.ES +# Builds src/rpcif_svc.c +env.RPCGenClient('src/rpcif.x') +.EE +.IP +'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.IP RPCGenXDR() +.IP env.RPCGenXDR() +Generates an RPC XDR routine (\fB_xdr.c\fP) file +from a specified RPC (\fB.x\fP) source file. +Because rpcgen only builds output files +in the local directory, +the command will be executed +in the source file's directory by default. + +.ES +# Builds src/rpcif_xdr.c +env.RPCGenClient('src/rpcif.x') +.EE +.IP +'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.IP SharedLibrary() +.IP env.SharedLibrary() +Builds a shared library +(\fB.so\fP on a POSIX system, +\fB.dll\fP on Windows) +given one or more object files +or C, C++, D or Fortran source files. +If any source files are given, +then they will be automatically +compiled to object files. +The static library prefix and suffix (if any) +are automatically added to the target. +The target library file prefix +(specified by the $SHLIBPREFIX construction variable; +by default, \fBlib\fP on POSIX systems, +nothing on Windows systems) +and suffix +(specified by the $SHLIBSUFFIX construction variable; +by default, \fB.dll\fP on Windows systems, +\fB.so\fP on POSIX systems) +are automatically added to the target if not already present. +Example: + +.ES +env.SharedLibrary(target = 'bar', source = ['bar.c', 'foo.o']) +.EE +.IP +On Windows systems, the +.BR SharedLibrary () +builder method will always build an import +(\fB.lib\fP) library +in addition to the shared (\fB.dll\fP) library, +adding a \fB.lib\fP library with the same basename +if there is not already a \fB.lib\fP file explicitly +listed in the targets. + +Any object files listed in the +.B source +must have been built for a shared library +(that is, using the +.BR SharedObject () +builder method). +.B scons +will raise an error if there is any mismatch. + +On some platforms, there is a distinction between a shared library +(loaded automatically by the system to resolve external references) +and a loadable module (explicitly loaded by user action). +For maximum portability, use the \fBLoadableModule\fP() builder for the latter. + +On Windows systems, specifying +.B register=1 +will cause the \fB.dll\fP to be +registered after it is built using REGSVR32. +The command that is run +("regsvr32" by default) is determined by $REGSVR construction +variable, and the flags passed are determined by $REGSVRFLAGS. By +default, $REGSVRFLAGS includes the \fB/s\fP option, +to prevent dialogs from popping +up and requiring user attention when it is run. If you change +$REGSVRFLAGS, be sure to include the \fB/s\fP option. +For example, + +.ES +env.SharedLibrary(target = 'bar', + source = ['bar.cxx', 'foo.obj'], + register=1) +.EE +.IP +will register \fBbar.dll\fP as a COM object +when it is done linking it. + +'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.IP SharedObject() +.IP env.SharedObject() +Builds an object file for +inclusion in a shared library. +Source files must have one of the same set of extensions +specified above for the +.BR StaticObject () +builder method. +On some platforms building a shared object requires additional +compiler option +(e.g. \fB\-fPIC\fP for gcc) +in addition to those needed to build a +normal (static) object, but on some platforms there is no difference between a +shared object and a normal (static) one. When there is a difference, SCons +will only allow shared objects to be linked into a shared library, and will +use a different suffix for shared objects. On platforms where there is no +difference, SCons will allow both normal (static) +and shared objects to be linked into a +shared library, and will use the same suffix for shared and normal +(static) objects. +The target object file prefix +(specified by the $SHOBJPREFIX construction variable; +by default, the same as $OBJPREFIX) +and suffix +(specified by the $SHOBJSUFFIX construction variable) +are automatically added to the target if not already present. +Examples: + +.ES +env.SharedObject(target = 'ddd', source = 'ddd.c') +env.SharedObject(target = 'eee.o', source = 'eee.cpp') +env.SharedObject(target = 'fff.obj', source = 'fff.for') +.EE +.IP +Note that the source files will be scanned +according to the suffix mappings in the +.B SourceFileScanner +object. +See the section "Scanner Objects," +below, for 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, \fBlib\fP on POSIX systems, +nothing on Windows systems) +and suffix +(specified by the $LIBSUFFIX construction variable; +by default, \fB.lib\fP on Windows systems, +\fB.a\fP on POSIX systems) +are automatically added to the target if not already present. +Example: + +.ES +env.StaticLibrary(target = 'bar', source = ['bar.c', 'foo.o']) +.EE +.IP +Any object files listed in the +.B source +must have been built for a static library +(that is, using the +.BR StaticObject () +builder method). +.B scons +will raise an error if there is any mismatch. + +'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.IP StaticObject() +.IP env.StaticObject() +Builds a static object file +from one or more C, C++, D, or Fortran source files. +Source files must have one of the following extensions: + +.ES + .asm assembly language file + .ASM assembly language file + .c C file + .C Windows: C file + POSIX: C++ file + .cc C++ file + .cpp C++ file + .cxx C++ file + .cxx C++ file + .c++ C++ file + .C++ C++ file + .d D file + .f Fortran file + .F Windows: Fortran file + POSIX: Fortran file + C pre-processor + .for Fortran file + .FOR Fortran file + .fpp Fortran file + C pre-processor + .FPP Fortran file + C pre-processor + .m Object C file + .mm Object C++ file + .s assembly language file + .S Windows: assembly language file + ARM: CodeSourcery Sourcery Lite + .sx assembly language file + C pre-processor + POSIX: assembly language file + C pre-processor + .spp assembly language file + C pre-processor + .SPP assembly language file + C pre-processor +.EE +.IP +The target object file prefix +(specified by the $OBJPREFIX construction variable; nothing by default) +and suffix +(specified by the $OBJSUFFIX construction variable; +\fB.obj\fP on Windows systems, +\fB.o\fP on POSIX systems) +are automatically added to the target if not already present. +Examples: + +.ES +env.StaticObject(target = 'aaa', source = 'aaa.c') +env.StaticObject(target = 'bbb.o', source = 'bbb.c++') +env.StaticObject(target = 'ccc.obj', source = 'ccc.f') +.EE +.IP +Note that the source files will be scanned +according to the suffix mappings in +.B SourceFileScanner +object. +See the section "Scanner Objects," +below, for a more information. + +'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.IP Substfile() +.IP env.Substfile() +The \fBSubstfile\fP() builder generates a single text file +by concatenating the source files. +Nested lists of sources are flattened. +$LINESEPARATOR is used to separate the source files; +see the description of \fBTextfile\fP() for details. + +If a single source file is present with an \fB.in\fP suffix, +the suffix is stripped and the remainder is used as the default target name. + +The prefix and suffix specified by the $SUBSTFILEPREFIX +and $SUBSTFILESUFFIX construction variables +(the null string by default in both cases) +are automatically added to the target if they are not already present. + +If a construction variable named $SUBST_DICT is present, +it may be either a Python dictionary or a sequence of (key,value) tuples. +If the former, +the dictionary is converted into a list of tuples in an arbitrary order, +so if one key is a prefix of another key +or if one substitution could be further expanded by another subsitition, +it is unpredictible whether the expansion will occur. + +Any occurences in the source of a key +are replaced by the corresponding value, +which may be a Python callable function or a string. +If a value is a function, +it is first called (with no arguments) to produce a string. +The string is \fIsubst\fP-expanded +and the result replaces the key. + +.ES +env = Environment(tools = ['default', 'textfile']) + +env['prefix'] = '/usr/bin' +script_dict = {'@prefix@': '/bin', @exec_prefix@: '$prefix'} +env.Substfile('script.in', SUBST_DICT = script_dict) + +conf_dict = {'%VERSION%': '1.2.3', '%BASE%': 'MyProg'} +env.Substfile('config.h.in', conf_dict, SUBST_DICT = conf_dict) + +# UNPREDICTABLE - one key is a prefix of another +bad_foo = {'$foo': '$foo', '$foobar': '$foobar'} +env.Substfile('foo.in', SUBST_DICT = bad_foo) + +# PREDICTABLE - keys are applied longest first +good_foo = [('$foobar', '$foobar'), ('$foo', '$foo')] +env.Substfile('foo.in', SUBST_DICT = good_foo) + +# UNPREDICTABLE - one substitution could be futher expanded +bad_bar = {'@bar@': '@soap@', '@soap@': 'lye'} +env.Substfile('bar.in', SUBST_DICT = bad_bar) + +# PREDICTABLE - substitutions are expanded in order +good_bar = (('@bar@', '@soap@'), ('@soap@', 'lye')) +env.Substfile('bar.in', SUBST_DICT = good_bar) + +# the SUBST_DICT may be in common (and not an override) +substutions = {} +subst = Environment(tools = ['textfile', SUBST_DICT = substitutions) +substitutions['@foo@'] = 'foo' +subst['SUBST_DICT']['@bar@'] = 'bar' +subst.Substfile('pgm1.c', [Value('#include "@foo@.h"'), + Value('#include "@bar@.h"'), + "common.in", + "pgm1.in" + ]) +subst.Substfile('pgm2.c', [Value('#include "@foo@.h"'), + Value('#include "@bar@.h"'), + "common.in", + "pgm2.in" + ]) + +.EE +.IP +'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.IP Tar() +.IP env.Tar() +Builds a tar archive of the specified files +and/or directories. +Unlike most builder methods, +the +.BR Tar () +builder method may be called multiple times +for a given target; +each additional call +adds to the list of entries +that will be built into the archive. +Any source directories will +be scanned for changes to +any on-disk files, +regardless of whether or not +.B scons +knows about them from other Builder or function calls. + +.ES +env.Tar('src.tar', 'src') + +# Create the stuff.tar file. +env.Tar('stuff', ['subdir1', 'subdir2']) +# Also add "another" to the stuff.tar file. +env.Tar('stuff', 'another') + +# Set TARFLAGS to create a gzip-filtered archive. +env = Environment(TARFLAGS = '-c -z') +env.Tar('foo.tar.gz', 'foo') + +# Also set the suffix to .tgz. +env = Environment(TARFLAGS = '-c -z', + TARSUFFIX = '.tgz') +env.Tar('foo') +.EE +.IP +'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.IP Textfile() +.IP env.Textfile() +The \fBTextfile\fP() builder generates a single text file. +The source strings constitute the lines; +nested lists of sources are flattened. +$LINESEPARATOR is used to separate the strings. + +If present, the $SUBST_DICT construction variable +is used to modify the strings before they are written; +see the \fBSubstfile\fP() description for details. + +The prefix and suffix specified by the $TEXTFILEPREFIX +and $TEXTFILESUFFIX construction variables +(the null string and \fB.txt\fP by default, respectively) +are automatically added to the target if they are not already present. +Examples: + +.ES +# builds/writes foo.txt +env.Textfile(target = 'foo.txt', source = ['Goethe', 42, 'Schiller']) + +# builds/writes bar.txt +env.Textfile(target = 'bar', + source = ['lalala', 'tanteratei'], + LINESEPARATOR='|*') + +# nested lists are flattened automatically +env.Textfile(target = 'blob', + source = ['lalala', ['Goethe', 42 'Schiller'], 'tanteratei']) + +# files may be used as input by wraping them in File() +env.Textfile(target = 'concat', # concatenate files with a marker between + source = [File('concat1'), File('concat2')], + LINESEPARATOR = '====================\\n') + +Results are: +foo.txt + ....8<---- + Goethe + 42 + Schiller + ....8<---- (no linefeed at the end) + +bar.txt: + ....8<---- + lalala|*tanteratei + ....8<---- (no linefeed at the end) + +blob.txt + ....8<---- + lalala + Goethe + 42 + Schiller + tanteratei + ....8<---- (no linefeed at the end) +.EE +.IP +'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.IP TypeLibrary() +.IP env.TypeLibrary() +Builds a Windows type library (\fB.tlb\fP) +file from an input IDL file (\fB.idl\fP). +In addition, it will build the associated inteface stub and +proxy source files, +naming them according to the base name of the \fB.idl\fP file. +For example, + +.ES +env.TypeLibrary(source="foo.idl") +.EE +.IP +Will create \fBfoo.tlb\fP, +.BR foo.h , +.BR foo_i.c , +.B foo_p.c +and +.B foo_data.c +files. + +'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.IP Uic() +.IP env.Uic() +Builds a header file, an implementation file and a moc file from an ui file. +and returns the corresponding nodes in the above order. +This builder is only available after using the tool 'qt'. Note: you can +specify \fB.ui\fP files directly as source +files to the \fBProgram\fP(), +.BR Library\fP() and \fBSharedLibrary () builders +without using this builder. Using this builder lets you override the standard +naming conventions (be careful: prefixes are always prepended to names of +built files; if you don't want prefixes, you may set them to ``). +See the $QTDIR variable for more information. +Example: + +.ES +env.Uic('foo.ui') # -> ['foo.h', 'uic_foo.cc', 'moc_foo.cc'] +env.Uic(target = Split('include/foo.h gen/uicfoo.cc gen/mocfoo.cc'), + source = 'foo.ui') # -> ['include/foo.h', 'gen/uicfoo.cc', 'gen/mocfoo.cc'] +.EE +.IP +'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.IP Zip() +.IP env.Zip() +Builds a zip archive of the specified files +and/or directories. +Unlike most builder methods, +the +.BR Zip () +builder method may be called multiple times +for a given target; +each additional call +adds to the list of entries +that will be built into the archive. +Any source directories will +be scanned for changes to +any on-disk files, +regardless of whether or not +.B scons +knows about them from other Builder or function calls. + +.ES +env.Zip('src.zip', 'src') + +# Create the stuff.zip file. +env.Zip('stuff', ['subdir1', 'subdir2']) +# Also add "another" to the stuff.tar file. +env.Zip('stuff', 'another') +.EE +'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +'\" END GENERATED BUILDER DESCRIPTIONS +'\" +'\" The descriptions above of the various SCons Builders are generated +'\" from the .xml files that live next to the various Python modules in +'\" the build enginer library. If you're reading this [gnt]roff file +'\" with an eye towards patching this man page, you can still submit +'\" a diff against this text, but it will have to be translated to a +'\" diff against the underlying .xml file before the patch is actually +'\" accepted. If you do that yourself, it will make it easier to +'\" integrate the patch. +'\" +'\" END GENERATED BUILDER DESCRIPTIONS +'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" + +.P +All +targets of builder methods automatically depend on their sources. +An explicit dependency can +be specified using the +.B Depends +method of a construction environment (see below). + +In addition, +.B scons +automatically scans +source files for various programming languages, +so the dependencies do not need to be specified explicitly. +By default, SCons can +C source files, +C++ source files, +Fortran source files with +.B .F +(POSIX systems only), +.B .fpp, +or +.B .FPP +file extensions, +and assembly language files with +.B .S +(POSIX systems only), +.B .spp, +or +.B .SPP +files extensions +for C preprocessor dependencies. +SCons also has default support +for scanning D source files, +You can also write your own Scanners +to add support for additional source file types. +These can be added to the default +Scanner object used by the +.BR Object (), +.BR StaticObject (), +and +.BR SharedObject () +Builders by adding them +to the +.B SourceFileScanner +object as follows: + +See the section "Scanner Objects," +below, for a more information about +defining your own Scanner objects. + +.SS Methods and Functions to Do Things +In addition to Builder methods, +.B scons +provides a number of other construction environment methods +and global functions to +manipulate the build configuration. + +Usually, a construction environment method +and global function with the same name both exist +so that you don't have to remember whether +to a specific bit of functionality +must be called with or without a construction environment. +In the following list, +if you call something as a global function +it looks like: +.ES +.RI Function( arguments ) +.EE +and if you call something through a construction +environment it looks like: +.ES +.RI env.Function( arguments ) +.EE +If you can call the functionality in both ways, +then both forms are listed. + +Global functions may be called from custom Python modules that you +import into an SConscript file by adding the following +to the Python module: + +.ES +from SCons.Script import * +.EE + +Except where otherwise noted, +the same-named +construction environment method +and global function +provide the exact same functionality. +The only difference is that, +where appropriate, +calling the functionality through a construction environment will +substitute construction variables into +any supplied strings. +For example: + +.ES +env = Environment(FOO = 'foo') +Default('$FOO') +env.Default('$FOO') +.EE + +In the above example, +the first call to the global +.B Default() +function will actually add a target named +.B $FOO +to the list of default targets, +while the second call to the +.B env.Default() +construction environment method +will expand the value +and add a target named +.B foo +to the list of default targets. +For more on construction variable expansion, +see the next section on +construction variables. + +Construction environment methods +and global functions supported by +.B scons +include: + +'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.RI Action( action ", [" cmd/str/fun ", [" var ", ...]] [" option = value ", ...])" +.TP +.IR env .Action( action ", [" cmd/str/fun ", [" var ", ...]] [" option = value ", ...])" +Creates an Action object for +the specified +.IR action . +See the section "Action Objects," +below, for a complete explanation of the arguments and behavior. + +Note that the +.BR env.Action () +form of the invocation will expand +construction variables in any argument strings, +including the +.I action +argument, at the time it is called +using the construction variables in the +.I env +construction environment through which +.BR env.Action () +was called. +The +.BR Action () +form delays all variable expansion +until the Action object is actually used. + +'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.RI AddMethod( object, function ", [" name ]) +.TP +.RI env.AddMethod( function ", [" name ]) +When called with the +.BR AddMethod () +form, +adds the specified +.I function +to the specified +.I object +as the specified method +.IR name . +When called with the +.BR env.AddMethod () +form, +adds the specified +.I function +to the construction environment +.I env +as the specified method +.IR name . +In both cases, if +.I name +is omitted or +.BR None , +the name of the +specified +.I function +itself is used for the method name. + +Examples: + +.ES +# Note that the first argument to the function to +# be attached as a method must be the object through +# which the method will be called; the Python +# convention is to call it 'self'. +def my_method(self, arg): + print "my_method() got", arg + +# Use the global AddMethod() function to add a method +# to the Environment class. This +AddMethod(Environment, my_method) +env = Environment() +env.my_method('arg') + +# Add the function as a method, using the function +# name for the method call. +env = Environment() +env.AddMethod(my_method, 'other_method_name') +env.other_method_name('another arg') +.EE + +'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.RI AddOption( arguments ) +This function adds a new command-line option to be recognized. +The specified +.I arguments +are the same as supported by the standard Python +.BR optparse.add_option () +method (with a few additional capabilities noted below); +see the documentation for +.B optparse +for a thorough discussion of its option-processing capabities. +(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 ]]) +.TP +.RI env.Alias( alias ", [" targets ", [" action ]]) +Creates one or more phony targets that +expand to one or more other targets. +An optional +.I action +(command) +or list of actions +can be specified that will be executed +whenever the any of the alias targets are out-of-date. +Returns the Node object representing the alias, +which exists outside of any file system. +This Node object, or the alias name, +may be used as a dependency of any other target, +including another alias. +.B Alias +can be called multiple times for the same +alias to add additional targets to the alias, +or additional actions to the list for this alias. + +Examples: + +.ES +Alias('install') +Alias('install', '/usr/bin') +Alias(['install', 'install-lib'], '/usr/local/lib') + +env.Alias('install', ['/usr/local/bin', '/usr/local/lib']) +env.Alias('install', ['/usr/local/man']) + +env.Alias('update', ['file1', 'file2'], "update_database $SOURCES") +.EE + +'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.RI AllowSubstExceptions([ exception ", ...])" +Specifies the exceptions that will be allowed +when expanding construction variables. +By default, +any construction variable expansions that generate a +.B NameError +or +.BR IndexError +exception will expand to a +.B '' +(a null string) and not cause scons to fail. +All exceptions not in the specified list +will generate an error message +and terminate processing. + +If +.B AllowSubstExceptions +is called multiple times, +each call completely overwrites the previous list +of allowed exceptions. + +Example: + +.ES +# Requires that all construction variable names exist. +# (You may wish to do this if you want to enforce strictly +# that all construction variables must be defined before use.) +AllowSubstExceptions() + +# Also allow a string containing a zero-division expansion +# like '${1 / 0}' to evalute to ''. +AllowSubstExceptions(IndexError, NameError, ZeroDivisionError) +.EE + +'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.RI AlwaysBuild( target ", ...)" +.TP +.RI env.AlwaysBuild( target ", ...)" +Marks each given +.I target +so that it is always assumed to be out of date, +and will always be rebuilt if needed. +Note, however, that +.BR AlwaysBuild () +does not add its target(s) to the default target list, +so the targets will only be built +if they are specified on the command line, +or are a dependent of a target specified on the command line--but +they will +.I always +be built if so specified. +Multiple targets can be passed in to a single call to +.BR AlwaysBuild (). + +'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.RI env.Append( key = val ", [...])" +Appends the specified keyword arguments +to the end of construction variables in the environment. +If the Environment does not have +the specified construction variable, +it is simply added to the environment. +If the values of the construction variable +and the keyword argument are the same type, +then the two values will be simply added together. +Otherwise, the construction variable +and the value of the keyword argument +are both coerced to lists, +and the lists are added together. +(See also the Prepend method, below.) + +Example: + +.ES +env.Append(CCFLAGS = ' -g', FOO = ['foo.yyy']) +.EE + +'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.RI env.AppendENVPath( name ", " newpath ", [" envname ", " sep ", " delete_existing ]) +This appends new path elements to the given path in the +specified external environment +.RB ( ENV +by default). +This will only add +any particular path once (leaving the last one it encounters and +ignoring the rest, to preserve path order), +and to help assure this, +will normalize all paths (using +.B os.path.normpath +and +.BR os.path.normcase ). +This can also handle the +case where the given old path variable is a list instead of a +string, in which case a list will be returned instead of a string. + +If +.I delete_existing +is 0, then adding a path that already exists +will not move it to the end; it will stay where it is in the list. + +Example: + +.ES +print 'before:',env['ENV']['INCLUDE'] +include_path = '/foo/bar:/foo' +env.AppendENVPath('INCLUDE', include_path) +print 'after:',env['ENV']['INCLUDE'] + +yields: +before: /foo:/biz +after: /biz:/foo/bar:/foo +.EE + +'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.RI env.AppendUnique( key = val ", [...], delete_existing=0)" +Appends the specified keyword arguments +to the end of construction variables in the environment. +If the Environment does not have +the specified construction variable, +it is simply added to the environment. +If the construction variable being appended to is a list, +then any value(s) that already exist in the +construction variable will +.I not +be added again to the list. +However, if delete_existing is 1, +existing matching values are removed first, so +existing values in the arg list move to the end of the list. + +Example: + +.ES +env.AppendUnique(CCFLAGS = '-g', FOO = ['foo.yyy']) +.EE + +'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +env.BitKeeper() +A factory function that +returns a Builder object +to be used to fetch source files +using BitKeeper. +The returned Builder +is intended to be passed to the +.B SourceCode +function. + +Example: + +.ES +env.SourceCode('.', env.BitKeeper()) +.EE + +'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.RI BuildDir( build_dir ", " src_dir ", [" duplicate ]) +.TP +.RI env.BuildDir( build_dir ", " src_dir ", [" duplicate ]) +Deprecated synonyms for +.BR VariantDir () +and +.BR env.VariantDir (). +The +.I build_dir +argument becomes the +.I variant_dir +argument of +.BR VariantDir () +or +.BR env.VariantDir (). + +'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.RI Builder( action ", [" arguments ]) +.TP +.RI env.Builder( action ", [" arguments ]) +Creates a Builder object for +the specified +.IR action . +See the section "Builder Objects," +below, for a complete explanation of the arguments and behavior. + +Note that the +.BR env.Builder () +form of the invocation will expand +construction variables in any arguments strings, +including the +.I action +argument, +at the time it is called +using the construction variables in the +.B env +construction environment through which +.BR env.Builder () +was called. +The +.BR Builder () +form delays all variable expansion +until after the Builder object is actually called. + +'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.RI CacheDir( cache_dir ) +.TP +.RI env.CacheDir( cache_dir ) +Specifies that +.B scons +will maintain a cache of derived files in +.I cache_dir . +The derived files in the cache will be shared +among all the builds using the same +.BR CacheDir () +call. +Specifying a +.I cache_dir +of +.B None +disables derived file caching. + +Calling +.BR env.CacheDir () +will only affect targets built +through the specified construction environment. +Calling +.BR CacheDir () +sets a global default +that will be used by all targets built +through construction environments +that do +.I not +have an +.BR env.CacheDir () +specified. + +When a +.BR CacheDir () +is being used and +.B scons +finds a derived file that needs to be rebuilt, +it will first look in the cache to see if a +derived file has already been built +from identical input files and an identical build action +(as incorporated into the MD5 build signature). +If so, +.B scons +will retrieve the file from the cache. +If the derived file is not present in the cache, +.B scons +will rebuild it and +then place a copy of the built file in the cache +(identified by its MD5 build signature), +so that it may be retrieved by other +builds that need to build the same derived file +from identical inputs. + +Use of a specified +.BR CacheDir() +may be disabled for any invocation +by using the +.B --cache-disable +option. + +If the +.B --cache-force +option is used, +.B scons +will place a copy of +.I all +derived files in the cache, +even if they already existed +and were not built by this invocation. +This is useful to populate a cache +the first time +.BR CacheDir () +is added to a build, +or after using the +.B --cache-disable +option. + +When using +.BR CacheDir (), +.B scons +will report, +"Retrieved `file' from cache," +unless the +.B --cache-show +option is being used. +When the +.B --cache-show +option is used, +.B scons +will print the action that +.I would +have been used to build the file, +without any indication that +the file was actually retrieved from the cache. +This is useful to generate build logs +that are equivalent regardless of whether +a given derived file has been built in-place +or retrieved from the cache. + +The +.BR NoCache () +method can be used to disable caching of specific files. This can be +useful if inputs and/or outputs of some tool are impossible to +predict or prohibitively large. + +'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.RI Clean( targets ", " files_or_dirs ) +.TP +.RI env.Clean( targets ", " files_or_dirs ) +This specifies a list of files or directories which should be removed +whenever the targets are specified with the +.B -c +command line option. +The specified targets may be a list +or an individual target. +Multiple calls to +.BR Clean () +are legal, +and create new targets or add files and directories to the +clean list for the specified targets. + +Multiple files or directories should be specified +either as separate arguments to the +.BR Clean () +method, or as a list. +.BR Clean () +will also accept the return value of any of the construction environment +Builder methods. +Examples: + +The related +.BR NoClean () +function overrides calling +.BR Clean () +for the same target, +and any targets passed to both functions will +.I not +be removed by the +.B -c +option. + +Examples: + +.ES +Clean('foo', ['bar', 'baz']) +Clean('dist', env.Program('hello', 'hello.c')) +Clean(['foo', 'bar'], 'something_else_to_clean') +.EE + +In this example, +installing the project creates a subdirectory for the documentation. +This statement causes the subdirectory to be removed +if the project is deinstalled. +.ES +Clean(docdir, os.path.join(docdir, projectname)) +.EE + +'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.RI Command( target ", " source ", " action ", [" key = val ", ...])" +.TP +.RI env.Command( target ", " source ", " action ", [" key = val ", ...])" +Executes a specific action +(or list of actions) +to build a target file or files. +This is more convenient +than defining a separate Builder object +for a single special-case build. + +As a special case, the +.B source_scanner +keyword argument can +be used to specify +a Scanner object +that will be used to scan the sources. +(The global +.B DirScanner +object can be used +if any of the sources will be directories +that must be scanned on-disk for +changes to files that aren't +already specified in other Builder of function calls.) + +Any other keyword arguments specified override any +same-named existing construction variables. + +An action can be an external command, +specified as a string, +or a callable Python object; +see "Action Objects," below, +for more complete information. +Also note that a string specifying an external command +may be preceded by an +.B @ +(at-sign) +to suppress printing the command in question, +or by a +.B \- +(hyphen) +to ignore the exit status of the external command. + +Examples: + +.ES +env.Command('foo.out', 'foo.in', + "$FOO_BUILD < $SOURCES > $TARGET") + +env.Command('bar.out', 'bar.in', + ["rm -f $TARGET", + "$BAR_BUILD < $SOURCES > $TARGET"], + ENV = {'PATH' : '/usr/local/bin/'}) + +def rename(env, target, source): + import os + os.rename('.tmp', str(target[0])) + +env.Command('baz.out', 'baz.in', + ["$BAZ_BUILD < $SOURCES > .tmp", + rename ]) +.EE + +.IP +Note that the +.BR Command () +function will usually assume, by default, +that the specified targets and/or sources are Files, +if no other part of the configuration +identifies what type of entry it is. +If necessary, you can explicitly specify +that targets or source nodes should +be treated as directoriese +by using the +.BR Dir () +or +.BR env.Dir () +functions. + +Examples: + +.ES +env.Command('ddd.list', Dir('ddd'), 'ls -l $SOURCE > $TARGET') + +env['DISTDIR'] = 'destination/directory' +env.Command(env.Dir('$DISTDIR')), None, make_distdir) +.EE + +.IP +(Also note that SCons will usually +automatically create any directory necessary to hold a target file, +so you normally don't need to create directories by hand.) + +'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.RI Configure( env ", [" custom_tests ", " conf_dir ", " log_file ", " config_h ]) +.TP +.RI env.Configure([ custom_tests ", " conf_dir ", " log_file ", " config_h ]) +Creates a Configure object for integrated +functionality similar to GNU autoconf. +See the section "Configure Contexts," +below, for a complete explanation of the arguments and behavior. + +'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.RI env.Clone([ key = val ", ...])" +Return a separate copy of a construction environment. +If there are any keyword arguments specified, +they are added to the returned copy, +overwriting any existing values +for the keywords. + +Example: + +.ES +env2 = env.Clone() +env3 = env.Clone(CCFLAGS = '-g') +.EE +.IP +Additionally, a list of tools and a toolpath may be specified, as in +the Environment constructor: + +.ES +def MyTool(env): env['FOO'] = 'bar' +env4 = env.Clone(tools = ['msvc', MyTool]) +.EE + +The +.I parse_flags +keyword argument is also recognized: + +.ES +# create an environment for compiling programs that use wxWidgets +wx_env = env.Clone(parse_flags = '!wx-config --cflags --cxxflags') +.EE + +'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.RI env.Copy([ key = val ", ...])" +A now-deprecated synonym for +.BR env.Clone() . + +'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.RI env.CVS( repository ", " module ) +A factory function that +returns a Builder object +to be used to fetch source files +from the specified +CVS +.IR repository . +The returned Builder +is intended to be passed to the +.B SourceCode +function. + +The optional specified +.I module +will be added to the beginning +of all repository path names; +this can be used, in essence, +to strip initial directory names +from the repository path names, +so that you only have to +replicate part of the repository +directory hierarchy in your +local build directory. + +Examples: + +.ES +# Will fetch foo/bar/src.c +# from /usr/local/CVSROOT/foo/bar/src.c. +env.SourceCode('.', env.CVS('/usr/local/CVSROOT')) + +# Will fetch bar/src.c +# from /usr/local/CVSROOT/foo/bar/src.c. +env.SourceCode('.', env.CVS('/usr/local/CVSROOT', 'foo')) + +# Will fetch src.c +# from /usr/local/CVSROOT/foo/bar/src.c. +env.SourceCode('.', env.CVS('/usr/local/CVSROOT', 'foo/bar')) +.EE + +'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.RI Decider( function ) +.TP +.RI env.Decider( function ) +Specifies that all up-to-date decisions for +targets built through this construction environment +will be handled by the specified +.IR function . +The +.I function +can be one of the following strings +that specify the type of decision function +to be performed: + +.RS 10 +.HP 6 +.B timestamp-newer +Specifies that a target shall be considered out of date and rebuilt +if the dependency's timestamp is newer than the target file's timestamp. +This is the behavior of the classic Make utility, +and +.B make +can be used a synonym for +.BR timestamp-newer . + +.HP 6 +.B timestamp-match +Specifies that a target shall be considered out of date and rebuilt +if the dependency's timestamp is different than the +timestamp recorded the last time the target was built. +This provides behavior very similar to the classic Make utility +(in particular, files are not opened up so that their +contents can be checksummed) +except that the target will also be rebuilt if a +dependency file has been restored to a version with an +.I earlier +timestamp, such as can happen when restoring files from backup archives. + +.HP 6 +.B MD5 +Specifies that a target shall be considered out of date and rebuilt +if the dependency's content has changed sine the last time +the target was built, +as determined be performing an MD5 checksum +on the dependency's contents +and comparing it to the checksum recorded the +last time the target was built. +.B content +can be used as a synonym for +.BR MD5 . + +.HP 6 +.B MD5-timestamp +Specifies that a target shall be considered out of date and rebuilt +if the dependency's content has changed sine the last time +the target was built, +except that dependencies with a timestamp that matches +the last time the target was rebuilt will be +assumed to be up-to-date and +.I not +rebuilt. +This provides behavior very similar +to the +.B MD5 +behavior of always checksumming file contents, +with an optimization of not checking +the contents of files whose timestamps haven't changed. +The drawback is that SCons will +.I not +detect if a file's content has changed +but its timestamp is the same, +as might happen in an automated script +that runs a build, +updates a file, +and runs the build again, +all within a single second. +.RE + +.IP +Examples: + +.ES +# Use exact timestamp matches by default. +Decider('timestamp-match') + +# Use MD5 content signatures for any targets built +# with the attached construction environment. +env.Decider('content') +.EE + +.IP +In addition to the above already-available functions, +the +.I function +argument may be an actual Python function +that takes the following three arguments: + +.RS 10 +.IP dependency +The Node (file) which +should cause the +.I target +to be rebuilt +if it has "changed" since the last tme +.I target was built. + +.IP target +The Node (file) being built. +In the normal case, +this is what should get rebuilt +if the +.I dependency +has "changed." + +.IP prev_ni +Stored information about the state of the +.I dependency +the last time the +.I target +was built. +This can be consulted to match various +file characteristics +such as the timestamp, +size, or content signature. +.RE + +.IP +The +.I function +should return a +.B True +(non-zero) +value if the +.I dependency +has "changed" since the last time +the +.I target +was built +(indicating that the target +.I should +be rebuilt), +and +.B False +(zero) +otherwise +(indicating that the target should +.I not +be rebuilt). +Note that the decision can be made +using whatever criteria are appopriate. +Ignoring some or all of the function arguments +is perfectly normal. + +Example: + +.ES +def my_decider(dependency, target, prev_ni): + return not os.path.exists(str(target)) + +env.Decider(my_decider) +.EE + +'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.RI Default( targets ) +.TP +.RI env.Default( targets ) +This specifies a list of default targets, +which will be built by +.B scons +if no explicit targets are given on the command line. +Multiple calls to +.BR Default () +are legal, +and add to the list of default targets. + +Multiple targets should be specified as +separate arguments to the +.BR Default () +method, or as a list. +.BR Default () +will also accept the Node returned by any +of a construction environment's +builder methods. + +Examples: + +.ES +Default('foo', 'bar', 'baz') +env.Default(['a', 'b', 'c']) +hello = env.Program('hello', 'hello.c') +env.Default(hello) +.EE +.IP +An argument to +.BR Default () +of +.B None +will clear all default targets. +Later calls to +.BR Default () +will add to the (now empty) default-target list +like normal. + +The current list of targets added using the +.BR Default () +function or method is available in the +.B DEFAULT_TARGETS +list; +see below. + +'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.RI DefaultEnvironment([ args ]) +Creates and returns a default construction environment object. +This construction environment is used internally by SCons +in order to execute many of the global functions in this list, +and to fetch source files transparently +from source code management systems. + +'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.RI Depends( target ", " dependency ) +.TP +.RI env.Depends( target ", " dependency ) +Specifies an explicit dependency; +the +.I target +will be rebuilt +whenever the +.I dependency +has changed. +Both the specified +.I target +and +.I dependency +can be a string +(usually the path name of a file or directory) +or Node objects, +or a list of strings or Node objects +(such as returned by a Builder call). +This should only be necessary +for cases where the dependency +is not caught by a Scanner +for the file. + +Example: + +.ES +env.Depends('foo', 'other-input-file-for-foo') + +mylib = env.Library('mylib.c') +installed_lib = env.Install('lib', mylib) +bar = env.Program('bar.c') + +# Arrange for the library to be copied into the installation +# directory before trying to build the "bar" program. +# (Note that this is for example only. A "real" library +# dependency would normally be configured through the $LIBS +# and $LIBPATH variables, not using an env.Depends() call.) + +env.Depends(bar, installed_lib) +.EE + +'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.RI env.Dictionary([ vars ]) +Returns a dictionary object +containing copies of all of the +construction variables in the environment. +If there are any variable names specified, +only the specified construction +variables are returned in the dictionary. + +Example: + +.ES +dict = env.Dictionary() +cc_dict = env.Dictionary('CC', 'CCFLAGS', 'CCCOM') +.EE + +'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.RI Dir( name ", [" directory ]) +.TP +.RI env.Dir( name ", [" directory ]) +This returns a Directory Node, +an object that represents the specified directory +.IR name . +.I name +can be a relative or absolute path. +.I directory +is an optional directory that will be used as the parent directory. +If no +.I directory +is specified, the current script's directory is used as the parent. + +If +.I name +is a list, SCons returns a list of Dir nodes. +Construction variables are expanded in +.IR name . + +Directory Nodes can be used anywhere you +would supply a string as a directory name +to a Builder method or function. +Directory Nodes have attributes and methods +that are useful in many situations; +see "File and Directory Nodes," below. + +'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.RI env.Dump([ key ]) +Returns a pretty printable representation of the environment. +.IR key , +if not +.IR None , +should be a string containing the name of the variable of interest. + +This SConstruct: +.ES +env=Environment() +print env.Dump('CCCOM') +.EE +.IP +will print: +.ES +\&'$CC -c -o $TARGET $CCFLAGS $CPPFLAGS $_CPPDEFFLAGS $_CPPINCFLAGS $SOURCES' +.EE + +.ES +env=Environment() +print env.Dump() +.EE +.IP +will print: +.ES +{ 'AR': 'ar', + 'ARCOM': '$AR $ARFLAGS $TARGET $SOURCES\n$RANLIB $RANLIBFLAGS $TARGET', + 'ARFLAGS': ['r'], + 'AS': 'as', + 'ASCOM': '$AS $ASFLAGS -o $TARGET $SOURCES', + 'ASFLAGS': [], + ... +.EE + +'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.RI EnsurePythonVersion( major ", " minor ) +.TP +.RI env.EnsurePythonVersion( major ", " minor ) +Ensure that the Python version is at least +.IR major . minor . +This function will +print out an error message and exit SCons with a non-zero exit code if the +actual Python version is not late enough. + +Example: + +.ES +EnsurePythonVersion(2,2) +.EE + +'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.RI EnsureSConsVersion( major ", " minor ", [" revision ]) +.TP +.RI env.EnsureSConsVersion( major ", " minor ", [" revision ]) +Ensure that the SCons version is at least +.IR major.minor , +or +.IR major.minor.revision . +if +.I revision +is specified. +This function will +print out an error message and exit SCons with a non-zero exit code if the +actual SCons version is not late enough. + +Examples: + +.ES +EnsureSConsVersion(0,14) + +EnsureSConsVersion(0,96,90) +.EE + +'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.RI Environment([ key = value ", ...])" +.TP +.RI env.Environment([ key = value ", ...])" +Return a new construction environment +initialized with the specified +.IR key = value +pairs. + +'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.RI Execute( action ", [" strfunction ", " varlist ]) +.TP +.RI env.Execute( action ", [" strfunction ", " varlist ]) +Executes an Action object. +The specified +.IR action +may be an Action object +(see the section "Action Objects," +below, for a complete explanation of the arguments and behavior), +or it may be a command-line string, +list of commands, +or executable Python function, +each of which will be converted +into an Action object +and then executed. +The exit value of the command +or return value of the Python function +will be returned. + +Note that +.B scons +will print an error message if the executed +.I action +fails--that is, +exits with or returns a non-zero value. +.B scons +will +.I not , +however, +automatically terminate the build +if the specified +.I action +fails. +If you want the build to stop in response to a failed +.BR Execute () +call, +you must explicitly check for a non-zero return value: + +.ES +Execute(Copy('file.out', 'file.in')) + +if Execute("mkdir sub/dir/ectory"): + # The mkdir failed, don't try to build. + Exit(1) +.EE + +'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.RI Exit([ value ]) +.TP +.RI env.Exit([ value ]) +This tells +.B scons +to exit immediately +with the specified +.IR value . +A default exit value of +.B 0 +(zero) +is used if no value is specified. + +'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.RI Export( vars ) +.TP +.RI env.Export( vars ) +This tells +.B scons +to export a list of variables from the current +SConscript file to all other SConscript files. +The exported variables are kept in a global collection, +so subsequent calls to +.BR Export () +will over-write previous exports that have the same name. +Multiple variable names can be passed to +.BR Export () +as separate arguments or as a list. +Keyword arguments can be used to provide names and their values. +A dictionary can be used to map variables to a different name when exported. +Both local variables and global variables can be exported. + +Examples: + +.ES +env = Environment() +# Make env available for all SConscript files to Import(). +Export("env") + +package = 'my_name' +# Make env and package available for all SConscript files:. +Export("env", "package") + +# Make env and package available for all SConscript files: +Export(["env", "package"]) + +# Make env available using the name debug: +Export(debug = env) + +# Make env available using the name debug: +Export({"debug":env}) +.EE + +.IP +Note that the +.BR SConscript () +function supports an +.I exports +argument that makes it easier to to export a variable or +set of variables to a single SConscript file. +See the description of the +.BR SConscript () +function, below. + +'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.RI File( name ", [" directory ]) +.TP +.RI env.File( name ", [" directory ]) +This returns a +File Node, +an object that represents the specified file +.IR name . +.I name +can be a relative or absolute path. +.I directory +is an optional directory that will be used as the parent directory. + +If +.I name +is a list, SCons returns a list of File nodes. +Construction variables are expanded in +.IR name . + +File Nodes can be used anywhere you +would supply a string as a file name +to a Builder method or function. +File Nodes have attributes and methods +that are useful in many situations; +see "File and Directory Nodes," below. + +'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.RI FindFile( file ", " dirs ) +.TP +.RI env.FindFile( file ", " dirs ) +Search for +.I file +in the path specified by +.IR dirs . +.I dirs +may be a list of directory names or a single directory name. +In addition to searching for files that exist in the 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 ) +.TP +.RI env.Flatten( sequence ) +Takes a sequence (that is, a Python list or tuple) +that may contain nested sequences +and returns a flattened list containing +all of the individual elements in any sequence. +This can be helpful for collecting +the lists returned by calls to Builders; +other Builders will automatically +flatten lists specified as input, +but direct Python manipulation of +these lists does not. + +Examples: + +.ES +foo = Object('foo.c') +bar = Object('bar.c') + +# Because `foo' and `bar' are lists returned by the Object() Builder, +# `objects' will be a list containing nested lists: +objects = ['f1.o', foo, 'f2.o', bar, 'f3.o'] + +# Passing such a list to another Builder is all right because +# the Builder will flatten the list automatically: +Program(source = objects) + +# If you need to manipulate the list directly using Python, you need to +# call Flatten() yourself, or otherwise handle nested lists: +for object in Flatten(objects): + print str(object) +.EE + +'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.RI GetBuildFailures() +Returns a list of exceptions for the +actions that failed while +attempting to build targets. +Each element in the returned list is a +.B BuildError +object +with the following attributes +that record various aspects +of the build failure: + +.B .node +The node that was being built +when the build failure occurred. + +.B .status +The numeric exit status +returned by the command or Python function +that failed when trying to build the +specified Node. + +.B .errstr +The SCons error string +describing the build failure. +(This is often a generic +message like "Error 2" +to indicate that an executed +command exited with a status of 2.) + +.B .filename +The name of the file or +directory that actually caused the failure. +This may be different from the +.B .node +attribute. +For example, +if an attempt to build a target named +.B sub/dir/target +fails because the +.B sub/dir +directory could not be created, +then the +.B .node +attribute will be +.B sub/dir/target +but the +.B .filename +attribute will be +.BR sub/dir . + +.B .executor +The SCons Executor object +for the target Node +being built. +This can be used to retrieve +the construction environment used +for the failed action. + +.B .action +The actual SCons Action object that failed. +This will be one specific action +out of the possible list of +actions that would have been +executed to build the target. + +.B .command +The actual expanded command that was executed and failed, +after expansion of +.BR $TARGET , +.BR $SOURCE , +and other construction variables. + +Note that the +.BR GetBuildFailures () +function +will always return an empty list +until any build failure has occurred, +which means that +.BR GetBuildFailures () +will always return an empty list +while the +.B SConscript +files are being read. +Its primary intended use is +for functions that will be +executed before SCons exits +by passing them to the +standard Python +.BR atexit.register () +function. +Example: + +.ES +import atexit + +def print_build_failures(): + from SCons.Script import GetBuildFailures + for bf in GetBuildFailures(): + print "%s failed: %s" % (bf.node, bf.errstr) + +atexit.register(print_build_failures) +.EE + +'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.RI GetBuildPath( file ", [" ... ]) +.TP +.RI env.GetBuildPath( file ", [" ... ]) +Returns the +.B scons +path name (or names) for the specified +.I file +(or files). +The specified +.I file +or files +may be +.B scons +Nodes or strings representing path names. + +'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.RI GetLaunchDir() +.TP +.RI env.GetLaunchDir() +Returns the absolute path name of the directory from which +.B scons +was initially invoked. +This can be useful when using the +.BR \-u , +.BR \-U +or +.BR \-D +options, which internally +change to the directory in which the +.B SConstruct +file is found. + +'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.RI GetOption( name ) +.TP +.RI env.GetOption( name ) +This function provides a way to query the value of +SCons options set on scons command line +(or set using the +.IR SetOption () +function). +The options supported are: + +.RS 10 +.TP 6 +.B cache_debug +which corresponds to --cache-debug; +.TP 6 +.B cache_disable +which corresponds to --cache-disable; +.TP 6 +.B cache_force +which corresponds to --cache-force; +.TP 6 +.B cache_show +which corresponds to --cache-show; +.TP 6 +.B clean +which corresponds to -c, --clean and --remove; +.TP 6 +.B config +which corresponds to --config; +.TP 6 +.B directory +which corresponds to -C and --directory; +.TP 6 +.B diskcheck +which corresponds to --diskcheck +.TP 6 +.B duplicate +which corresponds to --duplicate; +.TP 6 +.B file +which corresponds to -f, --file, --makefile and --sconstruct; +.TP 6 +.B help +which corresponds to -h and --help; +.TP 6 +.B ignore_errors +which corresponds to --ignore-errors; +.TP 6 +.B implicit_cache +which corresponds to --implicit-cache; +.TP 6 +.B implicit_deps_changed +which corresponds to --implicit-deps-changed; +.TP 6 +.B implicit_deps_unchanged +which corresponds to --implicit-deps-unchanged; +.TP 6 +.B interactive +which corresponds to --interact and --interactive; +.TP 6 +.B keep_going +which corresponds to -k and --keep-going; +.TP 6 +.B max_drift +which corresponds to --max-drift; +.TP 6 +.B no_exec +which corresponds to -n, --no-exec, --just-print, --dry-run and --recon; +.TP 6 +.B no_site_dir +which corresponds to --no-site-dir; +.TP 6 +.B num_jobs +which corresponds to -j and --jobs; +.TP 6 +.B profile_file +which corresponds to --profile; +.TP 6 +.B question +which corresponds to -q and --question; +.TP 6 +.B random +which corresponds to --random; +.TP 6 +.B repository +which corresponds to -Y, --repository and --srcdir; +.TP 6 +.B silent +which corresponds to -s, --silent and --quiet; +.TP 6 +.B site_dir +which corresponds to --site-dir; +.TP 6 +.B stack_size +which corresponds to --stack-size; +.TP 6 +.B taskmastertrace_file +which corresponds to --taskmastertrace; and +.TP 6 +.B warn +which corresponds to --warn and --warning. +.RE + +.IP +See the documentation for the +corresponding command line object for information about each specific +option. + +'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.RI Glob( pattern ", [" ondisk ", " source ", " strings ]) +.TP +.RI env.Glob( pattern ", [" ondisk ", " source ", " strings ]) +Returns Nodes (or strings) that match the specified +.IR pattern , +relative to the directory of the current +.B SConscript +file. +The +.BR env.Glob () +form performs string substition on +.I pattern +and returns whatever matches +the resulting expanded pattern. + +The specified +.I pattern +uses Unix shell style metacharacters for matching: + +.ES + * matches everything + ? matches any single character + [seq] matches any character in seq + [!seq] matches any char not in seq +.EE + +.IP +If the first character of a filename is a dot, +it must be matched explicitly. +Character matches do +.I not +span directory separators. + +The +.BR Glob () +knows about +repositories +(see the +.BR Repository () +function) +and source directories +(see the +.BR VariantDir () +function) +and +returns a Node (or string, if so configured) +in the local (SConscript) directory +if matching Node is found +anywhere in a corresponding +repository or source directory. + +The +.B ondisk +argument may be set to +.B False +(or any other non-true value) +to disable the search for matches on disk, +thereby only returning matches among +already-configured File or Dir Nodes. +The default behavior is to +return corresponding Nodes +for any on-disk matches found. + +The +.B source +argument may be set to +.B True +(or any equivalent value) +to specify that, +when the local directory is a +.BR VariantDir (), +the returned Nodes should be from the +corresponding source directory, +not the local directory. + +The +.B strings +argument may be set to +.B True +(or any equivalent value) +to have the +.BR Glob () +function return strings, not Nodes, +that represent the matched files or directories. +The returned strings will be relative to +the local (SConscript) directory. +(Note that This may make it easier to perform +arbitrary manipulation of file names, +but if the returned strings are +passed to a different +.B SConscript +file, +any Node translation will be relative +to the other +.B SConscript +directory, +not the original +.B SConscript +directory.) + +Examples: + +.ES +Program('foo', Glob('*.c')) +Zip('/tmp/everything', Glob('.??*') + Glob('*')) +.EE + +'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +'\".TP +'\".RI GlobalBuilders( flag ) +'\"When +'\".B flag +'\"is non-zero, +'\"adds the names of the default builders +'\"(Program, Library, etc.) +'\"to the global name space +'\"so they can be called without an explicit construction environment. +'\"(This is the default.) +'\"When +'\".B +'\"flag is zero, +'\"the names of the default builders are removed +'\"from the global name space +'\"so that an explicit construction environment is required +'\"to call all builders. + +'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.RI Help( text ) +.TP +.RI env.Help( text ) +This specifies help text to be printed if the +.B -h +argument is given to +.BR scons . +If +.BR Help +is called multiple times, the text is appended together in the order +that +.BR Help +is called. + +'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.RI Ignore( target ", " dependency ) +.TP +.RI env.Ignore( target ", " dependency ) +The specified dependency file(s) +will be ignored when deciding if +the target file(s) need to be rebuilt. + +You can also use +.BR Ignore() +to remove a target from the default build. +In order to do this you must specify the directory the target will +be built in as the target, and the file you want to skip building +as the dependency. + +Note that this will only remove the dependencies listed from +the files built by default. It will still be built if that +dependency is needed by another object being built. +See the third and forth examples below. + +Examples: + +.ES +env.Ignore('foo', 'foo.c') +env.Ignore('bar', ['bar1.h', 'bar2.h']) +env.Ignore('.','foobar.obj') +env.Ignore('bar','bar/foobar.obj') +.EE + +'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.RI Import( vars ) +.TP +.RI env.Import( vars ) +This tells +.B scons +to import a list of variables into the current SConscript file. This +will import variables that were exported with +.BR Export () +or in the +.I exports +argument to +.BR SConscript (). +Variables exported by +.BR SConscript () +have precedence. +Multiple variable names can be passed to +.BR Import () +as separate arguments or as a list. The variable "*" can be used +to import all variables. + +Examples: + +.ES +Import("env") +Import("env", "variable") +Import(["env", "variable"]) +Import("*") +.EE + +'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.RI Literal( string ) +.TP +.RI env.Literal( string ) +The specified +.I string +will be preserved as-is +and not have construction variables expanded. + +'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.RI Local( targets ) +.TP +.RI env.Local( targets ) +The specified +.I targets +will have copies made in the local tree, +even if an already up-to-date copy +exists in a repository. +Returns a list of the target Node or Nodes. + +'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +\" .TP +\" .RI env.MergeShellPaths( arg ", [" prepend ]) +\" Merges the elements of the specified +\" .IR arg , +\" which must be a dictionary, to the construction +\" environment's copy of the shell environment +\" in env['ENV']. +\" (This is the environment which is passed +\" to subshells spawned by SCons.) +\" Note that +\" .I arg +\" must be a single value, +\" so multiple strings must +\" be passed in as a list, +\" not as separate arguments to +\" .BR env.MergeShellPaths (). + +\" New values are prepended to the environment variable by default, +\" unless prepend=0 is specified. +\" Duplicate values are always eliminated, +\" since this function calls +\" .B AppendENVPath +\" or +\" .B PrependENVPath +\" depending on the +\" .I prepend +\" argument. See those functions for more details. + +\" Examples: + +\" .ES +\" # Prepend a path to the shell PATH. +\" env.MergeShellPaths({'PATH':'/usr/local/bin'} ) +\" # Append two dirs to the shell INCLUDE. +\" env.MergeShellPaths({'INCLUDE':['c:/inc1', 'c:/inc2']}, prepend=0 ) + +.EE + +'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.RI env.MergeFlags( arg ", [" unique ]) +Merges the specified +.I arg +values to the construction environment's construction variables. +If the +.I arg +argument is not a dictionary, +it is converted to one by calling +.B env.ParseFlags() +on the argument +before the values are merged. +Note that +.I arg +must be a single value, +so multiple strings must +be passed in as a list, +not as separate arguments to +.BR env.MergeFlags (). + +By default, +duplicate values are eliminated; +you can, however, specify +.B unique=0 +to allow duplicate +values to be added. +When eliminating duplicate values, +any construction variables that end with +the string +.B PATH +keep the left-most unique value. +All other construction variables keep +the right-most unique value. + +Examples: + +.ES +# Add an optimization flag to $CCFLAGS. +env.MergeFlags('-O3') + +# Combine the flags returned from running pkg-config with an optimization +# flag and merge the result into the construction variables. +env.MergeFlags(['!pkg-config gtk+-2.0 --cflags', '-O3']) + +# Combine an optimization flag with the flags returned from running pkg-config +# twice and merge the result into the construction variables. +env.MergeFlags(['-O3', + '!pkg-config gtk+-2.0 --cflags --libs', + '!pkg-config libpng12 --cflags --libs']) +.EE + +'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.RI NoCache( target ", ...)" +.TP +.RI env.NoCache( target ", ...)" +Specifies a list of files which should +.I not +be cached whenever the +.BR CacheDir () +method has been activated. +The specified targets may be a list +or an individual target. + +Multiple files should be specified +either as separate arguments to the +.BR NoCache () +method, or as a list. +.BR NoCache () +will also accept the return value of any of the construction environment +Builder methods. + +Calling +.BR NoCache () +on directories and other non-File Node types has no effect because +only File Nodes are cached. + +Examples: + +.ES +NoCache('foo.elf') +NoCache(env.Program('hello', 'hello.c')) +.EE + +'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.RI NoClean( target ", ...)" +.TP +.RI env.NoClean( target ", ...)" +Specifies a list of files or directories which should +.I not +be removed whenever the targets (or their dependencies) +are specified with the +.B -c +command line option. +The specified targets may be a list +or an individual target. +Multiple calls to +.BR NoClean () +are legal, +and prevent each specified target +from being removed by calls to the +.B -c +option. + +Multiple files or directories should be specified +either as separate arguments to the +.BR NoClean () +method, or as a list. +.BR NoClean () +will also accept the return value of any of the construction environment +Builder methods. + +Calling +.BR NoClean () +for a target overrides calling +.BR Clean () +for the same target, +and any targets passed to both functions will +.I not +be removed by the +.B -c +option. + +Examples: + +.ES +NoClean('foo.elf') +NoClean(env.Program('hello', 'hello.c')) +.EE + +'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.RI env.ParseConfig( command ", [" function ", " unique ]) +Calls the specified +.I function +to modify the environment as specified by the output of +.I command . +The default +.I function +is +.BR env.MergeFlags (), +which expects the output of a typical +.I *-config command +(for example, +.BR gtk-config ) +and adds the options +to the appropriate construction variables. +By default, +duplicate values are not +added to any construction variables; +you can specify +.B unique=0 +to allow duplicate +values to be added. + +Interpreted options +and the construction variables they affect +are as specified for the +.BR env.ParseFlags () +method (which this method calls). +See that method's description, below, +for a table of options and construction variables. + +'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.RI ParseDepends( filename ", [" must_exist ", " only_one ]) +.TP +.RI env.ParseDepends( filename ", [" must_exist ", " only_one ]) +Parses the contents of the specified +.I filename +as a list of dependencies in the style of +.BR Make +or +.BR mkdep , +and explicitly establishes all of the listed dependencies. + +By default, +it is not an error +if the specified +.I filename +does not exist. +The optional +.I must_exist +argument may be set to a non-zero +value to have +scons +throw an exception and +generate an error if the file does not exist, +or is otherwise inaccessible. + +The optional +.I only_one +argument may be set to a non-zero +value to have +scons +thrown an exception and +generate an error +if the file contains dependency +information for more than one target. +This can provide a small sanity check +for files intended to be generated +by, for example, the +.B gcc -M +flag, +which should typically only +write dependency information for +one output file into a corresponding +.B .d +file. + +The +.I filename +and all of the files listed therein +will be interpreted relative to +the directory of the +.I SConscript +file which calls the +.B ParseDepends +function. + +'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.RI env.ParseFlags( flags ", ...)" +Parses one or more strings containing +typical command-line flags for GCC tool chains +and returns a dictionary with the flag values +separated into the appropriate SCons construction variables. +This is intended as a companion to the +.BR env.MergeFlags () +method, but allows for the values in the returned dictionary +to be modified, if necessary, +before merging them into the construction environment. +(Note that +.BR env.MergeFlags () +will call this method if its argument is not a dictionary, +so it is usually not necessary to call +.BR env.ParseFlags () +directly unless you want to manipulate the values.) + +If the first character in any string is +an exclamation mark (!), +the rest of the string is executed as a command, +and the output from the command is +parsed as GCC tool chain command-line flags +and added to the resulting dictionary. + +Flag values are translated accordig to the prefix found, +and added to the following construction variables: + +.ES +-arch CCFLAGS, LINKFLAGS +-D CPPDEFINES +-framework FRAMEWORKS +-frameworkdir= FRAMEWORKPATH +-include CCFLAGS +-isysroot CCFLAGS, LINKFLAGS +-I CPPPATH +-l LIBS +-L LIBPATH +-mno-cygwin CCFLAGS, LINKFLAGS +-mwindows LINKFLAGS +-pthread CCFLAGS, LINKFLAGS +-std= CFLAGS +-Wa, ASFLAGS, CCFLAGS +-Wl,-rpath= RPATH +-Wl,-R, RPATH +-Wl,-R RPATH +-Wl, LINKFLAGS +-Wp, CPPFLAGS +- CCFLAGS ++ CCFLAGS, LINKFLAGS +.EE + +.IP +Any other strings not associated with options +are assumed to be the names of libraries +and added to the +.B LIBS +construction variable. + +Examples (all of which produce the same result): + +.ES +dict = env.ParseFlags('-O2 -Dfoo -Dbar=1') +dict = env.ParseFlags('-O2', '-Dfoo', '-Dbar=1') +dict = env.ParseFlags(['-O2', '-Dfoo -Dbar=1']) +dict = env.ParseFlags('-O2', '!echo -Dfoo -Dbar=1') +.EE + +'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +env.Perforce() +A factory function that +returns a Builder object +to be used to fetch source files +from the Perforce source code management system. +The returned Builder +is intended to be passed to the +.B SourceCode +function. + +Example: + +.ES +env.SourceCode('.', env.Perforce()) +.EE +.IP +Perforce uses a number of external +environment variables for its operation. +Consequently, this function adds the +following variables from the user's external environment +to the construction environment's +ENV dictionary: +P4CHARSET, +P4CLIENT, +P4LANGUAGE, +P4PASSWD, +P4PORT, +P4USER, +SystemRoot, +USER, +and +USERNAME. + +'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.RI Platform( string ) +Returns a callable object +that can be used to initialize +a construction environment using the +platform keyword of the Environment() method. + +Example: + +.ES +env = Environment(platform = Platform('win32')) +.EE +.TP +.RI env.Platform( string ) +Applies the callable object for the specified platform +.I string +to the environment through which the method was called. + +.ES +env.Platform('posix') +.EE +.IP +Note that the +.B win32 +platform adds the +.B SystemDrive +and +.B SystemRoot +variables from the user's external environment +to the construction environment's +.B ENV +dictionary. +This is so that any executed commands +that use sockets to connect with other systems +(such as fetching source files from +external CVS repository specifications like +.BR :pserver:anonymous@cvs.sourceforge.net:/cvsroot/scons ) +will work on Windows systems. + +'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.RI Progress( callable ", [" interval ]) +.TP +.RI Progress( string ", [" interval ", " file ", " overwrite ]) +.TP +.RI Progress( list_of_strings ", [" interval ", " file ", " overwrite ]) +Allows SCons to show progress made during the build +by displaying a string or calling a function while +evaluating Nodes (e.g. files). + +If the first specified argument is a Python callable +(a function or an object that has a +.BR __call__ () +method), +the function will be called +once every +.I interval +times a Node is evaluated. +The callable will be passed the evaluated Node +as its only argument. +(For future compatibility, +it's a good idea to also add +.B *args +and +.B **kw +as arguments to your function or method. +This will prevent the code from breaking +if SCons ever changes the interface +to call the function with additional arguments in the future.) + +An example of a simple custom progress function +that prints a string containing the Node name +every 10 Nodes: + +.ES +def my_progress_function(node, *args, **kw): + print 'Evaluating node %s!' % node +Progress(my_progress_function, interval=10) +.EE +.IP +A more complicated example of a custom progress display object +that prints a string containing a count +every 100 evaluated Nodes. +Note the use of +.B \\\\r +(a carriage return) +at the end so that the string +will overwrite itself on a display: + +.ES +import sys +class ProgressCounter: + count = 0 + def __call__(self, node, *args, **kw): + self.count += 100 + sys.stderr.write('Evaluated %s nodes\\r' % self.count) +Progress(ProgressCounter(), interval=100) +.EE +.IP +If the first argument +.BR Progress () +is a string, +the string will be displayed +every +.I interval +evaluated Nodes. +The default is to print the string on standard output; +an alternate output stream +may be specified with the +.B file= +argument. +The following will print a series of dots +on the error output, +one dot for every 100 evaluated Nodes: + +.ES +import sys +Progress('.', interval=100, file=sys.stderr) +.EE +.IP +If the string contains the verbatim substring +.B $TARGET, +it will be replaced with the Node. +Note that, for performance reasons, this is +.I not +a regular SCons variable substition, +so you can not use other variables +or use curly braces. +The following example will print the name of +every evaluated Node, +using a +.B \\\\r +(carriage return) to cause each line to overwritten by the next line, +and the +.B overwrite= +keyword argument to make sure the previously-printed +file name is overwritten with blank spaces: + +.ES +import sys +Progress('$TARGET\\r', overwrite=True) +.EE +.IP +If the first argument to +.BR Progress () +is a list of strings, +then each string in the list will be displayed +in rotating fashion every +.I interval +evaluated Nodes. +This can be used to implement a "spinner" +on the user's screen as follows: + +.ES +Progress(['-\\r', '\\\\\\r', '|\\r', '/\\r'], interval=5) +.EE + +'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.RI Precious( target ", ...)" +.TP +.RI env.Precious( target ", ...)" +Marks each given +.I target +as precious so it is not deleted before it is rebuilt. Normally +.B scons +deletes a target before building it. +Multiple targets can be passed in to a single call to +.BR Precious (). + +'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.RI env.Prepend( key = val ", [...])" +Appends the specified keyword arguments +to the beginning of construction variables in the environment. +If the Environment does not have +the specified construction variable, +it is simply added to the environment. +If the values of the construction variable +and the keyword argument are the same type, +then the two values will be simply added together. +Otherwise, the construction variable +and the value of the keyword argument +are both coerced to lists, +and the lists are added together. +(See also the Append method, above.) + +Example: + +.ES +env.Prepend(CCFLAGS = '-g ', FOO = ['foo.yyy']) +.EE + +'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.RI env.PrependENVPath( name ", " newpath ", [" envname ", " sep ", " delete_existing ]) +This appends new path elements to the given path in the +specified external environment +.RB ( ENV +by default). +This will only add +any particular path once (leaving the first one it encounters and +ignoring the rest, to preserve path order), +and to help assure this, +will normalize all paths (using +.B os.path.normpath +and +.BR os.path.normcase ). +This can also handle the +case where the given old path variable is a list instead of a +string, in which case a list will be returned instead of a string. + +If +.I delete_existing +is 0, then adding a path that already exists +will not move it to the beginning; +it will stay where it is in the list. + +Example: + +.ES +print 'before:',env['ENV']['INCLUDE'] +include_path = '/foo/bar:/foo' +env.PrependENVPath('INCLUDE', include_path) +print 'after:',env['ENV']['INCLUDE'] +.EE + +The above exmaple will print: + +.ES +before: /biz:/foo +after: /foo/bar:/foo:/biz +.EE + +'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.RI env.PrependUnique( key = val ", delete_existing=0, [...])" +Appends the specified keyword arguments +to the beginning of construction variables in the environment. +If the Environment does not have +the specified construction variable, +it is simply added to the environment. +If the construction variable being appended to is a list, +then any value(s) that already exist in the +construction variable will +.I not +be added again to the list. +However, if delete_existing is 1, +existing matching values are removed first, so +existing values in the arg list move to the front of the list. + +Example: + +.ES +env.PrependUnique(CCFLAGS = '-g', FOO = ['foo.yyy']) +.EE + +'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +env.RCS() +A factory function that +returns a Builder object +to be used to fetch source files +from RCS. +The returned Builder +is intended to be passed to the +.B SourceCode +function: + +Examples: + +.ES +env.SourceCode('.', env.RCS()) +.EE +.IP +Note that +.B scons +will fetch source files +from RCS subdirectories automatically, +so configuring RCS +as demonstrated in the above example +should only be necessary if +you are fetching from +RCS,v +files in the same +directory as the source files, +or if you need to explicitly specify RCS +for a specific subdirectory. + +'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.RI env.Replace( key = val ", [...])" +Replaces construction variables in the Environment +with the specified keyword arguments. + +Example: + +.ES +env.Replace(CCFLAGS = '-g', FOO = 'foo.xxx') +.EE + +'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.RI Repository( directory ) +.TP +.RI env.Repository( directory ) +Specifies that +.I directory +is a repository to be searched for files. +Multiple calls to +.BR Repository () +are legal, +and each one adds to the list of +repositories that will be searched. + +To +.BR scons , +a repository is a copy of the source tree, +from the top-level directory on down, +which may contain +both source files and derived files +that can be used to build targets in +the local source tree. +The canonical example would be an +official source tree maintained by an integrator. +If the repository contains derived files, +then the derived files should have been built using +.BR scons , +so that the repository contains the necessary +signature information to allow +.B scons +to figure out when it is appropriate to +use the repository copy of a derived file, +instead of building one locally. + +Note that if an up-to-date derived file +already exists in a repository, +.B scons +will +.I not +make a copy in the local directory tree. +In order to guarantee that a local copy +will be made, +use the +.B Local() +method. + +'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.RI Requires( target ", " prerequisite ) +.TP +.RI env.Requires( target ", " prerequisite ) +Specifies an order-only relationship +between the specified target file(s) +and the specified prerequisite file(s). +The prerequisite file(s) +will be (re)built, if necessary, +.I before +the target file(s), +but the target file(s) do not actually +depend on the prerequisites +and will not be rebuilt simply because +the prerequisite file(s) change. + +Example: + +.ES +env.Requires('foo', 'file-that-must-be-built-before-foo') +.EE + +'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.RI Return([ vars "... , " stop= ]) +By default, +this stops processing the current SConscript +file and returns to the calling SConscript file +the values of the variables named in the +.I vars +string arguments. +Multiple strings contaning variable names may be passed to +.BR Return (). +Any strings that contain white space + +The optional +.B stop= +keyword argument may be set to a false value +to continue processing the rest of the SConscript +file after the +.BR Return () +call. +This was the default behavior prior to SCons 0.98. +However, the values returned +are still the values of the variables in the named +.I vars +at the point +.BR Return () +is called. + +Examples: + +.ES +# Returns without returning a value. +Return() + +# Returns the value of the 'foo' Python variable. +Return("foo") + +# Returns the values of the Python variables 'foo' and 'bar'. +Return("foo", "bar") + +# Returns the values of Python variables 'val1' and 'val2'. +Return('val1 val2') +.EE + +'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.RI Scanner( function ", [" argument ", " keys ", " path_function ", " node_class ", " node_factory ", " scan_check ", " recursive ]) +.TP +.RI env.Scanner( function ", [" argument ", " keys ", " path_function ", " node_class ", " node_factory ", " scan_check ", " recursive ]) +Creates a Scanner object for +the specified +.IR function . +See the section "Scanner Objects," +below, for a complete explanation of the arguments and behavior. + +'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +env.SCCS() +A factory function that +returns a Builder object +to be used to fetch source files +from SCCS. +The returned Builder +is intended to be passed to the +.B SourceCode +function. + +Example: + +.ES +env.SourceCode('.', env.SCCS()) +.EE +.IP +Note that +.B scons +will fetch source files +from SCCS subdirectories automatically, +so configuring SCCS +as demonstrated in the above example +should only be necessary if +you are fetching from +.I s.SCCS +files in the same +directory as the source files, +or if you need to explicitly specify SCCS +for a specific subdirectory. + +'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.RI SConscript( scripts ", [" exports ", " variant_dir ", " duplicate ]) +'\" .RI SConscript( scripts ", [" exports ", " variant_dir ", " src_dir ", " duplicate ]) +.TP +.RI env.SConscript( scripts ", [" exports ", " variant_dir ", " duplicate ]) +'\" .RI env.SConscript( scripts ", [" exports ", " variant_dir ", " src_dir ", " duplicate ]) +.TP +.RI SConscript(dirs= subdirs ", [name=" script ", " exports ", " variant_dir ", " duplicate ]) +'\" .RI SConscript(dirs= subdirs ", [name=" script ", " exports ", " variant_dir ", " src_dir ", " duplicate ]) +.TP +.RI env.SConscript(dirs= subdirs ", [name=" script ", " exports ", " variant_dir ", " duplicate ]) +'\" .RI env.SConscript(dirs= subdirs ", [name=" script ", " exports ", " variant_dir ", " src_dir ", " duplicate ]) +This tells +.B scons +to execute +one or more subsidiary SConscript (configuration) files. +Any variables returned by a called script using +.BR Return () +will be returned by the call to +.BR SConscript (). +There are two ways to call the +.BR SConscript () +function. + +The first way you can call +.BR SConscript () +is to explicitly specify one or more +.I scripts +as the first argument. +A single script may be specified as a string; +multiple scripts must be specified as a list +(either explicitly or as created by +a function like +.BR Split ()). +Examples: +.ES +SConscript('SConscript') # run SConscript in the current directory +SConscript('src/SConscript') # run SConscript in the src directory +SConscript(['src/SConscript', 'doc/SConscript']) +config = SConscript('MyConfig.py') +.EE + +The second way you can call +.BR SConscript () +is to specify a list of (sub)directory names +as a +.RI dirs= subdirs +keyword argument. +In this case, +.B scons +will, by default, +execute a subsidiary configuration file named +.B SConscript +in each of the specified directories. +You may specify a name other than +.B SConscript +by supplying an optional +.RI name= script +keyword argument. +The first three examples below have the same effect +as the first three examples above: +.ES +SConscript(dirs='.') # run SConscript in the current directory +SConscript(dirs='src') # run SConscript in the src directory +SConscript(dirs=['src', 'doc']) +SConscript(dirs=['sub1', 'sub2'], name='MySConscript') +.EE + +The optional +.I exports +argument provides a list of variable names or a dictionary of +named values to export to the +.IR script(s) . +These variables are locally exported only to the specified +.IR script(s) , +and do not affect the global pool of variables used by the +.BR Export () +function. +'\"If multiple dirs are provided, each script gets a fresh export. +The subsidiary +.I script(s) +must use the +.BR Import () +function to import the variables. +Examples: +.ES +foo = SConscript('sub/SConscript', exports='env') +SConscript('dir/SConscript', exports=['env', 'variable']) +SConscript(dirs='subdir', exports='env variable') +SConscript(dirs=['one', 'two', 'three'], exports='shared_info') +.EE + +If the optional +.I variant_dir +argument is present, it causes an effect equivalent to the +.BR VariantDir () +method described below. +(If +.I variant_dir +is not present, the +'\" .IR src_dir and +.I duplicate +'\" arguments are ignored.) +argument is ignored.) +The +.I variant_dir +'\" and +'\" .I src_dir +'\" arguments are interpreted relative to the directory of the calling +argument is interpreted relative to the directory of the calling +.BR SConscript file. +See the description of the +.BR VariantDir () +function below for additional details and restrictions. + +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 + +'\" If +'\" .IR variant_dir " and" +'\" .IR src_dir " are both present," +'\" xxxxx everything is in a state of confusion. +'\" .ES +'\" SConscript(dirs = 'src', variant_dir = 'build', src_dir = '.') +'\" runs src/SConscript in build/src, but +'\" SConscript(dirs = 'lib', variant_dir = 'build', src_dir = 'src') +'\" runs lib/SConscript (in lib!). However, +'\" SConscript(dirs = 'src', variant_dir = 'build', src_dir = 'src') +'\" runs src/SConscript in build. Moreover, +'\" SConscript(dirs = 'src/lib', variant_dir = 'build', src_dir = 'src') +'\" runs src/lib/SConscript in build/lib. Moreover, +'\" SConscript(dirs = 'build/src/lib', variant_dir = 'build', src_dir = 'src') +'\" can't find build/src/lib/SConscript, even though it ought to exist. +'\" .EE +'\" is equivalent to +'\" .ES +'\" ???????????????? +'\" .EE +'\" and what about this alternative? +'\"TODO??? SConscript('build/SConscript', src_dir='src') + +Here are some composite examples: + +.ES +# collect the configuration information and use it to build src and doc +shared_info = SConscript('MyConfig.py') +SConscript('src/SConscript', exports='shared_info') +SConscript('doc/SConscript', exports='shared_info') +.EE + +.ES +# build debugging and production versions. SConscript +# can use Dir('.').path to determine variant. +SConscript('SConscript', variant_dir='debug', duplicate=0) +SConscript('SConscript', variant_dir='prod', duplicate=0) +.EE + +.ES +# build debugging and production versions. SConscript +# is passed flags to use. +opts = { 'CPPDEFINES' : ['DEBUG'], 'CCFLAGS' : '-pgdb' } +SConscript('SConscript', variant_dir='debug', duplicate=0, exports=opts) +opts = { 'CPPDEFINES' : ['NODEBUG'], 'CCFLAGS' : '-O' } +SConscript('SConscript', variant_dir='prod', duplicate=0, exports=opts) +.EE + +.ES +# build common documentation and compile for different architectures +SConscript('doc/SConscript', variant_dir='build/doc', duplicate=0) +SConscript('src/SConscript', variant_dir='build/x86', duplicate=0) +SConscript('src/SConscript', variant_dir='build/ppc', duplicate=0) +.EE + +'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.RI SConscriptChdir( value ) +.TP +.RI env.SConscriptChdir( value ) +By default, +.B scons +changes its working directory +to the directory in which each +subsidiary SConscript file lives. +This behavior may be disabled +by specifying either: + +.ES +SConscriptChdir(0) +env.SConscriptChdir(0) +.EE +.IP +in which case +.B scons +will stay in the top-level directory +while reading all SConscript files. +(This may be necessary when building from repositories, +when all the directories in which SConscript files may be found +don't necessarily exist locally.) +You may enable and disable +this ability by calling +SConscriptChdir() +multiple times. + +Example: + +.ES +env = Environment() +SConscriptChdir(0) +SConscript('foo/SConscript') # will not chdir to foo +env.SConscriptChdir(1) +SConscript('bar/SConscript') # will chdir to bar +.EE + +'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.RI SConsignFile([ file , dbm_module ]) +.TP +.RI env.SConsignFile([ file , dbm_module ]) +This tells +.B scons +to store all file signatures +in the specified database +.IR file . +If the +.I file +name is omitted, +.B .sconsign +is used by default. +(The actual file name(s) stored on disk +may have an appropriated suffix appended +by the +.IR dbm_module .) +If +.I file +is not an absolute path name, +the file is placed in the same directory as the top-level +.B SConstruct +file. + +If +.I file +is +.BR None , +then +.B scons +will store file signatures +in a separate +.B .sconsign +file in each directory, +not in one global database file. +(This was the default behavior +prior to SCons 0.96.91 and 0.97.) + +The optional +.I dbm_module +argument can be used to specify +which Python database module +The default is to use a custom +.B SCons.dblite +module that uses pickled +Python data structures, +and which works on all Python versions from 1.5.2 on. + +Examples: + +.ES +# Explicitly stores signatures in ".sconsign.dblite" +# in the top-level SConstruct directory (the +# default behavior). +SConsignFile() + +# Stores signatures in the file "etc/scons-signatures" +# relative to the top-level SConstruct directory. +SConsignFile("etc/scons-signatures") + +# Stores signatures in the specified absolute file name. +SConsignFile("/home/me/SCons/signatures") + +# Stores signatures in a separate .sconsign file +# in each directory. +SConsignFile(None) +.EE + +'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.RI env.SetDefault(key = val ", [...])" +Sets construction variables to default values specified with the keyword +arguments if (and only if) the variables are not already set. +The following statements are equivalent: + +.ES +env.SetDefault(FOO = 'foo') + +if not env.has_key('FOO'): env['FOO'] = 'foo' +.EE + +'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.RI SetOption( name ", " value ) +.TP +.RI env.SetOption( name ", " value ) +This function provides a way to set a select subset of the scons command +line options from a SConscript file. The options supported are: + +.RS 10 +.TP 6 +.B clean +which corresponds to -c, --clean and --remove; +.TP 6 +.B duplicate +which corresponds to --duplicate; +.TP 6 +.B help +which corresponds to -h and --help; +.TP 6 +.B implicit_cache +which corresponds to --implicit-cache; +.TP 6 +.B max_drift +which corresponds to --max-drift; +.TP 6 +.B no_exec +which corresponds to -n, --no-exec, --just-print, --dry-run and --recon; +.TP 6 +.B num_jobs +which corresponds to -j and --jobs; +.TP 6 +.B random +which corresponds to --random; and +.TP 6 +.B stack_size +which corresponds to --stack-size. +.RE + +.IP +See the documentation for the +corresponding command line object for information about each specific +option. + +Example: + +.ES +SetOption('max_drift', 1) +.EE + +'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.RI SideEffect( side_effect ", " target ) +.TP +.RI env.SideEffect( side_effect ", " target ) +Declares +.I side_effect +as a side effect of building +.IR target . +Both +.I side_effect +and +.I target +can be a list, a file name, or a node. +A side effect is a target file that is created or updated +as a side effect of building other targets. +For example, a Windows PDB +file is created as a side effect of building the .obj +files for a static library, +and various log files are created updated +as side effects of various TeX commands. +If a target is a side effect of multiple build commands, +.B scons +will ensure that only one set of commands +is executed at a time. +Consequently, you only need to use this method +for side-effect targets that are built as a result of +multiple build commands. + +Because multiple build commands may update +the same side effect file, +by default the +.I side_effect +target is +.I not +automatically removed +when the +.I target +is removed by the +.B -c +option. +(Note, however, that the +.I side_effect +might be removed as part of +cleaning the directory in which it lives.) +If you want to make sure the +.I side_effect +is cleaned whenever a specific +.I target +is cleaned, +you must specify this explicitly +with the +.BR Clean () +or +.BR env.Clean () +function. + +'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.RI SourceCode( entries ", " builder ) +.TP +.RI env.SourceCode( entries ", " builder ) +Arrange for non-existent source files to +be fetched from a source code management system +using the specified +.IR builder . +The specified +.I entries +may be a Node, string or list of both, +and may represent either individual +source files or directories in which +source files can be found. + +For any non-existent source files, +.B scons +will search up the directory tree +and use the first +.B SourceCode +builder it finds. +The specified +.I builder +may be +.BR None , +in which case +.B scons +will not use a builder to fetch +source files for the specified +.IR entries , +even if a +.B SourceCode +builder has been specified +for a directory higher up the tree. + +.B scons +will, by default, +fetch files from SCCS or RCS subdirectories +without explicit configuration. +This takes some extra processing time +to search for the necessary +source code management files on disk. +You can avoid these extra searches +and speed up your build a little +by disabling these searches as follows: + +.ES +env.SourceCode('.', None) +.EE + +.IP +Note that if the specified +.I builder +is one you create by hand, +it must have an associated +construction environment to use +when fetching a source file. + +.B scons +provides a set of canned factory +functions that return appropriate +Builders for various popular +source code management systems. +Canonical examples of invocation include: + +.ES +env.SourceCode('.', env.BitKeeper('/usr/local/BKsources')) +env.SourceCode('src', env.CVS('/usr/local/CVSROOT')) +env.SourceCode('/', env.RCS()) +env.SourceCode(['f1.c', 'f2.c'], env.SCCS()) +env.SourceCode('no_source.c', None) +.EE +'\"env.SourceCode('.', env.Subversion('file:///usr/local/Subversion')) + +'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.RI env.subst( input ", [" raw ", " target ", " source ", " conv ]) +Performs construction variable interpolation +on the specified string or sequence argument +.IR input . + +By default, +leading or trailing white space will +be removed from the result. +and all sequences of white space +will be compressed to a single space character. +Additionally, any +.B $( +and +.B $) +character sequences will be stripped from the returned string, +The optional +.I raw +argument may be set to +.B 1 +if you want to preserve white space and +.BR $( - $) +sequences. +The +.I raw +argument may be set to +.B 2 +if you want to strip +all characters between +any +.B $( +and +.B $) +pairs +(as is done for signature calculation). + +If the input is a sequence +(list or tuple), +the individual elements of +the sequence will be expanded, +and the results will be returned as a list. + +The optional +.I target +and +.I source +keyword arguments +must be set to lists of +target and source nodes, respectively, +if you want the +.BR $TARGET , +.BR $TARGETS , +.BR $SOURCE +and +.BR $SOURCES +to be available for expansion. +This is usually necessary if you are +calling +.BR env.subst () +from within a Python function used +as an SCons action. + +Returned string values or sequence elements +are converted to their string representation by default. +The optional +.I conv +argument +may specify a conversion function +that will be used in place of +the default. +For example, if you want Python objects +(including SCons Nodes) +to be returned as Python objects, +you can use the Python +.B lambda +idiom to pass in an unnamed function +that simply returns its unconverted argument. + +Example: + +.ES +print env.subst("The C compiler is: $CC") + +def compile(target, source, env): + sourceDir = env.subst("${SOURCE.srcdir}", + target=target, + source=source) + +source_nodes = env.subst('$EXPAND_TO_NODELIST', + conv=lambda x: x) +.EE + +'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +'\".TP +'\".RI Subversion( repository ", " module ) +'\"A factory function that +'\"returns a Builder object +'\"to be used to fetch source files +'\"from the specified Subversion +'\".IR repository . +'\"The returned Builder +'\"is intended to be passed to the +'\".B SourceCode +'\"function. +'\" +'\"The optional specified +'\".I module +'\"will be added to the beginning +'\"of all repository path names; +'\"this can be used, in essence, +'\"to strip initial directory names +'\"from the repository path names, +'\"so that you only have to +'\"replicate part of the repository +'\"directory hierarchy in your +'\"local build directory. +'\" +'\"Example: +'\" +'\".ES +'\"# Will fetch foo/bar/src.c +'\"# from /usr/local/Subversion/foo/bar/src.c. +'\"env.SourceCode('.', env.Subversion('file:///usr/local/Subversion')) +'\" +'\"# Will fetch bar/src.c +'\"# from /usr/local/Subversion/foo/bar/src.c. +'\"env.SourceCode('.', env.Subversion('file:///usr/local/Subversion', 'foo')) +'\" +'\"# Will fetch src.c +'\"# from /usr/local/Subversion/foo/bar/src.c. +'\"env.SourceCode('.', env.Subversion('file:///usr/local/Subversion', 'foo/bar')) +'\".EE + +'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.RI SourceSignatures( type ) +.TP +.RI env.SourceSignatures( type ) +Note: Although it is not yet officially deprecated, +use of this function is discouraged. +See the +.BR Decider () +function for a more flexible and straightforward way +to configure SCons' decision-making. + +The +.BR SourceSignatures () +function tells +.B scons +how to decide if a source file +(a file that is not built from any other files) +has changed since the last time it +was used to build a particular target file. +Legal values are +.B "MD5" +or +.BR "timestamp" . + +If the environment method is used, +the specified type of source signature +is only used when deciding whether targets +built with that environment are up-to-date or must be rebuilt. +If the global function is used, +the specified type of source signature becomes the default +used for all decisions +about whether targets are up-to-date. + +.B "MD5" +means +.B scons +decides that a source file has changed +if the MD5 checksum of its contents has changed since +the last time it was used to rebuild a particular target file. + +.B "timestamp" +means +.B scons +decides that a source file has changed +if its timestamp (modification time) has changed since +the last time it was used to rebuild a particular target file. +(Note that although this is similar to the behavior of Make, +by default it will also rebuild if the dependency is +.I older +than the last time it was used to rebuild the target file.) + +There is no different between the two behaviors +for Python +.BR Value () +node objects. + +.B "MD5" +signatures take longer to compute, +but are more accurate than +.B "timestamp" +signatures. +The default value is +.BR "MD5" . + +Note that the default +.BR TargetSignatures () +setting (see below) +is to use this +.BR SourceSignatures () +setting for any target files that are used +to build other target files. +Consequently, changing the value of +.BR SourceSignatures () +will, by default, +affect the up-to-date decision for all files in the build +(or all files built with a specific construction environment +when +.BR env.SourceSignatures () +is used). + +'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.RI Split( arg ) +.TP +.RI env.Split( arg ) +Returns a list of file names or other objects. +If arg is a string, +it will be split on strings of white-space characters +within the string, +making it easier to write long lists of file names. +If arg is already a list, +the list will be returned untouched. +If arg is any other type of object, +it will be returned as a list +containing just the object. + +Example: + +.ES +files = Split("f1.c f2.c f3.c") +files = env.Split("f4.c f5.c f6.c") +files = Split(""" + f7.c + f8.c + f9.c +""") +.EE + +'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.RI Tag( node ", " tags ) +Annotates file or directory Nodes with +information about how the +.BR Package () +Builder should package those files or directories. +All tags are optional. + +Examples: + +.ES +# makes sure the built library will be installed with 0644 file +# access mode +Tag( Library( 'lib.c' ), UNIX_ATTR="0644" ) + +# marks file2.txt to be a documentation file +Tag( 'file2.txt', DOC ) +.EE + +'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.RI TargetSignatures( type ) +.TP +.RI env.TargetSignatures( type ) +Note: Although it is not yet officially deprecated, +use of this function is discouraged. +See the +.BR Decider () +function for a more flexible and straightforward way +to configure SCons' decision-making. + +The +.BR TargetSignatures () +function tells +.B scons +how to decide if a target file +(a file that +.I is +built from any other files) +has changed since the last time it +was used to build some other target file. +Legal values are +.BR "build" ; +.BR "content" +(or its synonym +.BR "MD5" ); +.BR "timestamp" ; +or +.BR "source" . + +If the environment method is used, +the specified type of target signature is only used +for targets built with that environment. +If the global function is used, +the specified type of signature becomes the default +used for all target files that +don't have an explicit target signature type +specified for their environments. + +.B "content" +(or its synonym +.BR "MD5" ) +means +.B scons +decides that a target file has changed +if the MD5 checksum of its contents has changed since +the last time it was used to rebuild some other target file. +This means +.B scons +will open up +MD5 sum the contents +of target files after they're built, +and may decide that it does not need to rebuild +"downstream" target files if a file was +rebuilt with exactly the same contents as the last time. + +.B "timestamp" +means +.B scons +decides that a target file has changed +if its timestamp (modification time) has changed since +the last time it was used to rebuild some other target file. +(Note that although this is similar to the behavior of Make, +by default it will also rebuild if the dependency is +.I older +than the last time it was used to rebuild the target file.) + +.B "source" +means +.B scons +decides that a target file has changed +as specified by the corresponding +.BR SourceSignatures () +setting +.BR "" ( "MD5" +or +.BR "timestamp" ). +This means that +.B scons +will treat all input files to a target the same way, +regardless of whether they are source files +or have been built from other files. + +.B "build" +means +.B scons +decides that a target file has changed +if it has been rebuilt in this invocation +or if its content or timestamp have changed +as specified by the corresponding +.BR SourceSignatures () +setting. +This "propagates" the status of a rebuilt file +so that other "downstream" target files +will always be rebuilt, +even if the contents or the timestamp +have not changed. + +.B "build" +signatures are fastest because +.B "content" +(or +.BR "MD5" ) +signatures take longer to compute, +but are more accurate than +.B "timestamp" +signatures, +and can prevent unnecessary "downstream" rebuilds +when a target file is rebuilt to the exact same contents +as the previous build. +The +.B "source" +setting provides the most consistent behavior +when other target files may be rebuilt from +both source and target input files. +The default value is +.BR "source" . + +Because the default setting is +.BR "source" , +using +.BR SourceSignatures () +is generally preferable to +.BR TargetSignatures () , +so that the up-to-date decision +will be consistent for all files +(or all files built with a specific construction environment). +Use of +.BR TargetSignatures () +provides specific control for how built target files +affect their "downstream" dependencies. + +'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.RI Tool( string [, toolpath ", " **kw ]) +Returns a callable object +that can be used to initialize +a construction environment using the +tools keyword of the Environment() method. +The object may be called with a construction +environment as an argument, +in which case the object will +add the necessary variables +to the construction environment +and the name of the tool will be added to the +.B $TOOLS +construction variable. + +Additional keyword arguments are passed to the tool's +.B generate() +method. + +Examples: + +.ES +env = Environment(tools = [ Tool('msvc') ]) + +env = Environment() +t = Tool('msvc') +t(env) # adds 'msvc' to the TOOLS variable +u = Tool('opengl', toolpath = ['tools']) +u(env) # adds 'opengl' to the TOOLS variable +.EE +.TP +.RI env.Tool( string [, toolpath ", " **kw ]) +Applies the callable object for the specified tool +.I string +to the environment through which the method was called. + +Additional keyword arguments are passed to the tool's +.B generate() +method. + +.ES +env.Tool('gcc') +env.Tool('opengl', toolpath = ['build/tools']) +.EE + +'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.RI Value( value ", [" built_value ]) +.TP +.RI env.Value( value ", [" built_value ]) +Returns a Node object representing the specified Python value. Value +Nodes can be used as dependencies of targets. If the result of +calling +.BR str( value ) +changes between SCons runs, any targets depending on +.BR Value( value ) +will be rebuilt. +(This is true even when using timestamps to decide if +files are up-to-date.) +When using timestamp source signatures, Value Nodes' +timestamps are equal to the system time when the Node is created. + +The returned Value Node object has a +.BR write () +method that can be used to "build" a Value Node +by setting a new value. +The optional +.I built_value +argument can be specified +when the Value Node is created +to indicate the Node should already be considered +"built." +There is a corresponding +.BR read () +method that will return the built value of the Node. + +Examples: + +.ES +env = Environment() + +def create(target, source, env): + # A function that will write a 'prefix=$SOURCE' + # string into the file name specified as the + # $TARGET. + f = open(str(target[0]), 'wb') + f.write('prefix=' + source[0].get_contents()) + +# Fetch the prefix= argument, if any, from the command +# line, and use /usr/local as the default. +prefix = ARGUMENTS.get('prefix', '/usr/local') + +# Attach a .Config() builder for the above function action +# to the construction environment. +env['BUILDERS']['Config'] = Builder(action = create) +env.Config(target = 'package-config', source = Value(prefix)) + +def build_value(target, source, env): + # A function that "builds" a Python Value by updating + # the the Python value with the contents of the file + # specified as the source of the Builder call ($SOURCE). + target[0].write(source[0].get_contents()) + +output = env.Value('before') +input = env.Value('after') + +# Attach a .UpdateValue() builder for the above function +# action to the construction environment. +env['BUILDERS']['UpdateValue'] = Builder(action = build_value) +env.UpdateValue(target = Value(output), source = Value(input)) +.EE + +'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.RI VariantDir( variant_dir ", " src_dir ", [" duplicate ]) +.TP +.RI env.VariantDir( variant_dir ", " src_dir ", [" duplicate ]) +Use the +.BR VariantDir () +function to create a copy of your sources in another location: +if a name under +.IR variant_dir +is not found but exists under +.IR src_dir , +the file or directory is copied to +.IR variant_dir . +Target files can be built in a different directory +than the original sources by simply refering to the sources (and targets) +within the variant tree. + +.BR VariantDir () +can be called multiple times with the same +.I src_dir +to set up multiple builds with different options +.RI ( variants ). +The +.I src_dir +location must be in or underneath the SConstruct file's directory, and +.I variant_dir +may not be underneath +.IR src_dir . +'\"TODO: Can the above restrictions be clarified or relaxed? +'\"TODO: The latter restriction is clearly not completely right; +'\"TODO: src_dir = '.' works fine with a build dir under it. + +The default behavior is for +.B scons +to physically duplicate the source files in the variant tree. +Thus, a build performed in the variant tree is guaranteed to be identical +to a build performed in the source tree even if +intermediate source files are generated during the build, +or preprocessors or other scanners search for included files +relative to the source file, +or individual compilers or other invoked tools are hard-coded +to put derived files in the same directory as source files. + +If possible on the platform, +the duplication is performed by linking rather than copying; +see also the +.IR --duplicate +command-line option. +Moreover, only the files needed for the build are duplicated; +files and directories that are not used are not present in +.IR variant_dir . + +Duplicating the source tree may be disabled by setting the +.I duplicate +argument to 0 (zero). +This will cause +.B scons +to invoke Builders using the path names of source files in +.I src_dir +and the path names of derived files within +.IR variant_dir . +This is always more efficient than +.IR duplicate =1, +and is usually safe for most builds +(but see above for cases that may cause problems). + +Note that +.BR VariantDir () +works most naturally with a subsidiary SConscript file. +However, you would then call the subsidiary SConscript file +not in the source directory, but in the +.I variant_dir , +regardless of the value of +.IR duplicate . +This is how you tell +.B scons +which variant of a source tree to build: + +.ES +# run src/SConscript in two variant directories +VariantDir('build/variant1', 'src') +SConscript('build/variant1/SConscript') +VariantDir('build/variant2', 'src') +SConscript('build/variant2/SConscript') +.EE + +.IP +See also the +.BR SConscript () +function, described above, +for another way to specify a variant directory +in conjunction with calling a subsidiary SConscript file. + +Examples: + +.ES +# use names in the build directory, not the source directory +VariantDir('build', 'src', duplicate=0) +Program('build/prog', 'build/source.c') +.EE + +.ES +# this builds both the source and docs in a separate subtree +VariantDir('build', '.', duplicate=0) +SConscript(dirs=['build/src','build/doc']) +.EE + +.ES +# same as previous example, but only uses SConscript +SConscript(dirs='src', variant_dir='build/src', duplicate=0) +SConscript(dirs='doc', variant_dir='build/doc', duplicate=0) +.EE + +'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.RI WhereIs( program ", [" path ", " pathext ", " reject ]) +.TP +.RI env.WhereIs( program ", [" path ", " pathext ", " reject ]) + +Searches for the specified executable +.I program, +returning the full path name to the program +if it is found, +and returning None if not. +Searches the specified +.I path, +the value of the calling environment's PATH +(env['ENV']['PATH']), +or the user's current external PATH +(os.environ['PATH']) +by default. +On Windows systems, searches for executable +programs with any of the file extensions +listed in the specified +.I pathext, +the calling environment's PATHEXT +(env['ENV']['PATHEXT']) +or the user's current PATHEXT +(os.environ['PATHEXT']) +by default. +Will not select any +path name or names +in the specified +.I reject +list, if any. + +.SS SConscript Variables +In addition to the global functions and methods, +.B scons +supports a number of Python variables +that can be used in SConscript files +to affect how you want the build to be performed. +These variables may be accessed from custom Python modules that you +import into an SConscript file by adding the following +to the Python module: + +.ES +from SCons.Script import * +.EE + +'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +ARGLIST +A list +.IR keyword = value +arguments specified on the command line. +Each element in the list is a tuple +containing the +.RI ( keyword , value ) +of the argument. +The separate +.I keyword +and +.I value +elements of the tuple +can be accessed by +subscripting for element +.B [0] +and +.B [1] +of the tuple, respectively. + +Example: + +.ES +print "first keyword, value =", ARGLIST[0][0], ARGLIST[0][1] +print "second keyword, value =", ARGLIST[1][0], ARGLIST[1][1] +third_tuple = ARGLIST[2] +print "third keyword, value =", third_tuple[0], third_tuple[1] +for key, value in ARGLIST: + # process key and value +.EE + +'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +ARGUMENTS +A dictionary of all the +.IR keyword = value +arguments specified on the command line. +The dictionary is not in order, +and if a given keyword has +more than one value assigned to it +on the command line, +the last (right-most) value is +the one in the +.B ARGUMENTS +dictionary. + +Example: + +.ES +if ARGUMENTS.get('debug', 0): + env = Environment(CCFLAGS = '-g') +else: + env = Environment() +.EE + +'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +BUILD_TARGETS +A list of the targets which +.B scons +will actually try to build, +regardless of whether they were specified on +the command line or via the +.BR Default () +function or method. +The elements of this list may be strings +.I or +nodes, so you should run the list through the Python +.B str +function to make sure any Node path names +are converted to strings. + +Because this list may be taken from the +list of targets specified using the +.BR Default () +function or method, +the contents of the list may change +on each successive call to +.BR Default (). +See the +.B DEFAULT_TARGETS +list, below, +for additional information. + +Example: + +.ES +if 'foo' in BUILD_TARGETS: + print "Don't forget to test the `foo' program!" +if 'special/program' in BUILD_TARGETS: + SConscript('special') +.EE +.IP +Note that the +.B BUILD_TARGETS +list only contains targets expected listed +on the command line or via calls to the +.BR Default () +function or method. +It does +.I not +contain all dependent targets that will be built as +a result of making the sure the explicitly-specified +targets are up to date. + +'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +COMMAND_LINE_TARGETS +A list of the targets explicitly specified on +the command line. +If there are no targets specified on the command line, +the list is empty. +This can be used, for example, +to take specific actions only +when a certain target or targets +is explicitly being built. + +Example: + +.ES +if 'foo' in COMMAND_LINE_TARGETS: + print "Don't forget to test the `foo' program!" +if 'special/program' in COMMAND_LINE_TARGETS: + SConscript('special') +.EE + +'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +DEFAULT_TARGETS +A list of the target +.I nodes +that have been specified using the +.BR Default () +function or method. +The elements of the list are nodes, +so you need to run them through the Python +.B str +function to get at the path name for each Node. + +Example: + +.ES +print str(DEFAULT_TARGETS[0]) +if 'foo' in map(str, DEFAULT_TARGETS): + print "Don't forget to test the `foo' program!" +.EE +.IP +The contents of the +.B DEFAULT_TARGETS +list change on on each successive call to the +.BR Default () +function: + +.ES +print map(str, DEFAULT_TARGETS) # originally [] +Default('foo') +print map(str, DEFAULT_TARGETS) # now a node ['foo'] +Default('bar') +print map(str, DEFAULT_TARGETS) # now a node ['foo', 'bar'] +Default(None) +print map(str, DEFAULT_TARGETS) # back to [] +.EE +.IP +Consequently, be sure to use +.B DEFAULT_TARGETS +only after you've made all of your +.BR Default () +calls, +or else simply be careful of the order +of these statements in your SConscript files +so that you don't look for a specific +default target before it's actually been added to the list. + +.SS Construction Variables +.\" XXX From Gary Ruben, 23 April 2002: +.\" I think it would be good to have an example with each construction +.\" variable description in the documentation. +.\" eg. +.\" CC The C compiler +.\" Example: env["CC"] = "c68x" +.\" Default: env["CC"] = "cc" +.\" +.\" CCCOM The command line ... +.\" Example: +.\" To generate the compiler line c68x -ps -qq -mr -o $TARGET $SOURCES +.\" env["CC"] = "c68x" +.\" env["CFLAGS"] = "-ps -qq -mr" +.\" env["CCCOM"] = "$CC $CFLAGS -o $TARGET $SOURCES +.\" Default: +.\" (I dunno what this is ;-) +A construction environment has an associated dictionary of +.I construction variables +that are used by built-in or user-supplied build rules. +Construction variables must follow the same rules for +Python identifiers: +the initial character must be an underscore or letter, +followed by any number of underscores, letters, or digits. + +A number of useful construction variables are automatically defined by +scons for each supported platform, and additional construction variables +can be defined by the user. The following is a list of the automatically +defined construction variables: + +'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +'\" BEGIN GENERATED CONSTRUCTION VARIABLE DESCRIPTIONS +'\" +'\" The descriptions below of the various SCons construction variables +'\" are generated from the .xml files that live next to the various +'\" Python modules in the build enginer library. If you're reading +'\" this [gnt]roff file with an eye towards patching this man page, +'\" you can still submit a diff against this text, but it will have to +'\" be translated to a diff against the underlying .xml file before the +'\" patch is actually accepted. If you do that yourself, it will make +'\" it easier to integrate the patch. +'\" +'\" BEGIN GENERATED CONSTRUCTION VARIABLE DESCRIPTIONS +'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" + +.IP AR +The static library archiver. + +.IP ARCHITECTURE +Specifies the system architecture for which +the package is being built. +The default is the system architecture +of the machine on which SCons is running. +This is used to fill in the +.B Architecture: +field in an Ipkg +\fBcontrol\fP file, +and as part of the name of a generated RPM file. + +.IP ARCOM +The command line used to generate a static library from object files. + +.IP ARCOMSTR +The string displayed when an object file +is generated from an assembly-language source file. +If this is not set, then $ARCOM (the command line) is displayed. + +.ES +env = Environment(ARCOMSTR = "Archiving $TARGET") +.EE + +.IP ARFLAGS +General options passed to the static library archiver. + +.IP AS +The assembler. + +.IP ASCOM +The command line used to generate an object file +from an assembly-language source file. + +.IP ASCOMSTR +The string displayed when an object file +is generated from an assembly-language source file. +If this is not set, then $ASCOM (the command line) is displayed. + +.ES +env = Environment(ASCOMSTR = "Assembling $TARGET") +.EE + +.IP ASFLAGS +General options passed to the assembler. + +.IP ASPPCOM +The command line used to assemble an assembly-language +source file into an object file +after first running the file through the C preprocessor. +Any options specified +in the $ASFLAGS and $CPPFLAGS construction variables +are included on this command line. + +.IP ASPPCOMSTR +The string displayed when an object file +is generated from an assembly-language source file +after first running the file through the C preprocessor. +If this is not set, then $ASPPCOM (the command line) is displayed. + +.ES +env = Environment(ASPPCOMSTR = "Assembling $TARGET") +.EE + +.IP ASPPFLAGS +General options when an assembling an assembly-language +source file into an object file +after first running the file through the C preprocessor. +The default is to use the value of $ASFLAGS. + +.IP BIBTEX +The bibliography generator for the TeX formatter and typesetter and the +LaTeX structured formatter and typesetter. + +.IP BIBTEXCOM +The command line used to call the bibliography generator for the +TeX formatter and typesetter and the LaTeX structured formatter and +typesetter. + +.IP BIBTEXCOMSTR +The string displayed when generating a bibliography +for TeX or LaTeX. +If this is not set, then $BIBTEXCOM (the command line) is displayed. + +.ES +env = Environment(BIBTEXCOMSTR = "Generating bibliography $TARGET") +.EE + +.IP BIBTEXFLAGS +General options passed to the bibliography generator for the TeX formatter +and typesetter and the LaTeX structured formatter and typesetter. + +.IP BITKEEPER +The BitKeeper executable. + +.IP BITKEEPERCOM +The command line for +fetching source files using BitKeeper. + +.IP BITKEEPERCOMSTR +The string displayed when fetching +a source file using BitKeeper. +If this is not set, then $BITKEEPERCOM +(the command line) is displayed. + +.IP BITKEEPERGET +The command ($BITKEEPER) and subcommand +for fetching source files using BitKeeper. + +.IP BITKEEPERGETFLAGS +Options that are passed to the BitKeeper +.B get +subcommand. + +.IP BUILDERS +A dictionary mapping the names of the builders +available through this environment +to underlying Builder objects. +Builders named +Alias, CFile, CXXFile, DVI, Library, Object, PDF, PostScript, and Program +are available by default. +If you initialize this variable when an +Environment is created: + +.ES +env = Environment(BUILDERS = {'NewBuilder' : foo}) +.EE +.IP +the default Builders will no longer be available. +To use a new Builder object in addition to the default Builders, +add your new Builder object like this: + +.ES +env = Environment() +env.Append(BUILDERS = {'NewBuilder' : foo}) +.EE +.IP +or this: + +.ES +env = Environment() +env['BUILDERS]['NewBuilder'] = foo +.EE + +.IP CC +The C compiler. + +.IP CCCOM +The command line used to compile a C source file to a (static) object +file. Any options specified in the $CFLAGS, $CCFLAGS and +$CPPFLAGS construction variables are included on this command +line. + +.IP CCCOMSTR +The string displayed when a C source file +is compiled to a (static) object file. +If this is not set, then $CCCOM (the command line) is displayed. + +.ES +env = Environment(CCCOMSTR = "Compiling static object $TARGET") +.EE + +.IP CCFLAGS +General options that are passed to the C and C++ compilers. + +.IP CCPCHFLAGS +Options added to the compiler command line +to support building with precompiled headers. +The default value expands expands to the appropriate +Microsoft Visual C++ command-line options +when the $PCH construction variable is set. + +.IP CCPDBFLAGS +Options added to the compiler command line +to support storing debugging information in a +Microsoft Visual C++ PDB file. +The default value expands expands to appropriate +Microsoft Visual C++ command-line options +when the $PDB construction variable is set. + +The Visual C++ compiler option that SCons uses by default +to generate PDB information is \fB/Z7\fP. +This works correctly with parallel (\fB\-j\fP) builds +because it embeds the debug information in the intermediate object files, +as opposed to sharing a single PDB file between multiple object files. +This is also the only way to get debug information +embedded into a static library. +Using the \fB/Zi\fP instead may yield improved +link-time performance, +although parallel builds will no longer work. + +You can generate PDB files with the \fB/Zi\fP +switch by overriding the default $CCPDBFLAGS variable as follows: + +.ES +env['CCPDBFLAGS'] = ['${(PDB and "/Zi /Fd%s" % File(PDB)) or ""}'] +.EE +.IP +An alternative would be to use the \fB/Zi\fP +to put the debugging information in a separate \fB.pdb\fP +file for each object file by overriding +the $CCPDBFLAGS variable as follows: + +.ES +env['CCPDBFLAGS'] = '/Zi /Fd${TARGET}.pdb' +.EE + +.IP CCVERSION +The version number of the C compiler. +This may or may not be set, +depending on the specific C compiler being used. + +.IP CFILESUFFIX +The suffix for C source files. +This is used by the internal CFile builder +when generating C files from Lex (.l) or YACC (.y) input files. +The default suffix, of course, is +.B .c +(lower case). +On case-insensitive systems (like Windows), +SCons also treats +.B .C +(upper case) files +as C files. + +.IP CFLAGS +General options that are passed to the C compiler (C only; not C++). + +.IP CHANGE_SPECFILE +A hook for modifying the file that controls the packaging build +(the \fB.spec\fP for RPM, +the \fBcontrol\fP for Ipkg, +the \fB.wxs\fP for MSI). +If set, the function will be called +after the SCons template for the file has been written. +XXX + +.IP CHANGED_SOURCES +A reserved variable name +that may not be set or used in a construction environment. +(See "Variable Substitution," below.) + +.IP CHANGED_TARGETS +A reserved variable name +that may not be set or used in a construction environment. +(See "Variable Substitution," below.) + +.IP CHANGELOG +The name of a file containing the change log text +to be included in the package. +This is included as the +.B %changelog +section of the RPM +\fB.spec\fP file. + +.IP _concat +A function used to produce variables like $_CPPINCFLAGS. It takes +four or five +arguments: a prefix to concatenate onto each element, a list of +elements, a suffix to concatenate onto each element, an environment +for variable interpolation, and an optional function that will be +called to transform the list before concatenation. + +.ES +env['_CPPINCFLAGS'] = '$( ${_concat(INCPREFIX, CPPPATH, INCSUFFIX, __env__, RDirs)} $)', +.EE + +.IP CONFIGUREDIR +The name of the directory in which +Configure context test files are written. +The default is +.B .sconf_temp +in the top-level directory +containing the +.B SConstruct +file. + +.IP CONFIGURELOG +The name of the Configure context log file. +The default is +.B config.log +in the top-level directory +containing the +.B SConstruct +file. + +.IP _CPPDEFFLAGS +An automatically-generated construction variable +containing the C preprocessor command-line options +to define values. +The value of $_CPPDEFFLAGS is created +by appending $CPPDEFPREFIX and $CPPDEFSUFFIX +to the beginning and end +of each definition in $CPPDEFINES. + +.IP CPPDEFINES +A platform independent specification of C preprocessor definitions. +The definitions will be added to command lines +through the automatically-generated +$_CPPDEFFLAGS construction variable (see above), +which is constructed according to +the type of value of $CPPDEFINES: + +If $CPPDEFINES is a string, +the values of the +$CPPDEFPREFIX and $CPPDEFSUFFIX +construction variables +will be added to the beginning and end. + +.ES +# Will add -Dxyz to POSIX compiler command lines, +# and /Dxyz to Microsoft Visual C++ command lines. +env = Environment(CPPDEFINES='xyz') +.EE +.IP +If $CPPDEFINES is a list, +the values of the +$CPPDEFPREFIX and $CPPDEFSUFFIX +construction variables +will be appended to the beginning and end +of each element in the list. +If any element is a list or tuple, +then the first item is the name being +defined and the second item is its value: + +.ES +# Will add -DB=2 -DA to POSIX compiler command lines, +# and /DB=2 /DA to Microsoft Visual C++ command lines. +env = Environment(CPPDEFINES=[('B', 2), 'A']) +.EE +.IP +If $CPPDEFINES is a dictionary, +the values of the +$CPPDEFPREFIX and $CPPDEFSUFFIX +construction variables +will be appended to the beginning and end +of each item from the dictionary. +The key of each dictionary item +is a name being defined +to the dictionary item's corresponding value; +if the value is +.BR None , +then the name is defined without an explicit value. +Note that the resulting flags are sorted by keyword +to ensure that the order of the options on the +command line is consistent each time +.B scons +is run. + +.ES +# Will add -DA -DB=2 to POSIX compiler command lines, +# and /DA /DB=2 to Microsoft Visual C++ command lines. +env = Environment(CPPDEFINES={'B':2, 'A':None}) +.EE + +.IP CPPDEFPREFIX +The prefix used to specify preprocessor definitions +on the C compiler command line. +This will be appended to the beginning of each definition +in the $CPPDEFINES construction variable +when the $_CPPDEFFLAGS variable is automatically generated. + +.IP CPPDEFSUFFIX +The suffix used to specify preprocessor definitions +on the C compiler command line. +This will be appended to the end of each definition +in the $CPPDEFINES construction variable +when the $_CPPDEFFLAGS variable is automatically generated. + +.IP CPPFLAGS +User-specified C preprocessor options. +These will be included in any command that uses the C preprocessor, +including not just compilation of C and C++ source files +via the $CCCOM, +$SHCCCOM, +$CXXCOM and +$SHCXXCOM command lines, +but also the $FORTRANPPCOM, +$SHFORTRANPPCOM, +$F77PPCOM and +$SHF77PPCOM command lines +used to compile a Fortran source file, +and the $ASPPCOM command line +used to assemble an assembly language source file, +after first running each file through the C preprocessor. +Note that this variable does +.I not +contain +.B \-I +(or similar) include search path options +that scons generates automatically from $CPPPATH. +See $_CPPINCFLAGS, below, +for the variable that expands to those options. + +.IP _CPPINCFLAGS +An automatically-generated construction variable +containing the C preprocessor command-line options +for specifying directories to be searched for include files. +The value of $_CPPINCFLAGS is created +by appending $INCPREFIX and $INCSUFFIX +to the beginning and end +of each directory in $CPPPATH. + +.IP CPPPATH +The list of directories that the C preprocessor will search for include +directories. The C/C++ implicit dependency scanner will search these +directories for include files. Don't explicitly put include directory +arguments in CCFLAGS or CXXFLAGS because the result will be non-portable +and the directories will not be searched by the dependency scanner. Note: +directory names in CPPPATH will be looked-up relative to the SConscript +directory when they are used in a command. To force +.B scons +to look-up a directory relative to the root of the source tree use #: + +.ES +env = Environment(CPPPATH='#/include') +.EE +.IP +The directory look-up can also be forced using the +.BR Dir () +function: + +.ES +include = Dir('include') +env = Environment(CPPPATH=include) +.EE +.IP +The directory list will be added to command lines +through the automatically-generated +$_CPPINCFLAGS +construction variable, +which is constructed by +appending the values of the +$INCPREFIX and $INCSUFFIX +construction variables +to the beginning and end +of each directory in $CPPPATH. +Any command lines you define that need +the CPPPATH directory list should +include $_CPPINCFLAGS: + +.ES +env = Environment(CCCOM="my_compiler $_CPPINCFLAGS -c -o $TARGET $SOURCE") +.EE + +.IP CPPSUFFIXES +The list of suffixes of files that will be scanned +for C preprocessor implicit dependencies +(#include lines). +The default list is: + +.ES +[".c", ".C", ".cxx", ".cpp", ".c++", ".cc", + ".h", ".H", ".hxx", ".hpp", ".hh", + ".F", ".fpp", ".FPP", + ".m", ".mm", + ".S", ".spp", ".SPP"] +.EE + +.IP CVS +The CVS executable. + +.IP CVSCOFLAGS +Options that are passed to the CVS checkout subcommand. + +.IP CVSCOM +The command line used to +fetch source files from a CVS repository. + +.IP CVSCOMSTR +The string displayed when fetching +a source file from a CVS repository. +If this is not set, then $CVSCOM +(the command line) is displayed. + +.IP CVSFLAGS +General options that are passed to CVS. +By default, this is set to +.B \-d $CVSREPOSITORY +to specify from where the files must be fetched. + +.IP CVSREPOSITORY +The path to the CVS repository. +This is referenced in the default +$CVSFLAGS value. + +.IP CXX +The C++ compiler. + +.IP CXXCOM +The command line used to compile a C++ source file to an object file. +Any options specified in the $CXXFLAGS and +$CPPFLAGS construction variables +are included on this command line. + +.IP CXXCOMSTR +The string displayed when a C++ source file +is compiled to a (static) object file. +If this is not set, then $CXXCOM (the command line) is displayed. + +.ES +env = Environment(CXXCOMSTR = "Compiling static object $TARGET") +.EE + +.IP CXXFILESUFFIX +The suffix for C++ source files. +This is used by the internal CXXFile builder +when generating C++ files from Lex (.ll) or YACC (.yy) input files. +The default suffix is +.BR .cc . +SCons also treats files with the suffixes +.BR .cpp , +.BR .cxx , +.BR .c++ , +and +.B .C++ +as C++ files, +and files with +.B .mm +suffixes as Objective C++ files. +On case-sensitive systems (Linux, UNIX, and other POSIX-alikes), +SCons also treats +.B .C +(upper case) files +as C++ files. + +.IP CXXFLAGS +General options that are passed to the C++ compiler. +By default, this includes the value of $CCFLAGS, +so that setting $CCFLAGS affects both C and C++ compilation. +If you want to add C++-specific flags, +you must set or override the value of $CXXFLAGS. + +.IP CXXVERSION +The version number of the C++ compiler. +This may or may not be set, +depending on the specific C++ compiler being used. + +.IP DESCRIPTION +A long description of the project being packaged. +This is included in the relevant section +of the file that controls the packaging build. + +.IP DESCRIPTION_lang +A language-specific long description for +the specified \fIlang\fP. +This is used to populate a +.B %description -l +section of an RPM +\fB.spec\fP file. + +.IP Dir +A function that converts a string +into a Dir instance relative to the target being built. + +.IP Dirs +A function that converts a list of strings +into a list of Dir instances relative to the target being built. + +.IP DSUFFIXES +The list of suffixes of files that will be scanned +for imported D package files. +The default list is: + +.ES +['.d'] +.EE + +.IP DVIPDF +The TeX DVI file to PDF file converter. + +.IP DVIPDFCOM +The command line used to convert TeX DVI files into a PDF file. + +.IP DVIPDFCOMSTR +The string displayed when a TeX DVI file +is converted into a PDF file. +If this is not set, then $DVIPDFCOM (the command line) is displayed. + +.IP DVIPDFFLAGS +General options passed to the TeX DVI file to PDF file converter. + +.IP DVIPS +The TeX DVI file to PostScript converter. + +.IP DVIPSFLAGS +General options passed to the TeX DVI file to PostScript converter. + +.IP ENV +A dictionary of environment variables +to use when invoking commands. When +$ENV is used in a command all list +values will be joined using the path separator and any other non-string +values will simply be coerced to a string. +Note that, by default, +.B scons +does +.I not +propagate the environment in force when you +execute +.B scons +to the commands used to build target files. +This is so that builds will be guaranteed +repeatable regardless of the environment +variables set at the time +.B scons +is invoked. + +If you want to propagate your +environment variables +to the commands executed +to build target files, +you must do so explicitly: + +.ES +import os +env = Environment(ENV = os.environ) +.EE +.IP +Note that you can choose only to propagate +certain environment variables. +A common example is +the system +.B PATH +environment variable, +so that +.B scons +uses the same utilities +as the invoking shell (or other process): + +.ES +import os +env = Environment(ENV = {'PATH' : os.environ['PATH']}) +.EE + +.IP ESCAPE +A function that will be called to escape shell special characters in +command lines. The function should take one argument: the command line +string to escape; and should return the escaped command line. + +.IP F77 +The Fortran 77 compiler. +You should normally set the $FORTRAN variable, +which specifies the default Fortran compiler +for all Fortran versions. +You only need to set $F77 if you need to use a specific compiler +or compiler version for Fortran 77 files. + +.IP F77COM +The command line used to compile a Fortran 77 source file to an object file. +You only need to set $F77COM if you need to use a specific +command line for Fortran 77 files. +You should normally set the $FORTRANCOM variable, +which specifies the default command line +for all Fortran versions. + +.IP F77COMSTR +The string displayed when a Fortran 77 source file +is compiled to an object file. +If this is not set, then $F77COM or $FORTRANCOM +(the command line) is displayed. + +.IP F77FILESUFFIXES +The list of file extensions for which the F77 dialect will be used. By +default, this is ['.f77'] + +.IP F77FLAGS +General user-specified options that are passed to the Fortran 77 compiler. +Note that this variable does +.I not +contain +.B \-I +(or similar) include search path options +that scons generates automatically from $F77PATH. +See +$_F77INCFLAGS +below, +for the variable that expands to those options. +You only need to set $F77FLAGS if you need to define specific +user options for Fortran 77 files. +You should normally set the $FORTRANFLAGS variable, +which specifies the user-specified options +passed to the default Fortran compiler +for all Fortran versions. + +.IP _F77INCFLAGS +An automatically-generated construction variable +containing the Fortran 77 compiler command-line options +for specifying directories to be searched for include files. +The value of $_F77INCFLAGS is created +by appending $INCPREFIX and $INCSUFFIX +to the beginning and end +of each directory in $F77PATH. + +.IP F77PATH +The list of directories that the Fortran 77 compiler will search for include +directories. The implicit dependency scanner will search these +directories for include files. Don't explicitly put include directory +arguments in $F77FLAGS because the result will be non-portable +and the directories will not be searched by the dependency scanner. Note: +directory names in $F77PATH will be looked-up relative to the SConscript +directory when they are used in a command. To force +.B scons +to look-up a directory relative to the root of the source tree use #: +You only need to set $F77PATH if you need to define a specific +include path for Fortran 77 files. +You should normally set the $FORTRANPATH variable, +which specifies the include path +for the default Fortran compiler +for all Fortran versions. + +.ES +env = Environment(F77PATH='#/include') +.EE +.IP +The directory look-up can also be forced using the +.BR Dir () +function: + +.ES +include = Dir('include') +env = Environment(F77PATH=include) +.EE +.IP +The directory list will be added to command lines +through the automatically-generated +$_F77INCFLAGS +construction variable, +which is constructed by +appending the values of the +$INCPREFIX and $INCSUFFIX +construction variables +to the beginning and end +of each directory in $F77PATH. +Any command lines you define that need +the F77PATH directory list should +include $_F77INCFLAGS: + +.ES +env = Environment(F77COM="my_compiler $_F77INCFLAGS -c -o $TARGET $SOURCE") +.EE + +.IP F77PPCOM +The command line used to compile a Fortran 77 source file to an object file +after first running the file through the C preprocessor. +Any options specified in the $F77FLAGS and $CPPFLAGS construction variables +are included on this command line. +You only need to set $F77PPCOM if you need to use a specific +C-preprocessor command line for Fortran 77 files. +You should normally set the $FORTRANPPCOM variable, +which specifies the default C-preprocessor command line +for all Fortran versions. + +.IP F77PPCOMSTR +The string displayed when a Fortran 77 source file +is compiled to an object file +after first running the file through the C preprocessor. +If this is not set, then $F77PPCOM or $FORTRANPPCOM +(the command line) is displayed. + +.IP F77PPFILESUFFIXES +The list of file extensions for which the compilation + preprocessor pass for +F77 dialect will be used. By default, this is empty + +.IP F90 +The Fortran 90 compiler. +You should normally set the $FORTRAN variable, +which specifies the default Fortran compiler +for all Fortran versions. +You only need to set $F90 if you need to use a specific compiler +or compiler version for Fortran 90 files. + +.IP F90COM +The command line used to compile a Fortran 90 source file to an object file. +You only need to set $F90COM if you need to use a specific +command line for Fortran 90 files. +You should normally set the $FORTRANCOM variable, +which specifies the default command line +for all Fortran versions. + +.IP F90COMSTR +The string displayed when a Fortran 90 source file +is compiled to an object file. +If this is not set, then $F90COM or $FORTRANCOM +(the command line) is displayed. + +.IP F90FILESUFFIXES +The list of file extensions for which the F90 dialect will be used. By +default, this is ['.f90'] + +.IP F90FLAGS +General user-specified options that are passed to the Fortran 90 compiler. +Note that this variable does +.I not +contain +.B \-I +(or similar) include search path options +that scons generates automatically from $F90PATH. +See +$_F90INCFLAGS +below, +for the variable that expands to those options. +You only need to set $F90FLAGS if you need to define specific +user options for Fortran 90 files. +You should normally set the $FORTRANFLAGS variable, +which specifies the user-specified options +passed to the default Fortran compiler +for all Fortran versions. + +.IP _F90INCFLAGS +An automatically-generated construction variable +containing the Fortran 90 compiler command-line options +for specifying directories to be searched for include files. +The value of $_F90INCFLAGS is created +by appending $INCPREFIX and $INCSUFFIX +to the beginning and end +of each directory in $F90PATH. + +.IP F90PATH +The list of directories that the Fortran 90 compiler will search for include +directories. The implicit dependency scanner will search these +directories for include files. Don't explicitly put include directory +arguments in $F90FLAGS because the result will be non-portable +and the directories will not be searched by the dependency scanner. Note: +directory names in $F90PATH will be looked-up relative to the SConscript +directory when they are used in a command. To force +.B scons +to look-up a directory relative to the root of the source tree use #: +You only need to set $F90PATH if you need to define a specific +include path for Fortran 90 files. +You should normally set the $FORTRANPATH variable, +which specifies the include path +for the default Fortran compiler +for all Fortran versions. + +.ES +env = Environment(F90PATH='#/include') +.EE +.IP +The directory look-up can also be forced using the +.BR Dir () +function: + +.ES +include = Dir('include') +env = Environment(F90PATH=include) +.EE +.IP +The directory list will be added to command lines +through the automatically-generated +$_F90INCFLAGS +construction variable, +which is constructed by +appending the values of the +$INCPREFIX and $INCSUFFIX +construction variables +to the beginning and end +of each directory in $F90PATH. +Any command lines you define that need +the F90PATH directory list should +include $_F90INCFLAGS: + +.ES +env = Environment(F90COM="my_compiler $_F90INCFLAGS -c -o $TARGET $SOURCE") +.EE + +.IP F90PPCOM +The command line used to compile a Fortran 90 source file to an object file +after first running the file through the C preprocessor. +Any options specified in the $F90FLAGS and $CPPFLAGS construction variables +are included on this command line. +You only need to set $F90PPCOM if you need to use a specific +C-preprocessor command line for Fortran 90 files. +You should normally set the $FORTRANPPCOM variable, +which specifies the default C-preprocessor command line +for all Fortran versions. + +.IP F90PPCOMSTR +The string displayed when a Fortran 90 source file +is compiled after first running the file through the C preprocessor. +If this is not set, then $F90PPCOM or $FORTRANPPCOM +(the command line) is displayed. + +.IP F90PPFILESUFFIXES +The list of file extensions for which the compilation + preprocessor pass for +F90 dialect will be used. By default, this is empty + +.IP F95 +The Fortran 95 compiler. +You should normally set the $FORTRAN variable, +which specifies the default Fortran compiler +for all Fortran versions. +You only need to set $F95 if you need to use a specific compiler +or compiler version for Fortran 95 files. + +.IP F95COM +The command line used to compile a Fortran 95 source file to an object file. +You only need to set $F95COM if you need to use a specific +command line for Fortran 95 files. +You should normally set the $FORTRANCOM variable, +which specifies the default command line +for all Fortran versions. + +.IP F95COMSTR +The string displayed when a Fortran 95 source file +is compiled to an object file. +If this is not set, then $F95COM or $FORTRANCOM +(the command line) is displayed. + +.IP F95FILESUFFIXES +The list of file extensions for which the F95 dialect will be used. By +default, this is ['.f95'] + +.IP F95FLAGS +General user-specified options that are passed to the Fortran 95 compiler. +Note that this variable does +.I not +contain +.B \-I +(or similar) include search path options +that scons generates automatically from $F95PATH. +See +$_F95INCFLAGS +below, +for the variable that expands to those options. +You only need to set $F95FLAGS if you need to define specific +user options for Fortran 95 files. +You should normally set the $FORTRANFLAGS variable, +which specifies the user-specified options +passed to the default Fortran compiler +for all Fortran versions. + +.IP _F95INCFLAGS +An automatically-generated construction variable +containing the Fortran 95 compiler command-line options +for specifying directories to be searched for include files. +The value of $_F95INCFLAGS is created +by appending $INCPREFIX and $INCSUFFIX +to the beginning and end +of each directory in $F95PATH. + +.IP F95PATH +The list of directories that the Fortran 95 compiler will search for include +directories. The implicit dependency scanner will search these +directories for include files. Don't explicitly put include directory +arguments in $F95FLAGS because the result will be non-portable +and the directories will not be searched by the dependency scanner. Note: +directory names in $F95PATH will be looked-up relative to the SConscript +directory when they are used in a command. To force +.B scons +to look-up a directory relative to the root of the source tree use #: +You only need to set $F95PATH if you need to define a specific +include path for Fortran 95 files. +You should normally set the $FORTRANPATH variable, +which specifies the include path +for the default Fortran compiler +for all Fortran versions. + +.ES +env = Environment(F95PATH='#/include') +.EE +.IP +The directory look-up can also be forced using the +.BR Dir () +function: + +.ES +include = Dir('include') +env = Environment(F95PATH=include) +.EE +.IP +The directory list will be added to command lines +through the automatically-generated +$_F95INCFLAGS +construction variable, +which is constructed by +appending the values of the +$INCPREFIX and $INCSUFFIX +construction variables +to the beginning and end +of each directory in $F95PATH. +Any command lines you define that need +the F95PATH directory list should +include $_F95INCFLAGS: + +.ES +env = Environment(F95COM="my_compiler $_F95INCFLAGS -c -o $TARGET $SOURCE") +.EE + +.IP F95PPCOM +The command line used to compile a Fortran 95 source file to an object file +after first running the file through the C preprocessor. +Any options specified in the $F95FLAGS and $CPPFLAGS construction variables +are included on this command line. +You only need to set $F95PPCOM if you need to use a specific +C-preprocessor command line for Fortran 95 files. +You should normally set the $FORTRANPPCOM variable, +which specifies the default C-preprocessor command line +for all Fortran versions. + +.IP F95PPCOMSTR +The string displayed when a Fortran 95 source file +is compiled to an object file +after first running the file through the C preprocessor. +If this is not set, then $F95PPCOM or $FORTRANPPCOM +(the command line) is displayed. + +.IP F95PPFILESUFFIXES +The list of file extensions for which the compilation + preprocessor pass for +F95 dialect will be used. By default, this is empty + +.IP File +A function that converts a string into a File instance relative to the +target being built. + +.IP FORTRAN +The default Fortran compiler +for all versions of Fortran. + +.IP FORTRANCOM +The command line used to compile a Fortran source file to an object file. +By default, any options specified +in the $FORTRANFLAGS, +$CPPFLAGS, +$_CPPDEFFLAGS, +$_FORTRANMODFLAG, and +$_FORTRANINCFLAGS construction variables +are included on this command line. + +.IP FORTRANCOMSTR +The string displayed when a Fortran source file +is compiled to an object file. +If this is not set, then $FORTRANCOM +(the command line) is displayed. + +.IP FORTRANFILESUFFIXES +The list of file extensions for which the FORTRAN dialect will be used. By +default, this is ['.f', '.for', '.ftn'] + +.IP FORTRANFLAGS +General user-specified options that are passed to the Fortran compiler. +Note that this variable does +.I not +contain +.B \-I +(or similar) include or module search path options +that scons generates automatically from $FORTRANPATH. +See +$_FORTRANINCFLAGS and $_FORTRANMODFLAG, +below, +for the variables that expand those options. + +.IP _FORTRANINCFLAGS +An automatically-generated construction variable +containing the Fortran compiler command-line options +for specifying directories to be searched for include +files and module files. +The value of $_FORTRANINCFLAGS is created +by prepending/appending $INCPREFIX and $INCSUFFIX +to the beginning and end +of each directory in $FORTRANPATH. + +.IP FORTRANMODDIR +Directory location where the Fortran compiler should place +any module files it generates. This variable is empty, by default. Some +Fortran compilers will internally append this directory in the search path +for module files, as well. + +.IP FORTRANMODDIRPREFIX +The prefix used to specify a module directory on the Fortran compiler command +line. +This will be appended to the beginning of the directory +in the $FORTRANMODDIR construction variables +when the $_FORTRANMODFLAG variables is automatically generated. + +.IP FORTRANMODDIRSUFFIX +The suffix used to specify a module directory on the Fortran compiler command +line. +This will be appended to the beginning of the directory +in the $FORTRANMODDIR construction variables +when the $_FORTRANMODFLAG variables is automatically generated. + +.IP _FORTRANMODFLAG +An automatically-generated construction variable +containing the Fortran compiler command-line option +for specifying the directory location where the Fortran +compiler should place any module files that happen to get +generated during compilation. +The value of $_FORTRANMODFLAG is created +by prepending/appending $FORTRANMODDIRPREFIX and +$FORTRANMODDIRSUFFIX +to the beginning and end of the directory in $FORTRANMODDIR. + +.IP FORTRANMODPREFIX +The module file prefix used by the Fortran compiler. SCons assumes that +the Fortran compiler follows the quasi-standard naming convention for +module files of +.BR module_name.mod . +As a result, this variable is left empty, by default. For situations in +which the compiler does not necessarily follow the normal convention, +the user may use this variable. Its value will be appended to every +module file name as scons attempts to resolve dependencies. + +.IP FORTRANMODSUFFIX +The module file suffix used by the Fortran compiler. SCons assumes that +the Fortran compiler follows the quasi-standard naming convention for +module files of +.BR module_name.mod . +As a result, this variable is set to ".mod", by default. For situations +in which the compiler does not necessarily follow the normal convention, +the user may use this variable. Its value will be appended to every +module file name as scons attempts to resolve dependencies. + +.IP FORTRANPATH +The list of directories that the Fortran compiler will search for +include files and (for some compilers) module files. The Fortran implicit +dependency scanner will search these directories for include files (but +not module files since they are autogenerated and, as such, may not +actually exist at the time the scan takes place). Don't explicitly put +include directory arguments in FORTRANFLAGS because the result will be +non-portable and the directories will not be searched by the dependency +scanner. Note: directory names in FORTRANPATH will be looked-up relative +to the SConscript directory when they are used in a command. To force +.B scons +to look-up a directory relative to the root of the source tree use #: + +.ES +env = Environment(FORTRANPATH='#/include') +.EE +.IP +The directory look-up can also be forced using the +.BR Dir () +function: + +.ES +include = Dir('include') +env = Environment(FORTRANPATH=include) +.EE +.IP +The directory list will be added to command lines +through the automatically-generated +$_FORTRANINCFLAGS +construction variable, +which is constructed by +appending the values of the +$INCPREFIX and $INCSUFFIX +construction variables +to the beginning and end +of each directory in $FORTRANPATH. +Any command lines you define that need +the FORTRANPATH directory list should +include $_FORTRANINCFLAGS: + +.ES +env = Environment(FORTRANCOM="my_compiler $_FORTRANINCFLAGS -c -o $TARGET $SOURCE") +.EE + +.IP FORTRANPPCOM +The command line used to compile a Fortran source file to an object file +after first running the file through the C preprocessor. +By default, any options specified in the $FORTRANFLAGS, +$CPPFLAGS, +$_CPPDEFFLAGS, +$_FORTRANMODFLAG, and +$_FORTRANINCFLAGS +construction variables are included on this command line. + +.IP FORTRANPPCOMSTR +The string displayed when a Fortran source file +is compiled to an object file +after first running the file throught the C preprocessor. +If this is not set, then $FORTRANPPCOM +(the command line) is displayed. + +.IP FORTRANPPFILESUFFIXES +The list of file extensions for which the compilation + preprocessor pass for +FORTRAN dialect will be used. By default, this is ['.fpp', '.FPP'] + +.IP FORTRANSUFFIXES +The list of suffixes of files that will be scanned +for Fortran implicit dependencies +(INCLUDE lines and USE statements). +The default list is: + +.ES +[".f", ".F", ".for", ".FOR", ".ftn", ".FTN", ".fpp", ".FPP", +".f77", ".F77", ".f90", ".F90", ".f95", ".F95"] +.EE + +.IP FRAMEWORKPATH +On Mac OS X with gcc, +a list containing the paths to search for frameworks. +Used by the compiler to find framework-style includes like +#include <Fmwk/Header.h>. +Used by the linker to find user-specified frameworks when linking (see +$FRAMEWORKS). +For example: + +.ES + env.AppendUnique(FRAMEWORKPATH='#myframeworkdir') +.EE +.IP +will add + +.ES + ... -Fmyframeworkdir +.EE +.IP +to the compiler and linker command lines. + +.IP _FRAMEWORKPATH +On Mac OS X with gcc, an automatically-generated construction variable +containing the linker command-line options corresponding to +$FRAMEWORKPATH. + +.IP FRAMEWORKPATHPREFIX +On Mac OS X with gcc, the prefix to be used for the FRAMEWORKPATH entries. +(see $FRAMEWORKPATH). +The default value is +.BR \-F . + +.IP FRAMEWORKPREFIX +On Mac OS X with gcc, +the prefix to be used for linking in frameworks +(see $FRAMEWORKS). +The default value is +.BR \-framework . + +.IP _FRAMEWORKS +On Mac OS X with gcc, +an automatically-generated construction variable +containing the linker command-line options +for linking with FRAMEWORKS. + +.IP FRAMEWORKS +On Mac OS X with gcc, a list of the framework names to be linked into a +program or shared library or bundle. +The default value is the empty list. +For example: + +.ES + env.AppendUnique(FRAMEWORKS=Split('System Cocoa SystemConfiguration')) +.EE +.IP + +.IP FRAMEWORKSFLAGS +On Mac OS X with gcc, +general user-supplied frameworks options to be added at +the end of a command +line building a loadable module. +(This has been largely superceded by +the $FRAMEWORKPATH, $FRAMEWORKPATHPREFIX, +$FRAMEWORKPREFIX and $FRAMEWORKS variables +described above.) + +.IP GS +The Ghostscript program used to convert PostScript to PDF files. + +.IP GSCOM +The Ghostscript command line used to convert PostScript to PDF files. + +.IP GSCOMSTR +The string displayed when +Ghostscript is used to convert +a PostScript file to a PDF file. +If this is not set, then $GSCOM (the command line) is displayed. + +.IP GSFLAGS +General options passed to the Ghostscript program +when converting PostScript to PDF files. + +.IP HOST_ARCH +Sets the host architecture for Visual Studio compiler. If not set, +default to the detected host architecture: note that this may depend +on the python you are using. + +Valid values are the same as for $TARGET_ARCH. + +This is currently only used on Windows, but in the future it will be +used on other OSes as well. + +.IP HOST_OS + The name of the host operating system used to create the Environment. + If a platform is specified when creating the Environment, then + that Platform's logic will handle setting this value. + This value is immutable, and should not be changed by the user after + the Environment is initialized. + Currently only set for Win32. + +.IP IDLSUFFIXES +The list of suffixes of files that will be scanned +for IDL implicit dependencies +(#include or import lines). +The default list is: + +.ES +[".idl", ".IDL"] +.EE + +.IP IMPLICIT_COMMAND_DEPENDENCIES +Controls whether or not SCons will +add implicit dependencies for the commands +executed to build targets. + +By default, SCons will add +to each target +an implicit dependency on the command +represented by the first argument on any +command line it executes. +The specific file for the dependency is +found by searching the +.I PATH +variable in the +.I ENV +environment used to execute the command. + +If the construction variable +$IMPLICIT_COMMAND_DEPENDENCIES +is set to a false value +(\fBNone\fP, +.BR False , +.BR 0 , +etc.), +then the implicit dependency will +not be added to the targets +built with that construction environment. + +.ES +env = Environment(IMPLICIT_COMMAND_DEPENDENCIES = 0) +.EE + +.IP INCPREFIX +The prefix used to specify an include directory on the C compiler command +line. +This will be appended to the beginning of each directory +in the $CPPPATH and $FORTRANPATH construction variables +when the $_CPPINCFLAGS and $_FORTRANINCFLAGS +variables are automatically generated. + +.IP INCSUFFIX +The suffix used to specify an include directory on the C compiler command +line. +This will be appended to the end of each directory +in the $CPPPATH and $FORTRANPATH construction variables +when the $_CPPINCFLAGS and $_FORTRANINCFLAGS +variables are automatically generated. + +.IP INSTALL +A function to be called to install a file into a +destination file name. +The default function copies the file into the destination +(and sets the destination file's mode and permission bits +to match the source file's). +The function takes the following arguments: + +.ES +def install(dest, source, env): +.EE +.IP +.I dest +is the path name of the destination file. +.I source +is the path name of the source file. +.I env +is the construction environment +(a dictionary of construction values) +in force for this file installation. + +.IP INSTALLSTR +The string displayed when a file is +installed into a destination file name. +The default is: +.ES +Install file: "$SOURCE" as "$TARGET" +.EE + +.IP INTEL_C_COMPILER_VERSION +Set by the "intelc" Tool +to the major version number of the Intel C compiler +selected for use. + +.IP JAR +The Java archive tool. + +.IP JARCHDIR +The directory to which the Java archive tool should change +(using the +.B \-C +option). + +.IP JARCOM +The command line used to call the Java archive tool. + +.IP JARCOMSTR +The string displayed when the Java archive tool +is called +If this is not set, then $JARCOM (the command line) is displayed. + +.ES +env = Environment(JARCOMSTR = "JARchiving $SOURCES into $TARGET") +.EE + +.IP JARFLAGS +General options passed to the Java archive tool. +By default this is set to +.B cf +to create the necessary +.B jar +file. + +.IP JARSUFFIX +The suffix for Java archives: +.B .jar +by default. + +.IP JAVABOOTCLASSPATH +Specifies the list of directories that +will be added to the +&javac; command line +via the \fB\-bootclasspath\fP option. +The individual directory names will be +separated by the operating system's path separate character +(\fB:\fP on UNIX/Linux/POSIX, +\fB;\fP on Windows). + +.IP JAVAC +The Java compiler. + +.IP JAVACCOM +The command line used to compile a directory tree containing +Java source files to +corresponding Java class files. +Any options specified in the $JAVACFLAGS construction variable +are included on this command line. + +.IP JAVACCOMSTR +The string displayed when compiling +a directory tree of Java source files to +corresponding Java class files. +If this is not set, then $JAVACCOM (the command line) is displayed. + +.ES +env = Environment(JAVACCOMSTR = "Compiling class files $TARGETS from $SOURCES") +.EE + +.IP JAVACFLAGS +General options that are passed to the Java compiler. + +.IP JAVACLASSDIR +The directory in which Java class files may be found. +This is stripped from the beginning of any Java .class +file names supplied to the +.B JavaH +builder. + +.IP JAVACLASSPATH +Specifies the list of directories that +will be searched for Java +\fB.class\fP file. +The directories in this list will be added to the +&javac; and &javah; command lines +via the \fB\-classpath\fP option. +The individual directory names will be +separated by the operating system's path separate character +(\fB:\fP on UNIX/Linux/POSIX, +\fB;\fP on Windows). + +Note that this currently just adds the specified +directory via the \fB\-classpath\fP option. +&SCons; does not currently search the +$JAVACLASSPATH directories for dependency +\fB.class\fP files. + +.IP JAVACLASSSUFFIX +The suffix for Java class files; +.B .class +by default. + +.IP JAVAH +The Java generator for C header and stub files. + +.IP JAVAHCOM +The command line used to generate C header and stub files +from Java classes. +Any options specified in the $JAVAHFLAGS construction variable +are included on this command line. + +.IP JAVAHCOMSTR +The string displayed when C header and stub files +are generated from Java classes. +If this is not set, then $JAVAHCOM (the command line) is displayed. + +.ES +env = Environment(JAVAHCOMSTR = "Generating header/stub file(s) $TARGETS from $SOURCES") +.EE + +.IP JAVAHFLAGS +General options passed to the C header and stub file generator +for Java classes. + +.IP JAVASOURCEPATH +Specifies the list of directories that +will be searched for input +\fB.java\fP file. +The directories in this list will be added to the +&javac; command line +via the \fB\-sourcepath\fP option. +The individual directory names will be +separated by the operating system's path separate character +(\fB:\fP on UNIX/Linux/POSIX, +\fB;\fP on Windows). + +Note that this currently just adds the specified +directory via the \fB\-sourcepath\fP option. +&SCons; does not currently search the +$JAVASOURCEPATH directories for dependency +\fB.java\fP files. + +.IP JAVASUFFIX +The suffix for Java files; +.B .java +by default. + +.IP JAVAVERSION +Specifies the Java version being used by the \fBJava\fP() builder. +This is \fInot\fP currently used to select one +version of the Java compiler vs. another. +Instead, you should set this to specify the version of Java +supported by your &javac; compiler. +The default is \fB1.4\fP. + +This is sometimes necessary because +Java 1.5 changed the file names that are created +for nested anonymous inner classes, +which can cause a mismatch with the files +that &SCons; expects will be generated by the &javac; compiler. +Setting $JAVAVERSION to \fB1.5\fP +(or \fB1.6\fP, as appropriate) +can make &SCons; realize that a Java 1.5 or 1.6 +build is actually up to date. + +.IP LATEX +The LaTeX structured formatter and typesetter. + +.IP LATEXCOM +The command line used to call the LaTeX structured formatter and typesetter. + +.IP LATEXCOMSTR +The string displayed when calling +the LaTeX structured formatter and typesetter. +If this is not set, then $LATEXCOM (the command line) is displayed. + +.ES +env = Environment(LATEXCOMSTR = "Building $TARGET from LaTeX input $SOURCES") +.EE + +.IP LATEXFLAGS +General options passed to the LaTeX structured formatter and typesetter. + +.IP LATEXRETRIES +The maximum number of times that LaTeX +will be re-run if the +.B .log +generated by the $LATEXCOM command +indicates that there are undefined references. +The default is to try to resolve undefined references +by re-running LaTeX up to three times. + +.IP LATEXSUFFIXES +The list of suffixes of files that will be scanned +for LaTeX implicit dependencies +(\fB\\include\fP or \fB\\import\fP files). +The default list is: + +.ES +[".tex", ".ltx", ".latex"] +.EE + +.IP LDMODULE +The linker for building loadable modules. +By default, this is the same as $SHLINK. + +.IP LDMODULECOM +The command line for building loadable modules. +On Mac OS X, this uses the $LDMODULE, +$LDMODULEFLAGS and +$FRAMEWORKSFLAGS variables. +On other systems, this is the same as $SHLINK. + +.IP LDMODULECOMSTR +The string displayed when building loadable modules. +If this is not set, then $LDMODULECOM (the command line) is displayed. + +.IP LDMODULEFLAGS +General user options passed to the linker for building loadable modules. + +.IP LDMODULEPREFIX +The prefix used for loadable module file names. +On Mac OS X, this is null; +on other systems, this is +the same as $SHLIBPREFIX. + +.IP LDMODULESUFFIX +The suffix used for loadable module file names. +On Mac OS X, this is null; +on other systems, this is +the same as $SHLIBSUFFIX. + +.IP LEX +The lexical analyzer generator. + +.IP LEXCOM +The command line used to call the lexical analyzer generator +to generate a source file. + +.IP LEXCOMSTR +The string displayed when generating a source file +using the lexical analyzer generator. +If this is not set, then $LEXCOM (the command line) is displayed. + +.ES +env = Environment(LEXCOMSTR = "Lex'ing $TARGET from $SOURCES") +.EE + +.IP LEXFLAGS +General options passed to the lexical analyzer generator. + +.IP _LIBDIRFLAGS +An automatically-generated construction variable +containing the linker command-line options +for specifying directories to be searched for library. +The value of $_LIBDIRFLAGS is created +by appending $LIBDIRPREFIX and $LIBDIRSUFFIX +to the beginning and end +of each directory in $LIBPATH. + +.IP LIBDIRPREFIX +The prefix used to specify a library directory on the linker command line. +This will be appended to the beginning of each directory +in the $LIBPATH construction variable +when the $_LIBDIRFLAGS variable is automatically generated. + +.IP LIBDIRSUFFIX +The suffix used to specify a library directory on the linker command line. +This will be appended to the end of each directory +in the $LIBPATH construction variable +when the $_LIBDIRFLAGS variable is automatically generated. + +.IP _LIBFLAGS +An automatically-generated construction variable +containing the linker command-line options +for specifying libraries to be linked with the resulting target. +The value of $_LIBFLAGS is created +by appending $LIBLINKPREFIX and $LIBLINKSUFFIX +to the beginning and end +of each filename in $LIBS. + +.IP LIBLINKPREFIX +The prefix used to specify a library to link on the linker command line. +This will be appended to the beginning of each library +in the $LIBS construction variable +when the $_LIBFLAGS variable is automatically generated. + +.IP LIBLINKSUFFIX +The suffix used to specify a library to link on the linker command line. +This will be appended to the end of each library +in the $LIBS construction variable +when the $_LIBFLAGS variable is automatically generated. + +.IP LIBPATH +The list of directories that will be searched for libraries. +The implicit dependency scanner will search these +directories for include files. Don't explicitly put include directory +arguments in $LINKFLAGS or $SHLINKFLAGS +because the result will be non-portable +and the directories will not be searched by the dependency scanner. Note: +directory names in LIBPATH will be looked-up relative to the SConscript +directory when they are used in a command. To force +.B scons +to look-up a directory relative to the root of the source tree use #: + +.ES +env = Environment(LIBPATH='#/libs') +.EE +.IP +The directory look-up can also be forced using the +.BR Dir () +function: + +.ES +libs = Dir('libs') +env = Environment(LIBPATH=libs) +.EE +.IP +The directory list will be added to command lines +through the automatically-generated +$_LIBDIRFLAGS +construction variable, +which is constructed by +appending the values of the +$LIBDIRPREFIX and $LIBDIRSUFFIX +construction variables +to the beginning and end +of each directory in $LIBPATH. +Any command lines you define that need +the LIBPATH directory list should +include $_LIBDIRFLAGS: + +.ES +env = Environment(LINKCOM="my_linker $_LIBDIRFLAGS $_LIBFLAGS -o $TARGET $SOURCE") +.EE + +.IP LIBPREFIX +The prefix used for (static) library file names. +A default value is set for each platform +(posix, win32, os2, etc.), +but the value is overridden by individual tools +(ar, mslib, sgiar, sunar, tlib, etc.) +to reflect the names of the libraries they create. + +.IP LIBPREFIXES +A list of all legal prefixes for library file names. +When searching for library dependencies, +SCons will look for files with these prefixes, +the base library name, +and suffixes in the $LIBSUFFIXES list. + +.IP LIBS +A list of one or more libraries +that will be linked with +any executable programs +created by this environment. + +The library list will be added to command lines +through the automatically-generated +$_LIBFLAGS +construction variable, +which is constructed by +appending the values of the +$LIBLINKPREFIX and $LIBLINKSUFFIX +construction variables +to the beginning and end +of each filename in $LIBS. +Any command lines you define that need +the LIBS library list should +include $_LIBFLAGS: + +.ES +env = Environment(LINKCOM="my_linker $_LIBDIRFLAGS $_LIBFLAGS -o $TARGET $SOURCE") +.EE +.IP +If you add a +File +object to the +$LIBS +list, the name of that file will be added to +$_LIBFLAGS, +and thus the link line, as is, without +$LIBLINKPREFIX +or +$LIBLINKSUFFIX. +For example: + +.ES +env.Append(LIBS=File('/tmp/mylib.so')) +.EE +.IP +In all cases, scons will add dependencies from the executable program to +all the libraries in this list. + +.IP LIBSUFFIX +The suffix used for (static) library file names. +A default value is set for each platform +(posix, win32, os2, etc.), +but the value is overridden by individual tools +(ar, mslib, sgiar, sunar, tlib, etc.) +to reflect the names of the libraries they create. + +.IP LIBSUFFIXES +A list of all legal suffixes for library file names. +When searching for library dependencies, +SCons will look for files with prefixes, in the $LIBPREFIXES list, +the base library name, +and these suffixes. + +.IP LICENSE +The abbreviated name of the license under which +this project is released (gpl, lpgl, bsd etc.). +See http://www.opensource.org/licenses/alphabetical +for a list of license names. + +.IP LINESEPARATOR +The separator used by the \fBSubstfile\fP() and \fBTextfile\fP() builders. +This value is used between sources when constructing the target. +It defaults to the current system line separator. + +.IP LINK +The linker. + +.IP LINKCOM +The command line used to link object files into an executable. + +.IP LINKCOMSTR +The string displayed when object files +are linked into an executable. +If this is not set, then $LINKCOM (the command line) is displayed. + +.ES +env = Environment(LINKCOMSTR = "Linking $TARGET") +.EE + +.IP LINKFLAGS +General user options passed to the linker. +Note that this variable should +.I not +contain +.B \-l +(or similar) options for linking with the libraries listed in $LIBS, +nor +.B \-L +(or similar) library search path options +that scons generates automatically from $LIBPATH. +See +$_LIBFLAGS +above, +for the variable that expands to library-link options, +and +$_LIBDIRFLAGS +above, +for the variable that expands to library search path options. + +.IP M4 +The M4 macro preprocessor. + +.IP M4COM +The command line used to pass files through the M4 macro preprocessor. + +.IP M4COMSTR +The string displayed when +a file is passed through the M4 macro preprocessor. +If this is not set, then $M4COM (the command line) is displayed. + +.IP M4FLAGS +General options passed to the M4 macro preprocessor. + +.IP MAKEINDEX +The makeindex generator for the TeX formatter and typesetter and the +LaTeX structured formatter and typesetter. + +.IP MAKEINDEXCOM +The command line used to call the makeindex generator for the +TeX formatter and typesetter and the LaTeX structured formatter and +typesetter. + +.IP MAKEINDEXCOMSTR +The string displayed when calling the makeindex generator for the +TeX formatter and typesetter +and the LaTeX structured formatter and typesetter. +If this is not set, then $MAKEINDEXCOM (the command line) is displayed. + +.IP MAKEINDEXFLAGS +General options passed to the makeindex generator for the TeX formatter +and typesetter and the LaTeX structured formatter and typesetter. + +.IP MAXLINELENGTH +The maximum number of characters allowed on an external command line. +On Win32 systems, +link lines longer than this many characters +are linked via a temporary file name. + +.IP MIDL +The Microsoft IDL compiler. + +.IP MIDLCOM +The command line used to pass files to the Microsoft IDL compiler. + +.IP MIDLCOMSTR +The string displayed when +the Microsoft IDL copmiler is called. +If this is not set, then $MIDLCOM (the command line) is displayed. + +.IP MIDLFLAGS +General options passed to the Microsoft IDL compiler. + +.IP MSSDK_DIR +The directory containing the Microsoft SDK +(either Platform SDK or Windows SDK) +to be used for compilation. + +.IP MSSDK_VERSION +The version string of the Microsoft SDK +(either Platform SDK or Windows SDK) +to be used for compilation. +Supported versions include +.BR 6.1 , +.BR 6.0A , +.BR 6.0 , +.B 2003R2 +and +.BR 2003R1 . + +.IP MSVC_BATCH +When set to any true value, +specifies that &SCons; should batch +compilation of object files +when calling the Microsoft Visual C/C++ compiler. +All compilations of source files from the same source directory +that generate target files in a same output directory +and were configured in &SCons; using the same construction environment +will be built in a single call to the compiler. +Only source files that have changed since their +object files were built will be passed to each compiler invocation +(via the $CHANGED_SOURCES construction variable). +Any compilations where the object (target) file base name +(minus the \fB.obj\fP) +does not match the source file base name +will be compiled separately. + +.IP MSVC_VERSION +Sets the preferred version of Microsoft Visual C/C++ to use. + +If $MSVC_VERSION is not set, +&SCons; will (by default) select the latest version +of Visual C/C++ installed on your system. +If the specified version isn't installed, +tool initialization will fail. + +.IP MSVS +When the Microsoft Visual Studio tools are initialized, they set up +this dictionary with the following keys: + +.BR VERSION : +the version of MSVS being used (can be set via +$MSVS_VERSION) + +.BR VERSIONS : +the available versions of MSVS installed + +.BR VCINSTALLDIR : +installed directory of Visual C++ + +.BR VSINSTALLDIR : +installed directory of Visual Studio + +.BR FRAMEWORKDIR : +installed directory of the .NET framework + +.BR FRAMEWORKVERSIONS : +list of installed versions of the .NET framework, sorted latest to oldest. + +.BR FRAMEWORKVERSION : +latest installed version of the .NET framework + +.BR FRAMEWORKSDKDIR : +installed location of the .NET SDK. + +.BR PLATFORMSDKDIR : +installed location of the Platform SDK. + +.BR PLATFORMSDK_MODULES : +dictionary of installed Platform SDK modules, +where the dictionary keys are keywords for the various modules, and +the values are 2-tuples where the first is the release date, and the +second is the version number. + +If a value isn't set, it wasn't available in the registry. + +.IP MSVS_ARCH +Sets the architecture for which the generated project(s) should build. + +The default value is \fBx86\fP. +\fBamd64\fP is also supported +by &SCons; for some Visual Studio versions. +Trying to set $MSVS_ARCH to an architecture that's not +supported for a given Visual Studio version +will generate an error. + +.IP MSVS_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. + +For VS6, the mininimal set is: +.ES + 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' +.EE +For VS7, it is: +.ES + 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_PROJECT_BASE_PATH +The string +placed in a generated Microsoft Visual Studio solution file +as the value of the +.B SccProjectFilePathRelativizedFromConnection0 +and +.B SccProjectFilePathRelativizedFromConnection1 +attributes of the +.B GlobalSection(SourceCodeControl) +section. +There is no default value. + +.IP MSVS_PROJECT_GUID +The string +placed in a generated Microsoft Visual Studio project file +as the value of the +.B ProjectGUID +attribute. +The string is also placed in the +.B SolutionUniqueID +attribute of the +.B GlobalSection(SourceCodeControl) +section of the Microsoft Visual Studio solution file. +There is no default value. + +.IP MSVS_SCC_AUX_PATH +The path name +placed in a generated Microsoft Visual Studio project file +as the value of the +.B SccAuxPath +attribute +if the +.B MSVS_SCC_PROVIDER +construction variable is also set. +There is no default value. + +.IP MSVS_SCC_LOCAL_PATH +The path name +placed in a generated Microsoft Visual Studio project file +as the value of the +.B SccLocalPath +attribute +if the +.B MSVS_SCC_PROVIDER +construction variable is also set. +The path name is also placed in the +.B SccLocalPath0 +and +.B SccLocalPath1 +attributes of the +.B GlobalSection(SourceCodeControl) +section of the Microsoft Visual Studio solution file. +There is no default value. + +.IP MSVS_SCC_PROJECT_NAME +The project name +placed in a generated Microsoft Visual Studio project file +as the value of the +.B SccProjectName +attribute. +There is no default value. + +.IP MSVS_SCC_PROVIDER +The string +placed in a generated Microsoft Visual Studio project file +as the value of the +.B SccProvider +attribute. +The string is also placed in the +.B SccProvider1 +attribute of the +.B GlobalSection(SourceCodeControl) +section of the Microsoft Visual Studio solution file. +There is no default value. + +.IP MSVS_USE_MFC_DIRS +Tells the MS Visual Studio tool(s) to use +the MFC directories in its default paths +for compiling and linking. +The $MSVS_USE_MFC_DIRS variable has no effect if the +.B INCLUDE +or +.B LIB +environment variables are set explictly. + +Under Visual Studio version 6, +setting +$MSVS_USE_MFC_DIRS +to a non-zero value +adds the +.B "ATL\\\\ATL" +and +.B "MFC\\\\MFC" +directories to +the default +.B INCLUDE +external environment variable, +and adds the +.B "MFC\\\\MFC" +directory to +the default +.B LIB +external environment variable. + +Under Visual Studio version 7, +setting +$MSVS_USE_MFC_DIRS +to a non-zero value +adds the +.B "atlmfc\\\\atlmfc" +directory to the default +.B INCLUDE +external environment variable, +and adds the +.B "atlmfc\\\\atlmfc" +directory to the default +.B LIB +external environment variable. + +Under Visual Studio version 8, +setting +$MSVS_USE_MFC_DIRS +to a non-zero value will, +by default, +add the +.B "atlmfc\\\\atlmfc" +directory to the default +.B INCLUDE +external environment variable, +and the +.B "atlmfc\\\\atlmfc" +directory to the default +.B LIB +external environment variable. +If, however, the +.B ['MSVS']['PLATFORMSDKDIR'] +variable is set, +then the +.B mfc +and the +.B atl +subdirectories of the +.B PLATFORMSDKDIR +are added to the default value of the +.B INCLUDE +external environment variable, +and the default value of the +.B LIB +external environment variable is left untouched. + +.IP MSVS_VERSION +Sets the preferred version of Microsoft Visual Studio to use. + +If $MSVS_VERSION is not set, +&SCons; will (by default) select the latest version +of Visual Studio installed on your system. +So, if you have version 6 and version 7 (MSVS .NET) installed, +it will prefer version 7. +You can override this by +specifying the +.B MSVS_VERSION +variable in the Environment initialization, setting it to the +appropriate version ('6.0' or '7.0', for example). +If the specified version isn't installed, +tool initialization will fail. + +This is obsolete: use $MSVC_VERSION instead. If $MSVS_VERSION is set and +$MSVC_VERSION is not, $MSVC_VERSION will be set automatically to $MSVS_VERSION. +If both are set to different values, scons will raise an error. + +.IP MSVSBUILDCOM +The build command line placed in +a generated Microsoft Visual Studio project file. +The default is to have Visual Studio invoke SCons with any specified +build targets. + +.IP MSVSCLEANCOM +The clean command line placed in +a generated Microsoft Visual Studio project file. +The default is to have Visual Studio invoke SCons with the -c option +to remove any specified targets. + +.IP MSVSENCODING +The encoding string placed in +a generated Microsoft Visual Studio project file. +The default is encoding +.BR Windows-1252 . + +.IP MSVSPROJECTCOM +The action used to generate Microsoft Visual Studio project files. + +.IP MSVSPROJECTSUFFIX +The suffix used for Microsoft Visual Studio project (DSP) files. +The default value is +.B .vcproj +when using Visual Studio version 7.x (.NET) +or later version, +and +.B .dsp +when using earlier versions of Visual Studio. + +.IP MSVSREBUILDCOM +The rebuild command line placed in +a generated Microsoft Visual Studio project file. +The default is to have Visual Studio invoke SCons with any specified +rebuild targets. + +.IP MSVSSCONS +The SCons used in generated Microsoft Visual Studio project files. +The default is the version of SCons being +used to generate the project file. + +.IP MSVSSCONSCOM +The default SCons command used in generated Microsoft Visual Studio +project files. + +.IP MSVSSCONSCRIPT +The sconscript file +(that is, +.B SConstruct +or +.B SConscript +file) +that will be invoked by Visual Studio +project files +(through the +$MSVSSCONSCOM +variable). +The default is the same sconscript file +that contains the call to +.BR MSVSProject () +to build the project file. + +.IP MSVSSCONSFLAGS +The SCons flags used in generated Microsoft Visual Studio +project files. + +.IP MSVSSOLUTIONCOM +The action used to generate Microsoft Visual Studio solution files. + +.IP MSVSSOLUTIONSUFFIX +The suffix used for Microsoft Visual Studio solution (DSW) files. +The default value is +.B .sln +when using Visual Studio version 7.x (.NET), +and +.B .dsw +when using earlier versions of Visual Studio. + +.IP MWCW_VERSION +The version number of the MetroWerks CodeWarrior C compiler +to be used. + +.IP MWCW_VERSIONS +A list of installed versions of the MetroWerks CodeWarrior C compiler +on this system. + +.IP NAME +Specfies the name of the project to package. + +.IP no_import_lib +When set to non-zero, +suppresses creation of a corresponding Windows static import lib by the +.B SharedLibrary +builder when used with +MinGW, Microsoft Visual Studio or Metrowerks. +This also suppresses creation +of an export (.exp) file +when using Microsoft Visual Studio. + +.IP OBJPREFIX +The prefix used for (static) object file names. + +.IP OBJSUFFIX +The suffix used for (static) object file names. + +.IP P4 +The Perforce executable. + +.IP P4COM +The command line used to +fetch source files from Perforce. + +.IP P4COMSTR +The string displayed when +fetching a source file from Perforce. +If this is not set, then $P4COM (the command line) is displayed. + +.IP P4FLAGS +General options that are passed to Perforce. + +.IP PACKAGEROOT +Specifies the directory where all files in resulting archive will be +placed if applicable. The default value is "$NAME-$VERSION". + +.IP PACKAGETYPE +Selects the package type to build. Currently these are available: + + * msi - Microsoft Installer + * rpm - Redhat Package Manger + * ipkg - Itsy Package Management System + * tarbz2 - compressed tar + * targz - compressed tar + * zip - zip file + * src_tarbz2 - compressed tar source + * src_targz - compressed tar source + * src_zip - zip file source + +This may be overridden with the "package_type" command line option. + +.IP PACKAGEVERSION +The version of the package (not the underlying project). +This is currently only used by the rpm packager +and should reflect changes in the packaging, +not the underlying project code itself. + +.IP PCH +The Microsoft Visual C++ precompiled header that will be used when compiling +object files. This variable is ignored by tools other than Microsoft Visual C++. +When this variable is +defined SCons will add options to the compiler command line to +cause it to use the precompiled header, and will also set up the +dependencies for the PCH file. +Example: + +.ES +env['PCH'] = 'StdAfx.pch' +.EE + +.IP PCHCOM +The command line used by the +.BR PCH () +builder to generated a precompiled header. + +.IP PCHCOMSTR +The string displayed when generating a precompiled header. +If this is not set, then $PCHCOM (the command line) is displayed. + +.IP PCHPDBFLAGS +A construction variable that, when expanded, +adds the \fB/yD\fP flag to the command line +only if the $PDB construction variable is set. + +.IP PCHSTOP +This variable specifies how much of a source file is precompiled. This +variable is ignored by tools other than Microsoft Visual C++, or when +the PCH variable is not being used. When this variable is define it +must be a string that is the name of the header that +is included at the end of the precompiled portion of the source files, or +the empty string if the "#pragma hrdstop" construct is being used: + +.ES +env['PCHSTOP'] = 'StdAfx.h' +.EE + +.IP PDB +The Microsoft Visual C++ PDB file that will store debugging information for +object files, shared libraries, and programs. This variable is ignored by +tools other than Microsoft Visual C++. +When this variable is +defined SCons will add options to the compiler and linker command line to +cause them to generate external debugging information, and will also set up the +dependencies for the PDB file. +Example: + +.ES +env['PDB'] = 'hello.pdb' +.EE +.IP +The Visual C++ compiler switch that SCons uses by default +to generate PDB information is \fB/Z7\fP. +This works correctly with parallel (\fB\-j\fP) builds +because it embeds the debug information in the intermediate object files, +as opposed to sharing a single PDB file between multiple object files. +This is also the only way to get debug information +embedded into a static library. +Using the \fB/Zi\fP instead may yield improved +link-time performance, +although parallel builds will no longer work. +You can generate PDB files with the \fB/Zi\fP +switch by overriding the default $CCPDBFLAGS variable; +see the entry for that variable for specific examples. + +.IP PDFCOM +A deprecated synonym for $DVIPDFCOM. + +.IP PDFLATEX +The &pdflatex; utility. + +.IP PDFLATEXCOM +The command line used to call the &pdflatex; utility. + +.IP PDFLATEXCOMSTR +The string displayed when calling the &pdflatex; utility. +If this is not set, then $PDFLATEXCOM (the command line) is displayed. + +.ES +env = Environment(PDFLATEX;COMSTR = "Building $TARGET from LaTeX input $SOURCES") +.EE + +.IP PDFLATEXFLAGS +General options passed to the &pdflatex; utility. + +.IP PDFPREFIX +The prefix used for PDF file names. + +.IP PDFSUFFIX +The suffix used for PDF file names. + +.IP PDFTEX +The &pdftex; utility. + +.IP PDFTEXCOM +The command line used to call the &pdftex; utility. + +.IP PDFTEXCOMSTR +The string displayed when calling the &pdftex; utility. +If this is not set, then $PDFTEXCOM (the command line) is displayed. + +.ES +env = Environment(PDFTEXCOMSTR = "Building $TARGET from TeX input $SOURCES") +.EE + +.IP PDFTEXFLAGS +General options passed to the &pdftex; utility. + +.IP PKGCHK +On Solaris systems, +the package-checking program that will +be used (along with $PKGINFO) +to look for installed versions of +the Sun PRO C++ compiler. +The default is +.BR /usr/sbin/pgkchk . + +.IP PKGINFO +On Solaris systems, +the package information program that will +be used (along with $PKGCHK) +to look for installed versions of +the Sun PRO C++ compiler. +The default is +.BR pkginfo . + +.IP PLATFORM +The name of the platform used to create the Environment. If no platform is +specified when the Environment is created, +.B scons +autodetects the platform. + +.ES +env = Environment(tools = []) +if env['PLATFORM'] == 'cygwin': + Tool('mingw')(env) +else: + Tool('msvc')(env) +.EE + +.IP PRINT_CMD_LINE_FUNC +A Python function used to print the command lines as they are executed +(assuming command printing is not disabled by the +.B \-q +or +.B \-s +options or their equivalents). +The function should take four arguments: +.IR s , +the command being executed (a string), +.IR target , +the target being built (file node, list, or string name(s)), +.IR source , +the source(s) used (file node, list, or string name(s)), and +.IR env , +the environment being used. + +The function must do the printing itself. The default implementation, +used if this variable is not set or is None, is: +.ES +def print_cmd_line(s, target, source, env): + sys.stdout.write(s + "\\n") +.EE +.IP +Here's an example of a more interesting function: + +.ES +def print_cmd_line(s, target, source, env): + sys.stdout.write("Building %s -> %s...\\n" % + (' and '.join([str(x) for x in source]), + ' and '.join([str(x) for x in target]))) +env=Environment(PRINT_CMD_LINE_FUNC=print_cmd_line) +env.Program('foo', 'foo.c') +.EE +.IP +This just prints "Building \fItargetname\fP from \fIsourcename\fP..." instead +of the actual commands. +Such a function could also log the actual commands to a log file, +for example. + +.IP PROGPREFIX +The prefix used for executable file names. + +.IP PROGSUFFIX +The suffix used for executable file names. + +.IP PSCOM +The command line used to convert TeX DVI files into a PostScript file. + +.IP PSCOMSTR +The string displayed when a TeX DVI file +is converted into a PostScript file. +If this is not set, then $PSCOM (the command line) is displayed. + +.IP PSPREFIX +The prefix used for PostScript file names. + +.IP PSSUFFIX +The prefix used for PostScript file names. + +.IP QT_AUTOSCAN +Turn off scanning for mocable files. Use the Moc Builder to 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_LIB +Default value is 'qt'. You may want to set this to 'qt-mt'. Note: If you set +this variable to None, the tool won't change the $LIBS variable. + +.IP QT_LIBPATH +The path where the qt libraries are installed. +The default value is '$QTDIR/lib'. +Note: If you set this variable to None, +the tool won't change the $LIBPATH +construction variable. + +.IP QT_MOC +Default value is '$QT_BINPATH/moc'. + +.IP QT_MOCCXXPREFIX +Default value is ''. Prefix for moc output files, when source is a cxx file. + +.IP QT_MOCCXXSUFFIX +Default value is '.moc'. Suffix for moc output files, when source is a cxx +file. + +.IP QT_MOCFROMCXXCOM +Command to generate a moc file from a cpp file. + +.IP QT_MOCFROMCXXCOMSTR +The string displayed when generating a moc file from a cpp file. +If this is not set, then $QT_MOCFROMCXXCOM (the command line) is displayed. + +.IP QT_MOCFROMCXXFLAGS +Default value is '-i'. These flags are passed to moc, when moccing a +C++ file. + +.IP QT_MOCFROMHCOM +Command to generate a moc file from a header. + +.IP QT_MOCFROMHCOMSTR +The string displayed when generating a moc file from a cpp file. +If this is not set, then $QT_MOCFROMHCOM (the command line) is displayed. + +.IP QT_MOCFROMHFLAGS +Default value is ''. These flags are passed to moc, when moccing a header +file. + +.IP QT_MOCHPREFIX +Default value is 'moc_'. Prefix for moc output files, when source is a header. + +.IP QT_MOCHSUFFIX +Default value is '$CXXFILESUFFIX'. Suffix for moc output files, when source is +a header. + +.IP QT_UIC +Default value is '$QT_BINPATH/uic'. + +.IP QT_UICCOM +Command to generate header files from .ui files. + +.IP QT_UICCOMSTR +The string displayed when generating header files from .ui files. +If this is not set, then $QT_UICCOM (the command line) is displayed. + +.IP QT_UICDECLFLAGS +Default value is ''. These flags are passed to uic, when creating a a h +file from a .ui file. + +.IP QT_UICDECLPREFIX +Default value is ''. Prefix for uic generated header files. + +.IP QT_UICDECLSUFFIX +Default value is '.h'. Suffix for uic generated header files. + +.IP QT_UICIMPLFLAGS +Default value is ''. These flags are passed to uic, when creating a cxx +file from a .ui file. + +.IP QT_UICIMPLPREFIX +Default value is 'uic_'. Prefix for uic generated implementation files. + +.IP QT_UICIMPLSUFFIX +Default value is '$CXXFILESUFFIX'. Suffix for uic generated implementation +files. + +.IP QT_UISUFFIX +Default value is '.ui'. Suffix of designer input files. + +.IP QTDIR +The qt tool tries to take this from os.environ. +It also initializes all QT_* +construction variables listed below. +(Note that all paths are constructed +with python's os.path.join() method, +but are listed here with the '/' separator +for easier reading.) +In addition, the construction environment +variables $CPPPATH, +$LIBPATH and +$LIBS may be modified +and the variables +PROGEMITTER, SHLIBEMITTER and LIBEMITTER +are modified. Because the build-performance is affected when using this tool, +you have to explicitly specify it at Environment creation: + +.ES +Environment(tools=['default','qt']) +.EE +.IP +The qt tool supports the following operations: + +.I Automatic moc file generation from header files. +You do not have to specify moc files explicitly, the tool does it for you. +However, there are a few preconditions to do so: Your header file must have +the same filebase as your implementation file and must stay in the same +directory. It must have one of the suffixes .h, .hpp, .H, .hxx, .hh. You +can turn off automatic moc file generation by setting QT_AUTOSCAN to 0. +See also the corresponding builder method +.B Moc() + +.I Automatic moc file generation from cxx files. +As stated in the qt documentation, include the moc file at the end of +the cxx file. Note that you have to include the file, which is generated +by the transformation ${QT_MOCCXXPREFIX}<basename>${QT_MOCCXXSUFFIX}, by default +<basename>.moc. A warning is generated after building the moc file, if you +do not include the correct file. If you are using VariantDir, you may +need to specify duplicate=1. You can turn off automatic moc file generation +by setting QT_AUTOSCAN to 0. See also the corresponding +.BR Moc () +builder method. + +.I Automatic handling of .ui files. +The implementation files generated from .ui files are handled much the same +as yacc or lex files. Each .ui file given as a source of Program, Library or +SharedLibrary will generate three files, the declaration file, the +implementation file and a moc file. Because there are also generated headers, +you may need to specify duplicate=1 in calls to VariantDir. +See also the corresponding +.BR Uic () +builder method. + +.IP RANLIB +The archive indexer. + +.IP RANLIBCOM +The command line used to index a static library archive. + +.IP RANLIBCOMSTR +The string displayed when a static library archive is indexed. +If this is not set, then $RANLIBCOM (the command line) is displayed. + +.ES +env = Environment(RANLIBCOMSTR = "Indexing $TARGET") +.EE + +.IP RANLIBFLAGS +General options passed to the archive indexer. + +.IP RC +The resource compiler used to build +a Microsoft Visual C++ resource file. + +.IP RCCOM +The command line used to build +a Microsoft Visual C++ resource file. + +.IP RCCOMSTR +The string displayed when invoking the resource compiler +to build a Microsoft Visual C++ resource file. +If this is not set, then $RCCOM (the command line) is displayed. + +.IP RCFLAGS +The flags passed to the resource compiler by the RES builder. + +.IP RCINCFLAGS +An automatically-generated construction variable +containing the command-line options +for specifying directories to be searched +by the resource compiler. +The value of $RCINCFLAGS is created +by appending $RCINCPREFIX and $RCINCSUFFIX +to the beginning and end +of each directory in $CPPPATH. + +.IP RCINCPREFIX +The prefix (flag) used to specify an include directory +on the resource compiler command line. +This will be appended to the beginning of each directory +in the $CPPPATH construction variable +when the $RCINCFLAGS variable is expanded. + +.IP RCINCSUFFIX +The suffix used to specify an include directory +on the resource compiler command line. +This will be appended to the end of each directory +in the $CPPPATH construction variable +when the $RCINCFLAGS variable is expanded. + +.IP RCS +The RCS executable. +Note that this variable is not actually used +for the command to fetch source files from RCS; +see the +$RCS_CO +construction variable, below. + +.IP RCS_CO +The RCS "checkout" executable, +used to fetch source files from RCS. + +.IP RCS_COCOM +The command line used to +fetch (checkout) source files from RCS. + +.IP RCS_COCOMSTR +The string displayed when fetching +a source file from RCS. +If this is not set, then $RCS_COCOM +(the command line) is displayed. + +.IP RCS_COFLAGS +Options that are passed to the $RCS_CO command. + +.IP RDirs +A function that converts a string into a list of Dir instances by +searching the repositories. + +.IP REGSVR +The program used on Windows systems +to register a newly-built DLL library +whenever the \fBSharedLibrary\fP() builder +is passed a keyword argument of \fBregister=1\fP. + +.IP REGSVRCOM +The command line used on Windows systems +to register a newly-built DLL library +whenever the \fBSharedLibrary\fP() builder +is passed a keyword argument of \fBregister=1\fP. + +.IP REGSVRCOMSTR +The string displayed when registering a newly-built DLL file. +If this is not set, then $REGSVRCOM (the command line) is displayed. + +.IP REGSVRFLAGS +Flags passed to the DLL registration program +on Windows systems when a newly-built DLL library is registered. +By default, +this includes the \fB/s\fP +that prevents dialog boxes from popping up +and requiring user attention. + +.IP RMIC +The Java RMI stub compiler. + +.IP RMICCOM +The command line used to compile stub +and skeleton class files +from Java classes that contain RMI implementations. +Any options specified in the $RMICFLAGS construction variable +are included on this command line. + +.IP RMICCOMSTR +The string displayed when compiling +stub and skeleton class files +from Java classes that contain RMI implementations. +If this is not set, then $RMICCOM (the command line) is displayed. + +.ES +env = Environment(RMICCOMSTR = "Generating stub/skeleton class files $TARGETS from $SOURCES") +.EE + +.IP RMICFLAGS +General options passed to the Java RMI stub compiler. + +.IP _RPATH +An automatically-generated construction variable +containing the rpath flags to be used when linking +a program with shared libraries. +The value of $_RPATH is created +by appending $RPATHPREFIX and $RPATHSUFFIX +to the beginning and end +of each directory in $RPATH. + +.IP RPATH +A list of paths to search for shared libraries when running programs. +Currently only used in the GNU (gnulink), +IRIX (sgilink) and Sun (sunlink) linkers. +Ignored on platforms and toolchains that don't support it. +Note that the paths added to RPATH +are not transformed by +.B scons +in any way: if you want an absolute +path, you must make it absolute yourself. + +.IP RPATHPREFIX +The prefix used to specify a directory to be searched for +shared libraries when running programs. +This will be appended to the beginning of each directory +in the $RPATH construction variable +when the $_RPATH variable is automatically generated. + +.IP RPATHSUFFIX +The suffix used to specify a directory to be searched for +shared libraries when running programs. +This will be appended to the end of each directory +in the $RPATH construction variable +when the $_RPATH variable is automatically generated. + +.IP RPCGEN +The RPC protocol compiler. + +.IP RPCGENCLIENTFLAGS +Options passed to the RPC protocol compiler +when generating client side stubs. +These are in addition to any flags specified in the +$RPCGENFLAGS +construction variable. + +.IP RPCGENFLAGS +General options passed to the RPC protocol compiler. + +.IP RPCGENHEADERFLAGS +Options passed to the RPC protocol compiler +when generating a header file. +These are in addition to any flags specified in the +$RPCGENFLAGS +construction variable. + +.IP RPCGENSERVICEFLAGS +Options passed to the RPC protocol compiler +when generating server side stubs. +These are in addition to any flags specified in the +$RPCGENFLAGS +construction variable. + +.IP RPCGENXDRFLAGS +Options passed to the RPC protocol compiler +when generating XDR routines. +These are in addition to any flags specified in the +$RPCGENFLAGS +construction variable. + +.IP SCANNERS +A list of the available implicit dependency scanners. +New file scanners may be added by +appending to this list, +although the more flexible approach +is to associate scanners +with a specific Builder. +See the sections "Builder Objects" +and "Scanner Objects," +below, for more information. + +.IP SCCS +The SCCS executable. + +.IP SCCSCOM +The command line used to +fetch source files from SCCS. + +.IP SCCSCOMSTR +The string displayed when fetching +a source file from a CVS repository. +If this is not set, then $SCCSCOM +(the command line) is displayed. + +.IP SCCSFLAGS +General options that are passed to SCCS. + +.IP SCCSGETFLAGS +Options that are passed specifically to the SCCS "get" subcommand. +This can be set, for example, to +.B \-e +to check out editable files from SCCS. + +.IP SCONS_HOME +The (optional) path to the SCons library directory, +initialized from the external environment. +If set, this is used to construct a shorter and more +efficient search path in the +$MSVSSCONS +command line executed +from Microsoft Visual Studio project files. + +.IP SHCC +The C compiler used for generating shared-library objects. + +.IP SHCCCOM +The command line used to compile a C source file +to a shared-library object file. +Any options specified in the $SHCFLAGS, +$SHCCFLAGS and +$CPPFLAGS construction variables +are included on this command line. + +.IP SHCCCOMSTR +The string displayed when a C source file +is compiled to a shared object file. +If this is not set, then $SHCCCOM (the command line) is displayed. + +.ES +env = Environment(SHCCCOMSTR = "Compiling shared object $TARGET") +.EE + +.IP SHCCFLAGS +Options that are passed to the C and C++ compilers +to generate shared-library objects. + +.IP SHCFLAGS +Options that are passed to the C compiler (only; not C++) +to generate shared-library objects. + +.IP SHCXX +The C++ compiler used for generating shared-library objects. + +.IP SHCXXCOM +The command line used to compile a C++ source file +to a shared-library object file. +Any options specified in the $SHCXXFLAGS and +$CPPFLAGS construction variables +are included on this command line. + +.IP SHCXXCOMSTR +The string displayed when a C++ source file +is compiled to a shared object file. +If this is not set, then $SHCXXCOM (the command line) is displayed. + +.ES +env = Environment(SHCXXCOMSTR = "Compiling shared object $TARGET") +.EE + +.IP SHCXXFLAGS +Options that are passed to the C++ compiler +to generate shared-library objects. + +.IP SHELL +A string naming the shell program that will be passed to the +$SPAWN +function. +See the +$SPAWN +construction variable for more information. + +.IP SHF77 +The Fortran 77 compiler used for generating shared-library objects. +You should normally set the $SHFORTRAN variable, +which specifies the default Fortran compiler +for all Fortran versions. +You only need to set $SHF77 if you need to use a specific compiler +or compiler version for Fortran 77 files. + +.IP SHF77COM +The command line used to compile a Fortran 77 source file +to a shared-library object file. +You only need to set $SHF77COM if you need to use a specific +command line for Fortran 77 files. +You should normally set the $SHFORTRANCOM variable, +which specifies the default command line +for all Fortran versions. + +.IP SHF77COMSTR +The string displayed when a Fortran 77 source file +is compiled to a shared-library object file. +If this is not set, then $SHF77COM or $SHFORTRANCOM +(the command line) is displayed. + +.IP SHF77FLAGS +Options that are passed to the Fortran 77 compiler +to generated shared-library objects. +You only need to set $SHF77FLAGS if you need to define specific +user options for Fortran 77 files. +You should normally set the $SHFORTRANFLAGS variable, +which specifies the user-specified options +passed to the default Fortran compiler +for all Fortran versions. + +.IP SHF77PPCOM +The command line used to compile a Fortran 77 source file to a +shared-library object file +after first running the file through the C preprocessor. +Any options specified in the $SHF77FLAGS and $CPPFLAGS construction variables +are included on this command line. +You only need to set $SHF77PPCOM if you need to use a specific +C-preprocessor command line for Fortran 77 files. +You should normally set the $SHFORTRANPPCOM variable, +which specifies the default C-preprocessor command line +for all Fortran versions. + +.IP SHF77PPCOMSTR +The string displayed when a Fortran 77 source file +is compiled to a shared-library object file +after first running the file through the C preprocessor. +If this is not set, then $SHF77PPCOM or $SHFORTRANPPCOM +(the command line) is displayed. + +.IP SHF90 +The Fortran 90 compiler used for generating shared-library objects. +You should normally set the $SHFORTRAN variable, +which specifies the default Fortran compiler +for all Fortran versions. +You only need to set $SHF90 if you need to use a specific compiler +or compiler version for Fortran 90 files. + +.IP SHF90COM +The command line used to compile a Fortran 90 source file +to a shared-library object file. +You only need to set $SHF90COM if you need to use a specific +command line for Fortran 90 files. +You should normally set the $SHFORTRANCOM variable, +which specifies the default command line +for all Fortran versions. + +.IP SHF90COMSTR +The string displayed when a Fortran 90 source file +is compiled to a shared-library object file. +If this is not set, then $SHF90COM or $SHFORTRANCOM +(the command line) is displayed. + +.IP SHF90FLAGS +Options that are passed to the Fortran 90 compiler +to generated shared-library objects. +You only need to set $SHF90FLAGS if you need to define specific +user options for Fortran 90 files. +You should normally set the $SHFORTRANFLAGS variable, +which specifies the user-specified options +passed to the default Fortran compiler +for all Fortran versions. + +.IP SHF90PPCOM +The command line used to compile a Fortran 90 source file to a +shared-library object file +after first running the file through the C preprocessor. +Any options specified in the $SHF90FLAGS and $CPPFLAGS construction variables +are included on this command line. +You only need to set $SHF90PPCOM if you need to use a specific +C-preprocessor command line for Fortran 90 files. +You should normally set the $SHFORTRANPPCOM variable, +which specifies the default C-preprocessor command line +for all Fortran versions. + +.IP SHF90PPCOMSTR +The string displayed when a Fortran 90 source file +is compiled to a shared-library object file +after first running the file through the C preprocessor. +If this is not set, then $SHF90PPCOM or $SHFORTRANPPCOM +(the command line) is displayed. + +.IP SHF95 +The Fortran 95 compiler used for generating shared-library objects. +You should normally set the $SHFORTRAN variable, +which specifies the default Fortran compiler +for all Fortran versions. +You only need to set $SHF95 if you need to use a specific compiler +or compiler version for Fortran 95 files. + +.IP SHF95COM +The command line used to compile a Fortran 95 source file +to a shared-library object file. +You only need to set $SHF95COM if you need to use a specific +command line for Fortran 95 files. +You should normally set the $SHFORTRANCOM variable, +which specifies the default command line +for all Fortran versions. + +.IP SHF95COMSTR +The string displayed when a Fortran 95 source file +is compiled to a shared-library object file. +If this is not set, then $SHF95COM or $SHFORTRANCOM +(the command line) is displayed. + +.IP SHF95FLAGS +Options that are passed to the Fortran 95 compiler +to generated shared-library objects. +You only need to set $SHF95FLAGS if you need to define specific +user options for Fortran 95 files. +You should normally set the $SHFORTRANFLAGS variable, +which specifies the user-specified options +passed to the default Fortran compiler +for all Fortran versions. + +.IP SHF95PPCOM +The command line used to compile a Fortran 95 source file to a +shared-library object file +after first running the file through the C preprocessor. +Any options specified in the $SHF95FLAGS and $CPPFLAGS construction variables +are included on this command line. +You only need to set $SHF95PPCOM if you need to use a specific +C-preprocessor command line for Fortran 95 files. +You should normally set the $SHFORTRANPPCOM variable, +which specifies the default C-preprocessor command line +for all Fortran versions. + +.IP SHF95PPCOMSTR +The string displayed when a Fortran 95 source file +is compiled to a shared-library object file +after first running the file through the C preprocessor. +If this is not set, then $SHF95PPCOM or $SHFORTRANPPCOM +(the command line) is displayed. + +.IP SHFORTRAN +The default Fortran compiler used for generating shared-library objects. + +.IP SHFORTRANCOM +The command line used to compile a Fortran source file +to a shared-library object file. + +.IP SHFORTRANCOMSTR +The string displayed when a Fortran source file +is compiled to a shared-library object file. +If this is not set, then $SHFORTRANCOM +(the command line) is displayed. + +.IP SHFORTRANFLAGS +Options that are passed to the Fortran compiler +to generate shared-library objects. + +.IP SHFORTRANPPCOM +The command line used to compile a Fortran source file to a +shared-library object file +after first running the file through the C preprocessor. +Any options specified +in the $SHFORTRANFLAGS and +$CPPFLAGS construction variables +are included on this command line. + +.IP SHFORTRANPPCOMSTR +The string displayed when a Fortran source file +is compiled to a shared-library object file +after first running the file throught the C preprocessor. +If this is not set, then $SHFORTRANPPCOM +(the command line) is displayed. + +.IP SHLIBPREFIX +The prefix used for shared library file names. + +.IP SHLIBSUFFIX +The suffix used for shared library file names. + +.IP SHLINK +The linker for programs that use shared libraries. + +.IP SHLINKCOM +The command line used to link programs using shared 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 +$_LIBFLAGS +above, +for the variable that expands to library-link options, +and +$_LIBDIRFLAGS +above, +for the variable that expands to library search path options. + +.IP SHOBJPREFIX +The prefix used for shared object file names. + +.IP SHOBJSUFFIX +The suffix used for shared object file names. + +.IP SOURCE +A reserved variable name +that may not be set or used in a construction environment. +(See "Variable Substitution," below.) + +.IP SOURCE_URL +The URL +(web address) +of the location from which the project was retrieved. +This is used to fill in the +.B Source: +field in the controlling information for Ipkg and RPM packages. + +.IP SOURCES +A reserved variable name +that may not be set or used in a construction environment. +(See "Variable Substitution," below.) + +.IP SPAWN +A command interpreter function that will be called to execute command line +strings. The function must expect the following arguments: + +.ES +def spawn(shell, escape, cmd, args, env): +.EE +.IP +.I sh +is a string naming the shell program to use. +.I escape +is a function that can be called to escape shell special characters in +the command line. +.I cmd +is the path to the command to be executed. +.I args +is the arguments to the command. +.I env +is a dictionary of the environment variables +in which the command should be executed. + +.IP SUBST_DICT +The dictionary used by the \fBSubstfile\fP() or \fBTextfile\fP() builders +for substitution values. +It can be anything acceptable to the dict() constructor, +so in addition to a dictionary, +lists of tuples are also acceptable. + +.IP SUBSTFILEPREFIX +The prefix used for \fBSubstfile\fP() file names, +the null string by default. + +.IP SUBSTFILESUFFIX +The suffix used for \fBSubstfile\fP() file names, +the null string by default. + +.IP SUMMARY +A short summary of what the project is about. +This is used to fill in the +.B Summary: +field in the controlling information for Ipkg and RPM packages, +and as the +.B Description: +field in MSI packages. + +.IP SWIG +The scripting language wrapper and interface generator. + +.IP SWIGCFILESUFFIX +The suffix that will be used for intermediate C +source files generated by +the scripting language wrapper and interface generator. +The default value is +.BR _wrap $CFILESUFFIX. +By default, this value is used whenever the +.B \-c++ +option is +.I not +specified as part of the +$SWIGFLAGS +construction variable. + +.IP SWIGCOM +The command line used to call +the scripting language wrapper and interface generator. + +.IP SWIGCOMSTR +The string displayed when calling +the scripting language wrapper and interface generator. +If this is not set, then $SWIGCOM (the command line) is displayed. + +.IP SWIGCXXFILESUFFIX +The suffix that will be used for intermediate C++ +source files generated by +the scripting language wrapper and interface generator. +The default value is +.BR _wrap $CFILESUFFIX. +By default, this value is used whenever the +.B \-c++ +option is specified as part of the +$SWIGFLAGS +construction variable. + +.IP SWIGDIRECTORSUFFIX +The suffix that will be used for intermediate C++ header +files generated by the scripting language wrapper and interface generator. +These are only generated for C++ code when the SWIG 'directors' feature is +turned on. +The default value is +.BR _wrap.h . + +.IP SWIGFLAGS +General options passed to +the scripting language wrapper and interface generator. +This is where you should set +.BR \-python , +.BR \-perl5 , +.BR \-tcl , +or whatever other options you want to specify to SWIG. +If you set the +.B \-c++ +option in this variable, +.B scons +will, by default, +generate a C++ intermediate source file +with the extension that is specified as the +$CXXFILESUFFIX +variable. + +.IP _SWIGINCFLAGS +An automatically-generated construction variable +containing the SWIG command-line options +for specifying directories to be searched for included files. +The value of $_SWIGINCFLAGS is created +by appending $SWIGINCPREFIX and $SWIGINCSUFFIX +to the beginning and end +of each directory in $SWIGPATH. + +.IP SWIGINCPREFIX +The prefix used to specify an include directory on the SWIG command line. +This will be appended to the beginning of each directory +in the $SWIGPATH construction variable +when the $_SWIGINCFLAGS variable is automatically generated. + +.IP SWIGINCSUFFIX +The suffix used to specify an include directory on the SWIG command line. +This will be appended to the end of each directory +in the $SWIGPATH construction variable +when the $_SWIGINCFLAGS variable is automatically generated. + +.IP SWIGOUTDIR +Specifies the output directory in which +the scripting language wrapper and interface generator +should place generated language-specific files. +This will be used by SCons to identify +the files that will be generated by the &swig; call, +and translated into the +\fBswig -outdir\fP option on the command line. + +.IP SWIGPATH +The list of directories that the scripting language wrapper +and interface generate will search for included files. +The SWIG implicit dependency scanner will search these +directories for include files. +The default is to use the same path +specified as $CPPPATH. + +Don't explicitly put include directory +arguments in SWIGFLAGS; +the result will be non-portable +and the directories will not be searched by the dependency scanner. +Note: directory names in SWIGPATH will be looked-up relative to the SConscript +directory when they are used in a command. +To force +.B scons +to look-up a directory relative to the root of the source tree use #: + +.ES +env = Environment(SWIGPATH='#/include') +.EE +.IP +The directory look-up can also be forced using the +.BR Dir () +function: + +.ES +include = Dir('include') +env = Environment(SWIGPATH=include) +.EE +.IP +The directory list will be added to command lines +through the automatically-generated +$_SWIGINCFLAGS +construction variable, +which is constructed by +appending the values of the +$SWIGINCPREFIX and $SWIGINCSUFFIX +construction variables +to the beginning and end +of each directory in $SWIGPATH. +Any command lines you define that need +the SWIGPATH directory list should +include $_SWIGINCFLAGS: + +.ES +env = Environment(SWIGCOM="my_swig -o $TARGET $_SWIGINCFLAGS $SORUCES") +.EE + +.IP SWIGVERSION +The version number of the SWIG tool. + +.IP TAR +The tar archiver. + +.IP TARCOM +The command line used to call the tar archiver. + +.IP TARCOMSTR +The string displayed when archiving files +using the tar archiver. +If this is not set, then $TARCOM (the command line) is displayed. + +.ES +env = Environment(TARCOMSTR = "Archiving $TARGET") +.EE + +.IP TARFLAGS +General options passed to the tar archiver. + +.IP TARGET +A reserved variable name +that may not be set or used in a construction environment. +(See "Variable Substitution," below.) + +.IP TARGET_ARCH +Sets the target architecture for Visual Studio compiler (i.e. the arch +of the binaries generated by the compiler). If not set, default to +$HOST_ARCH. +This is currently only used on Windows, but in the future it will be +used on other OSes as well. + +Valid values for Windows are 'x86', 'i386' (for 32 bits); +'amd64', 'emt64', 'x86_64' (64 bits); +and 'ia64' (Itanium). +For example, if you want to compile 64-bit binaries, you would set +TARGET_ARCH='x86_64' in your SCons environment. + +.IP TARGET_OS + The name of the target operating system for the compiled objects + created by this Environment. + This defaults to the value of HOST_OS, and the user can override it. + Currently only set for Win32. + +.IP TARGETS +A reserved variable name +that may not be set or used in a construction environment. +(See "Variable Substitution," below.) + +.IP TARSUFFIX +The suffix used for tar file names. + +.IP TEMPFILEPREFIX +The prefix for a temporary file used +to execute lines longer than $MAXLINELENGTH. +The default is '@'. +This may be set for toolchains that use other values, +such as '-@' for the diab compiler +or '-via' for ARM toolchain. + +.IP TEX +The TeX formatter and typesetter. + +.IP TEXCOM +The command line used to call the TeX formatter and typesetter. + +.IP TEXCOMSTR +The string displayed when calling +the TeX formatter and typesetter. +If this is not set, then $TEXCOM (the command line) is displayed. + +.ES +env = Environment(TEXCOMSTR = "Building $TARGET from TeX input $SOURCES") +.EE + +.IP TEXFLAGS +General options passed to the TeX formatter and typesetter. + +.IP TEXINPUTS +List of directories that the LaTeX programm will search +for include directories. +The LaTeX implicit dependency scanner will search these +directories for \\include and \\import files. + +.IP TEXTFILEPREFIX +The prefix used for \fBTextfile\fP() file names, +the null string by default. + +.IP TEXTFILESUFFIX +The suffix used for \fBTextfile\fP() file names; +\fB.txt\fP by default. + +.IP TOOLS +A list of the names of the Tool specifications +that are part of this construction environment. + +.IP UNCHANGED_SOURCES +A reserved variable name +that may not be set or used in a construction environment. +(See "Variable Substitution," below.) + +.IP UNCHANGED_TARGETS +A reserved variable name +that may not be set or used in a construction environment. +(See "Variable Substitution," below.) + +.IP VENDOR +The person or organization who supply the packaged software. +This is used to fill in the +.B Vendor: +field in the controlling information for RPM packages, +and the +.B Manufacturer: +field in the controlling information for MSI packages. + +.IP VERSION +The version of the project, specified as a string. + +.IP WIN32_INSERT_DEF +A deprecated synonym for $WINDOWS_INSERT_DEF. + +.IP WIN32DEFPREFIX +A deprecated synonym for $WINDOWSDEFPREFIX. + +.IP WIN32DEFSUFFIX +A deprecated synonym for $WINDOWSDEFSUFFIX. + +.IP WIN32EXPPREFIX +A deprecated synonym for $WINDOWSEXPSUFFIX. + +.IP WIN32EXPSUFFIX +A deprecated synonym for $WINDOWSEXPSUFFIX. + +.IP WINDOWS_INSERT_DEF +When this is set to true, +a library build of a Windows shared library +(\fB.dll\fPfile) +will also build a corresponding \fB.def\fP file +at the same time, +if a \fB.def\fP file +is not already listed as a build target. +The default is 0 (do not build a \fB.def\fP file). + +.IP WINDOWS_INSERT_MANIFEST +When this is set to true, +.B scons +will be aware of the +.B .manifest +files generated by Microsoft Visua C/C++ 8. + +.IP WINDOWSDEFPREFIX +The prefix used for Windows \fB.def\fPfile names. + +.IP WINDOWSDEFSUFFIX +The suffix used for Windows \fB.def\fP file names. + +.IP WINDOWSEXPPREFIX +The prefix used for Windows \fB.exp\fP file names. + +.IP WINDOWSEXPSUFFIX +The suffix used for Windows \fB.exp\fP file names. + +.IP WINDOWSPROGMANIFESTPREFIX +The prefix used for executable program \fB.manifest\fP files +generated by Microsoft Visual C/C++. + +.IP WINDOWSPROGMANIFESTSUFFIX +The suffix used for executable program \fB.manifest\fP files +generated by Microsoft Visual C/C++. + +.IP WINDOWSSHLIBMANIFESTPREFIX +The prefix used for shared library \fB.manifest\fP files +generated by Microsoft Visual C/C++. + +.IP WINDOWSSHLIBMANIFESTSUFFIX +The suffix used for shared library \fB.manifest\fP files +generated by Microsoft Visual C/C++. + +.IP X_IPK_DEPENDS +This is used to fill in the +.B Depends: +field in the controlling information for Ipkg packages. + +.IP X_IPK_DESCRIPTION +This is used to fill in the +.B Description: +field in the controlling information for Ipkg packages. +The default value is +.B "$SUMMARY\\\\$SUMMARY" +.IP X_IPK_MAINTAINER +This is used to fill in the +.B Maintainer: +field in the controlling information for Ipkg packages. + +.IP X_IPK_PRIORITY +This is used to fill in the +.B Priority: +field in the controlling information for Ipkg packages. + +.IP X_IPK_SECTION +This is used to fill in the +.B Section: +field in the controlling information for Ipkg packages. + +.IP X_MSI_LANGUAGE +This is used to fill in the +.B Language: +attribute in the controlling information for MSI packages. + +.IP X_MSI_LICENSE_TEXT +The text of the software license in RTF format. +Carriage return characters will be +replaced with the RTF equivalent \\\par. + +.IP X_MSI_UPGRADE_CODE +TODO + +.IP X_RPM_AUTOREQPROV +This is used to fill in the +.B AutoReqProv: +field in the RPM +\fB.spec\fP file. + +.IP X_RPM_BUILD +internal, but overridable + +.IP X_RPM_BUILDREQUIRES +This is used to fill in the +.B BuildRequires: +field in the RPM +\fB.spec\fP file. + +.IP X_RPM_BUILDROOT +internal, but overridable + +.IP X_RPM_CLEAN +internal, but overridable + +.IP X_RPM_CONFLICTS +This is used to fill in the +.B Conflicts: +field in the RPM +\fB.spec\fP file. + +.IP X_RPM_DEFATTR +This value is used as the default attributes +for the files in the RPM package. +The default value is +.BR (-,root,root) . + +.IP X_RPM_DISTRIBUTION +This is used to fill in the +.B Distribution: +field in the RPM +\fB.spec\fP file. + +.IP X_RPM_EPOCH +This is used to fill in the +.B Epoch: +field in the controlling information for RPM packages. + +.IP X_RPM_EXCLUDEARCH +This is used to fill in the +.B ExcludeArch: +field in the RPM +\fB.spec\fP file. + +.IP X_RPM_EXLUSIVEARCH +This is used to fill in the +.B ExclusiveArch: +field in the RPM +\fB.spec\fP file. + +.IP X_RPM_GROUP +This is used to fill in the +.B Group: +field in the RPM +\fB.spec\fP file. + +.IP X_RPM_GROUP_lang +This is used to fill in the +.B Group(lang): +field in the RPM +\fB.spec\fP file. +Note that +.I lang +is not literal +and should be replaced by +the appropriate language code. + +.IP X_RPM_ICON +This is used to fill in the +.B Icon: +field in the RPM +\fB.spec\fP file. + +.IP X_RPM_INSTALL +internal, but overridable + +.IP X_RPM_PACKAGER +This is used to fill in the +.B Packager: +field in the RPM +\fB.spec\fP file. + +.IP X_RPM_POSTINSTALL +This is used to fill in the +.B %post: +section in the RPM +\fB.spec\fP file. + +.IP X_RPM_POSTUNINSTALL +This is used to fill in the +.B %postun: +section in the RPM +\fB.spec\fP file. + +.IP X_RPM_PREFIX +This is used to fill in the +.B Prefix: +field in the RPM +\fB.spec\fP file. + +.IP X_RPM_PREINSTALL +This is used to fill in the +.B %pre: +section in the RPM +\fB.spec\fP file. + +.IP X_RPM_PREP +internal, but overridable + +.IP X_RPM_PREUNINSTALL +This is used to fill in the +.B %preun: +section in the RPM +\fB.spec\fP file. + +.IP X_RPM_PROVIDES +This is used to fill in the +.B Provides: +field in the RPM +\fB.spec\fP file. + +.IP X_RPM_REQUIRES +This is used to fill in the +.B Requires: +field in the RPM +\fB.spec\fP file. + +.IP X_RPM_SERIAL +This is used to fill in the +.B Serial: +field in the RPM +\fB.spec\fP file. + +.IP X_RPM_URL +This is used to fill in the +.B Url: +field in the RPM +\fB.spec\fP file. + +.IP YACC +The parser generator. + +.IP YACCCOM +The command line used to call the parser generator +to generate a source file. + +.IP YACCCOMSTR +The string displayed when generating a source file +using the parser generator. +If this is not set, then $YACCCOM (the command line) is displayed. + +.ES +env = Environment(YACCCOMSTR = "Yacc'ing $TARGET from $SOURCES") +.EE + +.IP YACCFLAGS +General options passed to the parser generator. +If $YACCFLAGS contains a \fB\-d\fP option, +SCons assumes that the call will also create a .h file +(if the yacc source file ends in a .y suffix) +or a .hpp file +(if the yacc source file ends in a .yy suffix) + +.IP YACCHFILESUFFIX +The suffix of the C +header file generated by the parser generator +when the +.B \-d +option is used. +Note that setting this variable does not cause +the parser generator to generate a header +file with the specified suffix, +it exists to allow you to specify +what suffix the parser generator will use of its own accord. +The default value is +.BR .h . + +.IP YACCHXXFILESUFFIX +The suffix of the C++ +header file generated by the parser generator +when the +.B \-d +option is used. +Note that setting this variable does not cause +the parser generator to generate a header +file with the specified suffix, +it exists to allow you to specify +what suffix the parser generator will use of its own accord. +The default value is +.BR .hpp , +except on Mac OS X, +where the default is +.BR ${TARGET.suffix}.h . +because the default &bison; parser generator just +appends \fB.h\fP +to the name of the generated C++ file. + +.IP YACCVCGFILESUFFIX +The suffix of the file +containing the VCG grammar automaton definition +when the +.B \--graph= +option is used. +Note that setting this variable does not cause +the parser generator to generate a VCG +file with the specified suffix, +it exists to allow you to specify +what suffix the parser generator will use of its own accord. +The default value is +.BR .vcg . + +.IP ZIP +The zip compression and file packaging utility. + +.IP ZIPCOM +The command line used to call the zip utility, +or the internal Python function used to create a +zip archive. + +.IP ZIPCOMPRESSION +The +.I compression +flag +from the Python +.B zipfile +module used by the internal Python function +to control whether the zip archive +is compressed or not. +The default value is +.BR zipfile.ZIP_DEFLATED , +which creates a compressed zip archive. +This value has no effect when using Python 1.5.2 +or if the +.B zipfile +module is otherwise unavailable. + +.IP ZIPCOMSTR +The string displayed when archiving files +using the zip utility. +If this is not set, then $ZIPCOM +(the command line or internal Python function) is displayed. + +.ES +env = Environment(ZIPCOMSTR = "Zipping $TARGET") +.EE + +.IP ZIPFLAGS +General options passed to the zip utility. + +.IP ZIPSUFFIX +The suffix used for zip file names. +'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +'\" END GENERATED CONSTRUCTION VARIABLE DESCRIPTIONS +'\" +'\" The descriptions above of the various SCons construction variables +'\" are generated from the .xml files that live next to the various +'\" Python modules in the build enginer library. If you're reading +'\" this [gnt]roff file with an eye towards patching this man page, +'\" you can still submit a diff against this text, but it will have to +'\" be translated to a diff against the underlying .xml file before the +'\" patch is actually accepted. If you do that yourself, it will make +'\" it easier to integrate the patch. +'\" +'\" END GENERATED CONSTRUCTION VARIABLE DESCRIPTIONS +'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" + +.LP +Construction variables can be retrieved and set using the +.B Dictionary +method of the construction environment: + +.ES +dict = env.Dictionary() +dict["CC"] = "cc" +.EE + +or using the [] operator: + +.ES +env["CC"] = "cc" +.EE + +Construction variables can also be passed to the construction environment +constructor: + +.ES +env = Environment(CC="cc") +.EE + +or when copying a construction environment using the +.B Clone +method: + +.ES +env2 = env.Clone(CC="cl.exe") +.EE + +.SS Configure Contexts + +.B scons +supports +.I configure contexts, +an integrated mechanism similar to the +various AC_CHECK macros in GNU autoconf +for testing for the existence of C header +files, libraries, etc. +In contrast to autoconf, +.B scons +does not maintain an explicit cache of the tested values, +but uses its normal dependency tracking to keep the checked values +up to date. However, users may override this behaviour with the +.B --config +command line option. + +The following methods can be used to perform checks: + +.TP +.RI Configure( env ", [" custom_tests ", " conf_dir ", " log_file ", " config_h ", " clean ", " help]) +.TP +.RI env.Configure([ custom_tests ", " conf_dir ", " log_file ", " config_h ", " clean ", " help]) +This creates a configure context, which can be used to perform checks. +.I env +specifies the environment for building the tests. +This environment may be modified when performing checks. +.I custom_tests +is a dictionary containing custom tests. +See also the section about custom tests below. +By default, no custom tests are added to the configure context. +.I conf_dir +specifies a directory where the test cases are built. +Note that this directory is not used for building +normal targets. +The default value is the directory +#/.sconf_temp. +.I log_file +specifies a file which collects the output from commands +that are executed to check for the existence of header files, libraries, etc. +The default is the file #/config.log. +If you are using the +.BR VariantDir () +method, +you may want to specify a subdirectory under your variant directory. +.I config_h +specifies a C header file where the results of tests +will be written, e.g. #define HAVE_STDIO_H, #define HAVE_LIBM, etc. +The default is to not write a +.B config.h +file. +You can specify the same +.B config.h +file in multiple calls to Configure, +in which case +.B scons +will concatenate all results in the specified file. +Note that SCons +uses its normal dependency checking +to decide if it's necessary to rebuild +the specified +.I config_h +file. +This means that the file is not necessarily re-built each +time scons is run, +but is only rebuilt if its contents will have changed +and some target that depends on the +.I config_h +file is being built. + +The optional +.B clean +and +.B help +arguments can be used to suppress execution of the configuration +tests when the +.B -c/--clean +or +.B -H/-h/--help +options are used, respectively. +The default behavior is always to execute +configure context tests, +since the results of the tests may +affect the list of targets to be cleaned +or the help text. +If the configure tests do not affect these, +then you may add the +.B clean=False +or +.B help=False +arguments +(or both) +to avoid unnecessary test execution. + +.EE +A created +.B Configure +instance has the following associated methods: + +.TP +.RI SConf.Finish( context ) +.TP +.IR sconf .Finish() +This method should be called after configuration is done. +It returns the environment as modified +by the configuration checks performed. +After this method is called, no further checks can be performed +with this configuration context. +However, you can create a new +.RI Configure +context to perform additional checks. +Only one context should be active at a time. + +The following Checks are predefined. +(This list will likely grow larger as time +goes by and developers contribute new useful tests.) + +.TP +.RI SConf.CheckHeader( context ", " header ", [" include_quotes ", " language ]) +.TP +.IR sconf .CheckHeader( header ", [" include_quotes ", " language ]) +Checks if +.I header +is usable in the specified language. +.I header +may be a list, +in which case the last item in the list +is the header file to be checked, +and the previous list items are +header files whose +.B #include +lines should precede the +header line being checked for. +The optional argument +.I include_quotes +must be +a two character string, where the first character denotes the opening +quote and the second character denotes the closing quote. +By default, both characters are " (double quote). +The optional argument +.I language +should be either +.B C +or +.B C++ +and selects the compiler to be used for the check. +Returns 1 on success and 0 on failure. + +.TP +.RI SConf.CheckCHeader( context ", " header ", [" include_quotes ]) +.TP +.IR sconf .CheckCHeader( header ", [" include_quotes ]) +This is a wrapper around +.B SConf.CheckHeader +which checks if +.I header +is usable in the C language. +.I header +may be a list, +in which case the last item in the list +is the header file to be checked, +and the previous list items are +header files whose +.B #include +lines should precede the +header line being checked for. +The optional argument +.I include_quotes +must be +a two character string, where the first character denotes the opening +quote and the second character denotes the closing quote (both default +to \N'34'). +Returns 1 on success and 0 on failure. + +.TP +.RI SConf.CheckCXXHeader( context ", " header ", [" include_quotes ]) +.TP +.IR sconf .CheckCXXHeader( header ", [" include_quotes ]) +This is a wrapper around +.B SConf.CheckHeader +which checks if +.I header +is usable in the C++ language. +.I header +may be a list, +in which case the last item in the list +is the header file to be checked, +and the previous list items are +header files whose +.B #include +lines should precede the +header line being checked for. +The optional argument +.I include_quotes +must be +a two character string, where the first character denotes the opening +quote and the second character denotes the closing quote (both default +to \N'34'). +Returns 1 on success and 0 on failure. + +.TP +.RI SConf.CheckFunc( context, ", " function_name ", [" header ", " language ]) +.TP +.IR sconf .CheckFunc( function_name ", [" header ", " language ]) +Checks if the specified +C or C++ function is available. +.I function_name +is the name of the function to check for. +The optional +.I header +argument is a string +that will be +placed at the top +of the test file +that will be compiled +to check if the function exists; +the default is: +.ES +#ifdef __cplusplus +extern "C" +#endif +char function_name(); +.EE +The optional +.I language +argument should be +.B C +or +.B C++ +and selects the compiler to be used for the check; +the default is "C". + +.TP +.RI SConf.CheckLib( context ", [" library ", " symbol ", " header ", " language ", " autoadd=1 ]) +.TP +.IR sconf .CheckLib([ library ", " symbol ", " header ", " language ", " autoadd=1 ]) +Checks if +.I library +provides +.IR symbol . +If the value of +.I autoadd +is 1 and the library provides the specified +.IR symbol , +appends the library to the LIBS construction environment variable. +.I library +may also be None (the default), +in which case +.I symbol +is checked with the current LIBS variable, +or a list of library names, +in which case each library in the list +will be checked for +.IR symbol . +If +.I symbol +is not set or is +.BR None , +then +.BR SConf.CheckLib () +just checks if +you can link against the specified +.IR library . +The optional +.I language +argument should be +.B C +or +.B C++ +and selects the compiler to be used for the check; +the default is "C". +The default value for +.I autoadd +is 1. +This method returns 1 on success and 0 on error. + +.TP +.RI SConf.CheckLibWithHeader( context ", " library ", " header ", " language ", [" call ", " autoadd ]) +.TP +.IR sconf .CheckLibWithHeader( library ", " header ", " language ", [" call ", " autoadd ]) + +In contrast to the +.RI SConf.CheckLib +call, this call provides a more sophisticated way to check against libraries. +Again, +.I library +specifies the library or a list of libraries to check. +.I header +specifies a header to check for. +.I header +may be a list, +in which case the last item in the list +is the header file to be checked, +and the previous list items are +header files whose +.B #include +lines should precede the +header line being checked for. +.I language +may be one of 'C','c','CXX','cxx','C++' and 'c++'. +.I call +can be any valid expression (with a trailing ';'). +If +.I call +is not set, +the default simply checks that you +can link against the specified +.IR library . +.I autoadd +specifies whether to add the library to the environment (only if the check +succeeds). This method returns 1 on success and 0 on error. + +.TP +.RI SConf.CheckType( context ", " type_name ", [" includes ", " language ]) +.TP +.IR sconf .CheckType( type_name ", [" includes ", " language ]) +Checks for the existence of a type defined by +.BR typedef . +.I type_name +specifies the typedef name to check for. +.I includes +is a string containing one or more +.B #include +lines that will be inserted into the program +that will be run to test for the existence of the type. +The optional +.I language +argument should be +.B C +or +.B C++ +and selects the compiler to be used for the check; +the default is "C". +Example: +.ES +sconf.CheckType('foo_type', '#include "my_types.h"', 'C++') +.EE + +.TP +.RI Configure.CheckCC( self ) +Checks whether the C compiler (as defined by the CC construction variable) works +by trying to compile a small source file. + +By default, SCons only detects if there is a program with the correct name, not +if it is a functioning compiler. + +This uses the exact same command than the one used by the object builder for C +source file, so it can be used to detect if a particular compiler flag works or +not. + +.TP +.RI Configure.CheckCXX( self ) +Checks whether the C++ compiler (as defined by the CXX construction variable) +works by trying to compile a small source file. By default, SCons only detects +if there is a program with the correct name, not if it is a functioning compiler. + +This uses the exact same command than the one used by the object builder for +CXX source files, so it can be used to detect if a particular compiler flag +works or not. + +.TP +.RI Configure.CheckSHCC( self ) +Checks whether the C compiler (as defined by the SHCC construction variable) works +by trying to compile a small source file. By default, SCons only detects if +there is a program with the correct name, not if it is a functioning compiler. + +This uses the exact same command than the one used by the object builder for C +source file, so it can be used to detect if a particular compiler flag works or +not. This does not check whether the object code can be used to build a shared +library, only that the compilation (not link) succeeds. + +.TP +.RI Configure.CheckSHCXX( self ) +Checks whether the C++ compiler (as defined by the SHCXX construction variable) +works by trying to compile a small source file. By default, SCons only detects +if there is a program with the correct name, not if it is a functioning compiler. + +This uses the exact same command than the one used by the object builder for +CXX source files, so it can be used to detect if a particular compiler flag +works or not. This does not check whether the object code can be used to build +a shared library, only that the compilation (not link) succeeds. + +.EE +Example of a typical Configure usage: + +.ES +env = Environment() +conf = Configure( env ) +if not conf.CheckCHeader( 'math.h' ): + print 'We really need math.h!' + Exit(1) +if conf.CheckLibWithHeader( 'qt', 'qapp.h', 'c++', + 'QApplication qapp(0,0);' ): + # do stuff for qt - usage, e.g. + conf.env.Append( CPPFLAGS = '-DWITH_QT' ) +env = conf.Finish() +.EE + +.TP +.RI SConf.CheckTypeSize( context ", " type_name ", [" header ", " language ", " expect ]) +.TP +.IR sconf .CheckTypeSize( type_name ", [" header ", " language ", " expect ]) +Checks for the size of a type defined by +.BR typedef . +.I type_name +specifies the typedef name to check for. +The optional +.I header +argument is a string +that will be +placed at the top +of the test file +that will be compiled +to check if the function exists; +the default is empty. +The optional +.I language +argument should be +.B C +or +.B C++ +and selects the compiler to be used for the check; +the default is "C". +The optional +.I expect +argument should be an integer. +If this argument is used, +the function will only check whether the type +given in type_name has the expected size (in bytes). +For example, +.B "CheckTypeSize('short', expect = 2)" +will return success only if short is two bytes. + +.ES +.EE + +.TP +.RI SConf.CheckDeclaration( context ", " symbol ", [" includes ", " language ]) +.TP +.IR sconf .CheckDeclaration( symbol ", [" includes ", " language ]) +Checks if the specified +.I symbol +is declared. +.I includes +is a string containing one or more +.B #include +lines that will be inserted into the program +that will be run to test for the existence of the type. +The optional +.I language +argument should be +.B C +or +.B C++ +and selects the compiler to be used for the check; +the default is "C". + +.TP +.RI SConf.Define( context ", " symbol ", [" value ", " comment ]) +.TP +.IR sconf .Define( symbol ", [" value ", " comment ]) +This function does not check for anything, but defines a +preprocessor symbol that will be added to the configuration header file. +It is the equivalent of AC_DEFINE, +and defines the symbol +.I name +with the optional +.B value +and the optional comment +.BR comment . + +.IP +Examples: + +.ES +env = Environment() +conf = Configure( env ) + +# Puts the following line in the config header file: +# #define A_SYMBOL +conf.Define('A_SYMBOL') + +# Puts the following line in the config header file: +# #define A_SYMBOL 1 +conf.Define('A_SYMBOL', 1) +.EE + +.IP +Be careful about quoting string values, though: + +.ES +env = Environment() +conf = Configure( env ) + +# Puts the following line in the config header file: +# #define A_SYMBOL YA +conf.Define('A_SYMBOL', "YA") + +# Puts the following line in the config header file: +# #define A_SYMBOL "YA" +conf.Define('A_SYMBOL', '"YA"') +.EE + +.IP +For comment: + +.ES +env = Environment() +conf = Configure( env ) + +# Puts the following lines in the config header file: +# /* Set to 1 if you have a symbol */ +# #define A_SYMBOL 1 +conf.Define('A_SYMBOL', 1, 'Set to 1 if you have a symbol') +.EE + +.EE +You can define your own custom checks. +in addition to the predefined checks. +These are passed in a dictionary to the Configure function. +This dictionary maps the names of the checks +to user defined Python callables +(either Python functions or class instances implementing the +.I __call__ +method). +The first argument of the call is always a +.I CheckContext +instance followed by the arguments, +which must be supplied by the user of the check. +These CheckContext instances define the following methods: + +.TP +.RI CheckContext.Message( self ", " text ) + +Usually called before the check is started. +.I text +will be displayed to the user, e.g. 'Checking for library X...' + +.TP +.RI CheckContext.Result( self, ", " res ) + +Usually called after the check is done. +.I res +can be either an integer or a string. In the former case, 'yes' (res != 0) +or 'no' (res == 0) is displayed to the user, in the latter case the +given string is displayed. + +.TP +.RI CheckContext.TryCompile( self ", " text ", " extension ) +Checks if a file with the specified +.I extension +(e.g. '.c') containing +.I text +can be compiled using the environment's +.B Object +builder. Returns 1 on success and 0 on failure. + +.TP +.RI CheckContext.TryLink( self ", " text ", " extension ) +Checks, if a file with the specified +.I extension +(e.g. '.c') containing +.I text +can be compiled using the environment's +.B Program +builder. Returns 1 on success and 0 on failure. + +.TP +.RI CheckContext.TryRun( self ", " text ", " extension ) +Checks, if a file with the specified +.I extension +(e.g. '.c') containing +.I text +can be compiled using the environment's +.B Program +builder. On success, the program is run. If the program +executes successfully +(that is, its return status is 0), +a tuple +.I (1, outputStr) +is returned, where +.I outputStr +is the standard output of the +program. +If the program fails execution +(its return status is non-zero), +then (0, '') is returned. + +.TP +.RI CheckContext.TryAction( self ", " action ", [" text ", " extension ]) +Checks if the specified +.I action +with an optional source file (contents +.I text +, extension +.I extension += '' +) can be executed. +.I action +may be anything which can be converted to a +.B scons +.RI Action. +On success, +.I (1, outputStr) +is returned, where +.I outputStr +is the content of the target file. +On failure +.I (0, '') +is returned. + +.TP +.RI CheckContext.TryBuild( self ", " builder ", [" text ", " extension ]) +Low level implementation for testing specific builds; +the methods above are based on this method. +Given the Builder instance +.I builder +and the optional +.I text +of a source file with optional +.IR extension , +this method returns 1 on success and 0 on failure. In addition, +.I self.lastTarget +is set to the build target node, if the build was successful. + +.EE +Example for implementing and using custom tests: + +.ES +def CheckQt(context, qtdir): + context.Message( 'Checking for qt ...' ) + lastLIBS = context.env['LIBS'] + lastLIBPATH = context.env['LIBPATH'] + lastCPPPATH= context.env['CPPPATH'] + context.env.Append(LIBS = 'qt', LIBPATH = qtdir + '/lib', CPPPATH = qtdir + '/include' ) + ret = context.TryLink(""" +#include <qapp.h> +int main(int argc, char **argv) { + QApplication qapp(argc, argv); + return 0; +} +""") + if not ret: + context.env.Replace(LIBS = lastLIBS, LIBPATH=lastLIBPATH, CPPPATH=lastCPPPATH) + context.Result( ret ) + return ret + +env = Environment() +conf = Configure( env, custom_tests = { 'CheckQt' : CheckQt } ) +if not conf.CheckQt('/usr/lib/qt'): + print 'We really need qt!' + Exit(1) +env = conf.Finish() +.EE + +.SS Command-Line Construction Variables + +Often when building software, +some variables must be specified at build time. +For example, libraries needed for the build may be in non-standard +locations, or site-specific compiler options may need to be passed to the +compiler. +.B scons +provides a +.B Variables +object to support overriding construction variables +on the command line: +.ES +$ scons VARIABLE=foo +.EE +The variable values can also be specified in a text-based SConscript file. +To create a Variables object, call the Variables() function: + +.TP +.RI Variables([ files "], [" args ]) +This creates a Variables object that will read construction variables from +the file or list of filenames specified in +.IR files . +If no files are specified, +or the +.I files +argument is +.BR None , +then no files will be read. +The optional argument +.I args +is a dictionary of +values that will override anything read from the specified files; +it is primarily intended to be passed the +.B ARGUMENTS +dictionary that holds variables +specified on the command line. +Example: + +.ES +vars = Variables('custom.py') +vars = Variables('overrides.py', ARGUMENTS) +vars = Variables(None, {FOO:'expansion', BAR:7}) +.EE + +Variables objects have the following methods: + +.TP +.RI Add( key ", [" help ", " default ", " validator ", " converter ]) +This adds a customizable construction variable to the Variables object. +.I key +is the name of the variable. +.I help +is the help text for the variable. +.I default +is the default value of the variable; +if the default value is +.B None +and there is no explicit value specified, +the construction variable will +.I not +be added to the construction environment. +.I validator +is called to validate the value of the variable, and should take three +arguments: key, value, and environment. +The recommended way to handle an invalid value is +to raise an exception (see example below). +.I converter +is called to convert the value before putting it in the environment, and +should take either a value, or the value and environment, as parameters. +The +.I converter +must return a value, +which will be converted into a string +before being validated by the +.I validator +(if any) +and then added to the environment. + +Examples: + +.ES +vars.Add('CC', 'The C compiler') + +def validate_color(key, val, env): + if not val in ['red', 'blue', 'yellow']: + raise "Invalid color value '%s'" % val +vars.Add('COLOR', validator=valid_color) +.EE + +.TP +.RI AddVariables( list ) +A wrapper script that adds +multiple customizable construction variables +to a Variables object. +.I list +is a list of tuple or list objects +that contain the arguments +for an individual call to the +.B Add +method. + +.ES +opt.AddVariables( + ('debug', '', 0), + ('CC', 'The C compiler'), + ('VALIDATE', 'An option for testing validation', + 'notset', validator, None), + ) +.EE + +.TP +.RI Update( env ", [" args ]) +This updates a construction environment +.I env +with the customized construction variables. +Any specified variables that are +.I not +configured for the Variables object +will be saved and may be +retrieved with the +.BR UnknownVariables () +method, below. + +Normally this method is not called directly, +but is called indirectly by passing the Variables object to +the Environment() function: + +.ES +env = Environment(variables=vars) +.EE + +.IP +The text file(s) that were specified +when the Variables object was created +are executed as Python scripts, +and the values of (global) Python variables set in the file +are added to the construction environment. + +Example: + +.ES +CC = 'my_cc' +.EE + +.TP +.RI UnknownVariables( ) +Returns a dictionary containing any +variables that were specified +either in the files or the dictionary +with which the Variables object was initialized, +but for which the Variables object was +not configured. + +.ES +env = Environment(variables=vars) +for key, value in vars.UnknownVariables(): + print "unknown variable: %s=%s" % (key, value) +.EE + +.TP +.RI Save( filename ", " env ) +This saves the currently set variables into a script file named +.I filename +that can be used on the next invocation to automatically load the current +settings. This method combined with the Variables method can be used to +support caching of variables between runs. + +.ES +env = Environment() +vars = Variables(['variables.cache', 'custom.py']) +vars.Add(...) +vars.Update(env) +vars.Save('variables.cache', env) +.EE + +.TP +.RI GenerateHelpText( env ", [" sort ]) +This generates help text documenting the customizable construction +variables suitable to passing in to the Help() function. +.I env +is the construction environment that will be used to get the actual values +of customizable variables. Calling with +an optional +.I sort +function +will cause the output to be sorted +by the specified argument. +The specific +.I sort +function +should take two arguments +and return +-1, 0 or 1 +(like the standard Python +.I cmp +function). + +.ES +Help(vars.GenerateHelpText(env)) +Help(vars.GenerateHelpText(env, sort=cmp)) +.EE + +.TP +.RI FormatVariableHelpText( env ", " opt ", " help ", " default ", " actual ) +This method returns a formatted string +containing the printable help text +for one option. +It is normally not called directly, +but is called by the +.IR GenerateHelpText () +method to create the returned help text. +It may be overridden with your own +function that takes the arguments specified above +and returns a string of help text formatted to your liking. +Note that the +.IR GenerateHelpText () +will not put any blank lines or extra +characters in between the entries, +so you must add those characters to the returned +string if you want the entries separated. + +.ES +def my_format(env, opt, help, default, actual): + fmt = "\n%s: default=%s actual=%s (%s)\n" + return fmt % (opt, default. actual, help) +vars.FormatVariableHelpText = my_format +.EE + +To make it more convenient to work with customizable Variables, +.B scons +provides a number of functions +that make it easy to set up +various types of Variables: + +.TP +.RI BoolVariable( key ", " help ", " default ) +Return a tuple of arguments +to set up a Boolean option. +The option will use +the specified name +.IR key , +have a default value of +.IR default , +and display the specified +.I help +text. +The option will interpret the values +.BR y , +.BR yes , +.BR t , +.BR true , +.BR 1 , +.B on +and +.B all +as true, +and the values +.BR n , +.BR no , +.BR f , +.BR false , +.BR 0 , +.B off +and +.B none +as false. + +.TP +.RI EnumVariable( key ", " help ", " default ", " allowed_values ", [" map ", " ignorecase ]) +Return a tuple of arguments +to set up an option +whose value may be one +of a specified list of legal enumerated values. +The option will use +the specified name +.IR key , +have a default value of +.IR default , +and display the specified +.I help +text. +The option will only support those +values in the +.I allowed_values +list. +The optional +.I map +argument is a dictionary +that can be used to convert +input values into specific legal values +in the +.I allowed_values +list. +If the value of +.I ignore_case +is +.B 0 +(the default), +then the values are case-sensitive. +If the value of +.I ignore_case +is +.BR 1 , +then values will be matched +case-insensitive. +If the value of +.I ignore_case +is +.BR 1 , +then values will be matched +case-insensitive, +and all input values will be +converted to lower case. + +.TP +.RI ListVariable( key ", " help ", " default ", " names ", [", map ]) +Return a tuple of arguments +to set up an option +whose value may be one or more +of a specified list of legal enumerated values. +The option will use +the specified name +.IR key , +have a default value of +.IR default , +and display the specified +.I help +text. +The option will only support the values +.BR all , +.BR none , +or the values in the +.I names +list. +More than one value may be specified, +with all values separated by commas. +The default may be a string of +comma-separated default values, +or a list of the default values. +The optional +.I map +argument is a dictionary +that can be used to convert +input values into specific legal values +in the +.I names +list. + +.TP +.RI PackageVariable( key ", " help ", " default ) +Return a tuple of arguments +to set up an option +whose value is a path name +of a package that may be +enabled, disabled or +given an explicit path name. +The option will use +the specified name +.IR key , +have a default value of +.IR default , +and display the specified +.I help +text. +The option will support the values +.BR yes , +.BR true , +.BR on , +.BR enable +or +.BR search , +in which case the specified +.I default +will be used, +or the option may be set to an +arbitrary string +(typically the path name to a package +that is being enabled). +The option will also support the values +.BR no , +.BR false , +.BR off +or +.BR disable +to disable use of the specified option. + +.TP +.RI PathVariable( key ", " help ", " default ", [" validator ]) +Return a tuple of arguments +to set up an option +whose value is expected to be a path name. +The option will use +the specified name +.IR key , +have a default value of +.IR default , +and display the specified +.I help +text. +An additional +.I validator +may be specified +that will be called to +verify that the specified path +is acceptable. +SCons supplies the +following ready-made validators: +.BR PathVariable.PathExists +(the default), +which verifies that the specified path exists; +.BR PathVariable.PathIsFile , +which verifies that the specified path is an existing file; +.BR PathVariable.PathIsDir , +which verifies that the specified path is an existing directory; +.BR PathVariable.PathIsDirCreate , +which verifies that the specified path is a directory +and will create the specified directory if the path does not exist; +and +.BR PathVariable.PathAccept , +which simply accepts the specific path name argument without validation, +and which is suitable if you want your users +to be able to specify a directory path that will be +created as part of the build process, for example. +You may supply your own +.I validator +function, +which must take three arguments +.RI ( key , +the name of the variable to be set; +.IR val , +the specified value being checked; +and +.IR env , +the construction environment) +and should raise an exception +if the specified value is not acceptable. + +.RE +These functions make it +convenient to create a number +of variables with consistent behavior +in a single call to the +.B AddVariables +method: + +.ES +vars.AddVariables( + BoolVariable('warnings', 'compilation with -Wall and similiar', 1), + EnumVariable('debug', 'debug output and symbols', 'no' + allowed_values=('yes', 'no', 'full'), + map={}, ignorecase=0), # case sensitive + ListVariable('shared', + 'libraries to build as shared libraries', + 'all', + names = list_of_libs), + PackageVariable('x11', + 'use X11 installed here (yes = search some places)', + 'yes'), + PathVariable('qtdir', 'where the root of Qt is installed', qtdir), + PathVariable('foopath', 'where the foo library is installed', foopath, + PathVariable.PathIsDir), + +) +.EE + +.SS File and Directory Nodes + +The +.IR File () +and +.IR Dir () +functions return +.I File +and +.I Dir +Nodes, respectively. +python objects, respectively. +Those objects have several user-visible attributes +and methods that are often useful: + +.IP path +The build path +of the given +file or directory. +This path is relative to the top-level directory +(where the +.B SConstruct +file is found). +The build path is the same as the source path if +.I variant_dir +is not being used. + +.IP abspath +The absolute build path of the given file or directory. + +.IP srcnode() +The +.IR srcnode () +method +returns another +.I File +or +.I Dir +object representing the +.I source +path of the given +.I File +or +.IR Dir . +The + +.ES +# Get the current build dir's path, relative to top. +Dir('.').path +# Current dir's absolute path +Dir('.').abspath +# Next line is always '.', because it is the top dir's path relative to itself. +Dir('#.').path +File('foo.c').srcnode().path # source path of the given source file. + +# Builders also return File objects: +foo = env.Program('foo.c') +print "foo will be built in %s"%foo.path +.EE + +A +.I Dir +Node or +.I File +Node can also be used to create +file and subdirectory Nodes relative to the generating Node. +A +.I Dir +Node will place the new Nodes within the directory it represents. +A +.I File +node will place the new Nodes within its parent directory +(that is, "beside" the file in question). +If +.I d +is a +.I Dir +(directory) Node and +.I f +is a +.I File +(file) Node, +then these methods are available: + +.TP +.IR d .Dir( name ) +Returns a directory Node for a subdirectory of +.I d +named +.IR name . + +.TP +.IR d .File( name ) +Returns a file Node for a file within +.I d +named +.IR name . + +.TP +.IR d .Entry( name ) +Returns an unresolved Node within +.I d +named +.IR name . + +.TP +.IR f .Dir( name ) +Returns a directory named +.I name +within the parent directory of +.IR f . + +.TP +.IR f .File( name ) +Returns a file named +.I name +within the parent directory of +.IR f . + +.TP +.IR f .Entry( name ) +Returns an unresolved Node named +.I name +within the parent directory of +.IR f . + +.RE +For example: + +.ES +# Get a Node for a file within a directory +incl = Dir('include') +f = incl.File('header.h') + +# Get a Node for a subdirectory within a directory +dist = Dir('project-3.2.1) +src = dist.Dir('src') + +# Get a Node for a file in the same directory +cfile = File('sample.c') +hfile = cfile.File('sample.h') + +# Combined example +docs = Dir('docs') +html = docs.Dir('html') +index = html.File('index.html') +css = index.File('app.css') +.EE + +.SH EXTENDING SCONS +.SS Builder Objects +.B scons +can be extended to build different types of targets +by adding new Builder objects +to a construction environment. +.IR "In general" , +you should only need to add a new Builder object +when you want to build a new type of file or other external target. +If you just want to invoke a different compiler or other tool +to build a Program, Object, Library, or any other +type of output file for which +.B scons +already has an existing Builder, +it is generally much easier to +use those existing Builders +in a construction environment +that sets the appropriate construction variables +(CC, LINK, etc.). + +Builder objects are created +using the +.B Builder +function. +The +.B Builder +function accepts the following arguments: + +.IP action +The command line string used to build the target from the source. +.B action +can also be: +a list of strings representing the command +to be executed and its arguments +(suitable for enclosing white space in an argument), +a dictionary +mapping source file name suffixes to +any combination of command line strings +(if the builder should accept multiple source file extensions), +a Python function; +an Action object +(see the next section); +or a list of any of the above. + +An action function +takes three arguments: +.I source +- a list of source nodes, +.I target +- a list of target nodes, +.I env +- the construction environment. + +.IP prefix +The prefix that will be prepended to the target file name. +This may be specified as a: + +.RS 10 +.HP 6 +* +.IR string , + +.HP 6 +* +.I callable object +- a function or other callable that takes +two arguments (a construction environment and a list of sources) +and returns a prefix, + +.HP 6 +* +.I dictionary +- specifies a mapping from a specific source suffix (of the first +source specified) to a corresponding target prefix. Both the source +suffix and target prefix specifications may use environment variable +substitution, and the target prefix (the 'value' entries in the +dictionary) may also be a callable object. The default target prefix +may be indicated by a dictionary entry with a key value of None. +.RE +.P + +.ES +b = Builder("build_it < $SOURCE > $TARGET" + prefix = "file-") + +def gen_prefix(env, sources): + return "file-" + env['PLATFORM'] + '-' +b = Builder("build_it < $SOURCE > $TARGET", + prefix = gen_prefix) + +b = Builder("build_it < $SOURCE > $TARGET", + suffix = { None: "file-", + "$SRC_SFX_A": gen_prefix }) +.EE + +.IP suffix +The suffix that will be appended to the target file name. +This may be specified in the same manner as the prefix above. +If the suffix is a string, then +.B scons +will append a '.' to the beginning of the suffix if it's not already +there. The string returned by callable object (or obtained from the +dictionary) is untouched and must append its own '.' to the beginning +if one is desired. + +.ES +b = Builder("build_it < $SOURCE > $TARGET" + suffix = "-file") + +def gen_suffix(env, sources): + return "." + env['PLATFORM'] + "-file" +b = Builder("build_it < $SOURCE > $TARGET", + suffix = gen_suffix) + +b = Builder("build_it < $SOURCE > $TARGET", + suffix = { None: ".sfx1", + "$SRC_SFX_A": gen_suffix }) +.EE + +.IP ensure_suffix +When set to any true value, causes +.B scons +to add the target suffix specified by the +.I suffix +keyword to any target strings +that have a different suffix. +(The default behavior is to leave untouched +any target file name that looks like it already has any suffix.) + +.ES +b1 = Builder("build_it < $SOURCE > $TARGET" + suffix = ".out") +b2 = Builder("build_it < $SOURCE > $TARGET" + suffix = ".out", + ensure_suffix) +env = Environment() +env['BUILDERS']['B1'] = b1 +env['BUILDERS']['B2'] = b2 + +# Builds "foo.txt" because ensure_suffix is not set. +env.B1('foo.txt', 'foo.in') + +# Builds "bar.txt.out" because ensure_suffix is set. +env.B2('bar.txt', 'bar.in') +.EE + +.IP src_suffix +The expected source file name suffix. This may be a string or a list +of strings. + +.IP target_scanner +A Scanner object that +will be invoked to find +implicit dependencies for this target file. +This keyword argument should be used +for Scanner objects that find +implicit dependencies +based only on the target file +and the construction environment, +.I not +for implicit +(See the section "Scanner Objects," below, +for information about creating Scanner objects.) + +.IP source_scanner +A Scanner object that +will be invoked to +find implicit dependences in +any source files +used to build this target file. +This is where you would +specify a scanner to +find things like +.B #include +lines in source files. +The pre-built +.B DirScanner +Scanner object may be used to +indicate that this Builder +should scan directory trees +for on-disk changes to files +that +.B scons +does not know about from other Builder or function calls. +(See the section "Scanner Objects," below, +for information about creating your own Scanner objects.) + +.IP target_factory +A factory function that the Builder will use +to turn any targets specified as strings into SCons Nodes. +By default, +SCons assumes that all targets are files. +Other useful target_factory +values include +.BR Dir , +for when a Builder creates a directory target, +and +.BR Entry , +for when a Builder can create either a file +or directory target. + +Example: + +.ES +MakeDirectoryBuilder = Builder(action=my_mkdir, target_factory=Dir) +env = Environment() +env.Append(BUILDERS = {'MakeDirectory':MakeDirectoryBuilder}) +env.MakeDirectory('new_directory', []) +.EE + +.IP +Note that the call to the MakeDirectory Builder +needs to specify an empty source list +to make the string represent the builder's target; +without that, it would assume the argument is the source, +and would try to deduce the target name from it, +which in the absence of an automatically-added prefix or suffix +would lead to a matching target and source name +and a circular dependency. + +.IP source_factory +A factory function that the Builder will use +to turn any sources specified as strings into SCons Nodes. +By default, +SCons assumes that all source are files. +Other useful source_factory +values include +.BR Dir , +for when a Builder uses a directory as a source, +and +.BR Entry , +for when a Builder can use files +or directories (or both) as sources. + +Example: + +.ES +CollectBuilder = Builder(action=my_mkdir, source_factory=Entry) +env = Environment() +env.Append(BUILDERS = {'Collect':CollectBuilder}) +env.Collect('archive', ['directory_name', 'file_name']) +.EE + +.IP emitter +A function or list of functions to manipulate the target and source +lists before dependencies are established +and the target(s) are actually built. +.B emitter +can also be a string containing a construction variable to expand +to an emitter function or list of functions, +or a dictionary mapping source file suffixes +to emitter functions. +(Only the suffix of the first source file +is used to select the actual emitter function +from an emitter dictionary.) + +An emitter function +takes three arguments: +.I source +- a list of source nodes, +.I target +- a list of target nodes, +.I env +- the construction environment. +An emitter must return a tuple containing two lists, +the list of targets to be built by this builder, +and the list of sources for this builder. + +Example: + +.ES +def e(target, source, env): + return (target + ['foo.foo'], source + ['foo.src']) + +# Simple association of an emitter function with a Builder. +b = Builder("my_build < $TARGET > $SOURCE", + emitter = e) + +def e2(target, source, env): + return (target + ['bar.foo'], source + ['bar.src']) + +# Simple association of a list of emitter functions with a Builder. +b = Builder("my_build < $TARGET > $SOURCE", + emitter = [e, e2]) + +# Calling an emitter function through a construction variable. +env = Environment(MY_EMITTER = e) +b = Builder("my_build < $TARGET > $SOURCE", + emitter = '$MY_EMITTER') + +# Calling a list of emitter functions through a construction variable. +env = Environment(EMITTER_LIST = [e, e2]) +b = Builder("my_build < $TARGET > $SOURCE", + emitter = '$EMITTER_LIST') + +# Associating multiple emitters with different file +# suffixes using a dictionary. +def e_suf1(target, source, env): + return (target + ['another_target_file'], source) +def e_suf2(target, source, env): + return (target, source + ['another_source_file']) +b = Builder("my_build < $TARGET > $SOURCE", + emitter = {'.suf1' : e_suf1, + '.suf2' : e_suf2}) +.EE + +.IP multi +Specifies whether this builder is allowed to be called multiple times for +the same target file(s). The default is 0, which means the builder +can not be called multiple times for the same target file(s). Calling a +builder multiple times for the same target simply adds additional source +files to the target; it is not allowed to change the environment associated +with the target, specify addition environment overrides, or associate a different +builder with the target. + +.IP env +A construction environment that can be used +to fetch source code using this Builder. +(Note that this environment is +.I not +used for normal builds of normal target files, +which use the environment that was +used to call the Builder for the target file.) + +.IP generator +A function that returns a list of actions that will be executed to build +the target(s) from the source(s). +The returned action(s) may be +an Action object, or anything that +can be converted into an Action object +(see the next section). + +The generator function +takes four arguments: +.I source +- a list of source nodes, +.I target +- a list of target nodes, +.I env +- the construction environment, +.I for_signature +- a Boolean value that specifies +whether the generator is being called +for generating a build signature +(as opposed to actually executing the command). +Example: + +.ES +def g(source, target, env, for_signature): + return [["gcc", "-c", "-o"] + target + source] + +b = Builder(generator=g) +.EE + +.IP +The +.I generator +and +.I action +arguments must not both be used for the same Builder. + +.IP src_builder +Specifies a builder to use when a source file name suffix does not match +any of the suffixes of the builder. Using this argument produces a +multi-stage builder. + +.IP single_source +Specifies that this builder expects exactly one source file per call. Giving +more than one source files without target files results in implicitely calling +the builder multiple times (once for each source given). Giving multiple +source files together with target files results in a UserError exception. + +.RE +.IP +The +.I generator +and +.I action +arguments must not both be used for the same Builder. + +.IP source_ext_match +When the specified +.I action +argument is a dictionary, +the default behavior when a builder is passed +multiple source files is to make sure that the +extensions of all the source files match. +If it is legal for this builder to be +called with a list of source files with different extensions, +this check can be suppressed by setting +.B source_ext_match +to +.B None +or some other non-true value. +When +.B source_ext_match +is disable, +.B scons +will use the suffix of the first specified +source file to select the appropriate action from the +.I action +dictionary. + +In the following example, +the setting of +.B source_ext_match +prevents +.B scons +from exiting with an error +due to the mismatched suffixes of +.B foo.in +and +.BR foo.extra . + +.ES +b = Builder(action={'.in' : 'build $SOURCES > $TARGET'}, + source_ext_match = None) + +env = Environment(BUILDERS = {'MyBuild':b}) +env.MyBuild('foo.out', ['foo.in', 'foo.extra']) +.EE + +.IP env +A construction environment that can be used +to fetch source code using this Builder. +(Note that this environment is +.I not +used for normal builds of normal target files, +which use the environment that was +used to call the Builder for the target file.) + +.ES +b = Builder(action="build < $SOURCE > $TARGET") +env = Environment(BUILDERS = {'MyBuild' : b}) +env.MyBuild('foo.out', 'foo.in', my_arg = 'xyzzy') +.EE + +.IP chdir +A directory from which scons +will execute the +action(s) specified +for this Builder. +If the +.B chdir +argument is +a string or a directory Node, +scons will change to the specified directory. +If the +.B chdir +is not a string or Node +and is non-zero, +then scons will change to the +target file's directory. + +Note that scons will +.I not +automatically modify +its expansion of +construction variables like +.B $TARGET +and +.B $SOURCE +when using the chdir +keyword argument--that is, +the expanded file names +will still be relative to +the top-level SConstruct directory, +and consequently incorrect +relative to the chdir directory. +Builders created using chdir keyword argument, +will need to use construction variable +expansions like +.B ${TARGET.file} +and +.B ${SOURCE.file} +to use just the filename portion of the +targets and source. + +.ES +b = Builder(action="build < ${SOURCE.file} > ${TARGET.file}", + chdir=1) +env = Environment(BUILDERS = {'MyBuild' : b}) +env.MyBuild('sub/dir/foo.out', 'sub/dir/foo.in') +.EE + +.B WARNING: +Python only keeps one current directory +location for all of the threads. +This means that use of the +.B chdir +argument +will +.I not +work with the SCons +.B -j +option, +because individual worker threads spawned +by SCons interfere with each other +when they start changing directory. + +.RE +Any additional keyword arguments supplied +when a Builder object is created +(that is, when the Builder() function is called) +will be set in the executing construction +environment when the Builder object is called. +The canonical example here would be +to set a construction variable to +the repository of a source code system. + +Any additional keyword arguments supplied +when a Builder +.I object +is called +will only be associated with the target +created by that particular Builder call +(and any other files built as a +result of the call). + +These extra keyword arguments are passed to the +following functions: +command generator functions, +function Actions, +and emitter functions. + +.SS Action Objects + +The +.BR Builder () +function will turn its +.B action +keyword argument into an appropriate +internal Action object. +You can also explicity create Action objects +using the +.BR Action () +global function, +which can then be passed to the +.BR Builder () +function. +This can be used to configure +an Action object more flexibly, +or it may simply be more efficient +than letting each separate Builder object +create a separate Action +when multiple +Builder objects need to do the same thing. + +The +.BR Action () +global function +returns an appropriate object for the action +represented by the type of the first argument: + +.IP Action +If the first argument is already an Action object, +the object is simply returned. + +.IP String +If the first argument is a string, +a command-line Action is returned. +Note that the command-line string +may be preceded by an +.B @ +(at-sign) +to suppress printing of the specified command line, +or by a +.B \- +(hyphen) +to ignore the exit status from the specified command: + +.ES +Action('$CC -c -o $TARGET $SOURCES') + +# Doesn't print the line being executed. +Action('@build $TARGET $SOURCES') + +# Ignores return value +Action('-build $TARGET $SOURCES') +.EE +.\" XXX From Gary Ruben, 23 April 2002: +.\" What would be useful is a discussion of how you execute command +.\" shell commands ie. what is the process used to spawn the shell, pass +.\" environment variables to it etc., whether there is one shell per +.\" environment or one per command etc. It might help to look at the Gnu +.\" make documentation to see what they think is important to discuss about +.\" a build system. I'm sure you can do a better job of organising the +.\" documentation than they have :-) + +.IP List +If the first argument is a list, +then a list of Action objects is returned. +An Action object is created as necessary +for each element in the list. +If an element +.I within +the list is itself a list, +the internal list is the +command and arguments to be executed via +the command line. +This allows white space to be enclosed +in an argument by defining +a command in a list within a list: + +.ES +Action([['cc', '-c', '-DWHITE SPACE', '-o', '$TARGET', '$SOURCES']]) +.EE + +.IP Function +If the first argument is a Python function, +a function Action is returned. +The Python function must take three keyword arguments, +.B target +(a Node object representing the target file), +.B source +(a Node object representing the source file) +and +.B env +(the construction environment +used for building the target file). +The +.B target +and +.B source +arguments may be lists of Node objects if there is +more than one target file or source file. +The actual target and source file name(s) may +be retrieved from their Node objects +via the built-in Python str() function: + +.ES +target_file_name = str(target) +source_file_names = map(lambda x: str(x), source) +.EE +.IP +The function should return +.B 0 +or +.B None +to indicate a successful build of the target file(s). +The function may raise an exception +or return a non-zero exit status +to indicate an unsuccessful build. + +.ES +def build_it(target = None, source = None, env = None): + # build the target from the source + return 0 + +a = Action(build_it) +.EE + +If the action argument is not one of the above, +None is returned. +.PP + +The second argument is optional and is used to define the output +which is printed when the Action is actually performed. +In the absence of this parameter, +or if it's an empty string, +a default output depending on the type of the action is used. +For example, a command-line action will print the executed command. +The argument must be either a Python function or a string. + +In the first case, +it's a function that returns a string to be printed +to describe the action being executed. +The function may also be specified by the +.IR strfunction = +keyword argument. +Like a function to build a file, +this function must take three keyword arguments: +.B target +(a Node object representing the target file), +.B source +(a Node object representing the source file) +and +.BR env +(a construction environment). +The +.B target +and +.B source +arguments may be lists of Node objects if there is +more than one target file or source file. + +In the second case, you provide the string itself. +The string may also be specified by the +.IR cmdstr = +keyword argument. +The string typically contains variables, notably +$TARGET(S) and $SOURCE(S), or consists of just a single +variable, which is optionally defined somewhere else. +SCons itself heavily uses the latter variant. + +Examples: + +.ES +def build_it(target, source, env): + # build the target from the source + return 0 + +def string_it(target, source, env): + return "building '%s' from '%s'" % (target[0], source[0]) + +# Use a positional argument. +f = Action(build_it, string_it) +s = Action(build_it, "building '$TARGET' from '$SOURCE'") + +# Alternatively, use a keyword argument. +f = Action(build_it, strfunction=string_it) +s = Action(build_it, cmdstr="building '$TARGET' from '$SOURCE'") + +# You can provide a configurable variable. +l = Action(build_it, '$STRINGIT') +.EE + +The third and succeeding arguments, if present, +may either be a construction variable or a list of construction variables +whose values will be included in the signature of the Action +when deciding whether a target should be rebuilt because the action changed. +The variables may also be specified by a +.IR varlist = +keyword parameter; +if both are present, they are combined. +This is necessary whenever you want a target to be rebuilt +when a specific construction variable changes. +This is not often needed for a string action, +as the expanded variables will normally be part of the command line, +but may be needed if a Python function action uses +the value of a construction variable when generating the command line. + +.ES +def build_it(target, source, env): + # build the target from the 'XXX' construction variable + open(target[0], 'w').write(env['XXX']) + return 0 + +# Use positional arguments. +a = Action(build_it, '$STRINGIT', ['XXX']) + +# Alternatively, use a keyword argument. +a = Action(build_it, varlist=['XXX']) +.EE + +The +.BR Action () +global function +can be passed the following +optional keyword arguments +to modify the Action object's behavior: + +.IP +.B chdir +The +.B chdir +keyword argument specifies that +scons will execute the action +after changing to the specified directory. +If the +.B chdir +argument is +a string or a directory Node, +scons will change to the specified directory. +If the +.B chdir +argument +is not a string or Node +and is non-zero, +then scons will change to the +target file's directory. + +Note that scons will +.I not +automatically modify +its expansion of +construction variables like +.B $TARGET +and +.B $SOURCE +when using the chdir +keyword argument--that is, +the expanded file names +will still be relative to +the top-level SConstruct directory, +and consequently incorrect +relative to the chdir directory. +Builders created using chdir keyword argument, +will need to use construction variable +expansions like +.B ${TARGET.file} +and +.B ${SOURCE.file} +to use just the filename portion of the +targets and source. + +.ES +a = Action("build < ${SOURCE.file} > ${TARGET.file}", + chdir=1) +.EE + +.IP +.B exitstatfunc +The +.BR Action () +global function +also takes an +.B exitstatfunc +keyword argument +which specifies a function +that is passed the exit status +(or return value) +from the specified action +and can return an arbitrary +or modified value. +This can be used, for example, +to specify that an Action object's +return value should be ignored +under special conditions +and SCons should, therefore, +consider that the action always suceeds: + +.ES +def always_succeed(s): + # Always return 0, which indicates success. + return 0 +a = Action("build < ${SOURCE.file} > ${TARGET.file}", + exitstatfunc=always_succeed) +.EE + +.IP +.B batch_key +The +.B batch_key +keyword argument can be used +to specify that the Action can create multiple target files +by processing multiple independent source files simultaneously. +(The canonical example is "batch compilation" +of multiple object files +by passing multiple source files +to a single invocation of a compiler +such as Microsoft's Visual C / C++ compiler.) +If the +.B batch_key +argument is any non-False, non-callable Python value, +the configured Action object will cause +.B scons +to collect all targets built with the Action object +and configured with the same construction environment +into single invocations of the Action object's +command line or function. +Command lines will typically want to use the +.BR CHANGED_SOURCES +construction variable +(and possibly +.BR CHANGED_TARGETS +as well) +to only pass to the command line those sources that +have actually changed since their targets were built. + +Example: + +.ES +a = Action('build $CHANGED_SOURCES', batch_key=True) +.EE + +The +.B batch_key +argument may also be +a callable function +that returns a key that +will be used to identify different +"batches" of target files to be collected +for batch building. +A +.B batch_key +function must take the following arguments: + +.IP action +The action object. + +.IP env +The construction environment +configured for the target. + +.IP target +The list of targets for a particular configured action. + +.IP source +The list of source for a particular configured action. + +The returned key should typically +be a tuple of values derived from the arguments, +using any appropriate logic to decide +how multiple invocations should be batched. +For example, a +.B batch_key +function may decide to return +the value of a specific construction +variable from the +.B env +argument +which will cause +.B scons +to batch-build targets +with matching values of that variable, +or perhaps return the +.BR id () +of the entire construction environment, +in which case +.B scons +will batch-build +all targets configured with the same construction environment. +Returning +.B None +indicates that +the particular target should +.I not +be part of any batched build, +but instead will be built +by a separate invocation of action's +command or function. +Example: + +.ES +def batch_key(action, env, target, source): + tdir = target[0].dir + if tdir.name == 'special': + # Don't batch-build any target + # in the special/ subdirectory. + return None + return (id(action), id(env), tdir) +a = Action('build $CHANGED_SOURCES', batch_key=batch_key) +.EE + +.SS Miscellaneous Action Functions + +.B scons +supplies a number of functions +that arrange for various common +file and directory manipulations +to be performed. +These are similar in concept to "tasks" in the +Ant build tool, +although the implementation is slightly different. +These functions do not actually +perform the specified action +at the time the function is called, +but instead return an Action object +that can be executed at the +appropriate time. +(In Object-Oriented terminology, +these are actually +Action +.I Factory +functions +that return Action objects.) + +In practice, +there are two natural ways +that these +Action Functions +are intended to be used. + +First, +if you need +to perform the action +at the time the SConscript +file is being read, +you can use the +.B Execute +global function to do so: +.ES +Execute(Touch('file')) +.EE + +Second, +you can use these functions +to supply Actions in a list +for use by the +.B Command +method. +This can allow you to +perform more complicated +sequences of file manipulation +without relying +on platform-specific +external commands: +that +.ES +env = Environment(TMPBUILD = '/tmp/builddir') +env.Command('foo.out', 'foo.in', + [Mkdir('$TMPBUILD'), + Copy('$TMPBUILD', '${SOURCE.dir}'), + "cd $TMPBUILD && make", + Delete('$TMPBUILD')]) +.EE + +.TP +.RI Chmod( dest ", " mode ) +Returns an Action object that +changes the permissions on the specified +.I dest +file or directory to the specified +.IR mode . +Examples: + +.ES +Execute(Chmod('file', 0755)) + +env.Command('foo.out', 'foo.in', + [Copy('$TARGET', '$SOURCE'), + Chmod('$TARGET', 0755)]) +.EE + +.TP +.RI Copy( dest ", " src ) +Returns an Action object +that will copy the +.I src +source file or directory to the +.I dest +destination file or directory. +Examples: + +.ES +Execute(Copy('foo.output', 'foo.input')) + +env.Command('bar.out', 'bar.in', + Copy('$TARGET', '$SOURCE')) +.EE + +.TP +.RI Delete( entry ", [" must_exist ]) +Returns an Action that +deletes the specified +.IR entry , +which may be a file or a directory tree. +If a directory is specified, +the entire directory tree +will be removed. +If the +.I must_exist +flag is set, +then a Python error will be thrown +if the specified entry does not exist; +the default is +.BR must_exist=0 , +that is, the Action will silently do nothing +if the entry does not exist. +Examples: + +.ES +Execute(Delete('/tmp/buildroot')) + +env.Command('foo.out', 'foo.in', + [Delete('${TARGET.dir}'), + MyBuildAction]) + +Execute(Delete('file_that_must_exist', must_exist=1)) +.EE + +.TP +.RI Mkdir( dir ) +Returns an Action +that creates the specified +directory +.I dir . +Examples: + +.ES +Execute(Mkdir('/tmp/outputdir')) + +env.Command('foo.out', 'foo.in', + [Mkdir('/tmp/builddir'), + Copy('/tmp/builddir/foo.in', '$SOURCE'), + "cd /tmp/builddir && make", + Copy('$TARGET', '/tmp/builddir/foo.out')]) +.EE + +.TP +.RI Move( dest ", " src ) +Returns an Action +that moves the specified +.I src +file or directory to +the specified +.I dest +file or directory. +Examples: + +.ES +Execute(Move('file.destination', 'file.source')) + +env.Command('output_file', 'input_file', + [MyBuildAction, + Move('$TARGET', 'file_created_by_MyBuildAction')]) +.EE + +.TP +.RI Touch( file ) +Returns an Action +that updates the modification time +on the specified +.IR file . +Examples: + +.ES +Execute(Touch('file_to_be_touched')) + +env.Command('marker', 'input_file', + [MyBuildAction, + Touch('$TARGET')]) +.EE + +.SS Variable Substitution + +Before executing a command, +.B scons +performs construction variable interpolation on the strings that make up +the command line of builders. +Variables are introduced by a +.B $ +prefix. +Besides construction variables, scons provides the following +variables for each command execution: + +.IP CHANGED_SOURCES +The file names of all sources of the build command +that have changed since the target was last built. + +.IP CHANGED_TARGETS +The file names of all targets that would be built +from sources that have changed since the target was last built. + +.IP SOURCE +The file name of the source of the build command, +or the file name of the first source +if multiple sources are being built. + +.IP SOURCES +The file names of the sources of the build command. + +.IP TARGET +The file name of the target being built, +or the file name of the first target +if multiple targets are being built. + +.IP TARGETS +The file names of all targets being built. + +.IP UNCHANGED_SOURCES +The file names of all sources of the build command +that have +.I not +changed since the target was last built. + +.IP UNCHANGED_TARGETS +The file names of all targets that would be built +from sources that have +.I not +changed since the target was last built. + +(Note that the above variables are reserved +and may not be set in a construction environment.) + +.LP +For example, given the construction variable CC='cc', targets=['foo'], and +sources=['foo.c', 'bar.c']: + +.ES +action='$CC -c -o $TARGET $SOURCES' +.EE + +would produce the command line: + +.ES +cc -c -o foo foo.c bar.c +.EE + +Variable names may be surrounded by curly braces ({}) +to separate the name from the trailing characters. +Within the curly braces, a variable name may have +a Python slice subscript appended to select one +or more items from a list. +In the previous example, the string: + +.ES +${SOURCES[1]} +.EE + +would produce: + +.ES +bar.c +.EE + +Additionally, a variable name may +have the following special +modifiers appended within the enclosing curly braces +to modify the interpolated string: + +.IP base +The base path of the file name, +including the directory path +but excluding any suffix. + +.IP dir +The name of the directory in which the file exists. + +.IP file +The file name, +minus any directory portion. + +.IP filebase +Just the basename of the file, +minus any suffix +and minus the directory. + +.IP suffix +Just the file suffix. + +.IP abspath +The absolute path name of the file. + +.IP posix +The POSIX form of the path, +with directories separated by +.B / +(forward slashes) +not backslashes. +This is sometimes necessary on Windows systems +when a path references a file on other (POSIX) systems. + +.IP srcpath +The directory and file name to the source file linked to this file through +.BR VariantDir (). +If this file isn't linked, +it just returns the directory and filename unchanged. + +.IP srcdir +The directory containing the source file linked to this file through +.BR VariantDir (). +If this file isn't linked, +it just returns the directory part of the filename. + +.IP rsrcpath +The directory and file name to the source file linked to this file through +.BR VariantDir (). +If the file does not exist locally but exists in a Repository, +the path in the Repository is returned. +If this file isn't linked, it just returns the +directory and filename unchanged. + +.IP rsrcdir +The Repository directory containing the source file linked to this file through +.BR VariantDir (). +If this file isn't linked, +it just returns the directory part of the filename. + +.LP +For example, the specified target will +expand as follows for the corresponding modifiers: + +.ES +$TARGET => sub/dir/file.x +${TARGET.base} => sub/dir/file +${TARGET.dir} => sub/dir +${TARGET.file} => file.x +${TARGET.filebase} => file +${TARGET.suffix} => .x +${TARGET.abspath} => /top/dir/sub/dir/file.x + +SConscript('src/SConscript', variant_dir='sub/dir') +$SOURCE => sub/dir/file.x +${SOURCE.srcpath} => src/file.x +${SOURCE.srcdir} => src + +Repository('/usr/repository') +$SOURCE => sub/dir/file.x +${SOURCE.rsrcpath} => /usr/repository/src/file.x +${SOURCE.rsrcdir} => /usr/repository/src +.EE + +Note that curly braces braces may also be used +to enclose arbitrary Python code to be evaluated. +(In fact, this is how the above modifiers are substituted, +they are simply attributes of the Python objects +that represent TARGET, SOURCES, etc.) +See the section "Python Code Substitution," below, +for more thorough examples of +how this can be used. + +Lastly, a variable name +may be a callable Python function +associated with a +construction variable in the environment. +The function should +take four arguments: +.I target +- a list of target nodes, +.I source +- a list of source nodes, +.I env +- the construction environment, +.I for_signature +- a Boolean value that specifies +whether the function is being called +for generating a build signature. +SCons will insert whatever +the called function returns +into the expanded string: + +.ES +def foo(target, source, env, for_signature): + return "bar" + +# Will expand $BAR to "bar baz" +env=Environment(FOO=foo, BAR="$FOO baz") +.EE + +You can use this feature to pass arguments to a +Python function by creating a callable class +that stores one or more arguments in an object, +and then uses them when the +.B __call__() +method is called. +Note that in this case, +the entire variable expansion must +be enclosed by curly braces +so that the arguments will +be associated with the +instantiation of the class: + +.ES +class foo: + def __init__(self, arg): + self.arg = arg + + def __call__(self, target, source, env, for_signature): + return self.arg + " bar" + +# Will expand $BAR to "my argument bar baz" +env=Environment(FOO=foo, BAR="${FOO('my argument')} baz") +.EE + +.LP +The special pseudo-variables +.B "$(" +and +.B "$)" +may be used to surround parts of a command line +that may change +.I without +causing a rebuild--that is, +which are not included in the signature +of target files built with this command. +All text between +.B "$(" +and +.B "$)" +will be removed from the command line +before it is added to file signatures, +and the +.B "$(" +and +.B "$)" +will be removed before the command is executed. +For example, the command line: + +.ES +echo Last build occurred $( $TODAY $). > $TARGET +.EE + +.LP +would execute the command: + +.ES +echo Last build occurred $TODAY. > $TARGET +.EE + +.LP +but the command signature added to any target files would be: + +.ES +echo Last build occurred . > $TARGET +.EE + +.SS Python Code Substitution + +Any python code within +.BR "${" - "}" +pairs gets evaluated by python 'eval', with the python globals set to +the current environment's set of construction variables. +So in the following case: +.ES +env['COND'] = 0 +env.Command('foo.out', 'foo.in', + '''echo ${COND==1 and 'FOO' or 'BAR'} > $TARGET''') +.EE +the command executed will be either +.ES +echo FOO > foo.out +.EE +or +.ES +echo BAR > foo.out +.EE +according to the current value of env['COND'] when the command is +executed. The evaluation occurs when the target is being +built, not when the SConscript is being read. So if env['COND'] is changed +later in the SConscript, the final value will be used. + +Here's a more interesting example. Note that all of COND, FOO, and +BAR are environment variables, and their values are substituted into +the final command. FOO is a list, so its elements are interpolated +separated by spaces. + +.ES +env=Environment() +env['COND'] = 0 +env['FOO'] = ['foo1', 'foo2'] +env['BAR'] = 'barbar' +env.Command('foo.out', 'foo.in', + 'echo ${COND==1 and FOO or BAR} > $TARGET') + +# Will execute this: +# echo foo1 foo2 > foo.out +.EE + +SCons uses the following rules when converting construction variables into +command lines: + +.IP String +When the value is a string it is interpreted as a space delimited list of +command line arguments. + +.IP List +When the value is a list it is interpreted as a list of command line +arguments. Each element of the list is converted to a string. + +.IP Other +Anything that is not a list or string is converted to a string and +interpreted as a single command line argument. + +.IP Newline +Newline characters (\\n) delimit lines. The newline parsing is done after +all other parsing, so it is not possible for arguments (e.g. file names) to +contain embedded newline characters. This limitation will likely go away in +a future version of SCons. + +.SS Scanner Objects + +You can use the +.B Scanner +function to define +objects to scan +new file types for implicit dependencies. +Scanner accepts the following arguments: + +.IP function +This can be either: +1) a Python function that will process +the Node (file) +and return a list of strings (file names) +representing the implicit +dependencies found in the contents; +or: +2) a dictionary that maps keys +(typically the file suffix, but see below for more discussion) +to other Scanners that should be called. + +If the argument is actually a Python function, +the function must take three or four arguments: + + def scanner_function(node, env, path): + + def scanner_function(node, env, path, arg=None): + +The +.B node +argument is the internal +SCons node representing the file. +Use +.B str(node) +to fetch the name of the file, and +.B node.get_contents() +to fetch contents of the file. +Note that the file is +.I not +guaranteed to exist before the scanner is called, +so the scanner function should check that +if there's any chance that the scanned file +might not exist +(for example, if it's built from other files). + +The +.B env +argument is the construction environment for the scan. +Fetch values from it using the +.B env.Dictionary() +method. + +The +.B path +argument is a tuple (or list) +of directories that can be searched +for files. +This will usually be the tuple returned by the +.B path_function +argument (see below). + +The +.B arg +argument is the argument supplied +when the scanner was created, if any. + +.IP name +The name of the Scanner. +This is mainly used +to identify the Scanner internally. + +.IP argument +An optional argument that, if specified, +will be passed to the scanner function +(described above) +and the path function +(specified below). + +.IP skeys +An optional list that can be used to +determine which scanner should be used for +a given Node. +In the usual case of scanning for file names, +this argument will be a list of suffixes +for the different file types that this +Scanner knows how to scan. +If the argument is a string, +then it will be expanded +into a list by the current environment. + +.IP path_function +A Python function that takes four or five arguments: +a construction environment, +a Node for the directory containing +the SConscript file in which +the first target was defined, +a list of target nodes, +a list of source nodes, +and an optional argument supplied +when the scanner was created. +The +.B path_function +returns a tuple of directories +that can be searched for files to be returned +by this Scanner object. +(Note that the +.BR FindPathDirs () +function can be used to return a ready-made +.B path_function +for a given construction variable name, +instead of having to write your own function from scratch.) + +.IP node_class +The class of Node that should be returned +by this Scanner object. +Any strings or other objects returned +by the scanner function +that are not of this class +will be run through the +.B node_factory +function. + +.IP node_factory +A Python function that will take a string +or other object +and turn it into the appropriate class of Node +to be returned by this Scanner object. + +.IP scan_check +An optional Python function that takes two arguments, +a Node (file) and a construction environment, +and returns whether the +Node should, in fact, +be scanned for dependencies. +This check can be used to eliminate unnecessary +calls to the scanner function when, +for example, the underlying file +represented by a Node does not yet exist. + +.IP recursive +An optional flag that +specifies whether this scanner should be re-invoked +on the dependency files returned by the scanner. +When this flag is not set, +the Node subsystem will +only invoke the scanner on the file being scanned, +and not (for example) also on the files +specified by the #include lines +in the file being scanned. +.I recursive +may be a callable function, +in which case it will be called with a list of +Nodes found and +should return a list of Nodes +that should be scanned recursively; +this can be used to select a specific subset of +Nodes for additional scanning. + +Note that +.B scons +has a global +.B SourceFileScanner +object that is used by +the +.BR Object (), +.BR SharedObject (), +and +.BR StaticObject () +builders to decide +which scanner should be used +for different file extensions. +You can using the +.BR SourceFileScanner.add_scanner () +method to add your own Scanner object +to the +.B scons +infrastructure +that builds target programs or +libraries from a list of +source files of different types: + +.ES +def xyz_scan(node, env, path): + contents = node.get_text_contents() + # Scan the contents and return the included files. + +XYZScanner = Scanner(xyz_scan) + +SourceFileScanner.add_scanner('.xyx', XYZScanner) + +env.Program('my_prog', ['file1.c', 'file2.f', 'file3.xyz']) +.EE + +.SH SYSTEM-SPECIFIC BEHAVIOR +SCons and its configuration files are very portable, +due largely to its implementation in Python. +There are, however, a few portability +issues waiting to trap the unwary. +.SS .C file suffix +SCons handles the upper-case +.B .C +file suffix differently, +depending on the capabilities of +the underlying system. +On a case-sensitive system +such as Linux or UNIX, +SCons treats a file with a +.B .C +suffix as a C++ source file. +On a case-insensitive system +such as Windows, +SCons treats a file with a +.B .C +suffix as a C source file. +.SS .F file suffix +SCons handles the upper-case +.B .F +file suffix differently, +depending on the capabilities of +the underlying system. +On a case-sensitive system +such as Linux or UNIX, +SCons treats a file with a +.B .F +suffix as a Fortran source file +that is to be first run through +the standard C preprocessor. +On a case-insensitive system +such as Windows, +SCons treats a file with a +.B .F +suffix as a Fortran source file that should +.I not +be run through the C preprocessor. +.SS Windows: Cygwin Tools and Cygwin Python vs. Windows Pythons +Cygwin supplies a set of tools and utilities +that let users work on a +Windows system using a more POSIX-like environment. +The Cygwin tools, including Cygwin Python, +do this, in part, +by sharing an ability to interpret UNIX-like path names. +For example, the Cygwin tools +will internally translate a Cygwin path name +like /cygdrive/c/mydir +to an equivalent Windows pathname +of C:/mydir (equivalent to C:\\mydir). + +Versions of Python +that are built for native Windows execution, +such as the python.org and ActiveState versions, +do not have the Cygwin path name semantics. +This means that using a native Windows version of Python +to build compiled programs using Cygwin tools +(such as gcc, bison, and flex) +may yield unpredictable results. +"Mixing and matching" in this way +can be made to work, +but it requires careful attention to the use of path names +in your SConscript files. + +In practice, users can sidestep +the issue by adopting the following rules: +When using gcc, +use the Cygwin-supplied Python interpreter +to run SCons; +when using Microsoft Visual C/C++ +(or some other Windows compiler) +use the python.org or ActiveState version of Python +to run SCons. +.SS Windows: scons.bat file +On Windows systems, +SCons is executed via a wrapper +.B scons.bat +file. +This has (at least) two ramifications: + +First, Windows command-line users +that want to use variable assignment +on the command line +may have to put double quotes +around the assignments: + +.ES +scons "FOO=BAR" "BAZ=BLEH" +.EE + +Second, the Cygwin shell does not +recognize this file as being the same +as an +.B scons +command issued at the command-line prompt. +You can work around this either by +executing +.B scons.bat +from the Cygwin command line, +or by creating a wrapper shell +script named +.B scons . + +.SS MinGW + +The MinGW bin directory must be in your PATH environment variable or the +PATH variable under the ENV construction variable for SCons +to detect and use the MinGW tools. When running under the native Windows +Python interpreter, SCons will prefer the MinGW tools over the Cygwin +tools, if they are both installed, regardless of the order of the bin +directories in the PATH variable. If you have both MSVC and MinGW +installed and you want to use MinGW instead of MSVC, +then you must explictly tell SCons to use MinGW by passing + +.ES +tools=['mingw'] +.EE + +to the Environment() function, because SCons will prefer the MSVC tools +over the MinGW tools. + +.SH EXAMPLES + +To help you get started using SCons, +this section contains a brief overview of some common tasks. + +.SS Basic Compilation From a Single Source File + +.ES +env = Environment() +env.Program(target = 'foo', source = 'foo.c') +.EE + +Note: Build the file by specifying +the target as an argument +("scons foo" or "scons foo.exe"). +or by specifying a dot ("scons ."). + +.SS Basic Compilation From Multiple Source Files + +.ES +env = Environment() +env.Program(target = 'foo', source = Split('f1.c f2.c f3.c')) +.EE + +.SS Setting a Compilation Flag + +.ES +env = Environment(CCFLAGS = '-g') +env.Program(target = 'foo', source = 'foo.c') +.EE + +.SS Search The Local Directory For .h Files + +Note: You do +.I not +need to set CCFLAGS to specify -I options by hand. +SCons will construct the right -I options from CPPPATH. + +.ES +env = Environment(CPPPATH = ['.']) +env.Program(target = 'foo', source = 'foo.c') +.EE + +.SS Search Multiple Directories For .h Files + +.ES +env = Environment(CPPPATH = ['include1', 'include2']) +env.Program(target = 'foo', source = 'foo.c') +.EE + +.SS Building a Static Library + +.ES +env = Environment() +env.StaticLibrary(target = 'foo', source = Split('l1.c l2.c')) +env.StaticLibrary(target = 'bar', source = ['l3.c', 'l4.c']) +.EE + +.SS Building a Shared Library + +.ES +env = Environment() +env.SharedLibrary(target = 'foo', source = ['l5.c', 'l6.c']) +env.SharedLibrary(target = 'bar', source = Split('l7.c l8.c')) +.EE + +.SS Linking a Local Library Into a Program + +.ES +env = Environment(LIBS = 'mylib', LIBPATH = ['.']) +env.Library(target = 'mylib', source = Split('l1.c l2.c')) +env.Program(target = 'prog', source = ['p1.c', 'p2.c']) +.EE + +.SS Defining Your Own Builder Object + +Notice that when you invoke the Builder, +you can leave off the target file suffix, +and SCons will add it automatically. + +.ES +bld = Builder(action = 'pdftex < $SOURCES > $TARGET' + suffix = '.pdf', + src_suffix = '.tex') +env = Environment(BUILDERS = {'PDFBuilder' : bld}) +env.PDFBuilder(target = 'foo.pdf', source = 'foo.tex') + +# The following creates "bar.pdf" from "bar.tex" +env.PDFBuilder(target = 'bar', source = 'bar') +.EE + +Note also that the above initialization +overwrites the default Builder objects, +so the Environment created above +can not be used call Builders like env.Program(), +env.Object(), env.StaticLibrary(), etc. + +.SS Adding Your Own Builder Object to an Environment + +.ES +bld = Builder(action = 'pdftex < $SOURCES > $TARGET' + suffix = '.pdf', + src_suffix = '.tex') +env = Environment() +env.Append(BUILDERS = {'PDFBuilder' : bld}) +env.PDFBuilder(target = 'foo.pdf', source = 'foo.tex') +env.Program(target = 'bar', source = 'bar.c') +.EE + +You also can use other Pythonic techniques to add +to the BUILDERS construction variable, such as: + +.ES +env = Environment() +env['BUILDERS]['PDFBuilder'] = bld +.EE + +.SS Defining Your Own Scanner Object + +The following example shows an extremely simple scanner (the +.BR kfile_scan () +function) +that doesn't use a search path at all +and simply returns the +file names present on any +.B include +lines in the scanned file. +This would implicitly assume that all included +files live in the top-level directory: + +.ES +import re + +'\" Note: the \\ in the following are for the benefit of nroff/troff, +'\" not inappropriate doubled escape characters within the r'' raw string. +include_re = re.compile(r'^include\\s+(\\S+)$', re.M) + +def kfile_scan(node, env, path, arg): + contents = node.get_text_contents() + includes = include_re.findall(contents) + return includes + +kscan = Scanner(name = 'kfile', + function = kfile_scan, + argument = None, + skeys = ['.k']) +scanners = Environment().Dictionary('SCANNERS') +env = Environment(SCANNERS = scanners + [kscan]) + +env.Command('foo', 'foo.k', 'kprocess < $SOURCES > $TARGET') + +bar_in = File('bar.in') +env.Command('bar', bar_in, 'kprocess $SOURCES > $TARGET') +bar_in.target_scanner = kscan +.EE + +Here is a similar but more complete example that searches +a path of directories +(specified as the +.B MYPATH +construction variable) +for files that actually exist: + +.ES +include_re = re.compile(r'^include\\s+(\\S+)$', re.M) + +def my_scan(node, env, path, arg): + contents = node.get_text_contents() + includes = include_re.findall(contents) + if includes == []: + return [] + results = [] + for inc in includes: + for dir in path: + file = dir + os.sep + inc + if os.path.exists(file): + results.append(file) + break + return results + +scanner = Scanner(name = 'myscanner', + function = my_scan, + argument = None, + skeys = ['.x'], + path_function = FindPathDirs('MYPATH'), + ) +scanners = Environment().Dictionary('SCANNERS') +env = Environment(SCANNERS = scanners + [scanner]) +.EE + +The +.BR FindPathDirs () +function used in the previous example returns a function +(actually a callable Python object) +that will return a list of directories +specified in the +.B $MYPATH +construction variable. +If you need to customize how the search path is derived, +you would provide your own +.B path_function +argument when creating the Scanner object, +as follows: + +.ES +# MYPATH is a list of directories to search for files in +def pf(env, dir, target, source, arg): + top_dir = Dir('#').abspath + results = [] + if 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 +SConscript +file are relative to that subdirectory. + +.ES +SConstruct: + + env = Environment() + env.Program(target = 'foo', source = 'foo.c') + + SConscript('sub/SConscript') + +sub/SConscript: + + env = Environment() + # Builds sub/foo from sub/foo.c + env.Program(target = 'foo', source = 'foo.c') + + SConscript('dir/SConscript') + +sub/dir/SConscript: + + env = Environment() + # Builds sub/dir/foo from sub/dir/foo.c + env.Program(target = 'foo', source = 'foo.c') +.EE + +.SS Sharing Variables Between SConscript Files + +You must explicitly Export() and Import() variables that +you want to share between SConscript files. + +.ES +SConstruct: + + env = Environment() + env.Program(target = 'foo', source = 'foo.c') + + Export("env") + SConscript('subdirectory/SConscript') + +subdirectory/SConscript: + + Import("env") + env.Program(target = 'foo', source = 'foo.c') +.EE + +.SS Building Multiple Variants From the Same Source + +Use the variant_dir keyword argument to +the SConscript function to establish +one or more separate variant build directory trees +for a given source directory: + +.ES +SConstruct: + + cppdefines = ['FOO'] + Export("cppdefines") + SConscript('src/SConscript', variant_dir='foo') + + cppdefines = ['BAR'] + Export("cppdefines") + SConscript('src/SConscript', variant_dir='bar') + +src/SConscript: + + Import("cppdefines") + env = Environment(CPPDEFINES = cppdefines) + env.Program(target = 'src', source = 'src.c') +.EE + +Note the use of the Export() method +to set the "cppdefines" variable to a different +value each time we call the SConscript function. + +.SS Hierarchical Build of Two Libraries Linked With a Program + +.ES +SConstruct: + + env = Environment(LIBPATH = ['#libA', '#libB']) + Export('env') + SConscript('libA/SConscript') + SConscript('libB/SConscript') + SConscript('Main/SConscript') + +libA/SConscript: + + Import('env') + env.Library('a', Split('a1.c a2.c a3.c')) + +libB/SConscript: + + Import('env') + env.Library('b', Split('b1.c b2.c b3.c')) + +Main/SConscript: + + Import('env') + e = env.Copy(LIBS = ['a', 'b']) + e.Program('foo', Split('m1.c m2.c m3.c')) +.EE + +The '#' in the LIBPATH directories specify that they're relative to the +top-level directory, so they don't turn into "Main/libA" when they're +used in Main/SConscript. + +Specifying only 'a' and 'b' for the library names +allows SCons to append the appropriate library +prefix and suffix for the current platform +(for example, 'liba.a' on POSIX systems, +\&'a.lib' on Windows). + +.SS Customizing construction variables from the command line. + +The following would allow the C compiler to be specified on the command +line or in the file custom.py. + +.ES +vars = Variables('custom.py') +vars.Add('CC', 'The C compiler.') +env = Environment(variables=vars) +Help(vars.GenerateHelpText(env)) +.EE + +The user could specify the C compiler on the command line: + +.ES +scons "CC=my_cc" +.EE + +or in the custom.py file: + +.ES +CC = 'my_cc' +.EE + +or get documentation on the options: + +.ES +$ scons -h + +CC: The C compiler. + default: None + actual: cc + +.EE + +.SS Using Microsoft Visual C++ precompiled headers + +Since windows.h includes everything and the kitchen sink, it can take quite +some time to compile it over and over again for a bunch of object files, so +Microsoft provides a mechanism to compile a set of headers once and then +include the previously compiled headers in any object file. This +technology is called precompiled headers. The general recipe is to create a +file named "StdAfx.cpp" that includes a single header named "StdAfx.h", and +then include every header you want to precompile in "StdAfx.h", and finally +include "StdAfx.h" as the first header in all the source files you are +compiling to object files. For example: + +StdAfx.h: +.ES +#include <windows.h> +#include <my_big_header.h> +.EE + +StdAfx.cpp: +.ES +#include <StdAfx.h> +.EE + +Foo.cpp: +.ES +#include <StdAfx.h> + +/* do some stuff */ +.EE + +Bar.cpp: +.ES +#include <StdAfx.h> + +/* do some other stuff */ +.EE + +SConstruct: +.ES +env=Environment() +env['PCHSTOP'] = 'StdAfx.h' +env['PCH'] = env.PCH('StdAfx.cpp')[0] +env.Program('MyApp', ['Foo.cpp', 'Bar.cpp']) +.EE + +For more information see the document for the PCH builder, and the PCH and +PCHSTOP construction variables. To learn about the details of precompiled +headers consult the MSDN documention for /Yc, /Yu, and /Yp. + +.SS Using Microsoft Visual C++ external debugging information + +Since including debugging information in programs and shared libraries can +cause their size to increase significantly, Microsoft provides a mechanism +for including the debugging information in an external file called a PDB +file. SCons supports PDB files through the PDB construction +variable. + +SConstruct: +.ES +env=Environment() +env['PDB'] = 'MyApp.pdb' +env.Program('MyApp', ['Foo.cpp', 'Bar.cpp']) +.EE + +For more information see the document for the PDB construction variable. + +.SH ENVIRONMENT + +.IP SCONS_LIB_DIR +Specifies the directory that contains the SCons Python module directory +(e.g. /home/aroach/scons-src-0.01/src/engine). + +.IP SCONSFLAGS +A string of options that will be used by scons in addition to those passed +on the command line. + +.SH "SEE ALSO" +.B scons +User Manual, +.B scons +Design Document, +.B scons +source code. + +.SH AUTHORS +Steven Knight <knight@baldmt.com> +.br +Anthony Roach <aroach@electriceyeball.com> + |