diff options
Diffstat (limited to 'debian/patches/manpages.patch')
| -rw-r--r-- | debian/patches/manpages.patch | 17138 |
1 files changed, 0 insertions, 17138 deletions
diff --git a/debian/patches/manpages.patch b/debian/patches/manpages.patch deleted file mode 100644 index 38506ce..0000000 --- a/debian/patches/manpages.patch +++ /dev/null @@ -1,17138 +0,0 @@ -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:21:47.051232252 +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 committed 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 conjunction 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 conjunction 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:21:47.059232201 +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 -+conjunction 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 overridden 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 easily -+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). Additionally, 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 explicitly 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:20:51.007589417 +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> |