Index: scons-2.0.1/scons.1 |
=================================================================== |
--- scons-2.0.1/scons.1 (revision 0) |
+++ scons-2.0.1/scons.1 (revision 0) |
@@ -0,0 +1,15219 @@ |
+.\" Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 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 5134 2010/08/16 23:02:40 bdeegan |
+.\" |
+.TH SCONS 1 "August 2010" |
+.\" 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 the directory containing the |
+.I SConstruct |
+file; if it exists, |
+.I site_scons |
+is added to sys.path, |
+the file |
+.IR site_scons/site_init.py , |
+is evaluated if it exists, |
+and the directory |
+.I site_scons/site_tools |
+is added to the default toolpath if it exist. |
+See the |
+.I --no-site-dir |
+and |
+.I --site-dir |
+options for more details. |
+ |
+.B scons |
+reads and executes the SConscript files as Python scripts, |
+so you may use normal Python scripting capabilities |
+(such as flow control, data manipulation, and imported Python libraries) |
+to handle complicated build situations. |
+.BR scons , |
+however, reads and executes all of the SConscript files |
+.I before |
+it begins building any targets. |
+To make this obvious, |
+.B scons |
+prints the following messages about what it is doing: |
+ |
+.ES |
+$ scons foo.out |
+scons: Reading SConscript files ... |
+scons: done reading SConscript files. |
+scons: Building targets ... |
+cp foo.in foo.out |
+scons: done building targets. |
+$ |
+.EE |
+ |
+The status messages |
+(everything except the line that reads "cp foo.in foo.out") |
+may be suppressed using the |
+.B -Q |
+option. |
+ |
+.B scons |
+does not automatically propagate |
+the external environment used to execute |
+.B scons |
+to the commands used to build target files. |
+This is so that builds will be guaranteed |
+repeatable regardless of the environment |
+variables set at the time |
+.B scons |
+is invoked. |
+This also means that if the compiler or other commands |
+that you want to use to build your target files |
+are not in standard system locations, |
+.B scons |
+will not find them unless |
+you explicitly set the PATH |
+to include those locations. |
+Whenever you create an |
+.B scons |
+construction environment, |
+you can propagate the value of PATH |
+from your external environment as follows: |
+ |
+.ES |
+import os |
+env = Environment(ENV = {'PATH' : os.environ['PATH']}) |
+.EE |
+ |
+Similarly, if the commands use external environment variables |
+like $PATH, $HOME, $JAVA_HOME, $LANG, $SHELL, $TERM, etc., |
+these variables can also be explicitly propagated: |
+ |
+.ES |
+import os |
+env = Environment(ENV = {'PATH' : os.environ['PATH'], |
+ 'HOME' : os.environ['HOME']}) |
+.EE |
+ |
+Or you may explicitly propagate the invoking user's |
+complete external environment: |
+ |
+.ES |
+import os |
+env = Environment(ENV = os.environ) |
+.EE |
+ |
+This comes at the expense of making your build |
+dependent on the user's environment being set correctly, |
+but it may be more convenient for many configurations. |
+ |
+.B scons |
+can scan known input files automatically for dependency |
+information (for example, #include statements |
+in C or C++ files) and will rebuild dependent files appropriately |
+whenever any "included" input file changes. |
+.B scons |
+supports the |
+ability to define new scanners for unknown input file types. |
+ |
+.B scons |
+knows how to fetch files automatically from |
+SCCS or RCS subdirectories |
+using SCCS, RCS or BitKeeper. |
+ |
+.B scons |
+is normally executed in a top-level directory containing a |
+.I SConstruct |
+file, optionally specifying |
+as command-line arguments |
+the target file or files to be built. |
+ |
+By default, the command |
+ |
+.ES |
+scons |
+.EE |
+ |
+will build all target files in or below the current directory. |
+Explicit default targets |
+(to be built when no targets are specified on the command line) |
+may be defined the SConscript file(s) |
+using the |
+.B Default() |
+function, described below. |
+ |
+Even when |
+.B Default() |
+targets are specified in the SConscript file(s), |
+all target files in or below the current directory |
+may be built by explicitly specifying |
+the current directory (.) |
+as a command-line target: |
+ |
+.ES |
+scons . |
+.EE |
+ |
+Building all target files, |
+including any files outside of the current directory, |
+may be specified by supplying a command-line target |
+of the root directory (on POSIX systems): |
+ |
+.ES |
+scons / |
+.EE |
+ |
+or the path name(s) of the volume(s) in which all the targets |
+should be built (on Windows systems): |
+ |
+.ES |
+scons C:\\ D:\\ |
+.EE |
+ |
+To build only specific targets, |
+supply them as command-line arguments: |
+ |
+.ES |
+scons foo bar |
+.EE |
+ |
+in which case only the specified targets will be built |
+(along with any derived files on which they depend). |
+ |
+Specifying "cleanup" targets in SConscript files is not usually necessary. |
+The |
+.B -c |
+flag removes all files |
+necessary to build the specified target: |
+ |
+.ES |
+scons -c . |
+.EE |
+ |
+to remove all target files, or: |
+ |
+.ES |
+scons -c build export |
+.EE |
+ |
+to remove target files under build and export. |
+Additional files or directories to remove can be specified using the |
+.BR Clean() |
+function. |
+Conversely, targets that would normally be removed by the |
+.B -c |
+invocation |
+can be prevented from being removed by using the |
+.BR NoClean () |
+function. |
+ |
+A subset of a hierarchical tree may be built by |
+remaining at the top-level directory (where the |
+.I SConstruct |
+file lives) and specifying the subdirectory as the target to be |
+built: |
+ |
+.ES |
+scons src/subdir |
+.EE |
+ |
+or by changing directory and invoking scons with the |
+.B -u |
+option, which traverses up the directory |
+hierarchy until it finds the |
+.I SConstruct |
+file, and then builds |
+targets relatively to the current subdirectory: |
+ |
+.ES |
+cd src/subdir |
+scons -u . |
+.EE |
+ |
+.B scons |
+supports building multiple targets in parallel via a |
+.B -j |
+option that takes, as its argument, the number |
+of simultaneous tasks that may be spawned: |
+ |
+.ES |
+scons -j 4 |
+.EE |
+ |
+builds four targets in parallel, for example. |
+ |
+.B scons |
+can maintain a cache of target (derived) files that can |
+be shared between multiple builds. When caching is enabled in a |
+SConscript file, any target files built by |
+.B scons |
+will be copied |
+to the cache. If an up-to-date target file is found in the cache, it |
+will be retrieved from the cache instead of being rebuilt locally. |
+Caching behavior may be disabled and controlled in other ways by the |
+.BR --cache-force , |
+.BR --cache-disable , |
+and |
+.B --cache-show |
+command-line options. The |
+.B --random |
+option is useful to prevent multiple builds |
+from trying to update the cache simultaneously. |
+ |
+Values of variables to be passed to the SConscript file(s) |
+may be specified on the command line: |
+ |
+.ES |
+scons debug=1 . |
+.EE |
+ |
+These variables are available in SConscript files |
+through the ARGUMENTS dictionary, |
+and can be used in the SConscript file(s) to modify |
+the build in any way: |
+ |
+.ES |
+if ARGUMENTS.get('debug', 0): |
+ env = Environment(CCFLAGS = '-g') |
+else: |
+ env = Environment() |
+.EE |
+ |
+The command-line variable arguments are also available |
+in the ARGLIST list, |
+indexed by their order on the command line. |
+This allows you to process them in order rather than by name, |
+if necessary. |
+ARGLIST[0] returns a tuple |
+containing (argname, argvalue). |
+A Python exception is thrown if you |
+try to access a list member that |
+does not exist. |
+ |
+.B scons |
+requires Python version 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=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=presub |
+Print the raw command line used to build each target |
+before the construction environment variables are substituted. |
+Also shows which targets are being built by this command. |
+Output looks something like this: |
+.ES |
+$ scons --debug=presub |
+Building myprog.o with action(s): |
+ $SHCC $SHCFLAGS $SHCCFLAGS $CPPFLAGS $_CPPINCFLAGS -c -o $TARGET $SOURCES |
+\&... |
+.EE |
+ |
+.TP |
+--debug=stacktrace |
+Prints an internal Python stack trace |
+when encountering an otherwise unexplained error. |
+ |
+.TP |
+--debug=stree |
+A synonym for the newer |
+.B --tree=all,status |
+option. |
+This will be deprecated in some future release |
+and ultimately removed. |
+ |
+.TP |
+--debug=time |
+Prints various time profiling information: |
+the time spent executing each individual build command; |
+the total build time (time SCons ran from beginning to end); |
+the total time spent reading and executing SConscript files; |
+the total time spent SCons itself spend running |
+(that is, not counting reading and executing SConscript files); |
+and both the total time spent executing all build commands |
+and the elapsed wall-clock time spent executing those build commands. |
+(When |
+.B scons |
+is executed without the |
+.B -j |
+option, |
+the elapsed wall-clock time will typically |
+be slightly longer than the total time spent |
+executing all the build commands, |
+due to the SCons processing that takes place |
+in between executing each command. |
+When |
+.B scons |
+is executed |
+.I with |
+the |
+.B -j |
+option, |
+and your build configuration allows good parallelization, |
+the elapsed wall-clock time should |
+be significantly smaller than the |
+total time spent executing all the build commands, |
+since multiple build commands and |
+intervening SCons processing |
+should take place in parallel.) |
+ |
+.TP |
+--debug=tree |
+A synonym for the newer |
+.B --tree=all |
+option. |
+This will be deprecated in some future release |
+and ultimately removed. |
+ |
+.TP |
+.RI --diskcheck= types |
+Enable specific checks for |
+whether or not there is a file on disk |
+where the SCons configuration expects a directory |
+(or vice versa), |
+and whether or not RCS or SCCS sources exist |
+when searching for source and include files. |
+The |
+.I types |
+argument can be set to: |
+.BR all , |
+to enable all checks explicitly |
+(the default behavior); |
+.BR none , |
+to disable all such checks; |
+.BR match , |
+to check that files and directories on disk |
+match SCons' expected configuration; |
+.BR rcs , |
+to check for the existence of an RCS source |
+for any missing source or include files; |
+.BR sccs , |
+to check for the existence of an SCCS source |
+for any missing source or include files. |
+Multiple checks can be specified separated by commas; |
+for example, |
+.B --diskcheck=sccs,rcs |
+would still check for SCCS and RCS sources, |
+but disable the check for on-disk matches of files and directories. |
+Disabling some or all of these checks |
+can provide a performance boost for large configurations, |
+or when the configuration will check for files and/or directories |
+across networked or shared file systems, |
+at the slight increased risk of an incorrect build |
+or of not handling errors gracefully |
+(if include files really should be |
+found in SCCS or RCS, for example, |
+or if a file really does exist |
+where the SCons configuration expects a directory). |
+ |
+.TP |
+.RI --duplicate= ORDER |
+There are three ways to duplicate files in a build tree: hard links, |
+soft (symbolic) links and copies. The default behaviour of SCons is to |
+prefer hard links to soft links to copies. You can specify different |
+behaviours with this option. |
+.IR ORDER |
+must be one of |
+.IR hard-soft-copy |
+(the default), |
+.IR soft-hard-copy , |
+.IR hard-copy , |
+.IR soft-copy |
+or |
+.IR copy . |
+SCons will attempt to duplicate files using |
+the mechanisms in the specified order. |
+ |
+.\" .TP |
+.\" -e, --environment-overrides |
+.\" Variables from the execution environment override construction |
+.\" variables from the SConscript files. |
+ |
+.TP |
+.RI -f " file" ", --file=" file ", --makefile=" file ", --sconstruct=" file |
+Use |
+.I file |
+as the initial SConscript file. |
+Multiple |
+.B -f |
+options may be specified, |
+in which case |
+.B scons |
+will read all of the specified files. |
+ |
+.TP |
+-h, --help |
+Print a local help message for this build, if one is defined in |
+the SConscript file(s), plus a line that describes the |
+.B -H |
+option for command-line option help. If no local help message |
+is defined, prints the standard help message about command-line |
+options. Exits after displaying the appropriate message. |
+ |
+.TP |
+-H, --help-options |
+Print the standard help message about command-line options and |
+exit. |
+ |
+.TP |
+-i, --ignore-errors |
+Ignore all errors from commands executed to rebuild files. |
+ |
+.TP |
+.RI -I " directory" ", --include-dir=" directory |
+Specifies a |
+.I directory |
+to search for |
+imported Python modules. If several |
+.B -I |
+options |
+are used, the directories are searched in the order specified. |
+ |
+.TP |
+--implicit-cache |
+Cache implicit dependencies. |
+This causes |
+.B scons |
+to use the implicit (scanned) dependencies |
+from the last time it was run |
+instead of scanning the files for implicit dependencies. |
+This can significantly speed up SCons, |
+but with the following limitations: |
+.IP |
+.B scons |
+will not detect changes to implicit dependency search paths |
+(e.g. |
+.BR CPPPATH ", " LIBPATH ) |
+that would ordinarily |
+cause different versions of same-named files to be used. |
+.IP |
+.B scons |
+will miss changes in the implicit dependencies |
+in cases where a new implicit |
+dependency is added earlier in the implicit dependency search path |
+(e.g. |
+.BR CPPPATH ", " LIBPATH ) |
+than a current implicit dependency with the same name. |
+ |
+.TP |
+--implicit-deps-changed |
+Forces SCons to ignore the cached implicit dependencies. This causes the |
+implicit dependencies to be rescanned and recached. This implies |
+.BR --implicit-cache . |
+ |
+.TP |
+--implicit-deps-unchanged |
+Force SCons to ignore changes in the implicit dependencies. |
+This causes cached implicit dependencies to always be used. |
+This implies |
+.BR --implicit-cache . |
+ |
+.TP |
+--interactive |
+Starts SCons in interactive mode. |
+The SConscript files are read once and a |
+.B "scons>>>" |
+prompt is printed. |
+Targets may now be rebuilt by typing commands at interactive prompt |
+without having to re-read the SConscript files |
+and re-initialize the dependency graph from scratch. |
+ |
+SCons interactive mode supports the following commands: |
+ |
+.RS 10 |
+.TP 6 |
+.BI build "[OPTIONS] [TARGETS] ..." |
+Builds the specified |
+.I TARGETS |
+(and their dependencies) |
+with the specified |
+SCons command-line |
+.IR OPTIONS . |
+.B b |
+and |
+.B scons |
+are synonyms. |
+ |
+The following SCons command-line options affect the |
+.B build |
+command: |
+ |
+.ES |
+--cache-debug=FILE |
+--cache-disable, --no-cache |
+--cache-force, --cache-populate |
+--cache-show |
+--debug=TYPE |
+-i, --ignore-errors |
+-j N, --jobs=N |
+-k, --keep-going |
+-n, --no-exec, --just-print, --dry-run, --recon |
+-Q |
+-s, --silent, --quiet |
+--taskmastertrace=FILE |
+--tree=OPTIONS |
+.EE |
+ |
+.IP "" 6 |
+Any other SCons command-line options that are specified |
+do not cause errors |
+but have no effect on the |
+.B build |
+command |
+(mainly because they affect how the SConscript files are read, |
+which only happens once at the beginning of interactive mode). |
+ |
+.TP 6 |
+.BI clean "[OPTIONS] [TARGETS] ..." |
+Cleans the specified |
+.I TARGETS |
+(and their dependencies) |
+with the specified options. |
+.B c |
+is a synonym. |
+This command is itself a synonym for |
+.B "build --clean" |
+ |
+.TP 6 |
+.BI exit |
+Exits SCons interactive mode. |
+You can also exit by terminating input |
+(CTRL+D on UNIX or Linux systems, |
+CTRL+Z on Windows systems). |
+ |
+.TP 6 |
+.BI help "[COMMAND]" |
+Provides a help message about |
+the commands available in SCons interactive mode. |
+If |
+.I COMMAND |
+is specified, |
+.B h |
+and |
+.B ? |
+are synonyms. |
+ |
+.TP 6 |
+.BI shell "[COMMANDLINE]" |
+Executes the specified |
+.I COMMANDLINE |
+in a subshell. |
+If no |
+.I COMMANDLINE |
+is specified, |
+executes the interactive command interpreter |
+specified in the |
+.B SHELL |
+environment variable |
+(on UNIX and Linux systems) |
+or the |
+.B COMSPEC |
+environment variable |
+(on Windows systems). |
+.B sh |
+and |
+.B ! |
+are synonyms. |
+ |
+.TP 6 |
+.B version |
+Prints SCons version information. |
+.RE |
+ |
+.IP |
+An empty line repeats the last typed command. |
+Command-line editing can be used if the |
+.B readline |
+module is available. |
+ |
+.ES |
+$ scons --interactive |
+scons: Reading SConscript files ... |
+scons: done reading SConscript files. |
+scons>>> build -n prog |
+scons>>> exit |
+.EE |
+ |
+.TP |
+.RI -j " N" ", --jobs=" N |
+Specifies the number of jobs (commands) to run simultaneously. |
+If there is more than one |
+.B -j |
+option, the last one is effective. |
+.\" ??? If the |
+.\" .B -j |
+.\" option |
+.\" is specified without an argument, |
+.\" .B scons |
+.\" will not limit the number of |
+.\" simultaneous jobs. |
+ |
+.TP |
+-k, --keep-going |
+Continue as much as possible after an error. The target that |
+failed and those that depend on it will not be remade, but other |
+targets specified on the command line will still be processed. |
+ |
+.\" .TP |
+.\" .RI -l " N" ", --load-average=" N ", --max-load=" N |
+.\" No new jobs (commands) will be started if |
+.\" there are other jobs running and the system load |
+.\" average is at least |
+.\" .I N |
+.\" (a floating-point number). |
+ |
+.\" |
+.\" .TP |
+.\" --list-derived |
+.\" List derived files (targets, dependencies) that would be built, |
+.\" but do not build them. |
+.\" [XXX This can probably go away with the right |
+.\" combination of other options. Revisit this issue.] |
+.\" |
+.\" .TP |
+.\" --list-actions |
+.\" List derived files that would be built, with the actions |
+.\" (commands) that build them. Does not build the files. |
+.\" [XXX This can probably go away with the right |
+.\" combination of other options. Revisit this issue.] |
+.\" |
+.\" .TP |
+.\" --list-where |
+.\" List derived files that would be built, plus where the file is |
+.\" defined (file name and line number). Does not build the files. |
+.\" [XXX This can probably go away with the right |
+.\" combination of other options. Revisit this issue.] |
+ |
+.TP |
+-m |
+Ignored for compatibility with non-GNU versions of |
+.BR make . |
+ |
+.TP |
+.RI --max-drift= SECONDS |
+Set the maximum expected drift in the modification time of files to |
+.IR SECONDS . |
+This value determines how long a file must be unmodified |
+before its cached content signature |
+will be used instead of |
+calculating a new content signature (MD5 checksum) |
+of the file's contents. |
+The default value is 2 days, which means a file must have a |
+modification time of at least two days ago in order to have its |
+cached content signature used. |
+A negative value means to never cache the content |
+signature and to ignore the cached value if there already is one. A value |
+of 0 means to always use the cached signature, |
+no matter how old the file is. |
+ |
+.TP |
+.RI --md5-chunksize= KILOBYTES |
+Set the block size used to compute MD5 signatures to |
+.IR KILOBYTES . |
+This value determines the size of the chunks which are read in at once when |
+computing MD5 signatures. Files below that size are fully stored in memory |
+before performing the signature computation while bigger files are read in |
+block-by-block. A huge block-size leads to high memory consumption while a very |
+small block-size slows down the build considerably. |
+ |
+The default value is to use a chunk size of 64 kilobytes, which should |
+be appropriate for most uses. |
+ |
+.TP |
+-n, --just-print, --dry-run, --recon |
+No execute. Print the commands that would be executed to build |
+any out-of-date target files, but do not execute the commands. |
+ |
+.TP |
+.RI --no-site-dir |
+Prevents the automatic addition of the standard |
+.I site_scons |
+dir to |
+.IR sys.path . |
+Also prevents loading the |
+.I site_scons/site_init.py |
+module if it exists, and prevents adding |
+.I site_scons/site_tools |
+to the toolpath. |
+ |
+.\" .TP |
+.\" .RI -o " file" ", --old-file=" file ", --assume-old=" file |
+.\" Do not rebuild |
+.\" .IR file , |
+.\" and do |
+.\" not rebuild anything due to changes in the contents of |
+.\" .IR file . |
+.\" .TP |
+.\" .RI --override " file" |
+.\" Read values to override specific build environment variables |
+.\" from the specified |
+.\" .IR file . |
+.\" .TP |
+.\" -p |
+.\" Print the data base (construction environments, |
+.\" Builder and Scanner objects) that are defined |
+.\" after reading the SConscript files. |
+.\" After printing, a normal build is performed |
+.\" as usual, as specified by other command-line options. |
+.\" This also prints version information |
+.\" printed by the |
+.\" .B -v |
+.\" option. |
+.\" |
+.\" To print the database without performing a build do: |
+.\" |
+.\" .ES |
+.\" scons -p -q |
+.\" .EE |
+ |
+.TP |
+.RI --profile= file |
+Run SCons under the Python profiler |
+and save the results in the specified |
+.IR file . |
+The results may be analyzed using the Python |
+pstats module. |
+ |
+.TP |
+-q, --question |
+Do not run any commands, or print anything. Just return an exit |
+status that is zero if the specified targets are already up to |
+date, non-zero otherwise. |
+.TP |
+-Q |
+Quiets SCons status messages about |
+reading SConscript files, |
+building targets |
+and entering directories. |
+Commands that are executed |
+to rebuild target files are still printed. |
+ |
+.\" .TP |
+.\" -r, -R, --no-builtin-rules, --no-builtin-variables |
+.\" Clear the default construction variables. Construction |
+.\" environments that are created will be completely empty. |
+ |
+.TP |
+--random |
+Build dependencies in a random order. This is useful when |
+building multiple trees simultaneously with caching enabled, |
+to prevent multiple builds from simultaneously trying to build |
+or retrieve the same target files. |
+ |
+.TP |
+-s, --silent, --quiet |
+Silent. Do not print commands that are executed to rebuild |
+target files. |
+Also suppresses SCons status messages. |
+ |
+.TP |
+-S, --no-keep-going, --stop |
+Ignored for compatibility with GNU |
+.BR make . |
+ |
+.TP |
+.RI --site-dir= dir |
+Uses the named dir as the site dir rather than the default |
+.I site_scons |
+dir. This dir will get prepended to |
+.IR sys.path , |
+the module |
+.IR dir /site_init.py |
+will get loaded if it exists, and |
+.IR dir /site_tools |
+will get added to the default toolpath. |
+ |
+.TP |
+.RI --stack-size= KILOBYTES |
+Set the size stack used to run threads to |
+.IR KILOBYTES . |
+This value determines the stack size of the threads used to run jobs. |
+These are the threads that execute the actions of the builders for the |
+nodes that are out-of-date. |
+Note that this option has no effect unless the |
+.B num_jobs |
+option, which corresponds to -j and --jobs, is larger than one. Using |
+a stack size that is too small may cause stack overflow errors. This |
+usually shows up as segmentation faults that cause scons to abort |
+before building anything. Using a stack size that is too large will |
+cause scons to use more memory than required and may slow down the entire |
+build process. |
+ |
+The default value is to use a stack size of 256 kilobytes, which should |
+be appropriate for most uses. You should not need to increase this value |
+unless you encounter stack overflow errors. |
+ |
+.TP |
+-t, --touch |
+Ignored for compatibility with GNU |
+.BR make . |
+(Touching a file to make it |
+appear up-to-date is unnecessary when using |
+.BR scons .) |
+ |
+.TP |
+.RI --taskmastertrace= file |
+Prints trace information to the specified |
+.I file |
+about how the internal Taskmaster object |
+evaluates and controls the order in which Nodes are built. |
+A file name of |
+.B - |
+may be used to specify the standard output. |
+ |
+.TP |
+.RI -tree= options |
+Prints a tree of the dependencies |
+after each top-level target is built. |
+This prints out some or all of the tree, |
+in various formats, |
+depending on the |
+.I options |
+specified: |
+ |
+.TP |
+--tree=all |
+Print the entire dependency tree |
+after each top-level target is built. |
+This prints out the complete dependency tree, |
+including implicit dependencies and ignored dependencies. |
+ |
+.TP |
+--tree=derived |
+Restricts the tree output to only derived (target) files, |
+not source files. |
+ |
+.TP |
+--tree=status |
+Prints status information for each displayed node. |
+ |
+.TP |
+--tree=prune |
+Prunes the tree to avoid repeating dependency information |
+for nodes that have already been displayed. |
+Any node that has already been displayed |
+will have its name printed in |
+.BR "[square brackets]" , |
+as an indication that the dependencies |
+for that node can be found by searching |
+for the relevant output higher up in the tree. |
+ |
+.IP |
+Multiple options may be specified, |
+separated by commas: |
+ |
+.ES |
+# Prints only derived files, with status information: |
+scons --tree=derived,status |
+ |
+# Prints all dependencies of target, with status information |
+# and pruning dependencies of already-visited Nodes: |
+scons --tree=all,prune,status target |
+.EE |
+ |
+.TP |
+-u, --up, --search-up |
+Walks up the directory structure until an |
+.I SConstruct , |
+.I Sconstruct |
+or |
+.I sconstruct |
+file is found, and uses that |
+as the top of the directory tree. |
+If no targets are specified on the command line, |
+only targets at or below the |
+current directory will be built. |
+ |
+.TP |
+-U |
+Works exactly the same way as the |
+.B -u |
+option except for the way default targets are handled. |
+When this option is used and no targets are specified on the command line, |
+all default targets that are defined in the SConscript(s) in the current |
+directory are built, regardless of what directory the resultant targets end |
+up in. |
+ |
+.TP |
+-v, --version |
+Print the |
+.B scons |
+version, copyright information, |
+list of authors, and any other relevant information. |
+Then exit. |
+ |
+.TP |
+-w, --print-directory |
+Print a message containing the working directory before and |
+after other processing. |
+ |
+.TP |
+--no-print-directory |
+Turn off -w, even if it was turned on implicitly. |
+ |
+.TP |
+.RI --warn= type ", --warn=no-" type |
+Enable or disable warnings. |
+.I type |
+specifies the type of warnings to be enabled or disabled: |
+ |
+.TP |
+--warn=all, --warn=no-all |
+Enables or disables all warnings. |
+ |
+.TP |
+--warn=cache-write-error, --warn=no-cache-write-error |
+Enables or disables warnings about errors trying to |
+write a copy of a built file to a specified |
+.BR CacheDir (). |
+These warnings are disabled by default. |
+ |
+.TP |
+--warn=corrupt-sconsign, --warn=no-corrupt-sconsign |
+Enables or disables warnings about unfamiliar signature data in |
+.B .sconsign |
+files. |
+These warnings are enabled by default. |
+ |
+.TP |
+--warn=dependency, --warn=no-dependency |
+Enables or disables warnings about dependencies. |
+These warnings are disabled by default. |
+ |
+.TP |
+--warn=deprecated, --warn=no-deprecated |
+Enables or disables all warnings about use of |
+currently deprecated features. |
+These warnings are enabled by default. |
+Note that the |
+.B --warn=no-deprecated |
+option does not disable warnings about absolutely all deprecated features. |
+Warnings for some deprecated features that have already been through |
+several releases with deprecation warnings |
+may be mandatory for a release or two |
+before they are officially no longer supported by SCons. |
+Warnings for some specific deprecated features |
+may be enabled or disabled individually; |
+see below. |
+ |
+.RS |
+.TP |
+--warn=deprecated-copy, --warn=no-deprecated-copy |
+Enables or disables warnings about use of the deprecated |
+.B env.Copy() |
+method. |
+ |
+.TP |
+--warn=deprecated-source-signatures, --warn=no-deprecated-source-signatures |
+Enables or disables warnings about use of the deprecated |
+.B SourceSignatures() |
+function or |
+.B env.SourceSignatures() |
+method. |
+ |
+.TP |
+--warn=deprecated-target-signatures, --warn=no-deprecated-target-signatures |
+Enables or disables warnings about use of the deprecated |
+.B TargetSignatures() |
+function or |
+.B env.TargetSignatures() |
+method. |
+.RE |
+ |
+.TP |
+--warn=duplicate-environment, --warn=no-duplicate-environment |
+Enables or disables warnings about attempts to specify a build |
+of a target with two different construction environments |
+that use the same action. |
+These warnings are enabled by default. |
+ |
+.TP |
+--warn=fortran-cxx-mix, --warn=no-fortran-cxx-mix |
+Enables or disables the specific warning about linking |
+Fortran and C++ object files in a single executable, |
+which can yield unpredictable behavior with some compilers. |
+ |
+.TP |
+--warn=future-deprecated, --warn=no-future-deprecated |
+Enables or disables warnings about features |
+that will be deprecated in the future. |
+These warnings are disabled by default. |
+Enabling this warning is especially |
+recommended for projects that redistribute |
+SCons configurations for other users to build, |
+so that the project can be warned as soon as possible |
+about to-be-deprecated features |
+that may require changes to the configuration. |
+ |
+.TP |
+--warn=link, --warn=no-link |
+Enables or disables warnings about link steps. |
+ |
+.TP |
+--warn=misleading-keywords, --warn=no-misleading-keywords |
+Enables or disables warnings about use of the misspelled keywords |
+.B targets |
+and |
+.B sources |
+when calling Builders. |
+(Note the last |
+.B s |
+characters, the correct spellings are |
+.B target |
+and |
+.B source.) |
+These warnings are enabled by default. |
+ |
+.TP |
+--warn=missing-sconscript, --warn=no-missing-sconscript |
+Enables or disables warnings about missing SConscript files. |
+These warnings are enabled by default. |
+ |
+.TP |
+--warn=no-md5-module, --warn=no-no-md5-module |
+Enables or disables warnings about the version of Python |
+not having an MD5 checksum module available. |
+These warnings are enabled by default. |
+ |
+.TP |
+--warn=no-metaclass-support, --warn=no-no-metaclass-support |
+Enables or disables warnings about the version of Python |
+not supporting metaclasses when the |
+.B --debug=memoizer |
+option is used. |
+These warnings are enabled by default. |
+ |
+.TP |
+--warn=no-object-count, --warn=no-no-object-count |
+Enables or disables warnings about the |
+.B --debug=object |
+feature not working when |
+.B scons |
+is run with the python |
+.B \-O |
+option or from optimized Python (.pyo) modules. |
+ |
+.TP |
+--warn=no-parallel-support, --warn=no-no-parallel-support |
+Enables or disables warnings about the version of Python |
+not being able to support parallel builds when the |
+.B -j |
+option is used. |
+These warnings are enabled by default. |
+ |
+.TP |
+--warn=python-version, --warn=no-python-version |
+Enables or disables the warning about running |
+SCons with a deprecated version of Python. |
+These warnings are enabled by default. |
+ |
+.TP |
+--warn=reserved-variable, --warn=no-reserved-variable |
+Enables or disables warnings about attempts to set the |
+reserved construction variable names |
+.BR CHANGED_SOURCES , |
+.BR CHANGED_TARGETS , |
+.BR TARGET , |
+.BR TARGETS , |
+.BR SOURCE , |
+.BR SOURCES , |
+.BR UNCHANGED_SOURCES |
+or |
+.BR UNCHANGED_TARGETS . |
+These warnings are disabled by default. |
+ |
+.TP |
+--warn=stack-size, --warn=no-stack-size |
+Enables or disables warnings about requests to set the stack size |
+that could not be honored. |
+These warnings are enabled by default. |
+ |
+.\" .TP |
+.\" .RI --write-filenames= file |
+.\" Write all filenames considered into |
+.\" .IR file . |
+.\" |
+.\" .TP |
+.\" .RI -W " file" ", --what-if=" file ", --new-file=" file ", --assume-new=" file |
+.\" Pretend that the target |
+.\" .I file |
+.\" has been |
+.\" modified. When used with the |
+.\" .B -n |
+.\" option, this |
+.\" show you what would be rebuilt if you were to modify that file. |
+.\" Without |
+.\" .B -n |
+.\" ... what? XXX |
+.\" |
+.\" .TP |
+.\" --warn-undefined-variables |
+.\" Warn when an undefined variable is referenced. |
+ |
+.TP |
+.RI -Y " repository" ", --repository=" repository ", --srcdir=" repository |
+Search the specified repository for any input and target |
+files not found in the local directory hierarchy. Multiple |
+.B -Y |
+options may be specified, in which case the |
+repositories are searched in the order specified. |
+ |
+.SH CONFIGURATION FILE REFERENCE |
+.\" .SS Python Basics |
+.\" XXX Adding this in the future would be a help. |
+.SS Construction Environments |
+A construction environment is the basic means by which the SConscript |
+files communicate build information to |
+.BR scons . |
+A new construction environment is created using the |
+.B Environment |
+function: |
+ |
+.ES |
+env = Environment() |
+.EE |
+ |
+Variables, called |
+.I construction |
+.IR variables , |
+may be set in a construction environment |
+either by specifying them as keywords when the object is created |
+or by assigning them a value after the object is created: |
+ |
+.ES |
+env = Environment(FOO = 'foo') |
+env['BAR'] = 'bar' |
+.EE |
+ |
+As a convenience, |
+construction variables may also be set or modified by the |
+.I parse_flags |
+keyword argument, which applies the |
+.B ParseFlags |
+method (described below) to the argument value |
+after all other processing is completed. |
+This is useful either if the exact content of the flags is unknown |
+(for example, read from a control file) |
+or if the flags are distributed to a number of construction variables. |
+ |
+.ES |
+env = Environment(parse_flags = '-Iinclude -DEBUG -lm') |
+.EE |
+ |
+This example adds 'include' to |
+.BR CPPPATH , |
+\&'EBUG' to |
+.BR CPPDEFINES , |
+and 'm' to |
+.BR LIBS . |
+ |
+By default, a new construction environment is |
+initialized with a set of builder methods |
+and construction variables that are appropriate |
+for the current platform. |
+An optional platform keyword argument may be |
+used to specify that an environment should |
+be initialized for a different platform: |
+ |
+.ES |
+env = Environment(platform = 'cygwin') |
+env = Environment(platform = 'os2') |
+env = Environment(platform = 'posix') |
+env = Environment(platform = 'win32') |
+.EE |
+ |
+Specifying a platform initializes the appropriate |
+construction variables in the environment |
+to use and generate file names with prefixes |
+and suffixes appropriate for the platform. |
+ |
+Note that the |
+.B win32 |
+platform adds the |
+.B SystemDrive |
+and |
+.B SystemRoot |
+variables from the user's external environment |
+to the construction environment's |
+.B ENV |
+dictionary. |
+This is so that any executed commands |
+that use sockets to connect with other systems |
+(such as fetching source files from |
+external CVS repository specifications like |
+.BR :pserver:anonymous@cvs.sourceforge.net:/cvsroot/scons ) |
+will work on Windows systems. |
+ |
+The platform argument may be function or callable object, |
+in which case the Environment() method |
+will call the specified argument to update |
+the new construction environment: |
+ |
+.ES |
+def my_platform(env): |
+ env['VAR'] = 'xyzzy' |
+ |
+env = Environment(platform = my_platform) |
+.EE |
+ |
+Additionally, a specific set of tools |
+with which to initialize the environment |
+may be specified as an optional keyword argument: |
+ |
+.ES |
+env = Environment(tools = ['msvc', 'lex']) |
+.EE |
+ |
+Non-built-in tools may be specified using the toolpath argument: |
+ |
+.ES |
+env = Environment(tools = ['default', 'foo'], toolpath = ['tools']) |
+.EE |
+ |
+This looks for a tool specification in tools/foo.py (as well as |
+using the ordinary default tools for the platform). foo.py should |
+have two functions: generate(env, **kw) and exists(env). |
+The |
+.B generate() |
+function |
+modifies the passed-in environment |
+to set up variables so that the tool |
+can be executed; |
+it may use any keyword arguments |
+that the user supplies (see below) |
+to vary its initialization. |
+The |
+.B exists() |
+function should return a true |
+value if the tool is available. |
+Tools in the toolpath are used before |
+any of the built-in ones. For example, adding gcc.py to the toolpath |
+would override the built-in gcc tool. |
+Also note that the toolpath is |
+stored in the environment for use |
+by later calls to |
+.BR Clone () |
+and |
+.BR Tool () |
+methods: |
+ |
+.ES |
+base = Environment(toolpath=['custom_path']) |
+derived = base.Clone(tools=['custom_tool']) |
+derived.CustomBuilder() |
+.EE |
+ |
+The elements of the tools list may also |
+be functions or callable objects, |
+in which case the Environment() method |
+will call the specified elements |
+to update the new construction environment: |
+ |
+.ES |
+def my_tool(env): |
+ env['XYZZY'] = 'xyzzy' |
+ |
+env = Environment(tools = [my_tool]) |
+.EE |
+ |
+The individual elements of the tools list |
+may also themselves be two-element lists of the form |
+.RI ( toolname ", " kw_dict ). |
+SCons searches for the |
+.I toolname |
+specification file as described above, and |
+passes |
+.IR kw_dict , |
+which must be a dictionary, as keyword arguments to the tool's |
+.B generate |
+function. |
+The |
+.B generate |
+function can use the arguments to modify the tool's behavior |
+by setting up the environment in different ways |
+or otherwise changing its initialization. |
+ |
+.ES |
+# in tools/my_tool.py: |
+def generate(env, **kw): |
+ # Sets MY_TOOL to the value of keyword argument 'arg1' or 1. |
+ env['MY_TOOL'] = kw.get('arg1', '1') |
+def exists(env): |
+ return 1 |
+ |
+# in SConstruct: |
+env = Environment(tools = ['default', ('my_tool', {'arg1': 'abc'})], |
+ toolpath=['tools']) |
+.EE |
+ |
+The tool definition (i.e. my_tool()) can use the PLATFORM variable from |
+the environment it receives to customize the tool for different platforms. |
+ |
+If no tool list is specified, then SCons will auto-detect the installed |
+tools using the PATH variable in the ENV construction variable and the |
+platform name when the Environment is constructed. Changing the PATH |
+variable after the Environment is constructed will not cause the tools to |
+be redetected. |
+ |
+SCons supports the following tool specifications out of the box: |
+ |
+.ES |
+386asm |
+aixc++ |
+aixcc |
+aixf77 |
+aixlink |
+ar |
+as |
+bcc32 |
+c++ |
+cc |
+cvf |
+dmd |
+dvipdf |
+dvips |
+f77 |
+f90 |
+f95 |
+fortran |
+g++ |
+g77 |
+gas |
+gcc |
+gfortran |
+gnulink |
+gs |
+hpc++ |
+hpcc |
+hplink |
+icc |
+icl |
+ifl |
+ifort |
+ilink |
+ilink32 |
+intelc |
+jar |
+javac |
+javah |
+latex |
+lex |
+link |
+linkloc |
+m4 |
+masm |
+midl |
+mingw |
+mslib |
+mslink |
+mssdk |
+msvc |
+msvs |
+mwcc |
+mwld |
+nasm |
+pdflatex |
+pdftex |
+qt |
+rmic |
+rpcgen |
+sgiar |
+sgic++ |
+sgicc |
+sgilink |
+sunar |
+sunc++ |
+suncc |
+sunf77 |
+sunf90 |
+sunf95 |
+sunlink |
+swig |
+tar |
+tex |
+textfile |
+tlib |
+yacc |
+zip |
+.EE |
+ |
+Additionally, there is a "tool" named |
+.B default |
+which configures the |
+environment with a default set of tools for the current platform. |
+ |
+On posix and cygwin platforms |
+the GNU tools (e.g. gcc) are preferred by SCons, |
+on Windows the Microsoft tools (e.g. msvc) |
+followed by MinGW are preferred by SCons, |
+and in OS/2 the IBM tools (e.g. icc) are preferred by SCons. |
+ |
+.SS Builder Methods |
+ |
+Build rules are specified by calling a construction |
+environment's builder methods. |
+The arguments to the builder methods are |
+.B target |
+(a list of targets to be built, |
+usually file names) |
+and |
+.B source |
+(a list of sources to be built, |
+usually file names). |
+ |
+Because long lists of file names |
+can lead to a lot of quoting, |
+.B scons |
+supplies a |
+.B Split() |
+global function |
+and a same-named environment method |
+that split a single string |
+into a list, separated on |
+strings of white-space characters. |
+(These are similar to the 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 $CFILESUFFIX construction variable |
+(\fB.c\fP by default) |
+is automatically added to the target |
+if it is not already present. |
+Example: |
+ |
+.ES |
+# builds foo.c |
+env.CFile(target = 'foo.c', source = 'foo.l') |
+# builds bar.c |
+env.CFile(target = 'bar', source = 'bar.y') |
+.EE |
+ |
+'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" |
+.IP CXXFile() |
+.IP env.CXXFile() |
+Builds a C++ source file given a lex (\fB.ll\fP) |
+or yacc (\fB.yy\fP) |
+input file. |
+The suffix specified by the $CXXFILESUFFIX construction variable |
+(\fB.cc\fP by default) |
+is automatically added to the target |
+if it is not already present. |
+Example: |
+ |
+.ES |
+# builds foo.cc |
+env.CXXFile(target = 'foo.cc', source = 'foo.ll') |
+# builds bar.cc |
+env.CXXFile(target = 'bar', source = 'bar.yy') |
+.EE |
+ |
+'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" |
+.IP DVI() |
+.IP env.DVI() |
+Builds a \fB.dvi\fP file |
+from a \fB.tex\fP, |
+\fB.ltx\fP or \fB.latex\fP input file. |
+If the source file suffix is \fB.tex\fP, |
+.B scons |
+will examine the contents of the file; |
+if the string |
+.B \\documentclass |
+or |
+.B \\documentstyle |
+is found, the file is assumed to be a LaTeX file and |
+the target is built by invoking the $LATEXCOM command line; |
+otherwise, the $TEXCOM command line is used. |
+If the file is a LaTeX file, |
+the |
+.BR DVI () |
+builder method will also examine the contents |
+of the |
+.B .aux |
+file and invoke the $BIBTEX command line |
+if the string |
+.B bibdata |
+is found, |
+start $MAKEINDEX to generate an index if a |
+.B .ind |
+file is found |
+and will examine the contents |
+.B .log |
+file and re-run the $LATEXCOM command |
+if the log file says it is necessary. |
+ |
+The suffix \fB.dvi\fP |
+(hard-coded within TeX itself) |
+is automatically added to the target |
+if it is not already present. |
+Examples: |
+ |
+.ES |
+# builds from aaa.tex |
+env.DVI(target = 'aaa.dvi', source = 'aaa.tex') |
+# builds bbb.dvi |
+env.DVI(target = 'bbb', source = 'bbb.ltx') |
+# builds from ccc.latex |
+env.DVI(target = 'ccc.dvi', source = 'ccc.latex') |
+.EE |
+ |
+'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" |
+.IP Install() |
+.IP env.Install() |
+Installs one or more source files or directories |
+in the specified target, |
+which must be a directory. |
+The names of the specified source files or directories |
+remain the same within the destination directory. |
+ |
+.ES |
+env.Install('/usr/local/bin', source = ['foo', 'bar']) |
+.EE |
+ |
+'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" |
+.IP InstallAs() |
+.IP env.InstallAs() |
+Installs one or more source files or directories |
+to specific names, |
+allowing changing a file or directory name |
+as part of the installation. |
+It is an error if the |
+target |
+and |
+source |
+arguments list different numbers of files or directories. |
+ |
+.ES |
+env.InstallAs(target = '/usr/local/bin/foo', |
+ source = 'foo_debug') |
+env.InstallAs(target = ['../lib/libfoo.a', '../lib/libbar.a'], |
+ source = ['libFOO.a', 'libBAR.a']) |
+.EE |
+ |
+'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" |
+.IP Jar() |
+.IP env.Jar() |
+Builds a Java archive (\fB.jar\fP) file |
+from the specified list of sources. |
+Any directories in the source list |
+will be searched for \fB.class\fP files). |
+Any \fB.java\fP files in the source list |
+will be compiled to \fB.class\fP files |
+by calling the \fBJava\fP() Builder. |
+ |
+If the $JARCHDIR value is set, the |
+.B jar |
+command will change to the specified directory using the |
+.B \-C |
+option. |
+If $JARCHDIR is not set explicitly, |
+&SCons; will use the top of any subdirectory tree |
+in which Java \fB.class\fP |
+were built by the \fBJava\fP() Builder. |
+ |
+If the contents any of the source files begin with the string |
+.BR Manifest-Version , |
+the file is assumed to be a manifest |
+and is passed to the |
+.B jar |
+command with the |
+.B m |
+option set. |
+ |
+.ES |
+env.Jar(target = 'foo.jar', source = 'classes') |
+ |
+env.Jar(target = 'bar.jar', |
+ source = ['bar1.java', 'bar2.java']) |
+.EE |
+ |
+'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" |
+.IP 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 |
+$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 $M4FLAGS value of |
+.BR \-E , |
+which considers all warnings to be fatal |
+and stops on the first warning |
+when using the GNU version of m4. |
+Example: |
+ |
+.ES |
+env.M4(target = 'foo.c', source = 'foo.c.m4') |
+.EE |
+ |
+'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" |
+.IP Moc() |
+.IP env.Moc() |
+Builds an output file from a moc input file. Moc input files are either |
+header files or cxx files. This builder is only available after using the |
+tool 'qt'. See the $QTDIR variable for more information. |
+Example: |
+ |
+.ES |
+env.Moc('foo.h') # generates moc_foo.cc |
+env.Moc('foo.cpp') # generates foo.moc |
+.EE |
+ |
+'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" |
+.IP MSVSProject() |
+.IP env.MSVSProject() |
+Builds a Microsoft Visual Studio project file, |
+and by default builds a solution file as well. |
+ |
+This builds a Visual Studio project file, based on the version of |
+Visual Studio that is configured (either the latest installed version, |
+or the version specified by |
+$MSVS_VERSION |
+in the Environment constructor). |
+For Visual Studio 6, it will generate a |
+.B .dsp |
+file. |
+For Visual Studio 7 (.NET) and later versions, it will generate a |
+.B .vcproj |
+file. |
+ |
+By default, |
+this also generates a solution file |
+for the specified project, |
+a |
+.B .dsw |
+file for Visual Studio 6 |
+or a |
+.B .sln |
+file for Visual Studio 7 (.NET). |
+This behavior may be disabled by specifying |
+.B auto_build_solution=0 |
+when you call |
+.BR MSVSProject (), |
+in which case you presumably want to |
+build the solution file(s) |
+by calling the |
+.BR MSVSSolution () |
+Builder (see below). |
+ |
+The \fBMSVSProject\fP() builder |
+takes several lists of filenames |
+to be placed into the project file. |
+These are currently limited to |
+.BR srcs , |
+.BR incs , |
+.BR localincs , |
+.BR resources , |
+and |
+.BR misc . |
+These are pretty self-explanatory, but it should be noted that these |
+lists are added to the $SOURCES construction variable as strings, |
+NOT as SCons File Nodes. This is because they represent file |
+names to be added to the project file, not the source files used to |
+build the project file. |
+ |
+The above filename lists are all optional, |
+although at least one must be specified |
+for the resulting project file to be non-empty. |
+ |
+In addition to the above lists of values, |
+the following values may be specified: |
+ |
+.BR target : |
+The name of the target |
+.B .dsp |
+or |
+.B .vcproj |
+file. |
+The correct |
+suffix for the version of Visual Studio must be used, |
+but the |
+$MSVSPROJECTSUFFIX |
+construction variable |
+will be defined to the correct value (see example below). |
+ |
+.BR variant : |
+The name of this particular variant. |
+For Visual Studio 7 projects, |
+this can also be a list of variant names. |
+These are typically things like "Debug" or "Release", but really |
+can be anything you want. |
+For Visual Studio 7 projects, |
+they may also specify a target platform |
+separated from the variant name by a |
+.B | |
+(vertical pipe) |
+character: |
+.BR Debug|Xbox . |
+The default target platform is Win32. |
+Multiple calls to |
+.BR MSVSProject () |
+with different variants are allowed; |
+all variants will be added to the project file with their appropriate |
+build targets and sources. |
+ |
+.BR buildtarget : |
+An optional string, node, or list of strings or nodes |
+(one per build variant), to tell the Visual Studio debugger |
+what output target to use in what build variant. |
+The number of |
+.B buildtarget |
+entries must match the number of |
+.B variant |
+entries. |
+ |
+.BR runfile : |
+The name of the file that Visual Studio 7 and later |
+will run and debug. |
+This appears as the value of the |
+.B Output |
+field in the resutling Visual Studio project file. |
+If this is not specified, |
+the default is the same as the specified |
+.B buildtarget |
+value. |
+ |
+Note that because &SCons; always executes its build commands |
+from the directory in which the \fBSConstruct\fP file is located, |
+if you generate a project file in a different directory |
+than the \fBSConstruct\fP directory, |
+users will not be able to double-click |
+on the file name in compilation error messages |
+displayed in the Visual Studio console output window. |
+This can be remedied by adding the |
+Visual C/C++ |
+.B /FC |
+compiler option to the $CCFLAGS variable |
+so that the compiler will print |
+the full path name of any |
+files that cause compilation errors. |
+ |
+Example usage: |
+ |
+.ES |
+barsrcs = ['bar.cpp'], |
+barincs = ['bar.h'], |
+barlocalincs = ['StdAfx.h'] |
+barresources = ['bar.rc','resource.h'] |
+barmisc = ['bar_readme.txt'] |
+ |
+dll = env.SharedLibrary(target = 'bar.dll', |
+ source = barsrcs) |
+ |
+env.MSVSProject(target = 'Bar' + env['MSVSPROJECTSUFFIX'], |
+ srcs = barsrcs, |
+ incs = barincs, |
+ localincs = barlocalincs, |
+ resources = barresources, |
+ misc = barmisc, |
+ buildtarget = dll, |
+ variant = 'Release') |
+.EE |
+ |
+'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" |
+.IP MSVSSolution() |
+.IP env.MSVSSolution() |
+Builds a Microsoft Visual Studio solution file. |
+ |
+This builds a Visual Studio solution file, |
+based on the version of Visual Studio that is configured |
+(either the latest installed version, |
+or the version specified by |
+$MSVS_VERSION |
+in the construction environment). |
+For Visual Studio 6, it will generate a |
+.B .dsw |
+file. |
+For Visual Studio 7 (.NET), it will |
+generate a |
+.B .sln |
+file. |
+ |
+The following values must be specified: |
+ |
+.BR target : |
+The name of the target .dsw or .sln file. The correct |
+suffix for the version of Visual Studio must be used, but the value |
+$MSVSSOLUTIONSUFFIX |
+will be defined to the correct value (see example below). |
+ |
+.BR variant : |
+The name of this particular variant, or a list of variant |
+names (the latter is only supported for MSVS 7 solutions). These are |
+typically things like "Debug" or "Release", but really can be anything |
+you want. For MSVS 7 they may also specify target platform, like this |
+"Debug|Xbox". Default platform is Win32. |
+ |
+.BR projects : |
+A list of project file names, or Project nodes returned by calls to the |
+.BR MSVSProject () |
+Builder, |
+to be placed into the solution file. |
+It should be noted that these file names are NOT added to the $SOURCES |
+environment variable in form of files, but rather as strings. This |
+is because they represent file names to be added to the solution file, |
+not the source files used to build the solution file. |
+ |
+(NOTE: Currently only one project is supported per solution.) |
+ |
+Example Usage: |
+ |
+.ES |
+env.MSVSSolution(target = 'Bar' + env['MSVSSOLUTIONSUFFIX'], |
+ projects = ['bar' + env['MSVSPROJECTSUFFIX']], |
+ variant = 'Release') |
+.EE |
+ |
+'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" |
+.IP Object() |
+.IP env.Object() |
+A synonym for the |
+.BR StaticObject () |
+builder method. |
+ |
+'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" |
+.IP Package() |
+.IP env.Package() |
+Builds software distribution packages. |
+Packages consist of files to install and packaging information. |
+The former may be specified with the \fIsource\fP parameter and may be left out, |
+in which case the &FindInstalledFiles; function will collect |
+all files that have an \fBInstall\fP() or \fBInstallAs\fP() Builder attached. |
+If the \fItarget\fP is not specified |
+it will be deduced from additional information given to this Builder. |
+ |
+The packaging information is specified |
+with the help of construction variables documented below. |
+This information is called a tag to stress that |
+some of them can also be attached to files with the &Tag; function. |
+The mandatory ones will complain if they were not specified. |
+They vary depending on chosen target packager. |
+ |
+The target packager may be selected with the "PACKAGETYPE" command line |
+option or with the $PACKAGETYPE construction variable. Currently |
+the following packagers available: |
+ |
+ * msi - Microsoft Installer |
+ * rpm - Redhat Package Manger |
+ * ipkg - Itsy Package Management System |
+ * tarbz2 - compressed tar |
+ * targz - compressed tar |
+ * zip - zip file |
+ * src_tarbz2 - compressed tar source |
+ * src_targz - compressed tar source |
+ * src_zip - zip file source |
+ |
+An updated list is always available under the "package_type" option when |
+running "scons --help" on a project that has packaging activated. |
+.ES |
+env = Environment(tools=['default', 'packaging']) |
+env.Install('/bin/', 'my_program') |
+env.Package( NAME = 'foo', |
+ VERSION = '1.2.3', |
+ PACKAGEVERSION = 0, |
+ PACKAGETYPE = 'rpm', |
+ LICENSE = 'gpl', |
+ SUMMARY = 'balalalalal', |
+ DESCRIPTION = 'this should be really really long', |
+ X_RPM_GROUP = 'Application/fu', |
+ SOURCE_URL = 'http://foo.org/foo-1.2.3.tar.gz' |
+ ) |
+.EE |
+ |
+'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" |
+.IP 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 $PDFSUFFIX construction variable |
+(\fB.pdf\fP by default) |
+is added automatically to the target |
+if it is not already present. Example: |
+ |
+.ES |
+# builds from aaa.tex |
+env.PDF(target = 'aaa.pdf', source = 'aaa.tex') |
+# builds bbb.pdf from bbb.dvi |
+env.PDF(target = 'bbb', source = 'bbb.dvi') |
+.EE |
+ |
+'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" |
+.IP PostScript() |
+.IP env.PostScript() |
+Builds a \fB.ps\fP file |
+from a \fB.dvi\fP input file |
+(or, by extension, a \fB.tex\fP, |
+.BR .ltx , |
+or |
+\fB.latex\fP input file). |
+The suffix specified by the $PSSUFFIX construction variable |
+(\fB.ps\fP by default) |
+is added automatically to the target |
+if it is not already present. Example: |
+ |
+.ES |
+# builds from aaa.tex |
+env.PostScript(target = 'aaa.ps', source = 'aaa.tex') |
+# builds bbb.ps from bbb.dvi |
+env.PostScript(target = 'bbb', source = 'bbb.dvi') |
+.EE |
+ |
+'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" |
+.IP Program() |
+.IP env.Program() |
+Builds an executable given one or more object files |
+or C, C++, D, or Fortran source files. |
+If any C, C++, D or Fortran source files are specified, |
+then they will be automatically |
+compiled to object files using the |
+.BR Object () |
+builder method; |
+see that builder method's description for |
+a list of legal source file suffixes |
+and how they are interpreted. |
+The target executable file prefix |
+(specified by the $PROGPREFIX construction variable; nothing by default) |
+and suffix |
+(specified by the $PROGSUFFIX construction variable; |
+by default, \fB.exe\fP on Windows systems, |
+nothing on POSIX systems) |
+are automatically added to the target if not already present. |
+Example: |
+ |
+.ES |
+env.Program(target = 'foo', source = ['foo.o', 'bar.c', 'baz.f']) |
+.EE |
+ |
+'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" |
+.IP 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 |
+$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 $SHLIBPREFIX construction variable; |
+by default, \fBlib\fP on POSIX systems, |
+nothing on Windows systems) |
+and suffix |
+(specified by the $SHLIBSUFFIX construction variable; |
+by default, \fB.dll\fP on Windows systems, |
+\fB.so\fP on POSIX systems) |
+are automatically added to the target if not already present. |
+Example: |
+ |
+.ES |
+env.SharedLibrary(target = 'bar', source = ['bar.c', 'foo.o']) |
+.EE |
+.IP |
+On Windows systems, the |
+.BR SharedLibrary () |
+builder method will always build an import |
+(\fB.lib\fP) library |
+in addition to the shared (\fB.dll\fP) library, |
+adding a \fB.lib\fP library with the same basename |
+if there is not already a \fB.lib\fP file explicitly |
+listed in the targets. |
+ |
+Any object files listed in the |
+.B source |
+must have been built for a shared library |
+(that is, using the |
+.BR SharedObject () |
+builder method). |
+.B scons |
+will raise an error if there is any mismatch. |
+ |
+On some platforms, there is a distinction between a shared library |
+(loaded automatically by the system to resolve external references) |
+and a loadable module (explicitly loaded by user action). |
+For maximum portability, use the \fBLoadableModule\fP() builder for the latter. |
+ |
+On Windows systems, specifying |
+.B register=1 |
+will cause the \fB.dll\fP to be |
+registered after it is built using REGSVR32. |
+The command that is run |
+("regsvr32" by default) is determined by $REGSVR construction |
+variable, and the flags passed are determined by $REGSVRFLAGS. By |
+default, $REGSVRFLAGS includes the \fB/s\fP option, |
+to prevent dialogs from popping |
+up and requiring user attention when it is run. If you change |
+$REGSVRFLAGS, be sure to include the \fB/s\fP option. |
+For example, |
+ |
+.ES |
+env.SharedLibrary(target = 'bar', |
+ source = ['bar.cxx', 'foo.obj'], |
+ register=1) |
+.EE |
+.IP |
+will register \fBbar.dll\fP as a COM object |
+when it is done linking it. |
+ |
+'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" |
+.IP SharedObject() |
+.IP env.SharedObject() |
+Builds an object file for |
+inclusion in a shared library. |
+Source files must have one of the same set of extensions |
+specified above for the |
+.BR StaticObject () |
+builder method. |
+On some platforms building a shared object requires additional |
+compiler option |
+(e.g. \fB\-fPIC\fP for gcc) |
+in addition to those needed to build a |
+normal (static) object, but on some platforms there is no difference between a |
+shared object and a normal (static) one. When there is a difference, SCons |
+will only allow shared objects to be linked into a shared library, and will |
+use a different suffix for shared objects. On platforms where there is no |
+difference, SCons will allow both normal (static) |
+and shared objects to be linked into a |
+shared library, and will use the same suffix for shared and normal |
+(static) objects. |
+The target object file prefix |
+(specified by the $SHOBJPREFIX construction variable; |
+by default, the same as $OBJPREFIX) |
+and suffix |
+(specified by the $SHOBJSUFFIX construction variable) |
+are automatically added to the target if not already present. |
+Examples: |
+ |
+.ES |
+env.SharedObject(target = 'ddd', source = 'ddd.c') |
+env.SharedObject(target = 'eee.o', source = 'eee.cpp') |
+env.SharedObject(target = 'fff.obj', source = 'fff.for') |
+.EE |
+.IP |
+Note that the source files will be scanned |
+according to the suffix mappings in the |
+.B SourceFileScanner |
+object. |
+See the section "Scanner Objects," |
+below, for more information. |
+ |
+'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" |
+.IP StaticLibrary() |
+.IP env.StaticLibrary() |
+Builds a static library given one or more object files |
+or C, C++, D or Fortran source files. |
+If any source files are given, |
+then they will be automatically |
+compiled to object files. |
+The static library prefix and suffix (if any) |
+are automatically added to the target. |
+The target library file prefix |
+(specified by the $LIBPREFIX construction variable; |
+by default, \fBlib\fP on POSIX systems, |
+nothing on Windows systems) |
+and suffix |
+(specified by the $LIBSUFFIX construction variable; |
+by default, \fB.lib\fP on Windows systems, |
+\fB.a\fP on POSIX systems) |
+are automatically added to the target if not already present. |
+Example: |
+ |
+.ES |
+env.StaticLibrary(target = 'bar', source = ['bar.c', 'foo.o']) |
+.EE |
+.IP |
+Any object files listed in the |
+.B source |
+must have been built for a static library |
+(that is, using the |
+.BR StaticObject () |
+builder method). |
+.B scons |
+will raise an error if there is any mismatch. |
+ |
+'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" |
+.IP StaticObject() |
+.IP env.StaticObject() |
+Builds a static object file |
+from one or more C, C++, D, or Fortran source files. |
+Source files must have one of the following extensions: |
+ |
+.ES |
+ .asm assembly language file |
+ .ASM assembly language file |
+ .c C file |
+ .C Windows: C file |
+ POSIX: C++ file |
+ .cc C++ file |
+ .cpp C++ file |
+ .cxx C++ file |
+ .cxx C++ file |
+ .c++ C++ file |
+ .C++ C++ file |
+ .d D file |
+ .f Fortran file |
+ .F Windows: Fortran file |
+ POSIX: Fortran file + C pre-processor |
+ .for Fortran file |
+ .FOR Fortran file |
+ .fpp Fortran file + C pre-processor |
+ .FPP Fortran file + C pre-processor |
+ .m Object C file |
+ .mm Object C++ file |
+ .s assembly language file |
+ .S Windows: assembly language file |
+ ARM: CodeSourcery Sourcery Lite |
+ .sx assembly language file + C pre-processor |
+ POSIX: assembly language file + C pre-processor |
+ .spp assembly language file + C pre-processor |
+ .SPP assembly language file + C pre-processor |
+.EE |
+.IP |
+The target object file prefix |
+(specified by the $OBJPREFIX construction variable; nothing by default) |
+and suffix |
+(specified by the $OBJSUFFIX construction variable; |
+\fB.obj\fP on Windows systems, |
+\fB.o\fP on POSIX systems) |
+are automatically added to the target if not already present. |
+Examples: |
+ |
+.ES |
+env.StaticObject(target = 'aaa', source = 'aaa.c') |
+env.StaticObject(target = 'bbb.o', source = 'bbb.c++') |
+env.StaticObject(target = 'ccc.obj', source = 'ccc.f') |
+.EE |
+.IP |
+Note that the source files will be scanned |
+according to the suffix mappings in |
+.B SourceFileScanner |
+object. |
+See the section "Scanner Objects," |
+below, for more information. |
+ |
+'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" |
+.IP Substfile() |
+.IP env.Substfile() |
+The \fBSubstfile\fP() builder generates a single text file |
+by concatenating the source files. |
+Nested lists of sources are flattened. |
+$LINESEPARATOR is used to separate the source files; |
+see the description of \fBTextfile\fP() for details. |
+ |
+If a single source file is present with an \fB.in\fP suffix, |
+the suffix is stripped and the remainder is used as the default target name. |
+ |
+The prefix and suffix specified by the $SUBSTFILEPREFIX |
+and $SUBSTFILESUFFIX construction variables |
+(the null string by default in both cases) |
+are automatically added to the target if they are not already present. |
+ |
+If a construction variable named $SUBST_DICT is present, |
+it may be either a Python dictionary or a sequence of (key,value) tuples. |
+If the former, |
+the dictionary is converted into a list of tuples in an arbitrary order, |
+so if one key is a prefix of another key |
+or if one substitution could be further expanded by another subsitition, |
+it is unpredictible whether the expansion will occur. |
+ |
+Any occurences in the source of a key |
+are replaced by the corresponding value, |
+which may be a Python callable function or a string. |
+If a value is a function, |
+it is first called (with no arguments) to produce a string. |
+The string is \fIsubst\fP-expanded |
+and the result replaces the key. |
+ |
+.ES |
+env = Environment(tools = ['default', 'textfile']) |
+ |
+env['prefix'] = '/usr/bin' |
+script_dict = {'@prefix@': '/bin', @exec_prefix@: '$prefix'} |
+env.Substfile('script.in', SUBST_DICT = script_dict) |
+ |
+conf_dict = {'%VERSION%': '1.2.3', '%BASE%': 'MyProg'} |
+env.Substfile('config.h.in', conf_dict, SUBST_DICT = conf_dict) |
+ |
+# UNPREDICTABLE - one key is a prefix of another |
+bad_foo = {'$foo': '$foo', '$foobar': '$foobar'} |
+env.Substfile('foo.in', SUBST_DICT = bad_foo) |
+ |
+# PREDICTABLE - keys are applied longest first |
+good_foo = [('$foobar', '$foobar'), ('$foo', '$foo')] |
+env.Substfile('foo.in', SUBST_DICT = good_foo) |
+ |
+# UNPREDICTABLE - one substitution could be futher expanded |
+bad_bar = {'@bar@': '@soap@', '@soap@': 'lye'} |
+env.Substfile('bar.in', SUBST_DICT = bad_bar) |
+ |
+# PREDICTABLE - substitutions are expanded in order |
+good_bar = (('@bar@', '@soap@'), ('@soap@', 'lye')) |
+env.Substfile('bar.in', SUBST_DICT = good_bar) |
+ |
+# the SUBST_DICT may be in common (and not an override) |
+substutions = {} |
+subst = Environment(tools = ['textfile', SUBST_DICT = substitutions) |
+substitutions['@foo@'] = 'foo' |
+subst['SUBST_DICT']['@bar@'] = 'bar' |
+subst.Substfile('pgm1.c', [Value('#include "@foo@.h"'), |
+ Value('#include "@bar@.h"'), |
+ "common.in", |
+ "pgm1.in" |
+ ]) |
+subst.Substfile('pgm2.c', [Value('#include "@foo@.h"'), |
+ Value('#include "@bar@.h"'), |
+ "common.in", |
+ "pgm2.in" |
+ ]) |
+ |
+.EE |
+ |
+'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" |
+.IP 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. |
+$LINESEPARATOR is used to separate the strings. |
+ |
+If present, the $SUBST_DICT construction variable |
+is used to modify the strings before they are written; |
+see the \fBSubstfile\fP() description for details. |
+ |
+The prefix and suffix specified by the $TEXTFILEPREFIX |
+and $TEXTFILESUFFIX construction variables |
+(the null string and \fB.txt\fP by default, respectively) |
+are automatically added to the target if they are not already present. |
+Examples: |
+ |
+.ES |
+# builds/writes foo.txt |
+env.Textfile(target = 'foo.txt', source = ['Goethe', 42, 'Schiller']) |
+ |
+# builds/writes bar.txt |
+env.Textfile(target = 'bar', |
+ source = ['lalala', 'tanteratei'], |
+ LINESEPARATOR='|*') |
+ |
+# nested lists are flattened automatically |
+env.Textfile(target = 'blob', |
+ source = ['lalala', ['Goethe', 42 'Schiller'], 'tanteratei']) |
+ |
+# files may be used as input by wraping them in File() |
+env.Textfile(target = 'concat', # concatenate files with a marker between |
+ source = [File('concat1'), File('concat2')], |
+ LINESEPARATOR = '====================\\n') |
+ |
+Results are: |
+foo.txt |
+ ....8<---- |
+ Goethe |
+ 42 |
+ Schiller |
+ ....8<---- (no linefeed at the end) |
+ |
+bar.txt: |
+ ....8<---- |
+ lalala|*tanteratei |
+ ....8<---- (no linefeed at the end) |
+ |
+blob.txt |
+ ....8<---- |
+ lalala |
+ Goethe |
+ 42 |
+ Schiller |
+ tanteratei |
+ ....8<---- (no linefeed at the end) |
+.EE |
+ |
+'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" |
+.IP 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 $QTDIR variable for more information. |
+Example: |
+ |
+.ES |
+env.Uic('foo.ui') # -> ['foo.h', 'uic_foo.cc', 'moc_foo.cc'] |
+env.Uic(target = Split('include/foo.h gen/uicfoo.cc gen/mocfoo.cc'), |
+ source = 'foo.ui') # -> ['include/foo.h', 'gen/uicfoo.cc', 'gen/mocfoo.cc'] |
+.EE |
+ |
+'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" |
+.IP 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: |
+ |
+'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" |
+.TP |
+.RI Action( action ", [" cmd/str/fun ", [" var ", ...]] [" option = value ", ...])" |
+.TP |
+.IR env .Action( action ", [" cmd/str/fun ", [" var ", ...]] [" option = value ", ...])" |
+Creates an Action object for |
+the specified |
+.IR action . |
+See the section "Action Objects," |
+below, for a complete explanation of the arguments and behavior. |
+ |
+Note that the |
+.BR env.Action () |
+form of the invocation will expand |
+construction variables in any argument strings, |
+including the |
+.I action |
+argument, at the time it is called |
+using the construction variables in the |
+.I env |
+construction environment through which |
+.BR env.Action () |
+was called. |
+The |
+.BR Action () |
+form delays all variable expansion |
+until the Action object is actually used. |
+ |
+'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" |
+.TP |
+.RI AddMethod( object, function ", [" name ]) |
+.TP |
+.RI env.AddMethod( function ", [" name ]) |
+When called with the |
+.BR AddMethod () |
+form, |
+adds the specified |
+.I function |
+to the specified |
+.I object |
+as the specified method |
+.IR name . |
+When called with the |
+.BR env.AddMethod () |
+form, |
+adds the specified |
+.I function |
+to the construction environment |
+.I env |
+as the specified method |
+.IR name . |
+In both cases, if |
+.I name |
+is omitted or |
+.BR None , |
+the name of the |
+specified |
+.I function |
+itself is used for the method name. |
+ |
+Examples: |
+ |
+.ES |
+# Note that the first argument to the function to |
+# be attached as a method must be the object through |
+# which the method will be called; the Python |
+# convention is to call it 'self'. |
+def my_method(self, arg): |
+ print "my_method() got", arg |
+ |
+# Use the global AddMethod() function to add a method |
+# to the Environment class. This |
+AddMethod(Environment, my_method) |
+env = Environment() |
+env.my_method('arg') |
+ |
+# Add the function as a method, using the function |
+# name for the method call. |
+env = Environment() |
+env.AddMethod(my_method, 'other_method_name') |
+env.other_method_name('another arg') |
+.EE |
+ |
+'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" |
+.TP |
+.RI AddOption( arguments ) |
+This function adds a new command-line option to be recognized. |
+The specified |
+.I arguments |
+are the same as supported by the standard Python |
+.BR optparse.add_option () |
+method (with a few additional capabilities noted below); |
+see the documentation for |
+.B optparse |
+for a thorough discussion of its option-processing capabities. |
+ |
+In addition to the arguments and values supported by the |
+.B optparse.add_option () |
+method, |
+the SCons |
+.BR AddOption () |
+function allows you to set the |
+.B nargs |
+keyword value to |
+.B '?' |
+(a string with just the question mark) |
+to indicate that the specified long option(s) take(s) an |
+.I optional |
+argument. |
+When |
+.B "nargs = '?'" |
+is passed to the |
+.BR AddOption () |
+function, the |
+.B const |
+keyword argument |
+may be used to supply the "default" |
+value that should be used when the |
+option is specified on the command line |
+without an explicit argument. |
+ |
+If no |
+.B default= |
+keyword argument is supplied when calling |
+.BR AddOption (), |
+the option will have a default value of |
+.BR None . |
+ |
+Once a new command-line option has been added with |
+.BR AddOption (), |
+the option value may be accessed using |
+.BR GetOption () |
+or |
+.BR env.GetOption (). |
+\" NOTE: in SCons 1.x or 2.0, user options will be settable, but not yet. |
+\" Uncomment this when that works. See tigris issue 2105. |
+\" The value may also be set, using |
+\" .BR SetOption () |
+\" or |
+\" .BR env.SetOption (), |
+\" if conditions in a |
+\" .B SConscript |
+\" require overriding any default value. |
+\" Note, however, that a |
+\" value specified on the command line will |
+\" .I always |
+\" override a value set by any SConscript file. |
+ |
+Any specified |
+.B help= |
+strings for the new option(s) |
+will be displayed by the |
+.B -H |
+or |
+.B -h |
+options |
+(the latter only if no other help text is |
+specified in the SConscript files). |
+The help text for the local options specified by |
+.BR AddOption () |
+will appear below the SCons options themselves, |
+under a separate |
+.B "Local Options" |
+heading. |
+The options will appear in the help text |
+in the order in which the |
+.BR AddOption () |
+calls occur. |
+ |
+Example: |
+ |
+.ES |
+AddOption('--prefix', |
+ dest='prefix', |
+ nargs=1, type='string', |
+ action='store', |
+ metavar='DIR', |
+ help='installation prefix') |
+env = Environment(PREFIX = GetOption('prefix')) |
+.EE |
+ |
+'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" |
+.TP |
+.RI AddPostAction( target ", " action ) |
+.TP |
+.RI env.AddPostAction( target ", " action ) |
+Arranges for the specified |
+.I action |
+to be performed |
+after the specified |
+.I target |
+has been built. |
+The specified action(s) may be |
+an Action object, or anything that |
+can be converted into an Action object |
+(see below). |
+ |
+When multiple targets are supplied, |
+the action may be called multiple times, |
+once after each action that generates |
+one or more targets in the list. |
+ |
+'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" |
+.TP |
+.RI AddPreAction( target ", " action ) |
+.TP |
+.RI env.AddPreAction( target ", " action ) |
+Arranges for the specified |
+.I action |
+to be performed |
+before the specified |
+.I target |
+is built. |
+The specified action(s) may be |
+an Action object, or anything that |
+can be converted into an Action object |
+(see below). |
+ |
+When multiple targets are specified, |
+the action(s) may be called multiple times, |
+once before each action that generates |
+one or more targets in the list. |
+ |
+Note that if any of the targets are built in multiple steps, |
+the action will be invoked just |
+before the "final" action that specifically |
+generates the specified target(s). |
+For example, when building an executable program |
+from a specified source |
+.B .c |
+file via an intermediate object file: |
+ |
+.ES |
+foo = Program('foo.c') |
+AddPreAction(foo, 'pre_action') |
+.EE |
+ |
+The specified |
+.B pre_action |
+would be executed before |
+.B scons |
+calls the link command that actually |
+generates the executable program binary |
+.BR foo , |
+not before compiling the |
+.B foo.c |
+file into an object file. |
+ |
+'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" |
+.TP |
+.RI Alias( alias ", [" targets ", [" action ]]) |
+.TP |
+.RI env.Alias( alias ", [" targets ", [" action ]]) |
+Creates one or more phony targets that |
+expand to one or more other targets. |
+An optional |
+.I action |
+(command) |
+or list of actions |
+can be specified that will be executed |
+whenever the any of the alias targets are out-of-date. |
+Returns the Node object representing the alias, |
+which exists outside of any file system. |
+This Node object, or the alias name, |
+may be used as a dependency of any other target, |
+including another alias. |
+.B Alias |
+can be called multiple times for the same |
+alias to add additional targets to the alias, |
+or additional actions to the list for this alias. |
+ |
+Examples: |
+ |
+.ES |
+Alias('install') |
+Alias('install', '/usr/bin') |
+Alias(['install', 'install-lib'], '/usr/local/lib') |
+ |
+env.Alias('install', ['/usr/local/bin', '/usr/local/lib']) |
+env.Alias('install', ['/usr/local/man']) |
+ |
+env.Alias('update', ['file1', 'file2'], "update_database $SOURCES") |
+.EE |
+ |
+'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" |
+.TP |
+.RI AllowSubstExceptions([ exception ", ...])" |
+Specifies the exceptions that will be allowed |
+when expanding construction variables. |
+By default, |
+any construction variable expansions that generate a |
+.B NameError |
+or |
+.BR IndexError |
+exception will expand to a |
+.B '' |
+(a null string) and not cause scons to fail. |
+All exceptions not in the specified list |
+will generate an error message |
+and terminate processing. |
+ |
+If |
+.B AllowSubstExceptions |
+is called multiple times, |
+each call completely overwrites the previous list |
+of allowed exceptions. |
+ |
+Example: |
+ |
+.ES |
+# Requires that all construction variable names exist. |
+# (You may wish to do this if you want to enforce strictly |
+# that all construction variables must be defined before use.) |
+AllowSubstExceptions() |
+ |
+# Also allow a string containing a zero-division expansion |
+# like '${1 / 0}' to evalute to ''. |
+AllowSubstExceptions(IndexError, NameError, ZeroDivisionError) |
+.EE |
+ |
+'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" |
+.TP |
+.RI AlwaysBuild( target ", ...)" |
+.TP |
+.RI env.AlwaysBuild( target ", ...)" |
+Marks each given |
+.I target |
+so that it is always assumed to be out of date, |
+and will always be rebuilt if needed. |
+Note, however, that |
+.BR AlwaysBuild () |
+does not add its target(s) to the default target list, |
+so the targets will only be built |
+if they are specified on the command line, |
+or are a dependent of a target specified on the command line--but |
+they will |
+.I always |
+be built if so specified. |
+Multiple targets can be passed in to a single call to |
+.BR AlwaysBuild (). |
+ |
+'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" |
+.TP |
+.RI env.Append( key = val ", [...])" |
+Appends the specified keyword arguments |
+to the end of construction variables in the environment. |
+If the Environment does not have |
+the specified construction variable, |
+it is simply added to the environment. |
+If the values of the construction variable |
+and the keyword argument are the same type, |
+then the two values will be simply added together. |
+Otherwise, the construction variable |
+and the value of the keyword argument |
+are both coerced to lists, |
+and the lists are added together. |
+(See also the Prepend method, below.) |
+ |
+Example: |
+ |
+.ES |
+env.Append(CCFLAGS = ' -g', FOO = ['foo.yyy']) |
+.EE |
+ |
+'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" |
+.TP |
+.RI env.AppendENVPath( name ", " newpath ", [" envname ", " sep ", " delete_existing ]) |
+This appends new path elements to the given path in the |
+specified external environment |
+.RB ( ENV |
+by default). |
+This will only add |
+any particular path once (leaving the last one it encounters and |
+ignoring the rest, to preserve path order), |
+and to help assure this, |
+will normalize all paths (using |
+.B os.path.normpath |
+and |
+.BR os.path.normcase ). |
+This can also handle the |
+case where the given old path variable is a list instead of a |
+string, in which case a list will be returned instead of a string. |
+ |
+If |
+.I delete_existing |
+is 0, then adding a path that already exists |
+will not move it to the end; it will stay where it is in the list. |
+ |
+Example: |
+ |
+.ES |
+print 'before:',env['ENV']['INCLUDE'] |
+include_path = '/foo/bar:/foo' |
+env.AppendENVPath('INCLUDE', include_path) |
+print 'after:',env['ENV']['INCLUDE'] |
+ |
+yields: |
+before: /foo:/biz |
+after: /biz:/foo/bar:/foo |
+.EE |
+ |
+'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" |
+.TP |
+.RI env.AppendUnique( key = val ", [...], delete_existing=0)" |
+Appends the specified keyword arguments |
+to the end of construction variables in the environment. |
+If the Environment does not have |
+the specified construction variable, |
+it is simply added to the environment. |
+If the construction variable being appended to is a list, |
+then any value(s) that already exist in the |
+construction variable will |
+.I not |
+be added again to the list. |
+However, if delete_existing is 1, |
+existing matching values are removed first, so |
+existing values in the arg list move to the end of the list. |
+ |
+Example: |
+ |
+.ES |
+env.AppendUnique(CCFLAGS = '-g', FOO = ['foo.yyy']) |
+.EE |
+ |
+'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" |
+.TP |
+env.BitKeeper() |
+A factory function that |
+returns a Builder object |
+to be used to fetch source files |
+using BitKeeper. |
+The returned Builder |
+is intended to be passed to the |
+.B SourceCode |
+function. |
+ |
+This function is deprecated. For details, see the entry for the |
+.B SourceCode |
+function. |
+ |
+Example: |
+ |
+.ES |
+env.SourceCode('.', env.BitKeeper()) |
+.EE |
+ |
+'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" |
+.TP |
+.RI BuildDir( build_dir ", " src_dir ", [" duplicate ]) |
+.TP |
+.RI env.BuildDir( build_dir ", " src_dir ", [" duplicate ]) |
+Deprecated synonyms for |
+.BR VariantDir () |
+and |
+.BR env.VariantDir (). |
+The |
+.I build_dir |
+argument becomes the |
+.I variant_dir |
+argument of |
+.BR VariantDir () |
+or |
+.BR env.VariantDir (). |
+ |
+'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" |
+.TP |
+.RI Builder( action ", [" arguments ]) |
+.TP |
+.RI env.Builder( action ", [" arguments ]) |
+Creates a Builder object for |
+the specified |
+.IR action . |
+See the section "Builder Objects," |
+below, for a complete explanation of the arguments and behavior. |
+ |
+Note that the |
+.BR env.Builder () |
+form of the invocation will expand |
+construction variables in any arguments strings, |
+including the |
+.I action |
+argument, |
+at the time it is called |
+using the construction variables in the |
+.B env |
+construction environment through which |
+.BR env.Builder () |
+was called. |
+The |
+.BR Builder () |
+form delays all variable expansion |
+until after the Builder object is actually called. |
+ |
+'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" |
+.TP |
+.RI CacheDir( cache_dir ) |
+.TP |
+.RI env.CacheDir( cache_dir ) |
+Specifies that |
+.B scons |
+will maintain a cache of derived files in |
+.I cache_dir . |
+The derived files in the cache will be shared |
+among all the builds using the same |
+.BR CacheDir () |
+call. |
+Specifying a |
+.I cache_dir |
+of |
+.B None |
+disables derived file caching. |
+ |
+Calling |
+.BR env.CacheDir () |
+will only affect targets built |
+through the specified construction environment. |
+Calling |
+.BR CacheDir () |
+sets a global default |
+that will be used by all targets built |
+through construction environments |
+that do |
+.I not |
+have an |
+.BR env.CacheDir () |
+specified. |
+ |
+When a |
+.BR CacheDir () |
+is being used and |
+.B scons |
+finds a derived file that needs to be rebuilt, |
+it will first look in the cache to see if a |
+derived file has already been built |
+from identical input files and an identical build action |
+(as incorporated into the MD5 build signature). |
+If so, |
+.B scons |
+will retrieve the file from the cache. |
+If the derived file is not present in the cache, |
+.B scons |
+will rebuild it and |
+then place a copy of the built file in the cache |
+(identified by its MD5 build signature), |
+so that it may be retrieved by other |
+builds that need to build the same derived file |
+from identical inputs. |
+ |
+Use of a specified |
+.BR CacheDir() |
+may be disabled for any invocation |
+by using the |
+.B --cache-disable |
+option. |
+ |
+If the |
+.B --cache-force |
+option is used, |
+.B scons |
+will place a copy of |
+.I all |
+derived files in the cache, |
+even if they already existed |
+and were not built by this invocation. |
+This is useful to populate a cache |
+the first time |
+.BR CacheDir () |
+is added to a build, |
+or after using the |
+.B --cache-disable |
+option. |
+ |
+When using |
+.BR CacheDir (), |
+.B scons |
+will report, |
+"Retrieved `file' from cache," |
+unless the |
+.B --cache-show |
+option is being used. |
+When the |
+.B --cache-show |
+option is used, |
+.B scons |
+will print the action that |
+.I would |
+have been used to build the file, |
+without any indication that |
+the file was actually retrieved from the cache. |
+This is useful to generate build logs |
+that are equivalent regardless of whether |
+a given derived file has been built in-place |
+or retrieved from the cache. |
+ |
+The |
+.BR NoCache () |
+method can be used to disable caching of specific files. This can be |
+useful if inputs and/or outputs of some tool are impossible to |
+predict or prohibitively large. |
+ |
+'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" |
+.TP |
+.RI Clean( targets ", " files_or_dirs ) |
+.TP |
+.RI env.Clean( targets ", " files_or_dirs ) |
+This specifies a list of files or directories which should be removed |
+whenever the targets are specified with the |
+.B -c |
+command line option. |
+The specified targets may be a list |
+or an individual target. |
+Multiple calls to |
+.BR Clean () |
+are legal, |
+and create new targets or add files and directories to the |
+clean list for the specified targets. |
+ |
+Multiple files or directories should be specified |
+either as separate arguments to the |
+.BR Clean () |
+method, or as a list. |
+.BR Clean () |
+will also accept the return value of any of the construction environment |
+Builder methods. |
+Examples: |
+ |
+The related |
+.BR NoClean () |
+function overrides calling |
+.BR Clean () |
+for the same target, |
+and any targets passed to both functions will |
+.I not |
+be removed by the |
+.B -c |
+option. |
+ |
+Examples: |
+ |
+.ES |
+Clean('foo', ['bar', 'baz']) |
+Clean('dist', env.Program('hello', 'hello.c')) |
+Clean(['foo', 'bar'], 'something_else_to_clean') |
+.EE |
+ |
+In this example, |
+installing the project creates a subdirectory for the documentation. |
+This statement causes the subdirectory to be removed |
+if the project is deinstalled. |
+.ES |
+Clean(docdir, os.path.join(docdir, projectname)) |
+.EE |
+ |
+'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" |
+.TP |
+.RI Command( target ", " source ", " action ", [" key = val ", ...])" |
+.TP |
+.RI env.Command( target ", " source ", " action ", [" key = val ", ...])" |
+Executes a specific action |
+(or list of actions) |
+to build a target file or files. |
+This is more convenient |
+than defining a separate Builder object |
+for a single special-case build. |
+ |
+As a special case, the |
+.B source_scanner |
+keyword argument can |
+be used to specify |
+a Scanner object |
+that will be used to scan the sources. |
+(The global |
+.B DirScanner |
+object can be used |
+if any of the sources will be directories |
+that must be scanned on-disk for |
+changes to files that aren't |
+already specified in other Builder of function calls.) |
+ |
+Any other keyword arguments specified override any |
+same-named existing construction variables. |
+ |
+An action can be an external command, |
+specified as a string, |
+or a callable Python object; |
+see "Action Objects," below, |
+for more complete information. |
+Also note that a string specifying an external command |
+may be preceded by an |
+.B @ |
+(at-sign) |
+to suppress printing the command in question, |
+or by a |
+.B \- |
+(hyphen) |
+to ignore the exit status of the external command. |
+ |
+Examples: |
+ |
+.ES |
+env.Command('foo.out', 'foo.in', |
+ "$FOO_BUILD < $SOURCES > $TARGET") |
+ |
+env.Command('bar.out', 'bar.in', |
+ ["rm -f $TARGET", |
+ "$BAR_BUILD < $SOURCES > $TARGET"], |
+ ENV = {'PATH' : '/usr/local/bin/'}) |
+ |
+def rename(env, target, source): |
+ import os |
+ os.rename('.tmp', str(target[0])) |
+ |
+env.Command('baz.out', 'baz.in', |
+ ["$BAZ_BUILD < $SOURCES > .tmp", |
+ rename ]) |
+.EE |
+ |
+.IP |
+Note that the |
+.BR Command () |
+function will usually assume, by default, |
+that the specified targets and/or sources are Files, |
+if no other part of the configuration |
+identifies what type of entry it is. |
+If necessary, you can explicitly specify |
+that targets or source nodes should |
+be treated as directoriese |
+by using the |
+.BR Dir () |
+or |
+.BR env.Dir () |
+functions. |
+ |
+Examples: |
+ |
+.ES |
+env.Command('ddd.list', Dir('ddd'), 'ls -l $SOURCE > $TARGET') |
+ |
+env['DISTDIR'] = 'destination/directory' |
+env.Command(env.Dir('$DISTDIR')), None, make_distdir) |
+.EE |
+ |
+.IP |
+(Also note that SCons will usually |
+automatically create any directory necessary to hold a target file, |
+so you normally don't need to create directories by hand.) |
+ |
+'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" |
+.TP |
+.RI Configure( env ", [" custom_tests ", " conf_dir ", " log_file ", " config_h ]) |
+.TP |
+.RI env.Configure([ custom_tests ", " conf_dir ", " log_file ", " config_h ]) |
+Creates a Configure object for integrated |
+functionality similar to GNU autoconf. |
+See the section "Configure Contexts," |
+below, for a complete explanation of the arguments and behavior. |
+ |
+'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" |
+.TP |
+.RI env.Clone([ key = val ", ...])" |
+Return a separate copy of a construction environment. |
+If there are any keyword arguments specified, |
+they are added to the returned copy, |
+overwriting any existing values |
+for the keywords. |
+ |
+Example: |
+ |
+.ES |
+env2 = env.Clone() |
+env3 = env.Clone(CCFLAGS = '-g') |
+.EE |
+.IP |
+Additionally, a list of tools and a toolpath may be specified, as in |
+the Environment constructor: |
+ |
+.ES |
+def MyTool(env): env['FOO'] = 'bar' |
+env4 = env.Clone(tools = ['msvc', MyTool]) |
+.EE |
+ |
+The |
+.I parse_flags |
+keyword argument is also recognized: |
+ |
+.ES |
+# create an environment for compiling programs that use wxWidgets |
+wx_env = env.Clone(parse_flags = '!wx-config --cflags --cxxflags') |
+.EE |
+ |
+'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" |
+.TP |
+.RI env.Copy([ key = val ", ...])" |
+A now-deprecated synonym for |
+.BR env.Clone() . |
+ |
+'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" |
+.TP |
+.RI env.CVS( repository ", " module ) |
+A factory function that |
+returns a Builder object |
+to be used to fetch source files |
+from the specified |
+CVS |
+.IR repository . |
+The returned Builder |
+is intended to be passed to the |
+.B SourceCode |
+function. |
+ |
+The optional specified |
+.I module |
+will be added to the beginning |
+of all repository path names; |
+this can be used, in essence, |
+to strip initial directory names |
+from the repository path names, |
+so that you only have to |
+replicate part of the repository |
+directory hierarchy in your |
+local build directory. |
+ |
+This function is deprecated. For details, see the entry for the |
+.B SourceCode |
+function. |
+ |
+Examples: |
+ |
+.ES |
+# Will fetch foo/bar/src.c |
+# from /usr/local/CVSROOT/foo/bar/src.c. |
+env.SourceCode('.', env.CVS('/usr/local/CVSROOT')) |
+ |
+# Will fetch bar/src.c |
+# from /usr/local/CVSROOT/foo/bar/src.c. |
+env.SourceCode('.', env.CVS('/usr/local/CVSROOT', 'foo')) |
+ |
+# Will fetch src.c |
+# from /usr/local/CVSROOT/foo/bar/src.c. |
+env.SourceCode('.', env.CVS('/usr/local/CVSROOT', 'foo/bar')) |
+.EE |
+ |
+'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" |
+.TP |
+.RI Decider( function ) |
+.TP |
+.RI env.Decider( function ) |
+Specifies that all up-to-date decisions for |
+targets built through this construction environment |
+will be handled by the specified |
+.IR function . |
+The |
+.I function |
+can be one of the following strings |
+that specify the type of decision function |
+to be performed: |
+ |
+.RS 10 |
+.HP 6 |
+.B timestamp-newer |
+Specifies that a target shall be considered out of date and rebuilt |
+if the dependency's timestamp is newer than the target file's timestamp. |
+This is the behavior of the classic Make utility, |
+and |
+.B make |
+can be used a synonym for |
+.BR timestamp-newer . |
+ |
+.HP 6 |
+.B timestamp-match |
+Specifies that a target shall be considered out of date and rebuilt |
+if the dependency's timestamp is different than the |
+timestamp recorded the last time the target was built. |
+This provides behavior very similar to the classic Make utility |
+(in particular, files are not opened up so that their |
+contents can be checksummed) |
+except that the target will also be rebuilt if a |
+dependency file has been restored to a version with an |
+.I earlier |
+timestamp, such as can happen when restoring files from backup archives. |
+ |
+.HP 6 |
+.B MD5 |
+Specifies that a target shall be considered out of date and rebuilt |
+if the dependency's content has changed sine the last time |
+the target was built, |
+as determined be performing an MD5 checksum |
+on the dependency's contents |
+and comparing it to the checksum recorded the |
+last time the target was built. |
+.B content |
+can be used as a synonym for |
+.BR MD5 . |
+ |
+.HP 6 |
+.B MD5-timestamp |
+Specifies that a target shall be considered out of date and rebuilt |
+if the dependency's content has changed sine the last time |
+the target was built, |
+except that dependencies with a timestamp that matches |
+the last time the target was rebuilt will be |
+assumed to be up-to-date and |
+.I not |
+rebuilt. |
+This provides behavior very similar |
+to the |
+.B MD5 |
+behavior of always checksumming file contents, |
+with an optimization of not checking |
+the contents of files whose timestamps haven't changed. |
+The drawback is that SCons will |
+.I not |
+detect if a file's content has changed |
+but its timestamp is the same, |
+as might happen in an automated script |
+that runs a build, |
+updates a file, |
+and runs the build again, |
+all within a single second. |
+.RE |
+ |
+.IP |
+Examples: |
+ |
+.ES |
+# Use exact timestamp matches by default. |
+Decider('timestamp-match') |
+ |
+# Use MD5 content signatures for any targets built |
+# with the attached construction environment. |
+env.Decider('content') |
+.EE |
+ |
+.IP |
+In addition to the above already-available functions, |
+the |
+.I function |
+argument may be an actual Python function |
+that takes the following three arguments: |
+ |
+.RS 10 |
+.IP dependency |
+The Node (file) which |
+should cause the |
+.I target |
+to be rebuilt |
+if it has "changed" since the last tme |
+.I target was built. |
+ |
+.IP target |
+The Node (file) being built. |
+In the normal case, |
+this is what should get rebuilt |
+if the |
+.I dependency |
+has "changed." |
+ |
+.IP prev_ni |
+Stored information about the state of the |
+.I dependency |
+the last time the |
+.I target |
+was built. |
+This can be consulted to match various |
+file characteristics |
+such as the timestamp, |
+size, or content signature. |
+.RE |
+ |
+.IP |
+The |
+.I function |
+should return a |
+.B True |
+(non-zero) |
+value if the |
+.I dependency |
+has "changed" since the last time |
+the |
+.I target |
+was built |
+(indicating that the target |
+.I should |
+be rebuilt), |
+and |
+.B False |
+(zero) |
+otherwise |
+(indicating that the target should |
+.I not |
+be rebuilt). |
+Note that the decision can be made |
+using whatever criteria are appopriate. |
+Ignoring some or all of the function arguments |
+is perfectly normal. |
+ |
+Example: |
+ |
+.ES |
+def my_decider(dependency, target, prev_ni): |
+ return not os.path.exists(str(target)) |
+ |
+env.Decider(my_decider) |
+.EE |
+ |
+'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" |
+.TP |
+.RI Default( targets ) |
+.TP |
+.RI env.Default( targets ) |
+This specifies a list of default targets, |
+which will be built by |
+.B scons |
+if no explicit targets are given on the command line. |
+Multiple calls to |
+.BR Default () |
+are legal, |
+and add to the list of default targets. |
+ |
+Multiple targets should be specified as |
+separate arguments to the |
+.BR Default () |
+method, or as a list. |
+.BR Default () |
+will also accept the Node returned by any |
+of a construction environment's |
+builder methods. |
+ |
+Examples: |
+ |
+.ES |
+Default('foo', 'bar', 'baz') |
+env.Default(['a', 'b', 'c']) |
+hello = env.Program('hello', 'hello.c') |
+env.Default(hello) |
+.EE |
+.IP |
+An argument to |
+.BR Default () |
+of |
+.B None |
+will clear all default targets. |
+Later calls to |
+.BR Default () |
+will add to the (now empty) default-target list |
+like normal. |
+ |
+The current list of targets added using the |
+.BR Default () |
+function or method is available in the |
+.B DEFAULT_TARGETS |
+list; |
+see below. |
+ |
+'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" |
+.TP |
+.RI DefaultEnvironment([ args ]) |
+Creates and returns a default construction environment object. |
+This construction environment is used internally by SCons |
+in order to execute many of the global functions in this list, |
+and to fetch source files transparently |
+from source code management systems. |
+ |
+'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" |
+.TP |
+.RI Depends( target ", " dependency ) |
+.TP |
+.RI env.Depends( target ", " dependency ) |
+Specifies an explicit dependency; |
+the |
+.I target |
+will be rebuilt |
+whenever the |
+.I dependency |
+has changed. |
+Both the specified |
+.I target |
+and |
+.I dependency |
+can be a string |
+(usually the path name of a file or directory) |
+or Node objects, |
+or a list of strings or Node objects |
+(such as returned by a Builder call). |
+This should only be necessary |
+for cases where the dependency |
+is not caught by a Scanner |
+for the file. |
+ |
+Example: |
+ |
+.ES |
+env.Depends('foo', 'other-input-file-for-foo') |
+ |
+mylib = env.Library('mylib.c') |
+installed_lib = env.Install('lib', mylib) |
+bar = env.Program('bar.c') |
+ |
+# Arrange for the library to be copied into the installation |
+# directory before trying to build the "bar" program. |
+# (Note that this is for example only. A "real" library |
+# dependency would normally be configured through the $LIBS |
+# and $LIBPATH variables, not using an env.Depends() call.) |
+ |
+env.Depends(bar, installed_lib) |
+.EE |
+ |
+'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" |
+.TP |
+.RI env.Dictionary([ vars ]) |
+Returns a dictionary object |
+containing copies of all of the |
+construction variables in the environment. |
+If there are any variable names specified, |
+only the specified construction |
+variables are returned in the dictionary. |
+ |
+Example: |
+ |
+.ES |
+dict = env.Dictionary() |
+cc_dict = env.Dictionary('CC', 'CCFLAGS', 'CCCOM') |
+.EE |
+ |
+'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" |
+.TP |
+.RI Dir( name ", [" directory ]) |
+.TP |
+.RI env.Dir( name ", [" directory ]) |
+This returns a Directory Node, |
+an object that represents the specified directory |
+.IR name . |
+.I name |
+can be a relative or absolute path. |
+.I directory |
+is an optional directory that will be used as the parent directory. |
+If no |
+.I directory |
+is specified, the current script's directory is used as the parent. |
+ |
+If |
+.I name |
+is a list, SCons returns a list of Dir nodes. |
+Construction variables are expanded in |
+.IR name . |
+ |
+Directory Nodes can be used anywhere you |
+would supply a string as a directory name |
+to a Builder method or function. |
+Directory Nodes have attributes and methods |
+that are useful in many situations; |
+see "File and Directory Nodes," below. |
+ |
+'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" |
+.TP |
+.RI env.Dump([ key ]) |
+Returns a pretty printable representation of the environment. |
+.IR key , |
+if not |
+.IR None , |
+should be a string containing the name of the variable of interest. |
+ |
+This SConstruct: |
+.ES |
+env=Environment() |
+print env.Dump('CCCOM') |
+.EE |
+.IP |
+will print: |
+.ES |
+\&'$CC -c -o $TARGET $CCFLAGS $CPPFLAGS $_CPPDEFFLAGS $_CPPINCFLAGS $SOURCES' |
+.EE |
+ |
+.ES |
+env=Environment() |
+print env.Dump() |
+.EE |
+.IP |
+will print: |
+.ES |
+{ 'AR': 'ar', |
+ 'ARCOM': '$AR $ARFLAGS $TARGET $SOURCES\n$RANLIB $RANLIBFLAGS $TARGET', |
+ 'ARFLAGS': ['r'], |
+ 'AS': 'as', |
+ 'ASCOM': '$AS $ASFLAGS -o $TARGET $SOURCES', |
+ 'ASFLAGS': [], |
+ ... |
+.EE |
+ |
+'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" |
+.TP |
+.RI EnsurePythonVersion( major ", " minor ) |
+.TP |
+.RI env.EnsurePythonVersion( major ", " minor ) |
+Ensure that the Python version is at least |
+.IR major . minor . |
+This function will |
+print out an error message and exit SCons with a non-zero exit code if the |
+actual Python version is not late enough. |
+ |
+Example: |
+ |
+.ES |
+EnsurePythonVersion(2,2) |
+.EE |
+ |
+'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" |
+.TP |
+.RI EnsureSConsVersion( major ", " minor ", [" revision ]) |
+.TP |
+.RI env.EnsureSConsVersion( major ", " minor ", [" revision ]) |
+Ensure that the SCons version is at least |
+.IR major.minor , |
+or |
+.IR major.minor.revision . |
+if |
+.I revision |
+is specified. |
+This function will |
+print out an error message and exit SCons with a non-zero exit code if the |
+actual SCons version is not late enough. |
+ |
+Examples: |
+ |
+.ES |
+EnsureSConsVersion(0,14) |
+ |
+EnsureSConsVersion(0,96,90) |
+.EE |
+ |
+'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" |
+.TP |
+.RI Environment([ key = value ", ...])" |
+.TP |
+.RI env.Environment([ key = value ", ...])" |
+Return a new construction environment |
+initialized with the specified |
+.IR key = value |
+pairs. |
+ |
+'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" |
+.TP |
+.RI Execute( action ", [" strfunction ", " varlist ]) |
+.TP |
+.RI env.Execute( action ", [" strfunction ", " varlist ]) |
+Executes an Action object. |
+The specified |
+.IR action |
+may be an Action object |
+(see the section "Action Objects," |
+below, for a complete explanation of the arguments and behavior), |
+or it may be a command-line string, |
+list of commands, |
+or executable Python function, |
+each of which will be converted |
+into an Action object |
+and then executed. |
+The exit value of the command |
+or return value of the Python function |
+will be returned. |
+ |
+Note that |
+.B scons |
+will print an error message if the executed |
+.I action |
+fails--that is, |
+exits with or returns a non-zero value. |
+.B scons |
+will |
+.I not , |
+however, |
+automatically terminate the build |
+if the specified |
+.I action |
+fails. |
+If you want the build to stop in response to a failed |
+.BR Execute () |
+call, |
+you must explicitly check for a non-zero return value: |
+ |
+.ES |
+Execute(Copy('file.out', 'file.in')) |
+ |
+if Execute("mkdir sub/dir/ectory"): |
+ # The mkdir failed, don't try to build. |
+ Exit(1) |
+.EE |
+ |
+'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" |
+.TP |
+.RI Exit([ value ]) |
+.TP |
+.RI env.Exit([ value ]) |
+This tells |
+.B scons |
+to exit immediately |
+with the specified |
+.IR value . |
+A default exit value of |
+.B 0 |
+(zero) |
+is used if no value is specified. |
+ |
+'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" |
+.TP |
+.RI Export( vars ) |
+.TP |
+.RI env.Export( vars ) |
+This tells |
+.B scons |
+to export a list of variables from the current |
+SConscript file to all other SConscript files. |
+The exported variables are kept in a global collection, |
+so subsequent calls to |
+.BR Export () |
+will over-write previous exports that have the same name. |
+Multiple variable names can be passed to |
+.BR Export () |
+as separate arguments or as a list. |
+Keyword arguments can be used to provide names and their values. |
+A dictionary can be used to map variables to a different name when exported. |
+Both local variables and global variables can be exported. |
+ |
+Examples: |
+ |
+.ES |
+env = Environment() |
+# Make env available for all SConscript files to Import(). |
+Export("env") |
+ |
+package = 'my_name' |
+# Make env and package available for all SConscript files:. |
+Export("env", "package") |
+ |
+# Make env and package available for all SConscript files: |
+Export(["env", "package"]) |
+ |
+# Make env available using the name debug: |
+Export(debug = env) |
+ |
+# Make env available using the name debug: |
+Export({"debug":env}) |
+.EE |
+ |
+.IP |
+Note that the |
+.BR SConscript () |
+function supports an |
+.I exports |
+argument that makes it easier to to export a variable or |
+set of variables to a single SConscript file. |
+See the description of the |
+.BR SConscript () |
+function, below. |
+ |
+'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" |
+.TP |
+.RI File( name ", [" directory ]) |
+.TP |
+.RI env.File( name ", [" directory ]) |
+This returns a |
+File Node, |
+an object that represents the specified file |
+.IR name . |
+.I name |
+can be a relative or absolute path. |
+.I directory |
+is an optional directory that will be used as the parent directory. |
+ |
+If |
+.I name |
+is a list, SCons returns a list of File nodes. |
+Construction variables are expanded in |
+.IR name . |
+ |
+File Nodes can be used anywhere you |
+would supply a string as a file name |
+to a Builder method or function. |
+File Nodes have attributes and methods |
+that are useful in many situations; |
+see "File and Directory Nodes," below. |
+ |
+'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" |
+.TP |
+.RI FindFile( file ", " dirs ) |
+.TP |
+.RI env.FindFile( file ", " dirs ) |
+Search for |
+.I file |
+in the path specified by |
+.IR dirs . |
+.I dirs |
+may be a list of directory names or a single directory name. |
+In addition to searching for files that exist in the 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 |
+.RI env.FindInstalledFiles( ) |
+Returns the list of targets set up by the |
+.B Install() |
+or |
+.B InstallAs() |
+builders. |
+ |
+This function serves as a convenient method to select the contents of |
+a binary package. |
+ |
+Example: |
+ |
+.ES |
+Install( '/bin', [ 'executable_a', 'executable_b' ] ) |
+ |
+# will return the file node list |
+# [ '/bin/executable_a', '/bin/executable_b' ] |
+FindInstalledFiles() |
+ |
+Install( '/lib', [ 'some_library' ] ) |
+ |
+# will return the file node list |
+# [ '/bin/executable_a', '/bin/executable_b', '/lib/some_library' ] |
+FindInstalledFiles() |
+.EE |
+ |
+'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" |
+.TP |
+.RI FindSourceFiles( node = '"."' ) |
+.TP |
+.RI env.FindSourceFiles( node = '"."' ) |
+ |
+Returns the list of nodes which serve as the source of the built files. |
+It does so by inspecting the dependency tree starting at the optional |
+argument |
+.B node |
+which defaults to the '"."'-node. It will then return all leaves of |
+.B node. |
+These are all children which have no further children. |
+ |
+This function is a convenient method to select the contents of a Source |
+Package. |
+ |
+Example: |
+ |
+.ES |
+Program( 'src/main_a.c' ) |
+Program( 'src/main_b.c' ) |
+Program( 'main_c.c' ) |
+ |
+# returns ['main_c.c', 'src/main_a.c', 'SConstruct', 'src/main_b.c'] |
+FindSourceFiles() |
+ |
+# returns ['src/main_b.c', 'src/main_a.c' ] |
+FindSourceFiles( 'src' ) |
+.EE |
+ |
+.IP |
+As you can see build support files (SConstruct in the above example) |
+will also be returned by this function. |
+ |
+'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" |
+.TP |
+.RI FindPathDirs( variable ) |
+Returns a function |
+(actually a callable Python object) |
+intended to be used as the |
+.B path_function |
+of a Scanner object. |
+The returned object will look up the specified |
+.I variable |
+in a construction environment |
+and treat the construction variable's value as a list of |
+directory paths that should be searched |
+(like |
+.BR CPPPATH , |
+.BR LIBPATH , |
+etc.). |
+ |
+Note that use of |
+.BR FindPathDirs () |
+is generally preferable to |
+writing your own |
+.B path_function |
+for the following reasons: |
+1) The returned list will contain all appropriate directories |
+found in source trees |
+(when |
+.BR VariantDir () |
+is used) |
+or in code repositories |
+(when |
+.BR Repository () |
+or the |
+.B \-Y |
+option are used). |
+2) scons will identify expansions of |
+.I variable |
+that evaluate to the same list of directories as, |
+in fact, the same list, |
+and avoid re-scanning the directories for files, |
+when possible. |
+ |
+Example: |
+ |
+.ES |
+def my_scan(node, env, path, arg): |
+ # Code to scan file contents goes here... |
+ return include_files |
+ |
+scanner = Scanner(name = 'myscanner', |
+ function = my_scan, |
+ path_function = FindPathDirs('MYPATH')) |
+.EE |
+ |
+'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" |
+.TP |
+.RI Flatten( sequence ) |
+.TP |
+.RI env.Flatten( sequence ) |
+Takes a sequence (that is, a Python list or tuple) |
+that may contain nested sequences |
+and returns a flattened list containing |
+all of the individual elements in any sequence. |
+This can be helpful for collecting |
+the lists returned by calls to Builders; |
+other Builders will automatically |
+flatten lists specified as input, |
+but direct Python manipulation of |
+these lists does not. |
+ |
+Examples: |
+ |
+.ES |
+foo = Object('foo.c') |
+bar = Object('bar.c') |
+ |
+# Because `foo' and `bar' are lists returned by the Object() Builder, |
+# `objects' will be a list containing nested lists: |
+objects = ['f1.o', foo, 'f2.o', bar, 'f3.o'] |
+ |
+# Passing such a list to another Builder is all right because |
+# the Builder will flatten the list automatically: |
+Program(source = objects) |
+ |
+# If you need to manipulate the list directly using Python, you need to |
+# call Flatten() yourself, or otherwise handle nested lists: |
+for object in Flatten(objects): |
+ print str(object) |
+.EE |
+ |
+'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" |
+.TP |
+.RI GetBuildFailures() |
+Returns a list of exceptions for the |
+actions that failed while |
+attempting to build targets. |
+Each element in the returned list is a |
+.B BuildError |
+object |
+with the following attributes |
+that record various aspects |
+of the build failure: |
+ |
+.B .node |
+The node that was being built |
+when the build failure occurred. |
+ |
+.B .status |
+The numeric exit status |
+returned by the command or Python function |
+that failed when trying to build the |
+specified Node. |
+ |
+.B .errstr |
+The SCons error string |
+describing the build failure. |
+(This is often a generic |
+message like "Error 2" |
+to indicate that an executed |
+command exited with a status of 2.) |
+ |
+.B .filename |
+The name of the file or |
+directory that actually caused the failure. |
+This may be different from the |
+.B .node |
+attribute. |
+For example, |
+if an attempt to build a target named |
+.B sub/dir/target |
+fails because the |
+.B sub/dir |
+directory could not be created, |
+then the |
+.B .node |
+attribute will be |
+.B sub/dir/target |
+but the |
+.B .filename |
+attribute will be |
+.BR sub/dir . |
+ |
+.B .executor |
+The SCons Executor object |
+for the target Node |
+being built. |
+This can be used to retrieve |
+the construction environment used |
+for the failed action. |
+ |
+.B .action |
+The actual SCons Action object that failed. |
+This will be one specific action |
+out of the possible list of |
+actions that would have been |
+executed to build the target. |
+ |
+.B .command |
+The actual expanded command that was executed and failed, |
+after expansion of |
+.BR $TARGET , |
+.BR $SOURCE , |
+and other construction variables. |
+ |
+Note that the |
+.BR GetBuildFailures () |
+function |
+will always return an empty list |
+until any build failure has occurred, |
+which means that |
+.BR GetBuildFailures () |
+will always return an empty list |
+while the |
+.B SConscript |
+files are being read. |
+Its primary intended use is |
+for functions that will be |
+executed before SCons exits |
+by passing them to the |
+standard Python |
+.BR atexit.register () |
+function. |
+Example: |
+ |
+.ES |
+import atexit |
+ |
+def print_build_failures(): |
+ from SCons.Script import GetBuildFailures |
+ for bf in GetBuildFailures(): |
+ print "%s failed: %s" % (bf.node, bf.errstr) |
+ |
+atexit.register(print_build_failures) |
+.EE |
+ |
+'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" |
+.TP |
+.RI GetBuildPath( file ", [" ... ]) |
+.TP |
+.RI env.GetBuildPath( file ", [" ... ]) |
+Returns the |
+.B scons |
+path name (or names) for the specified |
+.I file |
+(or files). |
+The specified |
+.I file |
+or files |
+may be |
+.B scons |
+Nodes or strings representing path names. |
+ |
+'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" |
+.TP |
+.RI GetLaunchDir() |
+.TP |
+.RI env.GetLaunchDir() |
+Returns the absolute path name of the directory from which |
+.B scons |
+was initially invoked. |
+This can be useful when using the |
+.BR \-u , |
+.BR \-U |
+or |
+.BR \-D |
+options, which internally |
+change to the directory in which the |
+.B SConstruct |
+file is found. |
+ |
+'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" |
+.TP |
+.RI GetOption( name ) |
+.TP |
+.RI env.GetOption( name ) |
+This function provides a way to query the value of |
+SCons options set on scons command line |
+(or set using the |
+.IR SetOption () |
+function). |
+The options supported are: |
+ |
+.RS 10 |
+.TP 6 |
+.B cache_debug |
+which corresponds to --cache-debug; |
+.TP 6 |
+.B cache_disable |
+which corresponds to --cache-disable; |
+.TP 6 |
+.B cache_force |
+which corresponds to --cache-force; |
+.TP 6 |
+.B cache_show |
+which corresponds to --cache-show; |
+.TP 6 |
+.B clean |
+which corresponds to -c, --clean and --remove; |
+.TP 6 |
+.B config |
+which corresponds to --config; |
+.TP 6 |
+.B directory |
+which corresponds to -C and --directory; |
+.TP 6 |
+.B diskcheck |
+which corresponds to --diskcheck |
+.TP 6 |
+.B duplicate |
+which corresponds to --duplicate; |
+.TP 6 |
+.B file |
+which corresponds to -f, --file, --makefile and --sconstruct; |
+.TP 6 |
+.B help |
+which corresponds to -h and --help; |
+.TP 6 |
+.B ignore_errors |
+which corresponds to --ignore-errors; |
+.TP 6 |
+.B implicit_cache |
+which corresponds to --implicit-cache; |
+.TP 6 |
+.B implicit_deps_changed |
+which corresponds to --implicit-deps-changed; |
+.TP 6 |
+.B implicit_deps_unchanged |
+which corresponds to --implicit-deps-unchanged; |
+.TP 6 |
+.B interactive |
+which corresponds to --interact and --interactive; |
+.TP 6 |
+.B keep_going |
+which corresponds to -k and --keep-going; |
+.TP 6 |
+.B max_drift |
+which corresponds to --max-drift; |
+.TP 6 |
+.B no_exec |
+which corresponds to -n, --no-exec, --just-print, --dry-run and --recon; |
+.TP 6 |
+.B no_site_dir |
+which corresponds to --no-site-dir; |
+.TP 6 |
+.B num_jobs |
+which corresponds to -j and --jobs; |
+.TP 6 |
+.B profile_file |
+which corresponds to --profile; |
+.TP 6 |
+.B question |
+which corresponds to -q and --question; |
+.TP 6 |
+.B random |
+which corresponds to --random; |
+.TP 6 |
+.B repository |
+which corresponds to -Y, --repository and --srcdir; |
+.TP 6 |
+.B silent |
+which corresponds to -s, --silent and --quiet; |
+.TP 6 |
+.B site_dir |
+which corresponds to --site-dir; |
+.TP 6 |
+.B stack_size |
+which corresponds to --stack-size; |
+.TP 6 |
+.B taskmastertrace_file |
+which corresponds to --taskmastertrace; and |
+.TP 6 |
+.B warn |
+which corresponds to --warn and --warning. |
+.RE |
+ |
+.IP |
+See the documentation for the |
+corresponding command line object for information about each specific |
+option. |
+ |
+'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" |
+.TP |
+.RI Glob( pattern ", [" ondisk ", " source ", " strings ]) |
+.TP |
+.RI env.Glob( pattern ", [" ondisk ", " source ", " strings ]) |
+Returns Nodes (or strings) that match the specified |
+.IR pattern , |
+relative to the directory of the current |
+.B SConscript |
+file. |
+The |
+.BR env.Glob () |
+form performs string substition on |
+.I pattern |
+and returns whatever matches |
+the resulting expanded pattern. |
+ |
+The specified |
+.I pattern |
+uses Unix shell style metacharacters for matching: |
+ |
+.ES |
+ * matches everything |
+ ? matches any single character |
+ [seq] matches any character in seq |
+ [!seq] matches any char not in seq |
+.EE |
+ |
+.IP |
+If the first character of a filename is a dot, |
+it must be matched explicitly. |
+Character matches do |
+.I not |
+span directory separators. |
+ |
+The |
+.BR Glob () |
+knows about |
+repositories |
+(see the |
+.BR Repository () |
+function) |
+and source directories |
+(see the |
+.BR VariantDir () |
+function) |
+and |
+returns a Node (or string, if so configured) |
+in the local (SConscript) directory |
+if matching Node is found |
+anywhere in a corresponding |
+repository or source directory. |
+ |
+The |
+.B ondisk |
+argument may be set to |
+.B False |
+(or any other non-true value) |
+to disable the search for matches on disk, |
+thereby only returning matches among |
+already-configured File or Dir Nodes. |
+The default behavior is to |
+return corresponding Nodes |
+for any on-disk matches found. |
+ |
+The |
+.B source |
+argument may be set to |
+.B True |
+(or any equivalent value) |
+to specify that, |
+when the local directory is a |
+.BR VariantDir (), |
+the returned Nodes should be from the |
+corresponding source directory, |
+not the local directory. |
+ |
+The |
+.B strings |
+argument may be set to |
+.B True |
+(or any equivalent value) |
+to have the |
+.BR Glob () |
+function return strings, not Nodes, |
+that represent the matched files or directories. |
+The returned strings will be relative to |
+the local (SConscript) directory. |
+(Note that This may make it easier to perform |
+arbitrary manipulation of file names, |
+but if the returned strings are |
+passed to a different |
+.B SConscript |
+file, |
+any Node translation will be relative |
+to the other |
+.B SConscript |
+directory, |
+not the original |
+.B SConscript |
+directory.) |
+ |
+Examples: |
+ |
+.ES |
+Program('foo', Glob('*.c')) |
+Zip('/tmp/everything', Glob('.??*') + Glob('*')) |
+.EE |
+ |
+'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" |
+'\".TP |
+'\".RI GlobalBuilders( flag ) |
+'\"When |
+'\".B flag |
+'\"is non-zero, |
+'\"adds the names of the default builders |
+'\"(Program, Library, etc.) |
+'\"to the global name space |
+'\"so they can be called without an explicit construction environment. |
+'\"(This is the default.) |
+'\"When |
+'\".B |
+'\"flag is zero, |
+'\"the names of the default builders are removed |
+'\"from the global name space |
+'\"so that an explicit construction environment is required |
+'\"to call all builders. |
+ |
+'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" |
+.TP |
+.RI Help( text ) |
+.TP |
+.RI env.Help( text ) |
+This specifies help text to be printed if the |
+.B -h |
+argument is given to |
+.BR scons . |
+If |
+.BR Help |
+is called multiple times, the text is appended together in the order |
+that |
+.BR Help |
+is called. |
+ |
+'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" |
+.TP |
+.RI Ignore( target ", " dependency ) |
+.TP |
+.RI env.Ignore( target ", " dependency ) |
+The specified dependency file(s) |
+will be ignored when deciding if |
+the target file(s) need to be rebuilt. |
+ |
+You can also use |
+.BR Ignore() |
+to remove a target from the default build. |
+In order to do this you must specify the directory the target will |
+be built in as the target, and the file you want to skip building |
+as the dependency. |
+ |
+Note that this will only remove the dependencies listed from |
+the files built by default. It will still be built if that |
+dependency is needed by another object being built. |
+See the third and forth examples below. |
+ |
+Examples: |
+ |
+.ES |
+env.Ignore('foo', 'foo.c') |
+env.Ignore('bar', ['bar1.h', 'bar2.h']) |
+env.Ignore('.','foobar.obj') |
+env.Ignore('bar','bar/foobar.obj') |
+.EE |
+ |
+'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" |
+.TP |
+.RI Import( vars ) |
+.TP |
+.RI env.Import( vars ) |
+This tells |
+.B scons |
+to import a list of variables into the current SConscript file. This |
+will import variables that were exported with |
+.BR Export () |
+or in the |
+.I exports |
+argument to |
+.BR SConscript (). |
+Variables exported by |
+.BR SConscript () |
+have precedence. |
+Multiple variable names can be passed to |
+.BR Import () |
+as separate arguments or as a list. The variable "*" can be used |
+to import all variables. |
+ |
+Examples: |
+ |
+.ES |
+Import("env") |
+Import("env", "variable") |
+Import(["env", "variable"]) |
+Import("*") |
+.EE |
+ |
+'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" |
+.TP |
+.RI Literal( string ) |
+.TP |
+.RI env.Literal( string ) |
+The specified |
+.I string |
+will be preserved as-is |
+and not have construction variables expanded. |
+ |
+'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" |
+.TP |
+.RI Local( targets ) |
+.TP |
+.RI env.Local( targets ) |
+The specified |
+.I targets |
+will have copies made in the local tree, |
+even if an already up-to-date copy |
+exists in a repository. |
+Returns a list of the target Node or Nodes. |
+ |
+'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" |
+\" .TP |
+\" .RI env.MergeShellPaths( arg ", [" prepend ]) |
+\" Merges the elements of the specified |
+\" .IR arg , |
+\" which must be a dictionary, to the construction |
+\" environment's copy of the shell environment |
+\" in env['ENV']. |
+\" (This is the environment which is passed |
+\" to subshells spawned by SCons.) |
+\" Note that |
+\" .I arg |
+\" must be a single value, |
+\" so multiple strings must |
+\" be passed in as a list, |
+\" not as separate arguments to |
+\" .BR env.MergeShellPaths (). |
+ |
+\" New values are prepended to the environment variable by default, |
+\" unless prepend=0 is specified. |
+\" Duplicate values are always eliminated, |
+\" since this function calls |
+\" .B AppendENVPath |
+\" or |
+\" .B PrependENVPath |
+\" depending on the |
+\" .I prepend |
+\" argument. See those functions for more details. |
+ |
+\" Examples: |
+ |
+\" .ES |
+\" # Prepend a path to the shell PATH. |
+\" env.MergeShellPaths({'PATH':'/usr/local/bin'} ) |
+\" # Append two dirs to the shell INCLUDE. |
+\" env.MergeShellPaths({'INCLUDE':['c:/inc1', 'c:/inc2']}, prepend=0 ) |
+ |
+.EE |
+ |
+'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" |
+.TP |
+.RI env.MergeFlags( arg ", [" unique ]) |
+Merges the specified |
+.I arg |
+values to the construction environment's construction variables. |
+If the |
+.I arg |
+argument is not a dictionary, |
+it is converted to one by calling |
+.B env.ParseFlags() |
+on the argument |
+before the values are merged. |
+Note that |
+.I arg |
+must be a single value, |
+so multiple strings must |
+be passed in as a list, |
+not as separate arguments to |
+.BR env.MergeFlags (). |
+ |
+By default, |
+duplicate values are eliminated; |
+you can, however, specify |
+.B unique=0 |
+to allow duplicate |
+values to be added. |
+When eliminating duplicate values, |
+any construction variables that end with |
+the string |
+.B PATH |
+keep the left-most unique value. |
+All other construction variables keep |
+the right-most unique value. |
+ |
+Examples: |
+ |
+.ES |
+# Add an optimization flag to $CCFLAGS. |
+env.MergeFlags('-O3') |
+ |
+# Combine the flags returned from running pkg-config with an optimization |
+# flag and merge the result into the construction variables. |
+env.MergeFlags(['!pkg-config gtk+-2.0 --cflags', '-O3']) |
+ |
+# Combine an optimization flag with the flags returned from running pkg-config |
+# twice and merge the result into the construction variables. |
+env.MergeFlags(['-O3', |
+ '!pkg-config gtk+-2.0 --cflags --libs', |
+ '!pkg-config libpng12 --cflags --libs']) |
+.EE |
+ |
+'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" |
+.TP |
+.RI NoCache( target ", ...)" |
+.TP |
+.RI env.NoCache( target ", ...)" |
+Specifies a list of files which should |
+.I not |
+be cached whenever the |
+.BR CacheDir () |
+method has been activated. |
+The specified targets may be a list |
+or an individual target. |
+ |
+Multiple files should be specified |
+either as separate arguments to the |
+.BR NoCache () |
+method, or as a list. |
+.BR NoCache () |
+will also accept the return value of any of the construction environment |
+Builder methods. |
+ |
+Calling |
+.BR NoCache () |
+on directories and other non-File Node types has no effect because |
+only File Nodes are cached. |
+ |
+Examples: |
+ |
+.ES |
+NoCache('foo.elf') |
+NoCache(env.Program('hello', 'hello.c')) |
+.EE |
+ |
+'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" |
+.TP |
+.RI NoClean( target ", ...)" |
+.TP |
+.RI env.NoClean( target ", ...)" |
+Specifies a list of files or directories which should |
+.I not |
+be removed whenever the targets (or their dependencies) |
+are specified with the |
+.B -c |
+command line option. |
+The specified targets may be a list |
+or an individual target. |
+Multiple calls to |
+.BR NoClean () |
+are legal, |
+and prevent each specified target |
+from being removed by calls to the |
+.B -c |
+option. |
+ |
+Multiple files or directories should be specified |
+either as separate arguments to the |
+.BR NoClean () |
+method, or as a list. |
+.BR NoClean () |
+will also accept the return value of any of the construction environment |
+Builder methods. |
+ |
+Calling |
+.BR NoClean () |
+for a target overrides calling |
+.BR Clean () |
+for the same target, |
+and any targets passed to both functions will |
+.I not |
+be removed by the |
+.B -c |
+option. |
+ |
+Examples: |
+ |
+.ES |
+NoClean('foo.elf') |
+NoClean(env.Program('hello', 'hello.c')) |
+.EE |
+ |
+'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" |
+.TP |
+.RI env.ParseConfig( command ", [" function ", " unique ]) |
+Calls the specified |
+.I function |
+to modify the environment as specified by the output of |
+.I command . |
+The default |
+.I function |
+is |
+.BR env.MergeFlags (), |
+which expects the output of a typical |
+.I *-config command |
+(for example, |
+.BR gtk-config ) |
+and adds the options |
+to the appropriate construction variables. |
+By default, |
+duplicate values are not |
+added to any construction variables; |
+you can specify |
+.B unique=0 |
+to allow duplicate |
+values to be added. |
+ |
+Interpreted options |
+and the construction variables they affect |
+are as specified for the |
+.BR env.ParseFlags () |
+method (which this method calls). |
+See that method's description, below, |
+for a table of options and construction variables. |
+ |
+'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" |
+.TP |
+.RI ParseDepends( filename ", [" must_exist ", " only_one ]) |
+.TP |
+.RI env.ParseDepends( filename ", [" must_exist ", " only_one ]) |
+Parses the contents of the specified |
+.I filename |
+as a list of dependencies in the style of |
+.BR Make |
+or |
+.BR mkdep , |
+and explicitly establishes all of the listed dependencies. |
+ |
+By default, |
+it is not an error |
+if the specified |
+.I filename |
+does not exist. |
+The optional |
+.I must_exist |
+argument may be set to a non-zero |
+value to have |
+scons |
+throw an exception and |
+generate an error if the file does not exist, |
+or is otherwise inaccessible. |
+ |
+The optional |
+.I only_one |
+argument may be set to a non-zero |
+value to have |
+scons |
+thrown an exception and |
+generate an error |
+if the file contains dependency |
+information for more than one target. |
+This can provide a small sanity check |
+for files intended to be generated |
+by, for example, the |
+.B gcc -M |
+flag, |
+which should typically only |
+write dependency information for |
+one output file into a corresponding |
+.B .d |
+file. |
+ |
+The |
+.I filename |
+and all of the files listed therein |
+will be interpreted relative to |
+the directory of the |
+.I SConscript |
+file which calls the |
+.B ParseDepends |
+function. |
+ |
+'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" |
+.TP |
+.RI env.ParseFlags( flags ", ...)" |
+Parses one or more strings containing |
+typical command-line flags for GCC tool chains |
+and returns a dictionary with the flag values |
+separated into the appropriate SCons construction variables. |
+This is intended as a companion to the |
+.BR env.MergeFlags () |
+method, but allows for the values in the returned dictionary |
+to be modified, if necessary, |
+before merging them into the construction environment. |
+(Note that |
+.BR env.MergeFlags () |
+will call this method if its argument is not a dictionary, |
+so it is usually not necessary to call |
+.BR env.ParseFlags () |
+directly unless you want to manipulate the values.) |
+ |
+If the first character in any string is |
+an exclamation mark (!), |
+the rest of the string is executed as a command, |
+and the output from the command is |
+parsed as GCC tool chain command-line flags |
+and added to the resulting dictionary. |
+ |
+Flag values are translated accordig to the prefix found, |
+and added to the following construction variables: |
+ |
+.ES |
+-arch CCFLAGS, LINKFLAGS |
+-D CPPDEFINES |
+-framework FRAMEWORKS |
+-frameworkdir= FRAMEWORKPATH |
+-include CCFLAGS |
+-isysroot CCFLAGS, LINKFLAGS |
+-I CPPPATH |
+-l LIBS |
+-L LIBPATH |
+-mno-cygwin CCFLAGS, LINKFLAGS |
+-mwindows LINKFLAGS |
+-pthread CCFLAGS, LINKFLAGS |
+-std= CFLAGS |
+-Wa, ASFLAGS, CCFLAGS |
+-Wl,-rpath= RPATH |
+-Wl,-R, RPATH |
+-Wl,-R RPATH |
+-Wl, LINKFLAGS |
+-Wp, CPPFLAGS |
+- CCFLAGS |
++ CCFLAGS, LINKFLAGS |
+.EE |
+ |
+.IP |
+Any other strings not associated with options |
+are assumed to be the names of libraries |
+and added to the |
+.B LIBS |
+construction variable. |
+ |
+Examples (all of which produce the same result): |
+ |
+.ES |
+dict = env.ParseFlags('-O2 -Dfoo -Dbar=1') |
+dict = env.ParseFlags('-O2', '-Dfoo', '-Dbar=1') |
+dict = env.ParseFlags(['-O2', '-Dfoo -Dbar=1']) |
+dict = env.ParseFlags('-O2', '!echo -Dfoo -Dbar=1') |
+.EE |
+ |
+'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" |
+.TP |
+env.Perforce() |
+A factory function that |
+returns a Builder object |
+to be used to fetch source files |
+from the Perforce source code management system. |
+The returned Builder |
+is intended to be passed to the |
+.B SourceCode |
+function. |
+ |
+This function is deprecated. For details, see the entry for the |
+.B SourceCode |
+function. |
+ |
+Example: |
+ |
+.ES |
+env.SourceCode('.', env.Perforce()) |
+.EE |
+.IP |
+Perforce uses a number of external |
+environment variables for its operation. |
+Consequently, this function adds the |
+following variables from the user's external environment |
+to the construction environment's |
+ENV dictionary: |
+P4CHARSET, |
+P4CLIENT, |
+P4LANGUAGE, |
+P4PASSWD, |
+P4PORT, |
+P4USER, |
+SystemRoot, |
+USER, |
+and |
+USERNAME. |
+ |
+'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" |
+.TP |
+.RI Platform( string ) |
+Returns a callable object |
+that can be used to initialize |
+a construction environment using the |
+platform keyword of the Environment() method. |
+ |
+Example: |
+ |
+.ES |
+env = Environment(platform = Platform('win32')) |
+.EE |
+.TP |
+.RI env.Platform( string ) |
+Applies the callable object for the specified platform |
+.I string |
+to the environment through which the method was called. |
+ |
+.ES |
+env.Platform('posix') |
+.EE |
+.IP |
+Note that the |
+.B win32 |
+platform adds the |
+.B SystemDrive |
+and |
+.B SystemRoot |
+variables from the user's external environment |
+to the construction environment's |
+.B ENV |
+dictionary. |
+This is so that any executed commands |
+that use sockets to connect with other systems |
+(such as fetching source files from |
+external CVS repository specifications like |
+.BR :pserver:anonymous@cvs.sourceforge.net:/cvsroot/scons ) |
+will work on Windows systems. |
+ |
+'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" |
+.TP |
+.RI Progress( callable ", [" interval ]) |
+.TP |
+.RI Progress( string ", [" interval ", " file ", " overwrite ]) |
+.TP |
+.RI Progress( list_of_strings ", [" interval ", " file ", " overwrite ]) |
+Allows SCons to show progress made during the build |
+by displaying a string or calling a function while |
+evaluating Nodes (e.g. files). |
+ |
+If the first specified argument is a Python callable |
+(a function or an object that has a |
+.BR __call__ () |
+method), |
+the function will be called |
+once every |
+.I interval |
+times a Node is evaluated. |
+The callable will be passed the evaluated Node |
+as its only argument. |
+(For future compatibility, |
+it's a good idea to also add |
+.B *args |
+and |
+.B **kw |
+as arguments to your function or method. |
+This will prevent the code from breaking |
+if SCons ever changes the interface |
+to call the function with additional arguments in the future.) |
+ |
+An example of a simple custom progress function |
+that prints a string containing the Node name |
+every 10 Nodes: |
+ |
+.ES |
+def my_progress_function(node, *args, **kw): |
+ print 'Evaluating node %s!' % node |
+Progress(my_progress_function, interval=10) |
+.EE |
+.IP |
+A more complicated example of a custom progress display object |
+that prints a string containing a count |
+every 100 evaluated Nodes. |
+Note the use of |
+.B \\\\r |
+(a carriage return) |
+at the end so that the string |
+will overwrite itself on a display: |
+ |
+.ES |
+import sys |
+class ProgressCounter(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 |
+.B $TARGET, |
+it will be replaced with the Node. |
+Note that, for performance reasons, this is |
+.I not |
+a regular SCons variable substition, |
+so you can not use other variables |
+or use curly braces. |
+The following example will print the name of |
+every evaluated Node, |
+using a |
+.B \\\\r |
+(carriage return) to cause each line to overwritten by the next line, |
+and the |
+.B overwrite= |
+keyword argument to make sure the previously-printed |
+file name is overwritten with blank spaces: |
+ |
+.ES |
+import sys |
+Progress('$TARGET\\r', overwrite=True) |
+.EE |
+.IP |
+If the first argument to |
+.BR Progress () |
+is a list of strings, |
+then each string in the list will be displayed |
+in rotating fashion every |
+.I interval |
+evaluated Nodes. |
+This can be used to implement a "spinner" |
+on the user's screen as follows: |
+ |
+.ES |
+Progress(['-\\r', '\\\\\\r', '|\\r', '/\\r'], interval=5) |
+.EE |
+ |
+'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" |
+.TP |
+.RI Precious( target ", ...)" |
+.TP |
+.RI env.Precious( target ", ...)" |
+Marks each given |
+.I target |
+as precious so it is not deleted before it is rebuilt. Normally |
+.B scons |
+deletes a target before building it. |
+Multiple targets can be passed in to a single call to |
+.BR Precious (). |
+ |
+'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" |
+.TP |
+.RI env.Prepend( key = val ", [...])" |
+Appends the specified keyword arguments |
+to the beginning of construction variables in the environment. |
+If the Environment does not have |
+the specified construction variable, |
+it is simply added to the environment. |
+If the values of the construction variable |
+and the keyword argument are the same type, |
+then the two values will be simply added together. |
+Otherwise, the construction variable |
+and the value of the keyword argument |
+are both coerced to lists, |
+and the lists are added together. |
+(See also the Append method, above.) |
+ |
+Example: |
+ |
+.ES |
+env.Prepend(CCFLAGS = '-g ', FOO = ['foo.yyy']) |
+.EE |
+ |
+'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" |
+.TP |
+.RI env.PrependENVPath( name ", " newpath ", [" envname ", " sep ", " delete_existing ]) |
+This appends new path elements to the given path in the |
+specified external environment |
+.RB ( ENV |
+by default). |
+This will only add |
+any particular path once (leaving the first one it encounters and |
+ignoring the rest, to preserve path order), |
+and to help assure this, |
+will normalize all paths (using |
+.B os.path.normpath |
+and |
+.BR os.path.normcase ). |
+This can also handle the |
+case where the given old path variable is a list instead of a |
+string, in which case a list will be returned instead of a string. |
+ |
+If |
+.I delete_existing |
+is 0, then adding a path that already exists |
+will not move it to the beginning; |
+it will stay where it is in the list. |
+ |
+Example: |
+ |
+.ES |
+print 'before:',env['ENV']['INCLUDE'] |
+include_path = '/foo/bar:/foo' |
+env.PrependENVPath('INCLUDE', include_path) |
+print 'after:',env['ENV']['INCLUDE'] |
+.EE |
+ |
+The above exmaple will print: |
+ |
+.ES |
+before: /biz:/foo |
+after: /foo/bar:/foo:/biz |
+.EE |
+ |
+'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" |
+.TP |
+.RI env.PrependUnique( key = val ", delete_existing=0, [...])" |
+Appends the specified keyword arguments |
+to the beginning of construction variables in the environment. |
+If the Environment does not have |
+the specified construction variable, |
+it is simply added to the environment. |
+If the construction variable being appended to is a list, |
+then any value(s) that already exist in the |
+construction variable will |
+.I not |
+be added again to the list. |
+However, if delete_existing is 1, |
+existing matching values are removed first, so |
+existing values in the arg list move to the front of the list. |
+ |
+Example: |
+ |
+.ES |
+env.PrependUnique(CCFLAGS = '-g', FOO = ['foo.yyy']) |
+.EE |
+ |
+'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" |
+.TP |
+env.RCS() |
+A factory function that |
+returns a Builder object |
+to be used to fetch source files |
+from RCS. |
+The returned Builder |
+is intended to be passed to the |
+.B SourceCode |
+function: |
+ |
+This function is deprecated. For details, see the entry for the |
+.B SourceCode |
+function. |
+ |
+Examples: |
+ |
+.ES |
+env.SourceCode('.', env.RCS()) |
+.EE |
+.IP |
+Note that |
+.B scons |
+will fetch source files |
+from RCS subdirectories automatically, |
+so configuring RCS |
+as demonstrated in the above example |
+should only be necessary if |
+you are fetching from |
+RCS,v |
+files in the same |
+directory as the source files, |
+or if you need to explicitly specify RCS |
+for a specific subdirectory. |
+ |
+'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" |
+.TP |
+.RI env.Replace( key = val ", [...])" |
+Replaces construction variables in the Environment |
+with the specified keyword arguments. |
+ |
+Example: |
+ |
+.ES |
+env.Replace(CCFLAGS = '-g', FOO = 'foo.xxx') |
+.EE |
+ |
+'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" |
+.TP |
+.RI Repository( directory ) |
+.TP |
+.RI env.Repository( directory ) |
+Specifies that |
+.I directory |
+is a repository to be searched for files. |
+Multiple calls to |
+.BR Repository () |
+are legal, |
+and each one adds to the list of |
+repositories that will be searched. |
+ |
+To |
+.BR scons , |
+a repository is a copy of the source tree, |
+from the top-level directory on down, |
+which may contain |
+both source files and derived files |
+that can be used to build targets in |
+the local source tree. |
+The canonical example would be an |
+official source tree maintained by an integrator. |
+If the repository contains derived files, |
+then the derived files should have been built using |
+.BR scons , |
+so that the repository contains the necessary |
+signature information to allow |
+.B scons |
+to figure out when it is appropriate to |
+use the repository copy of a derived file, |
+instead of building one locally. |
+ |
+Note that if an up-to-date derived file |
+already exists in a repository, |
+.B scons |
+will |
+.I not |
+make a copy in the local directory tree. |
+In order to guarantee that a local copy |
+will be made, |
+use the |
+.B Local() |
+method. |
+ |
+'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" |
+.TP |
+.RI Requires( target ", " prerequisite ) |
+.TP |
+.RI env.Requires( target ", " prerequisite ) |
+Specifies an order-only relationship |
+between the specified target file(s) |
+and the specified prerequisite file(s). |
+The prerequisite file(s) |
+will be (re)built, if necessary, |
+.I before |
+the target file(s), |
+but the target file(s) do not actually |
+depend on the prerequisites |
+and will not be rebuilt simply because |
+the prerequisite file(s) change. |
+ |
+Example: |
+ |
+.ES |
+env.Requires('foo', 'file-that-must-be-built-before-foo') |
+.EE |
+ |
+'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" |
+.TP |
+.RI Return([ vars "... , " stop= ]) |
+By default, |
+this stops processing the current SConscript |
+file and returns to the calling SConscript file |
+the values of the variables named in the |
+.I vars |
+string arguments. |
+Multiple strings contaning variable names may be passed to |
+.BR Return (). |
+Any strings that contain white space |
+ |
+The optional |
+.B stop= |
+keyword argument may be set to a false value |
+to continue processing the rest of the SConscript |
+file after the |
+.BR Return () |
+call. |
+This was the default behavior prior to SCons 0.98. |
+However, the values returned |
+are still the values of the variables in the named |
+.I vars |
+at the point |
+.BR Return () |
+is called. |
+ |
+Examples: |
+ |
+.ES |
+# Returns without returning a value. |
+Return() |
+ |
+# Returns the value of the 'foo' Python variable. |
+Return("foo") |
+ |
+# Returns the values of the Python variables 'foo' and 'bar'. |
+Return("foo", "bar") |
+ |
+# Returns the values of Python variables 'val1' and 'val2'. |
+Return('val1 val2') |
+.EE |
+ |
+'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" |
+.TP |
+.RI Scanner( function ", [" argument ", " keys ", " path_function ", " node_class ", " node_factory ", " scan_check ", " recursive ]) |
+.TP |
+.RI env.Scanner( function ", [" argument ", " keys ", " path_function ", " node_class ", " node_factory ", " scan_check ", " recursive ]) |
+Creates a Scanner object for |
+the specified |
+.IR function . |
+See the section "Scanner Objects," |
+below, for a complete explanation of the arguments and behavior. |
+ |
+'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" |
+.TP |
+env.SCCS() |
+A factory function that |
+returns a Builder object |
+to be used to fetch source files |
+from SCCS. |
+The returned Builder |
+is intended to be passed to the |
+.B SourceCode |
+function. |
+ |
+This function is deprecated. For details, see the entry for the |
+.B SourceCode |
+function. |
+ |
+Example: |
+ |
+.ES |
+env.SourceCode('.', env.SCCS()) |
+.EE |
+.IP |
+Note that |
+.B scons |
+will fetch source files |
+from SCCS subdirectories automatically, |
+so configuring SCCS |
+as demonstrated in the above example |
+should only be necessary if |
+you are fetching from |
+.I s.SCCS |
+files in the same |
+directory as the source files, |
+or if you need to explicitly specify SCCS |
+for a specific subdirectory. |
+ |
+'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" |
+.TP |
+.RI SConscript( scripts ", [" exports ", " variant_dir ", " duplicate ]) |
+'\" .RI SConscript( scripts ", [" exports ", " variant_dir ", " src_dir ", " duplicate ]) |
+.TP |
+.RI env.SConscript( scripts ", [" exports ", " variant_dir ", " duplicate ]) |
+'\" .RI env.SConscript( scripts ", [" exports ", " variant_dir ", " src_dir ", " duplicate ]) |
+.TP |
+.RI SConscript(dirs= subdirs ", [name=" script ", " exports ", " variant_dir ", " duplicate ]) |
+'\" .RI SConscript(dirs= subdirs ", [name=" script ", " exports ", " variant_dir ", " src_dir ", " duplicate ]) |
+.TP |
+.RI env.SConscript(dirs= subdirs ", [name=" script ", " exports ", " variant_dir ", " duplicate ]) |
+'\" .RI env.SConscript(dirs= subdirs ", [name=" script ", " exports ", " variant_dir ", " src_dir ", " duplicate ]) |
+This tells |
+.B scons |
+to execute |
+one or more subsidiary SConscript (configuration) files. |
+Any variables returned by a called script using |
+.BR Return () |
+will be returned by the call to |
+.BR SConscript (). |
+There are two ways to call the |
+.BR SConscript () |
+function. |
+ |
+The first way you can call |
+.BR SConscript () |
+is to explicitly specify one or more |
+.I scripts |
+as the first argument. |
+A single script may be specified as a string; |
+multiple scripts must be specified as a list |
+(either explicitly or as created by |
+a function like |
+.BR Split ()). |
+Examples: |
+.ES |
+SConscript('SConscript') # run SConscript in the current directory |
+SConscript('src/SConscript') # run SConscript in the src directory |
+SConscript(['src/SConscript', 'doc/SConscript']) |
+config = SConscript('MyConfig.py') |
+.EE |
+ |
+The second way you can call |
+.BR SConscript () |
+is to specify a list of (sub)directory names |
+as a |
+.RI dirs= subdirs |
+keyword argument. |
+In this case, |
+.B scons |
+will, by default, |
+execute a subsidiary configuration file named |
+.B SConscript |
+in each of the specified directories. |
+You may specify a name other than |
+.B SConscript |
+by supplying an optional |
+.RI name= script |
+keyword argument. |
+The first three examples below have the same effect |
+as the first three examples above: |
+.ES |
+SConscript(dirs='.') # run SConscript in the current directory |
+SConscript(dirs='src') # run SConscript in the src directory |
+SConscript(dirs=['src', 'doc']) |
+SConscript(dirs=['sub1', 'sub2'], name='MySConscript') |
+.EE |
+ |
+The optional |
+.I exports |
+argument provides a list of variable names or a dictionary of |
+named values to export to the |
+.IR script(s) . |
+These variables are locally exported only to the specified |
+.IR script(s) , |
+and do not affect the global pool of variables used by the |
+.BR Export () |
+function. |
+'\"If multiple dirs are provided, each script gets a fresh export. |
+The subsidiary |
+.I script(s) |
+must use the |
+.BR Import () |
+function to import the variables. |
+Examples: |
+.ES |
+foo = SConscript('sub/SConscript', exports='env') |
+SConscript('dir/SConscript', exports=['env', 'variable']) |
+SConscript(dirs='subdir', exports='env variable') |
+SConscript(dirs=['one', 'two', 'three'], exports='shared_info') |
+.EE |
+ |
+If the optional |
+.I variant_dir |
+argument is present, it causes an effect equivalent to the |
+.BR VariantDir () |
+method described below. |
+(If |
+.I variant_dir |
+is not present, the |
+'\" .IR src_dir and |
+.I duplicate |
+'\" arguments are ignored.) |
+argument is ignored.) |
+The |
+.I variant_dir |
+'\" and |
+'\" .I src_dir |
+'\" arguments are interpreted relative to the directory of the calling |
+argument is interpreted relative to the directory of the calling |
+.B SConscript |
+file. |
+See the description of the |
+.BR VariantDir () |
+function below for additional details and restrictions. |
+ |
+If |
+.I variant_dir |
+is present, |
+'\" but |
+'\" .IR src_dir " is not," |
+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 |
+is equivalent to |
+.ES |
+VariantDir('build', 'src') |
+SConscript('build/SConscript') |
+.EE |
+This later paradigm is often used when the sources are |
+in the same directory as the |
+.BR SConstruct: |
+.ES |
+SConscript('SConscript', variant_dir = 'build') |
+.EE |
+is equivalent to |
+.ES |
+VariantDir('build', '.') |
+SConscript('build/SConscript') |
+.EE |
+ |
+'\" If |
+'\" .IR variant_dir " and" |
+'\" .IR src_dir " are both present," |
+'\" xxxxx everything is in a state of confusion. |
+'\" .ES |
+'\" SConscript(dirs = 'src', variant_dir = 'build', src_dir = '.') |
+'\" runs src/SConscript in build/src, but |
+'\" SConscript(dirs = 'lib', variant_dir = 'build', src_dir = 'src') |
+'\" runs lib/SConscript (in lib!). However, |
+'\" SConscript(dirs = 'src', variant_dir = 'build', src_dir = 'src') |
+'\" runs src/SConscript in build. Moreover, |
+'\" SConscript(dirs = 'src/lib', variant_dir = 'build', src_dir = 'src') |
+'\" runs src/lib/SConscript in build/lib. Moreover, |
+'\" SConscript(dirs = 'build/src/lib', variant_dir = 'build', src_dir = 'src') |
+'\" can't find build/src/lib/SConscript, even though it ought to exist. |
+'\" .EE |
+'\" is equivalent to |
+'\" .ES |
+'\" ???????????????? |
+'\" .EE |
+'\" and what about this alternative? |
+'\"TODO??? SConscript('build/SConscript', src_dir='src') |
+ |
+Here are some composite examples: |
+ |
+.ES |
+# collect the configuration information and use it to build src and doc |
+shared_info = SConscript('MyConfig.py') |
+SConscript('src/SConscript', exports='shared_info') |
+SConscript('doc/SConscript', exports='shared_info') |
+.EE |
+ |
+.ES |
+# build debugging and production versions. SConscript |
+# can use Dir('.').path to determine variant. |
+SConscript('SConscript', variant_dir='debug', duplicate=0) |
+SConscript('SConscript', variant_dir='prod', duplicate=0) |
+.EE |
+ |
+.ES |
+# build debugging and production versions. SConscript |
+# is passed flags to use. |
+opts = { 'CPPDEFINES' : ['DEBUG'], 'CCFLAGS' : '-pgdb' } |
+SConscript('SConscript', variant_dir='debug', duplicate=0, exports=opts) |
+opts = { 'CPPDEFINES' : ['NODEBUG'], 'CCFLAGS' : '-O' } |
+SConscript('SConscript', variant_dir='prod', duplicate=0, exports=opts) |
+.EE |
+ |
+.ES |
+# build common documentation and compile for different architectures |
+SConscript('doc/SConscript', variant_dir='build/doc', duplicate=0) |
+SConscript('src/SConscript', variant_dir='build/x86', duplicate=0) |
+SConscript('src/SConscript', variant_dir='build/ppc', duplicate=0) |
+.EE |
+ |
+'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" |
+.TP |
+.RI SConscriptChdir( value ) |
+.TP |
+.RI env.SConscriptChdir( value ) |
+By default, |
+.B scons |
+changes its working directory |
+to the directory in which each |
+subsidiary SConscript file lives. |
+This behavior may be disabled |
+by specifying either: |
+ |
+.ES |
+SConscriptChdir(0) |
+env.SConscriptChdir(0) |
+.EE |
+.IP |
+in which case |
+.B scons |
+will stay in the top-level directory |
+while reading all SConscript files. |
+(This may be necessary when building from repositories, |
+when all the directories in which SConscript files may be found |
+don't necessarily exist locally.) |
+You may enable and disable |
+this ability by calling |
+SConscriptChdir() |
+multiple times. |
+ |
+Example: |
+ |
+.ES |
+env = Environment() |
+SConscriptChdir(0) |
+SConscript('foo/SConscript') # will not chdir to foo |
+env.SConscriptChdir(1) |
+SConscript('bar/SConscript') # will chdir to bar |
+.EE |
+ |
+'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" |
+.TP |
+.RI SConsignFile([ file , dbm_module ]) |
+.TP |
+.RI env.SConsignFile([ file , dbm_module ]) |
+This tells |
+.B scons |
+to store all file signatures |
+in the specified database |
+.IR file . |
+If the |
+.I file |
+name is omitted, |
+.B .sconsign |
+is used by default. |
+(The actual file name(s) stored on disk |
+may have an appropriated suffix appended |
+by the |
+.IR dbm_module .) |
+If |
+.I file |
+is not an absolute path name, |
+the file is placed in the same directory as the top-level |
+.B SConstruct |
+file. |
+ |
+If |
+.I file |
+is |
+.BR None , |
+then |
+.B scons |
+will store file signatures |
+in a separate |
+.B .sconsign |
+file in each directory, |
+not in one global database file. |
+(This was the default behavior |
+prior to SCons 0.96.91 and 0.97.) |
+ |
+The optional |
+.I dbm_module |
+argument can be used to specify |
+which Python database module |
+The default is to use a custom |
+.B SCons.dblite |
+module that uses pickled |
+Python data structures, |
+and which works on all Python versions. |
+ |
+Examples: |
+ |
+.ES |
+# Explicitly stores signatures in ".sconsign.dblite" |
+# in the top-level SConstruct directory (the |
+# default behavior). |
+SConsignFile() |
+ |
+# Stores signatures in the file "etc/scons-signatures" |
+# relative to the top-level SConstruct directory. |
+SConsignFile("etc/scons-signatures") |
+ |
+# Stores signatures in the specified absolute file name. |
+SConsignFile("/home/me/SCons/signatures") |
+ |
+# Stores signatures in a separate .sconsign file |
+# in each directory. |
+SConsignFile(None) |
+.EE |
+ |
+'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" |
+.TP |
+.RI env.SetDefault(key = val ", [...])" |
+Sets construction variables to default values specified with the keyword |
+arguments if (and only if) the variables are not already set. |
+The following statements are equivalent: |
+ |
+.ES |
+env.SetDefault(FOO = 'foo') |
+ |
+if 'FOO' not in env: env['FOO'] = 'foo' |
+.EE |
+ |
+'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" |
+.TP |
+.RI SetOption( name ", " value ) |
+.TP |
+.RI env.SetOption( name ", " value ) |
+This function provides a way to set a select subset of the scons command |
+line options from a SConscript file. The options supported are: |
+ |
+.RS 10 |
+.TP 6 |
+.B clean |
+which corresponds to -c, --clean and --remove; |
+.TP 6 |
+.B duplicate |
+which corresponds to --duplicate; |
+.TP 6 |
+.B help |
+which corresponds to -h and --help; |
+.TP 6 |
+.B implicit_cache |
+which corresponds to --implicit-cache; |
+.TP 6 |
+.B max_drift |
+which corresponds to --max-drift; |
+.TP 6 |
+.B no_exec |
+which corresponds to -n, --no-exec, --just-print, --dry-run and --recon; |
+.TP 6 |
+.B num_jobs |
+which corresponds to -j and --jobs; |
+.TP 6 |
+.B random |
+which corresponds to --random; and |
+.TP 6 |
+.B stack_size |
+which corresponds to --stack-size. |
+.RE |
+ |
+.IP |
+See the documentation for the |
+corresponding command line object for information about each specific |
+option. |
+ |
+Example: |
+ |
+.ES |
+SetOption('max_drift', 1) |
+.EE |
+ |
+'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" |
+.TP |
+.RI SideEffect( side_effect ", " target ) |
+.TP |
+.RI env.SideEffect( side_effect ", " target ) |
+Declares |
+.I side_effect |
+as a side effect of building |
+.IR target . |
+Both |
+.I side_effect |
+and |
+.I target |
+can be a list, a file name, or a node. |
+A side effect is a target file that is created or updated |
+as a side effect of building other targets. |
+For example, a Windows PDB |
+file is created as a side effect of building the .obj |
+files for a static library, |
+and various log files are created updated |
+as side effects of various TeX commands. |
+If a target is a side effect of multiple build commands, |
+.B scons |
+will ensure that only one set of commands |
+is executed at a time. |
+Consequently, you only need to use this method |
+for side-effect targets that are built as a result of |
+multiple build commands. |
+ |
+Because multiple build commands may update |
+the same side effect file, |
+by default the |
+.I side_effect |
+target is |
+.I not |
+automatically removed |
+when the |
+.I target |
+is removed by the |
+.B -c |
+option. |
+(Note, however, that the |
+.I side_effect |
+might be removed as part of |
+cleaning the directory in which it lives.) |
+If you want to make sure the |
+.I side_effect |
+is cleaned whenever a specific |
+.I target |
+is cleaned, |
+you must specify this explicitly |
+with the |
+.BR Clean () |
+or |
+.BR env.Clean () |
+function. |
+ |
+'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" |
+.TP |
+.RI SourceCode( entries ", " builder ) |
+.TP |
+.RI env.SourceCode( entries ", " builder ) |
+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 |
+.B SourceCode |
+builder it finds. |
+The specified |
+.I builder |
+may be |
+.BR None , |
+in which case |
+.B scons |
+will not use a builder to fetch |
+source files for the specified |
+.IR entries , |
+even if a |
+.B SourceCode |
+builder has been specified |
+for a directory higher up the tree. |
+ |
+.B scons |
+will, by default, |
+fetch files from SCCS or RCS subdirectories |
+without explicit configuration. |
+This takes some extra processing time |
+to search for the necessary |
+source code management files on disk. |
+You can avoid these extra searches |
+and speed up your build a little |
+by disabling these searches as follows: |
+ |
+.ES |
+env.SourceCode('.', None) |
+.EE |
+ |
+.IP |
+Note that if the specified |
+.I builder |
+is one you create by hand, |
+it must have an associated |
+construction environment to use |
+when fetching a source file. |
+ |
+.B scons |
+provides a set of canned factory |
+functions that return appropriate |
+Builders for various popular |
+source code management systems. |
+Canonical examples of invocation include: |
+ |
+.ES |
+env.SourceCode('.', env.BitKeeper('/usr/local/BKsources')) |
+env.SourceCode('src', env.CVS('/usr/local/CVSROOT')) |
+env.SourceCode('/', env.RCS()) |
+env.SourceCode(['f1.c', 'f2.c'], env.SCCS()) |
+env.SourceCode('no_source.c', None) |
+.EE |
+'\"env.SourceCode('.', env.Subversion('file:///usr/local/Subversion')) |
+ |
+'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" |
+.TP |
+.RI env.subst( input ", [" raw ", " target ", " source ", " conv ]) |
+Performs construction variable interpolation |
+on the specified string or sequence argument |
+.IR input . |
+ |
+By default, |
+leading or trailing white space will |
+be removed from the result. |
+and all sequences of white space |
+will be compressed to a single space character. |
+Additionally, any |
+.B $( |
+and |
+.B $) |
+character sequences will be stripped from the returned string, |
+The optional |
+.I raw |
+argument may be set to |
+.B 1 |
+if you want to preserve white space and |
+.BR $( - $) |
+sequences. |
+The |
+.I raw |
+argument may be set to |
+.B 2 |
+if you want to strip |
+all characters between |
+any |
+.B $( |
+and |
+.B $) |
+pairs |
+(as is done for signature calculation). |
+ |
+If the input is a sequence |
+(list or tuple), |
+the individual elements of |
+the sequence will be expanded, |
+and the results will be returned as a list. |
+ |
+The optional |
+.I target |
+and |
+.I source |
+keyword arguments |
+must be set to lists of |
+target and source nodes, respectively, |
+if you want the |
+.BR $TARGET , |
+.BR $TARGETS , |
+.BR $SOURCE |
+and |
+.BR $SOURCES |
+to be available for expansion. |
+This is usually necessary if you are |
+calling |
+.BR env.subst () |
+from within a Python function used |
+as an SCons action. |
+ |
+Returned string values or sequence elements |
+are converted to their string representation by default. |
+The optional |
+.I conv |
+argument |
+may specify a conversion function |
+that will be used in place of |
+the default. |
+For example, if you want Python objects |
+(including SCons Nodes) |
+to be returned as Python objects, |
+you can use the Python |
+.B lambda |
+idiom to pass in an unnamed function |
+that simply returns its unconverted argument. |
+ |
+Example: |
+ |
+.ES |
+print env.subst("The C compiler is: $CC") |
+ |
+def compile(target, source, env): |
+ sourceDir = env.subst("${SOURCE.srcdir}", |
+ target=target, |
+ source=source) |
+ |
+source_nodes = env.subst('$EXPAND_TO_NODELIST', |
+ conv=lambda x: x) |
+.EE |
+ |
+'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" |
+'\".TP |
+'\".RI Subversion( repository ", " module ) |
+'\"A factory function that |
+'\"returns a Builder object |
+'\"to be used to fetch source files |
+'\"from the specified Subversion |
+'\".IR repository . |
+'\"The returned Builder |
+'\"is intended to be passed to the |
+'\".B SourceCode |
+'\"function. |
+'\" |
+'\"The optional specified |
+'\".I module |
+'\"will be added to the beginning |
+'\"of all repository path names; |
+'\"this can be used, in essence, |
+'\"to strip initial directory names |
+'\"from the repository path names, |
+'\"so that you only have to |
+'\"replicate part of the repository |
+'\"directory hierarchy in your |
+'\"local build directory. |
+'\" |
+'\"This function is deprecated. For details, see the entry for the |
+'\".B SourceCode |
+'\"function. |
+'\" |
+'\"Example: |
+'\" |
+'\".ES |
+'\"# Will fetch foo/bar/src.c |
+'\"# from /usr/local/Subversion/foo/bar/src.c. |
+'\"env.SourceCode('.', env.Subversion('file:///usr/local/Subversion')) |
+'\" |
+'\"# Will fetch bar/src.c |
+'\"# from /usr/local/Subversion/foo/bar/src.c. |
+'\"env.SourceCode('.', env.Subversion('file:///usr/local/Subversion', 'foo')) |
+'\" |
+'\"# Will fetch src.c |
+'\"# from /usr/local/Subversion/foo/bar/src.c. |
+'\"env.SourceCode('.', env.Subversion('file:///usr/local/Subversion', 'foo/bar')) |
+'\".EE |
+ |
+'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" |
+.TP |
+.RI SourceSignatures( type ) |
+.TP |
+.RI env.SourceSignatures( type ) |
+Note: Although it is not yet officially deprecated, |
+use of this function is discouraged. |
+See the |
+.BR Decider () |
+function for a more flexible and straightforward way |
+to configure SCons' decision-making. |
+ |
+The |
+.BR SourceSignatures () |
+function tells |
+.B scons |
+how to decide if a source file |
+(a file that is not built from any other files) |
+has changed since the last time it |
+was used to build a particular target file. |
+Legal values are |
+.B "MD5" |
+or |
+.BR "timestamp" . |
+ |
+If the environment method is used, |
+the specified type of source signature |
+is only used when deciding whether targets |
+built with that environment are up-to-date or must be rebuilt. |
+If the global function is used, |
+the specified type of source signature becomes the default |
+used for all decisions |
+about whether targets are up-to-date. |
+ |
+.B "MD5" |
+means |
+.B scons |
+decides that a source file has changed |
+if the MD5 checksum of its contents has changed since |
+the last time it was used to rebuild a particular target file. |
+ |
+.B "timestamp" |
+means |
+.B scons |
+decides that a source file has changed |
+if its timestamp (modification time) has changed since |
+the last time it was used to rebuild a particular target file. |
+(Note that although this is similar to the behavior of Make, |
+by default it will also rebuild if the dependency is |
+.I older |
+than the last time it was used to rebuild the target file.) |
+ |
+There is no different between the two behaviors |
+for Python |
+.BR Value () |
+node objects. |
+ |
+.B "MD5" |
+signatures take longer to compute, |
+but are more accurate than |
+.B "timestamp" |
+signatures. |
+The default value is |
+.BR "MD5" . |
+ |
+Note that the default |
+.BR TargetSignatures () |
+setting (see below) |
+is to use this |
+.BR SourceSignatures () |
+setting for any target files that are used |
+to build other target files. |
+Consequently, changing the value of |
+.BR SourceSignatures () |
+will, by default, |
+affect the up-to-date decision for all files in the build |
+(or all files built with a specific construction environment |
+when |
+.BR env.SourceSignatures () |
+is used). |
+ |
+'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" |
+.TP |
+.RI Split( arg ) |
+.TP |
+.RI env.Split( arg ) |
+Returns a list of file names or other objects. |
+If arg is a string, |
+it will be split on strings of white-space characters |
+within the string, |
+making it easier to write long lists of file names. |
+If arg is already a list, |
+the list will be returned untouched. |
+If arg is any other type of object, |
+it will be returned as a list |
+containing just the object. |
+ |
+Example: |
+ |
+.ES |
+files = Split("f1.c f2.c f3.c") |
+files = env.Split("f4.c f5.c f6.c") |
+files = Split(""" |
+ f7.c |
+ f8.c |
+ f9.c |
+""") |
+.EE |
+ |
+'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" |
+.TP |
+.RI Tag( node ", " tags ) |
+Annotates file or directory Nodes with |
+information about how the |
+.BR Package () |
+Builder should package those files or directories. |
+All tags are optional. |
+ |
+Examples: |
+ |
+.ES |
+# makes sure the built library will be installed with 0644 file |
+# access mode |
+Tag( Library( 'lib.c' ), UNIX_ATTR="0644" ) |
+ |
+# marks file2.txt to be a documentation file |
+Tag( 'file2.txt', DOC ) |
+.EE |
+ |
+'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" |
+.TP |
+.RI TargetSignatures( type ) |
+.TP |
+.RI env.TargetSignatures( type ) |
+Note: Although it is not yet officially deprecated, |
+use of this function is discouraged. |
+See the |
+.BR Decider () |
+function for a more flexible and straightforward way |
+to configure SCons' decision-making. |
+ |
+The |
+.BR TargetSignatures () |
+function tells |
+.B scons |
+how to decide if a target file |
+(a file that |
+.I is |
+built from any other files) |
+has changed since the last time it |
+was used to build some other target file. |
+Legal values are |
+.BR "build" ; |
+.BR "content" |
+(or its synonym |
+.BR "MD5" ); |
+.BR "timestamp" ; |
+or |
+.BR "source" . |
+ |
+If the environment method is used, |
+the specified type of target signature is only used |
+for targets built with that environment. |
+If the global function is used, |
+the specified type of signature becomes the default |
+used for all target files that |
+don't have an explicit target signature type |
+specified for their environments. |
+ |
+.B "content" |
+(or its synonym |
+.BR "MD5" ) |
+means |
+.B scons |
+decides that a target file has changed |
+if the MD5 checksum of its contents has changed since |
+the last time it was used to rebuild some other target file. |
+This means |
+.B scons |
+will open up |
+MD5 sum the contents |
+of target files after they're built, |
+and may decide that it does not need to rebuild |
+"downstream" target files if a file was |
+rebuilt with exactly the same contents as the last time. |
+ |
+.B "timestamp" |
+means |
+.B scons |
+decides that a target file has changed |
+if its timestamp (modification time) has changed since |
+the last time it was used to rebuild some other target file. |
+(Note that although this is similar to the behavior of Make, |
+by default it will also rebuild if the dependency is |
+.I older |
+than the last time it was used to rebuild the target file.) |
+ |
+.B "source" |
+means |
+.B scons |
+decides that a target file has changed |
+as specified by the corresponding |
+.BR SourceSignatures () |
+setting |
+.BR "" ( "MD5" |
+or |
+.BR "timestamp" ). |
+This means that |
+.B scons |
+will treat all input files to a target the same way, |
+regardless of whether they are source files |
+or have been built from other files. |
+ |
+.B "build" |
+means |
+.B scons |
+decides that a target file has changed |
+if it has been rebuilt in this invocation |
+or if its content or timestamp have changed |
+as specified by the corresponding |
+.BR SourceSignatures () |
+setting. |
+This "propagates" the status of a rebuilt file |
+so that other "downstream" target files |
+will always be rebuilt, |
+even if the contents or the timestamp |
+have not changed. |
+ |
+.B "build" |
+signatures are fastest because |
+.B "content" |
+(or |
+.BR "MD5" ) |
+signatures take longer to compute, |
+but are more accurate than |
+.B "timestamp" |
+signatures, |
+and can prevent unnecessary "downstream" rebuilds |
+when a target file is rebuilt to the exact same contents |
+as the previous build. |
+The |
+.B "source" |
+setting provides the most consistent behavior |
+when other target files may be rebuilt from |
+both source and target input files. |
+The default value is |
+.BR "source" . |
+ |
+Because the default setting is |
+.BR "source" , |
+using |
+.BR SourceSignatures () |
+is generally preferable to |
+.BR TargetSignatures () , |
+so that the up-to-date decision |
+will be consistent for all files |
+(or all files built with a specific construction environment). |
+Use of |
+.BR TargetSignatures () |
+provides specific control for how built target files |
+affect their "downstream" dependencies. |
+ |
+'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" |
+.TP |
+.RI Tool( string [, toolpath ", " **kw ]) |
+Returns a callable object |
+that can be used to initialize |
+a construction environment using the |
+tools keyword of the Environment() method. |
+The object may be called with a construction |
+environment as an argument, |
+in which case the object will |
+add the necessary variables |
+to the construction environment |
+and the name of the tool will be added to the |
+.B $TOOLS |
+construction variable. |
+ |
+Additional keyword arguments are passed to the tool's |
+.B generate() |
+method. |
+ |
+Examples: |
+ |
+.ES |
+env = Environment(tools = [ Tool('msvc') ]) |
+ |
+env = Environment() |
+t = Tool('msvc') |
+t(env) # adds 'msvc' to the TOOLS variable |
+u = Tool('opengl', toolpath = ['tools']) |
+u(env) # adds 'opengl' to the TOOLS variable |
+.EE |
+.TP |
+.RI env.Tool( string [, toolpath ", " **kw ]) |
+Applies the callable object for the specified tool |
+.I string |
+to the environment through which the method was called. |
+ |
+Additional keyword arguments are passed to the tool's |
+.B generate() |
+method. |
+ |
+.ES |
+env.Tool('gcc') |
+env.Tool('opengl', toolpath = ['build/tools']) |
+.EE |
+ |
+'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" |
+.TP |
+.RI Value( value ", [" built_value ]) |
+.TP |
+.RI env.Value( value ", [" built_value ]) |
+Returns a Node object representing the specified Python value. Value |
+Nodes can be used as dependencies of targets. If the result of |
+calling |
+.BR str( value ) |
+changes between SCons runs, any targets depending on |
+.BR Value( value ) |
+will be rebuilt. |
+(This is true even when using timestamps to decide if |
+files are up-to-date.) |
+When using timestamp source signatures, Value Nodes' |
+timestamps are equal to the system time when the Node is created. |
+ |
+The returned Value Node object has a |
+.BR write () |
+method that can be used to "build" a Value Node |
+by setting a new value. |
+The optional |
+.I built_value |
+argument can be specified |
+when the Value Node is created |
+to indicate the Node should already be considered |
+"built." |
+There is a corresponding |
+.BR read () |
+method that will return the built value of the Node. |
+ |
+Examples: |
+ |
+.ES |
+env = Environment() |
+ |
+def create(target, source, env): |
+ # A function that will write a 'prefix=$SOURCE' |
+ # string into the file name specified as the |
+ # $TARGET. |
+ f = open(str(target[0]), 'wb') |
+ f.write('prefix=' + source[0].get_contents()) |
+ |
+# Fetch the prefix= argument, if any, from the command |
+# line, and use /usr/local as the default. |
+prefix = ARGUMENTS.get('prefix', '/usr/local') |
+ |
+# Attach a .Config() builder for the above function action |
+# to the construction environment. |
+env['BUILDERS']['Config'] = Builder(action = create) |
+env.Config(target = 'package-config', source = Value(prefix)) |
+ |
+def build_value(target, source, env): |
+ # A function that "builds" a Python Value by updating |
+ # the the Python value with the contents of the file |
+ # specified as the source of the Builder call ($SOURCE). |
+ target[0].write(source[0].get_contents()) |
+ |
+output = env.Value('before') |
+input = env.Value('after') |
+ |
+# Attach a .UpdateValue() builder for the above function |
+# action to the construction environment. |
+env['BUILDERS']['UpdateValue'] = Builder(action = build_value) |
+env.UpdateValue(target = Value(output), source = Value(input)) |
+.EE |
+ |
+'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" |
+.TP |
+.RI VariantDir( variant_dir ", " src_dir ", [" duplicate ]) |
+.TP |
+.RI env.VariantDir( variant_dir ", " src_dir ", [" duplicate ]) |
+Use the |
+.BR VariantDir () |
+function to create a copy of your sources in another location: |
+if a name under |
+.IR variant_dir |
+is not found but exists under |
+.IR src_dir , |
+the file or directory is copied to |
+.IR variant_dir . |
+Target files can be built in a different directory |
+than the original sources by simply refering to the sources (and targets) |
+within the variant tree. |
+ |
+.BR VariantDir () |
+can be called multiple times with the same |
+.I src_dir |
+to set up multiple builds with different options |
+.RI ( variants ). |
+The |
+.I src_dir |
+location must be in or underneath the SConstruct file's directory, and |
+.I variant_dir |
+may not be underneath |
+.IR src_dir . |
+'\"TODO: Can the above restrictions be clarified or relaxed? |
+'\"TODO: The latter restriction is clearly not completely right; |
+'\"TODO: src_dir = '.' works fine with a build dir under it. |
+ |
+The default behavior is for |
+.B scons |
+to physically duplicate the source files in the variant tree. |
+Thus, a build performed in the variant tree is guaranteed to be identical |
+to a build performed in the source tree even if |
+intermediate source files are generated during the build, |
+or preprocessors or other scanners search for included files |
+relative to the source file, |
+or individual compilers or other invoked tools are hard-coded |
+to put derived files in the same directory as source files. |
+ |
+If possible on the platform, |
+the duplication is performed by linking rather than copying; |
+see also the |
+.IR --duplicate |
+command-line option. |
+Moreover, only the files needed for the build are duplicated; |
+files and directories that are not used are not present in |
+.IR variant_dir . |
+ |
+Duplicating the source tree may be disabled by setting the |
+.I duplicate |
+argument to 0 (zero). |
+This will cause |
+.B scons |
+to invoke Builders using the path names of source files in |
+.I src_dir |
+and the path names of derived files within |
+.IR variant_dir . |
+This is always more efficient than |
+.IR duplicate =1, |
+and is usually safe for most builds |
+(but see above for cases that may cause problems). |
+ |
+Note that |
+.BR VariantDir () |
+works most naturally with a subsidiary SConscript file. |
+However, you would then call the subsidiary SConscript file |
+not in the source directory, but in the |
+.I variant_dir , |
+regardless of the value of |
+.IR duplicate . |
+This is how you tell |
+.B scons |
+which variant of a source tree to build: |
+ |
+.ES |
+# run src/SConscript in two variant directories |
+VariantDir('build/variant1', 'src') |
+SConscript('build/variant1/SConscript') |
+VariantDir('build/variant2', 'src') |
+SConscript('build/variant2/SConscript') |
+.EE |
+ |
+.IP |
+See also the |
+.BR SConscript () |
+function, described above, |
+for another way to specify a variant directory |
+in conjunction with calling a subsidiary SConscript file. |
+ |
+Examples: |
+ |
+.ES |
+# use names in the build directory, not the source directory |
+VariantDir('build', 'src', duplicate=0) |
+Program('build/prog', 'build/source.c') |
+.EE |
+ |
+.ES |
+# this builds both the source and docs in a separate subtree |
+VariantDir('build', '.', duplicate=0) |
+SConscript(dirs=['build/src','build/doc']) |
+.EE |
+ |
+.ES |
+# same as previous example, but only uses SConscript |
+SConscript(dirs='src', variant_dir='build/src', duplicate=0) |
+SConscript(dirs='doc', variant_dir='build/doc', duplicate=0) |
+.EE |
+ |
+'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" |
+.TP |
+.RI WhereIs( program ", [" path ", " pathext ", " reject ]) |
+.TP |
+.RI env.WhereIs( program ", [" path ", " pathext ", " reject ]) |
+ |
+Searches for the specified executable |
+.I program, |
+returning the full path name to the program |
+if it is found, |
+and returning None if not. |
+Searches the specified |
+.I path, |
+the value of the calling environment's PATH |
+(env['ENV']['PATH']), |
+or the user's current external PATH |
+(os.environ['PATH']) |
+by default. |
+On Windows systems, searches for executable |
+programs with any of the file extensions |
+listed in the specified |
+.I pathext, |
+the calling environment's PATHEXT |
+(env['ENV']['PATHEXT']) |
+or the user's current PATHEXT |
+(os.environ['PATHEXT']) |
+by default. |
+Will not select any |
+path name or names |
+in the specified |
+.I reject |
+list, if any. |
+ |
+.SS SConscript Variables |
+In addition to the global functions and methods, |
+.B scons |
+supports a number of Python variables |
+that can be used in SConscript files |
+to affect how you want the build to be performed. |
+These variables may be accessed from custom Python modules that you |
+import into an SConscript file by adding the following |
+to the Python module: |
+ |
+.ES |
+from SCons.Script import * |
+.EE |
+ |
+'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" |
+.TP |
+ARGLIST |
+A list |
+.IR keyword = value |
+arguments specified on the command line. |
+Each element in the list is a tuple |
+containing the |
+.RI ( keyword , value ) |
+of the argument. |
+The separate |
+.I keyword |
+and |
+.I value |
+elements of the tuple |
+can be accessed by |
+subscripting for element |
+.B [0] |
+and |
+.B [1] |
+of the tuple, respectively. |
+ |
+Example: |
+ |
+.ES |
+print "first keyword, value =", ARGLIST[0][0], ARGLIST[0][1] |
+print "second keyword, value =", ARGLIST[1][0], ARGLIST[1][1] |
+third_tuple = ARGLIST[2] |
+print "third keyword, value =", third_tuple[0], third_tuple[1] |
+for key, value in ARGLIST: |
+ # process key and value |
+.EE |
+ |
+'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" |
+.TP |
+ARGUMENTS |
+A dictionary of all the |
+.IR keyword = value |
+arguments specified on the command line. |
+The dictionary is not in order, |
+and if a given keyword has |
+more than one value assigned to it |
+on the command line, |
+the last (right-most) value is |
+the one in the |
+.B ARGUMENTS |
+dictionary. |
+ |
+Example: |
+ |
+.ES |
+if ARGUMENTS.get('debug', 0): |
+ env = Environment(CCFLAGS = '-g') |
+else: |
+ env = Environment() |
+.EE |
+ |
+'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" |
+.TP |
+BUILD_TARGETS |
+A list of the targets which |
+.B scons |
+will actually try to build, |
+regardless of whether they were specified on |
+the command line or via the |
+.BR Default () |
+function or method. |
+The elements of this list may be strings |
+.I or |
+nodes, so you should run the list through the Python |
+.B str |
+function to make sure any Node path names |
+are converted to strings. |
+ |
+Because this list may be taken from the |
+list of targets specified using the |
+.BR Default () |
+function or method, |
+the contents of the list may change |
+on each successive call to |
+.BR Default (). |
+See the |
+.B DEFAULT_TARGETS |
+list, below, |
+for additional information. |
+ |
+Example: |
+ |
+.ES |
+if 'foo' in BUILD_TARGETS: |
+ print "Don't forget to test the `foo' program!" |
+if 'special/program' in BUILD_TARGETS: |
+ SConscript('special') |
+.EE |
+.IP |
+Note that the |
+.B BUILD_TARGETS |
+list only contains targets expected listed |
+on the command line or via calls to the |
+.BR Default () |
+function or method. |
+It does |
+.I not |
+contain all dependent targets that will be built as |
+a result of making the sure the explicitly-specified |
+targets are up to date. |
+ |
+'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" |
+.TP |
+COMMAND_LINE_TARGETS |
+A list of the targets explicitly specified on |
+the command line. |
+If there are no targets specified on the command line, |
+the list is empty. |
+This can be used, for example, |
+to take specific actions only |
+when a certain target or targets |
+is explicitly being built. |
+ |
+Example: |
+ |
+.ES |
+if 'foo' in COMMAND_LINE_TARGETS: |
+ print "Don't forget to test the `foo' program!" |
+if 'special/program' in COMMAND_LINE_TARGETS: |
+ SConscript('special') |
+.EE |
+ |
+'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" |
+.TP |
+DEFAULT_TARGETS |
+A list of the target |
+.I nodes |
+that have been specified using the |
+.BR Default () |
+function or method. |
+The elements of the list are nodes, |
+so you need to run them through the Python |
+.B str |
+function to get at the path name for each Node. |
+ |
+Example: |
+ |
+.ES |
+print str(DEFAULT_TARGETS[0]) |
+if 'foo' in map(str, DEFAULT_TARGETS): |
+ print "Don't forget to test the `foo' program!" |
+.EE |
+.IP |
+The contents of the |
+.B DEFAULT_TARGETS |
+list change on on each successive call to the |
+.BR Default () |
+function: |
+ |
+.ES |
+print map(str, DEFAULT_TARGETS) # originally [] |
+Default('foo') |
+print map(str, DEFAULT_TARGETS) # now a node ['foo'] |
+Default('bar') |
+print map(str, DEFAULT_TARGETS) # now a node ['foo', 'bar'] |
+Default(None) |
+print map(str, DEFAULT_TARGETS) # back to [] |
+.EE |
+.IP |
+Consequently, be sure to use |
+.B DEFAULT_TARGETS |
+only after you've made all of your |
+.BR Default () |
+calls, |
+or else simply be careful of the order |
+of these statements in your SConscript files |
+so that you don't look for a specific |
+default target before it's actually been added to the list. |
+ |
+.SS Construction Variables |
+.\" XXX From Gary Ruben, 23 April 2002: |
+.\" I think it would be good to have an example with each construction |
+.\" variable description in the documentation. |
+.\" eg. |
+.\" CC The C compiler |
+.\" Example: env["CC"] = "c68x" |
+.\" Default: env["CC"] = "cc" |
+.\" |
+.\" CCCOM The command line ... |
+.\" Example: |
+.\" To generate the compiler line c68x -ps -qq -mr -o $TARGET $SOURCES |
+.\" env["CC"] = "c68x" |
+.\" env["CFLAGS"] = "-ps -qq -mr" |
+.\" env["CCCOM"] = "$CC $CFLAGS -o $TARGET $SOURCES |
+.\" Default: |
+.\" (I dunno what this is ;-) |
+A construction environment has an associated dictionary of |
+.I construction variables |
+that are used by built-in or user-supplied build rules. |
+Construction variables must follow the same rules for |
+Python identifiers: |
+the initial character must be an underscore or letter, |
+followed by any number of underscores, letters, or digits. |
+ |
+A number of useful construction variables are automatically defined by |
+scons for each supported platform, and additional construction variables |
+can be defined by the user. The following is a list of the automatically |
+defined construction variables: |
+ |
+'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" |
+'\" BEGIN GENERATED CONSTRUCTION VARIABLE DESCRIPTIONS |
+'\" |
+'\" The descriptions below of the various SCons construction variables |
+'\" are generated from the .xml files that live next to the various |
+'\" Python modules in the build enginer library. If you're reading |
+'\" this [gnt]roff file with an eye towards patching this man page, |
+'\" you can still submit a diff against this text, but it will have to |
+'\" be translated to a diff against the underlying .xml file before the |
+'\" patch is actually accepted. If you do that yourself, it will make |
+'\" it easier to integrate the patch. |
+'\" |
+'\" BEGIN GENERATED CONSTRUCTION VARIABLE DESCRIPTIONS |
+'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" |
+ |
+.IP AR |
+The static library archiver. |
+ |
+.IP ARCHITECTURE |
+Specifies the system architecture for which |
+the package is being built. |
+The default is the system architecture |
+of the machine on which SCons is running. |
+This is used to fill in the |
+.B Architecture: |
+field in an Ipkg |
+\fBcontrol\fP file, |
+and as part of the name of a generated RPM file. |
+ |
+.IP ARCOM |
+The command line used to generate a static library from object files. |
+ |
+.IP ARCOMSTR |
+The string displayed when an object file |
+is generated from an assembly-language source file. |
+If this is not set, then $ARCOM (the command line) is displayed. |
+ |
+.ES |
+env = Environment(ARCOMSTR = "Archiving $TARGET") |
+.EE |
+ |
+.IP ARFLAGS |
+General options passed to the static library archiver. |
+ |
+.IP AS |
+The assembler. |
+ |
+.IP ASCOM |
+The command line used to generate an object file |
+from an assembly-language source file. |
+ |
+.IP ASCOMSTR |
+The string displayed when an object file |
+is generated from an assembly-language source file. |
+If this is not set, then $ASCOM (the command line) is displayed. |
+ |
+.ES |
+env = Environment(ASCOMSTR = "Assembling $TARGET") |
+.EE |
+ |
+.IP ASFLAGS |
+General options passed to the assembler. |
+ |
+.IP ASPPCOM |
+The command line used to assemble an assembly-language |
+source file into an object file |
+after first running the file through the C preprocessor. |
+Any options specified |
+in the $ASFLAGS and $CPPFLAGS construction variables |
+are included on this command line. |
+ |
+.IP ASPPCOMSTR |
+The string displayed when an object file |
+is generated from an assembly-language source file |
+after first running the file through the C preprocessor. |
+If this is not set, then $ASPPCOM (the command line) is displayed. |
+ |
+.ES |
+env = Environment(ASPPCOMSTR = "Assembling $TARGET") |
+.EE |
+ |
+.IP ASPPFLAGS |
+General options when an assembling an assembly-language |
+source file into an object file |
+after first running the file through the C preprocessor. |
+The default is to use the value of $ASFLAGS. |
+ |
+.IP BIBTEX |
+The bibliography generator for the TeX formatter and typesetter and the |
+LaTeX structured formatter and typesetter. |
+ |
+.IP BIBTEXCOM |
+The command line used to call the bibliography generator for the |
+TeX formatter and typesetter and the LaTeX structured formatter and |
+typesetter. |
+ |
+.IP BIBTEXCOMSTR |
+The string displayed when generating a bibliography |
+for TeX or LaTeX. |
+If this is not set, then $BIBTEXCOM (the command line) is displayed. |
+ |
+.ES |
+env = Environment(BIBTEXCOMSTR = "Generating bibliography $TARGET") |
+.EE |
+ |
+.IP BIBTEXFLAGS |
+General options passed to the bibliography generator for the TeX formatter |
+and typesetter and the LaTeX structured formatter and typesetter. |
+ |
+.IP BITKEEPER |
+The BitKeeper executable. |
+ |
+.IP BITKEEPERCOM |
+The command line for |
+fetching source files using BitKeeper. |
+ |
+.IP BITKEEPERCOMSTR |
+The string displayed when fetching |
+a source file using BitKeeper. |
+If this is not set, then $BITKEEPERCOM |
+(the command line) is displayed. |
+ |
+.IP BITKEEPERGET |
+The command ($BITKEEPER) and subcommand |
+for fetching source files using BitKeeper. |
+ |
+.IP BITKEEPERGETFLAGS |
+Options that are passed to the BitKeeper |
+.B get |
+subcommand. |
+ |
+.IP BUILDERS |
+A dictionary mapping the names of the builders |
+available through this environment |
+to underlying Builder objects. |
+Builders named |
+Alias, CFile, CXXFile, DVI, Library, Object, PDF, PostScript, and Program |
+are available by default. |
+If you initialize this variable when an |
+Environment is created: |
+ |
+.ES |
+env = Environment(BUILDERS = {'NewBuilder' : foo}) |
+.EE |
+.IP |
+the default Builders will no longer be available. |
+To use a new Builder object in addition to the default Builders, |
+add your new Builder object like this: |
+ |
+.ES |
+env = Environment() |
+env.Append(BUILDERS = {'NewBuilder' : foo}) |
+.EE |
+.IP |
+or this: |
+ |
+.ES |
+env = Environment() |
+env['BUILDERS]['NewBuilder'] = foo |
+.EE |
+ |
+.IP CC |
+The C compiler. |
+ |
+.IP CCCOM |
+The command line used to compile a C source file to a (static) object |
+file. Any options specified in the $CFLAGS, $CCFLAGS and |
+$CPPFLAGS construction variables are included on this command |
+line. |
+ |
+.IP CCCOMSTR |
+The string displayed when a C source file |
+is compiled to a (static) object file. |
+If this is not set, then $CCCOM (the command line) is displayed. |
+ |
+.ES |
+env = Environment(CCCOMSTR = "Compiling static object $TARGET") |
+.EE |
+ |
+.IP CCFLAGS |
+General options that are passed to the C and C++ compilers. |
+ |
+.IP CCPCHFLAGS |
+Options added to the compiler command line |
+to support building with precompiled headers. |
+The default value expands expands to the appropriate |
+Microsoft Visual C++ command-line options |
+when the $PCH construction variable is set. |
+ |
+.IP CCPDBFLAGS |
+Options added to the compiler command line |
+to support storing debugging information in a |
+Microsoft Visual C++ PDB file. |
+The default value expands expands to appropriate |
+Microsoft Visual C++ command-line options |
+when the $PDB construction variable is set. |
+ |
+The Visual C++ compiler option that SCons uses by default |
+to generate PDB information is \fB/Z7\fP. |
+This works correctly with parallel (\fB\-j\fP) builds |
+because it embeds the debug information in the intermediate object files, |
+as opposed to sharing a single PDB file between multiple object files. |
+This is also the only way to get debug information |
+embedded into a static library. |
+Using the \fB/Zi\fP instead may yield improved |
+link-time performance, |
+although parallel builds will no longer work. |
+ |
+You can generate PDB files with the \fB/Zi\fP |
+switch by overriding the default $CCPDBFLAGS variable as follows: |
+ |
+.ES |
+env['CCPDBFLAGS'] = ['${(PDB and "/Zi /Fd%s" % File(PDB)) or ""}'] |
+.EE |
+.IP |
+An alternative would be to use the \fB/Zi\fP |
+to put the debugging information in a separate \fB.pdb\fP |
+file for each object file by overriding |
+the $CCPDBFLAGS variable as follows: |
+ |
+.ES |
+env['CCPDBFLAGS'] = '/Zi /Fd${TARGET}.pdb' |
+.EE |
+ |
+.IP CCVERSION |
+The version number of the C compiler. |
+This may or may not be set, |
+depending on the specific C compiler being used. |
+ |
+.IP CFILESUFFIX |
+The suffix for C source files. |
+This is used by the internal CFile builder |
+when generating C files from Lex (.l) or YACC (.y) input files. |
+The default suffix, of course, is |
+.B .c |
+(lower case). |
+On case-insensitive systems (like Windows), |
+SCons also treats |
+.B .C |
+(upper case) files |
+as C files. |
+ |
+.IP CFLAGS |
+General options that are passed to the C compiler (C only; not C++). |
+ |
+.IP CHANGE_SPECFILE |
+A hook for modifying the file that controls the packaging build |
+(the \fB.spec\fP for RPM, |
+the \fBcontrol\fP for Ipkg, |
+the \fB.wxs\fP for MSI). |
+If set, the function will be called |
+after the SCons template for the file has been written. |
+XXX |
+ |
+.IP CHANGED_SOURCES |
+A reserved variable name |
+that may not be set or used in a construction environment. |
+(See "Variable Substitution," below.) |
+ |
+.IP CHANGED_TARGETS |
+A reserved variable name |
+that may not be set or used in a construction environment. |
+(See "Variable Substitution," below.) |
+ |
+.IP CHANGELOG |
+The name of a file containing the change log text |
+to be included in the package. |
+This is included as the |
+.B %changelog |
+section of the RPM |
+\fB.spec\fP file. |
+ |
+.IP _concat |
+A function used to produce variables like $_CPPINCFLAGS. It takes |
+four or five |
+arguments: a prefix to concatenate onto each element, a list of |
+elements, a suffix to concatenate onto each element, an environment |
+for variable interpolation, and an optional function that will be |
+called to transform the list before concatenation. |
+ |
+.ES |
+env['_CPPINCFLAGS'] = '$( ${_concat(INCPREFIX, CPPPATH, INCSUFFIX, __env__, RDirs)} $)', |
+.EE |
+ |
+.IP CONFIGUREDIR |
+The name of the directory in which |
+Configure context test files are written. |
+The default is |
+.B .sconf_temp |
+in the top-level directory |
+containing the |
+.B SConstruct |
+file. |
+ |
+.IP CONFIGURELOG |
+The name of the Configure context log file. |
+The default is |
+.B config.log |
+in the top-level directory |
+containing the |
+.B SConstruct |
+file. |
+ |
+.IP _CPPDEFFLAGS |
+An automatically-generated construction variable |
+containing the C preprocessor command-line options |
+to define values. |
+The value of $_CPPDEFFLAGS is created |
+by appending $CPPDEFPREFIX and $CPPDEFSUFFIX |
+to the beginning and end |
+of each definition in $CPPDEFINES. |
+ |
+.IP CPPDEFINES |
+A platform independent specification of C preprocessor definitions. |
+The definitions will be added to command lines |
+through the automatically-generated |
+$_CPPDEFFLAGS construction variable (see above), |
+which is constructed according to |
+the type of value of $CPPDEFINES: |
+ |
+If $CPPDEFINES is a string, |
+the values of the |
+$CPPDEFPREFIX and $CPPDEFSUFFIX |
+construction variables |
+will be added to the beginning and end. |
+ |
+.ES |
+# Will add -Dxyz to POSIX compiler command lines, |
+# and /Dxyz to Microsoft Visual C++ command lines. |
+env = Environment(CPPDEFINES='xyz') |
+.EE |
+.IP |
+If $CPPDEFINES is a list, |
+the values of the |
+$CPPDEFPREFIX and $CPPDEFSUFFIX |
+construction variables |
+will be appended to the beginning and end |
+of each element in the list. |
+If any element is a list or tuple, |
+then the first item is the name being |
+defined and the second item is its value: |
+ |
+.ES |
+# Will add -DB=2 -DA to POSIX compiler command lines, |
+# and /DB=2 /DA to Microsoft Visual C++ command lines. |
+env = Environment(CPPDEFINES=[('B', 2), 'A']) |
+.EE |
+.IP |
+If $CPPDEFINES is a dictionary, |
+the values of the |
+$CPPDEFPREFIX and $CPPDEFSUFFIX |
+construction variables |
+will be appended to the beginning and end |
+of each item from the dictionary. |
+The key of each dictionary item |
+is a name being defined |
+to the dictionary item's corresponding value; |
+if the value is |
+.BR None , |
+then the name is defined without an explicit value. |
+Note that the resulting flags are sorted by keyword |
+to ensure that the order of the options on the |
+command line is consistent each time |
+.B scons |
+is run. |
+ |
+.ES |
+# Will add -DA -DB=2 to POSIX compiler command lines, |
+# and /DA /DB=2 to Microsoft Visual C++ command lines. |
+env = Environment(CPPDEFINES={'B':2, 'A':None}) |
+.EE |
+ |
+.IP CPPDEFPREFIX |
+The prefix used to specify preprocessor definitions |
+on the C compiler command line. |
+This will be appended to the beginning of each definition |
+in the $CPPDEFINES construction variable |
+when the $_CPPDEFFLAGS variable is automatically generated. |
+ |
+.IP CPPDEFSUFFIX |
+The suffix used to specify preprocessor definitions |
+on the C compiler command line. |
+This will be appended to the end of each definition |
+in the $CPPDEFINES construction variable |
+when the $_CPPDEFFLAGS variable is automatically generated. |
+ |
+.IP CPPFLAGS |
+User-specified C preprocessor options. |
+These will be included in any command that uses the C preprocessor, |
+including not just compilation of C and C++ source files |
+via the $CCCOM, |
+$SHCCCOM, |
+$CXXCOM and |
+$SHCXXCOM command lines, |
+but also the $FORTRANPPCOM, |
+$SHFORTRANPPCOM, |
+$F77PPCOM and |
+$SHF77PPCOM command lines |
+used to compile a Fortran source file, |
+and the $ASPPCOM command line |
+used to assemble an assembly language source file, |
+after first running each file through the C preprocessor. |
+Note that this variable does |
+.I not |
+contain |
+.B \-I |
+(or similar) include search path options |
+that scons generates automatically from $CPPPATH. |
+See $_CPPINCFLAGS, below, |
+for the variable that expands to those options. |
+ |
+.IP _CPPINCFLAGS |
+An automatically-generated construction variable |
+containing the C preprocessor command-line options |
+for specifying directories to be searched for include files. |
+The value of $_CPPINCFLAGS is created |
+by appending $INCPREFIX and $INCSUFFIX |
+to the beginning and end |
+of each directory in $CPPPATH. |
+ |
+.IP CPPPATH |
+The list of directories that the C preprocessor will search for include |
+directories. The C/C++ implicit dependency scanner will search these |
+directories for include files. Don't explicitly put include directory |
+arguments in CCFLAGS or CXXFLAGS because the result will be non-portable |
+and the directories will not be searched by the dependency scanner. Note: |
+directory names in CPPPATH will be looked-up relative to the SConscript |
+directory when they are used in a command. To force |
+.B scons |
+to look-up a directory relative to the root of the source tree use #: |
+ |
+.ES |
+env = Environment(CPPPATH='#/include') |
+.EE |
+.IP |
+The directory look-up can also be forced using the |
+.BR Dir () |
+function: |
+ |
+.ES |
+include = Dir('include') |
+env = Environment(CPPPATH=include) |
+.EE |
+.IP |
+The directory list will be added to command lines |
+through the automatically-generated |
+$_CPPINCFLAGS |
+construction variable, |
+which is constructed by |
+appending the values of the |
+$INCPREFIX and $INCSUFFIX |
+construction variables |
+to the beginning and end |
+of each directory in $CPPPATH. |
+Any command lines you define that need |
+the CPPPATH directory list should |
+include $_CPPINCFLAGS: |
+ |
+.ES |
+env = Environment(CCCOM="my_compiler $_CPPINCFLAGS -c -o $TARGET $SOURCE") |
+.EE |
+ |
+.IP CPPSUFFIXES |
+The list of suffixes of files that will be scanned |
+for C preprocessor implicit dependencies |
+(#include lines). |
+The default list is: |
+ |
+.ES |
+[".c", ".C", ".cxx", ".cpp", ".c++", ".cc", |
+ ".h", ".H", ".hxx", ".hpp", ".hh", |
+ ".F", ".fpp", ".FPP", |
+ ".m", ".mm", |
+ ".S", ".spp", ".SPP"] |
+.EE |
+ |
+.IP CVS |
+The CVS executable. |
+ |
+.IP CVSCOFLAGS |
+Options that are passed to the CVS checkout subcommand. |
+ |
+.IP CVSCOM |
+The command line used to |
+fetch source files from a CVS repository. |
+ |
+.IP CVSCOMSTR |
+The string displayed when fetching |
+a source file from a CVS repository. |
+If this is not set, then $CVSCOM |
+(the command line) is displayed. |
+ |
+.IP CVSFLAGS |
+General options that are passed to CVS. |
+By default, this is set to |
+.B "-d $CVSREPOSITORY" |
+to specify from where the files must be fetched. |
+ |
+.IP CVSREPOSITORY |
+The path to the CVS repository. |
+This is referenced in the default |
+$CVSFLAGS value. |
+ |
+.IP CXX |
+The C++ compiler. |
+ |
+.IP CXXCOM |
+The command line used to compile a C++ source file to an object file. |
+Any options specified in the $CXXFLAGS and |
+$CPPFLAGS construction variables |
+are included on this command line. |
+ |
+.IP CXXCOMSTR |
+The string displayed when a C++ source file |
+is compiled to a (static) object file. |
+If this is not set, then $CXXCOM (the command line) is displayed. |
+ |
+.ES |
+env = Environment(CXXCOMSTR = "Compiling static object $TARGET") |
+.EE |
+ |
+.IP CXXFILESUFFIX |
+The suffix for C++ source files. |
+This is used by the internal CXXFile builder |
+when generating C++ files from Lex (.ll) or YACC (.yy) input files. |
+The default suffix is |
+.BR .cc . |
+SCons also treats files with the suffixes |
+.BR .cpp , |
+.BR .cxx , |
+.BR .c++ , |
+and |
+.B .C++ |
+as C++ files, |
+and files with |
+.B .mm |
+suffixes as Objective C++ files. |
+On case-sensitive systems (Linux, UNIX, and other POSIX-alikes), |
+SCons also treats |
+.B .C |
+(upper case) files |
+as C++ files. |
+ |
+.IP CXXFLAGS |
+General options that are passed to the C++ compiler. |
+By default, this includes the value of $CCFLAGS, |
+so that setting $CCFLAGS affects both C and C++ compilation. |
+If you want to add C++-specific flags, |
+you must set or override the value of $CXXFLAGS. |
+ |
+.IP CXXVERSION |
+The version number of the C++ compiler. |
+This may or may not be set, |
+depending on the specific C++ compiler being used. |
+ |
+.IP DESCRIPTION |
+A long description of the project being packaged. |
+This is included in the relevant section |
+of the file that controls the packaging build. |
+ |
+.IP DESCRIPTION_lang |
+A language-specific long description for |
+the specified \fIlang\fP. |
+This is used to populate a |
+.B "%description -l" |
+section of an RPM |
+\fB.spec\fP file. |
+ |
+.IP Dir |
+A function that converts a string |
+into a Dir instance relative to the target being built. |
+ |
+.IP Dirs |
+A function that converts a list of strings |
+into a list of Dir instances relative to the target being built. |
+ |
+.IP DSUFFIXES |
+The list of suffixes of files that will be scanned |
+for imported D package files. |
+The default list is: |
+ |
+.ES |
+['.d'] |
+.EE |
+ |
+.IP DVIPDF |
+The TeX DVI file to PDF file converter. |
+ |
+.IP DVIPDFCOM |
+The command line used to convert TeX DVI files into a PDF file. |
+ |
+.IP DVIPDFCOMSTR |
+The string displayed when a TeX DVI file |
+is converted into a PDF file. |
+If this is not set, then $DVIPDFCOM (the command line) is displayed. |
+ |
+.IP DVIPDFFLAGS |
+General options passed to the TeX DVI file to PDF file converter. |
+ |
+.IP DVIPS |
+The TeX DVI file to PostScript converter. |
+ |
+.IP DVIPSFLAGS |
+General options passed to the TeX DVI file to PostScript converter. |
+ |
+.IP ENV |
+A dictionary of environment variables |
+to use when invoking commands. When |
+$ENV is used in a command all list |
+values will be joined using the path separator and any other non-string |
+values will simply be coerced to a string. |
+Note that, by default, |
+.B scons |
+does |
+.I not |
+propagate the environment in force when you |
+execute |
+.B scons |
+to the commands used to build target files. |
+This is so that builds will be guaranteed |
+repeatable regardless of the environment |
+variables set at the time |
+.B scons |
+is invoked. |
+ |
+If you want to propagate your |
+environment variables |
+to the commands executed |
+to build target files, |
+you must do so explicitly: |
+ |
+.ES |
+import os |
+env = Environment(ENV = os.environ) |
+.EE |
+.IP |
+Note that you can choose only to propagate |
+certain environment variables. |
+A common example is |
+the system |
+.B PATH |
+environment variable, |
+so that |
+.B scons |
+uses the same utilities |
+as the invoking shell (or other process): |
+ |
+.ES |
+import os |
+env = Environment(ENV = {'PATH' : os.environ['PATH']}) |
+.EE |
+ |
+.IP ESCAPE |
+A function that will be called to escape shell special characters in |
+command lines. The function should take one argument: the command line |
+string to escape; and should return the escaped command line. |
+ |
+.IP F77 |
+The Fortran 77 compiler. |
+You should normally set the $FORTRAN variable, |
+which specifies the default Fortran compiler |
+for all Fortran versions. |
+You only need to set $F77 if you need to use a specific compiler |
+or compiler version for Fortran 77 files. |
+ |
+.IP F77COM |
+The command line used to compile a Fortran 77 source file to an object file. |
+You only need to set $F77COM if you need to use a specific |
+command line for Fortran 77 files. |
+You should normally set the $FORTRANCOM variable, |
+which specifies the default command line |
+for all Fortran versions. |
+ |
+.IP F77COMSTR |
+The string displayed when a Fortran 77 source file |
+is compiled to an object file. |
+If this is not set, then $F77COM or $FORTRANCOM |
+(the command line) is displayed. |
+ |
+.IP F77FILESUFFIXES |
+The list of file extensions for which the F77 dialect will be used. By |
+default, this is ['.f77'] |
+ |
+.IP F77FLAGS |
+General user-specified options that are passed to the Fortran 77 compiler. |
+Note that this variable does |
+.I not |
+contain |
+.B \-I |
+(or similar) include search path options |
+that scons generates automatically from $F77PATH. |
+See |
+$_F77INCFLAGS |
+below, |
+for the variable that expands to those options. |
+You only need to set $F77FLAGS if you need to define specific |
+user options for Fortran 77 files. |
+You should normally set the $FORTRANFLAGS variable, |
+which specifies the user-specified options |
+passed to the default Fortran compiler |
+for all Fortran versions. |
+ |
+.IP _F77INCFLAGS |
+An automatically-generated construction variable |
+containing the Fortran 77 compiler command-line options |
+for specifying directories to be searched for include files. |
+The value of $_F77INCFLAGS is created |
+by appending $INCPREFIX and $INCSUFFIX |
+to the beginning and end |
+of each directory in $F77PATH. |
+ |
+.IP F77PATH |
+The list of directories that the Fortran 77 compiler will search for include |
+directories. The implicit dependency scanner will search these |
+directories for include files. Don't explicitly put include directory |
+arguments in $F77FLAGS because the result will be non-portable |
+and the directories will not be searched by the dependency scanner. Note: |
+directory names in $F77PATH will be looked-up relative to the SConscript |
+directory when they are used in a command. To force |
+.B scons |
+to look-up a directory relative to the root of the source tree use #: |
+You only need to set $F77PATH if you need to define a specific |
+include path for Fortran 77 files. |
+You should normally set the $FORTRANPATH variable, |
+which specifies the include path |
+for the default Fortran compiler |
+for all Fortran versions. |
+ |
+.ES |
+env = Environment(F77PATH='#/include') |
+.EE |
+.IP |
+The directory look-up can also be forced using the |
+.BR Dir () |
+function: |
+ |
+.ES |
+include = Dir('include') |
+env = Environment(F77PATH=include) |
+.EE |
+.IP |
+The directory list will be added to command lines |
+through the automatically-generated |
+$_F77INCFLAGS |
+construction variable, |
+which is constructed by |
+appending the values of the |
+$INCPREFIX and $INCSUFFIX |
+construction variables |
+to the beginning and end |
+of each directory in $F77PATH. |
+Any command lines you define that need |
+the F77PATH directory list should |
+include $_F77INCFLAGS: |
+ |
+.ES |
+env = Environment(F77COM="my_compiler $_F77INCFLAGS -c -o $TARGET $SOURCE") |
+.EE |
+ |
+.IP F77PPCOM |
+The command line used to compile a Fortran 77 source file to an object file |
+after first running the file through the C preprocessor. |
+Any options specified in the $F77FLAGS and $CPPFLAGS construction variables |
+are included on this command line. |
+You only need to set $F77PPCOM if you need to use a specific |
+C-preprocessor command line for Fortran 77 files. |
+You should normally set the $FORTRANPPCOM variable, |
+which specifies the default C-preprocessor command line |
+for all Fortran versions. |
+ |
+.IP F77PPCOMSTR |
+The string displayed when a Fortran 77 source file |
+is compiled to an object file |
+after first running the file through the C preprocessor. |
+If this is not set, then $F77PPCOM or $FORTRANPPCOM |
+(the command line) is displayed. |
+ |
+.IP F77PPFILESUFFIXES |
+The list of file extensions for which the compilation + preprocessor pass for |
+F77 dialect will be used. By default, this is empty |
+ |
+.IP F90 |
+The Fortran 90 compiler. |
+You should normally set the $FORTRAN variable, |
+which specifies the default Fortran compiler |
+for all Fortran versions. |
+You only need to set $F90 if you need to use a specific compiler |
+or compiler version for Fortran 90 files. |
+ |
+.IP F90COM |
+The command line used to compile a Fortran 90 source file to an object file. |
+You only need to set $F90COM if you need to use a specific |
+command line for Fortran 90 files. |
+You should normally set the $FORTRANCOM variable, |
+which specifies the default command line |
+for all Fortran versions. |
+ |
+.IP F90COMSTR |
+The string displayed when a Fortran 90 source file |
+is compiled to an object file. |
+If this is not set, then $F90COM or $FORTRANCOM |
+(the command line) is displayed. |
+ |
+.IP F90FILESUFFIXES |
+The list of file extensions for which the F90 dialect will be used. By |
+default, this is ['.f90'] |
+ |
+.IP F90FLAGS |
+General user-specified options that are passed to the Fortran 90 compiler. |
+Note that this variable does |
+.I not |
+contain |
+.B \-I |
+(or similar) include search path options |
+that scons generates automatically from $F90PATH. |
+See |
+$_F90INCFLAGS |
+below, |
+for the variable that expands to those options. |
+You only need to set $F90FLAGS if you need to define specific |
+user options for Fortran 90 files. |
+You should normally set the $FORTRANFLAGS variable, |
+which specifies the user-specified options |
+passed to the default Fortran compiler |
+for all Fortran versions. |
+ |
+.IP _F90INCFLAGS |
+An automatically-generated construction variable |
+containing the Fortran 90 compiler command-line options |
+for specifying directories to be searched for include files. |
+The value of $_F90INCFLAGS is created |
+by appending $INCPREFIX and $INCSUFFIX |
+to the beginning and end |
+of each directory in $F90PATH. |
+ |
+.IP F90PATH |
+The list of directories that the Fortran 90 compiler will search for include |
+directories. The implicit dependency scanner will search these |
+directories for include files. Don't explicitly put include directory |
+arguments in $F90FLAGS because the result will be non-portable |
+and the directories will not be searched by the dependency scanner. Note: |
+directory names in $F90PATH will be looked-up relative to the SConscript |
+directory when they are used in a command. To force |
+.B scons |
+to look-up a directory relative to the root of the source tree use #: |
+You only need to set $F90PATH if you need to define a specific |
+include path for Fortran 90 files. |
+You should normally set the $FORTRANPATH variable, |
+which specifies the include path |
+for the default Fortran compiler |
+for all Fortran versions. |
+ |
+.ES |
+env = Environment(F90PATH='#/include') |
+.EE |
+.IP |
+The directory look-up can also be forced using the |
+.BR Dir () |
+function: |
+ |
+.ES |
+include = Dir('include') |
+env = Environment(F90PATH=include) |
+.EE |
+.IP |
+The directory list will be added to command lines |
+through the automatically-generated |
+$_F90INCFLAGS |
+construction variable, |
+which is constructed by |
+appending the values of the |
+$INCPREFIX and $INCSUFFIX |
+construction variables |
+to the beginning and end |
+of each directory in $F90PATH. |
+Any command lines you define that need |
+the F90PATH directory list should |
+include $_F90INCFLAGS: |
+ |
+.ES |
+env = Environment(F90COM="my_compiler $_F90INCFLAGS -c -o $TARGET $SOURCE") |
+.EE |
+ |
+.IP F90PPCOM |
+The command line used to compile a Fortran 90 source file to an object file |
+after first running the file through the C preprocessor. |
+Any options specified in the $F90FLAGS and $CPPFLAGS construction variables |
+are included on this command line. |
+You only need to set $F90PPCOM if you need to use a specific |
+C-preprocessor command line for Fortran 90 files. |
+You should normally set the $FORTRANPPCOM variable, |
+which specifies the default C-preprocessor command line |
+for all Fortran versions. |
+ |
+.IP F90PPCOMSTR |
+The string displayed when a Fortran 90 source file |
+is compiled after first running the file through the C preprocessor. |
+If this is not set, then $F90PPCOM or $FORTRANPPCOM |
+(the command line) is displayed. |
+ |
+.IP F90PPFILESUFFIXES |
+The list of file extensions for which the compilation + preprocessor pass for |
+F90 dialect will be used. By default, this is empty |
+ |
+.IP F95 |
+The Fortran 95 compiler. |
+You should normally set the $FORTRAN variable, |
+which specifies the default Fortran compiler |
+for all Fortran versions. |
+You only need to set $F95 if you need to use a specific compiler |
+or compiler version for Fortran 95 files. |
+ |
+.IP F95COM |
+The command line used to compile a Fortran 95 source file to an object file. |
+You only need to set $F95COM if you need to use a specific |
+command line for Fortran 95 files. |
+You should normally set the $FORTRANCOM variable, |
+which specifies the default command line |
+for all Fortran versions. |
+ |
+.IP F95COMSTR |
+The string displayed when a Fortran 95 source file |
+is compiled to an object file. |
+If this is not set, then $F95COM or $FORTRANCOM |
+(the command line) is displayed. |
+ |
+.IP F95FILESUFFIXES |
+The list of file extensions for which the F95 dialect will be used. By |
+default, this is ['.f95'] |
+ |
+.IP F95FLAGS |
+General user-specified options that are passed to the Fortran 95 compiler. |
+Note that this variable does |
+.I not |
+contain |
+.B \-I |
+(or similar) include search path options |
+that scons generates automatically from $F95PATH. |
+See |
+$_F95INCFLAGS |
+below, |
+for the variable that expands to those options. |
+You only need to set $F95FLAGS if you need to define specific |
+user options for Fortran 95 files. |
+You should normally set the $FORTRANFLAGS variable, |
+which specifies the user-specified options |
+passed to the default Fortran compiler |
+for all Fortran versions. |
+ |
+.IP _F95INCFLAGS |
+An automatically-generated construction variable |
+containing the Fortran 95 compiler command-line options |
+for specifying directories to be searched for include files. |
+The value of $_F95INCFLAGS is created |
+by appending $INCPREFIX and $INCSUFFIX |
+to the beginning and end |
+of each directory in $F95PATH. |
+ |
+.IP F95PATH |
+The list of directories that the Fortran 95 compiler will search for include |
+directories. The implicit dependency scanner will search these |
+directories for include files. Don't explicitly put include directory |
+arguments in $F95FLAGS because the result will be non-portable |
+and the directories will not be searched by the dependency scanner. Note: |
+directory names in $F95PATH will be looked-up relative to the SConscript |
+directory when they are used in a command. To force |
+.B scons |
+to look-up a directory relative to the root of the source tree use #: |
+You only need to set $F95PATH if you need to define a specific |
+include path for Fortran 95 files. |
+You should normally set the $FORTRANPATH variable, |
+which specifies the include path |
+for the default Fortran compiler |
+for all Fortran versions. |
+ |
+.ES |
+env = Environment(F95PATH='#/include') |
+.EE |
+.IP |
+The directory look-up can also be forced using the |
+.BR Dir () |
+function: |
+ |
+.ES |
+include = Dir('include') |
+env = Environment(F95PATH=include) |
+.EE |
+.IP |
+The directory list will be added to command lines |
+through the automatically-generated |
+$_F95INCFLAGS |
+construction variable, |
+which is constructed by |
+appending the values of the |
+$INCPREFIX and $INCSUFFIX |
+construction variables |
+to the beginning and end |
+of each directory in $F95PATH. |
+Any command lines you define that need |
+the F95PATH directory list should |
+include $_F95INCFLAGS: |
+ |
+.ES |
+env = Environment(F95COM="my_compiler $_F95INCFLAGS -c -o $TARGET $SOURCE") |
+.EE |
+ |
+.IP F95PPCOM |
+The command line used to compile a Fortran 95 source file to an object file |
+after first running the file through the C preprocessor. |
+Any options specified in the $F95FLAGS and $CPPFLAGS construction variables |
+are included on this command line. |
+You only need to set $F95PPCOM if you need to use a specific |
+C-preprocessor command line for Fortran 95 files. |
+You should normally set the $FORTRANPPCOM variable, |
+which specifies the default C-preprocessor command line |
+for all Fortran versions. |
+ |
+.IP F95PPCOMSTR |
+The string displayed when a Fortran 95 source file |
+is compiled to an object file |
+after first running the file through the C preprocessor. |
+If this is not set, then $F95PPCOM or $FORTRANPPCOM |
+(the command line) is displayed. |
+ |
+.IP F95PPFILESUFFIXES |
+The list of file extensions for which the compilation + preprocessor pass for |
+F95 dialect will be used. By default, this is empty |
+ |
+.IP File |
+A function that converts a string into a File instance relative to the |
+target being built. |
+ |
+.IP FORTRAN |
+The default Fortran compiler |
+for all versions of Fortran. |
+ |
+.IP FORTRANCOM |
+The command line used to compile a Fortran source file to an object file. |
+By default, any options specified |
+in the $FORTRANFLAGS, |
+$CPPFLAGS, |
+$_CPPDEFFLAGS, |
+$_FORTRANMODFLAG, and |
+$_FORTRANINCFLAGS construction variables |
+are included on this command line. |
+ |
+.IP FORTRANCOMSTR |
+The string displayed when a Fortran source file |
+is compiled to an object file. |
+If this is not set, then $FORTRANCOM |
+(the command line) is displayed. |
+ |
+.IP FORTRANFILESUFFIXES |
+The list of file extensions for which the FORTRAN dialect will be used. By |
+default, this is ['.f', '.for', '.ftn'] |
+ |
+.IP FORTRANFLAGS |
+General user-specified options that are passed to the Fortran compiler. |
+Note that this variable does |
+.I not |
+contain |
+.B \-I |
+(or similar) include or module search path options |
+that scons generates automatically from $FORTRANPATH. |
+See |
+$_FORTRANINCFLAGS and $_FORTRANMODFLAG, |
+below, |
+for the variables that expand those options. |
+ |
+.IP _FORTRANINCFLAGS |
+An automatically-generated construction variable |
+containing the Fortran compiler command-line options |
+for specifying directories to be searched for include |
+files and module files. |
+The value of $_FORTRANINCFLAGS is created |
+by prepending/appending $INCPREFIX and $INCSUFFIX |
+to the beginning and end |
+of each directory in $FORTRANPATH. |
+ |
+.IP FORTRANMODDIR |
+Directory location where the Fortran compiler should place |
+any module files it generates. This variable is empty, by default. Some |
+Fortran compilers will internally append this directory in the search path |
+for module files, as well. |
+ |
+.IP FORTRANMODDIRPREFIX |
+The prefix used to specify a module directory on the Fortran compiler command |
+line. |
+This will be appended to the beginning of the directory |
+in the $FORTRANMODDIR construction variables |
+when the $_FORTRANMODFLAG variables is automatically generated. |
+ |
+.IP FORTRANMODDIRSUFFIX |
+The suffix used to specify a module directory on the Fortran compiler command |
+line. |
+This will be appended to the beginning of the directory |
+in the $FORTRANMODDIR construction variables |
+when the $_FORTRANMODFLAG variables is automatically generated. |
+ |
+.IP _FORTRANMODFLAG |
+An automatically-generated construction variable |
+containing the Fortran compiler command-line option |
+for specifying the directory location where the Fortran |
+compiler should place any module files that happen to get |
+generated during compilation. |
+The value of $_FORTRANMODFLAG is created |
+by prepending/appending $FORTRANMODDIRPREFIX and |
+$FORTRANMODDIRSUFFIX |
+to the beginning and end of the directory in $FORTRANMODDIR. |
+ |
+.IP FORTRANMODPREFIX |
+The module file prefix used by the Fortran compiler. SCons assumes that |
+the Fortran compiler follows the quasi-standard naming convention for |
+module files of |
+.BR module_name.mod . |
+As a result, this variable is left empty, by default. For situations in |
+which the compiler does not necessarily follow the normal convention, |
+the user may use this variable. Its value will be appended to every |
+module file name as scons attempts to resolve dependencies. |
+ |
+.IP FORTRANMODSUFFIX |
+The module file suffix used by the Fortran compiler. SCons assumes that |
+the Fortran compiler follows the quasi-standard naming convention for |
+module files of |
+.BR module_name.mod . |
+As a result, this variable is set to ".mod", by default. For situations |
+in which the compiler does not necessarily follow the normal convention, |
+the user may use this variable. Its value will be appended to every |
+module file name as scons attempts to resolve dependencies. |
+ |
+.IP FORTRANPATH |
+The list of directories that the Fortran compiler will search for |
+include files and (for some compilers) module files. The Fortran implicit |
+dependency scanner will search these directories for include files (but |
+not module files since they are autogenerated and, as such, may not |
+actually exist at the time the scan takes place). Don't explicitly put |
+include directory arguments in FORTRANFLAGS because the result will be |
+non-portable and the directories will not be searched by the dependency |
+scanner. Note: directory names in FORTRANPATH will be looked-up relative |
+to the SConscript directory when they are used in a command. To force |
+.B scons |
+to look-up a directory relative to the root of the source tree use #: |
+ |
+.ES |
+env = Environment(FORTRANPATH='#/include') |
+.EE |
+.IP |
+The directory look-up can also be forced using the |
+.BR Dir () |
+function: |
+ |
+.ES |
+include = Dir('include') |
+env = Environment(FORTRANPATH=include) |
+.EE |
+.IP |
+The directory list will be added to command lines |
+through the automatically-generated |
+$_FORTRANINCFLAGS |
+construction variable, |
+which is constructed by |
+appending the values of the |
+$INCPREFIX and $INCSUFFIX |
+construction variables |
+to the beginning and end |
+of each directory in $FORTRANPATH. |
+Any command lines you define that need |
+the FORTRANPATH directory list should |
+include $_FORTRANINCFLAGS: |
+ |
+.ES |
+env = Environment(FORTRANCOM="my_compiler $_FORTRANINCFLAGS -c -o $TARGET $SOURCE") |
+.EE |
+ |
+.IP FORTRANPPCOM |
+The command line used to compile a Fortran source file to an object file |
+after first running the file through the C preprocessor. |
+By default, any options specified in the $FORTRANFLAGS, |
+$CPPFLAGS, |
+$_CPPDEFFLAGS, |
+$_FORTRANMODFLAG, and |
+$_FORTRANINCFLAGS |
+construction variables are included on this command line. |
+ |
+.IP FORTRANPPCOMSTR |
+The string displayed when a Fortran source file |
+is compiled to an object file |
+after first running the file through the C preprocessor. |
+If this is not set, then $FORTRANPPCOM |
+(the command line) is displayed. |
+ |
+.IP FORTRANPPFILESUFFIXES |
+The list of file extensions for which the compilation + preprocessor pass for |
+FORTRAN dialect will be used. By default, this is ['.fpp', '.FPP'] |
+ |
+.IP FORTRANSUFFIXES |
+The list of suffixes of files that will be scanned |
+for Fortran implicit dependencies |
+(INCLUDE lines and USE statements). |
+The default list is: |
+ |
+.ES |
+[".f", ".F", ".for", ".FOR", ".ftn", ".FTN", ".fpp", ".FPP", |
+".f77", ".F77", ".f90", ".F90", ".f95", ".F95"] |
+.EE |
+ |
+.IP FRAMEWORKPATH |
+On Mac OS X with gcc, |
+a list containing the paths to search for frameworks. |
+Used by the compiler to find framework-style includes like |
+#include <Fmwk/Header.h>. |
+Used by the linker to find user-specified frameworks when linking (see |
+$FRAMEWORKS). |
+For example: |
+ |
+.ES |
+ env.AppendUnique(FRAMEWORKPATH='#myframeworkdir') |
+.EE |
+.IP |
+will add |
+ |
+.ES |
+ ... -Fmyframeworkdir |
+.EE |
+.IP |
+to the compiler and linker command lines. |
+ |
+.IP _FRAMEWORKPATH |
+On Mac OS X with gcc, an automatically-generated construction variable |
+containing the linker command-line options corresponding to |
+$FRAMEWORKPATH. |
+ |
+.IP FRAMEWORKPATHPREFIX |
+On Mac OS X with gcc, the prefix to be used for the FRAMEWORKPATH entries. |
+(see $FRAMEWORKPATH). |
+The default value is |
+.BR \-F . |
+ |
+.IP FRAMEWORKPREFIX |
+On Mac OS X with gcc, |
+the prefix to be used for linking in frameworks |
+(see $FRAMEWORKS). |
+The default value is |
+.BR \-framework . |
+ |
+.IP _FRAMEWORKS |
+On Mac OS X with gcc, |
+an automatically-generated construction variable |
+containing the linker command-line options |
+for linking with FRAMEWORKS. |
+ |
+.IP FRAMEWORKS |
+On Mac OS X with gcc, a list of the framework names to be linked into a |
+program or shared library or bundle. |
+The default value is the empty list. |
+For example: |
+ |
+.ES |
+ env.AppendUnique(FRAMEWORKS=Split('System Cocoa SystemConfiguration')) |
+.EE |
+.IP |
+ |
+.IP FRAMEWORKSFLAGS |
+On Mac OS X with gcc, |
+general user-supplied frameworks options to be added at |
+the end of a command |
+line building a loadable module. |
+(This has been largely superseded by |
+the $FRAMEWORKPATH, $FRAMEWORKPATHPREFIX, |
+$FRAMEWORKPREFIX and $FRAMEWORKS variables |
+described above.) |
+ |
+.IP GS |
+The Ghostscript program used to convert PostScript to PDF files. |
+ |
+.IP GSCOM |
+The Ghostscript command line used to convert PostScript to PDF files. |
+ |
+.IP GSCOMSTR |
+The string displayed when |
+Ghostscript is used to convert |
+a PostScript file to a PDF file. |
+If this is not set, then $GSCOM (the command line) is displayed. |
+ |
+.IP GSFLAGS |
+General options passed to the Ghostscript program |
+when converting PostScript to PDF files. |
+ |
+.IP HOST_ARCH |
+Sets the host architecture for Visual Studio compiler. If not set, |
+default to the detected host architecture: note that this may depend |
+on the python you are using. |
+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 $TARGET_ARCH. |
+ |
+This is currently only used on Windows, but in the future it will be |
+used on other OSes as well. |
+ |
+.IP HOST_OS |
+ The name of the host operating system used to create the Environment. |
+ If a platform is specified when creating the Environment, then |
+ that Platform's logic will handle setting this value. |
+ This value is immutable, and should not be changed by the user after |
+ the Environment is initialized. |
+ Currently only set for Win32. |
+ |
+.IP IDLSUFFIXES |
+The list of suffixes of files that will be scanned |
+for IDL implicit dependencies |
+(#include or import lines). |
+The default list is: |
+ |
+.ES |
+[".idl", ".IDL"] |
+.EE |
+ |
+.IP IMPLICIT_COMMAND_DEPENDENCIES |
+Controls whether or not SCons will |
+add implicit dependencies for the commands |
+executed to build targets. |
+ |
+By default, SCons will add |
+to each target |
+an implicit dependency on the command |
+represented by the first argument on any |
+command line it executes. |
+The specific file for the dependency is |
+found by searching the |
+.I PATH |
+variable in the |
+.I ENV |
+environment used to execute the command. |
+ |
+If the construction variable |
+$IMPLICIT_COMMAND_DEPENDENCIES |
+is set to a false value |
+.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 $CPPPATH and $FORTRANPATH construction variables |
+when the $_CPPINCFLAGS and $_FORTRANINCFLAGS |
+variables are automatically generated. |
+ |
+.IP INCSUFFIX |
+The suffix used to specify an include directory on the C compiler command |
+line. |
+This will be appended to the end of each directory |
+in the $CPPPATH and $FORTRANPATH construction variables |
+when the $_CPPINCFLAGS and $_FORTRANINCFLAGS |
+variables are automatically generated. |
+ |
+.IP INSTALL |
+A function to be called to install a file into a |
+destination file name. |
+The default function copies the file into the destination |
+(and sets the destination file's mode and permission bits |
+to match the source file's). |
+The function takes the following arguments: |
+ |
+.ES |
+def install(dest, source, env): |
+.EE |
+.IP |
+.I dest |
+is the path name of the destination file. |
+.I source |
+is the path name of the source file. |
+.I env |
+is the construction environment |
+(a dictionary of construction values) |
+in force for this file installation. |
+ |
+.IP INSTALLSTR |
+The string displayed when a file is |
+installed into a destination file name. |
+The default is: |
+.ES |
+Install file: "$SOURCE" as "$TARGET" |
+.EE |
+ |
+.IP INTEL_C_COMPILER_VERSION |
+Set by the "intelc" Tool |
+to the major version number of the Intel C compiler |
+selected for use. |
+ |
+.IP JAR |
+The Java archive tool. |
+ |
+.IP JARCHDIR |
+The directory to which the Java archive tool should change |
+(using the |
+.B \-C |
+option). |
+ |
+.IP JARCOM |
+The command line used to call the Java archive tool. |
+ |
+.IP JARCOMSTR |
+The string displayed when the Java archive tool |
+is called |
+If this is not set, then $JARCOM (the command line) is displayed. |
+ |
+.ES |
+env = Environment(JARCOMSTR = "JARchiving $SOURCES into $TARGET") |
+.EE |
+ |
+.IP JARFLAGS |
+General options passed to the Java archive tool. |
+By default this is set to |
+.B cf |
+to create the necessary |
+.B jar |
+file. |
+ |
+.IP JARSUFFIX |
+The suffix for Java archives: |
+.B .jar |
+by default. |
+ |
+.IP JAVABOOTCLASSPATH |
+Specifies the list of directories that |
+will be added to the |
+&javac; command line |
+via the \fB\-bootclasspath\fP option. |
+The individual directory names will be |
+separated by the operating system's path separate character |
+(\fB:\fP on UNIX/Linux/POSIX, |
+\fB;\fP on Windows). |
+ |
+.IP JAVAC |
+The Java compiler. |
+ |
+.IP JAVACCOM |
+The command line used to compile a directory tree containing |
+Java source files to |
+corresponding Java class files. |
+Any options specified in the $JAVACFLAGS construction variable |
+are included on this command line. |
+ |
+.IP JAVACCOMSTR |
+The string displayed when compiling |
+a directory tree of Java source files to |
+corresponding Java class files. |
+If this is not set, then $JAVACCOM (the command line) is displayed. |
+ |
+.ES |
+env = Environment(JAVACCOMSTR = "Compiling class files $TARGETS from $SOURCES") |
+.EE |
+ |
+.IP JAVACFLAGS |
+General options that are passed to the Java compiler. |
+ |
+.IP JAVACLASSDIR |
+The directory in which Java class files may be found. |
+This is stripped from the beginning of any Java .class |
+file names supplied to the |
+.B JavaH |
+builder. |
+ |
+.IP JAVACLASSPATH |
+Specifies the list of directories that |
+will be searched for Java |
+\fB.class\fP file. |
+The directories in this list will be added to the |
+&javac; and &javah; command lines |
+via the \fB\-classpath\fP option. |
+The individual directory names will be |
+separated by the operating system's path separate character |
+(\fB:\fP on UNIX/Linux/POSIX, |
+\fB;\fP on Windows). |
+ |
+Note that this currently just adds the specified |
+directory via the \fB\-classpath\fP option. |
+&SCons; does not currently search the |
+$JAVACLASSPATH directories for dependency |
+\fB.class\fP files. |
+ |
+.IP JAVACLASSSUFFIX |
+The suffix for Java class files; |
+.B .class |
+by default. |
+ |
+.IP JAVAH |
+The Java generator for C header and stub files. |
+ |
+.IP JAVAHCOM |
+The command line used to generate C header and stub files |
+from Java classes. |
+Any options specified in the $JAVAHFLAGS construction variable |
+are included on this command line. |
+ |
+.IP JAVAHCOMSTR |
+The string displayed when C header and stub files |
+are generated from Java classes. |
+If this is not set, then $JAVAHCOM (the command line) is displayed. |
+ |
+.ES |
+env = Environment(JAVAHCOMSTR = "Generating header/stub file(s) $TARGETS from $SOURCES") |
+.EE |
+ |
+.IP JAVAHFLAGS |
+General options passed to the C header and stub file generator |
+for Java classes. |
+ |
+.IP JAVASOURCEPATH |
+Specifies the list of directories that |
+will be searched for input |
+\fB.java\fP file. |
+The directories in this list will be added to the |
+&javac; command line |
+via the \fB\-sourcepath\fP option. |
+The individual directory names will be |
+separated by the operating system's path separate character |
+(\fB:\fP on UNIX/Linux/POSIX, |
+\fB;\fP on Windows). |
+ |
+Note that this currently just adds the specified |
+directory via the \fB\-sourcepath\fP option. |
+&SCons; does not currently search the |
+$JAVASOURCEPATH directories for dependency |
+\fB.java\fP files. |
+ |
+.IP JAVASUFFIX |
+The suffix for Java files; |
+.B .java |
+by default. |
+ |
+.IP JAVAVERSION |
+Specifies the Java version being used by the \fBJava\fP() builder. |
+This is \fInot\fP currently used to select one |
+version of the Java compiler vs. another. |
+Instead, you should set this to specify the version of Java |
+supported by your &javac; compiler. |
+The default is \fB1.4\fP. |
+ |
+This is sometimes necessary because |
+Java 1.5 changed the file names that are created |
+for nested anonymous inner classes, |
+which can cause a mismatch with the files |
+that &SCons; expects will be generated by the &javac; compiler. |
+Setting $JAVAVERSION to \fB1.5\fP |
+(or \fB1.6\fP, as appropriate) |
+can make &SCons; realize that a Java 1.5 or 1.6 |
+build is actually up to date. |
+ |
+.IP LATEX |
+The LaTeX structured formatter and typesetter. |
+ |
+.IP LATEXCOM |
+The command line used to call the LaTeX structured formatter and typesetter. |
+ |
+.IP LATEXCOMSTR |
+The string displayed when calling |
+the LaTeX structured formatter and typesetter. |
+If this is not set, then $LATEXCOM (the command line) is displayed. |
+ |
+.ES |
+env = Environment(LATEXCOMSTR = "Building $TARGET from LaTeX input $SOURCES") |
+.EE |
+ |
+.IP LATEXFLAGS |
+General options passed to the LaTeX structured formatter and typesetter. |
+ |
+.IP LATEXRETRIES |
+The maximum number of times that LaTeX |
+will be re-run if the |
+.B .log |
+generated by the $LATEXCOM command |
+indicates that there are undefined references. |
+The default is to try to resolve undefined references |
+by re-running LaTeX up to three times. |
+ |
+.IP LATEXSUFFIXES |
+The list of suffixes of files that will be scanned |
+for LaTeX implicit dependencies |
+(\fB\\include\fP or \fB\\import\fP files). |
+The default list is: |
+ |
+.ES |
+[".tex", ".ltx", ".latex"] |
+.EE |
+ |
+.IP LDMODULE |
+The linker for building loadable modules. |
+By default, this is the same as $SHLINK. |
+ |
+.IP LDMODULECOM |
+The command line for building loadable modules. |
+On Mac OS X, this uses the $LDMODULE, |
+$LDMODULEFLAGS and |
+$FRAMEWORKSFLAGS variables. |
+On other systems, this is the same as $SHLINK. |
+ |
+.IP LDMODULECOMSTR |
+The string displayed when building loadable modules. |
+If this is not set, then $LDMODULECOM (the command line) is displayed. |
+ |
+.IP LDMODULEFLAGS |
+General user options passed to the linker for building loadable modules. |
+ |
+.IP LDMODULEPREFIX |
+The prefix used for loadable module file names. |
+On Mac OS X, this is null; |
+on other systems, this is |
+the same as $SHLIBPREFIX. |
+ |
+.IP LDMODULESUFFIX |
+The suffix used for loadable module file names. |
+On Mac OS X, this is null; |
+on other systems, this is |
+the same as $SHLIBSUFFIX. |
+ |
+.IP LEX |
+The lexical analyzer generator. |
+ |
+.IP LEXCOM |
+The command line used to call the lexical analyzer generator |
+to generate a source file. |
+ |
+.IP LEXCOMSTR |
+The string displayed when generating a source file |
+using the lexical analyzer generator. |
+If this is not set, then $LEXCOM (the command line) is displayed. |
+ |
+.ES |
+env = Environment(LEXCOMSTR = "Lex'ing $TARGET from $SOURCES") |
+.EE |
+ |
+.IP LEXFLAGS |
+General options passed to the lexical analyzer generator. |
+ |
+.IP _LIBDIRFLAGS |
+An automatically-generated construction variable |
+containing the linker command-line options |
+for specifying directories to be searched for library. |
+The value of $_LIBDIRFLAGS is created |
+by appending $LIBDIRPREFIX and $LIBDIRSUFFIX |
+to the beginning and end |
+of each directory in $LIBPATH. |
+ |
+.IP LIBDIRPREFIX |
+The prefix used to specify a library directory on the linker command line. |
+This will be appended to the beginning of each directory |
+in the $LIBPATH construction variable |
+when the $_LIBDIRFLAGS variable is automatically generated. |
+ |
+.IP LIBDIRSUFFIX |
+The suffix used to specify a library directory on the linker command line. |
+This will be appended to the end of each directory |
+in the $LIBPATH construction variable |
+when the $_LIBDIRFLAGS variable is automatically generated. |
+ |
+.IP _LIBFLAGS |
+An automatically-generated construction variable |
+containing the linker command-line options |
+for specifying libraries to be linked with the resulting target. |
+The value of $_LIBFLAGS is created |
+by appending $LIBLINKPREFIX and $LIBLINKSUFFIX |
+to the beginning and end |
+of each filename in $LIBS. |
+ |
+.IP LIBLINKPREFIX |
+The prefix used to specify a library to link on the linker command line. |
+This will be appended to the beginning of each library |
+in the $LIBS construction variable |
+when the $_LIBFLAGS variable is automatically generated. |
+ |
+.IP LIBLINKSUFFIX |
+The suffix used to specify a library to link on the linker command line. |
+This will be appended to the end of each library |
+in the $LIBS construction variable |
+when the $_LIBFLAGS variable is automatically generated. |
+ |
+.IP LIBPATH |
+The list of directories that will be searched for libraries. |
+The implicit dependency scanner will search these |
+directories for include files. Don't explicitly put include directory |
+arguments in $LINKFLAGS or $SHLINKFLAGS |
+because the result will be non-portable |
+and the directories will not be searched by the dependency scanner. Note: |
+directory names in LIBPATH will be looked-up relative to the SConscript |
+directory when they are used in a command. To force |
+.B scons |
+to look-up a directory relative to the root of the source tree use #: |
+ |
+.ES |
+env = Environment(LIBPATH='#/libs') |
+.EE |
+.IP |
+The directory look-up can also be forced using the |
+.BR Dir () |
+function: |
+ |
+.ES |
+libs = Dir('libs') |
+env = Environment(LIBPATH=libs) |
+.EE |
+.IP |
+The directory list will be added to command lines |
+through the automatically-generated |
+$_LIBDIRFLAGS |
+construction variable, |
+which is constructed by |
+appending the values of the |
+$LIBDIRPREFIX and $LIBDIRSUFFIX |
+construction variables |
+to the beginning and end |
+of each directory in $LIBPATH. |
+Any command lines you define that need |
+the LIBPATH directory list should |
+include $_LIBDIRFLAGS: |
+ |
+.ES |
+env = Environment(LINKCOM="my_linker $_LIBDIRFLAGS $_LIBFLAGS -o $TARGET $SOURCE") |
+.EE |
+ |
+.IP LIBPREFIX |
+The prefix used for (static) library file names. |
+A default value is set for each platform |
+(posix, win32, os2, etc.), |
+but the value is overridden by individual tools |
+(ar, mslib, sgiar, sunar, tlib, etc.) |
+to reflect the names of the libraries they create. |
+ |
+.IP LIBPREFIXES |
+A list of all legal prefixes for library file names. |
+When searching for library dependencies, |
+SCons will look for files with these prefixes, |
+the base library name, |
+and suffixes in the $LIBSUFFIXES list. |
+ |
+.IP LIBS |
+A list of one or more libraries |
+that will be linked with |
+any executable programs |
+created by this environment. |
+ |
+The library list will be added to command lines |
+through the automatically-generated |
+$_LIBFLAGS |
+construction variable, |
+which is constructed by |
+appending the values of the |
+$LIBLINKPREFIX and $LIBLINKSUFFIX |
+construction variables |
+to the beginning and end |
+of each filename in $LIBS. |
+Any command lines you define that need |
+the LIBS library list should |
+include $_LIBFLAGS: |
+ |
+.ES |
+env = Environment(LINKCOM="my_linker $_LIBDIRFLAGS $_LIBFLAGS -o $TARGET $SOURCE") |
+.EE |
+.IP |
+If you add a |
+File |
+object to the |
+$LIBS |
+list, the name of that file will be added to |
+$_LIBFLAGS, |
+and thus the link line, as is, without |
+$LIBLINKPREFIX |
+or |
+$LIBLINKSUFFIX. |
+For example: |
+ |
+.ES |
+env.Append(LIBS=File('/tmp/mylib.so')) |
+.EE |
+.IP |
+In all cases, scons will add dependencies from the executable program to |
+all the libraries in this list. |
+ |
+.IP LIBSUFFIX |
+The suffix used for (static) library file names. |
+A default value is set for each platform |
+(posix, win32, os2, etc.), |
+but the value is overridden by individual tools |
+(ar, mslib, sgiar, sunar, tlib, etc.) |
+to reflect the names of the libraries they create. |
+ |
+.IP LIBSUFFIXES |
+A list of all legal suffixes for library file names. |
+When searching for library dependencies, |
+SCons will look for files with prefixes, in the $LIBPREFIXES list, |
+the base library name, |
+and these suffixes. |
+ |
+.IP LICENSE |
+The abbreviated name of the license under which |
+this project is released (gpl, lpgl, bsd etc.). |
+See http://www.opensource.org/licenses/alphabetical |
+for a list of license names. |
+ |
+.IP LINESEPARATOR |
+The separator used by the \fBSubstfile\fP() and \fBTextfile\fP() builders. |
+This value is used between sources when constructing the target. |
+It defaults to the current system line separator. |
+ |
+.IP LINK |
+The linker. |
+ |
+.IP LINKCOM |
+The command line used to link object files into an executable. |
+ |
+.IP LINKCOMSTR |
+The string displayed when object files |
+are linked into an executable. |
+If this is not set, then $LINKCOM (the command line) is displayed. |
+ |
+.ES |
+env = Environment(LINKCOMSTR = "Linking $TARGET") |
+.EE |
+ |
+.IP LINKFLAGS |
+General user options passed to the linker. |
+Note that this variable should |
+.I not |
+contain |
+.B \-l |
+(or similar) options for linking with the libraries listed in $LIBS, |
+nor |
+.B \-L |
+(or similar) library search path options |
+that scons generates automatically from $LIBPATH. |
+See |
+$_LIBFLAGS |
+above, |
+for the variable that expands to library-link options, |
+and |
+$_LIBDIRFLAGS |
+above, |
+for the variable that expands to library search path options. |
+ |
+.IP M4 |
+The M4 macro preprocessor. |
+ |
+.IP M4COM |
+The command line used to pass files through the M4 macro preprocessor. |
+ |
+.IP M4COMSTR |
+The string displayed when |
+a file is passed through the M4 macro preprocessor. |
+If this is not set, then $M4COM (the command line) is displayed. |
+ |
+.IP M4FLAGS |
+General options passed to the M4 macro preprocessor. |
+ |
+.IP MAKEINDEX |
+The makeindex generator for the TeX formatter and typesetter and the |
+LaTeX structured formatter and typesetter. |
+ |
+.IP MAKEINDEXCOM |
+The command line used to call the makeindex generator for the |
+TeX formatter and typesetter and the LaTeX structured formatter and |
+typesetter. |
+ |
+.IP MAKEINDEXCOMSTR |
+The string displayed when calling the makeindex generator for the |
+TeX formatter and typesetter |
+and the LaTeX structured formatter and typesetter. |
+If this is not set, then $MAKEINDEXCOM (the command line) is displayed. |
+ |
+.IP MAKEINDEXFLAGS |
+General options passed to the makeindex generator for the TeX formatter |
+and typesetter and the LaTeX structured formatter and typesetter. |
+ |
+.IP MAXLINELENGTH |
+The maximum number of characters allowed on an external command line. |
+On Win32 systems, |
+link lines longer than this many characters |
+are linked via a temporary file name. |
+ |
+.IP MIDL |
+The Microsoft IDL compiler. |
+ |
+.IP MIDLCOM |
+The command line used to pass files to the Microsoft IDL compiler. |
+ |
+.IP MIDLCOMSTR |
+The string displayed when |
+the Microsoft IDL copmiler is called. |
+If this is not set, then $MIDLCOM (the command line) is displayed. |
+ |
+.IP MIDLFLAGS |
+General options passed to the Microsoft IDL compiler. |
+ |
+.IP MSSDK_DIR |
+The directory containing the Microsoft SDK |
+(either Platform SDK or Windows SDK) |
+to be used for compilation. |
+ |
+.IP MSSDK_VERSION |
+The version string of the Microsoft SDK |
+(either Platform SDK or Windows SDK) |
+to be used for compilation. |
+Supported versions include |
+.BR 6.1 , |
+.BR 6.0A , |
+.BR 6.0 , |
+.B 2003R2 |
+and |
+.BR 2003R1 . |
+ |
+.IP MSVC_BATCH |
+When set to any true value, |
+specifies that SCons should batch |
+compilation of object files |
+when calling the Microsoft Visual C/C++ compiler. |
+All compilations of source files from the same source directory |
+that generate target files in a same output directory |
+and were configured in SCons using the same construction environment |
+will be built in a single call to the compiler. |
+Only source files that have changed since their |
+object files were built will be passed to each compiler invocation |
+(via the $CHANGED_SOURCES construction variable). |
+Any compilations where the object (target) file base name |
+(minus the \fB.obj\fP) |
+does not match the source file base name |
+will be compiled separately. |
+ |
+.IP MSVC_USE_SCRIPT |
+Use a batch script to set up Microsoft Visual Studio compiler |
+ |
+$MSVC_USE_SCRIPT overrides $MSVC_VERSION and $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 $MSVC_VERSION is not set, SCons will (by default) select the |
+latest version of Visual C/C++ installed on your system. If the |
+specified version isn't installed, tool initialization will fail. |
+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 |
+$MSVS_VERSION) |
+ |
+.BR VERSIONS : |
+the available versions of MSVS installed |
+ |
+.BR VCINSTALLDIR : |
+installed directory of Visual C++ |
+ |
+.BR VSINSTALLDIR : |
+installed directory of Visual Studio |
+ |
+.BR FRAMEWORKDIR : |
+installed directory of the .NET framework |
+ |
+.BR FRAMEWORKVERSIONS : |
+list of installed versions of the .NET framework, sorted latest to oldest. |
+ |
+.BR FRAMEWORKVERSION : |
+latest installed version of the .NET framework |
+ |
+.BR FRAMEWORKSDKDIR : |
+installed location of the .NET SDK. |
+ |
+.BR PLATFORMSDKDIR : |
+installed location of the Platform SDK. |
+ |
+.BR PLATFORMSDK_MODULES : |
+dictionary of installed Platform SDK modules, |
+where the dictionary keys are keywords for the various modules, and |
+the values are 2-tuples where the first is the release date, and the |
+second is the version number. |
+ |
+If a value isn't set, it wasn't available in the registry. |
+ |
+.IP MSVS_ARCH |
+Sets the architecture for which the generated project(s) should build. |
+ |
+The default value is \fBx86\fP. |
+\fBamd64\fP is also supported |
+by &SCons; for some Visual Studio versions. |
+Trying to set $MSVS_ARCH to an architecture that's not |
+supported for a given Visual Studio version |
+will generate an error. |
+ |
+.IP MSVS_PROJECT_BASE_PATH |
+The string |
+placed in a generated Microsoft Visual Studio solution file |
+as the value of the |
+.B SccProjectFilePathRelativizedFromConnection0 |
+and |
+.B SccProjectFilePathRelativizedFromConnection1 |
+attributes of the |
+.B GlobalSection(SourceCodeControl) |
+section. |
+There is no default value. |
+ |
+.IP MSVS_PROJECT_GUID |
+The string |
+placed in a generated Microsoft Visual Studio project file |
+as the value of the |
+.B ProjectGUID |
+attribute. |
+The string is also placed in the |
+.B SolutionUniqueID |
+attribute of the |
+.B GlobalSection(SourceCodeControl) |
+section of the Microsoft Visual Studio solution file. |
+There is no default value. |
+ |
+.IP MSVS_SCC_AUX_PATH |
+The path name |
+placed in a generated Microsoft Visual Studio project file |
+as the value of the |
+.B SccAuxPath |
+attribute |
+if the |
+.B MSVS_SCC_PROVIDER |
+construction variable is also set. |
+There is no default value. |
+ |
+.IP MSVS_SCC_LOCAL_PATH |
+The path name |
+placed in a generated Microsoft Visual Studio project file |
+as the value of the |
+.B SccLocalPath |
+attribute |
+if the |
+.B MSVS_SCC_PROVIDER |
+construction variable is also set. |
+The path name is also placed in the |
+.B SccLocalPath0 |
+and |
+.B SccLocalPath1 |
+attributes of the |
+.B GlobalSection(SourceCodeControl) |
+section of the Microsoft Visual Studio solution file. |
+There is no default value. |
+ |
+.IP MSVS_SCC_PROJECT_NAME |
+The project name |
+placed in a generated Microsoft Visual Studio project file |
+as the value of the |
+.B SccProjectName |
+attribute. |
+There is no default value. |
+ |
+.IP MSVS_SCC_PROVIDER |
+The string |
+placed in a generated Microsoft Visual Studio project file |
+as the value of the |
+.B SccProvider |
+attribute. |
+The string is also placed in the |
+.B SccProvider1 |
+attribute of the |
+.B GlobalSection(SourceCodeControl) |
+section of the Microsoft Visual Studio solution file. |
+There is no default value. |
+ |
+.IP MSVS_VERSION |
+Sets the preferred version of Microsoft Visual Studio to use. |
+ |
+If $MSVS_VERSION is not set, |
+&SCons; will (by default) select the latest version |
+of Visual Studio installed on your system. |
+So, if you have version 6 and version 7 (MSVS .NET) installed, |
+it will prefer version 7. |
+You can override this by |
+specifying the |
+.B MSVS_VERSION |
+variable in the Environment initialization, setting it to the |
+appropriate version ('6.0' or '7.0', for example). |
+If the specified version isn't installed, |
+tool initialization will fail. |
+ |
+This is obsolete: use $MSVC_VERSION instead. If $MSVS_VERSION is set and |
+$MSVC_VERSION is not, $MSVC_VERSION will be set automatically to $MSVS_VERSION. |
+If both are set to different values, scons will raise an error. |
+ |
+.IP MSVSBUILDCOM |
+The build command line placed in |
+a generated Microsoft Visual Studio project file. |
+The default is to have Visual Studio invoke SCons with any specified |
+build targets. |
+ |
+.IP MSVSCLEANCOM |
+The clean command line placed in |
+a generated Microsoft Visual Studio project file. |
+The default is to have Visual Studio invoke SCons with the -c option |
+to remove any specified targets. |
+ |
+.IP MSVSENCODING |
+The encoding string placed in |
+a generated Microsoft Visual Studio project file. |
+The default is encoding |
+.BR Windows-1252 . |
+ |
+.IP MSVSPROJECTCOM |
+The action used to generate Microsoft Visual Studio project files. |
+ |
+.IP MSVSPROJECTSUFFIX |
+The suffix used for Microsoft Visual Studio project (DSP) files. |
+The default value is |
+.B .vcproj |
+when using Visual Studio version 7.x (.NET) |
+or later version, |
+and |
+.B .dsp |
+when using earlier versions of Visual Studio. |
+ |
+.IP MSVSREBUILDCOM |
+The rebuild command line placed in |
+a generated Microsoft Visual Studio project file. |
+The default is to have Visual Studio invoke SCons with any specified |
+rebuild targets. |
+ |
+.IP MSVSSCONS |
+The SCons used in generated Microsoft Visual Studio project files. |
+The default is the version of SCons being |
+used to generate the project file. |
+ |
+.IP MSVSSCONSCOM |
+The default SCons command used in generated Microsoft Visual Studio |
+project files. |
+ |
+.IP MSVSSCONSCRIPT |
+The sconscript file |
+(that is, |
+.B SConstruct |
+or |
+.B SConscript |
+file) |
+that will be invoked by Visual Studio |
+project files |
+(through the |
+$MSVSSCONSCOM |
+variable). |
+The default is the same sconscript file |
+that contains the call to |
+.BR MSVSProject () |
+to build the project file. |
+ |
+.IP MSVSSCONSFLAGS |
+The SCons flags used in generated Microsoft Visual Studio |
+project files. |
+ |
+.IP MSVSSOLUTIONCOM |
+The action used to generate Microsoft Visual Studio solution files. |
+ |
+.IP MSVSSOLUTIONSUFFIX |
+The suffix used for Microsoft Visual Studio solution (DSW) files. |
+The default value is |
+.B .sln |
+when using Visual Studio version 7.x (.NET), |
+and |
+.B .dsw |
+when using earlier versions of Visual Studio. |
+ |
+.IP MWCW_VERSION |
+The version number of the MetroWerks CodeWarrior C compiler |
+to be used. |
+ |
+.IP MWCW_VERSIONS |
+A list of installed versions of the MetroWerks CodeWarrior C compiler |
+on this system. |
+ |
+.IP NAME |
+Specfies the name of the project to package. |
+ |
+.IP no_import_lib |
+When set to non-zero, |
+suppresses creation of a corresponding Windows static import lib by the |
+.B SharedLibrary |
+builder when used with |
+MinGW, Microsoft Visual Studio or Metrowerks. |
+This also suppresses creation |
+of an export (.exp) file |
+when using Microsoft Visual Studio. |
+ |
+.IP OBJPREFIX |
+The prefix used for (static) object file names. |
+ |
+.IP OBJSUFFIX |
+The suffix used for (static) object file names. |
+ |
+.IP P4 |
+The Perforce executable. |
+ |
+.IP P4COM |
+The command line used to |
+fetch source files from Perforce. |
+ |
+.IP P4COMSTR |
+The string displayed when |
+fetching a source file from Perforce. |
+If this is not set, then $P4COM (the command line) is displayed. |
+ |
+.IP P4FLAGS |
+General options that are passed to Perforce. |
+ |
+.IP PACKAGEROOT |
+Specifies the directory where all files in resulting archive will be |
+placed if applicable. The default value is "$NAME-$VERSION". |
+ |
+.IP PACKAGETYPE |
+Selects the package type to build. Currently these are available: |
+ |
+ * msi - Microsoft Installer |
+ * rpm - Redhat Package Manger |
+ * ipkg - Itsy Package Management System |
+ * tarbz2 - compressed tar |
+ * targz - compressed tar |
+ * zip - zip file |
+ * src_tarbz2 - compressed tar source |
+ * src_targz - compressed tar source |
+ * src_zip - zip file source |
+ |
+This may be overridden with the "package_type" command line option. |
+ |
+.IP PACKAGEVERSION |
+The version of the package (not the underlying project). |
+This is currently only used by the rpm packager |
+and should reflect changes in the packaging, |
+not the underlying project code itself. |
+ |
+.IP PCH |
+The Microsoft Visual C++ precompiled header that will be used when compiling |
+object files. This variable is ignored by tools other than Microsoft Visual C++. |
+When this variable is |
+defined SCons will add options to the compiler command line to |
+cause it to use the precompiled header, and will also set up the |
+dependencies for the PCH file. |
+Example: |
+ |
+.ES |
+env['PCH'] = 'StdAfx.pch' |
+.EE |
+ |
+.IP PCHCOM |
+The command line used by the |
+.BR PCH () |
+builder to generated a precompiled header. |
+ |
+.IP PCHCOMSTR |
+The string displayed when generating a precompiled header. |
+If this is not set, then $PCHCOM (the command line) is displayed. |
+ |
+.IP PCHPDBFLAGS |
+A construction variable that, when expanded, |
+adds the \fB/yD\fP flag to the command line |
+only if the $PDB construction variable is set. |
+ |
+.IP PCHSTOP |
+This variable specifies how much of a source file is precompiled. This |
+variable is ignored by tools other than Microsoft Visual C++, or when |
+the PCH variable is not being used. When this variable is define it |
+must be a string that is the name of the header that |
+is included at the end of the precompiled portion of the source files, or |
+the empty string if the "#pragma hrdstop" construct is being used: |
+ |
+.ES |
+env['PCHSTOP'] = 'StdAfx.h' |
+.EE |
+ |
+.IP PDB |
+The Microsoft Visual C++ PDB file that will store debugging information for |
+object files, shared libraries, and programs. This variable is ignored by |
+tools other than Microsoft Visual C++. |
+When this variable is |
+defined SCons will add options to the compiler and linker command line to |
+cause them to generate external debugging information, and will also set up the |
+dependencies for the PDB file. |
+Example: |
+ |
+.ES |
+env['PDB'] = 'hello.pdb' |
+.EE |
+.IP |
+The Visual C++ compiler switch that SCons uses by default |
+to generate PDB information is \fB/Z7\fP. |
+This works correctly with parallel (\fB\-j\fP) builds |
+because it embeds the debug information in the intermediate object files, |
+as opposed to sharing a single PDB file between multiple object files. |
+This is also the only way to get debug information |
+embedded into a static library. |
+Using the \fB/Zi\fP instead may yield improved |
+link-time performance, |
+although parallel builds will no longer work. |
+You can generate PDB files with the \fB/Zi\fP |
+switch by overriding the default $CCPDBFLAGS variable; |
+see the entry for that variable for specific examples. |
+ |
+.IP PDFCOM |
+A deprecated synonym for $DVIPDFCOM. |
+ |
+.IP PDFLATEX |
+The &pdflatex; utility. |
+ |
+.IP PDFLATEXCOM |
+The command line used to call the &pdflatex; utility. |
+ |
+.IP PDFLATEXCOMSTR |
+The string displayed when calling the &pdflatex; utility. |
+If this is not set, then $PDFLATEXCOM (the command line) is displayed. |
+ |
+.ES |
+env = Environment(PDFLATEX;COMSTR = "Building $TARGET from LaTeX input $SOURCES") |
+.EE |
+ |
+.IP PDFLATEXFLAGS |
+General options passed to the &pdflatex; utility. |
+ |
+.IP PDFPREFIX |
+The prefix used for PDF file names. |
+ |
+.IP PDFSUFFIX |
+The suffix used for PDF file names. |
+ |
+.IP PDFTEX |
+The &pdftex; utility. |
+ |
+.IP PDFTEXCOM |
+The command line used to call the &pdftex; utility. |
+ |
+.IP PDFTEXCOMSTR |
+The string displayed when calling the &pdftex; utility. |
+If this is not set, then $PDFTEXCOM (the command line) is displayed. |
+ |
+.ES |
+env = Environment(PDFTEXCOMSTR = "Building $TARGET from TeX input $SOURCES") |
+.EE |
+ |
+.IP PDFTEXFLAGS |
+General options passed to the &pdftex; utility. |
+ |
+.IP PKGCHK |
+On Solaris systems, |
+the package-checking program that will |
+be used (along with $PKGINFO) |
+to look for installed versions of |
+the Sun PRO C++ compiler. |
+The default is |
+.BR /usr/sbin/pgkchk . |
+ |
+.IP PKGINFO |
+On Solaris systems, |
+the package information program that will |
+be used (along with $PKGCHK) |
+to look for installed versions of |
+the Sun PRO C++ compiler. |
+The default is |
+.BR pkginfo . |
+ |
+.IP PLATFORM |
+The name of the platform used to create the Environment. If no platform is |
+specified when the Environment is created, |
+.B scons |
+autodetects the platform. |
+ |
+.ES |
+env = Environment(tools = []) |
+if env['PLATFORM'] == 'cygwin': |
+ Tool('mingw')(env) |
+else: |
+ Tool('msvc')(env) |
+.EE |
+ |
+.IP PRINT_CMD_LINE_FUNC |
+A Python function used to print the command lines as they are executed |
+(assuming command printing is not disabled by the |
+.B \-q |
+or |
+.B \-s |
+options or their equivalents). |
+The function should take four arguments: |
+.IR s , |
+the command being executed (a string), |
+.IR target , |
+the target being built (file node, list, or string name(s)), |
+.IR source , |
+the source(s) used (file node, list, or string name(s)), and |
+.IR env , |
+the environment being used. |
+ |
+The function must do the printing itself. The default implementation, |
+used if this variable is not set or is None, is: |
+.ES |
+def print_cmd_line(s, target, source, env): |
+ sys.stdout.write(s + "\\n") |
+.EE |
+.IP |
+Here's an example of a more interesting function: |
+ |
+.ES |
+def print_cmd_line(s, target, source, env): |
+ sys.stdout.write("Building %s -> %s...\\n" % |
+ (' and '.join([str(x) for x in source]), |
+ ' and '.join([str(x) for x in target]))) |
+env=Environment(PRINT_CMD_LINE_FUNC=print_cmd_line) |
+env.Program('foo', 'foo.c') |
+.EE |
+.IP |
+This just prints "Building \fItargetname\fP from \fIsourcename\fP..." instead |
+of the actual commands. |
+Such a function could also log the actual commands to a log file, |
+for example. |
+ |
+.IP PROGPREFIX |
+The prefix used for executable file names. |
+ |
+.IP PROGSUFFIX |
+The suffix used for executable file names. |
+ |
+.IP PSCOM |
+The command line used to convert TeX DVI files into a PostScript file. |
+ |
+.IP PSCOMSTR |
+The string displayed when a TeX DVI file |
+is converted into a PostScript file. |
+If this is not set, then $PSCOM (the command line) is displayed. |
+ |
+.IP PSPREFIX |
+The prefix used for PostScript file names. |
+ |
+.IP PSSUFFIX |
+The prefix used for PostScript file names. |
+ |
+.IP QT_AUTOSCAN |
+Turn off scanning for mocable files. Use the Moc Builder to explicitly |
+specify files to run moc on. |
+ |
+.IP QT_BINPATH |
+The path where the qt binaries are installed. |
+The default value is '$QTDIR/bin'. |
+ |
+.IP QT_CPPPATH |
+The path where the qt header files are installed. |
+The default value is '$QTDIR/include'. |
+Note: If you set this variable to None, |
+the tool won't change the $CPPPATH |
+construction variable. |
+ |
+.IP QT_DEBUG |
+Prints lots of debugging information while scanning for moc files. |
+ |
+.IP QT_LIB |
+Default value is 'qt'. You may want to set this to 'qt-mt'. Note: If you set |
+this variable to None, the tool won't change the $LIBS variable. |
+ |
+.IP QT_LIBPATH |
+The path where the qt libraries are installed. |
+The default value is '$QTDIR/lib'. |
+Note: If you set this variable to None, |
+the tool won't change the $LIBPATH |
+construction variable. |
+ |
+.IP QT_MOC |
+Default value is '$QT_BINPATH/moc'. |
+ |
+.IP QT_MOCCXXPREFIX |
+Default value is ''. Prefix for moc output files, when source is a cxx file. |
+ |
+.IP QT_MOCCXXSUFFIX |
+Default value is '.moc'. Suffix for moc output files, when source is a cxx |
+file. |
+ |
+.IP QT_MOCFROMCXXCOM |
+Command to generate a moc file from a cpp file. |
+ |
+.IP QT_MOCFROMCXXCOMSTR |
+The string displayed when generating a moc file from a cpp file. |
+If this is not set, then $QT_MOCFROMCXXCOM (the command line) is displayed. |
+ |
+.IP QT_MOCFROMCXXFLAGS |
+Default value is '-i'. These flags are passed to moc, when moccing a |
+C++ file. |
+ |
+.IP QT_MOCFROMHCOM |
+Command to generate a moc file from a header. |
+ |
+.IP QT_MOCFROMHCOMSTR |
+The string displayed when generating a moc file from a cpp file. |
+If this is not set, then $QT_MOCFROMHCOM (the command line) is displayed. |
+ |
+.IP QT_MOCFROMHFLAGS |
+Default value is ''. These flags are passed to moc, when moccing a header |
+file. |
+ |
+.IP QT_MOCHPREFIX |
+Default value is 'moc_'. Prefix for moc output files, when source is a header. |
+ |
+.IP QT_MOCHSUFFIX |
+Default value is '$CXXFILESUFFIX'. Suffix for moc output files, when source is |
+a header. |
+ |
+.IP QT_UIC |
+Default value is '$QT_BINPATH/uic'. |
+ |
+.IP QT_UICCOM |
+Command to generate header files from .ui files. |
+ |
+.IP QT_UICCOMSTR |
+The string displayed when generating header files from .ui files. |
+If this is not set, then $QT_UICCOM (the command line) is displayed. |
+ |
+.IP QT_UICDECLFLAGS |
+Default value is ''. These flags are passed to uic, when creating a a h |
+file from a .ui file. |
+ |
+.IP QT_UICDECLPREFIX |
+Default value is ''. Prefix for uic generated header files. |
+ |
+.IP QT_UICDECLSUFFIX |
+Default value is '.h'. Suffix for uic generated header files. |
+ |
+.IP QT_UICIMPLFLAGS |
+Default value is ''. These flags are passed to uic, when creating a cxx |
+file from a .ui file. |
+ |
+.IP QT_UICIMPLPREFIX |
+Default value is 'uic_'. Prefix for uic generated implementation files. |
+ |
+.IP QT_UICIMPLSUFFIX |
+Default value is '$CXXFILESUFFIX'. Suffix for uic generated implementation |
+files. |
+ |
+.IP QT_UISUFFIX |
+Default value is '.ui'. Suffix of designer input files. |
+ |
+.IP QTDIR |
+The qt tool tries to take this from os.environ. |
+It also initializes all QT_* |
+construction variables listed below. |
+(Note that all paths are constructed |
+with python's os.path.join() method, |
+but are listed here with the '/' separator |
+for easier reading.) |
+In addition, the construction environment |
+variables $CPPPATH, |
+$LIBPATH and |
+$LIBS may be modified |
+and the variables |
+PROGEMITTER, SHLIBEMITTER and LIBEMITTER |
+are modified. Because the build-performance is affected when using this tool, |
+you have to explicitly specify it at Environment creation: |
+ |
+.ES |
+Environment(tools=['default','qt']) |
+.EE |
+.IP |
+The qt tool supports the following operations: |
+ |
+.I "Automatic moc file generation from header files." |
+You do not have to specify moc files explicitly, the tool does it for you. |
+However, there are a few preconditions to do so: Your header file must have |
+the same filebase as your implementation file and must stay in the same |
+directory. It must have one of the suffixes .h, .hpp, .H, .hxx, .hh. You |
+can turn off automatic moc file generation by setting QT_AUTOSCAN to 0. |
+See also the corresponding builder method |
+.B Moc() |
+ |
+.I "Automatic moc file generation from cxx files." |
+As stated in the qt documentation, include the moc file at the end of |
+the cxx file. Note that you have to include the file, which is generated |
+by the transformation ${QT_MOCCXXPREFIX}<basename>${QT_MOCCXXSUFFIX}, by default |
+<basename>.moc. A warning is generated after building the moc file, if you |
+do not include the correct file. If you are using VariantDir, you may |
+need to specify duplicate=1. You can turn off automatic moc file generation |
+by setting QT_AUTOSCAN to 0. See also the corresponding |
+.BR Moc () |
+builder method. |
+ |
+.I "Automatic handling of .ui files." |
+The implementation files generated from .ui files are handled much the same |
+as yacc or lex files. Each .ui file given as a source of Program, Library or |
+SharedLibrary will generate three files, the declaration file, the |
+implementation file and a moc file. Because there are also generated headers, |
+you may need to specify duplicate=1 in calls to VariantDir. |
+See also the corresponding |
+.BR Uic () |
+builder method. |
+ |
+.IP RANLIB |
+The archive indexer. |
+ |
+.IP RANLIBCOM |
+The command line used to index a static library archive. |
+ |
+.IP RANLIBCOMSTR |
+The string displayed when a static library archive is indexed. |
+If this is not set, then $RANLIBCOM (the command line) is displayed. |
+ |
+.ES |
+env = Environment(RANLIBCOMSTR = "Indexing $TARGET") |
+.EE |
+ |
+.IP RANLIBFLAGS |
+General options passed to the archive indexer. |
+ |
+.IP RC |
+The resource compiler used to build |
+a Microsoft Visual C++ resource file. |
+ |
+.IP RCCOM |
+The command line used to build |
+a Microsoft Visual C++ resource file. |
+ |
+.IP RCCOMSTR |
+The string displayed when invoking the resource compiler |
+to build a Microsoft Visual C++ resource file. |
+If this is not set, then $RCCOM (the command line) is displayed. |
+ |
+.IP RCFLAGS |
+The flags passed to the resource compiler by the RES builder. |
+ |
+.IP RCINCFLAGS |
+An automatically-generated construction variable |
+containing the command-line options |
+for specifying directories to be searched |
+by the resource compiler. |
+The value of $RCINCFLAGS is created |
+by appending $RCINCPREFIX and $RCINCSUFFIX |
+to the beginning and end |
+of each directory in $CPPPATH. |
+ |
+.IP RCINCPREFIX |
+The prefix (flag) used to specify an include directory |
+on the resource compiler command line. |
+This will be appended to the beginning of each directory |
+in the $CPPPATH construction variable |
+when the $RCINCFLAGS variable is expanded. |
+ |
+.IP RCINCSUFFIX |
+The suffix used to specify an include directory |
+on the resource compiler command line. |
+This will be appended to the end of each directory |
+in the $CPPPATH construction variable |
+when the $RCINCFLAGS variable is expanded. |
+ |
+.IP RCS |
+The RCS executable. |
+Note that this variable is not actually used |
+for the command to fetch source files from RCS; |
+see the |
+$RCS_CO |
+construction variable, below. |
+ |
+.IP RCS_CO |
+The RCS "checkout" executable, |
+used to fetch source files from RCS. |
+ |
+.IP RCS_COCOM |
+The command line used to |
+fetch (checkout) source files from RCS. |
+ |
+.IP RCS_COCOMSTR |
+The string displayed when fetching |
+a source file from RCS. |
+If this is not set, then $RCS_COCOM |
+(the command line) is displayed. |
+ |
+.IP RCS_COFLAGS |
+Options that are passed to the $RCS_CO command. |
+ |
+.IP RDirs |
+A function that converts a string into a list of Dir instances by |
+searching the repositories. |
+ |
+.IP REGSVR |
+The program used on Windows systems |
+to register a newly-built DLL library |
+whenever the \fBSharedLibrary\fP() builder |
+is passed a keyword argument of \fBregister=1\fP. |
+ |
+.IP REGSVRCOM |
+The command line used on Windows systems |
+to register a newly-built DLL library |
+whenever the \fBSharedLibrary\fP() builder |
+is passed a keyword argument of \fBregister=1\fP. |
+ |
+.IP REGSVRCOMSTR |
+The string displayed when registering a newly-built DLL file. |
+If this is not set, then $REGSVRCOM (the command line) is displayed. |
+ |
+.IP REGSVRFLAGS |
+Flags passed to the DLL registration program |
+on Windows systems when a newly-built DLL library is registered. |
+By default, |
+this includes the \fB/s\fP |
+that prevents dialog boxes from popping up |
+and requiring user attention. |
+ |
+.IP RMIC |
+The Java RMI stub compiler. |
+ |
+.IP RMICCOM |
+The command line used to compile stub |
+and skeleton class files |
+from Java classes that contain RMI implementations. |
+Any options specified in the $RMICFLAGS construction variable |
+are included on this command line. |
+ |
+.IP RMICCOMSTR |
+The string displayed when compiling |
+stub and skeleton class files |
+from Java classes that contain RMI implementations. |
+If this is not set, then $RMICCOM (the command line) is displayed. |
+ |
+.ES |
+env = Environment(RMICCOMSTR = "Generating stub/skeleton class files $TARGETS from $SOURCES") |
+.EE |
+ |
+.IP RMICFLAGS |
+General options passed to the Java RMI stub compiler. |
+ |
+.IP _RPATH |
+An automatically-generated construction variable |
+containing the rpath flags to be used when linking |
+a program with shared libraries. |
+The value of $_RPATH is created |
+by appending $RPATHPREFIX and $RPATHSUFFIX |
+to the beginning and end |
+of each directory in $RPATH. |
+ |
+.IP RPATH |
+A list of paths to search for shared libraries when running programs. |
+Currently only used in the GNU (gnulink), |
+IRIX (sgilink) and Sun (sunlink) linkers. |
+Ignored on platforms and toolchains that don't support it. |
+Note that the paths added to RPATH |
+are not transformed by |
+.B scons |
+in any way: if you want an absolute |
+path, you must make it absolute yourself. |
+ |
+.IP RPATHPREFIX |
+The prefix used to specify a directory to be searched for |
+shared libraries when running programs. |
+This will be appended to the beginning of each directory |
+in the $RPATH construction variable |
+when the $_RPATH variable is automatically generated. |
+ |
+.IP RPATHSUFFIX |
+The suffix used to specify a directory to be searched for |
+shared libraries when running programs. |
+This will be appended to the end of each directory |
+in the $RPATH construction variable |
+when the $_RPATH variable is automatically generated. |
+ |
+.IP RPCGEN |
+The RPC protocol compiler. |
+ |
+.IP RPCGENCLIENTFLAGS |
+Options passed to the RPC protocol compiler |
+when generating client side stubs. |
+These are in addition to any flags specified in the |
+$RPCGENFLAGS |
+construction variable. |
+ |
+.IP RPCGENFLAGS |
+General options passed to the RPC protocol compiler. |
+ |
+.IP RPCGENHEADERFLAGS |
+Options passed to the RPC protocol compiler |
+when generating a header file. |
+These are in addition to any flags specified in the |
+$RPCGENFLAGS |
+construction variable. |
+ |
+.IP RPCGENSERVICEFLAGS |
+Options passed to the RPC protocol compiler |
+when generating server side stubs. |
+These are in addition to any flags specified in the |
+$RPCGENFLAGS |
+construction variable. |
+ |
+.IP RPCGENXDRFLAGS |
+Options passed to the RPC protocol compiler |
+when generating XDR routines. |
+These are in addition to any flags specified in the |
+$RPCGENFLAGS |
+construction variable. |
+ |
+.IP SCANNERS |
+A list of the available implicit dependency scanners. |
+New file scanners may be added by |
+appending to this list, |
+although the more flexible approach |
+is to associate scanners |
+with a specific Builder. |
+See the sections "Builder Objects" |
+and "Scanner Objects," |
+below, for more information. |
+ |
+.IP SCCS |
+The SCCS executable. |
+ |
+.IP SCCSCOM |
+The command line used to |
+fetch source files from SCCS. |
+ |
+.IP SCCSCOMSTR |
+The string displayed when fetching |
+a source file from a CVS repository. |
+If this is not set, then $SCCSCOM |
+(the command line) is displayed. |
+ |
+.IP SCCSFLAGS |
+General options that are passed to SCCS. |
+ |
+.IP SCCSGETFLAGS |
+Options that are passed specifically to the SCCS "get" subcommand. |
+This can be set, for example, to |
+.B \-e |
+to check out editable files from SCCS. |
+ |
+.IP SCONS_HOME |
+The (optional) path to the SCons library directory, |
+initialized from the external environment. |
+If set, this is used to construct a shorter and more |
+efficient search path in the |
+$MSVSSCONS |
+command line executed |
+from Microsoft Visual Studio project files. |
+ |
+.IP SHCC |
+The C compiler used for generating shared-library objects. |
+ |
+.IP SHCCCOM |
+The command line used to compile a C source file |
+to a shared-library object file. |
+Any options specified in the $SHCFLAGS, |
+$SHCCFLAGS and |
+$CPPFLAGS construction variables |
+are included on this command line. |
+ |
+.IP SHCCCOMSTR |
+The string displayed when a C source file |
+is compiled to a shared object file. |
+If this is not set, then $SHCCCOM (the command line) is displayed. |
+ |
+.ES |
+env = Environment(SHCCCOMSTR = "Compiling shared object $TARGET") |
+.EE |
+ |
+.IP SHCCFLAGS |
+Options that are passed to the C and C++ compilers |
+to generate shared-library objects. |
+ |
+.IP SHCFLAGS |
+Options that are passed to the C compiler (only; not C++) |
+to generate shared-library objects. |
+ |
+.IP SHCXX |
+The C++ compiler used for generating shared-library objects. |
+ |
+.IP SHCXXCOM |
+The command line used to compile a C++ source file |
+to a shared-library object file. |
+Any options specified in the $SHCXXFLAGS and |
+$CPPFLAGS construction variables |
+are included on this command line. |
+ |
+.IP SHCXXCOMSTR |
+The string displayed when a C++ source file |
+is compiled to a shared object file. |
+If this is not set, then $SHCXXCOM (the command line) is displayed. |
+ |
+.ES |
+env = Environment(SHCXXCOMSTR = "Compiling shared object $TARGET") |
+.EE |
+ |
+.IP SHCXXFLAGS |
+Options that are passed to the C++ compiler |
+to generate shared-library objects. |
+ |
+.IP SHELL |
+A string naming the shell program that will be passed to the |
+$SPAWN |
+function. |
+See the |
+$SPAWN |
+construction variable for more information. |
+ |
+.IP SHF77 |
+The Fortran 77 compiler used for generating shared-library objects. |
+You should normally set the $SHFORTRAN variable, |
+which specifies the default Fortran compiler |
+for all Fortran versions. |
+You only need to set $SHF77 if you need to use a specific compiler |
+or compiler version for Fortran 77 files. |
+ |
+.IP SHF77COM |
+The command line used to compile a Fortran 77 source file |
+to a shared-library object file. |
+You only need to set $SHF77COM if you need to use a specific |
+command line for Fortran 77 files. |
+You should normally set the $SHFORTRANCOM variable, |
+which specifies the default command line |
+for all Fortran versions. |
+ |
+.IP SHF77COMSTR |
+The string displayed when a Fortran 77 source file |
+is compiled to a shared-library object file. |
+If this is not set, then $SHF77COM or $SHFORTRANCOM |
+(the command line) is displayed. |
+ |
+.IP SHF77FLAGS |
+Options that are passed to the Fortran 77 compiler |
+to generated shared-library objects. |
+You only need to set $SHF77FLAGS if you need to define specific |
+user options for Fortran 77 files. |
+You should normally set the $SHFORTRANFLAGS variable, |
+which specifies the user-specified options |
+passed to the default Fortran compiler |
+for all Fortran versions. |
+ |
+.IP SHF77PPCOM |
+The command line used to compile a Fortran 77 source file to a |
+shared-library object file |
+after first running the file through the C preprocessor. |
+Any options specified in the $SHF77FLAGS and $CPPFLAGS construction variables |
+are included on this command line. |
+You only need to set $SHF77PPCOM if you need to use a specific |
+C-preprocessor command line for Fortran 77 files. |
+You should normally set the $SHFORTRANPPCOM variable, |
+which specifies the default C-preprocessor command line |
+for all Fortran versions. |
+ |
+.IP SHF77PPCOMSTR |
+The string displayed when a Fortran 77 source file |
+is compiled to a shared-library object file |
+after first running the file through the C preprocessor. |
+If this is not set, then $SHF77PPCOM or $SHFORTRANPPCOM |
+(the command line) is displayed. |
+ |
+.IP SHF90 |
+The Fortran 90 compiler used for generating shared-library objects. |
+You should normally set the $SHFORTRAN variable, |
+which specifies the default Fortran compiler |
+for all Fortran versions. |
+You only need to set $SHF90 if you need to use a specific compiler |
+or compiler version for Fortran 90 files. |
+ |
+.IP SHF90COM |
+The command line used to compile a Fortran 90 source file |
+to a shared-library object file. |
+You only need to set $SHF90COM if you need to use a specific |
+command line for Fortran 90 files. |
+You should normally set the $SHFORTRANCOM variable, |
+which specifies the default command line |
+for all Fortran versions. |
+ |
+.IP SHF90COMSTR |
+The string displayed when a Fortran 90 source file |
+is compiled to a shared-library object file. |
+If this is not set, then $SHF90COM or $SHFORTRANCOM |
+(the command line) is displayed. |
+ |
+.IP SHF90FLAGS |
+Options that are passed to the Fortran 90 compiler |
+to generated shared-library objects. |
+You only need to set $SHF90FLAGS if you need to define specific |
+user options for Fortran 90 files. |
+You should normally set the $SHFORTRANFLAGS variable, |
+which specifies the user-specified options |
+passed to the default Fortran compiler |
+for all Fortran versions. |
+ |
+.IP SHF90PPCOM |
+The command line used to compile a Fortran 90 source file to a |
+shared-library object file |
+after first running the file through the C preprocessor. |
+Any options specified in the $SHF90FLAGS and $CPPFLAGS construction variables |
+are included on this command line. |
+You only need to set $SHF90PPCOM if you need to use a specific |
+C-preprocessor command line for Fortran 90 files. |
+You should normally set the $SHFORTRANPPCOM variable, |
+which specifies the default C-preprocessor command line |
+for all Fortran versions. |
+ |
+.IP SHF90PPCOMSTR |
+The string displayed when a Fortran 90 source file |
+is compiled to a shared-library object file |
+after first running the file through the C preprocessor. |
+If this is not set, then $SHF90PPCOM or $SHFORTRANPPCOM |
+(the command line) is displayed. |
+ |
+.IP SHF95 |
+The Fortran 95 compiler used for generating shared-library objects. |
+You should normally set the $SHFORTRAN variable, |
+which specifies the default Fortran compiler |
+for all Fortran versions. |
+You only need to set $SHF95 if you need to use a specific compiler |
+or compiler version for Fortran 95 files. |
+ |
+.IP SHF95COM |
+The command line used to compile a Fortran 95 source file |
+to a shared-library object file. |
+You only need to set $SHF95COM if you need to use a specific |
+command line for Fortran 95 files. |
+You should normally set the $SHFORTRANCOM variable, |
+which specifies the default command line |
+for all Fortran versions. |
+ |
+.IP SHF95COMSTR |
+The string displayed when a Fortran 95 source file |
+is compiled to a shared-library object file. |
+If this is not set, then $SHF95COM or $SHFORTRANCOM |
+(the command line) is displayed. |
+ |
+.IP SHF95FLAGS |
+Options that are passed to the Fortran 95 compiler |
+to generated shared-library objects. |
+You only need to set $SHF95FLAGS if you need to define specific |
+user options for Fortran 95 files. |
+You should normally set the $SHFORTRANFLAGS variable, |
+which specifies the user-specified options |
+passed to the default Fortran compiler |
+for all Fortran versions. |
+ |
+.IP SHF95PPCOM |
+The command line used to compile a Fortran 95 source file to a |
+shared-library object file |
+after first running the file through the C preprocessor. |
+Any options specified in the $SHF95FLAGS and $CPPFLAGS construction variables |
+are included on this command line. |
+You only need to set $SHF95PPCOM if you need to use a specific |
+C-preprocessor command line for Fortran 95 files. |
+You should normally set the $SHFORTRANPPCOM variable, |
+which specifies the default C-preprocessor command line |
+for all Fortran versions. |
+ |
+.IP SHF95PPCOMSTR |
+The string displayed when a Fortran 95 source file |
+is compiled to a shared-library object file |
+after first running the file through the C preprocessor. |
+If this is not set, then $SHF95PPCOM or $SHFORTRANPPCOM |
+(the command line) is displayed. |
+ |
+.IP SHFORTRAN |
+The default Fortran compiler used for generating shared-library objects. |
+ |
+.IP SHFORTRANCOM |
+The command line used to compile a Fortran source file |
+to a shared-library object file. |
+ |
+.IP SHFORTRANCOMSTR |
+The string displayed when a Fortran source file |
+is compiled to a shared-library object file. |
+If this is not set, then $SHFORTRANCOM |
+(the command line) is displayed. |
+ |
+.IP SHFORTRANFLAGS |
+Options that are passed to the Fortran compiler |
+to generate shared-library objects. |
+ |
+.IP SHFORTRANPPCOM |
+The command line used to compile a Fortran source file to a |
+shared-library object file |
+after first running the file through the C preprocessor. |
+Any options specified |
+in the $SHFORTRANFLAGS and |
+$CPPFLAGS construction variables |
+are included on this command line. |
+ |
+.IP SHFORTRANPPCOMSTR |
+The string displayed when a Fortran source file |
+is compiled to a shared-library object file |
+after first running the file through the C preprocessor. |
+If this is not set, then $SHFORTRANPPCOM |
+(the command line) is displayed. |
+ |
+.IP SHLIBPREFIX |
+The prefix used for shared library file names. |
+ |
+.IP SHLIBSUFFIX |
+The suffix used for shared library file names. |
+ |
+.IP SHLINK |
+The linker for programs that use shared libraries. |
+ |
+.IP SHLINKCOM |
+The command line used to link programs using shared libraries. |
+ |
+.IP SHLINKCOMSTR |
+The string displayed when programs using shared libraries are linked. |
+If this is not set, then $SHLINKCOM (the command line) is displayed. |
+ |
+.ES |
+env = Environment(SHLINKCOMSTR = "Linking shared $TARGET") |
+.EE |
+ |
+.IP SHLINKFLAGS |
+General user options passed to the linker for programs using shared libraries. |
+Note that this variable should |
+.I not |
+contain |
+.B \-l |
+(or similar) options for linking with the libraries listed in $LIBS, |
+nor |
+.B \-L |
+(or similar) include search path options |
+that scons generates automatically from $LIBPATH. |
+See |
+$_LIBFLAGS |
+above, |
+for the variable that expands to library-link options, |
+and |
+$_LIBDIRFLAGS |
+above, |
+for the variable that expands to library search path options. |
+ |
+.IP SHOBJPREFIX |
+The prefix used for shared object file names. |
+ |
+.IP SHOBJSUFFIX |
+The suffix used for shared object file names. |
+ |
+.IP SOURCE |
+A reserved variable name |
+that may not be set or used in a construction environment. |
+(See "Variable Substitution," below.) |
+ |
+.IP SOURCE_URL |
+The URL |
+(web address) |
+of the location from which the project was retrieved. |
+This is used to fill in the |
+.B Source: |
+field in the controlling information for Ipkg and RPM packages. |
+ |
+.IP SOURCES |
+A reserved variable name |
+that may not be set or used in a construction environment. |
+(See "Variable Substitution," below.) |
+ |
+.IP SPAWN |
+A command interpreter function that will be called to execute command line |
+strings. The function must expect the following arguments: |
+ |
+.ES |
+def spawn(shell, escape, cmd, args, env): |
+.EE |
+.IP |
+.I sh |
+is a string naming the shell program to use. |
+.I escape |
+is a function that can be called to escape shell special characters in |
+the command line. |
+.I cmd |
+is the path to the command to be executed. |
+.I args |
+is the arguments to the command. |
+.I env |
+is a dictionary of the environment variables |
+in which the command should be executed. |
+ |
+.IP SUBST_DICT |
+The dictionary used by the \fBSubstfile\fP() or \fBTextfile\fP() builders |
+for substitution values. |
+It can be anything acceptable to the dict() constructor, |
+so in addition to a dictionary, |
+lists of tuples are also acceptable. |
+ |
+.IP SUBSTFILEPREFIX |
+The prefix used for \fBSubstfile\fP() file names, |
+the null string by default. |
+ |
+.IP SUBSTFILESUFFIX |
+The suffix used for \fBSubstfile\fP() file names, |
+the null string by default. |
+ |
+.IP SUMMARY |
+A short summary of what the project is about. |
+This is used to fill in the |
+.B Summary: |
+field in the controlling information for Ipkg and RPM packages, |
+and as the |
+.B Description: |
+field in MSI packages. |
+ |
+.IP SWIG |
+The scripting language wrapper and interface generator. |
+ |
+.IP SWIGCFILESUFFIX |
+The suffix that will be used for intermediate C |
+source files generated by |
+the scripting language wrapper and interface generator. |
+The default value is |
+.BR _wrap $CFILESUFFIX. |
+By default, this value is used whenever the |
+.B \-c++ |
+option is |
+.I not |
+specified as part of the |
+$SWIGFLAGS |
+construction variable. |
+ |
+.IP SWIGCOM |
+The command line used to call |
+the scripting language wrapper and interface generator. |
+ |
+.IP SWIGCOMSTR |
+The string displayed when calling |
+the scripting language wrapper and interface generator. |
+If this is not set, then $SWIGCOM (the command line) is displayed. |
+ |
+.IP SWIGCXXFILESUFFIX |
+The suffix that will be used for intermediate C++ |
+source files generated by |
+the scripting language wrapper and interface generator. |
+The default value is |
+.BR _wrap $CFILESUFFIX. |
+By default, this value is used whenever the |
+.B \-c++ |
+option is specified as part of the |
+$SWIGFLAGS |
+construction variable. |
+ |
+.IP SWIGDIRECTORSUFFIX |
+The suffix that will be used for intermediate C++ header |
+files generated by the scripting language wrapper and interface generator. |
+These are only generated for C++ code when the SWIG 'directors' feature is |
+turned on. |
+The default value is |
+.BR _wrap.h . |
+ |
+.IP SWIGFLAGS |
+General options passed to |
+the scripting language wrapper and interface generator. |
+This is where you should set |
+.BR \-python , |
+.BR \-perl5 , |
+.BR \-tcl , |
+or whatever other options you want to specify to SWIG. |
+If you set the |
+.B \-c++ |
+option in this variable, |
+.B scons |
+will, by default, |
+generate a C++ intermediate source file |
+with the extension that is specified as the |
+$CXXFILESUFFIX |
+variable. |
+ |
+.IP _SWIGINCFLAGS |
+An automatically-generated construction variable |
+containing the SWIG command-line options |
+for specifying directories to be searched for included files. |
+The value of $_SWIGINCFLAGS is created |
+by appending $SWIGINCPREFIX and $SWIGINCSUFFIX |
+to the beginning and end |
+of each directory in $SWIGPATH. |
+ |
+.IP SWIGINCPREFIX |
+The prefix used to specify an include directory on the SWIG command line. |
+This will be appended to the beginning of each directory |
+in the $SWIGPATH construction variable |
+when the $_SWIGINCFLAGS variable is automatically generated. |
+ |
+.IP SWIGINCSUFFIX |
+The suffix used to specify an include directory on the SWIG command line. |
+This will be appended to the end of each directory |
+in the $SWIGPATH construction variable |
+when the $_SWIGINCFLAGS variable is automatically generated. |
+ |
+.IP SWIGOUTDIR |
+Specifies the output directory in which |
+the scripting language wrapper and interface generator |
+should place generated language-specific files. |
+This will be used by SCons to identify |
+the files that will be generated by the &swig; call, |
+and translated into the |
+\fBswig -outdir\fP option on the command line. |
+ |
+.IP SWIGPATH |
+The list of directories that the scripting language wrapper |
+and interface generate will search for included files. |
+The SWIG implicit dependency scanner will search these |
+directories for include files. |
+The default is to use the same path |
+specified as $CPPPATH. |
+ |
+Don't explicitly put include directory |
+arguments in SWIGFLAGS; |
+the result will be non-portable |
+and the directories will not be searched by the dependency scanner. |
+Note: directory names in SWIGPATH will be looked-up relative to the SConscript |
+directory when they are used in a command. |
+To force |
+.B scons |
+to look-up a directory relative to the root of the source tree use #: |
+ |
+.ES |
+env = Environment(SWIGPATH='#/include') |
+.EE |
+.IP |
+The directory look-up can also be forced using the |
+.BR Dir () |
+function: |
+ |
+.ES |
+include = Dir('include') |
+env = Environment(SWIGPATH=include) |
+.EE |
+.IP |
+The directory list will be added to command lines |
+through the automatically-generated |
+$_SWIGINCFLAGS |
+construction variable, |
+which is constructed by |
+appending the values of the |
+$SWIGINCPREFIX and $SWIGINCSUFFIX |
+construction variables |
+to the beginning and end |
+of each directory in $SWIGPATH. |
+Any command lines you define that need |
+the SWIGPATH directory list should |
+include $_SWIGINCFLAGS: |
+ |
+.ES |
+env = Environment(SWIGCOM="my_swig -o $TARGET $_SWIGINCFLAGS $SORUCES") |
+.EE |
+ |
+.IP SWIGVERSION |
+The version number of the SWIG tool. |
+ |
+.IP TAR |
+The tar archiver. |
+ |
+.IP TARCOM |
+The command line used to call the tar archiver. |
+ |
+.IP TARCOMSTR |
+The string displayed when archiving files |
+using the tar archiver. |
+If this is not set, then $TARCOM (the command line) is displayed. |
+ |
+.ES |
+env = Environment(TARCOMSTR = "Archiving $TARGET") |
+.EE |
+ |
+.IP TARFLAGS |
+General options passed to the tar archiver. |
+ |
+.IP TARGET |
+A reserved variable name |
+that may not be set or used in a construction environment. |
+(See "Variable Substitution," below.) |
+ |
+.IP TARGET_ARCH |
+Sets the target architecture for Visual Studio compiler (i.e. the arch |
+of the binaries generated by the compiler). If not set, default to |
+$HOST_ARCH, 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 $TEXCOM (the command line) is displayed. |
+ |
+.ES |
+env = Environment(TEXCOMSTR = "Building $TARGET from TeX input $SOURCES") |
+.EE |
+ |
+.IP TEXFLAGS |
+General options passed to the TeX formatter and typesetter. |
+ |
+.IP TEXINPUTS |
+List of directories that the LaTeX 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 $WINDOWS_INSERT_DEF. |
+ |
+.IP WIN32DEFPREFIX |
+A deprecated synonym for $WINDOWSDEFPREFIX. |
+ |
+.IP WIN32DEFSUFFIX |
+A deprecated synonym for $WINDOWSDEFSUFFIX. |
+ |
+.IP WIN32EXPPREFIX |
+A deprecated synonym for $WINDOWSEXPSUFFIX. |
+ |
+.IP WIN32EXPSUFFIX |
+A deprecated synonym for $WINDOWSEXPSUFFIX. |
+ |
+.IP WINDOWS_INSERT_DEF |
+When this is set to true, |
+a library build of a Windows shared library |
+.RB ( .dll 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\fPfile names. |
+ |
+.IP WINDOWSDEFSUFFIX |
+The suffix used for Windows \fB.def\fP file names. |
+ |
+.IP WINDOWSEXPPREFIX |
+The prefix used for Windows \fB.exp\fP file names. |
+ |
+.IP WINDOWSEXPSUFFIX |
+The suffix used for Windows \fB.exp\fP file names. |
+ |
+.IP WINDOWSPROGMANIFESTPREFIX |
+The prefix used for executable program \fB.manifest\fP files |
+generated by Microsoft Visual C/C++. |
+ |
+.IP WINDOWSPROGMANIFESTSUFFIX |
+The suffix used for executable program \fB.manifest\fP files |
+generated by Microsoft Visual C/C++. |
+ |
+.IP WINDOWSSHLIBMANIFESTPREFIX |
+The prefix used for shared library \fB.manifest\fP files |
+generated by Microsoft Visual C/C++. |
+ |
+.IP WINDOWSSHLIBMANIFESTSUFFIX |
+The suffix used for shared library \fB.manifest\fP files |
+generated by Microsoft Visual C/C++. |
+ |
+.IP X_IPK_DEPENDS |
+This is used to fill in the |
+.B Depends: |
+field in the controlling information for Ipkg packages. |
+ |
+.IP X_IPK_DESCRIPTION |
+This is used to fill in the |
+.B Description: |
+field in the controlling information for Ipkg packages. |
+The default value is |
+.B "$SUMMARY\\\\$SUMMARY" |
+.IP X_IPK_MAINTAINER |
+This is used to fill in the |
+.B Maintainer: |
+field in the controlling information for Ipkg packages. |
+ |
+.IP X_IPK_PRIORITY |
+This is used to fill in the |
+.B Priority: |
+field in the controlling information for Ipkg packages. |
+ |
+.IP X_IPK_SECTION |
+This is used to fill in the |
+.B Section: |
+field in the controlling information for Ipkg packages. |
+ |
+.IP X_MSI_LANGUAGE |
+This is used to fill in the |
+.B Language: |
+attribute in the controlling information for MSI packages. |
+ |
+.IP X_MSI_LICENSE_TEXT |
+The text of the software license in RTF format. |
+Carriage return characters will be |
+replaced with the RTF equivalent \\\par. |
+ |
+.IP X_MSI_UPGRADE_CODE |
+TODO |
+ |
+.IP X_RPM_AUTOREQPROV |
+This is used to fill in the |
+.B AutoReqProv: |
+field in the RPM |
+\fB.spec\fP file. |
+ |
+.IP X_RPM_BUILD |
+internal, but overridable |
+ |
+.IP X_RPM_BUILDREQUIRES |
+This is used to fill in the |
+.B BuildRequires: |
+field in the RPM |
+\fB.spec\fP file. |
+ |
+.IP X_RPM_BUILDROOT |
+internal, but overridable |
+ |
+.IP X_RPM_CLEAN |
+internal, but overridable |
+ |
+.IP X_RPM_CONFLICTS |
+This is used to fill in the |
+.B Conflicts: |
+field in the RPM |
+\fB.spec\fP file. |
+ |
+.IP X_RPM_DEFATTR |
+This value is used as the default attributes |
+for the files in the RPM package. |
+The default value is |
+.BR (-,root,root) . |
+ |
+.IP X_RPM_DISTRIBUTION |
+This is used to fill in the |
+.B Distribution: |
+field in the RPM |
+\fB.spec\fP file. |
+ |
+.IP X_RPM_EPOCH |
+This is used to fill in the |
+.B Epoch: |
+field in the controlling information for RPM packages. |
+ |
+.IP X_RPM_EXCLUDEARCH |
+This is used to fill in the |
+.B ExcludeArch: |
+field in the RPM |
+\fB.spec\fP file. |
+ |
+.IP X_RPM_EXLUSIVEARCH |
+This is used to fill in the |
+.B ExclusiveArch: |
+field in the RPM |
+\fB.spec\fP file. |
+ |
+.IP X_RPM_GROUP |
+This is used to fill in the |
+.B Group: |
+field in the RPM |
+\fB.spec\fP file. |
+ |
+.IP X_RPM_GROUP_lang |
+This is used to fill in the |
+.B Group(lang): |
+field in the RPM |
+\fB.spec\fP file. |
+Note that |
+.I lang |
+is not literal |
+and should be replaced by |
+the appropriate language code. |
+ |
+.IP X_RPM_ICON |
+This is used to fill in the |
+.B Icon: |
+field in the RPM |
+\fB.spec\fP file. |
+ |
+.IP X_RPM_INSTALL |
+internal, but overridable |
+ |
+.IP X_RPM_PACKAGER |
+This is used to fill in the |
+.B Packager: |
+field in the RPM |
+\fB.spec\fP file. |
+ |
+.IP X_RPM_POSTINSTALL |
+This is used to fill in the |
+.B %post: |
+section in the RPM |
+\fB.spec\fP file. |
+ |
+.IP X_RPM_POSTUNINSTALL |
+This is used to fill in the |
+.B %postun: |
+section in the RPM |
+\fB.spec\fP file. |
+ |
+.IP X_RPM_PREFIX |
+This is used to fill in the |
+.B Prefix: |
+field in the RPM |
+\fB.spec\fP file. |
+ |
+.IP X_RPM_PREINSTALL |
+This is used to fill in the |
+.B %pre: |
+section in the RPM |
+\fB.spec\fP file. |
+ |
+.IP X_RPM_PREP |
+internal, but overridable |
+ |
+.IP X_RPM_PREUNINSTALL |
+This is used to fill in the |
+.B %preun: |
+section in the RPM |
+\fB.spec\fP file. |
+ |
+.IP X_RPM_PROVIDES |
+This is used to fill in the |
+.B Provides: |
+field in the RPM |
+\fB.spec\fP file. |
+ |
+.IP X_RPM_REQUIRES |
+This is used to fill in the |
+.B Requires: |
+field in the RPM |
+\fB.spec\fP file. |
+ |
+.IP X_RPM_SERIAL |
+This is used to fill in the |
+.B Serial: |
+field in the RPM |
+\fB.spec\fP file. |
+ |
+.IP X_RPM_URL |
+This is used to fill in the |
+.B Url: |
+field in the RPM |
+\fB.spec\fP file. |
+ |
+.IP YACC |
+The parser generator. |
+ |
+.IP YACCCOM |
+The command line used to call the parser generator |
+to generate a source file. |
+ |
+.IP YACCCOMSTR |
+The string displayed when generating a source file |
+using the parser generator. |
+If this is not set, then $YACCCOM (the command line) is displayed. |
+ |
+.ES |
+env = Environment(YACCCOMSTR = "Yacc'ing $TARGET from $SOURCES") |
+.EE |
+ |
+.IP YACCFLAGS |
+General options passed to the parser generator. |
+If $YACCFLAGS contains a \fB\-d\fP option, |
+SCons assumes that the call will also create a .h file |
+(if the yacc source file ends in a .y suffix) |
+or a .hpp file |
+(if the yacc source file ends in a .yy suffix) |
+ |
+.IP YACCHFILESUFFIX |
+The suffix of the C |
+header file generated by the parser generator |
+when the |
+.B \-d |
+option is used. |
+Note that setting this variable does not cause |
+the parser generator to generate a header |
+file with the specified suffix, |
+it exists to allow you to specify |
+what suffix the parser generator will use of its own accord. |
+The default value is |
+.BR .h . |
+ |
+.IP YACCHXXFILESUFFIX |
+The suffix of the C++ |
+header file generated by the parser generator |
+when the |
+.B \-d |
+option is used. |
+Note that setting this variable does not cause |
+the parser generator to generate a header |
+file with the specified suffix, |
+it exists to allow you to specify |
+what suffix the parser generator will use of its own accord. |
+The default value is |
+.BR .hpp , |
+except on Mac OS X, |
+where the default is |
+.BR ${TARGET.suffix}.h . |
+because the default &bison; parser generator just |
+appends \fB.h\fP |
+to the name of the generated C++ file. |
+ |
+.IP YACCVCGFILESUFFIX |
+The suffix of the file |
+containing the VCG grammar automaton definition |
+when the |
+.B \-\-graph= |
+option is used. |
+Note that setting this variable does not cause |
+the parser generator to generate a VCG |
+file with the specified suffix, |
+it exists to allow you to specify |
+what suffix the parser generator will use of its own accord. |
+The default value is |
+.BR .vcg . |
+ |
+.IP ZIP |
+The zip compression and file packaging utility. |
+ |
+.IP ZIPCOM |
+The command line used to call the zip utility, |
+or the internal Python function used to create a |
+zip archive. |
+ |
+.IP ZIPCOMPRESSION |
+The |
+.I compression |
+flag |
+from the Python |
+.B zipfile |
+module used by the internal Python function |
+to control whether the zip archive |
+is compressed or not. |
+The default value is |
+.BR zipfile.ZIP_DEFLATED , |
+which creates a compressed zip archive. |
+This value has no effect 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 $ZIPCOM |
+(the command line or internal Python function) is displayed. |
+ |
+.ES |
+env = Environment(ZIPCOMSTR = "Zipping $TARGET") |
+.EE |
+ |
+.IP ZIPFLAGS |
+General options passed to the zip utility. |
+ |
+.IP ZIPSUFFIX |
+The suffix used for zip file names. |
+'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" |
+'\" END GENERATED CONSTRUCTION VARIABLE DESCRIPTIONS |
+'\" |
+'\" The descriptions above of the various SCons construction variables |
+'\" are generated from the .xml files that live next to the various |
+'\" Python modules in the build enginer library. If you're reading |
+'\" this [gnt]roff file with an eye towards patching this man page, |
+'\" you can still submit a diff against this text, but it will have to |
+'\" be translated to a diff against the underlying .xml file before the |
+'\" patch is actually accepted. If you do that yourself, it will make |
+'\" it easier to integrate the patch. |
+'\" |
+'\" END GENERATED CONSTRUCTION VARIABLE DESCRIPTIONS |
+'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" |
+ |
+.LP |
+Construction variables can be retrieved and set using the |
+.B Dictionary |
+method of the construction environment: |
+ |
+.ES |
+dict = env.Dictionary() |
+dict["CC"] = "cc" |
+.EE |
+ |
+or using the [] operator: |
+ |
+.ES |
+env["CC"] = "cc" |
+.EE |
+ |
+Construction variables can also be passed to the construction environment |
+constructor: |
+ |
+.ES |
+env = Environment(CC="cc") |
+.EE |
+ |
+or when copying a construction environment using the |
+.B Clone |
+method: |
+ |
+.ES |
+env2 = env.Clone(CC="cl.exe") |
+.EE |
+ |
+.SS Configure Contexts |
+ |
+.B scons |
+supports |
+.I configure contexts, |
+an integrated mechanism similar to the |
+various AC_CHECK macros in GNU autoconf |
+for testing for the existence of C header |
+files, libraries, etc. |
+In contrast to autoconf, |
+.B scons |
+does not maintain an explicit cache of the tested values, |
+but uses its normal dependency tracking to keep the checked values |
+up to date. However, users may override this behaviour with the |
+.B --config |
+command line option. |
+ |
+The following methods can be used to perform checks: |
+ |
+.TP |
+.RI Configure( env ", [" custom_tests ", " conf_dir ", " log_file ", " config_h ", " clean ", " help]) |
+.TP |
+.RI env.Configure([ custom_tests ", " conf_dir ", " log_file ", " config_h ", " clean ", " help]) |
+This creates a configure context, which can be used to perform checks. |
+.I env |
+specifies the environment for building the tests. |
+This environment may be modified when performing checks. |
+.I custom_tests |
+is a dictionary containing custom tests. |
+See also the section about custom tests below. |
+By default, no custom tests are added to the configure context. |
+.I conf_dir |
+specifies a directory where the test cases are built. |
+Note that this directory is not used for building |
+normal targets. |
+The default value is the directory |
+#/.sconf_temp. |
+.I log_file |
+specifies a file which collects the output from commands |
+that are executed to check for the existence of header files, libraries, etc. |
+The default is the file #/config.log. |
+If you are using the |
+.BR VariantDir () |
+method, |
+you may want to specify a subdirectory under your variant directory. |
+.I config_h |
+specifies a C header file where the results of tests |
+will be written, e.g. #define HAVE_STDIO_H, #define HAVE_LIBM, etc. |
+The default is to not write a |
+.B config.h |
+file. |
+You can specify the same |
+.B config.h |
+file in multiple calls to Configure, |
+in which case |
+.B scons |
+will concatenate all results in the specified file. |
+Note that SCons |
+uses its normal dependency checking |
+to decide if it's necessary to rebuild |
+the specified |
+.I config_h |
+file. |
+This means that the file is not necessarily re-built each |
+time scons is run, |
+but is only rebuilt if its contents will have changed |
+and some target that depends on the |
+.I config_h |
+file is being built. |
+ |
+The optional |
+.B clean |
+and |
+.B help |
+arguments can be used to suppress execution of the configuration |
+tests when the |
+.B -c/--clean |
+or |
+.B -H/-h/--help |
+options are used, respectively. |
+The default behavior is always to execute |
+configure context tests, |
+since the results of the tests may |
+affect the list of targets to be cleaned |
+or the help text. |
+If the configure tests do not affect these, |
+then you may add the |
+.B clean=False |
+or |
+.B help=False |
+arguments |
+(or both) |
+to avoid unnecessary test execution. |
+ |
+.EE |
+A created |
+.B Configure |
+instance has the following associated methods: |
+ |
+.TP |
+.RI SConf.Finish( context ) |
+.TP |
+.IR sconf .Finish() |
+This method should be called after configuration is done. |
+It returns the environment as modified |
+by the configuration checks performed. |
+After this method is called, no further checks can be performed |
+with this configuration context. |
+However, you can create a new |
+.RI Configure |
+context to perform additional checks. |
+Only one context should be active at a time. |
+ |
+The following Checks are predefined. |
+(This list will likely grow larger as time |
+goes by and developers contribute new useful tests.) |
+ |
+.TP |
+.RI SConf.CheckHeader( context ", " header ", [" include_quotes ", " language ]) |
+.TP |
+.IR sconf .CheckHeader( header ", [" include_quotes ", " language ]) |
+Checks if |
+.I header |
+is usable in the specified language. |
+.I header |
+may be a list, |
+in which case the last item in the list |
+is the header file to be checked, |
+and the previous list items are |
+header files whose |
+.B #include |
+lines should precede the |
+header line being checked for. |
+The optional argument |
+.I include_quotes |
+must be |
+a two character string, where the first character denotes the opening |
+quote and the second character denotes the closing quote. |
+By default, both characters are " (double quote). |
+The optional argument |
+.I language |
+should be either |
+.B C |
+or |
+.B C++ |
+and selects the compiler to be used for the check. |
+Returns 1 on success and 0 on failure. |
+ |
+.TP |
+.RI SConf.CheckCHeader( context ", " header ", [" include_quotes ]) |
+.TP |
+.IR sconf .CheckCHeader( header ", [" include_quotes ]) |
+This is a wrapper around |
+.B SConf.CheckHeader |
+which checks if |
+.I header |
+is usable in the C language. |
+.I header |
+may be a list, |
+in which case the last item in the list |
+is the header file to be checked, |
+and the previous list items are |
+header files whose |
+.B #include |
+lines should precede the |
+header line being checked for. |
+The optional argument |
+.I include_quotes |
+must be |
+a two character string, where the first character denotes the opening |
+quote and the second character denotes the closing quote (both default |
+to \N'34'). |
+Returns 1 on success and 0 on failure. |
+ |
+.TP |
+.RI SConf.CheckCXXHeader( context ", " header ", [" include_quotes ]) |
+.TP |
+.IR sconf .CheckCXXHeader( header ", [" include_quotes ]) |
+This is a wrapper around |
+.B SConf.CheckHeader |
+which checks if |
+.I header |
+is usable in the C++ language. |
+.I header |
+may be a list, |
+in which case the last item in the list |
+is the header file to be checked, |
+and the previous list items are |
+header files whose |
+.B #include |
+lines should precede the |
+header line being checked for. |
+The optional argument |
+.I include_quotes |
+must be |
+a two character string, where the first character denotes the opening |
+quote and the second character denotes the closing quote (both default |
+to \N'34'). |
+Returns 1 on success and 0 on failure. |
+ |
+.TP |
+.RI SConf.CheckFunc( context, ", " function_name ", [" header ", " language ]) |
+.TP |
+.IR sconf .CheckFunc( function_name ", [" header ", " language ]) |
+Checks if the specified |
+C or C++ function is available. |
+.I function_name |
+is the name of the function to check for. |
+The optional |
+.I header |
+argument is a string |
+that will be |
+placed at the top |
+of the test file |
+that will be compiled |
+to check if the function exists; |
+the default is: |
+.ES |
+#ifdef __cplusplus |
+extern "C" |
+#endif |
+char function_name(); |
+.EE |
+The optional |
+.I language |
+argument should be |
+.B C |
+or |
+.B C++ |
+and selects the compiler to be used for the check; |
+the default is "C". |
+ |
+.TP |
+.RI SConf.CheckLib( context ", [" library ", " symbol ", " header ", " language ", " autoadd=1 ]) |
+.TP |
+.IR sconf .CheckLib([ library ", " symbol ", " header ", " language ", " autoadd=1 ]) |
+Checks if |
+.I library |
+provides |
+.IR symbol . |
+If the value of |
+.I autoadd |
+is 1 and the library provides the specified |
+.IR symbol , |
+appends the library to the LIBS construction environment variable. |
+.I library |
+may also be None (the default), |
+in which case |
+.I symbol |
+is checked with the current LIBS variable, |
+or a list of library names, |
+in which case each library in the list |
+will be checked for |
+.IR symbol . |
+If |
+.I symbol |
+is not set or is |
+.BR None , |
+then |
+.BR SConf.CheckLib () |
+just checks if |
+you can link against the specified |
+.IR library . |
+The optional |
+.I language |
+argument should be |
+.B C |
+or |
+.B C++ |
+and selects the compiler to be used for the check; |
+the default is "C". |
+The default value for |
+.I autoadd |
+is 1. |
+This method returns 1 on success and 0 on error. |
+ |
+.TP |
+.RI SConf.CheckLibWithHeader( context ", " library ", " header ", " language ", [" call ", " autoadd ]) |
+.TP |
+.IR sconf .CheckLibWithHeader( library ", " header ", " language ", [" call ", " autoadd ]) |
+ |
+In contrast to the |
+.RI SConf.CheckLib |
+call, this call provides a more sophisticated way to check against libraries. |
+Again, |
+.I library |
+specifies the library or a list of libraries to check. |
+.I header |
+specifies a header to check for. |
+.I header |
+may be a list, |
+in which case the last item in the list |
+is the header file to be checked, |
+and the previous list items are |
+header files whose |
+.B #include |
+lines should precede the |
+header line being checked for. |
+.I language |
+may be one of 'C','c','CXX','cxx','C++' and 'c++'. |
+.I call |
+can be any valid expression (with a trailing ';'). |
+If |
+.I call |
+is not set, |
+the default simply checks that you |
+can link against the specified |
+.IR library . |
+.I autoadd |
+specifies whether to add the library to the environment (only if the check |
+succeeds). This method returns 1 on success and 0 on error. |
+ |
+.TP |
+.RI SConf.CheckType( context ", " type_name ", [" includes ", " language ]) |
+.TP |
+.IR sconf .CheckType( type_name ", [" includes ", " language ]) |
+Checks for the existence of a type defined by |
+.BR typedef . |
+.I type_name |
+specifies the typedef name to check for. |
+.I includes |
+is a string containing one or more |
+.B #include |
+lines that will be inserted into the program |
+that will be run to test for the existence of the type. |
+The optional |
+.I language |
+argument should be |
+.B C |
+or |
+.B C++ |
+and selects the compiler to be used for the check; |
+the default is "C". |
+Example: |
+.ES |
+sconf.CheckType('foo_type', '#include "my_types.h"', 'C++') |
+.EE |
+ |
+.TP |
+.RI Configure.CheckCC( self ) |
+Checks whether the C compiler (as defined by the CC construction variable) works |
+by trying to compile a small source file. |
+ |
+By default, SCons only detects if there is a program with the correct name, not |
+if it is a functioning compiler. |
+ |
+This uses the exact same command than the one used by the object builder for C |
+source file, so it can be used to detect if a particular compiler flag works or |
+not. |
+ |
+.TP |
+.RI Configure.CheckCXX( self ) |
+Checks whether the C++ compiler (as defined by the CXX construction variable) |
+works by trying to compile a small source file. By default, SCons only detects |
+if there is a program with the correct name, not if it is a functioning compiler. |
+ |
+This uses the exact same command than the one used by the object builder for |
+CXX source files, so it can be used to detect if a particular compiler flag |
+works or not. |
+ |
+.TP |
+.RI Configure.CheckSHCC( self ) |
+Checks whether the C compiler (as defined by the SHCC construction variable) works |
+by trying to compile a small source file. By default, SCons only detects if |
+there is a program with the correct name, not if it is a functioning compiler. |
+ |
+This uses the exact same command than the one used by the object builder for C |
+source file, so it can be used to detect if a particular compiler flag works or |
+not. This does not check whether the object code can be used to build a shared |
+library, only that the compilation (not link) succeeds. |
+ |
+.TP |
+.RI Configure.CheckSHCXX( self ) |
+Checks whether the C++ compiler (as defined by the SHCXX construction variable) |
+works by trying to compile a small source file. By default, SCons only detects |
+if there is a program with the correct name, not if it is a functioning compiler. |
+ |
+This uses the exact same command than the one used by the object builder for |
+CXX source files, so it can be used to detect if a particular compiler flag |
+works or not. This does not check whether the object code can be used to build |
+a shared library, only that the compilation (not link) succeeds. |
+ |
+.EE |
+Example of a typical Configure usage: |
+ |
+.ES |
+env = Environment() |
+conf = Configure( env ) |
+if not conf.CheckCHeader( 'math.h' ): |
+ print 'We really need math.h!' |
+ Exit(1) |
+if conf.CheckLibWithHeader( 'qt', 'qapp.h', 'c++', |
+ 'QApplication qapp(0,0);' ): |
+ # do stuff for qt - usage, e.g. |
+ conf.env.Append( CPPFLAGS = '-DWITH_QT' ) |
+env = conf.Finish() |
+.EE |
+ |
+.TP |
+.RI SConf.CheckTypeSize( context ", " type_name ", [" header ", " language ", " expect ]) |
+.TP |
+.IR sconf .CheckTypeSize( type_name ", [" header ", " language ", " expect ]) |
+Checks for the size of a type defined by |
+.BR typedef . |
+.I type_name |
+specifies the typedef name to check for. |
+The optional |
+.I header |
+argument is a string |
+that will be |
+placed at the top |
+of the test file |
+that will be compiled |
+to check if the function exists; |
+the default is empty. |
+The optional |
+.I language |
+argument should be |
+.B C |
+or |
+.B C++ |
+and selects the compiler to be used for the check; |
+the default is "C". |
+The optional |
+.I expect |
+argument should be an integer. |
+If this argument is used, |
+the function will only check whether the type |
+given in type_name has the expected size (in bytes). |
+For example, |
+.B "CheckTypeSize('short', expect = 2)" |
+will return success only if short is two bytes. |
+ |
+.ES |
+.EE |
+ |
+.TP |
+.RI SConf.CheckDeclaration( context ", " symbol ", [" includes ", " language ]) |
+.TP |
+.IR sconf .CheckDeclaration( symbol ", [" includes ", " language ]) |
+Checks if the specified |
+.I symbol |
+is declared. |
+.I includes |
+is a string containing one or more |
+.B #include |
+lines that will be inserted into the program |
+that will be run to test for the existence of the type. |
+The optional |
+.I language |
+argument should be |
+.B C |
+or |
+.B C++ |
+and selects the compiler to be used for the check; |
+the default is "C". |
+ |
+.TP |
+.RI SConf.Define( context ", " symbol ", [" value ", " comment ]) |
+.TP |
+.IR sconf .Define( symbol ", [" value ", " comment ]) |
+This function does not check for anything, but defines a |
+preprocessor symbol that will be added to the configuration header file. |
+It is the equivalent of AC_DEFINE, |
+and defines the symbol |
+.I name |
+with the optional |
+.B value |
+and the optional comment |
+.BR comment . |
+ |
+.IP |
+Examples: |
+ |
+.ES |
+env = Environment() |
+conf = Configure( env ) |
+ |
+# Puts the following line in the config header file: |
+# #define A_SYMBOL |
+conf.Define('A_SYMBOL') |
+ |
+# Puts the following line in the config header file: |
+# #define A_SYMBOL 1 |
+conf.Define('A_SYMBOL', 1) |
+.EE |
+ |
+.IP |
+Be careful about quoting string values, though: |
+ |
+.ES |
+env = Environment() |
+conf = Configure( env ) |
+ |
+# Puts the following line in the config header file: |
+# #define A_SYMBOL YA |
+conf.Define('A_SYMBOL', "YA") |
+ |
+# Puts the following line in the config header file: |
+# #define A_SYMBOL "YA" |
+conf.Define('A_SYMBOL', '"YA"') |
+.EE |
+ |
+.IP |
+For comment: |
+ |
+.ES |
+env = Environment() |
+conf = Configure( env ) |
+ |
+# Puts the following lines in the config header file: |
+# /* Set to 1 if you have a symbol */ |
+# #define A_SYMBOL 1 |
+conf.Define('A_SYMBOL', 1, 'Set to 1 if you have a symbol') |
+.EE |
+ |
+.EE |
+You can define your own custom checks. |
+in addition to the predefined checks. |
+These are passed in a dictionary to the Configure function. |
+This dictionary maps the names of the checks |
+to user defined Python callables |
+(either Python functions or class instances implementing the |
+.I __call__ |
+method). |
+The first argument of the call is always a |
+.I CheckContext |
+instance followed by the arguments, |
+which must be supplied by the user of the check. |
+These CheckContext instances define the following methods: |
+ |
+.TP |
+.RI CheckContext.Message( self ", " text ) |
+ |
+Usually called before the check is started. |
+.I text |
+will be displayed to the user, e.g. 'Checking for library X...' |
+ |
+.TP |
+.RI CheckContext.Result( self, ", " res ) |
+ |
+Usually called after the check is done. |
+.I res |
+can be either an integer or a string. In the former case, 'yes' (res != 0) |
+or 'no' (res == 0) is displayed to the user, in the latter case the |
+given string is displayed. |
+ |
+.TP |
+.RI CheckContext.TryCompile( self ", " text ", " extension ) |
+Checks if a file with the specified |
+.I extension |
+(e.g. '.c') containing |
+.I text |
+can be compiled using the environment's |
+.B Object |
+builder. Returns 1 on success and 0 on failure. |
+ |
+.TP |
+.RI CheckContext.TryLink( self ", " text ", " extension ) |
+Checks, if a file with the specified |
+.I extension |
+(e.g. '.c') containing |
+.I text |
+can be compiled using the environment's |
+.B Program |
+builder. Returns 1 on success and 0 on failure. |
+ |
+.TP |
+.RI CheckContext.TryRun( self ", " text ", " extension ) |
+Checks, if a file with the specified |
+.I extension |
+(e.g. '.c') containing |
+.I text |
+can be compiled using the environment's |
+.B Program |
+builder. On success, the program is run. If the program |
+executes successfully |
+(that is, its return status is 0), |
+a tuple |
+.I (1, outputStr) |
+is returned, where |
+.I outputStr |
+is the standard output of the |
+program. |
+If the program fails execution |
+(its return status is non-zero), |
+then (0, '') is returned. |
+ |
+.TP |
+.RI CheckContext.TryAction( self ", " action ", [" text ", " extension ]) |
+Checks if the specified |
+.I action |
+with an optional source file (contents |
+.I text |
+, extension |
+.I extension |
+= '' |
+) can be executed. |
+.I action |
+may be anything which can be converted to a |
+.B scons |
+.RI Action. |
+On success, |
+.I (1, outputStr) |
+is returned, where |
+.I outputStr |
+is the content of the target file. |
+On failure |
+.I (0, '') |
+is returned. |
+ |
+.TP |
+.RI CheckContext.TryBuild( self ", " builder ", [" text ", " extension ]) |
+Low level implementation for testing specific builds; |
+the methods above are based on this method. |
+Given the Builder instance |
+.I builder |
+and the optional |
+.I text |
+of a source file with optional |
+.IR extension , |
+this method returns 1 on success and 0 on failure. In addition, |
+.I self.lastTarget |
+is set to the build target node, if the build was successful. |
+ |
+.EE |
+Example for implementing and using custom tests: |
+ |
+.ES |
+def CheckQt(context, qtdir): |
+ context.Message( 'Checking for qt ...' ) |
+ lastLIBS = context.env['LIBS'] |
+ lastLIBPATH = context.env['LIBPATH'] |
+ lastCPPPATH= context.env['CPPPATH'] |
+ context.env.Append(LIBS = 'qt', LIBPATH = qtdir + '/lib', CPPPATH = qtdir + '/include' ) |
+ ret = context.TryLink(""" |
+#include <qapp.h> |
+int main(int argc, char **argv) { |
+ QApplication qapp(argc, argv); |
+ return 0; |
+} |
+""") |
+ if not ret: |
+ context.env.Replace(LIBS = lastLIBS, LIBPATH=lastLIBPATH, CPPPATH=lastCPPPATH) |
+ context.Result( ret ) |
+ return ret |
+ |
+env = Environment() |
+conf = Configure( env, custom_tests = { 'CheckQt' : CheckQt } ) |
+if not conf.CheckQt('/usr/lib/qt'): |
+ print 'We really need qt!' |
+ Exit(1) |
+env = conf.Finish() |
+.EE |
+ |
+.SS Command-Line Construction Variables |
+ |
+Often when building software, |
+some variables must be specified at build time. |
+For example, libraries needed for the build may be in non-standard |
+locations, or site-specific compiler options may need to be passed to the |
+compiler. |
+.B scons |
+provides a |
+.B Variables |
+object to support overriding construction variables |
+on the command line: |
+.ES |
+$ scons VARIABLE=foo |
+.EE |
+The variable values can also be specified in a text-based SConscript file. |
+To create a Variables object, call the Variables() function: |
+ |
+.TP |
+.RI Variables([ files "], [" args ]) |
+This creates a Variables object that will read construction variables from |
+the file or list of filenames specified in |
+.IR files . |
+If no files are specified, |
+or the |
+.I files |
+argument is |
+.BR None , |
+then no files will be read. |
+The optional argument |
+.I args |
+is a dictionary of |
+values that will override anything read from the specified files; |
+it is primarily intended to be passed the |
+.B ARGUMENTS |
+dictionary that holds variables |
+specified on the command line. |
+Example: |
+ |
+.ES |
+vars = Variables('custom.py') |
+vars = Variables('overrides.py', ARGUMENTS) |
+vars = Variables(None, {FOO:'expansion', BAR:7}) |
+.EE |
+ |
+Variables objects have the following methods: |
+ |
+.TP |
+.RI Add( key ", [" help ", " default ", " validator ", " converter ]) |
+This adds a customizable construction variable to the Variables object. |
+.I key |
+is the name of the variable. |
+.I help |
+is the help text for the variable. |
+.I default |
+is the default value of the variable; |
+if the default value is |
+.B None |
+and there is no explicit value specified, |
+the construction variable will |
+.I not |
+be added to the construction environment. |
+.I validator |
+is called to validate the value of the variable, and should take three |
+arguments: key, value, and environment. |
+The recommended way to handle an invalid value is |
+to raise an exception (see example below). |
+.I converter |
+is called to convert the value before putting it in the environment, and |
+should take either a value, or the value and environment, as parameters. |
+The |
+.I converter |
+must return a value, |
+which will be converted into a string |
+before being validated by the |
+.I validator |
+(if any) |
+and then added to the environment. |
+ |
+Examples: |
+ |
+.ES |
+vars.Add('CC', 'The C compiler') |
+ |
+def validate_color(key, val, env): |
+ if not val in ['red', 'blue', 'yellow']: |
+ raise 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 |
+(See the section "Scanner Objects," below, |
+for information about creating Scanner objects.) |
+ |
+.IP source_scanner |
+A Scanner object that |
+will be invoked to |
+find implicit dependences in |
+any source files |
+used to build this target file. |
+This is where you would |
+specify a scanner to |
+find things like |
+.B #include |
+lines in source files. |
+The pre-built |
+.B DirScanner |
+Scanner object may be used to |
+indicate that this Builder |
+should scan directory trees |
+for on-disk changes to files |
+that |
+.B scons |
+does not know about from other Builder or function calls. |
+(See the section "Scanner Objects," below, |
+for information about creating your own Scanner objects.) |
+ |
+.IP target_factory |
+A factory function that the Builder will use |
+to turn any targets specified as strings into SCons Nodes. |
+By default, |
+SCons assumes that all targets are files. |
+Other useful target_factory |
+values include |
+.BR Dir , |
+for when a Builder creates a directory target, |
+and |
+.BR Entry , |
+for when a Builder can create either a file |
+or directory target. |
+ |
+Example: |
+ |
+.ES |
+MakeDirectoryBuilder = Builder(action=my_mkdir, target_factory=Dir) |
+env = Environment() |
+env.Append(BUILDERS = {'MakeDirectory':MakeDirectoryBuilder}) |
+env.MakeDirectory('new_directory', []) |
+.EE |
+ |
+.IP |
+Note that the call to the MakeDirectory Builder |
+needs to specify an empty source list |
+to make the string represent the builder's target; |
+without that, it would assume the argument is the source, |
+and would try to deduce the target name from it, |
+which in the absence of an automatically-added prefix or suffix |
+would lead to a matching target and source name |
+and a circular dependency. |
+ |
+.IP source_factory |
+A factory function that the Builder will use |
+to turn any sources specified as strings into SCons Nodes. |
+By default, |
+SCons assumes that all source are files. |
+Other useful source_factory |
+values include |
+.BR Dir , |
+for when a Builder uses a directory as a source, |
+and |
+.BR Entry , |
+for when a Builder can use files |
+or directories (or both) as sources. |
+ |
+Example: |
+ |
+.ES |
+CollectBuilder = Builder(action=my_mkdir, source_factory=Entry) |
+env = Environment() |
+env.Append(BUILDERS = {'Collect':CollectBuilder}) |
+env.Collect('archive', ['directory_name', 'file_name']) |
+.EE |
+ |
+.IP emitter |
+A function or list of functions to manipulate the target and source |
+lists before dependencies are established |
+and the target(s) are actually built. |
+.B emitter |
+can also be a string containing a construction variable to expand |
+to an emitter function or list of functions, |
+or a dictionary mapping source file suffixes |
+to emitter functions. |
+(Only the suffix of the first source file |
+is used to select the actual emitter function |
+from an emitter dictionary.) |
+ |
+An emitter function |
+takes three arguments: |
+.I source |
+- a list of source nodes, |
+.I target |
+- a list of target nodes, |
+.I env |
+- the construction environment. |
+An emitter must return a tuple containing two lists, |
+the list of targets to be built by this builder, |
+and the list of sources for this builder. |
+ |
+Example: |
+ |
+.ES |
+def e(target, source, env): |
+ return (target + ['foo.foo'], source + ['foo.src']) |
+ |
+# Simple association of an emitter function with a Builder. |
+b = Builder("my_build < $TARGET > $SOURCE", |
+ emitter = e) |
+ |
+def e2(target, source, env): |
+ return (target + ['bar.foo'], source + ['bar.src']) |
+ |
+# Simple association of a list of emitter functions with a Builder. |
+b = Builder("my_build < $TARGET > $SOURCE", |
+ emitter = [e, e2]) |
+ |
+# Calling an emitter function through a construction variable. |
+env = Environment(MY_EMITTER = e) |
+b = Builder("my_build < $TARGET > $SOURCE", |
+ emitter = '$MY_EMITTER') |
+ |
+# Calling a list of emitter functions through a construction variable. |
+env = Environment(EMITTER_LIST = [e, e2]) |
+b = Builder("my_build < $TARGET > $SOURCE", |
+ emitter = '$EMITTER_LIST') |
+ |
+# Associating multiple emitters with different file |
+# suffixes using a dictionary. |
+def e_suf1(target, source, env): |
+ return (target + ['another_target_file'], source) |
+def e_suf2(target, source, env): |
+ return (target, source + ['another_source_file']) |
+b = Builder("my_build < $TARGET > $SOURCE", |
+ emitter = {'.suf1' : e_suf1, |
+ '.suf2' : e_suf2}) |
+.EE |
+ |
+.IP multi |
+Specifies whether this builder is allowed to be called multiple times for |
+the same target file(s). The default is 0, which means the builder |
+can not be called multiple times for the same target file(s). Calling a |
+builder multiple times for the same target simply adds additional source |
+files to the target; it is not allowed to change the environment associated |
+with the target, specify addition environment overrides, or associate a different |
+builder with the target. |
+ |
+.IP env |
+A construction environment that can be used |
+to fetch source code using this Builder. |
+(Note that this environment is |
+.I not |
+used for normal builds of normal target files, |
+which use the environment that was |
+used to call the Builder for the target file.) |
+ |
+.IP generator |
+A function that returns a list of actions that will be executed to build |
+the target(s) from the source(s). |
+The returned action(s) may be |
+an Action object, or anything that |
+can be converted into an Action object |
+(see the next section). |
+ |
+The generator function |
+takes four arguments: |
+.I source |
+- a list of source nodes, |
+.I target |
+- a list of target nodes, |
+.I env |
+- the construction environment, |
+.I for_signature |
+- a Boolean value that specifies |
+whether the generator is being called |
+for generating a build signature |
+(as opposed to actually executing the command). |
+Example: |
+ |
+.ES |
+def g(source, target, env, for_signature): |
+ return [["gcc", "-c", "-o"] + target + source] |
+ |
+b = Builder(generator=g) |
+.EE |
+ |
+.IP |
+The |
+.I generator |
+and |
+.I action |
+arguments must not both be used for the same Builder. |
+ |
+.IP src_builder |
+Specifies a builder to use when a source file name suffix does not match |
+any of the suffixes of the builder. Using this argument produces a |
+multi-stage builder. |
+ |
+.IP single_source |
+Specifies that this builder expects exactly one source file per call. Giving |
+more than one source 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 strings (file names) |
+representing the implicit |
+dependencies found in the contents; |
+or: |
+2) a dictionary that maps keys |
+(typically the file suffix, but see below for more discussion) |
+to other Scanners that should be called. |
+ |
+If the argument is actually a Python function, |
+the function must take three or four arguments: |
+ |
+ def scanner_function(node, env, path): |
+ |
+ def scanner_function(node, env, path, arg=None): |
+ |
+The |
+.B node |
+argument is the internal |
+SCons node representing the file. |
+Use |
+.B str(node) |
+to fetch the name of the file, and |
+.B node.get_contents() |
+to fetch contents of the file. |
+Note that the file is |
+.I not |
+guaranteed to exist before the scanner is called, |
+so the scanner function should check that |
+if there's any chance that the scanned file |
+might not exist |
+(for example, if it's built from other files). |
+ |
+The |
+.B env |
+argument is the construction environment for the scan. |
+Fetch values from it using the |
+.B env.Dictionary() |
+method. |
+ |
+The |
+.B path |
+argument is a tuple (or list) |
+of directories that can be searched |
+for files. |
+This will usually be the tuple returned by the |
+.B path_function |
+argument (see below). |
+ |
+The |
+.B arg |
+argument is the argument supplied |
+when the scanner was created, if any. |
+ |
+.IP name |
+The name of the Scanner. |
+This is mainly used |
+to identify the Scanner internally. |
+ |
+.IP argument |
+An optional argument that, if specified, |
+will be passed to the scanner function |
+(described above) |
+and the path function |
+(specified below). |
+ |
+.IP skeys |
+An optional list that can be used to |
+determine which scanner should be used for |
+a given Node. |
+In the usual case of scanning for file names, |
+this argument will be a list of suffixes |
+for the different file types that this |
+Scanner knows how to scan. |
+If the argument is a string, |
+then it will be expanded |
+into a list by the current environment. |
+ |
+.IP path_function |
+A Python function that takes four or five arguments: |
+a construction environment, |
+a Node for the directory containing |
+the SConscript file in which |
+the first target was defined, |
+a list of target nodes, |
+a list of source nodes, |
+and an optional argument supplied |
+when the scanner was created. |
+The |
+.B path_function |
+returns a tuple of directories |
+that can be searched for files to be returned |
+by this Scanner object. |
+(Note that the |
+.BR FindPathDirs () |
+function can be used to return a ready-made |
+.B path_function |
+for a given construction variable name, |
+instead of having to write your own function from scratch.) |
+ |
+.IP node_class |
+The class of Node that should be returned |
+by this Scanner object. |
+Any strings or other objects returned |
+by the scanner function |
+that are not of this class |
+will be run through the |
+.B node_factory |
+function. |
+ |
+.IP node_factory |
+A Python function that will take a string |
+or other object |
+and turn it into the appropriate class of Node |
+to be returned by this Scanner object. |
+ |
+.IP scan_check |
+An optional Python function that takes two arguments, |
+a Node (file) and a construction environment, |
+and returns whether the |
+Node should, in fact, |
+be scanned for dependencies. |
+This check can be used to eliminate unnecessary |
+calls to the scanner function when, |
+for example, the underlying file |
+represented by a Node does not yet exist. |
+ |
+.IP recursive |
+An optional flag that |
+specifies whether this scanner should be re-invoked |
+on the dependency files returned by the scanner. |
+When this flag is not set, |
+the Node subsystem will |
+only invoke the scanner on the file being scanned, |
+and not (for example) also on the files |
+specified by the #include lines |
+in the file being scanned. |
+.I recursive |
+may be a callable function, |
+in which case it will be called with a list of |
+Nodes found and |
+should return a list of Nodes |
+that should be scanned recursively; |
+this can be used to select a specific subset of |
+Nodes for additional scanning. |
+ |
+.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('.xyx', XYZScanner) |
+ |
+env.Program('my_prog', ['file1.c', 'file2.f', 'file3.xyz']) |
+.EE |
+ |
+.SH SYSTEM-SPECIFIC BEHAVIOR |
+SCons and its configuration files are very portable, |
+due largely to its implementation in Python. |
+There are, however, a few portability |
+issues waiting to trap the unwary. |
+.SS .C file suffix |
+SCons handles the upper-case |
+.B .C |
+file suffix differently, |
+depending on the capabilities of |
+the underlying system. |
+On a case-sensitive system |
+such as Linux or UNIX, |
+SCons treats a file with a |
+.B .C |
+suffix as a C++ source file. |
+On a case-insensitive system |
+such as Windows, |
+SCons treats a file with a |
+.B .C |
+suffix as a C source file. |
+.SS .F file suffix |
+SCons handles the upper-case |
+.B .F |
+file suffix differently, |
+depending on the capabilities of |
+the underlying system. |
+On a case-sensitive system |
+such as Linux or UNIX, |
+SCons treats a file with a |
+.B .F |
+suffix as a Fortran source file |
+that is to be first run through |
+the standard C preprocessor. |
+On a case-insensitive system |
+such as Windows, |
+SCons treats a file with a |
+.B .F |
+suffix as a Fortran source file that should |
+.I not |
+be run through the C preprocessor. |
+.SS Windows: Cygwin Tools and Cygwin Python vs. Windows Pythons |
+Cygwin supplies a set of tools and utilities |
+that let users work on a |
+Windows system using a more POSIX-like environment. |
+The Cygwin tools, including Cygwin Python, |
+do this, in part, |
+by sharing an ability to interpret UNIX-like path names. |
+For example, the Cygwin tools |
+will internally translate a Cygwin path name |
+like /cygdrive/c/mydir |
+to an equivalent Windows pathname |
+of C:/mydir (equivalent to C:\\mydir). |
+ |
+Versions of Python |
+that are built for native Windows execution, |
+such as the python.org and ActiveState versions, |
+do not have the Cygwin path name semantics. |
+This means that using a native Windows version of Python |
+to build compiled programs using Cygwin tools |
+(such as gcc, bison, and flex) |
+may yield unpredictable results. |
+"Mixing and matching" in this way |
+can be made to work, |
+but it requires careful attention to the use of path names |
+in your SConscript files. |
+ |
+In practice, users can sidestep |
+the issue by adopting the following rules: |
+When using gcc, |
+use the Cygwin-supplied Python interpreter |
+to run SCons; |
+when using Microsoft Visual C/C++ |
+(or some other Windows compiler) |
+use the python.org or ActiveState version of Python |
+to run SCons. |
+.SS Windows: scons.bat file |
+On Windows systems, |
+SCons is executed via a wrapper |
+.B scons.bat |
+file. |
+This has (at least) two ramifications: |
+ |
+First, Windows command-line users |
+that want to use variable assignment |
+on the command line |
+may have to put double quotes |
+around the assignments: |
+ |
+.ES |
+scons "FOO=BAR" "BAZ=BLEH" |
+.EE |
+ |
+Second, the Cygwin shell does not |
+recognize this file as being the same |
+as an |
+.B scons |
+command issued at the command-line prompt. |
+You can work around this either by |
+executing |
+.B scons.bat |
+from the Cygwin command line, |
+or by creating a wrapper shell |
+script named |
+.B scons . |
+ |
+.SS MinGW |
+ |
+The MinGW bin directory must be in your PATH environment variable or the |
+PATH variable under the ENV construction variable for SCons |
+to detect and use the MinGW tools. When running under the native Windows |
+Python interpreter, SCons will prefer the MinGW tools over the Cygwin |
+tools, if they are both installed, regardless of the order of the bin |
+directories in the PATH variable. If you have both MSVC and MinGW |
+installed and you want to use MinGW instead of MSVC, |
+then you must explictly tell SCons to use MinGW by passing |
+ |
+.ES |
+tools=['mingw'] |
+.EE |
+ |
+to the Environment() function, because SCons will prefer the MSVC tools |
+over the MinGW tools. |
+ |
+.SH EXAMPLES |
+ |
+To help you get started using SCons, |
+this section contains a brief overview of some common tasks. |
+ |
+.SS Basic Compilation From a Single Source File |
+ |
+.ES |
+env = Environment() |
+env.Program(target = 'foo', source = 'foo.c') |
+.EE |
+ |
+Note: Build the file by specifying |
+the target as an argument |
+("scons foo" or "scons foo.exe"). |
+or by specifying a dot ("scons ."). |
+ |
+.SS Basic Compilation From Multiple Source Files |
+ |
+.ES |
+env = Environment() |
+env.Program(target = 'foo', source = Split('f1.c f2.c f3.c')) |
+.EE |
+ |
+.SS Setting a Compilation Flag |
+ |
+.ES |
+env = Environment(CCFLAGS = '-g') |
+env.Program(target = 'foo', source = 'foo.c') |
+.EE |
+ |
+.SS Search The Local Directory For .h Files |
+ |
+Note: You do |
+.I not |
+need to set CCFLAGS to specify -I options by hand. |
+SCons will construct the right -I options from CPPPATH. |
+ |
+.ES |
+env = Environment(CPPPATH = ['.']) |
+env.Program(target = 'foo', source = 'foo.c') |
+.EE |
+ |
+.SS Search Multiple Directories For .h Files |
+ |
+.ES |
+env = Environment(CPPPATH = ['include1', 'include2']) |
+env.Program(target = 'foo', source = 'foo.c') |
+.EE |
+ |
+.SS Building a Static Library |
+ |
+.ES |
+env = Environment() |
+env.StaticLibrary(target = 'foo', source = Split('l1.c l2.c')) |
+env.StaticLibrary(target = 'bar', source = ['l3.c', 'l4.c']) |
+.EE |
+ |
+.SS Building a Shared Library |
+ |
+.ES |
+env = Environment() |
+env.SharedLibrary(target = 'foo', source = ['l5.c', 'l6.c']) |
+env.SharedLibrary(target = 'bar', source = Split('l7.c l8.c')) |
+.EE |
+ |
+.SS Linking a Local Library Into a Program |
+ |
+.ES |
+env = Environment(LIBS = 'mylib', LIBPATH = ['.']) |
+env.Library(target = 'mylib', source = Split('l1.c l2.c')) |
+env.Program(target = 'prog', source = ['p1.c', 'p2.c']) |
+.EE |
+ |
+.SS Defining Your Own Builder Object |
+ |
+Notice that when you invoke the Builder, |
+you can leave off the target file suffix, |
+and SCons will add it automatically. |
+ |
+.ES |
+bld = Builder(action = 'pdftex < $SOURCES > $TARGET' |
+ suffix = '.pdf', |
+ src_suffix = '.tex') |
+env = Environment(BUILDERS = {'PDFBuilder' : bld}) |
+env.PDFBuilder(target = 'foo.pdf', source = 'foo.tex') |
+ |
+# The following creates "bar.pdf" from "bar.tex" |
+env.PDFBuilder(target = 'bar', source = 'bar') |
+.EE |
+ |
+Note also that the above initialization |
+overwrites the default Builder objects, |
+so the Environment created above |
+can not be used call Builders like env.Program(), |
+env.Object(), env.StaticLibrary(), etc. |
+ |
+.SS Adding Your Own Builder Object to an Environment |
+ |
+.ES |
+bld = Builder(action = 'pdftex < $SOURCES > $TARGET' |
+ suffix = '.pdf', |
+ src_suffix = '.tex') |
+env = Environment() |
+env.Append(BUILDERS = {'PDFBuilder' : bld}) |
+env.PDFBuilder(target = 'foo.pdf', source = 'foo.tex') |
+env.Program(target = 'bar', source = 'bar.c') |
+.EE |
+ |
+You also can use other Pythonic techniques to add |
+to the BUILDERS construction variable, such as: |
+ |
+.ES |
+env = Environment() |
+env['BUILDERS]['PDFBuilder'] = bld |
+.EE |
+ |
+.SS Defining Your Own Scanner Object |
+ |
+The following example shows an extremely simple scanner (the |
+.BR kfile_scan () |
+function) |
+that doesn't use a search path at all |
+and simply returns the |
+file names present on any |
+.B include |
+lines in the scanned file. |
+This would implicitly assume that all included |
+files live in the top-level directory: |
+ |
+.ES |
+import re |
+ |
+'\" Note: the \\ in the following are for the benefit of nroff/troff, |
+'\" not inappropriate doubled escape characters within the r'' raw string. |
+include_re = re.compile(r'^include\\s+(\\S+)$', re.M) |
+ |
+def kfile_scan(node, env, path, arg): |
+ contents = node.get_text_contents() |
+ includes = include_re.findall(contents) |
+ return includes |
+ |
+kscan = Scanner(name = 'kfile', |
+ function = kfile_scan, |
+ argument = None, |
+ skeys = ['.k']) |
+scanners = Environment().Dictionary('SCANNERS') |
+env = Environment(SCANNERS = scanners + [kscan]) |
+ |
+env.Command('foo', 'foo.k', 'kprocess < $SOURCES > $TARGET') |
+ |
+bar_in = File('bar.in') |
+env.Command('bar', bar_in, 'kprocess $SOURCES > $TARGET') |
+bar_in.target_scanner = kscan |
+.EE |
+ |
+Here is a similar but more complete example that searches |
+a path of directories |
+(specified as the |
+.B MYPATH |
+construction variable) |
+for files that actually exist: |
+ |
+.ES |
+include_re = re.compile(r'^include\\s+(\\S+)$', re.M) |
+ |
+def my_scan(node, env, path, arg): |
+ contents = node.get_text_contents() |
+ includes = include_re.findall(contents) |
+ if includes == []: |
+ return [] |
+ results = [] |
+ for inc in includes: |
+ for dir in path: |
+ file = dir + os.sep + inc |
+ if os.path.exists(file): |
+ results.append(file) |
+ break |
+ return results |
+ |
+scanner = Scanner(name = 'myscanner', |
+ function = my_scan, |
+ argument = None, |
+ skeys = ['.x'], |
+ path_function = FindPathDirs('MYPATH'), |
+ ) |
+scanners = Environment().Dictionary('SCANNERS') |
+env = Environment(SCANNERS = scanners + [scanner]) |
+.EE |
+ |
+The |
+.BR FindPathDirs () |
+function used in the previous example returns a function |
+(actually a callable Python object) |
+that will return a list of directories |
+specified in the |
+.B $MYPATH |
+construction variable. |
+If you need to customize how the search path is derived, |
+you would provide your own |
+.B path_function |
+argument when creating the Scanner object, |
+as follows: |
+ |
+.ES |
+# MYPATH is a list of directories to search for files in |
+def pf(env, dir, target, source, arg): |
+ top_dir = Dir('#').abspath |
+ results = [] |
+ if '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> |
+ |