SCONS(1) SCONS(1)
NNAAMMEE
scons - a software construction tool
SSYYNNOOPPSSIISS
ssccoonnss [ _o_p_t_i_o_n_s... ] [ _n_a_m_e=_v_a_l... ] [ _t_a_r_g_e_t_s... ]
DDEESSCCRRIIPPTTIIOONN
The ssccoonnss utility builds software (or other files) by determining which
component pieces must be rebuilt and executing the necessary commands
to rebuild them.
By default, ssccoonnss searches for a file named _S_C_o_n_s_t_r_u_c_t, _S_c_o_n_s_t_r_u_c_t, or
_s_c_o_n_s_t_r_u_c_t (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 --ff option.
The _S_C_o_n_s_t_r_u_c_t file can specify subsidiary configuration files using
the SSCCoonnssccrriipptt(()) function. By convention, these subsidiary files are
named _S_C_o_n_s_c_r_i_p_t, although any name may be used. (Because of this nam-
ing convention, the term "SConscript files" is sometimes used to refer
generically to all ssccoonnss 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.
ssccoonnss 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. ssccoonnss, however, reads and executes all of the SCon-
script files _b_e_f_o_r_e it begins building any targets. To make this obvi-
ous, ssccoonnss 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 --QQ option.
ssccoonnss does not automatically propagate the external environment used to
execute ssccoonnss 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 ssccoonnss is invoked. This also means that if
the compiler or other commands that you want to use to build your tar-
get files are not in standard system locations, ssccoonnss will not find
them unless you explicitly set the PATH to include those locations.
Whenever you create an ssccoonnss construction environment, you can propa-
gate the value of PATH from your external environment as follows:
import os
env = Environment(ENV = {'PATH' : os.environ['PATH']})
Similarly, if the commands use external environment variables like
$PATH, $HOME, $JAVA_HOME, $LANG, $SHELL, $TERM, etc., these variables
can also be explicitly propagated:
import os
env = Environment(ENV = {'PATH' : os.environ['PATH'],
'HOME' : os.environ['HOME']})
Or you may explicitly propagate the invoking user's complete external
environment:
import os
env = Environment(ENV = os.environ['PATH'])
This comes at the expense of making your build dependent on the user's
environment being set correctly, but it may be more convenient for many
configurations.
ssccoonnss can scan known input files automatically for dependency informa-
tion (for example, #include statements in C or C++ files) and will
rebuild dependent files appropriately whenever any "included" input
file changes. ssccoonnss supports the ability to define new scanners for
unknown input file types.
ssccoonnss knows how to fetch files automatically from SCCS or RCS subdirec-
tories using SCCS, RCS or BitKeeper.
ssccoonnss is normally executed in a top-level directory containing a _S_C_o_n_-
_s_t_r_u_c_t file, optionally specifying as command-line arguments the target
file or files to be built.
By default, the command
scons
will build all target files in or below the current directory.
Explicit default targets (to be built when no targets are specified on
the command line) may be defined the SConscript file(s) using the
DDeeffaauulltt(()) function, described below.
Even when DDeeffaauulltt(()) targets are specified in the SConscript file(s),
all target files in or below the current directory may be built by
explicitly specifying the current directory (.) as a command-line tar-
get:
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 systems):
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 targets, 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 necessary. The
--cc flag removes all files necessary 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. Additional files or
directories to remove can be specified using the Clean() function.
A subset of a hierarchical tree may be built by remaining at the top-
level directory (where the _S_C_o_n_s_t_r_u_c_t file lives) and specifying the
subdirectory as the target to be built:
scons src/subdir
or by changing directory and invoking scons with the --uu option, which
traverses up the directory hierarchy until it finds the _S_C_o_n_s_t_r_u_c_t
file, and then builds targets relatively to the current subdirectory:
cd src/subdir
scons -u .
ssccoonnss supports building multiple targets in parallel via a --jj option
that takes, as its argument, the number of simultaneous tasks that may
be spawned:
scons -j 4
builds four targets in parallel, for example.
ssccoonnss can maintain a cache of target (derived) files that can be shared
between multiple builds. When caching is enabled in a SConscript file,
any target files built by ssccoonnss will be copied to the cache. If an up-
to-date target file is found in the cache, it will be retrieved from
the cache instead of being rebuilt locally. Caching behavior may be
disabled and controlled in other ways by the ----ccaacchhee--ffoorrccee, ----ccaacchhee--
ddiissaabbllee, and ----ccaacchhee--sshhooww command-line options. The ----rraannddoomm option is
useful to prevent multiple builds from trying to update the cache
simultaneously.
Values of variables to be passed to the SConscript file(s) may be spec-
ified on the command line:
scons debug=1 .
These variables are available in SConscript files through the ARGUMENTS
dictionary, and can be used in the SConscript file(s) to modify the
build in any way:
if ARGUMENTS.get('debug', 0):
env = Environment(CCFLAGS = '-g')
else:
env = Environment()
The command-line variable arguments are also available in the ARGLIST
list, indexed by their order on the command line. This allows you to
process them in order rather than by name, if necessary. ARGLIST[0]
returns a tuple containing (argname, argvalue). A Python exception is
thrown if you try to access a list member that does not exist.
ssccoonnss requires Python version 1.5.2 or later. There should be no other
dependencies or requirements to run ssccoonnss..
By default, ssccoonnss knows how to search for available programming tools
on various systems. On WIN32 systems, ssccoonnss searches in order for the
Microsoft Visual C++ tools, the MinGW tool chain, the Intel compiler
tools, and the PharLap ETS compiler. On OS/2 systems, ssccoonnss searches
in order for the OS/2 compiler, the GCC tool chain, and the Microsoft
Visual C++ tools, On SGI IRIX, IBM AIX, Hewlett Packard HP-UX, and Sun
Solaris systems, ssccoonnss searches for the native compiler tools (MIPSpro,
Visual Age, aCC, and Forte tools respectively) and the GCC tool chain.
On all other platforms, including POSIX (Linux and UNIX) platforms,
ssccoonnss searches in order for the GCC tool chain, the Microsoft Visual
C++ tools, and the Intel compiler tools. You may, of course, override
these default values by appropriate configuration of Environment con-
struction variables.
OOPPTTIIOONNSS
In general, ssccoonnss supports the same command-line options as GNU mmaakkee,
and many of those supported by ccoonnss.
-b Ignored for compatibility with non-GNU versions of mmaakkee..
-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 CCaacchheeDDiirr(). ssccoonnss
will neither retrieve files from the cache nor copy files to the
cache.
--cache-force, --cache-populate
When using CCaacchheeDDiirr(), 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 ----ccaacchhee--ddiissaabbllee option.
--cache-show
When using CCaacchheeDDiirr() 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.
--config=_m_o_d_e
This specifies how the CCoonnffiigguurree call should use or generate the
results of configuration tests. The option should be specified
from among the following choices:
--config=auto
scons will use its normal dependency mechanisms to decide if a
test must be rebuilt or not. This saves time by not running the
same configuration tests every time you invoke scons, but will
overlook changes in system header files or external commands
(such as compilers) if you don't specify those dependecies
explicitly. This is the default behavior.
--config=force
If this option is specified, all configuration tests will be re-
run regardless of whether the cached results are out of date.
This can be used to explicitly force the configuration tests to
be updated in response to an otherwise unconfigured change in a
system header file or compiler.
--config=cache
If this option is specified, no configuration tests will be
rerun and all results will be taken from cache. Note that scons
will still consider it an error if --config=cache is specified
and a necessary test does not yet have any results in the cache.
-C _d_i_r_e_c_t_o_r_y, --directory=_d_i_r_e_c_t_o_r_y
Change to the specified _d_i_r_e_c_t_o_r_y before searching for the _S_C_o_n_-
_s_t_r_u_c_t, _S_c_o_n_s_t_r_u_c_t, or _s_c_o_n_s_t_r_u_c_t file, or doing anything else.
Multiple --CC options are interpreted relative to the previous
one, and the right-most --CC option wins. (This option is nearly
equivalent to --ff ddiirreeccttoorryy//SSCCoonnssttrruucctt, except that it will
search for _S_C_o_n_s_t_r_u_c_t, _S_c_o_n_s_t_r_u_c_t, or _s_c_o_n_s_t_r_u_c_t in the speci-
fied directory.)
-D Works exactly the same way as the --uu 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=_t_y_p_e
Debug the build process. _t_y_p_e specifies what type of debugging:
--debug=count
Print how many objects are created of the various classes used
internally by SCons before and after reading the SConscript
files and before and after building targets. This 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=findlibs
Instruct the scanner that searches for libraries to print a mes-
sage about each potential library name it is searching for, and
about the actual libraries it finds.
--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=memoizer
Prints a summary of hits and misses in the Memoizer, the inter-
nal SCons subsystem for caching various values in memory instead
of recomputing them each time they're needed.
--debug=memory
Prints how much memory SCons uses before and after reading the
SConscript files and before and after building targets.
--debug=nomemoizer
Disables use of the Memoizer, the internal SCons subsystem for
caching various values in memory instead of recomputing them
each time they're needed. This provides more accurate counts of
the underlying function calls in the Python profiler output when
using the --profile= option. (When the Memoizer is used, the
profiler counts all memoized functions as being executed by the
Memoizer's wrapper calls.)
--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 debugger.
--debug=presub
Print the raw command line used to build each target before the
construction environment variables are substituted. Also shows
which targets are being built by this command. Output looks
something like this:
$ scons --debug=presub
Building myprog.o with action(s):
$SHCC $SHCCFLAGS $CPPFLAGS $_CPPINCFLAGS -c -o $TARGET $SOURCES
--debug=stacktrace
Prints an internal Python stack trace when encountering an oth-
erwise unexplained error.
--debug=stree
Print the dependency tree along with status information. This
is the same as the debug=tree option, but additional status
information is provided for each node in the tree.
--debug=time
Prints various time profiling information: the time spent exe-
cuting each build command, the total build time, the total time
spent executing build commands, the total time spent executing
SConstruct and SConscript files, and the total time spent exe-
cuting 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.
--diskcheck=_t_y_p_e_s
Enable specific checks for whether or not there is a file on
disk where the SCons configuration expects a directory (or vice
versa), and whether or not RCS or SCCS sources exist when
searching for source and include files. The _t_y_p_e_s argument can
be set to: aallll, to enable all checks explicitly (the default
behavior); nnoonnee, to disable all such checks; mmaattcchh, to check
that files and directories on disk match SCons' expected config-
uration; rrccss, to check for the existence of an RCS source for
any missing source or include files; ssccccss, to check for the
existence of an SCCS source for any missing source or include
files. Multiple checks can be specified separated by commas;
for example, ----ddiisskkcchheecckk==ssccccss,,rrccss would still check for SCCS and
RCS sources, but disable the check for on-disk matches of files
and directories. Disabling some or all of these checks can pro-
vide a performance boost for large configurations, or when the
configuration will check for files and/or directories across
networked or shared file systems, at the slight increased risk
of an incorrect build or of not handling errors gracefully (if
include files really should be found in SCCS or RCS, for exam-
ple, or if a file really does exist where the SCons configura-
tion expects a directory).
-f _f_i_l_e, --file=_f_i_l_e, --makefile=_f_i_l_e, --sconstruct=_f_i_l_e
Use _f_i_l_e 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 --HH option
for command-line option help. If no local help message is
defined, prints the standard help message about command-line
options. Exits after displaying the appropriate message.
-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 _d_i_r_e_c_t_o_r_y, --include-dir=_d_i_r_e_c_t_o_r_y
Specifies a _d_i_r_e_c_t_o_r_y to search for imported Python modules. If
several --II options are used, the directories are searched in the
order specified.
--implicit-cache
Cache implicit dependencies. This can cause ssccoonnss 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 dependencies. This
causes the implicit dependencies to be rescanned and recached.
This implies ----iimmpplliicciitt--ccaacchhee.
--implicit-deps-unchanged
Force SCons to ignore changes in the implicit dependencies.
This causes cached implicit dependencies to always be used.
This implies ----iimmpplliicciitt--ccaacchhee.
-j _N, --jobs=_N
Specifies the number of jobs (commands) to run simultaneously.
If there is more than one --jj 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=_O_R_D_E_R
There are three ways to duplicate files in a build tree: hard
links, soft (symbolic) links and copies. The default behaviour
of SCons is to prefer hard links to soft links to copies. You
can specify different behaviours with this option. _O_R_D_E_R must
be one of _h_a_r_d_-_s_o_f_t_-_c_o_p_y (the default), _s_o_f_t_-_h_a_r_d_-_c_o_p_y, _h_a_r_d_-
_c_o_p_y, _s_o_f_t_-_c_o_p_y or _c_o_p_y. SCons will attempt to duplicate files
using the mechanisms in the specified order.
-m Ignored for compatibility with non-GNU versions of mmaakkee.
--max-drift=_S_E_C_O_N_D_S
Set the maximum expected drift in the modification time of files
to _S_E_C_O_N_D_S. This value determines how long a file must be
unmodified before its cached content signature will be used
instead of calculating a new content signature (MD5 checksum) of
the file's contents. The default value is 2 days, which means a
file must have a modification time of at least two days ago in
order to have its cached content signature used. A negative
value means to never cache the content signature and to ignore
the cached value if there already is one. A value of 0 means to
always use the cached signature, no matter how old the file is.
-n, --just-print, --dry-run, --recon
No execute. Print the commands that would be executed to build
any out-of-date target files, but do not execute the commands.
--profile=_f_i_l_e
Run SCons under the Python profiler and save the results in the
specified _f_i_l_e. 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 specified targets are already up to
date, non-zero otherwise.
-Q Quiets SCons status messages about reading SConscript files,
building targets and entering directories. 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 tar-
get files. Also suppresses SCons status messages.
-S, --no-keep-going, --stop
Ignored for compatibility with GNU mmaakkee.
-t, --touch
Ignored for compatibility with GNU mmaakkee. (Touching a file to
make it appear up-to-date is unnecessary when using ssccoonnss.)
-u, --up, --search-up
Walks up the directory structure until an _S_C_o_n_s_t_r_u_c_t _, _S_c_o_n_-
_s_t_r_u_c_t or _s_c_o_n_s_t_r_u_c_t 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 --uu option except for the way
default targets are handled. When this option is used and no
targets are specified on the command line, all default targets
that are defined in the SConscript(s) in the current directory
are built, regardless of what directory the resultant targets
end up in.
-v, --version
Print the ssccoonnss version, copyright information, list of authors,
and any other relevant information. Then exit.
-w, --print-directory
Print a message containing the working directory before and
after other processing.
--warn=_t_y_p_e, --warn=no-_t_y_p_e
Enable or disable warnings. _t_y_p_e 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 deprecated features.
These warnings are enabled by default.
--warn=missing-sconscript, --warn=no-missing-sconscript
Enables or disables warnings about missing SConscript files.
These warnings are enabled by default.
--no-print-directory
Turn off -w, even if it was turned on implicitly.
-Y _r_e_p_o_s_i_t_o_r_y, --repository=_r_e_p_o_s_i_t_o_r_y
Search the specified repository for any input and target files
not found in the local directory hierarchy. Multiple --YY options
may specified, in which case the repositories are searched in
the order specified.
CCOONNFFIIGGUURRAATTIIOONN FFIILLEE RREEFFEERREENNCCEE
CCoonnssttrruuccttiioonn EEnnvviirroonnmmeennttss
A construction environment is the basic means by which the SConscript
files communicate build information to ssccoonnss. A new construction envi-
ronment is created using the EEnnvviirroonnmmeenntt 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 keyword argument may be used to
specify that an environment should be initialized for a different plat-
form:
env = Environment(platform = 'cygwin')
env = Environment(platform = 'os2')
env = Environment(platform = 'posix')
env = Environment(platform = 'win32')
Specifying a platform initializes the appropriate construction vari-
ables in the environment to use and generate file names with prefixes
and suffixes appropriate for the platform.
Note that the wwiinn3322 platform adds the SSYYSSTTEEMMDDRRIIVVEE and SSYYSSTTEEMMRROOOOTT vari-
ables from the user's external environment to the construction environ-
ment's EENNVV dictionary. This is so that any executed commands that use
sockets to connect with other systems (such as fetching source files
from external CVS repository specifications like ::ppsseerrvveerr::aannoonnyy--
mmoouuss@@ccvvss..ssoouurrcceeffoorrggee..nneett:://ccvvssrroooott//ssccoonnss) 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 environment:
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, **kw) and exists(env). The ggeenneerraattee(()) func-
tion modifies the passed-in environment to set up variables so that the
tool can be executed; it may use any keyword arguments that the user
supplies (see below) to vary its initialization. The eexxiissttss(()) function
should return a true value if the tool is available. Tools in the
toolpath are used before any of the built-in ones. For example, adding
gcc.py to the toolpath would override the built-in gcc tool. Also note
that the toolpath is stored in the environment for use by later calls
to CCooppyy() and TTooooll() methods:
base = Environment(toolpath=['custom_path'])
derived = base.Copy(tools=['custom_tool'])
derived.CustomBuilder()
The elements of the tools list may also be functions or callable
objects, in which case the Environment() method will call the specified
elements to update the new construction environment:
def my_tool(env):
env['XYZZY'] = 'xyzzy'
env = Environment(tools = [my_tool])
The individual elements of the tools list may also themselves be two-
element lists of the form (_t_o_o_l_n_a_m_e, _k_w___d_i_c_t). SCons searches for the
_t_o_o_l_n_a_m_e specification file as described above, and passes _k_w___d_i_c_t,
which must be a dictionary, as keyword arguments to the tool's ggeenneerraattee
function. The ggeenneerraattee function can use the arguments to modify the
tool's behavior by setting up the environment in different ways or oth-
erwise changing its initialization.
# in tools/my_tool.py:
def generate(env, **kw):
# Sets MY_TOOL to the value of keyword argument 'arg1' or 1.
env['MY_TOOL'] = kw.get('arg1', '1')
def exists(env):
return 1
# in SConstruct:
env = Environment(tools = ['default', ('my_tool', {'arg1': 'abc'})],
toolpath=['tools'])
The tool definition (i.e. my_tool()) can use the PLATFORM variable from
the environment it receives to customize the tool for different plat-
forms.
If no tool list is specified, then SCons will auto-detect the installed
tools using the PATH variable in the ENV construction variable and the
platform name when the Environment is constructed. Changing the PATH
variable after the Environment is constructed will not cause the tools
to be redetected.
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
intelc
jar
javac
javah
latex
lex
link
linkloc
m4
masm
midl
mingw
mslib
mslink
msvc
msvs
mwcc
mwld
nasm
pdflatex
pdftex
qt
rmic
rpcgen
sgiar
sgic++
sgicc
sgilink
sunar
sunc++
suncc
sunlink
swig
tar
tex
tlib
yacc
zip
Additionally, there is a "tool" named ddeeffaauulltt which configures the
environment with a default set of tools for the current platform.
On posix and cygwin platforms the GNU tools (e.g. gcc) are preferred by
SCons, on win32 the Microsoft tools (e.g. msvc) followed by MinGW are
preferred by SCons, and in OS/2 the IBM tools (e.g. icc) are preferred
by SCons.
BBuuiillddeerr MMeetthhooddss
Build rules are specified by calling a construction environment's
builder methods. The arguments to the builder methods are ttaarrggeett (a
list of target files) and ssoouurrccee (a list of source files).
Because long lists of file names can lead to a lot of quoting, ssccoonnss
supplies a SSpplliitt(()) 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 ssccoonnss will deduce the target file name from the source file name.
The following examples all build the executable program bbaarr (on POSIX
systems) or bbaarr..eexxee (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 keyword arguments. These overrid-
den 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 ssccoonnss are, in fact, methods of
a construction 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 con-
struction environment that consists of the tools and values that ssccoonnss
has determined are appropriate for the local system.
Builder methods that can be called without an explicit environment may
be called from custom Python modules that you import into an SConscript
file by adding the following to the Python module:
from SCons.Script import *
All builder methods return a list of Nodes that represent the target or
targets that will be built. A _N_o_d_e 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 --DD flag when compiling one specific object file:
bar_obj_list = env.StaticObject('bar.c', CPPDEFINES='-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 manipulate 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 FFllaatttteenn() supplied by scons to create a list con-
taining 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 ssttrr(()) function:
bar_obj_list = env.StaticObject('bar.c', CPPDEFINES='-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 ((bbaarr__oobbjj__lliisstt[[00]])) to get at the
Node that actually represents the object file.
Builder calls support a cchhddiirr keyword argument that specifies that the
Builder's action(s) should be executed after changing directory. If
the cchhddiirr argument is a string or a directory Node, scons will change
to the specified directory. If the cchhddiirr is not a string or Node and
is non-zero, then scons will change to the target file's directory.
# scons will change to the "sub" subdirectory
# before executing the "cp" command.
env.Command('sub/dir/foo.out', 'sub/dir/foo.in',
"cp dir/foo.in dir/foo.out",
chdir='sub')
# Because chdir is not a string, scons will change to the
# target's directory ("sub/dir") before executing the
# "cp" command.
env.Command('sub/dir/foo.out', 'sub/dir/foo.in',
"cp foo.in foo.out",
chdir=1)
Note that scons will _n_o_t automatically modify its expansion of con-
struction variables like $$TTAARRGGEETT and $$SSOOUURRCCEE when using the chdir key-
word argument--that is, the expanded file names will still be relative
to the top-level SConstruct directory, and consequently incorrect rela-
tive to the chdir directory. If you use the chdir keyword argument,
you will typically need to supply a different command line using expan-
sions like $${{TTAARRGGEETT..ffiillee}} and $${{SSOOUURRCCEE..ffiillee}} to use just the filename
portion of the targets and source.
ssccoonnss provides the following builder methods:
CFile()
env.CFile()
Builds a C source file given a lex (.l) or yacc (.y) input file.
The suffix specified by the $CFILESUFFIX construction variable
(.c by default) is automatically added to the target if it is
not already present. Example:
# 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 suffix specified by the $CXXFILESUFFIX construction
variable (.cc by default) is automatically added to the target
if it is not already present. Example:
# 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 suffix is .tex, ssccoonnss will examine the contents
of the file; if the string ooccuummeennttccllaassss or ooccuummeennttssttyyllee is
found, the file is assumed to be a LaTeX file and the target is
built by invoking the $LATEXCOM command line; otherwise, the
$TEXCOM command line is used. If the file is a LaTeX file, the
DDVVII builder method will also examine the contents of the ..aauuxx
ffiillee and invoke the $BIBTEX command line if the string bbiibbddaattaa
is found, and will examine the contents ..lloogg file and re-run the
$LATEXCOM command if the log file says it is necessary.
The suffix .dvi (hard-coded within TeX itself) is automatically
added to the target if it is not already present. Examples:
# 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 archive (.jar) file from a source tree of .class
files. If the $JARCHDIR value is set, the jjaarr command will
change to the specified directory using the --CC option. If the
contents any of the source files begin with the string MMaanniiffeesstt--
VVeerrssiioonn, the file is assumed to be a manifest and is passed to
the jjaarr command with the mm 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 underneath
the specified target directory. SCons will parse each source
.java file to find the classes (including inner classes) defined
within that file, and from that figure out the target .class
files that will be created. SCons will also search each Java
file for the Java package name, which it assumes can be found on
a line beginning with the string ppaacckkaaggee in the first column;
the resulting .class files will be placed in a directory
reflecting the specified package name. For example, the file
_F_o_o_._j_a_v_a defining a single public _F_o_o class and containing a
package name of _s_u_b_._d_i_r will generate a corresponding
_s_u_b_/_d_i_r_/_F_o_o_._c_l_a_s_s class file.
Example:
env.Java(target = 'classes', source = 'src')
env.Java(target = 'classes', source = ['src1', 'src2'])
JavaH()
env.JavaH()
Builds C header and source files for implementing Java native
methods. The target can be either a directory in which the
header files will be written, or a header file name which will
contain all of the definitions. The source can be either the
names of .class files, or the objects returned from the JJaavvaa
builder method.
If the construction variable JJAAVVAACCLLAASSSSDDIIRR is set, either in the
environment or in the call to the JJaavvaaHH builder method itself,
then the value of the variable will be stripped from the begin-
ning of any .class file names.
Examples:
# 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 synonym for the SSttaattiiccLLiibbrraarryy builder method.
LoadableModule()
env.LoadableModule()
On most systems, this is the same as SShhaarreeddLLiibbrraarryy(). On Mac OS
X (Darwin) platforms, this creates a loadable module bundle.
M4()
env.M4()
Builds an output file from an M4 input file. This uses a
default $M4FLAGS value of --EE, which considers all warnings to be
fatal and stops on the first warning when using the GNU version
of m4. Example:
env.M4(target = 'foo.c', source = 'foo.c.m4')
Moc()
env.Moc()
Builds an output file from a moc input file. Moc input files are
either header files or cxx files. This builder is only available
after using the tool 'qt'. See the QTDIR variable for more
information. Example:
env.Moc('foo.h') # generates moc_foo.cc
env.Moc('foo.cpp') # generates foo.moc
MSVSProject()
env.MSVSProject()
Builds Microsoft Visual Studio project files. This builds a
Visual Studio project file, based on the version of Visual Stu-
dio that is configured (either the latest installed version, or
the version set by MMSSVVSS__VVEERRSSIIOONN in the Environment constructor).
For VS 6, it will generate ..ddsspp and ..ddssww files, for VS 7, it
will generate ..vvccpprroojj and ..ssllnn files.
It takes several lists of filenames to be placed into the
project file, currently these are limited to ssrrccss,, iinnccss,, llooccaall--
iinnccss,, rreessoouurrcceess,, and mmiisscc.. These are pretty self explanatory,
but it should be noted that the 'srcs' list is NOT added to the
$SOURCES environment variable. This is because it represents 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 SConscript file used to call MSVSProject).
In addition to these values (which are all optional, although
not specifying any of them results in an empty project file),
the following values must be specified:
target: The name of the target .dsp or .vcproj file. The cor-
rect suffix for the version of Visual Studio must be used, but
the value
env['MSVSPROJECTSUFFIX']
will be defined to the correct value (see example below).
variant: The name of this particular variant. These are typi-
cally things like "Debug" or "Release", but really can be any-
thing you want. Multiple calls to MSVSProject with different
variants are allowed: all variants will be added to the project
file with their appropriate build targets and sources.
buildtarget: A list of SCons.Node.FS objects which is returned
from the command which builds the target. This is used to tell
SCons what to build when the 'build' button is pressed inside of
the IDE.
Example 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 synonym for the SSttaattiiccOObbjjeecctt builder method.
PCH()
env.PCH()
Builds a Microsoft Visual C++ precompiled header. Calling this
builder method returns a list of two targets: the PCH as the
first element, and the object file as the second element. Nor-
mally the object file is ignored. This builder method is only
provided when Microsoft Visual C++ is being used as the com-
piler. The PCH builder method is generally used in conjuction
with the PCH construction variable to force object files to use
the precompiled header:
env['PCH'] = env.PCH('StdAfx.cpp')[0]
PDF()
env.PDF()
Builds a .pdf file from a .dvi input file (or, by extension, a
.tex, .ltx, or .latex input file). The suffix specified by the
$PDFSUFFIX construction variable (.pdf by default) is added
automatically to the target 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')
PostScript()
env.PostScript()
Builds a .ps file from a .dvi input file (or, by extension, a
.tex, .ltx, or .latex input file). The suffix specified by the
$PSSUFFIX construction variable (.ps by default) is added auto-
matically to the target if it is not already present. Example:
# 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')
Program()
env.Program()
Builds an executable given one or more object files or C, C++,
D, or Fortran source files. If any C, C++, D or Fortran source
files are specified, then they will be automatically compiled to
object files using the OObbjjeecctt builder method; see that builder
method's description for a list of legal source file suffixes
and how they are interpreted. The target executable file prefix
(specified by the $PROGPREFIX construction variable; nothing by
default) and suffix (specified by the $PROGSUFFIX construction
variable; by default, .exe on Windows systems, nothing on POSIX
systems) are automatically added to the target if not already
present. Example:
env.Program(target = 'foo', source = ['foo.o', 'bar.c', 'baz.f'])
RES()
env.RES()
Builds a Microsoft Visual C++ resource file. This builder
method is only provided when Microsoft Visual C++ or MinGW is
being used as the compiler. The _._r_e_s (or _._o for MinGW) suffix is
added to the target name if no other suffix is given. The source
file is scanned for implicit dependencies as though it were a C
file. Example:
env.RES('resource.rc')
RMIC()
env.RMIC()
Builds stub and skeleton class files for remote objects from
Java .class files. The target is a directory relative to which
the stub and skeleton class files will be written. The source
can be the names of .class files, or the objects return from the
JJaavvaa builder method.
If the construction variable JJAAVVAACCLLAASSSSDDIIRR is set, either in the
environment or in the call to the RRMMIICC builder method itself,
then the value of the variable 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')
RPCGenClient()
env.RPCGenClient()
Generates an RPC client stub (_clnt.c) file from a specified RPC
(.x) source file. Because rpcgen only builds output files in
the local directory, the command will be executed in the source
file's directory by default.
# Builds src/rpcif_clnt.c
env.RPCGenClient('src/rpcif.x')
RPCGenHeader()
env.RPCGenHeader()
Generates an RPC header (.h) file from a specified RPC (.x)
source file. Because rpcgen only builds output files in the
local directory, the command will be executed in the source
file's directory by default.
# Builds src/rpcif.h
env.RPCGenHeader('src/rpcif.x')
RPCGenService()
env.RPCGenService()
Generates an RPC server-skeleton (_svc.c) file from a specified
RPC (.x) source file. Because rpcgen only builds output files
in the local directory, the command will be executed in the
source file's directory by default.
# Builds src/rpcif_svc.c
env.RPCGenClient('src/rpcif.x')
RPCGenXDR()
env.RPCGenXDR()
Generates an RPC XDR routine (_xdr.c) file from a specified RPC
(.x) source file. Because rpcgen only builds output files in
the local directory, the command will be executed in the source
file's directory by default.
# Builds src/rpcif_xdr.c
env.RPCGenClient('src/rpcif.x')
SharedLibrary()
env.SharedLibrary()
Builds a shared library (.so on a POSIX system, .dll on WIN32)
given one or more object files or C, C++, D or Fortran source
files. If any source files are given, then they will be auto-
matically compiled to object files. The static library prefix
and suffix (if any) are automatically added to the target. The
target library file prefix (specified by the $SHLIBPREFIX con-
struction variable; by default, lib on POSIX systems, nothing on
Windows systems) and suffix (specified by the $SHLIBSUFFIX con-
struction variable; by default, .dll on Windows systems, .so on
POSIX systems) are automatically added to the target if not
already present. Example:
env.SharedLibrary(target = 'bar', source = ['bar.c', 'foo.o'])
On WIN32 systems, the SShhaarreeddLLiibbrraarryy builder method will always
build an import (.lib) library in addition to the shared (.dll)
library, adding a .lib library with the same basename if there
is not already a .lib file explicitly listed in the targets.
Any object files listed in the ssoouurrccee must have been built for a
shared library (that is, using the SShhaarreeddOObbjjeecctt builder method).
ssccoonnss will raise an error if there is any mismatch.
On WIN32 systems, specifying "register=1" will cause the dll to
be registered after it is built using REGSVR32. The command
that is run ("regsvr32" by default) is determined by $REGSVR
construction variable, and the flags passed are determined by
$REGSVRFLAGS. By default, $REGSVRFLAGS includes "/s", to pre-
vent dialogs from popping up and requiring user attention when
it is run. If you change $REGSVRFLAGS, be sure to include "/s".
For example,
env.SharedLibrary(target = 'bar',
source = ['bar.cxx', 'foo.obj'],
register=1)
will register "bar.dll" as a COM object when it is done linking
it.
SharedObject()
env.SharedObject()
Builds an object file for inclusion in a shared library. Source
files must have one of the same set of extensions specified
above for the SSttaattiiccOObbjjeecctt builder method. On some platforms
building a shared object requires additional compiler options
(e.g. -fPIC for gcc) in addition to those needed to build a nor-
mal (static) object, but on some platforms there is no differ-
ence between a shared object and a normal (static) one. When
there is a difference, SCons will only allow shared objects to
be linked into a shared library, and will use a different suffix
for shared objects. On platforms where there is no difference,
SCons will allow both normal (static) and shared objects to be
linked into a shared library, and will use the same suffix for
shared and normal (static) objects. The target object file pre-
fix (specified by the $SHOBJPREFIX construction variable; by
default, the same as $OBJPREFIX) and suffix (specified by the
$SHOBJSUFFIX construction variable) are automatically added to
the target if not already present. Examples:
env.SharedObject(target = 'ddd', source = 'ddd.c')
env.SharedObject(target = 'eee.o', source = 'eee.cpp')
env.SharedObject(target = 'fff.obj', source = 'fff.for')
Note that the source files will be scanned according to the suffix map-
pings in SSoouurrcceeFFiilleeSSccaannnneerr object. See the section "Scanner Objects,"
below, for a more information.
StaticLibrary()
env.StaticLibrary()
Builds a static library given one or more object files or C,
C++, D or Fortran source files. If any source files are given,
then they will be automatically compiled to object files. The
static library prefix and suffix (if any) are automatically
added to the target. The target library file prefix (specified
by the $LIBPREFIX construction variable; by default, lib on
POSIX systems, nothing on Windows systems) and suffix (specified
by the $LIBSUFFIX construction variable; by default, .lib on
Windows systems, .a on POSIX systems) are automatically added to
the target if not already present. Example:
env.StaticLibrary(target = 'bar', source = ['bar.c', 'foo.o'])
Any object files listed in the ssoouurrccee must have been built for a
static library (that is, using the SSttaattiiccOObbjjeecctt builder method).
ssccoonnss will raise an error if there is any mismatch.
StaticObject()
env.StaticObject()
Builds a static object file from one or more C, C++, D, or For-
tran source files. Source files must have one of the following
extensions:
.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
.m Objective C file
.mm Objective C++ file
.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 target object file prefix (specified by the $OBJPREFIX con-
struction variable; nothing by default) and suffix (specified by
the $OBJSUFFIX construction variable; are automatically added to
the target if not already present. Examples:
env.StaticObject(target = 'aaa', source = 'aaa.c')
env.StaticObject(target = 'bbb.o', source = 'bbb.c++')
env.StaticObject(target = 'ccc.obj', source = 'ccc.f')
Note that the source files will be scanned according to the suffix
mappings in SSoouurrcceeFFiilleeSSccaannnneerr object. See the section "Scanner
Objects," below, for a more information.
Tar()
env.Tar()
Builds a tar archive of the specified files and/or directories.
Unlike most builder methods, the TTaarr builder method may be
called multiple times for a given target; each additional call
adds to the list of entries that will be built into the archive.
Any source directories will be scanned for changes to any on-
disk files, regardless of whether or not ssccoonnss knows about them
from other Builder or function calls.
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')
TypeLibrary()
env.TypeLibrary()
Builds a Windows type library (.tlb) file from and input IDL
file (.idl). In addition, it will build the associated inteface
stub and proxy source files. It names them according to the
base name of the .idl file.
For example,
env.TypeLibrary(source="foo.idl")
Will create foo.tlb, foo.h, foo_i.c, foo_p.c, and foo_data.c.
Uic()
env.Uic()
Builds a header file, an implementation file and a moc file from
an ui file. and returns the corresponding nodes in the above
order. This builder is only available after using the tool
'qt'. Note: you can specify .ui files directly as inputs for
Program, Library and SharedLibrary without using this builder.
Using the builder lets you override the standard naming conven-
tions (be careful: prefixes are always prepended to names of
built files; if you don't want prefixes, you may set them to
``). See the QTDIR variable for more information. Example:
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 archive of the specified files and/or directories.
Unlike most builder methods, the ZZiipp builder method may be
called multiple times for a given target; each additional call
adds to the list of entries that will be built into the archive.
Any source directories will be scanned for changes to any on-
disk files, regardless of whether or not ssccoonnss knows about them
from other Builder or function calls.
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')
All targets of builder methods automatically depend on their sources.
An explicit dependency can be specified using the DDeeppeennddss method of a
construction environment (see below).
In addition, ssccoonnss automatically scans source files for various pro-
gramming languages, so the dependencies do not need to be specified
explicitly. By default, SCons can C source files, C++ source files,
Fortran source files with ..FF (POSIX systems only), ..ffpppp,, or ..FFPPPP file
extensions, and assembly language files with ..SS (POSIX systems only),
..sspppp,, or ..SSPPPP files extensions for C preprocessor dependencies. SCons
also has default support for scanning D source files, You can also
write your own Scanners to add support for additional source file
types. These can be added to the default Scanner object used by the
OObbjjeecctt() SSttaattiiccOObbjjeecctt() and SShhaarreeddOObbjjeecctt() Builders by adding them to
the SSoouurrcceeFFiilleeSSccaannnneerr object as follows:
See the section "Scanner Objects," below, for a more information about
defining your own Scanner objects.
MMeetthhooddss aanndd FFuunnccttiioonnss ttoo DDoo TThhiinnggss
In addition to Builder methods, ssccoonnss 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(_a_r_g_u_m_e_n_t_s)
and if you call something through a construction environment it looks
like:
env.Function(_a_r_g_u_m_e_n_t_s)
If you can call the functionality in both ways, then both forms are
listed.
Global functions may be called from custom Python modules that you
import into an SConscript file by adding the following to the Python
module:
from SCons.Script import *
Except where otherwise noted, the same-named construction environment
method and global function provide the exact same functionality. The
only difference is that, where appropriate, calling the functionality
through a construction environment will substitute construction vari-
ables into any supplied strings. For example:
env = Environment(FOO = 'foo')
Default('$FOO')
env.Default('$FOO')
the first call to the global DDeeffaauulltt(()) function will actually add a
target named $$FFOOOO to the list of default targets, while the second call
to the eennvv..DDeeffaauulltt(()) construction environment method will expand the
value and add a target named ffoooo 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 functions supported by
ssccoonnss include:
Action(_a_c_t_i_o_n, [_s_t_r_f_u_n_c_t_i_o_n, _v_a_r_l_i_s_t])
env.Action(_a_c_t_i_o_n, [_s_t_r_f_u_n_c_t_i_o_n, _v_a_r_l_i_s_t])
Creates an Action object for the specified _a_c_t_i_o_n. See the sec-
tion "Action Objects," below, for a complete explanation of the
arguments and behavior.
AddPostAction(_t_a_r_g_e_t, _a_c_t_i_o_n)
env.AddPostAction(_t_a_r_g_e_t, _a_c_t_i_o_n)
Arranges for the specified _a_c_t_i_o_n to be performed after the
specified _t_a_r_g_e_t 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(_t_a_r_g_e_t, _a_c_t_i_o_n)
env.AddPreAction(_t_a_r_g_e_t, _a_c_t_i_o_n)
Arranges for the specified _a_c_t_i_o_n to be performed before the
specified _t_a_r_g_e_t is built. The specified action(s) may be an
Action object, or anything that can be converted into an Action
object (see below).
Alias(_a_l_i_a_s, [_t_a_r_g_e_t_s, [_a_c_t_i_o_n]])
env.Alias(_a_l_i_a_s, [_t_a_r_g_e_t_s, [_a_c_t_i_o_n]])
Creates one or more phony targets that expand to one or more
other targets. An optional _a_c_t_i_o_n (command) or list of actions
can be specified that will be executed whenever the any of the
alias targets are out-of-date. Returns the Node object repre-
senting 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. AAlliiaass can be
called multiple times for the same alias to add additional tar-
gets to the alias, or additional actions to the list for this
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'])
env.Alias('update', ['file1', 'file2'], "update_database $SOURCES")
AlwaysBuild(_t_a_r_g_e_t, ...)
env.AlwaysBuild(_t_a_r_g_e_t, ...)
Marks each given _t_a_r_g_e_t so that it is always assumed to be out
of date, and will always be rebuilt if needed. Note, however,
that AAllwwaayyssBBuuiilldd() does not add its target(s) to the default
target list, so the targets will only be built if they are spec-
ified on the command line, or are a dependent of a target speci-
fied on the command line--but they will _a_l_w_a_y_s be built if so
specified. Multiple targets can be passed in to a single call
to AAllwwaayyssBBuuiilldd().
env.Append(_k_e_y=_v_a_l, [...])
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 values of the construction variable and
the keyword argument are the same type, then the two values will
be simply added together. Otherwise, the construction variable
and the value of the keyword argument are both coerced to lists,
and the lists are added together. (See also the Prepend method,
below.)
env.Append(CCFLAGS = ' -g', FOO = ['foo.yyy'])
env.AppendENVPath(_n_a_m_e, _n_e_w_p_a_t_h, [_e_n_v_n_a_m_e, _s_e_p])
This appends new path elements to the given path in the speci-
fied external environment (EENNVV by default). This will only add
any particular path once (leaving the last one it encounters and
ignoring the rest, to preserve path order), and to help assure
this, will normalize all paths (using ooss..ppaatthh..nnoorrmmppaatthh and
ooss..ppaatthh..nnoorrmmccaassee). 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.AppendENVPath('INCLUDE', include_path)
print 'after:',env['ENV']['INCLUDE']
yields:
before: /foo:/biz
after: /biz:/foo/bar:/foo
env.AppendUnique(_k_e_y=_v_a_l, [...])
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 variable being appended to
is a list, then any value(s) that already exist in the construc-
tion variable will _n_o_t be added again to the list.
env.AppendUnique(CCFLAGS = '-g', FOO = ['foo.yyy'])
env.BitKeeper()
A factory function that returns a Builder object to be used to
fetch source files using BitKeeper. The returned Builder is
intended to be passed to the SSoouurrcceeCCooddee function.
env.SourceCode('.', env.BitKeeper())
BuildDir(_b_u_i_l_d___d_i_r, _s_r_c___d_i_r, [_d_u_p_l_i_c_a_t_e])
env.BuildDir(_b_u_i_l_d___d_i_r, _s_r_c___d_i_r, [_d_u_p_l_i_c_a_t_e])
This specifies a build directory _b_u_i_l_d___d_i_r in which to build all
derived files that would normally be built under _s_r_c___d_i_r. Mul-
tiple build directories can be set up for multiple build vari-
ants, for example. _s_r_c___d_i_r must be underneath the SConstruct
file's directory, and _b_u_i_l_d___d_i_r may not be underneath the
_s_r_c___d_i_r _.
The default behavior is for ssccoonnss to duplicate all of the files
in the tree underneath _s_r_c___d_i_r into _b_u_i_l_d___d_i_r, and then build
the derived files within the copied tree. (The duplication is
performed by linking or copying, depending on the platform; see
also the _-_-_d_u_p_l_i_c_a_t_e option.) This guarantees correct builds
regardless of whether intermediate source files are generated
during the build, where preprocessors or other scanners search
for included files, or whether individual compilers or other
invoked tools are hard-coded to put derived files in the same
directory as source files.
This behavior of making a complete copy of the source tree may
be disabled by setting _d_u_p_l_i_c_a_t_e to 0. This will cause ssccoonnss to
invoke Builders using the path names of source files in _s_r_c___d_i_r
and the path names of derived files within _b_u_i_l_d___d_i_r. This is
always more efficient than _d_u_p_l_i_c_a_t_e=1, and is usually safe for
most builds. Specifying _d_u_p_l_i_c_a_t_e=0, however, may cause build
problems if source files are generated during the build, if any
invoked tools are hard-coded to put derived files in the same
directory as the source files.
Note that specifying a BBuuiillddDDiirr works most naturally with a sub-
sidiary SConscript file in the source directory. However, you
would then call the subsidiary SConscript file not in the source
directory, but in the _b_u_i_l_d___d_i_r _, as if ssccoonnss had made a virtual
copy of the source tree regardless of the value of _d_u_p_l_i_c_a_t_e.
This is how you tell ssccoonnss 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 SSCCoonnssccrriipptt() function, described below, for another
way to specify a build directory in conjunction with calling a
subsidiary SConscript file.)
Builder(_a_c_t_i_o_n, [_a_r_g_u_m_e_n_t_s])
env.Builder(_a_c_t_i_o_n, [_a_r_g_u_m_e_n_t_s])
Creates a Builder object for the specified _a_c_t_i_o_n. See the sec-
tion "Builder Objects," below, for a complete explanation of the
arguments and behavior.
CacheDir(_c_a_c_h_e___d_i_r)
env.CacheDir(_c_a_c_h_e___d_i_r)
Specifies that ssccoonnss will maintain a cache of derived files in
_c_a_c_h_e___d_i_r _. The derived files in the cache will be shared among
all the builds using the same CCaacchheeDDiirr() call.
When a CCaacchheeDDiirr() is being used and ssccoonnss finds a derived file
that needs to be rebuilt, it will first look in the cache to see
if a derived file has already been built from identical input
files and an identical build action (as incorporated into the
MD5 build signature). If so, ssccoonnss will retrieve the file from
the cache. If the derived file is not present in the cache,
ssccoonnss will rebuild it and then place a copy of the built file in
the cache (identified by its MD5 build signature), so that it
may be retrieved by other builds that need to build the same
derived file from identical inputs.
Use of a specified CCaacchheeDDiirr(()) may be disabled for any invocation
by using the ----ccaacchhee--ddiissaabbllee option.
If the ----ccaacchhee--ffoorrccee option is used, ssccoonnss will place a copy of
_a_l_l derived files in the cache, even if they already existed and
were not built by this invocation. This is useful to populate a
cache the first time CCaacchheeDDiirr() is added to a build, or after
using the ----ccaacchhee--ddiissaabbllee option.
When using CCaacchheeDDiirr(), ssccoonnss will report, "Retrieved `file' from
cache," unless the ----ccaacchhee--sshhooww option is being used. When the
----ccaacchhee--sshhooww option is used, ssccoonnss will print the action that
_w_o_u_l_d have been used to build the file, without any indication
that the file was actually retrieved from the cache. This is
useful to generate build logs that are equivalent regardless of
whether a given derived file has been built in-place or
retrieved from the cache.
Clean(_t_a_r_g_e_t_s, _f_i_l_e_s___o_r___d_i_r_s)
env.Clean(_t_a_r_g_e_t_s, _f_i_l_e_s___o_r___d_i_r_s)
This specifies a list of files or directories which should be
removed whenever the targets are specified with the --cc command
line option. The specified targets may be a list or an individ-
ual target. Multiple calls to CClleeaann() are legal, and create new
targets or add files and directories to the clean list for the
specified targets.
Multiple files or directories should be specified either as sep-
arate arguments to the CClleeaann() method, or as a list. CClleeaann()
will also accept the return value of any of the construction
environment Builder methods. Examples:
Clean('foo', ['bar', 'baz'])
Clean('dist', env.Program('hello', 'hello.c'))
Clean(['foo', 'bar'], 'something_else_to_clean')
Command(_t_a_r_g_e_t, _s_o_u_r_c_e, _a_c_t_i_o_n, [_k_e_y=_v_a_l, ...])
env.Command(_t_a_r_g_e_t, _s_o_u_r_c_e, _a_c_t_i_o_n, [_k_e_y=_v_a_l, ...])
Executes a specific action (or list of actions) to build a tar-
get file or files. This is more convenient than defining a sep-
arate Builder object for a single special-case build.
As a special case, the ssoouurrccee__ssccaannnneerr keyword argument can be
used to specify a Scanner object that will be used to scan the
sources. (The global DDiirrSSccaannnneerr object can be used if any of
the sources will be directories that must be scanned on-disk for
changes to files that aren't already specified in other Builder
of function calls.)
Any other keyword arguments specified override any same-named
existing construction variables.
An action can be an external command, specified as a string, or
a callable Python object; see "Action Objects," below, for more
complete information. Also note that a string specifying an
external command may be preceded by an @@ (at-sign) to suppress
printing the command in question, or by a -- (hyphen) to ignore
the exit status of the external command. Examples:
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 ])
Configure(_e_n_v, [_c_u_s_t_o_m___t_e_s_t_s, _c_o_n_f___d_i_r, _l_o_g___f_i_l_e, _c_o_n_f_i_g___h])
env.Configure([_c_u_s_t_o_m___t_e_s_t_s, _c_o_n_f___d_i_r, _l_o_g___f_i_l_e, _c_o_n_f_i_g___h])
Creates a Configure object for integrated functionality similar
to GNU autoconf. See the section "Configure Contexts," below,
for a complete explanation of the arguments and behavior.
env.Copy([_k_e_y=_v_a_l, ...])
Return a separate copy of a construction environment. If there
are any keyword arguments specified, they are added to the
returned copy, overwriting any existing values for the keywords.
env2 = env.Copy()
env3 = env.Copy(CCFLAGS = '-g')
Additionally, a list of tools and a toolpath may be specified,
as in the Environment constructor:
def MyTool(env): env['FOO'] = 'bar'
env4 = env.Copy(tools = ['msvc', MyTool])
env.CVS(_r_e_p_o_s_i_t_o_r_y, _m_o_d_u_l_e)
A factory function that returns a Builder object to be used to
fetch source files from the specified CVS _r_e_p_o_s_i_t_o_r_y. The
returned Builder is intended to be passed to the SSoouurrcceeCCooddee
function.
The optional specified _m_o_d_u_l_e will be added to the beginning of
all repository path names; this can be used, in essence, to
strip initial directory names from the repository path names, so
that you only have to replicate part of the repository directory
hierarchy in your local build directory:
# 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(_t_a_r_g_e_t_s)
env.Default(_t_a_r_g_e_t_s)
This specifies a list of default targets, which will be built by
ssccoonnss if no explicit targets are given on the command line.
Multiple calls to DDeeffaauulltt() are legal, and add to the list of
default targets.
Multiple targets should be specified as separate arguments to
the DDeeffaauulltt() method, or as a list. DDeeffaauulltt() will also accept
the Node returned by any of a construction environment's builder
methods. Examples:
Default('foo', 'bar', 'baz')
env.Default(['a', 'b', 'c'])
hello = env.Program('hello', 'hello.c')
env.Default(hello)
An argument to DDeeffaauulltt() of NNoonnee will clear all default targets.
Later calls to DDeeffaauulltt() will add to the (now empty) default-
target list like normal.
The current list of targets added using the DDeeffaauulltt() function
or method is available in the DDEEFFAAUULLTT__TTAARRGGEETTSS list; see below.
DefaultEnvironment([_a_r_g_s])
Creates and returns a default construction environment object.
This construction environment is used internally by SCons in
order to execute many of the global functions in this list, and
to fetch source files transparently from source code management
systems.
Depends(_t_a_r_g_e_t, _d_e_p_e_n_d_e_n_c_y)
env.Depends(_t_a_r_g_e_t, _d_e_p_e_n_d_e_n_c_y)
Specifies an explicit dependency; the target file(s) will be
rebuilt whenever the dependency file(s) has changed. This
should only be necessary for cases where the dependency is not
caught by a Scanner for the file.
env.Depends('foo', 'other-input-file-for-foo')
env.Dictionary([_v_a_r_s])
Returns a dictionary object containing copies of all of the con-
struction variables in the environment. If there are any vari-
able names specified, only the specified construction variables
are returned in the dictionary.
dict = env.Dictionary()
cc_dict = env.Dictionary('CC', 'CCFLAGS', 'CCCOM')
Dir(_n_a_m_e, [_d_i_r_e_c_t_o_r_y])
env.Dir(_n_a_m_e, [_d_i_r_e_c_t_o_r_y])
This returns a Directory Node, an object that represents the
specified directory _n_a_m_e. _n_a_m_e can be a relative or absolute
path. _d_i_r_e_c_t_o_r_y is an optional directory that will be used as
the parent directory. If no _d_i_r_e_c_t_o_r_y is specified, the current
script's directory is used as the parent.
Directory Nodes can be used anywhere you would supply a string
as a directory name to a Builder method or function. Directory
Nodes have attributes and methods that are useful in many situa-
tions; see "File and Directory Nodes," below.
env.Dump([_k_e_y])
Returns a pretty printable representation of the environment.
_k_e_y, if not _N_o_n_e, should be a string containing the name of the
variable of interest.
This SConstruct:
env=Environment()
print env.Dump('CCCOM')
will print:
env=Environment()
print env.Dump()
will print:
{ 'AR': 'ar',
'ARCOM': '$AR $ARFLAGS $TARGET $SOURCES0RANLIB $RANLIBFLAGS $TARGET',
'ARFLAGS': ['r'],
'AS': 'as',
'ASCOM': '$AS $ASFLAGS -o $TARGET $SOURCES',
'ASFLAGS': [],
...
EnsurePythonVersion(_m_a_j_o_r, _m_i_n_o_r)
env.EnsurePythonVersion(_m_a_j_o_r, _m_i_n_o_r)
Ensure that the Python version is at least _m_a_j_o_r._m_i_n_o_r. This
function will print out an error message and exit SCons with a
non-zero exit code if the actual Python version is not late
enough.
EnsurePythonVersion(2,2)
EnsureSConsVersion(_m_a_j_o_r, _m_i_n_o_r, [_r_e_v_i_s_i_o_n])
env.EnsureSConsVersion(_m_a_j_o_r, _m_i_n_o_r, [_r_e_v_i_s_i_o_n])
Ensure that the SCons version is at least _m_a_j_o_r_._m_i_n_o_r, or
_m_a_j_o_r_._m_i_n_o_r_._r_e_v_i_s_i_o_n. if _r_e_v_i_s_i_o_n is specified. This function
will print out an error message and exit SCons with a non-zero
exit code if the actual SCons version is not late enough.
EnsureSConsVersion(0,14)
EnsureSConsVersion(0,96,90)
Environment([_k_e_y=_v_a_l_u_e, ...])
env.Environment([_k_e_y=_v_a_l_u_e, ...])
Return a new construction environment initialized with the spec-
ified _k_e_y=_v_a_l_u_e pairs.
Execute(_a_c_t_i_o_n, [_s_t_r_f_u_n_c_t_i_o_n, _v_a_r_l_i_s_t])
env.Execute(_a_c_t_i_o_n, [_s_t_r_f_u_n_c_t_i_o_n, _v_a_r_l_i_s_t])
Executes an Action object. The specified _a_c_t_i_o_n may be an
Action object (see the section "Action Objects," below, for a
complete explanation of the arguments and behavior), or it may
be a command-line string, list of commands, or executable Python
function, each of which will be converted into an Action object
and then executed. The exit value of the command or return
value of the Python function will be returned.
Exit([_v_a_l_u_e])
env.Exit([_v_a_l_u_e])
This tells ssccoonnss to exit immediately with the specified _v_a_l_u_e.
A default exit value of 00 (zero) is used if no value is speci-
fied.
Export(_v_a_r_s)
env.Export(_v_a_r_s)
This tells ssccoonnss to export a list of variables from the current
SConscript file to all other SConscript files. The exported
variables are kept in a global collection, so subsequent calls
to EExxppoorrtt() will over-write previous exports that have the same
name. Multiple variable names can be passed to EExxppoorrtt() as sep-
arate arguments or as a list. A dictionary can be used to map
variables to a different name when exported. Both local vari-
ables and global variables can be exported. Examples:
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 SSCCoonnssccrriipptt() function supports an _e_x_p_o_r_t_s argument
that makes it easier to to export a variable or set of variables
to a single SConscript file. See the description of the SSCCoonn--
ssccrriipptt() function, below.
File(_n_a_m_e, [_d_i_r_e_c_t_o_r_y])
env.File(_n_a_m_e, [_d_i_r_e_c_t_o_r_y])
This returns a File Node, an object that represents the speci-
fied file _n_a_m_e. _n_a_m_e can be a relative or absolute path.
_d_i_r_e_c_t_o_r_y is an optional directory that will be used as the par-
ent directory.
File Nodes can be used anywhere you would supply a string as a
file name to a Builder method or function. File Nodes have
attributes and methods that are useful in many situations; see
"File and Directory Nodes," below.
FindFile(_f_i_l_e, _d_i_r_s)
env.FindFile(_f_i_l_e, _d_i_r_s)
Search for _f_i_l_e in the path specified by _d_i_r_s. _f_i_l_e may be a
list of file names or a single file name. In addition to search-
ing for files that exist in the filesytem, this function also
searches for derived files that have not yet been built.
foo = env.FindFile('foo', ['dir1', 'dir2'])
Flatten(_s_e_q_u_e_n_c_e)
env.Flatten(_s_e_q_u_e_n_c_e)
Takes a sequence (that is, a Python list or tuple) that may con-
tain nested sequences and returns a flattened list containing
all of the individual elements in any sequence. This can be
helpful for collecting the lists returned by calls to Builders;
other Builders will automatically flatten lists specified as
input, but direct Python manipulation of these lists does not:
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)
GetBuildPath(_f_i_l_e, [_._._.])
env.GetBuildPath(_f_i_l_e, [_._._.])
Returns the ssccoonnss path name (or names) for the specified _f_i_l_e
(or files). The specified _f_i_l_e or files may be ssccoonnss Nodes or
strings representing path names.
GetLaunchDir()
env.GetLaunchDir()
Returns the absolute path name of the directory from which ssccoonnss
was initially invoked. This can be useful when using the --uu, --UU
or --DD options, which internally change to the directory in which
the SSCCoonnssttrruucctt file is found.
GetOption(_n_a_m_e)
env.GetOption(_n_a_m_e)
This function provides a way to query a select subset of the
scons command line options from a SConscript file. See _S_e_t_O_p_-
_t_i_o_n() for a description of the options available.
Help(_t_e_x_t)
env.Help(_t_e_x_t)
This specifies help text to be printed if the --hh argument is
given to ssccoonnss. If HHeellpp is called multiple times, the text is
appended together in the order that HHeellpp is called.
Ignore(_t_a_r_g_e_t, _d_e_p_e_n_d_e_n_c_y)
env.Ignore(_t_a_r_g_e_t, _d_e_p_e_n_d_e_n_c_y)
The specified dependency file(s) will be ignored when deciding
if the target file(s) need to be rebuilt.
env.Ignore('foo', 'foo.c')
env.Ignore('bar', ['bar1.h', 'bar2.h'])
Import(_v_a_r_s)
env.Import(_v_a_r_s)
This tells ssccoonnss to import a list of variables into the current
SConscript file. This will import variables that were exported
with EExxppoorrtt() or in the _e_x_p_o_r_t_s argument to SSCCoonnssccrriipptt(). Vari-
ables exported by SSCCoonnssccrriipptt() have precedence. Multiple vari-
able names can be passed to IImmppoorrtt() as separate arguments or as
a list. The variable "*" can be used to import all variables.
Examples:
Import("env")
Import("env", "variable")
Import(["env", "variable"])
Import("*")
Install(_d_i_r, _s_o_u_r_c_e)
env.Install(_d_i_r, _s_o_u_r_c_e)
Installs one or more files in a destination directory. The file
names remain the same.
env.Install(dir = '/usr/local/bin', source = ['foo', 'bar'])
InstallAs(_t_a_r_g_e_t, _s_o_u_r_c_e)
env.InstallAs(_t_a_r_g_e_t, _s_o_u_r_c_e)
Installs one or more files as specific file names, allowing
changing a file name as part of the installation. It is an
error if the target and source list different numbers 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'])
Literal(_s_t_r_i_n_g)
env.Literal(_s_t_r_i_n_g)
The specified _s_t_r_i_n_g will be preserved as-is and not have con-
struction variables expanded.
Local(_t_a_r_g_e_t_s)
env.Local(_t_a_r_g_e_t_s)
The specified _t_a_r_g_e_t_s will have copies made in the local tree,
even if an already up-to-date copy exists in a repository.
Returns a list of the target Node or Nodes.
env.ParseConfig(_c_o_m_m_a_n_d, [_f_u_n_c_t_i_o_n, _u_n_i_q_u_e])
Calls the specified _f_u_n_c_t_i_o_n to modify the environment as speci-
fied by the output of _c_o_m_m_a_n_d _. The default _f_u_n_c_t_i_o_n expects
the output of a typical _*_-_c_o_n_f_i_g _c_o_m_m_a_n_d (for example, ggttkk--ccoonn--
ffiigg) and adds the options to the appropriate construction vari-
ables. By default, duplicate values are not added to any con-
struction variables; you can specify uunniiqquuee==00 to allow duplicate
values to be added.
By default, --LL, --ll, --WWaa, --WWll, --WWpp, --II and other options, are add
to the LLIIBBPPAATTHH, LLIIBBSS, AASSFFLLAAGGSS, LLIINNKKFFLLAAGGSS, CCPPPPFFLLAAGGSS, CCPPPPPPAATTHH and
CCCCFFLLAAGGSS construction variables, respectively. A returned
--pptthhrreeaadd option gets added to both the CCCCFFLLAAGGSS and LLIINNKKFFLLAAGGSS
variables. A returned --ffrraammeewwoorrkk option gets added to the LLIINNKK--
FFLLAAGGSS variable. Any other strings not associated with options
are assumed to be the names of libraries and added to the LLIIBBSS
construction variable.
ParseDepends(_f_i_l_e_n_a_m_e, [_m_u_s_t___e_x_i_s_t])
env.ParseDepends(_f_i_l_e_n_a_m_e, [_m_u_s_t___e_x_i_s_t _o_n_l_y___o_n_e])
Parses the contents of the specified _f_i_l_e_n_a_m_e as a list of
dependencies in the style of MMaakkee or mmkkddeepp, and explicitly
establishes all of the listed dependencies.
By default, it is not an error if the specified _f_i_l_e_n_a_m_e does
not exist. The optional _m_u_s_t___e_x_i_t argument may be set to a non-
zero value to have scons throw an exception and generate an
error if the file does not exist, or is otherwise inaccessible.
The optional _o_n_l_y___o_n_e argument may be set to a non-zero value to
have scons thrown an exception and generate an error if the file
contains dependency information for more than one target. This
can provide a small sanity check for files intended to be gener-
ated by, for example, the ggcccc --MM flag, which should typically
only write dependency information for one output file into a
corresponding ..dd file.
The _f_i_l_e_n_a_m_e and all of the files listed therein will be inter-
preted relative to the directory of the _S_C_o_n_s_c_r_i_p_t file which
calls the PPaarrsseeDDeeppeennddss function.
env.Perforce()
A factory function that returns a Builder object to be used to
fetch source files from the Perforce source code management sys-
tem. The returned Builder is intended to be passed to the
SSoouurrcceeCCooddee function:
env.SourceCode('.', env.Perforce())
Perforce uses a number of external environment variables for its
operation. Consequently, this function adds the following vari-
ables from the user's external environment to the construction
environment's ENV dictionary: P4CHARSET, P4CLIENT, P4LANGUAGE,
P4PASSWD, P4PORT, P4USER, SYSTEMROOT, USER, and USERNAME.
Platform(_s_t_r_i_n_g)
Returns a callable object that can be used to initialize a con-
struction environment using the platform keyword of the Environ-
ment() method:
env = Environment(platform = Platform('win32'))
env.Platform(_s_t_r_i_n_g)
Applies the callable object for the specified platform _s_t_r_i_n_g to
the environment through which the method was called.
env.Platform('posix')
Note that the wwiinn3322 platform adds the SSYYSSTTEEMMDDRRIIVVEE and SSYYSSTTEEMMRROOOOTT
variables from the user's external environment to the construc-
tion environment's EENNVV dictionary. This is so that any executed
commands that use sockets to connect with other systems (such as
fetching source files from external CVS repository specifica-
tions like ::ppsseerrvveerr::aannoonnyymmoouuss@@ccvvss..ssoouurrcceeffoorrggee..nneett:://ccvvss--
rroooott//ssccoonnss) will work on Win32 systems.
Precious(_t_a_r_g_e_t, ...)
env.Precious(_t_a_r_g_e_t, ...)
Marks each given _t_a_r_g_e_t as precious so it is not deleted before
it is rebuilt. Normally ssccoonnss deletes a target before building
it. Multiple targets can be passed in to a single call to
PPrreecciioouuss().
env.Prepend(_k_e_y=_v_a_l, [...])
Appends the specified keyword arguments to the beginning of con-
struction variables in the environment. If the Environment does
not have the specified construction variable, it is simply added
to the environment. If the values of the construction variable
and the keyword argument are the same type, then the two values
will be simply added together. Otherwise, the construction
variable and the value of the keyword argument are both coerced
to lists, and the lists are added together. (See also the
Append method, above.)
env.Prepend(CCFLAGS = '-g ', FOO = ['foo.yyy'])
env.PrependENVPath(_n_a_m_e, _n_e_w_p_a_t_h, [_e_n_v_n_a_m_e, _s_e_p])
This appends new path elements to the given path in the speci-
fied external environment (EENNVV by default). This will only add
any particular path once (leaving the first one it encounters
and ignoring the rest, to preserve path order), and to help
assure this, will normalize all paths (using ooss..ppaatthh..nnoorrmmppaatthh
and ooss..ppaatthh..nnoorrmmccaassee). 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: /biz:/foo
after: /foo/bar:/foo:/biz
env.PrependUnique(_k_e_y=_v_a_l, [...])
Appends the specified keyword arguments to the beginning of con-
struction variables in the environment. If the Environment does
not have the specified construction variable, it is simply added
to the environment. If the construction variable being appended
to is a list, then any value(s) that already exist in the con-
struction variable will _n_o_t be added again to the list.
env.PrependUnique(CCFLAGS = '-g', FOO = ['foo.yyy'])
env.RCS()
A factory function that returns a Builder object to be used to
fetch source files from RCS. The returned Builder is intended
to be passed to the SSoouurrcceeCCooddee function:
env.SourceCode('.', env.RCS())
Note that ssccoonnss will fetch source files from RCS subdirectories
automatically, so configuring RCS as demonstrated in the above
example should only be necessary if you are fetching from RCS,v
files in the same directory as the source files, or if you need
to explicitly specify RCS for a specific subdirectory.
env.Replace(_k_e_y=_v_a_l, [...])
Replaces construction variables in the Environment with the
specified keyword arguments.
env.Replace(CCFLAGS = '-g', FOO = 'foo.xxx')
Repository(_d_i_r_e_c_t_o_r_y)
env.Repository(_d_i_r_e_c_t_o_r_y)
Specifies that _d_i_r_e_c_t_o_r_y is a repository to be searched for
files. Multiple calls to RReeppoossiittoorryy() are legal, and each one
adds to the list of repositories that will be searched.
To ssccoonnss, a repository is a copy of the source tree, from the
top-level directory on down, which may contain both source files
and derived files that can be used to build targets in the local
source tree. The canonical example would be an official source
tree maintained by an integrator. If the repository contains
derived files, then the derived files should have been built
using ssccoonnss, so that the repository contains the necessary sig-
nature information to allow ssccoonnss to figure out when it is
appropriate to use the repository copy of a derived file,
instead of building one locally.
Note that if an up-to-date derived file already exists in a
repository, ssccoonnss will _n_o_t make a copy in the local directory
tree. In order to guarantee that a local copy will be made, use
the LLooccaall(()) method.
Return(_v_a_r_s)
This tells ssccoonnss what variable(s) to use as the return value(s)
of the current SConscript file. These variables will be returned
to the "calling" SConscript file as the return value(s) of SSCCoonn--
ssccrriipptt(). Multiple variable names should be passed to RReettuurrnn()
as a list. Example:
Return("foo")
Return(["foo", "bar"])
Scanner(_f_u_n_c_t_i_o_n, [_a_r_g_u_m_e_n_t, _k_e_y_s, _p_a_t_h___f_u_n_c_t_i_o_n, _n_o_d_e___c_l_a_s_s, _n_o_d_e___f_a_c_-
_t_o_r_y, _s_c_a_n___c_h_e_c_k, _r_e_c_u_r_s_i_v_e])
env.Scanner(_f_u_n_c_t_i_o_n, [_a_r_g_u_m_e_n_t, _k_e_y_s, _p_a_t_h___f_u_n_c_t_i_o_n, _n_o_d_e___c_l_a_s_s,
_n_o_d_e___f_a_c_t_o_r_y, _s_c_a_n___c_h_e_c_k, _r_e_c_u_r_s_i_v_e])
Creates a Scanner object for the specified _f_u_n_c_t_i_o_n. See the
section "Scanner Objects," below, for a complete explanation of
the arguments and behavior.
env.SCCS()
A factory function that returns a Builder object to be used to
fetch source files from SCCS. The returned Builder is intended
to be passed to the SSoouurrcceeCCooddee function:
env.SourceCode('.', env.SCCS())
Note that ssccoonnss will fetch source files from SCCS subdirectories
automatically, so configuring SCCS as demonstrated in the above
example should only be necessary if you are fetching from _s_._S_C_C_S
files in the same directory as the source files, or if you need
to explicitly specify SCCS for a specific subdirectory.
SConscript(_s_c_r_i_p_t_s, [_e_x_p_o_r_t_s, _b_u_i_l_d___d_i_r, _s_r_c___d_i_r, _d_u_p_l_i_c_a_t_e])
env.SConscript(_s_c_r_i_p_t_s, [_e_x_p_o_r_t_s, _b_u_i_l_d___d_i_r, _s_r_c___d_i_r, _d_u_p_l_i_c_a_t_e])
SConscript(dirs=_s_u_b_d_i_r_s, [name=_s_c_r_i_p_t, _e_x_p_o_r_t_s, _b_u_i_l_d___d_i_r, _s_r_c___d_i_r,
_d_u_p_l_i_c_a_t_e])
env.SConscript(dirs=_s_u_b_d_i_r_s, [name=_s_c_r_i_p_t, _e_x_p_o_r_t_s, _b_u_i_l_d___d_i_r, _s_r_c___d_i_r,
_d_u_p_l_i_c_a_t_e])
This tells ssccoonnss to execute one or more subsidiary SConscript
(configuration) files. There are two ways to call the SSCCoonn--
ssccrriipptt() function.
The first way you can call SSCCoonnssccrriipptt() is to explicitly specify
one or more _s_c_r_i_p_t_s as the first argument. A single script may
be specified as a string; multiple scripts must be specified as
a list (either explicitly or as created by a function like
SSpplliitt()).
The second way you can call SSCCoonnssccrriipptt() is to specify a list of
(sub)directory names as a dirs=_s_u_b_d_i_r_s keyword argument. In
this case, ssccoonnss will, by default, execute a subsidiary configu-
ration file named SSCCoonnssccrriipptt in each of the specified directo-
ries. You may specify a name other than SSCCoonnssccrriipptt by supplying
an optional name=_s_c_r_i_p_t keyword argument.
The optional _e_x_p_o_r_t_s argument provides a list of variable names
or a dictionary of named values to export to the _s_c_r_i_p_t_(_s_).
These variables are locally exported only to the specified
_s_c_r_i_p_t_(_s_), and do not affect the global pool of variables used
by the EExxppoorrtt() function. The subsidiary _s_c_r_i_p_t_(_s_) must use the
IImmppoorrtt() function to import the variables.
The optional _b_u_i_l_d___d_i_r argument specifies that all of the target
files (for example, object files and executables) that would
normally be built in the subdirectory in which _s_c_r_i_p_t resides
should actually be built in _b_u_i_l_d___d_i_r. _b_u_i_l_d___d_i_r is interpreted
relative to the directory of the calling SConscript file.
The optional _s_r_c___d_i_r argument specifies that the source files
from which the target files should be built can be found in
_s_r_c___d_i_r. _s_r_c___d_i_r is interpreted relative to the directory of
the calling SConscript file.
By default, ssccoonnss will link or copy (depending on the platform)
all the source files into the build directory. This behavior
may be disabled by setting the optional _d_u_p_l_i_c_a_t_e argument to 0
(it is set to 1 by default), in which case ssccoonnss will refer
directly to the source files in their source directory when
building target files. (Setting _d_u_p_l_i_c_a_t_e=0 is usually safe,
and always more efficient than the default of _d_u_p_l_i_c_a_t_e=1, but
it may cause build problems in certain end-cases, such as com-
piling from source files that are generated by the build.)
Any variables returned by _s_c_r_i_p_t using RReettuurrnn() will be returned
by the call to SSCCoonnssccrriipptt().
Examples:
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')
SConscriptChdir(_v_a_l_u_e)
env.SConscriptChdir(_v_a_l_u_e)
By default, ssccoonnss changes its working directory to the directory
in which each subsidiary SConscript file lives. This behavior
may be disabled by specifying either:
SConscriptChdir(0)
env.SConscriptChdir(0)
in which case ssccoonnss will stay in the top-level directory while
reading all SConscript files. (This may be necessary when
building from repositories, when all the directories in which
SConscript files may be found don't necessarily exist locally.)
You may enable and disable this ability by calling SCon-
scriptChdir() multiple times:
env = Environment()
SConscriptChdir(0)
SConscript('foo/SConscript') # will not chdir to foo
env.SConscriptChdir(1)
SConscript('bar/SConscript') # will chdir to bar
SConsignFile([_f_i_l_e,_d_b_m___m_o_d_u_l_e])
env.SConsignFile([_f_i_l_e,_d_b_m___m_o_d_u_l_e])
This tells ssccoonnss to store all file signatures in the specified
database _f_i_l_e. If the _f_i_l_e name is omitted, ..ssccoonnssiiggnn is used
by default. (The actual file name(s) stored on disk may have an
appropriated suffix appended by the _d_b_m___m_o_d_u_l_e.) If _f_i_l_e is not
an absolute path name, the file is placed in the same directory
as the top-level SSCCoonnssttrruucctt file.
If _f_i_l_e is NNoonnee, then ssccoonnss will store file signatures in a sep-
arate ..ssccoonnssiiggnn file in each directory, not in one global
database file. (This was the default behavior prior to SCons
0.96.91 and 0.97.)
The optional _d_b_m___m_o_d_u_l_e argument can be used to specify which
Python database module The default is to use a custom
SSCCoonnss..ddbblliittee module that uses pickled Python data structures,
and which works on all Python versions from 1.5.2 on.
Examples:
# Explicitly stores signatures in ".sconsign.dblite"
# in the top-level SConstruct directory (the
# default behavior).
SConsignFile()
# Stores signatures in the file "etc/scons-signatures"
# relative to the top-level SConstruct directory.
SConsignFile("etc/scons-signatures")
# Stores signatures in the specified absolute file name.
SConsignFile("/home/me/SCons/signatures")
# Stores signatures in a separate .sconsign file
# in each directory.
SConsignFile(None)
env.SetDefault(key_=val_, _[_._._._]_)
Sets construction variables to default values specified with the
keyword arguments if (and only if) the variables are not already
set. The following statements are equivalent:
env.SetDefault(FOO = 'foo')
if not env.has_key('FOO'): env['FOO'] = 'foo'
SetOption(_n_a_m_e, _v_a_l_u_e)
env.SetOption(_n_a_m_e, _v_a_l_u_e)
This function provides a way to set a select subset of the scons
command line options from a SConscript file. The options sup-
ported are: cclleeaann which corresponds to -c, --clean, and
--remove; dduupplliiccaattee which corresponds to --duplicate;
iimmpplliicciitt__ccaacchhee which corresponds to --implicit-cache; mmaaxx__ddrriifftt
which corresponds to --max-drift; nnuumm__jjoobbss which corresponds to
-j and --jobs. See the documentation for the corresponding com-
mand line object for information about each specific option.
Example:
SetOption('max_drift', 1)
SideEffect(_s_i_d_e___e_f_f_e_c_t, _t_a_r_g_e_t)
env.SideEffect(_s_i_d_e___e_f_f_e_c_t, _t_a_r_g_e_t)
Declares _s_i_d_e___e_f_f_e_c_t as a side effect of building _t_a_r_g_e_t. Both
_s_i_d_e___e_f_f_e_c_t and _t_a_r_g_e_t can be a list, a file name, or a node. A
side effect is a target that is created as a side effect of
building other targets. For example, a Windows PDB file is cre-
ated as a side effect of building the .obj files for a static
library. If a target is a side effect of multiple build com-
mands, ssccoonnss will ensure that only one set of commands is exe-
cuted at a time. Consequently, you only need to use this method
for side-effect targets that are built as a result of multiple
build commands.
SourceCode(_e_n_t_r_i_e_s, _b_u_i_l_d_e_r)
env.SourceCode(_e_n_t_r_i_e_s, _b_u_i_l_d_e_r)
Arrange for non-existent source files to be fetched from a
source code management system using the specified _b_u_i_l_d_e_r. The
specified _e_n_t_r_i_e_s may be a Node, string or list of both, and may
represent either individual source files or directories in which
source files can be found.
For any non-existent source files, ssccoonnss will search up the
directory tree and use the first SSoouurrcceeCCooddee builder it finds.
The specified _b_u_i_l_d_e_r may be NNoonnee, in which case ssccoonnss will not
use a builder to fetch source files for the specified _e_n_t_r_i_e_s,
even if a SSoouurrcceeCCooddee builder has been specified for a directory
higher up the tree.
ssccoonnss will, by default, fetch files from SCCS or RCS subdirecto-
ries without explicit configuration. This takes some extra pro-
cessing time to search for the necessary source code management
files on disk. You can avoid these extra searches and speed up
your build a little by disabling these searches as follows:
env.SourceCode('.', None)
Note that if the specified _b_u_i_l_d_e_r is one you create by hand, it
must have an associated construction environment to use when
fetching a source file.
ssccoonnss provides a set of canned factory functions that return
appropriate Builders for various popular source code management
systems. Canonical examples of invocation 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)
env.subst(_s_t_r_i_n_g)
Performs construction variable interpolation on the specified
string argument.
print env.subst("The C compiler is: $CC")
def compile(target, source, env):
sourceDir = env.subst("${SOURCE.srcdir}")
SourceSignatures(_t_y_p_e)
env.SourceSignatures(_t_y_p_e)
This function tells SCons what type of signature to use for
source files: MMDD55 or ttiimmeessttaammpp. If the environment method is
used, the specified type of source signature is only used when
deciding whether targets built with that environment are up-to-
date or must be rebuilt. If the global function is used, the
specified type of source signature becomes the default used for
all decisions about whether targets are up-to-date.
"MD5" means the signature of a source file is the MD5 checksum
of its contents. "timestamp" means the signature of a source
file is its timestamp (modification time). There is no differ-
ent between the two behaviors for Python VVaalluuee() node objects.
"MD5" signatures take longer to compute, but are more accurate
than "timestamp" signatures. The default is "MD5".
Split(_a_r_g)
env.Split(_a_r_g)
Returns a list of file names or other objects. If arg is a
string, it will be split on strings of white-space characters
within the string, making it easier to write long lists of file
names. If arg is already a list, the list will be returned
untouched. If arg is any other type of object, it will be
returned as a list containing just the object.
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
""")
TargetSignatures(_t_y_p_e)
env.TargetSignatures(_t_y_p_e)
This function tells SCons what type of signatures to use for
target files: bbuuiilldd or ccoonntteenntt. If the environment method is
used, the specified type of signature is only used for targets
built with that environment. If the global function is used,
the specified type of signature becomes the default used for all
target files that don't have an explicit target signature type
specified for their environments.
"build" means the signature of a target file is made by concate-
nating all of the signatures of all its source files. "content"
means the signature of a target file is an MD5 checksum of its
contents. "build" signatures are usually faster to compute, but
"content" signatures can prevent unnecessary rebuilds when a
target file is rebuilt to the exact same contents as the previ-
ous build. The default is "build".
Tool(_s_t_r_i_n_g[,_t_o_o_l_p_a_t_h, _*_*_k_w])
Returns a callable object that can be used to initialize a con-
struction environment using the tools keyword of the Environ-
ment() method. The object may be called with a construction
environment as an argument, in which case the object will add
the necessary variables to the construction environment and the
name of the tool will be added to the $$TTOOOOLLSS construction vari-
able.
Additional keyword arguments are passed to the tool's ggeenneerraattee(())
method.
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(_s_t_r_i_n_g[,_t_o_o_l_p_a_t_h, _*_*_k_w])
Applies the callable object for the specified tool _s_t_r_i_n_g to the
environment through which the method was called.
Additional keyword arguments are passed to the tool's ggeenneerraattee(())
method.
env.Tool('gcc')
env.Tool('opengl', toolpath = ['build/tools'])
Value(_v_a_l_u_e)
env.Value(_v_a_l_u_e)
Returns a Node object representing the specified Python value.
Value nodes can be used as dependencies of targets. If the
result of calling ssttrr((value)) changes between SCons runs, any
targets depending on VVaalluuee((value)) will be rebuilt. When using
timestamp source signatures, Value nodes' timestamps are equal
to the system time when the node is created.
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(_p_r_o_g_r_a_m, [_p_a_t_h, _p_a_t_h_e_x_t, _r_e_j_e_c_t])
env.WhereIs(_p_r_o_g_r_a_m, [_p_a_t_h, _p_a_t_h_e_x_t, _r_e_j_e_c_t])
Searches for the specified executable _p_r_o_g_r_a_m_, returning the
full path name to the program if it is found, and returning None
if not. Searches the specified _p_a_t_h_, the value of the calling
environment's PATH (env['ENV']['PATH']), or the user's current
external PATH (os.environ['PATH']) by default. On Win32 sys-
tems, searches for executable programs with any of the file
extensions listed in the specified _p_a_t_h_e_x_t_, the calling environ-
ment's PATHEXT (env['ENV']['PATHEXT']) or the user's current
PATHEXT (os.environ['PATHEXT']) by default. Will not select any
path name or names in the specified _r_e_j_e_c_t list, if any.
SSCCoonnssccrriipptt VVaarriiaabblleess
In addition to the global functions and methods, ssccoonnss supports a num-
ber of Python variables that can be used in SConscript files to affect
how you want the build to be performed. These variables may be
accessed from custom Python modules that you import into an SConscript
file by adding the following to the Python module:
from SCons.Script import *
ARGLIST
A list _k_e_y_w_o_r_d=_v_a_l_u_e arguments specified on the command line.
Each element in the list is a tuple containing the
(_k_e_y_w_o_r_d,_v_a_l_u_e) of the argument. The separate _k_e_y_w_o_r_d and _v_a_l_u_e
elements of the tuple can be accessed by subscripting for ele-
ment [[00]] and [[11]] 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 _k_e_y_w_o_r_d=_v_a_l_u_e 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 AARRGGUUMMEENNTTSS
dictionary.
if ARGUMENTS.get('debug', 0):
env = Environment(CCFLAGS = '-g')
else:
env = Environment()
BUILD_TARGETS
A list of the targets which ssccoonnss will actually try to build,
regardless of whether they were specified on the command line or
via the DDeeffaauulltt() function or method. The elements of this list
may be strings _o_r nodes, so you should run the list through the
Python ssttrr function to make sure any Node path names are con-
verted to strings.
Because this list may be taken from the list of targets speci-
fied using the DDeeffaauulltt() function or method, the contents of the
list may change on each successive call to DDeeffaauulltt(). See the
DDEEFFAAUULLTT__TTAARRGGEETTSS list, below, for additional information.
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 BBUUIILLDD__TTAARRGGEETTSS list only contains targets expected
listed on the command line or via calls to the DDeeffaauulltt() func-
tion or method. It does _n_o_t 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 targets specified on the command line, the list
is empty. This can be used, for example, to take specific
actions only when a certain target or targets is explicitly
being built:
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 _n_o_d_e_s that have been specified using the
DDeeffaauulltt() function or method. The elements of the list are
nodes, so you need to run them through the Python ssttrr 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 DDEEFFAAUULLTT__TTAARRGGEETTSS list change on on each suc-
cessive call to the DDeeffaauulltt() 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 DDEEFFAAUULLTT__TTAARRGGEETTSS only after you've
made all of your DDeeffaauulltt() calls, or else simply be careful of
the order of these statements in your SConscript files so that
you don't look for a specific default target before it's actu-
ally been added to the list.
CCoonnssttrruuccttiioonn VVaarriiaabblleess
A construction environment has an associated dictionary of _c_o_n_s_t_r_u_c_t_i_o_n
_v_a_r_i_a_b_l_e_s 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.
ARCOMSTR
The string displayed when an object file is generated from an
assembly-language source file. If this is not set, then $ARCOM
(the command line) is displayed.
env = Environment(ARCOMSTR = "Archiving $TARGET")
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.
ASCOMSTR
The string displayed when an object file is generated from an
assembly-language source file. If this is not set, then $ASCOM
(the command line) is displayed.
env = Environment(ASCOMSTR = "Assembling $TARGET")
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.
ASPPCOMSTR
The string displayed when an object file is generated from an
assembly-language source file after first running the file
through the C preprocessor. If this is not set, then $ASPPCOM
(the command line) is displayed.
env = Environment(ASPPCOMSTR = "Assembling $TARGET")
ASPPFLAGS
General options when an assembling an assembly-language source
file into an object file after first running the file through
the C preprocessor. The default is to use the value of
$ASFLAGS.
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.
BIBTEXCOMSTR
The string displayed when generating a bibliography for TeX or
LaTeX. If this is not set, then $BIBTEXCOM (the command line)
is displayed.
env = Environment(BIBTEXCOMSTR = "Generating bibliography $TARGET")
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.
BITKEEPERCOMSTR
The string displayed when fetching a source file using Bit-
Keeper. If this is not set, then $BITKEEPERCOM (the command
line) is displayed.
BITKEEPERGET
The command ($BITKEEPER) and subcommand for fetching source
files using BitKeeper.
BITKEEPERGETFLAGS
Options that are passed to the BitKeeper ggeett 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.
CCCOMSTR
The string displayed when a C source file is compiled to a
(static) object file. If this is not set, then $CCCOM (the com-
mand line) is displayed.
env = Environment(CCCOMSTR = "Compiling static object $TARGET")
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-insensitive 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 arguments: a prefix to concatenate onto each
element, a list of elements, a suffix to concatenate onto each
element, an environment for variable interpolation, and an
optional function that will be called to transform the list
before concatenation.
env['_CPPINCFLAGS'] = '$( ${_concat(INCPREFIX, CPPPATH, INCSUFFIX, __env__, RDirs)} $)',
CPPDEFINES
A platform independent specification of C preprocessor defini-
tions. The definitions will be added to command lines through
the automatically-generated $_CPPDEFFLAGS construction variable
(see below), which is constructed according to the type of value
of $CPPDEFINES:
If $CPPDEFINES is a string, the values 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 construction 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 construction 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 dictionary
item's corresponding value; if the value is NNoonnee, then the name
is defined without an explicit value. Note that the resulting
flags are sorted by keyword to ensure that the order of the
options on the command line is consistent each time ssccoonnss
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 automatically-generated construction variable containing the
C preprocessor command-line options to define values. The value
of $_CPPDEFFLAGS is created by appending $CPPDEFPREFIX and
$CPPDEFSUFFIX to the beginning and end of each directory in
$CPPDEFINES.
CPPDEFPREFIX
The prefix used to specify preprocessor definitions on the C
compiler command line. This will be appended to the beginning
of each definition in the $CPPDEFINES construction variable when
the $_CPPDEFFLAGS variable is automatically generated.
CPPDEFSUFFIX
The suffix used to specify preprocessor definitions on the C
compiler command line. This will be appended to the end of each
definition in the $CPPDEFINES construction variable when the
$_CPPDEFFLAGS variable is automatically generated.
CPPFLAGS
User-specified C preprocessor options. These will be included
in any command that uses the C preprocessor, including not just
compilation of C and C++ source files via the $CCCOM, $SHCCCOM,
$CXXCOM and $SHCXXCOM command lines, but also the $FORTRANPPCOM,
$SHFORTRANPPCOM, $F77PPCOM and $SHF77PPCOM command lines used to
compile a Fortran source file, and the $ASPPCOM command line
used to assemble an assembly language source file, after first
running each file through the C preprocessor. Note that this
variable does _n_o_t contain --II (or similar) include search path
options that scons generates automatically from $CPPPATH. See
__CCPPPPIINNCCFFLLAAGGSS, below, for the variable that expands to those
options.
_CPPINCFLAGS
An automatically-generated construction variable containing 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 preprocessor will search for
include directories. The C/C++ implicit dependency scanner will
search these directories for include files. Don't explicitly put
include directory arguments in CCFLAGS or CXXFLAGS because the
result will be non-portable and the directories will not be
searched by the dependency scanner. Note: directory names in
CPPPATH will be looked-up relative to the SConscript directory
when they are used in a command. To force ssccoonnss to look-up a
directory relative to the root of the source tree use #:
env = Environment(CPPPATH='#/include')
The directory look-up can also be forced using the DDiirr() func-
tion:
include = Dir('include')
env = Environment(CPPPATH=include)
The directory list will be added to command lines through the
automatically-generated $_CPPINCFLAGS construction variable,
which is constructed by appending the values of the $INCPREFIX
and $INCSUFFIX construction variables to the beginning and end
of each directory in $CPPPATH. Any command lines you define
that need the CPPPATH directory list should include
$_CPPINCFLAGS:
env = Environment(CCCOM="my_compiler $_CPPINCFLAGS -c -o $TARGET $SOURCE")
CPPSUFFIXES
The list of suffixes of files that will be scanned for C prepro-
cessor implicit dependencies (#include lines). The default list
is:
[".c", ".C", ".cxx", ".cpp", ".c++", ".cc",
".h", ".H", ".hxx", ".hpp", ".hh",
".F", ".fpp", ".FPP",
".m", ".mm",
".S", ".spp", ".SPP"]
CVS The CVS executable.
CVSCOFLAGS
Options that are passed to the CVS checkout subcommand.
CVSCOM The command line used to fetch source files from a CVS reposi-
tory.
CVSCOMSTR
The string displayed when fetching a source file from a CVS
repository. If this is not set, then $CVSCOM (the command line)
is displayed.
CVSFLAGS
General options that are passed to CVS. By default, this is set
to "-d $CVSREPOSITORY" to specify from where the files must be
fetched.
CVSREPOSITORY
The path to the CVS repository. This is referenced in the
default $CVSFLAGS value.
CXX The C++ compiler.
CXXFILESUFFIX
The suffix for C++ source files. This is used by the internal
CXXFile builder when generating C++ files from Lex (.ll) or YACC
(.yy) input files. The default suffix is _._c_c. SCons also
treats files with the suffixes _._c_p_p, _._c_x_x, _._c_+_+, and _._C_+_+ as C++
files, and files with _._m_m suffixes as Objective C++ files. On
case-sensitive systems (Linux, UNIX, and other POSIX-alikes),
SCons also treats _._C (upper case) files as C++ files.
CXXCOM The command line used to compile a C++ source file to an object
file. Any options specified in the $CXXFLAGS and $CPPFLAGS con-
struction variables are included on this command line.
CXXCOMSTR
The string displayed when a C++ source file is compiled to a
(static) object file. If this is not set, then $CXXCOM (the
command line) is displayed.
env = Environment(CXXCOMSTR = "Compiling static object $TARGET")
CXXFLAGS
General options that are passed to the C++ compiler. By
default, this includes the value of $CCFLAGS, so that setting
$CCFLAGS affects both C and C++ compilation. If you want to add
C++-specific flags, you must set or override the value of
$CXXFLAGS.
CXXVERSION
The version number of the C++ compiler. This may or may not be
set, depending on the specific C++ compiler being used.
Dir A function that converts a string into a Dir instance relative
to the target being built.
Dirs A function that converts a list of strings into a list of Dir
instances relative to the target being built.
DSUFFIXES
The list of suffixes of files that will be scanned for imported
D package files. The default list is:
['.d']
DVIPDF The TeX DVI file to PDF file converter.
DVIPDFFLAGS
General options passed to the TeX DVI file to PDF file con-
verter.
DVIPDFCOM
The command line used to convert TeX DVI files into a PDF file.
DVIPDFCOMSTR
The string displayed when a TeX DVI file is converted into a PDF
file. If this is not set, then $DVIPDFCOM (the command line) is
displayed.
DVIPS The TeX DVI file to PostScript converter.
DVIPSFLAGS
General options passed to the TeX DVI file to PostScript con-
verter.
ENV A dictionary of environment variables to use when invoking com-
mands. When ENV is used in a command all list values will be
joined using the path separator and any other non-string values
will simply be coerced to a string. Note that, by default,
ssccoonnss does _n_o_t propagate the environment in force when you exe-
cute ssccoonnss 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 ssccoonnss is invoked.
If you want to propagate your environment variables to the com-
mands executed to build target files, you must do so explicitly:
import os
env = Environment(ENV = os.environ)
Note that you can choose only to propagate certain environment
variables. A common example is the system PPAATTHH environment
variable, so that ssccoonnss uses the same utilities as the invoking
shell (or other process):
import os
env = Environment(ENV = {'PATH' : os.environ['PATH']})
ESCAPE A function that will be called to escape shell special charac-
ters in command lines. The function should take one argument:
the command line string to escape; and should return the escaped
command line.
F77 The Fortran 77 compiler. You should normally set the $FORTRAN
variable, which specifies the default Fortran compiler for all
Fortran versions. You only need to set $F77 if you need to use
a specific compiler or compiler version for Fortran 77 files.
F77COM The command line used to compile a Fortran 77 source file to an
object file. You only need to set $F77COM if you need to use a
specific command line for Fortran 77 files. You should normally
set the $FORTRANCOM variable, which specifies the default com-
mand line for all Fortran versions.
F77COMSTR
The string displayed when a Fortran 77 source file is compiled
to an object file. If this is not set, then $F77COM or $FOR-
TRANCOM (the command line) is displayed.
F77FLAGS
General user-specified options that are passed to the Fortran 77
compiler. Note that this variable does _n_o_t contain --II (or simi-
lar) include search path options that scons generates automati-
cally from $F77PATH. See __FF7777IINNCCFFLLAAGGSS, below, for the variable
that expands to those options. You only need to set $F77FLAGS
if you need to define specific user options for Fortran 77
files. You should normally set the $FORTRANFLAGS variable,
which specifies the user-specified options passed to the default
Fortran compiler for all Fortran versions.
_F77INCFLAGS
An automatically-generated construction variable containing the
Fortran 77 compiler command-line options for specifying directo-
ries to be searched for include files. The value of
$_F77INCFLAGS is created by appending $INCPREFIX and $INCSUFFIX
to the beginning and end of each directory in $F77PATH.
F77PATH
The list of directories that the Fortran 77 compiler will search
for include directories. The implicit dependency scanner will
search these directories for include files. Don't explicitly put
include directory arguments in $F77FLAGS because the result will
be non-portable and the directories will not be searched by the
dependency scanner. Note: directory names in $F77PATH will be
looked-up relative to the SConscript directory when they are
used in a command. To force ssccoonnss to look-up a directory rela-
tive to the root of the source tree use #: You only need to set
$F77PATH if you need to define a specific include path for For-
tran 77 files. You should normally set the $FORTRANPATH vari-
able, which specifies the include path for the default Fortran
compiler for all Fortran versions.
env = Environment(F77PATH='#/include')
The directory look-up can also be forced using the DDiirr() func-
tion:
include = Dir('include')
env = Environment(F77PATH=include)
The directory list will be added to command lines through the
automatically-generated $_F77INCFLAGS construction variable,
which is constructed by appending the values of the $INCPREFIX
and $INCSUFFIX construction variables to the beginning and end
of each directory in $F77PATH. Any command lines you define
that need the F77PATH directory list should include
$_F77INCFLAGS:
env = Environment(F77COM="my_compiler $_F77INCFLAGS -c -o $TARGET $SOURCE")
F77PPCOM
The command line used to compile a Fortran 77 source file to an
object file after first running the file through the C prepro-
cessor. Any options specified in the $F77FLAGS and $CPPFLAGS
construction variables are included on this command line. You
only need to set $F77PPCOM if you need to use a specific C-pre-
processor command line for Fortran 77 files. You should nor-
mally set the $FORTRANPPCOM variable, which specifies the
default C-preprocessor command line for all Fortran versions.
F90 The Fortran 90 compiler. You should normally set the $FORTRAN
variable, which specifies the default Fortran compiler for all
Fortran versions. You only need to set $F90 if you need to use
a specific compiler or compiler version for Fortran 90 files.
F90COM The command line used to compile a Fortran 90 source file to an
object file. You only need to set $F90COM if you need to use a
specific command line for Fortran 90 files. You should normally
set the $FORTRANCOM variable, which specifies the default com-
mand line for all Fortran versions.
F90COMSTR
The string displayed when a Fortran 90 source file is compiled
to an object file. If this is not set, then $F90COM or $FOR-
TRANCOM (the command line) is displayed.
F90FLAGS
General user-specified options that are passed to the Fortran 90
compiler. Note that this variable does _n_o_t contain --II (or simi-
lar) include search path options that scons generates automati-
cally from $F90PATH. See __FF9900IINNCCFFLLAAGGSS, below, for the variable
that expands to those options. You only need to set $F90FLAGS
if you need to define specific user options for Fortran 90
files. You should normally set the $FORTRANFLAGS variable,
which specifies the user-specified options passed to the default
Fortran compiler for all Fortran versions.
_F90INCFLAGS
An automatically-generated construction variable containing the
Fortran 90 compiler command-line options for specifying
directories to be searched for include files. The value of
$_F90INCFLAGS is created by appending $INCPREFIX and $INCSUFFIX
to the beginning and end of each directory in $F90PATH.
F90PATH
The list of directories that the Fortran 90 compiler will search
for include directories. The implicit dependency scanner will
search these directories for include files. Don't explicitly put
include directory arguments in $F90FLAGS because the result will
be non-portable and the directories will not be searched by the
dependency scanner. Note: directory names in $F90PATH will be
looked-up relative to the SConscript directory when they are
used in a command. To force ssccoonnss to look-up a directory rela-
tive to the root of the source tree use #: You only need to set
$F90PATH if you need to define a specific include path for For-
tran 90 files. You should normally set the $FORTRANPATH vari-
able, which specifies the include path for the default Fortran
compiler for all Fortran versions.
env = Environment(F90PATH='#/include')
The directory look-up can also be forced using the DDiirr() func-
tion:
include = Dir('include')
env = Environment(F90PATH=include)
The directory list will be added to command lines through the
automatically-generated $_F90INCFLAGS construction variable,
which is constructed by appending the values of the $INCPREFIX
and $INCSUFFIX construction variables to the beginning and end
of each directory in $F90PATH. Any command lines you define
that need the F90PATH directory list should include
$_F90INCFLAGS:
env = Environment(F90COM="my_compiler $_F90INCFLAGS -c -o $TARGET $SOURCE")
F90PPCOM
The command line used to compile a Fortran 90 source file to an
object file after first running the file through the C prepro-
cessor. Any options specified in the $F90FLAGS and $CPPFLAGS
construction variables are included on this command line. You
only need to set $F90PPCOM if you need to use a specific C-pre-
processor command line for Fortran 90 files. You should nor-
mally set the $FORTRANPPCOM variable, which specifies the
default C-preprocessor command line for all Fortran versions.
F95 The Fortran 95 compiler. You should normally set the $FORTRAN
variable, which specifies the default Fortran compiler for all
Fortran versions. You only need to set $F95 if you need to use
a specific compiler or compiler version for Fortran 95 files.
F95COM The command line used to compile a Fortran 95 source file to an
object file. You only need to set $F95COM if you need to use a
specific command line for Fortran 95 files. You should normally
set the $FORTRANCOM variable, which specifies the default com-
mand line for all Fortran versions.
F95COMSTR
The string displayed when a Fortran 95 source file is compiled
to an object file. If this is not set, then $F95COM or $FOR-
TRANCOM (the command line) is displayed.
F95FLAGS
General user-specified options that are passed to the Fortran 95
compiler. Note that this variable does _n_o_t contain --II (or simi-
lar) include search path options that scons generates automati-
cally from $F95PATH. See __FF9955IINNCCFFLLAAGGSS, below, for the variable
that expands to those options. You only need to set $F95FLAGS
if you need to define specific user options for Fortran 95
files. You should normally set the $FORTRANFLAGS variable,
which specifies the user-specified options passed to the default
Fortran compiler for all Fortran versions.
_F95INCFLAGS
An automatically-generated construction variable containing the
Fortran 95 compiler command-line options for specifying directo-
ries to be searched for include files. The value of
$_F95INCFLAGS is created by appending $INCPREFIX and $INCSUFFIX
to the beginning and end of each directory in $F95PATH.
F95PATH
The list of directories that the Fortran 95 compiler will search
for include directories. The implicit dependency scanner will
search these directories for include files. Don't explicitly put
include directory arguments in $F95FLAGS because the result will
be non-portable and the directories will not be searched by the
dependency scanner. Note: directory names in $F95PATH will be
looked-up relative to the SConscript directory when they are
used in a command. To force ssccoonnss to look-up a directory rela-
tive to the root of the source tree use #: You only need to set
$F95PATH if you need to define a specific include path for For-
tran 95 files. You should normally set the $FORTRANPATH vari-
able, which specifies the include path for the default Fortran
compiler for all Fortran versions.
env = Environment(F95PATH='#/include')
The directory look-up can also be forced using the DDiirr() func-
tion:
include = Dir('include')
env = Environment(F95PATH=include)
The directory list will be added to command lines through the
automatically-generated $_F95INCFLAGS construction variable,
which is constructed by appending the values of the $INCPREFIX
and $INCSUFFIX construction variables to the beginning and end
of each directory in $F95PATH. Any command lines you define
that need the F95PATH directory list should include
$_F95INCFLAGS:
env = Environment(F95COM="my_compiler $_F95INCFLAGS -c -o $TARGET $SOURCE")
F95PPCOM
The command line used to compile a Fortran 95 source file to an
object file after first running the file through the C prepro-
cessor. Any options specified in the $F95FLAGS and $CPPFLAGS
construction variables are included on this command line. You
only need to set $F95PPCOM if you need to use a specific C-pre-
processor command line for Fortran 95 files. You should nor-
mally set the $FORTRANPPCOM variable, which specifies the
default C-preprocessor command line for all Fortran versions.
FORTRAN
The default Fortran compiler for all versions of Fortran.
FORTRANCOM
The command line used to compile a Fortran source file to an
object file. By default, any options specified in the $FORTRAN-
FLAGS, $CPPFLAGS, $_CPPDEFFLAGS, $_FORTRANMODFLAG, and $_FOR-
TRANINCFLAGS construction variables are included on this command
line.
FORTRANCOMSTR
The string displayed when a Fortran source file is compiled to
an object file. If this is not set, then $FORTRANCOM (the com-
mand line) is displayed.
FORTRANFLAGS
General user-specified options that are passed to the Fortran
compiler. Note that this variable does _n_o_t contain --II (or simi-
lar) include or module search path options that scons generates
automatically from $FORTRANPATH. See __FFOORRTTRRAANNIINNCCFFLLAAGGSSand__FFOORR--
TTRRAANNMMOODDFFLLAAGGSS,, below, for the variables that expand those
options.
_FORTRANINCFLAGS
An automatically-generated construction variable containing the
Fortran compiler command-line options for specifying directories
to be searched for include files and module files. The value of
$_FORTRANINCFLAGS is created by prepending/appending $INCPREFIX
and $INCSUFFIX to the beginning and end of each directory in
$FORTRANPATH.
FORTRANMODDIR
Directory location where the Fortran compiler should place any
module files it generates. This variable is empty, by default.
Some Fortran compilers will internally append this directory in
the search path for module files, as well.
FORTRANMODDIRPREFIX
The prefix used to specify a module directory on the Fortran
compiler command line. This will be appended to the beginning
of the directory in the $FORTRANMODDIR construction variables
when the $_FORTRANMODFLAG variables is automatically generated.
FORTRANMODDIRSUFFIX
The suffix used to specify a module directory on the Fortran
compiler command line. This will be appended to the beginning
of the directory in the $FORTRANMODDIR construction variables
when the $_FORTRANMODFLAG variables is automatically generated.
_FORTRANMODFLAG
An automatically-generated construction variable containing the
Fortran compiler command-line option for specifying the direc-
tory location where the Fortran compiler should place any module
files that happen to get generated during compilation. The
value of $_FORTRANMODFLAG is created by prepending/appending
$FORTRANMODDIRPREFIX and $FORTRANMODDIRSUFFIX to the beginning
and end of the directory in $FORTRANMODDIR.
FORTRANMODPREFIX
The module file prefix used by the Fortran compiler. SCons
assumes that the Fortran compiler follows the quasi-standard
naming convention for module files of _