File: scons.xml

package info (click to toggle)
scons-doc 2.5.1%2Brepack-1
links: PTS, VCS
area: main
in suites: stretch
size: 37,000 kB
ctags: 8,642
sloc: xml: 195,697; python: 60,955; sh: 1,391; ruby: 229; perl: 124; makefile: 68; cpp: 2
file content (7121 lines) | stat: -rw-r--r-- 216,056 bytes
<?xml version="1.0" encoding="UTF-8"?>
<!--

  Copyright (c) 2001 - 2016 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.

-->

<!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 http://www.scons.org/dbxsd/v1.0/scons.xsd">

  <referenceinfo>
    <title>SCons &buildversion;</title>
    <subtitle>MAN page</subtitle>

    <author>
      <firstname>Steven</firstname>
      <surname>Knight</surname>
    </author>

    <corpauthor>Steven Knight and the SCons Development Team</corpauthor>

    <pubdate>2004 - 2016</pubdate>

    <copyright>
      <year>2004 - 2016</year>
      <holder>The SCons Foundation</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'>SCons 2.5.1</refmiscinfo>
<refmiscinfo class='manual'>SCons 2.5.1</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.7 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&gt;&gt;&gt;</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&gt;&gt;&gt; build -n prog
scons&gt;&gt;&gt; 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-version, --warn=no-cache-version</term>
  <listitem>
<para>Enables or disables warnings about the cache directory not using
the latest configuration information
<emphasis role="bold">CacheDir</emphasis>().
These warnings are enabled by default.</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 &lt;qapp.h&gt;
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 &lt; $SOURCE &gt; $TARGET",
            prefix = "file-")

def gen_prefix(env, sources):
    return "file-" + env['PLATFORM'] + '-'
b = Builder("build_it &lt; $SOURCE &gt; $TARGET",
            prefix = gen_prefix)

b = Builder("build_it &lt; $SOURCE &gt; $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 &lt; $SOURCE &gt; $TARGET"
            suffix = "-file")

def gen_suffix(env, sources):
    return "." + env['PLATFORM'] + "-file"
b = Builder("build_it &lt; $SOURCE &gt; $TARGET",
            suffix = gen_suffix)

b = Builder("build_it &lt; $SOURCE &gt; $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 &lt; $SOURCE &gt; $TARGET"
             suffix = ".out")
b2 = Builder("build_it &lt; $SOURCE &gt; $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 &lt; $TARGET &gt; $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 &lt; $TARGET &gt; $SOURCE",
            emitter = [e, e2])

# Calling an emitter function through a construction variable.
env = Environment(MY_EMITTER = e)
b = Builder("my_build &lt; $TARGET &gt; $SOURCE",
            emitter = '$MY_EMITTER')

# Calling a list of emitter functions through a construction variable.
env = Environment(EMITTER_LIST = [e, e2])
b = Builder("my_build &lt; $TARGET &gt; $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 &lt; $TARGET &gt; $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 implicitly 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 &gt; $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 &lt; $SOURCE &gt; $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 &lt; ${SOURCE.file} &gt; ${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 explicitly 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 &lt; ${SOURCE.file} &gt; ${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 &lt; ${SOURCE.file} &gt; ${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 &amp;&amp; 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>
which can be octal or string, similar to the bash command.
Examples:</para>

<literallayout class="monospaced">
Execute(Chmod('file', 0755))

env.Command('foo.out', 'foo.in',
            [Copy('$TARGET', '$SOURCE'),
             Chmod('$TARGET', 0755)])

Execute(Chmod('file', "ugo+w"))

env.Command('foo.out', 'foo.in',
            [Copy('$TARGET', '$SOURCE'),
             Chmod('$TARGET', "ugo+w")])
</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 &amp;&amp; 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              =&gt; sub/dir/file.x
${TARGET.base}       =&gt; sub/dir/file
${TARGET.dir}        =&gt; sub/dir
${TARGET.file}       =&gt; file.x
${TARGET.filebase}   =&gt; file
${TARGET.suffix}     =&gt; .x
${TARGET.abspath}    =&gt; /top/dir/sub/dir/file.x

SConscript('src/SConscript', variant_dir='sub/dir')
$SOURCE              =&gt; sub/dir/file.x
${SOURCE.srcpath}    =&gt; src/file.x
${SOURCE.srcdir}     =&gt; src

Repository('/usr/repository')
$SOURCE              =&gt; sub/dir/file.x
${SOURCE.rsrcpath}   =&gt; /usr/repository/src/file.x
${SOURCE.rsrcdir}    =&gt; /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 $). &gt; $TARGET
</literallayout>


<para>would execute the command:</para>

<literallayout class="monospaced">
echo Last build occurred $TODAY. &gt; $TARGET
</literallayout>


<para>but the command signature added to any target files would be:</para>

<literallayout class="monospaced">
echo Last build occurred  . &gt; $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'} &gt; $TARGET''')
</literallayout>
<para>the command executed will be either</para>
<literallayout class="monospaced">
echo FOO &gt; foo.out
</literallayout>
<para>or</para>
<literallayout class="monospaced">
echo BAR &gt; 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} &gt; $TARGET')

# Will execute this:
#  echo foo1 foo2 &gt; 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 &lt; $SOURCES &gt; $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 &lt; $SOURCES &gt; $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 &lt; $SOURCES &gt; $TARGET')

bar_in = File('bar.in')
env.Command('bar', bar_in, 'kprocess $SOURCES &gt; $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 &lt; $SOURCES &gt; $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 &lt;windows.h&gt;
#include &lt;my_big_header.h&gt;
</literallayout>

<para>StdAfx.cpp:</para>
<literallayout class="monospaced">
#include &lt;StdAfx.h&gt;
</literallayout>

<para>Foo.cpp:</para>
<literallayout class="monospaced">
#include &lt;StdAfx.h&gt;

/* do some stuff */
</literallayout>

<para>Bar.cpp:</para>
<literallayout class="monospaced">
#include &lt;StdAfx.h&gt;

/* 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 documentation 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>Originally: Steven Knight &lt;knight@baldmt.com&gt; and Anthony Roach &lt;aroach@electriceyeball.com&gt;
Since 2010: The SCons Development Team &lt;scons-dev@scons.org&gt;
</para>
</refsect1>
</refentry>
</reference>