"Fossies" - the Fresh Open Source Software Archive  

Source code changes of the file "scons.1" between
SCons-4.3.0.tar.gz and SCons-4.4.0.tar.gz

About: SCons is a software construction tool (a Python script and a set of modules as a superior alternative to the classic "Make" build tool).

[ To the main SCons source changes report ]

scons.1  (SCons-4.3.0):scons.1  (SCons-4.4.0)
SCONS(1) SCons 4.3.0 SCONS(1) SCONS(1) SCons 4.4.0 SCONS(1)
NAME NAME
scons - a software construction tool scons - a software construction tool
SYNOPSIS SYNOPSIS
scons [options...] [name=val...] [targets...] scons [options...] [name=val...] [targets...]
DESCRIPTION DESCRIPTION
scons orchestrates the construction of software (and other tangible produ cts such as documentation files) scons orchestrates the construction of software (and other tangible produ cts such as documentation files)
by determining which component pieces must be built or rebuilt and invoki ng the necessary commands to by determining which component pieces must be built or rebuilt and invoki ng the necessary commands to
build them. SCons offers many features to improve developer productivity such as parallel builds, caching build them. SCons offers many features to improve developer productivity such as parallel builds, caching
of build artifacts, automatic dependency scanning, and a database of info rmation about previous builds so of build artifacts, automatic dependency scanning, and a database of info rmation about previous builds so
details do not have to be recalculated each run. details do not have to be recalculated each run.
scons requires Python 3.5 or later to run; there should be no other depen scons requires Python 3.6 or later to run; there should be no other depen
dencies or requirements. dencies or requirements. unless
Support for Python 3.5 is deprecated since SCons 4.2 and will be dropped the experimental Ninja tool is used.
in a future release. The CPython Support for Python 3.5 is removed since SCons 4.3.0. The CPython project
project has retired 3.5: https://www.python.org/dev/peps/pep-0478. has retired 3.5:
https://www.python.org/dev/peps/pep-0478.
You set up an SCons build system by writing a script that describes thing s to build (targets), and, if You set up an SCons build system by writing a script that describes thing s to build (targets), and, if
necessary, the rules to build those files (actions). SCons comes with a collection of Builder methods necessary, the rules to build those files (actions). SCons comes with a collection of Builder methods
which apply premade actions for building many common software components such as executable programs, which apply premade actions for building many common software components such as executable programs,
object files and libraries, so that for many software projects, only the targets and input files (sources) object files and libraries, so that for many software projects, only the targets and input files (sources)
need be specified in a call to a builder. scons thus can operate at a le need be specified in a call to a builder. SCons thus can operate at a le
vel of abstraction above that of vel of abstraction above that of
pure files. For example if you specify a library target named "foo", scon pure filenames. For example if you specify a library target named "foo",
s keeps track of the actual SCons keeps track of the actual
operating system dependent filename (such as libfoo.so on a GNU/Linux sys tem), and how to refer to that operating system dependent filename (such as libfoo.so on a GNU/Linux sys tem), and how to refer to that
library in later construction steps that want to use it, so you don't hav e to specify that precise library in later construction steps that want to use it, so you don't hav e to specify that precise
information yourself. scons can also scan automatically for dependency i information yourself. SCons can also scan automatically for dependency i
nformation, such as header files nformation, such as header files
included by source code files, so this does not have to be specified manu included by source code files (for example, #include preprocessor directi
ally. ves in C or C++ files), so these
implicit dependencies do not have to be specified manually. SCons suppor
ts the ability to define new
scanners to support additional input file types.
Information about files involved in the build, including a cryptographic
hash of the contents, is cached
for later reuse. By default this hash (the content signature) is used to
determine if a file has changed
since the last build, but this can be controlled by selecting an appropri
ate Decider function. Implicit
dependency files are also part of out-of-date computation. The scanned im
plicit dependency information can
optionally be cached and used to speed up future builds. A hash of each e
xecuted build action (the build
signature is cached, so that changes to build instructions (changing flag
s, etc.) or to the build tools
themselves (new version) can also trigger a rebuild.
When invoked, scons looks for a file named SConstruct in the current dire ctory and reads the build When invoked, scons looks for a file named SConstruct in the current dire ctory and reads the build
configuration from that file (other names are allowed, see the section ca lled “SConscript Files” for more configuration from that file (other names are allowed, see the section ca lled “SConscript Files” for more
information). The SConstruct file may specify subsidiary configuration fi les by calling the SConscript information). The SConstruct file may specify subsidiary configuration fi les by calling the SConscript
function. By convention, these subsidiary files are named SConscript, alt hough any name may be used. As a function. By convention, these subsidiary files are named SConscript, alt hough any name may be used. As a
result of this naming convention, the term SConscript files is used to re fer generically to the complete result of this naming convention, the term SConscript files is used to re fer generically to the complete
set of configuration files for a project (including the SConstruct file), regardless of the actual file set of configuration files for a project (including the SConstruct file), regardless of the actual file
names or number of such files. names or number of such files.
Before reading the SConscript files, scons looks for a directory named si te_scons in various system Before reading the SConscript files, scons looks for a directory named si te_scons in various system
skipping to change at line 68 skipping to change at line 79
$ scons foo.out $ scons foo.out
scons: Reading SConscript files ... scons: Reading SConscript files ...
scons: done reading SConscript files. scons: done reading SConscript files.
scons: Building targets ... scons: Building targets ...
cp foo.in foo.out cp foo.in foo.out
scons: done building targets. scons: done building targets.
$ $
The status messages (lines beginning with the scons: tag) may be suppress ed using the -Q option. The status messages (lines beginning with the scons: tag) may be suppress ed using the -Q option.
scons does not automatically propagate the external environment used to e To assure reproducible builds, SCons uses a restricted execution environm
xecute scons to the commands used ent for running external commands
to build target files. This is so that builds will be guaranteed repeatab used to build targets, rather then propagating the full environment in ef
le regardless of the environment fect at the time scons was
variables set at the time scons is invoked. This also means that if the c called. This helps avoid problems like picking up accidental settings, te
ompiler or other commands that mporary debug values that are no
you want to use to build your target files are not in standard system loc longer needed, or one developer having different settings than another (o
ations, scons will not find them r than the CI/CD pipeline).
unless you explicitly include the locations into the execution environmen Environment variables that are needed for proper operation of such comman
t by setting the path in the ENV ds need to be set explicitly,
construction variable in the internal construction environment: which can be done either by assigning the desired values, or by picking v
alues individually out of
environment variables using the Python os.environ dictionary. The executi
on environment for a given
construction environment is contained in its $ENV construction variable.
A few environment variables are
picked up automatically - see the section called “ENVIRONMENT”).
In particular, if the compiler or other commands that you want to use to
build your target files are not
in standard system locations, scons will not find them unless you explici
tly include the locations into
the PATH element of the execution environment. One example approach is to
extract the entire PATH
environment variable and set that into the execution environment:
import os import os
env = Environment(ENV={'PATH': os.environ['PATH']}) env = Environment(ENV={'PATH': os.environ['PATH']})
Similarly, if the commands use specific external environment variables th at scons does not recognize, they Similarly, if the commands use specific external environment variables th at scons does not recognize, they
can be propagated into the execution environment: can be propagated into the execution environment:
import os import os
env = Environment( env = Environment(
skipping to change at line 101 skipping to change at line 120
Or you may explicitly propagate the invoking user's complete external env ironment: Or you may explicitly propagate the invoking user's complete external env ironment:
import os import os
env = Environment(ENV=os.environ.copy()) env = Environment(ENV=os.environ.copy())
This comes at the expense of making your build dependent on the user's en vironment being set correctly, This comes at the expense of making your build dependent on the user's en vironment being set correctly,
but it may be more convenient for many configurations. It should not caus e problems if done in a build but it may be more convenient for many configurations. It should not caus e problems if done in a build
setup which tightly controls how the environment is set up before invokin g scons, as in many continuous setup which tightly controls how the environment is set up before invokin g scons, as in many continuous
integration setups. integration setups.
scons can scan known input file types automatically for dependency inform
ation (for example, #include
preprocessor directives in C or C++ files) and will rebuild dependent fil
es appropriately whenever any
"included" input file changes. scons supports the ability to define new
scanners to support additional
input file types.
scons is normally executed in a top-level directory containing an SConstr uct file. When scons is invoked, scons is normally executed in a top-level directory containing an SConstr uct file. When scons is invoked,
the command line (including the contents of the SCONSFLAGS environment va riable, if set) is processed. the command line (including the contents of the SCONSFLAGS environment va riable, if set) is processed.
Command-line options (see the section called “OPTIONS”) are consumed. Any variable argument assignments Command-line options (see the section called “OPTIONS”) are consumed. Any variable argument assignments
are collected, and remaining arguments are taken as targets to build. are collected, and remaining arguments are taken as targets to build.
Values of variables to be passed to the SConscript files may be specified on the command line: Values of variables to be passed to the SConscript files may be specified on the command line:
scons debug=1 scons debug=1
These variables are available through the ARGUMENTS dictionary, and can b e used in the SConscript files to These variables are available through the ARGUMENTS dictionary, and can b e used in the SConscript files to
skipping to change at line 488 skipping to change at line 502
directories are searched in the order specified. directories are searched in the order specified.
--ignore-virtualenv --ignore-virtualenv
Suppress importing virtualenv-related variables to SCons. Suppress importing virtualenv-related variables to SCons.
--implicit-cache --implicit-cache
Cache implicit dependencies. This causes scons to use the implicit (s canned) dependencies from the Cache implicit dependencies. This causes scons to use the implicit (s canned) dependencies from the
last time it was run instead of scanning the files for implicit depen dencies. This can significantly last time it was run instead of scanning the files for implicit depen dencies. This can significantly
speed up SCons, but with the following limitations: speed up SCons, but with the following limitations:
scons will not detect changes to implicit dependency search paths (e. scons will not detect changes to implicit dependency search paths (e.
g. CPPPATH, LIBPATH) that would g. $CPPPATH, $LIBPATH) that
ordinarily cause different versions of same-named files to be used. would ordinarily cause different versions of same-named files to be u
sed.
scons will miss changes in the implicit dependencies in cases where a new implicit dependency is added scons will miss changes in the implicit dependencies in cases where a new implicit dependency is added
earlier in the implicit dependency search path (e.g. CPPPATH, LIBPAT H) than a current implicit earlier in the implicit dependency search path (e.g. $CPPPATH, $LIBP ATH) than a current implicit
dependency with the same name. dependency with the same name.
--implicit-deps-changed --implicit-deps-changed
Forces SCons to ignore the cached implicit dependencies. This causes the implicit dependencies to be Forces SCons to ignore the cached implicit dependencies. This causes the implicit dependencies to be
rescanned and recached. This implies --implicit-cache. rescanned and recached. This implies --implicit-cache.
--implicit-deps-unchanged --implicit-deps-unchanged
Force SCons to ignore changes in the implicit dependencies. This caus es cached implicit dependencies Force SCons to ignore changes in the implicit dependencies. This caus es cached implicit dependencies
to always be used. This implies --implicit-cache. to always be used. This implies --implicit-cache.
skipping to change at line 583 skipping to change at line 597
-k, --keep-going -k, --keep-going
Continue as much as possible after an error. The target that failed a nd those that depend on it will Continue as much as possible after an error. The target that failed a nd those that depend on it will
not be remade, but other targets specified on the command line will s till be processed. not be remade, but other targets specified on the command line will s till be processed.
-m -m
Ignored for compatibility with non-GNU versions of Make. Ignored for compatibility with non-GNU versions of Make.
--max-drift=SECONDS --max-drift=SECONDS
Set the maximum expected drift in the modification time of files to S ECONDS. This value determines how Set the maximum expected drift in the modification time of files to S ECONDS. This value determines how
long a file must be unmodified before its cached content signature wi ll be used instead of calculating long a file must be unmodified before its cached content signature wi ll be used instead of calculating
a new content signature (MD5 checksum) of the file's contents. The de a new content signature (hash) of the file's contents. The default va
fault value is 2 days, which lue is 2 days, which means a file
means a file must have a modification time of at least two days ago i must have a modification time of at least two days ago in order to ha
n order to have its cached ve its cached content signature
content signature used. A negative value means to never cache the con used. A negative value means to never cache the content signature and
tent signature and to ignore the to ignore the cached value if
cached value if there already is one. A value of 0 means to always us there already is one. A value of 0 means to always use the cached sig
e the cached signature, no matter nature, no matter how old the
how old the file is. file is.
--md5-chunksize=KILOBYTES --md5-chunksize=KILOBYTES
A deprecated synonym for --hash-chunksize. A deprecated synonym for --hash-chunksize.
Deprecated since scons 4.2. Deprecated since scons 4.2.
-n, --no-exec, --just-print, --dry-run, --recon -n, --no-exec, --just-print, --dry-run, --recon
Set no execute mode. Print the commands that would be executed to bui ld any out-of-date target files, Set no execute mode. Print the commands that would be executed to bui ld any out-of-date target files,
but do not execute the commands. but do not execute the commands.
skipping to change at line 642 skipping to change at line 656
caching enabled, to prevent multiple builds from simultaneously tryin g to build or retrieve the same caching enabled, to prevent multiple builds from simultaneously tryin g to build or retrieve the same
target files. target files.
-s, --silent, --quiet -s, --silent, --quiet
Silent. Do not print commands that are executed to rebuild target fil es. Also suppresses SCons status Silent. Do not print commands that are executed to rebuild target fil es. Also suppresses SCons status
messages. messages.
-S, --no-keep-going, --stop -S, --no-keep-going, --stop
Ignored for compatibility with GNU Make Ignored for compatibility with GNU Make
--site-dir=dir --site-dir=path
Uses the named dir as the site directory rather than the default site Use a specific path as the site directory rather than searching the l
_scons directories. This ist of default site directories.
directory will be prepended to sys.path, the module dir/site_init.py This directory will be prepended to sys.path, the module path/site_in
will be loaded if it exists, and it.py will be loaded if it
dir/site_tools will be added to the default toolpath. exists, and path/site_tools will be added to the default toolpath.
The default set of site_scons directories used when --site-dir is not The default set of site directories searched when --site-dir is not s
specified depends on the system pecified depends on the system
platform, as follows. Directories are examined in the order given, fr platform, as follows. Users or system administrators can tune site-sp
om most generic to most specific, ecific or project-specific SCons
so the last-executed site_init.py file is the most specific one (whic behavior by setting up a site directory in one or more of these locat
h gives it the chance to override ions. Directories are examined in
the order given, from most generic ("system" directories) to most spe
cific (in the current project),
so the last-executed site_init.py file is the most specific one, givi
ng it the chance to override
everything else), and the directories are prepended to the paths, aga in so the last directory examined everything else), and the directories are prepended to the paths, aga in so the last directory examined
comes first in the resulting path. comes first in the resulting path.
Windows: Windows:
%ALLUSERSPROFILE/Application Data/scons/site_scons %ALLUSERSPROFILE%/scons/site_scons
%USERPROFILE%/Local Settings/Application Data/scons/site_scon %LOCALAPPDATA%/scons/site_scons
s
%APPDATA%/scons/site_scons %APPDATA%/scons/site_scons
%HOME%/.scons/site_scons %USERPROFILE%/.scons/site_scons
./site_scons ./site_scons
Note earlier versions of the documentation listed a different pat
h for the "system" site
directory, this path is still checked but its use is discouraged:
%ALLUSERSPROFILE%/Application Data/scons/site_scons
Mac OS X: Mac OS X:
/Library/Application Support/SCons/site_scons /Library/Application Support/SCons/site_scons
/opt/local/share/scons/site_scons (for MacPorts) /opt/local/share/scons/site_scons (for MacPorts)
/sw/share/scons/site_scons (for Fink) /sw/share/scons/site_scons (for Fink)
$HOME/Library/Application Support/SCons/site_scons $HOME/Library/Application Support/SCons/site_scons
$HOME/.scons/site_scons $HOME/.scons/site_scons
./site_scons ./site_scons
Solaris: Solaris:
skipping to change at line 918 skipping to change at line 939
As a convenience, construction variables may also be set or modified by t he parse_flags keyword argument As a convenience, construction variables may also be set or modified by t he parse_flags keyword argument
during object creation, which has the effect of the env.MergeFlags method being applied to the argument during object creation, which has the effect of the env.MergeFlags method being applied to the argument
value after all other processing is completed. This is useful either if t he exact content of the flags is value after all other processing is completed. This is useful either if t he exact content of the flags is
unknown (for example, read from a control file) or if the flags need to b e distributed to a number of unknown (for example, read from a control file) or if the flags need to b e distributed to a number of
construction variables. env.ParseFlags describes how these arguments are distributed to construction construction variables. env.ParseFlags describes how these arguments are distributed to construction
variables. variables.
env = Environment(parse_flags='-Iinclude -DEBUG -lm') env = Environment(parse_flags='-Iinclude -DEBUG -lm')
This example adds 'include' to the CPPPATH construction variable, 'EBUG' This example adds 'include' to the $CPPPATH construction variable, 'EBUG'
to CPPDEFINES, and 'm' to LIBS. to $CPPDEFINES, and 'm' to
$LIBS.
An existing construction environment can be duplicated by calling the env .Clone method. Without arguments, An existing construction environment can be duplicated by calling the env .Clone method. Without arguments,
it will be a copy with the same settings. Otherwise, env.Clone takes the same arguments as Environment, it will be a copy with the same settings. Otherwise, env.Clone takes the same arguments as Environment,
and uses the arguments to create a modified copy. and uses the arguments to create a modified copy.
SCons provides a special construction environment called the Default Envi ronment. The default environment SCons provides a special construction environment called the Default Envi ronment. The default environment
is used only for global functions, that is, construction activities calle d without the context of a is used only for global functions, that is, construction activities calle d without the context of a
regular construction environment. See DefaultEnvironment for more informa tion. regular construction environment. See DefaultEnvironment for more informa tion.
By default, a new construction environment is initialized with a set of b uilder methods and construction By default, a new construction environment is initialized with a set of b uilder methods and construction
skipping to change at line 964 skipping to change at line 986
which would otherwise identify as win32. which would otherwise identify as win32.
The optional tools and toolpath keyword arguments affect the way tools av ailable to the environment are The optional tools and toolpath keyword arguments affect the way tools av ailable to the environment are
initialized. See the section called “Tools” for details. initialized. See the section called “Tools” for details.
The optional variables keyword argument allows passing a Variables object which will be used in the The optional variables keyword argument allows passing a Variables object which will be used in the
initialization of the construction environment See the section called “Co mmand-Line Construction initialization of the construction environment See the section called “Co mmand-Line Construction
Variables” for details. Variables” for details.
Tools Tools
SCons has a large number of predefined tools (more properly, tool specifi SCons has a large number of predefined tool modules (more properly, tool
cations) which are used to help specification modules) which are
initialize the construction environment. An SCons tool is only responsibl used to help initialize the construction environment. An SCons tool is on
e for setup. For example, if the ly responsible for setup. For
SConscript file declares the need to construct an object file from a C-la example, if an SConscript file declares the need to construct an object f
nguage source file by calling the ile from a C-language source file
Object builder, then a tool representing an available C compiler needs to by calling the Object builder, then a tool representing an available C co
have run first, to set up that mpiler needs to have run first,
builder and all the construction variables it needs in the associated con to set up that builder and all the construction variables it needs in the
struction environment; the tool associated construction
itself is not called in the process of the build. Normally this happens i environment; the tool itself is not called in the process of the build. N
nvisibly: scons has per-platform ormally this happens invisibly as
lists of default tools, and it runs through those tools, calling the ones scons has per-platform lists of default tools, and it steps through those
which are actually applicable, tools, calling the ones which
skipping those where necessary programs are not installed on the build sy are actually applicable, skipping those where necessary programs are not
stem, or other preconditions are installed on the build system, or
not met. other preconditions are not met.
A specific set of tools with which to initialize an environment when crea ting it may be specified using A specific set of tools with which to initialize an environment when crea ting it may be specified using
the optional keyword argument tools, which takes a list of tool names. Th is is useful to override the the optional keyword argument tools, which takes a list of tool names. Th is is useful to override the
defaults, to specify non-default built-in tools, and to supply added tool s: defaults, to specify non-default built-in tools, and to supply added tool s:
env = Environment(tools=['msvc', 'lex']) env = Environment(tools=['msvc', 'lex'])
Tools can also be directly called by using the Tool method (see below). Tools can also be directly called by using the Tool method (see below).
The tools argument overrides the default tool list, it does not add to it , so be sure to include all the The tools argument overrides the default tool list, it does not add to it , so be sure to include all the
tools you need. For example if you are building a c/c++ program you must specify a tool for at least a tools you need. For example if you are building a c/c++ program you must specify a tool for at least a
compiler and a linker, as in tools=['clang', 'link']. The tool name 'defa ult' can be used to retain the compiler and a linker, as in tools=['clang', 'link']. The tool name 'defa ult' can be used to retain the
default list. default list.
If no tools argument is specified, or if tools includes 'default', then s cons will auto-detect usable If no tools argument is specified, or if tools includes 'default', then s cons will auto-detect usable
tools, using the execution environment value of PATH (that is, env['ENV'] ['PATH'] - the external tools, using the execution environment value of PATH (that is, env['ENV'] ['PATH'] - the external
evironment PATH from os.environ is not used) for looking up any backing p rograms, and the platform name in evironment PATH from os.environ is not used) for looking up any backing p rograms, and the platform name in
effect to determine the default tools for that platform. Changing the PAT H variable after the construction effect to determine the default tools for that platform. Changing the PAT H variable after the construction
environment is constructed will not cause the tools to be re-detected. environment is constructed will not cause the tools to be re-detected.
Additional tools can be added to a project either by placing them in a si Additional tools can be added, see the Extending SCons section and specif
te_tools subdirectory of a site ically Tool Modules.
directory, or in a custom location specified to scons by giving the toolp
ath keyword argument. toolpath
also takes a list as its value:
env = Environment(tools=['default', 'foo'], toolpath=['tools'])
This looks for a tool specification module foo.py in directory tools and
in the standard locations, as
well as using the ordinary default tools for the platform.
Directories specified via toolpath are prepended to the existing tool pat
h. The default tool path is any
site_tools directories, so tools in a specified toolpath take priority, f
ollowed by tools in a site_tools
directory, followed by built-in tools. For example, adding a tool specifi
cation module gcc.py to the
toolpath directory would override the built-in gcc tool. The tool path is
stored in the environment and
will be used by subsequent calls to the Tool method, as well as by env.Cl
one.
base = Environment(toolpath=['custom_path'])
derived = base.Clone(tools=['custom_tool'])
derived.CustomBuilder()
A tool specification module must include two functions:
generate(env, **kwargs)
Modifies the environment referenced by env to set up variables so tha
t the facilities represented by
the tool can be executed. It may use any keyword arguments that the u
ser supplies in kwargs to vary
its initialization.
exists(env)
Return True if the tool can be called in the context of env. Usually
this means looking up one or more
known programs using the PATH from the supplied env, but the tool can
make the "exists" decision in
any way it chooses.
Note
At the moment, user-added tools do not automatically have their exist
s function called. As a result,
it is recommended that the generate function be defensively coded - t
hat is, do not rely on any
necessary existence checks already having been performed. This is exp
ected to be a temporary
limitation, and the exists function should still be provided.
The elements of the tools list may also be functions or callable objects,
in which case the Environment
method will call those objects to update the new construction environment
(see Tool for more details):
def my_tool(env):
env['XYZZY'] = 'xyzzy'
env = Environment(tools=[my_tool])
The individual elements of the tools list may also themselves be lists or
tuples of the form (toolname,
kw_dict). SCons searches for the toolname specification file as described
above, and passes kw_dict, which
must be a dictionary, as keyword arguments to the tool's generate functio
n. The generate function can use
the arguments to modify the tool's behavior by setting up the environment
in different ways or otherwise
changing its initialization.
# in tools/my_tool.py:
def generate(env, **kwargs):
# Sets MY_TOOL to the value of keyword 'arg1' '1' if not supplied
env['MY_TOOL'] = kwargs.get('arg1', '1')
def exists(env):
return True
# in SConstruct:
env = Environment(tools=['default', ('my_tool', {'arg1': 'abc'})],
toolpath=['tools'])
The tool specification (my_tool in the example) can use the PLATFORM vari
able from the construction
environment it is passed to customize the tool for different platforms.
Tools can be "nested" - that is, they can be located within a subdirector
y in the toolpath. A nested tool
name uses a dot to represent a directory separator
# namespaced builder
env = Environment(ENV=os.environ.copy(), tools=['SubDir1.SubDir2.Some
Tool'])
env.SomeTool(targets, sources)
# Search Paths
# SCons\Tool\SubDir1\SubDir2\SomeTool.py
# SCons\Tool\SubDir1\SubDir2\SomeTool\__init__.py
# .\site_scons\site_tools\SubDir1\SubDir2\SomeTool.py
# .\site_scons\site_tools\SubDir1\SubDir2\SomeTool\__init__.py
SCons supports the following tool specifications out of the box: SCons supports the following tool specifications out of the box:
386asm 386asm
Sets construction variables for the 386ASM assembler for the Phar Lap ETS embedded operating system. Sets construction variables for the 386ASM assembler for the Phar Lap ETS embedded operating system.
Sets: $AS, $ASCOM, $ASFLAGS, $ASPPCOM, $ASPPFLAGS. Sets: $AS, $ASCOM, $ASFLAGS, $ASPPCOM, $ASPPFLAGS.
Uses: $CC, $CPPFLAGS, $_CPPDEFFLAGS, $_CPPINCFLAGS. Uses: $CC, $CPPFLAGS, $_CPPDEFFLAGS, $_CPPINCFLAGS.
skipping to change at line 1134 skipping to change at line 1079
Sets construction variables for the bcc32 compiler. Sets construction variables for the bcc32 compiler.
Sets: $CC, $CCCOM, $CCFLAGS, $CFILESUFFIX, $CFLAGS, $CPPDEFPREFIX, $C PPDEFSUFFIX, $INCPREFIX, Sets: $CC, $CCCOM, $CCFLAGS, $CFILESUFFIX, $CFLAGS, $CPPDEFPREFIX, $C PPDEFSUFFIX, $INCPREFIX,
$INCSUFFIX, $SHCC, $SHCCCOM, $SHCCFLAGS, $SHCFLAGS, $SHOBJSUFFIX. $INCSUFFIX, $SHCC, $SHCCCOM, $SHCCFLAGS, $SHCFLAGS, $SHOBJSUFFIX.
Uses: $_CPPDEFFLAGS, $_CPPINCFLAGS. Uses: $_CPPDEFFLAGS, $_CPPINCFLAGS.
cc cc
Sets construction variables for generic POSIX C compilers. Sets construction variables for generic POSIX C compilers.
Sets: $CC, $CCCOM, $CCFLAGS, $CFILESUFFIX, $CFLAGS, $CPPDEFPREFIX, $C Sets: $CC, $CCCOM, $CCDEPFLAGS, $CCFLAGS, $CFILESUFFIX, $CFLAGS, $CPP
PPDEFSUFFIX, $FRAMEWORKPATH, DEFPREFIX, $CPPDEFSUFFIX,
$FRAMEWORKS, $INCPREFIX, $INCSUFFIX, $SHCC, $SHCCCOM, $SHCCFLAGS, $SH $FRAMEWORKPATH, $FRAMEWORKS, $INCPREFIX, $INCSUFFIX, $SHCC, $SHCCCOM,
CFLAGS, $SHOBJSUFFIX. $SHCCFLAGS, $SHCFLAGS,
$SHOBJSUFFIX.
Uses: $CCCOMSTR, $PLATFORM, $SHCCCOMSTR. Uses: $CCCOMSTR, $PLATFORM, $SHCCCOMSTR.
clang clang
Set construction variables for the Clang C compiler. Set construction variables for the Clang C compiler.
Sets: $CC, $CCVERSION, $SHCCFLAGS. Sets: $CC, $CCDEPFLAGS, $CCVERSION, $SHCCFLAGS.
clangxx clangxx
Set construction variables for the Clang C++ compiler. Set construction variables for the Clang C++ compiler.
Sets: $CXX, $CXXVERSION, $SHCXXFLAGS, $SHOBJSUFFIX, $STATIC_AND_SHARE D_OBJECTS_ARE_THE_SAME. Sets: $CXX, $CXXVERSION, $SHCXXFLAGS, $SHOBJSUFFIX, $STATIC_AND_SHARE D_OBJECTS_ARE_THE_SAME.
compilation_db compilation_db
Sets up CompilationDatabase builder which generates a clang tooling c ompatible compilation database. Sets up CompilationDatabase builder which generates a clang tooling c ompatible compilation database.
Sets: $COMPILATIONDB_COMSTR, $COMPILATIONDB_PATH_FILTER, $COMPILATION DB_USE_ABSPATH. Sets: $COMPILATIONDB_COMSTR, $COMPILATIONDB_PATH_FILTER, $COMPILATION DB_USE_ABSPATH.
skipping to change at line 1349 skipping to change at line 1295
Sets: $DVIPS, $DVIPSFLAGS, $PSCOM, $PSPREFIX, $PSSUFFIX. Sets: $DVIPS, $DVIPSFLAGS, $PSCOM, $PSPREFIX, $PSSUFFIX.
Uses: $PSCOMSTR. Uses: $PSCOMSTR.
f03 f03
Set construction variables for generic POSIX Fortran 03 compilers. Set construction variables for generic POSIX Fortran 03 compilers.
Sets: $F03, $F03COM, $F03FLAGS, $F03PPCOM, $SHF03, $SHF03COM, $SHF03F LAGS, $SHF03PPCOM, $_F03INCFLAGS. Sets: $F03, $F03COM, $F03FLAGS, $F03PPCOM, $SHF03, $SHF03COM, $SHF03F LAGS, $SHF03PPCOM, $_F03INCFLAGS.
Uses: $F03COMSTR, $F03PPCOMSTR, $SHF03COMSTR, $SHF03PPCOMSTR. Uses: $F03COMSTR, $F03PPCOMSTR, $FORTRANCOMMONFLAGS, $SHF03COMSTR, $S HF03PPCOMSTR.
f08 f08
Set construction variables for generic POSIX Fortran 08 compilers. Set construction variables for generic POSIX Fortran 08 compilers.
Sets: $F08, $F08COM, $F08FLAGS, $F08PPCOM, $SHF08, $SHF08COM, $SHF08F LAGS, $SHF08PPCOM, $_F08INCFLAGS. Sets: $F08, $F08COM, $F08FLAGS, $F08PPCOM, $SHF08, $SHF08COM, $SHF08F LAGS, $SHF08PPCOM, $_F08INCFLAGS.
Uses: $F08COMSTR, $F08PPCOMSTR, $SHF08COMSTR, $SHF08PPCOMSTR. Uses: $F08COMSTR, $F08PPCOMSTR, $FORTRANCOMMONFLAGS, $SHF08COMSTR, $S HF08PPCOMSTR.
f77 f77
Set construction variables for generic POSIX Fortran 77 compilers. Set construction variables for generic POSIX Fortran 77 compilers.
Sets: $F77, $F77COM, $F77FILESUFFIXES, $F77FLAGS, $F77PPCOM, $F77PPFI LESUFFIXES, $FORTRAN, Sets: $F77, $F77COM, $F77FILESUFFIXES, $F77FLAGS, $F77PPCOM, $F77PPFI LESUFFIXES, $FORTRAN,
$FORTRANCOM, $FORTRANFLAGS, $SHF77, $SHF77COM, $SHF77FLAGS, $SHF77PPC OM, $SHFORTRAN, $SHFORTRANCOM, $FORTRANCOM, $FORTRANFLAGS, $SHF77, $SHF77COM, $SHF77FLAGS, $SHF77PPC OM, $SHFORTRAN, $SHFORTRANCOM,
$SHFORTRANFLAGS, $SHFORTRANPPCOM, $_F77INCFLAGS. $SHFORTRANFLAGS, $SHFORTRANPPCOM, $_F77INCFLAGS.
Uses: $F77COMSTR, $F77PPCOMSTR, $FORTRANCOMSTR, $FORTRANPPCOMSTR, $SH Uses: $F77COMSTR, $F77PPCOMSTR, $FORTRANCOMMONFLAGS, $FORTRANCOMSTR,
F77COMSTR, $SHF77PPCOMSTR, $FORTRANFLAGS, $FORTRANPPCOMSTR,
$SHFORTRANCOMSTR, $SHFORTRANPPCOMSTR. $SHF77COMSTR, $SHF77PPCOMSTR, $SHFORTRANCOMSTR, $SHFORTRANFLAGS, $SHF
ORTRANPPCOMSTR.
f90 f90
Set construction variables for generic POSIX Fortran 90 compilers. Set construction variables for generic POSIX Fortran 90 compilers.
Sets: $F90, $F90COM, $F90FLAGS, $F90PPCOM, $SHF90, $SHF90COM, $SHF90F LAGS, $SHF90PPCOM, $_F90INCFLAGS. Sets: $F90, $F90COM, $F90FLAGS, $F90PPCOM, $SHF90, $SHF90COM, $SHF90F LAGS, $SHF90PPCOM, $_F90INCFLAGS.
Uses: $F90COMSTR, $F90PPCOMSTR, $SHF90COMSTR, $SHF90PPCOMSTR. Uses: $F90COMSTR, $F90PPCOMSTR, $FORTRANCOMMONFLAGS, $SHF90COMSTR, $S HF90PPCOMSTR.
f95 f95
Set construction variables for generic POSIX Fortran 95 compilers. Set construction variables for generic POSIX Fortran 95 compilers.
Sets: $F95, $F95COM, $F95FLAGS, $F95PPCOM, $SHF95, $SHF95COM, $SHF95F LAGS, $SHF95PPCOM, $_F95INCFLAGS. Sets: $F95, $F95COM, $F95FLAGS, $F95PPCOM, $SHF95, $SHF95COM, $SHF95F LAGS, $SHF95PPCOM, $_F95INCFLAGS.
Uses: $F95COMSTR, $F95PPCOMSTR, $SHF95COMSTR, $SHF95PPCOMSTR. Uses: $F95COMSTR, $F95PPCOMSTR, $FORTRANCOMMONFLAGS, $SHF95COMSTR, $S HF95PPCOMSTR.
fortran fortran
Set construction variables for generic POSIX Fortran compilers. Set construction variables for generic POSIX Fortran compilers.
Sets: $FORTRAN, $FORTRANCOM, $FORTRANFLAGS, $SHFORTRAN, $SHFORTRANCOM , $SHFORTRANFLAGS, Sets: $FORTRAN, $FORTRANCOM, $FORTRANFLAGS, $SHFORTRAN, $SHFORTRANCOM , $SHFORTRANFLAGS,
$SHFORTRANPPCOM. $SHFORTRANPPCOM.
Uses: $FORTRANCOMSTR, $FORTRANPPCOMSTR, $SHFORTRANCOMSTR, $SHFORTRANP Uses: $CPPFLAGS, $FORTRANCOMSTR, $FORTRANPPCOMSTR, $SHFORTRANCOMSTR,
PCOMSTR. $SHFORTRANPPCOMSTR,
$_CPPDEFFLAGS.
g++ g++
Set construction variables for the g++ C++ compiler. Set construction variables for the g++ C++ compiler.
Sets: $CXX, $CXXVERSION, $SHCXXFLAGS, $SHOBJSUFFIX. Sets: $CXX, $CXXVERSION, $SHCXXFLAGS, $SHOBJSUFFIX.
g77 g77
Set construction variables for the g77 Fortran compiler. Calls the f7 Set construction variables for the g77 Fortran compiler.
7 Tool module to set variables.
Sets: $F77, $F77COM, $F77FILESUFFIXES, $F77PPCOM, $F77PPFILESUFFIXES,
$FORTRAN, $FORTRANCOM,
$FORTRANPPCOM, $SHF77, $SHF77COM, $SHF77FLAGS, $SHF77PPCOM, $SHFORTRA
N, $SHFORTRANCOM,
$SHFORTRANFLAGS, $SHFORTRANPPCOM.
Uses: $F77FLAGS, $FORTRANCOMMONFLAGS, $FORTRANFLAGS.
gas gas
Sets construction variables for the gas assembler. Calls the as tool. Sets construction variables for the gas assembler. Calls the as tool.
Sets: $AS. Sets: $AS.
gcc gcc
Set construction variables for the gcc C compiler. Set construction variables for the gcc C compiler.
Sets: $CC, $CCVERSION, $SHCCFLAGS. Sets: $CC, $CCDEPFLAGS, $CCVERSION, $SHCCFLAGS.
gdc gdc
Sets construction variables for the D language compiler GDC. Sets construction variables for the D language compiler GDC.
Sets: $DC, $DCOM, $DDEBUG, $DDEBUGPREFIX, $DDEBUGSUFFIX, $DFILESUFFIX , $DFLAGPREFIX, $DFLAGS, Sets: $DC, $DCOM, $DDEBUG, $DDEBUGPREFIX, $DDEBUGSUFFIX, $DFILESUFFIX , $DFLAGPREFIX, $DFLAGS,
$DFLAGSUFFIX, $DINCPREFIX, $DINCSUFFIX, $DLIB, $DLIBCOM, $DLIBDIRPREF IX, $DLIBDIRSUFFIX, $DFLAGSUFFIX, $DINCPREFIX, $DINCSUFFIX, $DLIB, $DLIBCOM, $DLIBDIRPREF IX, $DLIBDIRSUFFIX,
$DLIBFLAGPREFIX, $DLIBFLAGSUFFIX, $DLIBLINKPREFIX, $DLIBLINKSUFFIX, $ DLINK, $DLINKCOM, $DLIBFLAGPREFIX, $DLIBFLAGSUFFIX, $DLIBLINKPREFIX, $DLIBLINKSUFFIX, $ DLINK, $DLINKCOM,
$DLINKFLAGPREFIX, $DLINKFLAGS, $DLINKFLAGSUFFIX, $DPATH, $DRPATHPREFI X, $DRPATHSUFFIX, $DVERPREFIX, $DLINKFLAGPREFIX, $DLINKFLAGS, $DLINKFLAGSUFFIX, $DPATH, $DRPATHPREFI X, $DRPATHSUFFIX, $DVERPREFIX,
$DVERSIONS, $DVERSUFFIX, $SHDC, $SHDCOM, $SHDLIBVERSIONFLAGS, $SHDLIN K, $SHDLINKCOM, $SHDLINKFLAGS. $DVERSIONS, $DVERSUFFIX, $SHDC, $SHDCOM, $SHDLIBVERSIONFLAGS, $SHDLIN K, $SHDLINKCOM, $SHDLINKFLAGS.
skipping to change at line 1441 skipping to change at line 1394
Each of the above tools provides its own builder(s) which may be used to perform particular activities Each of the above tools provides its own builder(s) which may be used to perform particular activities
related to software internationalization. You may be however interest ed in top-level Translate related to software internationalization. You may be however interest ed in top-level Translate
builder. builder.
To use gettext tools add 'gettext' tool to your environment: To use gettext tools add 'gettext' tool to your environment:
env = Environment( tools = ['default', 'gettext'] ) env = Environment( tools = ['default', 'gettext'] )
gfortran gfortran
Sets construction variables for the GNU F95/F2003 GNU compiler. Sets construction variables for the GNU Fortran compiler. Calls the f
ortran Tool module to set
variables.
Sets: $F77, $F90, $F95, $FORTRAN, $SHF77, $SHF77FLAGS, $SHF90, $SHF90 FLAGS, $SHF95, $SHF95FLAGS, Sets: $F77, $F90, $F95, $FORTRAN, $SHF77, $SHF77FLAGS, $SHF90, $SHF90 FLAGS, $SHF95, $SHF95FLAGS,
$SHFORTRAN, $SHFORTRANFLAGS. $SHFORTRAN, $SHFORTRANFLAGS.
gnulink gnulink
Set construction variables for GNU linker/loader. Set construction variables for GNU linker/loader.
Sets: $LDMODULEVERSIONFLAGS, $RPATHPREFIX, $RPATHSUFFIX, $SHLIBVERSIO NFLAGS, $SHLINKFLAGS, Sets: $LDMODULEVERSIONFLAGS, $RPATHPREFIX, $RPATHSUFFIX, $SHLIBVERSIO NFLAGS, $SHLINKFLAGS,
$_LDMODULESONAME, $_SHLIBSONAME. $_LDMODULESONAME, $_SHLIBSONAME.
skipping to change at line 1565 skipping to change at line 1519
$DFLAGSUFFIX, $DINCPREFIX, $DINCSUFFIX, $DLIB, $DLIBCOM, $DLIBDIRPREF IX, $DLIBDIRSUFFIX, $DFLAGSUFFIX, $DINCPREFIX, $DINCSUFFIX, $DLIB, $DLIBCOM, $DLIBDIRPREF IX, $DLIBDIRSUFFIX,
$DLIBFLAGPREFIX, $DLIBFLAGSUFFIX, $DLIBLINKPREFIX, $DLIBLINKSUFFIX, $ DLINK, $DLINKCOM, $DLIBFLAGPREFIX, $DLIBFLAGSUFFIX, $DLIBLINKPREFIX, $DLIBLINKSUFFIX, $ DLINK, $DLINKCOM,
$DLINKFLAGPREFIX, $DLINKFLAGS, $DLINKFLAGSUFFIX, $DPATH, $DRPATHPREFI X, $DRPATHSUFFIX, $DVERPREFIX, $DLINKFLAGPREFIX, $DLINKFLAGS, $DLINKFLAGSUFFIX, $DPATH, $DRPATHPREFI X, $DRPATHSUFFIX, $DVERPREFIX,
$DVERSIONS, $DVERSUFFIX, $SHDC, $SHDCOM, $SHDLIBVERSIONFLAGS, $SHDLIN K, $SHDLINKCOM, $SHDLINKFLAGS. $DVERSIONS, $DVERSUFFIX, $SHDC, $SHDCOM, $SHDLIBVERSIONFLAGS, $SHDLIN K, $SHDLINKCOM, $SHDLINKFLAGS.
lex lex
Sets construction variables for the lex lexical analyser. Sets construction variables for the lex lexical analyser.
Sets: $LEX, $LEXCOM, $LEXFLAGS, $LEXUNISTD. Sets: $LEX, $LEXCOM, $LEXFLAGS, $LEXUNISTD.
Uses: $LEXCOMSTR. Uses: $LEXCOMSTR, $LEXFLAGS, $LEX_HEADER_FILE, $LEX_TABLES_FILE.
link link
Sets construction variables for generic POSIX linkers. This is a "sma rt" linker tool which selects a Sets construction variables for generic POSIX linkers. This is a "sma rt" linker tool which selects a
compiler to complete the linking based on the types of source files. compiler to complete the linking based on the types of source files.
Sets: $LDMODULE, $LDMODULECOM, $LDMODULEFLAGS, $LDMODULENOVERSIONSYML INKS, $LDMODULEPREFIX, Sets: $LDMODULE, $LDMODULECOM, $LDMODULEFLAGS, $LDMODULENOVERSIONSYML INKS, $LDMODULEPREFIX,
$LDMODULESUFFIX, $LDMODULEVERSION, $LDMODULEVERSIONFLAGS, $LIBDIRPREF IX, $LIBDIRSUFFIX, $LDMODULESUFFIX, $LDMODULEVERSION, $LDMODULEVERSIONFLAGS, $LIBDIRPREF IX, $LIBDIRSUFFIX,
$LIBLINKPREFIX, $LIBLINKSUFFIX, $LINK, $LINKCOM, $LINKFLAGS, $SHLIBSU FFIX, $SHLINK, $SHLINKCOM, $LIBLINKPREFIX, $LIBLINKSUFFIX, $LINK, $LINKCOM, $LINKFLAGS, $SHLIBSU FFIX, $SHLINK, $SHLINKCOM,
$SHLINKFLAGS, $__LDMODULEVERSIONFLAGS, $__SHLIBVERSIONFLAGS. $SHLINKFLAGS, $__LDMODULEVERSIONFLAGS, $__SHLIBVERSIONFLAGS.
skipping to change at line 1671 skipping to change at line 1625
mssdk mssdk
Sets variables for Microsoft Platform SDK and/or Windows SDK. Note th at unlike most other Tool Sets variables for Microsoft Platform SDK and/or Windows SDK. Note th at unlike most other Tool
modules, mssdk does not set construction variables, but sets the envi ronment variables in the modules, mssdk does not set construction variables, but sets the envi ronment variables in the
environment SCons uses to execute the Microsoft toolchain: %INCLUDE%, %LIB%, %LIBPATH% and %PATH%. environment SCons uses to execute the Microsoft toolchain: %INCLUDE%, %LIB%, %LIBPATH% and %PATH%.
Uses: $MSSDK_DIR, $MSSDK_VERSION, $MSVS_VERSION. Uses: $MSSDK_DIR, $MSSDK_VERSION, $MSVS_VERSION.
msvc msvc
Sets construction variables for the Microsoft Visual C/C++ compiler. Sets construction variables for the Microsoft Visual C/C++ compiler.
Sets: $BUILDERS, $CC, $CCCOM, $CCFLAGS, $CCPCHFLAGS, $CCPDBFLAGS, $CF ILESUFFIX, $CFLAGS, Sets: $BUILDERS, $CC, $CCCOM, $CCDEPFLAGS, $CCFLAGS, $CCPCHFLAGS, $CC PDBFLAGS, $CFILESUFFIX, $CFLAGS,
$CPPDEFPREFIX, $CPPDEFSUFFIX, $CXX, $CXXCOM, $CXXFILESUFFIX, $CXXFLAG S, $INCPREFIX, $INCSUFFIX, $CPPDEFPREFIX, $CPPDEFSUFFIX, $CXX, $CXXCOM, $CXXFILESUFFIX, $CXXFLAG S, $INCPREFIX, $INCSUFFIX,
$OBJPREFIX, $OBJSUFFIX, $PCHCOM, $PCHPDBFLAGS, $RC, $RCCOM, $RCFLAGS, $SHCC, $SHCCCOM, $SHCCFLAGS, $OBJPREFIX, $OBJSUFFIX, $PCHCOM, $PCHPDBFLAGS, $RC, $RCCOM, $RCFLAGS, $SHCC, $SHCCCOM, $SHCCFLAGS,
$SHCFLAGS, $SHCXX, $SHCXXCOM, $SHCXXFLAGS, $SHOBJPREFIX, $SHOBJSUFFIX . $SHCFLAGS, $SHCXX, $SHCXXCOM, $SHCXXFLAGS, $SHOBJPREFIX, $SHOBJSUFFIX .
Uses: $CCCOMSTR, $CXXCOMSTR, $PCH, $PCHSTOP, $PDB, $SHCCCOMSTR, $SHCX XCOMSTR. Uses: $CCCOMSTR, $CXXCOMSTR, $MSVC_NOTFOUND_POLICY, $PCH, $PCHSTOP, $ PDB, $SHCCCOMSTR, $SHCXXCOMSTR.
msvs msvs
Sets construction variables for Microsoft Visual Studio. Sets construction variables for Microsoft Visual Studio.
Sets: $MSVSBUILDCOM, $MSVSCLEANCOM, $MSVSENCODING, $MSVSPROJECTCOM, $ MSVSREBUILDCOM, $MSVSSCONS, Sets: $MSVSBUILDCOM, $MSVSCLEANCOM, $MSVSENCODING, $MSVSPROJECTCOM, $ MSVSREBUILDCOM, $MSVSSCONS,
$MSVSSCONSCOM, $MSVSSCONSCRIPT, $MSVSSCONSFLAGS, $MSVSSOLUTIONCOM. $MSVSSCONSCOM, $MSVSSCONSCRIPT, $MSVSSCONSFLAGS, $MSVSSOLUTIONCOM.
mwcc mwcc
Sets construction variables for the Metrowerks CodeWarrior compiler. Sets construction variables for the Metrowerks CodeWarrior compiler.
skipping to change at line 1707 skipping to change at line 1661
$SHLINK, $SHLINKCOM, $SHLINKFLAGS. $SHLINK, $SHLINKCOM, $SHLINKFLAGS.
nasm nasm
Sets construction variables for the nasm Netwide Assembler. Sets construction variables for the nasm Netwide Assembler.
Sets: $AS, $ASCOM, $ASFLAGS, $ASPPCOM, $ASPPFLAGS. Sets: $AS, $ASCOM, $ASFLAGS, $ASPPCOM, $ASPPFLAGS.
Uses: $ASCOMSTR, $ASPPCOMSTR. Uses: $ASCOMSTR, $ASPPCOMSTR.
ninja ninja
Sets up Ninja builder which generates a ninja build file, and then op tionally runs ninja. Sets up the Ninja builder, which generates a ninja build file, and th en optionally runs ninja.
Note Note
This is an experimental feature. This is an experimental feature. This functionality is subject to
change and/or removal without a
This functionality is subject to change and/or removal without de deprecation cycle.
precation cycle. Sets: $IMPLICIT_COMMAND_DEPENDENCIES, $NINJA_ALIAS_NAME, $NINJA_CMD_A
Sets: $IMPLICIT_COMMAND_DEPENDENCIES, $NINJA_ALIAS_NAME, $NINJA_COMPD RGS, $NINJA_COMPDB_EXPAND,
B_EXPAND, $NINJA_DIR, $NINJA_DEPFILE_PARSE_FORMAT, $NINJA_DIR, $NINJA_DISABLE_AUTO_RUN, $NI
$NINJA_DISABLE_AUTO_RUN, $NINJA_ENV_VAR_CACHE, $NINJA_FILE_NAME, $NIN NJA_ENV_VAR_CACHE,
JA_FORCE_SCONS_BUILD, $NINJA_FILE_NAME, $NINJA_FORCE_SCONS_BUILD, $NINJA_GENERATED_SOURCE_A
LIAS_NAME,
$NINJA_GENERATED_SOURCE_SUFFIXES, $NINJA_MSVC_DEPS_PREFIX, $NINJA_POO L, $NINJA_REGENERATE_DEPS, $NINJA_GENERATED_SOURCE_SUFFIXES, $NINJA_MSVC_DEPS_PREFIX, $NINJA_POO L, $NINJA_REGENERATE_DEPS,
$NINJA_SYNTAX, $_NINJA_REGENERATE_DEPS_FUNC, $__NINJA_NO. $NINJA_SCONS_DAEMON_KEEP_ALIVE, $NINJA_SCONS_DAEMON_PORT, $NINJA_SYNT AX, $_NINJA_REGENERATE_DEPS_FUNC.
Uses: $AR, $ARCOM, $ARFLAGS, $CC, $CCCOM, $CCFLAGS, $CXX, $CXXCOM, $E Uses: $AR, $ARCOM, $ARFLAGS, $CC, $CCCOM, $CCDEPFLAGS, $CCFLAGS, $CXX
SCAPE, $LINK, $LINKCOM, , $CXXCOM, $ESCAPE, $LINK,
$PLATFORM, $PRINT_CMD_LINE_FUNC, $PROGSUFFIX, $RANLIB, $RANLIBCOM, $S $LINKCOM, $PLATFORM, $PRINT_CMD_LINE_FUNC, $PROGSUFFIX, $RANLIB, $RAN
HCCCOM, $SHCXXCOM, $SHLINK, LIBCOM, $SHCCCOM, $SHCXXCOM,
$SHLINKCOM. $SHLINK, $SHLINKCOM.
packaging packaging
Sets construction variables for the Package Builder. If this tool is enabled, the --package-type Sets construction variables for the Package Builder. If this tool is enabled, the --package-type
command-line option is also enabled. command-line option is also enabled.
pdf pdf
Sets construction variables for the Portable Document Format builder. Sets construction variables for the Portable Document Format builder.
Sets: $PDFPREFIX, $PDFSUFFIX. Sets: $PDFPREFIX, $PDFSUFFIX.
skipping to change at line 1871 skipping to change at line 1825
Set construction variables for the Sun f95 Fortran compiler. Set construction variables for the Sun f95 Fortran compiler.
Sets: $F95, $FORTRAN, $SHF95, $SHF95FLAGS, $SHFORTRAN, $SHFORTRANFLAG S. Sets: $F95, $FORTRAN, $SHF95, $SHF95FLAGS, $SHFORTRAN, $SHFORTRANFLAG S.
sunlink sunlink
Sets construction variables for the Sun linker. Sets construction variables for the Sun linker.
Sets: $RPATHPREFIX, $RPATHSUFFIX, $SHLINKFLAGS. Sets: $RPATHPREFIX, $RPATHSUFFIX, $SHLINKFLAGS.
swig swig
Sets construction variables for the SWIG interface generator. Sets construction variables for the SWIG interface compiler.
Sets: $SWIG, $SWIGCFILESUFFIX, $SWIGCOM, $SWIGCXXFILESUFFIX, $SWIGDIR ECTORSUFFIX, $SWIGFLAGS, Sets: $SWIG, $SWIGCFILESUFFIX, $SWIGCOM, $SWIGCXXFILESUFFIX, $SWIGDIR ECTORSUFFIX, $SWIGFLAGS,
$SWIGINCPREFIX, $SWIGINCSUFFIX, $SWIGPATH, $SWIGVERSION, $_SWIGINCFLA GS. $SWIGINCPREFIX, $SWIGINCSUFFIX, $SWIGPATH, $SWIGVERSION, $_SWIGINCFLA GS.
Uses: $SWIGCOMSTR. Uses: $SWIGCOMSTR.
tar tar
Sets construction variables for the tar archiver. Sets construction variables for the tar archiver.
Sets: $TAR, $TARCOM, $TARFLAGS, $TARSUFFIX. Sets: $TAR, $TARCOM, $TARFLAGS, $TARSUFFIX.
skipping to change at line 1923 skipping to change at line 1877
$XGETTEXTFROMPREFIX, $XGETTEXTFROMSUFFIX, $XGETTEXTPATH, $XGETTEXTPAT HPREFIX, $XGETTEXTPATHSUFFIX, $XGETTEXTFROMPREFIX, $XGETTEXTFROMSUFFIX, $XGETTEXTPATH, $XGETTEXTPAT HPREFIX, $XGETTEXTPATHSUFFIX,
$_XGETTEXTDOMAIN, $_XGETTEXTFROMFLAGS, $_XGETTEXTPATHFLAGS. $_XGETTEXTDOMAIN, $_XGETTEXTFROMFLAGS, $_XGETTEXTPATHFLAGS.
Uses: $POTDOMAIN. Uses: $POTDOMAIN.
yacc yacc
Sets construction variables for the yacc parse generator. Sets construction variables for the yacc parse generator.
Sets: $YACC, $YACCCOM, $YACCFLAGS, $YACCHFILESUFFIX, $YACCHXXFILESUFF IX, $YACCVCGFILESUFFIX. Sets: $YACC, $YACCCOM, $YACCFLAGS, $YACCHFILESUFFIX, $YACCHXXFILESUFF IX, $YACCVCGFILESUFFIX.
Uses: $YACCCOMSTR. Uses: $YACCCOMSTR, $YACCFLAGS, $YACC_GRAPH_FILE, $YACC_HEADER_FILE.
zip zip
Sets construction variables for the zip archiver. Sets construction variables for the zip archiver.
Sets: $ZIP, $ZIPCOM, $ZIPCOMPRESSION, $ZIPFLAGS, $ZIPSUFFIX. Sets: $ZIP, $ZIPCOM, $ZIPCOMPRESSION, $ZIPFLAGS, $ZIPSUFFIX.
Uses: $ZIPCOMSTR. Uses: $ZIPCOMSTR.
Builder Methods Builder Methods
You tell scons what to build by calling Builders, functions which take pa You tell SCons what to build by calling Builders, functions which take pa
rticular action(s) to produce a rticular action(s) to produce
particular result type (conventionally described by the builder name such target(s) of a particular type (conventionally hinted at by the builder n
as Program) when given source ame, e.g. Program) from the
files of a particular type. Calling a builder defines one or more targets specified source files. A builder call is a declaration: SCons enters the
to the build system; whether the specified relationship into its
targets are actually built on a given invocation is determined by command internal dependency node graph, and only later makes the decision on whet
-line options, target selection her anything is actually built,
rules, and whether SCons determines the target(s) are out of date. since this depends on command-line options, target selection rules, and w
hether the target(s) are out of
SCons defines a number of builders, and you can also write your own. Buil date with respect to the sources.
ders are attached to a
construction environment as methods, and the available builder methods ar SCons provides a number of builders, and you can also write your own (see
e listed as key-value pairs in Builder Objects). Builders are
the BUILDERS attribute of the construction environment. The available bui created dynamically at run-time, often (though not always) by tools which
lders can be displayed like this determine whether the external
for debugging purposes: dependencies for the builder are satisfied, and which perform the necessa
ry setup (see Tools). Builders
are attached to a construction environment as methods. The available buil
der methods are registered as
key-value pairs in the $BUILDERS attribute of the construction environmen
t, so the available builders can
be examined. This example displays them for debugging purposes:
env = Environment() env = Environment()
print("Builders:", list(env['BUILDERS'])) print("Builders:", list(env['BUILDERS']))
Builder methods take two required arguments: target and source. Either ca Builder methods take two required arguments: target and source. The targe
n be passed as a scalar or as a t and source arguments can be
list. The target and source arguments can be specified either as position specified either as positional arguments, in which case target comes firs
al arguments, in which case t, or as keyword arguments, using
target comes first, or as keyword arguments, using target= and source=. A target= and source=. Although both arguments are nominally required, if t
lthough both arguments are here is a single source and the
nominally required, if there is a single source and the target can be inf target can be inferred the target argument can be omitted (see below). Bu
erred the target argument can be ilder methods also take a variety
omitted (see below). Builder methods also take a variety of keyword argum of keyword arguments, described below.
ents, described below.
Because long lists of file names can lead to a lot of quoting in a builde
The builder may add other targets beyond those requested if indicated by r call, SCons supplies a Split
an Emitter (see the section global function and a same-named environment method that splits a single
called “Builder Objects” and, for example, $PROGEMITTER for more informat string into a list, using strings
ion). of white-space characters as the delimiter (similar to the Python string
split method, but succeeds even
Because long lists of file names can lead to a lot of quoting, scons supp if the input isn't a string).
lies a Split global function and
a same-named environment method that splits a single string into a list,
using strings of white-space
characters as the delimiter. (similar to the Python string split method,
but succeeds even if the input
isn't a string.)
The following are equivalent examples of calling the Program builder meth od: The following are equivalent examples of calling the Program builder meth od:
env.Program('bar', ['bar.c', 'foo.c']) env.Program('bar', ['bar.c', 'foo.c'])
env.Program('bar', Split('bar.c foo.c')) env.Program('bar', Split('bar.c foo.c'))
env.Program('bar', env.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(source=['bar.c', 'foo.c'], target='bar')
env.Program(target='bar', source=Split('bar.c foo.c')) env.Program(target='bar', source=Split('bar.c foo.c'))
env.Program(target='bar', source=env.Split('bar.c foo.c')) env.Program(target='bar', source=env.Split('bar.c foo.c'))
env.Program('bar', source='bar.c foo.c'.split()) env.Program('bar', source='bar.c foo.c'.split())
Python follows the POSIX pathname convention for path strings: if a strin Sources and targets can be specified as a scalar or as a list, composed o
g begins with the operating f either strings or nodes (more
system pathname separator (on Windows both the slash and backslash separa on nodes below). When specifying path strings, Python follows the POSIX p
tor work, and any leading drive athname convention: if a string
specifier is ignored for the determination) it is considered an absolute begins with the operating system pathname separator (on Windows both the
path, otherwise it is a relative slash and backslash separator are
path. If the path string contains no separator characters, it is searched accepted, and any leading drive specifier is ignored for the determinatio
for as a file in the current n) it is considered an absolute
directory. If it contains separator characters, the search follows down f path, otherwise it is a relative path. If the path string contains no sep
rom the starting point, which is arator characters, it is searched
the top of the directory tree for an absolute path and the current direct for as a file in the current directory. If it contains separator characte
ory for a relative path. rs, the search follows down from
the starting point, which is the top of the directory tree for an absolut
e path and the current directory
for a relative path. The "current directory" in this context is the direc
tory of the SConscript file
currently being processed.
scons recognizes a third way to specify path strings: if the string begin s with the # character it is SCons also recognizes a third way to specify path strings: if the string begins with the # character it is
top-relative - it works like a relative path but the search follows down from the directory containing the top-relative - it works like a relative path but the search follows down from the directory containing the
top-level SConstruct rather than from the current directory. The # is all top-level SConstruct rather than from the current directory. The # can op
owed to be followed by a pathname tionally be followed by a
separator, which is ignored if found in that position. Top-relative paths pathname separator, which is ignored if found in that position. Top-relat
only work in places where scons ive paths only work in places
will interpret the path (see some examples below). To be used in other co where scons will interpret the path (see some examples below). To be used
ntexts the string will need to be in other contexts the string
converted to a relative or absolute path first. will need to be converted to a relative or absolute path first.
target and source can be absolute, relative, or top-relative. Relative pa
thnames are searched considering
the directory of the SConscript file currently being processed as the "cu
rrent directory".
Examples: Examples:
# The comments describing the targets that will be built # The comments describing the targets that will be built
# assume these calls are in a SConscript file in the # assume these calls are in a SConscript file in the
# a subdirectory named "subdir". # a subdirectory named "subdir".
# Builds the program "subdir/foo" from "subdir/foo.c": # Builds the program "subdir/foo" from "subdir/foo.c":
env.Program('foo', 'foo.c') env.Program('foo', 'foo.c')
skipping to change at line 2026 skipping to change at line 1980
When the target shares the same base name as the source and only the suff ix varies, and if the builder When the target shares the same base name as the source and only the suff ix varies, and if the builder
method has a suffix defined for the target file type, then the target arg ument may be omitted completely, method has a suffix defined for the target file type, then the target arg ument may be omitted completely,
and scons will deduce the target file name from the source file name. The following examples all build the and scons will deduce the target file name from the source file name. The following examples all build the
executable program bar (on POSIX systems) or bar.exe (on Windows systems) from the bar.c source file: executable program bar (on POSIX systems) or bar.exe (on Windows systems) from the bar.c source file:
env.Program(target='bar', source='bar.c') env.Program(target='bar', source='bar.c')
env.Program('bar', source='bar.c') env.Program('bar', source='bar.c')
env.Program(source='bar.c') env.Program(source='bar.c')
env.Program('bar.c') env.Program('bar.c')
As a convenience, a srcdir keyword argument may be specified when calling The optional srcdir keyword argument specifies that all source file strin
a Builder. When specified, all gs that are not absolute paths or
source file strings that are not absolute paths or top-relative paths wil top-relative paths shall be interpreted relative to the specified srcdir.
l be interpreted relative to the The following example will build
specified srcdir. The following example will build the build/prog (or bui the build/prog (or build/prog.exe on Windows) program from the files src/
ld/prog.exe on Windows) program f1.c and src/f2.c:
from the files src/f1.c and src/f2.c:
env.Program('build/prog', ['f1.c', 'f2.c'], srcdir='src') env.Program('build/prog', ['f1.c', 'f2.c'], srcdir='src')
The optional parse_flags keyword argument causes behavior similar to the
env.MergeFlags method, where the
argument value is broken into individual settings and merged into the app
ropriate construction variables.
env.Program('hello', 'hello.c', parse_flags='-Iinclude -DEBUG -lm')
This example adds 'include' to the $CPPPATH construction variable, 'EBUG'
to $CPPDEFINES, and 'm' to
$LIBS.
The optional chdir keyword argument specifies that the Builder's action(s
) should be executed after
changing directory. If the chdir argument is a path string or a directory
Node, scons will change to the
specified directory. If the chdir is not a string or Node and evaluates t
rue, then scons will change to
the target file's directory.
Warning
Python only keeps one current directory location even if there are mu
ltiple threads. This means that
use of the chdir argument will not work with the SCons -j option, bec
ause individual worker threads
spawned by SCons interfere with each other when they start changing d
irectory.
# scons will change to the "sub" subdirectory
# before executing the "cp" command.
env.Command(
target='sub/dir/foo.out',
source='sub/dir/foo.in',
action="cp dir/foo.in dir/foo.out",
chdir='sub',
)
# Because chdir is not a string, scons will change to the
# target's directory ("sub/dir") before executing the
# "cp" command.
env.Command('sub/dir/foo.out', 'sub/dir/foo.in', "cp foo.in foo.out",
chdir=True)
Note that SCons will not automatically modify its expansion of constructi
on variables like $TARGET and
$SOURCE when using the chdir keyword argument--that is, the expanded file
names will still be relative to
the top-level directory where the SConstruct was found, and consequently
incorrect relative to the chdir
directory. If you use the chdir keyword argument, you will typically need
to supply a different command
line using expansions like ${TARGET.file} and ${SOURCE.file} to use just
the filename portion of the
target and source.
Keyword arguments that are not specifically recognized are treated as con struction variable overrides, Keyword arguments that are not specifically recognized are treated as con struction variable overrides,
which replace or add those variables on a limited basis. These overrides will only be in effect when which replace or add those variables on a limited basis. These overrides will only be in effect when
building the target of the builder call, and will not affect other parts of the build. For example, if you building the target of the builder call, and will not affect other parts of the build. For example, if you
want to specify some libraries needed by just one program: want to specify some libraries needed by just one program:
env.Program('hello', 'hello.c', LIBS=['gl', 'glut']) env.Program('hello', 'hello.c', LIBS=['gl', 'glut'])
or generate a shared library with a non-standard suffix: or generate a shared library with a non-standard suffix:
env.SharedLibrary( env.SharedLibrary(
target='word', target='word',
source='word.cpp', source='word.cpp',
SHLIBSUFFIX='.ocx', SHLIBSUFFIX='.ocx',
LIBSUFFIXES=['.ocx'], LIBSUFFIXES=['.ocx'],
) )
Note that both the $SHLIBSUFFIX and $LIBSUFFIXES variables must be set if Note that both the $SHLIBSUFFIX and $LIBSUFFIXES construction variables m
you want scons to search ust be set if you want scons to
automatically for dependencies on the non-standard library names; see the search automatically for dependencies on the non-standard library names;
descriptions below of these see the descriptions of these
variables for more information. variables for more information.
The optional parse_flags keyword argument is recognized by builders. This
works similarly to the
env.MergeFlags method, where the argument value is broken into individual
settings and merged into the
appropriate construction variables.
env.Program('hello', 'hello.c', parse_flags='-Iinclude -DEBUG -lm')
This example adds 'include' to CPPPATH, 'EBUG' to CPPDEFINES, and 'm' to
LIBS.
Although the builder methods defined by scons are, in fact, methods of a construction environment object, Although the builder methods defined by scons are, in fact, methods of a construction environment object,
many may also be called without an explicit environment: many may also be called without an explicit environment:
Program('hello', 'hello.c') Program('hello', 'hello.c')
SharedLibrary('word', 'word.cpp') SharedLibrary('word', 'word.cpp')
If called this way, methods will internally use the default environment t hat consists of the tools and If called this way, the builder will internally use the Default Environme nt that consists of the tools and
values that scons has determined are appropriate for the local system. values that scons has determined are appropriate for the local system.
Builder methods that can be called without an explicit environment (indic ated in the listing of builders Builder methods that can be called without an explicit environment (indic ated in the listing of builders
without a leading env.) may be called from custom Python modules that you below without a leading env.) may be called from custom Python modules th
import into an SConscript file at you import into an SConscript
by adding the following to the Python module: file by adding the following to the Python module:
from SCons.Script import * from SCons.Script import *
Builder methods return a NodeList, a list-like object whose elements are A builder may add additional targets beyond those requested if an attache
Nodes, SCons' internal d Emitter chooses to do so (see
representation of build targets or sources. See the section called “File the section called “Builder Objects” for more information. $PROGEMITTER
and Directory Nodes” for more is an example). For example, the
information. The returned NodeList object can be passed to other builder GNU linker takes a command-line argument -Map=mapfile, which causes it to
methods as source(s) or passed to produce a linker map file in
any SCons function or method where a filename would normally be accepted. addition to the executable file actually being linked. If the Program bui
lder's emitter is configured to
add this mapfile if the option is set, then two targets will be returned
when you only provided for one.
For this reason, builder methods always return a NodeList, a list-like ob
ject whose elements are Nodes.
Nodes are the internal representation of build targets or sources (see th
e section called “Node Objects”
for more information). The returned NodeList object can be passed to othe
r builder methods as source(s) or
to other SCons functions or methods where a path string would normally be
accepted.
For example, to add a specific preprocessor define when compiling one spe cific object file but not the For example, to add a specific preprocessor define when compiling one spe cific object file but not the
others: others:
bar_obj_list = env.StaticObject('bar.c', CPPDEFINES='-DBAR') bar_obj_list = env.StaticObject('bar.c', CPPDEFINES='-DBAR')
env.Program("prog", ['foo.c', bar_obj_list, 'main.c']) env.Program("prog", ['foo.c', bar_obj_list, 'main.c'])
Using a Node as in this example makes for a more portable build by avoidi ng having to specify a Using a Node as in this example makes for a more portable build by avoidi ng having to specify a
platform-specific object suffix when calling the Program builder method. platform-specific object suffix when calling the Program builder method.
The NodeList object is also convenient to pass to the Default function, f or the same reason of avoiding a The NodeList object is also convenient to pass to the Default function, f or the same reason of avoiding a
platform-specific name: platform-specific name:
tgt = env.Program("prog", ["foo.c", "bar.c", "main.c"]) tgt = env.Program("prog", ["foo.c", "bar.c", "main.c"])
Default(tgt) Default(tgt)
Builder calls will automatically "flatten" lists passed as source and tar get, so they are free to contain Builder calls will automatically "flatten" lists passed as source and tar get, so they are free to contain
elements which are themselves lists, such as bar_obj_list returned by the elements which are themselves lists, such as bar_obj_list returned by the
StaticObject call above. If you StaticObject call. If you need
need to manipulate a list of lists returned by builders directly in Pytho to manipulate a list of lists returned by builders directly in Python cod
n code, you can either build a e, you can either build a new
new list by hand: list by hand:
foo = Object('foo.c') foo = Object('foo.c')
bar = Object('bar.c') bar = Object('bar.c')
objects = ['begin.o'] + foo + ['middle.o'] + bar + ['end.o'] objects = ['begin.o'] + foo + ['middle.o'] + bar + ['end.o']
for obj in objects: for obj in objects:
print(str(obj)) print(str(obj))
Or you can use the Flatten function supplied by scons to create a list co ntaining just the Nodes, which Or you can use the Flatten function supplied by SCons to create a list co ntaining just the Nodes, which
may be more convenient: may be more convenient:
foo = Object('foo.c') foo = Object('foo.c')
bar = Object('bar.c') bar = Object('bar.c')
objects = Flatten(['begin.o', foo, 'middle.o', bar, 'end.o']) objects = Flatten(['begin.o', foo, 'middle.o', bar, 'end.o'])
for obj in objects: for obj in objects:
print(str(obj)) print(str(obj))
SCons builder calls return a list-like object, not an actual Python list, Since builder calls return a list-like object, not an actual Python list,
so it is not appropriate to use it is not appropriate to use the
the Python add operator (+ or +=) to append builder results to a Python l Python add operator (+ or +=) to append builder results to a Python list.
ist. Because the list and the Because the list and the object
object are different types, Python will not update the original list in p are different types, Python will not update the original list in place, b
lace, but will instead create a ut will instead create a new
new NodeList object containing the concatenation of the list elements and NodeList object containing the concatenation of the list elements and the
the builder results. This will builder results. This will cause
cause problems for any other Python variables in your SCons configuration problems for any other Python variables in your SCons configuration that
that still hold on to a still hold on to a reference to
reference to the original list. Instead, use the Python list extend metho the original list. Instead, use the Python list extend method to make sur
d to make sure the list is e the list is updated in-place.
updated in-place. Example: Example:
object_files = [] object_files = []
# Do NOT use += here: # Do NOT use += here:
# object_files += Object('bar.c') # object_files += Object('bar.c')
# #
# It will not update the object_files list in place. # It will not update the object_files list in place.
# #
# Instead, use the list extend method: # Instead, use the list extend method:
object_files.extend(Object('bar.c')) object_files.extend(Object('bar.c'))
The path name for a Node's file may be used by passing the Node to Python 's builtin str function: The path name for a Node's file may be used by passing the Node to Python 's builtin str function:
bar_obj_list = env.StaticObject('bar.c', CPPDEFINES='-DBAR') bar_obj_list = env.StaticObject('bar.c', CPPDEFINES='-DBAR')
print("The path to bar_obj is:", str(bar_obj_list[0])) print("The path to bar_obj is:", str(bar_obj_list[0]))
Note that because the Builder call returns a NodeList, you have to access the first element in the list, Note that because the Builder call returns a NodeList, you have to access the first element in the list
(bar_obj_list[0] in the example) to get at the Node that actually represe nts the object file. (bar_obj_list[0] in the example) to get at the Node that actually represe nts the object file.
Builder calls support a chdir keyword argument that specifies that the Bu
ilder's action(s) should be
executed after changing directory. If the chdir argument is a string or a
directory Node, scons will
change to the specified directory. If the chdir is not a string or Node a
nd 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 not automatically modify its expansion of constructi
on variables like $TARGET and
$SOURCE when using the chdir keyword argument--that is, the expanded file
names will still be relative to
the top-level directory where SConstruct was found, and consequently inco
rrect relative to the chdir
directory. If you use the chdir keyword argument, you will typically need
to supply a different command
line using expansions like ${TARGET.file} and ${SOURCE.file} to use just
the filename portion of the
targets and source.
When trying to handle errors that may occur in a builder method, consider that the corresponding Action is When trying to handle errors that may occur in a builder method, consider that the corresponding Action is
executed at a different time than the SConscript file statement calling t he builder. It is not useful to executed at a different time than the SConscript file statement calling t he builder. It is not useful to
wrap a builder call in a try block, since success in the builder call is not the same as the builder wrap a builder call in a try block, since success in the builder call is not the same as the builder
itself succeeding. If necessary, a Builder's Action should be coded to ex it with a useful exception itself succeeding. If necessary, a Builder's Action should be coded to ex it with a useful exception
message indicating the problem in the SConscript files - programmatically recovering from build errors is message indicating the problem in the SConscript files - programmatically recovering from build errors is
rarely useful. rarely useful.
scons predefines the following builder methods. Depending on the setup of The following builder methods are predefined in the SCons core software d
a particular construction istribution. Depending on the
environment and on the type and software installation status of the under setup of a particular construction environment and on the type and softwa
lying system, not all builders re installation status of the
may be available to that construction environment. underlying system, not all builders may be available in that construction
environment. Since the function
calling signature is the same for all builders:
Buildername(target, source, [key=val, ...])
it is omitted in this listing for brevity.
CFile(), env.CFile() CFile(), env.CFile()
Builds a C source file given a lex (.l) or yacc (.y) input file. The suffix specified by the 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 a dded to the target if it is not $CFILESUFFIX construction variable (.c by default) is automatically a dded to the target if it is not
already present. Example: already present. Example:
# builds foo.c # builds foo.c
env.CFile(target = 'foo.c', source = 'foo.l') env.CFile(target = 'foo.c', source = 'foo.l')
# builds bar.c # builds bar.c
env.CFile(target = 'bar', source = 'bar.y') env.CFile(target = 'bar', source = 'bar.y')
skipping to change at line 2831 skipping to change at line 2801
Example Usage: Example Usage:
env.MSVSSolution( env.MSVSSolution(
target="Bar" + env["MSVSSOLUTIONSUFFIX"], target="Bar" + env["MSVSSOLUTIONSUFFIX"],
projects=["bar" + env["MSVSPROJECTSUFFIX"]], projects=["bar" + env["MSVSPROJECTSUFFIX"]],
variant="Release", variant="Release",
) )
Ninja(), env.Ninja() Ninja(), env.Ninja()
A special builder which adds a target to create a Ninja build file. T
Ninja is a special builder which adds a target to create a ninja buil he builder does not require any
d file. The builder does not source files to be specified.
require any source files to be specified.
Note Note
This is an experimental feature. To enable it you must use one of the following methods This is an experimental feature. To enable it you must use one of the following methods
# On the command line # On the command line
--experimental=ninja --experimental=ninja
# Or in your SConstruct # Or in your SConstruct
SetOption('experimental', 'ninja') SetOption('experimental', 'ninja')
This functionality is subject to change and/or removal without de precation cycle. This functionality is subject to change and/or removal without de precation cycle.
To use this tool you must install pypi's ninja package[4]. This c To use this tool you need to install the Python ninja package, as
an be done via pip install ninja the tool by default depends on
being able to do an import of the package This can be done via:
python -m pip install ninja
If called with no arguments, the builder will default to a target nam e of ninja.build. If called with no arguments, the builder will default to a target nam e of ninja.build.
If called with a single positional argument, scons will "deduce" the target name from that source If called with a single positional argument, scons will "deduce" the target name from that source
argument, giving it the same name, and then ignore the source. This i s the usual way to call the argument, giving it the same name, and then ignore the source. This i s the usual way to call the
builder if a non-default target name is wanted. builder if a non-default target name is wanted.
If called with either the target= or source= keyword arguments, the v alue of the argument is taken as If called with either the target= or source= keyword arguments, the v alue of the argument is taken as
the target name. If called with both, the target= value is used and s ource= is ignored. If called with the target name. If called with both, the target= value is used and s ource= is ignored. If called with
multiple sources, the source list will be ignored, since there is no way to deduce what the intent multiple sources, the source list will be ignored, since there is no way to deduce what the intent
was; in this case the default target name will be used. was; in this case the default target name will be used.
skipping to change at line 3717 skipping to change at line 3690
Adds function to an object as a method. function will be called with an instance object as the first Adds function to an object as a method. function will be called with an instance object as the first
argument as for other methods. If name is given, it is used as the na me of the new method, else the argument as for other methods. If name is given, it is used as the na me of the new method, else the
name of function is used. name of function is used.
When the global function AddMethod is called, the object to add the m ethod to must be passed as the When the global function AddMethod is called, the object to add the m ethod to must be passed as the
first argument; typically this will be Environment, in order to creat e a method which applies to all first argument; typically this will be Environment, in order to creat e a method which applies to all
construction environments subsequently constructed. When called using the env.AddMethod form, the construction environments subsequently constructed. When called using the env.AddMethod form, the
method is added to the specified construction environment only. Added methods propagate through method is added to the specified construction environment only. Added methods propagate through
env.Clone calls. env.Clone calls.
Examples: More examples:
# Function to add must accept an instance argument. # Function to add must accept an instance argument.
# The Python convention is to call this 'self'. # The Python convention is to call this 'self'.
def my_method(self, arg): def my_method(self, arg):
print("my_method() got", arg) print("my_method() got", arg)
# Use the global function to add a method to the Environment clas s: # Use the global function to add a method to the Environment clas s:
AddMethod(Environment, my_method) AddMethod(Environment, my_method)
env = Environment() env = Environment()
env.my_method('arg') env.my_method('arg')
skipping to change at line 3890 skipping to change at line 3863
If env. does not have a construction variable indicated by key, val i s added to the environment under If env. does not have a construction variable indicated by key, val i s added to the environment under
that key as-is. that key as-is.
val can be almost any type, and SCons will combine it with an existin g value into an appropriate type, val can be almost any type, and SCons will combine it with an existin g value into an appropriate type,
but there are a few special cases to be aware of. When two strings ar e combined, the result is but there are a few special cases to be aware of. When two strings ar e combined, the result is
normally a new string, with the caller responsible for supplying any needed separation. The exception normally a new string, with the caller responsible for supplying any needed separation. The exception
to this is the construction variable $CPPDEFINES, in which each item will be postprocessed by adding a to this is the construction variable $CPPDEFINES, in which each item will be postprocessed by adding a
prefix and/or suffix, so the contents are treated as a list of string s, that is, adding a string will prefix and/or suffix, so the contents are treated as a list of string s, that is, adding a string will
result in a separate string entry, not a combined string. For $CPPDEF INES as well as for $LIBS, and result in a separate string entry, not a combined string. For $CPPDEF INES as well as for $LIBS, and
the various *PATH variables, SCons will supply the compiler-specific syntax (e.g. adding a -D or /D the various *PATH; variables, SCons will supply the compiler-specific syntax (e.g. adding a -D or /D
prefix for $CPPDEFINES), so this syntax should be omitted when adding values to these variables. prefix for $CPPDEFINES), so this syntax should be omitted when adding values to these variables.
Example (gcc syntax shown in the expansion of CPPDEFINES): Example (gcc syntax shown in the expansion of CPPDEFINES):
env = Environment(CXXFLAGS="-std=c11", CPPDEFINES="RELEASE") env = Environment(CXXFLAGS="-std=c11", CPPDEFINES="RELEASE")
print("CXXFLAGS={}, CPPDEFINES={}".format(env['CXXFLAGS'], env['C PPDEFINES'])) print("CXXFLAGS={}, CPPDEFINES={}".format(env['CXXFLAGS'], env['C PPDEFINES']))
# notice including a leading space in CXXFLAGS value # notice including a leading space in CXXFLAGS value
env.Append(CXXFLAGS=" -O", CPPDEFINES="EXTRA") env.Append(CXXFLAGS=" -O", CPPDEFINES="EXTRA")
print("CXXFLAGS={}, CPPDEFINES={}".format(env['CXXFLAGS'], env['C PPDEFINES'])) print("CXXFLAGS={}, CPPDEFINES={}".format(env['CXXFLAGS'], env['C PPDEFINES']))
print("CPPDEFINES will expand to {}".format(env.subst("$_CPPDEFFL AGS"))) print("CPPDEFINES will expand to {}".format(env.subst("$_CPPDEFFL AGS")))
skipping to change at line 3946 skipping to change at line 3919
When using env.Append to modify construction variables which are path specifications (conventionally, When using env.Append to modify construction variables which are path specifications (conventionally,
the names of such end in PATH), it is recommended to add the values a s a list of strings, even if the names of such end in PATH), it is recommended to add the values a s a list of strings, even if
there is only a single string to add. The same goes for adding librar y names to $LIBS. there is only a single string to add. The same goes for adding librar y names to $LIBS.
env.Append(CPPPATH=["#/include"]) env.Append(CPPPATH=["#/include"])
See also env.AppendUnique, env.Prepend and env.PrependUnique. See also env.AppendUnique, env.Prepend and env.PrependUnique.
env.AppendENVPath(name, newpath, [envname, sep, delete_existing=False]) env.AppendENVPath(name, newpath, [envname, sep, delete_existing=False])
Append new path elements to the given path in the specified external Append path elements specified by newpath to the given search path st
environment ($ENV by default). ring or list name in mapping
This will only add any particular path once (leaving the last one it envname in the construction environment. Supplying envname is optiona
encounters and ignoring the rest, l: the default is the execution
to preserve path order), and to help assure this, will normalize all environment $ENV. Optional sep is used as the search path separator,
paths (using os.path.normpath and the default is the platform's
os.path.normcase). This can also handle the case where the given old separator (os.pathsep). A path element will only appear once. Any dup
path variable is a list instead licates in newpath are dropped,
of a string, in which case a list will be returned instead of a strin keeping the last appearing (to preserve path order). If delete_existi
g. ng is False (the default) any
addition duplicating an existing path element is ignored; if delete_e
If delete_existing is False, then adding a path that already exists w xisting is True the existing
ill not move it to the end; it value will be dropped and the path element will be added at the end.
will stay where it is in the list. To help maintain uniqueness all
paths are normalized (using os.path.normpath and os.path.normcase).
Example: Example:
print('before:', env['ENV']['INCLUDE']) print('before:', env['ENV']['INCLUDE'])
include_path = '/foo/bar:/foo' include_path = '/foo/bar:/foo'
env.AppendENVPath('INCLUDE', include_path) env.AppendENVPath('INCLUDE', include_path)
print('after:', env['ENV']['INCLUDE']) print('after:', env['ENV']['INCLUDE'])
Yields: Yields:
before: /foo:/biz before: /foo:/biz
after: /biz:/foo/bar:/foo after: /biz:/foo/bar:/foo
See also env.PrependENVPath.
env.AppendUnique(key=val, [...], delete_existing=False) env.AppendUnique(key=val, [...], delete_existing=False)
Append values to construction variables in the current construction e nvironment, maintaining Append values to construction variables in the current construction e nvironment, maintaining
uniqueness. Works like env.Append (see for details), except that valu es already present in the uniqueness. Works like env.Append (see for details), except that valu es already present in the
construction variable will not be added again. If delete_existing is True, the existing matching value construction variable will not be added again. If delete_existing is True, the existing matching value
is first removed, and the requested value is added, having the effect of moving such values to the is first removed, and the requested value is added, having the effect of moving such values to the
end. end.
Example: Example:
env.AppendUnique(CCFLAGS='-g', FOO=['foo.yyy']) env.AppendUnique(CCFLAGS='-g', FOO=['foo.yyy'])
skipping to change at line 4028 skipping to change at line 4003
--cache-readonly. --cache-readonly.
If the --cache-force option is used, scons will place a copy of all d erived files in the cache, even If the --cache-force option is used, scons will place a copy of all d erived files in the cache, even
if they already existed and were not built by this invocation. This i s useful to populate a cache the if they already existed and were not built by this invocation. This i s useful to populate a cache the
first time a cache_dir is used for a build, or to bring a cache up to date after a build with cache first time a cache_dir is used for a build, or to bring a cache up to date after a build with cache
updating disabled (--cache-disable or --cache-readonly) has been done . updating disabled (--cache-disable or --cache-readonly) has been done .
The NoCache method can be used to disable caching of specific files. This can be useful if inputs The NoCache method can be used to disable caching of specific files. This can be useful if inputs
and/or outputs of some tool are impossible to predict or prohibitivel y large. and/or outputs of some tool are impossible to predict or prohibitivel y large.
Note that (at this time) SCons provides no facilities for managing th
e derived-file cache. It is up to
the developer to arrange for cache pruning, expiry, etc. if needed.
Clean(targets, files_or_dirs), env.Clean(targets, files_or_dirs) Clean(targets, files_or_dirs), env.Clean(targets, files_or_dirs)
This specifies a list of files or directories which should be removed whenever the targets are This specifies a list of files or directories which should be removed whenever the targets are
specified with the -c command line option. The specified targets may be a list or an individual specified with the -c command line option. The specified targets may be a list or an individual
target. Multiple calls to Clean are legal, and create new targets or add files and directories to the target. Multiple calls to Clean are legal, and create new targets or add files and directories to the
clean list for the specified targets. clean list for the specified targets.
Multiple files or directories should be specified either as separate arguments to the Clean method, or Multiple files or directories should be specified either as separate arguments to the Clean method, or
as a list. Clean will also accept the return value of any of the con struction environment Builder as a list. Clean will also accept the return value of any of the con struction environment Builder
methods. Examples: methods. Examples:
skipping to change at line 4279 skipping to change at line 4257
# Arrange for the library to be copied into the installation # Arrange for the library to be copied into the installation
# directory before trying to build the "bar" program. # directory before trying to build the "bar" program.
# (Note that this is for example only. A "real" library # (Note that this is for example only. A "real" library
# dependency would normally be configured through the $LIBS # dependency would normally be configured through the $LIBS
# and $LIBPATH variables, not using an env.Depends() call.) # and $LIBPATH variables, not using an env.Depends() call.)
env.Depends(bar, installed_lib) env.Depends(bar, installed_lib)
env.Detect(progs) env.Detect(progs)
Find an executable from one or more choices: progs may be a string or a list of strings. Returns the Find an executable from one or more choices: progs may be a string or a list of strings. Returns the
first value from progs that was found, or None. Executable is searche first value from progs that was found, or None. Executable is searche
d by checking the paths specified d by checking the paths in the
by env['ENV']['PATH']. On Windows systems, additionally applies the f execution environment (env['ENV']['PATH']). On Windows systems, addit
ilename suffixes found in ionally applies the filename
env['ENV']['PATHEXT'] but will not include any such extension in the suffixes found in the execution environment (env['ENV']['PATHEXT']) b
return value. env.Detect is a ut will not include any such
wrapper around env.WhereIs. extension in the return value. env.Detect is a wrapper around env.Wh
ereIs.
env.Dictionary([vars]) env.Dictionary([vars])
Returns a dictionary object containing the construction variables in the construction environment. If Returns a dictionary object containing the construction variables in the construction environment. If
there are any arguments specified, the values of the specified constr uction variables are returned as there are any arguments specified, the values of the specified constr uction variables are returned as
a string (if one argument) or as a list of strings. a string (if one argument) or as a list of strings.
Example: Example:
cvars = env.Dictionary() cvars = env.Dictionary()
cc_values = env.Dictionary('CC', 'CCFLAGS', 'CCCOM') cc_values = env.Dictionary('CC', 'CCFLAGS', 'CCCOM')
skipping to change at line 4369 skipping to change at line 4347
EnsureSConsVersion(0,14) EnsureSConsVersion(0,14)
EnsureSConsVersion(0,96,90) EnsureSConsVersion(0,96,90)
Environment([key=value, ...]), env.Environment([key=value, ...]) Environment([key=value, ...]), env.Environment([key=value, ...])
Return a new construction environment initialized with the specified key=value pairs. The keyword Return a new construction environment initialized with the specified key=value pairs. The keyword
arguments parse_flags, platform, toolpath, tools and variables are al so specially recognized. See the arguments parse_flags, platform, toolpath, tools and variables are al so specially recognized. See the
manpage section "Construction Environments" for more details. manpage section "Construction Environments" for more details.
Execute(action, [strfunction, varlist]), env.Execute(action, [strfunction Execute(action, [actionargs ...]), env.Execute(action, [actionargs ...])
, varlist]) Executes an Action. action may be an Action object or it may be a co
Executes an Action object. The specified action may be an Action obje mmand-line string, list of
ct (see manpage section "Action commands, or executable Python function, each of which will first be
Objects" for an explanation of behavior), or it may be a command-line converted into an Action object
string, list of commands, or and then executed. Any additional arguments to Execute are passed on
executable Python function, each of which will be converted into an A to the Action factory function
ction object and then executed. which actually creates the Action object (see the manpage section Act
Any additional arguments to Execute (strfunction, varlist) are passed ion Objects for a description).
on to the Action factory Example:
function which actually creates the Action object. The exit value of
the command or return value of
the Python function will be returned.
Note that scons will print an error message if the executed action fa
ils--that is, exits with or
returns a non-zero value. scons will not, however, automatically ter
minate the build if the specified
action fails. If you want the build to stop in response to a failed E
xecute call, you must explicitly
check for a non-zero return value:
Execute(Copy('file.out', 'file.in')) Execute(Copy('file.out', 'file.in'))
Execute performs its action immediately, as part of the SConscript-re
ading phase. There are no sources
or targets declared in an Execute call, so any objects it manipulates
will not be tracked as part of
the SCons dependency graph. In the example above, neither file.out no
r file.in will be tracked
objects.
Execute returns the exit value of the command or return value of the
Python function. scons prints an
error message if the executed action fails (exits with or returns a n
on-zero value), however it does
not, automatically terminate the build for such a failure. If you wan
t the build to stop in response
to a failed Execute call, you must explicitly check for a non-zero re
turn value:
if Execute("mkdir sub/dir/ectory"): if Execute("mkdir sub/dir/ectory"):
# The mkdir failed, don't try to build. # The mkdir failed, don't try to build.
Exit(1) Exit(1)
Exit([value]), env.Exit([value]) Exit([value]), env.Exit([value])
This tells scons to exit immediately with the specified value. A defa ult exit value of 0 (zero) is This tells scons to exit immediately with the specified value. A defa ult exit value of 0 (zero) is
used if no value is specified. used if no value is specified.
Export([vars...], [key=value...]), env.Export([vars...], [key=value...]) Export([vars...], [key=value...]), env.Export([vars...], [key=value...])
Exports variables from the current SConscript file to a global collec tion where they can be imported Exports variables from the current SConscript file to a global collec tion where they can be imported
skipping to change at line 4800 skipping to change at line 4782
Local(targets), env.Local(targets) Local(targets), env.Local(targets)
The specified targets will have copies made in the local tree, even i f an already up-to-date copy The specified targets will have copies made in the local tree, even i f an already up-to-date copy
exists in a repository. Returns a list of the target Node or Nodes. exists in a repository. Returns a list of the target Node or Nodes.
env.MergeFlags(arg, [unique]) env.MergeFlags(arg, [unique])
Merges values from arg into construction variables in the current con struction environment. If arg is Merges values from arg into construction variables in the current con struction environment. If arg is
not a dictionary, it is converted to one by calling env.ParseFlags on the argument before the values not a dictionary, it is converted to one by calling env.ParseFlags on the argument before the values
are merged. Note that arg must be a single value, so multiple strings must be passed in as a list, not are merged. Note that arg must be a single value, so multiple strings must be passed in as a list, not
as separate arguments to env.MergeFlags. as separate arguments to env.MergeFlags.
By default, duplicate values are eliminated; you can, however, specif If unique is true (the default), duplicate values are not stored. Whe
y unique=False to allow duplicate n eliminating duplicate values,
values to be added. When eliminating duplicate values, any constructi any construction variables that end with the string PATH keep the lef
on variables that end with the t-most unique value. All other
string PATH keep the left-most unique value. All other construction v construction variables keep the right-most unique value. If unique is
ariables keep the right-most false, values are added even if
unique value. they are duplicates.
Examples: Examples:
# Add an optimization flag to $CCFLAGS. # Add an optimization flag to $CCFLAGS.
env.MergeFlags('-O3') env.MergeFlags('-O3')
# Combine the flags returned from running pkg-config with an opti mization # Combine the flags returned from running pkg-config with an opti mization
# flag and merge the result into the construction variables. # flag and merge the result into the construction variables.
env.MergeFlags(['!pkg-config gtk+-2.0 --cflags', '-O3']) env.MergeFlags(['!pkg-config gtk+-2.0 --cflags', '-O3'])
# Combine an optimization flag with the flags returned from runni ng pkg-config # Combine an optimization flag with the flags returned from runni ng pkg-config
# twice and merge the result into the construction variables. # twice and merge the result into the construction variables.
env.MergeFlags(['-O3', env.MergeFlags(
'!pkg-config gtk+-2.0 --cflags --libs', [
'!pkg-config libpng12 --cflags --libs']) '-O3',
'!pkg-config gtk+-2.0 --cflags --libs',
'!pkg-config libpng12 --cflags --libs',
]
)
NoCache(target, ...), env.NoCache(target, ...) NoCache(target, ...), env.NoCache(target, ...)
Specifies a list of files which should not be cached whenever the Cac heDir method has been activated. Specifies a list of files which should not be cached whenever the Cac heDir method has been activated.
The specified targets may be a list or an individual target. The specified targets may be a list or an individual target.
Multiple files should be specified either as separate arguments to th e NoCache method, or as a list. Multiple files should be specified either as separate arguments to th e NoCache method, or as a list.
NoCache will also accept the return value of any of the construction environment Builder methods. NoCache will also accept the return value of any of the construction environment Builder methods.
Calling NoCache on directories and other non-File Node types has no e ffect because only File Nodes are Calling NoCache on directories and other non-File Node types has no e ffect because only File Nodes are
cached. cached.
skipping to change at line 4854 skipping to change at line 4840
Calling NoClean for a target overrides calling Clean for the same tar get, and any targets passed to Calling NoClean for a target overrides calling Clean for the same tar get, and any targets passed to
both functions will not be removed by the -c option. both functions will not be removed by the -c option.
Examples: Examples:
NoClean('foo.elf') NoClean('foo.elf')
NoClean(env.Program('hello', 'hello.c')) NoClean(env.Program('hello', 'hello.c'))
env.ParseConfig(command, [function, unique]) env.ParseConfig(command, [function, unique])
Updates the current construction environment with the values extracte Updates the current construction environment with the values extracte
d from the output from running d from the output of running
external command, by calling a helper function function which underst external command, by passing it to a helper function. command may be
ands the output of command. a string or a list of strings
command may be a string or a list of strings representing the command representing the command and its arguments. If function is omitted or
and its arguments. If function None, env.MergeFlags is used. By
is not given, env.MergeFlags is used. By default, duplicate values ar default, duplicate values are not added to any construction variables
e not added to any construction ; you can specify unique=False to
variables; you can specify unique=False to allow duplicate values to allow duplicate values to be added.
be added.
command is executed using the SCons execution environment (that is, t
If env.MergeFlags is used, it expects a response in the style of a *- he construction variable $ENV in
config command typical of the the current construction environment). If command needs additional in
POSIX programming environment (for example, gtk-config) and adds the formation to operate properly,
options to the appropriate that needs to be set in the execution environment. For example, pkg-c
construction variables. Interpreted options and the construction vari onfig may need a custom value set
ables they affect are as in the PKG_CONFIG_PATH environment variable.
specified for the env.ParseFlags method (which env.MergeFlags calls).
See that method's description env.MergeFlags needs to understand the output produced by command in
for a table of options and corresponding construction variables. order to distribute it to
appropriate construction variables. env.MergeFlags uses a separate f
If env.MergeFlags cannot interpret the results of command, you can su unction to do that processing -
ppply a custom function to do so. see env.ParseFlags for the details, including a a table of options an
function must accept three arguments: the construction environment to d corresponding construction
modify, the string returned by variables. To provide alternative processing of the output of command
running command, and the optional unique flag. , you can suppply a custom
function, which must accept three arguments: the construction environ
ment to modify, a string argument
containing the output from running command, and the optional unique f
lag.
ParseDepends(filename, [must_exist, only_one]), env.ParseDepends(filename , [must_exist, only_one]) ParseDepends(filename, [must_exist, only_one]), env.ParseDepends(filename , [must_exist, only_one])
Parses the contents of the specified filename as a list of dependenci Parses the contents of filename as a list of dependencies in the styl
es in the style of Make or mkdep, e of Make or mkdep, and
and explicitly establishes all of the listed dependencies. explicitly establishes all of the listed dependencies.
By default, it is not an error if the specified filename does not exi By default, it is not an error if filename does not exist. The option
st. The optional must_exist al must_exist argument may be set
argument may be set to a non-zero value to have scons throw an except to True to have SCons raise an exception if the file does not exist,
ion and generate an error if the or is otherwise inaccessible.
file does not exist, or is otherwise inaccessible.
The optional only_one 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 mor
e than one target. This can
provide a small sanity check for files intended to be generated by, f
or example, the gcc -M flag,
which should typically only write dependency information for one outp
ut file into a corresponding .d
file.
The filename and all of the files listed therein will be interpreted The optional only_one argument may be set to True to have SCons raise
relative to the directory of the an exception if the file
contains dependency information for more than one target. This can pr
ovide a small sanity check for
files intended to be generated by, for example, the gcc -M flag, whic
h should typically only write
dependency information for one output file into a corresponding .d fi
le.
filename and all of the files listed therein will be interpreted rela
tive to the directory of the
SConscript file which calls the ParseDepends function. SConscript file which calls the ParseDepends function.
env.ParseFlags(flags, ...) env.ParseFlags(flags, ...)
Parses one or more strings containing typical command-line flags for Parses one or more strings containing typical command-line flags for
GCC tool chains and returns a GCC-style tool chains and returns
dictionary with the flag values separated into the appropriate SCons a dictionary with the flag values separated into the appropriate SCon
construction variables. This is s construction variables.
intended as a companion to the env.MergeFlags method, but allows for Intended as a companion to the env.MergeFlags method, but allows for
the values in the returned the values in the returned
dictionary to be modified, if necessary, before merging them into the construction environment. (Note dictionary to be modified, if necessary, before merging them into the construction environment. (Note
that env.MergeFlags will call this method if its argument is not a di ctionary, so it is usually not that env.MergeFlags will call this method if its argument is not a di ctionary, so it is usually not
necessary to call env.ParseFlags directly unless you want to manipula te the values.) necessary to call env.ParseFlags directly unless you want to manipula te the values.)
If the first character in any string is an exclamation mark (!), the rest of the string is executed as If the first character in any string is an exclamation mark (!), the rest of the string is executed as
a command, and the output from the command is parsed as GCC tool chai n command-line flags and added to a command, and the output from the command is parsed as GCC tool chai n command-line flags and added to
the resulting dictionary. the resulting dictionary. This can be used to call a *-config command
typical of the POSIX programming
environment (for example, pkg-config). Note that such a comamnd is ex
ecuted using the SCons execution
environment; if the command needs additional information, that inform
ation needs to be explcitly
provided. See ParseConfig for more details.
Flag values are translated accordig to the prefix found, and added to the following construction Flag values are translated accordig to the prefix found, and added to the following construction
variables: variables:
-arch CCFLAGS, LINKFLAGS -arch CCFLAGS, LINKFLAGS
-D CPPDEFINES -D CPPDEFINES
-framework FRAMEWORKS -framework FRAMEWORKS
-frameworkdir= FRAMEWORKPATH -frameworkdir= FRAMEWORKPATH
-fmerge-all-constants CCFLAGS, LINKFLAGS -fmerge-all-constants CCFLAGS, LINKFLAGS
-fopenmp CCFLAGS, LINKFLAGS -fopenmp CCFLAGS, LINKFLAGS
skipping to change at line 4972 skipping to change at line 4961
Prepend values to construction variables in the current construction environment, Works like Prepend values to construction variables in the current construction environment, Works like
env.Append (see for details), except that values are added to the fro nt, rather than the end, of any env.Append (see for details), except that values are added to the fro nt, rather than the end, of any
existing value of the construction variable existing value of the construction variable
Example: Example:
env.Prepend(CCFLAGS='-g ', FOO=['foo.yyy']) env.Prepend(CCFLAGS='-g ', FOO=['foo.yyy'])
See also env.Append, env.AppendUnique and env.PrependUnique. See also env.Append, env.AppendUnique and env.PrependUnique.
env.PrependENVPath(name, newpath, [envname, sep, delete_existing]) env.PrependENVPath(name, newpath, [envname, sep, delete_existing=True])
Prepend new path elements to the given path in the specified external Prepend path elements specified by newpath to the given search path s
environment ($ENV by default). tring or list name in mapping
This will only add any particular path once (leaving the first one it envname in the construction environment. Supplying envname is optiona
encounters and ignoring the l: the default is the execution
rest, to preserve path order), and to help assure this, will normaliz environment $ENV. Optional sep is used as the search path separator,
e all paths (using the default is the platform's
os.path.normpath and os.path.normcase). This can also handle the case separator (os.pathsep). A path element will only appear once. Any dup
where the given old path licates in newpath are dropped,
variable is a list instead of a string, in which case a list will be keeping the first appearing (to preserve path order). If delete_exist
returned instead of a string. ing is False any addition
duplicating an existing path element is ignored; if delete_existing i
If delete_existing is False, then adding a path that already exists w s True (the default) the existing
ill not move it to the beginning; value will be dropped and the path element will be inserted at the be
it will stay where it is in the list. ginning. To help maintain
uniqueness all paths are normalized (using os.path.normpath and os.pa
th.normcase).
Example: Example:
print('before:', env['ENV']['INCLUDE']) print('before:', env['ENV']['INCLUDE'])
include_path = '/foo/bar:/foo' include_path = '/foo/bar:/foo'
env.PrependENVPath('INCLUDE', include_path) env.PrependENVPath('INCLUDE', include_path)
print('after:', env['ENV']['INCLUDE']) print('after:', env['ENV']['INCLUDE'])
Yields: Yields:
before: /biz:/foo before: /biz:/foo
after: /foo/bar:/foo:/biz after: /foo/bar:/foo:/biz
See also env.AppendENVPath.
env.PrependUnique(key=val, delete_existing=False, [...]) env.PrependUnique(key=val, delete_existing=False, [...])
Prepend values to construction variables in the current construction environment, maintaining Prepend values to construction variables in the current construction environment, maintaining
uniqueness. Works like env.Append (see for details), except that valu es are added to the front, rather uniqueness. Works like env.Append (see for details), except that valu es are added to the front, rather
than the end, of any existing value of the the construction variable, than the end, of any existing value of the construction variable, and
and values already present in values already present in the
the construction variable will not be added again. If delete_existing construction variable will not be added again. If delete_existing is
is True, the existing matching True, the existing matching value
value is first removed, and the requested value is inserted, having t is first removed, and the requested value is inserted, having the eff
he effect of moving such values ect of moving such values to the
to the front. front.
Example: Example:
env.PrependUnique(CCFLAGS='-g', FOO=['foo.yyy']) env.PrependUnique(CCFLAGS='-g', FOO=['foo.yyy'])
See also env.Append, env.AppendUnique and env.Prepend. See also env.Append, env.AppendUnique and env.Prepend.
Progress(callable, [interval]), Progress(string, [interval, file, overwri te]), Progress(list_of_strings, Progress(callable, [interval]), Progress(string, [interval, file, overwri te]), Progress(list_of_strings,
[interval, file, overwrite]) [interval, file, overwrite])
Allows SCons to show progress made during the build by displaying a s tring or calling a function while Allows SCons to show progress made during the build by displaying a s tring or calling a function while
skipping to change at line 5144 skipping to change at line 5135
# Returns the values of Python variables 'val1' and 'val2'. # Returns the values of Python variables 'val1' and 'val2'.
Return('val1 val2') Return('val1 val2')
Scanner(function, [name, argument, skeys, path_function, node_class, node _factory, scan_check, Scanner(function, [name, argument, skeys, path_function, node_class, node _factory, scan_check,
recursive]), env.Scanner(function, [name, argument, skeys, path_function, node_class, node_factory, recursive]), env.Scanner(function, [name, argument, skeys, path_function, node_class, node_factory,
scan_check, recursive]) scan_check, recursive])
Creates a Scanner object for the specified function. See manpage sect ion "Scanner Objects" for a Creates a Scanner object for the specified function. See manpage sect ion "Scanner Objects" for a
complete explanation of the arguments and behavior. complete explanation of the arguments and behavior.
SConscript(scripts, [exports, variant_dir, duplicate, must_exist]), env.S Conscript(scripts, [exports, SConscript(scripts, [exports, variant_dir, duplicate, must_exist]), env.S Conscript(scripts, [exports,
variant_dir, duplicate, must_exist]), SConscript(dirs=subdirs, [name=scri variant_dir, duplicate, must_exist]), SConscript(dirs=subdirs, [name=scri
pt, exports, variant_dir, ptname, exports, variant_dir,
duplicate, must_exist]), env.SConscript(dirs=subdirs, [name=script, expor duplicate, must_exist]), env.SConscript(dirs=subdirs, [name=scriptname, e
ts, variant_dir, duplicate, xports, variant_dir, duplicate,
must_exist]) must_exist])
Execute one or more subsidiary SConscript (configuration) files. Ther e are two ways to call the Executes one or more subsidiary SConscript (configuration) files. The re are two ways to call the
SConscript function. SConscript function.
The first calling style is to explicitly specify one or more scripts The first calling style is to supply one or more SConscript file name
as the first argument. A single s as the first (positional)
script may be specified as a string; multiple scripts must be specifi argument. A single script may be specified as a string; multiple scri
ed as a list (either explicitly pts must be specified as a list
or as created by a function like Split). Examples: of strings (either explicitly or as created by a function like Split)
. Examples:
SConscript('SConscript') # run SConscript in the current dir ectory SConscript('SConscript') # run SConscript in the current directo ry
SConscript('src/SConscript') # run SConscript in the src directo ry SConscript('src/SConscript') # run SConscript in the src directo ry
SConscript(['src/SConscript', 'doc/SConscript']) SConscript(['src/SConscript', 'doc/SConscript'])
config = SConscript('MyConfig.py') config = SConscript('MyConfig.py')
The second way to call SConscript is to specify a list of (sub)direct The other calling style is to omit the positional argument naming scr
ory names as a dirs=subdirs ipts and instead specify a list
keyword argument. In this case, scons will execute a subsidiary confi of directory names using the dirs keyword argument. In this case, sco
guration file named SConscript in ns will execute a subsidiary
each of the specified directories. You may specify a name other than configuration file named SConscript in each of the specified director
SConscript by supplying an ies. You may specify a name other
optional name=script keyword argument. The first three examples below than SConscript by supplying an optional name=scriptname keyword argu
have the same effect as the ment. The first three examples
first three examples above: below have the same effect as the first three examples above:
SConscript(dirs='.') # run SConscript in the current directo SConscript(dirs='.') # run SConscript in the current directory
ry SConscript(dirs='src') # run SConscript in the src directory
SConscript(dirs='src') # run SConscript in the src directory
SConscript(dirs=['src', 'doc']) SConscript(dirs=['src', 'doc'])
SConscript(dirs=['sub1', 'sub2'], name='MySConscript') SConscript(dirs=['sub1', 'sub2'], name='MySConscript')
The optional exports argument provides a string or list of strings re The optional exports keyword argument provides a string or list of st
presenting variable names, or a rings representing variable
dictionary of named values, to export. These variables are locally ex names, or a dictionary of named values, to export. For the first call
ported only to the called ing style only, a second
SConscript file(s) and do not affect the global pool of variables man positional argument will be interpreted as exports; the second callin
aged by the Export function. The g style must use the keyword
subsidiary SConscript files must use the Import function to import th argument form for exports. These variables are locally exported only
e variables. Examples: to the called SConscript file(s)
and do not affect the global pool of variables managed by the Export
function. The subsidiary
SConscript files must use the Import function to import the variables
. Examples:
foo = SConscript('sub/SConscript', exports='env') foo = SConscript('sub/SConscript', exports='env')
SConscript('dir/SConscript', exports=['env', 'variable']) SConscript('dir/SConscript', exports=['env', 'variable'])
SConscript(dirs='subdir', exports='env variable') SConscript(dirs='subdir', exports='env variable')
SConscript(dirs=['one', 'two', 'three'], exports='shared_info') SConscript(dirs=['one', 'two', 'three'], exports='shared_info')
If the optional variant_dir argument is present, it causes an effect equivalent to the VariantDir If the optional variant_dir argument is present, it causes an effect equivalent to the VariantDir
function. The variant_dir argument is interpreted relative to the dir function, but in effect only within the scope of the SConscript call.
ectory of the calling SConscript The variant_dir argument is
file. The optional duplicate argument is interpreted as for VariantDi interpreted relative to the directory of the calling SConscript file.
r. If variant_dir is omitted, the The source directory is the
duplicate argument is ignored. See the description of VariantDir belo directory in which the called SConscript file resides and the SConscr
w for additional details and ipt file is evaluated as if it
restrictions. were in the variant_dir directory. Thus:
If variant_dir is present, the source directory is the directory in w
hich the SConscript file resides
and the SConscript file is evaluated as if it were in the variant_dir
directory:
SConscript('src/SConscript', variant_dir='build') SConscript('src/SConscript', variant_dir='build')
is equivalent to is equivalent to:
VariantDir('build', 'src') VariantDir('build', 'src')
SConscript('build/SConscript') SConscript('build/SConscript')
This later paradigm is often used when the sources are in the same di rectory as the SConstruct: If the sources are in the same directory as the SConstruct,
SConscript('SConscript', variant_dir='build') SConscript('SConscript', variant_dir='build')
is equivalent to is equivalent to:
VariantDir('build', '.') VariantDir('build', '.')
SConscript('build/SConscript') SConscript('build/SConscript')
The optional duplicate argument is interpreted as for VariantDir. If
the variant_dir argument is
omitted, the duplicate argument is ignored. See the description of Va
riantDir for additional details
and restrictions.
If the optional must_exist is True, causes an exception to be raised if a requested SConscript file is If the optional must_exist is True, causes an exception to be raised if a requested SConscript file is
not found. The current default is False, causing only a warning to be emitted, but this default is not found. The current default is False, causing only a warning to be emitted, but this default is
deprecated (since 3.1). For scripts which truly intend to be optional , transition to explicitly deprecated (since 3.1). For scripts which truly intend to be optional , transition to explicitly
supplying must_exist=False to the SConscript call. supplying must_exist=False to the SConscript call.
Here are some composite examples: Here are some composite examples:
# collect the configuration information and use it to build src a nd doc # collect the configuration information and use it to build src a nd doc
shared_info = SConscript('MyConfig.py') shared_info = SConscript('MyConfig.py')
SConscript('src/SConscript', exports='shared_info') SConscript('src/SConscript', exports='shared_info')
skipping to change at line 5234 skipping to change at line 5228
opts = { 'CPPDEFINES' : ['DEBUG'], 'CCFLAGS' : '-pgdb' } opts = { 'CPPDEFINES' : ['DEBUG'], 'CCFLAGS' : '-pgdb' }
SConscript('SConscript', variant_dir='debug', duplicate=0, export s=opts) SConscript('SConscript', variant_dir='debug', duplicate=0, export s=opts)
opts = { 'CPPDEFINES' : ['NODEBUG'], 'CCFLAGS' : '-O' } opts = { 'CPPDEFINES' : ['NODEBUG'], 'CCFLAGS' : '-O' }
SConscript('SConscript', variant_dir='prod', duplicate=0, exports =opts) SConscript('SConscript', variant_dir='prod', duplicate=0, exports =opts)
# build common documentation and compile for different architectu res # build common documentation and compile for different architectu res
SConscript('doc/SConscript', variant_dir='build/doc', duplicate=0 ) SConscript('doc/SConscript', variant_dir='build/doc', duplicate=0 )
SConscript('src/SConscript', variant_dir='build/x86', duplicate=0 ) SConscript('src/SConscript', variant_dir='build/x86', duplicate=0 )
SConscript('src/SConscript', variant_dir='build/ppc', duplicate=0 ) SConscript('src/SConscript', variant_dir='build/ppc', duplicate=0 )
SConscript returns the values of any variables named by the executed SConscript returns the values of any variables named by the executed
SConscript(s) in arguments to the SConscript file(s) in arguments
Return function (see above for details). If a single SConscript call to the Return function. If a single SConscript call causes multiple s
causes multiple scripts to be cripts to be executed, the return
executed, the return value is a tuple containing the returns of all o value is a tuple containing the returns of each of the scripts. If an
f the scripts. If an executed executed script does not
script does not explicitly call Return, it returns None. explicitly call Return, it returns None.
SConscriptChdir(value), env.SConscriptChdir(value) SConscriptChdir(value), env.SConscriptChdir(value)
By default, scons changes its working directory to the directory in w hich each subsidiary SConscript By default, scons changes its working directory to the directory in w hich each subsidiary SConscript
file lives. This behavior may be disabled by specifying either: file lives. This behavior may be disabled by specifying either:
SConscriptChdir(0) SConscriptChdir(0)
env.SConscriptChdir(0) env.SConscriptChdir(0)
in which case scons will stay in the top-level directory while readin g all SConscript files. (This may in which case scons will stay in the top-level directory while readin g all SConscript files. (This may
be necessary when building from repositories, when all the directorie s in which SConscript files may be necessary when building from repositories, when all the directorie s in which SConscript files may
be found don't necessarily exist locally.) You may enable and disable this ability by calling be found don't necessarily exist locally.) You may enable and disable this ability by calling
SConscriptChdir() multiple times. SConscriptChdir multiple times.
Example: Example:
env = Environment() env = Environment()
SConscriptChdir(0) SConscriptChdir(0)
SConscript('foo/SConscript') # will not chdir to foo SConscript('foo/SConscript') # will not chdir to foo
env.SConscriptChdir(1) env.SConscriptChdir(1)
SConscript('bar/SConscript') # will chdir to bar SConscript('bar/SConscript') # will chdir to bar
SConsignFile([name, dbm_module]), env.SConsignFile([name, dbm_module]) SConsignFile([name, dbm_module]), env.SConsignFile([name, dbm_module])
skipping to change at line 5372 skipping to change at line 5366
├────────────────────────┼───────────────────────────┼─────────────── ───────────────┤ ├────────────────────────┼───────────────────────────┼─────────────── ───────────────┤
│md5_chunksize │ --md5-chunksize │ │ │md5_chunksize │ --md5-chunksize │ │
├────────────────────────┼───────────────────────────┼─────────────── ───────────────┤ ├────────────────────────┼───────────────────────────┼─────────────── ───────────────┤
│no_exec │ -n, │ │ │no_exec │ -n, │ │
│ │ --no-exec, │ │ │ │ --no-exec, │ │
│ │ --just-print, │ │ │ │ --just-print, │ │
│ │ --dry-run, │ │ │ │ --dry-run, │ │
│ │ --recon │ │ │ │ --recon │ │
├────────────────────────┼───────────────────────────┼─────────────── ───────────────┤ ├────────────────────────┼───────────────────────────┼─────────────── ───────────────┤
│no_progress │ -Q │ See │ │no_progress │ -Q │ See │
│ │ │ [5] │ │ │ │ [4] │
├────────────────────────┼───────────────────────────┼─────────────── ───────────────┤ ├────────────────────────┼───────────────────────────┼─────────────── ───────────────┤
│num_jobs │ -j, --jobs │ │ │num_jobs │ -j, --jobs │ │
├────────────────────────┼───────────────────────────┼─────────────── ───────────────┤ ├────────────────────────┼───────────────────────────┼─────────────── ───────────────┤
│random │ --random │ │ │random │ --random │ │
├────────────────────────┼───────────────────────────┼─────────────── ───────────────┤ ├────────────────────────┼───────────────────────────┼─────────────── ───────────────┤
│silent │ -s, │ │ │silent │ -s, │ │
│ │ --silent, │ │ │ │ --silent, │ │
│ │ --quiet │ │ │ │ --quiet │ │
├────────────────────────┼───────────────────────────┼─────────────── ───────────────┤ ├────────────────────────┼───────────────────────────┼─────────────── ───────────────┤
│stack_size │ --stack-size │ │ │stack_size │ --stack-size │ │
skipping to change at line 5434 skipping to change at line 5428
files = Split("f1.c f2.c f3.c") files = Split("f1.c f2.c f3.c")
files = env.Split("f4.c f5.c f6.c") files = env.Split("f4.c f5.c f6.c")
files = Split(""" files = Split("""
f7.c f7.c
f8.c f8.c
f9.c f9.c
""") """)
env.subst(input, [raw, target, source, conv]) env.subst(input, [raw, target, source, conv])
Performs construction variable interpolation on input, which can be a Performs construction variable interpolation (substitution) on input,
string or a sequence. which can be a string or a
sequence. Substitutable elements take the form ${expression}, althoug
h if there is no ambiguity in
recognizing the element, the braces can be omitted. A literal $ can b
e entered by using $$.
By default, leading or trailing white space will be removed from the result, and all sequences of By default, leading or trailing white space will be removed from the result, and all sequences of
white space will be compressed to a single space character. Additiona lly, any $( and $) character white space will be compressed to a single space character. Additiona lly, any $( and $) character
sequences will be stripped from the returned string, The optional raw argument may be set to 1 if you sequences will be stripped from the returned string, The optional raw argument may be set to 1 if you
want to preserve white space and $(-$) sequences. The raw argument ma y be set to 2 if you want to want to preserve white space and $(-$) sequences. The raw argument ma y be set to 2 if you want to
additionally discard all characters between any $( and $) pairs (as i s done for signature additionally discard all characters between any $( and $) pairs (as i s done for signature
calculation). calculation).
If the input is a sequence (list or tuple), the individual elements o If input is a sequence (list or tuple), the individual elements of th
f the sequence will be expanded, e sequence will be expanded, and
and the results will be returned as a list. the results will be returned as a list.
The optional target and source keyword arguments must be set to lists of target and source nodes, The optional target and source keyword arguments must be set to lists of target and source nodes,
respectively, if you want the $TARGET, $TARGETS, $SOURCE and $SOURCES to be available for expansion. respectively, if you want the $TARGET, $TARGETS, $SOURCE and $SOURCES to be available for expansion.
This is usually necessary if you are calling env.subst from within a Python function used as an SCons This is usually necessary if you are calling env.subst from within a Python function used as an SCons
action. action.
Returned string values or sequence elements are converted to their st ring representation by default. Returned string values or sequence elements are converted to their st ring representation by default.
The optional conv argument may specify a conversion function that wil l be used in place of the The optional conv argument may specify a conversion function that wil l be used in place of the
default. For example, if you want Python objects (including SCons Nod es) to be returned as Python default. For example, if you want Python objects (including SCons Nod es) to be returned as Python
objects, you can use a Python lambda expression to pass in an unnamed function that simply returns its objects, you can use a Python lambda expression to pass in an unnamed function that simply returns its
skipping to change at line 5554 skipping to change at line 5550
# line, and use /usr/local as the default. # line, and use /usr/local as the default.
prefix = ARGUMENTS.get('prefix', '/usr/local') prefix = ARGUMENTS.get('prefix', '/usr/local')
# Attach a .Config() builder for the above function action # Attach a .Config() builder for the above function action
# to the construction environment. # to the construction environment.
env['BUILDERS']['Config'] = Builder(action = create) env['BUILDERS']['Config'] = Builder(action = create)
env.Config(target = 'package-config', source = Value(prefix)) env.Config(target = 'package-config', source = Value(prefix))
def build_value(target, source, env): def build_value(target, source, env):
# A function that "builds" a Python Value by updating # A function that "builds" a Python Value by updating
# the the Python value with the contents of the file # the Python value with the contents of the file
# specified as the source of the Builder call ($SOURCE). # specified as the source of the Builder call ($SOURCE).
target[0].write(source[0].get_contents()) target[0].write(source[0].get_contents())
output = env.Value('before') output = env.Value('before')
input = env.Value('after') input = env.Value('after')
# Attach a .UpdateValue() builder for the above function # Attach a .UpdateValue() builder for the above function
# action to the construction environment. # action to the construction environment.
env['BUILDERS']['UpdateValue'] = Builder(action = build_value) env['BUILDERS']['UpdateValue'] = Builder(action = build_value)
env.UpdateValue(target = Value(output), source = Value(input)) env.UpdateValue(target = Value(output), source = Value(input))
VariantDir(variant_dir, src_dir, [duplicate]), env.VariantDir(variant_dir , src_dir, [duplicate]) VariantDir(variant_dir, src_dir, [duplicate]), env.VariantDir(variant_dir , src_dir, [duplicate])
Sets up an alternate build location. When building in the variant_dir Sets up a mapping to define a variant build directory in variant_dir.
, SCons backfills as needed with src_dir may not be underneath
files from src_dir to create a complete build directory. VariantDir variant_dir. A VariantDir mapping is global, even if called using the
can be called multiple times with env.VariantDir form. VariantDir
the same src_dir to set up multiple builds with different options (va can be called multiple times with the same src_dir to set up multiple
riants). variant builds with different
options.
The variant location must be in or underneath the project top directo
ry, and src_dir may not be Note if variant_dir is not under the project top directory, target se
underneath variant_dir. lection rules will not pick
targets in the variant directory unless they are explicitly specified
By default, SCons physically duplicates the source files and SConscri .
pt files as needed into the
variant tree. Thus, a build performed in the variant tree is guarante When files in variant_dir are referenced, SCons backfills as needed w
ed to be identical to a build ith files from src_dir to create
performed in the source tree even if intermediate source files are ge a complete build directory. By default, SCons physically duplicates t
nerated during the build, or if he source files, SConscript
preprocessors or other scanners search for included files relative to files, and directory structure as needed into the variant directory.
the source file, or if Thus, a build performed in the
individual compilers or other invoked tools are hard-coded to put der variant directory is guaranteed to be identical to a build performed
ived files in the same directory in the source directory even if
as source files. Only the files SCons calculates are needed for the b intermediate source files are generated during the build, or if prepr
uild are duplicated into ocessors or other scanners search
variant_dir. for included files using paths relative to the source file, or if ind
ividual compilers or other
If possible on the platform, the duplication is performed by linking invoked tools are hard-coded to put derived files in the same directo
rather than copying. This ry as source files. Only the
behavior is affected by the --duplicate command-line option. files SCons calculates are needed for the build are duplicated into v
ariant_dir. If possible on the
platform, the duplication is performed by linking rather than copying
. This behavior is affected by
the --duplicate command-line option.
Duplicating the source files may be disabled by setting the duplicate argument to False. This will Duplicating the source files may be disabled by setting the duplicate argument to False. This will
cause SCons to invoke Builders using the path names of source files i n src_dir and the path names of cause SCons to invoke Builders using the path names of source files i n src_dir and the path names of
derived files within variant_dir. This is more efficient than duplica derived files within variant_dir. This is more efficient than duplica
te=True, and is safe for most ting, and is safe for most
builds; revert to True if it causes problems. builds; revert to duplicate=True if it causes problems.
VariantDir works most naturally with used with a subsidiary SConscrip VariantDir works most naturally when used with a subsidiary SConscrip
t file. The subsidiary SConscript t file. The subsidiary SConscript
file is called as if it were in variant_dir, regardless of the value file must be called as if it were in variant_dir, regardless of the v
of duplicate. This is how you alue of duplicate. When calling
tell scons which variant of a source tree to build: an SConscript file, you can use the exports keyword argument to pass
parameters (individually or as an
appropriately set up environment) so the SConscript can pick up the r
ight settings for that variant
build. The SConscript must Import these to use them. Example:
env1 = Environment(...settings for variant1...)
env2 = Environment(...settings for variant2...)
# run src/SConscript in two variant directories # run src/SConscript in two variant directories
VariantDir('build/variant1', 'src') VariantDir('build/variant1', 'src')
SConscript('build/variant1/SConscript') SConscript('build/variant1/SConscript', exports={"env": env1})
VariantDir('build/variant2', 'src') VariantDir('build/variant2', 'src')
SConscript('build/variant2/SConscript') SConscript('build/variant2/SConscript', exports={"env": env2})
See also the SConscript function, described above, for another way to See also the SConscript function for another way to specify a variant
specify a variant directory in directory in conjunction with
conjunction with calling a subsidiary SConscript file. calling a subsidiary SConscript file.
Examples: More examples:
# use names in the build directory, not the source directory # use names in the build directory, not the source directory
VariantDir('build', 'src', duplicate=0) VariantDir('build', 'src', duplicate=0)
Program('build/prog', 'build/source.c') Program('build/prog', 'build/source.c')
# this builds both the source and docs in a separate subtree # this builds both the source and docs in a separate subtree
VariantDir('build', '.', duplicate=0) VariantDir('build', '.', duplicate=0)
SConscript(dirs=['build/src','build/doc']) SConscript(dirs=['build/src','build/doc'])
# same as previous example, but only uses SConscript # same as previous example, but only uses SConscript
skipping to change at line 5775 skipping to change at line 5777
not being useful (wrong platform, necessary external command or files not installed, etc.) will not be set not being useful (wrong platform, necessary external command or files not installed, etc.) will not be set
up. Correct build setups should be resilient to the possible absence of c ertain construction variables up. Correct build setups should be resilient to the possible absence of c ertain construction variables
before using them, for example by using a Python dictionary get method to retrieve the value and taking before using them, for example by using a Python dictionary get method to retrieve the value and taking
alternative action if the return indicates the variable is unset. The env .Dump method can be called to alternative action if the return indicates the variable is unset. The env .Dump method can be called to
examine the construction variables set in a particular environment. examine the construction variables set in a particular environment.
__LDMODULEVERSIONFLAGS __LDMODULEVERSIONFLAGS
This construction variable automatically introduces $_LDMODULEVERSION FLAGS if $LDMODULEVERSION is set. This construction variable automatically introduces $_LDMODULEVERSION FLAGS if $LDMODULEVERSION is set.
Othervise it evaluates to an empty string. Othervise it evaluates to an empty string.
__NINJA_NO
Internal flag. Used to tell SCons whether or not to try to import pyp
i's ninja python package. This is
set to True when being called by Ninja?
__SHLIBVERSIONFLAGS __SHLIBVERSIONFLAGS
This construction variable automatically introduces $_SHLIBVERSIONFLA GS if $SHLIBVERSION is set. This construction variable automatically introduces $_SHLIBVERSIONFLA GS if $SHLIBVERSION is set.
Othervise it evaluates to an empty string. Othervise it evaluates to an empty string.
APPLELINK_COMPATIBILITY_VERSION APPLELINK_COMPATIBILITY_VERSION
On Mac OS X this is used to set the linker flag: -compatibility_versi on On Mac OS X this is used to set the linker flag: -compatibility_versi on
The value is specified as X[.Y[.Z]] where X is between 1 and 65535, Y can be omitted or between 1 and The value is specified as X[.Y[.Z]] where X is between 1 and 65535, Y can be omitted or between 1 and
255, Z can be omitted or between 1 and 255. This value will be derive d from $SHLIBVERSION if not 255, Z can be omitted or between 1 and 255. This value will be derive d from $SHLIBVERSION if not
specified. The lowest digit will be dropped and replaced by a 0. specified. The lowest digit will be dropped and replaced by a 0.
skipping to change at line 5942 skipping to change at line 5940
The command line used to compile a C source file to a (static) object file. Any options specified in The command line used to compile a C source file to a (static) object file. Any options specified in
the $CFLAGS, $CCFLAGS and $CPPFLAGS construction variables are includ ed on this command line. See also the $CFLAGS, $CCFLAGS and $CPPFLAGS construction variables are includ ed on this command line. See also
$SHCCCOM for compiling to shared objects. $SHCCCOM for compiling to shared objects.
CCCOMSTR CCCOMSTR
If set, the string displayed when a C source file is compiled to a (s tatic) object file. If not set, If set, the string displayed when a C source file is compiled to a (s tatic) object file. If not set,
then $CCCOM (the command line) is displayed. See also $SHCCCOMSTR for compiling to shared objects. then $CCCOM (the command line) is displayed. See also $SHCCCOMSTR for compiling to shared objects.
env = Environment(CCCOMSTR = "Compiling static object $TARGET") env = Environment(CCCOMSTR = "Compiling static object $TARGET")
CCDEPFLAGS
Options to pass to C or C++ compiler to generate list of dependency f
iles.
This is set only by compilers which support this functionality. (gcc,
clang, and msvc currently)
CCFLAGS CCFLAGS
General options that are passed to the C and C++ compilers. See also $SHCCFLAGS for compiling to General options that are passed to the C and C++ compilers. See also $SHCCFLAGS for compiling to
shared objects. shared objects.
CCPCHFLAGS CCPCHFLAGS
Options added to the compiler command line to support building with p recompiled headers. The default Options added to the compiler command line to support building with p recompiled headers. The default
value expands expands to the appropriate Microsoft Visual C++ command -line options when the $PCH value expands expands to the appropriate Microsoft Visual C++ command -line options when the $PCH
construction variable is set. construction variable is set.
CCPDBFLAGS CCPDBFLAGS
skipping to change at line 6384 skipping to change at line 6387
DVIPDFFLAGS DVIPDFFLAGS
General options passed to the TeX DVI file to PDF file converter. General options passed to the TeX DVI file to PDF file converter.
DVIPS DVIPS
The TeX DVI file to PostScript converter. The TeX DVI file to PostScript converter.
DVIPSFLAGS DVIPSFLAGS
General options passed to the TeX DVI file to PostScript converter. General options passed to the TeX DVI file to PostScript converter.
ENV ENV
A dictionary of environment variables to use when invoking commands. The execution environment - a dictionary of environment variables use
When $ENV is used in a command d when SCons invokes external
all list values will be joined using the path separator and any other commands to build targets defined in this construction environment. W
non-string values will simply be hen $ENV is passed to a command,
coerced to a string. Note that, by default, scons does not propagate all list values are assumed to be path lists and are joined using the
the environment in effect when search path separator. Any other
you execute scons to the commands used to build target files. This is non-string values are coerced to a string.
so that builds will be
guaranteed repeatable regardless of the environment variables set at Note that by default SCons does not propagate the environment in effe
the time scons is invoked. ct when you execute scons (the
"shell environment") to the execution environment. This is so that bu
If you want to propagate your environment variables to the commands e ilds will be guaranteed
xecuted to build target files, repeatable regardless of the environment variables set at the time sc
you must do so explicitly: ons is invoked. If you want to
propagate a shell environment variable to the commands executed to bu
ild target files, you must do so
explicitly. A common example is the system PATH environment variable,
so that scons will find
utilities the same way as the invoking shell (or other process):
import os import os
env = Environment(ENV=os.environ.copy()) env = Environment(ENV={'PATH': os.environ['PATH']})
Note that you can choose only to propagate certain environment variab Although it is usually not recommended, you can propagate the entire
les. A common example is the shell environment in one go:
system PATH environment variable, so that scons uses the same utiliti
es as the invoking shell (or
other process):
import os import os
env = Environment(ENV={'PATH': os.environ['PATH']}) env = Environment(ENV=os.environ.copy())
ESCAPE ESCAPE
A function that will be called to escape shell special characters in command lines. The function A function that will be called to escape shell special characters in command lines. The function
should take one argument: the command line string to escape; and shou ld return the escaped command should take one argument: the command line string to escape; and shou ld return the escaped command
line. line.
F03 F03
The Fortran 03 compiler. You should normally set the $FORTRAN variabl e, which specifies the default The Fortran 03 compiler. You should normally set the $FORTRAN variabl e, which specifies the default
Fortran compiler for all Fortran versions. You only need to set $F03 if you need to use a specific Fortran compiler for all Fortran versions. You only need to set $F03 if you need to use a specific
compiler or compiler version for Fortran 03 files. compiler or compiler version for Fortran 03 files.
skipping to change at line 6766 skipping to change at line 6770
used. By default, this is empty. used. By default, this is empty.
File File
A function that converts a string into a File instance relative to th e target being built. A function that converts a string into a File instance relative to th e target being built.
FORTRAN FORTRAN
The default Fortran compiler for all versions of Fortran. The default Fortran compiler for all versions of Fortran.
FORTRANCOM FORTRANCOM
The command line used to compile a Fortran source file to an object f ile. By default, any options The command line used to compile a Fortran source file to an object f ile. By default, any options
specified in the $FORTRANFLAGS, $CPPFLAGS, $_CPPDEFFLAGS, $_FORTRANMO specified in the $FORTRANFLAGS, $_FORTRANMODFLAG, and $_FORTRANINCFLA
DFLAG, and $_FORTRANINCFLAGS GS construction variables are
construction variables are included on this command line. included on this command line.
FORTRANCOMMONFLAGS
General user-specified options that are passed to the Fortran compile
r. Similar to $FORTRANFLAGS, but
this variable is applied to all dialects.
FORTRANCOMSTR FORTRANCOMSTR
If set, the string displayed when a Fortran source file is compiled t o an object file. If not set, If set, the string displayed when a Fortran source file is compiled t o an object file. If not set,
then $FORTRANCOM (the command line) is displayed. then $FORTRANCOM (the command line) is displayed.
FORTRANFILESUFFIXES FORTRANFILESUFFIXES
The list of file extensions for which the FORTRAN dialect will be use d. By default, this is ['.f', The list of file extensions for which the FORTRAN dialect will be use d. By default, this is ['.f',
'.for', '.ftn'] '.for', '.ftn']
FORTRANFLAGS FORTRANFLAGS
General user-specified options that are passed to the Fortran compile General user-specified options for the FORTRAN dialect that are passe
r. Note that this variable does d to the Fortran compiler. Note
not contain -I (or similar) include or module search path options tha that this variable does not contain -I (or similar) include or module
t scons generates automatically search path options that scons
from $FORTRANPATH. See $_FORTRANINCFLAGS and $_FORTRANMODFLAG, below, generates automatically from $FORTRANPATH. See $_FORTRANINCFLAGS and
for the variables that expand $_FORTRANMODFLAG, below, for the
those options. variables that expand those options.
_FORTRANINCFLAGS _FORTRANINCFLAGS
An automatically-generated construction variable containing the Fortr an compiler command-line options An automatically-generated construction variable containing the Fortr an compiler command-line options
for specifying directories to be searched for include files and modul e files. The value of for specifying directories to be searched for include files and modul e files. The value of
$_FORTRANINCFLAGS is created by respectively prepending and appending $INCPREFIX and $INCSUFFIX to the $_FORTRANINCFLAGS is created by respectively prepending and appending $INCPREFIX and $INCSUFFIX to the
beginning and end of each directory in $FORTRANPATH. beginning and end of each directory in $FORTRANPATH.
FORTRANMODDIR FORTRANMODDIR
Directory location where the Fortran compiler should place any module files it generates. This 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 variable is empty, by default. Some Fortran compilers will internally append this directory in the
skipping to change at line 7097 skipping to change at line 7105
JAVACLASSDIR JAVACLASSDIR
The directory in which Java class files may be found. This is strippe d from the beginning of any Java The directory in which Java class files may be found. This is strippe d from the beginning of any Java
.class file names supplied to the JavaH builder. .class file names supplied to the JavaH builder.
JAVACLASSPATH JAVACLASSPATH
Specifies the list of directories that will be searched for Java .cla ss file. The directories in this Specifies the list of directories that will be searched for Java .cla ss file. The directories in this
list will be added to the javac and javah command lines via the -clas spath option. The individual list will be added to the javac and javah command lines via the -clas spath option. The individual
directory names will be separated by the operating system's path sepa rate character (: on directory names will be separated by the operating system's path sepa rate character (: on
UNIX/Linux/POSIX, ; on Windows). UNIX/Linux/POSIX, ; on Windows).
Note that this currently just adds the specified directory via the -c
lasspath option. SCons does not
currently search the $JAVACLASSPATH directories for dependency .class
files.
JAVACLASSSUFFIX JAVACLASSSUFFIX
The suffix for Java class files; .class by default. The suffix for Java class files; .class by default.
JAVAH JAVAH
The Java generator for C header and stub files. The Java generator for C header and stub files.
JAVAHCOM JAVAHCOM
The command line used to generate C header and stub files from Java c lasses. Any options specified in The command line used to generate C header and stub files from Java c lasses. Any options specified in
the $JAVAHFLAGS construction variable are included on this command li ne. the $JAVAHFLAGS construction variable are included on this command li ne.
skipping to change at line 7226 skipping to change at line 7231
some extra dynamically generated options (such as -Wl,-soname=$_LDMOD ULESONAME). It is unused by plain some extra dynamically generated options (such as -Wl,-soname=$_LDMOD ULESONAME). It is unused by plain
(unversioned) loadable modules. (unversioned) loadable modules.
LDMODULEVERSIONFLAGS LDMODULEVERSIONFLAGS
Extra flags added to $LDMODULECOM when building versioned LoadableMod ule. These flags are only used Extra flags added to $LDMODULECOM when building versioned LoadableMod ule. These flags are only used
when $LDMODULEVERSION is set. when $LDMODULEVERSION is set.
LEX LEX
The lexical analyzer generator. The lexical analyzer generator.
LEX_HEADER_FILE
If supplied, generate a C header file with the name taken from this v
ariable. Will be emitted as a
--header-file= command-line option. Use this in preference to includi
ng --header-file= in $LEXFLAGS
directly.
LEX_TABLES_FILE
If supplied, write the lex tables to a file with the name taken from
this variable. Will be emitted as
a --tables-file= command-line option. Use this in preference to inclu
ding --tables-file= in $LEXFLAGS
directly.
LEXCOM LEXCOM
The command line used to call the lexical analyzer generator to gener ate a source file. The command line used to call the lexical analyzer generator to gener ate a source file.
LEXCOMSTR LEXCOMSTR
The string displayed when generating a source file using the lexical analyzer generator. If this is The string displayed when generating a source file using the lexical analyzer generator. If this is
not set, then $LEXCOM (the command line) is displayed. not set, then $LEXCOM (the command line) is displayed.
env = Environment(LEXCOMSTR = "Lex'ing $TARGET from $SOURCES") env = Environment(LEXCOMSTR="Lex'ing $TARGET from $SOURCES")
LEXFLAGS LEXFLAGS
General options passed to the lexical analyzer generator. General options passed to the lexical analyzer generator. In addition
to passing the value on during
invocation, the lex tool also examines this construction variable for
options which cause additional
output files to be generated, and adds those to the target list. Reco
gnized for this purpose are GNU
flex options --header-file= and --tables-file=; the output file is na
med by the option argument.
Note that files specified by --header-file= and --tables-file= may no
t be properly handled by SCons in
all situations. Consider using $LEX_HEADER_FILE and $LEX_TABLES_FILE
instead.
LEXUNISTD LEXUNISTD
Used only on windows environments to set a lex flag to prevent 'unist d.h' from being included. The Used only on windows environments to set a lex flag to prevent 'unist d.h' from being included. The
default value is '--nounistd'. default value is '--nounistd'.
_LIBDIRFLAGS _LIBDIRFLAGS
An automatically-generated construction variable containing the linke r command-line options for An automatically-generated construction variable containing the linke r command-line options for
specifying directories to be searched for library. The value of $_LIB DIRFLAGS is created by specifying directories to be searched for library. The value of $_LIB DIRFLAGS is created by
respectively prepending and appending $LIBDIRPREFIX and $LIBDIRSUFFIX to each directory in $LIBPATH. respectively prepending and appending $LIBDIRPREFIX and $LIBDIRSUFFIX to each directory in $LIBPATH.
skipping to change at line 7346 skipping to change at line 7367
win32, os2, etc.), but the value is overridden by individual tools (a r, mslib, sgiar, sunar, tlib, win32, os2, etc.), but the value is overridden by individual tools (a r, mslib, sgiar, sunar, tlib,
etc.) to reflect the names of the libraries they create. etc.) to reflect the names of the libraries they create.
LIBSUFFIXES LIBSUFFIXES
A list of all legal suffixes for library file names. When searching f or library dependencies, SCons A list of all legal suffixes for library file names. When searching f or library dependencies, SCons
will look for files with prefixes from the $LIBPREFIXES list, the bas e library name, and these will look for files with prefixes from the $LIBPREFIXES list, the bas e library name, and these
suffixes. suffixes.
LICENSE LICENSE
The abbreviated name, preferably the SPDX code, of the license under which this project is released The abbreviated name, preferably the SPDX code, of the license under which this project is released
(GPL-3.0, LGPL-2.1, BSD-2-Clause etc.). See http://www.opensource.org /licenses/alphabetical[6] for a (GPL-3.0, LGPL-2.1, BSD-2-Clause etc.). See http://www.opensource.org /licenses/alphabetical[5] for a
list of license names and SPDX codes. list of license names and SPDX codes.
See the Package builder. See the Package builder.
LINESEPARATOR LINESEPARATOR
The separator used by the Substfile and Textfile builders. This value is used between sources when The separator used by the Substfile and Textfile builders. This value is used between sources when
constructing the target. It defaults to the current system line separ ator. constructing the target. It defaults to the current system line separ ator.
LINGUAS_FILE LINGUAS_FILE
The $LINGUAS_FILE defines file(s) containing list of additional lingu as to be processed by POInit, The $LINGUAS_FILE defines file(s) containing list of additional lingu as to be processed by POInit,
skipping to change at line 7498 skipping to change at line 7519
MSVC_BATCH MSVC_BATCH
When set to any true value, specifies that SCons should batch compila tion of object files when calling When set to any true value, specifies that SCons should batch compila tion of object files when calling
the Microsoft Visual C/C++ compiler. All compilations of source files from the same source directory the Microsoft Visual C/C++ compiler. All compilations of source files from the same source directory
that generate target files in a same output directory and were config ured in SCons using the same that generate target files in a same output directory and were config ured in SCons using the same
construction environment will be built in a single call to the compil er. Only source files that have construction environment will be built in a single call to the compil er. Only source files that have
changed since their object files were built will be passed to each co mpiler invocation (via the changed since their object files were built will be passed to each co mpiler invocation (via the
$CHANGED_SOURCES construction variable). Any compilations where the o bject (target) file base name $CHANGED_SOURCES construction variable). Any compilations where the o bject (target) file base name
(minus the .obj) does not match the source file base name will be com piled separately. (minus the .obj) does not match the source file base name will be com piled separately.
MSVC_NOTFOUND_POLICY
Specify the scons behavior when the Microsoft Visual C/C++ compiler i
s not detected.
The $MSVC_NOTFOUND_POLICY specifies the scons behavior when no msvc v
ersions are detected or when the
requested msvc version is not detected.
The valid values for $MSVC_NOTFOUND_POLICY and the corresponding scon
s behavior are:
'Error' or 'Exception'
Raise an exception when no msvc versions are detected or when the
requested msvc version is not
detected.
'Warning' or 'Warn'
Issue a warning and continue when no msvc versions are detected o
r when the requested msvc version
is not detected. Depending on usage, this could result in build f
ailure(s).
'Ignore' or 'Suppress'
Take no action and continue when no msvc versions are detected or
when the requested msvc version
is not detected. Depending on usage, this could result in build f
ailure(s).
Note: in addition to the camel case values shown above, lower case an
d upper case values are accepted
as well.
The $MSVC_NOTFOUND_POLICY is applied when any of the following condit
ions are satisfied:
· $MSVC_VERSION is specified, the default tools list is implicitly
defined (i.e., the tools list is
not specified), and the default tools list contains one or more o
f the msvc tools.
· $MSVC_VERSION is specified, the default tools list is explicitly
specified (e.g.,
tools=['default']), and the default tools list contains one or mo
re of the msvc tools.
· A non-default tools list is specified that contains one or more o
f the msvc tools (e.g.,
tools=['msvc', 'mslink']).
The $MSVC_NOTFOUND_POLICY is ignored when any of the following condit
ions are satisfied:
· $MSVC_VERSION is not specified and the default tools list is imp
licitly defined (i.e., the tools
list is not specified).
· $MSVC_VERSION is not specified and the default tools list is exp
licitly specified (e.g.,
tools=['default']).
· A non-default tool list is specified that does not contain any of
the msvc tools (e.g.,
tools=['mingw']).
Important usage details:
· $MSVC_NOTFOUND_POLICY must be passed as an argument to the Envir
onment constructor when an msvc
tool (e.g., msvc, msvs, etc.) is loaded via the default tools lis
t or via a tools list passed to
the Environment constructor. Otherwise, $MSVC_NOTFOUND_POLICY mus
t be set before the first msvc
tool is loaded into the environment.
When $MSVC_NOTFOUND_POLICY is not specified, the default scons behavi
or is to issue a warning and
continue subject to the conditions listed above. The default scons be
havior may change in the future.
MSVC_SCRIPT_ARGS
Pass user-defined arguments to the Visual C++ batch file determined v
ia autodetection.
$MSVC_SCRIPT_ARGS is available for msvc batch file arguments that do
not have first-class support via
construction variables or when there is an issue with the appropriate
construction variable
validation. When available, it is recommended to use the appropriate
construction variables (e.g.,
$MSVC_TOOLSET_VERSION) rather than $MSVC_SCRIPT_ARGS arguments.
The valid values for $MSVC_SCRIPT_ARGS are: None, a string, or a list
of strings.
The $MSVC_SCRIPT_ARGS value is converted to a scalar string (i.e., "f
lattened"). The resulting scalar
string, if not empty, is passed as an argument to the msvc batch file
determined via autodetection
subject to the validation conditions listed below.
$MSVC_SCRIPT_ARGS is ignored when the value is None and when the resu
lt from argument conversion is an
empty string. The validation conditions below do not apply.
An exception is raised when any of the following conditions are satis
fied:
· $MSVC_SCRIPT_ARGS is specified for Visual Studio 2013 and earlie
r.
· Multiple SDK version arguments (e.g., '10.0.20348.0') are specifi
ed in $MSVC_SCRIPT_ARGS.
· $MSVC_SDK_VERSION is specified and an SDK version argument (e.g.
, '10.0.20348.0') is specified in
$MSVC_SCRIPT_ARGS. Multiple SDK version declarations via $MSVC_SD
K_VERSION and $MSVC_SCRIPT_ARGS
are not allowed.
· Multiple toolset version arguments (e.g., '-vcvars_ver=14.29') ar
e specified in $MSVC_SCRIPT_ARGS.
· $MSVC_TOOLSET_VERSION is specified and a toolset version argumen
t (e.g., '-vcvars_ver=14.29') is
specified in $MSVC_SCRIPT_ARGS. Multiple toolset version declarat
ions via $MSVC_TOOLSET_VERSION
and $MSVC_SCRIPT_ARGS are not allowed.
· Multiple spectre library arguments (e.g., '-vcvars_spectre_libs=s
pectre') are specified in
$MSVC_SCRIPT_ARGS.
· $MSVC_SPECTRE_LIBS is enabled and a spectre library argument (e.
g.,
'-vcvars_spectre_libs=spectre') is specified in $MSVC_SCRIPT_ARGS
. Multiple spectre library
declarations via $MSVC_SPECTRE_LIBS and $MSVC_SCRIPT_ARGS are not
allowed.
· Multiple UWP arguments (e.g., uwp or store) are specified in $MSV
C_SCRIPT_ARGS.
· $MSVC_UWP_APP is enabled and a UWP argument (e.g., uwp or store)
is specified in
$MSVC_SCRIPT_ARGS. Multiple UWP declarations via $MSVC_UWP_APP an
d $MSVC_SCRIPT_ARGS are not
allowed.
Example 1 - A Visual Studio 2022 build with an SDK version and a tool
set version specified with a
string argument:
env = Environment(MSVC_VERSION='14.3', MSVC_SCRIPT_ARGS='10.0.203
48.0 -vcvars_ver=14.29.30133')
Example 2 - A Visual Studio 2022 build with an SDK version and a tool
set version specified with a list
argument:
env = Environment(MSVC_VERSION='14.3', MSVC_SCRIPT_ARGS=['10.0.20
348.0', '-vcvars_ver=14.29.30133'])
Important usage details:
· $MSVC_SCRIPT_ARGS must be passed as an argument to the Environme
nt constructor when an msvc tool
(e.g., msvc, msvs, etc.) is loaded via the default tools list or
via a tools list passed to the
Environment constructor. Otherwise, $MSVC_SCRIPT_ARGS must be set
before the first msvc tool is
loaded into the environment.
· Other than checking for multiple declarations as described above,
$MSVC_SCRIPT_ARGS arguments are
not validated.
·
Erroneous, inconsistent, and/or version incompatible $MSVC_SCRIP
T_ARGS arguments are likely to
result in build failures for reasons that are not readily apparen
t and may be difficult to
diagnose. The burden is on the user to ensure that the arguments
provided to the msvc batch file
are valid, consistent and compatible with the version of msvc sel
ected.
MSVC_SCRIPTERROR_POLICY
Specify the scons behavior when Microsoft Visual C/C++ batch file err
ors are detected.
The $MSVC_SCRIPTERROR_POLICY specifies the scons behavior when msvc b
atch file errors are detected.
When $MSVC_SCRIPTERROR_POLICY is not specified, the default scons beh
avior is to suppress msvc batch
file error messages.
The root cause of msvc build failures may be difficult to diagnose. I
n these situations, setting the
scons behavior to issue a warning when msvc batch file errors are det
ected may produce additional
diagnostic information.
The valid values for $MSVC_SCRIPTERROR_POLICY and the corresponding s
cons behavior are:
'Error' or 'Exception'
Raise an exception when msvc batch file errors are detected.
'Warning' or 'Warn'
Issue a warning when msvc batch file errors are detected.
'Ignore' or 'Suppress'
Suppress msvc batch file error messages.
Note: in addition to the camel case values shown above, lower case an
d upper case values are accepted
as well.
Example 1 - A Visual Studio 2022 build with user-defined script argum
ents:
env = environment(MSVC_VERSION='14.3', MSVC_SCRIPT_ARGS=['8.1', '
store', '-vcvars_ver=14.1'])
env.Program('hello', ['hello.c'], CCFLAGS='/MD', LIBS=['kernel32'
, 'user32', 'runtimeobject'])
Example 1 - Output fragment:
...
link /nologo /OUT:_build001\hello.exe kernel32.lib user32.lib run
timeobject.lib _build001\hello.obj
LINK : fatal error LNK1104: cannot open file 'MSVCRT.lib'
...
Example 2 - A Visual Studio 2022 build with user-defined script argum
ents and the script error policy
set to issue a warning when msvc batch file errors are detected:
env = environment(MSVC_VERSION='14.3', MSVC_SCRIPT_ARGS=['8.1', '
store', '-vcvars_ver=14.1'], MSVC_SCRIPTERROR_POLICY='warn')
env.Program('hello', ['hello.c'], CCFLAGS='/MD', LIBS=['kernel32'
, 'user32', 'runtimeobject'])
Example 2 - Output fragment:
...
scons: warning: vc script errors detected:
[ERROR:vcvars.bat] The UWP Application Platform requires a Window
s 10 SDK.
[ERROR:vcvars.bat] WindowsSdkDir = "C:\Program Files (x86)\Window
s Kits\8.1\"
[ERROR:vcvars.bat] host/target architecture is not supported : {
x64 , x64 }
...
link /nologo /OUT:_build001\hello.exe kernel32.lib user32.lib run
timeobject.lib _build001\hello.obj
LINK : fatal error LNK1104: cannot open file 'MSVCRT.lib'
Important usage details:
· $MSVC_SCRIPTERROR_POLICY must be passed as an argument to the En
vironment constructor when an
msvc tool (e.g., msvc, msvs, etc.) is loaded via the default tool
s list or via a tools list passed
to the Environment constructor. Otherwise, $MSVC_SCRIPTERROR_POLI
CY must be set before the first
msvc tool is loaded into the environment.
· Due to scons implementation details, not all Windows system envir
onment variables are propagated
to the environment in which the msvc batch file is executed. Depe
nding on Visual Studio version
and installation options, non-fatal msvc batch file error message
s may be generated for ancillary
tools which may not affect builds with the msvc compiler. For thi
s reason, caution is recommended
when setting the script error policy to raise an exception (e.g.,
'Error').
MSVC_SDK_VERSION
Build with a specific version of the Microsoft Software Development K
it (SDK).
The valid values for $MSVC_SDK_VERSION are: None or a string containi
ng the requested SDK version
(e.g., '10.0.20348.0').
$MSVC_SDK_VERSION is ignored when the value is None and when the valu
e is an empty string. The
validation conditions below do not apply.
An exception is raised when any of the following conditions are satis
fied:
· $MSVC_SDK_VERSION is specified for Visual Studio 2013 and earlie
r.
· $MSVC_SDK_VERSION is specified and an SDK version argument is sp
ecified in $MSVC_SCRIPT_ARGS.
Multiple SDK version declarations via $MSVC_SDK_VERSION and $MSVC
_SCRIPT_ARGS are not allowed.
· The $MSVC_SDK_VERSION specified does not match any of the support
ed formats:
· '10.0.XXXXX.Y' [SDK 10.0]
· '8.1' [SDK 8.1]
· The system folder for the corresponding $MSVC_SDK_VERSION version
is not found. The requested SDK
version does not appear to be installed.
· The $MSVC_SDK_VERSION version does not appear to support the requ
ested platform type (i.e., UWP or
Desktop). The requested SDK version platform type components do n
ot appear to be installed.
· The $MSVC_SDK_VERSION version is 8.1, the platform type is UWP, a
nd the build tools selected are
from Visual Studio 2017 and later (i.e., $MSVC_VERSION must be '1
4.0' or $MSVC_TOOLSET_VERSION
must be '14.0').
Example 1 - A Visual Studio 2022 build with a specific Windows SDK ve
rsion:
env = Environment(MSVC_VERSION='14.3', MSVC_SDK_VERSION='10.0.203
48.0')
Example 2 - A Visual Studio 2022 build with a specific SDK version fo
r the Universal Windows Platform:
env = Environment(MSVC_VERSION='14.3', MSVC_SDK_VERSION='10.0.203
48.0', MSVC_UWP_APP=True)
Important usage details:
· $MSVC_SDK_VERSION must be passed as an argument to the Environme
nt constructor when an msvc tool
(e.g., msvc, msvs, etc.) is loaded via the default tools list or
via a tools list passed to the
Environment constructor. Otherwise, $MSVC_SDK_VERSION must be set
before the first msvc tool is
loaded into the environment.
· Should a SDK 10.0 version be installed that does not follow the
naming scheme above, the SDK
version will need to be specified via $MSVC_SCRIPT_ARGS until the
version number validation format
can be extended.
· Should an exception be raised indicating that the SDK version is
not found, verify that the
requested SDK version is installed with the necessary platform ty
pe components.
· There is a known issue with the Microsoft libraries when the targ
et architecture is ARM64 and a
Windows 11 SDK (version '10.0.22000.0' and later) is used with th
e v141 build tools and older v142
toolsets (versions '14.28.29333' and earlier). Should build failu
res arise with these combinations
of settings due to unresolved symbols in the Microsoft libraries,
$MSVC_SDK_VERSION may be
employed to specify a Windows 10 SDK (e.g., '10.0.20348.0') for t
he build.
MSVC_SPECTRE_LIBS
Build with the spectre-mitigated Visual C++ libraries.
The valid values for $MSVC_SPECTRE_LIBS are: True, False, or None.
When $MSVC_SPECTRE_LIBS is enabled (i.e., True), the Visual C++ envir
onment will include the paths to
the spectre-mitigated implementations of the Microsoft Visual C++ lib
raries.
An exception is raised when any of the following conditions are satis
fied:
· $MSVC_SPECTRE_LIBS is enabled for Visual Studio 2015 and earlier
.
· $MSVC_SPECTRE_LIBS is enabled and a spectre library argument is
specified in $MSVC_SCRIPT_ARGS.
Multiple spectre library declarations via $MSVC_SPECTRE_LIBS and
$MSVC_SCRIPT_ARGS are not
allowed.
· $MSVC_SPECTRE_LIBS is enabled and the platform type is UWP. Ther
e are no spectre-mitigated
libraries for Universal Windows Platform (UWP) applications or co
mponents.
Example - A Visual Studio 2022 build with spectre mitigated Visual C+
+ libraries:
env = Environment(MSVC_VERSION='14.3', MSVC_SPECTRE_LIBS=True)
Important usage details:
· $MSVC_SPECTRE_LIBS must be passed as an argument to the Environm
ent constructor when an msvc tool
(e.g., msvc, msvs, etc.) is loaded via the default tools list or
via a tools list passed to the
Environment constructor. Otherwise, $MSVC_SPECTRE_LIBS must be se
t before the first msvc tool is
loaded into the environment.
· Additional compiler switches (e.g., /Qspectre) are necessary for
including spectre mitigations
when building user artifacts. Refer to the Visual Studio document
ation for details.
·
The existence of the spectre libraries host architecture and tar
get architecture folders are not
verified when $MSVC_SPECTRE_LIBS is enabled which could result in
build failures. The burden is
on the user to ensure the requisite libraries with spectre mitiga
tions are installed.
MSVC_TOOLSET_VERSION
Build with a specific Visual C++ toolset version.
Specifying $MSVC_TOOLSET_VERSION does not affect the autodetection a
nd selection of msvc instances.
The $MSVC_TOOLSET_VERSION is applied after an msvc instance is select
ed. This could be the default
version of msvc if $MSVC_VERSION is not specified.
The valid values for $MSVC_TOOLSET_VERSION are: None or a string cont
aining the requested toolset
version (e.g., '14.29').
$MSVC_TOOLSET_VERSION is ignored when the value is None and when the
value is an empty string. The
validation conditions below do not apply.
An exception is raised when any of the following conditions are satis
fied:
· $MSVC_TOOLSET_VERSION is specified for Visual Studio 2015 and ea
rlier.
· $MSVC_TOOLSET_VERSION is specified and a toolset version argumen
t is specified in
$MSVC_SCRIPT_ARGS. Multiple toolset version declarations via $MSV
C_TOOLSET_VERSION and
$MSVC_SCRIPT_ARGS are not allowed.
· The $MSVC_TOOLSET_VERSION specified does not match any of the sup
ported formats:
· 'XX.Y'
· 'XX.YY'
· 'XX.YY.ZZZZZ'
· 'XX.YY.Z' to 'XX.YY.ZZZZ'
[scons extension not directly supported by the msvc batch fi
les and may be removed in the
future]
· 'XX.YY.ZZ.N' [SxS format]
· 'XX.YY.ZZ.NN' [SxS format]
· The major msvc version prefix (i.e., 'XX.Y') of the $MSVC_TOOLSET
_VERSION specified is for Visual
Studio 2013 and earlier (e.g., '12.0').
· The major msvc version prefix (i.e., 'XX.Y') of the $MSVC_TOOLSET
_VERSION specified is greater
than the msvc version selected (e.g., '99.0').
· A system folder for the corresponding $MSVC_TOOLSET_VERSION versi
on is not found. The requested
toolset version does not appear to be installed.
Toolset selection details:
· When $MSVC_TOOLSET_VERSION is not an SxS version number or a full
toolset version number: the
first toolset version, ranked in descending order, that matches t
he $MSVC_TOOLSET_VERSION prefix
is selected.
· When $MSVC_TOOLSET_VERSION is specified using the major msvc vers
ion prefix (i.e., 'XX.Y') and the
major msvc version is that of the latest release of Visual Studio
, the selected toolset version
may not be the same as the default Visual C++ toolset version.
In the latest release of Visual Studio, the default Visual C++ to
olset version is not necessarily
the toolset with the largest version number.
Example 1 - A default Visual Studio build with a partial toolset vers
ion specified:
env = Environment(MSVC_TOOLSET_VERSION='14.2')
Example 2 - A default Visual Studio build with a partial toolset vers
ion specified:
env = Environment(MSVC_TOOLSET_VERSION='14.29')
Example 3 - A Visual Studio 2022 build with a full toolset version sp
ecified:
env = Environment(MSVC_VERSION='14.3', MSVC_TOOLSET_VERSION='14.2
9.30133')
Example 4 - A Visual Studio 2022 build with an SxS toolset version sp
ecified:
env = Environment(MSVC_VERSION='14.3', MSVC_TOOLSET_VERSION='14.2
9.16.11')
Important usage details:
· $MSVC_TOOLSET_VERSION must be passed as an argument to the Envir
onment constructor when an msvc
tool (e.g., msvc, msvs, etc.) is loaded via the default tools lis
t or via a tools list passed to
the Environment constructor. Otherwise, $MSVC_TOOLSET_VERSION mus
t be set before the first msvc
tool is loaded into the environment.
·
The existence of the toolset host architecture and target archit
ecture folders are not verified
when $MSVC_TOOLSET_VERSION is specified which could result in bui
ld failures. The burden is on
the user to ensure the requisite toolset target architecture buil
d tools are installed.
MSVC_USE_SCRIPT MSVC_USE_SCRIPT
Use a batch script to set up the Microsoft Visual C++ compiler. Use a batch script to set up the Microsoft Visual C++ compiler.
If set to the name of a Visual Studio .bat file (e.g. vcvars.bat), S Cons will run that batch file If set to the name of a Visual Studio .bat file (e.g. vcvars.bat), S Cons will run that batch file
instead of the auto-detected one, and extract the relevant variables from the result (typically instead of the auto-detected one, and extract the relevant variables from the result (typically
%INCLUDE%, %LIB%, and %PATH%) for supplying to the build. This can be useful to force the use of a %INCLUDE%, %LIB%, and %PATH%) for supplying to the build. This can be useful to force the use of a
compiler version that SCons does not detect. compiler version that SCons does not detect. $MSVC_USE_SCRIPT_ARGS p
rovides arguments passed to this
script.
Setting $MSVC_USE_SCRIPT to None bypasses the Visual Studio autodetec tion entirely; use this if you Setting $MSVC_USE_SCRIPT to None bypasses the Visual Studio autodetec tion entirely; use this if you
are running SCons in a Visual Studio cmd window and importing the she ll's environment variables - that are running SCons in a Visual Studio cmd window and importing the she ll's environment variables - that
is, if you are sure everything is set correctly already and you don't want SCons to change anything. is, if you are sure everything is set correctly already and you don't want SCons to change anything.
$MSVC_USE_SCRIPT overrides $MSVC_VERSION and $TARGET_ARCH. $MSVC_USE_SCRIPT ignores $MSVC_VERSION and $TARGET_ARCH.
MSVC_USE_SCRIPT_ARGS
Provides arguments passed to the script $MSVC_USE_SCRIPT.
MSVC_USE_SETTINGS
Use a dictionary to set up the Microsoft Visual C++ compiler.
$MSVC_USE_SETTINGS is ignored when $MSVC_USE_SCRIPT is defined and/or
when $MSVC_USE_SETTINGS is set
to None.
The dictionary is used to populate the environment with the relevant
variables (typically %INCLUDE%,
%LIB%, and %PATH%) for supplying to the build. This can be useful to
force the use of a compiler
environment that SCons does not configure correctly. This is an alter
native to manually configuring
the environment when bypassing Visual Studio autodetection entirely b
y setting $MSVC_USE_SCRIPT to
None.
Here is an example of configuring a build environment using the Micro
soft Visual C/C++ compiler
included in the Microsoft SDK on a 64-bit host and building for a 64-
bit architecture:
# Microsoft SDK 6.0 (MSVC 8.0): 64-bit host and 64-bit target
msvc_use_settings = {
"PATH": [
"C:\\Program Files\\Microsoft SDKs\\Windows\\v6.0\\VC\\Bi
n\\x64",
"C:\\Program Files\\Microsoft SDKs\\Windows\\v6.0\\Bin\\x
64",
"C:\\Program Files\\Microsoft SDKs\\Windows\\v6.0\\Bin",
"C:\\Windows\\Microsoft.NET\\Framework\\v2.0.50727",
"C:\\Windows\\system32",
"C:\\Windows",
"C:\\Windows\\System32\\Wbem",
"C:\\Windows\\System32\\WindowsPowerShell\\v1.0\\"
],
"INCLUDE": [
"C:\\Program Files\\Microsoft SDKs\\Windows\\v6.0\\VC\\In
clude",
"C:\\Program Files\\Microsoft SDKs\\Windows\\v6.0\\VC\\In
clude\\Sys",
"C:\\Program Files\\Microsoft SDKs\\Windows\\v6.0\\Includ
e",
"C:\\Program Files\\Microsoft SDKs\\Windows\\v6.0\\Includ
e\\gl",
],
"LIB": [
"C:\\Program Files\\Microsoft SDKs\\Windows\\v6.0\\VC\\Li
b\\x64",
"C:\\Program Files\\Microsoft SDKs\\Windows\\v6.0\\Lib\\x
64",
],
"LIBPATH": [],
"VSCMD_ARG_app_plat": [],
"VCINSTALLDIR": [],
"VCToolsInstallDir": []
}
# Specifying MSVC_VERSION is recommended
env = Environment(MSVC_VERSION='8.0', MSVC_USE_SETTINGS=msvc_use_
settings)
Important usage details:
· $MSVC_USE_SETTINGS must be passed as an argument to the Environm
ent constructor when an msvc tool
(e.g., msvc, msvs, etc.) is loaded via the default tools list or
via a tools list passed to the
Environment constructor. Otherwise, $MSVC_USE_SETTINGS must be se
t before the first msvc tool is
loaded into the environment.
·
The dictionary content requirements are based on the internal ms
vc implementation and therefore
may change at any time. The burden is on the user to ensure the
dictionary contents are minimally
sufficient to ensure successful builds.
MSVC_UWP_APP MSVC_UWP_APP
Build libraries for a Universal Windows Platform (UWP) Application. Build with the Universal Windows Platform (UWP) application Visual C+
+ libraries.
The valid values for $MSVC_UWP_APP are: True, '1', False, '0', or Non
e.
When $MSVC_UWP_APP is enabled (i.e., True or '1'), the Visual C++ env
ironment will be set up to point
to the Windows Store compatible libraries and Visual C++ runtimes. In
doing so, any libraries that are
built will be able to be used in a UWP App and published to the Windo
ws Store.
An exception is raised when any of the following conditions are satis
fied:
If $MSVC_UWP_APP is set, the Visual C++ environment will be set up to · $MSVC_UWP_APP is enabled for Visual Studio 2013 and earlier.
point to the Windows Store
compatible libraries and Visual C++ runtimes. In doing so, any librar
ies that are built will be able
to be used in a UWP App and published to the Windows Store. This flag
will only have an effect with
Visual Studio 2015 or later. This variable must be passed as an argum
ent to the Environment()
constructor; setting it later has no effect.
Valid values are '1' or '0' · $MSVC_UWP_APP is enabled and a UWP argument is specified in $MSV
C_SCRIPT_ARGS. Multiple UWP
declarations via $MSVC_UWP_APP and $MSVC_SCRIPT_ARGS are not allo
wed.
Example - A Visual Studio 2022 build for the Universal Windows Platfo
rm:
env = Environment(MSVC_VERSION='14.3', MSVC_UWP_APP=True)
Important usage details:
· $MSVC_UWP_APP must be passed as an argument to the Environment c
onstructor when an msvc tool
(e.g., msvc, msvs, etc.) is loaded via the default tools list or
via a tools list passed to the
Environment constructor. Otherwise, $MSVC_UWP_APP must be set bef
ore the first msvc tool is loaded
into the environment.
·
The existence of the UWP libraries is not verified when $MSVC_UW
P_APP is enabled which could
result in build failures. The burden is on the user to ensure th
e requisite UWP libraries are
installed.
MSVC_VERSION MSVC_VERSION
Sets the preferred version of Microsoft Visual C/C++ to use. Sets the preferred version of Microsoft Visual C/C++ to use.
If $MSVC_VERSION is not set, SCons will (by default) select the lates t version of Visual C/C++ If $MSVC_VERSION is not set, SCons will (by default) select the lates t version of Visual C/C++
installed on your system. If the specified version isn't installed, t ool initialization will fail. installed on your system. If the specified version isn't installed, t ool initialization will fail.
This variable must be passed as an argument to the Environment constr
uctor; setting it later has no $MSVC_VERSION must be passed as an argument to the Environment constr
effect. uctor when an msvc tool (e.g.,
msvc, msvs, etc.) is loaded via the default tools list or via a tools
list passed to the Environment
constructor. Otherwise, $MSVC_VERSION must be set before the first ms
vc tool is loaded into the
environment.
Valid values for Windows are 14.3, 14.2, 14.1, 14.1Exp, 14.0, 14.0Exp , 12.0, 12.0Exp, 11.0, 11.0Exp, Valid values for Windows are 14.3, 14.2, 14.1, 14.1Exp, 14.0, 14.0Exp , 12.0, 12.0Exp, 11.0, 11.0Exp,
10.0, 10.0Exp, 9.0, 9.0Exp, 8.0, 8.0Exp, 7.1, 7.0, and 6.0. Versions ending in Exp refer to "Express" 10.0, 10.0Exp, 9.0, 9.0Exp, 8.0, 8.0Exp, 7.1, 7.0, and 6.0. Versions ending in Exp refer to "Express"
or "Express for Desktop" editions. or "Express for Desktop" editions.
MSVS MSVS
When the Microsoft Visual Studio tools are initialized, they set up t his dictionary with the following When the Microsoft Visual Studio tools are initialized, they set up t his dictionary with the following
keys: keys:
VERSION VERSION
skipping to change at line 7699 skipping to change at line 8185
MWCW_VERSIONS MWCW_VERSIONS
A list of installed versions of the MetroWerks CodeWarrior C compiler on this system. A list of installed versions of the MetroWerks CodeWarrior C compiler on this system.
NAME NAME
Specfies the name of the project to package. Specfies the name of the project to package.
See the Package builder. See the Package builder.
NINJA_ALIAS_NAME NINJA_ALIAS_NAME
Name of the Alias() which is will cause SCons to create the ninja.bui The name of the alias target which will cause SCons to create the nin
ld file, and then (optionally) ja build file, and then
run ninja. (optionally) run ninja. The default value is generate-ninja.
NINJA_COMPDB_EXPAND NINJA_CMD_ARGS
Boolean value (True|False) to instruct ninja to expand the command li A string which will pass arguments through SCons to the ninja command
ne arguments normally put into when scons executes ninja. Has
response files. This prevents lines in the compilation database like no effect if $NINJA_DISABLE_AUTO_RUN is set.
“gcc @rsp_file” and instead
yields “gcc -c -o myfile.o myfile.c -Ia -DXYZ” This value can also be passed on the command line:
scons NINJA_CMD_ARGS=-v
or
scons NINJA_CMD_ARGS="-v -j 3"
Ninja's compdb tool added the “-x” flag in Ninja V1.9.0 NINJA_COMPDB_EXPAND
Boolean value to instruct ninja to expand the command line arguments
normally put into response files.
If true, prevents unexpanded lines in the compilation database like “
gcc @rsp_file” and instead yields
expanded lines like “gcc -c -o myfile.o myfile.c -Ia -DXYZ”.
Ninja's compdb tool added the -x flag in Ninja V1.9.0
NINJA_DEPFILE_PARSE_FORMAT
Determines the type of format ninja should expect when parsing header
include depfiles. Can be msvc,
gcc, or clang. The msvc option corresponds to /showIncludes format, a
nd gcc or clang correspond to
-MMD -MF.
NINJA_DIR NINJA_DIR
This propagates directly into the generated ninja.build file. From Ni The builddir value. Propagates directly into the generated ninja buil
nja's docs: builddir A directory d file. From Ninja's docs: “ A
for some Ninja output files. ... (You can also store other build outp directory for some Ninja output files. ... (You can also store other
ut in this directory.) build output in this directory.)
” The default value is .ninja.
NINJA_DISABLE_AUTO_RUN NINJA_DISABLE_AUTO_RUN
Boolean (True|False). Default: False When True, SCons will not run ni Boolean. Default: False. If true, SCons will not run ninja automatica
nja automatically after creating lly after creating the ninja
the ninja.build file. If not set, this will be set to True if “--disa build file.
ble_execute_ninja” or
SetOption('disable_execute_ninja', True) If not explicitly set, this will be set to True if --disable_execute_
ninja or
SetOption('disable_execute_ninja', True) is seen.
NINJA_ENV_VAR_CACHE NINJA_ENV_VAR_CACHE
A string that sets the environment for any environment variables that differ between the OS A string that sets the environment for any environment variables that differ between the OS
environment and the SCons command ENV. It will be compatible with the environment and the SCons execution environment.
default shell of the operating
system. If not explicitly specified, SCons will generate this dynamic It will be compatible with the default shell of the operating system.
ally from the Environment()'s
'ENV' “env['ENV']” where those values differ from the existing shell. If not explicitly set, SCons will generate this dynamically from the
. execution environment stored in
the current construction environment (e.g. env['ENV']) where those v
alues differ from the existing
shell..
NINJA_FILE_NAME NINJA_FILE_NAME
The filename for the generated Ninja build file defaults to ninja.bui ld The filename for the generated Ninja build file. The default is ninja .build.
NINJA_FORCE_SCONS_BUILD NINJA_FORCE_SCONS_BUILD
When NINJA_FORCE_SCONS_BUILD is True, this will cause the build nodes If true, causes the build nodes to callback to scons instead of using
to callback to scons instead of ninja to build them. This is
using ninja to build them. This is intended to be passed to the envir intended to be passed to the environment on the builder invocation. I
onment on the builder invocation. t is useful if you have a build
It is useful if you have a build node which does something which is n node which does something which is not easily translated into ninja.
ot easily translated into ninja.
NINJA_GENERATED_SOURCE_ALIAS_NAME
A string matching the name of a user defined alias which represents a
list of all generated sources.
This will prevent the auto-detection of generated sources from $NINJA
_GENERATED_SOURCE_SUFFIXES. Then
all other source files will be made to depend on this in the ninja bu
ild file, forcing the generated
sources to be built first.
NINJA_GENERATED_SOURCE_SUFFIXES NINJA_GENERATED_SOURCE_SUFFIXES
The list of source file suffixes which are generated by SCons build s teps. All source files which The list of source file suffixes which are generated by SCons build s teps. All source files which
match these suffixes will be added to the _generated_sources alias in match these suffixes will be added to the _generated_sources alias in
the output ninja.build file. the output ninja build file.
Then all other source files will be made to depend on this in the nin Then all other source files will be made to depend on this in the nin
ja.build file, forcing the ja build file, forcing the
generated sources to be built first. generated sources to be built first.
NINJA_MSVC_DEPS_PREFIX NINJA_MSVC_DEPS_PREFIX
This propagates directly into the generated ninja.build file. From Ni The msvc_deps_prefix string. Propagates directly into the generated n
nja's docs “defines the string inja build file. From Ninja's
which should be stripped from msvc’s /showIncludes output” docs: “defines the string which should be stripped from msvc's /showI
ncludes output”
NINJA_POOL NINJA_POOL
Set the “ninja_pool” for this or all targets in scope for this env va r. Set the ninja_pool for this or all targets in scope for this env var.
NINJA_REGENERATE_DEPS NINJA_REGENERATE_DEPS
A generator function used to create a ninja depsfile which includes a ll the files which would require A generator function used to create a ninja depfile which includes al l the files which would require
SCons to be invoked if they change. Or a list of said files. SCons to be invoked if they change. Or a list of said files.
_NINJA_REGENERATE_DEPS_FUNC _NINJA_REGENERATE_DEPS_FUNC
Internal value used to specify the function to call with argument env to generate the list of files Internal value used to specify the function to call with argument env to generate the list of files
which if changed would require the ninja file to be regenerated. which if changed would require the ninja build file to be regenerated
.
NINJA_SCONS_DAEMON_KEEP_ALIVE
The number of seconds for the SCons deamon launched by ninja to stay
alive. (Default: 180000)
NINJA_SCONS_DAEMON_PORT
The TCP/IP port for the SCons daemon to listen on. NOTE: You cannot
use a port already being listened
to on your build machine. (Default: random number between 10000,6000
0)
NINJA_SYNTAX NINJA_SYNTAX
Theres also NINJA_SYNTAX which is the path to a custom ninja_syntax.p The path to a custom ninja_syntax.py file which is used in generation
y file which is used in . The tool currently assumes you
generation. The tool currently assumes you have ninja installed throu have ninja installed as a Python module and grabs the syntax file fro
gh pip, and grabs the syntax file m that installation if
from that installation if none specified. $NINJA_SYNTAX is not explicitly set.
no_import_lib no_import_lib
When set to non-zero, suppresses creation of a corresponding Windows static import lib by the When set to non-zero, suppresses creation of a corresponding Windows static import lib by the
SharedLibrary builder when used with MinGW, Microsoft Visual Studio o r Metrowerks. This also SharedLibrary builder when used with MinGW, Microsoft Visual Studio o r Metrowerks. This also
suppresses creation of an export (.exp) file when using Microsoft Vis ual Studio. suppresses creation of an export (.exp) file when using Microsoft Vis ual Studio.
OBJPREFIX OBJPREFIX
The prefix used for (static) object file names. The prefix used for (static) object file names.
OBJSUFFIX OBJSUFFIX
skipping to change at line 7920 skipping to change at line 8441
POTUPDATE_ALIAS POTUPDATE_ALIAS
Name of the common phony target for all PO Templates created with POU pdate (default: 'pot-update'). Name of the common phony target for all PO Templates created with POU pdate (default: 'pot-update').
See xgettext tool and POTUpdate builder. See xgettext tool and POTUpdate builder.
POUPDATE_ALIAS POUPDATE_ALIAS
Common alias for all PO files being defined with POUpdate builder (de fault: 'po-update'). See msgmerge Common alias for all PO files being defined with POUpdate builder (de fault: 'po-update'). See msgmerge
tool and POUpdate builder. tool and POUpdate builder.
PRINT_CMD_LINE_FUNC PRINT_CMD_LINE_FUNC
A Python function used to print the command lines as they are execute d (assuming command printing is A Python function used to print the command lines as they are execute d (assuming command printing is
not disabled by the -q or -s options or their equivalents). The funct not disabled by the -q or -s options or their equivalents). The funct
ion should take four arguments: ion must accept four arguments:
s, the command being executed (a string), target, the target being bu s, target, source and env. s is a string showing the command being e
ilt (file node, list, or string xecuted, target, is the target
name(s)), source, the source(s) used (file node, list, or string name being built (file node, list, or string name(s)), source, is the sour
(s)), and env, the environment ce(s) used (file node, list, or
being used. string name(s)), and env is the environment being used.
The function must do the printing itself. The default implementation, used if this variable is not set The function must do the printing itself. The default implementation, used if this variable is not set
or is None, is: or is None, is to just print the string, as in:
def print_cmd_line(s, target, source, env): def print_cmd_line(s, target, source, env):
sys.stdout.write(s + "\n") sys.stdout.write(s + "\n")
Here's an example of a more interesting function: Here is an example of a more interesting function:
def print_cmd_line(s, target, source, env): def print_cmd_line(s, target, source, env):
sys.stdout.write("Building %s -> %s...\n" % sys.stdout.write(
(' and '.join([str(x) for x in source]), "Building %s -> %s...\n"
' and '.join([str(x) for x in target]))) % (
env=Environment(PRINT_CMD_LINE_FUNC=print_cmd_line) ' and '.join([str(x) for x in source]),
env.Program('foo', 'foo.c') ' and '.join([str(x) for x in target]),
)
)
env = Environment(PRINT_CMD_LINE_FUNC=print_cmd_line)
env.Program('foo', ['foo.c', 'bar.c'])
This prints:
...
scons: Building targets ...
Building bar.c -> bar.o...
Building foo.c -> foo.o...
Building foo.o and bar.o -> foo...
scons: done building targets.
This just prints "Building targetname from sourcename..." instead of Another example could be a function that logs the actual commands to
the actual commands. Such a a file.
function could also log the actual commands to a log file, for exampl
e.
PROGEMITTER PROGEMITTER
Contains the emitter specification for the Program builder. The manpa ge section "Builder Objects" Contains the emitter specification for the Program builder. The manpa ge section "Builder Objects"
contains general information on specifying emitters. contains general information on specifying emitters.
PROGPREFIX PROGPREFIX
The prefix used for executable file names. The prefix used for executable file names.
PROGSUFFIX PROGSUFFIX
The suffix used for executable file names. The suffix used for executable file names.
skipping to change at line 8264 skipping to change at line 8798
The command line to use when generating shared objects. See also $DLI NKCOM for linking static objects. The command line to use when generating shared objects. See also $DLI NKCOM for linking static objects.
SHDLINKFLAGS SHDLINKFLAGS
The list of flags to use when generating a shared object. See also $D LINKFLAGS for linking static The list of flags to use when generating a shared object. See also $D LINKFLAGS for linking static
objects. objects.
SHELL SHELL
A string naming the shell program that will be passed to the $SPAWN f unction. See the $SPAWN A string naming the shell program that will be passed to the $SPAWN f unction. See the $SPAWN
construction variable for more information. construction variable for more information.
SHELL_ENV_GENERATORS
Must be a list (or an iterable) containing functions where each funct
ion generates or alters the
environment dictionary which will be used when executing the $SPAWN f
unction. The functions will
initially be passed a reference of the current execution environment
(e.g. env['ENV']), and each
called while iterating the list. Each function must return a dictiona
ry which will then be passed to
the next function iterated. The return dictionary should contain keys
which represent the environment
variables and their respective values. This primary purpose of this c
onstruction variable is to give
the user the ability to substitute execution environment variables ba
sed on env, targets, and sources.
If desired, the user can completely customize the execution environme
nt for particular targets.
def custom_shell_env(env, target, source, shell_env):
"""customize shell_env if desired"""
if str(target[0]) == 'special_target':
shell_env['SPECIAL_VAR'] = env.subst('SOME_VAR', target=t
arget, source=source)
return shell_env
env["SHELL_ENV_GENERATORS"] = [custom_shell_env]
env The SCons construction environment from which the execution envir
onment can be derived from.
target The list of targets associated with this action.
source The list of sources associated with this action.
shell_env The current shell_env after iterating other SHELL_ENV_GENER
ATORS functions. This can be
compared to the passed env['ENV'] to detect any changes.
SHF03 SHF03
The Fortran 03 compiler used for generating shared-library objects. Y ou should normally set the The Fortran 03 compiler used for generating shared-library objects. Y ou should normally set the
$SHFORTRAN variable, which specifies the default Fortran compiler for all Fortran versions. You only $SHFORTRAN variable, which specifies the default Fortran compiler for all Fortran versions. You only
need to set $SHF03 if you need to use a specific compiler or compiler version for Fortran 03 files. need to set $SHF03 if you need to use a specific compiler or compiler version for Fortran 03 files.
SHF03COM SHF03COM
The command line used to compile a Fortran 03 source file to a shared -library object file. You only The command line used to compile a Fortran 03 source file to a shared -library object file. You only
need to set $SHF03COM if you need to use a specific command line for Fortran 03 files. You should need to set $SHF03COM if you need to use a specific command line for Fortran 03 files. You should
normally set the $SHFORTRANCOM variable, which specifies the default command line for all Fortran normally set the $SHFORTRANCOM variable, which specifies the default command line for all Fortran
versions. versions.
SHF03COMSTR SHF03COMSTR
If set, the string displayed when a Fortran 03 source file is compile d to a shared-library object If set, the string displayed when a Fortran 03 source file is compile d to a shared-library object
file. If not set, then $SHF03COM or $SHFORTRANCOM (the command line) is displayed. file. If not set, then $SHF03COM or $SHFORTRANCOM (the command line) is displayed.
SHF03FLAGS SHF03FLAGS
Options that are passed to the Fortran 03 compiler to generated share d-library objects. You only need Options that are passed to the Fortran 03 compiler to generated share d-library objects. You only need
to set $SHF03FLAGS if you need to define specific user options for Fo rtran 03 files. You should to set $SHF03FLAGS if you need to define specific user options for Fo rtran 03 files. You should
normally set the $SHFORTRANFLAGS variable, which specifies the user-s normally set the $FORTRANCOMMONFLAGS variable, which specifies the us
pecified options passed to the er-specified options passed to
default Fortran compiler for all Fortran versions. the default Fortran compiler for all Fortran versions.
SHF03PPCOM SHF03PPCOM
The command line used to compile a Fortran 03 source file to a shared -library object file after first The command line used to compile a Fortran 03 source file to a shared -library object file after first
running the file through the C preprocessor. Any options specified in the $SHF03FLAGS and $CPPFLAGS running the file through the C preprocessor. Any options specified in the $SHF03FLAGS and $CPPFLAGS
construction variables are included on this command line. You only ne ed to set $SHF03PPCOM if you need construction variables are included on this command line. You only ne ed to set $SHF03PPCOM if you need
to use a specific C-preprocessor command line for Fortran 03 files. Y ou should normally set the to use a specific C-preprocessor command line for Fortran 03 files. Y ou should normally set the
$SHFORTRANPPCOM variable, which specifies the default C-preprocessor command line for all Fortran $SHFORTRANPPCOM variable, which specifies the default C-preprocessor command line for all Fortran
versions. versions.
SHF03PPCOMSTR SHF03PPCOMSTR
skipping to change at line 8316 skipping to change at line 8877
normally set the $SHFORTRANCOM variable, which specifies the default command line for all Fortran normally set the $SHFORTRANCOM variable, which specifies the default command line for all Fortran
versions. versions.
SHF08COMSTR SHF08COMSTR
If set, the string displayed when a Fortran 08 source file is compile d to a shared-library object If set, the string displayed when a Fortran 08 source file is compile d to a shared-library object
file. If not set, then $SHF08COM or $SHFORTRANCOM (the command line) is displayed. file. If not set, then $SHF08COM or $SHFORTRANCOM (the command line) is displayed.
SHF08FLAGS SHF08FLAGS
Options that are passed to the Fortran 08 compiler to generated share d-library objects. You only need Options that are passed to the Fortran 08 compiler to generated share d-library objects. You only need
to set $SHF08FLAGS if you need to define specific user options for Fo rtran 08 files. You should to set $SHF08FLAGS if you need to define specific user options for Fo rtran 08 files. You should
normally set the $SHFORTRANFLAGS variable, which specifies the user-s normally set the $FORTRANCOMMONFLAGS variable, which specifies the us
pecified options passed to the er-specified options passed to
default Fortran compiler for all Fortran versions. the default Fortran compiler for all Fortran versions.
SHF08PPCOM SHF08PPCOM
The command line used to compile a Fortran 08 source file to a shared -library object file after first The command line used to compile a Fortran 08 source file to a shared -library object file after first
running the file through the C preprocessor. Any options specified in the $SHF08FLAGS and $CPPFLAGS running the file through the C preprocessor. Any options specified in the $SHF08FLAGS and $CPPFLAGS
construction variables are included on this command line. You only ne ed to set $SHF08PPCOM if you need construction variables are included on this command line. You only ne ed to set $SHF08PPCOM if you need
to use a specific C-preprocessor command line for Fortran 08 files. Y ou should normally set the to use a specific C-preprocessor command line for Fortran 08 files. Y ou should normally set the
$SHFORTRANPPCOM variable, which specifies the default C-preprocessor command line for all Fortran $SHFORTRANPPCOM variable, which specifies the default C-preprocessor command line for all Fortran
versions. versions.
SHF08PPCOMSTR SHF08PPCOMSTR
skipping to change at line 8350 skipping to change at line 8911
normally set the $SHFORTRANCOM variable, which specifies the default command line for all Fortran normally set the $SHFORTRANCOM variable, which specifies the default command line for all Fortran
versions. versions.
SHF77COMSTR SHF77COMSTR
If set, the string displayed when a Fortran 77 source file is compile d to a shared-library object If set, the string displayed when a Fortran 77 source file is compile d to a shared-library object
file. If not set, then $SHF77COM or $SHFORTRANCOM (the command line) is displayed. file. If not set, then $SHF77COM or $SHFORTRANCOM (the command line) is displayed.
SHF77FLAGS SHF77FLAGS
Options that are passed to the Fortran 77 compiler to generated share d-library objects. You only need Options that are passed to the Fortran 77 compiler to generated share d-library objects. You only need
to set $SHF77FLAGS if you need to define specific user options for Fo rtran 77 files. You should to set $SHF77FLAGS if you need to define specific user options for Fo rtran 77 files. You should
normally set the $SHFORTRANFLAGS variable, which specifies the user-s normally set the $FORTRANCOMMONFLAGS variable, which specifies the us
pecified options passed to the er-specified options passed to
default Fortran compiler for all Fortran versions. the default Fortran compiler for all Fortran versions.
SHF77PPCOM SHF77PPCOM
The command line used to compile a Fortran 77 source file to a shared -library object file after first The command line used to compile a Fortran 77 source file to a shared -library object file after first
running the file through the C preprocessor. Any options specified in the $SHF77FLAGS and $CPPFLAGS running the file through the C preprocessor. Any options specified in the $SHF77FLAGS and $CPPFLAGS
construction variables are included on this command line. You only ne ed to set $SHF77PPCOM if you need construction variables are included on this command line. You only ne ed to set $SHF77PPCOM if you need
to use a specific C-preprocessor command line for Fortran 77 files. Y ou should normally set the to use a specific C-preprocessor command line for Fortran 77 files. Y ou should normally set the
$SHFORTRANPPCOM variable, which specifies the default C-preprocessor command line for all Fortran $SHFORTRANPPCOM variable, which specifies the default C-preprocessor command line for all Fortran
versions. versions.
SHF77PPCOMSTR SHF77PPCOMSTR
skipping to change at line 8384 skipping to change at line 8945
normally set the $SHFORTRANCOM variable, which specifies the default command line for all Fortran normally set the $SHFORTRANCOM variable, which specifies the default command line for all Fortran
versions. versions.
SHF90COMSTR SHF90COMSTR
If set, the string displayed when a Fortran 90 source file is compile d to a shared-library object If set, the string displayed when a Fortran 90 source file is compile d to a shared-library object
file. If not set, then $SHF90COM or $SHFORTRANCOM (the command line) is displayed. file. If not set, then $SHF90COM or $SHFORTRANCOM (the command line) is displayed.
SHF90FLAGS SHF90FLAGS
Options that are passed to the Fortran 90 compiler to generated share d-library objects. You only need Options that are passed to the Fortran 90 compiler to generated share d-library objects. You only need
to set $SHF90FLAGS if you need to define specific user options for Fo rtran 90 files. You should to set $SHF90FLAGS if you need to define specific user options for Fo rtran 90 files. You should
normally set the $SHFORTRANFLAGS variable, which specifies the user-s normally set the $FORTRANCOMMONFLAGS variable, which specifies the us
pecified options passed to the er-specified options passed to
default Fortran compiler for all Fortran versions. the default Fortran compiler for all Fortran versions.
SHF90PPCOM SHF90PPCOM
The command line used to compile a Fortran 90 source file to a shared -library object file after first The command line used to compile a Fortran 90 source file to a shared -library object file after first
running the file through the C preprocessor. Any options specified in the $SHF90FLAGS and $CPPFLAGS running the file through the C preprocessor. Any options specified in the $SHF90FLAGS and $CPPFLAGS
construction variables are included on this command line. You only ne ed to set $SHF90PPCOM if you need construction variables are included on this command line. You only ne ed to set $SHF90PPCOM if you need
to use a specific C-preprocessor command line for Fortran 90 files. Y ou should normally set the to use a specific C-preprocessor command line for Fortran 90 files. Y ou should normally set the
$SHFORTRANPPCOM variable, which specifies the default C-preprocessor command line for all Fortran $SHFORTRANPPCOM variable, which specifies the default C-preprocessor command line for all Fortran
versions. versions.
SHF90PPCOMSTR SHF90PPCOMSTR
skipping to change at line 8418 skipping to change at line 8979
normally set the $SHFORTRANCOM variable, which specifies the default command line for all Fortran normally set the $SHFORTRANCOM variable, which specifies the default command line for all Fortran
versions. versions.
SHF95COMSTR SHF95COMSTR
If set, the string displayed when a Fortran 95 source file is compile d to a shared-library object If set, the string displayed when a Fortran 95 source file is compile d to a shared-library object
file. If not set, then $SHF95COM or $SHFORTRANCOM (the command line) is displayed. file. If not set, then $SHF95COM or $SHFORTRANCOM (the command line) is displayed.
SHF95FLAGS SHF95FLAGS
Options that are passed to the Fortran 95 compiler to generated share d-library objects. You only need Options that are passed to the Fortran 95 compiler to generated share d-library objects. You only need
to set $SHF95FLAGS if you need to define specific user options for Fo rtran 95 files. You should to set $SHF95FLAGS if you need to define specific user options for Fo rtran 95 files. You should
normally set the $SHFORTRANFLAGS variable, which specifies the user-s normally set the $FORTRANCOMMONFLAGS variable, which specifies the us
pecified options passed to the er-specified options passed to
default Fortran compiler for all Fortran versions. the default Fortran compiler for all Fortran versions.
SHF95PPCOM SHF95PPCOM
The command line used to compile a Fortran 95 source file to a shared -library object file after first The command line used to compile a Fortran 95 source file to a shared -library object file after first
running the file through the C preprocessor. Any options specified in the $SHF95FLAGS and $CPPFLAGS running the file through the C preprocessor. Any options specified in the $SHF95FLAGS and $CPPFLAGS
construction variables are included on this command line. You only ne ed to set $SHF95PPCOM if you need construction variables are included on this command line. You only ne ed to set $SHF95PPCOM if you need
to use a specific C-preprocessor command line for Fortran 95 files. Y ou should normally set the to use a specific C-preprocessor command line for Fortran 95 files. Y ou should normally set the
$SHFORTRANPPCOM variable, which specifies the default C-preprocessor command line for all Fortran $SHFORTRANPPCOM variable, which specifies the default C-preprocessor command line for all Fortran
versions. versions.
SHF95PPCOMSTR SHF95PPCOMSTR
If set, the string displayed when a Fortran 95 source file is compile d to a shared-library object file If set, the string displayed when a Fortran 95 source file is compile d to a shared-library object file
after first running the file through the C preprocessor. If not set, then $SHF95PPCOM or after first running the file through the C preprocessor. If not set, then $SHF95PPCOM or
$SHFORTRANPPCOM (the command line) is displayed. $SHFORTRANPPCOM (the command line) is displayed.
SHFORTRAN SHFORTRAN
The default Fortran compiler used for generating shared-library objec ts. The default Fortran compiler used for generating shared-library objec ts.
SHFORTRANCOM SHFORTRANCOM
The command line used to compile a Fortran source file to a shared-li The command line used to compile a Fortran source file to a shared-li
brary object file. brary object file. By default,
any options specified in the $SHFORTRANFLAGS, $_FORTRANMODFLAG, and $
_FORTRANINCFLAGS construction
variables are included on this command line. See also $FORTRANCOM.
SHFORTRANCOMSTR SHFORTRANCOMSTR
If set, the string displayed when a Fortran source file is compiled t o a shared-library object file. If set, the string displayed when a Fortran source file is compiled t o a shared-library object file.
If not set, then $SHFORTRANCOM (the command line) is displayed. If not set, then $SHFORTRANCOM (the command line) is displayed.
SHFORTRANFLAGS SHFORTRANFLAGS
Options that are passed to the Fortran compiler to generate shared-li brary objects. Options that are passed to the Fortran compiler to generate shared-li brary objects.
SHFORTRANPPCOM SHFORTRANPPCOM
The command line used to compile a Fortran source file to a shared-li brary object file after first The command line used to compile a Fortran source file to a shared-li brary object file after first
running the file through the C preprocessor. Any options specified in running the file through the C preprocessor. By default, any options
the $SHFORTRANFLAGS and specified in the $SHFORTRANFLAGS,
$CPPFLAGS construction variables are included on this command line. $CPPFLAGS, $_CPPDEFFLAGS, $_FORTRANMODFLAG, and $_FORTRANINCFLAGS con
struction variables are included
on this command line. See also $SHFORTRANCOM.
SHFORTRANPPCOMSTR SHFORTRANPPCOMSTR
If set, the string displayed when a Fortran source file is compiled t o a shared-library object file If set, the string displayed when a Fortran source file is compiled t o a shared-library object file
after first running the file through the C preprocessor. If not set, then $SHFORTRANPPCOM (the command after first running the file through the C preprocessor. If not set, then $SHFORTRANPPCOM (the command
line) is displayed. line) is displayed.
SHLIBEMITTER SHLIBEMITTER
Contains the emitter specification for the SharedLibrary builder. The manpage section "Builder Contains the emitter specification for the SharedLibrary builder. The manpage section "Builder
Objects" contains general information on specifying emitters. Objects" contains general information on specifying emitters.
skipping to change at line 8556 skipping to change at line 9120
env.SharedLibrary('test', 'test.c', SHLIBVERSION='0.1.2', SOVERSI ON='2') env.SharedLibrary('test', 'test.c', SHLIBVERSION='0.1.2', SOVERSI ON='2')
The variable is used, for example, by gnulink linker tool. The variable is used, for example, by gnulink linker tool.
In the example above SONAME would be libtest.so.2 which would be a sy mlink and point to In the example above SONAME would be libtest.so.2 which would be a sy mlink and point to
libtest.so.0.1.2 libtest.so.0.1.2
SPAWN SPAWN
A command interpreter function that will be called to execute command line strings. The function must A command interpreter function that will be called to execute command line strings. The function must
expect the following arguments: accept five arguments:
def spawn(shell, escape, cmd, args, env): def spawn(shell, escape, cmd, args, env):
sh is a string naming the shell program to use. escape is a function shell is a string naming the shell program to use, escape is a functi
that can be called to escape on that can be called to escape
shell special characters in the command line. cmd is the path to the shell special characters in the command line, cmd is the path to the
command to be executed. args is command to be executed, args
the arguments to the command. env is a dictionary of the environment holds the arguments to the command and env is a dictionary of environ
variables in which the command ment variables defining the
should be executed. execution environment in which the command should be executed.
STATIC_AND_SHARED_OBJECTS_ARE_THE_SAME STATIC_AND_SHARED_OBJECTS_ARE_THE_SAME
When this variable is true, static objects and shared objects are ass umed to be the same; that is, When this variable is true, static objects and shared objects are ass umed to be the same; that is,
SCons does not check for linking static objects into a shared library . SCons does not check for linking static objects into a shared library .
SUBST_DICT SUBST_DICT
The dictionary used by the Substfile or Textfile builders for substit ution values. It can be anything The dictionary used by the Substfile or Textfile builders for substit ution values. It can be anything
acceptable to the dict() constructor, so in addition to a dictionary, lists of tuples are also acceptable to the dict() constructor, so in addition to a dictionary, lists of tuples are also
acceptable. acceptable.
skipping to change at line 8587 skipping to change at line 9151
SUBSTFILESUFFIX SUBSTFILESUFFIX
The suffix used for Substfile file names, an empty string by default. The suffix used for Substfile file names, an empty string by default.
SUMMARY SUMMARY
A short summary of what the project is about. This is used to fill in the Summary: field in the A short summary of what the project is about. This is used to fill in the Summary: field in the
controlling information for Ipkg and RPM packages, and as the Descrip tion: field in MSI packages. controlling information for Ipkg and RPM packages, and as the Descrip tion: field in MSI packages.
See the Package builder. See the Package builder.
SWIG SWIG
The scripting language wrapper and interface generator. The name of the SWIG compiler to use.
SWIGCFILESUFFIX SWIGCFILESUFFIX
The suffix that will be used for intermediate C source files generate The suffix that will be used for intermediate C source files generate
d by the scripting language d by SWIG. The default value is
wrapper and interface generator. The default value is _wrap$CFILESUFF '_wrap$CFILESUFFIX' - that is, the concatenation of the string _wrap
IX. By default, this value is and the current C suffix
used whenever the -c++ option is not specified as part of the $SWIGFL $CFILESUFFIX. By default, this value is used whenever the -c++ option
AGS construction variable. is not specified as part of the
$SWIGFLAGS construction variable.
SWIGCOM SWIGCOM
The command line used to call the scripting language wrapper and inte rface generator. The command line used to call SWIG.
SWIGCOMSTR SWIGCOMSTR
The string displayed when calling the scripting language wrapper and The string displayed when calling SWIG. If this is not set, then $SWI
interface generator. If this is GCOM (the command line) is
not set, then $SWIGCOM (the command line) is displayed. displayed.
SWIGCXXFILESUFFIX SWIGCXXFILESUFFIX
The suffix that will be used for intermediate C++ source files genera The suffix that will be used for intermediate C++ source files genera
ted by the scripting language ted by SWIG. The default value is
wrapper and interface generator. The default value is _wrap$CFILESUFF '_wrap$CXXFILESUFFIX' - that is, the concatenation of the string _wra
IX. By default, this value is p and the current C++ suffix
used whenever the -c++ option is specified as part of the $SWIGFLAGS $CXXFILESUFFIX. By default, this value is used whenever the -c++ opti
construction variable. on is specified as part of the
$SWIGFLAGS construction variable.
SWIGDIRECTORSUFFIX SWIGDIRECTORSUFFIX
The suffix that will be used for intermediate C++ header files genera The suffix that will be used for intermediate C++ header files genera
ted by the scripting language ted by SWIG. These are only
wrapper and interface generator. These are only generated for C++ cod generated for C++ code when the SWIG 'directors' feature is turned on
e when the SWIG 'directors' . The default value is _wrap.h.
feature is turned on. The default value is _wrap.h.
SWIGFLAGS SWIGFLAGS
General options passed to the scripting language wrapper and interfac General options passed to SWIG. This is where you should set the targ
e generator. This is where you et language (-python, -perl5,
should set -python, -perl5, -tcl, or whatever other options you want -tcl, etc.) and whatever other options you want to specify to SWIG, s
to specify to SWIG. If you set uch as the -c++ to generate C++
the -c++ option in this variable, scons will, by default, generate a code instead of C Code.
C++ intermediate source file with
the extension that is specified as the $CXXFILESUFFIX variable.
_SWIGINCFLAGS _SWIGINCFLAGS
An automatically-generated construction variable containing the SWIG command-line options for An automatically-generated construction variable containing the SWIG command-line options for
specifying directories to be searched for included files. The value o f $_SWIGINCFLAGS is created by specifying directories to be searched for included files. The value o f $_SWIGINCFLAGS is created by
respectively prepending and appending $SWIGINCPREFIX and $SWIGINCSUFF IX to the beginning and end of respectively prepending and appending $SWIGINCPREFIX and $SWIGINCSUFF IX to the beginning and end of
each directory in $SWIGPATH. each directory in $SWIGPATH.
SWIGINCPREFIX SWIGINCPREFIX
The prefix used to specify an include directory on the SWIG command l ine. This will be prepended to The prefix used to specify an include directory on the SWIG command l ine. This will be prepended to
the beginning of each directory in the $SWIGPATH construction variabl e when the $_SWIGINCFLAGS the beginning of each directory in the $SWIGPATH construction variabl e when the $_SWIGINCFLAGS
variable is automatically generated. variable is automatically generated.
SWIGINCSUFFIX SWIGINCSUFFIX
The suffix used to specify an include directory on the SWIG command l ine. This will be appended to the The suffix used to specify an include directory on the SWIG command l ine. This will be appended to the
end of each directory in the $SWIGPATH construction variable when the $_SWIGINCFLAGS variable is end of each directory in the $SWIGPATH construction variable when the $_SWIGINCFLAGS variable is
automatically generated. automatically generated.
SWIGOUTDIR SWIGOUTDIR
Specifies the output directory in which the scripting language wrappe Specifies the output directory in which SWIG should place generated l
r and interface generator should anguage-specific files. This will
place generated language-specific files. This will be used by SCons t be used by SCons to identify the files that will be generated by the
o identify the files that will be SWIG call, and translated into
generated by the swig call, and translated into the swig -outdir opti the swig -outdir option on the command line.
on on the command line.
SWIGPATH SWIGPATH
The list of directories that the scripting language wrapper and inter The list of directories that SWIG will search for included files. SC
face generate will search for ons' SWIG implicit dependency
included files. The SWIG implicit dependency scanner will search thes scanner will search these directories for include files. The default
e directories for include files. value is an empty list.
The default value is an empty list.
Don't explicitly put include directory arguments in SWIGFLAGS; the re Don't explicitly put include directory arguments in $SWIGFLAGS the re
sult will be non-portable and the sult will be non-portable and the
directories will not be searched by the dependency scanner. Note: dir directories will not be searched by the dependency scanner. Note: dir
ectory names in SWIGPATH will be ectory names in $SWIGPATH will be
looked-up relative to the SConscript directory when they are used in a command. To force scons to looked-up relative to the SConscript directory when they are used in a command. To force scons to
look-up a directory relative to the root of the source tree use #: look-up a directory relative to the root of the source tree use a top -relative path (#):
env = Environment(SWIGPATH='#/include') env = Environment(SWIGPATH='#/include')
The directory look-up can also be forced using the Dir() function: The directory look-up can also be forced using the Dir() function:
include = Dir('include') include = Dir('include')
env = Environment(SWIGPATH=include) env = Environment(SWIGPATH=include)
The directory list will be added to command lines through the automat ically-generated $_SWIGINCFLAGS The directory list will be added to command lines through the automat ically-generated $_SWIGINCFLAGS
construction variable, which is constructed by respectively prependin g and appending the values of the construction variable, which is constructed by respectively prependin g and appending the values of the
$SWIGINCPREFIX and $SWIGINCSUFFIX construction variables to the begin ning and end of each directory in $SWIGINCPREFIX and $SWIGINCSUFFIX construction variables to the begin ning and end of each directory in
$SWIGPATH. Any command lines you define that need the SWIGPATH direct ory list should include $SWIGPATH. Any command lines you define that need the SWIGPATH direct ory list should include
$_SWIGINCFLAGS: $_SWIGINCFLAGS:
env = Environment(SWIGCOM="my_swig -o $TARGET $_SWIGINCFLAGS $SOU RCES") env = Environment(SWIGCOM="my_swig -o $TARGET $_SWIGINCFLAGS $SOU RCES")
SWIGVERSION SWIGVERSION
The version number of the SWIG tool. The detected version string of the SWIG tool.
TAR TAR
The tar archiver. The tar archiver.
TARCOM TARCOM
The command line used to call the tar archiver. The command line used to call the tar archiver.
TARCOMSTR TARCOMSTR
The string displayed when archiving files using the tar archiver. If this is not set, then $TARCOM The string displayed when archiving files using the tar archiver. If this is not set, then $TARCOM
(the command line) is displayed. (the command line) is displayed.
skipping to change at line 9081 skipping to change at line 9644
XGETTEXTPATHPREFIX XGETTEXTPATHPREFIX
This flag is used to add single search path to xgettext(1)'s commandl ine (default: '-D'). This flag is used to add single search path to xgettext(1)'s commandl ine (default: '-D').
XGETTEXTPATHSUFFIX XGETTEXTPATHSUFFIX
(default: '') (default: '')
YACC YACC
The parser generator. The parser generator.
YACC_GRAPH_FILE
If supplied, write a graph of the automaton to a file with the name t
aken from this variable. Will be
emitted as a --graph= command-line option. Use this in preference to
including --graph= in $YACCFLAGS
directly.
YACC_HEADER_FILE
If supplied, generate a header file with the name taken from this var
iable. Will be emitted as a
--header= command-line option. Use this in preference to including --
header= in $YACCFLAGS directly.
YACCCOM YACCCOM
The command line used to call the parser generator to generate a sour ce file. The command line used to call the parser generator to generate a sour ce file.
YACCCOMSTR YACCCOMSTR
The string displayed when generating a source file using the parser g enerator. If this is not set, The string displayed when generating a source file using the parser g enerator. If this is not set,
then $YACCCOM (the command line) is displayed. then $YACCCOM (the command line) is displayed.
env = Environment(YACCCOMSTR = "Yacc'ing $TARGET from $SOURCES") env = Environment(YACCCOMSTR="Yacc'ing $TARGET from $SOURCES")
YACCFLAGS YACCFLAGS
General options passed to the parser generator. If $YACCFLAGS contain General options passed to the parser generator. In addition to passin
s a -d option, SCons assumes that g the value on during invocation,
the call will also create a .h file (if the yacc source file ends in the yacc tool also examines this construction variable for options wh
a .y suffix) or a .hpp file (if ich cause additional output files
the yacc source file ends in a .yy suffix) to be generated, and adds those to the target list.
If a -d option is present, scons assumes that the call will also crea
te a header file with the suffix
defined by $YACCHFILESUFFIX if the yacc source file ends in a .y suff
ix, or a file with the suffix
defined by $YACCHXXFILESUFFIX if the yacc source file ends in a .yy s
uffix.
If a -g option is present, scons assumes that the call will also crea
te a graph file with the suffix
defined by $YACCVCGFILESUFFIX.
If a -v option is present, scons assumes that the call will also crea
te an output debug file with the
suffix .output.
Also recognized are GNU bison options --header= and its deprecated sy
nonym --defines=, which is
similar to -d but the output filename is named by the option argument
; and --graph=, which is similar
to -g but the output filename is named by the option argument.
Note that files specified by --header= and --graph= may not be proper
ly handled by SCons in all
situations. Consider using $YACC_HEADER_FILE and $YACC_GRAPH_FILE ins
tead.
YACCHFILESUFFIX YACCHFILESUFFIX
The suffix of the C header file generated by the parser generator whe n the -d option is used. Note The suffix of the C header file generated by the parser generator whe n the -d option is used. Note
that setting this variable does not cause the parser generator to gen erate a header file with the that setting this variable does not cause the parser generator to gen erate a header file with the
specified suffix, it exists to allow you to specify what suffix the p arser generator will use of its specified suffix, it exists to allow you to specify what suffix the p arser generator will use of its
own accord. The default value is .h. own accord. The default value is .h.
YACCHXXFILESUFFIX YACCHXXFILESUFFIX
The suffix of the C++ header file generated by the parser generator w hen the -d option is used. Note The suffix of the C++ header file generated by the parser generator w hen the -d option is used. Note
that setting this variable does not cause the parser generator to gen erate a header file with the that setting this variable does not cause the parser generator to gen erate a header file with the
skipping to change at line 9198 skipping to change at line 9787
specified config_h file. This means that the file is not necessarily re-built each time scons is run, specified config_h file. This means that the file is not necessarily re-built each time scons is run,
but is only rebuilt if its contents will have changed and some target that depends on the config_h but is only rebuilt if its contents will have changed and some target that depends on the config_h
file is being built. file is being built.
The clean and help arguments can be used to suppress execution of the configuration tests when the The clean and help arguments can be used to suppress execution of the configuration tests when the
-c/--clean or -H/-h/--help options are used, respectively. The defaul t behavior is always to execute -c/--clean or -H/-h/--help options are used, respectively. The defaul t behavior is always to execute
configure context tests, since the results of the tests may affect th e list of targets to be cleaned configure context tests, since the results of the tests may affect th e list of targets to be cleaned
or the help text. If the configure tests do not affect these, then yo u may add the clean=False or or the help text. If the configure tests do not affect these, then yo u may add the clean=False or
help=False arguments (or both) to avoid unnecessary test execution. help=False arguments (or both) to avoid unnecessary test execution.
SConf.Finish(context), context.Finish() context.Finish()
This method must be called after configuration is done. Though requir ed, this is not enforced except This method must be called after configuration is done. Though requir ed, this is not enforced except
if Configure is called again while there is still an active context, in which case an exception is if Configure is called again while there is still an active context, in which case an exception is
raised. Finish returns the environment as modified during the course of running the configuration raised. Finish returns the environment as modified during the course of running the configuration
checks. After this method is called, no further checks can be perform ed with this configuration checks. After this method is called, no further checks can be perform ed with this configuration
context. However, you can create a new configure context to perform a dditional checks. context. However, you can create a new configure context to perform a dditional checks.
Example of a typical Configure usage: Example of a typical Configure usage:
env = Environment() env = Environment()
conf = Configure(env) conf = Configure(env)
skipping to change at line 9221 skipping to change at line 9810
Exit(1) Exit(1)
if conf.CheckLibWithHeader("qt", "qapp.h", "c++", "QApplication qapp( 0,0);"): if conf.CheckLibWithHeader("qt", "qapp.h", "c++", "QApplication qapp( 0,0);"):
# do stuff for qt - usage, e.g. # do stuff for qt - usage, e.g.
conf.env.Append(CPPDEFINES="WITH_QT") conf.env.Append(CPPDEFINES="WITH_QT")
env = conf.Finish() env = conf.Finish()
A configure context has the following predefined methods which can be use d to perform checks. Where A configure context has the following predefined methods which can be use d to perform checks. Where
language is a required or optional parameter, the choice can currently be C or C++. The spellings accepted language is a required or optional parameter, the choice can currently be C or C++. The spellings accepted
for C are “C” or “c”; for C++ the value can be “CXX”, “cxx”, “C++” or “c+ +”. for C are “C” or “c”; for C++ the value can be “CXX”, “cxx”, “C++” or “c+ +”.
SConf.CheckHeader(context, header, [include_quotes, language]), context.C context.CheckHeader(header, [include_quotes, language])
heckHeader(header,
[include_quotes, language])
Checks if header is usable in the specified language. header may be a list, in which case the last Checks if header is usable in the specified language. header may be a list, in which case the last
item in the list is the header file to be checked, and the previous l ist items are header files whose item in the list is the header file to be checked, and the previous l ist items are header files whose
#include lines should precede the header line being checked for. The optional argument include_quotes #include lines should precede the header line being checked for. The optional argument include_quotes
must be a two character string, where the first character denotes the opening quote and the second must be a two character string, where the first character denotes the opening quote and the second
character denotes the closing quote. By default, both characters are " (double quote). The optional character denotes the closing quote. By default, both characters are " (double quote). The optional
argument language should be either C or C++ and selects the compiler to be used for the check. Returns argument language should be either C or C++ and selects the compiler to be used for the check. Returns
a boolean indicating success or failure. a boolean indicating success or failure.
SConf.CheckCHeader(context, header, [include_quotes]), context.CheckCHead context.CheckCHeader(header, [include_quotes])
er(header, [include_quotes]) Checks if header is usable when compiling a C language program. head
This is a wrapper around SConf.CheckHeader which checks if header is er may be a list, in which case
usable in the C language. header the last item in the list is the header file to be checked, and the p
may be a list, in which case the last item in the list is the header revious list items are header
file to be checked, and the files whose #include lines should precede the header line being check
previous list items are header files whose #include lines should prec ed for. The optional argument
ede the header line being checked include_quotes must be a two character string, where the first charac
for. The optional argument include_quotes must be a two character str ter denotes the opening quote and
ing, where the first character the second character denotes the closing quote. By default, both char
denotes the opening quote and the second character denotes the closin acters are " (double quote). Note
g quote. By default, both this is a wrapper around CheckHeader. Returns a boolean indicating su
characters are " (double quote). Returns a boolean indicating success ccess or failure.
or failure.
context.CheckCXXHeader(header, [include_quotes])
SConf.CheckCXXHeader(context, header, [include_quotes]), context.CheckCXX Checks if header is usable when compiling a C++ language program. he
Header(header, [include_quotes]) ader may be a list, in which case
This is a wrapper around SConf.CheckHeader which checks if header is the last item in the list is the header file to be checked, and the p
usable in the C++ language. revious list items are header
header may be a list, in which case the last item in the list is the files whose #include lines should precede the header line being check
header file to be checked, and ed for. The optional argument
the previous list items are header files whose #include lines should include_quotes must be a two character string, where the first charac
precede the header line being ter denotes the opening quote and
checked for. The optional argument include_quotes must be a two chara the second character denotes the closing quote. By default, both char
cter string, where the first acters are " (double quote). Note
character denotes the opening quote and the second character denotes this is a wrapper around CheckHeader. Returns a boolean indicating su
the closing quote. By default, ccess or failure.
both characters are " (double quote). Returns a boolean indicating su
ccess or failure.
SConf.CheckFunc(context, function_name, [header, language]), context.Chec context.CheckFunc(function_name, [header, language])
kFunc(function_name, [header,
language])
Checks if the specified C or C++ library function is available based on the context's local Checks if the specified C or C++ library function is available based on the context's local
environment settings (that is, using the values of CFLAGS, CPPFLAGS, LIBS or other relevant environment settings (that is, using the values of $CFLAGS, $CPPFLAGS , $LIBS or other relevant
construction variables). construction variables).
function_name is the name of the function to check for. The optional header argument is a string that function_name is the name of the function to check for. The optional header argument is a string that
will be placed at the top of the test file that will be compiled to c heck if the function exists; the will be placed at the top of the test file that will be compiled to c heck if the function exists; the
default is: default is:
#ifdef __cplusplus #ifdef __cplusplus
extern "C" extern "C"
#endif #endif
char function_name(); char function_name();
Returns an empty string on success, a string containing an error mess age on failure. Returns an empty string on success, a string containing an error mess age on failure.
SConf.CheckLib(context, [library, symbol, header, language, autoadd=True] context.CheckLib([library, symbol, header, language, autoadd=True])
), context.CheckLib([library,
symbol, header, language, autoadd=True])
Checks if library provides symbol. If autoadd is true (the default) a nd the library provides the Checks if library provides symbol. If autoadd is true (the default) a nd the library provides the
specified symbol, appends the library to the LIBS construction variab le library may also be None (the specified symbol, appends the library to the LIBS construction variab le library may also be None (the
default), in which case symbol is checked with the current LIBS varia ble, or a list of library names, default), in which case symbol is checked with the current LIBS varia ble, or a list of library names,
in which case each library in the list will be checked for symbol. If symbol is not set or is None, in which case each library in the list will be checked for symbol. If symbol is not set or is None,
then SConf.CheckLib just checks if you can link against the specified library. Note though it is legal then CheckLib just checks if you can link against the specified libra ry. Note though it is legal
syntax, it would not be very useful to call this method with library and symbol both omitted or None. syntax, it would not be very useful to call this method with library and symbol both omitted or None.
Returns a boolean indicating success or failure. Returns a boolean indicating success or failure.
SConf.CheckLibWithHeader(context, library, header, language, [call, autoa dd=True]),
context.CheckLibWithHeader(library, header, language, [call, autoadd=True ]) context.CheckLibWithHeader(library, header, language, [call, autoadd=True ])
Provides a more sophisticated way to check against libraries then the SConf.CheckLib call. library Provides a more sophisticated way to check against libraries then the CheckLib call. library
specifies the library or a list of libraries to check. header specif ies a header to check for. specifies the library or a list of libraries to check. header specif ies a header to check for.
header may be a list, in which case the last item in the list is the header file to be checked, and header may be a list, in which case the last item in the list is the header file to be checked, and
the previous list items are header files whose #include lines should precede the header line being the previous list items are header files whose #include lines should precede the header line being
checked for. call can be any valid expression (with a trailing ';'). If call is not set, the default checked for. call can be any valid expression (with a trailing ';'). If call is not set, the default
simply checks that you can link against the specified library. autoa dd (default true) specifies simply checks that you can link against the specified library. autoa dd (default true) specifies
whether to add the library to the environment if the check succeeds. Returns a boolean indicating whether to add the library to the environment if the check succeeds. Returns a boolean indicating
success or failure. success or failure.
SConf.CheckType(context, type_name, [includes, language]), context.CheckT context.CheckType(type_name, [includes, language])
ype(type_name, [includes,
language])
Checks for the existence of a type defined by typedef. type_name spe cifies the typedef name to check Checks for the existence of a type defined by typedef. type_name spe cifies the typedef name to check
for. includes is a string containing one or more #include lines that will be inserted into the for. includes is a string containing one or more #include lines that will be inserted into the
program that will be run to test for the existence of the type. Examp le: program that will be run to test for the existence of the type. Examp le:
sconf.CheckType('foo_type', '#include "my_types.h"', 'C++') sconf.CheckType('foo_type', '#include "my_types.h"', 'C++')
Returns an empty string on success, a string containing an error mess age on failure. Returns an empty string on success, a string containing an error mess age on failure.
SConf.CheckCC(context), context.CheckCC() context.CheckTypeSize(type_name, [header, language, expect])
Checks whether the C compiler (as defined by the CC construction vari
able) works by trying to compile
a small source file. Returns a boolean indicating success or failure.
By default, SCons only detects if there is a program with the correct
name, not if it is a functioning
compiler.
This uses the exact same command as the one used by the object builde
r for C source files, so it can
be used to detect if a particular compiler flag works or not.
SConf.CheckCXX(context), context.CheckCXX()
Checks whether the C++ compiler (as defined by the CXX construction v
ariable) works by trying to
compile a small source file. By default, SCons only detects if there
is a program with the correct
name, not if it is a functioning compiler. Returns a boolean indicati
ng success or failure.
This uses the exact same command as the one used by the object builde
r for C++ source files, so it can
be used to detect if a particular compiler flag works or not.
SConf.CheckSHCC(context), context.CheckSHCC()
Checks whether the shared-object C compiler (as defined by the SHCC c
onstruction variable) works by
trying to compile a small source file. By default, SCons only detects
if there is a program with the
correct name, not if it is a functioning compiler. Returns a boolean
indicating success or failure.
This uses the exact same command as the one used by the object builde
r for C source file, so it can be
used to detect if a particular compiler flag works or not. This does
not check whether the object code
can be used to build a shared library, only that the compilation (not
link) succeeds.
SConf.CheckSHCXX(context), context.CheckSHCXX()
Checks whether the shared-object C++ compiler (as defined by the SHCX
X construction variable) works by
trying to compile a small source file. By default, SCons only detects
if there is a program with the
correct name, not if it is a functioning compiler. Returns a boolean
indicating success or failure.
This uses the exact same command as the one used by the object builde
r for C++ source files, so it can
be used to detect if a particular compiler flag works or not. This do
es not check whether the object
code can be used to build a shared library, only that the compilation
(not link) succeeds.
SConf.CheckTypeSize(context, type_name, [header, language, expect]), cont
ext.CheckTypeSize(type_name,
[header, language, expect])
Checks for the size of a type defined by typedef. type_name specifie s the typedef name to check for. Checks for the size of a type defined by typedef. type_name specifie s the typedef name to check for.
The optional header argument is a string that will be placed at the t op of the test file that will be The optional header argument is a string that will be placed at the t op of the test file that will be
compiled to check if the type exists; the default is empty. If the op tional expect, is supplied, it compiled to check if the type exists; the default is empty. If the op tional expect, is supplied, it
should be an integer size; CheckTypeSize will fail unless type_name i s actually that size. Returns the should be an integer size; CheckTypeSize will fail unless type_name i s actually that size. Returns the
size in bytes, or zero if the type was not found (or if the size did not match expect). size in bytes, or zero if the type was not found (or if the size did not match expect).
For example, For example,
CheckTypeSize('short', expect=2) CheckTypeSize('short', expect=2)
will return the size 2 only if short is actually two bytes. will return the size 2 only if short is actually two bytes.
SConf.CheckDeclaration(context, symbol, [includes, language]), context.Ch context.CheckCC()
eckDeclaration(symbol, [includes, Checks whether the C compiler (as defined by the $CC construction var
language]) iable) works, by trying to
compile a small source file. This provides a more rigorous check: by
default, SCons itself only
detects if there is a program with the correct name, not if it is a f
unctioning compiler. Returns a
boolean indicating success or failure.
The test program will be built with the same command line as the one
used by the Object builder for C
source files, so by setting relevant construction variables it can be
used to detect if particular
compiler flags will be accepted or rejected by the compiler.
context.CheckCXX()
Checks whether the C++ compiler (as defined by the $CXX construction
variable) works, by trying to
compile a small source file. This provides a more rigorous check: by
default, SCons itself only
detects if there is a program with the correct name, not if it is a f
unctioning compiler. Returns a
boolean indicating success or failure.
The test program will be built with the same command line as the one
used by the Object builder for
C++ source files, so by setting relevant construction variables it ca
n be used to detect if particular
compiler flags will be accepted or rejected by the compiler.
context.CheckSHCC()
Checks whether the shared-object C compiler (as defined by the $SHCC
construction variable) works by
trying to compile a small source file. This provides a more rigorous
check: by default, SCons itself
only detects if there is a program with the correct name, not if it i
s a functioning compiler. Returns
a boolean indicating success or failure.
The test program will be built with the same command line as the one
used by the SharedObject builder
for C source files, so by setting relevant construction variables it
can be used to detect if
particular compiler flags will be accepted or rejected by the compile
r. Note this does not check
whether a shared library/dll can be created.
context.CheckSHCXX()
Checks whether the shared-object C++ compiler (as defined by the $SHC
XX construction variable) works
by trying to compile a small source file. This provides a more rigoro
us check: by default, SCons
itself only detects if there is a program with the correct name, not
if it is a functioning compiler.
Returns a boolean indicating success or failure.
The test program will be built with the same command line as the one
used by the SharedObject builder
for C++ source files, so by setting relevant construction variables i
t can be used to detect if
particular compiler flags will be accepted or rejected by the compile
r. Note this does not check
whether a shared library/dll can be created.
context.CheckProg(prog_name)
Checks if prog_name exists in the path SCons will use at build time.
(context.env['ENV']['PATH']).
Returns a string containing the path to the program, or None on failu
re.
context.CheckDeclaration(symbol, [includes, language])
Checks if the specified symbol is declared. includes is a string con taining one or more #include Checks if the specified symbol is declared. includes is a string con taining one or more #include
lines that will be inserted into the program that will be run to test for the existence of the symbol. lines that will be inserted into the program that will be run to test for the existence of the symbol.
Returns a boolean indicating success or failure. Returns a boolean indicating success or failure.
SConf.Define(context, symbol, [value, comment]), context.Define(symbol, [ context.CheckMember(aggregate_member, [header, language])
value, comment]) Checks for the existence of a member of the C/C++ struct or class. a
This function does not check for anything, but defines a preprocessor ggregate_member specifies the
symbol that will be added to the struct/class and member to check for. header is a string containing
configuration header file. It is the equivalent of AC_DEFINE, and def one or more #include lines that
ines the symbol name with the will be inserted into the program that will be run to test for the ex
optional value and the optional comment comment. istence of the member. Example:
Define Examples: sconf.CheckMember('struct tm.tm_sec', '#include <time.h>')
Returns a boolean indicating success or failure.
context.Define(symbol, [value, comment])
This method does not check for anything, but rather forces the defini
tion of a preprocessor macro that
will be added to the configuration header file. name is the macro's
identifier. If value is given, it
will be be used as the macro replacement value. If value is a string
and needs to display with quotes,
the quotes need to be included, as in '"string"' If the optional comm
ent is given, it is inserted as a
comment above the macro definition (suitable comment marks will be ad
ded automatically). This is
analogous to using AC_DEFINE in Autoconf.
Examples:
env = Environment() env = Environment()
conf = Configure(env) conf = Configure(env)
# Puts the following line in the config header file: # Puts the following line in the config header file:
# #define A_SYMBOL # #define A_SYMBOL
conf.Define("A_SYMBOL") conf.Define("A_SYMBOL")
# Puts the following line in the config header file: # Puts the following line in the config header file:
# #define A_SYMBOL 1 # #define A_SYMBOL 1
conf.Define("A_SYMBOL", 1) conf.Define("A_SYMBOL", 1)
Be careful about quoting string values, though: Examples of quoting string values:
env = Environment() env = Environment()
conf = Configure(env) conf = Configure(env)
# Puts the following line in the config header file: # Puts the following line in the config header file:
# #define A_SYMBOL YA # #define A_SYMBOL YA
conf.Define("A_SYMBOL", "YA") conf.Define("A_SYMBOL", "YA")
# Puts the following line in the config header file: # Puts the following line in the config header file:
# #define A_SYMBOL "YA" # #define A_SYMBOL "YA"
conf.Define("A_SYMBOL", '"YA"') conf.Define("A_SYMBOL", '"YA"')
For comment: Example including comment:
env = Environment() env = Environment()
conf = Configure(env) conf = Configure(env)
# Puts the following lines in the config header file: # Puts the following lines in the config header file:
# /* Set to 1 if you have a symbol */ # /* Set to 1 if you have a symbol */
# #define A_SYMBOL 1 # #define A_SYMBOL 1
conf.Define("A_SYMBOL", 1, "Set to 1 if you have a symbol") conf.Define("A_SYMBOL", 1, "Set to 1 if you have a symbol")
You can define your own custom checks in addition to the predefined check You can define your own custom checks in addition to using the predefined
s. You pass a dictionary of these checks. To enable custom checks,
to the Configure function as the custom_tests argument. This dictionary m pass a dictionary to the Configure function as the custom_tests parameter
aps the names of the checks to . The dictionary maps the names
the user defined Python callables (either Python functions or class insta of the checks to the custom check callables (either a Python function or
nces implementing a __call__ an instance of a class
method). Each custom check will be called with a first argument of a Chec implementing a __call__ method). Each custom check will be called with a
kContext, instance followed by a CheckContext instance as the
the arguments, which must be supplied by the user of the check. A CheckCo first parameter followed by the remaining arguments, which must be suppli
ntext instance defines the ed by the user of the check. A
following methods: CheckContext is not the same as a configure context; rather it is an inst
ance of a class which contains a
context.Message(text) configure context (available as chk_ctx.sconf). A CheckContext provides t
Displays a message, as an indicator of progess. text will be display he following methods which custom
ed, e.g. Checking for library checks can make use of::
X.... Usually called before the check is started.
chk_ctx.Message(text)
context.Result(res) Displays text as an indicator of progess. For example: Checking for l
Displays a “result” message, as an indicator of progress. res can be ibrary X.... Usually called
either an integer or a string. before the check is started.
If an integer, displays yes (if res evaluates True) or no (if res eva
luates False). If a string, it is chk_ctx.Result(res)
displayed as-is. Usually called after the check has completed. Displays a result message as an indicator of progress. If res is an i
nteger, displays yes if res
context.TryCompile(text, extension='') evaluates true or no if false. If res is a string, it is displayed as
Checks if a file with the specified extension (e.g. '.c') containing -is. Usually called after the
text can be compiled using the check has completed.
environment's Object builder. Returns a boolean indicating success or
failure. chk_ctx.TryCompile(text, extension='')
Checks if a file containing text and given the specified extension (e
context.TryLink(text, extension='') .g. '.c') can be compiled to an
Checks, if a file with the specified extension (e.g. '.c') containing object file using the environment's Object builder. Returns a boolean
text can be compiled using the indicating success or failure.
environment's Program builder. Returns a boolean indicating success o
r failure. chk_ctx.TryLink(text, extension='')
Checks if a file containing text and given the specified extension (e
context.TryRun(text, extension='') .g. '.c') can be compiled to an
Checks if a file with the specified extension (e.g. '.c') containing executable program using the environment's Program builder. Returns a
text can be compiled using the boolean indicating success or
environment's Program builder. On success, the program is run. If the failure.
program executes successfully
(that is, its return status is 0), a tuple (1, outputStr) is returned chk_ctx.TryRun(text, extension='')
, where outputStr is the standard Checks if a file containing text and given the specified extension (e
output of the program. If the program fails execution (its return sta .g. '.c') can be compiled to an
tus is non-zero), then (0, '') is excutable program using the environment's Program builder and subsequ
returned. ently executed. Execution is only
attempted if the build succeeds. If the program executes successfully
context.TryAction(action, [text, extension='']) (that is, its return status is
Checks if the specified action with an optional source file (contents 0), a tuple (True, outputStr) is returned, where outputStr is the sta
text, extension extension) can ndard output of the program. If
be executed. action may be anything which can be converted to a scon the program fails execution (its return status is non-zero), then (Fa
s Action. On success, (1, lse, '') is returned.
outputStr) is returned, where outputStr is the content of the target
file. On failure (0, '') is chk_ctx.TryAction(action, [text, extension=''])
returned. Checks if the specified action with an optional source file (contents
text, given extension extension)
can be executed. action may be anything which can be converted to an
Action Object. On success, a
tuple (True, outputStr) is returned, where outputStr is the content o
f the target file. On failure
(False, '') is returned.
context.TryBuild(builder[, text, extension='']) chk_ctx.TryBuild(builder, [text, extension=''])
Low level implementation for testing specific builds; the methods abo ve are based on this method. Low level implementation for testing specific builds; the methods abo ve are based on this method.
Given the Builder instance builder and the optional text of a source file with optional extension, Given the Builder instance builder and the optional text of a source file with optional extension,
returns a boolean indicating success or failure. In addition, context .lastTarget is set to the build returns a boolean indicating success or failure. In addition, chk_ctx .lastTarget is set to the build
target node if the build was successful. target node if the build was successful.
Example of implementing and using custom tests: Example of implementing and using custom tests:
def CheckQt(context, qtdir): def CheckQt(chk_ctx, qtdir):
context.Message( 'Checking for qt ...' ) chk_ctx.Message('Checking for qt ...')
lastLIBS = context.env['LIBS'] lastLIBS = chk_ctx.env['LIBS']
lastLIBPATH = context.env['LIBPATH'] lastLIBPATH = chk_ctx.env['LIBPATH']
lastCPPPATH= context.env['CPPPATH'] lastCPPPATH = chk_ctx.env['CPPPATH']
context.env.Append(LIBS='qt', LIBPATH=qtdir + '/lib', CPPPATH=qtd chk_ctx.env.Append(LIBS='qt', LIBPATH=qtdir + '/lib', CPPPATH=qtd
ir + '/include') ir + '/include')
ret = context.TryLink(""" ret = chk_ctx.TryLink(
"""\
#include <qapp.h> #include <qapp.h>
int main(int argc, char **argv) { int main(int argc, char **argv) {
QApplication qapp(argc, argv); QApplication qapp(argc, argv);
return 0; return 0;
} }
""") """
)
if not ret: if not ret:
context.env.Replace(LIBS=lastLIBS, LIBPATH=lastLIBPATH, CPPPA chkctx.env.Replace(LIBS=lastLIBS, LIBPATH=lastLIBPATH, CPPPAT
TH=lastCPPPATH) H=lastCPPPATH)
context.Result( ret ) chkctx.Result(ret)
return ret return ret
env = Environment() env = Environment()
conf = Configure(env, custom_tests={'CheckQt': CheckQt}) conf = Configure(env, custom_tests={'CheckQt': CheckQt})
if not conf.CheckQt('/usr/lib/qt'): if not conf.CheckQt('/usr/lib/qt'):
print('We really need qt!') print('We really need qt!')
Exit(1) Exit(1)
env = conf.Finish() env = conf.Finish()
Command-Line Construction Variables Command-Line Construction Variables
skipping to change at line 9715 skipping to change at line 10324
help="where the root of Qt is installed", help="where the root of Qt is installed",
default=qtdir), default=qtdir),
PathVariable( PathVariable(
"foopath", "foopath",
help="where the foo library is installed", help="where the foo library is installed",
default=foopath, default=foopath,
validator=PathVariable.PathIsDir, validator=PathVariable.PathIsDir,
), ),
) )
File and Directory Nodes Node Objects
The File and Dir functions/methods return File and Directory Nodes, respe SCons represents objects that are the sources or targets of build operati
ctively. Such nodes are Python ons as Nodes, which are internal
objects with several user-visible attributes and methods that are often u data structures. There are a number of user-visible types of nodes: File
seful to access in SConscript Nodes, Directory Nodes, Value
files: Nodes and Alias Nodes. Some of the node types have public attributes and
methods, described below. Each of
n.path the node types has a global function and a matching environment method to
The build path of the given file or directory. This path is relative create instances: File, Dir,
to the top-level directory (where Value and Alias.
the SConstruct file is found). The build path is the same as the sour
ce path if variant_dir is not Filesystem Nodes
being used. The File and Dir functions/methods return File and Directory Nodes, r
espectively. File and Directory
Nodes (collectively, Filesystem Nodes) represent build components tha
t correspond to an entry in the
computer's filesystem, whether or not such an entry exists at the tim
e the Node is created. You do not
usually need to explicitly create filesystem Nodes, since when you su
pply a string as a target or
source of a Builder, SCons will create the Nodes as needed to populat
e the dependency graph. Builders
return the target Node(s) in the form of a list, which you can then m
ake use of. However, since
filesystem Nodes have some useful public attributes and methods that
you can use in SConscript files,
it is sometimes appropriate to create them manually, outside the regu
lar context of a Builder call.
The following attributes provide information about a Node:
node.path
The build path of the given file or directory. This path is relat
ive to the top-level directory
(where the SConstruct file is found). The build path is the same
as the source path if variant_dir
is not being used.
node.abspath
The absolute build path of the given file or directory.
node.relpath
The build path of the given file or directory relative to the roo
t SConstruct file's directory.
node.srcnode()
The srcnode method returns another File or Directory Node represe
nting the source path of the
given File or Directory Node.
Examples:
n.abspath # Get the current build dir's path, relative to top.
The absolute build path of the given file or directory. Dir('.').path
n.relpath # Current dir's absolute path
The build path of the given file or directory relative to the root SC Dir('.').abspath
onstruct file's directory.
n.srcnode() # Current dir's path relative to the root SConstruct file's direc
The srcnode method returns another File or Directory Node representin tory
g the source path of the given Dir('.').relpath
File or Directory Node.
For example: # Next line is always '.', because it is the top dir's path relat
ive to itself.
Dir('#.').path
# Get the current build dir's path, relative to top. # Source path of the given source file.
Dir('.').path File('foo.c').srcnode().path
# Current dir's absolute path
Dir('.').abspath
# Current dir's path relative to the root SConstruct file's directory
Dir('.').relpath
# Next line is always '.', because it is the top dir's path relative
to itself.
Dir('#.').path
File('foo.c').srcnode().path # source path of the given source file
.
# Builders also return File objects: # Builders return lists of File objects:
foo = env.Program('foo.c') foo = env.Program('foo.c')
print("foo will be built in", foo.path) print("foo will be built in", foo[0].path)
File and Directory Node objects have methods to create File and Directory Filesystem Node objects have methods to create new File and Directory
Nodes relative to the original Nodes relative to the original
Node. Node. There are also times when you may need to refer to an entry in
a filesystem without knowing in
advance whether it's a file or a directory. For those situations, the
re is an Entry method of
filesystem node objects, which returns a Node that can represent eith
er a file or a directory.
If the object is a Directory Node, these methods will place the the new N If the original Node is a Directory Node, these methods will place th
ode within the directory the Node e new Node within the directory
represents: the original Node represents:
d.Dir(name) node.Dir(name)
Returns a directory Node for a subdirectory of d named name. Returns a directory Node name which is a subdirectory of the dire
ctory represented by node.
d.File(name) node.File(name)
Returns a file Node for a file within d named name. Returns a file Node name in the directory represented by node.
d.Entry(name) node.Entry(name)
Returns an unresolved Node within d named name. Returns an unresolved Node name in the directory represented by n
ode.
If the object is a File Node, these methods will place the the new Node i If the original Node is a File Node, these methods will place the the
n the same directory as the one new Node in the same directory
the Node represents: as the one the original Node represents:
f.Dir(name) node.Dir(name)
Returns a directory named name within the parent directory of f. Returns a Node name for a directory in the parent directory of th
e file represented by node.
f.File(name) node.File(name)
Returns a file named name within the parent directory of f. Returns a Node name for a file in the parent directory of the fil
e represented by node.
f.Entry(name) node.Entry(name)
Returns an unresolved Node named name within the parent directory of Returns an unresolved Node name in the parent directory of the fi
f. le represented by node.
For example: For example:
# Get a Node for a file within a directory # Get a Node for a file within a directory
incl = Dir('include') incl = Dir('include')
f = incl.File('header.h') f = incl.File('header.h')
# Get a Node for a subdirectory within a directory # Get a Node for a subdirectory within a directory
dist = Dir('project-3.2.1') dist = Dir('project-3.2.1')
src = dist.Dir('src') src = dist.Dir('src')
# Get a Node for a file in the same directory # Get a Node for a file in the same directory
cfile = File('sample.c') cfile = File('sample.c')
hfile = cfile.File('sample.h') hfile = cfile.File('sample.h')
# Combined example # Combined example
docs = Dir('docs') docs = Dir('docs')
html = docs.Dir('html') html = docs.Dir('html')
index = html.File('index.html') index = html.File('index.html')
css = index.File('app.css') css = index.File('app.css')
Value and Alias Nodes
SCons provides two other Node types to represent object that will not
have an equivalent filesystem
entry. Such Nodes always need to be created explicitly.
The Alias method returns an Alias Node. Aliases are virtual objects -
they will not themselves result
in physical objects being constructed, but are entered into the depen
dency graph related to their
sources. An alias is checked for up to date by checking if its source
s are up to date. An alias is
built by making sure its sources have been built, and if any building
took place, applying any Actions
that are defined as part of the alias.
An Alias call creates an entry in the alias namespace, which is used
for disambiguation. If an alias
source has a string valued name, it will be resolved to a filesystem
entry Node, unless it is found in
the alias namespace, in which case it it resolved to the matching ali
as Node. As a result, the order
of Alias calls is significant. An alias can refer to another alias, b
ut only if the other alias has
previously been created.
The Value method returns a Value Node. Value nodes are often used for
generated data that will not
have any corresponding filesystem entry, but will be used to determin
e whether a build target is out
of date, or to include as part of a build Action. Common examples are
timestamp strings, revision
control version strings and other run-time generated strings.
A Value Node can also be the target of a builder.
EXTENDING SCONS EXTENDING SCONS
SCons is designed to be extensible through provided facilities, so changi
ng the code of SCons itself is
only rarely needed to customize its behavior. A number of the main operat
ions use callable objects which
can be supplemented by writing your own. Builders, Scanners and Tools eac
h use a kind of plugin system,
allowing you to easily drop in new ones. Information about creating Build
er Objects and Scanner Objects
appear in the following sections. The instructions SCons actually uses to
construct things are called
Actions, and it is easy to create Action Objects and hand them to the obj
ects that need to know about
those actions (besides Builders, see AddPostAction, AddPreAction and Alia
s for some examples of other
places that take Actions). Action Objects are also described below. Addi
ng new Tool modules is described
in Tool Modules
Builder Objects Builder Objects
scons can be extended to build different types of targets by adding new B uilder objects to a construction scons can be extended to build different types of targets by adding new B uilder objects to a construction
environment. In general, you should only need to add a new Builder objec t when you want to build a new environment. In general, you should only need to add a new Builder objec t when you want to build a new
type of file or other external target. For output file types scons alread y knows about, you can usually type of file or other external target. For output file types scons alread y knows about, you can usually
modify the behavior of premade Builders such as Program, Object or Librar y by changing the construction modify the behavior of premade Builders such as Program, Object or Librar y by changing the construction
variables they use ($CC, $LINK, etc.). In this manner you can, for exampl e, change the compiler to use, variables they use ($CC, $LINK, etc.). In this manner you can, for exampl e, change the compiler to use,
which is simpler and less error-prone than writing a new builder. The doc umentation for each Builder lists which is simpler and less error-prone than writing a new builder. The doc umentation for each Builder lists
which construction variables it uses. which construction variables it uses.
Builder objects are created using the Builder factory function. Once crea ted, a builder is added to an Builder objects are created using the Builder factory function. Once crea ted, a builder is added to an
environment by entering it in the $BUILDERS dictionary in that environmen t (some of the examples in this environment by entering it in the $BUILDERS dictionary in that environmen t (some of the examples in this
section illustrate that). section illustrate this). Doing so automatically triggers SCons to add a
method with the name of the
builder to the environment.
The Builder function accepts the following keyword arguments: The Builder function accepts the following keyword arguments:
action action
The command used to build the target from the source. action may be a string representing a template The command used to build the target from the source. action may be a string representing a template
command line to execute, a list of strings representing the command t o execute with its arguments command line to execute, a list of strings representing the command t o execute with its arguments
(suitable for enclosing white space in an argument), a dictionary map ping source file name suffixes to (suitable for enclosing white space in an argument), a dictionary map ping source file name suffixes to
any combination of command line strings (if the builder should accept multiple source file any combination of command line strings (if the builder should accept multiple source file
extensions), a Python function, an Action object (see the section cal extensions), a Python function, an Action object (see Action Objects)
led “Action Objects”) or a list or a list of any of the above.
of any of the above.
An action function must accept three arguments: source, target and en v. source is a list of source An action function must accept three arguments: source, target and en v. source is a list of source
nodes; target is a list of target nodes; env is the construction envi ronment to use for context. nodes; target is a list of target nodes; env is the construction envi ronment to use for context.
The action and generator arguments must not both be used for the same Builder. The action and generator arguments must not both be used for the same Builder.
prefix prefix
The prefix to prepend to the target file name. prefix may be a strin g, a function (or other callable) The prefix to prepend to the target file name. prefix may be a strin g, a function (or other callable)
that takes two arguments (a construction environment and a list of so urces) and returns a prefix that takes two arguments (a construction environment and a list of so urces) and returns a prefix
string, or a dictionary specifying a mapping from a specific source s uffix (of the first source string, or a dictionary specifying a mapping from a specific source s uffix (of the first source
skipping to change at line 9952 skipping to change at line 10615
A function passed as emitter must accept three arguments: source, tar get and env. source is a list of A function passed as emitter must accept three arguments: source, tar get and env. source is a list of
source nodes, target is a list of target nodes, env is the constructi on environment to use for source nodes, target is a list of target nodes, env is the constructi on environment to use for
context. context.
An emitter must return a tuple containing two lists, the list of targ ets to be built by this builder, An emitter must return a tuple containing two lists, the list of targ ets to be built by this builder,
and the list of sources for this builder. and the list of sources for this builder.
Example: Example:
def e(target, source, env): def e(target, source, env):
return (target + ['foo.foo'], source + ['foo.src']) return target + ['foo.foo'], source + ['foo.src']
# Simple association of an emitter function with a Builder. # Simple association of an emitter function with a Builder.
b = Builder("my_build < $TARGET > $SOURCE", b = Builder("my_build < $TARGET > $SOURCE", emitter=e)
emitter = e)
def e2(target, source, env): def e2(target, source, env):
return (target + ['bar.foo'], source + ['bar.src']) return target + ['bar.foo'], source + ['bar.src']
# Simple association of a list of emitter functions with a Builde r. # Simple association of a list of emitter functions with a Builde r.
b = Builder("my_build < $TARGET > $SOURCE", b = Builder("my_build < $TARGET > $SOURCE", emitter=[e, e2])
emitter = [e, e2])
# Calling an emitter function through a construction variable. # Calling an emitter function through a construction variable.
env = Environment(MY_EMITTER=e) env = Environment(MY_EMITTER=e)
b = Builder("my_build < $TARGET > $SOURCE", b = Builder("my_build < $TARGET > $SOURCE", emitter='$MY_EMITTER'
emitter='$MY_EMITTER') )
# Calling a list of emitter functions through a construction vari able. # Calling a list of emitter functions through a construction vari able.
env = Environment(EMITTER_LIST=[e, e2]) env = Environment(EMITTER_LIST=[e, e2])
b = Builder("my_build < $TARGET > $SOURCE", b = Builder("my_build < $TARGET > $SOURCE", emitter='$EMITTER_LIS
emitter='$EMITTER_LIST') T')
# Associating multiple emitters with different file # Associating multiple emitters with different file
# suffixes using a dictionary. # suffixes using a dictionary.
def e_suf1(target, source, env): def e_suf1(target, source, env):
return (target + ['another_target_file'], source) return target + ['another_target_file'], source
def e_suf2(target, source, env): def e_suf2(target, source, env):
return (target, source + ['another_source_file']) return target, source + ['another_source_file']
b = Builder("my_build < $TARGET > $SOURCE",
emitter={'.suf1' : e_suf1, b = Builder(
'.suf2' : e_suf2}) action="my_build < $TARGET > $SOURCE",
emitter={'.suf1': e_suf1, '.suf2': e_suf2}
)
multi multi
Specifies whether this builder is allowed to be called multiple times for the same target file(s). The Specifies whether this builder is allowed to be called multiple times for the same target file(s). The
default is False, which means the builder can not be called multiple times for the same target default is False, which means the builder can not be called multiple times for the same target
file(s). Calling a builder multiple times for the same target simply adds additional source files to file(s). Calling a builder multiple times for the same target simply adds additional source files to
the target; it is not allowed to change the environment associated wi th the target, specify additional the target; it is not allowed to change the environment associated wi th the target, specify additional
environment overrides, or associate a different builder with the targ et. environment overrides, or associate a different builder with the targ et.
env env
A construction environment that can be used to fetch source code usin g this Builder. (Note that this A construction environment that can be used to fetch source code usin g this Builder. (Note that this
environment is not used for normal builds of normal target files, whi ch use the environment that was environment is not used for normal builds of normal target files, whi ch use the environment that was
used to call the Builder for the target file.) used to call the Builder for the target file.)
generator generator
A function that returns a list of actions that will be executed to bu ild the target(s) from the A function that returns a list of actions that will be executed to bu ild the target(s) from the
source(s). The returned action(s) may be an Action object, or anythin g that can be converted into an source(s). The returned action(s) may be an Action object, or anythin g that can be converted into an
Action object (see the next section). Action object (see the next section).
A function passed as generator must accept four arguments: source, ta rget, env and for_signature. A function passed as generator must accept four arguments: source, ta rget, env and for_signature.
source is a list of source nodes, target is a list of target nodes, e nv is the construction source is a list of source nodes, target is a list of target nodes, e nv is the construction
environment to use for context, for_signature is a Boolean value that environment to use for context, and for_signature is a Boolean value
specifies whether the generator that tells the function if it is
is being called for generating a build signature (as opposed to actua being called for the purpose of generating a build signature (as oppo
lly executing the command). sed to actually executing the
command). Since the build signature is used for rebuild determination
, the function should omit those
elements that do not affect whether a rebuild should be triggered if
for_signature is true.
Example: Example:
def g(source, target, env, for_signature): def g(source, target, env, for_signature):
return [["gcc", "-c", "-o"] + target + source] return [["gcc", "-c", "-o"] + target + source]
b = Builder(generator=g) b = Builder(generator=g)
The generator and action arguments must not both be used for the same Builder. The generator and action arguments must not both be used for the same Builder.
skipping to change at line 10078 skipping to change at line 10742
Warning Warning
Python only keeps one current directory location even if there ar e multiple threads. This means Python only keeps one current directory location even if there ar e multiple threads. This means
that use of the chdir argument will not work with the SCons -j op tion, because individual worker that use of the chdir argument will not work with the SCons -j op tion, because individual worker
threads spawned by SCons interfere with each other when they star t changing directory. threads spawned by SCons interfere with each other when they star t changing directory.
Any additional keyword arguments supplied when a Builder object is create d (that is, when the Builder Any additional keyword arguments supplied when a Builder object is create d (that is, when the Builder
function is called) will be set in the executing construction environment when the Builder object is function is called) will be set in the executing construction environment when the Builder object is
called. The canonical example here would be to set a construction variabl e to the repository of a source called. The canonical example here would be to set a construction variabl e to the repository of a source
code system. code system.
Any additional keyword arguments supplied when a Builder object is called Any such keyword arguments supplied when a Builder object is called will
will only be associated with the only be associated with the
target created by that particular Builder call (and any other files built target created by that particular Builder call (and any other files built
as a result of the call). as a result of the call). These
extra keyword arguments are passed to the following functions: command ge
These extra keyword arguments are passed to the following functions: comm nerator functions, function
and generator functions, function
Actions, and emitter functions. Actions, and emitter functions.
Action Objects Action Objects
The Builder factory function will turn its action keyword argument into a n appropriate internal Action The Builder factory function will turn its action keyword argument into a n appropriate internal Action
object, as will the Command function. You can also explicitly create Acti on objects for passing to object, as will the Command function. You can also explicitly create Acti on objects for passing to
Builder, or other functions that take actions as arguments, by calling th e Action factory function. This Builder, or other functions that take actions as arguments, by calling th e Action factory function. This
may more efficient when multiple Builder objects need to do the same thin g rather than letting each of may more efficient when multiple Builder objects need to do the same thin g rather than letting each of
those Builder objects create a separate Action object. It also allows mor e flexible configuration of an those Builder objects create a separate Action object. It also allows mor e flexible configuration of an
Action object. For example, to control the message printed when the actio n is taken you need to create the Action object. For example, to control the message printed when the actio n is taken you need to create the
action object using Action. action object using Action.
The Action factory function returns an appropriate object for the action represented by the type of the The Action factory function returns an appropriate object for the action represented by the type of the
action argument (the first positional parmeter): action argument (the first positional parameter):
· If action is already an Action object, the object is simply returned. · If action is already an Action object, the object is simply returned.
· If action is a string, a command-line Action is returned. If such a s tring begins with @, the command · If action is a string, a command-line Action is returned. If such a s tring begins with @, the command
line is not printed. If the string begins with hyphen (-), the exit s tatus from the specified command line is not printed. If the string begins with hyphen (-), the exit s tatus from the specified command
is ignored, allowing execution to continue even if the command report s failure: is ignored, allowing execution to continue even if the command report s failure:
Action('$CC -c -o $TARGET $SOURCES') Action('$CC -c -o $TARGET $SOURCES')
# Doesn't print the line being executed. # Doesn't print the line being executed.
skipping to change at line 10151 skipping to change at line 10814
The environment method form env.Action will expand construction variables in any argument strings, The environment method form env.Action will expand construction variables in any argument strings,
including action, at the time it is called, using the construction variab les in the construction including action, at the time it is called, using the construction variab les in the construction
environment through which it was called. The global function form Action delays variable expansion until environment through which it was called. The global function form Action delays variable expansion until
the Action object is actually used. the Action object is actually used.
The optional second argument to Action is used to control the output whic h is printed when the Action is The optional second argument to Action is used to control the output whic h is printed when the Action is
actually performed. If this parameter is omitted, or if the value is an e mpty string, a default output actually performed. If this parameter is omitted, or if the value is an e mpty string, a default output
depending on the type of the action is used. For example, a command-line action will print the executed depending on the type of the action is used. For example, a command-line action will print the executed
command. The following argument types are accepted: command. The following argument types are accepted:
· If output is a string, substitution is performed on the string before · If the second argument is a string, or if the cmdstr keyword argument
it is printed. The string is supplied, the string defines
typically contains variables, notably $TARGET(S) and $SOURCE(S), or c what is printed. Substitution is performed on the string before it is
onsists of just a single printed. The string typically
variable, which is optionally defined somewhere else. SCons itself h contains substitutable variables, notably $TARGET(S) and $SOURCE(S),
eavily uses the latter variant. or consists of just a single
variable which is optionally defined somewhere else. SCons itself he
· If output is a function, the function will be called to obtain a stri avily uses the latter variant.
ng describing the action being
executed. The function must accept three keyword arguments: target, s · If the second argument is a function, or if the strfunction keyword a
ource and env, with the same rgument is supplied, the function
interpretation as for a callable action argument above. will be called to obtain the string to be printed when the action is
performed. The function must
· If outputis None, output is suppressed entirely. accept three keyword arguments: target, source and env, with the same
interpretation as for a callable
Instead of using a positional argument, the cmdstr keyword argument may b action argument above. The function is responsible for handling any r
e used to specify the output equired substitutions.
string, or the strfunction keyword argument may be used to specify a func
tion to return the output string. · If the second argument is None, or if cmdstr=None is supplied, output
cmdstr=None suppresses output entirely. is suppressed entirely.
The cmdstr and strfunction keyword arguments may not both be supplied in
a single call to Action
Printing of action strings is affected by the setting of $PRINT_CMD_LINE_
FUNC.
Examples: Examples:
def build_it(target, source, env): def build_it(target, source, env):
# build the target from the source # build the target from the source
return 0 return 0
def string_it(target, source, env): def string_it(target, source, env):
return "building '%s' from '%s'" % (target[0], source[0]) return "building '%s' from '%s'" % (target[0], source[0])
skipping to change at line 10186 skipping to change at line 10851
s = Action(build_it, "building '$TARGET' from '$SOURCE'") s = Action(build_it, "building '$TARGET' from '$SOURCE'")
# Alternatively, use a keyword argument. # Alternatively, use a keyword argument.
f = Action(build_it, strfunction=string_it) f = Action(build_it, strfunction=string_it)
s = Action(build_it, cmdstr="building '$TARGET' from '$SOURCE'") s = Action(build_it, cmdstr="building '$TARGET' from '$SOURCE'")
# You can provide a configurable variable. # You can provide a configurable variable.
l = Action(build_it, '$STRINGIT') l = Action(build_it, '$STRINGIT')
Any additional positional arguments, if present, may either be constructi on variables or lists of Any additional positional arguments, if present, may either be constructi on variables or lists of
construction variables whose values will be included in the signature of construction variables whose values will be included in the signature of
the Action when deciding whether the Action (the build signature)
a target should be rebuilt because the action changed. Such variables may when deciding whether a target should be rebuilt because the action chang
also be specified using the ed. Such variables may also be
varlist keyword parameter; both positional and keyword forms may be prese specified using the varlist keyword parameter; both positional and keywor
nt, and will be combined. This is d forms may be present, and will
necessary whenever you want a target to be rebuilt when a specific constr be combined. This is necessary whenever you want a target to be rebuilt w
uction variable changes. This is hen a specific construction
not often needed for a string action, as the expanded variables will norm variable changes. This is not often needed for a string action, as the ex
ally be part of the command line, panded variables will normally be
but may be needed if a Python function action uses the value of a constru part of the command line, but may be needed if a Python function action u
ction variable when generating ses the value of a construction
the command line. variable when generating the command line.
def build_it(target, source, env): def build_it(target, source, env):
# build the target from the 'XXX' construction variable # build the target from the 'XXX' construction variable
with open(target[0], 'w') as f: with open(target[0], 'w') as f:
f.write(env['XXX']) f.write(env['XXX'])
return 0 return 0
# Use positional arguments. # Use positional arguments.
a = Action(build_it, '$STRINGIT', ['XXX']) a = Action(build_it, '$STRINGIT', ['XXX'])
skipping to change at line 10274 skipping to change at line 10939
def batch_key(action, env, target, source): def batch_key(action, env, target, source):
tdir = target[0].dir tdir = target[0].dir
if tdir.name == 'special': if tdir.name == 'special':
# Don't batch-build any target # Don't batch-build any target
# in the special/ subdirectory. # in the special/ subdirectory.
return None return None
return (id(action), id(env), tdir) return (id(action), id(env), tdir)
a = Action('build $CHANGED_SOURCES', batch_key=batch_key) a = Action('build $CHANGED_SOURCES', batch_key=batch_key)
Miscellaneous Action Functions Miscellaneous Action Functions
SCons supplies Action functions that arrange for various common file and SCons supplies Action functions that arrange for various common file
directory manipulations to be and directory manipulations to be
performed. These are similar in concept to "tasks" in the Ant build tool, performed. These are similar in concept to "tasks" in the Ant build t
although the implementation is ool, although the implementation
slightly different. These functions do not actually perform the specified is slightly different. These functions do not actually perform the sp
action at the time the function ecified action at the time the
is called, but rather are factory functions which return an Action object function is called, but rather are factory functions which return an
that can be executed at the Action object that can be
appropriate time. executed at the appropriate time.
There are two natural ways that these Action Functions are intended to be used. There are two natural ways that these Action Functions are intended t o be used.
First, if you need to perform the action at the time the SConscript file First, if you need to perform the action at the time the SConscript f
is being read, you can use the ile is being read, you can use
Execute global function: the Execute global function:
Execute(Touch('file')) Execute(Touch('file'))
Second, you can use these functions to supply Actions in a list for use b Second, you can use these functions to supply Actions in a list for u
y the env.Command method. This se by the env.Command method.
can allow you to perform more complicated sequences of file manipulation This can allow you to perform more complicated sequences of file mani
without relying on pulation without relying on
platform-specific external commands: platform-specific external commands:
env = Environment(TMPBUILD='/tmp/builddir') env = Environment(TMPBUILD='/tmp/builddir')
env.Command( env.Command(
target='foo.out', target='foo.out',
source='foo.in', source='foo.in',
action=[ action=[
Mkdir('$TMPBUILD'), Mkdir('$TMPBUILD'),
Copy('$TMPBUILD', '${SOURCE.dir}'), Copy('$TMPBUILD', '${SOURCE.dir}'),
"cd $TMPBUILD && make", "cd $TMPBUILD && make",
Delete('$TMPBUILD'), Delete('$TMPBUILD'),
], ],
) )
Chmod(dest, mode) Chmod(dest, mode)
Returns an Action object that changes the permissions on the specifie Returns an Action object that changes the permissions on the spec
d dest file or directory to the ified dest file or directory to
specified mode which can be octal or string, similar to the bash comm the specified mode which can be octal or string, similar to the b
and. Examples: ash command. Examples:
Execute(Chmod('file', 0o755)) Execute(Chmod('file', 0o755))
env.Command('foo.out', 'foo.in', env.Command('foo.out', 'foo.in',
[Copy('$TARGET', '$SOURCE'), [Copy('$TARGET', '$SOURCE'),
Chmod('$TARGET', 0o755)]) Chmod('$TARGET', 0o755)])
Execute(Chmod('file', "ugo+w")) Execute(Chmod('file', "ugo+w"))
env.Command('foo.out', 'foo.in', env.Command('foo.out', 'foo.in',
[Copy('$TARGET', '$SOURCE'), [Copy('$TARGET', '$SOURCE'),
Chmod('$TARGET', "ugo+w")]) Chmod('$TARGET', "ugo+w")])
The behavior of Chmod is limited on Windows, see the notes in the Pyt The behavior of Chmod is limited on Windows, see the notes in the
hon documentation for os.chmod, Python documentation for
which is the underlying function. os.chmod, which is the underlying function.
Copy(dest, src) Copy(dest, src)
Returns an Action object that will copy the src source file or direct Returns an Action object that will copy the src source file or di
ory to the dest destination file rectory to the dest destination
or directory. Examples: file or directory. Examples:
Execute(Copy('foo.output', 'foo.input')) Execute(Copy('foo.output', 'foo.input'))
env.Command('bar.out', 'bar.in', Copy('$TARGET', '$SOURCE')) env.Command('bar.out', 'bar.in', Copy('$TARGET', '$SOURCE'))
Delete(entry, [must_exist]) Delete(entry, [must_exist])
Returns an Action that deletes the specified entry, which may be a fi Returns an Action that deletes the specified entry, which may be
le or a directory tree. If a a file or a directory tree. If a
directory is specified, the entire directory tree will be removed. If directory is specified, the entire directory tree will be removed
the must_exist flag is set to a . If the must_exist flag is set
true value, then a Python error will be raised if the specified entry to a true value, then a Python error will be raised if the specif
does not exist; the default is ied entry does not exist; the
false, that is, the Action will silently do nothing if the entry does default is false, that is, the Action will silently do nothing if
not exist. Examples: the entry does not exist.
Examples:
Execute(Delete('/tmp/buildroot')) Execute(Delete('/tmp/buildroot'))
env.Command( env.Command(
'foo.out', 'foo.out',
'foo.in', 'foo.in',
action=[ action=[
Delete('${TARGET.dir}'), Delete('${TARGET.dir}'),
MyBuildAction, MyBuildAction,
], ],
) )
Execute(Delete('file_that_must_exist', must_exist=True)) Execute(Delete('file_that_must_exist', must_exist=True))
Mkdir(name) Mkdir(name)
Returns an Action that creates the directory name and all needed inte Returns an Action that creates the directory name and all needed
rmediate directories. name may intermediate directories. name
also be a list of directories to create. Examples: may also be a list of directories to create. Examples:
Execute(Mkdir('/tmp/outputdir'))
env.Command(
'foo.out',
'foo.in',
action=[
Mkdir('/tmp/builddir'),
Copy('/tmp/builddir/foo.in', '$SOURCE'),
"cd /tmp/builddir && make",
Copy('$TARGET', '/tmp/builddir/foo.out'),
],
)
Execute(Mkdir('/tmp/outputdir')) Move(dest, src)
Returns an Action that moves the specified src file or directory
to the specified dest file or
directory. Examples:
Execute(Move('file.destination', 'file.source'))
env.Command(
'output_file',
'input_file',
action=[MyBuildAction, Move('$TARGET', 'file_created_by_M
yBuildAction')],
)
env.Command( Touch(file)
'foo.out', Returns an Action that updates the modification time on the speci
'foo.in', fied file. Examples:
action=[
Mkdir('/tmp/builddir'),
Copy('/tmp/builddir/foo.in', '$SOURCE'),
"cd /tmp/builddir && make",
Copy('$TARGET', '/tmp/builddir/foo.out'),
],
)
Move(dest, src) Execute(Touch('file_to_be_touched'))
Returns an Action that moves the specified src file or directory to t
he specified dest file or
directory. Examples:
Execute(Move('file.destination', 'file.source')) env.Command('marker', 'input_file', action=[MyBuildAction, To uch('$TARGET')])
env.Command( Variable Substitution
'output_file', Before executing a command, scons performs parameter expansion (subst
'input_file', itution) on the string that makes
action=[MyBuildAction, Move('$TARGET', 'file_created_by_MyBui up the action part of the builder. The format of a substitutable para
ldAction')], meter is ${expression}. If
) expression refers to a variable, the braces in ${expression} can be o
mitted unless the variable name
is immediately followed by a character that could either be interpret
ed as part of the name, or is
Python syntax such as [ (for indexing/slicing) or . (for attribute a
ccess - see Special Attributes
below).
Touch(file) If expression refers to a construction variable, it is replaced with
Returns an Action that updates the modification time on the specified the value of that variable in the
file. Examples: construction environment at the time of execution. If expression look
s like a variable name but is not
defined in the construction environment it is replaced with an empty
string. If expression refers to
one of the Special Variables (see below) the corresponding value of t
he variable is substituted.
expression may also be a Python expression to be evaluated. See Pytho
n Code Substitution below for a
description.
Execute(Touch('file_to_be_touched')) SCons uses the following rules when converting construction variables into command line strings:
env.Command('marker', 'input_file', action=[MyBuildAction, Touch( '$TARGET')]) · If the value is a string it is interpreted as space delimited com mand line arguments.
Variable Substitution · If the value is a list it is interpreted as a list of command lin
Before executing a command, scons performs variable substitution on the s e arguments. Each element of the
tring that makes up the action list is converted to a string.
part of the builder. Variables to be interpolated are indicated in the st
ring with a leading $, to
distinguish them from plain text which is not to be substituted. The name
may be surrounded by curly
braces (${}) to separate the name from surrounding characters if necessar
y. Curly braces are required when
you use Python list subscripting/slicing notation on a variable to select
one or more items from a list,
or access a variable's special attributes, or use Python expression subst
itution.
Besides regular construction variables, scons provides the following spec · Anything that is not a list or string is converted to a string an
ial variables for use in d interpreted as a single command
expanding commands: line argument.
$CHANGED_SOURCES · Newline characters (\n) delimit lines. The newline parsing is don
The file names of all sources of the build command that have changed e after all other parsing, so it
since the target was last built. is not possible for arguments (e.g. file names) to contain embedd
ed newline characters.
$CHANGED_TARGETS · For a literal $ use $$. For example, $$FOO will be left in the fi
The file names of all targets that would be built from sources that h nal string as $FOO.
ave changed since the target was
last built.
$SOURCE When a build action is executed, a hash of the command line is saved,
The file name of the source of the build command, or the file name of together with other information
the first source if multiple about the target(s) built by the action, for future use in rebuild de
sources are being built. termination. This is called the
build signature (or build action signature). The escape sequence $( s
ubexpression $) may be used to
indicate parts of a command line that may change without causing a re
build--that is, which are not to
be included when calculating the build signature. All text from $( up
to and including the matching $)
will be removed from the command line before it is added to the build
signature while only the $( and
$) will be removed before the command is executed. For example, the c
ommand line string:
$SOURCES "echo Last build occurred $( $TODAY $). > $TARGET"
The file names of the sources of the build command.
$TARGET would execute the command:
The file name of the target being built, or the file name of the firs
t target if multiple targets are
being built.
$TARGETS echo Last build occurred $TODAY. > $TARGET
The file names of all targets being built.
$UNCHANGED_SOURCES but the build signature added to any target files would be computed f
The file names of all sources of the build command that have not chan rom:
ged since the target was last
built.
$UNCHANGED_TARGETS echo Last build occurred . > $TARGET
The file names of all targets that would be built from sources that h
ave not changed since the target
was last built.
These names are reserved and may not be assigned to or used as constructi While construction variables are normally directly substituted, if a
on variables. construction variable has a value
which is a callable Python object (a function, or a class with a __ca
ll__ method), that object is
called during substitution. The callable must accept four arguments:
target, source, env and
for_signature. source is a list of source nodes, target is a list of
target nodes, env is the
construction environment to use for context, and for_signature is a b
oolean value that tells the
callable if it is being called for the purpose of generating a build
signature. Since the build
signature is used for rebuild determination, variable elements that d
o not affect whether a rebuild
should be triggered should be omitted from the returned string if for
_signature is true. See $( and $)
above for the syntax.
For example, the following builder call: SCons will insert whatever the callable returns into the expanded str ing:
env = Environment(CC='cc') def foo(target, source, env, for_signature):
env.Command( return "bar"
target=['foo'],
source=['foo.c', 'bar.c'],
action='@echo $CC -c -o $TARGET $SOURCES'
)
would produce the following output: # Will expand $BAR to "bar baz"
env = Environment(FOO=foo, BAR="$FOO baz")
cc -c -o foo foo.c bar.c As a reminder, substitution happens when $BAR is actually used in a b
uilder action. The value of
env['BAR'] will be exactly as it was set: "$FOO baz". This can make d
ebugging tricky, as the
substituted result is not available at the time the SConscript files
are being interpreted and thus
not available to print(). However, you can perform the substitution o
n demand by calling the env.subst
method for this purpose.
In the previous example, a string ${SOURCES[1]} would expand to: bar.c. You can use this feature to pass arguments to a callable variable by
creating a callable class that
stores passed arguments in the instance, and then uses them (in the _
_call__ method) when the instance
is called. Note that in this case, the entire variable expansion must
be enclosed by curly braces so
that the arguments will be associated with the instantiation of the c
lass:
A variable name may have the following modifiers appended within the encl class foo:
osing curly braces to access def __init__(self, arg):
properties of the interpolated string. These are known as special attribu self.arg = arg
tes.
base -
The base path of the file name,
including the directory path
but excluding any suffix.
dir - The name of the directory in which the file exists.
file - The file name, minus any directory portion.
filebase - Like file but minus its suffix.
suffix - Just the file suffix.
abspath - The absolute path name of the file.
relpath - The path name of the file relative to the root SConstruct f
ile's directory.
posix -
The path with directories separated by forward slashes
(/).
Sometimes necessary on Windows systems
when a path references a file on other (POSIX) systems.
windows -
The path with directories separated by backslashes
(\\).
Sometimes necessary on POSIX-style systems
when a path references a file on other (Windows) systems.
win32 is a (deprecated) synonym for
windows.
srcpath -
The directory and file name to the source file linked to this fil
e through
VariantDir().
If this file isn't linked,
it just returns the directory and filename unchanged.
srcdir -
The directory containing the source file linked to this file thro
ugh
VariantDir().
If this file isn't linked,
it just returns the directory part of the filename.
rsrcpath -
The directory and file name to the source file linked to this fil
e through
VariantDir().
If the file does not exist locally but exists in a Repository,
the path in the Repository is returned.
If this file isn't linked, it just returns the
directory and filename unchanged.
rsrcdir -
The Repository directory containing the source file linked to thi
s file through
VariantDir().
If this file isn't linked,
it just returns the directory part of the filename.
For example, the specified target will expand as follows for the correspo
nding modifiers:
$TARGET => sub/dir/file.x
${TARGET.base} => sub/dir/file
${TARGET.dir} => sub/dir
${TARGET.file} => file.x
${TARGET.filebase} => file
${TARGET.suffix} => .x
${TARGET.abspath} => /top/dir/sub/dir/file.x
${TARGET.relpath} => sub/dir/file.x
$TARGET => ../dir2/file.x
${TARGET.abspath} => /top/dir2/file.x
${TARGET.relpath} => ../dir2/file.x
SConscript('src/SConscript', variant_dir='sub/dir')
$SOURCE => sub/dir/file.x
${SOURCE.srcpath} => src/file.x
${SOURCE.srcdir} => src
Repository('/usr/repository')
$SOURCE => sub/dir/file.x
${SOURCE.rsrcpath} => /usr/repository/src/file.x
${SOURCE.rsrcdir} => /usr/repository/src
Some modifiers can be combined, like ${TARGET.srcpath.base), ${TARGET.fil
e.suffix}, etc.
The curly brace notation may also be used to enclose a Python expression
to be evaluated. See the section
called “Python Code Substitution” below for a description.
A variable name may also be a Python function associated with a construct
ion variable in the environment.
The function should accept four arguments:
target - a list of target nodes
source - a list of source nodes
env - the construction environment
for_signature -
a Boolean value that specifies
whether the function is being called
for generating a build signature.
SCons will insert whatever the called function returns into the expanded
string:
def foo(target, source, env, for_signature):
return "bar"
# Will expand $BAR to "bar baz"
env=Environment(FOO=foo, BAR="$FOO baz")
As a reminder, this evaluation happens when $BAR is actually used in a bu
ilder action. The value of
env['BAR'] will be exactly as it was set: "$FOO baz".
You can use this feature to pass arguments to a Python function by creati
ng a callable class that stores
one or more arguments in an object, and then uses them when the __call__(
) method is called. Note that in
this case, the entire variable expansion must be enclosed by curly braces
so that the arguments will be
associated with the instantiation of the class:
class foo:
def __init__(self, arg):
self.arg = arg
def __call__(self, target, source, env, for_signature):
return self.arg + " bar"
# Will expand $BAR to "my argument bar baz"
env=Environment(FOO=foo, BAR="${FOO('my argument')} baz")
The special pseudo-variables $( and $) may be used to surround parts of a
command line that may change
without causing a rebuild--that is, which are not included in the signatu
re of target files built with
this command. All text between $( and $) will be removed from the command
line before it is added to file
signatures, and the $( and $) will be removed before the command is execu
ted. For example, the command
line:
echo Last build occurred $( $TODAY $). > $TARGET
would execute the command:
echo Last build occurred $TODAY. > $TARGET
but the command signature added to any target files would be:
echo Last build occurred . > $TARGET
Python Code Substitution
If a substitutable expression using the notation ${something} does not ap
pear to match one of the other
substitution patterns, it is evaluated as a Python expression. This uses
Python's eval function, with the
globals parameter set to the current environment's set of construction va
riables, and the result
substituted in. So in the following case:
env.Command( def __call__(self, target, source, env, for_signature):
'foo.out', 'foo.in', "echo ${COND==1 and 'FOO' or 'BAR'} > $TARGE return self.arg + " bar"
T"
)
the command executed will be either # Will expand $BAR to "my argument bar baz"
env=Environment(FOO=foo, BAR="${FOO('my argument')} baz")
echo FOO > foo.out Substitution: Special Variables
Besides regular construction variables, scons provides the following
Special Variables for use in
expanding commands:
or $CHANGED_SOURCES
The file names of all sources of the build command that have chan
ged since the target was last
built.
echo BAR > foo.out $CHANGED_TARGETS
The file names of all targets that would be built from sources th
at have changed since the target
was last built.
according to the current value of env['COND'] when the command is execute $SOURCE
d. The evaluation takes place The file name of the source of the build command, or the file nam
when the target is being built, not when the SConscript is being read. So e of the first source if multiple
if env['COND'] is changed later sources are being built.
in the SConscript, the final value will be used.
Here's a more complete example. Note that all of COND, FOO, and BAR are c $SOURCES
onstruction variables, and their The file names of the sources of the build command.
values are substituted into the final command. FOO is a list, so its ele
ments are interpolated separated
by spaces.
env=Environment() $TARGET
env['COND'] = 1 The file name of the target being built, or the file name of the
env['FOO'] = ['foo1', 'foo2'] first target if multiple targets
env['BAR'] = 'barbar' are being built.
env.Command(
'foo.out', 'foo.in', "echo ${COND==1 and FOO or BAR} > $TARGET"
)
will execute: $TARGETS
The file names of all targets being built.
echo foo1 foo2 > foo.out $UNCHANGED_SOURCES
The file names of all sources of the build command that have not
changed since the target was last
built.
In point of fact, Python expression evaluation is how the special attribu $UNCHANGED_TARGETS
tes are substituted: they are The file names of all targets that would be built from sources th
simply attributes of the Python objects that represent $TARGET, $SOURCES, at have not changed since the
etc., which SCons passes to eval target was last built.
which returns the value.
SCons uses the following rules when converting construction variables int These names are reserved and may not be assigned to or used as constr
o command lines: uction variables. SCons computes
them in a context-dependent manner and they and are not retrieved fro
m a construction environment.
string For example, the following builder call:
When the value is a string it is interpreted as a space delimited lis
t of command line arguments.
list env = Environment(CC='cc')
When the value is a list it is interpreted as a list of command line env.Command(
arguments. Each element of the target=['foo'],
list is converted to a string. source=['foo.c', 'bar.c'],
action='@echo $CC -c -o $TARGET $SOURCES'
)
other would produce the following output:
Anything that is not a list or string is converted to a string and in
terpreted as a single command
line argument.
newline cc -c -o foo foo.c bar.c
Newline characters (\n) delimit lines. The newline parsing is done af
ter all other parsing, so it is
not possible for arguments (e.g. file names) to contain embedded newl
ine characters.
Note In the previous example, a string ${SOURCES[1]} would expand to: bar.
Use of the Python eval function is considered to have security implic c.
ations, since, depending on input
sources, arbitrary unchecked strings of code can be executed by the P Substitution: Special Attributes
ython interpreter. Although SCons A variable name may have the following modifiers appended within the
makes use of it in a somewhat restricted context, you should be aware enclosing curly braces to access
of this issue when using the properties of the interpolated string. These are known as special att
${python-expression-for-subst} form. ributes.
base -
The base path of the file name,
including the directory path
but excluding any suffix.
dir - The name of the directory in which the file exists.
file - The file name, minus any directory portion.
filebase - Like file but minus its suffix.
suffix - Just the file suffix.
abspath - The absolute path name of the file.
relpath - The path name of the file relative to the root SConstru
ct file's directory.
posix -
The path with directories separated by forward slashes
(/).
Sometimes necessary on Windows systems
when a path references a file on other (POSIX) systems.
windows -
The path with directories separated by backslashes
(\\).
Sometimes necessary on POSIX-style systems
when a path references a file on other (Windows) systems.
win32 is a (deprecated) synonym for
windows.
srcpath -
The directory and file name to the source file linked to this
file through
VariantDir().
If this file isn't linked,
it just returns the directory and filename unchanged.
srcdir -
The directory containing the source file linked to this file
through
VariantDir().
If this file isn't linked,
it just returns the directory part of the filename.
rsrcpath -
The directory and file name to the source file linked to this
file through
VariantDir().
If the file does not exist locally but exists in a Repository
,
the path in the Repository is returned.
If this file isn't linked, it just returns the
directory and filename unchanged.
rsrcdir -
The Repository directory containing the source file linked to
this file through
VariantDir().
If this file isn't linked,
it just returns the directory part of the filename.
For example, the specified target will expand as follows for the corr
esponding modifiers:
$TARGET => sub/dir/file.x
${TARGET.base} => sub/dir/file
${TARGET.dir} => sub/dir
${TARGET.file} => file.x
${TARGET.filebase} => file
${TARGET.suffix} => .x
${TARGET.abspath} => /top/dir/sub/dir/file.x
${TARGET.relpath} => sub/dir/file.x
$TARGET => ../dir2/file.x
${TARGET.abspath} => /top/dir2/file.x
${TARGET.relpath} => ../dir2/file.x
SConscript('src/SConscript', variant_dir='sub/dir')
$SOURCE => sub/dir/file.x
${SOURCE.srcpath} => src/file.x
${SOURCE.srcdir} => src
Repository('/usr/repository')
$SOURCE => sub/dir/file.x
${SOURCE.rsrcpath} => /usr/repository/src/file.x
${SOURCE.rsrcdir} => /usr/repository/src
Some modifiers can be combined, like ${TARGET.srcpath.base), ${TARGET
.file.suffix}, etc.
Python Code Substitution
If a substitutable expression using the notation ${expression} does n
ot appear to match one of the
other substitution patterns, it is evaluated as a Python expression.
This uses Python's eval function,
with the globals parameter set to the current environment's set of co
nstruction variables, and the
result substituted in. So in the following case:
env.Command(
'foo.out', 'foo.in', "echo ${COND==1 and 'FOO' or 'BAR'} > $T
ARGET"
)
the command executed will be either
echo FOO > foo.out
or
echo BAR > foo.out
according to the current value of env['COND'] when the command is exe
cuted. The evaluation takes place
when the target is being built, not when the SConscript is being read
. So if env['COND'] is changed
later in the SConscript, the final value will be used.
Here's a more complete example. Note that all of COND, FOO, and BAR a
re construction variables, and
their values are substituted into the final command. FOO is a list,
so its elements are interpolated
separated by spaces.
env=Environment()
env['COND'] = 1
env['FOO'] = ['foo1', 'foo2']
env['BAR'] = 'barbar'
env.Command(
'foo.out', 'foo.in', "echo ${COND==1 and FOO or BAR} > $TARGE
T"
)
will execute:
echo foo1 foo2 > foo.out
In point of fact, Python expression evaluation is how the special att
ributes are substituted: they are
simply attributes of the Python objects that represent $TARGET, $SOUR
CES, etc., which SCons passes to
eval which returns the value.
Note
Use of the Python eval function is considered to have security im
plications, since, depending on
input sources, arbitrary unchecked strings of code can be execute
d by the Python interpreter.
Although SCons makes use of it in a somewhat restricted context,
you should be aware of this issue
when using the ${python-expression-for-subst} form.
Scanner Objects Scanner Objects
Scanner objects are used to scan specific file types for implicit depende Scanner objects are used to scan specific file types for implicit depende
ncies. SCons has a number of ncies, for example embedded
pre-built Scanner objects, so it is usually only necessary to set up Scan preprocessor/compiler directives that cause other files to be included du
ners for new file types. You do ring processing. SCons has a
this by calling the Scanner function. The Scanner function accepts the fo number of pre-built Scanner objects, so it is usually only necessary to s
llowing arguments, only function et up Scanners for new file
is required, the rest are optional: types. You do this by calling the Scanner factory function. Scanner acce
pts the following arguments. Only
function is required; the rest are optional:
function function
A Python function that will process a given Node (usually a file) and A scanner function to call to process a given Node (usually a file) a
return a list of Nodes nd return a list of Nodes
representing the implicit dependencies (file names) found in the cont representing the implicit dependencies (usually files) found in the c
ents. The function must accept ontents. The function must accept
three required arguments, node, env and path, and an optional fourth, arg. node is the internal SCons three required arguments, node, env and path, and an optional fourth, arg. node is the internal SCons
node representing the file to scan, env is the construction environme nt to use during the scan, and node representing the file to scan, env is the construction environme nt to use during the scan, and
path is a tuple of directories that can be searched for files, as gen erated by the optional path is a tuple of directories that can be searched for files, as gen erated by the optional scanner
path_function (see below). If argument was supplied when the Scanner object was created, it is given path_function (see below). If argument was supplied when the Scanner object was created, it is given
as arg when the function is called; since argument is optional, the d efault is no arg. as arg when the scanner function is called; since argument is optiona l, the default is no arg.
The function can use use str(node) to fetch the name of the file, and The function can use use str(node) to fetch the name of the file, nod
node.get_contents() to fetch the e.dir to fetch the directory the
contents of the file as bytes or node.get_text_contents() to fetch th file is in, node.get_contents() to fetch the contents of the file as
e file's contents as text. Note bytes or node.get_text_contents()
that the file is not guaranteed to exist at the time the scanner is c to fetch the contents of the file as text.
alled (it could be a generated
file, not generated yet), so the scanner function must be tolerant of The function must take into account the path directories when generat
that. ing the dependency Nodes. To
illustrate this, a C language source file may contain a line like #in
clude "foo.h". However, there is
no guarantee that foo.h exists in the current directory: the contents
of $CPPPATH is passed to the C
preprocessor which will look in those places for the header, so the s
canner function needs to look in
those places as well in order to build Nodes with correct paths. Usin
g FindPathDirs with an argument
of CPPPATH as the path_function in the Scanner call means the scanner
function will be called with the
paths extracted from $CPPPATH in the environment env passed as the pa
ths parameter.
Note that the file to scan is not guaranteed to exist at the time the
scanner is called - it could be
a generated file which has not been generated yet - so the scanner fu
nction must be tolerant of that.
Alternatively, you can supply a dictionary as the function parameter,
to map keys (such as file
suffixes) to other Scanner objects. A Scanner created this way serves
as a dispatcher: the Scanner's
skeys parameter is automatically populated with the dictionary's keys
, indicating that the Scanner
handles Nodes which would be selected by those keys; the mapping is t
hen used to pass the file on to a
different Scanner that would not have been selected to handle that No
de based on its own skeys.
name name
The name to use for the Scanner. This is mainly used to identify the Scanner internally. The default The name to use for the Scanner. This is mainly used to identify the Scanner internally. The default
value is "NONE". value is "NONE".
argument argument
If specified, will be passed to the scanner function function and the path function path_function when If specified, will be passed to the scanner function function and the path function path_function when
called, as the additional argument each of those functions takes. called, as the optional parameter each of those functions takes.
skeys skeys
Scanner key(s) indicating the file types this scanner is associated w ith. Used internally to select an Scanner key(s) indicating the file types this scanner is associated w ith. Used internally to select an
appropriate scanner. In the usual case of scanning for file names, th is argument will be a list of appropriate scanner. In the usual case of scanning for file names, th is argument will be a list of
suffixes for the different file types that this Scanner knows how to scan. If skeys is a string, it suffixes for the different file types that this Scanner knows how to scan. If skeys is a string, it
will be expanded into a list by the current environment. will be expanded into a list by the current environment.
path_function path_function
A Python function that takes four or five arguments: a construction e nvironment, a Node for the A Python function that takes four or five arguments: a construction e nvironment, a Node for the
directory containing the SConscript file in which the first target wa s defined, a list of target directory containing the SConscript file in which the first target wa s defined, a list of target
nodes, a list of source nodes, and the value of argument if it was su pplied when the scanner was nodes, a list of source nodes, and the value of argument if it was su pplied when the Scanner was
created. Must return a tuple of directories that can be searched for files to be returned by this created. Must return a tuple of directories that can be searched for files to be returned by this
Scanner object. (Note that the FindPathDirs function can be used to r eturn a ready-made path_function Scanner object. (Note that the FindPathDirs function can be used to r eturn a ready-made path_function
for a given construction variable name, instead of having to write yo ur own function from scratch.) for a given construction variable name, instead of having to write yo ur own function from scratch.)
node_class node_class
The class of Node that should be returned by this Scanner object. Any strings or other objects The class of Node that should be returned by this Scanner object. Any strings or other objects
returned by the scanner function that are not of this class will be r un through the function supplied returned by the scanner function that are not of this class will be r un through the function supplied
by the node_factory argument. A value of None can be supplied to indi cate no conversion; the default by the node_factory argument. A value of None can be supplied to indi cate no conversion; the default
is to return File nodes. is to return File nodes.
skipping to change at line 10710 skipping to change at line 11404
recursive recursive
Specifies whether this scanner should be re-invoked on the dependency files returned by the scanner. Specifies whether this scanner should be re-invoked on the dependency files returned by the scanner.
If omitted, the Node subsystem will only invoke the scanner on the fi le being scanned and not recurse. If omitted, the Node subsystem will only invoke the scanner on the fi le being scanned and not recurse.
Recursion is needed when the files returned by the scanner may themse lves contain further file Recursion is needed when the files returned by the scanner may themse lves contain further file
dependencies, as in the case of preprocessor #include lines. A value that evaluates true enables dependencies, as in the case of preprocessor #include lines. A value that evaluates true enables
recursion; recursive may be a callable function, in which case it wil l be called with a list of Nodes recursion; recursive may be a callable function, in which case it wil l be called with a list of Nodes
found and should return a list of Nodes that should be scanned recurs ively; this can be used to select found and should return a list of Nodes that should be scanned recurs ively; this can be used to select
a specific subset of Nodes for additional scanning. a specific subset of Nodes for additional scanning.
Note that scons has a global SourceFileScanner object that is used by the Once created, a Scanner can added to an environment by setting it in the
Object, SharedObject and $SCANNERS list, which
StaticObject builders to decide which scanner should be used for differen automatically triggers SCons to also add it to the environment as a metho
t file extensions. You can use d. However, usually a scanner is
the SourceFileScanner.add_scanner() method to add your own Scanner object not truly standalone, but needs to be plugged in to the existing selectio
to the SCons infrastructure that n mechanism for deciding how to
builds target programs or libraries from a list of source files of differ scan source files based on filename extensions. For this, SCons has a glo
ent types: bal SourceFileScanner object that
is used by the Object, SharedObject and StaticObject builders to decide w
hich scanner should be used. You
can use the SourceFileScanner.add_scanner() method to add your own Scanne
r object to the SCons
infrastructure that builds target programs or libraries from a list of so
urce files of different types:
def xyz_scan(node, env, path): def xyz_scan(node, env, path):
contents = node.get_text_contents() contents = node.get_text_contents()
# Scan the contents and return the included files. # Scan the contents and return the included files.
XYZScanner = Scanner(xyz_scan) XYZScanner = Scanner(xyz_scan)
SourceFileScanner.add_scanner('.xyz', XYZScanner) SourceFileScanner.add_scanner('.xyz', XYZScanner)
env.Program('my_prog', ['file1.c', 'file2.f', 'file3.xyz']) env.Program('my_prog', ['file1.c', 'file2.f', 'file3.xyz'])
Tool Modules
Additional tools can be added to a project either by placing them in a si
te_tools subdirectory of a site
directory, or in a custom location specified to scons by giving the toolp
ath keyword argument to
Environment. A tool module is a form of Python module, invoked internally
using the Python import
mechanism, so a tool can consist either of a single source file taking th
e name of the tool (e.g.
mytool.py) or a directory taking the name of the tool (e.g. mytool/) whi
ch contains at least an
__init__.py file.
The toolpath parameter takes a list as its value:
env = Environment(tools=['default', 'foo'], toolpath=['tools'])
This looks for a tool specification module (mytool.py, or directory mytoo
l) in directory tools and in the
standard locations, as well as using the ordinary default tools for the p
latform.
Directories specified via toolpath are prepended to the existing tool pat
h. The default tool path is any
site_tools directories, so tools in a specified toolpath take priority, f
ollowed by tools in a site_tools
directory, followed by built-in tools. For example, adding a tool specifi
cation module gcc.py to the
toolpath directory would override the built-in gcc tool. The tool path is
stored in the environment and
will be used by subsequent calls to the Tool method, as well as by env.Cl
one.
base = Environment(toolpath=['custom_path'])
derived = base.Clone(tools=['custom_tool'])
derived.CustomBuilder()
A tool specification module must include two functions:
generate(env, **kwargs)
Modify the construction environment env to set up necessary construct
ion variables, Builders,
Emitters, etc., so the facilities represented by the tool can be exec
uted. Care should be taken not to
overwrite construction variables intended to be settable by the user.
For example:
def generate(env):
...
if 'MYTOOL' not in env:
env['MYTOOL'] = env.Detect("mytool")
if 'MYTOOLFLAGS' not in env:
env['MYTOOLFLAGS'] = SCons.Util.CLVar('--myarg')
...
The generate function may use any keyword arguments that the user sup
plies via kwargs to vary its
initialization.
exists(env)
Return a true value if the tool can be called in the context of env.
else false. Usually this means
looking up one or more known programs using the PATH from the supplie
d env, but the tool can make the
exists decision in any way it chooses.
Note
At the moment, user-added tools do not automatically have their exist
s function called. As a result,
it is recommended that the generate function be defensively coded - t
hat is, do not rely on any
necessary existence checks already having been performed. This is exp
ected to be a temporary
limitation, and the exists function should still be provided.
The elements of the tools list may also be functions or callable objects,
in which case the Environment
method will call those objects to update the new construction environment
(see Tool for more details):
def my_tool(env):
env['XYZZY'] = 'xyzzy'
env = Environment(tools=[my_tool])
The individual elements of the tools list may also themselves be lists or
tuples of the form (toolname,
kw_dict). SCons searches for the toolname specification file as described
above, and passes kw_dict, which
must be a dictionary, as keyword arguments to the tool's generate functio
n. The generate function can use
the arguments to modify the tool's behavior by setting up the environment
in different ways or otherwise
changing its initialization.
# in tools/my_tool.py:
def generate(env, **kwargs):
# Sets MY_TOOL to the value of keyword 'arg1' '1' if not supplied
env['MY_TOOL'] = kwargs.get('arg1', '1')
def exists(env):
return True
# in SConstruct:
env = Environment(tools=['default', ('my_tool', {'arg1': 'abc'})],
toolpath=['tools'])
The tool specification (my_tool in the example) can use the $PLATFORM var
iable from the construction
environment it is passed to customize the tool for different platforms.
Tools can be "nested" - that is, they can be located within a subdirector
y in the toolpath. A nested tool
name uses a dot to represent a directory separator
# namespaced builder
env = Environment(ENV=os.environ.copy(), tools=['SubDir1.SubDir2.Some
Tool'])
env.SomeTool(targets, sources)
# Search Paths
# SCons\Tool\SubDir1\SubDir2\SomeTool.py
# SCons\Tool\SubDir1\SubDir2\SomeTool\__init__.py
# .\site_scons\site_tools\SubDir1\SubDir2\SomeTool.py
# .\site_scons\site_tools\SubDir1\SubDir2\SomeTool\__init__.py
SYSTEM-SPECIFIC BEHAVIOR SYSTEM-SPECIFIC BEHAVIOR
scons and its configuration files are very portable, due largely to its i mplementation in Python. There scons and its configuration files are very portable, due largely to its i mplementation in Python. There
are, however, a few portability issues waiting to trap the unwary. are, however, a few portability issues waiting to trap the unwary.
.C file suffix .C File Suffix
scons handles the upper-case .C file suffix differently, depending on the capabilities of the underlying scons handles the upper-case .C file suffix differently, depending on the capabilities of the underlying
system. On a case-sensitive system such as Linux or UNIX, scons treats a file with a .C suffix as a C++ system. On a case-sensitive system such as Linux or UNIX, scons treats a file with a .C suffix as a C++
source file. On a case-insensitive system such as Windows, scons treats a file with a .C suffix as a C source file. On a case-insensitive system such as Windows, scons treats a file with a .C suffix as a C
source file. source file.
Fortran file suffixes Fortran File Suffixes
scons handles upper-case Fortran file suffixes differently depending on t There are several ways source file suffixes impact the behavior of SCons
he capabilities of the underlying when working with Fortran
system. On a case-sensitive system such as Linux or UNIX, scons treats a language code (not all are system-specific, but they are included here fo
file with a .F as a Fortran r completeness).
source file that is to be first run through the standard C preprocessor,
while the lower-case version is As the Fortran language has evolved through multiple standards editions,
not. This matches the convention of gfortran, which may also be followed projects might have a need to
by other Fortran compilers. This handle files from different language generations differently. To this end
also applies to other naming variants, .FOR, .FTN, .F90, .F95, .F03 and . , SCons dispatches to a different
F08; files suffixed with .FPP and compiler dialect setup (expressed as a set of construction variables) dep
.fpp are both run through the preprocessor, as indicated by the pp part o ending on the file suffix. By
f the name. On a case-insensitive default, all of these setups start out the same, but individual construct
system such as Windows, scons treats a file with a .F suffix as a Fortran ion variables can be modified as
source file that should not be needed to tune a given dialect. Each of these dialacts has a tool specifi
run through the C preprocessor. cation module whose documentation
describes the construction variables associated with that dialect: .f (as
Run through the C preprocessor here means that a different set of constru well as .for and .ftn) in
ction variables will be applied fortran; (construction variables start with FORTRAN) .f77 in f77; (constr
in constructed commands, for example $FORTRANPPCOM and $FORTRANPPCOMSTR i uction variables start with F77)
nstead of $FORTRANCOM and .f90 in f90; (construction variables start with F90) .f95 in f95; (constr
$FORTRANCOMSTR. See the Fortran-related construction variables for more d uction variables start with F95)
etails. .f03 in f03; (construction variables start with F03) .f08 in f08 (constru
ction variables start with F08).
While SCons recognizes multiple internal dialects based on filename suffi
xes, the convention of various
available Fortran compilers is to assign an actual meaning to only two of
these suffixes: .f (as well as
.for and .ftn) refers to the fixed-format source code that was the only a
vailable option in FORTRAN 77 and
earlier, and .f90 refers to free-format source code which became availabl
e as of the Fortran 90 standard.
Some compilers recognize suffixes which correspond to Fortran specificati
ons later then F90 as equivalent
to .f90 for this purpose, while some do not - check the documentation for
your compiler. An occasionally
suggested policy suggestion is to use only .f and .f90 as Fortran filenam
e suffixes. The fixed/free form
determination can usually be controlled explicitly with compiler flags (e
.g. -ffixed-form for gfortran),
overriding any assumption that may be made based on the source file suffi
x.
The source file suffix does not imply conformance with the similarly-name
d Fortran standard - a suffix of
.f08 does not mean you are compiling specifically for Fortran 2008. Norma
lly, compilers provide
command-line options for making this selection (e.g. -std=f2008 for gfor
tran).
For dialects from F90 on (including the generic FORTRAN dialect), a suffi
x of .mod is recognized for
Fortran modules. These files are a side effect of compiling a Fortran sou
rce file containing module
declarations, and must be available when other code which declares that i
t uses the module is processed.
SCons does not currently have integrated support for submodules, introduc
ed in the Fortran 2008 standard -
the invoked compiler will produce results, but SCons will not recognize .
smod files as tracked objects.
On a case-sensitive system such as Linux or UNIX, a file with a an upper-
cased suffix from the set .F,
.FOR, .FTN, .F90, .F95, .F03 and .F08 is treated as a Fortran source file
which shall first be run through
the standard C preprocessor. The lower-cased versions of these suffixes d
o not trigger this behavior. On
systems which do not distinguish between uppper and lower case in filenam
es, this behavior is not
available, but files suffixed with either .FPP or .fpp are always passed
to the preprocessor first. This
matches the convention of gfortran from the GNU Compiler Collection, and
also followed by certain other
Fortran compilers. For these two suffixes, the generic FORTRAN dialect wi
ll be selected.
SCons itself does not invoke the preprocessor, that is handled by the com
piler, but it adds construction
variables which are applicable to the preprocessor run. You can see this
difference by examining
$FORTRANPPCOM and $FORTRANPPCOMSTR which are used instead of $FORTRANCOM
and $FORTRANCOMSTR for that
dialect.
Windows: Cygwin Tools and Cygwin Python vs. Windows Pythons Windows: Cygwin Tools and Cygwin Python vs. Windows Pythons
Cygwin supplies a set of tools and utilities that let users work on a Win Cygwin supplies a set of tools and utilities that let users work on a Win
dows system using a more dows system using a POSIX-like
POSIX-like environment. The Cygwin tools, including Cygwin Python, do thi environment. The Cygwin tools, including Cygwin Python, do this, in part,
s, in part, by sharing an ability by sharing an ability to
to interpret UNIX-like path names. For example, the Cygwin tools will int interpret POSIX-style path names. For example, the Cygwin tools will inte
ernally translate a Cygwin path rnally translate a Cygwin path
name like /cygdrive/c/mydir to an equivalent Windows pathname of C:/mydir (equivalent to C:\mydir). name like /cygdrive/c/mydir to an equivalent Windows pathname of C:/mydir (equivalent to C:\mydir).
Versions of Python that are built for native Windows execution, such as t he python.org and ActiveState Versions of Python that are built for native Windows execution, such as t he python.org and ActiveState
versions, do not have the Cygwin path name semantics. This means that usi versions, do not understand the Cygwin path name semantics. This means th
ng a native Windows version of at using a native Windows version
Python to build compiled programs using Cygwin tools (such as gcc, bison of Python to build compiled programs using Cygwin tools (such as gcc, bis
and flex) may yield unpredictable on and flex) may yield
results. "Mixing and matching" in this way can be made to work, but it re unpredictable results. "Mixing and matching" in this way can be made to w
quires careful attention to the ork, but it requires careful
use of path names in your SConscript files. attention to the use of path names in your SConscript files.
In practice, users can sidestep the issue by adopting the following rules In practice, users can sidestep the issue by adopting the following guide
: When using Cygwin's gcc for lines: When using Cygwin's gcc
compiling, use the Cygwin-supplied Python interpreter to run scons; when for compiling, use the Cygwin-supplied Python interpreter to run scons; w
using Microsoft Visual C/C++ (or hen using Microsoft Visual C/C++
some other Windows compiler) use the python.org or Microsoft Store or Act (or some other "native" Windows compiler) use the python.org, Microsoft S
iveState version of Python to run tore, ActiveState or other native
scons. version of Python to run scons.
This discussion largely applies to the msys2 environment as well (with th
e use of the mingw compiler
toolchain), in particular the recommendation to use the msys2 version of
Python if running scons from
inside an msys2 shell.
Windows: scons.bat file Windows: scons.bat file
On Windows, if scons is executed via a wrapper scons.bat batch file, ther e are (at least) two On Windows, if scons is executed via a wrapper scons.bat batch file, ther e are (at least) two
ramifications. Note this is no longer the default - scons installed via P ython's pip installer will have ramifications. Note this is no longer the default - scons installed via P ython''s pip installer will have
an scons.exe which does not have these limitations: an scons.exe which does not have these limitations:
First, Windows command-line users that want to use variable assignment on the command line may have to put First, Windows command-line users that want to use variable assignment on the command line may have to put
double quotes around the assignments, otherwise the Windows command shell will consume those as arguments double quotes around the assignments, otherwise the Windows command shell will consume those as arguments
to itself, not to scons: to itself, not to scons:
scons "FOO=BAR" "BAZ=BLEH" scons "FOO=BAR" "BAZ=BLEH"
Second, the Cygwin shell does not reognize typing scons at the command li Second, the Cygwin shell does not recognize typing scons at the command l
ne prompt as referring to this ine prompt as referring to this
weapper. You can work around this either by executing scons.bat (includin wrapper. You can work around this either by executing scons.bat (includin
g the extension) from the Cygwin g the extension) from the Cygwin
command line, or by creating a wrapper shell script named scons which inv okes scons.bat. command line, or by creating a wrapper shell script named scons which inv okes scons.bat.
MinGW MinGW
The MinGW bin directory must be in your PATH environment variable or the ['ENV']['PATH'] construction The MinGW bin directory must be in your PATH environment variable or the ['ENV']['PATH'] construction
variable for scons to detect and use the MinGW tools. When running under the native Windows Python variable for scons to detect and use the MinGW tools. When running under the native Windows Python;
interpreter, scons will prefer the MinGW tools over the Cygwin tools, if they are both installed, interpreter, scons will prefer the MinGW tools over the Cygwin tools, if they are both installed,
regardless of the order of the bin directories in the PATH variable. If y ou have both MSVC and MinGW regardless of the order of the bin directories in the PATH variable. If y ou have both MSVC and MinGW
installed and you want to use MinGW instead of MSVC, then you must explic itly tell scons to use MinGW by installed and you want to use MinGW instead of MSVC, then you must explic itly tell scons to use MinGW by
passing tools=['mingw'] to the Environment function, because scons will p refer the MSVC tools over the passing tools=['mingw'] to the Environment function, because scons will p refer the MSVC tools over the
MinGW tools. MinGW tools.
ENVIRONMENT ENVIRONMENT
In general, scons is not controlled by environment variables set in the s hell used to invoke it, leaving In general, scons is not controlled by environment variables set in the s hell used to invoke it, leaving
it up to the SConscript file author to import those if desired. However t he following variables are it up to the SConscript file author to import those if desired. However t he following variables are
imported by scons itself if set: imported by scons itself if set:
skipping to change at line 10812 skipping to change at line 11642
line. Can be used to reduce frequent retyping of common options. The contents of SCONSFLAGS are line. Can be used to reduce frequent retyping of common options. The contents of SCONSFLAGS are
considered before any passed command line options, so the command lin e can be used to override considered before any passed command line options, so the command lin e can be used to override
SCONSFLAGS options if necessary. SCONSFLAGS options if necessary.
SCONS_CACHE_MSVC_CONFIG SCONS_CACHE_MSVC_CONFIG
(Windows only). If set, save the shell environment variables generate d when setting up the Microsoft (Windows only). If set, save the shell environment variables generate d when setting up the Microsoft
Visual C++ compiler (and/or Build Tools) to a cache file, to give the se settings, which are relatively Visual C++ compiler (and/or Build Tools) to a cache file, to give the se settings, which are relatively
expensive to generate, persistence across scons invocations. Use of t his option is primarily intended expensive to generate, persistence across scons invocations. Use of t his option is primarily intended
to aid performance in tightly controlled Continuous Integration setup s. to aid performance in tightly controlled Continuous Integration setup s.
If set to a True-like value ("1", "true" or "True") will cache to a f If set to a True-like value ("1", "true" or "True") will cache to a f
ile named .scons_msvc_cache in ile named .scons_msvc_cache.json
the user's home directory. If set to a pathname, will use that pathna in the user's home directory. If set to a pathname, will use that pat
me for the cache. hname for the cache.
Note: use this cache with caution as it might be somewhat fragile: wh ile each major toolset version Note: use this cache with caution as it might be somewhat fragile: wh ile each major toolset version
(e.g. Visual Studio 2017 vs 2019) and architecture pair will get sepa rate cache entries, if toolset (e.g. Visual Studio 2017 vs 2019) and architecture pair will get sepa rate cache entries, if toolset
updates cause a change to settings within a given release series, sco ns will not detect the change and updates cause a change to settings within a given release series, sco ns will not detect the change and
will reuse old settings. Remove the cache file in case of problems wi th this. scons will ignore will reuse old settings. Remove the cache file in case of problems wi th this. scons will ignore
failures reading or writing the file and will silently revert to non- cached behavior in such cases. failures reading or writing the file and will silently revert to non- cached behavior in such cases.
Available since scons 3.1 (experimental). Available since scons 3.1 (experimental).
QTDIR QTDIR
skipping to change at line 10839 skipping to change at line 11669
The SCons User Guide at The SCons User Guide at
https://scons.org/doc/production/HTML/scons-user.html https://scons.org/doc/production/HTML/scons-user.html
The SCons Design Document (old) The SCons Design Document (old)
The SCons Cookbook at The SCons Cookbook at
https://scons-cookbook.readthedocs.io https://scons-cookbook.readthedocs.io
for examples of how to solve various problems with SCons. for examples of how to solve various problems with SCons.
SCons source code SCons source code
on GitHub[7] on GitHub[6]
The SCons API Reference The SCons API Reference
https://scons.org/doc/production/HTML/scons-api/index.html https://scons.org/doc/production/HTML/scons-api/index.html
(for internal details) (for internal details)
AUTHORS AUTHORS
Originally: Steven Knight knight@baldmt.com and Anthony Roach aroach@elec triceyeball.com. Originally: Steven Knight knight@baldmt.com and Anthony Roach aroach@elec triceyeball.com.
Since 2010: The SCons Development Team scons-dev@scons.org. Since 2010: The SCons Development Team scons-dev@scons.org.
AUTHOR AUTHOR
The SCons Development Team The SCons Development Team
COPYRIGHT COPYRIGHT
Copyright © 2001 - 2021 The SCons Foundation Copyright © 2001 - 2022 The SCons Foundation
NOTES NOTES
1. https://github.com/SCons/scons-contrib 1. https://github.com/SCons/scons-contrib
https://github.com/SCons/scons-contrib https://github.com/SCons/scons-contrib
2. LLVM specification 2. LLVM specification
https://clang.llvm.org/docs/JSONCompilationDatabase.html https://clang.llvm.org/docs/JSONCompilationDatabase.html
3. JEP 313 3. JEP 313
https:openjdk.java.net/jeps/313 https:openjdk.java.net/jeps/313
4. ninja package 4. If no_progress is set via SetOption in an SConscript file (but not if
https://pypi.org/project/ninja/ set in a site_init.py file)
5. If no_progress is set via SetOption in an SConscript file (but not if
set in a site_init.py file)
there will still be an initial status message about reading SConscrip t files since SCons has to start there will still be an initial status message about reading SConscrip t files since SCons has to start
reading them before it can see the SetOption. reading them before it can see the SetOption.
6. http://www.opensource.org/licenses/alphabetical 5. http://www.opensource.org/licenses/alphabetical
http://www.opensource.org/licenses/alphabetical http://www.opensource.org/licenses/alphabetical
7. on GitHub 6. on GitHub
https://github.com/SCons/scons https://github.com/SCons/scons
SCons 4.3.0 Version 4.3.0 <pubdate>Released Tue, 16 Nov 2021 19:09:21 +0000</pu bdate> SCONS(1) SCons 4.4.0 Version 4.4.0 <pubdate>Released Sat, 30 Jul 2022 14:09:41 -0700</pu bdate> SCONS(1)
 End of changes. 311 change blocks. 
1624 lines changed or deleted 2862 lines changed or added
To the Man Pages (all 3): section of the SCons source changes report or the top of this page
Mainly generated by pkgdiff using rfcdiff
Home  |  About  |  Features  |  All  |  Newest  |  Dox  |  Diffs  |  RSS Feeds  |  Screenshots  |  Comments  |  Imprint  |  Privacy  |  HTTP(S)