scons/scons-user.html

21597 lines
1.1 MiB
HTML
Raw Normal View History

<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="book" 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">User Guide</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 <20> 2004 - 2019 The SCons Foundation</p></div><div><div class="legalnotice" title="Legal Notice"><a name="idm13"></a><div class="blockquote"><blockquote class="blockquote"><p>
SCons User's Guide Copyright (c) 2004-2019 Steven Knight
</p></blockquote></div></div></div><div><p class="pubdate">2004 - 2019</p></div></div><hr></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="preface"><a href="#chap-preface">Preface</a></span></dt><dd><dl><dt><span class="section"><a href="#idm33">1. <span class="application">SCons</span> Principles</a></span></dt><dt><span class="section"><a href="#idm58">2. A Caveat About This Guide's Completeness</a></span></dt><dt><span class="section"><a href="#idm66">3. Acknowledgements</a></span></dt><dt><span class="section"><a href="#idm87">4. Contact</a></span></dt></dl></dd><dt><span class="chapter"><a href="#chap-build-install">1. Building and Installing <span class="application">SCons</span></a></span></dt><dd><dl><dt><span class="section"><a href="#idm106">1.1. Installing Python</a></span></dt><dt><span class="section"><a href="#idm126">1.2. Installing <span class="application">SCons</span></a></span></dt><dt><span class="section"><a href="#idm142">1.3. Building and Installing <span class="application">SCons</span> on Any System</a></span></dt><dd><dl><dt><span class="section"><a href="#idm171">1.3.1. Building and Installing Multiple Versions of <span class="application">SCons</span> Side-by-Side</a></span></dt><dt><span class="section"><a href="#idm195">1.3.2. Installing <span class="application">SCons</span> in Other Locations</a></span></dt><dt><span class="section"><a href="#idm213">1.3.3. Building and Installing <span class="application">SCons</span> Without Administrative Privileges</a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="#chap-simple">2. Simple Builds</a></span></dt><dd><dl><dt><span class="section"><a href="#idm239">2.1. Building Simple C / C++ Programs</a></span></dt><dt><span class="section"><a href="#idm271">2.2. Building Object Files</a></span></dt><dt><span class="section"><a href="#idm290">2.3. Simple Java Builds</a></span></dt><dt><span class="section"><a href="#idm311">2.4. Cleaning Up After a Build</a></span></dt><dt><span class="section"><a href="#idm331">2.5. The <code class="filename">SConstruct</code> File</a></span></dt><dd><dl><dt><span class="section"><a href="#idm341">2.5.1. <code class="filename">SConstruct</code> Files Are Python Scripts</a></span></dt><dt><span class="section"><a href="#idm353">2.5.2. <span class="application">SCons</span> Functions Are Order-Independent</a></span></dt></dl></dd><dt><span class="section"><a href="#idm403">2.6. Making the <span class="application">SCons</span> Output Less Verbose</a></span></dt></dl></dd><dt><span class="chapter"><a href="#chap-less-simple">3. Less Simple Things to Do With Builds</a></span></dt><dd><dl><dt><span class="section"><a href="#idm426">3.1. Specifying the Name of the Target (Output) File</a></span></dt><dt><span class="section"><a href="#idm450">3.2. Compiling Multiple Source Files</a></span></dt><dt><span class="section"><a href="#idm472">3.3. Making a list of files with <code class="function">Glob</code></a></span></dt><dt><span class="section"><a href="#idm493">3.4. Specifying Single Files Vs. Lists of Files</a></span></dt><dt><span class="section"><a href="#idm511">3.5. Making Lists of Files Easier to Read</a></span></dt><dt><span class="section"><a href="#idm537">3.6. Keyword Arguments</a></span></dt><dt><span class="section"><a href="#idm548">3.7. Compiling Multiple Programs</a></span></dt><dt><span class="section"><a href="#idm562">3.8. Sharing Source Files Between Multiple Programs</a></span></dt><dt><span class="section"><a href="#idm578">3.9. Overriding construction variables when calling a Builder</a></span></dt></dl></dd><dt><span class="chapter"><a href="#chap-libraries">4. Building and Linking with Libraries</a></span></dt><dd><dl><dt><span class="section"><a href="#idm599">4.1. Building Libraries</a></span></dt><dd><dl><dt><span class="section"><a href="#idm618">4.1.1. Building Libraries From Source Code or Object Files</a></span></dt><dt><span class="section"><a href="#idm629">4.1.2. Building Static Libraries Explicitly: the <code class="function">StaticLibra
Function</a></span></dt><dt><span class="section"><a href="#idm1263">6.7. Ignoring Dependencies: the <code class="function">Ignore</code> Function</a></span></dt><dt><span class="section"><a href="#idm1290">6.8. Order-Only Dependencies: the <code class="function">Requires</code> Function</a></span></dt><dt><span class="section"><a href="#idm1351">6.9. The <code class="function">AlwaysBuild</code> Function</a></span></dt></dl></dd><dt><span class="chapter"><a href="#chap-environments">7. Environments</a></span></dt><dd><dl><dt><span class="section"><a href="#sect-external-environments">7.1. Using Values From the External Environment</a></span></dt><dt><span class="section"><a href="#sect-construction-environments">7.2. Construction Environments</a></span></dt><dd><dl><dt><span class="section"><a href="#idm1439">7.2.1. Creating a <code class="literal">Construction Environment</code>: the <code class="function">Environment</code> Function</a></span></dt><dt><span class="section"><a href="#idm1462">7.2.2. Fetching Values From a <code class="literal">Construction Environment</code></a></span></dt><dt><span class="section"><a href="#idm1485">7.2.3. Expanding Values From a <code class="literal">Construction Environment</code>: the <code class="function">subst</code> Method</a></span></dt><dt><span class="section"><a href="#idm1518">7.2.4. Handling Problems With Value Expansion</a></span></dt><dt><span class="section"><a href="#idm1542">7.2.5. Controlling the Default <code class="literal">Construction Environment</code>: the <code class="function">DefaultEnvironment</code> Function</a></span></dt><dt><span class="section"><a href="#idm1573">7.2.6. Multiple <code class="literal">Construction Environments</code></a></span></dt><dt><span class="section"><a href="#idm1613">7.2.7. Making Copies of <code class="literal">Construction Environments</code>: the <code class="function">Clone</code> Method</a></span></dt><dt><span class="section"><a href="#idm1634">7.2.8. Replacing Values: the <code class="function">Replace</code> Method</a></span></dt><dt><span class="section"><a href="#idm1666">7.2.9. Setting Values Only If They're Not Already Defined: the <code class="function">SetDefault</code> Method</a></span></dt><dt><span class="section"><a href="#idm1675">7.2.10. Appending to the End of Values: the <code class="function">Append</code> Method</a></span></dt><dt><span class="section"><a href="#idm1695">7.2.11. Appending Unique Values: the <code class="function">AppendUnique</code> Method</a></span></dt><dt><span class="section"><a href="#idm1705">7.2.12. Appending to the Beginning of Values: the <code class="function">Prepend</code> Method</a></span></dt><dt><span class="section"><a href="#idm1726">7.2.13. Prepending Unique Values: the <code class="function">PrependUnique</code> Method</a></span></dt></dl></dd><dt><span class="section"><a href="#sect-execution-environments">7.3. Controlling the Execution Environment for Issued Commands</a></span></dt><dd><dl><dt><span class="section"><a href="#idm1767">7.3.1. Propagating <code class="varname">PATH</code> From the External Environment</a></span></dt><dt><span class="section"><a href="#idm1786">7.3.2. Adding to <code class="varname">PATH</code> Values in the Execution Environment</a></span></dt></dl></dd><dt><span class="section"><a href="#sect-environment-toolpath">7.4. Using the toolpath for external Tools</a></span></dt><dd><dl><dt><span class="section"><a href="#idm1806">7.4.1. The default tool search path</a></span></dt><dt><span class="section"><a href="#idm1812">7.4.2. Providing an external directory to toolpath</a></span></dt><dt><span class="section"><a href="#idm1816">7.4.3. Nested Tools within a toolpath</a></span></dt><dt><span class="section"><a href="#idm1822">7.4.4. Using sys.path within the toolpath</a></span></dt><dt><span class="section"><a href="#idm1828">7.4.5. Using the <code class="function">PyPackageDir</code> function to add to the toolpath</a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="#chap-manip-options">8. Automatically P
of extensions</a></dt><dt>E.6. <a href="#idm14947">The "backtick function": run a shell command and capture the
output</a></dt><dt>E.7. <a href="#idm14950">Generating source code: how code can be generated and used by SCons</a></dt></dl></div><div class="preface" title="Preface"><div class="titlepage"><div><div><h2 class="title"><a name="chap-preface"></a>Preface</h2></div></div></div><p>
Thank you for taking the time to read about <span class="application">SCons</span>.
<span class="application">SCons</span> is a next-generation
software construction tool,
or make tool--that is, a software utility
for building software (or other files)
and keeping built software up-to-date
whenever the underlying input files change.
</p><p>
The most distinctive thing about <span class="application">SCons</span>
is that its configuration files are
actually <span class="emphasis"><em>scripts</em></span>,
written in the <span class="application">Python</span> programming language.
This is in contrast to most alternative build tools,
which typically invent a new language to
configure the build.
<span class="application">SCons</span> still has a learning curve, of course,
because you have to know what functions to call
to set up your build properly,
but the underlying syntax used should be familiar
to anyone who has ever looked at a Python script.
</p><p>
Paradoxically,
using Python as the configuration file format
makes <span class="application">SCons</span>
<span class="emphasis"><em>easier</em></span>
for non-programmers to learn
than the cryptic languages of other build tools,
which are usually invented by programmers for other programmers.
This is in no small part due to the
consistency and readability that are hallmarks of Python.
It just so happens that making a real, live
scripting language the basis for the
configuration files
makes it a snap for more accomplished programmers
to do more complicated things with builds,
as necessary.
</p><div class="section" title="1.<2E>SCons Principles"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idm33"></a>1.<2E><span class="application">SCons</span> Principles</h2></div></div></div><p>
There are a few overriding principles
we try to live up to in designing and implementing <span class="application">SCons</span>:
</p><div class="variablelist"><dl><dt><span class="term">Correctness</span></dt><dd><p>
First and foremost,
by default, <span class="application">SCons</span> guarantees a correct build
even if it means sacrificing performance a little.
We strive to guarantee the build is correct
regardless of how the software being built is structured,
how it may have been written,
or how unusual the tools are that build it.
</p></dd><dt><span class="term">Performance</span></dt><dd><p>
Given that the build is correct,
we try to make <span class="application">SCons</span> build software
as quickly as possible.
In particular, wherever we may have needed to slow
down the default <span class="application">SCons</span> behavior to guarantee a correct build,
we also try to make it easy to speed up <span class="application">SCons</span>
through optimization options that let you trade off
guaranteed correctness in all end cases for
a speedier build in the usual cases.
</p></dd><dt><span class="term">Convenience</span></dt><dd><p>
<span class="application">SCons</span> tries to do as much for you out of the box as reasonable,
including detecting the right tools on your system
and using them correctly to build the software.
</p></dd></dl></div><p>
In a nutshell, we try hard to make <span class="application">SCons</span> just
"do the right thing" and build software correctly,
with a minimum of hassles.
</p></div><div class="section" title="2.<2E>A Caveat About This Guide's Completeness"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idm58"></a>2.<2E>A Caveat About This Guide's Completeness</h2></div></div></div><p>
One word of warning as you read through this Guide:
Like too much Open Source software out there,
the <span class="application">SCons</span> documentation isn't always
kept up-to-date with the available features.
In other words,
there's a lot that <span class="application">SCons</span> can do that
isn't yet covered in this User's Guide.
(Come to think of it,
that also describes a lot of proprietary software, doesn't it?)
</p><p>
Although this User's Guide isn't as complete as we'd like it to be,
our development process does emphasize
making sure that the <span class="application">SCons</span> man page is kept up-to-date
with new features.
So if you're trying to figure out how to do something
that <span class="application">SCons</span> supports
but can't find enough (or any) information here,
it would be worth your while to look
at the man page to see if the information is covered there.
And if you do,
maybe you'd even consider contributing
a section to the User's Guide
so the next person looking for
that information won't have to
go through the same thing...?
</p></div><div class="section" title="3.<2E>Acknowledgements"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idm66"></a>3.<2E>Acknowledgements</h2></div></div></div><p>
<span class="application">SCons</span> would not exist without a lot of help
from a lot of people,
many of whom may not even be aware
that they helped or served as inspiration.
So in no particular order,
and at the risk of leaving out someone:
</p><p>
First and foremost,
<span class="application">SCons</span> owes a tremendous debt to Bob Sidebotham,
the original author of the classic Perl-based <span class="application">Cons</span> tool
which Bob first released to the world back around 1996.
Bob's work on Cons classic provided the underlying architecture
and model of specifying a build configuration
using a real scripting language.
My real-world experience working on Cons
informed many of the design decisions in SCons,
including the improved parallel build support,
making Builder objects easily definable by users,
and separating the build engine from the wrapping interface.
</p><p>
Greg Wilson was instrumental in getting
<span class="application">SCons</span> started as a real project
when he initiated the Software Carpentry design
competition in February 2000.
Without that nudge,
marrying the advantages of the Cons classic
architecture with the readability of Python
might have just stayed no more than a nice idea.
</p><p>
The entire <span class="application">SCons</span> team have been
absolutely wonderful to work with,
and <span class="application">SCons</span> would be nowhere near as useful a
tool without the energy, enthusiasm
and time people have contributed over the past few years.
The "core team"
of Chad Austin, Anthony Roach,
Bill Deegan, Charles Crain, Steve Leblanc, Greg Noel,
Gary Oberbrunner, Greg Spencer and Christoph Wiedemann
have been great about reviewing my (and other) changes
and catching problems before they get in the code base.
Of particular technical note:
Anthony's outstanding and innovative work on the tasking engine
has given <span class="application">SCons</span> a vastly superior parallel build model;
Charles has been the master of the crucial Node infrastructure;
Christoph's work on the Configure infrastructure
has added crucial Autoconf-like functionality;
and Greg has provided excellent support
for Microsoft Visual Studio.
</p><p>
Special thanks to David Snopek for contributing
his underlying "Autoscons" code that formed
the basis of Christoph's work with the Configure functionality.
David was extremely generous in making
this code available to <span class="application">SCons</span>,
given that he initially released it under the GPL
and <span class="application">SCons</span> is released under a less-restrictive MIT-style license.
</p><p>
Thanks to Peter Miller
for his splendid change management system, <span class="application">Aegis</span>,
which has provided the <span class="application">SCons</span> project
with a robust development methodology from day one,
and which showed me how you could
integrate incremental regression tests into
a practical development cycle
(years before eXtreme Programming arrived on the scene).
</p><p>
And last, thanks to Guido van Rossum
for his elegant scripting language,
which is the basis not only for the <span class="application">SCons</span> implementation,
but for the interface itself.
</p></div><div class="section" title="4.<2E>Contact"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idm87"></a>4.<2E>Contact</h2></div></div></div><p>
The best way to contact people involved with SCons,
including the author,
is through the SCons mailing lists.
</p><p>
If you want to ask general questions about how to use <span class="application">SCons</span>
send email to <code class="literal">scons-users@scons.org</code>.
</p><p>
If you want to contact the <span class="application">SCons</span> development community directly,
send email to <code class="literal">scons-dev@scons.org</code>.
</p><p>
If you want to receive announcements about <span class="application">SCons</span>,
join the low-volume <code class="literal">announce@scons.tigris.org</code> mailing list.
</p></div></div><div class="chapter" title="Chapter<65>1.<2E>Building and Installing SCons"><div class="titlepage"><div><div><h2 class="title"><a name="chap-build-install"></a>Chapter<EFBFBD>1.<2E>Building and Installing <span class="application">SCons</span></h2></div></div></div><p>
This chapter will take you through the basic steps
of installing <span class="application">SCons</span> on your system,
and building <span class="application">SCons</span> if you don't have a
pre-built package available
(or simply prefer the flexibility of building it yourself).
Before that, however, this chapter will also describe the basic steps
involved in installing Python on your system,
in case that is necessary.
Fortunately, both <span class="application">SCons</span> and Python
are very easy to install on almost any system,
and Python already comes installed on many systems.
</p><div class="section" title="1.1.<2E>Installing Python"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idm106"></a>1.1.<2E>Installing Python</h2></div></div></div><p>
Because <span class="application">SCons</span> is written in Python,
you need to have Python installed on your system
to use <span class="application">SCons</span>.
Before you try to install Python,
you should check to see if Python is already
available on your system by typing
<strong class="userinput"><code>python -V</code></strong>
(capital 'V')
or
<strong class="userinput"><code>python --version</code></strong>
at your system's command-line prompt.
For Linux/Unix/MacOS/BSD type systems this looks like:
</p><pre class="screen">
$ <strong class="userinput"><code>python -V</code></strong>
Python 3.7.1
</pre><p>
In a cmd shell or PowerShell on a Windows system
(note PoweShell needs it spelled "python.exe" rather than "python"):
</p><pre class="screen">
C:\&gt;<strong class="userinput"><code>python -V</code></strong>
Python 3.7.1
</pre><p>
If Python is not installed on your system,
you will see an error message
stating something like "command not found"
(on UNIX or Linux)
or "'python' is not recognized
as an internal or external command, operable progam or batch file"
(on Windows).
In that case, you need to install Python
before you can install <span class="application">SCons</span>.
</p><p>
The standard location for information
about downloading and installing Python is
<a class="ulink" href="http://www.python.org/download/" target="_top">http://www.python.org/download/</a>.
See that page and associated links to get started.
</p><p>
For Linux systems, Python is
almost certainly available as a supported package, possibly
installed by default; this is often preferred to installing
by other means, and is easier than installing from source code.
Many such systems have separate packages for
Python 2 and Python 3. Building from source may still be a
useful option if you need a version that is not offered by
the distribution you are using.
</p><p>
<span class="application">SCons</span> will work with Python 2.7.x or with Python 3.5 or later.
If you need to install Python and have a choice,
we recommend using the most recent Python version available.
Newer Pythons have significant improvements
that help speed up the performance of <span class="application">SCons</span>.
</p></div><div class="section" title="1.2.<2E>Installing SCons"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idm126"></a>1.2.<2E>Installing <span class="application">SCons</span></h2></div></div></div><p>
The canonical way to install <span class="application">SCons</span> is from the Python Package
Index (PyPi):
</p><pre class="screen">
% <strong class="userinput"><code>python -m pip install scons</code></strong>
</pre><p>
If you prefer not to install to the Python system location,
or do not have privileges to do so, you can add a flag to
install to a location specific to your own account:
</p><pre class="screen">
% <strong class="userinput"><code>python -m pip install --user scons</code></strong>
</pre><p>
<span class="application">SCons</span> comes pre-packaged for installation on many Linux systems
Check your package installation system
to see if there is an <span class="application">SCons</span> package available.
Many people prefer to install distribution-native packages if available,
as they provide a central point for management and updating.
Some distributions have two <span class="application">SCons</span> packages available, one which
uses Python 2 and one which uses Python 3. If you need a specific
version of <span class="application">SCons</span> that is different from the package available,
<code class="filename">pip</code> has a version option or you can follow
the instructions in the next section.
</p></div><div class="section" title="1.3.<2E>Building and Installing SCons on Any System"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idm142"></a>1.3.<2E>Building and Installing <span class="application">SCons</span> on Any System</h2></div></div></div><p>
If a pre-built <span class="application">SCons</span> package is not available for your system,
and installing using <code class="filename">pip</code> is not suitable,
then you can still easily build and install <span class="application">SCons</span> using the native
Python <code class="filename">distutils</code> package.
</p><p>
The first step is to download either the
<code class="filename">scons-3.0.4.tar.gz</code>
or <code class="filename">scons-3.0.4.zip</code>,
which are available from the SCons download page at
<a class="ulink" href="http://www.scons.org/download.html" target="_top">http://www.scons.org/download.html</a>.
</p><p>
Unpack the archive you downloaded,
using a utility like <span class="application">tar</span>
on Linux or UNIX,
or <span class="application">WinZip</span> on Windows.
This will create a directory called
<code class="filename">scons-3.0.4</code>,
usually in your local directory.
Then change your working directory to that directory
and install <span class="application">SCons</span> by executing the following commands:
</p><pre class="screen">
# <strong class="userinput"><code>cd scons-3.0.4</code></strong>
# <strong class="userinput"><code>python setup.py install</code></strong>
</pre><p>
This will build <span class="application">SCons</span>,
install the <code class="filename">scons</code> script
in the python which is used to run the setup.py's scripts directory
(<code class="filename">/usr/local/bin</code> or
<code class="filename">C:\Python27\Scripts</code>),
and will install the <span class="application">SCons</span> build engine
in the corresponding library directory for the python used
(<code class="filename">/usr/local/lib/scons</code> or
<code class="filename">C:\Python27\scons</code>).
Because these are system directories,
you may need root (on Linux or UNIX) or Administrator (on Windows)
privileges to install <span class="application">SCons</span> like this.
</p><div class="section" title="1.3.1.<2E>Building and Installing Multiple Versions of SCons Side-by-Side"><div class="titlepage"><div><div><h3 class="title"><a name="idm171"></a>1.3.1.<2E>Building and Installing Multiple Versions of <span class="application">SCons</span> Side-by-Side</h3></div></div></div><p>
The <span class="application">SCons</span> <code class="filename">setup.py</code> script
has some extensions that support
easy installation of multiple versions of <span class="application">SCons</span>
in side-by-side locations.
This makes it easier to download and
experiment with different versions of <span class="application">SCons</span>
before moving your official build process to a new version,
for example.
</p><p>
To install <span class="application">SCons</span> in a version-specific location,
add the <code class="option">--version-lib</code> option
when you call <code class="filename">setup.py</code>:
</p><pre class="screen">
# <strong class="userinput"><code>python setup.py install --version-lib</code></strong>
</pre><p>
This will install the <span class="application">SCons</span> build engine
in the
<code class="filename">/usr/lib/scons-3.0.4</code>
or
<code class="filename">C:\Python27\scons-3.0.4</code>
directory, for example.
</p><p>
If you use the <code class="option">--version-lib</code> option
the first time you install <span class="application">SCons</span>,
you do not need to specify it each time you install
a new version.
The <span class="application">SCons</span> <code class="filename">setup.py</code> script
will detect the version-specific directory name(s)
and assume you want to install all versions
in version-specific directories.
You can override that assumption in the future
by explicitly specifying the <code class="option">--standalone-lib</code> option.
</p></div><div class="section" title="1.3.2.<2E>Installing SCons in Other Locations"><div class="titlepage"><div><div><h3 class="title"><a name="idm195"></a>1.3.2.<2E>Installing <span class="application">SCons</span> in Other Locations</h3></div></div></div><p>
You can install <span class="application">SCons</span> in locations other than
the default by specifying the <code class="option">--prefix=</code> option:
</p><pre class="screen">
# <strong class="userinput"><code>python setup.py install --prefix=/opt/scons</code></strong>
</pre><p>
This would
install the <span class="application">scons</span> script in
<code class="filename">/opt/scons/bin</code>
and the build engine in
<code class="filename">/opt/scons/lib/scons</code>,
</p><p>
Note that you can specify both the <code class="option">--prefix=</code>
and the <code class="option">--version-lib</code> options
at the same type,
in which case <code class="filename">setup.py</code>
will install the build engine
in a version-specific directory
relative to the specified prefix.
Adding <code class="option">--version-lib</code> to the
above example would install the build engine in
<code class="filename">/opt/scons/lib/scons-3.0.4</code>.
</p></div><div class="section" title="1.3.3.<2E>Building and Installing SCons Without Administrative Privileges"><div class="titlepage"><div><div><h3 class="title"><a name="idm213"></a>1.3.3.<2E>Building and Installing <span class="application">SCons</span> Without Administrative Privileges</h3></div></div></div><p>
If you don't have the right privileges to install <span class="application">SCons</span>
in a system location,
simply use the <code class="literal">--prefix=</code> option
to install it in a location of your choosing.
For example,
to install <span class="application">SCons</span> in appropriate locations
relative to the user's <code class="literal">$HOME</code> directory,
the <code class="filename">scons</code> script in
<code class="filename">$HOME/bin</code>
and the build engine in
<code class="filename">$HOME/lib/scons</code>,
simply type:
</p><pre class="screen">
$ <strong class="userinput"><code>python setup.py install --prefix=$HOME</code></strong>
</pre><p>
You may, of course, specify any other location you prefer,
and may use the <code class="option">--version-lib</code> option
if you would like to install version-specific directories
relative to the specified prefix.
</p><p>
This can also be used to experiment with a newer
version of <span class="application">SCons</span> than the one installed
in your system locations.
Of course, the location in which you install the
newer version of the <code class="filename">scons</code> script
(<code class="filename">$HOME/bin</code> in the above example)
must be configured in your <code class="varname">PATH</code> variable
before the directory containing
the system-installed version
of the <code class="filename">scons</code> script.
</p></div></div></div><div class="chapter" title="Chapter<65>2.<2E>Simple Builds"><div class="titlepage"><div><div><h2 class="title"><a name="chap-simple"></a>Chapter<EFBFBD>2.<2E>Simple Builds</h2></div></div></div><p>
In this chapter,
you will see several examples of
very simple build configurations using <span class="application">SCons</span>,
which will demonstrate how easy
it is to use <span class="application">SCons</span> to
build programs from several different programming languages
on different types of systems.
</p><div class="section" title="2.1.<2E>Building Simple C / C++ Programs"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idm239"></a>2.1.<2E>Building Simple C / C++ Programs</h2></div></div></div><p>
Here's the famous "Hello, World!" program in C:
</p><pre class="programlisting">
int
main()
{
printf("Hello, world!\n");
}
</pre><p>
And here's how to build it using <span class="application">SCons</span>.
Enter the following into a file named <code class="filename">SConstruct</code>:
</p><pre class="programlisting">
Program('hello.c')
</pre><p>
This minimal configuration file gives
<span class="application">SCons</span> two pieces of information:
what you want to build
(an executable program),
and the input file from
which you want it built
(the <code class="filename">hello.c</code> file).
<a class="link" href="#b-Program"><code class="function">Program</code></a> is a <em class="firstterm">builder_method</em>,
a Python call that tells <span class="application">SCons</span> that you want to build an
executable program.
</p><p>
That's it. Now run the <code class="filename">scons</code> command to build the program.
On a POSIX-compliant system like Linux or UNIX,
you'll see something like:
</p><pre class="screen">% <strong class="userinput"><code>scons</code></strong>
scons: Reading SConscript files ...
scons: done reading SConscript files.
scons: Building targets ...
cc -o hello.o -c hello.c
cc -o hello hello.o
scons: done building targets.
</pre><p>
On a Windows system with the Microsoft Visual C++ compiler,
you'll see something like:
</p><pre class="screen">C:\&gt;<strong class="userinput"><code>scons</code></strong>
scons: Reading SConscript files ...
scons: done reading SConscript files.
scons: Building targets ...
cl /Fohello.obj /c hello.c /nologo
link /nologo /OUT:hello.exe hello.obj
embedManifestExeCheck(target, source, env)
scons: done building targets.
</pre><p>
First, notice that you only need
to specify the name of the source file,
and that <span class="application">SCons</span> correctly deduces the names of
the object and executable files to be built
from the base of the source file name.
</p><p>
Second, notice that the same input <code class="filename">SConstruct</code> file,
without any changes,
generates the correct output file names on both systems:
<code class="filename">hello.o</code> and <code class="filename">hello</code>
on POSIX systems,
<code class="filename">hello.obj</code> and <code class="filename">hello.exe</code>
on Windows systems.
This is a simple example of how <span class="application">SCons</span>
makes it extremely easy to
write portable software builds.
</p><p>
(Note that we won't provide duplicate side-by-side
POSIX and Windows output for all of the examples in this guide;
just keep in mind that, unless otherwise specified,
any of the examples should work equally well on both types of systems.)
</p></div><div class="section" title="2.2.<2E>Building Object Files"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idm271"></a>2.2.<2E>Building Object Files</h2></div></div></div><p>
The <a class="link" href="#b-Program"><code class="function">Program</code></a> builder method is only one of
many builder methods that <span class="application">SCons</span> provides
to build different types of files.
Another is the <a class="link" href="#b-Object"><code class="function">Object</code></a> builder method,
which tells <span class="application">SCons</span> to build an object file
from the specified source file:
</p><pre class="programlisting">
Object('hello.c')
</pre><p>
Now when you run the <code class="filename">scons</code> command to build the program,
it will build just the <code class="filename">hello.o</code> object file on a POSIX system:
</p><pre class="screen">% <strong class="userinput"><code>scons</code></strong>
scons: Reading SConscript files ...
scons: done reading SConscript files.
scons: Building targets ...
cc -o hello.o -c hello.c
scons: done building targets.
</pre><p>
And just the <code class="filename">hello.obj</code> object file
on a Windows system (with the Microsoft Visual C++ compiler):
</p><pre class="screen">C:\&gt;<strong class="userinput"><code>scons</code></strong>
scons: Reading SConscript files ...
scons: done reading SConscript files.
scons: Building targets ...
cl /Fohello.obj /c hello.c /nologo
scons: done building targets.
</pre></div><div class="section" title="2.3.<2E>Simple Java Builds"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idm290"></a>2.3.<2E>Simple Java Builds</h2></div></div></div><p>
<span class="application">SCons</span> also makes building with Java extremely easy.
Unlike the <a class="link" href="#b-Program"><code class="function">Program</code></a> and <a class="link" href="#b-Object"><code class="function">Object</code></a> builder methods,
however, the <a class="link" href="#b-Java"><code class="function">Java</code></a> builder method
requires that you specify
the name of a destination directory in which
you want the class files placed,
followed by the source directory
in which the <code class="filename">.java</code> files live:
</p><pre class="programlisting">
Java('classes', 'src')
</pre><p>
If the <code class="filename">src</code> directory
contains a single <code class="filename">hello.java</code> file,
then the output from running the <code class="filename">scons</code> command
would look something like this
(on a POSIX system):
</p><pre class="screen">% <strong class="userinput"><code>scons</code></strong>
scons: Reading SConscript files ...
scons: done reading SConscript files.
scons: Building targets ...
javac -d classes -sourcepath src src/hello.java
scons: done building targets.
</pre><p>
We'll cover Java builds in more detail,
including building Java archive (<code class="filename">.jar</code>)
and other types of file,
in <a class="xref" href="#chap-java" title="Chapter<65>26.<2E>Java Builds">Chapter<EFBFBD>26, <i>Java Builds</i></a>.
</p></div><div class="section" title="2.4.<2E>Cleaning Up After a Build"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idm311"></a>2.4.<2E>Cleaning Up After a Build</h2></div></div></div><p>
When using <span class="application">SCons</span>, it is unnecessary to add special
commands or target names to clean up after a build.
Instead, you simply use the
<code class="literal">-c</code> or <code class="literal">--clean</code>
option when you invoke <span class="application">SCons</span>,
and <span class="application">SCons</span> removes the appropriate built files.
So if we build our example above
and then invoke <code class="literal">scons -c</code>
afterwards, the output on POSIX looks like:
</p><pre class="screen">% <strong class="userinput"><code>scons</code></strong>
scons: Reading SConscript files ...
scons: done reading SConscript files.
scons: Building targets ...
cc -o hello.o -c hello.c
cc -o hello hello.o
scons: done building targets.
% <strong class="userinput"><code>scons -c</code></strong>
scons: Reading SConscript files ...
scons: done reading SConscript files.
scons: Cleaning targets ...
Removed hello.o
Removed hello
scons: done cleaning targets.
</pre><p>
And the output on Windows looks like:
</p><pre class="screen">C:\&gt;<strong class="userinput"><code>scons</code></strong>
scons: Reading SConscript files ...
scons: done reading SConscript files.
scons: Building targets ...
cl /Fohello.obj /c hello.c /nologo
link /nologo /OUT:hello.exe hello.obj
embedManifestExeCheck(target, source, env)
scons: done building targets.
C:\&gt;<strong class="userinput"><code>scons -c</code></strong>
scons: Reading SConscript files ...
scons: done reading SConscript files.
scons: Cleaning targets ...
Removed hello.obj
Removed hello.exe
scons: done cleaning targets.
</pre><p>
Notice that <span class="application">SCons</span> changes its output to tell you that it
is <code class="literal">Cleaning targets ...</code> and
<code class="literal">done cleaning targets.</code>
</p></div><div class="section" title="2.5.<2E>The SConstruct File"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idm331"></a>2.5.<2E>The <code class="filename">SConstruct</code> File</h2></div></div></div><p>
If you're used to build systems like <span class="application">Make</span>
you've already figured out that the <code class="filename">SConstruct</code> file
is the <span class="application">SCons</span> equivalent of a <code class="filename">Makefile</code>.
That is, the <code class="filename">SConstruct</code> file is the input file
that <span class="application">SCons</span> reads to control the build.
</p><div class="section" title="2.5.1.<2E>SConstruct Files Are Python Scripts"><div class="titlepage"><div><div><h3 class="title"><a name="idm341"></a>2.5.1.<2E><code class="filename">SConstruct</code> Files Are Python Scripts</h3></div></div></div><p>
There is, however, an important difference between
an <code class="filename">SConstruct</code> file and a <code class="filename">Makefile</code>:
the <code class="filename">SConstruct</code> file is actually a Python script.
If you're not already familiar with Python, don't worry.
This User's Guide will introduce you step-by-step
to the relatively small amount of Python you'll
need to know to be able to use <span class="application">SCons</span> effectively.
And Python is very easy to learn.
</p><p>
One aspect of using Python as the
scripting language is that you can put comments
in your <code class="filename">SConstruct</code> file using Python's commenting convention;
that is, everything between a '#' and the end of the line
will be ignored:
</p><pre class="programlisting">
# Arrange to build the "hello" program.
Program('hello.c') # "hello.c" is the source file.
</pre><p>
You'll see throughout the remainder of this Guide
that being able to use the power of a
real scripting language
can greatly simplify the solutions
to complex requirements of real-world builds.
</p></div><div class="section" title="2.5.2.<2E>SCons Functions Are Order-Independent"><div class="titlepage"><div><div><h3 class="title"><a name="idm353"></a>2.5.2.<2E><span class="application">SCons</span> Functions Are Order-Independent</h3></div></div></div><p>
One important way in which the <code class="filename">SConstruct</code>
file is not exactly like a normal Python script,
and is more like a <code class="filename">Makefile</code>,
is that the order in which
the <span class="application">SCons</span> functions are called in
the <code class="filename">SConstruct</code> file
does <span class="emphasis"><em>not</em></span>
affect the order in which <span class="application">SCons</span>
actually builds the programs and object files
you want it to build.<sup>[<a name="idm363" href="#ftn.idm363" class="footnote">1</a>]</sup>
In other words, when you call the <a class="link" href="#b-Program"><code class="function">Program</code></a> builder
(or any other builder method),
you're not telling <span class="application">SCons</span> to build
the program at the instant the builder method is called.
Instead, you're telling <span class="application">SCons</span> to build the program
that you want, for example,
a program built from a file named <code class="filename">hello.c</code>,
and it's up to <span class="application">SCons</span> to build that program
(and any other files) whenever it's necessary.
(We'll learn more about how
<span class="application">SCons</span> decides when building or rebuilding a file
is necessary in <a class="xref" href="#chap-depends" title="Chapter<65>6.<2E>Dependencies">Chapter<EFBFBD>6, <i>Dependencies</i></a>, below.)
</p><p>
<span class="application">SCons</span> reflects this distinction between
<span class="emphasis"><em>calling a builder method like</em></span> <code class="function">Program</code>
and <span class="emphasis"><em>actually building the program</em></span>
by printing the status messages that indicate
when it's "just reading" the <code class="filename">SConstruct</code> file,
and when it's actually building the target files.
This is to make it clear when <span class="application">SCons</span> is
executing the Python statements that make up the <code class="filename">SConstruct</code> file,
and when <span class="application">SCons</span> is actually executing the
commands or other actions to
build the necessary files.
</p><p>
Let's clarify this with an example.
Python has a <code class="literal">print</code> statement that
prints a string of characters to the screen.
If we put <code class="literal">print</code> statements around
our calls to the <code class="function">Program</code> builder method:
</p><pre class="programlisting">
print("Calling Program('hello.c')")
Program('hello.c')
print("Calling Program('goodbye.c')")
Program('goodbye.c')
print("Finished calling Program()")
</pre><p>
Then when we execute <span class="application">SCons</span>,
we see the output from the <code class="literal">print</code>
statements in between the messages about
reading the <code class="filename">SConscript</code> files,
indicating that that is when the
Python statements are being executed:
</p><pre class="screen">% <strong class="userinput"><code>scons</code></strong>
scons: Reading SConscript files ...
Calling Program('hello.c')
Calling Program('goodbye.c')
Finished calling Program()
scons: done reading SConscript files.
scons: Building targets ...
cc -o goodbye.o -c goodbye.c
cc -o goodbye goodbye.o
cc -o hello.o -c hello.c
cc -o hello hello.o
scons: done building targets.
</pre><p>
Notice also that <span class="application">SCons</span> built the <code class="filename">goodbye</code> program first,
even though the "reading <code class="filename">SConscript</code>" output
shows that we called <code class="literal">Program('hello.c')</code>
first in the <code class="filename">SConstruct</code> file.
</p></div></div><div class="section" title="2.6.<2E>Making the SCons Output Less Verbose"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idm403"></a>2.6.<2E>Making the <span class="application">SCons</span> Output Less Verbose</h2></div></div></div><p>
You've already seen how <span class="application">SCons</span> prints
some messages about what it's doing,
surrounding the actual commands used to build the software:
</p><pre class="screen">C:\&gt;<strong class="userinput"><code>scons</code></strong>
scons: Reading SConscript files ...
scons: done reading SConscript files.
scons: Building targets ...
cl /Fohello.obj /c hello.c /nologo
link /nologo /OUT:hello.exe hello.obj
embedManifestExeCheck(target, source, env)
scons: done building targets.
</pre><p>
These messages emphasize the
order in which <span class="application">SCons</span> does its work:
all of the configuration files
(generically referred to as <code class="filename">SConscript</code> files)
are read and executed first,
and only then are the target files built.
Among other benefits, these messages help to distinguish between
errors that occur while the configuration files are read,
and errors that occur while targets are being built.
</p><p>
One drawback, of course, is that these messages clutter the output.
Fortunately, they're easily disabled by using
the <code class="literal">-Q</code> option when invoking <span class="application">SCons</span>:
</p><pre class="screen">C:\&gt;<strong class="userinput"><code>scons -Q</code></strong>
cl /Fohello.obj /c hello.c /nologo
link /nologo /OUT:hello.exe hello.obj
embedManifestExeCheck(target, source, env)
</pre><p>
Because we want this User's Guide to focus
on what <span class="application">SCons</span> is actually doing,
we're going to use the <code class="literal">-Q</code> option
to remove these messages from the
output of all the remaining examples in this Guide.
</p></div><div class="footnotes"><br><hr width="100" align="left"><div class="footnote"><p><sup>[<a id="ftn.idm363" href="#idm363" class="para">1</a>] </sup>In programming parlance,
the <code class="filename">SConstruct</code> file is
<span class="emphasis"><em>declarative</em></span>,
meaning you tell <span class="application">SCons</span> what you want done
and let it figure out the order in which to do it,
rather than strictly <span class="emphasis"><em>imperative</em></span>,
where you specify explicitly the order in
which to do things.
</p></div></div></div><div class="chapter" title="Chapter<65>3.<2E>Less Simple Things to Do With Builds"><div class="titlepage"><div><div><h2 class="title"><a name="chap-less-simple"></a>Chapter<EFBFBD>3.<2E>Less Simple Things to Do With Builds</h2></div></div></div><p>
In this chapter,
you will see several examples of
very simple build configurations using <span class="application">SCons</span>,
which will demonstrate how easy
it is to use <span class="application">SCons</span> to
build programs from several different programming languages
on different types of systems.
</p><div class="section" title="3.1.<2E>Specifying the Name of the Target (Output) File"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idm426"></a>3.1.<2E>Specifying the Name of the Target (Output) File</h2></div></div></div><p>
You've seen that when you call the <a class="link" href="#b-Program"><code class="function">Program</code></a> builder method,
it builds the resulting program with the same
base name as the source file.
That is, the following call to build an
executable program from the <code class="filename">hello.c</code> source file
will build an executable program named <code class="filename">hello</code> on POSIX systems,
and an executable program named <code class="filename">hello.exe</code> on Windows systems:
</p><pre class="programlisting">
Program('hello.c')
</pre><p>
If you want to build a program with
a different name than the base of the source file name,
you simply put the target file name
to the left of the source file name:
</p><pre class="programlisting">
Program('new_hello', 'hello.c')
</pre><p>
(<span class="application">SCons</span> requires the target file name first,
followed by the source file name,
so that the order mimics that of an
assignment statement in most programming languages,
including Python:
<code class="literal">"program = source files"</code>.)
</p><p>
Now <span class="application">SCons</span> will build an executable program
named <code class="filename">new_hello</code> when run on a POSIX system:
</p><pre class="screen">% <strong class="userinput"><code>scons -Q</code></strong>
cc -o hello.o -c hello.c
cc -o new_hello hello.o
</pre><p>
And <span class="application">SCons</span> will build an executable program
named <code class="filename">new_hello.exe</code> when run on a Windows system:
</p><pre class="screen">C:\&gt;<strong class="userinput"><code>scons -Q</code></strong>
cl /Fohello.obj /c hello.c /nologo
link /nologo /OUT:new_hello.exe hello.obj
embedManifestExeCheck(target, source, env)
</pre></div><div class="section" title="3.2.<2E>Compiling Multiple Source Files"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idm450"></a>3.2.<2E>Compiling Multiple Source Files</h2></div></div></div><p>
You've just seen how to configure <span class="application">SCons</span>
to compile a program from a single source file.
It's more common, of course,
that you'll need to build a program from
many input source files, not just one.
To do this, you need to put the
source files in a Python list
(enclosed in square brackets),
like so:
</p><pre class="programlisting">
Program(['prog.c', 'file1.c', 'file2.c'])
</pre><p>
A build of the above example would look like:
</p><pre class="screen">% <strong class="userinput"><code>scons -Q</code></strong>
cc -o file1.o -c file1.c
cc -o file2.o -c file2.c
cc -o prog.o -c prog.c
cc -o prog prog.o file1.o file2.o
</pre><p>
Notice that <span class="application">SCons</span>
deduces the output program name
from the first source file specified
in the list--that is,
because the first source file was <code class="filename">prog.c</code>,
<span class="application">SCons</span> will name the resulting program <code class="filename">prog</code>
(or <code class="filename">prog.exe</code> on a Windows system).
If you want to specify a different program name,
then (as we've seen in the previous section)
you slide the list of source files
over to the right
to make room for the output program file name.
(<span class="application">SCons</span> puts the output file name to the left
of the source file names
so that the order mimics that of an
assignment statement: "program = source files".)
This makes our example:
</p><pre class="programlisting">
Program('program', ['prog.c', 'file1.c', 'file2.c'])
</pre><p>
On Linux, a build of this example would look like:
</p><pre class="screen">% <strong class="userinput"><code>scons -Q</code></strong>
cc -o file1.o -c file1.c
cc -o file2.o -c file2.c
cc -o prog.o -c prog.c
cc -o program prog.o file1.o file2.o
</pre><p>
Or on Windows:
</p><pre class="screen">C:\&gt;<strong class="userinput"><code>scons -Q</code></strong>
cl /Fofile1.obj /c file1.c /nologo
cl /Fofile2.obj /c file2.c /nologo
cl /Foprog.obj /c prog.c /nologo
link /nologo /OUT:program.exe prog.obj file1.obj file2.obj
embedManifestExeCheck(target, source, env)
</pre></div><div class="section" title="3.3.<2E>Making a list of files with Glob"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idm472"></a>3.3.<2E>Making a list of files with <code class="function">Glob</code></h2></div></div></div><p>
You can also use the <code class="function">Glob</code> function to find all files matching a
certain template, using the standard shell pattern matching
characters <code class="literal">*</code>, <code class="literal">?</code>
and <code class="literal">[abc]</code> to match any of
<code class="literal">a</code>, <code class="literal">b</code> or <code class="literal">c</code>.
<code class="literal">[!abc]</code> is also supported,
to match any character <span class="emphasis"><em>except</em></span>
<code class="literal">a</code>, <code class="literal">b</code> or <code class="literal">c</code>.
This makes many multi-source-file builds quite easy:
</p><pre class="programlisting">
Program('program', Glob('*.c'))
</pre><p>
The SCons man page has more details on using <code class="function">Glob</code>
with variant directories
(see <a class="xref" href="#chap-variants" title="Chapter<65>16.<2E>Variant Builds">Chapter<EFBFBD>16, <i>Variant Builds</i></a>, below)
and repositories
(see <a class="xref" href="#chap-repositories" title="Chapter<65>22.<2E>Building From Code Repositories">Chapter<EFBFBD>22, <i>Building From Code Repositories</i></a>, below),
excluding some files
and returning strings rather than Nodes.
</p></div><div class="section" title="3.4.<2E>Specifying Single Files Vs. Lists of Files"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idm493"></a>3.4.<2E>Specifying Single Files Vs. Lists of Files</h2></div></div></div><p>
We've now shown you two ways to specify
the source for a program,
one with a list of files:
</p><pre class="programlisting">
Program('hello', ['file1.c', 'file2.c'])
</pre><p>
And one with a single file:
</p><pre class="programlisting">
Program('hello', 'hello.c')
</pre><p>
You could actually put a single file name in a list, too,
which you might prefer just for the sake of consistency:
</p><pre class="programlisting">
Program('hello', ['hello.c'])
</pre><p>
<span class="application">SCons</span> functions will accept a single file name in either form.
In fact, internally, <span class="application">SCons</span> treats all input as lists of files,
but allows you to omit the square brackets
to cut down a little on the typing
when there's only a single file name.
</p><div class="important" title="Important" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Important</h3><p>
Although <span class="application">SCons</span> functions
are forgiving about whether or not you
use a string vs. a list for a single file name,
Python itself is more strict about
treating lists and strings differently.
So where <span class="application">SCons</span> allows either
a string or list:
</p><pre class="programlisting">
# The following two calls both work correctly:
Program('program1', 'program1.c')
Program('program2', ['program2.c'])
</pre><p>
Trying to do "Python things" that mix strings and
lists will cause errors or lead to incorrect results:
</p><pre class="programlisting">
common_sources = ['file1.c', 'file2.c']
# THE FOLLOWING IS INCORRECT AND GENERATES A PYTHON ERROR
# BECAUSE IT TRIES TO ADD A STRING TO A LIST:
Program('program1', common_sources + 'program1.c')
# The following works correctly, because it's adding two
# lists together to make another list.
Program('program2', common_sources + ['program2.c'])
</pre></div></div><div class="section" title="3.5.<2E>Making Lists of Files Easier to Read"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idm511"></a>3.5.<2E>Making Lists of Files Easier to Read</h2></div></div></div><p>
One drawback to the use of a Python list
for source files is that
each file name must be enclosed in quotes
(either single quotes or double quotes).
This can get cumbersome and difficult to read
when the list of file names is long.
Fortunately, <span class="application">SCons</span> and Python provide a number of ways
to make sure that
the <code class="filename">SConstruct</code> file stays easy to read.
</p><p>
To make long lists of file names
easier to deal with, <span class="application">SCons</span> provides a
<code class="function">Split</code> function
that takes a quoted list of file names,
with the names separated by spaces or other white-space characters,
and turns it into a list of separate file names.
Using the <code class="function">Split</code> function turns the
previous example into:
</p><pre class="programlisting">
Program('program', Split('main.c file1.c file2.c'))
</pre><p>
(If you're already familiar with Python,
you'll have realized that this is similar to the
<code class="function">split()</code> method
in the Python standard <code class="function">string</code> module.
Unlike the <code class="function">split()</code> member function of strings,
however, the <code class="function">Split</code> function
does not require a string as input
and will wrap up a single non-string object in a list,
or return its argument untouched if it's already a list.
This comes in handy as a way to make sure
arbitrary values can be passed to <span class="application">SCons</span> functions
without having to check the type of the variable by hand.)
</p><p>
Putting the call to the <code class="function">Split</code> function
inside the <code class="function">Program</code> call
can also be a little unwieldy.
A more readable alternative is to
assign the output from the <code class="function">Split</code> call
to a variable name,
and then use the variable when calling the
<code class="function">Program</code> function:
</p><pre class="programlisting">
src_files = Split('main.c file1.c file2.c')
Program('program', src_files)
</pre><p>
Lastly, the <code class="function">Split</code> function
doesn't care how much white space separates
the file names in the quoted string.
This allows you to create lists of file
names that span multiple lines,
which often makes for easier editing:
</p><pre class="programlisting">
src_files = Split("""main.c
file1.c
file2.c""")
Program('program', src_files)
</pre><p>
(Note in this example that we used
the Python "triple-quote" syntax,
which allows a string to contain
multiple lines.
The three quotes can be either
single or double quotes.)
</p></div><div class="section" title="3.6.<2E>Keyword Arguments"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idm537"></a>3.6.<2E>Keyword Arguments</h2></div></div></div><p>
<span class="application">SCons</span> also allows you to identify
the output file and input source files
using Python keyword arguments.
The output file is known as the
<span class="emphasis"><em>target</em></span>,
and the source file(s) are known (logically enough) as the
<span class="emphasis"><em>source</em></span>.
The Python syntax for this is:
</p><pre class="programlisting">
src_files = Split('main.c file1.c file2.c')
Program(target = 'program', source = src_files)
</pre><p>
Because the keywords explicitly identify
what each argument is,
you can actually reverse the order if you prefer:
</p><pre class="programlisting">
src_files = Split('main.c file1.c file2.c')
Program(source = src_files, target = 'program')
</pre><p>
Whether or not you choose to use keyword arguments
to identify the target and source files,
and the order in which you specify them
when using keywords,
are purely personal choices;
<span class="application">SCons</span> functions the same regardless.
</p></div><div class="section" title="3.7.<2E>Compiling Multiple Programs"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idm548"></a>3.7.<2E>Compiling Multiple Programs</h2></div></div></div><p>
In order to compile multiple programs
within the same <code class="filename">SConstruct</code> file,
simply call the <code class="function">Program</code> method
multiple times,
once for each program you need to build:
</p><pre class="programlisting">
Program('foo.c')
Program('bar', ['bar1.c', 'bar2.c'])
</pre><p>
<span class="application">SCons</span> would then build the programs as follows:
</p><pre class="screen">% <strong class="userinput"><code>scons -Q</code></strong>
cc -o bar1.o -c bar1.c
cc -o bar2.o -c bar2.c
cc -o bar bar1.o bar2.o
cc -o foo.o -c foo.c
cc -o foo foo.o
</pre><p>
Notice that <span class="application">SCons</span> does not necessarily build the
programs in the same order in which you specify
them in the <code class="filename">SConstruct</code> file.
<span class="application">SCons</span> does, however, recognize that
the individual object files must be built
before the resulting program can be built.
We'll discuss this in greater detail in
the "Dependencies" section, below.
</p></div><div class="section" title="3.8.<2E>Sharing Source Files Between Multiple Programs"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idm562"></a>3.8.<2E>Sharing Source Files Between Multiple Programs</h2></div></div></div><p>
It's common to re-use code by sharing source files
between multiple programs.
One way to do this is to create a library
from the common source files,
which can then be linked into resulting programs.
(Creating libraries is discussed in
<a class="xref" href="#chap-libraries" title="Chapter<65>4.<2E>Building and Linking with Libraries">Chapter<EFBFBD>4, <i>Building and Linking with Libraries</i></a>, below.)
</p><p>
A more straightforward, but perhaps less convenient,
way to share source files between multiple programs
is simply to include the common files
in the lists of source files for each program:
</p><pre class="programlisting">
Program(Split('foo.c common1.c common2.c'))
Program('bar', Split('bar1.c bar2.c common1.c common2.c'))
</pre><p>
<span class="application">SCons</span> recognizes that the object files for
the <code class="filename">common1.c</code> and <code class="filename">common2.c</code> source files
each need to be built only once,
even though the resulting object files are
each linked in to both of the resulting executable programs:
</p><pre class="screen">% <strong class="userinput"><code>scons -Q</code></strong>
cc -o bar1.o -c bar1.c
cc -o bar2.o -c bar2.c
cc -o common1.o -c common1.c
cc -o common2.o -c common2.c
cc -o bar bar1.o bar2.o common1.o common2.o
cc -o foo.o -c foo.c
cc -o foo foo.o common1.o common2.o
</pre><p>
If two or more programs
share a lot of common source files,
repeating the common files in the list for each program
can be a maintenance problem when you need to change the
list of common files.
You can simplify this by creating a separate Python list
to hold the common file names,
and concatenating it with other lists
using the Python <code class="literal">+</code> operator:
</p><pre class="programlisting">
common = ['common1.c', 'common2.c']
foo_files = ['foo.c'] + common
bar_files = ['bar1.c', 'bar2.c'] + common
Program('foo', foo_files)
Program('bar', bar_files)
</pre><p>
This is functionally equivalent to the previous example.
</p></div><div class="section" title="3.9.<2E>Overriding construction variables when calling a Builder"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idm578"></a>3.9.<2E>Overriding construction variables when calling a Builder</h2></div></div></div><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="programlisting">
env.Program('hello', 'hello.c', LIBS=['gl', 'glut'])
</pre><p>
or generate a shared library with a non-standard suffix:
</p><pre class="programlisting">
env.SharedLibrary('word', 'word.cpp',
SHLIBSUFFIX='.ocx',
LIBSUFFIXES=['.ocx'])
</pre><p>
It is also possible to use the <code class="literal">parse_flags</code> keyword argument in an
override:
</p><p>
This example adds 'include' to <a class="link" href="#cv-CPPPATH"><code class="envar">$CPPPATH</code></a>,
'EBUG' to <a class="link" href="#cv-CPPDEFINES"><code class="envar">$CPPDEFINES</code></a>, and 'm' to <a class="link" href="#cv-LIBS"><code class="envar">$LIBS</code></a>.
</p><pre class="programlisting">
env = Program('hello', 'hello.c', parse_flags = '-Iinclude -DEBUG -lm')
</pre><p>
Within the call to the builder action the environment is not cloned,
instead an OverrideEnvironment() is created which is more
light weight than a whole Environment()
</p></div></div><div class="chapter" title="Chapter<65>4.<2E>Building and Linking with Libraries"><div class="titlepage"><div><div><h2 class="title"><a name="chap-libraries"></a>Chapter<EFBFBD>4.<2E>Building and Linking with Libraries</h2></div></div></div><p>
It's often useful to organize large software projects
by collecting parts of the software into one or more libraries.
<span class="application">SCons</span> makes it easy to create libraries
and to use them in the programs.
</p><div class="section" title="4.1.<2E>Building Libraries"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idm599"></a>4.1.<2E>Building Libraries</h2></div></div></div><p>
You build your own libraries by specifying <a class="link" href="#b-Library"><code class="function">Library</code></a>
instead of <a class="link" href="#b-Program"><code class="function">Program</code></a>:
</p><pre class="programlisting">
Library('foo', ['f1.c', 'f2.c', 'f3.c'])
</pre><p>
<span class="application">SCons</span> uses the appropriate library prefix and suffix for your system.
So on POSIX or Linux systems,
the above example would build as follows
(although <span class="application">ranlib</span> may not be called on all systems):
</p><pre class="screen">% <strong class="userinput"><code>scons -Q</code></strong>
cc -o f1.o -c f1.c
cc -o f2.o -c f2.c
cc -o f3.o -c f3.c
ar rc libfoo.a f1.o f2.o f3.o
ranlib libfoo.a
</pre><p>
On a Windows system,
a build of the above example would look like:
</p><pre class="screen">C:\&gt;<strong class="userinput"><code>scons -Q</code></strong>
cl /Fof1.obj /c f1.c /nologo
cl /Fof2.obj /c f2.c /nologo
cl /Fof3.obj /c f3.c /nologo
lib /nologo /OUT:foo.lib f1.obj f2.obj f3.obj
</pre><p>
The rules for the target name of the library
are similar to those for programs:
if you don't explicitly specify a target library name,
<span class="application">SCons</span> will deduce one from the
name of the first source file specified,
and <span class="application">SCons</span> will add an appropriate
file prefix and suffix if you leave them off.
</p><div class="section" title="4.1.1.<2E>Building Libraries From Source Code or Object Files"><div class="titlepage"><div><div><h3 class="title"><a name="idm618"></a>4.1.1.<2E>Building Libraries From Source Code or Object Files</h3></div></div></div><p>
The previous example shows building a library from a
list of source files.
You can, however, also give the <a class="link" href="#b-Library"><code class="function">Library</code></a> call
object files,
and it will correctly realize they are object files.
In fact, you can arbitrarily mix source code files
and object files in the source list:
</p><pre class="programlisting">
Library('foo', ['f1.c', 'f2.o', 'f3.c', 'f4.o'])
</pre><p>
And SCons realizes that only the source code files
must be compiled into object files
before creating the final library:
</p><pre class="screen">% <strong class="userinput"><code>scons -Q</code></strong>
cc -o f1.o -c f1.c
cc -o f3.o -c f3.c
ar rc libfoo.a f1.o f2.o f3.o f4.o
ranlib libfoo.a
</pre><p>
Of course, in this example, the object files
must already exist for the build to succeed.
See <a class="xref" href="#chap-nodes" title="Chapter<65>5.<2E>Node Objects">Chapter<EFBFBD>5, <i>Node Objects</i></a>, below,
for information about how you can
build object files explicitly
and include the built files in a library.
</p></div><div class="section" title="4.1.2.<2E>Building Static Libraries Explicitly: the StaticLibrary Builder"><div class="titlepage"><div><div><h3 class="title"><a name="idm629"></a>4.1.2.<2E>Building Static Libraries Explicitly: the <code class="function">StaticLibrary</code> Builder</h3></div></div></div><p>
The <a class="link" href="#b-Library"><code class="function">Library</code></a> function builds a traditional static library.
If you want to be explicit about the type of library being built,
you can use the synonym <a class="link" href="#b-StaticLibrary"><code class="function">StaticLibrary</code></a> function
instead of <code class="function">Library</code>:
</p><pre class="programlisting">
StaticLibrary('foo', ['f1.c', 'f2.c', 'f3.c'])
</pre><p>
There is no functional difference between the
<a class="link" href="#b-StaticLibrary"><code class="function">StaticLibrary</code></a> and <code class="function">Library</code> functions.
</p></div><div class="section" title="4.1.3.<2E>Building Shared (DLL) Libraries: the SharedLibrary Builder"><div class="titlepage"><div><div><h3 class="title"><a name="idm643"></a>4.1.3.<2E>Building Shared (DLL) Libraries: the <code class="function">SharedLibrary</code> Builder</h3></div></div></div><p>
If you want to build a shared library (on POSIX systems)
or a DLL file (on Windows systems),
you use the <a class="link" href="#b-SharedLibrary"><code class="function">SharedLibrary</code></a> function:
</p><pre class="programlisting">
SharedLibrary('foo', ['f1.c', 'f2.c', 'f3.c'])
</pre><p>
The output on POSIX:
</p><pre class="screen">% <strong class="userinput"><code>scons -Q</code></strong>
cc -o f1.os -c f1.c
cc -o f2.os -c f2.c
cc -o f3.os -c f3.c
cc -o libfoo.so -shared f1.os f2.os f3.os
</pre><p>
And the output on Windows:
</p><pre class="screen">C:\&gt;<strong class="userinput"><code>scons -Q</code></strong>
cl /Fof1.obj /c f1.c /nologo
cl /Fof2.obj /c f2.c /nologo
cl /Fof3.obj /c f3.c /nologo
link /nologo /dll /out:foo.dll /implib:foo.lib f1.obj f2.obj f3.obj
RegServerFunc(target, source, env)
embedManifestDllCheck(target, source, env)
</pre><p>
Notice again that <span class="application">SCons</span> takes care of
building the output file correctly,
adding the <code class="literal">-shared</code> option
for a POSIX compilation,
and the <code class="literal">/dll</code> option on Windows.
</p></div></div><div class="section" title="4.2.<2E>Linking with Libraries"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idm660"></a>4.2.<2E>Linking with Libraries</h2></div></div></div><p>
Usually, you build a library
because you want to link it with one or more programs.
You link libraries with a program by specifying
the libraries in the <a class="link" href="#cv-LIBS"><code class="envar">$LIBS</code></a> construction variable,
and by specifying the directory in which
the library will be found in the
<a class="link" href="#cv-LIBPATH"><code class="envar">$LIBPATH</code></a> construction variable:
</p><pre class="programlisting">
Library('foo', ['f1.c', 'f2.c', 'f3.c'])
Program('prog.c', LIBS=['foo', 'bar'], LIBPATH='.')
</pre><p>
Notice, of course, that you don't need to specify a library
prefix (like <code class="literal">lib</code>)
or suffix (like <code class="literal">.a</code> or <code class="literal">.lib</code>).
<span class="application">SCons</span> uses the correct prefix or suffix for the current system.
</p><p>
On a POSIX or Linux system,
a build of the above example would look like:
</p><pre class="screen">% <strong class="userinput"><code>scons -Q</code></strong>
cc -o f1.o -c f1.c
cc -o f2.o -c f2.c
cc -o f3.o -c f3.c
ar rc libfoo.a f1.o f2.o f3.o
ranlib libfoo.a
cc -o prog.o -c prog.c
cc -o prog prog.o -L. -lfoo -lbar
</pre><p>
On a Windows system,
a build of the above example would look like:
</p><pre class="screen">C:\&gt;<strong class="userinput"><code>scons -Q</code></strong>
cl /Fof1.obj /c f1.c /nologo
cl /Fof2.obj /c f2.c /nologo
cl /Fof3.obj /c f3.c /nologo
lib /nologo /OUT:foo.lib f1.obj f2.obj f3.obj
cl /Foprog.obj /c prog.c /nologo
link /nologo /OUT:prog.exe /LIBPATH:. foo.lib bar.lib prog.obj
embedManifestExeCheck(target, source, env)
</pre><p>
As usual, notice that <span class="application">SCons</span> has taken care
of constructing the correct command lines
to link with the specified library on each system.
</p><p>
Note also that,
if you only have a single library to link with,
you can specify the library name in single string,
instead of a Python list,
so that:
</p><pre class="programlisting">
Program('prog.c', LIBS='foo', LIBPATH='.')
</pre><p>
is equivalent to:
</p><pre class="programlisting">
Program('prog.c', LIBS=['foo'], LIBPATH='.')
</pre><p>
This is similar to the way that <span class="application">SCons</span>
handles either a string or a list to
specify a single source file.
</p></div><div class="section" title="4.3.<2E>Finding Libraries: the $LIBPATH Construction Variable"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idm687"></a>4.3.<2E>Finding Libraries: the <code class="envar">$LIBPATH</code> Construction Variable</h2></div></div></div><p>
By default, the linker will only look in
certain system-defined directories for libraries.
<span class="application">SCons</span> knows how to look for libraries
in directories that you specify with the
<a class="link" href="#cv-LIBPATH"><code class="envar">$LIBPATH</code></a> construction variable.
<code class="envar">$LIBPATH</code> consists of a list of
directory names, like so:
</p><pre class="programlisting">
Program('prog.c', LIBS = 'm',
LIBPATH = ['/usr/lib', '/usr/local/lib'])
</pre><p>
Using a Python list is preferred because it's portable
across systems. Alternatively, you could put all of
the directory names in a single string, separated by the
system-specific path separator character:
a colon on POSIX systems:
</p><pre class="programlisting">
LIBPATH = '/usr/lib:/usr/local/lib'
</pre><p>
or a semi-colon on Windows systems:
</p><pre class="programlisting">
LIBPATH = 'C:\\lib;D:\\lib'
</pre><p>
(Note that Python requires that the backslash
separators in a Windows path name
be escaped within strings.)
</p><p>
When the linker is executed,
<span class="application">SCons</span> will create appropriate flags
so that the linker will look for
libraries in the same directories as <span class="application">SCons</span>.
So on a POSIX or Linux system,
a build of the above example would look like:
</p><pre class="screen">% <strong class="userinput"><code>scons -Q</code></strong>
cc -o prog.o -c prog.c
cc -o prog prog.o -L/usr/lib -L/usr/local/lib -lm
</pre><p>
On a Windows system,
a build of the above example would look like:
</p><pre class="screen">C:\&gt;<strong class="userinput"><code>scons -Q</code></strong>
cl /Foprog.obj /c prog.c /nologo
link /nologo /OUT:prog.exe /LIBPATH:\usr\lib /LIBPATH:\usr\local\lib m.lib prog.obj
embedManifestExeCheck(target, source, env)
</pre><p>
Note again that <span class="application">SCons</span> has taken care of
the system-specific details of creating
the right command-line options.
</p></div></div><div class="chapter" title="Chapter<65>5.<2E>Node Objects"><div class="titlepage"><div><div><h2 class="title"><a name="chap-nodes"></a>Chapter<EFBFBD>5.<2E>Node Objects</h2></div></div></div><p>
Internally, <span class="application">SCons</span> represents all of the files
and directories it knows about as <code class="literal">Nodes</code>.
These internal objects
(not object <span class="emphasis"><em>files</em></span>)
can be used in a variety of ways
to make your <code class="filename">SConscript</code>
files portable and easy to read.
</p><div class="section" title="5.1.<2E>Builder Methods Return Lists of Target Nodes"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idm718"></a>5.1.<2E>Builder Methods Return Lists of Target Nodes</h2></div></div></div><p>
All builder methods return a list of
<code class="classname">Node</code> objects that identify the
target file or files that will be built.
These returned <code class="literal">Nodes</code> can be passed
as arguments to other builder methods.
</p><p>
For example, suppose that we want to build
the two object files that make up a program with different options.
This would mean calling the <a class="link" href="#b-Object"><code class="function">Object</code></a>
builder once for each object file,
specifying the desired options:
</p><pre class="programlisting">
Object('hello.c', CCFLAGS='-DHELLO')
Object('goodbye.c', CCFLAGS='-DGOODBYE')
</pre><p>
One way to combine these object files
into the resulting program
would be to call the <a class="link" href="#b-Program"><code class="function">Program</code></a>
builder with the names of the object files
listed as sources:
</p><pre class="programlisting">
Object('hello.c', CCFLAGS='-DHELLO')
Object('goodbye.c', CCFLAGS='-DGOODBYE')
Program(['hello.o', 'goodbye.o'])
</pre><p>
The problem with specifying the names as strings
is that our <code class="filename">SConstruct</code> file is no longer portable
across operating systems.
It won't, for example, work on Windows
because the object files there would be
named <code class="filename">hello.obj</code> and <code class="filename">goodbye.obj</code>,
not <code class="filename">hello.o</code> and <code class="filename">goodbye.o</code>.
</p><p>
A better solution is to assign the lists of targets
returned by the calls to the <code class="function">Object</code> builder to variables,
which we can then concatenate in our
call to the <code class="function">Program</code> builder:
</p><pre class="programlisting">
hello_list = Object('hello.c', CCFLAGS='-DHELLO')
goodbye_list = Object('goodbye.c', CCFLAGS='-DGOODBYE')
Program(hello_list + goodbye_list)
</pre><p>
This makes our <code class="filename">SConstruct</code> file portable again,
the build output on Linux looking like:
</p><pre class="screen">% <strong class="userinput"><code>scons -Q</code></strong>
cc -o goodbye.o -c -DGOODBYE goodbye.c
cc -o hello.o -c -DHELLO hello.c
cc -o hello hello.o goodbye.o
</pre><p>
And on Windows:
</p><pre class="screen">C:\&gt;<strong class="userinput"><code>scons -Q</code></strong>
cl /Fogoodbye.obj /c goodbye.c -DGOODBYE
cl /Fohello.obj /c hello.c -DHELLO
link /nologo /OUT:hello.exe hello.obj goodbye.obj
embedManifestExeCheck(target, source, env)
</pre><p>
We'll see examples of using the list of nodes
returned by builder methods throughout
the rest of this guide.
</p></div><div class="section" title="5.2.<2E>Explicitly Creating File and Directory Nodes"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idm749"></a>5.2.<2E>Explicitly Creating File and Directory Nodes</h2></div></div></div><p>
It's worth mentioning here that
<span class="application">SCons</span> maintains a clear distinction
between Nodes that represent files
and Nodes that represent directories.
<span class="application">SCons</span> supports <code class="function">File</code> and <code class="function">Dir</code>
functions that, respectively,
return a file or directory Node:
</p><pre class="programlisting">
hello_c = File('hello.c')
Program(hello_c)
classes = Dir('classes')
Java(classes, 'src')
</pre><p>
Normally, you don't need to call
<code class="function">File</code> or <code class="function">Dir</code> directly,
because calling a builder method automatically
treats strings as the names of files or directories,
and translates them into
the Node objects for you.
The <code class="function">File</code> and <code class="function">Dir</code> functions can come in handy
in situations where you need to explicitly
instruct <span class="application">SCons</span> about the type of Node being
passed to a builder or other function,
or unambiguously refer to a specific
file in a directory tree.
</p><p>
There are also times when you may need to
refer to an entry in a file system
without knowing in advance
whether it's a file or a directory.
For those situations,
<span class="application">SCons</span> also supports an <code class="function">Entry</code> function,
which returns a Node
that can represent either a file or a directory.
</p><pre class="programlisting">
xyzzy = Entry('xyzzy')
</pre><p>
The returned <code class="literal">xyzzy</code> Node
will be turned into a file or directory Node
the first time it is used by a builder method
or other function that
requires one vs. the other.
</p></div><div class="section" title="5.3.<2E>Printing Node File Names"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idm769"></a>5.3.<2E>Printing <code class="classname">Node</code> File Names</h2></div></div></div><p>
One of the most common things you can do
with a Node is use it to print the
file name that the node represents.
Keep in mind, though, that because the object
returned by a builder call
is a <span class="emphasis"><em>list</em></span> of Nodes,
you must use Python subscripts
to fetch individual Nodes from the list.
For example, the following <code class="filename">SConstruct</code> file:
</p><pre class="programlisting">
object_list = Object('hello.c')
program_list = Program(object_list)
print("The object file is: %s"%object_list[0])
print("The program file is: %s"%program_list[0])
</pre><p>
Would print the following file names on a POSIX system:
</p><pre class="screen">% <strong class="userinput"><code>scons -Q</code></strong>
The object file is: hello.o
The program file is: hello
cc -o hello.o -c hello.c
cc -o hello hello.o
</pre><p>
And the following file names on a Windows system:
</p><pre class="screen">C:\&gt;<strong class="userinput"><code>scons -Q</code></strong>
The object file is: hello.obj
The program file is: hello.exe
cl /Fohello.obj /c hello.c /nologo
link /nologo /OUT:hello.exe hello.obj
embedManifestExeCheck(target, source, env)
</pre><p>
Note that in the above example,
the <code class="literal">object_list[0]</code>
extracts an actual Node <span class="emphasis"><em>object</em></span>
from the list,
and the Python <code class="literal">print</code> statement
converts the object to a string for printing.
</p></div><div class="section" title="5.4.<2E>Using a Node's File Name as a String"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idm786"></a>5.4.<2E>Using a <code class="classname">Node</code>'s File Name as a String</h2></div></div></div><p>
Printing a <code class="classname">Node</code>'s name
as described in the previous section
works because the string representation of a <code class="classname">Node</code> object
is the name of the file.
If you want to do something other than
print the name of the file,
you can fetch it by using the builtin Python
<code class="function">str</code> function.
For example, if you want to use the Python
<code class="function">os.path.exists</code>
to figure out whether a file
exists while the <code class="filename">SConstruct</code> file
is being read and executed,
you can fetch the string as follows:
</p><pre class="programlisting">
import os.path
program_list = Program('hello.c')
program_name = str(program_list[0])
if not os.path.exists(program_name):
print("%s does not exist!"%program_name)
</pre><p>
Which executes as follows on a POSIX system:
</p><pre class="screen">% <strong class="userinput"><code>scons -Q</code></strong>
hello does not exist!
cc -o hello.o -c hello.c
cc -o hello hello.o
</pre></div><div class="section" title="5.5.<2E>GetBuildPath: Getting the Path From a Node or String"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idm799"></a>5.5.<2E><code class="function">GetBuildPath</code>: Getting the Path From a <code class="classname">Node</code> or String</h2></div></div></div><p>
<code class="function">env.GetBuildPath(file_or_list)</code>
returns the path of a <code class="classname">Node</code> or a string representing a
path. It can also take a list of <code class="classname">Node</code>s and/or strings, and
returns the list of paths. If passed a single <code class="classname">Node</code>, the result
is the same as calling <code class="literal">str(node)</code> (see above).
The string(s) can have embedded construction variables, which are
expanded as usual, using the calling environment's set of
variables. The paths can be files or directories, and do not have
to exist.
</p><pre class="programlisting">
env=Environment(VAR="value")
n=File("foo.c")
print(env.GetBuildPath([n, "sub/dir/$VAR"]))
</pre><p>
Would print the following file names:
</p><pre class="screen">% <strong class="userinput"><code>scons -Q</code></strong>
['foo.c', 'sub/dir/value']
scons: `.' is up to date.
</pre><p>
There is also a function version of <code class="function">GetBuildPath</code> which can
be called without an <code class="function">Environment</code>; that uses the default SCons
<code class="function">Environment</code> to do substitution on any string arguments.
</p></div></div><div class="chapter" title="Chapter<65>6.<2E>Dependencies"><div class="titlepage"><div><div><h2 class="title"><a name="chap-depends"></a>Chapter<EFBFBD>6.<2E>Dependencies</h2></div></div></div><p>
So far we've seen how <span class="application">SCons</span> handles one-time builds.
But one of the main functions of a build tool like <span class="application">SCons</span>
is to rebuild only what is necessary
when source files change--or, put another way,
<span class="application">SCons</span> should <span class="emphasis"><em>not</em></span>
waste time rebuilding things that don't need to be rebuilt.
You can see this at work simply by re-invoking <span class="application">SCons</span>
after building our simple <code class="filename">hello</code> example:
</p><pre class="screen">% <strong class="userinput"><code>scons -Q</code></strong>
cc -o hello.o -c hello.c
cc -o hello hello.o
% <strong class="userinput"><code>scons -Q</code></strong>
scons: `.' is up to date.
</pre><p>
The second time it is executed,
<span class="application">SCons</span> realizes that the <code class="filename">hello</code> program
is up-to-date with respect to the current <code class="filename">hello.c</code> source file,
and avoids rebuilding it.
You can see this more clearly by naming
the <code class="filename">hello</code> program explicitly on the command line:
</p><pre class="screen">% <strong class="userinput"><code>scons -Q hello</code></strong>
cc -o hello.o -c hello.c
cc -o hello hello.o
% <strong class="userinput"><code>scons -Q hello</code></strong>
scons: `hello' is up to date.
</pre><p>
Note that <span class="application">SCons</span> reports <code class="literal">"...is up to date"</code>
only for target files named explicitly on the command line,
to avoid cluttering the output.
</p><div class="section" title="6.1.<2E>Deciding When an Input File Has Changed: the Decider Function"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idm840"></a>6.1.<2E>Deciding When an Input File Has Changed: the <code class="function">Decider</code> Function</h2></div></div></div><p>
Another aspect of avoiding unnecessary rebuilds
is the fundamental build tool behavior
of <span class="emphasis"><em>rebuilding</em></span>
things when an input file changes,
so that the built software is up to date.
By default,
<span class="application">SCons</span> keeps track of this through an
MD5 <code class="literal">signature</code>, or checksum, of the contents of each file,
although you can easily configure
<span class="application">SCons</span> to use the
modification times (or time stamps)
instead.
You can even specify your own Python function
for deciding if an input file has changed.
</p><div class="section" title="6.1.1.<2E>Using MD5 Signatures to Decide if a File Has Changed"><div class="titlepage"><div><div><h3 class="title"><a name="idm848"></a>6.1.1.<2E>Using MD5 Signatures to Decide if a File Has Changed</h3></div></div></div><p>
By default,
<span class="application">SCons</span> keeps track of whether a file has changed
based on an MD5 checksum of the file's contents,
not the file's modification time.
This means that you may be surprised by the
default <span class="application">SCons</span> behavior if you are used to the
<span class="application">Make</span> convention of forcing
a rebuild by updating the file's modification time
(using the <span class="application">touch</span> command, for example):
</p><pre class="screen">% <strong class="userinput"><code>scons -Q hello</code></strong>
cc -o hello.o -c hello.c
cc -o hello hello.o
% <strong class="userinput"><code>touch hello.c</code></strong>
% <strong class="userinput"><code>scons -Q hello</code></strong>
scons: `hello' is up to date.
</pre><p>
Even though the file's modification time has changed,
<span class="application">SCons</span> realizes that the contents of the
<code class="filename">hello.c</code> file have <span class="emphasis"><em>not</em></span> changed,
and therefore that the <code class="filename">hello</code> program
need not be rebuilt.
This avoids unnecessary rebuilds when,
for example, someone rewrites the
contents of a file without making a change.
But if the contents of the file really do change,
then <span class="application">SCons</span> detects the change
and rebuilds the program as required:
</p><pre class="screen">% <strong class="userinput"><code>scons -Q hello</code></strong>
cc -o hello.o -c hello.c
cc -o hello hello.o
% [CHANGE THE CONTENTS OF hello.c]
% <strong class="userinput"><code>scons -Q hello</code></strong>
cc -o hello.o -c hello.c
cc -o hello hello.o
</pre><p>
Note that you can, if you wish,
specify this default behavior
(MD5 signatures) explicitly
using the <code class="function">Decider</code> function as follows:
</p><pre class="programlisting">
Program('hello.c')
Decider('MD5')
</pre><p>
You can also use the string <code class="literal">'content'</code>
as a synonym for <code class="literal">'MD5'</code>
when calling the <code class="function">Decider</code> function.
</p><div class="section" title="6.1.1.1.<2E>Ramifications of Using MD5 Signatures"><div class="titlepage"><div><div><h4 class="title"><a name="idm875"></a>6.1.1.1.<2E>Ramifications of Using MD5 Signatures</h4></div></div></div><p>
Using MD5 signatures to decide if an input file has changed
has one surprising benefit:
if a source file has been changed
in such a way that the contents of the
rebuilt target file(s)
will be exactly the same as the last time
the file was built,
then any "downstream" target files
that depend on the rebuilt-but-not-changed target
file actually need not be rebuilt.
</p><p>
So if, for example,
a user were to only change a comment in a <code class="filename">hello.c</code> file,
then the rebuilt <code class="filename">hello.o</code> file
would be exactly the same as the one previously built
(assuming the compiler doesn't put any build-specific
information in the object file).
<span class="application">SCons</span> would then realize that it would not
need to rebuild the <code class="filename">hello</code> program as follows:
</p><pre class="screen">% <strong class="userinput"><code>scons -Q hello</code></strong>
cc -o hello.o -c hello.c
cc -o hello hello.o
% [CHANGE A COMMENT IN hello.c]
% <strong class="userinput"><code>scons -Q hello</code></strong>
cc -o hello.o -c hello.c
scons: `hello' is up to date.
</pre><p>
In essence, <span class="application">SCons</span>
"short-circuits" any dependent builds
when it realizes that a target file
has been rebuilt to exactly the same file as the last build.
This does take some extra processing time
to read the contents of the target (<code class="filename">hello.o</code>) file,
but often saves time when the rebuild that was avoided
would have been time-consuming and expensive.
</p></div></div><div class="section" title="6.1.2.<2E>Using Time Stamps to Decide If a File Has Changed"><div class="titlepage"><div><div><h3 class="title"><a name="idm889"></a>6.1.2.<2E>Using Time Stamps to Decide If a File Has Changed</h3></div></div></div><p>
If you prefer, you can
configure <span class="application">SCons</span> to use the modification time
of a file, not the file contents,
when deciding if a target needs to be rebuilt.
<span class="application">SCons</span> gives you two ways to use time stamps
to decide if an input file has changed
since the last time a target has been built.
</p><p>
The most familiar way to use time stamps
is the way <span class="application">Make</span> does:
that is, have <span class="application">SCons</span> decide
that a target must be rebuilt
if a source file's modification time is
<span class="emphasis"><em>newer</em></span>
than the target file.
To do this, call the <code class="function">Decider</code>
function as follows:
</p><pre class="programlisting">
Object('hello.c')
Decider('timestamp-newer')
</pre><p>
This makes <span class="application">SCons</span> act like <span class="application">Make</span>
when a file's modification time is updated
(using the <span class="application">touch</span> command, for example):
</p><pre class="screen">% <strong class="userinput"><code>scons -Q hello.o</code></strong>
cc -o hello.o -c hello.c
% <strong class="userinput"><code>touch hello.c</code></strong>
% <strong class="userinput"><code>scons -Q hello.o</code></strong>
cc -o hello.o -c hello.c
</pre><p>
And, in fact, because this behavior is the same
as the behavior of <span class="application">Make</span>,
you can also use the string <code class="literal">'make'</code>
as a synonym for <code class="literal">'timestamp-newer'</code>
when calling the <code class="function">Decider</code> function:
</p><pre class="programlisting">
Object('hello.c')
Decider('make')
</pre><p>
One drawback to using times stamps exactly like <span class="application">Make</span>
is that if an input file's modification time suddenly
becomes <span class="emphasis"><em>older</em></span> than a target file,
the target file will not be rebuilt.
This can happen if an old copy of a source file is restored
from a backup archive, for example.
The contents of the restored file will likely be different
than they were the last time a dependent target was built,
but the target won't be rebuilt
because the modification time of the source file
is not newer than the target.
</p><p>
Because <span class="application">SCons</span> actually stores information
about the source files' time stamps whenever a target is built,
it can handle this situation by checking for
an exact match of the source file time stamp,
instead of just whether or not the source file
is newer than the target file.
To do this, specify the argument
<code class="literal">'timestamp-match'</code>
when calling the <code class="function">Decider</code> function:
</p><pre class="programlisting">
Object('hello.c')
Decider('timestamp-match')
</pre><p>
When configured this way,
<span class="application">SCons</span> will rebuild a target whenever
a source file's modification time has changed.
So if we use the <code class="literal">touch -t</code>
option to change the modification time of
<code class="filename">hello.c</code> to an old date (January 1, 1989),
<span class="application">SCons</span> will still rebuild the target file:
</p><pre class="screen">% <strong class="userinput"><code>scons -Q hello.o</code></strong>
cc -o hello.o -c hello.c
% <strong class="userinput"><code>touch -t 198901010000 hello.c</code></strong>
% <strong class="userinput"><code>scons -Q hello.o</code></strong>
cc -o hello.o -c hello.c
</pre><p>
In general, the only reason to prefer
<code class="literal">timestamp-newer</code>
instead of
<code class="literal">timestamp-match</code>,
would be if you have some specific reason
to require this <span class="application">Make</span>-like behavior of
not rebuilding a target when an otherwise-modified
source file is older.
</p></div><div class="section" title="6.1.3.<2E>Deciding If a File Has Changed Using Both MD Signatures and Time Stamps"><div class="titlepage"><div><div><h3 class="title"><a name="idm935"></a>6.1.3.<2E>Deciding If a File Has Changed Using Both MD Signatures and Time Stamps</h3></div></div></div><p>
As a performance enhancement,
<span class="application">SCons</span> provides a way to use
MD5 checksums of file contents
but to read those contents
only when the file's timestamp has changed.
To do this, call the <code class="function">Decider</code>
function with <code class="literal">'MD5-timestamp'</code>
argument as follows:
</p><pre class="programlisting">
Program('hello.c')
Decider('MD5-timestamp')
</pre><p>
So configured, <span class="application">SCons</span> will still behave like
it does when using <code class="literal">Decider('MD5')</code>:
</p><pre class="screen">
% <strong class="userinput"><code>scons -Q hello</code></strong>
cc -o hello.o -c hello.c
cc -o hello hello.o
% <strong class="userinput"><code>touch hello.c</code></strong>
% <strong class="userinput"><code>scons -Q hello</code></strong>
scons: `hello' is up to date.
% <strong class="userinput"><code>edit hello.c</code></strong>
[CHANGE THE CONTENTS OF hello.c]
% <strong class="userinput"><code>scons -Q hello</code></strong>
cc -o hello.o -c hello.c
cc -o hello hello.o
</pre><p>
However, the second call to <span class="application">SCons</span> in the above output,
when the build is up-to-date,
will have been performed by simply looking at the
modification time of the <code class="filename">hello.c</code> file,
not by opening it and performing
an MD5 checksum calcuation on its contents.
This can significantly speed up many up-to-date builds.
</p><p>
The only drawback to using
<code class="literal">Decider('MD5-timestamp')</code>
is that <span class="application">SCons</span> will <span class="emphasis"><em>not</em></span>
rebuild a target file if a source file was modified
within one second of the last time <span class="application">SCons</span> built the file.
While most developers are programming,
this isn't a problem in practice,
since it's unlikely that someone will have built
and then thought quickly enough to make a substantive
change to a source file within one second.
Certain build scripts or
continuous integration tools may, however,
rely on the ability to apply changes to files
automatically and then rebuild as quickly as possible,
in which case use of
<code class="literal">Decider('MD5-timestamp')</code>
may not be appropriate.
</p></div><div class="section" title="6.1.4.<2E>Writing Your Own Custom Decider Function"><div class="titlepage"><div><div><h3 class="title"><a name="idm960"></a>6.1.4.<2E>Writing Your Own Custom <code class="function">Decider</code> Function</h3></div></div></div><p>
The different string values that we've passed to
the <code class="function">Decider</code> function are essentially used by <span class="application">SCons</span>
to pick one of several specific internal functions
that implement various ways of deciding if a dependency
(usually a source file)
has changed since a target file has been built.
As it turns out,
you can also supply your own function
to decide if a dependency has changed.
</p><p>
For example, suppose we have an input file
that contains a lot of data,
in some specific regular format,
that is used to rebuild a lot of different target files,
but each target file really only depends on
one particular section of the input file.
We'd like to have each target file depend on
only its section of the input file.
However, since the input file may contain a lot of data,
we want to open the input file only if its timestamp has changed.
This could be done with a custom
<code class="function">Decider</code> function that might look something like this:
</p><pre class="programlisting">
Program('hello.c')
def decide_if_changed(dependency, target, prev_ni):
if dependency.get_timestamp() != prev_ni.timestamp:
dep = str(dependency)
tgt = str(target)
if specific_part_of_file_has_changed(dep, tgt):
return True
return False
Decider(decide_if_changed)
</pre><p>
Note that in the function definition,
the <code class="varname">dependency</code>
(input file) is the first argument,
and then the <code class="varname">target</code>.
Both of these are passed to the functions as
SCons <code class="classname">Node</code> objects,
which we convert to strings using the Python
<code class="function">str()</code>.
</p><p>
The third argument, <code class="varname">prev_ni</code>,
is an object that holds the
signature or timestamp information
that was recorded about the dependency
the last time the target was built.
A <code class="varname">prev_ni</code> object can hold
different information,
depending on the type of thing that the
<code class="varname">dependency</code> argument represents.
For normal files,
the <code class="varname">prev_ni</code> object
has the following attributes:
</p><div class="variablelist"><dl><dt><span class="term">.csig</span></dt><dd><p>
The <span class="emphasis"><em>content signature</em></span>,
or MD5 checksum, of the contents of the
<code class="varname">dependency</code>
file the last time the <code class="varname">target</code> was built.
</p></dd><dt><span class="term">.size</span></dt><dd><p>
The size in bytes of the <code class="varname">dependency</code>
file the last time the target was built.
</p></dd><dt><span class="term">.timestamp</span></dt><dd><p>
The modification time of the <code class="varname">dependency</code>
file the last time the <code class="varname">target</code> was built.
</p></dd></dl></div><p>
Note that ignoring some of the arguments
in your custom <code class="function">Decider</code> function
is a perfectly normal thing to do,
if they don't impact the way you want to
decide if the dependency file has changed.
</p><p>
Another thing to look out for is the fact that the three
attributes above may not be present at the time of the first run.
Without any prior build, no targets have been created and no
<code class="filename">.sconsign</code> DB file exists yet.
So, you should always check whether the
<code class="varname">prev_ni</code> attribute in question is available.
</p><p>
We finally present a small example for a
<code class="varname">csig</code>-based decider function. Note how the
signature information for the <code class="varname">dependency</code> file
has to get initialized via <code class="function">get_csig</code>
during each function call (this is mandatory!).
</p><pre class="programlisting">
env = Environment()
def config_file_decider(dependency, target, prev_ni):
import os.path
# We always have to init the .csig value...
dep_csig = dependency.get_csig()
# .csig may not exist, because no target was built yet...
if 'csig' not in dir(prev_ni):
return True
# Target file may not exist yet
if not os.path.exists(str(target.abspath)):
return True
if dep_csig != prev_ni.csig:
# Some change on source file =&gt; update installed one
return True
return False
def update_file():
f = open("test.txt","a")
f.write("some line\n")
f.close()
update_file()
# Activate our own decider function
env.Decider(config_file_decider)
env.Install("install","test.txt")
</pre></div><div class="section" title="6.1.5.<2E>Mixing Different Ways of Deciding If a File Has Changed"><div class="titlepage"><div><div><h3 class="title"><a name="idm1008"></a>6.1.5.<2E>Mixing Different Ways of Deciding If a File Has Changed</h3></div></div></div><p>
The previous examples have all demonstrated calling
the global <code class="function">Decider</code> function
to configure all dependency decisions that <span class="application">SCons</span> makes.
Sometimes, however, you want to be able to configure
different decision-making for different targets.
When that's necessary, you can use the
<code class="function">env.Decider</code>
method to affect only the configuration
decisions for targets built with a
specific construction environment.
</p><p>
For example, if we arbitrarily want to build
one program using MD5 checkums
and another using file modification times
from the same source
we might configure it this way:
</p><pre class="programlisting">
env1 = Environment(CPPPATH = ['.'])
env2 = env1.Clone()
env2.Decider('timestamp-match')
env1.Program('prog-MD5', 'program1.c')
env2.Program('prog-timestamp', 'program2.c')
</pre><p>
If both of the programs include the same
<code class="filename">inc.h</code> file,
then updating the modification time of
<code class="filename">inc.h</code>
(using the <span class="application">touch</span> command)
will cause only <code class="filename">prog-timestamp</code>
to be rebuilt:
</p><pre class="screen">% <strong class="userinput"><code>scons -Q</code></strong>
cc -o program1.o -c -I. program1.c
cc -o prog-MD5 program1.o
cc -o program2.o -c -I. program2.c
cc -o prog-timestamp program2.o
% <strong class="userinput"><code>touch inc.h</code></strong>
% <strong class="userinput"><code>scons -Q</code></strong>
cc -o program2.o -c -I. program2.c
cc -o prog-timestamp program2.o
</pre></div></div><div class="section" title="6.2.<2E>Older Functions for Deciding When an Input File Has Changed"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idm1025"></a>6.2.<2E>Older Functions for Deciding When an Input File Has Changed</h2></div></div></div><p>
<span class="application">SCons</span> still supports two functions that used to be the
primary methods for configuring the
decision about whether or not an input file has changed.
These functions have been officially deprecated
as <span class="application">SCons</span> version 2.0,
and their use is discouraged,
mainly because they rely on a somewhat
confusing distinction between how
source files and target files are handled.
These functions are documented here mainly in case you
encounter them in older <code class="filename">SConscript</code> files.
</p><div class="section" title="6.2.1.<2E>The SourceSignatures Function"><div class="titlepage"><div><div><h3 class="title"><a name="idm1031"></a>6.2.1.<2E>The <code class="function">SourceSignatures</code> Function</h3></div></div></div><p>
The <code class="function">SourceSignatures</code> function is fairly straightforward,
and supports two different argument values
to configure whether source file changes should be decided
using MD5 signatures:
</p><pre class="programlisting">
Program('hello.c')
SourceSignatures('MD5')
</pre><p>
Or using time stamps:
</p><pre class="programlisting">
Program('hello.c')
SourceSignatures('timestamp')
</pre><p>
These are roughly equivalent to specifying
<code class="function">Decider('MD5')</code>
or
<code class="function">Decider('timestamp-match')</code>,
respectively,
although it only affects how SCons makes
decisions about dependencies on
<span class="emphasis"><em>source</em></span> files--that is,
files that are not built from any other files.
</p></div><div class="section" title="6.2.2.<2E>The TargetSignatures Function"><div class="titlepage"><div><div><h3 class="title"><a name="idm1043"></a>6.2.2.<2E>The <code class="function">TargetSignatures</code> Function</h3></div></div></div><p>
The <code class="function">TargetSignatures</code> function
specifies how <span class="application">SCons</span> decides
when a target file has changed
<span class="emphasis"><em>when it is used as a
dependency of (input to) another target</em></span>--that is,
the <code class="function">TargetSignatures</code> function configures
how the signatures of "intermediate" target files
are used when deciding if a "downstream" target file
must be rebuilt.
<sup>[<a name="idm1051" href="#ftn.idm1051" class="footnote">2</a>]</sup>
</p><p>
The <code class="function">TargetSignatures</code> function supports the same
<code class="literal">'MD5'</code> and <code class="literal">'timestamp'</code>
argument values that are supported by the <code class="function">SourceSignatures</code>,
with the same meanings, but applied to target files.
That is, in the example:
</p><pre class="programlisting">
Program('hello.c')
TargetSignatures('MD5')
</pre><p>
The MD5 checksum of the <code class="filename">hello.o</code> target file
will be used to decide if it has changed since the last
time the "downstream" <code class="filename">hello</code> target file was built.
And in the example:
</p><pre class="programlisting">
Program('hello.c')
TargetSignatures('timestamp')
</pre><p>
The modification time of the <code class="filename">hello.o</code> target file
will be used to decide if it has changed since the last
time the "downstream" <code class="filename">hello</code> target file was built.
</p><p>
The <code class="function">TargetSignatures</code> function supports
two additional argument values:
<code class="literal">'source'</code> and <code class="literal">'build'</code>.
The <code class="literal">'source'</code> argument
specifies that decisions involving
whether target files have changed
since a previous build
should use the same behavior
for the decisions configured for source files
(using the <code class="function">SourceSignatures</code> function).
So in the example:
</p><pre class="programlisting">
Program('hello.c')
TargetSignatures('source')
SourceSignatures('timestamp')
</pre><p>
All files, both targets and sources,
will use modification times
when deciding if an input file
has changed since the last
time a target was built.
</p><p>
Lastly, the <code class="literal">'build'</code> argument
specifies that <span class="application">SCons</span> should examine
the build status of a target file
and always rebuild a "downstream" target
if the target file was itself rebuilt,
without re-examining the contents or timestamp
of the newly-built target file.
If the target file was not rebuilt during
this <code class="filename">scons</code> invocation,
then the target file will be examined
the same way as configured by
the <code class="function">SourceSignature</code> call
to decide if it has changed.
</p><p>
This mimics the behavior of
<code class="literal">build signatures</code>
in earlier versions of <span class="application">SCons</span>.
A <code class="literal">build signature</code> re-combined
signatures of all the input files
that went into making the target file,
so that the target file itself
did not need to have its contents read
to compute an MD5 signature.
This can improve performance for some configurations,
but is generally not as effective as using
<code class="literal">Decider('MD5-timestamp')</code>.
</p></div></div><div class="section" title="6.3.<2E>Implicit Dependencies: The $CPPPATH Construction Variable"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idm1088"></a>6.3.<2E>Implicit Dependencies: The <code class="envar">$CPPPATH</code> Construction Variable</h2></div></div></div><p>
Now suppose that our "Hello, World!" program
actually has an <code class="literal">#include</code> line
to include the <code class="filename">hello.h</code> file in the compilation:
</p><pre class="programlisting">
#include &lt;hello.h&gt;
int
main()
{
printf("Hello, %s!\n", string);
}
</pre><p>
And, for completeness, the <code class="filename">hello.h</code> file looks like this:
</p><pre class="programlisting">
#define string "world"
</pre><p>
In this case, we want <span class="application">SCons</span> to recognize that,
if the contents of the <code class="filename">hello.h</code> file change,
the <code class="filename">hello</code> program must be recompiled.
To do this, we need to modify the
<code class="filename">SConstruct</code> file like so:
</p><pre class="programlisting">
Program('hello.c', CPPPATH = '.')
</pre><p>
The <a class="link" href="#cv-CPPPATH"><code class="envar">$CPPPATH</code></a> value
tells <span class="application">SCons</span> to look in the current directory
(<code class="literal">'.'</code>)
for any files included by C source files
(<code class="filename">.c</code> or <code class="filename">.h</code> files).
With this assignment in the <code class="filename">SConstruct</code> file:
</p><pre class="screen">% <strong class="userinput"><code>scons -Q hello</code></strong>
cc -o hello.o -c -I. hello.c
cc -o hello hello.o
% <strong class="userinput"><code>scons -Q hello</code></strong>
scons: `hello' is up to date.
% [CHANGE THE CONTENTS OF hello.h]
% <strong class="userinput"><code>scons -Q hello</code></strong>
cc -o hello.o -c -I. hello.c
cc -o hello hello.o
</pre><p>
First, notice that <span class="application">SCons</span>
added the <code class="literal">-I.</code> argument
from the <code class="envar">$CPPPATH</code> variable
so that the compilation would find the
<code class="filename">hello.h</code> file in the local directory.
</p><p>
Second, realize that <span class="application">SCons</span> knows that the <code class="filename">hello</code>
program must be rebuilt
because it scans the contents of
the <code class="filename">hello.c</code> file
for the <code class="literal">#include</code> lines that indicate
another file is being included in the compilation.
<span class="application">SCons</span> records these as
<span class="emphasis"><em>implicit dependencies</em></span>
of the target file,
Consequently,
when the <code class="filename">hello.h</code> file changes,
<span class="application">SCons</span> realizes that the <code class="filename">hello.c</code> file includes it,
and rebuilds the resulting <code class="filename">hello</code> program
that depends on both the <code class="filename">hello.c</code> and <code class="filename">hello.h</code> files.
</p><p>
Like the <a class="link" href="#cv-LIBPATH"><code class="envar">$LIBPATH</code></a> variable,
the <code class="envar">$CPPPATH</code> variable
may be a list of directories,
or a string separated by
the system-specific path separation character
(':' on POSIX/Linux, ';' on Windows).
Either way, <span class="application">SCons</span> creates the
right command-line options
so that the following example:
</p><pre class="programlisting">
Program('hello.c', CPPPATH = ['include', '/home/project/inc'])
</pre><p>
Will look like this on POSIX or Linux:
</p><pre class="screen">% <strong class="userinput"><code>scons -Q hello</code></strong>
cc -o hello.o -c -Iinclude -I/home/project/inc hello.c
cc -o hello hello.o
</pre><p>
And like this on Windows:
</p><pre class="screen">C:\&gt;<strong class="userinput"><code>scons -Q hello.exe</code></strong>
cl /Fohello.obj /c hello.c /nologo /Iinclude /I\home\project\inc
link /nologo /OUT:hello.exe hello.obj
embedManifestExeCheck(target, source, env)
</pre></div><div class="section" title="6.4.<2E>Caching Implicit Dependencies"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idm1146"></a>6.4.<2E>Caching Implicit Dependencies</h2></div></div></div><p>
Scanning each file for <code class="literal">#include</code> lines
does take some extra processing time.
When you're doing a full build of a large system,
the scanning time is usually a very small percentage
of the overall time spent on the build.
You're most likely to notice the scanning time,
however, when you <span class="emphasis"><em>rebuild</em></span>
all or part of a large system:
<span class="application">SCons</span> will likely take some extra time to "think about"
what must be built before it issues the
first build command
(or decides that everything is up to date
and nothing must be rebuilt).
</p><p>
In practice, having <span class="application">SCons</span> scan files saves time
relative to the amount of potential time
lost to tracking down subtle problems
introduced by incorrect dependencies.
Nevertheless, the "waiting time"
while <span class="application">SCons</span> scans files can annoy
individual developers waiting for their builds to finish.
Consequently, <span class="application">SCons</span> lets you cache
the implicit dependencies
that its scanners find,
for use by later builds.
You can do this by specifying the
<code class="literal">--implicit-cache</code> option on the command line:
</p><pre class="screen">% <strong class="userinput"><code>scons -Q --implicit-cache hello</code></strong>
cc -o hello.o -c hello.c
cc -o hello hello.o
% <strong class="userinput"><code>scons -Q hello</code></strong>
scons: `hello' is up to date.
</pre><p>
If you don't want to specify <code class="literal">--implicit-cache</code>
on the command line each time,
you can make it the default behavior for your build
by setting the <code class="literal">implicit_cache</code> option
in an <code class="filename">SConscript</code> file:
</p><pre class="programlisting">
SetOption('implicit_cache', 1)
</pre><p>
<span class="application">SCons</span> does not cache implicit dependencies like this by default
because the <code class="literal">--implicit-cache</code> causes <span class="application">SCons</span> to simply use the implicit
dependencies stored during the last run, without any checking
for whether or not those dependencies are still correct.
Specifically, this means <code class="literal">--implicit-cache</code> instructs <span class="application">SCons</span>
to <span class="emphasis"><em>not</em></span> rebuild "correctly" in the
following cases:
</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>
When <code class="literal">--implicit-cache</code> is used, <span class="application">SCons</span> will ignore any changes that
may have been made to search paths
(like <code class="envar">$CPPPATH</code> or <code class="envar">$LIBPATH</code>,).
This can lead to <span class="application">SCons</span> not rebuilding a file if a change to
<code class="envar">$CPPPATH</code> would normally cause a different, same-named file from
a different directory to be used.
</p></li><li class="listitem"><p>
When <code class="literal">--implicit-cache</code> is used, <span class="application">SCons</span> will not detect if a
same-named file has been added to a directory that is earlier in
the search path than the directory in which the file was found
last time.
</p></li></ul></div><div class="section" title="6.4.1.<2E>The --implicit-deps-changed Option"><div class="titlepage"><div><div><h3 class="title"><a name="idm1185"></a>6.4.1.<2E>The <code class="literal">--implicit-deps-changed</code> Option</h3></div></div></div><p>
When using cached implicit dependencies,
sometimes you want to "start fresh"
and have <span class="application">SCons</span> re-scan the files
for which it previously cached the dependencies.
For example,
if you have recently installed a new version of
external code that you use for compilation,
the external header files will have changed
and the previously-cached implicit dependencies
will be out of date.
You can update them by
running <span class="application">SCons</span> with the <code class="literal">--implicit-deps-changed</code> option:
</p><pre class="screen">% <strong class="userinput"><code>scons -Q --implicit-deps-changed hello</code></strong>
cc -o hello.o -c hello.c
cc -o hello hello.o
% <strong class="userinput"><code>scons -Q hello</code></strong>
scons: `hello' is up to date.
</pre><p>
In this case, <span class="application">SCons</span> will re-scan all of the implicit dependencies
and cache updated copies of the information.
</p></div><div class="section" title="6.4.2.<2E>The --implicit-deps-unchanged Option"><div class="titlepage"><div><div><h3 class="title"><a name="idm1197"></a>6.4.2.<2E>The <code class="literal">--implicit-deps-unchanged</code> Option</h3></div></div></div><p>
By default when caching dependencies,
<span class="application">SCons</span> notices when a file has been modified
and re-scans the file for any updated
implicit dependency information.
Sometimes, however, you may want
to force <span class="application">SCons</span> to use the cached implicit dependencies,
even if the source files changed.
This can speed up a build for example,
when you have changed your source files
but know that you haven't changed
any <code class="literal">#include</code> lines.
In this case,
you can use the <code class="literal">--implicit-deps-unchanged</code> option:
</p><pre class="screen">% <strong class="userinput"><code>scons -Q --implicit-deps-unchanged hello</code></strong>
cc -o hello.o -c hello.c
cc -o hello hello.o
% <strong class="userinput"><code>scons -Q hello</code></strong>
scons: `hello' is up to date.
</pre><p>
In this case,
<span class="application">SCons</span> will assume that the cached implicit
dependencies are correct and
will not bother to re-scan changed files.
For typical builds after small,
incremental changes to source files,
the savings may not be very big,
but sometimes every bit of
improved performance counts.
</p></div></div><div class="section" title="6.5.<2E>Explicit Dependencies: the Depends Function"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idm1210"></a>6.5.<2E>Explicit Dependencies: the <code class="function">Depends</code> Function</h2></div></div></div><p>
Sometimes a file depends on another file
that is not detected by an <span class="application">SCons</span> scanner.
For this situation,
<span class="application">SCons</span> allows you to specific explicitly that one file
depends on another file,
and must be rebuilt whenever that file changes.
This is specified using the <code class="function">Depends</code> method:
</p><pre class="programlisting">
hello = Program('hello.c')
Depends(hello, 'other_file')
</pre><pre class="screen">
% <strong class="userinput"><code>scons -Q hello</code></strong>
cc -c hello.c -o hello.o
cc -o hello hello.o
% <strong class="userinput"><code>scons -Q hello</code></strong>
scons: `hello' is up to date.
% <strong class="userinput"><code>edit other_file</code></strong>
[CHANGE THE CONTENTS OF other_file]
% <strong class="userinput"><code>scons -Q hello</code></strong>
cc -c hello.c -o hello.o
cc -o hello hello.o
</pre><p>
Note that the dependency
(the second argument to <code class="function">Depends</code>)
may also be a list of Node objects
(for example, as returned by a call to a Builder):
</p><pre class="programlisting">
hello = Program('hello.c')
goodbye = Program('goodbye.c')
Depends(hello, goodbye)
</pre><p>
in which case the dependency or dependencies
will be built before the target(s):
</p><pre class="screen">
% <strong class="userinput"><code>scons -Q hello</code></strong>
cc -c goodbye.c -o goodbye.o
cc -o goodbye goodbye.o
cc -c hello.c -o hello.o
cc -o hello hello.o
</pre></div><div class="section" title="6.6.<2E>Dependencies From External Files: the ParseDepends Function"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idm1229"></a>6.6.<2E>Dependencies From External Files: the <code class="function">ParseDepends</code>
Function</h2></div></div></div><p>
<span class="application">SCons</span> has built-in scanners for a number of languages. Sometimes
these scanners fail to extract certain implicit dependencies due
to limitations of the scanner implementation.
</p><p>
The following example illustrates a case where the built-in C
scanner is unable to extract the implicit dependency on a header
file.
</p><pre class="programlisting">
#define FOO_HEADER &lt;foo.h&gt;
#include FOO_HEADER
int main() {
return FOO;
}
</pre><pre class="screen">% <strong class="userinput"><code>scons -Q</code></strong>
cc -o hello.o -c -I. hello.c
cc -o hello hello.o
% [CHANGE CONTENTS OF foo.h]
% <strong class="userinput"><code>scons -Q</code></strong>
scons: `.' is up to date.
</pre><p>
Apparently, the scanner does not know about the header dependency.
Being not a full-fledged C preprocessor, the scanner does not
expand the macro.
</p><p>
In these cases, you may also use the compiler to extract the
implicit dependencies. <code class="function">ParseDepends</code> can parse the contents of
the compiler output in the style of <span class="application">Make</span>, and explicitly
establish all of the listed dependencies.
</p><p>
The following example uses <code class="function">ParseDepends</code> to process a compiler
generated dependency file which is generated as a side effect
during compilation of the object file:
</p><pre class="programlisting">
obj = Object('hello.c', CCFLAGS='-MD -MF hello.d', CPPPATH='.')
SideEffect('hello.d', obj)
ParseDepends('hello.d')
Program('hello', obj)
</pre><pre class="screen">% <strong class="userinput"><code>scons -Q</code></strong>
cc -o hello.o -c -MD -MF hello.d -I. hello.c
cc -o hello hello.o
% [CHANGE CONTENTS OF foo.h]
% <strong class="userinput"><code>scons -Q</code></strong>
cc -o hello.o -c -MD -MF hello.d -I. hello.c
</pre><p>
Parsing dependencies from a compiler-generated
<code class="filename">.d</code> file has a chicken-and-egg problem, that
causes unnecessary rebuilds:
</p><pre class="screen">
% <strong class="userinput"><code>scons -Q</code></strong>
cc -o hello.o -c -MD -MF hello.d -I. hello.c
cc -o hello hello.o
% <strong class="userinput"><code>scons -Q --debug=explain</code></strong>
scons: rebuilding `hello.o' because `foo.h' is a new dependency
cc -o hello.o -c -MD -MF hello.d -I. hello.c
% <strong class="userinput"><code>scons -Q</code></strong>
scons: `.' is up to date.
</pre><p>
In the first pass, the dependency file is generated while the
object file is compiled. At that time, <span class="application">SCons</span> does not know about
the dependency on <code class="filename">foo.h</code>. In the second pass,
the object file is regenerated because <code class="filename">foo.h</code>
is detected as a new dependency.
</p><p>
<code class="function">ParseDepends</code> immediately reads the specified file at invocation
time and just returns if the file does not exist. A dependency
file generated during the build process is not automatically
parsed again. Hence, the compiler-extracted dependencies are not
stored in the signature database during the same build pass. This
limitation of <code class="function">ParseDepends</code> leads to unnecessary recompilations.
Therefore, <code class="function">ParseDepends</code> should only be used if scanners are not
available for the employed language or not powerful enough for the
specific task.
</p></div><div class="section" title="6.7.<2E>Ignoring Dependencies: the Ignore Function"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idm1263"></a>6.7.<2E>Ignoring Dependencies: the <code class="function">Ignore</code> Function</h2></div></div></div><p>
Sometimes it makes sense
to not rebuild a program,
even if a dependency file changes.
In this case,
you would tell <span class="application">SCons</span> specifically
to ignore a dependency as follows:
</p><pre class="programlisting">
hello_obj=Object('hello.c')
hello = Program(hello_obj)
Ignore(hello_obj, 'hello.h')
</pre><pre class="screen">
% <strong class="userinput"><code>scons -Q hello</code></strong>
cc -c -o hello.o hello.c
cc -o hello hello.o
% <strong class="userinput"><code>scons -Q hello</code></strong>
scons: `hello' is up to date.
% <strong class="userinput"><code>edit hello.h</code></strong>
[CHANGE THE CONTENTS OF hello.h]
% <strong class="userinput"><code>scons -Q hello</code></strong>
scons: `hello' is up to date.
</pre><p>
Now, the above example is a little contrived,
because it's hard to imagine a real-world situation
where you wouldn't want to rebuild <code class="filename">hello</code>
if the <code class="filename">hello.h</code> file changed.
A more realistic example
might be if the <code class="filename">hello</code>
program is being built in a
directory that is shared between multiple systems
that have different copies of the
<code class="filename">stdio.h</code> include file.
In that case,
<span class="application">SCons</span> would notice the differences between
the different systems' copies of <code class="filename">stdio.h</code>
and would rebuild <code class="filename">hello</code>
each time you change systems.
You could avoid these rebuilds as follows:
</p><pre class="programlisting">
hello = Program('hello.c', CPPPATH=['/usr/include'])
Ignore(hello, '/usr/include/stdio.h')
</pre><p>
<code class="function">Ignore</code> can also be used to prevent a generated file from being built
by default. This is due to the fact that directories depend on
their contents. So to ignore a generated file from the default build,
you specify that the directory should ignore the generated file.
Note that the file will still be built if the user specifically
requests the target on scons command line, or if the file is
a dependency of another file which is requested and/or is built
by default.
</p><pre class="programlisting">
hello_obj=Object('hello.c')
hello = Program(hello_obj)
Ignore('.',[hello,hello_obj])
</pre><pre class="screen">% <strong class="userinput"><code>scons -Q</code></strong>
scons: `.' is up to date.
% <strong class="userinput"><code>scons -Q hello</code></strong>
cc -o hello.o -c hello.c
cc -o hello hello.o
% <strong class="userinput"><code>scons -Q hello</code></strong>
scons: `hello' is up to date.
</pre></div><div class="section" title="6.8.<2E>Order-Only Dependencies: the Requires Function"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idm1290"></a>6.8.<2E>Order-Only Dependencies: the <code class="function">Requires</code> Function</h2></div></div></div><p>
Occasionally,
it may be useful to specify that a certain
file or directory must, if necessary,
be built or created before some other target is built,
but that changes to that file or directory
do <span class="emphasis"><em>not</em></span>
require that the target itself be rebuilt.
Such a relationship is called an
<span class="emphasis"><em>order-only dependency</em></span>
because it only affects the order in which
things must be built--the dependency before the target--but
it is not a strict dependency relationship
because the target should not
change in response to changes in the dependent file.
</p><p>
For example, suppose that you want to create a file
every time you run a build
that identifies the time the build was performed,
the version number, etc.,
and which is included in every program that you build.
The version file's contents will change every build.
If you specify a normal dependency relationship,
then every program that depends on
that file would be rebuilt every time you ran <span class="application">SCons</span>.
For example, we could use some Python code in
a <code class="filename">SConstruct</code> file to create a new <code class="filename">version.c</code> file
with a string containing the current date every time
we run <span class="application">SCons</span>,
and then link a program with the resulting object file
by listing <code class="filename">version.c</code> in the sources:
</p><pre class="programlisting">
import time
version_c_text = """
char *date = "%s";
""" % time.ctime(time.time())
open('version.c', 'w').write(version_c_text)
hello = Program(['hello.c', 'version.c'])
</pre><p>
If we list <code class="filename">version.c</code> as an actual source file,
though, then the <code class="filename">version.o</code> file
will get rebuilt every time we run <span class="application">SCons</span>
(because the <code class="filename">SConstruct</code> file itself changes
the contents of <code class="filename">version.c</code>)
and the <code class="filename">hello</code> executable
will get re-linked every time
(because the <code class="filename">version.o</code> file changes):
</p><pre class="screen">% <strong class="userinput"><code>scons -Q hello</code></strong>
cc -o hello.o -c hello.c
cc -o version.o -c version.c
cc -o hello hello.o version.o
% <strong class="userinput"><code>sleep 1</code></strong>
% <strong class="userinput"><code>scons -Q hello</code></strong>
cc -o version.o -c version.c
cc -o hello hello.o version.o
% <strong class="userinput"><code>sleep 1</code></strong>
% <strong class="userinput"><code>scons -Q hello</code></strong>
cc -o version.o -c version.c
cc -o hello hello.o version.o
</pre><p>
(Note that for the above example to work,
we <span class="application">sleep</span> for one second in between each run,
so that the <code class="filename">SConstruct</code> file will create a
<code class="filename">version.c</code> file with a time string
that's one second later than the previous run.)
</p><p>
One solution is to use the <code class="function">Requires</code> function
to specify that the <code class="filename">version.o</code>
must be rebuilt before it is used by the link step,
but that changes to <code class="filename">version.o</code>
should not actually cause the <code class="filename">hello</code>
executable to be re-linked:
</p><pre class="programlisting">
import time
version_c_text = """
char *date = "%s";
""" % time.ctime(time.time())
open('version.c', 'w').write(version_c_text)
version_obj = Object('version.c')
hello = Program('hello.c',
LINKFLAGS = str(version_obj[0]))
Requires(hello, version_obj)
</pre><p>
Notice that because we can no longer list <code class="filename">version.c</code>
as one of the sources for the <code class="filename">hello</code> program,
we have to find some other way to get it into the link command line.
For this example, we're cheating a bit and stuffing the
object file name (extracted from <code class="literal">version_obj</code>
list returned by the <code class="function">Object</code> call)
into the <a class="link" href="#cv-LINKFLAGS"><code class="envar">$LINKFLAGS</code></a> variable,
because <code class="envar">$LINKFLAGS</code> is already included
in the <a class="link" href="#cv-LINKCOM"><code class="envar">$LINKCOM</code></a> command line.
</p><p>
With these changes,
we get the desired behavior of only
re-linking the <code class="filename">hello</code> executable
when the <code class="filename">hello.c</code> has changed,
even though the <code class="filename">version.o</code> is rebuilt
(because the <code class="filename">SConstruct</code> file still changes the
<code class="filename">version.c</code> contents directly each run):
</p><pre class="screen">% <strong class="userinput"><code>scons -Q hello</code></strong>
cc -o version.o -c version.c
cc -o hello.o -c hello.c
cc -o hello version.o hello.o
% <strong class="userinput"><code>sleep 1</code></strong>
% <strong class="userinput"><code>scons -Q hello</code></strong>
cc -o version.o -c version.c
scons: `hello' is up to date.
% <strong class="userinput"><code>sleep 1</code></strong>
% [CHANGE THE CONTENTS OF hello.c]
% <strong class="userinput"><code>scons -Q hello</code></strong>
cc -o version.o -c version.c
cc -o hello.o -c hello.c
cc -o hello version.o hello.o
% <strong class="userinput"><code>sleep 1</code></strong>
% <strong class="userinput"><code>scons -Q hello</code></strong>
cc -o version.o -c version.c
scons: `hello' is up to date.
</pre></div><div class="section" title="6.9.<2E>The AlwaysBuild Function"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idm1351"></a>6.9.<2E>The <code class="function">AlwaysBuild</code> Function</h2></div></div></div><p>
How <span class="application">SCons</span> handles dependencies can also be affected
by the <code class="function">AlwaysBuild</code> method.
When a file is passed to the <code class="function">AlwaysBuild</code> method,
like so:
</p><pre class="programlisting">
hello = Program('hello.c')
AlwaysBuild(hello)
</pre><p>
Then the specified target file (<code class="filename">hello</code> in our example)
will always be considered out-of-date and
rebuilt whenever that target file is evaluated
while walking the dependency graph:
</p><pre class="screen">% <strong class="userinput"><code>scons -Q</code></strong>
cc -o hello.o -c hello.c
cc -o hello hello.o
% <strong class="userinput"><code>scons -Q</code></strong>
cc -o hello hello.o
</pre><p>
The <code class="function">AlwaysBuild</code> function has a somewhat misleading name,
because it does not actually mean the target file will
be rebuilt every single time <span class="application">SCons</span> is invoked.
Instead, it means that the target will, in fact,
be rebuilt whenever the target file is encountered
while evaluating the targets specified on
the command line (and their dependencies).
So specifying some other target on the command line,
a target that does <span class="emphasis"><em>not</em></span>
itself depend on the <code class="function">AlwaysBuild</code> target,
will still be rebuilt only if it's out-of-date
with respect to its dependencies:
</p><pre class="screen">% <strong class="userinput"><code>scons -Q</code></strong>
cc -o hello.o -c hello.c
cc -o hello hello.o
% <strong class="userinput"><code>scons -Q hello.o</code></strong>
scons: `hello.o' is up to date.
</pre></div><div class="footnotes"><br><hr width="100" align="left"><div class="footnote"><p><sup>[<a id="ftn.idm1051" href="#idm1051" class="para">2</a>] </sup>
This easily-overlooked distinction between
how <span class="application">SCons</span> decides if the target itself must be rebuilt
and how the target is then used to decide if a different
target must be rebuilt is one of the confusing
things that has led to the <code class="function">TargetSignatures</code>
and <code class="function">SourceSignatures</code> functions being
replaced by the simpler <code class="function">Decider</code> function.
</p></div></div></div><div class="chapter" title="Chapter<65>7.<2E>Environments"><div class="titlepage"><div><div><h2 class="title"><a name="chap-environments"></a>Chapter<EFBFBD>7.<2E>Environments</h2></div></div></div><p>
An <code class="literal">environment</code>
is a collection of values that
can affect how a program executes.
<span class="application">SCons</span> distinguishes between three
different types of environments
that can affect the behavior of <span class="application">SCons</span> itself
(subject to the configuration in the <code class="filename">SConscript</code> files),
as well as the compilers and other tools it executes:
</p><div class="variablelist"><dl><dt><span class="term">External Environment</span></dt><dd><p>
The <code class="literal">external environment</code>
is the set of variables in the user's environment
at the time the user runs <span class="application">SCons</span>.
These variables are available within the <code class="filename">SConscript</code> files
through the Python <code class="literal">os.environ</code> dictionary.
See <a class="xref" href="#sect-external-environments" title="7.1.<2E>Using Values From the External Environment">Section<EFBFBD>7.1, &#8220;Using Values From the External Environment&#8221;</a>, below.
</p></dd><dt><span class="term"><code class="literal">Construction Environment</code></span></dt><dd><p>
A <code class="literal">construction environment</code>
is a distinct object created within
a <code class="filename">SConscript</code> file and
which contains values that
affect how <span class="application">SCons</span> decides
what action to use to build a target,
and even to define which targets
should be built from which sources.
One of the most powerful features of <span class="application">SCons</span>
is the ability to create multiple <code class="literal">construction environments</code>,
including the ability to clone a new, customized
<code class="literal">construction environment</code> from an existing <code class="literal">construction environment</code>.
See <a class="xref" href="#sect-construction-environments" title="7.2.<2E>Construction Environments">Section<EFBFBD>7.2, &#8220;Construction Environments&#8221;</a>, below.
</p></dd><dt><span class="term">Execution Environment</span></dt><dd><p>
An <code class="literal">execution environment</code>
is the values that <span class="application">SCons</span> sets
when executing an external
command (such as a compiler or linker)
to build one or more targets.
Note that this is not the same as
the <code class="literal">external environment</code>
(see above).
See <a class="xref" href="#sect-execution-environments" title="7.3.<2E>Controlling the Execution Environment for Issued Commands">Section<EFBFBD>7.3, &#8220;Controlling the Execution Environment for Issued Commands&#8221;</a>, below.
</p></dd></dl></div><p>
Unlike <span class="application">Make</span>, <span class="application">SCons</span> does not automatically
copy or import values between different environments
(with the exception of explicit clones of <code class="literal">construction environments</code>,
which inherit values from their parent).
This is a deliberate design choice
to make sure that builds are,
by default, repeatable regardless of
the values in the user's external environment.
This avoids a whole class of problems with builds
where a developer's local build works
because a custom variable setting
causes a different compiler or build option to be used,
but the checked-in change breaks the official build
because it uses different environment variable settings.
</p><p>
Note that the <code class="filename">SConscript</code> writer can
easily arrange for variables to be
copied or imported between environments,
and this is often very useful
(or even downright necessary)
to make it easy for developers
to customize the build in appropriate ways.
The point is <span class="emphasis"><em>not</em></span>
that copying variables between different environments
is evil and must always be avoided.
Instead, it should be up to the
implementer of the build system
to make conscious choices
about how and when to import
a variable from one environment to another,
making informed decisions about
striking the right balance
between making the build
repeatable on the one hand
and convenient to use on the other.
</p><div class="section" title="7.1.<2E>Using Values From the External Environment"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="sect-external-environments"></a>7.1.<2E>Using Values From the External Environment</h2></div></div></div><p>
The <code class="literal">external environment</code>
variable settings that
the user has in force
when executing <span class="application">SCons</span>
are available through the normal Python
<code class="envar">os.environ</code>
dictionary.
This means that you must add an
<code class="literal">import os</code> statement
to any <code class="filename">SConscript</code> file
in which you want to use
values from the user's external environment.
</p><pre class="programlisting">
import os
</pre><p>
More usefully, you can use the
<code class="envar">os.environ</code>
dictionary in your <code class="filename">SConscript</code>
files to initialize <code class="literal">construction environments</code>
with values from the user's external environment.
See the next section,
<a class="xref" href="#sect-construction-environments" title="7.2.<2E>Construction Environments">Section<EFBFBD>7.2, &#8220;Construction Environments&#8221;</a>,
for information on how to do this.
</p></div><div class="section" title="7.2.<2E>Construction Environments"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="sect-construction-environments"></a>7.2.<2E>Construction Environments</h2></div></div></div><p>
It is rare that all of the software in a large,
complicated system needs to be built the same way.
For example, different source files may need different options
enabled on the command line,
or different executable programs need to be linked
with different libraries.
<span class="application">SCons</span> accommodates these different build
requirements by allowing you to create and
configure multiple <code class="literal">construction environments</code>
that control how the software is built.
A <code class="literal">construction environment</code> is an object
that has a number of associated
<code class="literal">construction variables</code>, each with a name and a value.
(A construction environment also has an attached
set of <code class="classname">Builder</code> methods,
about which we'll learn more later.)
</p><div class="section" title="7.2.1.<2E>Creating a Construction Environment: the Environment Function"><div class="titlepage"><div><div><h3 class="title"><a name="idm1439"></a>7.2.1.<2E>Creating a <code class="literal">Construction Environment</code>: the <code class="function">Environment</code> Function</h3></div></div></div><p>
A <code class="literal">construction environment</code> is created by the <code class="function">Environment</code> method:
</p><pre class="programlisting">
env = Environment()
</pre><p>
By default, <span class="application">SCons</span> initializes every
new construction environment
with a set of <code class="literal">construction variables</code>
based on the tools that it finds on your system,
plus the default set of builder methods
necessary for using those tools.
The construction variables
are initialized with values describing
the C compiler,
the Fortran compiler,
the linker,
etc.,
as well as the command lines to invoke them.
</p><p>
When you initialize a construction environment
you can set the values of the
environment's <code class="literal">construction variables</code>
to control how a program is built.
For example:
</p><pre class="programlisting">
env = Environment(CC = 'gcc',
CCFLAGS = '-O2')
env.Program('foo.c')
</pre><p>
The construction environment in this example
is still initialized with the same default
construction variable values,
except that the user has explicitly specified use of the
GNU C compiler <span class="application">gcc</span>,
and further specifies that the <code class="literal">-O2</code>
(optimization level two)
flag should be used when compiling the object file.
In other words, the explicit initializations of
<a class="link" href="#cv-CC"><code class="envar">$CC</code></a> and <a class="link" href="#cv-CCFLAGS"><code class="envar">$CCFLAGS</code></a>
override the default values in the newly-created
construction environment.
So a run from this example would look like:
</p><pre class="screen">% <strong class="userinput"><code>scons -Q</code></strong>
gcc -o foo.o -c -O2 foo.c
gcc -o foo foo.o
</pre></div><div class="section" title="7.2.2.<2E>Fetching Values From a Construction Environment"><div class="titlepage"><div><div><h3 class="title"><a name="idm1462"></a>7.2.2.<2E>Fetching Values From a <code class="literal">Construction Environment</code></h3></div></div></div><p>
You can fetch individual construction variables
using the normal syntax
for accessing individual named items in a Python dictionary:
</p><pre class="programlisting">
env = Environment()
print("CC is: %s"%env['CC'])
</pre><p>
This example <code class="filename">SConstruct</code> file doesn't build anything,
but because it's actually a Python script,
it will print the value of <a class="link" href="#cv-CC"><code class="envar">$CC</code></a> for us:
</p><pre class="screen">% <strong class="userinput"><code>scons -Q</code></strong>
CC is: cc
scons: `.' is up to date.
</pre><p>
A construction environment, however,
is actually an object with associated methods, etc.
If you want to have direct access to only the
dictionary of construction variables,
you can fetch this using the <code class="literal">Dictionary</code> method:
</p><pre class="programlisting">
env = Environment(FOO = 'foo', BAR = 'bar')
dict = env.Dictionary()
for key in ['OBJSUFFIX', 'LIBSUFFIX', 'PROGSUFFIX']:
print("key = %s, value = %s" % (key, dict[key]))
</pre><p>
This <code class="filename">SConstruct</code> file
will print the specified dictionary items for us on POSIX
systems as follows:
</p><pre class="screen">% <strong class="userinput"><code>scons -Q</code></strong>
key = OBJSUFFIX, value = .o
key = LIBSUFFIX, value = .a
key = PROGSUFFIX, value =
scons: `.' is up to date.
</pre><p>
And on Windows:
</p><pre class="screen">C:\&gt;<strong class="userinput"><code>scons -Q</code></strong>
key = OBJSUFFIX, value = .obj
key = LIBSUFFIX, value = .lib
key = PROGSUFFIX, value = .exe
scons: `.' is up to date.
</pre><p>
If you want to loop and print the values of
all of the construction variables in a construction environment,
the Python code to do that in sorted order might look something like:
</p><pre class="programlisting">
env = Environment()
for item in sorted(env.Dictionary().items()):
print("construction variable = '%s', value = '%s'" % item)
</pre></div><div class="section" title="7.2.3.<2E>Expanding Values From a Construction Environment: the subst Method"><div class="titlepage"><div><div><h3 class="title"><a name="idm1485"></a>7.2.3.<2E>Expanding Values From a <code class="literal">Construction Environment</code>: the <code class="function">subst</code> Method</h3></div></div></div><p>
Another way to get information from
a construction environment
is to use the <code class="function">subst</code> method
on a string containing <code class="literal">$</code> expansions
of construction variable names.
As a simple example,
the example from the previous
section that used
<code class="literal">env['CC']</code>
to fetch the value of <a class="link" href="#cv-CC"><code class="envar">$CC</code></a>
could also be written as:
</p><pre class="programlisting">
env = Environment()
print("CC is: %s"%env.subst('$CC'))
</pre><p>
One advantage of using
<code class="function">subst</code> to expand strings is
that construction variables
in the result get re-expanded until
there are no expansions left in the string.
So a simple fetch of a value like
<a class="link" href="#cv-CCCOM"><code class="envar">$CCCOM</code></a>:
</p><pre class="programlisting">
env = Environment(CCFLAGS = '-DFOO')
print("CCCOM is: %s"%env['CCCOM'])
</pre><p>
Will print the unexpanded value of <code class="envar">$CCCOM</code>,
showing us the construction
variables that still need to be expanded:
</p><pre class="screen">
% <strong class="userinput"><code>scons -Q</code></strong>
CCCOM is: $CC $CCFLAGS $CPPFLAGS $_CPPDEFFLAGS $_CPPINCFLAGS -c -o $TARGET $SOURCES
scons: `.' is up to date.
</pre><p>
Calling the <code class="function">subst</code> method on <code class="varname">$CCOM</code>,
however:
</p><pre class="programlisting">
env = Environment(CCFLAGS = '-DFOO')
print("CCCOM is: %s"%env.subst('$CCCOM'))
</pre><p>
Will recursively expand all of
the construction variables prefixed
with <code class="literal">$</code> (dollar signs),
showing us the final output:
</p><pre class="screen">
% <strong class="userinput"><code>scons -Q</code></strong>
CCCOM is: gcc -DFOO -c -o
scons: `.' is up to date.
</pre><p>
Note that because we're not expanding this
in the context of building something
there are no target or source files
for <a class="link" href="#cv-TARGET"><code class="envar">$TARGET</code></a> and <a class="link" href="#cv-SOURCES"><code class="envar">$SOURCES</code></a> to expand.
</p></div><div class="section" title="7.2.4.<2E>Handling Problems With Value Expansion"><div class="titlepage"><div><div><h3 class="title"><a name="idm1518"></a>7.2.4.<2E>Handling Problems With Value Expansion</h3></div></div></div><p>
If a problem occurs when expanding a construction variable,
by default it is expanded to <code class="literal">''</code>
(a null string), and will not cause scons to fail.
</p><pre class="programlisting">
env = Environment()
print("value is: %s"%env.subst( '-&gt;$MISSING&lt;-' ))
</pre><pre class="screen">% <strong class="userinput"><code>scons -Q</code></strong>
value is: -&gt;&lt;-
scons: `.' is up to date.
</pre><p>
This default behaviour can be changed using the <code class="function">AllowSubstExceptions</code>
function.
When a problem occurs with a variable expansion it generates
an exception, and the <code class="function">AllowSubstExceptions</code> function controls
which of these exceptions are actually fatal and which are
allowed to occur safely. By default, <code class="classname">NameError</code> and <code class="classname">IndexError</code>
are the two exceptions that are allowed to occur: so instead of
causing scons to fail, these are caught, the variable expanded to
<code class="literal">''</code>
and scons execution continues.
To require that all construction variable names exist, and that
indexes out of range are not allowed, call <code class="function">AllowSubstExceptions</code>
with no extra arguments.
</p><pre class="programlisting">
AllowSubstExceptions()
env = Environment()
print("value is: %s"%env.subst( '-&gt;$MISSING&lt;-' ))
</pre><pre class="screen">% <strong class="userinput"><code>scons -Q</code></strong>
scons: *** NameError `MISSING' trying to evaluate `$MISSING'
File "/home/my/project/SConstruct", line 3, in &lt;module&gt;
</pre><p>
This can also be used to allow other exceptions that might occur,
most usefully with the <code class="literal">${...}</code> construction
variable syntax. For example, this would allow zero-division to
occur in a variable expansion in addition to the default exceptions
allowed
</p><pre class="programlisting">
AllowSubstExceptions(IndexError, NameError, ZeroDivisionError)
env = Environment()
print("value is: %s"%env.subst( '-&gt;${1 / 0}&lt;-' ))
</pre><pre class="screen">% <strong class="userinput"><code>scons -Q</code></strong>
value is: -&gt;&lt;-
scons: `.' is up to date.
</pre><p>
If <code class="function">AllowSubstExceptions</code> is called multiple times, each call
completely overwrites the previous list of allowed exceptions.
</p></div><div class="section" title="7.2.5.<2E>Controlling the Default Construction Environment: the DefaultEnvironment Function"><div class="titlepage"><div><div><h3 class="title"><a name="idm1542"></a>7.2.5.<2E>Controlling the Default <code class="literal">Construction Environment</code>: the <code class="function">DefaultEnvironment</code> Function</h3></div></div></div><p>
All of the <code class="classname">Builder</code> functions that we've introduced so far,
like <code class="function">Program</code> and <code class="function">Library</code>,
actually use a default <code class="literal">construction environment</code>
that contains settings
for the various compilers
and other tools that
<span class="application">SCons</span> configures by default,
or otherwise knows about
and has discovered on your system.
The goal of the default construction environment
is to make many configurations to "just work"
to build software using
readily available tools
with a minimum of configuration changes.
</p><p>
You can, however, control the settings
in the default construction environment
by using the <code class="function">DefaultEnvironment</code> function
to initialize various settings:
</p><pre class="programlisting">
DefaultEnvironment(CC = '/usr/local/bin/gcc')
</pre><p>
When configured as above,
all calls to the <code class="function">Program</code>
or <code class="function">Object</code> Builder
will build object files with the
<code class="filename">/usr/local/bin/gcc</code>
compiler.
</p><p>
Note that the <code class="function">DefaultEnvironment</code> function
returns the initialized
default construction environment object,
which can then be manipulated like any
other construction environment.
So the following
would be equivalent to the
previous example,
setting the <code class="envar">$CC</code>
variable to <code class="filename">/usr/local/bin/gcc</code>
but as a separate step after
the default construction environment has been initialized:
</p><pre class="programlisting">
env = DefaultEnvironment()
env['CC'] = '/usr/local/bin/gcc'
</pre><p>
One very common use of the <code class="function">DefaultEnvironment</code> function
is to speed up <span class="application">SCons</span> initialization.
As part of trying to make most default
configurations "just work,"
<span class="application">SCons</span> will actually
search the local system for installed
compilers and other utilities.
This search can take time,
especially on systems with
slow or networked file systems.
If you know which compiler(s) and/or
other utilities you want to configure,
you can control the search
that <span class="application">SCons</span> performs
by specifying some specific
tool modules with which to
initialize the default construction environment:
</p><pre class="programlisting">
env = DefaultEnvironment(tools = ['gcc', 'gnulink'],
CC = '/usr/local/bin/gcc')
</pre><p>
So the above example would tell <span class="application">SCons</span>
to explicitly configure the default environment
to use its normal GNU Compiler and GNU Linker settings
(without having to search for them,
or any other utilities for that matter),
and specifically to use the compiler found at
<code class="filename">/usr/local/bin/gcc</code>.
</p></div><div class="section" title="7.2.6.<2E>Multiple Construction Environments"><div class="titlepage"><div><div><h3 class="title"><a name="idm1573"></a>7.2.6.<2E>Multiple <code class="literal">Construction Environments</code></h3></div></div></div><p>
The real advantage of construction environments
is that you can create as many different construction
environments as you need,
each tailored to a different way to build
some piece of software or other file.
If, for example, we need to build
one program with the <code class="literal">-O2</code> flag
and another with the <code class="literal">-g</code> (debug) flag,
we would do this like so:
</p><pre class="programlisting">
opt = Environment(CCFLAGS = '-O2')
dbg = Environment(CCFLAGS = '-g')
opt.Program('foo', 'foo.c')
dbg.Program('bar', 'bar.c')
</pre><pre class="screen">% <strong class="userinput"><code>scons -Q</code></strong>
cc -o bar.o -c -g bar.c
cc -o bar bar.o
cc -o foo.o -c -O2 foo.c
cc -o foo foo.o
</pre><p>
We can even use multiple construction environments to build
multiple versions of a single program.
If you do this by simply trying to use the
<a class="link" href="#b-Program"><code class="function">Program</code></a> builder with both environments, though,
like this:
</p><pre class="programlisting">
opt = Environment(CCFLAGS = '-O2')
dbg = Environment(CCFLAGS = '-g')
opt.Program('foo', 'foo.c')
dbg.Program('foo', 'foo.c')
</pre><p>
Then <span class="application">SCons</span> generates the following error:
</p><pre class="screen">% <strong class="userinput"><code>scons -Q</code></strong>
scons: *** Two environments with different actions were specified for the same target: foo.o
File "/home/my/project/SConstruct", line 6, in &lt;module&gt;
</pre><p>
This is because the two <code class="function">Program</code> calls have
each implicitly told <span class="application">SCons</span> to generate an object file named
<code class="filename">foo.o</code>,
one with a <a class="link" href="#cv-CCFLAGS"><code class="envar">$CCFLAGS</code></a> value of
<code class="literal">-O2</code>
and one with a <a class="link" href="#cv-CCFLAGS"><code class="envar">$CCFLAGS</code></a> value of
<code class="literal">-g</code>.
<span class="application">SCons</span> can't just decide that one of them
should take precedence over the other,
so it generates the error.
To avoid this problem,
we must explicitly specify
that each environment compile
<code class="filename">foo.c</code>
to a separately-named object file
using the <a class="link" href="#b-Object"><code class="function">Object</code></a> builder, like so:
</p><pre class="programlisting">
opt = Environment(CCFLAGS = '-O2')
dbg = Environment(CCFLAGS = '-g')
o = opt.Object('foo-opt', 'foo.c')
opt.Program(o)
d = dbg.Object('foo-dbg', 'foo.c')
dbg.Program(d)
</pre><p>
Notice that each call to the <code class="function">Object</code> builder
returns a value,
an internal <span class="application">SCons</span> object that
represents the object file that will be built.
We then use that object
as input to the <code class="function">Program</code> builder.
This avoids having to specify explicitly
the object file name in multiple places,
and makes for a compact, readable
<code class="filename">SConstruct</code> file.
Our <span class="application">SCons</span> output then looks like:
</p><pre class="screen">% <strong class="userinput"><code>scons -Q</code></strong>
cc -o foo-dbg.o -c -g foo.c
cc -o foo-dbg foo-dbg.o
cc -o foo-opt.o -c -O2 foo.c
cc -o foo-opt foo-opt.o
</pre></div><div class="section" title="7.2.7.<2E>Making Copies of Construction Environments: the Clone Method"><div class="titlepage"><div><div><h3 class="title"><a name="idm1613"></a>7.2.7.<2E>Making Copies of <code class="literal">Construction Environments</code>: the <code class="function">Clone</code> Method</h3></div></div></div><p>
Sometimes you want more than one construction environment
to share the same values for one or more variables.
Rather than always having to repeat all of the common
variables when you create each construction environment,
you can use the <code class="function">Clone</code> method
to create a copy of a construction environment.
</p><p>
Like the <code class="function">Environment</code> call that creates a construction environment,
the <code class="function">Clone</code> method takes <code class="literal">construction variable</code> assignments,
which will override the values in the copied construction environment.
For example, suppose we want to use <span class="application">gcc</span>
to create three versions of a program,
one optimized, one debug, and one with neither.
We could do this by creating a "base" construction environment
that sets <a class="link" href="#cv-CC"><code class="envar">$CC</code></a> to <span class="application">gcc</span>,
and then creating two copies,
one which sets <a class="link" href="#cv-CCFLAGS"><code class="envar">$CCFLAGS</code></a> for optimization
and the other which sets <code class="envar">$CCFLAGS</code> for debugging:
</p><pre class="programlisting">
env = Environment(CC = 'gcc')
opt = env.Clone(CCFLAGS = '-O2')
dbg = env.Clone(CCFLAGS = '-g')
env.Program('foo', 'foo.c')
o = opt.Object('foo-opt', 'foo.c')
opt.Program(o)
d = dbg.Object('foo-dbg', 'foo.c')
dbg.Program(d)
</pre><p>
Then our output would look like:
</p><pre class="screen">% <strong class="userinput"><code>scons -Q</code></strong>
gcc -o foo.o -c foo.c
gcc -o foo foo.o
gcc -o foo-dbg.o -c -g foo.c
gcc -o foo-dbg foo-dbg.o
gcc -o foo-opt.o -c -O2 foo.c
gcc -o foo-opt foo-opt.o
</pre></div><div class="section" title="7.2.8.<2E>Replacing Values: the Replace Method"><div class="titlepage"><div><div><h3 class="title"><a name="idm1634"></a>7.2.8.<2E>Replacing Values: the <code class="function">Replace</code> Method</h3></div></div></div><p>
You can replace existing construction variable values
using the <code class="function">Replace</code> method:
</p><pre class="programlisting">
env = Environment(CCFLAGS = '-DDEFINE1')
env.Replace(CCFLAGS = '-DDEFINE2')
env.Program('foo.c')
</pre><p>
The replacing value
(<code class="literal">-DDEFINE2</code> in the above example)
completely replaces the value in the
construction environment:
</p><pre class="screen">% <strong class="userinput"><code>scons -Q</code></strong>
cc -o foo.o -c -DDEFINE2 foo.c
cc -o foo foo.o
</pre><p>
You can safely call <code class="function">Replace</code>
for construction variables that
don't exist in the construction environment:
</p><pre class="programlisting">
env = Environment()
env.Replace(NEW_VARIABLE = 'xyzzy')
print("NEW_VARIABLE = %s"%env['NEW_VARIABLE'])
</pre><p>
In this case,
the construction variable simply
gets added to the construction environment:
</p><pre class="screen">% <strong class="userinput"><code>scons -Q</code></strong>
NEW_VARIABLE = xyzzy
scons: `.' is up to date.
</pre><p>
Because the variables
aren't expanded until the construction environment
is actually used to build the targets,
and because <span class="application">SCons</span> function and method calls
are order-independent,
the last replacement "wins"
and is used to build all targets,
regardless of the order in which
the calls to Replace() are
interspersed with calls to
builder methods:
</p><pre class="programlisting">
env = Environment(CCFLAGS = '-DDEFINE1')
print("CCFLAGS = %s"%env['CCFLAGS'])
env.Program('foo.c')
env.Replace(CCFLAGS = '-DDEFINE2')
print("CCFLAGS = %s"%env['CCFLAGS'])
env.Program('bar.c')
</pre><p>
The timing of when the replacement
actually occurs relative
to when the targets get built
becomes apparent
if we run <code class="filename">scons</code> without the <code class="literal">-Q</code>
option:
</p><pre class="screen">% <strong class="userinput"><code>scons</code></strong>
scons: Reading SConscript files ...
CCFLAGS = -DDEFINE1
CCFLAGS = -DDEFINE2
scons: done reading SConscript files.
scons: Building targets ...
cc -o bar.o -c -DDEFINE2 bar.c
cc -o bar bar.o
cc -o foo.o -c -DDEFINE2 foo.c
cc -o foo foo.o
scons: done building targets.
</pre><p>
Because the replacement occurs while
the <code class="filename">SConscript</code> files are being read,
the <a class="link" href="#cv-CCFLAGS"><code class="envar">$CCFLAGS</code></a>
variable has already been set to
<code class="literal">-DDEFINE2</code>
by the time the <code class="filename">foo.o</code> target is built,
even though the call to the <code class="function">Replace</code>
method does not occur until later in
the <code class="filename">SConscript</code> file.
</p></div><div class="section" title="7.2.9.<2E>Setting Values Only If They're Not Already Defined: the SetDefault Method"><div class="titlepage"><div><div><h3 class="title"><a name="idm1666"></a>7.2.9.<2E>Setting Values Only If They're Not Already Defined: the <code class="function">SetDefault</code> Method</h3></div></div></div><p>
Sometimes it's useful to be able to specify
that a construction variable should be
set to a value only if the construction environment
does not already have that variable defined
You can do this with the <code class="function">SetDefault</code> method,
which behaves similarly to the <code class="function">set_default</code>
method of Python dictionary objects:
</p><pre class="programlisting">
env.SetDefault(SPECIAL_FLAG = '-extra-option')
</pre><p>
This is especially useful
when writing your own <code class="literal">Tool</code> modules
to apply variables to construction environments.
</p></div><div class="section" title="7.2.10.<2E>Appending to the End of Values: the Append Method"><div class="titlepage"><div><div><h3 class="title"><a name="idm1675"></a>7.2.10.<2E>Appending to the End of Values: the <code class="function">Append</code> Method</h3></div></div></div><p>
You can append a value to
an existing construction variable
using the <code class="function">Append</code> method:
</p><pre class="programlisting">
env = Environment(CCFLAGS = ['-DMY_VALUE'])
env.Append(CCFLAGS = ['-DLAST'])
env.Program('foo.c')
</pre><p>
<span class="application">SCons</span> then supplies both the <code class="literal">-DMY_VALUE</code> and
<code class="literal">-DLAST</code> flags when compiling the object file:
</p><pre class="screen">% <strong class="userinput"><code>scons -Q</code></strong>
cc -o foo.o -c -DMY_VALUE -DLAST foo.c
cc -o foo foo.o
</pre><p>
If the construction variable doesn't already exist,
the <code class="function">Append</code> method will create it:
</p><pre class="programlisting">
env = Environment()
env.Append(NEW_VARIABLE = 'added')
print("NEW_VARIABLE = %s"%env['NEW_VARIABLE'])
</pre><p>
Which yields:
</p><pre class="screen">% <strong class="userinput"><code>scons -Q</code></strong>
NEW_VARIABLE = added
scons: `.' is up to date.
</pre><p>
Note that the <code class="function">Append</code> function tries to be "smart"
about how the new value is appended to the old value.
If both are strings, the previous and new strings
are simply concatenated.
Similarly, if both are lists,
the lists are concatenated.
If, however, one is a string and the other is a list,
the string is added as a new element to the list.
</p></div><div class="section" title="7.2.11.<2E>Appending Unique Values: the AppendUnique Method"><div class="titlepage"><div><div><h3 class="title"><a name="idm1695"></a>7.2.11.<2E>Appending Unique Values: the <code class="function">AppendUnique</code> Method</h3></div></div></div><p>
Some times it's useful to add a new value
only if the existing construction variable
doesn't already contain the value.
This can be done using the <code class="function">AppendUnique</code> method:
</p><pre class="programlisting">
env.AppendUnique(CCFLAGS=['-g'])
</pre><p>
In the above example,
the <code class="literal">-g</code> would be added
only if the <code class="envar">$CCFLAGS</code> variable
does not already contain a <code class="literal">-g</code> value.
</p></div><div class="section" title="7.2.12.<2E>Appending to the Beginning of Values: the Prepend Method"><div class="titlepage"><div><div><h3 class="title"><a name="idm1705"></a>7.2.12.<2E>Appending to the Beginning of Values: the <code class="function">Prepend</code> Method</h3></div></div></div><p>
You can append a value to the beginning of
an existing construction variable
using the <code class="function">Prepend</code> method:
</p><pre class="programlisting">
env = Environment(CCFLAGS = ['-DMY_VALUE'])
env.Prepend(CCFLAGS = ['-DFIRST'])
env.Program('foo.c')
</pre><p>
<span class="application">SCons</span> then supplies both the <code class="literal">-DFIRST</code> and
<code class="literal">-DMY_VALUE</code> flags when compiling the object file:
</p><pre class="screen">% <strong class="userinput"><code>scons -Q</code></strong>
cc -o foo.o -c -DFIRST -DMY_VALUE foo.c
cc -o foo foo.o
</pre><p>
If the construction variable doesn't already exist,
the <code class="function">Prepend</code> method will create it:
</p><pre class="programlisting">
env = Environment()
env.Prepend(NEW_VARIABLE = 'added')
print("NEW_VARIABLE = %s"%env['NEW_VARIABLE'])
</pre><p>
Which yields:
</p><pre class="screen">% <strong class="userinput"><code>scons -Q</code></strong>
NEW_VARIABLE = added
scons: `.' is up to date.
</pre><p>
Like the <code class="function">Append</code> function,
the <code class="function">Prepend</code> function tries to be "smart"
about how the new value is appended to the old value.
If both are strings, the previous and new strings
are simply concatenated.
Similarly, if both are lists,
the lists are concatenated.
If, however, one is a string and the other is a list,
the string is added as a new element to the list.
</p></div><div class="section" title="7.2.13.<2E>Prepending Unique Values: the PrependUnique Method"><div class="titlepage"><div><div><h3 class="title"><a name="idm1726"></a>7.2.13.<2E>Prepending Unique Values: the <code class="function">PrependUnique</code> Method</h3></div></div></div><p>
Some times it's useful to add a new value
to the beginning of a construction variable
only if the existing value
doesn't already contain the to-be-added value.
This can be done using the <code class="function">PrependUnique</code> method:
</p><pre class="programlisting">
env.PrependUnique(CCFLAGS=['-g'])
</pre><p>
In the above example,
the <code class="literal">-g</code> would be added
only if the <code class="envar">$CCFLAGS</code> variable
does not already contain a <code class="literal">-g</code> value.
</p></div></div><div class="section" title="7.3.<2E>Controlling the Execution Environment for Issued Commands"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="sect-execution-environments"></a>7.3.<2E>Controlling the Execution Environment for Issued Commands</h2></div></div></div><p>
When <span class="application">SCons</span> builds a target file,
it does not execute the commands with
the same external environment
that you used to execute <span class="application">SCons</span>.
Instead, it uses the dictionary
stored in the <a class="link" href="#cv-ENV"><code class="envar">$ENV</code></a> construction variable
as the external environment
for executing commands.
</p><p>
The most important ramification of this behavior
is that the <code class="varname">PATH</code> environment variable,
which controls where the operating system
will look for commands and utilities,
is not the same as in the external environment
from which you called <span class="application">SCons</span>.
This means that <span class="application">SCons</span> will not, by default,
necessarily find all of the tools
that you can execute from the command line.
</p><p>
The default value of the <code class="varname">PATH</code> environment variable
on a POSIX system
is <code class="literal">/usr/local/bin:/bin:/usr/bin</code>.
The default value of the <code class="varname">PATH</code> environment variable
on a Windows system comes from the Windows registry
value for the command interpreter.
If you want to execute any commands--compilers, linkers, etc.--that
are not in these default locations,
you need to set the <code class="varname">PATH</code> value
in the <code class="envar">$ENV</code> dictionary
in your construction environment.
</p><p>
The simplest way to do this is to initialize explicitly
the value when you create the construction environment;
this is one way to do that:
</p><pre class="programlisting">
path = ['/usr/local/bin', '/bin', '/usr/bin']
env = Environment(ENV = {'PATH' : path})
</pre><p>
Assign a dictionary to the <code class="envar">$ENV</code>
construction variable in this way
completely resets the external environment
so that the only variable that will be
set when external commands are executed
will be the <code class="varname">PATH</code> value.
If you want to use the rest of
the values in <code class="envar">$ENV</code> and only
set the value of <code class="varname">PATH</code>,
the most straightforward way is probably:
</p><pre class="programlisting">
env['ENV']['PATH'] = ['/usr/local/bin', '/bin', '/usr/bin']
</pre><p>
Note that <span class="application">SCons</span> does allow you to define
the directories in the <code class="varname">PATH</code> in a string,
separated by the pathname-separator character
for your system (':' on POSIX systems, ';' on Windows):
</p><pre class="programlisting">
env['ENV']['PATH'] = '/usr/local/bin:/bin:/usr/bin'
</pre><p>
But doing so makes your <code class="filename">SConscript</code> file less portable,
(although in this case that may not be a huge concern
since the directories you list are likely system-specific, anyway).
</p><div class="section" title="7.3.1.<2E>Propagating PATH From the External Environment"><div class="titlepage"><div><div><h3 class="title"><a name="idm1767"></a>7.3.1.<2E>Propagating <code class="varname">PATH</code> From the External Environment</h3></div></div></div><p>
You may want to propagate the external <code class="varname">PATH</code>
to the execution environment for commands.
You do this by initializing the <code class="varname">PATH</code>
variable with the <code class="varname">PATH</code> value from
the <code class="literal">os.environ</code>
dictionary,
which is Python's way of letting you
get at the external environment:
</p><pre class="programlisting">
import os
env = Environment(ENV = {'PATH' : os.environ['PATH']})
</pre><p>
Alternatively, you may find it easier
to just propagate the entire external
environment to the execution environment
for commands.
This is simpler to code than explicity
selecting the <code class="varname">PATH</code> value:
</p><pre class="programlisting">
import os
env = Environment(ENV = os.environ)
</pre><p>
Either of these will guarantee that
<span class="application">SCons</span> will be able to execute
any command that you can execute from the command line.
The drawback is that the build can behave
differently if it's run by people with
different <code class="varname">PATH</code> values in their environment--for example,
if both the <code class="literal">/bin</code> and
<code class="literal">/usr/local/bin</code> directories
have different <span class="application">cc</span> commands,
then which one will be used to compile programs
will depend on which directory is listed
first in the user's <code class="varname">PATH</code> variable.
</p></div><div class="section" title="7.3.2.<2E>Adding to PATH Values in the Execution Environment"><div class="titlepage"><div><div><h3 class="title"><a name="idm1786"></a>7.3.2.<2E>Adding to <code class="varname">PATH</code> Values in the Execution Environment</h3></div></div></div><p>
One of the most common requirements
for manipulating a variable in the execution environment
is to add one or more custom directories to a search
like the <code class="envar">$PATH</code> variable on Linux or POSIX systems,
or the <code class="envar">%PATH%</code> variable on Windows,
so that a locally-installed compiler or other utility
can be found when <span class="application">SCons</span> tries to execute it to update a target.
<span class="application">SCons</span> provides <code class="function">PrependENVPath</code> and <code class="function">AppendENVPath</code> functions
to make adding things to execution variables convenient.
You call these functions by specifying the variable
to which you want the value added,
and then value itself.
So to add some <code class="filename">/usr/local</code> directories
to the <code class="envar">$PATH</code> and <code class="envar">$LIB</code> variables,
you might:
</p><pre class="programlisting">
env = Environment(ENV = os.environ)
env.PrependENVPath('PATH', '/usr/local/bin')
env.AppendENVPath('LIB', '/usr/local/lib')
</pre><p>
Note that the added values are strings,
and if you want to add multiple directories to
a variable like <code class="envar">$PATH</code>,
you must include the path separate character
(<code class="literal">:</code> on Linux or POSIX,
<code class="literal">;</code> on Windows)
in the string.
</p></div></div><div class="section" title="7.4.<2E>Using the toolpath for external Tools"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="sect-environment-toolpath"></a>7.4.<2E>Using the toolpath for external Tools</h2></div></div></div><div class="section" title="7.4.1.<2E>The default tool search path"><div class="titlepage"><div><div><h3 class="title"><a name="idm1806"></a>7.4.1.<2E>The default tool search path</h3></div></div></div><p>
Normally when using a tool from the construction environment,
several different search locations are checked by default.
This includes the <code class="literal">Scons/Tools/</code> directory
inbuilt to scons and the directory <code class="literal">site_scons/site_tools</code>
relative to the root SConstruct file.
</p><pre class="programlisting">
# Builtin tool or tool located within site_tools
env = Environment(tools = ['SomeTool'])
env.SomeTool(targets, sources)
# The search locations would include by default
SCons/Tool/SomeTool.py
SCons/Tool/SomeTool/__init__.py
./site_scons/site_tools/SomeTool.py
./site_scons/site_tools/SomeTool/__init__.py
</pre></div><div class="section" title="7.4.2.<2E>Providing an external directory to toolpath"><div class="titlepage"><div><div><h3 class="title"><a name="idm1812"></a>7.4.2.<2E>Providing an external directory to toolpath</h3></div></div></div><p>
In some cases you may want to specify a different location to search for tools.
The Environment constructor contains an option for this called toolpath
This can be used to add additional search directories.
</p><pre class="programlisting">
# Tool located within the toolpath directory option
env = Environment(tools = ['SomeTool'], toolpath = ['/opt/SomeToolPath', '/opt/SomeToolPath2'])
env.SomeTool(targets, sources)
# The search locations in this example would include:
/opt/SomeToolPath/SomeTool.py
/opt/SomeToolPath/SomeTool/__init__.py
/opt/SomeToolPath2/SomeTool.py
/opt/SomeToolPath2/SomeTool/__init__.py
SCons/Tool/SomeTool.py
SCons/Tool/SomeTool/__init__.py
./site_scons/site_tools/SomeTool.py
./site_scons/site_tools/SomeTool/__init__.py
</pre></div><div class="section" title="7.4.3.<2E>Nested Tools within a toolpath"><div class="titlepage"><div><div><h3 class="title"><a name="idm1816"></a>7.4.3.<2E>Nested Tools within a toolpath</h3></div></div></div><p>
<span class="application">SCons</span> 3.0 now supports the ability for a Builder to be located
within a sub-directory / sub-package of the toolpath.
This is similar to namespacing within python.
With nested or namespaced tools we can use the dot notation
to specify a sub-directory that the tool is located under.
</p><pre class="programlisting">
# namespaced target
env = Environment(tools = ['SubDir1.SubDir2.SomeTool'], toolpath = ['/opt/SomeToolPath'])
env.SomeTool(targets, sources)
# With this example the search locations would include
/opt/SomeToolPath/SubDir1/SubDir2/SomeTool.py
/opt/SomeToolPath/SubDir1/SubDir2/SomeTool/__init__.py
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>
For python2 It's important to note when creating tools within sub-directories,
there needs to be a __init__.py file within each directory.
This file can just be empty.
This is the same constraint used by python when loading modules
from within sub-directories (packages).
For python3 this appears to be no longer a requirement.
</p></div><div class="section" title="7.4.4.<2E>Using sys.path within the toolpath"><div class="titlepage"><div><div><h3 class="title"><a name="idm1822"></a>7.4.4.<2E>Using sys.path within the toolpath</h3></div></div></div><p>
If we want to access tools externally to scons on the sys.path
(one example would be tools installed via the pip package manager)
One way to do this is to use sys.path with the toolpath.
One thing to watch out for with this approach is that sys.path
can sometimes contains paths to .egg files instead of directories.
So we need to filter those out with this approach.
</p><pre class="programlisting">
# namespaced target using sys.path within toolpath
searchpaths = []
for item in sys.path:
if os.path.isdir(item): searchpaths.append(item)
env = Environment(tools = ['someinstalledpackage.SomeTool'], toolpath = searchpaths)
env.SomeTool(targets, sources)
</pre><p>
By using sys.path with the toolpath argument
and by using the nested syntax we can have scons search
packages installed via pip for Tools.
</p><pre class="programlisting">
# For Windows based on the python version and install directory, this may be something like
C:\Python35\Lib\site-packages\someinstalledpackage\SomeTool.py
C:\Python35\Lib\site-packages\someinstalledpackage\SomeTool\__init__.py
# For Linux this could be something like:
/usr/lib/python3/dist-packages/someinstalledpackage/SomeTool.py
/usr/lib/python3/dist-packages/someinstalledpackage/SomeTool/__init__.py
</pre></div><div class="section" title="7.4.5.<2E>Using the PyPackageDir function to add to the toolpath"><div class="titlepage"><div><div><h3 class="title"><a name="idm1828"></a>7.4.5.<2E>Using the <code class="function">PyPackageDir</code> function to add to the toolpath</h3></div></div></div><p>
In some cases you may want to use a tool
located within a installed external pip package.
This is possible by the use of sys.path with the toolpath.
However in that situation you need to provide a prefix to the toolname
to indicate where it is located within sys.path
</p><pre class="programlisting">
searchpaths = []
for item in sys.path:
if os.path.isdir(item): searchpaths.append(item)
env = Environment(tools = ['tools_example.subdir1.subdir2.SomeTool'], toolpath = searchpaths)
env.SomeTool(targets, sources)
</pre><p>
To avoid the use of a prefix within the name of the tool or filtering sys.path for directories,
we can use the <code class="function">PyPackageDir(modulename)</code> function to locate the directory of the python package.
<code class="function">PyPackageDir</code> returns a Dir object which represents the path of the directory
for the python package / module specified as a parameter.
</p><pre class="programlisting">
# namespaced target using sys.path
env = Environment(tools = ['SomeTool'], toolpath = [PyPackageDir('tools_example.subdir1.subdir2')])
env.SomeTool(targets, sources)
</pre></div></div></div><div class="chapter" title="Chapter<65>8.<2E>Automatically Putting Command-line Options into their Construction Variables"><div class="titlepage"><div><div><h2 class="title"><a name="chap-manip-options"></a>Chapter<EFBFBD>8.<2E>Automatically Putting Command-line Options into their Construction Variables</h2></div></div></div><p>
This chapter describes the <code class="function">MergeFlags</code>, <code class="function">ParseFlags</code>, and <code class="function">ParseConfig</code> methods of a <code class="literal">construction environment</code>.
</p><div class="section" title="8.1.<2E>Merging Options into the Environment: the MergeFlags Function"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="sect-mergeflags"></a>8.1.<2E>Merging Options into the Environment: the <code class="function">MergeFlags</code> Function</h2></div></div></div><p>
<span class="application">SCons</span> construction environments have a <code class="function">MergeFlags</code> method
that merges a dictionary of values into the construction environment.
<code class="function">MergeFlags</code> treats each value in the dictionary
as a list of options such as one might pass to a command
(such as a compiler or linker).
<code class="function">MergeFlags</code> will not duplicate an option
if it already exists in the construction environment variable.
</p><p>
<code class="function">MergeFlags</code> tries to be intelligent about merging options.
When merging options to any variable
whose name ends in <code class="varname">PATH</code>,
<code class="function">MergeFlags</code> keeps the leftmost occurrence of the option,
because in typical lists of directory paths,
the first occurrence "wins."
When merging options to any other variable name,
<code class="function">MergeFlags</code> keeps the rightmost occurrence of the option,
because in a list of typical command-line options,
the last occurrence "wins."
</p><pre class="programlisting">
env = Environment()
env.Append(CCFLAGS = '-option -O3 -O1')
flags = { 'CCFLAGS' : '-whatever -O3' }
env.MergeFlags(flags)
print env['CCFLAGS']
</pre><pre class="screen">% <strong class="userinput"><code>scons -Q</code></strong>
['-option', '-O1', '-whatever', '-O3']
scons: `.' is up to date.
</pre><p>
Note that the default value for <a class="link" href="#cv-CCFLAGS"><code class="envar">$CCFLAGS</code></a>
is an internal <span class="application">SCons</span> object
which automatically converts
the options we specified as a string into a list.
</p><pre class="programlisting">
env = Environment()
env.Append(CPPPATH = ['/include', '/usr/local/include', '/usr/include'])
flags = { 'CPPPATH' : ['/usr/opt/include', '/usr/local/include'] }
env.MergeFlags(flags)
print env['CPPPATH']
</pre><pre class="screen">% <strong class="userinput"><code>scons -Q</code></strong>
['/include', '/usr/local/include', '/usr/include', '/usr/opt/include']
scons: `.' is up to date.
</pre><p>
Note that the default value for <a class="link" href="#cv-CPPPATH"><code class="envar">$CPPPATH</code></a>
is a normal Python list,
so we must specify its values as a list
in the dictionary we pass to the <code class="function">MergeFlags</code> function.
</p><p>
If <code class="function">MergeFlags</code> is passed anything other than a dictionary,
it calls the <code class="function">ParseFlags</code> method to convert it into a dictionary.
</p><pre class="programlisting">
env = Environment()
env.Append(CCFLAGS = '-option -O3 -O1')
env.Append(CPPPATH = ['/include', '/usr/local/include', '/usr/include'])
env.MergeFlags('-whatever -I/usr/opt/include -O3 -I/usr/local/include')
print env['CCFLAGS']
print env['CPPPATH']
</pre><pre class="screen">% <strong class="userinput"><code>scons -Q</code></strong>
['-option', '-O1', '-whatever', '-O3']
['/include', '/usr/local/include', '/usr/include', '/usr/opt/include']
scons: `.' is up to date.
</pre><p>
In the combined example above,
<code class="function">ParseFlags</code> has sorted the options into their corresponding variables
and returned a dictionary for <code class="function">MergeFlags</code> to apply
to the construction variables
in the specified construction environment.
</p></div><div class="section" title="8.2.<2E>Separating Compile Arguments into their Variables: the ParseFlags Function"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="sect-parseflags"></a>8.2.<2E>Separating Compile Arguments into their Variables: the <code class="function">ParseFlags</code> Function</h2></div></div></div><p>
<span class="application">SCons</span> has a bewildering array of construction variables
for different types of options when building programs.
Sometimes you may not know exactly which variable
should be used for a particular option.
</p><p>
<span class="application">SCons</span> construction environments have a <code class="function">ParseFlags</code> method
that takes a set of typical command-line options
and distributes them into the appropriate construction variables.
Historically, it was created to support the <code class="function">ParseConfig</code> method,
so it focuses on options used by the GNU Compiler Collection (GCC)
for the C and C++ toolchains.
</p><p>
<code class="function">ParseFlags</code> returns a dictionary containing the options
distributed into their respective construction variables.
Normally, this dictionary would be passed to <code class="function">MergeFlags</code>
to merge the options into a <code class="literal">construction environment</code>,
but the dictionary can be edited if desired to provide
additional functionality.
(Note that if the flags are not going to be edited,
calling <code class="function">MergeFlags</code> with the options directly
will avoid an additional step.)
</p><pre class="programlisting">
env = Environment()
d = env.ParseFlags("-I/opt/include -L/opt/lib -lfoo")
for k,v in sorted(d.items()):
if v:
print k, v
env.MergeFlags(d)
env.Program('f1.c')
</pre><pre class="screen">% <strong class="userinput"><code>scons -Q</code></strong>
CPPPATH ['/opt/include']
LIBPATH ['/opt/lib']
LIBS ['foo']
cc -o f1.o -c -I/opt/include f1.c
cc -o f1 f1.o -L/opt/lib -lfoo
</pre><p>
Note that if the options are limited to generic types
like those above,
they will be correctly translated for other platform types:
</p><pre class="screen">C:\&gt;<strong class="userinput"><code>scons -Q</code></strong>
CPPPATH ['/opt/include']
LIBPATH ['/opt/lib']
LIBS ['foo']
cl /Fof1.obj /c f1.c /nologo /I\opt\include
link /nologo /OUT:f1.exe /LIBPATH:\opt\lib foo.lib f1.obj
embedManifestExeCheck(target, source, env)
</pre><p>
Since the assumption is that the flags are used for the GCC toolchain,
unrecognized flags are placed in <a class="link" href="#cv-CCFLAGS"><code class="envar">$CCFLAGS</code></a>
so they will be used for both C and C++ compiles:
</p><pre class="programlisting">
env = Environment()
d = env.ParseFlags("-whatever")
for k,v in sorted(d.items()):
if v:
print k, v
env.MergeFlags(d)
env.Program('f1.c')
</pre><pre class="screen">% <strong class="userinput"><code>scons -Q</code></strong>
CCFLAGS -whatever
cc -o f1.o -c -whatever f1.c
cc -o f1 f1.o
</pre><p>
<code class="function">ParseFlags</code> will also accept a (recursive) list of strings as input;
the list is flattened before the strings are processed:
</p><pre class="programlisting">
env = Environment()
d = env.ParseFlags(["-I/opt/include", ["-L/opt/lib", "-lfoo"]])
for k,v in sorted(d.items()):
if v:
print k, v
env.MergeFlags(d)
env.Program('f1.c')
</pre><pre class="screen">% <strong class="userinput"><code>scons -Q</code></strong>
CPPPATH ['/opt/include']
LIBPATH ['/opt/lib']
LIBS ['foo']
cc -o f1.o -c -I/opt/include f1.c
cc -o f1 f1.o -L/opt/lib -lfoo
</pre><p>
If a string begins with a "!" (an exclamation mark, often called a bang),
the string is passed to the shell for execution.
The output of the command is then parsed:
</p><pre class="programlisting">
env = Environment()
d = env.ParseFlags(["!echo -I/opt/include", "!echo -L/opt/lib", "-lfoo"])
for k,v in sorted(d.items()):
if v:
print k, v
env.MergeFlags(d)
env.Program('f1.c')
</pre><pre class="screen">% <strong class="userinput"><code>scons -Q</code></strong>
CPPPATH ['/opt/include']
LIBPATH ['/opt/lib']
LIBS ['foo']
cc -o f1.o -c -I/opt/include f1.c
cc -o f1 f1.o -L/opt/lib -lfoo
</pre><p>
<code class="function">ParseFlags</code> is regularly updated for new options;
consult the man page for details about those currently recognized.
</p></div><div class="section" title="8.3.<2E>Finding Installed Library Information: the ParseConfig Function"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="sect-parseconfig"></a>8.3.<2E>Finding Installed Library Information: the <code class="function">ParseConfig</code> Function</h2></div></div></div><p>
Configuring the right options to build programs to work with
libraries--especially shared libraries--that are available
on POSIX systems can be very complicated.
To help this situation,
various utilies with names that end in <code class="filename">config</code>
return the command-line options for the GNU Compiler Collection (GCC)
that are needed to use these libraries;
for example, the command-line options
to use a library named <code class="filename">lib</code>
would be found by calling a utility named <code class="filename">lib-config</code>.
</p><p>
A more recent convention is that these options
are available from the generic <code class="filename">pkg-config</code> program,
which has common framework, error handling, and the like,
so that all the package creator has to do is provide the set of strings
for his particular package.
</p><p>
<span class="application">SCons</span> construction environments have a <code class="function">ParseConfig</code> method
that executes a <code class="filename">*config</code> utility
(either <code class="filename">pkg-config</code> or a
more specific utility)
and configures the appropriate construction variables
in the environment
based on the command-line options
returned by the specified command.
</p><pre class="programlisting">
env = Environment()
env['CPPPATH'] = ['/lib/compat']
env.ParseConfig("pkg-config x11 --cflags --libs")
print env['CPPPATH']
</pre><p>
<span class="application">SCons</span> will execute the specified command string,
parse the resultant flags,
and add the flags to the appropriate environment variables.
</p><pre class="screen">
% <strong class="userinput"><code>scons -Q</code></strong>
['/lib/compat', '/usr/X11/include']
scons: `.' is up to date.
</pre><p>
In the example above, <span class="application">SCons</span> has added the include directory to
<code class="varname">CPPPATH</code>.
(Depending upon what other flags are emitted by the
<code class="filename">pkg-config</code> command,
other variables may have been extended as well.)
</p><p>
Note that the options are merged with existing options using
the <code class="function">MergeFlags</code> method,
so that each option only occurs once in the construction variable:
</p><pre class="programlisting">
env = Environment()
env.ParseConfig("pkg-config x11 --cflags --libs")
env.ParseConfig("pkg-config x11 --cflags --libs")
print env['CPPPATH']
</pre><pre class="screen">
% <strong class="userinput"><code>scons -Q</code></strong>
['/usr/X11/include']
scons: `.' is up to date.
</pre></div></div><div class="chapter" title="Chapter<65>9.<2E>Controlling Build Output"><div class="titlepage"><div><div><h2 class="title"><a name="chap-output"></a>Chapter<EFBFBD>9.<2E>Controlling Build Output</h2></div></div></div><p>
A key aspect of creating a usable build configuration
is providing good output from the build
so its users can readily understand
what the build is doing
and get information about how to control the build.
<span class="application">SCons</span> provides several ways of
controlling output from the build configuration
to help make the build
more useful and understandable.
</p><div class="section" title="9.1.<2E>Providing Build Help: the Help Function"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idm1949"></a>9.1.<2E>Providing Build Help: the <code class="function">Help</code> Function</h2></div></div></div><p>
It's often very useful to be able to give
users some help that describes the
specific targets, build options, etc.,
that can be used for your build.
<span class="application">SCons</span> provides the <code class="function">Help</code> function
to allow you to specify this help text:
</p><pre class="programlisting">
Help("""
Type: 'scons program' to build the production program,
'scons debug' to build the debug version.
""")
</pre><p>
Optionally, one can specify the append flag:
</p><pre class="programlisting">
Help("""
Type: 'scons program' to build the production program,
'scons debug' to build the debug version.
""", append=True)
</pre><p>
(Note the above use of the Python triple-quote syntax,
which comes in very handy for
specifying multi-line strings like help text.)
</p><p>
When the <code class="filename">SConstruct</code> or <code class="filename">SConscript</code> files
contain such a call to the <code class="function">Help</code> function,
the specified help text will be displayed in response to
the <span class="application">SCons</span> <code class="literal">-h</code> option:
</p><pre class="screen">% <strong class="userinput"><code>scons -h</code></strong>
scons: Reading SConscript files ...
scons: done reading SConscript files.
Type: 'scons program' to build the production program,
'scons debug' to build the debug version.
Use scons -H for help about command-line options.
</pre><p>
The <code class="filename">SConscript</code> files may contain
multiple calls to the <code class="function">Help</code> function,
in which case the specified text(s)
will be concatenated when displayed.
This allows you to split up the
help text across multiple <code class="filename">SConscript</code> files.
In this situation, the order in
which the <code class="filename">SConscript</code> files are called
will determine the order in which the <code class="function">Help</code> functions are called,
which will determine the order in which
the various bits of text will get concatenated.
</p><p>
When used with <code class="function">AddOption</code> Help("text", append=False) will clobber any help output associated with AddOption().
To preserve the help output from AddOption(), set append=True.
</p><p>
Another use would be to make the help text conditional
on some variable.
For example, suppose you only want to display
a line about building a Windows-only
version of a program when actually
run on Windows.
The following <code class="filename">SConstruct</code> file:
</p><pre class="programlisting">
env = Environment()
Help("\nType: 'scons program' to build the production program.\n")
if env['PLATFORM'] == 'win32':
Help("\nType: 'scons windebug' to build the Windows debug version.\n")
</pre><p>
Will display the complete help text on Windows:
</p><pre class="screen">C:\&gt;<strong class="userinput"><code>scons -h</code></strong>
scons: Reading SConscript files ...
scons: done reading SConscript files.
Type: 'scons program' to build the production program.
Type: 'scons windebug' to build the Windows debug version.
Use scons -H for help about command-line options.
</pre><p>
But only show the relevant option on a Linux or UNIX system:
</p><pre class="screen">% <strong class="userinput"><code>scons -h</code></strong>
scons: Reading SConscript files ...
scons: done reading SConscript files.
Type: 'scons program' to build the production program.
Use scons -H for help about command-line options.
</pre><p>
If there is no <code class="function">Help</code> text in the <code class="filename">SConstruct</code> or
<code class="filename">SConscript</code> files,
<span class="application">SCons</span> will revert to displaying its
standard list that describes the <span class="application">SCons</span> command-line
options.
This list is also always displayed whenever
the <code class="literal">-H</code> option is used.
</p></div><div class="section" title="9.2.<2E>Controlling How SCons Prints Build Commands: the $*COMSTR Variables"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idm1991"></a>9.2.<2E>Controlling How <span class="application">SCons</span> Prints Build Commands: the <code class="envar">$*COMSTR</code> Variables</h2></div></div></div><p>
Sometimes the commands executed
to compile object files or link programs
(or build other targets)
can get very long,
long enough to make it difficult for users
to distinguish error messages or
other important build output
from the commands themselves.
All of the default <code class="envar">$*COM</code> variables
that specify the command lines
used to build various types of target files
have a corresponding <code class="envar">$*COMSTR</code> variable
that can be set to an alternative
string that will be displayed
when the target is built.
</p><p>
For example, suppose you want to
have <span class="application">SCons</span> display a
<code class="literal">"Compiling"</code>
message whenever it's compiling an object file,
and a
<code class="literal">"Linking"</code>
when it's linking an executable.
You could write a <code class="filename">SConstruct</code> file
that looks like:
</p><pre class="programlisting">
env = Environment(CCCOMSTR = "Compiling $TARGET",
LINKCOMSTR = "Linking $TARGET")
env.Program('foo.c')
</pre><p>
Which would then yield the output:
</p><pre class="screen">
% <strong class="userinput"><code>scons -Q</code></strong>
Compiling foo.o
Linking foo
</pre><p>
<span class="application">SCons</span> performs complete variable substitution
on <code class="envar">$*COMSTR</code> variables,
so they have access to all of the
standard variables like <code class="envar">$TARGET</code> <code class="envar">$SOURCES</code>, etc.,
as well as any construction variables
that happen to be configured in
the construction environment
used to build a specific target.
</p><p>
Of course, sometimes it's still important to
be able to see the exact command
that <span class="application">SCons</span> will execute to build a target.
For example, you may simply need to verify
that <span class="application">SCons</span> is configured to supply
the right options to the compiler,
or a developer may want to
cut-and-paste a compile command
to add a few options
for a custom test.
</p><p>
One common way to give users
control over whether or not
<span class="application">SCons</span> should print the actual command line
or a short, configured summary
is to add support for a
<code class="varname">VERBOSE</code>
command-line variable to your <code class="filename">SConstruct</code> file.
A simple configuration for this might look like:
</p><pre class="programlisting">
env = Environment()
if ARGUMENTS.get('VERBOSE') != "1':
env['CCCOMSTR'] = "Compiling $TARGET"
env['LINKCOMSTR'] = "Linking $TARGET"
env.Program('foo.c')
</pre><p>
By only setting the appropriate
<code class="envar">$*COMSTR</code> variables
if the user specifies
<code class="literal">VERBOSE=1</code>
on the command line,
the user has control
over how <span class="application">SCons</span>
displays these particular command lines:
</p><pre class="screen">
% <strong class="userinput"><code>scons -Q</code></strong>
Compiling foo.o
Linking foo
% <strong class="userinput"><code>scons -Q -c</code></strong>
Removed foo.o
Removed foo
% <strong class="userinput"><code>scons -Q VERBOSE=1</code></strong>
cc -o foo.o -c foo.c
cc -o foo foo.o
</pre></div><div class="section" title="9.3.<2E>Providing Build Progress Output: the Progress Function"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idm2028"></a>9.3.<2E>Providing Build Progress Output: the <code class="function">Progress</code> Function</h2></div></div></div><p>
Another aspect of providing good build output
is to give the user feedback
about what <span class="application">SCons</span> is doing
even when nothing is being built at the moment.
This can be especially true for large builds
when most of the targets are already up-to-date.
Because <span class="application">SCons</span> can take a long time
making absolutely sure that every
target is, in fact, up-to-date
with respect to a lot of dependency files,
it can be easy for users to mistakenly
conclude that <span class="application">SCons</span> is hung
or that there is some other problem with the build.
</p><p>
One way to deal with this perception
is to configure <span class="application">SCons</span> to print something to
let the user know what it's "thinking about."
The <code class="function">Progress</code> function
allows you to specify a string
that will be printed for every file
that <span class="application">SCons</span> is "considering"
while it is traversing the dependency graph
to decide what targets are or are not up-to-date.
</p><pre class="programlisting">
Progress('Evaluating $TARGET\n')
Program('f1.c')
Program('f2.c')
</pre><p>
Note that the <code class="function">Progress</code> function does not
arrange for a newline to be printed automatically
at the end of the string (as does the Python
<code class="literal">print</code> statement),
and we must specify the
<code class="literal">\n</code>
that we want printed at the end of the configured string.
This configuration, then,
will have <span class="application">SCons</span>
print that it is <code class="literal">Evaluating</code>
each file that it encounters
in turn as it traverses the dependency graph:
</p><pre class="screen">% <strong class="userinput"><code>scons -Q</code></strong>
Evaluating SConstruct
Evaluating f1.c
Evaluating f1.o
cc -o f1.o -c f1.c
Evaluating f1
cc -o f1 f1.o
Evaluating f2.c
Evaluating f2.o
cc -o f2.o -c f2.c
Evaluating f2
cc -o f2 f2.o
Evaluating .
</pre><p>
Of course, normally you don't want to add
all of these additional lines to your build output,
as that can make it difficult for the user
to find errors or other important messages.
A more useful way to display
this progress might be
to have the file names printed
directly to the user's screen,
not to the same standard output
stream where build output is printed,
and to use a carriage return character
(<code class="literal">\r</code>)
so that each file name gets re-printed on the same line.
Such a configuration would look like:
</p><pre class="programlisting">
Progress('$TARGET\r',
file=open('/dev/tty', 'w'),
overwrite=True)
Program('f1.c')
Program('f2.c')
</pre><p>
Note that we also specified the
<code class="literal">overwrite=True</code> argument
to the <code class="function">Progress</code> function,
which causes <span class="application">SCons</span> to
"wipe out" the previous string with space characters
before printing the next <code class="function">Progress</code> string.
Without the
<code class="literal">overwrite=True</code> argument,
a shorter file name would not overwrite
all of the charactes in a longer file name that
precedes it,
making it difficult to tell what the
actual file name is on the output.
Also note that we opened up the
<code class="filename">/dev/tty</code> file
for direct access (on POSIX) to
the user's screen.
On Windows, the equivalent would be to open
the <code class="filename">con:</code> file name.
</p><p>
Also, it's important to know that although you can use
<code class="literal">$TARGET</code> to substitute the name of
the node in the string,
the <code class="function">Progress</code> function does <span class="emphasis"><em>not</em></span>
perform general variable substitution
(because there's not necessarily a construction
environment involved in evaluating a node
like a source file, for example).
</p><p>
You can also specify a list of strings
to the <code class="function">Progress</code> function,
in which case <span class="application">SCons</span> will
display each string in turn.
This can be used to implement a "spinner"
by having <span class="application">SCons</span> cycle through a
sequence of strings:
</p><pre class="programlisting">
Progress(['-\r', '\\\r', '|\r', '/\r'], interval=5)
Program('f1.c')
Program('f2.c')
</pre><p>
Note that here we have also used the
<code class="literal">interval=</code>
keyword argument to have <span class="application">SCons</span>
only print a new "spinner" string
once every five evaluated nodes.
Using an <code class="literal">interval=</code> count,
even with strings that use <code class="literal">$TARGET</code> like
our examples above,
can be a good way to lessen the
work that <span class="application">SCons</span> expends printing <code class="function">Progress</code> strings,
while still giving the user feedback
that indicates <span class="application">SCons</span> is still
working on evaluating the build.
</p><p>
Lastly, you can have direct control
over how to print each evaluated node
by passing a Python function
(or other Python callable)
to the <code class="function">Progress</code> function.
Your function will be called
for each evaluated node,
allowing you to
implement more sophisticated logic
like adding a counter:
</p><pre class="programlisting">
screen = open('/dev/tty', 'w')
count = 0
def progress_function(node)
count += 1
screen.write('Node %4d: %s\r' % (count, node))
Progress(progress_function)
</pre><p>
Of course, if you choose,
you could completely ignore the
<code class="varname">node</code> argument to the function,
and just print a count,
or anything else you wish.
</p><p>
(Note that there's an obvious follow-on question here:
how would you find the total number of nodes
that <span class="emphasis"><em>will be</em></span>
evaluated so you can tell the user how
close the build is to finishing?
Unfortunately, in the general case,
there isn't a good way to do that,
short of having <span class="application">SCons</span> evaluate its
dependency graph twice,
first to count the total and
the second time to actually build the targets.
This would be necessary because
you can't know in advance which
target(s) the user actually requested
to be built.
The entire build may consist of thousands of Nodes,
for example,
but maybe the user specifically requested
that only a single object file be built.)
</p></div><div class="section" title="9.4.<2E>Printing Detailed Build Status: the GetBuildFailures Function"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idm2084"></a>9.4.<2E>Printing Detailed Build Status: the <code class="function">GetBuildFailures</code> Function</h2></div></div></div><p>
SCons, like most build tools, returns zero status to
the shell on success and nonzero status on failure.
Sometimes it's useful to give more information about
the build status at the end of the run, for instance
to print an informative message, send an email, or
page the poor slob who broke the build.
</p><p>
SCons provides a <code class="function">GetBuildFailures</code> method that
you can use in a python <code class="function">atexit</code> function
to get a list of objects describing the actions that failed
while attempting to build targets. There can be more
than one if you're using <code class="literal">-j</code>. Here's a
simple example:
</p><pre class="programlisting">
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><p>
The <code class="function">atexit.register</code> call
registers <code class="function">print_build_failures</code>
as an <code class="function">atexit</code> callback, to be called
before <span class="application">SCons</span> exits. When that function is called,
it calls <code class="function">GetBuildFailures</code> to fetch the list of failed objects.
See the man page
for the detailed contents of the returned objects;
some of the more useful attributes are
<code class="literal">.node</code>,
<code class="literal">.errstr</code>,
<code class="literal">.filename</code>, and
<code class="literal">.command</code>.
The <code class="literal">filename</code> is not necessarily
the same file as the <code class="literal">node</code>; the
<code class="literal">node</code> is the target that was
being built when the error occurred, while the
<code class="literal">filename</code>is the file or dir that
actually caused the error.
Note: only call <code class="function">GetBuildFailures</code> at the end of the
build; calling it at any other time is undefined.
</p><p>
Here is a more complete example showing how to
turn each element of <code class="function">GetBuildFailures</code> into a string:
</p><pre class="programlisting">
# Make the build fail if we pass fail=1 on the command line
if ARGUMENTS.get('fail', 0):
Command('target', 'source', ['/bin/false'])
def bf_to_str(bf):
"""Convert an element of GetBuildFailures() to a string
in a useful way."""
import SCons.Errors
if bf is None: # unknown targets product None in list
return '(unknown tgt)'
elif isinstance(bf, SCons.Errors.StopError):
return str(bf)
elif bf.node:
return str(bf.node) + ': ' + bf.errstr
elif bf.filename:
return bf.filename + ': ' + bf.errstr
return 'unknown failure: ' + bf.errstr
import atexit
def build_status():
"""Convert the build status to a 2-tuple, (status, msg)."""
from SCons.Script import GetBuildFailures
bf = GetBuildFailures()
if bf:
# bf is normally a list of build failures; if an element is None,
# it's because of a target that scons doesn't know anything about.
status = 'failed'
failures_message = "\n".join(["Failed building %s" % bf_to_str(x)
for x in bf if x is not None])
else:
# if bf is None, the build completed successfully.
status = 'ok'
failures_message = ''
return (status, failures_message)
def display_build_status():
"""Display the build status. Called by atexit.
Here you could do all kinds of complicated things."""
status, failures_message = build_status()
if status == 'failed':
print("FAILED!!!!") # could display alert, ring bell, etc.
elif status == 'ok':
print("Build succeeded.")
print(failures_message)
atexit.register(display_build_status)
</pre><p>
When this runs, you'll see the appropriate output:
</p><pre class="screen">% <strong class="userinput"><code>scons -Q</code></strong>
scons: `.' is up to date.
Build succeeded.
% <strong class="userinput"><code>scons -Q fail=1</code></strong>
scons: *** [target] Source `source' not found, needed by target `target'.
FAILED!!!!
Failed building target: Source `source' not found, needed by target `target'.
</pre></div></div><div class="chapter" title="Chapter<65>10.<2E>Controlling a Build From the Command Line"><div class="titlepage"><div><div><h2 class="title"><a name="chap-command-line"></a>Chapter<EFBFBD>10.<2E>Controlling a Build From the Command Line</h2></div></div></div><p>
<span class="application">SCons</span> provides a number of ways
for the writer of the <code class="filename">SConscript</code> files
to give the users who will run <span class="application">SCons</span>
a great deal of control over the build execution.
The arguments that the user can specify on
the command line are broken down into three types:
</p><div class="variablelist"><dl><dt><span class="term">Options</span></dt><dd><p>
Command-line options always begin with
one or two <code class="literal">-</code> (hyphen) characters.
<span class="application">SCons</span> provides ways for you to examine
and set options values from within your <code class="filename">SConscript</code> files,
as well as the ability to define your own
custom options.
See <a class="xref" href="#sect-command-line-options" title="10.1.<2E>Command-Line Options">Section<EFBFBD>10.1, &#8220;Command-Line Options&#8221;</a>, below.
</p></dd><dt><span class="term">Variables</span></dt><dd><p>
Any command-line argument containing an <code class="literal">=</code>
(equal sign) is considered a variable setting with the form
<code class="varname">variable</code>=<code class="varname">value</code>.
<span class="application">SCons</span> provides direct access to
all of the command-line variable settings,
the ability to apply command-line variable settings
to construction environments,
and functions for configuring
specific types of variables
(Boolean values, path names, etc.)
with automatic validation of the user's specified values.
See <a class="xref" href="#sect-command-line-variables" title="10.2.<2E>Command-Line variable=value Build Variables">Section<EFBFBD>10.2, &#8220;Command-Line <code class="varname">variable</code>=<code class="varname">value</code> Build Variables&#8221;</a>, below.
</p></dd><dt><span class="term">Targets</span></dt><dd><p>
Any command-line argument that is not an option
or a variable setting
(does not begin with a hyphen
and does not contain an equal sign)
is considered a target that the user
(presumably) wants <span class="application">SCons</span> to build.
A list of Node objects representing
the target or targets to build.
<span class="application">SCons</span> provides access to the list of specified targets,
as well as ways to set the default list of targets
from within the <code class="filename">SConscript</code> files.
See <a class="xref" href="#sect-command-line-targets" title="10.3.<2E>Command-Line Targets">Section<EFBFBD>10.3, &#8220;Command-Line Targets&#8221;</a>, below.
</p></dd></dl></div><div class="section" title="10.1.<2E>Command-Line Options"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="sect-command-line-options"></a>10.1.<2E>Command-Line Options</h2></div></div></div><p>
<span class="application">SCons</span> has many <span class="emphasis"><em>command-line options</em></span>
that control its behavior.
A <span class="application">SCons</span> <span class="emphasis"><em>command-line option</em></span>
always begins with one or two <code class="literal">-</code> (hyphen)
characters.
</p><div class="section" title="10.1.1.<2E>Not Having to Specify Command-Line Options Each Time: the SCONSFLAGS Environment Variable"><div class="titlepage"><div><div><h3 class="title"><a name="idm2155"></a>10.1.1.<2E>Not Having to Specify Command-Line Options Each Time: the <code class="varname">SCONSFLAGS</code> Environment Variable</h3></div></div></div><p>
Users may find themselves supplying
the same command-line options every time
they run <span class="application">SCons</span>.
For example, you might find it saves time
to specify a value of <code class="literal">-j 2</code>
to have <span class="application">SCons</span> run up to two build commands in parallel.
To avoid having to type <code class="literal">-j 2</code> by hand
every time,
you can set the external environment variable
<code class="varname">SCONSFLAGS</code> to a string containing
command-line options that you want <span class="application">SCons</span> to use.
</p><p>
If, for example,
you're using a POSIX shell that's
compatible with the Bourne shell,
and you always want <span class="application">SCons</span> to use the
<code class="literal">-Q</code> option,
you can set the <code class="varname">SCONSFLAGS</code>
environment as follows:
</p><pre class="screen">% <strong class="userinput"><code>scons</code></strong>
scons: Reading SConscript files ...
scons: done reading SConscript files.
scons: Building targets ...
... [build output] ...
scons: done building targets.
% <strong class="userinput"><code>export SCONSFLAGS="-Q"</code></strong>
% <strong class="userinput"><code>scons</code></strong>
... [build output] ...
</pre><p>
Users of <span class="application">csh</span>-style shells on POSIX systems
can set the <code class="varname">SCONSFLAGS</code> environment as follows:
</p><pre class="screen">
$ <strong class="userinput"><code>setenv SCONSFLAGS "-Q"</code></strong>
</pre><p>
Windows users may typically want to set the
<code class="varname">SCONSFLAGS</code> in the appropriate tab of the
<code class="literal">System Properties</code> window.
</p></div><div class="section" title="10.1.2.<2E>Getting Values Set by Command-Line Options: the GetOption Function"><div class="titlepage"><div><div><h3 class="title"><a name="idm2181"></a>10.1.2.<2E>Getting Values Set by Command-Line Options: the <code class="function">GetOption</code> Function</h3></div></div></div><p>
<span class="application">SCons</span> provides the <code class="function">GetOption</code> function
to get the values set by the various command-line options.
One common use of this is to check whether or not
the <code class="literal">-h</code> or <code class="literal">--help</code> option
has been specified.
Normally, <span class="application">SCons</span> does not print its help text
until after it has read all of the <code class="filename">SConscript</code> files,
because it's possible that help text has been added
by some subsidiary <code class="filename">SConscript</code> file deep in the
source tree hierarchy.
Of course, reading all of the <code class="filename">SConscript</code> files
takes extra time.
</p><p>
If you know that your configuration does not define
any additional help text in subsidiary <code class="filename">SConscript</code> files,
you can speed up the command-line help available to users
by using the <code class="function">GetOption</code> function to load the
subsidiary <code class="filename">SConscript</code> files only if the
the user has <span class="emphasis"><em>not</em></span> specified
the <code class="literal">-h</code> or <code class="literal">--help</code> option,
like so:
</p><pre class="programlisting">
if not GetOption('help'):
SConscript('src/SConscript', export='env')
</pre><p>
In general, the string that you pass to the
<code class="function">GetOption</code> function to fetch the value of a command-line
option setting is the same as the "most common" long option name
(beginning with two hyphen characters),
although there are some exceptions.
The list of <span class="application">SCons</span> command-line options
and the <code class="function">GetOption</code> strings for fetching them,
are available in the
<a class="xref" href="#sect-command-line-option-strings" title="10.1.4.<2E>Strings for Getting or Setting Values of SCons Command-Line Options">Section<EFBFBD>10.1.4, &#8220;Strings for Getting or Setting Values of <span class="application">SCons</span> Command-Line Options&#8221;</a> section,
below.
</p></div><div class="section" title="10.1.3.<2E>Setting Values of Command-Line Options: the SetOption Function"><div class="titlepage"><div><div><h3 class="title"><a name="idm2206"></a>10.1.3.<2E>Setting Values of Command-Line Options: the <code class="function">SetOption</code> Function</h3></div></div></div><p>
You can also set the values of <span class="application">SCons</span>
command-line options from within the <code class="filename">SConscript</code> files
by using the <code class="function">SetOption</code> function.
The strings that you use to set the values of <span class="application">SCons</span>
command-line options are available in the
<a class="xref" href="#sect-command-line-option-strings" title="10.1.4.<2E>Strings for Getting or Setting Values of SCons Command-Line Options">Section<EFBFBD>10.1.4, &#8220;Strings for Getting or Setting Values of <span class="application">SCons</span> Command-Line Options&#8221;</a> section,
below.
</p><p>
One use of the <code class="function">SetOption</code> function is to
specify a value for the <code class="literal">-j</code>
or <code class="literal">--jobs</code> option,
so that users get the improved performance
of a parallel build without having to specify the option by hand.
A complicating factor is that a good value
for the <code class="literal">-j</code> option is
somewhat system-dependent.
One rough guideline is that the more processors
your system has,
the higher you want to set the
<code class="literal">-j</code> value,
in order to take advantage of the number of CPUs.
</p><p>
For example, suppose the administrators
of your development systems
have standardized on setting a
<code class="varname">NUM_CPU</code> environment variable
to the number of processors on each system.
A little bit of Python code
to access the environment variable
and the <code class="function">SetOption</code> function
provide the right level of flexibility:
</p><pre class="programlisting">
import os
num_cpu = int(os.environ.get('NUM_CPU', 2))
SetOption('num_jobs', num_cpu)
print("running with -j %s"%GetOption('num_jobs'))
</pre><p>
The above snippet of code
sets the value of the <code class="literal">--jobs</code> option
to the value specified in the
<code class="varname">$NUM_CPU</code> environment variable.
(This is one of the exception cases
where the string is spelled differently from
the from command-line option.
The string for fetching or setting the <code class="literal">--jobs</code>
value is <code class="literal">num_jobs</code>
for historical reasons.)
The code in this example prints the <code class="literal">num_jobs</code>
value for illustrative purposes.
It uses a default value of <code class="literal">2</code>
to provide some minimal parallelism even on
single-processor systems:
</p><pre class="screen">% <strong class="userinput"><code>scons -Q</code></strong>
running with -j 2
scons: `.' is up to date.
</pre><p>
But if the <code class="varname">$NUM_CPU</code>
environment variable is set,
then we use that for the default number of jobs:
</p><pre class="screen">% <strong class="userinput"><code>export NUM_CPU="4"</code></strong>
% <strong class="userinput"><code>scons -Q</code></strong>
running with -j 4
scons: `.' is up to date.
</pre><p>
But any explicit
<code class="literal">-j</code> or <code class="literal">--jobs</code>
value the user specifies an the command line is used first,
regardless of whether or not
the <code class="varname">$NUM_CPU</code> environment
variable is set:
</p><pre class="screen">% <strong class="userinput"><code>scons -Q -j 7</code></strong>
running with -j 7
scons: `.' is up to date.
% <strong class="userinput"><code>export NUM_CPU="4"</code></strong>
% <strong class="userinput"><code>scons -Q -j 3</code></strong>
running with -j 3
scons: `.' is up to date.
</pre></div><div class="section" title="10.1.4.<2E>Strings for Getting or Setting Values of SCons Command-Line Options"><div class="titlepage"><div><div><h3 class="title"><a name="sect-command-line-option-strings"></a>10.1.4.<2E>Strings for Getting or Setting Values of <span class="application">SCons</span> Command-Line Options</h3></div></div></div><p>
The strings that you can pass to the <code class="function">GetOption</code>
and <code class="function">SetOption</code> functions usually correspond to the
first long-form option name
(beginning with two hyphen characters: <code class="literal">--</code>),
after replacing any remaining hyphen characters
with underscores.
</p><p>
The full list of strings and the variables they
correspond to is as follows:
</p><div class="informaltable"><table border="1"><colgroup><col><col></colgroup><thead><tr><th align="left">String for <code class="function">GetOption</code> and <code class="function">SetOption</code></th><th align="left">Command-Line Option(s)</th></tr></thead><tbody><tr><td align="left"><code class="literal">cache_debug</code></td><td align="left"><code class="option">--cache-debug</code></td></tr><tr><td align="left"><code class="literal">cache_disable</code></td><td align="left"><code class="option">--cache-disable</code></td></tr><tr><td align="left"><code class="literal">cache_force</code></td><td align="left"><code class="option">--cache-force</code></td></tr><tr><td align="left"><code class="literal">cache_show</code></td><td align="left"><code class="option">--cache-show</code></td></tr><tr><td align="left"><code class="literal">clean</code></td><td align="left"><code class="option">-c</code>,
<code class="option">--clean</code>,
<code class="option">--remove</code></td></tr><tr><td align="left"><code class="literal">config</code></td><td align="left"><code class="option">--config</code></td></tr><tr><td align="left"><code class="literal">directory</code></td><td align="left"><code class="option">-C</code>,
<code class="option">--directory</code></td></tr><tr><td align="left"><code class="literal">diskcheck</code></td><td align="left"><code class="option">--diskcheck</code></td></tr><tr><td align="left"><code class="literal">duplicate</code></td><td align="left"><code class="option">--duplicate</code></td></tr><tr><td align="left"><code class="literal">file</code></td><td align="left"><code class="option">-f</code>,
<code class="option">--file</code>,
<code class="option">--makefile </code>,
<code class="option">--sconstruct</code></td></tr><tr><td align="left"><code class="literal">help</code></td><td align="left"><code class="option">-h</code>,
<code class="option">--help</code></td></tr><tr><td align="left"><code class="literal">ignore_errors</code></td><td align="left"><code class="option">--ignore-errors</code></td></tr><tr><td align="left"><code class="literal">implicit_cache</code></td><td align="left"><code class="option">--implicit-cache</code></td></tr><tr><td align="left"><code class="literal">implicit_deps_changed</code></td><td align="left"><code class="option">--implicit-deps-changed</code></td></tr><tr><td align="left"><code class="literal">implicit_deps_unchanged</code></td><td align="left"><code class="option">--implicit-deps-unchanged</code></td></tr><tr><td align="left"><code class="literal">interactive</code></td><td align="left"><code class="option">--interact</code>,
<code class="option">--interactive</code></td></tr><tr><td align="left"><code class="literal">keep_going</code></td><td align="left"><code class="option">-k</code>,
<code class="option">--keep-going</code></td></tr><tr><td align="left"><code class="literal">max_drift</code></td><td align="left"><code class="option">--max-drift</code></td></tr><tr><td align="left"><code class="literal">no_exec</code></td><td align="left"><code class="option">-n</code>,
<code class="option">--no-exec</code>,
<code class="option">--just-print</code>,
<code class="option">--dry-run</code>,
<code class="option">--recon</code></td></tr><tr><td align="left"><code class="literal">no_site_dir</code></td><td align="left"><code class="option">--no-site-dir</code></td></tr><tr><td align="left"><code class="literal">num_jobs</code></td><td align="left"><code class="option">-j</code>,
<code class="option">--jobs</code></td></tr><tr><td align="left"><code class="literal">profile_file</code></td><td align="left"><code class="option">--profile</code></td></tr><tr><td align="left"><code class="literal">question</code></td><td align="left"><code class="option">-q</code>,
<code class="option">--question</code></td></tr><tr><td align="left"><code class="literal">random</code></td><td align="left"><code class="option">--random</code></td></tr><tr><td align="left"><code class="literal">repository</code></td><td align="left"><code class="option">-Y</code>,
<code class="option">--repository</code>,
<code class="option">--srcdir</code></td></tr><tr><td align="left"><code class="literal">silent</code></td><td align="left"><code class="option">-s</code>,
<code class="option">--silent</code>,
<code class="option">--quiet</code></td></tr><tr><td align="left"><code class="literal">site_dir</code></td><td align="left"><code class="option">--site-dir</code></td></tr><tr><td align="left"><code class="literal">stack_size</code></td><td align="left"><code class="option">--stack-size</code></td></tr><tr><td align="left"><code class="literal">taskmastertrace_file</code></td><td align="left"><code class="option">--taskmastertrace</code></td></tr><tr><td align="left"><code class="literal">warn</code></td><td align="left"><code class="option">--warn</code> <code class="option">--warning</code></td></tr></tbody></table></div></div><div class="section" title="10.1.5.<2E>Adding Custom Command-Line Options: the AddOption Function"><div class="titlepage"><div><div><h3 class="title"><a name="idm2434"></a>10.1.5.<2E>Adding Custom Command-Line Options: the <code class="function">AddOption</code> Function</h3></div></div></div><p>
<span class="application">SCons</span> also allows you to define your own
command-line options with the <code class="function">AddOption</code> function.
The <code class="function">AddOption</code> function takes the same arguments
as the <code class="function">optparse.add_option</code> function
from the standard Python library.
<sup>[<a name="idm2442" href="#ftn.idm2442" class="footnote">3</a>]</sup>
Once you have added a custom command-line option
with the <code class="function">AddOption</code> function,
the value of the option (if any) is immediately available
using the standard <code class="function">GetOption</code> function.
(The value can also be set using <code class="function">SetOption</code>,
although that's not very useful in practice
because a default value can be specified in
directly in the <code class="function">AddOption</code> call.)
</p><p>
One useful example of using this functionality
is to provide a <code class="option">--prefix</code> for users:
</p><pre class="programlisting">
AddOption('--prefix',
dest='prefix',
type='string',
nargs=1,
action='store',
metavar='DIR',
help='installation prefix')
env = Environment(PREFIX = GetOption('prefix'))
installed_foo = env.Install('$PREFIX/usr/bin', 'foo.in')
Default(installed_foo)
</pre><p>
The above code uses the <code class="function">GetOption</code> function
to set the <code class="varname">$PREFIX</code>
construction variable to any
value that the user specifies with a command-line
option of <code class="literal">--prefix</code>.
Because <code class="varname">$PREFIX</code>
will expand to a null string if it's not initialized,
running <span class="application">SCons</span> without the
option of <code class="literal">--prefix</code>
will install the file in the
<code class="filename">/usr/bin/</code> directory:
</p><pre class="screen">% <strong class="userinput"><code>scons -Q -n</code></strong>
Install file: "foo.in" as "/usr/bin/foo.in"
</pre><p>
But specifying <code class="literal">--prefix=/tmp/install</code>
on the command line causes the file to be installed in the
<code class="filename">/tmp/install/usr/bin/</code> directory:
</p><pre class="screen">% <strong class="userinput"><code>scons -Q -n --prefix=/tmp/install</code></strong>
Install file: "foo.in" as "/tmp/install/usr/bin/foo.in"
</pre></div></div><div class="section" title="10.2.<2E>Command-Line variable=value Build Variables"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="sect-command-line-variables"></a>10.2.<2E>Command-Line <code class="varname">variable</code>=<code class="varname">value</code> Build Variables</h2></div></div></div><p>
You may want to control various aspects
of your build by allowing the user
to specify <code class="varname">variable</code>=<code class="varname">value</code>
values on the command line.
For example, suppose you
want users to be able to
build a debug version of a program
by running <span class="application">SCons</span> as follows:
</p><pre class="screen">
% <strong class="userinput"><code>scons -Q debug=1</code></strong>
</pre><p>
<span class="application">SCons</span> provides an <code class="varname">ARGUMENTS</code> dictionary
that stores all of the
<code class="varname">variable</code>=<code class="varname">value</code>
assignments from the command line.
This allows you to modify
aspects of your build in response
to specifications on the command line.
(Note that unless you want to require
that users <span class="emphasis"><em>always</em></span>
specify a variable,
you probably want to use
the Python
<code class="literal">ARGUMENTS.get()</code> function,
which allows you to specify a default value
to be used if there is no specification
on the command line.)
</p><p>
The following code sets the <a class="link" href="#cv-CCFLAGS"><code class="envar">$CCFLAGS</code></a> construction
variable in response to the <code class="varname">debug</code>
flag being set in the <code class="varname">ARGUMENTS</code> dictionary:
</p><pre class="programlisting">
env = Environment()
debug = ARGUMENTS.get('debug', 0)
if int(debug):
env.Append(CCFLAGS = '-g')
env.Program('prog.c')
</pre><p>
This results in the <code class="varname">-g</code>
compiler option being used when
<code class="literal">debug=1</code>
is used on the command line:
</p><pre class="screen">% <strong class="userinput"><code>scons -Q debug=0</code></strong>
cc -o prog.o -c prog.c
cc -o prog prog.o
% <strong class="userinput"><code>scons -Q debug=0</code></strong>
scons: `.' is up to date.
% <strong class="userinput"><code>scons -Q debug=1</code></strong>
cc -o prog.o -c -g prog.c
cc -o prog prog.o
% <strong class="userinput"><code>scons -Q debug=1</code></strong>
scons: `.' is up to date.
</pre><p>
Notice that <span class="application">SCons</span> keeps track of
the last values used to build the object files,
and as a result correctly rebuilds
the object and executable files
only when the value of the <code class="literal">debug</code>
argument has changed.
</p><p>
The <code class="varname">ARGUMENTS</code> dictionary has two minor drawbacks.
First, because it is a dictionary,
it can only store one value for each specified keyword,
and thus only "remembers" the last setting
for each keyword on the command line.
This makes the <code class="varname">ARGUMENTS</code> dictionary
inappropriate if users should be able to
specify multiple values
on the command line for a given keyword.
Second, it does not preserve
the order in which the variable settings
were specified,
which is a problem if
you want the configuration to
behave differently in response
to the order in which the build
variable settings were specified on the command line.
</p><p>
To accomodate these requirements,
<span class="application">SCons</span> provides an <code class="varname">ARGLIST</code> variable
that gives you direct access to
<code class="varname">variable</code>=<code class="varname">value</code>
settings on the command line,
in the exact order they were specified,
and without removing any duplicate settings.
Each element in the <code class="varname">ARGLIST</code> variable
is itself a two-element list
containing the keyword and the value
of the setting,
and you must loop through,
or otherwise select from,
the elements of <code class="varname">ARGLIST</code> to
process the specific settings you want
in whatever way is appropriate for your configuration.
For example,
the following code to let the user
add to the <code class="varname">CPPDEFINES</code> construction variable
by specifying multiple
<code class="varname">define=</code>
settings on the command line:
</p><pre class="programlisting">
cppdefines = []
for key, value in ARGLIST:
if key == 'define':
cppdefines.append(value)
env = Environment(CPPDEFINES = cppdefines)
env.Object('prog.c')
</pre><p>
Yields the following output:
</p><pre class="screen">% <strong class="userinput"><code>scons -Q define=FOO</code></strong>
cc -o prog.o -c -DFOO prog.c
% <strong class="userinput"><code>scons -Q define=FOO define=BAR</code></strong>
cc -o prog.o -c -DFOO -DBAR prog.c
</pre><p>
Note that the <code class="varname">ARGLIST</code> and <code class="varname">ARGUMENTS</code>
variables do not interfere with each other,
but merely provide slightly different views
into how the user specified
<code class="varname">variable</code>=<code class="varname">value</code>
settings on the command line.
You can use both variables in the same
<span class="application">SCons</span> configuration.
In general, the <code class="varname">ARGUMENTS</code> dictionary
is more convenient to use,
(since you can just fetch variable
settings through a dictionary access),
and the <code class="varname">ARGLIST</code> list
is more flexible
(since you can examine the
specific order in which
the user's command-line variabe settings).
</p><div class="section" title="10.2.1.<2E>Controlling Command-Line Build Variables"><div class="titlepage"><div><div><h3 class="title"><a name="idm2527"></a>10.2.1.<2E>Controlling Command-Line Build Variables</h3></div></div></div><p>
Being able to use a command-line build variable like
<code class="literal">debug=1</code> is handy,
but it can be a chore to write specific Python code
to recognize each such variable,
check for errors and provide appropriate messages,
and apply the values to a construction variable.
To help with this,
<span class="application">SCons</span> supports a class to
define such build variables easily,
and a mechanism to apply the
build variables to a construction environment.
This allows you to control how the build variables affect
construction environments.
</p><p>
For example, suppose that you want users to set
a <code class="varname">RELEASE</code> construction variable on the
command line whenever the time comes to build
a program for release,
and that the value of this variable
should be added to the command line
with the appropriate <code class="literal">-D</code> option
(or other command line option)
to pass the value to the C compiler.
Here's how you might do that by setting
the appropriate value in a dictionary for the
<a class="link" href="#cv-CPPDEFINES"><code class="envar">$CPPDEFINES</code></a> construction variable:
</p><pre class="programlisting">
vars = Variables(None, ARGUMENTS)
vars.Add('RELEASE', 'Set to 1 to build for release', 0)
env = Environment(variables = vars,
CPPDEFINES={'RELEASE_BUILD' : '${RELEASE}'})
env.Program(['foo.c', 'bar.c'])
</pre><p>
This <code class="filename">SConstruct</code> file first creates a <code class="function">Variables</code> object
which uses the values from the command-line options dictionary <code class="varname">ARGUMENTS</code>
(the <code class="literal">vars = Variables(None, ARGUMENTS)</code> call).
It then uses the object's <code class="function">Add</code>
method to indicate that the <code class="varname">RELEASE</code>
variable can be set on the command line,
and that its default value will be <code class="literal">0</code>
(the third argument to the <code class="function">Add</code> method).
The second argument is a line of help text;
we'll learn how to use it in the next section.
</p><p>
We then pass the created <code class="function">Variables</code>
object as a <code class="varname">variables</code> keyword argument
to the <code class="function">Environment</code> call
used to create the construction environment.
This then allows a user to set the
<code class="varname">RELEASE</code> build variable on the command line
and have the variable show up in
the command line used to build each object from
a C source file:
</p><pre class="screen">% <strong class="userinput"><code>scons -Q RELEASE=1</code></strong>
cc -o bar.o -c -DRELEASE_BUILD=1 bar.c
cc -o foo.o -c -DRELEASE_BUILD=1 foo.c
cc -o foo foo.o bar.o
</pre><p>
NOTE: Before <span class="application">SCons</span> release 0.98.1, these build variables
were known as "command-line build options."
The class was actually named the <code class="function">Options</code> class,
and in the sections below,
the various functions were named
<code class="function">BoolOption</code>, <code class="function">EnumOption</code>, <code class="function">ListOption</code>,
<code class="function">PathOption</code>, <code class="function">PackageOption</code> and <code class="function">AddOptions</code>.
These older names still work,
and you may encounter them in older
<code class="filename">SConscript</code> files,
but they have been officially deprecated
as of <span class="application">SCons</span> version 2.0.
</p></div><div class="section" title="10.2.2.<2E>Providing Help for Command-Line Build Variables"><div class="titlepage"><div><div><h3 class="title"><a name="idm2565"></a>10.2.2.<2E>Providing Help for Command-Line Build Variables</h3></div></div></div><p>
To make command-line build variables most useful,
you ideally want to provide
some help text that will describe
the available variables
when the user runs <code class="literal">scons -h</code>.
You could write this text by hand,
but <span class="application">SCons</span> provides an easier way.
<code class="function">Variables</code> objects support a
<code class="function">GenerateHelpText</code> method
that will, as its name suggests,
generate text that describes
the various variables that
have been added to it.
You then pass the output from this method to
the <code class="function">Help</code> function:
</p><pre class="programlisting">
vars = Variables(None, ARGUMENTS)
vars.Add('RELEASE', 'Set to 1 to build for release', 0)
env = Environment(variables = vars)
Help(vars.GenerateHelpText(env))
</pre><p>
<span class="application">SCons</span> will now display some useful text
when the <code class="literal">-h</code> option is used:
</p><pre class="screen">% <strong class="userinput"><code>scons -Q -h</code></strong>
RELEASE: Set to 1 to build for release
default: 0
actual: 0
Use scons -H for help about command-line options.
</pre><p>
Notice that the help output shows the default value,
and the current actual value of the build variable.
</p></div><div class="section" title="10.2.3.<2E>Reading Build Variables From a File"><div class="titlepage"><div><div><h3 class="title"><a name="idm2580"></a>10.2.3.<2E>Reading Build Variables From a File</h3></div></div></div><p>
Giving the user a way to specify the
value of a build variable on the command line
is useful,
but can still be tedious
if users must specify the variable
every time they run <span class="application">SCons</span>.
We can let users provide customized build variable settings
in a local file by providing a
file name when we create the
<code class="function">Variables</code> object:
</p><pre class="programlisting">
vars = Variables('custom.py')
vars.Add('RELEASE', 'Set to 1 to build for release', 0)
env = Environment(variables = vars,
CPPDEFINES={'RELEASE_BUILD' : '${RELEASE}'})
env.Program(['foo.c', 'bar.c'])
Help(vars.GenerateHelpText(env))
</pre><p>
This then allows the user to control the <code class="varname">RELEASE</code>
variable by setting it in the <code class="filename">custom.py</code> file:
</p><pre class="programlisting">
RELEASE = 1
</pre><p>
Note that this file is actually executed
like a Python script.
Now when we run <span class="application">SCons</span>:
</p><pre class="screen">% <strong class="userinput"><code>scons -Q</code></strong>
cc -o bar.o -c -DRELEASE_BUILD=1 bar.c
cc -o foo.o -c -DRELEASE_BUILD=1 foo.c
cc -o foo foo.o bar.o
</pre><p>
And if we change the contents of <code class="filename">custom.py</code> to:
</p><pre class="programlisting">
RELEASE = 0
</pre><p>
The object files are rebuilt appropriately
with the new variable:
</p><pre class="screen">% <strong class="userinput"><code>scons -Q</code></strong>
cc -o bar.o -c -DRELEASE_BUILD=0 bar.c
cc -o foo.o -c -DRELEASE_BUILD=0 foo.c
cc -o foo foo.o bar.o
</pre><p>
Finally, you can combine both methods with:
</p><pre class="screen">
vars = Variables('custom.py', ARGUMENTS)
</pre><p>
where values in the option file <code class="filename">custom.py</code> get overwritten
by the ones specified on the command line.
</p></div><div class="section" title="10.2.4.<2E>Pre-Defined Build Variable Functions"><div class="titlepage"><div><div><h3 class="title"><a name="idm2604"></a>10.2.4.<2E>Pre-Defined Build Variable Functions</h3></div></div></div><p>
<span class="application">SCons</span> provides a number of functions
that provide ready-made behaviors
for various types of command-line build variables.
</p><div class="section" title="10.2.4.1.<2E>True/False Values: the BoolVariable Build Variable Function"><div class="titlepage"><div><div><h4 class="title"><a name="idm2608"></a>10.2.4.1.<2E>True/False Values: the <code class="function">BoolVariable</code> Build Variable Function</h4></div></div></div><p>
It's often handy to be able to specify a
variable that controls a simple Boolean variable
with a <code class="literal">true</code> or <code class="literal">false</code> value.
It would be even more handy to accomodate
users who have different preferences for how to represent
<code class="literal">true</code> or <code class="literal">false</code> values.
The <code class="function">BoolVariable</code> function
makes it easy to accomodate these
common representations of
<code class="literal">true</code> or <code class="literal">false</code>.
</p><p>
The <code class="function">BoolVariable</code> function takes three arguments:
the name of the build variable,
the default value of the build variable,
and the help string for the variable.
It then returns appropriate information for
passing to the <code class="function">Add</code> method of a <code class="function">Variables</code> object, like so:
</p><pre class="programlisting">
vars = Variables('custom.py')
vars.Add(BoolVariable('RELEASE', 'Set to build for release', 0))
env = Environment(variables = vars,
CPPDEFINES={'RELEASE_BUILD' : '${RELEASE}'})
env.Program('foo.c')
</pre><p>
With this build variable,
the <code class="varname">RELEASE</code> variable can now be enabled by
setting it to the value <code class="literal">yes</code>
or <code class="literal">t</code>:
</p><pre class="screen">% <strong class="userinput"><code>scons -Q RELEASE=yes foo.o</code></strong>
cc -o foo.o -c -DRELEASE_BUILD=True foo.c
</pre><pre class="screen">% <strong class="userinput"><code>scons -Q RELEASE=t foo.o</code></strong>
cc -o foo.o -c -DRELEASE_BUILD=True foo.c
</pre><p>
Other values that equate to <code class="literal">true</code> include
<code class="literal">y</code>,
<code class="literal">1</code>,
<code class="literal">on</code>
and
<code class="literal">all</code>.
</p><p>
Conversely, <code class="varname">RELEASE</code> may now be given a <code class="literal">false</code>
value by setting it to
<code class="literal">no</code>
or
<code class="literal">f</code>:
</p><pre class="screen">% <strong class="userinput"><code>scons -Q RELEASE=no foo.o</code></strong>
cc -o foo.o -c -DRELEASE_BUILD=False foo.c
</pre><pre class="screen">% <strong class="userinput"><code>scons -Q RELEASE=f foo.o</code></strong>
cc -o foo.o -c -DRELEASE_BUILD=False foo.c
</pre><p>
Other values that equate to <code class="literal">false</code> include
<code class="literal">n</code>,
<code class="literal">0</code>,
<code class="literal">off</code>
and
<code class="literal">none</code>.
</p><p>
Lastly, if a user tries to specify
any other value,
<span class="application">SCons</span> supplies an appropriate error message:
</p><pre class="screen">% <strong class="userinput"><code>scons -Q RELEASE=bad_value foo.o</code></strong>
scons: *** Error converting option: RELEASE
Invalid value for boolean option: bad_value
File "/home/my/project/SConstruct", line 4, in &lt;module&gt;
</pre></div><div class="section" title="10.2.4.2.<2E>Single Value From a List: the EnumVariable Build Variable Function"><div class="titlepage"><div><div><h4 class="title"><a name="idm2657"></a>10.2.4.2.<2E>Single Value From a List: the <code class="function">EnumVariable</code> Build Variable Function</h4></div></div></div><p>
Suppose that we want a user to be able to
set a <code class="varname">COLOR</code> variable
that selects a background color to be
displayed by an application,
but that we want to restrict the
choices to a specific set of allowed colors.
This can be set up quite easily
using the <code class="function">EnumVariable</code>,
which takes a list of <code class="varname">allowed_values</code>
in addition to the variable name,
default value,
and help text arguments:
</p><pre class="programlisting">
vars = Variables('custom.py')
vars.Add(EnumVariable('COLOR', 'Set background color', 'red',
allowed_values=('red', 'green', 'blue')))
env = Environment(variables = vars,
CPPDEFINES={'COLOR' : '"${COLOR}"'})
env.Program('foo.c')
</pre><p>
The user can now explicity set the <code class="varname">COLOR</code> build variable
to any of the specified allowed values:
</p><pre class="screen">% <strong class="userinput"><code>scons -Q COLOR=red foo.o</code></strong>
cc -o foo.o -c -DCOLOR="red" foo.c
% <strong class="userinput"><code>scons -Q COLOR=blue foo.o</code></strong>
cc -o foo.o -c -DCOLOR="blue" foo.c
% <strong class="userinput"><code>scons -Q COLOR=green foo.o</code></strong>
cc -o foo.o -c -DCOLOR="green" foo.c
</pre><p>
But, almost more importantly,
an attempt to set <code class="varname">COLOR</code>
to a value that's not in the list
generates an error message:
</p><pre class="screen">% <strong class="userinput"><code>scons -Q COLOR=magenta foo.o</code></strong>
scons: *** Invalid value for option COLOR: magenta. Valid values are: ('red', 'green', 'blue')
File "/home/my/project/SConstruct", line 5, in &lt;module&gt;
</pre><p>
The <code class="function">EnumVariable</code> function also supports a way
to map alternate names to allowed values.
Suppose, for example,
that we want to allow the user
to use the word <code class="literal">navy</code> as a synonym for
<code class="literal">blue</code>.
We do this by adding a <code class="varname">map</code> dictionary
that will map its key values
to the desired legal value:
</p><pre class="programlisting">
vars = Variables('custom.py')
vars.Add(EnumVariable('COLOR', 'Set background color', 'red',
allowed_values=('red', 'green', 'blue'),
map={'navy':'blue'}))
env = Environment(variables = vars,
CPPDEFINES={'COLOR' : '"${COLOR}"'})
env.Program('foo.c')
</pre><p>
As desired, the user can then use
<code class="literal">navy</code> on the command line,
and <span class="application">SCons</span> will translate it into <code class="literal">blue</code>
when it comes time to use the <code class="varname">COLOR</code>
variable to build a target:
</p><pre class="screen">% <strong class="userinput"><code>scons -Q COLOR=navy foo.o</code></strong>
cc -o foo.o -c -DCOLOR="blue" foo.c
</pre><p>
By default, when using the <code class="function">EnumVariable</code> function,
arguments that differ
from the legal values
only in case
are treated as illegal values:
</p><pre class="screen">% <strong class="userinput"><code>scons -Q COLOR=Red foo.o</code></strong>
scons: *** Invalid value for option COLOR: Red. Valid values are: ('red', 'green', 'blue')
File "/home/my/project/SConstruct", line 5, in &lt;module&gt;
% <strong class="userinput"><code>scons -Q COLOR=BLUE foo.o</code></strong>
scons: *** Invalid value for option COLOR: BLUE. Valid values are: ('red', 'green', 'blue')
File "/home/my/project/SConstruct", line 5, in &lt;module&gt;
% <strong class="userinput"><code>scons -Q COLOR=nAvY foo.o</code></strong>
scons: *** Invalid value for option COLOR: nAvY. Valid values are: ('red', 'green', 'blue')
File "/home/my/project/SConstruct", line 5, in &lt;module&gt;
</pre><p>
The <code class="function">EnumVariable</code> function can take an additional
<code class="varname">ignorecase</code> keyword argument that,
when set to <code class="literal">1</code>,
tells <span class="application">SCons</span> to allow case differences
when the values are specified:
</p><pre class="programlisting">
vars = Variables('custom.py')
vars.Add(EnumVariable('COLOR', 'Set background color', 'red',
allowed_values=('red', 'green', 'blue'),
map={'navy':'blue'},
ignorecase=1))
env = Environment(variables = vars,
CPPDEFINES={'COLOR' : '"${COLOR}"'})
env.Program('foo.c')
</pre><p>
Which yields the output:
</p><pre class="screen">% <strong class="userinput"><code>scons -Q COLOR=Red foo.o</code></strong>
cc -o foo.o -c -DCOLOR="Red" foo.c
% <strong class="userinput"><code>scons -Q COLOR=BLUE foo.o</code></strong>
cc -o foo.o -c -DCOLOR="BLUE" foo.c
% <strong class="userinput"><code>scons -Q COLOR=nAvY foo.o</code></strong>
cc -o foo.o -c -DCOLOR="blue" foo.c
% <strong class="userinput"><code>scons -Q COLOR=green foo.o</code></strong>
cc -o foo.o -c -DCOLOR="green" foo.c
</pre><p>
Notice that an <code class="varname">ignorecase</code> value of <code class="literal">1</code>
preserves the case-spelling that the user supplied.
If you want <span class="application">SCons</span> to translate the names
into lower-case,
regardless of the case used by the user,
specify an <code class="varname">ignorecase</code> value of <code class="literal">2</code>:
</p><pre class="programlisting">
vars = Variables('custom.py')
vars.Add(EnumVariable('COLOR', 'Set background color', 'red',
allowed_values=('red', 'green', 'blue'),
map={'navy':'blue'},
ignorecase=2))
env = Environment(variables = vars,
CPPDEFINES={'COLOR' : '"${COLOR}"'})
env.Program('foo.c')
</pre><p>
Now <span class="application">SCons</span> will use values of
<code class="literal">red</code>,
<code class="literal">green</code> or
<code class="literal">blue</code>
regardless of how the user spells
those values on the command line:
</p><pre class="screen">% <strong class="userinput"><code>scons -Q COLOR=Red foo.o</code></strong>
cc -o foo.o -c -DCOLOR="red" foo.c
% <strong class="userinput"><code>scons -Q COLOR=nAvY foo.o</code></strong>
cc -o foo.o -c -DCOLOR="blue" foo.c
% <strong class="userinput"><code>scons -Q COLOR=GREEN foo.o</code></strong>
cc -o foo.o -c -DCOLOR="green" foo.c
</pre></div><div class="section" title="10.2.4.3.<2E>Multiple Values From a List: the ListVariable Build Variable Function"><div class="titlepage"><div><div><h4 class="title"><a name="idm2722"></a>10.2.4.3.<2E>Multiple Values From a List: the <code class="function">ListVariable</code> Build Variable Function</h4></div></div></div><p>
Another way in which you might want to allow users
to control a build variable is to
specify a list of one or more legal values.
<span class="application">SCons</span> supports this through the <code class="function">ListVariable</code> function.
If, for example, we want a user to be able to set a
<code class="varname">COLORS</code> variable to one or more of the legal list of values:
</p><pre class="programlisting">
vars = Variables('custom.py')
vars.Add(ListVariable('COLORS', 'List of colors', 0,
['red', 'green', 'blue']))
env = Environment(variables = vars,
CPPDEFINES={'COLORS' : '"${COLORS}"'})
env.Program('foo.c')
</pre><p>
A user can now specify a comma-separated list
of legal values,
which will get translated into a space-separated
list for passing to the any build commands:
</p><pre class="screen">% <strong class="userinput"><code>scons -Q COLORS=red,blue foo.o</code></strong>
cc -o foo.o -c -DCOLORS="red blue" foo.c
% <strong class="userinput"><code>scons -Q COLORS=blue,green,red foo.o</code></strong>
cc -o foo.o -c -DCOLORS="blue green red" foo.c
</pre><p>
In addition, the <code class="function">ListVariable</code> function
allows the user to specify explicit keywords of
<code class="literal">all</code> or <code class="literal">none</code>
to select all of the legal values,
or none of them, respectively:
</p><pre class="screen">% <strong class="userinput"><code>scons -Q COLORS=all foo.o</code></strong>
cc -o foo.o -c -DCOLORS="red green blue" foo.c
% <strong class="userinput"><code>scons -Q COLORS=none foo.o</code></strong>
cc -o foo.o -c -DCOLORS="" foo.c
</pre><p>
And, of course, an illegal value
still generates an error message:
</p><pre class="screen">% <strong class="userinput"><code>scons -Q COLORS=magenta foo.o</code></strong>
scons: *** Error converting option: COLORS
Invalid value(s) for option: magenta
File "/home/my/project/SConstruct", line 5, in &lt;module&gt;
</pre></div><div class="section" title="10.2.4.4.<2E>Path Names: the PathVariable Build Variable Function"><div class="titlepage"><div><div><h4 class="title"><a name="idm2744"></a>10.2.4.4.<2E>Path Names: the <code class="function">PathVariable</code> Build Variable Function</h4></div></div></div><p>
<span class="application">SCons</span> supports a <code class="function">PathVariable</code> function
to make it easy to create a build variable
to control an expected path name.
If, for example, you need to
define a variable in the preprocessor
that controls the location of a
configuration file:
</p><pre class="programlisting">
vars = Variables('custom.py')
vars.Add(PathVariable('CONFIG',
'Path to configuration file',
'/etc/my_config'))
env = Environment(variables = vars,
CPPDEFINES={'CONFIG_FILE' : '"$CONFIG"'})
env.Program('foo.c')
</pre><p>
This then allows the user to
override the <code class="varname">CONFIG</code> build variable
on the command line as necessary:
</p><pre class="screen">% <strong class="userinput"><code>scons -Q foo.o</code></strong>
cc -o foo.o -c -DCONFIG_FILE="/etc/my_config" foo.c
% <strong class="userinput"><code>scons -Q CONFIG=/usr/local/etc/other_config foo.o</code></strong>
scons: `foo.o' is up to date.
</pre><p>
By default, <code class="function">PathVariable</code> checks to make sure
that the specified path exists and generates an error if it
doesn't:
</p><pre class="screen">% <strong class="userinput"><code>scons -Q CONFIG=/does/not/exist foo.o</code></strong>
scons: *** Path for option CONFIG does not exist: /does/not/exist
File "/home/my/project/SConstruct", line 6, in &lt;module&gt;
</pre><p>
<code class="function">PathVariable</code> provides a number of methods
that you can use to change this behavior.
If you want to ensure that any specified paths are,
in fact, files and not directories,
use the <code class="function">PathVariable.PathIsFile</code> method:
</p><pre class="programlisting">
vars = Variables('custom.py')
vars.Add(PathVariable('CONFIG',
'Path to configuration file',
'/etc/my_config',
PathVariable.PathIsFile))
env = Environment(variables = vars,
CPPDEFINES={'CONFIG_FILE' : '"$CONFIG"'})
env.Program('foo.c')
</pre><p>
Conversely, to ensure that any specified paths are
directories and not files,
use the <code class="function">PathVariable.PathIsDir</code> method:
</p><pre class="programlisting">
vars = Variables('custom.py')
vars.Add(PathVariable('DBDIR',
'Path to database directory',
'/var/my_dbdir',
PathVariable.PathIsDir))
env = Environment(variables = vars,
CPPDEFINES={'DBDIR' : '"$DBDIR"'})
env.Program('foo.c')
</pre><p>
If you want to make sure that any specified paths
are directories,
and you would like the directory created
if it doesn't already exist,
use the <code class="function">PathVariable.PathIsDirCreate</code> method:
</p><pre class="programlisting">
vars = Variables('custom.py')
vars.Add(PathVariable('DBDIR',
'Path to database directory',
'/var/my_dbdir',
PathVariable.PathIsDirCreate))
env = Environment(variables = vars,
CPPDEFINES={'DBDIR' : '"$DBDIR"'})
env.Program('foo.c')
</pre><p>
Lastly, if you don't care whether the path exists,
is a file, or a directory,
use the <code class="function">PathVariable.PathAccept</code> method
to accept any path that the user supplies:
</p><pre class="programlisting">
vars = Variables('custom.py')
vars.Add(PathVariable('OUTPUT',
'Path to output file or directory',
None,
PathVariable.PathAccept))
env = Environment(variables = vars,
CPPDEFINES={'OUTPUT' : '"$OUTPUT"'})
env.Program('foo.c')
</pre></div><div class="section" title="10.2.4.5.<2E>Enabled/Disabled Path Names: the PackageVariable Build Variable Function"><div class="titlepage"><div><div><h4 class="title"><a name="idm2773"></a>10.2.4.5.<2E>Enabled/Disabled Path Names: the <code class="function">PackageVariable</code> Build Variable Function</h4></div></div></div><p>
Sometimes you want to give users
even more control over a path name variable,
allowing them to explicitly enable or
disable the path name
by using <code class="literal">yes</code> or <code class="literal">no</code> keywords,
in addition to allow them
to supply an explicit path name.
<span class="application">SCons</span> supports the <code class="function">PackageVariable</code>
function to support this:
</p><pre class="programlisting">
vars = Variables('custom.py')
vars.Add(PackageVariable('PACKAGE',
'Location package',
'/opt/location'))
env = Environment(variables = vars,
CPPDEFINES={'PACKAGE' : '"$PACKAGE"'})
env.Program('foo.c')
</pre><p>
When the <code class="filename">SConscript</code> file uses the <code class="function">PackageVariable</code> funciton,
user can now still use the default
or supply an overriding path name,
but can now explicitly set the
specified variable to a value
that indicates the package should be enabled
(in which case the default should be used)
or disabled:
</p><pre class="screen">% <strong class="userinput"><code>scons -Q foo.o</code></strong>
cc -o foo.o -c -DPACKAGE="/opt/location" foo.c
% <strong class="userinput"><code>scons -Q PACKAGE=/usr/local/location foo.o</code></strong>
cc -o foo.o -c -DPACKAGE="/usr/local/location" foo.c
% <strong class="userinput"><code>scons -Q PACKAGE=yes foo.o</code></strong>
cc -o foo.o -c -DPACKAGE="True" foo.c
% <strong class="userinput"><code>scons -Q PACKAGE=no foo.o</code></strong>
cc -o foo.o -c -DPACKAGE="False" foo.c
</pre></div></div><div class="section" title="10.2.5.<2E>Adding Multiple Command-Line Build Variables at Once"><div class="titlepage"><div><div><h3 class="title"><a name="idm2790"></a>10.2.5.<2E>Adding Multiple Command-Line Build Variables at Once</h3></div></div></div><p>
Lastly, <span class="application">SCons</span> provides a way to add
multiple build variables to a <code class="function">Variables</code> object at once.
Instead of having to call the <code class="function">Add</code> method
multiple times,
you can call the <code class="function">AddVariables</code>
method with a list of build variables
to be added to the object.
Each build variable is specified
as either a tuple of arguments,
just like you'd pass to the <code class="function">Add</code> method itself,
or as a call to one of the pre-defined
functions for pre-packaged command-line build variables.
in any order:
</p><pre class="programlisting">
vars = Variables()
vars.AddVariables(
('RELEASE', 'Set to 1 to build for release', 0),
('CONFIG', 'Configuration file', '/etc/my_config'),
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),
)
</pre><p>
</p></div><div class="section" title="10.2.6.<2E>Handling Unknown Command-Line Build Variables: the UnknownVariables Function"><div class="titlepage"><div><div><h3 class="title"><a name="idm2800"></a>10.2.6.<2E>Handling Unknown Command-Line Build Variables: the <code class="function">UnknownVariables</code> Function</h3></div></div></div><p>
Users may, of course,
occasionally misspell variable names in their command-line settings.
<span class="application">SCons</span> does not generate an error or warning
for any unknown variables the users specifies on the command line.
(This is in no small part because you may be
processing the arguments directly using the <code class="varname">ARGUMENTS</code> dictionary,
and therefore <span class="application">SCons</span> can't know in the general case
whether a given "misspelled" variable is
really unknown and a potential problem,
or something that your <code class="filename">SConscript</code> file
will handle directly with some Python code.)
</p><p>
If, however, you're using a <code class="function">Variables</code> object to
define a specific set of command-line build variables
that you expect users to be able to set,
you may want to provide an error
message or warning of your own
if the user supplies a variable setting
that is <span class="emphasis"><em>not</em></span> among
the defined list of variable names known to the <code class="function">Variables</code> object.
You can do this by calling the <code class="function">UnknownVariables</code>
method of the <code class="function">Variables</code> object:
</p><pre class="programlisting">
vars = Variables(None)
vars.Add('RELEASE', 'Set to 1 to build for release', 0)
env = Environment(variables = vars,
CPPDEFINES={'RELEASE_BUILD' : '${RELEASE}'})
unknown = vars.UnknownVariables()
if unknown:
print("Unknown variables: %s"%unknown.keys())
Exit(1)
env.Program('foo.c')
</pre><p>
The <code class="function">UnknownVariables</code> method returns a dictionary
containing the keywords and values
of any variables the user specified on the command line
that are <span class="emphasis"><em>not</em></span>
among the variables known to the <code class="function">Variables</code> object
(from having been specified using
the <code class="function">Variables</code> object's<code class="function">Add</code> method).
In the examble above,
we check for whether the dictionary
returned by the <code class="function">UnknownVariables</code> is non-empty,
and if so print the Python list
containing the names of the unknwown variables
and then call the <code class="function">Exit</code> function
to terminate <span class="application">SCons</span>:
</p><pre class="screen">% <strong class="userinput"><code>scons -Q NOT_KNOWN=foo</code></strong>
Unknown variables: ['NOT_KNOWN']
</pre><p>
Of course, you can process the items in the
dictionary returned by the <code class="function">UnknownVariables</code> function
in any way appropriate to your build configuration,
including just printing a warning message
but not exiting,
logging an error somewhere,
etc.
</p><p>
Note that you must delay the call of <code class="function">UnknownVariables</code>
until after you have applied the <code class="function">Variables</code> object
to a construction environment
with the <code class="literal">variables=</code>
keyword argument of an <code class="function">Environment</code> call.
</p></div></div><div class="section" title="10.3.<2E>Command-Line Targets"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="sect-command-line-targets"></a>10.3.<2E>Command-Line Targets</h2></div></div></div><div class="section" title="10.3.1.<2E>Fetching Command-Line Targets: the COMMAND_LINE_TARGETS Variable"><div class="titlepage"><div><div><h3 class="title"><a name="idm2835"></a>10.3.1.<2E>Fetching Command-Line Targets: the <code class="varname">COMMAND_LINE_TARGETS</code> Variable</h3></div></div></div><p>
<span class="application">SCons</span> supports a <code class="varname">COMMAND_LINE_TARGETS</code> variable
that lets you fetch the list of targets that the
user specified on the command line.
You can use the targets to manipulate the
build in any way you wish.
As a simple example,
suppose that you want to print a reminder
to the user whenever a specific program is built.
You can do this by checking for the
target in the <code class="varname">COMMAND_LINE_TARGETS</code> list:
</p><pre class="programlisting">
if 'bar' in COMMAND_LINE_TARGETS:
print("Don't forget to copy `bar' to the archive!")
Default(Program('foo.c'))
Program('bar.c')
</pre><p>
Then, running <span class="application">SCons</span> with the default target
works as it always does,
but explicity specifying the <code class="filename">bar</code> target
on the command line generates the warning message:
</p><pre class="screen">% <strong class="userinput"><code>scons -Q</code></strong>
cc -o foo.o -c foo.c
cc -o foo foo.o
% <strong class="userinput"><code>scons -Q bar</code></strong>
Don't forget to copy `bar' to the archive!
cc -o bar.o -c bar.c
cc -o bar bar.o
</pre><p>
Another practical use for the <code class="varname">COMMAND_LINE_TARGETS</code> variable
might be to speed up a build
by only reading certain subsidiary <code class="filename">SConscript</code>
files if a specific target is requested.
</p></div><div class="section" title="10.3.2.<2E>Controlling the Default Targets: the Default Function"><div class="titlepage"><div><div><h3 class="title"><a name="idm2852"></a>10.3.2.<2E>Controlling the Default Targets: the <code class="function">Default</code> Function</h3></div></div></div><p>
One of the most basic things you can control
is which targets <span class="application">SCons</span> will build by default--that is,
when there are no targets specified on the command line.
As mentioned previously,
<span class="application">SCons</span> will normally build every target
in or below the current directory
by default--that is, when you don't
explicitly specify one or more targets
on the command line.
Sometimes, however, you may want
to specify explicitly that only
certain programs, or programs in certain directories,
should be built by default.
You do this with the <code class="function">Default</code> function:
</p><pre class="programlisting">
env = Environment()
hello = env.Program('hello.c')
env.Program('goodbye.c')
Default(hello)
</pre><p>
This <code class="filename">SConstruct</code> file knows how to build two programs,
<code class="filename">hello</code> and <code class="filename">goodbye</code>,
but only builds the
<code class="filename">hello</code> program by default:
</p><pre class="screen">% <strong class="userinput"><code>scons -Q</code></strong>
cc -o hello.o -c hello.c
cc -o hello hello.o
% <strong class="userinput"><code>scons -Q</code></strong>
scons: `hello' is up to date.
% <strong class="userinput"><code>scons -Q goodbye</code></strong>
cc -o goodbye.o -c goodbye.c
cc -o goodbye goodbye.o
</pre><p>
Note that, even when you use the <code class="function">Default</code>
function in your <code class="filename">SConstruct</code> file,
you can still explicitly specify the current directory
(<code class="literal">.</code>) on the command line
to tell <span class="application">SCons</span> to build
everything in (or below) the current directory:
</p><pre class="screen">% <strong class="userinput"><code>scons -Q .</code></strong>
cc -o goodbye.o -c goodbye.c
cc -o goodbye goodbye.o
cc -o hello.o -c hello.c
cc -o hello hello.o
</pre><p>
You can also call the <code class="function">Default</code>
function more than once,
in which case each call
adds to the list of targets to be built by default:
</p><pre class="programlisting">
env = Environment()
prog1 = env.Program('prog1.c')
Default(prog1)
prog2 = env.Program('prog2.c')
prog3 = env.Program('prog3.c')
Default(prog3)
</pre><p>
Or you can specify more than one target
in a single call to the <code class="function">Default</code> function:
</p><pre class="programlisting">
env = Environment()
prog1 = env.Program('prog1.c')
prog2 = env.Program('prog2.c')
prog3 = env.Program('prog3.c')
Default(prog1, prog3)
</pre><p>
Either of these last two examples
will build only the
<span class="application">prog1</span>
and
<span class="application">prog3</span>
programs by default:
</p><pre class="screen">% <strong class="userinput"><code>scons -Q</code></strong>
cc -o prog1.o -c prog1.c
cc -o prog1 prog1.o
cc -o prog3.o -c prog3.c
cc -o prog3 prog3.o
% <strong class="userinput"><code>scons -Q .</code></strong>
cc -o prog2.o -c prog2.c
cc -o prog2 prog2.o
</pre><p>
You can list a directory as
an argument to <code class="function">Default</code>:
</p><pre class="programlisting">
env = Environment()
env.Program(['prog1/main.c', 'prog1/foo.c'])
env.Program(['prog2/main.c', 'prog2/bar.c'])
Default('prog1')
</pre><p>
In which case only the target(s) in that
directory will be built by default:
</p><pre class="screen">% <strong class="userinput"><code>scons -Q</code></strong>
cc -o prog1/foo.o -c prog1/foo.c
cc -o prog1/main.o -c prog1/main.c
cc -o prog1/main prog1/main.o prog1/foo.o
% <strong class="userinput"><code>scons -Q</code></strong>
scons: `prog1' is up to date.
% <strong class="userinput"><code>scons -Q .</code></strong>
cc -o prog2/bar.o -c prog2/bar.c
cc -o prog2/main.o -c prog2/main.c
cc -o prog2/main prog2/main.o prog2/bar.o
</pre><p>
Lastly, if for some reason you don't want
any targets built by default,
you can use the Python <code class="literal">None</code>
variable:
</p><pre class="programlisting">
env = Environment()
prog1 = env.Program('prog1.c')
prog2 = env.Program('prog2.c')
Default(None)
</pre><p>
Which would produce build output like:
</p><pre class="screen">% <strong class="userinput"><code>scons -Q</code></strong>
scons: *** No targets specified and no Default() targets found. Stop.
Found nothing to build
% <strong class="userinput"><code>scons -Q .</code></strong>
cc -o prog1.o -c prog1.c
cc -o prog1 prog1.o
cc -o prog2.o -c prog2.c
cc -o prog2 prog2.o
</pre><div class="section" title="10.3.2.1.<2E>Fetching the List of Default Targets: the DEFAULT_TARGETS Variable"><div class="titlepage"><div><div><h4 class="title"><a name="idm2903"></a>10.3.2.1.<2E>Fetching the List of Default Targets: the <code class="varname">DEFAULT_TARGETS</code> Variable</h4></div></div></div><p>
<span class="application">SCons</span> supports a <code class="varname">DEFAULT_TARGETS</code> variable
that lets you get at the current list of default targets.
The <code class="varname">DEFAULT_TARGETS</code> variable has
two important differences from the <code class="varname">COMMAND_LINE_TARGETS</code> variable.
First, the <code class="varname">DEFAULT_TARGETS</code> variable is a list of
internal <span class="application">SCons</span> nodes,
so you need to convert the list elements to strings
if you want to print them or look for a specific target name.
You can do this easily by calling the <code class="function">str</code>
on the elements in a list comprehension:
</p><pre class="programlisting">
prog1 = Program('prog1.c')
Default(prog1)
print("DEFAULT_TARGETS is %s" % [str(t) for t in DEFAULT_TARGETS])
</pre><p>
(Keep in mind that all of the manipulation of the
<code class="varname">DEFAULT_TARGETS</code> list takes place during the
first phase when <span class="application">SCons</span> is reading up the <code class="filename">SConscript</code> files,
which is obvious if
we leave off the <code class="literal">-Q</code> flag when we run <span class="application">SCons</span>:)
</p><pre class="screen">% <strong class="userinput"><code>scons</code></strong>
scons: Reading SConscript files ...
DEFAULT_TARGETS is ['prog1']
scons: done reading SConscript files.
scons: Building targets ...
cc -o prog1.o -c prog1.c
cc -o prog1 prog1.o
scons: done building targets.
</pre><p>
Second,
the contents of the <code class="varname">DEFAULT_TARGETS</code> list change
in response to calls to the <code class="function">Default</code> function,
as you can see from the following <code class="filename">SConstruct</code> file:
</p><pre class="programlisting">
prog1 = Program('prog1.c')
Default(prog1)
print("DEFAULT_TARGETS is now %s" % [str(t) for t in DEFAULT_TARGETS])
prog2 = Program('prog2.c')
Default(prog2)
print("DEFAULT_TARGETS is now %s" % [str(t) for t in DEFAULT_TARGETS])
</pre><p>
Which yields the output:
</p><pre class="screen">% <strong class="userinput"><code>scons</code></strong>
scons: Reading SConscript files ...
DEFAULT_TARGETS is now ['prog1']
DEFAULT_TARGETS is now ['prog1', 'prog2']
scons: done reading SConscript files.
scons: Building targets ...
cc -o prog1.o -c prog1.c
cc -o prog1 prog1.o
cc -o prog2.o -c prog2.c
cc -o prog2 prog2.o
scons: done building targets.
</pre><p>
In practice, this simply means that you
need to pay attention to the order in
which you call the <code class="function">Default</code> function
and refer to the <code class="varname">DEFAULT_TARGETS</code> list,
to make sure that you don't examine the
list before you've added the default targets
you expect to find in it.
</p></div></div><div class="section" title="10.3.3.<2E>Fetching the List of Build Targets, Regardless of Origin: the BUILD_TARGETS Variable"><div class="titlepage"><div><div><h3 class="title"><a name="idm2934"></a>10.3.3.<2E>Fetching the List of Build Targets, Regardless of Origin: the <code class="varname">BUILD_TARGETS</code> Variable</h3></div></div></div><p>
We've already been introduced to the
<code class="varname">COMMAND_LINE_TARGETS</code> variable,
which contains a list of targets specified on the command line,
and the <code class="varname">DEFAULT_TARGETS</code> variable,
which contains a list of targets specified
via calls to the <code class="function">Default</code> method or function.
Sometimes, however,
you want a list of whatever targets
<span class="application">SCons</span> will try to build,
regardless of whether the targets came from the
command line or a <code class="function">Default</code> call.
You could code this up by hand, as follows:
</p><pre class="programlisting">
if COMMAND_LINE_TARGETS:
targets = COMMAND_LINE_TARGETS
else:
targets = DEFAULT_TARGETS
</pre><p>
<span class="application">SCons</span>, however, provides a convenient
<code class="varname">BUILD_TARGETS</code> variable
that eliminates the need for this by-hand manipulation.
Essentially, the <code class="varname">BUILD_TARGETS</code> variable
contains a list of the command-line targets,
if any were specified,
and if no command-line targets were specified,
it contains a list of the targets specified
via the <code class="function">Default</code> method or function.
</p><p>
Because <code class="varname">BUILD_TARGETS</code> may contain a list of <span class="application">SCons</span> nodes,
you must convert the list elements to strings
if you want to print them or look for a specific target name,
just like the <code class="varname">DEFAULT_TARGETS</code> list:
</p><pre class="programlisting">
prog1 = Program('prog1.c')
Program('prog2.c')
Default(prog1)
print ("BUILD_TARGETS is %s" % [str(t) for t in BUILD_TARGETS])
</pre><p>
Notice how the value of <code class="varname">BUILD_TARGETS</code>
changes depending on whether a target is
specified on the command line:
</p><pre class="screen">% <strong class="userinput"><code>scons -Q</code></strong>
BUILD_TARGETS is ['prog1']
cc -o prog1.o -c prog1.c
cc -o prog1 prog1.o
% <strong class="userinput"><code>scons -Q prog2</code></strong>
BUILD_TARGETS is ['prog2']
cc -o prog2.o -c prog2.c
cc -o prog2 prog2.o
% <strong class="userinput"><code>scons -Q -c .</code></strong>
BUILD_TARGETS is ['.']
Removed prog1.o
Removed prog1
Removed prog2.o
Removed prog2
</pre></div></div><div class="footnotes"><br><hr width="100" align="left"><div class="footnote"><p><sup>[<a id="ftn.idm2442" href="#idm2442" class="para">3</a>] </sup>
The <code class="function">AddOption</code> function is,
in fact, implemented using a subclass
of the <code class="classname">optparse.OptionParser</code>.
</p></div></div></div><div class="chapter" title="Chapter<65>11.<2E>Installing Files in Other Directories: the Install Builder"><div class="titlepage"><div><div><h2 class="title"><a name="chap-install"></a>Chapter<EFBFBD>11.<2E>Installing Files in Other Directories: the <code class="function">Install</code> Builder</h2></div></div></div><p>
Once a program is built,
it is often appropriate to install it in another
directory for public use.
You use the <code class="function">Install</code> method
to arrange for a program, or any other file,
to be copied into a destination directory:
</p><pre class="programlisting">
env = Environment()
hello = env.Program('hello.c')
env.Install('/usr/bin', hello)
</pre><p>
Note, however, that installing a file is
still considered a type of file "build."
This is important when you remember that
the default behavior of <span class="application">SCons</span> is
to build files in or below the current directory.
If, as in the example above,
you are installing files in a directory
outside of the top-level <code class="filename">SConstruct</code> file's directory tree,
you must specify that directory
(or a higher directory, such as <code class="literal">/</code>)
for it to install anything there:
</p><pre class="screen">% <strong class="userinput"><code>scons -Q</code></strong>
cc -o hello.o -c hello.c
cc -o hello hello.o
% <strong class="userinput"><code>scons -Q /usr/bin</code></strong>
Install file: "hello" as "/usr/bin/hello"
</pre><p>
It can, however, be cumbersome to remember
(and type) the specific destination directory
in which the program (or any other file)
should be installed.
This is an area where the <code class="function">Alias</code>
function comes in handy,
allowing you, for example,
to create a pseudo-target named <code class="literal">install</code>
that can expand to the specified destination directory:
</p><pre class="programlisting">
env = Environment()
hello = env.Program('hello.c')
env.Install('/usr/bin', hello)
env.Alias('install', '/usr/bin')
</pre><p>
This then yields the more natural
ability to install the program
in its destination as follows:
</p><pre class="screen">% <strong class="userinput"><code>scons -Q</code></strong>
cc -o hello.o -c hello.c
cc -o hello hello.o
% <strong class="userinput"><code>scons -Q install</code></strong>
Install file: "hello" as "/usr/bin/hello"
</pre><div class="section" title="11.1.<2E>Installing Multiple Files in a Directory"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idm2981"></a>11.1.<2E>Installing Multiple Files in a Directory</h2></div></div></div><p>
You can install multiple files into a directory
simply by calling the <code class="function">Install</code> function multiple times:
</p><pre class="programlisting">
env = Environment()
hello = env.Program('hello.c')
goodbye = env.Program('goodbye.c')
env.Install('/usr/bin', hello)
env.Install('/usr/bin', goodbye)
env.Alias('install', '/usr/bin')
</pre><p>
Or, more succinctly, listing the multiple input
files in a list
(just like you can do with any other builder):
</p><pre class="programlisting">
env = Environment()
hello = env.Program('hello.c')
goodbye = env.Program('goodbye.c')
env.Install('/usr/bin', [hello, goodbye])
env.Alias('install', '/usr/bin')
</pre><p>
Either of these two examples yields:
</p><pre class="screen">% <strong class="userinput"><code>scons -Q install</code></strong>
cc -o goodbye.o -c goodbye.c
cc -o goodbye goodbye.o
Install file: "goodbye" as "/usr/bin/goodbye"
cc -o hello.o -c hello.c
cc -o hello hello.o
Install file: "hello" as "/usr/bin/hello"
</pre></div><div class="section" title="11.2.<2E>Installing a File Under a Different Name"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idm2991"></a>11.2.<2E>Installing a File Under a Different Name</h2></div></div></div><p>
The <code class="function">Install</code> method preserves the name
of the file when it is copied into the
destination directory.
If you need to change the name of the file
when you copy it, use the <code class="function">InstallAs</code> function:
</p><pre class="programlisting">
env = Environment()
hello = env.Program('hello.c')
env.InstallAs('/usr/bin/hello-new', hello)
env.Alias('install', '/usr/bin')
</pre><p>
This installs the <code class="literal">hello</code>
program with the name <code class="literal">hello-new</code>
as follows:
</p><pre class="screen">% <strong class="userinput"><code>scons -Q install</code></strong>
cc -o hello.o -c hello.c
cc -o hello hello.o
Install file: "hello" as "/usr/bin/hello-new"
</pre></div><div class="section" title="11.3.<2E>Installing Multiple Files Under Different Names"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idm3002"></a>11.3.<2E>Installing Multiple Files Under Different Names</h2></div></div></div><p>
Lastly, if you have multiple files that all
need to be installed with different file names,
you can either call the <code class="function">InstallAs</code> function
multiple times, or as a shorthand,
you can supply same-length lists
for both the target and source arguments:
</p><pre class="programlisting">
env = Environment()
hello = env.Program('hello.c')
goodbye = env.Program('goodbye.c')
env.InstallAs(['/usr/bin/hello-new',
'/usr/bin/goodbye-new'],
[hello, goodbye])
env.Alias('install', '/usr/bin')
</pre><p>
In this case, the <code class="function">InstallAs</code> function
loops through both lists simultaneously,
and copies each source file into its corresponding
target file name:
</p><pre class="screen">% <strong class="userinput"><code>scons -Q install</code></strong>
cc -o goodbye.o -c goodbye.c
cc -o goodbye goodbye.o
Install file: "goodbye" as "/usr/bin/goodbye-new"
cc -o hello.o -c hello.c
cc -o hello hello.o
Install file: "hello" as "/usr/bin/hello-new"
</pre></div></div><div class="chapter" title="Chapter<65>12.<2E>Platform-Independent File System Manipulation"><div class="titlepage"><div><div><h2 class="title"><a name="chap-factories"></a>Chapter<EFBFBD>12.<2E>Platform-Independent File System Manipulation</h2></div></div></div><p>
<span class="application">SCons</span> provides a number of platform-independent functions,
called <code class="literal">factories</code>,
that perform common file system manipulations
like copying, moving or deleting files and directories,
or making directories.
These functions are <code class="literal">factories</code>
because they don't perform the action
at the time they're called,
they each return an <code class="classname">Action</code> object
that can be executed at the appropriate time.
</p><div class="section" title="12.1.<2E>Copying Files or Directories: The Copy Factory"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idm3018"></a>12.1.<2E>Copying Files or Directories: The <code class="function">Copy</code> Factory</h2></div></div></div><p>
Suppose you want to arrange to make a copy of a file,
and don't have a suitable pre-existing builder.
<sup>[<a name="idm3022" href="#ftn.idm3022" class="footnote">4</a>]</sup>
One way would be to use the <code class="function">Copy</code> action factory
in conjunction with the <code class="function">Command</code> builder:
</p><pre class="programlisting">
Command("file.out", "file.in", Copy("$TARGET", "$SOURCE"))
</pre><p>
Notice that the action returned by the <code class="function">Copy</code> factory
will expand the <a class="link" href="#cv-TARGET"><code class="envar">$TARGET</code></a> and <a class="link" href="#cv-SOURCE"><code class="envar">$SOURCE</code></a> strings
at the time <code class="filename">file.out</code> is built,
and that the order of the arguments
is the same as that of a builder itself--that is,
target first, followed by source:
</p><pre class="screen">% <strong class="userinput"><code>scons -Q</code></strong>
Copy("file.out", "file.in")
</pre><p>
You can, of course, name a file explicitly
instead of using <code class="envar">$TARGET</code> or <code class="envar">$SOURCE</code>:
</p><pre class="programlisting">
Command("file.out", [], Copy("$TARGET", "file.in"))
</pre><p>
Which executes as:
</p><pre class="screen">% <strong class="userinput"><code>scons -Q</code></strong>
Copy("file.out", "file.in")
</pre><p>
The usefulness of the <code class="function">Copy</code> factory
becomes more apparent when
you use it in a list of actions
passed to the <code class="function">Command</code> builder.
For example, suppose you needed to run a
file through a utility that only modifies files in-place,
and can't "pipe" input to output.
One solution is to copy the source file
to a temporary file name,
run the utility,
and then copy the modified temporary file to the target,
which the <code class="function">Copy</code> factory makes extremely easy:
</p><pre class="programlisting">
Command("file.out", "file.in",
[
Copy("tempfile", "$SOURCE"),
"modify tempfile",
Copy("$TARGET", "tempfile"),
])
</pre><p>
The output then looks like:
</p><pre class="screen">% <strong class="userinput"><code>scons -Q</code></strong>
Copy("tempfile", "file.in")
modify tempfile
Copy("file.out", "tempfile")
</pre><p>
The <code class="function">Copy</code> factory has a third optional argument which controls
how symlinks are copied.
</p><p>
</p><pre class="programlisting">
# Symbolic link shallow copied as a new symbolic link:
Command("LinkIn", "LinkOut", Copy("$TARGET", "$SOURCE"[, True]))
# Symbolic link target copied as a file or directory:
Command("LinkIn", "FileOrDirectoryOut", Copy("$TARGET", "$SOURCE", False))
</pre></div><div class="section" title="12.2.<2E>Deleting Files or Directories: The Delete Factory"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idm3056"></a>12.2.<2E>Deleting Files or Directories: The <code class="function">Delete</code> Factory</h2></div></div></div><p>
If you need to delete a file,
then the <code class="function">Delete</code> factory
can be used in much the same way as
the <code class="function">Copy</code> factory.
For example, if we want to make sure that
the temporary file
in our last example doesn't exist before
we copy to it,
we could add <code class="function">Delete</code> to the beginning
of the command list:
</p><pre class="programlisting">
Command("file.out", "file.in",
[
Delete("tempfile"),
Copy("tempfile", "$SOURCE"),
"modify tempfile",
Copy("$TARGET", "tempfile"),
])
</pre><p>
Which then executes as follows:
</p><pre class="screen">% <strong class="userinput"><code>scons -Q</code></strong>
Delete("tempfile")
Copy("tempfile", "file.in")
modify tempfile
Copy("file.out", "tempfile")
</pre><p>
Of course, like all of these <code class="classname">Action</code> factories,
the <code class="function">Delete</code> factory also expands
<a class="link" href="#cv-TARGET"><code class="envar">$TARGET</code></a> and <a class="link" href="#cv-SOURCE"><code class="envar">$SOURCE</code></a> variables appropriately.
For example:
</p><pre class="programlisting">
Command("file.out", "file.in",
[
Delete("$TARGET"),
Copy("$TARGET", "$SOURCE")
])
</pre><p>
Executes as:
</p><pre class="screen">% <strong class="userinput"><code>scons -Q</code></strong>
Delete("file.out")
Copy("file.out", "file.in")
</pre><p>
Note, however, that you typically don't need to
call the <code class="function">Delete</code> factory explicitly in this way;
by default, <span class="application">SCons</span> deletes its target(s)
for you before executing any action.
</p><p>
One word of caution about using the <code class="function">Delete</code> factory:
it has the same variable expansions available
as any other factory, including the <code class="envar">$SOURCE</code> variable.
Specifying <code class="literal">Delete("$SOURCE")</code>
is not something you usually want to do!
</p></div><div class="section" title="12.3.<2E>Moving (Renaming) Files or Directories: The Move Factory"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idm3085"></a>12.3.<2E>Moving (Renaming) Files or Directories: The <code class="function">Move</code> Factory</h2></div></div></div><p>
The <code class="function">Move</code> factory
allows you to rename a file or directory.
For example, if we don't want to copy the temporary file,
we could use:
</p><pre class="programlisting">
Command("file.out", "file.in",
[
Copy("tempfile", "$SOURCE"),
"modify tempfile",
Move("$TARGET", "tempfile"),
])
</pre><p>
Which would execute as:
</p><pre class="screen">% <strong class="userinput"><code>scons -Q</code></strong>
Copy("tempfile", "file.in")
modify tempfile
Move("file.out", "tempfile")
</pre></div><div class="section" title="12.4.<2E>Updating the Modification Time of a File: The Touch Factory"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idm3094"></a>12.4.<2E>Updating the Modification Time of a File: The <code class="function">Touch</code> Factory</h2></div></div></div><p>
If you just need to update the
recorded modification time for a file,
use the <code class="function">Touch</code> factory:
</p><pre class="programlisting">
Command("file.out", "file.in",
[
Copy("$TARGET", "$SOURCE"),
Touch("$TARGET"),
])
</pre><p>
Which executes as:
</p><pre class="screen">% <strong class="userinput"><code>scons -Q</code></strong>
Copy("file.out", "file.in")
Touch("file.out")
</pre></div><div class="section" title="12.5.<2E>Creating a Directory: The Mkdir Factory"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idm3103"></a>12.5.<2E>Creating a Directory: The <code class="function">Mkdir</code> Factory</h2></div></div></div><p>
If you need to create a directory,
use the <code class="function">Mkdir</code> factory.
For example, if we need to process
a file in a temporary directory
in which the processing tool
will create other files that we don't care about,
you could use:
</p><pre class="programlisting">
Command("file.out", "file.in",
[
Delete("tempdir"),
Mkdir("tempdir"),
Copy("tempdir/${SOURCE.file}", "$SOURCE"),
"process tempdir",
Move("$TARGET", "tempdir/output_file"),
Delete("tempdir"),
])
</pre><p>
Which executes as:
</p><pre class="screen">% <strong class="userinput"><code>scons -Q</code></strong>
Delete("tempdir")
Mkdir("tempdir")
Copy("tempdir/file.in", "file.in")
process tempdir
Move("file.out", "tempdir/output_file")
scons: *** [file.out] tempdir/output_file: No such file or directory
</pre></div><div class="section" title="12.6.<2E>Changing File or Directory Permissions: The Chmod Factory"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idm3112"></a>12.6.<2E>Changing File or Directory Permissions: The <code class="function">Chmod</code> Factory</h2></div></div></div><p>
To change permissions on a file or directory,
use the <code class="function">Chmod</code> factory.
The permission argument uses POSIX-style
permission bits and should typically
be expressed as an octal,
not decimal, number:
</p><pre class="programlisting">
Command("file.out", "file.in",
[
Copy("$TARGET", "$SOURCE"),
Chmod("$TARGET", 0755),
])
</pre><p>
Which executes:
</p><pre class="screen">% <strong class="userinput"><code>scons -Q</code></strong>
Copy("file.out", "file.in")
Chmod("file.out", 0755)
</pre></div><div class="section" title="12.7.<2E>Executing an action immediately: the Execute Function"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idm3121"></a>12.7.<2E>Executing an action immediately: the <code class="function">Execute</code> Function</h2></div></div></div><p>
We've been showing you how to use <code class="classname">Action</code> factories
in the <code class="function">Command</code> function.
You can also execute an <code class="classname">Action</code> returned by a factory
(or actually, any <code class="classname">Action</code>)
at the time the <code class="filename">SConscript</code> file is read
by using the <code class="function">Execute</code> function.
For example, if we need to make sure that
a directory exists before we build any targets,
</p><pre class="programlisting">
Execute(Mkdir('/tmp/my_temp_directory'))
</pre><p>
Notice that this will
create the directory while
the <code class="filename">SConscript</code> file is being read:
</p><pre class="screen">% <strong class="userinput"><code>scons</code></strong>
scons: Reading SConscript files ...
Mkdir("/tmp/my_temp_directory")
scons: done reading SConscript files.
scons: Building targets ...
scons: `.' is up to date.
scons: done building targets.
</pre><p>
If you're familiar with Python,
you may wonder why you would want to use this
instead of just calling the native Python
<code class="function">os.mkdir()</code> function.
The advantage here is that the <code class="function">Mkdir</code>
action will behave appropriately if the user
specifies the <span class="application">SCons</span> <code class="option">-n</code> or
<code class="option">-q</code> options--that is,
it will print the action but not actually
make the directory when <code class="option">-n</code> is specified,
or make the directory but not print the action
when <code class="option">-q</code> is specified.
</p><p>
The <code class="function">Execute</code> function returns the exit status
or return value of the underlying action being executed.
It will also print an error message if the action
fails and returns a non-zero value.
<span class="application">SCons</span> will <span class="emphasis"><em>not</em></span>, however,
actually stop the build if the action fails.
If you want the build to stop
in response to a failure in an action called by <code class="function">Execute</code>,
you must do so by explicitly
checking the return value
and calling the <code class="function">Exit</code> function
(or a Python equivalent):
</p><pre class="programlisting">
if Execute(Mkdir('/tmp/my_temp_directory')):
# A problem occurred while making the temp directory.
Exit(1)
</pre></div><div class="footnotes"><br><hr width="100" align="left"><div class="footnote"><p><sup>[<a id="ftn.idm3022" href="#idm3022" class="para">4</a>] </sup>
Unfortunately, in the early days of SCons design,
we used the name <code class="function">Copy</code> for the function that
returns a copy of the environment,
otherwise that would be the logical choice for
a Builder that copies a file or directory tree
to a target location.
</p></div></div></div><div class="chapter" title="Chapter<65>13.<2E>Controlling Removal of Targets"><div class="titlepage"><div><div><h2 class="title"><a name="chap-file-removal"></a>Chapter<EFBFBD>13.<2E>Controlling Removal of Targets</h2></div></div></div><p>
There are two occasions when <span class="application">SCons</span> will,
by default, remove target files.
The first is when <span class="application">SCons</span> determines that
an target file needs to be rebuilt
and removes the existing version of the target
before executing
The second is when <span class="application">SCons</span> is invoked with the
<code class="literal">-c</code> option to "clean"
a tree of its built targets.
These behaviours can be suppressed with the
<code class="function">Precious</code> and <code class="function">NoClean</code> functions, respectively.
</p><div class="section" title="13.1.<2E>Preventing target removal during build: the Precious Function"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idm3160"></a>13.1.<2E>Preventing target removal during build: the <code class="function">Precious</code> Function</h2></div></div></div><p>
By default, <span class="application">SCons</span> removes targets before building them.
Sometimes, however, this is not what you want.
For example, you may want to update a library incrementally,
not by having it deleted and then rebuilt from all
of the constituent object files.
In such cases, you can use the
<code class="function">Precious</code> method to prevent
<span class="application">SCons</span> from removing the target before it is built:
</p><pre class="programlisting">
env = Environment(RANLIBCOM='')
lib = env.Library('foo', ['f1.c', 'f2.c', 'f3.c'])
env.Precious(lib)
</pre><p>
Although the output doesn't look any different,
<span class="application">SCons</span> does not, in fact,
delete the target library before rebuilding it:
</p><pre class="screen">% <strong class="userinput"><code>scons -Q</code></strong>
cc -o f1.o -c f1.c
cc -o f2.o -c f2.c
cc -o f3.o -c f3.c
ar rc libfoo.a f1.o f2.o f3.o
</pre><p>
<span class="application">SCons</span> will, however, still delete files marked as <code class="function">Precious</code>
when the <code class="literal">-c</code> option is used.
</p></div><div class="section" title="13.2.<2E>Preventing target removal during clean: the NoClean Function"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idm3176"></a>13.2.<2E>Preventing target removal during clean: the <code class="function">NoClean</code> Function</h2></div></div></div><p>
By default, <span class="application">SCons</span> removes all built targets when invoked
with the <code class="literal">-c</code> option to clean a source tree
of built targets.
Sometimes, however, this is not what you want.
For example, you may want to remove only intermediate generated files
(such as object files),
but leave the final targets
(the libraries)
untouched.
In such cases, you can use the <code class="function">NoClean</code> method to prevent <span class="application">SCons</span>
from removing a target during a clean:
</p><pre class="programlisting">
env = Environment(RANLIBCOM='')
lib = env.Library('foo', ['f1.c', 'f2.c', 'f3.c'])
env.NoClean(lib)
</pre><p>
Notice that the <code class="filename">libfoo.a</code>
is not listed as a removed file:
</p><pre class="screen">% <strong class="userinput"><code>scons -Q</code></strong>
cc -o f1.o -c f1.c
cc -o f2.o -c f2.c
cc -o f3.o -c f3.c
ar rc libfoo.a f1.o f2.o f3.o
% <strong class="userinput"><code>scons -c</code></strong>
scons: Reading SConscript files ...
scons: done reading SConscript files.
scons: Cleaning targets ...
Removed f1.o
Removed f2.o
Removed f3.o
scons: done cleaning targets.
</pre></div><div class="section" title="13.3.<2E>Removing additional files during clean: the Clean Function"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idm3190"></a>13.3.<2E>Removing additional files during clean: the <code class="function">Clean</code> Function</h2></div></div></div><p>
There may be additional files that you want removed
when the <code class="literal">-c</code> option is used,
but which <span class="application">SCons</span> doesn't know about
because they're not normal target files.
For example, perhaps a command you invoke
creates a log file as
part of building the target file you want.
You would like the log file cleaned,
but you don't want to have to teach
SCons that the command
"builds" two files.
</p><p>
You can use the <code class="function">Clean</code> function to arrange for additional files
to be removed when the <code class="literal">-c</code> option is used.
Notice, however, that the <code class="function">Clean</code> function takes two arguments,
and the <span class="emphasis"><em>second</em></span> argument
is the name of the additional file you want cleaned
(<code class="filename">foo.log</code> in this example):
</p><pre class="programlisting">
t = Command('foo.out', 'foo.in', 'build -o $TARGET $SOURCE')
Clean(t, 'foo.log')
</pre><p>
The first argument is the target with which you want
the cleaning of this additional file associated.
In the above example,
we've used the return value from the
<code class="function">Command</code> function,
which represents the
<code class="filename">foo.out</code>
target.
Now whenever the
<code class="filename">foo.out</code> target is cleaned
by the <code class="literal">-c</code> option,
the <code class="filename">foo.log</code> file
will be removed as well:
</p><pre class="screen">% <strong class="userinput"><code>scons -Q</code></strong>
build -o foo.out foo.in
% <strong class="userinput"><code>scons -Q -c</code></strong>
Removed foo.out
Removed foo.log
</pre></div></div><div class="chapter" title="Chapter<65>14.<2E>Hierarchical Builds"><div class="titlepage"><div><div><h2 class="title"><a name="chap-hierarchical"></a>Chapter<EFBFBD>14.<2E>Hierarchical Builds</h2></div></div></div><p>
The source code for large software projects
rarely stays in a single directory,
but is nearly always divided into a
hierarchy of directories.
Organizing a large software build using <span class="application">SCons</span>
involves creating a hierarchy of build scripts
using the <code class="filename">SConscript</code> function.
</p><div class="section" title="14.1.<2E>SConscript Files"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idm3217"></a>14.1.<2E><code class="filename">SConscript</code> Files</h2></div></div></div><p>
As we've already seen,
the build script at the top of the tree is called <code class="filename">SConstruct</code>.
The top-level <code class="filename">SConstruct</code> file can
use the <code class="filename">SConscript</code> function to
include other subsidiary scripts in the build.
These subsidiary scripts can, in turn,
use the <code class="filename">SConscript</code> function
to include still other scripts in the build.
By convention, these subsidiary scripts are usually
named <code class="filename">SConscript</code>.
For example, a top-level <code class="filename">SConstruct</code> file might
arrange for four subsidiary scripts to be included
in the build as follows:
</p><pre class="programlisting">
SConscript(['drivers/display/SConscript',
'drivers/mouse/SConscript',
'parser/SConscript',
'utilities/SConscript'])
</pre><p>
In this case, the <code class="filename">SConstruct</code> file
lists all of the <code class="filename">SConscript</code> files in the build explicitly.
(Note, however, that not every directory in the tree
necessarily has an <code class="filename">SConscript</code> file.)
Alternatively, the <code class="literal">drivers</code>
subdirectory might contain an intermediate
<code class="filename">SConscript</code> file,
in which case the <code class="filename">SConscript</code> call in
the top-level <code class="filename">SConstruct</code> file
would look like:
</p><pre class="programlisting">
SConscript(['drivers/SConscript',
'parser/SConscript',
'utilities/SConscript'])
</pre><p>
And the subsidiary <code class="filename">SConscript</code> file in the
<code class="literal">drivers</code> subdirectory
would look like:
</p><pre class="programlisting">
SConscript(['display/SConscript',
'mouse/SConscript'])
</pre><p>
Whether you list all of the <code class="filename">SConscript</code> files in the
top-level <code class="filename">SConstruct</code> file,
or place a subsidiary <code class="filename">SConscript</code> file in
intervening directories,
or use some mix of the two schemes,
is up to you and the needs of your software.
</p></div><div class="section" title="14.2.<2E>Path Names Are Relative to the SConscript Directory"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idm3245"></a>14.2.<2E>Path Names Are Relative to the <code class="filename">SConscript</code> Directory</h2></div></div></div><p>
Subsidiary <code class="filename">SConscript</code> files make it easy to create a build
hierarchy because all of the file and directory names
in a subsidiary <code class="filename">SConscript</code> files are interpreted
relative to the directory in which the <code class="filename">SConscript</code> file lives.
Typically, this allows the <code class="filename">SConscript</code> file containing the
instructions to build a target file
to live in the same directory as the source files
from which the target will be built,
making it easy to update how the software is built
whenever files are added or deleted
(or other changes are made).
</p><p>
For example, suppose we want to build two programs
<code class="filename">prog1</code> and <code class="filename">prog2</code> in two separate directories
with the same names as the programs.
One typical way to do this would be
with a top-level <code class="filename">SConstruct</code> file like this:
</p><pre class="programlisting">
SConscript(['prog1/SConscript',
'prog2/SConscript'])
</pre><p>
And subsidiary <code class="filename">SConscript</code> files that look like this:
</p><pre class="programlisting">
env = Environment()
env.Program('prog1', ['main.c', 'foo1.c', 'foo2.c'])
</pre><p>
And this:
</p><pre class="programlisting">
env = Environment()
env.Program('prog2', ['main.c', 'bar1.c', 'bar2.c'])
</pre><p>
Then, when we run <span class="application">SCons</span> in the top-level directory,
our build looks like:
</p><pre class="screen">% <strong class="userinput"><code>scons -Q</code></strong>
cc -o prog1/foo1.o -c prog1/foo1.c
cc -o prog1/foo2.o -c prog1/foo2.c
cc -o prog1/main.o -c prog1/main.c
cc -o prog1/prog1 prog1/main.o prog1/foo1.o prog1/foo2.o
cc -o prog2/bar1.o -c prog2/bar1.c
cc -o prog2/bar2.o -c prog2/bar2.c
cc -o prog2/main.o -c prog2/main.c
cc -o prog2/prog2 prog2/main.o prog2/bar1.o prog2/bar2.o
</pre><p>
Notice the following:
First, you can have files with the same names
in multiple directories, like main.c in the above example.
Second, unlike standard recursive use of <span class="application">Make</span>,
<span class="application">SCons</span> stays in the top-level directory
(where the <code class="filename">SConstruct</code> file lives)
and issues commands that use the path names
from the top-level directory to the
target and source files within the hierarchy.
</p></div><div class="section" title="14.3.<2E>Top-Level Path Names in Subsidiary SConscript Files"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idm3271"></a>14.3.<2E>Top-Level Path Names in Subsidiary <code class="filename">SConscript</code> Files</h2></div></div></div><p>
If you need to use a file from another directory,
it's sometimes more convenient to specify
the path to a file in another directory
from the top-level <code class="filename">SConstruct</code> directory,
even when you're using that file in
a subsidiary <code class="filename">SConscript</code> file in a subdirectory.
You can tell <span class="application">SCons</span> to interpret a path name
as relative to the top-level <code class="filename">SConstruct</code> directory,
not the local directory of the <code class="filename">SConscript</code> file,
by appending a <code class="literal">#</code> (hash mark)
to the beginning of the path name:
</p><pre class="programlisting">
env = Environment()
env.Program('prog', ['main.c', '#lib/foo1.c', 'foo2.c'])
</pre><p>
In this example,
the <code class="literal">lib</code> directory is
directly underneath the top-level <code class="filename">SConstruct</code> directory.
If the above <code class="filename">SConscript</code> file is in a subdirectory
named <code class="literal">src/prog</code>,
the output would look like:
</p><pre class="screen">% <strong class="userinput"><code>scons -Q</code></strong>
cc -o lib/foo1.o -c lib/foo1.c
cc -o src/prog/foo2.o -c src/prog/foo2.c
cc -o src/prog/main.o -c src/prog/main.c
cc -o src/prog/prog src/prog/main.o lib/foo1.o src/prog/foo2.o
</pre><p>
(Notice that the <code class="literal">lib/foo1.o</code> object file
is built in the same directory as its source file.
See <a class="xref" href="#chap-separate" title="Chapter<65>15.<2E>Separating Source and Build Directories">Chapter<EFBFBD>15, <i>Separating Source and Build Directories</i></a>, below,
for information about
how to build the object file in a different subdirectory.)
</p></div><div class="section" title="14.4.<2E>Absolute Path Names"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idm3292"></a>14.4.<2E>Absolute Path Names</h2></div></div></div><p>
Of course, you can always specify
an absolute path name for a file--for example:
</p><pre class="programlisting">
env = Environment()
env.Program('prog', ['main.c', '/usr/joe/lib/foo1.c', 'foo2.c'])
</pre><p>
Which, when executed, would yield:
</p><pre class="screen">% <strong class="userinput"><code>scons -Q</code></strong>
cc -o src/prog/foo2.o -c src/prog/foo2.c
cc -o src/prog/main.o -c src/prog/main.c
cc -o /usr/joe/lib/foo1.o -c /usr/joe/lib/foo1.c
cc -o src/prog/prog src/prog/main.o /usr/joe/lib/foo1.o src/prog/foo2.o
</pre><p>
(As was the case with top-relative path names,
notice that the <code class="literal">/usr/joe/lib/foo1.o</code> object file
is built in the same directory as its source file.
See <a class="xref" href="#chap-separate" title="Chapter<65>15.<2E>Separating Source and Build Directories">Chapter<EFBFBD>15, <i>Separating Source and Build Directories</i></a>, below,
for information about
how to build the object file in a different subdirectory.)
</p></div><div class="section" title="14.5.<2E>Sharing Environments (and Other Variables) Between SConscript Files"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idm3302"></a>14.5.<2E>Sharing Environments (and Other Variables) Between <code class="filename">SConscript</code> Files</h2></div></div></div><p>
In the previous example,
each of the subsidiary <code class="filename">SConscript</code> files
created its own construction environment
by calling <code class="function">Environment</code> separately.
This obviously works fine,
but if each program must be built
with the same construction variables,
it's cumbersome and error-prone to initialize
separate construction environments
in the same way over and over in each subsidiary
<code class="filename">SConscript</code> file.
</p><p>
<span class="application">SCons</span> supports the ability to <span class="emphasis"><em>export</em></span> variables
from a parent <code class="filename">SConscript</code> file
to its subsidiary <code class="filename">SConscript</code> files,
which allows you to share common initialized
values throughout your build hierarchy.
</p><div class="section" title="14.5.1.<2E>Exporting Variables"><div class="titlepage"><div><div><h3 class="title"><a name="idm3314"></a>14.5.1.<2E>Exporting Variables</h3></div></div></div><p>
There are two ways to export a variable,
such as a construction environment,
from an <code class="filename">SConscript</code> file,
so that it may be used by other <code class="filename">SConscript</code> files.
First, you can call the <code class="function">Export</code>
function with a list of variables,
or a string of white-space separated variable names.
Each call to <code class="function">Export</code> adds one
or more variables to a global list
of variables that are available for import
by other <code class="filename">SConscript</code> files.
</p><pre class="programlisting">
env = Environment()
Export('env')
</pre><p>
You may export more than one variable name at a time:
</p><pre class="programlisting">
env = Environment()
debug = ARGUMENTS['debug']
Export('env', 'debug')
</pre><p>
Because white space is not legal in Python variable names,
the <code class="function">Export</code> function will even automatically split
a string into separate names for you:
</p><pre class="programlisting">
Export('env debug')
</pre><p>
Second, you can specify a list of
variables to export as a second argument
to the <code class="filename">SConscript</code> function call:
</p><pre class="programlisting">
SConscript('src/SConscript', 'env')
</pre><p>
Or as the <code class="varname">exports</code> keyword argument:
</p><pre class="programlisting">
SConscript('src/SConscript', exports='env')
</pre><p>
These calls export the specified variables
to only the listed <code class="filename">SConscript</code> files.
You may, however, specify more than one
<code class="filename">SConscript</code> file in a list:
</p><pre class="programlisting">
SConscript(['src1/SConscript',
'src2/SConscript'], exports='env')
</pre><p>
This is functionally equivalent to
calling the <code class="filename">SConscript</code> function
multiple times with the same <code class="varname">exports</code> argument,
one per <code class="filename">SConscript</code> file.
</p></div><div class="section" title="14.5.2.<2E>Importing Variables"><div class="titlepage"><div><div><h3 class="title"><a name="idm3342"></a>14.5.2.<2E>Importing Variables</h3></div></div></div><p>
Once a variable has been exported from a calling
<code class="filename">SConscript</code> file,
it may be used in other <code class="filename">SConscript</code> files
by calling the <code class="function">Import</code> function:
</p><pre class="programlisting">
Import('env')
env.Program('prog', ['prog.c'])
</pre><p>
The <code class="function">Import</code> call makes the <code class="literal">env</code> construction
environment available to the <code class="filename">SConscript</code> file,
after which the variable can be used to build
programs, libraries, etc.
</p><p>
Like the <code class="function">Export</code> function,
the <code class="function">Import</code> function can be used
with multiple variable names:
</p><pre class="programlisting">
Import('env', 'debug')
env = env.Clone(DEBUG = debug)
env.Program('prog', ['prog.c'])
</pre><p>
And the <code class="function">Import</code> function will similarly
split a string along white-space
into separate variable names:
</p><pre class="programlisting">
Import('env debug')
env = env.Clone(DEBUG = debug)
env.Program('prog', ['prog.c'])
</pre><p>
Lastly, as a special case,
you may import all of the variables that
have been exported by supplying an asterisk
to the <code class="function">Import</code> function:
</p><pre class="programlisting">
Import('*')
env = env.Clone(DEBUG = debug)
env.Program('prog', ['prog.c'])
</pre><p>
If you're dealing with a lot of <code class="filename">SConscript</code> files,
this can be a lot simpler than keeping
arbitrary lists of imported variables in each file.
</p></div><div class="section" title="14.5.3.<2E>Returning Values From an SConscript File"><div class="titlepage"><div><div><h3 class="title"><a name="idm3365"></a>14.5.3.<2E>Returning Values From an <code class="filename">SConscript</code> File</h3></div></div></div><p>
Sometimes, you would like to be able to
use information from a subsidiary
<code class="filename">SConscript</code> file in some way.
For example,
suppose that you want to create one
library from source files
scattered throughout a number
of subsidiary <code class="filename">SConscript</code> files.
You can do this by using the <code class="function">Return</code>
function to return values
from the subsidiary <code class="filename">SConscript</code> files
to the calling file.
</p><p>
If, for example, we have two subdirectories
<code class="filename">foo</code> and <code class="filename">bar</code>
that should each contribute a source
file to a Library,
what we'd like to be able to do is
collect the object files
from the subsidiary <code class="filename">SConscript</code> calls
like this:
</p><pre class="programlisting">
env = Environment()
Export('env')
objs = []
for subdir in ['foo', 'bar']:
o = SConscript('%s/SConscript' % subdir)
objs.append(o)
env.Library('prog', objs)
</pre><p>
We can do this by using the <code class="function">Return</code>
function in the
<code class="literal">foo/SConscript</code> file like this:
</p><pre class="programlisting">
Import('env')
obj = env.Object('foo.c')
Return('obj')
</pre><p>
(The corresponding
<code class="literal">bar/SConscript</code>
file should be pretty obvious.)
Then when we run <span class="application">SCons</span>,
the object files from the subsidiary subdirectories
are all correctly archived in the desired library:
</p><pre class="screen">% <strong class="userinput"><code>scons -Q</code></strong>
cc -o bar/bar.o -c bar/bar.c
cc -o foo/foo.o -c foo/foo.c
ar rc libprog.a foo/foo.o bar/bar.o
ranlib libprog.a
</pre></div></div></div><div class="chapter" title="Chapter<65>15.<2E>Separating Source and Build Directories"><div class="titlepage"><div><div><h2 class="title"><a name="chap-separate"></a>Chapter<EFBFBD>15.<2E>Separating Source and Build Directories</h2></div></div></div><p>
It's often useful to keep any built files completely
separate from the source files.
In <span class="application">SCons</span>, this is usually done by creating one or more separate
<span class="emphasis"><em>variant directory trees</em></span>
that are used to hold the built objects files, libraries,
and executable programs, etc.
for a specific flavor, or variant, of build.
<span class="application">SCons</span> provides two ways to do this,
one through the <code class="filename">SConscript</code> function that we've already seen,
and the second through a more flexible <code class="function">VariantDir</code> function.
</p><p>
One historical note: the <code class="function">VariantDir</code> function
used to be called <code class="function">BuildDir</code>.
That name is still supported
but has been deprecated
because the <span class="application">SCons</span> functionality
differs from the model of a "build directory"
implemented by other build systems like the GNU Autotools.
</p><div class="section" title="15.1.<2E>Specifying a Variant Directory Tree as Part of an SConscript Call"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idm3399"></a>15.1.<2E>Specifying a Variant Directory Tree as Part of an <code class="filename">SConscript</code> Call</h2></div></div></div><p>
The most straightforward way to establish a variant directory tree
uses the fact that the usual way to
set up a build hierarchy is to have an
<code class="filename">SConscript</code> file in the source subdirectory.
If you then pass a <code class="varname">variant_dir</code> argument to the
<code class="filename">SConscript</code> function call:
</p><pre class="programlisting">
SConscript('src/SConscript', variant_dir='build')
</pre><p>
<span class="application">SCons</span> will then build all of the files in
the <code class="filename">build</code> subdirectory:
</p><pre class="screen">% <strong class="userinput"><code>ls src</code></strong>
SConscript hello.c
% <strong class="userinput"><code>scons -Q</code></strong>
cc -o build/hello.o -c build/hello.c
cc -o build/hello build/hello.o
% <strong class="userinput"><code>ls build</code></strong>
SConscript hello hello.c hello.o
</pre><p>
But wait a minute--what's going on here?
<span class="application">SCons</span> created the object file
<code class="filename">build/hello.o</code>
in the <code class="filename">build</code> subdirectory,
as expected.
But even though our <code class="filename">hello.c</code> file lives in the <code class="filename">src</code> subdirectory,
<span class="application">SCons</span> has actually compiled a
<code class="filename">build/hello.c</code> file
to create the object file.
</p><p>
What's happened is that <span class="application">SCons</span> has <span class="emphasis"><em>duplicated</em></span>
the <code class="filename">hello.c</code> file from the <code class="filename">src</code> subdirectory
to the <code class="filename">build</code> subdirectory,
and built the program from there.
The next section explains why <span class="application">SCons</span> does this.
</p></div><div class="section" title="15.2.<2E>Why SCons Duplicates Source Files in a Variant Directory Tree"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idm3429"></a>15.2.<2E>Why <span class="application">SCons</span> Duplicates Source Files in a Variant Directory Tree</h2></div></div></div><p>
<span class="application">SCons</span> duplicates source files in variant directory trees
because it's the most straightforward way to guarantee a correct build
<span class="emphasis"><em>regardless of include-file directory paths,
relative references between files,
or tool support for putting files in different locations</em></span>,
and the <span class="application">SCons</span> philosophy is to, by default,
guarantee a correct build in all cases.
</p><p>
The most direct reason to duplicate source files
in variant directories
is simply that some tools (mostly older versions)
are written to only build their output files
in the same directory as the source files.
In this case, the choices are either
to build the output file in the source directory
and move it to the variant directory,
or to duplicate the source files in the variant directory.
</p><p>
Additionally,
relative references between files
can cause problems if we don't
just duplicate the hierarchy of source files
in the variant directory.
You can see this at work in
use of the C preprocessor <code class="literal">#include</code>
mechanism with double quotes, not angle brackets:
</p><pre class="programlisting">
#include "file.h"
</pre><p>
The <span class="emphasis"><em>de facto</em></span> standard behavior
for most C compilers in this case
is to first look in the same directory
as the source file that contains the <code class="literal">#include</code> line,
then to look in the directories in the preprocessor search path.
Add to this that the <span class="application">SCons</span> implementation of
support for code repositories
(described below)
means not all of the files
will be found in the same directory hierarchy,
and the simplest way to make sure
that the right include file is found
is to duplicate the source files into the variant directory,
which provides a correct build
regardless of the original location(s) of the source files.
</p><p>
Although source-file duplication guarantees a correct build
even in these end-cases,
it <span class="emphasis"><em>can</em></span> usually be safely disabled.
The next section describes
how you can disable the duplication of source files
in the variant directory.
</p></div><div class="section" title="15.3.<2E>Telling SCons to Not Duplicate Source Files in the Variant Directory Tree"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idm3446"></a>15.3.<2E>Telling <span class="application">SCons</span> to Not Duplicate Source Files in the Variant Directory Tree</h2></div></div></div><p>
In most cases and with most tool sets,
<span class="application">SCons</span> can place its target files in a build subdirectory
<span class="emphasis"><em>without</em></span>
duplicating the source files
and everything will work just fine.
You can disable the default <span class="application">SCons</span> behavior
by specifying <code class="literal">duplicate=0</code>
when you call the <code class="filename">SConscript</code> function:
</p><pre class="programlisting">
SConscript('src/SConscript', variant_dir='build', duplicate=0)
</pre><p>
When this flag is specified,
<span class="application">SCons</span> uses the variant directory
like most people expect--that is,
the output files are placed in the variant directory
while the source files stay in the source directory:
</p><pre class="screen">
% <strong class="userinput"><code>ls src</code></strong>
SConscript
hello.c
% <strong class="userinput"><code>scons -Q</code></strong>
cc -c src/hello.c -o build/hello.o
cc -o build/hello build/hello.o
% <strong class="userinput"><code>ls build</code></strong>
hello
hello.o
</pre></div><div class="section" title="15.4.<2E>The VariantDir Function"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idm3462"></a>15.4.<2E>The <code class="function">VariantDir</code> Function</h2></div></div></div><p>
Use the <code class="function">VariantDir</code> function to establish that target
files should be built in a separate directory
from the source files:
</p><pre class="programlisting">
VariantDir('build', 'src')
env = Environment()
env.Program('build/hello.c')
</pre><p>
Note that when you're not using
an <code class="filename">SConscript</code> file in the <code class="filename">src</code> subdirectory,
you must actually specify that
the program must be built from
the <code class="filename">build/hello.c</code>
file that <span class="application">SCons</span> will duplicate in the
<code class="filename">build</code> subdirectory.
</p><p>
When using the <code class="function">VariantDir</code> function directly,
<span class="application">SCons</span> still duplicates the source files
in the variant directory by default:
</p><pre class="screen">% <strong class="userinput"><code>ls src</code></strong>
hello.c
% <strong class="userinput"><code>scons -Q</code></strong>
cc -o build/hello.o -c build/hello.c
cc -o build/hello build/hello.o
% <strong class="userinput"><code>ls build</code></strong>
hello hello.c hello.o
</pre><p>
You can specify the same <code class="literal">duplicate=0</code> argument
that you can specify for an <code class="filename">SConscript</code> call:
</p><pre class="programlisting">
VariantDir('build', 'src', duplicate=0)
env = Environment()
env.Program('build/hello.c')
</pre><p>
In which case <span class="application">SCons</span>
will disable duplication of the source files:
</p><pre class="screen">% <strong class="userinput"><code>ls src</code></strong>
hello.c
% <strong class="userinput"><code>scons -Q</code></strong>
cc -o build/hello.o -c src/hello.c
cc -o build/hello build/hello.o
% <strong class="userinput"><code>ls build</code></strong>
hello hello.o
</pre></div><div class="section" title="15.5.<2E>Using VariantDir With an SConscript File"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idm3491"></a>15.5.<2E>Using <code class="function">VariantDir</code> With an <code class="filename">SConscript</code> File</h2></div></div></div><p>
Even when using the <code class="function">VariantDir</code> function,
it's much more natural to use it with
a subsidiary <code class="filename">SConscript</code> file.
For example, if the
<code class="filename">src/SConscript</code>
looks like this:
</p><pre class="programlisting">
env = Environment()
env.Program('hello.c')
</pre><p>
Then our <code class="filename">SConstruct</code> file could look like:
</p><pre class="programlisting">
VariantDir('build', 'src')
SConscript('build/SConscript')
</pre><p>
Yielding the following output:
</p><pre class="screen">% <strong class="userinput"><code>ls src</code></strong>
SConscript hello.c
% <strong class="userinput"><code>scons -Q</code></strong>
cc -o build/hello.o -c build/hello.c
cc -o build/hello build/hello.o
% <strong class="userinput"><code>ls build</code></strong>
SConscript hello hello.c hello.o
</pre><p>
Notice that this is completely equivalent
to the use of <code class="filename">SConscript</code> that we
learned about in the previous section.
</p></div><div class="section" title="15.6.<2E>Using Glob with VariantDir"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idm3510"></a>15.6.<2E>Using <code class="function">Glob</code> with <code class="function">VariantDir</code></h2></div></div></div><p>
The <code class="function">Glob</code> file name pattern matching function
works just as usual when using <code class="function">VariantDir</code>.
For example, if the
<code class="filename">src/SConscript</code>
looks like this:
</p><pre class="programlisting">
env = Environment()
env.Program('hello', Glob('*.c'))
</pre><p>
Then with the same <code class="filename">SConstruct</code> file as in the previous section,
and source files <code class="filename">f1.c</code>
and <code class="filename">f2.c</code> in src,
we would see the following output:
</p><pre class="screen">% <strong class="userinput"><code>ls src</code></strong>
SConscript f1.c f2.c f2.h
% <strong class="userinput"><code>scons -Q</code></strong>
cc -o build/f1.o -c build/f1.c
cc -o build/f2.o -c build/f2.c
cc -o build/hello build/f1.o build/f2.o
% <strong class="userinput"><code>ls build</code></strong>
SConscript f1.c f1.o f2.c f2.h f2.o hello
</pre><p>
The <code class="function">Glob</code> function returns Nodes in the
<code class="filename">build/</code> tree, as you'd expect.
</p></div></div><div class="chapter" title="Chapter<65>16.<2E>Variant Builds"><div class="titlepage"><div><div><h2 class="title"><a name="chap-variants"></a>Chapter<EFBFBD>16.<2E>Variant Builds</h2></div></div></div><p>
The <code class="varname">variant_dir</code> keyword argument of
the <code class="filename">SConscript</code> function provides everything
we need to show how easy it is to create
variant builds using <span class="application">SCons</span>.
Suppose, for example, that we want to
build a program for both Windows and Linux platforms,
but that we want to build it in a shared directory
with separate side-by-side build directories
for the Windows and Linux versions of the program.
</p><pre class="programlisting">
platform = ARGUMENTS.get('OS', Platform())
include = "#export/$PLATFORM/include"
lib = "#export/$PLATFORM/lib"
bin = "#export/$PLATFORM/bin"
env = Environment(PLATFORM = platform,
BINDIR = bin,
INCDIR = include,
LIBDIR = lib,
CPPPATH = [include],
LIBPATH = [lib],
LIBS = 'world')
Export('env')
env.SConscript('src/SConscript', variant_dir='build/$PLATFORM')
</pre><p>
This SConstruct file,
when run on a Linux system, yields:
</p><pre class="screen">% <strong class="userinput"><code>scons -Q OS=linux</code></strong>
Install file: "build/linux/world/world.h" as "export/linux/include/world.h"
cc -o build/linux/hello/hello.o -c -Iexport/linux/include build/linux/hello/hello.c
cc -o build/linux/world/world.o -c -Iexport/linux/include build/linux/world/world.c
ar rc build/linux/world/libworld.a build/linux/world/world.o
ranlib build/linux/world/libworld.a
Install file: "build/linux/world/libworld.a" as "export/linux/lib/libworld.a"
cc -o build/linux/hello/hello build/linux/hello/hello.o -Lexport/linux/lib -lworld
Install file: "build/linux/hello/hello" as "export/linux/bin/hello"
</pre><p>
The same SConstruct file on Windows would build:
</p><pre class="screen">C:\&gt;<strong class="userinput"><code>scons -Q OS=windows</code></strong>
Install file: "build/windows/world/world.h" as "export/windows/include/world.h"
cl /Fobuild\windows\hello\hello.obj /c build\windows\hello\hello.c /nologo /Iexport\windows\include
cl /Fobuild\windows\world\world.obj /c build\windows\world\world.c /nologo /Iexport\windows\include
lib /nologo /OUT:build\windows\world\world.lib build\windows\world\world.obj
Install file: "build/windows/world/world.lib" as "export/windows/lib/world.lib"
link /nologo /OUT:build\windows\hello\hello.exe /LIBPATH:export\windows\lib world.lib build\windows\hello\hello.obj
embedManifestExeCheck(target, source, env)
Install file: "build/windows/hello/hello.exe" as "export/windows/bin/hello.exe"
</pre></div><div class="chapter" title="Chapter<65>17.<2E>Internationalization and localization with gettext"><div class="titlepage"><div><div><h2 class="title"><a name="chap-gettext"></a>Chapter<EFBFBD>17.<2E>Internationalization and localization with gettext</h2></div></div></div><p>
The <a class="link" href="#t-gettext"><code class="literal">gettext</code></a> toolset supports internationalization and localization
of SCons-based projects. Builders provided by <a class="link" href="#t-gettext"><code class="literal">gettext</code></a> automatize
generation and updates of translation files. You can manage translations and
translation templates similarly to how it's done with autotools.
</p><div class="section" title="17.1.<2E>Prerequisites"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idm3550"></a>17.1.<2E>Prerequisites</h2></div></div></div><p>
To follow examples provided in this chapter set up your operating system to
support two or more languages. In following examples we use locales
<code class="literal">en_US</code>, <code class="literal">de_DE</code>, and
<code class="literal">pl_PL</code>.
</p><p>
Ensure, that you have <a class="ulink" href="http://www.gnu.org/software/gettext/manual/gettext.html" target="_top">GNU gettext
utilities</a> installed on your system.
</p><p>
To edit translation files you may wish to install <a class="ulink" href="http://www.poedit.net/" target="_top">poedit</a> editor.
</p></div><div class="section" title="17.2.<2E>Simple project"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idm3560"></a>17.2.<2E>Simple project</h2></div></div></div><p>
Let's start with a very simple project, the "Hello world" program
for example
</p><pre class="programlisting">
/* hello.c */
#include &lt;stdio.h&gt;
int main(int argc, char* argv[])
{
printf("Hello world\n");
return 0;
}
</pre><p>
Prepare a <code class="filename">SConstruct</code> to compile the program
as usual.
</p><pre class="programlisting">
# SConstruct
env = Environment()
hello = Program(["hello.c"])
</pre><p>
</p><p>
Now we'll convert the project to a multi-lingual one. If you don't
already have <a class="ulink" href="http://www.gnu.org/software/gettext/manual/gettext.html" target="_top">GNU gettext
utilities</a> installed, install them from your preffered
package repository, or download from <a class="ulink" href="http://ftp.gnu.org/gnu/gettext/" target="_top">
http://ftp.gnu.org/gnu/gettext/</a>. For the purpose of this example,
you should have following three locales installed on your system:
<code class="literal">en_US</code>, <code class="literal">de_DE</code> and
<code class="literal">pl_PL</code>. On debian, for example, you may enable certain
locales through <span class="command"><strong>dpkg-reconfigure locales</strong></span>.
</p><p>
First prepare the <code class="filename">hello.c</code> program for
internationalization. Change the previous code so it reads as follows:
</p><pre class="programlisting">
/* hello.c */
#include &lt;stdio.h&gt;
#include &lt;libintl.h&gt;
#include &lt;locale.h&gt;
int main(int argc, char* argv[])
{
bindtextdomain("hello", "locale");
setlocale(LC_ALL, "");
textdomain("hello");
printf(gettext("Hello world\n"));
return 0;
}
</pre><p>
Detailed recipes for such conversion can
be found at <a class="ulink" href="http://www.gnu.org/software/gettext/manual/gettext.html#Sources" target="_top">
http://www.gnu.org/software/gettext/manual/gettext.html#Sources</a>.
The <code class="function">gettext("...")</code> has two purposes.
First, it marks messages for the <span class="command"><strong>xgettext(1)</strong></span> program, which
we will use to extract from the sources the messages for localization.
Second, it calls the <code class="literal">gettext</code> library internals to
translate the message at runtime.
</p><p>
Now we shall instruct SCons how to generate and maintain translation files.
For that, use the <a class="link" href="#b-Translate"><code class="function">Translate</code></a> builder and <a class="link" href="#b-MOFiles"><code class="function">MOFiles</code></a> builder.
The first one takes source files, extracts internationalized
messages from them, creates so-called <code class="literal">POT</code> file
(translation template), and then creates <code class="literal">PO</code> translation
files, one for each requested language. Later, during the development
lifecycle, the builder keeps all these files up-to date. The
<a class="link" href="#b-MOFiles"><code class="function">MOFiles</code></a> builder compiles the <code class="literal">PO</code> files to binary
form. Then install the <code class="literal">MO</code> files under directory
called <code class="filename">locale</code>.
</p><p> The completed
<code class="filename">SConstruct</code> is as follows:
</p><pre class="programlisting">
# SConstruct
env = Environment( tools = ['default', 'gettext'] )
hello = env.Program(["hello.c"])
env['XGETTEXTFLAGS'] = [
'--package-name=%s' % 'hello',
'--package-version=%s' % '1.0',
]
po = env.Translate(["pl","en", "de"], ["hello.c"], POAUTOINIT = 1)
mo = env.MOFiles(po)
InstallAs(["locale/en/LC_MESSAGES/hello.mo"], ["en.mo"])
InstallAs(["locale/pl/LC_MESSAGES/hello.mo"], ["pl.mo"])
InstallAs(["locale/de/LC_MESSAGES/hello.mo"], ["de.mo"])
</pre><p>
</p><p>
Generate the translation files with <span class="command"><strong>scons po-update</strong></span>.
You should see the output from SCons simillar to this:
</p><pre class="screen">
user@host:$ scons po-update
scons: Reading SConscript files ...
scons: done reading SConscript files.
scons: Building targets ...
Entering '/home/ptomulik/projects/tmp'
xgettext --package-name=hello --package-version=1.0 -o - hello.c
Leaving '/home/ptomulik/projects/tmp'
Writting 'messages.pot' (new file)
msginit --no-translator -l pl -i messages.pot -o pl.po
Created pl.po.
msginit --no-translator -l en -i messages.pot -o en.po
Created en.po.
msginit --no-translator -l de -i messages.pot -o de.po
Created de.po.
scons: done building targets.
</pre><p>
</p><p>
If everything is right, you should see following new files.
</p><pre class="screen">
user@host:$ ls *.po*
de.po en.po messages.pot pl.po
</pre><p>
</p><p>
Open <code class="filename">en.po</code> in <span class="command"><strong>poedit</strong></span> and provide
the English translation to message <code class="literal">"Hello world\n"</code>. Do the
same for <code class="filename">de.po</code> (deutsch) and
<code class="filename">pl.po</code> (polish). Let the translations be, for example:
</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>
<code class="literal">en: "Welcome to beautiful world!\n"</code>
</p></li><li class="listitem"><p>
<code class="literal">de: "Hallo Welt!\n"</code>
</p></li><li class="listitem"><p>
<code class="literal">pl: "Witaj swiecie!\n"</code>
</p></li></ul></div><p>
</p><p>
Now compile the project by executing <span class="command"><strong>scons</strong></span>. The
output should be similar to this:
</p><pre class="screen">
user@host:$ scons
scons: Reading SConscript files ...
scons: done reading SConscript files.
scons: Building targets ...
msgfmt -c -o de.mo de.po
msgfmt -c -o en.mo en.po
gcc -o hello.o -c hello.c
gcc -o hello hello.o
Install file: "de.mo" as "locale/de/LC_MESSAGES/hello.mo"
Install file: "en.mo" as "locale/en/LC_MESSAGES/hello.mo"
msgfmt -c -o pl.mo pl.po
Install file: "pl.mo" as "locale/pl/LC_MESSAGES/hello.mo"
scons: done building targets.
</pre><p>
SCons automatically compiled the <code class="literal">PO</code> files to binary format
<code class="literal">MO</code>, and the <code class="literal">InstallAs</code> lines installed
these files under <code class="filename">locale</code> folder.
</p><p>
Your program should be now ready. You may try it as follows (linux):
</p><pre class="screen">
user@host:$ LANG=en_US.UTF-8 ./hello
Welcome to beautiful world
</pre><p>
</p><pre class="screen">
user@host:$ LANG=de_DE.UTF-8 ./hello
Hallo Welt
</pre><p>
</p><pre class="screen">
user@host:$ LANG=pl_PL.UTF-8 ./hello
Witaj swiecie
</pre><p>
</p><p>
To demonstrate the further life of translation files, let's change Polish
translation (<span class="command"><strong>poedit pl.po</strong></span>) to <code class="literal">"Witaj drogi
swiecie\n"</code>. Run <span class="command"><strong>scons</strong></span> to see how scons
reacts to this
</p><pre class="screen">
user@host:$scons
scons: Reading SConscript files ...
scons: done reading SConscript files.
scons: Building targets ...
msgfmt -c -o pl.mo pl.po
Install file: "pl.mo" as "locale/pl/LC_MESSAGES/hello.mo"
scons: done building targets.
</pre><p>
</p><p>
Now, open <code class="filename">hello.c</code> and add another one
<code class="literal">printf</code> line with new message.
</p><pre class="programlisting">
/* hello.c */
#include &lt;stdio.h&gt;
#include &lt;libintl.h&gt;
#include &lt;locale.h&gt;
int main(int argc, char* argv[])
{
bindtextdomain("hello", "locale");
setlocale(LC_ALL, "");
textdomain("hello");
printf(gettext("Hello world\n"));
printf(gettext("and good bye\n"));
return 0;
}
</pre><p>
</p><p>
Compile project with <span class="command"><strong>scons</strong></span>. This time, the
<span class="command"><strong>msgmerge(1)</strong></span> program is used by SCons to update
<code class="literal">PO</code> file. The output from compilation is like:
</p><pre class="screen">
user@host:$scons
scons: Reading SConscript files ...
scons: done reading SConscript files.
scons: Building targets ...
Entering '/home/ptomulik/projects/tmp'
xgettext --package-name=hello --package-version=1.0 -o - hello.c
Leaving '/home/ptomulik/projects/tmp'
Writting 'messages.pot' (messages in file were outdated)
msgmerge --update de.po messages.pot
... done.
msgfmt -c -o de.mo de.po
msgmerge --update en.po messages.pot
... done.
msgfmt -c -o en.mo en.po
gcc -o hello.o -c hello.c
gcc -o hello hello.o
Install file: "de.mo" as "locale/de/LC_MESSAGES/hello.mo"
Install file: "en.mo" as "locale/en/LC_MESSAGES/hello.mo"
msgmerge --update pl.po messages.pot
... done.
msgfmt -c -o pl.mo pl.po
Install file: "pl.mo" as "locale/pl/LC_MESSAGES/hello.mo"
scons: done building targets.
</pre><p>
</p><p>
The next example demonstrates what happens if we change the source code
in such way that the internationalized messages do not change. The answer
is that none of translation files (<code class="literal">POT</code>,
<code class="literal">PO</code>) are touched (i.e. no content changes, no
creation/modification time changed and so on). Let's append another
line to the program (after the last printf), so its code becomes:
</p><pre class="programlisting">
/* hello.c */
#include &lt;stdio.h&gt;
#include &lt;libintl.h&gt;
#include &lt;locale.h&gt;
int main(int argc, char* argv[])
{
bindtextdomain("hello", "locale");
setlocale(LC_ALL, "");
textdomain("hello");
printf(gettext("Hello world\n"));
printf(gettext("and good bye\n"));
printf("----------------\n");
return a;
}
</pre><p>
Compile the project. You'll see on your screen
</p><pre class="screen">
user@host:$scons
scons: Reading SConscript files ...
scons: done reading SConscript files.
scons: Building targets ...
Entering '/home/ptomulik/projects/tmp'
xgettext --package-name=hello --package-version=1.0 -o - hello.c
Leaving '/home/ptomulik/projects/tmp'
Not writting 'messages.pot' (messages in file found to be up-to-date)
gcc -o hello.o -c hello.c
gcc -o hello hello.o
scons: done building targets.
</pre><p>
As you see, the internationalized messages ditn't change, so the
<code class="literal">POT</code> and the rest of translation files have not
even been touched.
</p></div></div><div class="chapter" title="Chapter<65>18.<2E>Writing Your Own Builders"><div class="titlepage"><div><div><h2 class="title"><a name="chap-builders-writing"></a>Chapter<EFBFBD>18.<2E>Writing Your Own Builders</h2></div></div></div><p>
Although <span class="application">SCons</span> provides many useful methods
for building common software products
(programs, libraries, documents, etc.),
you frequently want to be
able to build some other type of file
not supported directly by <span class="application">SCons</span>.
Fortunately, <span class="application">SCons</span> makes it very easy
to define your own <code class="classname">Builder</code> objects
for any custom file types you want to build.
(In fact, the <span class="application">SCons</span> interfaces for creating
<code class="classname">Builder</code> objects are flexible enough and easy enough to use
that all of the the <span class="application">SCons</span> built-in <code class="classname">Builder</code> objects
are created using the mechanisms described in this section.)
</p><div class="section" title="18.1.<2E>Writing Builders That Execute External Commands"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idm3658"></a>18.1.<2E>Writing Builders That Execute External Commands</h2></div></div></div><p>
The simplest <code class="classname">Builder</code> to create is
one that executes an external command.
For example, if we want to build
an output file by running the contents
of the input file through a command named
<code class="literal">foobuild</code>,
creating that <code class="classname">Builder</code> might look like:
</p><pre class="programlisting">
bld = Builder(action = 'foobuild &lt; $SOURCE &gt; $TARGET')
</pre><p>
All the above line does is create a free-standing
<code class="classname">Builder</code> object.
The next section will show us how to actually use it.
</p></div><div class="section" title="18.2.<2E>Attaching a Builder to a Construction Environment"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idm3667"></a>18.2.<2E>Attaching a Builder to a <code class="literal">Construction Environment</code></h2></div></div></div><p>
A <code class="classname">Builder</code> object isn't useful
until it's attached to a <code class="literal">construction environment</code>
so that we can call it to arrange
for files to be built.
This is done through the <a class="link" href="#cv-BUILDERS"><code class="envar">$BUILDERS</code></a>
<code class="literal">construction variable</code> in an environment.
The <code class="envar">$BUILDERS</code> variable is a Python dictionary
that maps the names by which you want to call
various <code class="classname">Builder</code> objects to the objects themselves.
For example, if we want to call the
<code class="classname">Builder</code> we just defined by the name
<code class="function">Foo</code>,
our <code class="filename">SConstruct</code> file might look like:
</p><pre class="programlisting">
bld = Builder(action = 'foobuild &lt; $SOURCE &gt; $TARGET')
env = Environment(BUILDERS = {'Foo' : bld})
</pre><p>
With the <code class="classname">Builder</code> attached to our <code class="literal">construction environment</code>
with the name <code class="function">Foo</code>,
we can now actually call it like so:
</p><pre class="programlisting">
env.Foo('file.foo', 'file.input')
</pre><p>
Then when we run <span class="application">SCons</span> it looks like:
</p><pre class="screen">% <strong class="userinput"><code>scons -Q</code></strong>
foobuild &lt; file.input &gt; file.foo
</pre><p>
Note, however, that the default <code class="envar">$BUILDERS</code>
variable in a <code class="literal">construction environment</code>
comes with a default set of <code class="classname">Builder</code> objects
already defined:
<a class="link" href="#b-Program"><code class="function">Program</code></a>, <a class="link" href="#b-Library"><code class="function">Library</code></a>, etc.
And when we explicitly set the <code class="envar">$BUILDERS</code> variable
when we create the <code class="literal">construction environment</code>,
the default <code class="classname">Builder</code>s are no longer part of
the environment:
</p><pre class="programlisting">
bld = Builder(action = 'foobuild &lt; $SOURCE &gt; $TARGET')
env = Environment(BUILDERS = {'Foo' : bld})
env.Foo('file.foo', 'file.input')
env.Program('hello.c')
</pre><pre class="screen">% <strong class="userinput"><code>scons -Q</code></strong>
AttributeError: 'SConsEnvironment' object has no attribute 'Program':
File "/home/my/project/SConstruct", line 4:
env.Program('hello.c')
</pre><p>
To be able to use both our own defined <code class="classname">Builder</code> objects
and the default <code class="classname">Builder</code> objects in the same <code class="literal">construction environment</code>,
you can either add to the <code class="envar">$BUILDERS</code> variable
using the <code class="function">Append</code> function:
</p><pre class="programlisting">
env = Environment()
bld = Builder(action = 'foobuild &lt; $SOURCE &gt; $TARGET')
env.Append(BUILDERS = {'Foo' : bld})
env.Foo('file.foo', 'file.input')
env.Program('hello.c')
</pre><p>
Or you can explicitly set the appropriately-named
key in the <code class="envar">$BUILDERS</code> dictionary:
</p><pre class="programlisting">
env = Environment()
bld = Builder(action = 'foobuild &lt; $SOURCE &gt; $TARGET')
env['BUILDERS']['Foo'] = bld
env.Foo('file.foo', 'file.input')
env.Program('hello.c')
</pre><p>
Either way, the same <code class="literal">construction environment</code>
can then use both the newly-defined
<code class="function">Foo</code> <code class="classname">Builder</code>
and the default <a class="link" href="#b-Program"><code class="function">Program</code></a> <code class="classname">Builder</code>:
</p><pre class="screen">% <strong class="userinput"><code>scons -Q</code></strong>
foobuild &lt; file.input &gt; file.foo
cc -o hello.o -c hello.c
cc -o hello hello.o
</pre></div><div class="section" title="18.3.<2E>Letting SCons Handle The File Suffixes"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idm3724"></a>18.3.<2E>Letting <span class="application">SCons</span> Handle The File Suffixes</h2></div></div></div><p>
By supplying additional information
when you create a <code class="classname">Builder</code>,
you can let <span class="application">SCons</span> add appropriate file
suffixes to the target and/or the source file.
For example, rather than having to specify
explicitly that you want the <code class="literal">Foo</code>
<code class="classname">Builder</code> to build the <code class="literal">file.foo</code>
target file from the <code class="literal">file.input</code> source file,
you can give the <code class="literal">.foo</code>
and <code class="literal">.input</code> suffixes to the <code class="classname">Builder</code>,
making for more compact and readable calls to
the <code class="literal">Foo</code> <code class="classname">Builder</code>:
</p><pre class="programlisting">
bld = Builder(action = 'foobuild &lt; $SOURCE &gt; $TARGET',
suffix = '.foo',
src_suffix = '.input')
env = Environment(BUILDERS = {'Foo' : bld})
env.Foo('file1')
env.Foo('file2')
</pre><pre class="screen">% <strong class="userinput"><code>scons -Q</code></strong>
foobuild &lt; file1.input &gt; file1.foo
foobuild &lt; file2.input &gt; file2.foo
</pre><p>
You can also supply a <code class="literal">prefix</code> keyword argument
if it's appropriate to have <span class="application">SCons</span> append a prefix
to the beginning of target file names.
</p></div><div class="section" title="18.4.<2E>Builders That Execute Python Functions"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idm3745"></a>18.4.<2E>Builders That Execute Python Functions</h2></div></div></div><p>
In <span class="application">SCons</span>, you don't have to call an external command
to build a file.
You can, instead, define a Python function
that a <code class="classname">Builder</code> object can invoke
to build your target file (or files).
Such a <code class="literal">builder function</code> definition looks like:
</p><pre class="programlisting">
def build_function(target, source, env):
# Code to build "target" from "source"
return None
</pre><p>
The arguments of a <code class="literal">builder function</code> are:
</p><div class="variablelist"><dl><dt><span class="term">target</span></dt><dd><p>
A list of Node objects representing
the target or targets to be
built by this builder function.
The file names of these target(s)
may be extracted using the Python <code class="function">str</code> function.
</p></dd><dt><span class="term">source</span></dt><dd><p>
A list of Node objects representing
the sources to be
used by this builder function to build the targets.
The file names of these source(s)
may be extracted using the Python <code class="function">str</code> function.
</p></dd><dt><span class="term">env</span></dt><dd><p>
The <code class="literal">construction environment</code> used for building the target(s).
The builder function may use any of the
environment's construction variables
in any way to affect how it builds the targets.
</p></dd></dl></div><p>
The builder function must
return a <code class="literal">0</code> or <code class="literal">None</code> value
if the target(s) are built successfully.
The builder function
may raise an exception
or return any non-zero value
to indicate that the build is unsuccessful.
</p><p>
Once you've defined the Python function
that will build your target file,
defining a <code class="classname">Builder</code> object for it is as
simple as specifying the name of the function,
instead of an external command,
as the <code class="classname">Builder</code>'s
<code class="literal">action</code>
argument:
</p><pre class="programlisting">
def build_function(target, source, env):
# Code to build "target" from "source"
return None
bld = Builder(action = build_function,
suffix = '.foo',
src_suffix = '.input')
env = Environment(BUILDERS = {'Foo' : bld})
env.Foo('file')
</pre><p>
And notice that the output changes slightly,
reflecting the fact that a Python function,
not an external command,
is now called to build the target file:
</p><pre class="screen">% <strong class="userinput"><code>scons -Q</code></strong>
build_function(["file.foo"], ["file.input"])
</pre></div><div class="section" title="18.5.<2E>Builders That Create Actions Using a Generator"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idm3781"></a>18.5.<2E>Builders That Create Actions Using a <code class="literal">Generator</code></h2></div></div></div><p>
<span class="application">SCons</span> Builder objects can create an action "on the fly"
by using a function called a <code class="literal">generator</code>.
This provides a great deal of flexibility to
construct just the right list of commands
to build your target.
A <code class="literal">generator</code> looks like:
</p><pre class="programlisting">
def generate_actions(source, target, env, for_signature):
return 'foobuild &lt; %s &gt; %s' % (target[0], source[0])
</pre><p>
The arguments of a <code class="literal">generator</code> are:
</p><div class="variablelist"><dl><dt><span class="term">source</span></dt><dd><p>
A list of Node objects representing
the sources to be built
by the command or other action
generated by this function.
The file names of these source(s)
may be extracted using the Python <code class="function">str</code> function.
</p></dd><dt><span class="term">target</span></dt><dd><p>
A list of Node objects representing
the target or targets to be built
by the command or other action
generated by this function.
The file names of these target(s)
may be extracted using the Python <code class="function">str</code> function.
</p></dd><dt><span class="term">env</span></dt><dd><p>
The <code class="literal">construction environment</code> used for building the target(s).
The generator may use any of the
environment's construction variables
in any way to determine what command
or other action to return.
</p></dd><dt><span class="term">for_signature</span></dt><dd><p>
A flag that specifies whether the
generator is being called to contribute to a build signature,
as opposed to actually executing the command.
</p></dd></dl></div><p>
The <code class="literal">generator</code> must return a
command string or other action that will be used to
build the specified target(s) from the specified source(s).
</p><p>
Once you've defined a <code class="literal">generator</code>,
you create a <code class="classname">Builder</code> to use it
by specifying the generator keyword argument
instead of <code class="literal">action</code>.
</p><pre class="programlisting">
def generate_actions(source, target, env, for_signature):
return 'foobuild &lt; %s &gt; %s' % (source[0], target[0])
bld = Builder(generator = generate_actions,
suffix = '.foo',
src_suffix = '.input')
env = Environment(BUILDERS = {'Foo' : bld})
env.Foo('file')
</pre><pre class="screen">% <strong class="userinput"><code>scons -Q</code></strong>
foobuild &lt; file.input &gt; file.foo
</pre><p>
Note that it's illegal to specify both an
<code class="literal">action</code>
and a
<code class="literal">generator</code>
for a <code class="classname">Builder</code>.
</p></div><div class="section" title="18.6.<2E>Builders That Modify the Target or Source Lists Using an Emitter"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idm3824"></a>18.6.<2E>Builders That Modify the Target or Source Lists Using an <code class="literal">Emitter</code></h2></div></div></div><p>
<span class="application">SCons</span> supports the ability for a Builder to modify the
lists of target(s) from the specified source(s).
You do this by defining an <code class="literal">emitter</code> function
that takes as its arguments
the list of the targets passed to the builder,
the list of the sources passed to the builder,
and the construction environment.
The emitter function should return the modified
lists of targets that should be built
and sources from which the targets will be built.
</p><p>
For example, suppose you want to define a Builder
that always calls a <code class="filename">foobuild</code> program,
and you want to automatically add
a new target file named
<code class="filename">new_target</code>
and a new source file named
<code class="filename">new_source</code>
whenever it's called.
The <code class="filename">SConstruct</code> file might look like this:
</p><pre class="programlisting">
def modify_targets(target, source, env):
target.append('new_target')
source.append('new_source')
return target, source
bld = Builder(action = 'foobuild $TARGETS - $SOURCES',
suffix = '.foo',
src_suffix = '.input',
emitter = modify_targets)
env = Environment(BUILDERS = {'Foo' : bld})
env.Foo('file')
</pre><p>
And would yield the following output:
</p><pre class="screen">% <strong class="userinput"><code>scons -Q</code></strong>
foobuild file.foo new_target - file.input new_source
</pre><p>
One very flexible thing that you can do is
use a construction variable to specify
different emitter functions for different
construction variable.
To do this, specify a string
containing a construction variable
expansion as the emitter when you call
the <code class="classname">Builder</code> function,
and set that construction variable to
the desired emitter function
in different construction environments:
</p><pre class="programlisting">
bld = Builder(action = './my_command $SOURCES &gt; $TARGET',
suffix = '.foo',
src_suffix = '.input',
emitter = '$MY_EMITTER')
def modify1(target, source, env):
return target, source + ['modify1.in']
def modify2(target, source, env):
return target, source + ['modify2.in']
env1 = Environment(BUILDERS = {'Foo' : bld},
MY_EMITTER = modify1)
env2 = Environment(BUILDERS = {'Foo' : bld},
MY_EMITTER = modify2)
env1.Foo('file1')
env2.Foo('file2')
</pre><p>
In this example, the <code class="filename">modify1.in</code>
and <code class="filename">modify2.in</code> files
get added to the source lists
of the different commands:
</p><pre class="screen">% <strong class="userinput"><code>scons -Q</code></strong>
./my_command file1.input modify1.in &gt; file1.foo
./my_command file2.input modify2.in &gt; file2.foo
</pre></div><div class="section" title="18.7.<2E>Where To Put Your Custom Builders and Tools"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idm3847"></a>18.7.<2E>Where To Put Your Custom Builders and Tools</h2></div></div></div><p>
The <code class="filename">site_scons</code> directories give you a place to
put Python modules and packages that you can import into your <code class="filename">SConscript</code> files
(<code class="filename">site_scons</code>),
add-on tools that can integrate into <span class="application">SCons</span>
(<code class="filename">site_scons/site_tools</code>),
and a <code class="filename">site_scons/site_init.py</code> file that
gets read before any <code class="filename">SConstruct</code> or <code class="filename">SConscript</code> file,
allowing you to change <span class="application">SCons</span>'s default behavior.
</p><p>
Each system type (Windows, Mac, Linux, etc.) searches a canonical
set of directories for site_scons; see the man page for details.
The top-level SConstruct's site_scons dir is always searched last,
and its dir is placed first in the tool path so it overrides all
others.
</p><p>
If you get a tool from somewhere (the <span class="application">SCons</span> wiki or a third party,
for instance) and you'd like to use it in your project, a
<code class="filename">site_scons</code> dir is the simplest place to put it.
Tools come in two flavors; either a Python function that operates on
an <code class="function">Environment</code> or a Python module or package containing two functions,
<code class="function">exists()</code> and <code class="function">generate()</code>.
</p><p>
A single-function Tool can just be included in your
<code class="filename">site_scons/site_init.py</code> file where it will be
parsed and made available for use. For instance, you could have a
<code class="filename">site_scons/site_init.py</code> file like this:
</p><pre class="programlisting">
def TOOL_ADD_HEADER(env):
"""A Tool to add a header from $HEADER to the source file"""
add_header = Builder(action=['echo "$HEADER" &gt; $TARGET',
'cat $SOURCE &gt;&gt; $TARGET'])
env.Append(BUILDERS = {'AddHeader' : add_header})
env['HEADER'] = '' # set default value
</pre><p>
and a <code class="filename">SConstruct</code> like this:
</p><pre class="programlisting">
# Use TOOL_ADD_HEADER from site_scons/site_init.py
env=Environment(tools=['default', TOOL_ADD_HEADER], HEADER="=====")
env.AddHeader('tgt', 'src')
</pre><p>
The <code class="function">TOOL_ADD_HEADER</code> tool method will be
called to add the <code class="function">AddHeader</code> tool to the
environment.
</p><p>
A more full-fledged tool with
<code class="function">exists()</code> and <code class="function">generate()</code>
methods can be installed either as a module in the file
<code class="filename">site_scons/site_tools/toolname.py</code> or as a
package in the
directory <code class="filename">site_scons/site_tools/toolname</code>. In
the case of using a package, the <code class="function">exists()</code>
and <code class="function">generate()</code> are in the
file <code class="filename">site_scons/site_tools/toolname/__init__.py</code>.
(In all the above case <code class="filename">toolname</code> is replaced
by the name of the tool.)
Since <code class="filename">site_scons/site_tools</code> is automatically
added to the head of the tool search path, any tool found there
will be available to all environments. Furthermore, a tool found
there will override a built-in tool of the same name, so if you
need to change the behavior of a built-in
tool, <code class="filename">site_scons</code> gives you the hook you need.
</p><p>
Many people have a library of utility Python functions they'd like
to include in <code class="filename">SConscript</code>s; just put that module in
<code class="filename">site_scons/my_utils.py</code> or any valid Python module name of your
choice. For instance you can do something like this in
<code class="filename">site_scons/my_utils.py</code> to add
<code class="function">build_id</code> and <code class="function">MakeWorkDir</code>
functions:
</p><pre class="programlisting">
from SCons.Script import * # for Execute and Mkdir
def build_id():
"""Return a build ID (stub version)"""
return "100"
def MakeWorkDir(workdir):
"""Create the specified dir immediately"""
Execute(Mkdir(workdir))
</pre><p>
And then in your <code class="filename">SConscript</code> or any sub-<code class="filename">SConscript</code> anywhere in
your build, you can import <code class="filename">my_utils</code> and use it:
</p><pre class="programlisting">
import my_utils
print("build_id=" + my_utils.build_id())
my_utils.MakeWorkDir('/tmp/work')
</pre><p>
Note that although you can put this library in
<code class="filename">site_scons/site_init.py</code>,
it is no better there than <code class="filename">site_scons/my_utils.py</code>
since you still have to import that module into your <code class="filename">SConscript</code>.
Also note that in order to refer to objects in the SCons namespace
such as <code class="function">Environment</code> or <code class="function">Mkdir</code> or <code class="function">Execute</code> in any file other
than a <code class="filename">SConstruct</code> or <code class="filename">SConscript</code> you always need to do
</p><pre class="programlisting">
from SCons.Script import *
</pre><p>
This is true in modules in <code class="filename">site_scons</code> such as
<code class="filename">site_scons/site_init.py</code> as well.
</p><p>
You can use any of the user- or machine-wide site dirs such as
<code class="filename">~/.scons/site_scons</code> instead of
<code class="filename">./site_scons</code>, or use the
<code class="literal">--site-dir</code> option to point to your own dir.
<code class="filename">site_init.py</code> and
<code class="filename">site_tools</code> will be located under that dir.
To avoid using a <code class="filename">site_scons</code> dir at all,
even if it exists, use the <code class="literal">--no-site-dir</code>
option.
</p></div></div><div class="chapter" title="Chapter<65>19.<2E>Not Writing a Builder: the Command Builder"><div class="titlepage"><div><div><h2 class="title"><a name="chap-builders-commands"></a>Chapter<EFBFBD>19.<2E>Not Writing a Builder: the <code class="function">Command</code> Builder</h2></div></div></div><p>
Creating a <code class="classname">Builder</code> and attaching it to a <code class="literal">construction environment</code>
allows for a lot of flexibility when you
want to re-use actions
to build multiple files of the same type.
This can, however, be cumbersome
if you only need to execute one specific command
to build a single file (or group of files).
For these situations, <span class="application">SCons</span> supports a
<code class="function">Command</code> <code class="classname">Builder</code> that arranges
for a specific action to be executed
to build a specific file or files.
This looks a lot like the other builders
(like <a class="link" href="#b-Program"><code class="function">Program</code></a>, <a class="link" href="#b-Object"><code class="function">Object</code></a>, etc.),
but takes as an additional argument
the command to be executed to build the file:
</p><pre class="programlisting">
env = Environment()
env.Command('foo.out', 'foo.in', "sed 's/x/y/' &lt; $SOURCE &gt; $TARGET")
</pre><p>
When executed,
<span class="application">SCons</span> runs the specified command,
substituting <a class="link" href="#cv-SOURCE"><code class="envar">$SOURCE</code></a> and <a class="link" href="#cv-TARGET"><code class="envar">$TARGET</code></a>
as expected:
</p><pre class="screen">% <strong class="userinput"><code>scons -Q</code></strong>
sed 's/x/y/' &lt; foo.in &gt; foo.out
</pre><p>
This is often more convenient than
creating a <code class="classname">Builder</code> object
and adding it to the <a class="link" href="#cv-BUILDERS"><code class="envar">$BUILDERS</code></a> variable
of a <code class="literal">construction environment</code>
</p><p>
Note that the action you specify to the
<code class="function">Command</code> <code class="classname">Builder</code> can be any legal <span class="application">SCons</span> <code class="classname">Action</code>,
such as a Python function:
</p><pre class="programlisting">
env = Environment()
def build(target, source, env):
# Whatever it takes to build
return None
env.Command('foo.out', 'foo.in', build)
</pre><p>
Which executes as follows:
</p><pre class="screen">% <strong class="userinput"><code>scons -Q</code></strong>
build(["foo.out"], ["foo.in"])
</pre><p>
Note that <a class="link" href="#cv-SOURCE"><code class="envar">$SOURCE</code></a> and <a class="link" href="#cv-TARGET"><code class="envar">$TARGET</code></a> are expanded
in the source and target as well as of SCons 1.1,
so you can write:
</p><pre class="programlisting">
env.Command('${SOURCE.basename}.out', 'foo.in', build)
</pre><p>
which does the same thing as the previous example, but allows you
to avoid repeating yourself.
</p></div><div class="chapter" title="Chapter<65>20.<2E>Pseudo-Builders: the AddMethod function"><div class="titlepage"><div><div><h2 class="title"><a name="chap-add-method"></a>Chapter<EFBFBD>20.<2E>Pseudo-Builders: the AddMethod function</h2></div></div></div><p>
The <code class="function">AddMethod</code> function is used to add a method
to an environment. It's typically used to add a "pseudo-builder,"
a function that looks like a <code class="classname">Builder</code> but
wraps up calls to multiple other <code class="classname">Builder</code>s
or otherwise processes its arguments
before calling one or more <code class="classname">Builder</code>s.
In the following example,
we want to install the program into the standard
<code class="filename">/usr/bin</code> directory hierarchy,
but also copy it into a local <code class="filename">install/bin</code>
directory from which a package might be built:
</p><pre class="programlisting">
def install_in_bin_dirs(env, source):
"""Install source in both bin dirs"""
i1 = env.Install("$BIN", source)
i2 = env.Install("$LOCALBIN", source)
return [i1[0], i2[0]] # Return a list, like a normal builder
env = Environment(BIN='/usr/bin', LOCALBIN='#install/bin')
env.AddMethod(install_in_bin_dirs, "InstallInBinDirs")
env.InstallInBinDirs(Program('hello.c')) # installs hello in both bin dirs
</pre><p>
This produces the following:
</p><pre class="screen">% <strong class="userinput"><code>scons -Q /</code></strong>
cc -o hello.o -c hello.c
cc -o hello hello.o
Install file: "hello" as "/usr/bin/hello"
Install file: "hello" as "install/bin/hello"
</pre><p>
As mentioned, a pseudo-builder also provides more flexibility
in parsing arguments than you can get with a <code class="classname">Builder</code>.
The next example shows a pseudo-builder with a
named argument that modifies the filename, and a separate argument
for the resource file (rather than having the builder figure it out
by file extension). This example also demonstrates using the global
<code class="function">AddMethod</code> function to add a method to the global Environment class,
so it will be used in all subsequently created environments.
</p><pre class="programlisting">
def BuildTestProg(env, testfile, resourcefile, testdir="tests"):
"""Build the test program;
prepends "test_" to src and target,
and puts target into testdir."""
srcfile = "test_%s.c" % testfile
target = "%s/test_%s" % (testdir, testfile)
if env['PLATFORM'] == 'win32':
resfile = env.RES(resourcefile)
p = env.Program(target, [srcfile, resfile])
else:
p = env.Program(target, srcfile)
return p
AddMethod(Environment, BuildTestProg)
env = Environment()
env.BuildTestProg('stuff', resourcefile='res.rc')
</pre><p>
This produces the following on Linux:
</p><pre class="screen">% <strong class="userinput"><code>scons -Q</code></strong>
cc -o test_stuff.o -c test_stuff.c
cc -o tests/test_stuff test_stuff.o
</pre><p>
And the following on Windows:
</p><pre class="screen">C:\&gt;<strong class="userinput"><code>scons -Q</code></strong>
rc /fores.res res.rc
cl /Fotest_stuff.obj /c test_stuff.c /nologo
link /nologo /OUT:tests\test_stuff.exe test_stuff.obj res.res
embedManifestExeCheck(target, source, env)
</pre><p>
Using <code class="function">AddMethod</code> is better than just adding an instance method
to a <code class="literal">construction environment</code> because it gets called as a proper method,
and because <code class="function">AddMethod</code> provides for copying the method
to any clones of the <code class="literal">construction environment</code> instance.
</p></div><div class="chapter" title="Chapter<65>21.<2E>Writing Scanners"><div class="titlepage"><div><div><h2 class="title"><a name="chap-scanners"></a>Chapter<EFBFBD>21.<2E>Writing Scanners</h2></div></div></div><p>
<span class="application">SCons</span> has built-in scanners that know how to look in
C, Fortran and IDL source files for information about
other files that targets built from those files depend on--for example,
in the case of files that use the C preprocessor,
the <code class="filename">.h</code> files that are specified
using <code class="literal">#include</code> lines in the source.
You can use the same mechanisms that <span class="application">SCons</span> uses to create
its built-in scanners to write scanners of your own for file types
that <span class="application">SCons</span> does not know how to scan "out of the box."
</p><div class="section" title="21.1.<2E>A Simple Scanner Example"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idm3999"></a>21.1.<2E>A Simple Scanner Example</h2></div></div></div><p>
Suppose, for example, that we want to create a simple scanner
for <code class="filename">.foo</code> files.
A <code class="filename">.foo</code> file contains some text that
will be processed,
and can include other files on lines that begin
with <code class="literal">include</code>
followed by a file name:
</p><pre class="programlisting">
include filename.foo
</pre><p>
Scanning a file will be handled by a Python function
that you must supply.
Here is a function that will use the Python
<code class="filename">re</code> module
to scan for the <code class="literal">include</code> lines in our example:
</p><pre class="programlisting">
import re
include_re = re.compile(r'^include\s+(\S+)$', re.M)
def kfile_scan(node, env, path, arg):
contents = node.get_text_contents()
return env.File(include_re.findall(contents))
</pre><p>
It is important to note that you
have to return a list of File nodes from the scanner function, simple
strings for the file names won't do. As in the examples we are showing here,
you can use the <code class="function">File</code>
function of your current Environment in order to create nodes on the fly from
a sequence of file names with relative paths.
</p><p>
The scanner function must
accept the four specified arguments
and return a list of implicit dependencies.
Presumably, these would be dependencies found
from examining the contents of the file,
although the function can perform any
manipulation at all to generate the list of
dependencies.
</p><div class="variablelist"><dl><dt><span class="term">node</span></dt><dd><p>
An <span class="application">SCons</span> node object representing the file being scanned.
The path name to the file can be
used by converting the node to a string
using the <code class="literal">str()</code> function,
or an internal <span class="application">SCons</span> <code class="literal">get_text_contents()</code>
object method can be used to fetch the contents.
</p></dd><dt><span class="term">env</span></dt><dd><p>
The construction environment in effect for this scan.
The scanner function may choose to use construction
variables from this environment to affect its behavior.
</p></dd><dt><span class="term">path</span></dt><dd><p>
A list of directories that form the search path for included files
for this scanner.
This is how <span class="application">SCons</span> handles the <a class="link" href="#cv-CPPPATH"><code class="envar">$CPPPATH</code></a> and <a class="link" href="#cv-LIBPATH"><code class="envar">$LIBPATH</code></a>
variables.
</p></dd><dt><span class="term">arg</span></dt><dd><p>
An optional argument that you can choose to
have passed to this scanner function by
various scanner instances.
</p></dd></dl></div><p>
A Scanner object is created using the <code class="classname">Scanner</code> function,
which typically takes an <code class="literal">skeys</code> argument
to associate the type of file suffix with this scanner.
The Scanner object must then be associated with the
<a class="link" href="#cv-SCANNERS"><code class="envar">$SCANNERS</code></a> construction variable of a construction environment,
typically by using the <code class="function">Append</code> method:
</p><pre class="programlisting">
kscan = Scanner(function = kfile_scan,
skeys = ['.k'])
env.Append(SCANNERS = kscan)
</pre><p>
When we put it all together, it looks like:
</p><pre class="programlisting">
import re
include_re = re.compile(r'^include\s+(\S+)$', re.M)
def kfile_scan(node, env, path):
contents = node.get_text_contents()
includes = include_re.findall(contents)
return env.File(includes)
kscan = Scanner(function = kfile_scan,
skeys = ['.k'])
env = Environment(ENV = {'PATH' : '/usr/local/bin'})
env.Append(SCANNERS = kscan)
env.Command('foo', 'foo.k', 'kprocess &lt; $SOURCES &gt; $TARGET')
</pre></div><div class="section" title="21.2.<2E>Adding a search path to a scanner: FindPathDirs"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idm4048"></a>21.2.<2E>Adding a search path to a scanner: <code class="function">FindPathDirs</code></h2></div></div></div><p>
Many scanners need to search for included files or dependencies
using a path variable; this is how <a class="link" href="#cv-CPPPATH"><code class="envar">$CPPPATH</code></a> and
<a class="link" href="#cv-LIBPATH"><code class="envar">$LIBPATH</code></a> work. The path to search is passed to your
scanner as the <code class="literal">path</code> argument. Path variables
may be lists of nodes, semicolon-separated strings, or even
contain SCons variables which need to be expanded. Fortunately,
<span class="application">SCons</span> provides the <code class="function">FindPathDirs</code> function which itself returns
a function to expand a given path (given as a SCons construction
variable name) to a list of paths at the time the scanner is
called. Deferring evaluation until that point allows, for
instance, the path to contain $TARGET references which differ for
each file scanned.
</p><p>
Using <code class="function">FindPathDirs</code> is quite easy. Continuing the above example,
using KPATH as the construction variable with the search path
(analogous to <a class="link" href="#cv-CPPPATH"><code class="envar">$CPPPATH</code></a>), we just modify the <code class="classname">Scanner</code>
constructor call to include a path keyword arg:
</p><pre class="programlisting">
kscan = Scanner(function = kfile_scan,
skeys = ['.k'],
path_function = FindPathDirs('KPATH'))
</pre><p>
FindPathDirs returns a callable object that, when called, will
essentially expand the elements in env['KPATH'] and tell the
scanner to search in those dirs. It will also properly add
related repository and variant dirs to the search list. As a side
note, the returned method stores the path in an efficient way so
lookups are fast even when variable substitutions may be needed.
This is important since many files get scanned in a typical build.
</p></div><div class="section" title="21.3.<2E>Using scanners with Builders"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idm4066"></a>21.3.<2E>Using scanners with Builders</h2></div></div></div><p>
One approach for the use of scanners is with builders.
There are two optional parameters we can use with a builder
<code class="literal">source_scanner</code> and <code class="literal">target_scanner</code>.
</p><pre class="programlisting">
def kfile_scan(node, env, path, arg):
contents = node.get_text_contents()
return env.File(include_re.findall(contents))
kscan = Scanner(function = kfile_scan,
skeys = ['.k'],
path_function = FindPathDirs('KPATH'))
def build_function(target, source, env):
# Code to build "target" from "source"
return None
bld = Builder(action = build_function,
suffix = '.foo',
source_scanner = kscan
src_suffix = '.input')
env = Environment(BUILDERS = {'Foo' : bld})
env.Foo('file')
</pre><p>
An emitter function can modify the list of sources or targets
passed to the action function when the builder is triggered.
</p><p>
A scanner function will not affect the list of sources or targets
seen by the builder during the build action. The scanner function
will however affect if the builder should be rebuilt (if any of
the files sourced by the scanner have changed for example).
</p></div></div><div class="chapter" title="Chapter<65>22.<2E>Building From Code Repositories"><div class="titlepage"><div><div><h2 class="title"><a name="chap-repositories"></a>Chapter<EFBFBD>22.<2E>Building From Code Repositories</h2></div></div></div><p>
Often, a software project will have
one or more central repositories,
directory trees that contain
source code, or derived files, or both.
You can eliminate additional unnecessary
rebuilds of files by having <span class="application">SCons</span>
use files from one or more code repositories
to build files in your local build tree.
</p><div class="section" title="22.1.<2E>The Repository Method"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idm4078"></a>22.1.<2E>The <code class="function">Repository</code> Method</h2></div></div></div><p>
It's often useful to allow multiple programmers working
on a project to build software from
source files and/or derived files that
are stored in a centrally-accessible repository,
a directory copy of the source code tree.
(Note that this is not the sort of repository
maintained by a source code management system
like BitKeeper, CVS, or Subversion.)
You use the <code class="function">Repository</code> method
to tell <span class="application">SCons</span> to search one or more
central code repositories (in order)
for any source files and derived files
that are not present in the local build tree:
</p><pre class="programlisting">
env = Environment()
env.Program('hello.c')
Repository('/usr/repository1', '/usr/repository2')
</pre><p>
Multiple calls to the <code class="function">Repository</code> method
will simply add repositories to the global list
that <span class="application">SCons</span> maintains,
with the exception that <span class="application">SCons</span> will automatically eliminate
the current directory and any non-existent
directories from the list.
</p></div><div class="section" title="22.2.<2E>Finding source files in repositories"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idm4089"></a>22.2.<2E>Finding source files in repositories</h2></div></div></div><p>
The above example
specifies that <span class="application">SCons</span>
will first search for files under
the <code class="filename">/usr/repository1</code> tree
and next under the <code class="filename">/usr/repository2</code> tree.
<span class="application">SCons</span> expects that any files it searches
for will be found in the same position
relative to the top-level directory.
In the above example, if the <code class="filename">hello.c</code> file is not
found in the local build tree,
<span class="application">SCons</span> will search first for
a <code class="filename">/usr/repository1/hello.c</code> file
and then for a <code class="filename">/usr/repository2/hello.c</code> file
to use in its place.
</p><p>
So given the <code class="filename">SConstruct</code> file above,
if the <code class="filename">hello.c</code> file exists in the local
build directory,
<span class="application">SCons</span> will rebuild the <code class="filename">hello</code> program
as normal:
</p><pre class="screen">% <strong class="userinput"><code>scons -Q</code></strong>
cc -o hello.o -c hello.c
cc -o hello hello.o
</pre><p>
If, however, there is no local <code class="filename">hello.c</code> file,
but one exists in <code class="filename">/usr/repository1</code>,
<span class="application">SCons</span> will recompile the <code class="filename">hello</code> program
from the source file it finds in the repository:
</p><pre class="screen">% <strong class="userinput"><code>scons -Q</code></strong>
cc -o hello.o -c /usr/repository1/hello.c
cc -o hello hello.o
</pre><p>
And similarly, if there is no local <code class="filename">hello.c</code> file
and no <code class="filename">/usr/repository1/hello.c</code>,
but one exists in <code class="filename">/usr/repository2</code>:
</p><pre class="screen">% <strong class="userinput"><code>scons -Q</code></strong>
cc -o hello.o -c /usr/repository2/hello.c
cc -o hello hello.o
</pre><p>
</p></div><div class="section" title="22.3.<2E>Finding #include files in repositories"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idm4121"></a>22.3.<2E>Finding <code class="literal">#include</code> files in repositories</h2></div></div></div><p>
We've already seen that SCons will scan the contents of
a source file for <code class="literal">#include</code> file names
and realize that targets built from that source file
also depend on the <code class="literal">#include</code> file(s).
For each directory in the <a class="link" href="#cv-CPPPATH"><code class="envar">$CPPPATH</code></a> list,
<span class="application">SCons</span> will actually search the corresponding directories
in any repository trees and establish the
correct dependencies on any
<code class="literal">#include</code> files that it finds
in repository directory.
</p><p>
Unless the C compiler also knows about these directories
in the repository trees, though,
it will be unable to find the <code class="literal">#include</code> files.
If, for example, the <code class="filename">hello.c</code> file in
our previous example includes the <code class="filename">hello.h</code>
in its current directory,
and the <code class="filename">hello.h</code> only exists in the repository:
</p><pre class="screen">
% <strong class="userinput"><code>scons -Q</code></strong>
cc -o hello.o -c hello.c
hello.c:1: hello.h: No such file or directory
</pre><p>
In order to inform the C compiler about the repositories,
<span class="application">SCons</span> will add appropriate
<code class="literal">-I</code> flags to the compilation commands
for each directory in the <code class="envar">$CPPPATH</code> list.
So if we add the current directory to the
construction environment <code class="envar">$CPPPATH</code> like so:
</p><pre class="programlisting">
env = Environment(CPPPATH = ['.'])
env.Program('hello.c')
Repository('/usr/repository1')
</pre><p>
Then re-executing <span class="application">SCons</span> yields:
</p><pre class="screen">% <strong class="userinput"><code>scons -Q</code></strong>
cc -o hello.o -c -I. -I/usr/repository1 hello.c
cc -o hello hello.o
</pre><p>
The order of the <code class="literal">-I</code> options replicates,
for the C preprocessor,
the same repository-directory search path
that <span class="application">SCons</span> uses for its own dependency analysis.
If there are multiple repositories and multiple <code class="envar">$CPPPATH</code>
directories, <span class="application">SCons</span> will add the repository directories
to the beginning of each <code class="envar">$CPPPATH</code> directory,
rapidly multiplying the number of <code class="literal">-I</code> flags.
If, for example, the <code class="envar">$CPPPATH</code> contains three directories
(and shorter repository path names!):
</p><pre class="programlisting">
env = Environment(CPPPATH = ['dir1', 'dir2', 'dir3'])
env.Program('hello.c')
Repository('/r1', '/r2')
</pre><p>
Then we'll end up with nine <code class="literal">-I</code> options
on the command line,
three (for each of the <code class="envar">$CPPPATH</code> directories)
times three (for the local directory plus the two repositories):
</p><pre class="screen">% <strong class="userinput"><code>scons -Q</code></strong>
cc -o hello.o -c -Idir1 -I/r1/dir1 -I/r2/dir1 -Idir2 -I/r1/dir2 -I/r2/dir2 -Idir3 -I/r1/dir3 -I/r2/dir3 hello.c
cc -o hello hello.o
</pre><div class="section" title="22.3.1.<2E>Limitations on #include files in repositories"><div class="titlepage"><div><div><h3 class="title"><a name="idm4162"></a>22.3.1.<2E>Limitations on <code class="literal">#include</code> files in repositories</h3></div></div></div><p>
<span class="application">SCons</span> relies on the C compiler's
<code class="literal">-I</code> options to control the order in which
the preprocessor will search the repository directories
for <code class="literal">#include</code> files.
This causes a problem, however, with how the C preprocessor
handles <code class="literal">#include</code> lines with
the file name included in double-quotes.
</p><p>
As we've seen,
<span class="application">SCons</span> will compile the <code class="filename">hello.c</code> file from
the repository if it doesn't exist in
the local directory.
If, however, the <code class="filename">hello.c</code> file in the repository contains
a <code class="literal">#include</code> line with the file name in
double quotes:
</p><pre class="programlisting">
#include "hello.h"
int
main(int argc, char *argv[])
{
printf(HELLO_MESSAGE);
return (0);
}
</pre><p>
Then the C preprocessor will <span class="emphasis"><em>always</em></span>
use a <code class="filename">hello.h</code> file from the repository directory first,
even if there is a <code class="filename">hello.h</code> file in the local directory,
despite the fact that the command line specifies
<code class="literal">-I</code> as the first option:
</p><pre class="screen">% <strong class="userinput"><code>scons -Q</code></strong>
cc -o hello.o -c -I. -I/usr/repository1 /usr/repository1/hello.c
cc -o hello hello.o
</pre><p>
This behavior of the C preprocessor--always search
for a <code class="literal">#include</code> file in double-quotes
first in the same directory as the source file,
and only then search the <code class="literal">-I</code>--can
not, in general, be changed.
In other words, it's a limitation
that must be lived with if you want to use
code repositories in this way.
There are three ways you can possibly
work around this C preprocessor behavior:
</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>
Some modern versions of C compilers do have an option
to disable or control this behavior.
If so, add that option to <a class="link" href="#cv-CFLAGS"><code class="envar">$CFLAGS</code></a>
(or <a class="link" href="#cv-CXXFLAGS"><code class="envar">$CXXFLAGS</code></a> or both) in your construction environment(s).
Make sure the option is used for all construction
environments that use C preprocessing!
</p></li><li class="listitem"><p>
Change all occurrences of <code class="literal">#include "file.h"</code>
to <code class="literal">#include &lt;file.h&gt;</code>.
Use of <code class="literal">#include</code> with angle brackets
does not have the same behavior--the <code class="literal">-I</code>
directories are searched first
for <code class="literal">#include</code> files--which
gives <span class="application">SCons</span> direct control over the list of
directories the C preprocessor will search.
</p></li><li class="listitem"><p>
Require that everyone working with compilation from
repositories check out and work on entire directories of files,
not individual files.
(If you use local wrapper scripts around
your source code control system's command,
you could add logic to enforce this restriction there.
</p></li></ol></div></div></div><div class="section" title="22.4.<2E>Finding the SConstruct file in repositories"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idm4203"></a>22.4.<2E>Finding the <code class="filename">SConstruct</code> file in repositories</h2></div></div></div><p>
<span class="application">SCons</span> will also search in repositories
for the <code class="filename">SConstruct</code> file and any specified <code class="filename">SConscript</code> files.
This poses a problem, though: how can <span class="application">SCons</span> search a
repository tree for an <code class="filename">SConstruct</code> file
if the <code class="filename">SConstruct</code> file itself contains the information
about the pathname of the repository?
To solve this problem, <span class="application">SCons</span> allows you
to specify repository directories
on the command line using the <code class="literal">-Y</code> option:
</p><pre class="screen">
% <strong class="userinput"><code>scons -Q -Y /usr/repository1 -Y /usr/repository2</code></strong>
</pre><p>
When looking for source or derived files,
<span class="application">SCons</span> will first search the repositories
specified on the command line,
and then search the repositories
specified in the <code class="filename">SConstruct</code> or <code class="filename">SConscript</code> files.
</p></div><div class="section" title="22.5.<2E>Finding derived files in repositories"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idm4221"></a>22.5.<2E>Finding derived files in repositories</h2></div></div></div><p>
If a repository contains not only source files,
but also derived files (such as object files,
libraries, or executables), <span class="application">SCons</span> will perform
its normal MD5 signature calculation to
decide if a derived file in a repository is up-to-date,
or the derived file must be rebuilt in the local build directory.
For the <span class="application">SCons</span> signature calculation to work correctly,
a repository tree must contain the <code class="filename">.sconsign</code> files
that <span class="application">SCons</span> uses to keep track of signature information.
</p><p>
Usually, this would be done by a build integrator
who would run <span class="application">SCons</span> in the repository
to create all of its derived files and <code class="filename">.sconsign</code> files,
or who would run <span class="application">SCons</span> in a separate build directory
and copy the resulting tree to the desired repository:
</p><pre class="screen">% <strong class="userinput"><code>cd /usr/repository1</code></strong>
% <strong class="userinput"><code>scons -Q</code></strong>
cc -o file1.o -c file1.c
cc -o file2.o -c file2.c
cc -o hello.o -c hello.c
cc -o hello hello.o file1.o file2.o
</pre><p>
(Note that this is safe even if the <code class="filename">SConstruct</code> file
lists <code class="filename">/usr/repository1</code> as a repository,
because <span class="application">SCons</span> will remove the current build directory
from its repository list for that invocation.)
</p><p>
Now, with the repository populated,
we only need to create the one local source file
we're interested in working with at the moment,
and use the <code class="literal">-Y</code> option to
tell <span class="application">SCons</span> to fetch any other files it needs
from the repository:
</p><pre class="screen">
% <strong class="userinput"><code>cd $HOME/build</code></strong>
% <strong class="userinput"><code>edit hello.c</code></strong>
% <strong class="userinput"><code>scons -Q -Y /usr/repository1</code></strong>
cc -c -o hello.o hello.c
cc -o hello hello.o /usr/repository1/file1.o /usr/repository1/file2.o
</pre><p>
Notice that <span class="application">SCons</span> realizes that it does not need to
rebuild local copies <code class="filename">file1.o</code> and <code class="filename">file2.o</code> files,
but instead uses the already-compiled files
from the repository.
</p></div><div class="section" title="22.6.<2E>Guaranteeing local copies of files"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idm4250"></a>22.6.<2E>Guaranteeing local copies of files</h2></div></div></div><p>
If the repository tree contains the complete results of a build,
and we try to build from the repository
without any files in our local tree,
something moderately surprising happens:
</p><pre class="screen">
% <strong class="userinput"><code>mkdir $HOME/build2</code></strong>
% <strong class="userinput"><code>cd $HOME/build2</code></strong>
% <strong class="userinput"><code>scons -Q -Y /usr/all/repository hello</code></strong>
scons: `hello' is up-to-date.
</pre><p>
Why does <span class="application">SCons</span> say that the <code class="filename">hello</code> program
is up-to-date when there is no <code class="filename">hello</code> program
in the local build directory?
Because the repository (not the local directory)
contains the up-to-date <code class="filename">hello</code> program,
and <span class="application">SCons</span> correctly determines that nothing
needs to be done to rebuild that
up-to-date copy of the file.
</p><p>
There are, however, many times when you want to ensure that a
local copy of a file always exists.
A packaging or testing script, for example,
may assume that certain generated files exist locally.
To tell <span class="application">SCons</span> to make a copy of any up-to-date repository
file in the local build directory,
use the <code class="function">Local</code> function:
</p><pre class="programlisting">
env = Environment()
hello = env.Program('hello.c')
Local(hello)
</pre><p>
If we then run the same command,
<span class="application">SCons</span> will make a local copy of the program
from the repository copy,
and tell you that it is doing so:
</p><pre class="screen">
% <strong class="userinput"><code>scons -Y /usr/all/repository hello</code></strong>
Local copy of hello from /usr/all/repository/hello
scons: `hello' is up-to-date.
</pre><p>
(Notice that, because the act of making the local copy
is not considered a "build" of the <code class="filename">hello</code> file,
<span class="application">SCons</span> still reports that it is up-to-date.)
</p></div></div><div class="chapter" title="Chapter<65>23.<2E>Multi-Platform Configuration (Autoconf Functionality)"><div class="titlepage"><div><div><h2 class="title"><a name="chap-sconf"></a>Chapter<EFBFBD>23.<2E>Multi-Platform Configuration (<span class="application">Autoconf</span> Functionality)</h2></div></div></div><p>
<span class="application">SCons</span> has integrated support for multi-platform build configuration
similar to that offered by GNU <span class="application">Autoconf</span>,
such as
figuring out what libraries or header files
are available on the local system.
This section describes how to use
this <span class="application">SCons</span> feature.
</p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
This chapter is still under development,
so not everything is explained as well as it should be.
See the <span class="application">SCons</span> man page for additional information.
</p></div><div class="section" title="23.1.<2E>Configure Contexts"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idm4284"></a>23.1.<2E><code class="literal">Configure Contexts</code></h2></div></div></div><p>
The basic framework for multi-platform build configuration
in <span class="application">SCons</span> is to attach a <code class="literal">configure context</code> to a
construction environment by calling the <code class="function">Configure</code> function,
perform a number of checks for
libraries, functions, header files, etc.,
and to then call the configure context's <code class="function">Finish</code> method
to finish off the configuration:
</p><pre class="programlisting">
env = Environment()
conf = Configure(env)
# Checks for libraries, header files, etc. go here!
env = conf.Finish()
</pre><p>
<span class="application">SCons</span> provides a number of basic checks,
as well as a mechanism for adding your own custom checks.
</p><p>
Note that <span class="application">SCons</span> uses its own dependency
mechanism to determine when a check
needs to be run--that is,
<span class="application">SCons</span> does not run the checks
every time it is invoked,
but caches the values returned by previous checks
and uses the cached values unless something has changed.
This saves a tremendous amount
of developer time while working on
cross-platform build issues.
</p><p>
The next sections describe
the basic checks that <span class="application">SCons</span> supports,
as well as how to add your own custom checks.
</p></div><div class="section" title="23.2.<2E>Checking for the Existence of Header Files"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idm4300"></a>23.2.<2E>Checking for the Existence of Header Files</h2></div></div></div><p>
Testing the existence of a header file
requires knowing what language the header file is.
A configure context has a <code class="function">CheckCHeader</code> method
that checks for the existence of a C header file:
</p><pre class="programlisting">
env = Environment()
conf = Configure(env)
if not conf.CheckCHeader('math.h'):
print 'Math.h must be installed!'
Exit(1)
if conf.CheckCHeader('foo.h'):
conf.env.Append('-DHAS_FOO_H')
env = conf.Finish()
</pre><p>
Note that you can choose to terminate
the build if a given header file doesn't exist,
or you can modify the construction environment
based on the existence of a header file.
</p><p>
If you need to check for the existence
a C++ header file,
use the <code class="function">CheckCXXHeader</code> method:
</p><pre class="programlisting">
env = Environment()
conf = Configure(env)
if not conf.CheckCXXHeader('vector.h'):
print 'vector.h must be installed!'
Exit(1)
env = conf.Finish()
</pre></div><div class="section" title="23.3.<2E>Checking for the Availability of a Function"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idm4309"></a>23.3.<2E>Checking for the Availability of a Function</h2></div></div></div><p>
Check for the availability of a specific function
using the <code class="function">CheckFunc</code> method:
</p><pre class="programlisting">
env = Environment()
conf = Configure(env)
if not conf.CheckFunc('strcpy'):
print 'Did not find strcpy(), using local version'
conf.env.Append(CPPDEFINES = '-Dstrcpy=my_local_strcpy')
env = conf.Finish()
</pre></div><div class="section" title="23.4.<2E>Checking for the Availability of a Library"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idm4314"></a>23.4.<2E>Checking for the Availability of a Library</h2></div></div></div><p>
Check for the availability of a library
using the <code class="function">CheckLib</code> method.
You only specify the basename of the library,
you don't need to add a <code class="literal">lib</code>
prefix or a <code class="literal">.a</code> or <code class="literal">.lib</code> suffix:
</p><pre class="programlisting">
env = Environment()
conf = Configure(env)
if not conf.CheckLib('m'):
print 'Did not find libm.a or m.lib, exiting!'
Exit(1)
env = conf.Finish()
</pre><p>
Because the ability to use a library successfully
often depends on having access to a header file
that describes the library's interface,
you can check for a library
<span class="emphasis"><em>and</em></span> a header file
at the same time by using the
<code class="function">CheckLibWithHeader</code> method:
</p><pre class="programlisting">
env = Environment()
conf = Configure(env)
if not conf.CheckLibWithHeader('m', 'math.h', 'c'):
print 'Did not find libm.a or m.lib, exiting!'
Exit(1)
env = conf.Finish()
</pre><p>
This is essentially shorthand for
separate calls to the <code class="function">CheckHeader</code> and <code class="function">CheckLib</code>
functions.
</p></div><div class="section" title="23.5.<2E>Checking for the Availability of a typedef"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idm4329"></a>23.5.<2E>Checking for the Availability of a <code class="literal">typedef</code></h2></div></div></div><p>
Check for the availability of a <code class="literal">typedef</code>
by using the <code class="function">CheckType</code> method:
</p><pre class="programlisting">
env = Environment()
conf = Configure(env)
if not conf.CheckType('off_t'):
print 'Did not find off_t typedef, assuming int'
conf.env.Append(CCFLAGS = '-Doff_t=int')
env = conf.Finish()
</pre><p>
You can also add a string that will be
placed at the beginning of the test file
that will be used to check for the <code class="literal">typedef</code>.
This provide a way to specify
files that must be included to find the <code class="literal">typedef</code>:
</p><pre class="programlisting">
env = Environment()
conf = Configure(env)
if not conf.CheckType('off_t', '#include &lt;sys/types.h&gt;\n'):
print 'Did not find off_t typedef, assuming int'
conf.env.Append(CCFLAGS = '-Doff_t=int')
env = conf.Finish()
</pre></div><div class="section" title="23.6.<2E>Checking the size of a datatype"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idm4340"></a>23.6.<2E>Checking the size of a datatype</h2></div></div></div><p>
Check the size of a datatype by using the <code class="function">CheckTypeSize</code> method:
</p><pre class="programlisting">
env = Environment()
conf = Configure(env)
int_size = conf.CheckTypeSize('unsigned int')
print 'sizeof unsigned int is', int_size
env = conf.Finish()
</pre><pre class="screen">
% <strong class="userinput"><code>scons -Q</code></strong>
sizeof unsigned int is 4
scons: `.' is up to date.
</pre></div><div class="section" title="23.7.<2E>Checking for the Presence of a program"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idm4347"></a>23.7.<2E>Checking for the Presence of a program</h2></div></div></div><p>
Check for the presence of a program
by using the <code class="function">CheckProg</code> method:
</p><pre class="programlisting">
env = Environment()
conf = Configure(env)
if not conf.CheckProg('foobar'):
print 'Unable to find the program foobar on the system'
Exit(1)
env = conf.Finish()
</pre></div><div class="section" title="23.8.<2E>Adding Your Own Custom Checks"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idm4352"></a>23.8.<2E>Adding Your Own Custom Checks</h2></div></div></div><p>
A custom check is a Python function
that checks for a certain condition to exist
on the running system,
usually using methods that <span class="application">SCons</span>
supplies to take care of the details
of checking whether a compilation succeeds,
a link succeeds,
a program is runnable,
etc.
A simple custom check for the existence of
a specific library might look as follows:
</p><pre class="programlisting">
mylib_test_source_file = """
#include &lt;mylib.h&gt;
int main(int argc, char **argv)
{
MyLibrary mylib(argc, argv);
return 0;
}
"""
def CheckMyLibrary(context):
context.Message('Checking for MyLibrary...')
result = context.TryLink(mylib_test_source_file, '.c')
context.Result(result)
return result
</pre><p>
The <code class="function">Message</code> and <code class="function">Result</code> methods
should typically begin and end a custom check to
let the user know what's going on:
the <code class="function">Message</code> call prints the
specified message (with no trailing newline)
and the <code class="function">Result</code> call prints
<code class="literal">yes</code> if the check succeeds and
<code class="literal">no</code> if it doesn't.
The <code class="function">TryLink</code> method
actually tests for whether the
specified program text
will successfully link.
</p><p>
(Note that a custom check can modify
its check based on any arguments you
choose to pass it,
or by using or modifying the configure context environment
in the <code class="literal">context.env</code> attribute.)
</p><p>
This custom check function is
then attached to the <code class="literal">configure context</code>
by passing a dictionary
to the <code class="function">Configure</code> call
that maps a name of the check
to the underlying function:
</p><pre class="programlisting">
env = Environment()
conf = Configure(env, custom_tests = {'CheckMyLibrary' : CheckMyLibrary})
</pre><p>
You'll typically want to make
the check and the function name the same,
as we've done here,
to avoid potential confusion.
</p><p>
We can then put these pieces together
and actually call the <code class="literal">CheckMyLibrary</code> check
as follows:
</p><pre class="programlisting">
mylib_test_source_file = """
#include &lt;mylib.h&gt;
int main(int argc, char **argv)
{
MyLibrary mylib(argc, argv);
return 0;
}
"""
def CheckMyLibrary(context):
context.Message('Checking for MyLibrary... ')
result = context.TryLink(mylib_test_source_file, '.c')
context.Result(result)
return result
env = Environment()
conf = Configure(env, custom_tests = {'CheckMyLibrary' : CheckMyLibrary})
if not conf.CheckMyLibrary():
print 'MyLibrary is not installed!'
Exit(1)
env = conf.Finish()
# We would then add actual calls like Program() to build
# something using the "env" construction environment.
</pre><p>
If MyLibrary is not installed on the system,
the output will look like:
</p><pre class="screen">
% <strong class="userinput"><code>scons</code></strong>
scons: Reading SConscript file ...
Checking for MyLibrary... no
MyLibrary is not installed!
</pre><p>
If MyLibrary is installed,
the output will look like:
</p><pre class="screen">
% <strong class="userinput"><code>scons</code></strong>
scons: Reading SConscript file ...
Checking for MyLibrary... yes
scons: done reading SConscript
scons: Building targets ...
.
.
.
</pre></div><div class="section" title="23.9.<2E>Not Configuring When Cleaning Targets"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idm4381"></a>23.9.<2E>Not Configuring When Cleaning Targets</h2></div></div></div><p>
Using multi-platform configuration
as described in the previous sections
will run the configuration commands
even when invoking
<strong class="userinput"><code>scons -c</code></strong>
to clean targets:
</p><pre class="screen">
% <strong class="userinput"><code>scons -Q -c</code></strong>
Checking for MyLibrary... yes
Removed foo.o
Removed foo
</pre><p>
Although running the platform checks
when removing targets doesn't hurt anything,
it's usually unnecessary.
You can avoid this by using the
<code class="function">GetOption</code> method to
check whether the <code class="option">-c</code> (clean)
option has been invoked on the command line:
</p><pre class="programlisting">
env = Environment()
if not env.GetOption('clean'):
conf = Configure(env, custom_tests = {'CheckMyLibrary' : CheckMyLibrary})
if not conf.CheckMyLibrary():
print 'MyLibrary is not installed!'
Exit(1)
env = conf.Finish()
</pre><pre class="screen">
% <strong class="userinput"><code>scons -Q -c</code></strong>
Removed foo.o
Removed foo
</pre></div></div><div class="chapter" title="Chapter<65>24.<2E>Caching Built Files"><div class="titlepage"><div><div><h2 class="title"><a name="chap-caching"></a>Chapter<EFBFBD>24.<2E>Caching Built Files</h2></div></div></div><p>
On multi-developer software projects,
you can sometimes speed up every developer's builds a lot by
allowing them to share the derived files that they build.
<span class="application">SCons</span> makes this easy, as well as reliable.
</p><div class="section" title="24.1.<2E>Specifying the Shared Cache Directory"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idm4397"></a>24.1.<2E>Specifying the Shared Cache Directory</h2></div></div></div><p>
To enable sharing of derived files,
use the <code class="function">CacheDir</code> function
in any <code class="filename">SConscript</code> file:
</p><pre class="programlisting">
CacheDir('/usr/local/build_cache')
</pre><p>
Note that the directory you specify must already exist
and be readable and writable by all developers
who will be sharing derived files.
It should also be in some central location
that all builds will be able to access.
In environments where developers are using separate systems
(like individual workstations) for builds,
this directory would typically be
on a shared or NFS-mounted file system.
</p><p>
Here's what happens:
When a build has a <code class="function">CacheDir</code> specified,
every time a file is built,
it is stored in the shared cache directory
along with its MD5 build signature.
<sup>[<a name="idm4406" href="#ftn.idm4406" class="footnote">5</a>]</sup>
On subsequent builds,
before an action is invoked to build a file,
<span class="application">SCons</span> will check the shared cache directory
to see if a file with the exact same build
signature already exists.
If so, the derived file will not be built locally,
but will be copied into the local build directory
from the shared cache directory,
like so:
</p><pre class="screen">% <strong class="userinput"><code>scons -Q</code></strong>
cc -o hello.o -c hello.c
cc -o hello hello.o
% <strong class="userinput"><code>scons -Q -c</code></strong>
Removed hello.o
Removed hello
% <strong class="userinput"><code>scons -Q</code></strong>
Retrieved `hello.o' from cache
Retrieved `hello' from cache
</pre><p>
Note that the <code class="function">CacheDir</code> feature still calculates
MD5 build sigantures for the shared cache file names
even if you configure <span class="application">SCons</span> to use timestamps
to decide if files are up to date.
(See the <a class="xref" href="#chap-depends" title="Chapter<65>6.<2E>Dependencies">Chapter<EFBFBD>6, <i>Dependencies</i></a>
chapter for information about the <code class="function">Decider</code> function.)
Consequently, using <code class="function">CacheDir</code> may reduce or eliminate any
potential performance improvements
from using timestamps for up-to-date decisions.
</p></div><div class="section" title="24.2.<2E>Keeping Build Output Consistent"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idm4419"></a>24.2.<2E>Keeping Build Output Consistent</h2></div></div></div><p>
One potential drawback to using a shared cache
is that the output printed by <span class="application">SCons</span>
can be inconsistent from invocation to invocation,
because any given file may be rebuilt one time
and retrieved from the shared cache the next time.
This can make analyzing build output more difficult,
especially for automated scripts that
expect consistent output each time.
</p><p>
If, however, you use the <code class="literal">--cache-show</code> option,
<span class="application">SCons</span> will print the command line that it
<span class="emphasis"><em>would</em></span> have executed
to build the file,
even when it is retrieving the file from the shared cache.
This makes the build output consistent
every time the build is run:
</p><pre class="screen">% <strong class="userinput"><code>scons -Q</code></strong>
cc -o hello.o -c hello.c
cc -o hello hello.o
% <strong class="userinput"><code>scons -Q -c</code></strong>
Removed hello.o
Removed hello
% <strong class="userinput"><code>scons -Q --cache-show</code></strong>
cc -o hello.o -c hello.c
cc -o hello hello.o
</pre><p>
The trade-off, of course, is that you no longer
know whether or not <span class="application">SCons</span>
has retrieved a derived file from cache
or has rebuilt it locally.
</p></div><div class="section" title="24.3.<2E>Not Using the Shared Cache for Specific Files"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idm4433"></a>24.3.<2E>Not Using the Shared Cache for Specific Files</h2></div></div></div><p>
You may want to disable caching for certain
specific files in your configuration.
For example, if you only want to put
executable files in a central cache,
but not the intermediate object files,
you can use the <code class="function">NoCache</code>
function to specify that the
object files should not be cached:
</p><pre class="programlisting">
env = Environment()
obj = env.Object('hello.c')
env.Program('hello.c')
CacheDir('cache')
NoCache('hello.o')
</pre><p>
Then when you run <code class="filename">scons</code> after cleaning
the built targets,
it will recompile the object file locally
(since it doesn't exist in the shared cache directory),
but still realize that the shared cache directory
contains an up-to-date executable program
that can be retrieved instead of re-linking:
</p><pre class="screen">
% <strong class="userinput"><code>scons -Q</code></strong>
cc -o hello.o -c hello.c
cc -o hello hello.o
% <strong class="userinput"><code>scons -Q -c</code></strong>
Removed hello.o
Removed hello
% <strong class="userinput"><code>scons -Q</code></strong>
cc -o hello.o -c hello.c
Retrieved `hello' from cache
</pre></div><div class="section" title="24.4.<2E>Disabling the Shared Cache"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idm4444"></a>24.4.<2E>Disabling the Shared Cache</h2></div></div></div><p>
Retrieving an already-built file
from the shared cache
is usually a significant time-savings
over rebuilding the file,
but how much of a savings
(or even whether it saves time at all)
can depend a great deal on your
system or network configuration.
For example, retrieving cached files
from a busy server over a busy network
might end up being slower than
rebuilding the files locally.
</p><p>
In these cases, you can specify
the <code class="literal">--cache-disable</code>
command-line option to tell <span class="application">SCons</span>
to not retrieve already-built files from the
shared cache directory:
</p><pre class="screen">% <strong class="userinput"><code>scons -Q</code></strong>
cc -o hello.o -c hello.c
cc -o hello hello.o
% <strong class="userinput"><code>scons -Q -c</code></strong>
Removed hello.o
Removed hello
% <strong class="userinput"><code>scons -Q</code></strong>
Retrieved `hello.o' from cache
Retrieved `hello' from cache
% <strong class="userinput"><code>scons -Q -c</code></strong>
Removed hello.o
Removed hello
% <strong class="userinput"><code>scons -Q --cache-disable</code></strong>
cc -o hello.o -c hello.c
cc -o hello hello.o
</pre></div><div class="section" title="24.5.<2E>Populating a Shared Cache With Already-Built Files"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idm4456"></a>24.5.<2E>Populating a Shared Cache With Already-Built Files</h2></div></div></div><p>
Sometimes, you may have one or more derived files
already built in your local build tree
that you wish to make available to other people doing builds.
For example, you may find it more effective to perform
integration builds with the cache disabled
(per the previous section)
and only populate the shared cache directory
with the built files after the integration build
has completed successfully.
This way, the cache will only get filled up
with derived files that are part of a complete, successful build
not with files that might be later overwritten
while you debug integration problems.
</p><p>
In this case, you can use the
the <code class="literal">--cache-force</code> option
to tell <span class="application">SCons</span> to put all derived files in the cache,
even if the files already exist in your local tree
from having been built by a previous invocation:
</p><pre class="screen">% <strong class="userinput"><code>scons -Q --cache-disable</code></strong>
cc -o hello.o -c hello.c
cc -o hello hello.o
% <strong class="userinput"><code>scons -Q -c</code></strong>
Removed hello.o
Removed hello
% <strong class="userinput"><code>scons -Q --cache-disable</code></strong>
cc -o hello.o -c hello.c
cc -o hello hello.o
% <strong class="userinput"><code>scons -Q --cache-force</code></strong>
scons: `.' is up to date.
% <strong class="userinput"><code>scons -Q</code></strong>
scons: `.' is up to date.
</pre><p>
Notice how the above sample run
demonstrates that the <code class="literal">--cache-disable</code>
option avoids putting the built
<code class="filename">hello.o</code>
and
<code class="filename">hello</code> files in the cache,
but after using the <code class="literal">--cache-force</code> option,
the files have been put in the cache
for the next invocation to retrieve.
</p></div><div class="section" title="24.6.<2E>Minimizing Cache Contention: the --random Option"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idm4473"></a>24.6.<2E>Minimizing Cache Contention: the <code class="literal">--random</code> Option</h2></div></div></div><p>
If you allow multiple builds to update the
shared cache directory simultaneously,
two builds that occur at the same time
can sometimes start "racing"
with one another to build the same files
in the same order.
If, for example,
you are linking multiple files into an executable program:
</p><pre class="programlisting">
Program('prog',
['f1.c', 'f2.c', 'f3.c', 'f4.c', 'f5.c'])
</pre><p>
<span class="application">SCons</span> will normally build the input object files
on which the program depends in their normal, sorted order:
</p><pre class="screen">% <strong class="userinput"><code>scons -Q</code></strong>
cc -o f5.o -c f5.c
cc -o f3.o -c f3.c
cc -o f2.o -c f2.c
cc -o f1.o -c f1.c
cc -o f4.o -c f4.c
cc -o prog f1.o f2.o f3.o f4.o f5.o
</pre><p>
But if two such builds take place simultaneously,
they may each look in the cache at nearly the same
time and both decide that <code class="filename">f1.o</code>
must be rebuilt and pushed into the shared cache directory,
then both decide that <code class="filename">f2.o</code>
must be rebuilt (and pushed into the shared cache directory),
then both decide that <code class="filename">f3.o</code>
must be rebuilt...
This won't cause any actual build problems--both
builds will succeed,
generate correct output files,
and populate the cache--but
it does represent wasted effort.
</p><p>
To alleviate such contention for the cache,
you can use the <code class="literal">--random</code> command-line option
to tell <span class="application">SCons</span> to build dependencies
in a random order:
</p><pre class="screen">
% <strong class="userinput"><code>scons -Q --random</code></strong>
cc -o f3.o -c f3.c
cc -o f1.o -c f1.c
cc -o f5.o -c f5.c
cc -o f2.o -c f2.c
cc -o f4.o -c f4.c
cc -o prog f1.o f2.o f3.o f4.o f5.o
</pre><p>
Multiple builds using the <code class="literal">--random</code> option
will usually build their dependencies in different,
random orders,
which minimizes the chances for a lot of
contention for same-named files
in the shared cache directory.
Multiple simultaneous builds might still race to try to build
the same target file on occasion,
but long sequences of inefficient contention
should be rare.
</p><p>
Note, of course,
the <code class="literal">--random</code> option
will cause the output that <span class="application">SCons</span> prints
to be inconsistent from invocation to invocation,
which may be an issue when
trying to compare output from different build runs.
</p><p>
If you want to make sure dependencies will be built
in a random order without having to specify
the <code class="literal">--random</code> on very command line,
you can use the <code class="function">SetOption</code> function to
set the <code class="literal">random</code> option
within any <code class="filename">SConscript</code> file:
</p><pre class="programlisting">
SetOption('random', 1)
Program('prog',
['f1.c', 'f2.c', 'f3.c', 'f4.c', 'f5.c'])
</pre></div><div class="footnotes"><br><hr width="100" align="left"><div class="footnote"><p><sup>[<a id="ftn.idm4406" href="#idm4406" class="para">5</a>] </sup>
Actually, the MD5 signature is used as the name of the file
in the shared cache directory in which the contents are stored.
</p></div></div></div><div class="chapter" title="Chapter<65>25.<2E>Alias Targets"><div class="titlepage"><div><div><h2 class="title"><a name="chap-alias"></a>Chapter<EFBFBD>25.<2E>Alias Targets</h2></div></div></div><p>
We've already seen how you can use the <code class="function">Alias</code>
function to create a target named <code class="literal">install</code>:
</p><pre class="programlisting">
env = Environment()
hello = env.Program('hello.c')
env.Install('/usr/bin', hello)
env.Alias('install', '/usr/bin')
</pre><p>
You can then use this alias on the command line
to tell <span class="application">SCons</span> more naturally that you want to install files:
</p><pre class="screen">% <strong class="userinput"><code>scons -Q install</code></strong>
cc -o hello.o -c hello.c
cc -o hello hello.o
Install file: "hello" as "/usr/bin/hello"
</pre><p>
Like other <code class="classname">Builder</code> methods, though,
the <code class="function">Alias</code> method returns an object
representing the alias being built.
You can then use this object as input to anothother <code class="classname">Builder</code>.
This is especially useful if you use such an object
as input to another call to the <code class="function">Alias</code> <code class="classname">Builder</code>,
allowing you to create a hierarchy
of nested aliases:
</p><pre class="programlisting">
env = Environment()
p = env.Program('foo.c')
l = env.Library('bar.c')
env.Install('/usr/bin', p)
env.Install('/usr/lib', l)
ib = env.Alias('install-bin', '/usr/bin')
il = env.Alias('install-lib', '/usr/lib')
env.Alias('install', [ib, il])
</pre><p>
This example defines separate <code class="literal">install</code>,
<code class="literal">install-bin</code>,
and <code class="literal">install-lib</code> aliases,
allowing you finer control over what gets installed:
</p><pre class="screen">% <strong class="userinput"><code>scons -Q install-bin</code></strong>
cc -o foo.o -c foo.c
cc -o foo foo.o
Install file: "foo" as "/usr/bin/foo"
% <strong class="userinput"><code>scons -Q install-lib</code></strong>
cc -o bar.o -c bar.c
ar rc libbar.a bar.o
ranlib libbar.a
Install file: "libbar.a" as "/usr/lib/libbar.a"
% <strong class="userinput"><code>scons -Q -c /</code></strong>
Removed foo.o
Removed foo
Removed /usr/bin/foo
Removed bar.o
Removed libbar.a
Removed /usr/lib/libbar.a
% <strong class="userinput"><code>scons -Q install</code></strong>
cc -o foo.o -c foo.c
cc -o foo foo.o
Install file: "foo" as "/usr/bin/foo"
cc -o bar.o -c bar.c
ar rc libbar.a bar.o
ranlib libbar.a
Install file: "libbar.a" as "/usr/lib/libbar.a"
</pre></div><div class="chapter" title="Chapter<65>26.<2E>Java Builds"><div class="titlepage"><div><div><h2 class="title"><a name="chap-java"></a>Chapter<EFBFBD>26.<2E>Java Builds</h2></div></div></div><p>
So far, we've been using examples of
building C and C++ programs
to demonstrate the features of <span class="application">SCons</span>.
<span class="application">SCons</span> also supports building Java programs,
but Java builds are handled slightly differently,
which reflects the ways in which
the Java compiler and tools
build programs differently than
other languages' tool chains.
</p><div class="section" title="26.1.<2E>Building Java Class Files: the Java Builder"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idm4533"></a>26.1.<2E>Building Java Class Files: the <code class="function">Java</code> Builder</h2></div></div></div><p>
The basic activity when programming in Java,
of course, is to take one or more <code class="filename">.java</code> files
containing Java source code
and to call the Java compiler
to turn them into one or more
<code class="filename">.class</code> files.
In <span class="application">SCons</span>, you do this
by giving the <a class="link" href="#b-Java"><code class="function">Java</code></a> Builder
a target directory in which
to put the <code class="filename">.class</code> files,
and a source directory that contains
the <code class="filename">.java</code> files:
</p><pre class="programlisting">
Java('classes', 'src')
</pre><p>
If the <code class="filename">src</code> directory contains
three <code class="filename">.java</code> source files,
then running <span class="application">SCons</span> might look like this:
</p><pre class="screen">% <strong class="userinput"><code>scons -Q</code></strong>
javac -d classes -sourcepath src src/Example1.java src/Example2.java src/Example3.java
</pre><p>
<span class="application">SCons</span> will actually search the <code class="filename">src</code>
directory tree for all of the <code class="filename">.java</code> files.
The Java compiler will then create the
necessary class files in the <code class="filename">classes</code> subdirectory,
based on the class names found in the <code class="filename">.java</code> files.
</p></div><div class="section" title="26.2.<2E>How SCons Handles Java Dependencies"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idm4557"></a>26.2.<2E>How <span class="application">SCons</span> Handles Java Dependencies</h2></div></div></div><p>
In addition to searching the source directory for
<code class="filename">.java</code> files,
<span class="application">SCons</span> actually runs the <code class="filename">.java</code> files
through a stripped-down Java parser that figures out
what classes are defined.
In other words, <span class="application">SCons</span> knows,
without you having to tell it,
what <code class="filename">.class</code> files
will be produced by the <span class="application">javac</span> call.
So our one-liner example from the preceding section:
</p><pre class="programlisting">
Java('classes', 'src')
</pre><p>
Will not only tell you reliably
that the <code class="filename">.class</code> files
in the <code class="filename">classes</code> subdirectory
are up-to-date:
</p><pre class="screen">% <strong class="userinput"><code>scons -Q</code></strong>
javac -d classes -sourcepath src src/Example1.java src/Example2.java src/Example3.java
% <strong class="userinput"><code>scons -Q classes</code></strong>
scons: `classes' is up to date.
</pre><p>
But it will also remove all of the generated
<code class="filename">.class</code> files,
even for inner classes,
without you having to specify them manually.
For example, if our
<code class="filename">Example1.java</code>
and
<code class="filename">Example3.java</code>
files both define additional classes,
and the class defined in <code class="filename">Example2.java</code>
has an inner class,
running <strong class="userinput"><code>scons -c</code></strong>
will clean up all of those <code class="filename">.class</code> files
as well:
</p><pre class="screen">% <strong class="userinput"><code>scons -Q</code></strong>
javac -d classes -sourcepath src src/Example1.java src/Example2.java src/Example3.java
% <strong class="userinput"><code>scons -Q -c classes</code></strong>
Removed classes/Example1.class
Removed classes/AdditionalClass1.class
Removed classes/Example2$Inner2.class
Removed classes/Example2.class
Removed classes/Example3.class
Removed classes/AdditionalClass3.class
</pre><p>
To ensure correct handling of <code class="filename">.class</code>
dependencies in all cases, you need to tell <span class="application">SCons</span> which Java
version is being used. This is needed because Java 1.5 changed
the <code class="filename">.class</code> file names for nested anonymous
inner classes. Use the <code class="varname">JAVAVERSION</code> construction
variable to specify the version in use. With Java 1.6, the
one-liner example can then be defined like this:
</p><pre class="programlisting">
Java('classes', 'src', JAVAVERSION='1.6')
</pre><p>
See <code class="varname">JAVAVERSION</code> in the man page for more information.
</p></div><div class="section" title="26.3.<2E>Building Java Archive (.jar) Files: the Jar Builder"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idm4592"></a>26.3.<2E>Building Java Archive (<code class="filename">.jar</code>) Files: the <code class="function">Jar</code> Builder</h2></div></div></div><p>
After building the class files,
it's common to collect them into
a Java archive (<code class="filename">.jar</code>) file,
which you do by calling the <a class="link" href="#b-Jar"><code class="function">Jar</code></a> Builder method.
If you want to just collect all of the
class files within a subdirectory,
you can just specify that subdirectory
as the <code class="function">Jar</code> source:
</p><pre class="programlisting">
Java(target = 'classes', source = 'src')
Jar(target = 'test.jar', source = 'classes')
</pre><p>
<span class="application">SCons</span> will then pass that directory
to the <span class="application">jar</span> command,
which will collect all of the underlying
<code class="filename">.class</code> files:
</p><pre class="screen">% <strong class="userinput"><code>scons -Q</code></strong>
javac -d classes -sourcepath src src/Example1.java src/Example2.java src/Example3.java
jar cf test.jar classes
</pre><p>
If you want to keep all of the
<code class="filename">.class</code> files
for multiple programs in one location,
and only archive some of them in
each <code class="filename">.jar</code> file,
you can pass the <code class="function">Jar</code> builder a
list of files as its source.
It's extremely simple to create multiple
<code class="filename">.jar</code> files this way,
using the lists of target class files created
by calls to the <a class="link" href="#b-Java"><code class="function">Java</code></a> builder
as sources to the various <code class="function">Jar</code> calls:
</p><pre class="programlisting">
prog1_class_files = Java(target = 'classes', source = 'prog1')
prog2_class_files = Java(target = 'classes', source = 'prog2')
Jar(target = 'prog1.jar', source = prog1_class_files)
Jar(target = 'prog2.jar', source = prog2_class_files)
</pre><p>
This will then create
<code class="filename">prog1.jar</code>
and <code class="filename">prog2.jar</code>
next to the subdirectories
that contain their <code class="filename">.java</code> files:
</p><pre class="screen">% <strong class="userinput"><code>scons -Q</code></strong>
javac -d classes -sourcepath prog1 prog1/Example1.java prog1/Example2.java
javac -d classes -sourcepath prog2 prog2/Example3.java prog2/Example4.java
jar cf prog1.jar -C classes Example1.class -C classes Example2.class
jar cf prog2.jar -C classes Example3.class -C classes Example4.class
</pre></div><div class="section" title="26.4.<2E>Building C Header and Stub Files: the JavaH Builder"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idm4623"></a>26.4.<2E>Building C Header and Stub Files: the <code class="function">JavaH</code> Builder</h2></div></div></div><p>
You can generate C header and source files
for implementing native methods,
by using the <a class="link" href="#b-JavaH"><code class="function">JavaH</code></a> Builder.
There are several ways of using the <code class="function">JavaH</code> Builder.
One typical invocation might look like:
</p><pre class="programlisting">
classes = Java(target = 'classes', source = 'src/pkg/sub')
JavaH(target = 'native', source = classes)
</pre><p>
The source is a list of class files generated by the
call to the <a class="link" href="#b-Java"><code class="function">Java</code></a> Builder,
and the target is the output directory in
which we want the C header files placed.
The target
gets converted into the <code class="option">-d</code>
when <span class="application">SCons</span> runs <span class="application">javah</span>:
</p><pre class="screen">% <strong class="userinput"><code>scons -Q</code></strong>
javac -d classes -sourcepath src/pkg/sub src/pkg/sub/Example1.java src/pkg/sub/Example2.java src/pkg/sub/Example3.java
javah -d native -classpath classes pkg.sub.Example1 pkg.sub.Example2 pkg.sub.Example3
</pre><p>
In this case,
the call to <span class="application">javah</span>
will generate the header files
<code class="filename">native/pkg_sub_Example1.h</code>,
<code class="filename">native/pkg_sub_Example2.h</code>
and
<code class="filename">native/pkg_sub_Example3.h</code>.
Notice that <span class="application">SCons</span> remembered that the class
files were generated with a target directory of
<code class="filename">classes</code>,
and that it then specified that target directory
as the <code class="option">-classpath</code> option
to the call to <span class="application">javah</span>.
</p><p>
Although it's more convenient to use
the list of class files returned by
the <code class="function">Java</code> Builder
as the source of a call to the <code class="function">JavaH</code> Builder,
you <span class="emphasis"><em>can</em></span>
specify the list of class files
by hand, if you prefer.
If you do,
you need to set the
<a class="link" href="#cv-JAVACLASSDIR"><code class="envar">$JAVACLASSDIR</code></a> construction variable
when calling <code class="function">JavaH</code>:
</p><pre class="programlisting">
Java(target = 'classes', source = 'src/pkg/sub')
class_file_list = ['classes/pkg/sub/Example1.class',
'classes/pkg/sub/Example2.class',
'classes/pkg/sub/Example3.class']
JavaH(target = 'native', source = class_file_list, JAVACLASSDIR = 'classes')
</pre><p>
The <code class="envar">$JAVACLASSDIR</code> value then
gets converted into the <code class="option">-classpath</code>
when <span class="application">SCons</span> runs <span class="application">javah</span>:
</p><pre class="screen">% <strong class="userinput"><code>scons -Q</code></strong>
javac -d classes -sourcepath src/pkg/sub src/pkg/sub/Example1.java src/pkg/sub/Example2.java src/pkg/sub/Example3.java
javah -d native -classpath classes pkg.sub.Example1 pkg.sub.Example2 pkg.sub.Example3
</pre><p>
Lastly, if you don't want a separate header file
generated for each source file,
you can specify an explicit File Node
as the target of the <code class="function">JavaH</code> Builder:
</p><pre class="programlisting">
classes = Java(target = 'classes', source = 'src/pkg/sub')
JavaH(target = File('native.h'), source = classes)
</pre><p>
Because <span class="application">SCons</span> assumes by default
that the target of the <code class="function">JavaH</code> builder is a directory,
you need to use the <code class="function">File</code> function
to make sure that <span class="application">SCons</span> doesn't
create a directory named <code class="filename">native.h</code>.
When a file is used, though,
<span class="application">SCons</span> correctly converts the file name
into the <span class="application">javah</span> <code class="option">-o</code> option:
</p><pre class="screen">% <strong class="userinput"><code>scons -Q</code></strong>
javac -d classes -sourcepath src/pkg/sub src/pkg/sub/Example1.java src/pkg/sub/Example2.java src/pkg/sub/Example3.java
javah -o native.h -classpath classes pkg.sub.Example1 pkg.sub.Example2 pkg.sub.Example3
</pre></div><div class="section" title="26.5.<2E>Building RMI Stub and Skeleton Class Files: the RMIC Builder"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idm4677"></a>26.5.<2E>Building RMI Stub and Skeleton Class Files: the <code class="function">RMIC</code> Builder</h2></div></div></div><p>
You can generate Remote Method Invocation stubs
by using the <a class="link" href="#b-RMIC"><code class="function">RMIC</code></a> Builder.
The source is a list of directories,
typically returned by a call to the <a class="link" href="#b-Java"><code class="function">Java</code></a> Builder,
and the target is an output directory
where the <code class="filename">_Stub.class</code>
and <code class="filename">_Skel.class</code> files will
be placed:
</p><pre class="programlisting">
classes = Java(target = 'classes', source = 'src/pkg/sub')
RMIC(target = 'outdir', source = classes)
</pre><p>
As it did with the <a class="link" href="#b-JavaH"><code class="function">JavaH</code></a> Builder,
<span class="application">SCons</span> remembers the class directory
and passes it as the <code class="option">-classpath</code> option
to <span class="application">rmic</span>:
</p><pre class="screen">% <strong class="userinput"><code>scons -Q</code></strong>
javac -d classes -sourcepath src/pkg/sub src/pkg/sub/Example1.java src/pkg/sub/Example2.java
rmic -d outdir -classpath classes pkg.sub.Example1 pkg.sub.Example2
</pre><p>
This example would generate the files
<code class="filename">outdir/pkg/sub/Example1_Skel.class</code>,
<code class="filename">outdir/pkg/sub/Example1_Stub.class</code>,
<code class="filename">outdir/pkg/sub/Example2_Skel.class</code> and
<code class="filename">outdir/pkg/sub/Example2_Stub.class</code>.
</p></div></div><div class="chapter" title="Chapter<65>27.<2E>Miscellaneous Functionality"><div class="titlepage"><div><div><h2 class="title"><a name="chap-misc"></a>Chapter<EFBFBD>27.<2E>Miscellaneous Functionality</h2></div></div></div><p>
<span class="application">SCons</span> supports a lot of additional functionality
that doesn't readily fit into the other chapters.
</p><div class="section" title="27.1.<2E>Verifying the Python Version: the EnsurePythonVersion Function"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idm4705"></a>27.1.<2E>Verifying the Python Version: the <code class="function">EnsurePythonVersion</code> Function</h2></div></div></div><p>
Although the <span class="application">SCons</span> code itself will run
on any 2.x Python version 2.7 or later,
you are perfectly free to make use of
Python syntax and modules from later versions
when writing your <code class="filename">SConscript</code> files
or your own local modules.
If you do this, it's usually helpful to
configure <span class="application">SCons</span> to exit gracefully with an error message
if it's being run with a version of Python
that simply won't work with your code.
This is especially true if you're going to use <span class="application">SCons</span>
to build source code that you plan to distribute publicly,
where you can't be sure of the Python version
that an anonymous remote user might use
to try to build your software.
</p><p>
<span class="application">SCons</span> provides an <code class="function">EnsurePythonVersion</code> function for this.
You simply pass it the major and minor versions
numbers of the version of Python you require:
</p><pre class="programlisting">
EnsurePythonVersion(2, 5)
</pre><p>
And then <span class="application">SCons</span> will exit with the following error
message when a user runs it with an unsupported
earlier version of Python:
</p><pre class="screen">
% <strong class="userinput"><code>scons -Q</code></strong>
Python 2.5 or greater required, but you have Python 2.3.6
</pre></div><div class="section" title="27.2.<2E>Verifying the SCons Version: the EnsureSConsVersion Function"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idm4721"></a>27.2.<2E>Verifying the SCons Version: the <code class="function">EnsureSConsVersion</code> Function</h2></div></div></div><p>
You may, of course, write your <code class="filename">SConscript</code> files
to use features that were only added in
recent versions of <span class="application">SCons</span>.
When you publicly distribute software that is built using <span class="application">SCons</span>,
it's helpful to have <span class="application">SCons</span>
verify the version being used and
exit gracefully with an error message
if the user's version of <span class="application">SCons</span> won't work
with your <code class="filename">SConscript</code> files.
<span class="application">SCons</span> provides an <code class="function">EnsureSConsVersion</code> function
that verifies the version of <span class="application">SCons</span>
in the same
the <code class="function">EnsurePythonVersion</code> function
verifies the version of Python,
by passing in the major and minor versions
numbers of the version of SCons you require:
</p><pre class="programlisting">
EnsureSConsVersion(1, 0)
</pre><p>
And then <span class="application">SCons</span> will exit with the following error
message when a user runs it with an unsupported
earlier version of <span class="application">SCons</span>:
</p><pre class="screen">
% <strong class="userinput"><code>scons -Q</code></strong>
SCons 1.0 or greater required, but you have SCons 0.98.5
</pre></div><div class="section" title="27.3.<2E>Explicitly Terminating SCons While Reading SConscript Files: the Exit Function"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idm4741"></a>27.3.<2E>Explicitly Terminating <span class="application">SCons</span> While Reading <code class="filename">SConscript</code> Files: the <code class="function">Exit</code> Function</h2></div></div></div><p>
<span class="application">SCons</span> supports an <code class="function">Exit</code> function
which can be used to terminate <span class="application">SCons</span>
while reading the <code class="filename">SConscript</code> files,
usually because you've detected a condition
under which it doesn't make sense to proceed:
</p><pre class="programlisting">
if ARGUMENTS.get('FUTURE'):
print("The FUTURE option is not supported yet!")
Exit(2)
env = Environment()
env.Program('hello.c')
</pre><pre class="screen">% <strong class="userinput"><code>scons -Q FUTURE=1</code></strong>
The FUTURE option is not supported yet!
% <strong class="userinput"><code>scons -Q</code></strong>
cc -o hello.o -c hello.c
cc -o hello hello.o
</pre><p>
The <code class="function">Exit</code> function takes as an argument
the (numeric) exit status that you want <span class="application">SCons</span> to exit with.
If you don't specify a value,
the default is to exit with <code class="literal">0</code>,
which indicates successful execution.
</p><p>
Note that the <code class="function">Exit</code> function
is equivalent to calling the Python
<code class="function">sys.exit</code> function
(which the it actually calls),
but because <code class="function">Exit</code> is a <span class="application">SCons</span> function,
you don't have to import the Python
<code class="literal">sys</code> module to use it.
</p></div><div class="section" title="27.4.<2E>Searching for Files: the FindFile Function"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idm4765"></a>27.4.<2E>Searching for Files: the <code class="function">FindFile</code> Function</h2></div></div></div><p>
The <code class="function">FindFile</code> function searches for a file in a list of directories.
If there is only one directory, it can be given as a simple string.
The function returns a File node if a matching file exists,
or None if no file is found.
(See the documentation for the <code class="function">Glob</code> function for an alternative way
of searching for entries in a directory.)
</p><pre class="programlisting">
# one directory
print("%s"%FindFile('missing', '.'))
t = FindFile('exists', '.')
print("%s %s"%(t.__class__, t))
</pre><pre class="screen">% <strong class="userinput"><code>scons -Q</code></strong>
None
&lt;class 'SCons.Node.FS.File'&gt; exists
scons: `.' is up to date.
</pre><pre class="programlisting">
# several directories
includes = [ '.', 'include', 'src/include']
headers = [ 'nonesuch.h', 'config.h', 'private.h', 'dist.h']
for hdr in headers:
print('%-12s: %s'%(hdr, FindFile(hdr, includes)))
</pre><pre class="screen">% <strong class="userinput"><code>scons -Q</code></strong>
nonesuch.h : None
config.h : config.h
private.h : src/include/private.h
dist.h : include/dist.h
scons: `.' is up to date.
</pre><p>
If the file exists in more than one directory,
only the first occurrence is returned.
</p><pre class="programlisting">
print(FindFile('multiple', ['sub1', 'sub2', 'sub3']))
print(FindFile('multiple', ['sub2', 'sub3', 'sub1']))
print(FindFile('multiple', ['sub3', 'sub1', 'sub2']))
</pre><pre class="screen">% <strong class="userinput"><code>scons -Q</code></strong>
sub1/multiple
sub2/multiple
sub3/multiple
scons: `.' is up to date.
</pre><p>
In addition to existing files, <code class="function">FindFile</code> will also find derived files
(that is, non-leaf files) that haven't been built yet.
(Leaf files should already exist, or the build will fail!)
</p><pre class="programlisting">
# Neither file exists, so build will fail
Command('derived', 'leaf', 'cat &gt;$TARGET $SOURCE')
print(FindFile('leaf', '.'))
print(FindFile('derived', '.'))
</pre><pre class="screen">% <strong class="userinput"><code>scons -Q</code></strong>
leaf
derived
cat &gt; derived leaf
</pre><pre class="programlisting">
# Only 'leaf' exists
Command('derived', 'leaf', 'cat &gt;$TARGET $SOURCE')
print(FindFile('leaf', '.'))
print(FindFile('derived', '.'))
</pre><pre class="screen">% <strong class="userinput"><code>scons -Q</code></strong>
leaf
derived
cat &gt; derived leaf
</pre><p>
If a source file exists, <code class="function">FindFile</code> will correctly return the name
in the build directory.
</p><pre class="programlisting">
# Only 'src/leaf' exists
VariantDir('build', 'src')
print(FindFile('leaf', 'build'))
</pre><pre class="screen">% <strong class="userinput"><code>scons -Q</code></strong>
build/leaf
scons: `.' is up to date.
</pre></div><div class="section" title="27.5.<2E>Handling Nested Lists: the Flatten Function"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idm4794"></a>27.5.<2E>Handling Nested Lists: the <code class="function">Flatten</code> Function</h2></div></div></div><p>
<span class="application">SCons</span> supports a <code class="function">Flatten</code> function
which takes an input Python sequence
(list or tuple)
and returns a flattened list
containing just the individual elements of
the sequence.
This can be handy when trying to examine
a list composed of the lists
returned by calls to various Builders.
For example, you might collect
object files built in different ways
into one call to the <code class="function">Program</code> Builder
by just enclosing them in a list, as follows:
</p><pre class="programlisting">
objects = [
Object('prog1.c'),
Object('prog2.c', CCFLAGS='-DFOO'),
]
Program(objects)
</pre><p>
Because the Builder calls in <span class="application">SCons</span>
flatten their input lists,
this works just fine to build the program:
</p><pre class="screen">% <strong class="userinput"><code>scons -Q</code></strong>
cc -o prog1.o -c prog1.c
cc -o prog2.o -c -DFOO prog2.c
cc -o prog1 prog1.o prog2.o
</pre><p>
But if you were debugging your build
and wanted to print the absolute path
of each object file in the
<code class="varname">objects</code> list,
you might try the following simple approach,
trying to print each Node's
<code class="literal">abspath</code>
attribute:
</p><pre class="programlisting">
objects = [
Object('prog1.c'),
Object('prog2.c', CCFLAGS='-DFOO'),
]
Program(objects)
for object_file in objects:
print(object_file.abspath)
</pre><p>
This does not work as expected
because each call to <code class="function">str</code>
is operating an embedded list returned by
each <code class="function">Object</code> call,
not on the underlying Nodes within those lists:
</p><pre class="screen">% <strong class="userinput"><code>scons -Q</code></strong>
AttributeError: 'NodeList' object has no attribute 'abspath':
File "/home/my/project/SConstruct", line 8:
print(object_file.abspath)
</pre><p>
The solution is to use the <code class="function">Flatten</code> function
so that you can pass each Node to
the <code class="function">str</code> separately:
</p><pre class="programlisting">
objects = [
Object('prog1.c'),
Object('prog2.c', CCFLAGS='-DFOO'),
]
Program(objects)
for object_file in Flatten(objects):
print(object_file.abspath)
</pre><pre class="screen">
% <strong class="userinput"><code>scons -Q</code></strong>
/home/me/project/prog1.o
/home/me/project/prog2.o
cc -o prog1.o -c prog1.c
cc -o prog2.o -c -DFOO prog2.c
cc -o prog1 prog1.o prog2.o
</pre></div><div class="section" title="27.6.<2E>Finding the Invocation Directory: the GetLaunchDir Function"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idm4821"></a>27.6.<2E>Finding the Invocation Directory: the <code class="function">GetLaunchDir</code> Function</h2></div></div></div><p>
If you need to find the directory from
which the user invoked the <code class="filename">scons</code> command,
you can use the <code class="function">GetLaunchDir</code> function:
</p><pre class="programlisting">
env = Environment(
LAUNCHDIR = GetLaunchDir(),
)
env.Command('directory_build_info',
'$LAUNCHDIR/build_info'
Copy('$TARGET', '$SOURCE'))
</pre><p>
Because <span class="application">SCons</span> is usually invoked from the top-level
directory in which the <code class="filename">SConstruct</code> file lives,
the Python <code class="function">os.getcwd()</code>
is often equivalent.
However, the <span class="application">SCons</span>
<code class="literal">-u</code>,
<code class="literal">-U</code>
and
<code class="literal">-D</code>
command-line options,
when invoked from a subdirectory,
will cause <span class="application">SCons</span> to change to the directory
in which the <code class="filename">SConstruct</code> file is found.
When those options are used,
<code class="function">GetLaunchDir</code> will still return the path to the
user's invoking subdirectory,
allowing the <code class="filename">SConscript</code> configuration
to still get at configuration (or other) files
from the originating directory.
</p></div><div class="section" title="27.7.<2E>Virtual environments (virtualenvs)"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idm4840"></a>27.7.<2E>Virtual environments (virtualenvs)</h2></div></div></div><p>
Virtualenv is a tool to create isolated Python environments.
A python application (such as SCons) may be executed within
an activated virtualenv. The activation of virtualenv modifies
current environment by defining some virtualenv-specific variables
and modifying search PATH, such that executables installed within
virtualenv's home directory are preferred over the ones installed
outside of it.
</p><p>
Normally, SCons uses hard-coded PATH when searching for external
executables, so it always picks-up executables from these pre-defined
locations. This applies also to python interpreter, which is invoked
by some custom SCons tools or test suites. This means, when running
SCons in a virtualenv, an eventual invocation of python interpreter from
SCons script will most probably jump out of virtualenv and execute
python executable found in hard-coded SCons PATH, not the one which is
executing SCons. Some users may consider this as an inconsistency.
</p><p>
This issue may be overcome by using <code class="literal">--enable-virtualenv</code>
option. The option automatically imports virtualenv-related environment
variables to all created construction environment <code class="literal">env['ENV']</code>,
and modifies SCons PATH appropriately to prefer virtualenv's executables.
Setting environment variable <code class="literal">SCONS_ENABLE_VIRTUALENV=1</code>
will have same effect. If virtualenv support is enabled system-vide
by the environment variable, it may be suppressed with
<code class="literal">--ignore-virtualenv</code> option.
</p><p>
Inside of SConscript, a global function <code class="literal">Virtualenv</code> is
available. It returns a path to virtualenv's home directory, or
<code class="literal">None</code> if SCons is not running from virtualenv. Note,
that this function returns a path even if SCons is run from an
unactivated virtualenv.
</p></div></div><div class="chapter" title="Chapter<65>28.<2E>Troubleshooting"><div class="titlepage"><div><div><h2 class="title"><a name="chap-troubleshooting"></a>Chapter<EFBFBD>28.<2E>Troubleshooting</h2></div></div></div><p>
The experience of configuring any
software build tool to build a large code base
usually, at some point,
involves trying to figure out why
the tool is behaving a certain way,
and how to get it to behave the way you want.
<span class="application">SCons</span> is no different.
This appendix contains a number of
different ways in which you can
get some additional insight into <span class="application">SCons</span>' behavior.
</p><p>
Note that we're always interested in trying to
improve how you can troubleshoot configuration problems.
If you run into a problem that has
you scratching your head,
and which there just doesn't seem to be a good way to debug,
odds are pretty good that someone else will run into
the same problem, too.
If so, please let the SCons development team know
(preferably by filing a bug report
or feature request at our project pages at tigris.org)
so that we can use your feedback
to try to come up with a better way to help you,
and others, get the necessary insight into <span class="application">SCons</span> behavior
to help identify and fix configuration issues.
</p><div class="section" title="28.1.<2E>Why is That Target Being Rebuilt? the --debug=explain Option"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idm4859"></a>28.1.<2E>Why is That Target Being Rebuilt? the <code class="literal">--debug=explain</code> Option</h2></div></div></div><p>
Let's look at a simple example of
a misconfigured build
that causes a target to be rebuilt
every time <span class="application">SCons</span> is run:
</p><pre class="programlisting">
# Intentionally misspell the output file name in the
# command used to create the file:
Command('file.out', 'file.in', 'cp $SOURCE file.oout')
</pre><p>
(Note to Windows users: The POSIX <span class="application">cp</span> command
copies the first file named on the command line
to the second file.
In our example, it copies the <code class="filename">file.in</code> file
to the <code class="filename">file.out</code> file.)
</p><p>
Now if we run <span class="application">SCons</span> multiple times on this example,
we see that it re-runs the <span class="application">cp</span>
command every time:
</p><pre class="screen">% <strong class="userinput"><code>scons -Q</code></strong>
cp file.in file.oout
% <strong class="userinput"><code>scons -Q</code></strong>
cp file.in file.oout
% <strong class="userinput"><code>scons -Q</code></strong>
cp file.in file.oout
</pre><p>
In this example,
the underlying cause is obvious:
we've intentionally misspelled the output file name
in the <span class="application">cp</span> command,
so the command doesn't actually
build the <code class="filename">file.out</code> file that we've told <span class="application">SCons</span> to expect.
But if the problem weren't obvious,
it would be helpful
to specify the <code class="literal">--debug=explain</code> option
on the command line
to have <span class="application">SCons</span> tell us very specifically
why it's decided to rebuild the target:
</p><pre class="screen">% <strong class="userinput"><code>scons -Q --debug=explain</code></strong>
scons: building `file.out' because it doesn't exist
cp file.in file.oout
</pre><p>
If this had been a more complicated example
involving a lot of build output,
having <span class="application">SCons</span> tell us that
it's trying to rebuild the target file
because it doesn't exist
would be an important clue
that something was wrong with
the command that we invoked to build it.
</p><p>
Note that you can also use --warn=target-not-built which checks
whether or not expected targets exist after a build rule is
executed.
</p><pre class="screen">% <strong class="userinput"><code>scons -Q --warn=target-not-built</code></strong>
cp file.in file.oout
scons: warning: Cannot find target file.out after building
File "/home/bdeegan/devel/scons/git/as_scons/src/script/scons.py", line 204, in &lt;module&gt;
</pre><p>
The <code class="literal">--debug=explain</code> option also comes in handy
to help figure out what input file changed.
Given a simple configuration that builds
a program from three source files,
changing one of the source files
and rebuilding with the <code class="literal">--debug=explain</code>
option shows very specifically
why <span class="application">SCons</span> rebuilds the files that it does:
</p><pre class="screen">% <strong class="userinput"><code>scons -Q</code></strong>
cc -o file1.o -c file1.c
cc -o file2.o -c file2.c
cc -o file3.o -c file3.c
cc -o prog file1.o file2.o file3.o
% [CHANGE THE CONTENTS OF file2.c]
% <strong class="userinput"><code>scons -Q --debug=explain</code></strong>
scons: rebuilding `file2.o' because `file2.c' changed
cc -o file2.o -c file2.c
scons: rebuilding `prog' because `file2.o' changed
cc -o prog file1.o file2.o file3.o
</pre><p>
This becomes even more helpful
in identifying when a file is rebuilt
due to a change in an implicit dependency,
such as an incuded <code class="filename">.h</code> file.
If the <code class="filename">file1.c</code>
and <code class="filename">file3.c</code> files
in our example
both included a <code class="filename">hello.h</code> file,
then changing that included file
and re-running <span class="application">SCons</span> with the <code class="literal">--debug=explain</code> option
will pinpoint that it's the change to the included file
that starts the chain of rebuilds:
</p><pre class="screen">% <strong class="userinput"><code>scons -Q</code></strong>
cc -o file1.o -c -I. file1.c
cc -o file2.o -c -I. file2.c
cc -o file3.o -c -I. file3.c
cc -o prog file1.o file2.o file3.o
% [CHANGE THE CONTENTS OF hello.h]
% <strong class="userinput"><code>scons -Q --debug=explain</code></strong>
scons: rebuilding `file1.o' because `hello.h' changed
cc -o file1.o -c -I. file1.c
scons: rebuilding `file3.o' because `hello.h' changed
cc -o file3.o -c -I. file3.c
scons: rebuilding `prog' because:
`file1.o' changed
`file3.o' changed
cc -o prog file1.o file2.o file3.o
</pre><p>
(Note that the <code class="literal">--debug=explain</code> option will only tell you
why <span class="application">SCons</span> decided to rebuild necessary targets.
It does not tell you what files it examined
when deciding <span class="emphasis"><em>not</em></span>
to rebuild a target file,
which is often a more valuable question to answer.)
</p></div><div class="section" title="28.2.<2E>What's in That Construction Environment? the Dump Method"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idm4910"></a>28.2.<2E>What's in That Construction Environment? the <code class="function">Dump</code> Method</h2></div></div></div><p>
When you create a construction environment,
<span class="application">SCons</span> populates it
with construction variables that are set up
for various compilers, linkers and utilities
that it finds on your system.
Although this is usually helpful and what you want,
it might be frustrating if <span class="application">SCons</span>
doesn't set certain variables that you
expect to be set.
In situations like this,
it's sometimes helpful to use the
construction environment <code class="function">Dump</code> method
to print all or some of
the construction variables.
Note that the <code class="function">Dump</code> method
<span class="emphasis"><em>returns</em></span>
the representation of the variables
in the environment
for you to print (or otherwise manipulate):
</p><pre class="programlisting">
env = Environment()
print env.Dump()
</pre><p>
On a POSIX system with gcc installed,
this might generate:
</p><pre class="screen">% <strong class="userinput"><code>scons</code></strong>
scons: Reading SConscript files ...
{ 'BUILDERS': {'_InternalInstall': &lt;function InstallBuilderWrapper at 0x700000&amp;gt;, '_InternalInstallVersionedLib': &lt;function InstallVersionedBuilderWrapper at 0x700000&amp;gt;, '_InternalInstallAs': &lt;function InstallAsBuilderWrapper at 0x700000&amp;gt;},
'CONFIGUREDIR': '#/.sconf_temp',
'CONFIGURELOG': '#/config.log',
'CPPSUFFIXES': [ '.c',
'.C',
'.cxx',
'.cpp',
'.c++',
'.cc',
'.h',
'.H',
'.hxx',
'.hpp',
'.hh',
'.F',
'.fpp',
'.FPP',
'.m',
'.mm',
'.S',
'.spp',
'.SPP',
'.sx'],
'DSUFFIXES': ['.d'],
'Dir': &lt;SCons.Defaults.Variable_Method_Caller object at 0x700000&amp;gt;,
'Dirs': &lt;SCons.Defaults.Variable_Method_Caller object at 0x700000&amp;gt;,
'ENV': { 'PATH': '/usr/local/bin:/opt/bin:/bin:/usr/bin'},
'ESCAPE': &lt;function escape at 0x700000&amp;gt;,
'File': &lt;SCons.Defaults.Variable_Method_Caller object at 0x700000&amp;gt;,
'HOST_ARCH': None,
'HOST_OS': None,
'IDLSUFFIXES': ['.idl', '.IDL'],
'INSTALL': &lt;function copyFunc at 0x700000&amp;gt;,
'INSTALLVERSIONEDLIB': &lt;function copyFuncVersionedLib at 0x700000&amp;gt;,
'LIBPREFIX': 'lib',
'LIBPREFIXES': ['$LIBPREFIX'],
'LIBSUFFIX': '.a',
'LIBSUFFIXES': ['$LIBSUFFIX', '$SHLIBSUFFIX'],
'MAXLINELENGTH': 128072,
'OBJPREFIX': '',
'OBJSUFFIX': '.o',
'PLATFORM': 'posix',
'PROGPREFIX': '',
'PROGSUFFIX': '',
'PSPAWN': &lt;function piped_env_spawn at 0x700000&amp;gt;,
'RDirs': &lt;SCons.Defaults.Variable_Method_Caller object at 0x700000&amp;gt;,
'SCANNERS': [&lt;SCons.Scanner.Base object at 0x700000&amp;gt;],
'SHELL': 'sh',
'SHLIBPREFIX': '$LIBPREFIX',
'SHLIBSUFFIX': '.so',
'SHOBJPREFIX': '$OBJPREFIX',
'SHOBJSUFFIX': '$OBJSUFFIX',
'SPAWN': &lt;function subprocess_spawn at 0x700000&amp;gt;,
'TARGET_ARCH': None,
'TARGET_OS': None,
'TEMPFILE': &lt;class 'SCons.Platform.TempFileMunge'&gt;,
'TEMPFILEPREFIX': '@',
'TOOLS': ['install', 'install'],
'_CPPDEFFLAGS': '${_defines(CPPDEFPREFIX, CPPDEFINES, CPPDEFSUFFIX, __env__)}',
'_CPPINCFLAGS': '$( ${_concat(INCPREFIX, CPPPATH, INCSUFFIX, __env__, RDirs, TARGET, SOURCE)} $)',
'_LIBDIRFLAGS': '$( ${_concat(LIBDIRPREFIX, LIBPATH, LIBDIRSUFFIX, __env__, RDirs, TARGET, SOURCE)} $)',
'_LIBFLAGS': '${_concat(LIBLINKPREFIX, LIBS, LIBLINKSUFFIX, __env__)}',
'__DRPATH': '$_DRPATH',
'__DSHLIBVERSIONFLAGS': '${__libversionflags(__env__,"DSHLIBVERSION","_DSHLIBVERSIONFLAGS")}',
'__LDMODULEVERSIONFLAGS': '${__libversionflags(__env__,"LDMODULEVERSION","_LDMODULEVERSIONFLAGS")}',
'__RPATH': '$_RPATH',
'__SHLIBVERSIONFLAGS': '${__libversionflags(__env__,"SHLIBVERSION","_SHLIBVERSIONFLAGS")}',
'__libversionflags': &lt;function __libversionflags at 0x700000&amp;gt;,
'_concat': &lt;function _concat at 0x700000&amp;gt;,
'_defines': &lt;function _defines at 0x700000&amp;gt;,
'_stripixes': &lt;function _stripixes at 0x700000&amp;gt;}
scons: done reading SConscript files.
scons: Building targets ...
scons: `.' is up to date.
scons: done building targets.
</pre><p>
On a Windows system with Visual C++
the output might look like:
</p><pre class="screen">C:\&gt;<strong class="userinput"><code>scons</code></strong>
scons: Reading SConscript files ...
{ 'BUILDERS': {'_InternalInstallVersionedLib': &lt;function InstallVersionedBuilderWrapper at 0x700000&amp;gt;, '_InternalInstall': &lt;function InstallBuilderWrapper at 0x700000&amp;gt;, 'Object': &lt;SCons.Builder.CompositeBuilder object at 0x700000&amp;gt;, 'PCH': &lt;SCons.Builder.BuilderBase object at 0x700000&amp;gt;, 'RES': &lt;SCons.Builder.BuilderBase object at 0x700000&amp;gt;, 'SharedObject': &lt;SCons.Builder.CompositeBuilder object at 0x700000&amp;gt;, 'StaticObject': &lt;SCons.Builder.CompositeBuilder object at 0x700000&amp;gt;, '_InternalInstallAs': &lt;function InstallAsBuilderWrapper at 0x700000&amp;gt;},
'CC': 'cl',
'CCCOM': &lt;SCons.Action.FunctionAction object at 0x700000&amp;gt;,
'CCFLAGS': ['/nologo'],
'CCPCHFLAGS': ['${(PCH and "/Yu%s \\"/Fp%s\\""%(PCHSTOP or "",File(PCH))) or ""}'],
'CCPDBFLAGS': ['${(PDB and "/Z7") or ""}'],
'CFILESUFFIX': '.c',
'CFLAGS': [],
'CONFIGUREDIR': '#/.sconf_temp',
'CONFIGURELOG': '#/config.log',
'CPPDEFPREFIX': '/D',
'CPPDEFSUFFIX': '',
'CPPSUFFIXES': [ '.c',
'.C',
'.cxx',
'.cpp',
'.c++',
'.cc',
'.h',
'.H',
'.hxx',
'.hpp',
'.hh',
'.F',
'.fpp',
'.FPP',
'.m',
'.mm',
'.S',
'.spp',
'.SPP',
'.sx'],
'CXX': '$CC',
'CXXCOM': '${TEMPFILE("$CXX $_MSVC_OUTPUT_FLAG /c $CHANGED_SOURCES $CXXFLAGS $CCFLAGS $_CCCOMCOM","$CXXCOMSTR")}',
'CXXFILESUFFIX': '.cc',
'CXXFLAGS': ['$(', '/TP', '$)'],
'DSUFFIXES': ['.d'],
'Dir': &lt;SCons.Defaults.Variable_Method_Caller object at 0x700000&amp;gt;,
'Dirs': &lt;SCons.Defaults.Variable_Method_Caller object at 0x700000&amp;gt;,
'ENV': { 'PATH': 'C:\\WINDOWS\\System32',
'PATHEXT': '.COM;.EXE;.BAT;.CMD',
'SystemRoot': 'C:\\WINDOWS'},
'ESCAPE': &lt;function escape at 0x700000&amp;gt;,
'File': &lt;SCons.Defaults.Variable_Method_Caller object at 0x700000&amp;gt;,
'HOST_ARCH': '',
'HOST_OS': 'win32',
'IDLSUFFIXES': ['.idl', '.IDL'],
'INCPREFIX': '/I',
'INCSUFFIX': '',
'INSTALL': &lt;function copyFunc at 0x700000&amp;gt;,
'INSTALLVERSIONEDLIB': &lt;function copyFuncVersionedLib at 0x700000&amp;gt;,
'LIBPREFIX': '',
'LIBPREFIXES': ['$LIBPREFIX'],
'LIBSUFFIX': '.lib',
'LIBSUFFIXES': ['$LIBSUFFIX'],
'MAXLINELENGTH': 2048,
'MSVC_SETUP_RUN': True,
'OBJPREFIX': '',
'OBJSUFFIX': '.obj',
'PCHCOM': '$CXX /Fo${TARGETS[1]} $CXXFLAGS $CCFLAGS $CPPFLAGS $_CPPDEFFLAGS $_CPPINCFLAGS /c $SOURCES /Yc$PCHSTOP /Fp${TARGETS[0]} $CCPDBFLAGS $PCHPDBFLAGS',
'PCHPDBFLAGS': ['${(PDB and "/Yd") or ""}'],
'PLATFORM': 'win32',
'PROGPREFIX': '',
'PROGSUFFIX': '.exe',
'PSPAWN': &lt;function piped_spawn at 0x700000&amp;gt;,
'RC': 'rc',
'RCCOM': &lt;SCons.Action.FunctionAction object at 0x700000&amp;gt;,
'RCFLAGS': [],
'RCSUFFIXES': ['.rc', '.rc2'],
'RDirs': &lt;SCons.Defaults.Variable_Method_Caller object at 0x700000&amp;gt;,
'SCANNERS': [&lt;SCons.Scanner.Base object at 0x700000&amp;gt;],
'SHCC': '$CC',
'SHCCCOM': &lt;SCons.Action.FunctionAction object at 0x700000&amp;gt;,
'SHCCFLAGS': ['$CCFLAGS'],
'SHCFLAGS': ['$CFLAGS'],
'SHCXX': '$CXX',
'SHCXXCOM': '${TEMPFILE("$SHCXX $_MSVC_OUTPUT_FLAG /c $CHANGED_SOURCES $SHCXXFLAGS $SHCCFLAGS $_CCCOMCOM","$SHCXXCOMSTR")}',
'SHCXXFLAGS': ['$CXXFLAGS'],
'SHELL': None,
'SHLIBPREFIX': '',
'SHLIBSUFFIX': '.dll',
'SHOBJPREFIX': '$OBJPREFIX',
'SHOBJSUFFIX': '$OBJSUFFIX',
'SPAWN': &lt;function spawn at 0x700000&amp;gt;,
'STATIC_AND_SHARED_OBJECTS_ARE_THE_SAME': 1,
'TARGET_ARCH': None,
'TARGET_OS': None,
'TEMPFILE': &lt;class 'SCons.Platform.TempFileMunge'&gt;,
'TEMPFILEPREFIX': '@',
'TOOLS': ['msvc', 'install', 'install'],
'_CCCOMCOM': '$CPPFLAGS $_CPPDEFFLAGS $_CPPINCFLAGS $CCPCHFLAGS $CCPDBFLAGS',
'_CPPDEFFLAGS': '${_defines(CPPDEFPREFIX, CPPDEFINES, CPPDEFSUFFIX, __env__)}',
'_CPPINCFLAGS': '$( ${_concat(INCPREFIX, CPPPATH, INCSUFFIX, __env__, RDirs, TARGET, SOURCE)} $)',
'_LIBDIRFLAGS': '$( ${_concat(LIBDIRPREFIX, LIBPATH, LIBDIRSUFFIX, __env__, RDirs, TARGET, SOURCE)} $)',
'_LIBFLAGS': '${_concat(LIBLINKPREFIX, LIBS, LIBLINKSUFFIX, __env__)}',
'_MSVC_OUTPUT_FLAG': &lt;function msvc_output_flag at 0x700000&amp;gt;,
'__DSHLIBVERSIONFLAGS': '${__libversionflags(__env__,"DSHLIBVERSION","_DSHLIBVERSIONFLAGS")}',
'__LDMODULEVERSIONFLAGS': '${__libversionflags(__env__,"LDMODULEVERSION","_LDMODULEVERSIONFLAGS")}',
'__SHLIBVERSIONFLAGS': '${__libversionflags(__env__,"SHLIBVERSION","_SHLIBVERSIONFLAGS")}',
'__libversionflags': &lt;function __libversionflags at 0x700000&amp;gt;,
'_concat': &lt;function _concat at 0x700000&amp;gt;,
'_defines': &lt;function _defines at 0x700000&amp;gt;,
'_stripixes': &lt;function _stripixes at 0x700000&amp;gt;}
scons: done reading SConscript files.
scons: Building targets ...
scons: `.' is up to date.
scons: done building targets.
</pre><p>
The construction environments in these examples have
actually been restricted to just gcc and Visual C++,
respectively.
In a real-life situation,
the construction environments will
likely contain a great many more variables.
Also note that we've massaged the example output above
to make the memory address of all objects a constant 0x700000.
In reality, you would see a different hexadecimal
number for each object.
</p><p>
To make it easier to see just what you're
interested in,
the <code class="function">Dump</code> method allows you to
specify a specific constrcution variable
that you want to disply.
For example,
it's not unusual to want to verify
the external environment used to execute build commands,
to make sure that the PATH and other
environment variables are set up the way they should be.
You can do this as follows:
</p><pre class="programlisting">
env = Environment()
print env.Dump('ENV')
</pre><p>
Which might display the following when executed on a POSIX system:
</p><pre class="screen">% <strong class="userinput"><code>scons</code></strong>
scons: Reading SConscript files ...
{ 'PATH': '/usr/local/bin:/opt/bin:/bin:/usr/bin'}
scons: done reading SConscript files.
scons: Building targets ...
scons: `.' is up to date.
scons: done building targets.
</pre><p>
And the following when executed on a Windows system:
</p><pre class="screen">C:\&gt;<strong class="userinput"><code>scons</code></strong>
scons: Reading SConscript files ...
{ 'PATH': 'C:\\WINDOWS\\System32:/usr/bin',
'PATHEXT': '.COM;.EXE;.BAT;.CMD',
'SystemRoot': 'C:\\WINDOWS'}
scons: done reading SConscript files.
scons: Building targets ...
scons: `.' is up to date.
scons: done building targets.
</pre></div><div class="section" title="28.3.<2E>What Dependencies Does SCons Know About? the --tree Option"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idm4936"></a>28.3.<2E>What Dependencies Does <span class="application">SCons</span> Know About? the <code class="literal">--tree</code> Option</h2></div></div></div><p>
Sometimes the best way to try to figure out what
<span class="application">SCons</span> is doing is simply to take a look at the
dependency graph that it constructs
based on your <code class="filename">SConscript</code> files.
The <code class="literal">--tree</code> option
will display all or part of the
<span class="application">SCons</span> dependency graph in an
"ASCII art" graphical format
that shows the dependency hierarchy.
</p><p>
For example, given the following input <code class="filename">SConstruct</code> file:
</p><pre class="programlisting">
env = Environment(CPPPATH = ['.'])
env.Program('prog', ['f1.c', 'f2.c', 'f3.c'])
</pre><p>
Running <span class="application">SCons</span> with the <code class="literal">--tree=all</code>
option yields:
</p><pre class="screen">% <strong class="userinput"><code>scons -Q --tree=all</code></strong>
cc -o f1.o -c -I. f1.c
cc -o f2.o -c -I. f2.c
cc -o f3.o -c -I. f3.c
cc -o prog f1.o f2.o f3.o
+-.
+-SConstruct
+-f1.c
+-f1.o
| +-f1.c
| +-inc.h
+-f2.c
+-f2.o
| +-f2.c
| +-inc.h
+-f3.c
+-f3.o
| +-f3.c
| +-inc.h
+-inc.h
+-prog
+-f1.o
| +-f1.c
| +-inc.h
+-f2.o
| +-f2.c
| +-inc.h
+-f3.o
+-f3.c
+-inc.h
</pre><p>
The tree will also be printed when the
<code class="literal">-n</code> (no execute) option is used,
which allows you to examine the dependency graph
for a configuration without actually
rebuilding anything in the tree.
</p><p>
The <code class="literal">--tree</code> option only prints
the dependency graph for the specified targets
(or the default target(s) if none are specified on the command line).
So if you specify a target like <code class="filename">f2.o</code>
on the command line,
the <code class="literal">--tree</code> option will only
print the dependency graph for that file:
</p><pre class="screen">% <strong class="userinput"><code>scons -Q --tree=all f2.o</code></strong>
cc -o f2.o -c -I. f2.c
+-f2.o
+-f2.c
+-inc.h
</pre><p>
This is, of course, useful for
restricting the output from a very large
build configuration to just a
portion in which you're interested.
Multiple targets are fine,
in which case a tree will be printed
for each specified target:
</p><pre class="screen">% <strong class="userinput"><code>scons -Q --tree=all f1.o f3.o</code></strong>
cc -o f1.o -c -I. f1.c
+-f1.o
+-f1.c
+-inc.h
cc -o f3.o -c -I. f3.c
+-f3.o
+-f3.c
+-inc.h
</pre><p>
The <code class="literal">status</code> argument may be used
to tell <span class="application">SCons</span> to print status information about
each file in the dependency graph:
</p><pre class="screen">% <strong class="userinput"><code>scons -Q --tree=status</code></strong>
cc -o f1.o -c -I. f1.c
cc -o f2.o -c -I. f2.c
cc -o f3.o -c -I. f3.c
cc -o prog f1.o f2.o f3.o
E = exists
R = exists in repository only
b = implicit builder
B = explicit builder
S = side effect
P = precious
A = always build
C = current
N = no clean
H = no cache
[E b ]+-.
[E C ] +-SConstruct
[E C ] +-f1.c
[E B C ] +-f1.o
[E C ] | +-f1.c
[E C ] | +-inc.h
[E C ] +-f2.c
[E B C ] +-f2.o
[E C ] | +-f2.c
[E C ] | +-inc.h
[E C ] +-f3.c
[E B C ] +-f3.o
[E C ] | +-f3.c
[E C ] | +-inc.h
[E C ] +-inc.h
[E B C ] +-prog
[E B C ] +-f1.o
[E C ] | +-f1.c
[E C ] | +-inc.h
[E B C ] +-f2.o
[E C ] | +-f2.c
[E C ] | +-inc.h
[E B C ] +-f3.o
[E C ] +-f3.c
[E C ] +-inc.h
</pre><p>
Note that <code class="literal">--tree=all,status</code> is equivalent;
the <code class="literal">all</code>
is assumed if only <code class="literal">status</code> is present.
As an alternative to <code class="literal">all</code>,
you can specify <code class="literal">--tree=derived</code>
to have <span class="application">SCons</span> only print derived targets
in the tree output,
skipping source files
(like <code class="filename">.c</code> and <code class="filename">.h</code> files):
</p><pre class="screen">% <strong class="userinput"><code>scons -Q --tree=derived</code></strong>
cc -o f1.o -c -I. f1.c
cc -o f2.o -c -I. f2.c
cc -o f3.o -c -I. f3.c
cc -o prog f1.o f2.o f3.o
+-.
+-f1.o
+-f2.o
+-f3.o
+-prog
+-f1.o
+-f2.o
+-f3.o
</pre><p>
You can use the <code class="literal">status</code>
modifier with <code class="literal">derived</code> as well:
</p><pre class="screen">% <strong class="userinput"><code>scons -Q --tree=derived,status</code></strong>
cc -o f1.o -c -I. f1.c
cc -o f2.o -c -I. f2.c
cc -o f3.o -c -I. f3.c
cc -o prog f1.o f2.o f3.o
E = exists
R = exists in repository only
b = implicit builder
B = explicit builder
S = side effect
P = precious
A = always build
C = current
N = no clean
H = no cache
[E b ]+-.
[E B C ] +-f1.o
[E B C ] +-f2.o
[E B C ] +-f3.o
[E B C ] +-prog
[E B C ] +-f1.o
[E B C ] +-f2.o
[E B C ] +-f3.o
</pre><p>
Note that the order of the <code class="literal">--tree=</code>
arguments doesn't matter;
<code class="literal">--tree=status,derived</code> is
completely equivalent.
</p><p>
The default behavior of the <code class="literal">--tree</code> option
is to repeat all of the dependencies each time the library dependency
(or any other dependency file) is encountered in the tree.
If certain target files share other target files,
such as two programs that use the same library:
</p><pre class="programlisting">
env = Environment(CPPPATH = ['.'],
LIBS = ['foo'],
LIBPATH = ['.'])
env.Library('foo', ['f1.c', 'f2.c', 'f3.c'])
env.Program('prog1.c')
env.Program('prog2.c')
</pre><p>
Then there can be a <span class="emphasis"><em>lot</em></span> of repetition in the
<code class="literal">--tree=</code> output:
</p><pre class="screen">% <strong class="userinput"><code>scons -Q --tree=all</code></strong>
cc -o f1.o -c -I. f1.c
cc -o f2.o -c -I. f2.c
cc -o f3.o -c -I. f3.c
ar rc libfoo.a f1.o f2.o f3.o
ranlib libfoo.a
cc -o prog1.o -c -I. prog1.c
cc -o prog1 prog1.o -L. -lfoo
cc -o prog2.o -c -I. prog2.c
cc -o prog2 prog2.o -L. -lfoo
+-.
+-SConstruct
+-f1.c
+-f1.o
| +-f1.c
| +-inc.h
+-f2.c
+-f2.o
| +-f2.c
| +-inc.h
+-f3.c
+-f3.o
| +-f3.c
| +-inc.h
+-inc.h
+-libfoo.a
| +-f1.o
| | +-f1.c
| | +-inc.h
| +-f2.o
| | +-f2.c
| | +-inc.h
| +-f3.o
| +-f3.c
| +-inc.h
+-prog1
| +-prog1.o
| | +-prog1.c
| | +-inc.h
| +-libfoo.a
| +-f1.o
| | +-f1.c
| | +-inc.h
| +-f2.o
| | +-f2.c
| | +-inc.h
| +-f3.o
| +-f3.c
| +-inc.h
+-prog1.c
+-prog1.o
| +-prog1.c
| +-inc.h
+-prog2
| +-prog2.o
| | +-prog2.c
| | +-inc.h
| +-libfoo.a
| +-f1.o
| | +-f1.c
| | +-inc.h
| +-f2.o
| | +-f2.c
| | +-inc.h
| +-f3.o
| +-f3.c
| +-inc.h
+-prog2.c
+-prog2.o
+-prog2.c
+-inc.h
</pre><p>
In a large configuration with many internal libraries
and include files,
this can very quickly lead to huge output trees.
To help make this more manageable,
a <code class="literal">prune</code> modifier may
be added to the option list,
in which case <span class="application">SCons</span>
will print the name of a target that has
already been visited during the tree-printing
in <code class="literal">[square brackets]</code>
as an indication that the dependencies
of the target file may be found
by looking farther up the tree:
</p><pre class="screen">% <strong class="userinput"><code>scons -Q --tree=prune</code></strong>
cc -o f1.o -c -I. f1.c
cc -o f2.o -c -I. f2.c
cc -o f3.o -c -I. f3.c
ar rc libfoo.a f1.o f2.o f3.o
ranlib libfoo.a
cc -o prog1.o -c -I. prog1.c
cc -o prog1 prog1.o -L. -lfoo
cc -o prog2.o -c -I. prog2.c
cc -o prog2 prog2.o -L. -lfoo
+-.
+-SConstruct
+-f1.c
+-f1.o
| +-f1.c
| +-inc.h
+-f2.c
+-f2.o
| +-f2.c
| +-inc.h
+-f3.c
+-f3.o
| +-f3.c
| +-inc.h
+-inc.h
+-libfoo.a
| +-[f1.o]
| +-[f2.o]
| +-[f3.o]
+-prog1
| +-prog1.o
| | +-prog1.c
| | +-inc.h
| +-[libfoo.a]
+-prog1.c
+-[prog1.o]
+-prog2
| +-prog2.o
| | +-prog2.c
| | +-inc.h
| +-[libfoo.a]
+-prog2.c
+-[prog2.o]
</pre><p>
Like the <code class="literal">status</code> keyword,
the <code class="literal">prune</code> argument by itself
is equivalent to <code class="literal">--tree=all,prune</code>.
</p></div><div class="section" title="28.4.<2E>How is SCons Constructing the Command Lines It Executes? the --debug=presub Option"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idm5006"></a>28.4.<2E>How is <span class="application">SCons</span> Constructing the Command Lines It Executes? the <code class="literal">--debug=presub</code> Option</h2></div></div></div><p>
Sometimes it's useful to look at the
pre-substitution string
that <span class="application">SCons</span> uses to generate
the command lines it executes.
This can be done with the <code class="literal">--debug=presub</code> option:
</p><pre class="screen">
% <strong class="userinput"><code>scons -Q --debug=presub</code></strong>
Building prog.o with action:
$CC -o $TARGET -c $CFLAGS $CCFLAGS $_CCOMCOM $SOURCES
cc -o prog.o -c -I. prog.c
Building prog with action:
$SMART_LINKCOM
cc -o prog prog.o
</pre></div><div class="section" title="28.5.<2E>Where is SCons Searching for Libraries? the --debug=findlibs Option"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idm5015"></a>28.5.<2E>Where is <span class="application">SCons</span> Searching for Libraries? the <code class="literal">--debug=findlibs</code> Option</h2></div></div></div><p>
To get some insight into what library names
<span class="application">SCons</span> is searching for,
and in which directories it is searching,
Use the <code class="literal">--debug=findlibs</code> option.
Given the following input <code class="filename">SConstruct</code> file:
</p><pre class="programlisting">
env = Environment(LIBPATH = ['libs1', 'libs2'])
env.Program('prog.c', LIBS=['foo', 'bar'])
</pre><p>
And the libraries <code class="filename">libfoo.a</code>
and <code class="filename">libbar.a</code>
in <code class="filename">libs1</code> and <code class="filename">libs2</code>,
respectively,
use of the <code class="literal">--debug=findlibs</code> option yields:
</p><pre class="screen">% <strong class="userinput"><code>scons -Q --debug=findlibs</code></strong>
findlibs: looking for 'libfoo.a' in 'libs1' ...
findlibs: ... FOUND 'libfoo.a' in 'libs1'
findlibs: looking for 'libfoo.so' in 'libs1' ...
findlibs: looking for 'libfoo.so' in 'libs2' ...
findlibs: looking for 'libbar.a' in 'libs1' ...
findlibs: looking for 'libbar.a' in 'libs2' ...
findlibs: ... FOUND 'libbar.a' in 'libs2'
findlibs: looking for 'libbar.so' in 'libs1' ...
findlibs: looking for 'libbar.so' in 'libs2' ...
cc -o prog.o -c prog.c
cc -o prog prog.o -Llibs1 -Llibs2 -lfoo -lbar
</pre></div><div class="section" title="28.6.<2E>Where is SCons Blowing Up? the --debug=stacktrace Option"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idm5032"></a>28.6.<2E>Where is <span class="application">SCons</span> Blowing Up? the <code class="literal">--debug=stacktrace</code> Option</h2></div></div></div><p>
In general, <span class="application">SCons</span> tries to keep its error
messages short and informative.
That means we usually try to avoid showing
the stack traces that are familiar
to experienced Python programmers,
since they usually contain much more
information than is useful to most people.
</p><p>
For example, the following <code class="filename">SConstruct</code> file:
</p><pre class="programlisting">
Program('prog.c')
</pre><p>
Generates the following error if the
<code class="filename">prog.c</code> file
does not exist:
</p><pre class="screen">% <strong class="userinput"><code>scons -Q</code></strong>
scons: *** [prog.o] Source `prog.c' not found, needed by target `prog.o'.
</pre><p>
In this case,
the error is pretty obvious.
But if it weren't,
and you wanted to try to get more information
about the error,
the <code class="literal">--debug=stacktrace</code> option
would show you exactly where in the <span class="application">SCons</span> source code
the problem occurs:
</p><pre class="screen">% <strong class="userinput"><code>scons -Q --debug=stacktrace</code></strong>
scons: *** [prog.o] Source `prog.c' not found, needed by target `prog.o'.
scons: internal stack trace:
File "bootstrap/src/engine/SCons/Job.py", line 199, in start
task.prepare()
File "bootstrap/src/engine/SCons/Script/Main.py", line 177, in prepare
return SCons.Taskmaster.OutOfDateTask.prepare(self)
File "bootstrap/src/engine/SCons/Taskmaster.py", line 198, in prepare
executor.prepare()
File "bootstrap/src/engine/SCons/Executor.py", line 430, in prepare
raise SCons.Errors.StopError(msg % (s, self.batches[0].targets[0]))
</pre><p>
Of course, if you do need to dive into the <span class="application">SCons</span> source code,
we'd like to know if, or how,
the error messages or troubleshooting options
could have been improved to avoid that.
Not everyone has the necessary time or
Python skill to dive into the source code,
and we'd like to improve <span class="application">SCons</span>
for those people as well...
</p></div><div class="section" title="28.7.<2E>How is SCons Making Its Decisions? the --taskmastertrace Option"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idm5053"></a>28.7.<2E>How is <span class="application">SCons</span> Making Its Decisions? the <code class="literal">--taskmastertrace</code> Option</h2></div></div></div><p>
The internal <span class="application">SCons</span> subsystem that handles walking
the dependency graph
and controls the decision-making about what to rebuild
is the <code class="literal">Taskmaster</code>.
<span class="application">SCons</span> supports a <code class="literal">--taskmastertrace</code>
option that tells the Taskmaster to print
information about the children (dependencies)
of the various Nodes on its walk down the graph,
which specific dependent Nodes are being evaluated,
and in what order.
</p><p>
The <code class="literal">--taskmastertrace</code> option
takes as an argument the name of a file in
which to put the trace output,
with <code class="filename">-</code> (a single hyphen)
indicating that the trace messages
should be printed to the standard output:
</p><pre class="programlisting">
env = Environment(CPPPATH = ['.'])
env.Program('prog.c')
</pre><pre class="screen">% <strong class="userinput"><code>scons -Q --taskmastertrace=- prog</code></strong>
Taskmaster: Looking for a node to evaluate
Taskmaster: Considering node &lt;no_state 0 'prog'&gt; and its children:
Taskmaster: &lt;no_state 0 'prog.o'&gt;
Taskmaster: adjusted ref count: &lt;pending 1 'prog'&gt;, child 'prog.o'
Taskmaster: Considering node &lt;no_state 0 'prog.o'&gt; and its children:
Taskmaster: &lt;no_state 0 'prog.c'&gt;
Taskmaster: &lt;no_state 0 'inc.h'&gt;
Taskmaster: adjusted ref count: &lt;pending 1 'prog.o'&gt;, child 'prog.c'
Taskmaster: adjusted ref count: &lt;pending 2 'prog.o'&gt;, child 'inc.h'
Taskmaster: Considering node &lt;no_state 0 'prog.c'&gt; and its children:
Taskmaster: Evaluating &lt;pending 0 'prog.c'&gt;
Task.make_ready_current(): node &lt;pending 0 'prog.c'&gt;
Task.prepare(): node &lt;up_to_date 0 'prog.c'&gt;
Task.executed_with_callbacks(): node &lt;up_to_date 0 'prog.c'&gt;
Task.postprocess(): node &lt;up_to_date 0 'prog.c'&gt;
Task.postprocess(): removing &lt;up_to_date 0 'prog.c'&gt;
Task.postprocess(): adjusted parent ref count &lt;pending 1 'prog.o'&gt;
Taskmaster: Looking for a node to evaluate
Taskmaster: Considering node &lt;no_state 0 'inc.h'&gt; and its children:
Taskmaster: Evaluating &lt;pending 0 'inc.h'&gt;
Task.make_ready_current(): node &lt;pending 0 'inc.h'&gt;
Task.prepare(): node &lt;up_to_date 0 'inc.h'&gt;
Task.executed_with_callbacks(): node &lt;up_to_date 0 'inc.h'&gt;
Task.postprocess(): node &lt;up_to_date 0 'inc.h'&gt;
Task.postprocess(): removing &lt;up_to_date 0 'inc.h'&gt;
Task.postprocess(): adjusted parent ref count &lt;pending 0 'prog.o'&gt;
Taskmaster: Looking for a node to evaluate
Taskmaster: Considering node &lt;pending 0 'prog.o'&gt; and its children:
Taskmaster: &lt;up_to_date 0 'prog.c'&gt;
Taskmaster: &lt;up_to_date 0 'inc.h'&gt;
Taskmaster: Evaluating &lt;pending 0 'prog.o'&gt;
Task.make_ready_current(): node &lt;pending 0 'prog.o'&gt;
Task.prepare(): node &lt;executing 0 'prog.o'&gt;
Task.execute(): node &lt;executing 0 'prog.o'&gt;
cc -o prog.o -c -I. prog.c
Task.executed_with_callbacks(): node &lt;executing 0 'prog.o'&gt;
Task.postprocess(): node &lt;executed 0 'prog.o'&gt;
Task.postprocess(): removing &lt;executed 0 'prog.o'&gt;
Task.postprocess(): adjusted parent ref count &lt;pending 0 'prog'&gt;
Taskmaster: Looking for a node to evaluate
Taskmaster: Considering node &lt;pending 0 'prog'&gt; and its children:
Taskmaster: &lt;executed 0 'prog.o'&gt;
Taskmaster: Evaluating &lt;pending 0 'prog'&gt;
Task.make_ready_current(): node &lt;pending 0 'prog'&gt;
Task.prepare(): node &lt;executing 0 'prog'&gt;
Task.execute(): node &lt;executing 0 'prog'&gt;
cc -o prog prog.o
Task.executed_with_callbacks(): node &lt;executing 0 'prog'&gt;
Task.postprocess(): node &lt;executed 0 'prog'&gt;
Taskmaster: Looking for a node to evaluate
Taskmaster: No candidate anymore.
</pre><p>
The <code class="literal">--taskmastertrace</code> option
doesn't provide information about the actual
calculations involved in deciding if a file is up-to-date,
but it does show all of the dependencies
it knows about for each Node,
and the order in which those dependencies are evaluated.
This can be useful as an alternate way to determine
whether or not your <span class="application">SCons</span> configuration,
or the implicit dependency scan,
has actually identified all the correct dependencies
you want it to.
</p></div><div class="section" title="28.8.<2E>Watch SCons prepare targets for building: the --debug=prepare Option"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idm5071"></a>28.8.<2E>Watch <span class="application">SCons</span> prepare targets for building: the <code class="literal">--debug=prepare</code> Option</h2></div></div></div><p>
Sometimes SCons doesn't build the target you want
and it's difficult to figure out why. You can use
the <code class="literal">--debug=prepare</code> option
to see all the targets <span class="application">SCons</span> is considering, whether
they are already up-to-date or not. The message is
printed before <span class="application">SCons</span> decides whether to build the target.
</p></div><div class="section" title="28.9.<2E>Why is a file disappearing? the --debug=duplicate Option"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idm5079"></a>28.9.<2E>Why is a file disappearing? the --debug=duplicate Option</h2></div></div></div><p>
When using the <code class="function">Duplicate</code> option to create variant dirs,
sometimes you may find files not getting copied to where you
expect (or not at all), or files mysteriously disappearing. These
are usually because of a misconfiguration of some kind in the
SConstruct/SConscript, but they can be tricky to debug. The
--debug=duplicate option shows each time a variant file is
unlinked and relinked from its source (or copied, depending on
settings), and also shows a message for removing "stale"
variant-dir files that no longer have a corresponding source file.
It also prints a line for each target that's removed just before
building, since that can also be mistaken for the same thing.
</p></div></div><div class="appendix" title="Appendix<69>A.<2E>Construction Variables"><div class="titlepage"><div><div><h2 class="title"><a name="app-variables"></a>Appendix<EFBFBD>A.<2E>Construction Variables</h2></div></div></div><p>
This appendix contains descriptions of all of the
construction variables that are <span class="emphasis"><em>potentially</em></span>
available "out of the box" in this version of SCons.
Whether or not setting a construction variable
in a construction environment
will actually have an effect depends on
whether any of the Tools and/or Builders
that use the variable have been
included in the construction environment.
</p><p>
In this appendix, we have
appended the initial <code class="envar">$</code>
(dollar sign) to the beginning of each
variable name when it appears in the text,
but left off the dollar sign
in the left-hand column
where the name appears for each entry.
</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 &lt;Fmwk/Header.h&gt;.
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">&#8220;<span class="quote"><code class="literal">$GS $GSFLAGS -sOutputFile=$TARGET $SOURCES</code></span>&#8221;</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">&#8220;<span class="quote"><code class="literal">-dNOPAUSE -dBATCH -sDEVICE=pdfwrite</code></span>&#8221;</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 -&gt; %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}&lt;basename&gt;${QT_MOCCXXSUFFIX}, by default
&lt;basename&gt;.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&lt;dir&gt;</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&lt;file&gt;</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></div><div class="appendix" title="Appendix<69>B.<2E>Builders"><div class="titlepage"><div><div><h2 class="title"><a name="app-builders"></a>Appendix<EFBFBD>B.<2E>Builders</h2></div></div></div><p>
This appendix contains descriptions of all of the
Builders that are <span class="emphasis"><em>potentially</em></span>
available "out of the box" in this version of SCons.
</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">&#8220;<span class="quote"><code class="literal">scons -c</code></span>&#8221;</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">&#8220;<span class="quote"><code class="literal">scons -c</code></span>&#8221;</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">&#8220;<span class="quote"><code class="literal">scons -c</code></span>&#8221;</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 --&gt; [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 --&gt; [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 --&gt; [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 --&gt; [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 --&gt; [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 -- &gt; [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&lt;----
Goethe
42
Schiller
....8&lt;---- (no linefeed at the end)
bar.txt:
....8&lt;----
lalala|*tanteratei
....8&lt;---- (no linefeed at the end)
blob.txt
....8&lt;----
lalala
Goethe
42
Schiller
tanteratei
....8&lt;---- (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') # -&gt; ['foo.h', 'uic_foo.cc', 'moc_foo.cc']
env.Uic(target = Split('include/foo.h gen/uicfoo.cc gen/mocfoo.cc'),
source = 'foo.ui') # -&gt; ['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></div><div class="appendix" title="Appendix<69>C.<2E>Tools"><div class="titlepage"><div><div><h2 class="title"><a name="app-tools"></a>Appendix<EFBFBD>C.<2E>Tools</h2></div></div></div><p>
This appendix contains descriptions of all of the
Tools modules that are
available "out of the box" in this version of SCons.
</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></div><div class="appendix" title="Appendix<69>D.<2E>Functions and Environment Methods"><div class="titlepage"><div><div><h2 class="title"><a name="app-functions"></a>Appendix<EFBFBD>D.<2E>Functions and Environment Methods</h2></div></div></div><p>
This appendix contains descriptions of all of the
function and construction environment methods
in this version of <span class="application">SCons</span>
</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 &lt; $SOURCES &gt; $TARGET")
env.Command('bar.out', 'bar.in',
["rm -f $TARGET",
"$BAR_BUILD &lt; $SOURCES &gt; $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 &lt; $SOURCES &gt; .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 &gt; $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
&#923;
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="appendix" title="Appendix<69>E.<2E>Handling Common Tasks"><div class="titlepage"><div><div><h2 class="title"><a name="app-tasks"></a>Appendix<EFBFBD>E.<2E>Handling Common Tasks</h2></div></div></div><p>
There is a common set of simple tasks that many build configurations rely
on as they become more complex. Most build tools have special
purpose constructs for performing these tasks, but since <code class="filename">SConscript</code>
files are <span class="application">Python</span> scripts, you can use more flexible built-in <span class="application">Python</span>
services to perform these tasks. This appendix lists a number of these
tasks and how to implement them in <span class="application">Python</span> and <span class="application">SCons</span>.
</p><div class="example"><a name="idm14932"></a><p class="title"><b>Example<EFBFBD>E.1.<2E>Wildcard globbing to create a list of filenames</b></p><div class="example-contents"><pre class="programlisting">
files = Glob(wildcard)
</pre></div></div><br class="example-break"><div class="example"><a name="idm14935"></a><p class="title"><b>Example<EFBFBD>E.2.<2E>Filename extension substitution</b></p><div class="example-contents"><pre class="programlisting">
import os.path
filename = os.path.splitext(filename)[0]+extension
</pre></div></div><br class="example-break"><div class="example"><a name="idm14938"></a><p class="title"><b>Example<EFBFBD>E.3.<2E>Appending a path prefix to a list of filenames</b></p><div class="example-contents"><pre class="programlisting">
import os.path
filenames = [os.path.join(prefix, x) for x in filenames]
</pre></div></div><br class="example-break"><div class="example"><a name="idm14941"></a><p class="title"><b>Example<EFBFBD>E.4.<2E>Substituting a path prefix with another one</b></p><div class="example-contents"><pre class="programlisting">
if filename.find(old_prefix) == 0:
filename = filename.replace(old_prefix, new_prefix)
</pre></div></div><br class="example-break"><div class="example"><a name="idm14944"></a><p class="title"><b>Example<EFBFBD>E.5.<2E>Filtering a filename list to exclude/retain only a specific set
of extensions</b></p><div class="example-contents"><pre class="programlisting">
import os.path
filenames = [x for x in filenames if os.path.splitext(x)[1] in extensions]
</pre></div></div><br class="example-break"><div class="example"><a name="idm14947"></a><p class="title"><b>Example<EFBFBD>E.6.<2E>The "backtick function": run a shell command and capture the
output</b></p><div class="example-contents"><pre class="programlisting">import subprocess
output = subprocess.check_output(command)
</pre></div></div><br class="example-break"><div class="example"><a name="idm14950"></a><p class="title"><b>Example<EFBFBD>E.7.<2E>Generating source code: how code can be generated and used by SCons</b></p><div class="example-contents"><p>
The Copy builders here could be any arbitrary shell or python function
that produces one or more files. This example shows how to create
those files and use them in <span class="application">SCons</span>.
</p><pre class="programlisting">
#### SConstruct
env = Environment()
env.Append(CPPPATH = "#")
## Header example
env.Append(BUILDERS =
{'Copy1' : Builder(action = 'cat &lt; $SOURCE &gt; $TARGET',
suffix='.h', src_suffix='.bar')})
env.Copy1('test.bar') # produces test.h from test.bar.
env.Program('app','main.cpp') # indirectly depends on test.bar
## Source file example
env.Append(BUILDERS =
{'Copy2' : Builder(action = 'cat &lt; $SOURCE &gt; $TARGET',
suffix='.cpp', src_suffix='.bar2')})
foo = env.Copy2('foo.bar2') # produces foo.cpp from foo.bar2.
env.Program('app2',['main2.cpp'] + foo) # compiles main2.cpp and foo.cpp into app2.
</pre><p>
Where main.cpp looks like this:
</p><pre class="programlisting">
#include "test.h"
</pre><p>
produces this:
</p><pre class="screen">% <strong class="userinput"><code>scons -Q</code></strong>
cat &lt; test.bar &gt; test.h
cc -o app main.cpp
cat &lt; foo.bar2 &gt; foo.cpp
cc -o app2 main2.cpp foo.cpp
</pre></div></div><br class="example-break"></div></div></body></html>