diff options
Diffstat (limited to 'doc/man/scons.xml')
| -rw-r--r-- | doc/man/scons.xml | 7101 |
1 files changed, 7101 insertions, 0 deletions
diff --git a/doc/man/scons.xml b/doc/man/scons.xml new file mode 100644 index 0000000..d9bd74d --- /dev/null +++ b/doc/man/scons.xml @@ -0,0 +1,7101 @@ +<?xml version="1.0" encoding="UTF-8"?> + +<!DOCTYPE reference [ +<!ENTITY % version SYSTEM "../version.xml"> +%version; +<!ENTITY % scons SYSTEM '../scons.mod'> +%scons; +<!ENTITY % builders-mod SYSTEM '../generated/builders.mod'> +%builders-mod; +<!ENTITY % functions-mod SYSTEM '../generated/functions.mod'> +%functions-mod; +<!ENTITY % tools-mod SYSTEM '../generated/tools.mod'> +%tools-mod; +<!ENTITY % variables-mod SYSTEM '../generated/variables.mod'> +%variables-mod; +]> +<!-- lifted from troff+man by doclifter --> +<reference xmlns="http://www.scons.org/dbxsd/v1.0" + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + xsi:schemaLocation="http://www.scons.org/dbxsd/v1.0/scons.xsd scons.xsd"> +<!-- Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014 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.xml 2014/03/02 14:18:15 garyo --> + + <referenceinfo> + <title>SCons &buildversion;</title> + <subtitle>MAN page</subtitle> + + <author> + <firstname>Steven</firstname> + <surname>Knight</surname> + </author> + + <corpauthor>Steven Knight</corpauthor> + + <pubdate>2004, 2005, 2006, 2007, 2008, 2009, 2010</pubdate> + + <copyright> + <year>2004, 2005, 2006, 2007, 2008, 2009, 2010</year> + <holder>Steven Knight</holder> + </copyright> + + <releaseinfo>version &buildversion;</releaseinfo> + + <mediaobject role="cover"><imageobject><imagedata fileref="cover.jpg" format="JPG"/></imageobject></mediaobject> + + </referenceinfo> + + <title>SCons &buildversion;</title> + <subtitle>MAN page</subtitle> + + +<refentry id='scons1'> +<refmeta> +<refentrytitle>SCONS</refentrytitle> +<manvolnum>1</manvolnum> +<refmiscinfo class='source'>March 2014</refmiscinfo> +</refmeta> +<refnamediv id='name'> +<refname>scons</refname> +<refpurpose>a software construction tool</refpurpose> +</refnamediv> +<!-- body begins here --> +<refsynopsisdiv id='synopsis'> +<cmdsynopsis> + <command>scons</command> + <arg choice='opt' rep='repeat'><replaceable>options</replaceable></arg> + <arg choice='opt' rep='repeat'><replaceable>name=val</replaceable></arg> + <arg choice='opt' rep='repeat'><replaceable>targets</replaceable></arg> +</cmdsynopsis> +</refsynopsisdiv> + + +<refsect1 id='description'><title>DESCRIPTION</title> +<para>The +<command>scons</command> +utility builds software (or other files) by determining which +component pieces must be rebuilt and executing the necessary commands to +rebuild them.</para> + +<para>By default, +<command>scons</command> +searches for a file named +<emphasis>SConstruct</emphasis>, +<emphasis>Sconstruct</emphasis>, +or +<emphasis>sconstruct</emphasis> +(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 +<option>-f</option> +option.</para> + +<para>The +<emphasis>SConstruct</emphasis> +file can specify subsidiary +configuration files using the +<emphasis role="bold">SConscript</emphasis>() +function. +By convention, +these subsidiary files are named +<emphasis>SConscript</emphasis>, +although any name may be used. +(Because of this naming convention, +the term "SConscript files" +is sometimes used to refer +generically to all +<command>scons</command> +configuration files, +regardless of actual file name.)</para> + +<para>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.</para> + +<para>Before reading the +<emphasis>SConstruct</emphasis> +file, +<command>scons</command> +looks for a directory named +<emphasis>site_scons</emphasis> +in various system directories (see below) and the directory containing the +<emphasis>SConstruct</emphasis> +file; for each of those dirs which exists, +<emphasis>site_scons</emphasis> +is prepended to sys.path, +the file +<emphasis>site_scons/site_init.py</emphasis>, +is evaluated if it exists, +and the directory +<emphasis>site_scons/site_tools</emphasis> +is prepended to the default toolpath if it exists. +See the +<option>--no-site-dir</option> +and +<option>--site-dir</option> +options for more details.</para> + +<para><command>scons</command> +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. +<command>scons</command>, +however, reads and executes all of the SConscript files +<emphasis>before</emphasis> +it begins building any targets. +To make this obvious, +<command>scons</command> +prints the following messages about what it is doing:</para> + +<literallayout class="monospaced"> +$ scons foo.out +scons: Reading SConscript files ... +scons: done reading SConscript files. +scons: Building targets ... +cp foo.in foo.out +scons: done building targets. +$ +</literallayout> + +<para>The status messages +(everything except the line that reads "cp foo.in foo.out") +may be suppressed using the +<option>-Q</option> +option.</para> + +<para><command>scons</command> +does not automatically propagate +the external environment used to execute +<command>scons</command> +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 +<command>scons</command> +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, +<command>scons</command> +will not find them unless +you explicitly set the PATH +to include those locations. +Whenever you create an +<command>scons</command> +construction environment, +you can propagate the value of PATH +from your external environment as follows:</para> + +<literallayout class="monospaced"> +import os +env = Environment(ENV = {'PATH' : os.environ['PATH']}) +</literallayout> + +<para>Similarly, if the commands use external environment variables +like $PATH, $HOME, $JAVA_HOME, $LANG, $SHELL, $TERM, etc., +these variables can also be explicitly propagated:</para> + +<literallayout class="monospaced"> +import os +env = Environment(ENV = {'PATH' : os.environ['PATH'], + 'HOME' : os.environ['HOME']}) +</literallayout> + +<para>Or you may explicitly propagate the invoking user's +complete external environment:</para> + +<literallayout class="monospaced"> +import os +env = Environment(ENV = os.environ) +</literallayout> + +<para>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.</para> + +<para><command>scons</command> +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. +<command>scons</command> +supports the +ability to define new scanners for unknown input file types.</para> + +<para><command>scons</command> +knows how to fetch files automatically from +SCCS or RCS subdirectories +using SCCS, RCS or BitKeeper.</para> + +<para><command>scons</command> +is normally executed in a top-level directory containing a +<emphasis>SConstruct</emphasis> +file, optionally specifying +as command-line arguments +the target file or files to be built.</para> + +<para>By default, the command</para> + +<literallayout class="monospaced"> +scons +</literallayout> + +<para>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 +<emphasis role="bold">Default()</emphasis> +function, described below.</para> + +<para>Even when +<emphasis role="bold">Default()</emphasis> +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:</para> + +<literallayout class="monospaced"> +scons . +</literallayout> + +<para>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):</para> + +<literallayout class="monospaced"> +scons / +</literallayout> + +<para>or the path name(s) of the volume(s) in which all the targets +should be built (on Windows systems):</para> + +<literallayout class="monospaced"> +scons C:\ D:\ +</literallayout> + +<para>To build only specific targets, +supply them as command-line arguments:</para> + +<literallayout class="monospaced"> +scons foo bar +</literallayout> + +<para>in which case only the specified targets will be built +(along with any derived files on which they depend).</para> + +<para>Specifying "cleanup" targets in SConscript files is not usually necessary. +The +<option>-c</option> +flag removes all files +necessary to build the specified target:</para> + +<literallayout class="monospaced"> +scons -c . +</literallayout> + +<para>to remove all target files, or:</para> + +<literallayout class="monospaced"> +scons -c build export +</literallayout> + +<para>to remove target files under build and export. +Additional files or directories to remove can be specified using the +<emphasis role="bold">Clean()</emphasis> +function. +Conversely, targets that would normally be removed by the +<option>-c</option> +invocation +can be prevented from being removed by using the +<emphasis role="bold">NoClean</emphasis>() +function.</para> + +<para>A subset of a hierarchical tree may be built by +remaining at the top-level directory (where the +<emphasis>SConstruct</emphasis> +file lives) and specifying the subdirectory as the target to be +built:</para> + +<literallayout class="monospaced"> +scons src/subdir +</literallayout> + +<para>or by changing directory and invoking scons with the +<option>-u</option> +option, which traverses up the directory +hierarchy until it finds the +<emphasis>SConstruct</emphasis> +file, and then builds +targets relatively to the current subdirectory:</para> + +<literallayout class="monospaced"> +cd src/subdir +scons -u . +</literallayout> + +<para><command>scons</command> +supports building multiple targets in parallel via a +<option>-j</option> +option that takes, as its argument, the number +of simultaneous tasks that may be spawned:</para> + +<literallayout class="monospaced"> +scons -j 4 +</literallayout> + +<para>builds four targets in parallel, for example.</para> + +<para><command>scons</command> +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 +<command>scons</command> +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 +<option>--cache-force</option>, +<option>--cache-disable</option>, +<option>--cache-readonly</option>, +and +<option>--cache-show</option> +command-line options. The +<option>--random</option> +option is useful to prevent multiple builds +from trying to update the cache simultaneously.</para> + +<para>Values of variables to be passed to the SConscript file(s) +may be specified on the command line:</para> + +<literallayout class="monospaced"> +scons debug=1 . +</literallayout> + +<para>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:</para> + +<literallayout class="monospaced"> +if ARGUMENTS.get('debug', 0): + env = Environment(CCFLAGS = '-g') +else: + env = Environment() +</literallayout> + +<para>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.</para> + +<para><command>scons</command> +requires Python version 2.4 or later. +There should be no other dependencies or requirements to run +<emphasis role="bold">scons.</emphasis></para> + +<!-- 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. --> +<para>By default, +<command>scons</command> +knows how to search for available programming tools +on various systems. +On Windows systems, +<command>scons</command> +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, +<command>scons</command> +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, +<command>scons</command> +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, +<command>scons</command> +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.</para> + +</refsect1> + +<refsect1 id='options'><title>OPTIONS</title> +<para>In general, +<command>scons</command> +supports the same command-line options as GNU +<emphasis role="bold">make</emphasis>, +and many of those supported by +<emphasis role="bold">cons</emphasis>.</para> + +<variablelist> + <varlistentry> + <term>-b</term> + <listitem> +<para>Ignored for compatibility with non-GNU versions of +<emphasis role="bold">make.</emphasis></para> + + </listitem> + </varlistentry> + <varlistentry> + <term>-c, --clean, --remove</term> + <listitem> +<para>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 +<emphasis role="bold">Clean</emphasis>() +function. +Will not remove any targets specified by the +<emphasis role="bold">NoClean</emphasis>() +function.</para> + + </listitem> + </varlistentry> + <varlistentry> + <term>--cache-debug=<emphasis>file</emphasis></term> + <listitem> +<para>Print debug information about the +<emphasis role="bold">CacheDir</emphasis>() +derived-file caching +to the specified +<emphasis>file</emphasis>. +If +<emphasis>file</emphasis> +is +<emphasis role="bold">-</emphasis> +(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 +<emphasis role="bold">CacheDir</emphasis>() +directory tree.</para> + + </listitem> + </varlistentry> + <varlistentry> + <term>--cache-disable, --no-cache</term> + <listitem> +<para>Disable the derived-file caching specified by +<emphasis role="bold">CacheDir</emphasis>(). +<command>scons</command> +will neither retrieve files from the cache +nor copy files to the cache.</para> + + </listitem> + </varlistentry> + <varlistentry> + <term>--cache-force, --cache-populate</term> + <listitem> +<para>When using +<emphasis role="bold">CacheDir</emphasis>(), +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 +<option>--cache-disable</option> +option.</para> + + </listitem> + </varlistentry> +<varlistentry> + <term>--cache-readonly</term> + <listitem> +<para>Use the cache (if enabled) for reading, but do not not update the +cache with changed files. +</para> + + </listitem> + </varlistentry> + <varlistentry> + <term>--cache-show</term> + <listitem> +<para>When using +<emphasis role="bold">CacheDir</emphasis>() +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.</para> + + </listitem> + </varlistentry> + <varlistentry> + <term>--config=<emphasis>mode</emphasis></term> + <listitem> +<para>This specifies how the +<emphasis role="bold">Configure</emphasis> +call should use or generate the +results of configuration tests. +The option should be specified from +among the following choices:</para> + + </listitem> + </varlistentry> + <varlistentry> + <term>--config=auto</term> + <listitem> +<para>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.</para> + + </listitem> + </varlistentry> + <varlistentry> + <term>--config=force</term> + <listitem> +<para>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.</para> + + </listitem> + </varlistentry> + <varlistentry> + <term>--config=cache</term> + <listitem> +<para>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.</para> + + </listitem> + </varlistentry> + <varlistentry> + <term>-C<emphasis> directory</emphasis>, --directory=<emphasis>directory</emphasis></term> + <listitem> +<para>Change to the specified +<emphasis>directory</emphasis> +before searching for the +<emphasis>SConstruct</emphasis>, +<emphasis>Sconstruct</emphasis>, +or +<emphasis>sconstruct</emphasis> +file, or doing anything +else. Multiple +<option>-C</option> +options are interpreted +relative to the previous one, and the right-most +<option>-C</option> +option wins. (This option is nearly +equivalent to +<option>-f directory/SConstruct</option>, +except that it will search for +<emphasis>SConstruct</emphasis>, +<emphasis>Sconstruct</emphasis>, +or +<emphasis>sconstruct</emphasis> +in the specified directory.)</para> + +<!-- .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. --> + + </listitem> + </varlistentry> + <varlistentry> + <term>-D</term> + <listitem> +<para>Works exactly the same way as the +<option>-u</option> +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.</para> + + </listitem> + </varlistentry> + <varlistentry> + <term>--debug=<emphasis>type</emphasis></term> + <listitem> +<para>Debug the build process. +<emphasis>type[,type...]</emphasis> +specifies what type of debugging. Multiple types may be specified, +separated by commas. The following types are valid:</para> + + </listitem> + </varlistentry> + <varlistentry> + <term>--debug=count</term> + <listitem> +<para>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 +<option>-O</option> +(optimized) option +or when the SCons modules +have been compiled with optimization +(that is, when executing from +<emphasis role="bold">*.pyo</emphasis> +files).</para> + + </listitem> + </varlistentry> + <varlistentry> + <term>--debug=duplicate</term> + <listitem> +<para>Print a line for each unlink/relink (or copy) of a variant file from +its source file. Includes debugging info for unlinking stale variant +files, as well as unlinking old targets before building them.</para> + + </listitem> + </varlistentry> + <varlistentry> + <term>--debug=dtree</term> + <listitem> +<para>A synonym for the newer +<option>--tree=derived</option> +option. +This will be deprecated in some future release +and ultimately removed.</para> + + </listitem> + </varlistentry> + <varlistentry> + <term>--debug=explain</term> + <listitem> +<para>Print an explanation of precisely why +<command>scons</command> +is deciding to (re-)build any targets. +(Note: this does not print anything +for targets that are +<emphasis>not</emphasis> +rebuilt.)</para> + + </listitem> + </varlistentry> + <varlistentry> + <term>--debug=findlibs</term> + <listitem> +<para>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.</para> + + </listitem> + </varlistentry> + <varlistentry> + <term>--debug=includes</term> + <listitem> +<para>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:</para> + +<literallayout class="monospaced"> +$ scons --debug=includes foo.o +</literallayout> + + </listitem> + </varlistentry> + <varlistentry> + <term>--debug=memoizer</term> + <listitem> +<para>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.</para> + + </listitem> + </varlistentry> + <varlistentry> + <term>--debug=memory</term> + <listitem> +<para>Prints how much memory SCons uses +before and after reading the SConscript files +and before and after building targets.</para> + + </listitem> + </varlistentry> + <varlistentry> + <term>--debug=nomemoizer</term> + <listitem> +<para>A deprecated option preserved for backwards compatibility.</para> + + </listitem> + </varlistentry> + <varlistentry> + <term>--debug=objects</term> + <listitem> +<para>Prints a list of the various objects +of the various classes used internally by SCons.</para> + + </listitem> + </varlistentry> + <varlistentry> + <term>--debug=pdb</term> + <listitem> +<para>Re-run SCons under the control of the +pdb +Python debugger.</para> + + </listitem> + </varlistentry> + <varlistentry> + <term>--debug=prepare</term> + <listitem> +<para>Print a line each time any target (internal or external) +is prepared for building. +<command>scons</command> +prints this for each target it considers, even if that +target is up to date (see also --debug=explain). +This can help debug problems with targets that aren't being +built; it shows whether +<command>scons</command> +is at least considering them or not.</para> + + </listitem> + </varlistentry> + <varlistentry> + <term>--debug=presub</term> + <listitem> +<para>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:</para> +<literallayout class="monospaced"> +$ scons --debug=presub +Building myprog.o with action(s): + $SHCC $SHCFLAGS $SHCCFLAGS $CPPFLAGS $_CPPINCFLAGS -c -o $TARGET $SOURCES +... +</literallayout> + + </listitem> + </varlistentry> + <varlistentry> + <term>--debug=stacktrace</term> + <listitem> +<para>Prints an internal Python stack trace +when encountering an otherwise unexplained error.</para> + + </listitem> + </varlistentry> + <varlistentry> + <term>--debug=stree</term> + <listitem> +<para>A synonym for the newer +<option>--tree=all,status</option> +option. +This will be deprecated in some future release +and ultimately removed.</para> + + </listitem> + </varlistentry> + <varlistentry> + <term>--debug=time</term> + <listitem> +<para>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 +<command>scons</command> +is executed without the +<option>-j</option> +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 +<command>scons</command> +is executed +<emphasis>with</emphasis> +the +<option>-j</option> +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.)</para> + + </listitem> + </varlistentry> + <varlistentry> + <term>--debug=tree</term> + <listitem> +<para>A synonym for the newer +<option>--tree=all</option> +option. +This will be deprecated in some future release +and ultimately removed.</para> + + </listitem> + </varlistentry> + <varlistentry> + <term>--diskcheck=<emphasis>types</emphasis></term> + <listitem> +<para>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 +<emphasis>types</emphasis> +argument can be set to: +<emphasis role="bold">all</emphasis>, +to enable all checks explicitly +(the default behavior); +<emphasis role="bold">none</emphasis>, +to disable all such checks; +<emphasis role="bold">match</emphasis>, +to check that files and directories on disk +match SCons' expected configuration; +<emphasis role="bold">rcs</emphasis>, +to check for the existence of an RCS source +for any missing source or include files; +<emphasis role="bold">sccs</emphasis>, +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, +<option>--diskcheck=sccs,rcs</option> +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).</para> + + </listitem> + </varlistentry> + <varlistentry> + <term>--duplicate=<emphasis>ORDER</emphasis></term> + <listitem> +<para>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. +<emphasis>ORDER</emphasis> +must be one of +<emphasis>hard-soft-copy</emphasis> +(the default), +<emphasis>soft-hard-copy</emphasis>, +<emphasis>hard-copy</emphasis>, +<emphasis>soft-copy</emphasis> +or +<emphasis>copy</emphasis>. +SCons will attempt to duplicate files using +the mechanisms in the specified order.</para> + +<!-- .TP --> +<!-- \-e, \-\-environment\-overrides --> +<!-- Variables from the execution environment override construction --> +<!-- variables from the SConscript files. --> + + </listitem> + </varlistentry> + <varlistentry> + <term>-f<emphasis> file</emphasis>, --file=<emphasis>file</emphasis>, --makefile=<emphasis>file</emphasis>, --sconstruct=<emphasis>file</emphasis></term> + <listitem> +<para>Use +<emphasis>file</emphasis> +as the initial SConscript file. +Multiple +<option>-f</option> +options may be specified, +in which case +<command>scons</command> +will read all of the specified files.</para> + + </listitem> + </varlistentry> + <varlistentry> + <term>-h, --help</term> + <listitem> +<para>Print a local help message for this build, if one is defined in +the SConscript file(s), plus a line that describes the +<option>-H</option> +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.</para> + + </listitem> + </varlistentry> + <varlistentry> + <term>-H, --help-options</term> + <listitem> +<para>Print the standard help message about command-line options and +exit.</para> + + </listitem> + </varlistentry> + <varlistentry> + <term>-i, --ignore-errors</term> + <listitem> +<para>Ignore all errors from commands executed to rebuild files.</para> + + </listitem> + </varlistentry> + <varlistentry> + <term>-I<emphasis> directory</emphasis>, --include-dir=<emphasis>directory</emphasis></term> + <listitem> +<para>Specifies a +<emphasis>directory</emphasis> +to search for +imported Python modules. If several +<option>-I</option> +options +are used, the directories are searched in the order specified.</para> + + </listitem> + </varlistentry> + <varlistentry> + <term>--implicit-cache</term> + <listitem> +<para>Cache implicit dependencies. +This causes +<command>scons</command> +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:</para> + </listitem> + </varlistentry> +</variablelist> + +<para><command>scons</command> +will not detect changes to implicit dependency search paths +(e.g. +<emphasis role="bold">CPPPATH</emphasis>, <emphasis role="bold">LIBPATH</emphasis>) +that would ordinarily +cause different versions of same-named files to be used.</para> + +<para><command>scons</command> +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. +<emphasis role="bold">CPPPATH</emphasis>, <emphasis role="bold">LIBPATH</emphasis>) +than a current implicit dependency with the same name.</para> + +<variablelist> + <varlistentry> + <term>--implicit-deps-changed</term> + <listitem> +<para>Forces SCons to ignore the cached implicit dependencies. This causes the +implicit dependencies to be rescanned and recached. This implies +<option>--implicit-cache</option>.</para> + + </listitem> + </varlistentry> + <varlistentry> + <term>--implicit-deps-unchanged</term> + <listitem> +<para>Force SCons to ignore changes in the implicit dependencies. +This causes cached implicit dependencies to always be used. +This implies +<option>--implicit-cache</option>.</para> + + </listitem> + </varlistentry> + <varlistentry> + <term>--interactive</term> + <listitem> +<para>Starts SCons in interactive mode. +The SConscript files are read once and a +<emphasis role="bold">scons>>></emphasis> +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.</para> + +<para>SCons interactive mode supports the following commands:</para> + + <blockquote> + <variablelist> + <varlistentry> + <term><emphasis role="bold">build</emphasis><emphasis>[OPTIONS] [TARGETS] ...</emphasis></term> + <listitem> +<para>Builds the specified +<emphasis>TARGETS</emphasis> +(and their dependencies) +with the specified +SCons command-line +<emphasis>OPTIONS</emphasis>. +<emphasis role="bold">b</emphasis> +and +<command>scons</command> +are synonyms.</para> + +<para>The following SCons command-line options affect the +<emphasis role="bold">build</emphasis> +command:</para> + +<literallayout class="monospaced"> +--cache-debug=FILE +--cache-disable, --no-cache +--cache-force, --cache-populate +--cache-readonly +--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 +</literallayout> + + </listitem> + </varlistentry> + </variablelist> + +<para>Any other SCons command-line options that are specified +do not cause errors +but have no effect on the +<emphasis role="bold">build</emphasis> +command +(mainly because they affect how the SConscript files are read, +which only happens once at the beginning of interactive mode).</para> + + <variablelist> + <varlistentry> + <term><emphasis role="bold">clean</emphasis><emphasis>[OPTIONS] [TARGETS] ...</emphasis></term> + <listitem> +<para>Cleans the specified +<emphasis>TARGETS</emphasis> +(and their dependencies) +with the specified options. +<emphasis role="bold">c</emphasis> +is a synonym. +This command is itself a synonym for +<userinput>build --clean</userinput></para> + + </listitem> + </varlistentry> + <varlistentry> + <term><emphasis role="bold">exit</emphasis></term> + <listitem> +<para>Exits SCons interactive mode. +You can also exit by terminating input +(CTRL+D on UNIX or Linux systems, +CTRL+Z on Windows systems).</para> + + </listitem> + </varlistentry> + <varlistentry> + <term><emphasis role="bold">help</emphasis><emphasis>[COMMAND]</emphasis></term> + <listitem> +<para>Provides a help message about +the commands available in SCons interactive mode. +If +<emphasis>COMMAND</emphasis> +is specified, +<emphasis role="bold">h</emphasis> +and +<emphasis role="bold">?</emphasis> +are synonyms.</para> + + </listitem> + </varlistentry> + <varlistentry> + <term><emphasis role="bold">shell</emphasis><emphasis>[COMMANDLINE]</emphasis></term> + <listitem> +<para>Executes the specified +<emphasis>COMMANDLINE</emphasis> +in a subshell. +If no +<emphasis>COMMANDLINE</emphasis> +is specified, +executes the interactive command interpreter +specified in the +<envar>SHELL</envar> +environment variable +(on UNIX and Linux systems) +or the +<emphasis role="bold">COMSPEC</emphasis> +environment variable +(on Windows systems). +<emphasis role="bold">sh</emphasis> +and +<emphasis role="bold">!</emphasis> +are synonyms.</para> + + </listitem> + </varlistentry> + <varlistentry> + <term><emphasis role="bold">version</emphasis></term> + <listitem> +<para>Prints SCons version information.</para> + </listitem> + </varlistentry> + </variablelist> + </blockquote> + + </listitem> + </varlistentry> +</variablelist> + +<para>An empty line repeats the last typed command. +Command-line editing can be used if the +<emphasis role="bold">readline</emphasis> +module is available.</para> + +<literallayout class="monospaced"> +$ scons --interactive +scons: Reading SConscript files ... +scons: done reading SConscript files. +scons>>> build -n prog +scons>>> exit +</literallayout> + +<variablelist> + <varlistentry> + <term>-j<emphasis> N</emphasis>, --jobs=<emphasis>N</emphasis></term> + <listitem> +<para>Specifies the number of jobs (commands) to run simultaneously. +If there is more than one +<option>-j</option> +option, the last one is effective.</para> +<!-- ??? If the --> +<!-- .B \-j --> +<!-- option --> +<!-- is specified without an argument, --> +<!-- .B scons --> +<!-- will not limit the number of --> +<!-- simultaneous jobs. --> + + </listitem> + </varlistentry> + <varlistentry> + <term>-k, --keep-going</term> + <listitem> +<para>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.</para> + +<!-- .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.] --> + + </listitem> + </varlistentry> + <varlistentry> + <term>-m</term> + <listitem> +<para>Ignored for compatibility with non-GNU versions of +<emphasis role="bold">make</emphasis>.</para> + + </listitem> + </varlistentry> + <varlistentry> + <term>--max-drift=<emphasis>SECONDS</emphasis></term> + <listitem> +<para>Set the maximum expected drift in the modification time of files to +<emphasis>SECONDS</emphasis>. +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.</para> + + </listitem> + </varlistentry> + <varlistentry> + <term>--md5-chunksize=<emphasis>KILOBYTES</emphasis></term> + <listitem> +<para>Set the block size used to compute MD5 signatures to +<emphasis>KILOBYTES</emphasis>. +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.</para> + +<para>The default value is to use a chunk size of 64 kilobytes, which should +be appropriate for most uses.</para> + + </listitem> + </varlistentry> + <varlistentry> + <term>-n, --just-print, --dry-run, --recon</term> + <listitem> +<para>No execute. Print the commands that would be executed to build +any out-of-date target files, but do not execute the commands.</para> + + </listitem> + </varlistentry> + <varlistentry> + <term>--no-site-dir</term> + <listitem> +<para>Prevents the automatic addition of the standard +<emphasis>site_scons</emphasis> +dirs to +<emphasis>sys.path</emphasis>. +Also prevents loading the +<emphasis>site_scons/site_init.py</emphasis> +modules if they exist, and prevents adding their +<emphasis>site_scons/site_tools</emphasis> +dirs to the toolpath.</para> + +<!-- .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 --> + + </listitem> + </varlistentry> + <varlistentry> + <term>--profile=<emphasis>file</emphasis></term> + <listitem> +<para>Run SCons under the Python profiler +and save the results in the specified +<emphasis>file</emphasis>. +The results may be analyzed using the Python +pstats module.</para> + + </listitem> + </varlistentry> + <varlistentry> + <term>-q, --question</term> + <listitem> +<para>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.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>-Q</term> + <listitem> +<para>Quiets SCons status messages about +reading SConscript files, +building targets +and entering directories. +Commands that are executed +to rebuild target files are still printed.</para> + +<!-- .TP --> +<!-- \-r, \-R, \-\-no\-builtin\-rules, \-\-no\-builtin\-variables --> +<!-- Clear the default construction variables. Construction --> +<!-- environments that are created will be completely empty. --> + + </listitem> + </varlistentry> + <varlistentry> + <term>--random</term> + <listitem> +<para>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.</para> + + </listitem> + </varlistentry> + <varlistentry> + <term>-s, --silent, --quiet</term> + <listitem> +<para>Silent. Do not print commands that are executed to rebuild +target files. +Also suppresses SCons status messages.</para> + + </listitem> + </varlistentry> + <varlistentry> + <term>-S, --no-keep-going, --stop</term> + <listitem> +<para>Ignored for compatibility with GNU +<emphasis role="bold">make</emphasis>.</para> + + </listitem> + </varlistentry> + <varlistentry> + <term>--site-dir=<emphasis>dir</emphasis></term> + <listitem> +<para>Uses the named dir as the site dir rather than the default +<emphasis>site_scons</emphasis> +dirs. This dir will get prepended to +<emphasis>sys.path</emphasis>, +the module +<emphasis>dir</emphasis>/site_init.py +will get loaded if it exists, and +<emphasis>dir</emphasis>/site_tools +will get added to the default toolpath.</para> + +<para>The default set of +<emphasis>site_scons</emphasis> +dirs used when +<option>--site-dir</option> +is not specified depends on the system platform, as follows. Note +that the directories are examined in the order given, from most +generic to most specific, so the last-executed site_init.py file is +the most specific one (which gives it the chance to override +everything else), and the dirs are prepended to the paths, again so +the last dir examined comes first in the resulting path.</para> + + </listitem> + </varlistentry> +</variablelist> +<variablelist> + <varlistentry> + <term>Windows:</term> + <listitem> +<literallayout class="monospaced"> +%ALLUSERSPROFILE/Application Data/scons/site_scons +%USERPROFILE%/Local Settings/Application Data/scons/site_scons +%APPDATA%/scons/site_scons +%HOME%/.scons/site_scons +./site_scons +</literallayout> + </listitem> + </varlistentry> + <varlistentry> + <term>Mac OS X:</term> + <listitem> +<literallayout class="monospaced"> +/Library/Application Support/SCons/site_scons +/opt/local/share/scons/site_scons (for MacPorts) +/sw/share/scons/site_scons (for Fink) +$HOME/Library/Application Support/SCons/site_scons +$HOME/.scons/site_scons +./site_scons +</literallayout> + </listitem> + </varlistentry> + <varlistentry> + <term>Solaris:</term> + <listitem> +<literallayout class="monospaced"> +/opt/sfw/scons/site_scons +/usr/share/scons/site_scons +$HOME/.scons/site_scons +./site_scons +</literallayout> + </listitem> + </varlistentry> + <varlistentry> + <term>Linux, HPUX, and other Posix-like systems:</term> + <listitem> +<literallayout class="monospaced"> +/usr/share/scons/site_scons +$HOME/.scons/site_scons +./site_scons +</literallayout> + + </listitem> + </varlistentry> +</variablelist> +<variablelist> + <varlistentry> + <term>--stack-size=<emphasis>KILOBYTES</emphasis></term> + <listitem> +<para>Set the size stack used to run threads to +<emphasis>KILOBYTES</emphasis>. +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 +<emphasis role="bold">num_jobs</emphasis> +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.</para> + +<para>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.</para> + + </listitem> + </varlistentry> + <varlistentry> + <term>-t, --touch</term> + <listitem> +<para>Ignored for compatibility with GNU +<emphasis role="bold">make</emphasis>. +(Touching a file to make it +appear up-to-date is unnecessary when using +<command>scons</command>.)</para> + + </listitem> + </varlistentry> + <varlistentry> + <term>--taskmastertrace=<emphasis>file</emphasis></term> + <listitem> +<para>Prints trace information to the specified +<emphasis>file</emphasis> +about how the internal Taskmaster object +evaluates and controls the order in which Nodes are built. +A file name of +<emphasis role="bold">-</emphasis> +may be used to specify the standard output.</para> + + </listitem> + </varlistentry> + <varlistentry> + <term>-tree=<emphasis>options</emphasis></term> + <listitem> +<para>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 +<emphasis>options</emphasis> +specified:</para> + + </listitem> + </varlistentry> + <varlistentry> + <term>--tree=all</term> + <listitem> +<para>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.</para> + + </listitem> + </varlistentry> + <varlistentry> + <term>--tree=derived</term> + <listitem> +<para>Restricts the tree output to only derived (target) files, +not source files.</para> + + </listitem> + </varlistentry> + <varlistentry> + <term>--tree=status</term> + <listitem> +<para>Prints status information for each displayed node.</para> + + </listitem> + </varlistentry> + <varlistentry> + <term>--tree=prune</term> + <listitem> +<para>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 +<emphasis role="bold">[square brackets]</emphasis>, +as an indication that the dependencies +for that node can be found by searching +for the relevant output higher up in the tree.</para> + + </listitem> + </varlistentry> +</variablelist> + +<para>Multiple options may be specified, +separated by commas:</para> + +<literallayout class="monospaced"> +# 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 +</literallayout> + +<variablelist> + <varlistentry> + <term>-u, --up, --search-up</term> + <listitem> +<para>Walks up the directory structure until an +<emphasis>SConstruct ,</emphasis> +<emphasis>Sconstruct</emphasis> +or +<emphasis>sconstruct</emphasis> +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.</para> + + </listitem> + </varlistentry> + <varlistentry> + <term>-U</term> + <listitem> +<para>Works exactly the same way as the +<option>-u</option> +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.</para> + + </listitem> + </varlistentry> + <varlistentry> + <term>-v, --version</term> + <listitem> +<para>Print the +<command>scons</command> +version, copyright information, +list of authors, and any other relevant information. +Then exit.</para> + + </listitem> + </varlistentry> + <varlistentry> + <term>-w, --print-directory</term> + <listitem> +<para>Print a message containing the working directory before and +after other processing.</para> + + </listitem> + </varlistentry> + <varlistentry> + <term>--no-print-directory</term> + <listitem> +<para>Turn off -w, even if it was turned on implicitly.</para> + + </listitem> + </varlistentry> + <varlistentry> + <term>--warn=<emphasis>type</emphasis>, --warn=no-<emphasis>type</emphasis></term> + <listitem> +<para>Enable or disable warnings. +<emphasis>type</emphasis> +specifies the type of warnings to be enabled or disabled:</para> + + </listitem> + </varlistentry> + <varlistentry> + <term>--warn=all, --warn=no-all</term> + <listitem> +<para>Enables or disables all warnings.</para> + + </listitem> + </varlistentry> + <varlistentry> + <term>--warn=cache-write-error, --warn=no-cache-write-error</term> + <listitem> +<para>Enables or disables warnings about errors trying to +write a copy of a built file to a specified +<emphasis role="bold">CacheDir</emphasis>(). +These warnings are disabled by default.</para> + + </listitem> + </varlistentry> + <varlistentry> + <term>--warn=corrupt-sconsign, --warn=no-corrupt-sconsign</term> + <listitem> +<para>Enables or disables warnings about unfamiliar signature data in +<markup>.sconsign</markup> +files. +These warnings are enabled by default.</para> + + </listitem> + </varlistentry> + <varlistentry> + <term>--warn=dependency, --warn=no-dependency</term> + <listitem> +<para>Enables or disables warnings about dependencies. +These warnings are disabled by default.</para> + + </listitem> + </varlistentry> + <varlistentry> + <term>--warn=deprecated, --warn=no-deprecated</term> + <listitem> +<para>Enables or disables all warnings about use of +currently deprecated features. +These warnings are enabled by default. +Note that the +<option>--warn=no-deprecated</option> +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.</para> + + <blockquote> + <variablelist> + <varlistentry> + <term>--warn=deprecated-copy, --warn=no-deprecated-copy</term> + <listitem> +<para>Enables or disables warnings about use of the deprecated +<emphasis role="bold">env.Copy()</emphasis> +method.</para> + + </listitem> + </varlistentry> + <varlistentry> + <term>--warn=deprecated-source-signatures, --warn=no-deprecated-source-signatures</term> + <listitem> +<para>Enables or disables warnings about use of the deprecated +<emphasis role="bold">SourceSignatures()</emphasis> +function or +<emphasis role="bold">env.SourceSignatures()</emphasis> +method.</para> + + </listitem> + </varlistentry> + <varlistentry> + <term>--warn=deprecated-target-signatures, --warn=no-deprecated-target-signatures</term> + <listitem> +<para>Enables or disables warnings about use of the deprecated +<emphasis role="bold">TargetSignatures()</emphasis> +function or +<emphasis role="bold">env.TargetSignatures()</emphasis> +method.</para> + </listitem> + </varlistentry> + </variablelist> + </blockquote> + + </listitem> + </varlistentry> + <varlistentry> + <term>--warn=duplicate-environment, --warn=no-duplicate-environment</term> + <listitem> +<para>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.</para> + + </listitem> + </varlistentry> + <varlistentry> + <term>--warn=fortran-cxx-mix, --warn=no-fortran-cxx-mix</term> + <listitem> +<para>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.</para> + + </listitem> + </varlistentry> + <varlistentry> + <term>--warn=future-deprecated, --warn=no-future-deprecated</term> + <listitem> +<para>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.</para> + + </listitem> + </varlistentry> + <varlistentry> + <term>--warn=link, --warn=no-link</term> + <listitem> +<para>Enables or disables warnings about link steps.</para> + + </listitem> + </varlistentry> + <varlistentry> + <term>--warn=misleading-keywords, --warn=no-misleading-keywords</term> + <listitem> +<para>Enables or disables warnings about use of the misspelled keywords +<emphasis role="bold">targets</emphasis> +and +<emphasis role="bold">sources</emphasis> +when calling Builders. +(Note the last +<emphasis role="bold">s</emphasis> +characters, the correct spellings are +<emphasis role="bold">target</emphasis> +and +<emphasis role="bold">source.)</emphasis> +These warnings are enabled by default.</para> + + </listitem> + </varlistentry> + <varlistentry> + <term>--warn=missing-sconscript, --warn=no-missing-sconscript</term> + <listitem> +<para>Enables or disables warnings about missing SConscript files. +These warnings are enabled by default.</para> + + </listitem> + </varlistentry> + <varlistentry> + <term>--warn=no-md5-module, --warn=no-no-md5-module</term> + <listitem> +<para>Enables or disables warnings about the version of Python +not having an MD5 checksum module available. +These warnings are enabled by default.</para> + + </listitem> + </varlistentry> + <varlistentry> + <term>--warn=no-metaclass-support, --warn=no-no-metaclass-support</term> + <listitem> +<para>Enables or disables warnings about the version of Python +not supporting metaclasses when the +<option>--debug=memoizer</option> +option is used. +These warnings are enabled by default.</para> + + </listitem> + </varlistentry> + <varlistentry> + <term>--warn=no-object-count, --warn=no-no-object-count</term> + <listitem> +<para>Enables or disables warnings about the +<option>--debug=object</option> +feature not working when +<command>scons</command> +is run with the python +<option>-O</option> +option or from optimized Python (.pyo) modules.</para> + + </listitem> + </varlistentry> + <varlistentry> + <term>--warn=no-parallel-support, --warn=no-no-parallel-support</term> + <listitem> +<para>Enables or disables warnings about the version of Python +not being able to support parallel builds when the +<option>-j</option> +option is used. +These warnings are enabled by default.</para> + + </listitem> + </varlistentry> + <varlistentry> + <term>--warn=python-version, --warn=no-python-version</term> + <listitem> +<para>Enables or disables the warning about running +SCons with a deprecated version of Python. +These warnings are enabled by default.</para> + + </listitem> + </varlistentry> + <varlistentry> + <term>--warn=reserved-variable, --warn=no-reserved-variable</term> + <listitem> +<para>Enables or disables warnings about attempts to set the +reserved construction variable names +<emphasis role="bold">CHANGED_SOURCES</emphasis>, +<emphasis role="bold">CHANGED_TARGETS</emphasis>, +<emphasis role="bold">TARGET</emphasis>, +<emphasis role="bold">TARGETS</emphasis>, +<emphasis role="bold">SOURCE</emphasis>, +<emphasis role="bold">SOURCES</emphasis>, +<emphasis role="bold">UNCHANGED_SOURCES</emphasis> +or +<emphasis role="bold">UNCHANGED_TARGETS</emphasis>. +These warnings are disabled by default.</para> + + </listitem> + </varlistentry> + <varlistentry> + <term>--warn=stack-size, --warn=no-stack-size</term> + <listitem> +<para>Enables or disables warnings about requests to set the stack size +that could not be honored. +These warnings are enabled by default.</para> + +<!-- .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. --> + + </listitem> + </varlistentry> + <varlistentry> + <term>--warn=target_not_build, --warn=no-target_not_built</term> + <listitem> +<para>Enables or disables warnings about a build rule not building the + expected targets. These warnings are not currently enabled by default.</para> + + </listitem> + </varlistentry> + <varlistentry> + <term>-Y<emphasis> repository</emphasis>, --repository=<emphasis>repository</emphasis>, --srcdir=<emphasis>repository</emphasis></term> + <listitem> +<para>Search the specified repository for any input and target +files not found in the local directory hierarchy. Multiple +<option>-Y</option> +options may be specified, in which case the +repositories are searched in the order specified.</para> + + </listitem> + </varlistentry> +</variablelist> +</refsect1> + +<refsect1 id='configuration_file_reference'><title>CONFIGURATION FILE REFERENCE</title> +<!-- .SS Python Basics --> +<!-- XXX Adding this in the future would be a help. --> + +<refsect2 id='construction_environments'><title>Construction Environments</title> +<para>A construction environment is the basic means by which the SConscript +files communicate build information to +<command>scons</command>. +A new construction environment is created using the +<emphasis role="bold">Environment</emphasis> +function:</para> + +<literallayout class="monospaced"> +env = Environment() +</literallayout> + +<para>Variables, called +<emphasis>construction</emphasis> +<emphasis>variables</emphasis>, +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:</para> + +<literallayout class="monospaced"> +env = Environment(FOO = 'foo') +env['BAR'] = 'bar' +</literallayout> + +<para>As a convenience, +construction variables may also be set or modified by the +<emphasis>parse_flags</emphasis> +keyword argument, which applies the +<emphasis role="bold">ParseFlags</emphasis> +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.</para> + +<literallayout class="monospaced"> +env = Environment(parse_flags = '-Iinclude -DEBUG -lm') +</literallayout> + +<para>This example adds 'include' to +<emphasis role="bold">CPPPATH</emphasis>, +'EBUG' to +<emphasis role="bold">CPPDEFINES</emphasis>, +and 'm' to +<emphasis role="bold">LIBS</emphasis>.</para> + +<para>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:</para> + +<literallayout class="monospaced"> +env = Environment(platform = 'cygwin') +env = Environment(platform = 'os2') +env = Environment(platform = 'posix') +env = Environment(platform = 'win32') +</literallayout> + +<para>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.</para> + +<para>Note that the +<emphasis role="bold">win32</emphasis> +platform adds the +<emphasis role="bold">SystemDrive</emphasis> +and +<emphasis role="bold">SystemRoot</emphasis> +variables from the user's external environment +to the construction environment's +<emphasis role="bold">ENV</emphasis> +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 +<emphasis role="bold">:pserver:anonymous@cvs.sourceforge.net:/cvsroot/scons</emphasis>) +will work on Windows systems.</para> + +<para>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:</para> + +<programlisting> +def my_platform(env): + env['VAR'] = 'xyzzy' + +env = Environment(platform = my_platform) +</programlisting> + +<para>Additionally, a specific set of tools +with which to initialize the environment +may be specified as an optional keyword argument:</para> + +<literallayout class="monospaced"> +env = Environment(tools = ['msvc', 'lex']) +</literallayout> + +<para>Non-built-in tools may be specified using the toolpath argument:</para> + +<literallayout class="monospaced"> +env = Environment(tools = ['default', 'foo'], toolpath = ['tools']) +</literallayout> + +<para>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 +<function>generate()</function> +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 +<function>exists()</function> +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 +<emphasis role="bold">Clone</emphasis>() +and +<emphasis role="bold">Tool</emphasis>() +methods:</para> + +<literallayout class="monospaced"> +base = Environment(toolpath=['custom_path']) +derived = base.Clone(tools=['custom_tool']) +derived.CustomBuilder() +</literallayout> + +<para>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:</para> + +<programlisting> +def my_tool(env): + env['XYZZY'] = 'xyzzy' + +env = Environment(tools = [my_tool]) +</programlisting> + +<para>The individual elements of the tools list +may also themselves be two-element lists of the form +(<emphasis>toolname</emphasis>, <emphasis>kw_dict</emphasis>). +SCons searches for the +<emphasis>toolname</emphasis> +specification file as described above, and +passes +<emphasis>kw_dict</emphasis>, +which must be a dictionary, as keyword arguments to the tool's +<emphasis role="bold">generate</emphasis> +function. +The +<emphasis role="bold">generate</emphasis> +function can use the arguments to modify the tool's behavior +by setting up the environment in different ways +or otherwise changing its initialization.</para> + +<programlisting> +# 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']) +</programlisting> + +<para>The tool definition (i.e. my_tool()) can use the PLATFORM variable from +the environment it receives to customize the tool for different platforms.</para> + +<para>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.</para> + +<para>SCons supports the following tool specifications out of the box:</para> + +<!-- '\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" --> +<!-- '\" BEGIN GENERATED TOOL DESCRIPTIONS --> + +<!-- '\" The descriptions below of the various SCons Tools 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 TOOL DESCRIPTIONS --> +<!-- '\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" --> +<xsi:include xmlns:xsi="http://www.w3.org/2001/XInclude" href="../generated/tools.gen"/> +<!-- '\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" --> +<!-- '\" END GENERATED TOOL DESCRIPTIONS --> + +<!-- '\" The descriptions above of the various SCons Tools 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 TOOL DESCRIPTIONS --> +<!-- '\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" --> + +<para>Additionally, there is a "tool" named +<emphasis role="bold">default</emphasis> +which configures the +environment with a default set of tools for the current platform.</para> + +<para>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.</para> + +</refsect2> + +<refsect2 id='builder_methods'><title>Builder Methods</title> + +<para>Build rules are specified by calling a construction +environment's builder methods. +The arguments to the builder methods are +<emphasis role="bold">target</emphasis> +(a list of targets to be built, +usually file names) +and +<emphasis role="bold">source</emphasis> +(a list of sources to be built, +usually file names).</para> + +<para>Because long lists of file names +can lead to a lot of quoting, +<command>scons</command> +supplies a +<emphasis role="bold">Split()</emphasis> +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.)</para> + +<para>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:</para> + +<literallayout class="monospaced"> +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()) +</literallayout> + +<para>Target and source file names +that are not absolute path names +(that is, do not begin with +<emphasis role="bold">/</emphasis> +on POSIX systems +or +<emphasis role="bold">\fR +on Windows systems, +with or without +an optional drive letter) +are interpreted relative to the directory containing the +SConscript</emphasis> +file being read. +An initial +<emphasis role="bold">#</emphasis> +(hash mark) +on a path name means that the rest of the file name +is interpreted relative to +the directory containing +the top-level +<emphasis role="bold">SConstruct</emphasis> +file, +even if the +<emphasis role="bold">#</emphasis> +is followed by a directory separator character +(slash or backslash).</para> + +<para>Examples:</para> + +<programlisting> +# 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') +</programlisting> + +<para>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 +<command>scons</command> +will deduce the target file name from +the source file name. +The following examples all build the +executable program +<emphasis role="bold">bar</emphasis> +(on POSIX systems) +or +<emphasis role="bold">bar.exe</emphasis> +(on Windows systems) +from the bar.c source file:</para> + +<literallayout class="monospaced"> +env.Program(target = 'bar', source = 'bar.c') +env.Program('bar', source = 'bar.c') +env.Program(source = 'bar.c') +env.Program('bar.c') +</literallayout> + +<para>As a convenience, a +<emphasis role="bold">srcdir</emphasis> +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 +<emphasis role="bold">srcdir</emphasis>. +The following example will build the +<emphasis role="bold">build/prog</emphasis> +(or +<emphasis role="bold">build/prog.exe</emphasis> +on Windows) +program from the files +<emphasis role="bold">src/f1.c</emphasis> +and +<emphasis role="bold">src/f2.c</emphasis>:</para> + +<literallayout class="monospaced"> +env.Program('build/prog', ['f1.c', 'f2.c'], srcdir='src') +</literallayout> + +<para>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:</para> + +<literallayout class="monospaced"> +env.Program('hello', 'hello.c', LIBS=['gl', 'glut']) +</literallayout> + +<para>or generate a shared library with a non-standard suffix:</para> + +<literallayout class="monospaced"> +env.SharedLibrary('word', 'word.cpp', + SHLIBSUFFIX='.ocx', + LIBSUFFIXES=['.ocx']) +</literallayout> + +<para>(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.)</para> + +<para>It is also possible to use the +<emphasis>parse_flags</emphasis> +keyword argument in an override:</para> + +<literallayout class="monospaced"> +env = Program('hello', 'hello.c', parse_flags = '-Iinclude -DEBUG -lm') +</literallayout> + +<para>This example adds 'include' to +<emphasis role="bold">CPPPATH</emphasis>, +'EBUG' to +<emphasis role="bold">CPPDEFINES</emphasis>, +and 'm' to +<emphasis role="bold">LIBS</emphasis>.</para> + +<para>Although the builder methods defined by +<command>scons</command> +are, in fact, +methods of a construction environment object, +they may also be called without an explicit environment:</para> + +<literallayout class="monospaced"> +Program('hello', 'hello.c') +SharedLibrary('word', 'word.cpp') +</literallayout> + +<para>In this case, +the methods are called internally using a default construction +environment that consists of the tools and values that +<command>scons</command> +has determined are appropriate for the local system.</para> + +<para>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:</para> + +<literallayout class="monospaced"> +from SCons.Script import * +</literallayout> + +<para>All builder methods return a list-like object +containing Nodes that +represent the target or targets that will be built. +A +<emphasis>Node</emphasis> +is an internal SCons object +which represents +build targets or sources.</para> + +<para>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 +<option>-D</option> +flag when compiling one specific object file:</para> + +<literallayout class="monospaced"> +bar_obj_list = env.StaticObject('bar.c', CPPDEFINES='-DBAR') +env.Program(source = ['foo.c', bar_obj_list, 'main.c']) +</literallayout> + +<para>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.</para> + +<para>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:</para> + +<literallayout class="monospaced"> +foo = Object('foo.c') +bar = Object('bar.c') +objects = ['begin.o'] + foo + ['middle.o'] + bar + ['end.o'] +for object in objects: + print str(object) +</literallayout> + +<para>Or you can use the +<emphasis role="bold">Flatten</emphasis>() +function supplied by scons +to create a list containing just the Nodes, +which may be more convenient:</para> + +<literallayout class="monospaced"> +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) +</literallayout> + +<para>Note also that because Builder calls return +a list-like object, not an actual Python list, +you should +<emphasis>not</emphasis> +use the Python +<emphasis role="bold">+=</emphasis> +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 +<markup>.extend()</markup> +method to make sure the list is updated in-place. +Example:</para> + +<literallayout class="monospaced"> +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')) + +</literallayout> + +<para>The path name for a Node's file may be used +by passing the Node to the Python-builtin +<function>str()</function> +function:</para> + +<literallayout class="monospaced"> +bar_obj_list = env.StaticObject('bar.c', CPPDEFINES='-DBAR') +print "The path to bar_obj is:", str(bar_obj_list[0]) +</literallayout> + +<para>Note again that because the Builder call returns a list, +we have to access the first element in the list +<emphasis role="bold">(bar_obj_list[0])</emphasis> +to get at the Node that actually represents +the object file.</para> + +<para>Builder calls support a +<emphasis role="bold">chdir</emphasis> +keyword argument that +specifies that the Builder's action(s) +should be executed +after changing directory. +If the +<emphasis role="bold">chdir</emphasis> +argument is +a string or a directory Node, +scons will change to the specified directory. +If the +<emphasis role="bold">chdir</emphasis> +is not a string or Node +and is non-zero, +then scons will change to the +target file's directory.</para> + +<literallayout class="monospaced"> +# 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) +</literallayout> + +<para>Note that scons will +<emphasis>not</emphasis> +automatically modify +its expansion of +construction variables like +<emphasis role="bold">$TARGET</emphasis> +and +<emphasis role="bold">$SOURCE</emphasis> +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 +<emphasis role="bold">${TARGET.file}</emphasis> +and +<emphasis role="bold">${SOURCE.file}</emphasis> +to use just the filename portion of the +targets and source.</para> + +<para><command>scons</command> +provides the following builder methods:</para> + +<!-- '\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" --> +<!-- '\" 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 --> +<!-- '\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" --> +<xsi:include xmlns:xsi="http://www.w3.org/2001/XInclude" href="../generated/builders.gen"/> +<!-- '\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" --> +<!-- '\" 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 --> +<!-- '\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" --> + + +<para>All +targets of builder methods automatically depend on their sources. +An explicit dependency can +be specified using the +<emphasis role="bold">Depends</emphasis> +method of a construction environment (see below).</para> + +<para>In addition, +<command>scons</command> +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 +<markup>.F</markup> +(POSIX systems only), +<markup>.fpp,</markup> +or +<markup>.FPP</markup> +file extensions, +and assembly language files with +<markup>.S</markup> +(POSIX systems only), +<markup>.spp,</markup> +or +<markup>.SPP</markup> +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 +<emphasis role="bold">Object</emphasis>(), +<emphasis role="bold">StaticObject</emphasis>(), +and +<emphasis role="bold">SharedObject</emphasis>() +Builders by adding them +to the +<emphasis role="bold">SourceFileScanner</emphasis> +object. +See the section "Scanner Objects" +below, for more information about +defining your own Scanner objects +and using the +<emphasis role="bold">SourceFileScanner</emphasis> +object.</para> + +</refsect2> + +<refsect2 id='methods_and_functions_to_do_things'><title>Methods and Functions to Do Things</title> +<para>In addition to Builder methods, +<command>scons</command> +provides a number of other construction environment methods +and global functions to +manipulate the build configuration.</para> + +<para>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:</para> +<literallayout class="monospaced"> +Function(<emphasis>arguments</emphasis>) +</literallayout> +<para>and if you call something through a construction +environment it looks like:</para> +<literallayout class="monospaced"> +env.Function(<emphasis>arguments</emphasis>) +</literallayout> +<para>If you can call the functionality in both ways, +then both forms are listed.</para> + +<para>Global functions may be called from custom Python modules that you +import into an SConscript file by adding the following +to the Python module:</para> + +<literallayout class="monospaced"> +from SCons.Script import * +</literallayout> + +<para>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:</para> + +<literallayout class="monospaced"> +env = Environment(FOO = 'foo') +Default('$FOO') +env.Default('$FOO') +</literallayout> + +<para>In the above example, +the first call to the global +<emphasis role="bold">Default()</emphasis> +function will actually add a target named +<emphasis role="bold">$FOO</emphasis> +to the list of default targets, +while the second call to the +<emphasis role="bold">env.Default()</emphasis> +construction environment method +will expand the value +and add a target named +<emphasis role="bold">foo</emphasis> +to the list of default targets. +For more on construction variable expansion, +see the next section on +construction variables.</para> + +<para>Construction environment methods +and global functions supported by +<command>scons</command> +include:</para> + +<!-- '\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" --> +<!-- '\" BEGIN GENERATED FUNCTION DESCRIPTIONS --> + +<!-- '\" The descriptions below of the various SCons functions are generated --> +<!-- '\" from the .xml files that live next to the various Python modules in --> +<!-- '\" the build enginer library. If you're reading this [gnt]roff file --> +<!-- '\" with an eye towards patching this man page, you can still submit --> +<!-- '\" a diff against this text, but it will have to be translated to a --> +<!-- '\" diff against the underlying .xml file before the patch is actually --> +<!-- '\" accepted. If you do that yourself, it will make it easier to --> +<!-- '\" integrate the patch. --> + +<!-- '\" BEGIN GENERATED FUNCTION DESCRIPTIONS --> +<!-- '\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" --> +<xsi:include xmlns:xsi="http://www.w3.org/2001/XInclude" href="../generated/functions.gen"/> +<!-- '\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" --> +<!-- '\" END GENERATED FUNCTION DESCRIPTIONS --> + +<!-- '\" The descriptions above of the various SCons functions are generated --> +<!-- '\" from the .xml files that live next to the various Python modules in --> +<!-- '\" the build enginer library. If you're reading this [gnt]roff file --> +<!-- '\" with an eye towards patching this man page, you can still submit --> +<!-- '\" a diff against this text, but it will have to be translated to a --> +<!-- '\" diff against the underlying .xml file before the patch is actually --> +<!-- '\" accepted. If you do that yourself, it will make it easier to --> +<!-- '\" integrate the patch. --> + +<!-- '\" END GENERATED FUNCTION DESCRIPTIONS --> +<!-- '\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" --> + +</refsect2> + +<refsect2 id='sconscript_variables'><title>SConscript Variables</title> +<para>In addition to the global functions and methods, +<command>scons</command> +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:</para> + +<literallayout class="monospaced"> +from SCons.Script import * +</literallayout> + +<!-- '\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" --> +<variablelist> + <varlistentry> + <term>ARGLIST</term> + <listitem> +<para>A list +<emphasis>keyword</emphasis>=<emphasis>value</emphasis> +arguments specified on the command line. +Each element in the list is a tuple +containing the +(<emphasis>keyword</emphasis>,<emphasis>value</emphasis>) +of the argument. +The separate +<emphasis>keyword</emphasis> +and +<emphasis>value</emphasis> +elements of the tuple +can be accessed by +subscripting for element +<emphasis role="bold">[0]</emphasis> +and +<emphasis role="bold">[1]</emphasis> +of the tuple, respectively.</para> + +<para>Example:</para> + +<literallayout class="monospaced"> +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 +</literallayout> + +<!-- '\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" --> + </listitem> + </varlistentry> + <varlistentry> + <term>ARGUMENTS</term> + <listitem> +<para>A dictionary of all the +<emphasis>keyword</emphasis>=<emphasis>value</emphasis> +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 +<emphasis role="bold">ARGUMENTS</emphasis> +dictionary.</para> + +<para>Example:</para> + +<literallayout class="monospaced"> +if ARGUMENTS.get('debug', 0): + env = Environment(CCFLAGS = '-g') +else: + env = Environment() +</literallayout> + +<!-- '\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" --> + </listitem> + </varlistentry> + <varlistentry> + <term>BUILD_TARGETS</term> + <listitem> +<para>A list of the targets which +<command>scons</command> +will actually try to build, +regardless of whether they were specified on +the command line or via the +<emphasis role="bold">Default</emphasis>() +function or method. +The elements of this list may be strings +<emphasis>or</emphasis> +nodes, so you should run the list through the Python +<emphasis role="bold">str</emphasis> +function to make sure any Node path names +are converted to strings.</para> + +<para>Because this list may be taken from the +list of targets specified using the +<emphasis role="bold">Default</emphasis>() +function or method, +the contents of the list may change +on each successive call to +<emphasis role="bold">Default</emphasis>(). +See the +<emphasis role="bold">DEFAULT_TARGETS</emphasis> +list, below, +for additional information.</para> + +<para>Example:</para> + +<literallayout class="monospaced"> +if 'foo' in BUILD_TARGETS: + print "Don't forget to test the `foo' program!" +if 'special/program' in BUILD_TARGETS: + SConscript('special') +</literallayout> + </listitem> + </varlistentry> +</variablelist> + +<para>Note that the +<emphasis role="bold">BUILD_TARGETS</emphasis> +list only contains targets expected listed +on the command line or via calls to the +<emphasis role="bold">Default</emphasis>() +function or method. +It does +<emphasis>not</emphasis> +contain all dependent targets that will be built as +a result of making the sure the explicitly-specified +targets are up to date.</para> + +<!-- '\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" --> +<variablelist> + <varlistentry> + <term>COMMAND_LINE_TARGETS</term> + <listitem> +<para>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.</para> + +<para>Example:</para> + +<literallayout class="monospaced"> +if 'foo' in COMMAND_LINE_TARGETS: + print "Don't forget to test the `foo' program!" +if 'special/program' in COMMAND_LINE_TARGETS: + SConscript('special') +</literallayout> + +<!-- '\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" --> + </listitem> + </varlistentry> + <varlistentry> + <term>DEFAULT_TARGETS</term> + <listitem> +<para>A list of the target +<emphasis>nodes</emphasis> +that have been specified using the +<emphasis role="bold">Default</emphasis>() +function or method. +The elements of the list are nodes, +so you need to run them through the Python +<emphasis role="bold">str</emphasis> +function to get at the path name for each Node.</para> + +<para>Example:</para> + +<literallayout class="monospaced"> +print str(DEFAULT_TARGETS[0]) +if 'foo' in map(str, DEFAULT_TARGETS): + print "Don't forget to test the `foo' program!" +</literallayout> + </listitem> + </varlistentry> +</variablelist> + +<para>The contents of the +<emphasis role="bold">DEFAULT_TARGETS</emphasis> +list change on on each successive call to the +<emphasis role="bold">Default</emphasis>() +function:</para> + +<literallayout class="monospaced"> +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 [] +</literallayout> + +<para>Consequently, be sure to use +<emphasis role="bold">DEFAULT_TARGETS</emphasis> +only after you've made all of your +<emphasis role="bold">Default</emphasis>() +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.</para> + +</refsect2> + +<refsect2 id='construction_variables'><title>Construction Variables</title> +<!-- 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 ;\-) --> +<para>A construction environment has an associated dictionary of +<emphasis>construction variables</emphasis> +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.</para> + +<para>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:</para> + +<!-- '\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" --> +<!-- '\" 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 --> +<!-- '\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" --> +<xsi:include xmlns:xsi="http://www.w3.org/2001/XInclude" href="../generated/variables.gen"/> +<!-- '\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" --> +<!-- '\" 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 --> +<!-- '\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" --> + + +<para>Construction variables can be retrieved and set using the +<emphasis role="bold">Dictionary</emphasis> +method of the construction environment:</para> + +<literallayout class="monospaced"> +dict = env.Dictionary() +dict["CC"] = "cc" +</literallayout> + +<para>or using the [] operator:</para> + +<literallayout class="monospaced"> +env["CC"] = "cc" +</literallayout> + +<para>Construction variables can also be passed to the construction environment +constructor:</para> + +<literallayout class="monospaced"> +env = Environment(CC="cc") +</literallayout> + +<para>or when copying a construction environment using the +<emphasis role="bold">Clone</emphasis> +method:</para> + +<literallayout class="monospaced"> +env2 = env.Clone(CC="cl.exe") +</literallayout> + +</refsect2> + +<refsect2 id='configure_contexts'><title>Configure Contexts</title> + +<para><command>scons</command> +supports +<emphasis>configure contexts,</emphasis> +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, +<command>scons</command> +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 +<option>--config</option> +command line option.</para> + +<para>The following methods can be used to perform checks:</para> + +<variablelist> + <varlistentry> + <term>Configure(<emphasis>env</emphasis>, [<emphasis>custom_tests</emphasis>, <emphasis>conf_dir</emphasis>, <emphasis>log_file</emphasis>, <emphasis>config_h</emphasis>, <emphasis>clean</emphasis>, <emphasis>help])</emphasis></term> + <term>env.Configure([<emphasis>custom_tests</emphasis>, <emphasis>conf_dir</emphasis>, <emphasis>log_file</emphasis>, <emphasis>config_h</emphasis>, <emphasis>clean</emphasis>, <emphasis>help])</emphasis></term> + <listitem> +<para>This creates a configure context, which can be used to perform checks. +<emphasis>env</emphasis> +specifies the environment for building the tests. +This environment may be modified when performing checks. +<emphasis>custom_tests</emphasis> +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. +<emphasis>conf_dir</emphasis> +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. +<emphasis>log_file</emphasis> +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 +<emphasis role="bold">VariantDir</emphasis>() +method, +you may want to specify a subdirectory under your variant directory. +<emphasis>config_h</emphasis> +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 +<emphasis role="bold">config.h</emphasis> +file. +You can specify the same +<emphasis role="bold">config.h</emphasis> +file in multiple calls to Configure, +in which case +<command>scons</command> +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 +<emphasis>config_h</emphasis> +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 +<emphasis>config_h</emphasis> +file is being built.</para> + +<para>The optional +<emphasis role="bold">clean</emphasis> +and +<emphasis role="bold">help</emphasis> +arguments can be used to suppress execution of the configuration +tests when the +<option>-c/--clean</option> +or +<option>-H/-h/--help</option> +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 +<emphasis role="bold">clean=False</emphasis> +or +<emphasis role="bold">help=False</emphasis> +arguments +(or both) +to avoid unnecessary test execution.</para> + + </listitem> + </varlistentry> +</variablelist> +<para>A created +<emphasis role="bold">Configure</emphasis> +instance has the following associated methods:</para> + +<variablelist> + <varlistentry> + <term>SConf.Finish(<emphasis>context</emphasis>)</term> + <term><emphasis>sconf</emphasis>.Finish()</term> + <listitem> +<para>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 +Configure +context to perform additional checks. +Only one context should be active at a time.</para> + +<para>The following Checks are predefined. +(This list will likely grow larger as time +goes by and developers contribute new useful tests.)</para> + + </listitem> + </varlistentry> + <varlistentry> + <term>SConf.CheckHeader(<emphasis>context</emphasis>, <emphasis>header</emphasis>, [<emphasis>include_quotes</emphasis>, <emphasis>language</emphasis>])</term> + <term><emphasis>sconf</emphasis>.CheckHeader(<emphasis>header</emphasis>, [<emphasis>include_quotes</emphasis>, <emphasis>language</emphasis>])</term> + <listitem> +<para>Checks if +<emphasis>header</emphasis> +is usable in the specified language. +<emphasis>header</emphasis> +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 +<emphasis role="bold">#include</emphasis> +lines should precede the +header line being checked for. +The optional argument +<emphasis>include_quotes</emphasis> +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 +<emphasis>language</emphasis> +should be either +<emphasis role="bold">C</emphasis> +or +<emphasis role="bold">C++</emphasis> +and selects the compiler to be used for the check. +Returns 1 on success and 0 on failure.</para> + + </listitem> + </varlistentry> + <varlistentry> + <term>SConf.CheckCHeader(<emphasis>context</emphasis>, <emphasis>header</emphasis>, [<emphasis>include_quotes</emphasis>])</term> + <term><emphasis>sconf</emphasis>.CheckCHeader(<emphasis>header</emphasis>, [<emphasis>include_quotes</emphasis>])</term> + <listitem> +<para>This is a wrapper around +<emphasis role="bold">SConf.CheckHeader</emphasis> +which checks if +<emphasis>header</emphasis> +is usable in the C language. +<emphasis>header</emphasis> +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 +<emphasis role="bold">#include</emphasis> +lines should precede the +header line being checked for. +The optional argument +<emphasis>include_quotes</emphasis> +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.</para> + + </listitem> + </varlistentry> + <varlistentry> + <term>SConf.CheckCXXHeader(<emphasis>context</emphasis>, <emphasis>header</emphasis>, [<emphasis>include_quotes</emphasis>])</term> + <term><emphasis>sconf</emphasis>.CheckCXXHeader(<emphasis>header</emphasis>, [<emphasis>include_quotes</emphasis>])</term> + <listitem> +<para>This is a wrapper around +<emphasis role="bold">SConf.CheckHeader</emphasis> +which checks if +<emphasis>header</emphasis> +is usable in the C++ language. +<emphasis>header</emphasis> +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 +<emphasis role="bold">#include</emphasis> +lines should precede the +header line being checked for. +The optional argument +<emphasis>include_quotes</emphasis> +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.</para> + + </listitem> + </varlistentry> + <varlistentry> + <term>SConf.CheckFunc(<emphasis>context,</emphasis>, <emphasis>function_name</emphasis>, [<emphasis>header</emphasis>, <emphasis>language</emphasis>])</term> + <term><emphasis>sconf</emphasis>.CheckFunc(<emphasis>function_name</emphasis>, [<emphasis>header</emphasis>, <emphasis>language</emphasis>])</term> + <listitem> +<para>Checks if the specified +C or C++ function is available. +<emphasis>function_name</emphasis> +is the name of the function to check for. +The optional +<emphasis>header</emphasis> +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:</para> +<literallayout class="monospaced"> +#ifdef __cplusplus +extern "C" +#endif +char function_name(); +</literallayout> +<para>The optional +<emphasis>language</emphasis> +argument should be +<emphasis role="bold">C</emphasis> +or +<emphasis role="bold">C++</emphasis> +and selects the compiler to be used for the check; +the default is "C".</para> + + </listitem> + </varlistentry> + <varlistentry> + <term>SConf.CheckLib(<emphasis>context</emphasis>, [<emphasis>library</emphasis>, <emphasis>symbol</emphasis>, <emphasis>header</emphasis>, <emphasis>language</emphasis>, <emphasis>autoadd=1</emphasis>])</term> + <term><emphasis>sconf</emphasis>.CheckLib([<emphasis>library</emphasis>, <emphasis>symbol</emphasis>, <emphasis>header</emphasis>, <emphasis>language</emphasis>, <emphasis>autoadd=1</emphasis>])</term> + <listitem> +<para>Checks if +<emphasis>library</emphasis> +provides +<emphasis>symbol</emphasis>. +If the value of +<emphasis>autoadd</emphasis> +is 1 and the library provides the specified +<emphasis>symbol</emphasis>, +appends the library to the LIBS construction environment variable. +<emphasis>library</emphasis> +may also be None (the default), +in which case +<emphasis>symbol</emphasis> +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 +<emphasis>symbol</emphasis>. +If +<emphasis>symbol</emphasis> +is not set or is +<emphasis role="bold">None</emphasis>, +then +<emphasis role="bold">SConf.CheckLib</emphasis>() +just checks if +you can link against the specified +<emphasis>library</emphasis>. +The optional +<emphasis>language</emphasis> +argument should be +<emphasis role="bold">C</emphasis> +or +<emphasis role="bold">C++</emphasis> +and selects the compiler to be used for the check; +the default is "C". +The default value for +<emphasis>autoadd</emphasis> +is 1. +This method returns 1 on success and 0 on error.</para> + + </listitem> + </varlistentry> + <varlistentry> + <term>SConf.CheckLibWithHeader(<emphasis>context</emphasis>, <emphasis>library</emphasis>, <emphasis>header</emphasis>, <emphasis>language</emphasis>, [<emphasis>call</emphasis>, <emphasis>autoadd</emphasis>])</term> + <term><emphasis>sconf</emphasis>.CheckLibWithHeader(<emphasis>library</emphasis>, <emphasis>header</emphasis>, <emphasis>language</emphasis>, [<emphasis>call</emphasis>, <emphasis>autoadd</emphasis>])</term> + <listitem> + +<para>In contrast to the +SConf.CheckLib +call, this call provides a more sophisticated way to check against libraries. +Again, +<emphasis>library</emphasis> +specifies the library or a list of libraries to check. +<emphasis>header</emphasis> +specifies a header to check for. +<emphasis>header</emphasis> +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 +<emphasis role="bold">#include</emphasis> +lines should precede the +header line being checked for. +<emphasis>language</emphasis> +may be one of 'C','c','CXX','cxx','C++' and 'c++'. +<emphasis>call</emphasis> +can be any valid expression (with a trailing ';'). +If +<emphasis>call</emphasis> +is not set, +the default simply checks that you +can link against the specified +<emphasis>library</emphasis>. +<emphasis>autoadd</emphasis> +specifies whether to add the library to the environment (only if the check +succeeds). This method returns 1 on success and 0 on error.</para> + + </listitem> + </varlistentry> + <varlistentry> + <term>SConf.CheckType(<emphasis>context</emphasis>, <emphasis>type_name</emphasis>, [<emphasis>includes</emphasis>, <emphasis>language</emphasis>])</term> + <term><emphasis>sconf</emphasis>.CheckType(<emphasis>type_name</emphasis>, [<emphasis>includes</emphasis>, <emphasis>language</emphasis>])</term> + <listitem> +<para>Checks for the existence of a type defined by +<emphasis role="bold">typedef</emphasis>. +<emphasis>type_name</emphasis> +specifies the typedef name to check for. +<emphasis>includes</emphasis> +is a string containing one or more +<emphasis role="bold">#include</emphasis> +lines that will be inserted into the program +that will be run to test for the existence of the type. +The optional +<emphasis>language</emphasis> +argument should be +<emphasis role="bold">C</emphasis> +or +<emphasis role="bold">C++</emphasis> +and selects the compiler to be used for the check; +the default is "C". +Example:</para> +<literallayout class="monospaced"> +sconf.CheckType('foo_type', '#include "my_types.h"', 'C++') +</literallayout> + + </listitem> + </varlistentry> + <varlistentry> + <term>Configure.CheckCC(<emphasis>self</emphasis>)</term> + <listitem> +<para>Checks whether the C compiler (as defined by the CC construction variable) works +by trying to compile a small source file.</para> + +<para>By default, SCons only detects if there is a program with the correct name, not +if it is a functioning compiler.</para> + +<para>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.</para> + + </listitem> + </varlistentry> + <varlistentry> + <term>Configure.CheckCXX(<emphasis>self</emphasis>)</term> + <listitem> +<para>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.</para> + +<para>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.</para> + + </listitem> + </varlistentry> + <varlistentry> + <term>Configure.CheckSHCC(<emphasis>self</emphasis>)</term> + <listitem> +<para>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.</para> + +<para>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.</para> + + </listitem> + </varlistentry> + <varlistentry> + <term>Configure.CheckSHCXX(<emphasis>self</emphasis>)</term> + <listitem> +<para>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.</para> + +<para>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.</para> + + </listitem> + </varlistentry> +</variablelist> +<para>Example of a typical Configure usage:</para> + +<literallayout class="monospaced"> +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() +</literallayout> + +<variablelist> + <varlistentry> + <term>SConf.CheckTypeSize(<emphasis>context</emphasis>, <emphasis>type_name</emphasis>, [<emphasis>header</emphasis>, <emphasis>language</emphasis>, <emphasis>expect</emphasis>])</term> + <term><emphasis>sconf</emphasis>.CheckTypeSize(<emphasis>type_name</emphasis>, [<emphasis>header</emphasis>, <emphasis>language</emphasis>, <emphasis>expect</emphasis>])</term> + <listitem> +<para>Checks for the size of a type defined by +<emphasis role="bold">typedef</emphasis>. +<emphasis>type_name</emphasis> +specifies the typedef name to check for. +The optional +<emphasis>header</emphasis> +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 +<emphasis>language</emphasis> +argument should be +<emphasis role="bold">C</emphasis> +or +<emphasis role="bold">C++</emphasis> +and selects the compiler to be used for the check; +the default is "C". +The optional +<emphasis>expect</emphasis> +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, +<emphasis role="bold">CheckTypeSize('short', expect = 2)</emphasis> +will return success only if short is two bytes.</para> + +<literallayout class="monospaced"> +</literallayout> + + </listitem> + </varlistentry> + <varlistentry> + <term>SConf.CheckDeclaration(<emphasis>context</emphasis>, <emphasis>symbol</emphasis>, [<emphasis>includes</emphasis>, <emphasis>language</emphasis>])</term> + <term><emphasis>sconf</emphasis>.CheckDeclaration(<emphasis>symbol</emphasis>, [<emphasis>includes</emphasis>, <emphasis>language</emphasis>])</term> + <listitem> +<para>Checks if the specified +<emphasis>symbol</emphasis> +is declared. +<emphasis>includes</emphasis> +is a string containing one or more +<emphasis role="bold">#include</emphasis> +lines that will be inserted into the program +that will be run to test for the existence of the type. +The optional +<emphasis>language</emphasis> +argument should be +<emphasis role="bold">C</emphasis> +or +<emphasis role="bold">C++</emphasis> +and selects the compiler to be used for the check; +the default is "C".</para> + + </listitem> + </varlistentry> + <varlistentry> + <term>SConf.Define(<emphasis>context</emphasis>, <emphasis>symbol</emphasis>, [<emphasis>value</emphasis>, <emphasis>comment</emphasis>])</term> + <term><emphasis>sconf</emphasis>.Define(<emphasis>symbol</emphasis>, [<emphasis>value</emphasis>, <emphasis>comment</emphasis>])</term> + <listitem> +<para>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 +<emphasis>name</emphasis> +with the optional +<emphasis role="bold">value</emphasis> +and the optional comment +<emphasis role="bold">comment</emphasis>.</para> + + </listitem> + </varlistentry> +</variablelist> + +<para>Examples:</para> + +<programlisting> +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) +</programlisting> + + +<para>Be careful about quoting string values, though:</para> + +<programlisting> +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"') +</programlisting> + + +<para>For comment:</para> + +<programlisting> +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') +</programlisting> + +<para>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 +<emphasis>__call__</emphasis> +method). +The first argument of the call is always a +<emphasis>CheckContext</emphasis> +instance followed by the arguments, +which must be supplied by the user of the check. +These CheckContext instances define the following methods:</para> + +<variablelist> + <varlistentry> + <term>CheckContext.Message(<emphasis>self</emphasis>, <emphasis>text</emphasis>)</term> + <listitem> + +<para>Usually called before the check is started. +<emphasis>text</emphasis> +will be displayed to the user, e.g. 'Checking for library X...'</para> + + </listitem> + </varlistentry> + <varlistentry> + <term>CheckContext.Result(<emphasis>self,</emphasis>, <emphasis>res</emphasis>)</term> + <listitem> + +<para>Usually called after the check is done. +<emphasis>res</emphasis> +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.</para> + + </listitem> + </varlistentry> + <varlistentry> + <term>CheckContext.TryCompile(<emphasis>self</emphasis>, <emphasis>text</emphasis>, <emphasis>extension</emphasis>)</term> + <listitem> +<para>Checks if a file with the specified +<emphasis>extension</emphasis> +(e.g. '.c') containing +<emphasis>text</emphasis> +can be compiled using the environment's +<emphasis role="bold">Object</emphasis> +builder. Returns 1 on success and 0 on failure.</para> + + </listitem> + </varlistentry> + <varlistentry> + <term>CheckContext.TryLink(<emphasis>self</emphasis>, <emphasis>text</emphasis>, <emphasis>extension</emphasis>)</term> + <listitem> +<para>Checks, if a file with the specified +<emphasis>extension</emphasis> +(e.g. '.c') containing +<emphasis>text</emphasis> +can be compiled using the environment's +<emphasis role="bold">Program</emphasis> +builder. Returns 1 on success and 0 on failure.</para> + + </listitem> + </varlistentry> + <varlistentry> + <term>CheckContext.TryRun(<emphasis>self</emphasis>, <emphasis>text</emphasis>, <emphasis>extension</emphasis>)</term> + <listitem> +<para>Checks, if a file with the specified +<emphasis>extension</emphasis> +(e.g. '.c') containing +<emphasis>text</emphasis> +can be compiled using the environment's +<emphasis role="bold">Program</emphasis> +builder. On success, the program is run. If the program +executes successfully +(that is, its return status is 0), +a tuple +<emphasis>(1, outputStr)</emphasis> +is returned, where +<emphasis>outputStr</emphasis> +is the standard output of the +program. +If the program fails execution +(its return status is non-zero), +then (0, '') is returned.</para> + + </listitem> + </varlistentry> + <varlistentry> + <term>CheckContext.TryAction(<emphasis>self</emphasis>, <emphasis>action</emphasis>, [<emphasis>text</emphasis>, <emphasis>extension</emphasis>])</term> + <listitem> +<para>Checks if the specified +<emphasis>action</emphasis> +with an optional source file (contents +<emphasis>text</emphasis> +, extension +<emphasis>extension</emphasis> += '' +) can be executed. +<emphasis>action</emphasis> +may be anything which can be converted to a +<command>scons</command> +Action. +On success, +<emphasis>(1, outputStr)</emphasis> +is returned, where +<emphasis>outputStr</emphasis> +is the content of the target file. +On failure +<emphasis>(0, '')</emphasis> +is returned.</para> + + </listitem> + </varlistentry> + <varlistentry> + <term>CheckContext.TryBuild(<emphasis>self</emphasis>, <emphasis>builder</emphasis>, [<emphasis>text</emphasis>, <emphasis>extension</emphasis>])</term> + <listitem> +<para>Low level implementation for testing specific builds; +the methods above are based on this method. +Given the Builder instance +<emphasis>builder</emphasis> +and the optional +<emphasis>text</emphasis> +of a source file with optional +<emphasis>extension</emphasis>, +this method returns 1 on success and 0 on failure. In addition, +<emphasis>self.lastTarget</emphasis> +is set to the build target node, if the build was successful.</para> + + </listitem> + </varlistentry> +</variablelist> +<para>Example for implementing and using custom tests:</para> + +<programlisting> +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() +</programlisting> + +</refsect2> + +<refsect2 id='commandline_construction_variables'><title>Command-Line Construction Variables</title> + +<para>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. +<command>scons</command> +provides a +<emphasis role="bold">Variables</emphasis> +object to support overriding construction variables +on the command line:</para> +<literallayout class="monospaced"> +$ scons VARIABLE=foo +</literallayout> +<para>The variable values can also be specified in a text-based SConscript file. +To create a Variables object, call the Variables() function:</para> + +<variablelist> + <varlistentry> + <term>Variables([<emphasis>files</emphasis>], [<emphasis>args</emphasis>])</term> + <listitem> +<para>This creates a Variables object that will read construction variables from +the file or list of filenames specified in +<emphasis>files</emphasis>. +If no files are specified, +or the +<emphasis>files</emphasis> +argument is +<emphasis role="bold">None</emphasis>, +then no files will be read. +The optional argument +<emphasis>args</emphasis> +is a dictionary of +values that will override anything read from the specified files; +it is primarily intended to be passed the +<emphasis role="bold">ARGUMENTS</emphasis> +dictionary that holds variables +specified on the command line. +Example:</para> + +<literallayout class="monospaced"> +vars = Variables('custom.py') +vars = Variables('overrides.py', ARGUMENTS) +vars = Variables(None, {FOO:'expansion', BAR:7}) +</literallayout> + +<para>Variables objects have the following methods:</para> + + </listitem> + </varlistentry> + <varlistentry> + <term>Add(<emphasis>key</emphasis>, [<emphasis>help</emphasis>, <emphasis>default</emphasis>, <emphasis>validator</emphasis>, <emphasis>converter</emphasis>])</term> + <listitem> +<para>This adds a customizable construction variable to the Variables object. +<emphasis>key</emphasis> +is the name of the variable. +<emphasis>help</emphasis> +is the help text for the variable. +<emphasis>default</emphasis> +is the default value of the variable; +if the default value is +<emphasis role="bold">None</emphasis> +and there is no explicit value specified, +the construction variable will +<emphasis>not</emphasis> +be added to the construction environment. +<emphasis>validator</emphasis> +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). +<emphasis>converter</emphasis> +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 +<emphasis>converter</emphasis> +must return a value, +which will be converted into a string +before being validated by the +<emphasis>validator</emphasis> +(if any) +and then added to the environment.</para> + +<para>Examples:</para> + +<programlisting> +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) +</programlisting> + + </listitem> + </varlistentry> + <varlistentry> + <term>AddVariables(<emphasis>list</emphasis>)</term> + <listitem> +<para>A wrapper script that adds +multiple customizable construction variables +to a Variables object. +<emphasis>list</emphasis> +is a list of tuple or list objects +that contain the arguments +for an individual call to the +<emphasis role="bold">Add</emphasis> +method.</para> + +<literallayout class="monospaced"> +opt.AddVariables( + ('debug', '', 0), + ('CC', 'The C compiler'), + ('VALIDATE', 'An option for testing validation', + 'notset', validator, None), + ) +</literallayout> + + </listitem> + </varlistentry> + <varlistentry> + <term>Update(<emphasis>env</emphasis>, [<emphasis>args</emphasis>])</term> + <listitem> +<para>This updates a construction environment +<emphasis>env</emphasis> +with the customized construction variables. +Any specified variables that are +<emphasis>not</emphasis> +configured for the Variables object +will be saved and may be +retrieved with the +<emphasis role="bold">UnknownVariables</emphasis>() +method, below.</para> + +<para>Normally this method is not called directly, +but is called indirectly by passing the Variables object to +the Environment() function:</para> + +<literallayout class="monospaced"> +env = Environment(variables=vars) +</literallayout> + + </listitem> + </varlistentry> +</variablelist> + +<para>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.</para> + +<para>Example:</para> + +<literallayout class="monospaced"> +CC = 'my_cc' +</literallayout> + +<variablelist> + <varlistentry> + <term>UnknownVariables(<emphasis>)</emphasis></term> + <listitem> +<para>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.</para> + +<literallayout class="monospaced"> +env = Environment(variables=vars) +for key, value in vars.UnknownVariables(): + print "unknown variable: %s=%s" % (key, value) +</literallayout> + + </listitem> + </varlistentry> + <varlistentry> + <term>Save(<emphasis>filename</emphasis>, <emphasis>env</emphasis>)</term> + <listitem> +<para>This saves the currently set variables into a script file named +<emphasis>filename</emphasis> +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.</para> + +<literallayout class="monospaced"> +env = Environment() +vars = Variables(['variables.cache', 'custom.py']) +vars.Add(...) +vars.Update(env) +vars.Save('variables.cache', env) +</literallayout> + + </listitem> + </varlistentry> + <varlistentry> + <term>GenerateHelpText(<emphasis>env</emphasis>, [<emphasis>sort</emphasis>])</term> + <listitem> +<para>This generates help text documenting the customizable construction +variables suitable to passing in to the Help() function. +<emphasis>env</emphasis> +is the construction environment that will be used to get the actual values +of customizable variables. Calling with +an optional +<emphasis>sort</emphasis> +function +will cause the output to be sorted +by the specified argument. +The specific +<emphasis>sort</emphasis> +function +should take two arguments +and return +-1, 0 or 1 +(like the standard Python +<emphasis>cmp</emphasis> +function).</para> + +<literallayout class="monospaced"> +Help(vars.GenerateHelpText(env)) +Help(vars.GenerateHelpText(env, sort=cmp)) +</literallayout> + + </listitem> + </varlistentry> + <varlistentry> + <term>FormatVariableHelpText(<emphasis>env</emphasis>, <emphasis>opt</emphasis>, <emphasis>help</emphasis>, <emphasis>default</emphasis>, <emphasis>actual</emphasis>)</term> + <listitem> +<para>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 +<emphasis>GenerateHelpText</emphasis>() +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 +<emphasis>GenerateHelpText</emphasis>() +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.</para> + +<programlisting> +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 +</programlisting> + +<para>To make it more convenient to work with customizable Variables, +<command>scons</command> +provides a number of functions +that make it easy to set up +various types of Variables:</para> + + </listitem> + </varlistentry> + <varlistentry> + <term>BoolVariable(<emphasis>key</emphasis>, <emphasis>help</emphasis>, <emphasis>default</emphasis>)</term> + <listitem> +<para>Return a tuple of arguments +to set up a Boolean option. +The option will use +the specified name +<emphasis>key</emphasis>, +have a default value of +<emphasis>default</emphasis>, +and display the specified +<emphasis>help</emphasis> +text. +The option will interpret the values +<emphasis role="bold">y</emphasis>, +<emphasis role="bold">yes</emphasis>, +<emphasis role="bold">t</emphasis>, +<emphasis role="bold">true</emphasis>, +<literal>1</literal>, +<emphasis role="bold">on</emphasis> +and +<emphasis role="bold">all</emphasis> +as true, +and the values +<emphasis role="bold">n</emphasis>, +<emphasis role="bold">no</emphasis>, +<emphasis role="bold">f</emphasis>, +<emphasis role="bold">false</emphasis>, +<literal>0</literal>, +<emphasis role="bold">off</emphasis> +and +<emphasis role="bold">none</emphasis> +as false.</para> + + </listitem> + </varlistentry> + <varlistentry> + <term>EnumVariable(<emphasis>key</emphasis>, <emphasis>help</emphasis>, <emphasis>default</emphasis>, <emphasis>allowed_values</emphasis>, [<emphasis>map</emphasis>, <emphasis>ignorecase</emphasis>])</term> + <listitem> +<para>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 +<emphasis>key</emphasis>, +have a default value of +<emphasis>default</emphasis>, +and display the specified +<emphasis>help</emphasis> +text. +The option will only support those +values in the +<emphasis>allowed_values</emphasis> +list. +The optional +<emphasis>map</emphasis> +argument is a dictionary +that can be used to convert +input values into specific legal values +in the +<emphasis>allowed_values</emphasis> +list. +If the value of +<emphasis>ignore_case</emphasis> +is +<literal>0</literal> +(the default), +then the values are case-sensitive. +If the value of +<emphasis>ignore_case</emphasis> +is +<literal>1</literal>, +then values will be matched +case-insensitive. +If the value of +<emphasis>ignore_case</emphasis> +is +<literal>2</literal>, +then values will be matched +case-insensitive, +and all input values will be +converted to lower case.</para> + + </listitem> + </varlistentry> + <varlistentry> + <term>ListVariable(<emphasis>key</emphasis>, <emphasis>help</emphasis>, <emphasis>default</emphasis>, <emphasis>names</emphasis>, [<emphasis>,</emphasis>map<emphasis>])</emphasis></term> + <listitem> +<para>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 +<emphasis>key</emphasis>, +have a default value of +<emphasis>default</emphasis>, +and display the specified +<emphasis>help</emphasis> +text. +The option will only support the values +<emphasis role="bold">all</emphasis>, +<emphasis role="bold">none</emphasis>, +or the values in the +<emphasis>names</emphasis> +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 +<emphasis>map</emphasis> +argument is a dictionary +that can be used to convert +input values into specific legal values +in the +<emphasis>names</emphasis> +list.</para> + + </listitem> + </varlistentry> + <varlistentry> + <term>PackageVariable(<emphasis>key</emphasis>, <emphasis>help</emphasis>, <emphasis>default</emphasis>)</term> + <listitem> +<para>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 +<emphasis>key</emphasis>, +have a default value of +<emphasis>default</emphasis>, +and display the specified +<emphasis>help</emphasis> +text. +The option will support the values +<emphasis role="bold">yes</emphasis>, +<emphasis role="bold">true</emphasis>, +<emphasis role="bold">on</emphasis>, +<emphasis role="bold">enable</emphasis> +or +<emphasis role="bold">search</emphasis>, +in which case the specified +<emphasis>default</emphasis> +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 +<emphasis role="bold">no</emphasis>, +<emphasis role="bold">false</emphasis>, +<emphasis role="bold">off</emphasis> +or +<emphasis role="bold">disable</emphasis> +to disable use of the specified option.</para> + + </listitem> + </varlistentry> + <varlistentry> + <term>PathVariable(<emphasis>key</emphasis>, <emphasis>help</emphasis>, <emphasis>default</emphasis>, [<emphasis>validator</emphasis>])</term> + <listitem> +<para>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 +<emphasis>key</emphasis>, +have a default value of +<emphasis>default</emphasis>, +and display the specified +<emphasis>help</emphasis> +text. +An additional +<emphasis>validator</emphasis> +may be specified +that will be called to +verify that the specified path +is acceptable. +SCons supplies the +following ready-made validators: +<emphasis role="bold">PathVariable.PathExists</emphasis> +(the default), +which verifies that the specified path exists; +<emphasis role="bold">PathVariable.PathIsFile</emphasis>, +which verifies that the specified path is an existing file; +<emphasis role="bold">PathVariable.PathIsDir</emphasis>, +which verifies that the specified path is an existing directory; +<emphasis role="bold">PathVariable.PathIsDirCreate</emphasis>, +which verifies that the specified path is a directory +and will create the specified directory if the path does not exist; +and +<emphasis role="bold">PathVariable.PathAccept</emphasis>, +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 +<emphasis>validator</emphasis> +function, +which must take three arguments +(<emphasis>key</emphasis>, +the name of the variable to be set; +<emphasis>val</emphasis>, +the specified value being checked; +and +<emphasis>env</emphasis>, +the construction environment) +and should raise an exception +if the specified value is not acceptable.</para> + + </listitem> + </varlistentry> +</variablelist> +<para>These functions make it +convenient to create a number +of variables with consistent behavior +in a single call to the +<emphasis role="bold">AddVariables</emphasis> +method:</para> + +<literallayout class="monospaced"> +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), + +) +</literallayout> + +</refsect2> + +<refsect2 id='file_and_directory_nodes'><title>File and Directory Nodes</title> + +<para>The +<emphasis>File</emphasis>() +and +<emphasis>Dir</emphasis>() +functions return +<emphasis>File</emphasis> +and +<emphasis>Dir</emphasis> +Nodes, respectively. +python objects, respectively. +Those objects have several user-visible attributes +and methods that are often useful:</para> + +<variablelist> + <varlistentry> + <term>path</term> + <listitem> +<para>The build path +of the given +file or directory. +This path is relative to the top-level directory +(where the +<emphasis role="bold">SConstruct</emphasis> +file is found). +The build path is the same as the source path if +<emphasis>variant_dir</emphasis> +is not being used.</para> + + </listitem> + </varlistentry> + <varlistentry> + <term>abspath</term> + <listitem> +<para>The absolute build path of the given file or directory.</para> + + </listitem> + </varlistentry> + <varlistentry> + <term>srcnode()</term> + <listitem> +<para>The +<emphasis>srcnode</emphasis>() +method +returns another +<emphasis>File</emphasis> +or +<emphasis>Dir</emphasis> +object representing the +<emphasis>source</emphasis> +path of the given +<emphasis>File</emphasis> +or +<emphasis>Dir</emphasis>. +The</para> + +<literallayout class="monospaced"> +# 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 +</literallayout> + +<para>A +<emphasis>Dir</emphasis> +Node or +<emphasis>File</emphasis> +Node can also be used to create +file and subdirectory Nodes relative to the generating Node. +A +<emphasis>Dir</emphasis> +Node will place the new Nodes within the directory it represents. +A +<emphasis>File</emphasis> +node will place the new Nodes within its parent directory +(that is, "beside" the file in question). +If +<emphasis>d</emphasis> +is a +<emphasis>Dir</emphasis> +(directory) Node and +<emphasis>f</emphasis> +is a +<emphasis>File</emphasis> +(file) Node, +then these methods are available:</para> + + </listitem> + </varlistentry> +</variablelist> +<variablelist> + <varlistentry> + <term><emphasis>d</emphasis>.Dir(<emphasis>name</emphasis>)</term> + <listitem> +<para>Returns a directory Node for a subdirectory of +<emphasis>d</emphasis> +named +<emphasis>name</emphasis>.</para> + + </listitem> + </varlistentry> + <varlistentry> + <term><emphasis>d</emphasis>.File(<emphasis>name</emphasis>)</term> + <listitem> +<para>Returns a file Node for a file within +<emphasis>d</emphasis> +named +<emphasis>name</emphasis>.</para> + + </listitem> + </varlistentry> + <varlistentry> + <term><emphasis>d</emphasis>.Entry(<emphasis>name</emphasis>)</term> + <listitem> +<para>Returns an unresolved Node within +<emphasis>d</emphasis> +named +<emphasis>name</emphasis>.</para> + + </listitem> + </varlistentry> + <varlistentry> + <term><emphasis>f</emphasis>.Dir(<emphasis>name</emphasis>)</term> + <listitem> +<para>Returns a directory named +<emphasis>name</emphasis> +within the parent directory of +<emphasis>f</emphasis>.</para> + + </listitem> + </varlistentry> + <varlistentry> + <term><emphasis>f</emphasis>.File(<emphasis>name</emphasis>)</term> + <listitem> +<para>Returns a file named +<emphasis>name</emphasis> +within the parent directory of +<emphasis>f</emphasis>.</para> + + </listitem> + </varlistentry> + <varlistentry> + <term><emphasis>f</emphasis>.Entry(<emphasis>name</emphasis>)</term> + <listitem> +<para>Returns an unresolved Node named +<emphasis>name</emphasis> +within the parent directory of +<emphasis>f</emphasis>.</para> + + </listitem> + </varlistentry> +</variablelist> +<para>For example:</para> + +<literallayout class="monospaced"> +# 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') +</literallayout> + +</refsect2> +</refsect1> + +<refsect1 id='extending_scons'><title>EXTENDING SCONS</title> + +<refsect2 id='builder_objects'><title>Builder Objects</title> +<para><command>scons</command> +can be extended to build different types of targets +by adding new Builder objects +to a construction environment. +<emphasis>In general</emphasis>, +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 +<command>scons</command> +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.).</para> + +<para>Builder objects are created +using the +<emphasis role="bold">Builder</emphasis> +function. +The +<emphasis role="bold">Builder</emphasis> +function accepts the following arguments:</para> + +<variablelist> + <varlistentry> + <term>action</term> + <listitem> +<para>The command line string used to build the target from the source. +<emphasis role="bold">action</emphasis> +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.</para> + +<para>An action function +takes three arguments: +<emphasis>source</emphasis> +- a list of source nodes, +<emphasis>target</emphasis> +- a list of target nodes, +<emphasis>env</emphasis> +- the construction environment.</para> + + </listitem> + </varlistentry> + <varlistentry> + <term>prefix</term> + <listitem> +<para>The prefix that will be prepended to the target file name. +This may be specified as a:</para> + + <blockquote> + +<para>* +<emphasis>string</emphasis>,</para> + + +<para>* +<emphasis>callable object</emphasis> +- a function or other callable that takes +two arguments (a construction environment and a list of sources) +and returns a prefix,</para> + + +<para>* +<emphasis>dictionary</emphasis> +- 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. + </para></blockquote> + </listitem> + </varlistentry> +</variablelist> + + +<programlisting> +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 }) +</programlisting> + +<variablelist> + <varlistentry> + <term>suffix</term> + <listitem> +<para>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 +<command>scons</command> +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.</para> + +<programlisting> +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 }) +</programlisting> + + </listitem> + </varlistentry> + <varlistentry> + <term>ensure_suffix</term> + <listitem> +<para>When set to any true value, causes +<command>scons</command> +to add the target suffix specified by the +<emphasis>suffix</emphasis> +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.)</para> + +<literallayout class="monospaced"> +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') +</literallayout> + + </listitem> + </varlistentry> + <varlistentry> + <term>src_suffix</term> + <listitem> +<para>The expected source file name suffix. This may be a string or a list +of strings.</para> + + </listitem> + </varlistentry> + <varlistentry> + <term>target_scanner</term> + <listitem> +<para>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, +<emphasis>not</emphasis> +for implicit dependencies based on source files. +(See the section "Scanner Objects" below, +for information about creating Scanner objects.)</para> + + </listitem> + </varlistentry> + <varlistentry> + <term>source_scanner</term> + <listitem> +<para>A Scanner object that +will be invoked to +find implicit dependencies in +any source files +used to build this target file. +This is where you would +specify a scanner to +find things like +<emphasis role="bold">#include</emphasis> +lines in source files. +The pre-built +<emphasis role="bold">DirScanner</emphasis> +Scanner object may be used to +indicate that this Builder +should scan directory trees +for on-disk changes to files +that +<command>scons</command> +does not know about from other Builder or function calls. +(See the section "Scanner Objects" below, +for information about creating your own Scanner objects.)</para> + + </listitem> + </varlistentry> + <varlistentry> + <term>target_factory</term> + <listitem> +<para>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 +<emphasis role="bold">Dir</emphasis>, +for when a Builder creates a directory target, +and +<emphasis role="bold">Entry</emphasis>, +for when a Builder can create either a file +or directory target.</para> + +<para>Example:</para> + +<literallayout class="monospaced"> +MakeDirectoryBuilder = Builder(action=my_mkdir, target_factory=Dir) +env = Environment() +env.Append(BUILDERS = {'MakeDirectory':MakeDirectoryBuilder}) +env.MakeDirectory('new_directory', []) +</literallayout> + + +<para>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.</para> + + </listitem> + </varlistentry> + <varlistentry> + <term>source_factory</term> + <listitem> +<para>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 +<emphasis role="bold">Dir</emphasis>, +for when a Builder uses a directory as a source, +and +<emphasis role="bold">Entry</emphasis>, +for when a Builder can use files +or directories (or both) as sources.</para> + +<para>Example:</para> + +<programlisting> +CollectBuilder = Builder(action=my_mkdir, source_factory=Entry) +env = Environment() +env.Append(BUILDERS = {'Collect':CollectBuilder}) +env.Collect('archive', ['directory_name', 'file_name']) +</programlisting> + + </listitem> + </varlistentry> + <varlistentry> + <term>emitter</term> + <listitem> +<para>A function or list of functions to manipulate the target and source +lists before dependencies are established +and the target(s) are actually built. +<emphasis role="bold">emitter</emphasis> +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.)</para> + +<para>An emitter function +takes three arguments: +<emphasis>source</emphasis> +- a list of source nodes, +<emphasis>target</emphasis> +- a list of target nodes, +<emphasis>env</emphasis> +- 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.</para> + +<para>Example:</para> + +<programlisting> +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}) +</programlisting> + + </listitem> + </varlistentry> + <varlistentry> + <term>multi</term> + <listitem> +<para>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.</para> + + </listitem> + </varlistentry> + <varlistentry> + <term>env</term> + <listitem> +<para>A construction environment that can be used +to fetch source code using this Builder. +(Note that this environment is +<emphasis>not</emphasis> +used for normal builds of normal target files, +which use the environment that was +used to call the Builder for the target file.)</para> + + </listitem> + </varlistentry> + <varlistentry> + <term>generator</term> + <listitem> +<para>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).</para> + +<para>The generator function +takes four arguments: +<emphasis>source</emphasis> +- a list of source nodes, +<emphasis>target</emphasis> +- a list of target nodes, +<emphasis>env</emphasis> +- the construction environment, +<emphasis>for_signature</emphasis> +- a Boolean value that specifies +whether the generator is being called +for generating a build signature +(as opposed to actually executing the command). +Example:</para> + +<programlisting> +def g(source, target, env, for_signature): + return [["gcc", "-c", "-o"] + target + source] + +b = Builder(generator=g) +</programlisting> + + +<para>The +<emphasis>generator</emphasis> +and +<emphasis>action</emphasis> +arguments must not both be used for the same Builder.</para> + + </listitem> + </varlistentry> + <varlistentry> + <term>src_builder</term> + <listitem> +<para>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.</para> + + </listitem> + </varlistentry> + <varlistentry> + <term>single_source</term> + <listitem> +<para>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.</para> + + </listitem> + </varlistentry> +</variablelist> + +<para>The +<emphasis>generator</emphasis> +and +<emphasis>action</emphasis> +arguments must not both be used for the same Builder.</para> + +<variablelist> + <varlistentry> + <term>source_ext_match</term> + <listitem> +<para>When the specified +<emphasis>action</emphasis> +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 +<emphasis role="bold">source_ext_match</emphasis> +to +<emphasis role="bold">None</emphasis> +or some other non-true value. +When +<emphasis role="bold">source_ext_match</emphasis> +is disable, +<command>scons</command> +will use the suffix of the first specified +source file to select the appropriate action from the +<emphasis>action</emphasis> +dictionary.</para> + +<para>In the following example, +the setting of +<emphasis role="bold">source_ext_match</emphasis> +prevents +<command>scons</command> +from exiting with an error +due to the mismatched suffixes of +<emphasis role="bold">foo.in</emphasis> +and +<emphasis role="bold">foo.extra</emphasis>.</para> + +<literallayout class="monospaced"> +b = Builder(action={'.in' : 'build $SOURCES > $TARGET'}, + source_ext_match = None) + +env = Environment(BUILDERS = {'MyBuild':b}) +env.MyBuild('foo.out', ['foo.in', 'foo.extra']) +</literallayout> + + </listitem> + </varlistentry> + <varlistentry> + <term>env</term> + <listitem> +<para>A construction environment that can be used +to fetch source code using this Builder. +(Note that this environment is +<emphasis>not</emphasis> +used for normal builds of normal target files, +which use the environment that was +used to call the Builder for the target file.)</para> + +<literallayout class="monospaced"> +b = Builder(action="build < $SOURCE > $TARGET") +env = Environment(BUILDERS = {'MyBuild' : b}) +env.MyBuild('foo.out', 'foo.in', my_arg = 'xyzzy') +</literallayout> + + </listitem> + </varlistentry> + <varlistentry> + <term>chdir</term> + <listitem> +<para>A directory from which scons +will execute the +action(s) specified +for this Builder. +If the +<emphasis role="bold">chdir</emphasis> +argument is +a string or a directory Node, +scons will change to the specified directory. +If the +<emphasis role="bold">chdir</emphasis> +is not a string or Node +and is non-zero, +then scons will change to the +target file's directory.</para> + +<para>Note that scons will +<emphasis>not</emphasis> +automatically modify +its expansion of +construction variables like +<emphasis role="bold">$TARGET</emphasis> +and +<emphasis role="bold">$SOURCE</emphasis> +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 +<emphasis role="bold">${TARGET.file}</emphasis> +and +<emphasis role="bold">${SOURCE.file}</emphasis> +to use just the filename portion of the +targets and source.</para> + +<literallayout class="monospaced"> +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') +</literallayout> + +<para><emphasis role="bold">WARNING:</emphasis> +Python only keeps one current directory +location for all of the threads. +This means that use of the +<emphasis role="bold">chdir</emphasis> +argument +will +<emphasis>not</emphasis> +work with the SCons +<option>-j</option> +option, +because individual worker threads spawned +by SCons interfere with each other +when they start changing directory.</para> + + </listitem> + </varlistentry> +</variablelist> +<para>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.</para> + +<para>Any additional keyword arguments supplied +when a Builder +<emphasis>object</emphasis> +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).</para> + +<para>These extra keyword arguments are passed to the +following functions: +command generator functions, +function Actions, +and emitter functions.</para> + +</refsect2> + +<refsect2 id='action_objects'><title>Action Objects</title> + +<para>The +<emphasis role="bold">Builder</emphasis>() +function will turn its +<emphasis role="bold">action</emphasis> +keyword argument into an appropriate +internal Action object. +You can also explicity create Action objects +using the +<emphasis role="bold">Action</emphasis>() +global function, +which can then be passed to the +<emphasis role="bold">Builder</emphasis>() +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.</para> + +<para>The +<emphasis role="bold">Action</emphasis>() +global function +returns an appropriate object for the action +represented by the type of the first argument:</para> + +<variablelist> + <varlistentry> + <term>Action</term> + <listitem> +<para>If the first argument is already an Action object, +the object is simply returned.</para> + + </listitem> + </varlistentry> + <varlistentry> + <term>String</term> + <listitem> +<para>If the first argument is a string, +a command-line Action is returned. +Note that the command-line string +may be preceded by an +<emphasis role="bold">@</emphasis> +(at-sign) +to suppress printing of the specified command line, +or by a +<emphasis role="bold">-</emphasis> +(hyphen) +to ignore the exit status from the specified command:</para> + +<literallayout class="monospaced"> +Action('$CC -c -o $TARGET $SOURCES') + +# Doesn't print the line being executed. +Action('@build $TARGET $SOURCES') + +# Ignores return value +Action('-build $TARGET $SOURCES') +</literallayout> +<!-- 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 :\-) --> + + </listitem> + </varlistentry> + <varlistentry> + <term>List</term> + <listitem> +<para>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 +<emphasis>within</emphasis> +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:</para> + +<literallayout class="monospaced"> +Action([['cc', '-c', '-DWHITE SPACE', '-o', '$TARGET', '$SOURCES']]) +</literallayout> + + </listitem> + </varlistentry> + <varlistentry> + <term>Function</term> + <listitem> +<para>If the first argument is a Python function, +a function Action is returned. +The Python function must take three keyword arguments, +<emphasis role="bold">target</emphasis> +(a Node object representing the target file), +<emphasis role="bold">source</emphasis> +(a Node object representing the source file) +and +<emphasis role="bold">env</emphasis> +(the construction environment +used for building the target file). +The +<emphasis role="bold">target</emphasis> +and +<emphasis role="bold">source</emphasis> +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:</para> + +<literallayout class="monospaced"> +target_file_name = str(target) +source_file_names = map(lambda x: str(x), source) +</literallayout> + +<para>The function should return +<literal>0</literal> +or +<emphasis role="bold">None</emphasis> +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.</para> + +<programlisting> +def build_it(target = None, source = None, env = None): + # build the target from the source + return 0 + +a = Action(build_it) +</programlisting> + +<para>If the action argument is not one of the above, +None is returned.</para> + </listitem> + </varlistentry> +</variablelist> + + +<para>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.</para> + +<para>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 +<emphasis>strfunction</emphasis>= +keyword argument. +Like a function to build a file, +this function must take three keyword arguments: +<emphasis role="bold">target</emphasis> +(a Node object representing the target file), +<emphasis role="bold">source</emphasis> +(a Node object representing the source file) +and +<emphasis role="bold">env</emphasis> +(a construction environment). +The +<emphasis role="bold">target</emphasis> +and +<emphasis role="bold">source</emphasis> +arguments may be lists of Node objects if there is +more than one target file or source file.</para> + +<para>In the second case, you provide the string itself. +The string may also be specified by the +<emphasis>cmdstr</emphasis>= +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.</para> + +<para>Examples:</para> + +<programlisting> +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') +</programlisting> + +<para>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 +<emphasis>varlist</emphasis>= +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.</para> + +<programlisting> +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']) +</programlisting> + +<para>The +<emphasis role="bold">Action</emphasis>() +global function +can be passed the following +optional keyword arguments +to modify the Action object's behavior:</para> + + +<para><emphasis role="bold">chdir</emphasis> +The +<emphasis role="bold">chdir</emphasis> +keyword argument specifies that +scons will execute the action +after changing to the specified directory. +If the +<emphasis role="bold">chdir</emphasis> +argument is +a string or a directory Node, +scons will change to the specified directory. +If the +<emphasis role="bold">chdir</emphasis> +argument +is not a string or Node +and is non-zero, +then scons will change to the +target file's directory.</para> + +<para>Note that scons will +<emphasis>not</emphasis> +automatically modify +its expansion of +construction variables like +<emphasis role="bold">$TARGET</emphasis> +and +<emphasis role="bold">$SOURCE</emphasis> +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 +<emphasis role="bold">${TARGET.file}</emphasis> +and +<emphasis role="bold">${SOURCE.file}</emphasis> +to use just the filename portion of the +targets and source.</para> + +<literallayout class="monospaced"> +a = Action("build < ${SOURCE.file} > ${TARGET.file}", + chdir=1) +</literallayout> + + +<para><emphasis role="bold">exitstatfunc</emphasis> +The +<emphasis role="bold">Action</emphasis>() +global function +also takes an +<emphasis role="bold">exitstatfunc</emphasis> +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:</para> + +<programlisting> +def always_succeed(s): + # Always return 0, which indicates success. + return 0 +a = Action("build < ${SOURCE.file} > ${TARGET.file}", + exitstatfunc=always_succeed) +</programlisting> + + +<para><emphasis role="bold">batch_key</emphasis> +The +<emphasis role="bold">batch_key</emphasis> +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 +<emphasis role="bold">batch_key</emphasis> +argument is any non-False, non-callable Python value, +the configured Action object will cause +<command>scons</command> +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 +<emphasis role="bold">CHANGED_SOURCES</emphasis> +construction variable +(and possibly +<emphasis role="bold">CHANGED_TARGETS</emphasis> +as well) +to only pass to the command line those sources that +have actually changed since their targets were built.</para> + +<para>Example:</para> + +<literallayout class="monospaced"> +a = Action('build $CHANGED_SOURCES', batch_key=True) +</literallayout> + +<para>The +<emphasis role="bold">batch_key</emphasis> +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 +<emphasis role="bold">batch_key</emphasis> +function must take the following arguments:</para> + +<variablelist> + <varlistentry> + <term>action</term> + <listitem> +<para>The action object.</para> + + </listitem> + </varlistentry> + <varlistentry> + <term>env</term> + <listitem> +<para>The construction environment +configured for the target.</para> + + </listitem> + </varlistentry> + <varlistentry> + <term>target</term> + <listitem> +<para>The list of targets for a particular configured action.</para> + + </listitem> + </varlistentry> + <varlistentry> + <term>source</term> + <listitem> +<para>The list of source for a particular configured action.</para> + +<para>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 +<emphasis role="bold">batch_key</emphasis> +function may decide to return +the value of a specific construction +variable from the +<emphasis role="bold">env</emphasis> +argument +which will cause +<command>scons</command> +to batch-build targets +with matching values of that variable, +or perhaps return the +<emphasis role="bold">id</emphasis>() +of the entire construction environment, +in which case +<command>scons</command> +will batch-build +all targets configured with the same construction environment. +Returning +<emphasis role="bold">None</emphasis> +indicates that +the particular target should +<emphasis>not</emphasis> +be part of any batched build, +but instead will be built +by a separate invocation of action's +command or function. +Example:</para> + +<programlisting> +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) +</programlisting> + + </listitem> + </varlistentry> +</variablelist> +</refsect2> + +<refsect2 id='miscellaneous_action_functions'><title>Miscellaneous Action Functions</title> + +<para><command>scons</command> +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 +<emphasis>Factory</emphasis> +functions +that return Action objects.)</para> + +<para>In practice, +there are two natural ways +that these +Action Functions +are intended to be used.</para> + +<para>First, +if you need +to perform the action +at the time the SConscript +file is being read, +you can use the +<emphasis role="bold">Execute</emphasis> +global function to do so:</para> +<literallayout class="monospaced"> +Execute(Touch('file')) +</literallayout> + +<para>Second, +you can use these functions +to supply Actions in a list +for use by the +<emphasis role="bold">Command</emphasis> +method. +This can allow you to +perform more complicated +sequences of file manipulation +without relying +on platform-specific +external commands: +that</para> +<literallayout class="monospaced"> +env = Environment(TMPBUILD = '/tmp/builddir') +env.Command('foo.out', 'foo.in', + [Mkdir('$TMPBUILD'), + Copy('$TMPBUILD', '${SOURCE.dir}'), + "cd $TMPBUILD && make", + Delete('$TMPBUILD')]) +</literallayout> + +<variablelist> + <varlistentry> + <term>Chmod(<emphasis>dest</emphasis>, <emphasis>mode</emphasis>)</term> + <listitem> +<para>Returns an Action object that +changes the permissions on the specified +<emphasis>dest</emphasis> +file or directory to the specified +<emphasis>mode</emphasis>. +Examples:</para> + +<literallayout class="monospaced"> +Execute(Chmod('file', 0755)) + +env.Command('foo.out', 'foo.in', + [Copy('$TARGET', '$SOURCE'), + Chmod('$TARGET', 0755)]) +</literallayout> + + </listitem> + </varlistentry> + <varlistentry> + <term>Copy(<emphasis>dest</emphasis>, <emphasis>src</emphasis>)</term> + <listitem> +<para>Returns an Action object +that will copy the +<emphasis>src</emphasis> +source file or directory to the +<emphasis>dest</emphasis> +destination file or directory. +Examples:</para> + +<literallayout class="monospaced"> +Execute(Copy('foo.output', 'foo.input')) + +env.Command('bar.out', 'bar.in', + Copy('$TARGET', '$SOURCE')) +</literallayout> + + </listitem> + </varlistentry> + <varlistentry> + <term>Delete(<emphasis>entry</emphasis>, [<emphasis>must_exist</emphasis>])</term> + <listitem> +<para>Returns an Action that +deletes the specified +<emphasis>entry</emphasis>, +which may be a file or a directory tree. +If a directory is specified, +the entire directory tree +will be removed. +If the +<emphasis>must_exist</emphasis> +flag is set, +then a Python error will be thrown +if the specified entry does not exist; +the default is +<emphasis role="bold">must_exist=0</emphasis>, +that is, the Action will silently do nothing +if the entry does not exist. +Examples:</para> + +<literallayout class="monospaced"> +Execute(Delete('/tmp/buildroot')) + +env.Command('foo.out', 'foo.in', + [Delete('${TARGET.dir}'), + MyBuildAction]) + +Execute(Delete('file_that_must_exist', must_exist=1)) +</literallayout> + + </listitem> + </varlistentry> + <varlistentry> + <term>Mkdir(<emphasis>dir</emphasis>)</term> + <listitem> +<para>Returns an Action +that creates the specified +directory +<emphasis>dir .</emphasis> +Examples:</para> + +<literallayout class="monospaced"> +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')]) +</literallayout> + + </listitem> + </varlistentry> + <varlistentry> + <term>Move(<emphasis>dest</emphasis>, <emphasis>src</emphasis>)</term> + <listitem> +<para>Returns an Action +that moves the specified +<emphasis>src</emphasis> +file or directory to +the specified +<emphasis>dest</emphasis> +file or directory. +Examples:</para> + +<literallayout class="monospaced"> +Execute(Move('file.destination', 'file.source')) + +env.Command('output_file', 'input_file', + [MyBuildAction, + Move('$TARGET', 'file_created_by_MyBuildAction')]) +</literallayout> + + </listitem> + </varlistentry> + <varlistentry> + <term>Touch(<emphasis>file</emphasis>)</term> + <listitem> +<para>Returns an Action +that updates the modification time +on the specified +<emphasis>file</emphasis>. +Examples:</para> + +<literallayout class="monospaced"> +Execute(Touch('file_to_be_touched')) + +env.Command('marker', 'input_file', + [MyBuildAction, + Touch('$TARGET')]) +</literallayout> + + </listitem> + </varlistentry> +</variablelist> +</refsect2> + +<refsect2 id='variable_substitution'><title>Variable Substitution</title> + +<para>Before executing a command, +<command>scons</command> +performs construction variable interpolation on the strings that make up +the command line of builders. +Variables are introduced by a +<emphasis role="bold">$</emphasis> +prefix. +Besides construction variables, scons provides the following +variables for each command execution:</para> + +<variablelist> + <varlistentry> + <term>CHANGED_SOURCES</term> + <listitem> +<para>The file names of all sources of the build command +that have changed since the target was last built.</para> + + </listitem> + </varlistentry> + <varlistentry> + <term>CHANGED_TARGETS</term> + <listitem> +<para>The file names of all targets that would be built +from sources that have changed since the target was last built.</para> + + </listitem> + </varlistentry> + <varlistentry> + <term>SOURCE</term> + <listitem> +<para>The file name of the source of the build command, +or the file name of the first source +if multiple sources are being built.</para> + + </listitem> + </varlistentry> + <varlistentry> + <term>SOURCES</term> + <listitem> +<para>The file names of the sources of the build command.</para> + + </listitem> + </varlistentry> + <varlistentry> + <term>TARGET</term> + <listitem> +<para>The file name of the target being built, +or the file name of the first target +if multiple targets are being built.</para> + + </listitem> + </varlistentry> + <varlistentry> + <term>TARGETS</term> + <listitem> +<para>The file names of all targets being built.</para> + + </listitem> + </varlistentry> + <varlistentry> + <term>UNCHANGED_SOURCES</term> + <listitem> +<para>The file names of all sources of the build command +that have +<emphasis>not</emphasis> +changed since the target was last built.</para> + + </listitem> + </varlistentry> + <varlistentry> + <term>UNCHANGED_TARGETS</term> + <listitem> +<para>The file names of all targets that would be built +from sources that have +<emphasis>not</emphasis> +changed since the target was last built.</para> + +<para>(Note that the above variables are reserved +and may not be set in a construction environment.)</para> + + </listitem> + </varlistentry> +</variablelist> + +<para>For example, given the construction variable CC='cc', targets=['foo'], and +sources=['foo.c', 'bar.c']:</para> + +<literallayout class="monospaced"> +action='$CC -c -o $TARGET $SOURCES' +</literallayout> + +<para>would produce the command line:</para> + +<literallayout class="monospaced"> +cc -c -o foo foo.c bar.c +</literallayout> + +<para>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:</para> + +<literallayout class="monospaced"> +${SOURCES[1]} +</literallayout> + +<para>would produce:</para> + +<literallayout class="monospaced"> +bar.c +</literallayout> + +<para>Additionally, a variable name may +have the following special +modifiers appended within the enclosing curly braces +to modify the interpolated string:</para> + +<variablelist> + <varlistentry> + <term>base</term> + <listitem> +<para>The base path of the file name, +including the directory path +but excluding any suffix.</para> + + </listitem> + </varlistentry> + <varlistentry> + <term>dir</term> + <listitem> +<para>The name of the directory in which the file exists.</para> + + </listitem> + </varlistentry> + <varlistentry> + <term>file</term> + <listitem> +<para>The file name, +minus any directory portion.</para> + + </listitem> + </varlistentry> + <varlistentry> + <term>filebase</term> + <listitem> +<para>Just the basename of the file, +minus any suffix +and minus the directory.</para> + + </listitem> + </varlistentry> + <varlistentry> + <term>suffix</term> + <listitem> +<para>Just the file suffix.</para> + + </listitem> + </varlistentry> + <varlistentry> + <term>abspath</term> + <listitem> +<para>The absolute path name of the file.</para> + + </listitem> + </varlistentry> + <varlistentry> + <term>posix</term> + <listitem> +<para>The POSIX form of the path, +with directories separated by +<emphasis role="bold">/</emphasis> +(forward slashes) +not backslashes. +This is sometimes necessary on Windows systems +when a path references a file on other (POSIX) systems.</para> + + </listitem> + </varlistentry> + <varlistentry> + <term>srcpath</term> + <listitem> +<para>The directory and file name to the source file linked to this file through +<emphasis role="bold">VariantDir</emphasis>(). +If this file isn't linked, +it just returns the directory and filename unchanged.</para> + + </listitem> + </varlistentry> + <varlistentry> + <term>srcdir</term> + <listitem> +<para>The directory containing the source file linked to this file through +<emphasis role="bold">VariantDir</emphasis>(). +If this file isn't linked, +it just returns the directory part of the filename.</para> + + </listitem> + </varlistentry> + <varlistentry> + <term>rsrcpath</term> + <listitem> +<para>The directory and file name to the source file linked to this file through +<emphasis role="bold">VariantDir</emphasis>(). +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.</para> + + </listitem> + </varlistentry> + <varlistentry> + <term>rsrcdir</term> + <listitem> +<para>The Repository directory containing the source file linked to this file through +<emphasis role="bold">VariantDir</emphasis>(). +If this file isn't linked, +it just returns the directory part of the filename.</para> + + </listitem> + </varlistentry> +</variablelist> + +<para>For example, the specified target will +expand as follows for the corresponding modifiers:</para> + +<literallayout class="monospaced"> +$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 +</literallayout> + +<para>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.</para> + +<para>Lastly, a variable name +may be a callable Python function +associated with a +construction variable in the environment. +The function should +take four arguments: +<emphasis>target</emphasis> +- a list of target nodes, +<emphasis>source</emphasis> +- a list of source nodes, +<emphasis>env</emphasis> +- the construction environment, +<emphasis>for_signature</emphasis> +- 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:</para> + +<programlisting> +def foo(target, source, env, for_signature): + return "bar" + +# Will expand $BAR to "bar baz" +env=Environment(FOO=foo, BAR="$FOO baz") +</programlisting> + +<para>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 +<function>__call__()</function> +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:</para> + +<literallayout class="monospaced"> +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") +</literallayout> + + +<para>The special pseudo-variables +<emphasis role="bold">$(</emphasis> +and +<emphasis role="bold">$)</emphasis> +may be used to surround parts of a command line +that may change +<emphasis>without</emphasis> +causing a rebuild--that is, +which are not included in the signature +of target files built with this command. +All text between +<emphasis role="bold">$(</emphasis> +and +<emphasis role="bold">$)</emphasis> +will be removed from the command line +before it is added to file signatures, +and the +<emphasis role="bold">$(</emphasis> +and +<emphasis role="bold">$)</emphasis> +will be removed before the command is executed. +For example, the command line:</para> + +<literallayout class="monospaced"> +echo Last build occurred $( $TODAY $). > $TARGET +</literallayout> + + +<para>would execute the command:</para> + +<literallayout class="monospaced"> +echo Last build occurred $TODAY. > $TARGET +</literallayout> + + +<para>but the command signature added to any target files would be:</para> + +<literallayout class="monospaced"> +echo Last build occurred . > $TARGET +</literallayout> + +</refsect2> + +<refsect2 id='python_code_substitution'><title>Python Code Substitution</title> + +<para>Any python code within +<emphasis role="bold">${</emphasis>-<emphasis role="bold">}</emphasis> +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:</para> +<literallayout class="monospaced"> +env['COND'] = 0 +env.Command('foo.out', 'foo.in', +<!-- '''echo ${COND==1 and 'FOO' or 'BAR'} > $TARGET''') --> +</literallayout> +<para>the command executed will be either</para> +<literallayout class="monospaced"> +echo FOO > foo.out +</literallayout> +<para>or</para> +<literallayout class="monospaced"> +echo BAR > foo.out +</literallayout> +<para>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.</para> + +<para>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.</para> + +<literallayout class="monospaced"> +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 +</literallayout> + +<para>SCons uses the following rules when converting construction variables into +command lines:</para> + +<variablelist> + <varlistentry> + <term>String</term> + <listitem> +<para>When the value is a string it is interpreted as a space delimited list of +command line arguments.</para> + + </listitem> + </varlistentry> + <varlistentry> + <term>List</term> + <listitem> +<para>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.</para> + + </listitem> + </varlistentry> + <varlistentry> + <term>Other</term> + <listitem> +<para>Anything that is not a list or string is converted to a string and +interpreted as a single command line argument.</para> + + </listitem> + </varlistentry> + <varlistentry> + <term>Newline</term> + <listitem> +<para>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.</para> + + </listitem> + </varlistentry> +</variablelist> +</refsect2> + +<refsect2 id='scanner_objects'><title>Scanner Objects</title> + +<para>You can use the +<emphasis role="bold">Scanner</emphasis> +function to define +objects to scan +new file types for implicit dependencies. +The +<emphasis role="bold">Scanner</emphasis> +function accepts the following arguments:</para> + +<variablelist> + <varlistentry> + <term>function</term> + <listitem> +<para>This can be either: +1) a Python function that will process +the Node (file) +and return a list of File Nodes +representing the implicit +dependencies (file names) found in the contents; +or: +2) a dictionary that maps keys +(typically the file suffix, but see below for more discussion) +to other Scanners that should be called.</para> + +<para>If the argument is actually a Python function, +the function must take three or four arguments:</para> + +<para> def scanner_function(node, env, path):</para> + +<para> def scanner_function(node, env, path, arg=None):</para> + +<para>The +<emphasis role="bold">node</emphasis> +argument is the internal +SCons node representing the file. +Use +<emphasis role="bold">str(node)</emphasis> +to fetch the name of the file, and +<emphasis role="bold">node.get_contents()</emphasis> +to fetch contents of the file. +Note that the file is +<emphasis>not</emphasis> +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).</para> + +<para>The +<emphasis role="bold">env</emphasis> +argument is the construction environment for the scan. +Fetch values from it using the +<emphasis role="bold">env.Dictionary()</emphasis> +method.</para> + +<para>The +<emphasis role="bold">path</emphasis> +argument is a tuple (or list) +of directories that can be searched +for files. +This will usually be the tuple returned by the +<emphasis role="bold">path_function</emphasis> +argument (see below).</para> + +<para>The +<emphasis role="bold">arg</emphasis> +argument is the argument supplied +when the scanner was created, if any.</para> + + </listitem> + </varlistentry> + <varlistentry> + <term>name</term> + <listitem> +<para>The name of the Scanner. +This is mainly used +to identify the Scanner internally.</para> + + </listitem> + </varlistentry> + <varlistentry> + <term>argument</term> + <listitem> +<para>An optional argument that, if specified, +will be passed to the scanner function +(described above) +and the path function +(specified below).</para> + + </listitem> + </varlistentry> + <varlistentry> + <term>skeys</term> + <listitem> +<para>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.</para> + + </listitem> + </varlistentry> + <varlistentry> + <term>path_function</term> + <listitem> +<para>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 +<emphasis role="bold">path_function</emphasis> +returns a tuple of directories +that can be searched for files to be returned +by this Scanner object. +(Note that the +<emphasis role="bold">FindPathDirs</emphasis>() +function can be used to return a ready-made +<emphasis role="bold">path_function</emphasis> +for a given construction variable name, +instead of having to write your own function from scratch.)</para> + + </listitem> + </varlistentry> + <varlistentry> + <term>node_class</term> + <listitem> +<para>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 +<emphasis role="bold">node_factory</emphasis> +function.</para> + + </listitem> + </varlistentry> + <varlistentry> + <term>node_factory</term> + <listitem> +<para>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.</para> + + </listitem> + </varlistentry> + <varlistentry> + <term>scan_check</term> + <listitem> +<para>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.</para> + + </listitem> + </varlistentry> + <varlistentry> + <term>recursive</term> + <listitem> +<para>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. +<emphasis>recursive</emphasis> +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.</para> + + </listitem> + </varlistentry> +</variablelist> +<para>Note that +<command>scons</command> +has a global +<emphasis role="bold">SourceFileScanner</emphasis> +object that is used by +the +<emphasis role="bold">Object</emphasis>(), +<emphasis role="bold">SharedObject</emphasis>(), +and +<emphasis role="bold">StaticObject</emphasis>() +builders to decide +which scanner should be used +for different file extensions. +You can using the +<emphasis role="bold">SourceFileScanner.add_scanner</emphasis>() +method to add your own Scanner object +to the +<command>scons</command> +infrastructure +that builds target programs or +libraries from a list of +source files of different types:</para> + +<programlisting> +def xyz_scan(node, env, path): + contents = node.get_text_contents() + # Scan the contents and return the included files. + +XYZScanner = Scanner(xyz_scan) + +SourceFileScanner.add_scanner('.xyz', XYZScanner) + +env.Program('my_prog', ['file1.c', 'file2.f', 'file3.xyz']) +</programlisting> + +</refsect2> +</refsect1> + +<refsect1 id='systemspecific_behavior'><title>SYSTEM-SPECIFIC BEHAVIOR</title> +<para>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.</para> + +<refsect2 id='c_file_suffix'><title>.C file suffix</title> +<para>SCons handles the upper-case +<markup>.C</markup> +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 +<markup>.C</markup> +suffix as a C++ source file. +On a case-insensitive system +such as Windows, +SCons treats a file with a +<markup>.C</markup> +suffix as a C source file.</para> +</refsect2> + +<refsect2 id='f_file_suffix'><title>.F file suffix</title> +<para>SCons handles the upper-case +<markup>.F</markup> +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 +<markup>.F</markup> +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 +<markup>.F</markup> +suffix as a Fortran source file that should +<emphasis>not</emphasis> +be run through the C preprocessor.</para> +</refsect2> + +<refsect2 id='windows_cygwin_tools_and_cygwin_python_v'><title>Windows: Cygwin Tools and Cygwin Python vs. Windows Pythons</title> +<para>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).</para> + +<para>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.</para> + +<para>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.</para> +</refsect2> + +<refsect2 id='windows_sconsbat_file'><title>Windows: scons.bat file</title> +<para>On Windows systems, +SCons is executed via a wrapper +<emphasis role="bold">scons.bat</emphasis> +file. +This has (at least) two ramifications:</para> + +<para>First, Windows command-line users +that want to use variable assignment +on the command line +may have to put double quotes +around the assignments:</para> + +<literallayout class="monospaced"> +scons "FOO=BAR" "BAZ=BLEH" +</literallayout> + +<para>Second, the Cygwin shell does not +recognize this file as being the same +as an +<command>scons</command> +command issued at the command-line prompt. +You can work around this either by +executing +<emphasis role="bold">scons.bat</emphasis> +from the Cygwin command line, +or by creating a wrapper shell +script named +<emphasis role="bold">scons .</emphasis></para> + +</refsect2> + +<refsect2 id='mingw'><title>MinGW</title> + +<para>The MinGW bin directory must be in your PATH environment variable or the +PATH variable under the ENV construction variable for SCons +to detect and use the MinGW tools. When running under the native Windows +Python interpreter, SCons will prefer the MinGW tools over the Cygwin +tools, if they are both installed, regardless of the order of the bin +directories in the PATH variable. If you have both MSVC and MinGW +installed and you want to use MinGW instead of MSVC, +then you must explicitly tell SCons to use MinGW by passing</para> + +<literallayout class="monospaced"> +tools=['mingw'] +</literallayout> + +<para>to the Environment() function, because SCons will prefer the MSVC tools +over the MinGW tools.</para> + +</refsect2> +</refsect1> + +<refsect1 id='examples'><title>EXAMPLES</title> +<para>To help you get started using SCons, +this section contains a brief overview of some common tasks.</para> + + +<refsect2 id='basic_compilation_from_a_single_source_f'><title>Basic Compilation From a Single Source File</title> + +<literallayout class="monospaced"> +env = Environment() +env.Program(target = 'foo', source = 'foo.c') +</literallayout> + +<para>Note: Build the file by specifying +the target as an argument +("scons foo" or "scons foo.exe"). +or by specifying a dot ("scons .").</para> + +</refsect2> + +<refsect2 id='basic_compilation_from_multiple_source_f'><title>Basic Compilation From Multiple Source Files</title> + +<literallayout class="monospaced"> +env = Environment() +env.Program(target = 'foo', source = Split('f1.c f2.c f3.c')) +</literallayout> + +</refsect2> + +<refsect2 id='setting_a_compilation_flag'><title>Setting a Compilation Flag</title> + +<literallayout class="monospaced"> +env = Environment(CCFLAGS = '-g') +env.Program(target = 'foo', source = 'foo.c') +</literallayout> + +</refsect2> + +<refsect2 id='search_the_local_directory_for_h_files'><title>Search The Local Directory For .h Files</title> + +<para>Note: You do +<emphasis>not</emphasis> +need to set CCFLAGS to specify -I options by hand. +SCons will construct the right -I options from CPPPATH.</para> + +<literallayout class="monospaced"> +env = Environment(CPPPATH = ['.']) +env.Program(target = 'foo', source = 'foo.c') +</literallayout> + +</refsect2> + +<refsect2 id='search_multiple_directories_for_h_files'><title>Search Multiple Directories For .h Files</title> + +<literallayout class="monospaced"> +env = Environment(CPPPATH = ['include1', 'include2']) +env.Program(target = 'foo', source = 'foo.c') +</literallayout> + +</refsect2> + +<refsect2 id='building_a_static_library'><title>Building a Static Library</title> + +<literallayout class="monospaced"> +env = Environment() +env.StaticLibrary(target = 'foo', source = Split('l1.c l2.c')) +env.StaticLibrary(target = 'bar', source = ['l3.c', 'l4.c']) +</literallayout> + +</refsect2> + +<refsect2 id='building_a_shared_library'><title>Building a Shared Library</title> + +<literallayout class="monospaced"> +env = Environment() +env.SharedLibrary(target = 'foo', source = ['l5.c', 'l6.c']) +env.SharedLibrary(target = 'bar', source = Split('l7.c l8.c')) +</literallayout> + +</refsect2> + +<refsect2 id='linking_a_local_library_into_a_program'><title>Linking a Local Library Into a Program</title> + +<literallayout class="monospaced"> +env = Environment(LIBS = 'mylib', LIBPATH = ['.']) +env.Library(target = 'mylib', source = Split('l1.c l2.c')) +env.Program(target = 'prog', source = ['p1.c', 'p2.c']) +</literallayout> + +</refsect2> + +<refsect2 id='defining_your_own_builder_object'><title>Defining Your Own Builder Object</title> + +<para>Notice that when you invoke the Builder, +you can leave off the target file suffix, +and SCons will add it automatically.</para> + +<literallayout class="monospaced"> +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') +</literallayout> + +<para>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.</para> + +</refsect2> + +<refsect2 id='adding_your_own_builder_object_to_an_env'><title>Adding Your Own Builder Object to an Environment</title> + +<literallayout class="monospaced"> +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') +</literallayout> + +<para>You also can use other Pythonic techniques to add +to the BUILDERS construction variable, such as:</para> + +<literallayout class="monospaced"> +env = Environment() +env['BUILDERS]['PDFBuilder'] = bld +</literallayout> + +</refsect2> + +<refsect2 id='defining_your_own_scanner_object'><title>Defining Your Own Scanner Object</title> + +<para>The following example shows an extremely simple scanner (the +<emphasis role="bold">kfile_scan</emphasis>() +function) +that doesn't use a search path at all +and simply returns the +file names present on any +<emphasis role="bold">include</emphasis> +lines in the scanned file. +This would implicitly assume that all included +files live in the top-level directory:</para> + +<literallayout class="monospaced"> +import re + +include_re = re.compile(r'^include\s+(\S+)$', re.M) + +def kfile_scan(node, env, path, arg): + contents = node.get_text_contents() + includes = include_re.findall(contents) + return env.File(includes) + +kscan = Scanner(name = 'kfile', + function = kfile_scan, + argument = None, + skeys = ['.k']) +scanners = Environment().Dictionary('SCANNERS') +env = Environment(SCANNERS = scanners + [kscan]) + +env.Command('foo', 'foo.k', 'kprocess < $SOURCES > $TARGET') + +bar_in = File('bar.in') +env.Command('bar', bar_in, 'kprocess $SOURCES > $TARGET') +bar_in.target_scanner = kscan +</literallayout> + +<para>It is important to note that you +have to return a list of File nodes from the scan function, simple +strings for the file names won't do. As in the examples we are showing here, +you can use the +<emphasis role="bold">File()</emphasis> +function of your current Environment in order to create nodes on the fly from +a sequence of file names with relative paths.</para> + +<para>Here is a similar but more complete example that searches +a path of directories +(specified as the +<emphasis role="bold">MYPATH</emphasis> +construction variable) +for files that actually exist:</para> + +<programlisting> +import re +import os +include_re = re.compile(r'^include\s+(\S+)$', re.M) + +def my_scan(node, env, path, arg): + contents = node.get_text_contents() + includes = include_re.findall(contents) + if includes == []: + return [] + results = [] + for inc in includes: + for dir in path: + file = str(dir) + os.sep + inc + if os.path.exists(file): + results.append(file) + break + return env.File(results) + +scanner = Scanner(name = 'myscanner', + function = my_scan, + argument = None, + skeys = ['.x'], + path_function = FindPathDirs('MYPATH') + ) +scanners = Environment().Dictionary('SCANNERS') +env = Environment(SCANNERS = scanners + [scanner], + MYPATH = ['incs']) + +env.Command('foo', 'foo.x', 'xprocess < $SOURCES > $TARGET') +</programlisting> + +<para>The +<emphasis role="bold">FindPathDirs</emphasis>() +function used in the previous example returns a function +(actually a callable Python object) +that will return a list of directories +specified in the +<emphasis role="bold">$MYPATH</emphasis> +construction variable. It lets SCons detect the file +<emphasis role="bold">incs/foo.inc</emphasis> +, even if +<emphasis role="bold">foo.x</emphasis> +contains the line +<emphasis role="bold">include foo.inc</emphasis> +only. +If you need to customize how the search path is derived, +you would provide your own +<emphasis role="bold">path_function</emphasis> +argument when creating the Scanner object, +as follows:</para> + +<programlisting> +# 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 + ) +</programlisting> + +</refsect2> + +<refsect2 id='creating_a_hierarchical_build'><title>Creating a Hierarchical Build</title> + +<para>Notice that the file names specified in a subdirectory's +SConscript +file are relative to that subdirectory.</para> + +<programlisting> +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') +</programlisting> + +</refsect2> + +<refsect2 id='sharing_variables_between_sconscript_fil'><title>Sharing Variables Between SConscript Files</title> + +<para>You must explicitly Export() and Import() variables that +you want to share between SConscript files.</para> + +<programlisting> +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') +</programlisting> + +</refsect2> + +<refsect2 id='building_multiple_variants_from_the_same'><title>Building Multiple Variants From the Same Source</title> + +<para>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:</para> + +<programlisting> +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') +</programlisting> + +<para>Note the use of the Export() method +to set the "cppdefines" variable to a different +value each time we call the SConscript function.</para> + +</refsect2> + +<refsect2 id='hierarchical_build_of_two_libraries_link'><title>Hierarchical Build of Two Libraries Linked With a Program</title> + +<programlisting> +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')) +</programlisting> + +<para>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.</para> + +<para>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).</para> + +</refsect2> + +<refsect2 id='customizing_construction_variables_from_'><title>Customizing construction variables from the command line.</title> + +<para>The following would allow the C compiler to be specified on the command +line or in the file custom.py.</para> + +<literallayout class="monospaced"> +vars = Variables('custom.py') +vars.Add('CC', 'The C compiler.') +env = Environment(variables=vars) +Help(vars.GenerateHelpText(env)) +</literallayout> + +<para>The user could specify the C compiler on the command line:</para> + +<literallayout class="monospaced"> +scons "CC=my_cc" +</literallayout> + +<para>or in the custom.py file:</para> + +<literallayout class="monospaced"> +CC = 'my_cc' +</literallayout> + +<para>or get documentation on the options:</para> + +<literallayout class="monospaced"> +$ scons -h + +CC: The C compiler. + default: None + actual: cc + +</literallayout> + +</refsect2> + +<refsect2 id='using_microsoft_visual_c_precompiled_hea'><title>Using Microsoft Visual C++ precompiled headers</title> + +<para>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:</para> + +<para>StdAfx.h:</para> +<literallayout class="monospaced"> +#include <windows.h> +#include <my_big_header.h> +</literallayout> + +<para>StdAfx.cpp:</para> +<literallayout class="monospaced"> +#include <StdAfx.h> +</literallayout> + +<para>Foo.cpp:</para> +<literallayout class="monospaced"> +#include <StdAfx.h> + +/* do some stuff */ +</literallayout> + +<para>Bar.cpp:</para> +<literallayout class="monospaced"> +#include <StdAfx.h> + +/* do some other stuff */ +</literallayout> + +<para>SConstruct:</para> +<literallayout class="monospaced"> +env=Environment() +env['PCHSTOP'] = 'StdAfx.h' +env['PCH'] = env.PCH('StdAfx.cpp')[0] +env.Program('MyApp', ['Foo.cpp', 'Bar.cpp']) +</literallayout> + +<para>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.</para> + +</refsect2> + +<refsect2 id='using_microsoft_visual_c_external_debugg'><title>Using Microsoft Visual C++ external debugging information</title> + +<para>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.</para> + +<para>SConstruct:</para> +<literallayout class="monospaced"> +env=Environment() +env['PDB'] = 'MyApp.pdb' +env.Program('MyApp', ['Foo.cpp', 'Bar.cpp']) +</literallayout> + +<para>For more information see the document for the PDB construction variable.</para> + +</refsect2> +</refsect1> + +<refsect1 id='environment'><title>ENVIRONMENT</title> +<variablelist> + <varlistentry> + <term>SCONS_LIB_DIR</term> + <listitem> +<para>Specifies the directory that contains the SCons Python module directory +(e.g. /home/aroach/scons-src-0.01/src/engine).</para> + + </listitem> + </varlistentry> + <varlistentry> + <term>SCONSFLAGS</term> + <listitem> +<para>A string of options that will be used by scons in addition to those passed +on the command line.</para> + + </listitem> + </varlistentry> +</variablelist> +</refsect1> + +<refsect1 id='see_also'><title>SEE ALSO</title> +<para><command>scons</command> +User Manual, +<command>scons</command> +Design Document, +<command>scons</command> +source code.</para> + +</refsect1> + +<refsect1 id='authors'><title>AUTHORS</title> +<para>Steven Knight <knight@baldmt.com> +<!-- .br --> +Anthony Roach <aroach@electriceyeball.com></para> +</refsect1> +</refentry> +</reference> |