scons man page

scons — a software construction tool

Synopsis

scons [options...] [name=val...] [targets...]

Description

The scons utility builds software (or other files) by determining which component pieces must be rebuilt and executing the necessary commands to rebuild them.

By default, scons searches for a file named SConstruct, Sconstruct, or sconstruct (in that order) in the current directory and reads its configuration from the first file found. An alternate file name may be specified via the -f option.

The SConstruct file can specify subsidiary configuration files using the SConscript() function. By convention, these subsidiary files are named SConscript, although any name may be used. (Because of this naming convention, the term "SConscript files" is sometimes used to refer generically to all scons configuration files, regardless of actual file name.)

The configuration files specify the target files to be built, and (optionally) the rules to build those targets. Reasonable default rules exist for building common software components (executable programs, object files, libraries), so that for most software projects, only the target and input files need be specified.

Before reading the SConstruct file, scons looks for a directory named site_scons in various system directories (see below) and the directory containing the SConstruct file; for each of those dirs which exists, site_scons is prepended to sys.path, the file site_scons/site_init.py, is evaluated if it exists, and the directory site_scons/site_tools is prepended to the default toolpath if it exists. See the --no-site-dir and --site-dir options for more details.

scons reads and executes the SConscript files as Python scripts, so you may use normal Python scripting capabilities (such as flow control, data manipulation, and imported Python libraries) to handle complicated build situations. scons, however, reads and executes all of the SConscript files before it begins building any targets. To make this obvious, scons prints the following messages about what it is doing:

$ scons foo.out
scons: Reading SConscript files ...
scons: done reading SConscript files.
scons: Building targets  ...
cp foo.in foo.out
scons: done building targets.
$

The status messages (everything except the line that reads "cp foo.in foo.out") may be suppressed using the -Q option.

scons does not automatically propagate the external environment used to execute scons to the commands used to build target files. This is so that builds will be guaranteed repeatable regardless of the environment variables set at the time scons is invoked. This also means that if the compiler or other commands that you want to use to build your target files are not in standard system locations, scons will not find them unless you explicitly set the PATH to include those locations. Whenever you create an scons construction environment, you can propagate the value of PATH from your external environment as follows:

import os
env = Environment(ENV = {'PATH' : os.environ['PATH']})

Similarly, if the commands use external environment variables like $PATH, $HOME, $JAVA_HOME, $LANG, $SHELL, $TERM, etc., these variables can also be explicitly propagated:

import os
env = Environment(ENV = {'PATH' : os.environ['PATH'],
                         'HOME' : os.environ['HOME']})

Or you may explicitly propagate the invoking user's complete external environment:

import os
env = Environment(ENV = os.environ)

This comes at the expense of making your build dependent on the user's environment being set correctly, but it may be more convenient for many configurations.

scons can scan known input files automatically for dependency information (for example, #include statements in C or C++ files) and will rebuild dependent files appropriately whenever any "included" input file changes. scons supports the ability to define new scanners for unknown input file types.

scons knows how to fetch files automatically from SCCS or RCS subdirectories using SCCS, RCS or BitKeeper.

scons is normally executed in a top-level directory containing a SConstruct file, optionally specifying as command-line arguments the target file or files to be built.

By default, the command

scons

will build all target files in or below the current directory. Explicit default targets (to be built when no targets are specified on the command line) may be defined the SConscript file(s) using the Default() function, described below.

Even when Default() targets are specified in the SConscript file(s), all target files in or below the current directory may be built by explicitly specifying the current directory (.) as a command-line target:

scons .

Building all target files, including any files outside of the current directory, may be specified by supplying a command-line target of the root directory (on POSIX systems):

scons /

or the path name(s) of the volume(s) in which all the targets should be built (on Windows systems):

scons C:\ D:\

To build only specific targets, supply them as command-line arguments:

scons foo bar

in which case only the specified targets will be built (along with any derived files on which they depend).

Specifying "cleanup" targets in SConscript files is not usually necessary. The -c flag removes all files necessary to build the specified target:

scons -c .

to remove all target files, or:

scons -c build export

to remove target files under build and export. Additional files or directories to remove can be specified using the Clean() function. Conversely, targets that would normally be removed by the -c invocation can be prevented from being removed by using the NoClean() function.

A subset of a hierarchical tree may be built by remaining at the top-level directory (where the SConstruct file lives) and specifying the subdirectory as the target to be built:

scons src/subdir

or by changing directory and invoking scons with the -u option, which traverses up the directory hierarchy until it finds the SConstruct file, and then builds targets relatively to the current subdirectory:

cd src/subdir
scons -u .

scons supports building multiple targets in parallel via a -j option that takes, as its argument, the number of simultaneous tasks that may be spawned:

scons -j 4

builds four targets in parallel, for example.

scons can maintain a cache of target (derived) files that can be shared between multiple builds. When caching is enabled in a SConscript file, any target files built by scons will be copied to the cache. If an up-to-date target file is found in the cache, it will be retrieved from the cache instead of being rebuilt locally. Caching behavior may be disabled and controlled in other ways by the --cache-force, --cache-disable, --cache-readonly, and --cache-show command-line options. The --random option is useful to prevent multiple builds from trying to update the cache simultaneously.

Values of variables to be passed to the SConscript file(s) may be specified on the command line:

scons debug=1 .

These variables are available in SConscript files through the ARGUMENTS dictionary, and can be used in the SConscript file(s) to modify the build in any way:

if ARGUMENTS.get('debug', 0):
    env = Environment(CCFLAGS = '-g')
else:
    env = Environment()

The command-line variable arguments are also available in the ARGLIST list, indexed by their order on the command line. This allows you to process them in order rather than by name, if necessary. ARGLIST[0] returns a tuple containing (argname, argvalue). A Python exception is thrown if you try to access a list member that does not exist.

scons requires Python version 2.7 or later. There should be no other dependencies or requirements to run scons.

By default, scons knows how to search for available programming tools on various systems. On Windows systems, scons searches in order for the Microsoft Visual C++ tools, the MinGW tool chain, the Intel compiler tools, and the PharLap ETS compiler. On OS/2 systems, scons searches in order for the OS/2 compiler, the GCC tool chain, and the Microsoft Visual C++ tools, On SGI IRIX, IBM AIX, Hewlett Packard HP-UX, and Sun Solaris systems, scons searches for the native compiler tools (MIPSpro, Visual Age, aCC, and Forte tools respectively) and the GCC tool chain. On all other platforms, including POSIX (Linux and UNIX) platforms, scons searches in order for the GCC tool chain, the Microsoft Visual C++ tools, and the Intel compiler tools. You may, of course, override these default values by appropriate configuration of Environment construction variables.

Options

In general, scons supports the same command-line options as GNU make, and many of those supported by cons.

-b
Ignored for compatibility with non-GNU versions of make.
-c, --clean, --remove
Clean up by removing all target files for which a construction command is specified. Also remove any files or directories associated to the construction command using the Clean() function. Will not remove any targets specified by the NoClean() function.
--cache-debug=file
Print debug information about the CacheDir() derived-file caching to the specified file. If file is - (a hyphen), the debug information are printed to the standard output. The printed messages describe what signature file names are being looked for in, retrieved from, or written to the CacheDir() directory tree.
--cache-disable, --no-cache
Disable the derived-file caching specified by CacheDir(). scons will neither retrieve files from the cache nor copy files to the cache.
--cache-force, --cache-populate
When using CacheDir(), populate a cache by copying any already-existing, up-to-date derived files to the cache, in addition to files built by this invocation. This is useful to populate a new cache with all the current derived files, or to add to the cache any derived files recently built with caching disabled via the --cache-disable option.
--cache-readonly
Use the cache (if enabled) for reading, but do not not update the cache with changed files.
--cache-show
When using CacheDir() and retrieving a derived file from the cache, show the command that would have been executed to build the file, instead of the usual report, "Retrieved `file' from cache." This will produce consistent output for build logs, regardless of whether a target file was rebuilt or retrieved from the cache.
--config=mode
This specifies how the Configure call should use or generate the results of configuration tests. The option should be specified from among the following choices:
--config=auto
scons will use its normal dependency mechanisms to decide if a test must be rebuilt or not. This saves time by not running the same configuration tests every time you invoke scons, but will overlook changes in system header files or external commands (such as compilers) if you don't specify those dependecies explicitly. This is the default behavior.
--config=force
If this option is specified, all configuration tests will be re-run regardless of whether the cached results are out of date. This can be used to explicitly force the configuration tests to be updated in response to an otherwise unconfigured change in a system header file or compiler.
--config=cache
If this option is specified, no configuration tests will be rerun and all results will be taken from cache. Note that scons will still consider it an error if --config=cache is specified and a necessary test does not yet have any results in the cache.
-C directory, --directory=directory
Change to the specified directory before searching for the SConstruct, Sconstruct, or sconstruct file, or doing anything else. Multiple -C options are interpreted relative to the previous one, and the right-most -C option wins. (This option is nearly equivalent to -f directory/SConstruct, except that it will search for SConstruct, Sconstruct, or sconstruct in the specified directory.)
-D
Works exactly the same way as the -u option except for the way default targets are handled. When this option is used and no targets are specified on the command line, all default targets are built, whether or not they are below the current directory.
--debug=type
Debug the build process. type[,type...] specifies what type of debugging. Multiple types may be specified, separated by commas. The following types are valid:
--debug=count
Print how many objects are created of the various classes used internally by SCons before and after reading the SConscript files and before and after building targets. This is not supported when SCons is executed with the Python -O (optimized) option or when the SCons modules have been compiled with optimization (that is, when executing from *.pyo files).
--debug=duplicate
Print a line for each unlink/relink (or copy) of a variant file from its source file. Includes debugging info for unlinking stale variant files, as well as unlinking old targets before building them.
--debug=dtree
A synonym for the newer --tree=derived option. This will be deprecated in some future release and ultimately removed.
--debug=explain
Print an explanation of precisely why scons is deciding to (re-)build any targets. (Note: this does not print anything for targets that are not rebuilt.)
--debug=findlibs
Instruct the scanner that searches for libraries to print a message about each potential library name it is searching for, and about the actual libraries it finds.
--debug=includes

Print the include tree after each top-level target is built. This is generally used to find out what files are included by the sources of a given derived file:

$ scons --debug=includes foo.o
--debug=memoizer
Prints a summary of hits and misses using the Memoizer, an internal subsystem that counts how often SCons uses cached values in memory instead of recomputing them each time they're needed.
--debug=memory
Prints how much memory SCons uses before and after reading the SConscript files and before and after building targets.
--debug=nomemoizer
A deprecated option preserved for backwards compatibility.
--debug=objects
Prints a list of the various objects of the various classes used internally by SCons.
--debug=pdb
Re-run SCons under the control of the pdb Python debugger.
--debug=prepare
Print a line each time any target (internal or external) is prepared for building. scons prints this for each target it considers, even if that target is up to date (see also --debug=explain). This can help debug problems with targets that aren't being built; it shows whether scons is at least considering them or not.
--debug=presub

Print the raw command line used to build each target before the construction environment variables are substituted. Also shows which targets are being built by this command. Output looks something like this:

$ scons --debug=presub
Building myprog.o with action(s):
  $SHCC $SHCFLAGS $SHCCFLAGS $CPPFLAGS $_CPPINCFLAGS -c -o $TARGET $SOURCES
...
--debug=stacktrace
Prints an internal Python stack trace when encountering an otherwise unexplained error.
--debug=stree
A synonym for the newer --tree=all,status option. This will be deprecated in some future release and ultimately removed.
--debug=time
Prints various time profiling information: the time spent executing each individual build command; the total build time (time SCons ran from beginning to end); the total time spent reading and executing SConscript files; the total time spent SCons itself spend running (that is, not counting reading and executing SConscript files); and both the total time spent executing all build commands and the elapsed wall-clock time spent executing those build commands. (When scons is executed without the -j option, the elapsed wall-clock time will typically be slightly longer than the total time spent executing all the build commands, due to the SCons processing that takes place in between executing each command. When scons is executed with the -j option, and your build configuration allows good parallelization, the elapsed wall-clock time should be significantly smaller than the total time spent executing all the build commands, since multiple build commands and intervening SCons processing should take place in parallel.)
--debug=tree
A synonym for the newer --tree=all option. This will be deprecated in some future release and ultimately removed.
--diskcheck=types
Enable specific checks for whether or not there is a file on disk where the SCons configuration expects a directory (or vice versa), and whether or not RCS or SCCS sources exist when searching for source and include files. The types argument can be set to: all, to enable all checks explicitly (the default behavior); none, to disable all such checks; match, to check that files and directories on disk match SCons' expected configuration; rcs, to check for the existence of an RCS source for any missing source or include files; sccs, to check for the existence of an SCCS source for any missing source or include files. Multiple checks can be specified separated by commas; for example, --diskcheck=sccs,rcs would still check for SCCS and RCS sources, but disable the check for on-disk matches of files and directories. Disabling some or all of these checks can provide a performance boost for large configurations, or when the configuration will check for files and/or directories across networked or shared file systems, at the slight increased risk of an incorrect build or of not handling errors gracefully (if include files really should be found in SCCS or RCS, for example, or if a file really does exist where the SCons configuration expects a directory).
--duplicate=ORDER
There are three ways to duplicate files in a build tree: hard links, soft (symbolic) links and copies. The default behaviour of SCons is to prefer hard links to soft links to copies. You can specify different behaviours with this option. ORDER must be one of hard-soft-copy (the default), soft-hard-copy, hard-copy, soft-copy or copy. SCons will attempt to duplicate files using the mechanisms in the specified order.
-f file, --file=file, --makefile=file, --sconstruct=file
Use file as the initial SConscript file. Multiple -f options may be specified, in which case scons will read all of the specified files.
-h, --help
Print a local help message for this build, if one is defined in the SConscript file(s), plus a line that describes the -H option for command-line option help. If no local help message is defined, prints the standard help message about command-line options. Exits after displaying the appropriate message.
-H, --help-options
Print the standard help message about command-line options and exit.
-i, --ignore-errors
Ignore all errors from commands executed to rebuild files.
-I directory, --include-dir=directory
Specifies a directory to search for imported Python modules. If several -I options are used, the directories are searched in the order specified.
--implicit-cache
Cache implicit dependencies. This causes scons to use the implicit (scanned) dependencies from the last time it was run instead of scanning the files for implicit dependencies. This can significantly speed up SCons, but with the following limitations:

scons will not detect changes to implicit dependency search paths (e.g. CPPPATH, LIBPATH) that would ordinarily cause different versions of same-named files to be used.

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, LIBPATH) than a current implicit dependency with the same name.

--implicit-deps-changed
Forces SCons to ignore the cached implicit dependencies. This causes the implicit dependencies to be rescanned and recached. This implies --implicit-cache.
--implicit-deps-unchanged
Force SCons to ignore changes in the implicit dependencies. This causes cached implicit dependencies to always be used. This implies --implicit-cache.
--interactive

Starts SCons in interactive mode. The SConscript files are read once and a scons>>> prompt is printed. Targets may now be rebuilt by typing commands at interactive prompt without having to re-read the SConscript files and re-initialize the dependency graph from scratch.

SCons interactive mode supports the following commands:

build[Options] [TARGETS] ...
Builds the specified TARGETS (and their dependencies) with the specified SCons command-line Options. b and scons are synonyms.

The following SCons command-line options affect the build command:

--cache-debug=FILE
--cache-disable, --no-cache
--cache-force, --cache-populate
--cache-readonly
--cache-show
--debug=TYPE
-i, --ignore-errors
-j N, --jobs=N
-k, --keep-going
-n, --no-exec, --just-print, --dry-run, --recon
-Q
-s, --silent, --quiet
--taskmastertrace=FILE
--tree=OPTIONS

Any other SCons command-line options that are specified do not cause errors but have no effect on the build command (mainly because they affect how the SConscript files are read, which only happens once at the beginning of interactive mode).

clean[Options] [TARGETS] ...
Cleans the specified TARGETS (and their dependencies) with the specified options. c is a synonym. This command is itself a synonym for build --clean

exit
Exits SCons interactive mode. You can also exit by terminating input (CTRL+D on UNIX or Linux systems, CTRL+Z on Windows systems).

help[COMMAND]
Provides a help message about the commands available in SCons interactive mode. If COMMAND is specified, h and ? are synonyms.

shell[COMMANDLINE]
Executes the specified COMMANDLINE in a subshell. If no COMMANDLINE is specified, executes the interactive command interpreter specified in the SHELL environment variable (on UNIX and Linux systems) or the COMSPEC environment variable (on Windows systems). sh and ! are synonyms.

version
Prints SCons version information.

An empty line repeats the last typed command. Command-line editing can be used if the readline module is available.

$ scons --interactive
scons: Reading SConscript files ...
scons: done reading SConscript files.
scons>>> build -n prog
scons>>> exit
-j N, --jobs=N
Specifies the number of jobs (commands) to run simultaneously. If there is more than one -j option, the last one is effective.
-k, --keep-going
Continue as much as possible after an error. The target that failed and those that depend on it will not be remade, but other targets specified on the command line will still be processed.
-m
Ignored for compatibility with non-GNU versions of make.
--max-drift=SECONDS
Set the maximum expected drift in the modification time of files to SECONDS. This value determines how long a file must be unmodified before its cached content signature will be used instead of calculating a new content signature (MD5 checksum) of the file's contents. The default value is 2 days, which means a file must have a modification time of at least two days ago in order to have its cached content signature used. A negative value means to never cache the content signature and to ignore the cached value if there already is one. A value of 0 means to always use the cached signature, no matter how old the file is.
--md5-chunksize=KILOBYTES
Set the block size used to compute MD5 signatures to KILOBYTES. This value determines the size of the chunks which are read in at once when computing MD5 signatures. Files below that size are fully stored in memory before performing the signature computation while bigger files are read in block-by-block. A huge block-size leads to high memory consumption while a very small block-size slows down the build considerably.

The default value is to use a chunk size of 64 kilobytes, which should be appropriate for most uses.
-n, --just-print, --dry-run, --recon
No execute. Print the commands that would be executed to build any out-of-date target files, but do not execute the commands.
--no-site-dir
Prevents the automatic addition of the standard site_scons dirs to sys.path. Also prevents loading the site_scons/site_init.py modules if they exist, and prevents adding their site_scons/site_tools dirs to the toolpath.
--profile=file
Run SCons under the Python profiler and save the results in the specified file. The results may be analyzed using the Python pstats module.
-q, --question
Do not run any commands, or print anything. Just return an exit status that is zero if the specified targets are already up to date, non-zero otherwise.
-Q
Quiets SCons status messages about reading SConscript files, building targets and entering directories. Commands that are executed to rebuild target files are still printed.
--random
Build dependencies in a random order. This is useful when building multiple trees simultaneously with caching enabled, to prevent multiple builds from simultaneously trying to build or retrieve the same target files.
-s, --silent, --quiet
Silent. Do not print commands that are executed to rebuild target files. Also suppresses SCons status messages.
-S, --no-keep-going, --stop
Ignored for compatibility with GNU make.
--site-dir=dir
Uses the named dir as the site dir rather than the default site_scons dirs. This dir will get prepended to sys.path, the module dir/site_init.py will get loaded if it exists, and dir/site_tools will get added to the default toolpath.

The default set of site_scons dirs used when --site-dir is not specified depends on the system platform, as follows. Note that the directories are examined in the order given, from most generic to most specific, so the last-executed site_init.py file is the most specific one (which gives it the chance to override everything else), and the dirs are prepended to the paths, again so the last dir examined comes first in the resulting path.

Windows:

%ALLUSERSPROFILE/Application Data/scons/site_scons
%USERPROFILE%/Local Settings/Application Data/scons/site_scons
%APPDATA%/scons/site_scons
%HOME%/.scons/site_scons
./site_scons

Mac OS X:

/Library/Application Support/SCons/site_scons
/opt/local/share/scons/site_scons (for MacPorts)
/sw/share/scons/site_scons (for Fink)
$HOME/Library/Application Support/SCons/site_scons
$HOME/.scons/site_scons
./site_scons

Solaris:

/opt/sfw/scons/site_scons
/usr/share/scons/site_scons
$HOME/.scons/site_scons
./site_scons

Linux, HPUX, and other Posix-like systems:

/usr/share/scons/site_scons
$HOME/.scons/site_scons
./site_scons
--stack-size=KILOBYTES
Set the size stack used to run threads to KILOBYTES. This value determines the stack size of the threads used to run jobs. These are the threads that execute the actions of the builders for the nodes that are out-of-date. Note that this option has no effect unless the num_jobs option, which corresponds to -j and --jobs, is larger than one. Using a stack size that is too small may cause stack overflow errors. This usually shows up as segmentation faults that cause scons to abort before building anything. Using a stack size that is too large will cause scons to use more memory than required and may slow down the entire build process.

The default value is to use a stack size of 256 kilobytes, which should be appropriate for most uses. You should not need to increase this value unless you encounter stack overflow errors.
-t, --touch
Ignored for compatibility with GNU make. (Touching a file to make it appear up-to-date is unnecessary when using scons.)
--taskmastertrace=file
Prints trace information to the specified file about how the internal Taskmaster object evaluates and controls the order in which Nodes are built. A file name of - may be used to specify the standard output.
-tree=options
Prints a tree of the dependencies after each top-level target is built. This prints out some or all of the tree, in various formats, depending on the options specified:
--tree=all
Print the entire dependency tree after each top-level target is built. This prints out the complete dependency tree, including implicit dependencies and ignored dependencies.
--tree=derived
Restricts the tree output to only derived (target) files, not source files.
--tree=status
Prints status information for each displayed node.
--tree=prune
Prunes the tree to avoid repeating dependency information for nodes that have already been displayed. Any node that has already been displayed will have its name printed in [square brackets], as an indication that the dependencies for that node can be found by searching for the relevant output higher up in the tree.

Multiple options may be specified, separated by commas:

# Prints only derived files, with status information:
scons --tree=derived,status

# Prints all dependencies of target, with status information
# and pruning dependencies of already-visited Nodes:
scons --tree=all,prune,status target
-u, --up, --search-up
Walks up the directory structure until an SConstruct , Sconstruct or sconstruct file is found, and uses that as the top of the directory tree. If no targets are specified on the command line, only targets at or below the current directory will be built.
-U
Works exactly the same way as the -u option except for the way default targets are handled. When this option is used and no targets are specified on the command line, all default targets that are defined in the SConscript(s) in the current directory are built, regardless of what directory the resultant targets end up in.
-v, --version
Print the scons version, copyright information, list of authors, and any other relevant information. Then exit.
-w, --print-directory
Print a message containing the working directory before and after other processing.
--no-print-directory
Turn off -w, even if it was turned on implicitly.
--warn=type, --warn=no-type
Enable or disable warnings. type specifies the type of warnings to be enabled or disabled:
--warn=all, --warn=no-all
Enables or disables all warnings.
--warn=cache-version, --warn=no-cache-version
Enables or disables warnings about the cache directory not using the latest configuration information CacheDir(). These warnings are enabled by default.
--warn=cache-write-error, --warn=no-cache-write-error
Enables or disables warnings about errors trying to write a copy of a built file to a specified CacheDir(). These warnings are disabled by default.
--warn=corrupt-sconsign, --warn=no-corrupt-sconsign
Enables or disables warnings about unfamiliar signature data in .sconsign files. These warnings are enabled by default.
--warn=dependency, --warn=no-dependency
Enables or disables warnings about dependencies. These warnings are disabled by default.
--warn=deprecated, --warn=no-deprecated

Enables or disables all warnings about use of currently deprecated features. These warnings are enabled by default. Note that the --warn=no-deprecated option does not disable warnings about absolutely all deprecated features. Warnings for some deprecated features that have already been through several releases with deprecation warnings may be mandatory for a release or two before they are officially no longer supported by SCons. Warnings for some specific deprecated features may be enabled or disabled individually; see below.

--warn=deprecated-copy, --warn=no-deprecated-copy
Enables or disables warnings about use of the deprecated env.Copy() method.

--warn=deprecated-source-signatures, --warn=no-deprecated-source-signatures
Enables or disables warnings about use of the deprecated SourceSignatures() function or env.SourceSignatures() method.

--warn=deprecated-target-signatures, --warn=no-deprecated-target-signatures
Enables or disables warnings about use of the deprecated TargetSignatures() function or env.TargetSignatures() method.

--warn=duplicate-environment, --warn=no-duplicate-environment
Enables or disables warnings about attempts to specify a build of a target with two different construction environments that use the same action. These warnings are enabled by default.
--warn=fortran-cxx-mix, --warn=no-fortran-cxx-mix
Enables or disables the specific warning about linking Fortran and C++ object files in a single executable, which can yield unpredictable behavior with some compilers.
--warn=future-deprecated, --warn=no-future-deprecated
Enables or disables warnings about features that will be deprecated in the future. These warnings are disabled by default. Enabling this warning is especially recommended for projects that redistribute SCons configurations for other users to build, so that the project can be warned as soon as possible about to-be-deprecated features that may require changes to the configuration.
--warn=link, --warn=no-link
Enables or disables warnings about link steps.
--warn=misleading-keywords, --warn=no-misleading-keywords
Enables or disables warnings about use of the misspelled keywords targets and sources when calling Builders. (Note the last s characters, the correct spellings are target and source.) These warnings are enabled by default.
--warn=missing-sconscript, --warn=no-missing-sconscript
Enables or disables warnings about missing SConscript files. These warnings are enabled by default.
--warn=no-md5-module, --warn=no-no-md5-module
Enables or disables warnings about the version of Python not having an MD5 checksum module available. These warnings are enabled by default.
--warn=no-metaclass-support, --warn=no-no-metaclass-support
Enables or disables warnings about the version of Python not supporting metaclasses when the --debug=memoizer option is used. These warnings are enabled by default.
--warn=no-object-count, --warn=no-no-object-count
Enables or disables warnings about the --debug=object feature not working when scons is run with the python -O option or from optimized Python (.pyo) modules.
--warn=no-parallel-support, --warn=no-no-parallel-support
Enables or disables warnings about the version of Python not being able to support parallel builds when the -j option is used. These warnings are enabled by default.
--warn=python-version, --warn=no-python-version
Enables or disables the warning about running SCons with a deprecated version of Python. These warnings are enabled by default.
--warn=reserved-variable, --warn=no-reserved-variable
Enables or disables warnings about attempts to set the reserved construction variable names CHANGED_SOURCES, CHANGED_TARGETS, TARGET, TARGETS, SOURCE, SOURCES, UNCHANGED_SOURCES or UNCHANGED_TARGETS. These warnings are disabled by default.
--warn=stack-size, --warn=no-stack-size
Enables or disables warnings about requests to set the stack size that could not be honored. These warnings are enabled by default.
--warn=target_not_build, --warn=no-target_not_built
Enables or disables warnings about a build rule not building the expected targets. These warnings are not currently enabled by default.
-Y repository, --repository=repository, --srcdir=repository
Search the specified repository for any input and target files not found in the local directory hierarchy. Multiple -Y options may be specified, in which case the repositories are searched in the order specified.

Configuration File Reference

Construction Environments

A construction environment is the basic means by which the SConscript files communicate build information to scons. A new construction environment is created using the Environment function:

env = Environment()

Variables, called construction variables, may be set in a construction environment either by specifying them as keywords when the object is created or by assigning them a value after the object is created:

env = Environment(FOO = 'foo')
env['BAR'] = 'bar'

As a convenience, construction variables may also be set or modified by the parse_flags keyword argument, which applies the ParseFlags method (described below) to the argument value after all other processing is completed. This is useful either if the exact content of the flags is unknown (for example, read from a control file) or if the flags are distributed to a number of construction variables.

env = Environment(parse_flags = '-Iinclude -DEBUG -lm')

This example adds 'include' to CPPPATH, 'EBUG' to CPPDEFINES, and 'm' to LIBS.

By default, a new construction environment is initialized with a set of builder methods and construction variables that are appropriate for the current platform. An optional platform keyword argument may be used to specify that an environment should be initialized for a different platform:

env = Environment(platform = 'cygwin')
env = Environment(platform = 'os2')
env = Environment(platform = 'posix')
env = Environment(platform = 'win32')

Specifying a platform initializes the appropriate construction variables in the environment to use and generate file names with prefixes and suffixes appropriate for the platform.

Note that the win32 platform adds the SystemDrive and SystemRoot variables from the user's external environment to the construction environment's ENV dictionary. This is so that any executed commands that use sockets to connect with other systems (such as fetching source files from external CVS repository specifications like :pserver:anonymous@cvs.sourceforge.net:/cvsroot/scons) will work on Windows systems.

The platform argument may be function or callable object, in which case the Environment() method will call the specified argument to update the new construction environment:

def my_platform(env):
    env['VAR'] = 'xyzzy'

env = Environment(platform = my_platform)

Additionally, a specific set of tools with which to initialize the environment may be specified as an optional keyword argument:

env = Environment(tools = ['msvc', 'lex'])

Non-built-in tools may be specified using the toolpath argument:

env = Environment(tools = ['default', 'foo'], toolpath = ['tools'])

This looks for a tool specification in tools/foo.py (as well as using the ordinary default tools for the platform). foo.py should have two functions: generate(env, **kw) and exists(env). The generate() function modifies the passed-in environment to set up variables so that the tool can be executed; it may use any keyword arguments that the user supplies (see below) to vary its initialization. The exists() function should return a true value if the tool is available. Tools in the toolpath are used before any of the built-in ones. For example, adding gcc.py to the toolpath would override the built-in gcc tool. Also note that the toolpath is stored in the environment for use by later calls to Clone() and Tool() methods:

base = Environment(toolpath=['custom_path'])
derived = base.Clone(tools=['custom_tool'])
derived.CustomBuilder()

The elements of the tools list may also be functions or callable objects, in which case the Environment() method will call the specified elements to update the new construction environment:

def my_tool(env):
    env['XYZZY'] = 'xyzzy'

env = Environment(tools = [my_tool])

The individual elements of the tools list may also themselves be two-element lists of the form (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 function. 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, **kw):
  # Sets MY_TOOL to the value of keyword argument 'arg1' or 1.
  env['MY_TOOL'] = kw.get('arg1', '1')
def exists(env):
  return 1

# in SConstruct:
env = Environment(tools = ['default', ('my_tool', {'arg1': 'abc'})],
                  toolpath=['tools'])

The tool definition (i.e. my_tool()) can use the PLATFORM variable from the environment it receives to customize the tool for different platforms.

If no tool list is specified, then SCons will auto-detect the installed tools using the PATH variable in the ENV construction variable and the platform name when the Environment is constructed. Changing the PATH variable after the Environment is constructed will not cause the tools to be redetected.

SCons supports the following tool specifications out of the box:

386asm

Sets construction variables for the 386ASM assembler for the Phar Lap ETS embedded operating system.

Sets: $AS, $ASCOM, $ASFLAGS, $ASPPCOM, $ASPPFLAGS.

Uses: $CC, $CPPFLAGS, $_CPPDEFFLAGS, $_CPPINCFLAGS.

aixc++

Sets construction variables for the IMB xlc / Visual Age C++ compiler.

Sets: $CXX, $CXXVERSION, $SHCXX, $SHOBJSUFFIX.

aixcc

Sets construction variables for the IBM xlc / Visual Age C compiler.

Sets: $CC, $CCVERSION, $SHCC.

aixf77

Sets construction variables for the IBM Visual Age f77 Fortran compiler.

Sets: $F77, $SHF77.

aixlink

Sets construction variables for the IBM Visual Age linker.

Sets: $LINKFLAGS, $SHLIBSUFFIX, $SHLINKFLAGS.

applelink

Sets construction variables for the Apple linker (similar to the GNU linker).

Sets: $FRAMEWORKPATHPREFIX, $LDMODULECOM, $LDMODULEFLAGS, $LDMODULEPREFIX, $LDMODULESUFFIX, $LINKCOM, $SHLINKCOM, $SHLINKFLAGS, $_FRAMEWORKPATH, $_FRAMEWORKS.

Uses: $FRAMEWORKSFLAGS.

ar

Sets construction variables for the ar library archiver.

Sets: $AR, $ARCOM, $ARFLAGS, $LIBPREFIX, $LIBSUFFIX, $RANLIB, $RANLIBCOM, $RANLIBFLAGS.

as

Sets construction variables for the as assembler.

Sets: $AS, $ASCOM, $ASFLAGS, $ASPPCOM, $ASPPFLAGS.

Uses: $CC, $CPPFLAGS, $_CPPDEFFLAGS, $_CPPINCFLAGS.

bcc32

Sets construction variables for the bcc32 compiler.

Sets: $CC, $CCCOM, $CCFLAGS, $CFILESUFFIX, $CFLAGS, $CPPDEFPREFIX, $CPPDEFSUFFIX, $INCPREFIX, $INCSUFFIX, $SHCC, $SHCCCOM, $SHCCFLAGS, $SHCFLAGS, $SHOBJSUFFIX.

Uses: $_CPPDEFFLAGS, $_CPPINCFLAGS.

BitKeeper

Sets construction variables for the BitKeeper source code control system.

Sets: $BITKE