Relintai/scons_gd
1
0
Fork 0
mirror of https://github.com/Relintai/scons_gd.git synced 2024-11-22 11:18:11 +01:00
Code Issues Packages Projects Releases Wiki Activity
master
scons_gd/scons/doc/man/scons.xml
Relintai 2f9a2dce8b Added scons.
2022-10-15 16:06:26 +02:00

8480 lines
263 KiB
XML
Raw Permalink Blame History

<?xml version="1.0" encoding="UTF-8"?>
<!--
MIT License
Copyright The SCons Foundation
Permission is hereby granted, free of charge, to any person obtaining
a copy of this software and associated documentation files (the
"Software"), to deal in the Software without restriction, including
without limitation the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Software, and to
permit persons to whom the Software is furnished to do so, subject to
the following conditions:
The above copyright notice and this permission notice shall be included
in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY
KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
-->
<!DOCTYPE reference [
<!ENTITY % version SYSTEM "../version.xml">
%version;
<!ENTITY % scons SYSTEM '../scons.mod'>
%scons;
<!ENTITY % builders-mod SYSTEM '../generated/builders.mod'>
%builders-mod;
<!ENTITY % functions-mod SYSTEM '../generated/functions.mod'>
%functions-mod;
<!ENTITY % tools-mod SYSTEM '../generated/tools.mod'>
%tools-mod;
<!ENTITY % variables-mod SYSTEM '../generated/variables.mod'>
%variables-mod;
]>
<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>
<corpauthor>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>Released &builddate;</pubdate>
<copyright>
<year>&copyright_years;</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.
&SCons; offers many features to improve developer productivity
such as parallel builds, caching of build artifacts,
automatic dependency scanning,
and a database of information about previous builds so
details do not have to be recalculated each run.
</para>
<para>&scons; requires Python 3.6 or later to run;
there should be no other dependencies or requirements.
unless the experimental Ninja tool is used.
<emphasis>
Support for Python 3.5 is removed since
&SCons; 4.3.0.
The CPython project has retired 3.5:
<ulink url="https://www.python.org/dev/peps/pep-0478"/>.
</emphasis></para>
<para>You set up an &SCons;
build system by writing a script
that describes things to build (<firstterm>targets</firstterm>), and,
if necessary, the rules to build those files (<firstterm>actions</firstterm>).
&SCons; comes with a collection of <firstterm>Builder</firstterm> methods
which apply premade actions for building many common software components
such as executable programs, object files and libraries,
so that for many software projects,
only the targets and input files (<firstterm>sources</firstterm>)
need be specified in a call to a builder.
&SCons; thus can operate at a level of abstraction above that of pure filenames.
For example if you specify a library target named "foo",
&SCons; keeps track of the actual operating system dependent filename
(such as <filename>libfoo.so</filename> on a GNU/Linux system),
and how to refer to that library in later construction steps
that want to use it, so you don't have to specify that precise
information yourself.
&SCons; can also scan automatically for dependency information,
such as header files included by source code files
(for example, <literal>#include</literal>
preprocessor directives in C or C++ files),
so these <firstterm>implicit dependencies</firstterm> do not
have to be specified manually.
&SCons; supports the ability to define new scanners
to support additional input file types.
</para>
<para>Information about files involved in the build,
including a cryptographic hash of the contents,
is cached for later reuse.
By default this hash (the <firstterm>&contentsig;</firstterm>)
is used to determine if a file has changed since the last build,
but this can be controlled by selecting an appropriate
<firstterm>&f-link-Decider;</firstterm> function.
Implicit dependency files are also part of out-of-date computation.
The scanned implicit dependency information can optionally be
cached and used to speed up future builds.
A hash of each executed build action (the <firstterm>&buildsig;</firstterm>
is cached, so that changes to build instructions (changing flags, etc.)
or to the build tools themselves (new version)
can also trigger a rebuild.
</para>
<para>
When invoked, &scons;
looks for a file named
&SConstruct;
in the current directory and reads the
build configuration from that file
(other names are allowed,
see <xref linkend="sconscript_files"/> for more information).
The &SConstruct;
file may specify subsidiary
configuration files by calling the
&f-link-SConscript; 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 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
or, if specified, the
directory from the
<link linkend="opt-site-dir"><option>--site-dir</option></link>
option instead, 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,
(1) if it contains a file <filename>site_init.py</filename>
that file is evaluated,
and (2) if it contains a directory
<filename>site_tools</filename> the path to that directory
is prepended to the default toolpath.
See the
<link linkend="opt-site-dir"><option>--site-dir</option></link>
and
<link linkend="opt-no-site-dir"><option>--no-site-dir</option></link>
options for details on default paths and
controlling the site directories.
</para>
<para>
SConscript 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.
SConscript files are invoked in a context that makes
the facilities described in this manual page available
in their local namespace without any special steps.
Standard Python scripting capabilities
such as flow control, data manipulation, and imported Python libraries
are available to use to handle complicated build situations.
Other Python files can be made a part of the build system,
but they do not automatically have the &SCons; context and
need to import it if they need access (described later).
</para>
<para>
&scons;
reads and executes all of the included 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
<link linkend="opt-Q"><option>-Q</option></link>
option.</para>
<para>
To assure reproducible builds,
&SCons;
uses a restricted <firstterm>execution environment</firstterm>
for running external commands used to build targets,
rather then propagating the full environment
in effect at the time &scons; was called.
This helps avoid problems like picking up accidental settings,
temporary debug values that are no longer needed,
or one developer having different settings than another
(or than the CI/CD pipeline).
Environment variables that are needed for proper
operation of such commands need to be set explicitly,
which can be done either by assigning the desired values,
or by picking values individually out of environment variables
using the &Python; <systemitem>os.environ</systemitem> dictionary.
The execution environment for a given &consenv; is
contained in its &cv-link-ENV; &consvar;.
A few environment variables are picked up automatically -
see <xref linkend="environment"/>).
</para>
<para>
In particular, 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
<varname>PATH</varname> element of the
execution environment.
One example approach is to
extract the entire <envar>PATH</envar>
environment variable and set that into the
execution environment:
</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 execution 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.copy())
</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;
is normally executed in a top-level directory containing an
&SConstruct; file.
When &scons; is invoked,
the command line (including the contents of the
<link linkend="v-SCONSFLAGS">&SCONSFLAGS;</link>
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 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
<link linkend="v-ARGUMENTS">&ARGUMENTS;</link> 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 <link linkend="v-ARGLIST">&ARGLIST;</link> 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>
See <xref linkend="commandline_construction_variables"/>
for more information.
</para>
<para>&scons;
can maintain a cache of target (derived) files that can
be shared between multiple builds. When derived-file caching is enabled in an
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
<link linkend="opt-cache-force"><option>--cache-force</option></link>,
<link linkend="opt-cache-disable"><option>--cache-disable</option></link>,
<link linkend="opt-cache-readonly"><option>--cache-readonly</option></link>,
and
<link linkend="opt-cache-show"><option>--cache-show</option></link>
command-line options. The
<link linkend="opt-random"><option>--random</option></link>
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>
<refsect2 id='target_selection'>
<title>Target Selection</title>
<para>&SCons; acts on the <firstterm>selected targets</firstterm>,
whether the requested operation is build, no-exec or clean.
Targets are selected as follows:
</para>
<orderedlist>
<listitem>
<para>
Targets specified on the command line.
These may be files, directories,
or phony targets defined using the &f-link-Alias; function.
Directory targets are scanned by &scons; for any targets
that may be found with a destination in or under that directory.
The targets listed on the command line are made available in the
<link linkend="v-COMMAND_LINE_TARGETS">&COMMAND_LINE_TARGETS;</link> list.
</para>
</listitem>
<listitem>
<para>If no targets are specified on the command line,
&scons; will select those targets
specified in the SConscript files via calls
to the &f-link-Default; function. These are
known as the <firstterm>default targets</firstterm>,
and are made available in the
<link linkend="v-DEFAULT_TARGETS">&DEFAULT_TARGETS;</link> list.
</para>
</listitem>
<listitem>
<para>
If no targets are selected by the previous steps,
&scons; selects the current directory for scanning,
unless command-line options which affect the target
scan are detected
(<link linkend="opt-C"><option>-C</option></link>,
<link linkend="opt-D"><option>-D</option></link>,
<link linkend="opt-u"><option>-u</option></link>,
<link linkend="opt-U"><option>-U</option></link>).
Since targets thus selected were not the result of
user instructions, this target list is not made available
for direct inspection; use the
<link linkend="opt-debug"><option>--debug=explain</option></link>
option if they need to be examined.
</para>
</listitem>
<listitem>
<para>
&scons; always adds to the selected targets any intermediate
targets which are necessary to build the specified ones.
For example, if constructing a shared library or dll from C
source files, &scons; will also build the object files which
will make up the library.
</para>
</listitem>
</orderedlist>
<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
<link linkend="opt-u"><option>-u</option></link>
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
<link linkend="opt-D"><option>-D</option></link>
and
<link linkend="opt-U"><option>-U</option></link>
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
usually not necessary.
The
<link linkend="opt-clean"><option>-c</option></link>
flag removes all selected targets:
</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
&f-link-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
&f-link-NoClean; function with those targets.</para>
<para>&scons;
supports building multiple targets in parallel via a
<link linkend="opt-j"><option>-j</option></link>
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>
</refsect2>
</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>
<!-- The recommended approach of multiple <term> entries per <varlistentry> -->
<!-- (if needed) is not used for Options, because the default docbook -->
<!-- presentation format for a varlist has been changed in SCons from -->
<!-- csv to one-per-line to improve the display of Builders and -->
<!-- Functions/Methods in those sections. Do the csv manually. -->
<!-- Note: commented-out options are retained as they may be a model -->
<!-- for future development directions. Do not remove. -->
<variablelist>
<varlistentry id="opt-b">
<term><option>-b</option></term>
<listitem>
<para>Ignored for compatibility with non-GNU versions of &Make;</para>
</listitem>
</varlistentry>
<varlistentry id="opt-clean">
<term>
<option>-c</option>,
<option>--clean</option>,
<option>--remove</option>
</term>
<listitem>
<para>Set <firstterm>clean</firstterm> mode.
Clean up by removing the selected targets,
well as any files or directories associated
with a selected target through calls to the &f-link-Clean; function.
Will not remove any targets which are marked for
preservation through calls to the &f-link-NoClean; function.
</para>
<para>
While clean mode removes targets rather than building them,
work which is done directly in Python code in SConscript files
will still be carried out. If it is important to avoid some
such work from taking place in clean mode, it should be protected.
An SConscript file can determine which mode
is active by querying &f-link-GetOption;, as in the call
<code>if GetOption("clean"):</code>
</para>
</listitem>
</varlistentry>
<varlistentry id="opt-cache-debug">
<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 id="opt-cache-disable">
<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 id="opt-cache-force">
<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 id="opt-cache-readonly">
<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 id="opt-show">
<term><option>--cache-show</option></term>
<listitem>
<para>When using a derived-file cache show the command
that would have been executed to build the file
(or the corresponding <literal>*COMSTR</literal>
contents if set)
even if the file is retrieved from cache.
Without this option, &scons; shows a cache retrieval message
if the file is fetched from cache.
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 id="opt-config">
<term><option>--config=<replaceable>mode</replaceable></option></term>
<listitem>
<para>Control how the &f-link-Configure;
call should use or generate the
results of configuration tests.
<replaceable>mode</replaceable> should be one of
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 mode 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 mode 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 id="opt-C">
<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
<link linkend="opt-f"><option>-f <replaceable>directory</replaceable>/SConstruct</option></link>,
but <option>-f</option> does not search for any of the
predefined &SConstruct; names
in the specified directory.
See also options
<link linkend="opt-u"><option>-u</option></link>,
<link linkend="opt-U"><option>-U</option></link>
and
<link linkend="opt-D"><option>-D</option></link>
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 id="opt-D">
<term><option>-D</option></term>
<listitem>
<para>Works exactly the same way as the
<link linkend="opt-u"><option>-u</option></link>
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 id="opt-debug">
<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 types are recognized:</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 id="opt-diskcheck">
<term><option>--diskcheck=<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)
when searching for source and include files.
<replaceable>type</replaceable>
can be an available diskcheck type or
the special tokens <literal>all</literal> or <literal>none</literal>.
A comma-separated string can be used to select multiple checks.
The default setting is <literal>all</literal>.
</para>
<para>Current available checks are:</para>
<variablelist> <!-- nested list -->
<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>
</variablelist> <!-- end nested list -->
<para>
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.
</para>
</listitem>
</varlistentry>
<varlistentry id="opt-duplicate">
<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 policy is to
prefer hard links to soft links to copies. You can specify a
different policy 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 id="opt-enable-virtualenv">
<term><option>--enable-virtualenv</option></term>
<listitem>
<para>Import virtualenv-related variables to SCons.</para>
</listitem>
</varlistentry>
<varlistentry id="opt-experimental">
<term>
<option>--experimental=<replaceable>feature</replaceable></option>
</term>
<listitem>
<para>Enable experimental features and/or tools.
<replaceable>feature</replaceable> can be an available feature name or
the special tokens <literal>all</literal> or <literal>none</literal>.
A comma-separated string can be used to select multiple features.
The default setting is <literal>none</literal>.</para>
<para>Current available features are: <literal>ninja</literal>.</para>
<caution><para>
No Support offered for any features or tools enabled by this flag.
</para></caution>
<para><emphasis>Available since &scons; 4.2.</emphasis></para>
</listitem>
</varlistentry>
<varlistentry id="opt-f">
<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 id="opt-h">
<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 id="opt-hash-chunksize">
<term>
<option>--hash-chunksize=<replaceable>KILOBYTES</replaceable></option>
</term>
<listitem>
<para>Set the block size used when computing &contentsigs; to
<replaceable>KILOBYTES</replaceable>.
This value determines the size of the chunks which are read in at once when
computing signature hashes. 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>
<para><emphasis>Available since &scons; 4.2.</emphasis></para>
</listitem>
</varlistentry>
<varlistentry id="opt-hash-format">
<term>
<option>--hash-format=<replaceable>ALGORITHM</replaceable></option>
</term>
<listitem>
<para>Set the hashing algorithm used by SCons to
<replaceable>ALGORITHM</replaceable>.
This value determines the hashing algorithm used in generating
&contentsigs;, &buildsigs; and &CacheDir; keys.</para>
<para>The supported list of values are:
<parameter>md5</parameter>,
<parameter>sha1</parameter>
and <parameter>sha256</parameter>.
However, the Python interpreter used to run SCons must have the corresponding
support available in the <systemitem>hashlib</systemitem> module
to use the specified algorithm.</para>
<para>If this option is omitted,
the first supported hash format found is selected.
Typically this is MD5, however, on a FIPS-compliant system
using a version of Python older than 3.9,
SHA1 or SHA256 is chosen as the default.
Python 3.9 and onwards clients always default to MD5, even in FIPS mode.
</para>
<para>Specifying this option changes the name of the SConsign database.
The default database is <filename>.sconsign.dblite</filename>.
In the presence of this option,
<replaceable>ALGORITHM</replaceable> is
included in the name to indicate the difference,
even if the argument is <parameter>md5</parameter>.
For example, <option>--hash-format=sha256</option> uses a SConsign
database named <filename>.sconsign_sha256.dblite</filename>.
</para>
<para><emphasis>Available since &scons; 4.2.</emphasis></para>
</listitem>
</varlistentry>
<varlistentry id="opt-H">
<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 id="opt-i">
<term>
<option>-i</option>,
<option>--ignore-errors</option>
</term>
<listitem>
<para>Ignore all errors from commands executed to rebuild files.</para>
</listitem>
</varlistentry>
<varlistentry id="opt-I">
<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 id="opt-ignore-virtualenv">
<term><option>--ignore-virtualenv</option></term>
<listitem>
<para>Suppress importing virtualenv-related variables to SCons.</para>
</listitem>
</varlistentry>
<varlistentry id="opt-implicit-cache">
<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. &cv-link-CPPPATH;, &cv-link-LIBPATH;)
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. &cv-link-CPPPATH;, &cv-link-LIBPATH;)
than a current implicit dependency with the same name.</para>
</listitem>
</varlistentry>
<varlistentry id="opt-implicit-deps-changed">
<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 id="opt-implicit-deps-unchanged">
<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 id="opt-install-sandbos">
<term><option>--install-sandbox=<replaceable>sandbox_path</replaceable></option></term>
<listitem>
<para>
When using the &Install; builders, prepend
<replaceable>sandbox_path</replaceable>
to the installation paths such that all installed files will be placed
under that directory. This option is unavailable if
one of &b-link-Install;, &b-link-InstallAs; or
&b-link-InstallVersionedLib; is not used in the SConscript files.
</para>
</listitem>
</varlistentry>
<varlistentry id="opt-interactive">
<term><option>--interactive</option></term>
<listitem>
<para>Starts SCons in interactive mode.
The SConscript files are read once and a
<computeroutput>scons&gt;&gt;&gt;</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&gt;&gt;&gt; build -n prog
scons&gt;&gt;&gt; exit
</screen>
</listitem>
</varlistentry>
<varlistentry id="opt-j">
<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 id="opt-k">
<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 id="opt-m">
<term><option>-m</option></term>
<listitem>
<para>Ignored for compatibility with non-GNU versions of &Make;.</para>
</listitem>
</varlistentry>
<varlistentry id="opt-max-drift">
<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 &contentsig;
will be used instead of
calculating a new &contentsig; (hash)
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 &contentsig; used.
A negative value means to never cache the
&contentsig; 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>A deprecated synonym for
<link linkend="opt-hash-chunksize"><option>--hash-chunksize</option></link>.
</para>
<para><emphasis>Deprecated since &scons; 4.2.</emphasis></para>
</listitem>
</varlistentry>
<varlistentry id="opt-n">
<term>
<option>-n</option>,
<option>--no-exec</option>,
<option>--just-print</option>,
<option>--dry-run</option>,
<option>--recon</option>
</term>
<listitem>
<para>Set <firstterm>no execute</firstterm> mode.
Print the commands that would be executed to build
any out-of-date target files, but do not execute the commands.</para>
<para>The output is a best effort, as &SCons; cannot always precisely
determine what would be built. For example, if a file is generated
by a builder action that is later used in the build,
that file is not available to scan for dependencies on an unbuilt tree,
or may contain out of date information in a built tree.
</para>
<para>
Work which is done directly in Python code in SConscript files,
as opposed to work done by builder actions during the build phase,
will still be carried out. If it is important to avoid some
such work from taking place in no execute mode, it should be protected.
An SConscript file can determine which mode
is active by querying &f-link-GetOption;, as in the call
<code>if GetOption("no_exec"):</code>
</para>
</listitem>
</varlistentry>
<varlistentry id="opt-no-site-dir">
<term><option>--no-site-dir</option></term>
<listitem>
<para>Prevents the automatic addition of the standard
<filename>site_scons</filename>
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 id="opt-package-type">
<term><option>--package-type=<replaceable>type</replaceable></option></term>
<listitem>
<para>The type or types
of package to create when using the &b-link-Package; builder.
In the case of multiple types, <replaceable>type</replaceable>
should be a comma-separated string; &SCons; will try to build
for all of those packages.
Note this option is only available if the &t-link-packaging; tool
has been enabled.
</para>
</listitem>
</varlistentry>
<varlistentry id="opt-profile">
<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 id="opt-q">
<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 id="opt-Q">
<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 id="opt-random">
<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 id="opt-s">
<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 id="opt-S">
<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 id="opt-site-dir">
<term><option>--site-dir=<replaceable>path</replaceable></option></term>
<listitem>
<para>Use a specific <replaceable>path</replaceable> as the site directory
rather than searching the list of default site directories.
This directory will be prepended to
<varname>sys.path</varname>,
the module
<filename><replaceable>path</replaceable>/site_init.py</filename>
will be loaded if it exists, and
<filename><replaceable>path</replaceable>/site_tools</filename>
will be added to the default toolpath.</para>
<para>The default set of site directories searched when
<option>--site-dir</option>
is not specified depends on the system platform, as follows.
Users or system administrators can tune site-specific or
project-specific &SCons; behavior by setting up a
site directory in one or more of these locations.
Directories are examined in the order given, from most
generic ("system" directories) to most specific (in the current project),
so the last-executed <filename>site_init.py</filename> file is
the most specific one, giving 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%/scons/site_scons
%LOCALAPPDATA%/scons/site_scons
%APPDATA%/scons/site_scons
%USERPROFILE%/.scons/site_scons
./site_scons
</literallayout>
<para>
Note earlier versions of the documentation listed a different
path for the "system" site directory, this path is still checked
but its use is discouraged:
</para>
<literallayout class="monospaced">
%ALLUSERSPROFILE%/Application Data/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 id="opt-stack-size">
<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 id="opt-t">
<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 id="opt-taskmastertrace">
<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 id="opt-tree">
<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 id="opt-u">
<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 id="opt-U">
<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 id="opt-v">
<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 id="opt-print-directory">
<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 id="opt-no-print-directory">
<term><option>--no-print-directory</option></term>
<listitem>
<para>Turn off -w, even if it was turned on implicitly.</para>
</listitem>
</varlistentry>
<varlistentry id="opt-warn">
<term>
<option>--warn=<replaceable>type</replaceable></option>,
<option>--warn=no-<replaceable>type</replaceable></option>
</term>
<listitem>
<para>Enable or disable (with the prefix "no-") warnings
(<option>--warning</option> is a synonym).
<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">tool-qt-deprecated</emphasis></term>
<listitem>
<para>Warnings about the &t-link-qt; tool being deprecated.
These warnings are disabled by default for the first
phase of deprecation. Enable to be reminded about use
of this tool module.
<emphasis>Available since &SCons; 4.3.</emphasis>
</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 id="opt-Y">
<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='sconscript_file_reference'>
<title>SCONSCRIPT FILE REFERENCE</title>
<refsect2 id='sconscript_files'>
<title>SConscript Files</title>
<para>
The build configuration is described by one or more files,
known as SConscript files.
There must be at least one file for a valid build
(&scons; will quit if it does not find one).
&scons; by default looks for this file by the name
<filename>SConstruct</filename>
in the directory from which you run &scons;,
though if necessary, also looks for alternative file names
&Sconstruct;, &sconstruct;, &SConstruct.py;, &Sconstruct.py;
and &sconstruct.py; in that order.
A different file name (which can include a pathname part)
may be specified via the <option>-f</option> option.
Except for the SConstruct file,
these files are not searched for automatically;
you add additional configuration files to the build
by calling the &f-link-SConscript; function.
This allows parts of the build to be conditionally
included or excluded at run-time depending on how &scons; is invoked.
</para>
<para>
Each SConscript file in a build configuration is invoked
independently in a separate context.
This provides necessary isolation so that different parts of
the build don't accidentally step on each other.
You have to be explicit about sharing information,
by using the &f-link-Export; function or the &exports; argument
to the &SConscript; function, as well as the &f-link-Return; function
in a called SConscript file, and comsume shared information by using the
&f-link-Import; function.
</para>
<para>
The following sections describe the various &SCons; facilities
that can be used in SConscript files. Quick links:
</para>
<simplelist type="vert">
<member><link linkend='construction_environments'>Construction Environments</link></member>
<member><link linkend='tools'>Tools</link></member>
<member><link linkend='builder_methods'>Builder Methods</link></member>
<member><link linkend='methods_and_functions_to_do_things'>Methods and Functions to do Things</link></member>
<member><link linkend='sconscript_variables'>SConscript Variables</link></member>
<member><link linkend='construction_variables'>Construction Variables</link></member>
<member><link linkend='configure_contexts'>Configure Contexts</link></member>
<member><link linkend='commandline_construction_variables'>Command-Line Construction Variables</link></member>
<member><link linkend='node_objects'>Node Objects</link></member>
</simplelist>
</refsect2>
<refsect2 id='construction_environments'>
<title>Construction Environments</title>
<para>A <firstterm>&ConsEnv;</firstterm> is the basic means by which
you 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.
These two are nominally equivalent:</para>
<programlisting language="python">
env = Environment(FOO='foo')
env['FOO'] = 'foo'
</programlisting>
<!--TODO: how can the user tell which settings are init-only? -->
<para>Note that certain settings which affect tool detection are
referenced only when the tools are initializided,
so you either need either to supply them as part of the call to
&f-link-Environment;, or defer tool initialization.
For example, initializing the Microsoft Visual C++ version you wish to use:
</para>
<programlisting language="python">
# initializes msvc to v14.1
env = Environment(MSVC_VERSION="14.1")
env = Environment()
# msvc tool was initialized to default, does not reinitialize
env['MSVC_VERSION'] = "14.1"
env = Environment(tools=[])
env['MSVC_VERSION'] = "14.1"
# msvc tool initialization was deferred, so will pick up new value
env.Tool('default')
</programlisting>
<para>As a convenience,
&consvars; may also be set or modified by the
<parameter>parse_flags</parameter>
keyword argument during object creation,
which has the effect of the
&f-link-env-MergeFlags;
method being applied 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;.
&f-link-env-ParseFlags; describes how these arguments
are distributed to &consvars;.
</para>
<programlisting language="python">
env = Environment(parse_flags='-Iinclude -DEBUG -lm')
</programlisting>
<para>This example adds 'include' to
the &cv-link-CPPPATH; &consvar;,
'EBUG' to
&cv-link-CPPDEFINES;,
and 'm' to
&cv-link-LIBS;.
</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-link-Environment;, and uses the arguments to create a modified copy.
</para>
<para>
&SCons; 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>By default, a new &consenv; is
initialized with a set of builder methods
and &consvars; that are appropriate
for the current platform.
The 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')
</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
<literal>win32</literal>
platform adds the
<varname>SystemDrive</varname>
and
<varname>SystemRoot</varname>
variables from the user's external environment
to the &consenv;'s
<varname>ENV</varname>
dictionary.
This is so that any executed commands
that use sockets to connect with other systems
will work on Windows systems.</para>
<para>The <parameter>platform</parameter> argument may be
a string value representing
one of the pre-defined platforms
(<literal>aix</literal>,
<literal>cygwin</literal>,
<literal>darwin</literal>,
<literal>hpux</literal>,
<literal>irix</literal>,
<literal>os2</literal>,
<literal>posix</literal>,
<literal>sunos</literal> or
<literal>win32</literal>),
or it may be be a callable platform object
returned by a call to &f-link-Platform;
selecting a pre-defined platform,
or it may be a user-supplied callable,
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>
<para>
Note that supplying a non-default platform or custom
fuction for initialization
may bypass settings that should happen for the host system
and should be used with care.
It is most useful in the case where the platform is an alternative for
the one that would be auto-detected,
such as <literal>platform="cygwin"</literal>
on a system which would otherwise
identify as <literal>win32</literal>.
</para>
<para>
The optional <parameter>tools</parameter> and <parameter>toolpath</parameter>
keyword arguments affect the way tools available to the environment are initialized.
See <xref linkend="tools"/> for details.
</para>
<para>
The optional <parameter>variables</parameter> keyword argument
allows passing a Variables object which will be used in the
initialization of the &consenv;
See <xref linkend="commandline_construction_variables"/> for details.
</para>
</refsect2>
<refsect2 id='tools'>
<title>Tools</title>
<para>
&SCons; has a large number of predefined tool modules
(more properly, <firstterm>tool specification modules</firstterm>)
which are used to help initialize the &consenv;.
An &SCons; tool is only responsible for setup.
For example, if an 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 that builder and all the &consvars;
it needs in the associated &consenv;; the tool itself
is not called in the process of the build. Normally this
happens invisibly as &scons; has per-platform
lists of default tools, and it steps through those tools,
calling the ones which are actually applicable,
skipping those where necessary programs are not
installed on the build system, or other preconditions are not met.
</para>
<para>
A specific set of tools
with which to initialize an environment when
creating it
may be specified using the optional keyword argument
<parameter>tools</parameter>, which takes a list
of tool names.
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 directly 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> argument is specified,
or if <parameter>tools</parameter> includes <literal>'default'</literal>,
then &scons; will auto-detect usable tools,
using the execution environment value of <varname>PATH</varname>
(that is, <varname><replaceable>env</replaceable>['ENV']['PATH']</varname> -
the external evironment &PATH; from <varname>os.environ</varname>
is <emphasis>not</emphasis> used)
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 re-detected.</para>
<para>Additional tools can be added, see the
<link linkend='extending_scons'>Extending SCons</link> section
and specifically <link linkend='tool_modules'>Tool Modules</link>.
</para>
<para>SCons supports the following tool specifications out of the box:</para>
<!-- '\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -->
<!-- '\" BEGIN GENERATED TOOL DESCRIPTIONS -->
<!-- '\" The descriptions below of the various SCons Tools are generated -->
<!-- '\" from the .xml files 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 take particular action(s)
to produce target(s) of a particular type
(conventionally hinted at by the builder name, e.g. &Program;)
from the specified source files.
A builder call is a declaration: &SCons; enters the
specified relationship into its internal dependency node graph,
and only later makes the decision on whether anything is actually built,
since this depends on command-line options,
target selection rules, and whether the target(s) are
out of date with respect to the sources.
</para>
<para>
&SCons;
provides a number of builders, and you can also write your own
(see <link linkend='builder_objects'>Builder Objects</link>).
Builders are created dynamically at run-time,
often (though not always) by tools which determine
whether the external dependencies for the builder are satisfied,
and which perform the necessary setup
(see <link linkend='tools'>Tools</link>).
Builders are attached to a &consenv; as methods.
The available builder methods are registered as
key-value pairs in the
&cv-link-BUILDERS; attribute of the &consenv;,
so the available builders can be examined.
This example displays them for debugging purposes:
</para>
<programlisting language="python">
env = Environment()
print("Builders:", list(env['BUILDERS']))
</programlisting>
<para>
Builder methods take two required arguments:
<parameter>target</parameter>
and
<parameter>source</parameter>.
The <parameter>target</parameter> and
<parameter>source</parameter> arguments
can be specified either as positional arguments,
in which case <parameter>target</parameter> comes first, or as
keyword arguments, using <parameter>target=</parameter>
and <parameter>source=</parameter>.
Although both arguments are nominally required,
if there is a single source and the target can be inferred
the <parameter>target</parameter> argument can 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 in a builder call,
&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 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>
Sources and targets can be specified as a scalar or as a list,
composed of either strings or nodes (more on nodes below).
When specifying path strings,
&Python; follows the POSIX pathname convention:
if a string begins with the operating system pathname separator
(on Windows both the slash and backslash separator are accepted,
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.
The "current directory" in this context is the directory
of the SConscript file currently being processed.
</para>
<para>
&SCons; also 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>
can optionally 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>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>The optional
<parameter>srcdir</parameter>
keyword argument specifies that
all source file strings that are not absolute paths
or top-relative paths
shall 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>The optional
<parameter>parse_flags</parameter>
keyword argument causes behavior similar to the
&f-link-env-MergeFlags; method, where the argument value is
broken into individual settings and merged into the appropriate &consvars;.
</para>
<programlisting language="python">
env.Program('hello', 'hello.c', parse_flags='-Iinclude -DEBUG -lm')
</programlisting>
<para>This example adds 'include' to
the &cv-link-CPPPATH; &consvar;,
'EBUG' to
&cv-link-CPPDEFINES;,
and 'm' to
&cv-link-LIBS;.
</para>
<para>The optional
<parameter>chdir</parameter>
keyword argument
specifies that the Builder's action(s)
should be executed
after changing directory.
If the
<parameter>chdir</parameter>
argument is
a path string or a directory Node,
scons will change to the specified directory.
If the
<parameter>chdir</parameter>
is not a string or Node
and evaluates true,
then &scons; will change to the
target file's directory.</para>
<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>
<programlisting language="python">
# scons will change to the "sub" subdirectory
# before executing the "cp" command.
env.Command(
target='sub/dir/foo.out',
source='sub/dir/foo.in',
action="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=True)
</programlisting>
<para>Note that &SCons; will
<emphasis>not</emphasis>
automatically modify
its expansion of
&consvars; like &cv-link-TARGET;
and &cv-link-SOURCE;
when using the <parameter>chdir</parameter>
keyword argument--that is,
the expanded file names
will still be relative to
the top-level directory where the &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
target and source.</para>
<para>Keyword arguments that are not specifically
recognized are treated as &consvar;
<firstterm>overrides</firstterm>,
which replace or add those variables on a limited basis.
These overrides
will only be in effect when building the target of the builder call,
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(
target='word',
source='word.cpp',
SHLIBSUFFIX='.ocx',
LIBSUFFIXES=['.ocx'],
)
</programlisting>
<para>Note that both the &cv-link-SHLIBSUFFIX;
and &cv-link-LIBSUFFIXES;
&consvars; must be set if you want &scons; to search automatically
for dependencies on the non-standard library names;
see the descriptions of these variables for more information.</para>
<para>Although the builder methods defined by
&scons;
are, in fact,
methods of a &consenv; object,
many may also be called without an explicit environment:</para>
<programlisting language="python">
Program('hello', 'hello.c')
SharedLibrary('word', 'word.cpp')
</programlisting>
<para>If called this way, the builder will internally use the
&DefEnv; 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 (indicated in the listing of builders below
without a leading <varname>env.</varname>)
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>
A builder <emphasis>may</emphasis> add additional targets
beyond those requested
if an attached <firstterm>Emitter</firstterm> chooses to do so
(see <xref linkend="builder_objects"/> for more information.
&cv-link-PROGEMITTER; is an example).
For example, the GNU linker takes a command-line argument
<option>-Map=<replaceable>mapfile</replaceable></option>,
which causes it to produce a linker map file in addition
to the executable file actually being linked.
If the &b-link-Program; builder's emitter is configured
to add this mapfile if the option is set,
then two targets will be returned when you only provided for one.
</para>
<para>
For this reason,
builder methods always return a <classname>NodeList</classname>,
a list-like object whose elements are Nodes.
Nodes are the internal representation of build targets or sources
(see <xref linkend="node_objects"/> for more information).
The returned <classname>NodeList</classname> object
can be passed to other builder methods as source(s)
or to other &SCons; functions or methods
where a path string would normally be accepted.
</para>
<para> For example,
to add a specific preprocessor define
when compiling one specific object file
but not the others:</para>
<programlisting language="python">
bar_obj_list = env.StaticObject('bar.c', CPPDEFINES='-DBAR')
env.Program("prog", ['foo.c', bar_obj_list, 'main.c'])
</programlisting>
<para>Using a Node as in this example
makes for a more portable build
by avoiding having to specify
a platform-specific object suffix
when calling the &b-link-Program; builder method.
</para>
<para>The <classname>NodeList</classname> object
is also convenient to pass to the &f-link-Default; function,
for the same reason of avoiding a platform-specific name:
</para>
<programlisting language="python">
tgt = env.Program("prog", ["foo.c", "bar.c", "main.c"])
Default(tgt)
</programlisting>
<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 &b-link-StaticObject; call.
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>Since builder calls return
a list-like object, not an actual &Python; list,
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 <classname>NodeList</classname> 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 that because the Builder call returns a
<classname>NodeList</classname>,
you have to access the first element in the list
(<literal>bar_obj_list[0]</literal> in the example)
to get at the Node that actually represents
the object file.</para>
<para>
When trying to handle errors that may occur in a builder method,
consider that the corresponding Action is executed at a different
time than the SConscript file statement calling the builder.
It is not useful to wrap a builder call in a
<systemitem>try</systemitem> block,
since success in the builder call is not the same as
the builder itself succeeding.
If necessary, a Builder's Action should be coded to exit with
a useful exception message indicating the problem in the SConscript files -
programmatically recovering from build errors is rarely useful.
</para>
<para>
The following builder methods are predefined in the
&SCons; core software distribution.
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 in that
&consenv;.
Since the function calling signature is the same for all builders:
</para>
<programlisting language="python">
<function>Buildername</function>(<parameter>target, source, [key=val, ...]</parameter>)
</programlisting>
<para>
it is omitted in this listing for brevity.
</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 id="v-ARGLIST">
<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 id="v-ARGUMENTS">
<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 id="v-BUILD_TARGETS">
<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 id="v-COMMAND_LINE_TARGETS">
<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 id="v-DEFAULT_TARGETS">
<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
Python identifier naming:
the initial character must be an underscore or letter,
followed by any number of underscores, letters, or digits.
A &consenv; is not a Python dictionary itself,
but it can be indexed like one to access a
&consvar;:</para>
<programlisting language="python">
env["CC"] = "cc"
flags = env.get("CPPDEFINES", [])
</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>
&Consvars; can also be supplied as keyword
arguments to a builder, in which case those settings
affect only the work done by that builder call,
and not the &consenv; as a whole.
This concept is called an <firstterm>override</firstterm>:
</para>
<programlisting language="python">
env.Program('hello', 'hello.c', LIBS=['gl', 'glut'])
</programlisting>
<para>A number of useful &consvars; are automatically defined by
scons for each supported platform, and you can modify these
or define any additional &consvars; for your own use,
taking care not to overwrite ones which &SCons; is using.
The following is a list of the possible
automatically defined &consvars;.
</para>
<para>Note the actual list available
at execution time will never 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.
Correct build setups should be resilient to the possible
absence of certain &consvars; before using them,
for example by using a &Python; dictionary
<function>get</function> method to retrieve the value and
taking alternative action if the return indicates the variable is unset.
The &f-link-env-Dump; method can be called to examine the
&consvars; set in a particular environment.
</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><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(CPPDEFINES="WITH_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><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><replaceable>context</replaceable>.<methodname>CheckCHeader</methodname>(<parameter>header, [include_quotes]</parameter>)</term>
<listitem>
<para>Checks if
<parameter>header</parameter>
is usable when compiling a C language program.
<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).
Note this is a wrapper around
<function>CheckHeader</function>.
Returns a boolean indicating success or failure.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable>context</replaceable>.<methodname>CheckCXXHeader</methodname>(<parameter>header, [include_quotes]</parameter>)</term>
<listitem>
<para>Checks if
<parameter>header</parameter>
is usable when compiling a C++ language program.
<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).
Note this is a wrapper around
<function>CheckHeader</function>.
Returns a boolean indicating success or failure.</para>
</listitem>
</varlistentry>
<varlistentry>
<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 &cv-link-CFLAGS;, &cv-link-CPPFLAGS;, &cv-link-LIBS;
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><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>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><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>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><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><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><replaceable>context</replaceable>.<methodname>CheckCC</methodname>()</term>
<listitem>
<para>Checks whether the C compiler
(as defined by the &cv-link-CC; &consvar;) works,
by trying to compile a small source file.
This provides a more rigorous check:
by default, &SCons; itself 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>The test program will be built with the
same command line as the one used by the &b-link-Object; builder
for C source files, so by setting relevant &consvars;
it can be used to detect if particular compiler flags will
be accepted or rejected by the compiler.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable>context</replaceable>.<methodname>CheckCXX</methodname>()</term>
<listitem>
<para>Checks whether the C++ compiler
(as defined by the &cv-link-CXX; &consvar;) works,
by trying to compile a small source file.
This provides a more rigorous check:
by default, &SCons; itself 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>The test program will be built with the
same command line as the one used by the &b-link-Object; builder
for C++ source files, so by setting relevant &consvars;
it can be used to detect if particular compiler flags will
be accepted or rejected by the compiler.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable>context</replaceable>.<methodname>CheckSHCC</methodname>()</term>
<listitem>
<para>Checks whether the shared-object C compiler (as defined by the
&cv-link-SHCC; &consvar;) works
by trying to compile a small source file.
This provides a more rigorous check:
by default, &SCons; itself 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>The test program will be built with the
same command line as the one used by the &b-link-SharedObject; builder
for C source files, so by setting relevant &consvars;
it can be used to detect if particular compiler flags will
be accepted or rejected by the compiler.
Note this does not check whether a shared library/dll can
be created.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable>context</replaceable>.<methodname>CheckSHCXX</methodname>()</term>
<listitem>
<para>Checks whether the shared-object C++ compiler (as defined by the
&cv-link-SHCXX; &consvar;)
works by trying to compile a small source file.
This provides a more rigorous check:
by default, &SCons; itself 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>The test program will be built with the
same command line as the one used by the &b-link-SharedObject; builder
for C++ source files, so by setting relevant &consvars;
it can be used to detect if particular compiler flags will
be accepted or rejected by the compiler.
Note this does not check whether a shared library/dll can
be created.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable>context</replaceable>.<methodname>CheckProg</methodname>(<parameter>prog_name</parameter>)</term>
<listitem>
<para>Checks if
<parameter>prog_name</parameter>
exists in the path &SCons; will use at build time.
(<replaceable>context</replaceable>.<varname>env['ENV']['PATH']</varname>).
Returns a string containing the path to the program,
or <constant>None</constant> on failure.</para>
</listitem>
</varlistentry>
<varlistentry>
<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><replaceable>context</replaceable>.<methodname>CheckMember</methodname>(<parameter>aggregate_member,
[header, language]</parameter>)
</term>
<listitem>
<para>Checks for the existence of a member of the C/C++ struct or class.
<parameter>aggregate_member</parameter>
specifies the struct/class and member to check for.
<parameter>header</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 member.
Example:
</para>
<programlisting language="python">
sconf.CheckMember('struct tm.tm_sec', '#include &lt;time.h&gt;')
</programlisting>
<para>
Returns a boolean indicating success or failure.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable>context</replaceable>.<methodname>Define</methodname>(<parameter>symbol, [value, comment]</parameter>)</term>
<listitem>
<para>This method does not check for anything, but rather forces
the definition of a preprocessor macro that will be added
to the configuration header file.
<parameter>name</parameter> is the macro's identifier.
If <parameter>value</parameter> is given,
it will be be used as the macro replacement value.
If <parameter>value</parameter> is a string and needs to
display with quotes, the quotes need to be included,
as in <literal>'"string"'</literal>
If the optional
<parameter>comment</parameter> is given,
it is inserted as a comment above the macro definition
(suitable comment marks will be added automatically).
This is analogous to using <constant>AC_DEFINE</constant> in &Autoconf;.
</para>
<para>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>Examples of quoting string values:</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>Example including 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 using the predefined checks.
To enable custom checks,
pass a dictionary to the &f-link-Configure; function
as the <parameter>custom_tests</parameter> parameter.
The dictionary maps the names of the checks
to the custom check callables
(either a Python function or an instance of a class implementing a
<methodname>__call__</methodname> method).
Each custom check will be called with a
a <classname>CheckContext</classname>
instance as the first parameter followed by the remaining arguments,
which must be supplied by the user of the check.
A <classname>CheckContext</classname> is not the same as
a configure context; rather it is an instance of a class
which contains a configure context
(available as <replaceable>chk_ctx</replaceable>.<varname>sconf</varname>).
A <classname>CheckContext</classname>
provides the following methods which custom checks
can make use of::</para>
<variablelist>
<varlistentry>
<term><replaceable>chk_ctx</replaceable>.<methodname>Message</methodname>(<parameter>text</parameter>)</term>
<listitem>
<para>Displays <parameter>text</parameter>
as an indicator of progess.
For example: <computeroutput>Checking for library X...</computeroutput>.
Usually called before the check is started.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable>chk_ctx</replaceable>.<methodname>Result</methodname>(<parameter>res</parameter>)</term>
<listitem>
<para>Displays a result message as an indicator of progress.
If <parameter>res</parameter> is an integer,
displays <computeroutput>yes</computeroutput>
if <parameter>res</parameter> evaluates true
or <computeroutput>no</computeroutput> if false.
If <parameter>res</parameter> is a string,
it is displayed as-is.
Usually called after the check has completed.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable>chk_ctx</replaceable>.<methodname>TryCompile</methodname>(<parameter>text, extension=''</parameter>)</term>
<listitem>
<para>Checks if a file containing <parameter>text</parameter>
and given the specified <parameter>extension</parameter> (e.g.
<literal>'.c'</literal>)
can be compiled to an object file
using the environment's &b-link-Object; builder.
Returns a boolean indicating success or failure.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable>chk_ctx</replaceable>.<methodname>TryLink</methodname>(<parameter>text, extension=''</parameter>)</term>
<listitem>
<para>Checks if a file containing <parameter>text</parameter>
and given the specified <parameter>extension</parameter> (e.g.
<literal>'.c'</literal>)
can be compiled to an executable program
using the environment's &b-link-Program; builder.
Returns a boolean indicating success or failure.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable>chk_ctx</replaceable>.<methodname>TryRun</methodname>(<parameter>text, extension=''</parameter>)</term>
<listitem>
<para>Checks if a file containing <parameter>text</parameter>
and given the specified <parameter>extension</parameter> (e.g.
<literal>'.c'</literal>)
can be compiled to an excutable program
using the environment's &b-link-Program; builder and subsequently executed.
Execution is only attempted if the build succeeds.
If the program executes successfully
(that is, its return status is <literal>0</literal>),
a tuple <literal>(True, outputStr)</literal>
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 <literal>(False, '')</literal> is returned.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable>chk_ctx</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>,
given extension <parameter>extension</parameter>)
can be executed.
<parameter>action</parameter>
may be anything which can be converted to an
<link linkend="action_objects">Action Object</link>.
On success, a tuple
<literal>(True, outputStr)</literal>
is returned, where <varname>outputStr</varname>
is the content of the target file.
On failure
<literal>(False, '')</literal>
is returned.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable>chk_ctx</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,
<replaceable>chk_ctx</replaceable>.<varname>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(chk_ctx, qtdir):
chk_ctx.Message('Checking for qt ...')
lastLIBS = chk_ctx.env['LIBS']
lastLIBPATH = chk_ctx.env['LIBPATH']
lastCPPPATH = chk_ctx.env['CPPPATH']
chk_ctx.env.Append(LIBS='qt', LIBPATH=qtdir + '/lib', CPPPATH=qtdir + '/include')
ret = chk_ctx.TryLink(
"""\
#include &lt;qapp.h&gt;
int main(int argc, char **argv) {
QApplication qapp(argc, argv);
return 0;
}
"""
)
if not ret:
chkctx.env.Replace(LIBS=lastLIBS, LIBPATH=lastLIBPATH, CPPPATH=lastCPPPATH)
chkctx.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; with values obtained
from various sources, often from the command line:</para>
<screen>
<userinput>scons VARIABLE=foo</userinput>
</screen>
<para>The variable values can also be specified in a configuration file or an SConscript file.</para>
<para>To obtain the object for manipulating values,
call the &Variables; function:</para>
<variablelist>
<varlistentry id="v-Variables">
<term><function>Variables</function>([<parameter>files, [args]]</parameter>)</term>
<listitem>
<para>If <parameter>files</parameter> is a file or
list of files, they 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
(supplying <constant>None</constant> is necessary
if there are no files but you want to specify
<parameter>args</parameter> as a positional argument).
</para>
<para>
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>.
The primary use is to pass the
&ARGUMENTS; dictionary that holds variables
specified on the command line,
allowing you to indicate that if a setting appears
on both the command line and in the file(s),
the command line setting takes precedence.
However, any dictionary can be passed.
Examples:</para>
<programlisting language="python">
vars = Variables('custom.py')
vars = Variables('overrides.py', ARGUMENTS)
vars = Variables(None, {FOO:'expansion', BAR:7})
</programlisting>
<para>
Calling &Variables; with no arguments is equivalent to:
</para>
<programlisting language="python">
vars = Variables(files=None, args=ARGUMENTS)
</programlisting>
<para>
Note that since the variables are eventually added as &consvars;,
you should choose variable names which do not unintentionally change
pre-defined &consvars; that your project will make use of
(see <xref linkend="construction_variables"/>).
</para>
</listitem>
</varlistentry>
</variablelist>
<para>Variables objects have the following methods:</para>
<variablelist>
<varlistentry id="v-Add">
<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 either the name of the variable,
or a tuple (or list), in which case
the first item in the tuple is taken as the variable name,
and any remaining values are considered aliases for the variable.
<parameter>help</parameter>
is the help text for the variable
(default empty string).
<parameter>default</parameter>
is the default value of the variable
(default <constant>None</constant>).
If <parameter>default</parameter> is
<constant>None</constant>
and a value is not specified,
the &consvar; will not
be added to the &consenv;.
</para>
<para>
As a special case, if <parameter>key</parameter>
is a tuple (or list) and is the <emphasis>only</emphasis>
argument, the tuple is unpacked into the five parameters
listed above left to right, with any missing members filled with
the respecitive default values. This form allows <function>Add</function>
to consume a tuple emitted by the convenience functions
<link linkend='v-BoolVariable'><function>BoolVariable</function></link>,
<link linkend='v-EnumVariable'><function>EnumVariable</function></link>,
<link linkend='v-ListVariable'><function>ListVariable</function></link>,
<link linkend='v-PackageVariable'><function>PackageVariable</function></link>
and
<link linkend='v-PathVariable'><function>PathVariable</function></link>.
</para>
<para>
If the optional <parameter>validator</parameter> is supplied,
it is called to validate the value of the variable.
A function supplied as a validator must accept
three arguments: <parameter>key</parameter>,
<parameter>value</parameter> and <parameter>env</parameter>,
and should raise an exception with a helpful error message
if <parameter>value</parameter> is invalid.
No return value is expected from the validator.
</para>
<para>
If the optional <parameter>converter</parameter> is supplied,
it is called to convert the value before putting it in the environment,
and should take either a value
or a value and environment as parameters.
The converter function must return a value,
which will be converted into a string and be passed to 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 id="v-AddVariables">
<term><replaceable>vars</replaceable>.<function>AddVariables</function>(<parameter>args</parameter>)</term>
<listitem>
<para>A convenience method that adds
one or more 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
<link linkend='v-Add'><function>Add</function></link>:
a required name, the other four optional,
but must be in the specified 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 id="v-Update">
<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
<link linkend='v-UnknownVariables'>&UnknownVariables;</link>
method.</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 id="v-UnknownVariables">
<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 id="v-Save">
<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>. Only variables that are
set to non-default values are saved.
You can load these saved settings on a subsequent run
by passing <parameter>filename</parameter> to the
<link linkend='v-Variables'>&Variables;</link> function,
providing a way to cache particular settings for reuse.
</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 id="v-GenerateHelpText">
<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 &gt; b) - (a &lt; b)
Help(vars.GenerateHelpText(env, sort=cmp))
</programlisting>
</listitem>
</varlistentry>
<varlistentry id="v-FormatVariableHelpText">
<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 id="v-BoolVariable">
<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 id="v-EnumVariable">
<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 id="v-ListVariable">
<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 id="v-PackageVariable">
<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 id="v-PathVariable">
<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='node_objects'>
<title>Node Objects</title>
<para>
&SCons; represents objects that are the sources or targets of
build operations as <firstterm>Nodes</firstterm>,
which are internal data structures.
There are a number of user-visible types of nodes:
File Nodes, Directory Nodes, Value Nodes and Alias Nodes.
Some of the node types have public attributes and methods,
described below. Each of the node types has a global function
and a matching environment method to create instances:
&f-link-File;, &f-link-Dir;, &f-link-Value; and &f-link-Alias;.
</para>
<refsect3 id='file_and_directory_nodes'>
<title>Filesystem Nodes</title>
<para>
The &f-link-File; and &f-link-Dir;
functions/methods return
File and Directory Nodes, respectively.
File and Directory Nodes
(collectively, Filesystem Nodes)
represent build components that correspond to an entry
in the computer's filesystem,
whether or not such an entry exists at the time the Node is created.
You do not usually need to explicitly create filesystem Nodes,
since when you supply a string as a target or source of a Builder,
&SCons; will create the Nodes as needed to populate the
dependency graph.
Builders return the target Node(s) in the form of a list,
which you can then make use of.
However, since filesystem Nodes have some useful
public attributes and methods
that you can use in SConscript files,
it is sometimes appropriate to create them manually,
outside the regular context of a Builder call.
</para>
<para>
The following attributes provide information about a Node:
</para>
<variablelist>
<varlistentry>
<term><replaceable>node</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>node</replaceable>.<varname>abspath</varname></term>
<listitem>
<para>The absolute build path of the given file or directory.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable>node</replaceable>.<varname>relpath</varname></term>
<listitem>
<para>The build path of the given file or directory relative to the root SConstruct file's directory.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable>node</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>Examples:</para>
<programlisting language="python">
# Get the current build dir's path, relative to top.
Dir('.').path
# Current dir's absolute path
Dir('.').abspath
# Current dir's path relative to the root SConstruct file's directory
Dir('.').relpath
# Next line is always '.', because it is the top dir's path relative to itself.
Dir('#.').path
# Source path of the given source file.
File('foo.c').srcnode().path
# Builders return lists of File objects:
foo = env.Program('foo.c')
print("foo will be built in", foo[0].path)
</programlisting>
<para>
Filesystem Node objects have methods to create new
File and Directory Nodes relative to the original Node.
There are also times when you may need to refer to an entry
in a filesystem without knowing in advance whether it's a
file or a directory.
For those situations,
there is an <function>Entry</function> method of filesystem node objects,
which returns a Node that can represent either a file or a directory.
</para>
<para>
If the original Node is a Directory Node,
these methods will place the new Node within the directory
the original Node represents:
</para>
<variablelist>
<varlistentry>
<term><replaceable>node</replaceable>.<function>Dir</function>(<parameter>name</parameter>)</term>
<listitem>
<para>Returns a directory Node
<parameter>name</parameter>
which is a subdirectory of
the directory represented by
<replaceable>node</replaceable>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable>node</replaceable>.<function>File</function>(<parameter>name</parameter>)</term>
<listitem>
<para>Returns a file Node
<parameter>name</parameter>
in the directory represented by
<replaceable>node</replaceable>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable>node</replaceable>.<function>Entry</function>(<parameter>name</parameter>)</term>
<listitem>
<para>Returns an unresolved Node
<parameter>name</parameter>
in the directory represented by
<replaceable>node</replaceable>.</para>
</listitem>
</varlistentry>
</variablelist>
<para>
If the original Node is a File Node,
these methods will place the the new Node in the same
directory as the one the original Node represents:
</para>
<variablelist>
<varlistentry>
<term><replaceable>node</replaceable>.<function>Dir</function>(<parameter>name</parameter>)</term>
<listitem>
<para>Returns a Node
<parameter>name</parameter>
for a directory in the parent directory of
the file represented by
<replaceable>node</replaceable>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable>node</replaceable>.<function>File</function>(<parameter>name</parameter>)</term>
<listitem>
<para>Returns a Node
<parameter>name</parameter>
for a file in the parent directory of
the file represented by
<replaceable>node</replaceable>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable>node</replaceable>.<function>Entry</function>(<parameter>name</parameter>)</term>
<listitem>
<para>Returns an unresolved Node
<parameter>name</parameter>
in the parent directory of
the file represented by
<replaceable>node</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>
</refsect3>
<refsect3 id='value_and_alias_nodes'>
<title>Value and Alias Nodes</title>
<para>
&SCons; provides two other Node types to represent
object that will not have an equivalent filesystem entry.
Such Nodes always need to be created explicitly.
</para>
<para>
The &f-link-Alias; method returns an Alias Node.
Aliases are virtual objects - they will not themselves result
in physical objects being constructed, but are entered into
the dependency graph related to their sources.
An alias is checked for up to date by checking if
its sources are up to date.
An alias is built by making sure its sources have been built,
and if any building took place,
applying any Actions that are defined as part of the alias.
</para>
<para>
An &f-link-Alias; call creates an entry in the alias namespace,
which is used for disambiguation.
If an alias source has a string valued name,
it will be resolved to a filesystem entry Node,
unless it is found in the alias namespace,
in which case it it resolved to the matching alias Node.
As a result, the order of &f-Alias; calls is significant.
An alias can refer to another alias, but only if the
other alias has previously been created.
</para>
<para>
The &f-link-Value; method returns a Value Node.
Value nodes are often used for generated data that
will not have any corresponding filesystem entry,
but will be used to determine whether a build target is out of date,
or to include as part of a build Action.
Common examples are timestamp strings,
revision control version strings
and other run-time generated strings.
</para>
<para>
A Value Node can also be the target of a builder.
</para>
</refsect3>
</refsect2>
</refsect1>
<refsect1 id='extending_scons'>
<title>EXTENDING SCONS</title>
<para>
&SCons; is designed to be extensible through provided facilities,
so changing the code of &SCons; itself is only rarely needed
to customize its behavior.
A number of the main operations use callable objects
which can be supplemented by writing your own.
Builders, Scanners and Tools each use a kind of plugin system,
allowing you to easily drop in new ones.
Information about creating
<link linkend='builder_objects'>Builder Objects</link> and
<link linkend='scanner_objects'>Scanner Objects</link>
appear in the following sections.
The instructions &SCons; actually uses to
construct things are called Actions,
and it is easy to create Action Objects and hand them
to the objects that need to know about those actions
(besides Builders, see &f-link-AddPostAction;,
&f-link-AddPreAction; and &f-link-Alias; for some examples
of other places that take Actions).
<link linkend='action_objects'>Action Objects</link>
are also described below.
Adding new Tool modules is described in
<link linkend='tool_modules'>Tool Modules</link>
</para>
<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.
For output file types &scons; already knows about,
you can usually modify the behavior of premade Builders
such as &b-link-Program;, &b-link-Object; or &b-link-Library;
by changing the &consvars; they use
(&cv-link-CC;, &cv-link-LINK;, etc.).
In this manner you can, for example, change the compiler to use,
which is simpler and less error-prone than writing a new builder.
The documentation for each Builder lists which
&consvars; it uses.
</para>
<para>Builder objects are created
using the
&f-link-Builder;
factory function.
Once created, a builder is added to an environment
by entering it in the &cv-link-BUILDERS; dictionary
in that environment (some of the examples
in this section illustrate this).
Doing so automatically triggers &SCons; to add a method
with the name of the builder to the environment.
</para>
<para>
The
&f-Builder;
function accepts the following keyword arguments:</para>
<variablelist>
<varlistentry>
<term><parameter>action</parameter></term>
<listitem>
<para>The command used to build the target from the source.
<parameter>action</parameter>
may be a string representing a template command line to execute,
a list of strings representing the command
to execute with 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 <link linkend='action_objects'>Action Objects</link>)
or a list of any of the above.</para>
<para>An action function must accept three arguments:
<parameter>source</parameter>,
<parameter>target</parameter> and
<parameter>env</parameter>.
<parameter>source</parameter> is a list of source nodes;
<parameter>target</parameter> is a list of target nodes;
<parameter>env</parameter> is the &consenv; to use for context.
</para>
<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 to prepend to the target file name.
<parameter>prefix</parameter> may be
a string, a function (or other callable) that takes
two arguments (a &consenv; and a list of sources)
and returns a prefix string,
or a dictionary specifying a mapping from a specific source suffix
(of the first source specified)
to a corresponding target prefix string. For the dictionary form, both the source
suffix (key) and target prefix (value) specifications may use environment variable
substitution, and the target prefix
may also be a callable object. The default target prefix
may be indicated by a dictionary entry with a key of <constant>None</constant>.</para>
<programlisting language="python">
b = Builder("build_it &lt; $SOURCE &gt; $TARGET",
prefix="file-")
def gen_prefix(env, sources):
return "file-" + env['PLATFORM'] + '-'
b = Builder("build_it &lt; $SOURCE &gt; $TARGET",
prefix=gen_prefix)
b = Builder("build_it &lt; $SOURCE &gt; $TARGET",
suffix={None: "file-", "$SRC_SFX_A": gen_prefix})
</programlisting>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>suffix</parameter></term>
<listitem>
<para>The suffix to append to the target file name.
Specified in the same manner as for <parameter>prefix</parameter> above.
If the suffix is a string, then
&scons;
prepends a <literal>'.'</literal> to the suffix if it's not already there.
The string returned by the callable object or obtained from the
dictionary is untouched and you need to manually prepend a <literal>'.'</literal>
if one is required.</para>
<programlisting language="python">
b = Builder("build_it &lt; $SOURCE &gt; $TARGET"
suffix="-file")
def gen_suffix(env, sources):
return "." + env['PLATFORM'] + "-file"
b = Builder("build_it &lt; $SOURCE &gt; $TARGET",
suffix=gen_suffix)
b = Builder("build_it &lt; $SOURCE &gt; $TARGET",
suffix={None: ".sfx1", "$SRC_SFX_A": gen_suffix})
</programlisting>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>ensure_suffix</parameter></term>
<listitem>
<para>If set to a true value,
ensures that targets will end in
<parameter>suffix</parameter>.
Thus, the suffix will also be added to any target strings
that have a suffix that is not already <parameter>suffix</parameter>.
The default behavior (also indicated by a false value)
is to leave unchanged
any target string that looks like it already has a suffix.</para>
<programlisting language="python">
b1 = Builder("build_it &lt; $SOURCE &gt; $TARGET"
suffix = ".out")
b2 = Builder("build_it &lt; $SOURCE &gt; $TARGET"
suffix = ".out",
ensure_suffix=True)
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.
<parameter>src_suffix</parameter>
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 id="emitter_function">
<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>A function passed as <parameter>emitter</parameter>
must accept three arguments:
<parameter>source</parameter>,
<parameter>target</parameter> and
<parameter>env</parameter>.
<parameter>source</parameter> is a list of source nodes,
<parameter>target</parameter> is a list of target nodes,
<parameter>env</parameter> is the &consenv; to use for context.
</para>
<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 &lt; $TARGET &gt; $SOURCE", emitter=e)
def e2(target, source, env):
return target + ['bar.foo'], source + ['bar.src']
# Simple association of a list of emitter functions with a Builder.
b = Builder("my_build &lt; $TARGET &gt; $SOURCE", emitter=[e, e2])
# Calling an emitter function through a construction variable.
env = Environment(MY_EMITTER=e)
b = Builder("my_build &lt; $TARGET &gt; $SOURCE", emitter='$MY_EMITTER')
# Calling a list of emitter functions through a construction variable.
env = Environment(EMITTER_LIST=[e, e2])
b = Builder("my_build &lt; $TARGET &gt; $SOURCE", emitter='$EMITTER_LIST')
# Associating multiple emitters with different file
# suffixes using a dictionary.
def e_suf1(target, source, env):
return target + ['another_target_file'], source
def e_suf2(target, source, env):
return target, source + ['another_source_file']
b = Builder(
action="my_build &lt; $TARGET &gt; $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>False</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 id="generator_function">
<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>A function passed as <parameter>generator</parameter>
must accept four arguments:
<parameter>source</parameter>,
<parameter>target</parameter>,
<parameter>env</parameter> and
<parameter>for_signature</parameter>.
<parameter>source</parameter> is a list of source nodes,
<parameter>target</parameter> is a list of target nodes,
<parameter>env</parameter> is the &consenv; to use for context,
and <parameter>for_signature</parameter> is
a Boolean value that tells the function
if it is being called for the purpose of generating a &buildsig;
(as opposed to actually executing the command).
Since the &buildsig; is used for rebuild determination,
the function should omit those elements
that do not affect whether a rebuild should be triggered
if <parameter>for_signature</parameter> is true.
</para>
<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
<constant>False</constant>
or some other non-true value.
In this case, &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 &gt; $TARGET'},
source_ext_match=False)
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 &lt; $SOURCE &gt; $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 &lt; ${SOURCE.file} &gt; ${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 such 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).
These extra keyword arguments are passed to the
following functions:
<link linkend='generator_function'>command generator functions</link>,
<link linkend='miscellaneous_action_functions'>function Actions</link>,
and
<link linkend='emitter_function'>emitter functions</link>.
</para>
</refsect2>
<refsect2 id='action_objects'>
<title>Action Objects</title>
<para>The
&f-link-Builder;
factory function will turn its
<parameter>action</parameter>
keyword argument into an appropriate
internal Action object, as will
the &f-link-Command; function.
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 may more efficient when multiple
Builder objects need to do the same thing
rather than letting each of those Builder objects
create a separate Action object.
It also allows more flexible configuration
of an Action object. For example, to control
the message printed when the action is taken
you need to create the action object using &f-Action;.
</para>
<para>The
&Action; factory function
returns an appropriate object for the action
represented by the type of the
<parameter>action</parameter> argument
(the first positional parameter):</para>
<itemizedlist>
<listitem>
<para>If <parameter>action</parameter> is already an Action object,
the object is simply returned.</para>
</listitem>
<listitem>
<para>If <parameter>action</parameter> is a string,
a command-line Action is returned.
If such a string begins with <literal>@</literal>,
the command line is not printed.
If the string begins with hyphen
(<literal>-</literal>),
the exit status from the specified command
is 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 <parameter>action</parameter> 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 within
the list is itself a list,
the embedded 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 <parameter>action</parameter> is a callable object,
a Function Action is returned.
The callable must accept three keyword arguments:
<parameter>target</parameter>,
<parameter>source</parameter> and
<parameter>env</parameter>.
<parameter>target</parameter>
is a Node object representing the target file,
<parameter>source</parameter>
is a Node object representing the source file and
<parameter>env</parameter>
is the &consenv; used for building the target file.
</para>
<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
<parameter>action</parameter>
is not one of the above types,
no action object is generated and &f-Action;
returns <constant>None</constant>.</para>
</listitem>
</itemizedlist>
<para>The environment method form &f-link-env-Action;
will expand &consvars; in any argument strings,
including
<parameter>action</parameter>,
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;
delays variable expansion until
the Action object is actually used.
</para>
<para>The optional second argument to &f-Action;
is used to control the output
which is printed when the Action is actually performed.
If this parameter is omitted,
or if the value is 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 following argument types are accepted:
</para>
<itemizedlist>
<listitem>
<para>If the second argument is a string,
or if the <parameter>cmdstr</parameter> keyword argument is supplied,
the string defines what is printed.
Substitution is performed on the string before it is printed.
The string typically contains substitutable 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>
<listitem>
<para>If the second argument is a function,
or if the <parameter>strfunction</parameter> keyword argument is supplied,
the function will be called to obtain the string
to be printed when the action is performed.
The function
must accept three keyword arguments:
<parameter>target</parameter>,
<parameter>source</parameter> and
<parameter>env</parameter>,
with the same interpretation as for a callable
<parameter>action</parameter> argument above.
The function is responsible for handling any required substitutions.
</para>
</listitem>
<listitem>
<para>If the second argument is <constant>None</constant>,
or if <literal>cmdstr=None</literal> is supplied,
output is suppressed entirely.</para>
</listitem>
</itemizedlist>
<para>
The <parameter>cmdstr</parameter> and
<parameter>strfunction</parameter>
keyword arguments may not both be supplied in a single call to &f-Action;
</para>
<para>
Printing of action strings is affected by the setting of
&cv-link-PRINT_CMD_LINE_FUNC;.
</para>
<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
(the &buildsig;)
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>
If <parameter>chdir</parameter> is true
(the default is <constant>False</constant>),
&SCons; will change directories before
executing the action.
If the value of <parameter>chdir</parameter>
is a string or a directory Node,
&SCons; will change to the specified directory.
Otherwise, if <parameter>chdir</parameter> evaluates true,
&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>
parameter - 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 &lt; ${SOURCE.file} &gt; ${TARGET.file}", chdir=True)
</programlisting>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>exitstatfunc</parameter></term>
<listitem>
<para>
If provided, must be a callable which accepts a single parameter,
the exit status (or return value)
from the specified action,
and which returns 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 &lt; ${SOURCE.file} &gt; ${TARGET.file}",
exitstatfunc=always_succeed)
</programlisting>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>batch_key</parameter></term>
<listitem>
<para>
If provided, indicates 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 four parameters:
<parameter>action</parameter>,
<parameter>env</parameter>,
<parameter>target</parameter> and
<parameter>source</parameter>.
The first parameter, <parameter>action</parameter>,
is the active action object.
The second parameter, <parameter>env</parameter>,
is the &consenv; configured for the target.
The <parameter>target</parameter> and <parameter>source</parameter>
parameters are the lists of targets and sources
for the configured action.
</para>
<para>The returned key should typically
be a tuple of values derived from the arguments,
using any appropriate logic to decide
how multiple invocations should be batched.
For example, a
<parameter>batch_key</parameter>
function may decide to return
the value of a specific &consvar;
from <parameter>env</parameter>
which will cause
&scons;
to batch-build targets
with matching values of that &consvar;,
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>
<refsect3 id='miscellaneous_action_functions'>
<title>Miscellaneous Action Functions</title>
<para>&SCons;
supplies Action 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>
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:</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 &amp;&amp; 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 POSIX
<command>chmod</command> 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>
<para>
The behavior of <function>Chmod</function> is limited on Windows,
see the notes in the Python documentation for
<systemitem>os.chmod</systemitem>, which is the underlying function.
</para>
</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.
If <parameter>src</parameter> is a list,
<parameter>dest</parameter> must be a directory
if it already exists.
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>name</parameter>)</term>
<listitem>
<para>Returns an Action
that creates the directory
<parameter>name</parameter>
and all needed intermediate directories.
<parameter>name</parameter> may also be a list
of directories to create.
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 &amp;&amp; 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>
</refsect3>
<refsect3 id='variable_substitution'>
<title>Variable Substitution</title>
<para>
Before executing a command, &scons;
performs parameter expansion (<firstterm>substitution</firstterm>)
on the string that makes up the action part of the builder.
The format of a substitutable parameter is
<literal>${<replaceable>expression</replaceable>}</literal>.
If <replaceable>expression</replaceable> refers to a variable,
the braces in <literal>${<replaceable>expression</replaceable>}</literal>
can be omitted <emphasis>unless</emphasis> the variable name is
immediately followed by a character that could either be interpreted
as part of the name, or is &Python; syntax such as
<emphasis role="bold">[</emphasis> (for indexing/slicing)
or <emphasis role="bold">.</emphasis> (for attribute access -
see <link linkend="special_attributes">Special Attributes</link> below).
</para>
<para>
If <replaceable>expression</replaceable> refers to a &consvar;,
it is replaced with the value of that variable in the
&consenv; at the time of execution.
If <replaceable>expression</replaceable> looks like
a variable name but is not defined in the &consenv;
it is replaced with an empty string.
If <replaceable>expression</replaceable> refers to one of the
<link linkend="special_variables">Special Variables</link>
(see below) the corresponding value of the variable is substituted.
<replaceable>expression</replaceable> may also be
a &Python; expression to be evaluated.
See <link linkend='python_code_substitution'>Python Code Substitution</link>
below for a description.
</para>
<para>&SCons; uses the following rules when converting &consvars; into
command line strings:</para>
<itemizedlist>
<listitem>
<para>If the value is a string it is interpreted as space delimited
command line arguments.</para>
</listitem>
<listitem>
<para>If 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>
<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>
<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>
<listitem>
<para>For a literal <emphasis role="bold">$</emphasis>
use <emphasis role="bold">$$</emphasis>.
For example, <literal>$$FOO</literal> will be left in the
final string as <literal>$FOO</literal>.</para>
</listitem>
</itemizedlist>
<para>
When a build action is executed, a hash of the command line is
saved, together with other information about the target(s) built
by the action, for future use in rebuild determination.
This is called the <firstterm>&buildsig;</firstterm>
(or <firstterm>&build_action; signature</firstterm>).
The escape sequence
<emphasis role="bold">$(</emphasis>
<replaceable>subexpression</replaceable>
<emphasis role="bold">$)</emphasis>
may be used to indicate parts of a command line
that may change without
causing a rebuild--that is,
which are not to be included when calculating the &buildsig;.
All text from
<emphasis role="bold">$(</emphasis>
up to and including the matching
<emphasis role="bold">$)</emphasis>
will be removed from the command line
before it is added to the &buildsig;
while only the
<emphasis role="bold">$(</emphasis>
and
<emphasis role="bold">$)</emphasis>
will be removed before the command is executed.
For example, the command line string:</para>
<programlisting language="python">
"echo Last build occurred $( $TODAY $). &gt; $TARGET"
</programlisting>
<para>would execute the command:</para>
<screen>
echo Last build occurred $TODAY. &gt; $TARGET
</screen>
<para>but the build signature added to any target files would be computed from:</para>
<screen>
echo Last build occurred . &gt; $TARGET
</screen>
<para>While &consvars; are normally directly substituted,
if a &consvar; has a value which
is a callable &Python; object
(a function, or a class with a <literal>__call__</literal> method),
that object is called during substitution.
The callable must accept four arguments:
<parameter>target</parameter>,
<parameter>source</parameter>,
<parameter>env</parameter> and
<parameter>for_signature</parameter>.
<parameter>source</parameter> is a list of source nodes,
<parameter>target</parameter> is a list of target nodes,
<parameter>env</parameter> is the &consenv; to use for context,
and <parameter>for_signature</parameter> is
a boolean value that tells the callable
if it is being called for the purpose of generating a build signature.
Since the build signature is used for rebuild determination,
variable elements that do not affect whether
a rebuild should be triggered
should be omitted from the returned string
if <parameter>for_signature</parameter> is true.
See <emphasis role="bold">$(</emphasis>
and <emphasis role="bold">$)</emphasis> above
for the syntax.
</para>
<para>
&SCons; will insert whatever
the callable 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>As a reminder, substitution happens when
<literal>$BAR</literal> is actually used in a
builder action. The value of <literal>env['BAR']</literal>
will be exactly as it was set: <literal>"$FOO baz"</literal>.
This can make debugging tricky,
as the substituted result is not available at the time
the SConscript files are being interpreted and
thus not available to <systemitem>print()</systemitem>.
However, you can perform the substitution on demand
by calling the &f-link-env-subst; method for this purpose.
</para>
<para>You can use this feature to pass arguments to a
callable variable by creating a callable class
that stores passed arguments in the instance,
and then uses them
(in the <methodname>__call__</methodname> method)
when the instance 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>
</refsect3>
<refsect3 id='special_variables'>
<title>Substitution: Special Variables</title>
<para>
Besides regular &consvars;, scons provides the following
<firstterm>Special Variables</firstterm> for use in expanding commands:</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>
These names are reserved
and may not be assigned to or used as &consvars;.
&SCons; computes them in a context-dependent manner
and they and are not retrieved from a &consenv;.
</para>
<para>For example, the following builder call:
</para>
<programlisting language="python">
env = Environment(CC='cc')
env.Command(
target=['foo'],
source=['foo.c', 'bar.c'],
action='@echo $CC -c -o $TARGET $SOURCES'
)
</programlisting>
<para>would produce the following output:</para>
<screen>
cc -c -o foo foo.c bar.c
</screen>
<para>
In the previous example, a string
<code>${SOURCES[1]}</code>
would expand to: <computeroutput>bar.c</computeroutput>.
</para>
</refsect3>
<refsect3 id='special_attributes'>
<title>Substitution: Special Attributes
</title>
<para>A variable name may
have the following
modifiers appended within the enclosing curly braces
to access properties of the interpolated string.
These are known as <firstterm>special attributes</firstterm>.
</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>relpath</parameter> - The path name of the file relative to the root SConstruct file's directory.</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 =&gt; sub/dir/file.x
${TARGET.base} =&gt; sub/dir/file
${TARGET.dir} =&gt; sub/dir
${TARGET.file} =&gt; file.x
${TARGET.filebase} =&gt; file
${TARGET.suffix} =&gt; .x
${TARGET.abspath} =&gt; /top/dir/sub/dir/file.x
${TARGET.relpath} =&gt; sub/dir/file.x
$TARGET =&gt; ../dir2/file.x
${TARGET.abspath} =&gt; /top/dir2/file.x
${TARGET.relpath} =&gt; ../dir2/file.x
SConscript('src/SConscript', variant_dir='sub/dir')
$SOURCE =&gt; sub/dir/file.x
${SOURCE.srcpath} =&gt; src/file.x
${SOURCE.srcdir} =&gt; src
Repository('/usr/repository')
$SOURCE =&gt; sub/dir/file.x
${SOURCE.rsrcpath} =&gt; /usr/repository/src/file.x
${SOURCE.rsrcdir} =&gt; /usr/repository/src
</literallayout>
<para>
Some modifiers can be combined, like
<literal>${TARGET.srcpath.base)</literal>,
<literal>${TARGET.file.suffix}</literal>, etc.
</para>
</refsect3>
<refsect3 id='python_code_substitution'>
<title>Python Code Substitution</title>
<para>
If a substitutable expression using the notation
<literal>${<replaceable>expression</replaceable>}</literal>
does not appear to match one of the other substitution patterns,
it is evaluated as a Python expression.
This uses Python's <function>eval</function> function,
with the <parameter>globals</parameter> parameter set to
the current environment's set of &consvars;,
and the result substituted in.
So in the following case:</para>
<programlisting language="python">
env.Command(
'foo.out', 'foo.in', "echo ${COND==1 and 'FOO' or 'BAR'} &gt; $TARGET"
)
</programlisting>
<para>the command executed will be either</para>
<screen>
echo FOO &gt; foo.out
</screen>
<para>or</para>
<screen>
echo BAR &gt; 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 complete 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'] = 1
env['FOO'] = ['foo1', 'foo2']
env['BAR'] = 'barbar'
env.Command(
'foo.out', 'foo.in', "echo ${COND==1 and FOO or BAR} &gt; $TARGET"
)
</programlisting>
<para>will execute:</para>
<screen>
echo foo1 foo2 &gt; foo.out
</screen>
<para>
In point of fact, Python expression evaluation is
how the special attributes are substituted:
they are simply attributes of the Python objects
that represent &cv-TARGET;, &cv-SOURCES;, etc.,
which &SCons; passes to <function>eval</function> which
returns the value.
</para>
<note><para>
Use of the Python <function>eval</function> function
is considered to have security implications, since,
depending on input sources,
arbitrary unchecked strings of code can be executed by the Python interpreter.
Although &SCons; makes use of it in a somewhat restricted context,
you should be aware of this issue when using the
<literal>${python-expression-for-subst}</literal> form.
</para></note>
</refsect3>
</refsect2>
<refsect2 id='scanner_objects'>
<title>Scanner Objects</title>
<para>
Scanner objects are used
to scan specific file types for implicit dependencies,
for example embedded preprocessor/compiler directives
that cause other files to be included during processing.
&SCons; has a number of pre-built Scanner objects,
so it is usually only necessary to set up Scanners for new file types.
You do this by calling the &f-link-Scanner; factory function.
&f-Scanner; accepts the following arguments.
Only <parameter>function</parameter> is required;
the rest are optional:
</para>
<variablelist>
<varlistentry>
<term><parameter>function</parameter></term>
<listitem>
<para>
A scanner function to call to process
a given Node (usually a file)
and return a list of Nodes
representing the implicit
dependencies (usually files) found in the contents.
The function must accept three required arguments,
<parameter>node</parameter>,
<parameter>env</parameter> and
<parameter>path</parameter>,
and an optional fourth,
<parameter>arg</parameter>.
<parameter>node</parameter> is
the internal &SCons; node representing the file to scan,
<parameter>env</parameter> is the &consenv; to use during
the scan, and <parameter>path</parameter> is a tuple
of directories that can be searched for files,
as generated by the optional scanner
<parameter>path_function</parameter> (see below).
If <parameter>argument</parameter> was supplied when the Scanner
object was created, it is given as <parameter>arg</parameter>
when the scanner function is called; since <parameter>argument</parameter>
is optional, the default is no <parameter>arg</parameter>.
</para>
<para>
The function can use use
<function>str</function>(<parameter>node</parameter>)
to fetch the name of the file,
<replaceable>node</replaceable>.<function>dir</function>
to fetch the directory the file is in,
<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 of the file as text.
</para>
<para>
The function must take into account the <parameter>path</parameter>
directories when generating the dependency Nodes. To illustrate this,
a C language source file may contain a line like
<literal>#include "foo.h"</literal>. However, there is no guarantee
that <filename>foo.h</filename> exists in the current directory:
the contents of &cv-link-CPPPATH; is passed to the C preprocessor which
will look in those places for the header,
so the scanner function needs to look in those places as well
in order to build Nodes with correct paths.
Using &f-link-FindPathDirs; with an argument of <literal>CPPPATH</literal>
as the <parameter>path_function</parameter> in the &f-Scanner; call
means the scanner function will be called with the paths extracted
from &cv-CPPPATH; in the environment <parameter>env</parameter>
passed as the <parameter>paths</parameter> parameter.
</para>
<para>
Note that the file to scan is
<emphasis>not</emphasis>
guaranteed to exist at the time the scanner is called -
it could be a generated file which has not been generated yet -
so the scanner function must be tolerant of that.
</para>
<para>
Alternatively, you can supply a dictionary as the
<parameter>function</parameter> parameter,
to map keys (such as file suffixes) to other Scanner objects.
A Scanner created this way serves as a dispatcher:
the Scanner's <parameter>skeys</parameter> parameter is
automatically populated with the dictionary's keys,
indicating that the Scanner handles Nodes which would be
selected by those keys; the mapping is then used to pass
the file on to a different Scanner that would not have been
selected to handle that Node based on its
own <parameter>skeys</parameter>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>name</parameter></term>
<listitem>
<para>The name to use for the Scanner.
This is mainly used to identify the Scanner internally.
The default value is <literal>"NONE"</literal>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>argument</parameter></term>
<listitem>
<para>If specified,
will be passed to the scanner function
<parameter>function</parameter>
and the path function
<parameter>path_function</parameter>
when called,
as the optional parameter each of those functions takes.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>skeys</parameter></term>
<listitem>
<para>Scanner key(s) indicating the file types
this scanner is associated with.
Used internally to select an appropriate scanner.
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 <parameter>skeys</parameter> is a string,
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 the value of <parameter>argument</parameter>
if it was supplied when the Scanner was created.
Must return 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.
A value of <constant>None</constant> can
be supplied to indicate no conversion;
the default is to return File nodes.
</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,
as indicated by <parameter>node_class</parameter>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>scan_check</parameter></term>
<listitem>
<para>A 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>
Specifies whether this scanner should be re-invoked
on the dependency files returned by the scanner.
If omitted, the Node subsystem will
only invoke the scanner on the file being scanned
and not recurse.
Recursion is needed when the files returned by the
scanner may themselves contain further file dependencies,
as in the case of preprocessor <literal>#include</literal> lines.
A value that evaluates true enables recursion;
<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>
Once created, a Scanner can added to an environment
by setting it in the &cv-link-SCANNERS; list,
which automatically triggers &SCons; to also add it
to the environment as a method.
However, usually a scanner is not truly standalone, but needs to
be plugged in to the existing selection mechanism for
deciding how to scan source files based on filename extensions.
For this, &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.
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>
<refsect2 id='tool_modules'>
<title>Tool Modules</title>
<para>
Additional tools can be added to a project either by
placing them in a <filename>site_tools</filename> subdirectory
of a site directory, or in a custom location specified to
&scons; by giving the
<parameter>toolpath</parameter> keyword argument to &f-link-Environment;.
A tool module is a form of Python module, invoked internally
using the Python import mechanism, so a tool can consist either
of a single source file taking the name of the tool
(e.g. <filename>mytool.py</filename>) or a directory taking
the name of the tool (e.g. <filename>mytool/</filename>)
which contains at least an <filename>__init__.py</filename> file.
</para>
<para>
The <parameter>toolpath</parameter> parameter
takes a list as its value:
</para>
<programlisting language="python">
env = Environment(tools=['default', 'foo'], toolpath=['tools'])
</programlisting>
<para>
This looks for a tool specification module (<filename>mytool.py</filename>,
or directory <filename>mytool</filename>)
in directory <filename>tools</filename> and in the standard locations,
as well as using the ordinary default tools for the platform.
</para>
<para>
Directories specified via <parameter>toolpath</parameter> are prepended
to the existing tool path.
The default tool path is any <filename>site_tools</filename> directories,
so tools in a specified <parameter>toolpath</parameter> take priority,
followed by tools in a <filename>site_tools</filename> directory,
followed by built-in tools. For example, adding
a tool specification module <filename>gcc.py</filename> to the toolpath
directory would override the built-in &t-link-gcc; tool.
The tool path is stored in the environment and will be
used by subsequent calls to the &f-link-Tool; method,
as well as by &f-link-env-Clone;.
</para>
<programlisting language="python">
base = Environment(toolpath=['custom_path'])
derived = base.Clone(tools=['custom_tool'])
derived.CustomBuilder()
</programlisting>
<para>
A tool specification module must include two functions:
</para>
<variablelist>
<varlistentry>
<term><function>generate</function>(<parameter>env, **kwargs</parameter>)</term>
<listitem>
<para>Modify the &consenv; <parameter>env</parameter>
to set up necessary &consvars;, Builders, Emitters, etc.,
so the facilities represented by the tool can be executed.
Care should be taken not to overwrite &consvars; intended
to be settable by the user. For example:
</para>
<programlisting language="python">
def generate(env):
...
if 'MYTOOL' not in env:
env['MYTOOL'] = env.Detect("mytool")
if 'MYTOOLFLAGS' not in env:
env['MYTOOLFLAGS'] = SCons.Util.CLVar('--myarg')
...
</programlisting>
<para>The <function>generate</function> function
may use any keyword arguments
that the user supplies via <parameter>kwargs</parameter>
to vary its initialization.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><function>exists</function>(<parameter>env</parameter>)</term>
<listitem>
<para>Return a true value if the tool can
be called in the context of <parameter>env</parameter>.
else false.
Usually this means looking up one or more
known programs using the <varname>PATH</varname> from the
supplied <parameter>env</parameter>, but the tool can
make the <emphasis>exists</emphasis> decision in any way it chooses.
</para>
</listitem>
</varlistentry>
</variablelist>
<note>
<para>
At the moment, user-added tools do not automatically have their
<function>exists</function> function called.
As a result, it is recommended that the <function>generate</function>
function be defensively coded - that is, do not rely on any
necessary existence checks already having been performed.
This is expected to be a temporary limitation,
and the <function>exists</function> function should still be provided.
</para>
</note>
<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
<literal>(toolname, kw_dict)</literal>.
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 specification (<function>my_tool</function> in the example)
can use the
&cv-link-PLATFORM; 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.copy(), 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>
</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>Fortran File Suffixes</title>
<para>
There are several ways source file suffixes impact the
behavior of &SCons; when working with Fortran language code
(not all are system-specific, but they are included here
for completeness).
</para>
<para>
As the Fortran language has evolved through multiple
standards editions, projects might have a need to handle
files from different language generations differently.
To this end, &SCons; dispatches to a different compiler
dialect setup (expressed as a set of &consvars;)
depending on the file suffix.
By default, all of these setups start out the same,
but individual &consvars; can be modified as needed to tune a given dialect.
Each of these dialacts has a tool specification module
whose documentation describes the &consvars; associated
with that dialect: <filename>.f</filename>
(as well as <filename>.for</filename> and <filename>.ftn</filename>)
in &t-link-fortran;; (&consvars; start with <literal>FORTRAN</literal>)
<filename>.f77</filename> in &t-link-f77;;
(&consvars; start with <literal>F77</literal>)
<filename>.f90</filename> in &t-link-f90;;
(&consvars; start with <literal>F90</literal>)
<filename>.f95</filename> in &t-link-f95;;
(&consvars; start with <literal>F95</literal>)
<filename>.f03</filename> in &t-link-f03;;
(&consvars; start with <literal>F03</literal>)
<filename>.f08</filename> in &t-link-f08;
(&consvars; start with <literal>F08</literal>).
</para>
<para>
While &SCons; recognizes multiple internal dialects
based on filename suffixes,
the convention of various available Fortran compilers is
to assign an actual meaning to only two of these suffixes:
<filename>.f</filename>
(as well as <filename>.for</filename> and <filename>.ftn</filename>)
refers to the fixed-format source
code that was the only available option in FORTRAN 77 and earlier,
and <filename>.f90</filename> refers to free-format source code
which became available as of the Fortran 90 standard.
Some compilers recognize suffixes which correspond to Fortran
specifications later then F90 as equivalent to
<filename>.f90</filename> for this purpose,
while some do not - check the documentation for your compiler.
An occasionally suggested policy suggestion is to use only
<filename>.f</filename> and <filename>.f90</filename>
as Fortran filename suffixes.
The fixed/free form determination can usually be controlled
explicitly with compiler flags
(e.g. <option>-ffixed-form</option> for gfortran),
overriding any assumption that may be made based on the source file suffix.
</para>
<para>
The source file suffix does not imply conformance
with the similarly-named Fortran standard - a suffix of
<filename>.f08</filename> does not mean you are compiling
specifically for Fortran 2008. Normally, compilers
provide command-line options for making this selection
(e.g. <option>-std=f2008</option> for gfortran).
</para>
<para>
For dialects from F90 on (including the generic FORTRAN dialect),
a suffix of <filename>.mod</filename> is recognized for Fortran modules.
These files are a side effect of compiling a Fortran
source file containing module declarations,
and must be available when other code which declares
that it uses the module is processed.
&SCons; does not currently have integrated support for submodules,
introduced in the Fortran 2008 standard -
the invoked compiler will produce results,
but &SCons; will not recognize
<filename>.smod</filename> files as tracked objects.
</para>
<para>
On a case-sensitive system such as Linux or UNIX,
a file with a an upper-cased suffix from the set
<filename>.F</filename>,
<filename>.FOR</filename>,
<filename>.FTN</filename>,
<filename>.F90</filename>,
<filename>.F95</filename>,
<filename>.F03</filename> and
<filename>.F08</filename>
is treated as a Fortran source file
which shall first be run through
the standard C preprocessor.
The lower-cased versions of these suffixes do not
trigger this behavior.
On systems which do not distinguish between uppper
and lower case in filenames,
this behavior is not available,
but files suffixed with either
<filename>.FPP</filename>
or <filename>.fpp</filename>
are always passed to the preprocessor first.
This matches the convention of <command>gfortran</command>
from the GNU Compiler Collection,
and also followed by certain other Fortran compilers.
For these two suffixes,
the generic <emphasis>FORTRAN</emphasis> dialect will be selected.
</para>
<para>
&SCons; itself does not invoke the preprocessor,
that is handled by the compiler,
but it adds &consvars; which are applicable to the preprocessor run.
You can see this difference by examining
&cv-link-FORTRANPPCOM; and &cv-link-FORTRANPPCOMSTR;
which are used instead of
&cv-link-FORTRANCOM; and &cv-link-FORTRANCOMSTR; for that dialect.
</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 POSIX-like environment.
The Cygwin tools, including Cygwin &Python;,
do this, in part,
by sharing an ability to interpret POSIX-style 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 understand the Cygwin path name semantics.
This means that using a native Windows version of &Python;
to build compiled programs using Cygwin tools
(such as &gcc;, &bison; and &flex;)
may yield unpredictable results.
"Mixing and matching" in this way
can be made to work,
but it requires careful attention to the use of path names
in your SConscript files.</para>
<para>In practice, users can sidestep
the issue by adopting the following guidelines:
When using Cygwin's &gcc; for compiling,
use the Cygwin-supplied &Python; interpreter
to run &scons;;
when using Microsoft Visual C/C++
(or some other "native" Windows compiler)
use the python.org, Microsoft Store, ActiveState or other
native version of &Python; to run &scons;.
</para>
<para>
This discussion largely applies to the msys2 environment
as well (with the use of the mingw compiler toolchain),
in particular the recommendation to use the msys2 version of
&Python; if running &scons; from inside an msys2 shell.
</para>
</refsect2>
<refsect2 id='windows_sconsbat_file'>
<title>Windows: <filename>scons.bat</filename> file</title>
<para>On Windows, if &scons; is executed via a wrapper
<filename>scons.bat</filename> batch file,
there are (at least) two ramifications.
Note this is no longer the default - &scons; installed
via &Python;''s <command>pip</command> installer
will have an <command>scons.exe</command> which does
not have these limitations:
</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, otherwise the
Windows command shell will consume those as
arguments to itself, not to &scons;:</para>
<screen>
<userinput>scons "FOO=BAR" "BAZ=BLEH"</userinput>
</screen>
<para>Second, the Cygwin shell does not
recognize typing <userinput>scons</userinput>
at the command line prompt as referring to this wrapper.
You can work around this either by executing
<userinput>scons.bat</userinput>
(including the extension)
from the Cygwin command line,
or by creating a wrapper shell
script named
<filename>scons</filename> which
invokes <filename>scons.bat</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
<varname>['ENV']['PATH']</varname> &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 &lt; $SOURCES &gt; $TARGET',
suffix='.pdf',
src_suffix='.tex'
)
env = Environment(BUILDERS={'PDFBuilder': bld})
env.PDFBuilder(target='foo.pdf', source='foo.tex')
# The following creates "bar.pdf" from "bar.tex"
env.PDFBuilder(target='bar', source='bar')
</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 &lt; $SOURCES &gt; $TARGET'
suffix='.pdf',
src_suffix='.tex'
)
env = Environment()
env.Append(BUILDERS={'PDFBuilder': bld})
env.PDFBuilder(target='foo.pdf', source='foo.tex')
env.Program(target='bar', source='bar.c')
</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 &lt; $SOURCES &gt; $TARGET')
bar_in = File('bar.in')
env.Command('bar', bar_in, 'kprocess $SOURCES &gt; $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 &lt; $SOURCES &gt; $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 &lt;windows.h&gt;
#include &lt;my_big_header.h&gt;
</programlisting>
<para><filename>StdAfx.cpp</filename>:</para>
<programlisting language="C++">
#include &lt;StdAfx.h&gt;
</programlisting>
<para><filename>Foo.cpp</filename>:</para>
<programlisting language="C++">
#include &lt;StdAfx.h&gt;
/* do some stuff */
</programlisting>
<para><filename>Bar.cpp</filename>:</para>
<programlisting language="C++">
#include &lt;StdAfx.h&gt;
/* 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 id="v-SCONSFLAGS">
<term><envar>SCONSFLAGS</envar></term>
<listitem>
<para>A string containing options that will be used by &scons;
in addition to those passed on the command line.
Can be used to reduce frequent retyping of common options.
The contents of <envar>SCONSFLAGS</envar> are considered
before any passed command line options,
so the command line can be used to override
<envar>SCONSFLAGS</envar> options if necessary.
</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 cache file, to give these settings
persistence across &scons; invocations.
Generating this information is relatively expensive,
so using this option may aid performance where &scons; is run often,
such as 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.json</filename> in the user's home directory.
If set to a pathname, will use that pathname for the cache.</para>
<para>Note: this implementation may still be somewhat fragile.
In case of problems, remove the cache file - recreating with
fresh info normally resolves any issues.
&SCons; ignores failures reading or writing the cache file
and will silently revert to non-cached behavior in such cases.
</para>
<para><emphasis>New in 3.1 (experimental).
The default cache file name was changed to
its present value in 4.4, and contents were expanded.</emphasis>
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><envar>QTDIR</envar></term>
<listitem>
<para>If using the &t-link-qt; tool, this is the path to
the Qt installation to build against. &SCons; respects this
setting because it is a long-standing convention in the Qt world,
where multiple Qt installations are possible.</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>
Reference in New Issue View Git Blame Copy Permalink