13962 lines
754 KiB
HTML
13962 lines
754 KiB
HTML
<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>SCons 3.0.4</title><link rel="stylesheet" type="text/css" href="scons.css"><meta name="generator" content="DocBook XSL Stylesheets V1.76.1"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="reference" title="SCons 3.0.4"><div class="titlepage"><div><div><h1 class="title"><a name="idm1"></a>SCons 3.0.4</h1></div><div><h2 class="subtitle">MAN page</h2></div><div><h3 class="corpauthor">Steven Knight and the SCons Development Team</h3></div><div><div class="author"><h3 class="author"><span class="firstname">Steven</span> <span class="surname">Knight</span></h3></div></div><div><p class="releaseinfo">version 3.0.4</p></div><div><p class="copyright">Copyright © 2004 - 2019 The SCons Foundation</p></div><div><p class="pubdate">2004 - 2019</p></div></div><hr></div><div class="refentry" title="SCONS"><a name="scons1"></a><div class="titlepage"></div><div class="refnamediv"><a name="name"></a><h2>Name</h2><p>scons — a software construction tool</p></div><div class="refsynopsisdiv" title="Synopsis"><a name="synopsis"></a><h2>Synopsis</h2><div class="cmdsynopsis"><p><code class="command">scons</code> [<em class="replaceable"><code>options</code></em>...] [<em class="replaceable"><code>name=val</code></em>...] [<em class="replaceable"><code>targets</code></em>...]</p></div></div><div class="refsect1" title="DESCRIPTION"><a name="description"></a><h2>DESCRIPTION</h2><p>The
|
|
<span class="command"><strong>scons</strong></span>
|
|
utility builds software (or other files) by determining which
|
|
component pieces must be rebuilt and executing the necessary commands to
|
|
rebuild them.</p><p>By default,
|
|
<span class="command"><strong>scons</strong></span>
|
|
searches for a file named
|
|
<span class="emphasis"><em>SConstruct</em></span>,
|
|
<span class="emphasis"><em>Sconstruct</em></span>,
|
|
<span class="emphasis"><em>sconstruct</em></span>,
|
|
<span class="emphasis"><em>SConstruct.py</em></span>
|
|
<span class="emphasis"><em>Sconstruct.py</em></span>
|
|
or
|
|
<span class="emphasis"><em>sconstruct.py</em></span>
|
|
(in that order) in the current directory and reads its
|
|
configuration from the first file found.
|
|
An alternate file name may be
|
|
specified via the
|
|
<code class="option">-f</code>
|
|
option.</p><p>The
|
|
<span class="emphasis"><em>SConstruct</em></span>
|
|
file can specify subsidiary
|
|
configuration files using the
|
|
<span class="bold"><strong>SConscript</strong></span>()
|
|
function.
|
|
By convention,
|
|
these subsidiary files are named
|
|
<span class="emphasis"><em>SConscript</em></span>,
|
|
although any name may be used.
|
|
(Because of this naming convention,
|
|
the term "SConscript files"
|
|
is sometimes used to refer
|
|
generically to all
|
|
<span class="command"><strong>scons</strong></span>
|
|
configuration files,
|
|
regardless of actual file name.)</p><p>The configuration files
|
|
specify the target files to be built, and
|
|
(optionally) the rules to build those targets. Reasonable default
|
|
rules exist for building common software components (executable
|
|
programs, object files, libraries), so that for most software
|
|
projects, only the target and input files need be specified.</p><p>Before reading the
|
|
<span class="emphasis"><em>SConstruct</em></span>
|
|
file,
|
|
<span class="command"><strong>scons</strong></span>
|
|
looks for a directory named
|
|
<span class="emphasis"><em>site_scons</em></span>
|
|
in various system directories (see below) and the directory containing the
|
|
<span class="emphasis"><em>SConstruct</em></span>
|
|
file; for each of those dirs which exists,
|
|
<span class="emphasis"><em>site_scons</em></span>
|
|
is prepended to sys.path,
|
|
the file
|
|
<span class="emphasis"><em>site_scons/site_init.py</em></span>,
|
|
is evaluated if it exists,
|
|
and the directory
|
|
<span class="emphasis"><em>site_scons/site_tools</em></span>
|
|
is prepended to the default toolpath if it exists.
|
|
See the
|
|
<code class="option">--no-site-dir</code>
|
|
and
|
|
<code class="option">--site-dir</code>
|
|
options for more details.</p><p><span class="command"><strong>scons</strong></span>
|
|
reads and executes the SConscript files as Python scripts,
|
|
so you may use normal Python scripting capabilities
|
|
(such as flow control, data manipulation, and imported Python libraries)
|
|
to handle complicated build situations.
|
|
<span class="command"><strong>scons</strong></span>,
|
|
however, reads and executes all of the SConscript files
|
|
<span class="emphasis"><em>before</em></span>
|
|
it begins building any targets.
|
|
To make this obvious,
|
|
<span class="command"><strong>scons</strong></span>
|
|
prints the following messages about what it is doing:</p><pre class="literallayout">
|
|
$ scons foo.out
|
|
scons: Reading SConscript files ...
|
|
scons: done reading SConscript files.
|
|
scons: Building targets ...
|
|
cp foo.in foo.out
|
|
scons: done building targets.
|
|
$
|
|
</pre><p>The status messages
|
|
(everything except the line that reads "cp foo.in foo.out")
|
|
may be suppressed using the
|
|
<code class="option">-Q</code>
|
|
option.</p><p><span class="command"><strong>scons</strong></span>
|
|
does not automatically propagate
|
|
the external environment used to execute
|
|
<span class="command"><strong>scons</strong></span>
|
|
to the commands used to build target files.
|
|
This is so that builds will be guaranteed
|
|
repeatable regardless of the environment
|
|
variables set at the time
|
|
<span class="command"><strong>scons</strong></span>
|
|
is invoked.
|
|
This also means that if the compiler or other commands
|
|
that you want to use to build your target files
|
|
are not in standard system locations,
|
|
<span class="command"><strong>scons</strong></span>
|
|
will not find them unless
|
|
you explicitly set the PATH
|
|
to include those locations.
|
|
Whenever you create an
|
|
<span class="command"><strong>scons</strong></span>
|
|
construction environment,
|
|
you can propagate the value of PATH
|
|
from your external environment as follows:</p><pre class="literallayout">
|
|
import os
|
|
env = Environment(ENV = {'PATH' : os.environ['PATH']})
|
|
</pre><p>Similarly, if the commands use external environment variables
|
|
like $PATH, $HOME, $JAVA_HOME, $LANG, $SHELL, $TERM, etc.,
|
|
these variables can also be explicitly propagated:</p><pre class="literallayout">
|
|
import os
|
|
env = Environment(ENV = {'PATH' : os.environ['PATH'],
|
|
'HOME' : os.environ['HOME']})
|
|
</pre><p>Or you may explicitly propagate the invoking user's
|
|
complete external environment:</p><pre class="literallayout">
|
|
import os
|
|
env = Environment(ENV = os.environ)
|
|
</pre><p>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.</p><p><span class="command"><strong>scons</strong></span>
|
|
can scan known input files automatically for dependency
|
|
information (for example, #include statements
|
|
in C or C++ files) and will rebuild dependent files appropriately
|
|
whenever any "included" input file changes.
|
|
<span class="command"><strong>scons</strong></span>
|
|
supports the
|
|
ability to define new scanners for unknown input file types.</p><p><span class="command"><strong>scons</strong></span>
|
|
knows how to fetch files automatically from
|
|
SCCS or RCS subdirectories
|
|
using SCCS, RCS or BitKeeper.</p><p><span class="command"><strong>scons</strong></span>
|
|
is normally executed in a top-level directory containing a
|
|
<span class="emphasis"><em>SConstruct</em></span>
|
|
file, optionally specifying
|
|
as command-line arguments
|
|
the target file or files to be built.</p><p>By default, the command</p><pre class="literallayout">
|
|
scons
|
|
</pre><p>will build all target files in or below the current directory.
|
|
Explicit default targets
|
|
(to be built when no targets are specified on the command line)
|
|
may be defined the SConscript file(s)
|
|
using the
|
|
<span class="bold"><strong>Default()</strong></span>
|
|
function, described below.</p><p>Even when
|
|
<span class="bold"><strong>Default()</strong></span>
|
|
targets are specified in the SConscript file(s),
|
|
all target files in or below the current directory
|
|
may be built by explicitly specifying
|
|
the current directory (.)
|
|
as a command-line target:</p><pre class="literallayout">
|
|
scons .
|
|
</pre><p>Building all target files,
|
|
including any files outside of the current directory,
|
|
may be specified by supplying a command-line target
|
|
of the root directory (on POSIX systems):</p><pre class="literallayout">
|
|
scons /
|
|
</pre><p>or the path name(s) of the volume(s) in which all the targets
|
|
should be built (on Windows systems):</p><pre class="literallayout">
|
|
scons C:\ D:\
|
|
</pre><p>To build only specific targets,
|
|
supply them as command-line arguments:</p><pre class="literallayout">
|
|
scons foo bar
|
|
</pre><p>in which case only the specified targets will be built
|
|
(along with any derived files on which they depend).</p><p>Specifying "cleanup" targets in SConscript files is not usually necessary.
|
|
The
|
|
<code class="option">-c</code>
|
|
flag removes all files
|
|
necessary to build the specified target:</p><pre class="literallayout">
|
|
scons -c .
|
|
</pre><p>to remove all target files, or:</p><pre class="literallayout">
|
|
scons -c build export
|
|
</pre><p>to remove target files under build and export.
|
|
Additional files or directories to remove can be specified using the
|
|
<span class="bold"><strong>Clean()</strong></span>
|
|
function.
|
|
Conversely, targets that would normally be removed by the
|
|
<code class="option">-c</code>
|
|
invocation
|
|
can be prevented from being removed by using the
|
|
<span class="bold"><strong>NoClean</strong></span>()
|
|
function.</p><p>A subset of a hierarchical tree may be built by
|
|
remaining at the top-level directory (where the
|
|
<span class="emphasis"><em>SConstruct</em></span>
|
|
file lives) and specifying the subdirectory as the target to be
|
|
built:</p><pre class="literallayout">
|
|
scons src/subdir
|
|
</pre><p>or by changing directory and invoking scons with the
|
|
<code class="option">-u</code>
|
|
option, which traverses up the directory
|
|
hierarchy until it finds the
|
|
<span class="emphasis"><em>SConstruct</em></span>
|
|
file, and then builds
|
|
targets relatively to the current subdirectory:</p><pre class="literallayout">
|
|
cd src/subdir
|
|
scons -u .
|
|
</pre><p><span class="command"><strong>scons</strong></span>
|
|
supports building multiple targets in parallel via a
|
|
<code class="option">-j</code>
|
|
option that takes, as its argument, the number
|
|
of simultaneous tasks that may be spawned:</p><pre class="literallayout">
|
|
scons -j 4
|
|
</pre><p>builds four targets in parallel, for example.</p><p><span class="command"><strong>scons</strong></span>
|
|
can maintain a cache of target (derived) files that can
|
|
be shared between multiple builds. When caching is enabled in a
|
|
SConscript file, any target files built by
|
|
<span class="command"><strong>scons</strong></span>
|
|
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
|
|
<code class="option">--cache-force</code>,
|
|
<code class="option">--cache-disable</code>,
|
|
<code class="option">--cache-readonly</code>,
|
|
and
|
|
<code class="option">--cache-show</code>
|
|
command-line options. The
|
|
<code class="option">--random</code>
|
|
option is useful to prevent multiple builds
|
|
from trying to update the cache simultaneously.</p><p>Values of variables to be passed to the SConscript file(s)
|
|
may be specified on the command line:</p><pre class="literallayout">
|
|
scons debug=1 .
|
|
</pre><p>These variables are available in SConscript files
|
|
through the ARGUMENTS dictionary,
|
|
and can be used in the SConscript file(s) to modify
|
|
the build in any way:</p><pre class="literallayout">
|
|
if ARGUMENTS.get('debug', 0):
|
|
env = Environment(CCFLAGS = '-g')
|
|
else:
|
|
env = Environment()
|
|
</pre><p>The command-line variable arguments are also available
|
|
in the ARGLIST list,
|
|
indexed by their order on the command line.
|
|
This allows you to process them in order rather than by name,
|
|
if necessary.
|
|
ARGLIST[0] returns a tuple
|
|
containing (argname, argvalue).
|
|
A Python exception is thrown if you
|
|
try to access a list member that
|
|
does not exist.</p><p><span class="command"><strong>scons</strong></span>
|
|
requires either Python 2.7 or Python 3.5 or higher.
|
|
There should be no other dependencies or requirements to run
|
|
<span class="bold"><strong>scons.</strong></span></p><p>By default,
|
|
<span class="command"><strong>scons</strong></span>
|
|
knows how to search for available programming tools
|
|
on various systems.
|
|
On Windows systems,
|
|
<span class="command"><strong>scons</strong></span>
|
|
searches in order for the
|
|
Microsoft Visual C++ tools,
|
|
the MinGW tool chain,
|
|
the Intel compiler tools,
|
|
and the PharLap ETS compiler.
|
|
On OS/2 systems,
|
|
<span class="command"><strong>scons</strong></span>
|
|
searches in order for the
|
|
OS/2 compiler,
|
|
the GCC tool chain,
|
|
and the Microsoft Visual C++ tools,
|
|
On SGI IRIX, IBM AIX, Hewlett Packard HP-UX, and Sun Solaris systems,
|
|
<span class="command"><strong>scons</strong></span>
|
|
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,
|
|
<span class="command"><strong>scons</strong></span>
|
|
searches in order
|
|
for the GCC tool chain,
|
|
the Microsoft Visual C++ tools,
|
|
and the Intel compiler tools.
|
|
You may, of course, override these default values
|
|
by appropriate configuration of
|
|
Environment construction variables.</p></div><div class="refsect1" title="OPTIONS"><a name="options"></a><h2>OPTIONS</h2><p>In general,
|
|
<span class="command"><strong>scons</strong></span>
|
|
supports the same command-line options as GNU
|
|
<span class="bold"><strong>make</strong></span>,
|
|
and many of those supported by
|
|
<span class="bold"><strong>cons</strong></span>.</p><div class="variablelist"><dl><dt><span class="term">-b</span></dt><dd><p>Ignored for compatibility with non-GNU versions of
|
|
<span class="bold"><strong>make.</strong></span></p></dd><dt><span class="term">-c, --clean, --remove</span></dt><dd><p>Clean up by removing all target files for which a construction
|
|
command is specified.
|
|
Also remove any files or directories associated to the construction command
|
|
using the
|
|
<span class="bold"><strong>Clean</strong></span>()
|
|
function.
|
|
Will not remove any targets specified by the
|
|
<span class="bold"><strong>NoClean</strong></span>()
|
|
function.</p></dd><dt><span class="term">--cache-debug=<span class="emphasis"><em>file</em></span></span></dt><dd><p>Print debug information about the
|
|
<span class="bold"><strong>CacheDir</strong></span>()
|
|
derived-file caching
|
|
to the specified
|
|
<span class="emphasis"><em>file</em></span>.
|
|
If
|
|
<span class="emphasis"><em>file</em></span>
|
|
is
|
|
<span class="bold"><strong>-</strong></span>
|
|
(a hyphen),
|
|
the debug information are printed to the standard output.
|
|
The printed messages describe what signature file names are
|
|
being looked for in, retrieved from, or written to the
|
|
<span class="bold"><strong>CacheDir</strong></span>()
|
|
directory tree.</p></dd><dt><span class="term">--cache-disable, --no-cache</span></dt><dd><p>Disable the derived-file caching specified by
|
|
<span class="bold"><strong>CacheDir</strong></span>().
|
|
<span class="command"><strong>scons</strong></span>
|
|
will neither retrieve files from the cache
|
|
nor copy files to the cache.</p></dd><dt><span class="term">--cache-force, --cache-populate</span></dt><dd><p>When using
|
|
<span class="bold"><strong>CacheDir</strong></span>(),
|
|
populate a cache by copying any already-existing, up-to-date
|
|
derived files to the cache,
|
|
in addition to files built by this invocation.
|
|
This is useful to populate a new cache with
|
|
all the current derived files,
|
|
or to add to the cache any derived files
|
|
recently built with caching disabled via the
|
|
<code class="option">--cache-disable</code>
|
|
option.</p></dd><dt><span class="term">--cache-readonly</span></dt><dd><p>Use the cache (if enabled) for reading, but do not not update the
|
|
cache with changed files.
|
|
</p></dd><dt><span class="term">--cache-show</span></dt><dd><p>When using
|
|
<span class="bold"><strong>CacheDir</strong></span>()
|
|
and retrieving a derived file from the cache,
|
|
show the command
|
|
that would have been executed to build the file,
|
|
instead of the usual report,
|
|
"Retrieved `file' from cache."
|
|
This will produce consistent output for build logs,
|
|
regardless of whether a target
|
|
file was rebuilt or retrieved from the cache.</p></dd><dt><span class="term">--config=<span class="emphasis"><em>mode</em></span></span></dt><dd><p>This specifies how the
|
|
<span class="bold"><strong>Configure</strong></span>
|
|
call should use or generate the
|
|
results of configuration tests.
|
|
The option should be specified from
|
|
among the following choices:</p></dd><dt><span class="term">--config=auto</span></dt><dd><p>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.</p></dd><dt><span class="term">--config=force</span></dt><dd><p>If this option is specified,
|
|
all configuration tests will be re-run
|
|
regardless of whether the
|
|
cached results are out of date.
|
|
This can be used to explicitly
|
|
force the configuration tests to be updated
|
|
in response to an otherwise unconfigured change
|
|
in a system header file or compiler.</p></dd><dt><span class="term">--config=cache</span></dt><dd><p>If this option is specified,
|
|
no configuration tests will be rerun
|
|
and all results will be taken from cache.
|
|
Note that scons will still consider it an error
|
|
if --config=cache is specified
|
|
and a necessary test does not
|
|
yet have any results in the cache.</p></dd><dt><span class="term">-C<span class="emphasis"><em> directory</em></span>, --directory=<span class="emphasis"><em>directory</em></span></span></dt><dd><p>Change to the specified
|
|
<span class="emphasis"><em>directory</em></span>
|
|
before searching for the
|
|
<span class="emphasis"><em>SConstruct</em></span>,
|
|
<span class="emphasis"><em>Sconstruct</em></span>,
|
|
<span class="emphasis"><em>sconstruct</em></span>,
|
|
<span class="emphasis"><em>SConstruct.py</em></span>
|
|
<span class="emphasis"><em>Sconstruct.py</em></span>
|
|
or
|
|
<span class="emphasis"><em>sconstruct.py</em></span>
|
|
file, or doing anything
|
|
else. Multiple
|
|
<code class="option">-C</code>
|
|
options are interpreted
|
|
relative to the previous one, and the right-most
|
|
<code class="option">-C</code>
|
|
option wins. (This option is nearly
|
|
equivalent to
|
|
<code class="option">-f directory/SConstruct</code>,
|
|
except that it will search for
|
|
<span class="emphasis"><em>SConstruct</em></span>,
|
|
<span class="emphasis"><em>Sconstruct</em></span>,
|
|
<span class="emphasis"><em>sconstruct</em></span>,
|
|
<span class="emphasis"><em>SConstruct.py</em></span>
|
|
<span class="emphasis"><em>Sconstruct.py</em></span>
|
|
or
|
|
<span class="emphasis"><em>sconstruct.py</em></span>
|
|
in the specified directory.)</p></dd><dt><span class="term">-D</span></dt><dd><p>Works exactly the same way as the
|
|
<code class="option">-u</code>
|
|
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.</p></dd><dt><span class="term">--debug=<span class="emphasis"><em>type</em></span></span></dt><dd><p>Debug the build process.
|
|
<span class="emphasis"><em>type[,type...]</em></span>
|
|
specifies what type of debugging. Multiple types may be specified,
|
|
separated by commas. The following types are valid:</p></dd><dt><span class="term">--debug=count</span></dt><dd><p>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
|
|
<code class="option">-O</code>
|
|
(optimized) option
|
|
or when the SCons modules
|
|
have been compiled with optimization
|
|
(that is, when executing from
|
|
<span class="bold"><strong>*.pyo</strong></span>
|
|
files).</p></dd><dt><span class="term">--debug=duplicate</span></dt><dd><p>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.</p></dd><dt><span class="term">--debug=dtree</span></dt><dd><p>A synonym for the newer
|
|
<code class="option">--tree=derived</code>
|
|
option.
|
|
This will be deprecated in some future release
|
|
and ultimately removed.</p></dd><dt><span class="term">--debug=explain</span></dt><dd><p>Print an explanation of precisely why
|
|
<span class="command"><strong>scons</strong></span>
|
|
is deciding to (re-)build any targets.
|
|
(Note: this does not print anything
|
|
for targets that are
|
|
<span class="emphasis"><em>not</em></span>
|
|
rebuilt.)</p></dd><dt><span class="term">--debug=findlibs</span></dt><dd><p>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.</p></dd><dt><span class="term">--debug=includes</span></dt><dd><p>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:</p><pre class="literallayout">
|
|
$ scons --debug=includes foo.o
|
|
</pre></dd><dt><span class="term">--debug=memoizer</span></dt><dd><p>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.</p></dd><dt><span class="term">--debug=memory</span></dt><dd><p>Prints how much memory SCons uses
|
|
before and after reading the SConscript files
|
|
and before and after building targets.</p></dd><dt><span class="term">--debug=nomemoizer</span></dt><dd><p>A deprecated option preserved for backwards compatibility.</p></dd><dt><span class="term">--debug=objects</span></dt><dd><p>Prints a list of the various objects
|
|
of the various classes used internally by SCons.</p></dd><dt><span class="term">--debug=pdb</span></dt><dd><p>Re-run SCons under the control of the
|
|
pdb
|
|
Python debugger.</p></dd><dt><span class="term">--debug=prepare</span></dt><dd><p>Print a line each time any target (internal or external)
|
|
is prepared for building.
|
|
<span class="command"><strong>scons</strong></span>
|
|
prints this for each target it considers, even if that
|
|
target is up to date (see also --debug=explain).
|
|
This can help debug problems with targets that aren't being
|
|
built; it shows whether
|
|
<span class="command"><strong>scons</strong></span>
|
|
is at least considering them or not.</p></dd><dt><span class="term">--debug=presub</span></dt><dd><p>Print the raw command line used to build each target
|
|
before the construction environment variables are substituted.
|
|
Also shows which targets are being built by this command.
|
|
Output looks something like this:</p><pre class="literallayout">
|
|
$ scons --debug=presub
|
|
Building myprog.o with action(s):
|
|
$SHCC $SHCFLAGS $SHCCFLAGS $CPPFLAGS $_CPPINCFLAGS -c -o $TARGET $SOURCES
|
|
...
|
|
</pre></dd><dt><span class="term">--debug=stacktrace</span></dt><dd><p>Prints an internal Python stack trace
|
|
when encountering an otherwise unexplained error.</p></dd><dt><span class="term">--debug=stree</span></dt><dd><p>A synonym for the newer
|
|
<code class="option">--tree=all,status</code>
|
|
option.
|
|
This will be deprecated in some future release
|
|
and ultimately removed.</p></dd><dt><span class="term">--debug=time</span></dt><dd><p>Prints various time profiling information:</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>The time spent executing each individual build command</p></li><li class="listitem"><p>The total build time (time SCons ran from beginning to end)</p></li><li class="listitem"><p>The total time spent reading and executing SConscript files</p></li><li class="listitem"><p>The total time spent SCons itself spend running
|
|
(that is, not counting reading and executing SConscript files)</p></li><li class="listitem"><p>The total time spent executing all build commands</p></li><li class="listitem"><p>The elapsed wall-clock time spent executing those build commands</p></li><li class="listitem"><p>The time spent processing each file passed to the <span class="emphasis"><em>SConscript()</em></span> function</p></li></ul></div><p>
|
|
(When
|
|
<span class="command"><strong>scons</strong></span>
|
|
is executed without the
|
|
<code class="option">-j</code>
|
|
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
|
|
<span class="command"><strong>scons</strong></span>
|
|
is executed
|
|
<span class="emphasis"><em>with</em></span>
|
|
the
|
|
<code class="option">-j</code>
|
|
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.)
|
|
</p></dd><dt><span class="term">--debug=tree</span></dt><dd><p>A synonym for the newer
|
|
<code class="option">--tree=all</code>
|
|
option.
|
|
This will be deprecated in some future release
|
|
and ultimately removed.</p></dd><dt><span class="term">--diskcheck=<span class="emphasis"><em>types</em></span></span></dt><dd><p>Enable specific checks for
|
|
whether or not there is a file on disk
|
|
where the SCons configuration expects a directory
|
|
(or vice versa),
|
|
and whether or not RCS or SCCS sources exist
|
|
when searching for source and include files.
|
|
The
|
|
<span class="emphasis"><em>types</em></span>
|
|
argument can be set to:
|
|
<span class="bold"><strong>all</strong></span>,
|
|
to enable all checks explicitly
|
|
(the default behavior);
|
|
<span class="bold"><strong>none</strong></span>,
|
|
to disable all such checks;
|
|
<span class="bold"><strong>match</strong></span>,
|
|
to check that files and directories on disk
|
|
match SCons' expected configuration;
|
|
<span class="bold"><strong>rcs</strong></span>,
|
|
to check for the existence of an RCS source
|
|
for any missing source or include files;
|
|
<span class="bold"><strong>sccs</strong></span>,
|
|
to check for the existence of an SCCS source
|
|
for any missing source or include files.
|
|
Multiple checks can be specified separated by commas;
|
|
for example,
|
|
<code class="option">--diskcheck=sccs,rcs</code>
|
|
would still check for SCCS and RCS sources,
|
|
but disable the check for on-disk matches of files and directories.
|
|
Disabling some or all of these checks
|
|
can provide a performance boost for large configurations,
|
|
or when the configuration will check for files and/or directories
|
|
across networked or shared file systems,
|
|
at the slight increased risk of an incorrect build
|
|
or of not handling errors gracefully
|
|
(if include files really should be
|
|
found in SCCS or RCS, for example,
|
|
or if a file really does exist
|
|
where the SCons configuration expects a directory).</p></dd><dt><span class="term">--duplicate=<span class="emphasis"><em>ORDER</em></span></span></dt><dd><p>There are three ways to duplicate files in a build tree: hard links,
|
|
soft (symbolic) links and copies. The default behaviour of SCons is to
|
|
prefer hard links to soft links to copies. You can specify different
|
|
behaviours with this option.
|
|
<span class="emphasis"><em>ORDER</em></span>
|
|
must be one of
|
|
<span class="emphasis"><em>hard-soft-copy</em></span>
|
|
(the default),
|
|
<span class="emphasis"><em>soft-hard-copy</em></span>,
|
|
<span class="emphasis"><em>hard-copy</em></span>,
|
|
<span class="emphasis"><em>soft-copy</em></span>
|
|
or
|
|
<span class="emphasis"><em>copy</em></span>.
|
|
SCons will attempt to duplicate files using
|
|
the mechanisms in the specified order.</p></dd><dt><span class="term">--enable-virtualenv</span></dt><dd><p>Import virtualenv-related variables to SCons.</p></dd><dt><span class="term">-f<span class="emphasis"><em> file</em></span>, --file=<span class="emphasis"><em>file</em></span>, --makefile=<span class="emphasis"><em>file</em></span>, --sconstruct=<span class="emphasis"><em>file</em></span></span></dt><dd><p>Use
|
|
<span class="emphasis"><em>file</em></span>
|
|
as the initial SConscript file.
|
|
Multiple
|
|
<code class="option">-f</code>
|
|
options may be specified,
|
|
in which case
|
|
<span class="command"><strong>scons</strong></span>
|
|
will read all of the specified files.</p></dd><dt><span class="term">-h, --help</span></dt><dd><p>Print a local help message for this build, if one is defined in
|
|
the SConscript file(s), plus a line that describes the
|
|
<code class="option">-H</code>
|
|
option for command-line option help. If no local help message
|
|
is defined, prints the standard help message about command-line
|
|
options. Exits after displaying the appropriate message.</p></dd><dt><span class="term">-H, --help-options</span></dt><dd><p>Print the standard help message about command-line options and
|
|
exit.</p></dd><dt><span class="term">-i, --ignore-errors</span></dt><dd><p>Ignore all errors from commands executed to rebuild files.</p></dd><dt><span class="term">-I<span class="emphasis"><em> directory</em></span>, --include-dir=<span class="emphasis"><em>directory</em></span></span></dt><dd><p>Specifies a
|
|
<span class="emphasis"><em>directory</em></span>
|
|
to search for
|
|
imported Python modules. If several
|
|
<code class="option">-I</code>
|
|
options
|
|
are used, the directories are searched in the order specified.</p></dd><dt><span class="term">--ignore-virtualenv</span></dt><dd><p>Suppress importing virtualenv-related variables to SCons.</p></dd><dt><span class="term">--implicit-cache</span></dt><dd><p>Cache implicit dependencies.
|
|
This causes
|
|
<span class="command"><strong>scons</strong></span>
|
|
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:</p></dd></dl></div><p><span class="command"><strong>scons</strong></span>
|
|
will not detect changes to implicit dependency search paths
|
|
(e.g.
|
|
<span class="bold"><strong>CPPPATH</strong></span>, <span class="bold"><strong>LIBPATH</strong></span>)
|
|
that would ordinarily
|
|
cause different versions of same-named files to be used.</p><p><span class="command"><strong>scons</strong></span>
|
|
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.
|
|
<span class="bold"><strong>CPPPATH</strong></span>, <span class="bold"><strong>LIBPATH</strong></span>)
|
|
than a current implicit dependency with the same name.</p><div class="variablelist"><dl><dt><span class="term">--implicit-deps-changed</span></dt><dd><p>Forces SCons to ignore the cached implicit dependencies. This causes the
|
|
implicit dependencies to be rescanned and recached. This implies
|
|
<code class="option">--implicit-cache</code>.</p></dd><dt><span class="term">--implicit-deps-unchanged</span></dt><dd><p>Force SCons to ignore changes in the implicit dependencies.
|
|
This causes cached implicit dependencies to always be used.
|
|
This implies
|
|
<code class="option">--implicit-cache</code>.</p></dd><dt><span class="term">--interactive</span></dt><dd><p>Starts SCons in interactive mode.
|
|
The SConscript files are read once and a
|
|
<span class="bold"><strong>scons>>></strong></span>
|
|
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.</p><p>SCons interactive mode supports the following commands:</p><div class="blockquote"><blockquote class="blockquote"><div class="variablelist"><dl><dt><span class="term"><span class="bold"><strong>build</strong></span><span class="emphasis"><em>[OPTIONS] [TARGETS] ...</em></span></span></dt><dd><p>Builds the specified
|
|
<span class="emphasis"><em>TARGETS</em></span>
|
|
(and their dependencies)
|
|
with the specified
|
|
SCons command-line
|
|
<span class="emphasis"><em>OPTIONS</em></span>.
|
|
<span class="bold"><strong>b</strong></span>
|
|
and
|
|
<span class="command"><strong>scons</strong></span>
|
|
are synonyms.</p><p>The following SCons command-line options affect the
|
|
<span class="bold"><strong>build</strong></span>
|
|
command:</p><pre class="literallayout">
|
|
--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
|
|
</pre></dd></dl></div><p>Any other SCons command-line options that are specified
|
|
do not cause errors
|
|
but have no effect on the
|
|
<span class="bold"><strong>build</strong></span>
|
|
command
|
|
(mainly because they affect how the SConscript files are read,
|
|
which only happens once at the beginning of interactive mode).</p><div class="variablelist"><dl><dt><span class="term"><span class="bold"><strong>clean</strong></span><span class="emphasis"><em>[OPTIONS] [TARGETS] ...</em></span></span></dt><dd><p>Cleans the specified
|
|
<span class="emphasis"><em>TARGETS</em></span>
|
|
(and their dependencies)
|
|
with the specified options.
|
|
<span class="bold"><strong>c</strong></span>
|
|
is a synonym.
|
|
This command is itself a synonym for
|
|
<strong class="userinput"><code>build --clean</code></strong></p></dd><dt><span class="term"><span class="bold"><strong>exit</strong></span></span></dt><dd><p>Exits SCons interactive mode.
|
|
You can also exit by terminating input
|
|
(CTRL+D on UNIX or Linux systems,
|
|
CTRL+Z on Windows systems).</p></dd><dt><span class="term"><span class="bold"><strong>help</strong></span><span class="emphasis"><em>[COMMAND]</em></span></span></dt><dd><p>Provides a help message about
|
|
the commands available in SCons interactive mode.
|
|
If
|
|
<span class="emphasis"><em>COMMAND</em></span>
|
|
is specified,
|
|
<span class="bold"><strong>h</strong></span>
|
|
and
|
|
<span class="bold"><strong>?</strong></span>
|
|
are synonyms.</p></dd><dt><span class="term"><span class="bold"><strong>shell</strong></span><span class="emphasis"><em>[COMMANDLINE]</em></span></span></dt><dd><p>Executes the specified
|
|
<span class="emphasis"><em>COMMANDLINE</em></span>
|
|
in a subshell.
|
|
If no
|
|
<span class="emphasis"><em>COMMANDLINE</em></span>
|
|
is specified,
|
|
executes the interactive command interpreter
|
|
specified in the
|
|
<code class="envar">SHELL</code>
|
|
environment variable
|
|
(on UNIX and Linux systems)
|
|
or the
|
|
<span class="bold"><strong>COMSPEC</strong></span>
|
|
environment variable
|
|
(on Windows systems).
|
|
<span class="bold"><strong>sh</strong></span>
|
|
and
|
|
<span class="bold"><strong>!</strong></span>
|
|
are synonyms.</p></dd><dt><span class="term"><span class="bold"><strong>version</strong></span></span></dt><dd><p>Prints SCons version information.</p></dd></dl></div></blockquote></div></dd></dl></div><p>An empty line repeats the last typed command.
|
|
Command-line editing can be used if the
|
|
<span class="bold"><strong>readline</strong></span>
|
|
module is available.</p><pre class="literallayout">
|
|
$ scons --interactive
|
|
scons: Reading SConscript files ...
|
|
scons: done reading SConscript files.
|
|
scons>>> build -n prog
|
|
scons>>> exit
|
|
</pre><div class="variablelist"><dl><dt><span class="term">-j<span class="emphasis"><em> N</em></span>, --jobs=<span class="emphasis"><em>N</em></span></span></dt><dd><p>Specifies the number of jobs (commands) to run simultaneously.
|
|
If there is more than one
|
|
<code class="option">-j</code>
|
|
option, the last one is effective.</p></dd><dt><span class="term">-k, --keep-going</span></dt><dd><p>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.</p></dd><dt><span class="term">-m</span></dt><dd><p>Ignored for compatibility with non-GNU versions of
|
|
<span class="bold"><strong>make</strong></span>.</p></dd><dt><span class="term">--max-drift=<span class="emphasis"><em>SECONDS</em></span></span></dt><dd><p>Set the maximum expected drift in the modification time of files to
|
|
<span class="emphasis"><em>SECONDS</em></span>.
|
|
This value determines how long a file must be unmodified
|
|
before its cached content signature
|
|
will be used instead of
|
|
calculating a new content signature (MD5 checksum)
|
|
of the file's contents.
|
|
The default value is 2 days, which means a file must have a
|
|
modification time of at least two days ago in order to have its
|
|
cached content signature used.
|
|
A negative value means to never cache the content
|
|
signature and to ignore the cached value if there already is one. A value
|
|
of 0 means to always use the cached signature,
|
|
no matter how old the file is.</p></dd><dt><span class="term">--md5-chunksize=<span class="emphasis"><em>KILOBYTES</em></span></span></dt><dd><p>Set the block size used to compute MD5 signatures to
|
|
<span class="emphasis"><em>KILOBYTES</em></span>.
|
|
This value determines the size of the chunks which are read in at once when
|
|
computing MD5 signatures. Files below that size are fully stored in memory
|
|
before performing the signature computation while bigger files are read in
|
|
block-by-block. A huge block-size leads to high memory consumption while a very
|
|
small block-size slows down the build considerably.</p><p>The default value is to use a chunk size of 64 kilobytes, which should
|
|
be appropriate for most uses.</p></dd><dt><span class="term">-n, --just-print, --dry-run, --recon</span></dt><dd><p>No execute. Print the commands that would be executed to build
|
|
any out-of-date target files, but do not execute the commands.</p></dd><dt><span class="term">--no-site-dir</span></dt><dd><p>Prevents the automatic addition of the standard
|
|
<span class="emphasis"><em>site_scons</em></span>
|
|
dirs to
|
|
<span class="emphasis"><em>sys.path</em></span>.
|
|
Also prevents loading the
|
|
<span class="emphasis"><em>site_scons/site_init.py</em></span>
|
|
modules if they exist, and prevents adding their
|
|
<span class="emphasis"><em>site_scons/site_tools</em></span>
|
|
dirs to the toolpath.</p></dd><dt><span class="term">--profile=<span class="emphasis"><em>file</em></span></span></dt><dd><p>Run SCons under the Python profiler
|
|
and save the results in the specified
|
|
<span class="emphasis"><em>file</em></span>.
|
|
The results may be analyzed using the Python
|
|
pstats module.</p></dd><dt><span class="term">-q, --question</span></dt><dd><p>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.</p></dd><dt><span class="term">-Q</span></dt><dd><p>Quiets SCons status messages about
|
|
reading SConscript files,
|
|
building targets
|
|
and entering directories.
|
|
Commands that are executed
|
|
to rebuild target files are still printed.</p></dd><dt><span class="term">--random</span></dt><dd><p>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.</p></dd><dt><span class="term">-s, --silent, --quiet</span></dt><dd><p>Silent. Do not print commands that are executed to rebuild
|
|
target files.
|
|
Also suppresses SCons status messages.</p></dd><dt><span class="term">-S, --no-keep-going, --stop</span></dt><dd><p>Ignored for compatibility with GNU
|
|
<span class="bold"><strong>make</strong></span>.</p></dd><dt><span class="term">--site-dir=<span class="emphasis"><em>dir</em></span></span></dt><dd><p>Uses the named dir as the site dir rather than the default
|
|
<span class="emphasis"><em>site_scons</em></span>
|
|
dirs. This dir will get prepended to
|
|
<span class="emphasis"><em>sys.path</em></span>,
|
|
the module
|
|
<span class="emphasis"><em>dir</em></span>/site_init.py
|
|
will get loaded if it exists, and
|
|
<span class="emphasis"><em>dir</em></span>/site_tools
|
|
will get added to the default toolpath.</p><p>The default set of
|
|
<span class="emphasis"><em>site_scons</em></span>
|
|
dirs used when
|
|
<code class="option">--site-dir</code>
|
|
is not specified depends on the system platform, as follows. Note
|
|
that the directories are examined in the order given, from most
|
|
generic to most specific, so the last-executed site_init.py file is
|
|
the most specific one (which gives it the chance to override
|
|
everything else), and the dirs are prepended to the paths, again so
|
|
the last dir examined comes first in the resulting path.</p></dd></dl></div><div class="variablelist"><dl><dt><span class="term">Windows:</span></dt><dd><pre class="literallayout">
|
|
%ALLUSERSPROFILE/Application Data/scons/site_scons
|
|
%USERPROFILE%/Local Settings/Application Data/scons/site_scons
|
|
%APPDATA%/scons/site_scons
|
|
%HOME%/.scons/site_scons
|
|
./site_scons
|
|
</pre></dd><dt><span class="term">Mac OS X:</span></dt><dd><pre class="literallayout">
|
|
/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
|
|
</pre></dd><dt><span class="term">Solaris:</span></dt><dd><pre class="literallayout">
|
|
/opt/sfw/scons/site_scons
|
|
/usr/share/scons/site_scons
|
|
$HOME/.scons/site_scons
|
|
./site_scons
|
|
</pre></dd><dt><span class="term">Linux, HPUX, and other Posix-like systems:</span></dt><dd><pre class="literallayout">
|
|
/usr/share/scons/site_scons
|
|
$HOME/.scons/site_scons
|
|
./site_scons
|
|
</pre></dd></dl></div><div class="variablelist"><dl><dt><span class="term">--stack-size=<span class="emphasis"><em>KILOBYTES</em></span></span></dt><dd><p>Set the size stack used to run threads to
|
|
<span class="emphasis"><em>KILOBYTES</em></span>.
|
|
This value determines the stack size of the threads used to run jobs.
|
|
These are the threads that execute the actions of the builders for the
|
|
nodes that are out-of-date.
|
|
Note that this option has no effect unless the
|
|
<span class="bold"><strong>num_jobs</strong></span>
|
|
option, which corresponds to -j and --jobs, is larger than one. Using
|
|
a stack size that is too small may cause stack overflow errors. This
|
|
usually shows up as segmentation faults that cause scons to abort
|
|
before building anything. Using a stack size that is too large will
|
|
cause scons to use more memory than required and may slow down the entire
|
|
build process.</p><p>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.</p></dd><dt><span class="term">-t, --touch</span></dt><dd><p>Ignored for compatibility with GNU
|
|
<span class="bold"><strong>make</strong></span>.
|
|
(Touching a file to make it
|
|
appear up-to-date is unnecessary when using
|
|
<span class="command"><strong>scons</strong></span>.)</p></dd><dt><span class="term">--taskmastertrace=<span class="emphasis"><em>file</em></span></span></dt><dd><p>Prints trace information to the specified
|
|
<span class="emphasis"><em>file</em></span>
|
|
about how the internal Taskmaster object
|
|
evaluates and controls the order in which Nodes are built.
|
|
A file name of
|
|
<span class="bold"><strong>-</strong></span>
|
|
may be used to specify the standard output.</p></dd><dt><span class="term">-tree=<span class="emphasis"><em>options</em></span></span></dt><dd><p>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
|
|
<span class="emphasis"><em>options</em></span>
|
|
specified:</p></dd><dt><span class="term">--tree=all</span></dt><dd><p>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.</p></dd><dt><span class="term">--tree=derived</span></dt><dd><p>Restricts the tree output to only derived (target) files,
|
|
not source files.</p></dd><dt><span class="term">--tree=status</span></dt><dd><p>Prints status information for each displayed node.</p></dd><dt><span class="term">--tree=prune</span></dt><dd><p>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
|
|
<span class="bold"><strong>[square brackets]</strong></span>,
|
|
as an indication that the dependencies
|
|
for that node can be found by searching
|
|
for the relevant output higher up in the tree.</p></dd></dl></div><p>Multiple options may be specified,
|
|
separated by commas:</p><pre class="literallayout">
|
|
# Prints only derived files, with status information:
|
|
scons --tree=derived,status
|
|
|
|
# Prints all dependencies of target, with status information
|
|
# and pruning dependencies of already-visited Nodes:
|
|
scons --tree=all,prune,status target
|
|
</pre><div class="variablelist"><dl><dt><span class="term">-u, --up, --search-up</span></dt><dd><p>Walks up the directory structure until an
|
|
<span class="emphasis"><em>SConstruct ,</em></span>
|
|
<span class="emphasis"><em>Sconstruct ,</em></span>
|
|
<span class="emphasis"><em>sconstruct ,</em></span>
|
|
<span class="emphasis"><em>SConstruct.py</em></span>
|
|
<span class="emphasis"><em>Sconstruct.py</em></span>
|
|
or
|
|
<span class="emphasis"><em>sconstruct.py</em></span>
|
|
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.</p></dd><dt><span class="term">-U</span></dt><dd><p>Works exactly the same way as the
|
|
<code class="option">-u</code>
|
|
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.</p></dd><dt><span class="term">-v, --version</span></dt><dd><p>Print the
|
|
<span class="command"><strong>scons</strong></span>
|
|
version, copyright information,
|
|
list of authors, and any other relevant information.
|
|
Then exit.</p></dd><dt><span class="term">-w, --print-directory</span></dt><dd><p>Print a message containing the working directory before and
|
|
after other processing.</p></dd><dt><span class="term">--no-print-directory</span></dt><dd><p>Turn off -w, even if it was turned on implicitly.</p></dd><dt><span class="term">--warn=<span class="emphasis"><em>type</em></span>, --warn=no-<span class="emphasis"><em>type</em></span></span></dt><dd><p>Enable or disable warnings.
|
|
<span class="emphasis"><em>type</em></span>
|
|
specifies the type of warnings to be enabled or disabled:</p></dd><dt><span class="term">--warn=all, --warn=no-all</span></dt><dd><p>Enables or disables all warnings.</p></dd><dt><span class="term">--warn=cache-version, --warn=no-cache-version</span></dt><dd><p>Enables or disables warnings about the cache directory not using
|
|
the latest configuration information
|
|
<span class="bold"><strong>CacheDir</strong></span>().
|
|
These warnings are enabled by default.</p></dd><dt><span class="term">--warn=cache-write-error, --warn=no-cache-write-error</span></dt><dd><p>Enables or disables warnings about errors trying to
|
|
write a copy of a built file to a specified
|
|
<span class="bold"><strong>CacheDir</strong></span>().
|
|
These warnings are disabled by default.</p></dd><dt><span class="term">--warn=corrupt-sconsign, --warn=no-corrupt-sconsign</span></dt><dd><p>Enables or disables warnings about unfamiliar signature data in
|
|
<span class="markup">.sconsign</span>
|
|
files.
|
|
These warnings are enabled by default.</p></dd><dt><span class="term">--warn=dependency, --warn=no-dependency</span></dt><dd><p>Enables or disables warnings about dependencies.
|
|
These warnings are disabled by default.</p></dd><dt><span class="term">--warn=deprecated, --warn=no-deprecated</span></dt><dd><p>Enables or disables all warnings about use of
|
|
currently deprecated features.
|
|
These warnings are enabled by default.
|
|
Note that the
|
|
<code class="option">--warn=no-deprecated</code>
|
|
option does not disable warnings about absolutely all deprecated features.
|
|
Warnings for some deprecated features that have already been through
|
|
several releases with deprecation warnings
|
|
may be mandatory for a release or two
|
|
before they are officially no longer supported by SCons.
|
|
Warnings for some specific deprecated features
|
|
may be enabled or disabled individually;
|
|
see below.</p><div class="blockquote"><blockquote class="blockquote"><div class="variablelist"><dl><dt><span class="term">--warn=deprecated-copy, --warn=no-deprecated-copy</span></dt><dd><p>Enables or disables warnings about use of the deprecated
|
|
<span class="bold"><strong>env.Copy()</strong></span>
|
|
method.</p></dd><dt><span class="term">--warn=deprecated-source-signatures, --warn=no-deprecated-source-signatures</span></dt><dd><p>Enables or disables warnings about use of the deprecated
|
|
<span class="bold"><strong>SourceSignatures()</strong></span>
|
|
function or
|
|
<span class="bold"><strong>env.SourceSignatures()</strong></span>
|
|
method.</p></dd><dt><span class="term">--warn=deprecated-target-signatures, --warn=no-deprecated-target-signatures</span></dt><dd><p>Enables or disables warnings about use of the deprecated
|
|
<span class="bold"><strong>TargetSignatures()</strong></span>
|
|
function or
|
|
<span class="bold"><strong>env.TargetSignatures()</strong></span>
|
|
method.</p></dd></dl></div></blockquote></div></dd><dt><span class="term">--warn=duplicate-environment, --warn=no-duplicate-environment</span></dt><dd><p>Enables or disables warnings about attempts to specify a build
|
|
of a target with two different construction environments
|
|
that use the same action.
|
|
These warnings are enabled by default.</p></dd><dt><span class="term">--warn=fortran-cxx-mix, --warn=no-fortran-cxx-mix</span></dt><dd><p>Enables or disables the specific warning about linking
|
|
Fortran and C++ object files in a single executable,
|
|
which can yield unpredictable behavior with some compilers.</p></dd><dt><span class="term">--warn=future-deprecated, --warn=no-future-deprecated</span></dt><dd><p>Enables or disables warnings about features
|
|
that will be deprecated in the future.
|
|
These warnings are disabled by default.
|
|
Enabling this warning is especially
|
|
recommended for projects that redistribute
|
|
SCons configurations for other users to build,
|
|
so that the project can be warned as soon as possible
|
|
about to-be-deprecated features
|
|
that may require changes to the configuration.</p></dd><dt><span class="term">--warn=link, --warn=no-link</span></dt><dd><p>Enables or disables warnings about link steps.</p></dd><dt><span class="term">--warn=misleading-keywords, --warn=no-misleading-keywords</span></dt><dd><p>Enables or disables warnings about use of the misspelled keywords
|
|
<span class="bold"><strong>targets</strong></span>
|
|
and
|
|
<span class="bold"><strong>sources</strong></span>
|
|
when calling Builders.
|
|
(Note the last
|
|
<span class="bold"><strong>s</strong></span>
|
|
characters, the correct spellings are
|
|
<span class="bold"><strong>target</strong></span>
|
|
and
|
|
<span class="bold"><strong>source.)</strong></span>
|
|
These warnings are enabled by default.</p></dd><dt><span class="term">--warn=missing-sconscript, --warn=no-missing-sconscript</span></dt><dd><p>Enables or disables warnings about missing SConscript files.
|
|
These warnings are enabled by default.</p></dd><dt><span class="term">--warn=no-object-count, --warn=no-no-object-count</span></dt><dd><p>Enables or disables warnings about the
|
|
<code class="option">--debug=object</code>
|
|
feature not working when
|
|
<span class="command"><strong>scons</strong></span>
|
|
is run with the python
|
|
<code class="option">-O</code>
|
|
option or from optimized Python (.pyo) modules.</p></dd><dt><span class="term">--warn=no-parallel-support, --warn=no-no-parallel-support</span></dt><dd><p>Enables or disables warnings about the version of Python
|
|
not being able to support parallel builds when the
|
|
<code class="option">-j</code>
|
|
option is used.
|
|
These warnings are enabled by default.</p></dd><dt><span class="term">--warn=python-version, --warn=no-python-version</span></dt><dd><p>Enables or disables the warning about running
|
|
SCons with a deprecated version of Python.
|
|
These warnings are enabled by default.</p></dd><dt><span class="term">--warn=reserved-variable, --warn=no-reserved-variable</span></dt><dd><p>Enables or disables warnings about attempts to set the
|
|
reserved construction variable names
|
|
<span class="bold"><strong>CHANGED_SOURCES</strong></span>,
|
|
<span class="bold"><strong>CHANGED_TARGETS</strong></span>,
|
|
<span class="bold"><strong>TARGET</strong></span>,
|
|
<span class="bold"><strong>TARGETS</strong></span>,
|
|
<span class="bold"><strong>SOURCE</strong></span>,
|
|
<span class="bold"><strong>SOURCES</strong></span>,
|
|
<span class="bold"><strong>UNCHANGED_SOURCES</strong></span>
|
|
or
|
|
<span class="bold"><strong>UNCHANGED_TARGETS</strong></span>.
|
|
These warnings are disabled by default.</p></dd><dt><span class="term">--warn=stack-size, --warn=no-stack-size</span></dt><dd><p>Enables or disables warnings about requests to set the stack size
|
|
that could not be honored.
|
|
These warnings are enabled by default.</p></dd><dt><span class="term">--warn=target_not_build, --warn=no-target_not_built</span></dt><dd><p>Enables or disables warnings about a build rule not building the
|
|
expected targets. These warnings are not currently enabled by default.</p></dd><dt><span class="term">-Y<span class="emphasis"><em> repository</em></span>, --repository=<span class="emphasis"><em>repository</em></span>, --srcdir=<span class="emphasis"><em>repository</em></span></span></dt><dd><p>Search the specified repository for any input and target
|
|
files not found in the local directory hierarchy. Multiple
|
|
<code class="option">-Y</code>
|
|
options may be specified, in which case the
|
|
repositories are searched in the order specified.</p></dd></dl></div></div><div class="refsect1" title="CONFIGURATION FILE REFERENCE"><a name="configuration_file_reference"></a><h2>CONFIGURATION FILE REFERENCE</h2><div class="refsect2" title="Construction Environments"><a name="construction_environments"></a><h3>Construction Environments</h3><p>A construction environment is the basic means by which the SConscript
|
|
files communicate build information to
|
|
<span class="command"><strong>scons</strong></span>.
|
|
A new construction environment is created using the
|
|
<span class="bold"><strong>Environment</strong></span>
|
|
function:</p><pre class="literallayout">
|
|
env = Environment()
|
|
</pre><p>Variables, called
|
|
<span class="emphasis"><em>construction</em></span>
|
|
<span class="emphasis"><em>variables</em></span>,
|
|
may be set in a construction environment
|
|
either by specifying them as keywords when the object is created
|
|
or by assigning them a value after the object is created:</p><pre class="literallayout">
|
|
env = Environment(FOO = 'foo')
|
|
env['BAR'] = 'bar'
|
|
</pre><p>As a convenience,
|
|
construction variables may also be set or modified by the
|
|
<span class="emphasis"><em>parse_flags</em></span>
|
|
keyword argument, which applies the
|
|
<span class="bold"><strong>ParseFlags</strong></span>
|
|
method (described below) to the argument value
|
|
after all other processing is completed.
|
|
This is useful either if the exact content of the flags is unknown
|
|
(for example, read from a control file)
|
|
or if the flags are distributed to a number of construction variables.</p><pre class="literallayout">
|
|
env = Environment(parse_flags = '-Iinclude -DEBUG -lm')
|
|
</pre><p>This example adds 'include' to
|
|
<span class="bold"><strong>CPPPATH</strong></span>,
|
|
'EBUG' to
|
|
<span class="bold"><strong>CPPDEFINES</strong></span>,
|
|
and 'm' to
|
|
<span class="bold"><strong>LIBS</strong></span>.</p><p>By default, a new construction environment is
|
|
initialized with a set of builder methods
|
|
and construction variables that are appropriate
|
|
for the current platform.
|
|
An optional platform keyword argument may be
|
|
used to specify that an environment should
|
|
be initialized for a different platform:</p><pre class="literallayout">
|
|
env = Environment(platform = 'cygwin')
|
|
env = Environment(platform = 'os2')
|
|
env = Environment(platform = 'posix')
|
|
env = Environment(platform = 'win32')
|
|
</pre><p>Specifying a platform initializes the appropriate
|
|
construction variables in the environment
|
|
to use and generate file names with prefixes
|
|
and suffixes appropriate for the platform.</p><p>Note that the
|
|
<span class="bold"><strong>win32</strong></span>
|
|
platform adds the
|
|
<span class="bold"><strong>SystemDrive</strong></span>
|
|
and
|
|
<span class="bold"><strong>SystemRoot</strong></span>
|
|
variables from the user's external environment
|
|
to the construction environment's
|
|
<span class="bold"><strong>ENV</strong></span>
|
|
dictionary.
|
|
This is so that any executed commands
|
|
that use sockets to connect with other systems
|
|
(such as fetching source files from
|
|
external CVS repository specifications like
|
|
<span class="bold"><strong>:pserver:anonymous@cvs.sourceforge.net:/cvsroot/scons</strong></span>)
|
|
will work on Windows systems.</p><p>The platform argument may be function or callable object,
|
|
in which case the Environment() method
|
|
will call the specified argument to update
|
|
the new construction environment:</p><pre class="programlisting">
|
|
def my_platform(env):
|
|
env['VAR'] = 'xyzzy'
|
|
|
|
env = Environment(platform = my_platform)
|
|
</pre><p>Additionally, a specific set of tools
|
|
with which to initialize the environment
|
|
may be specified as an optional keyword argument:</p><pre class="literallayout">
|
|
env = Environment(tools = ['msvc', 'lex'])
|
|
</pre><p>Non-built-in tools may be specified using the toolpath argument:</p><pre class="literallayout">
|
|
env = Environment(tools = ['default', 'foo'], toolpath = ['tools'])
|
|
</pre><p>This looks for a tool specification in tools/foo.py (as well as
|
|
using the ordinary default tools for the platform). foo.py should
|
|
have two functions: generate(env, **kw) and exists(env).
|
|
The
|
|
<code class="function">generate()</code>
|
|
function
|
|
modifies the passed-in environment
|
|
to set up variables so that the tool
|
|
can be executed;
|
|
it may use any keyword arguments
|
|
that the user supplies (see below)
|
|
to vary its initialization.
|
|
The
|
|
<code class="function">exists()</code>
|
|
function should return a true
|
|
value if the tool is available.
|
|
Tools in the toolpath are used before
|
|
any of the built-in ones. For example, adding gcc.py to the toolpath
|
|
would override the built-in gcc tool.
|
|
Also note that the toolpath is
|
|
stored in the environment for use
|
|
by later calls to
|
|
<span class="bold"><strong>Clone</strong></span>()
|
|
and
|
|
<span class="bold"><strong>Tool</strong></span>()
|
|
methods:</p><pre class="literallayout">
|
|
base = Environment(toolpath=['custom_path'])
|
|
derived = base.Clone(tools=['custom_tool'])
|
|
derived.CustomBuilder()
|
|
</pre><p>The elements of the tools list may also
|
|
be functions or callable objects,
|
|
in which case the Environment() method
|
|
will call the specified elements
|
|
to update the new construction environment:</p><pre class="programlisting">
|
|
def my_tool(env):
|
|
env['XYZZY'] = 'xyzzy'
|
|
|
|
env = Environment(tools = [my_tool])
|
|
</pre><p>The individual elements of the tools list
|
|
may also themselves be two-element lists of the form
|
|
(<span class="emphasis"><em>toolname</em></span>, <span class="emphasis"><em>kw_dict</em></span>).
|
|
SCons searches for the
|
|
<span class="emphasis"><em>toolname</em></span>
|
|
specification file as described above, and
|
|
passes
|
|
<span class="emphasis"><em>kw_dict</em></span>,
|
|
which must be a dictionary, as keyword arguments to the tool's
|
|
<span class="bold"><strong>generate</strong></span>
|
|
function.
|
|
The
|
|
<span class="bold"><strong>generate</strong></span>
|
|
function can use the arguments to modify the tool's behavior
|
|
by setting up the environment in different ways
|
|
or otherwise changing its initialization.</p><pre class="programlisting">
|
|
# in tools/my_tool.py:
|
|
def generate(env, **kw):
|
|
# Sets MY_TOOL to the value of keyword argument 'arg1' or 1.
|
|
env['MY_TOOL'] = kw.get('arg1', '1')
|
|
def exists(env):
|
|
return 1
|
|
|
|
# in SConstruct:
|
|
env = Environment(tools = ['default', ('my_tool', {'arg1': 'abc'})],
|
|
toolpath=['tools'])
|
|
</pre><p>The tool definition (i.e. my_tool()) can use the PLATFORM variable from
|
|
the environment it receives to customize the tool for different platforms.</p><p>If no tool list is specified, then SCons will auto-detect the installed
|
|
tools using the PATH variable in the ENV construction variable and the
|
|
platform name when the Environment is constructed. Changing the PATH
|
|
variable after the Environment is constructed will not cause the tools to
|
|
be redetected.</p><p> One feature now present within Scons is the ability to have nested tools.
|
|
Tools which can be located within a subdirectory in the toolpath.
|
|
With a nested tool name the dot represents a directory seperator</p><pre class="programlisting">
|
|
# namespaced builder
|
|
env = Environment(ENV = os.environ, tools = ['SubDir1.SubDir2.SomeTool'])
|
|
env.SomeTool(targets, sources)
|
|
|
|
# Search Paths
|
|
# SCons\Tool\SubDir1\SubDir2\SomeTool.py
|
|
# SCons\Tool\SubDir1\SubDir2\SomeTool\__init__.py
|
|
# .\site_scons\site_tools\SubDir1\SubDir2\SomeTool.py
|
|
# .\site_scons\site_tools\SubDir1\SubDir2\SomeTool\__init__.py
|
|
</pre><p>SCons supports the following tool specifications out of the box:</p><div class="variablelist"><dl><dt><a name="t-386asm"></a><span class="term">386asm</span></dt><dd><p>
|
|
Sets construction variables for the 386ASM assembler
|
|
for the Phar Lap ETS embedded operating system.
|
|
</p><p>Sets: <a class="link" href="#cv-AS"><code class="envar">$AS</code></a>, <a class="link" href="#cv-ASCOM"><code class="envar">$ASCOM</code></a>, <a class="link" href="#cv-ASFLAGS"><code class="envar">$ASFLAGS</code></a>, <a class="link" href="#cv-ASPPCOM"><code class="envar">$ASPPCOM</code></a>, <a class="link" href="#cv-ASPPFLAGS"><code class="envar">$ASPPFLAGS</code></a>.</p><p>Uses: <a class="link" href="#cv-CC"><code class="envar">$CC</code></a>, <a class="link" href="#cv-CPPFLAGS"><code class="envar">$CPPFLAGS</code></a>, <a class="link" href="#cv-_CPPDEFFLAGS"><code class="envar">$_CPPDEFFLAGS</code></a>, <a class="link" href="#cv-_CPPINCFLAGS"><code class="envar">$_CPPINCFLAGS</code></a>.</p></dd><dt><a name="t-aixcXX"></a><span class="term">aixc++</span></dt><dd><p>
|
|
Sets construction variables for the IMB xlc / Visual Age C++ compiler.
|
|
</p><p>Sets: <a class="link" href="#cv-CXX"><code class="envar">$CXX</code></a>, <a class="link" href="#cv-CXXVERSION"><code class="envar">$CXXVERSION</code></a>, <a class="link" href="#cv-SHCXX"><code class="envar">$SHCXX</code></a>, <a class="link" href="#cv-SHOBJSUFFIX"><code class="envar">$SHOBJSUFFIX</code></a>.</p></dd><dt><a name="t-aixcc"></a><span class="term">aixcc</span></dt><dd><p>
|
|
Sets construction variables for the IBM xlc / Visual Age C compiler.
|
|
</p><p>Sets: <a class="link" href="#cv-CC"><code class="envar">$CC</code></a>, <a class="link" href="#cv-CCVERSION"><code class="envar">$CCVERSION</code></a>, <a class="link" href="#cv-SHCC"><code class="envar">$SHCC</code></a>.</p></dd><dt><a name="t-aixf77"></a><span class="term">aixf77</span></dt><dd><p>
|
|
Sets construction variables for the IBM Visual Age f77 Fortran compiler.
|
|
</p><p>Sets: <a class="link" href="#cv-F77"><code class="envar">$F77</code></a>, <a class="link" href="#cv-SHF77"><code class="envar">$SHF77</code></a>.</p></dd><dt><a name="t-aixlink"></a><span class="term">aixlink</span></dt><dd><p>
|
|
Sets construction variables for the IBM Visual Age linker.
|
|
</p><p>Sets: <a class="link" href="#cv-LINKFLAGS"><code class="envar">$LINKFLAGS</code></a>, <a class="link" href="#cv-SHLIBSUFFIX"><code class="envar">$SHLIBSUFFIX</code></a>, <a class="link" href="#cv-SHLINKFLAGS"><code class="envar">$SHLINKFLAGS</code></a>.</p></dd><dt><a name="t-applelink"></a><span class="term">applelink</span></dt><dd><p>
|
|
Sets construction variables for the Apple linker
|
|
(similar to the GNU linker).
|
|
</p><p>Sets: <a class="link" href="#cv-APPLELINK_COMPATIBILITY_VERSION"><code class="envar">$APPLELINK_COMPATIBILITY_VERSION</code></a>, <a class="link" href="#cv-APPLELINK_CURRENT_VERSION"><code class="envar">$APPLELINK_CURRENT_VERSION</code></a>, <a class="link" href="#cv-APPLELINK_NO_COMPATIBILITY_VERSION"><code class="envar">$APPLELINK_NO_COMPATIBILITY_VERSION</code></a>, <a class="link" href="#cv-APPLELINK_NO_CURRENT_VERSION"><code class="envar">$APPLELINK_NO_CURRENT_VERSION</code></a>, <a class="link" href="#cv-FRAMEWORKPATHPREFIX"><code class="envar">$FRAMEWORKPATHPREFIX</code></a>, <a class="link" href="#cv-LDMODULECOM"><code class="envar">$LDMODULECOM</code></a>, <a class="link" href="#cv-LDMODULEFLAGS"><code class="envar">$LDMODULEFLAGS</code></a>, <a class="link" href="#cv-LDMODULEPREFIX"><code class="envar">$LDMODULEPREFIX</code></a>, <a class="link" href="#cv-LDMODULESUFFIX"><code class="envar">$LDMODULESUFFIX</code></a>, <a class="link" href="#cv-LINKCOM"><code class="envar">$LINKCOM</code></a>, <a class="link" href="#cv-SHLINKCOM"><code class="envar">$SHLINKCOM</code></a>, <a class="link" href="#cv-SHLINKFLAGS"><code class="envar">$SHLINKFLAGS</code></a>, <a class="link" href="#cv-_APPLELINK_COMPATIBILITY_VERSION"><code class="envar">$_APPLELINK_COMPATIBILITY_VERSION</code></a>, <a class="link" href="#cv-_APPLELINK_CURRENT_VERSION"><code class="envar">$_APPLELINK_CURRENT_VERSION</code></a>, <a class="link" href="#cv-_FRAMEWORKPATH"><code class="envar">$_FRAMEWORKPATH</code></a>, <a class="link" href="#cv-_FRAMEWORKS"><code class="envar">$_FRAMEWORKS</code></a>.</p><p>Uses: <a class="link" href="#cv-FRAMEWORKSFLAGS"><code class="envar">$FRAMEWORKSFLAGS</code></a>.</p></dd><dt><a name="t-ar"></a><span class="term">ar</span></dt><dd><p>
|
|
Sets construction variables for the <span class="application">ar</span> library archiver.
|
|
</p><p>Sets: <a class="link" href="#cv-AR"><code class="envar">$AR</code></a>, <a class="link" href="#cv-ARCOM"><code class="envar">$ARCOM</code></a>, <a class="link" href="#cv-ARFLAGS"><code class="envar">$ARFLAGS</code></a>, <a class="link" href="#cv-LIBPREFIX"><code class="envar">$LIBPREFIX</code></a>, <a class="link" href="#cv-LIBSUFFIX"><code class="envar">$LIBSUFFIX</code></a>, <a class="link" href="#cv-RANLIB"><code class="envar">$RANLIB</code></a>, <a class="link" href="#cv-RANLIBCOM"><code class="envar">$RANLIBCOM</code></a>, <a class="link" href="#cv-RANLIBFLAGS"><code class="envar">$RANLIBFLAGS</code></a>.</p></dd><dt><a name="t-as"></a><span class="term">as</span></dt><dd><p>
|
|
Sets construction variables for the <span class="application">as</span> assembler.
|
|
</p><p>Sets: <a class="link" href="#cv-AS"><code class="envar">$AS</code></a>, <a class="link" href="#cv-ASCOM"><code class="envar">$ASCOM</code></a>, <a class="link" href="#cv-ASFLAGS"><code class="envar">$ASFLAGS</code></a>, <a class="link" href="#cv-ASPPCOM"><code class="envar">$ASPPCOM</code></a>, <a class="link" href="#cv-ASPPFLAGS"><code class="envar">$ASPPFLAGS</code></a>.</p><p>Uses: <a class="link" href="#cv-CC"><code class="envar">$CC</code></a>, <a class="link" href="#cv-CPPFLAGS"><code class="envar">$CPPFLAGS</code></a>, <a class="link" href="#cv-_CPPDEFFLAGS"><code class="envar">$_CPPDEFFLAGS</code></a>, <a class="link" href="#cv-_CPPINCFLAGS"><code class="envar">$_CPPINCFLAGS</code></a>.</p></dd><dt><a name="t-bcc32"></a><span class="term">bcc32</span></dt><dd><p>
|
|
Sets construction variables for the bcc32 compiler.
|
|
</p><p>Sets: <a class="link" href="#cv-CC"><code class="envar">$CC</code></a>, <a class="link" href="#cv-CCCOM"><code class="envar">$CCCOM</code></a>, <a class="link" href="#cv-CCFLAGS"><code class="envar">$CCFLAGS</code></a>, <a class="link" href="#cv-CFILESUFFIX"><code class="envar">$CFILESUFFIX</code></a>, <a class="link" href="#cv-CFLAGS"><code class="envar">$CFLAGS</code></a>, <a class="link" href="#cv-CPPDEFPREFIX"><code class="envar">$CPPDEFPREFIX</code></a>, <a class="link" href="#cv-CPPDEFSUFFIX"><code class="envar">$CPPDEFSUFFIX</code></a>, <a class="link" href="#cv-INCPREFIX"><code class="envar">$INCPREFIX</code></a>, <a class="link" href="#cv-INCSUFFIX"><code class="envar">$INCSUFFIX</code></a>, <a class="link" href="#cv-SHCC"><code class="envar">$SHCC</code></a>, <a class="link" href="#cv-SHCCCOM"><code class="envar">$SHCCCOM</code></a>, <a class="link" href="#cv-SHCCFLAGS"><code class="envar">$SHCCFLAGS</code></a>, <a class="link" href="#cv-SHCFLAGS"><code class="envar">$SHCFLAGS</code></a>, <a class="link" href="#cv-SHOBJSUFFIX"><code class="envar">$SHOBJSUFFIX</code></a>.</p><p>Uses: <a class="link" href="#cv-_CPPDEFFLAGS"><code class="envar">$_CPPDEFFLAGS</code></a>, <a class="link" href="#cv-_CPPINCFLAGS"><code class="envar">$_CPPINCFLAGS</code></a>.</p></dd><dt><a name="t-cc"></a><span class="term">cc</span></dt><dd><p>
|
|
Sets construction variables for generic POSIX C copmilers.
|
|
</p><p>Sets: <a class="link" href="#cv-CC"><code class="envar">$CC</code></a>, <a class="link" href="#cv-CCCOM"><code class="envar">$CCCOM</code></a>, <a class="link" href="#cv-CCFLAGS"><code class="envar">$CCFLAGS</code></a>, <a class="link" href="#cv-CFILESUFFIX"><code class="envar">$CFILESUFFIX</code></a>, <a class="link" href="#cv-CFLAGS"><code class="envar">$CFLAGS</code></a>, <a class="link" href="#cv-CPPDEFPREFIX"><code class="envar">$CPPDEFPREFIX</code></a>, <a class="link" href="#cv-CPPDEFSUFFIX"><code class="envar">$CPPDEFSUFFIX</code></a>, <a class="link" href="#cv-FRAMEWORKPATH"><code class="envar">$FRAMEWORKPATH</code></a>, <a class="link" href="#cv-FRAMEWORKS"><code class="envar">$FRAMEWORKS</code></a>, <a class="link" href="#cv-INCPREFIX"><code class="envar">$INCPREFIX</code></a>, <a class="link" href="#cv-INCSUFFIX"><code class="envar">$INCSUFFIX</code></a>, <a class="link" href="#cv-SHCC"><code class="envar">$SHCC</code></a>, <a class="link" href="#cv-SHCCCOM"><code class="envar">$SHCCCOM</code></a>, <a class="link" href="#cv-SHCCFLAGS"><code class="envar">$SHCCFLAGS</code></a>, <a class="link" href="#cv-SHCFLAGS"><code class="envar">$SHCFLAGS</code></a>, <a class="link" href="#cv-SHOBJSUFFIX"><code class="envar">$SHOBJSUFFIX</code></a>.</p><p>Uses: <a class="link" href="#cv-PLATFORM"><code class="envar">$PLATFORM</code></a>.</p></dd><dt><a name="t-clang"></a><span class="term">clang</span></dt><dd><p>
|
|
Set construction variables for the Clang C compiler.
|
|
</p><p>Sets: <a class="link" href="#cv-CC"><code class="envar">$CC</code></a>, <a class="link" href="#cv-CCVERSION"><code class="envar">$CCVERSION</code></a>, <a class="link" href="#cv-SHCCFLAGS"><code class="envar">$SHCCFLAGS</code></a>.</p></dd><dt><a name="t-clangxx"></a><span class="term">clangxx</span></dt><dd><p>
|
|
Set construction variables for the Clang C++ compiler.
|
|
</p><p>Sets: <a class="link" href="#cv-CXX"><code class="envar">$CXX</code></a>, <a class="link" href="#cv-CXXVERSION"><code class="envar">$CXXVERSION</code></a>, <a class="link" href="#cv-SHCXXFLAGS"><code class="envar">$SHCXXFLAGS</code></a>, <a class="link" href="#cv-SHOBJSUFFIX"><code class="envar">$SHOBJSUFFIX</code></a>, <a class="link" href="#cv-STATIC_AND_SHARED_OBJECTS_ARE_THE_SAME"><code class="envar">$STATIC_AND_SHARED_OBJECTS_ARE_THE_SAME</code></a>.</p></dd><dt><a name="t-cvf"></a><span class="term">cvf</span></dt><dd><p>
|
|
Sets construction variables for the Compaq Visual Fortran compiler.
|
|
</p><p>Sets: <a class="link" href="#cv-FORTRAN"><code class="envar">$FORTRAN</code></a>, <a class="link" href="#cv-FORTRANCOM"><code class="envar">$FORTRANCOM</code></a>, <a class="link" href="#cv-FORTRANMODDIR"><code class="envar">$FORTRANMODDIR</code></a>, <a class="link" href="#cv-FORTRANMODDIRPREFIX"><code class="envar">$FORTRANMODDIRPREFIX</code></a>, <a class="link" href="#cv-FORTRANMODDIRSUFFIX"><code class="envar">$FORTRANMODDIRSUFFIX</code></a>, <a class="link" href="#cv-FORTRANPPCOM"><code class="envar">$FORTRANPPCOM</code></a>, <a class="link" href="#cv-OBJSUFFIX"><code class="envar">$OBJSUFFIX</code></a>, <a class="link" href="#cv-SHFORTRANCOM"><code class="envar">$SHFORTRANCOM</code></a>, <a class="link" href="#cv-SHFORTRANPPCOM"><code class="envar">$SHFORTRANPPCOM</code></a>.</p><p>Uses: <a class="link" href="#cv-CPPFLAGS"><code class="envar">$CPPFLAGS</code></a>, <a class="link" href="#cv-FORTRANFLAGS"><code class="envar">$FORTRANFLAGS</code></a>, <a class="link" href="#cv-SHFORTRANFLAGS"><code class="envar">$SHFORTRANFLAGS</code></a>, <a class="link" href="#cv-_CPPDEFFLAGS"><code class="envar">$_CPPDEFFLAGS</code></a>, <a class="link" href="#cv-_FORTRANINCFLAGS"><code class="envar">$_FORTRANINCFLAGS</code></a>, <a class="link" href="#cv-_FORTRANMODFLAG"><code class="envar">$_FORTRANMODFLAG</code></a>.</p></dd><dt><a name="t-cXX"></a><span class="term">cXX</span></dt><dd><p>
|
|
Sets construction variables for generic POSIX C++ compilers.
|
|
</p><p>Sets: <a class="link" href="#cv-CPPDEFPREFIX"><code class="envar">$CPPDEFPREFIX</code></a>, <a class="link" href="#cv-CPPDEFSUFFIX"><code class="envar">$CPPDEFSUFFIX</code></a>, <a class="link" href="#cv-CXX"><code class="envar">$CXX</code></a>, <a class="link" href="#cv-CXXCOM"><code class="envar">$CXXCOM</code></a>, <a class="link" href="#cv-CXXFILESUFFIX"><code class="envar">$CXXFILESUFFIX</code></a>, <a class="link" href="#cv-CXXFLAGS"><code class="envar">$CXXFLAGS</code></a>, <a class="link" href="#cv-INCPREFIX"><code class="envar">$INCPREFIX</code></a>, <a class="link" href="#cv-INCSUFFIX"><code class="envar">$INCSUFFIX</code></a>, <a class="link" href="#cv-OBJSUFFIX"><code class="envar">$OBJSUFFIX</code></a>, <a class="link" href="#cv-SHCXX"><code class="envar">$SHCXX</code></a>, <a class="link" href="#cv-SHCXXCOM"><code class="envar">$SHCXXCOM</code></a>, <a class="link" href="#cv-SHCXXFLAGS"><code class="envar">$SHCXXFLAGS</code></a>, <a class="link" href="#cv-SHOBJSUFFIX"><code class="envar">$SHOBJSUFFIX</code></a>.</p><p>Uses: <a class="link" href="#cv-CXXCOMSTR"><code class="envar">$CXXCOMSTR</code></a>.</p></dd><dt><a name="t-cyglink"></a><span class="term">cyglink</span></dt><dd><p>
|
|
Set construction variables for cygwin linker/loader.
|
|
</p><p>Sets: <a class="link" href="#cv-IMPLIBPREFIX"><code class="envar">$IMPLIBPREFIX</code></a>, <a class="link" href="#cv-IMPLIBSUFFIX"><code class="envar">$IMPLIBSUFFIX</code></a>, <a class="link" href="#cv-LDMODULEVERSIONFLAGS"><code class="envar">$LDMODULEVERSIONFLAGS</code></a>, <a class="link" href="#cv-LINKFLAGS"><code class="envar">$LINKFLAGS</code></a>, <a class="link" href="#cv-RPATHPREFIX"><code class="envar">$RPATHPREFIX</code></a>, <a class="link" href="#cv-RPATHSUFFIX"><code class="envar">$RPATHSUFFIX</code></a>, <a class="link" href="#cv-SHLIBPREFIX"><code class="envar">$SHLIBPREFIX</code></a>, <a class="link" href="#cv-SHLIBSUFFIX"><code class="envar">$SHLIBSUFFIX</code></a>, <a class="link" href="#cv-SHLIBVERSIONFLAGS"><code class="envar">$SHLIBVERSIONFLAGS</code></a>, <a class="link" href="#cv-SHLINKCOM"><code class="envar">$SHLINKCOM</code></a>, <a class="link" href="#cv-SHLINKFLAGS"><code class="envar">$SHLINKFLAGS</code></a>, <a class="link" href="#cv-_LDMODULEVERSIONFLAGS"><code class="envar">$_LDMODULEVERSIONFLAGS</code></a>, <a class="link" href="#cv-_SHLIBVERSIONFLAGS"><code class="envar">$_SHLIBVERSIONFLAGS</code></a>.</p></dd><dt><a name="t-default"></a><span class="term">default</span></dt><dd><p>
|
|
Sets variables by calling a default list of Tool modules
|
|
for the platform on which SCons is running.
|
|
</p></dd><dt><a name="t-dmd"></a><span class="term">dmd</span></dt><dd><p>
|
|
Sets construction variables for D language compiler DMD.
|
|
</p><p>Sets: <a class="link" href="#cv-DC"><code class="envar">$DC</code></a>, <a class="link" href="#cv-DCOM"><code class="envar">$DCOM</code></a>, <a class="link" href="#cv-DDEBUG"><code class="envar">$DDEBUG</code></a>, <a class="link" href="#cv-DDEBUGPREFIX"><code class="envar">$DDEBUGPREFIX</code></a>, <a class="link" href="#cv-DDEBUGSUFFIX"><code class="envar">$DDEBUGSUFFIX</code></a>, <a class="link" href="#cv-DFILESUFFIX"><code class="envar">$DFILESUFFIX</code></a>, <a class="link" href="#cv-DFLAGPREFIX"><code class="envar">$DFLAGPREFIX</code></a>, <a class="link" href="#cv-DFLAGS"><code class="envar">$DFLAGS</code></a>, <a class="link" href="#cv-DFLAGSUFFIX"><code class="envar">$DFLAGSUFFIX</code></a>, <a class="link" href="#cv-DINCPREFIX"><code class="envar">$DINCPREFIX</code></a>, <a class="link" href="#cv-DINCSUFFIX"><code class="envar">$DINCSUFFIX</code></a>, <a class="link" href="#cv-DLIB"><code class="envar">$DLIB</code></a>, <a class="link" href="#cv-DLIBCOM"><code class="envar">$DLIBCOM</code></a>, <a class="link" href="#cv-DLIBDIRPREFIX"><code class="envar">$DLIBDIRPREFIX</code></a>, <a class="link" href="#cv-DLIBDIRSUFFIX"><code class="envar">$DLIBDIRSUFFIX</code></a>, <a class="link" href="#cv-DLIBFLAGPREFIX"><code class="envar">$DLIBFLAGPREFIX</code></a>, <a class="link" href="#cv-DLIBFLAGSUFFIX"><code class="envar">$DLIBFLAGSUFFIX</code></a>, <a class="link" href="#cv-DLIBLINKPREFIX"><code class="envar">$DLIBLINKPREFIX</code></a>, <a class="link" href="#cv-DLIBLINKSUFFIX"><code class="envar">$DLIBLINKSUFFIX</code></a>, <a class="link" href="#cv-DLINK"><code class="envar">$DLINK</code></a>, <a class="link" href="#cv-DLINKCOM"><code class="envar">$DLINKCOM</code></a>, <a class="link" href="#cv-DLINKFLAGPREFIX"><code class="envar">$DLINKFLAGPREFIX</code></a>, <a class="link" href="#cv-DLINKFLAGS"><code class="envar">$DLINKFLAGS</code></a>, <a class="link" href="#cv-DLINKFLAGSUFFIX"><code class="envar">$DLINKFLAGSUFFIX</code></a>, <a class="link" href="#cv-DPATH"><code class="envar">$DPATH</code></a>, <a class="link" href="#cv-DRPATHPREFIX"><code class="envar">$DRPATHPREFIX</code></a>, <a class="link" href="#cv-DRPATHSUFFIX"><code class="envar">$DRPATHSUFFIX</code></a>, <a class="link" href="#cv-DShLibSonameGenerator"><code class="envar">$DShLibSonameGenerator</code></a>, <a class="link" href="#cv-DVERPREFIX"><code class="envar">$DVERPREFIX</code></a>, <a class="link" href="#cv-DVERSIONS"><code class="envar">$DVERSIONS</code></a>, <a class="link" href="#cv-DVERSUFFIX"><code class="envar">$DVERSUFFIX</code></a>, <a class="link" href="#cv-SHDC"><code class="envar">$SHDC</code></a>, <a class="link" href="#cv-SHDCOM"><code class="envar">$SHDCOM</code></a>, <a class="link" href="#cv-SHDLIBVERSION"><code class="envar">$SHDLIBVERSION</code></a>, <a class="link" href="#cv-SHDLIBVERSIONFLAGS"><code class="envar">$SHDLIBVERSIONFLAGS</code></a>, <a class="link" href="#cv-SHDLINK"><code class="envar">$SHDLINK</code></a>, <a class="link" href="#cv-SHDLINKCOM"><code class="envar">$SHDLINKCOM</code></a>, <a class="link" href="#cv-SHDLINKFLAGS"><code class="envar">$SHDLINKFLAGS</code></a>.</p></dd><dt><a name="t-docbook"></a><span class="term">docbook</span></dt><dd><p>This tool tries to make working with Docbook in SCons a little easier.
|
|
It provides several toolchains for creating different output formats,
|
|
like HTML or PDF. Contained in the package is
|
|
a distribution of the Docbook XSL stylesheets as of version 1.76.1.
|
|
As long as you don't specify your own stylesheets for customization,
|
|
these official versions are picked as default...which should reduce
|
|
the inevitable setup hassles for you.
|
|
</p><p>Implicit dependencies to images and XIncludes are detected automatically
|
|
if you meet the HTML requirements. The additional
|
|
stylesheet <code class="filename">utils/xmldepend.xsl</code> by Paul DuBois is used for this purpose.
|
|
</p><p>Note, that there is no support for XML catalog resolving offered! This tool calls
|
|
the XSLT processors and PDF renderers with the stylesheets you specified, that's it.
|
|
The rest lies in your hands and you still have to know what you're doing when
|
|
resolving names via a catalog.
|
|
</p><p>For activating the tool "docbook", you have to add its name to the Environment constructor,
|
|
like this
|
|
</p><pre class="screen">env = Environment(tools=['docbook'])
|
|
</pre><p>On its startup, the Docbook tool tries to find a required <code class="literal">xsltproc</code> processor, and
|
|
a PDF renderer, e.g. <code class="literal">fop</code>. So make sure that these are added to your system's environment
|
|
<code class="literal">PATH</code> and can be called directly, without specifying their full path.
|
|
</p><p>For the most basic processing of Docbook to HTML, you need to have installed
|
|
</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>the Python <code class="literal">lxml</code> binding to <code class="literal">libxml2</code>, or
|
|
</p></li><li class="listitem"><p>the direct Python bindings for <code class="literal">libxml2/libxslt</code>, or
|
|
</p></li><li class="listitem"><p>a standalone XSLT processor, currently detected are <code class="literal">xsltproc</code>, <code class="literal">saxon</code>, <code class="literal">saxon-xslt</code>
|
|
and <code class="literal">xalan</code>.
|
|
</p></li></ul></div><p>Rendering to PDF requires you to have one of the applications
|
|
<code class="literal">fop</code> or <code class="literal">xep</code> installed.
|
|
</p><p>Creating a HTML or PDF document is very simple and straightforward. Say
|
|
</p><pre class="screen">env = Environment(tools=['docbook'])
|
|
env.DocbookHtml('manual.html', 'manual.xml')
|
|
env.DocbookPdf('manual.pdf', 'manual.xml')
|
|
</pre><p>to get both outputs from your XML source <code class="filename">manual.xml</code>. As a shortcut, you can
|
|
give the stem of the filenames alone, like this:
|
|
</p><pre class="screen">env = Environment(tools=['docbook'])
|
|
env.DocbookHtml('manual')
|
|
env.DocbookPdf('manual')
|
|
</pre><p>and get the same result. Target and source lists are also supported:
|
|
</p><pre class="screen">env = Environment(tools=['docbook'])
|
|
env.DocbookHtml(['manual.html','reference.html'], ['manual.xml','reference.xml'])
|
|
</pre><p>or even
|
|
</p><pre class="screen">env = Environment(tools=['docbook'])
|
|
env.DocbookHtml(['manual','reference'])
|
|
</pre><div class="important" title="Important" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Important</h3><p>Whenever you leave out the list of sources, you may not specify a file extension! The
|
|
Tool uses the given names as file stems, and adds the suffixes for target and source files
|
|
accordingly.
|
|
</p></div><p>The rules given above are valid for the Builders <a class="link" href="#b-DocbookHtml"><code class="function">DocbookHtml</code></a>,
|
|
<a class="link" href="#b-DocbookPdf"><code class="function">DocbookPdf</code></a>, <a class="link" href="#b-DocbookEpub"><code class="function">DocbookEpub</code></a>, <a class="link" href="#b-DocbookSlidesPdf"><code class="function">DocbookSlidesPdf</code></a> and <a class="link" href="#b-DocbookXInclude"><code class="function">DocbookXInclude</code></a>. For the
|
|
<a class="link" href="#b-DocbookMan"><code class="function">DocbookMan</code></a> transformation you
|
|
can specify a target name, but the actual output names are automatically
|
|
set from the <code class="literal">refname</code> entries in your XML source.
|
|
</p><p>The Builders <a class="link" href="#b-DocbookHtmlChunked"><code class="function">DocbookHtmlChunked</code></a>, <a class="link" href="#b-DocbookHtmlhelp"><code class="function">DocbookHtmlhelp</code></a> and
|
|
<a class="link" href="#b-DocbookSlidesHtml"><code class="function">DocbookSlidesHtml</code></a> are special, in that:
|
|
</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>they create a large set of files, where the exact names and their number depend
|
|
on the content of the source file, and
|
|
</p></li><li class="listitem"><p>the main target is always named <code class="filename">index.html</code>, i.e. the output name for the
|
|
XSL transformation is not picked up by the stylesheets.
|
|
</p></li></ol></div><p>As a result, there is simply no use in specifying a target HTML name.
|
|
So the basic syntax for these builders is always:
|
|
</p><pre class="screen">env = Environment(tools=['docbook'])
|
|
env.DocbookHtmlhelp('manual')
|
|
</pre><p>If you want to use a specific XSL file, you can set the
|
|
additional <code class="literal">xsl</code> parameter to your
|
|
Builder call as follows:
|
|
</p><pre class="screen">env.DocbookHtml('other.html', 'manual.xml', xsl='html.xsl')
|
|
</pre><p>Since this may get tedious if you always use the same local naming for your customized XSL files,
|
|
e.g. <code class="filename">html.xsl</code> for HTML and <code class="filename">pdf.xsl</code> for PDF output, a set of
|
|
variables for setting the default XSL name is provided. These are:
|
|
</p><pre class="screen">DOCBOOK_DEFAULT_XSL_HTML
|
|
DOCBOOK_DEFAULT_XSL_HTMLCHUNKED
|
|
DOCBOOK_DEFAULT_XSL_HTMLHELP
|
|
DOCBOOK_DEFAULT_XSL_PDF
|
|
DOCBOOK_DEFAULT_XSL_EPUB
|
|
DOCBOOK_DEFAULT_XSL_MAN
|
|
DOCBOOK_DEFAULT_XSL_SLIDESPDF
|
|
DOCBOOK_DEFAULT_XSL_SLIDESHTML
|
|
</pre><p>and you can set them when constructing your environment:
|
|
</p><pre class="screen">env = Environment(tools=['docbook'],
|
|
DOCBOOK_DEFAULT_XSL_HTML='html.xsl',
|
|
DOCBOOK_DEFAULT_XSL_PDF='pdf.xsl')
|
|
env.DocbookHtml('manual') # now uses html.xsl
|
|
</pre><p>Sets: <a class="link" href="#cv-DOCBOOK_DEFAULT_XSL_EPUB"><code class="envar">$DOCBOOK_DEFAULT_XSL_EPUB</code></a>, <a class="link" href="#cv-DOCBOOK_DEFAULT_XSL_HTML"><code class="envar">$DOCBOOK_DEFAULT_XSL_HTML</code></a>, <a class="link" href="#cv-DOCBOOK_DEFAULT_XSL_HTMLCHUNKED"><code class="envar">$DOCBOOK_DEFAULT_XSL_HTMLCHUNKED</code></a>, <a class="link" href="#cv-DOCBOOK_DEFAULT_XSL_HTMLHELP"><code class="envar">$DOCBOOK_DEFAULT_XSL_HTMLHELP</code></a>, <a class="link" href="#cv-DOCBOOK_DEFAULT_XSL_MAN"><code class="envar">$DOCBOOK_DEFAULT_XSL_MAN</code></a>, <a class="link" href="#cv-DOCBOOK_DEFAULT_XSL_PDF"><code class="envar">$DOCBOOK_DEFAULT_XSL_PDF</code></a>, <a class="link" href="#cv-DOCBOOK_DEFAULT_XSL_SLIDESHTML"><code class="envar">$DOCBOOK_DEFAULT_XSL_SLIDESHTML</code></a>, <a class="link" href="#cv-DOCBOOK_DEFAULT_XSL_SLIDESPDF"><code class="envar">$DOCBOOK_DEFAULT_XSL_SLIDESPDF</code></a>, <a class="link" href="#cv-DOCBOOK_FOP"><code class="envar">$DOCBOOK_FOP</code></a>, <a class="link" href="#cv-DOCBOOK_FOPCOM"><code class="envar">$DOCBOOK_FOPCOM</code></a>, <a class="link" href="#cv-DOCBOOK_FOPFLAGS"><code class="envar">$DOCBOOK_FOPFLAGS</code></a>, <a class="link" href="#cv-DOCBOOK_XMLLINT"><code class="envar">$DOCBOOK_XMLLINT</code></a>, <a class="link" href="#cv-DOCBOOK_XMLLINTCOM"><code class="envar">$DOCBOOK_XMLLINTCOM</code></a>, <a class="link" href="#cv-DOCBOOK_XMLLINTFLAGS"><code class="envar">$DOCBOOK_XMLLINTFLAGS</code></a>, <a class="link" href="#cv-DOCBOOK_XSLTPROC"><code class="envar">$DOCBOOK_XSLTPROC</code></a>, <a class="link" href="#cv-DOCBOOK_XSLTPROCCOM"><code class="envar">$DOCBOOK_XSLTPROCCOM</code></a>, <a class="link" href="#cv-DOCBOOK_XSLTPROCFLAGS"><code class="envar">$DOCBOOK_XSLTPROCFLAGS</code></a>, <a class="link" href="#cv-DOCBOOK_XSLTPROCPARAMS"><code class="envar">$DOCBOOK_XSLTPROCPARAMS</code></a>.</p><p>Uses: <a class="link" href="#cv-DOCBOOK_FOPCOMSTR"><code class="envar">$DOCBOOK_FOPCOMSTR</code></a>, <a class="link" href="#cv-DOCBOOK_XMLLINTCOMSTR"><code class="envar">$DOCBOOK_XMLLINTCOMSTR</code></a>, <a class="link" href="#cv-DOCBOOK_XSLTPROCCOMSTR"><code class="envar">$DOCBOOK_XSLTPROCCOMSTR</code></a>.</p></dd><dt><a name="t-dvi"></a><span class="term">dvi</span></dt><dd><p>
|
|
Attaches the <code class="function">DVI</code> builder to the
|
|
construction environment.
|
|
</p></dd><dt><a name="t-dvipdf"></a><span class="term">dvipdf</span></dt><dd><p>
|
|
Sets construction variables for the dvipdf utility.
|
|
</p><p>Sets: <a class="link" href="#cv-DVIPDF"><code class="envar">$DVIPDF</code></a>, <a class="link" href="#cv-DVIPDFCOM"><code class="envar">$DVIPDFCOM</code></a>, <a class="link" href="#cv-DVIPDFFLAGS"><code class="envar">$DVIPDFFLAGS</code></a>.</p><p>Uses: <a class="link" href="#cv-DVIPDFCOMSTR"><code class="envar">$DVIPDFCOMSTR</code></a>.</p></dd><dt><a name="t-dvips"></a><span class="term">dvips</span></dt><dd><p>
|
|
Sets construction variables for the dvips utility.
|
|
</p><p>Sets: <a class="link" href="#cv-DVIPS"><code class="envar">$DVIPS</code></a>, <a class="link" href="#cv-DVIPSFLAGS"><code class="envar">$DVIPSFLAGS</code></a>, <a class="link" href="#cv-PSCOM"><code class="envar">$PSCOM</code></a>, <a class="link" href="#cv-PSPREFIX"><code class="envar">$PSPREFIX</code></a>, <a class="link" href="#cv-PSSUFFIX"><code class="envar">$PSSUFFIX</code></a>.</p><p>Uses: <a class="link" href="#cv-PSCOMSTR"><code class="envar">$PSCOMSTR</code></a>.</p></dd><dt><a name="t-f03"></a><span class="term">f03</span></dt><dd><p>
|
|
Set construction variables for generic POSIX Fortran 03 compilers.
|
|
</p><p>Sets: <a class="link" href="#cv-F03"><code class="envar">$F03</code></a>, <a class="link" href="#cv-F03COM"><code class="envar">$F03COM</code></a>, <a class="link" href="#cv-F03FLAGS"><code class="envar">$F03FLAGS</code></a>, <a class="link" href="#cv-F03PPCOM"><code class="envar">$F03PPCOM</code></a>, <a class="link" href="#cv-SHF03"><code class="envar">$SHF03</code></a>, <a class="link" href="#cv-SHF03COM"><code class="envar">$SHF03COM</code></a>, <a class="link" href="#cv-SHF03FLAGS"><code class="envar">$SHF03FLAGS</code></a>, <a class="link" href="#cv-SHF03PPCOM"><code class="envar">$SHF03PPCOM</code></a>, <a class="link" href="#cv-_F03INCFLAGS"><code class="envar">$_F03INCFLAGS</code></a>.</p><p>Uses: <a class="link" href="#cv-F03COMSTR"><code class="envar">$F03COMSTR</code></a>, <a class="link" href="#cv-F03PPCOMSTR"><code class="envar">$F03PPCOMSTR</code></a>, <a class="link" href="#cv-SHF03COMSTR"><code class="envar">$SHF03COMSTR</code></a>, <a class="link" href="#cv-SHF03PPCOMSTR"><code class="envar">$SHF03PPCOMSTR</code></a>.</p></dd><dt><a name="t-f08"></a><span class="term">f08</span></dt><dd><p>
|
|
Set construction variables for generic POSIX Fortran 08 compilers.
|
|
</p><p>Sets: <a class="link" href="#cv-F08"><code class="envar">$F08</code></a>, <a class="link" href="#cv-F08COM"><code class="envar">$F08COM</code></a>, <a class="link" href="#cv-F08FLAGS"><code class="envar">$F08FLAGS</code></a>, <a class="link" href="#cv-F08PPCOM"><code class="envar">$F08PPCOM</code></a>, <a class="link" href="#cv-SHF08"><code class="envar">$SHF08</code></a>, <a class="link" href="#cv-SHF08COM"><code class="envar">$SHF08COM</code></a>, <a class="link" href="#cv-SHF08FLAGS"><code class="envar">$SHF08FLAGS</code></a>, <a class="link" href="#cv-SHF08PPCOM"><code class="envar">$SHF08PPCOM</code></a>, <a class="link" href="#cv-_F08INCFLAGS"><code class="envar">$_F08INCFLAGS</code></a>.</p><p>Uses: <a class="link" href="#cv-F08COMSTR"><code class="envar">$F08COMSTR</code></a>, <a class="link" href="#cv-F08PPCOMSTR"><code class="envar">$F08PPCOMSTR</code></a>, <a class="link" href="#cv-SHF08COMSTR"><code class="envar">$SHF08COMSTR</code></a>, <a class="link" href="#cv-SHF08PPCOMSTR"><code class="envar">$SHF08PPCOMSTR</code></a>.</p></dd><dt><a name="t-f77"></a><span class="term">f77</span></dt><dd><p>
|
|
Set construction variables for generic POSIX Fortran 77 compilers.
|
|
</p><p>Sets: <a class="link" href="#cv-F77"><code class="envar">$F77</code></a>, <a class="link" href="#cv-F77COM"><code class="envar">$F77COM</code></a>, <a class="link" href="#cv-F77FILESUFFIXES"><code class="envar">$F77FILESUFFIXES</code></a>, <a class="link" href="#cv-F77FLAGS"><code class="envar">$F77FLAGS</code></a>, <a class="link" href="#cv-F77PPCOM"><code class="envar">$F77PPCOM</code></a>, <a class="link" href="#cv-F77PPFILESUFFIXES"><code class="envar">$F77PPFILESUFFIXES</code></a>, <a class="link" href="#cv-FORTRAN"><code class="envar">$FORTRAN</code></a>, <a class="link" href="#cv-FORTRANCOM"><code class="envar">$FORTRANCOM</code></a>, <a class="link" href="#cv-FORTRANFLAGS"><code class="envar">$FORTRANFLAGS</code></a>, <a class="link" href="#cv-SHF77"><code class="envar">$SHF77</code></a>, <a class="link" href="#cv-SHF77COM"><code class="envar">$SHF77COM</code></a>, <a class="link" href="#cv-SHF77FLAGS"><code class="envar">$SHF77FLAGS</code></a>, <a class="link" href="#cv-SHF77PPCOM"><code class="envar">$SHF77PPCOM</code></a>, <a class="link" href="#cv-SHFORTRAN"><code class="envar">$SHFORTRAN</code></a>, <a class="link" href="#cv-SHFORTRANCOM"><code class="envar">$SHFORTRANCOM</code></a>, <a class="link" href="#cv-SHFORTRANFLAGS"><code class="envar">$SHFORTRANFLAGS</code></a>, <a class="link" href="#cv-SHFORTRANPPCOM"><code class="envar">$SHFORTRANPPCOM</code></a>, <a class="link" href="#cv-_F77INCFLAGS"><code class="envar">$_F77INCFLAGS</code></a>.</p><p>Uses: <a class="link" href="#cv-F77COMSTR"><code class="envar">$F77COMSTR</code></a>, <a class="link" href="#cv-F77PPCOMSTR"><code class="envar">$F77PPCOMSTR</code></a>, <a class="link" href="#cv-FORTRANCOMSTR"><code class="envar">$FORTRANCOMSTR</code></a>, <a class="link" href="#cv-FORTRANPPCOMSTR"><code class="envar">$FORTRANPPCOMSTR</code></a>, <a class="link" href="#cv-SHF77COMSTR"><code class="envar">$SHF77COMSTR</code></a>, <a class="link" href="#cv-SHF77PPCOMSTR"><code class="envar">$SHF77PPCOMSTR</code></a>, <a class="link" href="#cv-SHFORTRANCOMSTR"><code class="envar">$SHFORTRANCOMSTR</code></a>, <a class="link" href="#cv-SHFORTRANPPCOMSTR"><code class="envar">$SHFORTRANPPCOMSTR</code></a>.</p></dd><dt><a name="t-f90"></a><span class="term">f90</span></dt><dd><p>
|
|
Set construction variables for generic POSIX Fortran 90 compilers.
|
|
</p><p>Sets: <a class="link" href="#cv-F90"><code class="envar">$F90</code></a>, <a class="link" href="#cv-F90COM"><code class="envar">$F90COM</code></a>, <a class="link" href="#cv-F90FLAGS"><code class="envar">$F90FLAGS</code></a>, <a class="link" href="#cv-F90PPCOM"><code class="envar">$F90PPCOM</code></a>, <a class="link" href="#cv-SHF90"><code class="envar">$SHF90</code></a>, <a class="link" href="#cv-SHF90COM"><code class="envar">$SHF90COM</code></a>, <a class="link" href="#cv-SHF90FLAGS"><code class="envar">$SHF90FLAGS</code></a>, <a class="link" href="#cv-SHF90PPCOM"><code class="envar">$SHF90PPCOM</code></a>, <a class="link" href="#cv-_F90INCFLAGS"><code class="envar">$_F90INCFLAGS</code></a>.</p><p>Uses: <a class="link" href="#cv-F90COMSTR"><code class="envar">$F90COMSTR</code></a>, <a class="link" href="#cv-F90PPCOMSTR"><code class="envar">$F90PPCOMSTR</code></a>, <a class="link" href="#cv-SHF90COMSTR"><code class="envar">$SHF90COMSTR</code></a>, <a class="link" href="#cv-SHF90PPCOMSTR"><code class="envar">$SHF90PPCOMSTR</code></a>.</p></dd><dt><a name="t-f95"></a><span class="term">f95</span></dt><dd><p>
|
|
Set construction variables for generic POSIX Fortran 95 compilers.
|
|
</p><p>Sets: <a class="link" href="#cv-F95"><code class="envar">$F95</code></a>, <a class="link" href="#cv-F95COM"><code class="envar">$F95COM</code></a>, <a class="link" href="#cv-F95FLAGS"><code class="envar">$F95FLAGS</code></a>, <a class="link" href="#cv-F95PPCOM"><code class="envar">$F95PPCOM</code></a>, <a class="link" href="#cv-SHF95"><code class="envar">$SHF95</code></a>, <a class="link" href="#cv-SHF95COM"><code class="envar">$SHF95COM</code></a>, <a class="link" href="#cv-SHF95FLAGS"><code class="envar">$SHF95FLAGS</code></a>, <a class="link" href="#cv-SHF95PPCOM"><code class="envar">$SHF95PPCOM</code></a>, <a class="link" href="#cv-_F95INCFLAGS"><code class="envar">$_F95INCFLAGS</code></a>.</p><p>Uses: <a class="link" href="#cv-F95COMSTR"><code class="envar">$F95COMSTR</code></a>, <a class="link" href="#cv-F95PPCOMSTR"><code class="envar">$F95PPCOMSTR</code></a>, <a class="link" href="#cv-SHF95COMSTR"><code class="envar">$SHF95COMSTR</code></a>, <a class="link" href="#cv-SHF95PPCOMSTR"><code class="envar">$SHF95PPCOMSTR</code></a>.</p></dd><dt><a name="t-fortran"></a><span class="term">fortran</span></dt><dd><p>
|
|
Set construction variables for generic POSIX Fortran compilers.
|
|
</p><p>Sets: <a class="link" href="#cv-FORTRAN"><code class="envar">$FORTRAN</code></a>, <a class="link" href="#cv-FORTRANCOM"><code class="envar">$FORTRANCOM</code></a>, <a class="link" href="#cv-FORTRANFLAGS"><code class="envar">$FORTRANFLAGS</code></a>, <a class="link" href="#cv-SHFORTRAN"><code class="envar">$SHFORTRAN</code></a>, <a class="link" href="#cv-SHFORTRANCOM"><code class="envar">$SHFORTRANCOM</code></a>, <a class="link" href="#cv-SHFORTRANFLAGS"><code class="envar">$SHFORTRANFLAGS</code></a>, <a class="link" href="#cv-SHFORTRANPPCOM"><code class="envar">$SHFORTRANPPCOM</code></a>.</p><p>Uses: <a class="link" href="#cv-FORTRANCOMSTR"><code class="envar">$FORTRANCOMSTR</code></a>, <a class="link" href="#cv-FORTRANPPCOMSTR"><code class="envar">$FORTRANPPCOMSTR</code></a>, <a class="link" href="#cv-SHFORTRANCOMSTR"><code class="envar">$SHFORTRANCOMSTR</code></a>, <a class="link" href="#cv-SHFORTRANPPCOMSTR"><code class="envar">$SHFORTRANPPCOMSTR</code></a>.</p></dd><dt><a name="t-gXX"></a><span class="term">g++</span></dt><dd><p>
|
|
Set construction variables for the <span class="application">gXX</span> C++ compiler.
|
|
</p><p>Sets: <a class="link" href="#cv-CXX"><code class="envar">$CXX</code></a>, <a class="link" href="#cv-CXXVERSION"><code class="envar">$CXXVERSION</code></a>, <a class="link" href="#cv-SHCXXFLAGS"><code class="envar">$SHCXXFLAGS</code></a>, <a class="link" href="#cv-SHOBJSUFFIX"><code class="envar">$SHOBJSUFFIX</code></a>.</p></dd><dt><a name="t-g77"></a><span class="term">g77</span></dt><dd><p>
|
|
Set construction variables for the <span class="application">g77</span> Fortran compiler.
|
|
Calls the <code class="literal">f77</code> Tool module
|
|
to set variables.
|
|
</p></dd><dt><a name="t-gas"></a><span class="term">gas</span></dt><dd><p>
|
|
Sets construction variables for the <span class="application">gas</span> assembler.
|
|
Calls the <code class="literal">as</code> module.
|
|
</p><p>Sets: <a class="link" href="#cv-AS"><code class="envar">$AS</code></a>.</p></dd><dt><a name="t-gcc"></a><span class="term">gcc</span></dt><dd><p>
|
|
Set construction variables for the <span class="application">gcc</span> C compiler.
|
|
</p><p>Sets: <a class="link" href="#cv-CC"><code class="envar">$CC</code></a>, <a class="link" href="#cv-CCVERSION"><code class="envar">$CCVERSION</code></a>, <a class="link" href="#cv-SHCCFLAGS"><code class="envar">$SHCCFLAGS</code></a>.</p></dd><dt><a name="t-gdc"></a><span class="term">gdc</span></dt><dd><p>
|
|
Sets construction variables for the D language compiler GDC.
|
|
</p><p>Sets: <a class="link" href="#cv-DC"><code class="envar">$DC</code></a>, <a class="link" href="#cv-DCOM"><code class="envar">$DCOM</code></a>, <a class="link" href="#cv-DDEBUG"><code class="envar">$DDEBUG</code></a>, <a class="link" href="#cv-DDEBUGPREFIX"><code class="envar">$DDEBUGPREFIX</code></a>, <a class="link" href="#cv-DDEBUGSUFFIX"><code class="envar">$DDEBUGSUFFIX</code></a>, <a class="link" href="#cv-DFILESUFFIX"><code class="envar">$DFILESUFFIX</code></a>, <a class="link" href="#cv-DFLAGPREFIX"><code class="envar">$DFLAGPREFIX</code></a>, <a class="link" href="#cv-DFLAGS"><code class="envar">$DFLAGS</code></a>, <a class="link" href="#cv-DFLAGSUFFIX"><code class="envar">$DFLAGSUFFIX</code></a>, <a class="link" href="#cv-DINCPREFIX"><code class="envar">$DINCPREFIX</code></a>, <a class="link" href="#cv-DINCSUFFIX"><code class="envar">$DINCSUFFIX</code></a>, <a class="link" href="#cv-DLIB"><code class="envar">$DLIB</code></a>, <a class="link" href="#cv-DLIBCOM"><code class="envar">$DLIBCOM</code></a>, <a class="link" href="#cv-DLIBDIRPREFIX"><code class="envar">$DLIBDIRPREFIX</code></a>, <a class="link" href="#cv-DLIBDIRSUFFIX"><code class="envar">$DLIBDIRSUFFIX</code></a>, <a class="link" href="#cv-DLIBFLAGPREFIX"><code class="envar">$DLIBFLAGPREFIX</code></a>, <a class="link" href="#cv-DLIBFLAGSUFFIX"><code class="envar">$DLIBFLAGSUFFIX</code></a>, <a class="link" href="#cv-DLIBLINKPREFIX"><code class="envar">$DLIBLINKPREFIX</code></a>, <a class="link" href="#cv-DLIBLINKSUFFIX"><code class="envar">$DLIBLINKSUFFIX</code></a>, <a class="link" href="#cv-DLINK"><code class="envar">$DLINK</code></a>, <a class="link" href="#cv-DLINKCOM"><code class="envar">$DLINKCOM</code></a>, <a class="link" href="#cv-DLINKFLAGPREFIX"><code class="envar">$DLINKFLAGPREFIX</code></a>, <a class="link" href="#cv-DLINKFLAGS"><code class="envar">$DLINKFLAGS</code></a>, <a class="link" href="#cv-DLINKFLAGSUFFIX"><code class="envar">$DLINKFLAGSUFFIX</code></a>, <a class="link" href="#cv-DPATH"><code class="envar">$DPATH</code></a>, <a class="link" href="#cv-DRPATHPREFIX"><code class="envar">$DRPATHPREFIX</code></a>, <a class="link" href="#cv-DRPATHSUFFIX"><code class="envar">$DRPATHSUFFIX</code></a>, <a class="link" href="#cv-DShLibSonameGenerator"><code class="envar">$DShLibSonameGenerator</code></a>, <a class="link" href="#cv-DVERPREFIX"><code class="envar">$DVERPREFIX</code></a>, <a class="link" href="#cv-DVERSIONS"><code class="envar">$DVERSIONS</code></a>, <a class="link" href="#cv-DVERSUFFIX"><code class="envar">$DVERSUFFIX</code></a>, <a class="link" href="#cv-SHDC"><code class="envar">$SHDC</code></a>, <a class="link" href="#cv-SHDCOM"><code class="envar">$SHDCOM</code></a>, <a class="link" href="#cv-SHDLIBVERSION"><code class="envar">$SHDLIBVERSION</code></a>, <a class="link" href="#cv-SHDLIBVERSIONFLAGS"><code class="envar">$SHDLIBVERSIONFLAGS</code></a>, <a class="link" href="#cv-SHDLINK"><code class="envar">$SHDLINK</code></a>, <a class="link" href="#cv-SHDLINKCOM"><code class="envar">$SHDLINKCOM</code></a>, <a class="link" href="#cv-SHDLINKFLAGS"><code class="envar">$SHDLINKFLAGS</code></a>.</p></dd><dt><a name="t-gettext"></a><span class="term">gettext</span></dt><dd><p>
|
|
This is actually a toolset, which supports internationalization and
|
|
localization of software being constructed with SCons. The toolset loads
|
|
following tools:
|
|
</p><p>
|
|
</p><div class="itemizedlist"><ul class="itemizedlist" type="opencircle"><li class="listitem" style="list-style-type: circle"><p>
|
|
<a class="link" href="#t-xgettext"><code class="literal">xgettext</code></a> - to extract internationalized messages from source code to
|
|
<code class="literal">POT</code> file(s),
|
|
</p></li><li class="listitem" style="list-style-type: circle"><p>
|
|
<a class="link" href="#t-msginit"><code class="literal">msginit</code></a> - may be optionally used to initialize <code class="literal">PO</code>
|
|
files,
|
|
</p></li><li class="listitem" style="list-style-type: circle"><p>
|
|
<a class="link" href="#t-msgmerge"><code class="literal">msgmerge</code></a> - to update <code class="literal">PO</code> files, that already contain
|
|
translated messages,</p></li><li class="listitem" style="list-style-type: circle"><p>
|
|
<a class="link" href="#t-msgfmt"><code class="literal">msgfmt</code></a> - to compile textual <code class="literal">PO</code> file to binary
|
|
installable <code class="literal">MO</code> file.
|
|
</p></li></ul></div><p>
|
|
</p><p>
|
|
When you enable <code class="literal">gettext</code>, it internally loads all abovementioned tools,
|
|
so you're encouraged to see their individual documentation.
|
|
</p><p>
|
|
Each of the above tools provides its own builder(s) which may be used to
|
|
perform particular activities related to software internationalization. You
|
|
may be however interested in <span class="emphasis"><em>top-level</em></span> builder
|
|
<code class="function">Translate</code> described few paragraphs later.
|
|
</p><p>
|
|
To use <code class="literal">gettext</code> tools add <code class="literal">'gettext'</code> tool to your
|
|
environment:
|
|
</p><pre class="screen">
|
|
env = Environment( tools = ['default', 'gettext'] )
|
|
</pre></dd><dt><a name="t-gfortran"></a><span class="term">gfortran</span></dt><dd><p>
|
|
Sets construction variables for the GNU F95/F2003 GNU compiler.
|
|
</p><p>Sets: <a class="link" href="#cv-F77"><code class="envar">$F77</code></a>, <a class="link" href="#cv-F90"><code class="envar">$F90</code></a>, <a class="link" href="#cv-F95"><code class="envar">$F95</code></a>, <a class="link" href="#cv-FORTRAN"><code class="envar">$FORTRAN</code></a>, <a class="link" href="#cv-SHF77"><code class="envar">$SHF77</code></a>, <a class="link" href="#cv-SHF77FLAGS"><code class="envar">$SHF77FLAGS</code></a>, <a class="link" href="#cv-SHF90"><code class="envar">$SHF90</code></a>, <a class="link" href="#cv-SHF90FLAGS"><code class="envar">$SHF90FLAGS</code></a>, <a class="link" href="#cv-SHF95"><code class="envar">$SHF95</code></a>, <a class="link" href="#cv-SHF95FLAGS"><code class="envar">$SHF95FLAGS</code></a>, <a class="link" href="#cv-SHFORTRAN"><code class="envar">$SHFORTRAN</code></a>, <a class="link" href="#cv-SHFORTRANFLAGS"><code class="envar">$SHFORTRANFLAGS</code></a>.</p></dd><dt><a name="t-gnulink"></a><span class="term">gnulink</span></dt><dd><p>
|
|
Set construction variables for GNU linker/loader.
|
|
</p><p>Sets: <a class="link" href="#cv-LDMODULEVERSIONFLAGS"><code class="envar">$LDMODULEVERSIONFLAGS</code></a>, <a class="link" href="#cv-RPATHPREFIX"><code class="envar">$RPATHPREFIX</code></a>, <a class="link" href="#cv-RPATHSUFFIX"><code class="envar">$RPATHSUFFIX</code></a>, <a class="link" href="#cv-SHLIBVERSIONFLAGS"><code class="envar">$SHLIBVERSIONFLAGS</code></a>, <a class="link" href="#cv-SHLINKFLAGS"><code class="envar">$SHLINKFLAGS</code></a>, <a class="link" href="#cv-_LDMODULESONAME"><code class="envar">$_LDMODULESONAME</code></a>, <a class="link" href="#cv-_SHLIBSONAME"><code class="envar">$_SHLIBSONAME</code></a>.</p></dd><dt><a name="t-gs"></a><span class="term">gs</span></dt><dd><p>
|
|
This Tool sets the required construction variables for working with
|
|
the Ghostscript command. It also registers an appropriate Action
|
|
with the PDF Builder (<a class="link" href="#b-PDF"><code class="function">PDF</code></a>), such that the conversion from
|
|
PS/EPS to PDF happens automatically for the TeX/LaTeX toolchain.
|
|
Finally, it adds an explicit Ghostscript Builder (<a class="link" href="#b-Gs"><code class="function">Gs</code></a>) to the
|
|
environment.
|
|
</p><p>Sets: <a class="link" href="#cv-GS"><code class="envar">$GS</code></a>, <a class="link" href="#cv-GSCOM"><code class="envar">$GSCOM</code></a>, <a class="link" href="#cv-GSFLAGS"><code class="envar">$GSFLAGS</code></a>.</p><p>Uses: <a class="link" href="#cv-GSCOMSTR"><code class="envar">$GSCOMSTR</code></a>.</p></dd><dt><a name="t-hpcXX"></a><span class="term">hpc++</span></dt><dd><p>
|
|
Set construction variables for the compilers aCC on HP/UX systems.
|
|
</p></dd><dt><a name="t-hpcc"></a><span class="term">hpcc</span></dt><dd><p>
|
|
Set construction variables for the
|
|
<span class="application">aCC</span> on HP/UX systems.
|
|
Calls the <code class="literal">cXX</code> tool for additional variables.
|
|
</p><p>Sets: <a class="link" href="#cv-CXX"><code class="envar">$CXX</code></a>, <a class="link" href="#cv-CXXVERSION"><code class="envar">$CXXVERSION</code></a>, <a class="link" href="#cv-SHCXXFLAGS"><code class="envar">$SHCXXFLAGS</code></a>.</p></dd><dt><a name="t-hplink"></a><span class="term">hplink</span></dt><dd><p>
|
|
Sets construction variables for the linker on HP/UX systems.
|
|
</p><p>Sets: <a class="link" href="#cv-LINKFLAGS"><code class="envar">$LINKFLAGS</code></a>, <a class="link" href="#cv-SHLIBSUFFIX"><code class="envar">$SHLIBSUFFIX</code></a>, <a class="link" href="#cv-SHLINKFLAGS"><code class="envar">$SHLINKFLAGS</code></a>.</p></dd><dt><a name="t-icc"></a><span class="term">icc</span></dt><dd><p>
|
|
Sets construction variables for the
|
|
<span class="application">icc</span> compiler on OS/2 systems.
|
|
</p><p>Sets: <a class="link" href="#cv-CC"><code class="envar">$CC</code></a>, <a class="link" href="#cv-CCCOM"><code class="envar">$CCCOM</code></a>, <a class="link" href="#cv-CFILESUFFIX"><code class="envar">$CFILESUFFIX</code></a>, <a class="link" href="#cv-CPPDEFPREFIX"><code class="envar">$CPPDEFPREFIX</code></a>, <a class="link" href="#cv-CPPDEFSUFFIX"><code class="envar">$CPPDEFSUFFIX</code></a>, <a class="link" href="#cv-CXXCOM"><code class="envar">$CXXCOM</code></a>, <a class="link" href="#cv-CXXFILESUFFIX"><code class="envar">$CXXFILESUFFIX</code></a>, <a class="link" href="#cv-INCPREFIX"><code class="envar">$INCPREFIX</code></a>, <a class="link" href="#cv-INCSUFFIX"><code class="envar">$INCSUFFIX</code></a>.</p><p>Uses: <a class="link" href="#cv-CCFLAGS"><code class="envar">$CCFLAGS</code></a>, <a class="link" href="#cv-CFLAGS"><code class="envar">$CFLAGS</code></a>, <a class="link" href="#cv-CPPFLAGS"><code class="envar">$CPPFLAGS</code></a>, <a class="link" href="#cv-_CPPDEFFLAGS"><code class="envar">$_CPPDEFFLAGS</code></a>, <a class="link" href="#cv-_CPPINCFLAGS"><code class="envar">$_CPPINCFLAGS</code></a>.</p></dd><dt><a name="t-icl"></a><span class="term">icl</span></dt><dd><p>
|
|
Sets construction variables for the Intel C/C++ compiler.
|
|
Calls the <code class="literal">intelc</code> Tool module to set its variables.
|
|
</p></dd><dt><a name="t-ifl"></a><span class="term">ifl</span></dt><dd><p>
|
|
Sets construction variables for the Intel Fortran compiler.
|
|
</p><p>Sets: <a class="link" href="#cv-FORTRAN"><code class="envar">$FORTRAN</code></a>, <a class="link" href="#cv-FORTRANCOM"><code class="envar">$FORTRANCOM</code></a>, <a class="link" href="#cv-FORTRANPPCOM"><code class="envar">$FORTRANPPCOM</code></a>, <a class="link" href="#cv-SHFORTRANCOM"><code class="envar">$SHFORTRANCOM</code></a>, <a class="link" href="#cv-SHFORTRANPPCOM"><code class="envar">$SHFORTRANPPCOM</code></a>.</p><p>Uses: <a class="link" href="#cv-CPPFLAGS"><code class="envar">$CPPFLAGS</code></a>, <a class="link" href="#cv-FORTRANFLAGS"><code class="envar">$FORTRANFLAGS</code></a>, <a class="link" href="#cv-_CPPDEFFLAGS"><code class="envar">$_CPPDEFFLAGS</code></a>, <a class="link" href="#cv-_FORTRANINCFLAGS"><code class="envar">$_FORTRANINCFLAGS</code></a>.</p></dd><dt><a name="t-ifort"></a><span class="term">ifort</span></dt><dd><p>
|
|
Sets construction variables for newer versions
|
|
of the Intel Fortran compiler for Linux.
|
|
</p><p>Sets: <a class="link" href="#cv-F77"><code class="envar">$F77</code></a>, <a class="link" href="#cv-F90"><code class="envar">$F90</code></a>, <a class="link" href="#cv-F95"><code class="envar">$F95</code></a>, <a class="link" href="#cv-FORTRAN"><code class="envar">$FORTRAN</code></a>, <a class="link" href="#cv-SHF77"><code class="envar">$SHF77</code></a>, <a class="link" href="#cv-SHF77FLAGS"><code class="envar">$SHF77FLAGS</code></a>, <a class="link" href="#cv-SHF90"><code class="envar">$SHF90</code></a>, <a class="link" href="#cv-SHF90FLAGS"><code class="envar">$SHF90FLAGS</code></a>, <a class="link" href="#cv-SHF95"><code class="envar">$SHF95</code></a>, <a class="link" href="#cv-SHF95FLAGS"><code class="envar">$SHF95FLAGS</code></a>, <a class="link" href="#cv-SHFORTRAN"><code class="envar">$SHFORTRAN</code></a>, <a class="link" href="#cv-SHFORTRANFLAGS"><code class="envar">$SHFORTRANFLAGS</code></a>.</p></dd><dt><a name="t-ilink"></a><span class="term">ilink</span></dt><dd><p>
|
|
Sets construction variables for the
|
|
<span class="application">ilink</span> linker on OS/2 systems.
|
|
</p><p>Sets: <a class="link" href="#cv-LIBDIRPREFIX"><code class="envar">$LIBDIRPREFIX</code></a>, <a class="link" href="#cv-LIBDIRSUFFIX"><code class="envar">$LIBDIRSUFFIX</code></a>, <a class="link" href="#cv-LIBLINKPREFIX"><code class="envar">$LIBLINKPREFIX</code></a>, <a class="link" href="#cv-LIBLINKSUFFIX"><code class="envar">$LIBLINKSUFFIX</code></a>, <a class="link" href="#cv-LINK"><code class="envar">$LINK</code></a>, <a class="link" href="#cv-LINKCOM"><code class="envar">$LINKCOM</code></a>, <a class="link" href="#cv-LINKFLAGS"><code class="envar">$LINKFLAGS</code></a>.</p></dd><dt><a name="t-ilink32"></a><span class="term">ilink32</span></dt><dd><p>
|
|
Sets construction variables for the Borland
|
|
<span class="application">ilink32</span> linker.
|
|
</p><p>Sets: <a class="link" href="#cv-LIBDIRPREFIX"><code class="envar">$LIBDIRPREFIX</code></a>, <a class="link" href="#cv-LIBDIRSUFFIX"><code class="envar">$LIBDIRSUFFIX</code></a>, <a class="link" href="#cv-LIBLINKPREFIX"><code class="envar">$LIBLINKPREFIX</code></a>, <a class="link" href="#cv-LIBLINKSUFFIX"><code class="envar">$LIBLINKSUFFIX</code></a>, <a class="link" href="#cv-LINK"><code class="envar">$LINK</code></a>, <a class="link" href="#cv-LINKCOM"><code class="envar">$LINKCOM</code></a>, <a class="link" href="#cv-LINKFLAGS"><code class="envar">$LINKFLAGS</code></a>.</p></dd><dt><a name="t-install"></a><span class="term">install</span></dt><dd><p>
|
|
Sets construction variables for file
|
|
and directory installation.
|
|
</p><p>Sets: <a class="link" href="#cv-INSTALL"><code class="envar">$INSTALL</code></a>, <a class="link" href="#cv-INSTALLSTR"><code class="envar">$INSTALLSTR</code></a>.</p></dd><dt><a name="t-intelc"></a><span class="term">intelc</span></dt><dd><p>
|
|
Sets construction variables for the Intel C/C++ compiler
|
|
(Linux and Windows, version 7 and later).
|
|
Calls the <code class="literal">gcc</code> or <code class="literal">msvc</code>
|
|
(on Linux and Windows, respectively)
|
|
to set underlying variables.
|
|
</p><p>Sets: <a class="link" href="#cv-AR"><code class="envar">$AR</code></a>, <a class="link" href="#cv-CC"><code class="envar">$CC</code></a>, <a class="link" href="#cv-CXX"><code class="envar">$CXX</code></a>, <a class="link" href="#cv-INTEL_C_COMPILER_VERSION"><code class="envar">$INTEL_C_COMPILER_VERSION</code></a>, <a class="link" href="#cv-LINK"><code class="envar">$LINK</code></a>.</p></dd><dt><a name="t-jar"></a><span class="term">jar</span></dt><dd><p>
|
|
Sets construction variables for the <span class="application">jar</span> utility.
|
|
</p><p>Sets: <a class="link" href="#cv-JAR"><code class="envar">$JAR</code></a>, <a class="link" href="#cv-JARCOM"><code class="envar">$JARCOM</code></a>, <a class="link" href="#cv-JARFLAGS"><code class="envar">$JARFLAGS</code></a>, <a class="link" href="#cv-JARSUFFIX"><code class="envar">$JARSUFFIX</code></a>.</p><p>Uses: <a class="link" href="#cv-JARCOMSTR"><code class="envar">$JARCOMSTR</code></a>.</p></dd><dt><a name="t-javac"></a><span class="term">javac</span></dt><dd><p>
|
|
Sets construction variables for the <span class="application">javac</span> compiler.
|
|
</p><p>Sets: <a class="link" href="#cv-JAVABOOTCLASSPATH"><code class="envar">$JAVABOOTCLASSPATH</code></a>, <a class="link" href="#cv-JAVAC"><code class="envar">$JAVAC</code></a>, <a class="link" href="#cv-JAVACCOM"><code class="envar">$JAVACCOM</code></a>, <a class="link" href="#cv-JAVACFLAGS"><code class="envar">$JAVACFLAGS</code></a>, <a class="link" href="#cv-JAVACLASSPATH"><code class="envar">$JAVACLASSPATH</code></a>, <a class="link" href="#cv-JAVACLASSSUFFIX"><code class="envar">$JAVACLASSSUFFIX</code></a>, <a class="link" href="#cv-JAVAINCLUDES"><code class="envar">$JAVAINCLUDES</code></a>, <a class="link" href="#cv-JAVASOURCEPATH"><code class="envar">$JAVASOURCEPATH</code></a>, <a class="link" href="#cv-JAVASUFFIX"><code class="envar">$JAVASUFFIX</code></a>.</p><p>Uses: <a class="link" href="#cv-JAVACCOMSTR"><code class="envar">$JAVACCOMSTR</code></a>.</p></dd><dt><a name="t-javah"></a><span class="term">javah</span></dt><dd><p>
|
|
Sets construction variables for the <span class="application">javah</span> tool.
|
|
</p><p>Sets: <a class="link" href="#cv-JAVACLASSSUFFIX"><code class="envar">$JAVACLASSSUFFIX</code></a>, <a class="link" href="#cv-JAVAH"><code class="envar">$JAVAH</code></a>, <a class="link" href="#cv-JAVAHCOM"><code class="envar">$JAVAHCOM</code></a>, <a class="link" href="#cv-JAVAHFLAGS"><code class="envar">$JAVAHFLAGS</code></a>.</p><p>Uses: <a class="link" href="#cv-JAVACLASSPATH"><code class="envar">$JAVACLASSPATH</code></a>, <a class="link" href="#cv-JAVAHCOMSTR"><code class="envar">$JAVAHCOMSTR</code></a>.</p></dd><dt><a name="t-latex"></a><span class="term">latex</span></dt><dd><p>
|
|
Sets construction variables for the <span class="application">latex</span> utility.
|
|
</p><p>Sets: <a class="link" href="#cv-LATEX"><code class="envar">$LATEX</code></a>, <a class="link" href="#cv-LATEXCOM"><code class="envar">$LATEXCOM</code></a>, <a class="link" href="#cv-LATEXFLAGS"><code class="envar">$LATEXFLAGS</code></a>.</p><p>Uses: <a class="link" href="#cv-LATEXCOMSTR"><code class="envar">$LATEXCOMSTR</code></a>.</p></dd><dt><a name="t-ldc"></a><span class="term">ldc</span></dt><dd><p>
|
|
Sets construction variables for the D language compiler LDC2.
|
|
</p><p>Sets: <a class="link" href="#cv-DC"><code class="envar">$DC</code></a>, <a class="link" href="#cv-DCOM"><code class="envar">$DCOM</code></a>, <a class="link" href="#cv-DDEBUG"><code class="envar">$DDEBUG</code></a>, <a class="link" href="#cv-DDEBUGPREFIX"><code class="envar">$DDEBUGPREFIX</code></a>, <a class="link" href="#cv-DDEBUGSUFFIX"><code class="envar">$DDEBUGSUFFIX</code></a>, <a class="link" href="#cv-DFILESUFFIX"><code class="envar">$DFILESUFFIX</code></a>, <a class="link" href="#cv-DFLAGPREFIX"><code class="envar">$DFLAGPREFIX</code></a>, <a class="link" href="#cv-DFLAGS"><code class="envar">$DFLAGS</code></a>, <a class="link" href="#cv-DFLAGSUFFIX"><code class="envar">$DFLAGSUFFIX</code></a>, <a class="link" href="#cv-DINCPREFIX"><code class="envar">$DINCPREFIX</code></a>, <a class="link" href="#cv-DINCSUFFIX"><code class="envar">$DINCSUFFIX</code></a>, <a class="link" href="#cv-DLIB"><code class="envar">$DLIB</code></a>, <a class="link" href="#cv-DLIBCOM"><code class="envar">$DLIBCOM</code></a>, <a class="link" href="#cv-DLIBDIRPREFIX"><code class="envar">$DLIBDIRPREFIX</code></a>, <a class="link" href="#cv-DLIBDIRSUFFIX"><code class="envar">$DLIBDIRSUFFIX</code></a>, <a class="link" href="#cv-DLIBFLAGPREFIX"><code class="envar">$DLIBFLAGPREFIX</code></a>, <a class="link" href="#cv-DLIBFLAGSUFFIX"><code class="envar">$DLIBFLAGSUFFIX</code></a>, <a class="link" href="#cv-DLIBLINKPREFIX"><code class="envar">$DLIBLINKPREFIX</code></a>, <a class="link" href="#cv-DLIBLINKSUFFIX"><code class="envar">$DLIBLINKSUFFIX</code></a>, <a class="link" href="#cv-DLINK"><code class="envar">$DLINK</code></a>, <a class="link" href="#cv-DLINKCOM"><code class="envar">$DLINKCOM</code></a>, <a class="link" href="#cv-DLINKFLAGPREFIX"><code class="envar">$DLINKFLAGPREFIX</code></a>, <a class="link" href="#cv-DLINKFLAGS"><code class="envar">$DLINKFLAGS</code></a>, <a class="link" href="#cv-DLINKFLAGSUFFIX"><code class="envar">$DLINKFLAGSUFFIX</code></a>, <a class="link" href="#cv-DPATH"><code class="envar">$DPATH</code></a>, <a class="link" href="#cv-DRPATHPREFIX"><code class="envar">$DRPATHPREFIX</code></a>, <a class="link" href="#cv-DRPATHSUFFIX"><code class="envar">$DRPATHSUFFIX</code></a>, <a class="link" href="#cv-DShLibSonameGenerator"><code class="envar">$DShLibSonameGenerator</code></a>, <a class="link" href="#cv-DVERPREFIX"><code class="envar">$DVERPREFIX</code></a>, <a class="link" href="#cv-DVERSIONS"><code class="envar">$DVERSIONS</code></a>, <a class="link" href="#cv-DVERSUFFIX"><code class="envar">$DVERSUFFIX</code></a>, <a class="link" href="#cv-SHDC"><code class="envar">$SHDC</code></a>, <a class="link" href="#cv-SHDCOM"><code class="envar">$SHDCOM</code></a>, <a class="link" href="#cv-SHDLIBVERSION"><code class="envar">$SHDLIBVERSION</code></a>, <a class="link" href="#cv-SHDLIBVERSIONFLAGS"><code class="envar">$SHDLIBVERSIONFLAGS</code></a>, <a class="link" href="#cv-SHDLINK"><code class="envar">$SHDLINK</code></a>, <a class="link" href="#cv-SHDLINKCOM"><code class="envar">$SHDLINKCOM</code></a>, <a class="link" href="#cv-SHDLINKFLAGS"><code class="envar">$SHDLINKFLAGS</code></a>.</p></dd><dt><a name="t-lex"></a><span class="term">lex</span></dt><dd><p>
|
|
Sets construction variables for the <span class="application">lex</span> lexical analyser.
|
|
</p><p>Sets: <a class="link" href="#cv-LEX"><code class="envar">$LEX</code></a>, <a class="link" href="#cv-LEXCOM"><code class="envar">$LEXCOM</code></a>, <a class="link" href="#cv-LEXFLAGS"><code class="envar">$LEXFLAGS</code></a>.</p><p>Uses: <a class="link" href="#cv-LEXCOMSTR"><code class="envar">$LEXCOMSTR</code></a>.</p></dd><dt><a name="t-link"></a><span class="term">link</span></dt><dd><p>
|
|
Sets construction variables for generic POSIX linkers.
|
|
</p><p>Sets: <a class="link" href="#cv-LDMODULE"><code class="envar">$LDMODULE</code></a>, <a class="link" href="#cv-LDMODULECOM"><code class="envar">$LDMODULECOM</code></a>, <a class="link" href="#cv-LDMODULEFLAGS"><code class="envar">$LDMODULEFLAGS</code></a>, <a class="link" href="#cv-LDMODULENOVERSIONSYMLINKS"><code class="envar">$LDMODULENOVERSIONSYMLINKS</code></a>, <a class="link" href="#cv-LDMODULEPREFIX"><code class="envar">$LDMODULEPREFIX</code></a>, <a class="link" href="#cv-LDMODULESUFFIX"><code class="envar">$LDMODULESUFFIX</code></a>, <a class="link" href="#cv-LDMODULEVERSION"><code class="envar">$LDMODULEVERSION</code></a>, <a class="link" href="#cv-LDMODULEVERSIONFLAGS"><code class="envar">$LDMODULEVERSIONFLAGS</code></a>, <a class="link" href="#cv-LIBDIRPREFIX"><code class="envar">$LIBDIRPREFIX</code></a>, <a class="link" href="#cv-LIBDIRSUFFIX"><code class="envar">$LIBDIRSUFFIX</code></a>, <a class="link" href="#cv-LIBLINKPREFIX"><code class="envar">$LIBLINKPREFIX</code></a>, <a class="link" href="#cv-LIBLINKSUFFIX"><code class="envar">$LIBLINKSUFFIX</code></a>, <a class="link" href="#cv-LINK"><code class="envar">$LINK</code></a>, <a class="link" href="#cv-LINKCOM"><code class="envar">$LINKCOM</code></a>, <a class="link" href="#cv-LINKFLAGS"><code class="envar">$LINKFLAGS</code></a>, <a class="link" href="#cv-SHLIBSUFFIX"><code class="envar">$SHLIBSUFFIX</code></a>, <a class="link" href="#cv-SHLINK"><code class="envar">$SHLINK</code></a>, <a class="link" href="#cv-SHLINKCOM"><code class="envar">$SHLINKCOM</code></a>, <a class="link" href="#cv-SHLINKFLAGS"><code class="envar">$SHLINKFLAGS</code></a>, <a class="link" href="#cv-__LDMODULEVERSIONFLAGS"><code class="envar">$__LDMODULEVERSIONFLAGS</code></a>, <a class="link" href="#cv-__SHLIBVERSIONFLAGS"><code class="envar">$__SHLIBVERSIONFLAGS</code></a>.</p><p>Uses: <a class="link" href="#cv-LDMODULECOMSTR"><code class="envar">$LDMODULECOMSTR</code></a>, <a class="link" href="#cv-LINKCOMSTR"><code class="envar">$LINKCOMSTR</code></a>, <a class="link" href="#cv-SHLINKCOMSTR"><code class="envar">$SHLINKCOMSTR</code></a>.</p></dd><dt><a name="t-linkloc"></a><span class="term">linkloc</span></dt><dd><p>
|
|
Sets construction variables for the
|
|
<span class="application">LinkLoc</span>
|
|
linker for the Phar Lap ETS embedded operating system.
|
|
</p><p>Sets: <a class="link" href="#cv-LIBDIRPREFIX"><code class="envar">$LIBDIRPREFIX</code></a>, <a class="link" href="#cv-LIBDIRSUFFIX"><code class="envar">$LIBDIRSUFFIX</code></a>, <a class="link" href="#cv-LIBLINKPREFIX"><code class="envar">$LIBLINKPREFIX</code></a>, <a class="link" href="#cv-LIBLINKSUFFIX"><code class="envar">$LIBLINKSUFFIX</code></a>, <a class="link" href="#cv-LINK"><code class="envar">$LINK</code></a>, <a class="link" href="#cv-LINKCOM"><code class="envar">$LINKCOM</code></a>, <a class="link" href="#cv-LINKFLAGS"><code class="envar">$LINKFLAGS</code></a>, <a class="link" href="#cv-SHLINK"><code class="envar">$SHLINK</code></a>, <a class="link" href="#cv-SHLINKCOM"><code class="envar">$SHLINKCOM</code></a>, <a class="link" href="#cv-SHLINKFLAGS"><code class="envar">$SHLINKFLAGS</code></a>.</p><p>Uses: <a class="link" href="#cv-LINKCOMSTR"><code class="envar">$LINKCOMSTR</code></a>, <a class="link" href="#cv-SHLINKCOMSTR"><code class="envar">$SHLINKCOMSTR</code></a>.</p></dd><dt><a name="t-m4"></a><span class="term">m4</span></dt><dd><p>
|
|
Sets construction variables for the <span class="application">m4</span> macro processor.
|
|
</p><p>Sets: <a class="link" href="#cv-M4"><code class="envar">$M4</code></a>, <a class="link" href="#cv-M4COM"><code class="envar">$M4COM</code></a>, <a class="link" href="#cv-M4FLAGS"><code class="envar">$M4FLAGS</code></a>.</p><p>Uses: <a class="link" href="#cv-M4COMSTR"><code class="envar">$M4COMSTR</code></a>.</p></dd><dt><a name="t-masm"></a><span class="term">masm</span></dt><dd><p>
|
|
Sets construction variables for the Microsoft assembler.
|
|
</p><p>Sets: <a class="link" href="#cv-AS"><code class="envar">$AS</code></a>, <a class="link" href="#cv-ASCOM"><code class="envar">$ASCOM</code></a>, <a class="link" href="#cv-ASFLAGS"><code class="envar">$ASFLAGS</code></a>, <a class="link" href="#cv-ASPPCOM"><code class="envar">$ASPPCOM</code></a>, <a class="link" href="#cv-ASPPFLAGS"><code class="envar">$ASPPFLAGS</code></a>.</p><p>Uses: <a class="link" href="#cv-ASCOMSTR"><code class="envar">$ASCOMSTR</code></a>, <a class="link" href="#cv-ASPPCOMSTR"><code class="envar">$ASPPCOMSTR</code></a>, <a class="link" href="#cv-CPPFLAGS"><code class="envar">$CPPFLAGS</code></a>, <a class="link" href="#cv-_CPPDEFFLAGS"><code class="envar">$_CPPDEFFLAGS</code></a>, <a class="link" href="#cv-_CPPINCFLAGS"><code class="envar">$_CPPINCFLAGS</code></a>.</p></dd><dt><a name="t-midl"></a><span class="term">midl</span></dt><dd><p>
|
|
Sets construction variables for the Microsoft IDL compiler.
|
|
</p><p>Sets: <a class="link" href="#cv-MIDL"><code class="envar">$MIDL</code></a>, <a class="link" href="#cv-MIDLCOM"><code class="envar">$MIDLCOM</code></a>, <a class="link" href="#cv-MIDLFLAGS"><code class="envar">$MIDLFLAGS</code></a>.</p><p>Uses: <a class="link" href="#cv-MIDLCOMSTR"><code class="envar">$MIDLCOMSTR</code></a>.</p></dd><dt><a name="t-mingw"></a><span class="term">mingw</span></dt><dd><p>
|
|
Sets construction variables for MinGW (Minimal Gnu on Windows).
|
|
</p><p>Sets: <a class="link" href="#cv-AS"><code class="envar">$AS</code></a>, <a class="link" href="#cv-CC"><code class="envar">$CC</code></a>, <a class="link" href="#cv-CXX"><code class="envar">$CXX</code></a>, <a class="link" href="#cv-LDMODULECOM"><code class="envar">$LDMODULECOM</code></a>, <a class="link" href="#cv-LIBPREFIX"><code class="envar">$LIBPREFIX</code></a>, <a class="link" href="#cv-LIBSUFFIX"><code class="envar">$LIBSUFFIX</code></a>, <a class="link" href="#cv-OBJSUFFIX"><code class="envar">$OBJSUFFIX</code></a>, <a class="link" href="#cv-RC"><code class="envar">$RC</code></a>, <a class="link" href="#cv-RCCOM"><code class="envar">$RCCOM</code></a>, <a class="link" href="#cv-RCFLAGS"><code class="envar">$RCFLAGS</code></a>, <a class="link" href="#cv-RCINCFLAGS"><code class="envar">$RCINCFLAGS</code></a>, <a class="link" href="#cv-RCINCPREFIX"><code class="envar">$RCINCPREFIX</code></a>, <a class="link" href="#cv-RCINCSUFFIX"><code class="envar">$RCINCSUFFIX</code></a>, <a class="link" href="#cv-SHCCFLAGS"><code class="envar">$SHCCFLAGS</code></a>, <a class="link" href="#cv-SHCXXFLAGS"><code class="envar">$SHCXXFLAGS</code></a>, <a class="link" href="#cv-SHLINKCOM"><code class="envar">$SHLINKCOM</code></a>, <a class="link" href="#cv-SHLINKFLAGS"><code class="envar">$SHLINKFLAGS</code></a>, <a class="link" href="#cv-SHOBJSUFFIX"><code class="envar">$SHOBJSUFFIX</code></a>, <a class="link" href="#cv-WINDOWSDEFPREFIX"><code class="envar">$WINDOWSDEFPREFIX</code></a>, <a class="link" href="#cv-WINDOWSDEFSUFFIX"><code class="envar">$WINDOWSDEFSUFFIX</code></a>.</p><p>Uses: <a class="link" href="#cv-RCCOMSTR"><code class="envar">$RCCOMSTR</code></a>, <a class="link" href="#cv-SHLINKCOMSTR"><code class="envar">$SHLINKCOMSTR</code></a>.</p></dd><dt><a name="t-msgfmt"></a><span class="term">msgfmt</span></dt><dd><p>
|
|
This scons tool is a part of scons <a class="link" href="#t-gettext"><code class="literal">gettext</code></a> toolset. It provides scons
|
|
interface to <span class="command"><strong>msgfmt(1)</strong></span> command, which generates binary
|
|
message catalog (<code class="literal">MO</code>) from a textual translation description
|
|
(<code class="literal">PO</code>).
|
|
</p><p>Sets: <a class="link" href="#cv-MOSUFFIX"><code class="envar">$MOSUFFIX</code></a>, <a class="link" href="#cv-MSGFMT"><code class="envar">$MSGFMT</code></a>, <a class="link" href="#cv-MSGFMTCOM"><code class="envar">$MSGFMTCOM</code></a>, <a class="link" href="#cv-MSGFMTCOMSTR"><code class="envar">$MSGFMTCOMSTR</code></a>, <a class="link" href="#cv-MSGFMTFLAGS"><code class="envar">$MSGFMTFLAGS</code></a>, <a class="link" href="#cv-POSUFFIX"><code class="envar">$POSUFFIX</code></a>.</p><p>Uses: <a class="link" href="#cv-LINGUAS_FILE"><code class="envar">$LINGUAS_FILE</code></a>.</p></dd><dt><a name="t-msginit"></a><span class="term">msginit</span></dt><dd><p>
|
|
This scons tool is a part of scons <a class="link" href="#t-gettext"><code class="literal">gettext</code></a> toolset. It provides
|
|
scons interface to <span class="command"><strong>msginit(1)</strong></span> program, which creates new
|
|
<code class="literal">PO</code> file, initializing the meta information with values from
|
|
user's environment (or options).
|
|
</p><p>Sets: <a class="link" href="#cv-MSGINIT"><code class="envar">$MSGINIT</code></a>, <a class="link" href="#cv-MSGINITCOM"><code class="envar">$MSGINITCOM</code></a>, <a class="link" href="#cv-MSGINITCOMSTR"><code class="envar">$MSGINITCOMSTR</code></a>, <a class="link" href="#cv-MSGINITFLAGS"><code class="envar">$MSGINITFLAGS</code></a>, <a class="link" href="#cv-POAUTOINIT"><code class="envar">$POAUTOINIT</code></a>, <a class="link" href="#cv-POCREATE_ALIAS"><code class="envar">$POCREATE_ALIAS</code></a>, <a class="link" href="#cv-POSUFFIX"><code class="envar">$POSUFFIX</code></a>, <a class="link" href="#cv-POTSUFFIX"><code class="envar">$POTSUFFIX</code></a>, <a class="link" href="#cv-_MSGINITLOCALE"><code class="envar">$_MSGINITLOCALE</code></a>.</p><p>Uses: <a class="link" href="#cv-LINGUAS_FILE"><code class="envar">$LINGUAS_FILE</code></a>, <a class="link" href="#cv-POAUTOINIT"><code class="envar">$POAUTOINIT</code></a>, <a class="link" href="#cv-POTDOMAIN"><code class="envar">$POTDOMAIN</code></a>.</p></dd><dt><a name="t-msgmerge"></a><span class="term">msgmerge</span></dt><dd><p>
|
|
This scons tool is a part of scons <a class="link" href="#t-gettext"><code class="literal">gettext</code></a> toolset. It provides
|
|
scons interface to <span class="command"><strong>msgmerge(1)</strong></span> command, which merges two
|
|
Uniform style <code class="filename">.po</code> files together.
|
|
</p><p>Sets: <a class="link" href="#cv-MSGMERGE"><code class="envar">$MSGMERGE</code></a>, <a class="link" href="#cv-MSGMERGECOM"><code class="envar">$MSGMERGECOM</code></a>, <a class="link" href="#cv-MSGMERGECOMSTR"><code class="envar">$MSGMERGECOMSTR</code></a>, <a class="link" href="#cv-MSGMERGEFLAGS"><code class="envar">$MSGMERGEFLAGS</code></a>, <a class="link" href="#cv-POSUFFIX"><code class="envar">$POSUFFIX</code></a>, <a class="link" href="#cv-POTSUFFIX"><code class="envar">$POTSUFFIX</code></a>, <a class="link" href="#cv-POUPDATE_ALIAS"><code class="envar">$POUPDATE_ALIAS</code></a>.</p><p>Uses: <a class="link" href="#cv-LINGUAS_FILE"><code class="envar">$LINGUAS_FILE</code></a>, <a class="link" href="#cv-POAUTOINIT"><code class="envar">$POAUTOINIT</code></a>, <a class="link" href="#cv-POTDOMAIN"><code class="envar">$POTDOMAIN</code></a>.</p></dd><dt><a name="t-mslib"></a><span class="term">mslib</span></dt><dd><p>
|
|
Sets construction variables for the Microsoft
|
|
<span class="application">mslib</span>
|
|
library archiver.
|
|
</p><p>Sets: <a class="link" href="#cv-AR"><code class="envar">$AR</code></a>, <a class="link" href="#cv-ARCOM"><code class="envar">$ARCOM</code></a>, <a class="link" href="#cv-ARFLAGS"><code class="envar">$ARFLAGS</code></a>, <a class="link" href="#cv-LIBPREFIX"><code class="envar">$LIBPREFIX</code></a>, <a class="link" href="#cv-LIBSUFFIX"><code class="envar">$LIBSUFFIX</code></a>.</p><p>Uses: <a class="link" href="#cv-ARCOMSTR"><code class="envar">$ARCOMSTR</code></a>.</p></dd><dt><a name="t-mslink"></a><span class="term">mslink</span></dt><dd><p>
|
|
Sets construction variables for the Microsoft linker.
|
|
</p><p>Sets: <a class="link" href="#cv-LDMODULE"><code class="envar">$LDMODULE</code></a>, <a class="link" href="#cv-LDMODULECOM"><code class="envar">$LDMODULECOM</code></a>, <a class="link" href="#cv-LDMODULEFLAGS"><code class="envar">$LDMODULEFLAGS</code></a>, <a class="link" href="#cv-LDMODULEPREFIX"><code class="envar">$LDMODULEPREFIX</code></a>, <a class="link" href="#cv-LDMODULESUFFIX"><code class="envar">$LDMODULESUFFIX</code></a>, <a class="link" href="#cv-LIBDIRPREFIX"><code class="envar">$LIBDIRPREFIX</code></a>, <a class="link" href="#cv-LIBDIRSUFFIX"><code class="envar">$LIBDIRSUFFIX</code></a>, <a class="link" href="#cv-LIBLINKPREFIX"><code class="envar">$LIBLINKPREFIX</code></a>, <a class="link" href="#cv-LIBLINKSUFFIX"><code class="envar">$LIBLINKSUFFIX</code></a>, <a class="link" href="#cv-LINK"><code class="envar">$LINK</code></a>, <a class="link" href="#cv-LINKCOM"><code class="envar">$LINKCOM</code></a>, <a class="link" href="#cv-LINKFLAGS"><code class="envar">$LINKFLAGS</code></a>, <a class="link" href="#cv-REGSVR"><code class="envar">$REGSVR</code></a>, <a class="link" href="#cv-REGSVRCOM"><code class="envar">$REGSVRCOM</code></a>, <a class="link" href="#cv-REGSVRFLAGS"><code class="envar">$REGSVRFLAGS</code></a>, <a class="link" href="#cv-SHLINK"><code class="envar">$SHLINK</code></a>, <a class="link" href="#cv-SHLINKCOM"><code class="envar">$SHLINKCOM</code></a>, <a class="link" href="#cv-SHLINKFLAGS"><code class="envar">$SHLINKFLAGS</code></a>, <a class="link" href="#cv-WIN32DEFPREFIX"><code class="envar">$WIN32DEFPREFIX</code></a>, <a class="link" href="#cv-WIN32DEFSUFFIX"><code class="envar">$WIN32DEFSUFFIX</code></a>, <a class="link" href="#cv-WIN32EXPPREFIX"><code class="envar">$WIN32EXPPREFIX</code></a>, <a class="link" href="#cv-WIN32EXPSUFFIX"><code class="envar">$WIN32EXPSUFFIX</code></a>, <a class="link" href="#cv-WINDOWSDEFPREFIX"><code class="envar">$WINDOWSDEFPREFIX</code></a>, <a class="link" href="#cv-WINDOWSDEFSUFFIX"><code class="envar">$WINDOWSDEFSUFFIX</code></a>, <a class="link" href="#cv-WINDOWSEXPPREFIX"><code class="envar">$WINDOWSEXPPREFIX</code></a>, <a class="link" href="#cv-WINDOWSEXPSUFFIX"><code class="envar">$WINDOWSEXPSUFFIX</code></a>, <a class="link" href="#cv-WINDOWSPROGMANIFESTPREFIX"><code class="envar">$WINDOWSPROGMANIFESTPREFIX</code></a>, <a class="link" href="#cv-WINDOWSPROGMANIFESTSUFFIX"><code class="envar">$WINDOWSPROGMANIFESTSUFFIX</code></a>, <a class="link" href="#cv-WINDOWSSHLIBMANIFESTPREFIX"><code class="envar">$WINDOWSSHLIBMANIFESTPREFIX</code></a>, <a class="link" href="#cv-WINDOWSSHLIBMANIFESTSUFFIX"><code class="envar">$WINDOWSSHLIBMANIFESTSUFFIX</code></a>, <a class="link" href="#cv-WINDOWS_INSERT_DEF"><code class="envar">$WINDOWS_INSERT_DEF</code></a>.</p><p>Uses: <a class="link" href="#cv-LDMODULECOMSTR"><code class="envar">$LDMODULECOMSTR</code></a>, <a class="link" href="#cv-LINKCOMSTR"><code class="envar">$LINKCOMSTR</code></a>, <a class="link" href="#cv-REGSVRCOMSTR"><code class="envar">$REGSVRCOMSTR</code></a>, <a class="link" href="#cv-SHLINKCOMSTR"><code class="envar">$SHLINKCOMSTR</code></a>.</p></dd><dt><a name="t-mssdk"></a><span class="term">mssdk</span></dt><dd><p>
|
|
Sets variables for Microsoft Platform SDK and/or Windows SDK.
|
|
Note that unlike most other Tool modules,
|
|
mssdk does not set construction variables,
|
|
but sets the <span class="emphasis"><em>environment variables</em></span>
|
|
in the environment <span class="application">SCons</span> uses to execute
|
|
the Microsoft toolchain:
|
|
<code class="literal">%INCLUDE%</code>,
|
|
<code class="literal">%LIB%</code>,
|
|
<code class="literal">%LIBPATH%</code> and
|
|
<code class="literal">%PATH%</code>.
|
|
</p><p>Uses: <a class="link" href="#cv-MSSDK_DIR"><code class="envar">$MSSDK_DIR</code></a>, <a class="link" href="#cv-MSSDK_VERSION"><code class="envar">$MSSDK_VERSION</code></a>, <a class="link" href="#cv-MSVS_VERSION"><code class="envar">$MSVS_VERSION</code></a>.</p></dd><dt><a name="t-msvc"></a><span class="term">msvc</span></dt><dd><p>
|
|
Sets construction variables for the Microsoft Visual C/C++ compiler.
|
|
</p><p>Sets: <a class="link" href="#cv-BUILDERS"><code class="envar">$BUILDERS</code></a>, <a class="link" href="#cv-CC"><code class="envar">$CC</code></a>, <a class="link" href="#cv-CCCOM"><code class="envar">$CCCOM</code></a>, <a class="link" href="#cv-CCFLAGS"><code class="envar">$CCFLAGS</code></a>, <a class="link" href="#cv-CCPCHFLAGS"><code class="envar">$CCPCHFLAGS</code></a>, <a class="link" href="#cv-CCPDBFLAGS"><code class="envar">$CCPDBFLAGS</code></a>, <a class="link" href="#cv-CFILESUFFIX"><code class="envar">$CFILESUFFIX</code></a>, <a class="link" href="#cv-CFLAGS"><code class="envar">$CFLAGS</code></a>, <a class="link" href="#cv-CPPDEFPREFIX"><code class="envar">$CPPDEFPREFIX</code></a>, <a class="link" href="#cv-CPPDEFSUFFIX"><code class="envar">$CPPDEFSUFFIX</code></a>, <a class="link" href="#cv-CXX"><code class="envar">$CXX</code></a>, <a class="link" href="#cv-CXXCOM"><code class="envar">$CXXCOM</code></a>, <a class="link" href="#cv-CXXFILESUFFIX"><code class="envar">$CXXFILESUFFIX</code></a>, <a class="link" href="#cv-CXXFLAGS"><code class="envar">$CXXFLAGS</code></a>, <a class="link" href="#cv-INCPREFIX"><code class="envar">$INCPREFIX</code></a>, <a class="link" href="#cv-INCSUFFIX"><code class="envar">$INCSUFFIX</code></a>, <a class="link" href="#cv-OBJPREFIX"><code class="envar">$OBJPREFIX</code></a>, <a class="link" href="#cv-OBJSUFFIX"><code class="envar">$OBJSUFFIX</code></a>, <a class="link" href="#cv-PCHCOM"><code class="envar">$PCHCOM</code></a>, <a class="link" href="#cv-PCHPDBFLAGS"><code class="envar">$PCHPDBFLAGS</code></a>, <a class="link" href="#cv-RC"><code class="envar">$RC</code></a>, <a class="link" href="#cv-RCCOM"><code class="envar">$RCCOM</code></a>, <a class="link" href="#cv-RCFLAGS"><code class="envar">$RCFLAGS</code></a>, <a class="link" href="#cv-SHCC"><code class="envar">$SHCC</code></a>, <a class="link" href="#cv-SHCCCOM"><code class="envar">$SHCCCOM</code></a>, <a class="link" href="#cv-SHCCFLAGS"><code class="envar">$SHCCFLAGS</code></a>, <a class="link" href="#cv-SHCFLAGS"><code class="envar">$SHCFLAGS</code></a>, <a class="link" href="#cv-SHCXX"><code class="envar">$SHCXX</code></a>, <a class="link" href="#cv-SHCXXCOM"><code class="envar">$SHCXXCOM</code></a>, <a class="link" href="#cv-SHCXXFLAGS"><code class="envar">$SHCXXFLAGS</code></a>, <a class="link" href="#cv-SHOBJPREFIX"><code class="envar">$SHOBJPREFIX</code></a>, <a class="link" href="#cv-SHOBJSUFFIX"><code class="envar">$SHOBJSUFFIX</code></a>.</p><p>Uses: <a class="link" href="#cv-CCCOMSTR"><code class="envar">$CCCOMSTR</code></a>, <a class="link" href="#cv-CXXCOMSTR"><code class="envar">$CXXCOMSTR</code></a>, <a class="link" href="#cv-PCH"><code class="envar">$PCH</code></a>, <a class="link" href="#cv-PCHSTOP"><code class="envar">$PCHSTOP</code></a>, <a class="link" href="#cv-PDB"><code class="envar">$PDB</code></a>, <a class="link" href="#cv-SHCCCOMSTR"><code class="envar">$SHCCCOMSTR</code></a>, <a class="link" href="#cv-SHCXXCOMSTR"><code class="envar">$SHCXXCOMSTR</code></a>.</p></dd><dt><a name="t-msvs"></a><span class="term">msvs</span></dt><dd><p>
|
|
Sets construction variables for Microsoft Visual Studio. </p><p>Sets: <a class="link" href="#cv-MSVSBUILDCOM"><code class="envar">$MSVSBUILDCOM</code></a>, <a class="link" href="#cv-MSVSCLEANCOM"><code class="envar">$MSVSCLEANCOM</code></a>, <a class="link" href="#cv-MSVSENCODING"><code class="envar">$MSVSENCODING</code></a>, <a class="link" href="#cv-MSVSPROJECTCOM"><code class="envar">$MSVSPROJECTCOM</code></a>, <a class="link" href="#cv-MSVSREBUILDCOM"><code class="envar">$MSVSREBUILDCOM</code></a>, <a class="link" href="#cv-MSVSSCONS"><code class="envar">$MSVSSCONS</code></a>, <a class="link" href="#cv-MSVSSCONSCOM"><code class="envar">$MSVSSCONSCOM</code></a>, <a class="link" href="#cv-MSVSSCONSCRIPT"><code class="envar">$MSVSSCONSCRIPT</code></a>, <a class="link" href="#cv-MSVSSCONSFLAGS"><code class="envar">$MSVSSCONSFLAGS</code></a>, <a class="link" href="#cv-MSVSSOLUTIONCOM"><code class="envar">$MSVSSOLUTIONCOM</code></a>.</p></dd><dt><a name="t-mwcc"></a><span class="term">mwcc</span></dt><dd><p>
|
|
Sets construction variables for the Metrowerks CodeWarrior compiler.
|
|
</p><p>Sets: <a class="link" href="#cv-CC"><code class="envar">$CC</code></a>, <a class="link" href="#cv-CCCOM"><code class="envar">$CCCOM</code></a>, <a class="link" href="#cv-CFILESUFFIX"><code class="envar">$CFILESUFFIX</code></a>, <a class="link" href="#cv-CPPDEFPREFIX"><code class="envar">$CPPDEFPREFIX</code></a>, <a class="link" href="#cv-CPPDEFSUFFIX"><code class="envar">$CPPDEFSUFFIX</code></a>, <a class="link" href="#cv-CXX"><code class="envar">$CXX</code></a>, <a class="link" href="#cv-CXXCOM"><code class="envar">$CXXCOM</code></a>, <a class="link" href="#cv-CXXFILESUFFIX"><code class="envar">$CXXFILESUFFIX</code></a>, <a class="link" href="#cv-INCPREFIX"><code class="envar">$INCPREFIX</code></a>, <a class="link" href="#cv-INCSUFFIX"><code class="envar">$INCSUFFIX</code></a>, <a class="link" href="#cv-MWCW_VERSION"><code class="envar">$MWCW_VERSION</code></a>, <a class="link" href="#cv-MWCW_VERSIONS"><code class="envar">$MWCW_VERSIONS</code></a>, <a class="link" href="#cv-SHCC"><code class="envar">$SHCC</code></a>, <a class="link" href="#cv-SHCCCOM"><code class="envar">$SHCCCOM</code></a>, <a class="link" href="#cv-SHCCFLAGS"><code class="envar">$SHCCFLAGS</code></a>, <a class="link" href="#cv-SHCFLAGS"><code class="envar">$SHCFLAGS</code></a>, <a class="link" href="#cv-SHCXX"><code class="envar">$SHCXX</code></a>, <a class="link" href="#cv-SHCXXCOM"><code class="envar">$SHCXXCOM</code></a>, <a class="link" href="#cv-SHCXXFLAGS"><code class="envar">$SHCXXFLAGS</code></a>.</p><p>Uses: <a class="link" href="#cv-CCCOMSTR"><code class="envar">$CCCOMSTR</code></a>, <a class="link" href="#cv-CXXCOMSTR"><code class="envar">$CXXCOMSTR</code></a>, <a class="link" href="#cv-SHCCCOMSTR"><code class="envar">$SHCCCOMSTR</code></a>, <a class="link" href="#cv-SHCXXCOMSTR"><code class="envar">$SHCXXCOMSTR</code></a>.</p></dd><dt><a name="t-mwld"></a><span class="term">mwld</span></dt><dd><p>
|
|
Sets construction variables for the Metrowerks CodeWarrior linker.
|
|
</p><p>Sets: <a class="link" href="#cv-AR"><code class="envar">$AR</code></a>, <a class="link" href="#cv-ARCOM"><code class="envar">$ARCOM</code></a>, <a class="link" href="#cv-LIBDIRPREFIX"><code class="envar">$LIBDIRPREFIX</code></a>, <a class="link" href="#cv-LIBDIRSUFFIX"><code class="envar">$LIBDIRSUFFIX</code></a>, <a class="link" href="#cv-LIBLINKPREFIX"><code class="envar">$LIBLINKPREFIX</code></a>, <a class="link" href="#cv-LIBLINKSUFFIX"><code class="envar">$LIBLINKSUFFIX</code></a>, <a class="link" href="#cv-LINK"><code class="envar">$LINK</code></a>, <a class="link" href="#cv-LINKCOM"><code class="envar">$LINKCOM</code></a>, <a class="link" href="#cv-SHLINK"><code class="envar">$SHLINK</code></a>, <a class="link" href="#cv-SHLINKCOM"><code class="envar">$SHLINKCOM</code></a>, <a class="link" href="#cv-SHLINKFLAGS"><code class="envar">$SHLINKFLAGS</code></a>.</p></dd><dt><a name="t-nasm"></a><span class="term">nasm</span></dt><dd><p>
|
|
Sets construction variables for the
|
|
<span class="application">nasm</span> Netwide Assembler.
|
|
</p><p>Sets: <a class="link" href="#cv-AS"><code class="envar">$AS</code></a>, <a class="link" href="#cv-ASCOM"><code class="envar">$ASCOM</code></a>, <a class="link" href="#cv-ASFLAGS"><code class="envar">$ASFLAGS</code></a>, <a class="link" href="#cv-ASPPCOM"><code class="envar">$ASPPCOM</code></a>, <a class="link" href="#cv-ASPPFLAGS"><code class="envar">$ASPPFLAGS</code></a>.</p><p>Uses: <a class="link" href="#cv-ASCOMSTR"><code class="envar">$ASCOMSTR</code></a>, <a class="link" href="#cv-ASPPCOMSTR"><code class="envar">$ASPPCOMSTR</code></a>.</p></dd><dt><a name="t-packaging"></a><span class="term">packaging</span></dt><dd><p>
|
|
A framework for building binary and source packages.
|
|
</p></dd><dt><a name="t-Packaging"></a><span class="term">Packaging</span></dt><dd><p>
|
|
Sets construction variables for the <code class="function">Package</code> Builder.
|
|
</p></dd><dt><a name="t-pdf"></a><span class="term">pdf</span></dt><dd><p>
|
|
Sets construction variables for the Portable Document Format builder.
|
|
</p><p>Sets: <a class="link" href="#cv-PDFPREFIX"><code class="envar">$PDFPREFIX</code></a>, <a class="link" href="#cv-PDFSUFFIX"><code class="envar">$PDFSUFFIX</code></a>.</p></dd><dt><a name="t-pdflatex"></a><span class="term">pdflatex</span></dt><dd><p>
|
|
Sets construction variables for the <span class="application">pdflatex</span> utility.
|
|
</p><p>Sets: <a class="link" href="#cv-LATEXRETRIES"><code class="envar">$LATEXRETRIES</code></a>, <a class="link" href="#cv-PDFLATEX"><code class="envar">$PDFLATEX</code></a>, <a class="link" href="#cv-PDFLATEXCOM"><code class="envar">$PDFLATEXCOM</code></a>, <a class="link" href="#cv-PDFLATEXFLAGS"><code class="envar">$PDFLATEXFLAGS</code></a>.</p><p>Uses: <a class="link" href="#cv-PDFLATEXCOMSTR"><code class="envar">$PDFLATEXCOMSTR</code></a>.</p></dd><dt><a name="t-pdftex"></a><span class="term">pdftex</span></dt><dd><p>
|
|
Sets construction variables for the <span class="application">pdftex</span> utility.
|
|
</p><p>Sets: <a class="link" href="#cv-LATEXRETRIES"><code class="envar">$LATEXRETRIES</code></a>, <a class="link" href="#cv-PDFLATEX"><code class="envar">$PDFLATEX</code></a>, <a class="link" href="#cv-PDFLATEXCOM"><code class="envar">$PDFLATEXCOM</code></a>, <a class="link" href="#cv-PDFLATEXFLAGS"><code class="envar">$PDFLATEXFLAGS</code></a>, <a class="link" href="#cv-PDFTEX"><code class="envar">$PDFTEX</code></a>, <a class="link" href="#cv-PDFTEXCOM"><code class="envar">$PDFTEXCOM</code></a>, <a class="link" href="#cv-PDFTEXFLAGS"><code class="envar">$PDFTEXFLAGS</code></a>.</p><p>Uses: <a class="link" href="#cv-PDFLATEXCOMSTR"><code class="envar">$PDFLATEXCOMSTR</code></a>, <a class="link" href="#cv-PDFTEXCOMSTR"><code class="envar">$PDFTEXCOMSTR</code></a>.</p></dd><dt><a name="t-qt"></a><span class="term">qt</span></dt><dd><p>
|
|
Sets construction variables for building Qt applications.
|
|
</p><p>Sets: <a class="link" href="#cv-QTDIR"><code class="envar">$QTDIR</code></a>, <a class="link" href="#cv-QT_AUTOSCAN"><code class="envar">$QT_AUTOSCAN</code></a>, <a class="link" href="#cv-QT_BINPATH"><code class="envar">$QT_BINPATH</code></a>, <a class="link" href="#cv-QT_CPPPATH"><code class="envar">$QT_CPPPATH</code></a>, <a class="link" href="#cv-QT_LIB"><code class="envar">$QT_LIB</code></a>, <a class="link" href="#cv-QT_LIBPATH"><code class="envar">$QT_LIBPATH</code></a>, <a class="link" href="#cv-QT_MOC"><code class="envar">$QT_MOC</code></a>, <a class="link" href="#cv-QT_MOCCXXPREFIX"><code class="envar">$QT_MOCCXXPREFIX</code></a>, <a class="link" href="#cv-QT_MOCCXXSUFFIX"><code class="envar">$QT_MOCCXXSUFFIX</code></a>, <a class="link" href="#cv-QT_MOCFROMCXXCOM"><code class="envar">$QT_MOCFROMCXXCOM</code></a>, <a class="link" href="#cv-QT_MOCFROMCXXFLAGS"><code class="envar">$QT_MOCFROMCXXFLAGS</code></a>, <a class="link" href="#cv-QT_MOCFROMHCOM"><code class="envar">$QT_MOCFROMHCOM</code></a>, <a class="link" href="#cv-QT_MOCFROMHFLAGS"><code class="envar">$QT_MOCFROMHFLAGS</code></a>, <a class="link" href="#cv-QT_MOCHPREFIX"><code class="envar">$QT_MOCHPREFIX</code></a>, <a class="link" href="#cv-QT_MOCHSUFFIX"><code class="envar">$QT_MOCHSUFFIX</code></a>, <a class="link" href="#cv-QT_UIC"><code class="envar">$QT_UIC</code></a>, <a class="link" href="#cv-QT_UICCOM"><code class="envar">$QT_UICCOM</code></a>, <a class="link" href="#cv-QT_UICDECLFLAGS"><code class="envar">$QT_UICDECLFLAGS</code></a>, <a class="link" href="#cv-QT_UICDECLPREFIX"><code class="envar">$QT_UICDECLPREFIX</code></a>, <a class="link" href="#cv-QT_UICDECLSUFFIX"><code class="envar">$QT_UICDECLSUFFIX</code></a>, <a class="link" href="#cv-QT_UICIMPLFLAGS"><code class="envar">$QT_UICIMPLFLAGS</code></a>, <a class="link" href="#cv-QT_UICIMPLPREFIX"><code class="envar">$QT_UICIMPLPREFIX</code></a>, <a class="link" href="#cv-QT_UICIMPLSUFFIX"><code class="envar">$QT_UICIMPLSUFFIX</code></a>, <a class="link" href="#cv-QT_UISUFFIX"><code class="envar">$QT_UISUFFIX</code></a>.</p></dd><dt><a name="t-rmic"></a><span class="term">rmic</span></dt><dd><p>
|
|
Sets construction variables for the <span class="application">rmic</span> utility.
|
|
</p><p>Sets: <a class="link" href="#cv-JAVACLASSSUFFIX"><code class="envar">$JAVACLASSSUFFIX</code></a>, <a class="link" href="#cv-RMIC"><code class="envar">$RMIC</code></a>, <a class="link" href="#cv-RMICCOM"><code class="envar">$RMICCOM</code></a>, <a class="link" href="#cv-RMICFLAGS"><code class="envar">$RMICFLAGS</code></a>.</p><p>Uses: <a class="link" href="#cv-RMICCOMSTR"><code class="envar">$RMICCOMSTR</code></a>.</p></dd><dt><a name="t-rpcgen"></a><span class="term">rpcgen</span></dt><dd><p>
|
|
Sets construction variables for building with RPCGEN.
|
|
</p><p>Sets: <a class="link" href="#cv-RPCGEN"><code class="envar">$RPCGEN</code></a>, <a class="link" href="#cv-RPCGENCLIENTFLAGS"><code class="envar">$RPCGENCLIENTFLAGS</code></a>, <a class="link" href="#cv-RPCGENFLAGS"><code class="envar">$RPCGENFLAGS</code></a>, <a class="link" href="#cv-RPCGENHEADERFLAGS"><code class="envar">$RPCGENHEADERFLAGS</code></a>, <a class="link" href="#cv-RPCGENSERVICEFLAGS"><code class="envar">$RPCGENSERVICEFLAGS</code></a>, <a class="link" href="#cv-RPCGENXDRFLAGS"><code class="envar">$RPCGENXDRFLAGS</code></a>.</p></dd><dt><a name="t-sgiar"></a><span class="term">sgiar</span></dt><dd><p>
|
|
Sets construction variables for the SGI library archiver.
|
|
</p><p>Sets: <a class="link" href="#cv-AR"><code class="envar">$AR</code></a>, <a class="link" href="#cv-ARCOMSTR"><code class="envar">$ARCOMSTR</code></a>, <a class="link" href="#cv-ARFLAGS"><code class="envar">$ARFLAGS</code></a>, <a class="link" href="#cv-LIBPREFIX"><code class="envar">$LIBPREFIX</code></a>, <a class="link" href="#cv-LIBSUFFIX"><code class="envar">$LIBSUFFIX</code></a>, <a class="link" href="#cv-SHLINK"><code class="envar">$SHLINK</code></a>, <a class="link" href="#cv-SHLINKFLAGS"><code class="envar">$SHLINKFLAGS</code></a>.</p><p>Uses: <a class="link" href="#cv-ARCOMSTR"><code class="envar">$ARCOMSTR</code></a>, <a class="link" href="#cv-SHLINKCOMSTR"><code class="envar">$SHLINKCOMSTR</code></a>.</p></dd><dt><a name="t-sgicXX"></a><span class="term">sgic++</span></dt><dd><p>
|
|
Sets construction variables for the SGI C++ compiler.
|
|
</p><p>Sets: <a class="link" href="#cv-CXX"><code class="envar">$CXX</code></a>, <a class="link" href="#cv-CXXFLAGS"><code class="envar">$CXXFLAGS</code></a>, <a class="link" href="#cv-SHCXX"><code class="envar">$SHCXX</code></a>, <a class="link" href="#cv-SHOBJSUFFIX"><code class="envar">$SHOBJSUFFIX</code></a>.</p></dd><dt><a name="t-sgicc"></a><span class="term">sgicc</span></dt><dd><p>
|
|
Sets construction variables for the SGI C compiler.
|
|
</p><p>Sets: <a class="link" href="#cv-CXX"><code class="envar">$CXX</code></a>, <a class="link" href="#cv-SHOBJSUFFIX"><code class="envar">$SHOBJSUFFIX</code></a>.</p></dd><dt><a name="t-sgilink"></a><span class="term">sgilink</span></dt><dd><p>
|
|
Sets construction variables for the SGI linker.
|
|
</p><p>Sets: <a class="link" href="#cv-LINK"><code class="envar">$LINK</code></a>, <a class="link" href="#cv-RPATHPREFIX"><code class="envar">$RPATHPREFIX</code></a>, <a class="link" href="#cv-RPATHSUFFIX"><code class="envar">$RPATHSUFFIX</code></a>, <a class="link" href="#cv-SHLINKFLAGS"><code class="envar">$SHLINKFLAGS</code></a>.</p></dd><dt><a name="t-sunar"></a><span class="term">sunar</span></dt><dd><p>
|
|
Sets construction variables for the Sun library archiver.
|
|
</p><p>Sets: <a class="link" href="#cv-AR"><code class="envar">$AR</code></a>, <a class="link" href="#cv-ARCOM"><code class="envar">$ARCOM</code></a>, <a class="link" href="#cv-ARFLAGS"><code class="envar">$ARFLAGS</code></a>, <a class="link" href="#cv-LIBPREFIX"><code class="envar">$LIBPREFIX</code></a>, <a class="link" href="#cv-LIBSUFFIX"><code class="envar">$LIBSUFFIX</code></a>.</p><p>Uses: <a class="link" href="#cv-ARCOMSTR"><code class="envar">$ARCOMSTR</code></a>.</p></dd><dt><a name="t-suncXX"></a><span class="term">sunc++</span></dt><dd><p>
|
|
Sets construction variables for the Sun C++ compiler.
|
|
</p><p>Sets: <a class="link" href="#cv-CXX"><code class="envar">$CXX</code></a>, <a class="link" href="#cv-CXXVERSION"><code class="envar">$CXXVERSION</code></a>, <a class="link" href="#cv-SHCXX"><code class="envar">$SHCXX</code></a>, <a class="link" href="#cv-SHCXXFLAGS"><code class="envar">$SHCXXFLAGS</code></a>, <a class="link" href="#cv-SHOBJPREFIX"><code class="envar">$SHOBJPREFIX</code></a>, <a class="link" href="#cv-SHOBJSUFFIX"><code class="envar">$SHOBJSUFFIX</code></a>.</p></dd><dt><a name="t-suncc"></a><span class="term">suncc</span></dt><dd><p>
|
|
Sets construction variables for the Sun C compiler.
|
|
</p><p>Sets: <a class="link" href="#cv-CXX"><code class="envar">$CXX</code></a>, <a class="link" href="#cv-SHCCFLAGS"><code class="envar">$SHCCFLAGS</code></a>, <a class="link" href="#cv-SHOBJPREFIX"><code class="envar">$SHOBJPREFIX</code></a>, <a class="link" href="#cv-SHOBJSUFFIX"><code class="envar">$SHOBJSUFFIX</code></a>.</p></dd><dt><a name="t-sunf77"></a><span class="term">sunf77</span></dt><dd><p>
|
|
Set construction variables for the Sun <span class="application">f77</span> Fortran compiler.
|
|
</p><p>Sets: <a class="link" href="#cv-F77"><code class="envar">$F77</code></a>, <a class="link" href="#cv-FORTRAN"><code class="envar">$FORTRAN</code></a>, <a class="link" href="#cv-SHF77"><code class="envar">$SHF77</code></a>, <a class="link" href="#cv-SHF77FLAGS"><code class="envar">$SHF77FLAGS</code></a>, <a class="link" href="#cv-SHFORTRAN"><code class="envar">$SHFORTRAN</code></a>, <a class="link" href="#cv-SHFORTRANFLAGS"><code class="envar">$SHFORTRANFLAGS</code></a>.</p></dd><dt><a name="t-sunf90"></a><span class="term">sunf90</span></dt><dd><p>
|
|
Set construction variables for the Sun <span class="application">f90</span> Fortran compiler.
|
|
</p><p>Sets: <a class="link" href="#cv-F90"><code class="envar">$F90</code></a>, <a class="link" href="#cv-FORTRAN"><code class="envar">$FORTRAN</code></a>, <a class="link" href="#cv-SHF90"><code class="envar">$SHF90</code></a>, <a class="link" href="#cv-SHF90FLAGS"><code class="envar">$SHF90FLAGS</code></a>, <a class="link" href="#cv-SHFORTRAN"><code class="envar">$SHFORTRAN</code></a>, <a class="link" href="#cv-SHFORTRANFLAGS"><code class="envar">$SHFORTRANFLAGS</code></a>.</p></dd><dt><a name="t-sunf95"></a><span class="term">sunf95</span></dt><dd><p>
|
|
Set construction variables for the Sun <span class="application">f95</span> Fortran compiler.
|
|
</p><p>Sets: <a class="link" href="#cv-F95"><code class="envar">$F95</code></a>, <a class="link" href="#cv-FORTRAN"><code class="envar">$FORTRAN</code></a>, <a class="link" href="#cv-SHF95"><code class="envar">$SHF95</code></a>, <a class="link" href="#cv-SHF95FLAGS"><code class="envar">$SHF95FLAGS</code></a>, <a class="link" href="#cv-SHFORTRAN"><code class="envar">$SHFORTRAN</code></a>, <a class="link" href="#cv-SHFORTRANFLAGS"><code class="envar">$SHFORTRANFLAGS</code></a>.</p></dd><dt><a name="t-sunlink"></a><span class="term">sunlink</span></dt><dd><p>
|
|
Sets construction variables for the Sun linker.
|
|
</p><p>Sets: <a class="link" href="#cv-RPATHPREFIX"><code class="envar">$RPATHPREFIX</code></a>, <a class="link" href="#cv-RPATHSUFFIX"><code class="envar">$RPATHSUFFIX</code></a>, <a class="link" href="#cv-SHLINKFLAGS"><code class="envar">$SHLINKFLAGS</code></a>.</p></dd><dt><a name="t-swig"></a><span class="term">swig</span></dt><dd><p>
|
|
Sets construction variables for the SWIG interface generator.
|
|
</p><p>Sets: <a class="link" href="#cv-SWIG"><code class="envar">$SWIG</code></a>, <a class="link" href="#cv-SWIGCFILESUFFIX"><code class="envar">$SWIGCFILESUFFIX</code></a>, <a class="link" href="#cv-SWIGCOM"><code class="envar">$SWIGCOM</code></a>, <a class="link" href="#cv-SWIGCXXFILESUFFIX"><code class="envar">$SWIGCXXFILESUFFIX</code></a>, <a class="link" href="#cv-SWIGDIRECTORSUFFIX"><code class="envar">$SWIGDIRECTORSUFFIX</code></a>, <a class="link" href="#cv-SWIGFLAGS"><code class="envar">$SWIGFLAGS</code></a>, <a class="link" href="#cv-SWIGINCPREFIX"><code class="envar">$SWIGINCPREFIX</code></a>, <a class="link" href="#cv-SWIGINCSUFFIX"><code class="envar">$SWIGINCSUFFIX</code></a>, <a class="link" href="#cv-SWIGPATH"><code class="envar">$SWIGPATH</code></a>, <a class="link" href="#cv-SWIGVERSION"><code class="envar">$SWIGVERSION</code></a>, <a class="link" href="#cv-_SWIGINCFLAGS"><code class="envar">$_SWIGINCFLAGS</code></a>.</p><p>Uses: <a class="link" href="#cv-SWIGCOMSTR"><code class="envar">$SWIGCOMSTR</code></a>.</p></dd><dt><a name="t-tar"></a><span class="term">tar</span></dt><dd><p>
|
|
Sets construction variables for the <span class="application">tar</span> archiver.
|
|
</p><p>Sets: <a class="link" href="#cv-TAR"><code class="envar">$TAR</code></a>, <a class="link" href="#cv-TARCOM"><code class="envar">$TARCOM</code></a>, <a class="link" href="#cv-TARFLAGS"><code class="envar">$TARFLAGS</code></a>, <a class="link" href="#cv-TARSUFFIX"><code class="envar">$TARSUFFIX</code></a>.</p><p>Uses: <a class="link" href="#cv-TARCOMSTR"><code class="envar">$TARCOMSTR</code></a>.</p></dd><dt><a name="t-tex"></a><span class="term">tex</span></dt><dd><p>
|
|
Sets construction variables for the TeX formatter and typesetter.
|
|
</p><p>Sets: <a class="link" href="#cv-BIBTEX"><code class="envar">$BIBTEX</code></a>, <a class="link" href="#cv-BIBTEXCOM"><code class="envar">$BIBTEXCOM</code></a>, <a class="link" href="#cv-BIBTEXFLAGS"><code class="envar">$BIBTEXFLAGS</code></a>, <a class="link" href="#cv-LATEX"><code class="envar">$LATEX</code></a>, <a class="link" href="#cv-LATEXCOM"><code class="envar">$LATEXCOM</code></a>, <a class="link" href="#cv-LATEXFLAGS"><code class="envar">$LATEXFLAGS</code></a>, <a class="link" href="#cv-MAKEINDEX"><code class="envar">$MAKEINDEX</code></a>, <a class="link" href="#cv-MAKEINDEXCOM"><code class="envar">$MAKEINDEXCOM</code></a>, <a class="link" href="#cv-MAKEINDEXFLAGS"><code class="envar">$MAKEINDEXFLAGS</code></a>, <a class="link" href="#cv-TEX"><code class="envar">$TEX</code></a>, <a class="link" href="#cv-TEXCOM"><code class="envar">$TEXCOM</code></a>, <a class="link" href="#cv-TEXFLAGS"><code class="envar">$TEXFLAGS</code></a>.</p><p>Uses: <a class="link" href="#cv-BIBTEXCOMSTR"><code class="envar">$BIBTEXCOMSTR</code></a>, <a class="link" href="#cv-LATEXCOMSTR"><code class="envar">$LATEXCOMSTR</code></a>, <a class="link" href="#cv-MAKEINDEXCOMSTR"><code class="envar">$MAKEINDEXCOMSTR</code></a>, <a class="link" href="#cv-TEXCOMSTR"><code class="envar">$TEXCOMSTR</code></a>.</p></dd><dt><a name="t-textfile"></a><span class="term">textfile</span></dt><dd><p>
|
|
Set construction variables for the <code class="function">Textfile</code> and <code class="function">Substfile</code> builders.
|
|
</p><p>Sets: <a class="link" href="#cv-LINESEPARATOR"><code class="envar">$LINESEPARATOR</code></a>, <a class="link" href="#cv-SUBSTFILEPREFIX"><code class="envar">$SUBSTFILEPREFIX</code></a>, <a class="link" href="#cv-SUBSTFILESUFFIX"><code class="envar">$SUBSTFILESUFFIX</code></a>, <a class="link" href="#cv-TEXTFILEPREFIX"><code class="envar">$TEXTFILEPREFIX</code></a>, <a class="link" href="#cv-TEXTFILESUFFIX"><code class="envar">$TEXTFILESUFFIX</code></a>.</p><p>Uses: <a class="link" href="#cv-SUBST_DICT"><code class="envar">$SUBST_DICT</code></a>.</p></dd><dt><a name="t-tlib"></a><span class="term">tlib</span></dt><dd><p>
|
|
Sets construction variables for the Borlan
|
|
<span class="application">tib</span> library archiver.
|
|
</p><p>Sets: <a class="link" href="#cv-AR"><code class="envar">$AR</code></a>, <a class="link" href="#cv-ARCOM"><code class="envar">$ARCOM</code></a>, <a class="link" href="#cv-ARFLAGS"><code class="envar">$ARFLAGS</code></a>, <a class="link" href="#cv-LIBPREFIX"><code class="envar">$LIBPREFIX</code></a>, <a class="link" href="#cv-LIBSUFFIX"><code class="envar">$LIBSUFFIX</code></a>.</p><p>Uses: <a class="link" href="#cv-ARCOMSTR"><code class="envar">$ARCOMSTR</code></a>.</p></dd><dt><a name="t-xgettext"></a><span class="term">xgettext</span></dt><dd><p>
|
|
This scons tool is a part of scons <a class="link" href="#t-gettext"><code class="literal">gettext</code></a> toolset. It provides
|
|
scons interface to <span class="command"><strong>xgettext(1)</strong></span>
|
|
program, which extracts internationalized messages from source code. The tool
|
|
provides <code class="function">POTUpdate</code> builder to make <code class="literal">PO</code>
|
|
<span class="emphasis"><em>Template</em></span> files.
|
|
</p><p>Sets: <a class="link" href="#cv-POTSUFFIX"><code class="envar">$POTSUFFIX</code></a>, <a class="link" href="#cv-POTUPDATE_ALIAS"><code class="envar">$POTUPDATE_ALIAS</code></a>, <a class="link" href="#cv-XGETTEXTCOM"><code class="envar">$XGETTEXTCOM</code></a>, <a class="link" href="#cv-XGETTEXTCOMSTR"><code class="envar">$XGETTEXTCOMSTR</code></a>, <a class="link" href="#cv-XGETTEXTFLAGS"><code class="envar">$XGETTEXTFLAGS</code></a>, <a class="link" href="#cv-XGETTEXTFROM"><code class="envar">$XGETTEXTFROM</code></a>, <a class="link" href="#cv-XGETTEXTFROMPREFIX"><code class="envar">$XGETTEXTFROMPREFIX</code></a>, <a class="link" href="#cv-XGETTEXTFROMSUFFIX"><code class="envar">$XGETTEXTFROMSUFFIX</code></a>, <a class="link" href="#cv-XGETTEXTPATH"><code class="envar">$XGETTEXTPATH</code></a>, <a class="link" href="#cv-XGETTEXTPATHPREFIX"><code class="envar">$XGETTEXTPATHPREFIX</code></a>, <a class="link" href="#cv-XGETTEXTPATHSUFFIX"><code class="envar">$XGETTEXTPATHSUFFIX</code></a>, <a class="link" href="#cv-_XGETTEXTDOMAIN"><code class="envar">$_XGETTEXTDOMAIN</code></a>, <a class="link" href="#cv-_XGETTEXTFROMFLAGS"><code class="envar">$_XGETTEXTFROMFLAGS</code></a>, <a class="link" href="#cv-_XGETTEXTPATHFLAGS"><code class="envar">$_XGETTEXTPATHFLAGS</code></a>.</p><p>Uses: <a class="link" href="#cv-POTDOMAIN"><code class="envar">$POTDOMAIN</code></a>.</p></dd><dt><a name="t-yacc"></a><span class="term">yacc</span></dt><dd><p>
|
|
Sets construction variables for the <span class="application">yacc</span> parse generator.
|
|
</p><p>Sets: <a class="link" href="#cv-YACC"><code class="envar">$YACC</code></a>, <a class="link" href="#cv-YACCCOM"><code class="envar">$YACCCOM</code></a>, <a class="link" href="#cv-YACCFLAGS"><code class="envar">$YACCFLAGS</code></a>, <a class="link" href="#cv-YACCHFILESUFFIX"><code class="envar">$YACCHFILESUFFIX</code></a>, <a class="link" href="#cv-YACCHXXFILESUFFIX"><code class="envar">$YACCHXXFILESUFFIX</code></a>, <a class="link" href="#cv-YACCVCGFILESUFFIX"><code class="envar">$YACCVCGFILESUFFIX</code></a>.</p><p>Uses: <a class="link" href="#cv-YACCCOMSTR"><code class="envar">$YACCCOMSTR</code></a>.</p></dd><dt><a name="t-zip"></a><span class="term">zip</span></dt><dd><p>
|
|
Sets construction variables for the <span class="application">zip</span> archiver.
|
|
</p><p>Sets: <a class="link" href="#cv-ZIP"><code class="envar">$ZIP</code></a>, <a class="link" href="#cv-ZIPCOM"><code class="envar">$ZIPCOM</code></a>, <a class="link" href="#cv-ZIPCOMPRESSION"><code class="envar">$ZIPCOMPRESSION</code></a>, <a class="link" href="#cv-ZIPFLAGS"><code class="envar">$ZIPFLAGS</code></a>, <a class="link" href="#cv-ZIPSUFFIX"><code class="envar">$ZIPSUFFIX</code></a>.</p><p>Uses: <a class="link" href="#cv-ZIPCOMSTR"><code class="envar">$ZIPCOMSTR</code></a>.</p></dd></dl></div><p>Additionally, there is a "tool" named
|
|
<span class="bold"><strong>default</strong></span>
|
|
which configures the
|
|
environment with a default set of tools for the current platform.</p><p>On posix and cygwin platforms
|
|
the GNU tools (e.g. gcc) are preferred by SCons,
|
|
on Windows the Microsoft tools (e.g. msvc)
|
|
followed by MinGW are preferred by SCons,
|
|
and in OS/2 the IBM tools (e.g. icc) are preferred by SCons.</p></div><div class="refsect2" title="Builder Methods"><a name="builder_methods"></a><h3>Builder Methods</h3><p>Build rules are specified by calling a construction
|
|
environment's builder methods.
|
|
The arguments to the builder methods are
|
|
<span class="bold"><strong>target</strong></span>
|
|
(a list of targets to be built,
|
|
usually file names)
|
|
and
|
|
<span class="bold"><strong>source</strong></span>
|
|
(a list of sources to be built,
|
|
usually file names).</p><p>Because long lists of file names
|
|
can lead to a lot of quoting,
|
|
<span class="command"><strong>scons</strong></span>
|
|
supplies a
|
|
<span class="bold"><strong>Split()</strong></span>
|
|
global function
|
|
and a same-named environment method
|
|
that split a single string
|
|
into a list, separated on
|
|
strings of white-space characters.
|
|
(These are similar to the split() member function of Python strings
|
|
but work even if the input isn't a string.)</p><p>Like all Python arguments,
|
|
the target and source arguments to a builder method
|
|
can be specified either with or without
|
|
the "target" and "source" keywords.
|
|
When the keywords are omitted,
|
|
the target is first,
|
|
followed by the source.
|
|
The following are equivalent examples of calling the Program builder method:</p><pre class="literallayout">
|
|
env.Program('bar', ['bar.c', 'foo.c'])
|
|
env.Program('bar', Split('bar.c foo.c'))
|
|
env.Program('bar', env.Split('bar.c foo.c'))
|
|
env.Program(source = ['bar.c', 'foo.c'], target = 'bar')
|
|
env.Program(target = 'bar', Split('bar.c foo.c'))
|
|
env.Program(target = 'bar', env.Split('bar.c foo.c'))
|
|
env.Program('bar', source = 'bar.c foo.c'.split())
|
|
</pre><p>Target and source file names
|
|
that are not absolute path names
|
|
(that is, do not begin with
|
|
<span class="bold"><strong>/</strong></span>
|
|
on POSIX systems
|
|
or
|
|
<span class="bold"><strong>\fR
|
|
on Windows systems,
|
|
with or without
|
|
an optional drive letter)
|
|
are interpreted relative to the directory containing the
|
|
SConscript</strong></span>
|
|
file being read.
|
|
An initial
|
|
<span class="bold"><strong>#</strong></span>
|
|
(hash mark)
|
|
on a path name means that the rest of the file name
|
|
is interpreted relative to
|
|
the directory containing
|
|
the top-level
|
|
<span class="bold"><strong>SConstruct</strong></span>
|
|
file,
|
|
even if the
|
|
<span class="bold"><strong>#</strong></span>
|
|
is followed by a directory separator character
|
|
(slash or backslash).</p><p>Examples:</p><pre class="programlisting">
|
|
# The comments describing the targets that will be built
|
|
# assume these calls are in a SConscript file in the
|
|
# a subdirectory named "subdir".
|
|
|
|
# Builds the program "subdir/foo" from "subdir/foo.c":
|
|
env.Program('foo', 'foo.c')
|
|
|
|
# Builds the program "/tmp/bar" from "subdir/bar.c":
|
|
env.Program('/tmp/bar', 'bar.c')
|
|
|
|
# An initial '#' or '#/' are equivalent; the following
|
|
# calls build the programs "foo" and "bar" (in the
|
|
# top-level SConstruct directory) from "subdir/foo.c" and
|
|
# "subdir/bar.c", respectively:
|
|
env.Program('#foo', 'foo.c')
|
|
env.Program('#/bar', 'bar.c')
|
|
|
|
# Builds the program "other/foo" (relative to the top-level
|
|
# SConstruct directory) from "subdir/foo.c":
|
|
env.Program('#other/foo', 'foo.c')
|
|
</pre><p>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
|
|
<span class="command"><strong>scons</strong></span>
|
|
will deduce the target file name from
|
|
the source file name.
|
|
The following examples all build the
|
|
executable program
|
|
<span class="bold"><strong>bar</strong></span>
|
|
(on POSIX systems)
|
|
or
|
|
<span class="bold"><strong>bar.exe</strong></span>
|
|
(on Windows systems)
|
|
from the bar.c source file:</p><pre class="literallayout">
|
|
env.Program(target = 'bar', source = 'bar.c')
|
|
env.Program('bar', source = 'bar.c')
|
|
env.Program(source = 'bar.c')
|
|
env.Program('bar.c')
|
|
</pre><p>As a convenience, a
|
|
<span class="bold"><strong>srcdir</strong></span>
|
|
keyword argument may be specified
|
|
when calling a Builder.
|
|
When specified,
|
|
all source file strings that are not absolute paths
|
|
will be interpreted relative to the specified
|
|
<span class="bold"><strong>srcdir</strong></span>.
|
|
The following example will build the
|
|
<span class="bold"><strong>build/prog</strong></span>
|
|
(or
|
|
<span class="bold"><strong>build/prog.exe</strong></span>
|
|
on Windows)
|
|
program from the files
|
|
<span class="bold"><strong>src/f1.c</strong></span>
|
|
and
|
|
<span class="bold"><strong>src/f2.c</strong></span>:</p><pre class="literallayout">
|
|
env.Program('build/prog', ['f1.c', 'f2.c'], srcdir='src')
|
|
</pre><p>It is possible to override or add construction variables when calling a
|
|
builder method by passing additional keyword arguments.
|
|
These overridden or added
|
|
variables will only be in effect when building the target, so they will not
|
|
affect other parts of the build. For example, if you want to add additional
|
|
libraries for just one program:</p><pre class="literallayout">
|
|
env.Program('hello', 'hello.c', LIBS=['gl', 'glut'])
|
|
</pre><p>or generate a shared library with a non-standard suffix:</p><pre class="literallayout">
|
|
env.SharedLibrary('word', 'word.cpp',
|
|
SHLIBSUFFIX='.ocx',
|
|
LIBSUFFIXES=['.ocx'])
|
|
</pre><p>(Note that both the $SHLIBSUFFIX and $LIBSUFFIXES variables must be set
|
|
if you want SCons to search automatically
|
|
for dependencies on the non-standard library names;
|
|
see the descriptions of these variables, below, for more information.)</p><p>It is also possible to use the
|
|
<span class="emphasis"><em>parse_flags</em></span>
|
|
keyword argument in an override:</p><pre class="literallayout">
|
|
env = Program('hello', 'hello.c', parse_flags = '-Iinclude -DEBUG -lm')
|
|
</pre><p>This example adds 'include' to
|
|
<span class="bold"><strong>CPPPATH</strong></span>,
|
|
'EBUG' to
|
|
<span class="bold"><strong>CPPDEFINES</strong></span>,
|
|
and 'm' to
|
|
<span class="bold"><strong>LIBS</strong></span>.</p><p>Although the builder methods defined by
|
|
<span class="command"><strong>scons</strong></span>
|
|
are, in fact,
|
|
methods of a construction environment object,
|
|
they may also be called without an explicit environment:</p><pre class="literallayout">
|
|
Program('hello', 'hello.c')
|
|
SharedLibrary('word', 'word.cpp')
|
|
</pre><p>In this case,
|
|
the methods are called internally using a default construction
|
|
environment that consists of the tools and values that
|
|
<span class="command"><strong>scons</strong></span>
|
|
has determined are appropriate for the local system.</p><p>Builder methods that can be called without an explicit
|
|
environment may be called from custom Python modules that you
|
|
import into an SConscript file by adding the following
|
|
to the Python module:</p><pre class="literallayout">
|
|
from SCons.Script import *
|
|
</pre><p>All builder methods return a list-like object
|
|
containing Nodes that
|
|
represent the target or targets that will be built.
|
|
A
|
|
<span class="emphasis"><em>Node</em></span>
|
|
is an internal SCons object
|
|
which represents
|
|
build targets or sources.</p><p>The returned Node-list object
|
|
can be passed to other builder methods as source(s)
|
|
or passed to any SCons function or method
|
|
where a filename would normally be accepted.
|
|
For example, if it were necessary
|
|
to add a specific
|
|
<code class="option">-D</code>
|
|
flag when compiling one specific object file:</p><pre class="literallayout">
|
|
bar_obj_list = env.StaticObject('bar.c', CPPDEFINES='-DBAR')
|
|
env.Program(source = ['foo.c', bar_obj_list, 'main.c'])
|
|
</pre><p>Using a Node in this way
|
|
makes for a more portable build
|
|
by avoiding having to specify
|
|
a platform-specific object suffix
|
|
when calling the Program() builder method.</p><p>Note that Builder calls will automatically "flatten"
|
|
the source and target file lists,
|
|
so it's all right to have the bar_obj list
|
|
return by the StaticObject() call
|
|
in the middle of the source file list.
|
|
If you need to manipulate a list of lists returned by Builders
|
|
directly using Python,
|
|
you can either build the list by hand:</p><pre class="literallayout">
|
|
foo = Object('foo.c')
|
|
bar = Object('bar.c')
|
|
objects = ['begin.o'] + foo + ['middle.o'] + bar + ['end.o']
|
|
for object in objects:
|
|
print(str(object))
|
|
</pre><p>Or you can use the
|
|
<span class="bold"><strong>Flatten</strong></span>()
|
|
function supplied by scons
|
|
to create a list containing just the Nodes,
|
|
which may be more convenient:</p><pre class="literallayout">
|
|
foo = Object('foo.c')
|
|
bar = Object('bar.c')
|
|
objects = Flatten(['begin.o', foo, 'middle.o', bar, 'end.o'])
|
|
for object in objects:
|
|
print(str(object))
|
|
</pre><p>Note also that because Builder calls return
|
|
a list-like object, not an actual Python list,
|
|
you should
|
|
<span class="emphasis"><em>not</em></span>
|
|
use the Python
|
|
<span class="bold"><strong>+=</strong></span>
|
|
operator to append Builder results to a Python list.
|
|
Because the list and the object are different types,
|
|
Python will not update the original list in place,
|
|
but will instead create a new Node-list object
|
|
containing the concatenation of the list
|
|
elements and the Builder results.
|
|
This will cause problems for any other Python variables
|
|
in your SCons configuration
|
|
that still hold on to a reference to the original list.
|
|
Instead, use the Python
|
|
<span class="markup">.extend()</span>
|
|
method to make sure the list is updated in-place.
|
|
Example:</p><pre class="literallayout">
|
|
object_files = []
|
|
|
|
# Do NOT use += as follows:
|
|
#
|
|
# object_files += Object('bar.c')
|
|
#
|
|
# It will not update the object_files list in place.
|
|
#
|
|
# Instead, use the .extend() method:
|
|
object_files.extend(Object('bar.c'))
|
|
|
|
</pre><p>The path name for a Node's file may be used
|
|
by passing the Node to the Python-builtin
|
|
<code class="function">str()</code>
|
|
function:</p><pre class="literallayout">
|
|
bar_obj_list = env.StaticObject('bar.c', CPPDEFINES='-DBAR')
|
|
print("The path to bar_obj is:", str(bar_obj_list[0]))
|
|
</pre><p>Note again that because the Builder call returns a list,
|
|
we have to access the first element in the list
|
|
<span class="bold"><strong>(bar_obj_list[0])</strong></span>
|
|
to get at the Node that actually represents
|
|
the object file.</p><p>Builder calls support a
|
|
<span class="bold"><strong>chdir</strong></span>
|
|
keyword argument that
|
|
specifies that the Builder's action(s)
|
|
should be executed
|
|
after changing directory.
|
|
If the
|
|
<span class="bold"><strong>chdir</strong></span>
|
|
argument is
|
|
a string or a directory Node,
|
|
scons will change to the specified directory.
|
|
If the
|
|
<span class="bold"><strong>chdir</strong></span>
|
|
is not a string or Node
|
|
and is non-zero,
|
|
then scons will change to the
|
|
target file's directory.</p><pre class="literallayout">
|
|
# scons will change to the "sub" subdirectory
|
|
# before executing the "cp" command.
|
|
env.Command('sub/dir/foo.out', 'sub/dir/foo.in',
|
|
"cp dir/foo.in dir/foo.out",
|
|
chdir='sub')
|
|
|
|
# Because chdir is not a string, scons will change to the
|
|
# target's directory ("sub/dir") before executing the
|
|
# "cp" command.
|
|
env.Command('sub/dir/foo.out', 'sub/dir/foo.in',
|
|
"cp foo.in foo.out",
|
|
chdir=1)
|
|
</pre><p>Note that scons will
|
|
<span class="emphasis"><em>not</em></span>
|
|
automatically modify
|
|
its expansion of
|
|
construction variables like
|
|
<span class="bold"><strong>$TARGET</strong></span>
|
|
and
|
|
<span class="bold"><strong>$SOURCE</strong></span>
|
|
when using the chdir
|
|
keyword argument--that is,
|
|
the expanded file names
|
|
will still be relative to
|
|
the top-level SConstruct directory,
|
|
and consequently incorrect
|
|
relative to the chdir directory.
|
|
If you use the chdir keyword argument,
|
|
you will typically need to supply a different
|
|
command line using
|
|
expansions like
|
|
<span class="bold"><strong>${TARGET.file}</strong></span>
|
|
and
|
|
<span class="bold"><strong>${SOURCE.file}</strong></span>
|
|
to use just the filename portion of the
|
|
targets and source.</p><p><span class="command"><strong>scons</strong></span>
|
|
provides the following builder methods:</p><div class="variablelist"><dl><dt><a name="b-CFile"></a><span class="term">
|
|
<code class="function">CFile()</code>
|
|
, </span><span class="term">
|
|
<code class="function">env.CFile()</code>
|
|
</span></dt><dd><p>
|
|
Builds a C source file given a lex (<code class="filename">.l</code>)
|
|
or yacc (<code class="filename">.y</code>) input file.
|
|
The suffix specified by the <a class="link" href="#cv-CFILESUFFIX"><code class="envar">$CFILESUFFIX</code></a> construction variable
|
|
(<code class="filename">.c</code> by default)
|
|
is automatically added to the target
|
|
if it is not already present.
|
|
Example:
|
|
</p><pre class="screen">
|
|
# builds foo.c
|
|
env.CFile(target = 'foo.c', source = 'foo.l')
|
|
# builds bar.c
|
|
env.CFile(target = 'bar', source = 'bar.y')
|
|
</pre></dd><dt><a name="b-Command"></a><span class="term">
|
|
<code class="function">Command()</code>
|
|
, </span><span class="term">
|
|
<code class="function">env.Command()</code>
|
|
</span></dt><dd><p>
|
|
The <code class="function">Command</code> "Builder" is actually implemented
|
|
as a function that looks like a Builder,
|
|
but actually takes an additional argument of the action
|
|
from which the Builder should be made.
|
|
See the <a class="link" href="#f-Command"><code class="function">Command</code></a> function description
|
|
for the calling syntax and details.
|
|
</p></dd><dt><a name="b-CXXFile"></a><span class="term">
|
|
<code class="function">CXXFile()</code>
|
|
, </span><span class="term">
|
|
<code class="function">env.CXXFile()</code>
|
|
</span></dt><dd><p>
|
|
Builds a C++ source file given a lex (<code class="filename">.ll</code>)
|
|
or yacc (<code class="filename">.yy</code>)
|
|
input file.
|
|
The suffix specified by the <a class="link" href="#cv-CXXFILESUFFIX"><code class="envar">$CXXFILESUFFIX</code></a> construction variable
|
|
(<code class="filename">.cc</code> by default)
|
|
is automatically added to the target
|
|
if it is not already present.
|
|
Example:
|
|
</p><pre class="screen">
|
|
# builds foo.cc
|
|
env.CXXFile(target = 'foo.cc', source = 'foo.ll')
|
|
# builds bar.cc
|
|
env.CXXFile(target = 'bar', source = 'bar.yy')
|
|
</pre></dd><dt><a name="b-DocbookEpub"></a><span class="term">
|
|
<code class="function">DocbookEpub()</code>
|
|
, </span><span class="term">
|
|
<code class="function">env.DocbookEpub()</code>
|
|
</span></dt><dd><p>
|
|
A pseudo-Builder, providing a Docbook toolchain for EPUB output.
|
|
</p><pre class="screen">env = Environment(tools=['docbook'])
|
|
env.DocbookEpub('manual.epub', 'manual.xml')
|
|
</pre><p>
|
|
or simply
|
|
</p><pre class="screen">env = Environment(tools=['docbook'])
|
|
env.DocbookEpub('manual')
|
|
</pre></dd><dt><a name="b-DocbookHtml"></a><span class="term">
|
|
<code class="function">DocbookHtml()</code>
|
|
, </span><span class="term">
|
|
<code class="function">env.DocbookHtml()</code>
|
|
</span></dt><dd><p>
|
|
A pseudo-Builder, providing a Docbook toolchain for HTML output.
|
|
</p><pre class="screen">env = Environment(tools=['docbook'])
|
|
env.DocbookHtml('manual.html', 'manual.xml')
|
|
</pre><p>
|
|
or simply
|
|
</p><pre class="screen">env = Environment(tools=['docbook'])
|
|
env.DocbookHtml('manual')
|
|
</pre></dd><dt><a name="b-DocbookHtmlChunked"></a><span class="term">
|
|
<code class="function">DocbookHtmlChunked()</code>
|
|
, </span><span class="term">
|
|
<code class="function">env.DocbookHtmlChunked()</code>
|
|
</span></dt><dd><p>
|
|
A pseudo-Builder, providing a Docbook toolchain for chunked HTML output.
|
|
It supports the <code class="literal">base.dir</code> parameter. The
|
|
<code class="filename">chunkfast.xsl</code> file (requires "EXSLT") is used as the
|
|
default stylesheet. Basic syntax:
|
|
</p><pre class="screen">env = Environment(tools=['docbook'])
|
|
env.DocbookHtmlChunked('manual')
|
|
</pre><p>
|
|
where <code class="filename">manual.xml</code> is the input file.
|
|
</p><p>If you use the <code class="literal">root.filename</code>
|
|
parameter in your own stylesheets you have to specify the new target name.
|
|
This ensures that the dependencies get correct, especially for the cleanup via <span class="quote">“<span class="quote"><code class="literal">scons -c</code></span>”</span>:
|
|
</p><pre class="screen">env = Environment(tools=['docbook'])
|
|
env.DocbookHtmlChunked('mymanual.html', 'manual', xsl='htmlchunk.xsl')
|
|
</pre><p>Some basic support for the <code class="literal">base.dir</code> is provided. You
|
|
can add the <code class="literal">base_dir</code> keyword to your Builder
|
|
call, and the given prefix gets prepended to all the created filenames:
|
|
</p><pre class="screen">env = Environment(tools=['docbook'])
|
|
env.DocbookHtmlChunked('manual', xsl='htmlchunk.xsl', base_dir='output/')
|
|
</pre><p>Make sure that you don't forget the trailing slash for the base folder, else
|
|
your files get renamed only!
|
|
</p></dd><dt><a name="b-DocbookHtmlhelp"></a><span class="term">
|
|
<code class="function">DocbookHtmlhelp()</code>
|
|
, </span><span class="term">
|
|
<code class="function">env.DocbookHtmlhelp()</code>
|
|
</span></dt><dd><p>
|
|
A pseudo-Builder, providing a Docbook toolchain for HTMLHELP output.
|
|
Its basic syntax is:
|
|
</p><pre class="screen">env = Environment(tools=['docbook'])
|
|
env.DocbookHtmlhelp('manual')
|
|
</pre><p>
|
|
where <code class="filename">manual.xml</code> is the input file.
|
|
</p><p>If you use the <code class="literal">root.filename</code>
|
|
parameter in your own stylesheets you have to specify the new target name.
|
|
This ensures that the dependencies get correct, especially for the cleanup via <span class="quote">“<span class="quote"><code class="literal">scons -c</code></span>”</span>:
|
|
</p><pre class="screen">env = Environment(tools=['docbook'])
|
|
env.DocbookHtmlhelp('mymanual.html', 'manual', xsl='htmlhelp.xsl')
|
|
</pre><p>Some basic support for the <code class="literal">base.dir</code> parameter
|
|
is provided. You can add the <code class="literal">base_dir</code> keyword to
|
|
your Builder call, and the given prefix gets prepended to all the
|
|
created filenames:
|
|
</p><pre class="screen">env = Environment(tools=['docbook'])
|
|
env.DocbookHtmlhelp('manual', xsl='htmlhelp.xsl', base_dir='output/')
|
|
</pre><p>Make sure that you don't forget the trailing slash for the base folder, else
|
|
your files get renamed only!
|
|
</p></dd><dt><a name="b-DocbookMan"></a><span class="term">
|
|
<code class="function">DocbookMan()</code>
|
|
, </span><span class="term">
|
|
<code class="function">env.DocbookMan()</code>
|
|
</span></dt><dd><p>
|
|
A pseudo-Builder, providing a Docbook toolchain for Man page output.
|
|
Its basic syntax is:
|
|
</p><pre class="screen">env = Environment(tools=['docbook'])
|
|
env.DocbookMan('manual')
|
|
</pre><p>
|
|
where <code class="filename">manual.xml</code> is the input file. Note, that
|
|
you can specify a target name, but the actual output names are automatically
|
|
set from the <code class="literal">refname</code> entries in your XML source.
|
|
</p></dd><dt><a name="b-DocbookPdf"></a><span class="term">
|
|
<code class="function">DocbookPdf()</code>
|
|
, </span><span class="term">
|
|
<code class="function">env.DocbookPdf()</code>
|
|
</span></dt><dd><p>
|
|
A pseudo-Builder, providing a Docbook toolchain for PDF output.
|
|
</p><pre class="screen">env = Environment(tools=['docbook'])
|
|
env.DocbookPdf('manual.pdf', 'manual.xml')
|
|
</pre><p>
|
|
or simply
|
|
</p><pre class="screen">env = Environment(tools=['docbook'])
|
|
env.DocbookPdf('manual')
|
|
</pre></dd><dt><a name="b-DocbookSlidesHtml"></a><span class="term">
|
|
<code class="function">DocbookSlidesHtml()</code>
|
|
, </span><span class="term">
|
|
<code class="function">env.DocbookSlidesHtml()</code>
|
|
</span></dt><dd><p>
|
|
A pseudo-Builder, providing a Docbook toolchain for HTML slides output.
|
|
</p><pre class="screen">env = Environment(tools=['docbook'])
|
|
env.DocbookSlidesHtml('manual')
|
|
</pre><p>If you use the <code class="literal">titlefoil.html</code> parameter in
|
|
your own stylesheets you have to give the new target name. This ensures
|
|
that the dependencies get correct, especially for the cleanup via
|
|
<span class="quote">“<span class="quote"><code class="literal">scons -c</code></span>”</span>:
|
|
</p><pre class="screen">env = Environment(tools=['docbook'])
|
|
env.DocbookSlidesHtml('mymanual.html','manual', xsl='slideshtml.xsl')
|
|
</pre><p>Some basic support for the <code class="literal">base.dir</code> parameter
|
|
is provided. You
|
|
can add the <code class="literal">base_dir</code> keyword to your Builder
|
|
call, and the given prefix gets prepended to all the created filenames:
|
|
</p><pre class="screen">env = Environment(tools=['docbook'])
|
|
env.DocbookSlidesHtml('manual', xsl='slideshtml.xsl', base_dir='output/')
|
|
</pre><p>Make sure that you don't forget the trailing slash for the base folder, else
|
|
your files get renamed only!
|
|
</p></dd><dt><a name="b-DocbookSlidesPdf"></a><span class="term">
|
|
<code class="function">DocbookSlidesPdf()</code>
|
|
, </span><span class="term">
|
|
<code class="function">env.DocbookSlidesPdf()</code>
|
|
</span></dt><dd><p>
|
|
A pseudo-Builder, providing a Docbook toolchain for PDF slides output.
|
|
</p><pre class="screen">env = Environment(tools=['docbook'])
|
|
env.DocbookSlidesPdf('manual.pdf', 'manual.xml')
|
|
</pre><p>
|
|
or simply
|
|
</p><pre class="screen">env = Environment(tools=['docbook'])
|
|
env.DocbookSlidesPdf('manual')
|
|
</pre></dd><dt><a name="b-DocbookXInclude"></a><span class="term">
|
|
<code class="function">DocbookXInclude()</code>
|
|
, </span><span class="term">
|
|
<code class="function">env.DocbookXInclude()</code>
|
|
</span></dt><dd><p>
|
|
A pseudo-Builder, for resolving XIncludes in a separate processing step.
|
|
</p><pre class="screen">env = Environment(tools=['docbook'])
|
|
env.DocbookXInclude('manual_xincluded.xml', 'manual.xml')
|
|
</pre></dd><dt><a name="b-DocbookXslt"></a><span class="term">
|
|
<code class="function">DocbookXslt()</code>
|
|
, </span><span class="term">
|
|
<code class="function">env.DocbookXslt()</code>
|
|
</span></dt><dd><p>
|
|
A pseudo-Builder, applying a given XSL transformation to the input file.
|
|
</p><pre class="screen">env = Environment(tools=['docbook'])
|
|
env.DocbookXslt('manual_transformed.xml', 'manual.xml', xsl='transform.xslt')
|
|
</pre><p>Note, that this builder requires the <code class="literal">xsl</code> parameter
|
|
to be set.
|
|
</p></dd><dt><a name="b-DVI"></a><span class="term">
|
|
<code class="function">DVI()</code>
|
|
, </span><span class="term">
|
|
<code class="function">env.DVI()</code>
|
|
</span></dt><dd><p>
|
|
Builds a <code class="filename">.dvi</code> file
|
|
from a <code class="filename">.tex</code>,
|
|
<code class="filename">.ltx</code> or <code class="filename">.latex</code> input file.
|
|
If the source file suffix is <code class="filename">.tex</code>,
|
|
<code class="filename">scons</code>
|
|
will examine the contents of the file;
|
|
if the string
|
|
<code class="literal">\documentclass</code>
|
|
or
|
|
<code class="literal">\documentstyle</code>
|
|
is found, the file is assumed to be a LaTeX file and
|
|
the target is built by invoking the <a class="link" href="#cv-LATEXCOM"><code class="envar">$LATEXCOM</code></a> command line;
|
|
otherwise, the <a class="link" href="#cv-TEXCOM"><code class="envar">$TEXCOM</code></a> command line is used.
|
|
If the file is a LaTeX file,
|
|
the
|
|
<code class="function">DVI</code>
|
|
builder method will also examine the contents
|
|
of the
|
|
<code class="filename">.aux</code>
|
|
file and invoke the <a class="link" href="#cv-BIBTEX"><code class="envar">$BIBTEX</code></a> command line
|
|
if the string
|
|
<code class="literal">bibdata</code>
|
|
is found,
|
|
start <a class="link" href="#cv-MAKEINDEX"><code class="envar">$MAKEINDEX</code></a> to generate an index if a
|
|
<code class="filename">.ind</code>
|
|
file is found
|
|
and will examine the contents
|
|
<code class="filename">.log</code>
|
|
file and re-run the <a class="link" href="#cv-LATEXCOM"><code class="envar">$LATEXCOM</code></a> command
|
|
if the log file says it is necessary.
|
|
</p><p>
|
|
The suffix <code class="filename">.dvi</code>
|
|
(hard-coded within TeX itself)
|
|
is automatically added to the target
|
|
if it is not already present.
|
|
Examples:
|
|
</p><pre class="screen">
|
|
# builds from aaa.tex
|
|
env.DVI(target = 'aaa.dvi', source = 'aaa.tex')
|
|
# builds bbb.dvi
|
|
env.DVI(target = 'bbb', source = 'bbb.ltx')
|
|
# builds from ccc.latex
|
|
env.DVI(target = 'ccc.dvi', source = 'ccc.latex')
|
|
</pre></dd><dt><a name="b-Gs"></a><span class="term">
|
|
<code class="function">Gs()</code>
|
|
, </span><span class="term">
|
|
<code class="function">env.Gs()</code>
|
|
</span></dt><dd><p>
|
|
A Builder for explicitly calling the <code class="literal">gs</code> executable.
|
|
Depending on the underlying OS, the different names <code class="literal">gs</code>,
|
|
<code class="literal">gsos2</code> and <code class="literal">gswin32c</code>
|
|
are tried.
|
|
</p><pre class="screen">env = Environment(tools=['gs'])
|
|
env.Gs('cover.jpg','scons-scons.pdf',
|
|
GSFLAGS='-dNOPAUSE -dBATCH -sDEVICE=jpeg -dFirstPage=1 -dLastPage=1 -q')
|
|
)
|
|
</pre></dd><dt><a name="b-Install"></a><span class="term">
|
|
<code class="function">Install()</code>
|
|
, </span><span class="term">
|
|
<code class="function">env.Install()</code>
|
|
</span></dt><dd><p>
|
|
Installs one or more source files or directories
|
|
in the specified target,
|
|
which must be a directory.
|
|
The names of the specified source files or directories
|
|
remain the same within the destination directory. The
|
|
sources may be given as a string or as a node returned by
|
|
a builder.
|
|
</p><pre class="screen">
|
|
env.Install('/usr/local/bin', source = ['foo', 'bar'])
|
|
</pre></dd><dt><a name="b-InstallAs"></a><span class="term">
|
|
<code class="function">InstallAs()</code>
|
|
, </span><span class="term">
|
|
<code class="function">env.InstallAs()</code>
|
|
</span></dt><dd><p>
|
|
Installs one or more source files or directories
|
|
to specific names,
|
|
allowing changing a file or directory name
|
|
as part of the installation.
|
|
It is an error if the
|
|
target
|
|
and
|
|
source
|
|
arguments list different numbers of files or directories.
|
|
</p><pre class="screen">
|
|
env.InstallAs(target = '/usr/local/bin/foo',
|
|
source = 'foo_debug')
|
|
env.InstallAs(target = ['../lib/libfoo.a', '../lib/libbar.a'],
|
|
source = ['libFOO.a', 'libBAR.a'])
|
|
</pre></dd><dt><a name="b-InstallVersionedLib"></a><span class="term">
|
|
<code class="function">InstallVersionedLib()</code>
|
|
, </span><span class="term">
|
|
<code class="function">env.InstallVersionedLib()</code>
|
|
</span></dt><dd><p>
|
|
Installs a versioned shared library. The symlinks appropriate to the
|
|
architecture will be generated based on symlinks of the source library.
|
|
</p><pre class="screen">
|
|
env.InstallVersionedLib(target = '/usr/local/bin/foo',
|
|
source = 'libxyz.1.5.2.so')
|
|
</pre></dd><dt><a name="b-Jar"></a><span class="term">
|
|
<code class="function">Jar()</code>
|
|
, </span><span class="term">
|
|
<code class="function">env.Jar()</code>
|
|
</span></dt><dd><p>
|
|
Builds a Java archive (<code class="filename">.jar</code>) file
|
|
from the specified list of sources.
|
|
Any directories in the source list
|
|
will be searched for <code class="filename">.class</code> files).
|
|
Any <code class="filename">.java</code> files in the source list
|
|
will be compiled to <code class="filename">.class</code> files
|
|
by calling the <a class="link" href="#b-Java"><code class="function">Java</code></a> Builder.
|
|
</p><p>
|
|
If the <a class="link" href="#cv-JARCHDIR"><code class="envar">$JARCHDIR</code></a> value is set, the
|
|
<span class="application">jar</span>
|
|
command will change to the specified directory using the
|
|
<code class="option">-C</code>
|
|
option.
|
|
If <code class="envar">$JARCHDIR</code> is not set explicitly,
|
|
<span class="application">SCons</span> will use the top of any subdirectory tree
|
|
in which Java <code class="filename">.class</code>
|
|
were built by the <a class="link" href="#b-Java"><code class="function">Java</code></a> Builder.
|
|
</p><p>
|
|
If the contents any of the source files begin with the string
|
|
<code class="literal">Manifest-Version</code>,
|
|
the file is assumed to be a manifest
|
|
and is passed to the
|
|
<span class="application">jar</span>
|
|
command with the
|
|
<code class="option">m</code>
|
|
option set.
|
|
</p><pre class="screen">
|
|
env.Jar(target = 'foo.jar', source = 'classes')
|
|
|
|
env.Jar(target = 'bar.jar',
|
|
source = ['bar1.java', 'bar2.java'])
|
|
</pre></dd><dt><a name="b-Java"></a><span class="term">
|
|
<code class="function">Java()</code>
|
|
, </span><span class="term">
|
|
<code class="function">env.Java()</code>
|
|
</span></dt><dd><p>
|
|
Builds one or more Java class files.
|
|
The sources may be any combination of explicit
|
|
<code class="filename">.java</code>
|
|
files,
|
|
or directory trees which will be scanned
|
|
for <code class="filename">.java</code> files.
|
|
</p><p>
|
|
SCons will parse each source <code class="filename">.java</code> file
|
|
to find the classes
|
|
(including inner classes)
|
|
defined within that file,
|
|
and from that figure out the
|
|
target <code class="filename">.class</code> files that will be created.
|
|
The class files will be placed underneath
|
|
the specified target directory.
|
|
</p><p>
|
|
SCons will also search each Java file
|
|
for the Java package name,
|
|
which it assumes can be found on a line
|
|
beginning with the string
|
|
<code class="literal">package</code>
|
|
in the first column;
|
|
the resulting <code class="filename">.class</code> files
|
|
will be placed in a directory reflecting
|
|
the specified package name.
|
|
For example,
|
|
the file
|
|
<code class="filename">Foo.java</code>
|
|
defining a single public
|
|
<code class="classname">Foo</code>
|
|
class and
|
|
containing a package name of
|
|
<code class="classname">sub.dir</code>
|
|
will generate a corresponding
|
|
<code class="filename">sub/dir/Foo.class</code>
|
|
class file.
|
|
</p><p>
|
|
Examples:
|
|
</p><pre class="screen">
|
|
env.Java(target = 'classes', source = 'src')
|
|
env.Java(target = 'classes', source = ['src1', 'src2'])
|
|
env.Java(target = 'classes', source = ['File1.java', 'File2.java'])
|
|
</pre><p>
|
|
Java source files can use the native encoding for the underlying OS.
|
|
Since SCons compiles in simple ASCII mode by default,
|
|
the compiler will generate warnings about unmappable characters,
|
|
which may lead to errors as the file is processed further.
|
|
In this case, the user must specify the
|
|
<code class="literal">LANG</code>
|
|
environment variable to tell the compiler what encoding is used.
|
|
For portibility, it's best if the encoding is hard-coded
|
|
so that the compile will work if it is done on a system
|
|
with a different encoding.
|
|
</p><pre class="screen">
|
|
env = Environment()
|
|
env['ENV']['LANG'] = 'en_GB.UTF-8'
|
|
</pre></dd><dt><a name="b-JavaH"></a><span class="term">
|
|
<code class="function">JavaH()</code>
|
|
, </span><span class="term">
|
|
<code class="function">env.JavaH()</code>
|
|
</span></dt><dd><p>
|
|
Builds C header and source files for
|
|
implementing Java native methods.
|
|
The target can be either a directory
|
|
in which the header files will be written,
|
|
or a header file name which
|
|
will contain all of the definitions.
|
|
The source can be the names of <code class="filename">.class</code> files,
|
|
the names of <code class="filename">.java</code> files
|
|
to be compiled into <code class="filename">.class</code> files
|
|
by calling the <a class="link" href="#b-Java"><code class="function">Java</code></a> builder method,
|
|
or the objects returned from the
|
|
<code class="function">Java</code>
|
|
builder method.
|
|
</p><p>
|
|
If the construction variable
|
|
<a class="link" href="#cv-JAVACLASSDIR"><code class="envar">$JAVACLASSDIR</code></a>
|
|
is set, either in the environment
|
|
or in the call to the
|
|
<code class="function">JavaH</code>
|
|
builder method itself,
|
|
then the value of the variable
|
|
will be stripped from the
|
|
beginning of any <code class="filename">.class</code> file names.
|
|
</p><p>
|
|
Examples:
|
|
</p><pre class="screen">
|
|
# builds java_native.h
|
|
classes = env.Java(target = 'classdir', source = 'src')
|
|
env.JavaH(target = 'java_native.h', source = classes)
|
|
|
|
# builds include/package_foo.h and include/package_bar.h
|
|
env.JavaH(target = 'include',
|
|
source = ['package/foo.class', 'package/bar.class'])
|
|
|
|
# builds export/foo.h and export/bar.h
|
|
env.JavaH(target = 'export',
|
|
source = ['classes/foo.class', 'classes/bar.class'],
|
|
JAVACLASSDIR = 'classes')
|
|
</pre></dd><dt><a name="b-Library"></a><span class="term">
|
|
<code class="function">Library()</code>
|
|
, </span><span class="term">
|
|
<code class="function">env.Library()</code>
|
|
</span></dt><dd><p>
|
|
A synonym for the
|
|
<code class="function">StaticLibrary</code>
|
|
builder method.
|
|
</p></dd><dt><a name="b-LoadableModule"></a><span class="term">
|
|
<code class="function">LoadableModule()</code>
|
|
, </span><span class="term">
|
|
<code class="function">env.LoadableModule()</code>
|
|
</span></dt><dd><p>
|
|
On most systems,
|
|
this is the same as
|
|
<code class="function">SharedLibrary</code>.
|
|
On Mac OS X (Darwin) platforms,
|
|
this creates a loadable module bundle.
|
|
</p></dd><dt><a name="b-M4"></a><span class="term">
|
|
<code class="function">M4()</code>
|
|
, </span><span class="term">
|
|
<code class="function">env.M4()</code>
|
|
</span></dt><dd><p>
|
|
Builds an output file from an M4 input file.
|
|
This uses a default <a class="link" href="#cv-M4FLAGS"><code class="envar">$M4FLAGS</code></a> value of
|
|
<code class="option">-E</code>,
|
|
which considers all warnings to be fatal
|
|
and stops on the first warning
|
|
when using the GNU version of m4.
|
|
Example:
|
|
</p><pre class="screen">
|
|
env.M4(target = 'foo.c', source = 'foo.c.m4')
|
|
</pre></dd><dt><a name="b-Moc"></a><span class="term">
|
|
<code class="function">Moc()</code>
|
|
, </span><span class="term">
|
|
<code class="function">env.Moc()</code>
|
|
</span></dt><dd><p>
|
|
Builds an output file from a moc input file. Moc input files are either
|
|
header files or cxx files. This builder is only available after using the
|
|
tool 'qt'. See the <a class="link" href="#cv-QTDIR"><code class="envar">$QTDIR</code></a> variable for more information.
|
|
Example:
|
|
</p><pre class="screen">
|
|
env.Moc('foo.h') # generates moc_foo.cc
|
|
env.Moc('foo.cpp') # generates foo.moc
|
|
</pre></dd><dt><a name="b-MOFiles"></a><span class="term">
|
|
<code class="function">MOFiles()</code>
|
|
, </span><span class="term">
|
|
<code class="function">env.MOFiles()</code>
|
|
</span></dt><dd><p>
|
|
This builder belongs to <a class="link" href="#t-msgfmt"><code class="literal">msgfmt</code></a> tool. The builder compiles
|
|
<code class="literal">PO</code> files to <code class="literal">MO</code> files.
|
|
</p><p>
|
|
<span class="emphasis"><em>Example 1</em></span>.
|
|
Create <code class="filename">pl.mo</code> and <code class="filename">en.mo</code> by compiling
|
|
<code class="filename">pl.po</code> and <code class="filename">en.po</code>:
|
|
</p><pre class="screen">
|
|
# ...
|
|
env.MOFiles(['pl', 'en'])
|
|
</pre><p>
|
|
<span class="emphasis"><em>Example 2</em></span>.
|
|
Compile files for languages defined in <code class="filename">LINGUAS</code> file:
|
|
</p><pre class="screen">
|
|
# ...
|
|
env.MOFiles(LINGUAS_FILE = 1)
|
|
</pre><p>
|
|
<span class="emphasis"><em>Example 3</em></span>.
|
|
Create <code class="filename">pl.mo</code> and <code class="filename">en.mo</code> by compiling
|
|
<code class="filename">pl.po</code> and <code class="filename">en.po</code> plus files for
|
|
languages defined in <code class="filename">LINGUAS</code> file:
|
|
</p><pre class="screen">
|
|
# ...
|
|
env.MOFiles(['pl', 'en'], LINGUAS_FILE = 1)
|
|
</pre><p>
|
|
<span class="emphasis"><em>Example 4</em></span>.
|
|
Compile files for languages defined in <code class="filename">LINGUAS</code> file
|
|
(another version):
|
|
</p><pre class="screen">
|
|
# ...
|
|
env['LINGUAS_FILE'] = 1
|
|
env.MOFiles()
|
|
</pre></dd><dt><a name="b-MSVSProject"></a><span class="term">
|
|
<code class="function">MSVSProject()</code>
|
|
, </span><span class="term">
|
|
<code class="function">env.MSVSProject()</code>
|
|
</span></dt><dd><p> Builds a Microsoft Visual Studio project
|
|
file, and by default builds a solution file as well. </p><p> This
|
|
builds a Visual Studio project file, based on the version of Visual Studio
|
|
that is configured (either the latest installed version, or the version
|
|
specified by <a class="link" href="#cv-MSVS_VERSION"><code class="envar">$MSVS_VERSION</code></a> in the Environment constructor). For
|
|
Visual Studio 6, it will generate a <code class="filename">.dsp</code> file. For Visual
|
|
Studio 7 (.NET) and later versions, it will generate a
|
|
<code class="filename">.vcproj</code> file. </p><p> By default, this also
|
|
generates a solution file for the specified project, a
|
|
<code class="filename">.dsw</code> file for Visual Studio 6 or a
|
|
<code class="filename">.sln</code> file for Visual Studio 7 (.NET). This behavior may
|
|
be disabled by specifying <code class="literal">auto_build_solution=0</code> when you
|
|
call <code class="function">MSVSProject</code>, in which case you presumably want to build the solution
|
|
file(s) by calling the <code class="function">MSVSSolution</code> Builder (see below). </p><p>
|
|
The <code class="function">MSVSProject</code> builder takes several lists of filenames to be placed into
|
|
the project file. These are currently limited to <code class="literal">srcs</code>,
|
|
<code class="literal">incs</code>, <code class="literal">localincs</code>,
|
|
<code class="literal">resources</code>, and <code class="literal">misc</code>. These are pretty
|
|
self-explanatory, but it should be noted that these lists are added to the
|
|
<a class="link" href="#cv-SOURCES"><code class="envar">$SOURCES</code></a> construction variable as strings, NOT as SCons File Nodes.
|
|
This is because they represent file names to be added to the project file, not
|
|
the source files used to build the project file. </p><p> The above
|
|
filename lists are all optional, although at least one must be specified for
|
|
the resulting project file to be non-empty. </p><p> In addition to the
|
|
above lists of values, the following values may be specified:
|
|
</p><div class="variablelist"><dl><dt><span class="term">target</span></dt><dd><p>The name of the target <code class="filename">.dsp</code> or
|
|
<code class="filename">.vcproj</code> file. The correct suffix for the version
|
|
of Visual Studio must be used, but the <a class="link" href="#cv-MSVSPROJECTSUFFIX"><code class="envar">$MSVSPROJECTSUFFIX</code></a>
|
|
construction variable will be defined to the correct value (see
|
|
example below).</p></dd><dt><span class="term">variant</span></dt><dd><p>The name of this particular variant. For Visual Studio 7
|
|
projects, this can also be a list of variant names. These are
|
|
typically things like "Debug" or "Release", but really can be anything
|
|
you want. For Visual Studio 7 projects, they may also specify a target
|
|
platform separated from the variant name by a <code class="literal">|</code>
|
|
(vertical pipe) character: <code class="literal">Debug|Xbox</code>. The default
|
|
target platform is Win32. Multiple calls to <code class="function">MSVSProject</code> with
|
|
different variants are allowed; all variants will be added to the
|
|
project file with their appropriate build targets and
|
|
sources.</p></dd><dt><span class="term">cmdargs</span></dt><dd><p>Additional command line arguments for the different
|
|
variants. The number of <code class="literal">cmdargs</code> entries must match
|
|
the number of <code class="literal">variant</code> entries, or be empty (not
|
|
specified). If you give only one, it will automatically be propagated
|
|
to all variants.</p></dd><dt><span class="term">buildtarget</span></dt><dd><p>An optional string, node, or list of strings or nodes (one
|
|
per build variant), to tell the Visual Studio debugger what output
|
|
target to use in what build variant. The number of
|
|
<code class="literal">buildtarget</code> entries must match the number of
|
|
<code class="literal">variant</code> entries.</p></dd><dt><span class="term">runfile</span></dt><dd><p>The name of the file that Visual Studio 7 and later will
|
|
run and debug. This appears as the value of the
|
|
<code class="literal">Output</code> field in the resulting Visual Studio project
|
|
file. If this is not specified, the default is the same as the
|
|
specified <code class="literal">buildtarget</code> value.</p></dd></dl></div><p> Note that because <span class="application">SCons</span> always executes its build
|
|
commands from the directory in which the <code class="filename">SConstruct</code> file is located, if you
|
|
generate a project file in a different directory than the <code class="filename">SConstruct</code>
|
|
directory, users will not be able to double-click on the file name in
|
|
compilation error messages displayed in the Visual Studio console output
|
|
window. This can be remedied by adding the Visual C/C++ <code class="literal">/FC</code>
|
|
compiler option to the <a class="link" href="#cv-CCFLAGS"><code class="envar">$CCFLAGS</code></a> variable so that the compiler will
|
|
print the full path name of any files that cause compilation errors. </p><p> Example usage: </p><pre class="screen">
|
|
barsrcs = ['bar.cpp']
|
|
barincs = ['bar.h']
|
|
barlocalincs = ['StdAfx.h']
|
|
barresources = ['bar.rc','resource.h']
|
|
barmisc = ['bar_readme.txt']
|
|
|
|
dll = env.SharedLibrary(target = 'bar.dll',
|
|
source = barsrcs)
|
|
buildtarget = [s for s in dll if str(s).endswith('dll')]
|
|
env.MSVSProject(target = 'Bar' + env['MSVSPROJECTSUFFIX'],
|
|
srcs = barsrcs,
|
|
incs = barincs,
|
|
localincs = barlocalincs,
|
|
resources = barresources,
|
|
misc = barmisc,
|
|
buildtarget = buildtarget,
|
|
variant = 'Release')
|
|
</pre><p>Starting with version 2.4 of
|
|
SCons it's also possible to specify the optional argument
|
|
<em class="parameter"><code>DebugSettings</code></em>, which creates files for debugging under
|
|
Visual Studio:</p><div class="variablelist"><dl><dt><span class="term">DebugSettings</span></dt><dd><p>A dictionary of debug settings that get written to the
|
|
<code class="filename">.vcproj.user</code> or the
|
|
<code class="filename">.vcxproj.user</code> file, depending on the version
|
|
installed. As it is done for cmdargs (see above), you can specify a
|
|
<em class="parameter"><code>DebugSettings</code></em> dictionary per variant. If you
|
|
give only one, it will be propagated to all variants.</p></dd></dl></div><p>Currently, only Visual Studio v9.0 and Visual Studio
|
|
version v11 are implemented, for other versions no file is generated. To
|
|
generate the user file, you just need to add a
|
|
<em class="parameter"><code>DebugSettings</code></em> dictionary to the environment with the
|
|
right parameters for your MSVS version. If the dictionary is empty, or does
|
|
not contain any good value, no file will be generated.</p><p>Following
|
|
is a more contrived example, involving the setup of a project for variants and
|
|
DebugSettings:</p><pre class="screen"># Assuming you store your defaults in a file
|
|
vars = Variables('variables.py')
|
|
msvcver = vars.args.get('vc', '9')
|
|
|
|
# Check command args to force one Microsoft Visual Studio version
|
|
if msvcver == '9' or msvcver == '11':
|
|
env = Environment(MSVC_VERSION=msvcver+'.0', MSVC_BATCH=False)
|
|
else:
|
|
env = Environment()
|
|
|
|
AddOption('--userfile', action='store_true', dest='userfile', default=False,
|
|
help="Create Visual Studio Project user file")
|
|
|
|
#
|
|
# 1. Configure your Debug Setting dictionary with options you want in the list
|
|
# of allowed options, for instance if you want to create a user file to launch
|
|
# a specific application for testing your dll with Microsoft Visual Studio 2008 (v9):
|
|
#
|
|
V9DebugSettings = {
|
|
'Command':'c:\\myapp\\using\\thisdll.exe',
|
|
'WorkingDirectory': 'c:\\myapp\\using\\',
|
|
'CommandArguments': '-p password',
|
|
# 'Attach':'false',
|
|
# 'DebuggerType':'3',
|
|
# 'Remote':'1',
|
|
# 'RemoteMachine': None,
|
|
# 'RemoteCommand': None,
|
|
# 'HttpUrl': None,
|
|
# 'PDBPath': None,
|
|
# 'SQLDebugging': None,
|
|
# 'Environment': '',
|
|
# 'EnvironmentMerge':'true',
|
|
# 'DebuggerFlavor': None,
|
|
# 'MPIRunCommand': None,
|
|
# 'MPIRunArguments': None,
|
|
# 'MPIRunWorkingDirectory': None,
|
|
# 'ApplicationCommand': None,
|
|
# 'ApplicationArguments': None,
|
|
# 'ShimCommand': None,
|
|
# 'MPIAcceptMode': None,
|
|
# 'MPIAcceptFilter': None,
|
|
}
|
|
|
|
#
|
|
# 2. Because there are a lot of different options depending on the Microsoft
|
|
# Visual Studio version, if you use more than one version you have to
|
|
# define a dictionary per version, for instance if you want to create a user
|
|
# file to launch a specific application for testing your dll with Microsoft
|
|
# Visual Studio 2012 (v11):
|
|
#
|
|
V10DebugSettings = {
|
|
'LocalDebuggerCommand': 'c:\\myapp\\using\\thisdll.exe',
|
|
'LocalDebuggerWorkingDirectory': 'c:\\myapp\\using\\',
|
|
'LocalDebuggerCommandArguments': '-p password',
|
|
# 'LocalDebuggerEnvironment': None,
|
|
# 'DebuggerFlavor': 'WindowsLocalDebugger',
|
|
# 'LocalDebuggerAttach': None,
|
|
# 'LocalDebuggerDebuggerType': None,
|
|
# 'LocalDebuggerMergeEnvironment': None,
|
|
# 'LocalDebuggerSQLDebugging': None,
|
|
# 'RemoteDebuggerCommand': None,
|
|
# 'RemoteDebuggerCommandArguments': None,
|
|
# 'RemoteDebuggerWorkingDirectory': None,
|
|
# 'RemoteDebuggerServerName': None,
|
|
# 'RemoteDebuggerConnection': None,
|
|
# 'RemoteDebuggerDebuggerType': None,
|
|
# 'RemoteDebuggerAttach': None,
|
|
# 'RemoteDebuggerSQLDebugging': None,
|
|
# 'DeploymentDirectory': None,
|
|
# 'AdditionalFiles': None,
|
|
# 'RemoteDebuggerDeployDebugCppRuntime': None,
|
|
# 'WebBrowserDebuggerHttpUrl': None,
|
|
# 'WebBrowserDebuggerDebuggerType': None,
|
|
# 'WebServiceDebuggerHttpUrl': None,
|
|
# 'WebServiceDebuggerDebuggerType': None,
|
|
# 'WebServiceDebuggerSQLDebugging': None,
|
|
}
|
|
|
|
#
|
|
# 3. Select the dictionary you want depending on the version of visual Studio
|
|
# Files you want to generate.
|
|
#
|
|
if not env.GetOption('userfile'):
|
|
dbgSettings = None
|
|
elif env.get('MSVC_VERSION', None) == '9.0':
|
|
dbgSettings = V9DebugSettings
|
|
elif env.get('MSVC_VERSION', None) == '11.0':
|
|
dbgSettings = V10DebugSettings
|
|
else:
|
|
dbgSettings = None
|
|
|
|
#
|
|
# 4. Add the dictionary to the DebugSettings keyword.
|
|
#
|
|
barsrcs = ['bar.cpp', 'dllmain.cpp', 'stdafx.cpp']
|
|
barincs = ['targetver.h']
|
|
barlocalincs = ['StdAfx.h']
|
|
barresources = ['bar.rc','resource.h']
|
|
barmisc = ['ReadMe.txt']
|
|
|
|
dll = env.SharedLibrary(target = 'bar.dll',
|
|
source = barsrcs)
|
|
|
|
env.MSVSProject(target = 'Bar' + env['MSVSPROJECTSUFFIX'],
|
|
srcs = barsrcs,
|
|
incs = barincs,
|
|
localincs = barlocalincs,
|
|
resources = barresources,
|
|
misc = barmisc,
|
|
buildtarget = [dll[0]] * 2,
|
|
variant = ('Debug|Win32', 'Release|Win32'),
|
|
cmdargs = 'vc=%s' % msvcver,
|
|
DebugSettings = (dbgSettings, {}))
|
|
</pre></dd><dt><a name="b-MSVSSolution"></a><span class="term">
|
|
<code class="function">MSVSSolution()</code>
|
|
, </span><span class="term">
|
|
<code class="function">env.MSVSSolution()</code>
|
|
</span></dt><dd><p>Builds a Microsoft Visual Studio solution
|
|
file. </p><p>This builds a Visual Studio solution file, based on the
|
|
version of Visual Studio that is configured (either the latest installed
|
|
version, or the version specified by <a class="link" href="#cv-MSVS_VERSION"><code class="envar">$MSVS_VERSION</code></a> in the
|
|
construction environment). For Visual Studio 6, it will generate a
|
|
<code class="filename">.dsw</code> file. For Visual Studio 7 (.NET), it will generate a
|
|
<code class="filename">.sln</code> file. </p><p> The following values must be
|
|
specified: </p><div class="variablelist"><dl><dt><span class="term">target</span></dt><dd><p>The name of the target .dsw or .sln file. The correct
|
|
suffix for the version of Visual Studio must be used, but the value
|
|
<a class="link" href="#cv-MSVSSOLUTIONSUFFIX"><code class="envar">$MSVSSOLUTIONSUFFIX</code></a> will be defined to the correct value (see
|
|
example below).</p></dd><dt><span class="term">variant</span></dt><dd><p>The name of this particular variant, or a list of variant
|
|
names (the latter is only supported for MSVS 7 solutions). These are
|
|
typically things like "Debug" or "Release", but really can be anything
|
|
you want. For MSVS 7 they may also specify target platform, like this
|
|
"Debug|Xbox". Default platform is Win32.</p></dd><dt><span class="term">projects</span></dt><dd><p>A list of project file names, or Project nodes returned by
|
|
calls to the <code class="function">MSVSProject</code> Builder, to be placed into the solution
|
|
file. It should be noted that these file names are NOT added to the
|
|
$SOURCES environment variable in form of files, but rather as strings.
|
|
This is because they represent file names to be added to the solution
|
|
file, not the source files used to build the solution
|
|
file.</p></dd></dl></div><p> Example Usage: </p><pre class="screen">
|
|
env.MSVSSolution(target = 'Bar' + env['MSVSSOLUTIONSUFFIX'], projects = ['bar'
|
|
+ env['MSVSPROJECTSUFFIX']], variant = 'Release')
|
|
</pre></dd><dt><a name="b-Object"></a><span class="term">
|
|
<code class="function">Object()</code>
|
|
, </span><span class="term">
|
|
<code class="function">env.Object()</code>
|
|
</span></dt><dd><p>
|
|
A synonym for the
|
|
<code class="function">StaticObject</code>
|
|
builder method.
|
|
</p></dd><dt><a name="b-Package"></a><span class="term">
|
|
<code class="function">Package()</code>
|
|
, </span><span class="term">
|
|
<code class="function">env.Package()</code>
|
|
</span></dt><dd><p>
|
|
Builds a Binary Package of the given source files.
|
|
</p><pre class="screen">
|
|
env.Package(source = FindInstalledFiles())
|
|
</pre><p>
|
|
Builds software distribution packages.
|
|
Packages consist of files to install and packaging information.
|
|
The former may be specified with the <code class="varname">source</code> parameter and may be left out,
|
|
in which case the <code class="function">FindInstalledFiles</code> function will collect
|
|
all files that have an <code class="function">Install</code> or <code class="function">InstallAs</code> Builder attached.
|
|
If the <code class="varname">target</code> is not specified
|
|
it will be deduced from additional information given to this Builder.
|
|
</p><p>
|
|
The packaging information is specified
|
|
with the help of construction variables documented below.
|
|
This information is called a tag to stress that
|
|
some of them can also be attached to files with the <code class="function">Tag</code> function.
|
|
The mandatory ones will complain if they were not specified.
|
|
They vary depending on chosen target packager.
|
|
</p><p>
|
|
The target packager may be selected with the "PACKAGETYPE" command line
|
|
option or with the <code class="envar">$PACKAGETYPE</code> construction variable. Currently
|
|
the following packagers available:
|
|
</p><p>
|
|
* msi - Microsoft Installer
|
|
* rpm - RPM Package Manger
|
|
* ipkg - Itsy Package Management System
|
|
* tarbz2 - bzip2 compressed tar
|
|
* targz - gzip compressed tar
|
|
* tarxz - xz compressed tar
|
|
* zip - zip file
|
|
* src_tarbz2 - bzip2 compressed tar source
|
|
* src_targz - gzip compressed tar source
|
|
* src_tarxz - xz compressed tar source
|
|
* src_zip - zip file source
|
|
</p><p>
|
|
An updated list is always available under the "package_type" option when
|
|
running "scons --help" on a project that has packaging activated.
|
|
</p><pre class="screen">
|
|
env = Environment(tools=['default', 'packaging'])
|
|
env.Install('/bin/', 'my_program')
|
|
env.Package( NAME = 'foo',
|
|
VERSION = '1.2.3',
|
|
PACKAGEVERSION = 0,
|
|
PACKAGETYPE = 'rpm',
|
|
LICENSE = 'gpl',
|
|
SUMMARY = 'balalalalal',
|
|
DESCRIPTION = 'this should be really really long',
|
|
X_RPM_GROUP = 'Application/fu',
|
|
SOURCE_URL = 'http://foo.org/foo-1.2.3.tar.gz'
|
|
)
|
|
</pre></dd><dt><a name="b-PCH"></a><span class="term">
|
|
<code class="function">PCH()</code>
|
|
, </span><span class="term">
|
|
<code class="function">env.PCH()</code>
|
|
</span></dt><dd><p>
|
|
Builds a Microsoft Visual C++ precompiled header.
|
|
Calling this builder method
|
|
returns a list of two targets: the PCH as the first element, and the object
|
|
file as the second element. Normally the object file is ignored.
|
|
This builder method is only
|
|
provided when Microsoft Visual C++ is being used as the compiler.
|
|
The PCH builder method is generally used in
|
|
conjunction with the PCH construction variable to force object files to use
|
|
the precompiled header:
|
|
</p><pre class="screen">
|
|
env['PCH'] = env.PCH('StdAfx.cpp')[0]
|
|
</pre></dd><dt><a name="b-PDF"></a><span class="term">
|
|
<code class="function">PDF()</code>
|
|
, </span><span class="term">
|
|
<code class="function">env.PDF()</code>
|
|
</span></dt><dd><p>
|
|
Builds a <code class="filename">.pdf</code> file
|
|
from a <code class="filename">.dvi</code> input file
|
|
(or, by extension, a <code class="filename">.tex</code>,
|
|
<code class="filename">.ltx</code>,
|
|
or
|
|
<code class="filename">.latex</code> input file).
|
|
The suffix specified by the <a class="link" href="#cv-PDFSUFFIX"><code class="envar">$PDFSUFFIX</code></a> construction variable
|
|
(<code class="filename">.pdf</code> by default)
|
|
is added automatically to the target
|
|
if it is not already present. Example:
|
|
</p><pre class="screen">
|
|
# builds from aaa.tex
|
|
env.PDF(target = 'aaa.pdf', source = 'aaa.tex')
|
|
# builds bbb.pdf from bbb.dvi
|
|
env.PDF(target = 'bbb', source = 'bbb.dvi')
|
|
</pre></dd><dt><a name="b-POInit"></a><span class="term">
|
|
<code class="function">POInit()</code>
|
|
, </span><span class="term">
|
|
<code class="function">env.POInit()</code>
|
|
</span></dt><dd><p>
|
|
This builder belongs to <a class="link" href="#t-msginit"><code class="literal">msginit</code></a> tool. The builder initializes missing
|
|
<code class="literal">PO</code> file(s) if <a class="link" href="#cv-POAUTOINIT"><code class="envar">$POAUTOINIT</code></a> is set. If
|
|
<a class="link" href="#cv-POAUTOINIT"><code class="envar">$POAUTOINIT</code></a> is not set (default), <code class="function">POInit</code> prints instruction for
|
|
user (that is supposed to be a translator), telling how the
|
|
<code class="literal">PO</code> file should be initialized. In normal projects
|
|
<span class="emphasis"><em>you should not use <code class="function">POInit</code> and use <a class="link" href="#b-POUpdate"><code class="function">POUpdate</code></a>
|
|
instead</em></span>. <a class="link" href="#b-POUpdate"><code class="function">POUpdate</code></a> chooses intelligently between
|
|
<span class="command"><strong>msgmerge(1)</strong></span> and <span class="command"><strong>msginit(1)</strong></span>. <code class="function">POInit</code>
|
|
always uses <span class="command"><strong>msginit(1)</strong></span> and should be regarded as builder for
|
|
special purposes or for temporary use (e.g. for quick, one time initialization
|
|
of a bunch of <code class="literal">PO</code> files) or for tests.
|
|
</p><p>
|
|
Target nodes defined through <code class="function">POInit</code> are not built by default (they're
|
|
<code class="literal">Ignore</code>d from <code class="literal">'.'</code> node) but are added to
|
|
special <code class="literal">Alias</code> (<code class="literal">'po-create'</code> by default).
|
|
The alias name may be changed through the <a class="link" href="#cv-POCREATE_ALIAS"><code class="envar">$POCREATE_ALIAS</code></a>
|
|
construction variable. All <code class="literal">PO</code> files defined through
|
|
<code class="function">POInit</code> may be easily initialized by <span class="command"><strong>scons po-create</strong></span>.
|
|
</p><p>
|
|
<span class="emphasis"><em>Example 1</em></span>.
|
|
Initialize <code class="filename">en.po</code> and <code class="filename">pl.po</code> from
|
|
<code class="filename">messages.pot</code>:
|
|
</p><pre class="screen">
|
|
# ...
|
|
env.POInit(['en', 'pl']) # messages.pot --> [en.po, pl.po]
|
|
</pre><p>
|
|
<span class="emphasis"><em>Example 2</em></span>.
|
|
Initialize <code class="filename">en.po</code> and <code class="filename">pl.po</code> from
|
|
<code class="filename">foo.pot</code>:
|
|
</p><pre class="screen">
|
|
# ...
|
|
env.POInit(['en', 'pl'], ['foo']) # foo.pot --> [en.po, pl.po]
|
|
</pre><p>
|
|
<span class="emphasis"><em>Example 3</em></span>.
|
|
Initialize <code class="filename">en.po</code> and <code class="filename">pl.po</code> from
|
|
<code class="filename">foo.pot</code> but using <a class="link" href="#cv-POTDOMAIN"><code class="envar">$POTDOMAIN</code></a> construction
|
|
variable:
|
|
</p><pre class="screen">
|
|
# ...
|
|
env.POInit(['en', 'pl'], POTDOMAIN='foo') # foo.pot --> [en.po, pl.po]
|
|
</pre><p>
|
|
<span class="emphasis"><em>Example 4</em></span>.
|
|
Initialize <code class="literal">PO</code> files for languages defined in
|
|
<code class="filename">LINGUAS</code> file. The files will be initialized from template
|
|
<code class="filename">messages.pot</code>:
|
|
</p><pre class="screen">
|
|
# ...
|
|
env.POInit(LINGUAS_FILE = 1) # needs 'LINGUAS' file
|
|
</pre><p>
|
|
<span class="emphasis"><em>Example 5</em></span>.
|
|
Initialize <code class="filename">en.po</code> and <code class="filename">pl.pl</code>
|
|
<code class="literal">PO</code> files plus files for languages defined in
|
|
<code class="filename">LINGUAS</code> file. The files will be initialized from template
|
|
<code class="filename">messages.pot</code>:
|
|
</p><pre class="screen">
|
|
# ...
|
|
env.POInit(['en', 'pl'], LINGUAS_FILE = 1)
|
|
</pre><p>
|
|
<span class="emphasis"><em>Example 6</em></span>.
|
|
You may preconfigure your environment first, and then initialize
|
|
<code class="literal">PO</code> files:
|
|
</p><pre class="screen">
|
|
# ...
|
|
env['POAUTOINIT'] = 1
|
|
env['LINGUAS_FILE'] = 1
|
|
env['POTDOMAIN'] = 'foo'
|
|
env.POInit()
|
|
</pre><p>
|
|
which has same efect as:
|
|
</p><pre class="screen">
|
|
# ...
|
|
env.POInit(POAUTOINIT = 1, LINGUAS_FILE = 1, POTDOMAIN = 'foo')
|
|
</pre></dd><dt><a name="b-PostScript"></a><span class="term">
|
|
<code class="function">PostScript()</code>
|
|
, </span><span class="term">
|
|
<code class="function">env.PostScript()</code>
|
|
</span></dt><dd><p>
|
|
Builds a <code class="filename">.ps</code> file
|
|
from a <code class="filename">.dvi</code> input file
|
|
(or, by extension, a <code class="filename">.tex</code>,
|
|
<code class="filename">.ltx</code>,
|
|
or
|
|
<code class="filename">.latex</code> input file).
|
|
The suffix specified by the <a class="link" href="#cv-PSSUFFIX"><code class="envar">$PSSUFFIX</code></a> construction variable
|
|
(<code class="filename">.ps</code> by default)
|
|
is added automatically to the target
|
|
if it is not already present. Example:
|
|
</p><pre class="screen">
|
|
# builds from aaa.tex
|
|
env.PostScript(target = 'aaa.ps', source = 'aaa.tex')
|
|
# builds bbb.ps from bbb.dvi
|
|
env.PostScript(target = 'bbb', source = 'bbb.dvi')
|
|
</pre></dd><dt><a name="b-POTUpdate"></a><span class="term">
|
|
<code class="function">POTUpdate()</code>
|
|
, </span><span class="term">
|
|
<code class="function">env.POTUpdate()</code>
|
|
</span></dt><dd><p>
|
|
The builder belongs to <a class="link" href="#t-xgettext"><code class="literal">xgettext</code></a> tool. The builder updates target
|
|
<code class="literal">POT</code> file if exists or creates one if it doesn't. The node is
|
|
not built by default (i.e. it is <code class="literal">Ignore</code>d from
|
|
<code class="literal">'.'</code>), but only on demand (i.e. when given
|
|
<code class="literal">POT</code> file is required or when special alias is invoked). This
|
|
builder adds its targe node (<code class="filename">messages.pot</code>, say) to a
|
|
special alias (<code class="literal">pot-update</code> by default, see
|
|
<a class="link" href="#cv-POTUPDATE_ALIAS"><code class="envar">$POTUPDATE_ALIAS</code></a>) so you can update/create them easily with
|
|
<span class="command"><strong>scons pot-update</strong></span>. The file is not written until there is no
|
|
real change in internationalized messages (or in comments that enter
|
|
<code class="literal">POT</code> file).
|
|
</p><p>
|
|
</p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>You may see <span class="command"><strong>xgettext(1)</strong></span> being invoked by the
|
|
<a class="link" href="#t-xgettext"><code class="literal">xgettext</code></a> tool even if there is no real change in internationalized
|
|
messages (so the <code class="literal">POT</code> file is not being updated). This
|
|
happens every time a source file has changed. In such case we invoke
|
|
<span class="command"><strong>xgettext(1)</strong></span> and compare its output with the content of
|
|
<code class="literal">POT</code> file to decide whether the file should be updated or
|
|
not.</p></div><p>
|
|
</p><p>
|
|
<span class="emphasis"><em>Example 1.</em></span>
|
|
Let's create <code class="filename">po/</code> directory and place following
|
|
<code class="filename">SConstruct</code> script there:
|
|
</p><pre class="screen">
|
|
# SConstruct in 'po/' subdir
|
|
env = Environment( tools = ['default', 'xgettext'] )
|
|
env.POTUpdate(['foo'], ['../a.cpp', '../b.cpp'])
|
|
env.POTUpdate(['bar'], ['../c.cpp', '../d.cpp'])
|
|
</pre><p>
|
|
Then invoke scons few times:
|
|
</p><pre class="screen">
|
|
user@host:$ scons # Does not create foo.pot nor bar.pot
|
|
user@host:$ scons foo.pot # Updates or creates foo.pot
|
|
user@host:$ scons pot-update # Updates or creates foo.pot and bar.pot
|
|
user@host:$ scons -c # Does not clean foo.pot nor bar.pot.
|
|
</pre><p>
|
|
the results shall be as the comments above say.
|
|
</p><p>
|
|
<span class="emphasis"><em>Example 2.</em></span>
|
|
The <code class="function">POTUpdate</code> builder may be used with no target specified, in which
|
|
case default target <code class="filename">messages.pot</code> will be used. The
|
|
default target may also be overridden by setting <a class="link" href="#cv-POTDOMAIN"><code class="envar">$POTDOMAIN</code></a> construction
|
|
variable or providing it as an override to <code class="function">POTUpdate</code> builder:
|
|
</p><pre class="screen">
|
|
# SConstruct script
|
|
env = Environment( tools = ['default', 'xgettext'] )
|
|
env['POTDOMAIN'] = "foo"
|
|
env.POTUpdate(source = ["a.cpp", "b.cpp"]) # Creates foo.pot ...
|
|
env.POTUpdate(POTDOMAIN = "bar", source = ["c.cpp", "d.cpp"]) # and bar.pot
|
|
</pre><p>
|
|
<span class="emphasis"><em>Example 3.</em></span>
|
|
The sources may be specified within separate file, for example
|
|
<code class="filename">POTFILES.in</code>:
|
|
</p><pre class="screen">
|
|
# POTFILES.in in 'po/' subdirectory
|
|
../a.cpp
|
|
../b.cpp
|
|
# end of file
|
|
</pre><p>
|
|
The name of the file (<code class="filename">POTFILES.in</code>) containing the list of
|
|
sources is provided via <a class="link" href="#cv-XGETTEXTFROM"><code class="envar">$XGETTEXTFROM</code></a>:
|
|
</p><pre class="screen">
|
|
# SConstruct file in 'po/' subdirectory
|
|
env = Environment( tools = ['default', 'xgettext'] )
|
|
env.POTUpdate(XGETTEXTFROM = 'POTFILES.in')
|
|
</pre><p>
|
|
<span class="emphasis"><em>Example 4.</em></span>
|
|
You may use <a class="link" href="#cv-XGETTEXTPATH"><code class="envar">$XGETTEXTPATH</code></a> to define source search path. Assume, for
|
|
example, that you have files <code class="filename">a.cpp</code>,
|
|
<code class="filename">b.cpp</code>, <code class="filename">po/SConstruct</code>,
|
|
<code class="filename">po/POTFILES.in</code>. Then your <code class="literal">POT</code>-related
|
|
files could look as below:
|
|
</p><pre class="screen">
|
|
# POTFILES.in in 'po/' subdirectory
|
|
a.cpp
|
|
b.cpp
|
|
# end of file
|
|
</pre><pre class="screen">
|
|
# SConstruct file in 'po/' subdirectory
|
|
env = Environment( tools = ['default', 'xgettext'] )
|
|
env.POTUpdate(XGETTEXTFROM = 'POTFILES.in', XGETTEXTPATH='../')
|
|
</pre><p>
|
|
<span class="emphasis"><em>Example 5.</em></span>
|
|
Multiple search directories may be defined within a list, i.e.
|
|
<code class="literal">XGETTEXTPATH = ['dir1', 'dir2', ...]</code>. The order in the list
|
|
determines the search order of source files. The path to the first file found
|
|
is used.
|
|
</p><p>
|
|
Let's create <code class="filename">0/1/po/SConstruct</code> script:
|
|
</p><pre class="screen">
|
|
# SConstruct file in '0/1/po/' subdirectory
|
|
env = Environment( tools = ['default', 'xgettext'] )
|
|
env.POTUpdate(XGETTEXTFROM = 'POTFILES.in', XGETTEXTPATH=['../', '../../'])
|
|
</pre><p>
|
|
and <code class="filename">0/1/po/POTFILES.in</code>:
|
|
</p><pre class="screen">
|
|
# POTFILES.in in '0/1/po/' subdirectory
|
|
a.cpp
|
|
# end of file
|
|
</pre><p>
|
|
Write two <code class="filename">*.cpp</code> files, the first one is
|
|
<code class="filename">0/a.cpp</code>:
|
|
</p><pre class="screen">
|
|
/* 0/a.cpp */
|
|
gettext("Hello from ../../a.cpp")
|
|
</pre><p>
|
|
and the second is <code class="filename">0/1/a.cpp</code>:
|
|
</p><pre class="screen">
|
|
/* 0/1/a.cpp */
|
|
gettext("Hello from ../a.cpp")
|
|
</pre><p>
|
|
then run scons. You'll obtain <code class="literal">0/1/po/messages.pot</code> with the
|
|
message <code class="literal">"Hello from ../a.cpp"</code>. When you reverse order in
|
|
<code class="varname">$XGETTEXTFOM</code>, i.e. when you write SConscript as
|
|
</p><pre class="screen">
|
|
# SConstruct file in '0/1/po/' subdirectory
|
|
env = Environment( tools = ['default', 'xgettext'] )
|
|
env.POTUpdate(XGETTEXTFROM = 'POTFILES.in', XGETTEXTPATH=['../../', '../'])
|
|
</pre><p>
|
|
then the <code class="filename">messages.pot</code> will contain
|
|
<code class="literal">msgid "Hello from ../../a.cpp"</code> line and not
|
|
<code class="literal">msgid "Hello from ../a.cpp"</code>.
|
|
</p></dd><dt><a name="b-POUpdate"></a><span class="term">
|
|
<code class="function">POUpdate()</code>
|
|
, </span><span class="term">
|
|
<code class="function">env.POUpdate()</code>
|
|
</span></dt><dd><p>
|
|
The builder belongs to <a class="link" href="#t-msgmerge"><code class="literal">msgmerge</code></a> tool. The builder updates
|
|
<code class="literal">PO</code> files with <span class="command"><strong>msgmerge(1)</strong></span>, or initializes
|
|
missing <code class="literal">PO</code> files as described in documentation of
|
|
<a class="link" href="#t-msginit"><code class="literal">msginit</code></a> tool and <a class="link" href="#b-POInit"><code class="function">POInit</code></a> builder (see also
|
|
<a class="link" href="#cv-POAUTOINIT"><code class="envar">$POAUTOINIT</code></a>). Note, that <code class="function">POUpdate</code> <span class="emphasis"><em>does not add its
|
|
targets to <code class="literal">po-create</code> alias</em></span> as <a class="link" href="#b-POInit"><code class="function">POInit</code></a>
|
|
does.
|
|
</p><p>
|
|
Target nodes defined through <code class="function">POUpdate</code> are not built by default
|
|
(they're <code class="literal">Ignore</code>d from <code class="literal">'.'</code> node). Instead,
|
|
they are added automatically to special <code class="literal">Alias</code>
|
|
(<code class="literal">'po-update'</code> by default). The alias name may be changed
|
|
through the <a class="link" href="#cv-POUPDATE_ALIAS"><code class="envar">$POUPDATE_ALIAS</code></a> construction variable. You can easily
|
|
update <code class="literal">PO</code> files in your project by <span class="command"><strong>scons
|
|
po-update</strong></span>.
|
|
</p><p>
|
|
<span class="emphasis"><em>Example 1.</em></span>
|
|
Update <code class="filename">en.po</code> and <code class="filename">pl.po</code> from
|
|
<code class="filename">messages.pot</code> template (see also <a class="link" href="#cv-POTDOMAIN"><code class="envar">$POTDOMAIN</code></a>),
|
|
assuming that the later one exists or there is rule to build it (see
|
|
<a class="link" href="#b-POTUpdate"><code class="function">POTUpdate</code></a>):
|
|
</p><pre class="screen">
|
|
# ...
|
|
env.POUpdate(['en','pl']) # messages.pot --> [en.po, pl.po]
|
|
</pre><p>
|
|
<span class="emphasis"><em>Example 2.</em></span>
|
|
Update <code class="filename">en.po</code> and <code class="filename">pl.po</code> from
|
|
<code class="filename">foo.pot</code> template:
|
|
</p><pre class="screen">
|
|
# ...
|
|
env.POUpdate(['en', 'pl'], ['foo']) # foo.pot --> [en.po, pl.pl]
|
|
</pre><p>
|
|
<span class="emphasis"><em>Example 3.</em></span>
|
|
Update <code class="filename">en.po</code> and <code class="filename">pl.po</code> from
|
|
<code class="filename">foo.pot</code> (another version):
|
|
</p><pre class="screen">
|
|
# ...
|
|
env.POUpdate(['en', 'pl'], POTDOMAIN='foo') # foo.pot -- > [en.po, pl.pl]
|
|
</pre><p>
|
|
<span class="emphasis"><em>Example 4.</em></span>
|
|
Update files for languages defined in <code class="filename">LINGUAS</code> file. The
|
|
files are updated from <code class="filename">messages.pot</code> template:
|
|
</p><pre class="screen">
|
|
# ...
|
|
env.POUpdate(LINGUAS_FILE = 1) # needs 'LINGUAS' file
|
|
</pre><p>
|
|
<span class="emphasis"><em>Example 5.</em></span>
|
|
Same as above, but update from <code class="filename">foo.pot</code> template:
|
|
</p><pre class="screen">
|
|
# ...
|
|
env.POUpdate(LINGUAS_FILE = 1, source = ['foo'])
|
|
</pre><p>
|
|
<span class="emphasis"><em>Example 6.</em></span>
|
|
Update <code class="filename">en.po</code> and <code class="filename">pl.po</code> plus files for
|
|
languages defined in <code class="filename">LINGUAS</code> file. The files are updated
|
|
from <code class="filename">messages.pot</code> template:
|
|
</p><pre class="screen">
|
|
# produce 'en.po', 'pl.po' + files defined in 'LINGUAS':
|
|
env.POUpdate(['en', 'pl' ], LINGUAS_FILE = 1)
|
|
</pre><p>
|
|
<span class="emphasis"><em>Example 7.</em></span>
|
|
Use <a class="link" href="#cv-POAUTOINIT"><code class="envar">$POAUTOINIT</code></a> to automatically initialize <code class="literal">PO</code> file
|
|
if it doesn't exist:
|
|
</p><pre class="screen">
|
|
# ...
|
|
env.POUpdate(LINGUAS_FILE = 1, POAUTOINIT = 1)
|
|
</pre><p>
|
|
<span class="emphasis"><em>Example 8.</em></span>
|
|
Update <code class="literal">PO</code> files for languages defined in
|
|
<code class="filename">LINGUAS</code> file. The files are updated from
|
|
<code class="filename">foo.pot</code> template. All necessary settings are
|
|
pre-configured via environment.
|
|
</p><pre class="screen">
|
|
# ...
|
|
env['POAUTOINIT'] = 1
|
|
env['LINGUAS_FILE'] = 1
|
|
env['POTDOMAIN'] = 'foo'
|
|
env.POUpdate()
|
|
</pre></dd><dt><a name="b-Program"></a><span class="term">
|
|
<code class="function">Program()</code>
|
|
, </span><span class="term">
|
|
<code class="function">env.Program()</code>
|
|
</span></dt><dd><p>
|
|
Builds an executable given one or more object files
|
|
or C, C++, D, or Fortran source files.
|
|
If any C, C++, D or Fortran source files are specified,
|
|
then they will be automatically
|
|
compiled to object files using the
|
|
<code class="function">Object</code>
|
|
builder method;
|
|
see that builder method's description for
|
|
a list of legal source file suffixes
|
|
and how they are interpreted.
|
|
The target executable file prefix
|
|
(specified by the <a class="link" href="#cv-PROGPREFIX"><code class="envar">$PROGPREFIX</code></a> construction variable; nothing by default)
|
|
and suffix
|
|
(specified by the <a class="link" href="#cv-PROGSUFFIX"><code class="envar">$PROGSUFFIX</code></a> construction variable;
|
|
by default, <code class="filename">.exe</code> on Windows systems,
|
|
nothing on POSIX systems)
|
|
are automatically added to the target if not already present.
|
|
Example:
|
|
</p><pre class="screen">
|
|
env.Program(target = 'foo', source = ['foo.o', 'bar.c', 'baz.f'])
|
|
</pre></dd><dt><a name="b-ProgramAllAtOnce"></a><span class="term">
|
|
<code class="function">ProgramAllAtOnce()</code>
|
|
, </span><span class="term">
|
|
<code class="function">env.ProgramAllAtOnce()</code>
|
|
</span></dt><dd><p>
|
|
Builds an executable from D sources without first creating individual
|
|
objects for each file.
|
|
</p><p>
|
|
D sources can be compiled file-by-file as C and C++ source are, and
|
|
D is integrated into the <code class="filename">scons</code> Object and Program builders for
|
|
this model of build. D codes can though do whole source
|
|
meta-programming (some of the testing frameworks do this). For this
|
|
it is imperative that all sources are compiled and linked in a single call of
|
|
the D compiler. This builder serves that purpose.
|
|
</p><pre class="screen">
|
|
env.ProgramAllAtOnce('executable', ['mod_a.d, mod_b.d', 'mod_c.d'])
|
|
</pre><p>
|
|
This command will compile the modules mod_a, mod_b, and mod_c in a
|
|
single compilation process without first creating object files for
|
|
the modules. Some of the D compilers will create executable.o others
|
|
will not.
|
|
</p><p>
|
|
Builds an executable from D sources without first creating individual
|
|
objects for each file.
|
|
</p><p>
|
|
D sources can be compiled file-by-file as C and C++ source are, and
|
|
D is integrated into the <code class="filename">scons</code> Object and Program builders for
|
|
this model of build. D codes can though do whole source
|
|
meta-programming (some of the testing frameworks do this). For this
|
|
it is imperative that all sources are compiled and linked in a single call of
|
|
the D compiler. This builder serves that purpose.
|
|
</p><pre class="screen">
|
|
env.ProgramAllAtOnce('executable', ['mod_a.d, mod_b.d', 'mod_c.d'])
|
|
</pre><p>
|
|
This command will compile the modules mod_a, mod_b, and mod_c in a
|
|
single compilation process without first creating object files for
|
|
the modules. Some of the D compilers will create executable.o others
|
|
will not.
|
|
</p><p>
|
|
Builds an executable from D sources without first creating individual
|
|
objects for each file.
|
|
</p><p>
|
|
D sources can be compiled file-by-file as C and C++ source are, and
|
|
D is integrated into the <code class="filename">scons</code> Object and Program builders for
|
|
this model of build. D codes can though do whole source
|
|
meta-programming (some of the testing frameworks do this). For this
|
|
it is imperative that all sources are compiled and linked in a single call of
|
|
the D compiler. This builder serves that purpose.
|
|
</p><pre class="screen">
|
|
env.ProgramAllAtOnce('executable', ['mod_a.d, mod_b.d', 'mod_c.d'])
|
|
</pre><p>
|
|
This command will compile the modules mod_a, mod_b, and mod_c in a
|
|
single compilation process without first creating object files for
|
|
the modules. Some of the D compilers will create executable.o others
|
|
will not.
|
|
</p></dd><dt><a name="b-RES"></a><span class="term">
|
|
<code class="function">RES()</code>
|
|
, </span><span class="term">
|
|
<code class="function">env.RES()</code>
|
|
</span></dt><dd><p>
|
|
Builds a Microsoft Visual C++ resource file.
|
|
This builder method is only provided
|
|
when Microsoft Visual C++ or MinGW is being used as the compiler. The
|
|
<code class="filename">.res</code>
|
|
(or
|
|
<code class="filename">.o</code>
|
|
for MinGW) suffix is added to the target name if no other suffix is given.
|
|
The source
|
|
file is scanned for implicit dependencies as though it were a C file.
|
|
Example:
|
|
</p><pre class="screen">
|
|
env.RES('resource.rc')
|
|
</pre></dd><dt><a name="b-RMIC"></a><span class="term">
|
|
<code class="function">RMIC()</code>
|
|
, </span><span class="term">
|
|
<code class="function">env.RMIC()</code>
|
|
</span></dt><dd><p>
|
|
Builds stub and skeleton class files
|
|
for remote objects
|
|
from Java <code class="filename">.class</code> files.
|
|
The target is a directory
|
|
relative to which the stub
|
|
and skeleton class files will be written.
|
|
The source can be the names of <code class="filename">.class</code> files,
|
|
or the objects return from the
|
|
<code class="function">Java</code>
|
|
builder method.
|
|
</p><p>
|
|
If the construction variable
|
|
<a class="link" href="#cv-JAVACLASSDIR"><code class="envar">$JAVACLASSDIR</code></a>
|
|
is set, either in the environment
|
|
or in the call to the
|
|
<code class="function">RMIC</code>
|
|
builder method itself,
|
|
then the value of the variable
|
|
will be stripped from the
|
|
beginning of any <code class="filename">.class </code>
|
|
file names.
|
|
</p><pre class="screen">
|
|
classes = env.Java(target = 'classdir', source = 'src')
|
|
env.RMIC(target = 'outdir1', source = classes)
|
|
|
|
env.RMIC(target = 'outdir2',
|
|
source = ['package/foo.class', 'package/bar.class'])
|
|
|
|
env.RMIC(target = 'outdir3',
|
|
source = ['classes/foo.class', 'classes/bar.class'],
|
|
JAVACLASSDIR = 'classes')
|
|
</pre></dd><dt><a name="b-RPCGenClient"></a><span class="term">
|
|
<code class="function">RPCGenClient()</code>
|
|
, </span><span class="term">
|
|
<code class="function">env.RPCGenClient()</code>
|
|
</span></dt><dd><p>
|
|
Generates an RPC client stub (<code class="filename">_clnt.c</code>) file
|
|
from a specified RPC (<code class="filename">.x</code>) source file.
|
|
Because rpcgen only builds output files
|
|
in the local directory,
|
|
the command will be executed
|
|
in the source file's directory by default.
|
|
</p><pre class="screen">
|
|
# Builds src/rpcif_clnt.c
|
|
env.RPCGenClient('src/rpcif.x')
|
|
</pre></dd><dt><a name="b-RPCGenHeader"></a><span class="term">
|
|
<code class="function">RPCGenHeader()</code>
|
|
, </span><span class="term">
|
|
<code class="function">env.RPCGenHeader()</code>
|
|
</span></dt><dd><p>
|
|
Generates an RPC header (<code class="filename">.h</code>) file
|
|
from a specified RPC (<code class="filename">.x</code>) source file.
|
|
Because rpcgen only builds output files
|
|
in the local directory,
|
|
the command will be executed
|
|
in the source file's directory by default.
|
|
</p><pre class="screen">
|
|
# Builds src/rpcif.h
|
|
env.RPCGenHeader('src/rpcif.x')
|
|
</pre></dd><dt><a name="b-RPCGenService"></a><span class="term">
|
|
<code class="function">RPCGenService()</code>
|
|
, </span><span class="term">
|
|
<code class="function">env.RPCGenService()</code>
|
|
</span></dt><dd><p>
|
|
Generates an RPC server-skeleton (<code class="filename">_svc.c</code>) file
|
|
from a specified RPC (<code class="filename">.x</code>) source file.
|
|
Because rpcgen only builds output files
|
|
in the local directory,
|
|
the command will be executed
|
|
in the source file's directory by default.
|
|
</p><pre class="screen">
|
|
# Builds src/rpcif_svc.c
|
|
env.RPCGenClient('src/rpcif.x')
|
|
</pre></dd><dt><a name="b-RPCGenXDR"></a><span class="term">
|
|
<code class="function">RPCGenXDR()</code>
|
|
, </span><span class="term">
|
|
<code class="function">env.RPCGenXDR()</code>
|
|
</span></dt><dd><p>
|
|
Generates an RPC XDR routine (<code class="filename">_xdr.c</code>) file
|
|
from a specified RPC (<code class="filename">.x</code>) source file.
|
|
Because rpcgen only builds output files
|
|
in the local directory,
|
|
the command will be executed
|
|
in the source file's directory by default.
|
|
</p><pre class="screen">
|
|
# Builds src/rpcif_xdr.c
|
|
env.RPCGenClient('src/rpcif.x')
|
|
</pre></dd><dt><a name="b-SharedLibrary"></a><span class="term">
|
|
<code class="function">SharedLibrary()</code>
|
|
, </span><span class="term">
|
|
<code class="function">env.SharedLibrary()</code>
|
|
</span></dt><dd><p>
|
|
Builds a shared library
|
|
(<code class="filename">.so</code> on a POSIX system,
|
|
<code class="filename">.dll</code> on Windows)
|
|
given one or more object files
|
|
or C, C++, D or Fortran source files.
|
|
If any source files are given,
|
|
then they will be automatically
|
|
compiled to object files.
|
|
The static library prefix and suffix (if any)
|
|
are automatically added to the target.
|
|
The target library file prefix
|
|
(specified by the <a class="link" href="#cv-SHLIBPREFIX"><code class="envar">$SHLIBPREFIX</code></a> construction variable;
|
|
by default, <code class="filename">lib</code> on POSIX systems,
|
|
nothing on Windows systems)
|
|
and suffix
|
|
(specified by the <a class="link" href="#cv-SHLIBSUFFIX"><code class="envar">$SHLIBSUFFIX</code></a> construction variable;
|
|
by default, <code class="filename">.dll</code> on Windows systems,
|
|
<code class="filename">.so</code> on POSIX systems)
|
|
are automatically added to the target if not already present.
|
|
Example:
|
|
</p><pre class="screen">
|
|
env.SharedLibrary(target = 'bar', source = ['bar.c', 'foo.o'])
|
|
</pre><p>
|
|
On Windows systems, the
|
|
<code class="function">SharedLibrary</code>
|
|
builder method will always build an import
|
|
(<code class="filename">.lib</code>) library
|
|
in addition to the shared (<code class="filename">.dll</code>) library,
|
|
adding a <code class="filename">.lib</code> library with the same basename
|
|
if there is not already a <code class="filename">.lib</code> file explicitly
|
|
listed in the targets.
|
|
</p><p>
|
|
On Cygwin systems, the
|
|
<code class="function">SharedLibrary</code>
|
|
builder method will always build an import
|
|
(<code class="filename">.dll.a</code>) library
|
|
in addition to the shared (<code class="filename">.dll</code>) library,
|
|
adding a <code class="filename">.dll.a</code> library with the same basename
|
|
if there is not already a <code class="filename">.dll.a</code> file explicitly
|
|
listed in the targets.
|
|
</p><p>
|
|
Any object files listed in the
|
|
<code class="literal">source</code>
|
|
must have been built for a shared library
|
|
(that is, using the
|
|
<code class="function">SharedObject</code>
|
|
builder method).
|
|
<code class="filename">scons</code>
|
|
will raise an error if there is any mismatch.
|
|
</p><p>
|
|
On some platforms, there is a distinction between a shared library
|
|
(loaded automatically by the system to resolve external references)
|
|
and a loadable module (explicitly loaded by user action).
|
|
For maximum portability, use the <code class="function">LoadableModule</code> builder for the latter.
|
|
</p><p>
|
|
When the <a class="link" href="#cv-SHLIBVERSION"><code class="envar">$SHLIBVERSION</code></a> construction variable is defined a versioned
|
|
shared library is created. This modifies the <a class="link" href="#cv-SHLINKFLAGS"><code class="envar">$SHLINKFLAGS</code></a> as required,
|
|
adds the version number to the library name, and creates the symlinks that
|
|
are needed.
|
|
</p><pre class="screen">
|
|
env.SharedLibrary(target = 'bar', source = ['bar.c', 'foo.o'], SHLIBVERSION='1.5.2')
|
|
</pre><p>
|
|
On a POSIX system, versions with a single token create exactly one symlink:
|
|
libbar.so.6 would have symlinks libbar.so only.
|
|
On a POSIX system, versions with two or more
|
|
tokens create exactly two symlinks: libbar.so.2.3.1 would have symlinks
|
|
libbar.so and libbar.so.2; on a Darwin (OSX) system the library would be
|
|
libbar.2.3.1.dylib and the link would be libbar.dylib.
|
|
</p><p>
|
|
On Windows systems, specifying
|
|
<code class="literal">register=1</code>
|
|
will cause the <code class="filename">.dll</code> to be
|
|
registered after it is built using REGSVR32.
|
|
The command that is run
|
|
("regsvr32" by default) is determined by <a class="link" href="#cv-REGSVR"><code class="envar">$REGSVR</code></a> construction
|
|
variable, and the flags passed are determined by <a class="link" href="#cv-REGSVRFLAGS"><code class="envar">$REGSVRFLAGS</code></a>. By
|
|
default, <a class="link" href="#cv-REGSVRFLAGS"><code class="envar">$REGSVRFLAGS</code></a> includes the <code class="option">/s</code> option,
|
|
to prevent dialogs from popping
|
|
up and requiring user attention when it is run. If you change
|
|
<a class="link" href="#cv-REGSVRFLAGS"><code class="envar">$REGSVRFLAGS</code></a>, be sure to include the <code class="option">/s</code> option.
|
|
For example,
|
|
</p><pre class="screen">
|
|
env.SharedLibrary(target = 'bar',
|
|
source = ['bar.cxx', 'foo.obj'],
|
|
register=1)
|
|
</pre><p>
|
|
will register <code class="filename">bar.dll</code> as a COM object
|
|
when it is done linking it.
|
|
</p></dd><dt><a name="b-SharedObject"></a><span class="term">
|
|
<code class="function">SharedObject()</code>
|
|
, </span><span class="term">
|
|
<code class="function">env.SharedObject()</code>
|
|
</span></dt><dd><p>
|
|
Builds an object file for
|
|
inclusion in a shared library.
|
|
Source files must have one of the same set of extensions
|
|
specified above for the
|
|
<code class="function">StaticObject</code>
|
|
builder method.
|
|
On some platforms building a shared object requires additional
|
|
compiler option
|
|
(e.g. <code class="option">-fPIC</code> for gcc)
|
|
in addition to those needed to build a
|
|
normal (static) object, but on some platforms there is no difference between a
|
|
shared object and a normal (static) one. When there is a difference, SCons
|
|
will only allow shared objects to be linked into a shared library, and will
|
|
use a different suffix for shared objects. On platforms where there is no
|
|
difference, SCons will allow both normal (static)
|
|
and shared objects to be linked into a
|
|
shared library, and will use the same suffix for shared and normal
|
|
(static) objects.
|
|
The target object file prefix
|
|
(specified by the <a class="link" href="#cv-SHOBJPREFIX"><code class="envar">$SHOBJPREFIX</code></a> construction variable;
|
|
by default, the same as <a class="link" href="#cv-OBJPREFIX"><code class="envar">$OBJPREFIX</code></a>)
|
|
and suffix
|
|
(specified by the <a class="link" href="#cv-SHOBJSUFFIX"><code class="envar">$SHOBJSUFFIX</code></a> construction variable)
|
|
are automatically added to the target if not already present.
|
|
Examples:
|
|
</p><pre class="screen">
|
|
env.SharedObject(target = 'ddd', source = 'ddd.c')
|
|
env.SharedObject(target = 'eee.o', source = 'eee.cpp')
|
|
env.SharedObject(target = 'fff.obj', source = 'fff.for')
|
|
</pre><p>
|
|
Note that the source files will be scanned
|
|
according to the suffix mappings in the
|
|
<code class="literal">SourceFileScanner</code>
|
|
object.
|
|
See the section "Scanner Objects,"
|
|
below, for more information.
|
|
</p></dd><dt><a name="b-StaticLibrary"></a><span class="term">
|
|
<code class="function">StaticLibrary()</code>
|
|
, </span><span class="term">
|
|
<code class="function">env.StaticLibrary()</code>
|
|
</span></dt><dd><p>
|
|
Builds a static library given one or more object files
|
|
or C, C++, D or Fortran source files.
|
|
If any source files are given,
|
|
then they will be automatically
|
|
compiled to object files.
|
|
The static library prefix and suffix (if any)
|
|
are automatically added to the target.
|
|
The target library file prefix
|
|
(specified by the <a class="link" href="#cv-LIBPREFIX"><code class="envar">$LIBPREFIX</code></a> construction variable;
|
|
by default, <code class="filename">lib</code> on POSIX systems,
|
|
nothing on Windows systems)
|
|
and suffix
|
|
(specified by the <a class="link" href="#cv-LIBSUFFIX"><code class="envar">$LIBSUFFIX</code></a> construction variable;
|
|
by default, <code class="filename">.lib</code> on Windows systems,
|
|
<code class="filename">.a</code> on POSIX systems)
|
|
are automatically added to the target if not already present.
|
|
Example:
|
|
</p><pre class="screen">
|
|
env.StaticLibrary(target = 'bar', source = ['bar.c', 'foo.o'])
|
|
</pre><p>
|
|
Any object files listed in the
|
|
<code class="literal">source</code>
|
|
must have been built for a static library
|
|
(that is, using the
|
|
<code class="function">StaticObject</code>
|
|
builder method).
|
|
<code class="filename">scons</code>
|
|
will raise an error if there is any mismatch.
|
|
</p></dd><dt><a name="b-StaticObject"></a><span class="term">
|
|
<code class="function">StaticObject()</code>
|
|
, </span><span class="term">
|
|
<code class="function">env.StaticObject()</code>
|
|
</span></dt><dd><p>
|
|
Builds a static object file
|
|
from one or more C, C++, D, or Fortran source files.
|
|
Source files must have one of the following extensions:
|
|
</p><pre class="screen">
|
|
.asm assembly language file
|
|
.ASM assembly language file
|
|
.c C file
|
|
.C Windows: C file
|
|
POSIX: C++ file
|
|
.cc C++ file
|
|
.cpp C++ file
|
|
.cxx C++ file
|
|
.cxx C++ file
|
|
.c++ C++ file
|
|
.C++ C++ file
|
|
.d D file
|
|
.f Fortran file
|
|
.F Windows: Fortran file
|
|
POSIX: Fortran file + C pre-processor
|
|
.for Fortran file
|
|
.FOR Fortran file
|
|
.fpp Fortran file + C pre-processor
|
|
.FPP Fortran file + C pre-processor
|
|
.m Object C file
|
|
.mm Object C++ file
|
|
.s assembly language file
|
|
.S Windows: assembly language file
|
|
ARM: CodeSourcery Sourcery Lite
|
|
.sx assembly language file + C pre-processor
|
|
POSIX: assembly language file + C pre-processor
|
|
.spp assembly language file + C pre-processor
|
|
.SPP assembly language file + C pre-processor
|
|
</pre><p>
|
|
The target object file prefix
|
|
(specified by the <a class="link" href="#cv-OBJPREFIX"><code class="envar">$OBJPREFIX</code></a> construction variable; nothing by default)
|
|
and suffix
|
|
(specified by the <a class="link" href="#cv-OBJSUFFIX"><code class="envar">$OBJSUFFIX</code></a> construction variable;
|
|
<code class="filename">.obj</code> on Windows systems,
|
|
<code class="filename">.o</code> on POSIX systems)
|
|
are automatically added to the target if not already present.
|
|
Examples:
|
|
</p><pre class="screen">
|
|
env.StaticObject(target = 'aaa', source = 'aaa.c')
|
|
env.StaticObject(target = 'bbb.o', source = 'bbb.c++')
|
|
env.StaticObject(target = 'ccc.obj', source = 'ccc.f')
|
|
</pre><p>
|
|
Note that the source files will be scanned
|
|
according to the suffix mappings in
|
|
<code class="literal">SourceFileScanner</code>
|
|
object.
|
|
See the section "Scanner Objects,"
|
|
below, for more information.
|
|
</p></dd><dt><a name="b-Substfile"></a><span class="term">
|
|
<code class="function">Substfile()</code>
|
|
, </span><span class="term">
|
|
<code class="function">env.Substfile()</code>
|
|
</span></dt><dd><p>
|
|
The <code class="function">Substfile</code> builder creates a single text file from another file or set of
|
|
files by concatenating them with <code class="envar">$LINESEPARATOR</code> and replacing text
|
|
using the <code class="envar">$SUBST_DICT</code> construction variable. Nested lists of source files
|
|
are flattened. See also <code class="function">Textfile</code>.
|
|
</p><p>
|
|
If a single source file is present with an <code class="filename">.in</code> suffix,
|
|
the suffix is stripped and the remainder is used as the default target name.
|
|
</p><p>
|
|
The prefix and suffix specified by the <code class="envar">$SUBSTFILEPREFIX</code>
|
|
and <code class="envar">$SUBSTFILESUFFIX</code> construction variables
|
|
(the null string by default in both cases)
|
|
are automatically added to the target if they are not already present.
|
|
</p><p>
|
|
If a construction variable named <code class="envar">$SUBST_DICT</code> is present,
|
|
it may be either a Python dictionary or a sequence of (key,value) tuples.
|
|
If it is a dictionary it is converted into a list of tuples in an arbitrary order,
|
|
so if one key is a prefix of another key
|
|
or if one substitution could be further expanded by another subsitition,
|
|
it is unpredictable whether the expansion will occur.
|
|
</p><p>
|
|
Any occurrences of a key in the source
|
|
are replaced by the corresponding value,
|
|
which may be a Python callable function or a string.
|
|
If the value is a callable, it is called with no arguments to get a string.
|
|
Strings are <span class="emphasis"><em>subst</em></span>-expanded
|
|
and the result replaces the key.
|
|
</p><pre class="screen">
|
|
env = Environment(tools = ['default', 'textfile'])
|
|
|
|
env['prefix'] = '/usr/bin'
|
|
script_dict = {'@prefix@': '/bin', '@exec_prefix@': '$prefix'}
|
|
env.Substfile('script.in', SUBST_DICT = script_dict)
|
|
|
|
conf_dict = {'%VERSION%': '1.2.3', '%BASE%': 'MyProg'}
|
|
env.Substfile('config.h.in', conf_dict, SUBST_DICT = conf_dict)
|
|
|
|
# UNPREDICTABLE - one key is a prefix of another
|
|
bad_foo = {'$foo': '$foo', '$foobar': '$foobar'}
|
|
env.Substfile('foo.in', SUBST_DICT = bad_foo)
|
|
|
|
# PREDICTABLE - keys are applied longest first
|
|
good_foo = [('$foobar', '$foobar'), ('$foo', '$foo')]
|
|
env.Substfile('foo.in', SUBST_DICT = good_foo)
|
|
|
|
# UNPREDICTABLE - one substitution could be futher expanded
|
|
bad_bar = {'@bar@': '@soap@', '@soap@': 'lye'}
|
|
env.Substfile('bar.in', SUBST_DICT = bad_bar)
|
|
|
|
# PREDICTABLE - substitutions are expanded in order
|
|
good_bar = (('@bar@', '@soap@'), ('@soap@', 'lye'))
|
|
env.Substfile('bar.in', SUBST_DICT = good_bar)
|
|
|
|
# the SUBST_DICT may be in common (and not an override)
|
|
substutions = {}
|
|
subst = Environment(tools = ['textfile'], SUBST_DICT = substitutions)
|
|
substitutions['@foo@'] = 'foo'
|
|
subst['SUBST_DICT']['@bar@'] = 'bar'
|
|
subst.Substfile('pgm1.c', [Value('#include "@foo@.h"'),
|
|
Value('#include "@bar@.h"'),
|
|
"common.in",
|
|
"pgm1.in"
|
|
])
|
|
subst.Substfile('pgm2.c', [Value('#include "@foo@.h"'),
|
|
Value('#include "@bar@.h"'),
|
|
"common.in",
|
|
"pgm2.in"
|
|
])
|
|
|
|
</pre></dd><dt><a name="b-Tar"></a><span class="term">
|
|
<code class="function">Tar()</code>
|
|
, </span><span class="term">
|
|
<code class="function">env.Tar()</code>
|
|
</span></dt><dd><p>
|
|
Builds a tar archive of the specified files
|
|
and/or directories.
|
|
Unlike most builder methods,
|
|
the
|
|
<code class="function">Tar</code>
|
|
builder method may be called multiple times
|
|
for a given target;
|
|
each additional call
|
|
adds to the list of entries
|
|
that will be built into the archive.
|
|
Any source directories will
|
|
be scanned for changes to
|
|
any on-disk files,
|
|
regardless of whether or not
|
|
<code class="filename">scons</code>
|
|
knows about them from other Builder or function calls.
|
|
</p><pre class="screen">
|
|
env.Tar('src.tar', 'src')
|
|
|
|
# Create the stuff.tar file.
|
|
env.Tar('stuff', ['subdir1', 'subdir2'])
|
|
# Also add "another" to the stuff.tar file.
|
|
env.Tar('stuff', 'another')
|
|
|
|
# Set TARFLAGS to create a gzip-filtered archive.
|
|
env = Environment(TARFLAGS = '-c -z')
|
|
env.Tar('foo.tar.gz', 'foo')
|
|
|
|
# Also set the suffix to .tgz.
|
|
env = Environment(TARFLAGS = '-c -z',
|
|
TARSUFFIX = '.tgz')
|
|
env.Tar('foo')
|
|
</pre></dd><dt><a name="b-Textfile"></a><span class="term">
|
|
<code class="function">Textfile()</code>
|
|
, </span><span class="term">
|
|
<code class="function">env.Textfile()</code>
|
|
</span></dt><dd><p>
|
|
The <code class="function">Textfile</code> builder generates a single text file.
|
|
The source strings constitute the lines;
|
|
nested lists of sources are flattened.
|
|
<code class="envar">$LINESEPARATOR</code> is used to separate the strings.
|
|
</p><p>
|
|
If present, the <code class="envar">$SUBST_DICT</code> construction variable
|
|
is used to modify the strings before they are written;
|
|
see the <code class="function">Substfile</code> description for details.
|
|
</p><p>
|
|
The prefix and suffix specified by the <code class="envar">$TEXTFILEPREFIX</code>
|
|
and <code class="envar">$TEXTFILESUFFIX</code> construction variables
|
|
(the null string and <code class="filename">.txt</code> by default, respectively)
|
|
are automatically added to the target if they are not already present.
|
|
Examples:
|
|
</p><pre class="screen">
|
|
# builds/writes foo.txt
|
|
env.Textfile(target = 'foo.txt', source = ['Goethe', 42, 'Schiller'])
|
|
|
|
# builds/writes bar.txt
|
|
env.Textfile(target = 'bar',
|
|
source = ['lalala', 'tanteratei'],
|
|
LINESEPARATOR='|*')
|
|
|
|
# nested lists are flattened automatically
|
|
env.Textfile(target = 'blob',
|
|
source = ['lalala', ['Goethe', 42 'Schiller'], 'tanteratei'])
|
|
|
|
# files may be used as input by wraping them in File()
|
|
env.Textfile(target = 'concat', # concatenate files with a marker between
|
|
source = [File('concat1'), File('concat2')],
|
|
LINESEPARATOR = '====================\n')
|
|
|
|
Results are:
|
|
foo.txt
|
|
....8<----
|
|
Goethe
|
|
42
|
|
Schiller
|
|
....8<---- (no linefeed at the end)
|
|
|
|
bar.txt:
|
|
....8<----
|
|
lalala|*tanteratei
|
|
....8<---- (no linefeed at the end)
|
|
|
|
blob.txt
|
|
....8<----
|
|
lalala
|
|
Goethe
|
|
42
|
|
Schiller
|
|
tanteratei
|
|
....8<---- (no linefeed at the end)
|
|
</pre></dd><dt><a name="b-Translate"></a><span class="term">
|
|
<code class="function">Translate()</code>
|
|
, </span><span class="term">
|
|
<code class="function">env.Translate()</code>
|
|
</span></dt><dd><p>
|
|
This pseudo-builder belongs to <a class="link" href="#t-gettext"><code class="literal">gettext</code></a> toolset. The builder extracts
|
|
internationalized messages from source files, updates <code class="literal">POT</code>
|
|
template (if necessary) and then updates <code class="literal">PO</code> translations (if
|
|
necessary). If <a class="link" href="#cv-POAUTOINIT"><code class="envar">$POAUTOINIT</code></a> is set, missing <code class="literal">PO</code> files
|
|
will be automatically created (i.e. without translator person intervention).
|
|
The variables <a class="link" href="#cv-LINGUAS_FILE"><code class="envar">$LINGUAS_FILE</code></a> and <a class="link" href="#cv-POTDOMAIN"><code class="envar">$POTDOMAIN</code></a> are taken into
|
|
acount too. All other construction variables used by <a class="link" href="#b-POTUpdate"><code class="function">POTUpdate</code></a>, and
|
|
<a class="link" href="#b-POUpdate"><code class="function">POUpdate</code></a> work here too.
|
|
</p><p>
|
|
<span class="emphasis"><em>Example 1</em></span>.
|
|
The simplest way is to specify input files and output languages inline in
|
|
a SCons script when invoking <code class="function">Translate</code>
|
|
</p><pre class="screen">
|
|
# SConscript in 'po/' directory
|
|
env = Environment( tools = ["default", "gettext"] )
|
|
env['POAUTOINIT'] = 1
|
|
env.Translate(['en','pl'], ['../a.cpp','../b.cpp'])
|
|
</pre><p>
|
|
<span class="emphasis"><em>Example 2</em></span>.
|
|
If you wish, you may also stick to conventional style known from
|
|
<span class="productname">autotools</span>, i.e. using
|
|
<code class="filename">POTFILES.in</code> and <code class="filename">LINGUAS</code> files
|
|
</p><pre class="screen">
|
|
# LINGUAS
|
|
en pl
|
|
#end
|
|
</pre><pre class="screen">
|
|
# POTFILES.in
|
|
a.cpp
|
|
b.cpp
|
|
# end
|
|
</pre><pre class="screen">
|
|
# SConscript
|
|
env = Environment( tools = ["default", "gettext"] )
|
|
env['POAUTOINIT'] = 1
|
|
env['XGETTEXTPATH'] = ['../']
|
|
env.Translate(LINGUAS_FILE = 1, XGETTEXTFROM = 'POTFILES.in')
|
|
</pre><p>
|
|
The last approach is perhaps the recommended one. It allows easily split
|
|
internationalization/localization onto separate SCons scripts, where a script
|
|
in source tree is responsible for translations (from sources to
|
|
<code class="literal">PO</code> files) and script(s) under variant directories are
|
|
responsible for compilation of <code class="literal">PO</code> to <code class="literal">MO</code>
|
|
files to and for installation of <code class="literal">MO</code> files. The "gluing
|
|
factor" synchronizing these two scripts is then the content of
|
|
<code class="filename">LINGUAS</code> file. Note, that the updated
|
|
<code class="literal">POT</code> and <code class="literal">PO</code> files are usually going to be
|
|
committed back to the repository, so they must be updated within the source
|
|
directory (and not in variant directories). Additionaly, the file listing of
|
|
<code class="filename">po/</code> directory contains <code class="filename">LINGUAS</code> file,
|
|
so the source tree looks familiar to translators, and they may work with the
|
|
project in their usual way.
|
|
</p><p>
|
|
<span class="emphasis"><em>Example 3</em></span>.
|
|
Let's prepare a development tree as below
|
|
</p><pre class="screen">
|
|
project/
|
|
+ SConstruct
|
|
+ build/
|
|
+ src/
|
|
+ po/
|
|
+ SConscript
|
|
+ SConscript.i18n
|
|
+ POTFILES.in
|
|
+ LINGUAS
|
|
</pre><p>
|
|
with <code class="filename">build</code> being variant directory. Write the top-level
|
|
<code class="filename">SConstruct</code> script as follows
|
|
</p><pre class="screen">
|
|
# SConstruct
|
|
env = Environment( tools = ["default", "gettext"] )
|
|
VariantDir('build', 'src', duplicate = 0)
|
|
env['POAUTOINIT'] = 1
|
|
SConscript('src/po/SConscript.i18n', exports = 'env')
|
|
SConscript('build/po/SConscript', exports = 'env')
|
|
</pre><p>
|
|
the <code class="filename">src/po/SConscript.i18n</code> as
|
|
</p><pre class="screen">
|
|
# src/po/SConscript.i18n
|
|
Import('env')
|
|
env.Translate(LINGUAS_FILE=1, XGETTEXTFROM='POTFILES.in', XGETTEXTPATH=['../'])
|
|
</pre><p>
|
|
and the <code class="filename">src/po/SConscript</code>
|
|
</p><pre class="screen">
|
|
# src/po/SConscript
|
|
Import('env')
|
|
env.MOFiles(LINGUAS_FILE = 1)
|
|
</pre><p>
|
|
Such setup produces <code class="literal">POT</code> and <code class="literal">PO</code> files
|
|
under source tree in <code class="filename">src/po/</code> and binary
|
|
<code class="literal">MO</code> files under variant tree in
|
|
<code class="filename">build/po/</code>. This way the <code class="literal">POT</code> and
|
|
<code class="literal">PO</code> files are separated from other output files, which must
|
|
not be committed back to source repositories (e.g. <code class="literal">MO</code>
|
|
files).
|
|
</p><p>
|
|
</p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>In above example, the <code class="literal">PO</code> files are not updated,
|
|
nor created automatically when you issue <span class="command"><strong>scons '.'</strong></span> command.
|
|
The files must be updated (created) by hand via <span class="command"><strong>scons
|
|
po-update</strong></span> and then <code class="literal">MO</code> files can be compiled by
|
|
running <span class="command"><strong>scons '.'</strong></span>.</p></div><p>
|
|
</p></dd><dt><a name="b-TypeLibrary"></a><span class="term">
|
|
<code class="function">TypeLibrary()</code>
|
|
, </span><span class="term">
|
|
<code class="function">env.TypeLibrary()</code>
|
|
</span></dt><dd><p>
|
|
Builds a Windows type library (<code class="filename">.tlb</code>)
|
|
file from an input IDL file (<code class="filename">.idl</code>).
|
|
In addition, it will build the associated interface stub and
|
|
proxy source files,
|
|
naming them according to the base name of the <code class="filename">.idl</code> file.
|
|
For example,
|
|
</p><pre class="screen">
|
|
env.TypeLibrary(source="foo.idl")
|
|
</pre><p>
|
|
Will create <code class="filename">foo.tlb</code>,
|
|
<code class="filename">foo.h</code>,
|
|
<code class="filename">foo_i.c</code>,
|
|
<code class="filename">foo_p.c</code>
|
|
and
|
|
<code class="filename">foo_data.c</code>
|
|
files.
|
|
</p></dd><dt><a name="b-Uic"></a><span class="term">
|
|
<code class="function">Uic()</code>
|
|
, </span><span class="term">
|
|
<code class="function">env.Uic()</code>
|
|
</span></dt><dd><p>
|
|
Builds a header file, an implementation file and a moc file from an ui file.
|
|
and returns the corresponding nodes in the above order.
|
|
This builder is only available after using the tool 'qt'. Note: you can
|
|
specify <code class="filename">.ui</code> files directly as source
|
|
files to the <code class="function">Program</code>,
|
|
<code class="function">Library</code> and <code class="function">SharedLibrary</code> builders
|
|
without using this builder. Using this builder lets you override the standard
|
|
naming conventions (be careful: prefixes are always prepended to names of
|
|
built files; if you don't want prefixes, you may set them to ``).
|
|
See the <a class="link" href="#cv-QTDIR"><code class="envar">$QTDIR</code></a> variable for more information.
|
|
Example:
|
|
</p><pre class="screen">
|
|
env.Uic('foo.ui') # -> ['foo.h', 'uic_foo.cc', 'moc_foo.cc']
|
|
env.Uic(target = Split('include/foo.h gen/uicfoo.cc gen/mocfoo.cc'),
|
|
source = 'foo.ui') # -> ['include/foo.h', 'gen/uicfoo.cc', 'gen/mocfoo.cc']
|
|
</pre></dd><dt><a name="b-Zip"></a><span class="term">
|
|
<code class="function">Zip()</code>
|
|
, </span><span class="term">
|
|
<code class="function">env.Zip()</code>
|
|
</span></dt><dd><p>
|
|
Builds a zip archive of the specified files
|
|
and/or directories.
|
|
Unlike most builder methods,
|
|
the
|
|
<code class="function">Zip</code>
|
|
builder method may be called multiple times
|
|
for a given target;
|
|
each additional call
|
|
adds to the list of entries
|
|
that will be built into the archive.
|
|
Any source directories will
|
|
be scanned for changes to
|
|
any on-disk files,
|
|
regardless of whether or not
|
|
<code class="filename">scons</code>
|
|
knows about them from other Builder or function calls.
|
|
</p><pre class="screen">
|
|
env.Zip('src.zip', 'src')
|
|
|
|
# Create the stuff.zip file.
|
|
env.Zip('stuff', ['subdir1', 'subdir2'])
|
|
# Also add "another" to the stuff.tar file.
|
|
env.Zip('stuff', 'another')
|
|
</pre></dd></dl></div><p>All
|
|
targets of builder methods automatically depend on their sources.
|
|
An explicit dependency can
|
|
be specified using the
|
|
<span class="bold"><strong>Depends</strong></span>
|
|
method of a construction environment (see below).</p><p>In addition,
|
|
<span class="command"><strong>scons</strong></span>
|
|
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
|
|
<span class="markup">.F</span>
|
|
(POSIX systems only),
|
|
<span class="markup">.fpp,</span>
|
|
or
|
|
<span class="markup">.FPP</span>
|
|
file extensions,
|
|
and assembly language files with
|
|
<span class="markup">.S</span>
|
|
(POSIX systems only),
|
|
<span class="markup">.spp,</span>
|
|
or
|
|
<span class="markup">.SPP</span>
|
|
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
|
|
<span class="bold"><strong>Object</strong></span>(),
|
|
<span class="bold"><strong>StaticObject</strong></span>(),
|
|
and
|
|
<span class="bold"><strong>SharedObject</strong></span>()
|
|
Builders by adding them
|
|
to the
|
|
<span class="bold"><strong>SourceFileScanner</strong></span>
|
|
object.
|
|
See the section "Scanner Objects"
|
|
below, for more information about
|
|
defining your own Scanner objects
|
|
and using the
|
|
<span class="bold"><strong>SourceFileScanner</strong></span>
|
|
object.</p></div><div class="refsect2" title="Methods and Functions to Do Things"><a name="methods_and_functions_to_do_things"></a><h3>Methods and Functions to Do Things</h3><p>In addition to Builder methods,
|
|
<span class="command"><strong>scons</strong></span>
|
|
provides a number of other construction environment methods
|
|
and global functions to
|
|
manipulate the build configuration.</p><p>Usually, a construction environment method
|
|
and global function with the same name both exist
|
|
so that you don't have to remember whether
|
|
to a specific bit of functionality
|
|
must be called with or without a construction environment.
|
|
In the following list,
|
|
if you call something as a global function
|
|
it looks like:</p><pre class="literallayout">
|
|
Function(<span class="emphasis"><em>arguments</em></span>)
|
|
</pre><p>and if you call something through a construction
|
|
environment it looks like:</p><pre class="literallayout">
|
|
env.Function(<span class="emphasis"><em>arguments</em></span>)
|
|
</pre><p>If you can call the functionality in both ways,
|
|
then both forms are listed.</p><p>Global functions may be called from custom Python modules that you
|
|
import into an SConscript file by adding the following
|
|
to the Python module:</p><pre class="literallayout">
|
|
from SCons.Script import *
|
|
</pre><p>Except where otherwise noted,
|
|
the same-named
|
|
construction environment method
|
|
and global function
|
|
provide the exact same functionality.
|
|
The only difference is that,
|
|
where appropriate,
|
|
calling the functionality through a construction environment will
|
|
substitute construction variables into
|
|
any supplied strings.
|
|
For example:</p><pre class="literallayout">
|
|
env = Environment(FOO = 'foo')
|
|
Default('$FOO')
|
|
env.Default('$FOO')
|
|
</pre><p>In the above example,
|
|
the first call to the global
|
|
<span class="bold"><strong>Default()</strong></span>
|
|
function will actually add a target named
|
|
<span class="bold"><strong>$FOO</strong></span>
|
|
to the list of default targets,
|
|
while the second call to the
|
|
<span class="bold"><strong>env.Default()</strong></span>
|
|
construction environment method
|
|
will expand the value
|
|
and add a target named
|
|
<span class="bold"><strong>foo</strong></span>
|
|
to the list of default targets.
|
|
For more on construction variable expansion,
|
|
see the next section on
|
|
construction variables.</p><p>Construction environment methods
|
|
and global functions supported by
|
|
<span class="command"><strong>scons</strong></span>
|
|
include:</p><div class="variablelist"><dl><dt><a name="f-Action"></a><span class="term">
|
|
<code class="literal">Action(action, [cmd/str/fun, [var, ...]] [option=value, ...])</code>
|
|
, </span><span class="term">
|
|
<code class="literal">env.Action(action, [cmd/str/fun, [var, ...]] [option=value, ...])</code>
|
|
</span></dt><dd><p>
|
|
Creates an Action object for
|
|
the specified
|
|
<code class="varname">action</code>.
|
|
See the section "Action Objects,"
|
|
below, for a complete explanation of the arguments and behavior.
|
|
</p><p>
|
|
Note that the
|
|
<code class="function">env.Action</code>()
|
|
form of the invocation will expand
|
|
construction variables in any argument strings,
|
|
including the
|
|
<code class="varname">action</code>
|
|
argument, at the time it is called
|
|
using the construction variables in the
|
|
<code class="varname">env</code>
|
|
construction environment through which
|
|
<code class="function">env.Action</code>()
|
|
was called.
|
|
The
|
|
<code class="function">Action</code>()
|
|
form delays all variable expansion
|
|
until the Action object is actually used.
|
|
</p></dd><dt><a name="f-AddMethod"></a><span class="term">
|
|
<code class="literal">AddMethod(object, function, [name])</code>
|
|
, </span><span class="term">
|
|
<code class="literal">env.AddMethod(function, [name])</code>
|
|
</span></dt><dd><p>
|
|
When called with the
|
|
<code class="function">AddMethod</code>()
|
|
form,
|
|
adds the specified
|
|
<code class="varname">function</code>
|
|
to the specified
|
|
<code class="varname">object</code>
|
|
as the specified method
|
|
<code class="varname">name</code>.
|
|
When called with the
|
|
<code class="function">env.AddMethod</code>()
|
|
form,
|
|
adds the specified
|
|
<code class="varname">function</code>
|
|
to the construction environment
|
|
<code class="varname">env</code>
|
|
as the specified method
|
|
<code class="varname">name</code>.
|
|
In both cases, if
|
|
<code class="varname">name</code>
|
|
is omitted or
|
|
<code class="literal">None</code>,
|
|
the name of the
|
|
specified
|
|
<code class="varname">function</code>
|
|
itself is used for the method name.
|
|
</p><p>
|
|
Examples:
|
|
</p><pre class="screen">
|
|
# Note that the first argument to the function to
|
|
# be attached as a method must be the object through
|
|
# which the method will be called; the Python
|
|
# convention is to call it 'self'.
|
|
def my_method(self, arg):
|
|
print("my_method() got", arg)
|
|
|
|
# Use the global AddMethod() function to add a method
|
|
# to the Environment class. This
|
|
AddMethod(Environment, my_method)
|
|
env = Environment()
|
|
env.my_method('arg')
|
|
|
|
# Add the function as a method, using the function
|
|
# name for the method call.
|
|
env = Environment()
|
|
env.AddMethod(my_method, 'other_method_name')
|
|
env.other_method_name('another arg')
|
|
</pre></dd><dt><a name="f-AddOption"></a><span class="term">
|
|
<code class="literal">AddOption(arguments)</code>
|
|
</span></dt><dd><p>
|
|
This function adds a new command-line option to be recognized.
|
|
The specified
|
|
<code class="varname">arguments</code>
|
|
are the same as supported by the standard Python
|
|
<code class="function">optparse.add_option</code>()
|
|
method (with a few additional capabilities noted below);
|
|
see the documentation for
|
|
<code class="literal">optparse</code>
|
|
for a thorough discussion of its option-processing capabities.
|
|
</p><p>
|
|
In addition to the arguments and values supported by the
|
|
<code class="function">optparse.add_option</code>()
|
|
method,
|
|
the SCons
|
|
<code class="function">AddOption</code>
|
|
function allows you to set the
|
|
<code class="literal">nargs</code>
|
|
keyword value to
|
|
<code class="literal">'?'</code>
|
|
(a string with just the question mark)
|
|
to indicate that the specified long option(s) take(s) an
|
|
<span class="emphasis"><em>optional</em></span>
|
|
argument.
|
|
When
|
|
<code class="literal">nargs = '?'</code>
|
|
is passed to the
|
|
<code class="function">AddOption</code>
|
|
function, the
|
|
<code class="literal">const</code>
|
|
keyword argument
|
|
may be used to supply the "default"
|
|
value that should be used when the
|
|
option is specified on the command line
|
|
without an explicit argument.
|
|
</p><p>
|
|
If no
|
|
<code class="literal">default=</code>
|
|
keyword argument is supplied when calling
|
|
<code class="function">AddOption</code>,
|
|
the option will have a default value of
|
|
<code class="literal">None</code>.
|
|
</p><p>
|
|
Once a new command-line option has been added with
|
|
<code class="function">AddOption</code>,
|
|
the option value may be accessed using
|
|
<code class="function">GetOption</code>
|
|
or
|
|
<code class="function">env.GetOption</code>().
|
|
The value may also be set, using
|
|
<code class="function">SetOption</code>
|
|
or
|
|
<code class="function">env.SetOption</code>(),
|
|
if conditions in a
|
|
<code class="filename">SConscript</code>
|
|
require overriding any default value.
|
|
Note, however, that a
|
|
value specified on the command line will
|
|
<span class="emphasis"><em>always</em></span>
|
|
override a value set by any SConscript file.
|
|
</p><p>
|
|
Any specified
|
|
<code class="literal">help=</code>
|
|
strings for the new option(s)
|
|
will be displayed by the
|
|
<code class="option">-H</code>
|
|
or
|
|
<code class="option">-h</code>
|
|
options
|
|
(the latter only if no other help text is
|
|
specified in the SConscript files).
|
|
The help text for the local options specified by
|
|
<code class="function">AddOption</code>
|
|
will appear below the SCons options themselves,
|
|
under a separate
|
|
<code class="literal">Local Options</code>
|
|
heading.
|
|
The options will appear in the help text
|
|
in the order in which the
|
|
<code class="function">AddOption</code>
|
|
calls occur.
|
|
</p><p>
|
|
Example:
|
|
</p><pre class="screen">
|
|
AddOption('--prefix',
|
|
dest='prefix',
|
|
nargs=1, type='string',
|
|
action='store',
|
|
metavar='DIR',
|
|
help='installation prefix')
|
|
env = Environment(PREFIX = GetOption('prefix'))
|
|
</pre></dd><dt><a name="f-AddPostAction"></a><span class="term">
|
|
<code class="literal">AddPostAction(target, action)</code>
|
|
, </span><span class="term">
|
|
<code class="literal">env.AddPostAction(target, action)</code>
|
|
</span></dt><dd><p>
|
|
Arranges for the specified
|
|
<code class="varname">action</code>
|
|
to be performed
|
|
after the specified
|
|
<code class="varname">target</code>
|
|
has been built.
|
|
The specified action(s) may be
|
|
an Action object, or anything that
|
|
can be converted into an Action object
|
|
(see below).
|
|
</p><p>
|
|
When multiple targets are supplied,
|
|
the action may be called multiple times,
|
|
once after each action that generates
|
|
one or more targets in the list.
|
|
</p></dd><dt><a name="f-AddPreAction"></a><span class="term">
|
|
<code class="literal">AddPreAction(target, action)</code>
|
|
, </span><span class="term">
|
|
<code class="literal">env.AddPreAction(target, action)</code>
|
|
</span></dt><dd><p>
|
|
Arranges for the specified
|
|
<code class="varname">action</code>
|
|
to be performed
|
|
before the specified
|
|
<code class="varname">target</code>
|
|
is built.
|
|
The specified action(s) may be
|
|
an Action object, or anything that
|
|
can be converted into an Action object
|
|
(see below).
|
|
</p><p>
|
|
When multiple targets are specified,
|
|
the action(s) may be called multiple times,
|
|
once before each action that generates
|
|
one or more targets in the list.
|
|
</p><p>
|
|
Note that if any of the targets are built in multiple steps,
|
|
the action will be invoked just
|
|
before the "final" action that specifically
|
|
generates the specified target(s).
|
|
For example, when building an executable program
|
|
from a specified source
|
|
<code class="filename">.c</code>
|
|
file via an intermediate object file:
|
|
</p><pre class="screen">
|
|
foo = Program('foo.c')
|
|
AddPreAction(foo, 'pre_action')
|
|
</pre><p>
|
|
The specified
|
|
<code class="literal">pre_action</code>
|
|
would be executed before
|
|
<code class="filename">scons</code>
|
|
calls the link command that actually
|
|
generates the executable program binary
|
|
<code class="filename">foo</code>,
|
|
not before compiling the
|
|
<code class="filename">foo.c</code>
|
|
file into an object file.
|
|
</p></dd><dt><a name="f-Alias"></a><span class="term">
|
|
<code class="literal">Alias(alias, [targets, [action]])</code>
|
|
, </span><span class="term">
|
|
<code class="literal">env.Alias(alias, [targets, [action]])</code>
|
|
</span></dt><dd><p>
|
|
Creates one or more phony targets that
|
|
expand to one or more other targets.
|
|
An optional
|
|
<code class="varname">action</code>
|
|
(command)
|
|
or list of actions
|
|
can be specified that will be executed
|
|
whenever the any of the alias targets are out-of-date.
|
|
Returns the Node object representing the alias,
|
|
which exists outside of any file system.
|
|
This Node object, or the alias name,
|
|
may be used as a dependency of any other target,
|
|
including another alias.
|
|
<code class="function">Alias</code>
|
|
can be called multiple times for the same
|
|
alias to add additional targets to the alias,
|
|
or additional actions to the list for this alias.
|
|
</p><p>
|
|
Examples:
|
|
</p><pre class="screen">
|
|
Alias('install')
|
|
Alias('install', '/usr/bin')
|
|
Alias(['install', 'install-lib'], '/usr/local/lib')
|
|
|
|
env.Alias('install', ['/usr/local/bin', '/usr/local/lib'])
|
|
env.Alias('install', ['/usr/local/man'])
|
|
|
|
env.Alias('update', ['file1', 'file2'], "update_database $SOURCES")
|
|
</pre></dd><dt><a name="f-AllowSubstExceptions"></a><span class="term">
|
|
<code class="literal">AllowSubstExceptions([exception, ...])</code>
|
|
</span></dt><dd><p>
|
|
Specifies the exceptions that will be allowed
|
|
when expanding construction variables.
|
|
By default,
|
|
any construction variable expansions that generate a
|
|
<code class="literal">NameError</code>
|
|
or
|
|
<code class="literal">IndexError</code>
|
|
exception will expand to a
|
|
<code class="literal">''</code>
|
|
(a null string) and not cause scons to fail.
|
|
All exceptions not in the specified list
|
|
will generate an error message
|
|
and terminate processing.
|
|
</p><p>
|
|
If
|
|
<code class="function">AllowSubstExceptions</code>
|
|
is called multiple times,
|
|
each call completely overwrites the previous list
|
|
of allowed exceptions.
|
|
</p><p>
|
|
Example:
|
|
</p><pre class="screen">
|
|
# Requires that all construction variable names exist.
|
|
# (You may wish to do this if you want to enforce strictly
|
|
# that all construction variables must be defined before use.)
|
|
AllowSubstExceptions()
|
|
|
|
# Also allow a string containing a zero-division expansion
|
|
# like '${1 / 0}' to evalute to ''.
|
|
AllowSubstExceptions(IndexError, NameError, ZeroDivisionError)
|
|
</pre></dd><dt><a name="f-AlwaysBuild"></a><span class="term">
|
|
<code class="literal">AlwaysBuild(target, ...)</code>
|
|
, </span><span class="term">
|
|
<code class="literal">env.AlwaysBuild(target, ...)</code>
|
|
</span></dt><dd><p>
|
|
Marks each given
|
|
<code class="varname">target</code>
|
|
so that it is always assumed to be out of date,
|
|
and will always be rebuilt if needed.
|
|
Note, however, that
|
|
<code class="function">AlwaysBuild</code>
|
|
does not add its target(s) to the default target list,
|
|
so the targets will only be built
|
|
if they are specified on the command line,
|
|
or are a dependent of a target specified on the command line--but
|
|
they will
|
|
<span class="emphasis"><em>always</em></span>
|
|
be built if so specified.
|
|
Multiple targets can be passed in to a single call to
|
|
<code class="function">AlwaysBuild</code>.
|
|
</p></dd><dt><a name="f-Append"></a><span class="term">
|
|
<code class="literal">env.Append(key=val, [...])</code>
|
|
</span></dt><dd><p>
|
|
Appends the specified keyword arguments
|
|
to the end of construction variables in the environment.
|
|
If the Environment does not have
|
|
the specified construction variable,
|
|
it is simply added to the environment.
|
|
If the values of the construction variable
|
|
and the keyword argument are the same type,
|
|
then the two values will be simply added together.
|
|
Otherwise, the construction variable
|
|
and the value of the keyword argument
|
|
are both coerced to lists,
|
|
and the lists are added together.
|
|
(See also the Prepend method, below.)
|
|
</p><p>
|
|
Example:
|
|
</p><pre class="screen">
|
|
env.Append(CCFLAGS = ' -g', FOO = ['foo.yyy'])
|
|
</pre></dd><dt><a name="f-AppendENVPath"></a><span class="term">
|
|
<code class="literal">env.AppendENVPath(name, newpath, [envname, sep, delete_existing])</code>
|
|
</span></dt><dd><p>
|
|
This appends new path elements to the given path in the
|
|
specified external environment
|
|
(<code class="literal">ENV</code>
|
|
by default).
|
|
This will only add
|
|
any particular path once (leaving the last one it encounters and
|
|
ignoring the rest, to preserve path order),
|
|
and to help assure this,
|
|
will normalize all paths (using
|
|
<code class="function">os.path.normpath</code>
|
|
and
|
|
<code class="function">os.path.normcase</code>).
|
|
This can also handle the
|
|
case where the given old path variable is a list instead of a
|
|
string, in which case a list will be returned instead of a string.
|
|
</p><p>
|
|
If
|
|
<code class="varname">delete_existing</code>
|
|
is 0, then adding a path that already exists
|
|
will not move it to the end; it will stay where it is in the list.
|
|
</p><p>
|
|
Example:
|
|
</p><pre class="screen">
|
|
print 'before:',env['ENV']['INCLUDE']
|
|
include_path = '/foo/bar:/foo'
|
|
env.AppendENVPath('INCLUDE', include_path)
|
|
print 'after:',env['ENV']['INCLUDE']
|
|
|
|
yields:
|
|
before: /foo:/biz
|
|
after: /biz:/foo/bar:/foo
|
|
</pre></dd><dt><a name="f-AppendUnique"></a><span class="term">
|
|
<code class="literal">env.AppendUnique(key=val, [...], delete_existing=0)</code>
|
|
</span></dt><dd><p>
|
|
Appends the specified keyword arguments
|
|
to the end of construction variables in the environment.
|
|
If the Environment does not have
|
|
the specified construction variable,
|
|
it is simply added to the environment.
|
|
If the construction variable being appended to is a list,
|
|
then any value(s) that already exist in the
|
|
construction variable will
|
|
<span class="emphasis"><em>not</em></span>
|
|
be added again to the list.
|
|
However, if delete_existing is 1,
|
|
existing matching values are removed first, so
|
|
existing values in the arg list move to the end of the list.
|
|
</p><p>
|
|
Example:
|
|
</p><pre class="screen">
|
|
env.AppendUnique(CCFLAGS = '-g', FOO = ['foo.yyy'])
|
|
</pre></dd><dt><a name="f-BuildDir"></a><span class="term">
|
|
<code class="literal">BuildDir(build_dir, src_dir, [duplicate])</code>
|
|
, </span><span class="term">
|
|
<code class="literal">env.BuildDir(build_dir, src_dir, [duplicate])</code>
|
|
</span></dt><dd><p>
|
|
Deprecated synonyms for
|
|
<code class="function">VariantDir</code>
|
|
and
|
|
<code class="function">env.VariantDir</code>().
|
|
The
|
|
<code class="varname">build_dir</code>
|
|
argument becomes the
|
|
<code class="varname">variant_dir</code>
|
|
argument of
|
|
<code class="function">VariantDir</code>
|
|
or
|
|
<code class="function">env.VariantDir</code>().
|
|
</p></dd><dt><a name="f-Builder"></a><span class="term">
|
|
<code class="literal">Builder(action, [arguments])</code>
|
|
, </span><span class="term">
|
|
<code class="literal">env.Builder(action, [arguments])</code>
|
|
</span></dt><dd><p>
|
|
Creates a Builder object for
|
|
the specified
|
|
<code class="varname">action</code>.
|
|
See the section "Builder Objects,"
|
|
below, for a complete explanation of the arguments and behavior.
|
|
</p><p>
|
|
Note that the
|
|
<code class="function">env.Builder</code>()
|
|
form of the invocation will expand
|
|
construction variables in any arguments strings,
|
|
including the
|
|
<code class="varname">action</code>
|
|
argument,
|
|
at the time it is called
|
|
using the construction variables in the
|
|
<code class="varname">env</code>
|
|
construction environment through which
|
|
<code class="function">env.Builder</code>()
|
|
was called.
|
|
The
|
|
<code class="function">Builder</code>
|
|
form delays all variable expansion
|
|
until after the Builder object is actually called.
|
|
</p></dd><dt><a name="f-CacheDir"></a><span class="term">
|
|
<code class="literal">CacheDir(cache_dir)</code>
|
|
, </span><span class="term">
|
|
<code class="literal">env.CacheDir(cache_dir)</code>
|
|
</span></dt><dd><p>
|
|
Specifies that
|
|
<code class="filename">scons</code>
|
|
will maintain a cache of derived files in
|
|
<code class="varname">cache_dir</code>.
|
|
The derived files in the cache will be shared
|
|
among all the builds using the same
|
|
<code class="function">CacheDir</code>
|
|
call.
|
|
Specifying a
|
|
<code class="varname">cache_dir</code>
|
|
of
|
|
<code class="literal">None</code>
|
|
disables derived file caching.
|
|
</p><p>
|
|
Calling
|
|
<code class="function">env.CacheDir</code>()
|
|
will only affect targets built
|
|
through the specified construction environment.
|
|
Calling
|
|
<code class="function">CacheDir</code>
|
|
sets a global default
|
|
that will be used by all targets built
|
|
through construction environments
|
|
that do
|
|
<span class="emphasis"><em>not</em></span>
|
|
have an
|
|
<code class="function">env.CacheDir</code>()
|
|
specified.
|
|
</p><p>
|
|
When a
|
|
<code class="function">CacheDir</code>()
|
|
is being used and
|
|
<code class="filename">scons</code>
|
|
finds a derived file that needs to be rebuilt,
|
|
it will first look in the cache to see if a
|
|
derived file has already been built
|
|
from identical input files and an identical build action
|
|
(as incorporated into the MD5 build signature).
|
|
If so,
|
|
<code class="filename">scons</code>
|
|
will retrieve the file from the cache.
|
|
If the derived file is not present in the cache,
|
|
<code class="filename">scons</code>
|
|
will rebuild it and
|
|
then place a copy of the built file in the cache
|
|
(identified by its MD5 build signature),
|
|
so that it may be retrieved by other
|
|
builds that need to build the same derived file
|
|
from identical inputs.
|
|
</p><p>
|
|
Use of a specified
|
|
<code class="function">CacheDir</code>
|
|
may be disabled for any invocation
|
|
by using the
|
|
<code class="option">--cache-disable</code>
|
|
option.
|
|
</p><p>
|
|
If the
|
|
<code class="option">--cache-force</code>
|
|
option is used,
|
|
<code class="filename">scons</code>
|
|
will place a copy of
|
|
<span class="emphasis"><em>all</em></span>
|
|
derived files in the cache,
|
|
even if they already existed
|
|
and were not built by this invocation.
|
|
This is useful to populate a cache
|
|
the first time
|
|
<code class="function">CacheDir</code>
|
|
is added to a build,
|
|
or after using the
|
|
<code class="option">--cache-disable</code>
|
|
option.
|
|
</p><p>
|
|
When using
|
|
<code class="function">CacheDir</code>,
|
|
<code class="filename">scons</code>
|
|
will report,
|
|
"Retrieved `file' from cache,"
|
|
unless the
|
|
<code class="option">--cache-show</code>
|
|
option is being used.
|
|
When the
|
|
<code class="option">--cache-show</code>
|
|
option is used,
|
|
<code class="filename">scons</code>
|
|
will print the action that
|
|
<span class="emphasis"><em>would</em></span>
|
|
have been used to build the file,
|
|
without any indication that
|
|
the file was actually retrieved from the cache.
|
|
This is useful to generate build logs
|
|
that are equivalent regardless of whether
|
|
a given derived file has been built in-place
|
|
or retrieved from the cache.
|
|
</p><p>
|
|
The
|
|
<a class="link" href="#f-NoCache"><code class="function">NoCache</code></a>
|
|
method can be used to disable caching of specific files. This can be
|
|
useful if inputs and/or outputs of some tool are impossible to
|
|
predict or prohibitively large.
|
|
</p></dd><dt><a name="f-Clean"></a><span class="term">
|
|
<code class="literal">Clean(targets, files_or_dirs)</code>
|
|
, </span><span class="term">
|
|
<code class="literal">env.Clean(targets, files_or_dirs)</code>
|
|
</span></dt><dd><p>
|
|
This specifies a list of files or directories which should be removed
|
|
whenever the targets are specified with the
|
|
<code class="option">-c</code>
|
|
command line option.
|
|
The specified targets may be a list
|
|
or an individual target.
|
|
Multiple calls to
|
|
<code class="function">Clean</code>
|
|
are legal,
|
|
and create new targets or add files and directories to the
|
|
clean list for the specified targets.
|
|
</p><p>
|
|
Multiple files or directories should be specified
|
|
either as separate arguments to the
|
|
<code class="function">Clean</code>
|
|
method, or as a list.
|
|
<code class="function">Clean</code>
|
|
will also accept the return value of any of the construction environment
|
|
Builder methods.
|
|
Examples:
|
|
</p><p>
|
|
The related
|
|
<a class="link" href="#f-NoClean"><code class="function">NoClean</code></a>
|
|
function overrides calling
|
|
<code class="function">Clean</code>
|
|
for the same target,
|
|
and any targets passed to both functions will
|
|
<span class="emphasis"><em>not</em></span>
|
|
be removed by the
|
|
<code class="option">-c</code>
|
|
option.
|
|
</p><p>
|
|
Examples:
|
|
</p><pre class="screen">
|
|
Clean('foo', ['bar', 'baz'])
|
|
Clean('dist', env.Program('hello', 'hello.c'))
|
|
Clean(['foo', 'bar'], 'something_else_to_clean')
|
|
</pre><p>
|
|
In this example,
|
|
installing the project creates a subdirectory for the documentation.
|
|
This statement causes the subdirectory to be removed
|
|
if the project is deinstalled.
|
|
</p><pre class="screen">
|
|
Clean(docdir, os.path.join(docdir, projectname))
|
|
</pre></dd><dt><a name="f-Clone"></a><span class="term">
|
|
<code class="literal">env.Clone([key=val, ...])</code>
|
|
</span></dt><dd><p>
|
|
Returns a separate copy of a construction environment.
|
|
If there are any keyword arguments specified,
|
|
they are added to the returned copy,
|
|
overwriting any existing values
|
|
for the keywords.
|
|
</p><p>
|
|
Example:
|
|
</p><pre class="screen">
|
|
env2 = env.Clone()
|
|
env3 = env.Clone(CCFLAGS = '-g')
|
|
</pre><p>
|
|
Additionally, a list of tools and a toolpath may be specified, as in
|
|
the Environment constructor:
|
|
</p><pre class="screen">
|
|
def MyTool(env): env['FOO'] = 'bar'
|
|
env4 = env.Clone(tools = ['msvc', MyTool])
|
|
</pre><p>
|
|
The
|
|
<code class="varname">parse_flags</code>
|
|
keyword argument is also recognized:
|
|
</p><pre class="screen">
|
|
# create an environment for compiling programs that use wxWidgets
|
|
wx_env = env.Clone(parse_flags = '!wx-config --cflags --cxxflags')
|
|
</pre></dd><dt><a name="f-Command"></a><span class="term">
|
|
<code class="literal">Command(target, source, action, [key=val, ...])</code>
|
|
, </span><span class="term">
|
|
<code class="literal">env.Command(target, source, action, [key=val, ...])</code>
|
|
</span></dt><dd><p>
|
|
Executes a specific action
|
|
(or list of actions)
|
|
to build a target file or files.
|
|
This is more convenient
|
|
than defining a separate Builder object
|
|
for a single special-case build.
|
|
</p><p>
|
|
As a special case, the
|
|
<code class="varname">source_scanner</code>
|
|
keyword argument can
|
|
be used to specify
|
|
a Scanner object
|
|
that will be used to scan the sources.
|
|
(The global
|
|
<code class="literal">DirScanner</code>
|
|
object can be used
|
|
if any of the sources will be directories
|
|
that must be scanned on-disk for
|
|
changes to files that aren't
|
|
already specified in other Builder of function calls.)
|
|
</p><p>
|
|
Any other keyword arguments specified override any
|
|
same-named existing construction variables.
|
|
</p><p>
|
|
An action can be an external command,
|
|
specified as a string,
|
|
or a callable Python object;
|
|
see "Action Objects," below,
|
|
for more complete information.
|
|
Also note that a string specifying an external command
|
|
may be preceded by an
|
|
<code class="literal">@</code>
|
|
(at-sign)
|
|
to suppress printing the command in question,
|
|
or by a
|
|
<code class="literal">-</code>
|
|
(hyphen)
|
|
to ignore the exit status of the external command.
|
|
</p><p>
|
|
Examples:
|
|
</p><pre class="screen">
|
|
env.Command('foo.out', 'foo.in',
|
|
"$FOO_BUILD < $SOURCES > $TARGET")
|
|
|
|
env.Command('bar.out', 'bar.in',
|
|
["rm -f $TARGET",
|
|
"$BAR_BUILD < $SOURCES > $TARGET"],
|
|
ENV = {'PATH' : '/usr/local/bin/'})
|
|
|
|
def rename(env, target, source):
|
|
import os
|
|
os.rename('.tmp', str(target[0]))
|
|
|
|
env.Command('baz.out', 'baz.in',
|
|
["$BAZ_BUILD < $SOURCES > .tmp",
|
|
rename ])
|
|
</pre><p>
|
|
Note that the
|
|
<code class="function">Command</code>
|
|
function will usually assume, by default,
|
|
that the specified targets and/or sources are Files,
|
|
if no other part of the configuration
|
|
identifies what type of entry it is.
|
|
If necessary, you can explicitly specify
|
|
that targets or source nodes should
|
|
be treated as directoriese
|
|
by using the
|
|
<a class="link" href="#f-Dir"><code class="function">Dir</code></a>
|
|
or
|
|
<code class="function">env.Dir</code>()
|
|
functions.
|
|
</p><p>
|
|
Examples:
|
|
</p><pre class="screen">
|
|
env.Command('ddd.list', Dir('ddd'), 'ls -l $SOURCE > $TARGET')
|
|
|
|
env['DISTDIR'] = 'destination/directory'
|
|
env.Command(env.Dir('$DISTDIR')), None, make_distdir)
|
|
</pre><p>
|
|
(Also note that SCons will usually
|
|
automatically create any directory necessary to hold a target file,
|
|
so you normally don't need to create directories by hand.)
|
|
</p></dd><dt><a name="f-Configure"></a><span class="term">
|
|
<code class="literal">Configure(env, [custom_tests, conf_dir, log_file, config_h])</code>
|
|
, </span><span class="term">
|
|
<code class="literal">env.Configure([custom_tests, conf_dir, log_file, config_h])</code>
|
|
</span></dt><dd><p>
|
|
Creates a Configure object for integrated
|
|
functionality similar to GNU autoconf.
|
|
See the section "Configure Contexts,"
|
|
below, for a complete explanation of the arguments and behavior.
|
|
</p></dd><dt><a name="f-Copy"></a><span class="term">
|
|
<code class="literal">env.Copy([key=val, ...])</code>
|
|
</span></dt><dd><p>
|
|
A now-deprecated synonym for
|
|
<code class="function">env.Clone</code>().
|
|
</p></dd><dt><a name="f-Decider"></a><span class="term">
|
|
<code class="literal">Decider(function)</code>
|
|
, </span><span class="term">
|
|
<code class="literal">env.Decider(function)</code>
|
|
</span></dt><dd><p>
|
|
Specifies that all up-to-date decisions for
|
|
targets built through this construction environment
|
|
will be handled by the specified
|
|
<code class="varname">function</code>.
|
|
The
|
|
<code class="varname">function</code>
|
|
can be one of the following strings
|
|
that specify the type of decision function
|
|
to be performed:
|
|
</p><p>
|
|
</p><div class="variablelist"><dl><dt><span class="term"><code class="literal">timestamp-newer</code></span></dt><dd><p>
|
|
Specifies that a target shall be considered out of date and rebuilt
|
|
if the dependency's timestamp is newer than the target file's timestamp.
|
|
This is the behavior of the classic Make utility,
|
|
and
|
|
<code class="literal">make</code>
|
|
can be used a synonym for
|
|
<code class="literal">timestamp-newer</code>.
|
|
</p></dd><dt><span class="term"><code class="literal">timestamp-match</code></span></dt><dd><p>
|
|
Specifies that a target shall be considered out of date and rebuilt
|
|
if the dependency's timestamp is different than the
|
|
timestamp recorded the last time the target was built.
|
|
This provides behavior very similar to the classic Make utility
|
|
(in particular, files are not opened up so that their
|
|
contents can be checksummed)
|
|
except that the target will also be rebuilt if a
|
|
dependency file has been restored to a version with an
|
|
<span class="emphasis"><em>earlier</em></span>
|
|
timestamp, such as can happen when restoring files from backup archives.
|
|
</p></dd><dt><span class="term"><code class="literal">MD5</code></span></dt><dd><p>
|
|
Specifies that a target shall be considered out of date and rebuilt
|
|
if the dependency's content has changed since the last time
|
|
the target was built,
|
|
as determined be performing an MD5 checksum
|
|
on the dependency's contents
|
|
and comparing it to the checksum recorded the
|
|
last time the target was built.
|
|
<code class="literal">content</code>
|
|
can be used as a synonym for
|
|
<code class="literal">MD5</code>.
|
|
</p></dd><dt><span class="term"><code class="literal">MD5-timestamp</code></span></dt><dd><p>
|
|
Specifies that a target shall be considered out of date and rebuilt
|
|
if the dependency's content has changed since the last time
|
|
the target was built,
|
|
except that dependencies with a timestamp that matches
|
|
the last time the target was rebuilt will be
|
|
assumed to be up-to-date and
|
|
<span class="emphasis"><em>not</em></span>
|
|
rebuilt.
|
|
This provides behavior very similar
|
|
to the
|
|
<code class="literal">MD5</code>
|
|
behavior of always checksumming file contents,
|
|
with an optimization of not checking
|
|
the contents of files whose timestamps haven't changed.
|
|
The drawback is that SCons will
|
|
<span class="emphasis"><em>not</em></span>
|
|
detect if a file's content has changed
|
|
but its timestamp is the same,
|
|
as might happen in an automated script
|
|
that runs a build,
|
|
updates a file,
|
|
and runs the build again,
|
|
all within a single second.
|
|
</p></dd></dl></div><p>
|
|
</p><p>
|
|
Examples:
|
|
</p><pre class="screen">
|
|
# Use exact timestamp matches by default.
|
|
Decider('timestamp-match')
|
|
|
|
# Use MD5 content signatures for any targets built
|
|
# with the attached construction environment.
|
|
env.Decider('content')
|
|
</pre><p>
|
|
In addition to the above already-available functions,
|
|
the
|
|
<code class="varname">function</code>
|
|
argument may be an actual Python function
|
|
that takes the following three arguments:
|
|
</p><p>
|
|
</p><div class="variablelist"><dl><dt><span class="term"><em class="parameter"><code>dependency</code></em></span></dt><dd><p>
|
|
The Node (file) which
|
|
should cause the
|
|
<code class="varname">target</code>
|
|
to be rebuilt
|
|
if it has "changed" since the last tme
|
|
<code class="varname">target</code>
|
|
was built.
|
|
</p></dd><dt><span class="term"><em class="parameter"><code>target</code></em></span></dt><dd><p>
|
|
The Node (file) being built.
|
|
In the normal case,
|
|
this is what should get rebuilt
|
|
if the
|
|
<code class="varname">dependency</code>
|
|
has "changed."
|
|
</p></dd><dt><span class="term"><em class="parameter"><code>prev_ni</code></em></span></dt><dd><p>
|
|
Stored information about the state of the
|
|
<code class="varname">dependency</code>
|
|
the last time the
|
|
<code class="varname">target</code>
|
|
was built.
|
|
This can be consulted to match various
|
|
file characteristics
|
|
such as the timestamp,
|
|
size, or content signature.
|
|
</p></dd></dl></div><p>
|
|
</p><p>
|
|
The
|
|
<code class="varname">function</code>
|
|
should return a
|
|
<code class="literal">True</code>
|
|
(non-zero)
|
|
value if the
|
|
<code class="varname">dependency</code>
|
|
has "changed" since the last time
|
|
the
|
|
<code class="varname">target</code>
|
|
was built
|
|
(indicating that the target
|
|
<span class="emphasis"><em>should</em></span>
|
|
be rebuilt),
|
|
and
|
|
<code class="literal">False</code>
|
|
(zero)
|
|
otherwise
|
|
(indicating that the target should
|
|
<span class="emphasis"><em>not</em></span>
|
|
be rebuilt).
|
|
Note that the decision can be made
|
|
using whatever criteria are appopriate.
|
|
Ignoring some or all of the function arguments
|
|
is perfectly normal.
|
|
</p><p>
|
|
Example:
|
|
</p><pre class="screen">
|
|
def my_decider(dependency, target, prev_ni):
|
|
return not os.path.exists(str(target))
|
|
|
|
env.Decider(my_decider)
|
|
</pre></dd><dt><a name="f-Default"></a><span class="term">
|
|
<code class="literal">Default(targets)</code>
|
|
, </span><span class="term">
|
|
<code class="literal">env.Default(targets)</code>
|
|
</span></dt><dd><p>
|
|
This specifies a list of default targets,
|
|
which will be built by
|
|
<code class="filename">scons</code>
|
|
if no explicit targets are given on the command line.
|
|
Multiple calls to
|
|
<code class="function">Default</code>
|
|
are legal,
|
|
and add to the list of default targets.
|
|
</p><p>
|
|
Multiple targets should be specified as
|
|
separate arguments to the
|
|
<code class="function">Default</code>
|
|
method, or as a list.
|
|
<code class="function">Default</code>
|
|
will also accept the Node returned by any
|
|
of a construction environment's
|
|
builder methods.
|
|
</p><p>
|
|
Examples:
|
|
</p><pre class="screen">
|
|
Default('foo', 'bar', 'baz')
|
|
env.Default(['a', 'b', 'c'])
|
|
hello = env.Program('hello', 'hello.c')
|
|
env.Default(hello)
|
|
</pre><p>
|
|
An argument to
|
|
<code class="function">Default</code>
|
|
of
|
|
<code class="literal">None</code>
|
|
will clear all default targets.
|
|
Later calls to
|
|
<code class="function">Default</code>
|
|
will add to the (now empty) default-target list
|
|
like normal.
|
|
</p><p>
|
|
The current list of targets added using the
|
|
<code class="function">Default</code>
|
|
function or method is available in the
|
|
<code class="literal">DEFAULT_TARGETS</code>
|
|
list;
|
|
see below.
|
|
</p></dd><dt><a name="f-DefaultEnvironment"></a><span class="term">
|
|
<code class="literal">DefaultEnvironment([args])</code>
|
|
</span></dt><dd><p>
|
|
Creates and returns a default construction environment object.
|
|
This construction environment is used internally by SCons
|
|
in order to execute many of the global functions in this list,
|
|
and to fetch source files transparently
|
|
from source code management systems.
|
|
</p></dd><dt><a name="f-Depends"></a><span class="term">
|
|
<code class="literal">Depends(target, dependency)</code>
|
|
, </span><span class="term">
|
|
<code class="literal">env.Depends(target, dependency)</code>
|
|
</span></dt><dd><p>
|
|
Specifies an explicit dependency;
|
|
the
|
|
<code class="varname">target</code>
|
|
will be rebuilt
|
|
whenever the
|
|
<code class="varname">dependency</code>
|
|
has changed.
|
|
Both the specified
|
|
<code class="varname">target</code>
|
|
and
|
|
<code class="varname">dependency</code>
|
|
can be a string
|
|
(usually the path name of a file or directory)
|
|
or Node objects,
|
|
or a list of strings or Node objects
|
|
(such as returned by a Builder call).
|
|
This should only be necessary
|
|
for cases where the dependency
|
|
is not caught by a Scanner
|
|
for the file.
|
|
</p><p>
|
|
Example:
|
|
</p><pre class="screen">
|
|
env.Depends('foo', 'other-input-file-for-foo')
|
|
|
|
mylib = env.Library('mylib.c')
|
|
installed_lib = env.Install('lib', mylib)
|
|
bar = env.Program('bar.c')
|
|
|
|
# Arrange for the library to be copied into the installation
|
|
# directory before trying to build the "bar" program.
|
|
# (Note that this is for example only. A "real" library
|
|
# dependency would normally be configured through the $LIBS
|
|
# and $LIBPATH variables, not using an env.Depends() call.)
|
|
|
|
env.Depends(bar, installed_lib)
|
|
</pre></dd><dt><a name="f-Dictionary"></a><span class="term">
|
|
<code class="literal">env.Dictionary([vars])</code>
|
|
</span></dt><dd><p>
|
|
Returns a dictionary object
|
|
containing copies of all of the
|
|
construction variables in the environment.
|
|
If there are any variable names specified,
|
|
only the specified construction
|
|
variables are returned in the dictionary.
|
|
</p><p>
|
|
Example:
|
|
</p><pre class="screen">
|
|
dict = env.Dictionary()
|
|
cc_dict = env.Dictionary('CC', 'CCFLAGS', 'CCCOM')
|
|
</pre></dd><dt><a name="f-Dir"></a><span class="term">
|
|
<code class="literal">Dir(name, [directory])</code>
|
|
, </span><span class="term">
|
|
<code class="literal">env.Dir(name, [directory])</code>
|
|
</span></dt><dd><p>
|
|
This returns a Directory Node,
|
|
an object that represents the specified directory
|
|
<code class="varname">name</code>.
|
|
<code class="varname">name</code>
|
|
can be a relative or absolute path.
|
|
<code class="varname">directory</code>
|
|
is an optional directory that will be used as the parent directory.
|
|
If no
|
|
<code class="varname">directory</code>
|
|
is specified, the current script's directory is used as the parent.
|
|
</p><p>
|
|
If
|
|
<code class="varname">name</code>
|
|
is a list, SCons returns a list of Dir nodes.
|
|
Construction variables are expanded in
|
|
<code class="varname">name</code>.
|
|
</p><p>
|
|
Directory Nodes can be used anywhere you
|
|
would supply a string as a directory name
|
|
to a Builder method or function.
|
|
Directory Nodes have attributes and methods
|
|
that are useful in many situations;
|
|
see "File and Directory Nodes," below.
|
|
</p></dd><dt><a name="f-Dump"></a><span class="term">
|
|
<code class="literal">env.Dump([key])</code>
|
|
</span></dt><dd><p>
|
|
Returns a pretty printable representation of the environment.
|
|
<code class="varname">key</code>,
|
|
if not
|
|
<code class="literal">None</code>,
|
|
should be a string containing the name of the variable of interest.
|
|
</p><p>
|
|
This SConstruct:
|
|
</p><pre class="screen">
|
|
env=Environment()
|
|
print env.Dump('CCCOM')
|
|
</pre><p>
|
|
will print:
|
|
</p><pre class="screen">
|
|
'$CC -c -o $TARGET $CCFLAGS $CPPFLAGS $_CPPDEFFLAGS $_CPPINCFLAGS $SOURCES'
|
|
</pre><p>
|
|
While this SConstruct:
|
|
</p><pre class="screen">
|
|
env=Environment()
|
|
print env.Dump()
|
|
</pre><p>
|
|
will print:
|
|
</p><pre class="screen">
|
|
{ 'AR': 'ar',
|
|
'ARCOM': '$AR $ARFLAGS $TARGET $SOURCES\n$RANLIB $RANLIBFLAGS $TARGET',
|
|
'ARFLAGS': ['r'],
|
|
'AS': 'as',
|
|
'ASCOM': '$AS $ASFLAGS -o $TARGET $SOURCES',
|
|
'ASFLAGS': [],
|
|
...
|
|
</pre></dd><dt><a name="f-EnsurePythonVersion"></a><span class="term">
|
|
<code class="literal">EnsurePythonVersion(major, minor)</code>
|
|
, </span><span class="term">
|
|
<code class="literal">env.EnsurePythonVersion(major, minor)</code>
|
|
</span></dt><dd><p>
|
|
Ensure that the Python version is at least
|
|
<code class="varname">major</code>.<code class="varname">minor</code>.
|
|
This function will
|
|
print out an error message and exit SCons with a non-zero exit code if the
|
|
actual Python version is not late enough.
|
|
</p><p>
|
|
Example:
|
|
</p><pre class="screen">
|
|
EnsurePythonVersion(2,2)
|
|
</pre></dd><dt><a name="f-EnsureSConsVersion"></a><span class="term">
|
|
<code class="literal">EnsureSConsVersion(major, minor, [revision])</code>
|
|
, </span><span class="term">
|
|
<code class="literal">env.EnsureSConsVersion(major, minor, [revision])</code>
|
|
</span></dt><dd><p>
|
|
Ensure that the SCons version is at least
|
|
<code class="varname">major.minor</code>,
|
|
or
|
|
<code class="varname">major.minor.revision</code>.
|
|
if
|
|
<code class="varname">revision</code>
|
|
is specified.
|
|
This function will
|
|
print out an error message and exit SCons with a non-zero exit code if the
|
|
actual SCons version is not late enough.
|
|
</p><p>
|
|
Examples:
|
|
</p><pre class="screen">
|
|
EnsureSConsVersion(0,14)
|
|
|
|
EnsureSConsVersion(0,96,90)
|
|
</pre></dd><dt><a name="f-Environment"></a><span class="term">
|
|
<code class="literal">Environment([key=value, ...])</code>
|
|
, </span><span class="term">
|
|
<code class="literal">env.Environment([key=value, ...])</code>
|
|
</span></dt><dd><p>
|
|
Return a new construction environment
|
|
initialized with the specified
|
|
<code class="varname">key</code><code class="literal">=</code><code class="varname">value</code>
|
|
pairs.
|
|
</p></dd><dt><a name="f-Execute"></a><span class="term">
|
|
<code class="literal">Execute(action, [strfunction, varlist])</code>
|
|
, </span><span class="term">
|
|
<code class="literal">env.Execute(action, [strfunction, varlist])</code>
|
|
</span></dt><dd><p>
|
|
Executes an Action object.
|
|
The specified
|
|
<code class="varname">action</code>
|
|
may be an Action object
|
|
(see the section "Action Objects,"
|
|
below, for a complete explanation of the arguments and behavior),
|
|
or it may be a command-line string,
|
|
list of commands,
|
|
or executable Python function,
|
|
each of which will be converted
|
|
into an Action object
|
|
and then executed.
|
|
The exit value of the command
|
|
or return value of the Python function
|
|
will be returned.
|
|
</p><p>
|
|
Note that
|
|
<code class="filename">scons</code>
|
|
will print an error message if the executed
|
|
<code class="varname">action</code>
|
|
fails--that is,
|
|
exits with or returns a non-zero value.
|
|
<code class="filename">scons</code>
|
|
will
|
|
<span class="emphasis"><em>not</em></span>,
|
|
however,
|
|
automatically terminate the build
|
|
if the specified
|
|
<code class="varname">action</code>
|
|
fails.
|
|
If you want the build to stop in response to a failed
|
|
<code class="function">Execute</code>
|
|
call,
|
|
you must explicitly check for a non-zero return value:
|
|
</p><pre class="screen">
|
|
Execute(Copy('file.out', 'file.in'))
|
|
|
|
if Execute("mkdir sub/dir/ectory"):
|
|
# The mkdir failed, don't try to build.
|
|
Exit(1)
|
|
</pre></dd><dt><a name="f-Exit"></a><span class="term">
|
|
<code class="literal">Exit([value])</code>
|
|
, </span><span class="term">
|
|
<code class="literal">env.Exit([value])</code>
|
|
</span></dt><dd><p>
|
|
This tells
|
|
<code class="filename">scons</code>
|
|
to exit immediately
|
|
with the specified
|
|
<code class="varname">value</code>.
|
|
A default exit value of
|
|
<code class="literal">0</code>
|
|
(zero)
|
|
is used if no value is specified.
|
|
</p></dd><dt><a name="f-Export"></a><span class="term">
|
|
<code class="literal">Export(vars)</code>
|
|
, </span><span class="term">
|
|
<code class="literal">env.Export(vars)</code>
|
|
</span></dt><dd><p>
|
|
This tells
|
|
<code class="filename">scons</code>
|
|
to export a list of variables from the current
|
|
SConscript file to all other SConscript files.
|
|
The exported variables are kept in a global collection,
|
|
so subsequent calls to
|
|
<code class="function">Export</code>
|
|
will over-write previous exports that have the same name.
|
|
Multiple variable names can be passed to
|
|
<code class="function">Export</code>
|
|
as separate arguments or as a list.
|
|
Keyword arguments can be used to provide names and their values.
|
|
A dictionary can be used to map variables to a different name when exported.
|
|
Both local variables and global variables can be exported.
|
|
</p><p>
|
|
Examples:
|
|
</p><pre class="screen">
|
|
env = Environment()
|
|
# Make env available for all SConscript files to Import().
|
|
Export("env")
|
|
|
|
package = 'my_name'
|
|
# Make env and package available for all SConscript files:.
|
|
Export("env", "package")
|
|
|
|
# Make env and package available for all SConscript files:
|
|
Export(["env", "package"])
|
|
|
|
# Make env available using the name debug:
|
|
Export(debug = env)
|
|
|
|
# Make env available using the name debug:
|
|
Export({"debug":env})
|
|
</pre><p>
|
|
Note that the
|
|
<code class="function">SConscript</code>
|
|
function supports an
|
|
<code class="varname">exports</code>
|
|
argument that makes it easier to to export a variable or
|
|
set of variables to a single SConscript file.
|
|
See the description of the
|
|
<code class="function">SConscript</code>
|
|
function, below.
|
|
</p></dd><dt><a name="f-File"></a><span class="term">
|
|
<code class="literal">File(name, [directory])</code>
|
|
, </span><span class="term">
|
|
<code class="literal">env.File(name, [directory])</code>
|
|
</span></dt><dd><p>
|
|
This returns a
|
|
File Node,
|
|
an object that represents the specified file
|
|
<code class="varname">name</code>.
|
|
<code class="varname">name</code>
|
|
can be a relative or absolute path.
|
|
<code class="varname">directory</code>
|
|
is an optional directory that will be used as the parent directory.
|
|
</p><p>
|
|
If
|
|
<code class="varname">name</code>
|
|
is a list, SCons returns a list of File nodes.
|
|
Construction variables are expanded in
|
|
<code class="varname">name</code>.
|
|
</p><p>
|
|
File Nodes can be used anywhere you
|
|
would supply a string as a file name
|
|
to a Builder method or function.
|
|
File Nodes have attributes and methods
|
|
that are useful in many situations;
|
|
see "File and Directory Nodes," below.
|
|
</p></dd><dt><a name="f-FindFile"></a><span class="term">
|
|
<code class="literal">FindFile(file, dirs)</code>
|
|
, </span><span class="term">
|
|
<code class="literal">env.FindFile(file, dirs)</code>
|
|
</span></dt><dd><p>
|
|
Search for
|
|
<code class="varname">file</code>
|
|
in the path specified by
|
|
<code class="varname">dirs</code>.
|
|
<code class="varname">dirs</code>
|
|
may be a list of directory names or a single directory name.
|
|
In addition to searching for files that exist in the filesystem,
|
|
this function also searches for derived files
|
|
that have not yet been built.
|
|
</p><p>
|
|
Example:
|
|
</p><pre class="screen">
|
|
foo = env.FindFile('foo', ['dir1', 'dir2'])
|
|
</pre></dd><dt><a name="f-FindInstalledFiles"></a><span class="term">
|
|
<code class="literal">FindInstalledFiles()</code>
|
|
, </span><span class="term">
|
|
<code class="literal">env.FindInstalledFiles()</code>
|
|
</span></dt><dd><p>
|
|
Returns the list of targets set up by the
|
|
<a class="link" href="#b-Install"><code class="function">Install</code></a>
|
|
or
|
|
<a class="link" href="#b-InstallAs"><code class="function">InstallAs</code></a>
|
|
builders.
|
|
</p><p>
|
|
This function serves as a convenient method to select the contents of
|
|
a binary package.
|
|
</p><p>
|
|
Example:
|
|
</p><pre class="screen">
|
|
Install( '/bin', [ 'executable_a', 'executable_b' ] )
|
|
|
|
# will return the file node list
|
|
# [ '/bin/executable_a', '/bin/executable_b' ]
|
|
FindInstalledFiles()
|
|
|
|
Install( '/lib', [ 'some_library' ] )
|
|
|
|
# will return the file node list
|
|
# [ '/bin/executable_a', '/bin/executable_b', '/lib/some_library' ]
|
|
FindInstalledFiles()
|
|
</pre></dd><dt><a name="f-FindPathDirs"></a><span class="term">
|
|
<code class="literal">FindPathDirs(variable)</code>
|
|
</span></dt><dd><p>
|
|
Returns a function
|
|
(actually a callable Python object)
|
|
intended to be used as the
|
|
<code class="varname">path_function</code>
|
|
of a Scanner object.
|
|
The returned object will look up the specified
|
|
<code class="varname">variable</code>
|
|
in a construction environment
|
|
and treat the construction variable's value as a list of
|
|
directory paths that should be searched
|
|
(like
|
|
<a class="link" href="#cv-CPPPATH"><code class="envar">$CPPPATH</code></a>,
|
|
<a class="link" href="#cv-LIBPATH"><code class="envar">$LIBPATH</code></a>,
|
|
etc.).
|
|
</p><p>
|
|
Note that use of
|
|
<code class="function">FindPathDirs</code>
|
|
is generally preferable to
|
|
writing your own
|
|
<code class="varname">path_function</code>
|
|
for the following reasons:
|
|
1) The returned list will contain all appropriate directories
|
|
found in source trees
|
|
(when
|
|
<a class="link" href="#f-VariantDir"><code class="function">VariantDir</code></a>
|
|
is used)
|
|
or in code repositories
|
|
(when
|
|
<code class="function">Repository</code>
|
|
or the
|
|
<code class="option">-Y</code>
|
|
option are used).
|
|
2) scons will identify expansions of
|
|
<code class="varname">variable</code>
|
|
that evaluate to the same list of directories as,
|
|
in fact, the same list,
|
|
and avoid re-scanning the directories for files,
|
|
when possible.
|
|
</p><p>
|
|
Example:
|
|
</p><pre class="screen">
|
|
def my_scan(node, env, path, arg):
|
|
# Code to scan file contents goes here...
|
|
return include_files
|
|
|
|
scanner = Scanner(name = 'myscanner',
|
|
function = my_scan,
|
|
path_function = FindPathDirs('MYPATH'))
|
|
</pre></dd><dt><a name="f-FindSourceFiles"></a><span class="term">
|
|
<code class="literal">FindSourceFiles(node='"."')</code>
|
|
, </span><span class="term">
|
|
<code class="literal">env.FindSourceFiles(node='"."')</code>
|
|
</span></dt><dd><p>
|
|
Returns the list of nodes which serve as the source of the built files.
|
|
It does so by inspecting the dependency tree starting at the optional
|
|
argument
|
|
<code class="varname">node</code>
|
|
which defaults to the '"."'-node. It will then return all leaves of
|
|
<code class="varname">node</code>.
|
|
These are all children which have no further children.
|
|
</p><p>
|
|
This function is a convenient method to select the contents of a Source
|
|
Package.
|
|
</p><p>
|
|
Example:
|
|
</p><pre class="screen">
|
|
Program( 'src/main_a.c' )
|
|
Program( 'src/main_b.c' )
|
|
Program( 'main_c.c' )
|
|
|
|
# returns ['main_c.c', 'src/main_a.c', 'SConstruct', 'src/main_b.c']
|
|
FindSourceFiles()
|
|
|
|
# returns ['src/main_b.c', 'src/main_a.c' ]
|
|
FindSourceFiles( 'src' )
|
|
</pre><p>
|
|
As you can see build support files (SConstruct in the above example)
|
|
will also be returned by this function.
|
|
</p></dd><dt><a name="f-Flatten"></a><span class="term">
|
|
<code class="literal">Flatten(sequence)</code>
|
|
, </span><span class="term">
|
|
<code class="literal">env.Flatten(sequence)</code>
|
|
</span></dt><dd><p>
|
|
Takes a sequence (that is, a Python list or tuple)
|
|
that may contain nested sequences
|
|
and returns a flattened list containing
|
|
all of the individual elements in any sequence.
|
|
This can be helpful for collecting
|
|
the lists returned by calls to Builders;
|
|
other Builders will automatically
|
|
flatten lists specified as input,
|
|
but direct Python manipulation of
|
|
these lists does not.
|
|
</p><p>
|
|
Examples:
|
|
</p><pre class="screen">
|
|
foo = Object('foo.c')
|
|
bar = Object('bar.c')
|
|
|
|
# Because `foo' and `bar' are lists returned by the Object() Builder,
|
|
# `objects' will be a list containing nested lists:
|
|
objects = ['f1.o', foo, 'f2.o', bar, 'f3.o']
|
|
|
|
# Passing such a list to another Builder is all right because
|
|
# the Builder will flatten the list automatically:
|
|
Program(source = objects)
|
|
|
|
# If you need to manipulate the list directly using Python, you need to
|
|
# call Flatten() yourself, or otherwise handle nested lists:
|
|
for object in Flatten(objects):
|
|
print str(object)
|
|
</pre></dd><dt><a name="f-GetBuildFailures"></a><span class="term">
|
|
<code class="literal">GetBuildFailures()</code>
|
|
</span></dt><dd><p>
|
|
Returns a list of exceptions for the
|
|
actions that failed while
|
|
attempting to build targets.
|
|
Each element in the returned list is a
|
|
<code class="classname">BuildError</code>
|
|
object
|
|
with the following attributes
|
|
that record various aspects
|
|
of the build failure:
|
|
</p><p>
|
|
<code class="literal">.node</code>
|
|
The node that was being built
|
|
when the build failure occurred.
|
|
</p><p>
|
|
<code class="literal">.status</code>
|
|
The numeric exit status
|
|
returned by the command or Python function
|
|
that failed when trying to build the
|
|
specified Node.
|
|
</p><p>
|
|
<code class="literal">.errstr</code>
|
|
The SCons error string
|
|
describing the build failure.
|
|
(This is often a generic
|
|
message like "Error 2"
|
|
to indicate that an executed
|
|
command exited with a status of 2.)
|
|
</p><p>
|
|
<code class="literal">.filename</code>
|
|
The name of the file or
|
|
directory that actually caused the failure.
|
|
This may be different from the
|
|
<code class="literal">.node</code>
|
|
attribute.
|
|
For example,
|
|
if an attempt to build a target named
|
|
<code class="filename">sub/dir/target</code>
|
|
fails because the
|
|
<code class="filename">sub/dir</code>
|
|
directory could not be created,
|
|
then the
|
|
<code class="literal">.node</code>
|
|
attribute will be
|
|
<code class="filename">sub/dir/target</code>
|
|
but the
|
|
<code class="literal">.filename</code>
|
|
attribute will be
|
|
<code class="filename">sub/dir</code>.
|
|
</p><p>
|
|
<code class="literal">.executor</code>
|
|
The SCons Executor object
|
|
for the target Node
|
|
being built.
|
|
This can be used to retrieve
|
|
the construction environment used
|
|
for the failed action.
|
|
</p><p>
|
|
<code class="literal">.action</code>
|
|
The actual SCons Action object that failed.
|
|
This will be one specific action
|
|
out of the possible list of
|
|
actions that would have been
|
|
executed to build the target.
|
|
</p><p>
|
|
<code class="literal">.command</code>
|
|
The actual expanded command that was executed and failed,
|
|
after expansion of
|
|
<a class="link" href="#cv-TARGET"><code class="envar">$TARGET</code></a>,
|
|
<a class="link" href="#cv-SOURCE"><code class="envar">$SOURCE</code></a>,
|
|
and other construction variables.
|
|
</p><p>
|
|
Note that the
|
|
<code class="function">GetBuildFailures</code>
|
|
function
|
|
will always return an empty list
|
|
until any build failure has occurred,
|
|
which means that
|
|
<code class="function">GetBuildFailures</code>
|
|
will always return an empty list
|
|
while the
|
|
<code class="filename">SConscript</code>
|
|
files are being read.
|
|
Its primary intended use is
|
|
for functions that will be
|
|
executed before SCons exits
|
|
by passing them to the
|
|
standard Python
|
|
<code class="function">atexit.register</code>()
|
|
function.
|
|
Example:
|
|
</p><pre class="screen">
|
|
import atexit
|
|
|
|
def print_build_failures():
|
|
from SCons.Script import GetBuildFailures
|
|
for bf in GetBuildFailures():
|
|
print("%s failed: %s" % (bf.node, bf.errstr))
|
|
|
|
atexit.register(print_build_failures)
|
|
</pre></dd><dt><a name="f-GetBuildPath"></a><span class="term">
|
|
<code class="literal">GetBuildPath(file, [...])</code>
|
|
, </span><span class="term">
|
|
<code class="literal">env.GetBuildPath(file, [...])</code>
|
|
</span></dt><dd><p>
|
|
Returns the
|
|
<code class="filename">scons</code>
|
|
path name (or names) for the specified
|
|
<code class="varname">file</code>
|
|
(or files).
|
|
The specified
|
|
<code class="varname">file</code>
|
|
or files
|
|
may be
|
|
<code class="filename">scons</code>
|
|
Nodes or strings representing path names.
|
|
</p></dd><dt><a name="f-GetLaunchDir"></a><span class="term">
|
|
<code class="literal">GetLaunchDir()</code>
|
|
, </span><span class="term">
|
|
<code class="literal">env.GetLaunchDir()</code>
|
|
</span></dt><dd><p>
|
|
Returns the absolute path name of the directory from which
|
|
<code class="filename">scons</code>
|
|
was initially invoked.
|
|
This can be useful when using the
|
|
<code class="option">-u</code>,
|
|
<code class="option">-U</code>
|
|
or
|
|
<code class="option">-D</code>
|
|
options, which internally
|
|
change to the directory in which the
|
|
<code class="filename">SConstruct</code>
|
|
file is found.
|
|
</p></dd><dt><a name="f-GetOption"></a><span class="term">
|
|
<code class="literal">GetOption(name)</code>
|
|
, </span><span class="term">
|
|
<code class="literal">env.GetOption(name)</code>
|
|
</span></dt><dd><p>
|
|
This function provides a way to query the value of
|
|
SCons options set on scons command line
|
|
(or set using the
|
|
<a class="link" href="#f-SetOption"><code class="function">SetOption</code></a>
|
|
function).
|
|
The options supported are:
|
|
</p><p>
|
|
</p><div class="variablelist"><dl><dt><span class="term"><code class="literal">cache_debug</code></span></dt><dd><p>
|
|
which corresponds to --cache-debug;
|
|
</p></dd><dt><span class="term"><code class="literal">cache_disable</code></span></dt><dd><p>
|
|
which corresponds to --cache-disable;
|
|
</p></dd><dt><span class="term"><code class="literal">cache_force</code></span></dt><dd><p>
|
|
which corresponds to --cache-force;
|
|
</p></dd><dt><span class="term"><code class="literal">cache_show</code></span></dt><dd><p>
|
|
which corresponds to --cache-show;
|
|
</p></dd><dt><span class="term"><code class="literal">clean</code></span></dt><dd><p>
|
|
which corresponds to -c, --clean and --remove;
|
|
</p></dd><dt><span class="term"><code class="literal">config</code></span></dt><dd><p>
|
|
which corresponds to --config;
|
|
</p></dd><dt><span class="term"><code class="literal">directory</code></span></dt><dd><p>
|
|
which corresponds to -C and --directory;
|
|
</p></dd><dt><span class="term"><code class="literal">diskcheck</code></span></dt><dd><p>
|
|
which corresponds to --diskcheck
|
|
</p></dd><dt><span class="term"><code class="literal">duplicate</code></span></dt><dd><p>
|
|
which corresponds to --duplicate;
|
|
</p></dd><dt><span class="term"><code class="literal">file</code></span></dt><dd><p>
|
|
which corresponds to -f, --file, --makefile and --sconstruct;
|
|
</p></dd><dt><span class="term"><code class="literal">help</code></span></dt><dd><p>
|
|
which corresponds to -h and --help;
|
|
</p></dd><dt><span class="term"><code class="literal">ignore_errors</code></span></dt><dd><p>
|
|
which corresponds to --ignore-errors;
|
|
</p></dd><dt><span class="term"><code class="literal">implicit_cache</code></span></dt><dd><p>
|
|
which corresponds to --implicit-cache;
|
|
</p></dd><dt><span class="term"><code class="literal">implicit_deps_changed</code></span></dt><dd><p>
|
|
which corresponds to --implicit-deps-changed;
|
|
</p></dd><dt><span class="term"><code class="literal">implicit_deps_unchanged</code></span></dt><dd><p>
|
|
which corresponds to --implicit-deps-unchanged;
|
|
</p></dd><dt><span class="term"><code class="literal">interactive</code></span></dt><dd><p>
|
|
which corresponds to --interact and --interactive;
|
|
</p></dd><dt><span class="term"><code class="literal">keep_going</code></span></dt><dd><p>
|
|
which corresponds to -k and --keep-going;
|
|
</p></dd><dt><span class="term"><code class="literal">max_drift</code></span></dt><dd><p>
|
|
which corresponds to --max-drift;
|
|
</p></dd><dt><span class="term"><code class="literal">no_exec</code></span></dt><dd><p>
|
|
which corresponds to -n, --no-exec, --just-print, --dry-run and --recon;
|
|
</p></dd><dt><span class="term"><code class="literal">no_site_dir</code></span></dt><dd><p>
|
|
which corresponds to --no-site-dir;
|
|
</p></dd><dt><span class="term"><code class="literal">num_jobs</code></span></dt><dd><p>
|
|
which corresponds to -j and --jobs;
|
|
</p></dd><dt><span class="term"><code class="literal">profile_file</code></span></dt><dd><p>
|
|
which corresponds to --profile;
|
|
</p></dd><dt><span class="term"><code class="literal">question</code></span></dt><dd><p>
|
|
which corresponds to -q and --question;
|
|
</p></dd><dt><span class="term"><code class="literal">random</code></span></dt><dd><p>
|
|
which corresponds to --random;
|
|
</p></dd><dt><span class="term"><code class="literal">repository</code></span></dt><dd><p>
|
|
which corresponds to -Y, --repository and --srcdir;
|
|
</p></dd><dt><span class="term"><code class="literal">silent</code></span></dt><dd><p>
|
|
which corresponds to -s, --silent and --quiet;
|
|
</p></dd><dt><span class="term"><code class="literal">site_dir</code></span></dt><dd><p>
|
|
which corresponds to --site-dir;
|
|
</p></dd><dt><span class="term"><code class="literal">stack_size</code></span></dt><dd><p>
|
|
which corresponds to --stack-size;
|
|
</p></dd><dt><span class="term"><code class="literal">taskmastertrace_file</code></span></dt><dd><p>
|
|
which corresponds to --taskmastertrace; and
|
|
</p></dd><dt><span class="term"><code class="literal">warn</code></span></dt><dd><p>
|
|
which corresponds to --warn and --warning.
|
|
</p></dd></dl></div><p>
|
|
</p><p>
|
|
See the documentation for the
|
|
corresponding command line object for information about each specific
|
|
option.
|
|
</p></dd><dt><a name="f-Glob"></a><span class="term">
|
|
<code class="literal">Glob(pattern, [ondisk, source, strings, exclude])</code>
|
|
, </span><span class="term">
|
|
<code class="literal">env.Glob(pattern, [ondisk, source, strings, exclude])</code>
|
|
</span></dt><dd><p>
|
|
Returns Nodes (or strings) that match the specified
|
|
<code class="varname">pattern</code>,
|
|
relative to the directory of the current
|
|
<code class="filename">SConscript</code>
|
|
file.
|
|
The
|
|
<code class="function">env.Glob</code>()
|
|
form performs string substition on
|
|
<code class="varname">pattern</code>
|
|
and returns whatever matches
|
|
the resulting expanded pattern.
|
|
</p><p>
|
|
The specified
|
|
<code class="varname">pattern</code>
|
|
uses Unix shell style metacharacters for matching:
|
|
</p><pre class="screen">
|
|
* matches everything
|
|
? matches any single character
|
|
[seq] matches any character in seq
|
|
[!seq] matches any char not in seq
|
|
</pre><p>
|
|
If the first character of a filename is a dot,
|
|
it must be matched explicitly.
|
|
Character matches do
|
|
<span class="emphasis"><em>not</em></span>
|
|
span directory separators.
|
|
</p><p>
|
|
The
|
|
<code class="function">Glob</code>
|
|
knows about
|
|
repositories
|
|
(see the
|
|
<a class="link" href="#f-Repository"><code class="function">Repository</code></a>
|
|
function)
|
|
and source directories
|
|
(see the
|
|
<a class="link" href="#f-VariantDir"><code class="function">VariantDir</code></a>
|
|
function)
|
|
and
|
|
returns a Node (or string, if so configured)
|
|
in the local (SConscript) directory
|
|
if matching Node is found
|
|
anywhere in a corresponding
|
|
repository or source directory.
|
|
</p><p>
|
|
The
|
|
<code class="varname">ondisk</code>
|
|
argument may be set to
|
|
<code class="literal">False</code>
|
|
(or any other non-true value)
|
|
to disable the search for matches on disk,
|
|
thereby only returning matches among
|
|
already-configured File or Dir Nodes.
|
|
The default behavior is to
|
|
return corresponding Nodes
|
|
for any on-disk matches found.
|
|
</p><p>
|
|
The
|
|
<code class="varname">source</code>
|
|
argument may be set to
|
|
<code class="literal">True</code>
|
|
(or any equivalent value)
|
|
to specify that,
|
|
when the local directory is a
|
|
<code class="function">VariantDir</code>,
|
|
the returned Nodes should be from the
|
|
corresponding source directory,
|
|
not the local directory.
|
|
</p><p>
|
|
The
|
|
<code class="varname">strings</code>
|
|
argument may be set to
|
|
<code class="literal">True</code>
|
|
(or any equivalent value)
|
|
to have the
|
|
<code class="function">Glob</code>
|
|
function return strings, not Nodes,
|
|
that represent the matched files or directories.
|
|
The returned strings will be relative to
|
|
the local (SConscript) directory.
|
|
(Note that This may make it easier to perform
|
|
arbitrary manipulation of file names,
|
|
but if the returned strings are
|
|
passed to a different
|
|
<code class="filename">SConscript</code>
|
|
file,
|
|
any Node translation will be relative
|
|
to the other
|
|
<code class="filename">SConscript</code>
|
|
directory,
|
|
not the original
|
|
<code class="filename">SConscript</code>
|
|
directory.)
|
|
</p><p>
|
|
The
|
|
<code class="varname">exclude</code>
|
|
argument may be set to a pattern or a list of patterns
|
|
(following the same Unix shell semantics)
|
|
which must be filtered out of returned elements.
|
|
Elements matching a least one pattern of
|
|
this list will be excluded.
|
|
</p><p>
|
|
Examples:
|
|
</p><pre class="screen">
|
|
Program('foo', Glob('*.c'))
|
|
Zip('/tmp/everything', Glob('.??*') + Glob('*'))
|
|
sources = Glob('*.cpp', exclude=['os_*_specific_*.cpp']) + Glob('os_%s_specific_*.cpp'%currentOS)
|
|
</pre></dd><dt><a name="f-Help"></a><span class="term">
|
|
<code class="literal">Help(text, append=False)</code>
|
|
, </span><span class="term">
|
|
<code class="literal">env.Help(text, append=False)</code>
|
|
</span></dt><dd><p>
|
|
This specifies help text to be printed if the
|
|
<code class="option">-h</code>
|
|
argument is given to
|
|
<code class="filename">scons</code>.
|
|
If
|
|
<code class="function">Help</code>
|
|
is called multiple times, the text is appended together in the order that
|
|
<code class="function">Help</code>
|
|
is called. With append set to False, any
|
|
<code class="function">Help</code>
|
|
text generated with
|
|
<code class="function">AddOption</code>
|
|
is clobbered. If append is True, the AddOption help is prepended to the help
|
|
string, thus preserving the
|
|
<code class="option">-h</code>
|
|
message.
|
|
</p></dd><dt><a name="f-Ignore"></a><span class="term">
|
|
<code class="literal">Ignore(target, dependency)</code>
|
|
, </span><span class="term">
|
|
<code class="literal">env.Ignore(target, dependency)</code>
|
|
</span></dt><dd><p>
|
|
The specified dependency file(s)
|
|
will be ignored when deciding if
|
|
the target file(s) need to be rebuilt.
|
|
</p><p>
|
|
You can also use
|
|
<code class="function">Ignore</code>
|
|
to remove a target from the default build.
|
|
In order to do this you must specify the directory the target will
|
|
be built in as the target, and the file you want to skip building
|
|
as the dependency.
|
|
</p><p>
|
|
Note that this will only remove the dependencies listed from
|
|
the files built by default. It will still be built if that
|
|
dependency is needed by another object being built.
|
|
See the third and forth examples below.
|
|
</p><p>
|
|
Examples:
|
|
</p><pre class="screen">
|
|
env.Ignore('foo', 'foo.c')
|
|
env.Ignore('bar', ['bar1.h', 'bar2.h'])
|
|
env.Ignore('.','foobar.obj')
|
|
env.Ignore('bar','bar/foobar.obj')
|
|
</pre></dd><dt><a name="f-Import"></a><span class="term">
|
|
<code class="literal">Import(vars)</code>
|
|
, </span><span class="term">
|
|
<code class="literal">env.Import(vars)</code>
|
|
</span></dt><dd><p>
|
|
This tells
|
|
<code class="filename">scons</code>
|
|
to import a list of variables into the current SConscript file. This
|
|
will import variables that were exported with
|
|
<code class="function">Export</code>
|
|
or in the
|
|
<code class="varname">exports</code>
|
|
argument to
|
|
<a class="link" href="#f-SConscript"><code class="function">SConscript</code></a>.
|
|
Variables exported by
|
|
<code class="function">SConscript</code>
|
|
have precedence.
|
|
Multiple variable names can be passed to
|
|
<code class="function">Import</code>
|
|
as separate arguments or as a list. The variable "*" can be used
|
|
to import all variables.
|
|
</p><p>
|
|
Examples:
|
|
</p><pre class="screen">
|
|
Import("env")
|
|
Import("env", "variable")
|
|
Import(["env", "variable"])
|
|
Import("*")
|
|
</pre></dd><dt><a name="f-Literal"></a><span class="term">
|
|
<code class="literal">Literal(string)</code>
|
|
, </span><span class="term">
|
|
<code class="literal">env.Literal(string)</code>
|
|
</span></dt><dd><p>
|
|
The specified
|
|
<code class="varname">string</code>
|
|
will be preserved as-is
|
|
and not have construction variables expanded.
|
|
</p></dd><dt><a name="f-Local"></a><span class="term">
|
|
<code class="literal">Local(targets)</code>
|
|
, </span><span class="term">
|
|
<code class="literal">env.Local(targets)</code>
|
|
</span></dt><dd><p>
|
|
The specified
|
|
<code class="varname">targets</code>
|
|
will have copies made in the local tree,
|
|
even if an already up-to-date copy
|
|
exists in a repository.
|
|
Returns a list of the target Node or Nodes.
|
|
</p></dd><dt><a name="f-MergeFlags"></a><span class="term">
|
|
<code class="literal">env.MergeFlags(arg, [unique])</code>
|
|
</span></dt><dd><p>
|
|
Merges the specified
|
|
<code class="varname">arg</code>
|
|
values to the construction environment's construction variables.
|
|
If the
|
|
<code class="varname">arg</code>
|
|
argument is not a dictionary,
|
|
it is converted to one by calling
|
|
<a class="link" href="#f-ParseFlags"><code class="function">env.ParseFlags</code></a>
|
|
on the argument
|
|
before the values are merged.
|
|
Note that
|
|
<code class="varname">arg</code>
|
|
must be a single value,
|
|
so multiple strings must
|
|
be passed in as a list,
|
|
not as separate arguments to
|
|
<code class="function">env.MergeFlags</code>.
|
|
</p><p>
|
|
By default,
|
|
duplicate values are eliminated;
|
|
you can, however, specify
|
|
<code class="literal">unique=0</code>
|
|
to allow duplicate
|
|
values to be added.
|
|
When eliminating duplicate values,
|
|
any construction variables that end with
|
|
the string
|
|
<code class="literal">PATH</code>
|
|
keep the left-most unique value.
|
|
All other construction variables keep
|
|
the right-most unique value.
|
|
</p><p>
|
|
Examples:
|
|
</p><pre class="screen">
|
|
# Add an optimization flag to $CCFLAGS.
|
|
env.MergeFlags('-O3')
|
|
|
|
# Combine the flags returned from running pkg-config with an optimization
|
|
# flag and merge the result into the construction variables.
|
|
env.MergeFlags(['!pkg-config gtk+-2.0 --cflags', '-O3'])
|
|
|
|
# Combine an optimization flag with the flags returned from running pkg-config
|
|
# twice and merge the result into the construction variables.
|
|
env.MergeFlags(['-O3',
|
|
'!pkg-config gtk+-2.0 --cflags --libs',
|
|
'!pkg-config libpng12 --cflags --libs'])
|
|
</pre></dd><dt><a name="f-NoCache"></a><span class="term">
|
|
<code class="literal">NoCache(target, ...)</code>
|
|
, </span><span class="term">
|
|
<code class="literal">env.NoCache(target, ...)</code>
|
|
</span></dt><dd><p>
|
|
Specifies a list of files which should
|
|
<span class="emphasis"><em>not</em></span>
|
|
be cached whenever the
|
|
<a class="link" href="#f-CacheDir"><code class="function">CacheDir</code></a>
|
|
method has been activated.
|
|
The specified targets may be a list
|
|
or an individual target.
|
|
</p><p>
|
|
Multiple files should be specified
|
|
either as separate arguments to the
|
|
<code class="function">NoCache</code>
|
|
method, or as a list.
|
|
<code class="function">NoCache</code>
|
|
will also accept the return value of any of the construction environment
|
|
Builder methods.
|
|
</p><p>
|
|
Calling
|
|
<code class="function">NoCache</code>
|
|
on directories and other non-File Node types has no effect because
|
|
only File Nodes are cached.
|
|
</p><p>
|
|
Examples:
|
|
</p><pre class="screen">
|
|
NoCache('foo.elf')
|
|
NoCache(env.Program('hello', 'hello.c'))
|
|
</pre></dd><dt><a name="f-NoClean"></a><span class="term">
|
|
<code class="literal">NoClean(target, ...)</code>
|
|
, </span><span class="term">
|
|
<code class="literal">env.NoClean(target, ...)</code>
|
|
</span></dt><dd><p>
|
|
Specifies a list of files or directories which should
|
|
<span class="emphasis"><em>not</em></span>
|
|
be removed whenever the targets (or their dependencies)
|
|
are specified with the
|
|
<code class="option">-c</code>
|
|
command line option.
|
|
The specified targets may be a list
|
|
or an individual target.
|
|
Multiple calls to
|
|
<code class="function">NoClean</code>
|
|
are legal,
|
|
and prevent each specified target
|
|
from being removed by calls to the
|
|
<code class="option">-c</code>
|
|
option.
|
|
</p><p>
|
|
Multiple files or directories should be specified
|
|
either as separate arguments to the
|
|
<code class="function">NoClean</code>
|
|
method, or as a list.
|
|
<code class="function">NoClean</code>
|
|
will also accept the return value of any of the construction environment
|
|
Builder methods.
|
|
</p><p>
|
|
Calling
|
|
<code class="function">NoClean</code>
|
|
for a target overrides calling
|
|
<a class="link" href="#f-Clean"><code class="function">Clean</code></a>
|
|
for the same target,
|
|
and any targets passed to both functions will
|
|
<span class="emphasis"><em>not</em></span>
|
|
be removed by the
|
|
<code class="option">-c</code>
|
|
option.
|
|
</p><p>
|
|
Examples:
|
|
</p><pre class="screen">
|
|
NoClean('foo.elf')
|
|
NoClean(env.Program('hello', 'hello.c'))
|
|
</pre></dd><dt><a name="f-ParseConfig"></a><span class="term">
|
|
<code class="literal">env.ParseConfig(command, [function, unique])</code>
|
|
</span></dt><dd><p>
|
|
Calls the specified
|
|
<code class="varname">function</code>
|
|
to modify the environment as specified by the output of
|
|
<code class="varname">command</code>.
|
|
The default
|
|
<code class="varname">function</code>
|
|
is
|
|
<a class="link" href="#f-MergeFlags"><code class="function">env.MergeFlags</code></a>,
|
|
which expects the output of a typical
|
|
<span class="application">*-config</span>
|
|
command
|
|
(for example,
|
|
<span class="application">gtk-config</span>)
|
|
and adds the options
|
|
to the appropriate construction variables.
|
|
By default,
|
|
duplicate values are not
|
|
added to any construction variables;
|
|
you can specify
|
|
<code class="literal">unique=0</code>
|
|
to allow duplicate
|
|
values to be added.
|
|
</p><p>
|
|
Interpreted options
|
|
and the construction variables they affect
|
|
are as specified for the
|
|
<a class="link" href="#f-ParseFlags"><code class="function">env.ParseFlags</code></a>
|
|
method (which this method calls).
|
|
See that method's description, below,
|
|
for a table of options and construction variables.
|
|
</p></dd><dt><a name="f-ParseDepends"></a><span class="term">
|
|
<code class="literal">ParseDepends(filename, [must_exist, only_one])</code>
|
|
, </span><span class="term">
|
|
<code class="literal">env.ParseDepends(filename, [must_exist, only_one])</code>
|
|
</span></dt><dd><p>
|
|
Parses the contents of the specified
|
|
<code class="varname">filename</code>
|
|
as a list of dependencies in the style of
|
|
<span class="application">Make</span>
|
|
or
|
|
<span class="application">mkdep</span>,
|
|
and explicitly establishes all of the listed dependencies.
|
|
</p><p>
|
|
By default,
|
|
it is not an error
|
|
if the specified
|
|
<code class="varname">filename</code>
|
|
does not exist.
|
|
The optional
|
|
<code class="varname">must_exist</code>
|
|
argument may be set to a non-zero
|
|
value to have
|
|
scons
|
|
throw an exception and
|
|
generate an error if the file does not exist,
|
|
or is otherwise inaccessible.
|
|
</p><p>
|
|
The optional
|
|
<code class="varname">only_one</code>
|
|
argument may be set to a non-zero
|
|
value to have
|
|
scons
|
|
thrown an exception and
|
|
generate an error
|
|
if the file contains dependency
|
|
information for more than one target.
|
|
This can provide a small sanity check
|
|
for files intended to be generated
|
|
by, for example, the
|
|
<code class="literal">gcc -M</code>
|
|
flag,
|
|
which should typically only
|
|
write dependency information for
|
|
one output file into a corresponding
|
|
<code class="filename">.d</code>
|
|
file.
|
|
</p><p>
|
|
The
|
|
<code class="varname">filename</code>
|
|
and all of the files listed therein
|
|
will be interpreted relative to
|
|
the directory of the
|
|
<code class="filename">SConscript</code>
|
|
file which calls the
|
|
<code class="function">ParseDepends</code>
|
|
function.
|
|
</p></dd><dt><a name="f-ParseFlags"></a><span class="term">
|
|
<code class="literal">env.ParseFlags(flags, ...)</code>
|
|
</span></dt><dd><p>
|
|
Parses one or more strings containing
|
|
typical command-line flags for GCC tool chains
|
|
and returns a dictionary with the flag values
|
|
separated into the appropriate SCons construction variables.
|
|
This is intended as a companion to the
|
|
<a class="link" href="#f-MergeFlags"><code class="function">env.MergeFlags</code></a>
|
|
method, but allows for the values in the returned dictionary
|
|
to be modified, if necessary,
|
|
before merging them into the construction environment.
|
|
(Note that
|
|
<code class="function">env.MergeFlags</code>
|
|
will call this method if its argument is not a dictionary,
|
|
so it is usually not necessary to call
|
|
<a class="link" href="#f-ParseFlags"><code class="function">env.ParseFlags</code></a>
|
|
directly unless you want to manipulate the values.)
|
|
</p><p>
|
|
If the first character in any string is
|
|
an exclamation mark (!),
|
|
the rest of the string is executed as a command,
|
|
and the output from the command is
|
|
parsed as GCC tool chain command-line flags
|
|
and added to the resulting dictionary.
|
|
</p><p>
|
|
Flag values are translated accordig to the prefix found,
|
|
and added to the following construction variables:
|
|
</p><pre class="screen">
|
|
-arch CCFLAGS, LINKFLAGS
|
|
-D CPPDEFINES
|
|
-framework FRAMEWORKS
|
|
-frameworkdir= FRAMEWORKPATH
|
|
-include CCFLAGS
|
|
-isysroot CCFLAGS, LINKFLAGS
|
|
-I CPPPATH
|
|
-l LIBS
|
|
-L LIBPATH
|
|
-mno-cygwin CCFLAGS, LINKFLAGS
|
|
-mwindows LINKFLAGS
|
|
-pthread CCFLAGS, LINKFLAGS
|
|
-std= CFLAGS
|
|
-Wa, ASFLAGS, CCFLAGS
|
|
-Wl,-rpath= RPATH
|
|
-Wl,-R, RPATH
|
|
-Wl,-R RPATH
|
|
-Wl, LINKFLAGS
|
|
-Wp, CPPFLAGS
|
|
- CCFLAGS
|
|
+ CCFLAGS, LINKFLAGS
|
|
</pre><p>
|
|
Any other strings not associated with options
|
|
are assumed to be the names of libraries
|
|
and added to the
|
|
<code class="envar">$LIBS</code>
|
|
construction variable.
|
|
</p><p>
|
|
Examples (all of which produce the same result):
|
|
</p><pre class="screen">
|
|
dict = env.ParseFlags('-O2 -Dfoo -Dbar=1')
|
|
dict = env.ParseFlags('-O2', '-Dfoo', '-Dbar=1')
|
|
dict = env.ParseFlags(['-O2', '-Dfoo -Dbar=1'])
|
|
dict = env.ParseFlags('-O2', '!echo -Dfoo -Dbar=1')
|
|
</pre></dd><dt><a name="f-Platform"></a><span class="term">
|
|
<code class="literal">Platform(string)</code>
|
|
</span></dt><dd><p>
|
|
The
|
|
<code class="function">Platform</code>
|
|
form returns a callable object
|
|
that can be used to initialize
|
|
a construction environment using the
|
|
platform keyword of the
|
|
<code class="function">Environment</code>
|
|
function.
|
|
</p><p>
|
|
Example:
|
|
</p><pre class="screen">
|
|
env = Environment(platform = Platform('win32'))
|
|
</pre><p>
|
|
The
|
|
<code class="function">env.Platform</code>
|
|
form applies the callable object for the specified platform
|
|
<code class="varname">string</code>
|
|
to the environment through which the method was called.
|
|
</p><pre class="screen">
|
|
env.Platform('posix')
|
|
</pre><p>
|
|
Note that the
|
|
<code class="literal">win32</code>
|
|
platform adds the
|
|
<code class="literal">SystemDrive</code>
|
|
and
|
|
<code class="literal">SystemRoot</code>
|
|
variables from the user's external environment
|
|
to the construction environment's
|
|
<a class="link" href="#cv-ENV"><code class="envar">$ENV</code></a>
|
|
dictionary.
|
|
This is so that any executed commands
|
|
that use sockets to connect with other systems
|
|
(such as fetching source files from
|
|
external CVS repository specifications like
|
|
<code class="literal">:pserver:anonymous@cvs.sourceforge.net:/cvsroot/scons</code>)
|
|
will work on Windows systems.
|
|
</p></dd><dt><a name="f-Precious"></a><span class="term">
|
|
<code class="literal">Precious(target, ...)</code>
|
|
, </span><span class="term">
|
|
<code class="literal">env.Precious(target, ...)</code>
|
|
</span></dt><dd><p>
|
|
Marks each given
|
|
<code class="varname">target</code>
|
|
as precious so it is not deleted before it is rebuilt. Normally
|
|
<code class="filename">scons</code>
|
|
deletes a target before building it.
|
|
Multiple targets can be passed in to a single call to
|
|
<code class="function">Precious</code>.
|
|
</p></dd><dt><a name="f-Prepend"></a><span class="term">
|
|
<code class="literal">env.Prepend(key=val, [...])</code>
|
|
</span></dt><dd><p>
|
|
Appends the specified keyword arguments
|
|
to the beginning of construction variables in the environment.
|
|
If the Environment does not have
|
|
the specified construction variable,
|
|
it is simply added to the environment.
|
|
If the values of the construction variable
|
|
and the keyword argument are the same type,
|
|
then the two values will be simply added together.
|
|
Otherwise, the construction variable
|
|
and the value of the keyword argument
|
|
are both coerced to lists,
|
|
and the lists are added together.
|
|
(See also the Append method, above.)
|
|
</p><p>
|
|
Example:
|
|
</p><pre class="screen">
|
|
env.Prepend(CCFLAGS = '-g ', FOO = ['foo.yyy'])
|
|
</pre></dd><dt><a name="f-PrependENVPath"></a><span class="term">
|
|
<code class="literal">env.PrependENVPath(name, newpath, [envname, sep, delete_existing])</code>
|
|
</span></dt><dd><p>
|
|
This appends new path elements to the given path in the
|
|
specified external environment
|
|
(<code class="envar">$ENV</code>
|
|
by default).
|
|
This will only add
|
|
any particular path once (leaving the first one it encounters and
|
|
ignoring the rest, to preserve path order),
|
|
and to help assure this,
|
|
will normalize all paths (using
|
|
<code class="literal">os.path.normpath</code>
|
|
and
|
|
<code class="literal">os.path.normcase</code>).
|
|
This can also handle the
|
|
case where the given old path variable is a list instead of a
|
|
string, in which case a list will be returned instead of a string.
|
|
</p><p>
|
|
If
|
|
<code class="varname">delete_existing</code>
|
|
is 0, then adding a path that already exists
|
|
will not move it to the beginning;
|
|
it will stay where it is in the list.
|
|
</p><p>
|
|
Example:
|
|
</p><pre class="screen">
|
|
print 'before:',env['ENV']['INCLUDE']
|
|
include_path = '/foo/bar:/foo'
|
|
env.PrependENVPath('INCLUDE', include_path)
|
|
print 'after:',env['ENV']['INCLUDE']
|
|
</pre><p>
|
|
The above example will print:
|
|
</p><pre class="screen">
|
|
before: /biz:/foo
|
|
after: /foo/bar:/foo:/biz
|
|
</pre></dd><dt><a name="f-PrependUnique"></a><span class="term">
|
|
<code class="literal">env.PrependUnique(key=val, delete_existing=0, [...])</code>
|
|
</span></dt><dd><p>
|
|
Appends the specified keyword arguments
|
|
to the beginning of construction variables in the environment.
|
|
If the Environment does not have
|
|
the specified construction variable,
|
|
it is simply added to the environment.
|
|
If the construction variable being appended to is a list,
|
|
then any value(s) that already exist in the
|
|
construction variable will
|
|
<span class="emphasis"><em>not</em></span>
|
|
be added again to the list.
|
|
However, if delete_existing is 1,
|
|
existing matching values are removed first, so
|
|
existing values in the arg list move to the front of the list.
|
|
</p><p>
|
|
Example:
|
|
</p><pre class="screen">
|
|
env.PrependUnique(CCFLAGS = '-g', FOO = ['foo.yyy'])
|
|
</pre></dd><dt><a name="f-Progress"></a><span class="term">
|
|
<code class="literal">Progress(callable, [interval])</code>
|
|
, </span><span class="term">
|
|
<code class="literal">Progress(string, [interval, file, overwrite])</code>
|
|
, </span><span class="term">
|
|
<code class="literal">Progress(list_of_strings, [interval, file, overwrite])</code>
|
|
</span></dt><dd><p>
|
|
Allows SCons to show progress made during the build
|
|
by displaying a string or calling a function while
|
|
evaluating Nodes (e.g. files).
|
|
</p><p>
|
|
If the first specified argument is a Python callable
|
|
(a function or an object that has a
|
|
<code class="function">__call__</code>()
|
|
method),
|
|
the function will be called
|
|
once every
|
|
<code class="varname">interval</code>
|
|
times a Node is evaluated.
|
|
The callable will be passed the evaluated Node
|
|
as its only argument.
|
|
(For future compatibility,
|
|
it's a good idea to also add
|
|
<code class="literal">*args</code>
|
|
and
|
|
<code class="literal">**kw</code>
|
|
as arguments to your function or method.
|
|
This will prevent the code from breaking
|
|
if SCons ever changes the interface
|
|
to call the function with additional arguments in the future.)
|
|
</p><p>
|
|
An example of a simple custom progress function
|
|
that prints a string containing the Node name
|
|
every 10 Nodes:
|
|
</p><pre class="screen">
|
|
def my_progress_function(node, *args, **kw):
|
|
print('Evaluating node %s!' % node)
|
|
Progress(my_progress_function, interval=10)
|
|
</pre><p>
|
|
A more complicated example of a custom progress display object
|
|
that prints a string containing a count
|
|
every 100 evaluated Nodes.
|
|
Note the use of
|
|
<code class="literal">\r</code>
|
|
(a carriage return)
|
|
at the end so that the string
|
|
will overwrite itself on a display:
|
|
</p><pre class="screen">
|
|
import sys
|
|
class ProgressCounter(object):
|
|
count = 0
|
|
def __call__(self, node, *args, **kw):
|
|
self.count += 100
|
|
sys.stderr.write('Evaluated %s nodes\r' % self.count)
|
|
Progress(ProgressCounter(), interval=100)
|
|
</pre><p>
|
|
If the first argument
|
|
<a class="link" href="#f-Progress"><code class="function">Progress</code></a>
|
|
is a string,
|
|
the string will be displayed
|
|
every
|
|
<code class="varname">interval</code>
|
|
evaluated Nodes.
|
|
The default is to print the string on standard output;
|
|
an alternate output stream
|
|
may be specified with the
|
|
<code class="literal">file=</code>
|
|
argument.
|
|
The following will print a series of dots
|
|
on the error output,
|
|
one dot for every 100 evaluated Nodes:
|
|
</p><pre class="screen">
|
|
import sys
|
|
Progress('.', interval=100, file=sys.stderr)
|
|
</pre><p>
|
|
If the string contains the verbatim substring
|
|
<code class="envar">$TARGET</code>,
|
|
it will be replaced with the Node.
|
|
Note that, for performance reasons, this is
|
|
<span class="emphasis"><em>not</em></span>
|
|
a regular SCons variable substition,
|
|
so you can not use other variables
|
|
or use curly braces.
|
|
The following example will print the name of
|
|
every evaluated Node,
|
|
using a
|
|
<code class="literal">\r</code>
|
|
(carriage return) to cause each line to overwritten by the next line,
|
|
and the
|
|
<code class="literal">overwrite=</code>
|
|
keyword argument to make sure the previously-printed
|
|
file name is overwritten with blank spaces:
|
|
</p><pre class="screen">
|
|
import sys
|
|
Progress('$TARGET\r', overwrite=True)
|
|
</pre><p>
|
|
If the first argument to
|
|
<code class="function">Progress</code>
|
|
is a list of strings,
|
|
then each string in the list will be displayed
|
|
in rotating fashion every
|
|
<code class="varname">interval</code>
|
|
evaluated Nodes.
|
|
This can be used to implement a "spinner"
|
|
on the user's screen as follows:
|
|
</p><pre class="screen">
|
|
Progress(['-\r', '\\\r', '|\r', '/\r'], interval=5)
|
|
</pre></dd><dt><a name="f-Pseudo"></a><span class="term">
|
|
<code class="literal">Pseudo(target, ...)</code>
|
|
, </span><span class="term">
|
|
<code class="literal">env.Pseudo(target, ...)</code>
|
|
</span></dt><dd><p>
|
|
This indicates that each given
|
|
<code class="varname">target</code>
|
|
should not be created by the build rule, and if the target is created,
|
|
an error will be generated. This is similar to the gnu make .PHONY
|
|
target. However, in the vast majority of cases, an
|
|
<code class="function">Alias</code>
|
|
is more appropriate.
|
|
|
|
Multiple targets can be passed in to a single call to
|
|
<code class="function">Pseudo</code>.
|
|
</p></dd><dt><a name="f-PyPackageDir"></a><span class="term">
|
|
<code class="literal">PyPackageDir(modulename)</code>
|
|
, </span><span class="term">
|
|
<code class="literal">env.PyPackageDir(modulename)</code>
|
|
</span></dt><dd><p>
|
|
This returns a Directory Node similar to Dir.
|
|
The python module / package is looked up and if located
|
|
the directory is returned for the location.
|
|
<code class="varname">modulename</code>
|
|
Is a named python package / module to
|
|
lookup the directory for it's location.
|
|
</p><p>
|
|
If
|
|
<code class="varname">modulename</code>
|
|
is a list, SCons returns a list of Dir nodes.
|
|
Construction variables are expanded in
|
|
<code class="varname">modulename</code>.
|
|
</p></dd><dt><a name="f-Replace"></a><span class="term">
|
|
<code class="literal">env.Replace(key=val, [...])</code>
|
|
</span></dt><dd><p>
|
|
Replaces construction variables in the Environment
|
|
with the specified keyword arguments.
|
|
</p><p>
|
|
Example:
|
|
</p><pre class="screen">
|
|
env.Replace(CCFLAGS = '-g', FOO = 'foo.xxx')
|
|
</pre></dd><dt><a name="f-Repository"></a><span class="term">
|
|
<code class="literal">Repository(directory)</code>
|
|
, </span><span class="term">
|
|
<code class="literal">env.Repository(directory)</code>
|
|
</span></dt><dd><p>
|
|
Specifies that
|
|
<code class="varname">directory</code>
|
|
is a repository to be searched for files.
|
|
Multiple calls to
|
|
<code class="function">Repository</code>
|
|
are legal,
|
|
and each one adds to the list of
|
|
repositories that will be searched.
|
|
</p><p>
|
|
To
|
|
<code class="filename">scons</code>,
|
|
a repository is a copy of the source tree,
|
|
from the top-level directory on down,
|
|
which may contain
|
|
both source files and derived files
|
|
that can be used to build targets in
|
|
the local source tree.
|
|
The canonical example would be an
|
|
official source tree maintained by an integrator.
|
|
If the repository contains derived files,
|
|
then the derived files should have been built using
|
|
<code class="filename">scons</code>,
|
|
so that the repository contains the necessary
|
|
signature information to allow
|
|
<code class="filename">scons</code>
|
|
to figure out when it is appropriate to
|
|
use the repository copy of a derived file,
|
|
instead of building one locally.
|
|
</p><p>
|
|
Note that if an up-to-date derived file
|
|
already exists in a repository,
|
|
<code class="filename">scons</code>
|
|
will
|
|
<span class="emphasis"><em>not</em></span>
|
|
make a copy in the local directory tree.
|
|
In order to guarantee that a local copy
|
|
will be made,
|
|
use the
|
|
<a class="link" href="#f-Local"><code class="function">Local</code></a>
|
|
method.
|
|
</p></dd><dt><a name="f-Requires"></a><span class="term">
|
|
<code class="literal">Requires(target, prerequisite)</code>
|
|
, </span><span class="term">
|
|
<code class="literal">env.Requires(target, prerequisite)</code>
|
|
</span></dt><dd><p>
|
|
Specifies an order-only relationship
|
|
between the specified target file(s)
|
|
and the specified prerequisite file(s).
|
|
The prerequisite file(s)
|
|
will be (re)built, if necessary,
|
|
<span class="emphasis"><em>before</em></span>
|
|
the target file(s),
|
|
but the target file(s) do not actually
|
|
depend on the prerequisites
|
|
and will not be rebuilt simply because
|
|
the prerequisite file(s) change.
|
|
</p><p>
|
|
Example:
|
|
</p><pre class="screen">
|
|
env.Requires('foo', 'file-that-must-be-built-before-foo')
|
|
</pre></dd><dt><a name="f-Return"></a><span class="term">
|
|
<code class="literal">Return([vars..., stop=])</code>
|
|
</span></dt><dd><p>
|
|
By default,
|
|
this stops processing the current SConscript
|
|
file and returns to the calling SConscript file
|
|
the values of the variables named in the
|
|
<code class="varname">vars</code>
|
|
string arguments.
|
|
Multiple strings contaning variable names may be passed to
|
|
<code class="function">Return</code>.
|
|
Any strings that contain white space
|
|
</p><p>
|
|
The optional
|
|
<code class="literal">stop=</code>
|
|
keyword argument may be set to a false value
|
|
to continue processing the rest of the SConscript
|
|
file after the
|
|
<code class="function">Return</code>
|
|
call.
|
|
This was the default behavior prior to SCons 0.98.
|
|
However, the values returned
|
|
are still the values of the variables in the named
|
|
<code class="varname">vars</code>
|
|
at the point
|
|
<code class="function">Return</code>
|
|
is called.
|
|
</p><p>
|
|
Examples:
|
|
</p><pre class="screen">
|
|
# Returns without returning a value.
|
|
Return()
|
|
|
|
# Returns the value of the 'foo' Python variable.
|
|
Return("foo")
|
|
|
|
# Returns the values of the Python variables 'foo' and 'bar'.
|
|
Return("foo", "bar")
|
|
|
|
# Returns the values of Python variables 'val1' and 'val2'.
|
|
Return('val1 val2')
|
|
</pre></dd><dt><a name="f-Scanner"></a><span class="term">
|
|
<code class="literal">Scanner(function, [argument, keys, path_function, node_class, node_factory, scan_check, recursive])</code>
|
|
, </span><span class="term">
|
|
<code class="literal">env.Scanner(function, [argument, keys, path_function, node_class, node_factory, scan_check, recursive])</code>
|
|
</span></dt><dd><p>
|
|
Creates a Scanner object for
|
|
the specified
|
|
<code class="varname">function</code>.
|
|
See the section "Scanner Objects,"
|
|
below, for a complete explanation of the arguments and behavior.
|
|
</p></dd><dt><a name="f-SConscript"></a><span class="term">
|
|
<code class="literal">SConscript(scripts, [exports, variant_dir, duplicate, must_exist])</code>
|
|
, </span><span class="term">
|
|
<code class="literal">env.SConscript(scripts, [exports, variant_dir, duplicate, must_exist])</code>
|
|
, </span><span class="term">
|
|
<code class="literal">SConscript(dirs=subdirs, [name=script, exports, variant_dir, duplicate, must_exist])</code>
|
|
, </span><span class="term">
|
|
<code class="literal">env.SConscript(dirs=subdirs, [name=script, exports, variant_dir, duplicate, must_exist])</code>
|
|
</span></dt><dd><p>
|
|
This tells
|
|
<code class="filename">scons</code>
|
|
to execute
|
|
one or more subsidiary SConscript (configuration) files.
|
|
Any variables returned by a called script using
|
|
<a class="link" href="#f-Return"><code class="function">Return</code></a>
|
|
will be returned by the call to
|
|
<code class="function">SConscript</code>.
|
|
There are two ways to call the
|
|
<code class="function">SConscript</code>
|
|
function.
|
|
</p><p>
|
|
The first way you can call
|
|
<code class="function">SConscript</code>
|
|
is to explicitly specify one or more
|
|
<code class="varname">scripts</code>
|
|
as the first argument.
|
|
A single script may be specified as a string;
|
|
multiple scripts must be specified as a list
|
|
(either explicitly or as created by
|
|
a function like
|
|
<code class="function">Split</code>).
|
|
Examples:
|
|
</p><pre class="screen">
|
|
SConscript('SConscript') # run SConscript in the current directory
|
|
SConscript('src/SConscript') # run SConscript in the src directory
|
|
SConscript(['src/SConscript', 'doc/SConscript'])
|
|
config = SConscript('MyConfig.py')
|
|
</pre><p>
|
|
The second way you can call
|
|
<code class="function">SConscript</code>
|
|
is to specify a list of (sub)directory names
|
|
as a
|
|
<code class="literal">dirs=</code><code class="varname">subdirs</code>
|
|
keyword argument.
|
|
In this case,
|
|
<code class="filename">scons</code>
|
|
will, by default,
|
|
execute a subsidiary configuration file named
|
|
<code class="filename">SConscript</code>
|
|
in each of the specified directories.
|
|
You may specify a name other than
|
|
<code class="filename">SConscript</code>
|
|
by supplying an optional
|
|
<code class="literal">name=</code><code class="varname">script</code>
|
|
keyword argument.
|
|
The first three examples below have the same effect
|
|
as the first three examples above:
|
|
</p><pre class="screen">
|
|
SConscript(dirs='.') # run SConscript in the current directory
|
|
SConscript(dirs='src') # run SConscript in the src directory
|
|
SConscript(dirs=['src', 'doc'])
|
|
SConscript(dirs=['sub1', 'sub2'], name='MySConscript')
|
|
</pre><p>
|
|
The optional
|
|
<code class="varname">exports</code>
|
|
argument provides a list of variable names or a dictionary of
|
|
named values to export to the
|
|
<code class="varname">script(s)</code>.
|
|
These variables are locally exported only to the specified
|
|
<code class="varname">script(s)</code>,
|
|
and do not affect the global pool of variables used by the
|
|
<code class="function">Export</code>
|
|
function.
|
|
|
|
The subsidiary
|
|
<code class="varname">script(s)</code>
|
|
must use the
|
|
<a class="link" href="#f-Import"><code class="function">Import</code></a>
|
|
function to import the variables.
|
|
Examples:
|
|
</p><pre class="screen">
|
|
foo = SConscript('sub/SConscript', exports='env')
|
|
SConscript('dir/SConscript', exports=['env', 'variable'])
|
|
SConscript(dirs='subdir', exports='env variable')
|
|
SConscript(dirs=['one', 'two', 'three'], exports='shared_info')
|
|
</pre><p>
|
|
If the optional
|
|
<code class="varname">variant_dir</code>
|
|
argument is present, it causes an effect equivalent to the
|
|
<a class="link" href="#f-VariantDir"><code class="function">VariantDir</code></a>
|
|
method described below.
|
|
(If
|
|
<code class="varname">variant_dir</code>
|
|
is not present, the
|
|
|
|
<code class="varname">duplicate</code>
|
|
|
|
argument is ignored.)
|
|
The
|
|
<code class="varname">variant_dir</code>
|
|
|
|
argument is interpreted relative to the directory of the calling
|
|
<code class="filename">SConscript</code>
|
|
file.
|
|
See the description of the
|
|
<code class="function">VariantDir</code>
|
|
function below for additional details and restrictions.
|
|
</p><p>
|
|
If
|
|
<code class="varname">variant_dir</code>
|
|
is present,
|
|
|
|
the source directory is the directory in which the
|
|
<code class="filename">SConscript</code>
|
|
file resides and the
|
|
<code class="filename">SConscript</code>
|
|
file is evaluated as if it were in the
|
|
<code class="varname">variant_dir</code>
|
|
directory:
|
|
</p><pre class="screen">
|
|
SConscript('src/SConscript', variant_dir = 'build')
|
|
</pre><p>
|
|
is equivalent to
|
|
</p><pre class="screen">
|
|
VariantDir('build', 'src')
|
|
SConscript('build/SConscript')
|
|
</pre><p>
|
|
This later paradigm is often used when the sources are
|
|
in the same directory as the
|
|
<code class="filename">SConstruct</code>:
|
|
</p><pre class="screen">
|
|
SConscript('SConscript', variant_dir = 'build')
|
|
</pre><p>
|
|
is equivalent to
|
|
</p><pre class="screen">
|
|
VariantDir('build', '.')
|
|
SConscript('build/SConscript')
|
|
</pre><p>
|
|
|
|
</p><p>
|
|
The optional
|
|
<code class="varname">must_exist</code>
|
|
argument, if true, causes an exception to be raised if a requested
|
|
<code class="filename">SConscript</code> file is not found. The current default is false,
|
|
causing only a warning to be omitted, but this behavior is deprecated.
|
|
For scripts which truly intend to be optional, transition to
|
|
explicty supplying
|
|
<code class="literal">must_exist=False</code> to the call.
|
|
</p><p>
|
|
Here are some composite examples:
|
|
</p><pre class="screen">
|
|
# collect the configuration information and use it to build src and doc
|
|
shared_info = SConscript('MyConfig.py')
|
|
SConscript('src/SConscript', exports='shared_info')
|
|
SConscript('doc/SConscript', exports='shared_info')
|
|
</pre><pre class="screen">
|
|
# build debugging and production versions. SConscript
|
|
# can use Dir('.').path to determine variant.
|
|
SConscript('SConscript', variant_dir='debug', duplicate=0)
|
|
SConscript('SConscript', variant_dir='prod', duplicate=0)
|
|
</pre><pre class="screen">
|
|
# build debugging and production versions. SConscript
|
|
# is passed flags to use.
|
|
opts = { 'CPPDEFINES' : ['DEBUG'], 'CCFLAGS' : '-pgdb' }
|
|
SConscript('SConscript', variant_dir='debug', duplicate=0, exports=opts)
|
|
opts = { 'CPPDEFINES' : ['NODEBUG'], 'CCFLAGS' : '-O' }
|
|
SConscript('SConscript', variant_dir='prod', duplicate=0, exports=opts)
|
|
</pre><pre class="screen">
|
|
# build common documentation and compile for different architectures
|
|
SConscript('doc/SConscript', variant_dir='build/doc', duplicate=0)
|
|
SConscript('src/SConscript', variant_dir='build/x86', duplicate=0)
|
|
SConscript('src/SConscript', variant_dir='build/ppc', duplicate=0)
|
|
</pre></dd><dt><a name="f-SConscriptChdir"></a><span class="term">
|
|
<code class="literal">SConscriptChdir(value)</code>
|
|
, </span><span class="term">
|
|
<code class="literal">env.SConscriptChdir(value)</code>
|
|
</span></dt><dd><p>
|
|
By default,
|
|
<code class="filename">scons</code>
|
|
changes its working directory
|
|
to the directory in which each
|
|
subsidiary SConscript file lives.
|
|
This behavior may be disabled
|
|
by specifying either:
|
|
</p><pre class="screen">
|
|
SConscriptChdir(0)
|
|
env.SConscriptChdir(0)
|
|
</pre><p>
|
|
in which case
|
|
<code class="filename">scons</code>
|
|
will stay in the top-level directory
|
|
while reading all SConscript files.
|
|
(This may be necessary when building from repositories,
|
|
when all the directories in which SConscript files may be found
|
|
don't necessarily exist locally.)
|
|
You may enable and disable
|
|
this ability by calling
|
|
SConscriptChdir()
|
|
multiple times.
|
|
</p><p>
|
|
Example:
|
|
</p><pre class="screen">
|
|
env = Environment()
|
|
SConscriptChdir(0)
|
|
SConscript('foo/SConscript') # will not chdir to foo
|
|
env.SConscriptChdir(1)
|
|
SConscript('bar/SConscript') # will chdir to bar
|
|
</pre></dd><dt><a name="f-SConsignFile"></a><span class="term">
|
|
<code class="literal">SConsignFile([file, dbm_module])</code>
|
|
, </span><span class="term">
|
|
<code class="literal">env.SConsignFile([file, dbm_module])</code>
|
|
</span></dt><dd><p>
|
|
This tells
|
|
<code class="filename">scons</code>
|
|
to store all file signatures
|
|
in the specified database
|
|
<code class="varname">file</code>.
|
|
If the
|
|
<code class="varname">file</code>
|
|
name is omitted,
|
|
<code class="filename">.sconsign</code>
|
|
is used by default.
|
|
(The actual file name(s) stored on disk
|
|
may have an appropriated suffix appended
|
|
by the
|
|
<code class="varname"> dbm_module</code>.)
|
|
If
|
|
<code class="varname">file</code>
|
|
is not an absolute path name,
|
|
the file is placed in the same directory as the top-level
|
|
<code class="filename">SConstruct</code>
|
|
file.
|
|
</p><p>
|
|
If
|
|
<code class="varname">file</code>
|
|
is
|
|
<code class="literal">None</code>,
|
|
then
|
|
<code class="filename">scons</code>
|
|
will store file signatures
|
|
in a separate
|
|
<code class="filename">.sconsign</code>
|
|
file in each directory,
|
|
not in one global database file.
|
|
(This was the default behavior
|
|
prior to SCons 0.96.91 and 0.97.)
|
|
</p><p>
|
|
The optional
|
|
<code class="varname">dbm_module</code>
|
|
argument can be used to specify
|
|
which Python database module
|
|
The default is to use a custom
|
|
<code class="filename">SCons.dblite</code>
|
|
module that uses pickled
|
|
Python data structures,
|
|
and which works on all Python versions.
|
|
</p><p>
|
|
Examples:
|
|
</p><pre class="screen">
|
|
# Explicitly stores signatures in ".sconsign.dblite"
|
|
# in the top-level SConstruct directory (the
|
|
# default behavior).
|
|
SConsignFile()
|
|
|
|
# Stores signatures in the file "etc/scons-signatures"
|
|
# relative to the top-level SConstruct directory.
|
|
SConsignFile("etc/scons-signatures")
|
|
|
|
# Stores signatures in the specified absolute file name.
|
|
SConsignFile("/home/me/SCons/signatures")
|
|
|
|
# Stores signatures in a separate .sconsign file
|
|
# in each directory.
|
|
SConsignFile(None)
|
|
</pre></dd><dt><a name="f-SetDefault"></a><span class="term">
|
|
<code class="literal">env.SetDefault(key=val, [...])</code>
|
|
</span></dt><dd><p>
|
|
Sets construction variables to default values specified with the keyword
|
|
arguments if (and only if) the variables are not already set.
|
|
The following statements are equivalent:
|
|
</p><pre class="screen">
|
|
env.SetDefault(FOO = 'foo')
|
|
|
|
if 'FOO' not in env: env['FOO'] = 'foo'
|
|
</pre></dd><dt><a name="f-SetOption"></a><span class="term">
|
|
<code class="literal">SetOption(name, value)</code>
|
|
, </span><span class="term">
|
|
<code class="literal">env.SetOption(name, value)</code>
|
|
</span></dt><dd><p>
|
|
This function provides a way to set a select subset of the scons command
|
|
line options from a SConscript file. The options supported are:
|
|
</p><p>
|
|
</p><div class="variablelist"><dl><dt><span class="term"><code class="literal">clean</code></span></dt><dd><p>
|
|
which corresponds to -c, --clean and --remove;
|
|
</p></dd><dt><span class="term"><code class="literal">duplicate</code></span></dt><dd><p>
|
|
which corresponds to --duplicate;
|
|
</p></dd><dt><span class="term"><code class="literal">help</code></span></dt><dd><p>
|
|
which corresponds to -h and --help;
|
|
</p></dd><dt><span class="term"><code class="literal">implicit_cache</code></span></dt><dd><p>
|
|
which corresponds to --implicit-cache;
|
|
</p></dd><dt><span class="term"><code class="literal">max_drift</code></span></dt><dd><p>
|
|
which corresponds to --max-drift;
|
|
</p></dd><dt><span class="term"><code class="literal">no_exec</code></span></dt><dd><p>
|
|
which corresponds to -n, --no-exec, --just-print, --dry-run and --recon;
|
|
</p></dd><dt><span class="term"><code class="literal">num_jobs</code></span></dt><dd><p>
|
|
which corresponds to -j and --jobs;
|
|
</p></dd><dt><span class="term"><code class="literal">random</code></span></dt><dd><p>
|
|
which corresponds to --random; and
|
|
</p></dd><dt><span class="term"><code class="literal">silent</code></span></dt><dd><p>
|
|
which corresponds to --silent.
|
|
</p></dd><dt><span class="term"><code class="literal">stack_size</code></span></dt><dd><p>
|
|
which corresponds to --stack-size.
|
|
</p></dd></dl></div><p>
|
|
</p><p>
|
|
See the documentation for the
|
|
corresponding command line object for information about each specific
|
|
option.
|
|
</p><p>
|
|
Example:
|
|
</p><pre class="screen">
|
|
SetOption('max_drift', 1)
|
|
</pre></dd><dt><a name="f-SideEffect"></a><span class="term">
|
|
<code class="literal">SideEffect(side_effect, target)</code>
|
|
, </span><span class="term">
|
|
<code class="literal">env.SideEffect(side_effect, target)</code>
|
|
</span></dt><dd><p>
|
|
Declares
|
|
<code class="varname">side_effect</code>
|
|
as a side effect of building
|
|
<code class="varname">target</code>.
|
|
Both
|
|
<code class="varname">side_effect</code>
|
|
and
|
|
<code class="varname">target</code>
|
|
can be a list, a file name, or a node.
|
|
A side effect is a target file that is created or updated
|
|
as a side effect of building other targets.
|
|
For example, a Windows PDB
|
|
file is created as a side effect of building the .obj
|
|
files for a static library,
|
|
and various log files are created updated
|
|
as side effects of various TeX commands.
|
|
If a target is a side effect of multiple build commands,
|
|
<code class="filename">scons</code>
|
|
will ensure that only one set of commands
|
|
is executed at a time.
|
|
Consequently, you only need to use this method
|
|
for side-effect targets that are built as a result of
|
|
multiple build commands.
|
|
</p><p>
|
|
Because multiple build commands may update
|
|
the same side effect file,
|
|
by default the
|
|
<code class="varname">side_effect</code>
|
|
target is
|
|
<span class="emphasis"><em>not</em></span>
|
|
automatically removed
|
|
when the
|
|
<code class="varname">target</code>
|
|
is removed by the
|
|
<code class="option">-c</code>
|
|
option.
|
|
(Note, however, that the
|
|
<code class="varname">side_effect</code>
|
|
might be removed as part of
|
|
cleaning the directory in which it lives.)
|
|
If you want to make sure the
|
|
<code class="varname">side_effect</code>
|
|
is cleaned whenever a specific
|
|
<code class="varname">target</code>
|
|
is cleaned,
|
|
you must specify this explicitly
|
|
with the
|
|
<a class="link" href="#f-Clean"><code class="function">Clean</code></a>
|
|
or
|
|
<code class="function">env.Clean</code>
|
|
function.
|
|
</p></dd><dt><a name="f-SourceCode"></a><span class="term">
|
|
<code class="literal">SourceCode(entries, builder)</code>
|
|
, </span><span class="term">
|
|
<code class="literal">env.SourceCode(entries, builder)</code>
|
|
</span></dt><dd><p>
|
|
This function and its associate factory functions are deprecated.
|
|
There is no replacement.
|
|
The intended use was to keep a local tree in sync with an archive,
|
|
but in actuality the function only causes the archive
|
|
to be fetched on the first run.
|
|
Synchronizing with the archive is best done external to <span class="application">SCons</span>.
|
|
</p><p>
|
|
Arrange for non-existent source files to
|
|
be fetched from a source code management system
|
|
using the specified
|
|
<code class="varname">builder</code>.
|
|
The specified
|
|
<code class="varname">entries</code>
|
|
may be a Node, string or list of both,
|
|
and may represent either individual
|
|
source files or directories in which
|
|
source files can be found.
|
|
</p><p>
|
|
For any non-existent source files,
|
|
<code class="filename">scons</code>
|
|
will search up the directory tree
|
|
and use the first
|
|
<code class="function">SourceCode</code>
|
|
builder it finds.
|
|
The specified
|
|
<code class="varname">builder</code>
|
|
may be
|
|
<code class="literal">None</code>,
|
|
in which case
|
|
<code class="filename">scons</code>
|
|
will not use a builder to fetch
|
|
source files for the specified
|
|
<code class="varname">entries</code>,
|
|
even if a
|
|
<code class="function">SourceCode</code>
|
|
builder has been specified
|
|
for a directory higher up the tree.
|
|
</p><p>
|
|
<code class="filename">scons</code>
|
|
will, by default,
|
|
fetch files from SCCS or RCS subdirectories
|
|
without explicit configuration.
|
|
This takes some extra processing time
|
|
to search for the necessary
|
|
source code management files on disk.
|
|
You can avoid these extra searches
|
|
and speed up your build a little
|
|
by disabling these searches as follows:
|
|
</p><pre class="screen">
|
|
env.SourceCode('.', None)
|
|
</pre><p>
|
|
Note that if the specified
|
|
<code class="varname">builder</code>
|
|
is one you create by hand,
|
|
it must have an associated
|
|
construction environment to use
|
|
when fetching a source file.
|
|
</p><p>
|
|
<code class="filename">scons</code>
|
|
provides a set of canned factory
|
|
functions that return appropriate
|
|
Builders for various popular
|
|
source code management systems.
|
|
Canonical examples of invocation include:
|
|
</p><pre class="screen">
|
|
env.SourceCode('.', env.BitKeeper('/usr/local/BKsources'))
|
|
env.SourceCode('src', env.CVS('/usr/local/CVSROOT'))
|
|
env.SourceCode('/', env.RCS())
|
|
env.SourceCode(['f1.c', 'f2.c'], env.SCCS())
|
|
env.SourceCode('no_source.c', None)
|
|
</pre><p>
|
|
|
|
</p></dd><dt><a name="f-SourceSignatures"></a><span class="term">
|
|
<code class="literal">SourceSignatures(type)</code>
|
|
, </span><span class="term">
|
|
<code class="literal">env.SourceSignatures(type)</code>
|
|
</span></dt><dd><p>
|
|
Note: Although it is not yet officially deprecated,
|
|
use of this function is discouraged.
|
|
See the
|
|
<a class="link" href="#f-Decider"><code class="function">Decider</code></a>
|
|
function for a more flexible and straightforward way
|
|
to configure SCons' decision-making.
|
|
</p><p>
|
|
The
|
|
<code class="function">SourceSignatures</code>
|
|
function tells
|
|
<code class="filename">scons</code>
|
|
how to decide if a source file
|
|
(a file that is not built from any other files)
|
|
has changed since the last time it
|
|
was used to build a particular target file.
|
|
Legal values are
|
|
<code class="literal">MD5</code>
|
|
or
|
|
<code class="literal">timestamp</code>.
|
|
</p><p>
|
|
If the environment method is used,
|
|
the specified type of source signature
|
|
is only used when deciding whether targets
|
|
built with that environment are up-to-date or must be rebuilt.
|
|
If the global function is used,
|
|
the specified type of source signature becomes the default
|
|
used for all decisions
|
|
about whether targets are up-to-date.
|
|
</p><p>
|
|
<code class="literal">MD5</code>
|
|
means
|
|
<code class="filename">scons</code>
|
|
decides that a source file has changed
|
|
if the MD5 checksum of its contents has changed since
|
|
the last time it was used to rebuild a particular target file.
|
|
</p><p>
|
|
<code class="literal">timestamp</code>
|
|
means
|
|
<code class="filename">scons</code>
|
|
decides that a source file has changed
|
|
if its timestamp (modification time) has changed since
|
|
the last time it was used to rebuild a particular target file.
|
|
(Note that although this is similar to the behavior of Make,
|
|
by default it will also rebuild if the dependency is
|
|
<span class="emphasis"><em>older</em></span>
|
|
than the last time it was used to rebuild the target file.)
|
|
</p><p>
|
|
There is no different between the two behaviors
|
|
for Python
|
|
<code class="function">Value</code>
|
|
node objects.
|
|
</p><p>
|
|
<code class="literal">MD5</code>
|
|
signatures take longer to compute,
|
|
but are more accurate than
|
|
<code class="literal">timestamp</code>
|
|
signatures.
|
|
The default value is
|
|
<code class="literal">MD5</code>.
|
|
</p><p>
|
|
Note that the default
|
|
<a class="link" href="#f-TargetSignatures"><code class="function">TargetSignatures</code></a>
|
|
setting (see below)
|
|
is to use this
|
|
<code class="function">SourceSignatures</code>
|
|
setting for any target files that are used
|
|
to build other target files.
|
|
Consequently, changing the value of
|
|
<code class="function">SourceSignatures</code>
|
|
will, by default,
|
|
affect the up-to-date decision for all files in the build
|
|
(or all files built with a specific construction environment
|
|
when
|
|
<code class="function">env.SourceSignatures</code>
|
|
is used).
|
|
</p></dd><dt><a name="f-Split"></a><span class="term">
|
|
<code class="literal">Split(arg)</code>
|
|
, </span><span class="term">
|
|
<code class="literal">env.Split(arg)</code>
|
|
</span></dt><dd><p>
|
|
Returns a list of file names or other objects.
|
|
If arg is a string,
|
|
it will be split on strings of white-space characters
|
|
within the string,
|
|
making it easier to write long lists of file names.
|
|
If arg is already a list,
|
|
the list will be returned untouched.
|
|
If arg is any other type of object,
|
|
it will be returned as a list
|
|
containing just the object.
|
|
</p><p>
|
|
Example:
|
|
</p><pre class="screen">
|
|
files = Split("f1.c f2.c f3.c")
|
|
files = env.Split("f4.c f5.c f6.c")
|
|
files = Split("""
|
|
f7.c
|
|
f8.c
|
|
f9.c
|
|
""")
|
|
</pre></dd><dt><a name="f-subst"></a><span class="term">
|
|
<code class="literal">env.subst(input, [raw, target, source, conv])</code>
|
|
</span></dt><dd><p>
|
|
Performs construction variable interpolation
|
|
on the specified string or sequence argument
|
|
<code class="varname">input</code>.
|
|
</p><p>
|
|
By default,
|
|
leading or trailing white space will
|
|
be removed from the result.
|
|
and all sequences of white space
|
|
will be compressed to a single space character.
|
|
Additionally, any
|
|
<code class="literal">$(</code>
|
|
and
|
|
<code class="literal">$)</code>
|
|
character sequences will be stripped from the returned string,
|
|
The optional
|
|
<code class="varname">raw</code>
|
|
argument may be set to
|
|
<code class="literal">1</code>
|
|
if you want to preserve white space and
|
|
<code class="literal">$(</code>-<code class="literal">$)</code>
|
|
sequences.
|
|
The
|
|
<code class="varname">raw</code>
|
|
argument may be set to
|
|
<code class="literal">2</code>
|
|
if you want to strip
|
|
all characters between
|
|
any
|
|
<code class="literal">$(</code>
|
|
and
|
|
<code class="literal">$)</code>
|
|
pairs
|
|
(as is done for signature calculation).
|
|
</p><p>
|
|
If the input is a sequence
|
|
(list or tuple),
|
|
the individual elements of
|
|
the sequence will be expanded,
|
|
and the results will be returned as a list.
|
|
</p><p>
|
|
The optional
|
|
<code class="varname">target</code>
|
|
and
|
|
<code class="varname">source</code>
|
|
keyword arguments
|
|
must be set to lists of
|
|
target and source nodes, respectively,
|
|
if you want the
|
|
<code class="envar">$TARGET</code>,
|
|
<code class="envar">$TARGETS</code>,
|
|
<code class="envar">$SOURCE</code>
|
|
and
|
|
<code class="envar">$SOURCES</code>
|
|
to be available for expansion.
|
|
This is usually necessary if you are
|
|
calling
|
|
<code class="function">env.subst</code>
|
|
from within a Python function used
|
|
as an SCons action.
|
|
</p><p>
|
|
Returned string values or sequence elements
|
|
are converted to their string representation by default.
|
|
The optional
|
|
<code class="varname">conv</code>
|
|
argument
|
|
may specify a conversion function
|
|
that will be used in place of
|
|
the default.
|
|
For example, if you want Python objects
|
|
(including SCons Nodes)
|
|
to be returned as Python objects,
|
|
you can use the Python
|
|
Λ
|
|
idiom to pass in an unnamed function
|
|
that simply returns its unconverted argument.
|
|
</p><p>
|
|
Example:
|
|
</p><pre class="screen">
|
|
print env.subst("The C compiler is: $CC")
|
|
|
|
def compile(target, source, env):
|
|
sourceDir = env.subst("${SOURCE.srcdir}",
|
|
target=target,
|
|
source=source)
|
|
|
|
source_nodes = env.subst('$EXPAND_TO_NODELIST',
|
|
conv=lambda x: x)
|
|
</pre></dd><dt><a name="f-Tag"></a><span class="term">
|
|
<code class="literal">Tag(node, tags)</code>
|
|
</span></dt><dd><p>
|
|
Annotates file or directory Nodes with
|
|
information about how the
|
|
<a class="link" href="#b-Package"><code class="function">Package</code></a>
|
|
Builder should package those files or directories.
|
|
All tags are optional.
|
|
</p><p>
|
|
Examples:
|
|
</p><pre class="screen">
|
|
# makes sure the built library will be installed with 0644 file
|
|
# access mode
|
|
Tag( Library( 'lib.c' ), UNIX_ATTR="0644" )
|
|
|
|
# marks file2.txt to be a documentation file
|
|
Tag( 'file2.txt', DOC )
|
|
</pre></dd><dt><a name="f-TargetSignatures"></a><span class="term">
|
|
<code class="literal">TargetSignatures(type)</code>
|
|
, </span><span class="term">
|
|
<code class="literal">env.TargetSignatures(type)</code>
|
|
</span></dt><dd><p>
|
|
Note: Although it is not yet officially deprecated,
|
|
use of this function is discouraged.
|
|
See the
|
|
<a class="link" href="#f-Decider"><code class="function">Decider</code></a>
|
|
function for a more flexible and straightforward way
|
|
to configure SCons' decision-making.
|
|
</p><p>
|
|
The
|
|
<code class="function">TargetSignatures</code>
|
|
function tells
|
|
<code class="filename">scons</code>
|
|
how to decide if a target file
|
|
(a file that
|
|
<span class="emphasis"><em>is</em></span>
|
|
built from any other files)
|
|
has changed since the last time it
|
|
was used to build some other target file.
|
|
Legal values are
|
|
<code class="literal">"build"</code>;
|
|
<code class="literal">"content"</code>
|
|
(or its synonym
|
|
<code class="literal">"MD5"</code>);
|
|
<code class="literal">"timestamp"</code>;
|
|
or
|
|
<code class="literal">"source"</code>.
|
|
</p><p>
|
|
If the environment method is used,
|
|
the specified type of target signature is only used
|
|
for targets built with that environment.
|
|
If the global function is used,
|
|
the specified type of signature becomes the default
|
|
used for all target files that
|
|
don't have an explicit target signature type
|
|
specified for their environments.
|
|
</p><p>
|
|
<code class="literal">"content"</code>
|
|
(or its synonym
|
|
<code class="literal">"MD5"</code>)
|
|
means
|
|
<code class="filename">scons</code>
|
|
decides that a target file has changed
|
|
if the MD5 checksum of its contents has changed since
|
|
the last time it was used to rebuild some other target file.
|
|
This means
|
|
<code class="filename">scons</code>
|
|
will open up
|
|
MD5 sum the contents
|
|
of target files after they're built,
|
|
and may decide that it does not need to rebuild
|
|
"downstream" target files if a file was
|
|
rebuilt with exactly the same contents as the last time.
|
|
</p><p>
|
|
<code class="literal">"timestamp"</code>
|
|
means
|
|
<code class="filename">scons</code>
|
|
decides that a target file has changed
|
|
if its timestamp (modification time) has changed since
|
|
the last time it was used to rebuild some other target file.
|
|
(Note that although this is similar to the behavior of Make,
|
|
by default it will also rebuild if the dependency is
|
|
<span class="emphasis"><em>older</em></span>
|
|
than the last time it was used to rebuild the target file.)
|
|
</p><p>
|
|
<code class="literal">"source"</code>
|
|
means
|
|
<code class="filename">scons</code>
|
|
decides that a target file has changed
|
|
as specified by the corresponding
|
|
<code class="function">SourceSignatures</code>
|
|
setting
|
|
(<code class="literal">"MD5"</code>
|
|
or
|
|
<code class="literal">"timestamp"</code>).
|
|
This means that
|
|
<code class="filename">scons</code>
|
|
will treat all input files to a target the same way,
|
|
regardless of whether they are source files
|
|
or have been built from other files.
|
|
</p><p>
|
|
<code class="literal">"build"</code>
|
|
means
|
|
<code class="filename">scons</code>
|
|
decides that a target file has changed
|
|
if it has been rebuilt in this invocation
|
|
or if its content or timestamp have changed
|
|
as specified by the corresponding
|
|
<code class="function">SourceSignatures</code>
|
|
setting.
|
|
This "propagates" the status of a rebuilt file
|
|
so that other "downstream" target files
|
|
will always be rebuilt,
|
|
even if the contents or the timestamp
|
|
have not changed.
|
|
</p><p>
|
|
<code class="literal">"build"</code>
|
|
signatures are fastest because
|
|
<code class="literal">"content"</code>
|
|
(or
|
|
<code class="literal">"MD5"</code>)
|
|
signatures take longer to compute,
|
|
but are more accurate than
|
|
<code class="literal">"timestamp"</code>
|
|
signatures,
|
|
and can prevent unnecessary "downstream" rebuilds
|
|
when a target file is rebuilt to the exact same contents
|
|
as the previous build.
|
|
The
|
|
<code class="literal">"source"</code>
|
|
setting provides the most consistent behavior
|
|
when other target files may be rebuilt from
|
|
both source and target input files.
|
|
The default value is
|
|
<code class="literal">"source"</code>.
|
|
</p><p>
|
|
Because the default setting is
|
|
<code class="literal">"source"</code>,
|
|
using
|
|
<code class="function">SourceSignatures</code>
|
|
is generally preferable to
|
|
<code class="function">TargetSignatures</code>,
|
|
so that the up-to-date decision
|
|
will be consistent for all files
|
|
(or all files built with a specific construction environment).
|
|
Use of
|
|
<code class="function">TargetSignatures</code>
|
|
provides specific control for how built target files
|
|
affect their "downstream" dependencies.
|
|
</p></dd><dt><a name="f-Tool"></a><span class="term">
|
|
<code class="literal">Tool(string, [toolpath, **kw])</code>
|
|
, </span><span class="term">
|
|
<code class="literal">env.Tool(string, [toolpath, **kw])</code>
|
|
</span></dt><dd><p>
|
|
The
|
|
<code class="function">Tool</code>
|
|
form of the function
|
|
returns a callable object
|
|
that can be used to initialize
|
|
a construction environment using the
|
|
tools keyword of the Environment() method.
|
|
The object may be called with a construction
|
|
environment as an argument,
|
|
in which case the object will
|
|
add the necessary variables
|
|
to the construction environment
|
|
and the name of the tool will be added to the
|
|
<a class="link" href="#cv-TOOLS"><code class="envar">$TOOLS</code></a>
|
|
construction variable.
|
|
</p><p>
|
|
Additional keyword arguments are passed to the tool's
|
|
<code class="function">generate</code>()
|
|
method.
|
|
</p><p>
|
|
Examples:
|
|
</p><pre class="screen">
|
|
env = Environment(tools = [ Tool('msvc') ])
|
|
|
|
env = Environment()
|
|
t = Tool('msvc')
|
|
t(env) # adds 'msvc' to the TOOLS variable
|
|
u = Tool('opengl', toolpath = ['tools'])
|
|
u(env) # adds 'opengl' to the TOOLS variable
|
|
</pre><p>
|
|
The
|
|
<code class="function">env.Tool</code>
|
|
form of the function
|
|
applies the callable object for the specified tool
|
|
<code class="varname">string</code>
|
|
to the environment through which the method was called.
|
|
</p><p>
|
|
Additional keyword arguments are passed to the tool's
|
|
<code class="function">generate</code>()
|
|
method.
|
|
</p><pre class="screen">
|
|
env.Tool('gcc')
|
|
env.Tool('opengl', toolpath = ['build/tools'])
|
|
</pre></dd><dt><a name="f-Value"></a><span class="term">
|
|
<code class="literal">Value(value, [built_value])</code>
|
|
, </span><span class="term">
|
|
<code class="literal">env.Value(value, [built_value])</code>
|
|
</span></dt><dd><p>
|
|
Returns a Node object representing the specified Python value. Value
|
|
Nodes can be used as dependencies of targets. If the result of
|
|
calling
|
|
<code class="function">str</code>(<code class="varname">value</code>)
|
|
changes between SCons runs, any targets depending on
|
|
<code class="function">Value</code>(<code class="varname">value</code>)
|
|
will be rebuilt.
|
|
(This is true even when using timestamps to decide if
|
|
files are up-to-date.)
|
|
When using timestamp source signatures, Value Nodes'
|
|
timestamps are equal to the system time when the Node is created.
|
|
</p><p>
|
|
The returned Value Node object has a
|
|
<code class="function">write</code>()
|
|
method that can be used to "build" a Value Node
|
|
by setting a new value.
|
|
The optional
|
|
<code class="varname">built_value</code>
|
|
argument can be specified
|
|
when the Value Node is created
|
|
to indicate the Node should already be considered
|
|
"built."
|
|
There is a corresponding
|
|
<code class="function">read</code>()
|
|
method that will return the built value of the Node.
|
|
</p><p>
|
|
Examples:
|
|
</p><pre class="screen">
|
|
env = Environment()
|
|
|
|
def create(target, source, env):
|
|
# A function that will write a 'prefix=$SOURCE'
|
|
# string into the file name specified as the
|
|
# $TARGET.
|
|
f = open(str(target[0]), 'wb')
|
|
f.write('prefix=' + source[0].get_contents())
|
|
|
|
# Fetch the prefix= argument, if any, from the command
|
|
# line, and use /usr/local as the default.
|
|
prefix = ARGUMENTS.get('prefix', '/usr/local')
|
|
|
|
# Attach a .Config() builder for the above function action
|
|
# to the construction environment.
|
|
env['BUILDERS']['Config'] = Builder(action = create)
|
|
env.Config(target = 'package-config', source = Value(prefix))
|
|
|
|
def build_value(target, source, env):
|
|
# A function that "builds" a Python Value by updating
|
|
# the the Python value with the contents of the file
|
|
# specified as the source of the Builder call ($SOURCE).
|
|
target[0].write(source[0].get_contents())
|
|
|
|
output = env.Value('before')
|
|
input = env.Value('after')
|
|
|
|
# Attach a .UpdateValue() builder for the above function
|
|
# action to the construction environment.
|
|
env['BUILDERS']['UpdateValue'] = Builder(action = build_value)
|
|
env.UpdateValue(target = Value(output), source = Value(input))
|
|
</pre></dd><dt><a name="f-VariantDir"></a><span class="term">
|
|
<code class="literal">VariantDir(variant_dir, src_dir, [duplicate])</code>
|
|
, </span><span class="term">
|
|
<code class="literal">env.VariantDir(variant_dir, src_dir, [duplicate])</code>
|
|
</span></dt><dd><p>
|
|
Use the
|
|
<code class="function">VariantDir</code>
|
|
function to create a copy of your sources in another location:
|
|
if a name under
|
|
<code class="varname">variant_dir</code>
|
|
is not found but exists under
|
|
<code class="varname">src_dir</code>,
|
|
the file or directory is copied to
|
|
<code class="varname">variant_dir</code>.
|
|
Target files can be built in a different directory
|
|
than the original sources by simply refering to the sources (and targets)
|
|
within the variant tree.
|
|
</p><p>
|
|
<code class="function">VariantDir</code>
|
|
can be called multiple times with the same
|
|
<code class="varname">src_dir</code>
|
|
to set up multiple builds with different options
|
|
(<code class="varname">variants</code>).
|
|
The
|
|
<code class="varname">src_dir</code>
|
|
location must be in or underneath the SConstruct file's directory, and
|
|
<code class="varname">variant_dir</code>
|
|
may not be underneath
|
|
<code class="varname">src_dir</code>.
|
|
|
|
</p><p>
|
|
The default behavior is for
|
|
<code class="filename">scons</code>
|
|
to physically duplicate the source files in the variant tree.
|
|
Thus, a build performed in the variant tree is guaranteed to be identical
|
|
to a build performed in the source tree even if
|
|
intermediate source files are generated during the build,
|
|
or preprocessors or other scanners search for included files
|
|
relative to the source file,
|
|
or individual compilers or other invoked tools are hard-coded
|
|
to put derived files in the same directory as source files.
|
|
</p><p>
|
|
If possible on the platform,
|
|
the duplication is performed by linking rather than copying;
|
|
see also the
|
|
<code class="option">--duplicate</code>
|
|
command-line option.
|
|
Moreover, only the files needed for the build are duplicated;
|
|
files and directories that are not used are not present in
|
|
<code class="varname">variant_dir</code>.
|
|
</p><p>
|
|
Duplicating the source tree may be disabled by setting the
|
|
<code class="literal">duplicate</code>
|
|
argument to
|
|
<code class="literal">0</code>
|
|
(zero).
|
|
This will cause
|
|
<code class="filename">scons</code>
|
|
to invoke Builders using the path names of source files in
|
|
<code class="varname">src_dir</code>
|
|
and the path names of derived files within
|
|
<code class="varname">variant_dir</code>.
|
|
This is always more efficient than
|
|
<code class="literal">duplicate=1</code>,
|
|
and is usually safe for most builds
|
|
(but see above for cases that may cause problems).
|
|
</p><p>
|
|
Note that
|
|
<code class="function">VariantDir</code>
|
|
works most naturally with a subsidiary SConscript file.
|
|
However, you would then call the subsidiary SConscript file
|
|
not in the source directory, but in the
|
|
<code class="varname">variant_dir</code>,
|
|
regardless of the value of
|
|
<code class="literal">duplicate</code>.
|
|
This is how you tell
|
|
<code class="filename">scons</code>
|
|
which variant of a source tree to build:
|
|
</p><pre class="screen">
|
|
# run src/SConscript in two variant directories
|
|
VariantDir('build/variant1', 'src')
|
|
SConscript('build/variant1/SConscript')
|
|
VariantDir('build/variant2', 'src')
|
|
SConscript('build/variant2/SConscript')
|
|
</pre><p>
|
|
See also the
|
|
<a class="link" href="#f-SConscript"><code class="function">SConscript</code></a>
|
|
function, described above,
|
|
for another way to specify a variant directory
|
|
in conjunction with calling a subsidiary SConscript file.
|
|
</p><p>
|
|
Examples:
|
|
</p><pre class="screen">
|
|
# use names in the build directory, not the source directory
|
|
VariantDir('build', 'src', duplicate=0)
|
|
Program('build/prog', 'build/source.c')
|
|
</pre><pre class="screen">
|
|
# this builds both the source and docs in a separate subtree
|
|
VariantDir('build', '.', duplicate=0)
|
|
SConscript(dirs=['build/src','build/doc'])
|
|
</pre><pre class="screen">
|
|
# same as previous example, but only uses SConscript
|
|
SConscript(dirs='src', variant_dir='build/src', duplicate=0)
|
|
SConscript(dirs='doc', variant_dir='build/doc', duplicate=0)
|
|
</pre></dd><dt><a name="f-WhereIs"></a><span class="term">
|
|
<code class="literal">WhereIs(program, [path, pathext, reject])</code>
|
|
, </span><span class="term">
|
|
<code class="literal">env.WhereIs(program, [path, pathext, reject])</code>
|
|
</span></dt><dd><p>
|
|
Searches for the specified executable
|
|
<code class="varname">program</code>,
|
|
returning the full path name to the program
|
|
if it is found,
|
|
and returning None if not.
|
|
Searches the specified
|
|
<code class="varname">path</code>,
|
|
the value of the calling environment's PATH
|
|
(<code class="literal">env['ENV']['PATH']</code>),
|
|
or the user's current external PATH
|
|
(<code class="literal">os.environ['PATH']</code>)
|
|
by default.
|
|
On Windows systems, searches for executable
|
|
programs with any of the file extensions
|
|
listed in the specified
|
|
<code class="varname">pathext</code>,
|
|
the calling environment's PATHEXT
|
|
(<code class="literal">env['ENV']['PATHEXT']</code>)
|
|
or the user's current PATHEXT
|
|
(<code class="literal">os.environ['PATHEXT']</code>)
|
|
by default.
|
|
Will not select any
|
|
path name or names
|
|
in the specified
|
|
<code class="varname">reject</code>
|
|
list, if any.
|
|
</p></dd></dl></div></div><div class="refsect2" title="SConscript Variables"><a name="sconscript_variables"></a><h3>SConscript Variables</h3><p>In addition to the global functions and methods,
|
|
<span class="command"><strong>scons</strong></span>
|
|
supports a number of Python variables
|
|
that can be used in SConscript files
|
|
to affect how you want the build to be performed.
|
|
These variables may be accessed from custom Python modules that you
|
|
import into an SConscript file by adding the following
|
|
to the Python module:</p><pre class="literallayout">
|
|
from SCons.Script import *
|
|
</pre><div class="variablelist"><dl><dt><span class="term">ARGLIST</span></dt><dd><p>A list
|
|
<span class="emphasis"><em>keyword</em></span>=<span class="emphasis"><em>value</em></span>
|
|
arguments specified on the command line.
|
|
Each element in the list is a tuple
|
|
containing the
|
|
(<span class="emphasis"><em>keyword</em></span>,<span class="emphasis"><em>value</em></span>)
|
|
of the argument.
|
|
The separate
|
|
<span class="emphasis"><em>keyword</em></span>
|
|
and
|
|
<span class="emphasis"><em>value</em></span>
|
|
elements of the tuple
|
|
can be accessed by
|
|
subscripting for element
|
|
<span class="bold"><strong>[0]</strong></span>
|
|
and
|
|
<span class="bold"><strong>[1]</strong></span>
|
|
of the tuple, respectively.</p><p>Example:</p><pre class="literallayout">
|
|
print("first keyword, value =", ARGLIST[0][0], ARGLIST[0][1])
|
|
print("second keyword, value =", ARGLIST[1][0], ARGLIST[1][1])
|
|
third_tuple = ARGLIST[2]
|
|
print("third keyword, value =", third_tuple[0], third_tuple[1])
|
|
for key, value in ARGLIST:
|
|
# process key and value
|
|
</pre></dd><dt><span class="term">ARGUMENTS</span></dt><dd><p>A dictionary of all the
|
|
<span class="emphasis"><em>keyword</em></span>=<span class="emphasis"><em>value</em></span>
|
|
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
|
|
<span class="bold"><strong>ARGUMENTS</strong></span>
|
|
dictionary.</p><p>Example:</p><pre class="literallayout">
|
|
if ARGUMENTS.get('debug', 0):
|
|
env = Environment(CCFLAGS = '-g')
|
|
else:
|
|
env = Environment()
|
|
</pre></dd><dt><span class="term">BUILD_TARGETS</span></dt><dd><p>A list of the targets which
|
|
<span class="command"><strong>scons</strong></span>
|
|
will actually try to build,
|
|
regardless of whether they were specified on
|
|
the command line or via the
|
|
<span class="bold"><strong>Default</strong></span>()
|
|
function or method.
|
|
The elements of this list may be strings
|
|
<span class="emphasis"><em>or</em></span>
|
|
nodes, so you should run the list through the Python
|
|
<span class="bold"><strong>str</strong></span>
|
|
function to make sure any Node path names
|
|
are converted to strings.</p><p>Because this list may be taken from the
|
|
list of targets specified using the
|
|
<span class="bold"><strong>Default</strong></span>()
|
|
function or method,
|
|
the contents of the list may change
|
|
on each successive call to
|
|
<span class="bold"><strong>Default</strong></span>().
|
|
See the
|
|
<span class="bold"><strong>DEFAULT_TARGETS</strong></span>
|
|
list, below,
|
|
for additional information.</p><p>Example:</p><pre class="literallayout">
|
|
if 'foo' in BUILD_TARGETS:
|
|
print("Don't forget to test the `foo' program!")
|
|
if 'special/program' in BUILD_TARGETS:
|
|
SConscript('special')
|
|
</pre></dd></dl></div><p>Note that the
|
|
<span class="bold"><strong>BUILD_TARGETS</strong></span>
|
|
list only contains targets expected listed
|
|
on the command line or via calls to the
|
|
<span class="bold"><strong>Default</strong></span>()
|
|
function or method.
|
|
It does
|
|
<span class="emphasis"><em>not</em></span>
|
|
contain all dependent targets that will be built as
|
|
a result of making the sure the explicitly-specified
|
|
targets are up to date.</p><div class="variablelist"><dl><dt><span class="term">COMMAND_LINE_TARGETS</span></dt><dd><p>A list of the targets explicitly specified on
|
|
the command line.
|
|
If there are no targets specified on the command line,
|
|
the list is empty.
|
|
This can be used, for example,
|
|
to take specific actions only
|
|
when a certain target or targets
|
|
is explicitly being built.</p><p>Example:</p><pre class="literallayout">
|
|
if 'foo' in COMMAND_LINE_TARGETS:
|
|
print("Don't forget to test the `foo' program!")
|
|
if 'special/program' in COMMAND_LINE_TARGETS:
|
|
SConscript('special')
|
|
</pre></dd><dt><span class="term">DEFAULT_TARGETS</span></dt><dd><p>A list of the target
|
|
<span class="emphasis"><em>nodes</em></span>
|
|
that have been specified using the
|
|
<span class="bold"><strong>Default</strong></span>()
|
|
function or method.
|
|
The elements of the list are nodes,
|
|
so you need to run them through the Python
|
|
<span class="bold"><strong>str</strong></span>
|
|
function to get at the path name for each Node.</p><p>Example:</p><pre class="literallayout">
|
|
print(str(DEFAULT_TARGETS[0]))
|
|
if 'foo' in [str(t) for t in DEFAULT_TARGETS]:
|
|
print("Don't forget to test the `foo' program!")
|
|
</pre></dd></dl></div><p>The contents of the
|
|
<span class="bold"><strong>DEFAULT_TARGETS</strong></span>
|
|
list change on on each successive call to the
|
|
<span class="bold"><strong>Default</strong></span>()
|
|
function:</p><pre class="literallayout">
|
|
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 []
|
|
</pre><p>Consequently, be sure to use
|
|
<span class="bold"><strong>DEFAULT_TARGETS</strong></span>
|
|
only after you've made all of your
|
|
<span class="bold"><strong>Default</strong></span>()
|
|
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.</p></div><div class="refsect2" title="Construction Variables"><a name="construction_variables"></a><h3>Construction Variables</h3><p>A construction environment has an associated dictionary of
|
|
<span class="emphasis"><em>construction variables</em></span>
|
|
that are used by built-in or user-supplied build rules.
|
|
Construction variables must follow the same rules for
|
|
Python identifiers:
|
|
the initial character must be an underscore or letter,
|
|
followed by any number of underscores, letters, or digits.</p><p>A number of useful construction variables are automatically defined by
|
|
scons for each supported platform, and additional construction variables
|
|
can be defined by the user. The following is a list of the automatically
|
|
defined construction variables:</p><div class="variablelist"><dl><dt><a name="cv-__LDMODULEVERSIONFLAGS"></a><span class="term">__LDMODULEVERSIONFLAGS</span></dt><dd><p>
|
|
This construction variable automatically introduces <a class="link" href="#cv-_LDMODULEVERSIONFLAGS"><code class="envar">$_LDMODULEVERSIONFLAGS</code></a>
|
|
if <a class="link" href="#cv-LDMODULEVERSION"><code class="envar">$LDMODULEVERSION</code></a> is set. Othervise it evaluates to an empty string.
|
|
</p></dd><dt><a name="cv-__SHLIBVERSIONFLAGS"></a><span class="term">__SHLIBVERSIONFLAGS</span></dt><dd><p>
|
|
This construction variable automatically introduces <a class="link" href="#cv-_SHLIBVERSIONFLAGS"><code class="envar">$_SHLIBVERSIONFLAGS</code></a>
|
|
if <a class="link" href="#cv-SHLIBVERSION"><code class="envar">$SHLIBVERSION</code></a> is set. Othervise it evaluates to an empty string.
|
|
</p></dd><dt><a name="cv-_APPLELINK_COMPATIBILITY_VERSION"></a><span class="term">_APPLELINK_COMPATIBILITY_VERSION</span></dt><dd><p>
|
|
A macro (by default a generator function) used to create the linker flags to specify
|
|
apple's linker's -compatibility_version flag.
|
|
The default generator uses <a class="link" href="#cv-APPLELINK_COMPATIBILITY_VERSION"><code class="envar">$APPLELINK_COMPATIBILITY_VERSION</code></a>
|
|
and <a class="link" href="#cv-APPLELINK_NO_COMPATIBILITY_VERSION"><code class="envar">$APPLELINK_NO_COMPATIBILITY_VERSION</code></a> and <a class="link" href="#cv-SHLIBVERSION"><code class="envar">$SHLIBVERSION</code></a>
|
|
to determine the correct flag.
|
|
</p></dd><dt><a name="cv-APPLELINK_COMPATIBILITY_VERSION"></a><span class="term">APPLELINK_COMPATIBILITY_VERSION</span></dt><dd><p>
|
|
On Mac OS X this is used to set the linker flag:
|
|
|
|
-compatibility_version
|
|
</p><p>
|
|
The value is specified as X[.Y[.Z]] where X is between 1 and 65535, Y can be omitted or between 1 and
|
|
255, Z can be omitted or between 1 and 255. This value will be derived from <a class="link" href="#cv-SHLIBVERSION"><code class="envar">$SHLIBVERSION</code></a> if
|
|
not
|
|
specified. The lowest digit will be dropped and replaced by a 0.
|
|
</p><p>
|
|
If the <a class="link" href="#cv-APPLELINK_NO_COMPATIBILITY_VERSION"><code class="envar">$APPLELINK_NO_COMPATIBILITY_VERSION</code></a> is set then no -compatibility_version will be
|
|
output.
|
|
</p><p>See MacOS's ld manpage for more details</p></dd><dt><a name="cv-_APPLELINK_CURRENT_VERSION"></a><span class="term">_APPLELINK_CURRENT_VERSION</span></dt><dd><p>
|
|
A macro (by default a generator function) used to create the linker flags to specify apple's linker's
|
|
-current_version flag. The default generator uses <a class="link" href="#cv-APPLELINK_CURRENT_VERSION"><code class="envar">$APPLELINK_CURRENT_VERSION</code></a> and
|
|
<a class="link" href="#cv-APPLELINK_NO_CURRENT_VERSION"><code class="envar">$APPLELINK_NO_CURRENT_VERSION</code></a> and <a class="link" href="#cv-SHLIBVERSION"><code class="envar">$SHLIBVERSION</code></a> to determine the correct flag.
|
|
</p></dd><dt><a name="cv-APPLELINK_CURRENT_VERSION"></a><span class="term">APPLELINK_CURRENT_VERSION</span></dt><dd><p>
|
|
On Mac OS X this is used to set the linker flag:
|
|
|
|
-current_version
|
|
</p><p>
|
|
The value is specified as X[.Y[.Z]] where X is between 1 and 65535, Y can be omitted or between 1 and
|
|
255, Z can be omitted or between 1 and 255. This value will be set to <a class="link" href="#cv-SHLIBVERSION"><code class="envar">$SHLIBVERSION</code></a> if not
|
|
specified.
|
|
</p><p>
|
|
If the <a class="link" href="#cv-APPLELINK_NO_CURRENT_VERSION"><code class="envar">$APPLELINK_NO_CURRENT_VERSION</code></a> is set then no -current_version will be
|
|
output.
|
|
</p><p>See MacOS's ld manpage for more details</p></dd><dt><a name="cv-APPLELINK_NO_COMPATIBILITY_VERSION"></a><span class="term">APPLELINK_NO_COMPATIBILITY_VERSION</span></dt><dd><p>
|
|
Set this to any True (1|True|non-empty string) value to disable adding -compatibility_version flag when
|
|
generating versioned shared libraries.
|
|
</p><p>
|
|
This overrides <a class="link" href="#cv-APPLELINK_COMPATIBILITY_VERSION"><code class="envar">$APPLELINK_COMPATIBILITY_VERSION</code></a>.
|
|
</p></dd><dt><a name="cv-APPLELINK_NO_CURRENT_VERSION"></a><span class="term">APPLELINK_NO_CURRENT_VERSION</span></dt><dd><p>
|
|
Set this to any True (1|True|non-empty string) value to disable adding -current_version flag when
|
|
generating versioned shared libraries.
|
|
</p><p>
|
|
This overrides <a class="link" href="#cv-APPLELINK_CURRENT_VERSION"><code class="envar">$APPLELINK_CURRENT_VERSION</code></a>.
|
|
</p></dd><dt><a name="cv-AR"></a><span class="term">AR</span></dt><dd><p>
|
|
The static library archiver.
|
|
</p></dd><dt><a name="cv-ARCHITECTURE"></a><span class="term">ARCHITECTURE</span></dt><dd><p>
|
|
Specifies the system architecture for which
|
|
the package is being built.
|
|
The default is the system architecture
|
|
of the machine on which SCons is running.
|
|
This is used to fill in the
|
|
<code class="literal">Architecture:</code>
|
|
field in an Ipkg
|
|
<code class="filename">control</code> file,
|
|
and the <code class="literal">BuildArch:</code> field
|
|
in the RPM <code class="filename">.spec</code> file,
|
|
as well as forming part of the name of a generated RPM package file.
|
|
</p></dd><dt><a name="cv-ARCOM"></a><span class="term">ARCOM</span></dt><dd><p>
|
|
The command line used to generate a static library from object files.
|
|
</p></dd><dt><a name="cv-ARCOMSTR"></a><span class="term">ARCOMSTR</span></dt><dd><p>
|
|
The string displayed when an object file
|
|
is generated from an assembly-language source file.
|
|
If this is not set, then <a class="link" href="#cv-ARCOM"><code class="envar">$ARCOM</code></a> (the command line) is displayed.
|
|
</p><pre class="screen">
|
|
env = Environment(ARCOMSTR = "Archiving $TARGET")
|
|
</pre></dd><dt><a name="cv-ARFLAGS"></a><span class="term">ARFLAGS</span></dt><dd><p>
|
|
General options passed to the static library archiver.
|
|
</p></dd><dt><a name="cv-AS"></a><span class="term">AS</span></dt><dd><p>
|
|
The assembler.
|
|
</p></dd><dt><a name="cv-ASCOM"></a><span class="term">ASCOM</span></dt><dd><p>
|
|
The command line used to generate an object file
|
|
from an assembly-language source file.
|
|
</p></dd><dt><a name="cv-ASCOMSTR"></a><span class="term">ASCOMSTR</span></dt><dd><p>
|
|
The string displayed when an object file
|
|
is generated from an assembly-language source file.
|
|
If this is not set, then <a class="link" href="#cv-ASCOM"><code class="envar">$ASCOM</code></a> (the command line) is displayed.
|
|
</p><pre class="screen">
|
|
env = Environment(ASCOMSTR = "Assembling $TARGET")
|
|
</pre></dd><dt><a name="cv-ASFLAGS"></a><span class="term">ASFLAGS</span></dt><dd><p>
|
|
General options passed to the assembler.
|
|
</p></dd><dt><a name="cv-ASPPCOM"></a><span class="term">ASPPCOM</span></dt><dd><p>
|
|
The command line used to assemble an assembly-language
|
|
source file into an object file
|
|
after first running the file through the C preprocessor.
|
|
Any options specified
|
|
in the <a class="link" href="#cv-ASFLAGS"><code class="envar">$ASFLAGS</code></a> and <a class="link" href="#cv-CPPFLAGS"><code class="envar">$CPPFLAGS</code></a> construction variables
|
|
are included on this command line.
|
|
</p></dd><dt><a name="cv-ASPPCOMSTR"></a><span class="term">ASPPCOMSTR</span></dt><dd><p>
|
|
The string displayed when an object file
|
|
is generated from an assembly-language source file
|
|
after first running the file through the C preprocessor.
|
|
If this is not set, then <a class="link" href="#cv-ASPPCOM"><code class="envar">$ASPPCOM</code></a> (the command line) is displayed.
|
|
</p><pre class="screen">
|
|
env = Environment(ASPPCOMSTR = "Assembling $TARGET")
|
|
</pre></dd><dt><a name="cv-ASPPFLAGS"></a><span class="term">ASPPFLAGS</span></dt><dd><p>
|
|
General options when an assembling an assembly-language
|
|
source file into an object file
|
|
after first running the file through the C preprocessor.
|
|
The default is to use the value of <a class="link" href="#cv-ASFLAGS"><code class="envar">$ASFLAGS</code></a>.
|
|
</p></dd><dt><a name="cv-BIBTEX"></a><span class="term">BIBTEX</span></dt><dd><p>
|
|
The bibliography generator for the TeX formatter and typesetter and the
|
|
LaTeX structured formatter and typesetter.
|
|
</p></dd><dt><a name="cv-BIBTEXCOM"></a><span class="term">BIBTEXCOM</span></dt><dd><p>
|
|
The command line used to call the bibliography generator for the
|
|
TeX formatter and typesetter and the LaTeX structured formatter and
|
|
typesetter.
|
|
</p></dd><dt><a name="cv-BIBTEXCOMSTR"></a><span class="term">BIBTEXCOMSTR</span></dt><dd><p>
|
|
The string displayed when generating a bibliography
|
|
for TeX or LaTeX.
|
|
If this is not set, then <a class="link" href="#cv-BIBTEXCOM"><code class="envar">$BIBTEXCOM</code></a> (the command line) is displayed.
|
|
</p><pre class="screen">
|
|
env = Environment(BIBTEXCOMSTR = "Generating bibliography $TARGET")
|
|
</pre></dd><dt><a name="cv-BIBTEXFLAGS"></a><span class="term">BIBTEXFLAGS</span></dt><dd><p>
|
|
General options passed to the bibliography generator for the TeX formatter
|
|
and typesetter and the LaTeX structured formatter and typesetter.
|
|
</p></dd><dt><a name="cv-BUILDERS"></a><span class="term">BUILDERS</span></dt><dd><p>
|
|
A dictionary mapping the names of the builders
|
|
available through this environment
|
|
to underlying Builder objects.
|
|
Builders named
|
|
Alias, CFile, CXXFile, DVI, Library, Object, PDF, PostScript, and Program
|
|
are available by default.
|
|
If you initialize this variable when an
|
|
Environment is created:
|
|
</p><pre class="screen">
|
|
env = Environment(BUILDERS = {'NewBuilder' : foo})
|
|
</pre><p>
|
|
the default Builders will no longer be available.
|
|
To use a new Builder object in addition to the default Builders,
|
|
add your new Builder object like this:
|
|
</p><pre class="screen">
|
|
env = Environment()
|
|
env.Append(BUILDERS = {'NewBuilder' : foo})
|
|
</pre><p>
|
|
or this:
|
|
</p><pre class="screen">
|
|
env = Environment()
|
|
env['BUILDERS']['NewBuilder'] = foo
|
|
</pre></dd><dt><a name="cv-CC"></a><span class="term">CC</span></dt><dd><p>
|
|
The C compiler.
|
|
</p></dd><dt><a name="cv-CCCOM"></a><span class="term">CCCOM</span></dt><dd><p>
|
|
The command line used to compile a C source file to a (static) object
|
|
file. Any options specified in the <a class="link" href="#cv-CFLAGS"><code class="envar">$CFLAGS</code></a>, <a class="link" href="#cv-CCFLAGS"><code class="envar">$CCFLAGS</code></a> and
|
|
<a class="link" href="#cv-CPPFLAGS"><code class="envar">$CPPFLAGS</code></a> construction variables are included on this command
|
|
line.
|
|
</p></dd><dt><a name="cv-CCCOMSTR"></a><span class="term">CCCOMSTR</span></dt><dd><p>
|
|
The string displayed when a C source file
|
|
is compiled to a (static) object file.
|
|
If this is not set, then <a class="link" href="#cv-CCCOM"><code class="envar">$CCCOM</code></a> (the command line) is displayed.
|
|
</p><pre class="screen">
|
|
env = Environment(CCCOMSTR = "Compiling static object $TARGET")
|
|
</pre></dd><dt><a name="cv-CCFLAGS"></a><span class="term">CCFLAGS</span></dt><dd><p>
|
|
General options that are passed to the C and C++ compilers.
|
|
</p></dd><dt><a name="cv-CCPCHFLAGS"></a><span class="term">CCPCHFLAGS</span></dt><dd><p>
|
|
Options added to the compiler command line
|
|
to support building with precompiled headers.
|
|
The default value expands expands to the appropriate
|
|
Microsoft Visual C++ command-line options
|
|
when the <a class="link" href="#cv-PCH"><code class="envar">$PCH</code></a> construction variable is set.
|
|
</p></dd><dt><a name="cv-CCPDBFLAGS"></a><span class="term">CCPDBFLAGS</span></dt><dd><p>
|
|
Options added to the compiler command line
|
|
to support storing debugging information in a
|
|
Microsoft Visual C++ PDB file.
|
|
The default value expands expands to appropriate
|
|
Microsoft Visual C++ command-line options
|
|
when the <a class="link" href="#cv-PDB"><code class="envar">$PDB</code></a> construction variable is set.
|
|
</p><p>
|
|
The Visual C++ compiler option that SCons uses by default
|
|
to generate PDB information is <code class="option">/Z7</code>.
|
|
This works correctly with parallel (<code class="option">-j</code>) builds
|
|
because it embeds the debug information in the intermediate object files,
|
|
as opposed to sharing a single PDB file between multiple object files.
|
|
This is also the only way to get debug information
|
|
embedded into a static library.
|
|
Using the <code class="option">/Zi</code> instead may yield improved
|
|
link-time performance,
|
|
although parallel builds will no longer work.
|
|
</p><p>
|
|
You can generate PDB files with the <code class="option">/Zi</code>
|
|
switch by overriding the default <a class="link" href="#cv-CCPDBFLAGS"><code class="envar">$CCPDBFLAGS</code></a> variable as follows:
|
|
</p><pre class="screen">
|
|
env['CCPDBFLAGS'] = ['${(PDB and "/Zi /Fd%s" % File(PDB)) or ""}']
|
|
</pre><p>
|
|
An alternative would be to use the <code class="option">/Zi</code>
|
|
to put the debugging information in a separate <code class="filename">.pdb</code>
|
|
file for each object file by overriding
|
|
the <a class="link" href="#cv-CCPDBFLAGS"><code class="envar">$CCPDBFLAGS</code></a> variable as follows:
|
|
</p><pre class="screen">
|
|
env['CCPDBFLAGS'] = '/Zi /Fd${TARGET}.pdb'
|
|
</pre></dd><dt><a name="cv-CCVERSION"></a><span class="term">CCVERSION</span></dt><dd><p>
|
|
The version number of the C compiler.
|
|
This may or may not be set,
|
|
depending on the specific C compiler being used.
|
|
</p></dd><dt><a name="cv-CFILESUFFIX"></a><span class="term">CFILESUFFIX</span></dt><dd><p>
|
|
The suffix for C source files.
|
|
This is used by the internal CFile builder
|
|
when generating C files from Lex (.l) or YACC (.y) input files.
|
|
The default suffix, of course, is
|
|
<code class="filename">.c</code>
|
|
(lower case).
|
|
On case-insensitive systems (like Windows),
|
|
SCons also treats
|
|
<code class="filename">.C</code>
|
|
(upper case) files
|
|
as C files.
|
|
</p></dd><dt><a name="cv-CFLAGS"></a><span class="term">CFLAGS</span></dt><dd><p>
|
|
General options that are passed to the C compiler (C only; not C++).
|
|
</p></dd><dt><a name="cv-CHANGE_SPECFILE"></a><span class="term">CHANGE_SPECFILE</span></dt><dd><p>
|
|
A hook for modifying the file that controls the packaging build
|
|
(the <code class="filename">.spec</code> for RPM,
|
|
the <code class="filename">control</code> for Ipkg,
|
|
the <code class="filename">.wxs</code> for MSI).
|
|
If set, the function will be called
|
|
after the SCons template for the file has been written.
|
|
</p></dd><dt><a name="cv-CHANGED_SOURCES"></a><span class="term">CHANGED_SOURCES</span></dt><dd><p>
|
|
A reserved variable name
|
|
that may not be set or used in a construction environment.
|
|
(See "Variable Substitution," below.)
|
|
</p></dd><dt><a name="cv-CHANGED_TARGETS"></a><span class="term">CHANGED_TARGETS</span></dt><dd><p>
|
|
A reserved variable name
|
|
that may not be set or used in a construction environment.
|
|
(See "Variable Substitution," below.)
|
|
</p></dd><dt><a name="cv-CHANGELOG"></a><span class="term">CHANGELOG</span></dt><dd><p>
|
|
The name of a file containing the change log text
|
|
to be included in the package.
|
|
This is included as the
|
|
<code class="literal">%changelog</code>
|
|
section of the RPM
|
|
<code class="filename">.spec</code> file.
|
|
</p></dd><dt><a name="cv-_concat"></a><span class="term">_concat</span></dt><dd><p>
|
|
A function used to produce variables like <code class="envar">$_CPPINCFLAGS</code>. It takes
|
|
four or five
|
|
arguments: a prefix to concatenate onto each element, a list of
|
|
elements, a suffix to concatenate onto each element, an environment
|
|
for variable interpolation, and an optional function that will be
|
|
called to transform the list before concatenation.
|
|
</p><pre class="screen">
|
|
env['_CPPINCFLAGS'] = '$( ${_concat(INCPREFIX, CPPPATH, INCSUFFIX, __env__, RDirs)} $)',
|
|
</pre></dd><dt><a name="cv-CONFIGUREDIR"></a><span class="term">CONFIGUREDIR</span></dt><dd><p>
|
|
The name of the directory in which
|
|
Configure context test files are written.
|
|
The default is
|
|
<code class="filename">.sconf_temp</code>
|
|
in the top-level directory
|
|
containing the
|
|
<code class="filename">SConstruct</code>
|
|
file.
|
|
</p></dd><dt><a name="cv-CONFIGURELOG"></a><span class="term">CONFIGURELOG</span></dt><dd><p>
|
|
The name of the Configure context log file.
|
|
The default is
|
|
<code class="filename">config.log</code>
|
|
in the top-level directory
|
|
containing the
|
|
<code class="filename">SConstruct</code>
|
|
file.
|
|
</p></dd><dt><a name="cv-_CPPDEFFLAGS"></a><span class="term">_CPPDEFFLAGS</span></dt><dd><p>
|
|
An automatically-generated construction variable
|
|
containing the C preprocessor command-line options
|
|
to define values.
|
|
The value of <code class="envar">$_CPPDEFFLAGS</code> is created
|
|
by respectively prepending and appending
|
|
<code class="envar">$CPPDEFPREFIX</code> and <code class="envar">$CPPDEFSUFFIX</code>
|
|
to the beginning and end
|
|
of each definition in <code class="envar">$CPPDEFINES</code>.
|
|
</p></dd><dt><a name="cv-CPPDEFINES"></a><span class="term">CPPDEFINES</span></dt><dd><p>
|
|
A platform independent specification of C preprocessor definitions.
|
|
The definitions will be added to command lines
|
|
through the automatically-generated
|
|
<code class="envar">$_CPPDEFFLAGS</code> construction variable (see above),
|
|
which is constructed according to
|
|
the type of value of <code class="envar">$CPPDEFINES</code>:
|
|
</p><p>
|
|
If <code class="envar">$CPPDEFINES</code> is a string,
|
|
the values of the
|
|
<code class="envar">$CPPDEFPREFIX</code> and <code class="envar">$CPPDEFSUFFIX</code>
|
|
construction variables
|
|
will be respectively prepended and appended to the beginning and end
|
|
of each definition in <code class="envar">$CPPDEFINES</code>.
|
|
</p><pre class="screen">
|
|
# Will add -Dxyz to POSIX compiler command lines,
|
|
# and /Dxyz to Microsoft Visual C++ command lines.
|
|
env = Environment(CPPDEFINES='xyz')
|
|
</pre><p>
|
|
If <code class="envar">$CPPDEFINES</code> is a list,
|
|
the values of the
|
|
<code class="envar">$CPPDEFPREFIX</code> and <code class="envar">$CPPDEFSUFFIX</code>
|
|
construction variables
|
|
will be respectively prepended and appended to the beginning and end
|
|
of each element in the list.
|
|
If any element is a list or tuple,
|
|
then the first item is the name being
|
|
defined and the second item is its value:
|
|
</p><pre class="screen">
|
|
# Will add -DB=2 -DA to POSIX compiler command lines,
|
|
# and /DB=2 /DA to Microsoft Visual C++ command lines.
|
|
env = Environment(CPPDEFINES=[('B', 2), 'A'])
|
|
</pre><p>
|
|
If <code class="envar">$CPPDEFINES</code> is a dictionary,
|
|
the values of the
|
|
<code class="envar">$CPPDEFPREFIX</code> and <code class="envar">$CPPDEFSUFFIX</code>
|
|
construction variables
|
|
will be respectively prepended and appended to the beginning and end
|
|
of each item from the dictionary.
|
|
The key of each dictionary item
|
|
is a name being defined
|
|
to the dictionary item's corresponding value;
|
|
if the value is
|
|
<code class="literal">None</code>,
|
|
then the name is defined without an explicit value.
|
|
Note that the resulting flags are sorted by keyword
|
|
to ensure that the order of the options on the
|
|
command line is consistent each time
|
|
<code class="filename">scons</code>
|
|
is run.
|
|
</p><pre class="screen">
|
|
# Will add -DA -DB=2 to POSIX compiler command lines,
|
|
# and /DA /DB=2 to Microsoft Visual C++ command lines.
|
|
env = Environment(CPPDEFINES={'B':2, 'A':None})
|
|
</pre></dd><dt><a name="cv-CPPDEFPREFIX"></a><span class="term">CPPDEFPREFIX</span></dt><dd><p>
|
|
The prefix used to specify preprocessor definitions
|
|
on the C compiler command line.
|
|
This will be prepended to the beginning of each definition
|
|
in the <code class="envar">$CPPDEFINES</code> construction variable
|
|
when the <code class="envar">$_CPPDEFFLAGS</code> variable is automatically generated.
|
|
</p></dd><dt><a name="cv-CPPDEFSUFFIX"></a><span class="term">CPPDEFSUFFIX</span></dt><dd><p>
|
|
The suffix used to specify preprocessor definitions
|
|
on the C compiler command line.
|
|
This will be appended to the end of each definition
|
|
in the <code class="envar">$CPPDEFINES</code> construction variable
|
|
when the <code class="envar">$_CPPDEFFLAGS</code> variable is automatically generated.
|
|
</p></dd><dt><a name="cv-CPPFLAGS"></a><span class="term">CPPFLAGS</span></dt><dd><p>
|
|
User-specified C preprocessor options.
|
|
These will be included in any command that uses the C preprocessor,
|
|
including not just compilation of C and C++ source files
|
|
via the <a class="link" href="#cv-CCCOM"><code class="envar">$CCCOM</code></a>,
|
|
<a class="link" href="#cv-SHCCCOM"><code class="envar">$SHCCCOM</code></a>,
|
|
<a class="link" href="#cv-CXXCOM"><code class="envar">$CXXCOM</code></a> and
|
|
<a class="link" href="#cv-SHCXXCOM"><code class="envar">$SHCXXCOM</code></a> command lines,
|
|
but also the <a class="link" href="#cv-FORTRANPPCOM"><code class="envar">$FORTRANPPCOM</code></a>,
|
|
<a class="link" href="#cv-SHFORTRANPPCOM"><code class="envar">$SHFORTRANPPCOM</code></a>,
|
|
<a class="link" href="#cv-F77PPCOM"><code class="envar">$F77PPCOM</code></a> and
|
|
<a class="link" href="#cv-SHF77PPCOM"><code class="envar">$SHF77PPCOM</code></a> command lines
|
|
used to compile a Fortran source file,
|
|
and the <a class="link" href="#cv-ASPPCOM"><code class="envar">$ASPPCOM</code></a> command line
|
|
used to assemble an assembly language source file,
|
|
after first running each file through the C preprocessor.
|
|
Note that this variable does
|
|
<span class="emphasis"><em>not</em></span>
|
|
contain
|
|
<code class="option">-I</code>
|
|
(or similar) include search path options
|
|
that scons generates automatically from <a class="link" href="#cv-CPPPATH"><code class="envar">$CPPPATH</code></a>.
|
|
See <a class="link" href="#cv-_CPPINCFLAGS"><code class="envar">$_CPPINCFLAGS</code></a>, below,
|
|
for the variable that expands to those options.
|
|
</p></dd><dt><a name="cv-_CPPINCFLAGS"></a><span class="term">_CPPINCFLAGS</span></dt><dd><p>
|
|
An automatically-generated construction variable
|
|
containing the C preprocessor command-line options
|
|
for specifying directories to be searched for include files.
|
|
The value of <code class="envar">$_CPPINCFLAGS</code> is created
|
|
by respectively prepending and appending <code class="envar">$INCPREFIX</code> and <code class="envar">$INCSUFFIX</code>
|
|
to the beginning and end
|
|
of each directory in <code class="envar">$CPPPATH</code>.
|
|
</p></dd><dt><a name="cv-CPPPATH"></a><span class="term">CPPPATH</span></dt><dd><p>
|
|
The list of directories that the C preprocessor will search for include
|
|
directories. The C/C++ implicit dependency scanner will search these
|
|
directories for include files. Don't explicitly put include directory
|
|
arguments in CCFLAGS or CXXFLAGS because the result will be non-portable
|
|
and the directories will not be searched by the dependency scanner. Note:
|
|
directory names in CPPPATH will be looked-up relative to the SConscript
|
|
directory when they are used in a command. To force
|
|
<code class="filename">scons</code>
|
|
to look-up a directory relative to the root of the source tree use #:
|
|
</p><pre class="screen">
|
|
env = Environment(CPPPATH='#/include')
|
|
</pre><p>
|
|
The directory look-up can also be forced using the
|
|
<code class="function">Dir</code>()
|
|
function:
|
|
</p><pre class="screen">
|
|
include = Dir('include')
|
|
env = Environment(CPPPATH=include)
|
|
</pre><p>
|
|
The directory list will be added to command lines
|
|
through the automatically-generated
|
|
<code class="envar">$_CPPINCFLAGS</code>
|
|
construction variable,
|
|
which is constructed by
|
|
respectively prepending and appending the value of the
|
|
<code class="envar">$INCPREFIX</code> and <code class="envar">$INCSUFFIX</code>
|
|
construction variables
|
|
to the beginning and end
|
|
of each directory in <code class="envar">$CPPPATH</code>.
|
|
Any command lines you define that need
|
|
the CPPPATH directory list should
|
|
include <code class="envar">$_CPPINCFLAGS</code>:
|
|
</p><pre class="screen">
|
|
env = Environment(CCCOM="my_compiler $_CPPINCFLAGS -c -o $TARGET $SOURCE")
|
|
</pre></dd><dt><a name="cv-CPPSUFFIXES"></a><span class="term">CPPSUFFIXES</span></dt><dd><p>
|
|
The list of suffixes of files that will be scanned
|
|
for C preprocessor implicit dependencies
|
|
(#include lines).
|
|
The default list is:
|
|
</p><pre class="screen">
|
|
[".c", ".C", ".cxx", ".cpp", ".c++", ".cc",
|
|
".h", ".H", ".hxx", ".hpp", ".hh",
|
|
".F", ".fpp", ".FPP",
|
|
".m", ".mm",
|
|
".S", ".spp", ".SPP"]
|
|
</pre></dd><dt><a name="cv-CXX"></a><span class="term">CXX</span></dt><dd><p>
|
|
The C++ compiler.
|
|
</p></dd><dt><a name="cv-CXXCOM"></a><span class="term">CXXCOM</span></dt><dd><p>
|
|
The command line used to compile a C++ source file to an object file.
|
|
Any options specified in the <a class="link" href="#cv-CXXFLAGS"><code class="envar">$CXXFLAGS</code></a> and
|
|
<a class="link" href="#cv-CPPFLAGS"><code class="envar">$CPPFLAGS</code></a> construction variables
|
|
are included on this command line.
|
|
</p></dd><dt><a name="cv-CXXCOMSTR"></a><span class="term">CXXCOMSTR</span></dt><dd><p>
|
|
The string displayed when a C++ source file
|
|
is compiled to a (static) object file.
|
|
If this is not set, then <a class="link" href="#cv-CXXCOM"><code class="envar">$CXXCOM</code></a> (the command line) is displayed.
|
|
</p><pre class="screen">
|
|
env = Environment(CXXCOMSTR = "Compiling static object $TARGET")
|
|
</pre></dd><dt><a name="cv-CXXFILESUFFIX"></a><span class="term">CXXFILESUFFIX</span></dt><dd><p>
|
|
The suffix for C++ source files.
|
|
This is used by the internal CXXFile builder
|
|
when generating C++ files from Lex (.ll) or YACC (.yy) input files.
|
|
The default suffix is
|
|
<code class="filename">.cc</code>.
|
|
SCons also treats files with the suffixes
|
|
<code class="filename">.cpp</code>,
|
|
<code class="filename">.cxx</code>,
|
|
<code class="filename">.c++</code>,
|
|
and
|
|
<code class="filename">.C++</code>
|
|
as C++ files,
|
|
and files with
|
|
<code class="filename">.mm</code>
|
|
suffixes as Objective C++ files.
|
|
On case-sensitive systems (Linux, UNIX, and other POSIX-alikes),
|
|
SCons also treats
|
|
<code class="filename">.C</code>
|
|
(upper case) files
|
|
as C++ files.
|
|
</p></dd><dt><a name="cv-CXXFLAGS"></a><span class="term">CXXFLAGS</span></dt><dd><p>
|
|
General options that are passed to the C++ compiler.
|
|
By default, this includes the value of <a class="link" href="#cv-CCFLAGS"><code class="envar">$CCFLAGS</code></a>,
|
|
so that setting <code class="envar">$CCFLAGS</code> affects both C and C++ compilation.
|
|
If you want to add C++-specific flags,
|
|
you must set or override the value of <a class="link" href="#cv-CXXFLAGS"><code class="envar">$CXXFLAGS</code></a>.
|
|
</p></dd><dt><a name="cv-CXXVERSION"></a><span class="term">CXXVERSION</span></dt><dd><p>
|
|
The version number of the C++ compiler.
|
|
This may or may not be set,
|
|
depending on the specific C++ compiler being used.
|
|
</p></dd><dt><a name="cv-DC"></a><span class="term">DC</span></dt><dd><p>
|
|
The D compiler to use.
|
|
</p><p>
|
|
The D compiler to use.
|
|
</p><p>
|
|
The D compiler to use.
|
|
</p></dd><dt><a name="cv-DCOM"></a><span class="term">DCOM</span></dt><dd><p>
|
|
The command line used to compile a D file to an object file.
|
|
Any options specified in the <a class="link" href="#cv-DFLAGS"><code class="envar">$DFLAGS</code></a> construction variable
|
|
is included on this command line.
|
|
</p><p>
|
|
The command line used to compile a D file to an object file.
|
|
Any options specified in the <a class="link" href="#cv-DFLAGS"><code class="envar">$DFLAGS</code></a> construction variable
|
|
is included on this command line.
|
|
</p><p>
|
|
The command line used to compile a D file to an object file.
|
|
Any options specified in the <a class="link" href="#cv-DFLAGS"><code class="envar">$DFLAGS</code></a> construction variable
|
|
is included on this command line.
|
|
</p></dd><dt><a name="cv-DDEBUG"></a><span class="term">DDEBUG</span></dt><dd><p>
|
|
List of debug tags to enable when compiling.
|
|
</p><p>
|
|
List of debug tags to enable when compiling.
|
|
</p><p>
|
|
List of debug tags to enable when compiling.
|
|
</p></dd><dt><a name="cv-DDEBUGPREFIX"></a><span class="term">DDEBUGPREFIX</span></dt><dd><p>
|
|
DDEBUGPREFIX.
|
|
</p><p>
|
|
DDEBUGPREFIX.
|
|
</p><p>
|
|
DDEBUGPREFIX.
|
|
</p></dd><dt><a name="cv-DDEBUGSUFFIX"></a><span class="term">DDEBUGSUFFIX</span></dt><dd><p>
|
|
DDEBUGSUFFIX.
|
|
</p><p>
|
|
DDEBUGSUFFIX.
|
|
</p><p>
|
|
DDEBUGSUFFIX.
|
|
</p></dd><dt><a name="cv-DESCRIPTION"></a><span class="term">DESCRIPTION</span></dt><dd><p>
|
|
A long description of the project being packaged.
|
|
This is included in the relevant section
|
|
of the file that controls the packaging build.
|
|
</p></dd><dt><a name="cv-DESCRIPTION_lang"></a><span class="term">DESCRIPTION_lang</span></dt><dd><p>
|
|
A language-specific long description for
|
|
the specified <code class="varname">lang</code>.
|
|
This is used to populate a
|
|
<code class="literal">%description -l</code>
|
|
section of an RPM
|
|
<code class="filename">.spec</code> file.
|
|
</p></dd><dt><a name="cv-DFILESUFFIX"></a><span class="term">DFILESUFFIX</span></dt><dd><p>
|
|
DFILESUFFIX.
|
|
</p><p>
|
|
DFILESUFFIX.
|
|
</p><p>
|
|
DFILESUFFIX.
|
|
</p></dd><dt><a name="cv-DFLAGPREFIX"></a><span class="term">DFLAGPREFIX</span></dt><dd><p>
|
|
DFLAGPREFIX.
|
|
</p><p>
|
|
DFLAGPREFIX.
|
|
</p><p>
|
|
DFLAGPREFIX.
|
|
</p></dd><dt><a name="cv-DFLAGS"></a><span class="term">DFLAGS</span></dt><dd><p>
|
|
General options that are passed to the D compiler.
|
|
</p><p>
|
|
General options that are passed to the D compiler.
|
|
</p><p>
|
|
General options that are passed to the D compiler.
|
|
</p></dd><dt><a name="cv-DFLAGSUFFIX"></a><span class="term">DFLAGSUFFIX</span></dt><dd><p>
|
|
DFLAGSUFFIX.
|
|
</p><p>
|
|
DFLAGSUFFIX.
|
|
</p><p>
|
|
DFLAGSUFFIX.
|
|
</p></dd><dt><a name="cv-DINCPREFIX"></a><span class="term">DINCPREFIX</span></dt><dd><p>
|
|
DINCPREFIX.
|
|
</p><p>
|
|
DINCPREFIX.
|
|
</p><p>
|
|
DINCPREFIX.
|
|
</p></dd><dt><a name="cv-DINCSUFFIX"></a><span class="term">DINCSUFFIX</span></dt><dd><p>
|
|
DLIBFLAGSUFFIX.
|
|
</p><p>
|
|
DLIBFLAGSUFFIX.
|
|
</p><p>
|
|
DLIBFLAGSUFFIX.
|
|
</p></dd><dt><a name="cv-Dir"></a><span class="term">Dir</span></dt><dd><p>
|
|
A function that converts a string
|
|
into a Dir instance relative to the target being built.
|
|
</p><p>
|
|
A function that converts a string
|
|
into a Dir instance relative to the target being built.
|
|
</p></dd><dt><a name="cv-Dirs"></a><span class="term">Dirs</span></dt><dd><p>
|
|
A function that converts a list of strings
|
|
into a list of Dir instances relative to the target being built.
|
|
</p></dd><dt><a name="cv-DLIB"></a><span class="term">DLIB</span></dt><dd><p>
|
|
Name of the lib tool to use for D codes.
|
|
</p><p>
|
|
Name of the lib tool to use for D codes.
|
|
</p><p>
|
|
Name of the lib tool to use for D codes.
|
|
</p></dd><dt><a name="cv-DLIBCOM"></a><span class="term">DLIBCOM</span></dt><dd><p>
|
|
The command line to use when creating libraries.
|
|
</p><p>
|
|
The command line to use when creating libraries.
|
|
</p><p>
|
|
The command line to use when creating libraries.
|
|
</p></dd><dt><a name="cv-DLIBDIRPREFIX"></a><span class="term">DLIBDIRPREFIX</span></dt><dd><p>
|
|
DLIBLINKPREFIX.
|
|
</p><p>
|
|
DLIBLINKPREFIX.
|
|
</p><p>
|
|
DLIBLINKPREFIX.
|
|
</p></dd><dt><a name="cv-DLIBDIRSUFFIX"></a><span class="term">DLIBDIRSUFFIX</span></dt><dd><p>
|
|
DLIBLINKSUFFIX.
|
|
</p><p>
|
|
DLIBLINKSUFFIX.
|
|
</p><p>
|
|
DLIBLINKSUFFIX.
|
|
</p></dd><dt><a name="cv-DLIBFLAGPREFIX"></a><span class="term">DLIBFLAGPREFIX</span></dt><dd><p>
|
|
DLIBFLAGPREFIX.
|
|
</p><p>
|
|
DLIBFLAGPREFIX.
|
|
</p><p>
|
|
DLIBFLAGPREFIX.
|
|
</p></dd><dt><a name="cv-DLIBFLAGSUFFIX"></a><span class="term">DLIBFLAGSUFFIX</span></dt><dd><p>
|
|
DLIBFLAGSUFFIX.
|
|
</p><p>
|
|
DLIBFLAGSUFFIX.
|
|
</p><p>
|
|
DLIBFLAGSUFFIX.
|
|
</p></dd><dt><a name="cv-DLIBLINKPREFIX"></a><span class="term">DLIBLINKPREFIX</span></dt><dd><p>
|
|
DLIBLINKPREFIX.
|
|
</p><p>
|
|
DLIBLINKPREFIX.
|
|
</p><p>
|
|
DLIBLINKPREFIX.
|
|
</p></dd><dt><a name="cv-DLIBLINKSUFFIX"></a><span class="term">DLIBLINKSUFFIX</span></dt><dd><p>
|
|
DLIBLINKSUFFIX.
|
|
</p><p>
|
|
DLIBLINKSUFFIX.
|
|
</p><p>
|
|
DLIBLINKSUFFIX.
|
|
</p></dd><dt><a name="cv-DLINK"></a><span class="term">DLINK</span></dt><dd><p>
|
|
Name of the linker to use for linking systems including D sources.
|
|
</p><p>
|
|
Name of the linker to use for linking systems including D sources.
|
|
</p><p>
|
|
Name of the linker to use for linking systems including D sources.
|
|
</p></dd><dt><a name="cv-DLINKCOM"></a><span class="term">DLINKCOM</span></dt><dd><p>
|
|
The command line to use when linking systems including D sources.
|
|
</p><p>
|
|
The command line to use when linking systems including D sources.
|
|
</p><p>
|
|
The command line to use when linking systems including D sources.
|
|
</p></dd><dt><a name="cv-DLINKFLAGPREFIX"></a><span class="term">DLINKFLAGPREFIX</span></dt><dd><p>
|
|
DLINKFLAGPREFIX.
|
|
</p><p>
|
|
DLINKFLAGPREFIX.
|
|
</p><p>
|
|
DLINKFLAGPREFIX.
|
|
</p></dd><dt><a name="cv-DLINKFLAGS"></a><span class="term">DLINKFLAGS</span></dt><dd><p>
|
|
List of linker flags.
|
|
</p><p>
|
|
List of linker flags.
|
|
</p><p>
|
|
List of linker flags.
|
|
</p></dd><dt><a name="cv-DLINKFLAGSUFFIX"></a><span class="term">DLINKFLAGSUFFIX</span></dt><dd><p>
|
|
DLINKFLAGSUFFIX.
|
|
</p><p>
|
|
DLINKFLAGSUFFIX.
|
|
</p><p>
|
|
DLINKFLAGSUFFIX.
|
|
</p></dd><dt><a name="cv-DOCBOOK_DEFAULT_XSL_EPUB"></a><span class="term">DOCBOOK_DEFAULT_XSL_EPUB</span></dt><dd><p>
|
|
The default XSLT file for the <a class="link" href="#b-DocbookEpub"><code class="function">DocbookEpub</code></a> builder within the
|
|
current environment, if no other XSLT gets specified via keyword.
|
|
</p></dd><dt><a name="cv-DOCBOOK_DEFAULT_XSL_HTML"></a><span class="term">DOCBOOK_DEFAULT_XSL_HTML</span></dt><dd><p>
|
|
The default XSLT file for the <a class="link" href="#b-DocbookHtml"><code class="function">DocbookHtml</code></a> builder within the
|
|
current environment, if no other XSLT gets specified via keyword.
|
|
</p></dd><dt><a name="cv-DOCBOOK_DEFAULT_XSL_HTMLCHUNKED"></a><span class="term">DOCBOOK_DEFAULT_XSL_HTMLCHUNKED</span></dt><dd><p>
|
|
The default XSLT file for the <a class="link" href="#b-DocbookHtmlChunked"><code class="function">DocbookHtmlChunked</code></a> builder within the
|
|
current environment, if no other XSLT gets specified via keyword.
|
|
</p></dd><dt><a name="cv-DOCBOOK_DEFAULT_XSL_HTMLHELP"></a><span class="term">DOCBOOK_DEFAULT_XSL_HTMLHELP</span></dt><dd><p>
|
|
The default XSLT file for the <a class="link" href="#b-DocbookHtmlhelp"><code class="function">DocbookHtmlhelp</code></a> builder within the
|
|
current environment, if no other XSLT gets specified via keyword.
|
|
</p></dd><dt><a name="cv-DOCBOOK_DEFAULT_XSL_MAN"></a><span class="term">DOCBOOK_DEFAULT_XSL_MAN</span></dt><dd><p>
|
|
The default XSLT file for the <a class="link" href="#b-DocbookMan"><code class="function">DocbookMan</code></a> builder within the
|
|
current environment, if no other XSLT gets specified via keyword.
|
|
</p></dd><dt><a name="cv-DOCBOOK_DEFAULT_XSL_PDF"></a><span class="term">DOCBOOK_DEFAULT_XSL_PDF</span></dt><dd><p>
|
|
The default XSLT file for the <a class="link" href="#b-DocbookPdf"><code class="function">DocbookPdf</code></a> builder within the
|
|
current environment, if no other XSLT gets specified via keyword.
|
|
</p></dd><dt><a name="cv-DOCBOOK_DEFAULT_XSL_SLIDESHTML"></a><span class="term">DOCBOOK_DEFAULT_XSL_SLIDESHTML</span></dt><dd><p>
|
|
The default XSLT file for the <a class="link" href="#b-DocbookSlidesHtml"><code class="function">DocbookSlidesHtml</code></a> builder within the
|
|
current environment, if no other XSLT gets specified via keyword.
|
|
</p></dd><dt><a name="cv-DOCBOOK_DEFAULT_XSL_SLIDESPDF"></a><span class="term">DOCBOOK_DEFAULT_XSL_SLIDESPDF</span></dt><dd><p>
|
|
The default XSLT file for the <a class="link" href="#b-DocbookSlidesPdf"><code class="function">DocbookSlidesPdf</code></a> builder within the
|
|
current environment, if no other XSLT gets specified via keyword.
|
|
</p></dd><dt><a name="cv-DOCBOOK_FOP"></a><span class="term">DOCBOOK_FOP</span></dt><dd><p>
|
|
The path to the PDF renderer <code class="literal">fop</code> or <code class="literal">xep</code>,
|
|
if one of them is installed (<code class="literal">fop</code> gets checked first).
|
|
</p></dd><dt><a name="cv-DOCBOOK_FOPCOM"></a><span class="term">DOCBOOK_FOPCOM</span></dt><dd><p>
|
|
The full command-line for the
|
|
PDF renderer <code class="literal">fop</code> or <code class="literal">xep</code>.
|
|
</p></dd><dt><a name="cv-DOCBOOK_FOPCOMSTR"></a><span class="term">DOCBOOK_FOPCOMSTR</span></dt><dd><p>
|
|
The string displayed when a renderer like <code class="literal">fop</code> or
|
|
<code class="literal">xep</code> is used to create PDF output from an XML file.
|
|
</p></dd><dt><a name="cv-DOCBOOK_FOPFLAGS"></a><span class="term">DOCBOOK_FOPFLAGS</span></dt><dd><p>
|
|
Additonal command-line flags for the
|
|
PDF renderer <code class="literal">fop</code> or <code class="literal">xep</code>.
|
|
</p></dd><dt><a name="cv-DOCBOOK_XMLLINT"></a><span class="term">DOCBOOK_XMLLINT</span></dt><dd><p>
|
|
The path to the external executable <code class="literal">xmllint</code>, if it's installed.
|
|
Note, that this is only used as last fallback for resolving
|
|
XIncludes, if no libxml2 or lxml Python binding can be imported
|
|
in the current system.
|
|
</p></dd><dt><a name="cv-DOCBOOK_XMLLINTCOM"></a><span class="term">DOCBOOK_XMLLINTCOM</span></dt><dd><p>
|
|
The full command-line for the external executable
|
|
<code class="literal">xmllint</code>.
|
|
</p></dd><dt><a name="cv-DOCBOOK_XMLLINTCOMSTR"></a><span class="term">DOCBOOK_XMLLINTCOMSTR</span></dt><dd><p>
|
|
The string displayed when <code class="literal">xmllint</code> is used to resolve
|
|
XIncludes for a given XML file.
|
|
</p></dd><dt><a name="cv-DOCBOOK_XMLLINTFLAGS"></a><span class="term">DOCBOOK_XMLLINTFLAGS</span></dt><dd><p>
|
|
Additonal command-line flags for the external executable
|
|
<code class="literal">xmllint</code>.
|
|
</p></dd><dt><a name="cv-DOCBOOK_XSLTPROC"></a><span class="term">DOCBOOK_XSLTPROC</span></dt><dd><p>
|
|
The path to the external executable <code class="literal">xsltproc</code>
|
|
(or <code class="literal">saxon</code>, <code class="literal">xalan</code>), if one of them
|
|
is installed.
|
|
Note, that this is only used as last fallback for XSL transformations, if
|
|
no libxml2 or lxml Python binding can be imported in the current system.
|
|
</p></dd><dt><a name="cv-DOCBOOK_XSLTPROCCOM"></a><span class="term">DOCBOOK_XSLTPROCCOM</span></dt><dd><p>
|
|
The full command-line for the external executable
|
|
<code class="literal">xsltproc</code> (or <code class="literal">saxon</code>,
|
|
<code class="literal">xalan</code>).
|
|
</p></dd><dt><a name="cv-DOCBOOK_XSLTPROCCOMSTR"></a><span class="term">DOCBOOK_XSLTPROCCOMSTR</span></dt><dd><p>
|
|
The string displayed when <code class="literal">xsltproc</code> is used to transform
|
|
an XML file via a given XSLT stylesheet.
|
|
</p></dd><dt><a name="cv-DOCBOOK_XSLTPROCFLAGS"></a><span class="term">DOCBOOK_XSLTPROCFLAGS</span></dt><dd><p>
|
|
Additonal command-line flags for the external executable
|
|
<code class="literal">xsltproc</code> (or <code class="literal">saxon</code>,
|
|
<code class="literal">xalan</code>).
|
|
</p></dd><dt><a name="cv-DOCBOOK_XSLTPROCPARAMS"></a><span class="term">DOCBOOK_XSLTPROCPARAMS</span></dt><dd><p>
|
|
Additonal parameters that are not intended for the XSLT processor executable, but
|
|
the XSL processing itself. By default, they get appended at the end of the command line
|
|
for <code class="literal">saxon</code> and <code class="literal">saxon-xslt</code>, respectively.
|
|
</p></dd><dt><a name="cv-DPATH"></a><span class="term">DPATH</span></dt><dd><p>
|
|
List of paths to search for import modules.
|
|
</p><p>
|
|
List of paths to search for import modules.
|
|
</p><p>
|
|
List of paths to search for import modules.
|
|
</p></dd><dt><a name="cv-DRPATHPREFIX"></a><span class="term">DRPATHPREFIX</span></dt><dd><p>
|
|
DRPATHPREFIX.
|
|
</p></dd><dt><a name="cv-DRPATHSUFFIX"></a><span class="term">DRPATHSUFFIX</span></dt><dd><p>
|
|
DRPATHSUFFIX.
|
|
</p></dd><dt><a name="cv-DShLibSonameGenerator"></a><span class="term">DShLibSonameGenerator</span></dt><dd><p>
|
|
DShLibSonameGenerator.
|
|
</p></dd><dt><a name="cv-DSUFFIXES"></a><span class="term">DSUFFIXES</span></dt><dd><p>
|
|
The list of suffixes of files that will be scanned
|
|
for imported D package files.
|
|
The default list is:
|
|
</p><pre class="screen">
|
|
['.d']
|
|
</pre></dd><dt><a name="cv-DVERPREFIX"></a><span class="term">DVERPREFIX</span></dt><dd><p>
|
|
DVERPREFIX.
|
|
</p><p>
|
|
DVERPREFIX.
|
|
</p><p>
|
|
DVERPREFIX.
|
|
</p></dd><dt><a name="cv-DVERSIONS"></a><span class="term">DVERSIONS</span></dt><dd><p>
|
|
List of version tags to enable when compiling.
|
|
</p><p>
|
|
List of version tags to enable when compiling.
|
|
</p><p>
|
|
List of version tags to enable when compiling.
|
|
</p></dd><dt><a name="cv-DVERSUFFIX"></a><span class="term">DVERSUFFIX</span></dt><dd><p>
|
|
DVERSUFFIX.
|
|
</p><p>
|
|
DVERSUFFIX.
|
|
</p><p>
|
|
DVERSUFFIX.
|
|
</p></dd><dt><a name="cv-DVIPDF"></a><span class="term">DVIPDF</span></dt><dd><p>
|
|
The TeX DVI file to PDF file converter.
|
|
</p></dd><dt><a name="cv-DVIPDFCOM"></a><span class="term">DVIPDFCOM</span></dt><dd><p>
|
|
The command line used to convert TeX DVI files into a PDF file.
|
|
</p></dd><dt><a name="cv-DVIPDFCOMSTR"></a><span class="term">DVIPDFCOMSTR</span></dt><dd><p>
|
|
The string displayed when a TeX DVI file
|
|
is converted into a PDF file.
|
|
If this is not set, then <a class="link" href="#cv-DVIPDFCOM"><code class="envar">$DVIPDFCOM</code></a> (the command line) is displayed.
|
|
</p></dd><dt><a name="cv-DVIPDFFLAGS"></a><span class="term">DVIPDFFLAGS</span></dt><dd><p>
|
|
General options passed to the TeX DVI file to PDF file converter.
|
|
</p></dd><dt><a name="cv-DVIPS"></a><span class="term">DVIPS</span></dt><dd><p>
|
|
The TeX DVI file to PostScript converter.
|
|
</p></dd><dt><a name="cv-DVIPSFLAGS"></a><span class="term">DVIPSFLAGS</span></dt><dd><p>
|
|
General options passed to the TeX DVI file to PostScript converter.
|
|
</p></dd><dt><a name="cv-ENV"></a><span class="term">ENV</span></dt><dd><p>
|
|
A dictionary of environment variables
|
|
to use when invoking commands. When
|
|
<code class="envar">$ENV</code> is used in a command all list
|
|
values will be joined using the path separator and any other non-string
|
|
values will simply be coerced to a string.
|
|
Note that, by default,
|
|
<code class="filename">scons</code>
|
|
does
|
|
<span class="emphasis"><em>not</em></span>
|
|
propagate the environment in force when you
|
|
execute
|
|
<code class="filename">scons</code>
|
|
to the commands used to build target files.
|
|
This is so that builds will be guaranteed
|
|
repeatable regardless of the environment
|
|
variables set at the time
|
|
<code class="filename">scons</code>
|
|
is invoked.
|
|
</p><p>
|
|
If you want to propagate your
|
|
environment variables
|
|
to the commands executed
|
|
to build target files,
|
|
you must do so explicitly:
|
|
</p><pre class="screen">
|
|
import os
|
|
env = Environment(ENV = os.environ)
|
|
</pre><p>
|
|
Note that you can choose only to propagate
|
|
certain environment variables.
|
|
A common example is
|
|
the system
|
|
<code class="envar">PATH</code>
|
|
environment variable,
|
|
so that
|
|
<code class="filename">scons</code>
|
|
uses the same utilities
|
|
as the invoking shell (or other process):
|
|
</p><pre class="screen">
|
|
import os
|
|
env = Environment(ENV = {'PATH' : os.environ['PATH']})
|
|
</pre></dd><dt><a name="cv-ESCAPE"></a><span class="term">ESCAPE</span></dt><dd><p>
|
|
A function that will be called to escape shell special characters in
|
|
command lines. The function should take one argument: the command line
|
|
string to escape; and should return the escaped command line.
|
|
</p></dd><dt><a name="cv-F03"></a><span class="term">F03</span></dt><dd><p>
|
|
The Fortran 03 compiler.
|
|
You should normally set the <a class="link" href="#cv-FORTRAN"><code class="envar">$FORTRAN</code></a> variable,
|
|
which specifies the default Fortran compiler
|
|
for all Fortran versions.
|
|
You only need to set <a class="link" href="#cv-F03"><code class="envar">$F03</code></a> if you need to use a specific compiler
|
|
or compiler version for Fortran 03 files.
|
|
</p></dd><dt><a name="cv-F03COM"></a><span class="term">F03COM</span></dt><dd><p>
|
|
The command line used to compile a Fortran 03 source file to an object file.
|
|
You only need to set <a class="link" href="#cv-F03COM"><code class="envar">$F03COM</code></a> if you need to use a specific
|
|
command line for Fortran 03 files.
|
|
You should normally set the <a class="link" href="#cv-FORTRANCOM"><code class="envar">$FORTRANCOM</code></a> variable,
|
|
which specifies the default command line
|
|
for all Fortran versions.
|
|
</p></dd><dt><a name="cv-F03COMSTR"></a><span class="term">F03COMSTR</span></dt><dd><p>
|
|
The string displayed when a Fortran 03 source file
|
|
is compiled to an object file.
|
|
If this is not set, then <a class="link" href="#cv-F03COM"><code class="envar">$F03COM</code></a> or <a class="link" href="#cv-FORTRANCOM"><code class="envar">$FORTRANCOM</code></a>
|
|
(the command line) is displayed.
|
|
</p></dd><dt><a name="cv-F03FILESUFFIXES"></a><span class="term">F03FILESUFFIXES</span></dt><dd><p>
|
|
The list of file extensions for which the F03 dialect will be used. By
|
|
default, this is ['.f03']
|
|
</p></dd><dt><a name="cv-F03FLAGS"></a><span class="term">F03FLAGS</span></dt><dd><p>
|
|
General user-specified options that are passed to the Fortran 03 compiler.
|
|
Note that this variable does
|
|
<span class="emphasis"><em>not</em></span>
|
|
contain
|
|
<code class="option">-I</code>
|
|
(or similar) include search path options
|
|
that scons generates automatically from <a class="link" href="#cv-F03PATH"><code class="envar">$F03PATH</code></a>.
|
|
See
|
|
<a class="link" href="#cv-_F03INCFLAGS"><code class="envar">$_F03INCFLAGS</code></a>
|
|
below,
|
|
for the variable that expands to those options.
|
|
You only need to set <a class="link" href="#cv-F03FLAGS"><code class="envar">$F03FLAGS</code></a> if you need to define specific
|
|
user options for Fortran 03 files.
|
|
You should normally set the <a class="link" href="#cv-FORTRANFLAGS"><code class="envar">$FORTRANFLAGS</code></a> variable,
|
|
which specifies the user-specified options
|
|
passed to the default Fortran compiler
|
|
for all Fortran versions.
|
|
</p></dd><dt><a name="cv-_F03INCFLAGS"></a><span class="term">_F03INCFLAGS</span></dt><dd><p>
|
|
An automatically-generated construction variable
|
|
containing the Fortran 03 compiler command-line options
|
|
for specifying directories to be searched for include files.
|
|
The value of <a class="link" href="#cv-_F03INCFLAGS"><code class="envar">$_F03INCFLAGS</code></a> is created
|
|
by appending <a class="link" href="#cv-INCPREFIX"><code class="envar">$INCPREFIX</code></a> and <a class="link" href="#cv-INCSUFFIX"><code class="envar">$INCSUFFIX</code></a>
|
|
to the beginning and end
|
|
of each directory in <a class="link" href="#cv-F03PATH"><code class="envar">$F03PATH</code></a>.
|
|
</p></dd><dt><a name="cv-F03PATH"></a><span class="term">F03PATH</span></dt><dd><p>
|
|
The list of directories that the Fortran 03 compiler will search for include
|
|
directories. The implicit dependency scanner will search these
|
|
directories for include files. Don't explicitly put include directory
|
|
arguments in <a class="link" href="#cv-F03FLAGS"><code class="envar">$F03FLAGS</code></a> because the result will be non-portable
|
|
and the directories will not be searched by the dependency scanner. Note:
|
|
directory names in <a class="link" href="#cv-F03PATH"><code class="envar">$F03PATH</code></a> will be looked-up relative to the SConscript
|
|
directory when they are used in a command. To force
|
|
<code class="filename">scons</code>
|
|
to look-up a directory relative to the root of the source tree use #:
|
|
You only need to set <a class="link" href="#cv-F03PATH"><code class="envar">$F03PATH</code></a> if you need to define a specific
|
|
include path for Fortran 03 files.
|
|
You should normally set the <a class="link" href="#cv-FORTRANPATH"><code class="envar">$FORTRANPATH</code></a> variable,
|
|
which specifies the include path
|
|
for the default Fortran compiler
|
|
for all Fortran versions.
|
|
</p><pre class="screen">
|
|
env = Environment(F03PATH='#/include')
|
|
</pre><p>
|
|
The directory look-up can also be forced using the
|
|
<code class="function">Dir</code>()
|
|
function:
|
|
</p><pre class="screen">
|
|
include = Dir('include')
|
|
env = Environment(F03PATH=include)
|
|
</pre><p>
|
|
The directory list will be added to command lines
|
|
through the automatically-generated
|
|
<a class="link" href="#cv-_F03INCFLAGS"><code class="envar">$_F03INCFLAGS</code></a>
|
|
construction variable,
|
|
which is constructed by
|
|
appending the values of the
|
|
<a class="link" href="#cv-INCPREFIX"><code class="envar">$INCPREFIX</code></a> and <a class="link" href="#cv-INCSUFFIX"><code class="envar">$INCSUFFIX</code></a>
|
|
construction variables
|
|
to the beginning and end
|
|
of each directory in <a class="link" href="#cv-F03PATH"><code class="envar">$F03PATH</code></a>.
|
|
Any command lines you define that need
|
|
the F03PATH directory list should
|
|
include <a class="link" href="#cv-_F03INCFLAGS"><code class="envar">$_F03INCFLAGS</code></a>:
|
|
</p><pre class="screen">
|
|
env = Environment(F03COM="my_compiler $_F03INCFLAGS -c -o $TARGET $SOURCE")
|
|
</pre></dd><dt><a name="cv-F03PPCOM"></a><span class="term">F03PPCOM</span></dt><dd><p>
|
|
The command line used to compile a Fortran 03 source file to an object file
|
|
after first running the file through the C preprocessor.
|
|
Any options specified in the <a class="link" href="#cv-F03FLAGS"><code class="envar">$F03FLAGS</code></a> and <a class="link" href="#cv-CPPFLAGS"><code class="envar">$CPPFLAGS</code></a> construction variables
|
|
are included on this command line.
|
|
You only need to set <a class="link" href="#cv-F03PPCOM"><code class="envar">$F03PPCOM</code></a> if you need to use a specific
|
|
C-preprocessor command line for Fortran 03 files.
|
|
You should normally set the <a class="link" href="#cv-FORTRANPPCOM"><code class="envar">$FORTRANPPCOM</code></a> variable,
|
|
which specifies the default C-preprocessor command line
|
|
for all Fortran versions.
|
|
</p></dd><dt><a name="cv-F03PPCOMSTR"></a><span class="term">F03PPCOMSTR</span></dt><dd><p>
|
|
The string displayed when a Fortran 03 source file
|
|
is compiled to an object file
|
|
after first running the file through the C preprocessor.
|
|
If this is not set, then <a class="link" href="#cv-F03PPCOM"><code class="envar">$F03PPCOM</code></a> or <a class="link" href="#cv-FORTRANPPCOM"><code class="envar">$FORTRANPPCOM</code></a>
|
|
(the command line) is displayed.
|
|
</p></dd><dt><a name="cv-F03PPFILESUFFIXES"></a><span class="term">F03PPFILESUFFIXES</span></dt><dd><p>
|
|
The list of file extensions for which the compilation + preprocessor pass for
|
|
F03 dialect will be used. By default, this is empty
|
|
</p></dd><dt><a name="cv-F08"></a><span class="term">F08</span></dt><dd><p>
|
|
The Fortran 08 compiler.
|
|
You should normally set the <a class="link" href="#cv-FORTRAN"><code class="envar">$FORTRAN</code></a> variable,
|
|
which specifies the default Fortran compiler
|
|
for all Fortran versions.
|
|
You only need to set <a class="link" href="#cv-F08"><code class="envar">$F08</code></a> if you need to use a specific compiler
|
|
or compiler version for Fortran 08 files.
|
|
</p></dd><dt><a name="cv-F08COM"></a><span class="term">F08COM</span></dt><dd><p>
|
|
The command line used to compile a Fortran 08 source file to an object file.
|
|
You only need to set <a class="link" href="#cv-F08COM"><code class="envar">$F08COM</code></a> if you need to use a specific
|
|
command line for Fortran 08 files.
|
|
You should normally set the <a class="link" href="#cv-FORTRANCOM"><code class="envar">$FORTRANCOM</code></a> variable,
|
|
which specifies the default command line
|
|
for all Fortran versions.
|
|
</p></dd><dt><a name="cv-F08COMSTR"></a><span class="term">F08COMSTR</span></dt><dd><p>
|
|
The string displayed when a Fortran 08 source file
|
|
is compiled to an object file.
|
|
If this is not set, then <a class="link" href="#cv-F08COM"><code class="envar">$F08COM</code></a> or <a class="link" href="#cv-FORTRANCOM"><code class="envar">$FORTRANCOM</code></a>
|
|
(the command line) is displayed.
|
|
</p></dd><dt><a name="cv-F08FILESUFFIXES"></a><span class="term">F08FILESUFFIXES</span></dt><dd><p>
|
|
The list of file extensions for which the F08 dialect will be used. By
|
|
default, this is ['.f08']
|
|
</p></dd><dt><a name="cv-F08FLAGS"></a><span class="term">F08FLAGS</span></dt><dd><p>
|
|
General user-specified options that are passed to the Fortran 08 compiler.
|
|
Note that this variable does
|
|
<span class="emphasis"><em>not</em></span>
|
|
contain
|
|
<code class="option">-I</code>
|
|
(or similar) include search path options
|
|
that scons generates automatically from <a class="link" href="#cv-F08PATH"><code class="envar">$F08PATH</code></a>.
|
|
See
|
|
<a class="link" href="#cv-_F08INCFLAGS"><code class="envar">$_F08INCFLAGS</code></a>
|
|
below,
|
|
for the variable that expands to those options.
|
|
You only need to set <a class="link" href="#cv-F08FLAGS"><code class="envar">$F08FLAGS</code></a> if you need to define specific
|
|
user options for Fortran 08 files.
|
|
You should normally set the <a class="link" href="#cv-FORTRANFLAGS"><code class="envar">$FORTRANFLAGS</code></a> variable,
|
|
which specifies the user-specified options
|
|
passed to the default Fortran compiler
|
|
for all Fortran versions.
|
|
</p></dd><dt><a name="cv-_F08INCFLAGS"></a><span class="term">_F08INCFLAGS</span></dt><dd><p>
|
|
An automatically-generated construction variable
|
|
containing the Fortran 08 compiler command-line options
|
|
for specifying directories to be searched for include files.
|
|
The value of <a class="link" href="#cv-_F08INCFLAGS"><code class="envar">$_F08INCFLAGS</code></a> is created
|
|
by appending <a class="link" href="#cv-INCPREFIX"><code class="envar">$INCPREFIX</code></a> and <a class="link" href="#cv-INCSUFFIX"><code class="envar">$INCSUFFIX</code></a>
|
|
to the beginning and end
|
|
of each directory in <a class="link" href="#cv-F08PATH"><code class="envar">$F08PATH</code></a>.
|
|
</p></dd><dt><a name="cv-F08PATH"></a><span class="term">F08PATH</span></dt><dd><p>
|
|
The list of directories that the Fortran 08 compiler will search for include
|
|
directories. The implicit dependency scanner will search these
|
|
directories for include files. Don't explicitly put include directory
|
|
arguments in <a class="link" href="#cv-F08FLAGS"><code class="envar">$F08FLAGS</code></a> because the result will be non-portable
|
|
and the directories will not be searched by the dependency scanner. Note:
|
|
directory names in <a class="link" href="#cv-F08PATH"><code class="envar">$F08PATH</code></a> will be looked-up relative to the SConscript
|
|
directory when they are used in a command. To force
|
|
<code class="filename">scons</code>
|
|
to look-up a directory relative to the root of the source tree use #:
|
|
You only need to set <a class="link" href="#cv-F08PATH"><code class="envar">$F08PATH</code></a> if you need to define a specific
|
|
include path for Fortran 08 files.
|
|
You should normally set the <a class="link" href="#cv-FORTRANPATH"><code class="envar">$FORTRANPATH</code></a> variable,
|
|
which specifies the include path
|
|
for the default Fortran compiler
|
|
for all Fortran versions.
|
|
</p><pre class="screen">
|
|
env = Environment(F08PATH='#/include')
|
|
</pre><p>
|
|
The directory look-up can also be forced using the
|
|
<code class="function">Dir</code>()
|
|
function:
|
|
</p><pre class="screen">
|
|
include = Dir('include')
|
|
env = Environment(F08PATH=include)
|
|
</pre><p>
|
|
The directory list will be added to command lines
|
|
through the automatically-generated
|
|
<a class="link" href="#cv-_F08INCFLAGS"><code class="envar">$_F08INCFLAGS</code></a>
|
|
construction variable,
|
|
which is constructed by
|
|
appending the values of the
|
|
<a class="link" href="#cv-INCPREFIX"><code class="envar">$INCPREFIX</code></a> and <a class="link" href="#cv-INCSUFFIX"><code class="envar">$INCSUFFIX</code></a>
|
|
construction variables
|
|
to the beginning and end
|
|
of each directory in <a class="link" href="#cv-F08PATH"><code class="envar">$F08PATH</code></a>.
|
|
Any command lines you define that need
|
|
the F08PATH directory list should
|
|
include <a class="link" href="#cv-_F08INCFLAGS"><code class="envar">$_F08INCFLAGS</code></a>:
|
|
</p><pre class="screen">
|
|
env = Environment(F08COM="my_compiler $_F08INCFLAGS -c -o $TARGET $SOURCE")
|
|
</pre></dd><dt><a name="cv-F08PPCOM"></a><span class="term">F08PPCOM</span></dt><dd><p>
|
|
The command line used to compile a Fortran 08 source file to an object file
|
|
after first running the file through the C preprocessor.
|
|
Any options specified in the <a class="link" href="#cv-F08FLAGS"><code class="envar">$F08FLAGS</code></a> and <a class="link" href="#cv-CPPFLAGS"><code class="envar">$CPPFLAGS</code></a> construction variables
|
|
are included on this command line.
|
|
You only need to set <a class="link" href="#cv-F08PPCOM"><code class="envar">$F08PPCOM</code></a> if you need to use a specific
|
|
C-preprocessor command line for Fortran 08 files.
|
|
You should normally set the <a class="link" href="#cv-FORTRANPPCOM"><code class="envar">$FORTRANPPCOM</code></a> variable,
|
|
which specifies the default C-preprocessor command line
|
|
for all Fortran versions.
|
|
</p></dd><dt><a name="cv-F08PPCOMSTR"></a><span class="term">F08PPCOMSTR</span></dt><dd><p>
|
|
The string displayed when a Fortran 08 source file
|
|
is compiled to an object file
|
|
after first running the file through the C preprocessor.
|
|
If this is not set, then <a class="link" href="#cv-F08PPCOM"><code class="envar">$F08PPCOM</code></a> or <a class="link" href="#cv-FORTRANPPCOM"><code class="envar">$FORTRANPPCOM</code></a>
|
|
(the command line) is displayed.
|
|
</p></dd><dt><a name="cv-F08PPFILESUFFIXES"></a><span class="term">F08PPFILESUFFIXES</span></dt><dd><p>
|
|
The list of file extensions for which the compilation + preprocessor pass for
|
|
F08 dialect will be used. By default, this is empty
|
|
</p></dd><dt><a name="cv-F77"></a><span class="term">F77</span></dt><dd><p>
|
|
The Fortran 77 compiler.
|
|
You should normally set the <a class="link" href="#cv-FORTRAN"><code class="envar">$FORTRAN</code></a> variable,
|
|
which specifies the default Fortran compiler
|
|
for all Fortran versions.
|
|
You only need to set <a class="link" href="#cv-F77"><code class="envar">$F77</code></a> if you need to use a specific compiler
|
|
or compiler version for Fortran 77 files.
|
|
</p></dd><dt><a name="cv-F77COM"></a><span class="term">F77COM</span></dt><dd><p>
|
|
The command line used to compile a Fortran 77 source file to an object file.
|
|
You only need to set <a class="link" href="#cv-F77COM"><code class="envar">$F77COM</code></a> if you need to use a specific
|
|
command line for Fortran 77 files.
|
|
You should normally set the <a class="link" href="#cv-FORTRANCOM"><code class="envar">$FORTRANCOM</code></a> variable,
|
|
which specifies the default command line
|
|
for all Fortran versions.
|
|
</p></dd><dt><a name="cv-F77COMSTR"></a><span class="term">F77COMSTR</span></dt><dd><p>
|
|
The string displayed when a Fortran 77 source file
|
|
is compiled to an object file.
|
|
If this is not set, then <a class="link" href="#cv-F77COM"><code class="envar">$F77COM</code></a> or <a class="link" href="#cv-FORTRANCOM"><code class="envar">$FORTRANCOM</code></a>
|
|
(the command line) is displayed.
|
|
</p></dd><dt><a name="cv-F77FILESUFFIXES"></a><span class="term">F77FILESUFFIXES</span></dt><dd><p>
|
|
The list of file extensions for which the F77 dialect will be used. By
|
|
default, this is ['.f77']
|
|
</p></dd><dt><a name="cv-F77FLAGS"></a><span class="term">F77FLAGS</span></dt><dd><p>
|
|
General user-specified options that are passed to the Fortran 77 compiler.
|
|
Note that this variable does
|
|
<span class="emphasis"><em>not</em></span>
|
|
contain
|
|
<code class="option">-I</code>
|
|
(or similar) include search path options
|
|
that scons generates automatically from <a class="link" href="#cv-F77PATH"><code class="envar">$F77PATH</code></a>.
|
|
See
|
|
<a class="link" href="#cv-_F77INCFLAGS"><code class="envar">$_F77INCFLAGS</code></a>
|
|
below,
|
|
for the variable that expands to those options.
|
|
You only need to set <a class="link" href="#cv-F77FLAGS"><code class="envar">$F77FLAGS</code></a> if you need to define specific
|
|
user options for Fortran 77 files.
|
|
You should normally set the <a class="link" href="#cv-FORTRANFLAGS"><code class="envar">$FORTRANFLAGS</code></a> variable,
|
|
which specifies the user-specified options
|
|
passed to the default Fortran compiler
|
|
for all Fortran versions.
|
|
</p></dd><dt><a name="cv-_F77INCFLAGS"></a><span class="term">_F77INCFLAGS</span></dt><dd><p>
|
|
An automatically-generated construction variable
|
|
containing the Fortran 77 compiler command-line options
|
|
for specifying directories to be searched for include files.
|
|
The value of <a class="link" href="#cv-_F77INCFLAGS"><code class="envar">$_F77INCFLAGS</code></a> is created
|
|
by appending <a class="link" href="#cv-INCPREFIX"><code class="envar">$INCPREFIX</code></a> and <a class="link" href="#cv-INCSUFFIX"><code class="envar">$INCSUFFIX</code></a>
|
|
to the beginning and end
|
|
of each directory in <a class="link" href="#cv-F77PATH"><code class="envar">$F77PATH</code></a>.
|
|
</p></dd><dt><a name="cv-F77PATH"></a><span class="term">F77PATH</span></dt><dd><p>
|
|
The list of directories that the Fortran 77 compiler will search for include
|
|
directories. The implicit dependency scanner will search these
|
|
directories for include files. Don't explicitly put include directory
|
|
arguments in <a class="link" href="#cv-F77FLAGS"><code class="envar">$F77FLAGS</code></a> because the result will be non-portable
|
|
and the directories will not be searched by the dependency scanner. Note:
|
|
directory names in <a class="link" href="#cv-F77PATH"><code class="envar">$F77PATH</code></a> will be looked-up relative to the SConscript
|
|
directory when they are used in a command. To force
|
|
<code class="filename">scons</code>
|
|
to look-up a directory relative to the root of the source tree use #:
|
|
You only need to set <a class="link" href="#cv-F77PATH"><code class="envar">$F77PATH</code></a> if you need to define a specific
|
|
include path for Fortran 77 files.
|
|
You should normally set the <a class="link" href="#cv-FORTRANPATH"><code class="envar">$FORTRANPATH</code></a> variable,
|
|
which specifies the include path
|
|
for the default Fortran compiler
|
|
for all Fortran versions.
|
|
</p><pre class="screen">
|
|
env = Environment(F77PATH='#/include')
|
|
</pre><p>
|
|
The directory look-up can also be forced using the
|
|
<code class="function">Dir</code>()
|
|
function:
|
|
</p><pre class="screen">
|
|
include = Dir('include')
|
|
env = Environment(F77PATH=include)
|
|
</pre><p>
|
|
The directory list will be added to command lines
|
|
through the automatically-generated
|
|
<a class="link" href="#cv-_F77INCFLAGS"><code class="envar">$_F77INCFLAGS</code></a>
|
|
construction variable,
|
|
which is constructed by
|
|
appending the values of the
|
|
<a class="link" href="#cv-INCPREFIX"><code class="envar">$INCPREFIX</code></a> and <a class="link" href="#cv-INCSUFFIX"><code class="envar">$INCSUFFIX</code></a>
|
|
construction variables
|
|
to the beginning and end
|
|
of each directory in <a class="link" href="#cv-F77PATH"><code class="envar">$F77PATH</code></a>.
|
|
Any command lines you define that need
|
|
the F77PATH directory list should
|
|
include <a class="link" href="#cv-_F77INCFLAGS"><code class="envar">$_F77INCFLAGS</code></a>:
|
|
</p><pre class="screen">
|
|
env = Environment(F77COM="my_compiler $_F77INCFLAGS -c -o $TARGET $SOURCE")
|
|
</pre></dd><dt><a name="cv-F77PPCOM"></a><span class="term">F77PPCOM</span></dt><dd><p>
|
|
The command line used to compile a Fortran 77 source file to an object file
|
|
after first running the file through the C preprocessor.
|
|
Any options specified in the <a class="link" href="#cv-F77FLAGS"><code class="envar">$F77FLAGS</code></a> and <a class="link" href="#cv-CPPFLAGS"><code class="envar">$CPPFLAGS</code></a> construction variables
|
|
are included on this command line.
|
|
You only need to set <a class="link" href="#cv-F77PPCOM"><code class="envar">$F77PPCOM</code></a> if you need to use a specific
|
|
C-preprocessor command line for Fortran 77 files.
|
|
You should normally set the <a class="link" href="#cv-FORTRANPPCOM"><code class="envar">$FORTRANPPCOM</code></a> variable,
|
|
which specifies the default C-preprocessor command line
|
|
for all Fortran versions.
|
|
</p></dd><dt><a name="cv-F77PPCOMSTR"></a><span class="term">F77PPCOMSTR</span></dt><dd><p>
|
|
The string displayed when a Fortran 77 source file
|
|
is compiled to an object file
|
|
after first running the file through the C preprocessor.
|
|
If this is not set, then <a class="link" href="#cv-F77PPCOM"><code class="envar">$F77PPCOM</code></a> or <a class="link" href="#cv-FORTRANPPCOM"><code class="envar">$FORTRANPPCOM</code></a>
|
|
(the command line) is displayed.
|
|
</p></dd><dt><a name="cv-F77PPFILESUFFIXES"></a><span class="term">F77PPFILESUFFIXES</span></dt><dd><p>
|
|
The list of file extensions for which the compilation + preprocessor pass for
|
|
F77 dialect will be used. By default, this is empty
|
|
</p></dd><dt><a name="cv-F90"></a><span class="term">F90</span></dt><dd><p>
|
|
The Fortran 90 compiler.
|
|
You should normally set the <a class="link" href="#cv-FORTRAN"><code class="envar">$FORTRAN</code></a> variable,
|
|
which specifies the default Fortran compiler
|
|
for all Fortran versions.
|
|
You only need to set <a class="link" href="#cv-F90"><code class="envar">$F90</code></a> if you need to use a specific compiler
|
|
or compiler version for Fortran 90 files.
|
|
</p></dd><dt><a name="cv-F90COM"></a><span class="term">F90COM</span></dt><dd><p>
|
|
The command line used to compile a Fortran 90 source file to an object file.
|
|
You only need to set <a class="link" href="#cv-F90COM"><code class="envar">$F90COM</code></a> if you need to use a specific
|
|
command line for Fortran 90 files.
|
|
You should normally set the <a class="link" href="#cv-FORTRANCOM"><code class="envar">$FORTRANCOM</code></a> variable,
|
|
which specifies the default command line
|
|
for all Fortran versions.
|
|
</p></dd><dt><a name="cv-F90COMSTR"></a><span class="term">F90COMSTR</span></dt><dd><p>
|
|
The string displayed when a Fortran 90 source file
|
|
is compiled to an object file.
|
|
If this is not set, then <a class="link" href="#cv-F90COM"><code class="envar">$F90COM</code></a> or <a class="link" href="#cv-FORTRANCOM"><code class="envar">$FORTRANCOM</code></a>
|
|
(the command line) is displayed.
|
|
</p></dd><dt><a name="cv-F90FILESUFFIXES"></a><span class="term">F90FILESUFFIXES</span></dt><dd><p>
|
|
The list of file extensions for which the F90 dialect will be used. By
|
|
default, this is ['.f90']
|
|
</p></dd><dt><a name="cv-F90FLAGS"></a><span class="term">F90FLAGS</span></dt><dd><p>
|
|
General user-specified options that are passed to the Fortran 90 compiler.
|
|
Note that this variable does
|
|
<span class="emphasis"><em>not</em></span>
|
|
contain
|
|
<code class="option">-I</code>
|
|
(or similar) include search path options
|
|
that scons generates automatically from <a class="link" href="#cv-F90PATH"><code class="envar">$F90PATH</code></a>.
|
|
See
|
|
<a class="link" href="#cv-_F90INCFLAGS"><code class="envar">$_F90INCFLAGS</code></a>
|
|
below,
|
|
for the variable that expands to those options.
|
|
You only need to set <a class="link" href="#cv-F90FLAGS"><code class="envar">$F90FLAGS</code></a> if you need to define specific
|
|
user options for Fortran 90 files.
|
|
You should normally set the <a class="link" href="#cv-FORTRANFLAGS"><code class="envar">$FORTRANFLAGS</code></a> variable,
|
|
which specifies the user-specified options
|
|
passed to the default Fortran compiler
|
|
for all Fortran versions.
|
|
</p></dd><dt><a name="cv-_F90INCFLAGS"></a><span class="term">_F90INCFLAGS</span></dt><dd><p>
|
|
An automatically-generated construction variable
|
|
containing the Fortran 90 compiler command-line options
|
|
for specifying directories to be searched for include files.
|
|
The value of <a class="link" href="#cv-_F90INCFLAGS"><code class="envar">$_F90INCFLAGS</code></a> is created
|
|
by appending <a class="link" href="#cv-INCPREFIX"><code class="envar">$INCPREFIX</code></a> and <a class="link" href="#cv-INCSUFFIX"><code class="envar">$INCSUFFIX</code></a>
|
|
to the beginning and end
|
|
of each directory in <a class="link" href="#cv-F90PATH"><code class="envar">$F90PATH</code></a>.
|
|
</p></dd><dt><a name="cv-F90PATH"></a><span class="term">F90PATH</span></dt><dd><p>
|
|
The list of directories that the Fortran 90 compiler will search for include
|
|
directories. The implicit dependency scanner will search these
|
|
directories for include files. Don't explicitly put include directory
|
|
arguments in <a class="link" href="#cv-F90FLAGS"><code class="envar">$F90FLAGS</code></a> because the result will be non-portable
|
|
and the directories will not be searched by the dependency scanner. Note:
|
|
directory names in <a class="link" href="#cv-F90PATH"><code class="envar">$F90PATH</code></a> will be looked-up relative to the SConscript
|
|
directory when they are used in a command. To force
|
|
<code class="filename">scons</code>
|
|
to look-up a directory relative to the root of the source tree use #:
|
|
You only need to set <a class="link" href="#cv-F90PATH"><code class="envar">$F90PATH</code></a> if you need to define a specific
|
|
include path for Fortran 90 files.
|
|
You should normally set the <a class="link" href="#cv-FORTRANPATH"><code class="envar">$FORTRANPATH</code></a> variable,
|
|
which specifies the include path
|
|
for the default Fortran compiler
|
|
for all Fortran versions.
|
|
</p><pre class="screen">
|
|
env = Environment(F90PATH='#/include')
|
|
</pre><p>
|
|
The directory look-up can also be forced using the
|
|
<code class="function">Dir</code>()
|
|
function:
|
|
</p><pre class="screen">
|
|
include = Dir('include')
|
|
env = Environment(F90PATH=include)
|
|
</pre><p>
|
|
The directory list will be added to command lines
|
|
through the automatically-generated
|
|
<a class="link" href="#cv-_F90INCFLAGS"><code class="envar">$_F90INCFLAGS</code></a>
|
|
construction variable,
|
|
which is constructed by
|
|
appending the values of the
|
|
<a class="link" href="#cv-INCPREFIX"><code class="envar">$INCPREFIX</code></a> and <a class="link" href="#cv-INCSUFFIX"><code class="envar">$INCSUFFIX</code></a>
|
|
construction variables
|
|
to the beginning and end
|
|
of each directory in <a class="link" href="#cv-F90PATH"><code class="envar">$F90PATH</code></a>.
|
|
Any command lines you define that need
|
|
the F90PATH directory list should
|
|
include <a class="link" href="#cv-_F90INCFLAGS"><code class="envar">$_F90INCFLAGS</code></a>:
|
|
</p><pre class="screen">
|
|
env = Environment(F90COM="my_compiler $_F90INCFLAGS -c -o $TARGET $SOURCE")
|
|
</pre></dd><dt><a name="cv-F90PPCOM"></a><span class="term">F90PPCOM</span></dt><dd><p>
|
|
The command line used to compile a Fortran 90 source file to an object file
|
|
after first running the file through the C preprocessor.
|
|
Any options specified in the <a class="link" href="#cv-F90FLAGS"><code class="envar">$F90FLAGS</code></a> and <a class="link" href="#cv-CPPFLAGS"><code class="envar">$CPPFLAGS</code></a> construction variables
|
|
are included on this command line.
|
|
You only need to set <a class="link" href="#cv-F90PPCOM"><code class="envar">$F90PPCOM</code></a> if you need to use a specific
|
|
C-preprocessor command line for Fortran 90 files.
|
|
You should normally set the <a class="link" href="#cv-FORTRANPPCOM"><code class="envar">$FORTRANPPCOM</code></a> variable,
|
|
which specifies the default C-preprocessor command line
|
|
for all Fortran versions.
|
|
</p></dd><dt><a name="cv-F90PPCOMSTR"></a><span class="term">F90PPCOMSTR</span></dt><dd><p>
|
|
The string displayed when a Fortran 90 source file
|
|
is compiled after first running the file through the C preprocessor.
|
|
If this is not set, then <a class="link" href="#cv-F90PPCOM"><code class="envar">$F90PPCOM</code></a> or <a class="link" href="#cv-FORTRANPPCOM"><code class="envar">$FORTRANPPCOM</code></a>
|
|
(the command line) is displayed.
|
|
</p></dd><dt><a name="cv-F90PPFILESUFFIXES"></a><span class="term">F90PPFILESUFFIXES</span></dt><dd><p>
|
|
The list of file extensions for which the compilation + preprocessor pass for
|
|
F90 dialect will be used. By default, this is empty
|
|
</p></dd><dt><a name="cv-F95"></a><span class="term">F95</span></dt><dd><p>
|
|
The Fortran 95 compiler.
|
|
You should normally set the <a class="link" href="#cv-FORTRAN"><code class="envar">$FORTRAN</code></a> variable,
|
|
which specifies the default Fortran compiler
|
|
for all Fortran versions.
|
|
You only need to set <a class="link" href="#cv-F95"><code class="envar">$F95</code></a> if you need to use a specific compiler
|
|
or compiler version for Fortran 95 files.
|
|
</p></dd><dt><a name="cv-F95COM"></a><span class="term">F95COM</span></dt><dd><p>
|
|
The command line used to compile a Fortran 95 source file to an object file.
|
|
You only need to set <a class="link" href="#cv-F95COM"><code class="envar">$F95COM</code></a> if you need to use a specific
|
|
command line for Fortran 95 files.
|
|
You should normally set the <a class="link" href="#cv-FORTRANCOM"><code class="envar">$FORTRANCOM</code></a> variable,
|
|
which specifies the default command line
|
|
for all Fortran versions.
|
|
</p></dd><dt><a name="cv-F95COMSTR"></a><span class="term">F95COMSTR</span></dt><dd><p>
|
|
The string displayed when a Fortran 95 source file
|
|
is compiled to an object file.
|
|
If this is not set, then <a class="link" href="#cv-F95COM"><code class="envar">$F95COM</code></a> or <a class="link" href="#cv-FORTRANCOM"><code class="envar">$FORTRANCOM</code></a>
|
|
(the command line) is displayed.
|
|
</p></dd><dt><a name="cv-F95FILESUFFIXES"></a><span class="term">F95FILESUFFIXES</span></dt><dd><p>
|
|
The list of file extensions for which the F95 dialect will be used. By
|
|
default, this is ['.f95']
|
|
</p></dd><dt><a name="cv-F95FLAGS"></a><span class="term">F95FLAGS</span></dt><dd><p>
|
|
General user-specified options that are passed to the Fortran 95 compiler.
|
|
Note that this variable does
|
|
<span class="emphasis"><em>not</em></span>
|
|
contain
|
|
<code class="option">-I</code>
|
|
(or similar) include search path options
|
|
that scons generates automatically from <a class="link" href="#cv-F95PATH"><code class="envar">$F95PATH</code></a>.
|
|
See
|
|
<a class="link" href="#cv-_F95INCFLAGS"><code class="envar">$_F95INCFLAGS</code></a>
|
|
below,
|
|
for the variable that expands to those options.
|
|
You only need to set <a class="link" href="#cv-F95FLAGS"><code class="envar">$F95FLAGS</code></a> if you need to define specific
|
|
user options for Fortran 95 files.
|
|
You should normally set the <a class="link" href="#cv-FORTRANFLAGS"><code class="envar">$FORTRANFLAGS</code></a> variable,
|
|
which specifies the user-specified options
|
|
passed to the default Fortran compiler
|
|
for all Fortran versions.
|
|
</p></dd><dt><a name="cv-_F95INCFLAGS"></a><span class="term">_F95INCFLAGS</span></dt><dd><p>
|
|
An automatically-generated construction variable
|
|
containing the Fortran 95 compiler command-line options
|
|
for specifying directories to be searched for include files.
|
|
The value of <a class="link" href="#cv-_F95INCFLAGS"><code class="envar">$_F95INCFLAGS</code></a> is created
|
|
by appending <a class="link" href="#cv-INCPREFIX"><code class="envar">$INCPREFIX</code></a> and <a class="link" href="#cv-INCSUFFIX"><code class="envar">$INCSUFFIX</code></a>
|
|
to the beginning and end
|
|
of each directory in <a class="link" href="#cv-F95PATH"><code class="envar">$F95PATH</code></a>.
|
|
</p></dd><dt><a name="cv-F95PATH"></a><span class="term">F95PATH</span></dt><dd><p>
|
|
The list of directories that the Fortran 95 compiler will search for include
|
|
directories. The implicit dependency scanner will search these
|
|
directories for include files. Don't explicitly put include directory
|
|
arguments in <a class="link" href="#cv-F95FLAGS"><code class="envar">$F95FLAGS</code></a> because the result will be non-portable
|
|
and the directories will not be searched by the dependency scanner. Note:
|
|
directory names in <a class="link" href="#cv-F95PATH"><code class="envar">$F95PATH</code></a> will be looked-up relative to the SConscript
|
|
directory when they are used in a command. To force
|
|
<code class="filename">scons</code>
|
|
to look-up a directory relative to the root of the source tree use #:
|
|
You only need to set <a class="link" href="#cv-F95PATH"><code class="envar">$F95PATH</code></a> if you need to define a specific
|
|
include path for Fortran 95 files.
|
|
You should normally set the <a class="link" href="#cv-FORTRANPATH"><code class="envar">$FORTRANPATH</code></a> variable,
|
|
which specifies the include path
|
|
for the default Fortran compiler
|
|
for all Fortran versions.
|
|
</p><pre class="screen">
|
|
env = Environment(F95PATH='#/include')
|
|
</pre><p>
|
|
The directory look-up can also be forced using the
|
|
<code class="function">Dir</code>()
|
|
function:
|
|
</p><pre class="screen">
|
|
include = Dir('include')
|
|
env = Environment(F95PATH=include)
|
|
</pre><p>
|
|
The directory list will be added to command lines
|
|
through the automatically-generated
|
|
<a class="link" href="#cv-_F95INCFLAGS"><code class="envar">$_F95INCFLAGS</code></a>
|
|
construction variable,
|
|
which is constructed by
|
|
appending the values of the
|
|
<a class="link" href="#cv-INCPREFIX"><code class="envar">$INCPREFIX</code></a> and <a class="link" href="#cv-INCSUFFIX"><code class="envar">$INCSUFFIX</code></a>
|
|
construction variables
|
|
to the beginning and end
|
|
of each directory in <a class="link" href="#cv-F95PATH"><code class="envar">$F95PATH</code></a>.
|
|
Any command lines you define that need
|
|
the F95PATH directory list should
|
|
include <a class="link" href="#cv-_F95INCFLAGS"><code class="envar">$_F95INCFLAGS</code></a>:
|
|
</p><pre class="screen">
|
|
env = Environment(F95COM="my_compiler $_F95INCFLAGS -c -o $TARGET $SOURCE")
|
|
</pre></dd><dt><a name="cv-F95PPCOM"></a><span class="term">F95PPCOM</span></dt><dd><p>
|
|
The command line used to compile a Fortran 95 source file to an object file
|
|
after first running the file through the C preprocessor.
|
|
Any options specified in the <a class="link" href="#cv-F95FLAGS"><code class="envar">$F95FLAGS</code></a> and <a class="link" href="#cv-CPPFLAGS"><code class="envar">$CPPFLAGS</code></a> construction variables
|
|
are included on this command line.
|
|
You only need to set <a class="link" href="#cv-F95PPCOM"><code class="envar">$F95PPCOM</code></a> if you need to use a specific
|
|
C-preprocessor command line for Fortran 95 files.
|
|
You should normally set the <a class="link" href="#cv-FORTRANPPCOM"><code class="envar">$FORTRANPPCOM</code></a> variable,
|
|
which specifies the default C-preprocessor command line
|
|
for all Fortran versions.
|
|
</p></dd><dt><a name="cv-F95PPCOMSTR"></a><span class="term">F95PPCOMSTR</span></dt><dd><p>
|
|
The string displayed when a Fortran 95 source file
|
|
is compiled to an object file
|
|
after first running the file through the C preprocessor.
|
|
If this is not set, then <a class="link" href="#cv-F95PPCOM"><code class="envar">$F95PPCOM</code></a> or <a class="link" href="#cv-FORTRANPPCOM"><code class="envar">$FORTRANPPCOM</code></a>
|
|
(the command line) is displayed.
|
|
</p></dd><dt><a name="cv-F95PPFILESUFFIXES"></a><span class="term">F95PPFILESUFFIXES</span></dt><dd><p>
|
|
The list of file extensions for which the compilation + preprocessor pass for
|
|
F95 dialect will be used. By default, this is empty
|
|
</p></dd><dt><a name="cv-File"></a><span class="term">File</span></dt><dd><p>
|
|
A function that converts a string into a File instance relative to the
|
|
target being built.
|
|
</p><p>
|
|
A function that converts a string into a File instance relative to the
|
|
target being built.
|
|
</p></dd><dt><a name="cv-FORTRAN"></a><span class="term">FORTRAN</span></dt><dd><p>
|
|
The default Fortran compiler
|
|
for all versions of Fortran.
|
|
</p></dd><dt><a name="cv-FORTRANCOM"></a><span class="term">FORTRANCOM</span></dt><dd><p>
|
|
The command line used to compile a Fortran source file to an object file.
|
|
By default, any options specified
|
|
in the <a class="link" href="#cv-FORTRANFLAGS"><code class="envar">$FORTRANFLAGS</code></a>,
|
|
<a class="link" href="#cv-CPPFLAGS"><code class="envar">$CPPFLAGS</code></a>,
|
|
<a class="link" href="#cv-_CPPDEFFLAGS"><code class="envar">$_CPPDEFFLAGS</code></a>,
|
|
<a class="link" href="#cv-_FORTRANMODFLAG"><code class="envar">$_FORTRANMODFLAG</code></a>, and
|
|
<a class="link" href="#cv-_FORTRANINCFLAGS"><code class="envar">$_FORTRANINCFLAGS</code></a> construction variables
|
|
are included on this command line.
|
|
</p></dd><dt><a name="cv-FORTRANCOMSTR"></a><span class="term">FORTRANCOMSTR</span></dt><dd><p>
|
|
The string displayed when a Fortran source file
|
|
is compiled to an object file.
|
|
If this is not set, then <a class="link" href="#cv-FORTRANCOM"><code class="envar">$FORTRANCOM</code></a>
|
|
(the command line) is displayed.
|
|
</p></dd><dt><a name="cv-FORTRANFILESUFFIXES"></a><span class="term">FORTRANFILESUFFIXES</span></dt><dd><p>
|
|
The list of file extensions for which the FORTRAN dialect will be used. By
|
|
default, this is ['.f', '.for', '.ftn']
|
|
</p></dd><dt><a name="cv-FORTRANFLAGS"></a><span class="term">FORTRANFLAGS</span></dt><dd><p>
|
|
General user-specified options that are passed to the Fortran compiler.
|
|
Note that this variable does
|
|
<span class="emphasis"><em>not</em></span>
|
|
contain
|
|
<code class="option">-I</code>
|
|
(or similar) include or module search path options
|
|
that scons generates automatically from <a class="link" href="#cv-FORTRANPATH"><code class="envar">$FORTRANPATH</code></a>.
|
|
See
|
|
<a class="link" href="#cv-_FORTRANINCFLAGS"><code class="envar">$_FORTRANINCFLAGS</code></a> and <a class="link" href="#cv-_FORTRANMODFLAG"><code class="envar">$_FORTRANMODFLAG</code></a>,
|
|
below,
|
|
for the variables that expand those options.
|
|
</p></dd><dt><a name="cv-_FORTRANINCFLAGS"></a><span class="term">_FORTRANINCFLAGS</span></dt><dd><p>
|
|
An automatically-generated construction variable
|
|
containing the Fortran compiler command-line options
|
|
for specifying directories to be searched for include
|
|
files and module files.
|
|
The value of <a class="link" href="#cv-_FORTRANINCFLAGS"><code class="envar">$_FORTRANINCFLAGS</code></a> is created
|
|
by respectively prepending and appending
|
|
<a class="link" href="#cv-INCPREFIX"><code class="envar">$INCPREFIX</code></a> and <a class="link" href="#cv-INCSUFFIX"><code class="envar">$INCSUFFIX</code></a>
|
|
to the beginning and end
|
|
of each directory in <a class="link" href="#cv-FORTRANPATH"><code class="envar">$FORTRANPATH</code></a>.
|
|
</p></dd><dt><a name="cv-FORTRANMODDIR"></a><span class="term">FORTRANMODDIR</span></dt><dd><p>
|
|
Directory location where the Fortran compiler should place
|
|
any module files it generates. This variable is empty, by default. Some
|
|
Fortran compilers will internally append this directory in the search path
|
|
for module files, as well.
|
|
</p></dd><dt><a name="cv-FORTRANMODDIRPREFIX"></a><span class="term">FORTRANMODDIRPREFIX</span></dt><dd><p>
|
|
The prefix used to specify a module directory on the Fortran compiler command
|
|
line.
|
|
This will be prepended to the beginning of the directory
|
|
in the <a class="link" href="#cv-FORTRANMODDIR"><code class="envar">$FORTRANMODDIR</code></a> construction variables
|
|
when the <a class="link" href="#cv-_FORTRANMODFLAG"><code class="envar">$_FORTRANMODFLAG</code></a> variables is automatically generated.
|
|
</p></dd><dt><a name="cv-FORTRANMODDIRSUFFIX"></a><span class="term">FORTRANMODDIRSUFFIX</span></dt><dd><p>
|
|
The suffix used to specify a module directory on the Fortran compiler command
|
|
line.
|
|
This will be appended to the end of the directory
|
|
in the <a class="link" href="#cv-FORTRANMODDIR"><code class="envar">$FORTRANMODDIR</code></a> construction variables
|
|
when the <a class="link" href="#cv-_FORTRANMODFLAG"><code class="envar">$_FORTRANMODFLAG</code></a> variables is automatically generated.
|
|
</p></dd><dt><a name="cv-_FORTRANMODFLAG"></a><span class="term">_FORTRANMODFLAG</span></dt><dd><p>
|
|
An automatically-generated construction variable
|
|
containing the Fortran compiler command-line option
|
|
for specifying the directory location where the Fortran
|
|
compiler should place any module files that happen to get
|
|
generated during compilation.
|
|
The value of <a class="link" href="#cv-_FORTRANMODFLAG"><code class="envar">$_FORTRANMODFLAG</code></a> is created
|
|
by respectively prepending and appending
|
|
<a class="link" href="#cv-FORTRANMODDIRPREFIX"><code class="envar">$FORTRANMODDIRPREFIX</code></a> and <a class="link" href="#cv-FORTRANMODDIRSUFFIX"><code class="envar">$FORTRANMODDIRSUFFIX</code></a>
|
|
to the beginning and end of the directory in <a class="link" href="#cv-FORTRANMODDIR"><code class="envar">$FORTRANMODDIR</code></a>.
|
|
</p></dd><dt><a name="cv-FORTRANMODPREFIX"></a><span class="term">FORTRANMODPREFIX</span></dt><dd><p>
|
|
The module file prefix used by the Fortran compiler. SCons assumes that
|
|
the Fortran compiler follows the quasi-standard naming convention for
|
|
module files of
|
|
<code class="filename">module_name.mod</code>.
|
|
As a result, this variable is left empty, by default. For situations in
|
|
which the compiler does not necessarily follow the normal convention,
|
|
the user may use this variable. Its value will be appended to every
|
|
module file name as scons attempts to resolve dependencies.
|
|
</p></dd><dt><a name="cv-FORTRANMODSUFFIX"></a><span class="term">FORTRANMODSUFFIX</span></dt><dd><p>
|
|
The module file suffix used by the Fortran compiler. SCons assumes that
|
|
the Fortran compiler follows the quasi-standard naming convention for
|
|
module files of
|
|
<code class="filename">module_name.mod</code>.
|
|
As a result, this variable is set to ".mod", by default. For situations
|
|
in which the compiler does not necessarily follow the normal convention,
|
|
the user may use this variable. Its value will be appended to every
|
|
module file name as scons attempts to resolve dependencies.
|
|
</p></dd><dt><a name="cv-FORTRANPATH"></a><span class="term">FORTRANPATH</span></dt><dd><p>
|
|
The list of directories that the Fortran compiler will search for
|
|
include files and (for some compilers) module files. The Fortran implicit
|
|
dependency scanner will search these directories for include files (but
|
|
not module files since they are autogenerated and, as such, may not
|
|
actually exist at the time the scan takes place). Don't explicitly put
|
|
include directory arguments in FORTRANFLAGS because the result will be
|
|
non-portable and the directories will not be searched by the dependency
|
|
scanner. Note: directory names in FORTRANPATH will be looked-up relative
|
|
to the SConscript directory when they are used in a command. To force
|
|
<code class="filename">scons</code>
|
|
to look-up a directory relative to the root of the source tree use #:
|
|
</p><pre class="screen">
|
|
env = Environment(FORTRANPATH='#/include')
|
|
</pre><p>
|
|
The directory look-up can also be forced using the
|
|
<code class="function">Dir</code>()
|
|
function:
|
|
</p><pre class="screen">
|
|
include = Dir('include')
|
|
env = Environment(FORTRANPATH=include)
|
|
</pre><p>
|
|
The directory list will be added to command lines
|
|
through the automatically-generated
|
|
<a class="link" href="#cv-_FORTRANINCFLAGS"><code class="envar">$_FORTRANINCFLAGS</code></a>
|
|
construction variable,
|
|
which is constructed by
|
|
respectively prepending and appending the values of the
|
|
<a class="link" href="#cv-INCPREFIX"><code class="envar">$INCPREFIX</code></a> and <a class="link" href="#cv-INCSUFFIX"><code class="envar">$INCSUFFIX</code></a>
|
|
construction variables
|
|
to the beginning and end
|
|
of each directory in <a class="link" href="#cv-FORTRANPATH"><code class="envar">$FORTRANPATH</code></a>.
|
|
Any command lines you define that need
|
|
the FORTRANPATH directory list should
|
|
include <a class="link" href="#cv-_FORTRANINCFLAGS"><code class="envar">$_FORTRANINCFLAGS</code></a>:
|
|
</p><pre class="screen">
|
|
env = Environment(FORTRANCOM="my_compiler $_FORTRANINCFLAGS -c -o $TARGET $SOURCE")
|
|
</pre></dd><dt><a name="cv-FORTRANPPCOM"></a><span class="term">FORTRANPPCOM</span></dt><dd><p>
|
|
The command line used to compile a Fortran source file to an object file
|
|
after first running the file through the C preprocessor.
|
|
By default, any options specified in the <a class="link" href="#cv-FORTRANFLAGS"><code class="envar">$FORTRANFLAGS</code></a>,
|
|
<a class="link" href="#cv-CPPFLAGS"><code class="envar">$CPPFLAGS</code></a>,
|
|
<a class="link" href="#cv-_CPPDEFFLAGS"><code class="envar">$_CPPDEFFLAGS</code></a>,
|
|
<a class="link" href="#cv-_FORTRANMODFLAG"><code class="envar">$_FORTRANMODFLAG</code></a>, and
|
|
<a class="link" href="#cv-_FORTRANINCFLAGS"><code class="envar">$_FORTRANINCFLAGS</code></a>
|
|
construction variables are included on this command line.
|
|
</p></dd><dt><a name="cv-FORTRANPPCOMSTR"></a><span class="term">FORTRANPPCOMSTR</span></dt><dd><p>
|
|
The string displayed when a Fortran source file
|
|
is compiled to an object file
|
|
after first running the file through the C preprocessor.
|
|
If this is not set, then <a class="link" href="#cv-FORTRANPPCOM"><code class="envar">$FORTRANPPCOM</code></a>
|
|
(the command line) is displayed.
|
|
</p></dd><dt><a name="cv-FORTRANPPFILESUFFIXES"></a><span class="term">FORTRANPPFILESUFFIXES</span></dt><dd><p>
|
|
The list of file extensions for which the compilation + preprocessor pass for
|
|
FORTRAN dialect will be used. By default, this is ['.fpp', '.FPP']
|
|
</p></dd><dt><a name="cv-FORTRANSUFFIXES"></a><span class="term">FORTRANSUFFIXES</span></dt><dd><p>
|
|
The list of suffixes of files that will be scanned
|
|
for Fortran implicit dependencies
|
|
(INCLUDE lines and USE statements).
|
|
The default list is:
|
|
</p><pre class="screen">
|
|
[".f", ".F", ".for", ".FOR", ".ftn", ".FTN", ".fpp", ".FPP",
|
|
".f77", ".F77", ".f90", ".F90", ".f95", ".F95"]
|
|
</pre></dd><dt><a name="cv-FRAMEWORKPATH"></a><span class="term">FRAMEWORKPATH</span></dt><dd><p>
|
|
On Mac OS X with gcc,
|
|
a list containing the paths to search for frameworks.
|
|
Used by the compiler to find framework-style includes like
|
|
#include <Fmwk/Header.h>.
|
|
Used by the linker to find user-specified frameworks when linking (see
|
|
<a class="link" href="#cv-FRAMEWORKS"><code class="envar">$FRAMEWORKS</code></a>).
|
|
For example:
|
|
</p><pre class="screen">
|
|
env.AppendUnique(FRAMEWORKPATH='#myframeworkdir')
|
|
</pre><p>
|
|
will add
|
|
</p><pre class="screen">
|
|
... -Fmyframeworkdir
|
|
</pre><p>
|
|
to the compiler and linker command lines.
|
|
</p></dd><dt><a name="cv-_FRAMEWORKPATH"></a><span class="term">_FRAMEWORKPATH</span></dt><dd><p>
|
|
On Mac OS X with gcc, an automatically-generated construction variable
|
|
containing the linker command-line options corresponding to
|
|
<a class="link" href="#cv-FRAMEWORKPATH"><code class="envar">$FRAMEWORKPATH</code></a>.
|
|
</p></dd><dt><a name="cv-FRAMEWORKPATHPREFIX"></a><span class="term">FRAMEWORKPATHPREFIX</span></dt><dd><p>
|
|
On Mac OS X with gcc, the prefix to be used for the FRAMEWORKPATH entries.
|
|
(see <a class="link" href="#cv-FRAMEWORKPATH"><code class="envar">$FRAMEWORKPATH</code></a>).
|
|
The default value is
|
|
<code class="option">-F</code>.
|
|
</p></dd><dt><a name="cv-FRAMEWORKPREFIX"></a><span class="term">FRAMEWORKPREFIX</span></dt><dd><p>
|
|
On Mac OS X with gcc,
|
|
the prefix to be used for linking in frameworks
|
|
(see <a class="link" href="#cv-FRAMEWORKS"><code class="envar">$FRAMEWORKS</code></a>).
|
|
The default value is
|
|
<code class="option">-framework</code>.
|
|
</p></dd><dt><a name="cv-_FRAMEWORKS"></a><span class="term">_FRAMEWORKS</span></dt><dd><p>
|
|
On Mac OS X with gcc,
|
|
an automatically-generated construction variable
|
|
containing the linker command-line options
|
|
for linking with FRAMEWORKS.
|
|
</p></dd><dt><a name="cv-FRAMEWORKS"></a><span class="term">FRAMEWORKS</span></dt><dd><p>
|
|
On Mac OS X with gcc, a list of the framework names to be linked into a
|
|
program or shared library or bundle.
|
|
The default value is the empty list.
|
|
For example:
|
|
</p><pre class="screen">
|
|
env.AppendUnique(FRAMEWORKS=Split('System Cocoa SystemConfiguration'))
|
|
</pre></dd><dt><a name="cv-FRAMEWORKSFLAGS"></a><span class="term">FRAMEWORKSFLAGS</span></dt><dd><p>
|
|
On Mac OS X with gcc,
|
|
general user-supplied frameworks options to be added at
|
|
the end of a command
|
|
line building a loadable module.
|
|
(This has been largely superseded by
|
|
the <a class="link" href="#cv-FRAMEWORKPATH"><code class="envar">$FRAMEWORKPATH</code></a>, <a class="link" href="#cv-FRAMEWORKPATHPREFIX"><code class="envar">$FRAMEWORKPATHPREFIX</code></a>,
|
|
<a class="link" href="#cv-FRAMEWORKPREFIX"><code class="envar">$FRAMEWORKPREFIX</code></a> and <a class="link" href="#cv-FRAMEWORKS"><code class="envar">$FRAMEWORKS</code></a> variables
|
|
described above.)
|
|
</p></dd><dt><a name="cv-GS"></a><span class="term">GS</span></dt><dd><p>
|
|
The Ghostscript program used, e.g. to convert PostScript to PDF files.
|
|
</p></dd><dt><a name="cv-GSCOM"></a><span class="term">GSCOM</span></dt><dd><p>
|
|
The full Ghostscript command line used for the conversion process. Its default
|
|
value is <span class="quote">“<span class="quote"><code class="literal">$GS $GSFLAGS -sOutputFile=$TARGET $SOURCES</code></span>”</span>.
|
|
</p></dd><dt><a name="cv-GSCOMSTR"></a><span class="term">GSCOMSTR</span></dt><dd><p>
|
|
The string displayed when
|
|
Ghostscript is called for the conversion process.
|
|
If this is not set (the default), then <a class="link" href="#cv-GSCOM"><code class="envar">$GSCOM</code></a> (the command line) is displayed.
|
|
</p></dd><dt><a name="cv-GSFLAGS"></a><span class="term">GSFLAGS</span></dt><dd><p>
|
|
General options passed to the Ghostscript program,
|
|
when converting PostScript to PDF files for example. Its default value
|
|
is <span class="quote">“<span class="quote"><code class="literal">-dNOPAUSE -dBATCH -sDEVICE=pdfwrite</code></span>”</span>
|
|
</p></dd><dt><a name="cv-HOST_ARCH"></a><span class="term">HOST_ARCH</span></dt><dd><p>
|
|
The name of the host hardware architecture used to create the Environment.
|
|
If a platform is specified when creating the Environment, then
|
|
that Platform's logic will handle setting this value.
|
|
This value is immutable, and should not be changed by the user after
|
|
the Environment is initialized.
|
|
Currently only set for Win32.
|
|
</p><p>
|
|
Sets the host architecture for Visual Studio compiler. If not set,
|
|
default to the detected host architecture: note that this may depend
|
|
on the python you are using.
|
|
This variable must be passed as an argument to the Environment()
|
|
constructor; setting it later has no effect.
|
|
</p><p>
|
|
Valid values are the same as for <code class="envar">$TARGET_ARCH</code>.
|
|
</p><p>
|
|
This is currently only used on Windows, but in the future it will be
|
|
used on other OSes as well.
|
|
</p></dd><dt><a name="cv-HOST_OS"></a><span class="term">HOST_OS</span></dt><dd><p>
|
|
The name of the host operating system used to create the Environment.
|
|
If a platform is specified when creating the Environment, then
|
|
that Platform's logic will handle setting this value.
|
|
This value is immutable, and should not be changed by the user after
|
|
the Environment is initialized.
|
|
Currently only set for Win32.
|
|
</p></dd><dt><a name="cv-IDLSUFFIXES"></a><span class="term">IDLSUFFIXES</span></dt><dd><p>
|
|
The list of suffixes of files that will be scanned
|
|
for IDL implicit dependencies
|
|
(#include or import lines).
|
|
The default list is:
|
|
</p><pre class="screen">
|
|
[".idl", ".IDL"]
|
|
</pre></dd><dt><a name="cv-IMPLIBNOVERSIONSYMLINKS"></a><span class="term">IMPLIBNOVERSIONSYMLINKS</span></dt><dd><p>
|
|
Used to override <a class="link" href="#cv-SHLIBNOVERSIONSYMLINKS"><code class="envar">$SHLIBNOVERSIONSYMLINKS</code></a>/<a class="link" href="#cv-LDMODULENOVERSIONSYMLINKS"><code class="envar">$LDMODULENOVERSIONSYMLINKS</code></a> when
|
|
creating versioned import library for a shared library/loadable module. If not defined,
|
|
then <a class="link" href="#cv-SHLIBNOVERSIONSYMLINKS"><code class="envar">$SHLIBNOVERSIONSYMLINKS</code></a>/<a class="link" href="#cv-LDMODULENOVERSIONSYMLINKS"><code class="envar">$LDMODULENOVERSIONSYMLINKS</code></a> is used to determine
|
|
whether to disable symlink generation or not.
|
|
</p></dd><dt><a name="cv-IMPLIBPREFIX"></a><span class="term">IMPLIBPREFIX</span></dt><dd><p>
|
|
The prefix used for import library names. For example, cygwin uses import
|
|
libraries (<code class="literal">libfoo.dll.a</code>) in pair with dynamic libraries
|
|
(<code class="literal">cygfoo.dll</code>). The <a class="link" href="#t-cyglink"><code class="literal">cyglink</code></a> linker sets
|
|
<a class="link" href="#cv-IMPLIBPREFIX"><code class="envar">$IMPLIBPREFIX</code></a> to <code class="literal">'lib'</code> and <a class="link" href="#cv-SHLIBPREFIX"><code class="envar">$SHLIBPREFIX</code></a>
|
|
to <code class="literal">'cyg'</code>.
|
|
</p></dd><dt><a name="cv-IMPLIBSUFFIX"></a><span class="term">IMPLIBSUFFIX</span></dt><dd><p>
|
|
The suffix used for import library names. For example, cygwin uses import
|
|
libraries (<code class="literal">libfoo.dll.a</code>) in pair with dynamic libraries
|
|
(<code class="literal">cygfoo.dll</code>). The <a class="link" href="#t-cyglink"><code class="literal">cyglink</code></a> linker sets
|
|
<a class="link" href="#cv-IMPLIBSUFFIX"><code class="envar">$IMPLIBSUFFIX</code></a> to <code class="literal">'.dll.a'</code> and <a class="link" href="#cv-SHLIBSUFFIX"><code class="envar">$SHLIBSUFFIX</code></a>
|
|
to <code class="literal">'.dll'</code>.
|
|
</p></dd><dt><a name="cv-IMPLIBVERSION"></a><span class="term">IMPLIBVERSION</span></dt><dd><p>
|
|
Used to override <a class="link" href="#cv-SHLIBVERSION"><code class="envar">$SHLIBVERSION</code></a>/<a class="link" href="#cv-LDMODULEVERSION"><code class="envar">$LDMODULEVERSION</code></a> when
|
|
generating versioned import library for a shared library/loadable module. If
|
|
undefined, the <a class="link" href="#cv-SHLIBVERSION"><code class="envar">$SHLIBVERSION</code></a>/<a class="link" href="#cv-LDMODULEVERSION"><code class="envar">$LDMODULEVERSION</code></a> is used to
|
|
determine the version of versioned import library.
|
|
</p></dd><dt><a name="cv-IMPLICIT_COMMAND_DEPENDENCIES"></a><span class="term">IMPLICIT_COMMAND_DEPENDENCIES</span></dt><dd><p>
|
|
Controls whether or not SCons will
|
|
add implicit dependencies for the commands
|
|
executed to build targets.
|
|
</p><p>
|
|
By default, SCons will add
|
|
to each target
|
|
an implicit dependency on the command
|
|
represented by the first argument on any
|
|
command line it executes.
|
|
The specific file for the dependency is
|
|
found by searching the
|
|
<code class="varname">PATH</code>
|
|
variable in the
|
|
<code class="varname">ENV</code>
|
|
environment used to execute the command.
|
|
</p><p>
|
|
If the construction variable
|
|
<code class="envar">$IMPLICIT_COMMAND_DEPENDENCIES</code>
|
|
is set to a false value
|
|
(<code class="literal">None</code>,
|
|
<code class="literal">False</code>,
|
|
<code class="literal">0</code>,
|
|
etc.),
|
|
then the implicit dependency will
|
|
not be added to the targets
|
|
built with that construction environment.
|
|
</p><pre class="screen">
|
|
env = Environment(IMPLICIT_COMMAND_DEPENDENCIES = 0)
|
|
</pre></dd><dt><a name="cv-INCPREFIX"></a><span class="term">INCPREFIX</span></dt><dd><p>
|
|
The prefix used to specify an include directory on the C compiler command
|
|
line.
|
|
This will be prepended to the beginning of each directory
|
|
in the <code class="envar">$CPPPATH</code> and <code class="envar">$FORTRANPATH</code> construction variables
|
|
when the <code class="envar">$_CPPINCFLAGS</code> and <code class="envar">$_FORTRANINCFLAGS</code>
|
|
variables are automatically generated.
|
|
</p></dd><dt><a name="cv-INCSUFFIX"></a><span class="term">INCSUFFIX</span></dt><dd><p>
|
|
The suffix used to specify an include directory on the C compiler command
|
|
line.
|
|
This will be appended to the end of each directory
|
|
in the <code class="envar">$CPPPATH</code> and <code class="envar">$FORTRANPATH</code> construction variables
|
|
when the <code class="envar">$_CPPINCFLAGS</code> and <code class="envar">$_FORTRANINCFLAGS</code>
|
|
variables are automatically generated.
|
|
</p></dd><dt><a name="cv-INSTALL"></a><span class="term">INSTALL</span></dt><dd><p>
|
|
A function to be called to install a file into a
|
|
destination file name.
|
|
The default function copies the file into the destination
|
|
(and sets the destination file's mode and permission bits
|
|
to match the source file's).
|
|
The function takes the following arguments:
|
|
</p><pre class="screen">
|
|
def install(dest, source, env):
|
|
</pre><p>
|
|
<code class="varname">dest</code>
|
|
is the path name of the destination file.
|
|
<code class="varname">source</code>
|
|
is the path name of the source file.
|
|
<code class="varname">env</code>
|
|
is the construction environment
|
|
(a dictionary of construction values)
|
|
in force for this file installation.
|
|
</p></dd><dt><a name="cv-INSTALLSTR"></a><span class="term">INSTALLSTR</span></dt><dd><p>
|
|
The string displayed when a file is
|
|
installed into a destination file name.
|
|
The default is:
|
|
</p><pre class="screen">
|
|
Install file: "$SOURCE" as "$TARGET"
|
|
</pre></dd><dt><a name="cv-INTEL_C_COMPILER_VERSION"></a><span class="term">INTEL_C_COMPILER_VERSION</span></dt><dd><p>
|
|
Set by the "intelc" Tool
|
|
to the major version number of the Intel C compiler
|
|
selected for use.
|
|
</p></dd><dt><a name="cv-JAR"></a><span class="term">JAR</span></dt><dd><p>
|
|
The Java archive tool.
|
|
</p><p>
|
|
The Java archive tool.
|
|
</p></dd><dt><a name="cv-JARCHDIR"></a><span class="term">JARCHDIR</span></dt><dd><p>
|
|
The directory to which the Java archive tool should change
|
|
(using the
|
|
<code class="option">-C</code>
|
|
option).
|
|
</p><p>
|
|
The directory to which the Java archive tool should change
|
|
(using the
|
|
<code class="option">-C</code>
|
|
option).
|
|
</p></dd><dt><a name="cv-JARCOM"></a><span class="term">JARCOM</span></dt><dd><p>
|
|
The command line used to call the Java archive tool.
|
|
</p><p>
|
|
The command line used to call the Java archive tool.
|
|
</p></dd><dt><a name="cv-JARCOMSTR"></a><span class="term">JARCOMSTR</span></dt><dd><p>
|
|
The string displayed when the Java archive tool
|
|
is called
|
|
If this is not set, then <code class="envar">$JARCOM</code> (the command line) is displayed.
|
|
</p><pre class="screen">
|
|
env = Environment(JARCOMSTR = "JARchiving $SOURCES into $TARGET")
|
|
</pre><p>
|
|
The string displayed when the Java archive tool
|
|
is called
|
|
If this is not set, then <a class="link" href="#cv-JARCOM"><code class="envar">$JARCOM</code></a> (the command line) is displayed.
|
|
</p><pre class="screen">
|
|
env = Environment(JARCOMSTR = "JARchiving $SOURCES into $TARGET")
|
|
</pre></dd><dt><a name="cv-JARFLAGS"></a><span class="term">JARFLAGS</span></dt><dd><p>
|
|
General options passed to the Java archive tool.
|
|
By default this is set to
|
|
<code class="option">cf</code>
|
|
to create the necessary
|
|
<span class="command"><strong>jar</strong></span>
|
|
file.
|
|
</p><p>
|
|
General options passed to the Java archive tool.
|
|
By default this is set to
|
|
<code class="option">cf</code>
|
|
to create the necessary
|
|
<span class="command"><strong>jar</strong></span>
|
|
file.
|
|
</p></dd><dt><a name="cv-JARSUFFIX"></a><span class="term">JARSUFFIX</span></dt><dd><p>
|
|
The suffix for Java archives:
|
|
<code class="filename">.jar</code>
|
|
by default.
|
|
</p><p>
|
|
The suffix for Java archives:
|
|
<code class="filename">.jar</code>
|
|
by default.
|
|
</p></dd><dt><a name="cv-JAVABOOTCLASSPATH"></a><span class="term">JAVABOOTCLASSPATH</span></dt><dd><p>
|
|
Specifies the list of directories that
|
|
will be added to the
|
|
<span class="application">javac</span> command line
|
|
via the <code class="option">-bootclasspath</code> option.
|
|
The individual directory names will be
|
|
separated by the operating system's path separate character
|
|
(<code class="filename">:</code> on UNIX/Linux/POSIX,
|
|
<code class="filename">;</code>
|
|
on Windows).
|
|
</p></dd><dt><a name="cv-JAVAC"></a><span class="term">JAVAC</span></dt><dd><p>
|
|
The Java compiler.
|
|
</p></dd><dt><a name="cv-JAVACCOM"></a><span class="term">JAVACCOM</span></dt><dd><p>
|
|
The command line used to compile a directory tree containing
|
|
Java source files to
|
|
corresponding Java class files.
|
|
Any options specified in the <a class="link" href="#cv-JAVACFLAGS"><code class="envar">$JAVACFLAGS</code></a> construction variable
|
|
are included on this command line.
|
|
</p></dd><dt><a name="cv-JAVACCOMSTR"></a><span class="term">JAVACCOMSTR</span></dt><dd><p>
|
|
The string displayed when compiling
|
|
a directory tree of Java source files to
|
|
corresponding Java class files.
|
|
If this is not set, then <a class="link" href="#cv-JAVACCOM"><code class="envar">$JAVACCOM</code></a> (the command line) is displayed.
|
|
</p><pre class="screen">
|
|
env = Environment(JAVACCOMSTR = "Compiling class files $TARGETS from $SOURCES")
|
|
</pre></dd><dt><a name="cv-JAVACFLAGS"></a><span class="term">JAVACFLAGS</span></dt><dd><p>
|
|
General options that are passed to the Java compiler.
|
|
</p></dd><dt><a name="cv-JAVACLASSDIR"></a><span class="term">JAVACLASSDIR</span></dt><dd><p>
|
|
The directory in which Java class files may be found.
|
|
This is stripped from the beginning of any Java .class
|
|
file names supplied to the
|
|
<code class="literal">JavaH</code>
|
|
builder.
|
|
</p></dd><dt><a name="cv-JAVACLASSPATH"></a><span class="term">JAVACLASSPATH</span></dt><dd><p>
|
|
Specifies the list of directories that
|
|
will be searched for Java
|
|
<code class="filename">.class</code>
|
|
file.
|
|
The directories in this list will be added to the
|
|
<span class="application">javac</span> and <span class="application">javah</span> command lines
|
|
via the <code class="option">-classpath</code> option.
|
|
The individual directory names will be
|
|
separated by the operating system's path separate character
|
|
(<code class="filename">:</code> on UNIX/Linux/POSIX,
|
|
<code class="filename">;</code>
|
|
on Windows).
|
|
</p><p>
|
|
Note that this currently just adds the specified
|
|
directory via the <code class="option">-classpath</code> option.
|
|
<span class="application">SCons</span> does not currently search the
|
|
<code class="envar">$JAVACLASSPATH</code> directories for dependency
|
|
<code class="filename">.class</code>
|
|
files.
|
|
</p></dd><dt><a name="cv-JAVACLASSSUFFIX"></a><span class="term">JAVACLASSSUFFIX</span></dt><dd><p>
|
|
The suffix for Java class files;
|
|
<code class="filename">.class</code>
|
|
by default.
|
|
</p></dd><dt><a name="cv-JAVAH"></a><span class="term">JAVAH</span></dt><dd><p>
|
|
The Java generator for C header and stub files.
|
|
</p></dd><dt><a name="cv-JAVAHCOM"></a><span class="term">JAVAHCOM</span></dt><dd><p>
|
|
The command line used to generate C header and stub files
|
|
from Java classes.
|
|
Any options specified in the <a class="link" href="#cv-JAVAHFLAGS"><code class="envar">$JAVAHFLAGS</code></a> construction variable
|
|
are included on this command line.
|
|
</p></dd><dt><a name="cv-JAVAHCOMSTR"></a><span class="term">JAVAHCOMSTR</span></dt><dd><p>
|
|
The string displayed when C header and stub files
|
|
are generated from Java classes.
|
|
If this is not set, then <a class="link" href="#cv-JAVAHCOM"><code class="envar">$JAVAHCOM</code></a> (the command line) is displayed.
|
|
</p><pre class="screen">
|
|
env = Environment(JAVAHCOMSTR = "Generating header/stub file(s) $TARGETS from $SOURCES")
|
|
</pre></dd><dt><a name="cv-JAVAHFLAGS"></a><span class="term">JAVAHFLAGS</span></dt><dd><p>
|
|
General options passed to the C header and stub file generator
|
|
for Java classes.
|
|
</p></dd><dt><a name="cv-JAVAINCLUDES"></a><span class="term">JAVAINCLUDES</span></dt><dd><p>
|
|
Include path for Java header files (such as jni.h)
|
|
</p></dd><dt><a name="cv-JAVASOURCEPATH"></a><span class="term">JAVASOURCEPATH</span></dt><dd><p>
|
|
Specifies the list of directories that
|
|
will be searched for input
|
|
<code class="filename">.java</code>
|
|
file.
|
|
The directories in this list will be added to the
|
|
<span class="application">javac</span> command line
|
|
via the <code class="option">-sourcepath</code> option.
|
|
The individual directory names will be
|
|
separated by the operating system's path separate character
|
|
(<code class="filename">:</code> on UNIX/Linux/POSIX,
|
|
<code class="filename">;</code>
|
|
on Windows).
|
|
</p><p>
|
|
Note that this currently just adds the specified
|
|
directory via the <code class="option">-sourcepath</code> option.
|
|
<span class="application">SCons</span> does not currently search the
|
|
<code class="envar">$JAVASOURCEPATH</code> directories for dependency
|
|
<code class="filename">.java</code>
|
|
files.
|
|
</p></dd><dt><a name="cv-JAVASUFFIX"></a><span class="term">JAVASUFFIX</span></dt><dd><p>
|
|
The suffix for Java files;
|
|
<code class="filename">.java</code>
|
|
by default.
|
|
</p></dd><dt><a name="cv-JAVAVERSION"></a><span class="term">JAVAVERSION</span></dt><dd><p>
|
|
Specifies the Java version being used by the <code class="function">Java</code> builder.
|
|
This is <span class="emphasis"><em>not</em></span> currently used to select one
|
|
version of the Java compiler vs. another.
|
|
Instead, you should set this to specify the version of Java
|
|
supported by your <span class="application">javac</span> compiler.
|
|
The default is <code class="literal">1.4</code>.
|
|
</p><p>
|
|
This is sometimes necessary because
|
|
Java 1.5 changed the file names that are created
|
|
for nested anonymous inner classes,
|
|
which can cause a mismatch with the files
|
|
that <span class="application">SCons</span> expects will be generated by the <span class="application">javac</span> compiler.
|
|
Setting <code class="envar">$JAVAVERSION</code> to
|
|
<code class="literal">1.5</code>
|
|
(or <code class="literal">1.6</code>, as appropriate)
|
|
can make <span class="application">SCons</span> realize that a Java 1.5 or 1.6
|
|
build is actually up to date.
|
|
</p></dd><dt><a name="cv-LATEX"></a><span class="term">LATEX</span></dt><dd><p>
|
|
The LaTeX structured formatter and typesetter.
|
|
</p></dd><dt><a name="cv-LATEXCOM"></a><span class="term">LATEXCOM</span></dt><dd><p>
|
|
The command line used to call the LaTeX structured formatter and typesetter.
|
|
</p></dd><dt><a name="cv-LATEXCOMSTR"></a><span class="term">LATEXCOMSTR</span></dt><dd><p>
|
|
The string displayed when calling
|
|
the LaTeX structured formatter and typesetter.
|
|
If this is not set, then <a class="link" href="#cv-LATEXCOM"><code class="envar">$LATEXCOM</code></a> (the command line) is displayed.
|
|
</p><pre class="screen">
|
|
env = Environment(LATEXCOMSTR = "Building $TARGET from LaTeX input $SOURCES")
|
|
</pre></dd><dt><a name="cv-LATEXFLAGS"></a><span class="term">LATEXFLAGS</span></dt><dd><p>
|
|
General options passed to the LaTeX structured formatter and typesetter.
|
|
</p></dd><dt><a name="cv-LATEXRETRIES"></a><span class="term">LATEXRETRIES</span></dt><dd><p>
|
|
The maximum number of times that LaTeX
|
|
will be re-run if the
|
|
<code class="filename">.log</code>
|
|
generated by the <a class="link" href="#cv-LATEXCOM"><code class="envar">$LATEXCOM</code></a> command
|
|
indicates that there are undefined references.
|
|
The default is to try to resolve undefined references
|
|
by re-running LaTeX up to three times.
|
|
</p></dd><dt><a name="cv-LATEXSUFFIXES"></a><span class="term">LATEXSUFFIXES</span></dt><dd><p>
|
|
The list of suffixes of files that will be scanned
|
|
for LaTeX implicit dependencies
|
|
(<code class="literal">\include</code> or <code class="literal">\import</code> files).
|
|
The default list is:
|
|
</p><pre class="screen">
|
|
[".tex", ".ltx", ".latex"]
|
|
</pre></dd><dt><a name="cv-LDMODULE"></a><span class="term">LDMODULE</span></dt><dd><p>
|
|
The linker for building loadable modules.
|
|
By default, this is the same as <a class="link" href="#cv-SHLINK"><code class="envar">$SHLINK</code></a>.
|
|
</p></dd><dt><a name="cv-LDMODULECOM"></a><span class="term">LDMODULECOM</span></dt><dd><p>
|
|
The command line for building loadable modules.
|
|
On Mac OS X, this uses the <a class="link" href="#cv-LDMODULE"><code class="envar">$LDMODULE</code></a>,
|
|
<a class="link" href="#cv-LDMODULEFLAGS"><code class="envar">$LDMODULEFLAGS</code></a> and
|
|
<a class="link" href="#cv-FRAMEWORKSFLAGS"><code class="envar">$FRAMEWORKSFLAGS</code></a> variables.
|
|
On other systems, this is the same as <a class="link" href="#cv-SHLINK"><code class="envar">$SHLINK</code></a>.
|
|
</p></dd><dt><a name="cv-LDMODULECOMSTR"></a><span class="term">LDMODULECOMSTR</span></dt><dd><p>
|
|
The string displayed when building loadable modules.
|
|
If this is not set, then <a class="link" href="#cv-LDMODULECOM"><code class="envar">$LDMODULECOM</code></a> (the command line) is displayed.
|
|
</p></dd><dt><a name="cv-LDMODULEFLAGS"></a><span class="term">LDMODULEFLAGS</span></dt><dd><p>
|
|
General user options passed to the linker for building loadable modules.
|
|
</p></dd><dt><a name="cv-LDMODULENOVERSIONSYMLINKS"></a><span class="term">LDMODULENOVERSIONSYMLINKS</span></dt><dd><p>
|
|
Instructs the <a class="link" href="#b-LoadableModule"><code class="function">LoadableModule</code></a> builder to not automatically create symlinks
|
|
for versioned modules. Defaults to <code class="literal">$SHLIBNOVERSIONSYMLINKS</code>
|
|
</p></dd><dt><a name="cv-LDMODULEPREFIX"></a><span class="term">LDMODULEPREFIX</span></dt><dd><p>
|
|
The prefix used for loadable module file names.
|
|
On Mac OS X, this is null;
|
|
on other systems, this is
|
|
the same as <a class="link" href="#cv-SHLIBPREFIX"><code class="envar">$SHLIBPREFIX</code></a>.
|
|
</p></dd><dt><a name="cv-_LDMODULESONAME"></a><span class="term">_LDMODULESONAME</span></dt><dd><p>
|
|
A macro that automatically generates loadable module's SONAME based on $TARGET,
|
|
$LDMODULEVERSION and $LDMODULESUFFIX. Used by <a class="link" href="#b-LoadableModule"><code class="function">LoadableModule</code></a> builder
|
|
when the linker tool supports SONAME (e.g. <a class="link" href="#t-gnulink"><code class="literal">gnulink</code></a>).
|
|
</p></dd><dt><a name="cv-LDMODULESUFFIX"></a><span class="term">LDMODULESUFFIX</span></dt><dd><p>
|
|
The suffix used for loadable module file names.
|
|
On Mac OS X, this is null;
|
|
on other systems, this is
|
|
the same as $SHLIBSUFFIX.
|
|
</p></dd><dt><a name="cv-LDMODULEVERSION"></a><span class="term">LDMODULEVERSION</span></dt><dd><p>
|
|
When this construction variable is defined, a versioned loadable module
|
|
is created by <a class="link" href="#b-LoadableModule"><code class="function">LoadableModule</code></a> builder. This activates the
|
|
<a class="link" href="#cv-_LDMODULEVERSIONFLAGS"><code class="envar">$_LDMODULEVERSIONFLAGS</code></a> and thus modifies the <a class="link" href="#cv-LDMODULECOM"><code class="envar">$LDMODULECOM</code></a> as
|
|
required, adds the version number to the library name, and creates the symlinks
|
|
that are needed. <a class="link" href="#cv-LDMODULEVERSION"><code class="envar">$LDMODULEVERSION</code></a> versions should exist in the same
|
|
format as <a class="link" href="#cv-SHLIBVERSION"><code class="envar">$SHLIBVERSION</code></a>.
|
|
</p></dd><dt><a name="cv-LDMODULEVERSIONFLAGS"></a><span class="term">LDMODULEVERSIONFLAGS</span></dt><dd><p>
|
|
Extra flags added to <a class="link" href="#cv-LDMODULECOM"><code class="envar">$LDMODULECOM</code></a> when building versioned
|
|
<a class="link" href="#b-LoadableModule"><code class="function">LoadableModule</code></a>. These flags are only used when <a class="link" href="#cv-LDMODULEVERSION"><code class="envar">$LDMODULEVERSION</code></a> is
|
|
set.
|
|
</p></dd><dt><a name="cv-_LDMODULEVERSIONFLAGS"></a><span class="term">_LDMODULEVERSIONFLAGS</span></dt><dd><p>
|
|
This macro automatically introduces extra flags to <a class="link" href="#cv-LDMODULECOM"><code class="envar">$LDMODULECOM</code></a> when
|
|
building versioned <a class="link" href="#b-LoadableModule"><code class="function">LoadableModule</code></a> (that is when
|
|
<a class="link" href="#cv-LDMODULEVERSION"><code class="envar">$LDMODULEVERSION</code></a> is set). <code class="literal">_LDMODULEVERSIONFLAGS</code>
|
|
usually adds <a class="link" href="#cv-SHLIBVERSIONFLAGS"><code class="envar">$SHLIBVERSIONFLAGS</code></a> and some extra dynamically generated
|
|
options (such as <code class="literal">-Wl,-soname=$_LDMODULESONAME</code>). It is unused
|
|
by plain (unversioned) loadable modules.
|
|
</p></dd><dt><a name="cv-LEX"></a><span class="term">LEX</span></dt><dd><p>
|
|
The lexical analyzer generator.
|
|
</p></dd><dt><a name="cv-LEXCOM"></a><span class="term">LEXCOM</span></dt><dd><p>
|
|
The command line used to call the lexical analyzer generator
|
|
to generate a source file.
|
|
</p></dd><dt><a name="cv-LEXCOMSTR"></a><span class="term">LEXCOMSTR</span></dt><dd><p>
|
|
The string displayed when generating a source file
|
|
using the lexical analyzer generator.
|
|
If this is not set, then <a class="link" href="#cv-LEXCOM"><code class="envar">$LEXCOM</code></a> (the command line) is displayed.
|
|
</p><pre class="screen">
|
|
env = Environment(LEXCOMSTR = "Lex'ing $TARGET from $SOURCES")
|
|
</pre></dd><dt><a name="cv-LEXFLAGS"></a><span class="term">LEXFLAGS</span></dt><dd><p>
|
|
General options passed to the lexical analyzer generator.
|
|
</p></dd><dt><a name="cv-_LIBDIRFLAGS"></a><span class="term">_LIBDIRFLAGS</span></dt><dd><p>
|
|
An automatically-generated construction variable
|
|
containing the linker command-line options
|
|
for specifying directories to be searched for library.
|
|
The value of <code class="envar">$_LIBDIRFLAGS</code> is created
|
|
by respectively prepending and appending <code class="envar">$LIBDIRPREFIX</code> and <code class="envar">$LIBDIRSUFFIX</code>
|
|
to the beginning and end
|
|
of each directory in <code class="envar">$LIBPATH</code>.
|
|
</p></dd><dt><a name="cv-LIBDIRPREFIX"></a><span class="term">LIBDIRPREFIX</span></dt><dd><p>
|
|
The prefix used to specify a library directory on the linker command line.
|
|
This will be prepended to the beginning of each directory
|
|
in the <code class="envar">$LIBPATH</code> construction variable
|
|
when the <code class="envar">$_LIBDIRFLAGS</code> variable is automatically generated.
|
|
</p></dd><dt><a name="cv-LIBDIRSUFFIX"></a><span class="term">LIBDIRSUFFIX</span></dt><dd><p>
|
|
The suffix used to specify a library directory on the linker command line.
|
|
This will be appended to the end of each directory
|
|
in the <code class="envar">$LIBPATH</code> construction variable
|
|
when the <code class="envar">$_LIBDIRFLAGS</code> variable is automatically generated.
|
|
</p></dd><dt><a name="cv-LIBEMITTER"></a><span class="term">LIBEMITTER</span></dt><dd><p>
|
|
TODO
|
|
</p></dd><dt><a name="cv-_LIBFLAGS"></a><span class="term">_LIBFLAGS</span></dt><dd><p>
|
|
An automatically-generated construction variable
|
|
containing the linker command-line options
|
|
for specifying libraries to be linked with the resulting target.
|
|
The value of <code class="envar">$_LIBFLAGS</code> is created
|
|
by respectively prepending and appending <code class="envar">$LIBLINKPREFIX</code> and <code class="envar">$LIBLINKSUFFIX</code>
|
|
to the beginning and end
|
|
of each filename in <code class="envar">$LIBS</code>.
|
|
</p></dd><dt><a name="cv-LIBLINKPREFIX"></a><span class="term">LIBLINKPREFIX</span></dt><dd><p>
|
|
The prefix used to specify a library to link on the linker command line.
|
|
This will be prepended to the beginning of each library
|
|
in the <code class="envar">$LIBS</code> construction variable
|
|
when the <code class="envar">$_LIBFLAGS</code> variable is automatically generated.
|
|
</p></dd><dt><a name="cv-LIBLINKSUFFIX"></a><span class="term">LIBLINKSUFFIX</span></dt><dd><p>
|
|
The suffix used to specify a library to link on the linker command line.
|
|
This will be appended to the end of each library
|
|
in the <code class="envar">$LIBS</code> construction variable
|
|
when the <code class="envar">$_LIBFLAGS</code> variable is automatically generated.
|
|
</p></dd><dt><a name="cv-LIBPATH"></a><span class="term">LIBPATH</span></dt><dd><p>
|
|
The list of directories that will be searched for libraries.
|
|
The implicit dependency scanner will search these
|
|
directories for include files. Don't explicitly put include directory
|
|
arguments in <code class="envar">$LINKFLAGS</code> or <code class="envar">$SHLINKFLAGS</code>
|
|
because the result will be non-portable
|
|
and the directories will not be searched by the dependency scanner. Note:
|
|
directory names in LIBPATH will be looked-up relative to the SConscript
|
|
directory when they are used in a command. To force
|
|
<code class="filename">scons</code>
|
|
to look-up a directory relative to the root of the source tree use #:
|
|
</p><pre class="screen">
|
|
env = Environment(LIBPATH='#/libs')
|
|
</pre><p>
|
|
The directory look-up can also be forced using the
|
|
<code class="function">Dir</code>()
|
|
function:
|
|
</p><pre class="screen">
|
|
libs = Dir('libs')
|
|
env = Environment(LIBPATH=libs)
|
|
</pre><p>
|
|
The directory list will be added to command lines
|
|
through the automatically-generated
|
|
<code class="envar">$_LIBDIRFLAGS</code>
|
|
construction variable,
|
|
which is constructed by
|
|
respectively prepending and appending the values of the
|
|
<code class="envar">$LIBDIRPREFIX</code> and <code class="envar">$LIBDIRSUFFIX</code>
|
|
construction variables
|
|
to the beginning and end
|
|
of each directory in <code class="envar">$LIBPATH</code>.
|
|
Any command lines you define that need
|
|
the LIBPATH directory list should
|
|
include <code class="envar">$_LIBDIRFLAGS</code>:
|
|
</p><pre class="screen">
|
|
env = Environment(LINKCOM="my_linker $_LIBDIRFLAGS $_LIBFLAGS -o $TARGET $SOURCE")
|
|
</pre></dd><dt><a name="cv-LIBPREFIX"></a><span class="term">LIBPREFIX</span></dt><dd><p>
|
|
The prefix used for (static) library file names.
|
|
A default value is set for each platform
|
|
(posix, win32, os2, etc.),
|
|
but the value is overridden by individual tools
|
|
(ar, mslib, sgiar, sunar, tlib, etc.)
|
|
to reflect the names of the libraries they create.
|
|
</p></dd><dt><a name="cv-LIBPREFIXES"></a><span class="term">LIBPREFIXES</span></dt><dd><p>
|
|
A list of all legal prefixes for library file names.
|
|
When searching for library dependencies,
|
|
SCons will look for files with these prefixes,
|
|
the base library name,
|
|
and suffixes in the <code class="envar">$LIBSUFFIXES</code> list.
|
|
</p></dd><dt><a name="cv-LIBS"></a><span class="term">LIBS</span></dt><dd><p>
|
|
A list of one or more libraries
|
|
that will be linked with
|
|
any executable programs
|
|
created by this environment.
|
|
</p><p>
|
|
The library list will be added to command lines
|
|
through the automatically-generated
|
|
<code class="envar">$_LIBFLAGS</code>
|
|
construction variable,
|
|
which is constructed by
|
|
respectively prepending and appending the values of the
|
|
<code class="envar">$LIBLINKPREFIX</code> and <code class="envar">$LIBLINKSUFFIX</code>
|
|
construction variables
|
|
to the beginning and end
|
|
of each filename in <code class="envar">$LIBS</code>.
|
|
Any command lines you define that need
|
|
the LIBS library list should
|
|
include <code class="envar">$_LIBFLAGS</code>:
|
|
</p><pre class="screen">
|
|
env = Environment(LINKCOM="my_linker $_LIBDIRFLAGS $_LIBFLAGS -o $TARGET $SOURCE")
|
|
</pre><p>
|
|
If you add a
|
|
File
|
|
object to the
|
|
<code class="envar">$LIBS</code>
|
|
list, the name of that file will be added to
|
|
<code class="envar">$_LIBFLAGS</code>,
|
|
and thus the link line, as is, without
|
|
<code class="envar">$LIBLINKPREFIX</code>
|
|
or
|
|
<code class="envar">$LIBLINKSUFFIX</code>.
|
|
For example:
|
|
</p><pre class="screen">
|
|
env.Append(LIBS=File('/tmp/mylib.so'))
|
|
</pre><p>
|
|
In all cases, scons will add dependencies from the executable program to
|
|
all the libraries in this list.
|
|
</p></dd><dt><a name="cv-LIBSUFFIX"></a><span class="term">LIBSUFFIX</span></dt><dd><p>
|
|
The suffix used for (static) library file names.
|
|
A default value is set for each platform
|
|
(posix, win32, os2, etc.),
|
|
but the value is overridden by individual tools
|
|
(ar, mslib, sgiar, sunar, tlib, etc.)
|
|
to reflect the names of the libraries they create.
|
|
</p></dd><dt><a name="cv-LIBSUFFIXES"></a><span class="term">LIBSUFFIXES</span></dt><dd><p>
|
|
A list of all legal suffixes for library file names.
|
|
When searching for library dependencies,
|
|
SCons will look for files with prefixes, in the <code class="envar">$LIBPREFIXES</code> list,
|
|
the base library name,
|
|
and these suffixes.
|
|
</p></dd><dt><a name="cv-LICENSE"></a><span class="term">LICENSE</span></dt><dd><p>
|
|
The abbreviated name, preferably the SPDX code, of the license under which
|
|
this project is released (GPL-3.0, LGPL-2.1, BSD-2-Clause etc.).
|
|
See http://www.opensource.org/licenses/alphabetical
|
|
for a list of license names and SPDX codes.
|
|
</p></dd><dt><a name="cv-LINESEPARATOR"></a><span class="term">LINESEPARATOR</span></dt><dd><p>
|
|
The separator used by the <code class="function">Substfile</code> and <code class="function">Textfile</code> builders.
|
|
This value is used between sources when constructing the target.
|
|
It defaults to the current system line separator.
|
|
</p></dd><dt><a name="cv-LINGUAS_FILE"></a><span class="term">LINGUAS_FILE</span></dt><dd><p>
|
|
The <code class="envar">$LINGUAS_FILE</code> defines file(s) containing list of additional linguas
|
|
to be processed by <a class="link" href="#b-POInit"><code class="function">POInit</code></a>, <a class="link" href="#b-POUpdate"><code class="function">POUpdate</code></a> or <a class="link" href="#b-MOFiles"><code class="function">MOFiles</code></a>
|
|
builders. It also affects <a class="link" href="#b-Translate"><code class="function">Translate</code></a> builder. If the variable contains
|
|
a string, it defines name of the list file. The <code class="envar">$LINGUAS_FILE</code> may be a
|
|
list of file names as well. If <code class="envar">$LINGUAS_FILE</code> is set to
|
|
<code class="literal">True</code> (or non-zero numeric value), the list will be read from
|
|
default file named
|
|
<code class="filename">LINGUAS</code>.
|
|
</p></dd><dt><a name="cv-LINK"></a><span class="term">LINK</span></dt><dd><p>
|
|
The linker.
|
|
</p></dd><dt><a name="cv-LINKCOM"></a><span class="term">LINKCOM</span></dt><dd><p>
|
|
The command line used to link object files into an executable.
|
|
</p></dd><dt><a name="cv-LINKCOMSTR"></a><span class="term">LINKCOMSTR</span></dt><dd><p>
|
|
The string displayed when object files
|
|
are linked into an executable.
|
|
If this is not set, then <a class="link" href="#cv-LINKCOM"><code class="envar">$LINKCOM</code></a> (the command line) is displayed.
|
|
</p><pre class="screen">
|
|
env = Environment(LINKCOMSTR = "Linking $TARGET")
|
|
</pre></dd><dt><a name="cv-LINKFLAGS"></a><span class="term">LINKFLAGS</span></dt><dd><p>
|
|
General user options passed to the linker.
|
|
Note that this variable should
|
|
<span class="emphasis"><em>not</em></span>
|
|
contain
|
|
<code class="option">-l</code>
|
|
(or similar) options for linking with the libraries listed in <a class="link" href="#cv-LIBS"><code class="envar">$LIBS</code></a>,
|
|
nor
|
|
<code class="option">-L</code>
|
|
(or similar) library search path options
|
|
that scons generates automatically from <a class="link" href="#cv-LIBPATH"><code class="envar">$LIBPATH</code></a>.
|
|
See
|
|
<a class="link" href="#cv-_LIBFLAGS"><code class="envar">$_LIBFLAGS</code></a>
|
|
above,
|
|
for the variable that expands to library-link options,
|
|
and
|
|
<a class="link" href="#cv-_LIBDIRFLAGS"><code class="envar">$_LIBDIRFLAGS</code></a>
|
|
above,
|
|
for the variable that expands to library search path options.
|
|
</p></dd><dt><a name="cv-M4"></a><span class="term">M4</span></dt><dd><p>
|
|
The M4 macro preprocessor.
|
|
</p></dd><dt><a name="cv-M4COM"></a><span class="term">M4COM</span></dt><dd><p>
|
|
The command line used to pass files through the M4 macro preprocessor.
|
|
</p></dd><dt><a name="cv-M4COMSTR"></a><span class="term">M4COMSTR</span></dt><dd><p>
|
|
The string displayed when
|
|
a file is passed through the M4 macro preprocessor.
|
|
If this is not set, then <a class="link" href="#cv-M4COM"><code class="envar">$M4COM</code></a> (the command line) is displayed.
|
|
</p></dd><dt><a name="cv-M4FLAGS"></a><span class="term">M4FLAGS</span></dt><dd><p>
|
|
General options passed to the M4 macro preprocessor.
|
|
</p></dd><dt><a name="cv-MAKEINDEX"></a><span class="term">MAKEINDEX</span></dt><dd><p>
|
|
The makeindex generator for the TeX formatter and typesetter and the
|
|
LaTeX structured formatter and typesetter.
|
|
</p></dd><dt><a name="cv-MAKEINDEXCOM"></a><span class="term">MAKEINDEXCOM</span></dt><dd><p>
|
|
The command line used to call the makeindex generator for the
|
|
TeX formatter and typesetter and the LaTeX structured formatter and
|
|
typesetter.
|
|
</p></dd><dt><a name="cv-MAKEINDEXCOMSTR"></a><span class="term">MAKEINDEXCOMSTR</span></dt><dd><p>
|
|
The string displayed when calling the makeindex generator for the
|
|
TeX formatter and typesetter
|
|
and the LaTeX structured formatter and typesetter.
|
|
If this is not set, then <a class="link" href="#cv-MAKEINDEXCOM"><code class="envar">$MAKEINDEXCOM</code></a> (the command line) is displayed.
|
|
</p></dd><dt><a name="cv-MAKEINDEXFLAGS"></a><span class="term">MAKEINDEXFLAGS</span></dt><dd><p>
|
|
General options passed to the makeindex generator for the TeX formatter
|
|
and typesetter and the LaTeX structured formatter and typesetter.
|
|
</p></dd><dt><a name="cv-MAXLINELENGTH"></a><span class="term">MAXLINELENGTH</span></dt><dd><p>
|
|
The maximum number of characters allowed on an external command line.
|
|
On Win32 systems,
|
|
link lines longer than this many characters
|
|
are linked via a temporary file name.
|
|
</p></dd><dt><a name="cv-MIDL"></a><span class="term">MIDL</span></dt><dd><p>
|
|
The Microsoft IDL compiler.
|
|
</p></dd><dt><a name="cv-MIDLCOM"></a><span class="term">MIDLCOM</span></dt><dd><p>
|
|
The command line used to pass files to the Microsoft IDL compiler.
|
|
</p></dd><dt><a name="cv-MIDLCOMSTR"></a><span class="term">MIDLCOMSTR</span></dt><dd><p>
|
|
The string displayed when
|
|
the Microsoft IDL copmiler is called.
|
|
If this is not set, then <a class="link" href="#cv-MIDLCOM"><code class="envar">$MIDLCOM</code></a> (the command line) is displayed.
|
|
</p></dd><dt><a name="cv-MIDLFLAGS"></a><span class="term">MIDLFLAGS</span></dt><dd><p>
|
|
General options passed to the Microsoft IDL compiler.
|
|
</p></dd><dt><a name="cv-MOSUFFIX"></a><span class="term">MOSUFFIX</span></dt><dd><p>
|
|
Suffix used for <code class="literal">MO</code> files (default: <code class="literal">'.mo'</code>).
|
|
See <a class="link" href="#t-msgfmt"><code class="literal">msgfmt</code></a> tool and <a class="link" href="#b-MOFiles"><code class="function">MOFiles</code></a> builder.
|
|
</p></dd><dt><a name="cv-MSGFMT"></a><span class="term">MSGFMT</span></dt><dd><p>
|
|
Absolute path to <span class="command"><strong>msgfmt(1)</strong></span> binary, found by
|
|
<code class="function">Detect()</code>.
|
|
See <a class="link" href="#t-msgfmt"><code class="literal">msgfmt</code></a> tool and <a class="link" href="#b-MOFiles"><code class="function">MOFiles</code></a> builder.
|
|
</p></dd><dt><a name="cv-MSGFMTCOM"></a><span class="term">MSGFMTCOM</span></dt><dd><p>
|
|
Complete command line to run <span class="command"><strong>msgfmt(1)</strong></span> program.
|
|
See <a class="link" href="#t-msgfmt"><code class="literal">msgfmt</code></a> tool and <a class="link" href="#b-MOFiles"><code class="function">MOFiles</code></a> builder.
|
|
</p></dd><dt><a name="cv-MSGFMTCOMSTR"></a><span class="term">MSGFMTCOMSTR</span></dt><dd><p>
|
|
String to display when <span class="command"><strong>msgfmt(1)</strong></span> is invoked
|
|
(default: <code class="literal">''</code>, which means ``print <a class="link" href="#cv-MSGFMTCOM"><code class="envar">$MSGFMTCOM</code></a>'').
|
|
See <a class="link" href="#t-msgfmt"><code class="literal">msgfmt</code></a> tool and <a class="link" href="#b-MOFiles"><code class="function">MOFiles</code></a> builder.
|
|
</p></dd><dt><a name="cv-MSGFMTFLAGS"></a><span class="term">MSGFMTFLAGS</span></dt><dd><p>
|
|
Additional flags to <span class="command"><strong>msgfmt(1)</strong></span>.
|
|
See <a class="link" href="#t-msgfmt"><code class="literal">msgfmt</code></a> tool and <a class="link" href="#b-MOFiles"><code class="function">MOFiles</code></a> builder.
|
|
</p></dd><dt><a name="cv-MSGINIT"></a><span class="term">MSGINIT</span></dt><dd><p>
|
|
Path to <span class="command"><strong>msginit(1)</strong></span> program (found via
|
|
<code class="literal">Detect()</code>).
|
|
See <a class="link" href="#t-msginit"><code class="literal">msginit</code></a> tool and <a class="link" href="#b-POInit"><code class="function">POInit</code></a> builder.
|
|
</p></dd><dt><a name="cv-MSGINITCOM"></a><span class="term">MSGINITCOM</span></dt><dd><p>
|
|
Complete command line to run <span class="command"><strong>msginit(1)</strong></span> program.
|
|
See <a class="link" href="#t-msginit"><code class="literal">msginit</code></a> tool and <a class="link" href="#b-POInit"><code class="function">POInit</code></a> builder.
|
|
</p></dd><dt><a name="cv-MSGINITCOMSTR"></a><span class="term">MSGINITCOMSTR</span></dt><dd><p>
|
|
String to display when <span class="command"><strong>msginit(1)</strong></span> is invoked
|
|
(default: <code class="literal">''</code>, which means ``print <a class="link" href="#cv-MSGINITCOM"><code class="envar">$MSGINITCOM</code></a>'').
|
|
See <a class="link" href="#t-msginit"><code class="literal">msginit</code></a> tool and <a class="link" href="#b-POInit"><code class="function">POInit</code></a> builder.
|
|
</p></dd><dt><a name="cv-MSGINITFLAGS"></a><span class="term">MSGINITFLAGS</span></dt><dd><p>
|
|
List of additional flags to <span class="command"><strong>msginit(1)</strong></span> (default:
|
|
<code class="literal">[]</code>).
|
|
See <a class="link" href="#t-msginit"><code class="literal">msginit</code></a> tool and <a class="link" href="#b-POInit"><code class="function">POInit</code></a> builder.
|
|
</p></dd><dt><a name="cv-_MSGINITLOCALE"></a><span class="term">_MSGINITLOCALE</span></dt><dd><p>
|
|
Internal ``macro''. Computes locale (language) name based on target filename
|
|
(default: <code class="literal">'${TARGET.filebase}' </code>).
|
|
</p><p>
|
|
See <a class="link" href="#t-msginit"><code class="literal">msginit</code></a> tool and <a class="link" href="#b-POInit"><code class="function">POInit</code></a> builder.
|
|
</p></dd><dt><a name="cv-MSGMERGE"></a><span class="term">MSGMERGE</span></dt><dd><p>
|
|
Absolute path to <span class="command"><strong>msgmerge(1)</strong></span> binary as found by
|
|
<code class="function">Detect()</code>.
|
|
See <a class="link" href="#t-msgmerge"><code class="literal">msgmerge</code></a> tool and <a class="link" href="#b-POUpdate"><code class="function">POUpdate</code></a> builder.
|
|
</p></dd><dt><a name="cv-MSGMERGECOM"></a><span class="term">MSGMERGECOM</span></dt><dd><p>
|
|
Complete command line to run <span class="command"><strong>msgmerge(1)</strong></span> command.
|
|
See <a class="link" href="#t-msgmerge"><code class="literal">msgmerge</code></a> tool and <a class="link" href="#b-POUpdate"><code class="function">POUpdate</code></a> builder.
|
|
</p></dd><dt><a name="cv-MSGMERGECOMSTR"></a><span class="term">MSGMERGECOMSTR</span></dt><dd><p>
|
|
String to be displayed when <span class="command"><strong>msgmerge(1)</strong></span> is invoked
|
|
(default: <code class="literal">''</code>, which means ``print <a class="link" href="#cv-MSGMERGECOM"><code class="envar">$MSGMERGECOM</code></a>'').
|
|
See <a class="link" href="#t-msgmerge"><code class="literal">msgmerge</code></a> tool and <a class="link" href="#b-POUpdate"><code class="function">POUpdate</code></a> builder.
|
|
</p></dd><dt><a name="cv-MSGMERGEFLAGS"></a><span class="term">MSGMERGEFLAGS</span></dt><dd><p>
|
|
Additional flags to <span class="command"><strong>msgmerge(1)</strong></span> command.
|
|
See <a class="link" href="#t-msgmerge"><code class="literal">msgmerge</code></a> tool and <a class="link" href="#b-POUpdate"><code class="function">POUpdate</code></a> builder.
|
|
</p></dd><dt><a name="cv-MSSDK_DIR"></a><span class="term">MSSDK_DIR</span></dt><dd><p>
|
|
The directory containing the Microsoft SDK
|
|
(either Platform SDK or Windows SDK)
|
|
to be used for compilation.
|
|
</p></dd><dt><a name="cv-MSSDK_VERSION"></a><span class="term">MSSDK_VERSION</span></dt><dd><p>
|
|
The version string of the Microsoft SDK
|
|
(either Platform SDK or Windows SDK)
|
|
to be used for compilation.
|
|
Supported versions include
|
|
<code class="literal">6.1</code>,
|
|
<code class="literal">6.0A</code>,
|
|
<code class="literal">6.0</code>,
|
|
<code class="literal">2003R2</code>
|
|
and
|
|
<code class="literal">2003R1</code>.
|
|
</p></dd><dt><a name="cv-MSVC_BATCH"></a><span class="term">MSVC_BATCH</span></dt><dd><p>
|
|
When set to any true value,
|
|
specifies that SCons should batch
|
|
compilation of object files
|
|
when calling the Microsoft Visual C/C++ compiler.
|
|
All compilations of source files from the same source directory
|
|
that generate target files in a same output directory
|
|
and were configured in SCons using the same construction environment
|
|
will be built in a single call to the compiler.
|
|
Only source files that have changed since their
|
|
object files were built will be passed to each compiler invocation
|
|
(via the <a class="link" href="#cv-CHANGED_SOURCES"><code class="envar">$CHANGED_SOURCES</code></a> construction variable).
|
|
Any compilations where the object (target) file base name
|
|
(minus the <code class="filename">.obj</code>)
|
|
does not match the source file base name
|
|
will be compiled separately.
|
|
</p></dd><dt><a name="cv-MSVC_USE_SCRIPT"></a><span class="term">MSVC_USE_SCRIPT</span></dt><dd><p>
|
|
Use a batch script to set up Microsoft Visual Studio compiler
|
|
</p><p>
|
|
<code class="envar">$MSVC_USE_SCRIPT</code> overrides <code class="envar">$MSVC_VERSION</code> and <code class="envar">$TARGET_ARCH</code>.
|
|
If set to the name of a Visual Studio .bat file (e.g. vcvars.bat),
|
|
SCons will run that bat file and extract the relevant variables from
|
|
the result (typically %INCLUDE%, %LIB%, and %PATH%). Setting
|
|
MSVC_USE_SCRIPT to None bypasses the Visual Studio autodetection
|
|
entirely; use this if you are running SCons in a Visual Studio cmd
|
|
window and importing the shell's environment variables.
|
|
</p></dd><dt><a name="cv-MSVC_UWP_APP"></a><span class="term">MSVC_UWP_APP</span></dt><dd><p>
|
|
Build libraries for a Universal Windows Platform (UWP) Application.
|
|
</p><p>
|
|
If <code class="envar">$MSVC_UWP_APP</code> is set, the Visual Studio environment will be set up to point
|
|
to the Windows Store compatible libraries and Visual Studio runtimes. In doing so,
|
|
any libraries that are built will be able to be used in a UWP App and published
|
|
to the Windows Store.
|
|
This flag will only have an effect with Visual Studio 2015+.
|
|
This variable must be passed as an argument to the Environment()
|
|
constructor; setting it later has no effect.
|
|
</p><p>
|
|
Valid values are '1' or '0'
|
|
</p></dd><dt><a name="cv-MSVC_VERSION"></a><span class="term">MSVC_VERSION</span></dt><dd><p>
|
|
Sets the preferred version of Microsoft Visual C/C++ to use.
|
|
</p><p>
|
|
If <code class="envar">$MSVC_VERSION</code> is not set, SCons will (by default) select the
|
|
latest version of Visual C/C++ installed on your system. If the
|
|
specified version isn't installed, tool initialization will fail.
|
|
This variable must be passed as an argument to the Environment()
|
|
constructor; setting it later has no effect.
|
|
</p><p>
|
|
Valid values for Windows are
|
|
<code class="literal">14.1</code>,
|
|
<code class="literal">14.0</code>,
|
|
<code class="literal">14.0Exp</code>,
|
|
<code class="literal">12.0</code>,
|
|
<code class="literal">12.0Exp</code>,
|
|
<code class="literal">11.0</code>,
|
|
<code class="literal">11.0Exp</code>,
|
|
<code class="literal">10.0</code>,
|
|
<code class="literal">10.0Exp</code>,
|
|
<code class="literal">9.0</code>,
|
|
<code class="literal">9.0Exp</code>,
|
|
<code class="literal">8.0</code>,
|
|
<code class="literal">8.0Exp</code>,
|
|
<code class="literal">7.1</code>,
|
|
<code class="literal">7.0</code>,
|
|
and <code class="literal">6.0</code>.
|
|
Versions ending in <code class="literal">Exp</code> refer to "Express" or
|
|
"Express for Desktop" editions.
|
|
</p></dd><dt><a name="cv-MSVS"></a><span class="term">MSVS</span></dt><dd><p>
|
|
When the Microsoft Visual Studio tools are initialized, they set up this
|
|
dictionary with the following keys: </p><div class="variablelist"><dl><dt><span class="term">VERSION</span></dt><dd><p>the version of MSVS being used (can be set via
|
|
<a class="link" href="#cv-MSVS_VERSION"><code class="envar">$MSVS_VERSION</code></a>)</p></dd><dt><span class="term">VERSIONS</span></dt><dd><p>the available versions of MSVS installed</p></dd><dt><span class="term">VCINSTALLDIR</span></dt><dd><p>installed directory of Visual C++</p></dd><dt><span class="term">VSINSTALLDIR</span></dt><dd><p>installed directory of Visual Studio</p></dd><dt><span class="term">FRAMEWORKDIR</span></dt><dd><p>installed directory of the .NET framework</p></dd><dt><span class="term">FRAMEWORKVERSIONS</span></dt><dd><p>list of installed versions of the .NET framework, sorted
|
|
latest to oldest.</p></dd><dt><span class="term">FRAMEWORKVERSION</span></dt><dd><p>latest installed version of the .NET
|
|
framework</p></dd><dt><span class="term">FRAMEWORKSDKDIR</span></dt><dd><p>installed location of the .NET SDK.</p></dd><dt><span class="term">PLATFORMSDKDIR</span></dt><dd><p>installed location of the Platform SDK.</p></dd><dt><span class="term">PLATFORMSDK_MODULES</span></dt><dd><p>dictionary of installed Platform SDK modules, where the
|
|
dictionary keys are keywords for the various modules, and the values
|
|
are 2-tuples where the first is the release date, and the second is
|
|
the version number.</p></dd></dl></div><p>If a value isn't set, it wasn't available in the
|
|
registry.</p></dd><dt><a name="cv-MSVS_ARCH"></a><span class="term">MSVS_ARCH</span></dt><dd><p>Sets
|
|
the architecture for which the generated project(s) should build. </p><p>The default value is <code class="literal">x86</code>. <code class="literal">amd64</code> is
|
|
also supported by <span class="application">SCons</span> for some Visual Studio versions. Trying to set
|
|
<code class="envar">$MSVS_ARCH</code> to an architecture that's not supported for a given Visual
|
|
Studio version will generate an error. </p></dd><dt><a name="cv-MSVS_PROJECT_GUID"></a><span class="term">MSVS_PROJECT_GUID</span></dt><dd><p>The string placed in a generated
|
|
Microsoft Visual Studio project file as the value of the
|
|
<code class="literal">ProjectGUID</code> attribute. There is no default value. If not
|
|
defined, a new GUID is generated. </p></dd><dt><a name="cv-MSVS_SCC_AUX_PATH"></a><span class="term">MSVS_SCC_AUX_PATH</span></dt><dd><p>The path name placed in a generated
|
|
Microsoft Visual Studio project file as the value of the
|
|
<code class="literal">SccAuxPath</code> attribute if the
|
|
<code class="envar">MSVS_SCC_PROVIDER</code> construction variable is also set. There is
|
|
no default value. </p></dd><dt><a name="cv-MSVS_SCC_CONNECTION_ROOT"></a><span class="term">MSVS_SCC_CONNECTION_ROOT</span></dt><dd><p>The root path of projects in
|
|
your SCC workspace, i.e the path under which all project and solution files
|
|
will be generated. It is used as a reference path from which the relative
|
|
paths of the generated Microsoft Visual Studio project and solution files are
|
|
computed. The relative project file path is placed as the value of the
|
|
<code class="literal">SccLocalPath</code> attribute of the project file and as the
|
|
values of the
|
|
<code class="literal">SccProjectFilePathRelativizedFromConnection[i]</code> (where [i]
|
|
ranges from 0 to the number of projects in the solution) attributes of the
|
|
<code class="literal">GlobalSection(SourceCodeControl)</code> section of the Microsoft
|
|
Visual Studio solution file. Similarly the relative solution file path is
|
|
placed as the values of the <code class="literal">SccLocalPath[i]</code> (where [i]
|
|
ranges from 0 to the number of projects in the solution) attributes of the
|
|
<code class="literal">GlobalSection(SourceCodeControl)</code> section of the Microsoft
|
|
Visual Studio solution file. This is used only if the
|
|
<code class="envar">MSVS_SCC_PROVIDER</code> construction variable is also set. The
|
|
default value is the current working directory. </p></dd><dt><a name="cv-MSVS_SCC_PROJECT_NAME"></a><span class="term">MSVS_SCC_PROJECT_NAME</span></dt><dd><p>The project name placed in
|
|
a generated Microsoft Visual Studio project file as the value of the
|
|
<code class="literal">SccProjectName</code> attribute if the
|
|
<code class="envar">MSVS_SCC_PROVIDER</code> construction variable is also set. In this
|
|
case the string is also placed in the <code class="literal">SccProjectName0</code>
|
|
attribute of the <code class="literal">GlobalSection(SourceCodeControl)</code> section
|
|
of the Microsoft Visual Studio solution file. There is no default value.
|
|
</p></dd><dt><a name="cv-MSVS_SCC_PROVIDER"></a><span class="term">MSVS_SCC_PROVIDER</span></dt><dd><p>The
|
|
string placed in a generated Microsoft Visual Studio project file as the value
|
|
of the <code class="literal">SccProvider</code> attribute. The string is also placed in
|
|
the <code class="literal">SccProvider0</code> attribute of the
|
|
<code class="literal">GlobalSection(SourceCodeControl)</code> section of the Microsoft
|
|
Visual Studio solution file. There is no default value. </p></dd><dt><a name="cv-MSVS_VERSION"></a><span class="term">MSVS_VERSION</span></dt><dd><p>Sets the preferred version
|
|
of Microsoft Visual Studio to use. </p><p>If <code class="envar">$MSVS_VERSION</code> is not
|
|
set, <span class="application">SCons</span> will (by default) select the latest version of Visual Studio
|
|
installed on your system. So, if you have version 6 and version 7 (MSVS .NET)
|
|
installed, it will prefer version 7. You can override this by specifying the
|
|
<code class="envar">MSVS_VERSION</code> variable in the Environment initialization,
|
|
setting it to the appropriate version ('6.0' or '7.0', for example). If the
|
|
specified version isn't installed, tool initialization will fail. </p><p>This is obsolete: use <code class="envar">$MSVC_VERSION</code> instead. If <code class="envar">$MSVS_VERSION</code> is
|
|
set and <code class="envar">$MSVC_VERSION</code> is not, <code class="envar">$MSVC_VERSION</code> will be set automatically
|
|
to <code class="envar">$MSVS_VERSION</code>. If both are set to different values, scons will raise an
|
|
error. </p></dd><dt><a name="cv-MSVSBUILDCOM"></a><span class="term">MSVSBUILDCOM</span></dt><dd><p>The build command line placed in a generated Microsoft Visual Studio
|
|
project file. The default is to have Visual Studio invoke SCons with any
|
|
specified build targets. </p></dd><dt><a name="cv-MSVSCLEANCOM"></a><span class="term">MSVSCLEANCOM</span></dt><dd><p>The clean command line placed in a generated Microsoft Visual
|
|
Studio project file. The default is to have Visual Studio invoke SCons with
|
|
the -c option to remove any specified targets. </p></dd><dt><a name="cv-MSVSENCODING"></a><span class="term">MSVSENCODING</span></dt><dd><p>The encoding string placed in a
|
|
generated Microsoft Visual Studio project file. The default is encoding
|
|
<code class="literal">Windows-1252</code>. </p></dd><dt><a name="cv-MSVSPROJECTCOM"></a><span class="term">MSVSPROJECTCOM</span></dt><dd><p>The action used to generate Microsoft
|
|
Visual Studio project files. </p></dd><dt><a name="cv-MSVSPROJECTSUFFIX"></a><span class="term">MSVSPROJECTSUFFIX</span></dt><dd><p>The suffix used for Microsoft Visual
|
|
Studio project (DSP) files. The default value is <code class="filename">.vcproj</code>
|
|
when using Visual Studio version 7.x (.NET) or later version, and
|
|
<code class="filename">.dsp</code> when using earlier versions of Visual Studio.
|
|
</p></dd><dt><a name="cv-MSVSREBUILDCOM"></a><span class="term">MSVSREBUILDCOM</span></dt><dd><p>The
|
|
rebuild command line placed in a generated Microsoft Visual Studio project
|
|
file. The default is to have Visual Studio invoke SCons with any specified
|
|
rebuild targets. </p></dd><dt><a name="cv-MSVSSCONS"></a><span class="term">MSVSSCONS</span></dt><dd><p>The SCons used in generated Microsoft Visual Studio project files. The
|
|
default is the version of SCons being used to generate the project file.
|
|
</p></dd><dt><a name="cv-MSVSSCONSCOM"></a><span class="term">MSVSSCONSCOM</span></dt><dd><p>The default
|
|
SCons command used in generated Microsoft Visual Studio project files. </p></dd><dt><a name="cv-MSVSSCONSCRIPT"></a><span class="term">MSVSSCONSCRIPT</span></dt><dd><p>The sconscript
|
|
file (that is, <code class="filename">SConstruct</code> or <code class="filename">SConscript</code> file) that will be invoked by
|
|
Visual Studio project files (through the <a class="link" href="#cv-MSVSSCONSCOM"><code class="envar">$MSVSSCONSCOM</code></a> variable). The
|
|
default is the same sconscript file that contains the call to <code class="function">MSVSProject</code>
|
|
to build the project file. </p></dd><dt><a name="cv-MSVSSCONSFLAGS"></a><span class="term">MSVSSCONSFLAGS</span></dt><dd><p>The
|
|
SCons flags used in generated Microsoft Visual Studio project files. </p></dd><dt><a name="cv-MSVSSOLUTIONCOM"></a><span class="term">MSVSSOLUTIONCOM</span></dt><dd><p>The action used to generate Microsoft
|
|
Visual Studio solution files. </p></dd><dt><a name="cv-MSVSSOLUTIONSUFFIX"></a><span class="term">MSVSSOLUTIONSUFFIX</span></dt><dd><p>The suffix used for Microsoft
|
|
Visual Studio solution (DSW) files. The default value is
|
|
<code class="filename">.sln</code> when using Visual Studio version 7.x (.NET), and
|
|
<code class="filename">.dsw</code> when using earlier versions of Visual Studio.
|
|
</p></dd><dt><a name="cv-MT"></a><span class="term">MT</span></dt><dd><p>
|
|
The program used on Windows systems to embed manifests into DLLs and EXEs.
|
|
See also <a class="link" href="#cv-WINDOWS_EMBED_MANIFEST"><code class="envar">$WINDOWS_EMBED_MANIFEST</code></a>.
|
|
</p></dd><dt><a name="cv-MTEXECOM"></a><span class="term">MTEXECOM</span></dt><dd><p>
|
|
The Windows command line used to embed manifests into executables.
|
|
See also <a class="link" href="#cv-MTSHLIBCOM"><code class="envar">$MTSHLIBCOM</code></a>.
|
|
</p></dd><dt><a name="cv-MTFLAGS"></a><span class="term">MTFLAGS</span></dt><dd><p>
|
|
Flags passed to the <a class="link" href="#cv-MT"><code class="envar">$MT</code></a> manifest embedding program (Windows only).
|
|
</p></dd><dt><a name="cv-MTSHLIBCOM"></a><span class="term">MTSHLIBCOM</span></dt><dd><p>
|
|
The Windows command line used to embed manifests into shared libraries (DLLs).
|
|
See also <a class="link" href="#cv-MTEXECOM"><code class="envar">$MTEXECOM</code></a>.
|
|
</p></dd><dt><a name="cv-MWCW_VERSION"></a><span class="term">MWCW_VERSION</span></dt><dd><p>
|
|
The version number of the MetroWerks CodeWarrior C compiler
|
|
to be used.
|
|
</p></dd><dt><a name="cv-MWCW_VERSIONS"></a><span class="term">MWCW_VERSIONS</span></dt><dd><p>
|
|
A list of installed versions of the MetroWerks CodeWarrior C compiler
|
|
on this system.
|
|
</p></dd><dt><a name="cv-NAME"></a><span class="term">NAME</span></dt><dd><p>
|
|
Specfies the name of the project to package.
|
|
</p></dd><dt><a name="cv-no_import_lib"></a><span class="term">no_import_lib</span></dt><dd><p>
|
|
When set to non-zero,
|
|
suppresses creation of a corresponding Windows static import lib by the
|
|
<code class="literal">SharedLibrary</code>
|
|
builder when used with
|
|
MinGW, Microsoft Visual Studio or Metrowerks.
|
|
This also suppresses creation
|
|
of an export (.exp) file
|
|
when using Microsoft Visual Studio.
|
|
</p></dd><dt><a name="cv-OBJPREFIX"></a><span class="term">OBJPREFIX</span></dt><dd><p>
|
|
The prefix used for (static) object file names.
|
|
</p></dd><dt><a name="cv-OBJSUFFIX"></a><span class="term">OBJSUFFIX</span></dt><dd><p>
|
|
The suffix used for (static) object file names.
|
|
</p></dd><dt><a name="cv-PACKAGEROOT"></a><span class="term">PACKAGEROOT</span></dt><dd><p>
|
|
Specifies the directory where all files in resulting archive will be
|
|
placed if applicable. The default value is "$NAME-$VERSION".
|
|
</p></dd><dt><a name="cv-PACKAGETYPE"></a><span class="term">PACKAGETYPE</span></dt><dd><p>
|
|
Selects the package type to build. Currently these are available:
|
|
</p><p>
|
|
* msi - Microsoft Installer
|
|
* rpm - Redhat Package Manger
|
|
* ipkg - Itsy Package Management System
|
|
* tarbz2 - compressed tar
|
|
* targz - compressed tar
|
|
* zip - zip file
|
|
* src_tarbz2 - compressed tar source
|
|
* src_targz - compressed tar source
|
|
* src_zip - zip file source
|
|
</p><p>
|
|
This may be overridden with the "package_type" command line option.
|
|
</p></dd><dt><a name="cv-PACKAGEVERSION"></a><span class="term">PACKAGEVERSION</span></dt><dd><p>
|
|
The version of the package (not the underlying project).
|
|
This is currently only used by the rpm packager
|
|
and should reflect changes in the packaging,
|
|
not the underlying project code itself.
|
|
</p></dd><dt><a name="cv-PCH"></a><span class="term">PCH</span></dt><dd><p>
|
|
The Microsoft Visual C++ precompiled header that will be used when compiling
|
|
object files. This variable is ignored by tools other than Microsoft Visual C++.
|
|
When this variable is
|
|
defined SCons will add options to the compiler command line to
|
|
cause it to use the precompiled header, and will also set up the
|
|
dependencies for the PCH file.
|
|
Example:
|
|
</p><pre class="screen">
|
|
env['PCH'] = 'StdAfx.pch'
|
|
</pre></dd><dt><a name="cv-PCHCOM"></a><span class="term">PCHCOM</span></dt><dd><p>
|
|
The command line used by the
|
|
<code class="function">PCH</code>
|
|
builder to generated a precompiled header.
|
|
</p></dd><dt><a name="cv-PCHCOMSTR"></a><span class="term">PCHCOMSTR</span></dt><dd><p>
|
|
The string displayed when generating a precompiled header.
|
|
If this is not set, then <a class="link" href="#cv-PCHCOM"><code class="envar">$PCHCOM</code></a> (the command line) is displayed.
|
|
</p></dd><dt><a name="cv-PCHPDBFLAGS"></a><span class="term">PCHPDBFLAGS</span></dt><dd><p>
|
|
A construction variable that, when expanded,
|
|
adds the <code class="literal">/yD</code> flag to the command line
|
|
only if the <code class="envar">$PDB</code> construction variable is set.
|
|
</p></dd><dt><a name="cv-PCHSTOP"></a><span class="term">PCHSTOP</span></dt><dd><p>
|
|
This variable specifies how much of a source file is precompiled. This
|
|
variable is ignored by tools other than Microsoft Visual C++, or when
|
|
the PCH variable is not being used. When this variable is define it
|
|
must be a string that is the name of the header that
|
|
is included at the end of the precompiled portion of the source files, or
|
|
the empty string if the "#pragma hrdstop" construct is being used:
|
|
</p><pre class="screen">
|
|
env['PCHSTOP'] = 'StdAfx.h'
|
|
</pre></dd><dt><a name="cv-PDB"></a><span class="term">PDB</span></dt><dd><p>
|
|
The Microsoft Visual C++ PDB file that will store debugging information for
|
|
object files, shared libraries, and programs. This variable is ignored by
|
|
tools other than Microsoft Visual C++.
|
|
When this variable is
|
|
defined SCons will add options to the compiler and linker command line to
|
|
cause them to generate external debugging information, and will also set up the
|
|
dependencies for the PDB file.
|
|
Example:
|
|
</p><pre class="screen">
|
|
env['PDB'] = 'hello.pdb'
|
|
</pre><p>
|
|
The Visual C++ compiler switch that SCons uses by default
|
|
to generate PDB information is <code class="option">/Z7</code>.
|
|
This works correctly with parallel (<code class="option">-j</code>) builds
|
|
because it embeds the debug information in the intermediate object files,
|
|
as opposed to sharing a single PDB file between multiple object files.
|
|
This is also the only way to get debug information
|
|
embedded into a static library.
|
|
Using the <code class="option">/Zi</code> instead may yield improved
|
|
link-time performance,
|
|
although parallel builds will no longer work.
|
|
You can generate PDB files with the <code class="option">/Zi</code>
|
|
switch by overriding the default <a class="link" href="#cv-CCPDBFLAGS"><code class="envar">$CCPDBFLAGS</code></a> variable;
|
|
see the entry for that variable for specific examples.
|
|
</p></dd><dt><a name="cv-PDFCOM"></a><span class="term">PDFCOM</span></dt><dd><p>
|
|
A deprecated synonym for <a class="link" href="#cv-DVIPDFCOM"><code class="envar">$DVIPDFCOM</code></a>.
|
|
</p></dd><dt><a name="cv-PDFLATEX"></a><span class="term">PDFLATEX</span></dt><dd><p>
|
|
The <span class="application">pdflatex</span> utility.
|
|
</p></dd><dt><a name="cv-PDFLATEXCOM"></a><span class="term">PDFLATEXCOM</span></dt><dd><p>
|
|
The command line used to call the <span class="application">pdflatex</span> utility.
|
|
</p></dd><dt><a name="cv-PDFLATEXCOMSTR"></a><span class="term">PDFLATEXCOMSTR</span></dt><dd><p>
|
|
The string displayed when calling the <span class="application">pdflatex</span> utility.
|
|
If this is not set, then <a class="link" href="#cv-PDFLATEXCOM"><code class="envar">$PDFLATEXCOM</code></a> (the command line) is displayed.
|
|
</p><pre class="screen">
|
|
env = Environment(PDFLATEX;COMSTR = "Building $TARGET from LaTeX input $SOURCES")
|
|
</pre></dd><dt><a name="cv-PDFLATEXFLAGS"></a><span class="term">PDFLATEXFLAGS</span></dt><dd><p>
|
|
General options passed to the <span class="application">pdflatex</span> utility.
|
|
</p></dd><dt><a name="cv-PDFPREFIX"></a><span class="term">PDFPREFIX</span></dt><dd><p>
|
|
The prefix used for PDF file names.
|
|
</p></dd><dt><a name="cv-PDFSUFFIX"></a><span class="term">PDFSUFFIX</span></dt><dd><p>
|
|
The suffix used for PDF file names.
|
|
</p></dd><dt><a name="cv-PDFTEX"></a><span class="term">PDFTEX</span></dt><dd><p>
|
|
The <span class="application">pdftex</span> utility.
|
|
</p></dd><dt><a name="cv-PDFTEXCOM"></a><span class="term">PDFTEXCOM</span></dt><dd><p>
|
|
The command line used to call the <span class="application">pdftex</span> utility.
|
|
</p></dd><dt><a name="cv-PDFTEXCOMSTR"></a><span class="term">PDFTEXCOMSTR</span></dt><dd><p>
|
|
The string displayed when calling the <span class="application">pdftex</span> utility.
|
|
If this is not set, then <a class="link" href="#cv-PDFTEXCOM"><code class="envar">$PDFTEXCOM</code></a> (the command line) is displayed.
|
|
</p><pre class="screen">
|
|
env = Environment(PDFTEXCOMSTR = "Building $TARGET from TeX input $SOURCES")
|
|
</pre></dd><dt><a name="cv-PDFTEXFLAGS"></a><span class="term">PDFTEXFLAGS</span></dt><dd><p>
|
|
General options passed to the <span class="application">pdftex</span> utility.
|
|
</p></dd><dt><a name="cv-PKGCHK"></a><span class="term">PKGCHK</span></dt><dd><p>
|
|
On Solaris systems,
|
|
the package-checking program that will
|
|
be used (along with <code class="envar">$PKGINFO</code>)
|
|
to look for installed versions of
|
|
the Sun PRO C++ compiler.
|
|
The default is
|
|
<code class="filename">/usr/sbin/pgkchk</code>.
|
|
</p></dd><dt><a name="cv-PKGINFO"></a><span class="term">PKGINFO</span></dt><dd><p>
|
|
On Solaris systems,
|
|
the package information program that will
|
|
be used (along with <code class="envar">$PKGCHK</code>)
|
|
to look for installed versions of
|
|
the Sun PRO C++ compiler.
|
|
The default is
|
|
<code class="filename">pkginfo</code>.
|
|
</p></dd><dt><a name="cv-PLATFORM"></a><span class="term">PLATFORM</span></dt><dd><p>
|
|
The name of the platform used to create the Environment. If no platform is
|
|
specified when the Environment is created,
|
|
<code class="filename">scons</code>
|
|
autodetects the platform.
|
|
</p><pre class="screen">
|
|
env = Environment(tools = [])
|
|
if env['PLATFORM'] == 'cygwin':
|
|
Tool('mingw')(env)
|
|
else:
|
|
Tool('msvc')(env)
|
|
</pre></dd><dt><a name="cv-POAUTOINIT"></a><span class="term">POAUTOINIT</span></dt><dd><p>
|
|
The <code class="envar">$POAUTOINIT</code> variable, if set to <code class="literal">True</code> (on non-zero
|
|
numeric value), let the <a class="link" href="#t-msginit"><code class="literal">msginit</code></a> tool to automatically initialize
|
|
<span class="emphasis"><em>missing</em></span> <code class="literal">PO</code> files with
|
|
<span class="command"><strong>msginit(1)</strong></span>. This applies to both,
|
|
<a class="link" href="#b-POInit"><code class="function">POInit</code></a> and <a class="link" href="#b-POUpdate"><code class="function">POUpdate</code></a> builders (and others that use any of
|
|
them).
|
|
</p></dd><dt><a name="cv-POCREATE_ALIAS"></a><span class="term">POCREATE_ALIAS</span></dt><dd><p>
|
|
Common alias for all <code class="literal">PO</code> files created with <code class="function">POInit</code>
|
|
builder (default: <code class="literal">'po-create'</code>).
|
|
See <a class="link" href="#t-msginit"><code class="literal">msginit</code></a> tool and <a class="link" href="#b-POInit"><code class="function">POInit</code></a> builder.
|
|
</p></dd><dt><a name="cv-POSUFFIX"></a><span class="term">POSUFFIX</span></dt><dd><p>
|
|
Suffix used for <code class="literal">PO</code> files (default: <code class="literal">'.po'</code>)
|
|
See <a class="link" href="#t-msginit"><code class="literal">msginit</code></a> tool and <a class="link" href="#b-POInit"><code class="function">POInit</code></a> builder.
|
|
</p></dd><dt><a name="cv-POTDOMAIN"></a><span class="term">POTDOMAIN</span></dt><dd><p>
|
|
The <code class="envar">$POTDOMAIN</code> defines default domain, used to generate
|
|
<code class="literal">POT</code> filename as <code class="filename"><code class="envar">$POTDOMAIN</code>.pot</code> when
|
|
no <code class="literal">POT</code> file name is provided by the user. This applies to
|
|
<a class="link" href="#b-POTUpdate"><code class="function">POTUpdate</code></a>, <a class="link" href="#b-POInit"><code class="function">POInit</code></a> and <a class="link" href="#b-POUpdate"><code class="function">POUpdate</code></a> builders (and
|
|
builders, that use them, e.g. <code class="function">Translate</code>). Normally (if <code class="envar">$POTDOMAIN</code> is
|
|
not defined), the builders use <code class="filename">messages.pot</code> as default
|
|
<code class="literal">POT</code> file name.
|
|
</p></dd><dt><a name="cv-POTSUFFIX"></a><span class="term">POTSUFFIX</span></dt><dd><p>
|
|
Suffix used for PO Template files (default: <code class="literal">'.pot'</code>).
|
|
See <a class="link" href="#t-xgettext"><code class="literal">xgettext</code></a> tool and <a class="link" href="#b-POTUpdate"><code class="function">POTUpdate</code></a> builder.
|
|
</p></dd><dt><a name="cv-POTUPDATE_ALIAS"></a><span class="term">POTUPDATE_ALIAS</span></dt><dd><p>
|
|
Name of the common phony target for all PO Templates created with
|
|
<a class="link" href="#b-POUpdate"><code class="function">POUpdate</code></a> (default: <code class="literal">'pot-update'</code>).
|
|
See <a class="link" href="#t-xgettext"><code class="literal">xgettext</code></a> tool and <a class="link" href="#b-POTUpdate"><code class="function">POTUpdate</code></a> builder.
|
|
</p></dd><dt><a name="cv-POUPDATE_ALIAS"></a><span class="term">POUPDATE_ALIAS</span></dt><dd><p>
|
|
Common alias for all <code class="literal">PO</code> files being defined with
|
|
<a class="link" href="#b-POUpdate"><code class="function">POUpdate</code></a> builder (default: <code class="literal">'po-update'</code>).
|
|
See <a class="link" href="#t-msgmerge"><code class="literal">msgmerge</code></a> tool and <a class="link" href="#b-POUpdate"><code class="function">POUpdate</code></a> builder.
|
|
</p></dd><dt><a name="cv-PRINT_CMD_LINE_FUNC"></a><span class="term">PRINT_CMD_LINE_FUNC</span></dt><dd><p>
|
|
A Python function used to print the command lines as they are executed
|
|
(assuming command printing is not disabled by the
|
|
<code class="option">-q</code>
|
|
or
|
|
<code class="option">-s</code>
|
|
options or their equivalents).
|
|
The function should take four arguments:
|
|
<code class="varname">s</code>,
|
|
the command being executed (a string),
|
|
<code class="varname">target</code>,
|
|
the target being built (file node, list, or string name(s)),
|
|
<code class="varname">source</code>,
|
|
the source(s) used (file node, list, or string name(s)), and
|
|
<code class="varname">env</code>,
|
|
the environment being used.
|
|
</p><p>
|
|
The function must do the printing itself. The default implementation,
|
|
used if this variable is not set or is None, is:
|
|
</p><pre class="screen">
|
|
def print_cmd_line(s, target, source, env):
|
|
sys.stdout.write(s + "\n")
|
|
</pre><p>
|
|
Here's an example of a more interesting function:
|
|
</p><pre class="screen">
|
|
def print_cmd_line(s, target, source, env):
|
|
sys.stdout.write("Building %s -> %s...\n" %
|
|
(' and '.join([str(x) for x in source]),
|
|
' and '.join([str(x) for x in target])))
|
|
env=Environment(PRINT_CMD_LINE_FUNC=print_cmd_line)
|
|
env.Program('foo', 'foo.c')
|
|
</pre><p>
|
|
This just prints "Building <code class="varname">targetname</code> from <code class="varname">sourcename</code>..." instead
|
|
of the actual commands.
|
|
Such a function could also log the actual commands to a log file,
|
|
for example.
|
|
</p></dd><dt><a name="cv-PROGEMITTER"></a><span class="term">PROGEMITTER</span></dt><dd><p>
|
|
TODO
|
|
</p></dd><dt><a name="cv-PROGPREFIX"></a><span class="term">PROGPREFIX</span></dt><dd><p>
|
|
The prefix used for executable file names.
|
|
</p></dd><dt><a name="cv-PROGSUFFIX"></a><span class="term">PROGSUFFIX</span></dt><dd><p>
|
|
The suffix used for executable file names.
|
|
</p></dd><dt><a name="cv-PSCOM"></a><span class="term">PSCOM</span></dt><dd><p>
|
|
The command line used to convert TeX DVI files into a PostScript file.
|
|
</p></dd><dt><a name="cv-PSCOMSTR"></a><span class="term">PSCOMSTR</span></dt><dd><p>
|
|
The string displayed when a TeX DVI file
|
|
is converted into a PostScript file.
|
|
If this is not set, then <a class="link" href="#cv-PSCOM"><code class="envar">$PSCOM</code></a> (the command line) is displayed.
|
|
</p></dd><dt><a name="cv-PSPREFIX"></a><span class="term">PSPREFIX</span></dt><dd><p>
|
|
The prefix used for PostScript file names.
|
|
</p></dd><dt><a name="cv-PSSUFFIX"></a><span class="term">PSSUFFIX</span></dt><dd><p>
|
|
The prefix used for PostScript file names.
|
|
</p></dd><dt><a name="cv-QT_AUTOSCAN"></a><span class="term">QT_AUTOSCAN</span></dt><dd><p>
|
|
Turn off scanning for mocable files. Use the Moc Builder to explicitly
|
|
specify files to run moc on.
|
|
</p></dd><dt><a name="cv-QT_BINPATH"></a><span class="term">QT_BINPATH</span></dt><dd><p>
|
|
The path where the qt binaries are installed.
|
|
The default value is '<a class="link" href="#cv-QTDIR"><code class="envar">$QTDIR</code></a>/bin'.
|
|
</p></dd><dt><a name="cv-QT_CPPPATH"></a><span class="term">QT_CPPPATH</span></dt><dd><p>
|
|
The path where the qt header files are installed.
|
|
The default value is '<a class="link" href="#cv-QTDIR"><code class="envar">$QTDIR</code></a>/include'.
|
|
Note: If you set this variable to None,
|
|
the tool won't change the <a class="link" href="#cv-CPPPATH"><code class="envar">$CPPPATH</code></a>
|
|
construction variable.
|
|
</p></dd><dt><a name="cv-QT_DEBUG"></a><span class="term">QT_DEBUG</span></dt><dd><p>
|
|
Prints lots of debugging information while scanning for moc files.
|
|
</p></dd><dt><a name="cv-QT_LIB"></a><span class="term">QT_LIB</span></dt><dd><p>
|
|
Default value is 'qt'. You may want to set this to 'qt-mt'. Note: If you set
|
|
this variable to None, the tool won't change the <a class="link" href="#cv-LIBS"><code class="envar">$LIBS</code></a> variable.
|
|
</p></dd><dt><a name="cv-QT_LIBPATH"></a><span class="term">QT_LIBPATH</span></dt><dd><p>
|
|
The path where the qt libraries are installed.
|
|
The default value is '<a class="link" href="#cv-QTDIR"><code class="envar">$QTDIR</code></a>/lib'.
|
|
Note: If you set this variable to None,
|
|
the tool won't change the <a class="link" href="#cv-LIBPATH"><code class="envar">$LIBPATH</code></a>
|
|
construction variable.
|
|
</p></dd><dt><a name="cv-QT_MOC"></a><span class="term">QT_MOC</span></dt><dd><p>
|
|
Default value is '<a class="link" href="#cv-QT_BINPATH"><code class="envar">$QT_BINPATH</code></a>/moc'.
|
|
</p></dd><dt><a name="cv-QT_MOCCXXPREFIX"></a><span class="term">QT_MOCCXXPREFIX</span></dt><dd><p>
|
|
Default value is ''. Prefix for moc output files, when source is a cxx file.
|
|
</p></dd><dt><a name="cv-QT_MOCCXXSUFFIX"></a><span class="term">QT_MOCCXXSUFFIX</span></dt><dd><p>
|
|
Default value is '.moc'. Suffix for moc output files, when source is a cxx
|
|
file.
|
|
</p></dd><dt><a name="cv-QT_MOCFROMCXXCOM"></a><span class="term">QT_MOCFROMCXXCOM</span></dt><dd><p>
|
|
Command to generate a moc file from a cpp file.
|
|
</p></dd><dt><a name="cv-QT_MOCFROMCXXCOMSTR"></a><span class="term">QT_MOCFROMCXXCOMSTR</span></dt><dd><p>
|
|
The string displayed when generating a moc file from a cpp file.
|
|
If this is not set, then <a class="link" href="#cv-QT_MOCFROMCXXCOM"><code class="envar">$QT_MOCFROMCXXCOM</code></a> (the command line) is displayed.
|
|
</p></dd><dt><a name="cv-QT_MOCFROMCXXFLAGS"></a><span class="term">QT_MOCFROMCXXFLAGS</span></dt><dd><p>
|
|
Default value is '-i'. These flags are passed to moc, when moccing a
|
|
C++ file.
|
|
</p></dd><dt><a name="cv-QT_MOCFROMHCOM"></a><span class="term">QT_MOCFROMHCOM</span></dt><dd><p>
|
|
Command to generate a moc file from a header.
|
|
</p></dd><dt><a name="cv-QT_MOCFROMHCOMSTR"></a><span class="term">QT_MOCFROMHCOMSTR</span></dt><dd><p>
|
|
The string displayed when generating a moc file from a cpp file.
|
|
If this is not set, then <a class="link" href="#cv-QT_MOCFROMHCOM"><code class="envar">$QT_MOCFROMHCOM</code></a> (the command line) is displayed.
|
|
</p></dd><dt><a name="cv-QT_MOCFROMHFLAGS"></a><span class="term">QT_MOCFROMHFLAGS</span></dt><dd><p>
|
|
Default value is ''. These flags are passed to moc, when moccing a header
|
|
file.
|
|
</p></dd><dt><a name="cv-QT_MOCHPREFIX"></a><span class="term">QT_MOCHPREFIX</span></dt><dd><p>
|
|
Default value is 'moc_'. Prefix for moc output files, when source is a header.
|
|
</p></dd><dt><a name="cv-QT_MOCHSUFFIX"></a><span class="term">QT_MOCHSUFFIX</span></dt><dd><p>
|
|
Default value is '<a class="link" href="#cv-CXXFILESUFFIX"><code class="envar">$CXXFILESUFFIX</code></a>'. Suffix for moc output files, when source is
|
|
a header.
|
|
</p></dd><dt><a name="cv-QT_UIC"></a><span class="term">QT_UIC</span></dt><dd><p>
|
|
Default value is '<a class="link" href="#cv-QT_BINPATH"><code class="envar">$QT_BINPATH</code></a>/uic'.
|
|
</p></dd><dt><a name="cv-QT_UICCOM"></a><span class="term">QT_UICCOM</span></dt><dd><p>
|
|
Command to generate header files from .ui files.
|
|
</p></dd><dt><a name="cv-QT_UICCOMSTR"></a><span class="term">QT_UICCOMSTR</span></dt><dd><p>
|
|
The string displayed when generating header files from .ui files.
|
|
If this is not set, then <a class="link" href="#cv-QT_UICCOM"><code class="envar">$QT_UICCOM</code></a> (the command line) is displayed.
|
|
</p></dd><dt><a name="cv-QT_UICDECLFLAGS"></a><span class="term">QT_UICDECLFLAGS</span></dt><dd><p>
|
|
Default value is ''. These flags are passed to uic, when creating a a h
|
|
file from a .ui file.
|
|
</p></dd><dt><a name="cv-QT_UICDECLPREFIX"></a><span class="term">QT_UICDECLPREFIX</span></dt><dd><p>
|
|
Default value is ''. Prefix for uic generated header files.
|
|
</p></dd><dt><a name="cv-QT_UICDECLSUFFIX"></a><span class="term">QT_UICDECLSUFFIX</span></dt><dd><p>
|
|
Default value is '.h'. Suffix for uic generated header files.
|
|
</p></dd><dt><a name="cv-QT_UICIMPLFLAGS"></a><span class="term">QT_UICIMPLFLAGS</span></dt><dd><p>
|
|
Default value is ''. These flags are passed to uic, when creating a cxx
|
|
file from a .ui file.
|
|
</p></dd><dt><a name="cv-QT_UICIMPLPREFIX"></a><span class="term">QT_UICIMPLPREFIX</span></dt><dd><p>
|
|
Default value is 'uic_'. Prefix for uic generated implementation files.
|
|
</p></dd><dt><a name="cv-QT_UICIMPLSUFFIX"></a><span class="term">QT_UICIMPLSUFFIX</span></dt><dd><p>
|
|
Default value is '<a class="link" href="#cv-CXXFILESUFFIX"><code class="envar">$CXXFILESUFFIX</code></a>'. Suffix for uic generated implementation
|
|
files.
|
|
</p></dd><dt><a name="cv-QT_UISUFFIX"></a><span class="term">QT_UISUFFIX</span></dt><dd><p>
|
|
Default value is '.ui'. Suffix of designer input files.
|
|
</p></dd><dt><a name="cv-QTDIR"></a><span class="term">QTDIR</span></dt><dd><p>
|
|
The qt tool tries to take this from os.environ.
|
|
It also initializes all QT_*
|
|
construction variables listed below.
|
|
(Note that all paths are constructed
|
|
with python's os.path.join() method,
|
|
but are listed here with the '/' separator
|
|
for easier reading.)
|
|
In addition, the construction environment
|
|
variables <a class="link" href="#cv-CPPPATH"><code class="envar">$CPPPATH</code></a>,
|
|
<a class="link" href="#cv-LIBPATH"><code class="envar">$LIBPATH</code></a> and
|
|
<a class="link" href="#cv-LIBS"><code class="envar">$LIBS</code></a> may be modified
|
|
and the variables
|
|
<a class="link" href="#cv-PROGEMITTER"><code class="envar">$PROGEMITTER</code></a>, <a class="link" href="#cv-SHLIBEMITTER"><code class="envar">$SHLIBEMITTER</code></a> and <a class="link" href="#cv-LIBEMITTER"><code class="envar">$LIBEMITTER</code></a>
|
|
are modified. Because the build-performance is affected when using this tool,
|
|
you have to explicitly specify it at Environment creation:
|
|
</p><pre class="screen">
|
|
Environment(tools=['default','qt'])
|
|
</pre><p>
|
|
The qt tool supports the following operations:
|
|
</p><p>
|
|
<span class="strong"><strong>Automatic moc file generation from header files.</strong></span>
|
|
You do not have to specify moc files explicitly, the tool does it for you.
|
|
However, there are a few preconditions to do so: Your header file must have
|
|
the same filebase as your implementation file and must stay in the same
|
|
directory. It must have one of the suffixes .h, .hpp, .H, .hxx, .hh. You
|
|
can turn off automatic moc file generation by setting QT_AUTOSCAN to 0.
|
|
See also the corresponding
|
|
<code class="function">Moc</code>()
|
|
builder method.
|
|
</p><p>
|
|
<span class="strong"><strong>Automatic moc file generation from cxx files.</strong></span>
|
|
As stated in the qt documentation, include the moc file at the end of
|
|
the cxx file. Note that you have to include the file, which is generated
|
|
by the transformation ${QT_MOCCXXPREFIX}<basename>${QT_MOCCXXSUFFIX}, by default
|
|
<basename>.moc. A warning is generated after building the moc file, if you
|
|
do not include the correct file. If you are using VariantDir, you may
|
|
need to specify duplicate=1. You can turn off automatic moc file generation
|
|
by setting QT_AUTOSCAN to 0. See also the corresponding
|
|
<code class="function">Moc</code>
|
|
builder method.
|
|
</p><p>
|
|
<span class="strong"><strong>Automatic handling of .ui files.</strong></span>
|
|
The implementation files generated from .ui files are handled much the same
|
|
as yacc or lex files. Each .ui file given as a source of Program, Library or
|
|
SharedLibrary will generate three files, the declaration file, the
|
|
implementation file and a moc file. Because there are also generated headers,
|
|
you may need to specify duplicate=1 in calls to VariantDir.
|
|
See also the corresponding
|
|
<code class="function">Uic</code>
|
|
builder method.
|
|
</p></dd><dt><a name="cv-RANLIB"></a><span class="term">RANLIB</span></dt><dd><p>
|
|
The archive indexer.
|
|
</p></dd><dt><a name="cv-RANLIBCOM"></a><span class="term">RANLIBCOM</span></dt><dd><p>
|
|
The command line used to index a static library archive.
|
|
</p></dd><dt><a name="cv-RANLIBCOMSTR"></a><span class="term">RANLIBCOMSTR</span></dt><dd><p>
|
|
The string displayed when a static library archive is indexed.
|
|
If this is not set, then <a class="link" href="#cv-RANLIBCOM"><code class="envar">$RANLIBCOM</code></a> (the command line) is displayed.
|
|
</p><pre class="screen">
|
|
env = Environment(RANLIBCOMSTR = "Indexing $TARGET")
|
|
</pre></dd><dt><a name="cv-RANLIBFLAGS"></a><span class="term">RANLIBFLAGS</span></dt><dd><p>
|
|
General options passed to the archive indexer.
|
|
</p></dd><dt><a name="cv-RC"></a><span class="term">RC</span></dt><dd><p>
|
|
The resource compiler used to build
|
|
a Microsoft Visual C++ resource file.
|
|
</p></dd><dt><a name="cv-RCCOM"></a><span class="term">RCCOM</span></dt><dd><p>
|
|
The command line used to build
|
|
a Microsoft Visual C++ resource file.
|
|
</p></dd><dt><a name="cv-RCCOMSTR"></a><span class="term">RCCOMSTR</span></dt><dd><p>
|
|
The string displayed when invoking the resource compiler
|
|
to build a Microsoft Visual C++ resource file.
|
|
If this is not set, then <a class="link" href="#cv-RCCOM"><code class="envar">$RCCOM</code></a> (the command line) is displayed.
|
|
</p></dd><dt><a name="cv-RCFLAGS"></a><span class="term">RCFLAGS</span></dt><dd><p>
|
|
The flags passed to the resource compiler by the RES builder.
|
|
</p></dd><dt><a name="cv-RCINCFLAGS"></a><span class="term">RCINCFLAGS</span></dt><dd><p>
|
|
An automatically-generated construction variable
|
|
containing the command-line options
|
|
for specifying directories to be searched
|
|
by the resource compiler.
|
|
The value of <code class="envar">$RCINCFLAGS</code> is created
|
|
by respectively prepending and appending
|
|
<code class="envar">$RCINCPREFIX</code> and <code class="envar">$RCINCSUFFIX</code>
|
|
to the beginning and end
|
|
of each directory in <code class="envar">$CPPPATH</code>.
|
|
</p></dd><dt><a name="cv-RCINCPREFIX"></a><span class="term">RCINCPREFIX</span></dt><dd><p>
|
|
The prefix (flag) used to specify an include directory
|
|
on the resource compiler command line.
|
|
This will be prepended to the beginning of each directory
|
|
in the <code class="envar">$CPPPATH</code> construction variable
|
|
when the <code class="envar">$RCINCFLAGS</code> variable is expanded.
|
|
</p></dd><dt><a name="cv-RCINCSUFFIX"></a><span class="term">RCINCSUFFIX</span></dt><dd><p>
|
|
The suffix used to specify an include directory
|
|
on the resource compiler command line.
|
|
This will be appended to the end of each directory
|
|
in the <code class="envar">$CPPPATH</code> construction variable
|
|
when the <code class="envar">$RCINCFLAGS</code> variable is expanded.
|
|
</p></dd><dt><a name="cv-RDirs"></a><span class="term">RDirs</span></dt><dd><p>
|
|
A function that converts a string into a list of Dir instances by
|
|
searching the repositories.
|
|
</p></dd><dt><a name="cv-REGSVR"></a><span class="term">REGSVR</span></dt><dd><p>
|
|
The program used on Windows systems
|
|
to register a newly-built DLL library
|
|
whenever the <code class="function">SharedLibrary</code> builder
|
|
is passed a keyword argument of <code class="literal">register=1</code>.
|
|
</p></dd><dt><a name="cv-REGSVRCOM"></a><span class="term">REGSVRCOM</span></dt><dd><p>
|
|
The command line used on Windows systems
|
|
to register a newly-built DLL library
|
|
whenever the <code class="function">SharedLibrary</code> builder
|
|
is passed a keyword argument of <code class="literal">register=1</code>.
|
|
</p></dd><dt><a name="cv-REGSVRCOMSTR"></a><span class="term">REGSVRCOMSTR</span></dt><dd><p>
|
|
The string displayed when registering a newly-built DLL file.
|
|
If this is not set, then <a class="link" href="#cv-REGSVRCOM"><code class="envar">$REGSVRCOM</code></a> (the command line) is displayed.
|
|
</p></dd><dt><a name="cv-REGSVRFLAGS"></a><span class="term">REGSVRFLAGS</span></dt><dd><p>
|
|
Flags passed to the DLL registration program
|
|
on Windows systems when a newly-built DLL library is registered.
|
|
By default,
|
|
this includes the <code class="option">/s</code>
|
|
that prevents dialog boxes from popping up
|
|
and requiring user attention.
|
|
</p></dd><dt><a name="cv-RMIC"></a><span class="term">RMIC</span></dt><dd><p>
|
|
The Java RMI stub compiler.
|
|
</p></dd><dt><a name="cv-RMICCOM"></a><span class="term">RMICCOM</span></dt><dd><p>
|
|
The command line used to compile stub
|
|
and skeleton class files
|
|
from Java classes that contain RMI implementations.
|
|
Any options specified in the <a class="link" href="#cv-RMICFLAGS"><code class="envar">$RMICFLAGS</code></a> construction variable
|
|
are included on this command line.
|
|
</p></dd><dt><a name="cv-RMICCOMSTR"></a><span class="term">RMICCOMSTR</span></dt><dd><p>
|
|
The string displayed when compiling
|
|
stub and skeleton class files
|
|
from Java classes that contain RMI implementations.
|
|
If this is not set, then <a class="link" href="#cv-RMICCOM"><code class="envar">$RMICCOM</code></a> (the command line) is displayed.
|
|
</p><pre class="screen">
|
|
env = Environment(RMICCOMSTR = "Generating stub/skeleton class files $TARGETS from $SOURCES")
|
|
</pre></dd><dt><a name="cv-RMICFLAGS"></a><span class="term">RMICFLAGS</span></dt><dd><p>
|
|
General options passed to the Java RMI stub compiler.
|
|
</p></dd><dt><a name="cv-_RPATH"></a><span class="term">_RPATH</span></dt><dd><p>
|
|
An automatically-generated construction variable
|
|
containing the rpath flags to be used when linking
|
|
a program with shared libraries.
|
|
The value of <code class="envar">$_RPATH</code> is created
|
|
by respectively prepending <code class="envar">$RPATHPREFIX</code> and appending <code class="envar">$RPATHSUFFIX</code>
|
|
to the beginning and end
|
|
of each directory in <code class="envar">$RPATH</code>.
|
|
</p></dd><dt><a name="cv-RPATH"></a><span class="term">RPATH</span></dt><dd><p>
|
|
A list of paths to search for shared libraries when running programs.
|
|
Currently only used in the GNU (gnulink),
|
|
IRIX (sgilink) and Sun (sunlink) linkers.
|
|
Ignored on platforms and toolchains that don't support it.
|
|
Note that the paths added to RPATH
|
|
are not transformed by
|
|
<code class="filename">scons</code>
|
|
in any way: if you want an absolute
|
|
path, you must make it absolute yourself.
|
|
</p></dd><dt><a name="cv-RPATHPREFIX"></a><span class="term">RPATHPREFIX</span></dt><dd><p>
|
|
The prefix used to specify a directory to be searched for
|
|
shared libraries when running programs.
|
|
This will be prepended to the beginning of each directory
|
|
in the <code class="envar">$RPATH</code> construction variable
|
|
when the <code class="envar">$_RPATH</code> variable is automatically generated.
|
|
</p></dd><dt><a name="cv-RPATHSUFFIX"></a><span class="term">RPATHSUFFIX</span></dt><dd><p>
|
|
The suffix used to specify a directory to be searched for
|
|
shared libraries when running programs.
|
|
This will be appended to the end of each directory
|
|
in the <code class="envar">$RPATH</code> construction variable
|
|
when the <code class="envar">$_RPATH</code> variable is automatically generated.
|
|
</p></dd><dt><a name="cv-RPCGEN"></a><span class="term">RPCGEN</span></dt><dd><p>
|
|
The RPC protocol compiler.
|
|
</p></dd><dt><a name="cv-RPCGENCLIENTFLAGS"></a><span class="term">RPCGENCLIENTFLAGS</span></dt><dd><p>
|
|
Options passed to the RPC protocol compiler
|
|
when generating client side stubs.
|
|
These are in addition to any flags specified in the
|
|
<a class="link" href="#cv-RPCGENFLAGS"><code class="envar">$RPCGENFLAGS</code></a>
|
|
construction variable.
|
|
</p></dd><dt><a name="cv-RPCGENFLAGS"></a><span class="term">RPCGENFLAGS</span></dt><dd><p>
|
|
General options passed to the RPC protocol compiler.
|
|
</p></dd><dt><a name="cv-RPCGENHEADERFLAGS"></a><span class="term">RPCGENHEADERFLAGS</span></dt><dd><p>
|
|
Options passed to the RPC protocol compiler
|
|
when generating a header file.
|
|
These are in addition to any flags specified in the
|
|
<a class="link" href="#cv-RPCGENFLAGS"><code class="envar">$RPCGENFLAGS</code></a>
|
|
construction variable.
|
|
</p></dd><dt><a name="cv-RPCGENSERVICEFLAGS"></a><span class="term">RPCGENSERVICEFLAGS</span></dt><dd><p>
|
|
Options passed to the RPC protocol compiler
|
|
when generating server side stubs.
|
|
These are in addition to any flags specified in the
|
|
<a class="link" href="#cv-RPCGENFLAGS"><code class="envar">$RPCGENFLAGS</code></a>
|
|
construction variable.
|
|
</p></dd><dt><a name="cv-RPCGENXDRFLAGS"></a><span class="term">RPCGENXDRFLAGS</span></dt><dd><p>
|
|
Options passed to the RPC protocol compiler
|
|
when generating XDR routines.
|
|
These are in addition to any flags specified in the
|
|
<a class="link" href="#cv-RPCGENFLAGS"><code class="envar">$RPCGENFLAGS</code></a>
|
|
construction variable.
|
|
</p></dd><dt><a name="cv-SCANNERS"></a><span class="term">SCANNERS</span></dt><dd><p>
|
|
A list of the available implicit dependency scanners.
|
|
New file scanners may be added by
|
|
appending to this list,
|
|
although the more flexible approach
|
|
is to associate scanners
|
|
with a specific Builder.
|
|
See the sections "Builder Objects"
|
|
and "Scanner Objects,"
|
|
below, for more information.
|
|
</p></dd><dt><a name="cv-SCONS_HOME"></a><span class="term">SCONS_HOME</span></dt><dd><p>The
|
|
(optional) path to the SCons library directory, initialized from the external
|
|
environment. If set, this is used to construct a shorter and more efficient
|
|
search path in the <a class="link" href="#cv-MSVSSCONS"><code class="envar">$MSVSSCONS</code></a> command line executed from Microsoft
|
|
Visual Studio project files. </p></dd><dt><a name="cv-SHCC"></a><span class="term">SHCC</span></dt><dd><p>
|
|
The C compiler used for generating shared-library objects.
|
|
</p></dd><dt><a name="cv-SHCCCOM"></a><span class="term">SHCCCOM</span></dt><dd><p>
|
|
The command line used to compile a C source file
|
|
to a shared-library object file.
|
|
Any options specified in the <a class="link" href="#cv-SHCFLAGS"><code class="envar">$SHCFLAGS</code></a>,
|
|
<a class="link" href="#cv-SHCCFLAGS"><code class="envar">$SHCCFLAGS</code></a> and
|
|
<a class="link" href="#cv-CPPFLAGS"><code class="envar">$CPPFLAGS</code></a> construction variables
|
|
are included on this command line.
|
|
</p></dd><dt><a name="cv-SHCCCOMSTR"></a><span class="term">SHCCCOMSTR</span></dt><dd><p>
|
|
The string displayed when a C source file
|
|
is compiled to a shared object file.
|
|
If this is not set, then <a class="link" href="#cv-SHCCCOM"><code class="envar">$SHCCCOM</code></a> (the command line) is displayed.
|
|
</p><pre class="screen">
|
|
env = Environment(SHCCCOMSTR = "Compiling shared object $TARGET")
|
|
</pre></dd><dt><a name="cv-SHCCFLAGS"></a><span class="term">SHCCFLAGS</span></dt><dd><p>
|
|
Options that are passed to the C and C++ compilers
|
|
to generate shared-library objects.
|
|
</p></dd><dt><a name="cv-SHCFLAGS"></a><span class="term">SHCFLAGS</span></dt><dd><p>
|
|
Options that are passed to the C compiler (only; not C++)
|
|
to generate shared-library objects.
|
|
</p></dd><dt><a name="cv-SHCXX"></a><span class="term">SHCXX</span></dt><dd><p>
|
|
The C++ compiler used for generating shared-library objects.
|
|
</p></dd><dt><a name="cv-SHCXXCOM"></a><span class="term">SHCXXCOM</span></dt><dd><p>
|
|
The command line used to compile a C++ source file
|
|
to a shared-library object file.
|
|
Any options specified in the <a class="link" href="#cv-SHCXXFLAGS"><code class="envar">$SHCXXFLAGS</code></a> and
|
|
<a class="link" href="#cv-CPPFLAGS"><code class="envar">$CPPFLAGS</code></a> construction variables
|
|
are included on this command line.
|
|
</p></dd><dt><a name="cv-SHCXXCOMSTR"></a><span class="term">SHCXXCOMSTR</span></dt><dd><p>
|
|
The string displayed when a C++ source file
|
|
is compiled to a shared object file.
|
|
If this is not set, then <a class="link" href="#cv-SHCXXCOM"><code class="envar">$SHCXXCOM</code></a> (the command line) is displayed.
|
|
</p><pre class="screen">
|
|
env = Environment(SHCXXCOMSTR = "Compiling shared object $TARGET")
|
|
</pre></dd><dt><a name="cv-SHCXXFLAGS"></a><span class="term">SHCXXFLAGS</span></dt><dd><p>
|
|
Options that are passed to the C++ compiler
|
|
to generate shared-library objects.
|
|
</p></dd><dt><a name="cv-SHDC"></a><span class="term">SHDC</span></dt><dd><p>
|
|
The name of the compiler to use when compiling D source
|
|
destined to be in a shared objects.
|
|
</p><p>
|
|
The name of the compiler to use when compiling D source
|
|
destined to be in a shared objects.
|
|
</p><p>
|
|
The name of the compiler to use when compiling D source
|
|
destined to be in a shared objects.
|
|
</p></dd><dt><a name="cv-SHDCOM"></a><span class="term">SHDCOM</span></dt><dd><p>
|
|
The command line to use when compiling code to be part of shared objects.
|
|
</p><p>
|
|
The command line to use when compiling code to be part of shared objects.
|
|
</p><p>
|
|
The command line to use when compiling code to be part of shared objects.
|
|
</p></dd><dt><a name="cv-SHDLIBVERSION"></a><span class="term">SHDLIBVERSION</span></dt><dd><p>
|
|
SHDLIBVERSION.
|
|
</p></dd><dt><a name="cv-SHDLIBVERSIONFLAGS"></a><span class="term">SHDLIBVERSIONFLAGS</span></dt><dd><p>
|
|
SHDLIBVERSIONFLAGS.
|
|
</p></dd><dt><a name="cv-SHDLINK"></a><span class="term">SHDLINK</span></dt><dd><p>
|
|
The linker to use when creating shared objects for code bases
|
|
include D sources.
|
|
</p><p>
|
|
The linker to use when creating shared objects for code bases
|
|
include D sources.
|
|
</p><p>
|
|
The linker to use when creating shared objects for code bases
|
|
include D sources.
|
|
</p></dd><dt><a name="cv-SHDLINKCOM"></a><span class="term">SHDLINKCOM</span></dt><dd><p>
|
|
The command line to use when generating shared objects.
|
|
</p><p>
|
|
The command line to use when generating shared objects.
|
|
</p><p>
|
|
The command line to use when generating shared objects.
|
|
</p></dd><dt><a name="cv-SHDLINKFLAGS"></a><span class="term">SHDLINKFLAGS</span></dt><dd><p>
|
|
The list of flags to use when generating a shared object.
|
|
</p><p>
|
|
The list of flags to use when generating a shared object.
|
|
</p><p>
|
|
The list of flags to use when generating a shared object.
|
|
</p></dd><dt><a name="cv-SHELL"></a><span class="term">SHELL</span></dt><dd><p>
|
|
A string naming the shell program that will be passed to the
|
|
<code class="envar">$SPAWN</code>
|
|
function.
|
|
See the
|
|
<code class="envar">$SPAWN</code>
|
|
construction variable for more information.
|
|
</p></dd><dt><a name="cv-SHF03"></a><span class="term">SHF03</span></dt><dd><p>
|
|
The Fortran 03 compiler used for generating shared-library objects.
|
|
You should normally set the <a class="link" href="#cv-SHFORTRAN"><code class="envar">$SHFORTRAN</code></a> variable,
|
|
which specifies the default Fortran compiler
|
|
for all Fortran versions.
|
|
You only need to set <a class="link" href="#cv-SHF03"><code class="envar">$SHF03</code></a> if you need to use a specific compiler
|
|
or compiler version for Fortran 03 files.
|
|
</p></dd><dt><a name="cv-SHF03COM"></a><span class="term">SHF03COM</span></dt><dd><p>
|
|
The command line used to compile a Fortran 03 source file
|
|
to a shared-library object file.
|
|
You only need to set <a class="link" href="#cv-SHF03COM"><code class="envar">$SHF03COM</code></a> if you need to use a specific
|
|
command line for Fortran 03 files.
|
|
You should normally set the <a class="link" href="#cv-SHFORTRANCOM"><code class="envar">$SHFORTRANCOM</code></a> variable,
|
|
which specifies the default command line
|
|
for all Fortran versions.
|
|
</p></dd><dt><a name="cv-SHF03COMSTR"></a><span class="term">SHF03COMSTR</span></dt><dd><p>
|
|
The string displayed when a Fortran 03 source file
|
|
is compiled to a shared-library object file.
|
|
If this is not set, then <a class="link" href="#cv-SHF03COM"><code class="envar">$SHF03COM</code></a> or <a class="link" href="#cv-SHFORTRANCOM"><code class="envar">$SHFORTRANCOM</code></a>
|
|
(the command line) is displayed.
|
|
</p></dd><dt><a name="cv-SHF03FLAGS"></a><span class="term">SHF03FLAGS</span></dt><dd><p>
|
|
Options that are passed to the Fortran 03 compiler
|
|
to generated shared-library objects.
|
|
You only need to set <a class="link" href="#cv-SHF03FLAGS"><code class="envar">$SHF03FLAGS</code></a> if you need to define specific
|
|
user options for Fortran 03 files.
|
|
You should normally set the <a class="link" href="#cv-SHFORTRANFLAGS"><code class="envar">$SHFORTRANFLAGS</code></a> variable,
|
|
which specifies the user-specified options
|
|
passed to the default Fortran compiler
|
|
for all Fortran versions.
|
|
</p></dd><dt><a name="cv-SHF03PPCOM"></a><span class="term">SHF03PPCOM</span></dt><dd><p>
|
|
The command line used to compile a Fortran 03 source file to a
|
|
shared-library object file
|
|
after first running the file through the C preprocessor.
|
|
Any options specified in the <a class="link" href="#cv-SHF03FLAGS"><code class="envar">$SHF03FLAGS</code></a> and <a class="link" href="#cv-CPPFLAGS"><code class="envar">$CPPFLAGS</code></a> construction variables
|
|
are included on this command line.
|
|
You only need to set <a class="link" href="#cv-SHF03PPCOM"><code class="envar">$SHF03PPCOM</code></a> if you need to use a specific
|
|
C-preprocessor command line for Fortran 03 files.
|
|
You should normally set the <a class="link" href="#cv-SHFORTRANPPCOM"><code class="envar">$SHFORTRANPPCOM</code></a> variable,
|
|
which specifies the default C-preprocessor command line
|
|
for all Fortran versions.
|
|
</p></dd><dt><a name="cv-SHF03PPCOMSTR"></a><span class="term">SHF03PPCOMSTR</span></dt><dd><p>
|
|
The string displayed when a Fortran 03 source file
|
|
is compiled to a shared-library object file
|
|
after first running the file through the C preprocessor.
|
|
If this is not set, then <a class="link" href="#cv-SHF03PPCOM"><code class="envar">$SHF03PPCOM</code></a> or <a class="link" href="#cv-SHFORTRANPPCOM"><code class="envar">$SHFORTRANPPCOM</code></a>
|
|
(the command line) is displayed.
|
|
</p></dd><dt><a name="cv-SHF08"></a><span class="term">SHF08</span></dt><dd><p>
|
|
The Fortran 08 compiler used for generating shared-library objects.
|
|
You should normally set the <a class="link" href="#cv-SHFORTRAN"><code class="envar">$SHFORTRAN</code></a> variable,
|
|
which specifies the default Fortran compiler
|
|
for all Fortran versions.
|
|
You only need to set <a class="link" href="#cv-SHF08"><code class="envar">$SHF08</code></a> if you need to use a specific compiler
|
|
or compiler version for Fortran 08 files.
|
|
</p></dd><dt><a name="cv-SHF08COM"></a><span class="term">SHF08COM</span></dt><dd><p>
|
|
The command line used to compile a Fortran 08 source file
|
|
to a shared-library object file.
|
|
You only need to set <a class="link" href="#cv-SHF08COM"><code class="envar">$SHF08COM</code></a> if you need to use a specific
|
|
command line for Fortran 08 files.
|
|
You should normally set the <a class="link" href="#cv-SHFORTRANCOM"><code class="envar">$SHFORTRANCOM</code></a> variable,
|
|
which specifies the default command line
|
|
for all Fortran versions.
|
|
</p></dd><dt><a name="cv-SHF08COMSTR"></a><span class="term">SHF08COMSTR</span></dt><dd><p>
|
|
The string displayed when a Fortran 08 source file
|
|
is compiled to a shared-library object file.
|
|
If this is not set, then <a class="link" href="#cv-SHF08COM"><code class="envar">$SHF08COM</code></a> or <a class="link" href="#cv-SHFORTRANCOM"><code class="envar">$SHFORTRANCOM</code></a>
|
|
(the command line) is displayed.
|
|
</p></dd><dt><a name="cv-SHF08FLAGS"></a><span class="term">SHF08FLAGS</span></dt><dd><p>
|
|
Options that are passed to the Fortran 08 compiler
|
|
to generated shared-library objects.
|
|
You only need to set <a class="link" href="#cv-SHF08FLAGS"><code class="envar">$SHF08FLAGS</code></a> if you need to define specific
|
|
user options for Fortran 08 files.
|
|
You should normally set the <a class="link" href="#cv-SHFORTRANFLAGS"><code class="envar">$SHFORTRANFLAGS</code></a> variable,
|
|
which specifies the user-specified options
|
|
passed to the default Fortran compiler
|
|
for all Fortran versions.
|
|
</p></dd><dt><a name="cv-SHF08PPCOM"></a><span class="term">SHF08PPCOM</span></dt><dd><p>
|
|
The command line used to compile a Fortran 08 source file to a
|
|
shared-library object file
|
|
after first running the file through the C preprocessor.
|
|
Any options specified in the <a class="link" href="#cv-SHF08FLAGS"><code class="envar">$SHF08FLAGS</code></a> and <a class="link" href="#cv-CPPFLAGS"><code class="envar">$CPPFLAGS</code></a> construction variables
|
|
are included on this command line.
|
|
You only need to set <a class="link" href="#cv-SHF08PPCOM"><code class="envar">$SHF08PPCOM</code></a> if you need to use a specific
|
|
C-preprocessor command line for Fortran 08 files.
|
|
You should normally set the <a class="link" href="#cv-SHFORTRANPPCOM"><code class="envar">$SHFORTRANPPCOM</code></a> variable,
|
|
which specifies the default C-preprocessor command line
|
|
for all Fortran versions.
|
|
</p></dd><dt><a name="cv-SHF08PPCOMSTR"></a><span class="term">SHF08PPCOMSTR</span></dt><dd><p>
|
|
The string displayed when a Fortran 08 source file
|
|
is compiled to a shared-library object file
|
|
after first running the file through the C preprocessor.
|
|
If this is not set, then <a class="link" href="#cv-SHF08PPCOM"><code class="envar">$SHF08PPCOM</code></a> or <a class="link" href="#cv-SHFORTRANPPCOM"><code class="envar">$SHFORTRANPPCOM</code></a>
|
|
(the command line) is displayed.
|
|
</p></dd><dt><a name="cv-SHF77"></a><span class="term">SHF77</span></dt><dd><p>
|
|
The Fortran 77 compiler used for generating shared-library objects.
|
|
You should normally set the <a class="link" href="#cv-SHFORTRAN"><code class="envar">$SHFORTRAN</code></a> variable,
|
|
which specifies the default Fortran compiler
|
|
for all Fortran versions.
|
|
You only need to set <a class="link" href="#cv-SHF77"><code class="envar">$SHF77</code></a> if you need to use a specific compiler
|
|
or compiler version for Fortran 77 files.
|
|
</p></dd><dt><a name="cv-SHF77COM"></a><span class="term">SHF77COM</span></dt><dd><p>
|
|
The command line used to compile a Fortran 77 source file
|
|
to a shared-library object file.
|
|
You only need to set <a class="link" href="#cv-SHF77COM"><code class="envar">$SHF77COM</code></a> if you need to use a specific
|
|
command line for Fortran 77 files.
|
|
You should normally set the <a class="link" href="#cv-SHFORTRANCOM"><code class="envar">$SHFORTRANCOM</code></a> variable,
|
|
which specifies the default command line
|
|
for all Fortran versions.
|
|
</p></dd><dt><a name="cv-SHF77COMSTR"></a><span class="term">SHF77COMSTR</span></dt><dd><p>
|
|
The string displayed when a Fortran 77 source file
|
|
is compiled to a shared-library object file.
|
|
If this is not set, then <a class="link" href="#cv-SHF77COM"><code class="envar">$SHF77COM</code></a> or <a class="link" href="#cv-SHFORTRANCOM"><code class="envar">$SHFORTRANCOM</code></a>
|
|
(the command line) is displayed.
|
|
</p></dd><dt><a name="cv-SHF77FLAGS"></a><span class="term">SHF77FLAGS</span></dt><dd><p>
|
|
Options that are passed to the Fortran 77 compiler
|
|
to generated shared-library objects.
|
|
You only need to set <a class="link" href="#cv-SHF77FLAGS"><code class="envar">$SHF77FLAGS</code></a> if you need to define specific
|
|
user options for Fortran 77 files.
|
|
You should normally set the <a class="link" href="#cv-SHFORTRANFLAGS"><code class="envar">$SHFORTRANFLAGS</code></a> variable,
|
|
which specifies the user-specified options
|
|
passed to the default Fortran compiler
|
|
for all Fortran versions.
|
|
</p></dd><dt><a name="cv-SHF77PPCOM"></a><span class="term">SHF77PPCOM</span></dt><dd><p>
|
|
The command line used to compile a Fortran 77 source file to a
|
|
shared-library object file
|
|
after first running the file through the C preprocessor.
|
|
Any options specified in the <a class="link" href="#cv-SHF77FLAGS"><code class="envar">$SHF77FLAGS</code></a> and <a class="link" href="#cv-CPPFLAGS"><code class="envar">$CPPFLAGS</code></a> construction variables
|
|
are included on this command line.
|
|
You only need to set <a class="link" href="#cv-SHF77PPCOM"><code class="envar">$SHF77PPCOM</code></a> if you need to use a specific
|
|
C-preprocessor command line for Fortran 77 files.
|
|
You should normally set the <a class="link" href="#cv-SHFORTRANPPCOM"><code class="envar">$SHFORTRANPPCOM</code></a> variable,
|
|
which specifies the default C-preprocessor command line
|
|
for all Fortran versions.
|
|
</p></dd><dt><a name="cv-SHF77PPCOMSTR"></a><span class="term">SHF77PPCOMSTR</span></dt><dd><p>
|
|
The string displayed when a Fortran 77 source file
|
|
is compiled to a shared-library object file
|
|
after first running the file through the C preprocessor.
|
|
If this is not set, then <a class="link" href="#cv-SHF77PPCOM"><code class="envar">$SHF77PPCOM</code></a> or <a class="link" href="#cv-SHFORTRANPPCOM"><code class="envar">$SHFORTRANPPCOM</code></a>
|
|
(the command line) is displayed.
|
|
</p></dd><dt><a name="cv-SHF90"></a><span class="term">SHF90</span></dt><dd><p>
|
|
The Fortran 90 compiler used for generating shared-library objects.
|
|
You should normally set the <a class="link" href="#cv-SHFORTRAN"><code class="envar">$SHFORTRAN</code></a> variable,
|
|
which specifies the default Fortran compiler
|
|
for all Fortran versions.
|
|
You only need to set <a class="link" href="#cv-SHF90"><code class="envar">$SHF90</code></a> if you need to use a specific compiler
|
|
or compiler version for Fortran 90 files.
|
|
</p></dd><dt><a name="cv-SHF90COM"></a><span class="term">SHF90COM</span></dt><dd><p>
|
|
The command line used to compile a Fortran 90 source file
|
|
to a shared-library object file.
|
|
You only need to set <a class="link" href="#cv-SHF90COM"><code class="envar">$SHF90COM</code></a> if you need to use a specific
|
|
command line for Fortran 90 files.
|
|
You should normally set the <a class="link" href="#cv-SHFORTRANCOM"><code class="envar">$SHFORTRANCOM</code></a> variable,
|
|
which specifies the default command line
|
|
for all Fortran versions.
|
|
</p></dd><dt><a name="cv-SHF90COMSTR"></a><span class="term">SHF90COMSTR</span></dt><dd><p>
|
|
The string displayed when a Fortran 90 source file
|
|
is compiled to a shared-library object file.
|
|
If this is not set, then <a class="link" href="#cv-SHF90COM"><code class="envar">$SHF90COM</code></a> or <a class="link" href="#cv-SHFORTRANCOM"><code class="envar">$SHFORTRANCOM</code></a>
|
|
(the command line) is displayed.
|
|
</p></dd><dt><a name="cv-SHF90FLAGS"></a><span class="term">SHF90FLAGS</span></dt><dd><p>
|
|
Options that are passed to the Fortran 90 compiler
|
|
to generated shared-library objects.
|
|
You only need to set <a class="link" href="#cv-SHF90FLAGS"><code class="envar">$SHF90FLAGS</code></a> if you need to define specific
|
|
user options for Fortran 90 files.
|
|
You should normally set the <a class="link" href="#cv-SHFORTRANFLAGS"><code class="envar">$SHFORTRANFLAGS</code></a> variable,
|
|
which specifies the user-specified options
|
|
passed to the default Fortran compiler
|
|
for all Fortran versions.
|
|
</p></dd><dt><a name="cv-SHF90PPCOM"></a><span class="term">SHF90PPCOM</span></dt><dd><p>
|
|
The command line used to compile a Fortran 90 source file to a
|
|
shared-library object file
|
|
after first running the file through the C preprocessor.
|
|
Any options specified in the <a class="link" href="#cv-SHF90FLAGS"><code class="envar">$SHF90FLAGS</code></a> and <a class="link" href="#cv-CPPFLAGS"><code class="envar">$CPPFLAGS</code></a> construction variables
|
|
are included on this command line.
|
|
You only need to set <a class="link" href="#cv-SHF90PPCOM"><code class="envar">$SHF90PPCOM</code></a> if you need to use a specific
|
|
C-preprocessor command line for Fortran 90 files.
|
|
You should normally set the <a class="link" href="#cv-SHFORTRANPPCOM"><code class="envar">$SHFORTRANPPCOM</code></a> variable,
|
|
which specifies the default C-preprocessor command line
|
|
for all Fortran versions.
|
|
</p></dd><dt><a name="cv-SHF90PPCOMSTR"></a><span class="term">SHF90PPCOMSTR</span></dt><dd><p>
|
|
The string displayed when a Fortran 90 source file
|
|
is compiled to a shared-library object file
|
|
after first running the file through the C preprocessor.
|
|
If this is not set, then <a class="link" href="#cv-SHF90PPCOM"><code class="envar">$SHF90PPCOM</code></a> or <a class="link" href="#cv-SHFORTRANPPCOM"><code class="envar">$SHFORTRANPPCOM</code></a>
|
|
(the command line) is displayed.
|
|
</p></dd><dt><a name="cv-SHF95"></a><span class="term">SHF95</span></dt><dd><p>
|
|
The Fortran 95 compiler used for generating shared-library objects.
|
|
You should normally set the <a class="link" href="#cv-SHFORTRAN"><code class="envar">$SHFORTRAN</code></a> variable,
|
|
which specifies the default Fortran compiler
|
|
for all Fortran versions.
|
|
You only need to set <a class="link" href="#cv-SHF95"><code class="envar">$SHF95</code></a> if you need to use a specific compiler
|
|
or compiler version for Fortran 95 files.
|
|
</p></dd><dt><a name="cv-SHF95COM"></a><span class="term">SHF95COM</span></dt><dd><p>
|
|
The command line used to compile a Fortran 95 source file
|
|
to a shared-library object file.
|
|
You only need to set <a class="link" href="#cv-SHF95COM"><code class="envar">$SHF95COM</code></a> if you need to use a specific
|
|
command line for Fortran 95 files.
|
|
You should normally set the <a class="link" href="#cv-SHFORTRANCOM"><code class="envar">$SHFORTRANCOM</code></a> variable,
|
|
which specifies the default command line
|
|
for all Fortran versions.
|
|
</p></dd><dt><a name="cv-SHF95COMSTR"></a><span class="term">SHF95COMSTR</span></dt><dd><p>
|
|
The string displayed when a Fortran 95 source file
|
|
is compiled to a shared-library object file.
|
|
If this is not set, then <a class="link" href="#cv-SHF95COM"><code class="envar">$SHF95COM</code></a> or <a class="link" href="#cv-SHFORTRANCOM"><code class="envar">$SHFORTRANCOM</code></a>
|
|
(the command line) is displayed.
|
|
</p></dd><dt><a name="cv-SHF95FLAGS"></a><span class="term">SHF95FLAGS</span></dt><dd><p>
|
|
Options that are passed to the Fortran 95 compiler
|
|
to generated shared-library objects.
|
|
You only need to set <a class="link" href="#cv-SHF95FLAGS"><code class="envar">$SHF95FLAGS</code></a> if you need to define specific
|
|
user options for Fortran 95 files.
|
|
You should normally set the <a class="link" href="#cv-SHFORTRANFLAGS"><code class="envar">$SHFORTRANFLAGS</code></a> variable,
|
|
which specifies the user-specified options
|
|
passed to the default Fortran compiler
|
|
for all Fortran versions.
|
|
</p></dd><dt><a name="cv-SHF95PPCOM"></a><span class="term">SHF95PPCOM</span></dt><dd><p>
|
|
The command line used to compile a Fortran 95 source file to a
|
|
shared-library object file
|
|
after first running the file through the C preprocessor.
|
|
Any options specified in the <a class="link" href="#cv-SHF95FLAGS"><code class="envar">$SHF95FLAGS</code></a> and <a class="link" href="#cv-CPPFLAGS"><code class="envar">$CPPFLAGS</code></a> construction variables
|
|
are included on this command line.
|
|
You only need to set <a class="link" href="#cv-SHF95PPCOM"><code class="envar">$SHF95PPCOM</code></a> if you need to use a specific
|
|
C-preprocessor command line for Fortran 95 files.
|
|
You should normally set the <a class="link" href="#cv-SHFORTRANPPCOM"><code class="envar">$SHFORTRANPPCOM</code></a> variable,
|
|
which specifies the default C-preprocessor command line
|
|
for all Fortran versions.
|
|
</p></dd><dt><a name="cv-SHF95PPCOMSTR"></a><span class="term">SHF95PPCOMSTR</span></dt><dd><p>
|
|
The string displayed when a Fortran 95 source file
|
|
is compiled to a shared-library object file
|
|
after first running the file through the C preprocessor.
|
|
If this is not set, then <a class="link" href="#cv-SHF95PPCOM"><code class="envar">$SHF95PPCOM</code></a> or <a class="link" href="#cv-SHFORTRANPPCOM"><code class="envar">$SHFORTRANPPCOM</code></a>
|
|
(the command line) is displayed.
|
|
</p></dd><dt><a name="cv-SHFORTRAN"></a><span class="term">SHFORTRAN</span></dt><dd><p>
|
|
The default Fortran compiler used for generating shared-library objects.
|
|
</p></dd><dt><a name="cv-SHFORTRANCOM"></a><span class="term">SHFORTRANCOM</span></dt><dd><p>
|
|
The command line used to compile a Fortran source file
|
|
to a shared-library object file.
|
|
</p></dd><dt><a name="cv-SHFORTRANCOMSTR"></a><span class="term">SHFORTRANCOMSTR</span></dt><dd><p>
|
|
The string displayed when a Fortran source file
|
|
is compiled to a shared-library object file.
|
|
If this is not set, then <a class="link" href="#cv-SHFORTRANCOM"><code class="envar">$SHFORTRANCOM</code></a>
|
|
(the command line) is displayed.
|
|
</p></dd><dt><a name="cv-SHFORTRANFLAGS"></a><span class="term">SHFORTRANFLAGS</span></dt><dd><p>
|
|
Options that are passed to the Fortran compiler
|
|
to generate shared-library objects.
|
|
</p></dd><dt><a name="cv-SHFORTRANPPCOM"></a><span class="term">SHFORTRANPPCOM</span></dt><dd><p>
|
|
The command line used to compile a Fortran source file to a
|
|
shared-library object file
|
|
after first running the file through the C preprocessor.
|
|
Any options specified
|
|
in the <a class="link" href="#cv-SHFORTRANFLAGS"><code class="envar">$SHFORTRANFLAGS</code></a> and
|
|
<a class="link" href="#cv-CPPFLAGS"><code class="envar">$CPPFLAGS</code></a> construction variables
|
|
are included on this command line.
|
|
</p></dd><dt><a name="cv-SHFORTRANPPCOMSTR"></a><span class="term">SHFORTRANPPCOMSTR</span></dt><dd><p>
|
|
The string displayed when a Fortran source file
|
|
is compiled to a shared-library object file
|
|
after first running the file through the C preprocessor.
|
|
If this is not set, then <a class="link" href="#cv-SHFORTRANPPCOM"><code class="envar">$SHFORTRANPPCOM</code></a>
|
|
(the command line) is displayed.
|
|
</p></dd><dt><a name="cv-SHLIBEMITTER"></a><span class="term">SHLIBEMITTER</span></dt><dd><p>
|
|
TODO
|
|
</p></dd><dt><a name="cv-SHLIBNOVERSIONSYMLINKS"></a><span class="term">SHLIBNOVERSIONSYMLINKS</span></dt><dd><p>
|
|
Instructs the <a class="link" href="#b-SharedLibrary"><code class="function">SharedLibrary</code></a> builder to not create symlinks for versioned
|
|
shared libraries.
|
|
</p></dd><dt><a name="cv-SHLIBPREFIX"></a><span class="term">SHLIBPREFIX</span></dt><dd><p>
|
|
The prefix used for shared library file names.
|
|
</p></dd><dt><a name="cv-_SHLIBSONAME"></a><span class="term">_SHLIBSONAME</span></dt><dd><p>
|
|
A macro that automatically generates shared library's SONAME based on $TARGET,
|
|
$SHLIBVERSION and $SHLIBSUFFIX. Used by <a class="link" href="#b-SharedLibrary"><code class="function">SharedLibrary</code></a> builder when
|
|
the linker tool supports SONAME (e.g. <a class="link" href="#t-gnulink"><code class="literal">gnulink</code></a>).
|
|
</p></dd><dt><a name="cv-SHLIBSUFFIX"></a><span class="term">SHLIBSUFFIX</span></dt><dd><p>
|
|
The suffix used for shared library file names.
|
|
</p></dd><dt><a name="cv-SHLIBVERSION"></a><span class="term">SHLIBVERSION</span></dt><dd><p>
|
|
When this construction variable is defined, a versioned shared library
|
|
is created by <a class="link" href="#b-SharedLibrary"><code class="function">SharedLibrary</code></a> builder. This activates the
|
|
<a class="link" href="#cv-_SHLIBVERSIONFLAGS"><code class="envar">$_SHLIBVERSIONFLAGS</code></a> and thus modifies the <a class="link" href="#cv-SHLINKCOM"><code class="envar">$SHLINKCOM</code></a> as
|
|
required, adds the version number to the library name, and creates the symlinks
|
|
that are needed. <a class="link" href="#cv-SHLIBVERSION"><code class="envar">$SHLIBVERSION</code></a> versions should exist as alpha-numeric,
|
|
decimal-delimited values as defined by the regular expression "\w+[\.\w+]*".
|
|
Example <a class="link" href="#cv-SHLIBVERSION"><code class="envar">$SHLIBVERSION</code></a> values include '1', '1.2.3', and '1.2.gitaa412c8b'.
|
|
</p></dd><dt><a name="cv-_SHLIBVERSIONFLAGS"></a><span class="term">_SHLIBVERSIONFLAGS</span></dt><dd><p>
|
|
This macro automatically introduces extra flags to <a class="link" href="#cv-SHLINKCOM"><code class="envar">$SHLINKCOM</code></a> when
|
|
building versioned <a class="link" href="#b-SharedLibrary"><code class="function">SharedLibrary</code></a> (that is when <a class="link" href="#cv-SHLIBVERSION"><code class="envar">$SHLIBVERSION</code></a>
|
|
is set). <code class="literal">_SHLIBVERSIONFLAGS</code> usually adds <a class="link" href="#cv-SHLIBVERSIONFLAGS"><code class="envar">$SHLIBVERSIONFLAGS</code></a>
|
|
and some extra dynamically generated options (such as
|
|
<code class="literal">-Wl,-soname=$_SHLIBSONAME</code>. It is unused by "plain"
|
|
(unversioned) shared libraries.
|
|
</p></dd><dt><a name="cv-SHLIBVERSIONFLAGS"></a><span class="term">SHLIBVERSIONFLAGS</span></dt><dd><p>
|
|
Extra flags added to <a class="link" href="#cv-SHLINKCOM"><code class="envar">$SHLINKCOM</code></a> when building versioned
|
|
<a class="link" href="#b-SharedLibrary"><code class="function">SharedLibrary</code></a>. These flags are only used when <a class="link" href="#cv-SHLIBVERSION"><code class="envar">$SHLIBVERSION</code></a> is
|
|
set.
|
|
</p></dd><dt><a name="cv-SHLINK"></a><span class="term">SHLINK</span></dt><dd><p>
|
|
The linker for programs that use shared libraries.
|
|
</p></dd><dt><a name="cv-SHLINKCOM"></a><span class="term">SHLINKCOM</span></dt><dd><p>
|
|
The command line used to link programs using shared libraries.
|
|
</p></dd><dt><a name="cv-SHLINKCOMSTR"></a><span class="term">SHLINKCOMSTR</span></dt><dd><p>
|
|
The string displayed when programs using shared libraries are linked.
|
|
If this is not set, then <a class="link" href="#cv-SHLINKCOM"><code class="envar">$SHLINKCOM</code></a> (the command line) is displayed.
|
|
</p><pre class="screen">
|
|
env = Environment(SHLINKCOMSTR = "Linking shared $TARGET")
|
|
</pre></dd><dt><a name="cv-SHLINKFLAGS"></a><span class="term">SHLINKFLAGS</span></dt><dd><p>
|
|
General user options passed to the linker for programs using shared libraries.
|
|
Note that this variable should
|
|
<span class="emphasis"><em>not</em></span>
|
|
contain
|
|
<code class="option">-l</code>
|
|
(or similar) options for linking with the libraries listed in <a class="link" href="#cv-LIBS"><code class="envar">$LIBS</code></a>,
|
|
nor
|
|
<code class="option">-L</code>
|
|
(or similar) include search path options
|
|
that scons generates automatically from <a class="link" href="#cv-LIBPATH"><code class="envar">$LIBPATH</code></a>.
|
|
See
|
|
<a class="link" href="#cv-_LIBFLAGS"><code class="envar">$_LIBFLAGS</code></a>
|
|
above,
|
|
for the variable that expands to library-link options,
|
|
and
|
|
<a class="link" href="#cv-_LIBDIRFLAGS"><code class="envar">$_LIBDIRFLAGS</code></a>
|
|
above,
|
|
for the variable that expands to library search path options.
|
|
</p></dd><dt><a name="cv-SHOBJPREFIX"></a><span class="term">SHOBJPREFIX</span></dt><dd><p>
|
|
The prefix used for shared object file names.
|
|
</p></dd><dt><a name="cv-SHOBJSUFFIX"></a><span class="term">SHOBJSUFFIX</span></dt><dd><p>
|
|
The suffix used for shared object file names.
|
|
</p></dd><dt><a name="cv-SONAME"></a><span class="term">SONAME</span></dt><dd><p>
|
|
Variable used to hard-code SONAME for versioned shared library/loadable module.
|
|
</p><pre class="screen">
|
|
env.SharedLibrary('test', 'test.c', SHLIBVERSION='0.1.2', SONAME='libtest.so.2')
|
|
</pre><p>
|
|
The variable is used, for example, by <a class="link" href="#t-gnulink"><code class="literal">gnulink</code></a> linker tool.
|
|
</p></dd><dt><a name="cv-SOURCE"></a><span class="term">SOURCE</span></dt><dd><p>
|
|
A reserved variable name
|
|
that may not be set or used in a construction environment.
|
|
(See "Variable Substitution," below.)
|
|
</p></dd><dt><a name="cv-SOURCE_URL"></a><span class="term">SOURCE_URL</span></dt><dd><p>
|
|
The URL
|
|
(web address)
|
|
of the location from which the project was retrieved.
|
|
This is used to fill in the
|
|
<code class="literal">Source:</code>
|
|
field in the controlling information for Ipkg and RPM packages.
|
|
</p></dd><dt><a name="cv-SOURCES"></a><span class="term">SOURCES</span></dt><dd><p>
|
|
A reserved variable name
|
|
that may not be set or used in a construction environment.
|
|
(See "Variable Substitution," below.)
|
|
</p></dd><dt><a name="cv-SPAWN"></a><span class="term">SPAWN</span></dt><dd><p>
|
|
A command interpreter function that will be called to execute command line
|
|
strings. The function must expect the following arguments:
|
|
</p><pre class="screen">
|
|
def spawn(shell, escape, cmd, args, env):
|
|
</pre><p>
|
|
<code class="varname">sh</code>
|
|
is a string naming the shell program to use.
|
|
<code class="varname">escape</code>
|
|
is a function that can be called to escape shell special characters in
|
|
the command line.
|
|
<code class="varname">cmd</code>
|
|
is the path to the command to be executed.
|
|
<code class="varname">args</code>
|
|
is the arguments to the command.
|
|
<code class="varname">env</code>
|
|
is a dictionary of the environment variables
|
|
in which the command should be executed.
|
|
</p></dd><dt><a name="cv-STATIC_AND_SHARED_OBJECTS_ARE_THE_SAME"></a><span class="term">STATIC_AND_SHARED_OBJECTS_ARE_THE_SAME</span></dt><dd><p>
|
|
When this variable is true, static objects and shared objects are assumed to be the same; that is, SCons does not check for linking static objects into a shared library.
|
|
</p></dd><dt><a name="cv-SUBST_DICT"></a><span class="term">SUBST_DICT</span></dt><dd><p>
|
|
The dictionary used by the <code class="function">Substfile</code> or <code class="function">Textfile</code> builders
|
|
for substitution values.
|
|
It can be anything acceptable to the dict() constructor,
|
|
so in addition to a dictionary,
|
|
lists of tuples are also acceptable.
|
|
</p></dd><dt><a name="cv-SUBSTFILEPREFIX"></a><span class="term">SUBSTFILEPREFIX</span></dt><dd><p>
|
|
The prefix used for <code class="function">Substfile</code> file names,
|
|
the null string by default.
|
|
</p></dd><dt><a name="cv-SUBSTFILESUFFIX"></a><span class="term">SUBSTFILESUFFIX</span></dt><dd><p>
|
|
The suffix used for <code class="function">Substfile</code> file names,
|
|
the null string by default.
|
|
</p></dd><dt><a name="cv-SUMMARY"></a><span class="term">SUMMARY</span></dt><dd><p>
|
|
A short summary of what the project is about.
|
|
This is used to fill in the
|
|
<code class="literal">Summary:</code>
|
|
field in the controlling information for Ipkg and RPM packages,
|
|
and as the
|
|
<code class="literal">Description:</code>
|
|
field in MSI packages.
|
|
</p></dd><dt><a name="cv-SWIG"></a><span class="term">SWIG</span></dt><dd><p>
|
|
The scripting language wrapper and interface generator.
|
|
</p></dd><dt><a name="cv-SWIGCFILESUFFIX"></a><span class="term">SWIGCFILESUFFIX</span></dt><dd><p>
|
|
The suffix that will be used for intermediate C
|
|
source files generated by
|
|
the scripting language wrapper and interface generator.
|
|
The default value is
|
|
<code class="filename">_wrap</code><a class="link" href="#cv-CFILESUFFIX"><code class="envar">$CFILESUFFIX</code></a>.
|
|
By default, this value is used whenever the
|
|
<code class="option">-c++</code>
|
|
option is
|
|
<span class="emphasis"><em>not</em></span>
|
|
specified as part of the
|
|
<a class="link" href="#cv-SWIGFLAGS"><code class="envar">$SWIGFLAGS</code></a>
|
|
construction variable.
|
|
</p></dd><dt><a name="cv-SWIGCOM"></a><span class="term">SWIGCOM</span></dt><dd><p>
|
|
The command line used to call
|
|
the scripting language wrapper and interface generator.
|
|
</p></dd><dt><a name="cv-SWIGCOMSTR"></a><span class="term">SWIGCOMSTR</span></dt><dd><p>
|
|
The string displayed when calling
|
|
the scripting language wrapper and interface generator.
|
|
If this is not set, then <a class="link" href="#cv-SWIGCOM"><code class="envar">$SWIGCOM</code></a> (the command line) is displayed.
|
|
</p></dd><dt><a name="cv-SWIGCXXFILESUFFIX"></a><span class="term">SWIGCXXFILESUFFIX</span></dt><dd><p>
|
|
The suffix that will be used for intermediate C++
|
|
source files generated by
|
|
the scripting language wrapper and interface generator.
|
|
The default value is
|
|
<code class="filename">_wrap</code><a class="link" href="#cv-CFILESUFFIX"><code class="envar">$CFILESUFFIX</code></a>.
|
|
By default, this value is used whenever the
|
|
<code class="filename">-c++</code>
|
|
option is specified as part of the
|
|
<a class="link" href="#cv-SWIGFLAGS"><code class="envar">$SWIGFLAGS</code></a>
|
|
construction variable.
|
|
</p></dd><dt><a name="cv-SWIGDIRECTORSUFFIX"></a><span class="term">SWIGDIRECTORSUFFIX</span></dt><dd><p>
|
|
The suffix that will be used for intermediate C++ header
|
|
files generated by the scripting language wrapper and interface generator.
|
|
These are only generated for C++ code when the SWIG 'directors' feature is
|
|
turned on.
|
|
The default value is
|
|
<code class="filename">_wrap.h</code>.
|
|
</p></dd><dt><a name="cv-SWIGFLAGS"></a><span class="term">SWIGFLAGS</span></dt><dd><p>
|
|
General options passed to
|
|
the scripting language wrapper and interface generator.
|
|
This is where you should set
|
|
<code class="option">-python</code>,
|
|
<code class="option">-perl5</code>,
|
|
<code class="option">-tcl</code>,
|
|
or whatever other options you want to specify to SWIG.
|
|
If you set the
|
|
<code class="option">-c++</code>
|
|
option in this variable,
|
|
<code class="filename">scons</code>
|
|
will, by default,
|
|
generate a C++ intermediate source file
|
|
with the extension that is specified as the
|
|
<a class="link" href="#cv-CXXFILESUFFIX"><code class="envar">$CXXFILESUFFIX</code></a>
|
|
variable.
|
|
</p></dd><dt><a name="cv-_SWIGINCFLAGS"></a><span class="term">_SWIGINCFLAGS</span></dt><dd><p>
|
|
An automatically-generated construction variable
|
|
containing the SWIG command-line options
|
|
for specifying directories to be searched for included files.
|
|
The value of <code class="envar">$_SWIGINCFLAGS</code> is created
|
|
by respectively prepending and appending
|
|
<code class="envar">$SWIGINCPREFIX</code> and <code class="envar">$SWIGINCSUFFIX</code>
|
|
to the beginning and end
|
|
of each directory in <code class="envar">$SWIGPATH</code>.
|
|
</p></dd><dt><a name="cv-SWIGINCPREFIX"></a><span class="term">SWIGINCPREFIX</span></dt><dd><p>
|
|
The prefix used to specify an include directory on the SWIG command line.
|
|
This will be prepended to the beginning of each directory
|
|
in the <code class="envar">$SWIGPATH</code> construction variable
|
|
when the <code class="envar">$_SWIGINCFLAGS</code> variable is automatically generated.
|
|
</p></dd><dt><a name="cv-SWIGINCSUFFIX"></a><span class="term">SWIGINCSUFFIX</span></dt><dd><p>
|
|
The suffix used to specify an include directory on the SWIG command line.
|
|
This will be appended to the end of each directory
|
|
in the <code class="envar">$SWIGPATH</code> construction variable
|
|
when the <code class="envar">$_SWIGINCFLAGS</code> variable is automatically generated.
|
|
</p></dd><dt><a name="cv-SWIGOUTDIR"></a><span class="term">SWIGOUTDIR</span></dt><dd><p>
|
|
Specifies the output directory in which
|
|
the scripting language wrapper and interface generator
|
|
should place generated language-specific files.
|
|
This will be used by SCons to identify
|
|
the files that will be generated by the <span class="application">swig</span> call,
|
|
and translated into the
|
|
<code class="literal">swig -outdir</code> option on the command line.
|
|
</p></dd><dt><a name="cv-SWIGPATH"></a><span class="term">SWIGPATH</span></dt><dd><p>
|
|
The list of directories that the scripting language wrapper
|
|
and interface generate will search for included files.
|
|
The SWIG implicit dependency scanner will search these
|
|
directories for include files. The default value is an empty list.
|
|
</p><p>
|
|
Don't explicitly put include directory
|
|
arguments in SWIGFLAGS;
|
|
the result will be non-portable
|
|
and the directories will not be searched by the dependency scanner.
|
|
Note: directory names in SWIGPATH will be looked-up relative to the SConscript
|
|
directory when they are used in a command.
|
|
To force
|
|
<code class="filename">scons</code>
|
|
to look-up a directory relative to the root of the source tree use #:
|
|
</p><pre class="screen">
|
|
env = Environment(SWIGPATH='#/include')
|
|
</pre><p>
|
|
The directory look-up can also be forced using the
|
|
<code class="function">Dir</code>()
|
|
function:
|
|
</p><pre class="screen">
|
|
include = Dir('include')
|
|
env = Environment(SWIGPATH=include)
|
|
</pre><p>
|
|
The directory list will be added to command lines
|
|
through the automatically-generated
|
|
<code class="envar">$_SWIGINCFLAGS</code>
|
|
construction variable,
|
|
which is constructed by
|
|
respectively prepending and appending the values of the
|
|
<code class="envar">$SWIGINCPREFIX</code> and <code class="envar">$SWIGINCSUFFIX</code>
|
|
construction variables
|
|
to the beginning and end
|
|
of each directory in <code class="envar">$SWIGPATH</code>.
|
|
Any command lines you define that need
|
|
the SWIGPATH directory list should
|
|
include <code class="envar">$_SWIGINCFLAGS</code>:
|
|
</p><pre class="screen">
|
|
env = Environment(SWIGCOM="my_swig -o $TARGET $_SWIGINCFLAGS $SOURCES")
|
|
</pre></dd><dt><a name="cv-SWIGVERSION"></a><span class="term">SWIGVERSION</span></dt><dd><p>
|
|
The version number of the SWIG tool.
|
|
</p></dd><dt><a name="cv-TAR"></a><span class="term">TAR</span></dt><dd><p>
|
|
The tar archiver.
|
|
</p></dd><dt><a name="cv-TARCOM"></a><span class="term">TARCOM</span></dt><dd><p>
|
|
The command line used to call the tar archiver.
|
|
</p></dd><dt><a name="cv-TARCOMSTR"></a><span class="term">TARCOMSTR</span></dt><dd><p>
|
|
The string displayed when archiving files
|
|
using the tar archiver.
|
|
If this is not set, then <a class="link" href="#cv-TARCOM"><code class="envar">$TARCOM</code></a> (the command line) is displayed.
|
|
</p><pre class="screen">
|
|
env = Environment(TARCOMSTR = "Archiving $TARGET")
|
|
</pre></dd><dt><a name="cv-TARFLAGS"></a><span class="term">TARFLAGS</span></dt><dd><p>
|
|
General options passed to the tar archiver.
|
|
</p></dd><dt><a name="cv-TARGET"></a><span class="term">TARGET</span></dt><dd><p>
|
|
A reserved variable name
|
|
that may not be set or used in a construction environment.
|
|
(See "Variable Substitution," below.)
|
|
</p></dd><dt><a name="cv-TARGET_ARCH"></a><span class="term">TARGET_ARCH</span></dt><dd><p>
|
|
The name of the target hardware architecture for the compiled objects
|
|
created by this Environment.
|
|
This defaults to the value of HOST_ARCH, and the user can override it.
|
|
Currently only set for Win32.
|
|
</p><p>
|
|
Sets the target architecture for Visual Studio compiler (i.e. the arch
|
|
of the binaries generated by the compiler). If not set, default to
|
|
<code class="envar">$HOST_ARCH</code>, or, if that is unset, to the architecture of the
|
|
running machine's OS (note that the python build or architecture has no
|
|
effect).
|
|
This variable must be passed as an argument to the Environment()
|
|
constructor; setting it later has no effect.
|
|
This is currently only used on Windows, but in the future it will be
|
|
used on other OSes as well.
|
|
If this is set and MSVC_VERSION is not set, this will search for
|
|
all installed MSVC's that support the TARGET_ARCH, selecting the
|
|
latest version for use.
|
|
</p><p>
|
|
Valid values for Windows are
|
|
<code class="literal">x86</code>,
|
|
<code class="literal">arm</code>,
|
|
<code class="literal">i386</code>
|
|
(for 32 bits);
|
|
<code class="literal">amd64</code>,
|
|
<code class="literal">arm64</code>,
|
|
<code class="literal">emt64</code>,
|
|
<code class="literal">x86_64</code>
|
|
(for 64 bits);
|
|
and <code class="literal">ia64</code> (Itanium).
|
|
|
|
For example, if you want to compile 64-bit binaries, you would set
|
|
<code class="literal">TARGET_ARCH='x86_64'</code> in your SCons environment.
|
|
</p></dd><dt><a name="cv-TARGET_OS"></a><span class="term">TARGET_OS</span></dt><dd><p>
|
|
The name of the target operating system for the compiled objects
|
|
created by this Environment.
|
|
This defaults to the value of HOST_OS, and the user can override it.
|
|
Currently only set for Win32.
|
|
</p></dd><dt><a name="cv-TARGETS"></a><span class="term">TARGETS</span></dt><dd><p>
|
|
A reserved variable name
|
|
that may not be set or used in a construction environment.
|
|
(See "Variable Substitution," below.)
|
|
</p></dd><dt><a name="cv-TARSUFFIX"></a><span class="term">TARSUFFIX</span></dt><dd><p>
|
|
The suffix used for tar file names.
|
|
</p></dd><dt><a name="cv-TEMPFILEPREFIX"></a><span class="term">TEMPFILEPREFIX</span></dt><dd><p>
|
|
The prefix for a temporary file used
|
|
to store lines lines longer than $MAXLINELENGTH
|
|
as operations which call out to a shell will fail
|
|
if the line is too long, which particularly
|
|
impacts linking.
|
|
The default is '@', which works for the Microsoft
|
|
and GNU toolchains on Windows.
|
|
Set this appropriately for other toolchains,
|
|
for example '-@' for the diab compiler
|
|
or '-via' for ARM toolchain.
|
|
</p></dd><dt><a name="cv-TEMPFILESUFFIX"></a><span class="term">TEMPFILESUFFIX</span></dt><dd><p>
|
|
The suffix used for the temporary file name
|
|
used for long command lines. The name should
|
|
include the dot ('.') if one is wanted as
|
|
it will not be added automatically.
|
|
The default is '.lnk'.
|
|
</p></dd><dt><a name="cv-TEX"></a><span class="term">TEX</span></dt><dd><p>
|
|
The TeX formatter and typesetter.
|
|
</p></dd><dt><a name="cv-TEXCOM"></a><span class="term">TEXCOM</span></dt><dd><p>
|
|
The command line used to call the TeX formatter and typesetter.
|
|
</p></dd><dt><a name="cv-TEXCOMSTR"></a><span class="term">TEXCOMSTR</span></dt><dd><p>
|
|
The string displayed when calling
|
|
the TeX formatter and typesetter.
|
|
If this is not set, then <a class="link" href="#cv-TEXCOM"><code class="envar">$TEXCOM</code></a> (the command line) is displayed.
|
|
</p><pre class="screen">
|
|
env = Environment(TEXCOMSTR = "Building $TARGET from TeX input $SOURCES")
|
|
</pre></dd><dt><a name="cv-TEXFLAGS"></a><span class="term">TEXFLAGS</span></dt><dd><p>
|
|
General options passed to the TeX formatter and typesetter.
|
|
</p></dd><dt><a name="cv-TEXINPUTS"></a><span class="term">TEXINPUTS</span></dt><dd><p>
|
|
List of directories that the LaTeX program will search
|
|
for include directories.
|
|
The LaTeX implicit dependency scanner will search these
|
|
directories for \include and \import files.
|
|
</p></dd><dt><a name="cv-TEXTFILEPREFIX"></a><span class="term">TEXTFILEPREFIX</span></dt><dd><p>
|
|
The prefix used for <code class="function">Textfile</code> file names,
|
|
the null string by default.
|
|
</p></dd><dt><a name="cv-TEXTFILESUFFIX"></a><span class="term">TEXTFILESUFFIX</span></dt><dd><p>
|
|
The suffix used for <code class="function">Textfile</code> file names;
|
|
<code class="filename">.txt</code> by default.
|
|
</p></dd><dt><a name="cv-TOOLS"></a><span class="term">TOOLS</span></dt><dd><p>
|
|
A list of the names of the Tool specifications
|
|
that are part of this construction environment.
|
|
</p></dd><dt><a name="cv-UNCHANGED_SOURCES"></a><span class="term">UNCHANGED_SOURCES</span></dt><dd><p>
|
|
A reserved variable name
|
|
that may not be set or used in a construction environment.
|
|
(See "Variable Substitution," below.)
|
|
</p></dd><dt><a name="cv-UNCHANGED_TARGETS"></a><span class="term">UNCHANGED_TARGETS</span></dt><dd><p>
|
|
A reserved variable name
|
|
that may not be set or used in a construction environment.
|
|
(See "Variable Substitution," below.)
|
|
</p></dd><dt><a name="cv-VENDOR"></a><span class="term">VENDOR</span></dt><dd><p>
|
|
The person or organization who supply the packaged software.
|
|
This is used to fill in the
|
|
<code class="literal">Vendor:</code>
|
|
field in the controlling information for RPM packages,
|
|
and the
|
|
<code class="literal">Manufacturer:</code>
|
|
field in the controlling information for MSI packages.
|
|
</p></dd><dt><a name="cv-VERSION"></a><span class="term">VERSION</span></dt><dd><p>
|
|
The version of the project, specified as a string.
|
|
</p></dd><dt><a name="cv-WIN32_INSERT_DEF"></a><span class="term">WIN32_INSERT_DEF</span></dt><dd><p>
|
|
A deprecated synonym for <a class="link" href="#cv-WINDOWS_INSERT_DEF"><code class="envar">$WINDOWS_INSERT_DEF</code></a>.
|
|
</p></dd><dt><a name="cv-WIN32DEFPREFIX"></a><span class="term">WIN32DEFPREFIX</span></dt><dd><p>
|
|
A deprecated synonym for <a class="link" href="#cv-WINDOWSDEFPREFIX"><code class="envar">$WINDOWSDEFPREFIX</code></a>.
|
|
</p></dd><dt><a name="cv-WIN32DEFSUFFIX"></a><span class="term">WIN32DEFSUFFIX</span></dt><dd><p>
|
|
A deprecated synonym for <a class="link" href="#cv-WINDOWSDEFSUFFIX"><code class="envar">$WINDOWSDEFSUFFIX</code></a>.
|
|
</p></dd><dt><a name="cv-WIN32EXPPREFIX"></a><span class="term">WIN32EXPPREFIX</span></dt><dd><p>
|
|
A deprecated synonym for <a class="link" href="#cv-WINDOWSEXPSUFFIX"><code class="envar">$WINDOWSEXPSUFFIX</code></a>.
|
|
</p></dd><dt><a name="cv-WIN32EXPSUFFIX"></a><span class="term">WIN32EXPSUFFIX</span></dt><dd><p>
|
|
A deprecated synonym for <a class="link" href="#cv-WINDOWSEXPSUFFIX"><code class="envar">$WINDOWSEXPSUFFIX</code></a>.
|
|
</p></dd><dt><a name="cv-WINDOWS_EMBED_MANIFEST"></a><span class="term">WINDOWS_EMBED_MANIFEST</span></dt><dd><p>
|
|
Set this variable to True or 1 to embed the compiler-generated manifest
|
|
(normally <code class="literal">${TARGET}.manifest</code>)
|
|
into all Windows exes and DLLs built with this environment,
|
|
as a resource during their link step.
|
|
This is done using <a class="link" href="#cv-MT"><code class="envar">$MT</code></a> and <a class="link" href="#cv-MTEXECOM"><code class="envar">$MTEXECOM</code></a> and <a class="link" href="#cv-MTSHLIBCOM"><code class="envar">$MTSHLIBCOM</code></a>.
|
|
</p></dd><dt><a name="cv-WINDOWS_INSERT_DEF"></a><span class="term">WINDOWS_INSERT_DEF</span></dt><dd><p>
|
|
When this is set to true,
|
|
a library build of a Windows shared library
|
|
(<code class="filename">.dll</code> file)
|
|
will also build a corresponding <code class="filename">.def</code> file
|
|
at the same time,
|
|
if a <code class="filename">.def</code> file
|
|
is not already listed as a build target.
|
|
The default is 0 (do not build a <code class="filename">.def</code> file).
|
|
</p></dd><dt><a name="cv-WINDOWS_INSERT_MANIFEST"></a><span class="term">WINDOWS_INSERT_MANIFEST</span></dt><dd><p>
|
|
When this is set to true,
|
|
<code class="filename">scons</code>
|
|
will be aware of the
|
|
<code class="filename">.manifest</code>
|
|
files generated by Microsoft Visua C/C++ 8.
|
|
</p></dd><dt><a name="cv-WINDOWSDEFPREFIX"></a><span class="term">WINDOWSDEFPREFIX</span></dt><dd><p>
|
|
The prefix used for Windows <code class="filename">.def</code> file names.
|
|
</p></dd><dt><a name="cv-WINDOWSDEFSUFFIX"></a><span class="term">WINDOWSDEFSUFFIX</span></dt><dd><p>
|
|
The suffix used for Windows <code class="filename">.def</code> file names.
|
|
</p></dd><dt><a name="cv-WINDOWSEXPPREFIX"></a><span class="term">WINDOWSEXPPREFIX</span></dt><dd><p>
|
|
The prefix used for Windows <code class="filename">.exp</code> file names.
|
|
</p></dd><dt><a name="cv-WINDOWSEXPSUFFIX"></a><span class="term">WINDOWSEXPSUFFIX</span></dt><dd><p>
|
|
The suffix used for Windows <code class="filename">.exp</code> file names.
|
|
</p></dd><dt><a name="cv-WINDOWSPROGMANIFESTPREFIX"></a><span class="term">WINDOWSPROGMANIFESTPREFIX</span></dt><dd><p>
|
|
The prefix used for executable program <code class="filename">.manifest</code> files
|
|
generated by Microsoft Visual C/C++.
|
|
</p></dd><dt><a name="cv-WINDOWSPROGMANIFESTSUFFIX"></a><span class="term">WINDOWSPROGMANIFESTSUFFIX</span></dt><dd><p>
|
|
The suffix used for executable program <code class="filename">.manifest</code> files
|
|
generated by Microsoft Visual C/C++.
|
|
</p></dd><dt><a name="cv-WINDOWSSHLIBMANIFESTPREFIX"></a><span class="term">WINDOWSSHLIBMANIFESTPREFIX</span></dt><dd><p>
|
|
The prefix used for shared library <code class="filename">.manifest</code> files
|
|
generated by Microsoft Visual C/C++.
|
|
</p></dd><dt><a name="cv-WINDOWSSHLIBMANIFESTSUFFIX"></a><span class="term">WINDOWSSHLIBMANIFESTSUFFIX</span></dt><dd><p>
|
|
The suffix used for shared library <code class="filename">.manifest</code> files
|
|
generated by Microsoft Visual C/C++.
|
|
</p></dd><dt><a name="cv-X_IPK_DEPENDS"></a><span class="term">X_IPK_DEPENDS</span></dt><dd><p>
|
|
This is used to fill in the
|
|
<code class="literal">Depends:</code>
|
|
field in the controlling information for Ipkg packages.
|
|
</p></dd><dt><a name="cv-X_IPK_DESCRIPTION"></a><span class="term">X_IPK_DESCRIPTION</span></dt><dd><p>
|
|
This is used to fill in the
|
|
<code class="literal">Description:</code>
|
|
field in the controlling information for Ipkg packages.
|
|
The default value is
|
|
<code class="literal">$SUMMARY\n$DESCRIPTION</code>
|
|
</p></dd><dt><a name="cv-X_IPK_MAINTAINER"></a><span class="term">X_IPK_MAINTAINER</span></dt><dd><p>
|
|
This is used to fill in the
|
|
<code class="literal">Maintainer:</code>
|
|
field in the controlling information for Ipkg packages.
|
|
</p></dd><dt><a name="cv-X_IPK_PRIORITY"></a><span class="term">X_IPK_PRIORITY</span></dt><dd><p>
|
|
This is used to fill in the
|
|
<code class="literal">Priority:</code>
|
|
field in the controlling information for Ipkg packages.
|
|
</p></dd><dt><a name="cv-X_IPK_SECTION"></a><span class="term">X_IPK_SECTION</span></dt><dd><p>
|
|
This is used to fill in the
|
|
<code class="literal">Section:</code>
|
|
field in the controlling information for Ipkg packages.
|
|
</p></dd><dt><a name="cv-X_MSI_LANGUAGE"></a><span class="term">X_MSI_LANGUAGE</span></dt><dd><p>
|
|
This is used to fill in the
|
|
<code class="literal">Language:</code>
|
|
attribute in the controlling information for MSI packages.
|
|
</p></dd><dt><a name="cv-X_MSI_LICENSE_TEXT"></a><span class="term">X_MSI_LICENSE_TEXT</span></dt><dd><p>
|
|
The text of the software license in RTF format.
|
|
Carriage return characters will be
|
|
replaced with the RTF equivalent \\par.
|
|
</p></dd><dt><a name="cv-X_MSI_UPGRADE_CODE"></a><span class="term">X_MSI_UPGRADE_CODE</span></dt><dd><p>
|
|
TODO
|
|
</p></dd><dt><a name="cv-X_RPM_AUTOREQPROV"></a><span class="term">X_RPM_AUTOREQPROV</span></dt><dd><p>
|
|
This is used to fill in the
|
|
<code class="literal">AutoReqProv:</code>
|
|
field in the RPM
|
|
<code class="filename">.spec</code> file.
|
|
</p></dd><dt><a name="cv-X_RPM_BUILD"></a><span class="term">X_RPM_BUILD</span></dt><dd><p>
|
|
internal, but overridable
|
|
</p></dd><dt><a name="cv-X_RPM_BUILDREQUIRES"></a><span class="term">X_RPM_BUILDREQUIRES</span></dt><dd><p>
|
|
This is used to fill in the
|
|
<code class="literal">BuildRequires:</code>
|
|
field in the RPM
|
|
<code class="filename">.spec</code> file.
|
|
Note this should only be used on a host managed by rpm as the dependencies will not be resolvable at build time otherwise.
|
|
</p></dd><dt><a name="cv-X_RPM_BUILDROOT"></a><span class="term">X_RPM_BUILDROOT</span></dt><dd><p>
|
|
internal, but overridable
|
|
</p></dd><dt><a name="cv-X_RPM_CLEAN"></a><span class="term">X_RPM_CLEAN</span></dt><dd><p>
|
|
internal, but overridable
|
|
</p></dd><dt><a name="cv-X_RPM_CONFLICTS"></a><span class="term">X_RPM_CONFLICTS</span></dt><dd><p>
|
|
This is used to fill in the
|
|
<code class="literal">Conflicts:</code>
|
|
field in the RPM
|
|
<code class="filename">.spec</code> file.
|
|
</p></dd><dt><a name="cv-X_RPM_DEFATTR"></a><span class="term">X_RPM_DEFATTR</span></dt><dd><p>
|
|
This value is used as the default attributes
|
|
for the files in the RPM package.
|
|
The default value is
|
|
<code class="literal">(-,root,root)</code>.
|
|
</p></dd><dt><a name="cv-X_RPM_DISTRIBUTION"></a><span class="term">X_RPM_DISTRIBUTION</span></dt><dd><p>
|
|
This is used to fill in the
|
|
<code class="literal">Distribution:</code>
|
|
field in the RPM
|
|
<code class="filename">.spec</code> file.
|
|
</p></dd><dt><a name="cv-X_RPM_EPOCH"></a><span class="term">X_RPM_EPOCH</span></dt><dd><p>
|
|
This is used to fill in the
|
|
<code class="literal">Epoch:</code>
|
|
field in the RPM
|
|
<code class="filename">.spec</code> file.
|
|
</p></dd><dt><a name="cv-X_RPM_EXCLUDEARCH"></a><span class="term">X_RPM_EXCLUDEARCH</span></dt><dd><p>
|
|
This is used to fill in the
|
|
<code class="literal">ExcludeArch:</code>
|
|
field in the RPM
|
|
<code class="filename">.spec</code> file.
|
|
</p></dd><dt><a name="cv-X_RPM_EXLUSIVEARCH"></a><span class="term">X_RPM_EXLUSIVEARCH</span></dt><dd><p>
|
|
This is used to fill in the
|
|
<code class="literal">ExclusiveArch:</code>
|
|
field in the RPM
|
|
<code class="filename">.spec</code> file.
|
|
</p></dd><dt><a name="cv-X_RPM_EXTRADEFS"></a><span class="term">X_RPM_EXTRADEFS</span></dt><dd><p>
|
|
A list used to supply extra defintions or flags
|
|
to be added to the RPM <code class="filename">.spec</code> file.
|
|
Each item is added as-is with a carriage return appended.
|
|
This is useful if some specific RPM feature not otherwise
|
|
anticipated by SCons needs to be turned on or off.
|
|
Note if this variable is omitted, SCons will by
|
|
default supply the value
|
|
<code class="literal">'%global debug_package %{nil}'</code>
|
|
to disable debug package generation.
|
|
To enable debug package generation, include this
|
|
variable set either to None, or to a custom
|
|
list that does not include the default line.
|
|
Added in version 3.1.
|
|
</p><pre class="screen">
|
|
env.Package(
|
|
NAME = 'foo',
|
|
...
|
|
X_RPM_EXTRADEFS = [
|
|
'%define _unpackaged_files_terminate_build 0'
|
|
'%define _missing_doc_files_terminate_build 0'
|
|
],
|
|
... )
|
|
</pre></dd><dt><a name="cv-X_RPM_GROUP"></a><span class="term">X_RPM_GROUP</span></dt><dd><p>
|
|
This is used to fill in the
|
|
<code class="literal">Group:</code>
|
|
field in the RPM
|
|
<code class="filename">.spec</code> file.
|
|
</p></dd><dt><a name="cv-X_RPM_GROUP_lang"></a><span class="term">X_RPM_GROUP_lang</span></dt><dd><p>
|
|
This is used to fill in the
|
|
<code class="literal">Group(lang):</code>
|
|
field in the RPM
|
|
<code class="filename">.spec</code> file.
|
|
Note that
|
|
<code class="varname">lang</code>
|
|
is not literal
|
|
and should be replaced by
|
|
the appropriate language code.
|
|
</p></dd><dt><a name="cv-X_RPM_ICON"></a><span class="term">X_RPM_ICON</span></dt><dd><p>
|
|
This is used to fill in the
|
|
<code class="literal">Icon:</code>
|
|
field in the RPM
|
|
<code class="filename">.spec</code> file.
|
|
</p></dd><dt><a name="cv-X_RPM_INSTALL"></a><span class="term">X_RPM_INSTALL</span></dt><dd><p>
|
|
internal, but overridable
|
|
</p></dd><dt><a name="cv-X_RPM_PACKAGER"></a><span class="term">X_RPM_PACKAGER</span></dt><dd><p>
|
|
This is used to fill in the
|
|
<code class="literal">Packager:</code>
|
|
field in the RPM
|
|
<code class="filename">.spec</code> file.
|
|
</p></dd><dt><a name="cv-X_RPM_POSTINSTALL"></a><span class="term">X_RPM_POSTINSTALL</span></dt><dd><p>
|
|
This is used to fill in the
|
|
<code class="literal">%post:</code>
|
|
section in the RPM
|
|
<code class="filename">.spec</code> file.
|
|
</p></dd><dt><a name="cv-X_RPM_POSTUNINSTALL"></a><span class="term">X_RPM_POSTUNINSTALL</span></dt><dd><p>
|
|
This is used to fill in the
|
|
<code class="literal">%postun:</code>
|
|
section in the RPM
|
|
<code class="filename">.spec</code> file.
|
|
</p></dd><dt><a name="cv-X_RPM_PREFIX"></a><span class="term">X_RPM_PREFIX</span></dt><dd><p>
|
|
This is used to fill in the
|
|
<code class="literal">Prefix:</code>
|
|
field in the RPM
|
|
<code class="filename">.spec</code> file.
|
|
</p></dd><dt><a name="cv-X_RPM_PREINSTALL"></a><span class="term">X_RPM_PREINSTALL</span></dt><dd><p>
|
|
This is used to fill in the
|
|
<code class="literal">%pre:</code>
|
|
section in the RPM
|
|
<code class="filename">.spec</code> file.
|
|
</p></dd><dt><a name="cv-X_RPM_PREP"></a><span class="term">X_RPM_PREP</span></dt><dd><p>
|
|
internal, but overridable
|
|
</p></dd><dt><a name="cv-X_RPM_PREUNINSTALL"></a><span class="term">X_RPM_PREUNINSTALL</span></dt><dd><p>
|
|
This is used to fill in the
|
|
<code class="literal">%preun:</code>
|
|
section in the RPM
|
|
<code class="filename">.spec</code> file.
|
|
</p></dd><dt><a name="cv-X_RPM_PROVIDES"></a><span class="term">X_RPM_PROVIDES</span></dt><dd><p>
|
|
This is used to fill in the
|
|
<code class="literal">Provides:</code>
|
|
field in the RPM
|
|
<code class="filename">.spec</code> file.
|
|
</p></dd><dt><a name="cv-X_RPM_REQUIRES"></a><span class="term">X_RPM_REQUIRES</span></dt><dd><p>
|
|
This is used to fill in the
|
|
<code class="literal">Requires:</code>
|
|
field in the RPM
|
|
<code class="filename">.spec</code> file.
|
|
</p></dd><dt><a name="cv-X_RPM_SERIAL"></a><span class="term">X_RPM_SERIAL</span></dt><dd><p>
|
|
This is used to fill in the
|
|
<code class="literal">Serial:</code>
|
|
field in the RPM
|
|
<code class="filename">.spec</code> file.
|
|
</p></dd><dt><a name="cv-X_RPM_URL"></a><span class="term">X_RPM_URL</span></dt><dd><p>
|
|
This is used to fill in the
|
|
<code class="literal">Url:</code>
|
|
field in the RPM
|
|
<code class="filename">.spec</code> file.
|
|
</p></dd><dt><a name="cv-XGETTEXT"></a><span class="term">XGETTEXT</span></dt><dd><p>
|
|
Path to <span class="command"><strong>xgettext(1)</strong></span> program (found via
|
|
<code class="function">Detect()</code>).
|
|
See <a class="link" href="#t-xgettext"><code class="literal">xgettext</code></a> tool and <a class="link" href="#b-POTUpdate"><code class="function">POTUpdate</code></a> builder.
|
|
</p></dd><dt><a name="cv-XGETTEXTCOM"></a><span class="term">XGETTEXTCOM</span></dt><dd><p>
|
|
Complete xgettext command line.
|
|
See <a class="link" href="#t-xgettext"><code class="literal">xgettext</code></a> tool and <a class="link" href="#b-POTUpdate"><code class="function">POTUpdate</code></a> builder.
|
|
</p></dd><dt><a name="cv-XGETTEXTCOMSTR"></a><span class="term">XGETTEXTCOMSTR</span></dt><dd><p>
|
|
A string that is shown when <span class="command"><strong>xgettext(1)</strong></span> command is invoked
|
|
(default: <code class="literal">''</code>, which means "print <a class="link" href="#cv-XGETTEXTCOM"><code class="envar">$XGETTEXTCOM</code></a>").
|
|
See <a class="link" href="#t-xgettext"><code class="literal">xgettext</code></a> tool and <a class="link" href="#b-POTUpdate"><code class="function">POTUpdate</code></a> builder.
|
|
</p></dd><dt><a name="cv-_XGETTEXTDOMAIN"></a><span class="term">_XGETTEXTDOMAIN</span></dt><dd><p>
|
|
Internal "macro". Generates <span class="command"><strong>xgettext</strong></span> domain name
|
|
form source and target (default: <code class="literal">'${TARGET.filebase}'</code>).
|
|
</p></dd><dt><a name="cv-XGETTEXTFLAGS"></a><span class="term">XGETTEXTFLAGS</span></dt><dd><p>
|
|
Additional flags to <span class="command"><strong>xgettext(1)</strong></span>.
|
|
See <a class="link" href="#t-xgettext"><code class="literal">xgettext</code></a> tool and <a class="link" href="#b-POTUpdate"><code class="function">POTUpdate</code></a> builder.
|
|
</p></dd><dt><a name="cv-XGETTEXTFROM"></a><span class="term">XGETTEXTFROM</span></dt><dd><p>
|
|
Name of file containing list of <span class="command"><strong>xgettext(1)</strong></span>'s source
|
|
files. Autotools' users know this as <code class="filename">POTFILES.in</code> so they
|
|
will in most cases set <code class="literal">XGETTEXTFROM="POTFILES.in"</code> here.
|
|
The <code class="envar">$XGETTEXTFROM</code> files have same syntax and semantics as the well known
|
|
GNU <code class="filename">POTFILES.in</code>.
|
|
See <a class="link" href="#t-xgettext"><code class="literal">xgettext</code></a> tool and <a class="link" href="#b-POTUpdate"><code class="function">POTUpdate</code></a> builder.
|
|
</p></dd><dt><a name="cv-_XGETTEXTFROMFLAGS"></a><span class="term">_XGETTEXTFROMFLAGS</span></dt><dd><p>
|
|
Internal "macro". Genrates list of <code class="literal">-D<dir></code> flags
|
|
from the <a class="link" href="#cv-XGETTEXTPATH"><code class="envar">$XGETTEXTPATH</code></a> list.
|
|
</p></dd><dt><a name="cv-XGETTEXTFROMPREFIX"></a><span class="term">XGETTEXTFROMPREFIX</span></dt><dd><p>
|
|
This flag is used to add single <a class="link" href="#cv-XGETTEXTFROM"><code class="envar">$XGETTEXTFROM</code></a> file to
|
|
<span class="command"><strong>xgettext(1)</strong></span>'s commandline (default:
|
|
<code class="literal">'-f'</code>).
|
|
</p></dd><dt><a name="cv-XGETTEXTFROMSUFFIX"></a><span class="term">XGETTEXTFROMSUFFIX</span></dt><dd><p>
|
|
(default: <code class="literal">''</code>)
|
|
</p></dd><dt><a name="cv-XGETTEXTPATH"></a><span class="term">XGETTEXTPATH</span></dt><dd><p>
|
|
List of directories, there <span class="command"><strong>xgettext(1)</strong></span> will look for
|
|
source files (default: <code class="literal">[]</code>).
|
|
</p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
|
|
This variable works only together with <a class="link" href="#cv-XGETTEXTFROM"><code class="envar">$XGETTEXTFROM</code></a>
|
|
</p></div><p>
|
|
See also <a class="link" href="#t-xgettext"><code class="literal">xgettext</code></a> tool and <a class="link" href="#b-POTUpdate"><code class="function">POTUpdate</code></a> builder.
|
|
</p></dd><dt><a name="cv-_XGETTEXTPATHFLAGS"></a><span class="term">_XGETTEXTPATHFLAGS</span></dt><dd><p>
|
|
Internal "macro". Generates list of <code class="literal">-f<file></code> flags
|
|
from <a class="link" href="#cv-XGETTEXTFROM"><code class="envar">$XGETTEXTFROM</code></a>.
|
|
</p></dd><dt><a name="cv-XGETTEXTPATHPREFIX"></a><span class="term">XGETTEXTPATHPREFIX</span></dt><dd><p>
|
|
This flag is used to add single search path to
|
|
<span class="command"><strong>xgettext(1)</strong></span>'s commandline (default:
|
|
<code class="literal">'-D'</code>).
|
|
</p></dd><dt><a name="cv-XGETTEXTPATHSUFFIX"></a><span class="term">XGETTEXTPATHSUFFIX</span></dt><dd><p>
|
|
(default: <code class="literal">''</code>)
|
|
</p></dd><dt><a name="cv-YACC"></a><span class="term">YACC</span></dt><dd><p>
|
|
The parser generator.
|
|
</p></dd><dt><a name="cv-YACCCOM"></a><span class="term">YACCCOM</span></dt><dd><p>
|
|
The command line used to call the parser generator
|
|
to generate a source file.
|
|
</p></dd><dt><a name="cv-YACCCOMSTR"></a><span class="term">YACCCOMSTR</span></dt><dd><p>
|
|
The string displayed when generating a source file
|
|
using the parser generator.
|
|
If this is not set, then <a class="link" href="#cv-YACCCOM"><code class="envar">$YACCCOM</code></a> (the command line) is displayed.
|
|
</p><pre class="screen">
|
|
env = Environment(YACCCOMSTR = "Yacc'ing $TARGET from $SOURCES")
|
|
</pre></dd><dt><a name="cv-YACCFLAGS"></a><span class="term">YACCFLAGS</span></dt><dd><p>
|
|
General options passed to the parser generator.
|
|
If <a class="link" href="#cv-YACCFLAGS"><code class="envar">$YACCFLAGS</code></a> contains a <code class="option">-d</code> option,
|
|
SCons assumes that the call will also create a .h file
|
|
(if the yacc source file ends in a .y suffix)
|
|
or a .hpp file
|
|
(if the yacc source file ends in a .yy suffix)
|
|
</p></dd><dt><a name="cv-YACCHFILESUFFIX"></a><span class="term">YACCHFILESUFFIX</span></dt><dd><p>
|
|
The suffix of the C
|
|
header file generated by the parser generator
|
|
when the
|
|
<code class="option">-d</code>
|
|
option is used.
|
|
Note that setting this variable does not cause
|
|
the parser generator to generate a header
|
|
file with the specified suffix,
|
|
it exists to allow you to specify
|
|
what suffix the parser generator will use of its own accord.
|
|
The default value is
|
|
<code class="filename">.h</code>.
|
|
</p></dd><dt><a name="cv-YACCHXXFILESUFFIX"></a><span class="term">YACCHXXFILESUFFIX</span></dt><dd><p>
|
|
The suffix of the C++
|
|
header file generated by the parser generator
|
|
when the
|
|
<code class="option">-d</code>
|
|
option is used.
|
|
Note that setting this variable does not cause
|
|
the parser generator to generate a header
|
|
file with the specified suffix,
|
|
it exists to allow you to specify
|
|
what suffix the parser generator will use of its own accord.
|
|
The default value is
|
|
<code class="filename">.hpp</code>,
|
|
except on Mac OS X,
|
|
where the default is
|
|
<code class="filename">${TARGET.suffix}.h</code>.
|
|
because the default <span class="application">bison</span> parser generator just
|
|
appends <code class="filename">.h</code>
|
|
to the name of the generated C++ file.
|
|
</p></dd><dt><a name="cv-YACCVCGFILESUFFIX"></a><span class="term">YACCVCGFILESUFFIX</span></dt><dd><p>
|
|
The suffix of the file
|
|
containing the VCG grammar automaton definition
|
|
when the
|
|
<code class="option">--graph=</code>
|
|
option is used.
|
|
Note that setting this variable does not cause
|
|
the parser generator to generate a VCG
|
|
file with the specified suffix,
|
|
it exists to allow you to specify
|
|
what suffix the parser generator will use of its own accord.
|
|
The default value is
|
|
<code class="filename">.vcg</code>.
|
|
</p></dd><dt><a name="cv-ZIP"></a><span class="term">ZIP</span></dt><dd><p>
|
|
The zip compression and file packaging utility.
|
|
</p></dd><dt><a name="cv-ZIPCOM"></a><span class="term">ZIPCOM</span></dt><dd><p>
|
|
The command line used to call the zip utility,
|
|
or the internal Python function used to create a
|
|
zip archive.
|
|
</p></dd><dt><a name="cv-ZIPCOMPRESSION"></a><span class="term">ZIPCOMPRESSION</span></dt><dd><p>
|
|
The
|
|
<code class="varname">compression</code>
|
|
flag
|
|
from the Python
|
|
<code class="filename">zipfile</code>
|
|
module used by the internal Python function
|
|
to control whether the zip archive
|
|
is compressed or not.
|
|
The default value is
|
|
<code class="literal">zipfile.ZIP_DEFLATED</code>,
|
|
which creates a compressed zip archive.
|
|
This value has no effect if the
|
|
<code class="literal">zipfile</code>
|
|
module is unavailable.
|
|
</p></dd><dt><a name="cv-ZIPCOMSTR"></a><span class="term">ZIPCOMSTR</span></dt><dd><p>
|
|
The string displayed when archiving files
|
|
using the zip utility.
|
|
If this is not set, then <a class="link" href="#cv-ZIPCOM"><code class="envar">$ZIPCOM</code></a>
|
|
(the command line or internal Python function) is displayed.
|
|
</p><pre class="screen">
|
|
env = Environment(ZIPCOMSTR = "Zipping $TARGET")
|
|
</pre></dd><dt><a name="cv-ZIPFLAGS"></a><span class="term">ZIPFLAGS</span></dt><dd><p>
|
|
General options passed to the zip utility.
|
|
</p></dd><dt><a name="cv-ZIPROOT"></a><span class="term">ZIPROOT</span></dt><dd><p>
|
|
An optional zip root directory (default empty). The filenames stored
|
|
in the zip file will be relative to this directory, if given.
|
|
Otherwise the filenames are relative to the current directory of the
|
|
command.
|
|
For instance:
|
|
</p><pre class="screen">
|
|
env = Environment()
|
|
env.Zip('foo.zip', 'subdir1/subdir2/file1', ZIPROOT='subdir1')
|
|
</pre><p>
|
|
will produce a zip file <code class="literal">foo.zip</code>
|
|
containing a file with the name
|
|
<code class="literal">subdir2/file1</code> rather than
|
|
<code class="literal">subdir1/subdir2/file1</code>.
|
|
</p></dd><dt><a name="cv-ZIPSUFFIX"></a><span class="term">ZIPSUFFIX</span></dt><dd><p>
|
|
The suffix used for zip file names.
|
|
</p></dd></dl></div><p>Construction variables can be retrieved and set using the
|
|
<span class="bold"><strong>Dictionary</strong></span>
|
|
method of the construction environment:</p><pre class="literallayout">
|
|
dict = env.Dictionary()
|
|
dict["CC"] = "cc"
|
|
</pre><p>or using the [] operator:</p><pre class="literallayout">
|
|
env["CC"] = "cc"
|
|
</pre><p>Construction variables can also be passed to the construction environment
|
|
constructor:</p><pre class="literallayout">
|
|
env = Environment(CC="cc")
|
|
</pre><p>or when copying a construction environment using the
|
|
<span class="bold"><strong>Clone</strong></span>
|
|
method:</p><pre class="literallayout">
|
|
env2 = env.Clone(CC="cl.exe")
|
|
</pre></div><div class="refsect2" title="Configure Contexts"><a name="configure_contexts"></a><h3>Configure Contexts</h3><p><span class="command"><strong>scons</strong></span>
|
|
supports
|
|
<span class="emphasis"><em>configure contexts,</em></span>
|
|
an integrated mechanism similar to the
|
|
various AC_CHECK macros in GNU autoconf
|
|
for testing for the existence of C header
|
|
files, libraries, etc.
|
|
In contrast to autoconf,
|
|
<span class="command"><strong>scons</strong></span>
|
|
does not maintain an explicit cache of the tested values,
|
|
but uses its normal dependency tracking to keep the checked values
|
|
up to date. However, users may override this behaviour with the
|
|
<code class="option">--config</code>
|
|
command line option.</p><p>The following methods can be used to perform checks:</p><div class="variablelist"><dl><dt><span class="term">Configure(<span class="emphasis"><em>env</em></span>, [<span class="emphasis"><em>custom_tests</em></span>, <span class="emphasis"><em>conf_dir</em></span>, <span class="emphasis"><em>log_file</em></span>, <span class="emphasis"><em>config_h</em></span>, <span class="emphasis"><em>clean</em></span>, <span class="emphasis"><em>help])</em></span>, </span><span class="term">env.Configure([<span class="emphasis"><em>custom_tests</em></span>, <span class="emphasis"><em>conf_dir</em></span>, <span class="emphasis"><em>log_file</em></span>, <span class="emphasis"><em>config_h</em></span>, <span class="emphasis"><em>clean</em></span>, <span class="emphasis"><em>help])</em></span></span></dt><dd><p>This creates a configure context, which can be used to perform checks.
|
|
<span class="emphasis"><em>env</em></span>
|
|
specifies the environment for building the tests.
|
|
This environment may be modified when performing checks.
|
|
<span class="emphasis"><em>custom_tests</em></span>
|
|
is a dictionary containing custom tests.
|
|
See also the section about custom tests below.
|
|
By default, no custom tests are added to the configure context.
|
|
<span class="emphasis"><em>conf_dir</em></span>
|
|
specifies a directory where the test cases are built.
|
|
Note that this directory is not used for building
|
|
normal targets.
|
|
The default value is the directory
|
|
#/.sconf_temp.
|
|
<span class="emphasis"><em>log_file</em></span>
|
|
specifies a file which collects the output from commands
|
|
that are executed to check for the existence of header files, libraries, etc.
|
|
The default is the file #/config.log.
|
|
If you are using the
|
|
<span class="bold"><strong>VariantDir</strong></span>()
|
|
method,
|
|
you may want to specify a subdirectory under your variant directory.
|
|
<span class="emphasis"><em>config_h</em></span>
|
|
specifies a C header file where the results of tests
|
|
will be written, e.g. #define HAVE_STDIO_H, #define HAVE_LIBM, etc.
|
|
The default is to not write a
|
|
<span class="bold"><strong>config.h</strong></span>
|
|
file.
|
|
You can specify the same
|
|
<span class="bold"><strong>config.h</strong></span>
|
|
file in multiple calls to Configure,
|
|
in which case
|
|
<span class="command"><strong>scons</strong></span>
|
|
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
|
|
<span class="emphasis"><em>config_h</em></span>
|
|
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
|
|
<span class="emphasis"><em>config_h</em></span>
|
|
file is being built.</p><p>The optional
|
|
<span class="bold"><strong>clean</strong></span>
|
|
and
|
|
<span class="bold"><strong>help</strong></span>
|
|
arguments can be used to suppress execution of the configuration
|
|
tests when the
|
|
<code class="option">-c/--clean</code>
|
|
or
|
|
<code class="option">-H/-h/--help</code>
|
|
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
|
|
<span class="bold"><strong>clean=False</strong></span>
|
|
or
|
|
<span class="bold"><strong>help=False</strong></span>
|
|
arguments
|
|
(or both)
|
|
to avoid unnecessary test execution.</p></dd></dl></div><p>A created
|
|
<span class="bold"><strong>Configure</strong></span>
|
|
instance has the following associated methods:</p><div class="variablelist"><dl><dt><span class="term">SConf.Finish(<span class="emphasis"><em>context</em></span>), </span><span class="term"><span class="emphasis"><em>sconf</em></span>.Finish()</span></dt><dd><p>This method should be called after configuration is done.
|
|
It returns the environment as modified
|
|
by the configuration checks performed.
|
|
After this method is called, no further checks can be performed
|
|
with this configuration context.
|
|
However, you can create a new
|
|
Configure
|
|
context to perform additional checks.
|
|
Only one context should be active at a time.</p><p>The following Checks are predefined.
|
|
(This list will likely grow larger as time
|
|
goes by and developers contribute new useful tests.)</p></dd><dt><span class="term">SConf.CheckHeader(<span class="emphasis"><em>context</em></span>, <span class="emphasis"><em>header</em></span>, [<span class="emphasis"><em>include_quotes</em></span>, <span class="emphasis"><em>language</em></span>]), </span><span class="term"><span class="emphasis"><em>sconf</em></span>.CheckHeader(<span class="emphasis"><em>header</em></span>, [<span class="emphasis"><em>include_quotes</em></span>, <span class="emphasis"><em>language</em></span>])</span></dt><dd><p>Checks if
|
|
<span class="emphasis"><em>header</em></span>
|
|
is usable in the specified language.
|
|
<span class="emphasis"><em>header</em></span>
|
|
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
|
|
<span class="bold"><strong>#include</strong></span>
|
|
lines should precede the
|
|
header line being checked for.
|
|
The optional argument
|
|
<span class="emphasis"><em>include_quotes</em></span>
|
|
must be
|
|
a two character string, where the first character denotes the opening
|
|
quote and the second character denotes the closing quote.
|
|
By default, both characters are " (double quote).
|
|
The optional argument
|
|
<span class="emphasis"><em>language</em></span>
|
|
should be either
|
|
<span class="bold"><strong>C</strong></span>
|
|
or
|
|
<span class="bold"><strong>C++</strong></span>
|
|
and selects the compiler to be used for the check.
|
|
Returns 1 on success and 0 on failure.</p></dd><dt><span class="term">SConf.CheckCHeader(<span class="emphasis"><em>context</em></span>, <span class="emphasis"><em>header</em></span>, [<span class="emphasis"><em>include_quotes</em></span>]), </span><span class="term"><span class="emphasis"><em>sconf</em></span>.CheckCHeader(<span class="emphasis"><em>header</em></span>, [<span class="emphasis"><em>include_quotes</em></span>])</span></dt><dd><p>This is a wrapper around
|
|
<span class="bold"><strong>SConf.CheckHeader</strong></span>
|
|
which checks if
|
|
<span class="emphasis"><em>header</em></span>
|
|
is usable in the C language.
|
|
<span class="emphasis"><em>header</em></span>
|
|
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
|
|
<span class="bold"><strong>#include</strong></span>
|
|
lines should precede the
|
|
header line being checked for.
|
|
The optional argument
|
|
<span class="emphasis"><em>include_quotes</em></span>
|
|
must be
|
|
a two character string, where the first character denotes the opening
|
|
quote and the second character denotes the closing quote (both default
|
|
to \N'34').
|
|
Returns 1 on success and 0 on failure.</p></dd><dt><span class="term">SConf.CheckCXXHeader(<span class="emphasis"><em>context</em></span>, <span class="emphasis"><em>header</em></span>, [<span class="emphasis"><em>include_quotes</em></span>]), </span><span class="term"><span class="emphasis"><em>sconf</em></span>.CheckCXXHeader(<span class="emphasis"><em>header</em></span>, [<span class="emphasis"><em>include_quotes</em></span>])</span></dt><dd><p>This is a wrapper around
|
|
<span class="bold"><strong>SConf.CheckHeader</strong></span>
|
|
which checks if
|
|
<span class="emphasis"><em>header</em></span>
|
|
is usable in the C++ language.
|
|
<span class="emphasis"><em>header</em></span>
|
|
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
|
|
<span class="bold"><strong>#include</strong></span>
|
|
lines should precede the
|
|
header line being checked for.
|
|
The optional argument
|
|
<span class="emphasis"><em>include_quotes</em></span>
|
|
must be
|
|
a two character string, where the first character denotes the opening
|
|
quote and the second character denotes the closing quote (both default
|
|
to \N'34').
|
|
Returns 1 on success and 0 on failure.</p></dd><dt><span class="term">SConf.CheckFunc(<span class="emphasis"><em>context,</em></span>, <span class="emphasis"><em>function_name</em></span>, [<span class="emphasis"><em>header</em></span>, <span class="emphasis"><em>language</em></span>]), </span><span class="term"><span class="emphasis"><em>sconf</em></span>.CheckFunc(<span class="emphasis"><em>function_name</em></span>, [<span class="emphasis"><em>header</em></span>, <span class="emphasis"><em>language</em></span>])</span></dt><dd><p>Checks if the specified
|
|
C or C++ function is available.
|
|
<span class="emphasis"><em>function_name</em></span>
|
|
is the name of the function to check for.
|
|
The optional
|
|
<span class="emphasis"><em>header</em></span>
|
|
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:</p><pre class="literallayout">
|
|
#ifdef __cplusplus
|
|
extern "C"
|
|
#endif
|
|
char function_name();
|
|
</pre><p>The optional
|
|
<span class="emphasis"><em>language</em></span>
|
|
argument should be
|
|
<span class="bold"><strong>C</strong></span>
|
|
or
|
|
<span class="bold"><strong>C++</strong></span>
|
|
and selects the compiler to be used for the check;
|
|
the default is "C".</p></dd><dt><span class="term">SConf.CheckLib(<span class="emphasis"><em>context</em></span>, [<span class="emphasis"><em>library</em></span>, <span class="emphasis"><em>symbol</em></span>, <span class="emphasis"><em>header</em></span>, <span class="emphasis"><em>language</em></span>, <span class="emphasis"><em>autoadd=1</em></span>]), </span><span class="term"><span class="emphasis"><em>sconf</em></span>.CheckLib([<span class="emphasis"><em>library</em></span>, <span class="emphasis"><em>symbol</em></span>, <span class="emphasis"><em>header</em></span>, <span class="emphasis"><em>language</em></span>, <span class="emphasis"><em>autoadd=1</em></span>])</span></dt><dd><p>Checks if
|
|
<span class="emphasis"><em>library</em></span>
|
|
provides
|
|
<span class="emphasis"><em>symbol</em></span>.
|
|
If the value of
|
|
<span class="emphasis"><em>autoadd</em></span>
|
|
is 1 and the library provides the specified
|
|
<span class="emphasis"><em>symbol</em></span>,
|
|
appends the library to the LIBS construction environment variable.
|
|
<span class="emphasis"><em>library</em></span>
|
|
may also be None (the default),
|
|
in which case
|
|
<span class="emphasis"><em>symbol</em></span>
|
|
is checked with the current LIBS variable,
|
|
or a list of library names,
|
|
in which case each library in the list
|
|
will be checked for
|
|
<span class="emphasis"><em>symbol</em></span>.
|
|
If
|
|
<span class="emphasis"><em>symbol</em></span>
|
|
is not set or is
|
|
<span class="bold"><strong>None</strong></span>,
|
|
then
|
|
<span class="bold"><strong>SConf.CheckLib</strong></span>()
|
|
just checks if
|
|
you can link against the specified
|
|
<span class="emphasis"><em>library</em></span>.
|
|
The optional
|
|
<span class="emphasis"><em>language</em></span>
|
|
argument should be
|
|
<span class="bold"><strong>C</strong></span>
|
|
or
|
|
<span class="bold"><strong>C++</strong></span>
|
|
and selects the compiler to be used for the check;
|
|
the default is "C".
|
|
The default value for
|
|
<span class="emphasis"><em>autoadd</em></span>
|
|
is 1.
|
|
This method returns 1 on success and 0 on error.</p></dd><dt><span class="term">SConf.CheckLibWithHeader(<span class="emphasis"><em>context</em></span>, <span class="emphasis"><em>library</em></span>, <span class="emphasis"><em>header</em></span>, <span class="emphasis"><em>language</em></span>, [<span class="emphasis"><em>call</em></span>, <span class="emphasis"><em>autoadd</em></span>]), </span><span class="term"><span class="emphasis"><em>sconf</em></span>.CheckLibWithHeader(<span class="emphasis"><em>library</em></span>, <span class="emphasis"><em>header</em></span>, <span class="emphasis"><em>language</em></span>, [<span class="emphasis"><em>call</em></span>, <span class="emphasis"><em>autoadd</em></span>])</span></dt><dd><p>In contrast to the
|
|
SConf.CheckLib
|
|
call, this call provides a more sophisticated way to check against libraries.
|
|
Again,
|
|
<span class="emphasis"><em>library</em></span>
|
|
specifies the library or a list of libraries to check.
|
|
<span class="emphasis"><em>header</em></span>
|
|
specifies a header to check for.
|
|
<span class="emphasis"><em>header</em></span>
|
|
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
|
|
<span class="bold"><strong>#include</strong></span>
|
|
lines should precede the
|
|
header line being checked for.
|
|
<span class="emphasis"><em>language</em></span>
|
|
may be one of 'C','c','CXX','cxx','C++' and 'c++'.
|
|
<span class="emphasis"><em>call</em></span>
|
|
can be any valid expression (with a trailing ';').
|
|
If
|
|
<span class="emphasis"><em>call</em></span>
|
|
is not set,
|
|
the default simply checks that you
|
|
can link against the specified
|
|
<span class="emphasis"><em>library</em></span>.
|
|
<span class="emphasis"><em>autoadd</em></span>
|
|
specifies whether to add the library to the environment (only if the check
|
|
succeeds). This method returns 1 on success and 0 on error.</p></dd><dt><span class="term">SConf.CheckType(<span class="emphasis"><em>context</em></span>, <span class="emphasis"><em>type_name</em></span>, [<span class="emphasis"><em>includes</em></span>, <span class="emphasis"><em>language</em></span>]), </span><span class="term"><span class="emphasis"><em>sconf</em></span>.CheckType(<span class="emphasis"><em>type_name</em></span>, [<span class="emphasis"><em>includes</em></span>, <span class="emphasis"><em>language</em></span>])</span></dt><dd><p>Checks for the existence of a type defined by
|
|
<span class="bold"><strong>typedef</strong></span>.
|
|
<span class="emphasis"><em>type_name</em></span>
|
|
specifies the typedef name to check for.
|
|
<span class="emphasis"><em>includes</em></span>
|
|
is a string containing one or more
|
|
<span class="bold"><strong>#include</strong></span>
|
|
lines that will be inserted into the program
|
|
that will be run to test for the existence of the type.
|
|
The optional
|
|
<span class="emphasis"><em>language</em></span>
|
|
argument should be
|
|
<span class="bold"><strong>C</strong></span>
|
|
or
|
|
<span class="bold"><strong>C++</strong></span>
|
|
and selects the compiler to be used for the check;
|
|
the default is "C".
|
|
Example:</p><pre class="literallayout">
|
|
sconf.CheckType('foo_type', '#include "my_types.h"', 'C++')
|
|
</pre></dd><dt><span class="term">Configure.CheckCC(<span class="emphasis"><em>self</em></span>)</span></dt><dd><p>Checks whether the C compiler (as defined by the CC construction variable) works
|
|
by trying to compile a small source file.</p><p>By default, SCons only detects if there is a program with the correct name, not
|
|
if it is a functioning compiler.</p><p>This uses the exact same command than the one used by the object builder for C
|
|
source file, so it can be used to detect if a particular compiler flag works or
|
|
not.</p></dd><dt><span class="term">Configure.CheckCXX(<span class="emphasis"><em>self</em></span>)</span></dt><dd><p>Checks whether the C++ compiler (as defined by the CXX construction variable)
|
|
works by trying to compile a small source file. By default, SCons only detects
|
|
if there is a program with the correct name, not if it is a functioning compiler.</p><p>This uses the exact same command than the one used by the object builder for
|
|
CXX source files, so it can be used to detect if a particular compiler flag
|
|
works or not.</p></dd><dt><span class="term">Configure.CheckSHCC(<span class="emphasis"><em>self</em></span>)</span></dt><dd><p>Checks whether the C compiler (as defined by the SHCC construction variable) works
|
|
by trying to compile a small source file. By default, SCons only detects if
|
|
there is a program with the correct name, not if it is a functioning compiler.</p><p>This uses the exact same command than the one used by the object builder for C
|
|
source file, so it can be used to detect if a particular compiler flag works or
|
|
not. This does not check whether the object code can be used to build a shared
|
|
library, only that the compilation (not link) succeeds.</p></dd><dt><span class="term">Configure.CheckSHCXX(<span class="emphasis"><em>self</em></span>)</span></dt><dd><p>Checks whether the C++ compiler (as defined by the SHCXX construction variable)
|
|
works by trying to compile a small source file. By default, SCons only detects
|
|
if there is a program with the correct name, not if it is a functioning compiler.</p><p>This uses the exact same command than the one used by the object builder for
|
|
CXX source files, so it can be used to detect if a particular compiler flag
|
|
works or not. This does not check whether the object code can be used to build
|
|
a shared library, only that the compilation (not link) succeeds.</p></dd></dl></div><p>Example of a typical Configure usage:</p><pre class="literallayout">
|
|
env = Environment()
|
|
conf = Configure( env )
|
|
if not conf.CheckCHeader( 'math.h' ):
|
|
print('We really need math.h!')
|
|
Exit(1)
|
|
if conf.CheckLibWithHeader( 'qt', 'qapp.h', 'c++',
|
|
'QApplication qapp(0,0);' ):
|
|
# do stuff for qt - usage, e.g.
|
|
conf.env.Append( CPPFLAGS = '-DWITH_QT' )
|
|
env = conf.Finish()
|
|
</pre><div class="variablelist"><dl><dt><span class="term">SConf.CheckTypeSize(<span class="emphasis"><em>context</em></span>, <span class="emphasis"><em>type_name</em></span>, [<span class="emphasis"><em>header</em></span>, <span class="emphasis"><em>language</em></span>, <span class="emphasis"><em>expect</em></span>]), </span><span class="term"><span class="emphasis"><em>sconf</em></span>.CheckTypeSize(<span class="emphasis"><em>type_name</em></span>, [<span class="emphasis"><em>header</em></span>, <span class="emphasis"><em>language</em></span>, <span class="emphasis"><em>expect</em></span>])</span></dt><dd><p>Checks for the size of a type defined by
|
|
<span class="bold"><strong>typedef</strong></span>.
|
|
<span class="emphasis"><em>type_name</em></span>
|
|
specifies the typedef name to check for.
|
|
The optional
|
|
<span class="emphasis"><em>header</em></span>
|
|
argument is a string
|
|
that will be
|
|
placed at the top
|
|
of the test file
|
|
that will be compiled
|
|
to check if the function exists;
|
|
the default is empty.
|
|
The optional
|
|
<span class="emphasis"><em>language</em></span>
|
|
argument should be
|
|
<span class="bold"><strong>C</strong></span>
|
|
or
|
|
<span class="bold"><strong>C++</strong></span>
|
|
and selects the compiler to be used for the check;
|
|
the default is "C".
|
|
The optional
|
|
<span class="emphasis"><em>expect</em></span>
|
|
argument should be an integer.
|
|
If this argument is used,
|
|
the function will only check whether the type
|
|
given in type_name has the expected size (in bytes).
|
|
For example,
|
|
<span class="bold"><strong>CheckTypeSize('short', expect = 2)</strong></span>
|
|
will return success only if short is two bytes.</p><pre class="literallayout">
|
|
</pre></dd><dt><span class="term">SConf.CheckDeclaration(<span class="emphasis"><em>context</em></span>, <span class="emphasis"><em>symbol</em></span>, [<span class="emphasis"><em>includes</em></span>, <span class="emphasis"><em>language</em></span>]), </span><span class="term"><span class="emphasis"><em>sconf</em></span>.CheckDeclaration(<span class="emphasis"><em>symbol</em></span>, [<span class="emphasis"><em>includes</em></span>, <span class="emphasis"><em>language</em></span>])</span></dt><dd><p>Checks if the specified
|
|
<span class="emphasis"><em>symbol</em></span>
|
|
is declared.
|
|
<span class="emphasis"><em>includes</em></span>
|
|
is a string containing one or more
|
|
<span class="bold"><strong>#include</strong></span>
|
|
lines that will be inserted into the program
|
|
that will be run to test for the existence of the type.
|
|
The optional
|
|
<span class="emphasis"><em>language</em></span>
|
|
argument should be
|
|
<span class="bold"><strong>C</strong></span>
|
|
or
|
|
<span class="bold"><strong>C++</strong></span>
|
|
and selects the compiler to be used for the check;
|
|
the default is "C".</p></dd><dt><span class="term">SConf.Define(<span class="emphasis"><em>context</em></span>, <span class="emphasis"><em>symbol</em></span>, [<span class="emphasis"><em>value</em></span>, <span class="emphasis"><em>comment</em></span>]), </span><span class="term"><span class="emphasis"><em>sconf</em></span>.Define(<span class="emphasis"><em>symbol</em></span>, [<span class="emphasis"><em>value</em></span>, <span class="emphasis"><em>comment</em></span>])</span></dt><dd><p>This function does not check for anything, but defines a
|
|
preprocessor symbol that will be added to the configuration header file.
|
|
It is the equivalent of AC_DEFINE,
|
|
and defines the symbol
|
|
<span class="emphasis"><em>name</em></span>
|
|
with the optional
|
|
<span class="bold"><strong>value</strong></span>
|
|
and the optional comment
|
|
<span class="bold"><strong>comment</strong></span>.</p></dd></dl></div><p>Examples:</p><pre class="programlisting">
|
|
env = Environment()
|
|
conf = Configure( env )
|
|
|
|
# Puts the following line in the config header file:
|
|
# #define A_SYMBOL
|
|
conf.Define('A_SYMBOL')
|
|
|
|
# Puts the following line in the config header file:
|
|
# #define A_SYMBOL 1
|
|
conf.Define('A_SYMBOL', 1)
|
|
</pre><p>Be careful about quoting string values, though:</p><pre class="programlisting">
|
|
env = Environment()
|
|
conf = Configure( env )
|
|
|
|
# Puts the following line in the config header file:
|
|
# #define A_SYMBOL YA
|
|
conf.Define('A_SYMBOL', "YA")
|
|
|
|
# Puts the following line in the config header file:
|
|
# #define A_SYMBOL "YA"
|
|
conf.Define('A_SYMBOL', '"YA"')
|
|
</pre><p>For comment:</p><pre class="programlisting">
|
|
env = Environment()
|
|
conf = Configure( env )
|
|
|
|
# Puts the following lines in the config header file:
|
|
# /* Set to 1 if you have a symbol */
|
|
# #define A_SYMBOL 1
|
|
conf.Define('A_SYMBOL', 1, 'Set to 1 if you have a symbol')
|
|
</pre><p>You can define your own custom checks.
|
|
in addition to the predefined checks.
|
|
These are passed in a dictionary to the Configure function.
|
|
This dictionary maps the names of the checks
|
|
to user defined Python callables
|
|
(either Python functions or class instances implementing the
|
|
<span class="emphasis"><em>__call__</em></span>
|
|
method).
|
|
The first argument of the call is always a
|
|
<span class="emphasis"><em>CheckContext</em></span>
|
|
instance followed by the arguments,
|
|
which must be supplied by the user of the check.
|
|
These CheckContext instances define the following methods:</p><div class="variablelist"><dl><dt><span class="term">CheckContext.Message(<span class="emphasis"><em>self</em></span>, <span class="emphasis"><em>text</em></span>)</span></dt><dd><p>Usually called before the check is started.
|
|
<span class="emphasis"><em>text</em></span>
|
|
will be displayed to the user, e.g. 'Checking for library X...'</p></dd><dt><span class="term">CheckContext.Result(<span class="emphasis"><em>self,</em></span>, <span class="emphasis"><em>res</em></span>)</span></dt><dd><p>Usually called after the check is done.
|
|
<span class="emphasis"><em>res</em></span>
|
|
can be either an integer or a string. In the former case, 'yes' (res != 0)
|
|
or 'no' (res == 0) is displayed to the user, in the latter case the
|
|
given string is displayed.</p></dd><dt><span class="term">CheckContext.TryCompile(<span class="emphasis"><em>self</em></span>, <span class="emphasis"><em>text</em></span>, <span class="emphasis"><em>extension</em></span>)</span></dt><dd><p>Checks if a file with the specified
|
|
<span class="emphasis"><em>extension</em></span>
|
|
(e.g. '.c') containing
|
|
<span class="emphasis"><em>text</em></span>
|
|
can be compiled using the environment's
|
|
<span class="bold"><strong>Object</strong></span>
|
|
builder. Returns 1 on success and 0 on failure.</p></dd><dt><span class="term">CheckContext.TryLink(<span class="emphasis"><em>self</em></span>, <span class="emphasis"><em>text</em></span>, <span class="emphasis"><em>extension</em></span>)</span></dt><dd><p>Checks, if a file with the specified
|
|
<span class="emphasis"><em>extension</em></span>
|
|
(e.g. '.c') containing
|
|
<span class="emphasis"><em>text</em></span>
|
|
can be compiled using the environment's
|
|
<span class="bold"><strong>Program</strong></span>
|
|
builder. Returns 1 on success and 0 on failure.</p></dd><dt><span class="term">CheckContext.TryRun(<span class="emphasis"><em>self</em></span>, <span class="emphasis"><em>text</em></span>, <span class="emphasis"><em>extension</em></span>)</span></dt><dd><p>Checks, if a file with the specified
|
|
<span class="emphasis"><em>extension</em></span>
|
|
(e.g. '.c') containing
|
|
<span class="emphasis"><em>text</em></span>
|
|
can be compiled using the environment's
|
|
<span class="bold"><strong>Program</strong></span>
|
|
builder. On success, the program is run. If the program
|
|
executes successfully
|
|
(that is, its return status is 0),
|
|
a tuple
|
|
<span class="emphasis"><em>(1, outputStr)</em></span>
|
|
is returned, where
|
|
<span class="emphasis"><em>outputStr</em></span>
|
|
is the standard output of the
|
|
program.
|
|
If the program fails execution
|
|
(its return status is non-zero),
|
|
then (0, '') is returned.</p></dd><dt><span class="term">CheckContext.TryAction(<span class="emphasis"><em>self</em></span>, <span class="emphasis"><em>action</em></span>, [<span class="emphasis"><em>text</em></span>, <span class="emphasis"><em>extension</em></span>])</span></dt><dd><p>Checks if the specified
|
|
<span class="emphasis"><em>action</em></span>
|
|
with an optional source file (contents
|
|
<span class="emphasis"><em>text</em></span>
|
|
, extension
|
|
<span class="emphasis"><em>extension</em></span>
|
|
= ''
|
|
) can be executed.
|
|
<span class="emphasis"><em>action</em></span>
|
|
may be anything which can be converted to a
|
|
<span class="command"><strong>scons</strong></span>
|
|
Action.
|
|
On success,
|
|
<span class="emphasis"><em>(1, outputStr)</em></span>
|
|
is returned, where
|
|
<span class="emphasis"><em>outputStr</em></span>
|
|
is the content of the target file.
|
|
On failure
|
|
<span class="emphasis"><em>(0, '')</em></span>
|
|
is returned.</p></dd><dt><span class="term">CheckContext.TryBuild(<span class="emphasis"><em>self</em></span>, <span class="emphasis"><em>builder</em></span>, [<span class="emphasis"><em>text</em></span>, <span class="emphasis"><em>extension</em></span>])</span></dt><dd><p>Low level implementation for testing specific builds;
|
|
the methods above are based on this method.
|
|
Given the Builder instance
|
|
<span class="emphasis"><em>builder</em></span>
|
|
and the optional
|
|
<span class="emphasis"><em>text</em></span>
|
|
of a source file with optional
|
|
<span class="emphasis"><em>extension</em></span>,
|
|
this method returns 1 on success and 0 on failure. In addition,
|
|
<span class="emphasis"><em>self.lastTarget</em></span>
|
|
is set to the build target node, if the build was successful.</p></dd></dl></div><p>Example for implementing and using custom tests:</p><pre class="programlisting">
|
|
def CheckQt(context, qtdir):
|
|
context.Message( 'Checking for qt ...' )
|
|
lastLIBS = context.env['LIBS']
|
|
lastLIBPATH = context.env['LIBPATH']
|
|
lastCPPPATH= context.env['CPPPATH']
|
|
context.env.Append(LIBS = 'qt', LIBPATH = qtdir + '/lib', CPPPATH = qtdir + '/include' )
|
|
ret = context.TryLink("""
|
|
#include <qapp.h>
|
|
int main(int argc, char **argv) {
|
|
QApplication qapp(argc, argv);
|
|
return 0;
|
|
}
|
|
""")
|
|
if not ret:
|
|
context.env.Replace(LIBS = lastLIBS, LIBPATH=lastLIBPATH, CPPPATH=lastCPPPATH)
|
|
context.Result( ret )
|
|
return ret
|
|
|
|
env = Environment()
|
|
conf = Configure( env, custom_tests = { 'CheckQt' : CheckQt } )
|
|
if not conf.CheckQt('/usr/lib/qt'):
|
|
print('We really need qt!')
|
|
Exit(1)
|
|
env = conf.Finish()
|
|
</pre></div><div class="refsect2" title="Command-Line Construction Variables"><a name="commandline_construction_variables"></a><h3>Command-Line Construction Variables</h3><p>Often when building software,
|
|
some variables must be specified at build time.
|
|
For example, libraries needed for the build may be in non-standard
|
|
locations, or site-specific compiler options may need to be passed to the
|
|
compiler.
|
|
<span class="command"><strong>scons</strong></span>
|
|
provides a
|
|
<span class="bold"><strong>Variables</strong></span>
|
|
object to support overriding construction variables
|
|
on the command line:</p><pre class="literallayout">
|
|
$ scons VARIABLE=foo
|
|
</pre><p>The variable values can also be specified in a text-based SConscript file.
|
|
To create a Variables object, call the Variables() function:</p><div class="variablelist"><dl><dt><span class="term">Variables([<span class="emphasis"><em>files</em></span>], [<span class="emphasis"><em>args</em></span>])</span></dt><dd><p>This creates a Variables object that will read construction variables from
|
|
the file or list of filenames specified in
|
|
<span class="emphasis"><em>files</em></span>.
|
|
If no files are specified,
|
|
or the
|
|
<span class="emphasis"><em>files</em></span>
|
|
argument is
|
|
<span class="bold"><strong>None</strong></span>,
|
|
then no files will be read.
|
|
The optional argument
|
|
<span class="emphasis"><em>args</em></span>
|
|
is a dictionary of
|
|
values that will override anything read from the specified files;
|
|
it is primarily intended to be passed the
|
|
<span class="bold"><strong>ARGUMENTS</strong></span>
|
|
dictionary that holds variables
|
|
specified on the command line.
|
|
Example:</p><pre class="literallayout">
|
|
vars = Variables('custom.py')
|
|
vars = Variables('overrides.py', ARGUMENTS)
|
|
vars = Variables(None, {FOO:'expansion', BAR:7})
|
|
</pre><p>Variables objects have the following methods:</p></dd><dt><span class="term">Add(<span class="emphasis"><em>key</em></span>, [<span class="emphasis"><em>help</em></span>, <span class="emphasis"><em>default</em></span>, <span class="emphasis"><em>validator</em></span>, <span class="emphasis"><em>converter</em></span>])</span></dt><dd><p>This adds a customizable construction variable to the Variables object.
|
|
<span class="emphasis"><em>key</em></span>
|
|
is the name of the variable.
|
|
<span class="emphasis"><em>help</em></span>
|
|
is the help text for the variable.
|
|
<span class="emphasis"><em>default</em></span>
|
|
is the default value of the variable;
|
|
if the default value is
|
|
<span class="bold"><strong>None</strong></span>
|
|
and there is no explicit value specified,
|
|
the construction variable will
|
|
<span class="emphasis"><em>not</em></span>
|
|
be added to the construction environment.
|
|
<span class="emphasis"><em>validator</em></span>
|
|
is called to validate the value of the variable, and should take three
|
|
arguments: key, value, and environment.
|
|
The recommended way to handle an invalid value is
|
|
to raise an exception (see example below).
|
|
<span class="emphasis"><em>converter</em></span>
|
|
is called to convert the value before putting it in the environment, and
|
|
should take either a value, or the value and environment, as parameters.
|
|
The
|
|
<span class="emphasis"><em>converter</em></span>
|
|
must return a value,
|
|
which will be converted into a string
|
|
before being validated by the
|
|
<span class="emphasis"><em>validator</em></span>
|
|
(if any)
|
|
and then added to the environment.</p><p>Examples:</p><pre class="programlisting">
|
|
vars.Add('CC', 'The C compiler')
|
|
|
|
def validate_color(key, val, env):
|
|
if not val in ['red', 'blue', 'yellow']:
|
|
raise Exception("Invalid color value '%s'" % val)
|
|
vars.Add('COLOR', validator=valid_color)
|
|
</pre></dd><dt><span class="term">AddVariables(<span class="emphasis"><em>list</em></span>)</span></dt><dd><p>A wrapper script that adds
|
|
multiple customizable construction variables
|
|
to a Variables object.
|
|
<span class="emphasis"><em>list</em></span>
|
|
is a list of tuple or list objects
|
|
that contain the arguments
|
|
for an individual call to the
|
|
<span class="bold"><strong>Add</strong></span>
|
|
method.</p><pre class="literallayout">
|
|
opt.AddVariables(
|
|
('debug', '', 0),
|
|
('CC', 'The C compiler'),
|
|
('VALIDATE', 'An option for testing validation',
|
|
'notset', validator, None),
|
|
)
|
|
</pre></dd><dt><span class="term">Update(<span class="emphasis"><em>env</em></span>, [<span class="emphasis"><em>args</em></span>])</span></dt><dd><p>This updates a construction environment
|
|
<span class="emphasis"><em>env</em></span>
|
|
with the customized construction variables.
|
|
Any specified variables that are
|
|
<span class="emphasis"><em>not</em></span>
|
|
configured for the Variables object
|
|
will be saved and may be
|
|
retrieved with the
|
|
<span class="bold"><strong>UnknownVariables</strong></span>()
|
|
method, below.</p><p>Normally this method is not called directly,
|
|
but is called indirectly by passing the Variables object to
|
|
the Environment() function:</p><pre class="literallayout">
|
|
env = Environment(variables=vars)
|
|
</pre></dd></dl></div><p>The text file(s) that were specified
|
|
when the Variables object was created
|
|
are executed as Python scripts,
|
|
and the values of (global) Python variables set in the file
|
|
are added to the construction environment.</p><p>Example:</p><pre class="literallayout">
|
|
CC = 'my_cc'
|
|
</pre><div class="variablelist"><dl><dt><span class="term">UnknownVariables(<span class="emphasis"><em>)</em></span></span></dt><dd><p>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.</p><pre class="literallayout">
|
|
env = Environment(variables=vars)
|
|
for key, value in vars.UnknownVariables():
|
|
print("unknown variable: %s=%s" % (key, value))
|
|
</pre></dd><dt><span class="term">Save(<span class="emphasis"><em>filename</em></span>, <span class="emphasis"><em>env</em></span>)</span></dt><dd><p>This saves the currently set variables into a script file named
|
|
<span class="emphasis"><em>filename</em></span>
|
|
that can be used on the next invocation to automatically load the current
|
|
settings. This method combined with the Variables method can be used to
|
|
support caching of variables between runs.</p><pre class="literallayout">
|
|
env = Environment()
|
|
vars = Variables(['variables.cache', 'custom.py'])
|
|
vars.Add(...)
|
|
vars.Update(env)
|
|
vars.Save('variables.cache', env)
|
|
</pre></dd><dt><span class="term">GenerateHelpText(<span class="emphasis"><em>env</em></span>, [<span class="emphasis"><em>sort</em></span>])</span></dt><dd><p>This generates help text documenting the customizable construction
|
|
variables suitable to passing in to the Help() function.
|
|
<span class="emphasis"><em>env</em></span>
|
|
is the construction environment that will be used to get the actual values
|
|
of customizable variables. Calling with
|
|
an optional
|
|
<span class="emphasis"><em>sort</em></span>
|
|
function
|
|
will cause the output to be sorted
|
|
by the specified argument.
|
|
The specific
|
|
<span class="emphasis"><em>sort</em></span>
|
|
function
|
|
should take two arguments
|
|
and return
|
|
-1, 0 or 1
|
|
(like the standard Python
|
|
<span class="emphasis"><em>cmp</em></span>
|
|
function).
|
|
|
|
Optionally a Boolean value of True for <span class="emphasis"><em>sort</em></span> will cause a standard alphabetical sort to be performed</p><pre class="literallayout">
|
|
Help(vars.GenerateHelpText(env))
|
|
Help(vars.GenerateHelpText(env, sort=cmp))
|
|
</pre></dd><dt><span class="term">FormatVariableHelpText(<span class="emphasis"><em>env</em></span>, <span class="emphasis"><em>opt</em></span>, <span class="emphasis"><em>help</em></span>, <span class="emphasis"><em>default</em></span>, <span class="emphasis"><em>actual</em></span>)</span></dt><dd><p>This method returns a formatted string
|
|
containing the printable help text
|
|
for one option.
|
|
It is normally not called directly,
|
|
but is called by the
|
|
<span class="emphasis"><em>GenerateHelpText</em></span>()
|
|
method to create the returned help text.
|
|
It may be overridden with your own
|
|
function that takes the arguments specified above
|
|
and returns a string of help text formatted to your liking.
|
|
Note that the
|
|
<span class="emphasis"><em>GenerateHelpText</em></span>()
|
|
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.</p><pre class="programlisting">
|
|
def my_format(env, opt, help, default, actual):
|
|
fmt = "\n%s: default=%s actual=%s (%s)\n"
|
|
return fmt % (opt, default. actual, help)
|
|
vars.FormatVariableHelpText = my_format
|
|
</pre><p>To make it more convenient to work with customizable Variables,
|
|
<span class="command"><strong>scons</strong></span>
|
|
provides a number of functions
|
|
that make it easy to set up
|
|
various types of Variables:</p></dd><dt><span class="term">BoolVariable(<span class="emphasis"><em>key</em></span>, <span class="emphasis"><em>help</em></span>, <span class="emphasis"><em>default</em></span>)</span></dt><dd><p>Return a tuple of arguments
|
|
to set up a Boolean option.
|
|
The option will use
|
|
the specified name
|
|
<span class="emphasis"><em>key</em></span>,
|
|
have a default value of
|
|
<span class="emphasis"><em>default</em></span>,
|
|
and display the specified
|
|
<span class="emphasis"><em>help</em></span>
|
|
text.
|
|
The option will interpret the values
|
|
<span class="bold"><strong>y</strong></span>,
|
|
<span class="bold"><strong>yes</strong></span>,
|
|
<span class="bold"><strong>t</strong></span>,
|
|
<span class="bold"><strong>true</strong></span>,
|
|
<code class="literal">1</code>,
|
|
<span class="bold"><strong>on</strong></span>
|
|
and
|
|
<span class="bold"><strong>all</strong></span>
|
|
as true,
|
|
and the values
|
|
<span class="bold"><strong>n</strong></span>,
|
|
<span class="bold"><strong>no</strong></span>,
|
|
<span class="bold"><strong>f</strong></span>,
|
|
<span class="bold"><strong>false</strong></span>,
|
|
<code class="literal">0</code>,
|
|
<span class="bold"><strong>off</strong></span>
|
|
and
|
|
<span class="bold"><strong>none</strong></span>
|
|
as false.</p></dd><dt><span class="term">EnumVariable(<span class="emphasis"><em>key</em></span>, <span class="emphasis"><em>help</em></span>, <span class="emphasis"><em>default</em></span>, <span class="emphasis"><em>allowed_values</em></span>, [<span class="emphasis"><em>map</em></span>, <span class="emphasis"><em>ignorecase</em></span>])</span></dt><dd><p>Return a tuple of arguments
|
|
to set up an option
|
|
whose value may be one
|
|
of a specified list of legal enumerated values.
|
|
The option will use
|
|
the specified name
|
|
<span class="emphasis"><em>key</em></span>,
|
|
have a default value of
|
|
<span class="emphasis"><em>default</em></span>,
|
|
and display the specified
|
|
<span class="emphasis"><em>help</em></span>
|
|
text.
|
|
The option will only support those
|
|
values in the
|
|
<span class="emphasis"><em>allowed_values</em></span>
|
|
list.
|
|
The optional
|
|
<span class="emphasis"><em>map</em></span>
|
|
argument is a dictionary
|
|
that can be used to convert
|
|
input values into specific legal values
|
|
in the
|
|
<span class="emphasis"><em>allowed_values</em></span>
|
|
list.
|
|
If the value of
|
|
<span class="emphasis"><em>ignore_case</em></span>
|
|
is
|
|
<code class="literal">0</code>
|
|
(the default),
|
|
then the values are case-sensitive.
|
|
If the value of
|
|
<span class="emphasis"><em>ignore_case</em></span>
|
|
is
|
|
<code class="literal">1</code>,
|
|
then values will be matched
|
|
case-insensitive.
|
|
If the value of
|
|
<span class="emphasis"><em>ignore_case</em></span>
|
|
is
|
|
<code class="literal">2</code>,
|
|
then values will be matched
|
|
case-insensitive,
|
|
and all input values will be
|
|
converted to lower case.</p></dd><dt><span class="term">ListVariable(<span class="emphasis"><em>key</em></span>, <span class="emphasis"><em>help</em></span>, <span class="emphasis"><em>default</em></span>, <span class="emphasis"><em>names</em></span>, [<span class="emphasis"><em>,</em></span>map<span class="emphasis"><em>])</em></span></span></dt><dd><p>Return a tuple of arguments
|
|
to set up an option
|
|
whose value may be one or more
|
|
of a specified list of legal enumerated values.
|
|
The option will use
|
|
the specified name
|
|
<span class="emphasis"><em>key</em></span>,
|
|
have a default value of
|
|
<span class="emphasis"><em>default</em></span>,
|
|
and display the specified
|
|
<span class="emphasis"><em>help</em></span>
|
|
text.
|
|
The option will only support the values
|
|
<span class="bold"><strong>all</strong></span>,
|
|
<span class="bold"><strong>none</strong></span>,
|
|
or the values in the
|
|
<span class="emphasis"><em>names</em></span>
|
|
list.
|
|
More than one value may be specified,
|
|
with all values separated by commas.
|
|
The default may be a string of
|
|
comma-separated default values,
|
|
or a list of the default values.
|
|
The optional
|
|
<span class="emphasis"><em>map</em></span>
|
|
argument is a dictionary
|
|
that can be used to convert
|
|
input values into specific legal values
|
|
in the
|
|
<span class="emphasis"><em>names</em></span>
|
|
list.</p></dd><dt><span class="term">PackageVariable(<span class="emphasis"><em>key</em></span>, <span class="emphasis"><em>help</em></span>, <span class="emphasis"><em>default</em></span>)</span></dt><dd><p>Return a tuple of arguments
|
|
to set up an option
|
|
whose value is a path name
|
|
of a package that may be
|
|
enabled, disabled or
|
|
given an explicit path name.
|
|
The option will use
|
|
the specified name
|
|
<span class="emphasis"><em>key</em></span>,
|
|
have a default value of
|
|
<span class="emphasis"><em>default</em></span>,
|
|
and display the specified
|
|
<span class="emphasis"><em>help</em></span>
|
|
text.
|
|
The option will support the values
|
|
<span class="bold"><strong>yes</strong></span>,
|
|
<span class="bold"><strong>true</strong></span>,
|
|
<span class="bold"><strong>on</strong></span>,
|
|
<span class="bold"><strong>enable</strong></span>
|
|
or
|
|
<span class="bold"><strong>search</strong></span>,
|
|
in which case the specified
|
|
<span class="emphasis"><em>default</em></span>
|
|
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
|
|
<span class="bold"><strong>no</strong></span>,
|
|
<span class="bold"><strong>false</strong></span>,
|
|
<span class="bold"><strong>off</strong></span>
|
|
or
|
|
<span class="bold"><strong>disable</strong></span>
|
|
to disable use of the specified option.</p></dd><dt><span class="term">PathVariable(<span class="emphasis"><em>key</em></span>, <span class="emphasis"><em>help</em></span>, <span class="emphasis"><em>default</em></span>, [<span class="emphasis"><em>validator</em></span>])</span></dt><dd><p>Return a tuple of arguments
|
|
to set up an option
|
|
whose value is expected to be a path name.
|
|
The option will use
|
|
the specified name
|
|
<span class="emphasis"><em>key</em></span>,
|
|
have a default value of
|
|
<span class="emphasis"><em>default</em></span>,
|
|
and display the specified
|
|
<span class="emphasis"><em>help</em></span>
|
|
text.
|
|
An additional
|
|
<span class="emphasis"><em>validator</em></span>
|
|
may be specified
|
|
that will be called to
|
|
verify that the specified path
|
|
is acceptable.
|
|
SCons supplies the
|
|
following ready-made validators:
|
|
<span class="bold"><strong>PathVariable.PathExists</strong></span>
|
|
(the default),
|
|
which verifies that the specified path exists;
|
|
<span class="bold"><strong>PathVariable.PathIsFile</strong></span>,
|
|
which verifies that the specified path is an existing file;
|
|
<span class="bold"><strong>PathVariable.PathIsDir</strong></span>,
|
|
which verifies that the specified path is an existing directory;
|
|
<span class="bold"><strong>PathVariable.PathIsDirCreate</strong></span>,
|
|
which verifies that the specified path is a directory
|
|
and will create the specified directory if the path does not exist;
|
|
and
|
|
<span class="bold"><strong>PathVariable.PathAccept</strong></span>,
|
|
which simply accepts the specific path name argument without validation,
|
|
and which is suitable if you want your users
|
|
to be able to specify a directory path that will be
|
|
created as part of the build process, for example.
|
|
You may supply your own
|
|
<span class="emphasis"><em>validator</em></span>
|
|
function,
|
|
which must take three arguments
|
|
(<span class="emphasis"><em>key</em></span>,
|
|
the name of the variable to be set;
|
|
<span class="emphasis"><em>val</em></span>,
|
|
the specified value being checked;
|
|
and
|
|
<span class="emphasis"><em>env</em></span>,
|
|
the construction environment)
|
|
and should raise an exception
|
|
if the specified value is not acceptable.</p></dd></dl></div><p>These functions make it
|
|
convenient to create a number
|
|
of variables with consistent behavior
|
|
in a single call to the
|
|
<span class="bold"><strong>AddVariables</strong></span>
|
|
method:</p><pre class="literallayout">
|
|
vars.AddVariables(
|
|
BoolVariable('warnings', 'compilation with -Wall and similiar', 1),
|
|
EnumVariable('debug', 'debug output and symbols', 'no'
|
|
allowed_values=('yes', 'no', 'full'),
|
|
map={}, ignorecase=0), # case sensitive
|
|
ListVariable('shared',
|
|
'libraries to build as shared libraries',
|
|
'all',
|
|
names = list_of_libs),
|
|
PackageVariable('x11',
|
|
'use X11 installed here (yes = search some places)',
|
|
'yes'),
|
|
PathVariable('qtdir', 'where the root of Qt is installed', qtdir),
|
|
PathVariable('foopath', 'where the foo library is installed', foopath,
|
|
PathVariable.PathIsDir),
|
|
|
|
)
|
|
</pre></div><div class="refsect2" title="File and Directory Nodes"><a name="file_and_directory_nodes"></a><h3>File and Directory Nodes</h3><p>The
|
|
<span class="emphasis"><em>File</em></span>()
|
|
and
|
|
<span class="emphasis"><em>Dir</em></span>()
|
|
functions return
|
|
<span class="emphasis"><em>File</em></span>
|
|
and
|
|
<span class="emphasis"><em>Dir</em></span>
|
|
Nodes, respectively.
|
|
python objects, respectively.
|
|
Those objects have several user-visible attributes
|
|
and methods that are often useful:</p><div class="variablelist"><dl><dt><span class="term">path</span></dt><dd><p>The build path
|
|
of the given
|
|
file or directory.
|
|
This path is relative to the top-level directory
|
|
(where the
|
|
<span class="bold"><strong>SConstruct</strong></span>
|
|
file is found).
|
|
The build path is the same as the source path if
|
|
<span class="emphasis"><em>variant_dir</em></span>
|
|
is not being used.</p></dd><dt><span class="term">abspath</span></dt><dd><p>The absolute build path of the given file or directory.</p></dd><dt><span class="term">srcnode()</span></dt><dd><p>The
|
|
<span class="emphasis"><em>srcnode</em></span>()
|
|
method
|
|
returns another
|
|
<span class="emphasis"><em>File</em></span>
|
|
or
|
|
<span class="emphasis"><em>Dir</em></span>
|
|
object representing the
|
|
<span class="emphasis"><em>source</em></span>
|
|
path of the given
|
|
<span class="emphasis"><em>File</em></span>
|
|
or
|
|
<span class="emphasis"><em>Dir</em></span>.
|
|
The</p><pre class="literallayout">
|
|
# Get the current build dir's path, relative to top.
|
|
Dir('.').path
|
|
# Current dir's absolute path
|
|
Dir('.').abspath
|
|
# Next line is always '.', because it is the top dir's path relative to itself.
|
|
Dir('#.').path
|
|
File('foo.c').srcnode().path # source path of the given source file.
|
|
|
|
# Builders also return File objects:
|
|
foo = env.Program('foo.c')
|
|
print("foo will be built in %s"%foo.path)
|
|
</pre><p>A
|
|
<span class="emphasis"><em>Dir</em></span>
|
|
Node or
|
|
<span class="emphasis"><em>File</em></span>
|
|
Node can also be used to create
|
|
file and subdirectory Nodes relative to the generating Node.
|
|
A
|
|
<span class="emphasis"><em>Dir</em></span>
|
|
Node will place the new Nodes within the directory it represents.
|
|
A
|
|
<span class="emphasis"><em>File</em></span>
|
|
node will place the new Nodes within its parent directory
|
|
(that is, "beside" the file in question).
|
|
If
|
|
<span class="emphasis"><em>d</em></span>
|
|
is a
|
|
<span class="emphasis"><em>Dir</em></span>
|
|
(directory) Node and
|
|
<span class="emphasis"><em>f</em></span>
|
|
is a
|
|
<span class="emphasis"><em>File</em></span>
|
|
(file) Node,
|
|
then these methods are available:</p></dd></dl></div><div class="variablelist"><dl><dt><span class="term"><span class="emphasis"><em>d</em></span>.Dir(<span class="emphasis"><em>name</em></span>)</span></dt><dd><p>Returns a directory Node for a subdirectory of
|
|
<span class="emphasis"><em>d</em></span>
|
|
named
|
|
<span class="emphasis"><em>name</em></span>.</p></dd><dt><span class="term"><span class="emphasis"><em>d</em></span>.File(<span class="emphasis"><em>name</em></span>)</span></dt><dd><p>Returns a file Node for a file within
|
|
<span class="emphasis"><em>d</em></span>
|
|
named
|
|
<span class="emphasis"><em>name</em></span>.</p></dd><dt><span class="term"><span class="emphasis"><em>d</em></span>.Entry(<span class="emphasis"><em>name</em></span>)</span></dt><dd><p>Returns an unresolved Node within
|
|
<span class="emphasis"><em>d</em></span>
|
|
named
|
|
<span class="emphasis"><em>name</em></span>.</p></dd><dt><span class="term"><span class="emphasis"><em>f</em></span>.Dir(<span class="emphasis"><em>name</em></span>)</span></dt><dd><p>Returns a directory named
|
|
<span class="emphasis"><em>name</em></span>
|
|
within the parent directory of
|
|
<span class="emphasis"><em>f</em></span>.</p></dd><dt><span class="term"><span class="emphasis"><em>f</em></span>.File(<span class="emphasis"><em>name</em></span>)</span></dt><dd><p>Returns a file named
|
|
<span class="emphasis"><em>name</em></span>
|
|
within the parent directory of
|
|
<span class="emphasis"><em>f</em></span>.</p></dd><dt><span class="term"><span class="emphasis"><em>f</em></span>.Entry(<span class="emphasis"><em>name</em></span>)</span></dt><dd><p>Returns an unresolved Node named
|
|
<span class="emphasis"><em>name</em></span>
|
|
within the parent directory of
|
|
<span class="emphasis"><em>f</em></span>.</p></dd></dl></div><p>For example:</p><pre class="literallayout">
|
|
# 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')
|
|
</pre></div></div><div class="refsect1" title="EXTENDING SCONS"><a name="extending_scons"></a><h2>EXTENDING SCONS</h2><div class="refsect2" title="Builder Objects"><a name="builder_objects"></a><h3>Builder Objects</h3><p><span class="command"><strong>scons</strong></span>
|
|
can be extended to build different types of targets
|
|
by adding new Builder objects
|
|
to a construction environment.
|
|
<span class="emphasis"><em>In general</em></span>,
|
|
you should only need to add a new Builder object
|
|
when you want to build a new type of file or other external target.
|
|
If you just want to invoke a different compiler or other tool
|
|
to build a Program, Object, Library, or any other
|
|
type of output file for which
|
|
<span class="command"><strong>scons</strong></span>
|
|
already has an existing Builder,
|
|
it is generally much easier to
|
|
use those existing Builders
|
|
in a construction environment
|
|
that sets the appropriate construction variables
|
|
(CC, LINK, etc.).</p><p>Builder objects are created
|
|
using the
|
|
<span class="bold"><strong>Builder</strong></span>
|
|
function.
|
|
The
|
|
<span class="bold"><strong>Builder</strong></span>
|
|
function accepts the following arguments:</p><div class="variablelist"><dl><dt><span class="term">action</span></dt><dd><p>The command line string used to build the target from the source.
|
|
<span class="bold"><strong>action</strong></span>
|
|
can also be:
|
|
a list of strings representing the command
|
|
to be executed and its arguments
|
|
(suitable for enclosing white space in an argument),
|
|
a dictionary
|
|
mapping source file name suffixes to
|
|
any combination of command line strings
|
|
(if the builder should accept multiple source file extensions),
|
|
a Python function;
|
|
an Action object
|
|
(see the next section);
|
|
or a list of any of the above.</p><p>An action function
|
|
takes three arguments:
|
|
<span class="emphasis"><em>source</em></span>
|
|
- a list of source nodes,
|
|
<span class="emphasis"><em>target</em></span>
|
|
- a list of target nodes,
|
|
<span class="emphasis"><em>env</em></span>
|
|
- the construction environment.</p></dd><dt><span class="term">prefix</span></dt><dd><p>The prefix that will be prepended to the target file name.
|
|
This may be specified as a:</p><div class="blockquote"><blockquote class="blockquote"><p>*
|
|
<span class="emphasis"><em>string</em></span>,</p><p>*
|
|
<span class="emphasis"><em>callable object</em></span>
|
|
- a function or other callable that takes
|
|
two arguments (a construction environment and a list of sources)
|
|
and returns a prefix,</p><p>*
|
|
<span class="emphasis"><em>dictionary</em></span>
|
|
- specifies a mapping from a specific source suffix (of the first
|
|
source specified) to a corresponding target prefix. Both the source
|
|
suffix and target prefix specifications may use environment variable
|
|
substitution, and the target prefix (the 'value' entries in the
|
|
dictionary) may also be a callable object. The default target prefix
|
|
may be indicated by a dictionary entry with a key value of None.
|
|
</p></blockquote></div></dd></dl></div><pre class="programlisting">
|
|
b = Builder("build_it < $SOURCE > $TARGET",
|
|
prefix = "file-")
|
|
|
|
def gen_prefix(env, sources):
|
|
return "file-" + env['PLATFORM'] + '-'
|
|
b = Builder("build_it < $SOURCE > $TARGET",
|
|
prefix = gen_prefix)
|
|
|
|
b = Builder("build_it < $SOURCE > $TARGET",
|
|
suffix = { None: "file-",
|
|
"$SRC_SFX_A": gen_prefix })
|
|
</pre><div class="variablelist"><dl><dt><span class="term">suffix</span></dt><dd><p>The suffix that will be appended to the target file name.
|
|
This may be specified in the same manner as the prefix above.
|
|
If the suffix is a string, then
|
|
<span class="command"><strong>scons</strong></span>
|
|
will append a '.' to the beginning of the suffix if it's not already
|
|
there. The string returned by callable object (or obtained from the
|
|
dictionary) is untouched and must append its own '.' to the beginning
|
|
if one is desired.</p><pre class="programlisting">
|
|
b = Builder("build_it < $SOURCE > $TARGET"
|
|
suffix = "-file")
|
|
|
|
def gen_suffix(env, sources):
|
|
return "." + env['PLATFORM'] + "-file"
|
|
b = Builder("build_it < $SOURCE > $TARGET",
|
|
suffix = gen_suffix)
|
|
|
|
b = Builder("build_it < $SOURCE > $TARGET",
|
|
suffix = { None: ".sfx1",
|
|
"$SRC_SFX_A": gen_suffix })
|
|
</pre></dd><dt><span class="term">ensure_suffix</span></dt><dd><p>When set to any true value, causes
|
|
<span class="command"><strong>scons</strong></span>
|
|
to add the target suffix specified by the
|
|
<span class="emphasis"><em>suffix</em></span>
|
|
keyword to any target strings
|
|
that have a different suffix.
|
|
(The default behavior is to leave untouched
|
|
any target file name that looks like it already has any suffix.)</p><pre class="literallayout">
|
|
b1 = Builder("build_it < $SOURCE > $TARGET"
|
|
suffix = ".out")
|
|
b2 = Builder("build_it < $SOURCE > $TARGET"
|
|
suffix = ".out",
|
|
ensure_suffix)
|
|
env = Environment()
|
|
env['BUILDERS']['B1'] = b1
|
|
env['BUILDERS']['B2'] = b2
|
|
|
|
# Builds "foo.txt" because ensure_suffix is not set.
|
|
env.B1('foo.txt', 'foo.in')
|
|
|
|
# Builds "bar.txt.out" because ensure_suffix is set.
|
|
env.B2('bar.txt', 'bar.in')
|
|
</pre></dd><dt><span class="term">src_suffix</span></dt><dd><p>The expected source file name suffix. This may be a string or a list
|
|
of strings.</p></dd><dt><span class="term">target_scanner</span></dt><dd><p>A Scanner object that
|
|
will be invoked to find
|
|
implicit dependencies for this target file.
|
|
This keyword argument should be used
|
|
for Scanner objects that find
|
|
implicit dependencies
|
|
based only on the target file
|
|
and the construction environment,
|
|
<span class="emphasis"><em>not</em></span>
|
|
for implicit dependencies based on source files.
|
|
(See the section "Scanner Objects" below,
|
|
for information about creating Scanner objects.)</p></dd><dt><span class="term">source_scanner</span></dt><dd><p>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
|
|
<span class="bold"><strong>#include</strong></span>
|
|
lines in source files.
|
|
The pre-built
|
|
<span class="bold"><strong>DirScanner</strong></span>
|
|
Scanner object may be used to
|
|
indicate that this Builder
|
|
should scan directory trees
|
|
for on-disk changes to files
|
|
that
|
|
<span class="command"><strong>scons</strong></span>
|
|
does not know about from other Builder or function calls.
|
|
(See the section "Scanner Objects" below,
|
|
for information about creating your own Scanner objects.)</p></dd><dt><span class="term">target_factory</span></dt><dd><p>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
|
|
<span class="bold"><strong>Dir</strong></span>,
|
|
for when a Builder creates a directory target,
|
|
and
|
|
<span class="bold"><strong>Entry</strong></span>,
|
|
for when a Builder can create either a file
|
|
or directory target.</p><p>Example:</p><pre class="literallayout">
|
|
MakeDirectoryBuilder = Builder(action=my_mkdir, target_factory=Dir)
|
|
env = Environment()
|
|
env.Append(BUILDERS = {'MakeDirectory':MakeDirectoryBuilder})
|
|
env.MakeDirectory('new_directory', [])
|
|
</pre><p>Note that the call to the MakeDirectory Builder
|
|
needs to specify an empty source list
|
|
to make the string represent the builder's target;
|
|
without that, it would assume the argument is the source,
|
|
and would try to deduce the target name from it,
|
|
which in the absence of an automatically-added prefix or suffix
|
|
would lead to a matching target and source name
|
|
and a circular dependency.</p></dd><dt><span class="term">source_factory</span></dt><dd><p>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
|
|
<span class="bold"><strong>Dir</strong></span>,
|
|
for when a Builder uses a directory as a source,
|
|
and
|
|
<span class="bold"><strong>Entry</strong></span>,
|
|
for when a Builder can use files
|
|
or directories (or both) as sources.</p><p>Example:</p><pre class="programlisting">
|
|
CollectBuilder = Builder(action=my_mkdir, source_factory=Entry)
|
|
env = Environment()
|
|
env.Append(BUILDERS = {'Collect':CollectBuilder})
|
|
env.Collect('archive', ['directory_name', 'file_name'])
|
|
</pre></dd><dt><span class="term">emitter</span></dt><dd><p>A function or list of functions to manipulate the target and source
|
|
lists before dependencies are established
|
|
and the target(s) are actually built.
|
|
<span class="bold"><strong>emitter</strong></span>
|
|
can also be a string containing a construction variable to expand
|
|
to an emitter function or list of functions,
|
|
or a dictionary mapping source file suffixes
|
|
to emitter functions.
|
|
(Only the suffix of the first source file
|
|
is used to select the actual emitter function
|
|
from an emitter dictionary.)</p><p>An emitter function
|
|
takes three arguments:
|
|
<span class="emphasis"><em>source</em></span>
|
|
- a list of source nodes,
|
|
<span class="emphasis"><em>target</em></span>
|
|
- a list of target nodes,
|
|
<span class="emphasis"><em>env</em></span>
|
|
- the construction environment.
|
|
An emitter must return a tuple containing two lists,
|
|
the list of targets to be built by this builder,
|
|
and the list of sources for this builder.</p><p>Example:</p><pre class="programlisting">
|
|
def e(target, source, env):
|
|
return (target + ['foo.foo'], source + ['foo.src'])
|
|
|
|
# Simple association of an emitter function with a Builder.
|
|
b = Builder("my_build < $TARGET > $SOURCE",
|
|
emitter = e)
|
|
|
|
def e2(target, source, env):
|
|
return (target + ['bar.foo'], source + ['bar.src'])
|
|
|
|
# Simple association of a list of emitter functions with a Builder.
|
|
b = Builder("my_build < $TARGET > $SOURCE",
|
|
emitter = [e, e2])
|
|
|
|
# Calling an emitter function through a construction variable.
|
|
env = Environment(MY_EMITTER = e)
|
|
b = Builder("my_build < $TARGET > $SOURCE",
|
|
emitter = '$MY_EMITTER')
|
|
|
|
# Calling a list of emitter functions through a construction variable.
|
|
env = Environment(EMITTER_LIST = [e, e2])
|
|
b = Builder("my_build < $TARGET > $SOURCE",
|
|
emitter = '$EMITTER_LIST')
|
|
|
|
# Associating multiple emitters with different file
|
|
# suffixes using a dictionary.
|
|
def e_suf1(target, source, env):
|
|
return (target + ['another_target_file'], source)
|
|
def e_suf2(target, source, env):
|
|
return (target, source + ['another_source_file'])
|
|
b = Builder("my_build < $TARGET > $SOURCE",
|
|
emitter = {'.suf1' : e_suf1,
|
|
'.suf2' : e_suf2})
|
|
</pre></dd><dt><span class="term">multi</span></dt><dd><p>Specifies whether this builder is allowed to be called multiple times for
|
|
the same target file(s). The default is 0, which means the builder
|
|
can not be called multiple times for the same target file(s). Calling a
|
|
builder multiple times for the same target simply adds additional source
|
|
files to the target; it is not allowed to change the environment associated
|
|
with the target, specify addition environment overrides, or associate a different
|
|
builder with the target.</p></dd><dt><span class="term">env</span></dt><dd><p>A construction environment that can be used
|
|
to fetch source code using this Builder.
|
|
(Note that this environment is
|
|
<span class="emphasis"><em>not</em></span>
|
|
used for normal builds of normal target files,
|
|
which use the environment that was
|
|
used to call the Builder for the target file.)</p></dd><dt><span class="term">generator</span></dt><dd><p>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).</p><p>The generator function
|
|
takes four arguments:
|
|
<span class="emphasis"><em>source</em></span>
|
|
- a list of source nodes,
|
|
<span class="emphasis"><em>target</em></span>
|
|
- a list of target nodes,
|
|
<span class="emphasis"><em>env</em></span>
|
|
- the construction environment,
|
|
<span class="emphasis"><em>for_signature</em></span>
|
|
- a Boolean value that specifies
|
|
whether the generator is being called
|
|
for generating a build signature
|
|
(as opposed to actually executing the command).
|
|
Example:</p><pre class="programlisting">
|
|
def g(source, target, env, for_signature):
|
|
return [["gcc", "-c", "-o"] + target + source]
|
|
|
|
b = Builder(generator=g)
|
|
</pre><p>The
|
|
<span class="emphasis"><em>generator</em></span>
|
|
and
|
|
<span class="emphasis"><em>action</em></span>
|
|
arguments must not both be used for the same Builder.</p></dd><dt><span class="term">src_builder</span></dt><dd><p>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.</p></dd><dt><span class="term">single_source</span></dt><dd><p>Specifies that this builder expects exactly one source file per call. Giving
|
|
more than one source file without target files results in implicitly calling
|
|
the builder multiple times (once for each source given). Giving multiple
|
|
source files together with target files results in a UserError exception.</p></dd></dl></div><p>The
|
|
<span class="emphasis"><em>generator</em></span>
|
|
and
|
|
<span class="emphasis"><em>action</em></span>
|
|
arguments must not both be used for the same Builder.</p><div class="variablelist"><dl><dt><span class="term">source_ext_match</span></dt><dd><p>When the specified
|
|
<span class="emphasis"><em>action</em></span>
|
|
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
|
|
<span class="bold"><strong>source_ext_match</strong></span>
|
|
to
|
|
<span class="bold"><strong>None</strong></span>
|
|
or some other non-true value.
|
|
When
|
|
<span class="bold"><strong>source_ext_match</strong></span>
|
|
is disable,
|
|
<span class="command"><strong>scons</strong></span>
|
|
will use the suffix of the first specified
|
|
source file to select the appropriate action from the
|
|
<span class="emphasis"><em>action</em></span>
|
|
dictionary.</p><p>In the following example,
|
|
the setting of
|
|
<span class="bold"><strong>source_ext_match</strong></span>
|
|
prevents
|
|
<span class="command"><strong>scons</strong></span>
|
|
from exiting with an error
|
|
due to the mismatched suffixes of
|
|
<span class="bold"><strong>foo.in</strong></span>
|
|
and
|
|
<span class="bold"><strong>foo.extra</strong></span>.</p><pre class="literallayout">
|
|
b = Builder(action={'.in' : 'build $SOURCES > $TARGET'},
|
|
source_ext_match = None)
|
|
|
|
env = Environment(BUILDERS = {'MyBuild':b})
|
|
env.MyBuild('foo.out', ['foo.in', 'foo.extra'])
|
|
</pre></dd><dt><span class="term">env</span></dt><dd><p>A construction environment that can be used
|
|
to fetch source code using this Builder.
|
|
(Note that this environment is
|
|
<span class="emphasis"><em>not</em></span>
|
|
used for normal builds of normal target files,
|
|
which use the environment that was
|
|
used to call the Builder for the target file.)</p><pre class="literallayout">
|
|
b = Builder(action="build < $SOURCE > $TARGET")
|
|
env = Environment(BUILDERS = {'MyBuild' : b})
|
|
env.MyBuild('foo.out', 'foo.in', my_arg = 'xyzzy')
|
|
</pre></dd><dt><span class="term">chdir</span></dt><dd><p>A directory from which scons
|
|
will execute the
|
|
action(s) specified
|
|
for this Builder.
|
|
If the
|
|
<span class="bold"><strong>chdir</strong></span>
|
|
argument is
|
|
a string or a directory Node,
|
|
scons will change to the specified directory.
|
|
If the
|
|
<span class="bold"><strong>chdir</strong></span>
|
|
is not a string or Node
|
|
and is non-zero,
|
|
then scons will change to the
|
|
target file's directory.</p><p>Note that scons will
|
|
<span class="emphasis"><em>not</em></span>
|
|
automatically modify
|
|
its expansion of
|
|
construction variables like
|
|
<span class="bold"><strong>$TARGET</strong></span>
|
|
and
|
|
<span class="bold"><strong>$SOURCE</strong></span>
|
|
when using the chdir
|
|
keyword argument--that is,
|
|
the expanded file names
|
|
will still be relative to
|
|
the top-level SConstruct directory,
|
|
and consequently incorrect
|
|
relative to the chdir directory.
|
|
Builders created using chdir keyword argument,
|
|
will need to use construction variable
|
|
expansions like
|
|
<span class="bold"><strong>${TARGET.file}</strong></span>
|
|
and
|
|
<span class="bold"><strong>${SOURCE.file}</strong></span>
|
|
to use just the filename portion of the
|
|
targets and source.</p><pre class="literallayout">
|
|
b = Builder(action="build < ${SOURCE.file} > ${TARGET.file}",
|
|
chdir=1)
|
|
env = Environment(BUILDERS = {'MyBuild' : b})
|
|
env.MyBuild('sub/dir/foo.out', 'sub/dir/foo.in')
|
|
</pre><p><span class="bold"><strong>WARNING:</strong></span>
|
|
Python only keeps one current directory
|
|
location for all of the threads.
|
|
This means that use of the
|
|
<span class="bold"><strong>chdir</strong></span>
|
|
argument
|
|
will
|
|
<span class="emphasis"><em>not</em></span>
|
|
work with the SCons
|
|
<code class="option">-j</code>
|
|
option,
|
|
because individual worker threads spawned
|
|
by SCons interfere with each other
|
|
when they start changing directory.</p></dd></dl></div><p>Any additional keyword arguments supplied
|
|
when a Builder object is created
|
|
(that is, when the Builder() function is called)
|
|
will be set in the executing construction
|
|
environment when the Builder object is called.
|
|
The canonical example here would be
|
|
to set a construction variable to
|
|
the repository of a source code system.</p><p>Any additional keyword arguments supplied
|
|
when a Builder
|
|
<span class="emphasis"><em>object</em></span>
|
|
is called
|
|
will only be associated with the target
|
|
created by that particular Builder call
|
|
(and any other files built as a
|
|
result of the call).</p><p>These extra keyword arguments are passed to the
|
|
following functions:
|
|
command generator functions,
|
|
function Actions,
|
|
and emitter functions.</p></div><div class="refsect2" title="Action Objects"><a name="action_objects"></a><h3>Action Objects</h3><p>The
|
|
<span class="bold"><strong>Builder</strong></span>()
|
|
function will turn its
|
|
<span class="bold"><strong>action</strong></span>
|
|
keyword argument into an appropriate
|
|
internal Action object.
|
|
You can also explicitly create Action objects
|
|
using the
|
|
<span class="bold"><strong>Action</strong></span>()
|
|
global function,
|
|
which can then be passed to the
|
|
<span class="bold"><strong>Builder</strong></span>()
|
|
function.
|
|
This can be used to configure
|
|
an Action object more flexibly,
|
|
or it may simply be more efficient
|
|
than letting each separate Builder object
|
|
create a separate Action
|
|
when multiple
|
|
Builder objects need to do the same thing.</p><p>The
|
|
<span class="bold"><strong>Action</strong></span>()
|
|
global function
|
|
returns an appropriate object for the action
|
|
represented by the type of the first argument:</p><div class="variablelist"><dl><dt><span class="term">Action</span></dt><dd><p>If the first argument is already an Action object,
|
|
the object is simply returned.</p></dd><dt><span class="term">String</span></dt><dd><p>If the first argument is a string,
|
|
a command-line Action is returned.
|
|
Note that the command-line string
|
|
may be preceded by an
|
|
<span class="bold"><strong>@</strong></span>
|
|
(at-sign)
|
|
to suppress printing of the specified command line,
|
|
or by a
|
|
<span class="bold"><strong>-</strong></span>
|
|
(hyphen)
|
|
to ignore the exit status from the specified command:</p><pre class="literallayout">
|
|
Action('$CC -c -o $TARGET $SOURCES')
|
|
|
|
# Doesn't print the line being executed.
|
|
Action('@build $TARGET $SOURCES')
|
|
|
|
# Ignores return value
|
|
Action('-build $TARGET $SOURCES')
|
|
</pre></dd><dt><span class="term">List</span></dt><dd><p>If the first argument is a list,
|
|
then a list of Action objects is returned.
|
|
An Action object is created as necessary
|
|
for each element in the list.
|
|
If an element
|
|
<span class="emphasis"><em>within</em></span>
|
|
the list is itself a list,
|
|
the internal list is the
|
|
command and arguments to be executed via
|
|
the command line.
|
|
This allows white space to be enclosed
|
|
in an argument by defining
|
|
a command in a list within a list:</p><pre class="literallayout">
|
|
Action([['cc', '-c', '-DWHITE SPACE', '-o', '$TARGET', '$SOURCES']])
|
|
</pre></dd><dt><span class="term">Function</span></dt><dd><p>If the first argument is a Python function,
|
|
a function Action is returned.
|
|
The Python function must take three keyword arguments,
|
|
<span class="bold"><strong>target</strong></span>
|
|
(a Node object representing the target file),
|
|
<span class="bold"><strong>source</strong></span>
|
|
(a Node object representing the source file)
|
|
and
|
|
<span class="bold"><strong>env</strong></span>
|
|
(the construction environment
|
|
used for building the target file).
|
|
The
|
|
<span class="bold"><strong>target</strong></span>
|
|
and
|
|
<span class="bold"><strong>source</strong></span>
|
|
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 <code class="function">str</code> function:</p><pre class="literallayout">
|
|
target_file_name = str(target)
|
|
source_file_names = [str(x) for x in source]
|
|
</pre><p>The function should return
|
|
<code class="literal">0</code>
|
|
or
|
|
<span class="bold"><strong>None</strong></span>
|
|
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.</p><pre class="programlisting">
|
|
def build_it(target = None, source = None, env = None):
|
|
# build the target from the source
|
|
return 0
|
|
|
|
a = Action(build_it)
|
|
</pre><p>If the action argument is not one of the above,
|
|
None is returned.</p></dd></dl></div><p>The second argument is optional and is used to define the output
|
|
which is printed when the Action is actually performed.
|
|
In the absence of this parameter,
|
|
or if it's an empty string,
|
|
a default output depending on the type of the action is used.
|
|
For example, a command-line action will print the executed command.
|
|
The argument must be either a Python function or a string.</p><p>In the first case,
|
|
it's a function that returns a string to be printed
|
|
to describe the action being executed.
|
|
The function may also be specified by the
|
|
<span class="emphasis"><em>strfunction</em></span>=
|
|
keyword argument.
|
|
Like a function to build a file,
|
|
this function must take three keyword arguments:
|
|
<span class="bold"><strong>target</strong></span>
|
|
(a Node object representing the target file),
|
|
<span class="bold"><strong>source</strong></span>
|
|
(a Node object representing the source file)
|
|
and
|
|
<span class="bold"><strong>env</strong></span>
|
|
(a construction environment).
|
|
The
|
|
<span class="bold"><strong>target</strong></span>
|
|
and
|
|
<span class="bold"><strong>source</strong></span>
|
|
arguments may be lists of Node objects if there is
|
|
more than one target file or source file.</p><p>In the second case, you provide the string itself.
|
|
The string may also be specified by the
|
|
<span class="emphasis"><em>cmdstr</em></span>=
|
|
keyword argument.
|
|
The string typically contains variables, notably
|
|
$TARGET(S) and $SOURCE(S), or consists of just a single
|
|
variable, which is optionally defined somewhere else.
|
|
SCons itself heavily uses the latter variant.</p><p>Examples:</p><pre class="programlisting">
|
|
def build_it(target, source, env):
|
|
# build the target from the source
|
|
return 0
|
|
|
|
def string_it(target, source, env):
|
|
return "building '%s' from '%s'" % (target[0], source[0])
|
|
|
|
# Use a positional argument.
|
|
f = Action(build_it, string_it)
|
|
s = Action(build_it, "building '$TARGET' from '$SOURCE'")
|
|
|
|
# Alternatively, use a keyword argument.
|
|
f = Action(build_it, strfunction=string_it)
|
|
s = Action(build_it, cmdstr="building '$TARGET' from '$SOURCE'")
|
|
|
|
# You can provide a configurable variable.
|
|
l = Action(build_it, '$STRINGIT')
|
|
</pre><p>The third and succeeding arguments, if present,
|
|
may either be a construction variable or a list of construction variables
|
|
whose values will be included in the signature of the Action
|
|
when deciding whether a target should be rebuilt because the action changed.
|
|
The variables may also be specified by a
|
|
<span class="emphasis"><em>varlist</em></span>=
|
|
keyword parameter;
|
|
if both are present, they are combined.
|
|
This is necessary whenever you want a target to be rebuilt
|
|
when a specific construction variable changes.
|
|
This is not often needed for a string action,
|
|
as the expanded variables will normally be part of the command line,
|
|
but may be needed if a Python function action uses
|
|
the value of a construction variable when generating the command line.</p><pre class="programlisting">
|
|
def build_it(target, source, env):
|
|
# build the target from the 'XXX' construction variable
|
|
open(target[0], 'w').write(env['XXX'])
|
|
return 0
|
|
|
|
# Use positional arguments.
|
|
a = Action(build_it, '$STRINGIT', ['XXX'])
|
|
|
|
# Alternatively, use a keyword argument.
|
|
a = Action(build_it, varlist=['XXX'])
|
|
</pre><p>The
|
|
<span class="bold"><strong>Action</strong></span>()
|
|
global function
|
|
can be passed the following
|
|
optional keyword arguments
|
|
to modify the Action object's behavior:</p><p><span class="bold"><strong>chdir</strong></span>
|
|
The
|
|
<span class="bold"><strong>chdir</strong></span>
|
|
keyword argument specifies that
|
|
scons will execute the action
|
|
after changing to the specified directory.
|
|
If the
|
|
<span class="bold"><strong>chdir</strong></span>
|
|
argument is
|
|
a string or a directory Node,
|
|
scons will change to the specified directory.
|
|
If the
|
|
<span class="bold"><strong>chdir</strong></span>
|
|
argument
|
|
is not a string or Node
|
|
and is non-zero,
|
|
then scons will change to the
|
|
target file's directory.</p><p>Note that scons will
|
|
<span class="emphasis"><em>not</em></span>
|
|
automatically modify
|
|
its expansion of
|
|
construction variables like
|
|
<span class="bold"><strong>$TARGET</strong></span>
|
|
and
|
|
<span class="bold"><strong>$SOURCE</strong></span>
|
|
when using the chdir
|
|
keyword argument--that is,
|
|
the expanded file names
|
|
will still be relative to
|
|
the top-level SConstruct directory,
|
|
and consequently incorrect
|
|
relative to the chdir directory.
|
|
Builders created using chdir keyword argument,
|
|
will need to use construction variable
|
|
expansions like
|
|
<span class="bold"><strong>${TARGET.file}</strong></span>
|
|
and
|
|
<span class="bold"><strong>${SOURCE.file}</strong></span>
|
|
to use just the filename portion of the
|
|
targets and source.</p><pre class="literallayout">
|
|
a = Action("build < ${SOURCE.file} > ${TARGET.file}",
|
|
chdir=1)
|
|
</pre><p><span class="bold"><strong>exitstatfunc</strong></span>
|
|
The
|
|
<span class="bold"><strong>Action</strong></span>()
|
|
global function
|
|
also takes an
|
|
<span class="bold"><strong>exitstatfunc</strong></span>
|
|
keyword argument
|
|
which specifies a function
|
|
that is passed the exit status
|
|
(or return value)
|
|
from the specified action
|
|
and can return an arbitrary
|
|
or modified value.
|
|
This can be used, for example,
|
|
to specify that an Action object's
|
|
return value should be ignored
|
|
under special conditions
|
|
and SCons should, therefore,
|
|
consider that the action always suceeds:</p><pre class="programlisting">
|
|
def always_succeed(s):
|
|
# Always return 0, which indicates success.
|
|
return 0
|
|
a = Action("build < ${SOURCE.file} > ${TARGET.file}",
|
|
exitstatfunc=always_succeed)
|
|
</pre><p><span class="bold"><strong>batch_key</strong></span>
|
|
The
|
|
<span class="bold"><strong>batch_key</strong></span>
|
|
keyword argument can be used
|
|
to specify that the Action can create multiple target files
|
|
by processing multiple independent source files simultaneously.
|
|
(The canonical example is "batch compilation"
|
|
of multiple object files
|
|
by passing multiple source files
|
|
to a single invocation of a compiler
|
|
such as Microsoft's Visual C / C++ compiler.)
|
|
If the
|
|
<span class="bold"><strong>batch_key</strong></span>
|
|
argument is any non-False, non-callable Python value,
|
|
the configured Action object will cause
|
|
<span class="command"><strong>scons</strong></span>
|
|
to collect all targets built with the Action object
|
|
and configured with the same construction environment
|
|
into single invocations of the Action object's
|
|
command line or function.
|
|
Command lines will typically want to use the
|
|
<span class="bold"><strong>CHANGED_SOURCES</strong></span>
|
|
construction variable
|
|
(and possibly
|
|
<span class="bold"><strong>CHANGED_TARGETS</strong></span>
|
|
as well)
|
|
to only pass to the command line those sources that
|
|
have actually changed since their targets were built.</p><p>Example:</p><pre class="literallayout">
|
|
a = Action('build $CHANGED_SOURCES', batch_key=True)
|
|
</pre><p>The
|
|
<span class="bold"><strong>batch_key</strong></span>
|
|
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
|
|
<span class="bold"><strong>batch_key</strong></span>
|
|
function must take the following arguments:</p><div class="variablelist"><dl><dt><span class="term">action</span></dt><dd><p>The action object.</p></dd><dt><span class="term">env</span></dt><dd><p>The construction environment
|
|
configured for the target.</p></dd><dt><span class="term">target</span></dt><dd><p>The list of targets for a particular configured action.</p></dd><dt><span class="term">source</span></dt><dd><p>The list of source for a particular configured action.</p><p>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
|
|
<span class="bold"><strong>batch_key</strong></span>
|
|
function may decide to return
|
|
the value of a specific construction
|
|
variable from the
|
|
<span class="bold"><strong>env</strong></span>
|
|
argument
|
|
which will cause
|
|
<span class="command"><strong>scons</strong></span>
|
|
to batch-build targets
|
|
with matching values of that variable,
|
|
or perhaps return the
|
|
<span class="bold"><strong>id</strong></span>()
|
|
of the entire construction environment,
|
|
in which case
|
|
<span class="command"><strong>scons</strong></span>
|
|
will batch-build
|
|
all targets configured with the same construction environment.
|
|
Returning
|
|
<span class="bold"><strong>None</strong></span>
|
|
indicates that
|
|
the particular target should
|
|
<span class="emphasis"><em>not</em></span>
|
|
be part of any batched build,
|
|
but instead will be built
|
|
by a separate invocation of action's
|
|
command or function.
|
|
Example:</p><pre class="programlisting">
|
|
def batch_key(action, env, target, source):
|
|
tdir = target[0].dir
|
|
if tdir.name == 'special':
|
|
# Don't batch-build any target
|
|
# in the special/ subdirectory.
|
|
return None
|
|
return (id(action), id(env), tdir)
|
|
a = Action('build $CHANGED_SOURCES', batch_key=batch_key)
|
|
</pre></dd></dl></div></div><div class="refsect2" title="Miscellaneous Action Functions"><a name="miscellaneous_action_functions"></a><h3>Miscellaneous Action Functions</h3><p><span class="command"><strong>scons</strong></span>
|
|
supplies a number of functions
|
|
that arrange for various common
|
|
file and directory manipulations
|
|
to be performed.
|
|
These are similar in concept to "tasks" in the
|
|
Ant build tool,
|
|
although the implementation is slightly different.
|
|
These functions do not actually
|
|
perform the specified action
|
|
at the time the function is called,
|
|
but instead return an Action object
|
|
that can be executed at the
|
|
appropriate time.
|
|
(In Object-Oriented terminology,
|
|
these are actually
|
|
Action
|
|
<span class="emphasis"><em>Factory</em></span>
|
|
functions
|
|
that return Action objects.)</p><p>In practice,
|
|
there are two natural ways
|
|
that these
|
|
Action Functions
|
|
are intended to be used.</p><p>First,
|
|
if you need
|
|
to perform the action
|
|
at the time the SConscript
|
|
file is being read,
|
|
you can use the
|
|
<span class="bold"><strong>Execute</strong></span>
|
|
global function to do so:</p><pre class="literallayout">
|
|
Execute(Touch('file'))
|
|
</pre><p>Second,
|
|
you can use these functions
|
|
to supply Actions in a list
|
|
for use by the
|
|
<span class="bold"><strong>Command</strong></span>
|
|
method.
|
|
This can allow you to
|
|
perform more complicated
|
|
sequences of file manipulation
|
|
without relying
|
|
on platform-specific
|
|
external commands:
|
|
that</p><pre class="literallayout">
|
|
env = Environment(TMPBUILD = '/tmp/builddir')
|
|
env.Command('foo.out', 'foo.in',
|
|
[Mkdir('$TMPBUILD'),
|
|
Copy('$TMPBUILD', '${SOURCE.dir}'),
|
|
"cd $TMPBUILD && make",
|
|
Delete('$TMPBUILD')])
|
|
</pre><div class="variablelist"><dl><dt><span class="term">Chmod(<span class="emphasis"><em>dest</em></span>, <span class="emphasis"><em>mode</em></span>)</span></dt><dd><p>Returns an Action object that
|
|
changes the permissions on the specified
|
|
<span class="emphasis"><em>dest</em></span>
|
|
file or directory to the specified
|
|
<span class="emphasis"><em>mode</em></span>
|
|
which can be octal or string, similar to the bash command.
|
|
Examples:</p><pre class="literallayout">
|
|
Execute(Chmod('file', 0755))
|
|
|
|
env.Command('foo.out', 'foo.in',
|
|
[Copy('$TARGET', '$SOURCE'),
|
|
Chmod('$TARGET', 0755)])
|
|
|
|
Execute(Chmod('file', "ugo+w"))
|
|
|
|
env.Command('foo.out', 'foo.in',
|
|
[Copy('$TARGET', '$SOURCE'),
|
|
Chmod('$TARGET', "ugo+w")])
|
|
</pre></dd><dt><span class="term">Copy(<span class="emphasis"><em>dest</em></span>, <span class="emphasis"><em>src</em></span>)</span></dt><dd><p>Returns an Action object
|
|
that will copy the
|
|
<span class="emphasis"><em>src</em></span>
|
|
source file or directory to the
|
|
<span class="emphasis"><em>dest</em></span>
|
|
destination file or directory.
|
|
Examples:</p><pre class="literallayout">
|
|
Execute(Copy('foo.output', 'foo.input'))
|
|
|
|
env.Command('bar.out', 'bar.in',
|
|
Copy('$TARGET', '$SOURCE'))
|
|
</pre></dd><dt><span class="term">Delete(<span class="emphasis"><em>entry</em></span>, [<span class="emphasis"><em>must_exist</em></span>])</span></dt><dd><p>Returns an Action that
|
|
deletes the specified
|
|
<span class="emphasis"><em>entry</em></span>,
|
|
which may be a file or a directory tree.
|
|
If a directory is specified,
|
|
the entire directory tree
|
|
will be removed.
|
|
If the
|
|
<span class="emphasis"><em>must_exist</em></span>
|
|
flag is set,
|
|
then a Python error will be thrown
|
|
if the specified entry does not exist;
|
|
the default is
|
|
<span class="bold"><strong>must_exist=0</strong></span>,
|
|
that is, the Action will silently do nothing
|
|
if the entry does not exist.
|
|
Examples:</p><pre class="literallayout">
|
|
Execute(Delete('/tmp/buildroot'))
|
|
|
|
env.Command('foo.out', 'foo.in',
|
|
[Delete('${TARGET.dir}'),
|
|
MyBuildAction])
|
|
|
|
Execute(Delete('file_that_must_exist', must_exist=1))
|
|
</pre></dd><dt><span class="term">Mkdir(<span class="emphasis"><em>dir</em></span>)</span></dt><dd><p>Returns an Action
|
|
that creates the specified
|
|
directory
|
|
<span class="emphasis"><em>dir .</em></span>
|
|
Examples:</p><pre class="literallayout">
|
|
Execute(Mkdir('/tmp/outputdir'))
|
|
|
|
env.Command('foo.out', 'foo.in',
|
|
[Mkdir('/tmp/builddir'),
|
|
Copy('/tmp/builddir/foo.in', '$SOURCE'),
|
|
"cd /tmp/builddir && make",
|
|
Copy('$TARGET', '/tmp/builddir/foo.out')])
|
|
</pre></dd><dt><span class="term">Move(<span class="emphasis"><em>dest</em></span>, <span class="emphasis"><em>src</em></span>)</span></dt><dd><p>Returns an Action
|
|
that moves the specified
|
|
<span class="emphasis"><em>src</em></span>
|
|
file or directory to
|
|
the specified
|
|
<span class="emphasis"><em>dest</em></span>
|
|
file or directory.
|
|
Examples:</p><pre class="literallayout">
|
|
Execute(Move('file.destination', 'file.source'))
|
|
|
|
env.Command('output_file', 'input_file',
|
|
[MyBuildAction,
|
|
Move('$TARGET', 'file_created_by_MyBuildAction')])
|
|
</pre></dd><dt><span class="term">Touch(<span class="emphasis"><em>file</em></span>)</span></dt><dd><p>Returns an Action
|
|
that updates the modification time
|
|
on the specified
|
|
<span class="emphasis"><em>file</em></span>.
|
|
Examples:</p><pre class="literallayout">
|
|
Execute(Touch('file_to_be_touched'))
|
|
|
|
env.Command('marker', 'input_file',
|
|
[MyBuildAction,
|
|
Touch('$TARGET')])
|
|
</pre></dd></dl></div></div><div class="refsect2" title="Variable Substitution"><a name="variable_substitution"></a><h3>Variable Substitution</h3><p>Before executing a command,
|
|
<span class="command"><strong>scons</strong></span>
|
|
performs construction variable interpolation on the strings that make up
|
|
the command line of builders.
|
|
Variables are introduced by a
|
|
<span class="bold"><strong>$</strong></span>
|
|
prefix.
|
|
Besides construction variables, scons provides the following
|
|
variables for each command execution:</p><div class="variablelist"><dl><dt><span class="term">CHANGED_SOURCES</span></dt><dd><p>The file names of all sources of the build command
|
|
that have changed since the target was last built.</p></dd><dt><span class="term">CHANGED_TARGETS</span></dt><dd><p>The file names of all targets that would be built
|
|
from sources that have changed since the target was last built.</p></dd><dt><span class="term">SOURCE</span></dt><dd><p>The file name of the source of the build command,
|
|
or the file name of the first source
|
|
if multiple sources are being built.</p></dd><dt><span class="term">SOURCES</span></dt><dd><p>The file names of the sources of the build command.</p></dd><dt><span class="term">TARGET</span></dt><dd><p>The file name of the target being built,
|
|
or the file name of the first target
|
|
if multiple targets are being built.</p></dd><dt><span class="term">TARGETS</span></dt><dd><p>The file names of all targets being built.</p></dd><dt><span class="term">UNCHANGED_SOURCES</span></dt><dd><p>The file names of all sources of the build command
|
|
that have
|
|
<span class="emphasis"><em>not</em></span>
|
|
changed since the target was last built.</p></dd><dt><span class="term">UNCHANGED_TARGETS</span></dt><dd><p>The file names of all targets that would be built
|
|
from sources that have
|
|
<span class="emphasis"><em>not</em></span>
|
|
changed since the target was last built.</p><p>(Note that the above variables are reserved
|
|
and may not be set in a construction environment.)</p></dd></dl></div><p>For example, given the construction variable CC='cc', targets=['foo'], and
|
|
sources=['foo.c', 'bar.c']:</p><pre class="literallayout">
|
|
action='$CC -c -o $TARGET $SOURCES'
|
|
</pre><p>would produce the command line:</p><pre class="literallayout">
|
|
cc -c -o foo foo.c bar.c
|
|
</pre><p>Variable names may be surrounded by curly braces ({})
|
|
to separate the name from the trailing characters.
|
|
Within the curly braces, a variable name may have
|
|
a Python slice subscript appended to select one
|
|
or more items from a list.
|
|
In the previous example, the string:</p><pre class="literallayout">
|
|
${SOURCES[1]}
|
|
</pre><p>would produce:</p><pre class="literallayout">
|
|
bar.c
|
|
</pre><p>Additionally, a variable name may
|
|
have the following special
|
|
modifiers appended within the enclosing curly braces
|
|
to modify the interpolated string:</p><div class="variablelist"><dl><dt><span class="term">base</span></dt><dd><p>The base path of the file name,
|
|
including the directory path
|
|
but excluding any suffix.</p></dd><dt><span class="term">dir</span></dt><dd><p>The name of the directory in which the file exists.</p></dd><dt><span class="term">file</span></dt><dd><p>The file name,
|
|
minus any directory portion.</p></dd><dt><span class="term">filebase</span></dt><dd><p>Just the basename of the file,
|
|
minus any suffix
|
|
and minus the directory.</p></dd><dt><span class="term">suffix</span></dt><dd><p>Just the file suffix.</p></dd><dt><span class="term">abspath</span></dt><dd><p>The absolute path name of the file.</p></dd><dt><span class="term">posix</span></dt><dd><p>The POSIX form of the path,
|
|
with directories separated by
|
|
<span class="bold"><strong>/</strong></span>
|
|
(forward slashes)
|
|
not backslashes.
|
|
This is sometimes necessary on Windows systems
|
|
when a path references a file on other (POSIX) systems.</p></dd><dt><span class="term">srcpath</span></dt><dd><p>The directory and file name to the source file linked to this file through
|
|
<span class="bold"><strong>VariantDir</strong></span>().
|
|
If this file isn't linked,
|
|
it just returns the directory and filename unchanged.</p></dd><dt><span class="term">srcdir</span></dt><dd><p>The directory containing the source file linked to this file through
|
|
<span class="bold"><strong>VariantDir</strong></span>().
|
|
If this file isn't linked,
|
|
it just returns the directory part of the filename.</p></dd><dt><span class="term">rsrcpath</span></dt><dd><p>The directory and file name to the source file linked to this file through
|
|
<span class="bold"><strong>VariantDir</strong></span>().
|
|
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.</p></dd><dt><span class="term">rsrcdir</span></dt><dd><p>The Repository directory containing the source file linked to this file through
|
|
<span class="bold"><strong>VariantDir</strong></span>().
|
|
If this file isn't linked,
|
|
it just returns the directory part of the filename.</p></dd></dl></div><p>For example, the specified target will
|
|
expand as follows for the corresponding modifiers:</p><pre class="literallayout">
|
|
$TARGET => sub/dir/file.x
|
|
${TARGET.base} => sub/dir/file
|
|
${TARGET.dir} => sub/dir
|
|
${TARGET.file} => file.x
|
|
${TARGET.filebase} => file
|
|
${TARGET.suffix} => .x
|
|
${TARGET.abspath} => /top/dir/sub/dir/file.x
|
|
|
|
SConscript('src/SConscript', variant_dir='sub/dir')
|
|
$SOURCE => sub/dir/file.x
|
|
${SOURCE.srcpath} => src/file.x
|
|
${SOURCE.srcdir} => src
|
|
|
|
Repository('/usr/repository')
|
|
$SOURCE => sub/dir/file.x
|
|
${SOURCE.rsrcpath} => /usr/repository/src/file.x
|
|
${SOURCE.rsrcdir} => /usr/repository/src
|
|
</pre><p>Note that curly braces braces may also be used
|
|
to enclose arbitrary Python code to be evaluated.
|
|
(In fact, this is how the above modifiers are substituted,
|
|
they are simply attributes of the Python objects
|
|
that represent TARGET, SOURCES, etc.)
|
|
See the section "Python Code Substitution" below,
|
|
for more thorough examples of
|
|
how this can be used.</p><p>Lastly, a variable name
|
|
may be a callable Python function
|
|
associated with a
|
|
construction variable in the environment.
|
|
The function should
|
|
take four arguments:
|
|
<span class="emphasis"><em>target</em></span>
|
|
- a list of target nodes,
|
|
<span class="emphasis"><em>source</em></span>
|
|
- a list of source nodes,
|
|
<span class="emphasis"><em>env</em></span>
|
|
- the construction environment,
|
|
<span class="emphasis"><em>for_signature</em></span>
|
|
- a Boolean value that specifies
|
|
whether the function is being called
|
|
for generating a build signature.
|
|
SCons will insert whatever
|
|
the called function returns
|
|
into the expanded string:</p><pre class="programlisting">
|
|
def foo(target, source, env, for_signature):
|
|
return "bar"
|
|
|
|
# Will expand $BAR to "bar baz"
|
|
env=Environment(FOO=foo, BAR="$FOO baz")
|
|
</pre><p>You can use this feature to pass arguments to a
|
|
Python function by creating a callable class
|
|
that stores one or more arguments in an object,
|
|
and then uses them when the
|
|
<code class="function">__call__()</code>
|
|
method is called.
|
|
Note that in this case,
|
|
the entire variable expansion must
|
|
be enclosed by curly braces
|
|
so that the arguments will
|
|
be associated with the
|
|
instantiation of the class:</p><pre class="literallayout">
|
|
class foo(object):
|
|
def __init__(self, arg):
|
|
self.arg = arg
|
|
|
|
def __call__(self, target, source, env, for_signature):
|
|
return self.arg + " bar"
|
|
|
|
# Will expand $BAR to "my argument bar baz"
|
|
env=Environment(FOO=foo, BAR="${FOO('my argument')} baz")
|
|
</pre><p>The special pseudo-variables
|
|
<span class="bold"><strong>$(</strong></span>
|
|
and
|
|
<span class="bold"><strong>$)</strong></span>
|
|
may be used to surround parts of a command line
|
|
that may change
|
|
<span class="emphasis"><em>without</em></span>
|
|
causing a rebuild--that is,
|
|
which are not included in the signature
|
|
of target files built with this command.
|
|
All text between
|
|
<span class="bold"><strong>$(</strong></span>
|
|
and
|
|
<span class="bold"><strong>$)</strong></span>
|
|
will be removed from the command line
|
|
before it is added to file signatures,
|
|
and the
|
|
<span class="bold"><strong>$(</strong></span>
|
|
and
|
|
<span class="bold"><strong>$)</strong></span>
|
|
will be removed before the command is executed.
|
|
For example, the command line:</p><pre class="literallayout">
|
|
echo Last build occurred $( $TODAY $). > $TARGET
|
|
</pre><p>would execute the command:</p><pre class="literallayout">
|
|
echo Last build occurred $TODAY. > $TARGET
|
|
</pre><p>but the command signature added to any target files would be:</p><pre class="literallayout">
|
|
echo Last build occurred . > $TARGET
|
|
</pre></div><div class="refsect2" title="Python Code Substitution"><a name="python_code_substitution"></a><h3>Python Code Substitution</h3><p>Any python code within
|
|
<span class="bold"><strong>${</strong></span>-<span class="bold"><strong>}</strong></span>
|
|
pairs gets evaluated by python 'eval', with the python globals set to
|
|
the current environment's set of construction variables.
|
|
So in the following case:</p><pre class="literallayout">
|
|
env['COND'] = 0
|
|
env.Command('foo.out', 'foo.in',
|
|
'''echo ${COND==1 and 'FOO' or 'BAR'} > $TARGET''')
|
|
</pre><p>the command executed will be either</p><pre class="literallayout">
|
|
echo FOO > foo.out
|
|
</pre><p>or</p><pre class="literallayout">
|
|
echo BAR > foo.out
|
|
</pre><p>according to the current value of env['COND'] when the command is
|
|
executed. The evaluation occurs when the target is being
|
|
built, not when the SConscript is being read. So if env['COND'] is changed
|
|
later in the SConscript, the final value will be used.</p><p>Here's a more interesting example. Note that all of COND, FOO, and
|
|
BAR are environment variables, and their values are substituted into
|
|
the final command. FOO is a list, so its elements are interpolated
|
|
separated by spaces.</p><pre class="literallayout">
|
|
env=Environment()
|
|
env['COND'] = 0
|
|
env['FOO'] = ['foo1', 'foo2']
|
|
env['BAR'] = 'barbar'
|
|
env.Command('foo.out', 'foo.in',
|
|
'echo ${COND==1 and FOO or BAR} > $TARGET')
|
|
|
|
# Will execute this:
|
|
# echo foo1 foo2 > foo.out
|
|
</pre><p>SCons uses the following rules when converting construction variables into
|
|
command lines:</p><div class="variablelist"><dl><dt><span class="term">String</span></dt><dd><p>When the value is a string it is interpreted as a space delimited list of
|
|
command line arguments.</p></dd><dt><span class="term">List</span></dt><dd><p>When the value is a list it is interpreted as a list of command line
|
|
arguments. Each element of the list is converted to a string.</p></dd><dt><span class="term">Other</span></dt><dd><p>Anything that is not a list or string is converted to a string and
|
|
interpreted as a single command line argument.</p></dd><dt><span class="term">Newline</span></dt><dd><p>Newline characters (\n) delimit lines. The newline parsing is done after
|
|
all other parsing, so it is not possible for arguments (e.g. file names) to
|
|
contain embedded newline characters. This limitation will likely go away in
|
|
a future version of SCons.</p></dd></dl></div></div><div class="refsect2" title="Scanner Objects"><a name="scanner_objects"></a><h3>Scanner Objects</h3><p>You can use the
|
|
<span class="bold"><strong>Scanner</strong></span>
|
|
function to define
|
|
objects to scan
|
|
new file types for implicit dependencies.
|
|
The
|
|
<span class="bold"><strong>Scanner</strong></span>
|
|
function accepts the following arguments:</p><div class="variablelist"><dl><dt><span class="term">function</span></dt><dd><p>This can be either:
|
|
1) a Python function that will process
|
|
the Node (file)
|
|
and return a list of File Nodes
|
|
representing the implicit
|
|
dependencies (file names) found in the contents;
|
|
or:
|
|
2) a dictionary that maps keys
|
|
(typically the file suffix, but see below for more discussion)
|
|
to other Scanners that should be called.</p><p>If the argument is actually a Python function,
|
|
the function must take three or four arguments:</p><p> def scanner_function(node, env, path):</p><p> def scanner_function(node, env, path, arg=None):</p><p>The
|
|
<span class="bold"><strong>node</strong></span>
|
|
argument is the internal
|
|
SCons node representing the file.
|
|
Use
|
|
<span class="bold"><strong>str(node)</strong></span>
|
|
to fetch the name of the file, and
|
|
<span class="bold"><strong>node.get_contents()</strong></span>
|
|
to fetch contents of the file.
|
|
Note that the file is
|
|
<span class="emphasis"><em>not</em></span>
|
|
guaranteed to exist before the scanner is called,
|
|
so the scanner function should check that
|
|
if there's any chance that the scanned file
|
|
might not exist
|
|
(for example, if it's built from other files).</p><p>The
|
|
<span class="bold"><strong>env</strong></span>
|
|
argument is the construction environment for the scan.
|
|
Fetch values from it using the
|
|
<span class="bold"><strong>env.Dictionary()</strong></span>
|
|
method.</p><p>The
|
|
<span class="bold"><strong>path</strong></span>
|
|
argument is a tuple (or list)
|
|
of directories that can be searched
|
|
for files.
|
|
This will usually be the tuple returned by the
|
|
<span class="bold"><strong>path_function</strong></span>
|
|
argument (see below).</p><p>The
|
|
<span class="bold"><strong>arg</strong></span>
|
|
argument is the argument supplied
|
|
when the scanner was created, if any.</p></dd><dt><span class="term">name</span></dt><dd><p>The name of the Scanner.
|
|
This is mainly used
|
|
to identify the Scanner internally.</p></dd><dt><span class="term">argument</span></dt><dd><p>An optional argument that, if specified,
|
|
will be passed to the scanner function
|
|
(described above)
|
|
and the path function
|
|
(specified below).</p></dd><dt><span class="term">skeys</span></dt><dd><p>An optional list that can be used to
|
|
determine which scanner should be used for
|
|
a given Node.
|
|
In the usual case of scanning for file names,
|
|
this argument will be a list of suffixes
|
|
for the different file types that this
|
|
Scanner knows how to scan.
|
|
If the argument is a string,
|
|
then it will be expanded
|
|
into a list by the current environment.</p></dd><dt><span class="term">path_function</span></dt><dd><p>A Python function that takes four or five arguments:
|
|
a construction environment,
|
|
a Node for the directory containing
|
|
the SConscript file in which
|
|
the first target was defined,
|
|
a list of target nodes,
|
|
a list of source nodes,
|
|
and an optional argument supplied
|
|
when the scanner was created.
|
|
The
|
|
<span class="bold"><strong>path_function</strong></span>
|
|
returns a tuple of directories
|
|
that can be searched for files to be returned
|
|
by this Scanner object.
|
|
(Note that the
|
|
<span class="bold"><strong>FindPathDirs</strong></span>()
|
|
function can be used to return a ready-made
|
|
<span class="bold"><strong>path_function</strong></span>
|
|
for a given construction variable name,
|
|
instead of having to write your own function from scratch.)</p></dd><dt><span class="term">node_class</span></dt><dd><p>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
|
|
<span class="bold"><strong>node_factory</strong></span>
|
|
function.</p></dd><dt><span class="term">node_factory</span></dt><dd><p>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.</p></dd><dt><span class="term">scan_check</span></dt><dd><p>An optional Python function that takes two arguments,
|
|
a Node (file) and a construction environment,
|
|
and returns whether the
|
|
Node should, in fact,
|
|
be scanned for dependencies.
|
|
This check can be used to eliminate unnecessary
|
|
calls to the scanner function when,
|
|
for example, the underlying file
|
|
represented by a Node does not yet exist.</p></dd><dt><span class="term">recursive</span></dt><dd><p>An optional flag that
|
|
specifies whether this scanner should be re-invoked
|
|
on the dependency files returned by the scanner.
|
|
When this flag is not set,
|
|
the Node subsystem will
|
|
only invoke the scanner on the file being scanned,
|
|
and not (for example) also on the files
|
|
specified by the #include lines
|
|
in the file being scanned.
|
|
<span class="emphasis"><em>recursive</em></span>
|
|
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.</p></dd></dl></div><p>Note that
|
|
<span class="command"><strong>scons</strong></span>
|
|
has a global
|
|
<span class="bold"><strong>SourceFileScanner</strong></span>
|
|
object that is used by
|
|
the
|
|
<span class="bold"><strong>Object</strong></span>(),
|
|
<span class="bold"><strong>SharedObject</strong></span>(),
|
|
and
|
|
<span class="bold"><strong>StaticObject</strong></span>()
|
|
builders to decide
|
|
which scanner should be used
|
|
for different file extensions.
|
|
You can using the
|
|
<span class="bold"><strong>SourceFileScanner.add_scanner</strong></span>()
|
|
method to add your own Scanner object
|
|
to the
|
|
<span class="command"><strong>scons</strong></span>
|
|
infrastructure
|
|
that builds target programs or
|
|
libraries from a list of
|
|
source files of different types:</p><pre class="programlisting">
|
|
def xyz_scan(node, env, path):
|
|
contents = node.get_text_contents()
|
|
# Scan the contents and return the included files.
|
|
|
|
XYZScanner = Scanner(xyz_scan)
|
|
|
|
SourceFileScanner.add_scanner('.xyz', XYZScanner)
|
|
|
|
env.Program('my_prog', ['file1.c', 'file2.f', 'file3.xyz'])
|
|
</pre></div></div><div class="refsect1" title="SYSTEM-SPECIFIC BEHAVIOR"><a name="systemspecific_behavior"></a><h2>SYSTEM-SPECIFIC BEHAVIOR</h2><p>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.</p><div class="refsect2" title=".C file suffix"><a name="c_file_suffix"></a><h3>.C file suffix</h3><p>SCons handles the upper-case
|
|
<span class="markup">.C</span>
|
|
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
|
|
<span class="markup">.C</span>
|
|
suffix as a C++ source file.
|
|
On a case-insensitive system
|
|
such as Windows,
|
|
SCons treats a file with a
|
|
<span class="markup">.C</span>
|
|
suffix as a C source file.</p></div><div class="refsect2" title=".F file suffix"><a name="f_file_suffix"></a><h3>.F file suffix</h3><p>SCons handles the upper-case
|
|
<span class="markup">.F</span>
|
|
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
|
|
<span class="markup">.F</span>
|
|
suffix as a Fortran source file
|
|
that is to be first run through
|
|
the standard C preprocessor.
|
|
On a case-insensitive system
|
|
such as Windows,
|
|
SCons treats a file with a
|
|
<span class="markup">.F</span>
|
|
suffix as a Fortran source file that should
|
|
<span class="emphasis"><em>not</em></span>
|
|
be run through the C preprocessor.</p></div><div class="refsect2" title="Windows: Cygwin Tools and Cygwin Python vs. Windows Pythons"><a name="windows_cygwin_tools_and_cygwin_python_v"></a><h3>Windows: Cygwin Tools and Cygwin Python vs. Windows Pythons</h3><p>Cygwin supplies a set of tools and utilities
|
|
that let users work on a
|
|
Windows system using a more POSIX-like environment.
|
|
The Cygwin tools, including Cygwin Python,
|
|
do this, in part,
|
|
by sharing an ability to interpret UNIX-like path names.
|
|
For example, the Cygwin tools
|
|
will internally translate a Cygwin path name
|
|
like /cygdrive/c/mydir
|
|
to an equivalent Windows pathname
|
|
of C:/mydir (equivalent to C:\mydir).</p><p>Versions of Python
|
|
that are built for native Windows execution,
|
|
such as the python.org and ActiveState versions,
|
|
do not have the Cygwin path name semantics.
|
|
This means that using a native Windows version of Python
|
|
to build compiled programs using Cygwin tools
|
|
(such as gcc, bison, and flex)
|
|
may yield unpredictable results.
|
|
"Mixing and matching" in this way
|
|
can be made to work,
|
|
but it requires careful attention to the use of path names
|
|
in your SConscript files.</p><p>In practice, users can sidestep
|
|
the issue by adopting the following rules:
|
|
When using gcc,
|
|
use the Cygwin-supplied Python interpreter
|
|
to run SCons;
|
|
when using Microsoft Visual C/C++
|
|
(or some other Windows compiler)
|
|
use the python.org or ActiveState version of Python
|
|
to run SCons.</p></div><div class="refsect2" title="Windows: scons.bat file"><a name="windows_sconsbat_file"></a><h3>Windows: scons.bat file</h3><p>On Windows systems,
|
|
SCons is executed via a wrapper
|
|
<span class="bold"><strong>scons.bat</strong></span>
|
|
file.
|
|
This has (at least) two ramifications:</p><p>First, Windows command-line users
|
|
that want to use variable assignment
|
|
on the command line
|
|
may have to put double quotes
|
|
around the assignments:</p><pre class="literallayout">
|
|
scons "FOO=BAR" "BAZ=BLEH"
|
|
</pre><p>Second, the Cygwin shell does not
|
|
recognize this file as being the same
|
|
as an
|
|
<span class="command"><strong>scons</strong></span>
|
|
command issued at the command-line prompt.
|
|
You can work around this either by
|
|
executing
|
|
<span class="bold"><strong>scons.bat</strong></span>
|
|
from the Cygwin command line,
|
|
or by creating a wrapper shell
|
|
script named
|
|
<span class="bold"><strong>scons .</strong></span></p></div><div class="refsect2" title="MinGW"><a name="mingw"></a><h3>MinGW</h3><p>The MinGW bin directory must be in your PATH environment variable or the
|
|
PATH variable under the ENV construction variable for SCons
|
|
to detect and use the MinGW tools. When running under the native Windows
|
|
Python interpreter, SCons will prefer the MinGW tools over the Cygwin
|
|
tools, if they are both installed, regardless of the order of the bin
|
|
directories in the PATH variable. If you have both MSVC and MinGW
|
|
installed and you want to use MinGW instead of MSVC,
|
|
then you must explicitly tell SCons to use MinGW by passing</p><pre class="literallayout">
|
|
tools=['mingw']
|
|
</pre><p>to the Environment() function, because SCons will prefer the MSVC tools
|
|
over the MinGW tools.</p></div></div><div class="refsect1" title="EXAMPLES"><a name="examples"></a><h2>EXAMPLES</h2><p>To help you get started using SCons,
|
|
this section contains a brief overview of some common tasks.</p><div class="refsect2" title="Basic Compilation From a Single Source File"><a name="basic_compilation_from_a_single_source_f"></a><h3>Basic Compilation From a Single Source File</h3><pre class="literallayout">
|
|
env = Environment()
|
|
env.Program(target = 'foo', source = 'foo.c')
|
|
</pre><p>Note: Build the file by specifying
|
|
the target as an argument
|
|
("scons foo" or "scons foo.exe").
|
|
or by specifying a dot ("scons .").</p></div><div class="refsect2" title="Basic Compilation From Multiple Source Files"><a name="basic_compilation_from_multiple_source_f"></a><h3>Basic Compilation From Multiple Source Files</h3><pre class="literallayout">
|
|
env = Environment()
|
|
env.Program(target = 'foo', source = Split('f1.c f2.c f3.c'))
|
|
</pre></div><div class="refsect2" title="Setting a Compilation Flag"><a name="setting_a_compilation_flag"></a><h3>Setting a Compilation Flag</h3><pre class="literallayout">
|
|
env = Environment(CCFLAGS = '-g')
|
|
env.Program(target = 'foo', source = 'foo.c')
|
|
</pre></div><div class="refsect2" title="Search The Local Directory For .h Files"><a name="search_the_local_directory_for_h_files"></a><h3>Search The Local Directory For .h Files</h3><p>Note: You do
|
|
<span class="emphasis"><em>not</em></span>
|
|
need to set CCFLAGS to specify -I options by hand.
|
|
SCons will construct the right -I options from CPPPATH.</p><pre class="literallayout">
|
|
env = Environment(CPPPATH = ['.'])
|
|
env.Program(target = 'foo', source = 'foo.c')
|
|
</pre></div><div class="refsect2" title="Search Multiple Directories For .h Files"><a name="search_multiple_directories_for_h_files"></a><h3>Search Multiple Directories For .h Files</h3><pre class="literallayout">
|
|
env = Environment(CPPPATH = ['include1', 'include2'])
|
|
env.Program(target = 'foo', source = 'foo.c')
|
|
</pre></div><div class="refsect2" title="Building a Static Library"><a name="building_a_static_library"></a><h3>Building a Static Library</h3><pre class="literallayout">
|
|
env = Environment()
|
|
env.StaticLibrary(target = 'foo', source = Split('l1.c l2.c'))
|
|
env.StaticLibrary(target = 'bar', source = ['l3.c', 'l4.c'])
|
|
</pre></div><div class="refsect2" title="Building a Shared Library"><a name="building_a_shared_library"></a><h3>Building a Shared Library</h3><pre class="literallayout">
|
|
env = Environment()
|
|
env.SharedLibrary(target = 'foo', source = ['l5.c', 'l6.c'])
|
|
env.SharedLibrary(target = 'bar', source = Split('l7.c l8.c'))
|
|
</pre></div><div class="refsect2" title="Linking a Local Library Into a Program"><a name="linking_a_local_library_into_a_program"></a><h3>Linking a Local Library Into a Program</h3><pre class="literallayout">
|
|
env = Environment(LIBS = 'mylib', LIBPATH = ['.'])
|
|
env.Library(target = 'mylib', source = Split('l1.c l2.c'))
|
|
env.Program(target = 'prog', source = ['p1.c', 'p2.c'])
|
|
</pre></div><div class="refsect2" title="Defining Your Own Builder Object"><a name="defining_your_own_builder_object"></a><h3>Defining Your Own Builder Object</h3><p>Notice that when you invoke the Builder,
|
|
you can leave off the target file suffix,
|
|
and SCons will add it automatically.</p><pre class="literallayout">
|
|
bld = Builder(action = 'pdftex < $SOURCES > $TARGET'
|
|
suffix = '.pdf',
|
|
src_suffix = '.tex')
|
|
env = Environment(BUILDERS = {'PDFBuilder' : bld})
|
|
env.PDFBuilder(target = 'foo.pdf', source = 'foo.tex')
|
|
|
|
# The following creates "bar.pdf" from "bar.tex"
|
|
env.PDFBuilder(target = 'bar', source = 'bar')
|
|
</pre><p>Note also that the above initialization
|
|
overwrites the default Builder objects,
|
|
so the Environment created above
|
|
can not be used call Builders like env.Program(),
|
|
env.Object(), env.StaticLibrary(), etc.</p></div><div class="refsect2" title="Adding Your Own Builder Object to an Environment"><a name="adding_your_own_builder_object_to_an_env"></a><h3>Adding Your Own Builder Object to an Environment</h3><pre class="literallayout">
|
|
bld = Builder(action = 'pdftex < $SOURCES > $TARGET'
|
|
suffix = '.pdf',
|
|
src_suffix = '.tex')
|
|
env = Environment()
|
|
env.Append(BUILDERS = {'PDFBuilder' : bld})
|
|
env.PDFBuilder(target = 'foo.pdf', source = 'foo.tex')
|
|
env.Program(target = 'bar', source = 'bar.c')
|
|
</pre><p>You also can use other Pythonic techniques to add
|
|
to the BUILDERS construction variable, such as:</p><pre class="literallayout">
|
|
env = Environment()
|
|
env['BUILDERS]['PDFBuilder'] = bld
|
|
</pre></div><div class="refsect2" title="Defining Your Own Scanner Object"><a name="defining_your_own_scanner_object"></a><h3>Defining Your Own Scanner Object</h3><p>The following example shows an extremely simple scanner (the
|
|
<span class="bold"><strong>kfile_scan</strong></span>()
|
|
function)
|
|
that doesn't use a search path at all
|
|
and simply returns the
|
|
file names present on any
|
|
<span class="bold"><strong>include</strong></span>
|
|
lines in the scanned file.
|
|
This would implicitly assume that all included
|
|
files live in the top-level directory:</p><pre class="literallayout">
|
|
import re
|
|
|
|
include_re = re.compile(r'^include\s+(\S+)$', re.M)
|
|
|
|
def kfile_scan(node, env, path, arg):
|
|
contents = node.get_text_contents()
|
|
includes = include_re.findall(contents)
|
|
return env.File(includes)
|
|
|
|
kscan = Scanner(name = 'kfile',
|
|
function = kfile_scan,
|
|
argument = None,
|
|
skeys = ['.k'])
|
|
scanners = Environment().Dictionary('SCANNERS')
|
|
env = Environment(SCANNERS = scanners + [kscan])
|
|
|
|
env.Command('foo', 'foo.k', 'kprocess < $SOURCES > $TARGET')
|
|
|
|
bar_in = File('bar.in')
|
|
env.Command('bar', bar_in, 'kprocess $SOURCES > $TARGET')
|
|
bar_in.target_scanner = kscan
|
|
</pre><p>It is important to note that you
|
|
have to return a list of File nodes from the scan function, simple
|
|
strings for the file names won't do. As in the examples we are showing here,
|
|
you can use the
|
|
<span class="bold"><strong>File()</strong></span>
|
|
function of your current Environment in order to create nodes on the fly from
|
|
a sequence of file names with relative paths.</p><p>Here is a similar but more complete example that searches
|
|
a path of directories
|
|
(specified as the
|
|
<span class="bold"><strong>MYPATH</strong></span>
|
|
construction variable)
|
|
for files that actually exist:</p><pre class="programlisting">
|
|
import re
|
|
import os
|
|
include_re = re.compile(r'^include\s+(\S+)$', re.M)
|
|
|
|
def my_scan(node, env, path, arg):
|
|
contents = node.get_text_contents()
|
|
includes = include_re.findall(contents)
|
|
if includes == []:
|
|
return []
|
|
results = []
|
|
for inc in includes:
|
|
for dir in path:
|
|
file = str(dir) + os.sep + inc
|
|
if os.path.exists(file):
|
|
results.append(file)
|
|
break
|
|
return env.File(results)
|
|
|
|
scanner = Scanner(name = 'myscanner',
|
|
function = my_scan,
|
|
argument = None,
|
|
skeys = ['.x'],
|
|
path_function = FindPathDirs('MYPATH')
|
|
)
|
|
scanners = Environment().Dictionary('SCANNERS')
|
|
env = Environment(SCANNERS = scanners + [scanner],
|
|
MYPATH = ['incs'])
|
|
|
|
env.Command('foo', 'foo.x', 'xprocess < $SOURCES > $TARGET')
|
|
</pre><p>The
|
|
<span class="bold"><strong>FindPathDirs</strong></span>()
|
|
function used in the previous example returns a function
|
|
(actually a callable Python object)
|
|
that will return a list of directories
|
|
specified in the
|
|
<span class="bold"><strong>$MYPATH</strong></span>
|
|
construction variable. It lets SCons detect the file
|
|
<span class="bold"><strong>incs/foo.inc</strong></span>
|
|
, even if
|
|
<span class="bold"><strong>foo.x</strong></span>
|
|
contains the line
|
|
<span class="bold"><strong>include foo.inc</strong></span>
|
|
only.
|
|
If you need to customize how the search path is derived,
|
|
you would provide your own
|
|
<span class="bold"><strong>path_function</strong></span>
|
|
argument when creating the Scanner object,
|
|
as follows:</p><pre class="programlisting">
|
|
# MYPATH is a list of directories to search for files in
|
|
def pf(env, dir, target, source, arg):
|
|
top_dir = Dir('#').abspath
|
|
results = []
|
|
if 'MYPATH' in env:
|
|
for p in env['MYPATH']:
|
|
results.append(top_dir + os.sep + p)
|
|
return results
|
|
|
|
scanner = Scanner(name = 'myscanner',
|
|
function = my_scan,
|
|
argument = None,
|
|
skeys = ['.x'],
|
|
path_function = pf
|
|
)
|
|
</pre></div><div class="refsect2" title="Creating a Hierarchical Build"><a name="creating_a_hierarchical_build"></a><h3>Creating a Hierarchical Build</h3><p>Notice that the file names specified in a subdirectory's
|
|
SConscript
|
|
file are relative to that subdirectory.</p><pre class="programlisting">
|
|
SConstruct:
|
|
|
|
env = Environment()
|
|
env.Program(target = 'foo', source = 'foo.c')
|
|
|
|
SConscript('sub/SConscript')
|
|
|
|
sub/SConscript:
|
|
|
|
env = Environment()
|
|
# Builds sub/foo from sub/foo.c
|
|
env.Program(target = 'foo', source = 'foo.c')
|
|
|
|
SConscript('dir/SConscript')
|
|
|
|
sub/dir/SConscript:
|
|
|
|
env = Environment()
|
|
# Builds sub/dir/foo from sub/dir/foo.c
|
|
env.Program(target = 'foo', source = 'foo.c')
|
|
</pre></div><div class="refsect2" title="Sharing Variables Between SConscript Files"><a name="sharing_variables_between_sconscript_fil"></a><h3>Sharing Variables Between SConscript Files</h3><p>You must explicitly Export() and Import() variables that
|
|
you want to share between SConscript files.</p><pre class="programlisting">
|
|
SConstruct:
|
|
|
|
env = Environment()
|
|
env.Program(target = 'foo', source = 'foo.c')
|
|
|
|
Export("env")
|
|
SConscript('subdirectory/SConscript')
|
|
|
|
subdirectory/SConscript:
|
|
|
|
Import("env")
|
|
env.Program(target = 'foo', source = 'foo.c')
|
|
</pre></div><div class="refsect2" title="Building Multiple Variants From the Same Source"><a name="building_multiple_variants_from_the_same"></a><h3>Building Multiple Variants From the Same Source</h3><p>Use the variant_dir keyword argument to
|
|
the SConscript function to establish
|
|
one or more separate variant build directory trees
|
|
for a given source directory:</p><pre class="programlisting">
|
|
SConstruct:
|
|
|
|
cppdefines = ['FOO']
|
|
Export("cppdefines")
|
|
SConscript('src/SConscript', variant_dir='foo')
|
|
|
|
cppdefines = ['BAR']
|
|
Export("cppdefines")
|
|
SConscript('src/SConscript', variant_dir='bar')
|
|
|
|
src/SConscript:
|
|
|
|
Import("cppdefines")
|
|
env = Environment(CPPDEFINES = cppdefines)
|
|
env.Program(target = 'src', source = 'src.c')
|
|
</pre><p>Note the use of the Export() method
|
|
to set the "cppdefines" variable to a different
|
|
value each time we call the SConscript function.</p></div><div class="refsect2" title="Hierarchical Build of Two Libraries Linked With a Program"><a name="hierarchical_build_of_two_libraries_link"></a><h3>Hierarchical Build of Two Libraries Linked With a Program</h3><pre class="programlisting">
|
|
SConstruct:
|
|
|
|
env = Environment(LIBPATH = ['#libA', '#libB'])
|
|
Export('env')
|
|
SConscript('libA/SConscript')
|
|
SConscript('libB/SConscript')
|
|
SConscript('Main/SConscript')
|
|
|
|
libA/SConscript:
|
|
|
|
Import('env')
|
|
env.Library('a', Split('a1.c a2.c a3.c'))
|
|
|
|
libB/SConscript:
|
|
|
|
Import('env')
|
|
env.Library('b', Split('b1.c b2.c b3.c'))
|
|
|
|
Main/SConscript:
|
|
|
|
Import('env')
|
|
e = env.Copy(LIBS = ['a', 'b'])
|
|
e.Program('foo', Split('m1.c m2.c m3.c'))
|
|
</pre><p>The '#' in the LIBPATH directories specify that they're relative to the
|
|
top-level directory, so they don't turn into "Main/libA" when they're
|
|
used in Main/SConscript.</p><p>Specifying only 'a' and 'b' for the library names
|
|
allows SCons to append the appropriate library
|
|
prefix and suffix for the current platform
|
|
(for example, 'liba.a' on POSIX systems,
|
|
'a.lib' on Windows).</p></div><div class="refsect2" title="Customizing construction variables from the command line."><a name="customizing_construction_variables_from_"></a><h3>Customizing construction variables from the command line.</h3><p>The following would allow the C compiler to be specified on the command
|
|
line or in the file custom.py.</p><pre class="literallayout">
|
|
vars = Variables('custom.py')
|
|
vars.Add('CC', 'The C compiler.')
|
|
env = Environment(variables=vars)
|
|
Help(vars.GenerateHelpText(env))
|
|
</pre><p>The user could specify the C compiler on the command line:</p><pre class="literallayout">
|
|
scons "CC=my_cc"
|
|
</pre><p>or in the custom.py file:</p><pre class="literallayout">
|
|
CC = 'my_cc'
|
|
</pre><p>or get documentation on the options:</p><pre class="literallayout">
|
|
$ scons -h
|
|
|
|
CC: The C compiler.
|
|
default: None
|
|
actual: cc
|
|
|
|
</pre></div><div class="refsect2" title="Using Microsoft Visual C++ precompiled headers"><a name="using_microsoft_visual_c_precompiled_hea"></a><h3>Using Microsoft Visual C++ precompiled headers</h3><p>Since windows.h includes everything and the kitchen sink, it can take quite
|
|
some time to compile it over and over again for a bunch of object files, so
|
|
Microsoft provides a mechanism to compile a set of headers once and then
|
|
include the previously compiled headers in any object file. This
|
|
technology is called precompiled headers. The general recipe is to create a
|
|
file named "StdAfx.cpp" that includes a single header named "StdAfx.h", and
|
|
then include every header you want to precompile in "StdAfx.h", and finally
|
|
include "StdAfx.h" as the first header in all the source files you are
|
|
compiling to object files. For example:</p><p>StdAfx.h:</p><pre class="literallayout">
|
|
#include <windows.h>
|
|
#include <my_big_header.h>
|
|
</pre><p>StdAfx.cpp:</p><pre class="literallayout">
|
|
#include <StdAfx.h>
|
|
</pre><p>Foo.cpp:</p><pre class="literallayout">
|
|
#include <StdAfx.h>
|
|
|
|
/* do some stuff */
|
|
</pre><p>Bar.cpp:</p><pre class="literallayout">
|
|
#include <StdAfx.h>
|
|
|
|
/* do some other stuff */
|
|
</pre><p>SConstruct:</p><pre class="literallayout">
|
|
env=Environment()
|
|
env['PCHSTOP'] = 'StdAfx.h'
|
|
env['PCH'] = env.PCH('StdAfx.cpp')[0]
|
|
env.Program('MyApp', ['Foo.cpp', 'Bar.cpp'])
|
|
</pre><p>For more information see the document for the PCH builder, and the PCH and
|
|
PCHSTOP construction variables. To learn about the details of precompiled
|
|
headers consult the MSDN documentation for /Yc, /Yu, and /Yp.</p></div><div class="refsect2" title="Using Microsoft Visual C++ external debugging information"><a name="using_microsoft_visual_c_external_debugg"></a><h3>Using Microsoft Visual C++ external debugging information</h3><p>Since including debugging information in programs and shared libraries can
|
|
cause their size to increase significantly, Microsoft provides a mechanism
|
|
for including the debugging information in an external file called a PDB
|
|
file. SCons supports PDB files through the PDB construction
|
|
variable.</p><p>SConstruct:</p><pre class="literallayout">
|
|
env=Environment()
|
|
env['PDB'] = 'MyApp.pdb'
|
|
env.Program('MyApp', ['Foo.cpp', 'Bar.cpp'])
|
|
</pre><p>For more information see the document for the PDB construction variable.</p></div></div><div class="refsect1" title="ENVIRONMENT"><a name="environment"></a><h2>ENVIRONMENT</h2><div class="variablelist"><dl><dt><span class="term">SCONS_LIB_DIR</span></dt><dd><p>Specifies the directory that contains the SCons Python module directory
|
|
(e.g. /home/aroach/scons-src-0.01/src/engine).</p></dd><dt><span class="term">SCONSFLAGS</span></dt><dd><p>A string of options that will be used by scons in addition to those passed
|
|
on the command line.</p></dd></dl></div></div><div class="refsect1" title="SEE ALSO"><a name="see_also"></a><h2>SEE ALSO</h2><p><span class="command"><strong>scons</strong></span>
|
|
User Manual,
|
|
<span class="command"><strong>scons</strong></span>
|
|
Design Document,
|
|
<span class="command"><strong>scons</strong></span>
|
|
source code.</p></div><div class="refsect1" title="AUTHORS"><a name="authors"></a><h2>AUTHORS</h2><p>Originally: Steven Knight <knight@baldmt.com> and Anthony Roach <aroach@electriceyeball.com>
|
|
Since 2010: The SCons Development Team <scons-dev@scons.org>
|
|
</p></div></div></div></body></html>
|