SCONS(1)SCONS(1)NAMEscons - a software construction tool
SYNOPSISscons [ options... ] [ name=val... ] [ targets... ]
DESCRIPTION
The scons utility builds software (or other files) by determining which
component pieces must be rebuilt and executing the necessary commands
to rebuild them.
By default, scons searches for a file named SConstruct, Sconstruct, or
sconstruct (in that order) in the current directory and reads its con‐
figuration from the first file found. An alternate file name may be
specified via the -f option.
The SConstruct file can specify subsidiary configuration files using
the SConscript() function. By convention, these subsidiary files are
named SConscript, although any name may be used. (Because of this nam‐
ing convention, the term "SConscript files" is sometimes used to refer
generically to all scons configuration files, regardless of actual file
name.)
The configuration files specify the target files to be built, and
(optionally) the rules to build those targets. Reasonable default
rules exist for building common software components (executable pro‐
grams, object files, libraries), so that for most software projects,
only the target and input files need be specified.
scons reads and executes the SConscript files as Python scripts, so you
may use normal Python scripting capabilities (such as flow control,
data manipulation, and imported Python libraries) to handle complicated
build situations. scons, however, reads and executes all of the SCon‐
script files before it begins building any targets. To make this obvi‐
ous, scons prints the following messages about what it is doing:
$ scons foo.out
scons: Reading SConscript files ...
scons: done reading SConscript files.
scons: Building targets ...
cp foo.in foo.out
scons: done building targets.
$
The status messages (everything except the line that reads "cp
foo.in foo.out") may be suppressed using the -Q option.
scons does not automatically propagate the external environment
used to execute scons to the commands used to build target
files. This is so that builds will be guaranteed repeatable
regardless of the environment variables set at the time scons is
invoked. This also means that if the compiler or other commands
that you want to use to build your target files are not in stan‐
dard system locations, scons will not find them unless you
explicitly set the PATH to include those locations. Whenever
you create an scons construction environment, you can propagate
the value of PATH from your external environment as follows:
import os
env = Environment(ENV = {'PATH' : os.environ['PATH']})
scons can scan known input files automatically for depen‐
dency information (for example, #include statements in C
or C++ files) and will rebuild dependent files appropri‐
ately whenever any "included" input file changes. scons
supports the ability to define new scanners for unknown
input file types.
scons knows how to fetch files automatically from SCCS or
RCS subdirectories using SCCS, RCS or BitKeeper.
scons is normally executed in a top-level directory con‐
taining a SConstruct file, optionally specifying as com‐
mand-line arguments the target file or files to be built.
By default, the command
scons
will build all target files in or below the cur‐
rent directory. Explicit default targets (to be
built when no targets are specified on the command
line) may be defined the SConscript file(s) using
the Default() function, described below.
Even when Default() targets are specified in the
SConscript file(s), all target files in or below
the current directory may be built by explicitly
specifying the current directory (.) as a com‐
mand-line target:
scons .
Building all target files, including any
files outside of the current directory, may
be specified by supplying a command-line
target of the root directory (on POSIX sys‐
tems):
scons /
or the path name(s) of the volume(s)
in which all the targets should be
built (on Windows systems):
scons C:\ D:\
To build only specific tar‐
gets, supply them as command-
line arguments:
scons foo bar
in which case only the
specified targets will
be built (along with
any derived files on
which they depend).
Specifying "cleanup"
targets in SConscript
files is not neces‐
sary. The -c flag
removes all files nec‐
essary to build the
specified target:
scons-c .
to remove all
target files,
or:
scons-c build export
to
remove
target
files
under
build
and
export.
Addi‐
tional
files or
directo‐
ries to
remove
can be
speci‐
fied
using
the
Clean()
func‐
tion.
A subset
of a
hierar‐
chical
tree may
be built
by
remain‐
ing at
the top-
level
direc‐
tory
(where
the
SCon‐
struct
file
lives)
and
specify‐
ing the
subdi‐
rectory
as the
target
to be
built:
scons src/subdir
or
by
chang‐
ing
direc‐
tory
and
invok‐
ing
scons
with
the
-u
option,
which
tra‐
verses
up
the
direc‐
tory
hier‐
ar‐
chy
until
it
finds
the
SCon‐
struct
file,
and
then
builds
tar‐
gets
rel‐
a‐
tively
to
the
cur‐
rent
sub‐
di‐
rec‐
tory:
cd src/subdir
scons-u .
scons
sup‐
ports
build‐
ing
mul‐
ti‐
ple
tar‐
gets
in
par‐
al‐
lel
via
a
-j
option
that
takes,
as
its
argu‐
ment,
the
num‐
ber
of
simul‐
ta‐
ne‐
ous
tasks
that
may
be
spawned:
scons-j 4
builds
four
tar‐
gets
in
par‐
al‐
lel,
for
exam‐
ple.
scons
can
main‐
tain
a
cache
of
tar‐
get
(derived)
files
that
can
be
shared
between
mul‐
ti‐
ple
builds.
When
caching
is
enabled
in
a
SCon‐
script
file,
any
tar‐
get
files
built
by
scons
will
be
copied
to
the
cache.
If
an
up-
to-
date
tar‐
get
file
is
found
in
the
cache,
it
will
be
retrieved
from
the
cache
instead
of
being
rebuilt
locally.
Caching
behav‐
ior
may
be
dis‐
abled
and
con‐
trolled
in
other
ways
by
the
--cache-
force,
--cache-
dis‐
able,
and
--cache-
show
com‐
mand-
line
options.
The
--ran‐
dom
option
is
use‐
ful
to
pre‐
vent
mul‐
ti‐
ple
builds
from
try‐
ing
to
update
the
cache
simul‐
ta‐
ne‐
ously.
Val‐
ues
of
vari‐
ables
to
be
passed
to
the
SCon‐
script
file(s)
may
be
spec‐
i‐
fied
on
the
com‐
mand
line:
scons debug=1 .
These
vari‐
ables
are
avail‐
able
in
SCon‐
script
files
through
the
ARGU‐
MENTS
dic‐
tio‐
nary,
and
can
be
used
in
the
SCon‐
script
file(s)
to
mod‐
ify
the
build
in
any
way:
if ARGUMENTS.get('debug', 0):
env = Environment(CCFLAGS = '-g')
else:
env = Environment()
The
com‐
mand-
line
vari‐
able
argu‐
ments
are
also
avail‐
able
in
the
ARGLIST
list,
indexed
by
their
order
on
the
com‐
mand
line.
This
allows
you
to
process
them
in
order
rather
than
by
name,
if
nec‐
es‐
sary.
ARGLIST[0]
returns
a
tuple
con‐
tain‐
ing
(argname,
argvalue).
A
Python
excep‐
tion
is
thrown
if
you
try
to
access
a
list
mem‐
ber
that
does
not
exist.
scons
requires
Python
ver‐
sion
1.5.2
or
later.
There
should
be
no
other
depen‐
den‐
cies
or
require‐
ments
to
run
scons.
By
default,
scons
knows
how
to
search
for
avail‐
able
pro‐
gram‐
ming
tools
on
var‐
i‐
ous
sys‐
tems.
On
WIN32
sys‐
tems,
scons
searches
in
order
for
the
Mi‐
cro‐
soft
Vis‐
ual
C++
tools,
the
MinGW
tool
chain,
the
Intel
com‐
piler
tools,
and
the
Phar‐
Lap
ETS
com‐
piler.
On
OS/2
sys‐
tems,
scons
searches
in
order
for
the
OS/2
com‐
piler,
the
GCC
tool
chain,
and
the
Mi‐
cro‐
soft
Vis‐
ual
C++
tools,
On
SGI
IRIX,
IBM
AIX,
Hewlett
Packard
HP-
UX,
and
Sun
Solaris
sys‐
tems,
scons
searches
for
the
native
com‐
piler
tools
(MIP‐
Spro,
Vis‐
ual
Age,
aCC,
and
Forte
tools
respec‐
tively)
and
the
GCC
tool
chain.
On
all
other
plat‐
forms,
includ‐
ing
POSIX
(Linux
and
UNIX)
plat‐
forms,
scons
searches
in
order
for
the
GCC
tool
chain,
the
Mi‐
cro‐
soft
Vis‐
ual
C++
tools,
and
the
Intel
com‐
piler
tools.
You
may,
of
course,
over‐
ride
these
default
val‐
ues
by
appro‐
pri‐
ate
con‐
fig‐
u‐
ra‐
tion
of
Envi‐
ron‐
ment
con‐
struc‐
tion
vari‐
ables.
OPTIONS
In general, scons supports the same command-line options as GNU make,
and many of those supported by cons.
-b Ignored for compatibility with non-GNU versions of make.
-c, --clean, --remove
Clean up by removing all target files for which a construction
command is specified. Also remove any files or directories
associated to the construction command using the Clean() func‐
tion.
--cache-disable, --no-cache
Disable the derived-file caching specified by CacheDir(). scons
will neither retrieve files from the cache nor copy files to the
cache.
--cache-force, --cache-populate
When using CacheDir(), populate a cache by copying any already-
existing, up-to-date derived files to the cache, in addition to
files built by this invocation. This is useful to populate a
new cache with all the current derived files, or to add to the
cache any derived files recently built with caching disabled via
the --cache-disable option.
--cache-show
When using CacheDir() and retrieving a derived file from the
cache, show the command that would have been executed to build
the file, instead of the usual report, "Retrieved `file' from
cache." This will produce consistent output for build logs,
regardless of whether a target file was rebuilt or retrieved
from the cache.
-C directory, --directory=directory
Change to the specified directory before searching for the SCon‐
struct, Sconstruct, or sconstruct file, or doing anything else.
Multiple -C options are interpreted relative to the previous
one, and the right-most -C option wins. (This option is nearly
equivalent to -f directory/SConstruct, except that it will
search for SConstruct, Sconstruct, or sconstruct in the speci‐
fied directory.)
-D Works exactly the same way as the -u option except for the way
default targets are handled. When this option is used and no
targets are specified on the command line, all default targets
are built, whether or not they are below the current directory.
--debug=type
Debug the build process. type specifies what type of debugging:
--debug=count
Print a count of how many objects are created of the various
classes used internally by SCons. This only works when run
under Python 2.1 or later.
--debug=dtree
Print the dependency tree after each top-level target is built.
This prints out only derived files.
--debug=includes
Print the include tree after each top-level target is built.
This is generally used to find out what files are included by
the sources of a given derived file:
$ scons --debug=includes foo.o
--debug=memory
Prints how much memory SCons uses before and after read‐
ing the SConscript files and before and after building.
--debug=objects
Prints a list of the various objects of the various
classes used internally by SCons. This only works when
run under Python 2.1 or later.
--debug=pdb
Re-run SCons under the control of the pdb Python debug‐
ger.
--debug=presub
Print the raw command line used to build each target
before the construction environment variables are substi‐
tuted. Also shows which targets are being built by this
command. Output looks something like this:
$ scons --debug=presub
Building myprog.o with action(s):
$SHCC $SHCCFLAGS $CPPFLAGS $_CPPINCFLAGS -c -o $TARGET $SOURCES
--debug=time
Prints various time profiling information: the
time spent executing each build command, the total
build time, the total time spent executing build
commands, the total time spent executing SCon‐
struct and SConscript files, and the total time
spent executing SCons itself.
--debug=tree
Print the dependency tree after each top-level
target is built. This prints out the complete
dependency tree including implicit dependencies
and ignored dependencies.
-f file, --file=file, --makefile=file, --sconstruct=file
Use file as the initial SConscript file.
-h, --help
Print a local help message for this build, if one
is defined in the SConscript file(s), plus a line
that describes the -H option for command-line
option help. If no local help message is defined,
prints the standard help message about command-
line options. Exits after displaying the appro‐
priate message.
-H, --help-options
Print the standard help message about command-line
options and exit.
-i, --ignore-errors
Ignore all errors from commands executed to
rebuild files.
-I directory, --include-dir=directory
Specifies a directory to search for imported
Python modules. If several -I options are used,
the directories are searched in the order speci‐
fied.
--implicit-cache
Cache implicit dependencies. This can cause scons
to miss changes in the implicit dependencies in
cases where a new implicit dependency is added
earlier in the implicit dependency search path
(e.g. CPPPATH) than a current implicit dependency
with the same name.
--implicit-deps-changed
Force SCons to ignore the cached implicit depen‐
dencies. This causes the implicit dependencies to
be rescanned and recached. This implies
--implicit-cache.
--implicit-deps-unchanged
Force SCons to ignore changes in the implicit
dependencies. This causes cached implicit depen‐
dencies to always be used. This implies
--implicit-cache.
-j N, --jobs=N
Specifies the number of jobs (commands) to run
simultaneously. If there is more than one -j
option, the last one is effective.
-k, --keep-going
Continue as much as possible after an error. The
target that failed and those that depend on it
will not be remade, but other targets specified on
the command line will still be processed.
--duplicate=ORDER
There are three ways to duplicate files in a build
tree: hard links, soft (symbolic) links and
copies. The default behaviour of SCons is to pre‐
fer hard links to soft links to copies. You can
specify different behaviours with this option.
ORDER must be one of hard-soft-copy (the default),
soft-hard-copy, hard-copy, soft-copy or copy.
SCons will attempt to duplicate files using the
mechanisms in the specified order.
-m Ignored for compatibility with non-GNU versions of
make.
--max-drift=SECONDS
Set the maximum expected drift in the modification
time of files to SECONDS. This value determines
how old a file must be before its content signa‐
ture is cached. The default value is 2 days, which
means a file must have a modification time of at
least two days ago in order to have its content
signature cached. A negative value means to never
cache the content signature and to ignore the
cached value if there already is one. A value of 0
means to always cache the signature, no matter how
old the file is.
-n, --just-print, --dry-run, --recon
No execute. Print the commands that would be exe‐
cuted to build any out-of-date target files, but
do not execute the commands.
--profile=file
Run SCons under the Python profiler and save the
results in the specified file. The results may be
analyzed using the Python pstats module.
-q, --question
Do not run any commands, or print anything. Just
return an exit status that is zero if the speci‐
fied targets are already up to date, non-zero oth‐
erwise.
-Q Quiets SCons status messages about reading SCon‐
script files, building targets and entering direc‐
tories. Commands that are executed to rebuild
target files are still printed.
--random
Build dependencies in a random order. This is
useful when building multiple trees simultaneously
with caching enabled, to prevent multiple builds
from simultaneously trying to build or retrieve
the same target files.
-s, --silent, --quiet
Silent. Do not print commands that are executed
to rebuild target files. Also suppresses SCons
status messages.
-S, --no-keep-going, --stop
Ignored for compatibility with GNU make.
-t, --touch
Ignored for compatibility with GNU make. (Touch‐
ing a file to make it appear up-to-date is unnec‐
essary when using scons.)
-u, --up, --search-up
Walks up the directory structure until an SCon‐
struct , Sconstruct or sconstruct file is found,
and uses that as the top of the directory tree.
If no targets are specified on the command line,
only targets at or below the current directory
will be built.
-U Works exactly the same way as the -u option except
for the way default targets are handled. When
this option is used and no targets are specified
on the command line, all default targets that are
defined in the SConscript(s) in the current direc‐
tory are built, regardless of what directory the
resultant targets end up in.
-v, --version
Print the scons version, copyright information,
list of authors, and any other relevant informa‐
tion. Then exit.
-w, --print-directory
Print a message containing the working directory
before and after other processing.
--warn=type, --warn=no-type
Enable or disable warnings. type specifies the
type of warnings to be enabled or disabled:
--warn=all, --warn=no-all
Enables or disables all warnings.
--warn=dependency, --warn=no-dependency
Enables or disables warnings about dependencies.
These warnings are disabled by default.
--warn=deprecated, --warn=no-deprecated
Enables or disables warnings about use of depre‐
cated features. These warnings are enabled by
default.
--warn=missing-sconscript, --warn=no-missing-sconscript
Enables or disables warnings about missing SCon‐
script files. These warnings are enabled by
default.
--no-print-directory
Turn off -w, even if it was turned on implicitly.
-Y repository, --repository=repository
Search the specified repository for any input and
target files not found in the local directory
hierarchy. Multiple -Y options may specified, in
which case the repositories are searched in the
order specified.
CONFIGURATION FILE REFERENCE
Construction Environments
A construction environment is the basic means by which the SConscript
files communicate build information to scons. A new construction envi‐
ronment is created using the Environment function:
env = Environment()
By default, a new construction environment is initialized with a
set of builder methods and construction variables that are
appropriate for the current platform. An optional platform key‐
word argument may be used to specify that an environment should
be initialized for a different platform:
env = Environment(platform = 'cygwin')
env = Environment(platform = 'os2')
env = Environment(platform = 'posix')
env = Environment(platform = 'win32')
Specifying a platform initializes the appropriate con‐
struction variables in the environment to use and gener‐
ate file names with prefixes and suffixes appropriate for
the platform.
Note that the win32 platform adds the SYSTEMROOT variable
from the user's external environment to the construction
environment's ENV dictionary. This is so that any exe‐
cuted commands that use sockets to connect with other
systems (such as fetching source files from external CVS
repository specifications like :pserver:anony‐
mous@cvs.sourceforge.net:/cvsroot/scons) will work on
Win32 systems.
The platform argument may be function or callable object,
in which case the Environment() method will call the
specified argument to update the new construction envi‐
ronment:
def my_platform(env):
env['VAR'] = 'xyzzy'
env = Environment(platform = my_platform)
Additionally, a specific set of tools with which
to initialize the environment may specified as an
optional keyword argument:
env = Environment(tools = ['msvc', 'lex'])
Non-built-in tools may be specified using
the toolpath argument:
env = Environment(tools = ['default', 'foo'], toolpath = ['tools'])
This looks for a tool specification
in tools/foo.py (as well as using
the ordinary default tools for the
platform). foo.py should have two
functions: generate(env) and
exists(env). generate() modifies
the passed in environment and
exists() should return a true value
if the tool is available. Tools in
the toolpath are used before any of
the built-in ones. For example,
adding gcc.py to the toolpath would
override the built-in gcc tool.
The elements of the tools list may
also be functions or callable
objects, in which case the Environ‐
ment() method will call the speci‐
fied elements to update the new con‐
struction environment:
def my_tool(env):
env['XYZZY'] = 'xyzzy'
env = Environment(tools = [my_tool])
The tool definition (i.e.
my_tool()) can use the PLAT‐
FORM variable from the envi‐
ronment it receives to cus‐
tomize the tool for different
platforms.
If no tool list is specified,
then SCons will auto-detect
the installed tools using the
PATH variable in the ENV con‐
struction variable and the
platform name when the Envi‐
ronment is constructed.
Changing the PATH variable
after the Environment is con‐
structed will not cause the
tools to be redetected.
SCons supports the following
tool specifications out of
the box:
386asm
aixc++
aixcc
aixf77
aixlink
ar
as
bcc32
c++
cc
cvf
dmd
dvipdf
dvips
f77
f90
f95
fortran
g++
g77
gas
gcc
gnulink
gs
hpc++
hpcc
hplink
icc
icl
ifl
ifort
ilink
ilink32
jar
javac
javah
latex
lex
link
linkloc
m4
masm
midl
mingw
mslib
mslink
msvc
msvs
nasm
pdflatex
pdftex
qt
rmic
sgiar
sgic++
sgicc
sgilink
sunar
sunc++
suncc
sunlink
swig
tar
tex
tlib
yacc
zip
Additionally, there is
a "tool" named default
which configures the
environment with a
default set of tools
for the current plat‐
form.
On posix and cygwin
platforms the GNU
tools (e.g. gcc) are
preferred by SCons, on
win32 the Microsoft
tools (e.g. msvc) fol‐
lowed by MinGW are
preferred by SCons,
and in OS/2 the IBM
tools (e.g. icc) are
preferred by SCons.
Builder Methods
Build rules are specified by calling a construction environment's
builder methods. The arguments to the builder methods are target (a
list of target files) and source (a list of source files).
Because long lists of file names can lead to a lot of quoting, scons
supplies a Split() global function and a same-named environment method
that split a single string into a list, separated on strings of white-
space characters. (These are similar to the string.split() method from
the standard Python library, but work even if the input isn't a
string.)
Like all Python arguments, the target and source arguments to a builder
method can be specified either with or without the "target" and
"source" keywords. When the keywords are omitted, the target is first,
followed by the source. The following are equivalent examples of call‐
ing the Program builder method:
env.Program('bar', ['bar.c', 'foo.c'])
env.Program('bar', Split('bar.c foo.c'))
env.Program('bar', env.Split('bar.c foo.c'))
env.Program(source = ['bar.c', 'foo.c'], target = 'bar')
env.Program(target = 'bar', Split('bar.c foo.c'))
env.Program(target = 'bar', env.Split('bar.c foo.c'))
env.Program('bar', source = string.split('bar.c foo.c'))
When the target shares the same base name as the source and only
the suffix varies, and if the builder method has a suffix
defined for the target file type, then the target argument may
be omitted completely, and scons will deduce the target file
name from the source file name. The following examples all
build the executable program bar (on POSIX systems) or bar.exe
(on Windows systems) from the bar.c source file:
env.Program(target = 'bar', source = 'bar.c')
env.Program('bar', source = 'bar.c')
env.Program(source = 'bar.c')
env.Program('bar.c')
It is possible to override or add construction variables
when calling a builder method by passing additional key‐
word 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:
env.Program('hello', 'hello.c', LIBS=['gl', 'glut'])
or generate a shared library with a nonstandard
suffix:
env.SharedLibrary('word', 'word.cpp', SHLIBSUFFIX='.ocx')
Although the builder methods defined by
scons are, in fact, methods of a construc‐
tion environment object, they may also be
called without an explicit environment:
Program('hello', 'hello.c')
SharedLibrary('word', 'word.cpp')
In this case, the methods are called
internally using a default construc‐
tion environment that consists of
the tools and values that scons has
determined are appropriate for the
local system.
All builder methods return a list of
Nodes that represent the target or
targets that will be built. A Node
is an internal SCons object which
represents build targets or sources.
The returned Node(s) can be passed
to other builder methods as
source(s) or passed to any SCons
function or method where a filename
would normally be accepted. For
example, if it were necessary to add
a specific -D flag when compiling
one specific object file:
bar_obj_list = env.StaticObject('bar.c', CCFLAGS='-DBAR')
env.Program(source = ['foo.c', bar_obj_list, 'main.c'])
Using a Node in this way
makes for a more portable
build by avoiding having to
specify a platform-specific
object suffix when calling
the Program() builder method.
Note that Builder calls will
automatically "flatten" the
source and target file lists,
so it's all right to have the
bar_obj list return by the
StaticObject() call in the
middle of the source file
list. If you need to manipu‐
late a list of lists returned
by Builders directly using
Python, you can either build
the list by hand:
foo = Object('foo.c')
bar = Object('bar.c')
objects = ['begin.o'] + foo + ['middle.o'] + bar + ['end.o']
for object in objects:
print str(object)
Or you can use the
Flatten() supplied by
scons to create a list
containing just the
Nodes, which may be
more convenient:
foo = Object('foo.c')
bar = Object('bar.c')
objects = Flatten(['begin.o', foo, 'middle.o', bar, 'end.o'])
for object in objects:
print str(object)
The path name
for a Node's
file may be
used by passing
the Node to the
Python-builtin
str() function:
bar_obj_list = env.StaticObject('bar.c', CCFLAGS='-DBAR')
print "The path to bar_obj is:", str(bar_obj_list[0])
Note
again
that
because
the
Builder
call
returns
a list,
we have
to
access
the
first
element
in the
list
(bar_obj_list[0])
to get
at the
Node
that
actually
repre‐
sents
the
object
file.
scons
provides
the fol‐
lowing
builder
methods:
CFile()env.CFile()
Builds
a
C
source
file
given
a
lex
(.l)
or
yacc
(.y)
input
file.
The
suf‐
fix
spec‐
i‐
fied
by
the
$CFILE‐
SUF‐
FIX
con‐
struc‐
tion
vari‐
able
(.c
by
default)
is
auto‐
mat‐
i‐
cally
added
to
the
tar‐
get
if
it
is
not
already
present.
Exam‐
ple:
# builds foo.c
env.CFile(target = 'foo.c', source = 'foo.l')
# builds bar.c
env.CFile(target = 'bar', source = 'bar.y')
CXXFile()env.CXXFile()
Builds
a
C++
source
file
given
a
lex
(.ll)
or
yacc
(.yy)
input
file.
The
suf‐
fix
spec‐
i‐
fied
by
the
$CXXFILE‐
SUF‐
FIX
con‐
struc‐
tion
vari‐
able
(.cc
by
default)
is
auto‐
mat‐
i‐
cally
added
to
the
tar‐
get
if
it
is
not
already
present.
Exam‐
ple:
# builds foo.cc
env.CXXFile(target = 'foo.cc', source = 'foo.ll')
# builds bar.cc
env.CXXFile(target = 'bar', source = 'bar.yy')
DVI()env.DVI()
Builds
a
.dvi
file
from
a
.tex,
.ltx
or
.latex
input
file.
If
the
source
file
suf‐
fix
is
.tex,
scons
will
exam‐
ine
the
con‐
tents
of
the
file;
if
the
string
ocu‐
ment‐
class
or
ocu‐
mentstyle
is
found,
the
file
is
assumed
to
be
a
LaTeX
file
and
the
tar‐
get
is
built
by
invok‐
ing
the
$LATEX‐
COM
com‐
mand
line;
oth‐
er‐
wise,
the
$TEX‐
COM
com‐
mand
line
is
used.
If
the
file
is
a
LaTeX
file,
the
DVI
builder
method
will
also
exam‐
ine
the
con‐
tents
of
the
.aux
file
and
invoke
the
$BIB‐
TEX
com‐
mand
line
if
the
string
bib‐
data
is
found,
and
will
exam‐
ine
the
con‐
tents
.log
file
and
re-
run
the
$LATEX‐
COM
com‐
mand
if
the
log
file
says
it
is
nec‐
es‐
sary.
The
suf‐
fix
.dvi
(hard-
coded
within
TeX
itself)
is
auto‐
mat‐
i‐
cally
added
to
the
tar‐
get
if
it
is
not
already
present.
Exam‐
ples:
# 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')
Jar()env.Jar()
Builds
a
Java
ar‐
chive
(.jar)
file
from
a
source
tree
of
.class
files.
If
the
$JARCHDIR
value
is
set,
the
jar
com‐
mand
will
change
to
the
spec‐
i‐
fied
direc‐
tory
using
the
-C
option.
If
the
con‐
tents
any
of
the
source
files
begin
with
the
string
Man‐
i‐
fest-
Ver‐
sion,
the
file
is
assumed
to
be
a
man‐
i‐
fest
and
is
passed
to
the
jar
com‐
mand
with
the
m
option
set.
env.Jar(target = 'foo.jar', source = 'classes')
Java()env.Java()
Builds
one
or
more
Java
class
files
from
one
or
more
source
trees
of
.java
files.
The
class
files
will
be
placed
under‐
neath
the
spec‐
i‐
fied
tar‐
get
direc‐
tory.
SCons
will
parse
each
source
.java
file
to
find
the
classes
(includ‐
ing
inner
classes)
defined
within
that
file,
and
from
that
fig‐
ure
out
the
tar‐
get
.class
files
that
will
be
cre‐
ated.
SCons
will
also
search
each
Java
file
for
the
Java
pack‐
age
name,
which
it
assumes
can
be
found
on
a
line
begin‐
ning
with
the
string
pack‐
age
in
the
first
col‐
umn;
the
result‐
ing
.class
files
will
be
placed
in
a
direc‐
tory
reflect‐
ing
the
spec‐
i‐
fied
pack‐
age
name.
For
exam‐
ple,
the
file
Foo.java
defin‐
ing
a
sin‐
gle
pub‐
lic
Foo
class
and
con‐
tain‐
ing
a
pack‐
age
name
of
sub.dir
will
gen‐
er‐
ate
a
cor‐
re‐
spond‐
ing
sub/dir/Foo.class
class
file.
Exam‐
ple:
env.Java(target = 'classes', source = 'src')
env.Java(target = 'classes', source = ['src1', 'src2'])
JavaH()env.JavaH()
Builds
C
header
and
source
files
for
imple‐
ment‐
ing
Java
native
meth‐
ods.
The
tar‐
get
can
be
either
a
direc‐
tory
in
which
the
header
files
will
be
writ‐
ten,
or
a
header
file
name
which
will
con‐
tain
all
of
the
def‐
i‐
ni‐
tions.
The
source
can
be
either
the
names
of
.class
files,
or
the
objects
returned
from
the
Java
builder
method.
If
the
con‐
struc‐
tion
vari‐
able
JAVA‐
CLASS‐
DIR
is
set,
either
in
the
envi‐
ron‐
ment
or
in
the
call
to
the
JavaH
builder
method
itself,
then
the
value
of
the
vari‐
able
will
be
stripped
from
the
begin‐
ning
of
any
.class
file
names.
Exam‐
ples:
# 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')
Library()env.Library()
A
syn‐
onym
for
the
Stat‐
i‐
cLi‐
brary
builder
method.
M4()env.M4()
Builds
an
out‐
put
file
from
an
M4
input
file.
This
uses
a
default
$M4FLAGS
value
of
-E,
which
con‐
sid‐
ers
all
warn‐
ings
to
be
fatal
and
stops
on
the
first
warn‐
ing
when
using
the
GNU
ver‐
sion
of
m4.
Exam‐
ple:
env.M4(target = 'foo.c', source = 'foo.c.m4')
Moc()env.Moc()
Builds
an
out‐
put
file
from
a
moc
input
file.
Moc
input
files
are
either
header
files
or
cxx
files.
This
builder
is
only
avail‐
able
after
using
the
tool
'qt'.
See
the
QTDIR
vari‐
able
for
more
infor‐
ma‐
tion.
Exam‐
ple:
env.Moc('foo.h') # generates moc_foo.cc
env.Moc('foo.cpp') # generates foo.moc
MSVSPro‐
ject()
env.MSVSPro‐
ject()
Builds
Mi‐
cro‐
soft
Vis‐
ual
Stu‐
dio
project
files.
This
builds
a
Vis‐
ual
Stu‐
dio
project
file,
based
on
the
ver‐
sion
of
Vis‐
ual
Stu‐
dio
that
is
con‐
fig‐
ured
(either
the
lat‐
est
installed
ver‐
sion,
or
the
ver‐
sion
set
by
MSVS_VER‐
SION
in
the
Envi‐
ron‐
ment
con‐
struc‐
tor).
For
VS
6,
it
will
gen‐
er‐
ate
.dsp
and
.dsw
files,
for
VS
7,
it
will
gen‐
er‐
ate
.vcproj
and
.sln
files.
It
takes
sev‐
eral
lists
of
file‐
names
to
be
placed
into
the
project
file,
cur‐
rently
these
are
lim‐
ited
to
srcs,
incs,
local‐
incs,
resources,
and
misc.
These
are
pretty
self
explana‐
tory,
but
it
should
be
noted
that
the
'srcs'
list
is
NOT
added
to
the
$SOURCES
envi‐
ron‐
ment
vari‐
able.
This
is
because
it
rep‐
re‐
sents
a
list
of
files
to
be
added
to
the
project
file,
not
the
source
used
to
build
the
project
file
(in
this
case,
the
'source'
is
the
SCon‐
script
file
used
to
call
MSVSPro‐
ject).
In
addi‐
tion
to
these
val‐
ues
(which
are
all
optional,
although
not
spec‐
i‐
fy‐
ing
any
of
them
results
in
an
empty
project
file),
the
fol‐
low‐
ing
val‐
ues
must
be
spec‐
i‐
fied:
tar‐
get:
The
name
of
the
tar‐
get
.dsp
or
.vcproj
file.
The
cor‐
rect
suf‐
fix
for
the
ver‐
sion
of
Vis‐
ual
Stu‐
dio
must
be
used,
but
the
value
env['MSVSPRO‐
JECT‐
SUF‐
FIX']
will
be
defined
to
the
cor‐
rect
value
(see
exam‐
ple
below).
vari‐
ant:
The
name
of
this
par‐
tic‐
u‐
lar
vari‐
ant.
These
are
typ‐
i‐
cally
things
like
"Debug"
or
"Release",
but
really
can
be
any‐
thing
you
want.
Mul‐
ti‐
ple
calls
to
MSVSPro‐
ject
with
dif‐
fer‐
ent
vari‐
ants
are
allowed:
all
vari‐
ants
will
be
added
to
the
project
file
with
their
appro‐
pri‐
ate
build
tar‐
gets
and
sources.
build‐
tar‐
get:
A
list
of
SCons.Node.FS
objects
which
is
returned
from
the
com‐
mand
which
builds
the
tar‐
get.
This
is
used
to
tell
SCons
what
to
build
when
the
'build'
but‐
ton
is
pressed
inside
of
the
IDE.
Exam‐
ple
Usage:
barsrcs = ['bar.cpp'],
barincs = ['bar.h'],
barlocalincs = ['StdAfx.h']
barresources = ['bar.rc','resource.h']
barmisc = ['bar_readme.txt']
dll = local.SharedLibrary(target = 'bar.dll',
source = barsrcs)
local.MSVSProject(target = 'Bar' + env['MSVSPROJECTSUFFIX'],
srcs = barsrcs,
incs = barincs,
localincs = barlocalincs,
resources = barresources,
misc = barmisc,
buildtarget = dll,
variant = 'Release')
Object()env.Object()
A
syn‐
onym
for
the
Stati‐
cOb‐
ject
builder
method.
PCH()env.PCH()
Builds
a
Mi‐
cro‐
soft
Vis‐
ual
C++
pre‐
com‐
piled
header.
Call‐
ing
this
builder
method
returns
a
list
of
two
tar‐
gets:
the
PCH
as
the
first
ele‐
ment,
and
the
object
file
as
the
sec‐
ond
ele‐
ment.
Nor‐
mally
the
object
file
is
ignored.
This
builder
method
is
only
pro‐
vided
when
Mi‐
cro‐
soft
Vis‐
ual
C++
is
being
used
as
the
com‐
piler.
The
PCH
builder
method
is
gen‐
er‐
ally
used
in
con‐
juc‐
tion
with
the
PCH
con‐
struc‐
tion
vari‐
able
to
force
object
files
to
use
the
pre‐
com‐
piled
header:
env['PCH'] = env.PCH('StdAfx.cpp')[0]
PDF()env.PDF()
Builds
a
.pdf
file
from
a
.dvi
input
file
(or,
by
exten‐
sion,
a
.tex,
.ltx,
or
.latex
input
file).
The
suf‐
fix
spec‐
i‐
fied
by
the
$PDF‐
SUF‐
FIX
con‐
struc‐
tion
vari‐
able
(.pdf
by
default)
is
added
auto‐
mat‐
i‐
cally
to
the
tar‐
get
if
it
is
not
already
present.
Exam‐
ple:
# 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')
Post‐
Script()
env.Post‐
Script()
Builds
a
.ps
file
from
a
.dvi
input
file
(or,
by
exten‐
sion,
a
.tex,
.ltx,
or
.latex
input
file).
The
suf‐
fix
spec‐
i‐
fied
by
the
$PSSUF‐
FIX
con‐
struc‐
tion
vari‐
able
(.ps
by
default)
is
added
auto‐
mat‐
i‐
cally
to
the
tar‐
get
if
it
is
not
already
present.
Exam‐
ple:
# 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')
Pro‐
gram()
env.Pro‐
gram()
Builds
an
exe‐
cutable
given
one
or
more
object
files
or
C,
C++,
D,
or
For‐
tran
source
files.
If
any
C,
C++,
D
or
For‐
tran
source
files
are
spec‐
i‐
fied,
then
they
will
be
auto‐
mat‐
i‐
cally
com‐
piled
to
object
files
using
the
Object
builder
method;
see
that
builder
method's
descrip‐
tion
for
a
list
of
legal
source
file
suf‐
fixes
and
how
they
are
inter‐
preted.
The
tar‐
get
exe‐
cutable
file
pre‐
fix
(spec‐
i‐
fied
by
the
$PROG‐
PRE‐
FIX
con‐
struc‐
tion
vari‐
able;
noth‐
ing
by
default)
and
suf‐
fix
(spec‐
i‐
fied
by
the
$PROG‐
SUF‐
FIX
con‐
struc‐
tion
vari‐
able;
by
default,
.exe
on
Win‐
dows
sys‐
tems,
noth‐
ing
on
POSIX
sys‐
tems)
are
auto‐
mat‐
i‐
cally
added
to
the
tar‐
get
if
not
already
present.
Exam‐
ple:
env.Program(target = 'foo', source = ['foo.o', 'bar.c', 'baz.f'])
RES()env.RES()
Builds
a
Mi‐
cro‐
soft
Vis‐
ual
C++
resource
file.
This
builder
method
is
only
pro‐
vided
when
Mi‐
cro‐
soft
Vis‐
ual
C++
or
MinGW
is
being
used
as
the
com‐
piler.
The
.res
(or
.o
for
MinGW)
suf‐
fix
is
added
to
the
tar‐
get
name
if
no
other
suf‐
fix
is
given.
The
source
file
is
scanned
for
implicit
depen‐
den‐
cies
as
though
it
were
a
C
file.
Exam‐
ple:
env.RES('resource.rc')
RMIC()env.RMIC()
Builds
stub
and
skele‐
ton
class
files
for
remote
objects
from
Java
.class
files.
The
tar‐
get
is
a
direc‐
tory
rel‐
a‐
tive
to
which
the
stub
and
skele‐
ton
class
files
will
be
writ‐
ten.
The
source
can
be
the
names
of
.class
files,
or
the
objects
return
from
the
Java
builder
method.
If
the
con‐
struc‐
tion
vari‐
able
JAVA‐
CLASS‐
DIR
is
set,
either
in
the
envi‐
ron‐
ment
or
in
the
call
to
the
RMIC
builder
method
itself,
then
the
value
of
the
vari‐
able
will
be
stripped
from
the
begin‐
ning
of
any
.class
file
names.
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')
SharedLi‐
brary()
env.SharedLi‐
brary()
Builds
a
shared
library
(.so
on
a
POSIX
sys‐
tem,
.dll
on
WIN32)
given
one
or
more
object
files
or
C,
C++,
D
or
For‐
tran
source
files.
If
any
source
files
are
given,
then
they
will
be
auto‐
mat‐
i‐
cally
com‐
piled
to
object
files.
The
static
library
pre‐
fix
and
suf‐
fix
(if
any)
are
auto‐
mat‐
i‐
cally
added
to
the
tar‐
get.
The
tar‐
get
library
file
pre‐
fix
(spec‐
i‐
fied
by
the
$SHLIBPRE‐
FIX
con‐
struc‐
tion
vari‐
able;
by
default,
lib
on
POSIX
sys‐
tems,
noth‐
ing
on
Win‐
dows
sys‐
tems)
and
suf‐
fix
(spec‐
i‐
fied
by
the
$SHLIB‐
SUF‐
FIX
con‐
struc‐
tion
vari‐
able;
by
default,
.dll
on
Win‐
dows
sys‐
tems,
.so
on
POSIX
sys‐
tems)
are
auto‐
mat‐
i‐
cally
added
to
the
tar‐
get
if
not
already
present.
Exam‐
ple:
env.SharedLibrary(target = 'bar', source = ['bar.c', 'foo.o'])
On
WIN32
sys‐
tems,
the
SharedLi‐
brary
builder
method
will
always
build
an
import
(.lib)
library
in
addi‐
tion
to
the
shared
(.dll)
library,
adding
a
.lib
library
with
the
same
base‐
name
if
there
is
not
already
a
.lib
file
explic‐
itly
listed
in
the
tar‐
gets.
Any
object
files
listed
in
the
source
must
have
been
built
for
a
shared
library
(that
is,
using
the
Share‐
dOb‐
ject
builder
method).
scons
will
raise
an
error
if
there
is
any
mis‐
match.
On
WIN32
sys‐
tems,
spec‐
i‐
fy‐
ing
"reg‐
is‐
ter=1"
will
cause
the
dll
to
be
reg‐
is‐
tered
after
it
is
built
using
REGSVR32.
The
com‐
mand
that
is
run
("regsvr32"
by
default)
is
deter‐
mined
by
$REGSVR
con‐
struc‐
tion
vari‐
able,
and
the
flags
passed
are
deter‐
mined
by
$REGSVR‐
FLAGS.
By
default,
$REGSVR‐
FLAGS
includes
"/s",
to
pre‐
vent
dialogs
from
pop‐
ping
up
and
requir‐
ing
user
atten‐
tion
when
it
is
run.
If
you
change
$REGSVR‐
FLAGS,
be
sure
to
include
"/s".
For
exam‐
ple,
env.SharedLibrary(target = 'bar',
source = ['bar.cxx', 'foo.obj'],
register=1)
will
reg‐
is‐
ter
"bar.dll"
as
a
COM
object
when
it
is
done
link‐
ing
it.
Share‐
dOb‐
ject()
env.Share‐
dOb‐
ject()
Builds
an
object
file
for
inclu‐
sion
in
a
shared
library.
Source
files
must
have
one
of
the
same
set
of
exten‐
sions
spec‐
i‐
fied
above
for
the
Stati‐
cOb‐
ject
builder
method.
On
some
plat‐
forms
build‐
ing
a
shared
object
requires
addi‐
tional
com‐
piler
options
(e.g.
-fPIC
for
gcc)
in
addi‐
tion
to
those
needed
to
build
a
nor‐
mal
(static)
object,
but
on
some
plat‐
forms
there
is
no
dif‐
fer‐
ence
between
a
shared
object
and
a
nor‐
mal
(static)
one.
When
there
is
a
dif‐
fer‐
ence,
SCons
will
only
allow
shared
objects
to
be
linked
into
a
shared
library,
and
will
use
a
dif‐
fer‐
ent
suf‐
fix
for
shared
objects.
On
plat‐
forms
where
there
is
no
dif‐
fer‐
ence,
SCons
will
allow
both
nor‐
mal
(static)
and
shared
objects
to
be
linked
into
a
shared
library,
and
will
use
the
same
suf‐
fix
for
shared
and
nor‐
mal
(static)
objects.
The
tar‐
get
object
file
pre‐
fix
(spec‐
i‐
fied
by
the
$SHOB‐
JPRE‐
FIX
con‐
struc‐
tion
vari‐
able;
by
default,
the
same
as
$OBJPRE‐
FIX)
and
suf‐
fix
(spec‐
i‐
fied
by
the
$SHOB‐
J‐
SUF‐
FIX
con‐
struc‐
tion
vari‐
able)
are
auto‐
mat‐
i‐
cally
added
to
the
tar‐
get
if
not
already
present.
Exam‐
ples:
env.SharedObject(target = 'ddd', source = 'ddd.c')
env.SharedObject(target = 'eee.o', source = 'eee.cpp')
env.SharedObject(target = 'fff.obj', source = 'fff.for')
Stat‐
i‐
cLi‐
brary()
env.Stat‐
i‐
cLi‐
brary()
Builds
a
static
library
given
one
or
more
object
files
or
C,
C++,
D
or
For‐
tran
source
files.
If
any
source
files
are
given,
then
they
will
be
auto‐
mat‐
i‐
cally
com‐
piled
to
object
files.
The
static
library
pre‐
fix
and
suf‐
fix
(if
any)
are
auto‐
mat‐
i‐
cally
added
to
the
tar‐
get.
The
tar‐
get
library
file
pre‐
fix
(spec‐
i‐
fied
by
the
$LIBPRE‐
FIX
con‐
struc‐
tion
vari‐
able;
by
default,
lib
on
POSIX
sys‐
tems,
noth‐
ing
on
Win‐
dows
sys‐
tems)
and
suf‐
fix
(spec‐
i‐
fied
by
the
$LIB‐
SUF‐
FIX
con‐
struc‐
tion
vari‐
able;
by
default,
.lib
on
Win‐
dows
sys‐
tems,
.a
on
POSIX
sys‐
tems)
are
auto‐
mat‐
i‐
cally
added
to
the
tar‐
get
if
not
already
present.
Exam‐
ple:
env.StaticLibrary(target = 'bar', source = ['bar.c', 'foo.o'])
Any
object
files
listed
in
the
source
must
have
been
built
for
a
static
library
(that
is,
using
the
Stati‐
cOb‐
ject
builder
method).
scons
will
raise
an
error
if
there
is
any
mis‐
match.
Stati‐
cOb‐
ject()
env.Stati‐
cOb‐
ject()
Builds
a
static
object
file
from
one
or
more
C,
C++,
D,
or
For‐
tran
source
files.
Source
files
must
have
one
of
the
fol‐
low‐
ing
exten‐
sions:
.asm assembly language file
.ASM assembly language file
.c C file
.C WIN32: 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 WIN32: 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
.s assembly language file
.S WIN32: assembly language file
POSIX: assembly language file + C pre-processor
.spp assembly language file + C pre-processor
.SPP assembly language file + C pre-processor
The
tar‐
get
object
file
pre‐
fix
(spec‐
i‐
fied
by
the
$OBJPRE‐
FIX
con‐
struc‐
tion
vari‐
able;
noth‐
ing
by
default)
and
suf‐
fix
(spec‐
i‐
fied
by
the
$OBJ‐
SUF‐
FIX
con‐
struc‐
tion
vari‐
able;
are
auto‐
mat‐
i‐
cally
added
to
the
tar‐
get
if
not
already
present.
Exam‐
ples:
env.StaticObject(target = 'aaa', source = 'aaa.c')
env.StaticObject(target = 'bbb.o', source = 'bbb.c++')
env.StaticObject(target = 'ccc.obj', source = 'ccc.f')
Tar()env.Tar()
Builds
a
tar
ar‐
chive
of
the
spec‐
i‐
fied
files
and/or
direc‐
to‐
ries.
Unlike
most
builder
meth‐
ods,
the
Tar
builder
method
may
be
called
mul‐
ti‐
ple
times
for
a
given
tar‐
get;
each
addi‐
tional
call
adds
to
the
list
of
entries
that
will
be
built
into
the
ar‐
chive.
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')
Type‐
Li‐
brary()
env.Type‐
Li‐
brary()
Builds
a
Win‐
dows
type
library
(.tlb)
file
from
and
input
IDL
file
(.idl).
In
addi‐
tion,
it
will
build
the
asso‐
ci‐
ated
inte‐
face
stub
and
proxy
source
files.
It
names
them
accord‐
ing
to
the
base
name
of
the
.idl
file.
For
exam‐
ple,
env.TypeLibrary(source="foo.idl")
Will
cre‐
ate
foo.tlb,
foo.h,
foo_i.c,
foo_p.c,
and
foo_data.c.
Uic()env.Uic()
Builds
a
header
file,
an
imple‐
men‐
ta‐
tion
file
and
a
moc
file
from
an
ui
file.
and
returns
the
cor‐
re‐
spond‐
ing
nodes
in
the
above
order.
This
builder
is
only
avail‐
able
after
using
the
tool
'qt'.
Note:
you
can
spec‐
ify
.ui
files
directly
as
inputs
for
Pro‐
gram,
Library
and
SharedLi‐
brary
with‐
out
using
this
builder.
Using
the
builder
lets
you
over‐
ride
the
stan‐
dard
nam‐
ing
con‐
ven‐
tions
(be
care‐
ful:
pre‐
fixes
are
always
prepended
to
names
of
built
files;
if
you
don't
want
pre‐
fixes,
you
may
set
them
to
``).
See
the
QTDIR
vari‐
able
for
more
infor‐
ma‐
tion.
Exam‐
ple:
env.Uic('foo.ui') # -> ['foo.h', 'uic_foo.cc', 'moc_foo.cc']
env.Uic(target = Split('include/foo.h gen/uicfoo.cc gen/mocfoo.cc'),
source = 'foo.ui') # -> ['include/foo.h', 'gen/uicfoo.cc', 'gen/mocfoo.cc']
Zip()env.Zip()
Builds
a
zip
ar‐
chive
of
the
spec‐
i‐
fied
files
and/or
direc‐
to‐
ries.
Unlike
most
builder
meth‐
ods,
the
Zip
builder
method
may
be
called
mul‐
ti‐
ple
times
for
a
given
tar‐
get;
each
addi‐
tional
call
adds
to
the
list
of
entries
that
will
be
built
into
the
ar‐
chive.
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')
scons
auto‐
mat‐
i‐
cally
scans
C
source
files,
C++
source
files,
For‐
tran
source
files
with
.F
(POSIX
sys‐
tems
only),
.fpp,
or
.FPP
file
exten‐
sions,
and
assem‐
bly
lan‐
guage
files
with
.S
(POSIX
sys‐
tems
only),
.spp,
or
.SPP
files
exten‐
sions
for
C
pre‐
proces‐
sor
depen‐
den‐
cies,
so
the
depen‐
den‐
cies
do
not
need
to
be
spec‐
i‐
fied
explic‐
itly.
In
addi‐
tion,
all
tar‐
gets
of
builder
meth‐
ods
auto‐
mat‐
i‐
cally
depend
on
their
sources.
An
explicit
depen‐
dency
can
be
spec‐
i‐
fied
using
the
Depends
method
of
a
con‐
struc‐
tion
envi‐
ron‐
ment
(see
below).
Methods and Functions to Do Things
In addition to Builder methods, scons provides a number of other con‐
struction environment methods and global functions to manipulate the
build configuration.
Usually, a construction environment method and global function with the
same name both exist so that you don't have to remember whether to a
specific bit of functionality must be called with or without a con‐
struction environment. In the following list, if you call something as
a global function it looks like:
Function(arguments)
and if you call something through a construction environment it
looks like:
env.Function(arguments)
If you can call the functionality in both ways, then both
forms are listed.
Except where otherwise noted, the same-named construction
environment method and global function provide the exact
same functionality. The only difference is that, where
appropriate, calling the functionality through a con‐
struction environment will substitute construction vari‐
ables into any supplied strings. For example:
env = Environment(FOO = 'foo')
Default('$FOO')
env.Default('$FOO')
the first call to the global Default() function
will actually add a target named $FOO to the list
of default targets, while the second call to the
env.Default() construction environment method will
expand the value and add a target named foo to the
list of default targets. For more on construction
variable expansion, see the next section on con‐
struction variables.
Construction environment methods and global func‐
tions supported by scons include:
Action(action, [strfunction, varlist])
env.Action(action, [strfunction, varlist])
Creates an Action object for the specified
action. See the section "Action Objects,"
below, for a complete explanation of the
arguments and behavior.
AddPostAction(target, action)
env.AddPostAction(target, action)
Arranges for the specified action to be
performed after the specified target has
been built. The specified action(s) may be
an Action object, or anything that can be
converted into an Action object (see
below).
AddPreAction(target, action)
env.AddPreAction(target, action)
Arranges for the specified action to be
performed before the specified target is
built. The specified action(s) may be an
Action object, or anything that can be con‐
verted into an Action object (see below).
Alias(alias, [targets])
env.Alias(alias, [targets])
Creates one or more phony targets that
expand to one or more other targets.
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.
Alias can be called multiple times for the
same alias to add additional targets to the
alias.
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'])
AlwaysBuild(target, ...)
env.AlwaysBuild(target, ...)
Marks each given target so that it
is always assumed to be out of date,
and will always be rebuilt if
needed. Note, however, that Always‐
Build() 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 spec‐
ified on the command line--but they
will always be built if so speci‐
fied. Multiple targets can be
passed in to a single call to
AlwaysBuild().
env.Append(key=val, [...])
Appends the specified keyword argu‐
ments 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 val‐
ues will be simply added together.
Otherwise, the construction variable
and the value of the keyword argu‐
ment are both coerced to lists, and
the lists are added together. (See
also the Prepend method, below.)
env.Append(CCFLAGS = ' -g', FOO = ['foo.yyy'])
env.AppendENVPath(name, newpath,
[envname, sep])
This appends new path ele‐
ments to the given path in
the specified external envi‐
ronment (ENV by default).
This will only add any par‐
ticular path once (leaving
the last one it encounters
and ignoring the rest, to
preserve path order), and to
help assure this, will nor‐
malize all paths (using
os.path.normpath and
os.path.normcase). 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. Example:
print 'before:',env['ENV']['INCLUDE']
include_path = '/foo/bar:/foo'
env.PrependENVPath('INCLUDE', include_path)
print 'after:',env['ENV']['INCLUDE']
yields:
before: /foo:/biz
after: /biz:/foo/bar:/foo
env.AppendUnique(key=val,
[...])
Appends the specified
keyword arguments to
the end of construc‐
tion variables in the
environment. If the
Environment does not
have the specified
construction variable,
it is simply added to
the environment. If
the construction vari‐
able being appended to
is a list, then any
value(s) that already
exist in the construc‐
tion variable will not
be added again to the
list.
env.AppendUnique(CCFLAGS = '-g', FOO = ['foo.yyy'])
env.BitKeeper()
A factory func‐
tion that
returns a
Builder object
to be used to
fetch source
files using
BitKeeper. The
returned
Builder is
intended to be
passed to the
SourceCode
function.
env.SourceCode('.', env.BitKeeper())
Build‐
Dir(build_dir,
src_dir,
[duplicate])
env.Build‐
Dir(build_dir,
src_dir,
[duplicate])
This
speci‐
fies a
build
direc‐
tory
build_dir
in which
to build
all
derived
files
that
would
normally
be built
under
src_dir.
Multiple
build
directo‐
ries can
be set
up for
multiple
build
vari‐
ants,
for
example.
src_dir
must be
under‐
neath
the
SCon‐
struct
file's
direc‐
tory,
and
build_dir
may not
be
under‐
neath
the
src_dir
.
The
default
behavior
is for
scons to
dupli‐
cate all
of the
files in
the tree
under‐
neath
src_dir
into
build_dir,
and then
build
the
derived
files
within
the
copied
tree.
(The
duplica‐
tion is
per‐
formed
by link‐
ing or
copying,
depend‐
ing on
the
plat‐
form;
see also
the
--dupli‐
cate
option.)
This
guaran‐
tees
correct
builds
regard‐
less of
whether
interme‐
diate
source
files
are gen‐
erated
during
the
build,
where
pre‐
proces‐
sors or
other
scanners
search
for
included
files,
or
whether
individ‐
ual com‐
pilers
or other
invoked
tools
are
hard-
coded to
put
derived
files in
the same
direc‐
tory as
source
files.
This
behavior
of mak‐
ing a
complete
copy of
the
source
tree may
be dis‐
abled by
setting
dupli‐
cate to
0. This
will
cause
scons to
invoke
Builders
using
the path
names of
source
files in
src_dir
and the
path
names of
derived
files
within
build_dir.
This is
always
more
effi‐
cient
than
dupli‐
cate=1,
and is
usually
safe for
most
builds.
Specify‐
ing
dupli‐
cate=0,
however,
may
cause
build
problems
if
source
files
are gen‐
erated
during
the
build,
if any
invoked
tools
are
hard-
coded to
put
derived
files in
the same
direc‐
tory as
the
source
files.
Note
that
specify‐
ing a
BuildDir
works
most
natu‐
rally
with a
sub‐
sidiary
SCon‐
script
file in
the
source
direc‐
tory.
However,
you
would
then
call the
sub‐
sidiary
SCon‐
script
file not
in the
source
direc‐
tory,
but in
the
build_dir
, as if
scons
had made
a vir‐
tual
copy of
the
source
tree
regard‐
less of
the
value of
dupli‐
cate.
This is
how you
tell
scons
which
variant
of a
source
tree to
build.
For
example:
BuildDir('build-variant1', 'src')
SConscript('build-variant1/SConscript')
BuildDir('build-variant2', 'src')
SConscript('build-variant2/SConscript')
See
also
the
SCon‐
script()
func‐
tion,
described
below,
for
another
way
to
spec‐
ify
a
build
direc‐
tory
in
con‐
junc‐
tion
with
call‐
ing
a
sub‐
sidiary
SCon‐
script
file.)
Builder(action,
[argu‐
ments])
env.Builder(action,
[argu‐
ments])
Cre‐
ates
a
Builder
object
for
the
spec‐
i‐
fied
action.
See
the
sec‐
tion
"Builder
Objects,"
below,
for
a
com‐
plete
expla‐
na‐
tion
of
the
argu‐
ments
and
behav‐
ior.
CacheDir(cache_dir)env.CacheDir(cache_dir)
Spec‐
i‐
fies
that
scons
will
main‐
tain
a
cache
of
derived
files
in
cache_dir
.
The
derived
files
in
the
cache
will
be
shared
among
all
the
builds
using
the
same
CacheDir()
call.
When
a
CacheDir()
is
being
used
and
scons
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
iden‐
ti‐
cal
input
files
and
an
iden‐
ti‐
cal
build
action
(as
incor‐
po‐
rated
into
the
MD5
build
sig‐
na‐
ture).
If
so,
scons
will
retrieve
the
file
from
the
cache.
If
the
derived
file
is
not
present
in
the
cache,
scons
will
rebuild
it
and
then
place
a
copy
of
the
built
file
in
the
cache
(iden‐
ti‐
fied
by
its
MD5
build
sig‐
na‐
ture),
so
that
it
may
be
retrieved
by
other
builds
that
need
to
build
the
same
derived
file
from
iden‐
ti‐
cal
inputs.
Use
of
a
spec‐
i‐
fied
CacheDir()
may
be
dis‐
abled
for
any
invo‐
ca‐
tion
by
using
the
--cache-
dis‐
able
option.
If
the
--cache-
force
option
is
used,
scons
will
place
a
copy
of
all
derived
files
in
the
cache,
even
if
they
already
existed
and
were
not
built
by
this
invo‐
ca‐
tion.
This
is
use‐
ful
to
pop‐
u‐
late
a
cache
the
first
time
CacheDir()
is
added
to
a
build,
or
after
using
the
--cache-
dis‐
able
option.
When
using
CacheDir(),
scons
will
report,
"Retrieved
`file'
from
cache,"
unless
the
--cache-
show
option
is
being
used.
When
the
--cache-
show
option
is
used,
scons
will
print
the
action
that
would
have
been
used
to
build
the
file,
with‐
out
any
indi‐
ca‐
tion
that
the
file
was
actu‐
ally
retrieved
from
the
cache.
This
is
use‐
ful
to
gen‐
er‐
ate
build
logs
that
are
equiv‐
a‐
lent
regard‐
less
of
whether
a
given
derived
file
has
been
built
in-
place
or
retrieved
from
the
cache.
Clean(tar‐
gets,
files_or_dirs)
env.Clean(tar‐
gets,
files_or_dirs)
This
spec‐
i‐
fies
a
list
of
files
or
direc‐
to‐
ries
which
should
be
removed
when‐
ever
the
tar‐
gets
are
spec‐
i‐
fied
with
the
-c
com‐
mand
line
option.
The
spec‐
i‐
fied
tar‐
gets
may
be
a
list
or
an
indi‐
vid‐
ual
tar‐
get.
Mul‐
ti‐
ple
calls
to
Clean()
are
legal,
and
cre‐
ate
new
tar‐
gets
or
add
files
and
direc‐
to‐
ries
to
the
clean
list
for
the
spec‐
i‐
fied
tar‐
gets.
Mul‐
ti‐
ple
files
or
direc‐
to‐
ries
should
be
spec‐
i‐
fied
either
as
sep‐
a‐
rate
argu‐
ments
to
the
Clean()
method,
or
as
a
list.
Clean()
will
also
accept
the
return
value
of
any
of
the
con‐
struc‐
tion
envi‐
ron‐
ment
Builder
meth‐
ods.
Exam‐
ples:
Clean('foo', ['bar', 'baz'])
Clean('dist', env.Program('hello', 'hello.c'))
Clean(['foo', 'bar'], 'something_else_to_clean')
Com‐
mand(tar‐
get,
source,
com‐
mands,
[key=val,
...])
env.Com‐
mand(tar‐
get,
source,
com‐
mands,
[key=val,
...])
Exe‐
cutes
a
spe‐
cific
action
(or
list
of
actions)
to
build
a
tar‐
get
file
or
files.
This
is
more
con‐
ve‐
nient
than
defin‐
ing
a
sep‐
a‐
rate
Builder
object
for
a
sin‐
gle
spe‐
cial-
case
build.
Any
key‐
word
argu‐
ments
spec‐
i‐
fied
over‐
ride
any
same-
named
exist‐
ing
con‐
struc‐
tion
vari‐
ables.
Note
that
an
action
can
be
an
exter‐
nal
com‐
mand,
spec‐
i‐
fied
as
a
string,
or
a
callable
Python
object;
see
"Action
Objects,"
below.
Exam‐
ples:
env.Command('foo.out', 'foo.in',
"$FOO_BUILD < $SOURCES > $TARGET")
env.Command('bar.out', 'bar.in',
["rm -f $TARGET",
"$BAR_BUILD < $SOURCES > $TARGET"],
ENV = {'PATH' : '/usr/local/bin/'})
def rename(env, target, source):
import os
os.rename('.tmp', str(target[0]))
env.Command('baz.out', 'baz.in',
["$BAZ_BUILD < $SOURCES > .tmp",
rename ])
Con‐
fig‐
ure(env,
[cus‐
tom_tests,
conf_dir,
log_file])
env.Con‐
fig‐
ure([cus‐
tom_tests,
conf_dir,
log_file])
Cre‐
ates
a
Con‐
fig‐
ure
object
for
inte‐
grated
func‐
tion‐
al‐
ity
sim‐
i‐
lar
to
GNU
auto‐
conf.
See
the
sec‐
tion
"Con‐
fig‐
ure
Con‐
texts,"
below,
for
a
com‐
plete
expla‐
na‐
tion
of
the
argu‐
ments
and
behav‐
ior.
env.Copy([key=val,
...])
Return
a
sep‐
a‐
rate
copy
of
a
con‐
struc‐
tion
envi‐
ron‐
ment.
If
there
are
any
key‐
word
argu‐
ments
spec‐
i‐
fied,
they
are
added
to
the
returned
copy,
over‐
writ‐
ing
any
exist‐
ing
val‐
ues
for
the
key‐
words.
env2 = env.Copy()
env3 = env.Copy(CCFLAGS = '-g')
Addi‐
tion‐
ally,
a
list
of
tools
and
a
tool‐
path
may
be
spec‐
i‐
fied,
as
in
the
Envi‐
ron‐
ment
con‐
struc‐
tor:
def MyTool(env): env['FOO'] = 'bar'
env4 = env.Copy(tools = ['msvc', MyTool])
env.CVS(repos‐
i‐
tory,
mod‐
ule)
A
fac‐
tory
func‐
tion
that
returns
a
Builder
object
to
be
used
to
fetch
source
files
from
the
spec‐
i‐
fied
CVS
repos‐
i‐
tory.
The
returned
Builder
is
intended
to
be
passed
to
the
Source‐
Code
func‐
tion.
The
optional
spec‐
i‐
fied
mod‐
ule
will
be
added
to
the
begin‐
ning
of
all
repos‐
i‐
tory
path
names;
this
can
be
used,
in
essence,
to
strip
ini‐
tial
direc‐
tory
names
from
the
repos‐
i‐
tory
path
names,
so
that
you
only
have
to
repli‐
cate
part
of
the
repos‐
i‐
tory
direc‐
tory
hier‐
ar‐
chy
in
your
local
build
direc‐
tory:
# Will fetch foo/bar/src.c
# from /usr/local/CVSROOT/foo/bar/src.c.
env.SourceCode('.', env.CVS('/usr/local/CVSROOT'))
# Will fetch bar/src.c
# from /usr/local/CVSROOT/foo/bar/src.c.
env.SourceCode('.', env.CVS('/usr/local/CVSROOT', 'foo'))
# Will fetch src.c
# from /usr/local/CVSROOT/foo/bar/src.c.
env.SourceCode('.', env.CVS('/usr/local/CVSROOT', 'foo/bar'))
Default(tar‐
gets)
env.Default(tar‐
gets)
This
spec‐
i‐
fies
a
list
of
default
tar‐
gets,
which
will
be
built
by
scons
if
no
explicit
tar‐
gets
are
given
on
the
com‐
mand
line.
Mul‐
ti‐
ple
calls
to
Default()
are
legal,
and
add
to
the
list
of
default
tar‐
gets.
Mul‐
ti‐
ple
tar‐
gets
should
be
spec‐
i‐
fied
as
sep‐
a‐
rate
argu‐
ments
to
the
Default()
method,
or
as
a
list.
Default()
will
also
accept
the
Node
returned
by
any
of
a
con‐
struc‐
tion
envi‐
ron‐
ment's
builder
meth‐
ods.
Exam‐
ples:
Default('foo', 'bar', 'baz')
env.Default(['a', 'b', 'c'])
hello = env.Program('hello', 'hello.c')
env.Default(hello)
An
argu‐
ment
to
Default()
of
None
will
clear
all
default
tar‐
gets.
Later
calls
to
Default()
will
add
to
the
(now
empty)
default-
tar‐
get
list
like
nor‐
mal.
The
cur‐
rent
list
of
tar‐
gets
added
using
the
Default()
func‐
tion
or
method
is
avail‐
able
in
the
DEFAULT_TAR‐
GETS
list;
see
below.
Default‐
Envi‐
ron‐
ment([args])
Cre‐
ates
and
returns
a
default
con‐
struc‐
tion
envi‐
ron‐
ment
object.
This
con‐
struc‐
tion
envi‐
ron‐
ment
is
used
inter‐
nally
by
SCons
in
order
to
exe‐
cute
many
of
the
global
func‐
tions
in
this
list,
and
to
fetch
source
files
trans‐
par‐
ently
from
source
code
man‐
age‐
ment
sys‐
tems.
Depends(tar‐
get,
depen‐
dency)
env.Depends(tar‐
get,
depen‐
dency)
Spec‐
i‐
fies
an
explicit
depen‐
dency;
the
tar‐
get
file(s)
will
be
rebuilt
when‐
ever
the
depen‐
dency
file(s)
has
changed.
This
should
only
be
nec‐
es‐
sary
for
cases
where
the
depen‐
dency
is
not
caught
by
a
Scan‐
ner
for
the
file.
env.Depends('foo', 'other-input-file-for-foo')
env.Dic‐
tio‐
nary([vars])
Returns
a
dic‐
tio‐
nary
object
con‐
tain‐
ing
copies
of
all
of
the
con‐
struc‐
tion
vari‐
ables
in
the
envi‐
ron‐
ment.
If
there
are
any
vari‐
able
names
spec‐
i‐
fied,
only
the
spec‐
i‐
fied
con‐
struc‐
tion
vari‐
ables
are
returned
in
the
dic‐
tio‐
nary.
dict = env.Dictionary()
cc_dict = env.Dictionary('CC', 'CCFLAGS', 'CCCOM')
Dir(name,
[direc‐
tory])
env.Dir(name,
[direc‐
tory])
This
returns
a
Direc‐
tory
Node,
an
object
that
rep‐
re‐
sents
the
spec‐
i‐
fied
direc‐
tory
name.
name
can
be
a
rel‐
a‐
tive
or
abso‐
lute
path.
direc‐
tory
is
an
optional
direc‐
tory
that
will
be
used
as
the
par‐
ent
direc‐
tory.
If
no
direc‐
tory
is
spec‐
i‐
fied,
the
cur‐
rent
script's
direc‐
tory
is
used
as
the
par‐
ent.
Direc‐
tory
Nodes
can
be
used
any‐
where
you
would
sup‐
ply
a
string
as
a
direc‐
tory
name
to
a
Builder
method
or
func‐
tion.
Direc‐
tory
Nodes
have
attributes
and
meth‐
ods
that
are
use‐
ful
in
many
sit‐
u‐
a‐
tions;
see
"File
and
Direc‐
tory
Nodes,"
below.
EnsurePython‐
Ver‐
sion(major,
minor)
env.EnsurePython‐
Ver‐
sion(major,
minor)
Ensure
that
the
Python
ver‐
sion
is
at
least
major.minor.
This
func‐
tion
will
print
out
an
error
mes‐
sage
and
exit
SCons
with
a
non-
zero
exit
code
if
the
actual
Python
ver‐
sion
is
not
late
enough.
EnsurePythonVersion(2,2)
EnsureSConsVer‐
sion(major,
minor)
env.EnsureSConsVer‐
sion(major,
minor)
Ensure
that
the
SCons
ver‐
sion
is
at
least
major.minor.
This
func‐
tion
will
print
out
an
error
mes‐
sage
and
exit
SCons
with
a
non-
zero
exit
code
if
the
actual
SCons
ver‐
sion
is
not
late
enough.
EnsureSConsVersion(0,9)
Envi‐
ron‐
ment([key=value,
...])
env.Envi‐
ron‐
ment([key=value,
...])
Return
a
new
con‐
struc‐
tion
envi‐
ron‐
ment
ini‐
tial‐
ized
with
the
spec‐
i‐
fied
key=value
pairs.
Exe‐
cute(action,
[str‐
func‐
tion,
varlist])
env.Exe‐
cute(action,
[str‐
func‐
tion,
varlist])
Exe‐
cutes
an
Action
object.
The
spec‐
i‐
fied
action
may
be
an
Action
object
(see
the
sec‐
tion
"Action
Objects,"
below,
for
a
com‐
plete
expla‐
na‐
tion
of
the
argu‐
ments
and
behav‐
ior),
or
it
may
be
a
com‐
mand-
line
string,
list
of
com‐
mands,
or
exe‐
cutable
Python
func‐
tion,
each
of
which
will
be
con‐
verted
into
an
Action
object
and
then
exe‐
cuted.
The
exit
value
of
the
com‐
mand
or
return
value
of
the
Python
func‐
tion
will
be
returned.
Exit([value])
env.Exit([value])
This
tells
scons
to
exit
imme‐
di‐
ately
with
the
spec‐
i‐
fied
value.
A
default
exit
value
of
0
(zero)
is
used
if
no
value
is
spec‐
i‐
fied.
Export(vars)env.Export(vars)
This
tells
scons
to
export
a
list
of
vari‐
ables
from
the
cur‐
rent
SCon‐
script
file
to
all
other
SCon‐
script
files.
The
exported
vari‐
ables
are
kept
in
a
global
col‐
lec‐
tion,
so
sub‐
se‐
quent
calls
to
Export()
will
over-
write
pre‐
vi‐
ous
exports
that
have
the
same
name.
Mul‐
ti‐
ple
vari‐
able
names
can
be
passed
to
Export()
as
sep‐
a‐
rate
argu‐
ments
or
as
a
list.
A
dic‐
tio‐
nary
can
be
used
to
map
vari‐
ables
to
a
dif‐
fer‐
ent
name
when
exported.
Both
local
vari‐
ables
and
global
vari‐
ables
can
be
exported.
Exam‐
ples:
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})
Note
that
the
SCon‐
script()
func‐
tion
sup‐
ports
an
exports
argu‐
ment
that
makes
it
eas‐
ier
to
to
export
a
vari‐
able
or
set
of
vari‐
ables
to
a
sin‐
gle
SCon‐
script
file.
See
the
descrip‐
tion
of
the
SCon‐
script()
func‐
tion,
below.
File(name,
[direc‐
tory])
env.File(name,
[direc‐
tory])
This
returns
a
File
Node,
an
object
that
rep‐
re‐
sents
the
spec‐
i‐
fied
file
name.
name
can
be
a
rel‐
a‐
tive
or
abso‐
lute
path.
direc‐
tory
is
an
optional
direc‐
tory
that
will
be
used
as
the
par‐
ent
direc‐
tory.
File
Nodes
can
be
used
any‐
where
you
would
sup‐
ply
a
string
as
a
file
name
to
a
Builder
method
or
func‐
tion.
File
Nodes
have
attributes
and
meth‐
ods
that
are
use‐
ful
in
many
sit‐
u‐
a‐
tions;
see
"File
and
Direc‐
tory
Nodes,"
below.
Find‐
File(file,
dirs)
env.Find‐
File(file,
dirs)
Search
for
file
in
the
path
spec‐
i‐
fied
by
dirs.
file
may
be
a
list
of
file
names
or
a
sin‐
gle
file
name.
In
addi‐
tion
to
search‐
ing
for
files
that
exist
in
the
filesytem,
this
func‐
tion
also
searches
for
derived
files
that
have
not
yet
been
built.
foo = env.FindFile('foo', ['dir1', 'dir2'])
Flat‐
ten(sequence)
env.Flat‐
ten(sequence)
Takes
a
sequence
(that
is,
a
Python
list
or
tuple)
that
may
con‐
tain
nested
sequences
and
returns
a
flat‐
tened
list
con‐
tain‐
ing
all
of
the
indi‐
vid‐
ual
ele‐
ments
in
any
sequence.
This
can
be
help‐
ful
for
col‐
lect‐
ing
the
lists
returned
by
calls
to
Builders;
other
Builders
will
auto‐
mat‐
i‐
cally
flat‐
ten
lists
spec‐
i‐
fied
as
input,
but
direct
Python
manip‐
u‐
la‐
tion
of
these
lists
does
not:
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)
Get‐
Build‐
Path(file,
[...])
env.Get‐
Build‐
Path(file,
[...])
Returns
the
scons
path
name
(or
names)
for
the
spec‐
i‐
fied
file
(or
files).
The
spec‐
i‐
fied
file
or
files
may
be
scons
Nodes
or
strings
rep‐
re‐
sent‐
ing
path
names.
Get‐
LaunchDir()
env.Get‐
LaunchDir()
Returns
the
abso‐
lute
path
name
of
the
direc‐
tory
from
which
scons
was
ini‐
tially
invoked.
This
can
be
use‐
ful
when
using
the
-u,
-U
or
-D
options,
which
inter‐
nally
change
to
the
direc‐
tory
in
which
the
SCon‐
struct
file
is
found.
GetOp‐
tion(name)
env.GetOp‐
tion(name)
This
func‐
tion
pro‐
vides
a
way
to
query
a
select
sub‐
set
of
the
scons
com‐
mand
line
options
from
a
SCon‐
script
file.
See
SetOp‐
tion()
for
a
descrip‐
tion
of
the
options
avail‐
able.
Help(text)env.Help(text)
This
spec‐
i‐
fies
help
text
to
be
printed
if
the
-h
argu‐
ment
is
given
to
scons.
scons
will
exit
after
print‐
ing
out
the
help
text.
Ignore(tar‐
get,
depen‐
dency)
env.Ignore(tar‐
get,
depen‐
dency)
The
spec‐
i‐
fied
depen‐
dency
file(s)
will
be
ignored
when
decid‐
ing
if
the
tar‐
get
file(s)
need
to
be
rebuilt.
env.Ignore('foo', 'foo.c')
env.Ignore('bar', ['bar1.h', 'bar2.h'])
Import(vars)env.Import(vars)
This
tells
scons
to
import
a
list
of
vari‐
ables
into
the
cur‐
rent
SCon‐
script
file.
This
will
import
vari‐
ables
that
were
exported
with
Export()
or
in
the
exports
argu‐
ment
to
SCon‐
script().
Vari‐
ables
exported
by
SCon‐
script()
have
prece‐
dence.
Mul‐
ti‐
ple
vari‐
able
names
can
be
passed
to
Import()
as
sep‐
a‐
rate
argu‐
ments
or
as
a
list.
The
vari‐
able
"*"
can
be
used
to
import
all
vari‐
ables.
Exam‐
ples:
Import("env")
Import("env", "variable")
Import(["env", "variable"])
Import("*")
Install(dir,
source)
env.Install(dir,
source)
Installs
one
or
more
files
in
a
des‐
ti‐
na‐
tion
direc‐
tory.
The
file
names
remain
the
same.
env.Install(dir = '/usr/local/bin', source = ['foo', 'bar'])
Instal‐
lAs(tar‐
get,
source)
env.Instal‐
lAs(tar‐
get,
source)
Installs
one
or
more
files
as
spe‐
cific
file
names,
allow‐
ing
chang‐
ing
a
file
name
as
part
of
the
instal‐
la‐
tion.
It
is
an
error
if
the
tar‐
get
and
source
list
dif‐
fer‐
ent
num‐
bers
of
files.
env.InstallAs(target = '/usr/local/bin/foo',
source = 'foo_debug')
env.InstallAs(target = ['../lib/libfoo.a', '../lib/libbar.a'],
source = ['libFOO.a', 'libBAR.a'])
Lit‐
eral(string)
env.Lit‐
eral(string)
The
spec‐
i‐
fied
string
will
be
pre‐
served
as-
is
and
not
have
con‐
struc‐
tion
vari‐
ables
expanded.
Local(tar‐
gets)
env.Local(tar‐
gets)
The
spec‐
i‐
fied
tar‐
gets
will
have
copies
made
in
the
local
tree,
even
if
an
already
up-
to-
date
copy
exists
in
a
repos‐
i‐
tory.
Returns
a
list
of
the
tar‐
get
Node
or
Nodes.
env.Par‐
seC‐
on‐
fig(com‐
mand,
[func‐
tion])
Calls
the
spec‐
i‐
fied
func‐
tion
to
mod‐
ify
the
envi‐
ron‐
ment
as
spec‐
i‐
fied
by
the
out‐
put
of
com‐
mand
.
The
default
func‐
tion
expects
the
out‐
put
of
a
typ‐
i‐
cal
*-con‐
fig
com‐
mand
(for
exam‐
ple,
gtk-
con‐
fig)
and
parses
the
returned
-L,
-l,
-Wa,
-Wl,
-Wp,
-I
and
other
options
into
the
LIB‐
PATH,
LIBS,
ASFLAGS,
LINK‐
FLAGS,
CPPFLAGS,
CPP‐
PATH
and
CCFLAGS
vari‐
ables,
respec‐
tively.
A
returned
-pthread
option
gets
added
to
both
the
CCFLAGS
and
LINK‐
FLAGS
vari‐
ables.
env.Per‐
force()
A
fac‐
tory
func‐
tion
that
returns
a
Builder
object
to
be
used
to
fetch
source
files
from
the
Per‐
force
source
code
man‐
age‐
ment
sys‐
tem.
The
returned
Builder
is
intended
to
be
passed
to
the
Source‐
Code
func‐
tion:
env.SourceCode('.', env.Perforce())
Per‐
force
uses
a
num‐
ber
of
exter‐
nal
envi‐
ron‐
ment
vari‐
ables
for
its
oper‐
a‐
tion.
Con‐
se‐
quently,
this
func‐
tion
adds
the
fol‐
low‐
ing
vari‐
ables
from
the
user's
exter‐
nal
envi‐
ron‐
ment
to
the
con‐
struc‐
tion
envi‐
ron‐
ment's
ENV
dic‐
tio‐
nary:
P4CHARSET,
P4CLIENT,
P4LAN‐
GUAGE,
P4PASSWD,
P4PORT,
P4USER,
SYS‐
TEM‐
ROOT,
USER,
and
USER‐
NAME.
Plat‐
form(string)
Returns
a
callable
object
that
can
be
used
to
ini‐
tial‐
ize
a
con‐
struc‐
tion
envi‐
ron‐
ment
using
the
plat‐
form
key‐
word
of
the
Envi‐
ron‐
ment()
method:
env = Environment(platform = Platform('win32'))
env.Plat‐
form(string)
Applies
the
callable
object
for
the
spec‐
i‐
fied
plat‐
form
string
to
the
envi‐
ron‐
ment
through
which
the
method
was
called.
env.Platform('posix')
Note
that
the
win32
plat‐
form
adds
the
SYS‐
TEM‐
ROOT
vari‐
able
from
the
user's
exter‐
nal
envi‐
ron‐
ment
to
the
con‐
struc‐
tion
envi‐
ron‐
ment's
ENV
dic‐
tio‐
nary.
This
is
so
that
any
exe‐
cuted
com‐
mands
that
use
sock‐
ets
to
con‐
nect
with
other
sys‐
tems
(such
as
fetch‐
ing
source
files
from
exter‐
nal
CVS
repos‐
i‐
tory
spec‐
i‐
fi‐
ca‐
tions
like
:pserver:anony‐
mous@cvs.source‐
forge.net:/cvs‐
root/scons)
will
work
on
Win32
sys‐
tems.
Pre‐
cious(tar‐
get,
...)
env.Pre‐
cious(tar‐
get,
...)
Marks
each
given
tar‐
get
as
pre‐
cious
so
it
is
not
deleted
before
it
is
rebuilt.
Nor‐
mally
scons
deletes
a
tar‐
get
before
build‐
ing
it.
Mul‐
ti‐
ple
tar‐
gets
can
be
passed
in
to
a
sin‐
gle
call
to
Pre‐
cious().
env.Prepend(key=val,
[...])
Appends
the
spec‐
i‐
fied
key‐
word
argu‐
ments
to
the
begin‐
ning
of
con‐
struc‐
tion
vari‐
ables
in
the
envi‐
ron‐
ment.
If
the
Envi‐
ron‐
ment
does
not
have
the
spec‐
i‐
fied
con‐
struc‐
tion
vari‐
able,
it
is
sim‐
ply
added
to
the
envi‐
ron‐
ment.
If
the
val‐
ues
of
the
con‐
struc‐
tion
vari‐
able
and
the
key‐
word
argu‐
ment
are
the
same
type,
then
the
two
val‐
ues
will
be
sim‐
ply
added
together.
Oth‐
er‐
wise,
the
con‐
struc‐
tion
vari‐
able
and
the
value
of
the
key‐
word
argu‐
ment
are
both
coerced
to
lists,
and
the
lists
are
added
together.
(See
also
the
Append
method,
above.)
env.Prepend(CCFLAGS = '-g ', FOO = ['foo.yyy'])
env.Prepen‐
dEN‐
VPath(name,
new‐
path,
[envname,
sep])
This
appends
new
path
ele‐
ments
to
the
given
path
in
the
spec‐
i‐
fied
exter‐
nal
envi‐
ron‐
ment
(ENV
by
default).
This
will
only
add
any
par‐
tic‐
u‐
lar
path
once
(leav‐
ing
the
first
one
it
encoun‐
ters
and
ignor‐
ing
the
rest,
to
pre‐
serve
path
order),
and
to
help
assure
this,
will
nor‐
mal‐
ize
all
paths
(using
os.path.norm‐
path
and
os.path.norm‐
case).
This
can
also
han‐
dle
the
case
where
the
given
old
path
vari‐
able
is
a
list
instead
of
a
string,
in
which
case
a
list
will
be
returned
instead
of
a
string.
Exam‐
ple:
print 'before:',env['ENV']['INCLUDE']
include_path = '/foo/bar:/foo'
env.PrependENVPath('INCLUDE', include_path)
print 'after:',env['ENV']['INCLUDE']
yields:
before: /biz:/foo
after: /foo/bar:/foo:/biz
env.Appen‐
dUnique(key=val,
[...])
Appends
the
spec‐
i‐
fied
key‐
word
argu‐
ments
to
the
begin‐
ning
of
con‐
struc‐
tion
vari‐
ables
in
the
envi‐
ron‐
ment.
If
the
Envi‐
ron‐
ment
does
not
have
the
spec‐
i‐
fied
con‐
struc‐
tion
vari‐
able,
it
is
sim‐
ply
added
to
the
envi‐
ron‐
ment.
If
the
con‐
struc‐
tion
vari‐
able
being
appended
to
is
a
list,
then
any
value(s)
that
already
exist
in
the
con‐
struc‐
tion
vari‐
able
will
not
be
added
again
to
the
list.
env.PrependUnique(CCFLAGS = '-g', FOO = ['foo.yyy'])
env.RCS()
A
fac‐
tory
func‐
tion
that
returns
a
Builder
object
to
be
used
to
fetch
source
files
from
RCS.
The
returned
Builder
is
intended
to
be
passed
to
the
Source‐
Code
func‐
tion:
env.SourceCode('.', env.RCS())
Note
that
scons
will
fetch
source
files
from
RCS
sub‐
di‐
rec‐
to‐
ries
auto‐
mat‐
i‐
cally,
so
con‐
fig‐
ur‐
ing
RCS
as
demon‐
strated
in
the
above
exam‐
ple
should
only
be
nec‐
es‐
sary
if
you
are
fetch‐
ing
from
RCS,v
files
in
the
same
direc‐
tory
as
the
source
files,
or
if
you
need
to
explic‐
itly
spec‐
ify
RCS
for
a
spe‐
cific
sub‐
di‐
rec‐
tory.
env.Replace(key=val,
[...])
Replaces
con‐
struc‐
tion
vari‐
ables
in
the
Envi‐
ron‐
ment
with
the
spec‐
i‐
fied
key‐
word
argu‐
ments.
env.Replace(CCFLAGS = '-g', FOO = 'foo.xxx')
Repos‐
i‐
tory(direc‐
tory)
env.Repos‐
i‐
tory(direc‐
tory)
Spec‐
i‐
fies
that
direc‐
tory
is
a
repos‐
i‐
tory
to
be
searched
for
files.
Mul‐
ti‐
ple
calls
to
Repos‐
i‐
tory()
are
legal,
and
each
one
adds
to
the
list
of
repos‐
i‐
to‐
ries
that
will
be
searched.
To
scons,
a
repos‐
i‐
tory
is
a
copy
of
the
source
tree,
from
the
top-
level
direc‐
tory
on
down,
which
may
con‐
tain
both
source
files
and
derived
files
that
can
be
used
to
build
tar‐
gets
in
the
local
source
tree.
The
canon‐
i‐
cal
exam‐
ple
would
be
an
offi‐
cial
source
tree
main‐
tained
by
an
inte‐
gra‐
tor.
If
the
repos‐
i‐
tory
con‐
tains
derived
files,
then
the
derived
files
should
have
been
built
using
scons,
so
that
the
repos‐
i‐
tory
con‐
tains
the
nec‐
es‐
sary
sig‐
na‐
ture
infor‐
ma‐
tion
to
allow
scons
to
fig‐
ure
out
when
it
is
appro‐
pri‐
ate
to
use
the
repos‐
i‐
tory
copy
of
a
derived
file,
instead
of
build‐
ing
one
locally.
Note
that
if
an
up-
to-
date
derived
file
already
exists
in
a
repos‐
i‐
tory,
scons
will
not
make
a
copy
in
the
local
direc‐
tory
tree.
In
order
to
guar‐
an‐
tee
that
a
local
copy
will
be
made,
use
the
Local()
method.
Return(vars)
This
tells
scons
what
vari‐
able(s)
to
use
as
the
return
value(s)
of
the
cur‐
rent
SCon‐
script
file.
These
vari‐
ables
will
be
returned
to
the
"call‐
ing"
SCon‐
script
file
as
the
return
value(s)
of
SCon‐
script().
Mul‐
ti‐
ple
vari‐
able
names
should
be
passed
to
Return()
as
a
list.
Exam‐
ple:
Return("foo")
Return(["foo", "bar"])
Scan‐
ner(func‐
tion,
[argu‐
ment,
keys,
path_func‐
tion,
node_class,
node_fac‐
tory,
scan_check,
recur‐
sive])
env.Scan‐
ner(func‐
tion,
[argu‐
ment,
keys,
path_func‐
tion,
node_class,
node_fac‐
tory,
scan_check,
recur‐
sive])
Cre‐
ates
a
Scan‐
ner
object
for
the
spec‐
i‐
fied
func‐
tion.
See
the
sec‐
tion
"Scan‐
ner
Objects,"
below,
for
a
com‐
plete
expla‐
na‐
tion
of
the
argu‐
ments
and
behav‐
ior.
env.SCCS()
A
fac‐
tory
func‐
tion
that
returns
a
Builder
object
to
be
used
to
fetch
source
files
from
SCCS.
The
returned
Builder
is
intended
to
be
passed
to
the
Source‐
Code
func‐
tion:
env.SourceCode('.', env.SCCS())
Note
that
scons
will
fetch
source
files
from
SCCS
sub‐
di‐
rec‐
to‐
ries
auto‐
mat‐
i‐
cally,
so
con‐
fig‐
ur‐
ing
SCCS
as
demon‐
strated
in
the
above
exam‐
ple
should
only
be
nec‐
es‐
sary
if
you
are
fetch‐
ing
from
s.SCCS
files
in
the
same
direc‐
tory
as
the
source
files,
or
if
you
need
to
explic‐
itly
spec‐
ify
SCCS
for
a
spe‐
cific
sub‐
di‐
rec‐
tory.
SCon‐
script(scripts,
[exports,
build_dir,
src_dir,
dupli‐
cate])
env.SCon‐
script(scripts,
[exports,
build_dir,
src_dir,
dupli‐
cate])
SCon‐
script(dirs=sub‐
dirs,
[name=script,
exports,
build_dir,
src_dir,
dupli‐
cate])
env.SCon‐
script(dirs=sub‐
dirs,
[name=script,
exports,
build_dir,
src_dir,
dupli‐
cate])
This
tells
scons
to
exe‐
cute
one
or
more
sub‐
sidiary
SCon‐
script
(con‐
fig‐
u‐
ra‐
tion)
files.
There
are
two
ways
to
call
the
SCon‐
script()
func‐
tion.
The
first
way
you
can
call
SCon‐
script()
is
to
explic‐
itly
spec‐
ify
one
or
more
scripts
as
the
first
argu‐
ment.
A
sin‐
gle
script
may
be
spec‐
i‐
fied
as
a
string;
mul‐
ti‐
ple
scripts
must
be
spec‐
i‐
fied
as
a
list
(either
explic‐
itly
or
as
cre‐
ated
by
a
func‐
tion
like
Split()).
The
sec‐
ond
way
you
can
call
SCon‐
script()
is
to
spec‐
ify
a
list
of
(sub)direc‐
tory
names
as
a
dirs=sub‐
dirs
key‐
word
argu‐
ment.
In
this
case,
scons
will,
by
default,
exe‐
cute
a
sub‐
sidiary
con‐
fig‐
u‐
ra‐
tion
file
named
SCon‐
script
in
each
of
the
spec‐
i‐
fied
direc‐
to‐
ries.
You
may
spec‐
ify
a
name
other
than
SCon‐
script
by
sup‐
ply‐
ing
an
optional
name=script
key‐
word
argu‐
ment.
The
optional
exports
argu‐
ment
pro‐
vides
a
list
of
vari‐
able
names
or
a
dic‐
tio‐
nary
of
named
val‐
ues
to
export
to
the
script(s).
These
vari‐
ables
are
locally
exported
only
to
the
spec‐
i‐
fied
script(s),
and
do
not
affect
the
global
pool
of
vari‐
ables
used
by
the
Export()
func‐
tion.
The
sub‐
sidiary
script(s)
must
use
the
Import()
func‐
tion
to
import
the
vari‐
ables.
The
optional
build_dir
argu‐
ment
spec‐
i‐
fies
that
all
of
the
tar‐
get
files
(for
exam‐
ple,
object
files
and
exe‐
cuta‐
bles)
that
would
nor‐
mally
be
built
in
the
sub‐
di‐
rec‐
tory
in
which
script
resides
should
actu‐
ally
be
built
in
build_dir.
build_dir
is
inter‐
preted
rel‐
a‐
tive
to
the
direc‐
tory
of
the
call‐
ing
SCon‐
script
file.
The
optional
src_dir
argu‐
ment
spec‐
i‐
fies
that
the
source
files
from
which
the
tar‐
get
files
should
be
built
can
be
found
in
src_dir.
src_dir
is
inter‐
preted
rel‐
a‐
tive
to
the
direc‐
tory
of
the
call‐
ing
SCon‐
script
file.
By
default,
scons
will
link
or
copy
(depend‐
ing
on
the
plat‐
form)
all
the
source
files
into
the
build
direc‐
tory.
This
behav‐
ior
may
be
dis‐
abled
by
set‐
ting
the
optional
dupli‐
cate
argu‐
ment
to
0
(it
is
set
to
1
by
default),
in
which
case
scons
will
refer
directly
to
the
source
files
in
their
source
direc‐
tory
when
build‐
ing
tar‐
get
files.
(Set‐
ting
dupli‐
cate=0
is
usu‐
ally
safe,
and
always
more
effi‐
cient
than
the
default
of
dupli‐
cate=1,
but
it
may
cause
build
prob‐
lems
in
cer‐
tain
end-
cases,
such
as
com‐
pil‐
ing
from
source
files
that
are
gen‐
er‐
ated
by
the
build.)
Any
vari‐
ables
returned
by
script
using
Return()
will
be
returned
by
the
call
to
SCon‐
script().
Exam‐
ples:
SConscript('subdir/SConscript')
foo = SConscript('sub/SConscript', exports='env')
SConscript('dir/SConscript', exports=['env', 'variable'])
SConscript('src/SConscript', build_dir='build', duplicate=0)
SConscript('bld/SConscript', src_dir='src', exports='env variable')
SConscript(dirs=['sub1', 'sub2'])
SConscript(dirs=['sub3', 'sub4'], name='MySConscript')
SCon‐
scriptChdir(value)
env.SCon‐
scriptChdir(value)
By
default,
scons
changes
its
work‐
ing
direc‐
tory
to
the
direc‐
tory
in
which
each
sub‐
sidiary
SCon‐
script
file
lives.
This
behav‐
ior
may
be
dis‐
abled
by
spec‐
i‐
fy‐
ing
either:
SConscriptChdir(0)env.SConscriptChdir(0)
in
which
case
scons
will
stay
in
the
top-
level
direc‐
tory
while
read‐
ing
all
SCon‐
script
files.
(This
may
be
nec‐
es‐
sary
when
build‐
ing
from
repos‐
i‐
to‐
ries,
when
all
the
direc‐
to‐
ries
in
which
SCon‐
script
files
may
be
found
don't
nec‐
es‐
sar‐
ily
exist
locally.)
You
may
enable
and
dis‐
able
this
abil‐
ity
by
call‐
ing
SCon‐
scriptChdir()
mul‐
ti‐
ple
times:
env = Environment()SConscriptChdir(0)
SConscript('foo/SConscript') # will not chdir to foo
env.SConscriptChdir(1)
SConscript('bar/SConscript') # will chdir to bar
SCon‐
sign‐
File([file,dbm_mod‐
ule])
env.SCon‐
sign‐
File([file,dbm_mod‐
ule])
This
tells
scons
to
store
all
file
sig‐
na‐
tures
in
the
spec‐
i‐
fied
file.
If
the
file
is
omit‐
ted,
.scon‐
sign.dbm
is
used
by
default.
If
file
is
not
an
abso‐
lute
path
name,
the
file
is
placed
in
the
same
direc‐
tory
as
the
top-
level
SCon‐
struct
file.
The
optional
dbm_mod‐
ule
argu‐
ment
can
be
used
to
spec‐
ify
which
Python
data‐
base
mod‐
ule
The
default
is
to
use
a
cus‐
tom
SCons.dblite
mod‐
ule
that
uses
pick‐
led
Python
data
struc‐
tures,
and
which
works
on
all
Python
ver‐
sions
from
1.5.2
on.
Exam‐
ples:
# Stores signatures in ".sconsign.dbm"
# in the top-level SConstruct directory.
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")
SetOp‐
tion(name,
value)
env.SetOp‐
tion(name,
value)
This
func‐
tion
pro‐
vides
a
way
to
set
a
select
sub‐
set
of
the
scons
com‐
mand
line
options
from
a
SCon‐
script
file.
The
options
sup‐
ported
are:
clean
which
cor‐
re‐
sponds
to
-c,
--clean,
and
--remove;
dupli‐
cate
which
cor‐
re‐
sponds
to
--dupli‐
cate;
implicit_cache
which
cor‐
re‐
sponds
to
--implicit-
cache;
max_drift
which
cor‐
re‐
sponds
to
--max-
drift;
num_jobs
which
cor‐
re‐
sponds
to
-j
and
--jobs.
See
the
doc‐
u‐
men‐
ta‐
tion
for
the
cor‐
re‐
spond‐
ing
com‐
mand
line
object
for
infor‐
ma‐
tion
about
each
spe‐
cific
option.
Exam‐
ple:
SetOption('max_drift', 1)
Side‐
Ef‐
fect(side_effect,
tar‐
get)
env.Side‐
Ef‐
fect(side_effect,
tar‐
get)
Declares
side_effect
as
a
side
effect
of
build‐
ing
tar‐
get.
Both
side_effect
and
tar‐
get
can
be
a
list,
a
file
name,
or
a
node.
A
side
effect
is
a
tar‐
get
that
is
cre‐
ated
as
a
side
effect
of
build‐
ing
other
tar‐
gets.
For
exam‐
ple,
a
Win‐
dows
PDB
file
is
cre‐
ated
as
a
side
effect
of
build‐
ing
the
.obj
files
for
a
static
library.
If
a
tar‐
get
is
a
side
effect
of
mul‐
ti‐
ple
build
com‐
mands,
scons
will
ensure
that
only
one
set
of
com‐
mands
is
exe‐
cuted
at
a
time.
Con‐
se‐
quently,
you
only
need
to
use
this
method
for
side-
effect
tar‐
gets
that
are
built
as
a
result
of
mul‐
ti‐
ple
build
com‐
mands.
Source‐
Code(entries,
builder)
env.Source‐
Code(entries,
builder)
Arrange
for
non-
exis‐
tent
source
files
to
be
fetched
from
a
source
code
man‐
age‐
ment
sys‐
tem
using
the
spec‐
i‐
fied
builder.
The
spec‐
i‐
fied
entries
may
be
a
Node,
string
or
list
of
both,
and
may
rep‐
re‐
sent
either
indi‐
vid‐
ual
source
files
or
direc‐
to‐
ries
in
which
source
files
can
be
found.
For
any
non-
exis‐
tent
source
files,
scons
will
search
up
the
direc‐
tory
tree
and
use
the
first
Source‐
Code
builder
it
finds.
The
spec‐
i‐
fied
builder
may
be
None,
in
which
case
scons
will
not
use
a
builder
to
fetch
source
files
for
the
spec‐
i‐
fied
entries,
even
if
a
Source‐
Code
builder
has
been
spec‐
i‐
fied
for
a
direc‐
tory
higher
up
the
tree.
scons
will,
by
default,
fetch
files
from
SCCS
or
RCS
sub‐
di‐
rec‐
to‐
ries
with‐
out
explicit
con‐
fig‐
u‐
ra‐
tion.
This
takes
some
extra
pro‐
cess‐
ing
time
to
search
for
the
nec‐
es‐
sary
source
code
man‐
age‐
ment
files
on
disk.
You
can
avoid
these
extra
searches
and
speed
up
your
build
a
lit‐
tle
by
dis‐
abling
these
searches
as
fol‐
lows:
env.SourceCode('.', None)
Note
that
if
the
spec‐
i‐
fied
builder
is
one
you
cre‐
ate
by
hand,
it
must
have
an
asso‐
ci‐
ated
con‐
struc‐
tion
envi‐
ron‐
ment
to
use
when
fetch‐
ing
a
source
file.
scons
pro‐
vides
a
set
of
canned
fac‐
tory
func‐
tions
that
return
appro‐
pri‐
ate
Builders
for
var‐
i‐
ous
pop‐
u‐
lar
source
code
man‐
age‐
ment
sys‐
tems.
Canon‐
i‐
cal
exam‐
ples
of
invo‐
ca‐
tion
include:
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)
SourceS‐
ig‐
na‐
tures(type)
env.SourceS‐
ig‐
na‐
tures(type)
This
func‐
tion
tells
SCons
what
type
of
sig‐
na‐
ture
to
use
for
source
files:
MD5
or
time‐
stamp.
If
the
envi‐
ron‐
ment
method
is
used,
the
spec‐
i‐
fied
type
of
source
sig‐
na‐
ture
is
only
used
when
decid‐
ing
whether
tar‐
gets
built
with
that
envi‐
ron‐
ment
are
up-
to-
date
or
must
be
rebuilt.
If
the
global
func‐
tion
is
used,
the
spec‐
i‐
fied
type
of
source
sig‐
na‐
ture
becomes
the
default
used
for
all
deci‐
sions
about
whether
tar‐
gets
are
up-
to-
date.
"MD5"
means
the
sig‐
na‐
ture
of
a
source
file
is
the
MD5
check‐
sum
of
its
con‐
tents.
"time‐
stamp"
means
the
sig‐
na‐
ture
of
a
source
file
is
its
time‐
stamp
(mod‐
i‐
fi‐
ca‐
tion
time).
There
is
no
dif‐
fer‐
ent
between
the
two
behav‐
iors
for
Python
Value()
node
objects.
"MD5"
sig‐
na‐
tures
take
longer
to
com‐
pute,
but
are
more
accu‐
rate
than
"time‐
stamp"
sig‐
na‐
tures.
The
default
is
"MD5".
Split(arg)env.Split(arg)
Returns
a
list
of
file
names
or
other
objects.
If
arg
is
a
string,
it
will
be
split
on
strings
of
white-
space
char‐
ac‐
ters
within
the
string,
mak‐
ing
it
eas‐
ier
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
con‐
tain‐
ing
just
the
object.
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
""")
Tar‐
getSig‐
na‐
tures(type)
env.Tar‐
getSig‐
na‐
tures(type)
This
func‐
tion
tells
SCons
what
type
of
sig‐
na‐
tures
to
use
for
tar‐
get
files:
build
or
con‐
tent.
If
the
envi‐
ron‐
ment
method
is
used,
the
spec‐
i‐
fied
type
of
sig‐
na‐
ture
is
only
used
for
tar‐
gets
built
with
that
envi‐
ron‐
ment.
If
the
global
func‐
tion
is
used,
the
spec‐
i‐
fied
type
of
sig‐
na‐
ture
becomes
the
default
used
for
all
tar‐
get
files
that
don't
have
an
explicit
tar‐
get
sig‐
na‐
ture
type
spec‐
i‐
fied
for
their
envi‐
ron‐
ments.
"build"
means
the
sig‐
na‐
ture
of
a
tar‐
get
file
is
made
by
con‐
cate‐
nat‐
ing
all
of
the
sig‐
na‐
tures
of
all
its
source
files.
"con‐
tent"
means
the
sig‐
na‐
ture
of
a
tar‐
get
file
is
an
MD5
check‐
sum
of
its
con‐
tents.
"build"
sig‐
na‐
tures
are
usu‐
ally
faster
to
com‐
pute,
but
"con‐
tent"
sig‐
na‐
tures
can
pre‐
vent
unnec‐
es‐
sary
rebuilds
when
a
tar‐
get
file
is
rebuilt
to
the
exact
same
con‐
tents
as
the
pre‐
vi‐
ous
build.
The
default
is
"build".
Tool(string,tool‐
path=[])
Returns
a
callable
object
that
can
be
used
to
ini‐
tial‐
ize
a
con‐
struc‐
tion
envi‐
ron‐
ment
using
the
tools
key‐
word
of
the
Envi‐
ron‐
ment()
method.
The
object
may
be
called
with
a
con‐
struc‐
tion
envi‐
ron‐
ment
as
an
argu‐
ment,
in
which
case
the
object
will
be
add
the
nec‐
es‐
sary
vari‐
ables
to
the
con‐
struc‐
tion
envi‐
ron‐
ment
and
the
name
of
the
tool
will
be
added
to
the
$TOOLS
con‐
struc‐
tion
vari‐
able.
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
env.Tool(string[,tool‐
path])
Applies
the
callable
object
for
the
spec‐
i‐
fied
tool
string
to
the
envi‐
ron‐
ment
through
which
the
method
was
called.
env.Tool('gcc')
env.Tool('opengl', toolpath = ['build/tools'])
Value(value)env.Value(value)
Returns
a
Node
object
rep‐
re‐
sent‐
ing
the
spec‐
i‐
fied
Python
value.
Value
nodes
can
be
used
as
depen‐
den‐
cies
of
tar‐
gets.
If
the
result
of
call‐
ing
str(value)
changes
between
SCons
runs,
any
tar‐
gets
depend‐
ing
on
Value(value)
will
be
rebuilt.
When
using
time‐
stamp
source
sig‐
na‐
tures,
Value
nodes'
time‐
stamps
are
equal
to
the
sys‐
tem
time
when
the
node
is
cre‐
ated.
def create(target, source, env):
f = open(str(target[0]), 'wb')
f.write('prefix=' + source[0].get_contents())
prefix = ARGUMENTS.get('prefix', '/usr/local')
env = Environment()
env['BUILDERS']['Config'] = Builder(action = create)
env.Config(target = 'package-config', source = Value(prefix))
WhereIs(pro‐
gram,
[path,
pathext,
reject])
env.WhereIs(pro‐
gram,
[path,
pathext,
reject])
Searches
for
the
spec‐
i‐
fied
exe‐
cutable
pro‐
gram,
return‐
ing
the
full
path
name
to
the
pro‐
gram
if
it
is
found,
and
return‐
ing
None
if
not.
Searches
the
spec‐
i‐
fied
path,
the
value
of
the
call‐
ing
envi‐
ron‐
ment's
PATH
(env['ENV']['PATH']),
or
the
user's
cur‐
rent
exter‐
nal
PATH
(os.env‐
i‐
ron['PATH'])
by
default.
On
Win32
sys‐
tems,
searches
for
exe‐
cutable
pro‐
grams
with
any
of
the
file
exten‐
sions
listed
in
the
spec‐
i‐
fied
pathext,
the
call‐
ing
envi‐
ron‐
ment's
PATHEXT
(env['ENV']['PATHEXT'])
or
the
user's
cur‐
rent
PATHEXT
(os.env‐
i‐
ron['PATHEXT'])
by
default.
Will
not
select
any
path
name
or
names
in
the
spec‐
i‐
fied
reject
list,
if
any.
SConscript Variables
In addition to the global functions and methods, scons supports a num‐
ber of Python variables that can be used in SConscript files to affect
how you want the build to be performed.
ARGLIST
A list keyword=value arguments specified on the command line.
Each element in the list is a tuple containing the (key‐
word,value) of the argument. The separate keyword and value
elements of the tuple can be accessed by subscripting for ele‐
ment [0] and [1] of the tuple, respectively.
print "first keyword, value =", ARGLIST[0][0], ARGLIST[0][1]
print "second keyword, value =", ARGLIST[1][0], ARGLIST[1][1]
third_tuple = ARGLIST[2]
print "third keyword, value =", third_tuple[0], third_tuple[1]
for key, value in ARGLIST:
# process key and value
ARGUMENTS
A dictionary of all the keyword=value arguments specified
on the command line. The dictionary is not in order, and
if a given keyword has more than one value assigned to it
on the command line, the last (right-most) value is the
one in the ARGUMENTS dictionary.
if ARGUMENTS.get('debug', 0):
env = Environment(CCFLAGS = '-g')
else:
env = Environment()
BUILD_TARGETS
A list of the targets which scons will actually
try to build, regardless of whether they were
specified on the command line or via the Default()
function or method. The elements of this list may
be strings or nodes, so you should run the list
through the Python str function to make sure any
Node path names are converted to strings.
Because this list may be taken from the list of
targets specified using the Default() function or
method, the contents of the list may change on
each successive call to Default(). See the
DEFAULT_TARGETS list, below, for additional infor‐
mation.
if 'foo' in BUILD_TARGETS:
print "Don't forget to test the `foo' program!"
if 'special/program' in BUILD_TARGETS:
SConscript('special')
Note that the BUILD_TARGETS list only con‐
tains targets expected listed on the com‐
mand line or via calls to the Default()
function or method. It does not contain
all dependent targets that will be built as
a result of making the sure the explicitly-
specified targets are up to date.
COMMAND_LINE_TARGETS
A list of the targets explicitly specified
on the command line. If there are no tar‐
gets specified on the command line, the
list is empty. This can be used, for exam‐
ple, to take specific actions only when a
certain target or targets is explicitly
being built:
if 'foo' in COMMAND_LINE_TARGETS:
print "Don't forget to test the `foo' program!"
if 'special/program' in COMMAND_LINE_TARGETS:
SConscript('special')
DEFAULT_TARGETS
A list of the target nodes that have
been specified using the Default()
function or method. The elements of
the list are nodes, so you need to
run them through the Python str
function to get at the path name for
each Node.
print str(DEFAULT_TARGETS[0])
if 'foo' in map(str, DEFAULT_TARGETS):
print "Don't forget to test the `foo' program!"
The contents of the
DEFAULT_TARGETS list change
on on each successive call to
the Default() function:
print map(str, DEFAULT_TARGETS) # originally []
Default('foo')
print map(str, DEFAULT_TARGETS) # now a node ['foo']
Default('bar')
print map(str, DEFAULT_TARGETS) # now a node ['foo', 'bar']
Default(None)
print map(str, DEFAULT_TARGETS) # back to []
Consequently, be sure
to use DEFAULT_TARGETS
only after you've made
all of your Default()
calls, or else simply
be careful of the
order of these state‐
ments in your SCon‐
script files so that
you don't look for a
specific default tar‐
get before it's actu‐
ally been added to the
list.
Construction Variables
A construction environment has an associated dictionary of construction
variables that are used by built-in or user-supplied build rules. Con‐
struction variables must follow the same rules for Python identifiers:
the initial character must be an underscore or letter, followed by any
number of underscores, letters, or digits.
A number of useful construction variables are automatically defined by
scons for each supported platform, and additional construction vari‐
ables can be defined by the user. The following is a list of the auto‐
matically defined construction variables:
AR The static library archiver.
ARCOM The command line used to generate a static library from object
files.
ARFLAGS
General options passed to the static library archiver.
AS The assembler.
ASCOM The command line used to generate an object file from an assem‐
bly-language source file.
ASFLAGS
General options passed to the assembler.
ASPPCOM
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 $ASFLAGS and
$CPPFLAGS construction variables are included on this command
line.
BIBTEX The bibliography generator for the TeX formatter and typesetter
and the LaTeX structured formatter and typesetter.
BIBTEXCOM
The command line used to call the bibliography generator for the
TeX formatter and typesetter and the LaTeX structured formatter
and typesetter.
BIBTEXFLAGS
General options passed to the bibliography generator for the TeX
formatter and typesetter and the LaTeX structured formatter and
typesetter.
BITKEEPER
The BitKeeper executable.
BITKEEPERCOM
The command line for fetching source files using BitKEeper.
BITKEEPERGET
The command ($BITKEEPER) and subcommand for fetching source
files using BitKeeper.
BITKEEPERGETFLAGS
Options that are passed to the BitKeeper get subcommand.
BUILDERS
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:
env = Environment(BUILDERS = {'NewBuilder' : foo})
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:
env = Environment()
env.Append(BUILDERS = {'NewBuilder' : foo})
or this:
env = Environment()
env['BUILDERS]['NewBuilder'] = foo
CC The C compiler.
CCCOM The command line used to compile a C source
file to a (static) object file. Any
options specified in the $CCFLAGS and
$CPPFLAGS construction variables are
included on this command line.
CCFLAGS
General options that are passed to the C
compiler.
CFILESUFFIX
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 .c (lower case). On case-insen‐
sitive systems (like Win32), SCons also
treats .C (upper case) files as C files.
CCVERSION
The version number of the C compiler. This
may or may not be set, depending on the
specific C compiler being used.
_concat
A function used to produce variables like
$_CPPINCFLAGS. It takes four or five argu‐
ments: a prefix to concatenate onto each
element, a list of elements, a suffix to
concatenate onto each element, an environ‐
ment for variable interpolation, and an
optional function that will be called to
transform the list before concatenation.
env['_CPPINCFLAGS'] = '$( ${_concat(INCPREFIX, CPPPATH, INCSUFFIX, __env__, RDirs)} $)',
CPPDEFINES
A platform independent specification
of C preprocessor definitions. The
definitions will be added to command
lines through the automatically-gen‐
erated $_CPPDEFFLAGS construction
variable (see below), which is con‐
structed according to the type of
value of $CPPDEFINES:
If $CPPDEFINES is a string, the val‐
ues of the $CPPDEFPREFIX and
$CPPDEFSUFFIX construction variables
will be added to the beginning and
end.
# Will add -Dxyz to POSIX compiler command lines,
# and /Dxyz to Microsoft Visual C++ command lines.
env = Environment(CPPDEFINES='xyz')
If $CPPDEFINES is a list, the
values of the $CPPDEFPREFIX
and $CPPDEFSUFFIX construc‐
tion variables will be
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:
# 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'])
If $CPPDEFINES is a
dictionary, the values
of the $CPPDEFPREFIX
and $CPPDEFSUFFIX con‐
struction variables
will be 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 dictio‐
nary item's corre‐
sponding value; if the
value is None, 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 con‐
sistent each time
scons
is run.
# 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})
_CPPDEFFLAGS
An automati‐
cally-generated
construction
variable con‐
taining the C
preprocessor
command-line
options to
define values.
The value of
$_CPPDEFFLAGS
is created by
appending
$CPPDEFPREFIX
and $CPPDEFSUF‐
FIX to the
beginning and
end of each
directory in
$CPPDEFINES.
CPPDEFPREFIX
The prefix used
to specify pre‐
processor defi‐
nitions on the
C compiler com‐
mand line.
This will be
appended to the
beginning of
each definition
in the $CPPDE‐
FINES construc‐
tion variable
when the
$_CPPDEFFLAGS
variable is
automatically
generated.
CPPDEFSUFFIX
The suffix used
to specify pre‐
processor defi‐
nitions on the
C compiler com‐
mand line.
This will be
appended to the
end of each
definition in
the $CPPDEFINES
construction
variable when
the $_CPPDEF‐
FLAGS variable
is automati‐
cally gener‐
ated.
CPPFLAGS
User-specified
C preprocessor
options. These
will be
included in any
command that
uses the C pre‐
processor,
including not
just compila‐
tion of C and
C++ source
files via the
$CCCOM, $SHCC‐
COM, $CXXCOM
and $SHCXXCOM
command lines,
but also the
$FORTRANPPCOM,
$SHFORTRANPP‐
COM, $F77PPCOM
and $SHF77PPCOM
command lines
used to compile
a Fortran
source file,
and the $ASPP‐
COM command
line used to
assemble an
assembly lan‐
guage source
file, after
first running
each file
through the C
preprocessor.
Note that this
variable does
not contain -I
(or similar)
include search
path options
that scons gen‐
erates automat‐
ically from
$CPPPATH. See
_CPPINCFLAGS,
below, for the
variable that
expands to
those options.
_CPPINCFLAGS
An automati‐
cally-generated
construction
variable con‐
taining the C
preprocessor
command-line
options for
specifying
directories to
be searched for
include files.
The value of
$_CPPINCFLAGS
is created by
appending
$INCPREFIX and
$INCSUFFIX to
the beginning
and end of each
directory in
$CPPPATH.
CPPPATH
The list of
directories
that the C pre‐
processor will
search for
include direc‐
tories. The
C/C++ implicit
dependency
scanner will
search these
directories for
include files.
Don't explic‐
itly put
include direc‐
tory arguments
in CCFLAGS or
CXXFLAGS
because the
result will be
non-portable
and the direc‐
tories 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 scons
to look-up a
directory rela‐
tive to the
root of the
source tree use
#:
env = Environment(CPPPATH='#/include')
The
direc‐
tory
look-up
can also
be
forced
using
the
Dir()
func‐
tion:
include = Dir('include')
env = Environment(CPPPATH=include)
The
direc‐
tory
list
will
be
added
to
com‐
mand
lines
through
the
auto‐
mat‐
i‐
cally-
gen‐
er‐
ated
$_CPPINCFLAGS
con‐
struc‐
tion
vari‐
able,
which
is
con‐
structed
by
append‐
ing
the
val‐
ues
of
the
$INCPRE‐
FIX
and
$INC‐
SUF‐
FIX
con‐
struc‐
tion
vari‐
ables
to
the
begin‐
ning
and
end
of
each
direc‐
tory
in
$CPP‐
PATH.
Any
com‐
mand
lines
you
define
that
need
the
CPP‐
PATH
direc‐
tory
list
should
include
$_CPPINCFLAGS:
env = Environment(CCCOM="my_compiler $_CPPINCFLAGS -c -o $TARGET $SOURCE")
CPP‐
SUF‐
FIXES The
list
of
suf‐
fixes
of
files
that
will
be
scanned
for
C
pre‐
proces‐
sor
implicit
depen‐
den‐
cies
(#include
lines).
The
default
list
is:
[".c", ".C", ".cxx", ".cpp", ".c++", ".cc",
".h", ".H", ".hxx", ".hpp", ".hh",
".F", ".fpp", ".FPP",
".S", ".spp", ".SPP"]
CVS The
CVS
exe‐
cutable.
CVS‐
COFLAGS
Options
that
are
passed
to
the
CVS
check‐
out
sub‐
com‐
mand.
CVS‐
COM The
com‐
mand
line
used
to
fetch
source
files
from
a
CVS
repos‐
i‐
tory.
CVS‐
FLAGS Gen‐
eral
options
that
are
passed
to
CVS.
By
default,
this
is
set
to
"-d
$CVS‐
REPOS‐
I‐
TORY"
to
spec‐
ify
from
where
the
files
must
be
fetched.
CVS‐
REPOS‐
I‐
TORY The
path
to
the
CVS
repos‐
i‐
tory.
This
is
ref‐
er‐
enced
in
the
default
$CVS‐
FLAGS
value.
CXX The
C++
com‐
piler.
CXXFILE‐
SUF‐
FIX
The
suf‐
fix
for
C++
source
files.
This
is
used
by
the
inter‐
nal
CXXFile
builder
when
gen‐
er‐
at‐
ing
C++
files
from
Lex
(.ll)
or
YACC
(.yy)
input
files.
The
default
suf‐
fix
is
.cc.
SCons
also
treats
files
with
the
suf‐
fixes
.cpp,
.cxx,
.c++,
and
.C++
as
C++
files.
On
case-
sen‐
si‐
tive
sys‐
tems
(Linux,
UNIX,
and
other
POSIX-
alikes),
SCons
also
treats
.C
(upper
case)
files
as
C++
files.
CXXCOM The
com‐
mand
line
used
to
com‐
pile
a
C++
source
file
to
an
object
file.
Any
options
spec‐
i‐
fied
in
the
$CXXFLAGS
and
$CPPFLAGS
con‐
struc‐
tion
vari‐
ables
are
included
on
this
com‐
mand
line.
CXXFLAGS
Gen‐
eral
options
that
are
passed
to
the
C++
com‐
piler.
CXXVER‐
SION
The
ver‐
sion
num‐
ber
of
the
C++
com‐
piler.
This
may
or
may
not
be
set,
depend‐
ing
on
the
spe‐
cific
C++
com‐
piler
being
used.
Dir A
func‐
tion
that
con‐
verts
a
file
name
into
a
Dir
instance
rel‐
a‐
tive
to
the
tar‐
get
being
built.
DSUF‐
FIXES The
list
of
suf‐
fixes
of
files
that
will
be
scanned
for
imported
D
pack‐
age
files.
The
default
list
is:
['.d']
DVIPDF The
TeX
DVI
file
to
PDF
file
con‐
verter.
DVIPDF‐
FLAGS
Gen‐
eral
options
passed
to
the
TeX
DVI
file
to
PDF
file
con‐
verter.
DVIPDF‐
COM
The
com‐
mand
line
used
to
con‐
vert
TeX
DVI
files
into
a
PDF
file.
DVIPS The
TeX
DVI
file
to
Post‐
Script
con‐
verter.
DVIPS‐
FLAGS Gen‐
eral
options
passed
to
the
TeX
DVI
file
to
Post‐
Script
con‐
verter.
ENV A
dic‐
tio‐
nary
of
envi‐
ron‐
ment
vari‐
ables
to
use
when
invok‐
ing
com‐
mands.
When
ENV
is
used
in
a
com‐
mand
all
list
val‐
ues
will
be
joined
using
the
path
sep‐
a‐
ra‐
tor
and
any
other
non-
string
val‐
ues
will
sim‐
ply
be
coerced
to
a
string.
Note
that,
by
default,
scons
does
not
prop‐
a‐
gate
the
envi‐
ron‐
ment
in
force
when
you
exe‐
cute
scons
to
the
com‐
mands
used
to
build
tar‐
get
files.
This
is
so
that
builds
will
be
guar‐
an‐
teed
repeat‐
able
regard‐
less
of
the
envi‐
ron‐
ment
vari‐
ables
set
at
the
time
scons
is
invoked.
If
you
want
to
prop‐
a‐
gate
your
envi‐
ron‐
ment
vari‐
ables
to
the
com‐
mands
exe‐
cuted
to
build
tar‐
get
files,
you
must
do
so
explic‐
itly:
import os
env = Environment(ENV = os.environ)
Note
that
you
can
choose
only
to
prop‐
a‐
gate
cer‐
tain
envi‐
ron‐
ment
vari‐
ables.
A
com‐
mon
exam‐
ple
is
the
sys‐
tem
PATH
envi‐
ron‐
ment
vari‐
able,
so
that
scons
uses
the
same
util‐
i‐
ties
as
the
invok‐
ing
shell
(or
other
process):
import os
env = Environment(ENV = {'PATH' : os.environ['PATH']})
ESCAPE A
func‐
tion
that
will
be
called
to
escape
shell
spe‐
cial
char‐
ac‐
ters
in
com‐
mand
lines.
The
func‐
tion
should
take
one
argu‐
ment:
the
com‐
mand
line
string
to
escape;
and
should
return
the
escaped
com‐
mand
line.
F77 The
For‐
tran
77
com‐
piler.
You
should
nor‐
mally
set
the
$FOR‐
TRAN
vari‐
able,
which
spec‐
i‐
fies
the
default
For‐
tran
com‐
piler
for
all
For‐
tran
ver‐
sions.
You
only
need
to
set
$F77
if
you
need
to
use
a
spe‐
cific
com‐
piler
or
com‐
piler
ver‐
sion
for
For‐
tran
77
files.
F77COM The
com‐
mand
line
used
to
com‐
pile
a
For‐
tran
77
source
file
to
an
object
file.
You
only
need
to
set
$F77COM
if
you
need
to
use
a
spe‐
cific
com‐
mand
line
for
For‐
tran
77
files.
You
should
nor‐
mally
set
the
$FOR‐
TRAN‐
COM
vari‐
able,
which
spec‐
i‐
fies
the
default
com‐
mand
line
for
all
For‐
tran
ver‐
sions.
F77FLAGS
Gen‐
eral
user-
spec‐
i‐
fied
options
that
are
passed
to
the
For‐
tran
77
com‐
piler.
Note
that
this
vari‐
able
does
not
con‐
tain
-I
(or
sim‐
i‐
lar)
include
search
path
options
that
scons
gen‐
er‐
ates
auto‐
mat‐
i‐
cally
from
$F77PATH.
See
_F77INCFLAGS,
below,
for
the
vari‐
able
that
expands
to
those
options.
You
only
need
to
set
$F77FLAGS
if
you
need
to
define
spe‐
cific
user
options
for
For‐
tran
77
files.
You
should
nor‐
mally
set
the
$FOR‐
TRAN‐
FLAGS
vari‐
able,
which
spec‐
i‐
fies
the
user-
spec‐
i‐
fied
options
passed
to
the
default
For‐
tran
com‐
piler
for
all
For‐
tran
ver‐
sions.
_F77INCFLAGS
An
auto‐
mat‐
i‐
cally-
gen‐
er‐
ated
con‐
struc‐
tion
vari‐
able
con‐
tain‐
ing
the
For‐
tran
77
com‐
piler
com‐
mand-
line
options
for
spec‐
i‐
fy‐
ing
direc‐
to‐
ries
to
be
searched
for
include
files.
The
value
of
$_F77INCFLAGS
is
cre‐
ated
by
append‐
ing
$INCPRE‐
FIX
and
$INC‐
SUF‐
FIX
to
the
begin‐
ning
and
end
of
each
direc‐
tory
in
$F77PATH.
F77PATH
The
list
of
direc‐
to‐
ries
that
the
For‐
tran
77
com‐
piler
will
search
for
include
direc‐
to‐
ries.
The
implicit
depen‐
dency
scan‐
ner
will
search
these
direc‐
to‐
ries
for
include
files.
Don't
explic‐
itly
put
include
direc‐
tory
argu‐
ments
in
$F77FLAGS
because
the
result
will
be
non-
por‐
ta‐
ble
and
the
direc‐
to‐
ries
will
not
be
searched
by
the
depen‐
dency
scan‐
ner.
Note:
direc‐
tory
names
in
$F77PATH
will
be
looked-
up
rel‐
a‐
tive
to
the
SCon‐
script
direc‐
tory
when
they
are
used
in
a
com‐
mand.
To
force
scons
to
look-
up
a
direc‐
tory
rel‐
a‐
tive
to
the
root
of
the
source
tree
use
#:
You
only
need
to
set
$F77PATH
if
you
need
to
define
a
spe‐
cific
include
path
for
For‐
tran
77
files.
You
should
nor‐
mally
set
the
$FOR‐
TRAN‐
PATH
vari‐
able,
which
spec‐
i‐
fies
the
include
path
for
the
default
For‐
tran
com‐
piler
for
all
For‐
tran
ver‐
sions.
env = Environment(F77PATH='#/include')
The
direc‐
tory
look-
up
can
also
be
forced
using
the
Dir()
func‐
tion:
include = Dir('include')
env = Environment(F77PATH=include)
The
direc‐
tory
list
will
be
added
to
com‐
mand
lines
through
the
auto‐
mat‐
i‐
cally-
gen‐
er‐
ated
$_F77INCFLAGS
con‐
struc‐
tion
vari‐
able,
which
is
con‐
structed
by
append‐
ing
the
val‐
ues
of
the
$INCPRE‐
FIX
and
$INC‐
SUF‐
FIX
con‐
struc‐
tion
vari‐
ables
to
the
begin‐
ning
and
end
of
each
direc‐
tory
in
$F77PATH.
Any
com‐
mand
lines
you
define
that
need
the
F77PATH
direc‐
tory
list
should
include
$_F77INCFLAGS:
env = Environment(F77COM="my_compiler $_F77INCFLAGS -c -o $TARGET $SOURCE")
F77PPCOM
The
com‐
mand
line
used
to
com‐
pile
a
For‐
tran
77
source
file
to
an
object
file
after
first
run‐
ning
the
file
through
the
C
pre‐
proces‐
sor.
Any
options
spec‐
i‐
fied
in
the
$F77FLAGS
and
$CPPFLAGS
con‐
struc‐
tion
vari‐
ables
are
included
on
this
com‐
mand
line.
You
only
need
to
set
$F77PPCOM
if
you
need
to
use
a
spe‐
cific
C-
pre‐
proces‐
sor
com‐
mand
line
for
For‐
tran
77
files.
You
should
nor‐
mally
set
the
$FOR‐
TRANPP‐
COM
vari‐
able,
which
spec‐
i‐
fies
the
default
C-
pre‐
proces‐
sor
com‐
mand
line
for
all
For‐
tran
ver‐
sions.
F90 The
For‐
tran
90
com‐
piler.
You
should
nor‐
mally
set
the
$FOR‐
TRAN
vari‐
able,
which
spec‐
i‐
fies
the
default
For‐
tran
com‐
piler
for
all
For‐
tran
ver‐
sions.
You
only
need
to
set
$F90
if
you
need
to
use
a
spe‐
cific
com‐
piler
or
com‐
piler
ver‐
sion
for
For‐
tran
90
files.
F90COM The
com‐
mand
line
used
to
com‐
pile
a
For‐
tran
90
source
file
to
an
object
file.
You
only
need
to
set
$F90COM
if
you
need
to
use
a
spe‐
cific
com‐
mand
line
for
For‐
tran
90
files.
You
should
nor‐
mally
set
the
$FOR‐
TRAN‐
COM
vari‐
able,
which
spec‐
i‐
fies
the
default
com‐
mand
line
for
all
For‐
tran
ver‐
sions.
F90FLAGS
Gen‐
eral
user-
spec‐
i‐
fied
options
that
are
passed
to
the
For‐
tran
90
com‐
piler.
Note
that
this
vari‐
able
does
not
con‐
tain
-I
(or
sim‐
i‐
lar)
include
search
path
options
that
scons
gen‐
er‐
ates
auto‐
mat‐
i‐
cally
from
$F90PATH.
See
_F90INCFLAGS,
below,
for
the
vari‐
able
that
expands
to
those
options.
You
only
need
to
set
$F90FLAGS
if
you
need
to
define
spe‐
cific
user
options
for
For‐
tran
90
files.
You
should
nor‐
mally
set
the
$FOR‐
TRAN‐
FLAGS
vari‐
able,
which
spec‐
i‐
fies
the
user-
spec‐
i‐
fied
options
passed
to
the
default
For‐
tran
com‐
piler
for
all
For‐
tran
ver‐
sions.
_F90INCFLAGS
An
auto‐
mat‐
i‐
cally-
gen‐
er‐
ated
con‐
struc‐
tion
vari‐
able
con‐
tain‐
ing
the
For‐
tran
90
com‐
piler
com‐
mand-
line
options
for
spec‐
i‐
fy‐
ing
direc‐
to‐
ries
to
be
searched
for
include
files.
The
value
of
$_F90INCFLAGS
is
cre‐
ated
by
append‐
ing
$INCPRE‐
FIX
and
$INC‐
SUF‐
FIX
to
the
begin‐
ning
and
end
of
each
direc‐
tory
in
$F90PATH.
F90PATH
The
list
of
direc‐
to‐
ries
that
the
For‐
tran
90
com‐
piler
will
search
for
include
direc‐
to‐
ries.
The
implicit
depen‐
dency
scan‐
ner
will
search
these
direc‐
to‐
ries
for
include
files.
Don't
explic‐
itly
put
include
direc‐
tory
argu‐
ments
in
$F90FLAGS
because
the
result
will
be
non-
por‐
ta‐
ble
and
the
direc‐
to‐
ries
will
not
be
searched
by
the
depen‐
dency
scan‐
ner.
Note:
direc‐
tory
names
in
$F90PATH
will
be
looked-
up
rel‐
a‐
tive
to
the
SCon‐
script
direc‐
tory
when
they
are
used
in
a
com‐
mand.
To
force
scons
to
look-
up
a
direc‐
tory
rel‐
a‐
tive
to
the
root
of
the
source
tree
use
#:
You
only
need
to
set
$F90PATH
if
you
need
to
define
a
spe‐
cific
include
path
for
For‐
tran
90
files.
You
should
nor‐
mally
set
the
$FOR‐
TRAN‐
PATH
vari‐
able,
which
spec‐
i‐
fies
the
include
path
for
the
default
For‐
tran
com‐
piler
for
all
For‐
tran
ver‐
sions.
env = Environment(F90PATH='#/include')
The
direc‐
tory
look-
up
can
also
be
forced
using
the
Dir()
func‐
tion:
include = Dir('include')
env = Environment(F90PATH=include)
The
direc‐
tory
list
will
be
added
to
com‐
mand
lines
through
the
auto‐
mat‐
i‐
cally-
gen‐
er‐
ated
$_F90INCFLAGS
con‐
struc‐
tion
vari‐
able,
which
is
con‐
structed
by
append‐
ing
the
val‐
ues
of
the
$INCPRE‐
FIX
and
$INC‐
SUF‐
FIX
con‐
struc‐
tion
vari‐
ables
to
the
begin‐
ning
and
end
of
each
direc‐
tory
in
$F90PATH.
Any
com‐
mand
lines
you
define
that
need
the
F90PATH
direc‐
tory
list
should
include
$_F90INCFLAGS:
env = Environment(F90COM="my_compiler $_F90INCFLAGS -c -o $TARGET $SOURCE")
F90PPCOM
The
com‐
mand
line
used
to
com‐
pile
a
For‐
tran
90
source
file
to
an
object
file
after
first
run‐
ning
the
file
through
the
C
pre‐
proces‐
sor.
Any
options
spec‐
i‐
fied
in
the
$F90FLAGS
and
$CPPFLAGS
con‐
struc‐
tion
vari‐
ables
are
included
on
this
com‐
mand
line.
You
only
need
to
set
$F90PPCOM
if
you
need
to
use
a
spe‐
cific
C-
pre‐
proces‐
sor
com‐
mand
line
for
For‐
tran
90
files.
You
should
nor‐
mally
set
the
$FOR‐
TRANPP‐
COM
vari‐
able,
which
spec‐
i‐
fies
the
default
C-
pre‐
proces‐
sor
com‐
mand
line
for
all
For‐
tran
ver‐
sions.
F95 The
For‐
tran
95
com‐
piler.
You
should
nor‐
mally
set
the
$FOR‐
TRAN
vari‐
able,
which
spec‐
i‐
fies
the
default
For‐
tran
com‐
piler
for
all
For‐
tran
ver‐
sions.
You
only
need
to
set
$F95
if
you
need
to
use
a
spe‐
cific
com‐
piler
or
com‐
piler
ver‐
sion
for
For‐
tran
95
files.
F95COM The
com‐
mand
line
used
to
com‐
pile
a
For‐
tran
95
source
file
to
an
object
file.
You
only
need
to
set
$F95COM
if
you
need
to
use
a
spe‐
cific
com‐
mand
line
for
For‐
tran
95
files.
You
should
nor‐
mally
set
the
$FOR‐
TRAN‐
COM
vari‐
able,
which
spec‐
i‐
fies
the
default
com‐
mand
line
for
all
For‐
tran
ver‐
sions.
F95FLAGS
Gen‐
eral
user-
spec‐
i‐
fied
options
that
are
passed
to
the
For‐
tran
95
com‐
piler.
Note
that
this
vari‐
able
does
not
con‐
tain
-I
(or
sim‐
i‐
lar)
include
search
path
options
that
scons
gen‐
er‐
ates
auto‐
mat‐
i‐
cally
from
$F95PATH.
See
_F95INCFLAGS,
below,
for
the
vari‐
able
that
expands
to
those
options.
You
only
need
to
set
$F95FLAGS
if
you
need
to
define
spe‐
cific
user
options
for
For‐
tran
95
files.
You
should
nor‐
mally
set
the
$FOR‐
TRAN‐
FLAGS
vari‐
able,
which
spec‐
i‐
fies
the
user-
spec‐
i‐
fied
options
passed
to
the
default
For‐
tran
com‐
piler
for
all
For‐
tran
ver‐
sions.
_F95INCFLAGS
An
auto‐
mat‐
i‐
cally-
gen‐
er‐
ated
con‐
struc‐
tion
vari‐
able
con‐
tain‐
ing
the
For‐
tran
95
com‐
piler
com‐
mand-
line
options
for
spec‐
i‐
fy‐
ing
direc‐
to‐
ries
to
be
searched
for
include
files.
The
value
of
$_F95INCFLAGS
is
cre‐
ated
by
append‐
ing
$INCPRE‐
FIX
and
$INC‐
SUF‐
FIX
to
the
begin‐
ning
and
end
of
each
direc‐
tory
in
$F95PATH.
F95PATH
The
list
of
direc‐
to‐
ries
that
the
For‐
tran
95
com‐
piler
will
search
for
include
direc‐
to‐
ries.
The
implicit
depen‐
dency
scan‐
ner
will
search
these
direc‐
to‐
ries
for
include
files.
Don't
explic‐
itly
put
include
direc‐
tory
argu‐
ments
in
$F95FLAGS
because
the
result
will
be
non-
por‐
ta‐
ble
and
the
direc‐
to‐
ries
will
not
be
searched
by
the
depen‐
dency
scan‐
ner.
Note:
direc‐
tory
names
in
$F95PATH
will
be
looked-
up
rel‐
a‐
tive
to
the
SCon‐
script
direc‐
tory
when
they
are
used
in
a
com‐
mand.
To
force
scons
to
look-
up
a
direc‐
tory
rel‐
a‐
tive
to
the
root
of
the
source
tree
use
#:
You
only
need
to
set
$F95PATH
if
you
need
to
define
a
spe‐
cific
include
path
for
For‐
tran
95
files.
You
should
nor‐
mally
set
the
$FOR‐
TRAN‐
PATH
vari‐
able,
which
spec‐
i‐
fies
the
include
path
for
the
default
For‐
tran
com‐
piler
for
all
For‐
tran
ver‐
sions.
env = Environment(F95PATH='#/include')
The
direc‐
tory
look-
up
can
also
be
forced
using
the
Dir()
func‐
tion:
include = Dir('include')
env = Environment(F95PATH=include)
The
direc‐
tory
list
will
be
added
to
com‐
mand
lines
through
the
auto‐
mat‐
i‐
cally-
gen‐
er‐
ated
$_F95INCFLAGS
con‐
struc‐
tion
vari‐
able,
which
is
con‐
structed
by
append‐
ing
the
val‐
ues
of
the
$INCPRE‐
FIX
and
$INC‐
SUF‐
FIX
con‐
struc‐
tion
vari‐
ables
to
the
begin‐
ning
and
end
of
each
direc‐
tory
in
$F95PATH.
Any
com‐
mand
lines
you
define
that
need
the
F95PATH
direc‐
tory
list
should
include
$_F95INCFLAGS:
env = Environment(F95COM="my_compiler $_F95INCFLAGS -c -o $TARGET $SOURCE")
F95PPCOM
The
com‐
mand
line
used
to
com‐
pile
a
For‐
tran
95
source
file
to
an
object
file
after
first
run‐
ning
the
file
through
the
C
pre‐
proces‐
sor.
Any
options
spec‐
i‐
fied
in
the
$F95FLAGS
and
$CPPFLAGS
con‐
struc‐
tion
vari‐
ables
are
included
on
this
com‐
mand
line.
You
only
need
to
set
$F95PPCOM
if
you
need
to
use
a
spe‐
cific
C-
pre‐
proces‐
sor
com‐
mand
line
for
For‐
tran
95
files.
You
should
nor‐
mally
set
the
$FOR‐
TRANPP‐
COM
vari‐
able,
which
spec‐
i‐
fies
the
default
C-
pre‐
proces‐
sor
com‐
mand
line
for
all
For‐
tran
ver‐
sions.
FOR‐
TRAN The
default
For‐
tran
com‐
piler
for
all
ver‐
sions
of
For‐
tran.
FOR‐
TRAN‐
COM The
com‐
mand
line
used
to
com‐
pile
a
For‐
tran
source
file
to
an
object
file.
By
default,
any
options
spec‐
i‐
fied
in
the
$FOR‐
TRAN‐
FLAGS,
$CPPFLAGS,
$_CPPDEF‐
FLAGS,
$_FOR‐
TRAN‐
MOD‐
FLAG,
and
$_FOR‐
TRAN‐
INCFLAGS
con‐
struc‐
tion
vari‐
ables
are
included
on
this
com‐
mand
line.
FOR‐
TRAN‐
FLAGS Gen‐
eral
user-
spec‐
i‐
fied
options
that
are
passed
to
the
For‐
tran
com‐
piler.
Note
that
this
vari‐
able
does
not
con‐
tain
-I
(or
sim‐
i‐
lar)
include
or
mod‐
ule
search
path
options
that
scons
gen‐
er‐
ates
auto‐
mat‐
i‐
cally
from
$FOR‐
TRAN‐
PATH.
See
_FOR‐
TRAN‐
INCFLAGSand_FOR‐
TRAN‐
MOD‐
FLAGS,
below,
for
the
vari‐
ables
that
expand
those
options.
_FOR‐
TRAN‐
INCFLAGS
An
auto‐
mat‐
i‐
cally-
gen‐
er‐
ated
con‐
struc‐
tion
vari‐
able
con‐
tain‐
ing
the
For‐
tran
com‐
piler
com‐
mand-
line
options
for
spec‐
i‐
fy‐
ing
direc‐
to‐
ries
to
be
searched
for
include
files
and
mod‐
ule
files.
The
value
of
$_FOR‐
TRAN‐
INCFLAGS
is
cre‐
ated
by
prepend‐
ing/append‐
ing
$INCPRE‐
FIX
and
$INC‐
SUF‐
FIX
to
the
begin‐
ning
and
end
of
each
direc‐
tory
in
$FOR‐
TRAN‐
PATH.
FOR‐
TRAN‐
MOD‐
DIR Direc‐
tory
loca‐
tion
where
the
For‐
tran
com‐
piler
should
place
any
mod‐
ule
files
it
gen‐
er‐
ates.
This
vari‐
able
is
empty,
by
default.
Some
For‐
tran
com‐
pil‐
ers
will
inter‐
nally
append
this
direc‐
tory
in
the
search
path
for
mod‐
ule
files,
as
well
FOR‐
TRAN‐
MOD‐
DIRPRE‐
FIX
The
pre‐
fix
used
to
spec‐
ify
a
mod‐
ule
direc‐
tory
on
the
For‐
tran
com‐
piler
com‐
mand
line.
This
will
be
appended
to
the
begin‐
ning
of
the
direc‐
tory
in
the
$FOR‐
TRAN‐
MOD‐
DIR
con‐
struc‐
tion
vari‐
ables
when
the
$_FOR‐
TRAN‐
MOD‐
FLAG
vari‐
ables
is
auto‐
mat‐
i‐
cally
gen‐
er‐
ated.
FOR‐
TRAN‐
MOD‐
DIRSUF‐
FIX
The
suf‐
fix
used
to
spec‐
ify
a
mod‐
ule
direc‐
tory
on
the
For‐
tran
com‐
piler
com‐
mand
line.
This
will
be
appended
to
the
begin‐
ning
of
the
direc‐
tory
in
the
$FOR‐
TRAN‐
MOD‐
DIR
con‐
struc‐
tion
vari‐
ables
when
the
$_FOR‐
TRAN‐
MOD‐
FLAG
vari‐
ables
is
auto‐
mat‐
i‐
cally
gen‐
er‐
ated.
FOR‐
TRAN‐
MOD‐
FLAG
An
auto‐
mat‐
i‐
cally-
gen‐
er‐
ated
con‐
struc‐
tion
vari‐
able
con‐
tain‐
ing
the
For‐
tran
com‐
piler
com‐
mand-
line
option
for
spec‐
i‐
fy‐
ing
the
direc‐
tory
loca‐
tion
where
the
For‐
tran
com‐
piler
should
place
any
mod‐
ule
files
that
hap‐
pen
to
get
gen‐
er‐
ated
dur‐
ing
com‐
pi‐
la‐
tion.
The
value
of
$_FOR‐
TRAN‐
MOD‐
FLAG
is
cre‐
ated
by
prepend‐
ing/append‐
ing
$FOR‐
TRAN‐
MOD‐
DIRPRE‐
FIX
and
$FOR‐
TRAN‐
MOD‐
DIRSUF‐
FIX
to
the
begin‐
ning
and
end
of
the
direc‐
tory
in
$FOR‐
TRAN‐
MOD‐
DIR.
FOR‐
TRAN‐
MOD‐
PRE‐
FIX The
mod‐
ule
file
pre‐
fix
used
by
the
For‐
tran
com‐
piler.
SCons
assumes
that
the
For‐
tran
com‐
piler
fol‐
lows
the
quasi-
stan‐
dard
nam‐
ing
con‐
ven‐
tion
for
mod‐
ule
files
of
<mod‐
ule_name>.mod.
As
a
result,
this
vari‐
able
is
left
empty,
by
default.
For
sit‐
u‐
a‐
tions
in
which
the
com‐
piler
does
not
nec‐
es‐
sar‐
ily
fol‐
low
the
nor‐
mal
con‐
ven‐
tion,
the
user
may
use
this
vari‐
able.
Its
value
will
be
appended
to
every
mod‐
ule
file
name
as
scons
attempts
to
resolve
depen‐
den‐
cies.
FOR‐
TRAN‐
MOD‐
SUF‐
FIX The
mod‐
ule
file
suf‐
fix
used
by
the
For‐
tran
com‐
piler.
SCons
assumes
that
the
For‐
tran
com‐
piler
fol‐
lows
the
quasi-
stan‐
dard
nam‐
ing
con‐
ven‐
tion
for
mod‐
ule
files
of
<mod‐
ule_name>.mod.
As
a
result,
this
vari‐
able
is
set
to
".mod",
by
default.
For
sit‐
u‐
a‐
tions
in
which
the
com‐
piler
does
not
nec‐
es‐
sar‐
ily
fol‐
low
the
nor‐
mal
con‐
ven‐
tion,
the
user
may
use
this
vari‐
able.
Its
value
will
be
appended
to
every
mod‐
ule
file
name
as
scons
attempts
to
resolve
depen‐
den‐
cies.
FOR‐
TRAN‐
PATH The
list
of
direc‐
to‐
ries
that
the
For‐
tran
com‐
piler
will
search
for
include
files
and
(for
some
com‐
pil‐
ers)
mod‐
ule
files.
The
For‐
tran
implicit
depen‐
dency
scan‐
ner
will
search
these
direc‐
to‐
ries
for
include
files
(but
not
mod‐
ule
files
since
they
are
auto‐
gen‐
er‐
ated
and,
as
such,
may
not
actu‐
ally
exist
at
the
time
the
scan
takes
place).
Don't
explic‐
itly
put
include
direc‐
tory
argu‐
ments
in
FOR‐
TRAN‐
FLAGS
because
the
result
will
be
non-
por‐
ta‐
ble
and
the
direc‐
to‐
ries
will
not
be
searched
by
the
depen‐
dency
scan‐
ner.
Note:
direc‐
tory
names
in
FOR‐
TRAN‐
PATH
will
be
looked-
up
rel‐
a‐
tive
to
the
SCon‐
script
direc‐
tory
when
they
are
used
in
a
com‐
mand.
To
force
scons
to
look-
up
a
direc‐
tory
rel‐
a‐
tive
to
the
root
of
the
source
tree
use
#:
env = Environment(FORTRANPATH='#/include')
The
direc‐
tory
look-
up
can
also
be
forced
using
the
Dir()
func‐
tion:
include = Dir('include')
env = Environment(FORTRANPATH=include)
The
direc‐
tory
list
will
be
added
to
com‐
mand
lines
through
the
auto‐
mat‐
i‐
cally-
gen‐
er‐
ated
$_FOR‐
TRAN‐
INCFLAGS
con‐
struc‐
tion
vari‐
able,
which
is
con‐
structed
by
append‐
ing
the
val‐
ues
of
the
$INCPRE‐
FIX
and
$INC‐
SUF‐
FIX
con‐
struc‐
tion
vari‐
ables
to
the
begin‐
ning
and
end
of
each
direc‐
tory
in
$FOR‐
TRAN‐
PATH.
Any
com‐
mand
lines
you
define
that
need
the
FOR‐
TRAN‐
PATH
direc‐
tory
list
should
include
$_FOR‐
TRAN‐
INCFLAGS:
env = Environment(FORTRANCOM="my_compiler $_FORTRANINCFLAGS -c -o $TARGET $SOURCE")
FOR‐
TRANPP‐
COM
The
com‐
mand
line
used
to
com‐
pile
a
For‐
tran
source
file
to
an
object
file
after
first
run‐
ning
the
file
through
the
C
pre‐
proces‐
sor.
By
default,
any
options
spec‐
i‐
fied
in
the
$FOR‐
TRAN‐
FLAGS,
$CPPFLAGS,
_CPPDEF‐
FLAGS,
$_FOR‐
TRAN‐
MOD‐
FLAG,
and
$_FOR‐
TRAN‐
INCFLAGS
con‐
struc‐
tion
vari‐
ables
are
included
on
this
com‐
mand
line.
FOR‐
TRAN‐
SUF‐
FIXES The
list
of
suf‐
fixes
of
files
that
will
be
scanned
for
For‐
tran
implicit
depen‐
den‐
cies
(INCLUDE
lines
&
USE
state‐
ments).
The
default
list
is:
[".f", ".F", ".for", ".FOR", ".ftn", ".FTN", ".fpp", ".FPP",
".f77", ".F77", ".f90", ".F90", ".f95", ".F95"]
File A
func‐
tion
that
con‐
verts
a
file
name
into
a
File
instance
rel‐
a‐
tive
to
the
tar‐
get
being
built.
GS The
Ghost‐
script
pro‐
gram
used
to
con‐
vert
Post‐
Script
to
PDF
files.
GSFLAGS
Gen‐
eral
options
passed
to
the
Ghost‐
script
pro‐
gram
when
con‐
vert‐
ing
Post‐
Script
to
PDF
files.
GSCOM The
Ghost‐
script
com‐
mand
line
used
to
con‐
vert
Post‐
Script
to
PDF
files.
IDL‐
SUF‐
FIXES The
list
of
suf‐
fixes
of
files
that
will
be
scanned
for
IDL
implicit
depen‐
den‐
cies
(#include
or
import
lines).
The
default
list
is:
[".idl", ".IDL"]
INCPRE‐
FIX
The
pre‐
fix
used
to
spec‐
ify
an
include
direc‐
tory
on
the
C
com‐
piler
com‐
mand
line.
This
will
be
appended
to
the
begin‐
ning
of
each
direc‐
tory
in
the
$CPP‐
PATH
and
$FOR‐
TRAN‐
PATH
con‐
struc‐
tion
vari‐
ables
when
the
$_CPPINCFLAGS
and
$_FOR‐
TRAN‐
INCFLAGS
vari‐
ables
are
auto‐
mat‐
i‐
cally
gen‐
er‐
ated.
INC‐
SUF‐
FIX The
suf‐
fix
used
to
spec‐
ify
an
include
direc‐
tory
on
the
C
com‐
piler
com‐
mand
line.
This
will
be
appended
to
the
end
of
each
direc‐
tory
in
the
$CPP‐
PATH
and
$FOR‐
TRAN‐
PATH
con‐
struc‐
tion
vari‐
ables
when
the
$_CPPINCFLAGS
and
$_FOR‐
TRAN‐
INCFLAGS
vari‐
ables
are
auto‐
mat‐
i‐
cally
gen‐
er‐
ated.
INSTALL
A
func‐
tion
to
be
called
to
install
a
file
into
a
des‐
ti‐
na‐
tion
file
name.
The
default
func‐
tion
copies
the
file
into
the
des‐
ti‐
na‐
tion
(and
sets
the
des‐
ti‐
na‐
tion
file's
mode
and
per‐
mis‐
sion
bits
to
match
the
source
file's).
The
func‐
tion
takes
the
fol‐
low‐
ing
argu‐
ments:
def install(dest, source, env):
dest
is
the
path
name
of
the
des‐
ti‐
na‐
tion
file.
source
is
the
path
name
of
the
source
file.
env
is
the
con‐
struc‐
tion
envi‐
ron‐
ment
(a
dic‐
tio‐
nary
of
con‐
struc‐
tion
val‐
ues)
in
force
for
this
file
instal‐
la‐
tion.
JAR The
Java
ar‐
chive
tool.
JARCHDIR
The
direc‐
tory
to
which
the
Java
ar‐
chive
tool
should
change
(using
the
-C
option).
JAR‐
COM The
com‐
mand
line
used
to
call
the
Java
ar‐
chive
tool.
JARFLAGS
Gen‐
eral
options
passed
to
the
Java
ar‐
chive
tool.
By
default
this
is
set
to
cf
to
cre‐
ate
the
nec‐
es‐
sary
jar
file.
JAR‐
SUF‐
FIX The
suf‐
fix
for
Java
ar‐
chives:
.jar
by
default.
JAVAC The
Java
com‐
piler.
JAVAC‐
COM The
com‐
mand
line
used
to
com‐
pile
a
direc‐
tory
tree
con‐
tain‐
ing
Java
source
files
to
cor‐
re‐
spond‐
ing
Java
class
files.
Any
options
spec‐
i‐
fied
in
the
$JAVACFLAGS
con‐
struc‐
tion
vari‐
able
are
included
on
this
com‐
mand
line.
JAVACFLAGS
Gen‐
eral
options
that
are
passed
to
the
Java
com‐
piler.
JAVA‐
CLASS‐
DIR The
direc‐
tory
in
which
Java
class
files
may
be
found.
This
is
stripped
from
the
begin‐
ning
of
any
Java
.class
file
names
sup‐
plied
to
the
JavaH
builder.
JAVA‐
CLASS‐
SUF‐
FIX The
suf‐
fix
for
Java
class
files;
.class
by
default.
JAVAH The
Java
gen‐
er‐
a‐
tor
for
C
header
and
stub
files.
JAVAH‐
COM The
com‐
mand
line
used
to
gen‐
er‐
ate
C
header
and
stub
files
from
Java
classes.
Any
options
spec‐
i‐
fied
in
the
$JAVAH‐
FLAGS
con‐
struc‐
tion
vari‐
able
are
included
on
this
com‐
mand
line.
JAVAH‐
FLAGS Gen‐
eral
options
passed
to
the
C
header
and
stub
file
gen‐
er‐
a‐
tor
for
Java
classes.
JAVA‐
SUF‐
FIX
The
suf‐
fix
for
Java
files;
.java
by
default.
LATEX The
LaTeX
struc‐
tured
for‐
mat‐
ter
and
type‐
set‐
ter.
LATEX‐
COM The
com‐
mand
line
used
to
call
the
LaTeX
struc‐
tured
for‐
mat‐
ter
and
type‐
set‐
ter.
LATEXFLAGS
Gen‐
eral
options
passed
to
the
LaTeX
struc‐
tured
for‐
mat‐
ter
and
type‐
set‐
ter.
LEX The
lex‐
i‐
cal
ana‐
lyzer
gen‐
er‐
a‐
tor.
LEXFLAGS
Gen‐
eral
options
passed
to
the
lex‐
i‐
cal
ana‐
lyzer
gen‐
er‐
a‐
tor.
LEX‐
COM The
com‐
mand
line
used
to
call
the
lex‐
i‐
cal
ana‐
lyzer
gen‐
er‐
a‐
tor
to
gen‐
er‐
ate
a
source
file.
_LIB‐
DIRFLAGS
An
auto‐
mat‐
i‐
cally-
gen‐
er‐
ated
con‐
struc‐
tion
vari‐
able
con‐
tain‐
ing
the
linker
com‐
mand-
line
options
for
spec‐
i‐
fy‐
ing
direc‐
to‐
ries
to
be
searched
for
library.
The
value
of
$_LIB‐
DIRFLAGS
is
cre‐
ated
by
append‐
ing
$LIB‐
DIRPRE‐
FIX
and
$LIB‐
DIRSUF‐
FIX
to
the
begin‐
ning
and
end
of
each
direc‐
tory
in
$LIB‐
PATH.
LIB‐
DIRPRE‐
FIX
The
pre‐
fix
used
to
spec‐
ify
a
library
direc‐
tory
on
the
linker
com‐
mand
line.
This
will
be
appended
to
the
begin‐
ning
of
each
direc‐
tory
in
the
$LIB‐
PATH
con‐
struc‐
tion
vari‐
able
when
the
$_LIB‐
DIRFLAGS
vari‐
able
is
auto‐
mat‐
i‐
cally
gen‐
er‐
ated.
LIB‐
DIRSUF‐
FIX
The
suf‐
fix
used
to
spec‐
ify
a
library
direc‐
tory
on
the
linker
com‐
mand
line.
This
will
be
appended
to
the
end
of
each
direc‐
tory
in
the
$LIB‐
PATH
con‐
struc‐
tion
vari‐
able
when
the
$_LIB‐
DIRFLAGS
vari‐
able
is
auto‐
mat‐
i‐
cally
gen‐
er‐
ated.
_LIBFLAGS
An
auto‐
mat‐
i‐
cally-
gen‐
er‐
ated
con‐
struc‐
tion
vari‐
able
con‐
tain‐
ing
the
linker
com‐
mand-
line
options
for
spec‐
i‐
fy‐
ing
libraries
to
be
linked
with
the
result‐
ing
tar‐
get.
The
value
of
$_LIBFLAGS
is
cre‐
ated
by
append‐
ing
$LIB‐
LINKPRE‐
FIX
and
$LIB‐
LINKSUF‐
FIX
to
the
begin‐
ning
and
end
of
each
direc‐
tory
in
$LIBS.
LIB‐
LINKPRE‐
FIX
The
pre‐
fix
used
to
spec‐
ify
a
library
to
link
on
the
linker
com‐
mand
line.
This
will
be
appended
to
the
begin‐
ning
of
each
library
in
the
$LIBS
con‐
struc‐
tion
vari‐
able
when
the
$_LIBFLAGS
vari‐
able
is
auto‐
mat‐
i‐
cally
gen‐
er‐
ated.
LIB‐
LINKSUF‐
FIX
The
suf‐
fix
used
to
spec‐
ify
a
library
to
link
on
the
linker
com‐
mand
line.
This
will
be
appended
to
the
end
of
each
library
in
the
$LIBS
con‐
struc‐
tion
vari‐
able
when
the
$_LIBFLAGS
vari‐
able
is
auto‐
mat‐
i‐
cally
gen‐
er‐
ated.
LIB‐
PATH The
list
of
direc‐
to‐
ries
that
will
be
searched
for
libraries.
The
implicit
depen‐
dency
scan‐
ner
will
search
these
direc‐
to‐
ries
for
include
files.
Don't
explic‐
itly
put
include
direc‐
tory
argu‐
ments
in
$LINK‐
FLAGS
or
$SHLINK‐
FLAGS
because
the
result
will
be
non-
por‐
ta‐
ble
and
the
direc‐
to‐
ries
will
not
be
searched
by
the
depen‐
dency
scan‐
ner.
Note:
direc‐
tory
names
in
LIB‐
PATH
will
be
looked-
up
rel‐
a‐
tive
to
the
SCon‐
script
direc‐
tory
when
they
are
used
in
a
com‐
mand.
To
force
scons
to
look-
up
a
direc‐
tory
rel‐
a‐
tive
to
the
root
of
the
source
tree
use
#:
env = Environment(LIBPATH='#/libs')
The
direc‐
tory
look-
up
can
also
be
forced
using
the
Dir()
func‐
tion:
libs = Dir('libs')
env = Environment(LIBPATH=libs)
The
direc‐
tory
list
will
be
added
to
com‐
mand
lines
through
the
auto‐
mat‐
i‐
cally-
gen‐
er‐
ated
$_LIB‐
DIRFLAGS
con‐
struc‐
tion
vari‐
able,
which
is
con‐
structed
by
append‐
ing
the
val‐
ues
of
the
$LIB‐
DIRPRE‐
FIX
and
$LIB‐
DIRSUF‐
FIX
con‐
struc‐
tion
vari‐
ables
to
the
begin‐
ning
and
end
of
each
direc‐
tory
in
$LIB‐
PATH.
Any
com‐
mand
lines
you
define
that
need
the
LIB‐
PATH
direc‐
tory
list
should
include
$_LIB‐
DIRFLAGS:
env = Environment(LINKCOM="my_linker $_LIBDIRFLAGS $_LIBFLAGS -o $TARGET $SOURCE")
LIBPRE‐
FIX
The
pre‐
fix
used
for
(static)
library
file
names.
A
default
value
is
set
for
each
plat‐
form
(posix,
win32,
os2,
etc.),
but
the
value
is
over‐
rid‐
den
by
indi‐
vid‐
ual
tools
(ar,
mslib,
sgiar,
sunar,
tlib,
etc.)
to
reflect
the
names
of
the
libraries
they
cre‐
ate.
LIBPRE‐
FIXES
An
array
of
legal
pre‐
fixes
for
library
file
names.
LIBS A
list
of
one
or
more
libraries
that
will
be
linked
with
any
exe‐
cutable
pro‐
grams
cre‐
ated
by
this
envi‐
ron‐
ment.
The
library
list
will
be
added
to
com‐
mand
lines
through
the
auto‐
mat‐
i‐
cally-
gen‐
er‐
ated
$_LIBFLAGS
con‐
struc‐
tion
vari‐
able,
which
is
con‐
structed
by
append‐
ing
the
val‐
ues
of
the
$LIB‐
LINKPRE‐
FIX
and
$LIB‐
LINKSUF‐
FIX
con‐
struc‐
tion
vari‐
ables
to
the
begin‐
ning
and
end
of
each
direc‐
tory
in
$LIBS.
Any
com‐
mand
lines
you
define
that
need
the
LIBS
library
list
should
include
$_LIBFLAGS:
env = Environment(LINKCOM="my_linker $_LIBDIRFLAGS $_LIBFLAGS -o $TARGET $SOURCE")
LIB‐
SUF‐
FIX The
suf‐
fix
used
for
(static)
library
file
names.
A
default
value
is
set
for
each
plat‐
form
(posix,
win32,
os2,
etc.),
but
the
value
is
over‐
rid‐
den
by
indi‐
vid‐
ual
tools
(ar,
mslib,
sgiar,
sunar,
tlib,
etc.)
to
reflect
the
names
of
the
libraries
they
cre‐
ate.
LIB‐
SUF‐
FIXES An
array
of
legal
suf‐
fixes
for
library
file
names.
LINK The
linker.
LINK‐
FLAGS Gen‐
eral
user
options
passed
to
the
linker.
Note
that
this
vari‐
able
should
not
con‐
tain
-l
(or
sim‐
i‐
lar)
options
for
link‐
ing
with
the
libraries
listed
in
$LIBS,
nor
-L
(or
sim‐
i‐
lar)
library
search
path
options
that
scons
gen‐
er‐
ates
auto‐
mat‐
i‐
cally
from
$LIB‐
PATH.
See
_LIBFLAGS,
above,
for
the
vari‐
able
that
expands
to
library-
link
options,
and
_LIB‐
DIRFLAGS,
above,
for
the
vari‐
able
that
expands
to
library
search
path
options.
LINKCOM
The
com‐
mand
line
used
to
link
object
files
into
an
exe‐
cutable.
M4 The
M4
macro
pre‐
proces‐
sor.
M4FLAGS
Gen‐
eral
options
passed
to
the
M4
macro
pre‐
proces‐
sor.
M4COM The
com‐
mand
line
used
to
pass
files
through
the
macro
pre‐
proces‐
sor.
MAX‐
LINE‐
LENGTH The
max‐
i‐
mum
num‐
ber
of
char‐
ac‐
ters
allowed
on
an
exter‐
nal
com‐
mand
line.
On
Win32
sys‐
tems,
link
lines
longer
than
this
many
char‐
ac‐
ters
are
linke
via
a
tem‐
po‐
rary
file
name.
MSVS When
the
Mi‐
cro‐
soft
Vis‐
ual
Stu‐
dio
tools
are
ini‐
tial‐
ized,
they
set
up
this
dic‐
tio‐
nary
with
the
fol‐
low‐
ing
keys:
VER‐
SION:
the
ver‐
sion
of
MSVS
being
used
(can
be
set
via
MSVS_VER‐
SION)
VER‐
SIONS:
the
avail‐
able
ver‐
sions
of
MSVS
installed
VCIN‐
STALLDIR:
installed
direc‐
tory
of
Vis‐
ual
C++
VSIN‐
STALLDIR:
installed
direc‐
tory
of
Vis‐
ual
Stu‐
dio
FRAME‐
WORKDIR:
installed
direc‐
tory
of
the
.NET
frame‐
work
FRAME‐
WORKVER‐
SIONS:
list
of
installed
ver‐
sions
of
the
.NET
frame‐
work,
sorted
lat‐
est
to
old‐
est.
FRAME‐
WORKVER‐
SION:
lat‐
est
installed
ver‐
sion
of
the
.NET
frame‐
work
FRAME‐
WORKS‐
D‐
KDIR:
installed
loca‐
tion
of
the
.NET
SDK.
PLAT‐
FORMS‐
D‐
KDIR:
installed
loca‐
tion
of
the
Plat‐
form
SDK.
PLAT‐
FORMSDK_MOD‐
ULES:
dic‐
tio‐
nary
of
installed
Plat‐
form
SDK
mod‐
ules,
where
the
dic‐
tio‐
nary
keys
are
key‐
words
for
the
var‐
i‐
ous
mod‐
ules,
and
the
val‐
ues
are
2-tuples
where
the
first
is
the
release
date,
and
the
sec‐
ond
is
the
ver‐
sion
num‐
ber.
If
a
value
isn't
set,
it
wasn't
avail‐
able
in
the
reg‐
istry.
MSVS_IGNORE_IDE_PATHS
Tells
the
MS
Vis‐
ual
Stu‐
dio
tools
to
use
min‐
i‐
mal
INCLUDE,
LIB,
and
PATH
set‐
tings,
instead
of
the
set‐
tings
from
the
IDE.
For
Vis‐
ual
Stu‐
dio,
SCons
will
(by
default)
auto‐
mat‐
i‐
cally
deter‐
mine
where
MSVS
is
installed,
and
use
the
LIB,
INCLUDE,
and
PATH
vari‐
ables
set
by
the
IDE.
You
can
over‐
ride
this
behav‐
ior
by
set‐
ting
these
vari‐
ables
after
Envi‐
ron‐
ment
ini‐
tial‐
iza‐
tion,
or
by
set‐
ting
MSVS_IGNORE_IDE_PATHS
=
1
in
the
Envi‐
ron‐
ment
ini‐
tial‐
iza‐
tion.
Spec‐
i‐
fy‐
ing
this
will
not
leave
these
unset,
but
will
set
them
to
a
min‐
i‐
mal
set
of
paths
needed
to
run
the
tools
suc‐
cess‐
fully.
For VS6, the mininimal set is:
INCLUDE:'<VSDir>\VC98\ATL\include;<VSDir>\VC98\MFC\include;<VSDir>\VC98\include'
LIB:'<VSDir>\VC98\MFC\lib;<VSDir>\VC98\lib'
PATH:'<VSDir>\Common\MSDev98\bin;<VSDir>\VC98\bin'
For VS7, it is:
INCLUDE:'<VSDir>\Vc7\atlmfc\include;<VSDir>\Vc7\include'
LIB:'<VSDir>\Vc7\atlmfc\lib;<VSDir>\Vc7\lib'
PATH:'<VSDir>\Common7\Tools\bin;<VSDir>\Common7\Tools;<VSDir>\Vc7\bin'
Where
'<VSDir>'
is
the
installed
loca‐
tion
of
Vis‐
ual
Stu‐
dio.
MSVS_USE_MFC_DIRS
Tells
the
MS
Vis‐
ual
Stu‐
dio
tool(s)
to
use
the
MFC
direc‐
to‐
ries
in
its
default
paths
for
com‐
pil‐
ing
and
link‐
ing.
Under
MSVS
ver‐
sion
6,
set‐
ting
MSVS_USE_MFC_DIRS
to
a
non-
zero
value
adds
the
ATL\include
and
MFC\include
direc‐
to‐
ries
to
the
default
INCLUDE
exter‐
nal
envi‐
ron‐
ment
vari‐
able,
and
adds
the
MFC\lib
direc‐
tory
to
the
default
LIB
exter‐
nal
envi‐
ron‐
ment
vari‐
able.
Under
MSVS
ver‐
sion
7,
set‐
ting
MSVS_USE_MFC_DIRS
to
a
non-
zero
value
adds
the
atlmfc\include
direc‐
tory
to
the
default
INCLUDE
exter‐
nal
envi‐
ron‐
ment
vari‐
able,
and
adds
the
atlmfc\lib
direc‐
tory
to
the
default
LIB
exter‐
nal
envi‐
ron‐
ment
vari‐
able.
The
cur‐
rent
default
value
is
1,
which
means
these
direc‐
to‐
ries
are
added
to
the
paths
by
default.
This
default
value
is
likely
to
change
in
a
future
release,
so
users
who
want
the
ATL
and
MFC
val‐
ues
included
in
their
paths
are
encour‐
aged
to
enable
the
MSVS_USE_MFC_DIRS
value
explic‐
itly
to
avoid
future
incom‐
pat‐
i‐
bil‐
ity.
This
vari‐
able
has
no
effect
if
the
INCLUDE
or
LIB
envi‐
ron‐
ment
vari‐
ables
are
set
explictly.
MSVS_VER‐
SION
Sets
the
pre‐
ferred
ver‐
sion
of
MSVS
to
use.
SCons
will
(by
default)
select
the
lat‐
est
ver‐
sion
of
MSVS
installed
on
your
machine.
So,
if
you
have
ver‐
sion
6
and
ver‐
sion
7
(MSVS
.NET)
installed,
it
will
pre‐
fer
ver‐
sion
7.
You
can
over‐
ride
this
by
spec‐
i‐
fy‐
ing
the
MSVS_VER‐
SION
vari‐
able
in
the
Envi‐
ron‐
ment
ini‐
tial‐
iza‐
tion,
set‐
ting
it
to
the
appro‐
pri‐
ate
ver‐
sion
('6.0'
or
'7.0',
for
exam‐
ple).
If
the
given
ver‐
sion
isn't
installed,
tool
ini‐
tial‐
iza‐
tion
will
fail.
MSVSPRO‐
JECT‐
COM
The
action
used
to
gen‐
er‐
ate
Mi‐
cro‐
soft
Vis‐
ual
Stu‐
dio
project
and
solu‐
tion
files.
MSVSPRO‐
JECT‐
SUF‐
FIX
The
suf‐
fix
used
for
Mi‐
cro‐
soft
Vis‐
ual
Stu‐
dio
project
(DSP)
files.
The
default
value
is
.vcproj
when
using
Vis‐
ual
Stu‐
dio
ver‐
sion
7.x
(.NET),
and
.dsp
when
using
ear‐
lier
ver‐
sions
of
Vis‐
ual
Stu‐
dio.
MSVS‐
SO‐
LU‐
TION‐
SUF‐
FIX The
suf‐
fix
used
for
Mi‐
cro‐
soft
Vis‐
ual
Stu‐
dio
solu‐
tion
(DSW)
files.
The
default
value
is
.sln
when
using
Vis‐
ual
Stu‐
dio
ver‐
sion
7.x
(.NET),
and
.dsw
when
using
ear‐
lier
ver‐
sions
of
Vis‐
ual
Stu‐
dio.
no_import_lib
When
set
to
non-
zero,
sup‐
presses
cre‐
ation
of
a
cor‐
re‐
spond‐
ing
Win32
static
import
lib
by
the
SharedLi‐
brary
builder
when
used
with
MinGW
or
Mi‐
cro‐
soft
Vis‐
ual
Stu‐
dio.
This
also
sup‐
presses
cre‐
ation
of
an
export
(.exp)
file
when
using
Mi‐
cro‐
soft
Vis‐
ual
Stu‐
dio.
OBJPRE‐
FIX
The
pre‐
fix
used
for
(static)
object
file
names.
OBJ‐
SUF‐
FIX The
suf‐
fix
used
for
(static)
object
file
names.
P4 The
Per‐
force
exe‐
cutable.
P4COM The
com‐
mand
line
used
to
fetch
source
files
from
Per‐
force.
P4FLAGS
Gen‐
eral
options
that
are
passed
to
Per‐
force.
PCH The
Mi‐
cro‐
soft
Vis‐
ual
C++
pre‐
com‐
piled
header
that
will
be
used
when
com‐
pil‐
ing
object
files.
This
vari‐
able
is
ignored
by
tools
other
than
Mi‐
cro‐
soft
Vis‐
ual
C++.
When
this
vari‐
able
is
defined
SCons
will
add
options
to
the
com‐
piler
com‐
mand
line
to
cause
it
to
use
the
pre‐
com‐
piled
header,
and
will
also
set
up
the
depen‐
den‐
cies
for
the
PCH
file.
Exam‐
ple:
env['PCH'] = 'StdAfx.pch'
PCH‐
STOP This
vari‐
able
spec‐
i‐
fies
how
much
of
a
source
file
is
pre‐
com‐
piled.
This
vari‐
able
is
ignored
by
tools
other
than
Mi‐
cro‐
soft
Vis‐
ual
C++,
or
when
the
PCH
vari‐
able
is
not
being
used.
When
this
vari‐
able
is
define
it
must
be
a
string
that
is
the
name
of
the
header
that
is
included
at
the
end
of
the
pre‐
com‐
piled
por‐
tion
of
the
source
files,
or
the
empty
string
if
the
"#pragma
hrd‐
stop"
con‐
struct
is
being
used:
env['PCHSTOP'] = 'StdAfx.h'
PDB The
Mi‐
cro‐
soft
Vis‐
ual
C++
PDB
file
that
will
store
debug‐
ging
infor‐
ma‐
tion
for
object
files,
shared
libraries,
and
pro‐
grams.
This
vari‐
able
is
ignored
by
tools
other
than
Mi‐
cro‐
soft
Vis‐
ual
C++.
When
this
vari‐
able
is
defined
SCons
will
add
options
to
the
com‐
piler
and
linker
com‐
mand
line
to
cause
them
to
gen‐
er‐
ate
exter‐
nal
debug‐
ging
infor‐
ma‐
tion,
and
will
also
set
up
the
depen‐
den‐
cies
for
the
PDB
file.
Exam‐
ple:
env['PDB'] = 'hello.pdb'
PDF‐
COM A
dep‐
re‐
cated
syn‐
onym
for
$DVIPDF‐
COM.
PDF‐
PRE‐
FIX The
pre‐
fix
used
for
PDF
file
names.
PDF‐
SUF‐
FIX The
suf‐
fix
used
for
PDF
file
names.
PLAT‐
FORM The
name
of
the
plat‐
form
used
to
cre‐
ate
the
Envi‐
ron‐
ment.
If
no
plat‐
form
is
spec‐
i‐
fied
when
the
Envi‐
ron‐
ment
is
cre‐
ated,
SCons
autode‐
tects
the
plat‐
form.
env = Environment(tools = [])
if env['PLATFORM'] == 'cygwin':
Tool('mingw')(env)
else:
Tool('msvc')(env)
PROG‐
PRE‐
FIX The
pre‐
fix
used
for
exe‐
cutable
file
names.
PROG‐
SUF‐
FIX The
suf‐
fix
used
for
exe‐
cutable
file
names.
PSCOM The
com‐
mand
line
used
to
con‐
vert
TeX
DVI
files
into
a
Post‐
Script
file.
PSPRE‐
FIX The
pre‐
fix
used
for
Post‐
Script
file
names.
PSSUF‐
FIX The
pre‐
fix
used
for
Post‐
Script
file
names.
QTDIR The
qt
tool
tries
to
take
this
from
os.env‐
i‐
ron.
It
also
ini‐
tial‐
izes
all
QT_*
con‐
struc‐
tion
vari‐
ables
listed
below.
(Note
that
all
paths
are
con‐
structed
with
python's
os.path.join()
method,
but
are
listed
here
with
the
'/'
sep‐
a‐
ra‐
tor
for
eas‐
ier
read‐
ing.)
In
addi‐
tion,
the
con‐
struc‐
tion
envi‐
ron‐
ment
vari‐
ables
CPP‐
PATH,
LIB‐
PATH,
LIBS,
PRO‐
GEMIT‐
TER,
SHLIBE‐
MIT‐
TER
and
LIBE‐
MIT‐
TER
are
mod‐
i‐
fied.
Because
the
build-
per‐
for‐
mance
is
affected
when
using
this
tool,
you
have
to
explic‐
itly
spec‐
ify
it
at
Envi‐
ron‐
ment
cre‐
ation:
Environment(tools=['default','qt'])
The
qt
tool
sup‐
ports
the
fol‐
low‐
ing
oper‐
a‐
tions:
Auto‐
matic
moc
file
gen‐
er‐
a‐
tion
from
header
files.
You
do
not
have
to
spec‐
ify
moc
files
explic‐
itly,
the
tool
does
it
for
you.
How‐
ever,
there
are
a
few
pre‐
con‐
di‐
tions
to
do
so:
Your
header
file
must
have
the
same
file‐
base
as
your
imple‐
men‐
ta‐
tion
file
and
must
stay
in
the
same
direc‐
tory.
It
must
have
one
of
the
suf‐
fixes
.h,
.hpp,
.H,
.hxx,
.hh.
You
can
turn
off
auto‐
matic
moc
file
gen‐
er‐
a‐
tion
by
set‐
ting
QT_AUTOSCAN
to
0.
See
also
the
cor‐
re‐
spond‐
ing
builder
method
Moc()
Auto‐
matic
moc
file
gen‐
er‐
a‐
tion
from
cxx
files.
As
stated
in
the
qt
doc‐
u‐
men‐
ta‐
tion,
include
the
moc
file
at
the
end
of
the
cxx
file.
Note
that
you
have
to
include
the
file,
which
is
gen‐
er‐
ated
by
the
trans‐
for‐
ma‐
tion
${QT_MOC‐
CXXPRE‐
FIX}<base‐
name>${QT_MOC‐
CXXSUF‐
FIX},
by
default
<base‐
name>.moc.
A
warn‐
ing
is
gen‐
er‐
ated
after
build‐
ing
the
moc
file,
if
you
do
not
include
the
cor‐
rect
file.
If
you
are
using
Build‐
Dir,
you
may
need
to
spec‐
ify
dupli‐
cate=1.
You
can
turn
off
auto‐
matic
moc
file
gen‐
er‐
a‐
tion
by
set‐
ting
QT_AUTOSCAN
to
0.
See
also
the
cor‐
re‐
spond‐
ing
builder
method
Moc()
Auto‐
matic
han‐
dling
of
.ui
files.
The
imple‐
men‐
ta‐
tion
files
gen‐
er‐
ated
from
.ui
files
are
han‐
dled
much
the
same
as
yacc
or
lex
files.
Each
.ui
file
given
as
a
source
of
Pro‐
gram,
Library
or
SharedLi‐
brary
will
gen‐
er‐
ate
three
files,
the
dec‐
la‐
ra‐
tion
file,
the
imple‐
men‐
ta‐
tion
file
and
a
moc
file.
Because
there
are
also
gen‐
er‐
ated
head‐
ers,
you
may
need
to
spec‐
ify
dupli‐
cate=1
in
calls
to
Build‐
Dir.
See
also
the
cor‐
re‐
spond‐
ing
builder
method
Uic()
QT_AUTOSCAN
Turn
off
scan‐
ning
for
moca‐
ble
files.
Use
the
Moc
Builder
to
explicitely
spec‐
ify
files
to
run
moc
on.
QT_DEBUG
Prints
lots
of
debug‐
ging
infor‐
ma‐
tion
while
scan‐
ning
for
moc
files.
QT_LIB Default
value
is
'qt'.
You
may
want
to
set
this
to
'qt-
mt'.
QT_MOC Default
value
is
'$QTDIR/bin/moc'.
QT_MOC‐
CXXPRE‐
FIX
Default
value
is
''.
Pre‐
fix
for
moc
out‐
put
files,
when
source
is
a
cxx
file.
QT_MOC‐
CXXSUF‐
FIX
Default
value
is
'.moc'.
Suf‐
fix
for
moc
out‐
put
files,
when
source
is
a
cxx
file.
QT_MOCFROM‐
CPPFLAGS
Default
value
is
'-i'.
These
flags
are
passed
to
moc,
when
moc‐
c‐
ing
a
cpp
file.
QT_MOCFROM‐
CXXCOM
Com‐
mand
to
gen‐
er‐
ate
a
moc
file
from
a
cpp
file.
QT_MOCFROMH‐
COM
Com‐
mand
to
gen‐
er‐
ate
a
moc
file
from
a
header.
QT_MOCFROMH‐
FLAGS
Default
value
is
''.
These
flags
are
passed
to
moc,
when
moc‐
c‐
ing
a
header
file.
QT_MOCH‐
PRE‐
FIX
Default
value
is
'moc_'.
Pre‐
fix
for
moc
out‐
put
files,
when
source
is
a
header.
QT_MOCHSUF‐
FIX
Default
value
is
'$CXXFILE‐
SUF‐
FIX'.
Suf‐
fix
for
moc
out‐
put
files,
when
source
is
a
header.
QT_UIC Default
value
is
'$QTDIR/bin/uic'.
QT_UICDE‐
CLCOM
Com‐
mand
to
gen‐
er‐
ate
header
files
from
.ui
files.
QT_UICDE‐
CLFLAGS
Default
value
is
''.
These
flags
are
passed
to
uic,
when
cre‐
at‐
ing
a
a
h
file
from
a
.ui
file.
QT_UICDE‐
CL‐
PRE‐
FIX
Default
value
is
''.
Pre‐
fix
for
uic
gen‐
er‐
ated
header
files.
QT_UICDE‐
CLSUF‐
FIX
Default
value
is
'.h'.
Suf‐
fix
for
uic
gen‐
er‐
ated
header
files.
QT_UICIM‐
PLCOM
Com‐
mand
to
gen‐
er‐
ate
cxx
files
from
.ui
files.
QT_UICIM‐
PLFLAGS
Default
value
is
''.
These
flags
are
passed
to
uic,
when
cre‐
at‐
ing
a
cxx
file
from
a
.ui
file.
QT_UICIM‐
PL‐
PRE‐
FIX
Default
value
is
'uic_'.
Pre‐
fix
for
uic
gen‐
er‐
ated
imple‐
men‐
ta‐
tion
files.
QT_UICIM‐
PLSUF‐
FIX
Default
value
is
'$CXXFILE‐
SUF‐
FIX'.
Suf‐
fix
for
uic
gen‐
er‐
ated
imple‐
men‐
ta‐
tion
files.
QT_UISUF‐
FIX
Default
value
is
'.ui'.
Suf‐
fix
of
designer
input
files.
RAN‐
LIB The
ar‐
chive
indexer.
RAN‐
LIBFLAGS
Gen‐
eral
options
passed
to
the
ar‐
chive
indexer.
RC The
resource
com‐
piler
used
by
the
RES
builder.
RCCOM The
com‐
mand
line
used
by
the
RES
builder.
RCFLAGS
The
flags
passed
to
the
resource
com‐
piler
by
the
RES
builder.
RCS The
RCS
exe‐
cutable.
Note
that
this
vari‐
able
is
not
actu‐
ally
used
for
the
com‐
mand
to
fetch
source
files
from
RCS;
see
the
RCS_CO
con‐
struc‐
tion
vari‐
able,
below.
RCS_CO The
RCS
"check‐
out"
exe‐
cutable,
used
to
fetch
source
files
from
RCS.
RCS_COCOM
The
com‐
mand
line
used
to
fetch
(check‐
out)
source
files
from
RCS.
RCS_COFLAGS
Options
that
are
passed
to
the
$RCS_CO
com‐
mand.
RDirs A
func‐
tion
that
con‐
verts
a
file
name
into
a
list
of
Dir
instances
by
search‐
ing
the
repos‐
i‐
to‐
ries.
RMIC The
Java
RMI
stub
com‐
piler.
RMIC‐
COM The
com‐
mand
line
used
to
com‐
pile
stub
and
skele‐
ton
class
files
from
Java
classes
that
con‐
tain
RMI
imple‐
men‐
ta‐
tions.
Any
options
spec‐
i‐
fied
in
the
$RMICFLAGS
con‐
struc‐
tion
vari‐
able
are
included
on
this
com‐
mand
line.
RMICFLAGS
Gen‐
eral
options
passed
to
the
Java
RMI
stub
com‐
piler.
RPATH A
list
of
paths
to
search
for
shared
libraries
when
run‐
ning
pro‐
grams.
Cur‐
rently
only
used
in
the
GNU
linker
(gnulink)
and
IRIX
linker
(sgilink).
Ignored
on
plat‐
forms
and
toolchains
that
don't
sup‐
port
it.
Note
that
the
paths
added
to
RPATH
are
not
trans‐
formed
by
scons
in
any
way:
if
you
want
an
abso‐
lute
path,
you
must
make
it
abso‐
lute
your‐
self.
SCAN‐
NERS A
list
of
the
avail‐
able
implicit
depen‐
dency
scan‐
ners.
New
file
scan‐
ners
may
be
added
by
append‐
ing
to
this
list,
although
the
more
flex‐
i‐
ble
approach
is
to
as‐
so‐
ciate
scan‐
ners
with
a
spe‐
cific
Builder.
See
the
sec‐
tions
"Builder
Objects"
and
"Scan‐
ner
Objects,"
below,
for
more
infor‐
ma‐
tion.
SCCS The
SCCS
exe‐
cutable.
SCC‐
SCOM The
com‐
mand
line
used
to
fetch
source
files
from
SCCS.
SCCS‐
FLAGS Gen‐
eral
options
that
are
passed
to
SCCS.
SCC‐
S‐
GET‐
FLAGS Options
that
are
passed
specif‐
i‐
cally
to
the
SCCS
"get"
sub‐
com‐
mand.
This
can
be
set,
for
exam‐
ple,
to
-e
to
check
out
editable
files
from
SCCS.
SHCC The
C
com‐
piler
used
for
gen‐
er‐
at‐
ing
shared-
library
objects.
SHC‐
C‐
COM The
com‐
mand
line
used
to
com‐
pile
a
C
source
file
to
a
shared-
library
object
file.
Any
options
spec‐
i‐
fied
in
the
$SHC‐
CFLAGS
and
$CPPFLAGS
con‐
struc‐
tion
vari‐
ables
are
included
on
this
com‐
mand
line.
SHC‐
CFLAGS Options
that
are
passed
to
the
C
com‐
piler
to
gen‐
er‐
ate
shared-
library
objects.
SHCXX The
C++
com‐
piler
used
for
gen‐
er‐
at‐
ing
shared-
library
objects.
SHCXXCOM
The
com‐
mand
line
used
to
com‐
pile
a
C++
source
file
to
a
shared-
library
object
file.
Any
options
spec‐
i‐
fied
in
the
$SHCXXFLAGS
and
$CPPFLAGS
con‐
struc‐
tion
vari‐
ables
are
included
on
this
com‐
mand
line.
SHCXXFLAGS
Options
that
are
passed
to
the
C++
com‐
piler
to
gen‐
er‐
ate
shared-
library
objects.
SHELL A
string
nam‐
ing
the
shell
pro‐
gram
that
will
be
passed
to
the
SPAWN
func‐
tion.
See
the
SPAWN
con‐
struc‐
tion
vari‐
able
for
more
infor‐
ma‐
tion.
SHF77 The
For‐
tran
77
com‐
piler
used
for
gen‐
er‐
at‐
ing
shared-
library
objects.
You
should
nor‐
mally
set
the
$SHFOR‐
TRANC
vari‐
able,
which
spec‐
i‐
fies
the
default
For‐
tran
com‐
piler
for
all
For‐
tran
ver‐
sions.
You
only
need
to
set
$SHF77
if
you
need
to
use
a
spe‐
cific
com‐
piler
or
com‐
piler
ver‐
sion
for
For‐
tran
77
files.
SHF77COM
The
com‐
mand
line
used
to
com‐
pile
a
For‐
tran
77
source
file
to
a
shared-
library
object
file.
You
only
need
to
set
$SHF77COM
if
you
need
to
use
a
spe‐
cific
com‐
mand
line
for
For‐
tran
77
files.
You
should
nor‐
mally
set
the
$SHFOR‐
TRAN‐
COM
vari‐
able,
which
spec‐
i‐
fies
the
default
com‐
mand
line
for
all
For‐
tran
ver‐
sions.
SHF77FLAGS
Options
that
are
passed
to
the
For‐
tran
77
com‐
piler
to
gen‐
er‐
ated
shared-
library
objects.
You
only
need
to
set
$SHF77FLAGS
if
you
need
to
define
spe‐
cific
user
options
for
For‐
tran
77
files.
You
should
nor‐
mally
set
the
$SHFOR‐
TRAN‐
FLAGS
vari‐
able,
which
spec‐
i‐
fies
the
user-
spec‐
i‐
fied
options
passed
to
the
default
For‐
tran
com‐
piler
for
all
For‐
tran
ver‐
sions.
SHF77PPCOM
The
com‐
mand
line
used
to
com‐
pile
a
For‐
tran
77
source
file
to
a
shared-
library
object
file
after
first
run‐
ning
the
file
through
the
C
pre‐
proces‐
sor.
Any
options
spec‐
i‐
fied
in
the
$SHF77FLAGS
and
$CPPFLAGS
con‐
struc‐
tion
vari‐
ables
are
included
on
this
com‐
mand
line.
You
only
need
to
set
$SHF77PPCOM
if
you
need
to
use
a
spe‐
cific
C-
pre‐
proces‐
sor
com‐
mand
line
for
For‐
tran
77
files.
You
should
nor‐
mally
set
the
$SHFOR‐
TRANPP‐
COM
vari‐
able,
which
spec‐
i‐
fies
the
default
C-
pre‐
proces‐
sor
com‐
mand
line
for
all
For‐
tran
ver‐
sions.
SHF90 The
For‐
tran
90
com‐
piler
used
for
gen‐
er‐
at‐
ing
shared-
library
objects.
You
should
nor‐
mally
set
the
$SHFOR‐
TRANC
vari‐
able,
which
spec‐
i‐
fies
the
default
For‐
tran
com‐
piler
for
all
For‐
tran
ver‐
sions.
You
only
need
to
set
$SHF90
if
you
need
to
use
a
spe‐
cific
com‐
piler
or
com‐
piler
ver‐
sion
for
For‐
tran
90
files.
SHF90COM
The
com‐
mand
line
used
to
com‐
pile
a
For‐
tran
90
source
file
to
a
shared-
library
object
file.
You
only
need
to
set
$SHF90COM
if
you
need
to
use
a
spe‐
cific
com‐
mand
line
for
For‐
tran
90
files.
You
should
nor‐
mally
set
the
$SHFOR‐
TRAN‐
COM
vari‐
able,
which
spec‐
i‐
fies
the
default
com‐
mand
line
for
all
For‐
tran
ver‐
sions.
SHF90FLAGS
Options
that
are
passed
to
the
For‐
tran
90
com‐
piler
to
gen‐
er‐
ated
shared-
library
objects.
You
only
need
to
set
$SHF90FLAGS
if
you
need
to
define
spe‐
cific
user
options
for
For‐
tran
90
files.
You
should
nor‐
mally
set
the
$SHFOR‐
TRAN‐
FLAGS
vari‐
able,
which
spec‐
i‐
fies
the
user-
spec‐
i‐
fied
options
passed
to
the
default
For‐
tran
com‐
piler
for
all
For‐
tran
ver‐
sions.
SHF90PPCOM
The
com‐
mand
line
used
to
com‐
pile
a
For‐
tran
90
source
file
to
a
shared-
library
object
file
after
first
run‐
ning
the
file
through
the
C
pre‐
proces‐
sor.
Any
options
spec‐
i‐
fied
in
the
$SHF90FLAGS
and
$CPPFLAGS
con‐
struc‐
tion
vari‐
ables
are
included
on
this
com‐
mand
line.
You
only
need
to
set
$SHF90PPCOM
if
you
need
to
use
a
spe‐
cific
C-
pre‐
proces‐
sor
com‐
mand
line
for
For‐
tran
90
files.
You
should
nor‐
mally
set
the
$SHFOR‐
TRANPP‐
COM
vari‐
able,
which
spec‐
i‐
fies
the
default
C-
pre‐
proces‐
sor
com‐
mand
line
for
all
For‐
tran
ver‐
sions.
SHF95 The
For‐
tran
95
com‐
piler
used
for
gen‐
er‐
at‐
ing
shared-
library
objects.
You
should
nor‐
mally
set
the
$SHFOR‐
TRANC
vari‐
able,
which
spec‐
i‐
fies
the
default
For‐
tran
com‐
piler
for
all
For‐
tran
ver‐
sions.
You
only
need
to
set
$SHF95
if
you
need
to
use
a
spe‐
cific
com‐
piler
or
com‐
piler
ver‐
sion
for
For‐
tran
95
files.
SHF95COM
The
com‐
mand
line
used
to
com‐
pile
a
For‐
tran
95
source
file
to
a
shared-
library
object
file.
You
only
need
to
set
$SHF95COM
if
you
need
to
use
a
spe‐
cific
com‐
mand
line
for
For‐
tran
95
files.
You
should
nor‐
mally
set
the
$SHFOR‐
TRAN‐
COM
vari‐
able,
which
spec‐
i‐
fies
the
default
com‐
mand
line
for
all
For‐
tran
ver‐
sions.
SHF95FLAGS
Options
that
are
passed
to
the
For‐
tran
95
com‐
piler
to
gen‐
er‐
ated
shared-
library
objects.
You
only
need
to
set
$SHF95FLAGS
if
you
need
to
define
spe‐
cific
user
options
for
For‐
tran
95
files.
You
should
nor‐
mally
set
the
$SHFOR‐
TRAN‐
FLAGS
vari‐
able,
which
spec‐
i‐
fies
the
user-
spec‐
i‐
fied
options
passed
to
the
default
For‐
tran
com‐
piler
for
all
For‐
tran
ver‐
sions.
SHF95PPCOM
The
com‐
mand
line
used
to
com‐
pile
a
For‐
tran
95
source
file
to
a
shared-
library
object
file
after
first
run‐
ning
the
file
through
the
C
pre‐
proces‐
sor.
Any
options
spec‐
i‐
fied
in
the
$SHF95FLAGS
and
$CPPFLAGS
con‐
struc‐
tion
vari‐
ables
are
included
on
this
com‐
mand
line.
You
only
need
to
set
$SHF95PPCOM
if
you
need
to
use
a
spe‐
cific
C-
pre‐
proces‐
sor
com‐
mand
line
for
For‐
tran
95
files.
You
should
nor‐
mally
set
the
$SHFOR‐
TRANPP‐
COM
vari‐
able,
which
spec‐
i‐
fies
the
default
C-
pre‐
proces‐
sor
com‐
mand
line
for
all
For‐
tran
ver‐
sions.
SHFOR‐
TRAN The
default
For‐
tran
com‐
piler
used
for
gen‐
er‐
at‐
ing
shared-
library
objects.
SHFOR‐
TRAN‐
COM The
com‐
mand
line
used
to
com‐
pile
a
For‐
tran
source
file
to
a
shared-
library
object
file.
SHFOR‐
TRAN‐
FLAGS Options
that
are
passed
to
the
For‐
tran
com‐
piler
to
gen‐
er‐
ate
shared-
library
objects.
SHFOR‐
TRANPP‐
COM
The
com‐
mand
line
used
to
com‐
pile
a
For‐
tran
source
file
to
a
shared-
library
object
file
after
first
run‐
ning
the
file
through
the
C
pre‐
proces‐
sor.
Any
options
spec‐
i‐
fied
in
the
$SHFOR‐
TRAN‐
FLAGS
and
$CPPFLAGS
con‐
struc‐
tion
vari‐
ables
are
included
on
this
com‐
mand
line.
SHLIBPRE‐
FIX
The
pre‐
fix
used
for
shared
library
file
names.
SHLIB‐
SUF‐
FIX The
suf‐
fix
used
for
shared
library
file
names.
SHLINK The
linker
for
pro‐
grams
that
use
shared
libraries.
SHLINK‐
FLAGS
Gen‐
eral
user
options
passed
to
the
linker
for
pro‐
grams
using
shared
libraries.
Note
that
this
vari‐
able
should
not
con‐
tain
-l
(or
sim‐
i‐
lar)
options
for
link‐
ing
with
the
libraries
listed
in
$LIBS,
nor
-L
(or
sim‐
i‐
lar)
include
search
path
options
that
scons
gen‐
er‐
ates
auto‐
mat‐
i‐
cally
from
$LIB‐
PATH.
See
_LIBFLAGS,
above,
for
the
vari‐
able
that
expands
to
library-
link
options,
and
_LIB‐
DIRFLAGS,
above,
for
the
vari‐
able
that
expands
to
library
search
path
options.
SHOB‐
JPRE‐
FIX The
pre‐
fix
used
for
shared
object
file
names.
SHOB‐
J‐
SUF‐
FIX The
suf‐
fix
used
for
shared
object
file
names.
SOURCE A
reserved
vari‐
able
name
that
may
not
be
set
or
used
in
a
con‐
struc‐
tion
envi‐
ron‐
ment.
(See
"Vari‐
able
Sub‐
sti‐
tu‐
tion,"
below.)
SOURCES
A
reserved
vari‐
able
name
that
may
not
be
set
or
used
in
a
con‐
struc‐
tion
envi‐
ron‐
ment.
(See
"Vari‐
able
Sub‐
sti‐
tu‐
tion,"
below.)
SPAWN A
com‐
mand
inter‐
preter
func‐
tion
that
will
be
called
to
exe‐
cute
com‐
mand
line
strings.
The
func‐
tion
must
expect
4
argu‐
ments:
def spawn(shell, escape, cmd, args, env):
sh
is
a
string
nam‐
ing
the
shell
pro‐
gram
to
use.
escape
is
a
func‐
tion
that
can
be
called
to
escape
shell
spe‐
cial
char‐
ac‐
ters
in
the
com‐
mand
line.
cmd
is
the
path
to
the
com‐
mand
to
be
exe‐
cuted.
args
is
that
argu‐
ments
to
the
com‐
mand.
env
is
a
dic‐
tio‐
nary
of
the
envi‐
ron‐
ment
vari‐
ables
in
which
the
com‐
mand
should
be
exe‐
cuted.
SWIG The
script‐
ing
lan‐
guage
wrap‐
per
and
inter‐
face
gen‐
er‐
a‐
tor.
SWIGC‐
FILE‐
SUF‐
FIX The
suf‐
fix
that
will
be
used
for
inter‐
me‐
di‐
ate
C
source
files
gen‐
er‐
ated
by
the
script‐
ing
lan‐
guage
wrap‐
per
and
inter‐
face
gen‐
er‐
a‐
tor.
The
default
value
is
_wrap$CFILE‐
SUF‐
FIX.
By
default,
this
value
is
used
when‐
ever
the
-c++
option
is
not
spec‐
i‐
fied
as
part
of
the
SWIGFLAGS
con‐
struc‐
tion
vari‐
able.
SWIG‐
COM The
com‐
mand
line
used
to
call
the
script‐
ing
lan‐
guage
wrap‐
per
and
inter‐
face
gen‐
er‐
a‐
tor.
SWIGCXXFILE‐
SUF‐
FIX
The
suf‐
fix
that
will
be
used
for
inter‐
me‐
di‐
ate
C++
source
files
gen‐
er‐
ated
by
the
script‐
ing
lan‐
guage
wrap‐
per
and
inter‐
face
gen‐
er‐
a‐
tor.
The
default
value
is
_wrap$CFILE‐
SUF‐
FIX.
By
default,
this
value
is
used
when‐
ever
the
-c++
option
is
spec‐
i‐
fied
as
part
of
the
SWIGFLAGS
con‐
struc‐
tion
vari‐
able.
SWIGFLAGS
Gen‐
eral
options
passed
to
the
script‐
ing
lan‐
guage
wrap‐
per
and
inter‐
face
gen‐
er‐
a‐
tor.
This
is
where
you
should
set
-python,
-perl5,
-tcl,
or
what‐
ever
other
options
you
want
to
spec‐
ify
to
SWIG.
If
you
set
the
-c++
option
in
this
vari‐
able,
scons
will,
by
default,
gen‐
er‐
ate
a
C++
inter‐
me‐
di‐
ate
source
file
with
the
exten‐
sion
that
is
spec‐
i‐
fied
as
the
$CXXFILE‐
SUF‐
FIX
vari‐
able.
TAR The
tar
archiver.
TAR‐
COM The
com‐
mand
line
used
to
call
the
tar
archiver.
TARFLAGS
Gen‐
eral
options
passed
to
the
tar
archiver.
TAR‐
GET A
reserved
vari‐
able
name
that
may
not
be
set
or
used
in
a
con‐
struc‐
tion
envi‐
ron‐
ment.
(See
"Vari‐
able
Sub‐
sti‐
tu‐
tion,"
below.)
TAR‐
GETS A
reserved
vari‐
able
name
that
may
not
be
set
or
used
in
a
con‐
struc‐
tion
envi‐
ron‐
ment.
(See
"Vari‐
able
Sub‐
sti‐
tu‐
tion,"
below.)
TAR‐
SUF‐
FIX The
suf‐
fix
used
for
tar
file
names.
TEX The
TeX
for‐
mat‐
ter
and
type‐
set‐
ter.
TEX‐
COM The
com‐
mand
line
used
to
call
the
TeX
for‐
mat‐
ter
and
type‐
set‐
ter.
TEXFLAGS
Gen‐
eral
options
passed
to
the
TeX
for‐
mat‐
ter
and
type‐
set‐
ter.
TOOLS A
list
of
the
names
of
the
Tool
spec‐
i‐
fi‐
ca‐
tions
that
are
part
of
this
con‐
struc‐
tion
envi‐
ron‐
ment.
WIN32_INSERT_DEF
When
this
is
set
to
true,
a
library
build
of
a
WIN32
shared
library
(.dll
file)
will
also
build
a
cor‐
re‐
spond‐
ing
.def
file
at
the
same
time,
if
a
.def
file
is
not
already
listed
as
a
build
tar‐
get.
The
default
is
0
(do
not
build
a
.def
file).
WIN32DEF‐
PRE‐
FIX
The
pre‐
fix
used
for
WIN32
.def
file
names.
WIN32DEF‐
SUF‐
FIX
The
suf‐
fix
used
for
WIN32
.def
file
names.
YACC The
parser
gen‐
er‐
a‐
tor.
YAC‐
C‐
COM The
com‐
mand
line
used
to
call
the
parser
gen‐
er‐
a‐
tor
to
gen‐
er‐
ate
a
source
file.
YAC‐
CFLAGS Gen‐
eral
options
passed
to
the
parser
gen‐
er‐
a‐
tor.
If
$YAC‐
CFLAGS
con‐
tains
a
-d
option,
SCons
assumes
that
the
call
will
also
cre‐
ate
a
.h
file
(if
the
yacc
source
file
ends
in
a
.y
suf‐
fix)
or
a
.hpp
file
(if
the
yacc
source
file
ends
in
a
.yy
suf‐
fix)
ZIP The
zip
com‐
pres‐
sion
and
file
pack‐
ag‐
ing
util‐
ity.
ZIP‐
COM The
com‐
mand
line
used
to
call
the
zip
util‐
ity,
or
the
inter‐
nal
Python
func‐
tion
used
to
cre‐
ate
a
zip
ar‐
chive.
ZIP‐
COM‐
PRES‐
SION The
com‐
pres‐
sion
flag
from
the
Python
zip‐
file
mod‐
ule
used
by
the
inter‐
nal
Python
func‐
tion
to
con‐
trol
whether
the
zip
ar‐
chive
is
com‐
pressed
or
not.
The
default
value
is
zip‐
file.ZIP_DEFLATED,
which
cre‐
ates
a
com‐
pressed
zip
ar‐
chive.
This
value
has
no
effect
when
using
Python
1.5.2
or
if
the
zip‐
file
mod‐
ule
is
oth‐
er‐
wise
unavail‐
able.
ZIPFLAGS
Gen‐
eral
options
passed
to
the
zip
util‐
ity.
Con‐
struc‐
tion
vari‐
ables
can
be
retrieved
and
set
using
the
Dic‐
tio‐
nary
method
of
the
con‐
struc‐
tion
envi‐
ron‐
ment:
dict = env.Dictionary()
dict["CC"] = "cc"
or
using
the
[]
oper‐
a‐
tor:
env["CC"] = "cc"
Con‐
struc‐
tion
vari‐
ables
can
also
be
passed
to
the
con‐
struc‐
tion
envi‐
ron‐
ment
con‐
struc‐
tor:
env = Environment(CC="cc")
or
when
copy‐
ing
a
con‐
struc‐
tion
envi‐
ron‐
ment
using
the
Copy
method:
env2 = env.Copy(CC="cl.exe")
Configure Contexts
scons supports configure contexts, an integrated mechanism similar to
the various AC_CHECK macros in GNU autoconf for testing for the exis‐
tence of C header files, libraries, etc. In contrast to autoconf,
scons does not maintain an explicit cache of the tested values, but
uses its normal dependency tracking to keep the checked values up to
date. The following methods can be used to perform checks:
Configure(env, [custom_tests, conf_dir, log_file])
env.Configure([custom_tests, conf_dir, log_file])
This creates a configure context, which can be used to perform
checks. env specifies the environment for building the tests.
This environment may be modified when performing checks. cus‐
tom_tests is a dictionary containing custom tests. See also the
section about custom tests below. By default, no custom tests
are added to the configure context. conf_dir specifies a direc‐
tory where the test cases are built. Note that this directory
is not used for building normal targets. The default value is
the directory #/.sconf_temp. log_file specifies a file which
collects the output from commands that are executed to check for
the existence of header files, libraries, etc. The default is
the file #/config.log. If you are using the BuildDir method,
you may want to specify a subdirectory under your build direc‐
tory.
A created Configure instance has the following associated meth‐
ods:
Configure.Finish(self)
This method should be called after configuration is done. It
returns the environment as modified by the configuration checks
performed. After this method is called, no further checks can
be performed with this configuration context. However, you can
create a new Configure context to perform additional checks.
Only one context should be active at a time.
The following Checks are predefined. (This list will likely
grow larger as time goes by and developers contribute new useful
tests.)
Configure.CheckHeader(self, header, [include_quotes, language])
Checks if header is usable in the specified language. header
may be a list, in which case the last item in the list is the
header file to be checked, and the previous list items are
header files whose #include lines should precede the header line
being checked for. The optional argument include_quotes must be
a two character string, where the first character denotes the
opening quote and the second character denotes the closing
quote. By default, both characters are " (double quote). The
optional argument language should be either C or C++ and selects
the compiler to be used for the check. Returns 1 on success and
0 on failure.
Configure.CheckCHeader(self, header, [include_quotes])
This is a wrapper around Configure.CheckHeader which checks if
header is usable in the C language. header may be a list, in
which case the last item in the list is the header file to be
checked, and the previous list items are header files whose
#include lines should precede the header line being checked for.
The optional argument include_quotes must be a two character
string, where the first character denotes the opening quote and
the second character denotes the closing quote (both default to
"). Returns 1 on success and 0 on failure.
Configure.CheckCXXHeader(self, header, [include_quotes])
This is a wrapper around Configure.CheckHeader which checks if
header is usable in the C++ language. header may be a list, in
which case the last item in the list is the header file to be
checked, and the previous list items are header files whose
#include lines should precede the header line being checked for.
The optional argument include_quotes must be a two character
string, where the first character denotes the opening quote and
the second character denotes the closing quote (both default to
"). Returns 1 on success and 0 on failure.
Configure.CheckFunc(self, function_name, [language])
Checks if the specified C or C++ function is available. func‐
tion_name is the name of the function to check for. The
optional language argument should be C or C++ and selects the
compiler to be used for the check; the default is "C".
Configure.CheckLib(self, [library, symbol, header, language, autoadd])
Checks if library provides symbol. If the value of autoadd is 1
and the library provides the specified symbol, appends the
library to the LIBS construction environment variable. library
may also be None (the default), in which case symbol is checked
with the current LIBS variable, or a list of library names, in
which case each library in the list will be checked for symbol.
The default symbol is "main", which just check if you can link
against the specified library. The optional language argument
should be C or C++ and selects the compiler to be used for the
check; the default is "C". The default value for autoadd is 1.
It is assumed, that the C-language is used. This method returns
1 on success and 0 on error.
Configure.CheckLibWithHeader(self, library, header, language, [call,
autoadd])
In contrast to the Configure.CheckLib call, this call provides a
more sophisticated way to check against libraries. Again,
library specifies the library or a list of libraries to check.
header specifies a header to check for. header may be a list,
in which case the last item in the list is the header file to be
checked, and the previous list items are header files whose
#include lines should precede the header line being checked for.
language may be one of 'C','c','CXX','cxx','C++' and 'c++'.
call can be any valid expression (with a trailing ';'). The
default is 'main();'. autoadd specifies whether to add the
library to the environment (only if the check succeeds). This
method returns 1 on success and 0 on error.
Configure.CheckType(self, type_name, [includes, language])
Checks for the existence of a type defined by typedef.
type_name specifies the typedef name to check for. includes is
a string containing one or more #include lines that will be
inserted into the program that will be run to test for the exis‐
tence of the type. The optional language argument should be C
or C++ and selects the compiler to be used for the check; the
default is "C".
Example of a typical Configure usage:
env = Environment()
conf = Configure( env )
if not conf.CheckCHeader( 'math.h' ):
print 'We really need math.h!'
Exit(1)
if conf.CheckLibWithHeader( 'qt', 'qapp.h', 'c++', 'QApplication qapp(0,0);' ):
# do stuff for qt - usage, e.g.
conf.env.Append( CPPFLAGS = '-DWITH_QT' )
env = conf.Finish()
You can define your own custom checks. in addition to the pre‐
defined checks. These are passed in a dictionary to the Config‐
ure function. This dictionary maps the names of the checks to
user defined Python callables (either Python functions or class
instances implementing the __call__ method). The first argument
of the call is always a CheckContext instance followed by the
arguments, which must be supplied by the user of the check.
These CheckContext instances define the following methods:
CheckContext.Message(self, text)
Usually called before the check is started. text will be
displayed to the user, e.g. 'Checking for library X...'
CheckContext.Result(self,, res)
Usually called after the check is done. res can be
either an integer or a string. In the former case, 'ok'
(res != 0) or 'failed' (res == 0) is displayed to the
user, in the latter case the given string is displayed.
CheckContext.TryCompile(self, text, extension)
Checks if a file with the specified extension (e.g. '.c')
containing text can be compiled using the environment's
Object builder. Returns 1 on success and 0 on failure.
CheckContext.TryLink(self, text, extension)
Checks, if a file with the specified extension (e.g.
'.c') containing text can be compiled using the environ‐
ment's Program builder. Returns 1 on success and 0 on
failure.
CheckContext.TryRun(self, text, extension)
Checks, if a file with the specified extension (e.g.
'.c') containing text can be compiled using the environ‐
ment's Program builder. On success, the program is run.
If the program executes successfully (that is, its return
status is 0), a tuple (1, outputStr) is returned, where
outputStr is the standard output of the program. If the
program fails execution (its return status is non-zero),
then (0, '') is returned.
CheckContext.TryAction(self, action, [text, extension])
Checks if the specified action with an optional source
file (contents text , extension extension = '' ) can be
executed. action may be anything which can be converted
to a scons Action. On success, (1, outputStr) is
returned, where outputStr is the content of the target
file. On failure (0, '') is returned.
CheckContext.TryBuild(self, builder, [text, extension])
Low level implementation for testing specific builds; the
methods above are based on this method. Given the
Builder instance builder and the optional text of a
source file with optional extension, this method returns
1 on success and 0 on failure. In addition, self.lastTar‐
get is set to the build target node, if the build was
successful.
Example for implementing and using custom tests:
def CheckQt(context, qtdir):
context.Message( 'Checking for qt ...' )
lastLIBS = context.env['LIBS']
lastLIBPATH = context.env['LIBPATH']
lastCPPPATH= context.env['CPPPATH']
context.env.Append(LIBS = 'qt', LIBPATH = qtdir + '/lib', CPPPATH = qtdir + '/include' )
ret = context.TryLink("""
#include <qapp.h>
int main(int argc, char **argv) {
QApplication qapp(argc, argv);
return 0;
}
""")
if not ret:
context.env.Replace(LIBS = lastLIBS, LIBPATH=lastLIBPATH, CPPPATH=lastCPPPATH)
context.Result( ret )
return ret
env = Environment()
conf = Configure( env, custom_tests = { 'CheckQt' : CheckQt } )
if not conf.CheckQt('/usr/lib/qt'):
print 'We really need qt!'
Exit(1)
env = conf.Finish()
Construction Variable Options
Often when building software, various options need to be specified at
build time that are not known when the SConstruct/SConscript files are
written. For example, libraries needed for the build may be in non-
standard locations, or site-specific compiler options may need to be
passed to the compiler. scons provides a mechanism for overridding
construction variables from the command line or a text-based SConscript
file through an Options object. To create an Options object, call the
Options() function:
Options([files], [args])
This creates an Options object that will read construction vari‐
ables from the file or list of filenames specified in files. If
no files are specified, or the files argument is None, then no
files will be read. The optional argument args is a dictionary
of values that will override anything read from the specified
files; it is primarily intended to be passed the ARGUMENTS dic‐
tionary that holds variables specified on the command line.
Example:
opts = Options('custom.py')
opts = Options('overrides.py', ARGUMENTS)
opts = Options(None, {FOO:'expansion', BAR:7})
Options objects have the following methods:
Add(key, [help, default, validator, converter])
This adds a customizable construction variable to the
Options object. key is the name of the variable. help
is the help text for the variable. default is the
default value of the variable. validator is called to
validate the value of the variable, and should take three
arguments: key, value, and environment converter is
called to convert the value before putting it in the
environment, and should take a single argument: value.
Example:
opts.Add('CC', 'The C compiler')
AddOptions(list)
A wrapper script that adds multiple customizable
construction variables to an Options object. list
is a list of tuple or list objects that contain
the arguments for an individual call to the Add
method.
opt.AddOptions(
('debug', '', 0),
('CC', 'The C compiler'),
('VALIDATE', 'An option for testing validation',
'notset', validator, None),
)
Update(env, [args])
This updates a construction environment env
with the customized construction variables.
Normally this method is not called
directly, but is called indirectly by pass‐
ing the Options object to the Environment()
function:
env = Environment(options=opts)
Save(filename, env)
This saves the currently set options
into a script file named filename
that can be used on the next invoca‐
tion to automatically load the cur‐
rent settings. This method combined
with the Options method can be used
to support caching of options
between runs.
env = Environment()
opts = Options(['options.cache', 'custom.py'])
opts.Add(...)
opts.Update(env)
opts.Save('options.cache', env)
GenerateHelpText(env, [sort])
This generates help text doc‐
umenting the customizable
construction variables suit‐
able to passing in to the
Help() function. env is the
construction environment that
will be used to get the
actual values of customizable
variables. Calling with an
optional sort function will
cause the output to be sorted
by the specified argument.
The specific sort function
should take two arguments and
return -1, 0 or 1 (like the
standard Python cmp func‐
tion).
Help(opts.GenerateHelpText(env))
Help(opts.GenerateHelpText(env, sort=cmp))
The text based SConscript
file is executed as a Python
script, and the global vari‐
ables are queried for custom‐
izable construction vari‐
ables. Example:
CC = 'my_cc'
To make it more conve‐
nient to work with
customizable Options,
scons provides a num‐
ber of functions that
make it easy to set up
various types of
Options:
BoolOption(key, help,
default)
Return a tuple
of arguments to
set up a Bool‐
ean option.
The option will
use the speci‐
fied name key,
have a default
value of
default, and
display the
specified help
text. The
option will
interpret the
values y, yes,
t, true, 1, on
and all as
true, and the
values n, no,
f, false, 0,
off and none as
false.
EnumOption(key, help,
default, allowed_val‐
ues, [map, ignore‐
case])
Return a tuple
of arguments to
set up an
option whose
value may be
one of a speci‐
fied list of
legal enumer‐
ated values.
The option will
use the speci‐
fied name key,
have a default
value of
default, and
display the
specified help
text. The
option will
only support
those values in
the
allowed_values
list. The
optional map
argument is a
dictionary that
can be used to
convert input
values into
specific legal
values in the
allowed_values
list. If the
value of
ignore_case is
0 (the
default), then
the values are
case-sensitive.
If the value of
ignore_case is
1, then values
will be matched
case-insensi‐
tive. If the
value of
ignore_case is
1, then values
will be matched
case-insensi‐
tive, and all
input values
will be con‐
verted to lower
case.
ListOption(key, help,
default, names)
Return a tuple
of arguments to
set up an
option whose
value may be
one or more of
a specified
list of legal
enumerated val‐
ues. The
option will use
the specified
name key, have
a default value
of default, and
display the
specified help
text. The
option will
only support
the values all,
none, or the
values in the
names list.
More than one
value may be
specified, with
all values sep‐
arated by com‐
mas.
PackageOption(key,
help, default)
Return a tuple
of arguments to
set up an
option whose
value is a path
name of a pack‐
age that may be
enabled, dis‐
abled or given
an explicit
path name. The
option will use
the specified
name key, have
a default value
of default, and
display the
specified help
text. The
option will
support the
values yes,
true, on,
enable or
search, in
which case the
specified
default will be
used, or the
option may be
set to an arbi‐
trary string
(typically the
path name to a
package that is
being enabled).
The option will
also support
the values no,
false, off or
disable to dis‐
able use of the
specified
option.
PathOption(key, help,
default)
Return a tuple
of arguments to
set up an
option whose
value is
expected to be
a path name.
The option will
use the speci‐
fied name key,
have a default
value of
default, and
display the
specified help
text.
These functions make it con‐
venient to create a number of
options with consistent
behavior in a single call to
the AddOptions method:
opts.AddOptions(
BoolOption('warnings', 'compilation with -Wall and similiar', 1),
EnumOption('debug', 'debug output and symbols', 'no'
allowed_values=('yes', 'no', 'full'),
map={}, ignorecase=0), # case sensitive
ListOption('shared',
'libraries to build as shared libraries',
'all',
names = list_of_libs),
PackageOption('x11',
'use X11 installed here (yes = search some places)',
'yes'),
PathOption('qtdir', 'where the root of Qt is installed', qtdir),
)
File and Directory Nodes
The File() and Dir() functions return File and Dir Nodes, respectively.
python objects, respectively. Those objects have several user-visible
attributes and methods that are often useful:
path The build path of the given file or directory. This path is
relative to the top-level directory (where the SConstruct file
is found). The build path is the same as the source path if
build_dir is not being used.
abspath
The absolute build path of the given file or directory.
srcnode()
The srcnode() method returns another File or Dir object repre‐
senting the source path of the given File or Dir. The
# Get the current build dir's path, relative to top.
Dir('.').path
# Current dir's absolute path
Dir('.').abspath
# Next line is always '.', because it is the top dir's path relative to itself.
Dir('#.').path
File('foo.c').srcnode().path # source path of the given source file.
# Builders also return File objects:
foo = env.Program('foo.c')
print "foo will be built in %s"%foo.path
EXTENDING SCONS
Builder Objects
scons can be extended to build different types of targets by adding new
Builder objects to a construction environment. In general, you should
only need to add a new Builder object when you want to build a new type
of file or other external target. If you just want to invoke a differ‐
ent compiler or other tool to build a Program, Object, Library, or any
other type of output file for which scons already has an existing
Builder, it is generally much easier to use those existing Builders in
a construction environment that sets the appropriate construction vari‐
ables (CC, LINK, etc.).
Builder objects are created using the Builder function. The Builder
function accepts the following arguments:
action The command line string used to build the target from the
source. action can also be: a list of strings representing the
command to be executed and its arguments (suitable for enclosing
white space in an argument), a dictionary mapping source file
name suffixes to any combination of command line strings (if the
builder should accept multiple source file extensions), a Python
function; an Action object (see the next section); or a list of
any of the above.
An action function takes three arguments: source - a list of
source nodes, target - a list of target nodes, env - the con‐
struction environment.
prefix The prefix that will be prepended to the target file name. This
may be a simple string, or a callable object that takes two
arguments, a construction environment and a list of sources, and
returns a prefix.
b = Builder("build_it < $SOURCE > $TARGET"
prefix = "file-")
def gen_prefix(env, sources):
return "file-" + env['PLATFORM'] + '-'
b = Builder("build_it < $SOURCE > $TARGET"
prefix = gen_prefix)
suffix The suffix that will be appended to the target file name.
This may be a simple string, or a callable object that
takes two arguments, a construction environment and a
list of sources, and returns a suffix. If the suffix is
a string, then scons will append a '.' to the beginning
of the suffix if it's not already there. The string
returned by callable object is untouched and must append
its own '.' to the beginning if one is desired.
b = Builder("build_it < $SOURCE > $TARGET"
suffix = "file-"
def gen_suffix(env, sources):
return "." + env['PLATFORM'] + "-file"
b = Builder("build_it < $SOURCE > $TARGET"
suffix = gen_suffix)
src_suffix
The expected source file name suffix.
target_scanner
A Scanner object that will be invoked to find
implicit dependencies for this target file. This
keyword argument should be used for Scanner
objects that find implicit dependencies based only
on the target file and the construction environ‐
ment, not for implicit (See the section "Scanner
Objects," below, for information about creating
Scanner objects.)
source_scanner
A Scanner object that will be invoked to find
implicit dependences in any source files used to
build this target file. This is where you would
specify a scanner to find things like #include
lines in source files. (See the section "Scanner
Objects," below, for information about creating
Scanner objects.)
target_factory
A factory function that the Builder will use to
turn any targets specified as strings into SCons
Nodes. By default, SCons assumes that all targets
are files. Other useful target_factory values
include Dir, for when a Builder creates a direc‐
tory target, and Entry, for when a Builder can
create either a file or directory target.
Example:
MakeDirectoryBuilder = Builder(action=my_mkdir, target_factory=Dir)
env = Environment()
env.Append(BUILDERS = {'MakeDirectory':MakeDirectoryBuilder})
env.MakeDirectory('new_directory')
source_factory
A factory function that the Builder will
use to turn any sources specified as
strings into SCons Nodes. By default,
SCons assumes that all source are files.
Other useful source_factory values include
Dir, for when a Builder uses a directory as
a source, and Entry, for when a Builder can
use files or directories (or both) as
sources.
Example:
CollectBuilder = Builder(action=my_mkdir, source_factory=Entry)
env = Environment()
env.Append(BUILDERS = {'Collect':CollectBuilder})
env.Collect('archive', ['directory_name', 'file_name'])
emitter
A function or list of functions to
manipulate the target and source
lists before dependencies are estab‐
lished and the target(s) are actu‐
ally built. emitter can also be a
string containing a construction
variable to expand to an emitter
function or list of functions, or a
dictionary mapping source file suf‐
fixes to emitter functions. (Only
the suffix of the first source file
is used to select the actual emitter
function from an emitter dictio‐
nary.)
An emitter function takes three
arguments: source - a list of source
nodes, target - a list of target
nodes, env - the construction envi‐
ronment. An emitter must return a
tuple containing two lists, the list
of targets to be built by this
builder, and the list of sources for
this builder.
Example:
def e(target, source, env):
return (target + ['foo.foo'], source + ['foo.src'])
# Simple association of an emitter function with a Builder.
b = Builder("my_build < $TARGET > $SOURCE",
emitter = e)
def e2(target, source, env):
return (target + ['bar.foo'], source + ['bar.src'])
# Simple association of a list of emitter functions with a Builder.
b = Builder("my_build < $TARGET > $SOURCE",
emitter = [e, e2])
# Calling an emitter function through a construction variable.
env = Environment(MY_EMITTER = e)
b = Builder("my_build < $TARGET > $SOURCE",
emitter = '$MY_EMITTER')
# Calling a list of emitter functions through a construction variable.
env = Environment(EMITTER_LIST = [e, e2])
b = Builder("my_build < $TARGET > $SOURCE",
emitter = '$EMITTER_LIST')
# Associating multiple emitters with different file
# suffixes using a dictionary.
def e_suf1(target, source, env):
return (target + ['another_target_file'], source)
def e_suf2(target, source, env):
return (target, source + ['another_source_file'])
b = Builder("my_build < $TARGET > $SOURCE",
emitter = {'.suf1' : e_suf1,
'.suf2' : e_suf2})
The generator and action
arguments must not both be
used for the same Builder.
multi Specifies whether this
builder is allowed to be
called multiple times for the
same target file(s). The
default is 0, which means the
builder can not be called
multiple times for the same
target file(s). Calling a
builder multiple times for
the same target simply adds
additional source files to
the target; it is not allowed
to change the environment
associated with the target,
specify addition environment
overrides, or associate a
different builder with the
target.
env A construction environment
that can be used to fetch
source code using this
Builder. (Note that this
environment is not used for
normal builds of normal tar‐
get files, which use the
environment that was used to
call the Builder for the tar‐
get file.)
generator
A function that returns a
list of actions that will be
executed to build the tar‐
get(s) from the source(s).
The returned action(s) may be
an Action object, or anything
that can be converted into an
Action object (see the next
section).
The generator function takes
four arguments: source - a
list of source nodes, target
- a list of target nodes, env
- the construction environ‐
ment, for_signature - a Bool‐
ean value that specifies
whether the generator is
being called for generating a
build signature (as opposed
to actually executing the
command). Example:
def g(source, target, env, for_signature):
return [["gcc", "-c", "-o"] + target + source]
b = Builder(generator=g)
src_builder
Specifies a builder to
use when a source file
name suffix does not
match any of the suf‐
fixes of the builder.
Using this argument
produces a multi-stage
builder.
single_source
Specifies that this
builder expects
exactly one source
file per call. Giving
more than one source
files without target
files results in
implicitely calling
the builder multiple
times (once for each
source given). Giving
multiple source files
together with target
files results in a
UserError exception.
The generator and action
arguments must not both be
used for the same Builder.
env A construction environment
that can be used to fetch
source code using this
Builder. (Note that this
environment is not used for
normal builds of normal tar‐
get files, which use the
environment that was used to
call the Builder for the tar‐
get file.)
b = Builder(action="build < $SOURCE > $TARGET")
env = Environment(BUILDERS = {'MyBuild' : b})
env.MyBuild('foo.out', 'foo.in', my_arg = 'xyzzy')
Any additional keyword arguments
supplied when a Builder object is
created (that is, when the Builder()
function is called) will be set in
the executing construction environ‐
ment when the Builder object is
called. The canonical example here
would be to set a construction vari‐
able to the repository of a source
code system.
Any additional keyword arguments
supplied when a Builder object is
called will only be associated with
the target created by that particu‐
lar Builder call (and any other
files built as a result of the
call).
These extra keyword arguments are
passed to the following functions:
command generator functions, func‐
tion Actions, and emitter functions.
Action Objects
The Builder() function will turn its action keyword argument into an
appropriate internal Action object. You can also explicity create
Action objects using the Action() global function, which can then be
passed to the Builder() function. This can be used to configure an
Action object more flexibly, or it may simply be more efficient than
letting each separate Builder object create a separate Action when mul‐
tiple Builder objects need to do the same thing.
The Action() global function returns an appropriate object for the
action represented by the type of the first argument:
Action If the first argument is already an Action object, the object is
simply returned.
String If the first argument is a string, a command-line Action is
returned.
Action('$CC -c -o $TARGET $SOURCES')
List If the first argument is a list, then a list of Action
objects is returned. An Action object is created as nec‐
essary for each element in the list. If an element
within the list is itself a list, the internal list is
the command and arguments to be executed via the command
line. This allows white space to be enclosed in an argu‐
ment by defining a command in a list within a list:
Action([['cc', '-c', '-DWHITE SPACE', '-o', '$TARGET', '$SOURCES']])
Function
If the first argument is a Python function, a
function Action is returned. The Python function
takes three keyword arguments, target (a Node
object representing the target file), source (a
Node object representing the source file) and env
(the construction environment used for building
the target file). The target and source arguments
may be lists of Node objects if there is more than
one target file or source file. The actual target
and source file name(s) may be retrieved from
their Node objects via the built-in Python str()
function:
target_file_name = str(target)
source_file_names = map(lambda x: str(x), source)
The function should return 0 or None to
indicate a successful build of the target
file(s). The function may raise an excep‐
tion or return a non-zero exit status to
indicate an unsuccessful build.
def build_it(target = None, source = None, env = None):
# build the target from the source
return 0
a = Action(build_it)
The second, optional argument is a Python
function that returns a string to be
printed to describe the action being exe‐
cuted. Like a function to build a file,
this function takes three arguments: target
(a Node object representing the target
file), source (a Node object representing
the source file) and env (a construction
environment). The target and source argu‐
ments may be lists of Node objects if there
is more than one target file or source
file. Examples:
def build_it(target, source, env):
# build the target from the source
return 0
def string_it(target, source, env):
return "building '%s' from '%s'" % (target[0], source[0])
# Use a positional argument.
a = Action(build_it, string_it)
# Alternatively, use a keyword argument.
a = Action(build_it, strfunction=string_it)
The third, also optional argument is
a list of construction variables
whose values will be included in the
signature of the Action when decid‐
ing whether a target should be
rebuilt because the action changed.
This is necessary whenever you want
a target to be rebuilt when a spe‐
cific construction variable changes,
because the underlying Python code
for a function will not change when
the value of the construction vari‐
able does.
def build_it(target, source, env):
# build the target from the 'XXX' construction variable
open(target[0], 'w').write(env['XXX'])
return 0
def string_it(target, source):
return "building '%s' from '%s'" % (target[0], source[0])
# Use positional arguments.
a = Action(build_it, string_it, ['XXX'])
# Alternatively, use a keyword argument.
a = Action(build_it, varlist=['XXX'])
If the action argument is not
one of the above, None is
returned.
Miscellaneous Action Functions
scons supplies a number of functions that arrange for various common
file and directory manipulations to be performed. These are similar in
concept to "tasks" in the Ant build tool, although the implementation
is slightly different. These functions do not actually perform the
specified action at the time the function is called, but instead return
an Action object that can be executed at the appropriate time. (In
Object-Oriented terminology, these are actually Action Factory func‐
tions that return Action objects.)
In practice, there are two natural ways that these Action Functions are
intended to be used.
First, if you need to perform the action at the time the SConscript
file is being read, you can use the Execute global function to do so:
Execute(Touch('file'))
Second, you can use these functions to supply Actions in a list
for use by the Command method. This can allow you to perform
more complicated sequences of file manipulation without relying
on platform-specific external commands: that
env = Environment(TMPBUILD = '/tmp/builddir')
env.Command('foo.out', 'foo.in',
[Mkdir('$TMPBUILD'),
Copy('${SOURCE.dir}', '$TMPBUILD')
"cd $TMPBUILD && make",
Delete('$TMPBUILD')])
Chmod(dest, mode)
Returns an Action object that changes the permis‐
sions on the specified dest file or directory to
the specified mode. Examples:
Execute(Chmod('file', 0755))
env.Command('foo.out', 'foo.in',
[Copy('$TARGET', '$SOURCE'),
Chmod('$TARGET', 0755)])
Copy(dest, src)
Returns an Action object that will copy the
src source file or directory to the dest
destination file or directory. Examples:
Execute(Copy('foo.output', 'foo.input'))
env.Command('bar.out', 'bar.in',
Copy('$TARGET', '$SOURCE'))
Delete(entry, [must_exist])
Returns an Action that deletes the
specified entry, which may be a file
or a directory tree. If a directory
is specified, the entire directory
tree will be removed. If the
must_exist flag is set, then a
Python error will be thrown if the
specified entry does not exist; the
default is must_exist=0, that is,
the Action will silently do nothing
if the entry does not exist. Exam‐
ples:
Execute(Delete('/tmp/buildroot'))
env.Command('foo.out', 'foo.in',
[Delete('${TARGET.dir}'),
MyBuildAction])
Execute(Delete('file_that_must_exist', must_exist=1))
Mkdir(dir)
Returns an Action that cre‐
ates the specified directory
dir . Examples:
Execute(Mkdir('/tmp/outputdir'))
env.Command('foo.out', 'foo.in',
[Mkdir('/tmp/builddir',
Copy('$SOURCE', '/tmp/builddir')
"cd /tmp/builddir && ])
Move(dest, src)
Returns an Action that
moves the specified
src file or directory
to the specified dest
file or directory.
Examples:
Execute(Move('file.destination', 'file.source'))
env.Command('output_file', 'input_file',
[MyBuildAction,
Move('$TARGET', 'file_created_by_MyBuildAction')])
Touch(file)
Returns an
Action that
updates the
modification
time on the
specified file.
Examples:
Execute(Touch('file_to_be_touched'))
env.Command('marker', 'input_file',
[MyBuildAction,
Touch('$TARGET')])
Variable Substitution
Before executing a command, scons performs construction variable inter‐
polation on the strings that make up the command line of builders.
Variables are introduced by a $ prefix. Besides construction vari‐
ables, scons provides the following variables for each command execu‐
tion:
TARGET The file name of the target being built, or the file name of the
first target if multiple targets are being built.
TARGETS
The file names of all targets being built.
SOURCE The file name of the source of the build command, or the file
name of the first source if multiple sources are being built.
SOURCES
The file names of the sources of the build command.
(Note that the above variables are reserved and may not be set
in a construction environment.)
For example, given the construction variable CC='cc', targets=['foo'],
and sources=['foo.c', 'bar.c']:
action='$CC -c -o $TARGET $SOURCES'
would produce the command line:
cc -c -o foo foo.c bar.c
Variable names may be surrounded by curly braces ({}) to
separate the name from the trailing characters. Within
the curly braces, a variable name may have a Python slice
subscript appended to select one or more items from a
list. In the previous example, the string:
${SOURCES[1]}
would produce:
bar.c
Additionally, a variable name may have the
following special modifiers appended within
the enclosing curly braces to modify the
interpolated string:
base The base path of the file name,
including the directory path but
excluding any suffix.
dir The name of the directory in which
the file exists.
file The file name, minus any directory
portion.
filebase
Just the basename of the file, minus
any suffix and minus the directory.
suffix Just the file suffix.
abspath
The absolute path name of the file.
posix The POSIX form of the path, with
directories separated by / (forward
slashes) not backslashes. This is
sometimes necessary on Win32 systems
when a path references a file on
other (POSIX) systems.
srcpath
The directory and file name to the
source file linked to this file
through BuildDir. If this file
isn't linked, it just returns the
directory and filename unchanged.
srcdir The directory containing the source
file linked to this file through
BuildDir. If this file isn't
linked, it just returns the direc‐
tory part of the filename.
rsrcpath
The directory and file name to the
source file linked to this file
through BuildDir. If the file does
not exist locally but exists in a
Repository, the path in the Reposi‐
tory is returned. If this file
isn't linked, it just returns the
directory and filename unchanged.
rsrcdir
The Repository directory containing
the source file linked to this file
through BuildDir. If this file
isn't linked, it just returns the
directory part of the filename.
For example, the specified target will
expand as follows for the corresponding
modifiers:
$TARGET => sub/dir/file.x
${TARGET.base} => sub/dir/file
${TARGET.dir} => sub/dir
${TARGET.file} => file.x
${TARGET.filebase} => file
${TARGET.suffix} => .x
${TARGET.abspath} => /top/dir/sub/dir/file.x
BuildDir('sub/dir','src')
$SOURCE => sub/dir/file.x
${SOURCE.srcpath} => src/file.x
${SOURCE.srcdir} => src
Repository('/usr/repository')
$SOURCE => sub/dir/file.x
${SOURCE.rsrcpath} => /usr/repository/src/file.x
${SOURCE.rsrcdir} => /usr/repository/src
Lastly, a variable name may be a
callable Python function associated
with a construction variable in the
environment. The function should
take four arguments: target - a list
of target nodes, source - a list of
source nodes, env - the construction
environment, for_signature - a Bool‐
ean value that specifies whether the
function is being called for gener‐
ating a build signature. SCons will
insert whatever the called function
returns into the expanded string:
def foo(target, source, env, for_signature):
return "bar"
# Will expand $BAR to "bar baz"
env=Environment(FOO=foo, BAR="$FOO baz")
You can use this feature to
pass arguments to a Python
function by creating a
callable class that stores
one or more arguments in an
object, and then uses them
when the __call__() method is
called. Note that in this
case, the entire variable
expansion must be enclosed by
curly braces so that the
arguments will be associated
with the instantiation of the
class:
class foo:
def __init__(self, arg):
self.arg = arg
def __call__(self, target, source, env, for_signature):
return arg + " bar"
# Will expand $BAR to "my argument bar baz"
env=Environment(FOO=foo, BAR="${FOO('my argument')} baz")
The special pseudo-
variables $( and $)
may be used to sur‐
round parts of a com‐
mand line that may
change without causing
a rebuild--that is,
which are not included
in the signature of
target files built
with this command.
All text between $(
and $) will be removed
from the command line
before it is added to
file signatures, and
the $( and $) will be
removed before the
command is executed.
For example, the com‐
mand line:
echo Last build occurred $( $TODAY $). > $TARGET
would execute
the command:
echo Last build occurred $TODAY. > $TARGET
but the
command
signa‐
ture
added to
any tar‐
get
files
would
be:
echo Last build occurred . > $TARGET
SCons
uses
the
fol‐
low‐
ing
rules
when
con‐
vert‐
ing
con‐
struc‐
tion
vari‐
ables
into
com‐
mand
lines:
String When
the
value
is
a
string
it
is
inter‐
preted
as
a
space
delim‐
ited
list
of
com‐
mand
line
argu‐
ments.
List When
the
value
is
a
list
it
is
inter‐
preted
as
a
list
of
com‐
mand
line
argu‐
ments.
Each
ele‐
ment
of
the
list
is
con‐
verted
to
a
string.
Other Any‐
thing
that
is
not
a
list
or
string
is
con‐
verted
to
a
string
and
inter‐
preted
as
a
sin‐
gle
com‐
mand
line
argu‐
ment.
New‐
line New‐
line
char‐
ac‐
ters
(\n)
delimit
lines.
The
new‐
line
pars‐
ing
is
done
after
all
other
pars‐
ing,
so
it
is
not
pos‐
si‐
ble
for
argu‐
ments
(e.g.
file
names)
to
con‐
tain
embed‐
ded
new‐
line
char‐
ac‐
ters.
This
lim‐
i‐
ta‐
tion
will
likely
go
away
in
a
future
ver‐
sion
of
SCons.
Scanner Objects
You can use the Scanner function to define objects to scan new file
types for implicit dependencies. Scanner accepts the following argu‐
ments:
function
A Python function that will process the Node (file) and return a
list of strings (file names) representing the implicit dependen‐
cies found in the contents. The function takes three or four
arguments:
def scanner_function(node, env, path):
def scanner_function(node, env, path, arg):
The node argument is the internal SCons node representing the
file. Use str(node) to fetch the name of the file, and
node.get_contents() to fetch contents of the file.
The env argument is the construction environment for the scan.
Fetch values from it using the env.Dictionary() method.
The path argument is a tuple (or list) of directories that can
be searched for files. This will usually be the tuple returned
by the path_function argument (see below).
The arg argument is the argument supplied when the scanner was
created, if any.
name The name of the Scanner. This is mainly used to identify the
Scanner internally.
argument
An optional argument that, if specified, will be passed to the
scanner function (described above) and the path function (speci‐
fied below).
skeys An optional list that can be used to determine which scanner
should be used for a given Node. In the usual case of scanning
for file names, this argument will be a list of suffixes for the
different file types that this Scanner knows how to scan. If
the argument is a string, then it will be expanded into a list
by the current environment.
path_function
A Python function that takes two or three arguments: a construc‐
tion environment, directory Node, and optional argument supplied
when the scanner was created. The path_function returns a tuple
of directories that can be searched for files to be returned by
this Scanner object.
node_class
The class of Node that should be returned by this Scanner
object. Any strings or other objects returned by the scanner
function that are not of this class will be run through the
node_factory function.
node_factory
A Python function that will take a string or other object and
turn it into the appropriate class of Node to be returned by
this Scanner object.
scan_check
An optional Python function that takes two arguments, a Node
(file) and a construction environment, and returns whether the
Node should, in fact, be scanned for dependencies. This check
can be used to eliminate unnecessary calls to the scanner func‐
tion when, for example, the underlying file represented by a
Node does not yet exist.
recursive
An optional flag that specifies whether this scanner should be
re-invoked on the dependency files returned by the scanner.
When this flag is not set, the Node subsystem will only invoke
the scanner on the file being scanned, and not (for example)
also on the files specified by the #include lines in the file
being scanned.
SYSTEM-SPECIFIC BEHAVIOR
SCons and its configuration files are very portable, due largely to its
implementation in Python. There are, however, a few portability issues
waiting to trap the unwary.
.C file suffix
SCons handles the upper-case .C file suffix differently, depending on
the capabilities of the underlying system. On a case-sensitive system
such as Linux or UNIX, SCons treats a file with a .C suffix as a C++
source file. On a case-insensitive system such as Windows, SCons
treats a file with a .C suffix as a C source file.
.F file suffix
SCons handles the upper-case .F file suffix differently, depending on
the capabilities of the underlying system. On a case-sensitive system
such as Linux or UNIX, SCons treats a file with a .F suffix as a For‐
tran source file that is to be first run through the standard C pre‐
processor. On a case-insensitive system such as Windows, SCons treats
a file with a .F suffix as a Fortran source file that should not be run
through the C preprocessor.
WIN32: Cygwin Tools and Cygwin Python vs. Windows Pythons
Cygwin supplies a set of tools and utilities that let users work on a
Windows system using a more POSIX-like environment. The Cygwin tools,
including Cygwin Python, do this, in part, by sharing an ability to
interpret UNIX-like path names. For example, the Cygwin tools will
internally translate a Cygwin path name like /cygdrive/c/mydir to an
equivalent Windows pathname of C:/mydir (equivalent to C:\mydir).
Versions of Python that are built for native Windows execution, such as
the python.org and ActiveState versions, do not have the Cygwin path
name semantics. This means that using a native Windows version of
Python to build compiled programs using Cygwin tools (such as gcc,
bison, and flex) may yield unpredictable results. "Mixing and match‐
ing" in this way can be made to work, but it requires careful attention
to the use of path names in your SConscript files.
In practice, users can sidestep the issue by adopting the following
rules: When using gcc, use the Cygwin-supplied Python interpreter to
run SCons; when using Microsoft Visual C/C++ (or some other Windows
compiler) use the python.org or ActiveState version of Python to run
SCons.
WIN32: scons.bat file
On WIN32 systems, SCons is executed via a wrapper scons.bat file. This
has (at least) two ramifications:
First, Windows command-line users that want to use variable assignment
on the command line may have to put double quotes around the assign‐
ments:
scons "FOO=BAR" "BAZ=BLEH"
Second, the Cygwin shell does not recognize this file as being
the same as an scons command issued at the command-line prompt.
You can work around this either by executing scons.bat from the
Cygwin command line, or by creating a wrapper shell script named
scons .
MinGW
The MinGW bin directory must be in your PATH environment variable or
the PATH variable under the ENV construction variable for SCons to
detect and use the MinGW tools. When running under the native Windows
Python interpreter, SCons will prefer the MinGW tools over the Cygwin
tools, if they are both installed, regardless of the order of the bin
directories in the PATH variable. If you have both MSVC and MinGW
installed and you want to use MinGW instead of MSVC, then you must
explictly tell SCons to use MinGW by passing
tools=['mingw']
to the Environment() function, because SCons will prefer the
MSVC tools over the MinGW tools.
EXAMPLES
To help you get started using SCons, this section contains a brief
overview of some common tasks.
Basic Compilation From a Single Source File
env = Environment()
env.Program(target = 'foo', source = 'foo.c')
Note: Build the file by specifying the target as an argument
("scons foo" or "scons foo.exe"). or by specifying a dot
("scons .").
Basic Compilation From Multiple Source Files
env = Environment()
env.Program(target = 'foo', source = Split('f1.c f2.c f3.c'))
Setting a Compilation Flag
env = Environment(CCFLAGS = '-g')
env.Program(target = 'foo', source = 'foo.c')
Search The Local Directory For .h Files
Note: You do not need to set CCFLAGS to specify -I options by hand.
SCons will construct the right -I options from CPPPATH.
env = Environment(CPPPATH = ['.'])
env.Program(target = 'foo', source = 'foo.c')
Search Multiple Directories For .h Files
env = Environment(CPPPATH = ['include1', 'include2'])
env.Program(target = 'foo', source = 'foo.c')
Building a Static Library
env = Environment()
env.StaticLibrary(target = 'foo', source = Split('l1.c l2.c'))
env.StaticLibrary(target = 'bar', source = ['l3.c', 'l4.c'])
Building a Shared Library
env = Environment()
env.SharedLibrary(target = 'foo', source = ['l5.c', 'l6.c'])
env.SharedLibrary(target = 'bar', source = Split('l7.c l8.c'))
Linking a Local Library Into a Program
env = Environment(LIBS = 'mylib', LIBPATH = ['.'])
env.Library(target = 'mylib', source = Split('l1.c l2.c'))
env.Program(target = 'prog', source = ['p1.c', 'p2.c'])
Defining Your Own Builder Object
Notice that when you invoke the Builder, you can leave off the target
file suffix, and SCons will add it automatically.
bld = Builder(action = 'pdftex < $SOURCES > $TARGET'
suffix = '.pdf',
src_suffix = '.tex')
env = Environment(BUILDERS = {'PDFBuilder' : bld})
env.PDFBuilder(target = 'foo.pdf', source = 'foo.tex')
# The following creates "bar.pdf" from "bar.tex"
env.PDFBuilder(target = 'bar', source = 'bar')
Note also that the above initialization overwrites the default
Builder objects, so the Environment created above can not be
used call Builders like env.Program(), env.Object(), env.Stati‐
cLibrary(), etc.
Adding Your Own Builder Object to an Environment
bld = Builder(action = 'pdftex < $SOURCES > $TARGET'
suffix = '.pdf',
src_suffix = '.tex')
env = Environment()
env.Append(BUILDERS = {'PDFBuilder' : bld})
env.PDFBuilder(target = 'foo.pdf', source = 'foo.tex')
env.Program(target = 'bar', source = 'bar.c')
You also can use other Pythonic techniques to add to the
BUILDERS construction variable, such as:
env = Environment()
env['BUILDERS]['PDFBuilder'] = bld
Defining Your Own Scanner Object
import re
include_re = re.compile(r'^include\s+(\S+)$', re.M)
def kfile_scan(node, env, path, arg):
contents = node.get_contents()
includes = include_re.findall(contents)
return includes
kscan = Scanner(name = 'kfile',
function = kfile_scan,
argument = None,
skeys = ['.k'])
scanners = Environment().Dictionary('SCANNERS')
env = Environment(SCANNERS = scanners + [kscan])
env.Command('foo', 'foo.k', 'kprocess < $SOURCES > $TARGET')
bar_in = File('bar.in')
env.Command('bar', bar_in, 'kprocess $SOURCES > $TARGET')
bar_in.target_scanner = kscan
Creating a Hierarchical Build
Notice that the file names specified in a subdirectory's SConscript
file are relative to that subdirectory.
SConstruct:
env = Environment()
env.Program(target = 'foo', source = 'foo.c')
SConscript('sub/SConscript')
sub/SConscript:
env = Environment()
# Builds sub/foo from sub/foo.c
env.Program(target = 'foo', source = 'foo.c')
SConscript('dir/SConscript')
sub/dir/SConscript:
env = Environment()
# Builds sub/dir/foo from sub/dir/foo.c
env.Program(target = 'foo', source = 'foo.c')
Sharing Variables Between SConscript Files
You must explicitly Export() and Import() variables that you want to
share between SConscript files.
SConstruct:
env = Environment()
env.Program(target = 'foo', source = 'foo.c')
Export("env")
SConscript('subdirectory/SConscript')
subdirectory/SConscript:
Import("env")
env.Program(target = 'foo', source = 'foo.c')
Building Multiple Variants From the Same Source
Use the BuildDir() method to establish one or more separate build
directories for a given source directory, then use the SConscript()
method to specify the SConscript files in the build directories:
SConstruct:
ccflags = '-DFOO'
Export("ccflags")
BuildDir('foo', 'src')
SConscript('foo/SConscript')
ccflags = '-DBAR'
Export("ccflags")
BuildDir('bar', 'src')
SConscript('bar/SConscript')
src/SConscript:
Import("ccflags")
env = Environment(CCFLAGS = ccflags)
env.Program(target = 'src', source = 'src.c')
Note the use of the Export() method to set the "ccflags" vari‐
able to a different value for each variant build.
Hierarchical Build of Two Libraries Linked With a Program
SConstruct:
env = Environment(LIBPATH = ['#libA', '#libB'])
Export('env')
SConscript('libA/SConscript')
SConscript('libB/SConscript')
SConscript('Main/SConscript')
libA/SConscript:
Import('env')
env.Library('a', Split('a1.c a2.c a3.c'))
libB/SConscript:
Import('env')
env.Library('b', Split('b1.c b2.c b3.c'))
Main/SConscript:
Import('env')
e = env.Copy(LIBS = ['a', 'b'])
e.Program('foo', Split('m1.c m2.c m3.c'))
The '#' in the LIBPATH directories specify that they're relative
to the top-level directory, so they don't turn into "Main/libA"
when they're used in Main/SConscript.
Specifying only 'a' and 'b' for the library names allows SCons
to append the appropriate library prefix and suffix for the cur‐
rent platform (for example, 'liba.a' on POSIX systems,
Customizing contruction variables from the command line.
The following would allow the C compiler to be specified on the command
line or in the file custom.py.
opts = Options('custom.py')
opts.Add('CC', 'The C compiler.')
env = Environment(options=opts)
Help(opts.GenerateHelpText(env))
The user could specify the C compiler on the command line:
scons "CC=my_cc"
or in the custom.py file:
CC = 'my_cc'
or get documentation on the options:
$ scons-h
CC: The C compiler.
default: None
actual: cc
Using Microsoft Visual C++ precompiled headers
Since windows.h includes everything and the kitchen sink, it can take
quite some time to compile it over and over again for a bunch of object
files, so Microsoft provides a mechanism to compile a set of headers
once and then include the previously compiled headers in any object
file. This technology is called precompiled headers. The general recipe
is to create a file named "StdAfx.cpp" that includes a single header
named "StdAfx.h", and then include every header you want to precompile
in "StdAfx.h", and finally include "StdAfx.h" as the first header in
all the source files you are compiling to object files. For example:
StdAfx.h:
#include <windows.h>
#include <my_big_header.h>
StdAfx.cpp:
#include <StdAfx.h>
Foo.cpp:
#include <StdAfx.h>
/* do some stuff */
Bar.cpp:
#include <StdAfx.h>
/* do some other stuff */
SConstruct:
env=Environment()
env['PCHSTOP'] = 'StdAfx.h'
env['PCH'] = env.PCH('StdAfx.cpp')[0]
env.Program('MyApp', ['Foo.cpp', 'Bar.cpp'])
For more information see the docu‐
ment for the PCH builder, and the
PCH and PCHSTOP construction vari‐
ables. To learn about the details of
precompiled headers consult the MSDN
documention for /Yc, /Yu, and /Yp.
Using Microsoft Visual C++ external debugging information
Since including debugging information in programs and shared libraries
can cause their size to increase significantly, Microsoft provides a
mechanism for including the debugging information in an external file
called a PDB file. SCons supports PDB files through the PDB construc‐
tion variable.
SConstruct:
env=Environment()
env['PDB'] = 'MyApp.pdb'
env.Program('MyApp', ['Foo.cpp', 'Bar.cpp'])
For more information see the document for the PDB construction
variable.
ENVIRONMENT
SCONS_LIB_DIR
Specifies the directory that contains the SCons Python module
directory (e.g. /home/aroach/scons-src-0.01/src/engine).
SCONSFLAGS
A string of options that will be used by scons in addition to
those passed on the command line.
SEE ALSOscons User Manual, scons Design Document, scons source code.
AUTHORS
Steven Knight <knight@baldmt.com>
Anthony Roach <aroach@electriceyeball.com>
August 2004 SCONS(1)