<?xml version="1.0" encoding="UTF-8"?>
<!--
__COPYRIGHT__
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;
]>
<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>
<!-- adding pubdate seems superfluous when copyright year is the same
and html rendering puts both of them at the top of the page -->
<pubdate>2004 - 2020</pubdate>
<copyright>
<year>2004 - 2020</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 __VERSION__</refmiscinfo>
<refmiscinfo class='manual'>SCons __VERSION__</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</replaceable>=<replaceable>val</replaceable></arg>
<arg choice='opt' rep='repeat'><replaceable>targets</replaceable></arg>
</cmdsynopsis>
</refsynopsisdiv>
<refsect1 id='description'>
<title>DESCRIPTION</title>
<para>
&scons;
orchestrates the construction of software
(and other tangible products such as documentation files)
by determining which
component pieces must be built or rebuilt and invoking the necessary
commands to build them.</para>
<para>You instruct
&scons; by writing a configuration file
which specifies the files to be built (<firstterm>targets</firstterm>),
and, if necessary, the rules to build those files. Premade
rules exist for building many common software components
such as executable programs, object files, libraries,
so that for many software projects,
only the target and input files need be specified.</para>
<para>
When invoked, &scons;
searches for a file named
&SConstruct;
(it also checks alternate spellings
&Sconstruct;, &sconstruct;, &SConstruct.py; &Sconstruct.py;
and &sconstruct.py;
in that order) in the current directory and reads its
configuration from that file.
An alternate file name may be
specified via the
<option>-f</option>
option.
The &SConstruct;
file can specify subsidiary
configuration files by calling the
&SConscriptFunc; function.
By convention,
these subsidiary files are named
&SConscript;,
although any name may be used.
As a result of this naming convention,
the term <firstterm>SConscript files</firstterm>
is often used to refer
generically to the complete set of
configuration files for a project
(including the &SConstruct; file),
regardless of the actual file names or number of such files.</para>
<para>Before reading the SConscript files,
&scons;
looks for a directory named
<filename>site_scons</filename>
in various system directories and in the directory containing the
&SConstruct; file and prepends the ones it
finds to the Python module search path (<varname>sys.path</varname>),
thus allowing modules in such directories to be imported in
the normal Python way in SConscript files.
For each found site directory,
if it contains a file <filename>site_init.py</filename>
it is evaluated, and if it contains a directory
<filename>site_tools</filename> the path to it
is prepended to the default toolpath.
See the
<option>--site-dir</option>
and
<option>--no-site-dir</option>
options for details on default paths and
controlling the site directories.
</para>
<para>
&scons; configuration files are written in the
<firstterm>Python</firstterm> programming language,
although it is normally not necessary to be a Python
programmer to use &scons; effectively.
Standard Python scripting capabilities
such as flow control, data manipulation, and imported Python libraries
are available to use to handle complicated build situations.
</para>
<para>
&scons;
reads and executes all of the SConscript files
<emphasis>before</emphasis>
it begins building any targets.
To make this clear,
&scons;
prints the following messages about what it is doing:</para>
<screen>
$ <userinput>scons foo.out</userinput>
scons: Reading SConscript files ...
scons: done reading SConscript files.
scons: Building targets ...
cp foo.in foo.out
scons: done building targets.
$
</screen>
<para>The status messages
(lines beginning with the <literal>scons:</literal> tag)
may be suppressed using the
<option>-Q</option>
option.</para>
<para>&scons;
does not automatically propagate
the external environment used to execute
&scons;
to the commands used to build target files.
This is so that builds will be guaranteed
repeatable regardless of the environment
variables set at the time
&scons;
is invoked.
This also means that if the compiler or other commands
that you want to use to build your target files
are not in standard system locations,
&scons;
will not find them unless
you explicitly include the locations into the value of
<varname>PATH</varname> in the <varname>ENV</varname>
variable in the internal &consenv;.
Whenever you create a &consenv;,
you can propagate the value of <envar>PATH</envar>
from your external environment as follows:</para>
<programlisting language="python">
import os
env = Environment(ENV={'PATH': os.environ['PATH']})
</programlisting>
<para>Similarly, if the commands use specific
external environment variables that &scons;
does not recognize, they can be propagated into
the internal environment:</para>
<programlisting language="python">
import os
env = Environment(ENV={'PATH': os.environ['PATH'],
'ANDROID_HOME': os.environ['ANDROID_HOME'],
'ANDROID_NDK_HOME': os.environ['ANDROID_NDK_HOME']})
</programlisting>
<para>Or you may explicitly propagate the invoking user's
complete external environment:</para>
<programlisting language="python">
import os
env = Environment(ENV=os.environ)
</programlisting>
<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.
It should not cause problems if done in a build setup which tightly
controls how the environment is set up before invoking
&scons;, as in many continuous
integration setups.
</para>
<para>&scons;
can scan known input files automatically for dependency
information (for example, <literal>#include</literal>
preprocessor directives in C or C++ files)
and will rebuild dependent files appropriately
whenever any "included" input file changes.
&scons;
supports the
ability to define new scanners for unknown input file types.</para>
<para>&scons;
is normally executed in a top-level directory containing an
&SConstruct; file.
When &scons; is invoked,
the command line (including the contents
of the &SCONSFLAGS; environment variable,
if set) is processed.
Command-line options (see <xref linkend="options"/>) are consumed.
Any variable argument assignments are collected, and
remaining arguments are taken as the targets to build.</para>
<para>Values of variables to be passed to the SConscript files
may be specified on the command line:</para>
<screen>
<userinput>scons debug=1</userinput>
</screen>
<para>These variables are available
through the &ARGUMENTS; dictionary,
and can be used in the SConscript files to modify
the build in any way:</para>
<programlisting language="python">
if ARGUMENTS.get('debug', 0):
env = Environment(CCFLAGS='-g')
else:
env = Environment()
</programlisting>
<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. Each &ARGLIST; entry is a tuple containing
(<replaceable>argname</replaceable>, <replaceable>argvalue</replaceable>).
</para>
<para>Targets on the command line may be files, directories,
or phony targets defined using the &Alias; function.
The command line targets are made available in the
&COMMAND_LINE_TARGETS; list.
</para>
<para>If no targets are specified on the command line,
&scons;
will build the default targets. The default targets
are those specified in the SConscript files via calls
to the &Default; function; if none, the default targets are
those target files in or below the current directory.
Targets specified via the &Default; function are available
in the &DEFAULT_TARGETS; list.
</para>
<para>To ignore the default targets specified
through calls to &Default; and instead build all
target files in or below the current directory
specify the current directory (<literal>.</literal>)
as a command-line target:</para>
<screen>
<userinput>scons .</userinput>
</screen>
<para>To build all target files,
including any files outside of the current directory,
supply a command-line target
of the root directory (on POSIX systems):</para>
<screen>
<userinput>scons /</userinput>
</screen>
<para>or the path name(s) of the volume(s) in which all the targets
should be built (on Windows systems):</para>
<screen>
<userinput>scons C:\ D:\</userinput>
</screen>
<para>A subset of a hierarchical tree may be built by
remaining at the top-level directory (where the
&SConstruct;
file lives) and specifying the subdirectory as the target to
build:</para>
<screen>
<userinput>scons src/subdir</userinput>
</screen>
<para>or by changing directory and invoking scons with the
<option>-u</option>
option, which traverses up the directory
hierarchy until it finds the
&SConstruct;
file, and then builds
targets relatively to the current subdirectory (see
also the related <option>-D</option> and <option>-U</option> options):</para>
<screen>
<userinput>cd src/subdir</userinput>
<userinput>scons -u .</userinput>
</screen>
<para>In all cases, more files may be built than are
requested, as &scons; needs to make
sure any dependent files are built.</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>
<screen>
<userinput>scons -c .</userinput>
</screen>
<para>to remove all target files in or under the current directory, or:</para>
<screen>
<userinput>scons -c build export</userinput>
</screen>
<para>to remove target files under <filename>build</filename>
and <filename>export</filename>.</para>
<para>
Additional files or directories to remove can be specified using the
&Clean; function in the SConscript files.
Conversely, targets that would normally be removed by the
<option>-c</option>
invocation can be retained by calling the
&NoClean; function with those targets.</para>
<para>&scons;
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>
<screen>
<userinput>scons -j 4</userinput>
</screen>
<para>builds four targets in parallel, for example.</para>
<para>&scons;
can maintain a cache of target (derived) files that can
be shared between multiple builds. When caching is enabled in a
SConscript file, any target files built by
&scons;
will be copied
to the cache. If an up-to-date target file is found in the cache, it
will be retrieved from the cache instead of being rebuilt locally.
Caching behavior may be disabled and controlled in other ways by the
<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>
<!-- 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,
&scons;
searches for known programming tools
on various systems and initializes itself based on what is found.
On Windows systems which identify as <emphasis>win32</emphasis>,
&scons;
searches in order for the
Microsoft Visual C++ tools,
the MinGW tool chain,
the Intel compiler tools,
and the PharLap ETS compiler.
On Windows system which identify as <emphasis>cygwin</emphasis>
(that is, if &scons; is invoked from a cygwin shell),
the order changes to prefer the GCC toolchain over the MSVC tools.
On OS/2 systems,
&scons;
searches in order for the
OS/2 compiler,
the GCC tool chain,
and the Microsoft Visual C++ tools,
On SGI IRIX, IBM AIX, Hewlett Packard HP-UX, and Oracle Solaris systems,
&scons;
searches for the native compiler tools
(MIPSpro, Visual Age, aCC, and Forte tools respectively)
and the GCC tool chain.
On all other platforms,
including POSIX (Linux and UNIX) platforms,
&scons;
searches in order
for the GCC tool chain,
and the Intel compiler tools.
These default values may be overridden
by appropriate setting of &consvars;.</para>
<para>&scons;
requires Python 3.5 or higher.
There should be no other dependencies or requirements to run &scons;,
although the <package>pywin32</package> Python package is
strongly recommended if running on Windows systems.
</para>
</refsect1>
<refsect1 id='options'>
<title>OPTIONS</title>
<para>In general,
&scons;
supports the same command-line options as GNU &Make;
and many of those supported by <application>cons</application>.
</para>
<!-- Note: commented-out options are retained as they may be a model -->
<!-- for future development directions. Do not remove. -->
<variablelist>
<varlistentry>
<term><option>-b</option></term>
<listitem>
<para>Ignored for compatibility with non-GNU versions of &Make;</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<option>-c</option>,
<option>--clean</option>,
<option>--remove</option>
</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 &Clean; function.
Will not remove any targets specified by the &NoClean; function.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-<option>-cache-debug=<replaceable>file</replaceable></option></term>
<listitem>
<para>Write debug information about
derived-file caching to the specified
<replaceable>file</replaceable>.
If
<replaceable>file</replaceable>
is a hyphen
(<literal>-</literal>),
the debug information is printed to the standard output.
The printed messages describe what signature-file names
are being looked for in, retrieved from, or written to the
derived-file cache specified by &f-link-CacheDir;.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<option>--cache-disable</option>,
<option>--no-cache</option>
</term>
<listitem>
<para>Disable derived-file caching.
&scons;
will neither retrieve files from the cache
nor copy files to the cache. This option can
be used to temporarily disable the cache without
modifying the build scripts.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<option>--cache-force</option>,
<option>--cache-populate</option>
</term>
<listitem>
<para>When using &f-link-CacheDir;,
populate a derived-file 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><option>--cache-readonly</option></term>
<listitem>
<para>Use the derived-file cache, if enabled, to retrieve files,
but do not not update the cache with any files actually
built during this invocation.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--cache-show</option></term>
<listitem>
<para>When using a derived-file cache
and retrieving a file from it,
show the command
that would have been executed to build the file.
Without this option, &scons; reports
<computeroutput>"Retrieved `file' from cache."</computeroutput>.
This allows producing consistent output for build logs,
regardless of whether a target
file was rebuilt or retrieved from the cache.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--config=<replaceable>mode</replaceable></option></term>
<listitem>
<para>Control how the &Configure;
call should use or generate the
results of configuration tests.
<replaceable>mode</replaceable>should be specified from
among the following choices:</para>
<variablelist> <!-- nested list -->
<varlistentry>
<term><emphasis role="bold">auto</emphasis></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><emphasis role="bold">force</emphasis></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><emphasis role="bold">cache</emphasis></term>
<listitem>
<para>If this option is specified,
no configuration tests will be rerun
and all results will be taken from cache.
&scons; will report an error
if <option>--config=cache</option> is specified
and a necessary test does not
have any results in the cache.</para>
</listitem>
</varlistentry>
</variablelist> <!-- end nested list -->
</listitem>
</varlistentry>
<varlistentry>
<term>
<option>-C <replaceable>directory</replaceable></option>,
<option>--directory=<replaceable>directory</replaceable></option>
</term>
<listitem>
<para>Run as if &scons; was started in
<replaceable>directory</replaceable>
instead of the current working directory.
That is, change directory before searching for the
&SConstruct;,
&Sconstruct;,
&sconstruct;,
&SConstruct.py;,
&Sconstruct.py;
or
&sconstruct.py;
file or doing anything else.
When multiple
<option>-C</option>
options are given, each subsequent non-absolute
<option>-C</option> <replaceable>directory</replaceable>
is interpreted relative to the preceding one.
This option is similar to using
<option>-f <replaceable>directory</replaceable>/SConstruct</option>,
but <option>-f</option> does not search for any of the
predefined &SConstruct; names
in the specified directory.
See also options
<option>-u</option>,
<option>-U</option>
and
<option>-D</option>
to change the &SConstruct; search behavior when this option is used.
</para>
</listitem>
</varlistentry>
<!-- .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. -->
<varlistentry>
<term><option>-D</option></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><option>--debug=<replaceable>type</replaceable>[<replaceable>,type</replaceable>...]</option></term>
<listitem>
<para>Debug the build process.
<replaceable>type</replaceable>
specifies the kind of debugging info to emit.
Multiple types may be specified, separated by commas.
The following entries show the recognized types:</para>
<variablelist> <!-- nested list -->
<varlistentry>
<term><emphasis role="bold">action-timestamps</emphasis></term>
<listitem>
<para>Prints additional time profiling information. For
each command, shows the absolute start and end times.
This may be useful in debugging parallel builds.
Implies the <option>--debug=time</option> option.
</para>
<para><emphasis>Available since &scons; 3.1.</emphasis></para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">count</emphasis></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
<filename>*.pyo</filename>
files).</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">duplicate</emphasis></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><emphasis role="bold">explain</emphasis></term>
<listitem>
<para>Print an explanation of why &scons;
is deciding to (re-)build the targets
it selects for building.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">findlibs</emphasis></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><emphasis role="bold">includes</emphasis></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>
<screen>
$ <userinput>scons --debug=includes foo.o</userinput>
</screen>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">memoizer</emphasis></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><emphasis role="bold">memory</emphasis></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><emphasis role="bold">objects</emphasis></term>
<listitem>
<para>Prints a list of the various objects
of the various classes used internally by SCons.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">pdb</emphasis></term>
<listitem>
<para>Re-run &scons; under the control of the
<command>pdb</command>
Python debugger.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">prepare</emphasis></term>
<listitem>
<para>Print a line each time any target (internal or external)
is prepared for building.
&scons;
prints this for each target it considers, even if that
target is up to date (see also <option>--debug=explain</option>).
This can help debug problems with targets that aren't being
built; it shows whether
&scons;
is at least considering them or not.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">presub</emphasis></term>
<listitem>
<para>Print the raw command line used to build each target
before the &consenv; variables are substituted.
Also shows which targets are being built by this command.
Output looks something like this:</para>
<screen>
$ <userinput>scons --debug=presub</userinput>
Building myprog.o with action(s):
$SHCC $SHCFLAGS $SHCCFLAGS $CPPFLAGS $_CPPINCFLAGS -c -o $TARGET $SOURCES
...
</screen>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">stacktrace</emphasis></term>
<listitem>
<para>Prints an internal Python stack trace
when encountering an otherwise unexplained error.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">time</emphasis></term>
<listitem>
<para>Prints various time profiling information:</para>
<itemizedlist>
<listitem>
<para>The time spent executing each individual build command</para>
</listitem>
<listitem>
<para>The total build time (time SCons ran from beginning to end)</para>
</listitem>
<listitem>
<para>The total time spent reading and executing SConscript files</para>
</listitem>
<listitem>
<para>The total time SCons itself spent running
(that is, not counting reading and executing SConscript files)</para>
</listitem>
<listitem>
<para>The total time spent executing all build commands</para></listitem>
<listitem>
<para>The elapsed wall-clock time spent executing those build commands</para>
</listitem>
<listitem>
<para>The time spent processing each file passed to the &SConscriptFunc; function</para>
</listitem>
</itemizedlist>
<para>
(When
&scons;
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
&scons;
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>
</variablelist> <!-- end nested list -->
</listitem>
</varlistentry>
<varlistentry>
<term><option>--diskcheck=<replaceable>type</replaceable>[<replaceable>,type</replaceable>...]</option></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
<replaceable>type</replaceable>
argument can be set to:
</para>
<variablelist> <!-- nested list -->
<varlistentry>
<term><emphasis role="bold">all</emphasis></term>
<listitem>
<para>Enable all checks explicitly (the default behavior).</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">none</emphasis></term>
<listitem>
<para>Disable all such checks.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">match</emphasis></term>
<listitem>
<para>to check that files and directories on disk
match SCons' expected configuration.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">rcs</emphasis></term>
<listitem>
<para>Check for the existence of an RCS source
for any missing source or include files.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">sccs</emphasis></term>
<listitem>
<para>Check for the existence of an SCCS source
for any missing source or include files.</para>
</listitem>
</varlistentry>
</variablelist> <!-- end nested list -->
<para>
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><option>--duplicate=<replaceable>ORDER</replaceable></option></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.
<replaceable>ORDER</replaceable>
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>
</listitem>
</varlistentry>
<!-- .TP -->
<!-- \-e, \-\-environment\-overrides -->
<!-- Variables from the execution environment override construction -->
<!-- variables from the SConscript files. -->
<varlistentry>
<term><option>--enable-virtualenv</option></term>
<listitem>
<para>Import virtualenv-related variables to SCons.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<option>-f <replaceable>file</replaceable></option>,
<option>--file=<replaceable>file</replaceable></option>,
<option>--makefile=<replaceable>file</replaceable></option>,
<option>--sconstruct=<replaceable>file</replaceable></option>
</term>
<listitem>
<para>Use
<replaceable>file</replaceable>
as the initial SConscript file.
Multiple
<option>-f</option>
options may be specified,
in which case
&scons;
will read all of the specified files.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<option>-h</option>,
<option>--help</option>
</term>
<listitem>
<para>Print a local help message for this project,
if one is defined in the SConscript files
(see the &f-link-Help; function),
plus a line that refers to the standard &SCons; help message.
If no local help message is defined,
prints the standard &SCons; help message
(as for the <option>-H</option> option)
plus help for any local options defined through &f-link-AddOption;.
Exits after displaying the appropriate message.</para>
<para>
Note that use of this option requires &SCons; to process
the SConscript files, so syntax errors may cause
the help message not to be displayed.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<option>-H</option>,
<option>--help-options</option>
</term>
<listitem>
<para>Print the standard help message about &SCons;
command-line options and exit.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<option>-i</option>,
<option>--ignore-errors</option>
</term>
<listitem>
<para>Ignore all errors from commands executed to rebuild files.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<option>-I <replaceable>directory</replaceable></option>,
<option>--include-dir=<replaceable>directory</replaceable></option>
</term>
<listitem>
<para>Specifies a
<replaceable>directory</replaceable>
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><option>--ignore-virtualenv</option></term>
<listitem>
<para>Suppress importing virtualenv-related variables to SCons.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--implicit-cache</option></term>
<listitem>
<para>Cache implicit dependencies.
This causes
&scons;
to use the implicit (scanned) dependencies
from the last time it was run
instead of scanning the files for implicit dependencies.
This can significantly speed up SCons,
but with the following limitations:</para>
<para>&scons;
will not detect changes to implicit dependency search paths
(e.g.
<envar>CPPPATH</envar>, <envar>LIBPATH</envar>)
that would ordinarily
cause different versions of same-named files to be used.</para>
<para>&scons;
will miss changes in the implicit dependencies
in cases where a new implicit
dependency is added earlier in the implicit dependency search path
(e.g.
<envar>CPPPATH</envar>, <envar>LIBPATH</envar>)
than a current implicit dependency with the same name.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--implicit-deps-changed</option></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><option>--implicit-deps-unchanged</option></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><option>--install-sandbox=<replaceable>path</replaceable></option></term>
<listitem>
<para>
When using the &Install; functions, prepend <replaceable>path</replaceable>
to the installation paths such that all installed files will be placed
underneath <replaceable>path</replaceable>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--interactive</option></term>
<listitem>
<para>Starts SCons in interactive mode.
The SConscript files are read once and a
<computeroutput>scons>>></computeroutput>
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>
<variablelist>
<varlistentry>
<term><userinput>build <parameter>[OPTIONS] [TARGETS] ...</parameter></userinput></term>
<listitem>
<para>Builds the specified
<parameter>TARGETS</parameter>
(and their dependencies)
with the specified
SCons command-line
<parameter>OPTIONS</parameter>.
<emphasis role="bold">b</emphasis>
and
<emphasis role="bold">scons</emphasis>
are synonyms for
<emphasis role="bold">build</emphasis>.
</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>
<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>
</listitem>
</varlistentry>
<varlistentry>
<term><userinput>clean <parameter>[OPTIONS] [TARGETS] ...</parameter></userinput></term>
<listitem>
<para>Cleans the specified
<parameter>TARGETS</parameter>
(and their dependencies)
with the specified
<parameter>OPTIONS</parameter>.
<emphasis role="bold">c</emphasis>
is a synonym.
This command is itself a synonym for
<userinput>build --clean</userinput></para>
</listitem>
</varlistentry>
<varlistentry>
<term><userinput>exit</userinput></term>
<listitem>
<para>Exits SCons interactive mode.
You can also exit by terminating input
(<keycombo action="simul">
<keycap>Ctrl</keycap>
<keycap>D</keycap>
</keycombo>
UNIX or Linux systems,
(<keycombo action="simul">
<keycap>Ctrl</keycap>
<keycap>Z</keycap>
</keycombo>
on Windows systems).</para>
</listitem>
</varlistentry>
<varlistentry>
<term><userinput>help <parameter>[COMMAND]</parameter></userinput></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><userinput>shell <parameter>[COMMANDLINE]</parameter></userinput></term>
<listitem>
<para>Executes the specified
<parameter>COMMANDLINE</parameter>
in a subshell.
If no
<parameter>COMMANDLINE</parameter>
is specified,
executes the interactive command interpreter
specified in the
<envar>SHELL</envar>
environment variable
(on UNIX and Linux systems)
or the
<envar>COMSPEC</envar>
environment variable
(on Windows systems).
<emphasis role="bold">sh</emphasis>
and
<emphasis role="bold">!</emphasis>
are synonyms.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><userinput>version</userinput></term>
<listitem>
<para>Prints SCons version information.</para>
</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>
<screen>
$ <userinput>scons --interactive</userinput>
scons: Reading SConscript files ...
scons: done reading SConscript files.
scons>>> build -n prog
scons>>> exit
</screen>
</listitem>
</varlistentry>
<varlistentry>
<term>
<option>-j <replaceable>N</replaceable></option>,
<option>--jobs=<replaceable>N</replaceable></option>
</term>
<listitem>
<para>Specifies the maximum number of comcurrent jobs (commands) to run.
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>
<option>-k</option>,
<option>--keep-going</option>
</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>
</listitem>
</varlistentry>
<!-- .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.] -->
<varlistentry>
<term><option>-m</option></term>
<listitem>
<para>Ignored for compatibility with non-GNU versions of &Make;.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--max-drift=<replaceable>SECONDS</replaceable></option></term>
<listitem>
<para>Set the maximum expected drift in the modification time of files to
<replaceable>SECONDS</replaceable>.
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><option>--md5-chunksize=<replaceable>KILOBYTES</replaceable></option></term>
<listitem>
<para>Set the block size used to compute MD5 signatures to
<replaceable>KILOBYTES</replaceable>.
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>
<option>-n</option>,
<option>--just-print</option>,
<option>--dry-run</option>,
<option>--recon</option>
</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><option>--no-site-dir</option></term>
<listitem>
<para>Prevents the automatic addition of the standard
<emphasis>site_scons</emphasis>
dirs to
<varname>sys.path</varname>.
Also prevents loading the
<filename>site_scons/site_init.py</filename>
modules if they exist, and prevents adding their
<filename>site_scons/site_tools</filename>
dirs to the toolpath.</para>
</listitem>
</varlistentry>
<!-- .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 -->
<varlistentry>
<term><option>--profile=<replaceable>file</replaceable></option></term>
<listitem>
<para>Run SCons under the Python profiler
and save the results in the specified
<replaceable>file</replaceable>.
The results may be analyzed using the Python
pstats module.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<option>-q</option>,
<option>--question</option></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><option>-Q</option></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>
</listitem>
</varlistentry>
<!-- .TP -->
<!-- \-r, \-R, \-\-no\-builtin\-rules, \-\-no\-builtin\-variables -->
<!-- Clear the default construction variables. Construction -->
<!-- environments that are created will be completely empty. -->
<varlistentry>
<term><option>--random</option></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>
<option>-s</option>,
<option>--silent</option>,
<option>--quiet</option>
</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>
<option>-S</option>,
<option>--no-keep-going</option>,
<option>--stop</option>
</term>
<listitem>
<para>Ignored for compatibility with GNU &Make;</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--site-dir=<replaceable>dir</replaceable></option></term>
<listitem>
<para>Uses the named <replaceable>dir</replaceable> as the site directory
rather than the default
<emphasis>site_scons</emphasis>
directories. This directory will be prepended to
<varname>sys.path</varname>,
the module
<filename><replaceable>dir</replaceable>/site_init.py</filename>
will be loaded if it exists, and
<filename><replaceable>dir</replaceable>/site_tools</filename>
will be added to the default toolpath.</para>
<para>The default set of
<emphasis>site_scons</emphasis>
directories used when
<option>--site-dir</option>
is not specified depends on the system platform, as follows.
Directories are examined in the order given, from most
generic to most specific, so the last-executed <filename>site_init.py</filename> file is
the most specific one (which gives it the chance to override
everything else), and the directories are prepended to the paths, again so
the last directory examined comes first in the resulting path.</para>
<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>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--stack-size=<replaceable>KILOBYTES</replaceable></option></term>
<listitem>
<para>Set the size stack used to run threads to
<replaceable>KILOBYTES</replaceable>.
This value determines the stack size of the threads used to run jobs.
These threads execute the actions of the builders for the
nodes that are out-of-date.
This option has no effect unless the number of concurrent
build jobs is larger than one (as set by <option>-j N</option> or
<option>--jobs=N</option> on the command line or &SetOption; in a script).
</para>
<para>
Using a stack size that is too small may cause stack overflow errors.
This usually shows up as segmentation faults that cause scons to abort
before building anything. Using a stack size that is too large will
cause scons to use more memory than required and may slow down the entire
build process.
The default value is to use a stack size of 256 kilobytes, which should
be appropriate for most uses. You should not need to increase this value
unless you encounter stack overflow errors.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<option>-t</option>,
<option>--touch</option>
</term>
<listitem>
<para>Ignored for compatibility with GNU &Make;.
(Touching a file to make it
appear up-to-date is unnecessary when using &scons;.)</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--taskmastertrace=<replaceable>file</replaceable></option></term>
<listitem>
<para>Prints trace information to the specified
<replaceable>file</replaceable>
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><option>--tree=<replaceable>type</replaceable>[<replaceable>,type</replaceable>...]</option></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
<replaceable>type</replaceable>
specified:</para>
<variablelist> <!-- nested list -->
<varlistentry>
<term><emphasis role="bold">all</emphasis></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><emphasis role="bold">derived</emphasis></term>
<listitem>
<para>Restricts the tree output to only derived (target) files,
not source files.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">linedraw</emphasis></term>
<listitem>
<para>Draw the tree output using Unicode line-drawing characters
instead of plain ASCII text. This option acts as a modifier
to the selected <replaceable>type</replaceable>(s). If
specified alone, without any <replaceable>type</replaceable>,
it behaves as if <emphasis role="bold">all</emphasis>
had been specified.
</para>
<para><emphasis>Available since &scons; 4.0.</emphasis></para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">status</emphasis></term>
<listitem>
<para>Prints status information for each displayed node.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">prune</emphasis></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> <!-- end nested list -->
<para>Multiple <replaceable>type</replaceable>
choices may be specified, separated by commas:</para>
<screen>
# Prints only derived files, with status information:
<userinput>scons --tree=derived,status</userinput>
# Prints all dependencies of target, with status information
# and pruning dependencies of already-visited Nodes:
<userinput>scons --tree=all,prune,status target</userinput>
</screen>
</listitem>
</varlistentry>
<varlistentry>
<term>
<option>-u</option>,
<option>--up</option>,
<option>--search-up</option>
</term>
<listitem>
<para>Walks up the directory structure until an
&SConstruct;, &Sconstruct;, &sconstruct;, &SConstruct.py;,
&Sconstruct.py; or &sconstruct.py;
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><option>-U</option></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>
<option>-v</option>,
<option>--version</option>
</term>
<listitem>
<para>Print the
&scons;
version, copyright information,
list of authors, and any other relevant information.
Then exit.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<option>-w</option>,
<option>--print-directory</option>
</term>
<listitem>
<para>Print a message containing the working directory before and
after other processing.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--no-print-directory</option></term>
<listitem>
<para>Turn off -w, even if it was turned on implicitly.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<option>--warn=<replaceable>type</replaceable></option>,
<option>--warn=no-<replaceable>type</replaceable></option>
</term>
<listitem>
<para>Enable or disable (with the no- prefix) warnings.
<replaceable>type</replaceable>
specifies the type of warnings to be enabled or disabled:</para>
<variablelist> <!-- nested list -->
<varlistentry>
<term><emphasis role="bold">all</emphasis></term>
<listitem>
<para>All warnings.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">cache-version</emphasis></term>
<listitem>
<para>Warnings about the derived-file cache directory
specified by &f-link-CacheDir; not using
the latest configuration information.
These warnings are enabled by default.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">cache-write-error</emphasis></term>
<listitem>
<para>Warnings about errors trying to
write a copy of a built file to a specified
derived-file cache specified by &f-link-CacheDir;.
These warnings are disabled by default.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">corrupt-sconsign</emphasis></term>
<listitem>
<para>Warnings about unfamiliar signature data in
<filename>.sconsign</filename>
files.
These warnings are enabled by default.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">dependency</emphasis></term>
<listitem>
<para>Warnings about dependencies.
These warnings are disabled by default.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">deprecated</emphasis></term>
<listitem>
<para>Warnings about use of
currently deprecated features.
These warnings are enabled by default.
Not all deprecation warnings can be disabled with the
<option>--warn=no-deprecated</option> option as some
deprecated features which are late in the deprecation
cycle may have been designated as mandatory warnings,
and these will still display.
Warnings for certain deprecated features
may also be enabled or disabled individually;
see below.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">duplicate-environment</emphasis></term>
<listitem>
<para>Warnings about attempts to specify a build
of a target with two different &consenvs;
that use the same action.
These warnings are enabled by default.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">fortran-cxx-mix</emphasis></term>
<listitem>
<para>Warnings about linking
Fortran and C++ object files in a single executable,
which can yield unpredictable behavior with some compilers.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">future-deprecated</emphasis></term>
<listitem>
<para>Warnings about features
that will be deprecated in the future.
Such warnings are disabled by default.
Enabling future deprecation warnings is
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><emphasis role="bold">link</emphasis></term>
<listitem>
<para>Warnings about link steps.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">misleading-keywords</emphasis></term>
<listitem>
<para>Warnings about the use of two commonly
misspelled keywords
<parameter>targets</parameter>
and
<parameter>sources</parameter>
to &f-link-Builder; calls. The correct spelling is the
singular form, even though
<parameter>target</parameter>
and
<parameter>source</parameter>
can themselves refer to lists of names or nodes.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">missing-sconscript</emphasis></term>
<listitem>
<para>Warnings about missing SConscript files.
These warnings are enabled by default.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">no-object-count</emphasis></term>
<listitem>
<para>Warnings about the
<option>--debug=object</option>
feature not working when
&scons;
is run with the Python
<option>-O</option>
option or from optimized Python (.pyo) modules.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">no-parallel-support</emphasis></term>
<listitem>
<para>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><emphasis role="bold">python-version</emphasis></term>
<listitem>
<para>Warnings about running
SCons with a deprecated version of Python.
These warnings are enabled by default.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">reserved-variable</emphasis></term>
<listitem>
<para>Warnings about attempts to set the
reserved &consvar; names
&cv-CHANGED_SOURCES;,
&cv-CHANGED_TARGETS;,
&cv-TARGET;,
&cv-TARGETS;,
&cv-SOURCE;,
&cv-SOURCES;,
&cv-UNCHANGED_SOURCES;
or
&cv-UNCHANGED_TARGETS;.
These warnings are disabled by default.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">stack-size</emphasis></term>
<listitem>
<para>Warnings about requests to set the stack size
that could not be honored.
These warnings are enabled by default.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">target_not_build</emphasis></term>
<listitem>
<para>Warnings about a build rule not building the
expected targets. These warnings are disabled by default.</para>
</listitem>
</varlistentry>
</variablelist> <!-- end nested list -->
</listitem>
</varlistentry>
<!-- .TP -->
<!-- \-\-warn\-undefined\-variables -->
<!-- Warn when an undefined variable is referenced. -->
<!-- .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 -->
<varlistentry>
<term>
<option>-Y <replaceable>repository</replaceable></option>,
<option>--repository=<replaceable>repository</replaceable></option>,
<option>--srcdir=<replaceable>repository</replaceable></option>
</term>
<listitem>
<para>Search the specified <replaceable>repository</replaceable>
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 <firstterm>&ConsEnv;</firstterm> is the basic means by which SConscript
files communicate build information to
&scons;.
A new &consenv; is created using the
&f-link-Environment;
function:</para>
<programlisting language="python">
env = Environment()
</programlisting>
<para>&Consenv; attributes called
<firstterm>&ConsVars;</firstterm> may be set
either by specifying them as keyword arguments when the object is created
or by assigning them a value after the object is created:</para>
<programlisting language="python">
env = Environment(FOO='foo')
env['BAR'] = 'bar'
</programlisting>
<!--TODO: want to say this, but then have to provide a way for user to tell...
<para>Certain settings that affect tool detection work
only on initialization, so check that setting a value
after creation is appropriate.</para>
-->
<para>
An existing &consenv; can be duplicated by calling the &f-link-env-Clone;
method. Without arguments, it will be a copy with the same
settings. Otherwise, &f-env-Clone; takes the same arguments as &f-Environment;,
and uses the arguments to create a modified copy.
</para>
<para>
&SCons; also provides a special &consenv; called the
<firstterm>&DefEnv;</firstterm>.
The &defenv; is used only for global functions, that is,
construction activities called without the context of a regular &consenv;.
See &f-link-DefaultEnvironment; for more information.
</para>
<para>As a convenience,
&consvars; may also be set or modified by the
<parameter>parse_flags</parameter>
keyword argument, which applies the
&f-link-env-MergeFlags;
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 need to be distributed to a number of &consvars;.</para>
<programlisting language="python">
env = Environment(parse_flags='-Iinclude -DEBUG -lm')
</programlisting>
<para>This example adds 'include' to
the <envar>CPPPATH</envar> &consvar;
'EBUG' to
<envar>CPPDEFINES</envar>,
and 'm' to
<envar>LIBS</envar>.
&f-link-env-ParseFlags; describes how these arguments
are distributed to &consvars;.
</para>
<para>By default, a new &consenv; is
initialized with a set of builder methods
and &consvars; that are appropriate
for the current platform.
An optional <parameter>platform</parameter> keyword argument may be
used to specify that the &consenv; should
be initialized for a different platform:</para>
<programlisting language="python">
env = Environment(platform='cygwin')
env = Environment(platform='os2')
env = Environment(platform='posix')
env = Environment(platform='win32')
</programlisting>
<para>Specifying a platform initializes the appropriate
&consvars; in the environment
to use and generate file names with prefixes
and suffixes appropriate for that platform.</para>
<para>Note that the
<emphasis role="bold">win32</emphasis>
platform adds the
<envar>SystemDrive</envar>
and
<envar>SystemRoot</envar>
variables from the user's external environment
to the &consenv;'s
<envar>ENV</envar>
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
<literal>:pserver:anonymous@cvs.sourceforge.net:/cvsroot/scons</literal>)
will work on Windows systems.</para>
<para>The <parameter>platform</parameter> argument may be a function or callable object,
in which case the &Environment; method
will call it to update
the new &consenv;:</para>
<programlisting language="python">
def my_platform(env):
env['VAR'] = 'xyzzy'
env = Environment(platform=my_platform)
</programlisting>
</refsect2>
<refsect2 id='tools'>
<title>Tools</title>
<para>
&SCons; has a large number of predefined tools which
are used to help initialize the &consenv;,
and additional tools can be added.
An &scons; <firstterm>tool specification</firstterm>
is only responsible for setup.
For example, if the SConscript file declares
the need to construct an object file from
a C-language source file by calling the
&b-link-Object; builder, then a tool representing
an available C compiler needs to have run first,
to set up the builder and all the &consvars;
it needs, in that &consenv;. Normally this
happens invisibly: &scons; has per-platform
lists of default tools, and it runs through those tools,
calling the ones which are actually applicable
(skipping those where necessary programs are not
installed on the build system, etc.).
</para>
<para>
A specific set of tools
with which to initialize the environment when
creating it
may be specified using the optional keyword argument
<parameter>tools</parameter>.
This is useful to override the defaults,
to specify non-default built-in tools, and
to supply added tools:</para>
<programlisting language="python">
env = Environment(tools=['msvc', 'lex'])
</programlisting>
<para>
Tools can also be called by using the &f-link-Tool;
method (see below).
</para>
<para>
The <parameter>tools</parameter> argument overrides
the default tool list, it does not add to it, so be
sure to include all the tools you need.
For example if you are building a c/c++ program
you must specify a tool for at least a compiler and a linker,
as in <literal>tools=['clang', 'link']</literal>.
The tool name <literal>'default'</literal> can
be used to retain the default list.
</para>
<para>If no <parameter>tools</parameter> list is specified,
or the list includes <literal>'default'</literal>,
then &scons; will detect usable tools,
using the value of <varname>PATH</varname>
in the <varname>ENV</varname> &consvar; (<emphasis>not</emphasis>
the external <envar>PATH</envar> from <varname>os.environ</varname>)
for looking up any backing programs, and the platform name in effect
to determine the default tools for that platform.
Changing the <varname>PATH</varname>
variable after the &consenv; is constructed will not cause the tools to
be redetected.</para>
<para>To help locate added tools, specify the
<parameter>toolpath</parameter> keyword argument:</para>
<programlisting language="python">
env = Environment(tools=['default', 'foo'], toolpath=['tools'])
</programlisting>
<para>
This looks for a tool specification in <filename>tools/foo.py</filename>
as well as using the ordinary default tools for the platform.
</para>
<para>
Tools in the toolpath are used in preference to
any of the built-in ones. For example, adding
a tool <filename>gcc.py</filename> to the toolpath
directory would override the built-in gcc tool.
The toolpath is
stored in the environment and will be
picked up by subsequent calls to the
&f-Clone; and &f-Tool; methods:
</para>
<programlisting language="python">
base = Environment(toolpath=['custom_path'])
derived = base.Clone(tools=['custom_tool'])
derived.CustomBuilder()
</programlisting>
<para>
A tool specification must include two functions:
</para>
<variablelist>
<varlistentry>
<term><function>generate</function>(<parameter>env, **kwargs</parameter>)</term>
<listitem>
<para>Modifies the environment referenced by <parameter>env</parameter>
to set up variables so that the facilities represented by
the tool can be executed.
It may use any keyword arguments
that the user supplies in <parameter>kwargs</parameter>
to vary its initialization.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><function>exists</function>(<parameter>env</parameter>)</term>
<listitem>
<para>Return <constant>True</constant> if the tool can
be called. Usually this means looking up one or more
known programs using the <envar>PATH</envar> from the
supplied <parameter>env</parameter>, but the tool can
make the "exists" decision in any way it chooses.
</para>
</listitem>
</varlistentry>
</variablelist>
<para>The elements of the <parameter>tools</parameter> list may also
be functions or callable objects,
in which case the &Environment; method
will call those objects
to update the new &consenv; (see &f-link-Tool; for more details):</para>
<programlisting language="python">
def my_tool(env):
env['XYZZY'] = 'xyzzy'
env = Environment(tools=[my_tool])
</programlisting>
<para>The individual elements of the <parameter>tools</parameter> list
may also themselves be lists or tuples of the form
(<varname>toolname</varname>, <varname>kw_dict</varname>).
SCons searches for the
<parameter>toolname</parameter>
specification file as described above, and
passes
<parameter>kw_dict</parameter>,
which must be a dictionary, as keyword arguments to the tool's
<function>generate</function>
function.
The
<function>generate</function>
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 language="python">
# in tools/my_tool.py:
def generate(env, **kwargs):
# Sets MY_TOOL to the value of keyword 'arg1' '1' if not supplied
env['MY_TOOL'] = kwargs.get('arg1', '1')
def exists(env):
return True
# in SConstruct:
env = Environment(tools=['default', ('my_tool', {'arg1': 'abc'})],
toolpath=['tools'])
</programlisting>
<para>The tool definition (<function>my_tool</function> in the example)
can use the
<envar>PLATFORM</envar> variable from
the &consenv; it is passed to customize the tool for different platforms.</para>
<para>Tools can be "nested" - that is, they
can be located within a subdirectory in the toolpath.
A nested tool name uses a dot to represent a directory separator</para>
<programlisting language="python">
# namespaced builder
env = Environment(ENV=os.environ, tools=['SubDir1.SubDir2.SomeTool'])
env.SomeTool(targets, sources)
# Search Paths
# SCons\Tool\SubDir1\SubDir2\SomeTool.py
# SCons\Tool\SubDir1\SubDir2\SomeTool\__init__.py
# .\site_scons\site_tools\SubDir1\SubDir2\SomeTool.py
# .\site_scons\site_tools\SubDir1\SubDir2\SomeTool\__init__.py
</programlisting>
<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 located together with the various Python -->
<!-- '\" tool modules in the build engine directory -->
<!-- '\" 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 located together with the various Python -->
<!-- '\" tool modules in the build engine directory -->
<!-- '\" END GENERATED TOOL DESCRIPTIONS -->
<!-- '\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -->
</refsect2>
<refsect2 id='builder_methods'>
<title>Builder Methods</title>
<para>You tell &scons; what to build
by calling <firstterm>Builders</firstterm>, functions which know to take a
particular action to produce a particular result type
when given source files of a particular type. &scons;
defines a number of builders, and you can also write your own.
Builders are attached to a &consenv; as methods,
and the available builder methods are listed as
key-value pairs in the
<envar>BUILDERS</envar> attribute of the &consenv;.
The available builders can be displayed like this
for debugging purposes:
</para>
<programlisting language="python">
print("Builders:", list(env['BUILDERS']))
</programlisting>
<para>
Builder methods always take two arguments:
<replaceable>target</replaceable>
(a target or a list of targets to be built)
and
<replaceable>source</replaceable>
(a source or list of sources to be used as input
when building),
although in some circumstances,
the target argument can actually be omitted (see below).
Builder methods also take a variety of
keyword arguments, described below.
</para>
<para>Because long lists of file names
can lead to a lot of quoting,
&scons;
supplies a &f-link-Split;
global function
and a same-named environment method
that splits a single string
into a list, using
strings of white-space characters as the delimiter.
(similar to the Python string <function>split</function>
method, but succeeds even if the input isn't a string.)</para>
<para>
The target and source arguments to a builder method
can be specified either as positional arguments,
in which case the target comes first, or as
keyword arguments, using <parameter>target=</parameter>
and <parameter>source=</parameter>.
The following are equivalent examples of calling the
&Program; builder method:
</para>
<programlisting language="python">
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', source=Split('bar.c foo.c'))
env.Program(target='bar', source=env.Split('bar.c foo.c'))
env.Program('bar', source='bar.c foo.c'.split())
</programlisting>
<para>
Python follows the POSIX pathname convention for path
strings: if a string begins with the operating system pathname separator
(on Windows both the slash and backslash separator work,
and any leading drive specifier is ignored for
the determination) it is considered an absolute path,
otherwise it is a relative path.
If the path string contains no separator characters,
it is searched for as a file in the current directory. If it
contains separator characters, the search follows down
from the starting point, which is the top of the directory tree for
an absolute path and the current directory for a relative path.
</para>
<para>
&scons; recognizes a third way to specify
path strings: if the string begins with
the <emphasis role="bold">#</emphasis> character it is
<firstterm>top-relative</firstterm> - it works like a relative path but the
search follows down from the directory containing the top-level
&SConstruct; rather than
from the current directory. The <emphasis role="bold">#</emphasis> is allowed
to be followed by a pathname separator, which is ignored if
found in that position.
Top-relative paths only work in places where &scons; will
interpret the path (see some examples below). To be
used in other contexts the string will need to be converted
to a relative or absolute path first.
</para>
<para>
Target and source pathnames can be absolute, relative, or
top-relative. Relative pathnames are searched considering the
directory of the SConscript
file currently being processed as the "current directory".
</para>
<para>Examples:</para>
<programlisting language="python">
# 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')
# This will not work, only SCons interfaces understand '#',
# os.path.exists is pure Python:
if os.path.exists('#inc/foo.h'):
env.Append(CPPPATH='#inc')
</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
&scons;
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 <filename>bar.c</filename> source file:</para>
<programlisting language="python">
env.Program(target='bar', source='bar.c')
env.Program('bar', source='bar.c')
env.Program(source='bar.c')
env.Program('bar.c')
</programlisting>
<para>As a convenience, a
<parameter>srcdir</parameter>
keyword argument may be specified
when calling a Builder.
When specified,
all source file strings that are not absolute paths
or top-relative paths
will be interpreted relative to the specified
<parameter>srcdir</parameter>.
The following example will build the
<filename>build/prog</filename>
(or
<filename>build/prog.exe</filename>
on Windows)
program from the files
<filename>src/f1.c</filename>
and
<filename>src/f2.c</filename>:
</para>
<programlisting language="python">
env.Program('build/prog', ['f1.c', 'f2.c'], srcdir='src')
</programlisting>
<para>It is possible to <firstterm>override</firstterm> (replace or add)
&consvars; when calling a
builder method by passing them as keyword arguments.
These overrides
will only be in effect when building that target, and will not
affect other parts of the build. For example, if you want to specify
some libraries needed by just one program:</para>
<programlisting language="python">
env.Program('hello', 'hello.c', LIBS=['gl', 'glut'])
</programlisting>
<para>or generate a shared library with a non-standard suffix:</para>
<programlisting language="python">
env.SharedLibrary('word', 'word.cpp',
SHLIBSUFFIX='.ocx',
LIBSUFFIXES=['.ocx'])
</programlisting>
<para>Note that both the &cv-link-SHLIBSUFFIX;
and &cv-link-LIBSUFFIXES;
variables must be set if you want &scons; to search automatically
for dependencies on the non-standard library names;
see the descriptions below of these variables for more information.</para>
<para>It is also possible to use the
<parameter>parse_flags</parameter>
keyword argument in an override,
to merge command-line style arguments
into the appropriate &consvars;
(see &f-link-env-MergeFlags;).
</para>
<programlisting language="python">
env = Program('hello', 'hello.c', parse_flags='-Iinclude -DEBUG -lm')
</programlisting>
<para>This example adds 'include' to
<envar>CPPPATH</envar>,
'EBUG' to
<envar>CPPDEFINES</envar>,
and 'm' to
<envar>LIBS</envar>.</para>
<para>Although the builder methods defined by
&scons;
are, in fact,
methods of a &consenv; object,
they may also be called without an explicit environment:</para>
<programlisting language="python">
Program('hello', 'hello.c')
SharedLibrary('word', 'word.cpp')
</programlisting>
<para>In this case,
the methods are called internally using a default construction
environment that consists of the tools and values that
&scons;
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>
<programlisting language="python">
from SCons.Script import *
</programlisting>
<para>All builder methods return a list-like object
containing Nodes that will be built.
A <firstterm>Node</firstterm>
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 preprocessor define
when compiling one specific object file:</para>
<programlisting language="python">
bar_obj_list = env.StaticObject('bar.c', CPPDEFINES='-DBAR')
env.Program(source=['foo.c', bar_obj_list, 'main.c'])
</programlisting>
<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>Builder calls will automatically "flatten"
lists passed as source and target, so they are free to
contain elements which are themselves lists, such as
<varname>bar_obj_list</varname>
returned by the &StaticObject; call above.
If you need to manipulate a list of lists returned by builders
directly in Python code,
you can either build a new list by hand:</para>
<programlisting language="python">
foo = Object('foo.c')
bar = Object('bar.c')
objects = ['begin.o'] + foo + ['middle.o'] + bar + ['end.o']
for obj in objects:
print(str(obj))
</programlisting>
<para>Or you can use the &f-link-Flatten;
function supplied by &scons;
to create a list containing just the Nodes,
which may be more convenient:</para>
<programlisting language="python">
foo = Object('foo.c')
bar = Object('bar.c')
objects = Flatten(['begin.o', foo, 'middle.o', bar, 'end.o'])
for obj in objects:
print(str(obj))
</programlisting>
<para>&SCons; builder calls return
a list-like object, not an actual Python list,
so it is not appropriate to use the Python add
operator (<literal>+</literal> or <literal>+=</literal>)
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 list
<function>extend</function>
method to make sure the list is updated in-place.
Example:</para>
<programlisting language="python">
object_files = []
# Do NOT use += here:
# object_files += Object('bar.c')
#
# It will not update the object_files list in place.
#
# Instead, use the list extend method:
object_files.extend(Object('bar.c'))
</programlisting>
<para>The path name for a Node's file may be used
by passing the Node to Python's builtin
<function>str</function>
function:</para>
<programlisting language="python">
bar_obj_list = env.StaticObject('bar.c', CPPDEFINES='-DBAR')
print("The path to bar_obj is:", str(bar_obj_list[0]))
</programlisting>
<para>Note again that because the Builder call returns a list,
we have to access the first element in the list
(<literal>(bar_obj_list[0])</literal>)
to get at the Node that actually represents
the object file.</para>
<para>Builder calls support a
<parameter>chdir</parameter>
keyword argument that
specifies that the Builder's action(s)
should be executed
after changing directory.
If the
<parameter>chdir</parameter>
argument is
a string or a directory Node,
scons will change to the specified directory.
If the
<parameter>chdir</parameter>
is not a string or Node
and is non-zero,
then scons will change to the
target file's directory.</para>
<programlisting language="python">
# 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)
</programlisting>
<para>Note that &SCons; will
<emphasis>not</emphasis>
automatically modify
its expansion of
&consvars; like
<envar>$TARGET</envar>
and
<envar>$SOURCE</envar>
when using the <parameter>chdir</parameter>
keyword argument--that is,
the expanded file names
will still be relative to
the top-level directory where &SConstruct; was found,
and consequently incorrect
relative to the chdir directory.
If you use the <parameter>chdir</parameter> keyword argument,
you will typically need to supply a different
command line using
expansions like
<literal>${TARGET.file}</literal>
and
<literal>${SOURCE.file}</literal>
to use just the filename portion of the
targets and source.</para>
<para>&scons;
predefines the following builder methods.
Depending on the setup of a particular
&consenv; and on the type and software
installation status of the underlying system,
not all builders may be available to that
&consenv;.</para>
<!-- '\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -->
<!-- '\" BEGIN GENERATED BUILDER DESCRIPTIONS -->
<!-- '\" The descriptions below of the various SCons Builders are generated -->
<!-- '\" from the .xml files located together with the various Python -->
<!-- '\" builder modules in the build engine directory -->
<!-- '\" BEGIN GENERATED BUILDER DESCRIPTIONS -->
<!-- '\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -->
<xsi:include xmlns:xsi="http://www.w3.org/2001/XInclude" href="../generated/builders.gen"/>
<!-- '\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -->
<!-- '\" END GENERATED BUILDER DESCRIPTIONS -->
<!-- '\" The descriptions abocve of the various SCons Builders are generated -->
<!-- '\" from the .xml files located together with the various Python -->
<!-- '\" builder modules in the build engine directory -->
<!-- '\" END GENERATED BUILDER DESCRIPTIONS -->
<!-- '\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -->
<para>All
targets of builder methods automatically depend on their sources.
An explicit dependency can
be specified using the
&f-link-env-Depends;
method of a &consenv; (see below).</para>
<para>In addition,
&scons;
automatically scans
source files for various programming languages,
so the dependencies do not need to be specified explicitly.
By default, SCons can
C source files,
C++ source files,
Fortran source files with
<filename>.F</filename>
(POSIX systems only),
<filename>.fpp</filename>,
or
<filename>.FPP</filename>
file extensions,
and assembly language files with
<filename>.S</filename>
(POSIX systems only),
<filename>.spp</filename>,
or
<filename>.SPP</filename>
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
&b-link-Object;, &b-link-StaticObject; and &b-link-SharedObject;
Builders by adding them
to the
<classname>SourceFileScanner</classname>
object.
See <xref linkend="scanner_objects"/>
for more information about
defining your own Scanner objects
and using the
<classname>SourceFileScanner</classname>
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,
&scons;
provides a number of other &consenv; methods
and global functions to
manipulate the build configuration.</para>
<para>Usually, a &consenv; method
and global function with the same name both exist
for convenience.
In the following list, the global function
is documented in this style:</para>
<programlisting language="python">
<function>Function</function>(<parameter>arguments, [optional arguments]</parameter>)
</programlisting>
<para>and the &consenv; method looks like:</para>
<programlisting language="python">
<replaceable>env</replaceable>.<methodname>Function</methodname>(<parameter>arguments, [optional arguments]</parameter>)
</programlisting>
<para>If the function can be called both ways,
then both forms are listed.</para>
<para>The global function and same-named
&consenv; method
provide almost identical functionality, with a couple of exceptions.
First, many of the &consenv; methods affect only that
&consenv;, while the global function has a
global effect. Second, where appropriate,
calling the functionality through a &consenv; will
substitute &consvars; into
any supplied string arguments, while the global function doesn't have the
context of a &consenv; to pick variables from,
so it cannot perform the substitution.
For example:</para>
<programlisting language="python">
Default('$FOO')
env = Environment(FOO='foo')
env.Default('$FOO')
</programlisting>
<para>In the above example,
the call to the global &f-Default;
function will add a target named
<emphasis role="bold">$FOO</emphasis>
to the list of default targets,
while the call to the
&f-env-Default; &consenv; method
will expand the value
and add a target named
<emphasis role="bold">foo</emphasis>
to the list of default targets.
For more on &consvar; expansion,
see the next section on
&consvars;.</para>
<para>Global functions may be called from custom Python modules that you
import into an SConscript file by adding the following import
to the Python module:</para>
<programlisting language="python">
from SCons.Script import *
</programlisting>
<para>&Consenv; methods
and global functions provided by
&scons;
include:</para>
<!-- '\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -->
<!-- '\" BEGIN GENERATED FUNCTION DESCRIPTIONS -->
<!-- '\" The descriptions below of the various SCons Tools are generated -->
<!-- '\" from the .xml files located together with the various Python -->
<!-- '\" modules in the build engine directory -->
<!-- '\" 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 Tools are generated -->
<!-- '\" from the .xml files located together with the various Python -->
<!-- '\" modules in the build engine directory -->
<!-- '\" END GENERATED FUNCTION DESCRIPTIONS -->
<!-- '\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -->
</refsect2>
<refsect2 id='sconscript_variables'>
<title>SConscript Variables</title>
<para>In addition to the global functions and methods,
&scons;
supports a number of variables
that can be used in SConscript files
to affect how you want the build to be performed.</para>
<variablelist>
<varlistentry>
<term>&ARGLIST;</term>
<listitem>
<para>A list of the
<emphasis>keyword</emphasis>=<emphasis>value</emphasis>
arguments specified on the command line.
Each element in the list is a tuple
containing the argument.
The separate
<emphasis>keyword</emphasis>
and
<emphasis>value</emphasis>
elements of the tuple
can be accessed by
subscripting for elements
<emphasis role="bold">[0]</emphasis>
and
<emphasis role="bold">[1]</emphasis>
of the tuple, or, more readably, by using tuple unpacking.
Example:</para>
<programlisting language="python">
print("first keyword, value =", ARGLIST[0][0], ARGLIST[0][1])
print("second keyword, value =", ARGLIST[1][0], ARGLIST[1][1])
key, value = ARGLIST[2]
print("third keyword, value =", key, value)
for key, value in ARGLIST:
# process key and value
</programlisting>
</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 &ARGUMENTS;
dictionary.</para>
<para>Example:</para>
<programlisting language="python">
if ARGUMENTS.get('debug', 0):
env = Environment(CCFLAGS='-g')
else:
env = Environment()
</programlisting>
</listitem>
</varlistentry>
<varlistentry>
<term>&BUILD_TARGETS;</term>
<listitem>
<para>A list of the targets which
&scons;
has been asked to build.
The contents will be either those targets listed
on the command line, or, if none, those targets set
via calls to the &f-link-Default; function.
It does
<emphasis>not</emphasis>
contain any dependent targets that &scons;
selects for building as a result of making the sure the
specified targets are up to date, if those targets
did not appear on the command line.
The list is empty if neither
command line targets or &Default; calls are present.
</para>
<para>
The elements of this list may be strings
<emphasis>or</emphasis>
nodes, so you should run the list through the Python
<function>str</function>
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
&Default; function,
the contents of the list may change
on each successive call to &Default;.
See the
&DEFAULT_TARGETS; list, below,
for additional information.</para>
<para>Example:</para>
<programlisting language="python">
if 'foo' in BUILD_TARGETS:
print("Don't forget to test the `foo' program!")
if 'special/program' in BUILD_TARGETS:
SConscript('special')
</programlisting>
</listitem>
</varlistentry>
<varlistentry>
<term>&COMMAND_LINE_TARGETS;</term>
<listitem>
<para>A list of the targets explicitly specified on
the command line. If there are command line targets,
this list will have the same contents as &BUILD_TARGETS;.
If there are no targets specified on the command line,
the list is empty. The elements of this list are strings.
This can be used, for example,
to take specific actions only
when certain targets are explicitly being built.</para>
<para>Example:</para>
<programlisting language="python">
if 'foo' in COMMAND_LINE_TARGETS:
print("Don't forget to test the `foo' program!")
if 'special/program' in COMMAND_LINE_TARGETS:
SConscript('special')
</programlisting>
</listitem>
</varlistentry>
<varlistentry>
<term>&DEFAULT_TARGETS;</term>
<listitem>
<para>A list of the target
<emphasis>nodes</emphasis>
that have been specified using the
&f-link-Default;
function. If there are no command line
targets, this list will have the same contents as
&BUILD_TARGETS;.
Since the elements of the list are nodes,
you need to call the Python
<function>str</function>
function on them to get the path name for each Node.</para>
<para>Example:</para>
<programlisting language="python">
print(str(DEFAULT_TARGETS[0]))
if 'foo' in [str(t) for t in DEFAULT_TARGETS]:
print("Don't forget to test the `foo' program!")
</programlisting>
<para>The contents of the
&DEFAULT_TARGETS;
list change on on each successive call to the
&Default; function:</para>
<programlisting language="python">
print([str(t) for t in DEFAULT_TARGETS]) # originally []
Default('foo')
print([str(t) for t in DEFAULT_TARGETS]) # now a node ['foo']
Default('bar')
print([str(t) for t in DEFAULT_TARGETS]) # now a node ['foo', 'bar']
Default(None)
print([str(t) for t in DEFAULT_TARGETS]) # back to []
</programlisting>
<para>Consequently, be sure to use
&DEFAULT_TARGETS;
only after you've made all of your
&Default;() calls,
or else simply be careful of the order
of these statements in your SConscript files
so that you don't look for a specific
default target before it's actually been added to the list.</para>
</listitem>
</varlistentry>
</variablelist>
<para>
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>
<programlisting language="python">
from SCons.Script import *
</programlisting>
</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 &consenv; has an associated dictionary of
<firstterm>&consvars;</firstterm>
that are used by built-in or user-supplied build rules.
&Consvar; naming must follow the same rules as for
Python identifiers:
the initial character must be an underscore or letter,
followed by any number of underscores, letters, or digits.</para>
<para>A &consenv; is not a Python dictionary,
but it can be indexed like one to access a
&consvar;:</para>
<programlisting language="python">
env["CC"] = "cc"
</programlisting>
<para>&Consvars; can also be retrieved and set
by using the &f-link-Dictionary;
method of the &consenv; to create an actual
dictionary:</para>
<programlisting language="python">
cvars = env.Dictionary()
cvars["CC"] = "cc"
</programlisting>
<para>&Consvars; can also be passed to the &consenv;
constructor:</para>
<programlisting language="python">
env = Environment(CC="cc")
</programlisting>
<para>or when copying a &consenv; using the
&f-link-Clone; method:</para>
<programlisting language="python">
env2 = env.Clone(CC="cl.exe")
</programlisting>
<para>A number of useful &consvars; are automatically defined by
scons for each supported platform, and additional &consvars;
can be defined by the user. The following is a list of the possible
automatically defined &consvars;. The actual list available
at execution time will not include all of these, as the ones
detected as not being useful (wrong platform, necessary
external command or files not installed, etc.) will not be set up.
:</para>
<!-- '\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -->
<!-- '\" BEGIN GENERATED CONSTRUCTION VARIABLE DESCRIPTIONS -->
<!-- '\" The descriptions below of the various SCons construction variables -->
<!-- '\" are generated from the .xml files located together with the various -->
<!-- '\" Python modules in the build engine directory -->
<!-- '\" 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 located together with the various -->
<!-- '\" Python modules in the build engine directory -->
<!-- '\" END GENERATED CONSTRUCTION VARIABLE DESCRIPTIONS -->
<!-- '\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -->
</refsect2>
<refsect2 id='configure_contexts'>
<title>Configure Contexts</title>
<para>&SCons;
supports a
<firstterm>&configure_context;</firstterm>,
an integrated mechanism similar to the
various <constant>AC_CHECK</constant> macros in GNU &Autoconf;
for testing the existence of external items needed
for the build, such as C header files, libraries, etc.
The mechanism is portable across platforms.
</para>
<para>
&scons;
does not maintain an explicit cache of the tested values
(this is different than &Autoconf;),
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>
<variablelist>
<varlistentry>
<term><function>Configure</function>(<parameter>env, [custom_tests, conf_dir, log_file, config_h, clean, help]</parameter>)</term>
<term><replaceable>env</replaceable>.<methodname>Configure</methodname>(<parameter>[custom_tests, conf_dir, log_file, config_h, clean, help]</parameter>)</term>
<listitem>
<para>Create a &configure_context;, which tracks information
discovered while running tests. The context includes a local &consenv;
(available as <replaceable>context</replaceable>.<varname>env</varname>)
which is used when running the tests and
which can be updated with the check results.
Only one context may be active
at a time (<emphasis>since 4.0, &scons; will raise an exception
on an attempt to create a new context when there is
an active context</emphasis>), but a new context can be created
after the active one is completed.
For the global function form, the required <parameter>env</parameter>
describes the initial values for the context's local &consenv;;
for the &consenv; method form the instance provides the values.
</para>
<para><parameter>custom_tests</parameter>
specifies a dictionary containing custom tests
(see the section on custom tests below).
The default value is <constant>None</constant>,
meaning no custom tests are added to the &configure_context;.</para>
<para>
<parameter>conf_dir</parameter>
specifies a directory where the test cases are built.
This directory is not used for building normal targets.
The default value is
<quote><filename>#/.sconf_temp</filename></quote>.</para>
<para>
<parameter>log_file</parameter>
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 <quote><filename>#/config.log</filename></quote>.
If you are using the
&VariantDir; function,
you may want to specify a subdirectory under your variant directory.</para>
<para>
<parameter>config_h</parameter>
specifies a C header file where the results of tests
will be written. The results will consist of lines like
<literal>#define HAVE_STDIO_H</literal>,
<literal>#define HAVE_LIBM</literal>, etc.
Customarily, the name chosen is <quote><filename>config.h</filename></quote>.
The default is to not write a
<parameter>config_h</parameter>
file.
You can specify the same
<parameter>config_h</parameter>
file in multiple calls to &Configure;,
in which case &SCons;
will concatenate all results in the specified file.
Note that &SCons;
uses its normal dependency checking
to decide if it's necessary to rebuild
the specified
<parameter>config_h</parameter>
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
<parameter>config_h</parameter>
file is being built.</para>
<para>The <parameter>clean</parameter>
and
<parameter>help</parameter>
arguments can be used to suppress execution of the configuration
tests when the
<option>-c</option>/<option>--clean</option>
or
<option>-H</option>/<option>-h</option>/<option>--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
<option>clean=False</option>
or
<option>help=False</option>
arguments
(or both)
to avoid unnecessary test execution.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>SConf</literal>.<function>Finish</function>(<parameter>context</parameter>)</term>
<term><replaceable>context</replaceable>.<methodname>Finish</methodname>()</term>
<listitem>
<para>This method must be called after configuration is done.
Though required, this is not enforced except
if &Configure; is called again while there is still an active context,
in which case an exception is raised.
&Finish; returns the environment as modified
during the course of running the configuration checks.
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.
</para>
</listitem>
</varlistentry>
</variablelist>
<para>Example of a typical Configure usage:</para>
<programlisting language="python">
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()
</programlisting>
<para>A &configure_context;
has the following predefined methods which
can be used to perform checks. Where
<parameter>language</parameter> is a required or
optional parameter, the choice can currently
be C or C++. The spellings accepted for
C are <quote>C</quote> or <quote>c</quote>;
for C++ the value can be
<quote>CXX</quote>, <quote>cxx</quote>, <quote>C++</quote>
or <quote>c++</quote>.
</para>
<variablelist>
<varlistentry>
<term><literal>SConf</literal>.<function>CheckHeader</function>(<parameter>context, header, [include_quotes, language]</parameter>)</term>
<term><replaceable>context</replaceable>.<methodname>CheckHeader</methodname>(<parameter>header, [include_quotes, language]</parameter>)</term>
<listitem>
<para>Checks if
<parameter>header</parameter>
is usable in the specified language.
<parameter>header</parameter>
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
<literal>#include</literal>
lines should precede the
header line being checked for.
The optional argument
<parameter>include_quotes</parameter>
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 <markup>"</markup> (double quote).
The optional argument
<parameter>language</parameter>
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 a boolean indicating success or failure.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>SConf</literal>.<function>CheckCHeader</function>(<parameter>context, header, [include_quotes]</parameter>)</term>
<term><replaceable>context</replaceable>.<methodname>CheckCHeader</methodname>(<parameter>header, [include_quotes]</parameter>)</term>
<listitem>
<para>This is a wrapper around
<function>SConf.CheckHeader</function>
which checks if
<parameter>header</parameter>
is usable in the C language.
<parameter>header</parameter>
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
<literal>#include</literal>
lines should precede the
header line being checked for.
The optional argument
<parameter>include_quotes</parameter>
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 <markup>"</markup> (double quote).
Returns a boolean indicating success or failure.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>SConf</literal>.<function>CheckCXXHeader</function>(<parameter>context, header, [include_quotes]</parameter>)</term>
<term><replaceable>context</replaceable>.<methodname>CheckCXXHeader</methodname>(<parameter>header, [include_quotes]</parameter>)</term>
<listitem>
<para>This is a wrapper around
<function>SConf.CheckHeader</function>
which checks if
<parameter>header</parameter>
is usable in the C++ language.
<parameter>header</parameter>
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
<literal>#include</literal>
lines should precede the
header line being checked for.
The optional argument
<parameter>include_quotes</parameter>
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 <markup>"</markup> (double quote).
Returns a boolean indicating success or failure.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>SConf</literal>.<function>CheckFunc</function>(<parameter>context, function_name, [header, language]</parameter>)</term>
<term><replaceable>context</replaceable>.<methodname>CheckFunc</methodname>(<parameter>function_name, [header, language]</parameter>)</term>
<listitem>
<para>Checks if the specified
C or C++ library function is available based on the
context's local environment settings (that is, using
the values of <varname>CFLAGS</varname>,
<varname>CPPFLAGS</varname>, <varname>LIBS</varname>
or other relevant &consvars;).
</para>
<para>
<parameter>function_name</parameter>
is the name of the function to check for.
The optional
<parameter>header</parameter>
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>
<programlisting language="C">
#ifdef __cplusplus
extern "C"
#endif
char function_name();
</programlisting>
<para>
Returns an empty string on success, a string containing
an error message on failure.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>SConf</literal>.<function>CheckLib</function>(<parameter>context, [library, symbol, header, language, autoadd=True]</parameter>)</term>
<term><replaceable>context</replaceable>.<methodname>CheckLib</methodname>(<parameter>[library, symbol, header, language, autoadd=True]</parameter>) </term>
<listitem>
<para>Checks if
<parameter>library</parameter>
provides
<parameter>symbol</parameter>.
If
<parameter>autoadd</parameter>
is true (the default) and the library provides the specified
<parameter>symbol</parameter>,
appends the library to the <varname>LIBS</varname> &consvar;
<parameter>library</parameter>
may also be <constant>None</constant> (the default),
in which case
<parameter>symbol</parameter>
is checked with the current <varname>LIBS</varname> variable,
or a list of library names,
in which case each library in the list
will be checked for
<parameter>symbol</parameter>.
If
<parameter>symbol</parameter>
is not set or is
<constant>None</constant>,
then
<function>SConf.CheckLib</function>
just checks if
you can link against the specified
<parameter>library</parameter>.
Note though it is legal syntax, it would
not be very useful to call this method
with <parameter>library</parameter>
and <parameter>symbol</parameter> both
omitted or <constant>None</constant>.
Returns a boolean indicating success or failure.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>SConf</literal>.<function>CheckLibWithHeader</function>(<parameter>context, library, header, language, [call, autoadd=True]</parameter>)</term>
<term><replaceable>context</replaceable>.<methodname>CheckLibWithHeader</methodname>(<parameter>library, header, language, [call, autoadd=True]</parameter>)</term>
<listitem>
<para>Provides a more sophisticated way to check against libraries then the
<function>SConf.CheckLib</function> call.
<parameter>library</parameter>
specifies the library or a list of libraries to check.
<parameter>header</parameter>
specifies a header to check for.
<parameter>header</parameter>
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
<literal>#include</literal>
lines should precede the
header line being checked for.
<parameter>call</parameter>
can be any valid expression (with a trailing ';').
If
<parameter>call</parameter>
is not set,
the default simply checks that you
can link against the specified
<parameter>library</parameter>.
<parameter>autoadd</parameter> (default true)
specifies whether to add the library to the environment if the check
succeeds.
Returns a boolean indicating success or failure.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>SConf</literal>.<function>CheckType</function>(<parameter>context, type_name, [includes, language]</parameter>)</term>
<term><replaceable>context</replaceable>.<methodname>CheckType</methodname>(<parameter>type_name, [includes, language]</parameter>)</term>
<listitem>
<para>Checks for the existence of a type defined by
<literal>typedef</literal>.
<parameter>type_name</parameter>
specifies the typedef name to check for.
<parameter>includes</parameter>
is a string containing one or more
<literal>#include</literal>
lines that will be inserted into the program
that will be run to test for the existence of the type.
Example:</para>
<programlisting language="python">
sconf.CheckType('foo_type', '#include "my_types.h"', 'C++')
</programlisting>
<para>
Returns an empty string on success, a string containing
an error message on failure.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>SConf</literal>.<function>CheckCC</function>(<parameter>context</parameter>)</term>
<term><replaceable>context</replaceable>.<methodname>CheckCC</methodname>()</term>
<listitem>
<para>Checks whether the C compiler (as defined by the
<varname>CC</varname> &consvar;) works
by trying to compile a small source file.
Returns a boolean indicating success or failure.</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 as the one used by the object builder for C
source files, so it can be used to detect if a particular compiler flag works or
not.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>SConf</literal>.<function>CheckCXX</function>(<parameter>context</parameter>)</term>
<term><replaceable>context</replaceable>.<methodname>CheckCXX</methodname>()</term>
<listitem>
<para>Checks whether the C++ compiler (as defined by the
<varname>CXX</varname> &consvar;)
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.
Returns a boolean indicating success or failure.</para>
<para>This uses the exact same command as the one used by the object builder for
C++ source files, so it can be used to detect if a particular compiler flag
works or not.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>SConf</literal>.<function>CheckSHCC</function>(<parameter>context</parameter>)</term>
<term><replaceable>context</replaceable>.<methodname>CheckSHCC</methodname>()</term>
<listitem>
<para>Checks whether the shared-object C compiler (as defined by the
<varname>SHCC</varname> &consvar;) 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.
Returns a boolean indicating success or failure.</para>
<para>This uses the exact same command as 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><literal>SConf</literal>.<function>CheckSHCXX</function>(<parameter>context</parameter>)</term>
<term><replaceable>context</replaceable>.<methodname>CheckSHCXX</methodname>()</term>
<listitem>
<para>Checks whether the shared-object C++ compiler (as defined by the
<varname>SHCXX</varname> &consvar;)
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.
Returns a boolean indicating success or failure.</para>
<para>This uses the exact same command as the one used by the object builder for
C++ 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>
<varlistentry>
<term><literal>SConf</literal>.<function>CheckTypeSize</function>(<parameter>context, type_name, [header, language, expect]</parameter>)</term>
<term><replaceable>context</replaceable>.<methodname>CheckTypeSize</methodname>(<parameter>type_name, [header, language, expect]</parameter>)</term>
<listitem>
<para>Checks for the size of a type defined by
<literal>typedef</literal>.
<parameter>type_name</parameter>
specifies the typedef name to check for.
The optional
<parameter>header</parameter>
argument is a string
that will be
placed at the top
of the test file
that will be compiled
to check if the type exists;
the default is empty.
If the optional
<parameter>expect</parameter>,
is supplied, it should be an integer size;
&CheckTypeSize; will fail unless
<parameter>type_name</parameter> is actually
that size.
Returns the size in bytes, or zero if the type was not found
(or if the size did not match <parameter>expect</parameter>).</para>
<para>
For example,</para>
<programlisting language="python">
CheckTypeSize('short', expect=2)
</programlisting>
<para>will return the size <literal>2</literal> only if short is
actually two bytes.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>SConf</literal>.<function>CheckDeclaration</function>(<parameter>context, symbol, [includes, language]</parameter>)</term>
<term><replaceable>context</replaceable>.<methodname>CheckDeclaration</methodname>(<parameter>symbol, [includes, language]</parameter>)</term>
<listitem>
<para>Checks if the specified
<parameter>symbol</parameter>
is declared.
<parameter>includes</parameter>
is a string containing one or more
<literal>#include</literal>
lines that will be inserted into the program
that will be run to test for the existence of the symbol.
Returns a boolean indicating success or failure.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>SConf</literal>.<function>Define</function>(<parameter>context, symbol, [value, comment]</parameter>)</term>
<term><replaceable>context</replaceable>.<methodname>Define</methodname>(<parameter>symbol, [value, comment]</parameter>)</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 <constant>AC_DEFINE</constant>,
and defines the symbol
<parameter>name</parameter>
with the optional
<parameter>value</parameter>
and the optional comment
<parameter>comment</parameter>.</para>
<para>Define Examples:</para>
<programlisting language="python">
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 language="python">
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 language="python">
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>
</listitem>
</varlistentry>
</variablelist>
<para>You can define your own custom checks
in addition to the predefined checks.
You pass a dictionary of these
to the &Configure; function
as the <parameter>custom_tests</parameter> argument.
This dictionary maps the names of the checks
to the user defined Python callables
(either Python functions or class instances implementing a
<methodname>__call__</methodname>
method).
Each custom check will be called with a first
argument of a <emphasis>CheckContext</emphasis>,
instance followed by the arguments,
which must be supplied by the user of the check.
A CheckContext instance defines the following methods:</para>
<variablelist>
<varlistentry>
<term><replaceable>context</replaceable>.<methodname>Message</methodname>(<parameter>text</parameter>)</term>
<listitem>
<para>Displays a message, as an indicator of progess.
<parameter>text</parameter>
will be displayed, e.g.
<computeroutput>Checking for library X...</computeroutput>.
Usually called before the check is started.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable>context</replaceable>.<methodname>Result</methodname>(<parameter>res</parameter>)</term>
<listitem>
<para>Displays a <quote>result</quote> message, as an indicator of progress.
<parameter>res</parameter>
can be either an integer or a string. If an integer, displays
<computeroutput>yes</computeroutput>
(if <parameter>res</parameter> evaluates <constant>True</constant>)
or <computeroutput>no</computeroutput>
(if <parameter>res</parameter> evaluates <constant>False</constant>).
If a string, it is displayed as-is.
Usually called after the check has completed.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable>context</replaceable>.<methodname>TryCompile</methodname>(<parameter>text, extension=''</parameter>)</term>
<listitem>
<para>Checks if a file with the specified
<parameter>extension</parameter>
(e.g. '.c') containing
<parameter>text</parameter>
can be compiled using the environment's
&Object; builder.
Returns a boolean indicating success or failure.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable>context</replaceable>.<methodname>TryLink</methodname>(<parameter>text, extension=''</parameter>)</term>
<listitem>
<para>Checks, if a file with the specified
<parameter>extension</parameter>
(e.g. '.c') containing
<parameter>text</parameter>
can be compiled using the environment's &Program; builder.
Returns a boolean indicating success or failure.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable>context</replaceable>.<methodname>TryRun</methodname>(<parameter>text, extension=''</parameter>)</term>
<listitem>
<para>Checks if a file with the specified
<parameter>extension</parameter>
(e.g. '.c') containing
<parameter>text</parameter>
can be compiled using the environment's
&Program; 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
<varname>outputStr</varname>
is the standard output of the
program.
If the program fails execution
(its return status is non-zero),
then <emphasis>(0, '')</emphasis> is returned.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable>context</replaceable>.<methodname>TryAction</methodname>(<parameter>action, [text, extension='']</parameter>)</term>
<listitem>
<para>Checks if the specified
<parameter>action</parameter>
with an optional source file (contents
<parameter>text</parameter>,
extension
<parameter>extension</parameter>)
can be executed.
<parameter>action</parameter>
may be anything which can be converted to a
&scons;
Action.
On success,
<emphasis>(1, outputStr)</emphasis>
is returned, where
<varname>outputStr</varname>
is the content of the target file.
On failure
<emphasis>(0, '')</emphasis>
is returned.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable>context</replaceable>.<methodname>TryBuild</methodname>(<parameter>builder[, text, extension='']</parameter>)</term>
<listitem>
<para>Low level implementation for testing specific builds;
the methods above are based on this method.
Given the Builder instance
<parameter>builder</parameter>
and the optional
<parameter>text</parameter>
of a source file with optional
<parameter>extension</parameter>,
returns a boolean indicating success or failure.
In addition,
<varname>context.lastTarget</varname>
is set to the build target node if the build was successful.</para>
</listitem>
</varlistentry>
</variablelist>
<para>Example of implementing and using custom tests:</para>
<programlisting language="python">
def CheckQt(context, qtdir):
context.Message( 'Checking for qt ...' )
lastLIBS = context.env['LIBS']
lastLIBPATH = context.env['LIBPATH']
lastCPPPATH= context.env['CPPPATH']
context.env.Append(LIBS='qt', LIBPATH=qtdir + '/lib', CPPPATH=qtdir + '/include')
ret = context.TryLink("""
#include <qapp.h>
int main(int argc, char **argv) {
QApplication qapp(argc, argv);
return 0;
}
""")
if not ret:
context.env.Replace(LIBS=lastLIBS, LIBPATH=lastLIBPATH, CPPPATH=lastCPPPATH)
context.Result( ret )
return ret
env = Environment()
conf = Configure(env, custom_tests={'CheckQt': CheckQt})
if not conf.CheckQt('/usr/lib/qt'):
print('We really need qt!')
Exit(1)
env = conf.Finish()
</programlisting>
</refsect2>
<refsect2 id='commandline_construction_variables'>
<title>Command-Line Construction Variables</title>
<para>Often when building software,
some variables need to 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.
&SCons;
provides a <firstterm>&Variables;</firstterm>
object to support overriding &consvars;
on the command line:</para>
<screen>
<userinput>scons VARIABLE=foo</userinput>
</screen>
<para>The variable values can also be specified in an SConscript file.</para>
<para>To obtain the object for manipulating values,
call the &Variables; function:</para>
<variablelist>
<varlistentry>
<term><function>Variables</function>([<parameter>files, [args]]</parameter>)</term>
<listitem>
<para>If <parameter>files</parameter> is a file or
list of files, those are executed as Python scripts,
and the values of (global) Python variables set in
those files are added as &consvars; in the &DefEnv;.
If no files are specified,
or the
<parameter>files</parameter>
argument is
<constant>None</constant>,
then no files will be read. The following example file
contents could be used to set an alternative C compiler:</para>
<programlisting language="python">
CC = 'my_cc'
</programlisting>
<para>If
<parameter>args</parameter>
is specified, it is a dictionary of
values that will override anything read from
<parameter>files</parameter>.
it is primarily intended to be passed the
&ARGUMENTS; dictionary that holds variables
specified on the command line.
Example:</para>
<programlisting language="python">
vars = Variables('custom.py')
vars = Variables('overrides.py', ARGUMENTS)
vars = Variables(None, {FOO:'expansion', BAR:7})
</programlisting>
</listitem>
</varlistentry>
</variablelist>
<para>Variables objects have the following methods:</para>
<variablelist>
<varlistentry>
<term><replaceable>vars</replaceable>.<function>Add</function>(<parameter>key, [help, default, validator, converter]</parameter>)</term>
<listitem>
<para>Add a customizable &consvar; to the Variables object.
<parameter>key</parameter>
is the name of the variable.
<parameter>help</parameter>
is the help text for the variable.
<parameter>default</parameter>
is the default value of the variable;
if the default value is
<constant>None</constant>
and there is no explicit value specified,
the &consvar; will not
be added to the &consenv;.
If set, <parameter>validator</parameter>
is called to validate the value of the variable.
A function supplied as a validator shall accept
arguments: <parameter>key</parameter>,
<parameter>value</parameter>, and <parameter>env</parameter>.
The recommended way to handle an invalid value is
to raise an exception (see example below).
If set, <parameter>converter</parameter>
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 converter function must return a value,
which will be converted into a string
before being validated by the
<parameter>validator</parameter>
(if any)
and then added to the &consenv;.</para>
<para>Examples:</para>
<programlisting language="python">
vars.Add('CC', help='The C compiler')
def valid_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><replaceable>vars</replaceable>.<function>AddVariables</function>(<parameter>args</parameter>)</term>
<listitem>
<para>A convenience method that adds
multiple customizable &consvars;
to a Variables object in one call;
equivalent to calling &Add; multiple times.
The <parameter>args</parameter>
are tuples (or lists)
that contain the arguments
for an individual call to the &Add; method.
Since tuples are not Python mappings,
the arguments cannot use the keyword form,
but rather are positional arguments as documented
for &Add;: a required name, the rest optional
but must be in the specified in order if used.
</para>
<programlisting language="python">
opt.AddVariables(
("debug", "", 0),
("CC", "The C compiler"),
("VALIDATE", "An option for testing validation", "notset", validator, None),
)
</programlisting>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable>vars</replaceable>.<function>Update</function>(<parameter>env, [args]</parameter>)</term>
<listitem>
<para>Update a &consenv;
<parameter>env</parameter>
with the customized &consvars; .
Any specified variables that are not
configured for the Variables object
will be saved and may be
retrieved using the
&UnknownVariables;
method, below.</para>
<para>Normally this method is not called directly,
but rather invoked indirectly by passing the Variables object to
the &f-link-Environment; function:</para>
<programlisting language="python">
env = Environment(variables=vars)
</programlisting>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable>vars</replaceable>.<function>UnknownVariables</function>()</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>
<programlisting language="python">
env = Environment(variables=vars)
for key, value in vars.UnknownVariables():
print("unknown variable: %s=%s" % (key, value))
</programlisting>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable>vars</replaceable>.<function>Save</function>(<parameter>filename, env</parameter>)</term>
<listitem>
<para>Save the currently set variables into a script file named
by <parameter>filename</parameter>
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>
<programlisting language="python">
env = Environment()
vars = Variables(['variables.cache', 'custom.py'])
vars.Add(...)
vars.Update(env)
vars.Save('variables.cache', env)
</programlisting>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable>vars</replaceable>.<function>GenerateHelpText</function>(<parameter>env, [sort]</parameter>)</term>
<listitem>
<para>Generate help text documenting the customizable construction
variables, suitable for passing in to the &f-link-Help; function.
<parameter>env</parameter>
is the &consenv; that will be used to get the actual values
of the customizable variables. If the (optional)
value of <parameter>sort</parameter>
is callable, it is used as a comparison function to
determine how to sort the added variables.
This function must accept two arguments, compare them,
and return a negative integer if the first is
less-than the second, zero for equality, or a positive integer
for greater-than.
Optionally a Boolean value of <constant>True</constant>
for <parameter>sort</parameter> will cause a standard
alphabetical sort to be performed.</para>
<programlisting language="python">
Help(vars.GenerateHelpText(env))
def cmp(a, b):
return (a > b) - (a < b)
Help(vars.GenerateHelpText(env, sort=cmp))
</programlisting>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable>vars</replaceable>.<function>FormatVariableHelpText</function>(<parameter>env, opt, help, default, actual</parameter>)</term>
<listitem>
<para>Returns a formatted string
containing the printable help text
for one option.
It is normally not called directly,
but is called by the &GenerateHelpText;
method to create the returned help text.
It may be overridden with your own
function that takes the arguments specified above
and returns a string of help text formatted to your liking.
Note that &GenerateHelpText;
will not put any blank lines or extra
characters in between the entries,
so you must add those characters to the returned
string if you want the entries separated.</para>
<programlisting language="python">
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>
</listitem>
</varlistentry>
</variablelist>
<para>To make it more convenient to work with customizable Variables,
&scons;
provides a number of functions
that make it easy to set up
various types of Variables.
Each of these return a tuple ready to be passed to
the &Add; or &AddVariables; method:</para>
<variablelist>
<varlistentry>
<term><function>BoolVariable</function>(<parameter>key, help, default</parameter>)</term>
<listitem>
<para>Returns a tuple of arguments
to set up a Boolean option.
The option will use
the specified name
<parameter>key</parameter>,
have a default value of
<parameter>default</parameter>,
and <parameter>help</parameter>
will form the descriptive part of the help text.
The option will interpret the values
<userinput>y</userinput>,
<userinput>yes</userinput>,
<userinput>t</userinput>,
<userinput>true</userinput>,
<userinput>1</userinput>,
<userinput>on</userinput>
and
<userinput>all</userinput>
as true,
and the values
<userinput>n</userinput>,
<userinput>no</userinput>,
<userinput>f</userinput>,
<userinput>false</userinput>,
<userinput>0</userinput>,
<userinput>off</userinput>
and
<userinput>none</userinput>
as false.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><function>EnumVariable</function>(<parameter>key, help, default, allowed_values, [map, ignorecase]</parameter>)</term>
<listitem>
<para>Returns 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
<parameter>key</parameter>,
have a default value of
<parameter>default</parameter>,
and <parameter>help</parameter>
will form the descriptive part of the help text.
The option will only support those
values in the
<parameter>allowed_values</parameter>
list.
The optional
<parameter>map</parameter>
argument is a dictionary
that can be used to convert
input values into specific legal values
in the
<parameter>allowed_values</parameter>
list.
If the value of
<parameter>ignore_case</parameter>
is
<literal>0</literal>
(the default),
then the values are case-sensitive.
If the value of
<parameter>ignore_case</parameter>
is
<literal>1</literal>,
then values will be matched
case-insensitively.
If the value of
<parameter>ignore_case</parameter>
is
<literal>2</literal>,
then values will be matched
case-insensitively,
and all input values will be
converted to lower case.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><function>ListVariable</function>(<parameter>key, help, default, names, [map]</parameter>)</term>
<listitem>
<para>Returns 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
<parameter>key</parameter>,
have a default value of
<parameter>default</parameter>,
and <parameter>help</parameter>
will form the descriptive part of the help text.
The option will only accept the values
<quote>all</quote>,
<quote>none</quote>,
or the values in the
<parameter>names</parameter>
list.
More than one value may be specified,
separated by commas.
The default may be a string of
comma-separated default values,
or a list of the default values.
The optional
<parameter>map</parameter>
argument is a dictionary
that can be used to convert
input values into specific legal values
in the
<parameter>names</parameter>
list.
(Note that the additional values accepted through
the use of a <parameter>map</parameter> are not
reflected in the generated help message). </para>
</listitem>
</varlistentry>
<varlistentry>
<term><function>PackageVariable</function>(<parameter>key, help, default</parameter>)</term>
<listitem>
<para>Returns 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
<parameter>key</parameter>,
have a default value of
<parameter>default</parameter>,
and <parameter>help</parameter>
will form the descriptive part of the help text.
The option will support the values
<userinput>yes</userinput>,
<userinput>true</userinput>,
<userinput>on</userinput>,
<userinput>enable</userinput>
or
<userinput>search</userinput>,
in which case the specified
<parameter>default</parameter>
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
<userinput>no</userinput>,
<userinput>false</userinput>,
<userinput>off</userinput>
or
<userinput>disable</userinput>
to disable use of the specified option.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><function>PathVariable</function>(<parameter>key, help, default, [validator]</parameter>)</term>
<listitem>
<para>Returns 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
<parameter>key</parameter>,
have a default value of
<parameter>default</parameter>,
and <parameter>help</parameter>
will form the descriptive part of the help text.
An additional
<parameter>validator</parameter>
may be specified
that will be called to
verify that the specified path
is acceptable.
SCons supplies the
following ready-made validators:</para>
<variablelist> <!-- nested list -->
<varlistentry>
<term><literal>PathVariable</literal>.<function>PathExists</function></term>
<listitem>
<para>Verify that the specified path exists
(this the default behavior if no
<parameter>validator</parameter> is supplied).</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>PathVariable</literal>.<function>PathIsFile</function></term>
<listitem>
<para>Verify that the specified path exists and is a regular file.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>PathVariable</literal>.<function>PathIsDir</function></term>
<listitem>
<para>Verify that the specified path exists and is a directory.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>PathVariable</literal>.<function>PathIsDirCreate</function></term>
<listitem>
<para>Verify that the specified path exists and is a directory;
if it does not exist, create the directory.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>PathVariable</literal>.<function>PathAccept</function></term>
<listitem>
<para>Accept the specific path name argument without validation,
suitable for when you want your users
to be able to specify a directory path that will be
created as part of the build process, for example.</para>
</listitem>
</varlistentry>
</variablelist> <!-- end nested list -->
<para>
You may supply your own
<emphasis>validator</emphasis>
function,
which must accept three arguments
(<parameter>key</parameter>,
the name of the variable to be set;
<parameter>val</parameter>,
the specified value being checked;
and
<parameter>env</parameter>,
the &consenv;)
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 &AddVariables;
method:</para>
<programlisting language="python">
vars.AddVariables(
BoolVariable(
"warnings",
help="compilation with -Wall and similar",
default=1,
),
EnumVariable(
"debug",
help="debug output and symbols",
default="no",
allowed_values=("yes", "no", "full"),
map={},
ignorecase=0, # case sensitive
),
ListVariable(
"shared",
help="libraries to build as shared libraries",
default="all",
names=list_of_libs,
),
PackageVariable(
"x11",
help="use X11 installed here (yes = search some places)",
default="yes",
),
PathVariable(
"qtdir",
help="where the root of Qt is installed",
default=qtdir),
PathVariable(
"foopath",
help="where the foo library is installed",
default=foopath,
validator=PathVariable.PathIsDir,
),
)
</programlisting>
</refsect2>
<refsect2 id='file_and_directory_nodes'>
<title>File and Directory Nodes</title>
<para>
The &f-link-File; and &f-link-Dir;
functions/methods return
File and Directory Nodes, respectively.
Such nodes are Python objects with
several user-visible attributes
and methods that are often useful to access
in SConscript files:</para>
<variablelist>
<varlistentry>
<term><replaceable>n</replaceable>.<varname>path</varname></term>
<listitem>
<para>The build path
of the given
file or directory.
This path is relative to the top-level directory
(where the &SConstruct; 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><replaceable>n</replaceable>.<varname>abspath</varname></term>
<listitem>
<para>The absolute build path of the given file or directory.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable>n</replaceable>.<function>srcnode</function>()</term>
<listitem>
<para>The
<function>srcnode</function>
method
returns another File or Directory Node
representing the source path of the given
File or Directory Node.
</para>
</listitem>
</varlistentry>
</variablelist>
<para>For example:</para>
<programlisting language="python">
# 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", foo.path)
</programlisting>
<para>
File and Directory Node objects have methods to create
File and Directory Nodes relative to the original Node.
</para>
<para>
If the object is a Directory Node,
these methods will place the the new Node within the directory
the Node represents:
</para>
<variablelist>
<varlistentry>
<term><replaceable>d</replaceable>.<function>Dir</function>(<parameter>name</parameter>)</term>
<listitem>
<para>Returns a directory Node for a subdirectory of
<replaceable>d</replaceable>
named
<parameter>name</parameter>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable>d</replaceable>.<function>File</function>(<parameter>name</parameter>)</term>
<listitem>
<para>Returns a file Node for a file within
<replaceable>d</replaceable>
named
<parameter>name</parameter>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable>d</replaceable>.<function>Entry</function>(<parameter>name</parameter>)</term>
<listitem>
<para>Returns an unresolved Node within
<replaceable>d</replaceable>
named
<parameter>name</parameter>.</para>
</listitem>
</varlistentry>
</variablelist>
<para>
If the object is a File Node,
these methods will place the the new Node in the same
directory as the one the Node represents:
</para>
<variablelist>
<varlistentry>
<term><replaceable>f</replaceable>.<function>Dir</function>(<parameter>name</parameter>)</term>
<listitem>
<para>Returns a directory named
<parameter>name</parameter>
within the parent directory of
<replaceable>f</replaceable>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable>f</replaceable>.<function>File</function>(<parameter>name</parameter>)</term>
<listitem>
<para>Returns a file named
<parameter>name</parameter>
within the parent directory of
<replaceable>f</replaceable>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable>f</replaceable>.<function>Entry</function>(<parameter>name</parameter>)</term>
<listitem>
<para>Returns an unresolved Node named
<parameter>name</parameter>
within the parent directory of
<replaceable>f</replaceable>.</para>
</listitem>
</varlistentry>
</variablelist>
<para>For example:</para>
<programlisting language="python">
# 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')
</programlisting>
</refsect2>
</refsect1>
<refsect1 id='extending_scons'>
<title>EXTENDING SCONS</title>
<refsect2 id='builder_objects'>
<title>Builder Objects</title>
<para>&scons;
can be extended to build different types of targets
by adding new Builder objects
to a &consenv;.
<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 &Program;, &Object;, &Library;, or any other
type of output file for which
&scons;
already has an existing Builder,
it is generally much easier to
use those existing Builders
in a &consenv;
that sets the appropriate &consvars;
(<envar>CC</envar>, <envar>LINK</envar>, etc.).</para>
<para>Builder objects are created
using the
&f-link-Builder;
factory function.
The
&f-Builder;
function accepts the following keyword arguments:</para>
<variablelist>
<varlistentry>
<term><parameter>action</parameter></term>
<listitem>
<para>The command line string used to build the target from the source.
<parameter>action</parameter>
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:</para>
<simplelist type="vert">
<member><parameter>source</parameter> - a list of source nodes;.</member>
<member><parameter>target</parameter> - a list of target nodes;.</member>
<member><parameter>env</parameter> - the &consenv;.</member>
</simplelist>
<para>The
<parameter>action</parameter>
and
<parameter>generator</parameter>
arguments must not both be used for the same Builder.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>prefix</parameter></term>
<listitem>
<para>The prefix that will be prepended to the target file name.
<parameter>prefix</parameter> may be:</para>
<itemizedlist>
<listitem><para>a string</para></listitem>
<listitem><para>a callable object -
a function or other callable that takes
two arguments (a &consenv; and a list of sources)
and returns a prefix</para></listitem>
<listitem><para>a dictionary -
specifies a mapping from a specific source suffix (of the first
source specified) to a corresponding target prefix. Both the source
suffix and target prefix specifications may use environment variable
substitution, and the target prefix (the 'value' entries in the
dictionary) may also be a callable object. The default target prefix
may be indicated by a dictionary entry with a key value of <constant>None</constant>.</para>
</listitem>
</itemizedlist>
<programlisting language="python">
b = Builder("build_it < $SOURCE > $TARGET",
prefix = "file-")
def gen_prefix(env, sources):
return "file-" + env['PLATFORM'] + '-'
b = Builder("build_it < $SOURCE > $TARGET",
prefix = gen_prefix)
b = Builder("build_it < $SOURCE > $TARGET",
suffix = { None: "file-",
"$SRC_SFX_A": gen_prefix })
</programlisting>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>suffix</parameter></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
&scons;
will append a '.' to the beginning of the suffix if it's not already
there. The string returned by callable object (or obtained from the
dictionary) is untouched and must append its own '.' to the beginning
if one is desired.</para>
<programlisting language="python">
b = Builder("build_it < $SOURCE > $TARGET"
suffix = "-file")
def gen_suffix(env, sources):
return "." + env['PLATFORM'] + "-file"
b = Builder("build_it < $SOURCE > $TARGET",
suffix = gen_suffix)
b = Builder("build_it < $SOURCE > $TARGET",
suffix = { None: ".sfx1",
"$SRC_SFX_A": gen_suffix })
</programlisting>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>ensure_suffix</parameter></term>
<listitem>
<para>When set to any true value, causes
&scons;
to add the target suffix specified by the
<parameter>suffix</parameter>
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>
<programlisting language="python">
b1 = Builder("build_it < $SOURCE > $TARGET"
suffix = ".out")
b2 = Builder("build_it < $SOURCE > $TARGET"
suffix = ".out",
ensure_suffix)
env = Environment()
env['BUILDERS']['B1'] = b1
env['BUILDERS']['B2'] = b2
# Builds "foo.txt" because ensure_suffix is not set.
env.B1('foo.txt', 'foo.in')
# Builds "bar.txt.out" because ensure_suffix is set.
env.B2('bar.txt', 'bar.in')
</programlisting>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>src_suffix</parameter></term>
<listitem>
<para>The expected source file name suffix. This may be a string or a list
of strings.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>target_scanner</parameter></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 &consenv;,
<emphasis>not</emphasis>
for implicit dependencies based on source files.
See <xref linkend="scanner_objects"/>
for information about creating Scanner objects.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>source_scanner</parameter></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
<literal>#include</literal>
lines in source files.
The pre-built
<classname>DirScanner</classname>
Scanner object may be used to
indicate that this Builder
should scan directory trees
for on-disk changes to files
that
&scons;
does not know about from other Builder or function calls.
See <xref linkend="scanner_objects"/>
for information about creating your own Scanner objects.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>target_factory</parameter></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>
<programlisting language="python">
MakeDirectoryBuilder = Builder(action=my_mkdir, target_factory=Dir)
env = Environment()
env.Append(BUILDERS={'MakeDirectory': MakeDirectoryBuilder})
env.MakeDirectory('new_directory', [])
</programlisting>
<para>Note that the call to this <function>MakeDirectory</function> 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><parameter>source_factory</parameter></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 language="python">
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><parameter>emitter</parameter></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.
<parameter>emitter</parameter>
can also be a string containing a &consvar; 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:</para>
<simplelist type="vert">
<member><parameter>source</parameter> - a list of source nodes.</member>
<member><parameter>target</parameter> - a list of target nodes.</member>
<member><parameter>env</parameter> - the &consenv;.</member>
</simplelist>
<para>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 language="python">
def e(target, source, env):
return (target + ['foo.foo'], source + ['foo.src'])
# Simple association of an emitter function with a Builder.
b = Builder("my_build < $TARGET > $SOURCE",
emitter = e)
def e2(target, source, env):
return (target + ['bar.foo'], source + ['bar.src'])
# Simple association of a list of emitter functions with a Builder.
b = Builder("my_build < $TARGET > $SOURCE",
emitter = [e, e2])
# Calling an emitter function through a &consvar;.
env = Environment(MY_EMITTER=e)
b = Builder("my_build < $TARGET > $SOURCE",
emitter='$MY_EMITTER')
# Calling a list of emitter functions through a &consvar;.
env = Environment(EMITTER_LIST=[e, e2])
b = Builder("my_build < $TARGET > $SOURCE",
emitter='$EMITTER_LIST')
# Associating multiple emitters with different file
# suffixes using a dictionary.
def e_suf1(target, source, env):
return (target + ['another_target_file'], source)
def e_suf2(target, source, env):
return (target, source + ['another_source_file'])
b = Builder("my_build < $TARGET > $SOURCE",
emitter={'.suf1' : e_suf1,
'.suf2' : e_suf2})
</programlisting>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>multi</parameter></term>
<listitem>
<para>Specifies whether this builder is allowed to be called multiple times for
the same target file(s). The default is <constant>0</constant>,
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 additional environment overrides,
or associate a different
builder with the target.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>env</parameter></term>
<listitem>
<para>A &consenv; 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><parameter>generator</parameter></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:</para>
<simplelist type="vert">
<member><parameter>source</parameter> - A list of source nodes;.</member>
<member><parameter>target</parameter> - A list of target nodes;.</member>
<member><parameter>env</parameter> - the &consenv;.</member>
<member><parameter>for_signature</parameter> -
A Boolean value that specifies
whether the generator is being called
for generating a build signature
(as opposed to actually executing the command).</member>
</simplelist>
<para>Example:</para>
<programlisting language="python">
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><parameter>src_builder</parameter></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><parameter>single_source</parameter></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
<exceptionname>UserError</exceptionname> exception.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>source_ext_match</parameter></term>
<listitem>
<para>When the specified
<parameter>action</parameter>
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
<parameter>source_ext_match</parameter>
to
<parameter>None</parameter>
or some other non-true value.
When
<parameter>source_ext_match</parameter>
is disable,
&scons;
will use the suffix of the first specified
source file to select the appropriate action from the
<parameter>action</parameter>
dictionary.</para>
<para>In the following example,
the setting of
<parameter>source_ext_match</parameter>
prevents
&scons;
from exiting with an error
due to the mismatched suffixes of
<filename>foo.in</filename>
and
<filename>foo.extra</filename>.</para>
<programlisting language="python">
b = Builder(action={'.in' : 'build $SOURCES > $TARGET'},
source_ext_match = None)
env = Environment(BUILDERS={'MyBuild':b})
env.MyBuild('foo.out', ['foo.in', 'foo.extra'])
</programlisting>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>env</parameter></term>
<listitem>
<para>A &consenv; 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>
<programlisting language="python">
b = Builder(action="build < $SOURCE > $TARGET")
env = Environment(BUILDERS={'MyBuild' : b})
env.MyBuild('foo.out', 'foo.in', my_arg='xyzzy')
</programlisting>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>chdir</parameter></term>
<listitem>
<para>A directory from which scons
will execute the
action(s) specified
for this Builder.
If the
<parameter>chdir</parameter>
argument is
a string or a directory Node,
scons will change to the specified directory.
If the
<parameter>chdir</parameter>
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
&consvars; like
<envar>$TARGET</envar>
and
<envar>$SOURCE</envar>
when using the <parameter>chdir</parameter>
keyword argument--that is,
the expanded file names
will still be relative to
the top-level directory containing the &SConstruct; file,
and consequently incorrect
relative to the chdir directory.
Builders created using <parameter>chdir</parameter> keyword argument,
will need to use &consvar;
expansions like
<literal>${TARGET.file}</literal>
and
<literal>${SOURCE.file}</literal>
to use just the filename portion of the
targets and source.</para>
<programlisting language="python">
b = Builder(action="build < ${SOURCE.file} > ${TARGET.file}",
chdir=1)
env = Environment(BUILDERS={'MyBuild' : b})
env.MyBuild('sub/dir/foo.out', 'sub/dir/foo.in')
</programlisting>
<warning>
<para>
Python only keeps one current directory
location even if there are multiple threads.
This means that use of the
<parameter>chdir</parameter>
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>
</warning>
</listitem>
</varlistentry>
</variablelist>
<para>Any additional keyword arguments supplied
when a Builder object is created
(that is, when the &f-link-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 &consvar; to
the repository of a source code system.</para>
<para>Any additional keyword arguments supplied
when a Builder object is called
will only be associated with the target
created by that particular &f-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
&f-link-Builder;
function will turn its
<parameter>action</parameter>
keyword argument into an appropriate
internal Action object.
You can also explicitly create Action objects
for passing to &f-Builder;, or other functions
that take actions as arguments,
by calling the &f-link-Action; factory 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
&Action; factory function
returns an appropriate object for the action
represented by the type of the action argument
(the first positional parmeter):</para>
<itemizedlist>
<listitem>
<para>If the action argument is already an Action object,
the object is simply returned.</para>
</listitem>
<listitem>
<para>If the action argument is a string,
a command-line Action is returned.
If such a string begins with
<emphasis role="bold">@</emphasis>,
it indicates printing of the command line is to be suppressed.
If the string begins with
<emphasis role="bold">-</emphasis> (hyphen),
it indicates the exit status from the specified command
is to be ignored, allowing execution to continue
even if the command reports failure:</para>
<programlisting language="python">
Action('$CC -c -o $TARGET $SOURCES')
# Doesn't print the line being executed.
Action('@build $TARGET $SOURCES')
# Ignores return value
Action('-build $TARGET $SOURCES')
</programlisting>
</listitem>
<listitem>
<para>If the action 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 taken as the
command and arguments to be executed via
the command line.
This allows white space to be enclosed
in an argument rather than taken as a separator by defining
a command in a list within a list:</para>
<programlisting language="python">
Action([['cc', '-c', '-DWHITE SPACE', '-o', '$TARGET', '$SOURCES']])
</programlisting>
</listitem>
<listitem>
<para>If the action argument is a Python function,
a function Action is returned.
The Python function must accept three keyword arguments:</para>
<simplelist type="vert">
<member><parameter>target</parameter> -
a Node object representing the target file.</member>
<member><parameter>source</parameter> -
a Node object representing the source file.</member>
<member><parameter>env</parameter> -
the &consenv; used for building the target file.</member>
</simplelist>
<para>
The
<parameter>target</parameter>
and
<parameter>source</parameter>
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 <function>str</function> function:</para>
<programlisting language="python">
target_file_name = str(target)
source_file_names = [str(x) for x in source]
</programlisting>
<para>The function should return
<literal>0</literal>
or
<constant>None</constant>
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 language="python">
def build_it(target=None, source=None, env=None):
# build the target from the source
return 0
a = Action(build_it)
</programlisting>
</listitem>
<listitem>
<para>If the action argument is not one of the above types,
<constant>None</constant> is returned.</para>
</listitem>
</itemizedlist>
<para>As usual the environment method form &f-link-env-Action;
will expand &consvars; in any argument strings,
including the action argument, at the time it is called,
using the construction variables in the &consenv; through which
it was called. The global function form &f-link-Action;
<emphasis>delays</emphasis> variable expansion until
the Action object is actually used.
</para>
<para>The second argument to &f-Action;
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>
<itemizedlist>
<listitem>
<para>If the output argument is a function,
it must return a string
describing the action being executed.
A function may also be specified using the
<parameter>strfunction</parameter>
keyword argument. The function
must accept these three keyword arguments:</para>
<simplelist type="vert">
<member><parameter>source</parameter> -
a Node object representing the source file.</member>
<member><parameter>target</parameter> -
a Node object representing the target file.</member>
<member><parameter>env</parameter> - the &consenv;.</member>
</simplelist>
<para>The
<parameter>target</parameter>
and
<parameter>source</parameter>
arguments may be lists of Node objects if there is
more than one target file or source file.</para>
</listitem>
<listitem>
<para>If the output argument is a string,
substitution is performed on it before it is printed.
The output string may also be specified using the
<parameter>cmdstr</parameter>
keyword argument.
The string typically contains variables, notably
<literal>$TARGET(S)</literal> and <literal>$SOURCE(S)</literal>,
or consists of just a single
variable, which is optionally defined somewhere else.
SCons itself heavily uses the latter variant.</para>
</listitem>
</itemizedlist>
<para>Examples:</para>
<programlisting language="python">
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>Any additional positional arguments, if present,
may either be &consvars; or lists of &consvars;
whose values will be included in the signature of the Action
when deciding whether a target should be rebuilt because the action changed.
Such variables may also be specified using the
<parameter>varlist</parameter>
keyword parameter;
both positional and keyword forms may be present, and will be combined.
This is necessary whenever you want a target to be rebuilt
when a specific &consvar; 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 &consvar; when generating the command line.</para>
<programlisting language="python">
def build_it(target, source, env):
# build the target from the 'XXX' construction variable
with open(target[0], 'w') as f:
f.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
&Action;
factory function
can be passed the following
optional keyword arguments
to modify the Action object's behavior:</para>
<variablelist>
<varlistentry>
<term><parameter>chdir</parameter></term>
<listitem>
<para>
Specifies that
scons will execute the action
after changing to the specified directory.
If the
<parameter>chdir</parameter>
argument is
a string or a directory Node,
scons will change to the specified directory.
If the
<parameter>chdir</parameter>
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
&consvars; like
&cv-TARGET; and &cv-SOURCE;
when using the <parameter>chdir</parameter>
keyword argument--that is,
the expanded file names
will still be relative to
the top-level directory containing the &SConstruct; file,
and consequently incorrect
relative to the chdir directory.
Builders created using <parameter>chdir</parameter> keyword argument,
will need to use &consvar;
expansions like
<literal>${TARGET.file}</literal>
and
<literal>${SOURCE.file}</literal>
to use just the filename portion of the
targets and source. Example:</para>
<programlisting language="python">
a = Action("build < ${SOURCE.file} > ${TARGET.file}",
chdir=1)
</programlisting>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>exitstatfunc</parameter></term>
<listitem>
<para>
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 succeeds. Example:</para>
<programlisting language="python">
def always_succeed(s):
# Always return 0, which indicates success.
return 0
a = Action("build < ${SOURCE.file} > ${TARGET.file}",
exitstatfunc=always_succeed)
</programlisting>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>batch_key</parameter></term>
<listitem>
<para>
Specifies 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
<parameter>batch_key</parameter>
argument evaluates True and is not a callable object,
the configured Action object will cause
&scons;
to collect all targets built with the Action object
and configured with the same &consenv;
into single invocations of the Action object's
command line or function.
Command lines will typically want to use the
&cv-CHANGED_SOURCES; &consvar;
(and possibly &cv-CHANGED_TARGETS; as well)
to only pass to the command line those sources that
have actually changed since their targets were built.
Example:</para>
<programlisting language="python">
a = Action('build $CHANGED_SOURCES', batch_key=True)
</programlisting>
<para>The
<parameter>batch_key</parameter>
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
<parameter>batch_key</parameter>
function must accept the following arguments:</para>
<simplelist>
<member><parameter>action</parameter> - The action object.</member>
<member><parameter>env</parameter> -
The &consenv; configured for the target.</member>
<member><parameter>target</parameter> -
The list of targets for a particular configured action.</member>
<member><parameter>source</parameter> -
The list of source for a particular configured action.</member>
</simplelist>
<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
<function>batch_key</function>
function may decide to return
the value of a specific construction
variable from the
<parameter>env</parameter>
argument
which will cause
&scons;
to batch-build targets
with matching values of that variable,
or perhaps return the
Python <function>id</function>()
of the entire &consenv;,
in which case
&scons;
will batch-build
all targets configured with the same &consenv;.
Returning
<constant>None</constant>
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 language="python">
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>&scons;
supplies a number of functions
that arrange for various common
file and directory manipulations
to be performed.
These are similar in concept to "tasks" in the
&Ant; build tool,
although the implementation is slightly different.
These functions do not actually
perform the specified action
at the time the function is called,
but rather are factory functions which
return an Action object
that can be executed at the
appropriate time.</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
&f-link-Execute;
global function to do so:</para>
<programlisting language="python">
Execute(Touch('file'))
</programlisting>
<para>Second,
you can use these functions
to supply Actions in a list
for use by the &f-link-env-Command; method.
This can allow you to
perform more complicated
sequences of file manipulation
without relying
on platform-specific
external commands:
</para>
<programlisting language="python">
env = Environment(TMPBUILD='/tmp/builddir')
env.Command(
target='foo.out',
source='foo.in',
action=[
Mkdir('$TMPBUILD'),
Copy('$TMPBUILD', '${SOURCE.dir}'),
"cd $TMPBUILD && make",
Delete('$TMPBUILD'),
],
)
</programlisting>
<variablelist>
<varlistentry>
<term><function>Chmod</function>(<parameter>dest, mode</parameter>)</term>
<listitem>
<para>Returns an Action object that
changes the permissions on the specified
<parameter>dest</parameter>
file or directory to the specified
<parameter>mode</parameter>
which can be octal or string, similar to the bash command.
Examples:</para>
<programlisting language="python">
Execute(Chmod('file', 0o755))
env.Command('foo.out', 'foo.in',
[Copy('$TARGET', '$SOURCE'),
Chmod('$TARGET', 0o755)])
Execute(Chmod('file', "ugo+w"))
env.Command('foo.out', 'foo.in',
[Copy('$TARGET', '$SOURCE'),
Chmod('$TARGET', "ugo+w")])
</programlisting>
</listitem>
</varlistentry>
<varlistentry>
<term><function>Copy</function>(<parameter>dest, src</parameter>)</term>
<listitem>
<para>Returns an Action object
that will copy the
<parameter>src</parameter>
source file or directory to the
<parameter>dest</parameter>
destination file or directory.
Examples:</para>
<programlisting language="python">
Execute(Copy('foo.output', 'foo.input'))
env.Command('bar.out', 'bar.in', Copy('$TARGET', '$SOURCE'))
</programlisting>
</listitem>
</varlistentry>
<varlistentry>
<term><function>Delete</function>(<parameter>entry, [must_exist]</parameter>)</term>
<listitem>
<para>Returns an Action that
deletes the specified
<parameter>entry</parameter>,
which may be a file or a directory tree.
If a directory is specified,
the entire directory tree
will be removed.
If the
<parameter>must_exist</parameter>
flag is set to a true value,
then a Python error will be raised
if the specified entry does not exist;
the default is false,
that is, the Action will silently do nothing
if the entry does not exist.
Examples:</para>
<programlisting language="python">
Execute(Delete('/tmp/buildroot'))
env.Command(
'foo.out',
'foo.in',
action=[
Delete('${TARGET.dir}'),
MyBuildAction,
],
)
Execute(Delete('file_that_must_exist', must_exist=True))
</programlisting>
</listitem>
</varlistentry>
<varlistentry>
<term><function>Mkdir</function>(<parameter>dir</parameter>)</term>
<listitem>
<para>Returns an Action
that creates the specified
directory
<parameter>dir</parameter>.
Examples:</para>
<programlisting language="python">
Execute(Mkdir('/tmp/outputdir'))
env.Command(
'foo.out',
'foo.in',
action=[
Mkdir('/tmp/builddir'),
Copy('/tmp/builddir/foo.in', '$SOURCE'),
"cd /tmp/builddir && make",
Copy('$TARGET', '/tmp/builddir/foo.out'),
],
)
</programlisting>
</listitem>
</varlistentry>
<varlistentry>
<term><function>Move</function>(<parameter>dest, src</parameter>)</term>
<listitem>
<para>Returns an Action
that moves the specified
<parameter>src</parameter>
file or directory to
the specified
<parameter>dest</parameter>
file or directory.
Examples:</para>
<programlisting language="python">
Execute(Move('file.destination', 'file.source'))
env.Command(
'output_file',
'input_file',
action=[MyBuildAction, Move('$TARGET', 'file_created_by_MyBuildAction')],
)
</programlisting>
</listitem>
</varlistentry>
<varlistentry>
<term><function>Touch</function>(<parameter>file</parameter>)</term>
<listitem>
<para>Returns an Action
that updates the modification time
on the specified
<parameter>file</parameter>.
Examples:</para>
<programlisting language="python">
Execute(Touch('file_to_be_touched'))
env.Command('marker', 'input_file', action=[MyBuildAction, Touch('$TARGET')])
</programlisting>
</listitem>
</varlistentry>
</variablelist>
</refsect2>
<refsect2 id='variable_substitution'>
<title>Variable Substitution</title>
<para>Before executing a command,
&scons;
performs &consvar; substitution on the string that makes up
the command line of the builder.
&Consvars; to be interpolated are indicated in the
string with a leading
<literal>$</literal>, to distinguish them from plain text
which is not to be substituted.
Besides regular &consvars;, scons provides the following
special variables for each command execution:</para>
<variablelist>
<varlistentry>
<term>&cv-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>&cv-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>&cv-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>&cv-SOURCES;</term>
<listitem>
<para>The file names of the sources of the build command.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>&cv-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>&cv-TARGETS;</term>
<listitem>
<para>The file names of all targets being built.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>&cv-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>&cv-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>
</listitem>
</varlistentry>
</variablelist>
<para>Note that the above variables are reserved
and may not be assigned to in the &consenv;.</para>
<para>For example, given the &consvars;
<literal>CC='cc'</literal>,
<literal>targets=['foo']</literal>
and
<literal>sources=['foo.c', 'bar.c']</literal>:
</para>
<programlisting language="python">
action='$CC -c -o $TARGET $SOURCES'
</programlisting>
<para>would produce the command line:</para>
<screen>
cc -c -o foo foo.c bar.c
</screen>
<para>Variable names may be surrounded by curly braces
(<emphasis role="bold">{}</emphasis>)
to separate the name from surrounding characters which
are not part of the name.
Within the curly braces, a variable name may use
Python list subscripting/slicing notation to select one
or more items from a list.
In the previous example, the string:
<code>${SOURCES[1]}</code>
would produce:</para>
<screen>
bar.c
</screen>
<para>Additionally, a variable name may
have the following
modifiers appended within the enclosing curly braces
to access properties of the interpolated string:</para>
<simplelist>
<member><parameter>base</parameter> -
The base path of the file name,
including the directory path
but excluding any suffix.
</member>
<member><parameter>dir</parameter> - The name of the directory in which the file exists.</member>
<member><parameter>file</parameter> - The file name, minus any directory portion.</member>
<member><parameter>filebase</parameter> - Like <parameter>file</parameter> but minus its suffix.</member>
<member><parameter>suffix</parameter> - Just the file suffix.</member>
<member><parameter>abspath</parameter> - The absolute path name of the file.</member>
<member><parameter>posix</parameter> -
The path with directories separated by forward slashes
(<emphasis role="bold">/</emphasis>).
Sometimes necessary on Windows systems
when a path references a file on other (POSIX) systems.
</member>
<member><parameter>windows</parameter> -
The path with directories separated by backslashes
(<emphasis role="bold"><literal>\\</literal></emphasis>).
Sometimes necessary on POSIX-style systems
when a path references a file on other (Windows) systems.
<parameter>win32</parameter> is a (deprecated) synonym for
<parameter>windows</parameter>.
</member>
<member><parameter>srcpath</parameter> -
The directory and file name to the source file linked to this file through
&f-VariantDir;().
If this file isn't linked,
it just returns the directory and filename unchanged.
</member>
<member><parameter>srcdir</parameter> -
The directory containing the source file linked to this file through
&f-VariantDir;().
If this file isn't linked,
it just returns the directory part of the filename.
</member>
<member><parameter>rsrcpath</parameter> -
The directory and file name to the source file linked to this file through
&f-VariantDir;().
If the file does not exist locally but exists in a Repository,
the path in the Repository is returned.
If this file isn't linked, it just returns the
directory and filename unchanged.
</member>
<member><parameter>rsrcdir</parameter> -
The Repository directory containing the source file linked to this file through
&VariantDir;().
If this file isn't linked,
it just returns the directory part of the filename.
</member>
</simplelist>
<para>For example, the specified target will
expand as follows for the corresponding modifiers:</para>
<literallayout class="monospaced">
$TARGET => sub/dir/file.x
${TARGET.base} => sub/dir/file
${TARGET.dir} => sub/dir
${TARGET.file} => file.x
${TARGET.filebase} => file
${TARGET.suffix} => .x
${TARGET.abspath} => /top/dir/sub/dir/file.x
SConscript('src/SConscript', variant_dir='sub/dir')
$SOURCE => sub/dir/file.x
${SOURCE.srcpath} => src/file.x
${SOURCE.srcdir} => src
Repository('/usr/repository')
$SOURCE => sub/dir/file.x
${SOURCE.rsrcpath} => /usr/repository/src/file.x
${SOURCE.rsrcdir} => /usr/repository/src
</literallayout>
<para>
Modifiers can be combined, like
<literal>${TARGET.base.windows}</literal>,
<literal>${TARGET.srcpath.base)</literal>,
<literal>${TARGET.file.suffix}</literal>, etc.
</para>
<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 &cv-TARGET;, &cv-SOURCES;, etc.)
See <xref linkend='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
&consvar; in the environment.
The function should
accept four arguments:
</para>
<simplelist>
<member><parameter>target</parameter> - a list of target nodes</member>
<member><parameter>source</parameter> - a list of source nodes</member>
<member><parameter>env</parameter> - the &consenv;</member>
<member><parameter>for_signature</parameter> -
a Boolean value that specifies
whether the function is being called
for generating a build signature.
</member>
</simplelist>
<para>
SCons will insert whatever
the called function returns
into the expanded string:
</para>
<programlisting language="python">
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
<methodname>__call__()</methodname>
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>
<programlisting language="python">
class foo:
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")
</programlisting>
<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>
<programlisting language="python">
echo Last build occurred $( $TODAY $). > $TARGET
</programlisting>
<para>would execute the command:</para>
<screen>
echo Last build occurred $TODAY. > $TARGET
</screen>
<para>but the command signature added to any target files would be:</para>
<screen>
echo Last build occurred . > $TARGET
</screen>
</refsect2>
<refsect2 id='python_code_substitution'>
<title>Python Code Substitution</title>
<para>
Any Python code within curly braces
(<emphasis role="bold">{}</emphasis>)
and introduced by the variable prefix <literal>$</literal>
will be evaluated using the Python <function>eval</function> statement,
with the Python globals set to
the current environment's set of &consvars;, and the result
substituted in.
So in the following case:</para>
<programlisting language="python">
env['COND'] = 0
env.Command('foo.out', 'foo.in',
'''echo ${COND==1 and 'FOO' or 'BAR'} > $TARGET''')
</programlisting>
<para>the command executed will be either</para>
<screen>
echo FOO > foo.out
</screen>
<para>or</para>
<screen>
echo BAR > foo.out
</screen>
<para>according to the current value of <literal>env['COND']</literal>
when the command is executed.
The evaluation takes place when the target is being
built, not when the SConscript is being read. So if
<literal>env['COND']</literal> is changed
later in the SConscript, the final value will be used.</para>
<para>Here's a more interesting example. Note that all of
<envar>COND</envar>,
<envar>FOO</envar>,
and
<envar>BAR</envar> are &consvars;,
and their values are substituted into the final command.
<envar>FOO</envar> is a list, so its elements are interpolated
separated by spaces.</para>
<programlisting language="python">
env=Environment()
env['COND'] = 0
env['FOO'] = ['foo1', 'foo2']
env['BAR'] = 'barbar'
env.Command('foo.out', 'foo.in',
'echo ${COND==1 and FOO or BAR} > $TARGET')
# Will execute this:
# echo foo1 foo2 > foo.out
</programlisting>
<para>SCons uses the following rules when converting &consvars; 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 (<literal>\n</literal>) 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.</para>
</listitem>
</varlistentry>
</variablelist>
</refsect2>
<refsect2 id='scanner_objects'>
<title>Scanner Objects</title>
<para>You can use the
&f-link-Scanner;
function to define
objects to scan
new file types for implicit dependencies.
The &f-Scanner;
function accepts the following arguments:</para>
<variablelist>
<varlistentry>
<term><parameter>function</parameter></term>
<listitem>
<para>This can be either:</para>
<itemizedlist>
<listitem><para>
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:
</para></listitem>
<listitem><para>
a dictionary that maps keys
(typically the file suffix, but see below for more discussion)
to other Scanners that should be called.
</para></listitem>
</itemizedlist>
<para>If the argument is a Python function,
the function must accept three required arguments
and an optional fourth:
</para>
<simplelist type="vert">
<member><parameter>node</parameter> -
The internal &SCons; node representing the file.
Use <function>str</function>(<parameter>node</parameter>)
to fetch the name of the file, and
<replaceable>node</replaceable>.<function>get_contents</function>()
to fetch the contents of the file as bytes or
<replaceable>node</replaceable>.<function>get_text_contents</function>()
to fetch the contents as text.
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).
</member>
<member><parameter>env</parameter> - The &consenv; for the scan.</member>
<member><parameter>path</parameter> -
A tuple (or list)
of directories that can be searched
for files.
This will usually be the tuple returned by the
<parameter>path_function</parameter>
argument (see below).
</member>
<member><parameter>arg</parameter> -
The argument supplied when the scanner was created, if any
(default <constant>None</constant>.
</member>
</simplelist>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>name</parameter></term>
<listitem>
<para>The name of the Scanner.
This is mainly used
to identify the Scanner internally.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>argument</parameter></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><parameter>skeys</parameter></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><parameter>path_function</parameter></term>
<listitem>
<para>A Python function that takes four or five arguments:
a &consenv;,
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
<parameter>path_function</parameter>
returns a tuple of directories
that can be searched for files to be returned
by this Scanner object.
(Note that the
&f-link-FindPathDirs;
function can be used to return a ready-made
<parameter>path_function</parameter>
for a given &consvar; name,
instead of having to write your own function from scratch.)</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>node_class</parameter></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 function
supplied by the
<parameter>node_factory</parameter> argument.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>node_factory</parameter></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><parameter>scan_check</parameter></term>
<listitem>
<para>An optional Python function that takes two arguments,
a Node (file) and a &consenv;,
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><parameter>recursive</parameter></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 <literal>#include</literal> 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
&scons;
has a global
<classname>SourceFileScanner</classname>
object that is used by
the &b-link-Object;, &b-link-SharedObject; and &b-link-StaticObject;
builders to decide
which scanner should be used
for different file extensions.
You can use the
<methodname>SourceFileScanner.add_scanner()</methodname>
method to add your own Scanner object
to the
&SCons;
infrastructure
that builds target programs or
libraries from a list of
source files of different types:</para>
<programlisting language="python">
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
<filename>.C</filename>
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
<filename>.C</filename>
suffix as a C++ source file.
On a case-insensitive system
such as Windows,
&scons; treats a file with a
<filename>.C</filename>
suffix as a C source file.</para>
</refsect2>
<refsect2 id='f_file_suffix'>
<title>.F file suffix</title>
<para>&scons; handles the upper-case
<filename>.F</filename>
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
<filename>.F</filename>
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
<filename>.F</filename>
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 <filename>/cygdrive/c/mydir</filename>
to an equivalent Windows pathname
of <filename>C:/mydir</filename> (equivalent to <filename>C:\mydir</filename>).
</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 <application>flex</application>)
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 Microsoft Store or ActiveState version of Python
to run &scons;.</para>
</refsect2>
<refsect2 id='windows_sconsbat_file'>
<title>Windows: <filename>scons.bat</filename> file</title>
<para>On Windows systems,
&scons; is executed via a wrapper
<filename>scons.bat</filename>
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>
<screen>
<userinput>scons "FOO=BAR" "BAZ=BLEH"</userinput>
</screen>
<para>Second, the Cygwin shell does not
recognize this file as being the same
as an &scons;
command issued at the command-line prompt.
You can work around this either by
executing
<filename>scons.bat</filename>
from the Cygwin command line,
or by creating a wrapper shell
script named
<filename>scons</filename>.</para>
</refsect2>
<refsect2 id='mingw'>
<title>MinGW</title>
<para>The MinGW <filename>bin</filename>
directory must be in your <envar>PATH</envar>
environment variable or the
<envar>ENV['PATH']</envar> &consvar; 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 <envar>PATH</envar> 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
<code>tools=['mingw']</code>
to the &Environment; function, because &scons; will prefer the MSVC tools
over the MinGW tools.</para>
</refsect2>
</refsect1>
<!-- Removed in favor of scons-cookbook.readthedocs.io,
but leave here for the time being...
<refsect1 id='examples'>
<title>EXAMPLES</title>
<para>To help you get started using &scons;,
this section contains a brief overview of some common tasks.
See the &SCons; User Guide for many more examples.
</para>
<refsect2 id='basic_compilation_from_a_single_source_f'>
<title>Basic Compilation From a Single Source File</title>
<programlisting language="python">
env = Environment()
env.Program(target='foo', source='foo.c')
</programlisting>
<para>Note: Build the file by specifying
the target as an argument
(<userinput>scons foo</userinput> or <userinput>scons foo.exe</userinput>)
or by specifying the current directory as the target
(<userinput>scons .</userinput>).</para>
</refsect2>
<refsect2 id='basic_compilation_from_multiple_source_f'>
<title>Basic Compilation From Multiple Source Files</title>
<programlisting language="python">
env = Environment()
env.Program(target='foo', source=Split('f1.c f2.c f3.c'))
</programlisting>
</refsect2>
<refsect2 id='setting_a_compilation_flag'>
<title>Setting a Compilation Flag</title>
<programlisting language="python">
env = Environment(CCFLAGS='-g')
env.Program(target='foo', source='foo.c')
</programlisting>
</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 <envar>CCFLAGS</envar> to specify
<option>-I</option> options by hand.
&scons; will construct the right <option>-I</option>
options from the contents of <envar>CPPPATH.</envar></para>
<programlisting language="python">
env = Environment(CPPPATH=['.'])
env.Program(target='foo', source='foo.c')
</programlisting>
</refsect2>
<refsect2 id='search_multiple_directories_for_h_files'>
<title>Search Multiple Directories For .h Files</title>
<programlisting language="python">
env = Environment(CPPPATH=['include1', 'include2'])
env.Program(target='foo', source='foo.c')
</programlisting>
</refsect2>
<refsect2 id='building_a_static_library'>
<title>Building a Static Library</title>
<programlisting language="python">
env = Environment()
env.StaticLibrary(target='foo', source=Split('l1.c l2.c'))
env.StaticLibrary(target='bar', source=['l3.c', 'l4.c'])
</programlisting>
</refsect2>
<refsect2 id='building_a_shared_library'>
<title>Building a Shared Library</title>
<programlisting language="python">
env = Environment()
env.SharedLibrary(target='foo', source=['l5.c', 'l6.c'])
env.SharedLibrary(target='bar', source=Split('l7.c l8.c'))
</programlisting>
</refsect2>
<refsect2 id='linking_a_local_library_into_a_program'>
<title>Linking a Local Library Into a Program</title>
<programlisting language="python">
env = Environment(LIBS='mylib', LIBPATH=['.'])
env.Library(target='mylib', source=Split('l1.c l2.c'))
env.Program(target='prog', source=['p1.c', 'p2.c'])
</programlisting>
</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>
<programlisting language="python">
bld = Builder(
action='pdftex < $SOURCES > $TARGET',
suffix='.pdf',
src_suffix='.tex'
)
env = Environment(BUILDERS={'PDFBuilder': bld})
env.PDFBuilder(target='foo.pdf', source='foo.tex')
# The following creates "bar.pdf" from "bar.tex"
env.PDFBuilder(target='bar', source='bar')
</programlisting>
<para>Note that the above initialization
replaces the default dictionary of Builders,
so this &consenv; can not be used call Builders like
&b-link-Program;, &b-link-Object;, &b-link-StaticLibrary; etc.
See the next example for an alternative.
</para>
</refsect2>
<refsect2 id='adding_your_own_builder_object_to_an_env'>
<title>Adding Your Own Builder Object to an Environment</title>
<programlisting language="python">
bld = Builder(
action='pdftex < $SOURCES > $TARGET'
suffix='.pdf',
src_suffix='.tex'
)
env = Environment()
env.Append(BUILDERS={'PDFBuilder': bld})
env.PDFBuilder(target='foo.pdf', source='foo.tex')
env.Program(target='bar', source='bar.c')
</programlisting>
<para>You also can use other Pythonic techniques to add
to the <envar>BUILDERS</envar> &consvar;, such as:</para>
<programlisting language="python">
env = Environment()
env['BUILDERS]['PDFBuilder'] = bld
</programlisting>
</refsect2>
<refsect2 id='defining_your_own_scanner_object'>
<title>Defining Your Own Scanner Object</title>
<para>The following example shows adding an extremely simple scanner
(<function>kfile_scan</function>)
that doesn't use a search path at all
and simply returns the
file names present on any
<literal>include</literal>
lines in the scanned file.
This would implicitly assume that all included
files live in the top-level directory:</para>
<programlisting language="python">
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 = DefaultEnvironment()['SCANNERS']
scanners.append(kscan)
env = Environment(SCANNERS=scanners)
env.Command('foo', 'foo.k', 'kprocess < $SOURCES > $TARGET')
bar_in = File('bar.in')
env.Command('bar', bar_in, 'kprocess $SOURCES > $TARGET')
bar_in.target_scanner = kscan
</programlisting>
<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 shown here,
you can use the &f-link-env-File;
function of your current &consenv; 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 adds
a scanner which searches
a path of directories
(specified as the
<envar>MYPATH</envar> &consvar;)
for files that actually exist:</para>
<programlisting language="python">
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 not 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 = DefaultEnvironment()['SCANNERS']
scanners.append(scanner)
env = Environment(SCANNERS=scanners, MYPATH=['incs'])
env.Command('foo', 'foo.x', 'xprocess < $SOURCES > $TARGET')
</programlisting>
<para>The
&f-link-FindPathDirs;
function used in the previous example returns a function
(actually a callable Python object)
that will return a list of directories
specified in the
<envar>MYPATH</envar>
&consvar;. It lets &scons; detect the file
<filename>incs/foo.inc</filename>,
even if
<filename>foo.x</filename>
contains the line
<literal>include foo.inc</literal>
only.
If you need to customize how the search path is derived,
you would provide your own
<parameter>path_function</parameter>
argument when creating the Scanner object,
as follows:</para>
<programlisting language="python">
# 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>
<para><filename>SConstruct</filename>:</para>
<programlisting language="python">
env = Environment()
env.Program(target='foo', source='foo.c')
SConscript('sub/SConscript')
</programlisting>
<para><filename>sub/SConscript</filename>:</para>
<programlisting language="python">
env = Environment()
# Builds sub/foo from sub/foo.c
env.Program(target='foo', source='foo.c')
SConscript('dir/SConscript')
</programlisting>
<para><filename>sub/dir/SConscript</filename>:</para>
<programlisting language="python">
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 call &f-link-Export; and &f-link-Import;
for variables that
you want to share between SConscript files.</para>
<para><filename>SConstruct</filename>:</para>
<programlisting language="python">
env = Environment()
env.Program(target='foo', source='foo.c')
Export("env")
SConscript('subdirectory/SConscript')
</programlisting>
<para><filename>subdirectory/SConscript</filename>:</para>
<programlisting language="python">
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 <parameter>variant_dir</parameter> keyword argument to
the &f-link-SConscript; function to establish
one or more separate variant build directory trees
for a given source directory:</para>
<para><filename>SConstruct</filename>:</para>
<programlisting language="python">
cppdefines = ['FOO']
Export("cppdefines")
SConscript('src/SConscript', variant_dir='foo')
cppdefines = ['BAR']
Export("cppdefines")
SConscript('src/SConscript', variant_dir='bar')
</programlisting>
<para><filename>src/SConscript</filename>:</para>
<programlisting language="python">
Import("cppdefines")
env = Environment(CPPDEFINES=cppdefines)
env.Program(target='src', source='src.c')
</programlisting>
<para>Note the use of the &f-link-Export; method
to set the <varname>cppdefines</varname> variable to a different
value each time we call the &SConscriptFunc; function.</para>
</refsect2>
<refsect2 id='hierarchical_build_of_two_libraries_link'>
<title>Hierarchical Build of Two Libraries Linked With a Program</title>
<para><filename>SConstruct</filename>:</para>
<programlisting language="python">
env = Environment(LIBPATH=['#libA', '#libB'])
Export('env')
SConscript('libA/SConscript')
SConscript('libB/SConscript')
SConscript('Main/SConscript')
</programlisting>
<para><filename>libA/SConscript</filename>:</para>
<programlisting language="python">
Import('env')
env.Library('a', Split('a1.c a2.c a3.c'))
</programlisting>
<para><filename>libB/SConscript</filename>:</para>
<programlisting language="python">
Import('env')
env.Library('b', Split('b1.c b2.c b3.c'))
</programlisting>
<para><filename>Main/SConscript</filename>:</para>
<programlisting language="python">
Import('env')
e = env.Clone(LIBS=['a', 'b'])
e.Program('foo', Split('m1.c m2.c m3.c'))
</programlisting>
<para>The <literal>#</literal> in the <envar>LIBPATH</envar>
directories specify that they're relative to the
top-level directory, so they don't turn into
<filename>Main/libA</filename> when they're
used in <filename>Main/SConscript</filename></para>
<para>Specifying only 'a' and 'b' for the library names
allows &scons; to attach the appropriate library
prefix and suffix for the current platform in
creating the library filename
(for example, <filename>liba.a</filename> on POSIX systems,
<filename>a.lib</filename> on Windows).</para>
</refsect2>
<refsect2 id='customizing_construction_variables_from_'>
<title>Customizing &consvars; from the command line.</title>
<para>The following would allow the C compiler to be specified on the command
line or in the file <filename>custom.py</filename>.</para>
<programlisting language="python">
vars = Variables('custom.py')
vars.Add('CC', 'The C compiler.')
env = Environment(variables=vars)
Help(vars.GenerateHelpText(env))
</programlisting>
<para>The user could specify the C compiler on the command line:</para>
<screen>
<userinput>scons "CC=my_cc"</userinput>
</screen>
<para>or in the <filename>custom.py</filename> file:</para>
<programlisting language="python">
CC = 'my_cc'
</programlisting>
<para>or get documentation on the options:</para>
<screen>
$ <userinput>scons -h</userinput>
CC: The C compiler.
default: None
actual: cc
</screen>
</refsect2>
<refsect2 id='using_microsoft_visual_c_precompiled_hea'>
<title>Using Microsoft Visual C++ precompiled headers</title>
<para>Since <filename>windows.h</filename> 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 (<firstterm>PCH</firstterm>).
The general recipe is to create a
file named <filename>StdAfx.cpp</filename>
that includes a single header named <filename>StdAfx.h</filename>,
and then include every header you want to precompile in
<filename>StdAfx.h</filename>,
and finally include <filename>"StdAfx.h</filename>
as the first header in all the source files you are
compiling to object files. For example:</para>
<para><filename>StdAfx.h</filename>:</para>
<programlisting language="C++">
#include <windows.h>
#include <my_big_header.h>
</programlisting>
<para><filename>StdAfx.cpp</filename>:</para>
<programlisting language="C++">
#include <StdAfx.h>
</programlisting>
<para><filename>Foo.cpp</filename>:</para>
<programlisting language="C++">
#include <StdAfx.h>
/* do some stuff */
</programlisting>
<para><filename>Bar.cpp</filename>:</para>
<programlisting language="C++">
#include <StdAfx.h>
/* do some other stuff */
</programlisting>
<para><filename>SConstruct</filename>:</para>
<programlisting language="python">
env=Environment()
env['PCHSTOP'] = 'StdAfx.h'
env['PCH'] = env.PCH('StdAfx.cpp')[0]
env.Program('MyApp', ['Foo.cpp', 'Bar.cpp'])
</programlisting>
<para>For more information see the documentation for the &b-link-PCH; builder,
and the &cv-link-PCH; and &cv-link-PCHSTOP; &consvars;.
To learn about the details of precompiled
headers consult the MSDN documentation for
<option>/Yc</option>, <option>/Yu</option>, and <option>/Yp</option>.</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
<firstterm>PDB</firstterm> file.
&scons; supports PDB files through the &cv-PDB; &consvar;.</para>
<para><filename>SConstruct</filename>:</para>
<programlisting language="python">
env=Environment()
env['PDB'] = 'MyApp.pdb'
env.Program('MyApp', ['Foo.cpp', 'Bar.cpp'])
</programlisting>
<para>For more information see the documentation for the
&cv-link-PDB; &consvar;.</para>
</refsect2>
</refsect1 -->
<refsect1 id='environment'>
<title>ENVIRONMENT</title>
<para>In general, &scons; is not controlled by environment
variables set in the shell used to invoke it, leaving it
up to the SConscript file author to import those if desired.
However the following variables are imported by
&scons; itself if set:
</para>
<variablelist>
<varlistentry>
<term><envar>SCONS_LIB_DIR</envar></term>
<listitem>
<para>Specifies the directory that contains the &scons;
Python module directory. Normally &scons; can deduce this,
but in some circumstances, such as working with a source
release, it may be necessary to specify
(for example,
<filename>/home/aroach/scons-src-0.01/src/engine</filename>).</para>
</listitem>
</varlistentry>
<varlistentry>
<term><envar>SCONSFLAGS</envar></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>
<varlistentry>
<term><envar>SCONS_CACHE_MSVC_CONFIG</envar></term>
<listitem>
<para>(Windows only). If set, save the shell environment variables
generated when setting up the Microsoft Visual C++ compiler
(and/or Build Tools) to a file to give these settings,
which are expensive to generate, persistence
across &scons; invocations.
Use of this option is primarily intended to aid performance
in tightly controlled Continuous Integration setups.</para>
<para>If set to a True-like value (<literal>"1"</literal>,
<literal>"true"</literal> or
<literal>"True"</literal>) will cache to a file named
<filename>.scons_msvc_cache</filename> in the user's home directory.
If set to a pathname, will use that pathname for the cache.</para>
<para>Note: use this cache with caution as it
might be somewhat fragile: while each major toolset version
(e.g. Visual Studio 2017 vs 2019) and architecture pair will get separate
cache entries, if toolset updates cause a change
to settings within a given release series, &scons; will not
detect the change and will reuse old settings.
Remove the cache file in case of problems with this.
&scons; will ignore failures reading or writing the file
and will silently revert to non-cached behavior in such cases.</para>
<para><emphasis>Available since &scons; 3.1 (experimental)</emphasis>.</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 id='see_also'>
<title>SEE ALSO</title>
<simplelist type="vert">
<member>
The SCons User Guide at
<ulink url="https://scons.org/doc/production/HTML/scons-user.html"/>
</member>
<member>The SCons Design Document (old)</member>
<member>
The SCons Cookbook at
<ulink url="https://scons-cookbook.readthedocs.io"/>
for examples of how to solve various problems with &SCons;.
</member>
<member>
SCons source code
<ulink url="https://github.com/SCons/scons">
on GitHub</ulink>
</member>
<member>
The SCons API Reference
<ulink url="https://scons.org/doc/production/HTML/scons-api/index.html"/>
(for internal details)
</member>
</simplelist>
</refsect1>
<refsect1 id='authors'>
<title>AUTHORS</title>
<para>Originally: Steven Knight
<email>knight@baldmt.com</email>
and Anthony Roach <email>aroach@electriceyeball.com</email>.
</para>
<para>
Since 2010: The SCons Development Team <email>scons-dev@scons.org</email>.
</para>
</refsect1>
</refentry>
</reference>