diff options
Diffstat (limited to 'debian/patches/manpages.patch')
| -rw-r--r-- | debian/patches/manpages.patch | 17138 |
1 files changed, 17138 insertions, 0 deletions
diff --git a/debian/patches/manpages.patch b/debian/patches/manpages.patch new file mode 100644 index 0000000..88414d2 --- /dev/null +++ b/debian/patches/manpages.patch @@ -0,0 +1,17138 @@ +Description: Restore man pages from version 2.3.0 +Author: Luca Falavigna <dktrkranz@debian.org> + +Index: scons/scons-time.1 +=================================================================== +--- /dev/null 1970-01-01 00:00:00.000000000 +0000 ++++ scons/scons-time.1 2014-04-26 12:12:55.641711527 +0200 +@@ -0,0 +1,1017 @@ ++.\" Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013 The SCons Foundation ++.\" ++.\" Permission is hereby granted, free of charge, to any person obtaining ++.\" a copy of this software and associated documentation files (the ++.\" "Software"), to deal in the Software without restriction, including ++.\" without limitation the rights to use, copy, modify, merge, publish, ++.\" distribute, sublicense, and/or sell copies of the Software, and to ++.\" permit persons to whom the Software is furnished to do so, subject to ++.\" the following conditions: ++.\" ++.\" The above copyright notice and this permission notice shall be included ++.\" in all copies or substantial portions of the Software. ++.\" ++.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY ++.\" KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE ++.\" WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND ++.\" NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE ++.\" LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION ++.\" OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION ++.\" WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. ++.\" ++.\" doc/man/scons-time.1 2013/03/03 09:48:35 garyo ++.\" ++.\" ES - Example Start - indents and turns off line fill ++.de ES ++.RS ++.nf ++.. ++.\" EE - Example End - ends indent and turns line fill back on ++.de EE ++.RE ++.fi ++.. ++'\"========================================================================== ++.de SF ++.B scons-time func ++[\fB-h\fR] ++[\fB--chdir=\fIDIR\fR] ++[\fB-f \fIFILE\fR] ++[\fB--fmt=\fIFORMAT\fR] ++[\fB--func=\fINAME\fR] ++[\fB-p \fISTRING\fR] ++[\fB-t \fINUMBER\fR] ++[\fB--title= TITLE\fR] ++[\fIARGUMENTS\fR] ++.. ++'\"-------------------------------------------------------------------------- ++.de SY ++.B scons-time mem ++[\fB-h\fR] ++[\fB--chdir=\fIDIR\fR] ++[\fB-f \fIFILE\fR] ++[\fB--fmt=\fIFORMAT\fR] ++[\fB-p \fISTRING\fR] ++[\fB--stage=\fISTAGE\fR] ++[\fB-t \fINUMBER\fR] ++[\fB--title=\fITITLE\fR] ++[\fIARGUMENTS\fR] ++.. ++'\"-------------------------------------------------------------------------- ++.de SO ++.B scons-time obj ++[\fB-h\fR] ++[\fB--chdir=\fIDIR\fR] ++[\fB-f \fIFILE\fR] ++[\fB--fmt=\fIFORMAT\fR] ++[\fB-p \fISTRING\fR] ++[\fB--stage=\fISTAGE\fR] ++[\fB-t \fINUMBER\fR] ++[\fB--title=\fITITLE\fR] ++[\fIARGUMENTS\fR] ++.. ++'\"-------------------------------------------------------------------------- ++.de SR ++.B scons-time run ++[\fB-hnqv\fR] ++[\fB--aegis=\fIPROJECT\fR] ++[\fB-f \fIFILE\fR] ++[\fB--number=\fINUMBER\fR] ++[\fB--outdir=\fIOUTDIR\fR] ++[\fB-p \fISTRING\fR] ++[\fB--python=\fIPYTHON\fR] ++[\fB-s \fIDIR\fR] ++[\fB--scons=\fISCONS\fR] ++[\fB--svn=\fIURL\fR] ++[\fIARGUMENTS\fR] ++.. ++'\"-------------------------------------------------------------------------- ++.de ST ++.B scons-time time ++[\fB-h\fR] ++[\fB--chdir=\fIDIR\fR] ++[\fB-f \fIFILE\fR] ++[\fB--fmt=\fIFORMAT\fR] ++[\fB-p \fISTRING\fR] ++[\fB-t \fINUMBER\fR] ++[\fB--title=\fITITLE\fR] ++[\fB--which=\fIWHICH\fR] ++[\fIARGUMENTS\fR] ++.. ++.TH SCONS-TIME 1 "March 2013" ++.SH NAME ++scons-time \- generate and display SCons timing information ++'\"========================================================================== ++.SH SYNOPSIS ++.B scons-time ++.IR subcommand ++[ ++.IR options ... ++] ++[ ++.IR arguments ... ++] ++'\"-------------------------------------------------------------------------- ++.SS "Generating Timing Information" ++.SR ++'\"-------------------------------------------------------------------------- ++.SS "Extracting Function Timings" ++.SF ++'\"-------------------------------------------------------------------------- ++.SS "Extracting Memory Statistics" ++.SY ++'\"-------------------------------------------------------------------------- ++.SS "Extracting Object Counts" ++.SO ++'\"-------------------------------------------------------------------------- ++.SS "Extracting Execution Times" ++.ST ++'\"-------------------------------------------------------------------------- ++.SS "Help Text" ++.B scons-time help ++.I SUBCOMMAND ++[...] ++'\"========================================================================== ++.SH DESCRIPTION ++The ++.B scons-time ++command runs an SCons configuration ++through a standard set of profiled timings ++and can extract and graph information from the ++resulting profiles and log files of those timings. ++The action to be performed by the ++.B scons-time ++script is specified ++by a subcommand, the first argument on the command line. ++See the ++.B SUBCOMMANDS ++section below for information about the operation ++of specific subcommands. ++.P ++The basic way to use ++.B scons-time ++is to run the ++.B scons-time run ++subcommand ++(possibly multiple times) ++to generate profile and log file output, ++and then use one of the other ++subcommands to display the results ++captured in the profiles and log files ++for a particular kind of information: ++function timings ++(the ++.B scons-time func ++subcommand), ++total memory used ++(the ++.B scons-time mem ++subcommand), ++object counts ++(the ++.B scons-time obj ++subcommand) ++and overall execution time ++(the ++.B scons-time time ++subcommand). ++Options exist to place and find the ++profiles and log files in separate directories, ++to generate the output in a format suitable ++for graphing with the ++.BR gnuplot (1) ++program, ++and so on. ++.P ++There are two basic ways the ++.B scons-time run ++subcommand ++is intended to be used ++to gather timing statistics ++for a configuration. ++One is to use the ++.B --svn= ++option to test a configuration against ++a list of revisions from the SCons Subversion repository. ++This will generate a profile and timing log file ++for every revision listed with the ++.B --number= ++option, ++and can be used to look at the ++impact of commited changes to the ++SCons code base on a particular ++configuration over time. ++.P ++The other way is to profile incremental changes to a ++local SCons code base during a development cycle--that is, ++to look at the performance impact of changes ++you're making in the local tree. ++In this mode, ++you run the ++.B scons-time run ++subcommand ++.I without ++the ++.B --svn= ++option, ++in which case it simply looks in the profile/log file output directory ++(the current directory by default) ++and automatically figures out the ++.I next ++run number for the output profile and log file. ++Used in this way, ++the development cycle goes something like: ++make a change to SCons; ++run ++.B scons-time run ++to profile it against a specific configuration; ++make another change to SCons; ++run ++.B scons-time run ++again to profile it; ++etc. ++'\"========================================================================== ++.SH OPTIONS ++The ++.B scons-time ++command only supports a few global options: ++.TP ++-h, --help ++Displays the global help text and exits, ++identical to the ++.B scons-time help ++subcommand. ++.TP ++-V, --version ++Displays the ++.B scons-time ++version and exits. ++.P ++Most functionality is controlled by options ++to the individual subcommands. ++See the next section for information ++about individual subcommand options. ++'\"========================================================================== ++.SH SUBCOMMANDS ++The ++.B scons-time ++command supports the following ++individual subcommands. ++'\"-------------------------------------------------------------------------- ++.SS "The func Subcommand" ++.SF ++.P ++The ++.B scons-time func ++subcommand displays timing information ++for a specific Python function within SCons. ++By default, it extracts information about the ++.BR _main () ++function, ++which includes the Python profiler timing ++for all of SCons. ++.P ++The ++.B scons-time func ++subcommand extracts function timing information ++from all the specified file arguments, ++which should be Python profiler output files. ++(Normally, these would be ++.B *.prof ++files generated by the ++.B scons-time run ++subcommand, ++but they can actually be generated ++by any Python profiler invocation.) ++All file name arguments will be ++globbed for on-disk files. ++.P ++If no arguments are specified, ++then function timing information ++will be extracted from all ++.B *.prof ++files, ++or the subset of them ++with a prefix specified by the ++.B -p ++option. ++.P ++Options include: ++.TP ++-C DIRECTORY, --chdir=DIRECTORY ++Changes to the specified ++.I DIRECTORY ++before looking for the specified files ++(or files that match the specified patterns). ++.TP ++-f FILE, --file=FILE ++Reads configuration information from the specified ++.IR FILE . ++.TP ++-fmt=FORMAT, --format=FORMAT ++Reports the output in the specified ++.IR FORMAT . ++The formats currently supported are ++.B ascii ++(the default) ++and ++.BR gnuplot . ++.TP ++--func=NAME ++Extracts timings for the specified function ++.IR NAME . ++The default is to report cumulative timings for the ++.BR _main () ++function, ++which contains the entire SCons run. ++.TP ++-h, --help ++Displays help text for the ++.B scons-time func ++subcommand. ++.TP ++-p STRING, --prefix=STRING ++Specifies the prefix string for profiles ++from which to extract function timing information. ++This will be used to search for profiles ++if no arguments are specified on the command line. ++.TP ++-t NUMBER, --tail=NUMBER ++Only extracts function timings from the last ++.I NUMBER ++files. ++'\"-------------------------------------------------------------------------- ++.SS "The help Subcommand" ++.B scons-time help ++.I SUBCOMMAND ++[...] ++The ++.B help ++subcommand prints help text for any ++other subcommands listed as later arguments on the command line. ++'\"-------------------------------------------------------------------------- ++.SS "The mem Subcommand" ++.SY ++.P ++The ++.B scons-time mem ++subcommand displays how much memory SCons uses. ++.P ++The ++.B scons-time mem ++subcommand extracts memory use information ++from all the specified file arguments, ++which should be files containing output from ++running SCons with the ++.B --debug=memory ++option. ++(Normally, these would be ++.B *.log ++files generated by the ++.B scons-time run ++subcommand.) ++All file name arguments will be ++globbed for on-disk files. ++.P ++If no arguments are specified, ++then memory information ++will be extracted from all ++.B *.log ++files, ++or the subset of them ++with a prefix specified by the ++.B -p ++option. ++.P ++.TP ++-C DIR, --chdir=DIR ++Changes to the specified ++.I DIRECTORY ++before looking for the specified files ++(or files that match the specified patterns). ++.TP ++-f FILE, --file=FILE ++Reads configuration information from the specified ++.IR FILE . ++.TP ++-fmt=FORMAT, --format=FORMAT ++Reports the output in the specified ++.IR FORMAT . ++The formats currently supported are ++.B ascii ++(the default) ++and ++.BR gnuplot . ++.TP ++-h, --help ++Displays help text for the ++.B scons-time mem ++subcommand. ++.TP ++-p STRING, --prefix=STRING ++Specifies the prefix string for log files ++from which to extract memory usage information. ++This will be used to search for log files ++if no arguments are specified on the command line. ++.TP ++--stage=STAGE ++Prints the memory used at the end of the specified ++.IR STAGE : ++.B pre-read ++(before the SConscript files are read), ++.B post-read , ++(after the SConscript files are read), ++.B pre-build ++(before any targets are built) ++or ++.B post-build ++(after any targets are built). ++If no ++.B --stage ++option is specified, ++the default behavior is ++.BR post-build , ++which reports the final amount of memory ++used by SCons during each run. ++.TP ++-t NUMBER, --tail=NUMBER ++Only reports memory statistics from the last ++.I NUMBER ++files. ++'\"-------------------------------------------------------------------------- ++.SS "The obj Subcommand" ++.SO ++.P ++The ++.B scons-time obj ++subcommand displays how many objects of a specific named type ++are created by SCons. ++.P ++The ++.B scons-time obj ++subcommand extracts object counts ++from all the specified file arguments, ++which should be files containing output from ++running SCons with the ++.B --debug=count ++option. ++(Normally, these would be ++.B *.log ++files generated by the ++.B scons-time run ++subcommand.) ++All file name arguments will be ++globbed for on-disk files. ++.P ++If no arguments are specified, ++then object counts ++will be extracted from all ++.B *.log ++files, ++or the subset of them ++with a prefix specified by the ++.B -p ++option. ++.TP ++-C DIR, --chdir=DIR ++Changes to the specified ++.I DIRECTORY ++before looking for the specified files ++(or files that match the specified patterns). ++.TP ++-f FILE, --file=FILE ++Reads configuration information from the specified ++.IR FILE . ++.TP ++-fmt=FORMAT, --format=FORMAT ++Reports the output in the specified ++.IR FORMAT . ++The formats currently supported are ++.B ascii ++(the default) ++and ++.BR gnuplot . ++.TP ++-h, --help ++Displays help text for the ++.B scons-time obj ++subcommand. ++.TP ++-p STRING, --prefix=STRING ++Specifies the prefix string for log files ++from which to extract object counts. ++This will be used to search for log files ++if no arguments are specified on the command line. ++.TP ++--stage=STAGE ++Prints the object count at the end of the specified ++.IR STAGE : ++.B pre-read ++(before the SConscript files are read), ++.B post-read , ++(after the SConscript files are read), ++.B pre-build ++(before any targets are built) ++or ++.B post-build ++(after any targets are built). ++If no ++.B --stage ++option is specified, ++the default behavior is ++.BR post-build , ++which reports the final object count during each run. ++.TP ++-t NUMBER, --tail=NUMBER ++Only reports object counts from the last ++.I NUMBER ++files. ++'\"-------------------------------------------------------------------------- ++.SS "The run Subcommand" ++.SR ++The ++.B scons-time run ++subcommand is the basic subcommand ++for profiling a specific configuration ++against a version of SCons. ++.P ++The configuration to be tested ++is specified as a list of files ++or directories that will be unpacked or copied ++into a temporary directory ++in which SCons will be invoked. ++The ++.B scons-time run ++subcommand understands file suffixes like ++.BR .tar , ++.BR .tar.gz , ++.BR .tgz ++and ++.BR .zip ++and will unpack their contents into a temporary directory. ++If more than one argument is specified, ++each one will be unpacked or copied ++into the temporary directory "on top of" ++the previous archives or directories, ++so the expectation is that multiple ++specified archives share the same directory layout. ++.P ++Once the file or directory arguments are unpacked or ++copied to the temporary directory, ++the ++.B scons-time run ++subcommand runs the ++requested version of SCons ++against the configuration ++three times: ++.TP ++Startup ++SCons is run with the ++.B --help ++option so that just the SConscript files are read, ++and then the default help text is printed. ++This profiles just the perceived "overhead" of starting up SCons ++and processing the SConscript files. ++.TP ++Full build ++SCons is run to build everything specified in the configuration. ++Specific targets to be passed in on the command l ine ++may be specified by the ++.B targets ++keyword in a configuration file; see below for details. ++.TP ++Rebuild ++SCons is run again on the same just-built directory. ++If the dependencies in the SCons configuration are correct, ++this should be an up-to-date, "do nothing" rebuild. ++.P ++Each invocation captures the output log file and a profile. ++.P ++The ++.B scons-time run ++subcommand supports the following options: ++.TP ++--aegis=PROJECT ++Specifies the Aegis ++.I PROJECT ++from which the ++version(s) of ++.B scons ++being timed will be extracted. ++When ++.B --aegis ++is specified, the ++.BI --number= NUMBER ++option specifies delta numbers ++that will be tested. ++Output from each invocation run will be placed in file ++names that match the Aegis delta numbers. ++If the ++.B --number= ++option is not specified, ++then the default behavior is to time the ++tip of the specified ++.IR PROJECT . ++.TP ++-f FILE, --file=FILE ++Reads configuration information from the specified ++.IR FILE . ++This often provides a more convenient way to specify and ++collect parameters associated with a specific timing configuration ++than specifying them on the command line. ++See the ++.B CONFIGURATION FILE ++section below ++for information about the configuration file parameters. ++.TP ++-h, --help ++Displays help text for the ++.B scons-time run ++subcommand. ++.TP ++-n, --no-exec ++Do not execute commands, ++just printing the command-line equivalents of what would be executed. ++Note that the ++.B scons-time ++script actually executes its actions in Python, ++where possible, ++for portability. ++The commands displayed are UNIX ++.I equivalents ++of what it's doing. ++.TP ++--number=NUMBER ++Specifies the run number to be used in the names of ++the log files and profile outputs generated by this run. ++.IP ++When used in conjuction with the ++.BI --aegis= PROJECT ++option, ++.I NUMBER ++specifies one or more comma-separated Aegis delta numbers ++that will be retrieved automatically from the specified Aegis ++.IR PROJECT . ++.IP ++When used in conjuction with the ++.BI --svn= URL ++option, ++.I NUMBER ++specifies one or more comma-separated Subversion revision numbers ++that will be retrieved automatically from the Subversion ++repository at the specified ++.IR URL . ++Ranges of delta or revision numbers ++may be specified be separating two numbers ++with a hyphen ++.RB ( \- ). ++.P ++Example: ++.ES ++% scons-time run --svn=http://scons.tigris.org/svn/trunk --num=1247,1249-1252 . ++.EE ++.TP ++-p STRING, --prefix=STRING ++Specifies the prefix string to be used for all of the log files ++and profiles generated by this run. ++The default is derived from the first ++specified argument: ++if the first argument is a directory, ++the default prefix is the name of the directory; ++if the first argument is an archive ++(tar or zip file), ++the default prefix is the the base name of the archive, ++that is, what remains after stripping the archive suffix ++.RB ( .tgz ", " .tar.gz " or " .zip ). ++.TP ++--python=PYTHON ++Specifies a path to the Python executable to be used ++for the timing runs. ++The default is to use the same Python executable that ++is running the ++.B scons-time ++command itself. ++.TP ++-q, --quiet ++Suppresses display of the command lines being executed. ++.TP ++-s DIR, --subdir=DIR ++Specifies the name of directory or subdirectory ++from which the commands should be executed. ++The default is XXX ++.TP ++--scons=SCONS ++Specifies a path to the SCons script to be used ++for the timing runs. ++The default is XXX ++.TP ++--svn=URL, --subversion=URL ++Specifies the ++.I URL ++of the Subversion repository from which the ++version(s) of ++.B scons ++being timed will be extracted. ++When ++.B --svn ++is specified, the ++.BI --number= NUMBER ++option specifies revision numbers ++that will be tested. ++Output from each invocation run will be placed in file ++names that match the Subversion revision numbers. ++If the ++.B --number= ++option is not specified, ++then the default behavior is to time the ++.B HEAD ++of the specified ++.IR URL . ++.TP ++-v, --verbose ++Displays the output from individual commands to the screen ++(in addition to capturing the output in log files). ++'\"-------------------------------------------------------------------------- ++.SS "The time Subcommand" ++.ST ++.P ++The ++.B scons-time time ++subcommand displays SCons execution times ++as reported by the ++.B scons --debug=time ++option. ++.P ++The ++.B scons-time time ++subcommand extracts SCons timing ++from all the specified file arguments, ++which should be files containing output from ++running SCons with the ++.B --debug=time ++option. ++(Normally, these would be ++.B *.log ++files generated by the ++.B scons-time run ++subcommand.) ++All file name arguments will be ++globbed for on-disk files. ++.P ++If no arguments are specified, ++then execution timings ++will be extracted from all ++.B *.log ++files, ++or the subset of them ++with a prefix specified by the ++.B -p ++option. ++.TP ++-C DIR, --chdir=DIR ++Changes to the specified ++.I DIRECTORY ++before looking for the specified files ++(or files that match the specified patterns). ++.TP ++-f FILE, --file=FILE ++Reads configuration information from the specified ++.IR FILE . ++.TP ++-fmt=FORMAT, --format=FORMAT ++Reports the output in the specified ++.IR FORMAT . ++The formats currently supported are ++.B ascii ++(the default) ++and ++.BR gnuplot . ++.TP ++-h, --help ++Displays help text for the ++.B scons-time time ++subcommand. ++.TP ++-p STRING, --prefix=STRING ++Specifies the prefix string for log files ++from which to extract execution timings. ++This will be used to search for log files ++if no arguments are specified on the command line. ++.TP ++-t NUMBER, --tail=NUMBER ++Only reports object counts from the last ++.I NUMBER ++files. ++.TP ++--which=WHICH ++Prints the execution time for the specified ++.IR WHICH ++value: ++.B total ++(the total execution time), ++.B SConscripts ++(total execution time for the SConscript files themselves), ++.B SCons ++(exectuion time in SCons code itself) ++or ++.B commands ++(execution time of the commands and other actions ++used to build targets). ++If no ++.B --which ++option is specified, ++the default behavior is ++.BR total , ++which reports the total execution time for each run. ++'\"========================================================================== ++.SH CONFIGURATION FILE ++Various ++.B scons-time ++subcommands can read information from a specified ++configuration file when passed the ++.B \-f ++or ++.B \--file ++options. ++The configuration file is actually executed as a Python script. ++Setting Python variables in the configuration file ++controls the behavior of the ++.B scons-time ++script more conveniently than having to specify ++command-line options or arguments for every run, ++and provides a handy way to "shrink-wrap" ++the necessary information for producing (and reporting) ++consistent timing runs for a given configuration. ++.TP ++.B aegis ++The Aegis executable for extracting deltas. ++The default is simply ++.BR aegis . ++.TP ++.B aegis_project ++The Aegis project from which deltas should be extracted. ++The default is whatever is specified ++with the ++.B --aegis= ++command-line option. ++.TP ++.B archive_list ++A list of archives (files or directories) ++that will be copied to the temporary directory ++in which SCons will be invoked. ++.BR .tar , ++.BR .tar.gz , ++.BR .tgz ++and ++.BR .zip ++files will have their contents unpacked in ++the temporary directory. ++Directory trees and files will be copied as-is. ++.TP ++.B initial_commands ++A list of commands that will be executed ++before the actual timed ++.B scons ++runs. ++This can be used for commands that are necessary ++to prepare the source tree\-for example, ++creating a configuration file ++that should not be part of the timed run. ++.TP ++.B key_location ++The location of the key on Gnuplot graphing information ++generated with the ++.BR --format=gnuplot ++option. ++The default is ++.BR "bottom left" . ++.TP ++.B prefix ++The file name prefix to be used when ++running or extracting timing for this configuration. ++.TP ++.B python ++The path name of the Python executable ++to be used when running or extracting information ++for this configuration. ++The default is the same version of Python ++used to run the SCons ++.TP ++.B scons ++The path name of the SCons script to be used ++when running or extracting information ++for this configuration. ++The default is simply ++.BR scons . ++.TP ++.B scons_flags ++The ++.B scons ++flags used when running SCons to collect timing information. ++The default value is ++.BR "--debug=count --debug=memory --debug=time --debug=memoizer" . ++.TP ++.B scons_lib_dir ++.TP ++.B scons_wrapper ++.TP ++.B startup_targets ++.TP ++.B subdir ++The subdirectory of the project into which the ++.B scons-time ++script should change ++before executing the SCons commands to time. ++.TP ++.B subversion_url ++The Subversion URL from ++.TP ++.B svn ++The subversion executable used to ++check out revisions of SCons to be timed. ++The default is simple ++.BR svn . ++.TP ++.B svn_co_flag ++.TP ++.B tar ++.TP ++.B targets ++A string containing the targets that should be added to ++the command line of every timed ++.B scons ++run. ++This can be used to restrict what's being timed to a ++subset of the full build for the configuration. ++.TP ++.B targets0 ++.TP ++.B targets1 ++.TP ++.B targets2 ++.TP ++.B title ++.TP ++.B unzip ++.TP ++.B verbose ++.TP ++.B vertical_bars ++'\"-------------------------------------------------------------------------- ++.SS Example ++Here is an example ++.B scons-time ++configuration file ++for a hypothetical sample project: ++.P ++.ES ++# The project doesn't use SCons natively (yet), so we're ++# timing a separate set of SConscript files that we lay ++# on top of the vanilla unpacked project tarball. ++arguments = ['project-1.2.tgz', 'project-SConscripts.tar'] ++ ++# The subdirectory name contains the project version number, ++# so tell scons-time to chdir there before building. ++subdir = 'project-1.2' ++ ++# Set the prefix so output log files and profiles are named: ++# project-000-[012].{log,prof} ++# project-001-[012].{log,prof} ++# etc. ++prefix = 'project' ++ ++# The SConscript files being tested don't do any SConf ++# configuration, so run their normal ./configure script ++# before we invoke SCons. ++initial_commands = [ ++ './configure', ++] ++ ++# Only time building the bin/project executable. ++targets = 'bin/project' ++ ++# Time against SCons revisions of the branches/core branch ++subversion_url = 'http://scons.tigris.org/svn/scons/branches/core' ++.EE ++'\"========================================================================== ++.SH ENVIRONMENT ++The ++.B scons-time ++script uses the following environment variables: ++.TP ++.B PRESERVE ++If this value is set, ++the ++.B scons-time ++script will ++.I not ++remove the temporary directory or directories ++in which it builds the specified configuration ++or downloads a specific version of SCons. ++'\"========================================================================== ++.SH "SEE ALSO" ++.BR gnuplot (1), ++.BR scons (1) ++ ++.SH AUTHORS ++Steven Knight <knight at baldmt dot com> +Index: scons/scons.1 +=================================================================== +--- /dev/null 1970-01-01 00:00:00.000000000 +0000 ++++ scons/scons.1 2014-04-26 12:12:44.853737230 +0200 +@@ -0,0 +1,15895 @@ ++.\" Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013 The SCons Foundation ++.\" ++.\" Permission is hereby granted, free of charge, to any person obtaining ++.\" a copy of this software and associated documentation files (the ++.\" "Software"), to deal in the Software without restriction, including ++.\" without limitation the rights to use, copy, modify, merge, publish, ++.\" distribute, sublicense, and/or sell copies of the Software, and to ++.\" permit persons to whom the Software is furnished to do so, subject to ++.\" the following conditions: ++.\" ++.\" The above copyright notice and this permission notice shall be included ++.\" in all copies or substantial portions of the Software. ++.\" ++.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY ++.\" KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE ++.\" WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND ++.\" NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE ++.\" LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION ++.\" OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION ++.\" WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. ++.\" ++.\" doc/man/scons.1 2013/03/03 09:48:35 garyo ++.\" ++.TH SCONS 1 "March 2013" ++.\" ES - Example Start - indents and turns off line fill ++.rm ES ++.de ES ++.RS ++.nf ++.. ++.\" EE - Example End - ends indent and turns line fill back on ++.rm EE ++.de EE ++.fi ++.RE ++.. ++.SH NAME ++scons \- a software construction tool ++.SH SYNOPSIS ++.B scons ++[ ++.IR options ... ++] ++[ ++.IR name = val ... ++] ++[ ++.IR targets ... ++] ++.SH DESCRIPTION ++ ++The ++.B scons ++utility builds software (or other files) by determining which ++component pieces must be rebuilt and executing the necessary commands to ++rebuild them. ++ ++By default, ++.B scons ++searches for a file named ++.IR SConstruct , ++.IR Sconstruct , ++or ++.I sconstruct ++(in that order) in the current directory and reads its ++configuration from the first file found. ++An alternate file name may be ++specified via the ++.B -f ++option. ++ ++The ++.I SConstruct ++file can specify subsidiary ++configuration files using the ++.BR SConscript () ++function. ++By convention, ++these subsidiary files are named ++.IR SConscript , ++although any name may be used. ++(Because of this naming convention, ++the term "SConscript files" ++is sometimes used to refer ++generically to all ++.B scons ++configuration files, ++regardless of actual file name.) ++ ++The configuration files ++specify the target files to be built, and ++(optionally) the rules to build those targets. Reasonable default ++rules exist for building common software components (executable ++programs, object files, libraries), so that for most software ++projects, only the target and input files need be specified. ++ ++Before reading the ++.I SConstruct ++file, ++.B scons ++looks for a directory named ++.I site_scons ++in various system directories (see below) and the directory containing the ++.I SConstruct ++file; for each of those dirs which exists, ++.I site_scons ++is prepended to sys.path, ++the file ++.IR site_scons/site_init.py , ++is evaluated if it exists, ++and the directory ++.I site_scons/site_tools ++is prepended to the default toolpath if it exists. ++See the ++.I --no-site-dir ++and ++.I --site-dir ++options for more details. ++ ++.B scons ++reads and executes the SConscript files as Python scripts, ++so you may use normal Python scripting capabilities ++(such as flow control, data manipulation, and imported Python libraries) ++to handle complicated build situations. ++.BR scons , ++however, reads and executes all of the SConscript files ++.I before ++it begins building any targets. ++To make this obvious, ++.B scons ++prints the following messages about what it is doing: ++ ++.ES ++$ scons foo.out ++scons: Reading SConscript files ... ++scons: done reading SConscript files. ++scons: Building targets ... ++cp foo.in foo.out ++scons: done building targets. ++$ ++.EE ++ ++The status messages ++(everything except the line that reads "cp foo.in foo.out") ++may be suppressed using the ++.B -Q ++option. ++ ++.B scons ++does not automatically propagate ++the external environment used to execute ++.B scons ++to the commands used to build target files. ++This is so that builds will be guaranteed ++repeatable regardless of the environment ++variables set at the time ++.B scons ++is invoked. ++This also means that if the compiler or other commands ++that you want to use to build your target files ++are not in standard system locations, ++.B scons ++will not find them unless ++you explicitly set the PATH ++to include those locations. ++Whenever you create an ++.B scons ++construction environment, ++you can propagate the value of PATH ++from your external environment as follows: ++ ++.ES ++import os ++env = Environment(ENV = {'PATH' : os.environ['PATH']}) ++.EE ++ ++Similarly, if the commands use external environment variables ++like $PATH, $HOME, $JAVA_HOME, $LANG, $SHELL, $TERM, etc., ++these variables can also be explicitly propagated: ++ ++.ES ++import os ++env = Environment(ENV = {'PATH' : os.environ['PATH'], ++ 'HOME' : os.environ['HOME']}) ++.EE ++ ++Or you may explicitly propagate the invoking user's ++complete external environment: ++ ++.ES ++import os ++env = Environment(ENV = os.environ) ++.EE ++ ++This comes at the expense of making your build ++dependent on the user's environment being set correctly, ++but it may be more convenient for many configurations. ++ ++.B scons ++can scan known input files automatically for dependency ++information (for example, #include statements ++in C or C++ files) and will rebuild dependent files appropriately ++whenever any "included" input file changes. ++.B scons ++supports the ++ability to define new scanners for unknown input file types. ++ ++.B scons ++knows how to fetch files automatically from ++SCCS or RCS subdirectories ++using SCCS, RCS or BitKeeper. ++ ++.B scons ++is normally executed in a top-level directory containing a ++.I SConstruct ++file, optionally specifying ++as command-line arguments ++the target file or files to be built. ++ ++By default, the command ++ ++.ES ++scons ++.EE ++ ++will build all target files in or below the current directory. ++Explicit default targets ++(to be built when no targets are specified on the command line) ++may be defined the SConscript file(s) ++using the ++.B Default() ++function, described below. ++ ++Even when ++.B Default() ++targets are specified in the SConscript file(s), ++all target files in or below the current directory ++may be built by explicitly specifying ++the current directory (.) ++as a command-line target: ++ ++.ES ++scons . ++.EE ++ ++Building all target files, ++including any files outside of the current directory, ++may be specified by supplying a command-line target ++of the root directory (on POSIX systems): ++ ++.ES ++scons / ++.EE ++ ++or the path name(s) of the volume(s) in which all the targets ++should be built (on Windows systems): ++ ++.ES ++scons C:\\ D:\\ ++.EE ++ ++To build only specific targets, ++supply them as command-line arguments: ++ ++.ES ++scons foo bar ++.EE ++ ++in which case only the specified targets will be built ++(along with any derived files on which they depend). ++ ++Specifying "cleanup" targets in SConscript files is not usually necessary. ++The ++.B -c ++flag removes all files ++necessary to build the specified target: ++ ++.ES ++scons -c . ++.EE ++ ++to remove all target files, or: ++ ++.ES ++scons -c build export ++.EE ++ ++to remove target files under build and export. ++Additional files or directories to remove can be specified using the ++.BR Clean() ++function. ++Conversely, targets that would normally be removed by the ++.B -c ++invocation ++can be prevented from being removed by using the ++.BR NoClean () ++function. ++ ++A subset of a hierarchical tree may be built by ++remaining at the top-level directory (where the ++.I SConstruct ++file lives) and specifying the subdirectory as the target to be ++built: ++ ++.ES ++scons src/subdir ++.EE ++ ++or by changing directory and invoking scons with the ++.B -u ++option, which traverses up the directory ++hierarchy until it finds the ++.I SConstruct ++file, and then builds ++targets relatively to the current subdirectory: ++ ++.ES ++cd src/subdir ++scons -u . ++.EE ++ ++.B scons ++supports building multiple targets in parallel via a ++.B -j ++option that takes, as its argument, the number ++of simultaneous tasks that may be spawned: ++ ++.ES ++scons -j 4 ++.EE ++ ++builds four targets in parallel, for example. ++ ++.B scons ++can maintain a cache of target (derived) files that can ++be shared between multiple builds. When caching is enabled in a ++SConscript file, any target files built by ++.B scons ++will be copied ++to the cache. If an up-to-date target file is found in the cache, it ++will be retrieved from the cache instead of being rebuilt locally. ++Caching behavior may be disabled and controlled in other ways by the ++.BR --cache-force , ++.BR --cache-disable , ++and ++.B --cache-show ++command-line options. The ++.B --random ++option is useful to prevent multiple builds ++from trying to update the cache simultaneously. ++ ++Values of variables to be passed to the SConscript file(s) ++may be specified on the command line: ++ ++.ES ++scons debug=1 . ++.EE ++ ++These variables are available in SConscript files ++through the ARGUMENTS dictionary, ++and can be used in the SConscript file(s) to modify ++the build in any way: ++ ++.ES ++if ARGUMENTS.get('debug', 0): ++ env = Environment(CCFLAGS = '-g') ++else: ++ env = Environment() ++.EE ++ ++The command-line variable arguments are also available ++in the ARGLIST list, ++indexed by their order on the command line. ++This allows you to process them in order rather than by name, ++if necessary. ++ARGLIST[0] returns a tuple ++containing (argname, argvalue). ++A Python exception is thrown if you ++try to access a list member that ++does not exist. ++ ++.B scons ++requires Python version 2.4 or later. ++There should be no other dependencies or requirements to run ++.B scons. ++ ++.\" The following paragraph reflects the default tool search orders ++.\" currently in SCons/Tool/__init__.py. If any of those search orders ++.\" change, this documentation should change, too. ++By default, ++.B scons ++knows how to search for available programming tools ++on various systems. ++On Windows systems, ++.B scons ++searches in order for the ++Microsoft Visual C++ tools, ++the MinGW tool chain, ++the Intel compiler tools, ++and the PharLap ETS compiler. ++On OS/2 systems, ++.B scons ++searches in order for the ++OS/2 compiler, ++the GCC tool chain, ++and the Microsoft Visual C++ tools, ++On SGI IRIX, IBM AIX, Hewlett Packard HP-UX, and Sun Solaris systems, ++.B scons ++searches for the native compiler tools ++(MIPSpro, Visual Age, aCC, and Forte tools respectively) ++and the GCC tool chain. ++On all other platforms, ++including POSIX (Linux and UNIX) platforms, ++.B scons ++searches in order ++for the GCC tool chain, ++the Microsoft Visual C++ tools, ++and the Intel compiler tools. ++You may, of course, override these default values ++by appropriate configuration of ++Environment construction variables. ++ ++.SH OPTIONS ++In general, ++.B scons ++supports the same command-line options as GNU ++.BR make , ++and many of those supported by ++.BR cons . ++ ++.TP ++-b ++Ignored for compatibility with non-GNU versions of ++.BR make. ++ ++.TP ++-c, --clean, --remove ++Clean up by removing all target files for which a construction ++command is specified. ++Also remove any files or directories associated to the construction command ++using the ++.BR Clean () ++function. ++Will not remove any targets specified by the ++.BR NoClean () ++function. ++ ++.TP ++.RI --cache-debug= file ++Print debug information about the ++.BR CacheDir () ++derived-file caching ++to the specified ++.IR file . ++If ++.I file ++is ++.B \- ++(a hyphen), ++the debug information are printed to the standard output. ++The printed messages describe what signature file names are ++being looked for in, retrieved from, or written to the ++.BR CacheDir () ++directory tree. ++ ++.TP ++--cache-disable, --no-cache ++Disable the derived-file caching specified by ++.BR CacheDir (). ++.B scons ++will neither retrieve files from the cache ++nor copy files to the cache. ++ ++.TP ++--cache-force, --cache-populate ++When using ++.BR CacheDir (), ++populate a cache by copying any already-existing, up-to-date ++derived files to the cache, ++in addition to files built by this invocation. ++This is useful to populate a new cache with ++all the current derived files, ++or to add to the cache any derived files ++recently built with caching disabled via the ++.B --cache-disable ++option. ++ ++.TP ++--cache-show ++When using ++.BR CacheDir () ++and retrieving a derived file from the cache, ++show the command ++that would have been executed to build the file, ++instead of the usual report, ++"Retrieved `file' from cache." ++This will produce consistent output for build logs, ++regardless of whether a target ++file was rebuilt or retrieved from the cache. ++ ++.TP ++.RI --config= mode ++This specifies how the ++.B Configure ++call should use or generate the ++results of configuration tests. ++The option should be specified from ++among the following choices: ++ ++.TP ++--config=auto ++scons will use its normal dependency mechanisms ++to decide if a test must be rebuilt or not. ++This saves time by not running the same configuration tests ++every time you invoke scons, ++but will overlook changes in system header files ++or external commands (such as compilers) ++if you don't specify those dependecies explicitly. ++This is the default behavior. ++ ++.TP ++--config=force ++If this option is specified, ++all configuration tests will be re-run ++regardless of whether the ++cached results are out of date. ++This can be used to explicitly ++force the configuration tests to be updated ++in response to an otherwise unconfigured change ++in a system header file or compiler. ++ ++.TP ++--config=cache ++If this option is specified, ++no configuration tests will be rerun ++and all results will be taken from cache. ++Note that scons will still consider it an error ++if --config=cache is specified ++and a necessary test does not ++yet have any results in the cache. ++ ++.TP ++.RI "-C" " directory" ", --directory=" directory ++Change to the specified ++.I directory ++before searching for the ++.IR SConstruct , ++.IR Sconstruct , ++or ++.I sconstruct ++file, or doing anything ++else. Multiple ++.B -C ++options are interpreted ++relative to the previous one, and the right-most ++.B -C ++option wins. (This option is nearly ++equivalent to ++.BR "-f directory/SConstruct" , ++except that it will search for ++.IR SConstruct , ++.IR Sconstruct , ++or ++.I sconstruct ++in the specified directory.) ++ ++.\" .TP ++.\" -d ++.\" Display dependencies while building target files. Useful for ++.\" figuring out why a specific file is being rebuilt, as well as ++.\" general debugging of the build process. ++ ++.TP ++-D ++Works exactly the same way as the ++.B -u ++option except for the way default targets are handled. ++When this option is used and no targets are specified on the command line, ++all default targets are built, whether or not they are below the current ++directory. ++ ++.TP ++.RI --debug= type ++Debug the build process. ++.I type ++specifies what type of debugging: ++ ++.TP ++--debug=count ++Print how many objects are created ++of the various classes used internally by SCons ++before and after reading the SConscript files ++and before and after building targets. ++This is not supported when SCons is executed with the Python ++.B -O ++(optimized) option ++or when the SCons modules ++have been compiled with optimization ++(that is, when executing from ++.B *.pyo ++files). ++ ++.TP ++--debug=duplicate ++Print a line for each unlink/relink (or copy) of a variant file from ++its source file. Includes debugging info for unlinking stale variant ++files, as well as unlinking old targets before building them. ++ ++.TP ++--debug=dtree ++A synonym for the newer ++.B --tree=derived ++option. ++This will be deprecated in some future release ++and ultimately removed. ++ ++.TP ++--debug=explain ++Print an explanation of precisely why ++.B scons ++is deciding to (re-)build any targets. ++(Note: this does not print anything ++for targets that are ++.I not ++rebuilt.) ++ ++.TP ++--debug=findlibs ++Instruct the scanner that searches for libraries ++to print a message about each potential library ++name it is searching for, ++and about the actual libraries it finds. ++ ++.TP ++--debug=includes ++Print the include tree after each top-level target is built. ++This is generally used to find out what files are included by the sources ++of a given derived file: ++ ++.ES ++$ scons --debug=includes foo.o ++.EE ++ ++.TP ++--debug=memoizer ++Prints a summary of hits and misses using the Memoizer, ++an internal subsystem that counts ++how often SCons uses cached values in memory ++instead of recomputing them each time they're needed. ++ ++.TP ++--debug=memory ++Prints how much memory SCons uses ++before and after reading the SConscript files ++and before and after building targets. ++ ++.TP ++--debug=nomemoizer ++A deprecated option preserved for backwards compatibility. ++ ++.TP ++--debug=objects ++Prints a list of the various objects ++of the various classes used internally by SCons. ++ ++.TP ++--debug=pdb ++Re-run SCons under the control of the ++.RI pdb ++Python debugger. ++ ++.TP ++--debug=prepare ++Print a line each time any target (internal or external) ++is prepared for building. ++.B scons ++prints this for each target it considers, even if that ++target is up to date (see also --debug=explain). ++This can help debug problems with targets that aren't being ++built; it shows whether ++.B scons ++is at least considering them or not. ++ ++.TP ++--debug=presub ++Print the raw command line used to build each target ++before the construction environment variables are substituted. ++Also shows which targets are being built by this command. ++Output looks something like this: ++.ES ++$ scons --debug=presub ++Building myprog.o with action(s): ++ $SHCC $SHCFLAGS $SHCCFLAGS $CPPFLAGS $_CPPINCFLAGS -c -o $TARGET $SOURCES ++\&... ++.EE ++ ++.TP ++--debug=stacktrace ++Prints an internal Python stack trace ++when encountering an otherwise unexplained error. ++ ++.TP ++--debug=stree ++A synonym for the newer ++.B --tree=all,status ++option. ++This will be deprecated in some future release ++and ultimately removed. ++ ++.TP ++--debug=time ++Prints various time profiling information: ++the time spent executing each individual build command; ++the total build time (time SCons ran from beginning to end); ++the total time spent reading and executing SConscript files; ++the total time spent SCons itself spend running ++(that is, not counting reading and executing SConscript files); ++and both the total time spent executing all build commands ++and the elapsed wall-clock time spent executing those build commands. ++(When ++.B scons ++is executed without the ++.B -j ++option, ++the elapsed wall-clock time will typically ++be slightly longer than the total time spent ++executing all the build commands, ++due to the SCons processing that takes place ++in between executing each command. ++When ++.B scons ++is executed ++.I with ++the ++.B -j ++option, ++and your build configuration allows good parallelization, ++the elapsed wall-clock time should ++be significantly smaller than the ++total time spent executing all the build commands, ++since multiple build commands and ++intervening SCons processing ++should take place in parallel.) ++ ++.TP ++--debug=tree ++A synonym for the newer ++.B --tree=all ++option. ++This will be deprecated in some future release ++and ultimately removed. ++ ++.TP ++.RI --diskcheck= types ++Enable specific checks for ++whether or not there is a file on disk ++where the SCons configuration expects a directory ++(or vice versa), ++and whether or not RCS or SCCS sources exist ++when searching for source and include files. ++The ++.I types ++argument can be set to: ++.BR all , ++to enable all checks explicitly ++(the default behavior); ++.BR none , ++to disable all such checks; ++.BR match , ++to check that files and directories on disk ++match SCons' expected configuration; ++.BR rcs , ++to check for the existence of an RCS source ++for any missing source or include files; ++.BR sccs , ++to check for the existence of an SCCS source ++for any missing source or include files. ++Multiple checks can be specified separated by commas; ++for example, ++.B --diskcheck=sccs,rcs ++would still check for SCCS and RCS sources, ++but disable the check for on-disk matches of files and directories. ++Disabling some or all of these checks ++can provide a performance boost for large configurations, ++or when the configuration will check for files and/or directories ++across networked or shared file systems, ++at the slight increased risk of an incorrect build ++or of not handling errors gracefully ++(if include files really should be ++found in SCCS or RCS, for example, ++or if a file really does exist ++where the SCons configuration expects a directory). ++ ++.TP ++.RI --duplicate= ORDER ++There are three ways to duplicate files in a build tree: hard links, ++soft (symbolic) links and copies. The default behaviour of SCons is to ++prefer hard links to soft links to copies. You can specify different ++behaviours with this option. ++.IR ORDER ++must be one of ++.IR hard-soft-copy ++(the default), ++.IR soft-hard-copy , ++.IR hard-copy , ++.IR soft-copy ++or ++.IR copy . ++SCons will attempt to duplicate files using ++the mechanisms in the specified order. ++ ++.\" .TP ++.\" -e, --environment-overrides ++.\" Variables from the execution environment override construction ++.\" variables from the SConscript files. ++ ++.TP ++.RI -f " file" ", --file=" file ", --makefile=" file ", --sconstruct=" file ++Use ++.I file ++as the initial SConscript file. ++Multiple ++.B -f ++options may be specified, ++in which case ++.B scons ++will read all of the specified files. ++ ++.TP ++-h, --help ++Print a local help message for this build, if one is defined in ++the SConscript file(s), plus a line that describes the ++.B -H ++option for command-line option help. If no local help message ++is defined, prints the standard help message about command-line ++options. Exits after displaying the appropriate message. ++ ++.TP ++-H, --help-options ++Print the standard help message about command-line options and ++exit. ++ ++.TP ++-i, --ignore-errors ++Ignore all errors from commands executed to rebuild files. ++ ++.TP ++.RI -I " directory" ", --include-dir=" directory ++Specifies a ++.I directory ++to search for ++imported Python modules. If several ++.B -I ++options ++are used, the directories are searched in the order specified. ++ ++.TP ++--implicit-cache ++Cache implicit dependencies. ++This causes ++.B scons ++to use the implicit (scanned) dependencies ++from the last time it was run ++instead of scanning the files for implicit dependencies. ++This can significantly speed up SCons, ++but with the following limitations: ++.IP ++.B scons ++will not detect changes to implicit dependency search paths ++(e.g. ++.BR CPPPATH ", " LIBPATH ) ++that would ordinarily ++cause different versions of same-named files to be used. ++.IP ++.B scons ++will miss changes in the implicit dependencies ++in cases where a new implicit ++dependency is added earlier in the implicit dependency search path ++(e.g. ++.BR CPPPATH ", " LIBPATH ) ++than a current implicit dependency with the same name. ++ ++.TP ++--implicit-deps-changed ++Forces SCons to ignore the cached implicit dependencies. This causes the ++implicit dependencies to be rescanned and recached. This implies ++.BR --implicit-cache . ++ ++.TP ++--implicit-deps-unchanged ++Force SCons to ignore changes in the implicit dependencies. ++This causes cached implicit dependencies to always be used. ++This implies ++.BR --implicit-cache . ++ ++.TP ++--interactive ++Starts SCons in interactive mode. ++The SConscript files are read once and a ++.B "scons>>>" ++prompt is printed. ++Targets may now be rebuilt by typing commands at interactive prompt ++without having to re-read the SConscript files ++and re-initialize the dependency graph from scratch. ++ ++SCons interactive mode supports the following commands: ++ ++.RS 10 ++.TP 6 ++.BI build "[OPTIONS] [TARGETS] ..." ++Builds the specified ++.I TARGETS ++(and their dependencies) ++with the specified ++SCons command-line ++.IR OPTIONS . ++.B b ++and ++.B scons ++are synonyms. ++ ++The following SCons command-line options affect the ++.B build ++command: ++ ++.ES ++--cache-debug=FILE ++--cache-disable, --no-cache ++--cache-force, --cache-populate ++--cache-show ++--debug=TYPE ++-i, --ignore-errors ++-j N, --jobs=N ++-k, --keep-going ++-n, --no-exec, --just-print, --dry-run, --recon ++-Q ++-s, --silent, --quiet ++--taskmastertrace=FILE ++--tree=OPTIONS ++.EE ++ ++.IP "" 6 ++Any other SCons command-line options that are specified ++do not cause errors ++but have no effect on the ++.B build ++command ++(mainly because they affect how the SConscript files are read, ++which only happens once at the beginning of interactive mode). ++ ++.TP 6 ++.BI clean "[OPTIONS] [TARGETS] ..." ++Cleans the specified ++.I TARGETS ++(and their dependencies) ++with the specified options. ++.B c ++is a synonym. ++This command is itself a synonym for ++.B "build --clean" ++ ++.TP 6 ++.BI exit ++Exits SCons interactive mode. ++You can also exit by terminating input ++(CTRL+D on UNIX or Linux systems, ++CTRL+Z on Windows systems). ++ ++.TP 6 ++.BI help "[COMMAND]" ++Provides a help message about ++the commands available in SCons interactive mode. ++If ++.I COMMAND ++is specified, ++.B h ++and ++.B ? ++are synonyms. ++ ++.TP 6 ++.BI shell "[COMMANDLINE]" ++Executes the specified ++.I COMMANDLINE ++in a subshell. ++If no ++.I COMMANDLINE ++is specified, ++executes the interactive command interpreter ++specified in the ++.B SHELL ++environment variable ++(on UNIX and Linux systems) ++or the ++.B COMSPEC ++environment variable ++(on Windows systems). ++.B sh ++and ++.B ! ++are synonyms. ++ ++.TP 6 ++.B version ++Prints SCons version information. ++.RE ++ ++.IP ++An empty line repeats the last typed command. ++Command-line editing can be used if the ++.B readline ++module is available. ++ ++.ES ++$ scons --interactive ++scons: Reading SConscript files ... ++scons: done reading SConscript files. ++scons>>> build -n prog ++scons>>> exit ++.EE ++ ++.TP ++.RI -j " N" ", --jobs=" N ++Specifies the number of jobs (commands) to run simultaneously. ++If there is more than one ++.B -j ++option, the last one is effective. ++.\" ??? If the ++.\" .B -j ++.\" option ++.\" is specified without an argument, ++.\" .B scons ++.\" will not limit the number of ++.\" simultaneous jobs. ++ ++.TP ++-k, --keep-going ++Continue as much as possible after an error. The target that ++failed and those that depend on it will not be remade, but other ++targets specified on the command line will still be processed. ++ ++.\" .TP ++.\" .RI -l " N" ", --load-average=" N ", --max-load=" N ++.\" No new jobs (commands) will be started if ++.\" there are other jobs running and the system load ++.\" average is at least ++.\" .I N ++.\" (a floating-point number). ++ ++.\" ++.\" .TP ++.\" --list-derived ++.\" List derived files (targets, dependencies) that would be built, ++.\" but do not build them. ++.\" [XXX This can probably go away with the right ++.\" combination of other options. Revisit this issue.] ++.\" ++.\" .TP ++.\" --list-actions ++.\" List derived files that would be built, with the actions ++.\" (commands) that build them. Does not build the files. ++.\" [XXX This can probably go away with the right ++.\" combination of other options. Revisit this issue.] ++.\" ++.\" .TP ++.\" --list-where ++.\" List derived files that would be built, plus where the file is ++.\" defined (file name and line number). Does not build the files. ++.\" [XXX This can probably go away with the right ++.\" combination of other options. Revisit this issue.] ++ ++.TP ++-m ++Ignored for compatibility with non-GNU versions of ++.BR make . ++ ++.TP ++.RI --max-drift= SECONDS ++Set the maximum expected drift in the modification time of files to ++.IR SECONDS . ++This value determines how long a file must be unmodified ++before its cached content signature ++will be used instead of ++calculating a new content signature (MD5 checksum) ++of the file's contents. ++The default value is 2 days, which means a file must have a ++modification time of at least two days ago in order to have its ++cached content signature used. ++A negative value means to never cache the content ++signature and to ignore the cached value if there already is one. A value ++of 0 means to always use the cached signature, ++no matter how old the file is. ++ ++.TP ++.RI --md5-chunksize= KILOBYTES ++Set the block size used to compute MD5 signatures to ++.IR KILOBYTES . ++This value determines the size of the chunks which are read in at once when ++computing MD5 signatures. Files below that size are fully stored in memory ++before performing the signature computation while bigger files are read in ++block-by-block. A huge block-size leads to high memory consumption while a very ++small block-size slows down the build considerably. ++ ++The default value is to use a chunk size of 64 kilobytes, which should ++be appropriate for most uses. ++ ++.TP ++-n, --just-print, --dry-run, --recon ++No execute. Print the commands that would be executed to build ++any out-of-date target files, but do not execute the commands. ++ ++.TP ++.RI --no-site-dir ++Prevents the automatic addition of the standard ++.I site_scons ++dirs to ++.IR sys.path . ++Also prevents loading the ++.I site_scons/site_init.py ++modules if they exist, and prevents adding their ++.I site_scons/site_tools ++dirs to the toolpath. ++ ++.\" .TP ++.\" .RI -o " file" ", --old-file=" file ", --assume-old=" file ++.\" Do not rebuild ++.\" .IR file , ++.\" and do ++.\" not rebuild anything due to changes in the contents of ++.\" .IR file . ++.\" .TP ++.\" .RI --override " file" ++.\" Read values to override specific build environment variables ++.\" from the specified ++.\" .IR file . ++.\" .TP ++.\" -p ++.\" Print the data base (construction environments, ++.\" Builder and Scanner objects) that are defined ++.\" after reading the SConscript files. ++.\" After printing, a normal build is performed ++.\" as usual, as specified by other command-line options. ++.\" This also prints version information ++.\" printed by the ++.\" .B -v ++.\" option. ++.\" ++.\" To print the database without performing a build do: ++.\" ++.\" .ES ++.\" scons -p -q ++.\" .EE ++ ++.TP ++.RI --profile= file ++Run SCons under the Python profiler ++and save the results in the specified ++.IR file . ++The results may be analyzed using the Python ++pstats module. ++ ++.TP ++-q, --question ++Do not run any commands, or print anything. Just return an exit ++status that is zero if the specified targets are already up to ++date, non-zero otherwise. ++.TP ++-Q ++Quiets SCons status messages about ++reading SConscript files, ++building targets ++and entering directories. ++Commands that are executed ++to rebuild target files are still printed. ++ ++.\" .TP ++.\" -r, -R, --no-builtin-rules, --no-builtin-variables ++.\" Clear the default construction variables. Construction ++.\" environments that are created will be completely empty. ++ ++.TP ++--random ++Build dependencies in a random order. This is useful when ++building multiple trees simultaneously with caching enabled, ++to prevent multiple builds from simultaneously trying to build ++or retrieve the same target files. ++ ++.TP ++-s, --silent, --quiet ++Silent. Do not print commands that are executed to rebuild ++target files. ++Also suppresses SCons status messages. ++ ++.TP ++-S, --no-keep-going, --stop ++Ignored for compatibility with GNU ++.BR make . ++ ++.TP ++.RI --site-dir= dir ++Uses the named dir as the site dir rather than the default ++.I site_scons ++dirs. This dir will get prepended to ++.IR sys.path , ++the module ++.IR dir /site_init.py ++will get loaded if it exists, and ++.IR dir /site_tools ++will get added to the default toolpath. ++ ++The default set of ++.I site_scons ++dirs used when ++.I --site-dir ++is not specified depends on the system platform, as follows. Note ++that the directories are examined in the order given, from most ++generic to most specific, so the last-executed site_init.py file is ++the most specific one (which gives it the chance to override ++everything else), and the dirs are prepended to the paths, again so ++the last dir examined comes first in the resulting path. ++ ++.IP "Windows:" ++.nf ++ %ALLUSERSPROFILE/Application Data/scons/site_scons ++ %USERPROFILE%/Local Settings/Application Data/scons/site_scons ++ %APPDATA%/scons/site_scons ++ %HOME%/.scons/site_scons ++ ./site_scons ++.fi ++.IP "Mac OS X:" ++.nf ++ /Library/Application Support/SCons/site_scons ++ /opt/local/share/scons/site_scons (for MacPorts) ++ /sw/share/scons/site_scons (for Fink) ++ $HOME/Library/Application Support/SCons/site_scons ++ $HOME/.scons/site_scons ++ ./site_scons ++.fi ++.IP "Solaris:" ++.nf ++ /opt/sfw/scons/site_scons ++ /usr/share/scons/site_scons ++ $HOME/.scons/site_scons ++ ./site_scons ++.fi ++.IP "Linux, HPUX, and other Posix-like systems:" ++.nf ++ /usr/share/scons/site_scons ++ $HOME/.scons/site_scons ++ ./site_scons ++.fi ++ ++.TP ++.RI --stack-size= KILOBYTES ++Set the size stack used to run threads to ++.IR KILOBYTES . ++This value determines the stack size of the threads used to run jobs. ++These are the threads that execute the actions of the builders for the ++nodes that are out-of-date. ++Note that this option has no effect unless the ++.B num_jobs ++option, which corresponds to -j and --jobs, is larger than one. Using ++a stack size that is too small may cause stack overflow errors. This ++usually shows up as segmentation faults that cause scons to abort ++before building anything. Using a stack size that is too large will ++cause scons to use more memory than required and may slow down the entire ++build process. ++ ++The default value is to use a stack size of 256 kilobytes, which should ++be appropriate for most uses. You should not need to increase this value ++unless you encounter stack overflow errors. ++ ++.TP ++-t, --touch ++Ignored for compatibility with GNU ++.BR make . ++(Touching a file to make it ++appear up-to-date is unnecessary when using ++.BR scons .) ++ ++.TP ++.RI --taskmastertrace= file ++Prints trace information to the specified ++.I file ++about how the internal Taskmaster object ++evaluates and controls the order in which Nodes are built. ++A file name of ++.B - ++may be used to specify the standard output. ++ ++.TP ++.RI -tree= options ++Prints a tree of the dependencies ++after each top-level target is built. ++This prints out some or all of the tree, ++in various formats, ++depending on the ++.I options ++specified: ++ ++.TP ++--tree=all ++Print the entire dependency tree ++after each top-level target is built. ++This prints out the complete dependency tree, ++including implicit dependencies and ignored dependencies. ++ ++.TP ++--tree=derived ++Restricts the tree output to only derived (target) files, ++not source files. ++ ++.TP ++--tree=status ++Prints status information for each displayed node. ++ ++.TP ++--tree=prune ++Prunes the tree to avoid repeating dependency information ++for nodes that have already been displayed. ++Any node that has already been displayed ++will have its name printed in ++.BR "[square brackets]" , ++as an indication that the dependencies ++for that node can be found by searching ++for the relevant output higher up in the tree. ++ ++.IP ++Multiple options may be specified, ++separated by commas: ++ ++.ES ++# Prints only derived files, with status information: ++scons --tree=derived,status ++ ++# Prints all dependencies of target, with status information ++# and pruning dependencies of already-visited Nodes: ++scons --tree=all,prune,status target ++.EE ++ ++.TP ++-u, --up, --search-up ++Walks up the directory structure until an ++.I SConstruct , ++.I Sconstruct ++or ++.I sconstruct ++file is found, and uses that ++as the top of the directory tree. ++If no targets are specified on the command line, ++only targets at or below the ++current directory will be built. ++ ++.TP ++-U ++Works exactly the same way as the ++.B -u ++option except for the way default targets are handled. ++When this option is used and no targets are specified on the command line, ++all default targets that are defined in the SConscript(s) in the current ++directory are built, regardless of what directory the resultant targets end ++up in. ++ ++.TP ++-v, --version ++Print the ++.B scons ++version, copyright information, ++list of authors, and any other relevant information. ++Then exit. ++ ++.TP ++-w, --print-directory ++Print a message containing the working directory before and ++after other processing. ++ ++.TP ++--no-print-directory ++Turn off -w, even if it was turned on implicitly. ++ ++.TP ++.RI --warn= type ", --warn=no-" type ++Enable or disable warnings. ++.I type ++specifies the type of warnings to be enabled or disabled: ++ ++.TP ++--warn=all, --warn=no-all ++Enables or disables all warnings. ++ ++.TP ++--warn=cache-write-error, --warn=no-cache-write-error ++Enables or disables warnings about errors trying to ++write a copy of a built file to a specified ++.BR CacheDir (). ++These warnings are disabled by default. ++ ++.TP ++--warn=corrupt-sconsign, --warn=no-corrupt-sconsign ++Enables or disables warnings about unfamiliar signature data in ++.B .sconsign ++files. ++These warnings are enabled by default. ++ ++.TP ++--warn=dependency, --warn=no-dependency ++Enables or disables warnings about dependencies. ++These warnings are disabled by default. ++ ++.TP ++--warn=deprecated, --warn=no-deprecated ++Enables or disables all warnings about use of ++currently deprecated features. ++These warnings are enabled by default. ++Note that the ++.B --warn=no-deprecated ++option does not disable warnings about absolutely all deprecated features. ++Warnings for some deprecated features that have already been through ++several releases with deprecation warnings ++may be mandatory for a release or two ++before they are officially no longer supported by SCons. ++Warnings for some specific deprecated features ++may be enabled or disabled individually; ++see below. ++ ++.RS ++.TP ++--warn=deprecated-copy, --warn=no-deprecated-copy ++Enables or disables warnings about use of the deprecated ++.B env.Copy() ++method. ++ ++.TP ++--warn=deprecated-source-signatures, --warn=no-deprecated-source-signatures ++Enables or disables warnings about use of the deprecated ++.B SourceSignatures() ++function or ++.B env.SourceSignatures() ++method. ++ ++.TP ++--warn=deprecated-target-signatures, --warn=no-deprecated-target-signatures ++Enables or disables warnings about use of the deprecated ++.B TargetSignatures() ++function or ++.B env.TargetSignatures() ++method. ++.RE ++ ++.TP ++--warn=duplicate-environment, --warn=no-duplicate-environment ++Enables or disables warnings about attempts to specify a build ++of a target with two different construction environments ++that use the same action. ++These warnings are enabled by default. ++ ++.TP ++--warn=fortran-cxx-mix, --warn=no-fortran-cxx-mix ++Enables or disables the specific warning about linking ++Fortran and C++ object files in a single executable, ++which can yield unpredictable behavior with some compilers. ++ ++.TP ++--warn=future-deprecated, --warn=no-future-deprecated ++Enables or disables warnings about features ++that will be deprecated in the future. ++These warnings are disabled by default. ++Enabling this warning is especially ++recommended for projects that redistribute ++SCons configurations for other users to build, ++so that the project can be warned as soon as possible ++about to-be-deprecated features ++that may require changes to the configuration. ++ ++.TP ++--warn=link, --warn=no-link ++Enables or disables warnings about link steps. ++ ++.TP ++--warn=misleading-keywords, --warn=no-misleading-keywords ++Enables or disables warnings about use of the misspelled keywords ++.B targets ++and ++.B sources ++when calling Builders. ++(Note the last ++.B s ++characters, the correct spellings are ++.B target ++and ++.B source.) ++These warnings are enabled by default. ++ ++.TP ++--warn=missing-sconscript, --warn=no-missing-sconscript ++Enables or disables warnings about missing SConscript files. ++These warnings are enabled by default. ++ ++.TP ++--warn=no-md5-module, --warn=no-no-md5-module ++Enables or disables warnings about the version of Python ++not having an MD5 checksum module available. ++These warnings are enabled by default. ++ ++.TP ++--warn=no-metaclass-support, --warn=no-no-metaclass-support ++Enables or disables warnings about the version of Python ++not supporting metaclasses when the ++.B --debug=memoizer ++option is used. ++These warnings are enabled by default. ++ ++.TP ++--warn=no-object-count, --warn=no-no-object-count ++Enables or disables warnings about the ++.B --debug=object ++feature not working when ++.B scons ++is run with the python ++.B \-O ++option or from optimized Python (.pyo) modules. ++ ++.TP ++--warn=no-parallel-support, --warn=no-no-parallel-support ++Enables or disables warnings about the version of Python ++not being able to support parallel builds when the ++.B -j ++option is used. ++These warnings are enabled by default. ++ ++.TP ++--warn=python-version, --warn=no-python-version ++Enables or disables the warning about running ++SCons with a deprecated version of Python. ++These warnings are enabled by default. ++ ++.TP ++--warn=reserved-variable, --warn=no-reserved-variable ++Enables or disables warnings about attempts to set the ++reserved construction variable names ++.BR CHANGED_SOURCES , ++.BR CHANGED_TARGETS , ++.BR TARGET , ++.BR TARGETS , ++.BR SOURCE , ++.BR SOURCES , ++.BR UNCHANGED_SOURCES ++or ++.BR UNCHANGED_TARGETS . ++These warnings are disabled by default. ++ ++.TP ++--warn=stack-size, --warn=no-stack-size ++Enables or disables warnings about requests to set the stack size ++that could not be honored. ++These warnings are enabled by default. ++ ++.\" .TP ++.\" .RI --write-filenames= file ++.\" Write all filenames considered into ++.\" .IR file . ++.\" ++.\" .TP ++.\" .RI -W " file" ", --what-if=" file ", --new-file=" file ", --assume-new=" file ++.\" Pretend that the target ++.\" .I file ++.\" has been ++.\" modified. When used with the ++.\" .B -n ++.\" option, this ++.\" show you what would be rebuilt if you were to modify that file. ++.\" Without ++.\" .B -n ++.\" ... what? XXX ++.\" ++.\" .TP ++.\" --warn-undefined-variables ++.\" Warn when an undefined variable is referenced. ++ ++.TP ++.RI -Y " repository" ", --repository=" repository ", --srcdir=" repository ++Search the specified repository for any input and target ++files not found in the local directory hierarchy. Multiple ++.B -Y ++options may be specified, in which case the ++repositories are searched in the order specified. ++ ++.SH CONFIGURATION FILE REFERENCE ++.\" .SS Python Basics ++.\" XXX Adding this in the future would be a help. ++.SS Construction Environments ++A construction environment is the basic means by which the SConscript ++files communicate build information to ++.BR scons . ++A new construction environment is created using the ++.B Environment ++function: ++ ++.ES ++env = Environment() ++.EE ++ ++Variables, called ++.I construction ++.IR variables , ++may be set in a construction environment ++either by specifying them as keywords when the object is created ++or by assigning them a value after the object is created: ++ ++.ES ++env = Environment(FOO = 'foo') ++env['BAR'] = 'bar' ++.EE ++ ++As a convenience, ++construction variables may also be set or modified by the ++.I parse_flags ++keyword argument, which applies the ++.B ParseFlags ++method (described below) to the argument value ++after all other processing is completed. ++This is useful either if the exact content of the flags is unknown ++(for example, read from a control file) ++or if the flags are distributed to a number of construction variables. ++ ++.ES ++env = Environment(parse_flags = '-Iinclude -DEBUG -lm') ++.EE ++ ++This example adds 'include' to ++.BR CPPPATH , ++\&'EBUG' to ++.BR CPPDEFINES , ++and 'm' to ++.BR LIBS . ++ ++By default, a new construction environment is ++initialized with a set of builder methods ++and construction variables that are appropriate ++for the current platform. ++An optional platform keyword argument may be ++used to specify that an environment should ++be initialized for a different platform: ++ ++.ES ++env = Environment(platform = 'cygwin') ++env = Environment(platform = 'os2') ++env = Environment(platform = 'posix') ++env = Environment(platform = 'win32') ++.EE ++ ++Specifying a platform initializes the appropriate ++construction variables in the environment ++to use and generate file names with prefixes ++and suffixes appropriate for the platform. ++ ++Note that the ++.B win32 ++platform adds the ++.B SystemDrive ++and ++.B SystemRoot ++variables from the user's external environment ++to the construction environment's ++.B ENV ++dictionary. ++This is so that any executed commands ++that use sockets to connect with other systems ++(such as fetching source files from ++external CVS repository specifications like ++.BR :pserver:anonymous@cvs.sourceforge.net:/cvsroot/scons ) ++will work on Windows systems. ++ ++The platform argument may be function or callable object, ++in which case the Environment() method ++will call the specified argument to update ++the new construction environment: ++ ++.ES ++def my_platform(env): ++ env['VAR'] = 'xyzzy' ++ ++env = Environment(platform = my_platform) ++.EE ++ ++Additionally, a specific set of tools ++with which to initialize the environment ++may be specified as an optional keyword argument: ++ ++.ES ++env = Environment(tools = ['msvc', 'lex']) ++.EE ++ ++Non-built-in tools may be specified using the toolpath argument: ++ ++.ES ++env = Environment(tools = ['default', 'foo'], toolpath = ['tools']) ++.EE ++ ++This looks for a tool specification in tools/foo.py (as well as ++using the ordinary default tools for the platform). foo.py should ++have two functions: generate(env, **kw) and exists(env). ++The ++.B generate() ++function ++modifies the passed-in environment ++to set up variables so that the tool ++can be executed; ++it may use any keyword arguments ++that the user supplies (see below) ++to vary its initialization. ++The ++.B exists() ++function should return a true ++value if the tool is available. ++Tools in the toolpath are used before ++any of the built-in ones. For example, adding gcc.py to the toolpath ++would override the built-in gcc tool. ++Also note that the toolpath is ++stored in the environment for use ++by later calls to ++.BR Clone () ++and ++.BR Tool () ++methods: ++ ++.ES ++base = Environment(toolpath=['custom_path']) ++derived = base.Clone(tools=['custom_tool']) ++derived.CustomBuilder() ++.EE ++ ++The elements of the tools list may also ++be functions or callable objects, ++in which case the Environment() method ++will call the specified elements ++to update the new construction environment: ++ ++.ES ++def my_tool(env): ++ env['XYZZY'] = 'xyzzy' ++ ++env = Environment(tools = [my_tool]) ++.EE ++ ++The individual elements of the tools list ++may also themselves be two-element lists of the form ++.RI ( toolname ", " kw_dict ). ++SCons searches for the ++.I toolname ++specification file as described above, and ++passes ++.IR kw_dict , ++which must be a dictionary, as keyword arguments to the tool's ++.B generate ++function. ++The ++.B generate ++function can use the arguments to modify the tool's behavior ++by setting up the environment in different ways ++or otherwise changing its initialization. ++ ++.ES ++# in tools/my_tool.py: ++def generate(env, **kw): ++ # Sets MY_TOOL to the value of keyword argument 'arg1' or 1. ++ env['MY_TOOL'] = kw.get('arg1', '1') ++def exists(env): ++ return 1 ++ ++# in SConstruct: ++env = Environment(tools = ['default', ('my_tool', {'arg1': 'abc'})], ++ toolpath=['tools']) ++.EE ++ ++The tool definition (i.e. my_tool()) can use the PLATFORM variable from ++the environment it receives to customize the tool for different platforms. ++ ++If no tool list is specified, then SCons will auto-detect the installed ++tools using the PATH variable in the ENV construction variable and the ++platform name when the Environment is constructed. Changing the PATH ++variable after the Environment is constructed will not cause the tools to ++be redetected. ++ ++SCons supports the following tool specifications out of the box: ++ ++.ES ++386asm ++aixc++ ++aixcc ++aixf77 ++aixlink ++ar ++as ++bcc32 ++c++ ++cc ++cvf ++dmd ++dvipdf ++dvips ++f77 ++f90 ++f95 ++fortran ++g++ ++g77 ++gas ++gcc ++gfortran ++gnulink ++gs ++hpc++ ++hpcc ++hplink ++icc ++icl ++ifl ++ifort ++ilink ++ilink32 ++intelc ++jar ++javac ++javah ++latex ++lex ++link ++linkloc ++m4 ++masm ++midl ++mingw ++mslib ++mslink ++mssdk ++msvc ++msvs ++mwcc ++mwld ++nasm ++pdflatex ++pdftex ++qt ++rmic ++rpcgen ++sgiar ++sgic++ ++sgicc ++sgilink ++sunar ++sunc++ ++suncc ++sunf77 ++sunf90 ++sunf95 ++sunlink ++swig ++tar ++tex ++textfile ++tlib ++yacc ++zip ++.EE ++ ++Additionally, there is a "tool" named ++.B default ++which configures the ++environment with a default set of tools for the current platform. ++ ++On posix and cygwin platforms ++the GNU tools (e.g. gcc) are preferred by SCons, ++on Windows the Microsoft tools (e.g. msvc) ++followed by MinGW are preferred by SCons, ++and in OS/2 the IBM tools (e.g. icc) are preferred by SCons. ++ ++.SS Builder Methods ++ ++Build rules are specified by calling a construction ++environment's builder methods. ++The arguments to the builder methods are ++.B target ++(a list of targets to be built, ++usually file names) ++and ++.B source ++(a list of sources to be built, ++usually file names). ++ ++Because long lists of file names ++can lead to a lot of quoting, ++.B scons ++supplies a ++.B Split() ++global function ++and a same-named environment method ++that split a single string ++into a list, separated on ++strings of white-space characters. ++(These are similar to the split() member function of Python strings ++but work even if the input isn't a string.) ++ ++Like all Python arguments, ++the target and source arguments to a builder method ++can be specified either with or without ++the "target" and "source" keywords. ++When the keywords are omitted, ++the target is first, ++followed by the source. ++The following are equivalent examples of calling the Program builder method: ++ ++.ES ++env.Program('bar', ['bar.c', 'foo.c']) ++env.Program('bar', Split('bar.c foo.c')) ++env.Program('bar', env.Split('bar.c foo.c')) ++env.Program(source = ['bar.c', 'foo.c'], target = 'bar') ++env.Program(target = 'bar', Split('bar.c foo.c')) ++env.Program(target = 'bar', env.Split('bar.c foo.c')) ++env.Program('bar', source = 'bar.c foo.c'.split()) ++.EE ++ ++Target and source file names ++that are not absolute path names ++(that is, do not begin with ++.B / ++on POSIX systems ++or ++.B \\ ++on Windows systems, ++with or without ++an optional drive letter) ++are interpreted relative to the directory containing the ++.B SConscript ++file being read. ++An initial ++.B # ++(hash mark) ++on a path name means that the rest of the file name ++is interpreted relative to ++the directory containing ++the top-level ++.B SConstruct ++file, ++even if the ++.B # ++is followed by a directory separator character ++(slash or backslash). ++ ++Examples: ++ ++.ES ++# The comments describing the targets that will be built ++# assume these calls are in a SConscript file in the ++# a subdirectory named "subdir". ++ ++# Builds the program "subdir/foo" from "subdir/foo.c": ++env.Program('foo', 'foo.c') ++ ++# Builds the program "/tmp/bar" from "subdir/bar.c": ++env.Program('/tmp/bar', 'bar.c') ++ ++# An initial '#' or '#/' are equivalent; the following ++# calls build the programs "foo" and "bar" (in the ++# top-level SConstruct directory) from "subdir/foo.c" and ++# "subdir/bar.c", respectively: ++env.Program('#foo', 'foo.c') ++env.Program('#/bar', 'bar.c') ++ ++# Builds the program "other/foo" (relative to the top-level ++# SConstruct directory) from "subdir/foo.c": ++env.Program('#other/foo', 'foo.c') ++.EE ++ ++When the target shares the same base name ++as the source and only the suffix varies, ++and if the builder method has a suffix defined for the target file type, ++then the target argument may be omitted completely, ++and ++.B scons ++will deduce the target file name from ++the source file name. ++The following examples all build the ++executable program ++.B bar ++(on POSIX systems) ++or ++.B bar.exe ++(on Windows systems) ++from the bar.c source file: ++ ++.ES ++env.Program(target = 'bar', source = 'bar.c') ++env.Program('bar', source = 'bar.c') ++env.Program(source = 'bar.c') ++env.Program('bar.c') ++.EE ++ ++As a convenience, a ++.B srcdir ++keyword argument may be specified ++when calling a Builder. ++When specified, ++all source file strings that are not absolute paths ++will be interpreted relative to the specified ++.BR srcdir . ++The following example will build the ++.B build/prog ++(or ++.B build/prog.exe ++on Windows) ++program from the files ++.B src/f1.c ++and ++.BR src/f2.c : ++ ++.ES ++env.Program('build/prog', ['f1.c', 'f2.c'], srcdir='src') ++.EE ++ ++It is possible to override or add construction variables when calling a ++builder method by passing additional keyword arguments. ++These overridden or added ++variables will only be in effect when building the target, so they will not ++affect other parts of the build. For example, if you want to add additional ++libraries for just one program: ++ ++.ES ++env.Program('hello', 'hello.c', LIBS=['gl', 'glut']) ++.EE ++ ++or generate a shared library with a non-standard suffix: ++ ++.ES ++env.SharedLibrary('word', 'word.cpp', ++ SHLIBSUFFIX='.ocx', ++ LIBSUFFIXES=['.ocx']) ++.EE ++ ++(Note that both the $SHLIBSUFFIX and $LIBSUFFIXES variables must be set ++if you want SCons to search automatically ++for dependencies on the non-standard library names; ++see the descriptions of these variables, below, for more information.) ++ ++It is also possible to use the ++.I parse_flags ++keyword argument in an override: ++ ++.ES ++env = Program('hello', 'hello.c', parse_flags = '-Iinclude -DEBUG -lm') ++.EE ++ ++This example adds 'include' to ++.BR CPPPATH , ++\&'EBUG' to ++.BR CPPDEFINES , ++and 'm' to ++.BR LIBS . ++ ++Although the builder methods defined by ++.B scons ++are, in fact, ++methods of a construction environment object, ++they may also be called without an explicit environment: ++ ++.ES ++Program('hello', 'hello.c') ++SharedLibrary('word', 'word.cpp') ++.EE ++ ++In this case, ++the methods are called internally using a default construction ++environment that consists of the tools and values that ++.B scons ++has determined are appropriate for the local system. ++ ++Builder methods that can be called without an explicit ++environment may be called from custom Python modules that you ++import into an SConscript file by adding the following ++to the Python module: ++ ++.ES ++from SCons.Script import * ++.EE ++ ++All builder methods return a list-like object ++containing Nodes that ++represent the target or targets that will be built. ++A ++.I Node ++is an internal SCons object ++which represents ++build targets or sources. ++ ++The returned Node-list object ++can be passed to other builder methods as source(s) ++or passed to any SCons function or method ++where a filename would normally be accepted. ++For example, if it were necessary ++to add a specific ++.B -D ++flag when compiling one specific object file: ++ ++.ES ++bar_obj_list = env.StaticObject('bar.c', CPPDEFINES='-DBAR') ++env.Program(source = ['foo.c', bar_obj_list, 'main.c']) ++.EE ++ ++Using a Node in this way ++makes for a more portable build ++by avoiding having to specify ++a platform-specific object suffix ++when calling the Program() builder method. ++ ++Note that Builder calls will automatically "flatten" ++the source and target file lists, ++so it's all right to have the bar_obj list ++return by the StaticObject() call ++in the middle of the source file list. ++If you need to manipulate a list of lists returned by Builders ++directly using Python, ++you can either build the list by hand: ++ ++.ES ++foo = Object('foo.c') ++bar = Object('bar.c') ++objects = ['begin.o'] + foo + ['middle.o'] + bar + ['end.o'] ++for object in objects: ++ print str(object) ++.EE ++ ++Or you can use the ++.BR Flatten () ++function supplied by scons ++to create a list containing just the Nodes, ++which may be more convenient: ++ ++.ES ++foo = Object('foo.c') ++bar = Object('bar.c') ++objects = Flatten(['begin.o', foo, 'middle.o', bar, 'end.o']) ++for object in objects: ++ print str(object) ++.EE ++ ++Note also that because Builder calls return ++a list-like object, not an actual Python list, ++you should ++.I not ++use the Python ++.B += ++operator to append Builder results to a Python list. ++Because the list and the object are different types, ++Python will not update the original list in place, ++but will instead create a new Node-list object ++containing the concatenation of the list ++elements and the Builder results. ++This will cause problems for any other Python variables ++in your SCons configuration ++that still hold on to a reference to the original list. ++Instead, use the Python ++.B .extend() ++method to make sure the list is updated in-place. ++Example: ++ ++.ES ++object_files = [] ++ ++# Do NOT use += as follows: ++# ++# object_files += Object('bar.c') ++# ++# It will not update the object_files list in place. ++# ++# Instead, use the .extend() method: ++object_files.extend(Object('bar.c')) ++ ++.EE ++ ++The path name for a Node's file may be used ++by passing the Node to the Python-builtin ++.B str() ++function: ++ ++.ES ++bar_obj_list = env.StaticObject('bar.c', CPPDEFINES='-DBAR') ++print "The path to bar_obj is:", str(bar_obj_list[0]) ++.EE ++ ++Note again that because the Builder call returns a list, ++we have to access the first element in the list ++.B (bar_obj_list[0]) ++to get at the Node that actually represents ++the object file. ++ ++Builder calls support a ++.B chdir ++keyword argument that ++specifies that the Builder's action(s) ++should be executed ++after changing directory. ++If the ++.B chdir ++argument is ++a string or a directory Node, ++scons will change to the specified directory. ++If the ++.B chdir ++is not a string or Node ++and is non-zero, ++then scons will change to the ++target file's directory. ++ ++.ES ++# scons will change to the "sub" subdirectory ++# before executing the "cp" command. ++env.Command('sub/dir/foo.out', 'sub/dir/foo.in', ++ "cp dir/foo.in dir/foo.out", ++ chdir='sub') ++ ++# Because chdir is not a string, scons will change to the ++# target's directory ("sub/dir") before executing the ++# "cp" command. ++env.Command('sub/dir/foo.out', 'sub/dir/foo.in', ++ "cp foo.in foo.out", ++ chdir=1) ++.EE ++ ++Note that scons will ++.I not ++automatically modify ++its expansion of ++construction variables like ++.B $TARGET ++and ++.B $SOURCE ++when using the chdir ++keyword argument--that is, ++the expanded file names ++will still be relative to ++the top-level SConstruct directory, ++and consequently incorrect ++relative to the chdir directory. ++If you use the chdir keyword argument, ++you will typically need to supply a different ++command line using ++expansions like ++.B ${TARGET.file} ++and ++.B ${SOURCE.file} ++to use just the filename portion of the ++targets and source. ++ ++.B scons ++provides the following builder methods: ++ ++'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" ++'\" BEGIN GENERATED BUILDER DESCRIPTIONS ++'\" ++'\" The descriptions below of the various SCons Builders are generated ++'\" from the .xml files that live next to the various Python modules in ++'\" the build enginer library. If you're reading this [gnt]roff file ++'\" with an eye towards patching this man page, you can still submit ++'\" a diff against this text, but it will have to be translated to a ++'\" diff against the underlying .xml file before the patch is actually ++'\" accepted. If you do that yourself, it will make it easier to ++'\" integrate the patch. ++'\" ++'\" BEGIN GENERATED BUILDER DESCRIPTIONS ++'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" ++ ++'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" ++.IP CFile() ++.IP env.CFile() ++Builds a C source file given a lex (\fB.l\fP) ++or yacc (\fB.y\fP) input file. ++The suffix specified by the \fB$CFILESUFFIX\fP construction variable ++(\fB.c\fP by default) ++is automatically added to the target ++if it is not already present. ++Example: ++ ++.ES ++# builds foo.c ++env.CFile(target = 'foo.c', source = 'foo.l') ++# builds bar.c ++env.CFile(target = 'bar', source = 'bar.y') ++.EE ++ ++'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" ++.IP Command() ++.IP env.Command() ++The \fBCommand\fP() "Builder" is actually implemented ++as a function that looks like a Builder, ++but actually takes an additional argument of the action ++from which the Builder should be made. ++See the \fBCommand\fP() function description ++for the calling syntax and details. ++ ++'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" ++.IP CXXFile() ++.IP env.CXXFile() ++Builds a C++ source file given a lex (\fB.ll\fP) ++or yacc (\fB.yy\fP) ++input file. ++The suffix specified by the \fB$CXXFILESUFFIX\fP construction variable ++(\fB.cc\fP by default) ++is automatically added to the target ++if it is not already present. ++Example: ++ ++.ES ++# builds foo.cc ++env.CXXFile(target = 'foo.cc', source = 'foo.ll') ++# builds bar.cc ++env.CXXFile(target = 'bar', source = 'bar.yy') ++.EE ++ ++'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" ++.IP DVI() ++.IP env.DVI() ++Builds a \fB.dvi\fP file ++from a \fB.tex\fP, ++\fB.ltx\fP or \fB.latex\fP input file. ++If the source file suffix is \fB.tex\fP, ++.B scons ++will examine the contents of the file; ++if the string ++.B \\documentclass ++or ++.B \\documentstyle ++is found, the file is assumed to be a LaTeX file and ++the target is built by invoking the \fB$LATEXCOM\fP command line; ++otherwise, the \fB$TEXCOM\fP command line is used. ++If the file is a LaTeX file, ++the ++.BR DVI () ++builder method will also examine the contents ++of the ++.B .aux ++file and invoke the \fB$BIBTEX\fP command line ++if the string ++.B bibdata ++is found, ++start \fB$MAKEINDEX\fP to generate an index if a ++.B .ind ++file is found ++and will examine the contents ++.B .log ++file and re-run the \fB$LATEXCOM\fP command ++if the log file says it is necessary. ++ ++The suffix \fB.dvi\fP ++(hard-coded within TeX itself) ++is automatically added to the target ++if it is not already present. ++Examples: ++ ++.ES ++# builds from aaa.tex ++env.DVI(target = 'aaa.dvi', source = 'aaa.tex') ++# builds bbb.dvi ++env.DVI(target = 'bbb', source = 'bbb.ltx') ++# builds from ccc.latex ++env.DVI(target = 'ccc.dvi', source = 'ccc.latex') ++.EE ++ ++'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" ++.IP Install() ++.IP env.Install() ++Installs one or more source files or directories ++in the specified target, ++which must be a directory. ++The names of the specified source files or directories ++remain the same within the destination directory. The ++sources may be given as a string or as a node returned by ++a builder. ++ ++.ES ++env.Install('/usr/local/bin', source = ['foo', 'bar']) ++.EE ++ ++'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" ++.IP InstallAs() ++.IP env.InstallAs() ++Installs one or more source files or directories ++to specific names, ++allowing changing a file or directory name ++as part of the installation. ++It is an error if the ++target ++and ++source ++arguments list different numbers of files or directories. ++ ++'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" ++.IP InstallVersionedLib() ++.IP env.InstallVersionedLib() ++Installs a versioned shared library. The \fB$SHLIBVERSION\fP ++construction variable should be defined in the environment ++to confirm the version number in the library name. ++The symlinks appropriate to the architecture will be generated. ++ ++.ES ++env.InstallAs(target = '/usr/local/bin/foo', ++ source = 'foo_debug') ++env.InstallAs(target = ['../lib/libfoo.a', '../lib/libbar.a'], ++ source = ['libFOO.a', 'libBAR.a']) ++.EE ++ ++'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" ++.IP Jar() ++.IP env.Jar() ++Builds a Java archive (\fB.jar\fP) file ++from the specified list of sources. ++Any directories in the source list ++will be searched for \fB.class\fP files). ++Any \fB.java\fP files in the source list ++will be compiled to \fB.class\fP files ++by calling the \fBJava\fP() Builder. ++ ++If the \fB$JARCHDIR\fP value is set, the ++.B jar ++command will change to the specified directory using the ++.B \-C ++option. ++If \fB$JARCHDIR\fP is not set explicitly, ++&SCons; will use the top of any subdirectory tree ++in which Java \fB.class\fP ++were built by the \fBJava\fP() Builder. ++ ++If the contents any of the source files begin with the string ++.BR Manifest-Version , ++the file is assumed to be a manifest ++and is passed to the ++.B jar ++command with the ++.B m ++option set. ++ ++.ES ++env.Jar(target = 'foo.jar', source = 'classes') ++ ++env.Jar(target = 'bar.jar', ++ source = ['bar1.java', 'bar2.java']) ++.EE ++ ++'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" ++.IP Java() ++.IP env.Java() ++Builds one or more Java class files. ++The sources may be any combination of explicit ++\fB.java\fP files, ++or directory trees which will be scanned ++for \fB.java\fP files. ++ ++SCons will parse each source \fB.java\fP file ++to find the classes ++(including inner classes) ++defined within that file, ++and from that figure out the ++target \fB.class\fP files that will be created. ++The class files will be placed underneath ++the specified target directory. ++ ++SCons will also search each Java file ++for the Java package name, ++which it assumes can be found on a line ++beginning with the string ++.B package ++in the first column; ++the resulting \fB.class\fP files ++will be placed in a directory reflecting ++the specified package name. ++For example, ++the file ++.B Foo.java ++defining a single public ++.I Foo ++class and ++containing a package name of ++.I sub.dir ++will generate a corresponding ++.B sub/dir/Foo.class ++class file. ++ ++Examples: ++ ++.ES ++env.Java(target = 'classes', source = 'src') ++env.Java(target = 'classes', source = ['src1', 'src2']) ++env.Java(target = 'classes', source = ['File1.java', 'File2.java']) ++.EE ++.IP ++Java source files can use the native encoding for the underlying OS. ++Since SCons compiles in simple ASCII mode by default, ++the compiler will generate warnings about unmappable characters, ++which may lead to errors as the file is processed further. ++In this case, the user must specify the \fBLANG\fP ++environment variable to tell the compiler what encoding is used. ++For portibility, it's best if the encoding is hard-coded ++so that the compile will work if it is done on a system ++with a different encoding. ++ ++.ES ++env = Environment() ++env['ENV']['LANG'] = 'en_GB.UTF-8' ++.EE ++ ++'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" ++.IP JavaH() ++.IP env.JavaH() ++Builds C header and source files for ++implementing Java native methods. ++The target can be either a directory ++in which the header files will be written, ++or a header file name which ++will contain all of the definitions. ++The source can be the names of \fB.class\fP files, ++the names of \fB.java\fP files ++to be compiled into \fB.class\fP files ++by calling the \fBJava\fP() builder method, ++or the objects returned from the ++.BR Java () ++builder method. ++ ++If the construction variable ++.B $JAVACLASSDIR ++is set, either in the environment ++or in the call to the ++.BR JavaH () ++builder method itself, ++then the value of the variable ++will be stripped from the ++beginning of any \fB.class\fP file names. ++ ++Examples: ++ ++.ES ++# builds java_native.h ++classes = env.Java(target = 'classdir', source = 'src') ++env.JavaH(target = 'java_native.h', source = classes) ++ ++# builds include/package_foo.h and include/package_bar.h ++env.JavaH(target = 'include', ++ source = ['package/foo.class', 'package/bar.class']) ++ ++# builds export/foo.h and export/bar.h ++env.JavaH(target = 'export', ++ source = ['classes/foo.class', 'classes/bar.class'], ++ JAVACLASSDIR = 'classes') ++.EE ++ ++'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" ++.IP Library() ++.IP env.Library() ++A synonym for the ++.BR StaticLibrary () ++builder method. ++ ++'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" ++.IP LoadableModule() ++.IP env.LoadableModule() ++On most systems, ++this is the same as ++.BR SharedLibrary (). ++On Mac OS X (Darwin) platforms, ++this creates a loadable module bundle. ++ ++'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" ++.IP M4() ++.IP env.M4() ++Builds an output file from an M4 input file. ++This uses a default \fB$M4FLAGS\fP value of ++.BR \-E , ++which considers all warnings to be fatal ++and stops on the first warning ++when using the GNU version of m4. ++Example: ++ ++.ES ++env.M4(target = 'foo.c', source = 'foo.c.m4') ++.EE ++ ++'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" ++.IP Moc() ++.IP env.Moc() ++Builds an output file from a moc input file. Moc input files are either ++header files or cxx files. This builder is only available after using the ++tool 'qt'. See the \fB$QTDIR\fP variable for more information. ++Example: ++ ++.ES ++env.Moc('foo.h') # generates moc_foo.cc ++env.Moc('foo.cpp') # generates foo.moc ++.EE ++ ++'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" ++.IP MOFiles() ++.IP env.MOFiles() ++This builder belongs to &t-link-msgfmt; tool. The builder compiles ++\fBPO\fP files to \fBMO\fP files. ++ ++.IR Example 1 . ++Create \fBpl.mo\fP and \fBen.mo\fP by compiling ++.BR pl.po\fP and \fBen.po : ++.ES ++ # ... ++ env.MOFiles(['pl', 'en']) ++.EE ++.IP ++.IR Example 2 . ++Compile files for languages defined in \fBLINGUAS\fP file: ++.ES ++ # ... ++ env.MOFiles(LINGUAS_FILE = 1) ++.EE ++.IP ++.IR Example 3 . ++Create \fBpl.mo\fP and \fBen.mo\fP by compiling ++\fBpl.po\fP and \fBen.po\fP plus files for ++languages defined in \fBLINGUAS\fP file: ++.ES ++ # ... ++ env.MOFiles(['pl', 'en'], LINGUAS_FILE = 1) ++.EE ++.IP ++.IR Example 4 . ++Compile files for languages defined in \fBLINGUAS\fP file ++(another version): ++.ES ++ # ... ++ env['LINGUAS_FILE'] = 1 ++ env.MOFiles() ++.EE ++ ++'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" ++.IP MSVSProject() ++.IP env.MSVSProject() ++Builds a Microsoft Visual Studio project file, ++and by default builds a solution file as well. ++ ++This builds a Visual Studio project file, based on the version of ++Visual Studio that is configured (either the latest installed version, ++or the version specified by ++.B $MSVS_VERSION ++in the Environment constructor). ++For Visual Studio 6, it will generate a ++.B .dsp ++file. ++For Visual Studio 7 (.NET) and later versions, it will generate a ++.B .vcproj ++file. ++ ++By default, ++this also generates a solution file ++for the specified project, ++a ++.B .dsw ++file for Visual Studio 6 ++or a ++.B .sln ++file for Visual Studio 7 (.NET). ++This behavior may be disabled by specifying ++.B auto_build_solution=0 ++when you call ++.BR MSVSProject (), ++in which case you presumably want to ++build the solution file(s) ++by calling the ++.BR MSVSSolution () ++Builder (see below). ++ ++The \fBMSVSProject\fP() builder ++takes several lists of filenames ++to be placed into the project file. ++These are currently limited to ++.BR srcs , ++.BR incs , ++.BR localincs , ++.BR resources , ++and ++.BR misc . ++These are pretty self-explanatory, but it should be noted that these ++lists are added to the \fB$SOURCES\fP construction variable as strings, ++NOT as SCons File Nodes. This is because they represent file ++names to be added to the project file, not the source files used to ++build the project file. ++ ++The above filename lists are all optional, ++although at least one must be specified ++for the resulting project file to be non-empty. ++ ++In addition to the above lists of values, ++the following values may be specified: ++ ++.BR target : ++The name of the target ++.B .dsp ++or ++.B .vcproj ++file. ++The correct ++suffix for the version of Visual Studio must be used, ++but the ++.B $MSVSPROJECTSUFFIX ++construction variable ++will be defined to the correct value (see example below). ++ ++.BR variant : ++The name of this particular variant. ++For Visual Studio 7 projects, ++this can also be a list of variant names. ++These are typically things like "Debug" or "Release", but really ++can be anything you want. ++For Visual Studio 7 projects, ++they may also specify a target platform ++separated from the variant name by a ++.B | ++(vertical pipe) ++character: ++.BR Debug|Xbox . ++The default target platform is Win32. ++Multiple calls to ++.BR MSVSProject () ++with different variants are allowed; ++all variants will be added to the project file with their appropriate ++build targets and sources. ++ ++.BR buildtarget : ++An optional string, node, or list of strings or nodes ++(one per build variant), to tell the Visual Studio debugger ++what output target to use in what build variant. ++The number of ++.B buildtarget ++entries must match the number of ++.B variant ++entries. ++ ++.BR runfile : ++The name of the file that Visual Studio 7 and later ++will run and debug. ++This appears as the value of the ++.B Output ++field in the resutling Visual Studio project file. ++If this is not specified, ++the default is the same as the specified ++.B buildtarget ++value. ++ ++Note that because &SCons; always executes its build commands ++from the directory in which the \fBSConstruct\fP file is located, ++if you generate a project file in a different directory ++than the \fBSConstruct\fP directory, ++users will not be able to double-click ++on the file name in compilation error messages ++displayed in the Visual Studio console output window. ++This can be remedied by adding the ++Visual C/C++ ++.B /FC ++compiler option to the \fB$CCFLAGS\fP variable ++so that the compiler will print ++the full path name of any ++files that cause compilation errors. ++ ++Example usage: ++ ++.ES ++barsrcs = ['bar.cpp'], ++barincs = ['bar.h'], ++barlocalincs = ['StdAfx.h'] ++barresources = ['bar.rc','resource.h'] ++barmisc = ['bar_readme.txt'] ++ ++dll = env.SharedLibrary(target = 'bar.dll', ++ source = barsrcs) ++ ++env.MSVSProject(target = 'Bar' + env['MSVSPROJECTSUFFIX'], ++ srcs = barsrcs, ++ incs = barincs, ++ localincs = barlocalincs, ++ resources = barresources, ++ misc = barmisc, ++ buildtarget = dll, ++ variant = 'Release') ++.EE ++ ++'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" ++.IP MSVSSolution() ++.IP env.MSVSSolution() ++Builds a Microsoft Visual Studio solution file. ++ ++This builds a Visual Studio solution file, ++based on the version of Visual Studio that is configured ++(either the latest installed version, ++or the version specified by ++.B $MSVS_VERSION ++in the construction environment). ++For Visual Studio 6, it will generate a ++.B .dsw ++file. ++For Visual Studio 7 (.NET), it will ++generate a ++.B .sln ++file. ++ ++The following values must be specified: ++ ++.BR target : ++The name of the target .dsw or .sln file. The correct ++suffix for the version of Visual Studio must be used, but the value ++.B $MSVSSOLUTIONSUFFIX ++will be defined to the correct value (see example below). ++ ++.BR variant : ++The name of this particular variant, or a list of variant ++names (the latter is only supported for MSVS 7 solutions). These are ++typically things like "Debug" or "Release", but really can be anything ++you want. For MSVS 7 they may also specify target platform, like this ++"Debug|Xbox". Default platform is Win32. ++ ++.BR projects : ++A list of project file names, or Project nodes returned by calls to the ++.BR MSVSProject () ++Builder, ++to be placed into the solution file. ++It should be noted that these file names are NOT added to the $SOURCES ++environment variable in form of files, but rather as strings. This ++is because they represent file names to be added to the solution file, ++not the source files used to build the solution file. ++ ++Example Usage: ++ ++.ES ++env.MSVSSolution(target = 'Bar' + env['MSVSSOLUTIONSUFFIX'], ++ projects = ['bar' + env['MSVSPROJECTSUFFIX']], ++ variant = 'Release') ++.EE ++ ++'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" ++.IP Object() ++.IP env.Object() ++A synonym for the ++.BR StaticObject () ++builder method. ++ ++'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" ++.IP Package() ++.IP env.Package() ++Builds software distribution packages. ++Packages consist of files to install and packaging information. ++The former may be specified with the \fIsource\fP parameter and may be left out, ++in which case the &FindInstalledFiles; function will collect ++all files that have an \fBInstall\fP() or \fBInstallAs\fP() Builder attached. ++If the \fItarget\fP is not specified ++it will be deduced from additional information given to this Builder. ++ ++The packaging information is specified ++with the help of construction variables documented below. ++This information is called a tag to stress that ++some of them can also be attached to files with the &Tag; function. ++The mandatory ones will complain if they were not specified. ++They vary depending on chosen target packager. ++ ++The target packager may be selected with the "PACKAGETYPE" command line ++option or with the \fB$PACKAGETYPE\fP construction variable. Currently ++the following packagers available: ++ ++ * msi - Microsoft Installer ++ * rpm - Redhat Package Manger ++ * ipkg - Itsy Package Management System ++ * tarbz2 - compressed tar ++ * targz - compressed tar ++ * zip - zip file ++ * src_tarbz2 - compressed tar source ++ * src_targz - compressed tar source ++ * src_zip - zip file source ++ ++An updated list is always available under the "package_type" option when ++running "scons --help" on a project that has packaging activated. ++.ES ++env = Environment(tools=['default', 'packaging']) ++env.Install('/bin/', 'my_program') ++env.Package( NAME = 'foo', ++ VERSION = '1.2.3', ++ PACKAGEVERSION = 0, ++ PACKAGETYPE = 'rpm', ++ LICENSE = 'gpl', ++ SUMMARY = 'balalalalal', ++ DESCRIPTION = 'this should be really really long', ++ X_RPM_GROUP = 'Application/fu', ++ SOURCE_URL = 'http://foo.org/foo-1.2.3.tar.gz' ++ ) ++.EE ++ ++'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" ++.IP PCH() ++.IP env.PCH() ++Builds a Microsoft Visual C++ precompiled header. ++Calling this builder method ++returns a list of two targets: the PCH as the first element, and the object ++file as the second element. Normally the object file is ignored. ++This builder method is only ++provided when Microsoft Visual C++ is being used as the compiler. ++The PCH builder method is generally used in ++conjuction with the PCH construction variable to force object files to use ++the precompiled header: ++ ++.ES ++env['PCH'] = env.PCH('StdAfx.cpp')[0] ++.EE ++ ++'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" ++.IP PDF() ++.IP env.PDF() ++Builds a \fB.pdf\fP file ++from a \fB.dvi\fP input file ++(or, by extension, a \fB.tex\fP, ++.BR .ltx , ++or ++\fB.latex\fP input file). ++The suffix specified by the \fB$PDFSUFFIX\fP construction variable ++(\fB.pdf\fP by default) ++is added automatically to the target ++if it is not already present. Example: ++ ++.ES ++# builds from aaa.tex ++env.PDF(target = 'aaa.pdf', source = 'aaa.tex') ++# builds bbb.pdf from bbb.dvi ++env.PDF(target = 'bbb', source = 'bbb.dvi') ++.EE ++ ++'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" ++.IP POInit() ++.IP env.POInit() ++This builder belongs to &t-link-msginit; tool. The builder initializes missing ++\fBPO\fP file(s) if \fB$POAUTOINIT\fP is set. If ++\fB$POAUTOINIT\fP is not set (default), \fBPOInit\fP() prints instruction for ++user (that is supposed to be a translator), telling how the ++\fBPO\fP file should be initialized. In normal projects ++.IR you should not use \fBPOInit\fP() and use \fBPOUpdate () ++instead\fP. \fBPOUpdate\fP() chooses intelligently between ++.BR msgmerge(1)\fP and \fBmsginit(1)\fP. \fBPOInit () ++always uses \fBmsginit(1)\fP and should be regarded as builder for ++special purposes or for temporary use (e.g. for quick, one time initialization ++of a bunch of \fBPO\fP files) or for tests. ++ ++Target nodes defined through \fBPOInit\fP() are not built by default (they're ++\fBIgnore\fPd from \fB'.'\fP node) but are added to ++special \fBAlias\fP (\fB'po-create'\fP by default). ++The alias name may be changed through the \fB$POCREATE_ALIAS\fP ++construction variable. All \fBPO\fP files defined through ++.BR POInit\fP() may be easily initialized by \fBscons po-create . ++ ++.IR Example 1 . ++Initialize \fBen.po\fP and \fBpl.po\fP from ++.BR messages.pot : ++.ES ++ # ... ++ env.POInit(['en', 'pl']) # messages.pot --> [en.po, pl.po] ++.EE ++.IP ++.IR Example 2 . ++Initialize \fBen.po\fP and \fBpl.po\fP from ++.BR foo.pot : ++.ES ++ # ... ++ env.POInit(['en', 'pl'], ['foo']) # foo.pot --> [en.po, pl.po] ++.EE ++.IP ++.IR Example 3 . ++Initialize \fBen.po\fP and \fBpl.po\fP from ++\fBfoo.pot\fP but using \fB$POTDOMAIN\fP construction ++variable: ++.ES ++ # ... ++ env.POInit(['en', 'pl'], POTDOMAIN='foo') # foo.pot --> [en.po, pl.po] ++.EE ++.IP ++.IR Example 4 . ++Initialize \fBPO\fP files for languages defined in ++\fBLINGUAS\fP file. The files will be initialized from template ++.BR messages.pot : ++.ES ++ # ... ++ env.POInit(LINGUAS_FILE = 1) # needs 'LINGUAS' file ++.EE ++.IP ++.IR Example 5 . ++Initialize \fBen.po\fP and \fBpl.pl\fP ++\fBPO\fP files plus files for languages defined in ++\fBLINGUAS\fP file. The files will be initialized from template ++.BR messages.pot : ++.ES ++ # ... ++ env.POInit(['en', 'pl'], LINGUAS_FILE = 1) ++.EE ++.IP ++.IR Example 6 . ++You may preconfigure your environment first, and then initialize ++\fBPO\fP files: ++.ES ++ # ... ++ env['POAUTOINIT'] = 1 ++ env['LINGUAS_FILE'] = 1 ++ env['POTDOMAIN'] = 'foo' ++ env.POInit() ++.EE ++which has same efect as: ++.ES ++ # ... ++ env.POInit(POAUTOINIT = 1, LINGUAS_FILE = 1, POTDOMAIN = 'foo') ++.EE ++ ++'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" ++.IP PostScript() ++.IP env.PostScript() ++Builds a \fB.ps\fP file ++from a \fB.dvi\fP input file ++(or, by extension, a \fB.tex\fP, ++.BR .ltx , ++or ++\fB.latex\fP input file). ++The suffix specified by the \fB$PSSUFFIX\fP construction variable ++(\fB.ps\fP by default) ++is added automatically to the target ++if it is not already present. Example: ++ ++.ES ++# builds from aaa.tex ++env.PostScript(target = 'aaa.ps', source = 'aaa.tex') ++# builds bbb.ps from bbb.dvi ++env.PostScript(target = 'bbb', source = 'bbb.dvi') ++.EE ++ ++'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" ++.IP POTUpdate() ++.IP env.POTUpdate() ++The builder belongs to &t-link-xgettext; tool. The builder updates target ++\fBPOT\fP file if exists or creates one if it doesn't. The node is ++not built by default (i.e. it is \fBIgnore\fPd from ++\fB'.'\fP), but only on demand (i.e. when given ++\fBPOT\fP file is required or when special alias is invoked). This ++builder adds its targe node (\fBmessages.pot\fP, say) to a ++special alias (\fBpot-update\fP by default, see ++\fB$POTUPDATE_ALIAS\fP) so you can update/create them easily with ++\fBscons pot-update\fP. The file is not written until there is no ++real change in internationalized messages (or in comments that enter ++\fBPOT\fP file). ++ ++<note> ++You may see \fBxgettext(1)\fP being invoked by the ++&t-link-xgettext; tool even if there is no real change in internationalized ++messages (so the \fBPOT\fP file is not being updated). This ++happens every time a source file has changed. In such case we invoke ++\fBxgettext(1)\fP and compare its output with the content of ++\fBPOT\fP file to decide whether the file should be updated or ++not.</para></note> ++ ++.I "Example 1." ++Let's create \fBpo/\fP directory and place following ++\fBSConstruct\fP script there: ++.ES ++ # SConstruct in 'po/' subdir ++ env = Environment( tools = ['default', 'xgettext'] ) ++ env.POTUpdate(['foo'], ['../a.cpp', '../b.cpp']) ++ env.POTUpdate(['bar'], ['../c.cpp', '../d.cpp']) ++.EE ++.IP ++ ++Then invoke scons few times: ++.ES ++ user@host:$ scons # Does not create foo.pot nor bar.pot ++ user@host:$ scons foo.pot # Updates or creates foo.pot ++ user@host:$ scons pot-update # Updates or creates foo.pot and bar.pot ++ user@host:$ scons -c # Does not clean foo.pot nor bar.pot. ++.EE ++the results shall be as the comments above say. ++ ++.I "Example 2." ++The \fBPOTUpdate\fP() builder may be used with no target specified, in which ++case default target \fBmessages.pot\fP will be used. The ++default target may also be overriden by setting \fB$POTDOMAIN\fP construction ++variable or providing it as an override to \fBPOTUpdate\fP() builder: ++.ES ++ # SConstruct script ++ env = Environment( tools = ['default', 'xgettext'] ) ++ env['POTDOMAIN'] = "foo" ++ env.POTUpdate(source = ["a.cpp", "b.cpp"]) # Creates foo.pot ... ++ env.POTUpdate(POTDOMAIN = "bar", source = ["c.cpp", "d.cpp"]) # and bar.pot ++.EE ++.IP ++.I "Example 3." ++The sources may be specified within separate file, for example ++.BR POTFILES.in : ++.ES ++ # POTFILES.in in 'po/' subdirectory ++ ../a.cpp ++ ../b.cpp ++ # end of file ++.EE ++.IP ++ ++The name of the file (\fBPOTFILES.in\fP) containing the list of ++sources is provided via \fB$XGETTEXTFROM\fP: ++.ES ++ # SConstruct file in 'po/' subdirectory ++ env = Environment( tools = ['default', 'xgettext'] ) ++ env.POTUpdate(XGETTEXTFROM = 'POTFILES.in') ++.EE ++.IP ++ ++ ++.I "Example 4." ++You may use \fB$XGETTEXTPATH\fP to define source search path. Assume, for ++example, that you have files \fBa.cpp\fP, ++.BR b.cpp\fP, \fBpo/SConstruct , ++.BR po/POTFILES.in\fP. Then your \fBPOT -related ++files could look as below: ++.ES ++ # POTFILES.in in 'po/' subdirectory ++ a.cpp ++ b.cpp ++ # end of file ++.EE ++ ++.ES ++ # SConstruct file in 'po/' subdirectory ++ env = Environment( tools = ['default', 'xgettext'] ) ++ env.POTUpdate(XGETTEXTFROM = 'POTFILES.in', XGETTEXTPATH='../') ++.EE ++.IP ++.I "Example 5." ++Multiple search directories may be defined within a list, i.e. ++\fBXGETTEXTPATH = ['dir1', 'dir2', ...]\fP. The order in the list ++determines the search order of source files. The path to the first file found ++is used. ++ ++Let's create \fB0/1/po/SConstruct\fP script: ++.ES ++ # SConstruct file in '0/1/po/' subdirectory ++ env = Environment( tools = ['default', 'xgettext'] ) ++ env.POTUpdate(XGETTEXTFROM = 'POTFILES.in', XGETTEXTPATH=['../', '../../']) ++.EE ++and \fB0/1/po/POTFILES.in\fP: ++.ES ++ # POTFILES.in in '0/1/po/' subdirectory ++ a.cpp ++ # end of file ++.EE ++Write two \fB*.cpp\fP files, the first one is ++.BR 0/a.cpp : ++.ES ++ /* 0/a.cpp */ ++ gettext("Hello from ../../a.cpp") ++.EE ++and the second is \fB0/1/a.cpp\fP: ++.ES ++ /* 0/1/a.cpp */ ++ gettext("Hello from ../a.cpp") ++.EE ++then run scons. You'll obtain \fB0/1/po/messages.pot\fP with the ++message \fB"Hello from ../a.cpp"\fP. When you reverse order in ++\fI$XGETTEXTFOM\fP, i.e. when you write SConscript as ++.ES ++ # SConstruct file in '0/1/po/' subdirectory ++ env = Environment( tools = ['default', 'xgettext'] ) ++ env.POTUpdate(XGETTEXTFROM = 'POTFILES.in', XGETTEXTPATH=['../../', '../']) ++.EE ++.IP ++ then the \fBmessages.pot\fP will contain ++\fBmsgid "Hello from ../../a.cpp"\fP line and not ++.BR msgid "Hello from ../a.cpp" . ++ ++ ++'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" ++.IP POUpdate() ++.IP env.POUpdate() ++The builder belongs to &t-link-msgmerge; tool. The builder updates ++\fBPO\fP files with \fBmsgmerge(1)\fP, or initializes ++missing \fBPO\fP files as described in documentation of ++&t-link-msginit; tool and \fBPOInit\fP() builder (see also ++\fB$POAUTOINIT\fP). Note, that \fBPOUpdate\fP() \fIdoes not add its ++targets to \fBpo-create\fP alias\fP as \fBPOInit\fP() ++does. ++ ++Target nodes defined through \fBPOUpdate\fP() are not built by default ++(they're \fBIgnore\fPd from \fB'.'\fP node). Instead, ++they are added automatically to special \fBAlias\fP ++(\fB'po-update'\fP by default). The alias name may be changed ++through the \fB$POUPDATE_ALIAS\fP construction variable. You can easilly ++update \fBPO\fP files in your project by \fBscons ++po-update\fP. ++ ++.I "Example 1." ++Update \fBen.po\fP and \fBpl.po\fP from ++.BR messages.pot\fP template (see also \fB$POTDOMAIN ), ++assuming that the later one exists or there is rule to build it (see ++.BR POTUpdate ()): ++.ES ++ # ... ++ env.POUpdate(['en','pl']) # messages.pot --> [en.po, pl.po] ++.EE ++.IP ++.I "Example 2." ++Update \fBen.po\fP and \fBpl.po\fP from ++\fBfoo.pot\fP template: ++.ES ++ # ... ++ env.POUpdate(['en', 'pl'], ['foo']) # foo.pot --> [en.po, pl.pl] ++.EE ++.IP ++.I "Example 3." ++Update \fBen.po\fP and \fBpl.po\fP from ++\fBfoo.pot\fP (another version): ++.ES ++ # ... ++ env.POUpdate(['en', 'pl'], POTDOMAIN='foo') # foo.pot -- > [en.po, pl.pl] ++.EE ++.IP ++.I "Example 4." ++Update files for languages defined in \fBLINGUAS\fP file. The ++files are updated from \fBmessages.pot\fP template: ++.ES ++ # ... ++ env.POUpdate(LINGUAS_FILE = 1) # needs 'LINGUAS' file ++.EE ++.IP ++.I "Example 5." ++Same as above, but update from \fBfoo.pot\fP template: ++.ES ++ # ... ++ env.POUpdate(LINGUAS_FILE = 1, source = ['foo']) ++.EE ++.IP ++.I "Example 6." ++Update \fBen.po\fP and \fBpl.po\fP plus files for ++languages defined in \fBLINGUAS\fP file. The files are updated ++from \fBmessages.pot\fP template: ++.ES ++ # produce 'en.po', 'pl.po' + files defined in 'LINGUAS': ++ env.POUpdate(['en', 'pl' ], LINGUAS_FILE = 1) ++.EE ++.IP ++.I "Example 7." ++Use \fB$POAUTOINIT\fP to automatically initialize \fBPO\fP file ++if it doesn't exist: ++.ES ++ # ... ++ env.POUpdate(LINGUAS_FILE = 1, POAUTOINIT = 1) ++.EE ++.IP ++.I "Example 8." ++Update \fBPO\fP files for languages defined in ++\fBLINGUAS\fP file. The files are updated from ++\fBfoo.pot\fP template. All necessary settings are ++pre-configured via environment. ++.ES ++ # ... ++ env['POAUTOINIT'] = 1 ++ env['LINGUAS_FILE'] = 1 ++ env['POTDOMAIN'] = 'foo' ++ env.POUpdate() ++.EE ++ ++'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" ++.IP Program() ++.IP env.Program() ++Builds an executable given one or more object files ++or C, C++, D, or Fortran source files. ++If any C, C++, D or Fortran source files are specified, ++then they will be automatically ++compiled to object files using the ++.BR Object () ++builder method; ++see that builder method's description for ++a list of legal source file suffixes ++and how they are interpreted. ++The target executable file prefix ++(specified by the \fB$PROGPREFIX\fP construction variable; nothing by default) ++and suffix ++(specified by the \fB$PROGSUFFIX\fP construction variable; ++by default, \fB.exe\fP on Windows systems, ++nothing on POSIX systems) ++are automatically added to the target if not already present. ++Example: ++ ++.ES ++env.Program(target = 'foo', source = ['foo.o', 'bar.c', 'baz.f']) ++.EE ++ ++'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" ++.IP RES() ++.IP env.RES() ++Builds a Microsoft Visual C++ resource file. ++This builder method is only provided ++when Microsoft Visual C++ or MinGW is being used as the compiler. The ++.B .res ++(or ++.B .o ++for MinGW) suffix is added to the target name if no other suffix is given. ++The source ++file is scanned for implicit dependencies as though it were a C file. ++Example: ++ ++.ES ++env.RES('resource.rc') ++.EE ++ ++'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" ++.IP RMIC() ++.IP env.RMIC() ++Builds stub and skeleton class files ++for remote objects ++from Java \fB.class\fP files. ++The target is a directory ++relative to which the stub ++and skeleton class files will be written. ++The source can be the names of \fB.class\fP files, ++or the objects return from the ++.BR Java () ++builder method. ++ ++If the construction variable ++.B $JAVACLASSDIR ++is set, either in the environment ++or in the call to the ++.BR RMIC () ++builder method itself, ++then the value of the variable ++will be stripped from the ++beginning of any \fB.class \fP ++file names. ++ ++.ES ++classes = env.Java(target = 'classdir', source = 'src') ++env.RMIC(target = 'outdir1', source = classes) ++ ++env.RMIC(target = 'outdir2', ++ source = ['package/foo.class', 'package/bar.class']) ++ ++env.RMIC(target = 'outdir3', ++ source = ['classes/foo.class', 'classes/bar.class'], ++ JAVACLASSDIR = 'classes') ++.EE ++ ++'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" ++.IP RPCGenClient() ++.IP env.RPCGenClient() ++Generates an RPC client stub (\fB_clnt.c\fP) file ++from a specified RPC (\fB.x\fP) source file. ++Because rpcgen only builds output files ++in the local directory, ++the command will be executed ++in the source file's directory by default. ++ ++.ES ++# Builds src/rpcif_clnt.c ++env.RPCGenClient('src/rpcif.x') ++.EE ++ ++'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" ++.IP RPCGenHeader() ++.IP env.RPCGenHeader() ++Generates an RPC header (\fB.h\fP) file ++from a specified RPC (\fB.x\fP) source file. ++Because rpcgen only builds output files ++in the local directory, ++the command will be executed ++in the source file's directory by default. ++ ++.ES ++# Builds src/rpcif.h ++env.RPCGenHeader('src/rpcif.x') ++.EE ++ ++'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" ++.IP RPCGenService() ++.IP env.RPCGenService() ++Generates an RPC server-skeleton (\fB_svc.c\fP) file ++from a specified RPC (\fB.x\fP) source file. ++Because rpcgen only builds output files ++in the local directory, ++the command will be executed ++in the source file's directory by default. ++ ++.ES ++# Builds src/rpcif_svc.c ++env.RPCGenClient('src/rpcif.x') ++.EE ++ ++'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" ++.IP RPCGenXDR() ++.IP env.RPCGenXDR() ++Generates an RPC XDR routine (\fB_xdr.c\fP) file ++from a specified RPC (\fB.x\fP) source file. ++Because rpcgen only builds output files ++in the local directory, ++the command will be executed ++in the source file's directory by default. ++ ++.ES ++# Builds src/rpcif_xdr.c ++env.RPCGenClient('src/rpcif.x') ++.EE ++ ++'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" ++.IP SharedLibrary() ++.IP env.SharedLibrary() ++Builds a shared library ++(\fB.so\fP on a POSIX system, ++\fB.dll\fP on Windows) ++given one or more object files ++or C, C++, D or Fortran source files. ++If any source files are given, ++then they will be automatically ++compiled to object files. ++The static library prefix and suffix (if any) ++are automatically added to the target. ++The target library file prefix ++(specified by the \fB$SHLIBPREFIX\fP construction variable; ++by default, \fBlib\fP on POSIX systems, ++nothing on Windows systems) ++and suffix ++(specified by the \fB$SHLIBSUFFIX\fP construction variable; ++by default, \fB.dll\fP on Windows systems, ++\fB.so\fP on POSIX systems) ++are automatically added to the target if not already present. ++Example: ++ ++.ES ++env.SharedLibrary(target = 'bar', source = ['bar.c', 'foo.o']) ++.EE ++.IP ++On Windows systems, the ++.BR SharedLibrary () ++builder method will always build an import ++(\fB.lib\fP) library ++in addition to the shared (\fB.dll\fP) library, ++adding a \fB.lib\fP library with the same basename ++if there is not already a \fB.lib\fP file explicitly ++listed in the targets. ++ ++Any object files listed in the ++.B source ++must have been built for a shared library ++(that is, using the ++.BR SharedObject () ++builder method). ++.B scons ++will raise an error if there is any mismatch. ++ ++On some platforms, there is a distinction between a shared library ++(loaded automatically by the system to resolve external references) ++and a loadable module (explicitly loaded by user action). ++For maximum portability, use the \fBLoadableModule\fP() builder for the latter. ++ ++When the \fB$SHLIBVERSION\fP construction variable is defined a versioned ++shared library is created. This modifies the \fB$SHLINKFLAGS\fP as required, ++adds the version number to the library name, and creates the symlinks that ++are needed. \fB$SHLIBVERSION\fP needs to be of the form X.Y.Z, where X ++and Y are numbers, and Z is a number but can also contain letters to designate ++alpha, beta, or release candidate patch levels. ++ ++This builder may create multiple links to the library. On a POSIX system, ++for the shared library libbar.so.2.3.1, the links created would be ++libbar.so, libbar.so.2, and libbar.so.2.3; on a Darwin (OSX) system ++the library would be libbar.2.3.1.dylib and the link would be ++libbar.dylib. ++ ++On Windows systems, specifying ++.B register=1 ++will cause the \fB.dll\fP to be ++registered after it is built using REGSVR32. ++The command that is run ++("regsvr32" by default) is determined by \fB$REGSVR\fP construction ++variable, and the flags passed are determined by \fB$REGSVRFLAGS\fP. By ++default, \fB$REGSVRFLAGS\fP includes the \fB/s\fP option, ++to prevent dialogs from popping ++up and requiring user attention when it is run. If you change ++\fB$REGSVRFLAGS\fP, be sure to include the \fB/s\fP option. ++For example, ++ ++.ES ++env.SharedLibrary(target = 'bar', ++ source = ['bar.cxx', 'foo.obj'], ++ register=1) ++.EE ++.IP ++will register \fBbar.dll\fP as a COM object ++when it is done linking it. ++ ++'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" ++.IP SharedObject() ++.IP env.SharedObject() ++Builds an object file for ++inclusion in a shared library. ++Source files must have one of the same set of extensions ++specified above for the ++.BR StaticObject () ++builder method. ++On some platforms building a shared object requires additional ++compiler option ++(e.g. \fB\-fPIC\fP for gcc) ++in addition to those needed to build a ++normal (static) object, but on some platforms there is no difference between a ++shared object and a normal (static) one. When there is a difference, SCons ++will only allow shared objects to be linked into a shared library, and will ++use a different suffix for shared objects. On platforms where there is no ++difference, SCons will allow both normal (static) ++and shared objects to be linked into a ++shared library, and will use the same suffix for shared and normal ++(static) objects. ++The target object file prefix ++(specified by the \fB$SHOBJPREFIX\fP construction variable; ++by default, the same as \fB$OBJPREFIX\fP) ++and suffix ++(specified by the \fB$SHOBJSUFFIX\fP construction variable) ++are automatically added to the target if not already present. ++Examples: ++ ++.ES ++env.SharedObject(target = 'ddd', source = 'ddd.c') ++env.SharedObject(target = 'eee.o', source = 'eee.cpp') ++env.SharedObject(target = 'fff.obj', source = 'fff.for') ++.EE ++.IP ++Note that the source files will be scanned ++according to the suffix mappings in the ++.B SourceFileScanner ++object. ++See the section "Scanner Objects," ++below, for more information. ++ ++'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" ++.IP StaticLibrary() ++.IP env.StaticLibrary() ++Builds a static library given one or more object files ++or C, C++, D or Fortran source files. ++If any source files are given, ++then they will be automatically ++compiled to object files. ++The static library prefix and suffix (if any) ++are automatically added to the target. ++The target library file prefix ++(specified by the \fB$LIBPREFIX\fP construction variable; ++by default, \fBlib\fP on POSIX systems, ++nothing on Windows systems) ++and suffix ++(specified by the \fB$LIBSUFFIX\fP construction variable; ++by default, \fB.lib\fP on Windows systems, ++\fB.a\fP on POSIX systems) ++are automatically added to the target if not already present. ++Example: ++ ++.ES ++env.StaticLibrary(target = 'bar', source = ['bar.c', 'foo.o']) ++.EE ++.IP ++Any object files listed in the ++.B source ++must have been built for a static library ++(that is, using the ++.BR StaticObject () ++builder method). ++.B scons ++will raise an error if there is any mismatch. ++ ++'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" ++.IP StaticObject() ++.IP env.StaticObject() ++Builds a static object file ++from one or more C, C++, D, or Fortran source files. ++Source files must have one of the following extensions: ++ ++.ES ++ .asm assembly language file ++ .ASM assembly language file ++ .c C file ++ .C Windows: C file ++ POSIX: C++ file ++ .cc C++ file ++ .cpp C++ file ++ .cxx C++ file ++ .cxx C++ file ++ .c++ C++ file ++ .C++ C++ file ++ .d D file ++ .f Fortran file ++ .F Windows: Fortran file ++ POSIX: Fortran file + C pre-processor ++ .for Fortran file ++ .FOR Fortran file ++ .fpp Fortran file + C pre-processor ++ .FPP Fortran file + C pre-processor ++ .m Object C file ++ .mm Object C++ file ++ .s assembly language file ++ .S Windows: assembly language file ++ ARM: CodeSourcery Sourcery Lite ++ .sx assembly language file + C pre-processor ++ POSIX: assembly language file + C pre-processor ++ .spp assembly language file + C pre-processor ++ .SPP assembly language file + C pre-processor ++.EE ++.IP ++The target object file prefix ++(specified by the \fB$OBJPREFIX\fP construction variable; nothing by default) ++and suffix ++(specified by the \fB$OBJSUFFIX\fP construction variable; ++\fB.obj\fP on Windows systems, ++\fB.o\fP on POSIX systems) ++are automatically added to the target if not already present. ++Examples: ++ ++.ES ++env.StaticObject(target = 'aaa', source = 'aaa.c') ++env.StaticObject(target = 'bbb.o', source = 'bbb.c++') ++env.StaticObject(target = 'ccc.obj', source = 'ccc.f') ++.EE ++.IP ++Note that the source files will be scanned ++according to the suffix mappings in ++.B SourceFileScanner ++object. ++See the section "Scanner Objects," ++below, for more information. ++ ++'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" ++.IP Substfile() ++.IP env.Substfile() ++The \fBSubstfile\fP() builder generates a single text file ++by concatenating the source files. ++Nested lists of sources are flattened. ++\fB$LINESEPARATOR\fP is used to separate the source files; ++see the description of \fBTextfile\fP() for details. ++ ++If a single source file is present with an \fB.in\fP suffix, ++the suffix is stripped and the remainder is used as the default target name. ++ ++The prefix and suffix specified by the \fB$SUBSTFILEPREFIX\fP ++and \fB$SUBSTFILESUFFIX\fP construction variables ++(the null string by default in both cases) ++are automatically added to the target if they are not already present. ++ ++If a construction variable named \fB$SUBST_DICT\fP is present, ++it may be either a Python dictionary or a sequence of (key,value) tuples. ++If the former, ++the dictionary is converted into a list of tuples in an arbitrary order, ++so if one key is a prefix of another key ++or if one substitution could be further expanded by another subsitition, ++it is unpredictible whether the expansion will occur. ++ ++Any occurences in the source of a key ++are replaced by the corresponding value, ++which may be a Python callable function or a string. ++If a value is a function, ++it is first called (with no arguments) to produce a string. ++The string is \fIsubst\fP-expanded ++and the result replaces the key. ++ ++.ES ++env = Environment(tools = ['default', 'textfile']) ++ ++env['prefix'] = '/usr/bin' ++script_dict = {'@prefix@': '/bin', @exec_prefix@: '$prefix'} ++env.Substfile('script.in', SUBST_DICT = script_dict) ++ ++conf_dict = {'%VERSION%': '1.2.3', '%BASE%': 'MyProg'} ++env.Substfile('config.h.in', conf_dict, SUBST_DICT = conf_dict) ++ ++# UNPREDICTABLE - one key is a prefix of another ++bad_foo = {'$foo': '$foo', '$foobar': '$foobar'} ++env.Substfile('foo.in', SUBST_DICT = bad_foo) ++ ++# PREDICTABLE - keys are applied longest first ++good_foo = [('$foobar', '$foobar'), ('$foo', '$foo')] ++env.Substfile('foo.in', SUBST_DICT = good_foo) ++ ++# UNPREDICTABLE - one substitution could be futher expanded ++bad_bar = {'@bar@': '@soap@', '@soap@': 'lye'} ++env.Substfile('bar.in', SUBST_DICT = bad_bar) ++ ++# PREDICTABLE - substitutions are expanded in order ++good_bar = (('@bar@', '@soap@'), ('@soap@', 'lye')) ++env.Substfile('bar.in', SUBST_DICT = good_bar) ++ ++# the SUBST_DICT may be in common (and not an override) ++substutions = {} ++subst = Environment(tools = ['textfile'], SUBST_DICT = substitutions) ++substitutions['@foo@'] = 'foo' ++subst['SUBST_DICT']['@bar@'] = 'bar' ++subst.Substfile('pgm1.c', [Value('#include "@foo@.h"'), ++ Value('#include "@bar@.h"'), ++ "common.in", ++ "pgm1.in" ++ ]) ++subst.Substfile('pgm2.c', [Value('#include "@foo@.h"'), ++ Value('#include "@bar@.h"'), ++ "common.in", ++ "pgm2.in" ++ ]) ++ ++.EE ++ ++'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" ++.IP Tar() ++.IP env.Tar() ++Builds a tar archive of the specified files ++and/or directories. ++Unlike most builder methods, ++the ++.BR Tar () ++builder method may be called multiple times ++for a given target; ++each additional call ++adds to the list of entries ++that will be built into the archive. ++Any source directories will ++be scanned for changes to ++any on-disk files, ++regardless of whether or not ++.B scons ++knows about them from other Builder or function calls. ++ ++.ES ++env.Tar('src.tar', 'src') ++ ++# Create the stuff.tar file. ++env.Tar('stuff', ['subdir1', 'subdir2']) ++# Also add "another" to the stuff.tar file. ++env.Tar('stuff', 'another') ++ ++# Set TARFLAGS to create a gzip-filtered archive. ++env = Environment(TARFLAGS = '-c -z') ++env.Tar('foo.tar.gz', 'foo') ++ ++# Also set the suffix to .tgz. ++env = Environment(TARFLAGS = '-c -z', ++ TARSUFFIX = '.tgz') ++env.Tar('foo') ++.EE ++ ++'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" ++.IP Textfile() ++.IP env.Textfile() ++The \fBTextfile\fP() builder generates a single text file. ++The source strings constitute the lines; ++nested lists of sources are flattened. ++\fB$LINESEPARATOR\fP is used to separate the strings. ++ ++If present, the \fB$SUBST_DICT\fP construction variable ++is used to modify the strings before they are written; ++see the \fBSubstfile\fP() description for details. ++ ++The prefix and suffix specified by the \fB$TEXTFILEPREFIX\fP ++and \fB$TEXTFILESUFFIX\fP construction variables ++(the null string and \fB.txt\fP by default, respectively) ++are automatically added to the target if they are not already present. ++Examples: ++ ++.ES ++# builds/writes foo.txt ++env.Textfile(target = 'foo.txt', source = ['Goethe', 42, 'Schiller']) ++ ++# builds/writes bar.txt ++env.Textfile(target = 'bar', ++ source = ['lalala', 'tanteratei'], ++ LINESEPARATOR='|*') ++ ++# nested lists are flattened automatically ++env.Textfile(target = 'blob', ++ source = ['lalala', ['Goethe', 42 'Schiller'], 'tanteratei']) ++ ++# files may be used as input by wraping them in File() ++env.Textfile(target = 'concat', # concatenate files with a marker between ++ source = [File('concat1'), File('concat2')], ++ LINESEPARATOR = '====================\\n') ++ ++Results are: ++foo.txt ++ ....8<---- ++ Goethe ++ 42 ++ Schiller ++ ....8<---- (no linefeed at the end) ++ ++bar.txt: ++ ....8<---- ++ lalala|*tanteratei ++ ....8<---- (no linefeed at the end) ++ ++blob.txt ++ ....8<---- ++ lalala ++ Goethe ++ 42 ++ Schiller ++ tanteratei ++ ....8<---- (no linefeed at the end) ++.EE ++ ++'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" ++.IP Translate() ++.IP env.Translate() ++This pseudo-builder belongs to &t-link-gettext; toolset. The builder extracts ++internationalized messages from source files, updates \fBPOT\fP ++template (if necessary) and then updates \fBPO\fP translations (if ++necessary). If \fB$POAUTOINIT\fP is set, missing \fBPO\fP files ++will be automatically created (i.e. without translator person intervention). ++The variables \fB$LINGUAS_FILE\fP and \fB$POTDOMAIN\fP are taken into ++acount too. All other construction variables used by \fBPOTUpdate\fP(), and ++\fBPOUpdate\fP() work here too. ++ ++.IR Example 1 . ++The simplest way is to specify input files and output languages inline in ++a SCons script when invoking \fBTranslate\fP() ++.ES ++# SConscript in 'po/' directory ++env = Environment( tools = ["default", "gettext"] ) ++env['POAUTOINIT'] = 1 ++env.Translate(['en','pl'], ['../a.cpp','../b.cpp']) ++.EE ++.IP ++.IR Example 2 . ++If you wish, you may also stick to conventional style known from ++<productname>autotools</productname>, i.e. using ++\fBPOTFILES.in\fP and \fBLINGUAS\fP files ++.ES ++# LINGUAS ++en pl ++#end ++.EE ++ ++.ES ++# POTFILES.in ++a.cpp ++b.cpp ++# end ++.EE ++ ++.ES ++# SConscript ++env = Environment( tools = ["default", "gettext"] ) ++env['POAUTOINIT'] = 1 ++env['XGETTEXTPATH'] = ['../'] ++env.Translate(LINGUAS_FILE = 1, XGETTEXTFROM = 'POTFILES.in') ++.EE ++.IP ++The last approach is perhaps the recommended one. It allows easily split ++internationalization/localization onto separate SCons scripts, where a script ++in source tree is responsible for translations (from sources to ++\fBPO\fP files) and script(s) under variant directories are ++responsible for compilation of \fBPO\fP to \fBMO\fP ++files to and for installation of \fBMO\fP files. The "gluing ++factor" synchronizing these two scripts is then the content of ++\fBLINGUAS\fP file. Note, that the updated ++\fBPOT\fP and \fBPO\fP files are usually going to be ++committed back to the repository, so they must be updated within the source ++directory (and not in variant directories). Additionaly, the file listing of ++\fBpo/\fP directory contains \fBLINGUAS\fP file, ++so the source tree looks familiar to translators, and they may work with the ++project in their usual way. ++ ++.IR Example 3 . ++Let's prepare a development tree as below ++.ES ++ project/ ++ + SConstruct ++ + build/ ++ + src/ ++ + po/ ++ + SConscript ++ + SConscript.i18n ++ + POTFILES.in ++ + LINGUAS ++.EE ++with \fBbuild\fP being variant directory. Write the top-level ++\fBSConstruct\fP script as follows ++.ES ++ # SConstruct ++ env = Environment( tools = ["default", "gettext"] ) ++ VariantDir('build', 'src', duplicate = 0) ++ env['POAUTOINIT'] = 1 ++ SConscript('src/po/SConscript.i18n', exports = 'env') ++ SConscript('build/po/SConscript', exports = 'env') ++.EE ++the \fBsrc/po/SConscript.i18n\fP as ++.ES ++ # src/po/SConscript.i18n ++ Import('env') ++ env.Translate(LINGUAS_FILE=1, XGETTEXTFROM='POTFILES.in', XGETTEXTPATH=['../']) ++.EE ++and the \fBsrc/po/SConscript\fP ++.ES ++ # src/po/SConscript ++ Import('env') ++ env.MOFiles(LINGUAS_FILE = 1) ++.EE ++Such setup produces \fBPOT\fP and \fBPO\fP files ++under source tree in \fBsrc/po/\fP and binary ++\fBMO\fP files under variant tree in ++\fBbuild/po/\fP. This way the \fBPOT\fP and ++\fBPO\fP files are separated from other output files, which must ++not be committed back to source repositories (e.g. \fBMO\fP ++files). ++ ++<note> ++In above example, the \fBPO\fP files are not updated, ++nor created automatically when you issue \fBscons '.'\fP command. ++The files must be updated (created) by hand via \fBscons ++po-update\fP and then \fBMO\fP files can be compiled by ++running \fBscons '.'\fP.</para></note> ++ ++ ++'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" ++.IP TypeLibrary() ++.IP env.TypeLibrary() ++Builds a Windows type library (\fB.tlb\fP) ++file from an input IDL file (\fB.idl\fP). ++In addition, it will build the associated inteface stub and ++proxy source files, ++naming them according to the base name of the \fB.idl\fP file. ++For example, ++ ++.ES ++env.TypeLibrary(source="foo.idl") ++.EE ++.IP ++Will create \fBfoo.tlb\fP, ++.BR foo.h , ++.BR foo_i.c , ++.B foo_p.c ++and ++.B foo_data.c ++files. ++ ++'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" ++.IP Uic() ++.IP env.Uic() ++Builds a header file, an implementation file and a moc file from an ui file. ++and returns the corresponding nodes in the above order. ++This builder is only available after using the tool 'qt'. Note: you can ++specify \fB.ui\fP files directly as source ++files to the \fBProgram\fP(), ++\fBLibrary\fP() and \fBSharedLibrary\fP() builders ++without using this builder. Using this builder lets you override the standard ++naming conventions (be careful: prefixes are always prepended to names of ++built files; if you don't want prefixes, you may set them to ``). ++See the \fB$QTDIR\fP variable for more information. ++Example: ++ ++.ES ++env.Uic('foo.ui') # -> ['foo.h', 'uic_foo.cc', 'moc_foo.cc'] ++env.Uic(target = Split('include/foo.h gen/uicfoo.cc gen/mocfoo.cc'), ++ source = 'foo.ui') # -> ['include/foo.h', 'gen/uicfoo.cc', 'gen/mocfoo.cc'] ++.EE ++ ++'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" ++.IP Zip() ++.IP env.Zip() ++Builds a zip archive of the specified files ++and/or directories. ++Unlike most builder methods, ++the ++.BR Zip () ++builder method may be called multiple times ++for a given target; ++each additional call ++adds to the list of entries ++that will be built into the archive. ++Any source directories will ++be scanned for changes to ++any on-disk files, ++regardless of whether or not ++.B scons ++knows about them from other Builder or function calls. ++ ++.ES ++env.Zip('src.zip', 'src') ++ ++# Create the stuff.zip file. ++env.Zip('stuff', ['subdir1', 'subdir2']) ++# Also add "another" to the stuff.tar file. ++env.Zip('stuff', 'another') ++.EE ++'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" ++'\" END GENERATED BUILDER DESCRIPTIONS ++'\" ++'\" The descriptions above of the various SCons Builders are generated ++'\" from the .xml files that live next to the various Python modules in ++'\" the build enginer library. If you're reading this [gnt]roff file ++'\" with an eye towards patching this man page, you can still submit ++'\" a diff against this text, but it will have to be translated to a ++'\" diff against the underlying .xml file before the patch is actually ++'\" accepted. If you do that yourself, it will make it easier to ++'\" integrate the patch. ++'\" ++'\" END GENERATED BUILDER DESCRIPTIONS ++'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" ++ ++.P ++All ++targets of builder methods automatically depend on their sources. ++An explicit dependency can ++be specified using the ++.B Depends ++method of a construction environment (see below). ++ ++In addition, ++.B scons ++automatically scans ++source files for various programming languages, ++so the dependencies do not need to be specified explicitly. ++By default, SCons can ++C source files, ++C++ source files, ++Fortran source files with ++.B .F ++(POSIX systems only), ++.B .fpp, ++or ++.B .FPP ++file extensions, ++and assembly language files with ++.B .S ++(POSIX systems only), ++.B .spp, ++or ++.B .SPP ++files extensions ++for C preprocessor dependencies. ++SCons also has default support ++for scanning D source files, ++You can also write your own Scanners ++to add support for additional source file types. ++These can be added to the default ++Scanner object used by the ++.BR Object (), ++.BR StaticObject (), ++and ++.BR SharedObject () ++Builders by adding them ++to the ++.B SourceFileScanner ++object. ++See the section "Scanner Objects" ++below, for more information about ++defining your own Scanner objects ++and using the ++.B SourceFileScanner ++object. ++ ++.SS Methods and Functions to Do Things ++In addition to Builder methods, ++.B scons ++provides a number of other construction environment methods ++and global functions to ++manipulate the build configuration. ++ ++Usually, a construction environment method ++and global function with the same name both exist ++so that you don't have to remember whether ++to a specific bit of functionality ++must be called with or without a construction environment. ++In the following list, ++if you call something as a global function ++it looks like: ++.ES ++.RI Function( arguments ) ++.EE ++and if you call something through a construction ++environment it looks like: ++.ES ++.RI env.Function( arguments ) ++.EE ++If you can call the functionality in both ways, ++then both forms are listed. ++ ++Global functions may be called from custom Python modules that you ++import into an SConscript file by adding the following ++to the Python module: ++ ++.ES ++from SCons.Script import * ++.EE ++ ++Except where otherwise noted, ++the same-named ++construction environment method ++and global function ++provide the exact same functionality. ++The only difference is that, ++where appropriate, ++calling the functionality through a construction environment will ++substitute construction variables into ++any supplied strings. ++For example: ++ ++.ES ++env = Environment(FOO = 'foo') ++Default('$FOO') ++env.Default('$FOO') ++.EE ++ ++In the above example, ++the first call to the global ++.B Default() ++function will actually add a target named ++.B $FOO ++to the list of default targets, ++while the second call to the ++.B env.Default() ++construction environment method ++will expand the value ++and add a target named ++.B foo ++to the list of default targets. ++For more on construction variable expansion, ++see the next section on ++construction variables. ++ ++Construction environment methods ++and global functions supported by ++.B scons ++include: ++ ++'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" ++'\" BEGIN GENERATED FUNCTION DESCRIPTIONS ++'\" ++'\" The descriptions below of the various SCons functions are generated ++'\" from the .xml files that live next to the various Python modules in ++'\" the build enginer library. If you're reading this [gnt]roff file ++'\" with an eye towards patching this man page, you can still submit ++'\" a diff against this text, but it will have to be translated to a ++'\" diff against the underlying .xml file before the patch is actually ++'\" accepted. If you do that yourself, it will make it easier to ++'\" integrate the patch. ++'\" ++'\" BEGIN GENERATED FUNCTION DESCRIPTIONS ++'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" ++ ++'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" ++.TP ++.RI Action( action ", [" cmd/str/fun ", [" var ", ...]] [option=" value ", ...])" ++.TP ++.IR env .Action( action ", [" cmd/str/fun ", [" var ", ...]] [option=" value ", ...])" ++Creates an Action object for ++the specified ++.IR action . ++See the section "Action Objects," ++below, for a complete explanation of the arguments and behavior. ++ ++Note that the ++.BR env.Action () ++form of the invocation will expand ++construction variables in any argument strings, ++including the ++.I action ++argument, at the time it is called ++using the construction variables in the ++.I env ++construction environment through which ++.BR env.Action () ++was called. ++The ++.BR Action () ++form delays all variable expansion ++until the Action object is actually used. ++ ++'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" ++.TP ++.RI AddMethod( object ", " function ", [" name ]) ++.TP ++.IR env .AddMethod( function ", [" name ]) ++When called with the ++.BR AddMethod () ++form, ++adds the specified ++.I function ++to the specified ++.I object ++as the specified method ++.IR name . ++When called with the ++.BR env.AddMethod () ++form, ++adds the specified ++.I function ++to the construction environment ++.I env ++as the specified method ++.IR name . ++In both cases, if ++.I name ++is omitted or ++.BR None , ++the name of the ++specified ++.I function ++itself is used for the method name. ++ ++Examples: ++ ++.ES ++# Note that the first argument to the function to ++# be attached as a method must be the object through ++# which the method will be called; the Python ++# convention is to call it 'self'. ++def my_method(self, arg): ++ print "my_method() got", arg ++ ++# Use the global AddMethod() function to add a method ++# to the Environment class. This ++AddMethod(Environment, my_method) ++env = Environment() ++env.my_method('arg') ++ ++# Add the function as a method, using the function ++# name for the method call. ++env = Environment() ++env.AddMethod(my_method, 'other_method_name') ++env.other_method_name('another arg') ++.EE ++ ++'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" ++.TP ++.RI AddOption( arguments ) ++This function adds a new command-line option to be recognized. ++The specified ++.I arguments ++are the same as supported by the standard Python ++.BR optparse.add_option () ++method (with a few additional capabilities noted below); ++see the documentation for ++.B optparse ++for a thorough discussion of its option-processing capabities. ++ ++In addition to the arguments and values supported by the ++.BR optparse.add_option () ++method, ++the SCons ++.BR AddOption () ++function allows you to set the ++.B nargs ++keyword value to ++.B '?' ++(a string with just the question mark) ++to indicate that the specified long option(s) take(s) an ++.I optional ++argument. ++When ++.B "nargs = '?'" ++is passed to the ++.BR AddOption () ++function, the ++.B const ++keyword argument ++may be used to supply the "default" ++value that should be used when the ++option is specified on the command line ++without an explicit argument. ++ ++If no ++.B default= ++keyword argument is supplied when calling ++.BR AddOption (), ++the option will have a default value of ++.BR None . ++ ++Once a new command-line option has been added with ++.BR AddOption (), ++the option value may be accessed using ++.BR GetOption () ++or ++.BR env.GetOption (). ++The value may also be set, using ++.BR SetOption () ++or ++.BR env.SetOption (), ++if conditions in a ++.B SConscript ++require overriding any default value. ++Note, however, that a ++value specified on the command line will ++.I always ++override a value set by any SConscript file. ++ ++Any specified ++.B help= ++strings for the new option(s) ++will be displayed by the ++.B \-H ++or ++.B \-h ++options ++(the latter only if no other help text is ++specified in the SConscript files). ++The help text for the local options specified by ++.BR AddOption () ++will appear below the SCons options themselves, ++under a separate ++.B "Local Options" ++heading. ++The options will appear in the help text ++in the order in which the ++.BR AddOption () ++calls occur. ++ ++Example: ++ ++.ES ++AddOption('--prefix', ++ dest='prefix', ++ nargs=1, type='string', ++ action='store', ++ metavar='DIR', ++ help='installation prefix') ++env = Environment(PREFIX = GetOption('prefix')) ++.EE ++ ++'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" ++.TP ++.RI AddPostAction( target ", " action ) ++.TP ++.IR env .AddPostAction( target ", " action ) ++Arranges for the specified ++.I action ++to be performed ++after the specified ++.I target ++has been built. ++The specified action(s) may be ++an Action object, or anything that ++can be converted into an Action object ++(see below). ++ ++When multiple targets are supplied, ++the action may be called multiple times, ++once after each action that generates ++one or more targets in the list. ++ ++'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" ++.TP ++.RI AddPreAction( target ", " action ) ++.TP ++.IR env .AddPreAction( target ", " action ) ++Arranges for the specified ++.I action ++to be performed ++before the specified ++.I target ++is built. ++The specified action(s) may be ++an Action object, or anything that ++can be converted into an Action object ++(see below). ++ ++When multiple targets are specified, ++the action(s) may be called multiple times, ++once before each action that generates ++one or more targets in the list. ++ ++Note that if any of the targets are built in multiple steps, ++the action will be invoked just ++before the "final" action that specifically ++generates the specified target(s). ++For example, when building an executable program ++from a specified source ++.B .c ++file via an intermediate object file: ++ ++.ES ++foo = Program('foo.c') ++AddPreAction(foo, 'pre_action') ++.EE ++.IP ++The specified ++.B pre_action ++would be executed before ++.B scons ++calls the link command that actually ++generates the executable program binary ++.BR foo , ++not before compiling the ++.B foo.c ++file into an object file. ++ ++'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" ++.TP ++.RI Alias( alias ", [" targets ", [" action ]]) ++.TP ++.IR env .Alias( alias ", [" targets ", [" action ]]) ++Creates one or more phony targets that ++expand to one or more other targets. ++An optional ++.I action ++(command) ++or list of actions ++can be specified that will be executed ++whenever the any of the alias targets are out-of-date. ++Returns the Node object representing the alias, ++which exists outside of any file system. ++This Node object, or the alias name, ++may be used as a dependency of any other target, ++including another alias. ++.BR Alias () ++can be called multiple times for the same ++alias to add additional targets to the alias, ++or additional actions to the list for this alias. ++ ++Examples: ++ ++.ES ++Alias('install') ++Alias('install', '/usr/bin') ++Alias(['install', 'install-lib'], '/usr/local/lib') ++ ++env.Alias('install', ['/usr/local/bin', '/usr/local/lib']) ++env.Alias('install', ['/usr/local/man']) ++ ++env.Alias('update', ['file1', 'file2'], "update_database $SOURCES") ++.EE ++ ++'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" ++.TP ++.RI AllowSubstExceptions([ exception ", ...])" ++Specifies the exceptions that will be allowed ++when expanding construction variables. ++By default, ++any construction variable expansions that generate a ++.B NameError ++or ++.B IndexError ++exception will expand to a ++.B '' ++(a null string) and not cause scons to fail. ++All exceptions not in the specified list ++will generate an error message ++and terminate processing. ++ ++If ++.BR AllowSubstExceptions () ++is called multiple times, ++each call completely overwrites the previous list ++of allowed exceptions. ++ ++Example: ++ ++.ES ++# Requires that all construction variable names exist. ++# (You may wish to do this if you want to enforce strictly ++# that all construction variables must be defined before use.) ++AllowSubstExceptions() ++ ++# Also allow a string containing a zero-division expansion ++# like '${1 / 0}' to evalute to ''. ++AllowSubstExceptions(IndexError, NameError, ZeroDivisionError) ++.EE ++ ++'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" ++.TP ++.RI AlwaysBuild( target ", ...)" ++.TP ++.IR env .AlwaysBuild( target ", ...)" ++Marks each given ++.I target ++so that it is always assumed to be out of date, ++and will always be rebuilt if needed. ++Note, however, that ++.BR AlwaysBuild () ++does not add its target(s) to the default target list, ++so the targets will only be built ++if they are specified on the command line, ++or are a dependent of a target specified on the command line--but ++they will ++.I always ++be built if so specified. ++Multiple targets can be passed in to a single call to ++.BR AlwaysBuild (). ++ ++'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" ++.TP ++.IR env .Append(key= val ", [...])" ++Appends the specified keyword arguments ++to the end of construction variables in the environment. ++If the Environment does not have ++the specified construction variable, ++it is simply added to the environment. ++If the values of the construction variable ++and the keyword argument are the same type, ++then the two values will be simply added together. ++Otherwise, the construction variable ++and the value of the keyword argument ++are both coerced to lists, ++and the lists are added together. ++(See also the Prepend method, below.) ++ ++Example: ++ ++.ES ++env.Append(CCFLAGS = ' -g', FOO = ['foo.yyy']) ++.EE ++ ++'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" ++.TP ++.IR env .AppendENVPath( name ", " newpath ", [" envname ", " sep ", " delete_existing ]) ++This appends new path elements to the given path in the ++specified external environment ++.RB ( ENV ++by default). ++This will only add ++any particular path once (leaving the last one it encounters and ++ignoring the rest, to preserve path order), ++and to help assure this, ++will normalize all paths (using ++.B os.path.normpath ++and ++.BR os.path.normcase ). ++This can also handle the ++case where the given old path variable is a list instead of a ++string, in which case a list will be returned instead of a string. ++ ++If ++.I delete_existing ++is 0, then adding a path that already exists ++will not move it to the end; it will stay where it is in the list. ++ ++Example: ++ ++.ES ++print 'before:',env['ENV']['INCLUDE'] ++include_path = '/foo/bar:/foo' ++env.AppendENVPath('INCLUDE', include_path) ++print 'after:',env['ENV']['INCLUDE'] ++ ++yields: ++before: /foo:/biz ++after: /biz:/foo/bar:/foo ++.EE ++ ++'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" ++.TP ++.IR env .AppendUnique(key= val ", [...], delete_existing=" 0) ++Appends the specified keyword arguments ++to the end of construction variables in the environment. ++If the Environment does not have ++the specified construction variable, ++it is simply added to the environment. ++If the construction variable being appended to is a list, ++then any value(s) that already exist in the ++construction variable will ++.I not ++be added again to the list. ++However, if delete_existing is 1, ++existing matching values are removed first, so ++existing values in the arg list move to the end of the list. ++ ++Example: ++ ++.ES ++env.AppendUnique(CCFLAGS = '-g', FOO = ['foo.yyy']) ++.EE ++ ++'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" ++.TP ++.IR env .BitKeeper() ++A factory function that ++returns a Builder object ++to be used to fetch source files ++using BitKeeper. ++The returned Builder ++is intended to be passed to the ++.BR SourceCode () ++function. ++ ++This function is deprecated. For details, see the entry for the ++.BR SourceCode () ++function. ++ ++Example: ++ ++.ES ++env.SourceCode('.', env.BitKeeper()) ++.EE ++ ++'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" ++.TP ++.RI BuildDir( build_dir ", " src_dir ", [" duplicate ]) ++.TP ++.IR env .BuildDir( build_dir ", " src_dir ", [" duplicate ]) ++Deprecated synonyms for ++.BR VariantDir () ++and ++.BR env.VariantDir (). ++The ++.I build_dir ++argument becomes the ++.I variant_dir ++argument of ++.BR VariantDir () ++or ++.BR env.VariantDir (). ++ ++'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" ++.TP ++.RI Builder( action ", [" arguments ]) ++.TP ++.IR env .Builder( action ", [" arguments ]) ++Creates a Builder object for ++the specified ++.IR action . ++See the section "Builder Objects," ++below, for a complete explanation of the arguments and behavior. ++ ++Note that the ++.BR env.Builder () ++form of the invocation will expand ++construction variables in any arguments strings, ++including the ++.I action ++argument, ++at the time it is called ++using the construction variables in the ++.I env ++construction environment through which ++.BR env.Builder () ++was called. ++The ++.BR Builder () ++form delays all variable expansion ++until after the Builder object is actually called. ++ ++'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" ++.TP ++.RI CacheDir( cache_dir ) ++.TP ++.IR env .CacheDir( cache_dir ) ++Specifies that ++.B scons ++will maintain a cache of derived files in ++.IR cache_dir . ++The derived files in the cache will be shared ++among all the builds using the same ++.BR CacheDir () ++call. ++Specifying a ++.I cache_dir ++of ++.B None ++disables derived file caching. ++ ++Calling ++.BR env.CacheDir () ++will only affect targets built ++through the specified construction environment. ++Calling ++.BR CacheDir () ++sets a global default ++that will be used by all targets built ++through construction environments ++that do ++.I not ++have an ++.BR env.CacheDir () ++specified. ++ ++When a ++.BR CacheDir () ++is being used and ++.B scons ++finds a derived file that needs to be rebuilt, ++it will first look in the cache to see if a ++derived file has already been built ++from identical input files and an identical build action ++(as incorporated into the MD5 build signature). ++If so, ++.B scons ++will retrieve the file from the cache. ++If the derived file is not present in the cache, ++.B scons ++will rebuild it and ++then place a copy of the built file in the cache ++(identified by its MD5 build signature), ++so that it may be retrieved by other ++builds that need to build the same derived file ++from identical inputs. ++ ++Use of a specified ++.BR CacheDir () ++may be disabled for any invocation ++by using the ++.B \-\-cache-disable ++option. ++ ++If the ++.B \-\-cache-force ++option is used, ++.B scons ++will place a copy of ++.I all ++derived files in the cache, ++even if they already existed ++and were not built by this invocation. ++This is useful to populate a cache ++the first time ++.BR CacheDir () ++is added to a build, ++or after using the ++.B \-\-cache-disable ++option. ++ ++When using ++.BR CacheDir (), ++.B scons ++will report, ++"Retrieved `file' from cache," ++unless the ++.B \-\-cache-show ++option is being used. ++When the ++.B \-\-cache-show ++option is used, ++.B scons ++will print the action that ++.I would ++have been used to build the file, ++without any indication that ++the file was actually retrieved from the cache. ++This is useful to generate build logs ++that are equivalent regardless of whether ++a given derived file has been built in-place ++or retrieved from the cache. ++ ++The ++.BR NoCache () ++method can be used to disable caching of specific files. This can be ++useful if inputs and/or outputs of some tool are impossible to ++predict or prohibitively large. ++ ++'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" ++.TP ++.RI Clean( targets ", " files_or_dirs ) ++.TP ++.IR env .Clean( targets ", " files_or_dirs ) ++This specifies a list of files or directories which should be removed ++whenever the targets are specified with the ++.B \-c ++command line option. ++The specified targets may be a list ++or an individual target. ++Multiple calls to ++.BR Clean () ++are legal, ++and create new targets or add files and directories to the ++clean list for the specified targets. ++ ++Multiple files or directories should be specified ++either as separate arguments to the ++.BR Clean () ++method, or as a list. ++.BR Clean () ++will also accept the return value of any of the construction environment ++Builder methods. ++Examples: ++ ++The related ++.BR NoClean () ++function overrides calling ++.BR Clean () ++for the same target, ++and any targets passed to both functions will ++.I not ++be removed by the ++.B \-c ++option. ++ ++Examples: ++ ++.ES ++Clean('foo', ['bar', 'baz']) ++Clean('dist', env.Program('hello', 'hello.c')) ++Clean(['foo', 'bar'], 'something_else_to_clean') ++.EE ++.IP ++In this example, ++installing the project creates a subdirectory for the documentation. ++This statement causes the subdirectory to be removed ++if the project is deinstalled. ++.ES ++Clean(docdir, os.path.join(docdir, projectname)) ++.EE ++ ++'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" ++.TP ++.IR env .Clone([key= val ", ...])" ++Returns a separate copy of a construction environment. ++If there are any keyword arguments specified, ++they are added to the returned copy, ++overwriting any existing values ++for the keywords. ++ ++Example: ++ ++.ES ++env2 = env.Clone() ++env3 = env.Clone(CCFLAGS = '-g') ++.EE ++.IP ++Additionally, a list of tools and a toolpath may be specified, as in ++the Environment constructor: ++ ++.ES ++def MyTool(env): env['FOO'] = 'bar' ++env4 = env.Clone(tools = ['msvc', MyTool]) ++.EE ++.IP ++The ++.I parse_flags ++keyword argument is also recognized: ++ ++.ES ++# create an environment for compiling programs that use wxWidgets ++wx_env = env.Clone(parse_flags = '!wx-config --cflags --cxxflags') ++.EE ++ ++'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" ++.TP ++.RI Command( target ", " source ", " action ", [key=" val ", ...])" ++.TP ++.IR env .Command( target ", " source ", " action ", [key=" val ", ...])" ++Executes a specific action ++(or list of actions) ++to build a target file or files. ++This is more convenient ++than defining a separate Builder object ++for a single special-case build. ++ ++As a special case, the ++.I source_scanner ++keyword argument can ++be used to specify ++a Scanner object ++that will be used to scan the sources. ++(The global ++.B DirScanner ++object can be used ++if any of the sources will be directories ++that must be scanned on-disk for ++changes to files that aren't ++already specified in other Builder of function calls.) ++ ++Any other keyword arguments specified override any ++same-named existing construction variables. ++ ++An action can be an external command, ++specified as a string, ++or a callable Python object; ++see "Action Objects," below, ++for more complete information. ++Also note that a string specifying an external command ++may be preceded by an ++.B @ ++(at-sign) ++to suppress printing the command in question, ++or by a ++.B \- ++(hyphen) ++to ignore the exit status of the external command. ++ ++Examples: ++ ++.ES ++env.Command('foo.out', 'foo.in', ++ "$FOO_BUILD < $SOURCES > $TARGET") ++ ++env.Command('bar.out', 'bar.in', ++ ["rm -f $TARGET", ++ "$BAR_BUILD < $SOURCES > $TARGET"], ++ ENV = {'PATH' : '/usr/local/bin/'}) ++ ++def rename(env, target, source): ++ import os ++ os.rename('.tmp', str(target[0])) ++ ++env.Command('baz.out', 'baz.in', ++ ["$BAZ_BUILD < $SOURCES > .tmp", ++ rename ]) ++.EE ++.IP ++Note that the ++.BR Command () ++function will usually assume, by default, ++that the specified targets and/or sources are Files, ++if no other part of the configuration ++identifies what type of entry it is. ++If necessary, you can explicitly specify ++that targets or source nodes should ++be treated as directoriese ++by using the ++.BR Dir () ++or ++.BR env.Dir () ++functions. ++ ++Examples: ++ ++.ES ++env.Command('ddd.list', Dir('ddd'), 'ls -l $SOURCE > $TARGET') ++ ++env['DISTDIR'] = 'destination/directory' ++env.Command(env.Dir('$DISTDIR')), None, make_distdir) ++.EE ++.IP ++(Also note that SCons will usually ++automatically create any directory necessary to hold a target file, ++so you normally don't need to create directories by hand.) ++ ++'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" ++.TP ++.RI Configure( env ", [" custom_tests ", " conf_dir ", " log_file ", " config_h ]) ++.TP ++.IR env .Configure([ custom_tests ", " conf_dir ", " log_file ", " config_h ]) ++Creates a Configure object for integrated ++functionality similar to GNU autoconf. ++See the section "Configure Contexts," ++below, for a complete explanation of the arguments and behavior. ++ ++'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" ++.TP ++.IR env .Copy([key= val ", ...])" ++A now-deprecated synonym for ++.BR env.Clone (). ++ ++'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" ++.TP ++.IR env .CVS( repository ", " module ) ++A factory function that ++returns a Builder object ++to be used to fetch source files ++from the specified ++CVS ++.IR repository . ++The returned Builder ++is intended to be passed to the ++.BR SourceCode () ++function. ++ ++This function is deprecated. For details, see the entry for the ++.BR SourceCode () ++function. ++ ++The optional specified ++.I module ++will be added to the beginning ++of all repository path names; ++this can be used, in essence, ++to strip initial directory names ++from the repository path names, ++so that you only have to ++replicate part of the repository ++directory hierarchy in your ++local build directory. ++ ++Examples: ++ ++.ES ++# Will fetch foo/bar/src.c ++# from /usr/local/CVSROOT/foo/bar/src.c. ++env.SourceCode('.', env.CVS('/usr/local/CVSROOT')) ++ ++# Will fetch bar/src.c ++# from /usr/local/CVSROOT/foo/bar/src.c. ++env.SourceCode('.', env.CVS('/usr/local/CVSROOT', 'foo')) ++ ++# Will fetch src.c ++# from /usr/local/CVSROOT/foo/bar/src.c. ++env.SourceCode('.', env.CVS('/usr/local/CVSROOT', 'foo/bar')) ++.EE ++ ++'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" ++.TP ++.RI Decider( function ) ++.TP ++.IR env .Decider( function ) ++Specifies that all up-to-date decisions for ++targets built through this construction environment ++will be handled by the specified ++.IR function . ++The ++.I function ++can be one of the following strings ++that specify the type of decision function ++to be performed: ++ ++.RS 10 ++.TP 6 ++.B timestamp-newer ++Specifies that a target shall be considered out of date and rebuilt ++if the dependency's timestamp is newer than the target file's timestamp. ++This is the behavior of the classic Make utility, ++and ++.B make ++can be used a synonym for ++.BR timestamp-newer . ++.TP 6 ++.B timestamp-match ++Specifies that a target shall be considered out of date and rebuilt ++if the dependency's timestamp is different than the ++timestamp recorded the last time the target was built. ++This provides behavior very similar to the classic Make utility ++(in particular, files are not opened up so that their ++contents can be checksummed) ++except that the target will also be rebuilt if a ++dependency file has been restored to a version with an ++.I earlier ++timestamp, such as can happen when restoring files from backup archives. ++.TP 6 ++.B MD5 ++Specifies that a target shall be considered out of date and rebuilt ++if the dependency's content has changed sine the last time ++the target was built, ++as determined be performing an MD5 checksum ++on the dependency's contents ++and comparing it to the checksum recorded the ++last time the target was built. ++.B content ++can be used as a synonym for ++.BR MD5 . ++.TP 6 ++.B MD5-timestamp ++Specifies that a target shall be considered out of date and rebuilt ++if the dependency's content has changed sine the last time ++the target was built, ++except that dependencies with a timestamp that matches ++the last time the target was rebuilt will be ++assumed to be up-to-date and ++.I not ++rebuilt. ++This provides behavior very similar ++to the ++.B MD5 ++behavior of always checksumming file contents, ++with an optimization of not checking ++the contents of files whose timestamps haven't changed. ++The drawback is that SCons will ++.I not ++detect if a file's content has changed ++but its timestamp is the same, ++as might happen in an automated script ++that runs a build, ++updates a file, ++and runs the build again, ++all within a single second. ++.RE ++ ++Examples: ++ ++.ES ++# Use exact timestamp matches by default. ++Decider('timestamp-match') ++ ++# Use MD5 content signatures for any targets built ++# with the attached construction environment. ++env.Decider('content') ++.EE ++.IP ++In addition to the above already-available functions, ++the ++.I function ++argument may be an actual Python function ++that takes the following three arguments: ++ ++.RS 10 ++.IP dependency ++The Node (file) which ++should cause the ++.I target ++to be rebuilt ++if it has "changed" since the last tme ++.I target ++was built. ++.IP target ++The Node (file) being built. ++In the normal case, ++this is what should get rebuilt ++if the ++.I dependency ++has "changed." ++.IP prev_ni ++Stored information about the state of the ++.I dependency ++the last time the ++.I target ++was built. ++This can be consulted to match various ++file characteristics ++such as the timestamp, ++size, or content signature. ++.RE ++ ++The ++.I function ++should return a ++.B True ++(non-zero) ++value if the ++.I dependency ++has "changed" since the last time ++the ++.I target ++was built ++(indicating that the target ++.I should ++be rebuilt), ++and ++.B False ++(zero) ++otherwise ++(indicating that the target should ++.I not ++be rebuilt). ++Note that the decision can be made ++using whatever criteria are appopriate. ++Ignoring some or all of the function arguments ++is perfectly normal. ++ ++Example: ++ ++.ES ++def my_decider(dependency, target, prev_ni): ++ return not os.path.exists(str(target)) ++ ++env.Decider(my_decider) ++.EE ++ ++'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" ++.TP ++.RI Default( targets ) ++.TP ++.IR env .Default( targets ) ++This specifies a list of default targets, ++which will be built by ++.B scons ++if no explicit targets are given on the command line. ++Multiple calls to ++.BR Default () ++are legal, ++and add to the list of default targets. ++ ++Multiple targets should be specified as ++separate arguments to the ++.BR Default () ++method, or as a list. ++.BR Default () ++will also accept the Node returned by any ++of a construction environment's ++builder methods. ++ ++Examples: ++ ++.ES ++Default('foo', 'bar', 'baz') ++env.Default(['a', 'b', 'c']) ++hello = env.Program('hello', 'hello.c') ++env.Default(hello) ++.EE ++.IP ++An argument to ++.BR Default () ++of ++.B None ++will clear all default targets. ++Later calls to ++.BR Default () ++will add to the (now empty) default-target list ++like normal. ++ ++The current list of targets added using the ++.BR Default () ++function or method is available in the ++.B DEFAULT_TARGETS ++list; ++see below. ++ ++'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" ++.TP ++.RI DefaultEnvironment([ args ]) ++Creates and returns a default construction environment object. ++This construction environment is used internally by SCons ++in order to execute many of the global functions in this list, ++and to fetch source files transparently ++from source code management systems. ++ ++'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" ++.TP ++.RI Depends( target ", " dependency ) ++.TP ++.IR env .Depends( target ", " dependency ) ++Specifies an explicit dependency; ++the ++.I target ++will be rebuilt ++whenever the ++.I dependency ++has changed. ++Both the specified ++.I target ++and ++.I dependency ++can be a string ++(usually the path name of a file or directory) ++or Node objects, ++or a list of strings or Node objects ++(such as returned by a Builder call). ++This should only be necessary ++for cases where the dependency ++is not caught by a Scanner ++for the file. ++ ++Example: ++ ++.ES ++env.Depends('foo', 'other-input-file-for-foo') ++ ++mylib = env.Library('mylib.c') ++installed_lib = env.Install('lib', mylib) ++bar = env.Program('bar.c') ++ ++# Arrange for the library to be copied into the installation ++# directory before trying to build the "bar" program. ++# (Note that this is for example only. A "real" library ++# dependency would normally be configured through the $LIBS ++# and $LIBPATH variables, not using an env.Depends() call.) ++ ++env.Depends(bar, installed_lib) ++.EE ++ ++'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" ++.TP ++.IR env .Dictionary([ vars ]) ++Returns a dictionary object ++containing copies of all of the ++construction variables in the environment. ++If there are any variable names specified, ++only the specified construction ++variables are returned in the dictionary. ++ ++Example: ++ ++.ES ++dict = env.Dictionary() ++cc_dict = env.Dictionary('CC', 'CCFLAGS', 'CCCOM') ++.EE ++ ++'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" ++.TP ++.RI Dir( name ", [" directory ]) ++.TP ++.IR env .Dir( name ", [" directory ]) ++This returns a Directory Node, ++an object that represents the specified directory ++.IR name . ++.I name ++can be a relative or absolute path. ++.I directory ++is an optional directory that will be used as the parent directory. ++If no ++.I directory ++is specified, the current script's directory is used as the parent. ++ ++If ++.I name ++is a list, SCons returns a list of Dir nodes. ++Construction variables are expanded in ++.IR name . ++ ++Directory Nodes can be used anywhere you ++would supply a string as a directory name ++to a Builder method or function. ++Directory Nodes have attributes and methods ++that are useful in many situations; ++see "File and Directory Nodes," below. ++ ++'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" ++.TP ++.IR env .Dump([ key ]) ++Returns a pretty printable representation of the environment. ++.IR key , ++if not ++.BR None , ++should be a string containing the name of the variable of interest. ++ ++This SConstruct: ++ ++.ES ++env=Environment() ++print env.Dump('CCCOM') ++.EE ++.IP ++will print: ++ ++.ES ++'$CC -c -o $TARGET $CCFLAGS $CPPFLAGS $_CPPDEFFLAGS $_CPPINCFLAGS $SOURCES' ++.EE ++.IP ++While this SConstruct: ++ ++.ES ++env=Environment() ++print env.Dump() ++.EE ++.IP ++will print: ++.ES ++{ 'AR': 'ar', ++ 'ARCOM': '$AR $ARFLAGS $TARGET $SOURCES\\n$RANLIB $RANLIBFLAGS $TARGET', ++ 'ARFLAGS': ['r'], ++ 'AS': 'as', ++ 'ASCOM': '$AS $ASFLAGS -o $TARGET $SOURCES', ++ 'ASFLAGS': [], ++ ... ++.EE ++ ++'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" ++.TP ++.RI EnsurePythonVersion( major ", " minor ) ++.TP ++.IR env .EnsurePythonVersion( major ", " minor ) ++Ensure that the Python version is at least ++.IR major\fP.\fIminor . ++This function will ++print out an error message and exit SCons with a non-zero exit code if the ++actual Python version is not late enough. ++ ++Example: ++ ++.ES ++EnsurePythonVersion(2,2) ++.EE ++ ++'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" ++.TP ++.RI EnsureSConsVersion( major ", " minor ", [" revision ]) ++.TP ++.IR env .EnsureSConsVersion( major ", " minor ", [" revision ]) ++Ensure that the SCons version is at least ++.IR major.minor , ++or ++.IR major.minor.revision . ++if ++.I revision ++is specified. ++This function will ++print out an error message and exit SCons with a non-zero exit code if the ++actual SCons version is not late enough. ++ ++Examples: ++ ++.ES ++EnsureSConsVersion(0,14) ++ ++EnsureSConsVersion(0,96,90) ++.EE ++ ++'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" ++.TP ++.RI Environment([key= value ", ...])" ++.TP ++.IR env .Environment([key= value ", ...])" ++Return a new construction environment ++initialized with the specified ++.IR key = value ++pairs. ++ ++'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" ++.TP ++.RI Execute( action ", [" strfunction ", " varlist ]) ++.TP ++.IR env .Execute( action ", [" strfunction ", " varlist ]) ++Executes an Action object. ++The specified ++.I action ++may be an Action object ++(see the section "Action Objects," ++below, for a complete explanation of the arguments and behavior), ++or it may be a command-line string, ++list of commands, ++or executable Python function, ++each of which will be converted ++into an Action object ++and then executed. ++The exit value of the command ++or return value of the Python function ++will be returned. ++ ++Note that ++.B scons ++will print an error message if the executed ++.I action ++fails--that is, ++exits with or returns a non-zero value. ++.B scons ++will ++.IR not , ++however, ++automatically terminate the build ++if the specified ++.I action ++fails. ++If you want the build to stop in response to a failed ++.BR Execute () ++call, ++you must explicitly check for a non-zero return value: ++ ++.ES ++Execute(Copy('file.out', 'file.in')) ++ ++if Execute("mkdir sub/dir/ectory"): ++ # The mkdir failed, don't try to build. ++ Exit(1) ++.EE ++ ++'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" ++.TP ++.RI Exit([ value ]) ++.TP ++.IR env .Exit([ value ]) ++This tells ++.B scons ++to exit immediately ++with the specified ++.IR value . ++A default exit value of ++.B 0 ++(zero) ++is used if no value is specified. ++ ++'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" ++.TP ++.RI Export( vars ) ++.TP ++.IR env .Export( vars ) ++This tells ++.B scons ++to export a list of variables from the current ++SConscript file to all other SConscript files. ++The exported variables are kept in a global collection, ++so subsequent calls to ++.BR Export () ++will over-write previous exports that have the same name. ++Multiple variable names can be passed to ++.BR Export () ++as separate arguments or as a list. ++Keyword arguments can be used to provide names and their values. ++A dictionary can be used to map variables to a different name when exported. ++Both local variables and global variables can be exported. ++ ++Examples: ++ ++.ES ++env = Environment() ++# Make env available for all SConscript files to Import(). ++Export("env") ++ ++package = 'my_name' ++# Make env and package available for all SConscript files:. ++Export("env", "package") ++ ++# Make env and package available for all SConscript files: ++Export(["env", "package"]) ++ ++# Make env available using the name debug: ++Export(debug = env) ++ ++# Make env available using the name debug: ++Export({"debug":env}) ++.EE ++.IP ++Note that the ++.BR SConscript () ++function supports an ++.I exports ++argument that makes it easier to to export a variable or ++set of variables to a single SConscript file. ++See the description of the ++.BR SConscript () ++function, below. ++ ++'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" ++.TP ++.RI File( name ", [" directory ]) ++.TP ++.IR env .File( name ", [" directory ]) ++This returns a ++File Node, ++an object that represents the specified file ++.IR name . ++.I name ++can be a relative or absolute path. ++.I directory ++is an optional directory that will be used as the parent directory. ++ ++If ++.I name ++is a list, SCons returns a list of File nodes. ++Construction variables are expanded in ++.IR name . ++ ++File Nodes can be used anywhere you ++would supply a string as a file name ++to a Builder method or function. ++File Nodes have attributes and methods ++that are useful in many situations; ++see "File and Directory Nodes," below. ++ ++'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" ++.TP ++.RI FindFile( file ", " dirs ) ++.TP ++.IR env .FindFile( file ", " dirs ) ++Search for ++.I file ++in the path specified by ++.IR dirs . ++.I dirs ++may be a list of directory names or a single directory name. ++In addition to searching for files that exist in the filesystem, ++this function also searches for derived files ++that have not yet been built. ++ ++Example: ++ ++.ES ++foo = env.FindFile('foo', ['dir1', 'dir2']) ++.EE ++ ++'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" ++.TP ++.RI FindInstalledFiles() ++.TP ++.IR env .FindInstalledFiles() ++Returns the list of targets set up by the ++.BR Install () ++or ++.BR InstallAs () ++builders. ++ ++This function serves as a convenient method to select the contents of ++a binary package. ++ ++Example: ++ ++.ES ++Install( '/bin', [ 'executable_a', 'executable_b' ] ) ++ ++# will return the file node list ++# [ '/bin/executable_a', '/bin/executable_b' ] ++FindInstalledFiles() ++ ++Install( '/lib', [ 'some_library' ] ) ++ ++# will return the file node list ++# [ '/bin/executable_a', '/bin/executable_b', '/lib/some_library' ] ++FindInstalledFiles() ++.EE ++ ++'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" ++.TP ++.RI FindPathDirs( variable ) ++Returns a function ++(actually a callable Python object) ++intended to be used as the ++.I path_function ++of a Scanner object. ++The returned object will look up the specified ++.I variable ++in a construction environment ++and treat the construction variable's value as a list of ++directory paths that should be searched ++(like ++.BR $CPPPATH , ++.BR $LIBPATH , ++etc.). ++ ++Note that use of ++.BR FindPathDirs () ++is generally preferable to ++writing your own ++.I path_function ++for the following reasons: ++1) The returned list will contain all appropriate directories ++found in source trees ++(when ++.BR VariantDir () ++is used) ++or in code repositories ++(when ++.BR Repository () ++or the ++.B \-Y ++option are used). ++2) scons will identify expansions of ++.I variable ++that evaluate to the same list of directories as, ++in fact, the same list, ++and avoid re-scanning the directories for files, ++when possible. ++ ++Example: ++ ++.ES ++def my_scan(node, env, path, arg): ++ # Code to scan file contents goes here... ++ return include_files ++ ++scanner = Scanner(name = 'myscanner', ++ function = my_scan, ++ path_function = FindPathDirs('MYPATH')) ++.EE ++ ++'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" ++.TP ++.RI FindSourceFiles(node= '"."') ++.TP ++.IR env .FindSourceFiles(node= '"."') ++Returns the list of nodes which serve as the source of the built files. ++It does so by inspecting the dependency tree starting at the optional ++argument ++.I node ++which defaults to the '"."'-node. It will then return all leaves of ++.IR node . ++These are all children which have no further children. ++ ++This function is a convenient method to select the contents of a Source ++Package. ++ ++Example: ++ ++.ES ++Program( 'src/main_a.c' ) ++Program( 'src/main_b.c' ) ++Program( 'main_c.c' ) ++ ++# returns ['main_c.c', 'src/main_a.c', 'SConstruct', 'src/main_b.c'] ++FindSourceFiles() ++ ++# returns ['src/main_b.c', 'src/main_a.c' ] ++FindSourceFiles( 'src' ) ++.EE ++.IP ++As you can see build support files (SConstruct in the above example) ++will also be returned by this function. ++ ++'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" ++.TP ++.RI Flatten( sequence ) ++.TP ++.IR env .Flatten( sequence ) ++Takes a sequence (that is, a Python list or tuple) ++that may contain nested sequences ++and returns a flattened list containing ++all of the individual elements in any sequence. ++This can be helpful for collecting ++the lists returned by calls to Builders; ++other Builders will automatically ++flatten lists specified as input, ++but direct Python manipulation of ++these lists does not. ++ ++Examples: ++ ++.ES ++foo = Object('foo.c') ++bar = Object('bar.c') ++ ++# Because `foo' and `bar' are lists returned by the Object() Builder, ++# `objects' will be a list containing nested lists: ++objects = ['f1.o', foo, 'f2.o', bar, 'f3.o'] ++ ++# Passing such a list to another Builder is all right because ++# the Builder will flatten the list automatically: ++Program(source = objects) ++ ++# If you need to manipulate the list directly using Python, you need to ++# call Flatten() yourself, or otherwise handle nested lists: ++for object in Flatten(objects): ++ print str(object) ++.EE ++ ++'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" ++.TP ++.RI GetBuildFailures() ++Returns a list of exceptions for the ++actions that failed while ++attempting to build targets. ++Each element in the returned list is a ++.I BuildError ++object ++with the following attributes ++that record various aspects ++of the build failure: ++ ++.B .node ++The node that was being built ++when the build failure occurred. ++ ++.B .status ++The numeric exit status ++returned by the command or Python function ++that failed when trying to build the ++specified Node. ++ ++.B .errstr ++The SCons error string ++describing the build failure. ++(This is often a generic ++message like "Error 2" ++to indicate that an executed ++command exited with a status of 2.) ++ ++.B .filename ++The name of the file or ++directory that actually caused the failure. ++This may be different from the ++.B .node ++attribute. ++For example, ++if an attempt to build a target named ++.B sub/dir/target ++fails because the ++.B sub/dir ++directory could not be created, ++then the ++.B .node ++attribute will be ++.B sub/dir/target ++but the ++.B .filename ++attribute will be ++.BR sub/dir . ++ ++.B .executor ++The SCons Executor object ++for the target Node ++being built. ++This can be used to retrieve ++the construction environment used ++for the failed action. ++ ++.B .action ++The actual SCons Action object that failed. ++This will be one specific action ++out of the possible list of ++actions that would have been ++executed to build the target. ++ ++.B .command ++The actual expanded command that was executed and failed, ++after expansion of ++.BR $TARGET , ++.BR $SOURCE , ++and other construction variables. ++ ++Note that the ++.BR GetBuildFailures () ++function ++will always return an empty list ++until any build failure has occurred, ++which means that ++.BR GetBuildFailures () ++will always return an empty list ++while the ++.B SConscript ++files are being read. ++Its primary intended use is ++for functions that will be ++executed before SCons exits ++by passing them to the ++standard Python ++.BR atexit.register () ++function. ++Example: ++ ++.ES ++import atexit ++ ++def print_build_failures(): ++ from SCons.Script import GetBuildFailures ++ for bf in GetBuildFailures(): ++ print "%s failed: %s" % (bf.node, bf.errstr) ++ ++atexit.register(print_build_failures) ++.EE ++ ++'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" ++.TP ++.RI GetBuildPath( file ", [...])" ++.TP ++.IR env .GetBuildPath( file ", [...])" ++Returns the ++.B scons ++path name (or names) for the specified ++.I file ++(or files). ++The specified ++.I file ++or files ++may be ++.B scons ++Nodes or strings representing path names. ++ ++'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" ++.TP ++.RI GetLaunchDir() ++.TP ++.IR env .GetLaunchDir() ++Returns the absolute path name of the directory from which ++.B scons ++was initially invoked. ++This can be useful when using the ++.BR \-u , ++.B \-U ++or ++.B \-D ++options, which internally ++change to the directory in which the ++.B SConstruct ++file is found. ++ ++'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" ++.TP ++.RI GetOption( name ) ++.TP ++.IR env .GetOption( name ) ++This function provides a way to query the value of ++SCons options set on scons command line ++(or set using the ++.BR SetOption () ++function). ++The options supported are: ++ ++.RS 10 ++.TP 6 ++.B cache_debug ++which corresponds to --cache-debug; ++.TP 6 ++.B cache_disable ++which corresponds to --cache-disable; ++.TP 6 ++.B cache_force ++which corresponds to --cache-force; ++.TP 6 ++.B cache_show ++which corresponds to --cache-show; ++.TP 6 ++.B clean ++which corresponds to -c, --clean and --remove; ++.TP 6 ++.B config ++which corresponds to --config; ++.TP 6 ++.B directory ++which corresponds to -C and --directory; ++.TP 6 ++.B diskcheck ++which corresponds to --diskcheck ++.TP 6 ++.B duplicate ++which corresponds to --duplicate; ++.TP 6 ++.B file ++which corresponds to -f, --file, --makefile and --sconstruct; ++.TP 6 ++.B help ++which corresponds to -h and --help; ++.TP 6 ++.B ignore_errors ++which corresponds to --ignore-errors; ++.TP 6 ++.B implicit_cache ++which corresponds to --implicit-cache; ++.TP 6 ++.B implicit_deps_changed ++which corresponds to --implicit-deps-changed; ++.TP 6 ++.B implicit_deps_unchanged ++which corresponds to --implicit-deps-unchanged; ++.TP 6 ++.B interactive ++which corresponds to --interact and --interactive; ++.TP 6 ++.B keep_going ++which corresponds to -k and --keep-going; ++.TP 6 ++.B max_drift ++which corresponds to --max-drift; ++.TP 6 ++.B no_exec ++which corresponds to -n, --no-exec, --just-print, --dry-run and --recon; ++.TP 6 ++.B no_site_dir ++which corresponds to --no-site-dir; ++.TP 6 ++.B num_jobs ++which corresponds to -j and --jobs; ++.TP 6 ++.B profile_file ++which corresponds to --profile; ++.TP 6 ++.B question ++which corresponds to -q and --question; ++.TP 6 ++.B random ++which corresponds to --random; ++.TP 6 ++.B repository ++which corresponds to -Y, --repository and --srcdir; ++.TP 6 ++.B silent ++which corresponds to -s, --silent and --quiet; ++.TP 6 ++.B site_dir ++which corresponds to --site-dir; ++.TP 6 ++.B stack_size ++which corresponds to --stack-size; ++.TP 6 ++.B taskmastertrace_file ++which corresponds to --taskmastertrace; and ++.TP 6 ++.B warn ++which corresponds to --warn and --warning. ++.RE ++ ++See the documentation for the ++corresponding command line object for information about each specific ++option. ++ ++'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" ++.TP ++.RI Glob( pattern ", [" ondisk ", " source ", " strings ]) ++.TP ++.IR env .Glob( pattern ", [" ondisk ", " source ", " strings ]) ++Returns Nodes (or strings) that match the specified ++.IR pattern , ++relative to the directory of the current ++.B SConscript ++file. ++The ++.BR env.Glob () ++form performs string substition on ++.I pattern ++and returns whatever matches ++the resulting expanded pattern. ++ ++The specified ++.I pattern ++uses Unix shell style metacharacters for matching: ++ ++.ES ++ * matches everything ++ ? matches any single character ++ [seq] matches any character in seq ++ [!seq] matches any char not in seq ++.EE ++.IP ++If the first character of a filename is a dot, ++it must be matched explicitly. ++Character matches do ++.I not ++span directory separators. ++ ++The ++.BR Glob () ++knows about ++repositories ++(see the ++.BR Repository () ++function) ++and source directories ++(see the ++.BR VariantDir () ++function) ++and ++returns a Node (or string, if so configured) ++in the local (SConscript) directory ++if matching Node is found ++anywhere in a corresponding ++repository or source directory. ++ ++The ++.I ondisk ++argument may be set to ++.B False ++(or any other non-true value) ++to disable the search for matches on disk, ++thereby only returning matches among ++already-configured File or Dir Nodes. ++The default behavior is to ++return corresponding Nodes ++for any on-disk matches found. ++ ++The ++.I source ++argument may be set to ++.B True ++(or any equivalent value) ++to specify that, ++when the local directory is a ++.BR VariantDir (), ++the returned Nodes should be from the ++corresponding source directory, ++not the local directory. ++ ++The ++.I strings ++argument may be set to ++.B True ++(or any equivalent value) ++to have the ++.BR Glob () ++function return strings, not Nodes, ++that represent the matched files or directories. ++The returned strings will be relative to ++the local (SConscript) directory. ++(Note that This may make it easier to perform ++arbitrary manipulation of file names, ++but if the returned strings are ++passed to a different ++.B SConscript ++file, ++any Node translation will be relative ++to the other ++.B SConscript ++directory, ++not the original ++.B SConscript ++directory.) ++ ++Examples: ++ ++.ES ++Program('foo', Glob('*.c')) ++Zip('/tmp/everything', Glob('.??*') + Glob('*')) ++.EE ++ ++'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" ++.TP ++.RI Help( text ) ++.TP ++.IR env .Help( text ) ++This specifies help text to be printed if the ++.B \-h ++argument is given to ++.BR scons . ++If ++.BR Help () ++is called multiple times, the text is appended together in the order ++that ++.BR Help () ++is called. ++ ++'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" ++.TP ++.RI Ignore( target ", " dependency ) ++.TP ++.IR env .Ignore( target ", " dependency ) ++The specified dependency file(s) ++will be ignored when deciding if ++the target file(s) need to be rebuilt. ++ ++You can also use ++.BR Ignore () ++to remove a target from the default build. ++In order to do this you must specify the directory the target will ++be built in as the target, and the file you want to skip building ++as the dependency. ++ ++Note that this will only remove the dependencies listed from ++the files built by default. It will still be built if that ++dependency is needed by another object being built. ++See the third and forth examples below. ++ ++Examples: ++ ++.ES ++env.Ignore('foo', 'foo.c') ++env.Ignore('bar', ['bar1.h', 'bar2.h']) ++env.Ignore('.','foobar.obj') ++env.Ignore('bar','bar/foobar.obj') ++.EE ++ ++'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" ++.TP ++.RI Import( vars ) ++.TP ++.IR env .Import( vars ) ++This tells ++.B scons ++to import a list of variables into the current SConscript file. This ++will import variables that were exported with ++.BR Export () ++or in the ++.I exports ++argument to ++.BR SConscript (). ++Variables exported by ++.BR SConscript () ++have precedence. ++Multiple variable names can be passed to ++.BR Import () ++as separate arguments or as a list. The variable "*" can be used ++to import all variables. ++ ++Examples: ++ ++.ES ++Import("env") ++Import("env", "variable") ++Import(["env", "variable"]) ++Import("*") ++.EE ++ ++'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" ++.TP ++.RI Literal( string ) ++.TP ++.IR env .Literal( string ) ++The specified ++.I string ++will be preserved as-is ++and not have construction variables expanded. ++ ++'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" ++.TP ++.RI Local( targets ) ++.TP ++.IR env .Local( targets ) ++The specified ++.I targets ++will have copies made in the local tree, ++even if an already up-to-date copy ++exists in a repository. ++Returns a list of the target Node or Nodes. ++ ++'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" ++.TP ++.IR env .MergeFlags( arg ", [" unique ]) ++Merges the specified ++.I arg ++values to the construction environment's construction variables. ++If the ++.I arg ++argument is not a dictionary, ++it is converted to one by calling ++.BR env.ParseFlags () ++on the argument ++before the values are merged. ++Note that ++.I arg ++must be a single value, ++so multiple strings must ++be passed in as a list, ++not as separate arguments to ++.BR env.MergeFlags (). ++ ++By default, ++duplicate values are eliminated; ++you can, however, specify ++.B unique=0 ++to allow duplicate ++values to be added. ++When eliminating duplicate values, ++any construction variables that end with ++the string ++.B PATH ++keep the left-most unique value. ++All other construction variables keep ++the right-most unique value. ++ ++Examples: ++ ++.ES ++# Add an optimization flag to $CCFLAGS. ++env.MergeFlags('-O3') ++ ++# Combine the flags returned from running pkg-config with an optimization ++# flag and merge the result into the construction variables. ++env.MergeFlags(['!pkg-config gtk+-2.0 --cflags', '-O3']) ++ ++# Combine an optimization flag with the flags returned from running pkg-config ++# twice and merge the result into the construction variables. ++env.MergeFlags(['-O3', ++ '!pkg-config gtk+-2.0 --cflags --libs', ++ '!pkg-config libpng12 --cflags --libs']) ++.EE ++ ++'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" ++.TP ++.RI NoCache( target ", ...)" ++.TP ++.IR env .NoCache( target ", ...)" ++Specifies a list of files which should ++.I not ++be cached whenever the ++.BR CacheDir () ++method has been activated. ++The specified targets may be a list ++or an individual target. ++ ++Multiple files should be specified ++either as separate arguments to the ++.BR NoCache () ++method, or as a list. ++.BR NoCache () ++will also accept the return value of any of the construction environment ++Builder methods. ++ ++Calling ++.BR NoCache () ++on directories and other non-File Node types has no effect because ++only File Nodes are cached. ++ ++Examples: ++ ++.ES ++NoCache('foo.elf') ++NoCache(env.Program('hello', 'hello.c')) ++.EE ++ ++'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" ++.TP ++.RI NoClean( target ", ...)" ++.TP ++.IR env .NoClean( target ", ...)" ++Specifies a list of files or directories which should ++.I not ++be removed whenever the targets (or their dependencies) ++are specified with the ++.B \-c ++command line option. ++The specified targets may be a list ++or an individual target. ++Multiple calls to ++.BR NoClean () ++are legal, ++and prevent each specified target ++from being removed by calls to the ++.B \-c ++option. ++ ++Multiple files or directories should be specified ++either as separate arguments to the ++.BR NoClean () ++method, or as a list. ++.BR NoClean () ++will also accept the return value of any of the construction environment ++Builder methods. ++ ++Calling ++.BR NoClean () ++for a target overrides calling ++.BR Clean () ++for the same target, ++and any targets passed to both functions will ++.I not ++be removed by the ++.B \-c ++option. ++ ++Examples: ++ ++.ES ++NoClean('foo.elf') ++NoClean(env.Program('hello', 'hello.c')) ++.EE ++ ++'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" ++.TP ++.IR env .ParseConfig( command ", [" function ", " unique ]) ++Calls the specified ++.I function ++to modify the environment as specified by the output of ++.IR command . ++The default ++.I function ++is ++.BR env.MergeFlags (), ++which expects the output of a typical ++.B *-config ++command ++(for example, ++.BR gtk-config ) ++and adds the options ++to the appropriate construction variables. ++By default, ++duplicate values are not ++added to any construction variables; ++you can specify ++.B unique=0 ++to allow duplicate ++values to be added. ++ ++Interpreted options ++and the construction variables they affect ++are as specified for the ++.BR env.ParseFlags () ++method (which this method calls). ++See that method's description, below, ++for a table of options and construction variables. ++ ++'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" ++.TP ++.RI ParseDepends( filename ", [" must_exist ", " only_one ]) ++.TP ++.IR env .ParseDepends( filename ", [" must_exist ", " only_one ]) ++Parses the contents of the specified ++.I filename ++as a list of dependencies in the style of ++.B Make ++or ++.BR mkdep , ++and explicitly establishes all of the listed dependencies. ++ ++By default, ++it is not an error ++if the specified ++.I filename ++does not exist. ++The optional ++.I must_exist ++argument may be set to a non-zero ++value to have ++scons ++throw an exception and ++generate an error if the file does not exist, ++or is otherwise inaccessible. ++ ++The optional ++.I only_one ++argument may be set to a non-zero ++value to have ++scons ++thrown an exception and ++generate an error ++if the file contains dependency ++information for more than one target. ++This can provide a small sanity check ++for files intended to be generated ++by, for example, the ++.B "gcc -M" ++flag, ++which should typically only ++write dependency information for ++one output file into a corresponding ++.B .d ++file. ++ ++The ++.I filename ++and all of the files listed therein ++will be interpreted relative to ++the directory of the ++.B SConscript ++file which calls the ++.BR ParseDepends () ++function. ++ ++'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" ++.TP ++.IR env .ParseFlags( flags ", ...)" ++Parses one or more strings containing ++typical command-line flags for GCC tool chains ++and returns a dictionary with the flag values ++separated into the appropriate SCons construction variables. ++This is intended as a companion to the ++.BR env.MergeFlags () ++method, but allows for the values in the returned dictionary ++to be modified, if necessary, ++before merging them into the construction environment. ++(Note that ++.BR env.MergeFlags () ++will call this method if its argument is not a dictionary, ++so it is usually not necessary to call ++.BR env.ParseFlags () ++directly unless you want to manipulate the values.) ++ ++If the first character in any string is ++an exclamation mark (!), ++the rest of the string is executed as a command, ++and the output from the command is ++parsed as GCC tool chain command-line flags ++and added to the resulting dictionary. ++ ++Flag values are translated accordig to the prefix found, ++and added to the following construction variables: ++ ++.ES ++-arch CCFLAGS, LINKFLAGS ++-D CPPDEFINES ++-framework FRAMEWORKS ++-frameworkdir= FRAMEWORKPATH ++-include CCFLAGS ++-isysroot CCFLAGS, LINKFLAGS ++-I CPPPATH ++-l LIBS ++-L LIBPATH ++-mno-cygwin CCFLAGS, LINKFLAGS ++-mwindows LINKFLAGS ++-pthread CCFLAGS, LINKFLAGS ++-std= CFLAGS ++-Wa, ASFLAGS, CCFLAGS ++-Wl,-rpath= RPATH ++-Wl,-R, RPATH ++-Wl,-R RPATH ++-Wl, LINKFLAGS ++-Wp, CPPFLAGS ++- CCFLAGS +++ CCFLAGS, LINKFLAGS ++.EE ++.IP ++Any other strings not associated with options ++are assumed to be the names of libraries ++and added to the ++.B $LIBS ++construction variable. ++ ++Examples (all of which produce the same result): ++ ++.ES ++dict = env.ParseFlags('-O2 -Dfoo -Dbar=1') ++dict = env.ParseFlags('-O2', '-Dfoo', '-Dbar=1') ++dict = env.ParseFlags(['-O2', '-Dfoo -Dbar=1']) ++dict = env.ParseFlags('-O2', '!echo -Dfoo -Dbar=1') ++.EE ++ ++'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" ++.TP ++.IR env .Perforce() ++A factory function that ++returns a Builder object ++to be used to fetch source files ++from the Perforce source code management system. ++The returned Builder ++is intended to be passed to the ++.BR SourceCode () ++function. ++ ++This function is deprecated. For details, see the entry for the ++.BR SourceCode () ++function. ++ ++Example: ++ ++.ES ++env.SourceCode('.', env.Perforce()) ++.EE ++.IP ++Perforce uses a number of external ++environment variables for its operation. ++Consequently, this function adds the ++following variables from the user's external environment ++to the construction environment's ++ENV dictionary: ++P4CHARSET, ++P4CLIENT, ++P4LANGUAGE, ++P4PASSWD, ++P4PORT, ++P4USER, ++SystemRoot, ++USER, ++and ++USERNAME. ++ ++'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" ++.TP ++.RI Platform( string ) ++The ++.BR Platform () ++form returns a callable object ++that can be used to initialize ++a construction environment using the ++platform keyword of the ++.BR Environment () ++function. ++ ++Example: ++ ++.ES ++env = Environment(platform = Platform('win32')) ++.EE ++.IP ++The ++.BR env.Platform () ++form applies the callable object for the specified platform ++.I string ++to the environment through which the method was called. ++ ++.ES ++env.Platform('posix') ++.EE ++.IP ++Note that the ++.B win32 ++platform adds the ++.B SystemDrive ++and ++.B SystemRoot ++variables from the user's external environment ++to the construction environment's ++.B $ENV ++dictionary. ++This is so that any executed commands ++that use sockets to connect with other systems ++(such as fetching source files from ++external CVS repository specifications like ++.BR :pserver:anonymous@cvs.sourceforge.net:/cvsroot/scons ) ++will work on Windows systems. ++ ++'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" ++.TP ++.RI Precious( target ", ...)" ++.TP ++.IR env .Precious( target ", ...)" ++Marks each given ++.I target ++as precious so it is not deleted before it is rebuilt. Normally ++.B scons ++deletes a target before building it. ++Multiple targets can be passed in to a single call to ++.BR Precious (). ++ ++'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" ++.TP ++.IR env .Prepend(key= val ", [...])" ++Appends the specified keyword arguments ++to the beginning of construction variables in the environment. ++If the Environment does not have ++the specified construction variable, ++it is simply added to the environment. ++If the values of the construction variable ++and the keyword argument are the same type, ++then the two values will be simply added together. ++Otherwise, the construction variable ++and the value of the keyword argument ++are both coerced to lists, ++and the lists are added together. ++(See also the Append method, above.) ++ ++Example: ++ ++.ES ++env.Prepend(CCFLAGS = '-g ', FOO = ['foo.yyy']) ++.EE ++ ++'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" ++.TP ++.IR env .PrependENVPath( name ", " newpath ", [" envname ", " sep ", " delete_existing ]) ++This appends new path elements to the given path in the ++specified external environment ++.RB ( $ENV ++by default). ++This will only add ++any particular path once (leaving the first one it encounters and ++ignoring the rest, to preserve path order), ++and to help assure this, ++will normalize all paths (using ++.B os.path.normpath ++and ++.BR os.path.normcase ). ++This can also handle the ++case where the given old path variable is a list instead of a ++string, in which case a list will be returned instead of a string. ++ ++If ++.I delete_existing ++is 0, then adding a path that already exists ++will not move it to the beginning; ++it will stay where it is in the list. ++ ++Example: ++ ++.ES ++print 'before:',env['ENV']['INCLUDE'] ++include_path = '/foo/bar:/foo' ++env.PrependENVPath('INCLUDE', include_path) ++print 'after:',env['ENV']['INCLUDE'] ++.EE ++.IP ++The above example will print: ++ ++.ES ++before: /biz:/foo ++after: /foo/bar:/foo:/biz ++.EE ++ ++'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" ++.TP ++.IR env .PrependUnique(key= val ", delete_existing=" "0, [...])" ++Appends the specified keyword arguments ++to the beginning of construction variables in the environment. ++If the Environment does not have ++the specified construction variable, ++it is simply added to the environment. ++If the construction variable being appended to is a list, ++then any value(s) that already exist in the ++construction variable will ++.I not ++be added again to the list. ++However, if delete_existing is 1, ++existing matching values are removed first, so ++existing values in the arg list move to the front of the list. ++ ++Example: ++ ++.ES ++env.PrependUnique(CCFLAGS = '-g', FOO = ['foo.yyy']) ++.EE ++ ++'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" ++.TP ++.RI Progress( callable ", [" interval ]) ++.TP ++.RI Progress( string ", [" interval ", " file ", " overwrite ]) ++.TP ++.RI Progress( list_of_strings ", [" interval ", " file ", " overwrite ]) ++Allows SCons to show progress made during the build ++by displaying a string or calling a function while ++evaluating Nodes (e.g. files). ++ ++If the first specified argument is a Python callable ++(a function or an object that has a ++.BR __call__ () ++method), ++the function will be called ++once every ++.I interval ++times a Node is evaluated. ++The callable will be passed the evaluated Node ++as its only argument. ++(For future compatibility, ++it's a good idea to also add ++.B *args ++and ++.B **kw ++as arguments to your function or method. ++This will prevent the code from breaking ++if SCons ever changes the interface ++to call the function with additional arguments in the future.) ++ ++An example of a simple custom progress function ++that prints a string containing the Node name ++every 10 Nodes: ++ ++.ES ++def my_progress_function(node, *args, **kw): ++ print 'Evaluating node %s!' % node ++Progress(my_progress_function, interval=10) ++.EE ++.IP ++A more complicated example of a custom progress display object ++that prints a string containing a count ++every 100 evaluated Nodes. ++Note the use of ++.B \\r ++(a carriage return) ++at the end so that the string ++will overwrite itself on a display: ++ ++.ES ++import sys ++class ProgressCounter(object): ++ count = 0 ++ def __call__(self, node, *args, **kw): ++ self.count += 100 ++ sys.stderr.write('Evaluated %s nodes\\r' % self.count) ++Progress(ProgressCounter(), interval=100) ++.EE ++.IP ++If the first argument ++.BR Progress () ++is a string, ++the string will be displayed ++every ++.I interval ++evaluated Nodes. ++The default is to print the string on standard output; ++an alternate output stream ++may be specified with the ++.B file= ++argument. ++The following will print a series of dots ++on the error output, ++one dot for every 100 evaluated Nodes: ++ ++.ES ++import sys ++Progress('.', interval=100, file=sys.stderr) ++.EE ++.IP ++If the string contains the verbatim substring ++.BR $TARGET , ++it will be replaced with the Node. ++Note that, for performance reasons, this is ++.I not ++a regular SCons variable substition, ++so you can not use other variables ++or use curly braces. ++The following example will print the name of ++every evaluated Node, ++using a ++.B \\r ++(carriage return) to cause each line to overwritten by the next line, ++and the ++.B overwrite= ++keyword argument to make sure the previously-printed ++file name is overwritten with blank spaces: ++ ++.ES ++import sys ++Progress('$TARGET\\r', overwrite=True) ++.EE ++.IP ++If the first argument to ++.BR Progress () ++is a list of strings, ++then each string in the list will be displayed ++in rotating fashion every ++.I interval ++evaluated Nodes. ++This can be used to implement a "spinner" ++on the user's screen as follows: ++ ++.ES ++Progress(['-\\r', '\\\\\\r', '|\\r', '/\\r'], interval=5) ++.EE ++ ++'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" ++.TP ++.IR env .RCS() ++A factory function that ++returns a Builder object ++to be used to fetch source files ++from RCS. ++The returned Builder ++is intended to be passed to the ++.BR SourceCode () ++function: ++ ++This function is deprecated. For details, see the entry for the ++.BR SourceCode () ++function. ++ ++Examples: ++ ++.ES ++env.SourceCode('.', env.RCS()) ++.EE ++.IP ++Note that ++.B scons ++will fetch source files ++from RCS subdirectories automatically, ++so configuring RCS ++as demonstrated in the above example ++should only be necessary if ++you are fetching from ++RCS,v ++files in the same ++directory as the source files, ++or if you need to explicitly specify RCS ++for a specific subdirectory. ++ ++'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" ++.TP ++.IR env .Replace(key= val ", [...])" ++Replaces construction variables in the Environment ++with the specified keyword arguments. ++ ++Example: ++ ++.ES ++env.Replace(CCFLAGS = '-g', FOO = 'foo.xxx') ++.EE ++ ++'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" ++.TP ++.RI Repository( directory ) ++.TP ++.IR env .Repository( directory ) ++Specifies that ++.I directory ++is a repository to be searched for files. ++Multiple calls to ++.BR Repository () ++are legal, ++and each one adds to the list of ++repositories that will be searched. ++ ++To ++.BR scons , ++a repository is a copy of the source tree, ++from the top-level directory on down, ++which may contain ++both source files and derived files ++that can be used to build targets in ++the local source tree. ++The canonical example would be an ++official source tree maintained by an integrator. ++If the repository contains derived files, ++then the derived files should have been built using ++.BR scons , ++so that the repository contains the necessary ++signature information to allow ++.B scons ++to figure out when it is appropriate to ++use the repository copy of a derived file, ++instead of building one locally. ++ ++Note that if an up-to-date derived file ++already exists in a repository, ++.B scons ++will ++.I not ++make a copy in the local directory tree. ++In order to guarantee that a local copy ++will be made, ++use the ++.BR Local () ++method. ++ ++'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" ++.TP ++.RI Requires( target ", " prerequisite ) ++.TP ++.IR env .Requires( target ", " prerequisite ) ++Specifies an order-only relationship ++between the specified target file(s) ++and the specified prerequisite file(s). ++The prerequisite file(s) ++will be (re)built, if necessary, ++.I before ++the target file(s), ++but the target file(s) do not actually ++depend on the prerequisites ++and will not be rebuilt simply because ++the prerequisite file(s) change. ++ ++Example: ++ ++.ES ++env.Requires('foo', 'file-that-must-be-built-before-foo') ++.EE ++ ++'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" ++.TP ++.RI Return([ vars "..., stop=" ]) ++By default, ++this stops processing the current SConscript ++file and returns to the calling SConscript file ++the values of the variables named in the ++.I vars ++string arguments. ++Multiple strings contaning variable names may be passed to ++.BR Return (). ++Any strings that contain white space ++ ++The optional ++.B stop= ++keyword argument may be set to a false value ++to continue processing the rest of the SConscript ++file after the ++.BR Return () ++call. ++This was the default behavior prior to SCons 0.98. ++However, the values returned ++are still the values of the variables in the named ++.I vars ++at the point ++.BR Return () ++is called. ++ ++Examples: ++ ++.ES ++# Returns without returning a value. ++Return() ++ ++# Returns the value of the 'foo' Python variable. ++Return("foo") ++ ++# Returns the values of the Python variables 'foo' and 'bar'. ++Return("foo", "bar") ++ ++# Returns the values of Python variables 'val1' and 'val2'. ++Return('val1 val2') ++.EE ++ ++'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" ++.TP ++.RI Scanner( function ", [" argument ", " keys ", " path_function ", " node_class ", " node_factory ", " scan_check ", " recursive ]) ++.TP ++.IR env .Scanner( function ", [" argument ", " keys ", " path_function ", " node_class ", " node_factory ", " scan_check ", " recursive ]) ++Creates a Scanner object for ++the specified ++.IR function . ++See the section "Scanner Objects," ++below, for a complete explanation of the arguments and behavior. ++ ++'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" ++.TP ++.IR env .SCCS() ++A factory function that ++returns a Builder object ++to be used to fetch source files ++from SCCS. ++The returned Builder ++is intended to be passed to the ++.BR SourceCode () ++function. ++ ++Example: ++ ++.ES ++env.SourceCode('.', env.SCCS()) ++.EE ++.IP ++Note that ++.B scons ++will fetch source files ++from SCCS subdirectories automatically, ++so configuring SCCS ++as demonstrated in the above example ++should only be necessary if ++you are fetching from ++.B s.SCCS ++files in the same ++directory as the source files, ++or if you need to explicitly specify SCCS ++for a specific subdirectory. ++ ++'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" ++.TP ++.RI SConscript( scripts ", [" exports ", " variant_dir ", " duplicate ]) ++.TP ++.IR env .SConscript( scripts ", [" exports ", " variant_dir ", " duplicate ]) ++.TP ++.RI SConscript(dirs= subdirs ", [name=" script ", " exports ", " variant_dir ", " duplicate ]) ++.TP ++.IR env .SConscript(dirs= subdirs ", [name=" script ", " exports ", " variant_dir ", " duplicate ]) ++This tells ++.B scons ++to execute ++one or more subsidiary SConscript (configuration) files. ++Any variables returned by a called script using ++.BR Return () ++will be returned by the call to ++.BR SConscript (). ++There are two ways to call the ++.BR SConscript () ++function. ++ ++The first way you can call ++.BR SConscript () ++is to explicitly specify one or more ++.I scripts ++as the first argument. ++A single script may be specified as a string; ++multiple scripts must be specified as a list ++(either explicitly or as created by ++a function like ++.BR Split ()). ++Examples: ++.ES ++SConscript('SConscript') # run SConscript in the current directory ++SConscript('src/SConscript') # run SConscript in the src directory ++SConscript(['src/SConscript', 'doc/SConscript']) ++config = SConscript('MyConfig.py') ++.EE ++.IP ++The second way you can call ++.BR SConscript () ++is to specify a list of (sub)directory names ++as a ++.BI dirs= subdirs ++keyword argument. ++In this case, ++.B scons ++will, by default, ++execute a subsidiary configuration file named ++.B SConscript ++in each of the specified directories. ++You may specify a name other than ++.B SConscript ++by supplying an optional ++.BI name= script ++keyword argument. ++The first three examples below have the same effect ++as the first three examples above: ++.ES ++SConscript(dirs='.') # run SConscript in the current directory ++SConscript(dirs='src') # run SConscript in the src directory ++SConscript(dirs=['src', 'doc']) ++SConscript(dirs=['sub1', 'sub2'], name='MySConscript') ++.EE ++.IP ++The optional ++.I exports ++argument provides a list of variable names or a dictionary of ++named values to export to the ++.IR script(s) . ++These variables are locally exported only to the specified ++.IR script(s) , ++and do not affect the global pool of variables used by the ++.BR Export () ++function. ++The subsidiary ++.I script(s) ++must use the ++.BR Import () ++function to import the variables. ++Examples: ++.ES ++foo = SConscript('sub/SConscript', exports='env') ++SConscript('dir/SConscript', exports=['env', 'variable']) ++SConscript(dirs='subdir', exports='env variable') ++SConscript(dirs=['one', 'two', 'three'], exports='shared_info') ++.EE ++.IP ++If the optional ++.I variant_dir ++argument is present, it causes an effect equivalent to the ++.BR VariantDir () ++method described below. ++(If ++.I variant_dir ++is not present, the ++.I duplicate ++argument is ignored.) ++The ++.I variant_dir ++argument is interpreted relative to the directory of the calling ++.B SConscript ++file. ++See the description of the ++.BR VariantDir () ++function below for additional details and restrictions. ++ ++If ++.I variant_dir ++is present, ++the source directory is the directory in which the ++.B SConscript ++file resides and the ++.B SConscript ++file is evaluated as if it were in the ++.I variant_dir ++directory: ++.ES ++SConscript('src/SConscript', variant_dir = 'build') ++.EE ++.IP ++is equivalent to ++ ++.ES ++VariantDir('build', 'src') ++SConscript('build/SConscript') ++.EE ++.IP ++This later paradigm is often used when the sources are ++in the same directory as the ++.BR SConstruct : ++ ++.ES ++SConscript('SConscript', variant_dir = 'build') ++.EE ++.IP ++is equivalent to ++ ++.ES ++VariantDir('build', '.') ++SConscript('build/SConscript') ++.EE ++.IP ++Here are some composite examples: ++ ++.ES ++# collect the configuration information and use it to build src and doc ++shared_info = SConscript('MyConfig.py') ++SConscript('src/SConscript', exports='shared_info') ++SConscript('doc/SConscript', exports='shared_info') ++.EE ++ ++.ES ++# build debugging and production versions. SConscript ++# can use Dir('.').path to determine variant. ++SConscript('SConscript', variant_dir='debug', duplicate=0) ++SConscript('SConscript', variant_dir='prod', duplicate=0) ++.EE ++ ++.ES ++# build debugging and production versions. SConscript ++# is passed flags to use. ++opts = { 'CPPDEFINES' : ['DEBUG'], 'CCFLAGS' : '-pgdb' } ++SConscript('SConscript', variant_dir='debug', duplicate=0, exports=opts) ++opts = { 'CPPDEFINES' : ['NODEBUG'], 'CCFLAGS' : '-O' } ++SConscript('SConscript', variant_dir='prod', duplicate=0, exports=opts) ++.EE ++ ++.ES ++# build common documentation and compile for different architectures ++SConscript('doc/SConscript', variant_dir='build/doc', duplicate=0) ++SConscript('src/SConscript', variant_dir='build/x86', duplicate=0) ++SConscript('src/SConscript', variant_dir='build/ppc', duplicate=0) ++.EE ++ ++'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" ++.TP ++.RI SConscriptChdir( value ) ++.TP ++.IR env .SConscriptChdir( value ) ++By default, ++.B scons ++changes its working directory ++to the directory in which each ++subsidiary SConscript file lives. ++This behavior may be disabled ++by specifying either: ++ ++.ES ++SConscriptChdir(0) ++env.SConscriptChdir(0) ++.EE ++.IP ++in which case ++.B scons ++will stay in the top-level directory ++while reading all SConscript files. ++(This may be necessary when building from repositories, ++when all the directories in which SConscript files may be found ++don't necessarily exist locally.) ++You may enable and disable ++this ability by calling ++SConscriptChdir() ++multiple times. ++ ++Example: ++ ++.ES ++env = Environment() ++SConscriptChdir(0) ++SConscript('foo/SConscript') # will not chdir to foo ++env.SConscriptChdir(1) ++SConscript('bar/SConscript') # will chdir to bar ++.EE ++ ++'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" ++.TP ++.RI SConsignFile([ file ", " dbm_module ]) ++.TP ++.IR env .SConsignFile([ file ", " dbm_module ]) ++This tells ++.B scons ++to store all file signatures ++in the specified database ++.IR file . ++If the ++.I file ++name is omitted, ++.B .sconsign ++is used by default. ++(The actual file name(s) stored on disk ++may have an appropriated suffix appended ++by the ++.IR dbm_module .) ++If ++.I file ++is not an absolute path name, ++the file is placed in the same directory as the top-level ++.B SConstruct ++file. ++ ++If ++.I file ++is ++.BR None , ++then ++.B scons ++will store file signatures ++in a separate ++.B .sconsign ++file in each directory, ++not in one global database file. ++(This was the default behavior ++prior to SCons 0.96.91 and 0.97.) ++ ++The optional ++.I dbm_module ++argument can be used to specify ++which Python database module ++The default is to use a custom ++.B SCons.dblite ++module that uses pickled ++Python data structures, ++and which works on all Python versions. ++ ++Examples: ++ ++.ES ++# Explicitly stores signatures in ".sconsign.dblite" ++# in the top-level SConstruct directory (the ++# default behavior). ++SConsignFile() ++ ++# Stores signatures in the file "etc/scons-signatures" ++# relative to the top-level SConstruct directory. ++SConsignFile("etc/scons-signatures") ++ ++# Stores signatures in the specified absolute file name. ++SConsignFile("/home/me/SCons/signatures") ++ ++# Stores signatures in a separate .sconsign file ++# in each directory. ++SConsignFile(None) ++.EE ++ ++'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" ++.TP ++.IR env .SetDefault(key= val ", [...])" ++Sets construction variables to default values specified with the keyword ++arguments if (and only if) the variables are not already set. ++The following statements are equivalent: ++ ++.ES ++env.SetDefault(FOO = 'foo') ++ ++if 'FOO' not in env: env['FOO'] = 'foo' ++.EE ++ ++'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" ++.TP ++.RI SetOption( name ", " value ) ++.TP ++.IR env .SetOption( name ", " value ) ++This function provides a way to set a select subset of the scons command ++line options from a SConscript file. The options supported are: ++ ++.RS 10 ++.TP 6 ++.B clean ++which corresponds to -c, --clean and --remove; ++.TP 6 ++.B duplicate ++which corresponds to --duplicate; ++.TP 6 ++.B help ++which corresponds to -h and --help; ++.TP 6 ++.B implicit_cache ++which corresponds to --implicit-cache; ++.TP 6 ++.B max_drift ++which corresponds to --max-drift; ++.TP 6 ++.B no_exec ++which corresponds to -n, --no-exec, --just-print, --dry-run and --recon; ++.TP 6 ++.B num_jobs ++which corresponds to -j and --jobs; ++.TP 6 ++.B random ++which corresponds to --random; and ++.TP 6 ++.B stack_size ++which corresponds to --stack-size. ++.RE ++ ++See the documentation for the ++corresponding command line object for information about each specific ++option. ++ ++Example: ++ ++.ES ++SetOption('max_drift', 1) ++.EE ++ ++'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" ++.TP ++.RI SideEffect( side_effect ", " target ) ++.TP ++.IR env .SideEffect( side_effect ", " target ) ++Declares ++.I side_effect ++as a side effect of building ++.IR target . ++Both ++.I side_effect ++and ++.I target ++can be a list, a file name, or a node. ++A side effect is a target file that is created or updated ++as a side effect of building other targets. ++For example, a Windows PDB ++file is created as a side effect of building the .obj ++files for a static library, ++and various log files are created updated ++as side effects of various TeX commands. ++If a target is a side effect of multiple build commands, ++.B scons ++will ensure that only one set of commands ++is executed at a time. ++Consequently, you only need to use this method ++for side-effect targets that are built as a result of ++multiple build commands. ++ ++Because multiple build commands may update ++the same side effect file, ++by default the ++.I side_effect ++target is ++.I not ++automatically removed ++when the ++.I target ++is removed by the ++.B \-c ++option. ++(Note, however, that the ++.I side_effect ++might be removed as part of ++cleaning the directory in which it lives.) ++If you want to make sure the ++.I side_effect ++is cleaned whenever a specific ++.I target ++is cleaned, ++you must specify this explicitly ++with the ++.BR Clean () ++or ++.BR env.Clean () ++function. ++ ++'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" ++.TP ++.RI SourceCode( entries ", " builder ) ++.TP ++.IR env .SourceCode( entries ", " builder ) ++This function and its associate factory functions are deprecated. ++There is no replacement. ++The intended use was to keep a local tree in sync with an archive, ++but in actuality the function only causes the archive ++to be fetched on the first run. ++Synchronizing with the archive is best done external to &SCons;. ++ ++Arrange for non-existent source files to ++be fetched from a source code management system ++using the specified ++.IR builder . ++The specified ++.I entries ++may be a Node, string or list of both, ++and may represent either individual ++source files or directories in which ++source files can be found. ++ ++For any non-existent source files, ++.B scons ++will search up the directory tree ++and use the first ++.BR SourceCode () ++builder it finds. ++The specified ++.I builder ++may be ++.BR None , ++in which case ++.B scons ++will not use a builder to fetch ++source files for the specified ++.IR entries , ++even if a ++.BR SourceCode () ++builder has been specified ++for a directory higher up the tree. ++ ++.B scons ++will, by default, ++fetch files from SCCS or RCS subdirectories ++without explicit configuration. ++This takes some extra processing time ++to search for the necessary ++source code management files on disk. ++You can avoid these extra searches ++and speed up your build a little ++by disabling these searches as follows: ++ ++.ES ++env.SourceCode('.', None) ++.EE ++.IP ++Note that if the specified ++.I builder ++is one you create by hand, ++it must have an associated ++construction environment to use ++when fetching a source file. ++ ++.B scons ++provides a set of canned factory ++functions that return appropriate ++Builders for various popular ++source code management systems. ++Canonical examples of invocation include: ++ ++.ES ++env.SourceCode('.', env.BitKeeper('/usr/local/BKsources')) ++env.SourceCode('src', env.CVS('/usr/local/CVSROOT')) ++env.SourceCode('/', env.RCS()) ++env.SourceCode(['f1.c', 'f2.c'], env.SCCS()) ++env.SourceCode('no_source.c', None) ++.EE ++ ++'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" ++.TP ++.RI SourceSignatures( type ) ++.TP ++.IR env .SourceSignatures( type ) ++Note: Although it is not yet officially deprecated, ++use of this function is discouraged. ++See the ++.BR Decider () ++function for a more flexible and straightforward way ++to configure SCons' decision-making. ++ ++The ++.BR SourceSignatures () ++function tells ++.B scons ++how to decide if a source file ++(a file that is not built from any other files) ++has changed since the last time it ++was used to build a particular target file. ++Legal values are ++.B MD5 ++or ++.BR timestamp . ++ ++If the environment method is used, ++the specified type of source signature ++is only used when deciding whether targets ++built with that environment are up-to-date or must be rebuilt. ++If the global function is used, ++the specified type of source signature becomes the default ++used for all decisions ++about whether targets are up-to-date. ++ ++.B MD5 ++means ++.B scons ++decides that a source file has changed ++if the MD5 checksum of its contents has changed since ++the last time it was used to rebuild a particular target file. ++ ++.B timestamp ++means ++.B scons ++decides that a source file has changed ++if its timestamp (modification time) has changed since ++the last time it was used to rebuild a particular target file. ++(Note that although this is similar to the behavior of Make, ++by default it will also rebuild if the dependency is ++.I older ++than the last time it was used to rebuild the target file.) ++ ++There is no different between the two behaviors ++for Python ++.BR Value () ++node objects. ++ ++.B MD5 ++signatures take longer to compute, ++but are more accurate than ++.B timestamp ++signatures. ++The default value is ++.BR MD5 . ++ ++Note that the default ++.BR TargetSignatures () ++setting (see below) ++is to use this ++.BR SourceSignatures () ++setting for any target files that are used ++to build other target files. ++Consequently, changing the value of ++.BR SourceSignatures () ++will, by default, ++affect the up-to-date decision for all files in the build ++(or all files built with a specific construction environment ++when ++.BR env.SourceSignatures () ++is used). ++ ++'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" ++.TP ++.RI Split( arg ) ++.TP ++.IR env .Split( arg ) ++Returns a list of file names or other objects. ++If arg is a string, ++it will be split on strings of white-space characters ++within the string, ++making it easier to write long lists of file names. ++If arg is already a list, ++the list will be returned untouched. ++If arg is any other type of object, ++it will be returned as a list ++containing just the object. ++ ++Example: ++ ++.ES ++files = Split("f1.c f2.c f3.c") ++files = env.Split("f4.c f5.c f6.c") ++files = Split(""" ++ f7.c ++ f8.c ++ f9.c ++""") ++.EE ++ ++'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" ++.TP ++.IR env .subst( input ", [" raw ", " target ", " source ", " conv ]) ++Performs construction variable interpolation ++on the specified string or sequence argument ++.IR input . ++ ++By default, ++leading or trailing white space will ++be removed from the result. ++and all sequences of white space ++will be compressed to a single space character. ++Additionally, any ++.B $( ++and ++.B $) ++character sequences will be stripped from the returned string, ++The optional ++.I raw ++argument may be set to ++.B 1 ++if you want to preserve white space and ++.BR $( - $) ++sequences. ++The ++.I raw ++argument may be set to ++.B 2 ++if you want to strip ++all characters between ++any ++.B $( ++and ++.B $) ++pairs ++(as is done for signature calculation). ++ ++If the input is a sequence ++(list or tuple), ++the individual elements of ++the sequence will be expanded, ++and the results will be returned as a list. ++ ++The optional ++.I target ++and ++.I source ++keyword arguments ++must be set to lists of ++target and source nodes, respectively, ++if you want the ++.BR $TARGET , ++.BR $TARGETS , ++.B $SOURCE ++and ++.B $SOURCES ++to be available for expansion. ++This is usually necessary if you are ++calling ++.BR env.subst () ++from within a Python function used ++as an SCons action. ++ ++Returned string values or sequence elements ++are converted to their string representation by default. ++The optional ++.I conv ++argument ++may specify a conversion function ++that will be used in place of ++the default. ++For example, if you want Python objects ++(including SCons Nodes) ++to be returned as Python objects, ++you can use the Python ++.B lambda ++idiom to pass in an unnamed function ++that simply returns its unconverted argument. ++ ++Example: ++ ++.ES ++print env.subst("The C compiler is: $CC") ++ ++def compile(target, source, env): ++ sourceDir = env.subst("${SOURCE.srcdir}", ++ target=target, ++ source=source) ++ ++source_nodes = env.subst('$EXPAND_TO_NODELIST', ++ conv=lambda x: x) ++.EE ++ ++'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" ++.TP ++.RI Tag( node ", " tags ) ++Annotates file or directory Nodes with ++information about how the ++.BR Package () ++Builder should package those files or directories. ++All tags are optional. ++ ++Examples: ++ ++.ES ++# makes sure the built library will be installed with 0644 file ++# access mode ++Tag( Library( 'lib.c' ), UNIX_ATTR="0644" ) ++ ++# marks file2.txt to be a documentation file ++Tag( 'file2.txt', DOC ) ++.EE ++ ++'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" ++.TP ++.RI TargetSignatures( type ) ++.TP ++.IR env .TargetSignatures( type ) ++Note: Although it is not yet officially deprecated, ++use of this function is discouraged. ++See the ++.BR Decider () ++function for a more flexible and straightforward way ++to configure SCons' decision-making. ++ ++The ++.BR TargetSignatures () ++function tells ++.B scons ++how to decide if a target file ++(a file that ++.I is ++built from any other files) ++has changed since the last time it ++was used to build some other target file. ++Legal values are ++.BR "build" ; ++.B "content" ++(or its synonym ++.BR "MD5" ); ++.BR "timestamp" ; ++or ++.BR "source" . ++ ++If the environment method is used, ++the specified type of target signature is only used ++for targets built with that environment. ++If the global function is used, ++the specified type of signature becomes the default ++used for all target files that ++don't have an explicit target signature type ++specified for their environments. ++ ++.B "content" ++(or its synonym ++.BR "MD5" ) ++means ++.B scons ++decides that a target file has changed ++if the MD5 checksum of its contents has changed since ++the last time it was used to rebuild some other target file. ++This means ++.B scons ++will open up ++MD5 sum the contents ++of target files after they're built, ++and may decide that it does not need to rebuild ++"downstream" target files if a file was ++rebuilt with exactly the same contents as the last time. ++ ++.B "timestamp" ++means ++.B scons ++decides that a target file has changed ++if its timestamp (modification time) has changed since ++the last time it was used to rebuild some other target file. ++(Note that although this is similar to the behavior of Make, ++by default it will also rebuild if the dependency is ++.I older ++than the last time it was used to rebuild the target file.) ++ ++.B "source" ++means ++.B scons ++decides that a target file has changed ++as specified by the corresponding ++.BR SourceSignatures () ++setting ++.RB ( "MD5" ++or ++.BR "timestamp" ). ++This means that ++.B scons ++will treat all input files to a target the same way, ++regardless of whether they are source files ++or have been built from other files. ++ ++.B "build" ++means ++.B scons ++decides that a target file has changed ++if it has been rebuilt in this invocation ++or if its content or timestamp have changed ++as specified by the corresponding ++.BR SourceSignatures () ++setting. ++This "propagates" the status of a rebuilt file ++so that other "downstream" target files ++will always be rebuilt, ++even if the contents or the timestamp ++have not changed. ++ ++.B "build" ++signatures are fastest because ++.B "content" ++(or ++.BR "MD5" ) ++signatures take longer to compute, ++but are more accurate than ++.B "timestamp" ++signatures, ++and can prevent unnecessary "downstream" rebuilds ++when a target file is rebuilt to the exact same contents ++as the previous build. ++The ++.B "source" ++setting provides the most consistent behavior ++when other target files may be rebuilt from ++both source and target input files. ++The default value is ++.BR "source" . ++ ++Because the default setting is ++.BR "source" , ++using ++.BR SourceSignatures () ++is generally preferable to ++.BR TargetSignatures (), ++so that the up-to-date decision ++will be consistent for all files ++(or all files built with a specific construction environment). ++Use of ++.BR TargetSignatures () ++provides specific control for how built target files ++affect their "downstream" dependencies. ++ ++'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" ++.TP ++.RI Tool( string ", [" toolpath ", **" kw ]) ++.TP ++.IR env .Tool( string ", [" toolpath ", **" kw ]) ++The ++.BR Tool () ++form of the function ++returns a callable object ++that can be used to initialize ++a construction environment using the ++tools keyword of the Environment() method. ++The object may be called with a construction ++environment as an argument, ++in which case the object will ++add the necessary variables ++to the construction environment ++and the name of the tool will be added to the ++.B $TOOLS ++construction variable. ++ ++Additional keyword arguments are passed to the tool's ++.BR generate () ++method. ++ ++Examples: ++ ++.ES ++env = Environment(tools = [ Tool('msvc') ]) ++ ++env = Environment() ++t = Tool('msvc') ++t(env) # adds 'msvc' to the TOOLS variable ++u = Tool('opengl', toolpath = ['tools']) ++u(env) # adds 'opengl' to the TOOLS variable ++.EE ++.IP ++The ++.BR env.Tool () ++form of the function ++applies the callable object for the specified tool ++.I string ++to the environment through which the method was called. ++ ++Additional keyword arguments are passed to the tool's ++.BR generate () ++method. ++ ++.ES ++env.Tool('gcc') ++env.Tool('opengl', toolpath = ['build/tools']) ++.EE ++ ++'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" ++.TP ++.RI Value( value ", [" built_value ]) ++.TP ++.IR env .Value( value ", [" built_value ]) ++Returns a Node object representing the specified Python value. Value ++Nodes can be used as dependencies of targets. If the result of ++calling ++.BI str( value ) ++changes between SCons runs, any targets depending on ++.BI Value( value ) ++will be rebuilt. ++(This is true even when using timestamps to decide if ++files are up-to-date.) ++When using timestamp source signatures, Value Nodes' ++timestamps are equal to the system time when the Node is created. ++ ++The returned Value Node object has a ++.BR write () ++method that can be used to "build" a Value Node ++by setting a new value. ++The optional ++.I built_value ++argument can be specified ++when the Value Node is created ++to indicate the Node should already be considered ++"built." ++There is a corresponding ++.BR read () ++method that will return the built value of the Node. ++ ++Examples: ++ ++.ES ++env = Environment() ++ ++def create(target, source, env): ++ # A function that will write a 'prefix=$SOURCE' ++ # string into the file name specified as the ++ # $TARGET. ++ f = open(str(target[0]), 'wb') ++ f.write('prefix=' + source[0].get_contents()) ++ ++# Fetch the prefix= argument, if any, from the command ++# line, and use /usr/local as the default. ++prefix = ARGUMENTS.get('prefix', '/usr/local') ++ ++# Attach a .Config() builder for the above function action ++# to the construction environment. ++env['BUILDERS']['Config'] = Builder(action = create) ++env.Config(target = 'package-config', source = Value(prefix)) ++ ++def build_value(target, source, env): ++ # A function that "builds" a Python Value by updating ++ # the the Python value with the contents of the file ++ # specified as the source of the Builder call ($SOURCE). ++ target[0].write(source[0].get_contents()) ++ ++output = env.Value('before') ++input = env.Value('after') ++ ++# Attach a .UpdateValue() builder for the above function ++# action to the construction environment. ++env['BUILDERS']['UpdateValue'] = Builder(action = build_value) ++env.UpdateValue(target = Value(output), source = Value(input)) ++.EE ++ ++'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" ++.TP ++.RI VariantDir( variant_dir ", " src_dir ", [" duplicate ]) ++.TP ++.IR env .VariantDir( variant_dir ", " src_dir ", [" duplicate ]) ++Use the ++.BR VariantDir () ++function to create a copy of your sources in another location: ++if a name under ++.I variant_dir ++is not found but exists under ++.IR src_dir , ++the file or directory is copied to ++.IR variant_dir . ++Target files can be built in a different directory ++than the original sources by simply refering to the sources (and targets) ++within the variant tree. ++ ++.BR VariantDir () ++can be called multiple times with the same ++.I src_dir ++to set up multiple builds with different options ++.RI ( variants ). ++The ++.I src_dir ++location must be in or underneath the SConstruct file's directory, and ++.I variant_dir ++may not be underneath ++.IR src_dir . ++ ++The default behavior is for ++.B scons ++to physically duplicate the source files in the variant tree. ++Thus, a build performed in the variant tree is guaranteed to be identical ++to a build performed in the source tree even if ++intermediate source files are generated during the build, ++or preprocessors or other scanners search for included files ++relative to the source file, ++or individual compilers or other invoked tools are hard-coded ++to put derived files in the same directory as source files. ++ ++If possible on the platform, ++the duplication is performed by linking rather than copying; ++see also the ++.B \-\-duplicate ++command-line option. ++Moreover, only the files needed for the build are duplicated; ++files and directories that are not used are not present in ++.IR variant_dir . ++ ++Duplicating the source tree may be disabled by setting the ++.B duplicate ++argument to ++.B 0 ++(zero). ++This will cause ++.B scons ++to invoke Builders using the path names of source files in ++.I src_dir ++and the path names of derived files within ++.IR variant_dir . ++This is always more efficient than ++.BR duplicate=1 , ++and is usually safe for most builds ++(but see above for cases that may cause problems). ++ ++Note that ++.BR VariantDir () ++works most naturally with a subsidiary SConscript file. ++However, you would then call the subsidiary SConscript file ++not in the source directory, but in the ++.IR variant_dir , ++regardless of the value of ++.BR duplicate . ++This is how you tell ++.B scons ++which variant of a source tree to build: ++ ++.ES ++# run src/SConscript in two variant directories ++VariantDir('build/variant1', 'src') ++SConscript('build/variant1/SConscript') ++VariantDir('build/variant2', 'src') ++SConscript('build/variant2/SConscript') ++.EE ++.IP ++See also the ++.BR SConscript () ++function, described above, ++for another way to specify a variant directory ++in conjunction with calling a subsidiary SConscript file. ++ ++Examples: ++ ++.ES ++# use names in the build directory, not the source directory ++VariantDir('build', 'src', duplicate=0) ++Program('build/prog', 'build/source.c') ++.EE ++ ++.ES ++# this builds both the source and docs in a separate subtree ++VariantDir('build', '.', duplicate=0) ++SConscript(dirs=['build/src','build/doc']) ++.EE ++ ++.ES ++# same as previous example, but only uses SConscript ++SConscript(dirs='src', variant_dir='build/src', duplicate=0) ++SConscript(dirs='doc', variant_dir='build/doc', duplicate=0) ++.EE ++ ++'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" ++.TP ++.RI WhereIs( program ", [" path ", " pathext ", " reject ]) ++.TP ++.IR env .WhereIs( program ", [" path ", " pathext ", " reject ]) ++Searches for the specified executable ++.IR program , ++returning the full path name to the program ++if it is found, ++and returning None if not. ++Searches the specified ++.IR path , ++the value of the calling environment's PATH ++.RB ( env['ENV']['PATH'] ), ++or the user's current external PATH ++.RB ( os.environ['PATH'] ) ++by default. ++On Windows systems, searches for executable ++programs with any of the file extensions ++listed in the specified ++.IR pathext , ++the calling environment's PATHEXT ++.RB ( env['ENV']['PATHEXT'] ) ++or the user's current PATHEXT ++.RB ( os.environ['PATHEXT'] ) ++by default. ++Will not select any ++path name or names ++in the specified ++.I reject ++list, if any. ++'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" ++'\" END GENERATED FUNCTION DESCRIPTIONS ++'\" ++'\" The descriptions above of the various SCons functions are generated ++'\" from the .xml files that live next to the various Python modules in ++'\" the build enginer library. If you're reading this [gnt]roff file ++'\" with an eye towards patching this man page, you can still submit ++'\" a diff against this text, but it will have to be translated to a ++'\" diff against the underlying .xml file before the patch is actually ++'\" accepted. If you do that yourself, it will make it easier to ++'\" integrate the patch. ++'\" ++'\" END GENERATED FUNCTION DESCRIPTIONS ++'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" ++ ++.SS SConscript Variables ++In addition to the global functions and methods, ++.B scons ++supports a number of Python variables ++that can be used in SConscript files ++to affect how you want the build to be performed. ++These variables may be accessed from custom Python modules that you ++import into an SConscript file by adding the following ++to the Python module: ++ ++.ES ++from SCons.Script import * ++.EE ++ ++'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" ++.TP ++ARGLIST ++A list ++.IR keyword = value ++arguments specified on the command line. ++Each element in the list is a tuple ++containing the ++.RI ( keyword , value ) ++of the argument. ++The separate ++.I keyword ++and ++.I value ++elements of the tuple ++can be accessed by ++subscripting for element ++.B [0] ++and ++.B [1] ++of the tuple, respectively. ++ ++Example: ++ ++.ES ++print "first keyword, value =", ARGLIST[0][0], ARGLIST[0][1] ++print "second keyword, value =", ARGLIST[1][0], ARGLIST[1][1] ++third_tuple = ARGLIST[2] ++print "third keyword, value =", third_tuple[0], third_tuple[1] ++for key, value in ARGLIST: ++ # process key and value ++.EE ++ ++'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" ++.TP ++ARGUMENTS ++A dictionary of all the ++.IR keyword = value ++arguments specified on the command line. ++The dictionary is not in order, ++and if a given keyword has ++more than one value assigned to it ++on the command line, ++the last (right-most) value is ++the one in the ++.B ARGUMENTS ++dictionary. ++ ++Example: ++ ++.ES ++if ARGUMENTS.get('debug', 0): ++ env = Environment(CCFLAGS = '-g') ++else: ++ env = Environment() ++.EE ++ ++'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" ++.TP ++BUILD_TARGETS ++A list of the targets which ++.B scons ++will actually try to build, ++regardless of whether they were specified on ++the command line or via the ++.BR Default () ++function or method. ++The elements of this list may be strings ++.I or ++nodes, so you should run the list through the Python ++.B str ++function to make sure any Node path names ++are converted to strings. ++ ++Because this list may be taken from the ++list of targets specified using the ++.BR Default () ++function or method, ++the contents of the list may change ++on each successive call to ++.BR Default (). ++See the ++.B DEFAULT_TARGETS ++list, below, ++for additional information. ++ ++Example: ++ ++.ES ++if 'foo' in BUILD_TARGETS: ++ print "Don't forget to test the `foo' program!" ++if 'special/program' in BUILD_TARGETS: ++ SConscript('special') ++.EE ++.IP ++Note that the ++.B BUILD_TARGETS ++list only contains targets expected listed ++on the command line or via calls to the ++.BR Default () ++function or method. ++It does ++.I not ++contain all dependent targets that will be built as ++a result of making the sure the explicitly-specified ++targets are up to date. ++ ++'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" ++.TP ++COMMAND_LINE_TARGETS ++A list of the targets explicitly specified on ++the command line. ++If there are no targets specified on the command line, ++the list is empty. ++This can be used, for example, ++to take specific actions only ++when a certain target or targets ++is explicitly being built. ++ ++Example: ++ ++.ES ++if 'foo' in COMMAND_LINE_TARGETS: ++ print "Don't forget to test the `foo' program!" ++if 'special/program' in COMMAND_LINE_TARGETS: ++ SConscript('special') ++.EE ++ ++'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" ++.TP ++DEFAULT_TARGETS ++A list of the target ++.I nodes ++that have been specified using the ++.BR Default () ++function or method. ++The elements of the list are nodes, ++so you need to run them through the Python ++.B str ++function to get at the path name for each Node. ++ ++Example: ++ ++.ES ++print str(DEFAULT_TARGETS[0]) ++if 'foo' in map(str, DEFAULT_TARGETS): ++ print "Don't forget to test the `foo' program!" ++.EE ++.IP ++The contents of the ++.B DEFAULT_TARGETS ++list change on on each successive call to the ++.BR Default () ++function: ++ ++.ES ++print map(str, DEFAULT_TARGETS) # originally [] ++Default('foo') ++print map(str, DEFAULT_TARGETS) # now a node ['foo'] ++Default('bar') ++print map(str, DEFAULT_TARGETS) # now a node ['foo', 'bar'] ++Default(None) ++print map(str, DEFAULT_TARGETS) # back to [] ++.EE ++.IP ++Consequently, be sure to use ++.B DEFAULT_TARGETS ++only after you've made all of your ++.BR Default () ++calls, ++or else simply be careful of the order ++of these statements in your SConscript files ++so that you don't look for a specific ++default target before it's actually been added to the list. ++ ++.SS Construction Variables ++.\" XXX From Gary Ruben, 23 April 2002: ++.\" I think it would be good to have an example with each construction ++.\" variable description in the documentation. ++.\" eg. ++.\" CC The C compiler ++.\" Example: env["CC"] = "c68x" ++.\" Default: env["CC"] = "cc" ++.\" ++.\" CCCOM The command line ... ++.\" Example: ++.\" To generate the compiler line c68x -ps -qq -mr -o $TARGET $SOURCES ++.\" env["CC"] = "c68x" ++.\" env["CFLAGS"] = "-ps -qq -mr" ++.\" env["CCCOM"] = "$CC $CFLAGS -o $TARGET $SOURCES ++.\" Default: ++.\" (I dunno what this is ;-) ++A construction environment has an associated dictionary of ++.I construction variables ++that are used by built-in or user-supplied build rules. ++Construction variables must follow the same rules for ++Python identifiers: ++the initial character must be an underscore or letter, ++followed by any number of underscores, letters, or digits. ++ ++A number of useful construction variables are automatically defined by ++scons for each supported platform, and additional construction variables ++can be defined by the user. The following is a list of the automatically ++defined construction variables: ++ ++'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" ++'\" BEGIN GENERATED CONSTRUCTION VARIABLE DESCRIPTIONS ++'\" ++'\" The descriptions below of the various SCons construction variables ++'\" are generated from the .xml files that live next to the various ++'\" Python modules in the build enginer library. If you're reading ++'\" this [gnt]roff file with an eye towards patching this man page, ++'\" you can still submit a diff against this text, but it will have to ++'\" be translated to a diff against the underlying .xml file before the ++'\" patch is actually accepted. If you do that yourself, it will make ++'\" it easier to integrate the patch. ++'\" ++'\" BEGIN GENERATED CONSTRUCTION VARIABLE DESCRIPTIONS ++'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" ++ ++.IP AR ++The static library archiver. ++ ++.IP ARCHITECTURE ++Specifies the system architecture for which ++the package is being built. ++The default is the system architecture ++of the machine on which SCons is running. ++This is used to fill in the ++.B Architecture: ++field in an Ipkg ++\fBcontrol\fP file, ++and as part of the name of a generated RPM file. ++ ++.IP ARCOM ++The command line used to generate a static library from object files. ++ ++.IP ARCOMSTR ++The string displayed when an object file ++is generated from an assembly-language source file. ++If this is not set, then \fB$ARCOM\fP (the command line) is displayed. ++ ++.ES ++env = Environment(ARCOMSTR = "Archiving $TARGET") ++.EE ++ ++.IP ARFLAGS ++General options passed to the static library archiver. ++ ++.IP AS ++The assembler. ++ ++.IP ASCOM ++The command line used to generate an object file ++from an assembly-language source file. ++ ++.IP ASCOMSTR ++The string displayed when an object file ++is generated from an assembly-language source file. ++If this is not set, then \fB$ASCOM\fP (the command line) is displayed. ++ ++.ES ++env = Environment(ASCOMSTR = "Assembling $TARGET") ++.EE ++ ++.IP ASFLAGS ++General options passed to the assembler. ++ ++.IP ASPPCOM ++The command line used to assemble an assembly-language ++source file into an object file ++after first running the file through the C preprocessor. ++Any options specified ++in the \fB$ASFLAGS\fP and \fB$CPPFLAGS\fP construction variables ++are included on this command line. ++ ++.IP ASPPCOMSTR ++The string displayed when an object file ++is generated from an assembly-language source file ++after first running the file through the C preprocessor. ++If this is not set, then \fB$ASPPCOM\fP (the command line) is displayed. ++ ++.ES ++env = Environment(ASPPCOMSTR = "Assembling $TARGET") ++.EE ++ ++.IP ASPPFLAGS ++General options when an assembling an assembly-language ++source file into an object file ++after first running the file through the C preprocessor. ++The default is to use the value of \fB$ASFLAGS\fP. ++ ++.IP BIBTEX ++The bibliography generator for the TeX formatter and typesetter and the ++LaTeX structured formatter and typesetter. ++ ++.IP BIBTEXCOM ++The command line used to call the bibliography generator for the ++TeX formatter and typesetter and the LaTeX structured formatter and ++typesetter. ++ ++.IP BIBTEXCOMSTR ++The string displayed when generating a bibliography ++for TeX or LaTeX. ++If this is not set, then \fB$BIBTEXCOM\fP (the command line) is displayed. ++ ++.ES ++env = Environment(BIBTEXCOMSTR = "Generating bibliography $TARGET") ++.EE ++ ++.IP BIBTEXFLAGS ++General options passed to the bibliography generator for the TeX formatter ++and typesetter and the LaTeX structured formatter and typesetter. ++ ++.IP BITKEEPER ++The BitKeeper executable. ++ ++.IP BITKEEPERCOM ++The command line for ++fetching source files using BitKeeper. ++ ++.IP BITKEEPERCOMSTR ++The string displayed when fetching ++a source file using BitKeeper. ++If this is not set, then \fB$BITKEEPERCOM\fP ++(the command line) is displayed. ++ ++.IP BITKEEPERGET ++The command (\fB$BITKEEPER\fP) and subcommand ++for fetching source files using BitKeeper. ++ ++.IP BITKEEPERGETFLAGS ++Options that are passed to the BitKeeper ++.B get ++subcommand. ++ ++.IP BUILDERS ++A dictionary mapping the names of the builders ++available through this environment ++to underlying Builder objects. ++Builders named ++Alias, CFile, CXXFile, DVI, Library, Object, PDF, PostScript, and Program ++are available by default. ++If you initialize this variable when an ++Environment is created: ++ ++.ES ++env = Environment(BUILDERS = {'NewBuilder' : foo}) ++.EE ++.IP ++the default Builders will no longer be available. ++To use a new Builder object in addition to the default Builders, ++add your new Builder object like this: ++ ++.ES ++env = Environment() ++env.Append(BUILDERS = {'NewBuilder' : foo}) ++.EE ++.IP ++or this: ++ ++.ES ++env = Environment() ++env['BUILDERS]['NewBuilder'] = foo ++.EE ++ ++.IP CC ++The C compiler. ++ ++.IP CCCOM ++The command line used to compile a C source file to a (static) object ++file. Any options specified in the \fB$CFLAGS\fP, \fB$CCFLAGS\fP and ++\fB$CPPFLAGS\fP construction variables are included on this command ++line. ++ ++.IP CCCOMSTR ++The string displayed when a C source file ++is compiled to a (static) object file. ++If this is not set, then \fB$CCCOM\fP (the command line) is displayed. ++ ++.ES ++env = Environment(CCCOMSTR = "Compiling static object $TARGET") ++.EE ++ ++.IP CCFLAGS ++General options that are passed to the C and C++ compilers. ++ ++.IP CCPCHFLAGS ++Options added to the compiler command line ++to support building with precompiled headers. ++The default value expands expands to the appropriate ++Microsoft Visual C++ command-line options ++when the \fB$PCH\fP construction variable is set. ++ ++.IP CCPDBFLAGS ++Options added to the compiler command line ++to support storing debugging information in a ++Microsoft Visual C++ PDB file. ++The default value expands expands to appropriate ++Microsoft Visual C++ command-line options ++when the \fB$PDB\fP construction variable is set. ++ ++The Visual C++ compiler option that SCons uses by default ++to generate PDB information is \fB/Z7\fP. ++This works correctly with parallel (\fB\-j\fP) builds ++because it embeds the debug information in the intermediate object files, ++as opposed to sharing a single PDB file between multiple object files. ++This is also the only way to get debug information ++embedded into a static library. ++Using the \fB/Zi\fP instead may yield improved ++link-time performance, ++although parallel builds will no longer work. ++ ++You can generate PDB files with the \fB/Zi\fP ++switch by overriding the default \fB$CCPDBFLAGS\fP variable as follows: ++ ++.ES ++env['CCPDBFLAGS'] = ['${(PDB and "/Zi /Fd%s" % File(PDB)) or ""}'] ++.EE ++.IP ++An alternative would be to use the \fB/Zi\fP ++to put the debugging information in a separate \fB.pdb\fP ++file for each object file by overriding ++the \fB$CCPDBFLAGS\fP variable as follows: ++ ++.ES ++env['CCPDBFLAGS'] = '/Zi /Fd${TARGET}.pdb' ++.EE ++ ++.IP CCVERSION ++The version number of the C compiler. ++This may or may not be set, ++depending on the specific C compiler being used. ++ ++.IP CFILESUFFIX ++The suffix for C source files. ++This is used by the internal CFile builder ++when generating C files from Lex (.l) or YACC (.y) input files. ++The default suffix, of course, is ++.B .c ++(lower case). ++On case-insensitive systems (like Windows), ++SCons also treats ++.B .C ++(upper case) files ++as C files. ++ ++.IP CFLAGS ++General options that are passed to the C compiler (C only; not C++). ++ ++.IP CHANGE_SPECFILE ++A hook for modifying the file that controls the packaging build ++(the \fB.spec\fP for RPM, ++the \fBcontrol\fP for Ipkg, ++the \fB.wxs\fP for MSI). ++If set, the function will be called ++after the SCons template for the file has been written. ++XXX ++ ++.IP CHANGED_SOURCES ++A reserved variable name ++that may not be set or used in a construction environment. ++(See "Variable Substitution," below.) ++ ++.IP CHANGED_TARGETS ++A reserved variable name ++that may not be set or used in a construction environment. ++(See "Variable Substitution," below.) ++ ++.IP CHANGELOG ++The name of a file containing the change log text ++to be included in the package. ++This is included as the ++.B %changelog ++section of the RPM ++\fB.spec\fP file. ++ ++.IP _concat ++A function used to produce variables like \fB$_CPPINCFLAGS\fP. It takes ++four or five ++arguments: a prefix to concatenate onto each element, a list of ++elements, a suffix to concatenate onto each element, an environment ++for variable interpolation, and an optional function that will be ++called to transform the list before concatenation. ++ ++.ES ++env['_CPPINCFLAGS'] = '$( ${_concat(INCPREFIX, CPPPATH, INCSUFFIX, __env__, RDirs)} $)', ++.EE ++ ++.IP CONFIGUREDIR ++The name of the directory in which ++Configure context test files are written. ++The default is ++.B .sconf_temp ++in the top-level directory ++containing the ++.B SConstruct ++file. ++ ++.IP CONFIGURELOG ++The name of the Configure context log file. ++The default is ++.B config.log ++in the top-level directory ++containing the ++.B SConstruct ++file. ++ ++.IP _CPPDEFFLAGS ++An automatically-generated construction variable ++containing the C preprocessor command-line options ++to define values. ++The value of \fB$_CPPDEFFLAGS\fP is created ++by appending \fB$CPPDEFPREFIX\fP and \fB$CPPDEFSUFFIX\fP ++to the beginning and end ++of each definition in \fB$CPPDEFINES\fP. ++ ++.IP CPPDEFINES ++A platform independent specification of C preprocessor definitions. ++The definitions will be added to command lines ++through the automatically-generated ++\fB$_CPPDEFFLAGS\fP construction variable (see above), ++which is constructed according to ++the type of value of \fB$CPPDEFINES\fP: ++ ++If \fB$CPPDEFINES\fP is a string, ++the values of the ++.BR $CPPDEFPREFIX and $CPPDEFSUFFIX ++construction variables ++will be added to the beginning and end. ++ ++.ES ++# Will add -Dxyz to POSIX compiler command lines, ++# and /Dxyz to Microsoft Visual C++ command lines. ++env = Environment(CPPDEFINES='xyz') ++.EE ++.IP ++If \fB$CPPDEFINES\fP is a list, ++the values of the ++.BR $CPPDEFPREFIX and $CPPDEFSUFFIX ++construction variables ++will be appended to the beginning and end ++of each element in the list. ++If any element is a list or tuple, ++then the first item is the name being ++defined and the second item is its value: ++ ++.ES ++# Will add -DB=2 -DA to POSIX compiler command lines, ++# and /DB=2 /DA to Microsoft Visual C++ command lines. ++env = Environment(CPPDEFINES=[('B', 2), 'A']) ++.EE ++.IP ++If \fB$CPPDEFINES\fP is a dictionary, ++the values of the ++.BR $CPPDEFPREFIX and $CPPDEFSUFFIX ++construction variables ++will be appended to the beginning and end ++of each item from the dictionary. ++The key of each dictionary item ++is a name being defined ++to the dictionary item's corresponding value; ++if the value is ++.BR None , ++then the name is defined without an explicit value. ++Note that the resulting flags are sorted by keyword ++to ensure that the order of the options on the ++command line is consistent each time ++.B scons ++is run. ++ ++.ES ++# Will add -DA -DB=2 to POSIX compiler command lines, ++# and /DA /DB=2 to Microsoft Visual C++ command lines. ++env = Environment(CPPDEFINES={'B':2, 'A':None}) ++.EE ++ ++.IP CPPDEFPREFIX ++The prefix used to specify preprocessor definitions ++on the C compiler command line. ++This will be appended to the beginning of each definition ++in the \fB$CPPDEFINES\fP construction variable ++when the \fB$_CPPDEFFLAGS\fP variable is automatically generated. ++ ++.IP CPPDEFSUFFIX ++The suffix used to specify preprocessor definitions ++on the C compiler command line. ++This will be appended to the end of each definition ++in the \fB$CPPDEFINES\fP construction variable ++when the \fB$_CPPDEFFLAGS\fP variable is automatically generated. ++ ++.IP CPPFLAGS ++User-specified C preprocessor options. ++These will be included in any command that uses the C preprocessor, ++including not just compilation of C and C++ source files ++via the \fB$CCCOM\fP, ++.BR $SHCCCOM , ++\fB$CXXCOM\fP and ++\fB$SHCXXCOM\fP command lines, ++but also the \fB$FORTRANPPCOM\fP, ++.BR $SHFORTRANPPCOM , ++\fB$F77PPCOM\fP and ++\fB$SHF77PPCOM\fP command lines ++used to compile a Fortran source file, ++and the \fB$ASPPCOM\fP command line ++used to assemble an assembly language source file, ++after first running each file through the C preprocessor. ++Note that this variable does ++.I not ++contain ++.B \-I ++(or similar) include search path options ++that scons generates automatically from \fB$CPPPATH\fP. ++See \fB$_CPPINCFLAGS\fP, below, ++for the variable that expands to those options. ++ ++.IP _CPPINCFLAGS ++An automatically-generated construction variable ++containing the C preprocessor command-line options ++for specifying directories to be searched for include files. ++The value of \fB$_CPPINCFLAGS\fP is created ++by appending \fB$INCPREFIX\fP and \fB$INCSUFFIX\fP ++to the beginning and end ++of each directory in \fB$CPPPATH\fP. ++ ++.IP CPPPATH ++The list of directories that the C preprocessor will search for include ++directories. The C/C++ implicit dependency scanner will search these ++directories for include files. Don't explicitly put include directory ++arguments in CCFLAGS or CXXFLAGS because the result will be non-portable ++and the directories will not be searched by the dependency scanner. Note: ++directory names in CPPPATH will be looked-up relative to the SConscript ++directory when they are used in a command. To force ++.B scons ++to look-up a directory relative to the root of the source tree use #: ++ ++.ES ++env = Environment(CPPPATH='#/include') ++.EE ++.IP ++The directory look-up can also be forced using the ++.BR Dir () ++function: ++ ++.ES ++include = Dir('include') ++env = Environment(CPPPATH=include) ++.EE ++.IP ++The directory list will be added to command lines ++through the automatically-generated ++.B $_CPPINCFLAGS ++construction variable, ++which is constructed by ++appending the values of the ++.BR $INCPREFIX and $INCSUFFIX ++construction variables ++to the beginning and end ++of each directory in \fB$CPPPATH\fP. ++Any command lines you define that need ++the CPPPATH directory list should ++include \fB$_CPPINCFLAGS\fP: ++ ++.ES ++env = Environment(CCCOM="my_compiler $_CPPINCFLAGS -c -o $TARGET $SOURCE") ++.EE ++ ++.IP CPPSUFFIXES ++The list of suffixes of files that will be scanned ++for C preprocessor implicit dependencies ++(#include lines). ++The default list is: ++ ++.ES ++[".c", ".C", ".cxx", ".cpp", ".c++", ".cc", ++ ".h", ".H", ".hxx", ".hpp", ".hh", ++ ".F", ".fpp", ".FPP", ++ ".m", ".mm", ++ ".S", ".spp", ".SPP"] ++.EE ++ ++.IP CVS ++The CVS executable. ++ ++.IP CVSCOFLAGS ++Options that are passed to the CVS checkout subcommand. ++ ++.IP CVSCOM ++The command line used to ++fetch source files from a CVS repository. ++ ++.IP CVSCOMSTR ++The string displayed when fetching ++a source file from a CVS repository. ++If this is not set, then \fB$CVSCOM\fP ++(the command line) is displayed. ++ ++.IP CVSFLAGS ++General options that are passed to CVS. ++By default, this is set to ++.B "-d $CVSREPOSITORY" ++to specify from where the files must be fetched. ++ ++.IP CVSREPOSITORY ++The path to the CVS repository. ++This is referenced in the default ++\fB$CVSFLAGS\fP value. ++ ++.IP CXX ++The C++ compiler. ++ ++.IP CXXCOM ++The command line used to compile a C++ source file to an object file. ++Any options specified in the \fB$CXXFLAGS\fP and ++\fB$CPPFLAGS\fP construction variables ++are included on this command line. ++ ++.IP CXXCOMSTR ++The string displayed when a C++ source file ++is compiled to a (static) object file. ++If this is not set, then \fB$CXXCOM\fP (the command line) is displayed. ++ ++.ES ++env = Environment(CXXCOMSTR = "Compiling static object $TARGET") ++.EE ++ ++.IP CXXFILESUFFIX ++The suffix for C++ source files. ++This is used by the internal CXXFile builder ++when generating C++ files from Lex (.ll) or YACC (.yy) input files. ++The default suffix is ++.BR .cc . ++SCons also treats files with the suffixes ++.BR .cpp , ++.BR .cxx , ++.BR .c++ , ++and ++.B .C++ ++as C++ files, ++and files with ++.B .mm ++suffixes as Objective C++ files. ++On case-sensitive systems (Linux, UNIX, and other POSIX-alikes), ++SCons also treats ++.B .C ++(upper case) files ++as C++ files. ++ ++.IP CXXFLAGS ++General options that are passed to the C++ compiler. ++By default, this includes the value of \fB$CCFLAGS\fP, ++so that setting \fB$CCFLAGS\fP affects both C and C++ compilation. ++If you want to add C++-specific flags, ++you must set or override the value of \fB$CXXFLAGS\fP. ++ ++.IP CXXVERSION ++The version number of the C++ compiler. ++This may or may not be set, ++depending on the specific C++ compiler being used. ++ ++.IP DESCRIPTION ++A long description of the project being packaged. ++This is included in the relevant section ++of the file that controls the packaging build. ++ ++.IP DESCRIPTION_lang ++A language-specific long description for ++the specified \fIlang\fP. ++This is used to populate a ++.B "%description -l" ++section of an RPM ++\fB.spec\fP file. ++ ++.IP Dir ++A function that converts a string ++into a Dir instance relative to the target being built. ++ ++.IP Dirs ++A function that converts a list of strings ++into a list of Dir instances relative to the target being built. ++ ++.IP DSUFFIXES ++The list of suffixes of files that will be scanned ++for imported D package files. ++The default list is: ++ ++.ES ++['.d'] ++.EE ++ ++.IP DVIPDF ++The TeX DVI file to PDF file converter. ++ ++.IP DVIPDFCOM ++The command line used to convert TeX DVI files into a PDF file. ++ ++.IP DVIPDFCOMSTR ++The string displayed when a TeX DVI file ++is converted into a PDF file. ++If this is not set, then \fB$DVIPDFCOM\fP (the command line) is displayed. ++ ++.IP DVIPDFFLAGS ++General options passed to the TeX DVI file to PDF file converter. ++ ++.IP DVIPS ++The TeX DVI file to PostScript converter. ++ ++.IP DVIPSFLAGS ++General options passed to the TeX DVI file to PostScript converter. ++ ++.IP ENV ++A dictionary of environment variables ++to use when invoking commands. When ++\fB$ENV\fP is used in a command all list ++values will be joined using the path separator and any other non-string ++values will simply be coerced to a string. ++Note that, by default, ++.B scons ++does ++.I not ++propagate the environment in force when you ++execute ++.B scons ++to the commands used to build target files. ++This is so that builds will be guaranteed ++repeatable regardless of the environment ++variables set at the time ++.B scons ++is invoked. ++ ++If you want to propagate your ++environment variables ++to the commands executed ++to build target files, ++you must do so explicitly: ++ ++.ES ++import os ++env = Environment(ENV = os.environ) ++.EE ++.IP ++Note that you can choose only to propagate ++certain environment variables. ++A common example is ++the system ++.B PATH ++environment variable, ++so that ++.B scons ++uses the same utilities ++as the invoking shell (or other process): ++ ++.ES ++import os ++env = Environment(ENV = {'PATH' : os.environ['PATH']}) ++.EE ++ ++.IP ESCAPE ++A function that will be called to escape shell special characters in ++command lines. The function should take one argument: the command line ++string to escape; and should return the escaped command line. ++ ++.IP F77 ++The Fortran 77 compiler. ++You should normally set the \fB$FORTRAN\fP variable, ++which specifies the default Fortran compiler ++for all Fortran versions. ++You only need to set \fB$F77\fP if you need to use a specific compiler ++or compiler version for Fortran 77 files. ++ ++.IP F77COM ++The command line used to compile a Fortran 77 source file to an object file. ++You only need to set \fB$F77COM\fP if you need to use a specific ++command line for Fortran 77 files. ++You should normally set the \fB$FORTRANCOM\fP variable, ++which specifies the default command line ++for all Fortran versions. ++ ++.IP F77COMSTR ++The string displayed when a Fortran 77 source file ++is compiled to an object file. ++If this is not set, then \fB$F77COM\fP or \fB$FORTRANCOM\fP ++(the command line) is displayed. ++ ++.IP F77FILESUFFIXES ++The list of file extensions for which the F77 dialect will be used. By ++default, this is ['.f77'] ++ ++.IP F77FLAGS ++General user-specified options that are passed to the Fortran 77 compiler. ++Note that this variable does ++.I not ++contain ++.B \-I ++(or similar) include search path options ++that scons generates automatically from \fB$F77PATH\fP. ++See ++.B $_F77INCFLAGS ++below, ++for the variable that expands to those options. ++You only need to set \fB$F77FLAGS\fP if you need to define specific ++user options for Fortran 77 files. ++You should normally set the \fB$FORTRANFLAGS\fP variable, ++which specifies the user-specified options ++passed to the default Fortran compiler ++for all Fortran versions. ++ ++.IP _F77INCFLAGS ++An automatically-generated construction variable ++containing the Fortran 77 compiler command-line options ++for specifying directories to be searched for include files. ++The value of \fB$_F77INCFLAGS\fP is created ++by appending \fB$INCPREFIX\fP and \fB$INCSUFFIX\fP ++to the beginning and end ++of each directory in \fB$F77PATH\fP. ++ ++.IP F77PATH ++The list of directories that the Fortran 77 compiler will search for include ++directories. The implicit dependency scanner will search these ++directories for include files. Don't explicitly put include directory ++arguments in \fB$F77FLAGS\fP because the result will be non-portable ++and the directories will not be searched by the dependency scanner. Note: ++directory names in \fB$F77PATH\fP will be looked-up relative to the SConscript ++directory when they are used in a command. To force ++.B scons ++to look-up a directory relative to the root of the source tree use #: ++You only need to set \fB$F77PATH\fP if you need to define a specific ++include path for Fortran 77 files. ++You should normally set the \fB$FORTRANPATH\fP variable, ++which specifies the include path ++for the default Fortran compiler ++for all Fortran versions. ++ ++.ES ++env = Environment(F77PATH='#/include') ++.EE ++.IP ++The directory look-up can also be forced using the ++.BR Dir () ++function: ++ ++.ES ++include = Dir('include') ++env = Environment(F77PATH=include) ++.EE ++.IP ++The directory list will be added to command lines ++through the automatically-generated ++.B $_F77INCFLAGS ++construction variable, ++which is constructed by ++appending the values of the ++.BR $INCPREFIX and $INCSUFFIX ++construction variables ++to the beginning and end ++of each directory in \fB$F77PATH\fP. ++Any command lines you define that need ++the F77PATH directory list should ++include \fB$_F77INCFLAGS\fP: ++ ++.ES ++env = Environment(F77COM="my_compiler $_F77INCFLAGS -c -o $TARGET $SOURCE") ++.EE ++ ++.IP F77PPCOM ++The command line used to compile a Fortran 77 source file to an object file ++after first running the file through the C preprocessor. ++Any options specified in the \fB$F77FLAGS\fP and \fB$CPPFLAGS\fP construction variables ++are included on this command line. ++You only need to set \fB$F77PPCOM\fP if you need to use a specific ++C-preprocessor command line for Fortran 77 files. ++You should normally set the \fB$FORTRANPPCOM\fP variable, ++which specifies the default C-preprocessor command line ++for all Fortran versions. ++ ++.IP F77PPCOMSTR ++The string displayed when a Fortran 77 source file ++is compiled to an object file ++after first running the file through the C preprocessor. ++If this is not set, then \fB$F77PPCOM\fP or \fB$FORTRANPPCOM\fP ++(the command line) is displayed. ++ ++.IP F77PPFILESUFFIXES ++The list of file extensions for which the compilation + preprocessor pass for ++F77 dialect will be used. By default, this is empty ++ ++.IP F90 ++The Fortran 90 compiler. ++You should normally set the \fB$FORTRAN\fP variable, ++which specifies the default Fortran compiler ++for all Fortran versions. ++You only need to set \fB$F90\fP if you need to use a specific compiler ++or compiler version for Fortran 90 files. ++ ++.IP F90COM ++The command line used to compile a Fortran 90 source file to an object file. ++You only need to set \fB$F90COM\fP if you need to use a specific ++command line for Fortran 90 files. ++You should normally set the \fB$FORTRANCOM\fP variable, ++which specifies the default command line ++for all Fortran versions. ++ ++.IP F90COMSTR ++The string displayed when a Fortran 90 source file ++is compiled to an object file. ++If this is not set, then \fB$F90COM\fP or \fB$FORTRANCOM\fP ++(the command line) is displayed. ++ ++.IP F90FILESUFFIXES ++The list of file extensions for which the F90 dialect will be used. By ++default, this is ['.f90'] ++ ++.IP F90FLAGS ++General user-specified options that are passed to the Fortran 90 compiler. ++Note that this variable does ++.I not ++contain ++.B \-I ++(or similar) include search path options ++that scons generates automatically from \fB$F90PATH\fP. ++See ++.B $_F90INCFLAGS ++below, ++for the variable that expands to those options. ++You only need to set \fB$F90FLAGS\fP if you need to define specific ++user options for Fortran 90 files. ++You should normally set the \fB$FORTRANFLAGS\fP variable, ++which specifies the user-specified options ++passed to the default Fortran compiler ++for all Fortran versions. ++ ++.IP _F90INCFLAGS ++An automatically-generated construction variable ++containing the Fortran 90 compiler command-line options ++for specifying directories to be searched for include files. ++The value of \fB$_F90INCFLAGS\fP is created ++by appending \fB$INCPREFIX\fP and \fB$INCSUFFIX\fP ++to the beginning and end ++of each directory in \fB$F90PATH\fP. ++ ++.IP F90PATH ++The list of directories that the Fortran 90 compiler will search for include ++directories. The implicit dependency scanner will search these ++directories for include files. Don't explicitly put include directory ++arguments in \fB$F90FLAGS\fP because the result will be non-portable ++and the directories will not be searched by the dependency scanner. Note: ++directory names in \fB$F90PATH\fP will be looked-up relative to the SConscript ++directory when they are used in a command. To force ++.B scons ++to look-up a directory relative to the root of the source tree use #: ++You only need to set \fB$F90PATH\fP if you need to define a specific ++include path for Fortran 90 files. ++You should normally set the \fB$FORTRANPATH\fP variable, ++which specifies the include path ++for the default Fortran compiler ++for all Fortran versions. ++ ++.ES ++env = Environment(F90PATH='#/include') ++.EE ++.IP ++The directory look-up can also be forced using the ++.BR Dir () ++function: ++ ++.ES ++include = Dir('include') ++env = Environment(F90PATH=include) ++.EE ++.IP ++The directory list will be added to command lines ++through the automatically-generated ++.B $_F90INCFLAGS ++construction variable, ++which is constructed by ++appending the values of the ++.BR $INCPREFIX and $INCSUFFIX ++construction variables ++to the beginning and end ++of each directory in \fB$F90PATH\fP. ++Any command lines you define that need ++the F90PATH directory list should ++include \fB$_F90INCFLAGS\fP: ++ ++.ES ++env = Environment(F90COM="my_compiler $_F90INCFLAGS -c -o $TARGET $SOURCE") ++.EE ++ ++.IP F90PPCOM ++The command line used to compile a Fortran 90 source file to an object file ++after first running the file through the C preprocessor. ++Any options specified in the \fB$F90FLAGS\fP and \fB$CPPFLAGS\fP construction variables ++are included on this command line. ++You only need to set \fB$F90PPCOM\fP if you need to use a specific ++C-preprocessor command line for Fortran 90 files. ++You should normally set the \fB$FORTRANPPCOM\fP variable, ++which specifies the default C-preprocessor command line ++for all Fortran versions. ++ ++.IP F90PPCOMSTR ++The string displayed when a Fortran 90 source file ++is compiled after first running the file through the C preprocessor. ++If this is not set, then \fB$F90PPCOM\fP or \fB$FORTRANPPCOM\fP ++(the command line) is displayed. ++ ++.IP F90PPFILESUFFIXES ++The list of file extensions for which the compilation + preprocessor pass for ++F90 dialect will be used. By default, this is empty ++ ++.IP F95 ++The Fortran 95 compiler. ++You should normally set the \fB$FORTRAN\fP variable, ++which specifies the default Fortran compiler ++for all Fortran versions. ++You only need to set \fB$F95\fP if you need to use a specific compiler ++or compiler version for Fortran 95 files. ++ ++.IP F95COM ++The command line used to compile a Fortran 95 source file to an object file. ++You only need to set \fB$F95COM\fP if you need to use a specific ++command line for Fortran 95 files. ++You should normally set the \fB$FORTRANCOM\fP variable, ++which specifies the default command line ++for all Fortran versions. ++ ++.IP F95COMSTR ++The string displayed when a Fortran 95 source file ++is compiled to an object file. ++If this is not set, then \fB$F95COM\fP or \fB$FORTRANCOM\fP ++(the command line) is displayed. ++ ++.IP F95FILESUFFIXES ++The list of file extensions for which the F95 dialect will be used. By ++default, this is ['.f95'] ++ ++.IP F95FLAGS ++General user-specified options that are passed to the Fortran 95 compiler. ++Note that this variable does ++.I not ++contain ++.B \-I ++(or similar) include search path options ++that scons generates automatically from \fB$F95PATH\fP. ++See ++.B $_F95INCFLAGS ++below, ++for the variable that expands to those options. ++You only need to set \fB$F95FLAGS\fP if you need to define specific ++user options for Fortran 95 files. ++You should normally set the \fB$FORTRANFLAGS\fP variable, ++which specifies the user-specified options ++passed to the default Fortran compiler ++for all Fortran versions. ++ ++.IP _F95INCFLAGS ++An automatically-generated construction variable ++containing the Fortran 95 compiler command-line options ++for specifying directories to be searched for include files. ++The value of \fB$_F95INCFLAGS\fP is created ++by appending \fB$INCPREFIX\fP and \fB$INCSUFFIX\fP ++to the beginning and end ++of each directory in \fB$F95PATH\fP. ++ ++.IP F95PATH ++The list of directories that the Fortran 95 compiler will search for include ++directories. The implicit dependency scanner will search these ++directories for include files. Don't explicitly put include directory ++arguments in \fB$F95FLAGS\fP because the result will be non-portable ++and the directories will not be searched by the dependency scanner. Note: ++directory names in \fB$F95PATH\fP will be looked-up relative to the SConscript ++directory when they are used in a command. To force ++.B scons ++to look-up a directory relative to the root of the source tree use #: ++You only need to set \fB$F95PATH\fP if you need to define a specific ++include path for Fortran 95 files. ++You should normally set the \fB$FORTRANPATH\fP variable, ++which specifies the include path ++for the default Fortran compiler ++for all Fortran versions. ++ ++.ES ++env = Environment(F95PATH='#/include') ++.EE ++.IP ++The directory look-up can also be forced using the ++.BR Dir () ++function: ++ ++.ES ++include = Dir('include') ++env = Environment(F95PATH=include) ++.EE ++.IP ++The directory list will be added to command lines ++through the automatically-generated ++.B $_F95INCFLAGS ++construction variable, ++which is constructed by ++appending the values of the ++.BR $INCPREFIX and $INCSUFFIX ++construction variables ++to the beginning and end ++of each directory in \fB$F95PATH\fP. ++Any command lines you define that need ++the F95PATH directory list should ++include \fB$_F95INCFLAGS\fP: ++ ++.ES ++env = Environment(F95COM="my_compiler $_F95INCFLAGS -c -o $TARGET $SOURCE") ++.EE ++ ++.IP F95PPCOM ++The command line used to compile a Fortran 95 source file to an object file ++after first running the file through the C preprocessor. ++Any options specified in the \fB$F95FLAGS\fP and \fB$CPPFLAGS\fP construction variables ++are included on this command line. ++You only need to set \fB$F95PPCOM\fP if you need to use a specific ++C-preprocessor command line for Fortran 95 files. ++You should normally set the \fB$FORTRANPPCOM\fP variable, ++which specifies the default C-preprocessor command line ++for all Fortran versions. ++ ++.IP F95PPCOMSTR ++The string displayed when a Fortran 95 source file ++is compiled to an object file ++after first running the file through the C preprocessor. ++If this is not set, then \fB$F95PPCOM\fP or \fB$FORTRANPPCOM\fP ++(the command line) is displayed. ++ ++.IP F95PPFILESUFFIXES ++The list of file extensions for which the compilation + preprocessor pass for ++F95 dialect will be used. By default, this is empty ++ ++.IP File ++A function that converts a string into a File instance relative to the ++target being built. ++ ++.IP FORTRAN ++The default Fortran compiler ++for all versions of Fortran. ++ ++.IP FORTRANCOM ++The command line used to compile a Fortran source file to an object file. ++By default, any options specified ++in the \fB$FORTRANFLAGS\fP, ++.BR $CPPFLAGS , ++.BR $_CPPDEFFLAGS , ++\fB$_FORTRANMODFLAG\fP, and ++\fB$_FORTRANINCFLAGS\fP construction variables ++are included on this command line. ++ ++.IP FORTRANCOMSTR ++The string displayed when a Fortran source file ++is compiled to an object file. ++If this is not set, then \fB$FORTRANCOM\fP ++(the command line) is displayed. ++ ++.IP FORTRANFILESUFFIXES ++The list of file extensions for which the FORTRAN dialect will be used. By ++default, this is ['.f', '.for', '.ftn'] ++ ++.IP FORTRANFLAGS ++General user-specified options that are passed to the Fortran compiler. ++Note that this variable does ++.I not ++contain ++.B \-I ++(or similar) include or module search path options ++that scons generates automatically from \fB$FORTRANPATH\fP. ++See ++.BR $_FORTRANINCFLAGS\fP and \fB$_FORTRANMODFLAG , ++below, ++for the variables that expand those options. ++ ++.IP _FORTRANINCFLAGS ++An automatically-generated construction variable ++containing the Fortran compiler command-line options ++for specifying directories to be searched for include ++files and module files. ++The value of \fB$_FORTRANINCFLAGS\fP is created ++by prepending/appending \fB$INCPREFIX\fP and \fB$INCSUFFIX\fP ++to the beginning and end ++of each directory in \fB$FORTRANPATH\fP. ++ ++.IP FORTRANMODDIR ++Directory location where the Fortran compiler should place ++any module files it generates. This variable is empty, by default. Some ++Fortran compilers will internally append this directory in the search path ++for module files, as well. ++ ++.IP FORTRANMODDIRPREFIX ++The prefix used to specify a module directory on the Fortran compiler command ++line. ++This will be appended to the beginning of the directory ++in the \fB$FORTRANMODDIR\fP construction variables ++when the \fB$_FORTRANMODFLAG\fP variables is automatically generated. ++ ++.IP FORTRANMODDIRSUFFIX ++The suffix used to specify a module directory on the Fortran compiler command ++line. ++This will be appended to the beginning of the directory ++in the \fB$FORTRANMODDIR\fP construction variables ++when the \fB$_FORTRANMODFLAG\fP variables is automatically generated. ++ ++.IP _FORTRANMODFLAG ++An automatically-generated construction variable ++containing the Fortran compiler command-line option ++for specifying the directory location where the Fortran ++compiler should place any module files that happen to get ++generated during compilation. ++The value of \fB$_FORTRANMODFLAG\fP is created ++by prepending/appending \fB$FORTRANMODDIRPREFIX\fP and ++.B $FORTRANMODDIRSUFFIX ++to the beginning and end of the directory in \fB$FORTRANMODDIR\fP. ++ ++.IP FORTRANMODPREFIX ++The module file prefix used by the Fortran compiler. SCons assumes that ++the Fortran compiler follows the quasi-standard naming convention for ++module files of ++.BR module_name.mod . ++As a result, this variable is left empty, by default. For situations in ++which the compiler does not necessarily follow the normal convention, ++the user may use this variable. Its value will be appended to every ++module file name as scons attempts to resolve dependencies. ++ ++.IP FORTRANMODSUFFIX ++The module file suffix used by the Fortran compiler. SCons assumes that ++the Fortran compiler follows the quasi-standard naming convention for ++module files of ++.BR module_name.mod . ++As a result, this variable is set to ".mod", by default. For situations ++in which the compiler does not necessarily follow the normal convention, ++the user may use this variable. Its value will be appended to every ++module file name as scons attempts to resolve dependencies. ++ ++.IP FORTRANPATH ++The list of directories that the Fortran compiler will search for ++include files and (for some compilers) module files. The Fortran implicit ++dependency scanner will search these directories for include files (but ++not module files since they are autogenerated and, as such, may not ++actually exist at the time the scan takes place). Don't explicitly put ++include directory arguments in FORTRANFLAGS because the result will be ++non-portable and the directories will not be searched by the dependency ++scanner. Note: directory names in FORTRANPATH will be looked-up relative ++to the SConscript directory when they are used in a command. To force ++.B scons ++to look-up a directory relative to the root of the source tree use #: ++ ++.ES ++env = Environment(FORTRANPATH='#/include') ++.EE ++.IP ++The directory look-up can also be forced using the ++.BR Dir () ++function: ++ ++.ES ++include = Dir('include') ++env = Environment(FORTRANPATH=include) ++.EE ++.IP ++The directory list will be added to command lines ++through the automatically-generated ++.B $_FORTRANINCFLAGS ++construction variable, ++which is constructed by ++appending the values of the ++.BR $INCPREFIX and $INCSUFFIX ++construction variables ++to the beginning and end ++of each directory in \fB$FORTRANPATH\fP. ++Any command lines you define that need ++the FORTRANPATH directory list should ++include \fB$_FORTRANINCFLAGS\fP: ++ ++.ES ++env = Environment(FORTRANCOM="my_compiler $_FORTRANINCFLAGS -c -o $TARGET $SOURCE") ++.EE ++ ++.IP FORTRANPPCOM ++The command line used to compile a Fortran source file to an object file ++after first running the file through the C preprocessor. ++By default, any options specified in the \fB$FORTRANFLAGS\fP, ++.BR $CPPFLAGS , ++.BR $_CPPDEFFLAGS , ++\fB$_FORTRANMODFLAG\fP, and ++.B $_FORTRANINCFLAGS ++construction variables are included on this command line. ++ ++.IP FORTRANPPCOMSTR ++The string displayed when a Fortran source file ++is compiled to an object file ++after first running the file through the C preprocessor. ++If this is not set, then \fB$FORTRANPPCOM\fP ++(the command line) is displayed. ++ ++.IP FORTRANPPFILESUFFIXES ++The list of file extensions for which the compilation + preprocessor pass for ++FORTRAN dialect will be used. By default, this is ['.fpp', '.FPP'] ++ ++.IP FORTRANSUFFIXES ++The list of suffixes of files that will be scanned ++for Fortran implicit dependencies ++(INCLUDE lines and USE statements). ++The default list is: ++ ++.ES ++[".f", ".F", ".for", ".FOR", ".ftn", ".FTN", ".fpp", ".FPP", ++".f77", ".F77", ".f90", ".F90", ".f95", ".F95"] ++.EE ++ ++.IP FRAMEWORKPATH ++On Mac OS X with gcc, ++a list containing the paths to search for frameworks. ++Used by the compiler to find framework-style includes like ++#include <Fmwk/Header.h>. ++Used by the linker to find user-specified frameworks when linking (see ++.BR $FRAMEWORKS ). ++For example: ++ ++.ES ++ env.AppendUnique(FRAMEWORKPATH='#myframeworkdir') ++.EE ++.IP ++will add ++ ++.ES ++ ... -Fmyframeworkdir ++.EE ++.IP ++to the compiler and linker command lines. ++ ++.IP _FRAMEWORKPATH ++On Mac OS X with gcc, an automatically-generated construction variable ++containing the linker command-line options corresponding to ++.BR $FRAMEWORKPATH . ++ ++.IP FRAMEWORKPATHPREFIX ++On Mac OS X with gcc, the prefix to be used for the FRAMEWORKPATH entries. ++(see \fB$FRAMEWORKPATH\fP). ++The default value is ++.BR \-F . ++ ++.IP FRAMEWORKPREFIX ++On Mac OS X with gcc, ++the prefix to be used for linking in frameworks ++(see \fB$FRAMEWORKS\fP). ++The default value is ++.BR \-framework . ++ ++.IP _FRAMEWORKS ++On Mac OS X with gcc, ++an automatically-generated construction variable ++containing the linker command-line options ++for linking with FRAMEWORKS. ++ ++.IP FRAMEWORKS ++On Mac OS X with gcc, a list of the framework names to be linked into a ++program or shared library or bundle. ++The default value is the empty list. ++For example: ++ ++.ES ++ env.AppendUnique(FRAMEWORKS=Split('System Cocoa SystemConfiguration')) ++.EE ++.IP ++ ++.IP FRAMEWORKSFLAGS ++On Mac OS X with gcc, ++general user-supplied frameworks options to be added at ++the end of a command ++line building a loadable module. ++(This has been largely superseded by ++the \fB$FRAMEWORKPATH\fP, \fB$FRAMEWORKPATHPREFIX\fP, ++\fB$FRAMEWORKPREFIX\fP and \fB$FRAMEWORKS\fP variables ++described above.) ++ ++.IP GS ++The Ghostscript program used to convert PostScript to PDF files. ++ ++.IP GSCOM ++The Ghostscript command line used to convert PostScript to PDF files. ++ ++.IP GSCOMSTR ++The string displayed when ++Ghostscript is used to convert ++a PostScript file to a PDF file. ++If this is not set, then \fB$GSCOM\fP (the command line) is displayed. ++ ++.IP GSFLAGS ++General options passed to the Ghostscript program ++when converting PostScript to PDF files. ++ ++.IP HOST_ARCH ++Sets the host architecture for Visual Studio compiler. If not set, ++default to the detected host architecture: note that this may depend ++on the python you are using. ++This variable must be passed as an argument to the Environment() ++constructor; setting it later has no effect. ++ ++Valid values are the same as for \fB$TARGET_ARCH\fP. ++ ++This is currently only used on Windows, but in the future it will be ++used on other OSes as well. ++ ++.IP HOST_OS ++ The name of the host operating system used to create the Environment. ++ If a platform is specified when creating the Environment, then ++ that Platform's logic will handle setting this value. ++ This value is immutable, and should not be changed by the user after ++ the Environment is initialized. ++ Currently only set for Win32. ++ ++.IP IDLSUFFIXES ++The list of suffixes of files that will be scanned ++for IDL implicit dependencies ++(#include or import lines). ++The default list is: ++ ++.ES ++[".idl", ".IDL"] ++.EE ++ ++.IP IMPLICIT_COMMAND_DEPENDENCIES ++Controls whether or not SCons will ++add implicit dependencies for the commands ++executed to build targets. ++ ++By default, SCons will add ++to each target ++an implicit dependency on the command ++represented by the first argument on any ++command line it executes. ++The specific file for the dependency is ++found by searching the ++.I PATH ++variable in the ++.I ENV ++environment used to execute the command. ++ ++If the construction variable ++.B $IMPLICIT_COMMAND_DEPENDENCIES ++is set to a false value ++.RB ( None , ++.BR False , ++.BR 0 , ++etc.), ++then the implicit dependency will ++not be added to the targets ++built with that construction environment. ++ ++.ES ++env = Environment(IMPLICIT_COMMAND_DEPENDENCIES = 0) ++.EE ++ ++.IP INCPREFIX ++The prefix used to specify an include directory on the C compiler command ++line. ++This will be appended to the beginning of each directory ++in the \fB$CPPPATH\fP and \fB$FORTRANPATH\fP construction variables ++when the \fB$_CPPINCFLAGS\fP and \fB$_FORTRANINCFLAGS\fP ++variables are automatically generated. ++ ++.IP INCSUFFIX ++The suffix used to specify an include directory on the C compiler command ++line. ++This will be appended to the end of each directory ++in the \fB$CPPPATH\fP and \fB$FORTRANPATH\fP construction variables ++when the \fB$_CPPINCFLAGS\fP and \fB$_FORTRANINCFLAGS\fP ++variables are automatically generated. ++ ++.IP INSTALL ++A function to be called to install a file into a ++destination file name. ++The default function copies the file into the destination ++(and sets the destination file's mode and permission bits ++to match the source file's). ++The function takes the following arguments: ++ ++.ES ++def install(dest, source, env): ++.EE ++.IP ++.I dest ++is the path name of the destination file. ++.I source ++is the path name of the source file. ++.I env ++is the construction environment ++(a dictionary of construction values) ++in force for this file installation. ++ ++.IP INSTALLSTR ++The string displayed when a file is ++installed into a destination file name. ++The default is: ++.ES ++Install file: "$SOURCE" as "$TARGET" ++.EE ++ ++.IP INTEL_C_COMPILER_VERSION ++Set by the "intelc" Tool ++to the major version number of the Intel C compiler ++selected for use. ++ ++.IP JAR ++The Java archive tool. ++ ++.IP JARCHDIR ++The directory to which the Java archive tool should change ++(using the ++.B \-C ++option). ++ ++.IP JARCOM ++The command line used to call the Java archive tool. ++ ++.IP JARCOMSTR ++The string displayed when the Java archive tool ++is called ++If this is not set, then \fB$JARCOM\fP (the command line) is displayed. ++ ++.ES ++env = Environment(JARCOMSTR = "JARchiving $SOURCES into $TARGET") ++.EE ++ ++.IP JARFLAGS ++General options passed to the Java archive tool. ++By default this is set to ++.B cf ++to create the necessary ++.B jar ++file. ++ ++.IP JARSUFFIX ++The suffix for Java archives: ++.B .jar ++by default. ++ ++.IP JAVABOOTCLASSPATH ++Specifies the list of directories that ++will be added to the ++&javac; command line ++via the \fB\-bootclasspath\fP option. ++The individual directory names will be ++separated by the operating system's path separate character ++(\fB:\fP on UNIX/Linux/POSIX, ++\fB;\fP on Windows). ++ ++.IP JAVAC ++The Java compiler. ++ ++.IP JAVACCOM ++The command line used to compile a directory tree containing ++Java source files to ++corresponding Java class files. ++Any options specified in the \fB$JAVACFLAGS\fP construction variable ++are included on this command line. ++ ++.IP JAVACCOMSTR ++The string displayed when compiling ++a directory tree of Java source files to ++corresponding Java class files. ++If this is not set, then \fB$JAVACCOM\fP (the command line) is displayed. ++ ++.ES ++env = Environment(JAVACCOMSTR = "Compiling class files $TARGETS from $SOURCES") ++.EE ++ ++.IP JAVACFLAGS ++General options that are passed to the Java compiler. ++ ++.IP JAVACLASSDIR ++The directory in which Java class files may be found. ++This is stripped from the beginning of any Java .class ++file names supplied to the ++.B JavaH ++builder. ++ ++.IP JAVACLASSPATH ++Specifies the list of directories that ++will be searched for Java ++\fB.class\fP file. ++The directories in this list will be added to the ++&javac; and &javah; command lines ++via the \fB\-classpath\fP option. ++The individual directory names will be ++separated by the operating system's path separate character ++(\fB:\fP on UNIX/Linux/POSIX, ++\fB;\fP on Windows). ++ ++Note that this currently just adds the specified ++directory via the \fB\-classpath\fP option. ++&SCons; does not currently search the ++\fB$JAVACLASSPATH\fP directories for dependency ++\fB.class\fP files. ++ ++.IP JAVACLASSSUFFIX ++The suffix for Java class files; ++.B .class ++by default. ++ ++.IP JAVAH ++The Java generator for C header and stub files. ++ ++.IP JAVAHCOM ++The command line used to generate C header and stub files ++from Java classes. ++Any options specified in the \fB$JAVAHFLAGS\fP construction variable ++are included on this command line. ++ ++.IP JAVAHCOMSTR ++The string displayed when C header and stub files ++are generated from Java classes. ++If this is not set, then \fB$JAVAHCOM\fP (the command line) is displayed. ++ ++.ES ++env = Environment(JAVAHCOMSTR = "Generating header/stub file(s) $TARGETS from $SOURCES") ++.EE ++ ++.IP JAVAHFLAGS ++General options passed to the C header and stub file generator ++for Java classes. ++ ++.IP JAVASOURCEPATH ++Specifies the list of directories that ++will be searched for input ++\fB.java\fP file. ++The directories in this list will be added to the ++&javac; command line ++via the \fB\-sourcepath\fP option. ++The individual directory names will be ++separated by the operating system's path separate character ++(\fB:\fP on UNIX/Linux/POSIX, ++\fB;\fP on Windows). ++ ++Note that this currently just adds the specified ++directory via the \fB\-sourcepath\fP option. ++&SCons; does not currently search the ++\fB$JAVASOURCEPATH\fP directories for dependency ++\fB.java\fP files. ++ ++.IP JAVASUFFIX ++The suffix for Java files; ++.B .java ++by default. ++ ++.IP JAVAVERSION ++Specifies the Java version being used by the \fBJava\fP() builder. ++This is \fInot\fP currently used to select one ++version of the Java compiler vs. another. ++Instead, you should set this to specify the version of Java ++supported by your &javac; compiler. ++The default is \fB1.4\fP. ++ ++This is sometimes necessary because ++Java 1.5 changed the file names that are created ++for nested anonymous inner classes, ++which can cause a mismatch with the files ++that &SCons; expects will be generated by the &javac; compiler. ++Setting \fB$JAVAVERSION\fP to \fB1.5\fP ++(or \fB1.6\fP, as appropriate) ++can make &SCons; realize that a Java 1.5 or 1.6 ++build is actually up to date. ++ ++.IP LATEX ++The LaTeX structured formatter and typesetter. ++ ++.IP LATEXCOM ++The command line used to call the LaTeX structured formatter and typesetter. ++ ++.IP LATEXCOMSTR ++The string displayed when calling ++the LaTeX structured formatter and typesetter. ++If this is not set, then \fB$LATEXCOM\fP (the command line) is displayed. ++ ++.ES ++env = Environment(LATEXCOMSTR = "Building $TARGET from LaTeX input $SOURCES") ++.EE ++ ++.IP LATEXFLAGS ++General options passed to the LaTeX structured formatter and typesetter. ++ ++.IP LATEXRETRIES ++The maximum number of times that LaTeX ++will be re-run if the ++.B .log ++generated by the \fB$LATEXCOM\fP command ++indicates that there are undefined references. ++The default is to try to resolve undefined references ++by re-running LaTeX up to three times. ++ ++.IP LATEXSUFFIXES ++The list of suffixes of files that will be scanned ++for LaTeX implicit dependencies ++(\fB\\include\fP or \fB\\import\fP files). ++The default list is: ++ ++.ES ++[".tex", ".ltx", ".latex"] ++.EE ++ ++.IP LDMODULE ++The linker for building loadable modules. ++By default, this is the same as \fB$SHLINK\fP. ++ ++.IP LDMODULECOM ++The command line for building loadable modules. ++On Mac OS X, this uses the \fB$LDMODULE\fP, ++\fB$LDMODULEFLAGS\fP and ++\fB$FRAMEWORKSFLAGS\fP variables. ++On other systems, this is the same as \fB$SHLINK\fP. ++ ++.IP LDMODULECOMSTR ++The string displayed when building loadable modules. ++If this is not set, then \fB$LDMODULECOM\fP (the command line) is displayed. ++ ++.IP LDMODULEFLAGS ++General user options passed to the linker for building loadable modules. ++ ++.IP LDMODULEPREFIX ++The prefix used for loadable module file names. ++On Mac OS X, this is null; ++on other systems, this is ++the same as \fB$SHLIBPREFIX\fP. ++ ++.IP LDMODULESUFFIX ++The suffix used for loadable module file names. ++On Mac OS X, this is null; ++on other systems, this is ++the same as $SHLIBSUFFIX. ++ ++.IP LEX ++The lexical analyzer generator. ++ ++.IP LEXCOM ++The command line used to call the lexical analyzer generator ++to generate a source file. ++ ++.IP LEXCOMSTR ++The string displayed when generating a source file ++using the lexical analyzer generator. ++If this is not set, then \fB$LEXCOM\fP (the command line) is displayed. ++ ++.ES ++env = Environment(LEXCOMSTR = "Lex'ing $TARGET from $SOURCES") ++.EE ++ ++.IP LEXFLAGS ++General options passed to the lexical analyzer generator. ++ ++.IP _LIBDIRFLAGS ++An automatically-generated construction variable ++containing the linker command-line options ++for specifying directories to be searched for library. ++The value of \fB$_LIBDIRFLAGS\fP is created ++by appending \fB$LIBDIRPREFIX\fP and \fB$LIBDIRSUFFIX\fP ++to the beginning and end ++of each directory in \fB$LIBPATH\fP. ++ ++.IP LIBDIRPREFIX ++The prefix used to specify a library directory on the linker command line. ++This will be appended to the beginning of each directory ++in the \fB$LIBPATH\fP construction variable ++when the \fB$_LIBDIRFLAGS\fP variable is automatically generated. ++ ++.IP LIBDIRSUFFIX ++The suffix used to specify a library directory on the linker command line. ++This will be appended to the end of each directory ++in the \fB$LIBPATH\fP construction variable ++when the \fB$_LIBDIRFLAGS\fP variable is automatically generated. ++ ++.IP LIBEMITTER ++TODO ++ ++.IP _LIBFLAGS ++An automatically-generated construction variable ++containing the linker command-line options ++for specifying libraries to be linked with the resulting target. ++The value of \fB$_LIBFLAGS\fP is created ++by appending \fB$LIBLINKPREFIX\fP and \fB$LIBLINKSUFFIX\fP ++to the beginning and end ++of each filename in \fB$LIBS\fP. ++ ++.IP LIBLINKPREFIX ++The prefix used to specify a library to link on the linker command line. ++This will be appended to the beginning of each library ++in the \fB$LIBS\fP construction variable ++when the \fB$_LIBFLAGS\fP variable is automatically generated. ++ ++.IP LIBLINKSUFFIX ++The suffix used to specify a library to link on the linker command line. ++This will be appended to the end of each library ++in the \fB$LIBS\fP construction variable ++when the \fB$_LIBFLAGS\fP variable is automatically generated. ++ ++.IP LIBPATH ++The list of directories that will be searched for libraries. ++The implicit dependency scanner will search these ++directories for include files. Don't explicitly put include directory ++arguments in \fB$LINKFLAGS\fP or \fB$SHLINKFLAGS\fP ++because the result will be non-portable ++and the directories will not be searched by the dependency scanner. Note: ++directory names in LIBPATH will be looked-up relative to the SConscript ++directory when they are used in a command. To force ++.B scons ++to look-up a directory relative to the root of the source tree use #: ++ ++.ES ++env = Environment(LIBPATH='#/libs') ++.EE ++.IP ++The directory look-up can also be forced using the ++.BR Dir () ++function: ++ ++.ES ++libs = Dir('libs') ++env = Environment(LIBPATH=libs) ++.EE ++.IP ++The directory list will be added to command lines ++through the automatically-generated ++.B $_LIBDIRFLAGS ++construction variable, ++which is constructed by ++appending the values of the ++.BR $LIBDIRPREFIX and $LIBDIRSUFFIX ++construction variables ++to the beginning and end ++of each directory in \fB$LIBPATH\fP. ++Any command lines you define that need ++the LIBPATH directory list should ++include \fB$_LIBDIRFLAGS\fP: ++ ++.ES ++env = Environment(LINKCOM="my_linker $_LIBDIRFLAGS $_LIBFLAGS -o $TARGET $SOURCE") ++.EE ++ ++.IP LIBPREFIX ++The prefix used for (static) library file names. ++A default value is set for each platform ++(posix, win32, os2, etc.), ++but the value is overridden by individual tools ++(ar, mslib, sgiar, sunar, tlib, etc.) ++to reflect the names of the libraries they create. ++ ++.IP LIBPREFIXES ++A list of all legal prefixes for library file names. ++When searching for library dependencies, ++SCons will look for files with these prefixes, ++the base library name, ++and suffixes in the \fB$LIBSUFFIXES\fP list. ++ ++.IP LIBS ++A list of one or more libraries ++that will be linked with ++any executable programs ++created by this environment. ++ ++The library list will be added to command lines ++through the automatically-generated ++.B $_LIBFLAGS ++construction variable, ++which is constructed by ++appending the values of the ++.BR $LIBLINKPREFIX and $LIBLINKSUFFIX ++construction variables ++to the beginning and end ++of each filename in \fB$LIBS\fP. ++Any command lines you define that need ++the LIBS library list should ++include \fB$_LIBFLAGS\fP: ++ ++.ES ++env = Environment(LINKCOM="my_linker $_LIBDIRFLAGS $_LIBFLAGS -o $TARGET $SOURCE") ++.EE ++.IP ++If you add a ++File ++object to the ++.B $LIBS ++list, the name of that file will be added to ++.BR $_LIBFLAGS , ++and thus the link line, as is, without ++.B $LIBLINKPREFIX ++or ++.BR $LIBLINKSUFFIX . ++For example: ++ ++.ES ++env.Append(LIBS=File('/tmp/mylib.so')) ++.EE ++.IP ++In all cases, scons will add dependencies from the executable program to ++all the libraries in this list. ++ ++.IP LIBSUFFIX ++The suffix used for (static) library file names. ++A default value is set for each platform ++(posix, win32, os2, etc.), ++but the value is overridden by individual tools ++(ar, mslib, sgiar, sunar, tlib, etc.) ++to reflect the names of the libraries they create. ++ ++.IP LIBSUFFIXES ++A list of all legal suffixes for library file names. ++When searching for library dependencies, ++SCons will look for files with prefixes, in the \fB$LIBPREFIXES\fP list, ++the base library name, ++and these suffixes. ++ ++.IP LICENSE ++The abbreviated name of the license under which ++this project is released (gpl, lpgl, bsd etc.). ++See http://www.opensource.org/licenses/alphabetical ++for a list of license names. ++ ++.IP LINESEPARATOR ++The separator used by the \fBSubstfile\fP() and \fBTextfile\fP() builders. ++This value is used between sources when constructing the target. ++It defaults to the current system line separator. ++ ++.IP LINGUAS_FILE ++The \fB$LINGUAS_FILE\fP defines file(s) containing list of additional linguas ++to be processed by \fBPOInit\fP(), \fBPOUpdate\fP() or \fBMOFiles\fP() ++builders. It also affects \fBTranslate\fP() builder. If the variable contains ++a string, it defines name of the list file. The \fB$LINGUAS_FILE\fP may be a ++list of file names as well. If \fB$LINGUAS_FILE\fP is set to ++\fBTrue\fP (or non-zero numeric value), the list will be read from ++default file named ++.BR LINGUAS . ++ ++ ++.IP LINK ++The linker. ++ ++.IP LINKCOM ++The command line used to link object files into an executable. ++ ++.IP LINKCOMSTR ++The string displayed when object files ++are linked into an executable. ++If this is not set, then \fB$LINKCOM\fP (the command line) is displayed. ++ ++.ES ++env = Environment(LINKCOMSTR = "Linking $TARGET") ++.EE ++ ++.IP LINKFLAGS ++General user options passed to the linker. ++Note that this variable should ++.I not ++contain ++.B \-l ++(or similar) options for linking with the libraries listed in \fB$LIBS\fP, ++nor ++.B \-L ++(or similar) library search path options ++that scons generates automatically from \fB$LIBPATH\fP. ++See ++.B $_LIBFLAGS ++above, ++for the variable that expands to library-link options, ++and ++.B $_LIBDIRFLAGS ++above, ++for the variable that expands to library search path options. ++ ++.IP M4 ++The M4 macro preprocessor. ++ ++.IP M4COM ++The command line used to pass files through the M4 macro preprocessor. ++ ++.IP M4COMSTR ++The string displayed when ++a file is passed through the M4 macro preprocessor. ++If this is not set, then \fB$M4COM\fP (the command line) is displayed. ++ ++.IP M4FLAGS ++General options passed to the M4 macro preprocessor. ++ ++.IP MAKEINDEX ++The makeindex generator for the TeX formatter and typesetter and the ++LaTeX structured formatter and typesetter. ++ ++.IP MAKEINDEXCOM ++The command line used to call the makeindex generator for the ++TeX formatter and typesetter and the LaTeX structured formatter and ++typesetter. ++ ++.IP MAKEINDEXCOMSTR ++The string displayed when calling the makeindex generator for the ++TeX formatter and typesetter ++and the LaTeX structured formatter and typesetter. ++If this is not set, then \fB$MAKEINDEXCOM\fP (the command line) is displayed. ++ ++.IP MAKEINDEXFLAGS ++General options passed to the makeindex generator for the TeX formatter ++and typesetter and the LaTeX structured formatter and typesetter. ++ ++.IP MAXLINELENGTH ++The maximum number of characters allowed on an external command line. ++On Win32 systems, ++link lines longer than this many characters ++are linked via a temporary file name. ++ ++.IP MIDL ++The Microsoft IDL compiler. ++ ++.IP MIDLCOM ++The command line used to pass files to the Microsoft IDL compiler. ++ ++.IP MIDLCOMSTR ++The string displayed when ++the Microsoft IDL copmiler is called. ++If this is not set, then \fB$MIDLCOM\fP (the command line) is displayed. ++ ++.IP MIDLFLAGS ++General options passed to the Microsoft IDL compiler. ++ ++.IP MOSUFFIX ++Suffix used for \fBMO\fP files (default: \fB'.mo'\fP). ++See &t-link-msgfmt; tool and \fBMOFiles\fP() builder. ++ ++.IP MSGFMT ++Absolute path to \fBmsgfmt(1)\fP binary, found by ++.BR Detect() . ++See &t-link-msgfmt; tool and \fBMOFiles\fP() builder. ++ ++.IP MSGFMTCOM ++Complete command line to run \fBmsgfmt(1)\fP program. ++See &t-link-msgfmt; tool and \fBMOFiles\fP() builder. ++ ++.IP MSGFMTCOMSTR ++String to display when \fBmsgfmt(1)\fP is invoked ++(default: \fB''\fP, which means ``print \fB$MSGFMTCOM\fP''). ++See &t-link-msgfmt; tool and \fBMOFiles\fP() builder. ++ ++.IP MSGFMTFLAGS ++Additional flags to \fBmsgfmt(1)\fP. ++See &t-link-msgfmt; tool and \fBMOFiles\fP() builder. ++ ++.IP MSGINIT ++Path to \fBmsginit(1)\fP program (found via ++.BR Detect() ). ++See &t-link-msginit; tool and \fBPOInit\fP() builder. ++ ++.IP MSGINITCOM ++Complete command line to run \fBmsginit(1)\fP program. ++See &t-link-msginit; tool and \fBPOInit\fP() builder. ++ ++.IP MSGINITCOMSTR ++String to display when \fBmsginit(1)\fP is invoked ++(default: \fB''\fP, which means ``print \fB$MSGINITCOM\fP''). ++See &t-link-msginit; tool and \fBPOInit\fP() builder. ++ ++.IP MSGINITFLAGS ++List of additional flags to \fBmsginit(1)\fP (default: ++.BR [] ). ++See &t-link-msginit; tool and \fBPOInit\fP() builder. ++ ++.IP _MSGINITLOCALE ++Internal ``macro''. Computes locale (language) name based on target filename ++(default: \fB'${TARGET.filebase}' \fP). ++ ++.IP MSGMERGE ++Absolute path to \fBmsgmerge(1)\fP binary as found by ++.BR Detect() . ++See &t-link-msgmerge; tool and \fBPOUpdate\fP() builder. ++ ++.IP MSGMERGECOM ++Complete command line to run \fBmsgmerge(1)\fP command. ++See &t-link-msgmerge; tool and \fBPOUpdate\fP() builder. ++ ++.IP MSGMERGECOMSTR ++String to be displayed when \fBmsgmerge(1)\fP is invoked ++(default: \fB''\fP, which means ``print \fB$MSGMERGECOM\fP''). ++See &t-link-msgmerge; tool and \fBPOUpdate\fP() builder. ++ ++.IP MSGMERGEFLAGS ++Additional flags to \fBmsgmerge(1)\fP command. ++See &t-link-msgmerge; tool and \fBPOUpdate\fP() builder. ++ ++.IP MSSDK_DIR ++The directory containing the Microsoft SDK ++(either Platform SDK or Windows SDK) ++to be used for compilation. ++ ++.IP MSSDK_VERSION ++The version string of the Microsoft SDK ++(either Platform SDK or Windows SDK) ++to be used for compilation. ++Supported versions include ++.BR 6.1 , ++.BR 6.0A , ++.BR 6.0 , ++.B 2003R2 ++and ++.BR 2003R1 . ++ ++.IP MSVC_BATCH ++When set to any true value, ++specifies that SCons should batch ++compilation of object files ++when calling the Microsoft Visual C/C++ compiler. ++All compilations of source files from the same source directory ++that generate target files in a same output directory ++and were configured in SCons using the same construction environment ++will be built in a single call to the compiler. ++Only source files that have changed since their ++object files were built will be passed to each compiler invocation ++(via the \fB$CHANGED_SOURCES\fP construction variable). ++Any compilations where the object (target) file base name ++(minus the \fB.obj\fP) ++does not match the source file base name ++will be compiled separately. ++ ++.IP MSVC_USE_SCRIPT ++Use a batch script to set up Microsoft Visual Studio compiler ++ ++.BR $MSVC_USE_SCRIPT\fP overrides \fB$MSVC_VERSION\fP and \fB$TARGET_ARCH . ++If set to the name of a Visual Studio .bat file (e.g. vcvars.bat), ++SCons will run that bat file and extract the relevant variables from ++the result (typically %INCLUDE%, %LIB%, and %PATH%). Setting ++MSVC_USE_SCRIPT to None bypasses the Visual Studio autodetection ++entirely; use this if you are running SCons in a Visual Studio cmd ++window and importing the shell's environment variables. ++ ++.IP MSVC_VERSION ++Sets the preferred version of Microsoft Visual C/C++ to use. ++ ++If \fB$MSVC_VERSION\fP is not set, SCons will (by default) select the ++latest version of Visual C/C++ installed on your system. If the ++specified version isn't installed, tool initialization will fail. ++This variable must be passed as an argument to the Environment() ++constructor; setting it later has no effect. Set it to an unexpected ++value (e.g. "XXX") to see the valid values on your system. ++ ++.IP MSVS ++When the Microsoft Visual Studio tools are initialized, they set up ++this dictionary with the following keys: ++ ++.BR VERSION : ++the version of MSVS being used (can be set via ++.BR $MSVS_VERSION ) ++ ++.BR VERSIONS : ++the available versions of MSVS installed ++ ++.BR VCINSTALLDIR : ++installed directory of Visual C++ ++ ++.BR VSINSTALLDIR : ++installed directory of Visual Studio ++ ++.BR FRAMEWORKDIR : ++installed directory of the .NET framework ++ ++.BR FRAMEWORKVERSIONS : ++list of installed versions of the .NET framework, sorted latest to oldest. ++ ++.BR FRAMEWORKVERSION : ++latest installed version of the .NET framework ++ ++.BR FRAMEWORKSDKDIR : ++installed location of the .NET SDK. ++ ++.BR PLATFORMSDKDIR : ++installed location of the Platform SDK. ++ ++.BR PLATFORMSDK_MODULES : ++dictionary of installed Platform SDK modules, ++where the dictionary keys are keywords for the various modules, and ++the values are 2-tuples where the first is the release date, and the ++second is the version number. ++ ++If a value isn't set, it wasn't available in the registry. ++ ++.IP MSVS_ARCH ++Sets the architecture for which the generated project(s) should build. ++ ++The default value is \fBx86\fP. ++\fBamd64\fP is also supported ++by &SCons; for some Visual Studio versions. ++Trying to set \fB$MSVS_ARCH\fP to an architecture that's not ++supported for a given Visual Studio version ++will generate an error. ++ ++.IP MSVS_PROJECT_GUID ++The string ++placed in a generated Microsoft Visual Studio project file ++as the value of the ++.B ProjectGUID ++attribute. ++There is no default value. If not defined, a new GUID is generated. ++ ++.IP MSVS_SCC_AUX_PATH ++The path name ++placed in a generated Microsoft Visual Studio project file ++as the value of the ++.B SccAuxPath ++attribute ++if the ++.B MSVS_SCC_PROVIDER ++construction variable is also set. ++There is no default value. ++ ++.IP MSVS_SCC_CONNECTION_ROOT ++The root path of projects in your SCC workspace, i.e the path under which ++all project and solution files will be generated. It is used as a ++reference path from which the relative paths of the generated ++Microsoft Visual Studio project and solution files are computed. ++The relative project file path is placed as the value of the ++.B SccLocalPath ++attribute ++of the project file ++and as the values of the ++.B SccProjectFilePathRelativizedFromConnection[i] ++(where [i] ranges from 0 to the number of projects in the solution) ++attributes of the ++.B GlobalSection(SourceCodeControl) ++section of the Microsoft Visual Studio solution file. ++Similarly the relative solution file path is placed as the values of the ++.B SccLocalPath[i] ++(where [i] ranges from 0 to the number of projects in the solution) ++attributes of the ++.B GlobalSection(SourceCodeControl) ++section of the Microsoft Visual Studio solution file. ++This is used only ++if the ++.B MSVS_SCC_PROVIDER ++construction variable is also set. ++The default value is the current working directory. ++ ++.IP MSVS_SCC_PROJECT_NAME ++The project name ++placed in a generated Microsoft Visual Studio project file ++as the value of the ++.B SccProjectName ++attribute ++if the ++.B MSVS_SCC_PROVIDER ++construction variable is also set. ++In this case the string is also placed in the ++.B SccProjectName0 ++attribute of the ++.B GlobalSection(SourceCodeControl) ++section of the Microsoft Visual Studio solution file. ++There is no default value. ++ ++.IP MSVS_SCC_PROVIDER ++The string ++placed in a generated Microsoft Visual Studio project file ++as the value of the ++.B SccProvider ++attribute. ++The string is also placed in the ++.B SccProvider0 ++attribute of the ++.B GlobalSection(SourceCodeControl) ++section of the Microsoft Visual Studio solution file. ++There is no default value. ++ ++.IP MSVS_VERSION ++Sets the preferred version of Microsoft Visual Studio to use. ++ ++If \fB$MSVS_VERSION\fP is not set, ++&SCons; will (by default) select the latest version ++of Visual Studio installed on your system. ++So, if you have version 6 and version 7 (MSVS .NET) installed, ++it will prefer version 7. ++You can override this by ++specifying the ++.B MSVS_VERSION ++variable in the Environment initialization, setting it to the ++appropriate version ('6.0' or '7.0', for example). ++If the specified version isn't installed, ++tool initialization will fail. ++ ++This is obsolete: use \fB$MSVC_VERSION\fP instead. If \fB$MSVS_VERSION\fP is set and ++.BR $MSVC_VERSION\fP is not, \fB$MSVC_VERSION\fP will be set automatically to \fB$MSVS_VERSION . ++If both are set to different values, scons will raise an error. ++ ++.IP MSVSBUILDCOM ++The build command line placed in ++a generated Microsoft Visual Studio project file. ++The default is to have Visual Studio invoke SCons with any specified ++build targets. ++ ++.IP MSVSCLEANCOM ++The clean command line placed in ++a generated Microsoft Visual Studio project file. ++The default is to have Visual Studio invoke SCons with the -c option ++to remove any specified targets. ++ ++.IP MSVSENCODING ++The encoding string placed in ++a generated Microsoft Visual Studio project file. ++The default is encoding ++.BR Windows-1252 . ++ ++.IP MSVSPROJECTCOM ++The action used to generate Microsoft Visual Studio project files. ++ ++.IP MSVSPROJECTSUFFIX ++The suffix used for Microsoft Visual Studio project (DSP) files. ++The default value is ++.B .vcproj ++when using Visual Studio version 7.x (.NET) ++or later version, ++and ++.B .dsp ++when using earlier versions of Visual Studio. ++ ++.IP MSVSREBUILDCOM ++The rebuild command line placed in ++a generated Microsoft Visual Studio project file. ++The default is to have Visual Studio invoke SCons with any specified ++rebuild targets. ++ ++.IP MSVSSCONS ++The SCons used in generated Microsoft Visual Studio project files. ++The default is the version of SCons being ++used to generate the project file. ++ ++.IP MSVSSCONSCOM ++The default SCons command used in generated Microsoft Visual Studio ++project files. ++ ++.IP MSVSSCONSCRIPT ++The sconscript file ++(that is, ++.B SConstruct ++or ++.B SConscript ++file) ++that will be invoked by Visual Studio ++project files ++(through the ++.B $MSVSSCONSCOM ++variable). ++The default is the same sconscript file ++that contains the call to ++.BR MSVSProject () ++to build the project file. ++ ++.IP MSVSSCONSFLAGS ++The SCons flags used in generated Microsoft Visual Studio ++project files. ++ ++.IP MSVSSOLUTIONCOM ++The action used to generate Microsoft Visual Studio solution files. ++ ++.IP MSVSSOLUTIONSUFFIX ++The suffix used for Microsoft Visual Studio solution (DSW) files. ++The default value is ++.B .sln ++when using Visual Studio version 7.x (.NET), ++and ++.B .dsw ++when using earlier versions of Visual Studio. ++ ++.IP MT ++The program used on Windows systems to embed manifests into DLLs and EXEs. ++See also \fB$WINDOWS_EMBED_MANIFEST\fP. ++ ++.IP MTEXECOM ++The Windows command line used to embed manifests into executables. ++See also \fB$MTSHLIBCOM\fP. ++ ++.IP MTFLAGS ++Flags passed to the \fB$MT\fP manifest embedding program (Windows only). ++ ++.IP MTSHLIBCOM ++The Windows command line used to embed manifests into shared libraries (DLLs). ++See also \fB$MTEXECOM\fP. ++ ++.IP MWCW_VERSION ++The version number of the MetroWerks CodeWarrior C compiler ++to be used. ++ ++.IP MWCW_VERSIONS ++A list of installed versions of the MetroWerks CodeWarrior C compiler ++on this system. ++ ++.IP NAME ++Specfies the name of the project to package. ++ ++.IP no_import_lib ++When set to non-zero, ++suppresses creation of a corresponding Windows static import lib by the ++.B SharedLibrary ++builder when used with ++MinGW, Microsoft Visual Studio or Metrowerks. ++This also suppresses creation ++of an export (.exp) file ++when using Microsoft Visual Studio. ++ ++.IP OBJPREFIX ++The prefix used for (static) object file names. ++ ++.IP OBJSUFFIX ++The suffix used for (static) object file names. ++ ++.IP P4 ++The Perforce executable. ++ ++.IP P4COM ++The command line used to ++fetch source files from Perforce. ++ ++.IP P4COMSTR ++The string displayed when ++fetching a source file from Perforce. ++If this is not set, then \fB$P4COM\fP (the command line) is displayed. ++ ++.IP P4FLAGS ++General options that are passed to Perforce. ++ ++.IP PACKAGEROOT ++Specifies the directory where all files in resulting archive will be ++placed if applicable. The default value is "$NAME-$VERSION". ++ ++.IP PACKAGETYPE ++Selects the package type to build. Currently these are available: ++ ++ * msi - Microsoft Installer ++ * rpm - Redhat Package Manger ++ * ipkg - Itsy Package Management System ++ * tarbz2 - compressed tar ++ * targz - compressed tar ++ * zip - zip file ++ * src_tarbz2 - compressed tar source ++ * src_targz - compressed tar source ++ * src_zip - zip file source ++ ++This may be overridden with the "package_type" command line option. ++ ++.IP PACKAGEVERSION ++The version of the package (not the underlying project). ++This is currently only used by the rpm packager ++and should reflect changes in the packaging, ++not the underlying project code itself. ++ ++.IP PCH ++The Microsoft Visual C++ precompiled header that will be used when compiling ++object files. This variable is ignored by tools other than Microsoft Visual C++. ++When this variable is ++defined SCons will add options to the compiler command line to ++cause it to use the precompiled header, and will also set up the ++dependencies for the PCH file. ++Example: ++ ++.ES ++env['PCH'] = 'StdAfx.pch' ++.EE ++ ++.IP PCHCOM ++The command line used by the ++.BR PCH () ++builder to generated a precompiled header. ++ ++.IP PCHCOMSTR ++The string displayed when generating a precompiled header. ++If this is not set, then \fB$PCHCOM\fP (the command line) is displayed. ++ ++.IP PCHPDBFLAGS ++A construction variable that, when expanded, ++adds the \fB/yD\fP flag to the command line ++only if the \fB$PDB\fP construction variable is set. ++ ++.IP PCHSTOP ++This variable specifies how much of a source file is precompiled. This ++variable is ignored by tools other than Microsoft Visual C++, or when ++the PCH variable is not being used. When this variable is define it ++must be a string that is the name of the header that ++is included at the end of the precompiled portion of the source files, or ++the empty string if the "#pragma hrdstop" construct is being used: ++ ++.ES ++env['PCHSTOP'] = 'StdAfx.h' ++.EE ++ ++.IP PDB ++The Microsoft Visual C++ PDB file that will store debugging information for ++object files, shared libraries, and programs. This variable is ignored by ++tools other than Microsoft Visual C++. ++When this variable is ++defined SCons will add options to the compiler and linker command line to ++cause them to generate external debugging information, and will also set up the ++dependencies for the PDB file. ++Example: ++ ++.ES ++env['PDB'] = 'hello.pdb' ++.EE ++.IP ++The Visual C++ compiler switch that SCons uses by default ++to generate PDB information is \fB/Z7\fP. ++This works correctly with parallel (\fB\-j\fP) builds ++because it embeds the debug information in the intermediate object files, ++as opposed to sharing a single PDB file between multiple object files. ++This is also the only way to get debug information ++embedded into a static library. ++Using the \fB/Zi\fP instead may yield improved ++link-time performance, ++although parallel builds will no longer work. ++You can generate PDB files with the \fB/Zi\fP ++switch by overriding the default \fB$CCPDBFLAGS\fP variable; ++see the entry for that variable for specific examples. ++ ++.IP PDFCOM ++A deprecated synonym for \fB$DVIPDFCOM\fP. ++ ++.IP PDFLATEX ++The &pdflatex; utility. ++ ++.IP PDFLATEXCOM ++The command line used to call the &pdflatex; utility. ++ ++.IP PDFLATEXCOMSTR ++The string displayed when calling the &pdflatex; utility. ++If this is not set, then \fB$PDFLATEXCOM\fP (the command line) is displayed. ++ ++.ES ++env = Environment(PDFLATEX;COMSTR = "Building $TARGET from LaTeX input $SOURCES") ++.EE ++ ++.IP PDFLATEXFLAGS ++General options passed to the &pdflatex; utility. ++ ++.IP PDFPREFIX ++The prefix used for PDF file names. ++ ++.IP PDFSUFFIX ++The suffix used for PDF file names. ++ ++.IP PDFTEX ++The &pdftex; utility. ++ ++.IP PDFTEXCOM ++The command line used to call the &pdftex; utility. ++ ++.IP PDFTEXCOMSTR ++The string displayed when calling the &pdftex; utility. ++If this is not set, then \fB$PDFTEXCOM\fP (the command line) is displayed. ++ ++.ES ++env = Environment(PDFTEXCOMSTR = "Building $TARGET from TeX input $SOURCES") ++.EE ++ ++.IP PDFTEXFLAGS ++General options passed to the &pdftex; utility. ++ ++.IP PKGCHK ++On Solaris systems, ++the package-checking program that will ++be used (along with \fB$PKGINFO\fP) ++to look for installed versions of ++the Sun PRO C++ compiler. ++The default is ++.BR /usr/sbin/pgkchk . ++ ++.IP PKGINFO ++On Solaris systems, ++the package information program that will ++be used (along with \fB$PKGCHK\fP) ++to look for installed versions of ++the Sun PRO C++ compiler. ++The default is ++.BR pkginfo . ++ ++.IP PLATFORM ++The name of the platform used to create the Environment. If no platform is ++specified when the Environment is created, ++.B scons ++autodetects the platform. ++ ++.ES ++env = Environment(tools = []) ++if env['PLATFORM'] == 'cygwin': ++ Tool('mingw')(env) ++else: ++ Tool('msvc')(env) ++.EE ++ ++.IP POAUTOINIT ++The \fB$POAUTOINIT\fP variable, if set to \fBTrue\fP (on non-zero ++numeric value), let the &t-link-msginit; tool to automatically initialize ++\fImissing\fP \fBPO\fP files with ++\fBmsginit(1)\fP. This applies to both, ++\fBPOInit\fP() and \fBPOUpdate\fP() builders (and others that use any of ++them). ++ ++.IP POCREATE_ALIAS ++Common alias for all \fBPO\fP files created with \fBPOInit\fP() ++builder (default: \fB'po-create'\fP). ++See &t-link-msginit; tool and \fBPOInit\fP() builder. ++ ++.IP POSUFFIX ++Suffix used for \fBPO\fP files (default: \fB'.po'\fP) ++See &t-link-msginit; tool and \fBPOInit\fP() builder. ++ ++.IP POTDOMAIN ++The \fB$POTDOMAIN\fP defines default domain, used to generate ++\fBPOT\fP filename as \fB\fB$POTDOMAIN\fP.pot\fP when ++no \fBPOT\fP file name is provided by the user. This applies to ++\fBPOTUpdate\fP(), \fBPOInit\fP() and \fBPOUpdate\fP() builders (and ++builders, that use them, e.g. \fBTranslate\fP()). Normally (if \fB$POTDOMAIN\fP is ++not defined), the builders use \fBmessages.pot\fP as default ++\fBPOT\fP file name. ++ ++.IP POTSUFFIX ++Suffix used for PO Template files (default: \fB'.pot'\fP). ++See &t-link-xgettext; tool and \fBPOTUpdate\fP() builder. ++ ++.IP POTUPDATE_ALIAS ++Name of the common phony target for all PO Templates created with ++.BR POUpdate\fP() (default: \fB'pot-update' ). ++See &t-link-xgettext; tool and \fBPOTUpdate\fP() builder. ++ ++.IP POUPDATE_ALIAS ++Common alias for all \fBPO\fP files being defined with ++.BR POUpdate\fP() builder (default: \fB'po-update' ). ++See &t-link-msgmerge; tool and \fBPOUpdate\fP() builder. ++ ++.IP PRINT_CMD_LINE_FUNC ++A Python function used to print the command lines as they are executed ++(assuming command printing is not disabled by the ++.B \-q ++or ++.B \-s ++options or their equivalents). ++The function should take four arguments: ++.IR s , ++the command being executed (a string), ++.IR target , ++the target being built (file node, list, or string name(s)), ++.IR source , ++the source(s) used (file node, list, or string name(s)), and ++.IR env , ++the environment being used. ++ ++The function must do the printing itself. The default implementation, ++used if this variable is not set or is None, is: ++.ES ++def print_cmd_line(s, target, source, env): ++ sys.stdout.write(s + "\\n") ++.EE ++.IP ++Here's an example of a more interesting function: ++ ++.ES ++def print_cmd_line(s, target, source, env): ++ sys.stdout.write("Building %s -> %s...\\n" % ++ (' and '.join([str(x) for x in source]), ++ ' and '.join([str(x) for x in target]))) ++env=Environment(PRINT_CMD_LINE_FUNC=print_cmd_line) ++env.Program('foo', 'foo.c') ++.EE ++.IP ++This just prints "Building \fItargetname\fP from \fIsourcename\fP..." instead ++of the actual commands. ++Such a function could also log the actual commands to a log file, ++for example. ++ ++.IP PROGEMITTER ++TODO ++ ++.IP PROGPREFIX ++The prefix used for executable file names. ++ ++.IP PROGSUFFIX ++The suffix used for executable file names. ++ ++.IP PSCOM ++The command line used to convert TeX DVI files into a PostScript file. ++ ++.IP PSCOMSTR ++The string displayed when a TeX DVI file ++is converted into a PostScript file. ++If this is not set, then \fB$PSCOM\fP (the command line) is displayed. ++ ++.IP PSPREFIX ++The prefix used for PostScript file names. ++ ++.IP PSSUFFIX ++The prefix used for PostScript file names. ++ ++.IP QT_AUTOSCAN ++Turn off scanning for mocable files. Use the Moc Builder to explicitly ++specify files to run moc on. ++ ++.IP QT_BINPATH ++The path where the qt binaries are installed. ++The default value is '\fB$QTDIR\fP/bin'. ++ ++.IP QT_CPPPATH ++The path where the qt header files are installed. ++The default value is '\fB$QTDIR\fP/include'. ++Note: If you set this variable to None, ++the tool won't change the \fB$CPPPATH\fP ++construction variable. ++ ++.IP QT_DEBUG ++Prints lots of debugging information while scanning for moc files. ++ ++.IP QT_LIB ++Default value is 'qt'. You may want to set this to 'qt-mt'. Note: If you set ++this variable to None, the tool won't change the \fB$LIBS\fP variable. ++ ++.IP QT_LIBPATH ++The path where the qt libraries are installed. ++The default value is '\fB$QTDIR\fP/lib'. ++Note: If you set this variable to None, ++the tool won't change the \fB$LIBPATH\fP ++construction variable. ++ ++.IP QT_MOC ++Default value is '\fB$QT_BINPATH\fP/moc'. ++ ++.IP QT_MOCCXXPREFIX ++Default value is ''. Prefix for moc output files, when source is a cxx file. ++ ++.IP QT_MOCCXXSUFFIX ++Default value is '.moc'. Suffix for moc output files, when source is a cxx ++file. ++ ++.IP QT_MOCFROMCXXCOM ++Command to generate a moc file from a cpp file. ++ ++.IP QT_MOCFROMCXXCOMSTR ++The string displayed when generating a moc file from a cpp file. ++If this is not set, then \fB$QT_MOCFROMCXXCOM\fP (the command line) is displayed. ++ ++.IP QT_MOCFROMCXXFLAGS ++Default value is '-i'. These flags are passed to moc, when moccing a ++C++ file. ++ ++.IP QT_MOCFROMHCOM ++Command to generate a moc file from a header. ++ ++.IP QT_MOCFROMHCOMSTR ++The string displayed when generating a moc file from a cpp file. ++If this is not set, then \fB$QT_MOCFROMHCOM\fP (the command line) is displayed. ++ ++.IP QT_MOCFROMHFLAGS ++Default value is ''. These flags are passed to moc, when moccing a header ++file. ++ ++.IP QT_MOCHPREFIX ++Default value is 'moc_'. Prefix for moc output files, when source is a header. ++ ++.IP QT_MOCHSUFFIX ++Default value is '\fB$CXXFILESUFFIX\fP'. Suffix for moc output files, when source is ++a header. ++ ++.IP QT_UIC ++Default value is '\fB$QT_BINPATH\fP/uic'. ++ ++.IP QT_UICCOM ++Command to generate header files from .ui files. ++ ++.IP QT_UICCOMSTR ++The string displayed when generating header files from .ui files. ++If this is not set, then \fB$QT_UICCOM\fP (the command line) is displayed. ++ ++.IP QT_UICDECLFLAGS ++Default value is ''. These flags are passed to uic, when creating a a h ++file from a .ui file. ++ ++.IP QT_UICDECLPREFIX ++Default value is ''. Prefix for uic generated header files. ++ ++.IP QT_UICDECLSUFFIX ++Default value is '.h'. Suffix for uic generated header files. ++ ++.IP QT_UICIMPLFLAGS ++Default value is ''. These flags are passed to uic, when creating a cxx ++file from a .ui file. ++ ++.IP QT_UICIMPLPREFIX ++Default value is 'uic_'. Prefix for uic generated implementation files. ++ ++.IP QT_UICIMPLSUFFIX ++Default value is '\fB$CXXFILESUFFIX\fP'. Suffix for uic generated implementation ++files. ++ ++.IP QT_UISUFFIX ++Default value is '.ui'. Suffix of designer input files. ++ ++.IP QTDIR ++The qt tool tries to take this from os.environ. ++It also initializes all QT_* ++construction variables listed below. ++(Note that all paths are constructed ++with python's os.path.join() method, ++but are listed here with the '/' separator ++for easier reading.) ++In addition, the construction environment ++variables \fB$CPPPATH\fP, ++\fB$LIBPATH\fP and ++\fB$LIBS\fP may be modified ++and the variables ++.BR $PROGEMITTER\fP, \fB$SHLIBEMITTER and $LIBEMITTER ++are modified. Because the build-performance is affected when using this tool, ++you have to explicitly specify it at Environment creation: ++ ++.ES ++Environment(tools=['default','qt']) ++.EE ++.IP ++The qt tool supports the following operations: ++ ++.I "Automatic moc file generation from header files." ++You do not have to specify moc files explicitly, the tool does it for you. ++However, there are a few preconditions to do so: Your header file must have ++the same filebase as your implementation file and must stay in the same ++directory. It must have one of the suffixes .h, .hpp, .H, .hxx, .hh. You ++can turn off automatic moc file generation by setting QT_AUTOSCAN to 0. ++See also the corresponding ++.BR Moc() () ++builder method. ++ ++.I "Automatic moc file generation from cxx files." ++As stated in the qt documentation, include the moc file at the end of ++the cxx file. Note that you have to include the file, which is generated ++by the transformation ${QT_MOCCXXPREFIX}<basename>${QT_MOCCXXSUFFIX}, by default ++<basename>.moc. A warning is generated after building the moc file, if you ++do not include the correct file. If you are using VariantDir, you may ++need to specify duplicate=1. You can turn off automatic moc file generation ++by setting QT_AUTOSCAN to 0. See also the corresponding ++.BR Moc () ++builder method. ++ ++.I "Automatic handling of .ui files." ++The implementation files generated from .ui files are handled much the same ++as yacc or lex files. Each .ui file given as a source of Program, Library or ++SharedLibrary will generate three files, the declaration file, the ++implementation file and a moc file. Because there are also generated headers, ++you may need to specify duplicate=1 in calls to VariantDir. ++See also the corresponding ++.BR Uic () ++builder method. ++ ++.IP RANLIB ++The archive indexer. ++ ++.IP RANLIBCOM ++The command line used to index a static library archive. ++ ++.IP RANLIBCOMSTR ++The string displayed when a static library archive is indexed. ++If this is not set, then \fB$RANLIBCOM\fP (the command line) is displayed. ++ ++.ES ++env = Environment(RANLIBCOMSTR = "Indexing $TARGET") ++.EE ++ ++.IP RANLIBFLAGS ++General options passed to the archive indexer. ++ ++.IP RC ++The resource compiler used to build ++a Microsoft Visual C++ resource file. ++ ++.IP RCCOM ++The command line used to build ++a Microsoft Visual C++ resource file. ++ ++.IP RCCOMSTR ++The string displayed when invoking the resource compiler ++to build a Microsoft Visual C++ resource file. ++If this is not set, then \fB$RCCOM\fP (the command line) is displayed. ++ ++.IP RCFLAGS ++The flags passed to the resource compiler by the RES builder. ++ ++.IP RCINCFLAGS ++An automatically-generated construction variable ++containing the command-line options ++for specifying directories to be searched ++by the resource compiler. ++The value of \fB$RCINCFLAGS\fP is created ++by appending \fB$RCINCPREFIX\fP and \fB$RCINCSUFFIX\fP ++to the beginning and end ++of each directory in \fB$CPPPATH\fP. ++ ++.IP RCINCPREFIX ++The prefix (flag) used to specify an include directory ++on the resource compiler command line. ++This will be appended to the beginning of each directory ++in the \fB$CPPPATH\fP construction variable ++when the \fB$RCINCFLAGS\fP variable is expanded. ++ ++.IP RCINCSUFFIX ++The suffix used to specify an include directory ++on the resource compiler command line. ++This will be appended to the end of each directory ++in the \fB$CPPPATH\fP construction variable ++when the \fB$RCINCFLAGS\fP variable is expanded. ++ ++.IP RCS ++The RCS executable. ++Note that this variable is not actually used ++for the command to fetch source files from RCS; ++see the ++.B $RCS_CO ++construction variable, below. ++ ++.IP RCS_CO ++The RCS "checkout" executable, ++used to fetch source files from RCS. ++ ++.IP RCS_COCOM ++The command line used to ++fetch (checkout) source files from RCS. ++ ++.IP RCS_COCOMSTR ++The string displayed when fetching ++a source file from RCS. ++If this is not set, then \fB$RCS_COCOM\fP ++(the command line) is displayed. ++ ++.IP RCS_COFLAGS ++Options that are passed to the \fB$RCS_CO\fP command. ++ ++.IP RDirs ++A function that converts a string into a list of Dir instances by ++searching the repositories. ++ ++.IP REGSVR ++The program used on Windows systems ++to register a newly-built DLL library ++whenever the \fBSharedLibrary\fP() builder ++is passed a keyword argument of \fBregister=1\fP. ++ ++.IP REGSVRCOM ++The command line used on Windows systems ++to register a newly-built DLL library ++whenever the \fBSharedLibrary\fP() builder ++is passed a keyword argument of \fBregister=1\fP. ++ ++.IP REGSVRCOMSTR ++The string displayed when registering a newly-built DLL file. ++If this is not set, then \fB$REGSVRCOM\fP (the command line) is displayed. ++ ++.IP REGSVRFLAGS ++Flags passed to the DLL registration program ++on Windows systems when a newly-built DLL library is registered. ++By default, ++this includes the \fB/s\fP ++that prevents dialog boxes from popping up ++and requiring user attention. ++ ++.IP RMIC ++The Java RMI stub compiler. ++ ++.IP RMICCOM ++The command line used to compile stub ++and skeleton class files ++from Java classes that contain RMI implementations. ++Any options specified in the \fB$RMICFLAGS\fP construction variable ++are included on this command line. ++ ++.IP RMICCOMSTR ++The string displayed when compiling ++stub and skeleton class files ++from Java classes that contain RMI implementations. ++If this is not set, then \fB$RMICCOM\fP (the command line) is displayed. ++ ++.ES ++env = Environment(RMICCOMSTR = "Generating stub/skeleton class files $TARGETS from $SOURCES") ++.EE ++ ++.IP RMICFLAGS ++General options passed to the Java RMI stub compiler. ++ ++.IP _RPATH ++An automatically-generated construction variable ++containing the rpath flags to be used when linking ++a program with shared libraries. ++The value of \fB$_RPATH\fP is created ++by appending \fB$RPATHPREFIX\fP and \fB$RPATHSUFFIX\fP ++to the beginning and end ++of each directory in \fB$RPATH\fP. ++ ++.IP RPATH ++A list of paths to search for shared libraries when running programs. ++Currently only used in the GNU (gnulink), ++IRIX (sgilink) and Sun (sunlink) linkers. ++Ignored on platforms and toolchains that don't support it. ++Note that the paths added to RPATH ++are not transformed by ++.B scons ++in any way: if you want an absolute ++path, you must make it absolute yourself. ++ ++.IP RPATHPREFIX ++The prefix used to specify a directory to be searched for ++shared libraries when running programs. ++This will be appended to the beginning of each directory ++in the \fB$RPATH\fP construction variable ++when the \fB$_RPATH\fP variable is automatically generated. ++ ++.IP RPATHSUFFIX ++The suffix used to specify a directory to be searched for ++shared libraries when running programs. ++This will be appended to the end of each directory ++in the \fB$RPATH\fP construction variable ++when the \fB$_RPATH\fP variable is automatically generated. ++ ++.IP RPCGEN ++The RPC protocol compiler. ++ ++.IP RPCGENCLIENTFLAGS ++Options passed to the RPC protocol compiler ++when generating client side stubs. ++These are in addition to any flags specified in the ++.B $RPCGENFLAGS ++construction variable. ++ ++.IP RPCGENFLAGS ++General options passed to the RPC protocol compiler. ++ ++.IP RPCGENHEADERFLAGS ++Options passed to the RPC protocol compiler ++when generating a header file. ++These are in addition to any flags specified in the ++.B $RPCGENFLAGS ++construction variable. ++ ++.IP RPCGENSERVICEFLAGS ++Options passed to the RPC protocol compiler ++when generating server side stubs. ++These are in addition to any flags specified in the ++.B $RPCGENFLAGS ++construction variable. ++ ++.IP RPCGENXDRFLAGS ++Options passed to the RPC protocol compiler ++when generating XDR routines. ++These are in addition to any flags specified in the ++.B $RPCGENFLAGS ++construction variable. ++ ++.IP SCANNERS ++A list of the available implicit dependency scanners. ++New file scanners may be added by ++appending to this list, ++although the more flexible approach ++is to associate scanners ++with a specific Builder. ++See the sections "Builder Objects" ++and "Scanner Objects," ++below, for more information. ++ ++.IP SCCS ++The SCCS executable. ++ ++.IP SCCSCOM ++The command line used to ++fetch source files from SCCS. ++ ++.IP SCCSCOMSTR ++The string displayed when fetching ++a source file from a CVS repository. ++If this is not set, then \fB$SCCSCOM\fP ++(the command line) is displayed. ++ ++.IP SCCSFLAGS ++General options that are passed to SCCS. ++ ++.IP SCCSGETFLAGS ++Options that are passed specifically to the SCCS "get" subcommand. ++This can be set, for example, to ++.B \-e ++to check out editable files from SCCS. ++ ++.IP SCONS_HOME ++The (optional) path to the SCons library directory, ++initialized from the external environment. ++If set, this is used to construct a shorter and more ++efficient search path in the ++.B $MSVSSCONS ++command line executed ++from Microsoft Visual Studio project files. ++ ++.IP SHCC ++The C compiler used for generating shared-library objects. ++ ++.IP SHCCCOM ++The command line used to compile a C source file ++to a shared-library object file. ++Any options specified in the \fB$SHCFLAGS\fP, ++\fB$SHCCFLAGS\fP and ++\fB$CPPFLAGS\fP construction variables ++are included on this command line. ++ ++.IP SHCCCOMSTR ++The string displayed when a C source file ++is compiled to a shared object file. ++If this is not set, then \fB$SHCCCOM\fP (the command line) is displayed. ++ ++.ES ++env = Environment(SHCCCOMSTR = "Compiling shared object $TARGET") ++.EE ++ ++.IP SHCCFLAGS ++Options that are passed to the C and C++ compilers ++to generate shared-library objects. ++ ++.IP SHCFLAGS ++Options that are passed to the C compiler (only; not C++) ++to generate shared-library objects. ++ ++.IP SHCXX ++The C++ compiler used for generating shared-library objects. ++ ++.IP SHCXXCOM ++The command line used to compile a C++ source file ++to a shared-library object file. ++Any options specified in the \fB$SHCXXFLAGS\fP and ++\fB$CPPFLAGS\fP construction variables ++are included on this command line. ++ ++.IP SHCXXCOMSTR ++The string displayed when a C++ source file ++is compiled to a shared object file. ++If this is not set, then \fB$SHCXXCOM\fP (the command line) is displayed. ++ ++.ES ++env = Environment(SHCXXCOMSTR = "Compiling shared object $TARGET") ++.EE ++ ++.IP SHCXXFLAGS ++Options that are passed to the C++ compiler ++to generate shared-library objects. ++ ++.IP SHELL ++A string naming the shell program that will be passed to the ++.B $SPAWN ++function. ++See the ++.B $SPAWN ++construction variable for more information. ++ ++.IP SHF77 ++The Fortran 77 compiler used for generating shared-library objects. ++You should normally set the \fB$SHFORTRAN\fP variable, ++which specifies the default Fortran compiler ++for all Fortran versions. ++You only need to set \fB$SHF77\fP if you need to use a specific compiler ++or compiler version for Fortran 77 files. ++ ++.IP SHF77COM ++The command line used to compile a Fortran 77 source file ++to a shared-library object file. ++You only need to set \fB$SHF77COM\fP if you need to use a specific ++command line for Fortran 77 files. ++You should normally set the \fB$SHFORTRANCOM\fP variable, ++which specifies the default command line ++for all Fortran versions. ++ ++.IP SHF77COMSTR ++The string displayed when a Fortran 77 source file ++is compiled to a shared-library object file. ++If this is not set, then \fB$SHF77COM\fP or \fB$SHFORTRANCOM\fP ++(the command line) is displayed. ++ ++.IP SHF77FLAGS ++Options that are passed to the Fortran 77 compiler ++to generated shared-library objects. ++You only need to set \fB$SHF77FLAGS\fP if you need to define specific ++user options for Fortran 77 files. ++You should normally set the \fB$SHFORTRANFLAGS\fP variable, ++which specifies the user-specified options ++passed to the default Fortran compiler ++for all Fortran versions. ++ ++.IP SHF77PPCOM ++The command line used to compile a Fortran 77 source file to a ++shared-library object file ++after first running the file through the C preprocessor. ++Any options specified in the \fB$SHF77FLAGS\fP and \fB$CPPFLAGS\fP construction variables ++are included on this command line. ++You only need to set \fB$SHF77PPCOM\fP if you need to use a specific ++C-preprocessor command line for Fortran 77 files. ++You should normally set the \fB$SHFORTRANPPCOM\fP variable, ++which specifies the default C-preprocessor command line ++for all Fortran versions. ++ ++.IP SHF77PPCOMSTR ++The string displayed when a Fortran 77 source file ++is compiled to a shared-library object file ++after first running the file through the C preprocessor. ++If this is not set, then \fB$SHF77PPCOM\fP or \fB$SHFORTRANPPCOM\fP ++(the command line) is displayed. ++ ++.IP SHF90 ++The Fortran 90 compiler used for generating shared-library objects. ++You should normally set the \fB$SHFORTRAN\fP variable, ++which specifies the default Fortran compiler ++for all Fortran versions. ++You only need to set \fB$SHF90\fP if you need to use a specific compiler ++or compiler version for Fortran 90 files. ++ ++.IP SHF90COM ++The command line used to compile a Fortran 90 source file ++to a shared-library object file. ++You only need to set \fB$SHF90COM\fP if you need to use a specific ++command line for Fortran 90 files. ++You should normally set the \fB$SHFORTRANCOM\fP variable, ++which specifies the default command line ++for all Fortran versions. ++ ++.IP SHF90COMSTR ++The string displayed when a Fortran 90 source file ++is compiled to a shared-library object file. ++If this is not set, then \fB$SHF90COM\fP or \fB$SHFORTRANCOM\fP ++(the command line) is displayed. ++ ++.IP SHF90FLAGS ++Options that are passed to the Fortran 90 compiler ++to generated shared-library objects. ++You only need to set \fB$SHF90FLAGS\fP if you need to define specific ++user options for Fortran 90 files. ++You should normally set the \fB$SHFORTRANFLAGS\fP variable, ++which specifies the user-specified options ++passed to the default Fortran compiler ++for all Fortran versions. ++ ++.IP SHF90PPCOM ++The command line used to compile a Fortran 90 source file to a ++shared-library object file ++after first running the file through the C preprocessor. ++Any options specified in the \fB$SHF90FLAGS\fP and \fB$CPPFLAGS\fP construction variables ++are included on this command line. ++You only need to set \fB$SHF90PPCOM\fP if you need to use a specific ++C-preprocessor command line for Fortran 90 files. ++You should normally set the \fB$SHFORTRANPPCOM\fP variable, ++which specifies the default C-preprocessor command line ++for all Fortran versions. ++ ++.IP SHF90PPCOMSTR ++The string displayed when a Fortran 90 source file ++is compiled to a shared-library object file ++after first running the file through the C preprocessor. ++If this is not set, then \fB$SHF90PPCOM\fP or \fB$SHFORTRANPPCOM\fP ++(the command line) is displayed. ++ ++.IP SHF95 ++The Fortran 95 compiler used for generating shared-library objects. ++You should normally set the \fB$SHFORTRAN\fP variable, ++which specifies the default Fortran compiler ++for all Fortran versions. ++You only need to set \fB$SHF95\fP if you need to use a specific compiler ++or compiler version for Fortran 95 files. ++ ++.IP SHF95COM ++The command line used to compile a Fortran 95 source file ++to a shared-library object file. ++You only need to set \fB$SHF95COM\fP if you need to use a specific ++command line for Fortran 95 files. ++You should normally set the \fB$SHFORTRANCOM\fP variable, ++which specifies the default command line ++for all Fortran versions. ++ ++.IP SHF95COMSTR ++The string displayed when a Fortran 95 source file ++is compiled to a shared-library object file. ++If this is not set, then \fB$SHF95COM\fP or \fB$SHFORTRANCOM\fP ++(the command line) is displayed. ++ ++.IP SHF95FLAGS ++Options that are passed to the Fortran 95 compiler ++to generated shared-library objects. ++You only need to set \fB$SHF95FLAGS\fP if you need to define specific ++user options for Fortran 95 files. ++You should normally set the \fB$SHFORTRANFLAGS\fP variable, ++which specifies the user-specified options ++passed to the default Fortran compiler ++for all Fortran versions. ++ ++.IP SHF95PPCOM ++The command line used to compile a Fortran 95 source file to a ++shared-library object file ++after first running the file through the C preprocessor. ++Any options specified in the \fB$SHF95FLAGS\fP and \fB$CPPFLAGS\fP construction variables ++are included on this command line. ++You only need to set \fB$SHF95PPCOM\fP if you need to use a specific ++C-preprocessor command line for Fortran 95 files. ++You should normally set the \fB$SHFORTRANPPCOM\fP variable, ++which specifies the default C-preprocessor command line ++for all Fortran versions. ++ ++.IP SHF95PPCOMSTR ++The string displayed when a Fortran 95 source file ++is compiled to a shared-library object file ++after first running the file through the C preprocessor. ++If this is not set, then \fB$SHF95PPCOM\fP or \fB$SHFORTRANPPCOM\fP ++(the command line) is displayed. ++ ++.IP SHFORTRAN ++The default Fortran compiler used for generating shared-library objects. ++ ++.IP SHFORTRANCOM ++The command line used to compile a Fortran source file ++to a shared-library object file. ++ ++.IP SHFORTRANCOMSTR ++The string displayed when a Fortran source file ++is compiled to a shared-library object file. ++If this is not set, then \fB$SHFORTRANCOM\fP ++(the command line) is displayed. ++ ++.IP SHFORTRANFLAGS ++Options that are passed to the Fortran compiler ++to generate shared-library objects. ++ ++.IP SHFORTRANPPCOM ++The command line used to compile a Fortran source file to a ++shared-library object file ++after first running the file through the C preprocessor. ++Any options specified ++in the \fB$SHFORTRANFLAGS\fP and ++\fB$CPPFLAGS\fP construction variables ++are included on this command line. ++ ++.IP SHFORTRANPPCOMSTR ++The string displayed when a Fortran source file ++is compiled to a shared-library object file ++after first running the file through the C preprocessor. ++If this is not set, then \fB$SHFORTRANPPCOM\fP ++(the command line) is displayed. ++ ++.IP SHLIBEMITTER ++TODO ++ ++.IP SHLIBPREFIX ++The prefix used for shared library file names. ++ ++.IP SHLIBSUFFIX ++The suffix used for shared library file names. ++ ++.IP SHLIBVERSION ++When this construction variable is defined, a versioned shared library ++is created. This modifies the \fB$SHLINKFLAGS\fP as required, adds ++the version number to the library name, and creates the symlinks that ++are needed. \fB$SHLIBVERSION\fP needs to be of the form X.Y.Z, ++where X and Y are numbers, and Z is a number but can also contain ++letters to designate alpha, beta, or release candidate patch levels. ++ ++.IP SHLINK ++The linker for programs that use shared libraries. ++ ++.IP SHLINKCOM ++The command line used to link programs using shared libraries. ++ ++.IP SHLINKCOMSTR ++The string displayed when programs using shared libraries are linked. ++If this is not set, then \fB$SHLINKCOM\fP (the command line) is displayed. ++ ++.ES ++env = Environment(SHLINKCOMSTR = "Linking shared $TARGET") ++.EE ++ ++.IP SHLINKFLAGS ++General user options passed to the linker for programs using shared libraries. ++Note that this variable should ++.I not ++contain ++.B \-l ++(or similar) options for linking with the libraries listed in \fB$LIBS\fP, ++nor ++.B \-L ++(or similar) include search path options ++that scons generates automatically from \fB$LIBPATH\fP. ++See ++.B $_LIBFLAGS ++above, ++for the variable that expands to library-link options, ++and ++.B $_LIBDIRFLAGS ++above, ++for the variable that expands to library search path options. ++ ++.IP SHOBJPREFIX ++The prefix used for shared object file names. ++ ++.IP SHOBJSUFFIX ++The suffix used for shared object file names. ++ ++.IP SOURCE ++A reserved variable name ++that may not be set or used in a construction environment. ++(See "Variable Substitution," below.) ++ ++.IP SOURCE_URL ++The URL ++(web address) ++of the location from which the project was retrieved. ++This is used to fill in the ++.B Source: ++field in the controlling information for Ipkg and RPM packages. ++ ++.IP SOURCES ++A reserved variable name ++that may not be set or used in a construction environment. ++(See "Variable Substitution," below.) ++ ++.IP SPAWN ++A command interpreter function that will be called to execute command line ++strings. The function must expect the following arguments: ++ ++.ES ++def spawn(shell, escape, cmd, args, env): ++.EE ++.IP ++.I sh ++is a string naming the shell program to use. ++.I escape ++is a function that can be called to escape shell special characters in ++the command line. ++.I cmd ++is the path to the command to be executed. ++.I args ++is the arguments to the command. ++.I env ++is a dictionary of the environment variables ++in which the command should be executed. ++ ++.IP SUBST_DICT ++The dictionary used by the \fBSubstfile\fP() or \fBTextfile\fP() builders ++for substitution values. ++It can be anything acceptable to the dict() constructor, ++so in addition to a dictionary, ++lists of tuples are also acceptable. ++ ++.IP SUBSTFILEPREFIX ++The prefix used for \fBSubstfile\fP() file names, ++the null string by default. ++ ++.IP SUBSTFILESUFFIX ++The suffix used for \fBSubstfile\fP() file names, ++the null string by default. ++ ++.IP SUMMARY ++A short summary of what the project is about. ++This is used to fill in the ++.B Summary: ++field in the controlling information for Ipkg and RPM packages, ++and as the ++.B Description: ++field in MSI packages. ++ ++.IP SWIG ++The scripting language wrapper and interface generator. ++ ++.IP SWIGCFILESUFFIX ++The suffix that will be used for intermediate C ++source files generated by ++the scripting language wrapper and interface generator. ++The default value is ++.BR _wrap\fP\fB$CFILESUFFIX . ++By default, this value is used whenever the ++.B \-c++ ++option is ++.I not ++specified as part of the ++.B $SWIGFLAGS ++construction variable. ++ ++.IP SWIGCOM ++The command line used to call ++the scripting language wrapper and interface generator. ++ ++.IP SWIGCOMSTR ++The string displayed when calling ++the scripting language wrapper and interface generator. ++If this is not set, then \fB$SWIGCOM\fP (the command line) is displayed. ++ ++.IP SWIGCXXFILESUFFIX ++The suffix that will be used for intermediate C++ ++source files generated by ++the scripting language wrapper and interface generator. ++The default value is ++.BR _wrap\fP\fB$CFILESUFFIX . ++By default, this value is used whenever the ++.B \-c++ ++option is specified as part of the ++.B $SWIGFLAGS ++construction variable. ++ ++.IP SWIGDIRECTORSUFFIX ++The suffix that will be used for intermediate C++ header ++files generated by the scripting language wrapper and interface generator. ++These are only generated for C++ code when the SWIG 'directors' feature is ++turned on. ++The default value is ++.BR _wrap.h . ++ ++.IP SWIGFLAGS ++General options passed to ++the scripting language wrapper and interface generator. ++This is where you should set ++.BR \-python , ++.BR \-perl5 , ++.BR \-tcl , ++or whatever other options you want to specify to SWIG. ++If you set the ++.B \-c++ ++option in this variable, ++.B scons ++will, by default, ++generate a C++ intermediate source file ++with the extension that is specified as the ++.B $CXXFILESUFFIX ++variable. ++ ++.IP _SWIGINCFLAGS ++An automatically-generated construction variable ++containing the SWIG command-line options ++for specifying directories to be searched for included files. ++The value of \fB$_SWIGINCFLAGS\fP is created ++by appending \fB$SWIGINCPREFIX\fP and \fB$SWIGINCSUFFIX\fP ++to the beginning and end ++of each directory in \fB$SWIGPATH\fP. ++ ++.IP SWIGINCPREFIX ++The prefix used to specify an include directory on the SWIG command line. ++This will be appended to the beginning of each directory ++in the \fB$SWIGPATH\fP construction variable ++when the \fB$_SWIGINCFLAGS\fP variable is automatically generated. ++ ++.IP SWIGINCSUFFIX ++The suffix used to specify an include directory on the SWIG command line. ++This will be appended to the end of each directory ++in the \fB$SWIGPATH\fP construction variable ++when the \fB$_SWIGINCFLAGS\fP variable is automatically generated. ++ ++.IP SWIGOUTDIR ++Specifies the output directory in which ++the scripting language wrapper and interface generator ++should place generated language-specific files. ++This will be used by SCons to identify ++the files that will be generated by the &swig; call, ++and translated into the ++\fBswig -outdir\fP option on the command line. ++ ++.IP SWIGPATH ++The list of directories that the scripting language wrapper ++and interface generate will search for included files. ++The SWIG implicit dependency scanner will search these ++directories for include files. ++The default is to use the same path ++specified as \fB$CPPPATH\fP. ++ ++Don't explicitly put include directory ++arguments in SWIGFLAGS; ++the result will be non-portable ++and the directories will not be searched by the dependency scanner. ++Note: directory names in SWIGPATH will be looked-up relative to the SConscript ++directory when they are used in a command. ++To force ++.B scons ++to look-up a directory relative to the root of the source tree use #: ++ ++.ES ++env = Environment(SWIGPATH='#/include') ++.EE ++.IP ++The directory look-up can also be forced using the ++.BR Dir () ++function: ++ ++.ES ++include = Dir('include') ++env = Environment(SWIGPATH=include) ++.EE ++.IP ++The directory list will be added to command lines ++through the automatically-generated ++.B $_SWIGINCFLAGS ++construction variable, ++which is constructed by ++appending the values of the ++.BR $SWIGINCPREFIX and $SWIGINCSUFFIX ++construction variables ++to the beginning and end ++of each directory in \fB$SWIGPATH\fP. ++Any command lines you define that need ++the SWIGPATH directory list should ++include \fB$_SWIGINCFLAGS\fP: ++ ++.ES ++env = Environment(SWIGCOM="my_swig -o $TARGET $_SWIGINCFLAGS $SORUCES") ++.EE ++ ++.IP SWIGVERSION ++The version number of the SWIG tool. ++ ++.IP TAR ++The tar archiver. ++ ++.IP TARCOM ++The command line used to call the tar archiver. ++ ++.IP TARCOMSTR ++The string displayed when archiving files ++using the tar archiver. ++If this is not set, then \fB$TARCOM\fP (the command line) is displayed. ++ ++.ES ++env = Environment(TARCOMSTR = "Archiving $TARGET") ++.EE ++ ++.IP TARFLAGS ++General options passed to the tar archiver. ++ ++.IP TARGET ++A reserved variable name ++that may not be set or used in a construction environment. ++(See "Variable Substitution," below.) ++ ++.IP TARGET_ARCH ++Sets the target architecture for Visual Studio compiler (i.e. the arch ++of the binaries generated by the compiler). If not set, default to ++\fB$HOST_ARCH\fP, or, if that is unset, to the architecture of the ++running machine's OS (note that the python build or architecture has no ++effect). ++This variable must be passed as an argument to the Environment() ++constructor; setting it later has no effect. ++This is currently only used on Windows, but in the future it will be ++used on other OSes as well. ++ ++Valid values for Windows are ++.BR x86 , ++.B i386 ++(for 32 bits); ++.BR amd64 , ++.BR emt64 , ++.B x86_64 ++(for 64 bits); ++and \fBia64\fP (Itanium). ++For example, if you want to compile 64-bit binaries, you would set ++\fBTARGET_ARCH='x86_64'\fP in your SCons environment. ++ ++.IP TARGET_OS ++ The name of the target operating system for the compiled objects ++ created by this Environment. ++ This defaults to the value of HOST_OS, and the user can override it. ++ Currently only set for Win32. ++ ++.IP TARGETS ++A reserved variable name ++that may not be set or used in a construction environment. ++(See "Variable Substitution," below.) ++ ++.IP TARSUFFIX ++The suffix used for tar file names. ++ ++.IP TEMPFILEPREFIX ++The prefix for a temporary file used ++to execute lines longer than $MAXLINELENGTH. ++The default is '@'. ++This may be set for toolchains that use other values, ++such as '-@' for the diab compiler ++or '-via' for ARM toolchain. ++ ++.IP TEX ++The TeX formatter and typesetter. ++ ++.IP TEXCOM ++The command line used to call the TeX formatter and typesetter. ++ ++.IP TEXCOMSTR ++The string displayed when calling ++the TeX formatter and typesetter. ++If this is not set, then \fB$TEXCOM\fP (the command line) is displayed. ++ ++.ES ++env = Environment(TEXCOMSTR = "Building $TARGET from TeX input $SOURCES") ++.EE ++ ++.IP TEXFLAGS ++General options passed to the TeX formatter and typesetter. ++ ++.IP TEXINPUTS ++List of directories that the LaTeX program will search ++for include directories. ++The LaTeX implicit dependency scanner will search these ++directories for \\include and \\import files. ++ ++.IP TEXTFILEPREFIX ++The prefix used for \fBTextfile\fP() file names, ++the null string by default. ++ ++.IP TEXTFILESUFFIX ++The suffix used for \fBTextfile\fP() file names; ++\fB.txt\fP by default. ++ ++.IP TOOLS ++A list of the names of the Tool specifications ++that are part of this construction environment. ++ ++.IP UNCHANGED_SOURCES ++A reserved variable name ++that may not be set or used in a construction environment. ++(See "Variable Substitution," below.) ++ ++.IP UNCHANGED_TARGETS ++A reserved variable name ++that may not be set or used in a construction environment. ++(See "Variable Substitution," below.) ++ ++.IP VENDOR ++The person or organization who supply the packaged software. ++This is used to fill in the ++.B Vendor: ++field in the controlling information for RPM packages, ++and the ++.B Manufacturer: ++field in the controlling information for MSI packages. ++ ++.IP VERSION ++The version of the project, specified as a string. ++ ++.IP WIN32_INSERT_DEF ++A deprecated synonym for \fB$WINDOWS_INSERT_DEF\fP. ++ ++.IP WIN32DEFPREFIX ++A deprecated synonym for \fB$WINDOWSDEFPREFIX\fP. ++ ++.IP WIN32DEFSUFFIX ++A deprecated synonym for \fB$WINDOWSDEFSUFFIX\fP. ++ ++.IP WIN32EXPPREFIX ++A deprecated synonym for \fB$WINDOWSEXPSUFFIX\fP. ++ ++.IP WIN32EXPSUFFIX ++A deprecated synonym for \fB$WINDOWSEXPSUFFIX\fP. ++ ++.IP WINDOWS_EMBED_MANIFEST ++Set this variable to True or 1 to embed the compiler-generated manifest ++(normally \fB${TARGET}.manifest\fP) ++into all Windows exes and DLLs built with this environment, ++as a resource during their link step. ++This is done using \fB$MT\fP and \fB$MTEXECOM\fP and \fB$MTSHLIBCOM\fP. ++ ++.IP WINDOWS_INSERT_DEF ++When this is set to true, ++a library build of a Windows shared library ++(\fB.dll\fP file) ++will also build a corresponding \fB.def\fP file ++at the same time, ++if a \fB.def\fP file ++is not already listed as a build target. ++The default is 0 (do not build a \fB.def\fP file). ++ ++.IP WINDOWS_INSERT_MANIFEST ++When this is set to true, ++.B scons ++will be aware of the ++.B .manifest ++files generated by Microsoft Visua C/C++ 8. ++ ++.IP WINDOWSDEFPREFIX ++The prefix used for Windows \fB.def\fP file names. ++ ++.IP WINDOWSDEFSUFFIX ++The suffix used for Windows \fB.def\fP file names. ++ ++.IP WINDOWSEXPPREFIX ++The prefix used for Windows \fB.exp\fP file names. ++ ++.IP WINDOWSEXPSUFFIX ++The suffix used for Windows \fB.exp\fP file names. ++ ++.IP WINDOWSPROGMANIFESTPREFIX ++The prefix used for executable program \fB.manifest\fP files ++generated by Microsoft Visual C/C++. ++ ++.IP WINDOWSPROGMANIFESTSUFFIX ++The suffix used for executable program \fB.manifest\fP files ++generated by Microsoft Visual C/C++. ++ ++.IP WINDOWSSHLIBMANIFESTPREFIX ++The prefix used for shared library \fB.manifest\fP files ++generated by Microsoft Visual C/C++. ++ ++.IP WINDOWSSHLIBMANIFESTSUFFIX ++The suffix used for shared library \fB.manifest\fP files ++generated by Microsoft Visual C/C++. ++ ++.IP X_IPK_DEPENDS ++This is used to fill in the ++.B Depends: ++field in the controlling information for Ipkg packages. ++ ++.IP X_IPK_DESCRIPTION ++This is used to fill in the ++.B Description: ++field in the controlling information for Ipkg packages. ++The default value is ++.B "$SUMMARY\\n$DESCRIPTION" ++.IP X_IPK_MAINTAINER ++This is used to fill in the ++.B Maintainer: ++field in the controlling information for Ipkg packages. ++ ++.IP X_IPK_PRIORITY ++This is used to fill in the ++.B Priority: ++field in the controlling information for Ipkg packages. ++ ++.IP X_IPK_SECTION ++This is used to fill in the ++.B Section: ++field in the controlling information for Ipkg packages. ++ ++.IP X_MSI_LANGUAGE ++This is used to fill in the ++.B Language: ++attribute in the controlling information for MSI packages. ++ ++.IP X_MSI_LICENSE_TEXT ++The text of the software license in RTF format. ++Carriage return characters will be ++replaced with the RTF equivalent \\\\par. ++ ++.IP X_MSI_UPGRADE_CODE ++TODO ++ ++.IP X_RPM_AUTOREQPROV ++This is used to fill in the ++.B AutoReqProv: ++field in the RPM ++\fB.spec\fP file. ++ ++.IP X_RPM_BUILD ++internal, but overridable ++ ++.IP X_RPM_BUILDREQUIRES ++This is used to fill in the ++.B BuildRequires: ++field in the RPM ++\fB.spec\fP file. ++ ++.IP X_RPM_BUILDROOT ++internal, but overridable ++ ++.IP X_RPM_CLEAN ++internal, but overridable ++ ++.IP X_RPM_CONFLICTS ++This is used to fill in the ++.B Conflicts: ++field in the RPM ++\fB.spec\fP file. ++ ++.IP X_RPM_DEFATTR ++This value is used as the default attributes ++for the files in the RPM package. ++The default value is ++.BR (-,root,root) . ++ ++.IP X_RPM_DISTRIBUTION ++This is used to fill in the ++.B Distribution: ++field in the RPM ++\fB.spec\fP file. ++ ++.IP X_RPM_EPOCH ++This is used to fill in the ++.B Epoch: ++field in the controlling information for RPM packages. ++ ++.IP X_RPM_EXCLUDEARCH ++This is used to fill in the ++.B ExcludeArch: ++field in the RPM ++\fB.spec\fP file. ++ ++.IP X_RPM_EXLUSIVEARCH ++This is used to fill in the ++.B ExclusiveArch: ++field in the RPM ++\fB.spec\fP file. ++ ++.IP X_RPM_GROUP ++This is used to fill in the ++.B Group: ++field in the RPM ++\fB.spec\fP file. ++ ++.IP X_RPM_GROUP_lang ++This is used to fill in the ++.B Group(lang): ++field in the RPM ++\fB.spec\fP file. ++Note that ++.I lang ++is not literal ++and should be replaced by ++the appropriate language code. ++ ++.IP X_RPM_ICON ++This is used to fill in the ++.B Icon: ++field in the RPM ++\fB.spec\fP file. ++ ++.IP X_RPM_INSTALL ++internal, but overridable ++ ++.IP X_RPM_PACKAGER ++This is used to fill in the ++.B Packager: ++field in the RPM ++\fB.spec\fP file. ++ ++.IP X_RPM_POSTINSTALL ++This is used to fill in the ++.B %post: ++section in the RPM ++\fB.spec\fP file. ++ ++.IP X_RPM_POSTUNINSTALL ++This is used to fill in the ++.B %postun: ++section in the RPM ++\fB.spec\fP file. ++ ++.IP X_RPM_PREFIX ++This is used to fill in the ++.B Prefix: ++field in the RPM ++\fB.spec\fP file. ++ ++.IP X_RPM_PREINSTALL ++This is used to fill in the ++.B %pre: ++section in the RPM ++\fB.spec\fP file. ++ ++.IP X_RPM_PREP ++internal, but overridable ++ ++.IP X_RPM_PREUNINSTALL ++This is used to fill in the ++.B %preun: ++section in the RPM ++\fB.spec\fP file. ++ ++.IP X_RPM_PROVIDES ++This is used to fill in the ++.B Provides: ++field in the RPM ++\fB.spec\fP file. ++ ++.IP X_RPM_REQUIRES ++This is used to fill in the ++.B Requires: ++field in the RPM ++\fB.spec\fP file. ++ ++.IP X_RPM_SERIAL ++This is used to fill in the ++.B Serial: ++field in the RPM ++\fB.spec\fP file. ++ ++.IP X_RPM_URL ++This is used to fill in the ++.B Url: ++field in the RPM ++\fB.spec\fP file. ++ ++.IP XGETTEXT ++Path to \fBxgettext(1)\fP program (found via ++.BR Detect() ). ++See &t-link-xgettext; tool and \fBPOTUpdate\fP() builder. ++ ++.IP XGETTEXTCOM ++Complete xgettext command line. ++See &t-link-xgettext; tool and \fBPOTUpdate\fP() builder. ++ ++.IP XGETTEXTCOMSTR ++A string that is shown when \fBxgettext(1)\fP command is invoked ++(default: \fB''\fP, which means "print \fB$XGETTEXTCOM\fP"). ++See &t-link-xgettext; tool and \fBPOTUpdate\fP() builder. ++ ++.IP _XGETTEXTDOMAIN ++Internal "macro". Generates \fBxgettext\fP domain name ++form source and target (default: \fB'${TARGET.filebase}'\fP). ++ ++.IP XGETTEXTFLAGS ++Additional flags to \fBxgettext(1)\fP. ++See &t-link-xgettext; tool and \fBPOTUpdate\fP() builder. ++ ++.IP XGETTEXTFROM ++Name of file containing list of \fBxgettext(1)\fP's source ++files. Autotools' users know this as \fBPOTFILES.in\fP so they ++will in most cases set \fBXGETTEXTFROM="POTFILES.in"\fP here. ++The \fB$XGETTEXTFROM\fP files have same syntax and semantics as the well known ++GNU \fBPOTFILES.in\fP. ++See &t-link-xgettext; tool and \fBPOTUpdate\fP() builder. ++ ++.IP _XGETTEXTFROMFLAGS ++Internal "macro". Genrates list of \fB\-D<dir>\fP flags ++from the \fB$XGETTEXTPATH\fP list. ++ ++.IP XGETTEXTFROMPREFIX ++This flag is used to add single \fB$XGETTEXTFROM\fP file to ++\fBxgettext(1)\fP's commandline (default: ++.BR '-f' ). ++ ++.IP XGETTEXTFROMSUFFIX ++(default: \fB''\fP) ++ ++.IP XGETTEXTPATH ++List of directories, there \fBxgettext(1)\fP will look for ++source files (default: \fB[]\fP). ++<note>This variable works only together with \fB$XGETTEXTFROM\fP ++</para></note> ++See also &t-link-xgettext; tool and \fBPOTUpdate\fP() builder. ++ ++.IP _XGETTEXTPATHFLAGS ++Internal "macro". Generates list of \fB\-f<file>\fP flags ++from \fB$XGETTEXTFROM\fP. ++ ++.IP XGETTEXTPATHPREFIX ++This flag is used to add single search path to ++\fBxgettext(1)\fP's commandline (default: ++.BR '-D' ). ++ ++.IP XGETTEXTPATHSUFFIX ++(default: \fB''\fP) ++ ++.IP YACC ++The parser generator. ++ ++.IP YACCCOM ++The command line used to call the parser generator ++to generate a source file. ++ ++.IP YACCCOMSTR ++The string displayed when generating a source file ++using the parser generator. ++If this is not set, then \fB$YACCCOM\fP (the command line) is displayed. ++ ++.ES ++env = Environment(YACCCOMSTR = "Yacc'ing $TARGET from $SOURCES") ++.EE ++ ++.IP YACCFLAGS ++General options passed to the parser generator. ++If \fB$YACCFLAGS\fP contains a \fB\-d\fP option, ++SCons assumes that the call will also create a .h file ++(if the yacc source file ends in a .y suffix) ++or a .hpp file ++(if the yacc source file ends in a .yy suffix) ++ ++.IP YACCHFILESUFFIX ++The suffix of the C ++header file generated by the parser generator ++when the ++.B \-d ++option is used. ++Note that setting this variable does not cause ++the parser generator to generate a header ++file with the specified suffix, ++it exists to allow you to specify ++what suffix the parser generator will use of its own accord. ++The default value is ++.BR .h . ++ ++.IP YACCHXXFILESUFFIX ++The suffix of the C++ ++header file generated by the parser generator ++when the ++.B \-d ++option is used. ++Note that setting this variable does not cause ++the parser generator to generate a header ++file with the specified suffix, ++it exists to allow you to specify ++what suffix the parser generator will use of its own accord. ++The default value is ++.BR .hpp , ++except on Mac OS X, ++where the default is ++.BR ${TARGET.suffix}.h . ++because the default &bison; parser generator just ++appends \fB.h\fP ++to the name of the generated C++ file. ++ ++.IP YACCVCGFILESUFFIX ++The suffix of the file ++containing the VCG grammar automaton definition ++when the ++.B \-\-graph= ++option is used. ++Note that setting this variable does not cause ++the parser generator to generate a VCG ++file with the specified suffix, ++it exists to allow you to specify ++what suffix the parser generator will use of its own accord. ++The default value is ++.BR .vcg . ++ ++.IP ZIP ++The zip compression and file packaging utility. ++ ++.IP ZIPCOM ++The command line used to call the zip utility, ++or the internal Python function used to create a ++zip archive. ++ ++.IP ZIPCOMPRESSION ++The ++.I compression ++flag ++from the Python ++.B zipfile ++module used by the internal Python function ++to control whether the zip archive ++is compressed or not. ++The default value is ++.BR zipfile.ZIP_DEFLATED , ++which creates a compressed zip archive. ++This value has no effect if the ++.B zipfile ++module is unavailable. ++ ++.IP ZIPCOMSTR ++The string displayed when archiving files ++using the zip utility. ++If this is not set, then \fB$ZIPCOM\fP ++(the command line or internal Python function) is displayed. ++ ++.ES ++env = Environment(ZIPCOMSTR = "Zipping $TARGET") ++.EE ++ ++.IP ZIPFLAGS ++General options passed to the zip utility. ++ ++.IP ZIPSUFFIX ++The suffix used for zip file names. ++'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" ++'\" END GENERATED CONSTRUCTION VARIABLE DESCRIPTIONS ++'\" ++'\" The descriptions above of the various SCons construction variables ++'\" are generated from the .xml files that live next to the various ++'\" Python modules in the build enginer library. If you're reading ++'\" this [gnt]roff file with an eye towards patching this man page, ++'\" you can still submit a diff against this text, but it will have to ++'\" be translated to a diff against the underlying .xml file before the ++'\" patch is actually accepted. If you do that yourself, it will make ++'\" it easier to integrate the patch. ++'\" ++'\" END GENERATED CONSTRUCTION VARIABLE DESCRIPTIONS ++'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" ++ ++.LP ++Construction variables can be retrieved and set using the ++.B Dictionary ++method of the construction environment: ++ ++.ES ++dict = env.Dictionary() ++dict["CC"] = "cc" ++.EE ++ ++or using the [] operator: ++ ++.ES ++env["CC"] = "cc" ++.EE ++ ++Construction variables can also be passed to the construction environment ++constructor: ++ ++.ES ++env = Environment(CC="cc") ++.EE ++ ++or when copying a construction environment using the ++.B Clone ++method: ++ ++.ES ++env2 = env.Clone(CC="cl.exe") ++.EE ++ ++.SS Configure Contexts ++ ++.B scons ++supports ++.I configure contexts, ++an integrated mechanism similar to the ++various AC_CHECK macros in GNU autoconf ++for testing for the existence of C header ++files, libraries, etc. ++In contrast to autoconf, ++.B scons ++does not maintain an explicit cache of the tested values, ++but uses its normal dependency tracking to keep the checked values ++up to date. However, users may override this behaviour with the ++.B --config ++command line option. ++ ++The following methods can be used to perform checks: ++ ++.TP ++.RI Configure( env ", [" custom_tests ", " conf_dir ", " log_file ", " config_h ", " clean ", " help]) ++.TP ++.RI env.Configure([ custom_tests ", " conf_dir ", " log_file ", " config_h ", " clean ", " help]) ++This creates a configure context, which can be used to perform checks. ++.I env ++specifies the environment for building the tests. ++This environment may be modified when performing checks. ++.I custom_tests ++is a dictionary containing custom tests. ++See also the section about custom tests below. ++By default, no custom tests are added to the configure context. ++.I conf_dir ++specifies a directory where the test cases are built. ++Note that this directory is not used for building ++normal targets. ++The default value is the directory ++#/.sconf_temp. ++.I log_file ++specifies a file which collects the output from commands ++that are executed to check for the existence of header files, libraries, etc. ++The default is the file #/config.log. ++If you are using the ++.BR VariantDir () ++method, ++you may want to specify a subdirectory under your variant directory. ++.I config_h ++specifies a C header file where the results of tests ++will be written, e.g. #define HAVE_STDIO_H, #define HAVE_LIBM, etc. ++The default is to not write a ++.B config.h ++file. ++You can specify the same ++.B config.h ++file in multiple calls to Configure, ++in which case ++.B scons ++will concatenate all results in the specified file. ++Note that SCons ++uses its normal dependency checking ++to decide if it's necessary to rebuild ++the specified ++.I config_h ++file. ++This means that the file is not necessarily re-built each ++time scons is run, ++but is only rebuilt if its contents will have changed ++and some target that depends on the ++.I config_h ++file is being built. ++ ++The optional ++.B clean ++and ++.B help ++arguments can be used to suppress execution of the configuration ++tests when the ++.B -c/--clean ++or ++.B -H/-h/--help ++options are used, respectively. ++The default behavior is always to execute ++configure context tests, ++since the results of the tests may ++affect the list of targets to be cleaned ++or the help text. ++If the configure tests do not affect these, ++then you may add the ++.B clean=False ++or ++.B help=False ++arguments ++(or both) ++to avoid unnecessary test execution. ++ ++.EE ++A created ++.B Configure ++instance has the following associated methods: ++ ++.TP ++.RI SConf.Finish( context ) ++.TP ++.IR sconf .Finish() ++This method should be called after configuration is done. ++It returns the environment as modified ++by the configuration checks performed. ++After this method is called, no further checks can be performed ++with this configuration context. ++However, you can create a new ++.RI Configure ++context to perform additional checks. ++Only one context should be active at a time. ++ ++The following Checks are predefined. ++(This list will likely grow larger as time ++goes by and developers contribute new useful tests.) ++ ++.TP ++.RI SConf.CheckHeader( context ", " header ", [" include_quotes ", " language ]) ++.TP ++.IR sconf .CheckHeader( header ", [" include_quotes ", " language ]) ++Checks if ++.I header ++is usable in the specified language. ++.I header ++may be a list, ++in which case the last item in the list ++is the header file to be checked, ++and the previous list items are ++header files whose ++.B #include ++lines should precede the ++header line being checked for. ++The optional argument ++.I include_quotes ++must be ++a two character string, where the first character denotes the opening ++quote and the second character denotes the closing quote. ++By default, both characters are " (double quote). ++The optional argument ++.I language ++should be either ++.B C ++or ++.B C++ ++and selects the compiler to be used for the check. ++Returns 1 on success and 0 on failure. ++ ++.TP ++.RI SConf.CheckCHeader( context ", " header ", [" include_quotes ]) ++.TP ++.IR sconf .CheckCHeader( header ", [" include_quotes ]) ++This is a wrapper around ++.B SConf.CheckHeader ++which checks if ++.I header ++is usable in the C language. ++.I header ++may be a list, ++in which case the last item in the list ++is the header file to be checked, ++and the previous list items are ++header files whose ++.B #include ++lines should precede the ++header line being checked for. ++The optional argument ++.I include_quotes ++must be ++a two character string, where the first character denotes the opening ++quote and the second character denotes the closing quote (both default ++to \N'34'). ++Returns 1 on success and 0 on failure. ++ ++.TP ++.RI SConf.CheckCXXHeader( context ", " header ", [" include_quotes ]) ++.TP ++.IR sconf .CheckCXXHeader( header ", [" include_quotes ]) ++This is a wrapper around ++.B SConf.CheckHeader ++which checks if ++.I header ++is usable in the C++ language. ++.I header ++may be a list, ++in which case the last item in the list ++is the header file to be checked, ++and the previous list items are ++header files whose ++.B #include ++lines should precede the ++header line being checked for. ++The optional argument ++.I include_quotes ++must be ++a two character string, where the first character denotes the opening ++quote and the second character denotes the closing quote (both default ++to \N'34'). ++Returns 1 on success and 0 on failure. ++ ++.TP ++.RI SConf.CheckFunc( context, ", " function_name ", [" header ", " language ]) ++.TP ++.IR sconf .CheckFunc( function_name ", [" header ", " language ]) ++Checks if the specified ++C or C++ function is available. ++.I function_name ++is the name of the function to check for. ++The optional ++.I header ++argument is a string ++that will be ++placed at the top ++of the test file ++that will be compiled ++to check if the function exists; ++the default is: ++.ES ++#ifdef __cplusplus ++extern "C" ++#endif ++char function_name(); ++.EE ++The optional ++.I language ++argument should be ++.B C ++or ++.B C++ ++and selects the compiler to be used for the check; ++the default is "C". ++ ++.TP ++.RI SConf.CheckLib( context ", [" library ", " symbol ", " header ", " language ", " autoadd=1 ]) ++.TP ++.IR sconf .CheckLib([ library ", " symbol ", " header ", " language ", " autoadd=1 ]) ++Checks if ++.I library ++provides ++.IR symbol . ++If the value of ++.I autoadd ++is 1 and the library provides the specified ++.IR symbol , ++appends the library to the LIBS construction environment variable. ++.I library ++may also be None (the default), ++in which case ++.I symbol ++is checked with the current LIBS variable, ++or a list of library names, ++in which case each library in the list ++will be checked for ++.IR symbol . ++If ++.I symbol ++is not set or is ++.BR None , ++then ++.BR SConf.CheckLib () ++just checks if ++you can link against the specified ++.IR library . ++The optional ++.I language ++argument should be ++.B C ++or ++.B C++ ++and selects the compiler to be used for the check; ++the default is "C". ++The default value for ++.I autoadd ++is 1. ++This method returns 1 on success and 0 on error. ++ ++.TP ++.RI SConf.CheckLibWithHeader( context ", " library ", " header ", " language ", [" call ", " autoadd ]) ++.TP ++.IR sconf .CheckLibWithHeader( library ", " header ", " language ", [" call ", " autoadd ]) ++ ++In contrast to the ++.RI SConf.CheckLib ++call, this call provides a more sophisticated way to check against libraries. ++Again, ++.I library ++specifies the library or a list of libraries to check. ++.I header ++specifies a header to check for. ++.I header ++may be a list, ++in which case the last item in the list ++is the header file to be checked, ++and the previous list items are ++header files whose ++.B #include ++lines should precede the ++header line being checked for. ++.I language ++may be one of 'C','c','CXX','cxx','C++' and 'c++'. ++.I call ++can be any valid expression (with a trailing ';'). ++If ++.I call ++is not set, ++the default simply checks that you ++can link against the specified ++.IR library . ++.I autoadd ++specifies whether to add the library to the environment (only if the check ++succeeds). This method returns 1 on success and 0 on error. ++ ++.TP ++.RI SConf.CheckType( context ", " type_name ", [" includes ", " language ]) ++.TP ++.IR sconf .CheckType( type_name ", [" includes ", " language ]) ++Checks for the existence of a type defined by ++.BR typedef . ++.I type_name ++specifies the typedef name to check for. ++.I includes ++is a string containing one or more ++.B #include ++lines that will be inserted into the program ++that will be run to test for the existence of the type. ++The optional ++.I language ++argument should be ++.B C ++or ++.B C++ ++and selects the compiler to be used for the check; ++the default is "C". ++Example: ++.ES ++sconf.CheckType('foo_type', '#include "my_types.h"', 'C++') ++.EE ++ ++.TP ++.RI Configure.CheckCC( self ) ++Checks whether the C compiler (as defined by the CC construction variable) works ++by trying to compile a small source file. ++ ++By default, SCons only detects if there is a program with the correct name, not ++if it is a functioning compiler. ++ ++This uses the exact same command than the one used by the object builder for C ++source file, so it can be used to detect if a particular compiler flag works or ++not. ++ ++.TP ++.RI Configure.CheckCXX( self ) ++Checks whether the C++ compiler (as defined by the CXX construction variable) ++works by trying to compile a small source file. By default, SCons only detects ++if there is a program with the correct name, not if it is a functioning compiler. ++ ++This uses the exact same command than the one used by the object builder for ++CXX source files, so it can be used to detect if a particular compiler flag ++works or not. ++ ++.TP ++.RI Configure.CheckSHCC( self ) ++Checks whether the C compiler (as defined by the SHCC construction variable) works ++by trying to compile a small source file. By default, SCons only detects if ++there is a program with the correct name, not if it is a functioning compiler. ++ ++This uses the exact same command than the one used by the object builder for C ++source file, so it can be used to detect if a particular compiler flag works or ++not. This does not check whether the object code can be used to build a shared ++library, only that the compilation (not link) succeeds. ++ ++.TP ++.RI Configure.CheckSHCXX( self ) ++Checks whether the C++ compiler (as defined by the SHCXX construction variable) ++works by trying to compile a small source file. By default, SCons only detects ++if there is a program with the correct name, not if it is a functioning compiler. ++ ++This uses the exact same command than the one used by the object builder for ++CXX source files, so it can be used to detect if a particular compiler flag ++works or not. This does not check whether the object code can be used to build ++a shared library, only that the compilation (not link) succeeds. ++ ++.EE ++Example of a typical Configure usage: ++ ++.ES ++env = Environment() ++conf = Configure( env ) ++if not conf.CheckCHeader( 'math.h' ): ++ print 'We really need math.h!' ++ Exit(1) ++if conf.CheckLibWithHeader( 'qt', 'qapp.h', 'c++', ++ 'QApplication qapp(0,0);' ): ++ # do stuff for qt - usage, e.g. ++ conf.env.Append( CPPFLAGS = '-DWITH_QT' ) ++env = conf.Finish() ++.EE ++ ++.TP ++.RI SConf.CheckTypeSize( context ", " type_name ", [" header ", " language ", " expect ]) ++.TP ++.IR sconf .CheckTypeSize( type_name ", [" header ", " language ", " expect ]) ++Checks for the size of a type defined by ++.BR typedef . ++.I type_name ++specifies the typedef name to check for. ++The optional ++.I header ++argument is a string ++that will be ++placed at the top ++of the test file ++that will be compiled ++to check if the function exists; ++the default is empty. ++The optional ++.I language ++argument should be ++.B C ++or ++.B C++ ++and selects the compiler to be used for the check; ++the default is "C". ++The optional ++.I expect ++argument should be an integer. ++If this argument is used, ++the function will only check whether the type ++given in type_name has the expected size (in bytes). ++For example, ++.B "CheckTypeSize('short', expect = 2)" ++will return success only if short is two bytes. ++ ++.ES ++.EE ++ ++.TP ++.RI SConf.CheckDeclaration( context ", " symbol ", [" includes ", " language ]) ++.TP ++.IR sconf .CheckDeclaration( symbol ", [" includes ", " language ]) ++Checks if the specified ++.I symbol ++is declared. ++.I includes ++is a string containing one or more ++.B #include ++lines that will be inserted into the program ++that will be run to test for the existence of the type. ++The optional ++.I language ++argument should be ++.B C ++or ++.B C++ ++and selects the compiler to be used for the check; ++the default is "C". ++ ++.TP ++.RI SConf.Define( context ", " symbol ", [" value ", " comment ]) ++.TP ++.IR sconf .Define( symbol ", [" value ", " comment ]) ++This function does not check for anything, but defines a ++preprocessor symbol that will be added to the configuration header file. ++It is the equivalent of AC_DEFINE, ++and defines the symbol ++.I name ++with the optional ++.B value ++and the optional comment ++.BR comment . ++ ++.IP ++Examples: ++ ++.ES ++env = Environment() ++conf = Configure( env ) ++ ++# Puts the following line in the config header file: ++# #define A_SYMBOL ++conf.Define('A_SYMBOL') ++ ++# Puts the following line in the config header file: ++# #define A_SYMBOL 1 ++conf.Define('A_SYMBOL', 1) ++.EE ++ ++.IP ++Be careful about quoting string values, though: ++ ++.ES ++env = Environment() ++conf = Configure( env ) ++ ++# Puts the following line in the config header file: ++# #define A_SYMBOL YA ++conf.Define('A_SYMBOL', "YA") ++ ++# Puts the following line in the config header file: ++# #define A_SYMBOL "YA" ++conf.Define('A_SYMBOL', '"YA"') ++.EE ++ ++.IP ++For comment: ++ ++.ES ++env = Environment() ++conf = Configure( env ) ++ ++# Puts the following lines in the config header file: ++# /* Set to 1 if you have a symbol */ ++# #define A_SYMBOL 1 ++conf.Define('A_SYMBOL', 1, 'Set to 1 if you have a symbol') ++.EE ++ ++.EE ++You can define your own custom checks. ++in addition to the predefined checks. ++These are passed in a dictionary to the Configure function. ++This dictionary maps the names of the checks ++to user defined Python callables ++(either Python functions or class instances implementing the ++.I __call__ ++method). ++The first argument of the call is always a ++.I CheckContext ++instance followed by the arguments, ++which must be supplied by the user of the check. ++These CheckContext instances define the following methods: ++ ++.TP ++.RI CheckContext.Message( self ", " text ) ++ ++Usually called before the check is started. ++.I text ++will be displayed to the user, e.g. 'Checking for library X...' ++ ++.TP ++.RI CheckContext.Result( self, ", " res ) ++ ++Usually called after the check is done. ++.I res ++can be either an integer or a string. In the former case, 'yes' (res != 0) ++or 'no' (res == 0) is displayed to the user, in the latter case the ++given string is displayed. ++ ++.TP ++.RI CheckContext.TryCompile( self ", " text ", " extension ) ++Checks if a file with the specified ++.I extension ++(e.g. '.c') containing ++.I text ++can be compiled using the environment's ++.B Object ++builder. Returns 1 on success and 0 on failure. ++ ++.TP ++.RI CheckContext.TryLink( self ", " text ", " extension ) ++Checks, if a file with the specified ++.I extension ++(e.g. '.c') containing ++.I text ++can be compiled using the environment's ++.B Program ++builder. Returns 1 on success and 0 on failure. ++ ++.TP ++.RI CheckContext.TryRun( self ", " text ", " extension ) ++Checks, if a file with the specified ++.I extension ++(e.g. '.c') containing ++.I text ++can be compiled using the environment's ++.B Program ++builder. On success, the program is run. If the program ++executes successfully ++(that is, its return status is 0), ++a tuple ++.I (1, outputStr) ++is returned, where ++.I outputStr ++is the standard output of the ++program. ++If the program fails execution ++(its return status is non-zero), ++then (0, '') is returned. ++ ++.TP ++.RI CheckContext.TryAction( self ", " action ", [" text ", " extension ]) ++Checks if the specified ++.I action ++with an optional source file (contents ++.I text ++, extension ++.I extension ++= '' ++) can be executed. ++.I action ++may be anything which can be converted to a ++.B scons ++.RI Action. ++On success, ++.I (1, outputStr) ++is returned, where ++.I outputStr ++is the content of the target file. ++On failure ++.I (0, '') ++is returned. ++ ++.TP ++.RI CheckContext.TryBuild( self ", " builder ", [" text ", " extension ]) ++Low level implementation for testing specific builds; ++the methods above are based on this method. ++Given the Builder instance ++.I builder ++and the optional ++.I text ++of a source file with optional ++.IR extension , ++this method returns 1 on success and 0 on failure. In addition, ++.I self.lastTarget ++is set to the build target node, if the build was successful. ++ ++.EE ++Example for implementing and using custom tests: ++ ++.ES ++def CheckQt(context, qtdir): ++ context.Message( 'Checking for qt ...' ) ++ lastLIBS = context.env['LIBS'] ++ lastLIBPATH = context.env['LIBPATH'] ++ lastCPPPATH= context.env['CPPPATH'] ++ context.env.Append(LIBS = 'qt', LIBPATH = qtdir + '/lib', CPPPATH = qtdir + '/include' ) ++ ret = context.TryLink(""" ++#include <qapp.h> ++int main(int argc, char **argv) { ++ QApplication qapp(argc, argv); ++ return 0; ++} ++""") ++ if not ret: ++ context.env.Replace(LIBS = lastLIBS, LIBPATH=lastLIBPATH, CPPPATH=lastCPPPATH) ++ context.Result( ret ) ++ return ret ++ ++env = Environment() ++conf = Configure( env, custom_tests = { 'CheckQt' : CheckQt } ) ++if not conf.CheckQt('/usr/lib/qt'): ++ print 'We really need qt!' ++ Exit(1) ++env = conf.Finish() ++.EE ++ ++.SS Command-Line Construction Variables ++ ++Often when building software, ++some variables must be specified at build time. ++For example, libraries needed for the build may be in non-standard ++locations, or site-specific compiler options may need to be passed to the ++compiler. ++.B scons ++provides a ++.B Variables ++object to support overriding construction variables ++on the command line: ++.ES ++$ scons VARIABLE=foo ++.EE ++The variable values can also be specified in a text-based SConscript file. ++To create a Variables object, call the Variables() function: ++ ++.TP ++.RI Variables([ files "], [" args ]) ++This creates a Variables object that will read construction variables from ++the file or list of filenames specified in ++.IR files . ++If no files are specified, ++or the ++.I files ++argument is ++.BR None , ++then no files will be read. ++The optional argument ++.I args ++is a dictionary of ++values that will override anything read from the specified files; ++it is primarily intended to be passed the ++.B ARGUMENTS ++dictionary that holds variables ++specified on the command line. ++Example: ++ ++.ES ++vars = Variables('custom.py') ++vars = Variables('overrides.py', ARGUMENTS) ++vars = Variables(None, {FOO:'expansion', BAR:7}) ++.EE ++ ++Variables objects have the following methods: ++ ++.TP ++.RI Add( key ", [" help ", " default ", " validator ", " converter ]) ++This adds a customizable construction variable to the Variables object. ++.I key ++is the name of the variable. ++.I help ++is the help text for the variable. ++.I default ++is the default value of the variable; ++if the default value is ++.B None ++and there is no explicit value specified, ++the construction variable will ++.I not ++be added to the construction environment. ++.I validator ++is called to validate the value of the variable, and should take three ++arguments: key, value, and environment. ++The recommended way to handle an invalid value is ++to raise an exception (see example below). ++.I converter ++is called to convert the value before putting it in the environment, and ++should take either a value, or the value and environment, as parameters. ++The ++.I converter ++must return a value, ++which will be converted into a string ++before being validated by the ++.I validator ++(if any) ++and then added to the environment. ++ ++Examples: ++ ++.ES ++vars.Add('CC', 'The C compiler') ++ ++def validate_color(key, val, env): ++ if not val in ['red', 'blue', 'yellow']: ++ raise Exception("Invalid color value '%s'" % val) ++vars.Add('COLOR', validator=valid_color) ++.EE ++ ++.TP ++.RI AddVariables( list ) ++A wrapper script that adds ++multiple customizable construction variables ++to a Variables object. ++.I list ++is a list of tuple or list objects ++that contain the arguments ++for an individual call to the ++.B Add ++method. ++ ++.ES ++opt.AddVariables( ++ ('debug', '', 0), ++ ('CC', 'The C compiler'), ++ ('VALIDATE', 'An option for testing validation', ++ 'notset', validator, None), ++ ) ++.EE ++ ++.TP ++.RI Update( env ", [" args ]) ++This updates a construction environment ++.I env ++with the customized construction variables. ++Any specified variables that are ++.I not ++configured for the Variables object ++will be saved and may be ++retrieved with the ++.BR UnknownVariables () ++method, below. ++ ++Normally this method is not called directly, ++but is called indirectly by passing the Variables object to ++the Environment() function: ++ ++.ES ++env = Environment(variables=vars) ++.EE ++ ++.IP ++The text file(s) that were specified ++when the Variables object was created ++are executed as Python scripts, ++and the values of (global) Python variables set in the file ++are added to the construction environment. ++ ++Example: ++ ++.ES ++CC = 'my_cc' ++.EE ++ ++.TP ++.RI UnknownVariables( ) ++Returns a dictionary containing any ++variables that were specified ++either in the files or the dictionary ++with which the Variables object was initialized, ++but for which the Variables object was ++not configured. ++ ++.ES ++env = Environment(variables=vars) ++for key, value in vars.UnknownVariables(): ++ print "unknown variable: %s=%s" % (key, value) ++.EE ++ ++.TP ++.RI Save( filename ", " env ) ++This saves the currently set variables into a script file named ++.I filename ++that can be used on the next invocation to automatically load the current ++settings. This method combined with the Variables method can be used to ++support caching of variables between runs. ++ ++.ES ++env = Environment() ++vars = Variables(['variables.cache', 'custom.py']) ++vars.Add(...) ++vars.Update(env) ++vars.Save('variables.cache', env) ++.EE ++ ++.TP ++.RI GenerateHelpText( env ", [" sort ]) ++This generates help text documenting the customizable construction ++variables suitable to passing in to the Help() function. ++.I env ++is the construction environment that will be used to get the actual values ++of customizable variables. Calling with ++an optional ++.I sort ++function ++will cause the output to be sorted ++by the specified argument. ++The specific ++.I sort ++function ++should take two arguments ++and return ++-1, 0 or 1 ++(like the standard Python ++.I cmp ++function). ++ ++.ES ++Help(vars.GenerateHelpText(env)) ++Help(vars.GenerateHelpText(env, sort=cmp)) ++.EE ++ ++.TP ++.RI FormatVariableHelpText( env ", " opt ", " help ", " default ", " actual ) ++This method returns a formatted string ++containing the printable help text ++for one option. ++It is normally not called directly, ++but is called by the ++.IR GenerateHelpText () ++method to create the returned help text. ++It may be overridden with your own ++function that takes the arguments specified above ++and returns a string of help text formatted to your liking. ++Note that the ++.IR GenerateHelpText () ++will not put any blank lines or extra ++characters in between the entries, ++so you must add those characters to the returned ++string if you want the entries separated. ++ ++.ES ++def my_format(env, opt, help, default, actual): ++ fmt = "\n%s: default=%s actual=%s (%s)\n" ++ return fmt % (opt, default. actual, help) ++vars.FormatVariableHelpText = my_format ++.EE ++ ++To make it more convenient to work with customizable Variables, ++.B scons ++provides a number of functions ++that make it easy to set up ++various types of Variables: ++ ++.TP ++.RI BoolVariable( key ", " help ", " default ) ++Return a tuple of arguments ++to set up a Boolean option. ++The option will use ++the specified name ++.IR key , ++have a default value of ++.IR default , ++and display the specified ++.I help ++text. ++The option will interpret the values ++.BR y , ++.BR yes , ++.BR t , ++.BR true , ++.BR 1 , ++.B on ++and ++.B all ++as true, ++and the values ++.BR n , ++.BR no , ++.BR f , ++.BR false , ++.BR 0 , ++.B off ++and ++.B none ++as false. ++ ++.TP ++.RI EnumVariable( key ", " help ", " default ", " allowed_values ", [" map ", " ignorecase ]) ++Return a tuple of arguments ++to set up an option ++whose value may be one ++of a specified list of legal enumerated values. ++The option will use ++the specified name ++.IR key , ++have a default value of ++.IR default , ++and display the specified ++.I help ++text. ++The option will only support those ++values in the ++.I allowed_values ++list. ++The optional ++.I map ++argument is a dictionary ++that can be used to convert ++input values into specific legal values ++in the ++.I allowed_values ++list. ++If the value of ++.I ignore_case ++is ++.B 0 ++(the default), ++then the values are case-sensitive. ++If the value of ++.I ignore_case ++is ++.BR 1 , ++then values will be matched ++case-insensitive. ++If the value of ++.I ignore_case ++is ++.BR 1 , ++then values will be matched ++case-insensitive, ++and all input values will be ++converted to lower case. ++ ++.TP ++.RI ListVariable( key ", " help ", " default ", " names ", [", map ]) ++Return a tuple of arguments ++to set up an option ++whose value may be one or more ++of a specified list of legal enumerated values. ++The option will use ++the specified name ++.IR key , ++have a default value of ++.IR default , ++and display the specified ++.I help ++text. ++The option will only support the values ++.BR all , ++.BR none , ++or the values in the ++.I names ++list. ++More than one value may be specified, ++with all values separated by commas. ++The default may be a string of ++comma-separated default values, ++or a list of the default values. ++The optional ++.I map ++argument is a dictionary ++that can be used to convert ++input values into specific legal values ++in the ++.I names ++list. ++ ++.TP ++.RI PackageVariable( key ", " help ", " default ) ++Return a tuple of arguments ++to set up an option ++whose value is a path name ++of a package that may be ++enabled, disabled or ++given an explicit path name. ++The option will use ++the specified name ++.IR key , ++have a default value of ++.IR default , ++and display the specified ++.I help ++text. ++The option will support the values ++.BR yes , ++.BR true , ++.BR on , ++.BR enable ++or ++.BR search , ++in which case the specified ++.I default ++will be used, ++or the option may be set to an ++arbitrary string ++(typically the path name to a package ++that is being enabled). ++The option will also support the values ++.BR no , ++.BR false , ++.BR off ++or ++.BR disable ++to disable use of the specified option. ++ ++.TP ++.RI PathVariable( key ", " help ", " default ", [" validator ]) ++Return a tuple of arguments ++to set up an option ++whose value is expected to be a path name. ++The option will use ++the specified name ++.IR key , ++have a default value of ++.IR default , ++and display the specified ++.I help ++text. ++An additional ++.I validator ++may be specified ++that will be called to ++verify that the specified path ++is acceptable. ++SCons supplies the ++following ready-made validators: ++.BR PathVariable.PathExists ++(the default), ++which verifies that the specified path exists; ++.BR PathVariable.PathIsFile , ++which verifies that the specified path is an existing file; ++.BR PathVariable.PathIsDir , ++which verifies that the specified path is an existing directory; ++.BR PathVariable.PathIsDirCreate , ++which verifies that the specified path is a directory ++and will create the specified directory if the path does not exist; ++and ++.BR PathVariable.PathAccept , ++which simply accepts the specific path name argument without validation, ++and which is suitable if you want your users ++to be able to specify a directory path that will be ++created as part of the build process, for example. ++You may supply your own ++.I validator ++function, ++which must take three arguments ++.RI ( key , ++the name of the variable to be set; ++.IR val , ++the specified value being checked; ++and ++.IR env , ++the construction environment) ++and should raise an exception ++if the specified value is not acceptable. ++ ++.RE ++These functions make it ++convenient to create a number ++of variables with consistent behavior ++in a single call to the ++.B AddVariables ++method: ++ ++.ES ++vars.AddVariables( ++ BoolVariable('warnings', 'compilation with -Wall and similiar', 1), ++ EnumVariable('debug', 'debug output and symbols', 'no' ++ allowed_values=('yes', 'no', 'full'), ++ map={}, ignorecase=0), # case sensitive ++ ListVariable('shared', ++ 'libraries to build as shared libraries', ++ 'all', ++ names = list_of_libs), ++ PackageVariable('x11', ++ 'use X11 installed here (yes = search some places)', ++ 'yes'), ++ PathVariable('qtdir', 'where the root of Qt is installed', qtdir), ++ PathVariable('foopath', 'where the foo library is installed', foopath, ++ PathVariable.PathIsDir), ++ ++) ++.EE ++ ++.SS File and Directory Nodes ++ ++The ++.IR File () ++and ++.IR Dir () ++functions return ++.I File ++and ++.I Dir ++Nodes, respectively. ++python objects, respectively. ++Those objects have several user-visible attributes ++and methods that are often useful: ++ ++.IP path ++The build path ++of the given ++file or directory. ++This path is relative to the top-level directory ++(where the ++.B SConstruct ++file is found). ++The build path is the same as the source path if ++.I variant_dir ++is not being used. ++ ++.IP abspath ++The absolute build path of the given file or directory. ++ ++.IP srcnode() ++The ++.IR srcnode () ++method ++returns another ++.I File ++or ++.I Dir ++object representing the ++.I source ++path of the given ++.I File ++or ++.IR Dir . ++The ++ ++.ES ++# Get the current build dir's path, relative to top. ++Dir('.').path ++# Current dir's absolute path ++Dir('.').abspath ++# Next line is always '.', because it is the top dir's path relative to itself. ++Dir('#.').path ++File('foo.c').srcnode().path # source path of the given source file. ++ ++# Builders also return File objects: ++foo = env.Program('foo.c') ++print "foo will be built in %s"%foo.path ++.EE ++ ++A ++.I Dir ++Node or ++.I File ++Node can also be used to create ++file and subdirectory Nodes relative to the generating Node. ++A ++.I Dir ++Node will place the new Nodes within the directory it represents. ++A ++.I File ++node will place the new Nodes within its parent directory ++(that is, "beside" the file in question). ++If ++.I d ++is a ++.I Dir ++(directory) Node and ++.I f ++is a ++.I File ++(file) Node, ++then these methods are available: ++ ++.TP ++.IR d .Dir( name ) ++Returns a directory Node for a subdirectory of ++.I d ++named ++.IR name . ++ ++.TP ++.IR d .File( name ) ++Returns a file Node for a file within ++.I d ++named ++.IR name . ++ ++.TP ++.IR d .Entry( name ) ++Returns an unresolved Node within ++.I d ++named ++.IR name . ++ ++.TP ++.IR f .Dir( name ) ++Returns a directory named ++.I name ++within the parent directory of ++.IR f . ++ ++.TP ++.IR f .File( name ) ++Returns a file named ++.I name ++within the parent directory of ++.IR f . ++ ++.TP ++.IR f .Entry( name ) ++Returns an unresolved Node named ++.I name ++within the parent directory of ++.IR f . ++ ++.RE ++For example: ++ ++.ES ++# Get a Node for a file within a directory ++incl = Dir('include') ++f = incl.File('header.h') ++ ++# Get a Node for a subdirectory within a directory ++dist = Dir('project-3.2.1) ++src = dist.Dir('src') ++ ++# Get a Node for a file in the same directory ++cfile = File('sample.c') ++hfile = cfile.File('sample.h') ++ ++# Combined example ++docs = Dir('docs') ++html = docs.Dir('html') ++index = html.File('index.html') ++css = index.File('app.css') ++.EE ++ ++.SH EXTENDING SCONS ++.SS Builder Objects ++.B scons ++can be extended to build different types of targets ++by adding new Builder objects ++to a construction environment. ++.IR "In general" , ++you should only need to add a new Builder object ++when you want to build a new type of file or other external target. ++If you just want to invoke a different compiler or other tool ++to build a Program, Object, Library, or any other ++type of output file for which ++.B scons ++already has an existing Builder, ++it is generally much easier to ++use those existing Builders ++in a construction environment ++that sets the appropriate construction variables ++(CC, LINK, etc.). ++ ++Builder objects are created ++using the ++.B Builder ++function. ++The ++.B Builder ++function accepts the following arguments: ++ ++.IP action ++The command line string used to build the target from the source. ++.B action ++can also be: ++a list of strings representing the command ++to be executed and its arguments ++(suitable for enclosing white space in an argument), ++a dictionary ++mapping source file name suffixes to ++any combination of command line strings ++(if the builder should accept multiple source file extensions), ++a Python function; ++an Action object ++(see the next section); ++or a list of any of the above. ++ ++An action function ++takes three arguments: ++.I source ++- a list of source nodes, ++.I target ++- a list of target nodes, ++.I env ++- the construction environment. ++ ++.IP prefix ++The prefix that will be prepended to the target file name. ++This may be specified as a: ++ ++.RS 10 ++.HP 6 ++* ++.IR string , ++ ++.HP 6 ++* ++.I callable object ++- a function or other callable that takes ++two arguments (a construction environment and a list of sources) ++and returns a prefix, ++ ++.HP 6 ++* ++.I dictionary ++- specifies a mapping from a specific source suffix (of the first ++source specified) to a corresponding target prefix. Both the source ++suffix and target prefix specifications may use environment variable ++substitution, and the target prefix (the 'value' entries in the ++dictionary) may also be a callable object. The default target prefix ++may be indicated by a dictionary entry with a key value of None. ++.RE ++.P ++ ++.ES ++b = Builder("build_it < $SOURCE > $TARGET", ++ prefix = "file-") ++ ++def gen_prefix(env, sources): ++ return "file-" + env['PLATFORM'] + '-' ++b = Builder("build_it < $SOURCE > $TARGET", ++ prefix = gen_prefix) ++ ++b = Builder("build_it < $SOURCE > $TARGET", ++ suffix = { None: "file-", ++ "$SRC_SFX_A": gen_prefix }) ++.EE ++ ++.IP suffix ++The suffix that will be appended to the target file name. ++This may be specified in the same manner as the prefix above. ++If the suffix is a string, then ++.B scons ++will append a '.' to the beginning of the suffix if it's not already ++there. The string returned by callable object (or obtained from the ++dictionary) is untouched and must append its own '.' to the beginning ++if one is desired. ++ ++.ES ++b = Builder("build_it < $SOURCE > $TARGET" ++ suffix = "-file") ++ ++def gen_suffix(env, sources): ++ return "." + env['PLATFORM'] + "-file" ++b = Builder("build_it < $SOURCE > $TARGET", ++ suffix = gen_suffix) ++ ++b = Builder("build_it < $SOURCE > $TARGET", ++ suffix = { None: ".sfx1", ++ "$SRC_SFX_A": gen_suffix }) ++.EE ++ ++.IP ensure_suffix ++When set to any true value, causes ++.B scons ++to add the target suffix specified by the ++.I suffix ++keyword to any target strings ++that have a different suffix. ++(The default behavior is to leave untouched ++any target file name that looks like it already has any suffix.) ++ ++.ES ++b1 = Builder("build_it < $SOURCE > $TARGET" ++ suffix = ".out") ++b2 = Builder("build_it < $SOURCE > $TARGET" ++ suffix = ".out", ++ ensure_suffix) ++env = Environment() ++env['BUILDERS']['B1'] = b1 ++env['BUILDERS']['B2'] = b2 ++ ++# Builds "foo.txt" because ensure_suffix is not set. ++env.B1('foo.txt', 'foo.in') ++ ++# Builds "bar.txt.out" because ensure_suffix is set. ++env.B2('bar.txt', 'bar.in') ++.EE ++ ++.IP src_suffix ++The expected source file name suffix. This may be a string or a list ++of strings. ++ ++.IP target_scanner ++A Scanner object that ++will be invoked to find ++implicit dependencies for this target file. ++This keyword argument should be used ++for Scanner objects that find ++implicit dependencies ++based only on the target file ++and the construction environment, ++.I not ++for implicit dependencies based on source files. ++(See the section "Scanner Objects" below, ++for information about creating Scanner objects.) ++ ++.IP source_scanner ++A Scanner object that ++will be invoked to ++find implicit dependencies in ++any source files ++used to build this target file. ++This is where you would ++specify a scanner to ++find things like ++.B #include ++lines in source files. ++The pre-built ++.B DirScanner ++Scanner object may be used to ++indicate that this Builder ++should scan directory trees ++for on-disk changes to files ++that ++.B scons ++does not know about from other Builder or function calls. ++(See the section "Scanner Objects" below, ++for information about creating your own Scanner objects.) ++ ++.IP target_factory ++A factory function that the Builder will use ++to turn any targets specified as strings into SCons Nodes. ++By default, ++SCons assumes that all targets are files. ++Other useful target_factory ++values include ++.BR Dir , ++for when a Builder creates a directory target, ++and ++.BR Entry , ++for when a Builder can create either a file ++or directory target. ++ ++Example: ++ ++.ES ++MakeDirectoryBuilder = Builder(action=my_mkdir, target_factory=Dir) ++env = Environment() ++env.Append(BUILDERS = {'MakeDirectory':MakeDirectoryBuilder}) ++env.MakeDirectory('new_directory', []) ++.EE ++ ++.IP ++Note that the call to the MakeDirectory Builder ++needs to specify an empty source list ++to make the string represent the builder's target; ++without that, it would assume the argument is the source, ++and would try to deduce the target name from it, ++which in the absence of an automatically-added prefix or suffix ++would lead to a matching target and source name ++and a circular dependency. ++ ++.IP source_factory ++A factory function that the Builder will use ++to turn any sources specified as strings into SCons Nodes. ++By default, ++SCons assumes that all source are files. ++Other useful source_factory ++values include ++.BR Dir , ++for when a Builder uses a directory as a source, ++and ++.BR Entry , ++for when a Builder can use files ++or directories (or both) as sources. ++ ++Example: ++ ++.ES ++CollectBuilder = Builder(action=my_mkdir, source_factory=Entry) ++env = Environment() ++env.Append(BUILDERS = {'Collect':CollectBuilder}) ++env.Collect('archive', ['directory_name', 'file_name']) ++.EE ++ ++.IP emitter ++A function or list of functions to manipulate the target and source ++lists before dependencies are established ++and the target(s) are actually built. ++.B emitter ++can also be a string containing a construction variable to expand ++to an emitter function or list of functions, ++or a dictionary mapping source file suffixes ++to emitter functions. ++(Only the suffix of the first source file ++is used to select the actual emitter function ++from an emitter dictionary.) ++ ++An emitter function ++takes three arguments: ++.I source ++- a list of source nodes, ++.I target ++- a list of target nodes, ++.I env ++- the construction environment. ++An emitter must return a tuple containing two lists, ++the list of targets to be built by this builder, ++and the list of sources for this builder. ++ ++Example: ++ ++.ES ++def e(target, source, env): ++ return (target + ['foo.foo'], source + ['foo.src']) ++ ++# Simple association of an emitter function with a Builder. ++b = Builder("my_build < $TARGET > $SOURCE", ++ emitter = e) ++ ++def e2(target, source, env): ++ return (target + ['bar.foo'], source + ['bar.src']) ++ ++# Simple association of a list of emitter functions with a Builder. ++b = Builder("my_build < $TARGET > $SOURCE", ++ emitter = [e, e2]) ++ ++# Calling an emitter function through a construction variable. ++env = Environment(MY_EMITTER = e) ++b = Builder("my_build < $TARGET > $SOURCE", ++ emitter = '$MY_EMITTER') ++ ++# Calling a list of emitter functions through a construction variable. ++env = Environment(EMITTER_LIST = [e, e2]) ++b = Builder("my_build < $TARGET > $SOURCE", ++ emitter = '$EMITTER_LIST') ++ ++# Associating multiple emitters with different file ++# suffixes using a dictionary. ++def e_suf1(target, source, env): ++ return (target + ['another_target_file'], source) ++def e_suf2(target, source, env): ++ return (target, source + ['another_source_file']) ++b = Builder("my_build < $TARGET > $SOURCE", ++ emitter = {'.suf1' : e_suf1, ++ '.suf2' : e_suf2}) ++.EE ++ ++.IP multi ++Specifies whether this builder is allowed to be called multiple times for ++the same target file(s). The default is 0, which means the builder ++can not be called multiple times for the same target file(s). Calling a ++builder multiple times for the same target simply adds additional source ++files to the target; it is not allowed to change the environment associated ++with the target, specify addition environment overrides, or associate a different ++builder with the target. ++ ++.IP env ++A construction environment that can be used ++to fetch source code using this Builder. ++(Note that this environment is ++.I not ++used for normal builds of normal target files, ++which use the environment that was ++used to call the Builder for the target file.) ++ ++.IP generator ++A function that returns a list of actions that will be executed to build ++the target(s) from the source(s). ++The returned action(s) may be ++an Action object, or anything that ++can be converted into an Action object ++(see the next section). ++ ++The generator function ++takes four arguments: ++.I source ++- a list of source nodes, ++.I target ++- a list of target nodes, ++.I env ++- the construction environment, ++.I for_signature ++- a Boolean value that specifies ++whether the generator is being called ++for generating a build signature ++(as opposed to actually executing the command). ++Example: ++ ++.ES ++def g(source, target, env, for_signature): ++ return [["gcc", "-c", "-o"] + target + source] ++ ++b = Builder(generator=g) ++.EE ++ ++.IP ++The ++.I generator ++and ++.I action ++arguments must not both be used for the same Builder. ++ ++.IP src_builder ++Specifies a builder to use when a source file name suffix does not match ++any of the suffixes of the builder. Using this argument produces a ++multi-stage builder. ++ ++.IP single_source ++Specifies that this builder expects exactly one source file per call. Giving ++more than one source file without target files results in implicitely calling ++the builder multiple times (once for each source given). Giving multiple ++source files together with target files results in a UserError exception. ++ ++.RE ++.IP ++The ++.I generator ++and ++.I action ++arguments must not both be used for the same Builder. ++ ++.IP source_ext_match ++When the specified ++.I action ++argument is a dictionary, ++the default behavior when a builder is passed ++multiple source files is to make sure that the ++extensions of all the source files match. ++If it is legal for this builder to be ++called with a list of source files with different extensions, ++this check can be suppressed by setting ++.B source_ext_match ++to ++.B None ++or some other non-true value. ++When ++.B source_ext_match ++is disable, ++.B scons ++will use the suffix of the first specified ++source file to select the appropriate action from the ++.I action ++dictionary. ++ ++In the following example, ++the setting of ++.B source_ext_match ++prevents ++.B scons ++from exiting with an error ++due to the mismatched suffixes of ++.B foo.in ++and ++.BR foo.extra . ++ ++.ES ++b = Builder(action={'.in' : 'build $SOURCES > $TARGET'}, ++ source_ext_match = None) ++ ++env = Environment(BUILDERS = {'MyBuild':b}) ++env.MyBuild('foo.out', ['foo.in', 'foo.extra']) ++.EE ++ ++.IP env ++A construction environment that can be used ++to fetch source code using this Builder. ++(Note that this environment is ++.I not ++used for normal builds of normal target files, ++which use the environment that was ++used to call the Builder for the target file.) ++ ++.ES ++b = Builder(action="build < $SOURCE > $TARGET") ++env = Environment(BUILDERS = {'MyBuild' : b}) ++env.MyBuild('foo.out', 'foo.in', my_arg = 'xyzzy') ++.EE ++ ++.IP chdir ++A directory from which scons ++will execute the ++action(s) specified ++for this Builder. ++If the ++.B chdir ++argument is ++a string or a directory Node, ++scons will change to the specified directory. ++If the ++.B chdir ++is not a string or Node ++and is non-zero, ++then scons will change to the ++target file's directory. ++ ++Note that scons will ++.I not ++automatically modify ++its expansion of ++construction variables like ++.B $TARGET ++and ++.B $SOURCE ++when using the chdir ++keyword argument--that is, ++the expanded file names ++will still be relative to ++the top-level SConstruct directory, ++and consequently incorrect ++relative to the chdir directory. ++Builders created using chdir keyword argument, ++will need to use construction variable ++expansions like ++.B ${TARGET.file} ++and ++.B ${SOURCE.file} ++to use just the filename portion of the ++targets and source. ++ ++.ES ++b = Builder(action="build < ${SOURCE.file} > ${TARGET.file}", ++ chdir=1) ++env = Environment(BUILDERS = {'MyBuild' : b}) ++env.MyBuild('sub/dir/foo.out', 'sub/dir/foo.in') ++.EE ++ ++.B WARNING: ++Python only keeps one current directory ++location for all of the threads. ++This means that use of the ++.B chdir ++argument ++will ++.I not ++work with the SCons ++.B -j ++option, ++because individual worker threads spawned ++by SCons interfere with each other ++when they start changing directory. ++ ++.RE ++Any additional keyword arguments supplied ++when a Builder object is created ++(that is, when the Builder() function is called) ++will be set in the executing construction ++environment when the Builder object is called. ++The canonical example here would be ++to set a construction variable to ++the repository of a source code system. ++ ++Any additional keyword arguments supplied ++when a Builder ++.I object ++is called ++will only be associated with the target ++created by that particular Builder call ++(and any other files built as a ++result of the call). ++ ++These extra keyword arguments are passed to the ++following functions: ++command generator functions, ++function Actions, ++and emitter functions. ++ ++.SS Action Objects ++ ++The ++.BR Builder () ++function will turn its ++.B action ++keyword argument into an appropriate ++internal Action object. ++You can also explicity create Action objects ++using the ++.BR Action () ++global function, ++which can then be passed to the ++.BR Builder () ++function. ++This can be used to configure ++an Action object more flexibly, ++or it may simply be more efficient ++than letting each separate Builder object ++create a separate Action ++when multiple ++Builder objects need to do the same thing. ++ ++The ++.BR Action () ++global function ++returns an appropriate object for the action ++represented by the type of the first argument: ++ ++.IP Action ++If the first argument is already an Action object, ++the object is simply returned. ++ ++.IP String ++If the first argument is a string, ++a command-line Action is returned. ++Note that the command-line string ++may be preceded by an ++.B @ ++(at-sign) ++to suppress printing of the specified command line, ++or by a ++.B \- ++(hyphen) ++to ignore the exit status from the specified command: ++ ++.ES ++Action('$CC -c -o $TARGET $SOURCES') ++ ++# Doesn't print the line being executed. ++Action('@build $TARGET $SOURCES') ++ ++# Ignores return value ++Action('-build $TARGET $SOURCES') ++.EE ++.\" XXX From Gary Ruben, 23 April 2002: ++.\" What would be useful is a discussion of how you execute command ++.\" shell commands ie. what is the process used to spawn the shell, pass ++.\" environment variables to it etc., whether there is one shell per ++.\" environment or one per command etc. It might help to look at the Gnu ++.\" make documentation to see what they think is important to discuss about ++.\" a build system. I'm sure you can do a better job of organising the ++.\" documentation than they have :-) ++ ++.IP List ++If the first argument is a list, ++then a list of Action objects is returned. ++An Action object is created as necessary ++for each element in the list. ++If an element ++.I within ++the list is itself a list, ++the internal list is the ++command and arguments to be executed via ++the command line. ++This allows white space to be enclosed ++in an argument by defining ++a command in a list within a list: ++ ++.ES ++Action([['cc', '-c', '-DWHITE SPACE', '-o', '$TARGET', '$SOURCES']]) ++.EE ++ ++.IP Function ++If the first argument is a Python function, ++a function Action is returned. ++The Python function must take three keyword arguments, ++.B target ++(a Node object representing the target file), ++.B source ++(a Node object representing the source file) ++and ++.B env ++(the construction environment ++used for building the target file). ++The ++.B target ++and ++.B source ++arguments may be lists of Node objects if there is ++more than one target file or source file. ++The actual target and source file name(s) may ++be retrieved from their Node objects ++via the built-in Python str() function: ++ ++.ES ++target_file_name = str(target) ++source_file_names = map(lambda x: str(x), source) ++.EE ++.IP ++The function should return ++.B 0 ++or ++.B None ++to indicate a successful build of the target file(s). ++The function may raise an exception ++or return a non-zero exit status ++to indicate an unsuccessful build. ++ ++.ES ++def build_it(target = None, source = None, env = None): ++ # build the target from the source ++ return 0 ++ ++a = Action(build_it) ++.EE ++ ++If the action argument is not one of the above, ++None is returned. ++.PP ++ ++The second argument is optional and is used to define the output ++which is printed when the Action is actually performed. ++In the absence of this parameter, ++or if it's an empty string, ++a default output depending on the type of the action is used. ++For example, a command-line action will print the executed command. ++The argument must be either a Python function or a string. ++ ++In the first case, ++it's a function that returns a string to be printed ++to describe the action being executed. ++The function may also be specified by the ++.IR strfunction = ++keyword argument. ++Like a function to build a file, ++this function must take three keyword arguments: ++.B target ++(a Node object representing the target file), ++.B source ++(a Node object representing the source file) ++and ++.BR env ++(a construction environment). ++The ++.B target ++and ++.B source ++arguments may be lists of Node objects if there is ++more than one target file or source file. ++ ++In the second case, you provide the string itself. ++The string may also be specified by the ++.IR cmdstr = ++keyword argument. ++The string typically contains variables, notably ++$TARGET(S) and $SOURCE(S), or consists of just a single ++variable, which is optionally defined somewhere else. ++SCons itself heavily uses the latter variant. ++ ++Examples: ++ ++.ES ++def build_it(target, source, env): ++ # build the target from the source ++ return 0 ++ ++def string_it(target, source, env): ++ return "building '%s' from '%s'" % (target[0], source[0]) ++ ++# Use a positional argument. ++f = Action(build_it, string_it) ++s = Action(build_it, "building '$TARGET' from '$SOURCE'") ++ ++# Alternatively, use a keyword argument. ++f = Action(build_it, strfunction=string_it) ++s = Action(build_it, cmdstr="building '$TARGET' from '$SOURCE'") ++ ++# You can provide a configurable variable. ++l = Action(build_it, '$STRINGIT') ++.EE ++ ++The third and succeeding arguments, if present, ++may either be a construction variable or a list of construction variables ++whose values will be included in the signature of the Action ++when deciding whether a target should be rebuilt because the action changed. ++The variables may also be specified by a ++.IR varlist = ++keyword parameter; ++if both are present, they are combined. ++This is necessary whenever you want a target to be rebuilt ++when a specific construction variable changes. ++This is not often needed for a string action, ++as the expanded variables will normally be part of the command line, ++but may be needed if a Python function action uses ++the value of a construction variable when generating the command line. ++ ++.ES ++def build_it(target, source, env): ++ # build the target from the 'XXX' construction variable ++ open(target[0], 'w').write(env['XXX']) ++ return 0 ++ ++# Use positional arguments. ++a = Action(build_it, '$STRINGIT', ['XXX']) ++ ++# Alternatively, use a keyword argument. ++a = Action(build_it, varlist=['XXX']) ++.EE ++ ++The ++.BR Action () ++global function ++can be passed the following ++optional keyword arguments ++to modify the Action object's behavior: ++ ++.IP ++.B chdir ++The ++.B chdir ++keyword argument specifies that ++scons will execute the action ++after changing to the specified directory. ++If the ++.B chdir ++argument is ++a string or a directory Node, ++scons will change to the specified directory. ++If the ++.B chdir ++argument ++is not a string or Node ++and is non-zero, ++then scons will change to the ++target file's directory. ++ ++Note that scons will ++.I not ++automatically modify ++its expansion of ++construction variables like ++.B $TARGET ++and ++.B $SOURCE ++when using the chdir ++keyword argument--that is, ++the expanded file names ++will still be relative to ++the top-level SConstruct directory, ++and consequently incorrect ++relative to the chdir directory. ++Builders created using chdir keyword argument, ++will need to use construction variable ++expansions like ++.B ${TARGET.file} ++and ++.B ${SOURCE.file} ++to use just the filename portion of the ++targets and source. ++ ++.ES ++a = Action("build < ${SOURCE.file} > ${TARGET.file}", ++ chdir=1) ++.EE ++ ++.IP ++.B exitstatfunc ++The ++.BR Action () ++global function ++also takes an ++.B exitstatfunc ++keyword argument ++which specifies a function ++that is passed the exit status ++(or return value) ++from the specified action ++and can return an arbitrary ++or modified value. ++This can be used, for example, ++to specify that an Action object's ++return value should be ignored ++under special conditions ++and SCons should, therefore, ++consider that the action always suceeds: ++ ++.ES ++def always_succeed(s): ++ # Always return 0, which indicates success. ++ return 0 ++a = Action("build < ${SOURCE.file} > ${TARGET.file}", ++ exitstatfunc=always_succeed) ++.EE ++ ++.IP ++.B batch_key ++The ++.B batch_key ++keyword argument can be used ++to specify that the Action can create multiple target files ++by processing multiple independent source files simultaneously. ++(The canonical example is "batch compilation" ++of multiple object files ++by passing multiple source files ++to a single invocation of a compiler ++such as Microsoft's Visual C / C++ compiler.) ++If the ++.B batch_key ++argument is any non-False, non-callable Python value, ++the configured Action object will cause ++.B scons ++to collect all targets built with the Action object ++and configured with the same construction environment ++into single invocations of the Action object's ++command line or function. ++Command lines will typically want to use the ++.BR CHANGED_SOURCES ++construction variable ++(and possibly ++.BR CHANGED_TARGETS ++as well) ++to only pass to the command line those sources that ++have actually changed since their targets were built. ++ ++Example: ++ ++.ES ++a = Action('build $CHANGED_SOURCES', batch_key=True) ++.EE ++ ++The ++.B batch_key ++argument may also be ++a callable function ++that returns a key that ++will be used to identify different ++"batches" of target files to be collected ++for batch building. ++A ++.B batch_key ++function must take the following arguments: ++ ++.IP action ++The action object. ++ ++.IP env ++The construction environment ++configured for the target. ++ ++.IP target ++The list of targets for a particular configured action. ++ ++.IP source ++The list of source for a particular configured action. ++ ++The returned key should typically ++be a tuple of values derived from the arguments, ++using any appropriate logic to decide ++how multiple invocations should be batched. ++For example, a ++.B batch_key ++function may decide to return ++the value of a specific construction ++variable from the ++.B env ++argument ++which will cause ++.B scons ++to batch-build targets ++with matching values of that variable, ++or perhaps return the ++.BR id () ++of the entire construction environment, ++in which case ++.B scons ++will batch-build ++all targets configured with the same construction environment. ++Returning ++.B None ++indicates that ++the particular target should ++.I not ++be part of any batched build, ++but instead will be built ++by a separate invocation of action's ++command or function. ++Example: ++ ++.ES ++def batch_key(action, env, target, source): ++ tdir = target[0].dir ++ if tdir.name == 'special': ++ # Don't batch-build any target ++ # in the special/ subdirectory. ++ return None ++ return (id(action), id(env), tdir) ++a = Action('build $CHANGED_SOURCES', batch_key=batch_key) ++.EE ++ ++.SS Miscellaneous Action Functions ++ ++.B scons ++supplies a number of functions ++that arrange for various common ++file and directory manipulations ++to be performed. ++These are similar in concept to "tasks" in the ++Ant build tool, ++although the implementation is slightly different. ++These functions do not actually ++perform the specified action ++at the time the function is called, ++but instead return an Action object ++that can be executed at the ++appropriate time. ++(In Object-Oriented terminology, ++these are actually ++Action ++.I Factory ++functions ++that return Action objects.) ++ ++In practice, ++there are two natural ways ++that these ++Action Functions ++are intended to be used. ++ ++First, ++if you need ++to perform the action ++at the time the SConscript ++file is being read, ++you can use the ++.B Execute ++global function to do so: ++.ES ++Execute(Touch('file')) ++.EE ++ ++Second, ++you can use these functions ++to supply Actions in a list ++for use by the ++.B Command ++method. ++This can allow you to ++perform more complicated ++sequences of file manipulation ++without relying ++on platform-specific ++external commands: ++that ++.ES ++env = Environment(TMPBUILD = '/tmp/builddir') ++env.Command('foo.out', 'foo.in', ++ [Mkdir('$TMPBUILD'), ++ Copy('$TMPBUILD', '${SOURCE.dir}'), ++ "cd $TMPBUILD && make", ++ Delete('$TMPBUILD')]) ++.EE ++ ++.TP ++.RI Chmod( dest ", " mode ) ++Returns an Action object that ++changes the permissions on the specified ++.I dest ++file or directory to the specified ++.IR mode . ++Examples: ++ ++.ES ++Execute(Chmod('file', 0755)) ++ ++env.Command('foo.out', 'foo.in', ++ [Copy('$TARGET', '$SOURCE'), ++ Chmod('$TARGET', 0755)]) ++.EE ++ ++.TP ++.RI Copy( dest ", " src ) ++Returns an Action object ++that will copy the ++.I src ++source file or directory to the ++.I dest ++destination file or directory. ++Examples: ++ ++.ES ++Execute(Copy('foo.output', 'foo.input')) ++ ++env.Command('bar.out', 'bar.in', ++ Copy('$TARGET', '$SOURCE')) ++.EE ++ ++.TP ++.RI Delete( entry ", [" must_exist ]) ++Returns an Action that ++deletes the specified ++.IR entry , ++which may be a file or a directory tree. ++If a directory is specified, ++the entire directory tree ++will be removed. ++If the ++.I must_exist ++flag is set, ++then a Python error will be thrown ++if the specified entry does not exist; ++the default is ++.BR must_exist=0 , ++that is, the Action will silently do nothing ++if the entry does not exist. ++Examples: ++ ++.ES ++Execute(Delete('/tmp/buildroot')) ++ ++env.Command('foo.out', 'foo.in', ++ [Delete('${TARGET.dir}'), ++ MyBuildAction]) ++ ++Execute(Delete('file_that_must_exist', must_exist=1)) ++.EE ++ ++.TP ++.RI Mkdir( dir ) ++Returns an Action ++that creates the specified ++directory ++.I dir . ++Examples: ++ ++.ES ++Execute(Mkdir('/tmp/outputdir')) ++ ++env.Command('foo.out', 'foo.in', ++ [Mkdir('/tmp/builddir'), ++ Copy('/tmp/builddir/foo.in', '$SOURCE'), ++ "cd /tmp/builddir && make", ++ Copy('$TARGET', '/tmp/builddir/foo.out')]) ++.EE ++ ++.TP ++.RI Move( dest ", " src ) ++Returns an Action ++that moves the specified ++.I src ++file or directory to ++the specified ++.I dest ++file or directory. ++Examples: ++ ++.ES ++Execute(Move('file.destination', 'file.source')) ++ ++env.Command('output_file', 'input_file', ++ [MyBuildAction, ++ Move('$TARGET', 'file_created_by_MyBuildAction')]) ++.EE ++ ++.TP ++.RI Touch( file ) ++Returns an Action ++that updates the modification time ++on the specified ++.IR file . ++Examples: ++ ++.ES ++Execute(Touch('file_to_be_touched')) ++ ++env.Command('marker', 'input_file', ++ [MyBuildAction, ++ Touch('$TARGET')]) ++.EE ++ ++.SS Variable Substitution ++ ++Before executing a command, ++.B scons ++performs construction variable interpolation on the strings that make up ++the command line of builders. ++Variables are introduced by a ++.B $ ++prefix. ++Besides construction variables, scons provides the following ++variables for each command execution: ++ ++.IP CHANGED_SOURCES ++The file names of all sources of the build command ++that have changed since the target was last built. ++ ++.IP CHANGED_TARGETS ++The file names of all targets that would be built ++from sources that have changed since the target was last built. ++ ++.IP SOURCE ++The file name of the source of the build command, ++or the file name of the first source ++if multiple sources are being built. ++ ++.IP SOURCES ++The file names of the sources of the build command. ++ ++.IP TARGET ++The file name of the target being built, ++or the file name of the first target ++if multiple targets are being built. ++ ++.IP TARGETS ++The file names of all targets being built. ++ ++.IP UNCHANGED_SOURCES ++The file names of all sources of the build command ++that have ++.I not ++changed since the target was last built. ++ ++.IP UNCHANGED_TARGETS ++The file names of all targets that would be built ++from sources that have ++.I not ++changed since the target was last built. ++ ++(Note that the above variables are reserved ++and may not be set in a construction environment.) ++ ++.LP ++For example, given the construction variable CC='cc', targets=['foo'], and ++sources=['foo.c', 'bar.c']: ++ ++.ES ++action='$CC -c -o $TARGET $SOURCES' ++.EE ++ ++would produce the command line: ++ ++.ES ++cc -c -o foo foo.c bar.c ++.EE ++ ++Variable names may be surrounded by curly braces ({}) ++to separate the name from the trailing characters. ++Within the curly braces, a variable name may have ++a Python slice subscript appended to select one ++or more items from a list. ++In the previous example, the string: ++ ++.ES ++${SOURCES[1]} ++.EE ++ ++would produce: ++ ++.ES ++bar.c ++.EE ++ ++Additionally, a variable name may ++have the following special ++modifiers appended within the enclosing curly braces ++to modify the interpolated string: ++ ++.IP base ++The base path of the file name, ++including the directory path ++but excluding any suffix. ++ ++.IP dir ++The name of the directory in which the file exists. ++ ++.IP file ++The file name, ++minus any directory portion. ++ ++.IP filebase ++Just the basename of the file, ++minus any suffix ++and minus the directory. ++ ++.IP suffix ++Just the file suffix. ++ ++.IP abspath ++The absolute path name of the file. ++ ++.IP posix ++The POSIX form of the path, ++with directories separated by ++.B / ++(forward slashes) ++not backslashes. ++This is sometimes necessary on Windows systems ++when a path references a file on other (POSIX) systems. ++ ++.IP srcpath ++The directory and file name to the source file linked to this file through ++.BR VariantDir (). ++If this file isn't linked, ++it just returns the directory and filename unchanged. ++ ++.IP srcdir ++The directory containing the source file linked to this file through ++.BR VariantDir (). ++If this file isn't linked, ++it just returns the directory part of the filename. ++ ++.IP rsrcpath ++The directory and file name to the source file linked to this file through ++.BR VariantDir (). ++If the file does not exist locally but exists in a Repository, ++the path in the Repository is returned. ++If this file isn't linked, it just returns the ++directory and filename unchanged. ++ ++.IP rsrcdir ++The Repository directory containing the source file linked to this file through ++.BR VariantDir (). ++If this file isn't linked, ++it just returns the directory part of the filename. ++ ++.LP ++For example, the specified target will ++expand as follows for the corresponding modifiers: ++ ++.ES ++$TARGET => sub/dir/file.x ++${TARGET.base} => sub/dir/file ++${TARGET.dir} => sub/dir ++${TARGET.file} => file.x ++${TARGET.filebase} => file ++${TARGET.suffix} => .x ++${TARGET.abspath} => /top/dir/sub/dir/file.x ++ ++SConscript('src/SConscript', variant_dir='sub/dir') ++$SOURCE => sub/dir/file.x ++${SOURCE.srcpath} => src/file.x ++${SOURCE.srcdir} => src ++ ++Repository('/usr/repository') ++$SOURCE => sub/dir/file.x ++${SOURCE.rsrcpath} => /usr/repository/src/file.x ++${SOURCE.rsrcdir} => /usr/repository/src ++.EE ++ ++Note that curly braces braces may also be used ++to enclose arbitrary Python code to be evaluated. ++(In fact, this is how the above modifiers are substituted, ++they are simply attributes of the Python objects ++that represent TARGET, SOURCES, etc.) ++See the section "Python Code Substitution" below, ++for more thorough examples of ++how this can be used. ++ ++Lastly, a variable name ++may be a callable Python function ++associated with a ++construction variable in the environment. ++The function should ++take four arguments: ++.I target ++- a list of target nodes, ++.I source ++- a list of source nodes, ++.I env ++- the construction environment, ++.I for_signature ++- a Boolean value that specifies ++whether the function is being called ++for generating a build signature. ++SCons will insert whatever ++the called function returns ++into the expanded string: ++ ++.ES ++def foo(target, source, env, for_signature): ++ return "bar" ++ ++# Will expand $BAR to "bar baz" ++env=Environment(FOO=foo, BAR="$FOO baz") ++.EE ++ ++You can use this feature to pass arguments to a ++Python function by creating a callable class ++that stores one or more arguments in an object, ++and then uses them when the ++.B __call__() ++method is called. ++Note that in this case, ++the entire variable expansion must ++be enclosed by curly braces ++so that the arguments will ++be associated with the ++instantiation of the class: ++ ++.ES ++class foo(object): ++ def __init__(self, arg): ++ self.arg = arg ++ ++ def __call__(self, target, source, env, for_signature): ++ return self.arg + " bar" ++ ++# Will expand $BAR to "my argument bar baz" ++env=Environment(FOO=foo, BAR="${FOO('my argument')} baz") ++.EE ++ ++.LP ++The special pseudo-variables ++.B "$(" ++and ++.B "$)" ++may be used to surround parts of a command line ++that may change ++.I without ++causing a rebuild--that is, ++which are not included in the signature ++of target files built with this command. ++All text between ++.B "$(" ++and ++.B "$)" ++will be removed from the command line ++before it is added to file signatures, ++and the ++.B "$(" ++and ++.B "$)" ++will be removed before the command is executed. ++For example, the command line: ++ ++.ES ++echo Last build occurred $( $TODAY $). > $TARGET ++.EE ++ ++.LP ++would execute the command: ++ ++.ES ++echo Last build occurred $TODAY. > $TARGET ++.EE ++ ++.LP ++but the command signature added to any target files would be: ++ ++.ES ++echo Last build occurred . > $TARGET ++.EE ++ ++.SS Python Code Substitution ++ ++Any python code within ++.BR "${" - "}" ++pairs gets evaluated by python 'eval', with the python globals set to ++the current environment's set of construction variables. ++So in the following case: ++.ES ++env['COND'] = 0 ++env.Command('foo.out', 'foo.in', ++ '''echo ${COND==1 and 'FOO' or 'BAR'} > $TARGET''') ++.EE ++the command executed will be either ++.ES ++echo FOO > foo.out ++.EE ++or ++.ES ++echo BAR > foo.out ++.EE ++according to the current value of env['COND'] when the command is ++executed. The evaluation occurs when the target is being ++built, not when the SConscript is being read. So if env['COND'] is changed ++later in the SConscript, the final value will be used. ++ ++Here's a more interesting example. Note that all of COND, FOO, and ++BAR are environment variables, and their values are substituted into ++the final command. FOO is a list, so its elements are interpolated ++separated by spaces. ++ ++.ES ++env=Environment() ++env['COND'] = 0 ++env['FOO'] = ['foo1', 'foo2'] ++env['BAR'] = 'barbar' ++env.Command('foo.out', 'foo.in', ++ 'echo ${COND==1 and FOO or BAR} > $TARGET') ++ ++# Will execute this: ++# echo foo1 foo2 > foo.out ++.EE ++ ++SCons uses the following rules when converting construction variables into ++command lines: ++ ++.IP String ++When the value is a string it is interpreted as a space delimited list of ++command line arguments. ++ ++.IP List ++When the value is a list it is interpreted as a list of command line ++arguments. Each element of the list is converted to a string. ++ ++.IP Other ++Anything that is not a list or string is converted to a string and ++interpreted as a single command line argument. ++ ++.IP Newline ++Newline characters (\\n) delimit lines. The newline parsing is done after ++all other parsing, so it is not possible for arguments (e.g. file names) to ++contain embedded newline characters. This limitation will likely go away in ++a future version of SCons. ++ ++.SS Scanner Objects ++ ++You can use the ++.B Scanner ++function to define ++objects to scan ++new file types for implicit dependencies. ++The ++.B Scanner ++function accepts the following arguments: ++ ++.IP function ++This can be either: ++1) a Python function that will process ++the Node (file) ++and return a list of File Nodes ++representing the implicit ++dependencies (file names) found in the contents; ++or: ++2) a dictionary that maps keys ++(typically the file suffix, but see below for more discussion) ++to other Scanners that should be called. ++ ++If the argument is actually a Python function, ++the function must take three or four arguments: ++ ++ def scanner_function(node, env, path): ++ ++ def scanner_function(node, env, path, arg=None): ++ ++The ++.B node ++argument is the internal ++SCons node representing the file. ++Use ++.B str(node) ++to fetch the name of the file, and ++.B node.get_contents() ++to fetch contents of the file. ++Note that the file is ++.I not ++guaranteed to exist before the scanner is called, ++so the scanner function should check that ++if there's any chance that the scanned file ++might not exist ++(for example, if it's built from other files). ++ ++The ++.B env ++argument is the construction environment for the scan. ++Fetch values from it using the ++.B env.Dictionary() ++method. ++ ++The ++.B path ++argument is a tuple (or list) ++of directories that can be searched ++for files. ++This will usually be the tuple returned by the ++.B path_function ++argument (see below). ++ ++The ++.B arg ++argument is the argument supplied ++when the scanner was created, if any. ++ ++.IP name ++The name of the Scanner. ++This is mainly used ++to identify the Scanner internally. ++ ++.IP argument ++An optional argument that, if specified, ++will be passed to the scanner function ++(described above) ++and the path function ++(specified below). ++ ++.IP skeys ++An optional list that can be used to ++determine which scanner should be used for ++a given Node. ++In the usual case of scanning for file names, ++this argument will be a list of suffixes ++for the different file types that this ++Scanner knows how to scan. ++If the argument is a string, ++then it will be expanded ++into a list by the current environment. ++ ++.IP path_function ++A Python function that takes four or five arguments: ++a construction environment, ++a Node for the directory containing ++the SConscript file in which ++the first target was defined, ++a list of target nodes, ++a list of source nodes, ++and an optional argument supplied ++when the scanner was created. ++The ++.B path_function ++returns a tuple of directories ++that can be searched for files to be returned ++by this Scanner object. ++(Note that the ++.BR FindPathDirs () ++function can be used to return a ready-made ++.B path_function ++for a given construction variable name, ++instead of having to write your own function from scratch.) ++ ++.IP node_class ++The class of Node that should be returned ++by this Scanner object. ++Any strings or other objects returned ++by the scanner function ++that are not of this class ++will be run through the ++.B node_factory ++function. ++ ++.IP node_factory ++A Python function that will take a string ++or other object ++and turn it into the appropriate class of Node ++to be returned by this Scanner object. ++ ++.IP scan_check ++An optional Python function that takes two arguments, ++a Node (file) and a construction environment, ++and returns whether the ++Node should, in fact, ++be scanned for dependencies. ++This check can be used to eliminate unnecessary ++calls to the scanner function when, ++for example, the underlying file ++represented by a Node does not yet exist. ++ ++.IP recursive ++An optional flag that ++specifies whether this scanner should be re-invoked ++on the dependency files returned by the scanner. ++When this flag is not set, ++the Node subsystem will ++only invoke the scanner on the file being scanned, ++and not (for example) also on the files ++specified by the #include lines ++in the file being scanned. ++.I recursive ++may be a callable function, ++in which case it will be called with a list of ++Nodes found and ++should return a list of Nodes ++that should be scanned recursively; ++this can be used to select a specific subset of ++Nodes for additional scanning. ++ ++.RE ++Note that ++.B scons ++has a global ++.B SourceFileScanner ++object that is used by ++the ++.BR Object (), ++.BR SharedObject (), ++and ++.BR StaticObject () ++builders to decide ++which scanner should be used ++for different file extensions. ++You can using the ++.BR SourceFileScanner.add_scanner () ++method to add your own Scanner object ++to the ++.B scons ++infrastructure ++that builds target programs or ++libraries from a list of ++source files of different types: ++ ++.ES ++def xyz_scan(node, env, path): ++ contents = node.get_text_contents() ++ # Scan the contents and return the included files. ++ ++XYZScanner = Scanner(xyz_scan) ++ ++SourceFileScanner.add_scanner('.xyz', XYZScanner) ++ ++env.Program('my_prog', ['file1.c', 'file2.f', 'file3.xyz']) ++.EE ++ ++.SH SYSTEM-SPECIFIC BEHAVIOR ++SCons and its configuration files are very portable, ++due largely to its implementation in Python. ++There are, however, a few portability ++issues waiting to trap the unwary. ++.SS .C file suffix ++SCons handles the upper-case ++.B .C ++file suffix differently, ++depending on the capabilities of ++the underlying system. ++On a case-sensitive system ++such as Linux or UNIX, ++SCons treats a file with a ++.B .C ++suffix as a C++ source file. ++On a case-insensitive system ++such as Windows, ++SCons treats a file with a ++.B .C ++suffix as a C source file. ++.SS .F file suffix ++SCons handles the upper-case ++.B .F ++file suffix differently, ++depending on the capabilities of ++the underlying system. ++On a case-sensitive system ++such as Linux or UNIX, ++SCons treats a file with a ++.B .F ++suffix as a Fortran source file ++that is to be first run through ++the standard C preprocessor. ++On a case-insensitive system ++such as Windows, ++SCons treats a file with a ++.B .F ++suffix as a Fortran source file that should ++.I not ++be run through the C preprocessor. ++.SS Windows: Cygwin Tools and Cygwin Python vs. Windows Pythons ++Cygwin supplies a set of tools and utilities ++that let users work on a ++Windows system using a more POSIX-like environment. ++The Cygwin tools, including Cygwin Python, ++do this, in part, ++by sharing an ability to interpret UNIX-like path names. ++For example, the Cygwin tools ++will internally translate a Cygwin path name ++like /cygdrive/c/mydir ++to an equivalent Windows pathname ++of C:/mydir (equivalent to C:\\mydir). ++ ++Versions of Python ++that are built for native Windows execution, ++such as the python.org and ActiveState versions, ++do not have the Cygwin path name semantics. ++This means that using a native Windows version of Python ++to build compiled programs using Cygwin tools ++(such as gcc, bison, and flex) ++may yield unpredictable results. ++"Mixing and matching" in this way ++can be made to work, ++but it requires careful attention to the use of path names ++in your SConscript files. ++ ++In practice, users can sidestep ++the issue by adopting the following rules: ++When using gcc, ++use the Cygwin-supplied Python interpreter ++to run SCons; ++when using Microsoft Visual C/C++ ++(or some other Windows compiler) ++use the python.org or ActiveState version of Python ++to run SCons. ++.SS Windows: scons.bat file ++On Windows systems, ++SCons is executed via a wrapper ++.B scons.bat ++file. ++This has (at least) two ramifications: ++ ++First, Windows command-line users ++that want to use variable assignment ++on the command line ++may have to put double quotes ++around the assignments: ++ ++.ES ++scons "FOO=BAR" "BAZ=BLEH" ++.EE ++ ++Second, the Cygwin shell does not ++recognize this file as being the same ++as an ++.B scons ++command issued at the command-line prompt. ++You can work around this either by ++executing ++.B scons.bat ++from the Cygwin command line, ++or by creating a wrapper shell ++script named ++.B scons . ++ ++.SS MinGW ++ ++The MinGW bin directory must be in your PATH environment variable or the ++PATH variable under the ENV construction variable for SCons ++to detect and use the MinGW tools. When running under the native Windows ++Python interpreter, SCons will prefer the MinGW tools over the Cygwin ++tools, if they are both installed, regardless of the order of the bin ++directories in the PATH variable. If you have both MSVC and MinGW ++installed and you want to use MinGW instead of MSVC, ++then you must explictly tell SCons to use MinGW by passing ++ ++.ES ++tools=['mingw'] ++.EE ++ ++to the Environment() function, because SCons will prefer the MSVC tools ++over the MinGW tools. ++ ++.SH EXAMPLES ++ ++To help you get started using SCons, ++this section contains a brief overview of some common tasks. ++ ++.SS Basic Compilation From a Single Source File ++ ++.ES ++env = Environment() ++env.Program(target = 'foo', source = 'foo.c') ++.EE ++ ++Note: Build the file by specifying ++the target as an argument ++("scons foo" or "scons foo.exe"). ++or by specifying a dot ("scons ."). ++ ++.SS Basic Compilation From Multiple Source Files ++ ++.ES ++env = Environment() ++env.Program(target = 'foo', source = Split('f1.c f2.c f3.c')) ++.EE ++ ++.SS Setting a Compilation Flag ++ ++.ES ++env = Environment(CCFLAGS = '-g') ++env.Program(target = 'foo', source = 'foo.c') ++.EE ++ ++.SS Search The Local Directory For .h Files ++ ++Note: You do ++.I not ++need to set CCFLAGS to specify -I options by hand. ++SCons will construct the right -I options from CPPPATH. ++ ++.ES ++env = Environment(CPPPATH = ['.']) ++env.Program(target = 'foo', source = 'foo.c') ++.EE ++ ++.SS Search Multiple Directories For .h Files ++ ++.ES ++env = Environment(CPPPATH = ['include1', 'include2']) ++env.Program(target = 'foo', source = 'foo.c') ++.EE ++ ++.SS Building a Static Library ++ ++.ES ++env = Environment() ++env.StaticLibrary(target = 'foo', source = Split('l1.c l2.c')) ++env.StaticLibrary(target = 'bar', source = ['l3.c', 'l4.c']) ++.EE ++ ++.SS Building a Shared Library ++ ++.ES ++env = Environment() ++env.SharedLibrary(target = 'foo', source = ['l5.c', 'l6.c']) ++env.SharedLibrary(target = 'bar', source = Split('l7.c l8.c')) ++.EE ++ ++.SS Linking a Local Library Into a Program ++ ++.ES ++env = Environment(LIBS = 'mylib', LIBPATH = ['.']) ++env.Library(target = 'mylib', source = Split('l1.c l2.c')) ++env.Program(target = 'prog', source = ['p1.c', 'p2.c']) ++.EE ++ ++.SS Defining Your Own Builder Object ++ ++Notice that when you invoke the Builder, ++you can leave off the target file suffix, ++and SCons will add it automatically. ++ ++.ES ++bld = Builder(action = 'pdftex < $SOURCES > $TARGET' ++ suffix = '.pdf', ++ src_suffix = '.tex') ++env = Environment(BUILDERS = {'PDFBuilder' : bld}) ++env.PDFBuilder(target = 'foo.pdf', source = 'foo.tex') ++ ++# The following creates "bar.pdf" from "bar.tex" ++env.PDFBuilder(target = 'bar', source = 'bar') ++.EE ++ ++Note also that the above initialization ++overwrites the default Builder objects, ++so the Environment created above ++can not be used call Builders like env.Program(), ++env.Object(), env.StaticLibrary(), etc. ++ ++.SS Adding Your Own Builder Object to an Environment ++ ++.ES ++bld = Builder(action = 'pdftex < $SOURCES > $TARGET' ++ suffix = '.pdf', ++ src_suffix = '.tex') ++env = Environment() ++env.Append(BUILDERS = {'PDFBuilder' : bld}) ++env.PDFBuilder(target = 'foo.pdf', source = 'foo.tex') ++env.Program(target = 'bar', source = 'bar.c') ++.EE ++ ++You also can use other Pythonic techniques to add ++to the BUILDERS construction variable, such as: ++ ++.ES ++env = Environment() ++env['BUILDERS]['PDFBuilder'] = bld ++.EE ++ ++.SS Defining Your Own Scanner Object ++ ++The following example shows an extremely simple scanner (the ++.BR kfile_scan () ++function) ++that doesn't use a search path at all ++and simply returns the ++file names present on any ++.B include ++lines in the scanned file. ++This would implicitly assume that all included ++files live in the top-level directory: ++ ++.ES ++import re ++ ++'\" Note: the \\ in the following are for the benefit of nroff/troff, ++'\" not inappropriate doubled escape characters within the r'' raw string. ++include_re = re.compile(r'^include\\s+(\\S+)$', re.M) ++ ++def kfile_scan(node, env, path, arg): ++ contents = node.get_text_contents() ++ includes = include_re.findall(contents) ++ return env.File(includes) ++ ++kscan = Scanner(name = 'kfile', ++ function = kfile_scan, ++ argument = None, ++ skeys = ['.k']) ++scanners = Environment().Dictionary('SCANNERS') ++env = Environment(SCANNERS = scanners + [kscan]) ++ ++env.Command('foo', 'foo.k', 'kprocess < $SOURCES > $TARGET') ++ ++bar_in = File('bar.in') ++env.Command('bar', bar_in, 'kprocess $SOURCES > $TARGET') ++bar_in.target_scanner = kscan ++.EE ++ ++It is important to note that you ++have to return a list of File nodes from the scan function, simple ++strings for the file names won't do. As in the examples we are showing here, ++you can use the ++.BR File() ++function of your current Environment in order to create nodes on the fly from ++a sequence of file names with relative paths. ++ ++Here is a similar but more complete example that searches ++a path of directories ++(specified as the ++.B MYPATH ++construction variable) ++for files that actually exist: ++ ++.ES ++import re ++import os ++include_re = re.compile(r'^include\\s+(\\S+)$', re.M) ++ ++def my_scan(node, env, path, arg): ++ contents = node.get_text_contents() ++ includes = include_re.findall(contents) ++ if includes == []: ++ return [] ++ results = [] ++ for inc in includes: ++ for dir in path: ++ file = str(dir) + os.sep + inc ++ if os.path.exists(file): ++ results.append(file) ++ break ++ return env.File(results) ++ ++scanner = Scanner(name = 'myscanner', ++ function = my_scan, ++ argument = None, ++ skeys = ['.x'], ++ path_function = FindPathDirs('MYPATH') ++ ) ++scanners = Environment().Dictionary('SCANNERS') ++env = Environment(SCANNERS = scanners + [scanner], ++ MYPATH = ['incs']) ++ ++env.Command('foo', 'foo.x', 'xprocess < $SOURCES > $TARGET') ++.EE ++ ++The ++.BR FindPathDirs () ++function used in the previous example returns a function ++(actually a callable Python object) ++that will return a list of directories ++specified in the ++.B $MYPATH ++construction variable. It lets SCons detect the file ++.B incs/foo.inc ++, even if ++.B foo.x ++contains the line ++.B include foo.inc ++only. ++If you need to customize how the search path is derived, ++you would provide your own ++.B path_function ++argument when creating the Scanner object, ++as follows: ++ ++.ES ++# MYPATH is a list of directories to search for files in ++def pf(env, dir, target, source, arg): ++ top_dir = Dir('#').abspath ++ results = [] ++ if 'MYPATH' in env: ++ for p in env['MYPATH']: ++ results.append(top_dir + os.sep + p) ++ return results ++ ++scanner = Scanner(name = 'myscanner', ++ function = my_scan, ++ argument = None, ++ skeys = ['.x'], ++ path_function = pf ++ ) ++.EE ++ ++.SS Creating a Hierarchical Build ++ ++Notice that the file names specified in a subdirectory's ++SConscript ++file are relative to that subdirectory. ++ ++.ES ++SConstruct: ++ ++ env = Environment() ++ env.Program(target = 'foo', source = 'foo.c') ++ ++ SConscript('sub/SConscript') ++ ++sub/SConscript: ++ ++ env = Environment() ++ # Builds sub/foo from sub/foo.c ++ env.Program(target = 'foo', source = 'foo.c') ++ ++ SConscript('dir/SConscript') ++ ++sub/dir/SConscript: ++ ++ env = Environment() ++ # Builds sub/dir/foo from sub/dir/foo.c ++ env.Program(target = 'foo', source = 'foo.c') ++.EE ++ ++.SS Sharing Variables Between SConscript Files ++ ++You must explicitly Export() and Import() variables that ++you want to share between SConscript files. ++ ++.ES ++SConstruct: ++ ++ env = Environment() ++ env.Program(target = 'foo', source = 'foo.c') ++ ++ Export("env") ++ SConscript('subdirectory/SConscript') ++ ++subdirectory/SConscript: ++ ++ Import("env") ++ env.Program(target = 'foo', source = 'foo.c') ++.EE ++ ++.SS Building Multiple Variants From the Same Source ++ ++Use the variant_dir keyword argument to ++the SConscript function to establish ++one or more separate variant build directory trees ++for a given source directory: ++ ++.ES ++SConstruct: ++ ++ cppdefines = ['FOO'] ++ Export("cppdefines") ++ SConscript('src/SConscript', variant_dir='foo') ++ ++ cppdefines = ['BAR'] ++ Export("cppdefines") ++ SConscript('src/SConscript', variant_dir='bar') ++ ++src/SConscript: ++ ++ Import("cppdefines") ++ env = Environment(CPPDEFINES = cppdefines) ++ env.Program(target = 'src', source = 'src.c') ++.EE ++ ++Note the use of the Export() method ++to set the "cppdefines" variable to a different ++value each time we call the SConscript function. ++ ++.SS Hierarchical Build of Two Libraries Linked With a Program ++ ++.ES ++SConstruct: ++ ++ env = Environment(LIBPATH = ['#libA', '#libB']) ++ Export('env') ++ SConscript('libA/SConscript') ++ SConscript('libB/SConscript') ++ SConscript('Main/SConscript') ++ ++libA/SConscript: ++ ++ Import('env') ++ env.Library('a', Split('a1.c a2.c a3.c')) ++ ++libB/SConscript: ++ ++ Import('env') ++ env.Library('b', Split('b1.c b2.c b3.c')) ++ ++Main/SConscript: ++ ++ Import('env') ++ e = env.Copy(LIBS = ['a', 'b']) ++ e.Program('foo', Split('m1.c m2.c m3.c')) ++.EE ++ ++The '#' in the LIBPATH directories specify that they're relative to the ++top-level directory, so they don't turn into "Main/libA" when they're ++used in Main/SConscript. ++ ++Specifying only 'a' and 'b' for the library names ++allows SCons to append the appropriate library ++prefix and suffix for the current platform ++(for example, 'liba.a' on POSIX systems, ++\&'a.lib' on Windows). ++ ++.SS Customizing construction variables from the command line. ++ ++The following would allow the C compiler to be specified on the command ++line or in the file custom.py. ++ ++.ES ++vars = Variables('custom.py') ++vars.Add('CC', 'The C compiler.') ++env = Environment(variables=vars) ++Help(vars.GenerateHelpText(env)) ++.EE ++ ++The user could specify the C compiler on the command line: ++ ++.ES ++scons "CC=my_cc" ++.EE ++ ++or in the custom.py file: ++ ++.ES ++CC = 'my_cc' ++.EE ++ ++or get documentation on the options: ++ ++.ES ++$ scons -h ++ ++CC: The C compiler. ++ default: None ++ actual: cc ++ ++.EE ++ ++.SS Using Microsoft Visual C++ precompiled headers ++ ++Since windows.h includes everything and the kitchen sink, it can take quite ++some time to compile it over and over again for a bunch of object files, so ++Microsoft provides a mechanism to compile a set of headers once and then ++include the previously compiled headers in any object file. This ++technology is called precompiled headers. The general recipe is to create a ++file named "StdAfx.cpp" that includes a single header named "StdAfx.h", and ++then include every header you want to precompile in "StdAfx.h", and finally ++include "StdAfx.h" as the first header in all the source files you are ++compiling to object files. For example: ++ ++StdAfx.h: ++.ES ++#include <windows.h> ++#include <my_big_header.h> ++.EE ++ ++StdAfx.cpp: ++.ES ++#include <StdAfx.h> ++.EE ++ ++Foo.cpp: ++.ES ++#include <StdAfx.h> ++ ++/* do some stuff */ ++.EE ++ ++Bar.cpp: ++.ES ++#include <StdAfx.h> ++ ++/* do some other stuff */ ++.EE ++ ++SConstruct: ++.ES ++env=Environment() ++env['PCHSTOP'] = 'StdAfx.h' ++env['PCH'] = env.PCH('StdAfx.cpp')[0] ++env.Program('MyApp', ['Foo.cpp', 'Bar.cpp']) ++.EE ++ ++For more information see the document for the PCH builder, and the PCH and ++PCHSTOP construction variables. To learn about the details of precompiled ++headers consult the MSDN documention for /Yc, /Yu, and /Yp. ++ ++.SS Using Microsoft Visual C++ external debugging information ++ ++Since including debugging information in programs and shared libraries can ++cause their size to increase significantly, Microsoft provides a mechanism ++for including the debugging information in an external file called a PDB ++file. SCons supports PDB files through the PDB construction ++variable. ++ ++SConstruct: ++.ES ++env=Environment() ++env['PDB'] = 'MyApp.pdb' ++env.Program('MyApp', ['Foo.cpp', 'Bar.cpp']) ++.EE ++ ++For more information see the document for the PDB construction variable. ++ ++.SH ENVIRONMENT ++ ++.IP SCONS_LIB_DIR ++Specifies the directory that contains the SCons Python module directory ++(e.g. /home/aroach/scons-src-0.01/src/engine). ++ ++.IP SCONSFLAGS ++A string of options that will be used by scons in addition to those passed ++on the command line. ++ ++.SH "SEE ALSO" ++.B scons ++User Manual, ++.B scons ++Design Document, ++.B scons ++source code. ++ ++.SH AUTHORS ++Steven Knight <knight@baldmt.com> ++.br ++Anthony Roach <aroach@electriceyeball.com> ++ +Index: scons/sconsign.1 +=================================================================== +--- /dev/null 1970-01-01 00:00:00.000000000 +0000 ++++ scons/sconsign.1 2014-04-26 12:12:51.305721997 +0200 +@@ -0,0 +1,208 @@ ++.\" Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013 The SCons Foundation ++.\" ++.\" Permission is hereby granted, free of charge, to any person obtaining ++.\" a copy of this software and associated documentation files (the ++.\" "Software"), to deal in the Software without restriction, including ++.\" without limitation the rights to use, copy, modify, merge, publish, ++.\" distribute, sublicense, and/or sell copies of the Software, and to ++.\" permit persons to whom the Software is furnished to do so, subject to ++.\" the following conditions: ++.\" ++.\" The above copyright notice and this permission notice shall be included ++.\" in all copies or substantial portions of the Software. ++.\" ++.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY ++.\" KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE ++.\" WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND ++.\" NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE ++.\" LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION ++.\" OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION ++.\" WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. ++.\" ++.\" doc/man/sconsign.1 2013/03/03 09:48:35 garyo ++.\" ++.\" ES - Example Start - indents and turns off line fill ++.de ES ++.RS ++.nf ++.. ++.\" EE - Example End - ends indent and turns line fill back on ++.de EE ++.RE ++.fi ++.. ++.TH SCONSIGN 1 "March 2013" ++.SH NAME ++sconsign \- print SCons .sconsign file information ++.SH SYNOPSIS ++.B sconsign ++[ ++.IR options ... ++] ++.IR file ++[ ... ] ++.SH DESCRIPTION ++ ++The ++.B sconsign ++command ++displays the contents of one or more ++.B .sconsign ++files specified by the user. ++ ++By default, ++.B sconsign ++dumps the entire contents of the ++specified file(s). ++Each entry is printed in the following format: ++ ++ file: signature timestamp length ++ implicit_dependency_1: signature timestamp length ++ implicit_dependency_2: signature timestamp length ++ action_signature [action string] ++ ++.B None ++is printed ++in place of any missing timestamp, bsig, or csig ++values for ++any entry ++or any of its dependencies. ++If the entry has no implicit dependencies, ++or no build action, ++the lines are simply omitted. ++ ++By default, ++.B sconsign ++assumes that any ++.I file ++arguments that end with a ++.B .dbm ++suffix contains ++signature entries for ++more than one directory ++(that is, ++was specified by the ++.B SConsignFile () ++function). ++Any ++.I file ++argument that does not end in ++.B .dbm ++is assumed to be a traditional ++.B .sconsign ++file containing the signature entries ++for a single directory. ++An explicit format ++may be specified using the ++.B -f ++or ++.B --file= ++options. ++ ++.SH OPTIONS ++ ++Various options control what information is printed ++and the format: ++ ++.TP ++-a, --act, --action ++Prints the build action information ++for all entries or the specified entries. ++ ++.TP ++-c, --csig ++Prints the content signature (csig) information ++for all entries or the specified entries. ++ ++.TP ++-d DIRECTORY, --dir=DIRECTORY ++When the signatures are being ++read from a ++.B .dbm ++file, or the ++.B -f dbm ++or ++.B --format=dbm ++options are used, ++prints information about ++only the signatures ++for entries in the specified ++.IR DIRECTORY . ++ ++.TP ++-e ENTRY, --entry=ENTRY ++Prints information about only the specified ++.IR ENTRY . ++Multiple -e options may be used, ++in which case information about each ++.I ENTRY ++is printed in the order in which the ++options are specified on the command line. ++ ++.TP ++-f FORMAT, --format=FORMAT ++The file(s) to be printed ++are in the specified ++.IR FORMAT . ++Legal values are ++.B dbm ++(the DBM format used ++when the ++.BR SConsignFile () ++function is used) ++or ++.B sconsign ++(the default format ++used for an individual ++.B .sconsign ++file in each directory). ++ ++.TP ++-h, --help ++Prints a help message and exits. ++ ++.TP ++-i, --implicit ++Prints the list of cached implicit dependencies ++for all entries or the the specified entries. ++ ++.TP ++--raw ++Prints a pretty-printed representation ++of the raw Python dictionary that holds ++build information about individual entry ++(both the entry itself or its implicit dependencies). ++An entry's build action is still printed in its usual format. ++ ++.TP ++-r, --readable ++Prints timestamps in a human-readable string, ++enclosed in single quotes. ++ ++.TP ++-t, --timestamp ++Prints the timestamp information ++for all entries or the specified entries. ++ ++.TP ++-v, --verbose ++Prints labels identifying each field being printed. ++ ++.SH ENVIRONMENT ++ ++.IP SCONS_LIB_DIR ++Specifies the directory that contains the SCons Python module directory ++(e.g. /home/aroach/scons-src-0.01/src/engine). ++on the command line. ++ ++.SH "SEE ALSO" ++.BR scons , ++.B scons ++User Manual, ++.B scons ++Design Document, ++.B scons ++source code. ++ ++.SH AUTHORS ++Steven Knight <knight at baldmt dot com> |