diff options
Diffstat (limited to 'scons.1')
| -rw-r--r-- | scons.1 | 15895 |
1 files changed, 0 insertions, 15895 deletions
@@ -1,15895 +0,0 @@ -.\" Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013 The SCons Foundation -.\" -.\" Permission is hereby granted, free of charge, to any person obtaining -.\" a copy of this software and associated documentation files (the -.\" "Software"), to deal in the Software without restriction, including -.\" without limitation the rights to use, copy, modify, merge, publish, -.\" distribute, sublicense, and/or sell copies of the Software, and to -.\" permit persons to whom the Software is furnished to do so, subject to -.\" the following conditions: -.\" -.\" The above copyright notice and this permission notice shall be included -.\" in all copies or substantial portions of the Software. -.\" -.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY -.\" KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE -.\" WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND -.\" NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE -.\" LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION -.\" OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION -.\" WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. -.\" -.\" doc/man/scons.1 2013/03/03 09:48:35 garyo -.\" -.TH SCONS 1 "March 2013" -.\" ES - Example Start - indents and turns off line fill -.rm ES -.de ES -.RS -.nf -.. -.\" EE - Example End - ends indent and turns line fill back on -.rm EE -.de EE -.fi -.RE -.. -.SH NAME -scons \- a software construction tool -.SH SYNOPSIS -.B scons -[ -.IR options ... -] -[ -.IR name = val ... -] -[ -.IR targets ... -] -.SH DESCRIPTION - -The -.B scons -utility builds software (or other files) by determining which -component pieces must be rebuilt and executing the necessary commands to -rebuild them. - -By default, -.B scons -searches for a file named -.IR SConstruct , -.IR Sconstruct , -or -.I sconstruct -(in that order) in the current directory and reads its -configuration from the first file found. -An alternate file name may be -specified via the -.B -f -option. - -The -.I SConstruct -file can specify subsidiary -configuration files using the -.BR SConscript () -function. -By convention, -these subsidiary files are named -.IR SConscript , -although any name may be used. -(Because of this naming convention, -the term "SConscript files" -is sometimes used to refer -generically to all -.B scons -configuration files, -regardless of actual file name.) - -The configuration files -specify the target files to be built, and -(optionally) the rules to build those targets. Reasonable default -rules exist for building common software components (executable -programs, object files, libraries), so that for most software -projects, only the target and input files need be specified. - -Before reading the -.I SConstruct -file, -.B scons -looks for a directory named -.I site_scons -in various system directories (see below) and the directory containing the -.I SConstruct -file; for each of those dirs which exists, -.I site_scons -is prepended to sys.path, -the file -.IR site_scons/site_init.py , -is evaluated if it exists, -and the directory -.I site_scons/site_tools -is prepended to the default toolpath if it exists. -See the -.I --no-site-dir -and -.I --site-dir -options for more details. - -.B scons -reads and executes the SConscript files as Python scripts, -so you may use normal Python scripting capabilities -(such as flow control, data manipulation, and imported Python libraries) -to handle complicated build situations. -.BR scons , -however, reads and executes all of the SConscript files -.I before -it begins building any targets. -To make this obvious, -.B scons -prints the following messages about what it is doing: - -.ES -$ scons foo.out -scons: Reading SConscript files ... -scons: done reading SConscript files. -scons: Building targets ... -cp foo.in foo.out -scons: done building targets. -$ -.EE - -The status messages -(everything except the line that reads "cp foo.in foo.out") -may be suppressed using the -.B -Q -option. - -.B scons -does not automatically propagate -the external environment used to execute -.B scons -to the commands used to build target files. -This is so that builds will be guaranteed -repeatable regardless of the environment -variables set at the time -.B scons -is invoked. -This also means that if the compiler or other commands -that you want to use to build your target files -are not in standard system locations, -.B scons -will not find them unless -you explicitly set the PATH -to include those locations. -Whenever you create an -.B scons -construction environment, -you can propagate the value of PATH -from your external environment as follows: - -.ES -import os -env = Environment(ENV = {'PATH' : os.environ['PATH']}) -.EE - -Similarly, if the commands use external environment variables -like $PATH, $HOME, $JAVA_HOME, $LANG, $SHELL, $TERM, etc., -these variables can also be explicitly propagated: - -.ES -import os -env = Environment(ENV = {'PATH' : os.environ['PATH'], - 'HOME' : os.environ['HOME']}) -.EE - -Or you may explicitly propagate the invoking user's -complete external environment: - -.ES -import os -env = Environment(ENV = os.environ) -.EE - -This comes at the expense of making your build -dependent on the user's environment being set correctly, -but it may be more convenient for many configurations. - -.B scons -can scan known input files automatically for dependency -information (for example, #include statements -in C or C++ files) and will rebuild dependent files appropriately -whenever any "included" input file changes. -.B scons -supports the -ability to define new scanners for unknown input file types. - -.B scons -knows how to fetch files automatically from -SCCS or RCS subdirectories -using SCCS, RCS or BitKeeper. - -.B scons -is normally executed in a top-level directory containing a -.I SConstruct -file, optionally specifying -as command-line arguments -the target file or files to be built. - -By default, the command - -.ES -scons -.EE - -will build all target files in or below the current directory. -Explicit default targets -(to be built when no targets are specified on the command line) -may be defined the SConscript file(s) -using the -.B Default() -function, described below. - -Even when -.B Default() -targets are specified in the SConscript file(s), -all target files in or below the current directory -may be built by explicitly specifying -the current directory (.) -as a command-line target: - -.ES -scons . -.EE - -Building all target files, -including any files outside of the current directory, -may be specified by supplying a command-line target -of the root directory (on POSIX systems): - -.ES -scons / -.EE - -or the path name(s) of the volume(s) in which all the targets -should be built (on Windows systems): - -.ES -scons C:\\ D:\\ -.EE - -To build only specific targets, -supply them as command-line arguments: - -.ES -scons foo bar -.EE - -in which case only the specified targets will be built -(along with any derived files on which they depend). - -Specifying "cleanup" targets in SConscript files is not usually necessary. -The -.B -c -flag removes all files -necessary to build the specified target: - -.ES -scons -c . -.EE - -to remove all target files, or: - -.ES -scons -c build export -.EE - -to remove target files under build and export. -Additional files or directories to remove can be specified using the -.BR Clean() -function. -Conversely, targets that would normally be removed by the -.B -c -invocation -can be prevented from being removed by using the -.BR NoClean () -function. - -A subset of a hierarchical tree may be built by -remaining at the top-level directory (where the -.I SConstruct -file lives) and specifying the subdirectory as the target to be -built: - -.ES -scons src/subdir -.EE - -or by changing directory and invoking scons with the -.B -u -option, which traverses up the directory -hierarchy until it finds the -.I SConstruct -file, and then builds -targets relatively to the current subdirectory: - -.ES -cd src/subdir -scons -u . -.EE - -.B scons -supports building multiple targets in parallel via a -.B -j -option that takes, as its argument, the number -of simultaneous tasks that may be spawned: - -.ES -scons -j 4 -.EE - -builds four targets in parallel, for example. - -.B scons -can maintain a cache of target (derived) files that can -be shared between multiple builds. When caching is enabled in a -SConscript file, any target files built by -.B scons -will be copied -to the cache. If an up-to-date target file is found in the cache, it -will be retrieved from the cache instead of being rebuilt locally. -Caching behavior may be disabled and controlled in other ways by the -.BR --cache-force , -.BR --cache-disable , -and -.B --cache-show -command-line options. The -.B --random -option is useful to prevent multiple builds -from trying to update the cache simultaneously. - -Values of variables to be passed to the SConscript file(s) -may be specified on the command line: - -.ES -scons debug=1 . -.EE - -These variables are available in SConscript files -through the ARGUMENTS dictionary, -and can be used in the SConscript file(s) to modify -the build in any way: - -.ES -if ARGUMENTS.get('debug', 0): - env = Environment(CCFLAGS = '-g') -else: - env = Environment() -.EE - -The command-line variable arguments are also available -in the ARGLIST list, -indexed by their order on the command line. -This allows you to process them in order rather than by name, -if necessary. -ARGLIST[0] returns a tuple -containing (argname, argvalue). -A Python exception is thrown if you -try to access a list member that -does not exist. - -.B scons -requires Python version 2.4 or later. -There should be no other dependencies or requirements to run -.B scons. - -.\" The following paragraph reflects the default tool search orders -.\" currently in SCons/Tool/__init__.py. If any of those search orders -.\" change, this documentation should change, too. -By default, -.B scons -knows how to search for available programming tools -on various systems. -On Windows systems, -.B scons -searches in order for the -Microsoft Visual C++ tools, -the MinGW tool chain, -the Intel compiler tools, -and the PharLap ETS compiler. -On OS/2 systems, -.B scons -searches in order for the -OS/2 compiler, -the GCC tool chain, -and the Microsoft Visual C++ tools, -On SGI IRIX, IBM AIX, Hewlett Packard HP-UX, and Sun Solaris systems, -.B scons -searches for the native compiler tools -(MIPSpro, Visual Age, aCC, and Forte tools respectively) -and the GCC tool chain. -On all other platforms, -including POSIX (Linux and UNIX) platforms, -.B scons -searches in order -for the GCC tool chain, -the Microsoft Visual C++ tools, -and the Intel compiler tools. -You may, of course, override these default values -by appropriate configuration of -Environment construction variables. - -.SH OPTIONS -In general, -.B scons -supports the same command-line options as GNU -.BR make , -and many of those supported by -.BR cons . - -.TP --b -Ignored for compatibility with non-GNU versions of -.BR make. - -.TP --c, --clean, --remove -Clean up by removing all target files for which a construction -command is specified. -Also remove any files or directories associated to the construction command -using the -.BR Clean () -function. -Will not remove any targets specified by the -.BR NoClean () -function. - -.TP -.RI --cache-debug= file -Print debug information about the -.BR CacheDir () -derived-file caching -to the specified -.IR file . -If -.I file -is -.B \- -(a hyphen), -the debug information are printed to the standard output. -The printed messages describe what signature file names are -being looked for in, retrieved from, or written to the -.BR CacheDir () -directory tree. - -.TP ---cache-disable, --no-cache -Disable the derived-file caching specified by -.BR CacheDir (). -.B scons -will neither retrieve files from the cache -nor copy files to the cache. - -.TP ---cache-force, --cache-populate -When using -.BR CacheDir (), -populate a cache by copying any already-existing, up-to-date -derived files to the cache, -in addition to files built by this invocation. -This is useful to populate a new cache with -all the current derived files, -or to add to the cache any derived files -recently built with caching disabled via the -.B --cache-disable -option. - -.TP ---cache-show -When using -.BR CacheDir () -and retrieving a derived file from the cache, -show the command -that would have been executed to build the file, -instead of the usual report, -"Retrieved `file' from cache." -This will produce consistent output for build logs, -regardless of whether a target -file was rebuilt or retrieved from the cache. - -.TP -.RI --config= mode -This specifies how the -.B Configure -call should use or generate the -results of configuration tests. -The option should be specified from -among the following choices: - -.TP ---config=auto -scons will use its normal dependency mechanisms -to decide if a test must be rebuilt or not. -This saves time by not running the same configuration tests -every time you invoke scons, -but will overlook changes in system header files -or external commands (such as compilers) -if you don't specify those dependecies explicitly. -This is the default behavior. - -.TP ---config=force -If this option is specified, -all configuration tests will be re-run -regardless of whether the -cached results are out of date. -This can be used to explicitly -force the configuration tests to be updated -in response to an otherwise unconfigured change -in a system header file or compiler. - -.TP ---config=cache -If this option is specified, -no configuration tests will be rerun -and all results will be taken from cache. -Note that scons will still consider it an error -if --config=cache is specified -and a necessary test does not -yet have any results in the cache. - -.TP -.RI "-C" " directory" ", --directory=" directory -Change to the specified -.I directory -before searching for the -.IR SConstruct , -.IR Sconstruct , -or -.I sconstruct -file, or doing anything -else. Multiple -.B -C -options are interpreted -relative to the previous one, and the right-most -.B -C -option wins. (This option is nearly -equivalent to -.BR "-f directory/SConstruct" , -except that it will search for -.IR SConstruct , -.IR Sconstruct , -or -.I sconstruct -in the specified directory.) - -.\" .TP -.\" -d -.\" Display dependencies while building target files. Useful for -.\" figuring out why a specific file is being rebuilt, as well as -.\" general debugging of the build process. - -.TP --D -Works exactly the same way as the -.B -u -option except for the way default targets are handled. -When this option is used and no targets are specified on the command line, -all default targets are built, whether or not they are below the current -directory. - -.TP -.RI --debug= type -Debug the build process. -.I type -specifies what type of debugging: - -.TP ---debug=count -Print how many objects are created -of the various classes used internally by SCons -before and after reading the SConscript files -and before and after building targets. -This is not supported when SCons is executed with the Python -.B -O -(optimized) option -or when the SCons modules -have been compiled with optimization -(that is, when executing from -.B *.pyo -files). - -.TP ---debug=duplicate -Print a line for each unlink/relink (or copy) of a variant file from -its source file. Includes debugging info for unlinking stale variant -files, as well as unlinking old targets before building them. - -.TP ---debug=dtree -A synonym for the newer -.B --tree=derived -option. -This will be deprecated in some future release -and ultimately removed. - -.TP ---debug=explain -Print an explanation of precisely why -.B scons -is deciding to (re-)build any targets. -(Note: this does not print anything -for targets that are -.I not -rebuilt.) - -.TP ---debug=findlibs -Instruct the scanner that searches for libraries -to print a message about each potential library -name it is searching for, -and about the actual libraries it finds. - -.TP ---debug=includes -Print the include tree after each top-level target is built. -This is generally used to find out what files are included by the sources -of a given derived file: - -.ES -$ scons --debug=includes foo.o -.EE - -.TP ---debug=memoizer -Prints a summary of hits and misses using the Memoizer, -an internal subsystem that counts -how often SCons uses cached values in memory -instead of recomputing them each time they're needed. - -.TP ---debug=memory -Prints how much memory SCons uses -before and after reading the SConscript files -and before and after building targets. - -.TP ---debug=nomemoizer -A deprecated option preserved for backwards compatibility. - -.TP ---debug=objects -Prints a list of the various objects -of the various classes used internally by SCons. - -.TP ---debug=pdb -Re-run SCons under the control of the -.RI pdb -Python debugger. - -.TP ---debug=prepare -Print a line each time any target (internal or external) -is prepared for building. -.B scons -prints this for each target it considers, even if that -target is up to date (see also --debug=explain). -This can help debug problems with targets that aren't being -built; it shows whether -.B scons -is at least considering them or not. - -.TP ---debug=presub -Print the raw command line used to build each target -before the construction environment variables are substituted. -Also shows which targets are being built by this command. -Output looks something like this: -.ES -$ scons --debug=presub -Building myprog.o with action(s): - $SHCC $SHCFLAGS $SHCCFLAGS $CPPFLAGS $_CPPINCFLAGS -c -o $TARGET $SOURCES -\&... -.EE - -.TP ---debug=stacktrace -Prints an internal Python stack trace -when encountering an otherwise unexplained error. - -.TP ---debug=stree -A synonym for the newer -.B --tree=all,status -option. -This will be deprecated in some future release -and ultimately removed. - -.TP ---debug=time -Prints various time profiling information: -the time spent executing each individual build command; -the total build time (time SCons ran from beginning to end); -the total time spent reading and executing SConscript files; -the total time spent SCons itself spend running -(that is, not counting reading and executing SConscript files); -and both the total time spent executing all build commands -and the elapsed wall-clock time spent executing those build commands. -(When -.B scons -is executed without the -.B -j -option, -the elapsed wall-clock time will typically -be slightly longer than the total time spent -executing all the build commands, -due to the SCons processing that takes place -in between executing each command. -When -.B scons -is executed -.I with -the -.B -j -option, -and your build configuration allows good parallelization, -the elapsed wall-clock time should -be significantly smaller than the -total time spent executing all the build commands, -since multiple build commands and -intervening SCons processing -should take place in parallel.) - -.TP ---debug=tree -A synonym for the newer -.B --tree=all -option. -This will be deprecated in some future release -and ultimately removed. - -.TP -.RI --diskcheck= types -Enable specific checks for -whether or not there is a file on disk -where the SCons configuration expects a directory -(or vice versa), -and whether or not RCS or SCCS sources exist -when searching for source and include files. -The -.I types -argument can be set to: -.BR all , -to enable all checks explicitly -(the default behavior); -.BR none , -to disable all such checks; -.BR match , -to check that files and directories on disk -match SCons' expected configuration; -.BR rcs , -to check for the existence of an RCS source -for any missing source or include files; -.BR sccs , -to check for the existence of an SCCS source -for any missing source or include files. -Multiple checks can be specified separated by commas; -for example, -.B --diskcheck=sccs,rcs -would still check for SCCS and RCS sources, -but disable the check for on-disk matches of files and directories. -Disabling some or all of these checks -can provide a performance boost for large configurations, -or when the configuration will check for files and/or directories -across networked or shared file systems, -at the slight increased risk of an incorrect build -or of not handling errors gracefully -(if include files really should be -found in SCCS or RCS, for example, -or if a file really does exist -where the SCons configuration expects a directory). - -.TP -.RI --duplicate= ORDER -There are three ways to duplicate files in a build tree: hard links, -soft (symbolic) links and copies. The default behaviour of SCons is to -prefer hard links to soft links to copies. You can specify different -behaviours with this option. -.IR ORDER -must be one of -.IR hard-soft-copy -(the default), -.IR soft-hard-copy , -.IR hard-copy , -.IR soft-copy -or -.IR copy . -SCons will attempt to duplicate files using -the mechanisms in the specified order. - -.\" .TP -.\" -e, --environment-overrides -.\" Variables from the execution environment override construction -.\" variables from the SConscript files. - -.TP -.RI -f " file" ", --file=" file ", --makefile=" file ", --sconstruct=" file -Use -.I file -as the initial SConscript file. -Multiple -.B -f -options may be specified, -in which case -.B scons -will read all of the specified files. - -.TP --h, --help -Print a local help message for this build, if one is defined in -the SConscript file(s), plus a line that describes the -.B -H -option for command-line option help. If no local help message -is defined, prints the standard help message about command-line -options. Exits after displaying the appropriate message. - -.TP --H, --help-options -Print the standard help message about command-line options and -exit. - -.TP --i, --ignore-errors -Ignore all errors from commands executed to rebuild files. - -.TP -.RI -I " directory" ", --include-dir=" directory -Specifies a -.I directory -to search for -imported Python modules. If several -.B -I -options -are used, the directories are searched in the order specified. - -.TP ---implicit-cache -Cache implicit dependencies. -This causes -.B scons -to use the implicit (scanned) dependencies -from the last time it was run -instead of scanning the files for implicit dependencies. -This can significantly speed up SCons, -but with the following limitations: -.IP -.B scons -will not detect changes to implicit dependency search paths -(e.g. -.BR CPPPATH ", " LIBPATH ) -that would ordinarily -cause different versions of same-named files to be used. -.IP -.B scons -will miss changes in the implicit dependencies -in cases where a new implicit -dependency is added earlier in the implicit dependency search path -(e.g. -.BR CPPPATH ", " LIBPATH ) -than a current implicit dependency with the same name. - -.TP ---implicit-deps-changed -Forces SCons to ignore the cached implicit dependencies. This causes the -implicit dependencies to be rescanned and recached. This implies -.BR --implicit-cache . - -.TP ---implicit-deps-unchanged -Force SCons to ignore changes in the implicit dependencies. -This causes cached implicit dependencies to always be used. -This implies -.BR --implicit-cache . - -.TP ---interactive -Starts SCons in interactive mode. -The SConscript files are read once and a -.B "scons>>>" -prompt is printed. -Targets may now be rebuilt by typing commands at interactive prompt -without having to re-read the SConscript files -and re-initialize the dependency graph from scratch. - -SCons interactive mode supports the following commands: - -.RS 10 -.TP 6 -.BI build "[OPTIONS] [TARGETS] ..." -Builds the specified -.I TARGETS -(and their dependencies) -with the specified -SCons command-line -.IR OPTIONS . -.B b -and -.B scons -are synonyms. - -The following SCons command-line options affect the -.B build -command: - -.ES ---cache-debug=FILE ---cache-disable, --no-cache ---cache-force, --cache-populate ---cache-show ---debug=TYPE --i, --ignore-errors --j N, --jobs=N --k, --keep-going --n, --no-exec, --just-print, --dry-run, --recon --Q --s, --silent, --quiet ---taskmastertrace=FILE ---tree=OPTIONS -.EE - -.IP "" 6 -Any other SCons command-line options that are specified -do not cause errors -but have no effect on the -.B build -command -(mainly because they affect how the SConscript files are read, -which only happens once at the beginning of interactive mode). - -.TP 6 -.BI clean "[OPTIONS] [TARGETS] ..." -Cleans the specified -.I TARGETS -(and their dependencies) -with the specified options. -.B c -is a synonym. -This command is itself a synonym for -.B "build --clean" - -.TP 6 -.BI exit -Exits SCons interactive mode. -You can also exit by terminating input -(CTRL+D on UNIX or Linux systems, -CTRL+Z on Windows systems). - -.TP 6 -.BI help "[COMMAND]" -Provides a help message about -the commands available in SCons interactive mode. -If -.I COMMAND -is specified, -.B h -and -.B ? -are synonyms. - -.TP 6 -.BI shell "[COMMANDLINE]" -Executes the specified -.I COMMANDLINE -in a subshell. -If no -.I COMMANDLINE -is specified, -executes the interactive command interpreter -specified in the -.B SHELL -environment variable -(on UNIX and Linux systems) -or the -.B COMSPEC -environment variable -(on Windows systems). -.B sh -and -.B ! -are synonyms. - -.TP 6 -.B version -Prints SCons version information. -.RE - -.IP -An empty line repeats the last typed command. -Command-line editing can be used if the -.B readline -module is available. - -.ES -$ scons --interactive -scons: Reading SConscript files ... -scons: done reading SConscript files. -scons>>> build -n prog -scons>>> exit -.EE - -.TP -.RI -j " N" ", --jobs=" N -Specifies the number of jobs (commands) to run simultaneously. -If there is more than one -.B -j -option, the last one is effective. -.\" ??? If the -.\" .B -j -.\" option -.\" is specified without an argument, -.\" .B scons -.\" will not limit the number of -.\" simultaneous jobs. - -.TP --k, --keep-going -Continue as much as possible after an error. The target that -failed and those that depend on it will not be remade, but other -targets specified on the command line will still be processed. - -.\" .TP -.\" .RI -l " N" ", --load-average=" N ", --max-load=" N -.\" No new jobs (commands) will be started if -.\" there are other jobs running and the system load -.\" average is at least -.\" .I N -.\" (a floating-point number). - -.\" -.\" .TP -.\" --list-derived -.\" List derived files (targets, dependencies) that would be built, -.\" but do not build them. -.\" [XXX This can probably go away with the right -.\" combination of other options. Revisit this issue.] -.\" -.\" .TP -.\" --list-actions -.\" List derived files that would be built, with the actions -.\" (commands) that build them. Does not build the files. -.\" [XXX This can probably go away with the right -.\" combination of other options. Revisit this issue.] -.\" -.\" .TP -.\" --list-where -.\" List derived files that would be built, plus where the file is -.\" defined (file name and line number). Does not build the files. -.\" [XXX This can probably go away with the right -.\" combination of other options. Revisit this issue.] - -.TP --m -Ignored for compatibility with non-GNU versions of -.BR make . - -.TP -.RI --max-drift= SECONDS -Set the maximum expected drift in the modification time of files to -.IR SECONDS . -This value determines how long a file must be unmodified -before its cached content signature -will be used instead of -calculating a new content signature (MD5 checksum) -of the file's contents. -The default value is 2 days, which means a file must have a -modification time of at least two days ago in order to have its -cached content signature used. -A negative value means to never cache the content -signature and to ignore the cached value if there already is one. A value -of 0 means to always use the cached signature, -no matter how old the file is. - -.TP -.RI --md5-chunksize= KILOBYTES -Set the block size used to compute MD5 signatures to -.IR KILOBYTES . -This value determines the size of the chunks which are read in at once when -computing MD5 signatures. Files below that size are fully stored in memory -before performing the signature computation while bigger files are read in -block-by-block. A huge block-size leads to high memory consumption while a very -small block-size slows down the build considerably. - -The default value is to use a chunk size of 64 kilobytes, which should -be appropriate for most uses. - -.TP --n, --just-print, --dry-run, --recon -No execute. Print the commands that would be executed to build -any out-of-date target files, but do not execute the commands. - -.TP -.RI --no-site-dir -Prevents the automatic addition of the standard -.I site_scons -dirs to -.IR sys.path . -Also prevents loading the -.I site_scons/site_init.py -modules if they exist, and prevents adding their -.I site_scons/site_tools -dirs to the toolpath. - -.\" .TP -.\" .RI -o " file" ", --old-file=" file ", --assume-old=" file -.\" Do not rebuild -.\" .IR file , -.\" and do -.\" not rebuild anything due to changes in the contents of -.\" .IR file . -.\" .TP -.\" .RI --override " file" -.\" Read values to override specific build environment variables -.\" from the specified -.\" .IR file . -.\" .TP -.\" -p -.\" Print the data base (construction environments, -.\" Builder and Scanner objects) that are defined -.\" after reading the SConscript files. -.\" After printing, a normal build is performed -.\" as usual, as specified by other command-line options. -.\" This also prints version information -.\" printed by the -.\" .B -v -.\" option. -.\" -.\" To print the database without performing a build do: -.\" -.\" .ES -.\" scons -p -q -.\" .EE - -.TP -.RI --profile= file -Run SCons under the Python profiler -and save the results in the specified -.IR file . -The results may be analyzed using the Python -pstats module. - -.TP --q, --question -Do not run any commands, or print anything. Just return an exit -status that is zero if the specified targets are already up to -date, non-zero otherwise. -.TP --Q -Quiets SCons status messages about -reading SConscript files, -building targets -and entering directories. -Commands that are executed -to rebuild target files are still printed. - -.\" .TP -.\" -r, -R, --no-builtin-rules, --no-builtin-variables -.\" Clear the default construction variables. Construction -.\" environments that are created will be completely empty. - -.TP ---random -Build dependencies in a random order. This is useful when -building multiple trees simultaneously with caching enabled, -to prevent multiple builds from simultaneously trying to build -or retrieve the same target files. - -.TP --s, --silent, --quiet -Silent. Do not print commands that are executed to rebuild -target files. -Also suppresses SCons status messages. - -.TP --S, --no-keep-going, --stop -Ignored for compatibility with GNU -.BR make . - -.TP -.RI --site-dir= dir -Uses the named dir as the site dir rather than the default -.I site_scons -dirs. This dir will get prepended to -.IR sys.path , -the module -.IR dir /site_init.py -will get loaded if it exists, and -.IR dir /site_tools -will get added to the default toolpath. - -The default set of -.I site_scons -dirs used when -.I --site-dir -is not specified depends on the system platform, as follows. Note -that the directories are examined in the order given, from most -generic to most specific, so the last-executed site_init.py file is -the most specific one (which gives it the chance to override -everything else), and the dirs are prepended to the paths, again so -the last dir examined comes first in the resulting path. - -.IP "Windows:" -.nf - %ALLUSERSPROFILE/Application Data/scons/site_scons - %USERPROFILE%/Local Settings/Application Data/scons/site_scons - %APPDATA%/scons/site_scons - %HOME%/.scons/site_scons - ./site_scons -.fi -.IP "Mac OS X:" -.nf - /Library/Application Support/SCons/site_scons - /opt/local/share/scons/site_scons (for MacPorts) - /sw/share/scons/site_scons (for Fink) - $HOME/Library/Application Support/SCons/site_scons - $HOME/.scons/site_scons - ./site_scons -.fi -.IP "Solaris:" -.nf - /opt/sfw/scons/site_scons - /usr/share/scons/site_scons - $HOME/.scons/site_scons - ./site_scons -.fi -.IP "Linux, HPUX, and other Posix-like systems:" -.nf - /usr/share/scons/site_scons - $HOME/.scons/site_scons - ./site_scons -.fi - -.TP -.RI --stack-size= KILOBYTES -Set the size stack used to run threads to -.IR KILOBYTES . -This value determines the stack size of the threads used to run jobs. -These are the threads that execute the actions of the builders for the -nodes that are out-of-date. -Note that this option has no effect unless the -.B num_jobs -option, which corresponds to -j and --jobs, is larger than one. Using -a stack size that is too small may cause stack overflow errors. This -usually shows up as segmentation faults that cause scons to abort -before building anything. Using a stack size that is too large will -cause scons to use more memory than required and may slow down the entire -build process. - -The default value is to use a stack size of 256 kilobytes, which should -be appropriate for most uses. You should not need to increase this value -unless you encounter stack overflow errors. - -.TP --t, --touch -Ignored for compatibility with GNU -.BR make . -(Touching a file to make it -appear up-to-date is unnecessary when using -.BR scons .) - -.TP -.RI --taskmastertrace= file -Prints trace information to the specified -.I file -about how the internal Taskmaster object -evaluates and controls the order in which Nodes are built. -A file name of -.B - -may be used to specify the standard output. - -.TP -.RI -tree= options -Prints a tree of the dependencies -after each top-level target is built. -This prints out some or all of the tree, -in various formats, -depending on the -.I options -specified: - -.TP ---tree=all -Print the entire dependency tree -after each top-level target is built. -This prints out the complete dependency tree, -including implicit dependencies and ignored dependencies. - -.TP ---tree=derived -Restricts the tree output to only derived (target) files, -not source files. - -.TP ---tree=status -Prints status information for each displayed node. - -.TP ---tree=prune -Prunes the tree to avoid repeating dependency information -for nodes that have already been displayed. -Any node that has already been displayed -will have its name printed in -.BR "[square brackets]" , -as an indication that the dependencies -for that node can be found by searching -for the relevant output higher up in the tree. - -.IP -Multiple options may be specified, -separated by commas: - -.ES -# Prints only derived files, with status information: -scons --tree=derived,status - -# Prints all dependencies of target, with status information -# and pruning dependencies of already-visited Nodes: -scons --tree=all,prune,status target -.EE - -.TP --u, --up, --search-up -Walks up the directory structure until an -.I SConstruct , -.I Sconstruct -or -.I sconstruct -file is found, and uses that -as the top of the directory tree. -If no targets are specified on the command line, -only targets at or below the -current directory will be built. - -.TP --U -Works exactly the same way as the -.B -u -option except for the way default targets are handled. -When this option is used and no targets are specified on the command line, -all default targets that are defined in the SConscript(s) in the current -directory are built, regardless of what directory the resultant targets end -up in. - -.TP --v, --version -Print the -.B scons -version, copyright information, -list of authors, and any other relevant information. -Then exit. - -.TP --w, --print-directory -Print a message containing the working directory before and -after other processing. - -.TP ---no-print-directory -Turn off -w, even if it was turned on implicitly. - -.TP -.RI --warn= type ", --warn=no-" type -Enable or disable warnings. -.I type -specifies the type of warnings to be enabled or disabled: - -.TP ---warn=all, --warn=no-all -Enables or disables all warnings. - -.TP ---warn=cache-write-error, --warn=no-cache-write-error -Enables or disables warnings about errors trying to -write a copy of a built file to a specified -.BR CacheDir (). -These warnings are disabled by default. - -.TP ---warn=corrupt-sconsign, --warn=no-corrupt-sconsign -Enables or disables warnings about unfamiliar signature data in -.B .sconsign -files. -These warnings are enabled by default. - -.TP ---warn=dependency, --warn=no-dependency -Enables or disables warnings about dependencies. -These warnings are disabled by default. - -.TP ---warn=deprecated, --warn=no-deprecated -Enables or disables all warnings about use of -currently deprecated features. -These warnings are enabled by default. -Note that the -.B --warn=no-deprecated -option does not disable warnings about absolutely all deprecated features. -Warnings for some deprecated features that have already been through -several releases with deprecation warnings -may be mandatory for a release or two -before they are officially no longer supported by SCons. -Warnings for some specific deprecated features -may be enabled or disabled individually; -see below. - -.RS -.TP ---warn=deprecated-copy, --warn=no-deprecated-copy -Enables or disables warnings about use of the deprecated -.B env.Copy() -method. - -.TP ---warn=deprecated-source-signatures, --warn=no-deprecated-source-signatures -Enables or disables warnings about use of the deprecated -.B SourceSignatures() -function or -.B env.SourceSignatures() -method. - -.TP ---warn=deprecated-target-signatures, --warn=no-deprecated-target-signatures -Enables or disables warnings about use of the deprecated -.B TargetSignatures() -function or -.B env.TargetSignatures() -method. -.RE - -.TP ---warn=duplicate-environment, --warn=no-duplicate-environment -Enables or disables warnings about attempts to specify a build -of a target with two different construction environments -that use the same action. -These warnings are enabled by default. - -.TP ---warn=fortran-cxx-mix, --warn=no-fortran-cxx-mix -Enables or disables the specific warning about linking -Fortran and C++ object files in a single executable, -which can yield unpredictable behavior with some compilers. - -.TP ---warn=future-deprecated, --warn=no-future-deprecated -Enables or disables warnings about features -that will be deprecated in the future. -These warnings are disabled by default. -Enabling this warning is especially -recommended for projects that redistribute -SCons configurations for other users to build, -so that the project can be warned as soon as possible -about to-be-deprecated features -that may require changes to the configuration. - -.TP ---warn=link, --warn=no-link -Enables or disables warnings about link steps. - -.TP ---warn=misleading-keywords, --warn=no-misleading-keywords -Enables or disables warnings about use of the misspelled keywords -.B targets -and -.B sources -when calling Builders. -(Note the last -.B s -characters, the correct spellings are -.B target -and -.B source.) -These warnings are enabled by default. - -.TP ---warn=missing-sconscript, --warn=no-missing-sconscript -Enables or disables warnings about missing SConscript files. -These warnings are enabled by default. - -.TP ---warn=no-md5-module, --warn=no-no-md5-module -Enables or disables warnings about the version of Python -not having an MD5 checksum module available. -These warnings are enabled by default. - -.TP ---warn=no-metaclass-support, --warn=no-no-metaclass-support -Enables or disables warnings about the version of Python -not supporting metaclasses when the -.B --debug=memoizer -option is used. -These warnings are enabled by default. - -.TP ---warn=no-object-count, --warn=no-no-object-count -Enables or disables warnings about the -.B --debug=object -feature not working when -.B scons -is run with the python -.B \-O -option or from optimized Python (.pyo) modules. - -.TP ---warn=no-parallel-support, --warn=no-no-parallel-support -Enables or disables warnings about the version of Python -not being able to support parallel builds when the -.B -j -option is used. -These warnings are enabled by default. - -.TP ---warn=python-version, --warn=no-python-version -Enables or disables the warning about running -SCons with a deprecated version of Python. -These warnings are enabled by default. - -.TP ---warn=reserved-variable, --warn=no-reserved-variable -Enables or disables warnings about attempts to set the -reserved construction variable names -.BR CHANGED_SOURCES , -.BR CHANGED_TARGETS , -.BR TARGET , -.BR TARGETS , -.BR SOURCE , -.BR SOURCES , -.BR UNCHANGED_SOURCES -or -.BR UNCHANGED_TARGETS . -These warnings are disabled by default. - -.TP ---warn=stack-size, --warn=no-stack-size -Enables or disables warnings about requests to set the stack size -that could not be honored. -These warnings are enabled by default. - -.\" .TP -.\" .RI --write-filenames= file -.\" Write all filenames considered into -.\" .IR file . -.\" -.\" .TP -.\" .RI -W " file" ", --what-if=" file ", --new-file=" file ", --assume-new=" file -.\" Pretend that the target -.\" .I file -.\" has been -.\" modified. When used with the -.\" .B -n -.\" option, this -.\" show you what would be rebuilt if you were to modify that file. -.\" Without -.\" .B -n -.\" ... what? XXX -.\" -.\" .TP -.\" --warn-undefined-variables -.\" Warn when an undefined variable is referenced. - -.TP -.RI -Y " repository" ", --repository=" repository ", --srcdir=" repository -Search the specified repository for any input and target -files not found in the local directory hierarchy. Multiple -.B -Y -options may be specified, in which case the -repositories are searched in the order specified. - -.SH CONFIGURATION FILE REFERENCE -.\" .SS Python Basics -.\" XXX Adding this in the future would be a help. -.SS Construction Environments -A construction environment is the basic means by which the SConscript -files communicate build information to -.BR scons . -A new construction environment is created using the -.B Environment -function: - -.ES -env = Environment() -.EE - -Variables, called -.I construction -.IR variables , -may be set in a construction environment -either by specifying them as keywords when the object is created -or by assigning them a value after the object is created: - -.ES -env = Environment(FOO = 'foo') -env['BAR'] = 'bar' -.EE - -As a convenience, -construction variables may also be set or modified by the -.I parse_flags -keyword argument, which applies the -.B ParseFlags -method (described below) to the argument value -after all other processing is completed. -This is useful either if the exact content of the flags is unknown -(for example, read from a control file) -or if the flags are distributed to a number of construction variables. - -.ES -env = Environment(parse_flags = '-Iinclude -DEBUG -lm') -.EE - -This example adds 'include' to -.BR CPPPATH , -\&'EBUG' to -.BR CPPDEFINES , -and 'm' to -.BR LIBS . - -By default, a new construction environment is -initialized with a set of builder methods -and construction variables that are appropriate -for the current platform. -An optional platform keyword argument may be -used to specify that an environment should -be initialized for a different platform: - -.ES -env = Environment(platform = 'cygwin') -env = Environment(platform = 'os2') -env = Environment(platform = 'posix') -env = Environment(platform = 'win32') -.EE - -Specifying a platform initializes the appropriate -construction variables in the environment -to use and generate file names with prefixes -and suffixes appropriate for the platform. - -Note that the -.B win32 -platform adds the -.B SystemDrive -and -.B SystemRoot -variables from the user's external environment -to the construction environment's -.B ENV -dictionary. -This is so that any executed commands -that use sockets to connect with other systems -(such as fetching source files from -external CVS repository specifications like -.BR :pserver:anonymous@cvs.sourceforge.net:/cvsroot/scons ) -will work on Windows systems. - -The platform argument may be function or callable object, -in which case the Environment() method -will call the specified argument to update -the new construction environment: - -.ES -def my_platform(env): - env['VAR'] = 'xyzzy' - -env = Environment(platform = my_platform) -.EE - -Additionally, a specific set of tools -with which to initialize the environment -may be specified as an optional keyword argument: - -.ES -env = Environment(tools = ['msvc', 'lex']) -.EE - -Non-built-in tools may be specified using the toolpath argument: - -.ES -env = Environment(tools = ['default', 'foo'], toolpath = ['tools']) -.EE - -This looks for a tool specification in tools/foo.py (as well as -using the ordinary default tools for the platform). foo.py should -have two functions: generate(env, **kw) and exists(env). -The -.B generate() -function -modifies the passed-in environment -to set up variables so that the tool -can be executed; -it may use any keyword arguments -that the user supplies (see below) -to vary its initialization. -The -.B exists() -function should return a true -value if the tool is available. -Tools in the toolpath are used before -any of the built-in ones. For example, adding gcc.py to the toolpath -would override the built-in gcc tool. -Also note that the toolpath is -stored in the environment for use -by later calls to -.BR Clone () -and -.BR Tool () -methods: - -.ES -base = Environment(toolpath=['custom_path']) -derived = base.Clone(tools=['custom_tool']) -derived.CustomBuilder() -.EE - -The elements of the tools list may also -be functions or callable objects, -in which case the Environment() method -will call the specified elements -to update the new construction environment: - -.ES -def my_tool(env): - env['XYZZY'] = 'xyzzy' - -env = Environment(tools = [my_tool]) -.EE - -The individual elements of the tools list -may also themselves be two-element lists of the form -.RI ( toolname ", " kw_dict ). -SCons searches for the -.I toolname -specification file as described above, and -passes -.IR kw_dict , -which must be a dictionary, as keyword arguments to the tool's -.B generate -function. -The -.B generate -function can use the arguments to modify the tool's behavior -by setting up the environment in different ways -or otherwise changing its initialization. - -.ES -# in tools/my_tool.py: -def generate(env, **kw): - # Sets MY_TOOL to the value of keyword argument 'arg1' or 1. - env['MY_TOOL'] = kw.get('arg1', '1') -def exists(env): - return 1 - -# in SConstruct: -env = Environment(tools = ['default', ('my_tool', {'arg1': 'abc'})], - toolpath=['tools']) -.EE - -The tool definition (i.e. my_tool()) can use the PLATFORM variable from -the environment it receives to customize the tool for different platforms. - -If no tool list is specified, then SCons will auto-detect the installed -tools using the PATH variable in the ENV construction variable and the -platform name when the Environment is constructed. Changing the PATH -variable after the Environment is constructed will not cause the tools to -be redetected. - -SCons supports the following tool specifications out of the box: - -.ES -386asm -aixc++ -aixcc -aixf77 -aixlink -ar -as -bcc32 -c++ -cc -cvf -dmd -dvipdf -dvips -f77 -f90 -f95 -fortran -g++ -g77 -gas -gcc -gfortran -gnulink -gs -hpc++ -hpcc -hplink -icc -icl -ifl -ifort -ilink -ilink32 -intelc -jar -javac -javah -latex -lex -link -linkloc -m4 -masm -midl -mingw -mslib -mslink -mssdk -msvc -msvs -mwcc -mwld -nasm -pdflatex -pdftex -qt -rmic -rpcgen -sgiar -sgic++ -sgicc -sgilink -sunar -sunc++ -suncc -sunf77 -sunf90 -sunf95 -sunlink -swig -tar -tex -textfile -tlib -yacc -zip -.EE - -Additionally, there is a "tool" named -.B default -which configures the -environment with a default set of tools for the current platform. - -On posix and cygwin platforms -the GNU tools (e.g. gcc) are preferred by SCons, -on Windows the Microsoft tools (e.g. msvc) -followed by MinGW are preferred by SCons, -and in OS/2 the IBM tools (e.g. icc) are preferred by SCons. - -.SS Builder Methods - -Build rules are specified by calling a construction -environment's builder methods. -The arguments to the builder methods are -.B target -(a list of targets to be built, -usually file names) -and -.B source -(a list of sources to be built, -usually file names). - -Because long lists of file names -can lead to a lot of quoting, -.B scons -supplies a -.B Split() -global function -and a same-named environment method -that split a single string -into a list, separated on -strings of white-space characters. -(These are similar to the split() member function of Python strings -but work even if the input isn't a string.) - -Like all Python arguments, -the target and source arguments to a builder method -can be specified either with or without -the "target" and "source" keywords. -When the keywords are omitted, -the target is first, -followed by the source. -The following are equivalent examples of calling the Program builder method: - -.ES -env.Program('bar', ['bar.c', 'foo.c']) -env.Program('bar', Split('bar.c foo.c')) -env.Program('bar', env.Split('bar.c foo.c')) -env.Program(source = ['bar.c', 'foo.c'], target = 'bar') -env.Program(target = 'bar', Split('bar.c foo.c')) -env.Program(target = 'bar', env.Split('bar.c foo.c')) -env.Program('bar', source = 'bar.c foo.c'.split()) -.EE - -Target and source file names -that are not absolute path names -(that is, do not begin with -.B / -on POSIX systems -or -.B \\ -on Windows systems, -with or without -an optional drive letter) -are interpreted relative to the directory containing the -.B SConscript -file being read. -An initial -.B # -(hash mark) -on a path name means that the rest of the file name -is interpreted relative to -the directory containing -the top-level -.B SConstruct -file, -even if the -.B # -is followed by a directory separator character -(slash or backslash). - -Examples: - -.ES -# The comments describing the targets that will be built -# assume these calls are in a SConscript file in the -# a subdirectory named "subdir". - -# Builds the program "subdir/foo" from "subdir/foo.c": -env.Program('foo', 'foo.c') - -# Builds the program "/tmp/bar" from "subdir/bar.c": -env.Program('/tmp/bar', 'bar.c') - -# An initial '#' or '#/' are equivalent; the following -# calls build the programs "foo" and "bar" (in the -# top-level SConstruct directory) from "subdir/foo.c" and -# "subdir/bar.c", respectively: -env.Program('#foo', 'foo.c') -env.Program('#/bar', 'bar.c') - -# Builds the program "other/foo" (relative to the top-level -# SConstruct directory) from "subdir/foo.c": -env.Program('#other/foo', 'foo.c') -.EE - -When the target shares the same base name -as the source and only the suffix varies, -and if the builder method has a suffix defined for the target file type, -then the target argument may be omitted completely, -and -.B scons -will deduce the target file name from -the source file name. -The following examples all build the -executable program -.B bar -(on POSIX systems) -or -.B bar.exe -(on Windows systems) -from the bar.c source file: - -.ES -env.Program(target = 'bar', source = 'bar.c') -env.Program('bar', source = 'bar.c') -env.Program(source = 'bar.c') -env.Program('bar.c') -.EE - -As a convenience, a -.B srcdir -keyword argument may be specified -when calling a Builder. -When specified, -all source file strings that are not absolute paths -will be interpreted relative to the specified -.BR srcdir . -The following example will build the -.B build/prog -(or -.B build/prog.exe -on Windows) -program from the files -.B src/f1.c -and -.BR src/f2.c : - -.ES -env.Program('build/prog', ['f1.c', 'f2.c'], srcdir='src') -.EE - -It is possible to override or add construction variables when calling a -builder method by passing additional keyword arguments. -These overridden or added -variables will only be in effect when building the target, so they will not -affect other parts of the build. For example, if you want to add additional -libraries for just one program: - -.ES -env.Program('hello', 'hello.c', LIBS=['gl', 'glut']) -.EE - -or generate a shared library with a non-standard suffix: - -.ES -env.SharedLibrary('word', 'word.cpp', - SHLIBSUFFIX='.ocx', - LIBSUFFIXES=['.ocx']) -.EE - -(Note that both the $SHLIBSUFFIX and $LIBSUFFIXES variables must be set -if you want SCons to search automatically -for dependencies on the non-standard library names; -see the descriptions of these variables, below, for more information.) - -It is also possible to use the -.I parse_flags -keyword argument in an override: - -.ES -env = Program('hello', 'hello.c', parse_flags = '-Iinclude -DEBUG -lm') -.EE - -This example adds 'include' to -.BR CPPPATH , -\&'EBUG' to -.BR CPPDEFINES , -and 'm' to -.BR LIBS . - -Although the builder methods defined by -.B scons -are, in fact, -methods of a construction environment object, -they may also be called without an explicit environment: - -.ES -Program('hello', 'hello.c') -SharedLibrary('word', 'word.cpp') -.EE - -In this case, -the methods are called internally using a default construction -environment that consists of the tools and values that -.B scons -has determined are appropriate for the local system. - -Builder methods that can be called without an explicit -environment may be called from custom Python modules that you -import into an SConscript file by adding the following -to the Python module: - -.ES -from SCons.Script import * -.EE - -All builder methods return a list-like object -containing Nodes that -represent the target or targets that will be built. -A -.I Node -is an internal SCons object -which represents -build targets or sources. - -The returned Node-list object -can be passed to other builder methods as source(s) -or passed to any SCons function or method -where a filename would normally be accepted. -For example, if it were necessary -to add a specific -.B -D -flag when compiling one specific object file: - -.ES -bar_obj_list = env.StaticObject('bar.c', CPPDEFINES='-DBAR') -env.Program(source = ['foo.c', bar_obj_list, 'main.c']) -.EE - -Using a Node in this way -makes for a more portable build -by avoiding having to specify -a platform-specific object suffix -when calling the Program() builder method. - -Note that Builder calls will automatically "flatten" -the source and target file lists, -so it's all right to have the bar_obj list -return by the StaticObject() call -in the middle of the source file list. -If you need to manipulate a list of lists returned by Builders -directly using Python, -you can either build the list by hand: - -.ES -foo = Object('foo.c') -bar = Object('bar.c') -objects = ['begin.o'] + foo + ['middle.o'] + bar + ['end.o'] -for object in objects: - print str(object) -.EE - -Or you can use the -.BR Flatten () -function supplied by scons -to create a list containing just the Nodes, -which may be more convenient: - -.ES -foo = Object('foo.c') -bar = Object('bar.c') -objects = Flatten(['begin.o', foo, 'middle.o', bar, 'end.o']) -for object in objects: - print str(object) -.EE - -Note also that because Builder calls return -a list-like object, not an actual Python list, -you should -.I not -use the Python -.B += -operator to append Builder results to a Python list. -Because the list and the object are different types, -Python will not update the original list in place, -but will instead create a new Node-list object -containing the concatenation of the list -elements and the Builder results. -This will cause problems for any other Python variables -in your SCons configuration -that still hold on to a reference to the original list. -Instead, use the Python -.B .extend() -method to make sure the list is updated in-place. -Example: - -.ES -object_files = [] - -# Do NOT use += as follows: -# -# object_files += Object('bar.c') -# -# It will not update the object_files list in place. -# -# Instead, use the .extend() method: -object_files.extend(Object('bar.c')) - -.EE - -The path name for a Node's file may be used -by passing the Node to the Python-builtin -.B str() -function: - -.ES -bar_obj_list = env.StaticObject('bar.c', CPPDEFINES='-DBAR') -print "The path to bar_obj is:", str(bar_obj_list[0]) -.EE - -Note again that because the Builder call returns a list, -we have to access the first element in the list -.B (bar_obj_list[0]) -to get at the Node that actually represents -the object file. - -Builder calls support a -.B chdir -keyword argument that -specifies that the Builder's action(s) -should be executed -after changing directory. -If the -.B chdir -argument is -a string or a directory Node, -scons will change to the specified directory. -If the -.B chdir -is not a string or Node -and is non-zero, -then scons will change to the -target file's directory. - -.ES -# scons will change to the "sub" subdirectory -# before executing the "cp" command. -env.Command('sub/dir/foo.out', 'sub/dir/foo.in', - "cp dir/foo.in dir/foo.out", - chdir='sub') - -# Because chdir is not a string, scons will change to the -# target's directory ("sub/dir") before executing the -# "cp" command. -env.Command('sub/dir/foo.out', 'sub/dir/foo.in', - "cp foo.in foo.out", - chdir=1) -.EE - -Note that scons will -.I not -automatically modify -its expansion of -construction variables like -.B $TARGET -and -.B $SOURCE -when using the chdir -keyword argument--that is, -the expanded file names -will still be relative to -the top-level SConstruct directory, -and consequently incorrect -relative to the chdir directory. -If you use the chdir keyword argument, -you will typically need to supply a different -command line using -expansions like -.B ${TARGET.file} -and -.B ${SOURCE.file} -to use just the filename portion of the -targets and source. - -.B scons -provides the following builder methods: - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -'\" BEGIN GENERATED BUILDER DESCRIPTIONS -'\" -'\" The descriptions below of the various SCons Builders are generated -'\" from the .xml files that live next to the various Python modules in -'\" the build enginer library. If you're reading this [gnt]roff file -'\" with an eye towards patching this man page, you can still submit -'\" a diff against this text, but it will have to be translated to a -'\" diff against the underlying .xml file before the patch is actually -'\" accepted. If you do that yourself, it will make it easier to -'\" integrate the patch. -'\" -'\" BEGIN GENERATED BUILDER DESCRIPTIONS -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.IP CFile() -.IP env.CFile() -Builds a C source file given a lex (\fB.l\fP) -or yacc (\fB.y\fP) input file. -The suffix specified by the \fB$CFILESUFFIX\fP construction variable -(\fB.c\fP by default) -is automatically added to the target -if it is not already present. -Example: - -.ES -# builds foo.c -env.CFile(target = 'foo.c', source = 'foo.l') -# builds bar.c -env.CFile(target = 'bar', source = 'bar.y') -.EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.IP Command() -.IP env.Command() -The \fBCommand\fP() "Builder" is actually implemented -as a function that looks like a Builder, -but actually takes an additional argument of the action -from which the Builder should be made. -See the \fBCommand\fP() function description -for the calling syntax and details. - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.IP CXXFile() -.IP env.CXXFile() -Builds a C++ source file given a lex (\fB.ll\fP) -or yacc (\fB.yy\fP) -input file. -The suffix specified by the \fB$CXXFILESUFFIX\fP construction variable -(\fB.cc\fP by default) -is automatically added to the target -if it is not already present. -Example: - -.ES -# builds foo.cc -env.CXXFile(target = 'foo.cc', source = 'foo.ll') -# builds bar.cc -env.CXXFile(target = 'bar', source = 'bar.yy') -.EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.IP DVI() -.IP env.DVI() -Builds a \fB.dvi\fP file -from a \fB.tex\fP, -\fB.ltx\fP or \fB.latex\fP input file. -If the source file suffix is \fB.tex\fP, -.B scons -will examine the contents of the file; -if the string -.B \\documentclass -or -.B \\documentstyle -is found, the file is assumed to be a LaTeX file and -the target is built by invoking the \fB$LATEXCOM\fP command line; -otherwise, the \fB$TEXCOM\fP command line is used. -If the file is a LaTeX file, -the -.BR DVI () -builder method will also examine the contents -of the -.B .aux -file and invoke the \fB$BIBTEX\fP command line -if the string -.B bibdata -is found, -start \fB$MAKEINDEX\fP to generate an index if a -.B .ind -file is found -and will examine the contents -.B .log -file and re-run the \fB$LATEXCOM\fP command -if the log file says it is necessary. - -The suffix \fB.dvi\fP -(hard-coded within TeX itself) -is automatically added to the target -if it is not already present. -Examples: - -.ES -# builds from aaa.tex -env.DVI(target = 'aaa.dvi', source = 'aaa.tex') -# builds bbb.dvi -env.DVI(target = 'bbb', source = 'bbb.ltx') -# builds from ccc.latex -env.DVI(target = 'ccc.dvi', source = 'ccc.latex') -.EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.IP Install() -.IP env.Install() -Installs one or more source files or directories -in the specified target, -which must be a directory. -The names of the specified source files or directories -remain the same within the destination directory. The -sources may be given as a string or as a node returned by -a builder. - -.ES -env.Install('/usr/local/bin', source = ['foo', 'bar']) -.EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.IP InstallAs() -.IP env.InstallAs() -Installs one or more source files or directories -to specific names, -allowing changing a file or directory name -as part of the installation. -It is an error if the -target -and -source -arguments list different numbers of files or directories. - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.IP InstallVersionedLib() -.IP env.InstallVersionedLib() -Installs a versioned shared library. The \fB$SHLIBVERSION\fP -construction variable should be defined in the environment -to confirm the version number in the library name. -The symlinks appropriate to the architecture will be generated. - -.ES -env.InstallAs(target = '/usr/local/bin/foo', - source = 'foo_debug') -env.InstallAs(target = ['../lib/libfoo.a', '../lib/libbar.a'], - source = ['libFOO.a', 'libBAR.a']) -.EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.IP Jar() -.IP env.Jar() -Builds a Java archive (\fB.jar\fP) file -from the specified list of sources. -Any directories in the source list -will be searched for \fB.class\fP files). -Any \fB.java\fP files in the source list -will be compiled to \fB.class\fP files -by calling the \fBJava\fP() Builder. - -If the \fB$JARCHDIR\fP value is set, the -.B jar -command will change to the specified directory using the -.B \-C -option. -If \fB$JARCHDIR\fP is not set explicitly, -&SCons; will use the top of any subdirectory tree -in which Java \fB.class\fP -were built by the \fBJava\fP() Builder. - -If the contents any of the source files begin with the string -.BR Manifest-Version , -the file is assumed to be a manifest -and is passed to the -.B jar -command with the -.B m -option set. - -.ES -env.Jar(target = 'foo.jar', source = 'classes') - -env.Jar(target = 'bar.jar', - source = ['bar1.java', 'bar2.java']) -.EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.IP Java() -.IP env.Java() -Builds one or more Java class files. -The sources may be any combination of explicit -\fB.java\fP files, -or directory trees which will be scanned -for \fB.java\fP files. - -SCons will parse each source \fB.java\fP file -to find the classes -(including inner classes) -defined within that file, -and from that figure out the -target \fB.class\fP files that will be created. -The class files will be placed underneath -the specified target directory. - -SCons will also search each Java file -for the Java package name, -which it assumes can be found on a line -beginning with the string -.B package -in the first column; -the resulting \fB.class\fP files -will be placed in a directory reflecting -the specified package name. -For example, -the file -.B Foo.java -defining a single public -.I Foo -class and -containing a package name of -.I sub.dir -will generate a corresponding -.B sub/dir/Foo.class -class file. - -Examples: - -.ES -env.Java(target = 'classes', source = 'src') -env.Java(target = 'classes', source = ['src1', 'src2']) -env.Java(target = 'classes', source = ['File1.java', 'File2.java']) -.EE -.IP -Java source files can use the native encoding for the underlying OS. -Since SCons compiles in simple ASCII mode by default, -the compiler will generate warnings about unmappable characters, -which may lead to errors as the file is processed further. -In this case, the user must specify the \fBLANG\fP -environment variable to tell the compiler what encoding is used. -For portibility, it's best if the encoding is hard-coded -so that the compile will work if it is done on a system -with a different encoding. - -.ES -env = Environment() -env['ENV']['LANG'] = 'en_GB.UTF-8' -.EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.IP JavaH() -.IP env.JavaH() -Builds C header and source files for -implementing Java native methods. -The target can be either a directory -in which the header files will be written, -or a header file name which -will contain all of the definitions. -The source can be the names of \fB.class\fP files, -the names of \fB.java\fP files -to be compiled into \fB.class\fP files -by calling the \fBJava\fP() builder method, -or the objects returned from the -.BR Java () -builder method. - -If the construction variable -.B $JAVACLASSDIR -is set, either in the environment -or in the call to the -.BR JavaH () -builder method itself, -then the value of the variable -will be stripped from the -beginning of any \fB.class\fP file names. - -Examples: - -.ES -# builds java_native.h -classes = env.Java(target = 'classdir', source = 'src') -env.JavaH(target = 'java_native.h', source = classes) - -# builds include/package_foo.h and include/package_bar.h -env.JavaH(target = 'include', - source = ['package/foo.class', 'package/bar.class']) - -# builds export/foo.h and export/bar.h -env.JavaH(target = 'export', - source = ['classes/foo.class', 'classes/bar.class'], - JAVACLASSDIR = 'classes') -.EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.IP Library() -.IP env.Library() -A synonym for the -.BR StaticLibrary () -builder method. - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.IP LoadableModule() -.IP env.LoadableModule() -On most systems, -this is the same as -.BR SharedLibrary (). -On Mac OS X (Darwin) platforms, -this creates a loadable module bundle. - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.IP M4() -.IP env.M4() -Builds an output file from an M4 input file. -This uses a default \fB$M4FLAGS\fP value of -.BR \-E , -which considers all warnings to be fatal -and stops on the first warning -when using the GNU version of m4. -Example: - -.ES -env.M4(target = 'foo.c', source = 'foo.c.m4') -.EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.IP Moc() -.IP env.Moc() -Builds an output file from a moc input file. Moc input files are either -header files or cxx files. This builder is only available after using the -tool 'qt'. See the \fB$QTDIR\fP variable for more information. -Example: - -.ES -env.Moc('foo.h') # generates moc_foo.cc -env.Moc('foo.cpp') # generates foo.moc -.EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.IP MOFiles() -.IP env.MOFiles() -This builder belongs to &t-link-msgfmt; tool. The builder compiles -\fBPO\fP files to \fBMO\fP files. - -.IR Example 1 . -Create \fBpl.mo\fP and \fBen.mo\fP by compiling -.BR pl.po\fP and \fBen.po : -.ES - # ... - env.MOFiles(['pl', 'en']) -.EE -.IP -.IR Example 2 . -Compile files for languages defined in \fBLINGUAS\fP file: -.ES - # ... - env.MOFiles(LINGUAS_FILE = 1) -.EE -.IP -.IR Example 3 . -Create \fBpl.mo\fP and \fBen.mo\fP by compiling -\fBpl.po\fP and \fBen.po\fP plus files for -languages defined in \fBLINGUAS\fP file: -.ES - # ... - env.MOFiles(['pl', 'en'], LINGUAS_FILE = 1) -.EE -.IP -.IR Example 4 . -Compile files for languages defined in \fBLINGUAS\fP file -(another version): -.ES - # ... - env['LINGUAS_FILE'] = 1 - env.MOFiles() -.EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.IP MSVSProject() -.IP env.MSVSProject() -Builds a Microsoft Visual Studio project file, -and by default builds a solution file as well. - -This builds a Visual Studio project file, based on the version of -Visual Studio that is configured (either the latest installed version, -or the version specified by -.B $MSVS_VERSION -in the Environment constructor). -For Visual Studio 6, it will generate a -.B .dsp -file. -For Visual Studio 7 (.NET) and later versions, it will generate a -.B .vcproj -file. - -By default, -this also generates a solution file -for the specified project, -a -.B .dsw -file for Visual Studio 6 -or a -.B .sln -file for Visual Studio 7 (.NET). -This behavior may be disabled by specifying -.B auto_build_solution=0 -when you call -.BR MSVSProject (), -in which case you presumably want to -build the solution file(s) -by calling the -.BR MSVSSolution () -Builder (see below). - -The \fBMSVSProject\fP() builder -takes several lists of filenames -to be placed into the project file. -These are currently limited to -.BR srcs , -.BR incs , -.BR localincs , -.BR resources , -and -.BR misc . -These are pretty self-explanatory, but it should be noted that these -lists are added to the \fB$SOURCES\fP construction variable as strings, -NOT as SCons File Nodes. This is because they represent file -names to be added to the project file, not the source files used to -build the project file. - -The above filename lists are all optional, -although at least one must be specified -for the resulting project file to be non-empty. - -In addition to the above lists of values, -the following values may be specified: - -.BR target : -The name of the target -.B .dsp -or -.B .vcproj -file. -The correct -suffix for the version of Visual Studio must be used, -but the -.B $MSVSPROJECTSUFFIX -construction variable -will be defined to the correct value (see example below). - -.BR variant : -The name of this particular variant. -For Visual Studio 7 projects, -this can also be a list of variant names. -These are typically things like "Debug" or "Release", but really -can be anything you want. -For Visual Studio 7 projects, -they may also specify a target platform -separated from the variant name by a -.B | -(vertical pipe) -character: -.BR Debug|Xbox . -The default target platform is Win32. -Multiple calls to -.BR MSVSProject () -with different variants are allowed; -all variants will be added to the project file with their appropriate -build targets and sources. - -.BR buildtarget : -An optional string, node, or list of strings or nodes -(one per build variant), to tell the Visual Studio debugger -what output target to use in what build variant. -The number of -.B buildtarget -entries must match the number of -.B variant -entries. - -.BR runfile : -The name of the file that Visual Studio 7 and later -will run and debug. -This appears as the value of the -.B Output -field in the resutling Visual Studio project file. -If this is not specified, -the default is the same as the specified -.B buildtarget -value. - -Note that because &SCons; always executes its build commands -from the directory in which the \fBSConstruct\fP file is located, -if you generate a project file in a different directory -than the \fBSConstruct\fP directory, -users will not be able to double-click -on the file name in compilation error messages -displayed in the Visual Studio console output window. -This can be remedied by adding the -Visual C/C++ -.B /FC -compiler option to the \fB$CCFLAGS\fP variable -so that the compiler will print -the full path name of any -files that cause compilation errors. - -Example usage: - -.ES -barsrcs = ['bar.cpp'], -barincs = ['bar.h'], -barlocalincs = ['StdAfx.h'] -barresources = ['bar.rc','resource.h'] -barmisc = ['bar_readme.txt'] - -dll = env.SharedLibrary(target = 'bar.dll', - source = barsrcs) - -env.MSVSProject(target = 'Bar' + env['MSVSPROJECTSUFFIX'], - srcs = barsrcs, - incs = barincs, - localincs = barlocalincs, - resources = barresources, - misc = barmisc, - buildtarget = dll, - variant = 'Release') -.EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.IP MSVSSolution() -.IP env.MSVSSolution() -Builds a Microsoft Visual Studio solution file. - -This builds a Visual Studio solution file, -based on the version of Visual Studio that is configured -(either the latest installed version, -or the version specified by -.B $MSVS_VERSION -in the construction environment). -For Visual Studio 6, it will generate a -.B .dsw -file. -For Visual Studio 7 (.NET), it will -generate a -.B .sln -file. - -The following values must be specified: - -.BR target : -The name of the target .dsw or .sln file. The correct -suffix for the version of Visual Studio must be used, but the value -.B $MSVSSOLUTIONSUFFIX -will be defined to the correct value (see example below). - -.BR variant : -The name of this particular variant, or a list of variant -names (the latter is only supported for MSVS 7 solutions). These are -typically things like "Debug" or "Release", but really can be anything -you want. For MSVS 7 they may also specify target platform, like this -"Debug|Xbox". Default platform is Win32. - -.BR projects : -A list of project file names, or Project nodes returned by calls to the -.BR MSVSProject () -Builder, -to be placed into the solution file. -It should be noted that these file names are NOT added to the $SOURCES -environment variable in form of files, but rather as strings. This -is because they represent file names to be added to the solution file, -not the source files used to build the solution file. - -Example Usage: - -.ES -env.MSVSSolution(target = 'Bar' + env['MSVSSOLUTIONSUFFIX'], - projects = ['bar' + env['MSVSPROJECTSUFFIX']], - variant = 'Release') -.EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.IP Object() -.IP env.Object() -A synonym for the -.BR StaticObject () -builder method. - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.IP Package() -.IP env.Package() -Builds software distribution packages. -Packages consist of files to install and packaging information. -The former may be specified with the \fIsource\fP parameter and may be left out, -in which case the &FindInstalledFiles; function will collect -all files that have an \fBInstall\fP() or \fBInstallAs\fP() Builder attached. -If the \fItarget\fP is not specified -it will be deduced from additional information given to this Builder. - -The packaging information is specified -with the help of construction variables documented below. -This information is called a tag to stress that -some of them can also be attached to files with the &Tag; function. -The mandatory ones will complain if they were not specified. -They vary depending on chosen target packager. - -The target packager may be selected with the "PACKAGETYPE" command line -option or with the \fB$PACKAGETYPE\fP construction variable. Currently -the following packagers available: - - * msi - Microsoft Installer - * rpm - Redhat Package Manger - * ipkg - Itsy Package Management System - * tarbz2 - compressed tar - * targz - compressed tar - * zip - zip file - * src_tarbz2 - compressed tar source - * src_targz - compressed tar source - * src_zip - zip file source - -An updated list is always available under the "package_type" option when -running "scons --help" on a project that has packaging activated. -.ES -env = Environment(tools=['default', 'packaging']) -env.Install('/bin/', 'my_program') -env.Package( NAME = 'foo', - VERSION = '1.2.3', - PACKAGEVERSION = 0, - PACKAGETYPE = 'rpm', - LICENSE = 'gpl', - SUMMARY = 'balalalalal', - DESCRIPTION = 'this should be really really long', - X_RPM_GROUP = 'Application/fu', - SOURCE_URL = 'http://foo.org/foo-1.2.3.tar.gz' - ) -.EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.IP PCH() -.IP env.PCH() -Builds a Microsoft Visual C++ precompiled header. -Calling this builder method -returns a list of two targets: the PCH as the first element, and the object -file as the second element. Normally the object file is ignored. -This builder method is only -provided when Microsoft Visual C++ is being used as the compiler. -The PCH builder method is generally used in -conjuction with the PCH construction variable to force object files to use -the precompiled header: - -.ES -env['PCH'] = env.PCH('StdAfx.cpp')[0] -.EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.IP PDF() -.IP env.PDF() -Builds a \fB.pdf\fP file -from a \fB.dvi\fP input file -(or, by extension, a \fB.tex\fP, -.BR .ltx , -or -\fB.latex\fP input file). -The suffix specified by the \fB$PDFSUFFIX\fP construction variable -(\fB.pdf\fP by default) -is added automatically to the target -if it is not already present. Example: - -.ES -# builds from aaa.tex -env.PDF(target = 'aaa.pdf', source = 'aaa.tex') -# builds bbb.pdf from bbb.dvi -env.PDF(target = 'bbb', source = 'bbb.dvi') -.EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.IP POInit() -.IP env.POInit() -This builder belongs to &t-link-msginit; tool. The builder initializes missing -\fBPO\fP file(s) if \fB$POAUTOINIT\fP is set. If -\fB$POAUTOINIT\fP is not set (default), \fBPOInit\fP() prints instruction for -user (that is supposed to be a translator), telling how the -\fBPO\fP file should be initialized. In normal projects -.IR you should not use \fBPOInit\fP() and use \fBPOUpdate () -instead\fP. \fBPOUpdate\fP() chooses intelligently between -.BR msgmerge(1)\fP and \fBmsginit(1)\fP. \fBPOInit () -always uses \fBmsginit(1)\fP and should be regarded as builder for -special purposes or for temporary use (e.g. for quick, one time initialization -of a bunch of \fBPO\fP files) or for tests. - -Target nodes defined through \fBPOInit\fP() are not built by default (they're -\fBIgnore\fPd from \fB'.'\fP node) but are added to -special \fBAlias\fP (\fB'po-create'\fP by default). -The alias name may be changed through the \fB$POCREATE_ALIAS\fP -construction variable. All \fBPO\fP files defined through -.BR POInit\fP() may be easily initialized by \fBscons po-create . - -.IR Example 1 . -Initialize \fBen.po\fP and \fBpl.po\fP from -.BR messages.pot : -.ES - # ... - env.POInit(['en', 'pl']) # messages.pot --> [en.po, pl.po] -.EE -.IP -.IR Example 2 . -Initialize \fBen.po\fP and \fBpl.po\fP from -.BR foo.pot : -.ES - # ... - env.POInit(['en', 'pl'], ['foo']) # foo.pot --> [en.po, pl.po] -.EE -.IP -.IR Example 3 . -Initialize \fBen.po\fP and \fBpl.po\fP from -\fBfoo.pot\fP but using \fB$POTDOMAIN\fP construction -variable: -.ES - # ... - env.POInit(['en', 'pl'], POTDOMAIN='foo') # foo.pot --> [en.po, pl.po] -.EE -.IP -.IR Example 4 . -Initialize \fBPO\fP files for languages defined in -\fBLINGUAS\fP file. The files will be initialized from template -.BR messages.pot : -.ES - # ... - env.POInit(LINGUAS_FILE = 1) # needs 'LINGUAS' file -.EE -.IP -.IR Example 5 . -Initialize \fBen.po\fP and \fBpl.pl\fP -\fBPO\fP files plus files for languages defined in -\fBLINGUAS\fP file. The files will be initialized from template -.BR messages.pot : -.ES - # ... - env.POInit(['en', 'pl'], LINGUAS_FILE = 1) -.EE -.IP -.IR Example 6 . -You may preconfigure your environment first, and then initialize -\fBPO\fP files: -.ES - # ... - env['POAUTOINIT'] = 1 - env['LINGUAS_FILE'] = 1 - env['POTDOMAIN'] = 'foo' - env.POInit() -.EE -which has same efect as: -.ES - # ... - env.POInit(POAUTOINIT = 1, LINGUAS_FILE = 1, POTDOMAIN = 'foo') -.EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.IP PostScript() -.IP env.PostScript() -Builds a \fB.ps\fP file -from a \fB.dvi\fP input file -(or, by extension, a \fB.tex\fP, -.BR .ltx , -or -\fB.latex\fP input file). -The suffix specified by the \fB$PSSUFFIX\fP construction variable -(\fB.ps\fP by default) -is added automatically to the target -if it is not already present. Example: - -.ES -# builds from aaa.tex -env.PostScript(target = 'aaa.ps', source = 'aaa.tex') -# builds bbb.ps from bbb.dvi -env.PostScript(target = 'bbb', source = 'bbb.dvi') -.EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.IP POTUpdate() -.IP env.POTUpdate() -The builder belongs to &t-link-xgettext; tool. The builder updates target -\fBPOT\fP file if exists or creates one if it doesn't. The node is -not built by default (i.e. it is \fBIgnore\fPd from -\fB'.'\fP), but only on demand (i.e. when given -\fBPOT\fP file is required or when special alias is invoked). This -builder adds its targe node (\fBmessages.pot\fP, say) to a -special alias (\fBpot-update\fP by default, see -\fB$POTUPDATE_ALIAS\fP) so you can update/create them easily with -\fBscons pot-update\fP. The file is not written until there is no -real change in internationalized messages (or in comments that enter -\fBPOT\fP file). - -<note> -You may see \fBxgettext(1)\fP being invoked by the -&t-link-xgettext; tool even if there is no real change in internationalized -messages (so the \fBPOT\fP file is not being updated). This -happens every time a source file has changed. In such case we invoke -\fBxgettext(1)\fP and compare its output with the content of -\fBPOT\fP file to decide whether the file should be updated or -not.</para></note> - -.I "Example 1." -Let's create \fBpo/\fP directory and place following -\fBSConstruct\fP script there: -.ES - # SConstruct in 'po/' subdir - env = Environment( tools = ['default', 'xgettext'] ) - env.POTUpdate(['foo'], ['../a.cpp', '../b.cpp']) - env.POTUpdate(['bar'], ['../c.cpp', '../d.cpp']) -.EE -.IP - -Then invoke scons few times: -.ES - user@host:$ scons # Does not create foo.pot nor bar.pot - user@host:$ scons foo.pot # Updates or creates foo.pot - user@host:$ scons pot-update # Updates or creates foo.pot and bar.pot - user@host:$ scons -c # Does not clean foo.pot nor bar.pot. -.EE -the results shall be as the comments above say. - -.I "Example 2." -The \fBPOTUpdate\fP() builder may be used with no target specified, in which -case default target \fBmessages.pot\fP will be used. The -default target may also be overriden by setting \fB$POTDOMAIN\fP construction -variable or providing it as an override to \fBPOTUpdate\fP() builder: -.ES - # SConstruct script - env = Environment( tools = ['default', 'xgettext'] ) - env['POTDOMAIN'] = "foo" - env.POTUpdate(source = ["a.cpp", "b.cpp"]) # Creates foo.pot ... - env.POTUpdate(POTDOMAIN = "bar", source = ["c.cpp", "d.cpp"]) # and bar.pot -.EE -.IP -.I "Example 3." -The sources may be specified within separate file, for example -.BR POTFILES.in : -.ES - # POTFILES.in in 'po/' subdirectory - ../a.cpp - ../b.cpp - # end of file -.EE -.IP - -The name of the file (\fBPOTFILES.in\fP) containing the list of -sources is provided via \fB$XGETTEXTFROM\fP: -.ES - # SConstruct file in 'po/' subdirectory - env = Environment( tools = ['default', 'xgettext'] ) - env.POTUpdate(XGETTEXTFROM = 'POTFILES.in') -.EE -.IP - - -.I "Example 4." -You may use \fB$XGETTEXTPATH\fP to define source search path. Assume, for -example, that you have files \fBa.cpp\fP, -.BR b.cpp\fP, \fBpo/SConstruct , -.BR po/POTFILES.in\fP. Then your \fBPOT -related -files could look as below: -.ES - # POTFILES.in in 'po/' subdirectory - a.cpp - b.cpp - # end of file -.EE - -.ES - # SConstruct file in 'po/' subdirectory - env = Environment( tools = ['default', 'xgettext'] ) - env.POTUpdate(XGETTEXTFROM = 'POTFILES.in', XGETTEXTPATH='../') -.EE -.IP -.I "Example 5." -Multiple search directories may be defined within a list, i.e. -\fBXGETTEXTPATH = ['dir1', 'dir2', ...]\fP. The order in the list -determines the search order of source files. The path to the first file found -is used. - -Let's create \fB0/1/po/SConstruct\fP script: -.ES - # SConstruct file in '0/1/po/' subdirectory - env = Environment( tools = ['default', 'xgettext'] ) - env.POTUpdate(XGETTEXTFROM = 'POTFILES.in', XGETTEXTPATH=['../', '../../']) -.EE -and \fB0/1/po/POTFILES.in\fP: -.ES - # POTFILES.in in '0/1/po/' subdirectory - a.cpp - # end of file -.EE -Write two \fB*.cpp\fP files, the first one is -.BR 0/a.cpp : -.ES - /* 0/a.cpp */ - gettext("Hello from ../../a.cpp") -.EE -and the second is \fB0/1/a.cpp\fP: -.ES - /* 0/1/a.cpp */ - gettext("Hello from ../a.cpp") -.EE -then run scons. You'll obtain \fB0/1/po/messages.pot\fP with the -message \fB"Hello from ../a.cpp"\fP. When you reverse order in -\fI$XGETTEXTFOM\fP, i.e. when you write SConscript as -.ES - # SConstruct file in '0/1/po/' subdirectory - env = Environment( tools = ['default', 'xgettext'] ) - env.POTUpdate(XGETTEXTFROM = 'POTFILES.in', XGETTEXTPATH=['../../', '../']) -.EE -.IP - then the \fBmessages.pot\fP will contain -\fBmsgid "Hello from ../../a.cpp"\fP line and not -.BR msgid "Hello from ../a.cpp" . - - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.IP POUpdate() -.IP env.POUpdate() -The builder belongs to &t-link-msgmerge; tool. The builder updates -\fBPO\fP files with \fBmsgmerge(1)\fP, or initializes -missing \fBPO\fP files as described in documentation of -&t-link-msginit; tool and \fBPOInit\fP() builder (see also -\fB$POAUTOINIT\fP). Note, that \fBPOUpdate\fP() \fIdoes not add its -targets to \fBpo-create\fP alias\fP as \fBPOInit\fP() -does. - -Target nodes defined through \fBPOUpdate\fP() are not built by default -(they're \fBIgnore\fPd from \fB'.'\fP node). Instead, -they are added automatically to special \fBAlias\fP -(\fB'po-update'\fP by default). The alias name may be changed -through the \fB$POUPDATE_ALIAS\fP construction variable. You can easilly -update \fBPO\fP files in your project by \fBscons -po-update\fP. - -.I "Example 1." -Update \fBen.po\fP and \fBpl.po\fP from -.BR messages.pot\fP template (see also \fB$POTDOMAIN ), -assuming that the later one exists or there is rule to build it (see -.BR POTUpdate ()): -.ES - # ... - env.POUpdate(['en','pl']) # messages.pot --> [en.po, pl.po] -.EE -.IP -.I "Example 2." -Update \fBen.po\fP and \fBpl.po\fP from -\fBfoo.pot\fP template: -.ES - # ... - env.POUpdate(['en', 'pl'], ['foo']) # foo.pot --> [en.po, pl.pl] -.EE -.IP -.I "Example 3." -Update \fBen.po\fP and \fBpl.po\fP from -\fBfoo.pot\fP (another version): -.ES - # ... - env.POUpdate(['en', 'pl'], POTDOMAIN='foo') # foo.pot -- > [en.po, pl.pl] -.EE -.IP -.I "Example 4." -Update files for languages defined in \fBLINGUAS\fP file. The -files are updated from \fBmessages.pot\fP template: -.ES - # ... - env.POUpdate(LINGUAS_FILE = 1) # needs 'LINGUAS' file -.EE -.IP -.I "Example 5." -Same as above, but update from \fBfoo.pot\fP template: -.ES - # ... - env.POUpdate(LINGUAS_FILE = 1, source = ['foo']) -.EE -.IP -.I "Example 6." -Update \fBen.po\fP and \fBpl.po\fP plus files for -languages defined in \fBLINGUAS\fP file. The files are updated -from \fBmessages.pot\fP template: -.ES - # produce 'en.po', 'pl.po' + files defined in 'LINGUAS': - env.POUpdate(['en', 'pl' ], LINGUAS_FILE = 1) -.EE -.IP -.I "Example 7." -Use \fB$POAUTOINIT\fP to automatically initialize \fBPO\fP file -if it doesn't exist: -.ES - # ... - env.POUpdate(LINGUAS_FILE = 1, POAUTOINIT = 1) -.EE -.IP -.I "Example 8." -Update \fBPO\fP files for languages defined in -\fBLINGUAS\fP file. The files are updated from -\fBfoo.pot\fP template. All necessary settings are -pre-configured via environment. -.ES - # ... - env['POAUTOINIT'] = 1 - env['LINGUAS_FILE'] = 1 - env['POTDOMAIN'] = 'foo' - env.POUpdate() -.EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.IP Program() -.IP env.Program() -Builds an executable given one or more object files -or C, C++, D, or Fortran source files. -If any C, C++, D or Fortran source files are specified, -then they will be automatically -compiled to object files using the -.BR Object () -builder method; -see that builder method's description for -a list of legal source file suffixes -and how they are interpreted. -The target executable file prefix -(specified by the \fB$PROGPREFIX\fP construction variable; nothing by default) -and suffix -(specified by the \fB$PROGSUFFIX\fP construction variable; -by default, \fB.exe\fP on Windows systems, -nothing on POSIX systems) -are automatically added to the target if not already present. -Example: - -.ES -env.Program(target = 'foo', source = ['foo.o', 'bar.c', 'baz.f']) -.EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.IP RES() -.IP env.RES() -Builds a Microsoft Visual C++ resource file. -This builder method is only provided -when Microsoft Visual C++ or MinGW is being used as the compiler. The -.B .res -(or -.B .o -for MinGW) suffix is added to the target name if no other suffix is given. -The source -file is scanned for implicit dependencies as though it were a C file. -Example: - -.ES -env.RES('resource.rc') -.EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.IP RMIC() -.IP env.RMIC() -Builds stub and skeleton class files -for remote objects -from Java \fB.class\fP files. -The target is a directory -relative to which the stub -and skeleton class files will be written. -The source can be the names of \fB.class\fP files, -or the objects return from the -.BR Java () -builder method. - -If the construction variable -.B $JAVACLASSDIR -is set, either in the environment -or in the call to the -.BR RMIC () -builder method itself, -then the value of the variable -will be stripped from the -beginning of any \fB.class \fP -file names. - -.ES -classes = env.Java(target = 'classdir', source = 'src') -env.RMIC(target = 'outdir1', source = classes) - -env.RMIC(target = 'outdir2', - source = ['package/foo.class', 'package/bar.class']) - -env.RMIC(target = 'outdir3', - source = ['classes/foo.class', 'classes/bar.class'], - JAVACLASSDIR = 'classes') -.EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.IP RPCGenClient() -.IP env.RPCGenClient() -Generates an RPC client stub (\fB_clnt.c\fP) file -from a specified RPC (\fB.x\fP) source file. -Because rpcgen only builds output files -in the local directory, -the command will be executed -in the source file's directory by default. - -.ES -# Builds src/rpcif_clnt.c -env.RPCGenClient('src/rpcif.x') -.EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.IP RPCGenHeader() -.IP env.RPCGenHeader() -Generates an RPC header (\fB.h\fP) file -from a specified RPC (\fB.x\fP) source file. -Because rpcgen only builds output files -in the local directory, -the command will be executed -in the source file's directory by default. - -.ES -# Builds src/rpcif.h -env.RPCGenHeader('src/rpcif.x') -.EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.IP RPCGenService() -.IP env.RPCGenService() -Generates an RPC server-skeleton (\fB_svc.c\fP) file -from a specified RPC (\fB.x\fP) source file. -Because rpcgen only builds output files -in the local directory, -the command will be executed -in the source file's directory by default. - -.ES -# Builds src/rpcif_svc.c -env.RPCGenClient('src/rpcif.x') -.EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.IP RPCGenXDR() -.IP env.RPCGenXDR() -Generates an RPC XDR routine (\fB_xdr.c\fP) file -from a specified RPC (\fB.x\fP) source file. -Because rpcgen only builds output files -in the local directory, -the command will be executed -in the source file's directory by default. - -.ES -# Builds src/rpcif_xdr.c -env.RPCGenClient('src/rpcif.x') -.EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.IP SharedLibrary() -.IP env.SharedLibrary() -Builds a shared library -(\fB.so\fP on a POSIX system, -\fB.dll\fP on Windows) -given one or more object files -or C, C++, D or Fortran source files. -If any source files are given, -then they will be automatically -compiled to object files. -The static library prefix and suffix (if any) -are automatically added to the target. -The target library file prefix -(specified by the \fB$SHLIBPREFIX\fP construction variable; -by default, \fBlib\fP on POSIX systems, -nothing on Windows systems) -and suffix -(specified by the \fB$SHLIBSUFFIX\fP construction variable; -by default, \fB.dll\fP on Windows systems, -\fB.so\fP on POSIX systems) -are automatically added to the target if not already present. -Example: - -.ES -env.SharedLibrary(target = 'bar', source = ['bar.c', 'foo.o']) -.EE -.IP -On Windows systems, the -.BR SharedLibrary () -builder method will always build an import -(\fB.lib\fP) library -in addition to the shared (\fB.dll\fP) library, -adding a \fB.lib\fP library with the same basename -if there is not already a \fB.lib\fP file explicitly -listed in the targets. - -Any object files listed in the -.B source -must have been built for a shared library -(that is, using the -.BR SharedObject () -builder method). -.B scons -will raise an error if there is any mismatch. - -On some platforms, there is a distinction between a shared library -(loaded automatically by the system to resolve external references) -and a loadable module (explicitly loaded by user action). -For maximum portability, use the \fBLoadableModule\fP() builder for the latter. - -When the \fB$SHLIBVERSION\fP construction variable is defined a versioned -shared library is created. This modifies the \fB$SHLINKFLAGS\fP as required, -adds the version number to the library name, and creates the symlinks that -are needed. \fB$SHLIBVERSION\fP needs to be of the form X.Y.Z, where X -and Y are numbers, and Z is a number but can also contain letters to designate -alpha, beta, or release candidate patch levels. - -This builder may create multiple links to the library. On a POSIX system, -for the shared library libbar.so.2.3.1, the links created would be -libbar.so, libbar.so.2, and libbar.so.2.3; on a Darwin (OSX) system -the library would be libbar.2.3.1.dylib and the link would be -libbar.dylib. - -On Windows systems, specifying -.B register=1 -will cause the \fB.dll\fP to be -registered after it is built using REGSVR32. -The command that is run -("regsvr32" by default) is determined by \fB$REGSVR\fP construction -variable, and the flags passed are determined by \fB$REGSVRFLAGS\fP. By -default, \fB$REGSVRFLAGS\fP includes the \fB/s\fP option, -to prevent dialogs from popping -up and requiring user attention when it is run. If you change -\fB$REGSVRFLAGS\fP, be sure to include the \fB/s\fP option. -For example, - -.ES -env.SharedLibrary(target = 'bar', - source = ['bar.cxx', 'foo.obj'], - register=1) -.EE -.IP -will register \fBbar.dll\fP as a COM object -when it is done linking it. - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.IP SharedObject() -.IP env.SharedObject() -Builds an object file for -inclusion in a shared library. -Source files must have one of the same set of extensions -specified above for the -.BR StaticObject () -builder method. -On some platforms building a shared object requires additional -compiler option -(e.g. \fB\-fPIC\fP for gcc) -in addition to those needed to build a -normal (static) object, but on some platforms there is no difference between a -shared object and a normal (static) one. When there is a difference, SCons -will only allow shared objects to be linked into a shared library, and will -use a different suffix for shared objects. On platforms where there is no -difference, SCons will allow both normal (static) -and shared objects to be linked into a -shared library, and will use the same suffix for shared and normal -(static) objects. -The target object file prefix -(specified by the \fB$SHOBJPREFIX\fP construction variable; -by default, the same as \fB$OBJPREFIX\fP) -and suffix -(specified by the \fB$SHOBJSUFFIX\fP construction variable) -are automatically added to the target if not already present. -Examples: - -.ES -env.SharedObject(target = 'ddd', source = 'ddd.c') -env.SharedObject(target = 'eee.o', source = 'eee.cpp') -env.SharedObject(target = 'fff.obj', source = 'fff.for') -.EE -.IP -Note that the source files will be scanned -according to the suffix mappings in the -.B SourceFileScanner -object. -See the section "Scanner Objects," -below, for more information. - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.IP StaticLibrary() -.IP env.StaticLibrary() -Builds a static library given one or more object files -or C, C++, D or Fortran source files. -If any source files are given, -then they will be automatically -compiled to object files. -The static library prefix and suffix (if any) -are automatically added to the target. -The target library file prefix -(specified by the \fB$LIBPREFIX\fP construction variable; -by default, \fBlib\fP on POSIX systems, -nothing on Windows systems) -and suffix -(specified by the \fB$LIBSUFFIX\fP construction variable; -by default, \fB.lib\fP on Windows systems, -\fB.a\fP on POSIX systems) -are automatically added to the target if not already present. -Example: - -.ES -env.StaticLibrary(target = 'bar', source = ['bar.c', 'foo.o']) -.EE -.IP -Any object files listed in the -.B source -must have been built for a static library -(that is, using the -.BR StaticObject () -builder method). -.B scons -will raise an error if there is any mismatch. - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.IP StaticObject() -.IP env.StaticObject() -Builds a static object file -from one or more C, C++, D, or Fortran source files. -Source files must have one of the following extensions: - -.ES - .asm assembly language file - .ASM assembly language file - .c C file - .C Windows: C file - POSIX: C++ file - .cc C++ file - .cpp C++ file - .cxx C++ file - .cxx C++ file - .c++ C++ file - .C++ C++ file - .d D file - .f Fortran file - .F Windows: Fortran file - POSIX: Fortran file + C pre-processor - .for Fortran file - .FOR Fortran file - .fpp Fortran file + C pre-processor - .FPP Fortran file + C pre-processor - .m Object C file - .mm Object C++ file - .s assembly language file - .S Windows: assembly language file - ARM: CodeSourcery Sourcery Lite - .sx assembly language file + C pre-processor - POSIX: assembly language file + C pre-processor - .spp assembly language file + C pre-processor - .SPP assembly language file + C pre-processor -.EE -.IP -The target object file prefix -(specified by the \fB$OBJPREFIX\fP construction variable; nothing by default) -and suffix -(specified by the \fB$OBJSUFFIX\fP construction variable; -\fB.obj\fP on Windows systems, -\fB.o\fP on POSIX systems) -are automatically added to the target if not already present. -Examples: - -.ES -env.StaticObject(target = 'aaa', source = 'aaa.c') -env.StaticObject(target = 'bbb.o', source = 'bbb.c++') -env.StaticObject(target = 'ccc.obj', source = 'ccc.f') -.EE -.IP -Note that the source files will be scanned -according to the suffix mappings in -.B SourceFileScanner -object. -See the section "Scanner Objects," -below, for more information. - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.IP Substfile() -.IP env.Substfile() -The \fBSubstfile\fP() builder generates a single text file -by concatenating the source files. -Nested lists of sources are flattened. -\fB$LINESEPARATOR\fP is used to separate the source files; -see the description of \fBTextfile\fP() for details. - -If a single source file is present with an \fB.in\fP suffix, -the suffix is stripped and the remainder is used as the default target name. - -The prefix and suffix specified by the \fB$SUBSTFILEPREFIX\fP -and \fB$SUBSTFILESUFFIX\fP construction variables -(the null string by default in both cases) -are automatically added to the target if they are not already present. - -If a construction variable named \fB$SUBST_DICT\fP is present, -it may be either a Python dictionary or a sequence of (key,value) tuples. -If the former, -the dictionary is converted into a list of tuples in an arbitrary order, -so if one key is a prefix of another key -or if one substitution could be further expanded by another subsitition, -it is unpredictible whether the expansion will occur. - -Any occurences in the source of a key -are replaced by the corresponding value, -which may be a Python callable function or a string. -If a value is a function, -it is first called (with no arguments) to produce a string. -The string is \fIsubst\fP-expanded -and the result replaces the key. - -.ES -env = Environment(tools = ['default', 'textfile']) - -env['prefix'] = '/usr/bin' -script_dict = {'@prefix@': '/bin', @exec_prefix@: '$prefix'} -env.Substfile('script.in', SUBST_DICT = script_dict) - -conf_dict = {'%VERSION%': '1.2.3', '%BASE%': 'MyProg'} -env.Substfile('config.h.in', conf_dict, SUBST_DICT = conf_dict) - -# UNPREDICTABLE - one key is a prefix of another -bad_foo = {'$foo': '$foo', '$foobar': '$foobar'} -env.Substfile('foo.in', SUBST_DICT = bad_foo) - -# PREDICTABLE - keys are applied longest first -good_foo = [('$foobar', '$foobar'), ('$foo', '$foo')] -env.Substfile('foo.in', SUBST_DICT = good_foo) - -# UNPREDICTABLE - one substitution could be futher expanded -bad_bar = {'@bar@': '@soap@', '@soap@': 'lye'} -env.Substfile('bar.in', SUBST_DICT = bad_bar) - -# PREDICTABLE - substitutions are expanded in order -good_bar = (('@bar@', '@soap@'), ('@soap@', 'lye')) -env.Substfile('bar.in', SUBST_DICT = good_bar) - -# the SUBST_DICT may be in common (and not an override) -substutions = {} -subst = Environment(tools = ['textfile'], SUBST_DICT = substitutions) -substitutions['@foo@'] = 'foo' -subst['SUBST_DICT']['@bar@'] = 'bar' -subst.Substfile('pgm1.c', [Value('#include "@foo@.h"'), - Value('#include "@bar@.h"'), - "common.in", - "pgm1.in" - ]) -subst.Substfile('pgm2.c', [Value('#include "@foo@.h"'), - Value('#include "@bar@.h"'), - "common.in", - "pgm2.in" - ]) - -.EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.IP Tar() -.IP env.Tar() -Builds a tar archive of the specified files -and/or directories. -Unlike most builder methods, -the -.BR Tar () -builder method may be called multiple times -for a given target; -each additional call -adds to the list of entries -that will be built into the archive. -Any source directories will -be scanned for changes to -any on-disk files, -regardless of whether or not -.B scons -knows about them from other Builder or function calls. - -.ES -env.Tar('src.tar', 'src') - -# Create the stuff.tar file. -env.Tar('stuff', ['subdir1', 'subdir2']) -# Also add "another" to the stuff.tar file. -env.Tar('stuff', 'another') - -# Set TARFLAGS to create a gzip-filtered archive. -env = Environment(TARFLAGS = '-c -z') -env.Tar('foo.tar.gz', 'foo') - -# Also set the suffix to .tgz. -env = Environment(TARFLAGS = '-c -z', - TARSUFFIX = '.tgz') -env.Tar('foo') -.EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.IP Textfile() -.IP env.Textfile() -The \fBTextfile\fP() builder generates a single text file. -The source strings constitute the lines; -nested lists of sources are flattened. -\fB$LINESEPARATOR\fP is used to separate the strings. - -If present, the \fB$SUBST_DICT\fP construction variable -is used to modify the strings before they are written; -see the \fBSubstfile\fP() description for details. - -The prefix and suffix specified by the \fB$TEXTFILEPREFIX\fP -and \fB$TEXTFILESUFFIX\fP construction variables -(the null string and \fB.txt\fP by default, respectively) -are automatically added to the target if they are not already present. -Examples: - -.ES -# builds/writes foo.txt -env.Textfile(target = 'foo.txt', source = ['Goethe', 42, 'Schiller']) - -# builds/writes bar.txt -env.Textfile(target = 'bar', - source = ['lalala', 'tanteratei'], - LINESEPARATOR='|*') - -# nested lists are flattened automatically -env.Textfile(target = 'blob', - source = ['lalala', ['Goethe', 42 'Schiller'], 'tanteratei']) - -# files may be used as input by wraping them in File() -env.Textfile(target = 'concat', # concatenate files with a marker between - source = [File('concat1'), File('concat2')], - LINESEPARATOR = '====================\\n') - -Results are: -foo.txt - ....8<---- - Goethe - 42 - Schiller - ....8<---- (no linefeed at the end) - -bar.txt: - ....8<---- - lalala|*tanteratei - ....8<---- (no linefeed at the end) - -blob.txt - ....8<---- - lalala - Goethe - 42 - Schiller - tanteratei - ....8<---- (no linefeed at the end) -.EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.IP Translate() -.IP env.Translate() -This pseudo-builder belongs to &t-link-gettext; toolset. The builder extracts -internationalized messages from source files, updates \fBPOT\fP -template (if necessary) and then updates \fBPO\fP translations (if -necessary). If \fB$POAUTOINIT\fP is set, missing \fBPO\fP files -will be automatically created (i.e. without translator person intervention). -The variables \fB$LINGUAS_FILE\fP and \fB$POTDOMAIN\fP are taken into -acount too. All other construction variables used by \fBPOTUpdate\fP(), and -\fBPOUpdate\fP() work here too. - -.IR Example 1 . -The simplest way is to specify input files and output languages inline in -a SCons script when invoking \fBTranslate\fP() -.ES -# SConscript in 'po/' directory -env = Environment( tools = ["default", "gettext"] ) -env['POAUTOINIT'] = 1 -env.Translate(['en','pl'], ['../a.cpp','../b.cpp']) -.EE -.IP -.IR Example 2 . -If you wish, you may also stick to conventional style known from -<productname>autotools</productname>, i.e. using -\fBPOTFILES.in\fP and \fBLINGUAS\fP files -.ES -# LINGUAS -en pl -#end -.EE - -.ES -# POTFILES.in -a.cpp -b.cpp -# end -.EE - -.ES -# SConscript -env = Environment( tools = ["default", "gettext"] ) -env['POAUTOINIT'] = 1 -env['XGETTEXTPATH'] = ['../'] -env.Translate(LINGUAS_FILE = 1, XGETTEXTFROM = 'POTFILES.in') -.EE -.IP -The last approach is perhaps the recommended one. It allows easily split -internationalization/localization onto separate SCons scripts, where a script -in source tree is responsible for translations (from sources to -\fBPO\fP files) and script(s) under variant directories are -responsible for compilation of \fBPO\fP to \fBMO\fP -files to and for installation of \fBMO\fP files. The "gluing -factor" synchronizing these two scripts is then the content of -\fBLINGUAS\fP file. Note, that the updated -\fBPOT\fP and \fBPO\fP files are usually going to be -committed back to the repository, so they must be updated within the source -directory (and not in variant directories). Additionaly, the file listing of -\fBpo/\fP directory contains \fBLINGUAS\fP file, -so the source tree looks familiar to translators, and they may work with the -project in their usual way. - -.IR Example 3 . -Let's prepare a development tree as below -.ES - project/ - + SConstruct - + build/ - + src/ - + po/ - + SConscript - + SConscript.i18n - + POTFILES.in - + LINGUAS -.EE -with \fBbuild\fP being variant directory. Write the top-level -\fBSConstruct\fP script as follows -.ES - # SConstruct - env = Environment( tools = ["default", "gettext"] ) - VariantDir('build', 'src', duplicate = 0) - env['POAUTOINIT'] = 1 - SConscript('src/po/SConscript.i18n', exports = 'env') - SConscript('build/po/SConscript', exports = 'env') -.EE -the \fBsrc/po/SConscript.i18n\fP as -.ES - # src/po/SConscript.i18n - Import('env') - env.Translate(LINGUAS_FILE=1, XGETTEXTFROM='POTFILES.in', XGETTEXTPATH=['../']) -.EE -and the \fBsrc/po/SConscript\fP -.ES - # src/po/SConscript - Import('env') - env.MOFiles(LINGUAS_FILE = 1) -.EE -Such setup produces \fBPOT\fP and \fBPO\fP files -under source tree in \fBsrc/po/\fP and binary -\fBMO\fP files under variant tree in -\fBbuild/po/\fP. This way the \fBPOT\fP and -\fBPO\fP files are separated from other output files, which must -not be committed back to source repositories (e.g. \fBMO\fP -files). - -<note> -In above example, the \fBPO\fP files are not updated, -nor created automatically when you issue \fBscons '.'\fP command. -The files must be updated (created) by hand via \fBscons -po-update\fP and then \fBMO\fP files can be compiled by -running \fBscons '.'\fP.</para></note> - - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.IP TypeLibrary() -.IP env.TypeLibrary() -Builds a Windows type library (\fB.tlb\fP) -file from an input IDL file (\fB.idl\fP). -In addition, it will build the associated inteface stub and -proxy source files, -naming them according to the base name of the \fB.idl\fP file. -For example, - -.ES -env.TypeLibrary(source="foo.idl") -.EE -.IP -Will create \fBfoo.tlb\fP, -.BR foo.h , -.BR foo_i.c , -.B foo_p.c -and -.B foo_data.c -files. - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.IP Uic() -.IP env.Uic() -Builds a header file, an implementation file and a moc file from an ui file. -and returns the corresponding nodes in the above order. -This builder is only available after using the tool 'qt'. Note: you can -specify \fB.ui\fP files directly as source -files to the \fBProgram\fP(), -\fBLibrary\fP() and \fBSharedLibrary\fP() builders -without using this builder. Using this builder lets you override the standard -naming conventions (be careful: prefixes are always prepended to names of -built files; if you don't want prefixes, you may set them to ``). -See the \fB$QTDIR\fP variable for more information. -Example: - -.ES -env.Uic('foo.ui') # -> ['foo.h', 'uic_foo.cc', 'moc_foo.cc'] -env.Uic(target = Split('include/foo.h gen/uicfoo.cc gen/mocfoo.cc'), - source = 'foo.ui') # -> ['include/foo.h', 'gen/uicfoo.cc', 'gen/mocfoo.cc'] -.EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.IP Zip() -.IP env.Zip() -Builds a zip archive of the specified files -and/or directories. -Unlike most builder methods, -the -.BR Zip () -builder method may be called multiple times -for a given target; -each additional call -adds to the list of entries -that will be built into the archive. -Any source directories will -be scanned for changes to -any on-disk files, -regardless of whether or not -.B scons -knows about them from other Builder or function calls. - -.ES -env.Zip('src.zip', 'src') - -# Create the stuff.zip file. -env.Zip('stuff', ['subdir1', 'subdir2']) -# Also add "another" to the stuff.tar file. -env.Zip('stuff', 'another') -.EE -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -'\" END GENERATED BUILDER DESCRIPTIONS -'\" -'\" The descriptions above of the various SCons Builders are generated -'\" from the .xml files that live next to the various Python modules in -'\" the build enginer library. If you're reading this [gnt]roff file -'\" with an eye towards patching this man page, you can still submit -'\" a diff against this text, but it will have to be translated to a -'\" diff against the underlying .xml file before the patch is actually -'\" accepted. If you do that yourself, it will make it easier to -'\" integrate the patch. -'\" -'\" END GENERATED BUILDER DESCRIPTIONS -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" - -.P -All -targets of builder methods automatically depend on their sources. -An explicit dependency can -be specified using the -.B Depends -method of a construction environment (see below). - -In addition, -.B scons -automatically scans -source files for various programming languages, -so the dependencies do not need to be specified explicitly. -By default, SCons can -C source files, -C++ source files, -Fortran source files with -.B .F -(POSIX systems only), -.B .fpp, -or -.B .FPP -file extensions, -and assembly language files with -.B .S -(POSIX systems only), -.B .spp, -or -.B .SPP -files extensions -for C preprocessor dependencies. -SCons also has default support -for scanning D source files, -You can also write your own Scanners -to add support for additional source file types. -These can be added to the default -Scanner object used by the -.BR Object (), -.BR StaticObject (), -and -.BR SharedObject () -Builders by adding them -to the -.B SourceFileScanner -object. -See the section "Scanner Objects" -below, for more information about -defining your own Scanner objects -and using the -.B SourceFileScanner -object. - -.SS Methods and Functions to Do Things -In addition to Builder methods, -.B scons -provides a number of other construction environment methods -and global functions to -manipulate the build configuration. - -Usually, a construction environment method -and global function with the same name both exist -so that you don't have to remember whether -to a specific bit of functionality -must be called with or without a construction environment. -In the following list, -if you call something as a global function -it looks like: -.ES -.RI Function( arguments ) -.EE -and if you call something through a construction -environment it looks like: -.ES -.RI env.Function( arguments ) -.EE -If you can call the functionality in both ways, -then both forms are listed. - -Global functions may be called from custom Python modules that you -import into an SConscript file by adding the following -to the Python module: - -.ES -from SCons.Script import * -.EE - -Except where otherwise noted, -the same-named -construction environment method -and global function -provide the exact same functionality. -The only difference is that, -where appropriate, -calling the functionality through a construction environment will -substitute construction variables into -any supplied strings. -For example: - -.ES -env = Environment(FOO = 'foo') -Default('$FOO') -env.Default('$FOO') -.EE - -In the above example, -the first call to the global -.B Default() -function will actually add a target named -.B $FOO -to the list of default targets, -while the second call to the -.B env.Default() -construction environment method -will expand the value -and add a target named -.B foo -to the list of default targets. -For more on construction variable expansion, -see the next section on -construction variables. - -Construction environment methods -and global functions supported by -.B scons -include: - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -'\" BEGIN GENERATED FUNCTION DESCRIPTIONS -'\" -'\" The descriptions below of the various SCons functions are generated -'\" from the .xml files that live next to the various Python modules in -'\" the build enginer library. If you're reading this [gnt]roff file -'\" with an eye towards patching this man page, you can still submit -'\" a diff against this text, but it will have to be translated to a -'\" diff against the underlying .xml file before the patch is actually -'\" accepted. If you do that yourself, it will make it easier to -'\" integrate the patch. -'\" -'\" BEGIN GENERATED FUNCTION DESCRIPTIONS -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI Action( action ", [" cmd/str/fun ", [" var ", ...]] [option=" value ", ...])" -.TP -.IR env .Action( action ", [" cmd/str/fun ", [" var ", ...]] [option=" value ", ...])" -Creates an Action object for -the specified -.IR action . -See the section "Action Objects," -below, for a complete explanation of the arguments and behavior. - -Note that the -.BR env.Action () -form of the invocation will expand -construction variables in any argument strings, -including the -.I action -argument, at the time it is called -using the construction variables in the -.I env -construction environment through which -.BR env.Action () -was called. -The -.BR Action () -form delays all variable expansion -until the Action object is actually used. - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI AddMethod( object ", " function ", [" name ]) -.TP -.IR env .AddMethod( function ", [" name ]) -When called with the -.BR AddMethod () -form, -adds the specified -.I function -to the specified -.I object -as the specified method -.IR name . -When called with the -.BR env.AddMethod () -form, -adds the specified -.I function -to the construction environment -.I env -as the specified method -.IR name . -In both cases, if -.I name -is omitted or -.BR None , -the name of the -specified -.I function -itself is used for the method name. - -Examples: - -.ES -# Note that the first argument to the function to -# be attached as a method must be the object through -# which the method will be called; the Python -# convention is to call it 'self'. -def my_method(self, arg): - print "my_method() got", arg - -# Use the global AddMethod() function to add a method -# to the Environment class. This -AddMethod(Environment, my_method) -env = Environment() -env.my_method('arg') - -# Add the function as a method, using the function -# name for the method call. -env = Environment() -env.AddMethod(my_method, 'other_method_name') -env.other_method_name('another arg') -.EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI AddOption( arguments ) -This function adds a new command-line option to be recognized. -The specified -.I arguments -are the same as supported by the standard Python -.BR optparse.add_option () -method (with a few additional capabilities noted below); -see the documentation for -.B optparse -for a thorough discussion of its option-processing capabities. - -In addition to the arguments and values supported by the -.BR optparse.add_option () -method, -the SCons -.BR AddOption () -function allows you to set the -.B nargs -keyword value to -.B '?' -(a string with just the question mark) -to indicate that the specified long option(s) take(s) an -.I optional -argument. -When -.B "nargs = '?'" -is passed to the -.BR AddOption () -function, the -.B const -keyword argument -may be used to supply the "default" -value that should be used when the -option is specified on the command line -without an explicit argument. - -If no -.B default= -keyword argument is supplied when calling -.BR AddOption (), -the option will have a default value of -.BR None . - -Once a new command-line option has been added with -.BR AddOption (), -the option value may be accessed using -.BR GetOption () -or -.BR env.GetOption (). -The value may also be set, using -.BR SetOption () -or -.BR env.SetOption (), -if conditions in a -.B SConscript -require overriding any default value. -Note, however, that a -value specified on the command line will -.I always -override a value set by any SConscript file. - -Any specified -.B help= -strings for the new option(s) -will be displayed by the -.B \-H -or -.B \-h -options -(the latter only if no other help text is -specified in the SConscript files). -The help text for the local options specified by -.BR AddOption () -will appear below the SCons options themselves, -under a separate -.B "Local Options" -heading. -The options will appear in the help text -in the order in which the -.BR AddOption () -calls occur. - -Example: - -.ES -AddOption('--prefix', - dest='prefix', - nargs=1, type='string', - action='store', - metavar='DIR', - help='installation prefix') -env = Environment(PREFIX = GetOption('prefix')) -.EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI AddPostAction( target ", " action ) -.TP -.IR env .AddPostAction( target ", " action ) -Arranges for the specified -.I action -to be performed -after the specified -.I target -has been built. -The specified action(s) may be -an Action object, or anything that -can be converted into an Action object -(see below). - -When multiple targets are supplied, -the action may be called multiple times, -once after each action that generates -one or more targets in the list. - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI AddPreAction( target ", " action ) -.TP -.IR env .AddPreAction( target ", " action ) -Arranges for the specified -.I action -to be performed -before the specified -.I target -is built. -The specified action(s) may be -an Action object, or anything that -can be converted into an Action object -(see below). - -When multiple targets are specified, -the action(s) may be called multiple times, -once before each action that generates -one or more targets in the list. - -Note that if any of the targets are built in multiple steps, -the action will be invoked just -before the "final" action that specifically -generates the specified target(s). -For example, when building an executable program -from a specified source -.B .c -file via an intermediate object file: - -.ES -foo = Program('foo.c') -AddPreAction(foo, 'pre_action') -.EE -.IP -The specified -.B pre_action -would be executed before -.B scons -calls the link command that actually -generates the executable program binary -.BR foo , -not before compiling the -.B foo.c -file into an object file. - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI Alias( alias ", [" targets ", [" action ]]) -.TP -.IR env .Alias( alias ", [" targets ", [" action ]]) -Creates one or more phony targets that -expand to one or more other targets. -An optional -.I action -(command) -or list of actions -can be specified that will be executed -whenever the any of the alias targets are out-of-date. -Returns the Node object representing the alias, -which exists outside of any file system. -This Node object, or the alias name, -may be used as a dependency of any other target, -including another alias. -.BR Alias () -can be called multiple times for the same -alias to add additional targets to the alias, -or additional actions to the list for this alias. - -Examples: - -.ES -Alias('install') -Alias('install', '/usr/bin') -Alias(['install', 'install-lib'], '/usr/local/lib') - -env.Alias('install', ['/usr/local/bin', '/usr/local/lib']) -env.Alias('install', ['/usr/local/man']) - -env.Alias('update', ['file1', 'file2'], "update_database $SOURCES") -.EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI AllowSubstExceptions([ exception ", ...])" -Specifies the exceptions that will be allowed -when expanding construction variables. -By default, -any construction variable expansions that generate a -.B NameError -or -.B IndexError -exception will expand to a -.B '' -(a null string) and not cause scons to fail. -All exceptions not in the specified list -will generate an error message -and terminate processing. - -If -.BR AllowSubstExceptions () -is called multiple times, -each call completely overwrites the previous list -of allowed exceptions. - -Example: - -.ES -# Requires that all construction variable names exist. -# (You may wish to do this if you want to enforce strictly -# that all construction variables must be defined before use.) -AllowSubstExceptions() - -# Also allow a string containing a zero-division expansion -# like '${1 / 0}' to evalute to ''. -AllowSubstExceptions(IndexError, NameError, ZeroDivisionError) -.EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI AlwaysBuild( target ", ...)" -.TP -.IR env .AlwaysBuild( target ", ...)" -Marks each given -.I target -so that it is always assumed to be out of date, -and will always be rebuilt if needed. -Note, however, that -.BR AlwaysBuild () -does not add its target(s) to the default target list, -so the targets will only be built -if they are specified on the command line, -or are a dependent of a target specified on the command line--but -they will -.I always -be built if so specified. -Multiple targets can be passed in to a single call to -.BR AlwaysBuild (). - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.IR env .Append(key= val ", [...])" -Appends the specified keyword arguments -to the end of construction variables in the environment. -If the Environment does not have -the specified construction variable, -it is simply added to the environment. -If the values of the construction variable -and the keyword argument are the same type, -then the two values will be simply added together. -Otherwise, the construction variable -and the value of the keyword argument -are both coerced to lists, -and the lists are added together. -(See also the Prepend method, below.) - -Example: - -.ES -env.Append(CCFLAGS = ' -g', FOO = ['foo.yyy']) -.EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.IR env .AppendENVPath( name ", " newpath ", [" envname ", " sep ", " delete_existing ]) -This appends new path elements to the given path in the -specified external environment -.RB ( ENV -by default). -This will only add -any particular path once (leaving the last one it encounters and -ignoring the rest, to preserve path order), -and to help assure this, -will normalize all paths (using -.B os.path.normpath -and -.BR os.path.normcase ). -This can also handle the -case where the given old path variable is a list instead of a -string, in which case a list will be returned instead of a string. - -If -.I delete_existing -is 0, then adding a path that already exists -will not move it to the end; it will stay where it is in the list. - -Example: - -.ES -print 'before:',env['ENV']['INCLUDE'] -include_path = '/foo/bar:/foo' -env.AppendENVPath('INCLUDE', include_path) -print 'after:',env['ENV']['INCLUDE'] - -yields: -before: /foo:/biz -after: /biz:/foo/bar:/foo -.EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.IR env .AppendUnique(key= val ", [...], delete_existing=" 0) -Appends the specified keyword arguments -to the end of construction variables in the environment. -If the Environment does not have -the specified construction variable, -it is simply added to the environment. -If the construction variable being appended to is a list, -then any value(s) that already exist in the -construction variable will -.I not -be added again to the list. -However, if delete_existing is 1, -existing matching values are removed first, so -existing values in the arg list move to the end of the list. - -Example: - -.ES -env.AppendUnique(CCFLAGS = '-g', FOO = ['foo.yyy']) -.EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.IR env .BitKeeper() -A factory function that -returns a Builder object -to be used to fetch source files -using BitKeeper. -The returned Builder -is intended to be passed to the -.BR SourceCode () -function. - -This function is deprecated. For details, see the entry for the -.BR SourceCode () -function. - -Example: - -.ES -env.SourceCode('.', env.BitKeeper()) -.EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI BuildDir( build_dir ", " src_dir ", [" duplicate ]) -.TP -.IR env .BuildDir( build_dir ", " src_dir ", [" duplicate ]) -Deprecated synonyms for -.BR VariantDir () -and -.BR env.VariantDir (). -The -.I build_dir -argument becomes the -.I variant_dir -argument of -.BR VariantDir () -or -.BR env.VariantDir (). - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI Builder( action ", [" arguments ]) -.TP -.IR env .Builder( action ", [" arguments ]) -Creates a Builder object for -the specified -.IR action . -See the section "Builder Objects," -below, for a complete explanation of the arguments and behavior. - -Note that the -.BR env.Builder () -form of the invocation will expand -construction variables in any arguments strings, -including the -.I action -argument, -at the time it is called -using the construction variables in the -.I env -construction environment through which -.BR env.Builder () -was called. -The -.BR Builder () -form delays all variable expansion -until after the Builder object is actually called. - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI CacheDir( cache_dir ) -.TP -.IR env .CacheDir( cache_dir ) -Specifies that -.B scons -will maintain a cache of derived files in -.IR cache_dir . -The derived files in the cache will be shared -among all the builds using the same -.BR CacheDir () -call. -Specifying a -.I cache_dir -of -.B None -disables derived file caching. - -Calling -.BR env.CacheDir () -will only affect targets built -through the specified construction environment. -Calling -.BR CacheDir () -sets a global default -that will be used by all targets built -through construction environments -that do -.I not -have an -.BR env.CacheDir () -specified. - -When a -.BR CacheDir () -is being used and -.B scons -finds a derived file that needs to be rebuilt, -it will first look in the cache to see if a -derived file has already been built -from identical input files and an identical build action -(as incorporated into the MD5 build signature). -If so, -.B scons -will retrieve the file from the cache. -If the derived file is not present in the cache, -.B scons -will rebuild it and -then place a copy of the built file in the cache -(identified by its MD5 build signature), -so that it may be retrieved by other -builds that need to build the same derived file -from identical inputs. - -Use of a specified -.BR CacheDir () -may be disabled for any invocation -by using the -.B \-\-cache-disable -option. - -If the -.B \-\-cache-force -option is used, -.B scons -will place a copy of -.I all -derived files in the cache, -even if they already existed -and were not built by this invocation. -This is useful to populate a cache -the first time -.BR CacheDir () -is added to a build, -or after using the -.B \-\-cache-disable -option. - -When using -.BR CacheDir (), -.B scons -will report, -"Retrieved `file' from cache," -unless the -.B \-\-cache-show -option is being used. -When the -.B \-\-cache-show -option is used, -.B scons -will print the action that -.I would -have been used to build the file, -without any indication that -the file was actually retrieved from the cache. -This is useful to generate build logs -that are equivalent regardless of whether -a given derived file has been built in-place -or retrieved from the cache. - -The -.BR NoCache () -method can be used to disable caching of specific files. This can be -useful if inputs and/or outputs of some tool are impossible to -predict or prohibitively large. - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI Clean( targets ", " files_or_dirs ) -.TP -.IR env .Clean( targets ", " files_or_dirs ) -This specifies a list of files or directories which should be removed -whenever the targets are specified with the -.B \-c -command line option. -The specified targets may be a list -or an individual target. -Multiple calls to -.BR Clean () -are legal, -and create new targets or add files and directories to the -clean list for the specified targets. - -Multiple files or directories should be specified -either as separate arguments to the -.BR Clean () -method, or as a list. -.BR Clean () -will also accept the return value of any of the construction environment -Builder methods. -Examples: - -The related -.BR NoClean () -function overrides calling -.BR Clean () -for the same target, -and any targets passed to both functions will -.I not -be removed by the -.B \-c -option. - -Examples: - -.ES -Clean('foo', ['bar', 'baz']) -Clean('dist', env.Program('hello', 'hello.c')) -Clean(['foo', 'bar'], 'something_else_to_clean') -.EE -.IP -In this example, -installing the project creates a subdirectory for the documentation. -This statement causes the subdirectory to be removed -if the project is deinstalled. -.ES -Clean(docdir, os.path.join(docdir, projectname)) -.EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.IR env .Clone([key= val ", ...])" -Returns a separate copy of a construction environment. -If there are any keyword arguments specified, -they are added to the returned copy, -overwriting any existing values -for the keywords. - -Example: - -.ES -env2 = env.Clone() -env3 = env.Clone(CCFLAGS = '-g') -.EE -.IP -Additionally, a list of tools and a toolpath may be specified, as in -the Environment constructor: - -.ES -def MyTool(env): env['FOO'] = 'bar' -env4 = env.Clone(tools = ['msvc', MyTool]) -.EE -.IP -The -.I parse_flags -keyword argument is also recognized: - -.ES -# create an environment for compiling programs that use wxWidgets -wx_env = env.Clone(parse_flags = '!wx-config --cflags --cxxflags') -.EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI Command( target ", " source ", " action ", [key=" val ", ...])" -.TP -.IR env .Command( target ", " source ", " action ", [key=" val ", ...])" -Executes a specific action -(or list of actions) -to build a target file or files. -This is more convenient -than defining a separate Builder object -for a single special-case build. - -As a special case, the -.I source_scanner -keyword argument can -be used to specify -a Scanner object -that will be used to scan the sources. -(The global -.B DirScanner -object can be used -if any of the sources will be directories -that must be scanned on-disk for -changes to files that aren't -already specified in other Builder of function calls.) - -Any other keyword arguments specified override any -same-named existing construction variables. - -An action can be an external command, -specified as a string, -or a callable Python object; -see "Action Objects," below, -for more complete information. -Also note that a string specifying an external command -may be preceded by an -.B @ -(at-sign) -to suppress printing the command in question, -or by a -.B \- -(hyphen) -to ignore the exit status of the external command. - -Examples: - -.ES -env.Command('foo.out', 'foo.in', - "$FOO_BUILD < $SOURCES > $TARGET") - -env.Command('bar.out', 'bar.in', - ["rm -f $TARGET", - "$BAR_BUILD < $SOURCES > $TARGET"], - ENV = {'PATH' : '/usr/local/bin/'}) - -def rename(env, target, source): - import os - os.rename('.tmp', str(target[0])) - -env.Command('baz.out', 'baz.in', - ["$BAZ_BUILD < $SOURCES > .tmp", - rename ]) -.EE -.IP -Note that the -.BR Command () -function will usually assume, by default, -that the specified targets and/or sources are Files, -if no other part of the configuration -identifies what type of entry it is. -If necessary, you can explicitly specify -that targets or source nodes should -be treated as directoriese -by using the -.BR Dir () -or -.BR env.Dir () -functions. - -Examples: - -.ES -env.Command('ddd.list', Dir('ddd'), 'ls -l $SOURCE > $TARGET') - -env['DISTDIR'] = 'destination/directory' -env.Command(env.Dir('$DISTDIR')), None, make_distdir) -.EE -.IP -(Also note that SCons will usually -automatically create any directory necessary to hold a target file, -so you normally don't need to create directories by hand.) - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI Configure( env ", [" custom_tests ", " conf_dir ", " log_file ", " config_h ]) -.TP -.IR env .Configure([ custom_tests ", " conf_dir ", " log_file ", " config_h ]) -Creates a Configure object for integrated -functionality similar to GNU autoconf. -See the section "Configure Contexts," -below, for a complete explanation of the arguments and behavior. - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.IR env .Copy([key= val ", ...])" -A now-deprecated synonym for -.BR env.Clone (). - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.IR env .CVS( repository ", " module ) -A factory function that -returns a Builder object -to be used to fetch source files -from the specified -CVS -.IR repository . -The returned Builder -is intended to be passed to the -.BR SourceCode () -function. - -This function is deprecated. For details, see the entry for the -.BR SourceCode () -function. - -The optional specified -.I module -will be added to the beginning -of all repository path names; -this can be used, in essence, -to strip initial directory names -from the repository path names, -so that you only have to -replicate part of the repository -directory hierarchy in your -local build directory. - -Examples: - -.ES -# Will fetch foo/bar/src.c -# from /usr/local/CVSROOT/foo/bar/src.c. -env.SourceCode('.', env.CVS('/usr/local/CVSROOT')) - -# Will fetch bar/src.c -# from /usr/local/CVSROOT/foo/bar/src.c. -env.SourceCode('.', env.CVS('/usr/local/CVSROOT', 'foo')) - -# Will fetch src.c -# from /usr/local/CVSROOT/foo/bar/src.c. -env.SourceCode('.', env.CVS('/usr/local/CVSROOT', 'foo/bar')) -.EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI Decider( function ) -.TP -.IR env .Decider( function ) -Specifies that all up-to-date decisions for -targets built through this construction environment -will be handled by the specified -.IR function . -The -.I function -can be one of the following strings -that specify the type of decision function -to be performed: - -.RS 10 -.TP 6 -.B timestamp-newer -Specifies that a target shall be considered out of date and rebuilt -if the dependency's timestamp is newer than the target file's timestamp. -This is the behavior of the classic Make utility, -and -.B make -can be used a synonym for -.BR timestamp-newer . -.TP 6 -.B timestamp-match -Specifies that a target shall be considered out of date and rebuilt -if the dependency's timestamp is different than the -timestamp recorded the last time the target was built. -This provides behavior very similar to the classic Make utility -(in particular, files are not opened up so that their -contents can be checksummed) -except that the target will also be rebuilt if a -dependency file has been restored to a version with an -.I earlier -timestamp, such as can happen when restoring files from backup archives. -.TP 6 -.B MD5 -Specifies that a target shall be considered out of date and rebuilt -if the dependency's content has changed sine the last time -the target was built, -as determined be performing an MD5 checksum -on the dependency's contents -and comparing it to the checksum recorded the -last time the target was built. -.B content -can be used as a synonym for -.BR MD5 . -.TP 6 -.B MD5-timestamp -Specifies that a target shall be considered out of date and rebuilt -if the dependency's content has changed sine the last time -the target was built, -except that dependencies with a timestamp that matches -the last time the target was rebuilt will be -assumed to be up-to-date and -.I not -rebuilt. -This provides behavior very similar -to the -.B MD5 -behavior of always checksumming file contents, -with an optimization of not checking -the contents of files whose timestamps haven't changed. -The drawback is that SCons will -.I not -detect if a file's content has changed -but its timestamp is the same, -as might happen in an automated script -that runs a build, -updates a file, -and runs the build again, -all within a single second. -.RE - -Examples: - -.ES -# Use exact timestamp matches by default. -Decider('timestamp-match') - -# Use MD5 content signatures for any targets built -# with the attached construction environment. -env.Decider('content') -.EE -.IP -In addition to the above already-available functions, -the -.I function -argument may be an actual Python function -that takes the following three arguments: - -.RS 10 -.IP dependency -The Node (file) which -should cause the -.I target -to be rebuilt -if it has "changed" since the last tme -.I target -was built. -.IP target -The Node (file) being built. -In the normal case, -this is what should get rebuilt -if the -.I dependency -has "changed." -.IP prev_ni -Stored information about the state of the -.I dependency -the last time the -.I target -was built. -This can be consulted to match various -file characteristics -such as the timestamp, -size, or content signature. -.RE - -The -.I function -should return a -.B True -(non-zero) -value if the -.I dependency -has "changed" since the last time -the -.I target -was built -(indicating that the target -.I should -be rebuilt), -and -.B False -(zero) -otherwise -(indicating that the target should -.I not -be rebuilt). -Note that the decision can be made -using whatever criteria are appopriate. -Ignoring some or all of the function arguments -is perfectly normal. - -Example: - -.ES -def my_decider(dependency, target, prev_ni): - return not os.path.exists(str(target)) - -env.Decider(my_decider) -.EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI Default( targets ) -.TP -.IR env .Default( targets ) -This specifies a list of default targets, -which will be built by -.B scons -if no explicit targets are given on the command line. -Multiple calls to -.BR Default () -are legal, -and add to the list of default targets. - -Multiple targets should be specified as -separate arguments to the -.BR Default () -method, or as a list. -.BR Default () -will also accept the Node returned by any -of a construction environment's -builder methods. - -Examples: - -.ES -Default('foo', 'bar', 'baz') -env.Default(['a', 'b', 'c']) -hello = env.Program('hello', 'hello.c') -env.Default(hello) -.EE -.IP -An argument to -.BR Default () -of -.B None -will clear all default targets. -Later calls to -.BR Default () -will add to the (now empty) default-target list -like normal. - -The current list of targets added using the -.BR Default () -function or method is available in the -.B DEFAULT_TARGETS -list; -see below. - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI DefaultEnvironment([ args ]) -Creates and returns a default construction environment object. -This construction environment is used internally by SCons -in order to execute many of the global functions in this list, -and to fetch source files transparently -from source code management systems. - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI Depends( target ", " dependency ) -.TP -.IR env .Depends( target ", " dependency ) -Specifies an explicit dependency; -the -.I target -will be rebuilt -whenever the -.I dependency -has changed. -Both the specified -.I target -and -.I dependency -can be a string -(usually the path name of a file or directory) -or Node objects, -or a list of strings or Node objects -(such as returned by a Builder call). -This should only be necessary -for cases where the dependency -is not caught by a Scanner -for the file. - -Example: - -.ES -env.Depends('foo', 'other-input-file-for-foo') - -mylib = env.Library('mylib.c') -installed_lib = env.Install('lib', mylib) -bar = env.Program('bar.c') - -# Arrange for the library to be copied into the installation -# directory before trying to build the "bar" program. -# (Note that this is for example only. A "real" library -# dependency would normally be configured through the $LIBS -# and $LIBPATH variables, not using an env.Depends() call.) - -env.Depends(bar, installed_lib) -.EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.IR env .Dictionary([ vars ]) -Returns a dictionary object -containing copies of all of the -construction variables in the environment. -If there are any variable names specified, -only the specified construction -variables are returned in the dictionary. - -Example: - -.ES -dict = env.Dictionary() -cc_dict = env.Dictionary('CC', 'CCFLAGS', 'CCCOM') -.EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI Dir( name ", [" directory ]) -.TP -.IR env .Dir( name ", [" directory ]) -This returns a Directory Node, -an object that represents the specified directory -.IR name . -.I name -can be a relative or absolute path. -.I directory -is an optional directory that will be used as the parent directory. -If no -.I directory -is specified, the current script's directory is used as the parent. - -If -.I name -is a list, SCons returns a list of Dir nodes. -Construction variables are expanded in -.IR name . - -Directory Nodes can be used anywhere you -would supply a string as a directory name -to a Builder method or function. -Directory Nodes have attributes and methods -that are useful in many situations; -see "File and Directory Nodes," below. - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.IR env .Dump([ key ]) -Returns a pretty printable representation of the environment. -.IR key , -if not -.BR None , -should be a string containing the name of the variable of interest. - -This SConstruct: - -.ES -env=Environment() -print env.Dump('CCCOM') -.EE -.IP -will print: - -.ES -'$CC -c -o $TARGET $CCFLAGS $CPPFLAGS $_CPPDEFFLAGS $_CPPINCFLAGS $SOURCES' -.EE -.IP -While this SConstruct: - -.ES -env=Environment() -print env.Dump() -.EE -.IP -will print: -.ES -{ 'AR': 'ar', - 'ARCOM': '$AR $ARFLAGS $TARGET $SOURCES\\n$RANLIB $RANLIBFLAGS $TARGET', - 'ARFLAGS': ['r'], - 'AS': 'as', - 'ASCOM': '$AS $ASFLAGS -o $TARGET $SOURCES', - 'ASFLAGS': [], - ... -.EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI EnsurePythonVersion( major ", " minor ) -.TP -.IR env .EnsurePythonVersion( major ", " minor ) -Ensure that the Python version is at least -.IR major\fP.\fIminor . -This function will -print out an error message and exit SCons with a non-zero exit code if the -actual Python version is not late enough. - -Example: - -.ES -EnsurePythonVersion(2,2) -.EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI EnsureSConsVersion( major ", " minor ", [" revision ]) -.TP -.IR env .EnsureSConsVersion( major ", " minor ", [" revision ]) -Ensure that the SCons version is at least -.IR major.minor , -or -.IR major.minor.revision . -if -.I revision -is specified. -This function will -print out an error message and exit SCons with a non-zero exit code if the -actual SCons version is not late enough. - -Examples: - -.ES -EnsureSConsVersion(0,14) - -EnsureSConsVersion(0,96,90) -.EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI Environment([key= value ", ...])" -.TP -.IR env .Environment([key= value ", ...])" -Return a new construction environment -initialized with the specified -.IR key = value -pairs. - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI Execute( action ", [" strfunction ", " varlist ]) -.TP -.IR env .Execute( action ", [" strfunction ", " varlist ]) -Executes an Action object. -The specified -.I action -may be an Action object -(see the section "Action Objects," -below, for a complete explanation of the arguments and behavior), -or it may be a command-line string, -list of commands, -or executable Python function, -each of which will be converted -into an Action object -and then executed. -The exit value of the command -or return value of the Python function -will be returned. - -Note that -.B scons -will print an error message if the executed -.I action -fails--that is, -exits with or returns a non-zero value. -.B scons -will -.IR not , -however, -automatically terminate the build -if the specified -.I action -fails. -If you want the build to stop in response to a failed -.BR Execute () -call, -you must explicitly check for a non-zero return value: - -.ES -Execute(Copy('file.out', 'file.in')) - -if Execute("mkdir sub/dir/ectory"): - # The mkdir failed, don't try to build. - Exit(1) -.EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI Exit([ value ]) -.TP -.IR env .Exit([ value ]) -This tells -.B scons -to exit immediately -with the specified -.IR value . -A default exit value of -.B 0 -(zero) -is used if no value is specified. - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI Export( vars ) -.TP -.IR env .Export( vars ) -This tells -.B scons -to export a list of variables from the current -SConscript file to all other SConscript files. -The exported variables are kept in a global collection, -so subsequent calls to -.BR Export () -will over-write previous exports that have the same name. -Multiple variable names can be passed to -.BR Export () -as separate arguments or as a list. -Keyword arguments can be used to provide names and their values. -A dictionary can be used to map variables to a different name when exported. -Both local variables and global variables can be exported. - -Examples: - -.ES -env = Environment() -# Make env available for all SConscript files to Import(). -Export("env") - -package = 'my_name' -# Make env and package available for all SConscript files:. -Export("env", "package") - -# Make env and package available for all SConscript files: -Export(["env", "package"]) - -# Make env available using the name debug: -Export(debug = env) - -# Make env available using the name debug: -Export({"debug":env}) -.EE -.IP -Note that the -.BR SConscript () -function supports an -.I exports -argument that makes it easier to to export a variable or -set of variables to a single SConscript file. -See the description of the -.BR SConscript () -function, below. - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI File( name ", [" directory ]) -.TP -.IR env .File( name ", [" directory ]) -This returns a -File Node, -an object that represents the specified file -.IR name . -.I name -can be a relative or absolute path. -.I directory -is an optional directory that will be used as the parent directory. - -If -.I name -is a list, SCons returns a list of File nodes. -Construction variables are expanded in -.IR name . - -File Nodes can be used anywhere you -would supply a string as a file name -to a Builder method or function. -File Nodes have attributes and methods -that are useful in many situations; -see "File and Directory Nodes," below. - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI FindFile( file ", " dirs ) -.TP -.IR env .FindFile( file ", " dirs ) -Search for -.I file -in the path specified by -.IR dirs . -.I dirs -may be a list of directory names or a single directory name. -In addition to searching for files that exist in the filesystem, -this function also searches for derived files -that have not yet been built. - -Example: - -.ES -foo = env.FindFile('foo', ['dir1', 'dir2']) -.EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI FindInstalledFiles() -.TP -.IR env .FindInstalledFiles() -Returns the list of targets set up by the -.BR Install () -or -.BR InstallAs () -builders. - -This function serves as a convenient method to select the contents of -a binary package. - -Example: - -.ES -Install( '/bin', [ 'executable_a', 'executable_b' ] ) - -# will return the file node list -# [ '/bin/executable_a', '/bin/executable_b' ] -FindInstalledFiles() - -Install( '/lib', [ 'some_library' ] ) - -# will return the file node list -# [ '/bin/executable_a', '/bin/executable_b', '/lib/some_library' ] -FindInstalledFiles() -.EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI FindPathDirs( variable ) -Returns a function -(actually a callable Python object) -intended to be used as the -.I path_function -of a Scanner object. -The returned object will look up the specified -.I variable -in a construction environment -and treat the construction variable's value as a list of -directory paths that should be searched -(like -.BR $CPPPATH , -.BR $LIBPATH , -etc.). - -Note that use of -.BR FindPathDirs () -is generally preferable to -writing your own -.I path_function -for the following reasons: -1) The returned list will contain all appropriate directories -found in source trees -(when -.BR VariantDir () -is used) -or in code repositories -(when -.BR Repository () -or the -.B \-Y -option are used). -2) scons will identify expansions of -.I variable -that evaluate to the same list of directories as, -in fact, the same list, -and avoid re-scanning the directories for files, -when possible. - -Example: - -.ES -def my_scan(node, env, path, arg): - # Code to scan file contents goes here... - return include_files - -scanner = Scanner(name = 'myscanner', - function = my_scan, - path_function = FindPathDirs('MYPATH')) -.EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI FindSourceFiles(node= '"."') -.TP -.IR env .FindSourceFiles(node= '"."') -Returns the list of nodes which serve as the source of the built files. -It does so by inspecting the dependency tree starting at the optional -argument -.I node -which defaults to the '"."'-node. It will then return all leaves of -.IR node . -These are all children which have no further children. - -This function is a convenient method to select the contents of a Source -Package. - -Example: - -.ES -Program( 'src/main_a.c' ) -Program( 'src/main_b.c' ) -Program( 'main_c.c' ) - -# returns ['main_c.c', 'src/main_a.c', 'SConstruct', 'src/main_b.c'] -FindSourceFiles() - -# returns ['src/main_b.c', 'src/main_a.c' ] -FindSourceFiles( 'src' ) -.EE -.IP -As you can see build support files (SConstruct in the above example) -will also be returned by this function. - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI Flatten( sequence ) -.TP -.IR env .Flatten( sequence ) -Takes a sequence (that is, a Python list or tuple) -that may contain nested sequences -and returns a flattened list containing -all of the individual elements in any sequence. -This can be helpful for collecting -the lists returned by calls to Builders; -other Builders will automatically -flatten lists specified as input, -but direct Python manipulation of -these lists does not. - -Examples: - -.ES -foo = Object('foo.c') -bar = Object('bar.c') - -# Because `foo' and `bar' are lists returned by the Object() Builder, -# `objects' will be a list containing nested lists: -objects = ['f1.o', foo, 'f2.o', bar, 'f3.o'] - -# Passing such a list to another Builder is all right because -# the Builder will flatten the list automatically: -Program(source = objects) - -# If you need to manipulate the list directly using Python, you need to -# call Flatten() yourself, or otherwise handle nested lists: -for object in Flatten(objects): - print str(object) -.EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI GetBuildFailures() -Returns a list of exceptions for the -actions that failed while -attempting to build targets. -Each element in the returned list is a -.I BuildError -object -with the following attributes -that record various aspects -of the build failure: - -.B .node -The node that was being built -when the build failure occurred. - -.B .status -The numeric exit status -returned by the command or Python function -that failed when trying to build the -specified Node. - -.B .errstr -The SCons error string -describing the build failure. -(This is often a generic -message like "Error 2" -to indicate that an executed -command exited with a status of 2.) - -.B .filename -The name of the file or -directory that actually caused the failure. -This may be different from the -.B .node -attribute. -For example, -if an attempt to build a target named -.B sub/dir/target -fails because the -.B sub/dir -directory could not be created, -then the -.B .node -attribute will be -.B sub/dir/target -but the -.B .filename -attribute will be -.BR sub/dir . - -.B .executor -The SCons Executor object -for the target Node -being built. -This can be used to retrieve -the construction environment used -for the failed action. - -.B .action -The actual SCons Action object that failed. -This will be one specific action -out of the possible list of -actions that would have been -executed to build the target. - -.B .command -The actual expanded command that was executed and failed, -after expansion of -.BR $TARGET , -.BR $SOURCE , -and other construction variables. - -Note that the -.BR GetBuildFailures () -function -will always return an empty list -until any build failure has occurred, -which means that -.BR GetBuildFailures () -will always return an empty list -while the -.B SConscript -files are being read. -Its primary intended use is -for functions that will be -executed before SCons exits -by passing them to the -standard Python -.BR atexit.register () -function. -Example: - -.ES -import atexit - -def print_build_failures(): - from SCons.Script import GetBuildFailures - for bf in GetBuildFailures(): - print "%s failed: %s" % (bf.node, bf.errstr) - -atexit.register(print_build_failures) -.EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI GetBuildPath( file ", [...])" -.TP -.IR env .GetBuildPath( file ", [...])" -Returns the -.B scons -path name (or names) for the specified -.I file -(or files). -The specified -.I file -or files -may be -.B scons -Nodes or strings representing path names. - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI GetLaunchDir() -.TP -.IR env .GetLaunchDir() -Returns the absolute path name of the directory from which -.B scons -was initially invoked. -This can be useful when using the -.BR \-u , -.B \-U -or -.B \-D -options, which internally -change to the directory in which the -.B SConstruct -file is found. - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI GetOption( name ) -.TP -.IR env .GetOption( name ) -This function provides a way to query the value of -SCons options set on scons command line -(or set using the -.BR SetOption () -function). -The options supported are: - -.RS 10 -.TP 6 -.B cache_debug -which corresponds to --cache-debug; -.TP 6 -.B cache_disable -which corresponds to --cache-disable; -.TP 6 -.B cache_force -which corresponds to --cache-force; -.TP 6 -.B cache_show -which corresponds to --cache-show; -.TP 6 -.B clean -which corresponds to -c, --clean and --remove; -.TP 6 -.B config -which corresponds to --config; -.TP 6 -.B directory -which corresponds to -C and --directory; -.TP 6 -.B diskcheck -which corresponds to --diskcheck -.TP 6 -.B duplicate -which corresponds to --duplicate; -.TP 6 -.B file -which corresponds to -f, --file, --makefile and --sconstruct; -.TP 6 -.B help -which corresponds to -h and --help; -.TP 6 -.B ignore_errors -which corresponds to --ignore-errors; -.TP 6 -.B implicit_cache -which corresponds to --implicit-cache; -.TP 6 -.B implicit_deps_changed -which corresponds to --implicit-deps-changed; -.TP 6 -.B implicit_deps_unchanged -which corresponds to --implicit-deps-unchanged; -.TP 6 -.B interactive -which corresponds to --interact and --interactive; -.TP 6 -.B keep_going -which corresponds to -k and --keep-going; -.TP 6 -.B max_drift -which corresponds to --max-drift; -.TP 6 -.B no_exec -which corresponds to -n, --no-exec, --just-print, --dry-run and --recon; -.TP 6 -.B no_site_dir -which corresponds to --no-site-dir; -.TP 6 -.B num_jobs -which corresponds to -j and --jobs; -.TP 6 -.B profile_file -which corresponds to --profile; -.TP 6 -.B question -which corresponds to -q and --question; -.TP 6 -.B random -which corresponds to --random; -.TP 6 -.B repository -which corresponds to -Y, --repository and --srcdir; -.TP 6 -.B silent -which corresponds to -s, --silent and --quiet; -.TP 6 -.B site_dir -which corresponds to --site-dir; -.TP 6 -.B stack_size -which corresponds to --stack-size; -.TP 6 -.B taskmastertrace_file -which corresponds to --taskmastertrace; and -.TP 6 -.B warn -which corresponds to --warn and --warning. -.RE - -See the documentation for the -corresponding command line object for information about each specific -option. - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI Glob( pattern ", [" ondisk ", " source ", " strings ]) -.TP -.IR env .Glob( pattern ", [" ondisk ", " source ", " strings ]) -Returns Nodes (or strings) that match the specified -.IR pattern , -relative to the directory of the current -.B SConscript -file. -The -.BR env.Glob () -form performs string substition on -.I pattern -and returns whatever matches -the resulting expanded pattern. - -The specified -.I pattern -uses Unix shell style metacharacters for matching: - -.ES - * matches everything - ? matches any single character - [seq] matches any character in seq - [!seq] matches any char not in seq -.EE -.IP -If the first character of a filename is a dot, -it must be matched explicitly. -Character matches do -.I not -span directory separators. - -The -.BR Glob () -knows about -repositories -(see the -.BR Repository () -function) -and source directories -(see the -.BR VariantDir () -function) -and -returns a Node (or string, if so configured) -in the local (SConscript) directory -if matching Node is found -anywhere in a corresponding -repository or source directory. - -The -.I ondisk -argument may be set to -.B False -(or any other non-true value) -to disable the search for matches on disk, -thereby only returning matches among -already-configured File or Dir Nodes. -The default behavior is to -return corresponding Nodes -for any on-disk matches found. - -The -.I source -argument may be set to -.B True -(or any equivalent value) -to specify that, -when the local directory is a -.BR VariantDir (), -the returned Nodes should be from the -corresponding source directory, -not the local directory. - -The -.I strings -argument may be set to -.B True -(or any equivalent value) -to have the -.BR Glob () -function return strings, not Nodes, -that represent the matched files or directories. -The returned strings will be relative to -the local (SConscript) directory. -(Note that This may make it easier to perform -arbitrary manipulation of file names, -but if the returned strings are -passed to a different -.B SConscript -file, -any Node translation will be relative -to the other -.B SConscript -directory, -not the original -.B SConscript -directory.) - -Examples: - -.ES -Program('foo', Glob('*.c')) -Zip('/tmp/everything', Glob('.??*') + Glob('*')) -.EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI Help( text ) -.TP -.IR env .Help( text ) -This specifies help text to be printed if the -.B \-h -argument is given to -.BR scons . -If -.BR Help () -is called multiple times, the text is appended together in the order -that -.BR Help () -is called. - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI Ignore( target ", " dependency ) -.TP -.IR env .Ignore( target ", " dependency ) -The specified dependency file(s) -will be ignored when deciding if -the target file(s) need to be rebuilt. - -You can also use -.BR Ignore () -to remove a target from the default build. -In order to do this you must specify the directory the target will -be built in as the target, and the file you want to skip building -as the dependency. - -Note that this will only remove the dependencies listed from -the files built by default. It will still be built if that -dependency is needed by another object being built. -See the third and forth examples below. - -Examples: - -.ES -env.Ignore('foo', 'foo.c') -env.Ignore('bar', ['bar1.h', 'bar2.h']) -env.Ignore('.','foobar.obj') -env.Ignore('bar','bar/foobar.obj') -.EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI Import( vars ) -.TP -.IR env .Import( vars ) -This tells -.B scons -to import a list of variables into the current SConscript file. This -will import variables that were exported with -.BR Export () -or in the -.I exports -argument to -.BR SConscript (). -Variables exported by -.BR SConscript () -have precedence. -Multiple variable names can be passed to -.BR Import () -as separate arguments or as a list. The variable "*" can be used -to import all variables. - -Examples: - -.ES -Import("env") -Import("env", "variable") -Import(["env", "variable"]) -Import("*") -.EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI Literal( string ) -.TP -.IR env .Literal( string ) -The specified -.I string -will be preserved as-is -and not have construction variables expanded. - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI Local( targets ) -.TP -.IR env .Local( targets ) -The specified -.I targets -will have copies made in the local tree, -even if an already up-to-date copy -exists in a repository. -Returns a list of the target Node or Nodes. - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.IR env .MergeFlags( arg ", [" unique ]) -Merges the specified -.I arg -values to the construction environment's construction variables. -If the -.I arg -argument is not a dictionary, -it is converted to one by calling -.BR env.ParseFlags () -on the argument -before the values are merged. -Note that -.I arg -must be a single value, -so multiple strings must -be passed in as a list, -not as separate arguments to -.BR env.MergeFlags (). - -By default, -duplicate values are eliminated; -you can, however, specify -.B unique=0 -to allow duplicate -values to be added. -When eliminating duplicate values, -any construction variables that end with -the string -.B PATH -keep the left-most unique value. -All other construction variables keep -the right-most unique value. - -Examples: - -.ES -# Add an optimization flag to $CCFLAGS. -env.MergeFlags('-O3') - -# Combine the flags returned from running pkg-config with an optimization -# flag and merge the result into the construction variables. -env.MergeFlags(['!pkg-config gtk+-2.0 --cflags', '-O3']) - -# Combine an optimization flag with the flags returned from running pkg-config -# twice and merge the result into the construction variables. -env.MergeFlags(['-O3', - '!pkg-config gtk+-2.0 --cflags --libs', - '!pkg-config libpng12 --cflags --libs']) -.EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI NoCache( target ", ...)" -.TP -.IR env .NoCache( target ", ...)" -Specifies a list of files which should -.I not -be cached whenever the -.BR CacheDir () -method has been activated. -The specified targets may be a list -or an individual target. - -Multiple files should be specified -either as separate arguments to the -.BR NoCache () -method, or as a list. -.BR NoCache () -will also accept the return value of any of the construction environment -Builder methods. - -Calling -.BR NoCache () -on directories and other non-File Node types has no effect because -only File Nodes are cached. - -Examples: - -.ES -NoCache('foo.elf') -NoCache(env.Program('hello', 'hello.c')) -.EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI NoClean( target ", ...)" -.TP -.IR env .NoClean( target ", ...)" -Specifies a list of files or directories which should -.I not -be removed whenever the targets (or their dependencies) -are specified with the -.B \-c -command line option. -The specified targets may be a list -or an individual target. -Multiple calls to -.BR NoClean () -are legal, -and prevent each specified target -from being removed by calls to the -.B \-c -option. - -Multiple files or directories should be specified -either as separate arguments to the -.BR NoClean () -method, or as a list. -.BR NoClean () -will also accept the return value of any of the construction environment -Builder methods. - -Calling -.BR NoClean () -for a target overrides calling -.BR Clean () -for the same target, -and any targets passed to both functions will -.I not -be removed by the -.B \-c -option. - -Examples: - -.ES -NoClean('foo.elf') -NoClean(env.Program('hello', 'hello.c')) -.EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.IR env .ParseConfig( command ", [" function ", " unique ]) -Calls the specified -.I function -to modify the environment as specified by the output of -.IR command . -The default -.I function -is -.BR env.MergeFlags (), -which expects the output of a typical -.B *-config -command -(for example, -.BR gtk-config ) -and adds the options -to the appropriate construction variables. -By default, -duplicate values are not -added to any construction variables; -you can specify -.B unique=0 -to allow duplicate -values to be added. - -Interpreted options -and the construction variables they affect -are as specified for the -.BR env.ParseFlags () -method (which this method calls). -See that method's description, below, -for a table of options and construction variables. - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI ParseDepends( filename ", [" must_exist ", " only_one ]) -.TP -.IR env .ParseDepends( filename ", [" must_exist ", " only_one ]) -Parses the contents of the specified -.I filename -as a list of dependencies in the style of -.B Make -or -.BR mkdep , -and explicitly establishes all of the listed dependencies. - -By default, -it is not an error -if the specified -.I filename -does not exist. -The optional -.I must_exist -argument may be set to a non-zero -value to have -scons -throw an exception and -generate an error if the file does not exist, -or is otherwise inaccessible. - -The optional -.I only_one -argument may be set to a non-zero -value to have -scons -thrown an exception and -generate an error -if the file contains dependency -information for more than one target. -This can provide a small sanity check -for files intended to be generated -by, for example, the -.B "gcc -M" -flag, -which should typically only -write dependency information for -one output file into a corresponding -.B .d -file. - -The -.I filename -and all of the files listed therein -will be interpreted relative to -the directory of the -.B SConscript -file which calls the -.BR ParseDepends () -function. - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.IR env .ParseFlags( flags ", ...)" -Parses one or more strings containing -typical command-line flags for GCC tool chains -and returns a dictionary with the flag values -separated into the appropriate SCons construction variables. -This is intended as a companion to the -.BR env.MergeFlags () -method, but allows for the values in the returned dictionary -to be modified, if necessary, -before merging them into the construction environment. -(Note that -.BR env.MergeFlags () -will call this method if its argument is not a dictionary, -so it is usually not necessary to call -.BR env.ParseFlags () -directly unless you want to manipulate the values.) - -If the first character in any string is -an exclamation mark (!), -the rest of the string is executed as a command, -and the output from the command is -parsed as GCC tool chain command-line flags -and added to the resulting dictionary. - -Flag values are translated accordig to the prefix found, -and added to the following construction variables: - -.ES --arch CCFLAGS, LINKFLAGS --D CPPDEFINES --framework FRAMEWORKS --frameworkdir= FRAMEWORKPATH --include CCFLAGS --isysroot CCFLAGS, LINKFLAGS --I CPPPATH --l LIBS --L LIBPATH --mno-cygwin CCFLAGS, LINKFLAGS --mwindows LINKFLAGS --pthread CCFLAGS, LINKFLAGS --std= CFLAGS --Wa, ASFLAGS, CCFLAGS --Wl,-rpath= RPATH --Wl,-R, RPATH --Wl,-R RPATH --Wl, LINKFLAGS --Wp, CPPFLAGS -- CCFLAGS -+ CCFLAGS, LINKFLAGS -.EE -.IP -Any other strings not associated with options -are assumed to be the names of libraries -and added to the -.B $LIBS -construction variable. - -Examples (all of which produce the same result): - -.ES -dict = env.ParseFlags('-O2 -Dfoo -Dbar=1') -dict = env.ParseFlags('-O2', '-Dfoo', '-Dbar=1') -dict = env.ParseFlags(['-O2', '-Dfoo -Dbar=1']) -dict = env.ParseFlags('-O2', '!echo -Dfoo -Dbar=1') -.EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.IR env .Perforce() -A factory function that -returns a Builder object -to be used to fetch source files -from the Perforce source code management system. -The returned Builder -is intended to be passed to the -.BR SourceCode () -function. - -This function is deprecated. For details, see the entry for the -.BR SourceCode () -function. - -Example: - -.ES -env.SourceCode('.', env.Perforce()) -.EE -.IP -Perforce uses a number of external -environment variables for its operation. -Consequently, this function adds the -following variables from the user's external environment -to the construction environment's -ENV dictionary: -P4CHARSET, -P4CLIENT, -P4LANGUAGE, -P4PASSWD, -P4PORT, -P4USER, -SystemRoot, -USER, -and -USERNAME. - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI Platform( string ) -The -.BR Platform () -form returns a callable object -that can be used to initialize -a construction environment using the -platform keyword of the -.BR Environment () -function. - -Example: - -.ES -env = Environment(platform = Platform('win32')) -.EE -.IP -The -.BR env.Platform () -form applies the callable object for the specified platform -.I string -to the environment through which the method was called. - -.ES -env.Platform('posix') -.EE -.IP -Note that the -.B win32 -platform adds the -.B SystemDrive -and -.B SystemRoot -variables from the user's external environment -to the construction environment's -.B $ENV -dictionary. -This is so that any executed commands -that use sockets to connect with other systems -(such as fetching source files from -external CVS repository specifications like -.BR :pserver:anonymous@cvs.sourceforge.net:/cvsroot/scons ) -will work on Windows systems. - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI Precious( target ", ...)" -.TP -.IR env .Precious( target ", ...)" -Marks each given -.I target -as precious so it is not deleted before it is rebuilt. Normally -.B scons -deletes a target before building it. -Multiple targets can be passed in to a single call to -.BR Precious (). - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.IR env .Prepend(key= val ", [...])" -Appends the specified keyword arguments -to the beginning of construction variables in the environment. -If the Environment does not have -the specified construction variable, -it is simply added to the environment. -If the values of the construction variable -and the keyword argument are the same type, -then the two values will be simply added together. -Otherwise, the construction variable -and the value of the keyword argument -are both coerced to lists, -and the lists are added together. -(See also the Append method, above.) - -Example: - -.ES -env.Prepend(CCFLAGS = '-g ', FOO = ['foo.yyy']) -.EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.IR env .PrependENVPath( name ", " newpath ", [" envname ", " sep ", " delete_existing ]) -This appends new path elements to the given path in the -specified external environment -.RB ( $ENV -by default). -This will only add -any particular path once (leaving the first one it encounters and -ignoring the rest, to preserve path order), -and to help assure this, -will normalize all paths (using -.B os.path.normpath -and -.BR os.path.normcase ). -This can also handle the -case where the given old path variable is a list instead of a -string, in which case a list will be returned instead of a string. - -If -.I delete_existing -is 0, then adding a path that already exists -will not move it to the beginning; -it will stay where it is in the list. - -Example: - -.ES -print 'before:',env['ENV']['INCLUDE'] -include_path = '/foo/bar:/foo' -env.PrependENVPath('INCLUDE', include_path) -print 'after:',env['ENV']['INCLUDE'] -.EE -.IP -The above example will print: - -.ES -before: /biz:/foo -after: /foo/bar:/foo:/biz -.EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.IR env .PrependUnique(key= val ", delete_existing=" "0, [...])" -Appends the specified keyword arguments -to the beginning of construction variables in the environment. -If the Environment does not have -the specified construction variable, -it is simply added to the environment. -If the construction variable being appended to is a list, -then any value(s) that already exist in the -construction variable will -.I not -be added again to the list. -However, if delete_existing is 1, -existing matching values are removed first, so -existing values in the arg list move to the front of the list. - -Example: - -.ES -env.PrependUnique(CCFLAGS = '-g', FOO = ['foo.yyy']) -.EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI Progress( callable ", [" interval ]) -.TP -.RI Progress( string ", [" interval ", " file ", " overwrite ]) -.TP -.RI Progress( list_of_strings ", [" interval ", " file ", " overwrite ]) -Allows SCons to show progress made during the build -by displaying a string or calling a function while -evaluating Nodes (e.g. files). - -If the first specified argument is a Python callable -(a function or an object that has a -.BR __call__ () -method), -the function will be called -once every -.I interval -times a Node is evaluated. -The callable will be passed the evaluated Node -as its only argument. -(For future compatibility, -it's a good idea to also add -.B *args -and -.B **kw -as arguments to your function or method. -This will prevent the code from breaking -if SCons ever changes the interface -to call the function with additional arguments in the future.) - -An example of a simple custom progress function -that prints a string containing the Node name -every 10 Nodes: - -.ES -def my_progress_function(node, *args, **kw): - print 'Evaluating node %s!' % node -Progress(my_progress_function, interval=10) -.EE -.IP -A more complicated example of a custom progress display object -that prints a string containing a count -every 100 evaluated Nodes. -Note the use of -.B \\r -(a carriage return) -at the end so that the string -will overwrite itself on a display: - -.ES -import sys -class ProgressCounter(object): - count = 0 - def __call__(self, node, *args, **kw): - self.count += 100 - sys.stderr.write('Evaluated %s nodes\\r' % self.count) -Progress(ProgressCounter(), interval=100) -.EE -.IP -If the first argument -.BR Progress () -is a string, -the string will be displayed -every -.I interval -evaluated Nodes. -The default is to print the string on standard output; -an alternate output stream -may be specified with the -.B file= -argument. -The following will print a series of dots -on the error output, -one dot for every 100 evaluated Nodes: - -.ES -import sys -Progress('.', interval=100, file=sys.stderr) -.EE -.IP -If the string contains the verbatim substring -.BR $TARGET , -it will be replaced with the Node. -Note that, for performance reasons, this is -.I not -a regular SCons variable substition, -so you can not use other variables -or use curly braces. -The following example will print the name of -every evaluated Node, -using a -.B \\r -(carriage return) to cause each line to overwritten by the next line, -and the -.B overwrite= -keyword argument to make sure the previously-printed -file name is overwritten with blank spaces: - -.ES -import sys -Progress('$TARGET\\r', overwrite=True) -.EE -.IP -If the first argument to -.BR Progress () -is a list of strings, -then each string in the list will be displayed -in rotating fashion every -.I interval -evaluated Nodes. -This can be used to implement a "spinner" -on the user's screen as follows: - -.ES -Progress(['-\\r', '\\\\\\r', '|\\r', '/\\r'], interval=5) -.EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.IR env .RCS() -A factory function that -returns a Builder object -to be used to fetch source files -from RCS. -The returned Builder -is intended to be passed to the -.BR SourceCode () -function: - -This function is deprecated. For details, see the entry for the -.BR SourceCode () -function. - -Examples: - -.ES -env.SourceCode('.', env.RCS()) -.EE -.IP -Note that -.B scons -will fetch source files -from RCS subdirectories automatically, -so configuring RCS -as demonstrated in the above example -should only be necessary if -you are fetching from -RCS,v -files in the same -directory as the source files, -or if you need to explicitly specify RCS -for a specific subdirectory. - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.IR env .Replace(key= val ", [...])" -Replaces construction variables in the Environment -with the specified keyword arguments. - -Example: - -.ES -env.Replace(CCFLAGS = '-g', FOO = 'foo.xxx') -.EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI Repository( directory ) -.TP -.IR env .Repository( directory ) -Specifies that -.I directory -is a repository to be searched for files. -Multiple calls to -.BR Repository () -are legal, -and each one adds to the list of -repositories that will be searched. - -To -.BR scons , -a repository is a copy of the source tree, -from the top-level directory on down, -which may contain -both source files and derived files -that can be used to build targets in -the local source tree. -The canonical example would be an -official source tree maintained by an integrator. -If the repository contains derived files, -then the derived files should have been built using -.BR scons , -so that the repository contains the necessary -signature information to allow -.B scons -to figure out when it is appropriate to -use the repository copy of a derived file, -instead of building one locally. - -Note that if an up-to-date derived file -already exists in a repository, -.B scons -will -.I not -make a copy in the local directory tree. -In order to guarantee that a local copy -will be made, -use the -.BR Local () -method. - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI Requires( target ", " prerequisite ) -.TP -.IR env .Requires( target ", " prerequisite ) -Specifies an order-only relationship -between the specified target file(s) -and the specified prerequisite file(s). -The prerequisite file(s) -will be (re)built, if necessary, -.I before -the target file(s), -but the target file(s) do not actually -depend on the prerequisites -and will not be rebuilt simply because -the prerequisite file(s) change. - -Example: - -.ES -env.Requires('foo', 'file-that-must-be-built-before-foo') -.EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI Return([ vars "..., stop=" ]) -By default, -this stops processing the current SConscript -file and returns to the calling SConscript file -the values of the variables named in the -.I vars -string arguments. -Multiple strings contaning variable names may be passed to -.BR Return (). -Any strings that contain white space - -The optional -.B stop= -keyword argument may be set to a false value -to continue processing the rest of the SConscript -file after the -.BR Return () -call. -This was the default behavior prior to SCons 0.98. -However, the values returned -are still the values of the variables in the named -.I vars -at the point -.BR Return () -is called. - -Examples: - -.ES -# Returns without returning a value. -Return() - -# Returns the value of the 'foo' Python variable. -Return("foo") - -# Returns the values of the Python variables 'foo' and 'bar'. -Return("foo", "bar") - -# Returns the values of Python variables 'val1' and 'val2'. -Return('val1 val2') -.EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI Scanner( function ", [" argument ", " keys ", " path_function ", " node_class ", " node_factory ", " scan_check ", " recursive ]) -.TP -.IR env .Scanner( function ", [" argument ", " keys ", " path_function ", " node_class ", " node_factory ", " scan_check ", " recursive ]) -Creates a Scanner object for -the specified -.IR function . -See the section "Scanner Objects," -below, for a complete explanation of the arguments and behavior. - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.IR env .SCCS() -A factory function that -returns a Builder object -to be used to fetch source files -from SCCS. -The returned Builder -is intended to be passed to the -.BR SourceCode () -function. - -Example: - -.ES -env.SourceCode('.', env.SCCS()) -.EE -.IP -Note that -.B scons -will fetch source files -from SCCS subdirectories automatically, -so configuring SCCS -as demonstrated in the above example -should only be necessary if -you are fetching from -.B s.SCCS -files in the same -directory as the source files, -or if you need to explicitly specify SCCS -for a specific subdirectory. - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI SConscript( scripts ", [" exports ", " variant_dir ", " duplicate ]) -.TP -.IR env .SConscript( scripts ", [" exports ", " variant_dir ", " duplicate ]) -.TP -.RI SConscript(dirs= subdirs ", [name=" script ", " exports ", " variant_dir ", " duplicate ]) -.TP -.IR env .SConscript(dirs= subdirs ", [name=" script ", " exports ", " variant_dir ", " duplicate ]) -This tells -.B scons -to execute -one or more subsidiary SConscript (configuration) files. -Any variables returned by a called script using -.BR Return () -will be returned by the call to -.BR SConscript (). -There are two ways to call the -.BR SConscript () -function. - -The first way you can call -.BR SConscript () -is to explicitly specify one or more -.I scripts -as the first argument. -A single script may be specified as a string; -multiple scripts must be specified as a list -(either explicitly or as created by -a function like -.BR Split ()). -Examples: -.ES -SConscript('SConscript') # run SConscript in the current directory -SConscript('src/SConscript') # run SConscript in the src directory -SConscript(['src/SConscript', 'doc/SConscript']) -config = SConscript('MyConfig.py') -.EE -.IP -The second way you can call -.BR SConscript () -is to specify a list of (sub)directory names -as a -.BI dirs= subdirs -keyword argument. -In this case, -.B scons -will, by default, -execute a subsidiary configuration file named -.B SConscript -in each of the specified directories. -You may specify a name other than -.B SConscript -by supplying an optional -.BI name= script -keyword argument. -The first three examples below have the same effect -as the first three examples above: -.ES -SConscript(dirs='.') # run SConscript in the current directory -SConscript(dirs='src') # run SConscript in the src directory -SConscript(dirs=['src', 'doc']) -SConscript(dirs=['sub1', 'sub2'], name='MySConscript') -.EE -.IP -The optional -.I exports -argument provides a list of variable names or a dictionary of -named values to export to the -.IR script(s) . -These variables are locally exported only to the specified -.IR script(s) , -and do not affect the global pool of variables used by the -.BR Export () -function. -The subsidiary -.I script(s) -must use the -.BR Import () -function to import the variables. -Examples: -.ES -foo = SConscript('sub/SConscript', exports='env') -SConscript('dir/SConscript', exports=['env', 'variable']) -SConscript(dirs='subdir', exports='env variable') -SConscript(dirs=['one', 'two', 'three'], exports='shared_info') -.EE -.IP -If the optional -.I variant_dir -argument is present, it causes an effect equivalent to the -.BR VariantDir () -method described below. -(If -.I variant_dir -is not present, the -.I duplicate -argument is ignored.) -The -.I variant_dir -argument is interpreted relative to the directory of the calling -.B SConscript -file. -See the description of the -.BR VariantDir () -function below for additional details and restrictions. - -If -.I variant_dir -is present, -the source directory is the directory in which the -.B SConscript -file resides and the -.B SConscript -file is evaluated as if it were in the -.I variant_dir -directory: -.ES -SConscript('src/SConscript', variant_dir = 'build') -.EE -.IP -is equivalent to - -.ES -VariantDir('build', 'src') -SConscript('build/SConscript') -.EE -.IP -This later paradigm is often used when the sources are -in the same directory as the -.BR SConstruct : - -.ES -SConscript('SConscript', variant_dir = 'build') -.EE -.IP -is equivalent to - -.ES -VariantDir('build', '.') -SConscript('build/SConscript') -.EE -.IP -Here are some composite examples: - -.ES -# collect the configuration information and use it to build src and doc -shared_info = SConscript('MyConfig.py') -SConscript('src/SConscript', exports='shared_info') -SConscript('doc/SConscript', exports='shared_info') -.EE - -.ES -# build debugging and production versions. SConscript -# can use Dir('.').path to determine variant. -SConscript('SConscript', variant_dir='debug', duplicate=0) -SConscript('SConscript', variant_dir='prod', duplicate=0) -.EE - -.ES -# build debugging and production versions. SConscript -# is passed flags to use. -opts = { 'CPPDEFINES' : ['DEBUG'], 'CCFLAGS' : '-pgdb' } -SConscript('SConscript', variant_dir='debug', duplicate=0, exports=opts) -opts = { 'CPPDEFINES' : ['NODEBUG'], 'CCFLAGS' : '-O' } -SConscript('SConscript', variant_dir='prod', duplicate=0, exports=opts) -.EE - -.ES -# build common documentation and compile for different architectures -SConscript('doc/SConscript', variant_dir='build/doc', duplicate=0) -SConscript('src/SConscript', variant_dir='build/x86', duplicate=0) -SConscript('src/SConscript', variant_dir='build/ppc', duplicate=0) -.EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI SConscriptChdir( value ) -.TP -.IR env .SConscriptChdir( value ) -By default, -.B scons -changes its working directory -to the directory in which each -subsidiary SConscript file lives. -This behavior may be disabled -by specifying either: - -.ES -SConscriptChdir(0) -env.SConscriptChdir(0) -.EE -.IP -in which case -.B scons -will stay in the top-level directory -while reading all SConscript files. -(This may be necessary when building from repositories, -when all the directories in which SConscript files may be found -don't necessarily exist locally.) -You may enable and disable -this ability by calling -SConscriptChdir() -multiple times. - -Example: - -.ES -env = Environment() -SConscriptChdir(0) -SConscript('foo/SConscript') # will not chdir to foo -env.SConscriptChdir(1) -SConscript('bar/SConscript') # will chdir to bar -.EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI SConsignFile([ file ", " dbm_module ]) -.TP -.IR env .SConsignFile([ file ", " dbm_module ]) -This tells -.B scons -to store all file signatures -in the specified database -.IR file . -If the -.I file -name is omitted, -.B .sconsign -is used by default. -(The actual file name(s) stored on disk -may have an appropriated suffix appended -by the -.IR dbm_module .) -If -.I file -is not an absolute path name, -the file is placed in the same directory as the top-level -.B SConstruct -file. - -If -.I file -is -.BR None , -then -.B scons -will store file signatures -in a separate -.B .sconsign -file in each directory, -not in one global database file. -(This was the default behavior -prior to SCons 0.96.91 and 0.97.) - -The optional -.I dbm_module -argument can be used to specify -which Python database module -The default is to use a custom -.B SCons.dblite -module that uses pickled -Python data structures, -and which works on all Python versions. - -Examples: - -.ES -# Explicitly stores signatures in ".sconsign.dblite" -# in the top-level SConstruct directory (the -# default behavior). -SConsignFile() - -# Stores signatures in the file "etc/scons-signatures" -# relative to the top-level SConstruct directory. -SConsignFile("etc/scons-signatures") - -# Stores signatures in the specified absolute file name. -SConsignFile("/home/me/SCons/signatures") - -# Stores signatures in a separate .sconsign file -# in each directory. -SConsignFile(None) -.EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.IR env .SetDefault(key= val ", [...])" -Sets construction variables to default values specified with the keyword -arguments if (and only if) the variables are not already set. -The following statements are equivalent: - -.ES -env.SetDefault(FOO = 'foo') - -if 'FOO' not in env: env['FOO'] = 'foo' -.EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI SetOption( name ", " value ) -.TP -.IR env .SetOption( name ", " value ) -This function provides a way to set a select subset of the scons command -line options from a SConscript file. The options supported are: - -.RS 10 -.TP 6 -.B clean -which corresponds to -c, --clean and --remove; -.TP 6 -.B duplicate -which corresponds to --duplicate; -.TP 6 -.B help -which corresponds to -h and --help; -.TP 6 -.B implicit_cache -which corresponds to --implicit-cache; -.TP 6 -.B max_drift -which corresponds to --max-drift; -.TP 6 -.B no_exec -which corresponds to -n, --no-exec, --just-print, --dry-run and --recon; -.TP 6 -.B num_jobs -which corresponds to -j and --jobs; -.TP 6 -.B random -which corresponds to --random; and -.TP 6 -.B stack_size -which corresponds to --stack-size. -.RE - -See the documentation for the -corresponding command line object for information about each specific -option. - -Example: - -.ES -SetOption('max_drift', 1) -.EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI SideEffect( side_effect ", " target ) -.TP -.IR env .SideEffect( side_effect ", " target ) -Declares -.I side_effect -as a side effect of building -.IR target . -Both -.I side_effect -and -.I target -can be a list, a file name, or a node. -A side effect is a target file that is created or updated -as a side effect of building other targets. -For example, a Windows PDB -file is created as a side effect of building the .obj -files for a static library, -and various log files are created updated -as side effects of various TeX commands. -If a target is a side effect of multiple build commands, -.B scons -will ensure that only one set of commands -is executed at a time. -Consequently, you only need to use this method -for side-effect targets that are built as a result of -multiple build commands. - -Because multiple build commands may update -the same side effect file, -by default the -.I side_effect -target is -.I not -automatically removed -when the -.I target -is removed by the -.B \-c -option. -(Note, however, that the -.I side_effect -might be removed as part of -cleaning the directory in which it lives.) -If you want to make sure the -.I side_effect -is cleaned whenever a specific -.I target -is cleaned, -you must specify this explicitly -with the -.BR Clean () -or -.BR env.Clean () -function. - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI SourceCode( entries ", " builder ) -.TP -.IR env .SourceCode( entries ", " builder ) -This function and its associate factory functions are deprecated. -There is no replacement. -The intended use was to keep a local tree in sync with an archive, -but in actuality the function only causes the archive -to be fetched on the first run. -Synchronizing with the archive is best done external to &SCons;. - -Arrange for non-existent source files to -be fetched from a source code management system -using the specified -.IR builder . -The specified -.I entries -may be a Node, string or list of both, -and may represent either individual -source files or directories in which -source files can be found. - -For any non-existent source files, -.B scons -will search up the directory tree -and use the first -.BR SourceCode () -builder it finds. -The specified -.I builder -may be -.BR None , -in which case -.B scons -will not use a builder to fetch -source files for the specified -.IR entries , -even if a -.BR SourceCode () -builder has been specified -for a directory higher up the tree. - -.B scons -will, by default, -fetch files from SCCS or RCS subdirectories -without explicit configuration. -This takes some extra processing time -to search for the necessary -source code management files on disk. -You can avoid these extra searches -and speed up your build a little -by disabling these searches as follows: - -.ES -env.SourceCode('.', None) -.EE -.IP -Note that if the specified -.I builder -is one you create by hand, -it must have an associated -construction environment to use -when fetching a source file. - -.B scons -provides a set of canned factory -functions that return appropriate -Builders for various popular -source code management systems. -Canonical examples of invocation include: - -.ES -env.SourceCode('.', env.BitKeeper('/usr/local/BKsources')) -env.SourceCode('src', env.CVS('/usr/local/CVSROOT')) -env.SourceCode('/', env.RCS()) -env.SourceCode(['f1.c', 'f2.c'], env.SCCS()) -env.SourceCode('no_source.c', None) -.EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI SourceSignatures( type ) -.TP -.IR env .SourceSignatures( type ) -Note: Although it is not yet officially deprecated, -use of this function is discouraged. -See the -.BR Decider () -function for a more flexible and straightforward way -to configure SCons' decision-making. - -The -.BR SourceSignatures () -function tells -.B scons -how to decide if a source file -(a file that is not built from any other files) -has changed since the last time it -was used to build a particular target file. -Legal values are -.B MD5 -or -.BR timestamp . - -If the environment method is used, -the specified type of source signature -is only used when deciding whether targets -built with that environment are up-to-date or must be rebuilt. -If the global function is used, -the specified type of source signature becomes the default -used for all decisions -about whether targets are up-to-date. - -.B MD5 -means -.B scons -decides that a source file has changed -if the MD5 checksum of its contents has changed since -the last time it was used to rebuild a particular target file. - -.B timestamp -means -.B scons -decides that a source file has changed -if its timestamp (modification time) has changed since -the last time it was used to rebuild a particular target file. -(Note that although this is similar to the behavior of Make, -by default it will also rebuild if the dependency is -.I older -than the last time it was used to rebuild the target file.) - -There is no different between the two behaviors -for Python -.BR Value () -node objects. - -.B MD5 -signatures take longer to compute, -but are more accurate than -.B timestamp -signatures. -The default value is -.BR MD5 . - -Note that the default -.BR TargetSignatures () -setting (see below) -is to use this -.BR SourceSignatures () -setting for any target files that are used -to build other target files. -Consequently, changing the value of -.BR SourceSignatures () -will, by default, -affect the up-to-date decision for all files in the build -(or all files built with a specific construction environment -when -.BR env.SourceSignatures () -is used). - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI Split( arg ) -.TP -.IR env .Split( arg ) -Returns a list of file names or other objects. -If arg is a string, -it will be split on strings of white-space characters -within the string, -making it easier to write long lists of file names. -If arg is already a list, -the list will be returned untouched. -If arg is any other type of object, -it will be returned as a list -containing just the object. - -Example: - -.ES -files = Split("f1.c f2.c f3.c") -files = env.Split("f4.c f5.c f6.c") -files = Split(""" - f7.c - f8.c - f9.c -""") -.EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.IR env .subst( input ", [" raw ", " target ", " source ", " conv ]) -Performs construction variable interpolation -on the specified string or sequence argument -.IR input . - -By default, -leading or trailing white space will -be removed from the result. -and all sequences of white space -will be compressed to a single space character. -Additionally, any -.B $( -and -.B $) -character sequences will be stripped from the returned string, -The optional -.I raw -argument may be set to -.B 1 -if you want to preserve white space and -.BR $( - $) -sequences. -The -.I raw -argument may be set to -.B 2 -if you want to strip -all characters between -any -.B $( -and -.B $) -pairs -(as is done for signature calculation). - -If the input is a sequence -(list or tuple), -the individual elements of -the sequence will be expanded, -and the results will be returned as a list. - -The optional -.I target -and -.I source -keyword arguments -must be set to lists of -target and source nodes, respectively, -if you want the -.BR $TARGET , -.BR $TARGETS , -.B $SOURCE -and -.B $SOURCES -to be available for expansion. -This is usually necessary if you are -calling -.BR env.subst () -from within a Python function used -as an SCons action. - -Returned string values or sequence elements -are converted to their string representation by default. -The optional -.I conv -argument -may specify a conversion function -that will be used in place of -the default. -For example, if you want Python objects -(including SCons Nodes) -to be returned as Python objects, -you can use the Python -.B lambda -idiom to pass in an unnamed function -that simply returns its unconverted argument. - -Example: - -.ES -print env.subst("The C compiler is: $CC") - -def compile(target, source, env): - sourceDir = env.subst("${SOURCE.srcdir}", - target=target, - source=source) - -source_nodes = env.subst('$EXPAND_TO_NODELIST', - conv=lambda x: x) -.EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI Tag( node ", " tags ) -Annotates file or directory Nodes with -information about how the -.BR Package () -Builder should package those files or directories. -All tags are optional. - -Examples: - -.ES -# makes sure the built library will be installed with 0644 file -# access mode -Tag( Library( 'lib.c' ), UNIX_ATTR="0644" ) - -# marks file2.txt to be a documentation file -Tag( 'file2.txt', DOC ) -.EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI TargetSignatures( type ) -.TP -.IR env .TargetSignatures( type ) -Note: Although it is not yet officially deprecated, -use of this function is discouraged. -See the -.BR Decider () -function for a more flexible and straightforward way -to configure SCons' decision-making. - -The -.BR TargetSignatures () -function tells -.B scons -how to decide if a target file -(a file that -.I is -built from any other files) -has changed since the last time it -was used to build some other target file. -Legal values are -.BR "build" ; -.B "content" -(or its synonym -.BR "MD5" ); -.BR "timestamp" ; -or -.BR "source" . - -If the environment method is used, -the specified type of target signature is only used -for targets built with that environment. -If the global function is used, -the specified type of signature becomes the default -used for all target files that -don't have an explicit target signature type -specified for their environments. - -.B "content" -(or its synonym -.BR "MD5" ) -means -.B scons -decides that a target file has changed -if the MD5 checksum of its contents has changed since -the last time it was used to rebuild some other target file. -This means -.B scons -will open up -MD5 sum the contents -of target files after they're built, -and may decide that it does not need to rebuild -"downstream" target files if a file was -rebuilt with exactly the same contents as the last time. - -.B "timestamp" -means -.B scons -decides that a target file has changed -if its timestamp (modification time) has changed since -the last time it was used to rebuild some other target file. -(Note that although this is similar to the behavior of Make, -by default it will also rebuild if the dependency is -.I older -than the last time it was used to rebuild the target file.) - -.B "source" -means -.B scons -decides that a target file has changed -as specified by the corresponding -.BR SourceSignatures () -setting -.RB ( "MD5" -or -.BR "timestamp" ). -This means that -.B scons -will treat all input files to a target the same way, -regardless of whether they are source files -or have been built from other files. - -.B "build" -means -.B scons -decides that a target file has changed -if it has been rebuilt in this invocation -or if its content or timestamp have changed -as specified by the corresponding -.BR SourceSignatures () -setting. -This "propagates" the status of a rebuilt file -so that other "downstream" target files -will always be rebuilt, -even if the contents or the timestamp -have not changed. - -.B "build" -signatures are fastest because -.B "content" -(or -.BR "MD5" ) -signatures take longer to compute, -but are more accurate than -.B "timestamp" -signatures, -and can prevent unnecessary "downstream" rebuilds -when a target file is rebuilt to the exact same contents -as the previous build. -The -.B "source" -setting provides the most consistent behavior -when other target files may be rebuilt from -both source and target input files. -The default value is -.BR "source" . - -Because the default setting is -.BR "source" , -using -.BR SourceSignatures () -is generally preferable to -.BR TargetSignatures (), -so that the up-to-date decision -will be consistent for all files -(or all files built with a specific construction environment). -Use of -.BR TargetSignatures () -provides specific control for how built target files -affect their "downstream" dependencies. - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI Tool( string ", [" toolpath ", **" kw ]) -.TP -.IR env .Tool( string ", [" toolpath ", **" kw ]) -The -.BR Tool () -form of the function -returns a callable object -that can be used to initialize -a construction environment using the -tools keyword of the Environment() method. -The object may be called with a construction -environment as an argument, -in which case the object will -add the necessary variables -to the construction environment -and the name of the tool will be added to the -.B $TOOLS -construction variable. - -Additional keyword arguments are passed to the tool's -.BR generate () -method. - -Examples: - -.ES -env = Environment(tools = [ Tool('msvc') ]) - -env = Environment() -t = Tool('msvc') -t(env) # adds 'msvc' to the TOOLS variable -u = Tool('opengl', toolpath = ['tools']) -u(env) # adds 'opengl' to the TOOLS variable -.EE -.IP -The -.BR env.Tool () -form of the function -applies the callable object for the specified tool -.I string -to the environment through which the method was called. - -Additional keyword arguments are passed to the tool's -.BR generate () -method. - -.ES -env.Tool('gcc') -env.Tool('opengl', toolpath = ['build/tools']) -.EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI Value( value ", [" built_value ]) -.TP -.IR env .Value( value ", [" built_value ]) -Returns a Node object representing the specified Python value. Value -Nodes can be used as dependencies of targets. If the result of -calling -.BI str( value ) -changes between SCons runs, any targets depending on -.BI Value( value ) -will be rebuilt. -(This is true even when using timestamps to decide if -files are up-to-date.) -When using timestamp source signatures, Value Nodes' -timestamps are equal to the system time when the Node is created. - -The returned Value Node object has a -.BR write () -method that can be used to "build" a Value Node -by setting a new value. -The optional -.I built_value -argument can be specified -when the Value Node is created -to indicate the Node should already be considered -"built." -There is a corresponding -.BR read () -method that will return the built value of the Node. - -Examples: - -.ES -env = Environment() - -def create(target, source, env): - # A function that will write a 'prefix=$SOURCE' - # string into the file name specified as the - # $TARGET. - f = open(str(target[0]), 'wb') - f.write('prefix=' + source[0].get_contents()) - -# Fetch the prefix= argument, if any, from the command -# line, and use /usr/local as the default. -prefix = ARGUMENTS.get('prefix', '/usr/local') - -# Attach a .Config() builder for the above function action -# to the construction environment. -env['BUILDERS']['Config'] = Builder(action = create) -env.Config(target = 'package-config', source = Value(prefix)) - -def build_value(target, source, env): - # A function that "builds" a Python Value by updating - # the the Python value with the contents of the file - # specified as the source of the Builder call ($SOURCE). - target[0].write(source[0].get_contents()) - -output = env.Value('before') -input = env.Value('after') - -# Attach a .UpdateValue() builder for the above function -# action to the construction environment. -env['BUILDERS']['UpdateValue'] = Builder(action = build_value) -env.UpdateValue(target = Value(output), source = Value(input)) -.EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI VariantDir( variant_dir ", " src_dir ", [" duplicate ]) -.TP -.IR env .VariantDir( variant_dir ", " src_dir ", [" duplicate ]) -Use the -.BR VariantDir () -function to create a copy of your sources in another location: -if a name under -.I variant_dir -is not found but exists under -.IR src_dir , -the file or directory is copied to -.IR variant_dir . -Target files can be built in a different directory -than the original sources by simply refering to the sources (and targets) -within the variant tree. - -.BR VariantDir () -can be called multiple times with the same -.I src_dir -to set up multiple builds with different options -.RI ( variants ). -The -.I src_dir -location must be in or underneath the SConstruct file's directory, and -.I variant_dir -may not be underneath -.IR src_dir . - -The default behavior is for -.B scons -to physically duplicate the source files in the variant tree. -Thus, a build performed in the variant tree is guaranteed to be identical -to a build performed in the source tree even if -intermediate source files are generated during the build, -or preprocessors or other scanners search for included files -relative to the source file, -or individual compilers or other invoked tools are hard-coded -to put derived files in the same directory as source files. - -If possible on the platform, -the duplication is performed by linking rather than copying; -see also the -.B \-\-duplicate -command-line option. -Moreover, only the files needed for the build are duplicated; -files and directories that are not used are not present in -.IR variant_dir . - -Duplicating the source tree may be disabled by setting the -.B duplicate -argument to -.B 0 -(zero). -This will cause -.B scons -to invoke Builders using the path names of source files in -.I src_dir -and the path names of derived files within -.IR variant_dir . -This is always more efficient than -.BR duplicate=1 , -and is usually safe for most builds -(but see above for cases that may cause problems). - -Note that -.BR VariantDir () -works most naturally with a subsidiary SConscript file. -However, you would then call the subsidiary SConscript file -not in the source directory, but in the -.IR variant_dir , -regardless of the value of -.BR duplicate . -This is how you tell -.B scons -which variant of a source tree to build: - -.ES -# run src/SConscript in two variant directories -VariantDir('build/variant1', 'src') -SConscript('build/variant1/SConscript') -VariantDir('build/variant2', 'src') -SConscript('build/variant2/SConscript') -.EE -.IP -See also the -.BR SConscript () -function, described above, -for another way to specify a variant directory -in conjunction with calling a subsidiary SConscript file. - -Examples: - -.ES -# use names in the build directory, not the source directory -VariantDir('build', 'src', duplicate=0) -Program('build/prog', 'build/source.c') -.EE - -.ES -# this builds both the source and docs in a separate subtree -VariantDir('build', '.', duplicate=0) -SConscript(dirs=['build/src','build/doc']) -.EE - -.ES -# same as previous example, but only uses SConscript -SConscript(dirs='src', variant_dir='build/src', duplicate=0) -SConscript(dirs='doc', variant_dir='build/doc', duplicate=0) -.EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI WhereIs( program ", [" path ", " pathext ", " reject ]) -.TP -.IR env .WhereIs( program ", [" path ", " pathext ", " reject ]) -Searches for the specified executable -.IR program , -returning the full path name to the program -if it is found, -and returning None if not. -Searches the specified -.IR path , -the value of the calling environment's PATH -.RB ( env['ENV']['PATH'] ), -or the user's current external PATH -.RB ( os.environ['PATH'] ) -by default. -On Windows systems, searches for executable -programs with any of the file extensions -listed in the specified -.IR pathext , -the calling environment's PATHEXT -.RB ( env['ENV']['PATHEXT'] ) -or the user's current PATHEXT -.RB ( os.environ['PATHEXT'] ) -by default. -Will not select any -path name or names -in the specified -.I reject -list, if any. -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -'\" END GENERATED FUNCTION DESCRIPTIONS -'\" -'\" The descriptions above of the various SCons functions are generated -'\" from the .xml files that live next to the various Python modules in -'\" the build enginer library. If you're reading this [gnt]roff file -'\" with an eye towards patching this man page, you can still submit -'\" a diff against this text, but it will have to be translated to a -'\" diff against the underlying .xml file before the patch is actually -'\" accepted. If you do that yourself, it will make it easier to -'\" integrate the patch. -'\" -'\" END GENERATED FUNCTION DESCRIPTIONS -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" - -.SS SConscript Variables -In addition to the global functions and methods, -.B scons -supports a number of Python variables -that can be used in SConscript files -to affect how you want the build to be performed. -These variables may be accessed from custom Python modules that you -import into an SConscript file by adding the following -to the Python module: - -.ES -from SCons.Script import * -.EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -ARGLIST -A list -.IR keyword = value -arguments specified on the command line. -Each element in the list is a tuple -containing the -.RI ( keyword , value ) -of the argument. -The separate -.I keyword -and -.I value -elements of the tuple -can be accessed by -subscripting for element -.B [0] -and -.B [1] -of the tuple, respectively. - -Example: - -.ES -print "first keyword, value =", ARGLIST[0][0], ARGLIST[0][1] -print "second keyword, value =", ARGLIST[1][0], ARGLIST[1][1] -third_tuple = ARGLIST[2] -print "third keyword, value =", third_tuple[0], third_tuple[1] -for key, value in ARGLIST: - # process key and value -.EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -ARGUMENTS -A dictionary of all the -.IR keyword = value -arguments specified on the command line. -The dictionary is not in order, -and if a given keyword has -more than one value assigned to it -on the command line, -the last (right-most) value is -the one in the -.B ARGUMENTS -dictionary. - -Example: - -.ES -if ARGUMENTS.get('debug', 0): - env = Environment(CCFLAGS = '-g') -else: - env = Environment() -.EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -BUILD_TARGETS -A list of the targets which -.B scons -will actually try to build, -regardless of whether they were specified on -the command line or via the -.BR Default () -function or method. -The elements of this list may be strings -.I or -nodes, so you should run the list through the Python -.B str -function to make sure any Node path names -are converted to strings. - -Because this list may be taken from the -list of targets specified using the -.BR Default () -function or method, -the contents of the list may change -on each successive call to -.BR Default (). -See the -.B DEFAULT_TARGETS -list, below, -for additional information. - -Example: - -.ES -if 'foo' in BUILD_TARGETS: - print "Don't forget to test the `foo' program!" -if 'special/program' in BUILD_TARGETS: - SConscript('special') -.EE -.IP -Note that the -.B BUILD_TARGETS -list only contains targets expected listed -on the command line or via calls to the -.BR Default () -function or method. -It does -.I not -contain all dependent targets that will be built as -a result of making the sure the explicitly-specified -targets are up to date. - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -COMMAND_LINE_TARGETS -A list of the targets explicitly specified on -the command line. -If there are no targets specified on the command line, -the list is empty. -This can be used, for example, -to take specific actions only -when a certain target or targets -is explicitly being built. - -Example: - -.ES -if 'foo' in COMMAND_LINE_TARGETS: - print "Don't forget to test the `foo' program!" -if 'special/program' in COMMAND_LINE_TARGETS: - SConscript('special') -.EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -DEFAULT_TARGETS -A list of the target -.I nodes -that have been specified using the -.BR Default () -function or method. -The elements of the list are nodes, -so you need to run them through the Python -.B str -function to get at the path name for each Node. - -Example: - -.ES -print str(DEFAULT_TARGETS[0]) -if 'foo' in map(str, DEFAULT_TARGETS): - print "Don't forget to test the `foo' program!" -.EE -.IP -The contents of the -.B DEFAULT_TARGETS -list change on on each successive call to the -.BR Default () -function: - -.ES -print map(str, DEFAULT_TARGETS) # originally [] -Default('foo') -print map(str, DEFAULT_TARGETS) # now a node ['foo'] -Default('bar') -print map(str, DEFAULT_TARGETS) # now a node ['foo', 'bar'] -Default(None) -print map(str, DEFAULT_TARGETS) # back to [] -.EE -.IP -Consequently, be sure to use -.B DEFAULT_TARGETS -only after you've made all of your -.BR Default () -calls, -or else simply be careful of the order -of these statements in your SConscript files -so that you don't look for a specific -default target before it's actually been added to the list. - -.SS Construction Variables -.\" XXX From Gary Ruben, 23 April 2002: -.\" I think it would be good to have an example with each construction -.\" variable description in the documentation. -.\" eg. -.\" CC The C compiler -.\" Example: env["CC"] = "c68x" -.\" Default: env["CC"] = "cc" -.\" -.\" CCCOM The command line ... -.\" Example: -.\" To generate the compiler line c68x -ps -qq -mr -o $TARGET $SOURCES -.\" env["CC"] = "c68x" -.\" env["CFLAGS"] = "-ps -qq -mr" -.\" env["CCCOM"] = "$CC $CFLAGS -o $TARGET $SOURCES -.\" Default: -.\" (I dunno what this is ;-) -A construction environment has an associated dictionary of -.I construction variables -that are used by built-in or user-supplied build rules. -Construction variables must follow the same rules for -Python identifiers: -the initial character must be an underscore or letter, -followed by any number of underscores, letters, or digits. - -A number of useful construction variables are automatically defined by -scons for each supported platform, and additional construction variables -can be defined by the user. The following is a list of the automatically -defined construction variables: - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -'\" BEGIN GENERATED CONSTRUCTION VARIABLE DESCRIPTIONS -'\" -'\" The descriptions below of the various SCons construction variables -'\" are generated from the .xml files that live next to the various -'\" Python modules in the build enginer library. If you're reading -'\" this [gnt]roff file with an eye towards patching this man page, -'\" you can still submit a diff against this text, but it will have to -'\" be translated to a diff against the underlying .xml file before the -'\" patch is actually accepted. If you do that yourself, it will make -'\" it easier to integrate the patch. -'\" -'\" BEGIN GENERATED CONSTRUCTION VARIABLE DESCRIPTIONS -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" - -.IP AR -The static library archiver. - -.IP ARCHITECTURE -Specifies the system architecture for which -the package is being built. -The default is the system architecture -of the machine on which SCons is running. -This is used to fill in the -.B Architecture: -field in an Ipkg -\fBcontrol\fP file, -and as part of the name of a generated RPM file. - -.IP ARCOM -The command line used to generate a static library from object files. - -.IP ARCOMSTR -The string displayed when an object file -is generated from an assembly-language source file. -If this is not set, then \fB$ARCOM\fP (the command line) is displayed. - -.ES -env = Environment(ARCOMSTR = "Archiving $TARGET") -.EE - -.IP ARFLAGS -General options passed to the static library archiver. - -.IP AS -The assembler. - -.IP ASCOM -The command line used to generate an object file -from an assembly-language source file. - -.IP ASCOMSTR -The string displayed when an object file -is generated from an assembly-language source file. -If this is not set, then \fB$ASCOM\fP (the command line) is displayed. - -.ES -env = Environment(ASCOMSTR = "Assembling $TARGET") -.EE - -.IP ASFLAGS -General options passed to the assembler. - -.IP ASPPCOM -The command line used to assemble an assembly-language -source file into an object file -after first running the file through the C preprocessor. -Any options specified -in the \fB$ASFLAGS\fP and \fB$CPPFLAGS\fP construction variables -are included on this command line. - -.IP ASPPCOMSTR -The string displayed when an object file -is generated from an assembly-language source file -after first running the file through the C preprocessor. -If this is not set, then \fB$ASPPCOM\fP (the command line) is displayed. - -.ES -env = Environment(ASPPCOMSTR = "Assembling $TARGET") -.EE - -.IP ASPPFLAGS -General options when an assembling an assembly-language -source file into an object file -after first running the file through the C preprocessor. -The default is to use the value of \fB$ASFLAGS\fP. - -.IP BIBTEX -The bibliography generator for the TeX formatter and typesetter and the -LaTeX structured formatter and typesetter. - -.IP BIBTEXCOM -The command line used to call the bibliography generator for the -TeX formatter and typesetter and the LaTeX structured formatter and -typesetter. - -.IP BIBTEXCOMSTR -The string displayed when generating a bibliography -for TeX or LaTeX. -If this is not set, then \fB$BIBTEXCOM\fP (the command line) is displayed. - -.ES -env = Environment(BIBTEXCOMSTR = "Generating bibliography $TARGET") -.EE - -.IP BIBTEXFLAGS -General options passed to the bibliography generator for the TeX formatter -and typesetter and the LaTeX structured formatter and typesetter. - -.IP BITKEEPER -The BitKeeper executable. - -.IP BITKEEPERCOM -The command line for -fetching source files using BitKeeper. - -.IP BITKEEPERCOMSTR -The string displayed when fetching -a source file using BitKeeper. -If this is not set, then \fB$BITKEEPERCOM\fP -(the command line) is displayed. - -.IP BITKEEPERGET -The command (\fB$BITKEEPER\fP) and subcommand -for fetching source files using BitKeeper. - -.IP BITKEEPERGETFLAGS -Options that are passed to the BitKeeper -.B get -subcommand. - -.IP BUILDERS -A dictionary mapping the names of the builders -available through this environment -to underlying Builder objects. -Builders named -Alias, CFile, CXXFile, DVI, Library, Object, PDF, PostScript, and Program -are available by default. -If you initialize this variable when an -Environment is created: - -.ES -env = Environment(BUILDERS = {'NewBuilder' : foo}) -.EE -.IP -the default Builders will no longer be available. -To use a new Builder object in addition to the default Builders, -add your new Builder object like this: - -.ES -env = Environment() -env.Append(BUILDERS = {'NewBuilder' : foo}) -.EE -.IP -or this: - -.ES -env = Environment() -env['BUILDERS]['NewBuilder'] = foo -.EE - -.IP CC -The C compiler. - -.IP CCCOM -The command line used to compile a C source file to a (static) object -file. Any options specified in the \fB$CFLAGS\fP, \fB$CCFLAGS\fP and -\fB$CPPFLAGS\fP construction variables are included on this command -line. - -.IP CCCOMSTR -The string displayed when a C source file -is compiled to a (static) object file. -If this is not set, then \fB$CCCOM\fP (the command line) is displayed. - -.ES -env = Environment(CCCOMSTR = "Compiling static object $TARGET") -.EE - -.IP CCFLAGS -General options that are passed to the C and C++ compilers. - -.IP CCPCHFLAGS -Options added to the compiler command line -to support building with precompiled headers. -The default value expands expands to the appropriate -Microsoft Visual C++ command-line options -when the \fB$PCH\fP construction variable is set. - -.IP CCPDBFLAGS -Options added to the compiler command line -to support storing debugging information in a -Microsoft Visual C++ PDB file. -The default value expands expands to appropriate -Microsoft Visual C++ command-line options -when the \fB$PDB\fP construction variable is set. - -The Visual C++ compiler option that SCons uses by default -to generate PDB information is \fB/Z7\fP. -This works correctly with parallel (\fB\-j\fP) builds -because it embeds the debug information in the intermediate object files, -as opposed to sharing a single PDB file between multiple object files. -This is also the only way to get debug information -embedded into a static library. -Using the \fB/Zi\fP instead may yield improved -link-time performance, -although parallel builds will no longer work. - -You can generate PDB files with the \fB/Zi\fP -switch by overriding the default \fB$CCPDBFLAGS\fP variable as follows: - -.ES -env['CCPDBFLAGS'] = ['${(PDB and "/Zi /Fd%s" % File(PDB)) or ""}'] -.EE -.IP -An alternative would be to use the \fB/Zi\fP -to put the debugging information in a separate \fB.pdb\fP -file for each object file by overriding -the \fB$CCPDBFLAGS\fP variable as follows: - -.ES -env['CCPDBFLAGS'] = '/Zi /Fd${TARGET}.pdb' -.EE - -.IP CCVERSION -The version number of the C compiler. -This may or may not be set, -depending on the specific C compiler being used. - -.IP CFILESUFFIX -The suffix for C source files. -This is used by the internal CFile builder -when generating C files from Lex (.l) or YACC (.y) input files. -The default suffix, of course, is -.B .c -(lower case). -On case-insensitive systems (like Windows), -SCons also treats -.B .C -(upper case) files -as C files. - -.IP CFLAGS -General options that are passed to the C compiler (C only; not C++). - -.IP CHANGE_SPECFILE -A hook for modifying the file that controls the packaging build -(the \fB.spec\fP for RPM, -the \fBcontrol\fP for Ipkg, -the \fB.wxs\fP for MSI). -If set, the function will be called -after the SCons template for the file has been written. -XXX - -.IP CHANGED_SOURCES -A reserved variable name -that may not be set or used in a construction environment. -(See "Variable Substitution," below.) - -.IP CHANGED_TARGETS -A reserved variable name -that may not be set or used in a construction environment. -(See "Variable Substitution," below.) - -.IP CHANGELOG -The name of a file containing the change log text -to be included in the package. -This is included as the -.B %changelog -section of the RPM -\fB.spec\fP file. - -.IP _concat -A function used to produce variables like \fB$_CPPINCFLAGS\fP. It takes -four or five -arguments: a prefix to concatenate onto each element, a list of -elements, a suffix to concatenate onto each element, an environment -for variable interpolation, and an optional function that will be -called to transform the list before concatenation. - -.ES -env['_CPPINCFLAGS'] = '$( ${_concat(INCPREFIX, CPPPATH, INCSUFFIX, __env__, RDirs)} $)', -.EE - -.IP CONFIGUREDIR -The name of the directory in which -Configure context test files are written. -The default is -.B .sconf_temp -in the top-level directory -containing the -.B SConstruct -file. - -.IP CONFIGURELOG -The name of the Configure context log file. -The default is -.B config.log -in the top-level directory -containing the -.B SConstruct -file. - -.IP _CPPDEFFLAGS -An automatically-generated construction variable -containing the C preprocessor command-line options -to define values. -The value of \fB$_CPPDEFFLAGS\fP is created -by appending \fB$CPPDEFPREFIX\fP and \fB$CPPDEFSUFFIX\fP -to the beginning and end -of each definition in \fB$CPPDEFINES\fP. - -.IP CPPDEFINES -A platform independent specification of C preprocessor definitions. -The definitions will be added to command lines -through the automatically-generated -\fB$_CPPDEFFLAGS\fP construction variable (see above), -which is constructed according to -the type of value of \fB$CPPDEFINES\fP: - -If \fB$CPPDEFINES\fP is a string, -the values of the -.BR $CPPDEFPREFIX and $CPPDEFSUFFIX -construction variables -will be added to the beginning and end. - -.ES -# Will add -Dxyz to POSIX compiler command lines, -# and /Dxyz to Microsoft Visual C++ command lines. -env = Environment(CPPDEFINES='xyz') -.EE -.IP -If \fB$CPPDEFINES\fP is a list, -the values of the -.BR $CPPDEFPREFIX and $CPPDEFSUFFIX -construction variables -will be appended to the beginning and end -of each element in the list. -If any element is a list or tuple, -then the first item is the name being -defined and the second item is its value: - -.ES -# Will add -DB=2 -DA to POSIX compiler command lines, -# and /DB=2 /DA to Microsoft Visual C++ command lines. -env = Environment(CPPDEFINES=[('B', 2), 'A']) -.EE -.IP -If \fB$CPPDEFINES\fP is a dictionary, -the values of the -.BR $CPPDEFPREFIX and $CPPDEFSUFFIX -construction variables -will be appended to the beginning and end -of each item from the dictionary. -The key of each dictionary item -is a name being defined -to the dictionary item's corresponding value; -if the value is -.BR None , -then the name is defined without an explicit value. -Note that the resulting flags are sorted by keyword -to ensure that the order of the options on the -command line is consistent each time -.B scons -is run. - -.ES -# Will add -DA -DB=2 to POSIX compiler command lines, -# and /DA /DB=2 to Microsoft Visual C++ command lines. -env = Environment(CPPDEFINES={'B':2, 'A':None}) -.EE - -.IP CPPDEFPREFIX -The prefix used to specify preprocessor definitions -on the C compiler command line. -This will be appended to the beginning of each definition -in the \fB$CPPDEFINES\fP construction variable -when the \fB$_CPPDEFFLAGS\fP variable is automatically generated. - -.IP CPPDEFSUFFIX -The suffix used to specify preprocessor definitions -on the C compiler command line. -This will be appended to the end of each definition -in the \fB$CPPDEFINES\fP construction variable -when the \fB$_CPPDEFFLAGS\fP variable is automatically generated. - -.IP CPPFLAGS -User-specified C preprocessor options. -These will be included in any command that uses the C preprocessor, -including not just compilation of C and C++ source files -via the \fB$CCCOM\fP, -.BR $SHCCCOM , -\fB$CXXCOM\fP and -\fB$SHCXXCOM\fP command lines, -but also the \fB$FORTRANPPCOM\fP, -.BR $SHFORTRANPPCOM , -\fB$F77PPCOM\fP and -\fB$SHF77PPCOM\fP command lines -used to compile a Fortran source file, -and the \fB$ASPPCOM\fP command line -used to assemble an assembly language source file, -after first running each file through the C preprocessor. -Note that this variable does -.I not -contain -.B \-I -(or similar) include search path options -that scons generates automatically from \fB$CPPPATH\fP. -See \fB$_CPPINCFLAGS\fP, below, -for the variable that expands to those options. - -.IP _CPPINCFLAGS -An automatically-generated construction variable -containing the C preprocessor command-line options -for specifying directories to be searched for include files. -The value of \fB$_CPPINCFLAGS\fP is created -by appending \fB$INCPREFIX\fP and \fB$INCSUFFIX\fP -to the beginning and end -of each directory in \fB$CPPPATH\fP. - -.IP CPPPATH -The list of directories that the C preprocessor will search for include -directories. The C/C++ implicit dependency scanner will search these -directories for include files. Don't explicitly put include directory -arguments in CCFLAGS or CXXFLAGS because the result will be non-portable -and the directories will not be searched by the dependency scanner. Note: -directory names in CPPPATH will be looked-up relative to the SConscript -directory when they are used in a command. To force -.B scons -to look-up a directory relative to the root of the source tree use #: - -.ES -env = Environment(CPPPATH='#/include') -.EE -.IP -The directory look-up can also be forced using the -.BR Dir () -function: - -.ES -include = Dir('include') -env = Environment(CPPPATH=include) -.EE -.IP -The directory list will be added to command lines -through the automatically-generated -.B $_CPPINCFLAGS -construction variable, -which is constructed by -appending the values of the -.BR $INCPREFIX and $INCSUFFIX -construction variables -to the beginning and end -of each directory in \fB$CPPPATH\fP. -Any command lines you define that need -the CPPPATH directory list should -include \fB$_CPPINCFLAGS\fP: - -.ES -env = Environment(CCCOM="my_compiler $_CPPINCFLAGS -c -o $TARGET $SOURCE") -.EE - -.IP CPPSUFFIXES -The list of suffixes of files that will be scanned -for C preprocessor implicit dependencies -(#include lines). -The default list is: - -.ES -[".c", ".C", ".cxx", ".cpp", ".c++", ".cc", - ".h", ".H", ".hxx", ".hpp", ".hh", - ".F", ".fpp", ".FPP", - ".m", ".mm", - ".S", ".spp", ".SPP"] -.EE - -.IP CVS -The CVS executable. - -.IP CVSCOFLAGS -Options that are passed to the CVS checkout subcommand. - -.IP CVSCOM -The command line used to -fetch source files from a CVS repository. - -.IP CVSCOMSTR -The string displayed when fetching -a source file from a CVS repository. -If this is not set, then \fB$CVSCOM\fP -(the command line) is displayed. - -.IP CVSFLAGS -General options that are passed to CVS. -By default, this is set to -.B "-d $CVSREPOSITORY" -to specify from where the files must be fetched. - -.IP CVSREPOSITORY -The path to the CVS repository. -This is referenced in the default -\fB$CVSFLAGS\fP value. - -.IP CXX -The C++ compiler. - -.IP CXXCOM -The command line used to compile a C++ source file to an object file. -Any options specified in the \fB$CXXFLAGS\fP and -\fB$CPPFLAGS\fP construction variables -are included on this command line. - -.IP CXXCOMSTR -The string displayed when a C++ source file -is compiled to a (static) object file. -If this is not set, then \fB$CXXCOM\fP (the command line) is displayed. - -.ES -env = Environment(CXXCOMSTR = "Compiling static object $TARGET") -.EE - -.IP CXXFILESUFFIX -The suffix for C++ source files. -This is used by the internal CXXFile builder -when generating C++ files from Lex (.ll) or YACC (.yy) input files. -The default suffix is -.BR .cc . -SCons also treats files with the suffixes -.BR .cpp , -.BR .cxx , -.BR .c++ , -and -.B .C++ -as C++ files, -and files with -.B .mm -suffixes as Objective C++ files. -On case-sensitive systems (Linux, UNIX, and other POSIX-alikes), -SCons also treats -.B .C -(upper case) files -as C++ files. - -.IP CXXFLAGS -General options that are passed to the C++ compiler. -By default, this includes the value of \fB$CCFLAGS\fP, -so that setting \fB$CCFLAGS\fP affects both C and C++ compilation. -If you want to add C++-specific flags, -you must set or override the value of \fB$CXXFLAGS\fP. - -.IP CXXVERSION -The version number of the C++ compiler. -This may or may not be set, -depending on the specific C++ compiler being used. - -.IP DESCRIPTION -A long description of the project being packaged. -This is included in the relevant section -of the file that controls the packaging build. - -.IP DESCRIPTION_lang -A language-specific long description for -the specified \fIlang\fP. -This is used to populate a -.B "%description -l" -section of an RPM -\fB.spec\fP file. - -.IP Dir -A function that converts a string -into a Dir instance relative to the target being built. - -.IP Dirs -A function that converts a list of strings -into a list of Dir instances relative to the target being built. - -.IP DSUFFIXES -The list of suffixes of files that will be scanned -for imported D package files. -The default list is: - -.ES -['.d'] -.EE - -.IP DVIPDF -The TeX DVI file to PDF file converter. - -.IP DVIPDFCOM -The command line used to convert TeX DVI files into a PDF file. - -.IP DVIPDFCOMSTR -The string displayed when a TeX DVI file -is converted into a PDF file. -If this is not set, then \fB$DVIPDFCOM\fP (the command line) is displayed. - -.IP DVIPDFFLAGS -General options passed to the TeX DVI file to PDF file converter. - -.IP DVIPS -The TeX DVI file to PostScript converter. - -.IP DVIPSFLAGS -General options passed to the TeX DVI file to PostScript converter. - -.IP ENV -A dictionary of environment variables -to use when invoking commands. When -\fB$ENV\fP is used in a command all list -values will be joined using the path separator and any other non-string -values will simply be coerced to a string. -Note that, by default, -.B scons -does -.I not -propagate the environment in force when you -execute -.B scons -to the commands used to build target files. -This is so that builds will be guaranteed -repeatable regardless of the environment -variables set at the time -.B scons -is invoked. - -If you want to propagate your -environment variables -to the commands executed -to build target files, -you must do so explicitly: - -.ES -import os -env = Environment(ENV = os.environ) -.EE -.IP -Note that you can choose only to propagate -certain environment variables. -A common example is -the system -.B PATH -environment variable, -so that -.B scons -uses the same utilities -as the invoking shell (or other process): - -.ES -import os -env = Environment(ENV = {'PATH' : os.environ['PATH']}) -.EE - -.IP ESCAPE -A function that will be called to escape shell special characters in -command lines. The function should take one argument: the command line -string to escape; and should return the escaped command line. - -.IP F77 -The Fortran 77 compiler. -You should normally set the \fB$FORTRAN\fP variable, -which specifies the default Fortran compiler -for all Fortran versions. -You only need to set \fB$F77\fP if you need to use a specific compiler -or compiler version for Fortran 77 files. - -.IP F77COM -The command line used to compile a Fortran 77 source file to an object file. -You only need to set \fB$F77COM\fP if you need to use a specific -command line for Fortran 77 files. -You should normally set the \fB$FORTRANCOM\fP variable, -which specifies the default command line -for all Fortran versions. - -.IP F77COMSTR -The string displayed when a Fortran 77 source file -is compiled to an object file. -If this is not set, then \fB$F77COM\fP or \fB$FORTRANCOM\fP -(the command line) is displayed. - -.IP F77FILESUFFIXES -The list of file extensions for which the F77 dialect will be used. By -default, this is ['.f77'] - -.IP F77FLAGS -General user-specified options that are passed to the Fortran 77 compiler. -Note that this variable does -.I not -contain -.B \-I -(or similar) include search path options -that scons generates automatically from \fB$F77PATH\fP. -See -.B $_F77INCFLAGS -below, -for the variable that expands to those options. -You only need to set \fB$F77FLAGS\fP if you need to define specific -user options for Fortran 77 files. -You should normally set the \fB$FORTRANFLAGS\fP variable, -which specifies the user-specified options -passed to the default Fortran compiler -for all Fortran versions. - -.IP _F77INCFLAGS -An automatically-generated construction variable -containing the Fortran 77 compiler command-line options -for specifying directories to be searched for include files. -The value of \fB$_F77INCFLAGS\fP is created -by appending \fB$INCPREFIX\fP and \fB$INCSUFFIX\fP -to the beginning and end -of each directory in \fB$F77PATH\fP. - -.IP F77PATH -The list of directories that the Fortran 77 compiler will search for include -directories. The implicit dependency scanner will search these -directories for include files. Don't explicitly put include directory -arguments in \fB$F77FLAGS\fP because the result will be non-portable -and the directories will not be searched by the dependency scanner. Note: -directory names in \fB$F77PATH\fP will be looked-up relative to the SConscript -directory when they are used in a command. To force -.B scons -to look-up a directory relative to the root of the source tree use #: -You only need to set \fB$F77PATH\fP if you need to define a specific -include path for Fortran 77 files. -You should normally set the \fB$FORTRANPATH\fP variable, -which specifies the include path -for the default Fortran compiler -for all Fortran versions. - -.ES -env = Environment(F77PATH='#/include') -.EE -.IP -The directory look-up can also be forced using the -.BR Dir () -function: - -.ES -include = Dir('include') -env = Environment(F77PATH=include) -.EE -.IP -The directory list will be added to command lines -through the automatically-generated -.B $_F77INCFLAGS -construction variable, -which is constructed by -appending the values of the -.BR $INCPREFIX and $INCSUFFIX -construction variables -to the beginning and end -of each directory in \fB$F77PATH\fP. -Any command lines you define that need -the F77PATH directory list should -include \fB$_F77INCFLAGS\fP: - -.ES -env = Environment(F77COM="my_compiler $_F77INCFLAGS -c -o $TARGET $SOURCE") -.EE - -.IP F77PPCOM -The command line used to compile a Fortran 77 source file to an object file -after first running the file through the C preprocessor. -Any options specified in the \fB$F77FLAGS\fP and \fB$CPPFLAGS\fP construction variables -are included on this command line. -You only need to set \fB$F77PPCOM\fP if you need to use a specific -C-preprocessor command line for Fortran 77 files. -You should normally set the \fB$FORTRANPPCOM\fP variable, -which specifies the default C-preprocessor command line -for all Fortran versions. - -.IP F77PPCOMSTR -The string displayed when a Fortran 77 source file -is compiled to an object file -after first running the file through the C preprocessor. -If this is not set, then \fB$F77PPCOM\fP or \fB$FORTRANPPCOM\fP -(the command line) is displayed. - -.IP F77PPFILESUFFIXES -The list of file extensions for which the compilation + preprocessor pass for -F77 dialect will be used. By default, this is empty - -.IP F90 -The Fortran 90 compiler. -You should normally set the \fB$FORTRAN\fP variable, -which specifies the default Fortran compiler -for all Fortran versions. -You only need to set \fB$F90\fP if you need to use a specific compiler -or compiler version for Fortran 90 files. - -.IP F90COM -The command line used to compile a Fortran 90 source file to an object file. -You only need to set \fB$F90COM\fP if you need to use a specific -command line for Fortran 90 files. -You should normally set the \fB$FORTRANCOM\fP variable, -which specifies the default command line -for all Fortran versions. - -.IP F90COMSTR -The string displayed when a Fortran 90 source file -is compiled to an object file. -If this is not set, then \fB$F90COM\fP or \fB$FORTRANCOM\fP -(the command line) is displayed. - -.IP F90FILESUFFIXES -The list of file extensions for which the F90 dialect will be used. By -default, this is ['.f90'] - -.IP F90FLAGS -General user-specified options that are passed to the Fortran 90 compiler. -Note that this variable does -.I not -contain -.B \-I -(or similar) include search path options -that scons generates automatically from \fB$F90PATH\fP. -See -.B $_F90INCFLAGS -below, -for the variable that expands to those options. -You only need to set \fB$F90FLAGS\fP if you need to define specific -user options for Fortran 90 files. -You should normally set the \fB$FORTRANFLAGS\fP variable, -which specifies the user-specified options -passed to the default Fortran compiler -for all Fortran versions. - -.IP _F90INCFLAGS -An automatically-generated construction variable -containing the Fortran 90 compiler command-line options -for specifying directories to be searched for include files. -The value of \fB$_F90INCFLAGS\fP is created -by appending \fB$INCPREFIX\fP and \fB$INCSUFFIX\fP -to the beginning and end -of each directory in \fB$F90PATH\fP. - -.IP F90PATH -The list of directories that the Fortran 90 compiler will search for include -directories. The implicit dependency scanner will search these -directories for include files. Don't explicitly put include directory -arguments in \fB$F90FLAGS\fP because the result will be non-portable -and the directories will not be searched by the dependency scanner. Note: -directory names in \fB$F90PATH\fP will be looked-up relative to the SConscript -directory when they are used in a command. To force -.B scons -to look-up a directory relative to the root of the source tree use #: -You only need to set \fB$F90PATH\fP if you need to define a specific -include path for Fortran 90 files. -You should normally set the \fB$FORTRANPATH\fP variable, -which specifies the include path -for the default Fortran compiler -for all Fortran versions. - -.ES -env = Environment(F90PATH='#/include') -.EE -.IP -The directory look-up can also be forced using the -.BR Dir () -function: - -.ES -include = Dir('include') -env = Environment(F90PATH=include) -.EE -.IP -The directory list will be added to command lines -through the automatically-generated -.B $_F90INCFLAGS -construction variable, -which is constructed by -appending the values of the -.BR $INCPREFIX and $INCSUFFIX -construction variables -to the beginning and end -of each directory in \fB$F90PATH\fP. -Any command lines you define that need -the F90PATH directory list should -include \fB$_F90INCFLAGS\fP: - -.ES -env = Environment(F90COM="my_compiler $_F90INCFLAGS -c -o $TARGET $SOURCE") -.EE - -.IP F90PPCOM -The command line used to compile a Fortran 90 source file to an object file -after first running the file through the C preprocessor. -Any options specified in the \fB$F90FLAGS\fP and \fB$CPPFLAGS\fP construction variables -are included on this command line. -You only need to set \fB$F90PPCOM\fP if you need to use a specific -C-preprocessor command line for Fortran 90 files. -You should normally set the \fB$FORTRANPPCOM\fP variable, -which specifies the default C-preprocessor command line -for all Fortran versions. - -.IP F90PPCOMSTR -The string displayed when a Fortran 90 source file -is compiled after first running the file through the C preprocessor. -If this is not set, then \fB$F90PPCOM\fP or \fB$FORTRANPPCOM\fP -(the command line) is displayed. - -.IP F90PPFILESUFFIXES -The list of file extensions for which the compilation + preprocessor pass for -F90 dialect will be used. By default, this is empty - -.IP F95 -The Fortran 95 compiler. -You should normally set the \fB$FORTRAN\fP variable, -which specifies the default Fortran compiler -for all Fortran versions. -You only need to set \fB$F95\fP if you need to use a specific compiler -or compiler version for Fortran 95 files. - -.IP F95COM -The command line used to compile a Fortran 95 source file to an object file. -You only need to set \fB$F95COM\fP if you need to use a specific -command line for Fortran 95 files. -You should normally set the \fB$FORTRANCOM\fP variable, -which specifies the default command line -for all Fortran versions. - -.IP F95COMSTR -The string displayed when a Fortran 95 source file -is compiled to an object file. -If this is not set, then \fB$F95COM\fP or \fB$FORTRANCOM\fP -(the command line) is displayed. - -.IP F95FILESUFFIXES -The list of file extensions for which the F95 dialect will be used. By -default, this is ['.f95'] - -.IP F95FLAGS -General user-specified options that are passed to the Fortran 95 compiler. -Note that this variable does -.I not -contain -.B \-I -(or similar) include search path options -that scons generates automatically from \fB$F95PATH\fP. -See -.B $_F95INCFLAGS -below, -for the variable that expands to those options. -You only need to set \fB$F95FLAGS\fP if you need to define specific -user options for Fortran 95 files. -You should normally set the \fB$FORTRANFLAGS\fP variable, -which specifies the user-specified options -passed to the default Fortran compiler -for all Fortran versions. - -.IP _F95INCFLAGS -An automatically-generated construction variable -containing the Fortran 95 compiler command-line options -for specifying directories to be searched for include files. -The value of \fB$_F95INCFLAGS\fP is created -by appending \fB$INCPREFIX\fP and \fB$INCSUFFIX\fP -to the beginning and end -of each directory in \fB$F95PATH\fP. - -.IP F95PATH -The list of directories that the Fortran 95 compiler will search for include -directories. The implicit dependency scanner will search these -directories for include files. Don't explicitly put include directory -arguments in \fB$F95FLAGS\fP because the result will be non-portable -and the directories will not be searched by the dependency scanner. Note: -directory names in \fB$F95PATH\fP will be looked-up relative to the SConscript -directory when they are used in a command. To force -.B scons -to look-up a directory relative to the root of the source tree use #: -You only need to set \fB$F95PATH\fP if you need to define a specific -include path for Fortran 95 files. -You should normally set the \fB$FORTRANPATH\fP variable, -which specifies the include path -for the default Fortran compiler -for all Fortran versions. - -.ES -env = Environment(F95PATH='#/include') -.EE -.IP -The directory look-up can also be forced using the -.BR Dir () -function: - -.ES -include = Dir('include') -env = Environment(F95PATH=include) -.EE -.IP -The directory list will be added to command lines -through the automatically-generated -.B $_F95INCFLAGS -construction variable, -which is constructed by -appending the values of the -.BR $INCPREFIX and $INCSUFFIX -construction variables -to the beginning and end -of each directory in \fB$F95PATH\fP. -Any command lines you define that need -the F95PATH directory list should -include \fB$_F95INCFLAGS\fP: - -.ES -env = Environment(F95COM="my_compiler $_F95INCFLAGS -c -o $TARGET $SOURCE") -.EE - -.IP F95PPCOM -The command line used to compile a Fortran 95 source file to an object file -after first running the file through the C preprocessor. -Any options specified in the \fB$F95FLAGS\fP and \fB$CPPFLAGS\fP construction variables -are included on this command line. -You only need to set \fB$F95PPCOM\fP if you need to use a specific -C-preprocessor command line for Fortran 95 files. -You should normally set the \fB$FORTRANPPCOM\fP variable, -which specifies the default C-preprocessor command line -for all Fortran versions. - -.IP F95PPCOMSTR -The string displayed when a Fortran 95 source file -is compiled to an object file -after first running the file through the C preprocessor. -If this is not set, then \fB$F95PPCOM\fP or \fB$FORTRANPPCOM\fP -(the command line) is displayed. - -.IP F95PPFILESUFFIXES -The list of file extensions for which the compilation + preprocessor pass for -F95 dialect will be used. By default, this is empty - -.IP File -A function that converts a string into a File instance relative to the -target being built. - -.IP FORTRAN -The default Fortran compiler -for all versions of Fortran. - -.IP FORTRANCOM -The command line used to compile a Fortran source file to an object file. -By default, any options specified -in the \fB$FORTRANFLAGS\fP, -.BR $CPPFLAGS , -.BR $_CPPDEFFLAGS , -\fB$_FORTRANMODFLAG\fP, and -\fB$_FORTRANINCFLAGS\fP construction variables -are included on this command line. - -.IP FORTRANCOMSTR -The string displayed when a Fortran source file -is compiled to an object file. -If this is not set, then \fB$FORTRANCOM\fP -(the command line) is displayed. - -.IP FORTRANFILESUFFIXES -The list of file extensions for which the FORTRAN dialect will be used. By -default, this is ['.f', '.for', '.ftn'] - -.IP FORTRANFLAGS -General user-specified options that are passed to the Fortran compiler. -Note that this variable does -.I not -contain -.B \-I -(or similar) include or module search path options -that scons generates automatically from \fB$FORTRANPATH\fP. -See -.BR $_FORTRANINCFLAGS\fP and \fB$_FORTRANMODFLAG , -below, -for the variables that expand those options. - -.IP _FORTRANINCFLAGS -An automatically-generated construction variable -containing the Fortran compiler command-line options -for specifying directories to be searched for include -files and module files. -The value of \fB$_FORTRANINCFLAGS\fP is created -by prepending/appending \fB$INCPREFIX\fP and \fB$INCSUFFIX\fP -to the beginning and end -of each directory in \fB$FORTRANPATH\fP. - -.IP FORTRANMODDIR -Directory location where the Fortran compiler should place -any module files it generates. This variable is empty, by default. Some -Fortran compilers will internally append this directory in the search path -for module files, as well. - -.IP FORTRANMODDIRPREFIX -The prefix used to specify a module directory on the Fortran compiler command -line. -This will be appended to the beginning of the directory -in the \fB$FORTRANMODDIR\fP construction variables -when the \fB$_FORTRANMODFLAG\fP variables is automatically generated. - -.IP FORTRANMODDIRSUFFIX -The suffix used to specify a module directory on the Fortran compiler command -line. -This will be appended to the beginning of the directory -in the \fB$FORTRANMODDIR\fP construction variables -when the \fB$_FORTRANMODFLAG\fP variables is automatically generated. - -.IP _FORTRANMODFLAG -An automatically-generated construction variable -containing the Fortran compiler command-line option -for specifying the directory location where the Fortran -compiler should place any module files that happen to get -generated during compilation. -The value of \fB$_FORTRANMODFLAG\fP is created -by prepending/appending \fB$FORTRANMODDIRPREFIX\fP and -.B $FORTRANMODDIRSUFFIX -to the beginning and end of the directory in \fB$FORTRANMODDIR\fP. - -.IP FORTRANMODPREFIX -The module file prefix used by the Fortran compiler. SCons assumes that -the Fortran compiler follows the quasi-standard naming convention for -module files of -.BR module_name.mod . -As a result, this variable is left empty, by default. For situations in -which the compiler does not necessarily follow the normal convention, -the user may use this variable. Its value will be appended to every -module file name as scons attempts to resolve dependencies. - -.IP FORTRANMODSUFFIX -The module file suffix used by the Fortran compiler. SCons assumes that -the Fortran compiler follows the quasi-standard naming convention for -module files of -.BR module_name.mod . -As a result, this variable is set to ".mod", by default. For situations -in which the compiler does not necessarily follow the normal convention, -the user may use this variable. Its value will be appended to every -module file name as scons attempts to resolve dependencies. - -.IP FORTRANPATH -The list of directories that the Fortran compiler will search for -include files and (for some compilers) module files. The Fortran implicit -dependency scanner will search these directories for include files (but -not module files since they are autogenerated and, as such, may not -actually exist at the time the scan takes place). Don't explicitly put -include directory arguments in FORTRANFLAGS because the result will be -non-portable and the directories will not be searched by the dependency -scanner. Note: directory names in FORTRANPATH will be looked-up relative -to the SConscript directory when they are used in a command. To force -.B scons -to look-up a directory relative to the root of the source tree use #: - -.ES -env = Environment(FORTRANPATH='#/include') -.EE -.IP -The directory look-up can also be forced using the -.BR Dir () -function: - -.ES -include = Dir('include') -env = Environment(FORTRANPATH=include) -.EE -.IP -The directory list will be added to command lines -through the automatically-generated -.B $_FORTRANINCFLAGS -construction variable, -which is constructed by -appending the values of the -.BR $INCPREFIX and $INCSUFFIX -construction variables -to the beginning and end -of each directory in \fB$FORTRANPATH\fP. -Any command lines you define that need -the FORTRANPATH directory list should -include \fB$_FORTRANINCFLAGS\fP: - -.ES -env = Environment(FORTRANCOM="my_compiler $_FORTRANINCFLAGS -c -o $TARGET $SOURCE") -.EE - -.IP FORTRANPPCOM -The command line used to compile a Fortran source file to an object file -after first running the file through the C preprocessor. -By default, any options specified in the \fB$FORTRANFLAGS\fP, -.BR $CPPFLAGS , -.BR $_CPPDEFFLAGS , -\fB$_FORTRANMODFLAG\fP, and -.B $_FORTRANINCFLAGS -construction variables are included on this command line. - -.IP FORTRANPPCOMSTR -The string displayed when a Fortran source file -is compiled to an object file -after first running the file through the C preprocessor. -If this is not set, then \fB$FORTRANPPCOM\fP -(the command line) is displayed. - -.IP FORTRANPPFILESUFFIXES -The list of file extensions for which the compilation + preprocessor pass for -FORTRAN dialect will be used. By default, this is ['.fpp', '.FPP'] - -.IP FORTRANSUFFIXES -The list of suffixes of files that will be scanned -for Fortran implicit dependencies -(INCLUDE lines and USE statements). -The default list is: - -.ES -[".f", ".F", ".for", ".FOR", ".ftn", ".FTN", ".fpp", ".FPP", -".f77", ".F77", ".f90", ".F90", ".f95", ".F95"] -.EE - -.IP FRAMEWORKPATH -On Mac OS X with gcc, -a list containing the paths to search for frameworks. -Used by the compiler to find framework-style includes like -#include <Fmwk/Header.h>. -Used by the linker to find user-specified frameworks when linking (see -.BR $FRAMEWORKS ). -For example: - -.ES - env.AppendUnique(FRAMEWORKPATH='#myframeworkdir') -.EE -.IP -will add - -.ES - ... -Fmyframeworkdir -.EE -.IP -to the compiler and linker command lines. - -.IP _FRAMEWORKPATH -On Mac OS X with gcc, an automatically-generated construction variable -containing the linker command-line options corresponding to -.BR $FRAMEWORKPATH . - -.IP FRAMEWORKPATHPREFIX -On Mac OS X with gcc, the prefix to be used for the FRAMEWORKPATH entries. -(see \fB$FRAMEWORKPATH\fP). -The default value is -.BR \-F . - -.IP FRAMEWORKPREFIX -On Mac OS X with gcc, -the prefix to be used for linking in frameworks -(see \fB$FRAMEWORKS\fP). -The default value is -.BR \-framework . - -.IP _FRAMEWORKS -On Mac OS X with gcc, -an automatically-generated construction variable -containing the linker command-line options -for linking with FRAMEWORKS. - -.IP FRAMEWORKS -On Mac OS X with gcc, a list of the framework names to be linked into a -program or shared library or bundle. -The default value is the empty list. -For example: - -.ES - env.AppendUnique(FRAMEWORKS=Split('System Cocoa SystemConfiguration')) -.EE -.IP - -.IP FRAMEWORKSFLAGS -On Mac OS X with gcc, -general user-supplied frameworks options to be added at -the end of a command -line building a loadable module. -(This has been largely superseded by -the \fB$FRAMEWORKPATH\fP, \fB$FRAMEWORKPATHPREFIX\fP, -\fB$FRAMEWORKPREFIX\fP and \fB$FRAMEWORKS\fP variables -described above.) - -.IP GS -The Ghostscript program used to convert PostScript to PDF files. - -.IP GSCOM -The Ghostscript command line used to convert PostScript to PDF files. - -.IP GSCOMSTR -The string displayed when -Ghostscript is used to convert -a PostScript file to a PDF file. -If this is not set, then \fB$GSCOM\fP (the command line) is displayed. - -.IP GSFLAGS -General options passed to the Ghostscript program -when converting PostScript to PDF files. - -.IP HOST_ARCH -Sets the host architecture for Visual Studio compiler. If not set, -default to the detected host architecture: note that this may depend -on the python you are using. -This variable must be passed as an argument to the Environment() -constructor; setting it later has no effect. - -Valid values are the same as for \fB$TARGET_ARCH\fP. - -This is currently only used on Windows, but in the future it will be -used on other OSes as well. - -.IP HOST_OS - The name of the host operating system used to create the Environment. - If a platform is specified when creating the Environment, then - that Platform's logic will handle setting this value. - This value is immutable, and should not be changed by the user after - the Environment is initialized. - Currently only set for Win32. - -.IP IDLSUFFIXES -The list of suffixes of files that will be scanned -for IDL implicit dependencies -(#include or import lines). -The default list is: - -.ES -[".idl", ".IDL"] -.EE - -.IP IMPLICIT_COMMAND_DEPENDENCIES -Controls whether or not SCons will -add implicit dependencies for the commands -executed to build targets. - -By default, SCons will add -to each target -an implicit dependency on the command -represented by the first argument on any -command line it executes. -The specific file for the dependency is -found by searching the -.I PATH -variable in the -.I ENV -environment used to execute the command. - -If the construction variable -.B $IMPLICIT_COMMAND_DEPENDENCIES -is set to a false value -.RB ( None , -.BR False , -.BR 0 , -etc.), -then the implicit dependency will -not be added to the targets -built with that construction environment. - -.ES -env = Environment(IMPLICIT_COMMAND_DEPENDENCIES = 0) -.EE - -.IP INCPREFIX -The prefix used to specify an include directory on the C compiler command -line. -This will be appended to the beginning of each directory -in the \fB$CPPPATH\fP and \fB$FORTRANPATH\fP construction variables -when the \fB$_CPPINCFLAGS\fP and \fB$_FORTRANINCFLAGS\fP -variables are automatically generated. - -.IP INCSUFFIX -The suffix used to specify an include directory on the C compiler command -line. -This will be appended to the end of each directory -in the \fB$CPPPATH\fP and \fB$FORTRANPATH\fP construction variables -when the \fB$_CPPINCFLAGS\fP and \fB$_FORTRANINCFLAGS\fP -variables are automatically generated. - -.IP INSTALL -A function to be called to install a file into a -destination file name. -The default function copies the file into the destination -(and sets the destination file's mode and permission bits -to match the source file's). -The function takes the following arguments: - -.ES -def install(dest, source, env): -.EE -.IP -.I dest -is the path name of the destination file. -.I source -is the path name of the source file. -.I env -is the construction environment -(a dictionary of construction values) -in force for this file installation. - -.IP INSTALLSTR -The string displayed when a file is -installed into a destination file name. -The default is: -.ES -Install file: "$SOURCE" as "$TARGET" -.EE - -.IP INTEL_C_COMPILER_VERSION -Set by the "intelc" Tool -to the major version number of the Intel C compiler -selected for use. - -.IP JAR -The Java archive tool. - -.IP JARCHDIR -The directory to which the Java archive tool should change -(using the -.B \-C -option). - -.IP JARCOM -The command line used to call the Java archive tool. - -.IP JARCOMSTR -The string displayed when the Java archive tool -is called -If this is not set, then \fB$JARCOM\fP (the command line) is displayed. - -.ES -env = Environment(JARCOMSTR = "JARchiving $SOURCES into $TARGET") -.EE - -.IP JARFLAGS -General options passed to the Java archive tool. -By default this is set to -.B cf -to create the necessary -.B jar -file. - -.IP JARSUFFIX -The suffix for Java archives: -.B .jar -by default. - -.IP JAVABOOTCLASSPATH -Specifies the list of directories that -will be added to the -&javac; command line -via the \fB\-bootclasspath\fP option. -The individual directory names will be -separated by the operating system's path separate character -(\fB:\fP on UNIX/Linux/POSIX, -\fB;\fP on Windows). - -.IP JAVAC -The Java compiler. - -.IP JAVACCOM -The command line used to compile a directory tree containing -Java source files to -corresponding Java class files. -Any options specified in the \fB$JAVACFLAGS\fP construction variable -are included on this command line. - -.IP JAVACCOMSTR -The string displayed when compiling -a directory tree of Java source files to -corresponding Java class files. -If this is not set, then \fB$JAVACCOM\fP (the command line) is displayed. - -.ES -env = Environment(JAVACCOMSTR = "Compiling class files $TARGETS from $SOURCES") -.EE - -.IP JAVACFLAGS -General options that are passed to the Java compiler. - -.IP JAVACLASSDIR -The directory in which Java class files may be found. -This is stripped from the beginning of any Java .class -file names supplied to the -.B JavaH -builder. - -.IP JAVACLASSPATH -Specifies the list of directories that -will be searched for Java -\fB.class\fP file. -The directories in this list will be added to the -&javac; and &javah; command lines -via the \fB\-classpath\fP option. -The individual directory names will be -separated by the operating system's path separate character -(\fB:\fP on UNIX/Linux/POSIX, -\fB;\fP on Windows). - -Note that this currently just adds the specified -directory via the \fB\-classpath\fP option. -&SCons; does not currently search the -\fB$JAVACLASSPATH\fP directories for dependency -\fB.class\fP files. - -.IP JAVACLASSSUFFIX -The suffix for Java class files; -.B .class -by default. - -.IP JAVAH -The Java generator for C header and stub files. - -.IP JAVAHCOM -The command line used to generate C header and stub files -from Java classes. -Any options specified in the \fB$JAVAHFLAGS\fP construction variable -are included on this command line. - -.IP JAVAHCOMSTR -The string displayed when C header and stub files -are generated from Java classes. -If this is not set, then \fB$JAVAHCOM\fP (the command line) is displayed. - -.ES -env = Environment(JAVAHCOMSTR = "Generating header/stub file(s) $TARGETS from $SOURCES") -.EE - -.IP JAVAHFLAGS -General options passed to the C header and stub file generator -for Java classes. - -.IP JAVASOURCEPATH -Specifies the list of directories that -will be searched for input -\fB.java\fP file. -The directories in this list will be added to the -&javac; command line -via the \fB\-sourcepath\fP option. -The individual directory names will be -separated by the operating system's path separate character -(\fB:\fP on UNIX/Linux/POSIX, -\fB;\fP on Windows). - -Note that this currently just adds the specified -directory via the \fB\-sourcepath\fP option. -&SCons; does not currently search the -\fB$JAVASOURCEPATH\fP directories for dependency -\fB.java\fP files. - -.IP JAVASUFFIX -The suffix for Java files; -.B .java -by default. - -.IP JAVAVERSION -Specifies the Java version being used by the \fBJava\fP() builder. -This is \fInot\fP currently used to select one -version of the Java compiler vs. another. -Instead, you should set this to specify the version of Java -supported by your &javac; compiler. -The default is \fB1.4\fP. - -This is sometimes necessary because -Java 1.5 changed the file names that are created -for nested anonymous inner classes, -which can cause a mismatch with the files -that &SCons; expects will be generated by the &javac; compiler. -Setting \fB$JAVAVERSION\fP to \fB1.5\fP -(or \fB1.6\fP, as appropriate) -can make &SCons; realize that a Java 1.5 or 1.6 -build is actually up to date. - -.IP LATEX -The LaTeX structured formatter and typesetter. - -.IP LATEXCOM -The command line used to call the LaTeX structured formatter and typesetter. - -.IP LATEXCOMSTR -The string displayed when calling -the LaTeX structured formatter and typesetter. -If this is not set, then \fB$LATEXCOM\fP (the command line) is displayed. - -.ES -env = Environment(LATEXCOMSTR = "Building $TARGET from LaTeX input $SOURCES") -.EE - -.IP LATEXFLAGS -General options passed to the LaTeX structured formatter and typesetter. - -.IP LATEXRETRIES -The maximum number of times that LaTeX -will be re-run if the -.B .log -generated by the \fB$LATEXCOM\fP command -indicates that there are undefined references. -The default is to try to resolve undefined references -by re-running LaTeX up to three times. - -.IP LATEXSUFFIXES -The list of suffixes of files that will be scanned -for LaTeX implicit dependencies -(\fB\\include\fP or \fB\\import\fP files). -The default list is: - -.ES -[".tex", ".ltx", ".latex"] -.EE - -.IP LDMODULE -The linker for building loadable modules. -By default, this is the same as \fB$SHLINK\fP. - -.IP LDMODULECOM -The command line for building loadable modules. -On Mac OS X, this uses the \fB$LDMODULE\fP, -\fB$LDMODULEFLAGS\fP and -\fB$FRAMEWORKSFLAGS\fP variables. -On other systems, this is the same as \fB$SHLINK\fP. - -.IP LDMODULECOMSTR -The string displayed when building loadable modules. -If this is not set, then \fB$LDMODULECOM\fP (the command line) is displayed. - -.IP LDMODULEFLAGS -General user options passed to the linker for building loadable modules. - -.IP LDMODULEPREFIX -The prefix used for loadable module file names. -On Mac OS X, this is null; -on other systems, this is -the same as \fB$SHLIBPREFIX\fP. - -.IP LDMODULESUFFIX -The suffix used for loadable module file names. -On Mac OS X, this is null; -on other systems, this is -the same as $SHLIBSUFFIX. - -.IP LEX -The lexical analyzer generator. - -.IP LEXCOM -The command line used to call the lexical analyzer generator -to generate a source file. - -.IP LEXCOMSTR -The string displayed when generating a source file -using the lexical analyzer generator. -If this is not set, then \fB$LEXCOM\fP (the command line) is displayed. - -.ES -env = Environment(LEXCOMSTR = "Lex'ing $TARGET from $SOURCES") -.EE - -.IP LEXFLAGS -General options passed to the lexical analyzer generator. - -.IP _LIBDIRFLAGS -An automatically-generated construction variable -containing the linker command-line options -for specifying directories to be searched for library. -The value of \fB$_LIBDIRFLAGS\fP is created -by appending \fB$LIBDIRPREFIX\fP and \fB$LIBDIRSUFFIX\fP -to the beginning and end -of each directory in \fB$LIBPATH\fP. - -.IP LIBDIRPREFIX -The prefix used to specify a library directory on the linker command line. -This will be appended to the beginning of each directory -in the \fB$LIBPATH\fP construction variable -when the \fB$_LIBDIRFLAGS\fP variable is automatically generated. - -.IP LIBDIRSUFFIX -The suffix used to specify a library directory on the linker command line. -This will be appended to the end of each directory -in the \fB$LIBPATH\fP construction variable -when the \fB$_LIBDIRFLAGS\fP variable is automatically generated. - -.IP LIBEMITTER -TODO - -.IP _LIBFLAGS -An automatically-generated construction variable -containing the linker command-line options -for specifying libraries to be linked with the resulting target. -The value of \fB$_LIBFLAGS\fP is created -by appending \fB$LIBLINKPREFIX\fP and \fB$LIBLINKSUFFIX\fP -to the beginning and end -of each filename in \fB$LIBS\fP. - -.IP LIBLINKPREFIX -The prefix used to specify a library to link on the linker command line. -This will be appended to the beginning of each library -in the \fB$LIBS\fP construction variable -when the \fB$_LIBFLAGS\fP variable is automatically generated. - -.IP LIBLINKSUFFIX -The suffix used to specify a library to link on the linker command line. -This will be appended to the end of each library -in the \fB$LIBS\fP construction variable -when the \fB$_LIBFLAGS\fP variable is automatically generated. - -.IP LIBPATH -The list of directories that will be searched for libraries. -The implicit dependency scanner will search these -directories for include files. Don't explicitly put include directory -arguments in \fB$LINKFLAGS\fP or \fB$SHLINKFLAGS\fP -because the result will be non-portable -and the directories will not be searched by the dependency scanner. Note: -directory names in LIBPATH will be looked-up relative to the SConscript -directory when they are used in a command. To force -.B scons -to look-up a directory relative to the root of the source tree use #: - -.ES -env = Environment(LIBPATH='#/libs') -.EE -.IP -The directory look-up can also be forced using the -.BR Dir () -function: - -.ES -libs = Dir('libs') -env = Environment(LIBPATH=libs) -.EE -.IP -The directory list will be added to command lines -through the automatically-generated -.B $_LIBDIRFLAGS -construction variable, -which is constructed by -appending the values of the -.BR $LIBDIRPREFIX and $LIBDIRSUFFIX -construction variables -to the beginning and end -of each directory in \fB$LIBPATH\fP. -Any command lines you define that need -the LIBPATH directory list should -include \fB$_LIBDIRFLAGS\fP: - -.ES -env = Environment(LINKCOM="my_linker $_LIBDIRFLAGS $_LIBFLAGS -o $TARGET $SOURCE") -.EE - -.IP LIBPREFIX -The prefix used for (static) library file names. -A default value is set for each platform -(posix, win32, os2, etc.), -but the value is overridden by individual tools -(ar, mslib, sgiar, sunar, tlib, etc.) -to reflect the names of the libraries they create. - -.IP LIBPREFIXES -A list of all legal prefixes for library file names. -When searching for library dependencies, -SCons will look for files with these prefixes, -the base library name, -and suffixes in the \fB$LIBSUFFIXES\fP list. - -.IP LIBS -A list of one or more libraries -that will be linked with -any executable programs -created by this environment. - -The library list will be added to command lines -through the automatically-generated -.B $_LIBFLAGS -construction variable, -which is constructed by -appending the values of the -.BR $LIBLINKPREFIX and $LIBLINKSUFFIX -construction variables -to the beginning and end -of each filename in \fB$LIBS\fP. -Any command lines you define that need -the LIBS library list should -include \fB$_LIBFLAGS\fP: - -.ES -env = Environment(LINKCOM="my_linker $_LIBDIRFLAGS $_LIBFLAGS -o $TARGET $SOURCE") -.EE -.IP -If you add a -File -object to the -.B $LIBS -list, the name of that file will be added to -.BR $_LIBFLAGS , -and thus the link line, as is, without -.B $LIBLINKPREFIX -or -.BR $LIBLINKSUFFIX . -For example: - -.ES -env.Append(LIBS=File('/tmp/mylib.so')) -.EE -.IP -In all cases, scons will add dependencies from the executable program to -all the libraries in this list. - -.IP LIBSUFFIX -The suffix used for (static) library file names. -A default value is set for each platform -(posix, win32, os2, etc.), -but the value is overridden by individual tools -(ar, mslib, sgiar, sunar, tlib, etc.) -to reflect the names of the libraries they create. - -.IP LIBSUFFIXES -A list of all legal suffixes for library file names. -When searching for library dependencies, -SCons will look for files with prefixes, in the \fB$LIBPREFIXES\fP list, -the base library name, -and these suffixes. - -.IP LICENSE -The abbreviated name of the license under which -this project is released (gpl, lpgl, bsd etc.). -See http://www.opensource.org/licenses/alphabetical -for a list of license names. - -.IP LINESEPARATOR -The separator used by the \fBSubstfile\fP() and \fBTextfile\fP() builders. -This value is used between sources when constructing the target. -It defaults to the current system line separator. - -.IP LINGUAS_FILE -The \fB$LINGUAS_FILE\fP defines file(s) containing list of additional linguas -to be processed by \fBPOInit\fP(), \fBPOUpdate\fP() or \fBMOFiles\fP() -builders. It also affects \fBTranslate\fP() builder. If the variable contains -a string, it defines name of the list file. The \fB$LINGUAS_FILE\fP may be a -list of file names as well. If \fB$LINGUAS_FILE\fP is set to -\fBTrue\fP (or non-zero numeric value), the list will be read from -default file named -.BR LINGUAS . - - -.IP LINK -The linker. - -.IP LINKCOM -The command line used to link object files into an executable. - -.IP LINKCOMSTR -The string displayed when object files -are linked into an executable. -If this is not set, then \fB$LINKCOM\fP (the command line) is displayed. - -.ES -env = Environment(LINKCOMSTR = "Linking $TARGET") -.EE - -.IP LINKFLAGS -General user options passed to the linker. -Note that this variable should -.I not -contain -.B \-l -(or similar) options for linking with the libraries listed in \fB$LIBS\fP, -nor -.B \-L -(or similar) library search path options -that scons generates automatically from \fB$LIBPATH\fP. -See -.B $_LIBFLAGS -above, -for the variable that expands to library-link options, -and -.B $_LIBDIRFLAGS -above, -for the variable that expands to library search path options. - -.IP M4 -The M4 macro preprocessor. - -.IP M4COM -The command line used to pass files through the M4 macro preprocessor. - -.IP M4COMSTR -The string displayed when -a file is passed through the M4 macro preprocessor. -If this is not set, then \fB$M4COM\fP (the command line) is displayed. - -.IP M4FLAGS -General options passed to the M4 macro preprocessor. - -.IP MAKEINDEX -The makeindex generator for the TeX formatter and typesetter and the -LaTeX structured formatter and typesetter. - -.IP MAKEINDEXCOM -The command line used to call the makeindex generator for the -TeX formatter and typesetter and the LaTeX structured formatter and -typesetter. - -.IP MAKEINDEXCOMSTR -The string displayed when calling the makeindex generator for the -TeX formatter and typesetter -and the LaTeX structured formatter and typesetter. -If this is not set, then \fB$MAKEINDEXCOM\fP (the command line) is displayed. - -.IP MAKEINDEXFLAGS -General options passed to the makeindex generator for the TeX formatter -and typesetter and the LaTeX structured formatter and typesetter. - -.IP MAXLINELENGTH -The maximum number of characters allowed on an external command line. -On Win32 systems, -link lines longer than this many characters -are linked via a temporary file name. - -.IP MIDL -The Microsoft IDL compiler. - -.IP MIDLCOM -The command line used to pass files to the Microsoft IDL compiler. - -.IP MIDLCOMSTR -The string displayed when -the Microsoft IDL copmiler is called. -If this is not set, then \fB$MIDLCOM\fP (the command line) is displayed. - -.IP MIDLFLAGS -General options passed to the Microsoft IDL compiler. - -.IP MOSUFFIX -Suffix used for \fBMO\fP files (default: \fB'.mo'\fP). -See &t-link-msgfmt; tool and \fBMOFiles\fP() builder. - -.IP MSGFMT -Absolute path to \fBmsgfmt(1)\fP binary, found by -.BR Detect() . -See &t-link-msgfmt; tool and \fBMOFiles\fP() builder. - -.IP MSGFMTCOM -Complete command line to run \fBmsgfmt(1)\fP program. -See &t-link-msgfmt; tool and \fBMOFiles\fP() builder. - -.IP MSGFMTCOMSTR -String to display when \fBmsgfmt(1)\fP is invoked -(default: \fB''\fP, which means ``print \fB$MSGFMTCOM\fP''). -See &t-link-msgfmt; tool and \fBMOFiles\fP() builder. - -.IP MSGFMTFLAGS -Additional flags to \fBmsgfmt(1)\fP. -See &t-link-msgfmt; tool and \fBMOFiles\fP() builder. - -.IP MSGINIT -Path to \fBmsginit(1)\fP program (found via -.BR Detect() ). -See &t-link-msginit; tool and \fBPOInit\fP() builder. - -.IP MSGINITCOM -Complete command line to run \fBmsginit(1)\fP program. -See &t-link-msginit; tool and \fBPOInit\fP() builder. - -.IP MSGINITCOMSTR -String to display when \fBmsginit(1)\fP is invoked -(default: \fB''\fP, which means ``print \fB$MSGINITCOM\fP''). -See &t-link-msginit; tool and \fBPOInit\fP() builder. - -.IP MSGINITFLAGS -List of additional flags to \fBmsginit(1)\fP (default: -.BR [] ). -See &t-link-msginit; tool and \fBPOInit\fP() builder. - -.IP _MSGINITLOCALE -Internal ``macro''. Computes locale (language) name based on target filename -(default: \fB'${TARGET.filebase}' \fP). - -.IP MSGMERGE -Absolute path to \fBmsgmerge(1)\fP binary as found by -.BR Detect() . -See &t-link-msgmerge; tool and \fBPOUpdate\fP() builder. - -.IP MSGMERGECOM -Complete command line to run \fBmsgmerge(1)\fP command. -See &t-link-msgmerge; tool and \fBPOUpdate\fP() builder. - -.IP MSGMERGECOMSTR -String to be displayed when \fBmsgmerge(1)\fP is invoked -(default: \fB''\fP, which means ``print \fB$MSGMERGECOM\fP''). -See &t-link-msgmerge; tool and \fBPOUpdate\fP() builder. - -.IP MSGMERGEFLAGS -Additional flags to \fBmsgmerge(1)\fP command. -See &t-link-msgmerge; tool and \fBPOUpdate\fP() builder. - -.IP MSSDK_DIR -The directory containing the Microsoft SDK -(either Platform SDK or Windows SDK) -to be used for compilation. - -.IP MSSDK_VERSION -The version string of the Microsoft SDK -(either Platform SDK or Windows SDK) -to be used for compilation. -Supported versions include -.BR 6.1 , -.BR 6.0A , -.BR 6.0 , -.B 2003R2 -and -.BR 2003R1 . - -.IP MSVC_BATCH -When set to any true value, -specifies that SCons should batch -compilation of object files -when calling the Microsoft Visual C/C++ compiler. -All compilations of source files from the same source directory -that generate target files in a same output directory -and were configured in SCons using the same construction environment -will be built in a single call to the compiler. -Only source files that have changed since their -object files were built will be passed to each compiler invocation -(via the \fB$CHANGED_SOURCES\fP construction variable). -Any compilations where the object (target) file base name -(minus the \fB.obj\fP) -does not match the source file base name -will be compiled separately. - -.IP MSVC_USE_SCRIPT -Use a batch script to set up Microsoft Visual Studio compiler - -.BR $MSVC_USE_SCRIPT\fP overrides \fB$MSVC_VERSION\fP and \fB$TARGET_ARCH . -If set to the name of a Visual Studio .bat file (e.g. vcvars.bat), -SCons will run that bat file and extract the relevant variables from -the result (typically %INCLUDE%, %LIB%, and %PATH%). Setting -MSVC_USE_SCRIPT to None bypasses the Visual Studio autodetection -entirely; use this if you are running SCons in a Visual Studio cmd -window and importing the shell's environment variables. - -.IP MSVC_VERSION -Sets the preferred version of Microsoft Visual C/C++ to use. - -If \fB$MSVC_VERSION\fP is not set, SCons will (by default) select the -latest version of Visual C/C++ installed on your system. If the -specified version isn't installed, tool initialization will fail. -This variable must be passed as an argument to the Environment() -constructor; setting it later has no effect. Set it to an unexpected -value (e.g. "XXX") to see the valid values on your system. - -.IP MSVS -When the Microsoft Visual Studio tools are initialized, they set up -this dictionary with the following keys: - -.BR VERSION : -the version of MSVS being used (can be set via -.BR $MSVS_VERSION ) - -.BR VERSIONS : -the available versions of MSVS installed - -.BR VCINSTALLDIR : -installed directory of Visual C++ - -.BR VSINSTALLDIR : -installed directory of Visual Studio - -.BR FRAMEWORKDIR : -installed directory of the .NET framework - -.BR FRAMEWORKVERSIONS : -list of installed versions of the .NET framework, sorted latest to oldest. - -.BR FRAMEWORKVERSION : -latest installed version of the .NET framework - -.BR FRAMEWORKSDKDIR : -installed location of the .NET SDK. - -.BR PLATFORMSDKDIR : -installed location of the Platform SDK. - -.BR PLATFORMSDK_MODULES : -dictionary of installed Platform SDK modules, -where the dictionary keys are keywords for the various modules, and -the values are 2-tuples where the first is the release date, and the -second is the version number. - -If a value isn't set, it wasn't available in the registry. - -.IP MSVS_ARCH -Sets the architecture for which the generated project(s) should build. - -The default value is \fBx86\fP. -\fBamd64\fP is also supported -by &SCons; for some Visual Studio versions. -Trying to set \fB$MSVS_ARCH\fP to an architecture that's not -supported for a given Visual Studio version -will generate an error. - -.IP MSVS_PROJECT_GUID -The string -placed in a generated Microsoft Visual Studio project file -as the value of the -.B ProjectGUID -attribute. -There is no default value. If not defined, a new GUID is generated. - -.IP MSVS_SCC_AUX_PATH -The path name -placed in a generated Microsoft Visual Studio project file -as the value of the -.B SccAuxPath -attribute -if the -.B MSVS_SCC_PROVIDER -construction variable is also set. -There is no default value. - -.IP MSVS_SCC_CONNECTION_ROOT -The root path of projects in your SCC workspace, i.e the path under which -all project and solution files will be generated. It is used as a -reference path from which the relative paths of the generated -Microsoft Visual Studio project and solution files are computed. -The relative project file path is placed as the value of the -.B SccLocalPath -attribute -of the project file -and as the values of the -.B SccProjectFilePathRelativizedFromConnection[i] -(where [i] ranges from 0 to the number of projects in the solution) -attributes of the -.B GlobalSection(SourceCodeControl) -section of the Microsoft Visual Studio solution file. -Similarly the relative solution file path is placed as the values of the -.B SccLocalPath[i] -(where [i] ranges from 0 to the number of projects in the solution) -attributes of the -.B GlobalSection(SourceCodeControl) -section of the Microsoft Visual Studio solution file. -This is used only -if the -.B MSVS_SCC_PROVIDER -construction variable is also set. -The default value is the current working directory. - -.IP MSVS_SCC_PROJECT_NAME -The project name -placed in a generated Microsoft Visual Studio project file -as the value of the -.B SccProjectName -attribute -if the -.B MSVS_SCC_PROVIDER -construction variable is also set. -In this case the string is also placed in the -.B SccProjectName0 -attribute of the -.B GlobalSection(SourceCodeControl) -section of the Microsoft Visual Studio solution file. -There is no default value. - -.IP MSVS_SCC_PROVIDER -The string -placed in a generated Microsoft Visual Studio project file -as the value of the -.B SccProvider -attribute. -The string is also placed in the -.B SccProvider0 -attribute of the -.B GlobalSection(SourceCodeControl) -section of the Microsoft Visual Studio solution file. -There is no default value. - -.IP MSVS_VERSION -Sets the preferred version of Microsoft Visual Studio to use. - -If \fB$MSVS_VERSION\fP is not set, -&SCons; will (by default) select the latest version -of Visual Studio installed on your system. -So, if you have version 6 and version 7 (MSVS .NET) installed, -it will prefer version 7. -You can override this by -specifying the -.B MSVS_VERSION -variable in the Environment initialization, setting it to the -appropriate version ('6.0' or '7.0', for example). -If the specified version isn't installed, -tool initialization will fail. - -This is obsolete: use \fB$MSVC_VERSION\fP instead. If \fB$MSVS_VERSION\fP is set and -.BR $MSVC_VERSION\fP is not, \fB$MSVC_VERSION\fP will be set automatically to \fB$MSVS_VERSION . -If both are set to different values, scons will raise an error. - -.IP MSVSBUILDCOM -The build command line placed in -a generated Microsoft Visual Studio project file. -The default is to have Visual Studio invoke SCons with any specified -build targets. - -.IP MSVSCLEANCOM -The clean command line placed in -a generated Microsoft Visual Studio project file. -The default is to have Visual Studio invoke SCons with the -c option -to remove any specified targets. - -.IP MSVSENCODING -The encoding string placed in -a generated Microsoft Visual Studio project file. -The default is encoding -.BR Windows-1252 . - -.IP MSVSPROJECTCOM -The action used to generate Microsoft Visual Studio project files. - -.IP MSVSPROJECTSUFFIX -The suffix used for Microsoft Visual Studio project (DSP) files. -The default value is -.B .vcproj -when using Visual Studio version 7.x (.NET) -or later version, -and -.B .dsp -when using earlier versions of Visual Studio. - -.IP MSVSREBUILDCOM -The rebuild command line placed in -a generated Microsoft Visual Studio project file. -The default is to have Visual Studio invoke SCons with any specified -rebuild targets. - -.IP MSVSSCONS -The SCons used in generated Microsoft Visual Studio project files. -The default is the version of SCons being -used to generate the project file. - -.IP MSVSSCONSCOM -The default SCons command used in generated Microsoft Visual Studio -project files. - -.IP MSVSSCONSCRIPT -The sconscript file -(that is, -.B SConstruct -or -.B SConscript -file) -that will be invoked by Visual Studio -project files -(through the -.B $MSVSSCONSCOM -variable). -The default is the same sconscript file -that contains the call to -.BR MSVSProject () -to build the project file. - -.IP MSVSSCONSFLAGS -The SCons flags used in generated Microsoft Visual Studio -project files. - -.IP MSVSSOLUTIONCOM -The action used to generate Microsoft Visual Studio solution files. - -.IP MSVSSOLUTIONSUFFIX -The suffix used for Microsoft Visual Studio solution (DSW) files. -The default value is -.B .sln -when using Visual Studio version 7.x (.NET), -and -.B .dsw -when using earlier versions of Visual Studio. - -.IP MT -The program used on Windows systems to embed manifests into DLLs and EXEs. -See also \fB$WINDOWS_EMBED_MANIFEST\fP. - -.IP MTEXECOM -The Windows command line used to embed manifests into executables. -See also \fB$MTSHLIBCOM\fP. - -.IP MTFLAGS -Flags passed to the \fB$MT\fP manifest embedding program (Windows only). - -.IP MTSHLIBCOM -The Windows command line used to embed manifests into shared libraries (DLLs). -See also \fB$MTEXECOM\fP. - -.IP MWCW_VERSION -The version number of the MetroWerks CodeWarrior C compiler -to be used. - -.IP MWCW_VERSIONS -A list of installed versions of the MetroWerks CodeWarrior C compiler -on this system. - -.IP NAME -Specfies the name of the project to package. - -.IP no_import_lib -When set to non-zero, -suppresses creation of a corresponding Windows static import lib by the -.B SharedLibrary -builder when used with -MinGW, Microsoft Visual Studio or Metrowerks. -This also suppresses creation -of an export (.exp) file -when using Microsoft Visual Studio. - -.IP OBJPREFIX -The prefix used for (static) object file names. - -.IP OBJSUFFIX -The suffix used for (static) object file names. - -.IP P4 -The Perforce executable. - -.IP P4COM -The command line used to -fetch source files from Perforce. - -.IP P4COMSTR -The string displayed when -fetching a source file from Perforce. -If this is not set, then \fB$P4COM\fP (the command line) is displayed. - -.IP P4FLAGS -General options that are passed to Perforce. - -.IP PACKAGEROOT -Specifies the directory where all files in resulting archive will be -placed if applicable. The default value is "$NAME-$VERSION". - -.IP PACKAGETYPE -Selects the package type to build. Currently these are available: - - * msi - Microsoft Installer - * rpm - Redhat Package Manger - * ipkg - Itsy Package Management System - * tarbz2 - compressed tar - * targz - compressed tar - * zip - zip file - * src_tarbz2 - compressed tar source - * src_targz - compressed tar source - * src_zip - zip file source - -This may be overridden with the "package_type" command line option. - -.IP PACKAGEVERSION -The version of the package (not the underlying project). -This is currently only used by the rpm packager -and should reflect changes in the packaging, -not the underlying project code itself. - -.IP PCH -The Microsoft Visual C++ precompiled header that will be used when compiling -object files. This variable is ignored by tools other than Microsoft Visual C++. -When this variable is -defined SCons will add options to the compiler command line to -cause it to use the precompiled header, and will also set up the -dependencies for the PCH file. -Example: - -.ES -env['PCH'] = 'StdAfx.pch' -.EE - -.IP PCHCOM -The command line used by the -.BR PCH () -builder to generated a precompiled header. - -.IP PCHCOMSTR -The string displayed when generating a precompiled header. -If this is not set, then \fB$PCHCOM\fP (the command line) is displayed. - -.IP PCHPDBFLAGS -A construction variable that, when expanded, -adds the \fB/yD\fP flag to the command line -only if the \fB$PDB\fP construction variable is set. - -.IP PCHSTOP -This variable specifies how much of a source file is precompiled. This -variable is ignored by tools other than Microsoft Visual C++, or when -the PCH variable is not being used. When this variable is define it -must be a string that is the name of the header that -is included at the end of the precompiled portion of the source files, or -the empty string if the "#pragma hrdstop" construct is being used: - -.ES -env['PCHSTOP'] = 'StdAfx.h' -.EE - -.IP PDB -The Microsoft Visual C++ PDB file that will store debugging information for -object files, shared libraries, and programs. This variable is ignored by -tools other than Microsoft Visual C++. -When this variable is -defined SCons will add options to the compiler and linker command line to -cause them to generate external debugging information, and will also set up the -dependencies for the PDB file. -Example: - -.ES -env['PDB'] = 'hello.pdb' -.EE -.IP -The Visual C++ compiler switch that SCons uses by default -to generate PDB information is \fB/Z7\fP. -This works correctly with parallel (\fB\-j\fP) builds -because it embeds the debug information in the intermediate object files, -as opposed to sharing a single PDB file between multiple object files. -This is also the only way to get debug information -embedded into a static library. -Using the \fB/Zi\fP instead may yield improved -link-time performance, -although parallel builds will no longer work. -You can generate PDB files with the \fB/Zi\fP -switch by overriding the default \fB$CCPDBFLAGS\fP variable; -see the entry for that variable for specific examples. - -.IP PDFCOM -A deprecated synonym for \fB$DVIPDFCOM\fP. - -.IP PDFLATEX -The &pdflatex; utility. - -.IP PDFLATEXCOM -The command line used to call the &pdflatex; utility. - -.IP PDFLATEXCOMSTR -The string displayed when calling the &pdflatex; utility. -If this is not set, then \fB$PDFLATEXCOM\fP (the command line) is displayed. - -.ES -env = Environment(PDFLATEX;COMSTR = "Building $TARGET from LaTeX input $SOURCES") -.EE - -.IP PDFLATEXFLAGS -General options passed to the &pdflatex; utility. - -.IP PDFPREFIX -The prefix used for PDF file names. - -.IP PDFSUFFIX -The suffix used for PDF file names. - -.IP PDFTEX -The &pdftex; utility. - -.IP PDFTEXCOM -The command line used to call the &pdftex; utility. - -.IP PDFTEXCOMSTR -The string displayed when calling the &pdftex; utility. -If this is not set, then \fB$PDFTEXCOM\fP (the command line) is displayed. - -.ES -env = Environment(PDFTEXCOMSTR = "Building $TARGET from TeX input $SOURCES") -.EE - -.IP PDFTEXFLAGS -General options passed to the &pdftex; utility. - -.IP PKGCHK -On Solaris systems, -the package-checking program that will -be used (along with \fB$PKGINFO\fP) -to look for installed versions of -the Sun PRO C++ compiler. -The default is -.BR /usr/sbin/pgkchk . - -.IP PKGINFO -On Solaris systems, -the package information program that will -be used (along with \fB$PKGCHK\fP) -to look for installed versions of -the Sun PRO C++ compiler. -The default is -.BR pkginfo . - -.IP PLATFORM -The name of the platform used to create the Environment. If no platform is -specified when the Environment is created, -.B scons -autodetects the platform. - -.ES -env = Environment(tools = []) -if env['PLATFORM'] == 'cygwin': - Tool('mingw')(env) -else: - Tool('msvc')(env) -.EE - -.IP POAUTOINIT -The \fB$POAUTOINIT\fP variable, if set to \fBTrue\fP (on non-zero -numeric value), let the &t-link-msginit; tool to automatically initialize -\fImissing\fP \fBPO\fP files with -\fBmsginit(1)\fP. This applies to both, -\fBPOInit\fP() and \fBPOUpdate\fP() builders (and others that use any of -them). - -.IP POCREATE_ALIAS -Common alias for all \fBPO\fP files created with \fBPOInit\fP() -builder (default: \fB'po-create'\fP). -See &t-link-msginit; tool and \fBPOInit\fP() builder. - -.IP POSUFFIX -Suffix used for \fBPO\fP files (default: \fB'.po'\fP) -See &t-link-msginit; tool and \fBPOInit\fP() builder. - -.IP POTDOMAIN -The \fB$POTDOMAIN\fP defines default domain, used to generate -\fBPOT\fP filename as \fB\fB$POTDOMAIN\fP.pot\fP when -no \fBPOT\fP file name is provided by the user. This applies to -\fBPOTUpdate\fP(), \fBPOInit\fP() and \fBPOUpdate\fP() builders (and -builders, that use them, e.g. \fBTranslate\fP()). Normally (if \fB$POTDOMAIN\fP is -not defined), the builders use \fBmessages.pot\fP as default -\fBPOT\fP file name. - -.IP POTSUFFIX -Suffix used for PO Template files (default: \fB'.pot'\fP). -See &t-link-xgettext; tool and \fBPOTUpdate\fP() builder. - -.IP POTUPDATE_ALIAS -Name of the common phony target for all PO Templates created with -.BR POUpdate\fP() (default: \fB'pot-update' ). -See &t-link-xgettext; tool and \fBPOTUpdate\fP() builder. - -.IP POUPDATE_ALIAS -Common alias for all \fBPO\fP files being defined with -.BR POUpdate\fP() builder (default: \fB'po-update' ). -See &t-link-msgmerge; tool and \fBPOUpdate\fP() builder. - -.IP PRINT_CMD_LINE_FUNC -A Python function used to print the command lines as they are executed -(assuming command printing is not disabled by the -.B \-q -or -.B \-s -options or their equivalents). -The function should take four arguments: -.IR s , -the command being executed (a string), -.IR target , -the target being built (file node, list, or string name(s)), -.IR source , -the source(s) used (file node, list, or string name(s)), and -.IR env , -the environment being used. - -The function must do the printing itself. The default implementation, -used if this variable is not set or is None, is: -.ES -def print_cmd_line(s, target, source, env): - sys.stdout.write(s + "\\n") -.EE -.IP -Here's an example of a more interesting function: - -.ES -def print_cmd_line(s, target, source, env): - sys.stdout.write("Building %s -> %s...\\n" % - (' and '.join([str(x) for x in source]), - ' and '.join([str(x) for x in target]))) -env=Environment(PRINT_CMD_LINE_FUNC=print_cmd_line) -env.Program('foo', 'foo.c') -.EE -.IP -This just prints "Building \fItargetname\fP from \fIsourcename\fP..." instead -of the actual commands. -Such a function could also log the actual commands to a log file, -for example. - -.IP PROGEMITTER -TODO - -.IP PROGPREFIX -The prefix used for executable file names. - -.IP PROGSUFFIX -The suffix used for executable file names. - -.IP PSCOM -The command line used to convert TeX DVI files into a PostScript file. - -.IP PSCOMSTR -The string displayed when a TeX DVI file -is converted into a PostScript file. -If this is not set, then \fB$PSCOM\fP (the command line) is displayed. - -.IP PSPREFIX -The prefix used for PostScript file names. - -.IP PSSUFFIX -The prefix used for PostScript file names. - -.IP QT_AUTOSCAN -Turn off scanning for mocable files. Use the Moc Builder to explicitly -specify files to run moc on. - -.IP QT_BINPATH -The path where the qt binaries are installed. -The default value is '\fB$QTDIR\fP/bin'. - -.IP QT_CPPPATH -The path where the qt header files are installed. -The default value is '\fB$QTDIR\fP/include'. -Note: If you set this variable to None, -the tool won't change the \fB$CPPPATH\fP -construction variable. - -.IP QT_DEBUG -Prints lots of debugging information while scanning for moc files. - -.IP QT_LIB -Default value is 'qt'. You may want to set this to 'qt-mt'. Note: If you set -this variable to None, the tool won't change the \fB$LIBS\fP variable. - -.IP QT_LIBPATH -The path where the qt libraries are installed. -The default value is '\fB$QTDIR\fP/lib'. -Note: If you set this variable to None, -the tool won't change the \fB$LIBPATH\fP -construction variable. - -.IP QT_MOC -Default value is '\fB$QT_BINPATH\fP/moc'. - -.IP QT_MOCCXXPREFIX -Default value is ''. Prefix for moc output files, when source is a cxx file. - -.IP QT_MOCCXXSUFFIX -Default value is '.moc'. Suffix for moc output files, when source is a cxx -file. - -.IP QT_MOCFROMCXXCOM -Command to generate a moc file from a cpp file. - -.IP QT_MOCFROMCXXCOMSTR -The string displayed when generating a moc file from a cpp file. -If this is not set, then \fB$QT_MOCFROMCXXCOM\fP (the command line) is displayed. - -.IP QT_MOCFROMCXXFLAGS -Default value is '-i'. These flags are passed to moc, when moccing a -C++ file. - -.IP QT_MOCFROMHCOM -Command to generate a moc file from a header. - -.IP QT_MOCFROMHCOMSTR -The string displayed when generating a moc file from a cpp file. -If this is not set, then \fB$QT_MOCFROMHCOM\fP (the command line) is displayed. - -.IP QT_MOCFROMHFLAGS -Default value is ''. These flags are passed to moc, when moccing a header -file. - -.IP QT_MOCHPREFIX -Default value is 'moc_'. Prefix for moc output files, when source is a header. - -.IP QT_MOCHSUFFIX -Default value is '\fB$CXXFILESUFFIX\fP'. Suffix for moc output files, when source is -a header. - -.IP QT_UIC -Default value is '\fB$QT_BINPATH\fP/uic'. - -.IP QT_UICCOM -Command to generate header files from .ui files. - -.IP QT_UICCOMSTR -The string displayed when generating header files from .ui files. -If this is not set, then \fB$QT_UICCOM\fP (the command line) is displayed. - -.IP QT_UICDECLFLAGS -Default value is ''. These flags are passed to uic, when creating a a h -file from a .ui file. - -.IP QT_UICDECLPREFIX -Default value is ''. Prefix for uic generated header files. - -.IP QT_UICDECLSUFFIX -Default value is '.h'. Suffix for uic generated header files. - -.IP QT_UICIMPLFLAGS -Default value is ''. These flags are passed to uic, when creating a cxx -file from a .ui file. - -.IP QT_UICIMPLPREFIX -Default value is 'uic_'. Prefix for uic generated implementation files. - -.IP QT_UICIMPLSUFFIX -Default value is '\fB$CXXFILESUFFIX\fP'. Suffix for uic generated implementation -files. - -.IP QT_UISUFFIX -Default value is '.ui'. Suffix of designer input files. - -.IP QTDIR -The qt tool tries to take this from os.environ. -It also initializes all QT_* -construction variables listed below. -(Note that all paths are constructed -with python's os.path.join() method, -but are listed here with the '/' separator -for easier reading.) -In addition, the construction environment -variables \fB$CPPPATH\fP, -\fB$LIBPATH\fP and -\fB$LIBS\fP may be modified -and the variables -.BR $PROGEMITTER\fP, \fB$SHLIBEMITTER and $LIBEMITTER -are modified. Because the build-performance is affected when using this tool, -you have to explicitly specify it at Environment creation: - -.ES -Environment(tools=['default','qt']) -.EE -.IP -The qt tool supports the following operations: - -.I "Automatic moc file generation from header files." -You do not have to specify moc files explicitly, the tool does it for you. -However, there are a few preconditions to do so: Your header file must have -the same filebase as your implementation file and must stay in the same -directory. It must have one of the suffixes .h, .hpp, .H, .hxx, .hh. You -can turn off automatic moc file generation by setting QT_AUTOSCAN to 0. -See also the corresponding -.BR Moc() () -builder method. - -.I "Automatic moc file generation from cxx files." -As stated in the qt documentation, include the moc file at the end of -the cxx file. Note that you have to include the file, which is generated -by the transformation ${QT_MOCCXXPREFIX}<basename>${QT_MOCCXXSUFFIX}, by default -<basename>.moc. A warning is generated after building the moc file, if you -do not include the correct file. If you are using VariantDir, you may -need to specify duplicate=1. You can turn off automatic moc file generation -by setting QT_AUTOSCAN to 0. See also the corresponding -.BR Moc () -builder method. - -.I "Automatic handling of .ui files." -The implementation files generated from .ui files are handled much the same -as yacc or lex files. Each .ui file given as a source of Program, Library or -SharedLibrary will generate three files, the declaration file, the -implementation file and a moc file. Because there are also generated headers, -you may need to specify duplicate=1 in calls to VariantDir. -See also the corresponding -.BR Uic () -builder method. - -.IP RANLIB -The archive indexer. - -.IP RANLIBCOM -The command line used to index a static library archive. - -.IP RANLIBCOMSTR -The string displayed when a static library archive is indexed. -If this is not set, then \fB$RANLIBCOM\fP (the command line) is displayed. - -.ES -env = Environment(RANLIBCOMSTR = "Indexing $TARGET") -.EE - -.IP RANLIBFLAGS -General options passed to the archive indexer. - -.IP RC -The resource compiler used to build -a Microsoft Visual C++ resource file. - -.IP RCCOM -The command line used to build -a Microsoft Visual C++ resource file. - -.IP RCCOMSTR -The string displayed when invoking the resource compiler -to build a Microsoft Visual C++ resource file. -If this is not set, then \fB$RCCOM\fP (the command line) is displayed. - -.IP RCFLAGS -The flags passed to the resource compiler by the RES builder. - -.IP RCINCFLAGS -An automatically-generated construction variable -containing the command-line options -for specifying directories to be searched -by the resource compiler. -The value of \fB$RCINCFLAGS\fP is created -by appending \fB$RCINCPREFIX\fP and \fB$RCINCSUFFIX\fP -to the beginning and end -of each directory in \fB$CPPPATH\fP. - -.IP RCINCPREFIX -The prefix (flag) used to specify an include directory -on the resource compiler command line. -This will be appended to the beginning of each directory -in the \fB$CPPPATH\fP construction variable -when the \fB$RCINCFLAGS\fP variable is expanded. - -.IP RCINCSUFFIX -The suffix used to specify an include directory -on the resource compiler command line. -This will be appended to the end of each directory -in the \fB$CPPPATH\fP construction variable -when the \fB$RCINCFLAGS\fP variable is expanded. - -.IP RCS -The RCS executable. -Note that this variable is not actually used -for the command to fetch source files from RCS; -see the -.B $RCS_CO -construction variable, below. - -.IP RCS_CO -The RCS "checkout" executable, -used to fetch source files from RCS. - -.IP RCS_COCOM -The command line used to -fetch (checkout) source files from RCS. - -.IP RCS_COCOMSTR -The string displayed when fetching -a source file from RCS. -If this is not set, then \fB$RCS_COCOM\fP -(the command line) is displayed. - -.IP RCS_COFLAGS -Options that are passed to the \fB$RCS_CO\fP command. - -.IP RDirs -A function that converts a string into a list of Dir instances by -searching the repositories. - -.IP REGSVR -The program used on Windows systems -to register a newly-built DLL library -whenever the \fBSharedLibrary\fP() builder -is passed a keyword argument of \fBregister=1\fP. - -.IP REGSVRCOM -The command line used on Windows systems -to register a newly-built DLL library -whenever the \fBSharedLibrary\fP() builder -is passed a keyword argument of \fBregister=1\fP. - -.IP REGSVRCOMSTR -The string displayed when registering a newly-built DLL file. -If this is not set, then \fB$REGSVRCOM\fP (the command line) is displayed. - -.IP REGSVRFLAGS -Flags passed to the DLL registration program -on Windows systems when a newly-built DLL library is registered. -By default, -this includes the \fB/s\fP -that prevents dialog boxes from popping up -and requiring user attention. - -.IP RMIC -The Java RMI stub compiler. - -.IP RMICCOM -The command line used to compile stub -and skeleton class files -from Java classes that contain RMI implementations. -Any options specified in the \fB$RMICFLAGS\fP construction variable -are included on this command line. - -.IP RMICCOMSTR -The string displayed when compiling -stub and skeleton class files -from Java classes that contain RMI implementations. -If this is not set, then \fB$RMICCOM\fP (the command line) is displayed. - -.ES -env = Environment(RMICCOMSTR = "Generating stub/skeleton class files $TARGETS from $SOURCES") -.EE - -.IP RMICFLAGS -General options passed to the Java RMI stub compiler. - -.IP _RPATH -An automatically-generated construction variable -containing the rpath flags to be used when linking -a program with shared libraries. -The value of \fB$_RPATH\fP is created -by appending \fB$RPATHPREFIX\fP and \fB$RPATHSUFFIX\fP -to the beginning and end -of each directory in \fB$RPATH\fP. - -.IP RPATH -A list of paths to search for shared libraries when running programs. -Currently only used in the GNU (gnulink), -IRIX (sgilink) and Sun (sunlink) linkers. -Ignored on platforms and toolchains that don't support it. -Note that the paths added to RPATH -are not transformed by -.B scons -in any way: if you want an absolute -path, you must make it absolute yourself. - -.IP RPATHPREFIX -The prefix used to specify a directory to be searched for -shared libraries when running programs. -This will be appended to the beginning of each directory -in the \fB$RPATH\fP construction variable -when the \fB$_RPATH\fP variable is automatically generated. - -.IP RPATHSUFFIX -The suffix used to specify a directory to be searched for -shared libraries when running programs. -This will be appended to the end of each directory -in the \fB$RPATH\fP construction variable -when the \fB$_RPATH\fP variable is automatically generated. - -.IP RPCGEN -The RPC protocol compiler. - -.IP RPCGENCLIENTFLAGS -Options passed to the RPC protocol compiler -when generating client side stubs. -These are in addition to any flags specified in the -.B $RPCGENFLAGS -construction variable. - -.IP RPCGENFLAGS -General options passed to the RPC protocol compiler. - -.IP RPCGENHEADERFLAGS -Options passed to the RPC protocol compiler -when generating a header file. -These are in addition to any flags specified in the -.B $RPCGENFLAGS -construction variable. - -.IP RPCGENSERVICEFLAGS -Options passed to the RPC protocol compiler -when generating server side stubs. -These are in addition to any flags specified in the -.B $RPCGENFLAGS -construction variable. - -.IP RPCGENXDRFLAGS -Options passed to the RPC protocol compiler -when generating XDR routines. -These are in addition to any flags specified in the -.B $RPCGENFLAGS -construction variable. - -.IP SCANNERS -A list of the available implicit dependency scanners. -New file scanners may be added by -appending to this list, -although the more flexible approach -is to associate scanners -with a specific Builder. -See the sections "Builder Objects" -and "Scanner Objects," -below, for more information. - -.IP SCCS -The SCCS executable. - -.IP SCCSCOM -The command line used to -fetch source files from SCCS. - -.IP SCCSCOMSTR -The string displayed when fetching -a source file from a CVS repository. -If this is not set, then \fB$SCCSCOM\fP -(the command line) is displayed. - -.IP SCCSFLAGS -General options that are passed to SCCS. - -.IP SCCSGETFLAGS -Options that are passed specifically to the SCCS "get" subcommand. -This can be set, for example, to -.B \-e -to check out editable files from SCCS. - -.IP SCONS_HOME -The (optional) path to the SCons library directory, -initialized from the external environment. -If set, this is used to construct a shorter and more -efficient search path in the -.B $MSVSSCONS -command line executed -from Microsoft Visual Studio project files. - -.IP SHCC -The C compiler used for generating shared-library objects. - -.IP SHCCCOM -The command line used to compile a C source file -to a shared-library object file. -Any options specified in the \fB$SHCFLAGS\fP, -\fB$SHCCFLAGS\fP and -\fB$CPPFLAGS\fP construction variables -are included on this command line. - -.IP SHCCCOMSTR -The string displayed when a C source file -is compiled to a shared object file. -If this is not set, then \fB$SHCCCOM\fP (the command line) is displayed. - -.ES -env = Environment(SHCCCOMSTR = "Compiling shared object $TARGET") -.EE - -.IP SHCCFLAGS -Options that are passed to the C and C++ compilers -to generate shared-library objects. - -.IP SHCFLAGS -Options that are passed to the C compiler (only; not C++) -to generate shared-library objects. - -.IP SHCXX -The C++ compiler used for generating shared-library objects. - -.IP SHCXXCOM -The command line used to compile a C++ source file -to a shared-library object file. -Any options specified in the \fB$SHCXXFLAGS\fP and -\fB$CPPFLAGS\fP construction variables -are included on this command line. - -.IP SHCXXCOMSTR -The string displayed when a C++ source file -is compiled to a shared object file. -If this is not set, then \fB$SHCXXCOM\fP (the command line) is displayed. - -.ES -env = Environment(SHCXXCOMSTR = "Compiling shared object $TARGET") -.EE - -.IP SHCXXFLAGS -Options that are passed to the C++ compiler -to generate shared-library objects. - -.IP SHELL -A string naming the shell program that will be passed to the -.B $SPAWN -function. -See the -.B $SPAWN -construction variable for more information. - -.IP SHF77 -The Fortran 77 compiler used for generating shared-library objects. -You should normally set the \fB$SHFORTRAN\fP variable, -which specifies the default Fortran compiler -for all Fortran versions. -You only need to set \fB$SHF77\fP if you need to use a specific compiler -or compiler version for Fortran 77 files. - -.IP SHF77COM -The command line used to compile a Fortran 77 source file -to a shared-library object file. -You only need to set \fB$SHF77COM\fP if you need to use a specific -command line for Fortran 77 files. -You should normally set the \fB$SHFORTRANCOM\fP variable, -which specifies the default command line -for all Fortran versions. - -.IP SHF77COMSTR -The string displayed when a Fortran 77 source file -is compiled to a shared-library object file. -If this is not set, then \fB$SHF77COM\fP or \fB$SHFORTRANCOM\fP -(the command line) is displayed. - -.IP SHF77FLAGS -Options that are passed to the Fortran 77 compiler -to generated shared-library objects. -You only need to set \fB$SHF77FLAGS\fP if you need to define specific -user options for Fortran 77 files. -You should normally set the \fB$SHFORTRANFLAGS\fP variable, -which specifies the user-specified options -passed to the default Fortran compiler -for all Fortran versions. - -.IP SHF77PPCOM -The command line used to compile a Fortran 77 source file to a -shared-library object file -after first running the file through the C preprocessor. -Any options specified in the \fB$SHF77FLAGS\fP and \fB$CPPFLAGS\fP construction variables -are included on this command line. -You only need to set \fB$SHF77PPCOM\fP if you need to use a specific -C-preprocessor command line for Fortran 77 files. -You should normally set the \fB$SHFORTRANPPCOM\fP variable, -which specifies the default C-preprocessor command line -for all Fortran versions. - -.IP SHF77PPCOMSTR -The string displayed when a Fortran 77 source file -is compiled to a shared-library object file -after first running the file through the C preprocessor. -If this is not set, then \fB$SHF77PPCOM\fP or \fB$SHFORTRANPPCOM\fP -(the command line) is displayed. - -.IP SHF90 -The Fortran 90 compiler used for generating shared-library objects. -You should normally set the \fB$SHFORTRAN\fP variable, -which specifies the default Fortran compiler -for all Fortran versions. -You only need to set \fB$SHF90\fP if you need to use a specific compiler -or compiler version for Fortran 90 files. - -.IP SHF90COM -The command line used to compile a Fortran 90 source file -to a shared-library object file. -You only need to set \fB$SHF90COM\fP if you need to use a specific -command line for Fortran 90 files. -You should normally set the \fB$SHFORTRANCOM\fP variable, -which specifies the default command line -for all Fortran versions. - -.IP SHF90COMSTR -The string displayed when a Fortran 90 source file -is compiled to a shared-library object file. -If this is not set, then \fB$SHF90COM\fP or \fB$SHFORTRANCOM\fP -(the command line) is displayed. - -.IP SHF90FLAGS -Options that are passed to the Fortran 90 compiler -to generated shared-library objects. -You only need to set \fB$SHF90FLAGS\fP if you need to define specific -user options for Fortran 90 files. -You should normally set the \fB$SHFORTRANFLAGS\fP variable, -which specifies the user-specified options -passed to the default Fortran compiler -for all Fortran versions. - -.IP SHF90PPCOM -The command line used to compile a Fortran 90 source file to a -shared-library object file -after first running the file through the C preprocessor. -Any options specified in the \fB$SHF90FLAGS\fP and \fB$CPPFLAGS\fP construction variables -are included on this command line. -You only need to set \fB$SHF90PPCOM\fP if you need to use a specific -C-preprocessor command line for Fortran 90 files. -You should normally set the \fB$SHFORTRANPPCOM\fP variable, -which specifies the default C-preprocessor command line -for all Fortran versions. - -.IP SHF90PPCOMSTR -The string displayed when a Fortran 90 source file -is compiled to a shared-library object file -after first running the file through the C preprocessor. -If this is not set, then \fB$SHF90PPCOM\fP or \fB$SHFORTRANPPCOM\fP -(the command line) is displayed. - -.IP SHF95 -The Fortran 95 compiler used for generating shared-library objects. -You should normally set the \fB$SHFORTRAN\fP variable, -which specifies the default Fortran compiler -for all Fortran versions. -You only need to set \fB$SHF95\fP if you need to use a specific compiler -or compiler version for Fortran 95 files. - -.IP SHF95COM -The command line used to compile a Fortran 95 source file -to a shared-library object file. -You only need to set \fB$SHF95COM\fP if you need to use a specific -command line for Fortran 95 files. -You should normally set the \fB$SHFORTRANCOM\fP variable, -which specifies the default command line -for all Fortran versions. - -.IP SHF95COMSTR -The string displayed when a Fortran 95 source file -is compiled to a shared-library object file. -If this is not set, then \fB$SHF95COM\fP or \fB$SHFORTRANCOM\fP -(the command line) is displayed. - -.IP SHF95FLAGS -Options that are passed to the Fortran 95 compiler -to generated shared-library objects. -You only need to set \fB$SHF95FLAGS\fP if you need to define specific -user options for Fortran 95 files. -You should normally set the \fB$SHFORTRANFLAGS\fP variable, -which specifies the user-specified options -passed to the default Fortran compiler -for all Fortran versions. - -.IP SHF95PPCOM -The command line used to compile a Fortran 95 source file to a -shared-library object file -after first running the file through the C preprocessor. -Any options specified in the \fB$SHF95FLAGS\fP and \fB$CPPFLAGS\fP construction variables -are included on this command line. -You only need to set \fB$SHF95PPCOM\fP if you need to use a specific -C-preprocessor command line for Fortran 95 files. -You should normally set the \fB$SHFORTRANPPCOM\fP variable, -which specifies the default C-preprocessor command line -for all Fortran versions. - -.IP SHF95PPCOMSTR -The string displayed when a Fortran 95 source file -is compiled to a shared-library object file -after first running the file through the C preprocessor. -If this is not set, then \fB$SHF95PPCOM\fP or \fB$SHFORTRANPPCOM\fP -(the command line) is displayed. - -.IP SHFORTRAN -The default Fortran compiler used for generating shared-library objects. - -.IP SHFORTRANCOM -The command line used to compile a Fortran source file -to a shared-library object file. - -.IP SHFORTRANCOMSTR -The string displayed when a Fortran source file -is compiled to a shared-library object file. -If this is not set, then \fB$SHFORTRANCOM\fP -(the command line) is displayed. - -.IP SHFORTRANFLAGS -Options that are passed to the Fortran compiler -to generate shared-library objects. - -.IP SHFORTRANPPCOM -The command line used to compile a Fortran source file to a -shared-library object file -after first running the file through the C preprocessor. -Any options specified -in the \fB$SHFORTRANFLAGS\fP and -\fB$CPPFLAGS\fP construction variables -are included on this command line. - -.IP SHFORTRANPPCOMSTR -The string displayed when a Fortran source file -is compiled to a shared-library object file -after first running the file through the C preprocessor. -If this is not set, then \fB$SHFORTRANPPCOM\fP -(the command line) is displayed. - -.IP SHLIBEMITTER -TODO - -.IP SHLIBPREFIX -The prefix used for shared library file names. - -.IP SHLIBSUFFIX -The suffix used for shared library file names. - -.IP SHLIBVERSION -When this construction variable is defined, a versioned shared library -is created. This modifies the \fB$SHLINKFLAGS\fP as required, adds -the version number to the library name, and creates the symlinks that -are needed. \fB$SHLIBVERSION\fP needs to be of the form X.Y.Z, -where X and Y are numbers, and Z is a number but can also contain -letters to designate alpha, beta, or release candidate patch levels. - -.IP SHLINK -The linker for programs that use shared libraries. - -.IP SHLINKCOM -The command line used to link programs using shared libraries. - -.IP SHLINKCOMSTR -The string displayed when programs using shared libraries are linked. -If this is not set, then \fB$SHLINKCOM\fP (the command line) is displayed. - -.ES -env = Environment(SHLINKCOMSTR = "Linking shared $TARGET") -.EE - -.IP SHLINKFLAGS -General user options passed to the linker for programs using shared libraries. -Note that this variable should -.I not -contain -.B \-l -(or similar) options for linking with the libraries listed in \fB$LIBS\fP, -nor -.B \-L -(or similar) include search path options -that scons generates automatically from \fB$LIBPATH\fP. -See -.B $_LIBFLAGS -above, -for the variable that expands to library-link options, -and -.B $_LIBDIRFLAGS -above, -for the variable that expands to library search path options. - -.IP SHOBJPREFIX -The prefix used for shared object file names. - -.IP SHOBJSUFFIX -The suffix used for shared object file names. - -.IP SOURCE -A reserved variable name -that may not be set or used in a construction environment. -(See "Variable Substitution," below.) - -.IP SOURCE_URL -The URL -(web address) -of the location from which the project was retrieved. -This is used to fill in the -.B Source: -field in the controlling information for Ipkg and RPM packages. - -.IP SOURCES -A reserved variable name -that may not be set or used in a construction environment. -(See "Variable Substitution," below.) - -.IP SPAWN -A command interpreter function that will be called to execute command line -strings. The function must expect the following arguments: - -.ES -def spawn(shell, escape, cmd, args, env): -.EE -.IP -.I sh -is a string naming the shell program to use. -.I escape -is a function that can be called to escape shell special characters in -the command line. -.I cmd -is the path to the command to be executed. -.I args -is the arguments to the command. -.I env -is a dictionary of the environment variables -in which the command should be executed. - -.IP SUBST_DICT -The dictionary used by the \fBSubstfile\fP() or \fBTextfile\fP() builders -for substitution values. -It can be anything acceptable to the dict() constructor, -so in addition to a dictionary, -lists of tuples are also acceptable. - -.IP SUBSTFILEPREFIX -The prefix used for \fBSubstfile\fP() file names, -the null string by default. - -.IP SUBSTFILESUFFIX -The suffix used for \fBSubstfile\fP() file names, -the null string by default. - -.IP SUMMARY -A short summary of what the project is about. -This is used to fill in the -.B Summary: -field in the controlling information for Ipkg and RPM packages, -and as the -.B Description: -field in MSI packages. - -.IP SWIG -The scripting language wrapper and interface generator. - -.IP SWIGCFILESUFFIX -The suffix that will be used for intermediate C -source files generated by -the scripting language wrapper and interface generator. -The default value is -.BR _wrap\fP\fB$CFILESUFFIX . -By default, this value is used whenever the -.B \-c++ -option is -.I not -specified as part of the -.B $SWIGFLAGS -construction variable. - -.IP SWIGCOM -The command line used to call -the scripting language wrapper and interface generator. - -.IP SWIGCOMSTR -The string displayed when calling -the scripting language wrapper and interface generator. -If this is not set, then \fB$SWIGCOM\fP (the command line) is displayed. - -.IP SWIGCXXFILESUFFIX -The suffix that will be used for intermediate C++ -source files generated by -the scripting language wrapper and interface generator. -The default value is -.BR _wrap\fP\fB$CFILESUFFIX . -By default, this value is used whenever the -.B \-c++ -option is specified as part of the -.B $SWIGFLAGS -construction variable. - -.IP SWIGDIRECTORSUFFIX -The suffix that will be used for intermediate C++ header -files generated by the scripting language wrapper and interface generator. -These are only generated for C++ code when the SWIG 'directors' feature is -turned on. -The default value is -.BR _wrap.h . - -.IP SWIGFLAGS -General options passed to -the scripting language wrapper and interface generator. -This is where you should set -.BR \-python , -.BR \-perl5 , -.BR \-tcl , -or whatever other options you want to specify to SWIG. -If you set the -.B \-c++ -option in this variable, -.B scons -will, by default, -generate a C++ intermediate source file -with the extension that is specified as the -.B $CXXFILESUFFIX -variable. - -.IP _SWIGINCFLAGS -An automatically-generated construction variable -containing the SWIG command-line options -for specifying directories to be searched for included files. -The value of \fB$_SWIGINCFLAGS\fP is created -by appending \fB$SWIGINCPREFIX\fP and \fB$SWIGINCSUFFIX\fP -to the beginning and end -of each directory in \fB$SWIGPATH\fP. - -.IP SWIGINCPREFIX -The prefix used to specify an include directory on the SWIG command line. -This will be appended to the beginning of each directory -in the \fB$SWIGPATH\fP construction variable -when the \fB$_SWIGINCFLAGS\fP variable is automatically generated. - -.IP SWIGINCSUFFIX -The suffix used to specify an include directory on the SWIG command line. -This will be appended to the end of each directory -in the \fB$SWIGPATH\fP construction variable -when the \fB$_SWIGINCFLAGS\fP variable is automatically generated. - -.IP SWIGOUTDIR -Specifies the output directory in which -the scripting language wrapper and interface generator -should place generated language-specific files. -This will be used by SCons to identify -the files that will be generated by the &swig; call, -and translated into the -\fBswig -outdir\fP option on the command line. - -.IP SWIGPATH -The list of directories that the scripting language wrapper -and interface generate will search for included files. -The SWIG implicit dependency scanner will search these -directories for include files. -The default is to use the same path -specified as \fB$CPPPATH\fP. - -Don't explicitly put include directory -arguments in SWIGFLAGS; -the result will be non-portable -and the directories will not be searched by the dependency scanner. -Note: directory names in SWIGPATH will be looked-up relative to the SConscript -directory when they are used in a command. -To force -.B scons -to look-up a directory relative to the root of the source tree use #: - -.ES -env = Environment(SWIGPATH='#/include') -.EE -.IP -The directory look-up can also be forced using the -.BR Dir () -function: - -.ES -include = Dir('include') -env = Environment(SWIGPATH=include) -.EE -.IP -The directory list will be added to command lines -through the automatically-generated -.B $_SWIGINCFLAGS -construction variable, -which is constructed by -appending the values of the -.BR $SWIGINCPREFIX and $SWIGINCSUFFIX -construction variables -to the beginning and end -of each directory in \fB$SWIGPATH\fP. -Any command lines you define that need -the SWIGPATH directory list should -include \fB$_SWIGINCFLAGS\fP: - -.ES -env = Environment(SWIGCOM="my_swig -o $TARGET $_SWIGINCFLAGS $SORUCES") -.EE - -.IP SWIGVERSION -The version number of the SWIG tool. - -.IP TAR -The tar archiver. - -.IP TARCOM -The command line used to call the tar archiver. - -.IP TARCOMSTR -The string displayed when archiving files -using the tar archiver. -If this is not set, then \fB$TARCOM\fP (the command line) is displayed. - -.ES -env = Environment(TARCOMSTR = "Archiving $TARGET") -.EE - -.IP TARFLAGS -General options passed to the tar archiver. - -.IP TARGET -A reserved variable name -that may not be set or used in a construction environment. -(See "Variable Substitution," below.) - -.IP TARGET_ARCH -Sets the target architecture for Visual Studio compiler (i.e. the arch -of the binaries generated by the compiler). If not set, default to -\fB$HOST_ARCH\fP, or, if that is unset, to the architecture of the -running machine's OS (note that the python build or architecture has no -effect). -This variable must be passed as an argument to the Environment() -constructor; setting it later has no effect. -This is currently only used on Windows, but in the future it will be -used on other OSes as well. - -Valid values for Windows are -.BR x86 , -.B i386 -(for 32 bits); -.BR amd64 , -.BR emt64 , -.B x86_64 -(for 64 bits); -and \fBia64\fP (Itanium). -For example, if you want to compile 64-bit binaries, you would set -\fBTARGET_ARCH='x86_64'\fP in your SCons environment. - -.IP TARGET_OS - The name of the target operating system for the compiled objects - created by this Environment. - This defaults to the value of HOST_OS, and the user can override it. - Currently only set for Win32. - -.IP TARGETS -A reserved variable name -that may not be set or used in a construction environment. -(See "Variable Substitution," below.) - -.IP TARSUFFIX -The suffix used for tar file names. - -.IP TEMPFILEPREFIX -The prefix for a temporary file used -to execute lines longer than $MAXLINELENGTH. -The default is '@'. -This may be set for toolchains that use other values, -such as '-@' for the diab compiler -or '-via' for ARM toolchain. - -.IP TEX -The TeX formatter and typesetter. - -.IP TEXCOM -The command line used to call the TeX formatter and typesetter. - -.IP TEXCOMSTR -The string displayed when calling -the TeX formatter and typesetter. -If this is not set, then \fB$TEXCOM\fP (the command line) is displayed. - -.ES -env = Environment(TEXCOMSTR = "Building $TARGET from TeX input $SOURCES") -.EE - -.IP TEXFLAGS -General options passed to the TeX formatter and typesetter. - -.IP TEXINPUTS -List of directories that the LaTeX program will search -for include directories. -The LaTeX implicit dependency scanner will search these -directories for \\include and \\import files. - -.IP TEXTFILEPREFIX -The prefix used for \fBTextfile\fP() file names, -the null string by default. - -.IP TEXTFILESUFFIX -The suffix used for \fBTextfile\fP() file names; -\fB.txt\fP by default. - -.IP TOOLS -A list of the names of the Tool specifications -that are part of this construction environment. - -.IP UNCHANGED_SOURCES -A reserved variable name -that may not be set or used in a construction environment. -(See "Variable Substitution," below.) - -.IP UNCHANGED_TARGETS -A reserved variable name -that may not be set or used in a construction environment. -(See "Variable Substitution," below.) - -.IP VENDOR -The person or organization who supply the packaged software. -This is used to fill in the -.B Vendor: -field in the controlling information for RPM packages, -and the -.B Manufacturer: -field in the controlling information for MSI packages. - -.IP VERSION -The version of the project, specified as a string. - -.IP WIN32_INSERT_DEF -A deprecated synonym for \fB$WINDOWS_INSERT_DEF\fP. - -.IP WIN32DEFPREFIX -A deprecated synonym for \fB$WINDOWSDEFPREFIX\fP. - -.IP WIN32DEFSUFFIX -A deprecated synonym for \fB$WINDOWSDEFSUFFIX\fP. - -.IP WIN32EXPPREFIX -A deprecated synonym for \fB$WINDOWSEXPSUFFIX\fP. - -.IP WIN32EXPSUFFIX -A deprecated synonym for \fB$WINDOWSEXPSUFFIX\fP. - -.IP WINDOWS_EMBED_MANIFEST -Set this variable to True or 1 to embed the compiler-generated manifest -(normally \fB${TARGET}.manifest\fP) -into all Windows exes and DLLs built with this environment, -as a resource during their link step. -This is done using \fB$MT\fP and \fB$MTEXECOM\fP and \fB$MTSHLIBCOM\fP. - -.IP WINDOWS_INSERT_DEF -When this is set to true, -a library build of a Windows shared library -(\fB.dll\fP file) -will also build a corresponding \fB.def\fP file -at the same time, -if a \fB.def\fP file -is not already listed as a build target. -The default is 0 (do not build a \fB.def\fP file). - -.IP WINDOWS_INSERT_MANIFEST -When this is set to true, -.B scons -will be aware of the -.B .manifest -files generated by Microsoft Visua C/C++ 8. - -.IP WINDOWSDEFPREFIX -The prefix used for Windows \fB.def\fP file names. - -.IP WINDOWSDEFSUFFIX -The suffix used for Windows \fB.def\fP file names. - -.IP WINDOWSEXPPREFIX -The prefix used for Windows \fB.exp\fP file names. - -.IP WINDOWSEXPSUFFIX -The suffix used for Windows \fB.exp\fP file names. - -.IP WINDOWSPROGMANIFESTPREFIX -The prefix used for executable program \fB.manifest\fP files -generated by Microsoft Visual C/C++. - -.IP WINDOWSPROGMANIFESTSUFFIX -The suffix used for executable program \fB.manifest\fP files -generated by Microsoft Visual C/C++. - -.IP WINDOWSSHLIBMANIFESTPREFIX -The prefix used for shared library \fB.manifest\fP files -generated by Microsoft Visual C/C++. - -.IP WINDOWSSHLIBMANIFESTSUFFIX -The suffix used for shared library \fB.manifest\fP files -generated by Microsoft Visual C/C++. - -.IP X_IPK_DEPENDS -This is used to fill in the -.B Depends: -field in the controlling information for Ipkg packages. - -.IP X_IPK_DESCRIPTION -This is used to fill in the -.B Description: -field in the controlling information for Ipkg packages. -The default value is -.B "$SUMMARY\\n$DESCRIPTION" -.IP X_IPK_MAINTAINER -This is used to fill in the -.B Maintainer: -field in the controlling information for Ipkg packages. - -.IP X_IPK_PRIORITY -This is used to fill in the -.B Priority: -field in the controlling information for Ipkg packages. - -.IP X_IPK_SECTION -This is used to fill in the -.B Section: -field in the controlling information for Ipkg packages. - -.IP X_MSI_LANGUAGE -This is used to fill in the -.B Language: -attribute in the controlling information for MSI packages. - -.IP X_MSI_LICENSE_TEXT -The text of the software license in RTF format. -Carriage return characters will be -replaced with the RTF equivalent \\\\par. - -.IP X_MSI_UPGRADE_CODE -TODO - -.IP X_RPM_AUTOREQPROV -This is used to fill in the -.B AutoReqProv: -field in the RPM -\fB.spec\fP file. - -.IP X_RPM_BUILD -internal, but overridable - -.IP X_RPM_BUILDREQUIRES -This is used to fill in the -.B BuildRequires: -field in the RPM -\fB.spec\fP file. - -.IP X_RPM_BUILDROOT -internal, but overridable - -.IP X_RPM_CLEAN -internal, but overridable - -.IP X_RPM_CONFLICTS -This is used to fill in the -.B Conflicts: -field in the RPM -\fB.spec\fP file. - -.IP X_RPM_DEFATTR -This value is used as the default attributes -for the files in the RPM package. -The default value is -.BR (-,root,root) . - -.IP X_RPM_DISTRIBUTION -This is used to fill in the -.B Distribution: -field in the RPM -\fB.spec\fP file. - -.IP X_RPM_EPOCH -This is used to fill in the -.B Epoch: -field in the controlling information for RPM packages. - -.IP X_RPM_EXCLUDEARCH -This is used to fill in the -.B ExcludeArch: -field in the RPM -\fB.spec\fP file. - -.IP X_RPM_EXLUSIVEARCH -This is used to fill in the -.B ExclusiveArch: -field in the RPM -\fB.spec\fP file. - -.IP X_RPM_GROUP -This is used to fill in the -.B Group: -field in the RPM -\fB.spec\fP file. - -.IP X_RPM_GROUP_lang -This is used to fill in the -.B Group(lang): -field in the RPM -\fB.spec\fP file. -Note that -.I lang -is not literal -and should be replaced by -the appropriate language code. - -.IP X_RPM_ICON -This is used to fill in the -.B Icon: -field in the RPM -\fB.spec\fP file. - -.IP X_RPM_INSTALL -internal, but overridable - -.IP X_RPM_PACKAGER -This is used to fill in the -.B Packager: -field in the RPM -\fB.spec\fP file. - -.IP X_RPM_POSTINSTALL -This is used to fill in the -.B %post: -section in the RPM -\fB.spec\fP file. - -.IP X_RPM_POSTUNINSTALL -This is used to fill in the -.B %postun: -section in the RPM -\fB.spec\fP file. - -.IP X_RPM_PREFIX -This is used to fill in the -.B Prefix: -field in the RPM -\fB.spec\fP file. - -.IP X_RPM_PREINSTALL -This is used to fill in the -.B %pre: -section in the RPM -\fB.spec\fP file. - -.IP X_RPM_PREP -internal, but overridable - -.IP X_RPM_PREUNINSTALL -This is used to fill in the -.B %preun: -section in the RPM -\fB.spec\fP file. - -.IP X_RPM_PROVIDES -This is used to fill in the -.B Provides: -field in the RPM -\fB.spec\fP file. - -.IP X_RPM_REQUIRES -This is used to fill in the -.B Requires: -field in the RPM -\fB.spec\fP file. - -.IP X_RPM_SERIAL -This is used to fill in the -.B Serial: -field in the RPM -\fB.spec\fP file. - -.IP X_RPM_URL -This is used to fill in the -.B Url: -field in the RPM -\fB.spec\fP file. - -.IP XGETTEXT -Path to \fBxgettext(1)\fP program (found via -.BR Detect() ). -See &t-link-xgettext; tool and \fBPOTUpdate\fP() builder. - -.IP XGETTEXTCOM -Complete xgettext command line. -See &t-link-xgettext; tool and \fBPOTUpdate\fP() builder. - -.IP XGETTEXTCOMSTR -A string that is shown when \fBxgettext(1)\fP command is invoked -(default: \fB''\fP, which means "print \fB$XGETTEXTCOM\fP"). -See &t-link-xgettext; tool and \fBPOTUpdate\fP() builder. - -.IP _XGETTEXTDOMAIN -Internal "macro". Generates \fBxgettext\fP domain name -form source and target (default: \fB'${TARGET.filebase}'\fP). - -.IP XGETTEXTFLAGS -Additional flags to \fBxgettext(1)\fP. -See &t-link-xgettext; tool and \fBPOTUpdate\fP() builder. - -.IP XGETTEXTFROM -Name of file containing list of \fBxgettext(1)\fP's source -files. Autotools' users know this as \fBPOTFILES.in\fP so they -will in most cases set \fBXGETTEXTFROM="POTFILES.in"\fP here. -The \fB$XGETTEXTFROM\fP files have same syntax and semantics as the well known -GNU \fBPOTFILES.in\fP. -See &t-link-xgettext; tool and \fBPOTUpdate\fP() builder. - -.IP _XGETTEXTFROMFLAGS -Internal "macro". Genrates list of \fB\-D<dir>\fP flags -from the \fB$XGETTEXTPATH\fP list. - -.IP XGETTEXTFROMPREFIX -This flag is used to add single \fB$XGETTEXTFROM\fP file to -\fBxgettext(1)\fP's commandline (default: -.BR '-f' ). - -.IP XGETTEXTFROMSUFFIX -(default: \fB''\fP) - -.IP XGETTEXTPATH -List of directories, there \fBxgettext(1)\fP will look for -source files (default: \fB[]\fP). -<note>This variable works only together with \fB$XGETTEXTFROM\fP -</para></note> -See also &t-link-xgettext; tool and \fBPOTUpdate\fP() builder. - -.IP _XGETTEXTPATHFLAGS -Internal "macro". Generates list of \fB\-f<file>\fP flags -from \fB$XGETTEXTFROM\fP. - -.IP XGETTEXTPATHPREFIX -This flag is used to add single search path to -\fBxgettext(1)\fP's commandline (default: -.BR '-D' ). - -.IP XGETTEXTPATHSUFFIX -(default: \fB''\fP) - -.IP YACC -The parser generator. - -.IP YACCCOM -The command line used to call the parser generator -to generate a source file. - -.IP YACCCOMSTR -The string displayed when generating a source file -using the parser generator. -If this is not set, then \fB$YACCCOM\fP (the command line) is displayed. - -.ES -env = Environment(YACCCOMSTR = "Yacc'ing $TARGET from $SOURCES") -.EE - -.IP YACCFLAGS -General options passed to the parser generator. -If \fB$YACCFLAGS\fP contains a \fB\-d\fP option, -SCons assumes that the call will also create a .h file -(if the yacc source file ends in a .y suffix) -or a .hpp file -(if the yacc source file ends in a .yy suffix) - -.IP YACCHFILESUFFIX -The suffix of the C -header file generated by the parser generator -when the -.B \-d -option is used. -Note that setting this variable does not cause -the parser generator to generate a header -file with the specified suffix, -it exists to allow you to specify -what suffix the parser generator will use of its own accord. -The default value is -.BR .h . - -.IP YACCHXXFILESUFFIX -The suffix of the C++ -header file generated by the parser generator -when the -.B \-d -option is used. -Note that setting this variable does not cause -the parser generator to generate a header -file with the specified suffix, -it exists to allow you to specify -what suffix the parser generator will use of its own accord. -The default value is -.BR .hpp , -except on Mac OS X, -where the default is -.BR ${TARGET.suffix}.h . -because the default &bison; parser generator just -appends \fB.h\fP -to the name of the generated C++ file. - -.IP YACCVCGFILESUFFIX -The suffix of the file -containing the VCG grammar automaton definition -when the -.B \-\-graph= -option is used. -Note that setting this variable does not cause -the parser generator to generate a VCG -file with the specified suffix, -it exists to allow you to specify -what suffix the parser generator will use of its own accord. -The default value is -.BR .vcg . - -.IP ZIP -The zip compression and file packaging utility. - -.IP ZIPCOM -The command line used to call the zip utility, -or the internal Python function used to create a -zip archive. - -.IP ZIPCOMPRESSION -The -.I compression -flag -from the Python -.B zipfile -module used by the internal Python function -to control whether the zip archive -is compressed or not. -The default value is -.BR zipfile.ZIP_DEFLATED , -which creates a compressed zip archive. -This value has no effect if the -.B zipfile -module is unavailable. - -.IP ZIPCOMSTR -The string displayed when archiving files -using the zip utility. -If this is not set, then \fB$ZIPCOM\fP -(the command line or internal Python function) is displayed. - -.ES -env = Environment(ZIPCOMSTR = "Zipping $TARGET") -.EE - -.IP ZIPFLAGS -General options passed to the zip utility. - -.IP ZIPSUFFIX -The suffix used for zip file names. -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -'\" END GENERATED CONSTRUCTION VARIABLE DESCRIPTIONS -'\" -'\" The descriptions above of the various SCons construction variables -'\" are generated from the .xml files that live next to the various -'\" Python modules in the build enginer library. If you're reading -'\" this [gnt]roff file with an eye towards patching this man page, -'\" you can still submit a diff against this text, but it will have to -'\" be translated to a diff against the underlying .xml file before the -'\" patch is actually accepted. If you do that yourself, it will make -'\" it easier to integrate the patch. -'\" -'\" END GENERATED CONSTRUCTION VARIABLE DESCRIPTIONS -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" - -.LP -Construction variables can be retrieved and set using the -.B Dictionary -method of the construction environment: - -.ES -dict = env.Dictionary() -dict["CC"] = "cc" -.EE - -or using the [] operator: - -.ES -env["CC"] = "cc" -.EE - -Construction variables can also be passed to the construction environment -constructor: - -.ES -env = Environment(CC="cc") -.EE - -or when copying a construction environment using the -.B Clone -method: - -.ES -env2 = env.Clone(CC="cl.exe") -.EE - -.SS Configure Contexts - -.B scons -supports -.I configure contexts, -an integrated mechanism similar to the -various AC_CHECK macros in GNU autoconf -for testing for the existence of C header -files, libraries, etc. -In contrast to autoconf, -.B scons -does not maintain an explicit cache of the tested values, -but uses its normal dependency tracking to keep the checked values -up to date. However, users may override this behaviour with the -.B --config -command line option. - -The following methods can be used to perform checks: - -.TP -.RI Configure( env ", [" custom_tests ", " conf_dir ", " log_file ", " config_h ", " clean ", " help]) -.TP -.RI env.Configure([ custom_tests ", " conf_dir ", " log_file ", " config_h ", " clean ", " help]) -This creates a configure context, which can be used to perform checks. -.I env -specifies the environment for building the tests. -This environment may be modified when performing checks. -.I custom_tests -is a dictionary containing custom tests. -See also the section about custom tests below. -By default, no custom tests are added to the configure context. -.I conf_dir -specifies a directory where the test cases are built. -Note that this directory is not used for building -normal targets. -The default value is the directory -#/.sconf_temp. -.I log_file -specifies a file which collects the output from commands -that are executed to check for the existence of header files, libraries, etc. -The default is the file #/config.log. -If you are using the -.BR VariantDir () -method, -you may want to specify a subdirectory under your variant directory. -.I config_h -specifies a C header file where the results of tests -will be written, e.g. #define HAVE_STDIO_H, #define HAVE_LIBM, etc. -The default is to not write a -.B config.h -file. -You can specify the same -.B config.h -file in multiple calls to Configure, -in which case -.B scons -will concatenate all results in the specified file. -Note that SCons -uses its normal dependency checking -to decide if it's necessary to rebuild -the specified -.I config_h -file. -This means that the file is not necessarily re-built each -time scons is run, -but is only rebuilt if its contents will have changed -and some target that depends on the -.I config_h -file is being built. - -The optional -.B clean -and -.B help -arguments can be used to suppress execution of the configuration -tests when the -.B -c/--clean -or -.B -H/-h/--help -options are used, respectively. -The default behavior is always to execute -configure context tests, -since the results of the tests may -affect the list of targets to be cleaned -or the help text. -If the configure tests do not affect these, -then you may add the -.B clean=False -or -.B help=False -arguments -(or both) -to avoid unnecessary test execution. - -.EE -A created -.B Configure -instance has the following associated methods: - -.TP -.RI SConf.Finish( context ) -.TP -.IR sconf .Finish() -This method should be called after configuration is done. -It returns the environment as modified -by the configuration checks performed. -After this method is called, no further checks can be performed -with this configuration context. -However, you can create a new -.RI Configure -context to perform additional checks. -Only one context should be active at a time. - -The following Checks are predefined. -(This list will likely grow larger as time -goes by and developers contribute new useful tests.) - -.TP -.RI SConf.CheckHeader( context ", " header ", [" include_quotes ", " language ]) -.TP -.IR sconf .CheckHeader( header ", [" include_quotes ", " language ]) -Checks if -.I header -is usable in the specified language. -.I header -may be a list, -in which case the last item in the list -is the header file to be checked, -and the previous list items are -header files whose -.B #include -lines should precede the -header line being checked for. -The optional argument -.I include_quotes -must be -a two character string, where the first character denotes the opening -quote and the second character denotes the closing quote. -By default, both characters are " (double quote). -The optional argument -.I language -should be either -.B C -or -.B C++ -and selects the compiler to be used for the check. -Returns 1 on success and 0 on failure. - -.TP -.RI SConf.CheckCHeader( context ", " header ", [" include_quotes ]) -.TP -.IR sconf .CheckCHeader( header ", [" include_quotes ]) -This is a wrapper around -.B SConf.CheckHeader -which checks if -.I header -is usable in the C language. -.I header -may be a list, -in which case the last item in the list -is the header file to be checked, -and the previous list items are -header files whose -.B #include -lines should precede the -header line being checked for. -The optional argument -.I include_quotes -must be -a two character string, where the first character denotes the opening -quote and the second character denotes the closing quote (both default -to \N'34'). -Returns 1 on success and 0 on failure. - -.TP -.RI SConf.CheckCXXHeader( context ", " header ", [" include_quotes ]) -.TP -.IR sconf .CheckCXXHeader( header ", [" include_quotes ]) -This is a wrapper around -.B SConf.CheckHeader -which checks if -.I header -is usable in the C++ language. -.I header -may be a list, -in which case the last item in the list -is the header file to be checked, -and the previous list items are -header files whose -.B #include -lines should precede the -header line being checked for. -The optional argument -.I include_quotes -must be -a two character string, where the first character denotes the opening -quote and the second character denotes the closing quote (both default -to \N'34'). -Returns 1 on success and 0 on failure. - -.TP -.RI SConf.CheckFunc( context, ", " function_name ", [" header ", " language ]) -.TP -.IR sconf .CheckFunc( function_name ", [" header ", " language ]) -Checks if the specified -C or C++ function is available. -.I function_name -is the name of the function to check for. -The optional -.I header -argument is a string -that will be -placed at the top -of the test file -that will be compiled -to check if the function exists; -the default is: -.ES -#ifdef __cplusplus -extern "C" -#endif -char function_name(); -.EE -The optional -.I language -argument should be -.B C -or -.B C++ -and selects the compiler to be used for the check; -the default is "C". - -.TP -.RI SConf.CheckLib( context ", [" library ", " symbol ", " header ", " language ", " autoadd=1 ]) -.TP -.IR sconf .CheckLib([ library ", " symbol ", " header ", " language ", " autoadd=1 ]) -Checks if -.I library -provides -.IR symbol . -If the value of -.I autoadd -is 1 and the library provides the specified -.IR symbol , -appends the library to the LIBS construction environment variable. -.I library -may also be None (the default), -in which case -.I symbol -is checked with the current LIBS variable, -or a list of library names, -in which case each library in the list -will be checked for -.IR symbol . -If -.I symbol -is not set or is -.BR None , -then -.BR SConf.CheckLib () -just checks if -you can link against the specified -.IR library . -The optional -.I language -argument should be -.B C -or -.B C++ -and selects the compiler to be used for the check; -the default is "C". -The default value for -.I autoadd -is 1. -This method returns 1 on success and 0 on error. - -.TP -.RI SConf.CheckLibWithHeader( context ", " library ", " header ", " language ", [" call ", " autoadd ]) -.TP -.IR sconf .CheckLibWithHeader( library ", " header ", " language ", [" call ", " autoadd ]) - -In contrast to the -.RI SConf.CheckLib -call, this call provides a more sophisticated way to check against libraries. -Again, -.I library -specifies the library or a list of libraries to check. -.I header -specifies a header to check for. -.I header -may be a list, -in which case the last item in the list -is the header file to be checked, -and the previous list items are -header files whose -.B #include -lines should precede the -header line being checked for. -.I language -may be one of 'C','c','CXX','cxx','C++' and 'c++'. -.I call -can be any valid expression (with a trailing ';'). -If -.I call -is not set, -the default simply checks that you -can link against the specified -.IR library . -.I autoadd -specifies whether to add the library to the environment (only if the check -succeeds). This method returns 1 on success and 0 on error. - -.TP -.RI SConf.CheckType( context ", " type_name ", [" includes ", " language ]) -.TP -.IR sconf .CheckType( type_name ", [" includes ", " language ]) -Checks for the existence of a type defined by -.BR typedef . -.I type_name -specifies the typedef name to check for. -.I includes -is a string containing one or more -.B #include -lines that will be inserted into the program -that will be run to test for the existence of the type. -The optional -.I language -argument should be -.B C -or -.B C++ -and selects the compiler to be used for the check; -the default is "C". -Example: -.ES -sconf.CheckType('foo_type', '#include "my_types.h"', 'C++') -.EE - -.TP -.RI Configure.CheckCC( self ) -Checks whether the C compiler (as defined by the CC construction variable) works -by trying to compile a small source file. - -By default, SCons only detects if there is a program with the correct name, not -if it is a functioning compiler. - -This uses the exact same command than the one used by the object builder for C -source file, so it can be used to detect if a particular compiler flag works or -not. - -.TP -.RI Configure.CheckCXX( self ) -Checks whether the C++ compiler (as defined by the CXX construction variable) -works by trying to compile a small source file. By default, SCons only detects -if there is a program with the correct name, not if it is a functioning compiler. - -This uses the exact same command than the one used by the object builder for -CXX source files, so it can be used to detect if a particular compiler flag -works or not. - -.TP -.RI Configure.CheckSHCC( self ) -Checks whether the C compiler (as defined by the SHCC construction variable) works -by trying to compile a small source file. By default, SCons only detects if -there is a program with the correct name, not if it is a functioning compiler. - -This uses the exact same command than the one used by the object builder for C -source file, so it can be used to detect if a particular compiler flag works or -not. This does not check whether the object code can be used to build a shared -library, only that the compilation (not link) succeeds. - -.TP -.RI Configure.CheckSHCXX( self ) -Checks whether the C++ compiler (as defined by the SHCXX construction variable) -works by trying to compile a small source file. By default, SCons only detects -if there is a program with the correct name, not if it is a functioning compiler. - -This uses the exact same command than the one used by the object builder for -CXX source files, so it can be used to detect if a particular compiler flag -works or not. This does not check whether the object code can be used to build -a shared library, only that the compilation (not link) succeeds. - -.EE -Example of a typical Configure usage: - -.ES -env = Environment() -conf = Configure( env ) -if not conf.CheckCHeader( 'math.h' ): - print 'We really need math.h!' - Exit(1) -if conf.CheckLibWithHeader( 'qt', 'qapp.h', 'c++', - 'QApplication qapp(0,0);' ): - # do stuff for qt - usage, e.g. - conf.env.Append( CPPFLAGS = '-DWITH_QT' ) -env = conf.Finish() -.EE - -.TP -.RI SConf.CheckTypeSize( context ", " type_name ", [" header ", " language ", " expect ]) -.TP -.IR sconf .CheckTypeSize( type_name ", [" header ", " language ", " expect ]) -Checks for the size of a type defined by -.BR typedef . -.I type_name -specifies the typedef name to check for. -The optional -.I header -argument is a string -that will be -placed at the top -of the test file -that will be compiled -to check if the function exists; -the default is empty. -The optional -.I language -argument should be -.B C -or -.B C++ -and selects the compiler to be used for the check; -the default is "C". -The optional -.I expect -argument should be an integer. -If this argument is used, -the function will only check whether the type -given in type_name has the expected size (in bytes). -For example, -.B "CheckTypeSize('short', expect = 2)" -will return success only if short is two bytes. - -.ES -.EE - -.TP -.RI SConf.CheckDeclaration( context ", " symbol ", [" includes ", " language ]) -.TP -.IR sconf .CheckDeclaration( symbol ", [" includes ", " language ]) -Checks if the specified -.I symbol -is declared. -.I includes -is a string containing one or more -.B #include -lines that will be inserted into the program -that will be run to test for the existence of the type. -The optional -.I language -argument should be -.B C -or -.B C++ -and selects the compiler to be used for the check; -the default is "C". - -.TP -.RI SConf.Define( context ", " symbol ", [" value ", " comment ]) -.TP -.IR sconf .Define( symbol ", [" value ", " comment ]) -This function does not check for anything, but defines a -preprocessor symbol that will be added to the configuration header file. -It is the equivalent of AC_DEFINE, -and defines the symbol -.I name -with the optional -.B value -and the optional comment -.BR comment . - -.IP -Examples: - -.ES -env = Environment() -conf = Configure( env ) - -# Puts the following line in the config header file: -# #define A_SYMBOL -conf.Define('A_SYMBOL') - -# Puts the following line in the config header file: -# #define A_SYMBOL 1 -conf.Define('A_SYMBOL', 1) -.EE - -.IP -Be careful about quoting string values, though: - -.ES -env = Environment() -conf = Configure( env ) - -# Puts the following line in the config header file: -# #define A_SYMBOL YA -conf.Define('A_SYMBOL', "YA") - -# Puts the following line in the config header file: -# #define A_SYMBOL "YA" -conf.Define('A_SYMBOL', '"YA"') -.EE - -.IP -For comment: - -.ES -env = Environment() -conf = Configure( env ) - -# Puts the following lines in the config header file: -# /* Set to 1 if you have a symbol */ -# #define A_SYMBOL 1 -conf.Define('A_SYMBOL', 1, 'Set to 1 if you have a symbol') -.EE - -.EE -You can define your own custom checks. -in addition to the predefined checks. -These are passed in a dictionary to the Configure function. -This dictionary maps the names of the checks -to user defined Python callables -(either Python functions or class instances implementing the -.I __call__ -method). -The first argument of the call is always a -.I CheckContext -instance followed by the arguments, -which must be supplied by the user of the check. -These CheckContext instances define the following methods: - -.TP -.RI CheckContext.Message( self ", " text ) - -Usually called before the check is started. -.I text -will be displayed to the user, e.g. 'Checking for library X...' - -.TP -.RI CheckContext.Result( self, ", " res ) - -Usually called after the check is done. -.I res -can be either an integer or a string. In the former case, 'yes' (res != 0) -or 'no' (res == 0) is displayed to the user, in the latter case the -given string is displayed. - -.TP -.RI CheckContext.TryCompile( self ", " text ", " extension ) -Checks if a file with the specified -.I extension -(e.g. '.c') containing -.I text -can be compiled using the environment's -.B Object -builder. Returns 1 on success and 0 on failure. - -.TP -.RI CheckContext.TryLink( self ", " text ", " extension ) -Checks, if a file with the specified -.I extension -(e.g. '.c') containing -.I text -can be compiled using the environment's -.B Program -builder. Returns 1 on success and 0 on failure. - -.TP -.RI CheckContext.TryRun( self ", " text ", " extension ) -Checks, if a file with the specified -.I extension -(e.g. '.c') containing -.I text -can be compiled using the environment's -.B Program -builder. On success, the program is run. If the program -executes successfully -(that is, its return status is 0), -a tuple -.I (1, outputStr) -is returned, where -.I outputStr -is the standard output of the -program. -If the program fails execution -(its return status is non-zero), -then (0, '') is returned. - -.TP -.RI CheckContext.TryAction( self ", " action ", [" text ", " extension ]) -Checks if the specified -.I action -with an optional source file (contents -.I text -, extension -.I extension -= '' -) can be executed. -.I action -may be anything which can be converted to a -.B scons -.RI Action. -On success, -.I (1, outputStr) -is returned, where -.I outputStr -is the content of the target file. -On failure -.I (0, '') -is returned. - -.TP -.RI CheckContext.TryBuild( self ", " builder ", [" text ", " extension ]) -Low level implementation for testing specific builds; -the methods above are based on this method. -Given the Builder instance -.I builder -and the optional -.I text -of a source file with optional -.IR extension , -this method returns 1 on success and 0 on failure. In addition, -.I self.lastTarget -is set to the build target node, if the build was successful. - -.EE -Example for implementing and using custom tests: - -.ES -def CheckQt(context, qtdir): - context.Message( 'Checking for qt ...' ) - lastLIBS = context.env['LIBS'] - lastLIBPATH = context.env['LIBPATH'] - lastCPPPATH= context.env['CPPPATH'] - context.env.Append(LIBS = 'qt', LIBPATH = qtdir + '/lib', CPPPATH = qtdir + '/include' ) - ret = context.TryLink(""" -#include <qapp.h> -int main(int argc, char **argv) { - QApplication qapp(argc, argv); - return 0; -} -""") - if not ret: - context.env.Replace(LIBS = lastLIBS, LIBPATH=lastLIBPATH, CPPPATH=lastCPPPATH) - context.Result( ret ) - return ret - -env = Environment() -conf = Configure( env, custom_tests = { 'CheckQt' : CheckQt } ) -if not conf.CheckQt('/usr/lib/qt'): - print 'We really need qt!' - Exit(1) -env = conf.Finish() -.EE - -.SS Command-Line Construction Variables - -Often when building software, -some variables must be specified at build time. -For example, libraries needed for the build may be in non-standard -locations, or site-specific compiler options may need to be passed to the -compiler. -.B scons -provides a -.B Variables -object to support overriding construction variables -on the command line: -.ES -$ scons VARIABLE=foo -.EE -The variable values can also be specified in a text-based SConscript file. -To create a Variables object, call the Variables() function: - -.TP -.RI Variables([ files "], [" args ]) -This creates a Variables object that will read construction variables from -the file or list of filenames specified in -.IR files . -If no files are specified, -or the -.I files -argument is -.BR None , -then no files will be read. -The optional argument -.I args -is a dictionary of -values that will override anything read from the specified files; -it is primarily intended to be passed the -.B ARGUMENTS -dictionary that holds variables -specified on the command line. -Example: - -.ES -vars = Variables('custom.py') -vars = Variables('overrides.py', ARGUMENTS) -vars = Variables(None, {FOO:'expansion', BAR:7}) -.EE - -Variables objects have the following methods: - -.TP -.RI Add( key ", [" help ", " default ", " validator ", " converter ]) -This adds a customizable construction variable to the Variables object. -.I key -is the name of the variable. -.I help -is the help text for the variable. -.I default -is the default value of the variable; -if the default value is -.B None -and there is no explicit value specified, -the construction variable will -.I not -be added to the construction environment. -.I validator -is called to validate the value of the variable, and should take three -arguments: key, value, and environment. -The recommended way to handle an invalid value is -to raise an exception (see example below). -.I converter -is called to convert the value before putting it in the environment, and -should take either a value, or the value and environment, as parameters. -The -.I converter -must return a value, -which will be converted into a string -before being validated by the -.I validator -(if any) -and then added to the environment. - -Examples: - -.ES -vars.Add('CC', 'The C compiler') - -def validate_color(key, val, env): - if not val in ['red', 'blue', 'yellow']: - raise Exception("Invalid color value '%s'" % val) -vars.Add('COLOR', validator=valid_color) -.EE - -.TP -.RI AddVariables( list ) -A wrapper script that adds -multiple customizable construction variables -to a Variables object. -.I list -is a list of tuple or list objects -that contain the arguments -for an individual call to the -.B Add -method. - -.ES -opt.AddVariables( - ('debug', '', 0), - ('CC', 'The C compiler'), - ('VALIDATE', 'An option for testing validation', - 'notset', validator, None), - ) -.EE - -.TP -.RI Update( env ", [" args ]) -This updates a construction environment -.I env -with the customized construction variables. -Any specified variables that are -.I not -configured for the Variables object -will be saved and may be -retrieved with the -.BR UnknownVariables () -method, below. - -Normally this method is not called directly, -but is called indirectly by passing the Variables object to -the Environment() function: - -.ES -env = Environment(variables=vars) -.EE - -.IP -The text file(s) that were specified -when the Variables object was created -are executed as Python scripts, -and the values of (global) Python variables set in the file -are added to the construction environment. - -Example: - -.ES -CC = 'my_cc' -.EE - -.TP -.RI UnknownVariables( ) -Returns a dictionary containing any -variables that were specified -either in the files or the dictionary -with which the Variables object was initialized, -but for which the Variables object was -not configured. - -.ES -env = Environment(variables=vars) -for key, value in vars.UnknownVariables(): - print "unknown variable: %s=%s" % (key, value) -.EE - -.TP -.RI Save( filename ", " env ) -This saves the currently set variables into a script file named -.I filename -that can be used on the next invocation to automatically load the current -settings. This method combined with the Variables method can be used to -support caching of variables between runs. - -.ES -env = Environment() -vars = Variables(['variables.cache', 'custom.py']) -vars.Add(...) -vars.Update(env) -vars.Save('variables.cache', env) -.EE - -.TP -.RI GenerateHelpText( env ", [" sort ]) -This generates help text documenting the customizable construction -variables suitable to passing in to the Help() function. -.I env -is the construction environment that will be used to get the actual values -of customizable variables. Calling with -an optional -.I sort -function -will cause the output to be sorted -by the specified argument. -The specific -.I sort -function -should take two arguments -and return --1, 0 or 1 -(like the standard Python -.I cmp -function). - -.ES -Help(vars.GenerateHelpText(env)) -Help(vars.GenerateHelpText(env, sort=cmp)) -.EE - -.TP -.RI FormatVariableHelpText( env ", " opt ", " help ", " default ", " actual ) -This method returns a formatted string -containing the printable help text -for one option. -It is normally not called directly, -but is called by the -.IR GenerateHelpText () -method to create the returned help text. -It may be overridden with your own -function that takes the arguments specified above -and returns a string of help text formatted to your liking. -Note that the -.IR GenerateHelpText () -will not put any blank lines or extra -characters in between the entries, -so you must add those characters to the returned -string if you want the entries separated. - -.ES -def my_format(env, opt, help, default, actual): - fmt = "\n%s: default=%s actual=%s (%s)\n" - return fmt % (opt, default. actual, help) -vars.FormatVariableHelpText = my_format -.EE - -To make it more convenient to work with customizable Variables, -.B scons -provides a number of functions -that make it easy to set up -various types of Variables: - -.TP -.RI BoolVariable( key ", " help ", " default ) -Return a tuple of arguments -to set up a Boolean option. -The option will use -the specified name -.IR key , -have a default value of -.IR default , -and display the specified -.I help -text. -The option will interpret the values -.BR y , -.BR yes , -.BR t , -.BR true , -.BR 1 , -.B on -and -.B all -as true, -and the values -.BR n , -.BR no , -.BR f , -.BR false , -.BR 0 , -.B off -and -.B none -as false. - -.TP -.RI EnumVariable( key ", " help ", " default ", " allowed_values ", [" map ", " ignorecase ]) -Return a tuple of arguments -to set up an option -whose value may be one -of a specified list of legal enumerated values. -The option will use -the specified name -.IR key , -have a default value of -.IR default , -and display the specified -.I help -text. -The option will only support those -values in the -.I allowed_values -list. -The optional -.I map -argument is a dictionary -that can be used to convert -input values into specific legal values -in the -.I allowed_values -list. -If the value of -.I ignore_case -is -.B 0 -(the default), -then the values are case-sensitive. -If the value of -.I ignore_case -is -.BR 1 , -then values will be matched -case-insensitive. -If the value of -.I ignore_case -is -.BR 1 , -then values will be matched -case-insensitive, -and all input values will be -converted to lower case. - -.TP -.RI ListVariable( key ", " help ", " default ", " names ", [", map ]) -Return a tuple of arguments -to set up an option -whose value may be one or more -of a specified list of legal enumerated values. -The option will use -the specified name -.IR key , -have a default value of -.IR default , -and display the specified -.I help -text. -The option will only support the values -.BR all , -.BR none , -or the values in the -.I names -list. -More than one value may be specified, -with all values separated by commas. -The default may be a string of -comma-separated default values, -or a list of the default values. -The optional -.I map -argument is a dictionary -that can be used to convert -input values into specific legal values -in the -.I names -list. - -.TP -.RI PackageVariable( key ", " help ", " default ) -Return a tuple of arguments -to set up an option -whose value is a path name -of a package that may be -enabled, disabled or -given an explicit path name. -The option will use -the specified name -.IR key , -have a default value of -.IR default , -and display the specified -.I help -text. -The option will support the values -.BR yes , -.BR true , -.BR on , -.BR enable -or -.BR search , -in which case the specified -.I default -will be used, -or the option may be set to an -arbitrary string -(typically the path name to a package -that is being enabled). -The option will also support the values -.BR no , -.BR false , -.BR off -or -.BR disable -to disable use of the specified option. - -.TP -.RI PathVariable( key ", " help ", " default ", [" validator ]) -Return a tuple of arguments -to set up an option -whose value is expected to be a path name. -The option will use -the specified name -.IR key , -have a default value of -.IR default , -and display the specified -.I help -text. -An additional -.I validator -may be specified -that will be called to -verify that the specified path -is acceptable. -SCons supplies the -following ready-made validators: -.BR PathVariable.PathExists -(the default), -which verifies that the specified path exists; -.BR PathVariable.PathIsFile , -which verifies that the specified path is an existing file; -.BR PathVariable.PathIsDir , -which verifies that the specified path is an existing directory; -.BR PathVariable.PathIsDirCreate , -which verifies that the specified path is a directory -and will create the specified directory if the path does not exist; -and -.BR PathVariable.PathAccept , -which simply accepts the specific path name argument without validation, -and which is suitable if you want your users -to be able to specify a directory path that will be -created as part of the build process, for example. -You may supply your own -.I validator -function, -which must take three arguments -.RI ( key , -the name of the variable to be set; -.IR val , -the specified value being checked; -and -.IR env , -the construction environment) -and should raise an exception -if the specified value is not acceptable. - -.RE -These functions make it -convenient to create a number -of variables with consistent behavior -in a single call to the -.B AddVariables -method: - -.ES -vars.AddVariables( - BoolVariable('warnings', 'compilation with -Wall and similiar', 1), - EnumVariable('debug', 'debug output and symbols', 'no' - allowed_values=('yes', 'no', 'full'), - map={}, ignorecase=0), # case sensitive - ListVariable('shared', - 'libraries to build as shared libraries', - 'all', - names = list_of_libs), - PackageVariable('x11', - 'use X11 installed here (yes = search some places)', - 'yes'), - PathVariable('qtdir', 'where the root of Qt is installed', qtdir), - PathVariable('foopath', 'where the foo library is installed', foopath, - PathVariable.PathIsDir), - -) -.EE - -.SS File and Directory Nodes - -The -.IR File () -and -.IR Dir () -functions return -.I File -and -.I Dir -Nodes, respectively. -python objects, respectively. -Those objects have several user-visible attributes -and methods that are often useful: - -.IP path -The build path -of the given -file or directory. -This path is relative to the top-level directory -(where the -.B SConstruct -file is found). -The build path is the same as the source path if -.I variant_dir -is not being used. - -.IP abspath -The absolute build path of the given file or directory. - -.IP srcnode() -The -.IR srcnode () -method -returns another -.I File -or -.I Dir -object representing the -.I source -path of the given -.I File -or -.IR Dir . -The - -.ES -# Get the current build dir's path, relative to top. -Dir('.').path -# Current dir's absolute path -Dir('.').abspath -# Next line is always '.', because it is the top dir's path relative to itself. -Dir('#.').path -File('foo.c').srcnode().path # source path of the given source file. - -# Builders also return File objects: -foo = env.Program('foo.c') -print "foo will be built in %s"%foo.path -.EE - -A -.I Dir -Node or -.I File -Node can also be used to create -file and subdirectory Nodes relative to the generating Node. -A -.I Dir -Node will place the new Nodes within the directory it represents. -A -.I File -node will place the new Nodes within its parent directory -(that is, "beside" the file in question). -If -.I d -is a -.I Dir -(directory) Node and -.I f -is a -.I File -(file) Node, -then these methods are available: - -.TP -.IR d .Dir( name ) -Returns a directory Node for a subdirectory of -.I d -named -.IR name . - -.TP -.IR d .File( name ) -Returns a file Node for a file within -.I d -named -.IR name . - -.TP -.IR d .Entry( name ) -Returns an unresolved Node within -.I d -named -.IR name . - -.TP -.IR f .Dir( name ) -Returns a directory named -.I name -within the parent directory of -.IR f . - -.TP -.IR f .File( name ) -Returns a file named -.I name -within the parent directory of -.IR f . - -.TP -.IR f .Entry( name ) -Returns an unresolved Node named -.I name -within the parent directory of -.IR f . - -.RE -For example: - -.ES -# Get a Node for a file within a directory -incl = Dir('include') -f = incl.File('header.h') - -# Get a Node for a subdirectory within a directory -dist = Dir('project-3.2.1) -src = dist.Dir('src') - -# Get a Node for a file in the same directory -cfile = File('sample.c') -hfile = cfile.File('sample.h') - -# Combined example -docs = Dir('docs') -html = docs.Dir('html') -index = html.File('index.html') -css = index.File('app.css') -.EE - -.SH EXTENDING SCONS -.SS Builder Objects -.B scons -can be extended to build different types of targets -by adding new Builder objects -to a construction environment. -.IR "In general" , -you should only need to add a new Builder object -when you want to build a new type of file or other external target. -If you just want to invoke a different compiler or other tool -to build a Program, Object, Library, or any other -type of output file for which -.B scons -already has an existing Builder, -it is generally much easier to -use those existing Builders -in a construction environment -that sets the appropriate construction variables -(CC, LINK, etc.). - -Builder objects are created -using the -.B Builder -function. -The -.B Builder -function accepts the following arguments: - -.IP action -The command line string used to build the target from the source. -.B action -can also be: -a list of strings representing the command -to be executed and its arguments -(suitable for enclosing white space in an argument), -a dictionary -mapping source file name suffixes to -any combination of command line strings -(if the builder should accept multiple source file extensions), -a Python function; -an Action object -(see the next section); -or a list of any of the above. - -An action function -takes three arguments: -.I source -- a list of source nodes, -.I target -- a list of target nodes, -.I env -- the construction environment. - -.IP prefix -The prefix that will be prepended to the target file name. -This may be specified as a: - -.RS 10 -.HP 6 -* -.IR string , - -.HP 6 -* -.I callable object -- a function or other callable that takes -two arguments (a construction environment and a list of sources) -and returns a prefix, - -.HP 6 -* -.I dictionary -- specifies a mapping from a specific source suffix (of the first -source specified) to a corresponding target prefix. Both the source -suffix and target prefix specifications may use environment variable -substitution, and the target prefix (the 'value' entries in the -dictionary) may also be a callable object. The default target prefix -may be indicated by a dictionary entry with a key value of None. -.RE -.P - -.ES -b = Builder("build_it < $SOURCE > $TARGET", - prefix = "file-") - -def gen_prefix(env, sources): - return "file-" + env['PLATFORM'] + '-' -b = Builder("build_it < $SOURCE > $TARGET", - prefix = gen_prefix) - -b = Builder("build_it < $SOURCE > $TARGET", - suffix = { None: "file-", - "$SRC_SFX_A": gen_prefix }) -.EE - -.IP suffix -The suffix that will be appended to the target file name. -This may be specified in the same manner as the prefix above. -If the suffix is a string, then -.B scons -will append a '.' to the beginning of the suffix if it's not already -there. The string returned by callable object (or obtained from the -dictionary) is untouched and must append its own '.' to the beginning -if one is desired. - -.ES -b = Builder("build_it < $SOURCE > $TARGET" - suffix = "-file") - -def gen_suffix(env, sources): - return "." + env['PLATFORM'] + "-file" -b = Builder("build_it < $SOURCE > $TARGET", - suffix = gen_suffix) - -b = Builder("build_it < $SOURCE > $TARGET", - suffix = { None: ".sfx1", - "$SRC_SFX_A": gen_suffix }) -.EE - -.IP ensure_suffix -When set to any true value, causes -.B scons -to add the target suffix specified by the -.I suffix -keyword to any target strings -that have a different suffix. -(The default behavior is to leave untouched -any target file name that looks like it already has any suffix.) - -.ES -b1 = Builder("build_it < $SOURCE > $TARGET" - suffix = ".out") -b2 = Builder("build_it < $SOURCE > $TARGET" - suffix = ".out", - ensure_suffix) -env = Environment() -env['BUILDERS']['B1'] = b1 -env['BUILDERS']['B2'] = b2 - -# Builds "foo.txt" because ensure_suffix is not set. -env.B1('foo.txt', 'foo.in') - -# Builds "bar.txt.out" because ensure_suffix is set. -env.B2('bar.txt', 'bar.in') -.EE - -.IP src_suffix -The expected source file name suffix. This may be a string or a list -of strings. - -.IP target_scanner -A Scanner object that -will be invoked to find -implicit dependencies for this target file. -This keyword argument should be used -for Scanner objects that find -implicit dependencies -based only on the target file -and the construction environment, -.I not -for implicit dependencies based on source files. -(See the section "Scanner Objects" below, -for information about creating Scanner objects.) - -.IP source_scanner -A Scanner object that -will be invoked to -find implicit dependencies in -any source files -used to build this target file. -This is where you would -specify a scanner to -find things like -.B #include -lines in source files. -The pre-built -.B DirScanner -Scanner object may be used to -indicate that this Builder -should scan directory trees -for on-disk changes to files -that -.B scons -does not know about from other Builder or function calls. -(See the section "Scanner Objects" below, -for information about creating your own Scanner objects.) - -.IP target_factory -A factory function that the Builder will use -to turn any targets specified as strings into SCons Nodes. -By default, -SCons assumes that all targets are files. -Other useful target_factory -values include -.BR Dir , -for when a Builder creates a directory target, -and -.BR Entry , -for when a Builder can create either a file -or directory target. - -Example: - -.ES -MakeDirectoryBuilder = Builder(action=my_mkdir, target_factory=Dir) -env = Environment() -env.Append(BUILDERS = {'MakeDirectory':MakeDirectoryBuilder}) -env.MakeDirectory('new_directory', []) -.EE - -.IP -Note that the call to the MakeDirectory Builder -needs to specify an empty source list -to make the string represent the builder's target; -without that, it would assume the argument is the source, -and would try to deduce the target name from it, -which in the absence of an automatically-added prefix or suffix -would lead to a matching target and source name -and a circular dependency. - -.IP source_factory -A factory function that the Builder will use -to turn any sources specified as strings into SCons Nodes. -By default, -SCons assumes that all source are files. -Other useful source_factory -values include -.BR Dir , -for when a Builder uses a directory as a source, -and -.BR Entry , -for when a Builder can use files -or directories (or both) as sources. - -Example: - -.ES -CollectBuilder = Builder(action=my_mkdir, source_factory=Entry) -env = Environment() -env.Append(BUILDERS = {'Collect':CollectBuilder}) -env.Collect('archive', ['directory_name', 'file_name']) -.EE - -.IP emitter -A function or list of functions to manipulate the target and source -lists before dependencies are established -and the target(s) are actually built. -.B emitter -can also be a string containing a construction variable to expand -to an emitter function or list of functions, -or a dictionary mapping source file suffixes -to emitter functions. -(Only the suffix of the first source file -is used to select the actual emitter function -from an emitter dictionary.) - -An emitter function -takes three arguments: -.I source -- a list of source nodes, -.I target -- a list of target nodes, -.I env -- the construction environment. -An emitter must return a tuple containing two lists, -the list of targets to be built by this builder, -and the list of sources for this builder. - -Example: - -.ES -def e(target, source, env): - return (target + ['foo.foo'], source + ['foo.src']) - -# Simple association of an emitter function with a Builder. -b = Builder("my_build < $TARGET > $SOURCE", - emitter = e) - -def e2(target, source, env): - return (target + ['bar.foo'], source + ['bar.src']) - -# Simple association of a list of emitter functions with a Builder. -b = Builder("my_build < $TARGET > $SOURCE", - emitter = [e, e2]) - -# Calling an emitter function through a construction variable. -env = Environment(MY_EMITTER = e) -b = Builder("my_build < $TARGET > $SOURCE", - emitter = '$MY_EMITTER') - -# Calling a list of emitter functions through a construction variable. -env = Environment(EMITTER_LIST = [e, e2]) -b = Builder("my_build < $TARGET > $SOURCE", - emitter = '$EMITTER_LIST') - -# Associating multiple emitters with different file -# suffixes using a dictionary. -def e_suf1(target, source, env): - return (target + ['another_target_file'], source) -def e_suf2(target, source, env): - return (target, source + ['another_source_file']) -b = Builder("my_build < $TARGET > $SOURCE", - emitter = {'.suf1' : e_suf1, - '.suf2' : e_suf2}) -.EE - -.IP multi -Specifies whether this builder is allowed to be called multiple times for -the same target file(s). The default is 0, which means the builder -can not be called multiple times for the same target file(s). Calling a -builder multiple times for the same target simply adds additional source -files to the target; it is not allowed to change the environment associated -with the target, specify addition environment overrides, or associate a different -builder with the target. - -.IP env -A construction environment that can be used -to fetch source code using this Builder. -(Note that this environment is -.I not -used for normal builds of normal target files, -which use the environment that was -used to call the Builder for the target file.) - -.IP generator -A function that returns a list of actions that will be executed to build -the target(s) from the source(s). -The returned action(s) may be -an Action object, or anything that -can be converted into an Action object -(see the next section). - -The generator function -takes four arguments: -.I source -- a list of source nodes, -.I target -- a list of target nodes, -.I env -- the construction environment, -.I for_signature -- a Boolean value that specifies -whether the generator is being called -for generating a build signature -(as opposed to actually executing the command). -Example: - -.ES -def g(source, target, env, for_signature): - return [["gcc", "-c", "-o"] + target + source] - -b = Builder(generator=g) -.EE - -.IP -The -.I generator -and -.I action -arguments must not both be used for the same Builder. - -.IP src_builder -Specifies a builder to use when a source file name suffix does not match -any of the suffixes of the builder. Using this argument produces a -multi-stage builder. - -.IP single_source -Specifies that this builder expects exactly one source file per call. Giving -more than one source file without target files results in implicitely calling -the builder multiple times (once for each source given). Giving multiple -source files together with target files results in a UserError exception. - -.RE -.IP -The -.I generator -and -.I action -arguments must not both be used for the same Builder. - -.IP source_ext_match -When the specified -.I action -argument is a dictionary, -the default behavior when a builder is passed -multiple source files is to make sure that the -extensions of all the source files match. -If it is legal for this builder to be -called with a list of source files with different extensions, -this check can be suppressed by setting -.B source_ext_match -to -.B None -or some other non-true value. -When -.B source_ext_match -is disable, -.B scons -will use the suffix of the first specified -source file to select the appropriate action from the -.I action -dictionary. - -In the following example, -the setting of -.B source_ext_match -prevents -.B scons -from exiting with an error -due to the mismatched suffixes of -.B foo.in -and -.BR foo.extra . - -.ES -b = Builder(action={'.in' : 'build $SOURCES > $TARGET'}, - source_ext_match = None) - -env = Environment(BUILDERS = {'MyBuild':b}) -env.MyBuild('foo.out', ['foo.in', 'foo.extra']) -.EE - -.IP env -A construction environment that can be used -to fetch source code using this Builder. -(Note that this environment is -.I not -used for normal builds of normal target files, -which use the environment that was -used to call the Builder for the target file.) - -.ES -b = Builder(action="build < $SOURCE > $TARGET") -env = Environment(BUILDERS = {'MyBuild' : b}) -env.MyBuild('foo.out', 'foo.in', my_arg = 'xyzzy') -.EE - -.IP chdir -A directory from which scons -will execute the -action(s) specified -for this Builder. -If the -.B chdir -argument is -a string or a directory Node, -scons will change to the specified directory. -If the -.B chdir -is not a string or Node -and is non-zero, -then scons will change to the -target file's directory. - -Note that scons will -.I not -automatically modify -its expansion of -construction variables like -.B $TARGET -and -.B $SOURCE -when using the chdir -keyword argument--that is, -the expanded file names -will still be relative to -the top-level SConstruct directory, -and consequently incorrect -relative to the chdir directory. -Builders created using chdir keyword argument, -will need to use construction variable -expansions like -.B ${TARGET.file} -and -.B ${SOURCE.file} -to use just the filename portion of the -targets and source. - -.ES -b = Builder(action="build < ${SOURCE.file} > ${TARGET.file}", - chdir=1) -env = Environment(BUILDERS = {'MyBuild' : b}) -env.MyBuild('sub/dir/foo.out', 'sub/dir/foo.in') -.EE - -.B WARNING: -Python only keeps one current directory -location for all of the threads. -This means that use of the -.B chdir -argument -will -.I not -work with the SCons -.B -j -option, -because individual worker threads spawned -by SCons interfere with each other -when they start changing directory. - -.RE -Any additional keyword arguments supplied -when a Builder object is created -(that is, when the Builder() function is called) -will be set in the executing construction -environment when the Builder object is called. -The canonical example here would be -to set a construction variable to -the repository of a source code system. - -Any additional keyword arguments supplied -when a Builder -.I object -is called -will only be associated with the target -created by that particular Builder call -(and any other files built as a -result of the call). - -These extra keyword arguments are passed to the -following functions: -command generator functions, -function Actions, -and emitter functions. - -.SS Action Objects - -The -.BR Builder () -function will turn its -.B action -keyword argument into an appropriate -internal Action object. -You can also explicity create Action objects -using the -.BR Action () -global function, -which can then be passed to the -.BR Builder () -function. -This can be used to configure -an Action object more flexibly, -or it may simply be more efficient -than letting each separate Builder object -create a separate Action -when multiple -Builder objects need to do the same thing. - -The -.BR Action () -global function -returns an appropriate object for the action -represented by the type of the first argument: - -.IP Action -If the first argument is already an Action object, -the object is simply returned. - -.IP String -If the first argument is a string, -a command-line Action is returned. -Note that the command-line string -may be preceded by an -.B @ -(at-sign) -to suppress printing of the specified command line, -or by a -.B \- -(hyphen) -to ignore the exit status from the specified command: - -.ES -Action('$CC -c -o $TARGET $SOURCES') - -# Doesn't print the line being executed. -Action('@build $TARGET $SOURCES') - -# Ignores return value -Action('-build $TARGET $SOURCES') -.EE -.\" XXX From Gary Ruben, 23 April 2002: -.\" What would be useful is a discussion of how you execute command -.\" shell commands ie. what is the process used to spawn the shell, pass -.\" environment variables to it etc., whether there is one shell per -.\" environment or one per command etc. It might help to look at the Gnu -.\" make documentation to see what they think is important to discuss about -.\" a build system. I'm sure you can do a better job of organising the -.\" documentation than they have :-) - -.IP List -If the first argument is a list, -then a list of Action objects is returned. -An Action object is created as necessary -for each element in the list. -If an element -.I within -the list is itself a list, -the internal list is the -command and arguments to be executed via -the command line. -This allows white space to be enclosed -in an argument by defining -a command in a list within a list: - -.ES -Action([['cc', '-c', '-DWHITE SPACE', '-o', '$TARGET', '$SOURCES']]) -.EE - -.IP Function -If the first argument is a Python function, -a function Action is returned. -The Python function must take three keyword arguments, -.B target -(a Node object representing the target file), -.B source -(a Node object representing the source file) -and -.B env -(the construction environment -used for building the target file). -The -.B target -and -.B source -arguments may be lists of Node objects if there is -more than one target file or source file. -The actual target and source file name(s) may -be retrieved from their Node objects -via the built-in Python str() function: - -.ES -target_file_name = str(target) -source_file_names = map(lambda x: str(x), source) -.EE -.IP -The function should return -.B 0 -or -.B None -to indicate a successful build of the target file(s). -The function may raise an exception -or return a non-zero exit status -to indicate an unsuccessful build. - -.ES -def build_it(target = None, source = None, env = None): - # build the target from the source - return 0 - -a = Action(build_it) -.EE - -If the action argument is not one of the above, -None is returned. -.PP - -The second argument is optional and is used to define the output -which is printed when the Action is actually performed. -In the absence of this parameter, -or if it's an empty string, -a default output depending on the type of the action is used. -For example, a command-line action will print the executed command. -The argument must be either a Python function or a string. - -In the first case, -it's a function that returns a string to be printed -to describe the action being executed. -The function may also be specified by the -.IR strfunction = -keyword argument. -Like a function to build a file, -this function must take three keyword arguments: -.B target -(a Node object representing the target file), -.B source -(a Node object representing the source file) -and -.BR env -(a construction environment). -The -.B target -and -.B source -arguments may be lists of Node objects if there is -more than one target file or source file. - -In the second case, you provide the string itself. -The string may also be specified by the -.IR cmdstr = -keyword argument. -The string typically contains variables, notably -$TARGET(S) and $SOURCE(S), or consists of just a single -variable, which is optionally defined somewhere else. -SCons itself heavily uses the latter variant. - -Examples: - -.ES -def build_it(target, source, env): - # build the target from the source - return 0 - -def string_it(target, source, env): - return "building '%s' from '%s'" % (target[0], source[0]) - -# Use a positional argument. -f = Action(build_it, string_it) -s = Action(build_it, "building '$TARGET' from '$SOURCE'") - -# Alternatively, use a keyword argument. -f = Action(build_it, strfunction=string_it) -s = Action(build_it, cmdstr="building '$TARGET' from '$SOURCE'") - -# You can provide a configurable variable. -l = Action(build_it, '$STRINGIT') -.EE - -The third and succeeding arguments, if present, -may either be a construction variable or a list of construction variables -whose values will be included in the signature of the Action -when deciding whether a target should be rebuilt because the action changed. -The variables may also be specified by a -.IR varlist = -keyword parameter; -if both are present, they are combined. -This is necessary whenever you want a target to be rebuilt -when a specific construction variable changes. -This is not often needed for a string action, -as the expanded variables will normally be part of the command line, -but may be needed if a Python function action uses -the value of a construction variable when generating the command line. - -.ES -def build_it(target, source, env): - # build the target from the 'XXX' construction variable - open(target[0], 'w').write(env['XXX']) - return 0 - -# Use positional arguments. -a = Action(build_it, '$STRINGIT', ['XXX']) - -# Alternatively, use a keyword argument. -a = Action(build_it, varlist=['XXX']) -.EE - -The -.BR Action () -global function -can be passed the following -optional keyword arguments -to modify the Action object's behavior: - -.IP -.B chdir -The -.B chdir -keyword argument specifies that -scons will execute the action -after changing to the specified directory. -If the -.B chdir -argument is -a string or a directory Node, -scons will change to the specified directory. -If the -.B chdir -argument -is not a string or Node -and is non-zero, -then scons will change to the -target file's directory. - -Note that scons will -.I not -automatically modify -its expansion of -construction variables like -.B $TARGET -and -.B $SOURCE -when using the chdir -keyword argument--that is, -the expanded file names -will still be relative to -the top-level SConstruct directory, -and consequently incorrect -relative to the chdir directory. -Builders created using chdir keyword argument, -will need to use construction variable -expansions like -.B ${TARGET.file} -and -.B ${SOURCE.file} -to use just the filename portion of the -targets and source. - -.ES -a = Action("build < ${SOURCE.file} > ${TARGET.file}", - chdir=1) -.EE - -.IP -.B exitstatfunc -The -.BR Action () -global function -also takes an -.B exitstatfunc -keyword argument -which specifies a function -that is passed the exit status -(or return value) -from the specified action -and can return an arbitrary -or modified value. -This can be used, for example, -to specify that an Action object's -return value should be ignored -under special conditions -and SCons should, therefore, -consider that the action always suceeds: - -.ES -def always_succeed(s): - # Always return 0, which indicates success. - return 0 -a = Action("build < ${SOURCE.file} > ${TARGET.file}", - exitstatfunc=always_succeed) -.EE - -.IP -.B batch_key -The -.B batch_key -keyword argument can be used -to specify that the Action can create multiple target files -by processing multiple independent source files simultaneously. -(The canonical example is "batch compilation" -of multiple object files -by passing multiple source files -to a single invocation of a compiler -such as Microsoft's Visual C / C++ compiler.) -If the -.B batch_key -argument is any non-False, non-callable Python value, -the configured Action object will cause -.B scons -to collect all targets built with the Action object -and configured with the same construction environment -into single invocations of the Action object's -command line or function. -Command lines will typically want to use the -.BR CHANGED_SOURCES -construction variable -(and possibly -.BR CHANGED_TARGETS -as well) -to only pass to the command line those sources that -have actually changed since their targets were built. - -Example: - -.ES -a = Action('build $CHANGED_SOURCES', batch_key=True) -.EE - -The -.B batch_key -argument may also be -a callable function -that returns a key that -will be used to identify different -"batches" of target files to be collected -for batch building. -A -.B batch_key -function must take the following arguments: - -.IP action -The action object. - -.IP env -The construction environment -configured for the target. - -.IP target -The list of targets for a particular configured action. - -.IP source -The list of source for a particular configured action. - -The returned key should typically -be a tuple of values derived from the arguments, -using any appropriate logic to decide -how multiple invocations should be batched. -For example, a -.B batch_key -function may decide to return -the value of a specific construction -variable from the -.B env -argument -which will cause -.B scons -to batch-build targets -with matching values of that variable, -or perhaps return the -.BR id () -of the entire construction environment, -in which case -.B scons -will batch-build -all targets configured with the same construction environment. -Returning -.B None -indicates that -the particular target should -.I not -be part of any batched build, -but instead will be built -by a separate invocation of action's -command or function. -Example: - -.ES -def batch_key(action, env, target, source): - tdir = target[0].dir - if tdir.name == 'special': - # Don't batch-build any target - # in the special/ subdirectory. - return None - return (id(action), id(env), tdir) -a = Action('build $CHANGED_SOURCES', batch_key=batch_key) -.EE - -.SS Miscellaneous Action Functions - -.B scons -supplies a number of functions -that arrange for various common -file and directory manipulations -to be performed. -These are similar in concept to "tasks" in the -Ant build tool, -although the implementation is slightly different. -These functions do not actually -perform the specified action -at the time the function is called, -but instead return an Action object -that can be executed at the -appropriate time. -(In Object-Oriented terminology, -these are actually -Action -.I Factory -functions -that return Action objects.) - -In practice, -there are two natural ways -that these -Action Functions -are intended to be used. - -First, -if you need -to perform the action -at the time the SConscript -file is being read, -you can use the -.B Execute -global function to do so: -.ES -Execute(Touch('file')) -.EE - -Second, -you can use these functions -to supply Actions in a list -for use by the -.B Command -method. -This can allow you to -perform more complicated -sequences of file manipulation -without relying -on platform-specific -external commands: -that -.ES -env = Environment(TMPBUILD = '/tmp/builddir') -env.Command('foo.out', 'foo.in', - [Mkdir('$TMPBUILD'), - Copy('$TMPBUILD', '${SOURCE.dir}'), - "cd $TMPBUILD && make", - Delete('$TMPBUILD')]) -.EE - -.TP -.RI Chmod( dest ", " mode ) -Returns an Action object that -changes the permissions on the specified -.I dest -file or directory to the specified -.IR mode . -Examples: - -.ES -Execute(Chmod('file', 0755)) - -env.Command('foo.out', 'foo.in', - [Copy('$TARGET', '$SOURCE'), - Chmod('$TARGET', 0755)]) -.EE - -.TP -.RI Copy( dest ", " src ) -Returns an Action object -that will copy the -.I src -source file or directory to the -.I dest -destination file or directory. -Examples: - -.ES -Execute(Copy('foo.output', 'foo.input')) - -env.Command('bar.out', 'bar.in', - Copy('$TARGET', '$SOURCE')) -.EE - -.TP -.RI Delete( entry ", [" must_exist ]) -Returns an Action that -deletes the specified -.IR entry , -which may be a file or a directory tree. -If a directory is specified, -the entire directory tree -will be removed. -If the -.I must_exist -flag is set, -then a Python error will be thrown -if the specified entry does not exist; -the default is -.BR must_exist=0 , -that is, the Action will silently do nothing -if the entry does not exist. -Examples: - -.ES -Execute(Delete('/tmp/buildroot')) - -env.Command('foo.out', 'foo.in', - [Delete('${TARGET.dir}'), - MyBuildAction]) - -Execute(Delete('file_that_must_exist', must_exist=1)) -.EE - -.TP -.RI Mkdir( dir ) -Returns an Action -that creates the specified -directory -.I dir . -Examples: - -.ES -Execute(Mkdir('/tmp/outputdir')) - -env.Command('foo.out', 'foo.in', - [Mkdir('/tmp/builddir'), - Copy('/tmp/builddir/foo.in', '$SOURCE'), - "cd /tmp/builddir && make", - Copy('$TARGET', '/tmp/builddir/foo.out')]) -.EE - -.TP -.RI Move( dest ", " src ) -Returns an Action -that moves the specified -.I src -file or directory to -the specified -.I dest -file or directory. -Examples: - -.ES -Execute(Move('file.destination', 'file.source')) - -env.Command('output_file', 'input_file', - [MyBuildAction, - Move('$TARGET', 'file_created_by_MyBuildAction')]) -.EE - -.TP -.RI Touch( file ) -Returns an Action -that updates the modification time -on the specified -.IR file . -Examples: - -.ES -Execute(Touch('file_to_be_touched')) - -env.Command('marker', 'input_file', - [MyBuildAction, - Touch('$TARGET')]) -.EE - -.SS Variable Substitution - -Before executing a command, -.B scons -performs construction variable interpolation on the strings that make up -the command line of builders. -Variables are introduced by a -.B $ -prefix. -Besides construction variables, scons provides the following -variables for each command execution: - -.IP CHANGED_SOURCES -The file names of all sources of the build command -that have changed since the target was last built. - -.IP CHANGED_TARGETS -The file names of all targets that would be built -from sources that have changed since the target was last built. - -.IP SOURCE -The file name of the source of the build command, -or the file name of the first source -if multiple sources are being built. - -.IP SOURCES -The file names of the sources of the build command. - -.IP TARGET -The file name of the target being built, -or the file name of the first target -if multiple targets are being built. - -.IP TARGETS -The file names of all targets being built. - -.IP UNCHANGED_SOURCES -The file names of all sources of the build command -that have -.I not -changed since the target was last built. - -.IP UNCHANGED_TARGETS -The file names of all targets that would be built -from sources that have -.I not -changed since the target was last built. - -(Note that the above variables are reserved -and may not be set in a construction environment.) - -.LP -For example, given the construction variable CC='cc', targets=['foo'], and -sources=['foo.c', 'bar.c']: - -.ES -action='$CC -c -o $TARGET $SOURCES' -.EE - -would produce the command line: - -.ES -cc -c -o foo foo.c bar.c -.EE - -Variable names may be surrounded by curly braces ({}) -to separate the name from the trailing characters. -Within the curly braces, a variable name may have -a Python slice subscript appended to select one -or more items from a list. -In the previous example, the string: - -.ES -${SOURCES[1]} -.EE - -would produce: - -.ES -bar.c -.EE - -Additionally, a variable name may -have the following special -modifiers appended within the enclosing curly braces -to modify the interpolated string: - -.IP base -The base path of the file name, -including the directory path -but excluding any suffix. - -.IP dir -The name of the directory in which the file exists. - -.IP file -The file name, -minus any directory portion. - -.IP filebase -Just the basename of the file, -minus any suffix -and minus the directory. - -.IP suffix -Just the file suffix. - -.IP abspath -The absolute path name of the file. - -.IP posix -The POSIX form of the path, -with directories separated by -.B / -(forward slashes) -not backslashes. -This is sometimes necessary on Windows systems -when a path references a file on other (POSIX) systems. - -.IP srcpath -The directory and file name to the source file linked to this file through -.BR VariantDir (). -If this file isn't linked, -it just returns the directory and filename unchanged. - -.IP srcdir -The directory containing the source file linked to this file through -.BR VariantDir (). -If this file isn't linked, -it just returns the directory part of the filename. - -.IP rsrcpath -The directory and file name to the source file linked to this file through -.BR VariantDir (). -If the file does not exist locally but exists in a Repository, -the path in the Repository is returned. -If this file isn't linked, it just returns the -directory and filename unchanged. - -.IP rsrcdir -The Repository directory containing the source file linked to this file through -.BR VariantDir (). -If this file isn't linked, -it just returns the directory part of the filename. - -.LP -For example, the specified target will -expand as follows for the corresponding modifiers: - -.ES -$TARGET => sub/dir/file.x -${TARGET.base} => sub/dir/file -${TARGET.dir} => sub/dir -${TARGET.file} => file.x -${TARGET.filebase} => file -${TARGET.suffix} => .x -${TARGET.abspath} => /top/dir/sub/dir/file.x - -SConscript('src/SConscript', variant_dir='sub/dir') -$SOURCE => sub/dir/file.x -${SOURCE.srcpath} => src/file.x -${SOURCE.srcdir} => src - -Repository('/usr/repository') -$SOURCE => sub/dir/file.x -${SOURCE.rsrcpath} => /usr/repository/src/file.x -${SOURCE.rsrcdir} => /usr/repository/src -.EE - -Note that curly braces braces may also be used -to enclose arbitrary Python code to be evaluated. -(In fact, this is how the above modifiers are substituted, -they are simply attributes of the Python objects -that represent TARGET, SOURCES, etc.) -See the section "Python Code Substitution" below, -for more thorough examples of -how this can be used. - -Lastly, a variable name -may be a callable Python function -associated with a -construction variable in the environment. -The function should -take four arguments: -.I target -- a list of target nodes, -.I source -- a list of source nodes, -.I env -- the construction environment, -.I for_signature -- a Boolean value that specifies -whether the function is being called -for generating a build signature. -SCons will insert whatever -the called function returns -into the expanded string: - -.ES -def foo(target, source, env, for_signature): - return "bar" - -# Will expand $BAR to "bar baz" -env=Environment(FOO=foo, BAR="$FOO baz") -.EE - -You can use this feature to pass arguments to a -Python function by creating a callable class -that stores one or more arguments in an object, -and then uses them when the -.B __call__() -method is called. -Note that in this case, -the entire variable expansion must -be enclosed by curly braces -so that the arguments will -be associated with the -instantiation of the class: - -.ES -class foo(object): - def __init__(self, arg): - self.arg = arg - - def __call__(self, target, source, env, for_signature): - return self.arg + " bar" - -# Will expand $BAR to "my argument bar baz" -env=Environment(FOO=foo, BAR="${FOO('my argument')} baz") -.EE - -.LP -The special pseudo-variables -.B "$(" -and -.B "$)" -may be used to surround parts of a command line -that may change -.I without -causing a rebuild--that is, -which are not included in the signature -of target files built with this command. -All text between -.B "$(" -and -.B "$)" -will be removed from the command line -before it is added to file signatures, -and the -.B "$(" -and -.B "$)" -will be removed before the command is executed. -For example, the command line: - -.ES -echo Last build occurred $( $TODAY $). > $TARGET -.EE - -.LP -would execute the command: - -.ES -echo Last build occurred $TODAY. > $TARGET -.EE - -.LP -but the command signature added to any target files would be: - -.ES -echo Last build occurred . > $TARGET -.EE - -.SS Python Code Substitution - -Any python code within -.BR "${" - "}" -pairs gets evaluated by python 'eval', with the python globals set to -the current environment's set of construction variables. -So in the following case: -.ES -env['COND'] = 0 -env.Command('foo.out', 'foo.in', - '''echo ${COND==1 and 'FOO' or 'BAR'} > $TARGET''') -.EE -the command executed will be either -.ES -echo FOO > foo.out -.EE -or -.ES -echo BAR > foo.out -.EE -according to the current value of env['COND'] when the command is -executed. The evaluation occurs when the target is being -built, not when the SConscript is being read. So if env['COND'] is changed -later in the SConscript, the final value will be used. - -Here's a more interesting example. Note that all of COND, FOO, and -BAR are environment variables, and their values are substituted into -the final command. FOO is a list, so its elements are interpolated -separated by spaces. - -.ES -env=Environment() -env['COND'] = 0 -env['FOO'] = ['foo1', 'foo2'] -env['BAR'] = 'barbar' -env.Command('foo.out', 'foo.in', - 'echo ${COND==1 and FOO or BAR} > $TARGET') - -# Will execute this: -# echo foo1 foo2 > foo.out -.EE - -SCons uses the following rules when converting construction variables into -command lines: - -.IP String -When the value is a string it is interpreted as a space delimited list of -command line arguments. - -.IP List -When the value is a list it is interpreted as a list of command line -arguments. Each element of the list is converted to a string. - -.IP Other -Anything that is not a list or string is converted to a string and -interpreted as a single command line argument. - -.IP Newline -Newline characters (\\n) delimit lines. The newline parsing is done after -all other parsing, so it is not possible for arguments (e.g. file names) to -contain embedded newline characters. This limitation will likely go away in -a future version of SCons. - -.SS Scanner Objects - -You can use the -.B Scanner -function to define -objects to scan -new file types for implicit dependencies. -The -.B Scanner -function accepts the following arguments: - -.IP function -This can be either: -1) a Python function that will process -the Node (file) -and return a list of File Nodes -representing the implicit -dependencies (file names) found in the contents; -or: -2) a dictionary that maps keys -(typically the file suffix, but see below for more discussion) -to other Scanners that should be called. - -If the argument is actually a Python function, -the function must take three or four arguments: - - def scanner_function(node, env, path): - - def scanner_function(node, env, path, arg=None): - -The -.B node -argument is the internal -SCons node representing the file. -Use -.B str(node) -to fetch the name of the file, and -.B node.get_contents() -to fetch contents of the file. -Note that the file is -.I not -guaranteed to exist before the scanner is called, -so the scanner function should check that -if there's any chance that the scanned file -might not exist -(for example, if it's built from other files). - -The -.B env -argument is the construction environment for the scan. -Fetch values from it using the -.B env.Dictionary() -method. - -The -.B path -argument is a tuple (or list) -of directories that can be searched -for files. -This will usually be the tuple returned by the -.B path_function -argument (see below). - -The -.B arg -argument is the argument supplied -when the scanner was created, if any. - -.IP name -The name of the Scanner. -This is mainly used -to identify the Scanner internally. - -.IP argument -An optional argument that, if specified, -will be passed to the scanner function -(described above) -and the path function -(specified below). - -.IP skeys -An optional list that can be used to -determine which scanner should be used for -a given Node. -In the usual case of scanning for file names, -this argument will be a list of suffixes -for the different file types that this -Scanner knows how to scan. -If the argument is a string, -then it will be expanded -into a list by the current environment. - -.IP path_function -A Python function that takes four or five arguments: -a construction environment, -a Node for the directory containing -the SConscript file in which -the first target was defined, -a list of target nodes, -a list of source nodes, -and an optional argument supplied -when the scanner was created. -The -.B path_function -returns a tuple of directories -that can be searched for files to be returned -by this Scanner object. -(Note that the -.BR FindPathDirs () -function can be used to return a ready-made -.B path_function -for a given construction variable name, -instead of having to write your own function from scratch.) - -.IP node_class -The class of Node that should be returned -by this Scanner object. -Any strings or other objects returned -by the scanner function -that are not of this class -will be run through the -.B node_factory -function. - -.IP node_factory -A Python function that will take a string -or other object -and turn it into the appropriate class of Node -to be returned by this Scanner object. - -.IP scan_check -An optional Python function that takes two arguments, -a Node (file) and a construction environment, -and returns whether the -Node should, in fact, -be scanned for dependencies. -This check can be used to eliminate unnecessary -calls to the scanner function when, -for example, the underlying file -represented by a Node does not yet exist. - -.IP recursive -An optional flag that -specifies whether this scanner should be re-invoked -on the dependency files returned by the scanner. -When this flag is not set, -the Node subsystem will -only invoke the scanner on the file being scanned, -and not (for example) also on the files -specified by the #include lines -in the file being scanned. -.I recursive -may be a callable function, -in which case it will be called with a list of -Nodes found and -should return a list of Nodes -that should be scanned recursively; -this can be used to select a specific subset of -Nodes for additional scanning. - -.RE -Note that -.B scons -has a global -.B SourceFileScanner -object that is used by -the -.BR Object (), -.BR SharedObject (), -and -.BR StaticObject () -builders to decide -which scanner should be used -for different file extensions. -You can using the -.BR SourceFileScanner.add_scanner () -method to add your own Scanner object -to the -.B scons -infrastructure -that builds target programs or -libraries from a list of -source files of different types: - -.ES -def xyz_scan(node, env, path): - contents = node.get_text_contents() - # Scan the contents and return the included files. - -XYZScanner = Scanner(xyz_scan) - -SourceFileScanner.add_scanner('.xyz', XYZScanner) - -env.Program('my_prog', ['file1.c', 'file2.f', 'file3.xyz']) -.EE - -.SH SYSTEM-SPECIFIC BEHAVIOR -SCons and its configuration files are very portable, -due largely to its implementation in Python. -There are, however, a few portability -issues waiting to trap the unwary. -.SS .C file suffix -SCons handles the upper-case -.B .C -file suffix differently, -depending on the capabilities of -the underlying system. -On a case-sensitive system -such as Linux or UNIX, -SCons treats a file with a -.B .C -suffix as a C++ source file. -On a case-insensitive system -such as Windows, -SCons treats a file with a -.B .C -suffix as a C source file. -.SS .F file suffix -SCons handles the upper-case -.B .F -file suffix differently, -depending on the capabilities of -the underlying system. -On a case-sensitive system -such as Linux or UNIX, -SCons treats a file with a -.B .F -suffix as a Fortran source file -that is to be first run through -the standard C preprocessor. -On a case-insensitive system -such as Windows, -SCons treats a file with a -.B .F -suffix as a Fortran source file that should -.I not -be run through the C preprocessor. -.SS Windows: Cygwin Tools and Cygwin Python vs. Windows Pythons -Cygwin supplies a set of tools and utilities -that let users work on a -Windows system using a more POSIX-like environment. -The Cygwin tools, including Cygwin Python, -do this, in part, -by sharing an ability to interpret UNIX-like path names. -For example, the Cygwin tools -will internally translate a Cygwin path name -like /cygdrive/c/mydir -to an equivalent Windows pathname -of C:/mydir (equivalent to C:\\mydir). - -Versions of Python -that are built for native Windows execution, -such as the python.org and ActiveState versions, -do not have the Cygwin path name semantics. -This means that using a native Windows version of Python -to build compiled programs using Cygwin tools -(such as gcc, bison, and flex) -may yield unpredictable results. -"Mixing and matching" in this way -can be made to work, -but it requires careful attention to the use of path names -in your SConscript files. - -In practice, users can sidestep -the issue by adopting the following rules: -When using gcc, -use the Cygwin-supplied Python interpreter -to run SCons; -when using Microsoft Visual C/C++ -(or some other Windows compiler) -use the python.org or ActiveState version of Python -to run SCons. -.SS Windows: scons.bat file -On Windows systems, -SCons is executed via a wrapper -.B scons.bat -file. -This has (at least) two ramifications: - -First, Windows command-line users -that want to use variable assignment -on the command line -may have to put double quotes -around the assignments: - -.ES -scons "FOO=BAR" "BAZ=BLEH" -.EE - -Second, the Cygwin shell does not -recognize this file as being the same -as an -.B scons -command issued at the command-line prompt. -You can work around this either by -executing -.B scons.bat -from the Cygwin command line, -or by creating a wrapper shell -script named -.B scons . - -.SS MinGW - -The MinGW bin directory must be in your PATH environment variable or the -PATH variable under the ENV construction variable for SCons -to detect and use the MinGW tools. When running under the native Windows -Python interpreter, SCons will prefer the MinGW tools over the Cygwin -tools, if they are both installed, regardless of the order of the bin -directories in the PATH variable. If you have both MSVC and MinGW -installed and you want to use MinGW instead of MSVC, -then you must explictly tell SCons to use MinGW by passing - -.ES -tools=['mingw'] -.EE - -to the Environment() function, because SCons will prefer the MSVC tools -over the MinGW tools. - -.SH EXAMPLES - -To help you get started using SCons, -this section contains a brief overview of some common tasks. - -.SS Basic Compilation From a Single Source File - -.ES -env = Environment() -env.Program(target = 'foo', source = 'foo.c') -.EE - -Note: Build the file by specifying -the target as an argument -("scons foo" or "scons foo.exe"). -or by specifying a dot ("scons ."). - -.SS Basic Compilation From Multiple Source Files - -.ES -env = Environment() -env.Program(target = 'foo', source = Split('f1.c f2.c f3.c')) -.EE - -.SS Setting a Compilation Flag - -.ES -env = Environment(CCFLAGS = '-g') -env.Program(target = 'foo', source = 'foo.c') -.EE - -.SS Search The Local Directory For .h Files - -Note: You do -.I not -need to set CCFLAGS to specify -I options by hand. -SCons will construct the right -I options from CPPPATH. - -.ES -env = Environment(CPPPATH = ['.']) -env.Program(target = 'foo', source = 'foo.c') -.EE - -.SS Search Multiple Directories For .h Files - -.ES -env = Environment(CPPPATH = ['include1', 'include2']) -env.Program(target = 'foo', source = 'foo.c') -.EE - -.SS Building a Static Library - -.ES -env = Environment() -env.StaticLibrary(target = 'foo', source = Split('l1.c l2.c')) -env.StaticLibrary(target = 'bar', source = ['l3.c', 'l4.c']) -.EE - -.SS Building a Shared Library - -.ES -env = Environment() -env.SharedLibrary(target = 'foo', source = ['l5.c', 'l6.c']) -env.SharedLibrary(target = 'bar', source = Split('l7.c l8.c')) -.EE - -.SS Linking a Local Library Into a Program - -.ES -env = Environment(LIBS = 'mylib', LIBPATH = ['.']) -env.Library(target = 'mylib', source = Split('l1.c l2.c')) -env.Program(target = 'prog', source = ['p1.c', 'p2.c']) -.EE - -.SS Defining Your Own Builder Object - -Notice that when you invoke the Builder, -you can leave off the target file suffix, -and SCons will add it automatically. - -.ES -bld = Builder(action = 'pdftex < $SOURCES > $TARGET' - suffix = '.pdf', - src_suffix = '.tex') -env = Environment(BUILDERS = {'PDFBuilder' : bld}) -env.PDFBuilder(target = 'foo.pdf', source = 'foo.tex') - -# The following creates "bar.pdf" from "bar.tex" -env.PDFBuilder(target = 'bar', source = 'bar') -.EE - -Note also that the above initialization -overwrites the default Builder objects, -so the Environment created above -can not be used call Builders like env.Program(), -env.Object(), env.StaticLibrary(), etc. - -.SS Adding Your Own Builder Object to an Environment - -.ES -bld = Builder(action = 'pdftex < $SOURCES > $TARGET' - suffix = '.pdf', - src_suffix = '.tex') -env = Environment() -env.Append(BUILDERS = {'PDFBuilder' : bld}) -env.PDFBuilder(target = 'foo.pdf', source = 'foo.tex') -env.Program(target = 'bar', source = 'bar.c') -.EE - -You also can use other Pythonic techniques to add -to the BUILDERS construction variable, such as: - -.ES -env = Environment() -env['BUILDERS]['PDFBuilder'] = bld -.EE - -.SS Defining Your Own Scanner Object - -The following example shows an extremely simple scanner (the -.BR kfile_scan () -function) -that doesn't use a search path at all -and simply returns the -file names present on any -.B include -lines in the scanned file. -This would implicitly assume that all included -files live in the top-level directory: - -.ES -import re - -'\" Note: the \\ in the following are for the benefit of nroff/troff, -'\" not inappropriate doubled escape characters within the r'' raw string. -include_re = re.compile(r'^include\\s+(\\S+)$', re.M) - -def kfile_scan(node, env, path, arg): - contents = node.get_text_contents() - includes = include_re.findall(contents) - return env.File(includes) - -kscan = Scanner(name = 'kfile', - function = kfile_scan, - argument = None, - skeys = ['.k']) -scanners = Environment().Dictionary('SCANNERS') -env = Environment(SCANNERS = scanners + [kscan]) - -env.Command('foo', 'foo.k', 'kprocess < $SOURCES > $TARGET') - -bar_in = File('bar.in') -env.Command('bar', bar_in, 'kprocess $SOURCES > $TARGET') -bar_in.target_scanner = kscan -.EE - -It is important to note that you -have to return a list of File nodes from the scan function, simple -strings for the file names won't do. As in the examples we are showing here, -you can use the -.BR File() -function of your current Environment in order to create nodes on the fly from -a sequence of file names with relative paths. - -Here is a similar but more complete example that searches -a path of directories -(specified as the -.B MYPATH -construction variable) -for files that actually exist: - -.ES -import re -import os -include_re = re.compile(r'^include\\s+(\\S+)$', re.M) - -def my_scan(node, env, path, arg): - contents = node.get_text_contents() - includes = include_re.findall(contents) - if includes == []: - return [] - results = [] - for inc in includes: - for dir in path: - file = str(dir) + os.sep + inc - if os.path.exists(file): - results.append(file) - break - return env.File(results) - -scanner = Scanner(name = 'myscanner', - function = my_scan, - argument = None, - skeys = ['.x'], - path_function = FindPathDirs('MYPATH') - ) -scanners = Environment().Dictionary('SCANNERS') -env = Environment(SCANNERS = scanners + [scanner], - MYPATH = ['incs']) - -env.Command('foo', 'foo.x', 'xprocess < $SOURCES > $TARGET') -.EE - -The -.BR FindPathDirs () -function used in the previous example returns a function -(actually a callable Python object) -that will return a list of directories -specified in the -.B $MYPATH -construction variable. It lets SCons detect the file -.B incs/foo.inc -, even if -.B foo.x -contains the line -.B include foo.inc -only. -If you need to customize how the search path is derived, -you would provide your own -.B path_function -argument when creating the Scanner object, -as follows: - -.ES -# MYPATH is a list of directories to search for files in -def pf(env, dir, target, source, arg): - top_dir = Dir('#').abspath - results = [] - if 'MYPATH' in env: - for p in env['MYPATH']: - results.append(top_dir + os.sep + p) - return results - -scanner = Scanner(name = 'myscanner', - function = my_scan, - argument = None, - skeys = ['.x'], - path_function = pf - ) -.EE - -.SS Creating a Hierarchical Build - -Notice that the file names specified in a subdirectory's -SConscript -file are relative to that subdirectory. - -.ES -SConstruct: - - env = Environment() - env.Program(target = 'foo', source = 'foo.c') - - SConscript('sub/SConscript') - -sub/SConscript: - - env = Environment() - # Builds sub/foo from sub/foo.c - env.Program(target = 'foo', source = 'foo.c') - - SConscript('dir/SConscript') - -sub/dir/SConscript: - - env = Environment() - # Builds sub/dir/foo from sub/dir/foo.c - env.Program(target = 'foo', source = 'foo.c') -.EE - -.SS Sharing Variables Between SConscript Files - -You must explicitly Export() and Import() variables that -you want to share between SConscript files. - -.ES -SConstruct: - - env = Environment() - env.Program(target = 'foo', source = 'foo.c') - - Export("env") - SConscript('subdirectory/SConscript') - -subdirectory/SConscript: - - Import("env") - env.Program(target = 'foo', source = 'foo.c') -.EE - -.SS Building Multiple Variants From the Same Source - -Use the variant_dir keyword argument to -the SConscript function to establish -one or more separate variant build directory trees -for a given source directory: - -.ES -SConstruct: - - cppdefines = ['FOO'] - Export("cppdefines") - SConscript('src/SConscript', variant_dir='foo') - - cppdefines = ['BAR'] - Export("cppdefines") - SConscript('src/SConscript', variant_dir='bar') - -src/SConscript: - - Import("cppdefines") - env = Environment(CPPDEFINES = cppdefines) - env.Program(target = 'src', source = 'src.c') -.EE - -Note the use of the Export() method -to set the "cppdefines" variable to a different -value each time we call the SConscript function. - -.SS Hierarchical Build of Two Libraries Linked With a Program - -.ES -SConstruct: - - env = Environment(LIBPATH = ['#libA', '#libB']) - Export('env') - SConscript('libA/SConscript') - SConscript('libB/SConscript') - SConscript('Main/SConscript') - -libA/SConscript: - - Import('env') - env.Library('a', Split('a1.c a2.c a3.c')) - -libB/SConscript: - - Import('env') - env.Library('b', Split('b1.c b2.c b3.c')) - -Main/SConscript: - - Import('env') - e = env.Copy(LIBS = ['a', 'b']) - e.Program('foo', Split('m1.c m2.c m3.c')) -.EE - -The '#' in the LIBPATH directories specify that they're relative to the -top-level directory, so they don't turn into "Main/libA" when they're -used in Main/SConscript. - -Specifying only 'a' and 'b' for the library names -allows SCons to append the appropriate library -prefix and suffix for the current platform -(for example, 'liba.a' on POSIX systems, -\&'a.lib' on Windows). - -.SS Customizing construction variables from the command line. - -The following would allow the C compiler to be specified on the command -line or in the file custom.py. - -.ES -vars = Variables('custom.py') -vars.Add('CC', 'The C compiler.') -env = Environment(variables=vars) -Help(vars.GenerateHelpText(env)) -.EE - -The user could specify the C compiler on the command line: - -.ES -scons "CC=my_cc" -.EE - -or in the custom.py file: - -.ES -CC = 'my_cc' -.EE - -or get documentation on the options: - -.ES -$ scons -h - -CC: The C compiler. - default: None - actual: cc - -.EE - -.SS Using Microsoft Visual C++ precompiled headers - -Since windows.h includes everything and the kitchen sink, it can take quite -some time to compile it over and over again for a bunch of object files, so -Microsoft provides a mechanism to compile a set of headers once and then -include the previously compiled headers in any object file. This -technology is called precompiled headers. The general recipe is to create a -file named "StdAfx.cpp" that includes a single header named "StdAfx.h", and -then include every header you want to precompile in "StdAfx.h", and finally -include "StdAfx.h" as the first header in all the source files you are -compiling to object files. For example: - -StdAfx.h: -.ES -#include <windows.h> -#include <my_big_header.h> -.EE - -StdAfx.cpp: -.ES -#include <StdAfx.h> -.EE - -Foo.cpp: -.ES -#include <StdAfx.h> - -/* do some stuff */ -.EE - -Bar.cpp: -.ES -#include <StdAfx.h> - -/* do some other stuff */ -.EE - -SConstruct: -.ES -env=Environment() -env['PCHSTOP'] = 'StdAfx.h' -env['PCH'] = env.PCH('StdAfx.cpp')[0] -env.Program('MyApp', ['Foo.cpp', 'Bar.cpp']) -.EE - -For more information see the document for the PCH builder, and the PCH and -PCHSTOP construction variables. To learn about the details of precompiled -headers consult the MSDN documention for /Yc, /Yu, and /Yp. - -.SS Using Microsoft Visual C++ external debugging information - -Since including debugging information in programs and shared libraries can -cause their size to increase significantly, Microsoft provides a mechanism -for including the debugging information in an external file called a PDB -file. SCons supports PDB files through the PDB construction -variable. - -SConstruct: -.ES -env=Environment() -env['PDB'] = 'MyApp.pdb' -env.Program('MyApp', ['Foo.cpp', 'Bar.cpp']) -.EE - -For more information see the document for the PDB construction variable. - -.SH ENVIRONMENT - -.IP SCONS_LIB_DIR -Specifies the directory that contains the SCons Python module directory -(e.g. /home/aroach/scons-src-0.01/src/engine). - -.IP SCONSFLAGS -A string of options that will be used by scons in addition to those passed -on the command line. - -.SH "SEE ALSO" -.B scons -User Manual, -.B scons -Design Document, -.B scons -source code. - -.SH AUTHORS -Steven Knight <knight@baldmt.com> -.br -Anthony Roach <aroach@electriceyeball.com> - |