SCons &buildversion;

MAN page

The SCons Development Team
Released &builddate;
©right_years; The SCons Foundation
Version &buildversion;

# SCons &buildversion;

MAN page

SCONS 1 SCons __VERSION__ SCons __VERSION__
scons a software construction tool
`scons` options name=val targets

### DESCRIPTION

&scons; orchestrates the construction of software (and other tangible products such as documentation files) by determining which component pieces must be built or rebuilt and invoking the necessary commands to 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 information about previous builds so details do not have to be recalculated each run.

&scons; requires &Python; 3.6 or later to run; there should be no other dependencies or requirements, unless the experimental Ninja tool is used.

Changed in version 4.3.0: support for &Python; 3.5 is removed; the CPython project has retired 3.5: .

You set up an &SCons; build system by writing a script that describes things to build (targets), and, if 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, 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 level of abstraction above that of pure filenames. For example if you specify a library target named "foo", &SCons; keeps track of the actual operating system dependent filename (such as `libfoo.so` on a GNU/Linux system), and how to refer to that library in later construction steps that want to use it, so you don't have to specify that precise information yourself. &SCons; can also scan automatically for dependency information, such as header files included by source code files (for example, `#include` preprocessor directives in C or C++ files), so these implicit dependencies do not have to be specified manually. &SCons; supports 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 of source files, is cached for later reuse. By default this hash (the &contentsig;) is used to determine if a file has changed since the last build, although this can be controlled by selecting an appropriate &f-link-Decider; function. Implicit dependency files are also part of out-of-date computation. The scanned implicit dependency information can optionally be cached and used to speed up future builds. A hash of each executed build action (the &buildsig;) is cached, so that changes to build instructions (changing flags, etc.) or to the build tools themselves (new version) can also trigger a rebuild.

&SCons; supports the concept of separated source and build directories through the definition of variant directories (see the &f-link-VariantDir; function).

When invoked, &scons; looks for a file named &SConstruct; in the current directory and reads the build configuration from that file (other names are allowed, see and the `-f` option for more information). The build may be structured in a hierarchical manner: the &SConstruct; file may specify subsidiary configuration files by calling the &f-link-SConscript; function, and these may, in turn, do the same. By convention, these subsidiary files are named &SConscript;, although any name may be used. As a result of this naming convention, the term &SConscript; files is used to refer generically to the complete set of configuration files for a project (including the &SConstruct; file), regardless of the actual file names or number of such files. A hierarchical build is not recursive - all of the SConscript files are processed in a single pass, although each is processed in a separate context so as not to interfere with one another. &SCons; provides mechanisms for information to be shared between SConscript files when needed.

Before reading the &SConscript; files, &scons; looks for a directory named `site_scons` in various system directories and in the directory containing the &SConstruct; file or, if specified, the directory from the `--site-dir` option instead, and prepends the ones it finds to the &Python; module search path (`sys.path`), thus allowing modules in such directories to be imported in the normal &Python; way in &SConscript; files. For each found site directory, (1) if it contains a file `site_init.py` that file is evaluated, and (2) if it contains a directory `site_tools` the path to that directory is prepended to the default toolpath. See the `--site-dir` and `--no-site-dir` options for details on default paths and controlling the site directories.

&SConscript; files are written in the &Python; programming language, although it is normally not necessary to be a &Python; programmer to use &scons; effectively. &SConscript; files are invoked in a context that makes the facilities described in this manual page available in their local namespace without any special steps. Standard &Python; scripting capabilities such as flow control, data manipulation, and imported &Python; libraries are available to use to handle complicated build situations. Other &Python; files can be made a part of the build system, but they do not automatically have the &SCons; context and need to import it if they need access (described later).

&scons; reads and executes all of the included &SConscript; files before it begins building any targets. To make this clear, &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 (lines beginning with the `scons:` tag) may be suppressed using the `-Q` option.

To assure reproducible builds, &SCons; uses a restricted execution environment for running external commands used to build targets, rather then propagating the full environment in effect at the time &scons; was called. This helps avoid problems like picking up accidental settings, temporary debug values that are no longer needed, or one developer having different settings than another (or than the CI/CD pipeline). Environment variables that are needed for proper operation of such commands need to be set explicitly, which can be done either by assigning the desired values, or by picking values individually out of environment variables using the &Python; os.environ dictionary. The execution environment for a given &consenv; is contained in its &cv-link-ENV; &consvar;. A few environment variables are picked up automatically - see ).

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 explicitly 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
    env = Environment(ENV={'PATH': os.environ['PATH']})

Similarly, if the commands use specific external environment variables that &scons; does not recognize, they can be propagated into the execution environment:

    import os

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

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

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

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. It should not cause problems if done in a build setup which tightly controls how the environment is set up before invoking &scons;, as in many continuous integration setups.

&scons; is normally executed in a top-level directory containing an &SConstruct; file. When &scons; is invoked, the command line (including the contents of the &SCONSFLAGS; environment variable, if set) is processed. Command-line options (see ) are consumed. Any variable argument assignments 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:

    scons debug=1

These variables are available through the &ARGUMENTS; dictionary, and can be used in the &SConscript; files 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. Each &ARGLIST; entry is a tuple containing (argname, argvalue).

See for more information.

&scons; can maintain a cache of target (derived) files that can be shared between multiple builds. When derived-file caching is enabled in an &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.

By default, &scons; searches for known programming tools on various systems and initializes itself based on what is found. On Windows systems which identify as win32, &scons; searches in order for the Microsoft Visual C++ tools, the MinGW tool chain, the Intel compiler tools, and the PharLap ETS compiler. On Windows system which identify as cygwin (that is, if &scons; is invoked from a cygwin shell), the order changes to prefer the GCC toolchain over the MSVC tools. 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 Oracle 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, and the Intel compiler tools. These default values may be overridden by appropriate setting of &consvars;.

#### Target Selection

&SCons; acts on the selected targets, whether the requested operation is build, no-exec or clean. Targets are selected as follows:

1. Targets specified on the command line. These may be files, directories, or phony targets defined using the &f-link-Alias; function. Directory targets are scanned by &scons; for any targets that may be found with a destination in or under that directory. The targets listed on the command line are made available in the &COMMAND_LINE_TARGETS; list.

2. If no targets are specified on the command line, &scons; will select those targets specified in the &SConscript; files via calls to the &f-link-Default; function. These are known as the default targets, and are made available in the &DEFAULT_TARGETS; list.

3. If no targets are selected by the previous steps, &scons; selects the current directory for scanning, unless command-line options which affect the directory for target scanning are present (`-C`, `-D`, `-u`, `-U`). Since targets thus selected were not the result of user instructions, this target list is not made available for direct inspection; use the `--debug=explain` option if they need to be examined.

4. &scons; always adds to the selected targets any intermediate targets which are necessary to build the specified ones. For example, if constructing a shared library or dll from C source files, &scons; will also build the object files which will make up the library.

To ignore the default targets specified through calls to &Default; and instead build all target files in or below the current directory specify the current directory (`.`) as a command-line target:

    scons .

To build all target files, including any files outside of the current directory, supply 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:\

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 build:

    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 (see also the related `-D` and `-U` options):

    cd src/subdir
    scons -u .

In all cases, more files may be built than are requested, as &scons; needs to make sure any dependent files are built.

Specifying "cleanup" targets in &SConscript; files is usually not necessary. The `-c` flag removes all selected targets:

    scons -c .

to remove all target files in or under the current directory, or:

    scons -c build export

to remove target files under `build` and `export`.

Additional files or directories to remove can be specified using the &f-link-Clean; function in the &SConscript; files. Conversely, targets that would normally be removed by the `-c` invocation can be retained by calling the &f-link-NoClean; function with those targets.

&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.

### 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`

  Set clean mode. Clean up by removing the selected targets, well as any files or directories associated with a selected target through calls to the &f-link-Clean; function. Will not remove any targets which are marked for preservation through calls to the &f-link-NoClean; function.

  While clean mode removes targets rather than building them, work which is done directly in &Python; code in &SConscript; files will still be carried out. If it is important to avoid some such work from taking place in clean mode, it should be protected. An &SConscript; file can determine which mode is active by querying &f-link-GetOption;, as in the call `if GetOption("clean"):`

`--cache-debug=file`

  Write debug information about derived-file caching to the specified file. If file is a hyphen (`-`), the debug information is printed to the standard output. The printed messages describe what signature-file names are being looked for in, retrieved from, or written to the derived-file cache specified by &f-link-CacheDir;.

`--cache-disable`, `--no-cache`

  Disable derived-file caching. &scons; will neither retrieve files from the cache nor copy files to the cache. This option can be used to temporarily disable the cache without modifying the build scripts.

`--cache-force`, `--cache-populate`

  When using &f-link-CacheDir;, populate a derived-file 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 derived-file cache, if enabled, to retrieve files, but do not not update the cache with any files actually built during this invocation.

`--cache-show`

  When using a derived-file cache show the command that would have been executed to build the file (or the corresponding `*COMSTR` contents if set) even if the file is retrieved from cache. Without this option, &scons; shows a cache retrieval message if the file is fetched from cache. This allows producing consistent output for build logs, regardless of whether a target file was rebuilt or retrieved from the cache.

`--config=mode`

  Control how the &f-link-Configure; call should use or generate the results of configuration tests. mode should be one of the following choices:

  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.

  force

    If this mode 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.

  cache

    If this mode is specified, no configuration tests will be rerun and all results will be taken from cache. &scons; will report an error if `--config=cache` is specified and a necessary test does not have any results in the cache.

`-C directory`, `--directory=directory`

  Run as if &scons; was started in directory instead of the current working directory. That is, change directory before searching for the &SConstruct;, &Sconstruct;, &sconstruct;, &SConstruct.py;, &Sconstruct.py; or &sconstruct.py; file or doing anything else. When multiple `-C` options are given, each subsequent non-absolute `-C` directory is interpreted relative to the preceding one. This option is similar to using `-f directory/SConstruct`, but `-f` does not search for any of the predefined &SConstruct; names in the specified directory. See also options `-u`, `-U` and `-D` to change the &SConstruct; search behavior when this option is used.

`-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[,type...]`

  Debug the build process. type specifies the kind of debugging info to emit. Multiple types may be specified, separated by commas. The following types are recognized:

  action-timestamps

    Prints additional time profiling information. For each command, shows the absolute start and end times. This may be useful in debugging parallel builds. Implies the `--debug=time` option.

    New in version 3.1.

  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).

  duplicate

    Print a line for each unlink/relink (or copy) of a file in a variant directory from its source file. Includes debugging info for unlinking stale variant directory files, as well as unlinking old targets before building them.

  explain

    Print an explanation of why &scons; is deciding to (re-)build the targets it selects for building.

  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.

  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

  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.

  memory

    Prints how much memory SCons uses before and after reading the &SConscript; files and before and after building targets.

  objects

    Prints a list of the various objects of the various classes used internally by SCons.

  pdb

    Re-run &scons; under the control of the pdb &Python; debugger.

  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.

  presub

    Print the raw command line used to build each target before the &consenv; 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
        ...

  stacktrace

    Prints an internal &Python; stack trace when encountering an otherwise unexplained error.

  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 SCons itself spent running (that is, not counting reading and executing &SConscript; files)

    - The total time spent executing all build commands

    - The elapsed wall-clock time spent executing those build commands

    - The time spent processing each file passed to the &f-link-SConscript; function

    (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.)

`--diskcheck=type`

  Enable specific checks for whether or not there is a file on disk where the SCons configuration expects a directory (or vice versa) when searching for source and include files. type can be an available diskcheck type or the special tokens `all` or `none`. A comma-separated string can be used to select multiple checks. The default setting is `all`.

  Current available checks are:

  match

    to check that files and directories on disk match SCons' expected configuration.

  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.

`--duplicate=ORDER`

  There are three ways to duplicate files in a build tree: hard links, soft (symbolic) links and copies. The default policy is to prefer hard links to soft links to copies. You can specify a different policy 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.

`--enable-virtualenv`

  Import virtualenv-related variables to SCons.

`--experimental=feature`

  Enable experimental features and/or tools. feature can be an available feature name or the special tokens `all` or `none`. A comma-separated string can be used to select multiple features. The default setting is `none`.

  Current available features are: `ninja` (added in version 4.2), `tm_v2` (added in version 4.4.1).

  No Support offered for any features or tools enabled by this flag.

  New in version 4.2 (experimental).

`-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 project, if one is defined in the &SConscript; files (see the &f-link-Help; function), plus a line that refers to the standard &SCons; help message. If no local help message is defined, prints the standard &SCons; help message (as for the `-H` option) plus help for any local options defined through &f-link-AddOption;. Exits after displaying the appropriate message.

  Note that use of this option requires &SCons; to process the &SConscript; files, so syntax errors may cause the help message not to be displayed.

`--hash-chunksize=KILOBYTES`

  Set the block size used when computing &contentsigs; to KILOBYTES. This value determines the size of the chunks which are read in at once when computing signature hashes. 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.

  New in version 4.2.

`--hash-format=ALGORITHM`

  Set the hashing algorithm used by SCons to ALGORITHM. This value determines the hashing algorithm used in generating &contentsigs;, &buildsigs; and &CacheDir; keys.

  The supported list of values are: md5, sha1 and sha256. However, the &Python; interpreter used to run &scons; must have the corresponding support available in the hashlib module to use the specified algorithm.

  If this option is omitted, the first supported hash format found is selected. Typically this is MD5, however, on a FIPS-compliant system using a version of &Python; older than 3.9, SHA1 or SHA256 is chosen as the default. &Python; 3.9 and onwards clients always default to MD5, even in FIPS mode.

  Specifying this option changes the name of the SConsign database. The default database is `.sconsign.dblite`. In the presence of this option, ALGORITHM is included in the name to indicate the difference, even if the argument is md5. For example, `--hash-format=sha256` uses a SConsign database named `.sconsign_sha256.dblite`.

  New in version 4.2.

`-H`, `--help-options`

  Print the standard help message about &SCons; 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.

`--ignore-virtualenv`

  Suppress importing virtualenv-related variables to SCons.

`--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. &cv-link-CPPPATH;, &cv-link-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. &cv-link-CPPPATH;, &cv-link-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`.

`--install-sandbox=sandbox_path`

  When using the &Install; builders, prepend sandbox_path to the installation paths such that all installed files will be placed under that directory. This option is unavailable if one of &b-link-Install;, &b-link-InstallAs; or &b-link-InstallVersionedLib; is not used in the &SConscript; files.

`--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 for build.

    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 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 maximum number of comcurrent jobs (commands) to run. 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 &contentsig; will be used instead of calculating a new &contentsig; (hash) 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 &contentsig; used. A negative value means to never cache the &contentsig; 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`

  A deprecated synonym for `--hash-chunksize`.

  Changed in version 4.2: deprecated.

`-n`, `--no-exec`, `--just-print`, `--dry-run`, `--recon`

  Set no-exec mode. Print the commands that would be executed to build any out-of-date targets, but do not execute those commands.

  Only target building is suppressed - any work in the build system that is done directly (in regular &Python; code) will still be carried out. You can add guards around code which should not be executed in no-exec mode by checking the value of the option at run time with &f-link-GetOption;:

      if not GetOption("no_exec"):
          # run regular instructions

  The output is a best effort, as &SCons; cannot always precisely determine what would be built. For example, if a file generated by a builder action is also used as a source in the build, that file is not available to scan for dependencies at all in an unbuilt tree, and may contain out of date information in a previously built tree.

`--no-site-dir`

  Prevents the automatic addition of the standard `site_scons` directories to `sys.path`. Also prevents loading the `site_scons/site_init.py` modules if they exist, and prevents adding their `site_scons/site_tools` directories to the toolpath.

`--package-type=type`

  The type of package to create when using the &b-link-Package; builder. Multiple types can be specified by using a comma-separated string, in which case &SCons; will try to build for all of those package types. Note this option is only available if the &t-link-packaging; tool has been enabled.

`--profile=file`

  Run &SCons; under the &Python; profiler and save the results to 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`

  Suppress 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=path`

  Use a specific path as the site directory rather than searching the list of default site directories. This directory will be prepended to `sys.path`, the module `path/site_init.py` will be loaded if it exists, and `path/site_tools` will be added to the default toolpath.

  The default set of site directories searched when `--site-dir` is not specified depends on the system platform, as follows. Users or system administrators can tune site-specific or project-specific &SCons; behavior by setting up a site directory in one or more of these locations. Directories are examined in the order given, from most generic ("system" directories) to most specific (in the current project), so the last-executed `site_init.py` file is the most specific one, giving it the chance to override everything else), and the directories are prepended to the paths, again so the last directory examined comes first in the resulting path.

  Windows:

        %ALLUSERSPROFILE%/scons/site_scons
        %LOCALAPPDATA%/scons/site_scons
        %APPDATA%/scons/site_scons
        %USERPROFILE%/.scons/site_scons
        ./site_scons

    Note earlier versions of the documentation listed a different path for the "system" site directory, this path is still checked but its use is discouraged:

        %ALLUSERSPROFILE%/Application Data/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 threads execute the actions of the builders for the nodes that are out-of-date. This option has no effect unless the number of concurrent build jobs is larger than one (as set by `-j N` or `--jobs=N` on the command line or &SetOption; in a script).

  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=type[,type...]`

  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 type specified:

  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.

  derived

    Restricts the tree output to only derived (target) files, not source files.

  linedraw

    Draw the tree output using Unicode line-drawing characters instead of plain ASCII text. This option acts as a modifier to the selected type(s). If specified alone, without any type, it behaves as if all had been specified.

    New in version 4.0.

  status

    Prints status information for each displayed node.

  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 type choices 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;, &sconstruct;, &SConstruct.py;, &Sconstruct.py; or &sconstruct.py; 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; file(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 (with the prefix "no-") warnings (`--warning` is a synonym). type specifies the type of warnings to be enabled or disabled:

  all

    All warnings.

  cache-version

    Warnings about the derived-file cache directory specified by &f-link-CacheDir; not using the latest configuration information. These warnings are enabled by default.

  cache-write-error

    Warnings about errors trying to write a copy of a built file to a specified derived-file cache specified by &f-link-CacheDir;. These warnings are disabled by default.

  corrupt-sconsign

    Warnings about unfamiliar signature data in `.sconsign` files. These warnings are enabled by default.

  dependency

    Warnings about dependencies. These warnings are disabled by default.

  deprecated

    Warnings about use of currently deprecated features. These warnings are enabled by default. Not all deprecation warnings can be disabled with the `--warn=no-deprecated` option as some deprecated features which are late in the deprecation cycle may have been designated as mandatory warnings, and these will still display. Warnings for certain deprecated features may also be enabled or disabled individually; see below.

  duplicate-environment

    Warnings about attempts to specify a build of a target with two different &consenvs; that use the same action. These warnings are enabled by default.

  fortran-cxx-mix

    Warnings about linking Fortran and C++ object files in a single executable, which can yield unpredictable behavior with some compilers.

  future-deprecated

    Warnings about features that will be deprecated in the future. Such warnings are disabled by default. Enabling future deprecation warnings is 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.

  link

    Warnings about link steps.

  misleading-keywords

    Warnings about the use of two commonly misspelled keywords targets and sources to &f-link-Builder; calls. The correct spelling is the singular form, even though target and source can themselves refer to lists of names or nodes.

  tool-qt-deprecated

    Warnings about the &t-link-qt; tool being deprecated. These warnings are disabled by default for the first phase of deprecation. Enable to be reminded about use of this tool module. New in version 4.3.

  missing-sconscript

    Warnings about missing &SConscript; files. These warnings are enabled by default.

  no-object-count

    Warnings about the `--debug=object` feature not working when &scons; is run with the &Python; `-O` option or from optimized &Python; (`.pyo`) modules.

  no-parallel-support

    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.

  python-version

    Warnings about running &SCons; using a version of &Python; that has been deprecated. These warnings are enabled by default.

  reserved-variable

    Warnings about attempts to set the reserved &consvar; names &cv-CHANGED_SOURCES;, &cv-CHANGED_TARGETS;, &cv-TARGET;, &cv-TARGETS;, &cv-SOURCE;, &cv-SOURCES;, &cv-UNCHANGED_SOURCES; or &cv-UNCHANGED_TARGETS;. These warnings are disabled by default.

  stack-size

    Warnings about requests to set the stack size that could not be honored. These warnings are enabled by default.

  target_not_build

    Warnings about a build rule not building the expected targets. These warnings are disabled 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.

### SCONSCRIPT FILE REFERENCE

#### SConscript Files

The build configuration is described by one or more files, known as &SConscript; files. There must be at least one file for a valid build (&scons; will quit if it does not find one). &scons; by default looks for this file by the name `SConstruct` in the directory from which you run &scons;, though if necessary, also looks for alternative file names &Sconstruct;, &sconstruct;, &SConstruct.py;, &Sconstruct.py; and &sconstruct.py; in that order. A different file name (which can include a pathname part) may be specified via the `-f` option. Except for the SConstruct file, these files are not searched for automatically; you add additional configuration files to the build by calling the &f-link-SConscript; function. This allows parts of the build to be conditionally included or excluded at run-time depending on how &scons; is invoked.

Each &SConscript; file in a build configuration is invoked independently in a separate context. This provides necessary isolation so that different parts of the build don't accidentally step on each other. You have to be explicit about sharing information, by using the &f-link-Export; function or the &exports; argument to the &f-link-SConscript; function, as well as the &f-link-Return; function in a called &SConscript; file, and comsume shared information by using the &f-link-Import; function.

The following sections describe the various &SCons; facilities that can be used in &SConscript; files. Quick links:

- Construction Environments
- Tools
- Builder Methods
- Methods and Functions to do Things
- SConscript Variables
- Construction Variables
- Configure Contexts
- Command-Line Construction Variables
- Node Objects

#### Construction Environments

A &ConsEnv; is the basic means by which you communicate build information to &SCons;. A new &consenv; is created using the &f-link-Environment; function:

    env = Environment()

&Consenv; attributes called &ConsVars; may be set either by specifying them as keyword arguments when the object is created or by assigning them a value after the object is created. These two are nominally equivalent:

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

Note that certain settings which affect tool detection are referenced only when the tools are initializided, so you either need either to supply them as part of the call to &f-link-Environment;, or defer tool initialization. For example, initializing the Microsoft Visual C++ version you wish to use:

    # initializes msvc to v14.1
    env = Environment(MSVC_VERSION="14.1")

    env = Environment()
    # msvc tool was initialized to default, does not reinitialize
    env['MSVC_VERSION'] = "14.1"

    env = Environment(tools=[])
    env['MSVC_VERSION'] = "14.1"
    # msvc tool initialization was deferred, so will pick up new value
    env.Tool('default')

As a convenience, &consvars; may also be set or modified by the parse_flags keyword argument during object creation, which has the effect of the &f-link-env-MergeFlags; method being applied 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 need to be distributed to a number of &consvars;. &f-link-env-ParseFlags; describes how these arguments are distributed to &consvars;.

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

This example adds 'include' to the &cv-link-CPPPATH; &consvar;, 'EBUG' to &cv-link-CPPDEFINES;, and 'm' to &cv-link-LIBS;.

An existing &consenv; can be duplicated by calling the &f-link-env-Clone; method. Without arguments, it will be a copy with the same settings. Otherwise, &f-env-Clone; takes the same arguments as &f-link-Environment;, and uses the arguments to create a modified copy.

&SCons; provides a special &consenv; called the &DefEnv;. The &defenv; is used only for global functions, that is, construction activities called without the context of a regular &consenv;. See &f-link-DefaultEnvironment; for more information.

By default, a new &consenv; is initialized with a set of builder methods and &consvars; that are appropriate for the current platform. The optional platform keyword argument may be used to specify that the &consenv; should be initialized for a different platform:

    env = Environment(platform='cygwin')

Specifying a platform initializes the appropriate &consvars; in the environment to use and generate file names with prefixes and suffixes appropriate for that platform.

Note that the `win32` platform adds the `SystemDrive` and `SystemRoot` variables from the user's external environment to the &consenv;'s `ENV` dictionary. This is so that any executed commands that use sockets to connect with other systems will work on Windows systems.

The platform argument may be a string value representing one of the pre-defined platforms (`aix`, `cygwin`, `darwin`, `hpux`, `irix`, `os2`, `posix`, `sunos` or `win32`), or it may be be a callable platform object returned by a call to &f-link-Platform; selecting a pre-defined platform, or it may be a user-supplied callable, in which case the &Environment; method will call it to update the new &consenv;:

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

    env = Environment(platform=my_platform)

Note that supplying a non-default platform or custom fuction for initialization may bypass settings that should happen for the host system and should be used with care. It is most useful in the case where the platform is an alternative for the one that would be auto-detected, such as `platform="cygwin"` on a system which would otherwise identify as `win32`.

The optional tools and toolpath keyword arguments affect the way tools available to the environment are initialized. See for details.

The optional variables keyword argument allows passing a Variables object which will be used in the initialization of the &consenv; See for details.

#### Tools

&SCons; has a large number of predefined tool modules (more properly, tool specification modules) which are used to help initialize the &consenv;. An &SCons; tool is only responsible for setup. For example, if an &SConscript; file declares the need to construct an object file from a C-language source file by calling the &b-link-Object; builder, then a tool representing an available C compiler needs to have run first, to set up that builder and all the &consvars; it needs in the associated &consenv;; the tool itself is not called in the process of the build. Normally this happens invisibly as &scons; has per-platform lists of default tools, and it steps through those tools, calling the ones which are actually applicable, skipping those where necessary programs are not installed on the build system, or other preconditions are not met.

A specific set of tools with which to initialize an environment when creating it may be specified using the optional keyword argument tools, which takes a list of tool names. This is useful to override the defaults, to specify non-default built-in tools, and to supply added tools:

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

Tools can also be directly called by using the &f-link-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 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 `'default'` can be used to retain the default list.

If no tools argument is specified, or if tools includes `'default'`, then &scons; will auto-detect usable 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 programs, and the platform name in effect to determine the default tools for that platform. Changing the `PATH` variable after the &consenv; is constructed will not cause the tools to be re-detected.

Additional tools can be added, see the Extending SCons section and specifically Tool Modules.

SCons supports the following tool specifications out of the box:

#### Builder Methods

You tell &SCons; what to build by calling Builders, functions which take particular action(s) to produce target(s) of a particular type (conventionally hinted at by the builder name, e.g. &Program;) from the specified source files. A builder call is a declaration: &SCons; enters the specified relationship into its internal dependency node graph, and only later makes the decision on whether anything is actually built, since this depends on command-line options, target selection rules, and whether the target(s) are out of date with respect to the sources.

&SCons; provides a number of builders, and you can also write your own (see Builder Objects). Builders are created dynamically at run-time, often (though not always) by tools which determine whether the external dependencies for the builder are satisfied, and which perform the necessary setup (see Tools). Builders are attached to a &consenv; as methods. The available builder methods are registered as key-value pairs in the &cv-link-BUILDERS; attribute of the &consenv;, so the available builders can be examined. This example displays them for debugging purposes:

    env = Environment()
    print("Builders:", list(env['BUILDERS']))

Builder methods take two required arguments: target and source. The target and source arguments can be specified either as positional arguments, in which case target comes first, or as keyword arguments, using target= and source=. Although both arguments are nominally required, if there is a single source and the target can be inferred the target argument can be omitted (see below). Builder methods also take a variety of keyword arguments, described below.

Because long lists of file names can lead to a lot of quoting in a builder call, &SCons; supplies a &f-link-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 method:

    env.Program('bar', ['bar.c', 'foo.c'])
    env.Program('bar', Split('bar.c foo.c'))
    env.Program('bar', env.Split('bar.c foo.c'))
    env.Program(source=['bar.c', 'foo.c'], target='bar')
    env.Program(target='bar', source=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())

Sources and targets can be specified as a scalar or as a list, composed of either strings or nodes (more on nodes below). When specifying path strings, &Python; follows the POSIX pathname convention: if a string begins with the operating system pathname separator (on Windows both the slash and backslash separator are accepted, and any leading drive specifier is ignored for the determination) it is considered an absolute path, otherwise it is a relative path. If the path string contains no separator characters, it is searched for as a file in the current directory. If it contains separator characters, the search follows down from the starting point, which is the top of the directory tree for an absolute path and the current directory for a relative path. The "current directory" in this context is the directory of the &SConscript; file currently being processed.

&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-level &SConstruct; rather than from the current directory. The # can optionally be followed by a pathname separator, which is ignored if found in that position. Top-relative paths only work in places where &scons; will interpret the path (see some examples below). To be used in other contexts the string will need to be converted to a relative or absolute path first.

Examples:

    # The comments describing the targets that will be built
    # assume these calls are in a SConscript file in the
    # a subdirectory named "subdir".

    # Builds the program "subdir/foo" from "subdir/foo.c":
    env.Program('foo', 'foo.c')

    # Builds the program "/tmp/bar" from "subdir/bar.c":
    env.Program('/tmp/bar', 'bar.c')

    # An initial '#' or '#/' are equivalent; the following
    # calls build the programs "foo" and "bar" (in the
    # top-level SConstruct directory) from "subdir/foo.c" and
    # "subdir/bar.c", respectively:
    env.Program('#foo', 'foo.c')
    env.Program('#/bar', 'bar.c')

    # Builds the program "other/foo" (relative to the top-level
    # SConstruct directory) from "subdir/foo.c":
    env.Program('#other/foo', 'foo.c')

    # This will not work, only SCons interfaces understand '#',
    # os.path.exists is pure Python:
    if os.path.exists('#inc/foo.h'):
        env.Append(CPPPATH='#inc')

When the target shares the same base name as the source and only the suffix varies, and if the builder method has a suffix defined for the target file type, then the target argument may be omitted completely, and &scons; will deduce the target file name from the source file name. The following examples all build the executable program bar (on POSIX systems) or bar.exe (on Windows systems) from the `bar.c` source file:

    env.Program(target='bar', source='bar.c')
    env.Program('bar', source='bar.c')
    env.Program(source='bar.c')
    env.Program('bar.c')

The optional srcdir keyword argument specifies that all source file strings that are not absolute paths or top-relative paths shall be interpreted relative to the specified srcdir. The following example will build the `build/prog` (or `build/prog.exe` on Windows) program from the files `src/f1.c` and `src/f2.c`:

    env.Program('build/prog', ['f1.c', 'f2.c'], srcdir='src')

The optional parse_flags keyword argument causes behavior similar to the &f-link-env-MergeFlags; method, where the argument value is broken into individual settings and merged into the appropriate &consvars;.

    env.Program('hello', 'hello.c', parse_flags='-Iinclude -DEBUG -lm')

This example adds 'include' to the &cv-link-CPPPATH; &consvar;, 'EBUG' to &cv-link-CPPDEFINES;, and 'm' to &cv-link-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 true, then &scons; will change to the target file's directory.

&Python; only keeps one current directory location even if there are multiple threads. This means that use of the chdir argument will not work with the SCons `-j` option, because individual worker threads spawned by &SCons; interfere with each other when they start changing directory.

    # 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 &consvars; like &cv-link-TARGET; and &cv-link-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 &consvar; overrides, 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 want to specify some libraries needed by just one program:

    env.Program('hello', 'hello.c', LIBS=['gl', 'glut'])

or generate a shared library with a non-standard suffix:

    env.SharedLibrary(
        target='word',
        source='word.cpp',
        SHLIBSUFFIX='.ocx',
        LIBSUFFIXES=['.ocx'],
    )

Note that both the &cv-link-SHLIBSUFFIX; and &cv-link-LIBSUFFIXES; &consvars; must be set if you want &scons; to search automatically for dependencies on the non-standard library names; see the descriptions of these variables for more information.

Although the builder methods defined by &scons; are, in fact, methods of a &consenv; object, many may also be called without an explicit environment:

    Program('hello', 'hello.c')
    SharedLibrary('word', 'word.cpp')

If called this way, the builder will internally use the &DefEnv; that consists of the tools and values that &scons; has determined are appropriate for the local system.

Builder methods that can be called without an explicit environment (indicated in the listing of builders below without a leading `env.`) may be called from custom &Python; modules that you import into an &SConscript; file by adding the following to the &Python; module:

    from SCons.Script import *

A builder may add additional targets beyond those requested if an attached Emitter chooses to do so (see for more information. &cv-link-PROGEMITTER; is an example). For example, the GNU linker takes a command-line argument `-Map=mapfile`, which causes it to produce a linker map file in addition to the executable file actually being linked. If the &b-link-Program; builder'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 object whose elements are Nodes. Nodes are the internal representation of build targets or sources (see for more information). The returned NodeList object can be passed to other 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 specific object file but not the others:

    bar_obj_list = env.StaticObject('bar.c', CPPDEFINES='-DBAR')
    env.Program("prog", ['foo.c', bar_obj_list, 'main.c'])

Using a Node as in this example makes for a more portable build by avoiding having to specify a platform-specific object suffix when calling the &b-link-Program; builder method.

The NodeList object is also convenient to pass to the &f-link-Default; function, for the same reason of avoiding a platform-specific name:

    tgt = env.Program("prog", ["foo.c", "bar.c", "main.c"])
    Default(tgt)

Builder calls will automatically "flatten" lists passed as source and target, so they are free to contain elements which are themselves lists, such as `bar_obj_list` returned by the &b-link-StaticObject; call. If you need to manipulate a list of lists returned by builders directly in &Python; code, you can either build a new list by hand:

    foo = Object('foo.c')
    bar = Object('bar.c')
    objects = ['begin.o'] + foo + ['middle.o'] + bar + ['end.o']
    for obj in objects:
        print(str(obj))

Or you can use the &f-link-Flatten; function supplied by &SCons; to create a list containing just the Nodes, which may be more convenient:

    foo = Object('foo.c')
    bar = Object('bar.c')
    objects = Flatten(['begin.o', foo, 'middle.o', bar, 'end.o'])
    for obj in objects:
        print(str(obj))

Since builder calls return a list-like object, not an actual &Python; list, it is not appropriate to use the &Python; add operator (`+` or `+=`) to append builder results to a &Python; list. Because the list and the object are different types, &Python; will not update the original list in place, but will instead create a new NodeList object containing the concatenation of the list elements and the builder results. This will cause problems for any other &Python; variables in your SCons configuration that still hold on to a reference to the original list. Instead, use the &Python; list `extend` method to make sure the list is updated in-place. Example:

    object_files = []

    # Do NOT use += here:
    #    object_files += Object('bar.c')
    #
    # It will not update the object_files list in place.
    #
    # Instead, use the list extend method:
    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:

    bar_obj_list = env.StaticObject('bar.c', CPPDEFINES='-DBAR')
    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 (`bar_obj_list[0]` in the example) to get at the Node that actually represents the object file.

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 the 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 itself succeeding. If necessary, a Builder's Action should be coded to exit with a useful exception message indicating the problem in the &SConscript; files - programmatically recovering from build errors is rarely useful.

The following builder methods are predefined in the &SCons; core software distribution. Depending on the setup of a particular &consenv; and on the type and software installation status of the underlying system, not all builders may be available in that &consenv;. Since the function calling signature is the same for all builders:

    Buildername(target, source, [key=val, ...])

it is omitted in this listing for brevity.

All targets of builder methods automatically depend on their sources. An explicit dependency can be specified using the &f-link-env-Depends; method of a &consenv; (see below).

In addition, &scons; automatically scans source files for various programming languages, so the dependencies do not need to be specified explicitly. By default, SCons can C source files, C++ source files, Fortran source files with `.F` (POSIX systems only), `.fpp`, or `.FPP` file extensions, and assembly language files with `.S` (POSIX systems only), `.spp`, or `.SPP` files extensions for C preprocessor dependencies. SCons also has default support for scanning D source files, You can also write your own Scanners to add support for additional source file types. These can be added to the default Scanner object used by the &b-link-Object;, &b-link-StaticObject; and &b-link-SharedObject; Builders by adding them to the SourceFileScanner object. See for more information about defining your own Scanner objects and using the SourceFileScanner object.

#### Methods and Functions To Do Things

In addition to Builder methods, &scons; provides a number of other &consenv; methods and global functions to manipulate the build configuration.

Usually, a &consenv; method and global function with the same name both exist for convenience. In the following list, the global function is documented in this style:

    Function(arguments, [optional arguments])

and the &consenv; method looks like:

    env.Function(arguments, [optional arguments])

If the function can be called both ways, then both forms are listed.

The global function and same-named &consenv; method provide almost identical functionality, with a couple of exceptions. First, many of the &consenv; methods affect only that &consenv;, while the global function has a global effect. Second, where appropriate, calling the functionality through a &consenv; will substitute &consvars; into any supplied string arguments, while the global function doesn't have the context of a &consenv; to pick variables from, so it cannot perform the substitution. For example:

    Default('$FOO')

    env = Environment(FOO='foo')
    env.Default('$FOO')

In the above example, the call to the global &f-Default; function will add a target named $FOO to the list of default targets, while the call to the &f-env-Default; &consenv; method will expand the value and add a target named foo to the list of default targets. For more on &consvar; expansion, see the next section on &consvars;.

Global functions may be called from custom Python modules that you import into an &SConscript; file by adding the following import to the Python module:

    from SCons.Script import *

&Consenv; methods and global functions provided by &scons; include:

#### SConscript Variables

In addition to the global functions and methods, &scons; supports a number of variables that can be used in &SConscript; files to affect how you want the build to be performed.

&ARGLIST;

  A list of the keyword=value arguments specified on the command line. Each element in the list is a tuple containing the argument. The separate keyword and value elements of the tuple can be accessed by subscripting for elements [0] and [1] of the tuple, or, more readably, by using tuple unpacking. Example:

      print("first keyword, value =", ARGLIST[0][0], ARGLIST[0][1])
      print("second keyword, value =", ARGLIST[1][0], ARGLIST[1][1])
      key, value = ARGLIST[2]
      print("third keyword, value =", key, value)
      for key, value in ARGLIST:
          # process key and value

&ARGUMENTS;

  A dictionary of all the keyword=value arguments specified on the command line. The dictionary is not in order, and if a given keyword has more than one value assigned to it on the command line, the last (right-most) value is the one in the &ARGUMENTS; dictionary.

  Example:

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

&BUILD_TARGETS;

  A list of the targets which &scons; has been asked to build. The contents will be either those targets listed on the command line, or, if none, those targets set via calls to the &f-link-Default; function. It does not contain any dependent targets that &scons; selects for building as a result of making the sure the specified targets are up to date, if those targets did not appear on the command line. The list is empty if neither command line targets or &Default; calls are present.

  The elements of this list may be strings or nodes, so you should run the list through the Python `str` function to make sure any Node path names are converted to strings.

  Because this list may be taken from the list of targets specified using the &Default; function, the contents of the list may change on each successive call to &Default;. See the &DEFAULT_TARGETS; list, below, for additional information.

  Example:

      if 'foo' in BUILD_TARGETS:
          print("Don't forget to test the `foo' program!")
      if 'special/program' in BUILD_TARGETS:
          SConscript('special')

&COMMAND_LINE_TARGETS;

  A list of the targets explicitly specified on the command line. If there are command line targets, this list will have the same contents as &BUILD_TARGETS;. If there are no targets specified on the command line, the list is empty. The elements of this list are strings. This can be used, for example, to take specific actions only when certain targets are explicitly being built.

  Example:

      if 'foo' in COMMAND_LINE_TARGETS:
          print("Don't forget to test the `foo' program!")
      if 'special/program' in COMMAND_LINE_TARGETS:
          SConscript('special')

&DEFAULT_TARGETS;

  A list of the target nodes that have been specified using the &f-link-Default; function. If there are no command line targets, this list will have the same contents as &BUILD_TARGETS;. Since the elements of the list are nodes, you need to call the Python `str` function on them to get the path name for each Node.

  Example:

      print(str(DEFAULT_TARGETS[0]))
      if 'foo' in [str(t) for t in DEFAULT_TARGETS]:
          print("Don't forget to test the `foo' program!")

  The contents of the &DEFAULT_TARGETS; list change on on each successive call to the &Default; function:

      print([str(t) for t in DEFAULT_TARGETS])   # originally []
      Default('foo')
      print([str(t) for t in DEFAULT_TARGETS])   # now a node ['foo']
      Default('bar')
      print([str(t) for t in DEFAULT_TARGETS])   # now a node ['foo', 'bar']
      Default(None)
      print([str(t) for t in DEFAULT_TARGETS])   # back to []

  Consequently, be sure to use &DEFAULT_TARGETS; only after you've made all of your &Default;() calls, or else simply be careful of the order of these statements in your &SConscript; files so that you don't look for a specific default target before it's actually been added to the list.

These variables may be accessed from custom Python modules that you import into an &SConscript; file by adding the following to the Python module:

    from SCons.Script import *

#### Construction Variables

A &consenv; has an associated dictionary of &consvars; that are used by built-in or user-supplied build rules. &Consvar; naming must follow the same rules as Python identifier naming: the initial character must be an underscore or letter, followed by any number of underscores, letters, or digits. A &consenv; is not a Python dictionary itself, but it can be indexed like one to access a &consvar;:

    env["CC"] = "cc"
    flags = env.get("CPPDEFINES", [])

&Consvars; can also be retrieved and set by using the &f-link-Dictionary; method of the &consenv; to create an actual dictionary:

    cvars = env.Dictionary()
    cvars["CC"] = "cc"

&Consvars; can also be passed to the &consenv; constructor:

    env = Environment(CC="cc")

or when copying a &consenv; using the &f-link-Clone; method:

    env2 = env.Clone(CC="cl.exe")

&Consvars; can also be supplied as keyword arguments to a builder, in which case those settings affect only the work done by that builder call, and not the &consenv; as a whole. This concept is called an override:

    env.Program('hello', 'hello.c', LIBS=['gl', 'glut'])

A number of useful &consvars; are automatically defined by scons for each supported platform, and you can modify these or define any additional &consvars; for your own use, taking care not to overwrite ones which &SCons; is using. The following is a list of the possible automatically defined &consvars;.

Note the actual list available at execution time will never include all of these, as the ones detected as 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 certain &consvars; 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 &f-link-env-Dump; method can be called to examine the &consvars; set in a particular environment.

#### Configure Contexts

&SCons; supports a &configure_context;, an integrated mechanism similar to the various `AC_CHECK` macros in GNU &Autoconf; for testing the existence of external items needed for the build, such as C header files, libraries, etc. The mechanism is portable across platforms.

&scons; does not maintain an explicit cache of the tested values (this is different than &Autoconf;), but uses its normal dependency tracking to keep the checked values up to date. However, users may override this behaviour with the `--config` command line option.

`Configure`(env, [custom_tests, conf_dir, log_file, config_h, clean, help])
env.Configure([custom_tests, conf_dir, log_file, config_h, clean, help])

  Create a &configure_context;, which tracks information discovered while running tests. The context includes a local &consenv; (available as context.`env`) which is used when running the tests and which can be updated with the check results. Only one context may be active at a time, but a new context can be created after the active one is completed. For the global function form, the required env describes the initial values for the context's local &consenv;; for the &consenv; method form the instance provides the values.

  Changed in version 4.0: raises an exception on an attempt to create a new context when there is an active context.

  custom_tests specifies a dictionary containing custom tests (see the section on custom tests below). The default value is `None`, meaning no custom tests are added to the &configure_context;.

  conf_dir specifies a directory where the test cases are built. This directory is not used for building normal targets. The default value is `#/.sconf_temp`.

  log_file specifies a file which collects the output from commands that are executed to check for the existence of header files, libraries, etc. The default is `#/config.log`. If you are using variant directories, you may want to place the log file for a given build under that build's variant directory.

  config_h specifies a C header file where the results of tests will be written. The results will consist of lines like `#define HAVE_STDIO_H`, `#define HAVE_LIBM`, etc. Customarily, the name chosen is `config.h`. The default is to not write a config_h file. You can specify the same config_h file in multiple calls to &Configure;, in which case &SCons; will concatenate all results in the specified file. Note that &SCons; uses its normal dependency checking to decide if it's necessary to rebuild the 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 file is being built.

  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 default behavior is always to execute &configure_context; tests, since the results of the tests may affect the list of targets to be cleaned or the help text. If the configure tests do not affect these, then you may add the `clean=False` or `help=False` arguments (or both) to avoid unnecessary test execution.

context.Finish()

  This method must be called after configuration is done. Though required, this is not enforced except 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 checks. After this method is called, no further checks can be performed with this configuration context. However, you can create a new &configure_context; to perform additional checks.

Example of a typical Configure usage:

    env = Environment()
    conf = Configure(env)
    if not conf.CheckCHeader("math.h"):
        print("We really need math.h!")
        Exit(1)
    if conf.CheckLibWithHeader("qt", "qapp.h", "c++", "QApplication qapp(0,0);"):
        # do stuff for qt - usage, e.g.
        conf.env.Append(CPPDEFINES="WITH_QT")
    env = conf.Finish()

A &configure_context; has the following predefined methods which can be used to perform checks. Where language is an optional parameter, it specifies the compiler to use for the check, currently a choice of C or C++. The spellings accepted for C are C or c; for C++ the value can be CXX, cxx, C++ or c++. If language is omitted, C is assumed.

context.CheckHeader(header, [include_quotes, language])

  Checks if header is usable in the specified language. header may be a list, in which case the last item in the list is the header file to be checked, and the previous list items are header files whose `#include` lines should precede the header line being checked for. The optional argument include_quotes must be a two character string, where the first character denotes the opening quote and the second character denotes the closing quote. By default, both characters are " (double quote).

  Returns a boolean indicating success or failure.

context.CheckCHeader(header, [include_quotes])

  Checks if header is usable when compiling a C language program. header may be a list, in which case the last item in the list is the header file to be checked, and the previous list items are header files whose `#include` lines should precede the header line being checked for. The optional argument include_quotes must be a two character string, where the first character denotes the opening quote and the second character denotes the closing quote. By default, both characters are " (double quote). Note this is a wrapper around `CheckHeader`. Returns a boolean indicating success or failure.

context.CheckCXXHeader(header, [include_quotes])

  Checks if header is usable when compiling a C++ language program. header may be a list, in which case the last item in the list is the header file to be checked, and the previous list items are header files whose `#include` lines should precede the header line being checked for. The optional argument include_quotes must be a two character string, where the first character denotes the opening quote and the second character denotes the closing quote. By default, both characters are " (double quote). Note this is a wrapper around `CheckHeader`. Returns a boolean indicating success or failure.

context.CheckFunc(function_name, [header, language])

  Checks if function_name is usable in the context's local environment, using the compiler specified by language - that is, can a check referencing it be compiled using the current values of &cv-link-CFLAGS;, &cv-link-CPPFLAGS;, &cv-link-LIBS; or other relevant &consvars;.

  The optional header argument is a string representing a code fragment to place at the top of the test program that will be compiled to check if the function exists. If omitted, the default stanza will be (with function_name appropriately substituted):

      #ifdef __cplusplus
      extern "C"
      #endif
      char function_name(void);

  Note: if header is supplied, it should not include the standard header file that declares function_name, and it should include a dummy prototype similar to the default case. Compilers reject builds where a function call does not match the declared prototype as happens if the "real" header is included, and modern compilers are now rejecting implicit function declarations.

  Returns a boolean indicating success or failure.

context.CheckLib([library, symbol, header, language, autoadd=True, append=True, unique=False])

  Checks if library provides symbol by compiling a simple stub program with the compiler selected by language, and optionally adds that library to the context. If supplied, the text of header is included at the top of the stub. If autoadd is true (the default), and the library provides the specified symbol (as defined by successfully linking the stub program), it is added to the &cv-link-LIBS; &consvar; in the context. if append is true (the default), the library is appended, otherwise it is prepended. If unique is true, and the library would otherwise be added but is already present in &cv-link-LIBS; in the configure context, it will not be added again. The default is `False`.

  library can be a list of library names, or `None` (the default if the argument is omitted). If the former, symbol is checked against each library name in order, returning (and reporting success) on the first successful test; if the latter, it is checked with the current value of &cv-LIBS; (in this case no library name would be added). If symbol is omitted or `None`, then `CheckLib` just checks if you can link against the specified library, Note though it is legal syntax, it would not be very useful to call this method with library and symbol both omitted or `None` - at least one should be supplied.

  Returns a boolean indicating success or failure.

  Changed in version 4.5.0: added the append and unique parameters.

context.CheckLibWithHeader(library, header, [language, call, autoadd=True, append=True, unique=False])

  Provides an alternative to the CheckLib method for checking for libraries usable in a build. library specifies a library or list of libraries to check. header specifies a header to include in the test program, and language indicates the compiler to use. header may be a list, in which case the last item in the list is the header file to be checked, and the previous list items are header files whose `#include` lines should precede the header line being checked for. A code fragment (must be a a valid expression, including a trailing semicolon) to serve as the test can be supplied in call; if not supplied, the default checks the ability to link against the specified library. If autoadd is true (the default), the first library that passes the check is added to the &cv-link-LIBS; &consvar; in the context and the method returns. If append is true (the default), the library is appended, otherwise prepended. If unique is true, and the library would otherwise be added but is already present in &cv-link-LIBS; in the configure context, it will not be added again. The default is `False`.

  Returns a boolean indicating success or failure.

  Changed in version 4.5.0: added the append and unique parameters.

context.CheckType(type_name, [includes, language])

  Checks for the existence of a type defined by `typedef`. type_name specifies the typedef name to check for. includes is a string containing one or more `#include` lines that will be inserted into the program that will be run to test for the existence of the type. Example:

      sconf.CheckType('foo_type', '#include "my_types.h"', 'C++')

  Returns a boolean indicating success or failure.

context.CheckTypeSize(type_name, [header, language, expect])

  Checks for the size of a type defined by `typedef`. type_name specifies the typedef name 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 check if the type exists; the default is empty. If the optional expect, is supplied, it should be an integer size; &CheckTypeSize; will fail unless type_name is actually that size. Returns the size in bytes, or zero if the type was not found (or if the size did not match optional expect).

  For example,

      CheckTypeSize('short', expect=2)

  will return the size `2` only if short is actually two bytes.

context.CheckCC()

  Checks whether the C compiler (as defined by the &cv-link-CC; &consvar;) 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 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 &b-link-Object; builder for C source files, so by setting relevant &consvars; it can be used to detect if particular compiler flags will be accepted or rejected by the compiler.

  Returns a boolean indicating success or failure.

context.CheckCXX()

  Checks whether the C++ compiler (as defined by the &cv-link-CXX; &consvar;) 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 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 &b-link-Object; builder for C++ source files, so by setting relevant &consvars; it can be used to detect if particular compiler flags will be accepted or rejected by the compiler.

  Returns a boolean indicating success or failure.

context.CheckSHCC()

  Checks whether the shared-object C compiler (as defined by the &cv-link-SHCC; &consvar;) 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 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 &b-link-SharedObject; builder for C source files, so by setting relevant &consvars; it can be used to detect if particular compiler flags will be accepted or rejected by the compiler. Note this does not check whether a shared library/dll can be created.

  Returns a boolean indicating success or failure.

context.CheckSHCXX()

  Checks whether the shared-object C++ compiler (as defined by the &cv-link-SHCXX; &consvar;) 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 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 &b-link-SharedObject; builder for C++ source files, so by setting relevant &consvars; it can be used to detect if particular compiler flags will be accepted or rejected by the compiler. Note this does not check whether a shared library/dll can be created.

  Returns a boolean indicating success or failure.

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 failure.

context.CheckDeclaration(symbol, [includes, language])

  Checks if the specified symbol is declared. 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 symbol.

  Returns a boolean indicating success or failure.

context.CheckMember(aggregate_member, [header, language])

  Checks for the existence of a member of the C/C++ struct or class. aggregate_member specifies the struct/class and member to check for. header 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 member. Example:

      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 definition 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 comment is given, it is inserted as a comment above the macro definition (suitable comment marks will be added automatically). This is analogous to using `AC_DEFINE` in &Autoconf;.

  Examples:

      env = Environment()
      conf = Configure(env)

      # Puts the following line in the config header file:
      #    #define A_SYMBOL
      conf.Define("A_SYMBOL")

      # Puts the following line in the config header file:
      #    #define A_SYMBOL 1
      conf.Define("A_SYMBOL", 1)

  Examples of quoting string values:

      env = Environment()
      conf = Configure(env)

      # Puts the following line in the config header file:
      #    #define A_SYMBOL YA
      conf.Define("A_SYMBOL", "YA")

      # Puts the following line in the config header file:
      #    #define A_SYMBOL "YA"
      conf.Define("A_SYMBOL", '"YA"')

  Example including comment:

      env = Environment()
      conf = Configure(env)

      # Puts the following lines in the config header file:
      #    /* Set to 1 if you have a symbol */
      #    #define A_SYMBOL 1
      conf.Define("A_SYMBOL", 1, "Set to 1 if you have a symbol")

You can define your own custom checks in addition to using the predefined checks. To enable custom checks, pass a dictionary to the &f-link-Configure; function as the custom_tests parameter. The dictionary maps the names of the checks to the custom check callables (either a Python function or an instance of a class implementing a __call__ method). Each custom check will be called with a a CheckContext instance as the first parameter followed by the remaining arguments, which must be supplied by the user of the check. A CheckContext is not the same as a configure context; rather it is an instance of a class which contains a configure context (available as chk_ctx.`sconf`). A CheckContext provides the following methods which custom checks can make use of::

chk_ctx.Message(text)

  Displays text as an indicator of progess. For example: `Checking for library X...`. Usually called before the check is started.

chk_ctx.Result(res)

  Displays a result message as an indicator of progress. If res is an integer, displays `yes` if res evaluates true or `no` if false. If res is a string, it is displayed as-is. Usually called after the check has completed.

chk_ctx.TryCompile(text, extension='')

  Checks if a file containing text and given the specified extension (e.g. `'.c'`) can be compiled to an object file using the environment's &b-link-Object; builder. Returns a boolean indicating success or failure.

chk_ctx.TryLink(text, extension='')

  Checks if a file containing text and given the specified extension (e.g. `'.c'`) can be compiled to an executable program using the environment's &b-link-Program; builder. Returns a boolean indicating success or failure.

chk_ctx.TryRun(text, extension='')

  Checks if a file containing text and given the specified extension (e.g. `'.c'`) can be compiled to an excutable program using the environment's &b-link-Program; builder and subsequently executed. Execution is only attempted if the build succeeds. If the program executes successfully (that is, its return status is `0`), a tuple `(True, outputStr)` is returned, where `outputStr` is the standard output of the program. If the program fails execution (its return status is non-zero), then `(False, '')` is returned.

chk_ctx.TryAction(action, [text, extension=''])

  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 of the target file. On failure `(False, '')` is returned.

chk_ctx.TryBuild(builder, [text, extension=''])

  Low level implementation for testing specific builds; the methods above are based on this method. Given the Builder instance builder and the optional text of a source file with optional extension, returns a boolean indicating success or failure. In addition, chk_ctx.`lastTarget` is set to the build target node if the build was successful.

Example of implementing and using custom tests:

    def CheckQt(chk_ctx, qtdir):
        chk_ctx.Message('Checking for qt ...')
        lastLIBS = chk_ctx.env['LIBS']
        lastLIBPATH = chk_ctx.env['LIBPATH']
        lastCPPPATH = chk_ctx.env['CPPPATH']
        chk_ctx.env.Append(LIBS='qt', LIBPATH=qtdir + '/lib', CPPPATH=qtdir + '/include')
        ret = chk_ctx.TryLink(
            """\
    #include <qapp.h>
    int main(int argc, char **argv) {
      QApplication qapp(argc, argv);
      return 0;
    }
    """
        )
        if not ret:
            chkctx.env.Replace(LIBS=lastLIBS, LIBPATH=lastLIBPATH, CPPPATH=lastCPPPATH)
        chkctx.Result(ret)
        return ret

    env = Environment()
    conf = Configure(env, custom_tests={'CheckQt': CheckQt})
    if not conf.CheckQt('/usr/lib/qt'):
        print('We really need qt!')
        Exit(1)
    env = conf.Finish()

#### Command-Line Construction Variables

Often when building software, some variables need to be specified at build time. For example, libraries needed for the build may be in non-standard locations, or site-specific compiler options may need to be passed to the compiler. &SCons; provides a &Variables; object to support overriding &consvars; with values obtained from various sources, often from the command line:

    scons VARIABLE=foo

The variable values can also be specified in a configuration file or an &SConscript; file.

To obtain the object for manipulating values, call the &Variables; function:

`Variables`([files, [args]])

  If files is a file or list of files, they are executed as Python scripts, and the values of (global) Python variables set in those files are added as &consvars; in the &DefEnv;. If no files are specified, or the files argument is `None`, then no files will be read (supplying `None` is necessary if there are no files but you want to specify args as a positional argument).

  The following example file contents could be used to set an alternative C compiler:

      CC = 'my_cc'

  If args is specified, it is a dictionary of values that will override anything read from files. The primary use is to pass the &ARGUMENTS; dictionary that holds variables specified on the command line, allowing you to indicate that if a setting appears on both the command line and in the file(s), the command line setting takes precedence. However, any dictionary can be passed. Examples:

      vars = Variables('custom.py')
      vars = Variables('overrides.py', ARGUMENTS)
      vars = Variables(None, {FOO:'expansion', BAR:7})

  Calling &Variables; with no arguments is equivalent to:

      vars = Variables(files=None, args=ARGUMENTS)

  Note that since the variables are eventually added as &consvars;, you should choose variable names which do not unintentionally change pre-defined &consvars; that your project will make use of (see ).

Variables objects have the following methods:

vars.`Add`(key, [help, default, validator, converter])

  Add a customizable &consvar; to the Variables object. key is either the name of the variable, or a tuple (or list), in which case the first item in the tuple is taken as the variable name, and any remaining values are considered aliases for the variable. help is the help text for the variable (default empty string). default is the default value of the variable (default `None`). If default is `None` and a value is not specified, the &consvar; will not be added to the &consenv;.

  As a special case, if key is a tuple (or list) and is the only argument, the tuple is unpacked into the five parameters listed above left to right, with any missing members filled with the respecitive default values. This form allows `Add` to consume a tuple emitted by the convenience functions `BoolVariable`, `EnumVariable`, `ListVariable`, `PackageVariable` and `PathVariable`.

  If the optional validator is supplied, it is called to validate the value of the variable. A function supplied as a validator must accept three arguments: key, value and env, and should raise an exception with a helpful error message if value is invalid. No return value is expected from the validator.

  If the optional converter is supplied, it is called to convert the value before putting it in the environment, and should take either a value or a value and environment as parameters. The converter function must return a value, which will be converted into a string and be passed to the validator (if any) and then added to the &consenv;.

  Examples:

      vars.Add('CC', help='The C compiler')

      def valid_color(key, val, env):
          if not val in ['red', 'blue', 'yellow']:
              raise Exception("Invalid color value '%s'" % val)

      vars.Add('COLOR', validator=valid_color)

vars.`AddVariables`(args)

  A convenience method that adds one or more customizable &consvars; to a Variables object in one call; equivalent to calling &Add; multiple times. The args are tuples (or lists) that contain the arguments for an individual call to the &Add; method. Since tuples are not Python mappings, the arguments cannot use the keyword form, but rather are positional arguments as documented for `Add`: a required name, the other four optional, but must be in the specified order if used.

      opt.AddVariables(
          ("debug", "", 0),
          ("CC", "The C compiler"),
          ("VALIDATE", "An option for testing validation", "notset", validator, None),
      )

vars.`Update`(env, [args])

  Update a &consenv; env with the customized &consvars;. Any specified variables that are not configured for the Variables object will be saved and may be retrieved using the &UnknownVariables; method.

  Normally this method is not called directly, but rather invoked indirectly by passing the Variables object to the &f-link-Environment; function:

      env = Environment(variables=vars)

vars.`UnknownVariables`()

  Returns a dictionary containing any variables that were specified either in the files or the dictionary with which the Variables object was initialized, but for which the Variables object was not configured.

      env = Environment(variables=vars)
      for key, value in vars.UnknownVariables():
          print("unknown variable:  %s=%s" % (key, value))

vars.`Save`(filename, env)

  Save the currently set variables into a script file named by filename. Only variables that are set to non-default values are saved. You can load these saved settings on a subsequent run by passing filename to the &Variables; function, providing a way to cache particular settings for reuse.

      env = Environment()
      vars = Variables(['variables.cache', 'custom.py'])
      vars.Add(...)
      vars.Update(env)
      vars.Save('variables.cache', env)

vars.`GenerateHelpText`(env, [sort])

  Generate help text documenting the customizable construction variables, suitable for passing in to the &f-link-Help; function. env is the &consenv; that will be used to get the actual values of the customizable variables. If the (optional) value of sort is callable, it is used as a comparison function to determine how to sort the added variables. This function must accept two arguments, compare them, and return a negative integer if the first is less-than the second, zero for equality, or a positive integer for greater-than. Optionally a Boolean value of `True` for sort will cause a standard alphabetical sort to be performed.

      Help(vars.GenerateHelpText(env))

      def cmp(a, b):
          return (a > b) - (a < b)

      Help(vars.GenerateHelpText(env, sort=cmp))

vars.`FormatVariableHelpText`(env, opt, help, default, actual)

  Returns a formatted string containing the printable help text for one option. It is normally not called directly, but is called by the &GenerateHelpText; method to create the returned help text. It may be overridden with your own function that takes the arguments specified above and returns a string of help text formatted to your liking. Note that &GenerateHelpText; will not put any blank lines or extra characters in between the entries, so you must add those characters to the returned string if you want the entries separated.

      def my_format(env, opt, help, default, actual):
          fmt = "\n%s: default=%s actual=%s (%s)\n"
          return fmt % (opt, default, actual, help)

      vars.FormatVariableHelpText = my_format

To make it more convenient to work with customizable Variables, &scons; provides a number of functions that make it easy to set up various types of Variables. Each of these return a tuple ready to be passed to the &Add; or &AddVariables; method:

`BoolVariable`(key, help, default)

  Return a tuple of arguments to set up a Boolean option. The option will use the specified name key, have a default value of default, and help will form the descriptive part of the help text. The option will interpret the command-line values `y`, `yes`, `t`, `true`, `1`, `on` and `all` as true, and the command-line values `n`, `no`, `f`, `false`, `0`, `off` and `none` as false.

`EnumVariable`(key, help, default, allowed_values, [map, ignorecase])

  Returns a tuple of arguments to set up an option whose value may be one of a specified list of legal enumerated values. The option will use the specified name key, have a default value of default, and help will form the descriptive part of the help text. The option will only support those values in the allowed_values list. The optional map argument is a dictionary that can be used to convert input values into specific legal values in the allowed_values list. If the value of ignore_case is `0` (the default), then the values are case-sensitive. If the value of ignore_case is `1`, then values will be matched case-insensitively. If the value of ignore_case is `2`, then values will be matched case-insensitively, and all input values will be converted to lower case.

`ListVariable`(key, help, default, names, [map])

  Returns a tuple of arguments to set up an option whose value may be one or more of a specified list of legal enumerated values. The option will use the specified name key, have a default value of default, and help will form the descriptive part of the help text. The option will only accept the values all, none, or the values in the names list. More than one value may be specified, separated by commas. The default may be a string of comma-separated default values, or a list of the default values. The optional map argument is a dictionary that can be used to convert input values into specific legal values in the names list. (Note that the additional values accepted through the use of a map are not reflected in the generated help message).

`PackageVariable`(key, help, default)

  Returns a tuple of arguments to set up an option whose value is a path name of a package that may be enabled, disabled or given an explicit path name. The option will use the specified name key, have a default value of default, and help will form the descriptive part of the help text. The option will support the values `yes`, `true`, `on`, `enable` or `search`, in which case the specified default will be used, or the option may be set to an arbitrary string (typically the path name to a package that is being enabled). The option will also support the values `no`, `false`, `off` or `disable` to disable use of the specified option.

`PathVariable`(key, help, default, [validator])

  Returns a tuple of arguments to set up an option whose value is expected to be a path name. The option will use the specified name key, have a default value of default, and help will form the descriptive part of the help text. An additional validator may be specified that will be called to verify that the specified path is acceptable. SCons supplies the following ready-made validators:

  `PathVariable`.`PathExists`

    Verify that the specified path exists (this the default behavior if no validator is supplied).

  `PathVariable`.`PathIsFile`

    Verify that the specified path exists and is a regular file.

  `PathVariable`.`PathIsDir`

    Verify that the specified path exists and is a directory.

  `PathVariable`.`PathIsDirCreate`

    Verify that the specified path exists and is a directory; if it does not exist, create the directory.

  `PathVariable`.`PathAccept`

    Accept the specific path name argument without validation, suitable for when you want your users to be able to specify a directory path that will be created as part of the build process, for example.

  You may supply your own validator function, which must accept three arguments (key, the name of the variable to be set; val, the specified value being checked; and env, the &consenv;) and should raise an exception if the specified value is not acceptable.

These functions make it convenient to create a number of variables with consistent behavior in a single call to the &AddVariables; method:

    vars.AddVariables(
        BoolVariable(
            "warnings",
            help="compilation with -Wall and similar",
            default=True,
        ),
        EnumVariable(
            "debug",
            help="debug output and symbols",
            default="no",
            allowed_values=("yes", "no", "full"),
            map={},
            ignorecase=0,  # case sensitive
        ),
        ListVariable(
            "shared",
            help="libraries to build as shared libraries",
            default="all",
            names=list_of_libs,
        ),
        PackageVariable(
            "x11",
            help="use X11 installed here (yes = search some places)",
            default="yes",
        ),
        PathVariable(
            "qtdir",
            help="where the root of Qt is installed",
            default=qtdir),
        PathVariable(
            "foopath",
            help="where the foo library is installed",
            default=foopath,
            validator=PathVariable.PathIsDir,
        ),
    )

#### Node Objects

&SCons; represents objects that are the sources or targets of build operations as Nodes, which are internal data structures. There are a number of user-visible types of nodes: File Nodes, Directory Nodes, Value Nodes and Alias Nodes. Some of the node types have public attributes and methods, described below. Each of the node types has a global function and a matching environment method to create instances: &f-link-File;, &f-link-Dir;, &f-link-Value; and &f-link-Alias;.

##### Filesystem Nodes

The &f-link-File; and &f-link-Dir; functions/methods return File and Directory Nodes, respectively. File and Directory Nodes (collectively, Filesystem Nodes) represent build components that correspond to an entry in the computer's filesystem, whether or not such an entry exists at the time the Node is created. You do not usually need to explicitly create filesystem Nodes, since when you supply a string as a target or source of a Builder, &SCons; will create the Nodes as needed to populate the dependency graph. Builders return the target Node(s) in the form of a list, which you can then make 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 regular 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 relative 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 root SConstruct file's directory.

node.`srcnode`()

  The `srcnode` method returns another File or Directory Node representing the source path of the given File or Directory Node.

Examples:

    # Get the current build dir's path, relative to top.
    Dir('.').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

    # Source path of the given source file.
    File('foo.c').srcnode().path

    # Builders return lists of File objects:
    foo = env.Program('foo.c')
    print("foo will be built in", foo[0].path)

Filesystem Node objects have methods to create new File and Directory Nodes relative to the original 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, there is an `Entry` method of filesystem node objects, which returns a Node that can represent either a file or a directory.

If the original Node is a Directory Node, these methods will place the new Node within the directory the original Node represents:

node.`Dir`(name)

  Returns a directory Node name which is a subdirectory of the directory represented by node.

node.`File`(name)

  Returns a file Node name in the directory represented by node.

node.`Entry`(name)

  Returns an unresolved Node name in the directory represented by node.

If the original Node is a File Node, these methods will place the the new Node in the same directory as the one the original Node represents:

node.`Dir`(name)

  Returns a Node name for a directory in the parent directory of the file represented by node.

node.`File`(name)

  Returns a Node name for a file in the parent directory of the file represented by node.

node.`Entry`(name)

  Returns an unresolved Node name in the parent directory of the file represented by node.

For example:

    # Get a Node for a file within a directory
    incl = Dir('include')
    f = incl.File('header.h')

    # Get a Node for a subdirectory within a directory
    dist = Dir('project-3.2.1')
    src = dist.Dir('src')

    # Get a Node for a file in the same directory
    cfile = File('sample.c')
    hfile = cfile.File('sample.h')

    # Combined example
    docs = Dir('docs')
    html = docs.Dir('html')
    index = html.File('index.html')
    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 &f-link-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 dependency graph related to their sources. An alias is checked for up to date by checking if its sources 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 &f-link-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 alias Node. As a result, the order of &f-Alias; calls is significant. An alias can refer to another alias, but only if the other alias has previously been created.

The &f-link-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 determine 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

&SCons; is designed to be extensible through provided facilities, so changing the code of &SCons; itself is only rarely needed to customize its behavior. A number of the main operations use callable objects which can be supplemented by writing your own. Builders, Scanners and Tools each use a kind of plugin system, allowing you to easily drop in new ones. Information about creating Builder 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 objects that need to know about those actions (besides Builders, see &f-link-AddPostAction;, &f-link-AddPreAction; and &f-link-Alias; for some examples of other places that take Actions). Action Objects are also described below. Adding new Tool modules is described in Tool Modules

#### Builder Objects

&scons; can be extended to build different types of targets by adding new Builder objects to a &consenv;. In general, you should only need to add a new Builder object when you want to build a new type of file or other external target. For output file types &scons; already knows about, you can usually modify the behavior of premade Builders such as &b-link-Program;, &b-link-Object; or &b-link-Library; by changing the &consvars; they use (&cv-link-CC;, &cv-link-LINK;, etc.). In this manner you can, for example, change the compiler to use, which is simpler and less error-prone than writing a new builder. The documentation for each Builder lists which &consvars; it uses.

Builder objects are created using the &f-link-Builder; factory function. Once created, a builder is added to an environment by entering it in the &cv-link-BUILDERS; dictionary in that environment (some of the examples in this section illustrate this). Doing so automatically triggers &SCons; to add a method with the name of the builder to the environment.

The &f-Builder; function accepts the following keyword arguments:

action

  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 to execute with its arguments (suitable for enclosing white space in an argument), a dictionary mapping source file name suffixes to any combination of command line strings (if the builder should accept multiple source file extensions), a Python function, an Action object (see Action Objects) or a list of any of the above.

  An action function must accept three arguments: source, target and env. source is a list of source nodes; target is a list of target nodes; env is the &consenv; to use for context.

  The action and generator arguments must not both be used for the same Builder.

prefix

  The prefix to prepend to the target file name. prefix may be a string, a function (or other callable) that takes two arguments (a &consenv; and a list of sources) and returns a prefix string, or a dictionary specifying a mapping from a specific source suffix (of the first source specified) to a corresponding target prefix string. For the dictionary form, both the source suffix (key) and target prefix (value) specifications may use environment variable substitution, and the target prefix may also be a callable object. The default target prefix may be indicated by a dictionary entry with a key of `None`.

      b = Builder("build_it < $SOURCE > $TARGET",
                  prefix="file-")

      def gen_prefix(env, sources):
          return "file-" + env['PLATFORM'] + '-'

      b = Builder("build_it < $SOURCE > $TARGET",
                  prefix=gen_prefix)

      b = Builder("build_it < $SOURCE > $TARGET",
                  suffix={None: "file-", "$SRC_SFX_A": gen_prefix})

suffix

  The suffix to append to the target file name. Specified in the same manner as for prefix above. If the suffix is a string, then &scons; prepends a `'.'` to the suffix if it's not already there. The string returned by the callable object or obtained from the dictionary is untouched and you need to manually prepend a `'.'` if one is required.

      b = Builder("build_it < $SOURCE > $TARGET"
                  suffix="-file")

      def gen_suffix(env, sources):
          return "." + env['PLATFORM'] + "-file"

      b = Builder("build_it < $SOURCE > $TARGET",
                  suffix=gen_suffix)

      b = Builder("build_it < $SOURCE > $TARGET",
                  suffix={None: ".sfx1", "$SRC_SFX_A": gen_suffix})

ensure_suffix

  If set to a true value, ensures that targets will end in suffix. Thus, the suffix will also be added to any target strings that have a suffix that is not already suffix. The default behavior (also indicated by a false value) is to leave unchanged any target string that looks like it already has a suffix.

      b1 = Builder("build_it < $SOURCE > $TARGET"
                   suffix = ".out")
      b2 = Builder("build_it < $SOURCE > $TARGET"
                   suffix = ".out",
                   ensure_suffix=True)
      env = Environment()
      env['BUILDERS']['B1'] = b1
      env['BUILDERS']['B2'] = b2

      # Builds "foo.txt" because ensure_suffix is not set.
      env.B1('foo.txt', 'foo.in')

      # Builds "bar.txt.out" because ensure_suffix is set.
      env.B2('bar.txt', 'bar.in')

src_suffix

  The expected source file name suffix. src_suffix may be a string or a list of strings.

target_scanner

  A Scanner object that will be invoked to find implicit dependencies for this target file. This keyword argument should be used for Scanner objects that find implicit dependencies based only on the target file and the &consenv;, not for implicit dependencies based on source files. See for information about creating Scanner objects.

source_scanner

  A Scanner object that will be invoked to find implicit dependencies in any source files used to build this target file. This is where you would specify a scanner to find things like `#include` lines in source files. The pre-built DirScanner Scanner object may be used to indicate that this Builder should scan directory trees for on-disk changes to files that &scons; does not know about from other Builder or function calls. See for information about creating your own Scanner objects.

target_factory

  A factory function that the Builder will use to turn any targets specified as strings into SCons Nodes. By default, SCons assumes that all targets are files. Other useful target_factory values include Dir, for when a Builder creates a directory target, and Entry, for when a Builder can create either a file or directory target.

  Example:

      MakeDirectoryBuilder = Builder(action=my_mkdir, target_factory=Dir)
      env = Environment()
      env.Append(BUILDERS={'MakeDirectory': MakeDirectoryBuilder})
      env.MakeDirectory('new_directory', [])

  Note that the call to this `MakeDirectory` Builder needs to specify an empty source list to make the string represent the builder's target; without that, it would assume the argument is the source, and would try to deduce the target name from it, which in the absence of an automatically-added prefix or suffix would lead to a matching target and source name and a circular dependency.

source_factory

  A factory function that the Builder will use to turn any sources specified as strings into SCons Nodes. By default, SCons assumes that all source are files. Other useful source_factory values include Dir, for when a Builder uses a directory as a source, and Entry, for when a Builder can use files or directories (or both) as sources.

  Example:

      CollectBuilder = Builder(action=my_mkdir, source_factory=Entry)
      env = Environment()
      env.Append(BUILDERS={'Collect': CollectBuilder})
      env.Collect('archive', ['directory_name', 'file_name'])

emitter

  A function or list of functions to manipulate the target and source lists before dependencies are established and the target(s) are actually built. emitter can also be a string containing a &consvar; to expand to an emitter function or list of functions, or a dictionary mapping source file suffixes to emitter functions. (Only the suffix of the first source file is used to select the actual emitter function from an emitter dictionary.)

  A function passed as emitter must accept three arguments: source, target and env. source is a list of source nodes, target is a list of target nodes, env is the &consenv; to use for context.

  An emitter must return a tuple containing two lists, the list of targets to be built by this builder, and the list of sources for this builder.

  Example:

      def e(target, source, env):
          return target + ['foo.foo'], source + ['foo.src']

      # Simple association of an emitter function with a Builder.
      b = Builder("my_build < $TARGET > $SOURCE", emitter=e)

      def e2(target, source, env):
          return target + ['bar.foo'], source + ['bar.src']

      # Simple association of a list of emitter functions with a Builder.
      b = Builder("my_build < $TARGET > $SOURCE", emitter=[e, e2])

      # Calling an emitter function through a construction variable.
      env = Environment(MY_EMITTER=e)
      b = Builder("my_build < $TARGET > $SOURCE", emitter='$MY_EMITTER')

      # Calling a list of emitter functions through a construction variable.
      env = Environment(EMITTER_LIST=[e, e2])
      b = Builder("my_build < $TARGET > $SOURCE", emitter='$EMITTER_LIST')

      # Associating multiple emitters with different file
      # suffixes using a dictionary.
      def e_suf1(target, source, env):
          return target + ['another_target_file'], source

      def e_suf2(target, source, env):
          return target, source + ['another_source_file']

      b = Builder(
          action="my_build < $TARGET > $SOURCE",
          emitter={'.suf1': e_suf1, '.suf2': e_suf2}
      )

multi

  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 file(s). Calling a builder multiple times for the same target simply adds additional source files to the target; it is not allowed to change the environment associated with the target, specify additional environment overrides, or associate a different builder with the target.

env

  A &consenv; that can be used to fetch source code using this Builder. (Note that this environment is not used for normal builds of normal target files, which use the environment that was used to call the Builder for the target file.)

generator

  A function that returns a list of actions that will be executed to build the target(s) from the source(s). The returned action(s) may be an Action object, or anything that can be converted into an Action object (see the next section).

  A function passed as generator must accept four arguments: source, target, env and for_signature. source is a list of source nodes, target is a list of target nodes, env is the &consenv; to use for context, and for_signature is a Boolean value that tells the function if it is being called for the purpose of generating a &buildsig; (as opposed to actually executing the command). Since the &buildsig; 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:

      def g(source, target, env, for_signature):
          return [["gcc", "-c", "-o"] + target + source]

      b = Builder(generator=g)

  The generator and action arguments must not both be used for the same Builder.

src_builder

  Specifies a builder to use when a source file name suffix does not match any of the suffixes of the builder. Using this argument produces a multi-stage builder.

single_source

  Specifies that this builder expects exactly one source file per call. Giving more than one source file without target files results in implicitly calling the builder multiple times (once for each source given). Giving multiple source files together with target files results in a UserError exception.

source_ext_match

  When the specified action argument is a dictionary, the default behavior when a builder is passed multiple source files is to make sure that the extensions of all the source files match. If it is legal for this builder to be called with a list of source files with different extensions, this check can be suppressed by setting source_ext_match to `False` or some other non-true value. In this case, &scons; will use the suffix of the first specified source file to select the appropriate action from the action dictionary.

  In the following example, the setting of source_ext_match prevents &scons; from exiting with an error due to the mismatched suffixes of `foo.in` and `foo.extra`.

      b = Builder(action={'.in' : 'build $SOURCES > $TARGET'},
                  source_ext_match=False)

      env = Environment(BUILDERS={'MyBuild':b})
      env.MyBuild('foo.out', ['foo.in', 'foo.extra'])

env

  A &consenv; that can be used to fetch source code using this Builder. (Note that this environment is not used for normal builds of normal target files, which use the environment that was used to call the Builder for the target file.)

      b = Builder(action="build < $SOURCE > $TARGET")
      env = Environment(BUILDERS={'MyBuild' : b})
      env.MyBuild('foo.out', 'foo.in', my_arg='xyzzy')

chdir

  A directory from which scons will execute the action(s) specified for this Builder. 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 and is non-zero, then scons will change to the target file's directory.

  Note that scons will not automatically modify its expansion of &consvars; 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 containing the &SConstruct; file, and consequently incorrect relative to the chdir directory. Builders created using chdir keyword argument, will need to use &consvar; expansions like `${TARGET.file}` and `${SOURCE.file}` to use just the filename portion of the targets and source.

      b = Builder(action="build < ${SOURCE.file} > ${TARGET.file}",
                  chdir=1)
      env = Environment(BUILDERS={'MyBuild' : b})
      env.MyBuild('sub/dir/foo.out', 'sub/dir/foo.in')

  Python only keeps one current directory location even if there are multiple threads. This means that use of the chdir argument will not work with the SCons `-j` option, because individual worker threads spawned by SCons interfere with each other when they start changing directory.

Any additional keyword arguments supplied when a Builder object is created (that is, when the &f-link-Builder; 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 &consvar; to the repository of a source code system.

Any such keyword arguments supplied when a Builder object is called will only be associated with the target created by that particular &f-Builder; call (and any other files built as a result of the call). These extra keyword arguments are passed to the following functions: command generator functions, function Actions, and emitter functions.

#### Action Objects

The &f-link-Builder; factory function will turn its action keyword argument into an appropriate internal Action object, as will the &f-link-Command; function. You can also explicitly create Action objects for passing to &f-Builder;, or other functions that take actions as arguments, by calling the &f-link-Action; factory function. This may more efficient when multiple Builder objects need to do the same thing rather than letting each of those Builder objects create a separate Action object. It also allows more flexible configuration of an Action object. For example, to control the message printed when the action is taken you need to create the action object using &f-Action;.

The &Action; factory function returns an appropriate object for the action represented by the type of the action argument (the first positional parameter):

- 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 string begins with `@`, the command line is not printed. If the string begins with hyphen (`-`), the exit status from the specified command is ignored, allowing execution to continue even if the command reports failure:

      Action('$CC -c -o $TARGET $SOURCES')

      # Doesn't print the line being executed.
      Action('@build $TARGET $SOURCES')

      # Ignores return value
      Action('-build $TARGET $SOURCES')

- If action is a list, then a list of Action objects is returned. An Action object is created as necessary for each element in the list. If an element within the list is itself a list, the embedded list is taken as the command and arguments to be executed via the command line. This allows white space to be enclosed in an argument rather than taken as a separator by defining a command in a list within a list:

      Action([['cc', '-c', '-DWHITE SPACE', '-o', '$TARGET', '$SOURCES']])

- If action is a callable object, a Function Action is returned. The callable must accept three keyword arguments: target, source and env. target is a Node object representing the target file, source is a Node object representing the source file and env is the &consenv; used for building the target file.

  The target and source arguments may be lists of Node objects if there is more than one target file or source file. The actual target and source file name(s) may be retrieved from their Node objects via the built-in Python `str` function:

      target_file_name = str(target)
      source_file_names = [str(x) for x in source]

  The function should return `0` or `None` to indicate a successful build of the target file(s). The function may raise an exception or return a non-zero exit status to indicate an unsuccessful build.

      def build_it(target=None, source=None, env=None):
          # build the target from the source
          return 0

      a = Action(build_it)

- If action is not one of the above types, no action object is generated and &f-Action; returns `None`.

The environment method form &f-link-env-Action; will expand &consvars; in any argument strings, including action, at the time it is called, using the construction variables in the &consenv; through which it was called. The global function form &f-link-Action; delays variable expansion until the Action object is actually used.

The optional second argument to &f-Action; is used to control the output which is printed when the Action is actually performed. If this parameter is omitted, or if the value is an empty string, a default output 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:

- If the second argument is a string, or if the cmdstr keyword argument is supplied, the string defines what is printed. Substitution is performed on the string before it is printed. The string typically contains substitutable variables, notably `$TARGET(S)` and `$SOURCE(S)`, or consists of just a single variable which is optionally defined somewhere else. &SCons; itself heavily uses the latter variant.

- If the second argument is a function, or if the strfunction keyword argument is supplied, the function will be called to obtain the string to be printed when the action is performed. The function must accept three keyword arguments: target, source and env, with the same interpretation as for a callable action argument above. The function is responsible for handling any required substitutions.

- If the second argument is `None`, or if `cmdstr=None` is supplied, output is suppressed entirely.

The cmdstr and strfunction keyword arguments may not both be supplied in a single call to &f-Action;

Printing of action strings is affected by the setting of &cv-link-PRINT_CMD_LINE_FUNC;.

Examples:

    def build_it(target, source, env):
        # build the target from the source
        return 0

    def string_it(target, source, env):
        return "building '%s' from '%s'" % (target[0], source[0])

    # Use a positional argument.
    f = Action(build_it, string_it)
    s = Action(build_it, "building '$TARGET' from '$SOURCE'")

    # Alternatively, use a keyword argument.
    f = Action(build_it, strfunction=string_it)
    s = Action(build_it, cmdstr="building '$TARGET' from '$SOURCE'")

    # You can provide a configurable variable.
    l = Action(build_it, '$STRINGIT')

Any additional positional arguments, if present, may either be &consvars; or lists of &consvars; whose values will be included in the signature of the Action (the &buildsig;) when deciding whether a target should be rebuilt because the action changed. Such variables may also be specified using the varlist keyword parameter; both positional and keyword forms may be present, and will be combined. This is necessary whenever you want a target to be rebuilt when a specific &consvar; changes. This is not often needed for a string action, as the expanded variables will normally be part of the command line, but may be needed if a Python function action uses the value of a &consvar; when generating the command line.

    def build_it(target, source, env):
        # build the target from the 'XXX' construction variable
        with open(target[0], 'w') as f:
            f.write(env['XXX'])
        return 0

    # Use positional arguments.
    a = Action(build_it, '$STRINGIT', ['XXX'])

    # Alternatively, use a keyword argument.
    a = Action(build_it, varlist=['XXX'])

The &Action; factory function can be passed the following optional keyword arguments to modify the Action object's behavior:

chdir

  If chdir is true (the default is `False`), &SCons; will change directories before executing the action. If the value of chdir is a string or a directory Node, &SCons; will change to the specified directory. Otherwise, if chdir evaluates true, &SCons; will change to the target file's directory.

  Note that &SCons; will not automatically modify its expansion of &consvars; like &cv-TARGET; and &cv-SOURCE; when using the chdir parameter - that is, the expanded file names will still be relative to the top-level directory containing the &SConstruct; file, and consequently incorrect relative to the chdir directory. Builders created using chdir keyword argument, will need to use &consvar; expansions like `${TARGET.file}` and `${SOURCE.file}` to use just the filename portion of the targets and source. Example:

      a = Action("build < ${SOURCE.file} > ${TARGET.file}", chdir=True)

exitstatfunc

  If provided, must be a callable which accepts a single parameter, the exit status (or return value) from the specified action, and which returns an arbitrary or modified value. This can be used, for example, to specify that an Action object's return value should be ignored under special conditions and SCons should, therefore, consider that the action always succeeds. Example:

      def always_succeed(s):
          # Always return 0, which indicates success.
          return 0

      a = Action("build < ${SOURCE.file} > ${TARGET.file}",
                 exitstatfunc=always_succeed)

batch_key

  If provided, indicates that the Action can create multiple target files by processing multiple independent source files simultaneously. (The canonical example is "batch compilation" of multiple object files by passing multiple source files to a single invocation of a compiler such as Microsoft's Visual C / C++ compiler.) If the batch_key argument evaluates True and is not a callable object, the configured Action object will cause &scons; to collect all targets built with the Action object and configured with the same &consenv; into single invocations of the Action object's command line or function. Command lines will typically want to use the &cv-CHANGED_SOURCES; &consvar; (and possibly &cv-CHANGED_TARGETS; as well) to only pass to the command line those sources that have actually changed since their targets were built. Example:

      a = Action('build $CHANGED_SOURCES', batch_key=True)

  The batch_key argument may also be a callable function that returns a key that will be used to identify different "batches" of target files to be collected for batch building. A batch_key function must accept four parameters: action, env, target and source. The first parameter, action, is the active action object. The second parameter, env, is the &consenv; configured for the target. The target and source parameters are the lists of targets and sources for the configured action.

  The returned key should typically be a tuple of values derived from the arguments, using any appropriate logic to decide how multiple invocations should be batched. For example, a batch_key function may decide to return the value of a specific &consvar; from env which will cause &scons; to batch-build targets with matching values of that &consvar;, or perhaps return the Python `id`() of the entire &consenv;, in which case &scons; will batch-build all targets configured with the same &consenv;. Returning `None` indicates that the particular target should not be part of any batched build, but instead will be built by a separate invocation of action's command or function. Example:

      def batch_key(action, env, target, source):
          tdir = target[0].dir
          if tdir.name == 'special':
              # Don't batch-build any target
              # in the special/ subdirectory.
              return None
          return (id(action), id(env), tdir)
      a = Action('build $CHANGED_SOURCES', batch_key=batch_key)

##### Miscellaneous Action Functions

&SCons; supplies Action functions that arrange for various common file and directory manipulations to be performed. These are similar in concept to "tasks" in the &Ant; build tool, although the implementation is slightly different. These functions do not actually perform the specified action at the time the function is called, but rather are factory functions which return an Action object that can be executed at the appropriate time.

There are two natural ways that these Action Functions are intended to be used.

First, if you need to perform the action at the time the &SConscript; file is being read, you can use the &f-link-Execute; global function:

    Execute(Touch('file'))

Second, you can use these functions to supply Actions in a list for use by the &f-link-env-Command; method. This can allow you to perform more complicated sequences of file manipulation without relying on platform-specific external commands:

    env = Environment(TMPBUILD='/tmp/builddir')
    env.Command(
        target='foo.out',
        source='foo.in',
        action=[
            Mkdir('$TMPBUILD'),
            Copy('$TMPBUILD', '${SOURCE.dir}'),
            "cd $TMPBUILD && make",
            Delete('$TMPBUILD'),
        ],
    )

`Chmod`(dest, mode)

  Returns an Action object that changes the permissions on the specified dest file or directory to the specified mode which can be octal or string, similar to the POSIX `chmod` command. Examples:

      Execute(Chmod('file', 0o755))

      env.Command(
          'foo.out',
          'foo.in',
          [Copy('$TARGET', '$SOURCE'), Chmod('$TARGET', 0o755)],
      )

      Execute(Chmod('file', "ugo+w"))

      env.Command(
          'foo.out',
          'foo.in',
          [Copy('$TARGET', '$SOURCE'), Chmod('$TARGET', "ugo+w")],
      )

  The behavior of `Chmod` is limited on Windows, see the notes in the Python documentation for os.chmod, which is the underlying function.

`Copy`(dest, src)

  Returns an Action object that will copy the src source file or directory to the dest destination file or directory. If src is a list, dest must be a directory if it already exists. Examples:

      Execute(Copy('foo.output', 'foo.input'))

      env.Command('bar.out', 'bar.in', Copy('$TARGET', '$SOURCE'))

`Delete`(entry, [must_exist])

  Returns an Action that deletes the specified entry, which may be a file or a directory tree. If a directory is specified, the entire directory tree will be removed. If the must_exist flag is set to a true value, then a Python error will be raised if the specified entry does not exist; the default is false, that is, the Action will silently do nothing if the entry does not exist. Examples:

      Execute(Delete('/tmp/buildroot'))

      env.Command(
          'foo.out',
          'foo.in',
          action=[
              Delete('${TARGET.dir}'),
              MyBuildAction,
          ],
      )

      Execute(Delete('file_that_must_exist', must_exist=True))

`Mkdir`(name)

  Returns an Action that creates the directory name and all needed intermediate directories. name 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'),
          ],
      )

`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_MyBuildAction')],
      )

`Touch`(file)

  Returns an Action that updates the modification time on the specified file. Examples:

      Execute(Touch('file_to_be_touched'))

      env.Command('marker', 'input_file', action=[MyBuildAction, Touch('$TARGET')])

##### Variable Substitution

Before executing a command, &scons; performs parameter expansion (substitution) on the string that makes up the action part of the builder. The format of a substitutable parameter is `${expression}`. If expression refers to a variable, the braces in `${expression}` can be omitted unless the variable name is immediately followed by a character that could either be interpreted as part of the name, or is &Python; syntax such as [ (for indexing/slicing) or . (for attribute access - see Special Attributes below).

If expression refers to a &consvar;, it is replaced with the value of that variable in the &consenv; at the time of execution. If expression looks like a variable name but is not defined in the &consenv; it is replaced with an empty string. If expression refers to one of the Special Variables (see below) the corresponding value of the variable is substituted. expression may also be a &Python; expression to be evaluated. See Python Code Substitution below for a description.

&SCons; uses the following rules when converting &consvars; into command line strings:

- If the value is a string it is interpreted as space delimited command line arguments.

- If the value is a list it is interpreted as a list of command line arguments. Each element of the list is converted to a string.

- Anything that is not a list or string is converted to a string and interpreted as a single command line argument.

- Newline characters (`\n`) delimit lines. The newline parsing is done after all other parsing, so it is not possible for arguments (e.g. file names) to contain embedded newline characters.

- For a literal $ use $$. For example, `$$FOO` will be left in the final string as `$FOO`.

When a build action is executed, a hash of the command line is saved, together with other information about the target(s) built by the action, for future use in rebuild determination. This is called the &buildsig; (or &build_action; signature). The escape sequence $( subexpression $) may be used to indicate parts of a command line that may change without causing a rebuild--that is, which are not to be included when calculating the &buildsig;. All text from $( up to and including the matching $) will be removed from the command line before it is added to the &buildsig; while only the $( and $) will be removed before the command is executed. For example, the command line string:

    "echo Last build occurred $( $TODAY $). > $TARGET"

would execute the command:

    echo Last build occurred $TODAY. > $TARGET

but the &buildsig; added to any target files would be computed from:

    echo Last build occurred  . > $TARGET

While &consvars; are normally directly substituted, if a &consvar; has a value which is a callable &Python; object (a function, or a class with a `__call__` 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 &consenv; to use for context, and for_signature is a boolean value that tells the callable if it is being called for the purpose of generating a &buildsig;. Since the &buildsig; is used for rebuild determination, variable elements that do 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.

&SCons; will insert whatever the callable 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, substitution happens when `$BAR` is actually used in a builder action. The value of `env['BAR']` will be exactly as it was set: `"$FOO baz"`. This can make debugging tricky, as the substituted result is not available at the time the &SConscript; files are being interpreted and thus not available to the print function. However, you can perform the substitution on demand by calling the &f-link-env-subst; method for this purpose.

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 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")

##### Substitution: Special Variables

Besides regular &consvars;, scons provides the following Special Variables for use in expanding commands:

&cv-CHANGED_SOURCES;

  The file names of all sources of the build command that have changed since the target was last built.

&cv-CHANGED_TARGETS;

  The file names of all targets that would be built from sources that have changed since the target was last built.

&cv-SOURCE;

  The file name of the source of the build command, or the file name of the first source if multiple sources are being built.

&cv-SOURCES;

  The file names of the sources of the build command.

&cv-TARGET;

  The file name of the target being built, or the file name of the first target if multiple targets are being built.

&cv-TARGETS;

  The file names of all targets being built.

&cv-UNCHANGED_SOURCES;

  The file names of all sources of the build command that have not changed since the target was last built.

&cv-UNCHANGED_TARGETS;

  The file names of all targets that would be built from sources that have not changed since the target was last built.

These names are reserved and may not be assigned to or used as &consvars;. &SCons; computes them in a context-dependent manner and they and are not retrieved from a &consenv;.

For example, the following builder call:

    env = Environment(CC='cc')
    env.Command(
        target=['foo'],
        source=['foo.c', 'bar.c'],
        action='@echo $CC -c -o $TARGET $SOURCES'
    )

would produce the following output:

    cc -c -o foo foo.c bar.c

In the previous example, a string `${SOURCES[1]}` would expand to: `bar.c`.

##### Substitution: Special Attributes

A variable name may have the following modifiers appended within the enclosing curly braces to access properties of the interpolated string. These are known as special attributes.

- 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 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 &f-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 &f-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 &f-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 corresponding modifiers:

    $TARGET              => sub/dir/file.x
    ${TARGET.base}       => sub/dir/file
    ${TARGET.dir}        => sub/dir
    ${TARGET.file}       => file.x
    ${TARGET.filebase}   => file
    ${TARGET.suffix}     => .x
    ${TARGET.abspath}    => /top/dir/sub/dir/file.x
    ${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 not 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 &consvars;, and the result substituted in. So in the following case:

    env.Command(
        'foo.out', 'foo.in', "echo ${COND==1 and 'FOO' or 'BAR'} > $TARGET"
    )

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 executed. 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` are &consvars;, 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} > $TARGET"
    )

will execute:

    echo foo1 foo2 > foo.out

In point of fact, Python expression evaluation is how the special attributes are substituted: they are simply attributes of the Python objects that represent &cv-TARGET;, &cv-SOURCES;, etc., which &SCons; passes to `eval` which returns the value.

Use of the Python `eval` function is considered to have security implications, since, depending on input sources, arbitrary unchecked strings of code can be executed 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 are used to scan specific file types for implicit dependencies, for example embedded preprocessor/compiler directives that cause other files to be included during processing. &SCons; has a number of pre-built Scanner objects, so it is usually only necessary to set up Scanners for new file types. You do this by calling the &f-link-Scanner; factory function. &f-Scanner; accepts the following arguments. Only function is required; the rest are optional:

function

  A scanner function to call to process a given Node (usually a file) and return a list of Nodes representing the implicit dependencies (usually files) found in the contents. The function must accept 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 &consenv; to use during the scan, and path is a tuple of directories that can be searched for files, as generated by the optional scanner path_function (see below). If argument was supplied when the Scanner object was created, it is given as arg when the scanner function is called; since argument is optional, the default is no arg.

  The function can use use `str`(node) to fetch the name of the file, node.`dir` to fetch the directory the file is in, node.`get_contents`() to fetch the contents of the file as bytes or node.`get_text_contents`() to fetch the contents of the file as text.

  The function must take into account the path directories when generating the dependency Nodes. To illustrate this, a C language source file may contain a line like `#include "foo.h"`. However, there is no guarantee that `foo.h` exists in the current directory: the contents of &cv-link-CPPPATH; is passed to the C preprocessor which will look in those places for the header, so the scanner function needs to look in those places as well in order to build Nodes with correct paths. Using &f-link-FindPathDirs; with an argument of `CPPPATH` as the path_function in the &f-Scanner; call means the scanner function will be called with the paths extracted from &cv-CPPPATH; in the environment env passed as the paths 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 function 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 then used to pass the file on to a different Scanner that would not have been selected to handle that Node based on its own skeys.

name

  The name to use for the Scanner. This is mainly used to identify the Scanner internally. The default value is `"NONE"`.

argument

  If specified, will be passed to the scanner function function and the path function path_function when called, as the optional parameter each of those functions takes.

skeys

  Scanner key(s) indicating the file types this scanner is associated with. Used internally to select an appropriate scanner. In the usual case of scanning for file names, this argument will be a list of suffixes for the different file types that this Scanner knows how to scan. If skeys is a string, it will be expanded into a list by the current environment.

path_function

  A Python function that takes four or five arguments: a &consenv;, a Node for the directory containing the &SConscript; file in which the first target was defined, a list of target nodes, a list of source nodes, and the value of argument if it was supplied when the Scanner was created. Must return a tuple of directories that can be searched for files to be returned by this Scanner object. (Note that the &f-link-FindPathDirs; function can be used to return a ready-made path_function for a given &consvar; name, instead of having to write your own function from scratch.)

node_class

  The class of Node that should be returned by this Scanner object. Any strings or other objects returned by the scanner function that are not of this class will be run through the function supplied by the node_factory argument. A value of `None` can be supplied to indicate no conversion; the default is to return File nodes.

node_factory

  A Python function that will take a string or other object and turn it into the appropriate class of Node to be returned by this Scanner object, as indicated by node_class.

scan_check

  A Python function that takes two arguments, a Node (file) and a &consenv;, and returns whether the Node should, in fact, be scanned for dependencies. This check can be used to eliminate unnecessary calls to the scanner function when, for example, the underlying file represented by a Node does not yet exist.

recursive

  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 file being scanned and not recurse. Recursion is needed when the files returned by the scanner may themselves contain further file 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 will be called with a list of Nodes found and should return a list of Nodes that should be scanned recursively; this can be used to select a specific subset of Nodes for additional scanning.

Once created, a Scanner can added to an environment by setting it in the &cv-link-SCANNERS; list, which automatically triggers &SCons; to also add it to the environment as a method. However, usually a scanner is not truly standalone, but needs to be plugged in to the existing selection mechanism for deciding how to scan source files based on filename extensions. For this, &SCons; has a global SourceFileScanner object that is used by the &b-link-Object;, &b-link-SharedObject; and &b-link-StaticObject; builders to decide which scanner should be used. You can use the SourceFileScanner.add_scanner() method to add your own Scanner object to the &SCons; infrastructure that builds target programs or libraries from a list of source files of different types:

    def xyz_scan(node, env, path):
        contents = node.get_text_contents()
        # Scan the contents and return the included files.

    XYZScanner = Scanner(xyz_scan)

    SourceFileScanner.add_scanner('.xyz', XYZScanner)

    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 `site_tools` subdirectory of a site directory, or in a custom location specified to &scons; by giving the toolpath keyword argument to &f-link-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 the name of the tool (e.g. `mytool.py`) or a directory taking the name of the tool (e.g. `mytool/`) which 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 `mytool`) 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 path. The default tool path is any `site_tools` directories, so tools in a specified toolpath take priority, followed by tools in a `site_tools` directory, followed by built-in tools. For example, adding a tool specification module `gcc.py` to the toolpath directory would override the built-in &t-link-gcc; tool. The tool path is stored in the environment and will be used by subsequent calls to the &f-link-Tool; method, as well as by &f-link-env-Clone;.

    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 &consenv; env to set up necessary &consvars;, Builders, Emitters, etc., so the facilities represented by the tool can be executed. Care should be taken not to overwrite &consvars; 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 supplies 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 supplied env, but the tool can make the exists decision in any way it chooses.

At the moment, user-added tools do not automatically have their `exists` function called. As a result, it is recommended that the `generate` function be defensively coded - that is, do not rely on any necessary existence checks already having been performed. This is expected 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 &consenv; (see &f-link-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` 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, **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 &cv-link-PLATFORM; variable from the &consenv; it is passed to customize the tool for different platforms.

Tools can be "nested" - that is, they can be located within a subdirectory 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.SomeTool'])
    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

&scons; and its configuration files are very portable, due largely to its implementation in Python. There are, however, a few portability issues waiting to trap the unwary.

#### .C File Suffix

&scons; handles the upper-case `.C` file suffix differently, depending on the capabilities of the underlying system. On a case-sensitive system such as Linux or UNIX, &scons; treats a file with a `.C` suffix as a C++ source file. On a case-insensitive system such as Windows, &scons; treats a file with a `.C` suffix as a C source file.

#### Fortran File Suffixes

There are several ways source file suffixes impact the behavior of &SCons; when working with Fortran language code (not all are system-specific, but they are included here for completeness).

As the Fortran language has evolved through multiple standards editions, projects might have a need to handle files from different language generations differently. To this end, &SCons; dispatches to a different compiler dialect setup (expressed as a set of &consvars;) depending on the file suffix. By default, all of these setups start out the same, but individual &consvars; can be modified as needed to tune a given dialect. Each of these dialacts has a tool specification module whose documentation describes the &consvars; associated with that dialect: `.f` (as well as `.for` and `.ftn`) in &t-link-fortran;; (&consvars; start with `FORTRAN`) `.f77` in &t-link-f77;; (&consvars; start with `F77`) `.f90` in &t-link-f90;; (&consvars; start with `F90`) `.f95` in &t-link-f95;; (&consvars; start with `F95`) `.f03` in &t-link-f03;; (&consvars; start with `F03`) `.f08` in &t-link-f08; (&consvars; start with `F08`).

While &SCons; recognizes multiple internal dialects based on filename suffixes, 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 available option in FORTRAN 77 and earlier, and `.f90` refers to free-format source code which became available as of the Fortran 90 standard. Some compilers recognize suffixes which correspond to Fortran specifications 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 filename 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 suffix.

The source file suffix does not imply conformance with the similarly-named Fortran standard - a suffix of `.f08` does not mean you are compiling specifically for Fortran 2008. Normally, compilers provide command-line options for making this selection (e.g. `-std=f2008` for gfortran).

For dialects from F90 on (including the generic FORTRAN dialect), a suffix of `.mod` is recognized for Fortran modules. These files are a side effect of compiling a Fortran source file containing module declarations, and must be available when other code which declares that it uses the module is processed. &SCons; does not currently have integrated support for submodules, introduced 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 do not trigger this behavior. On systems which do not distinguish between uppper and lower case in filenames, 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 will be selected.

&SCons; itself does not invoke the preprocessor, that is handled by the compiler, but it adds &consvars; which are applicable to the preprocessor run. You can see this difference by examining &cv-link-FORTRANPPCOM; and &cv-link-FORTRANPPCOMSTR; which are used instead of &cv-link-FORTRANCOM; and &cv-link-FORTRANCOMSTR; for that dialect.

#### Windows: Cygwin Tools and Cygwin Python vs. Windows Pythons

Cygwin supplies a set of tools and utilities that let users work on a Windows system using a POSIX-like environment. The Cygwin tools, including Cygwin &Python;, do this, in part, by sharing an ability to interpret POSIX-style path names. For example, the Cygwin tools will internally translate a Cygwin path name like `/cygdrive/c/mydir` to an equivalent Windows pathname of `C:/mydir` (equivalent to `C:\mydir`).

Versions of &Python; that are built for native Windows execution, such as the python.org and ActiveState versions, do not understand the Cygwin path name semantics. This means that using a native Windows version of &Python; to build compiled programs using Cygwin tools (such as &gcc;, &bison; and &flex;) may yield unpredictable results. "Mixing and matching" in this way can be made to work, but it requires careful attention to the use of path names in your &SConscript; files.

In practice, users can sidestep the issue by adopting the following guidelines: When using Cygwin's &gcc; for compiling, use the Cygwin-supplied &Python; interpreter to run &scons;; when using Microsoft Visual C/C++ (or some other "native" Windows compiler) use the python.org, Microsoft Store, ActiveState or other native version of &Python; to run &scons;.

This discussion largely applies to the msys2 environment as well (with the 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

On Windows, if &scons; is executed via a wrapper `scons.bat` batch file, there are (at least) two ramifications. Note this is no longer the default - &scons; installed via &Python;''s `pip` installer will have 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 double quotes around the assignments, otherwise the Windows command shell will consume those as arguments to itself, not to &scons;:

    scons "FOO=BAR" "BAZ=BLEH"

Second, the Cygwin shell does not recognize typing `scons` at the command line prompt as referring to this wrapper. You can work around this either by executing `scons.bat` (including the extension) from the Cygwin command line, or by creating a wrapper shell script named `scons` which invokes `scons.bat`.

#### MinGW

The MinGW `bin` directory must be in your `PATH` environment variable or the `['ENV']['PATH']` &consvar; for &scons; to detect and use the MinGW tools. When running under the native Windows Python; interpreter, &scons; will prefer the MinGW tools over the Cygwin tools, if they are both installed, regardless of the order of the bin directories in the `PATH` variable. If you have both MSVC and MinGW installed and you want to use MinGW instead of MSVC, then you must explicitly tell &scons; to use MinGW by passing `tools=['mingw']` to the &Environment; function, because &scons; will prefer the MSVC tools over the MinGW tools.

### ENVIRONMENT

In general, &scons; is not controlled by environment variables set in the shell used to invoke it, leaving it up to the &SConscript; file author to import those if desired. However the following variables are imported by &scons; itself if set:

`SCONS_LIB_DIR`

  Specifies the directory that contains the &scons; Python module directory. Normally &scons; can deduce this, but in some circumstances, such as working with a source release, it may be necessary to specify (for example, `/home/aroach/scons-src-0.01/src/engine`).

`SCONSFLAGS`

  A string containing options that will be used by &scons; in addition to those passed on the command 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 line can be used to override `SCONSFLAGS` options if necessary.

`SCONS_CACHE_MSVC_CONFIG`

  (Windows only). If set, save the shell environment variables generated when setting up the Microsoft Visual C++ compiler (and/or Build Tools) to a cache file, to give these settings persistence across &scons; invocations. Generating this information is relatively expensive, so using this option may aid performance where &scons; is run often, such as Continuous Integration setups.

  If set to a True-like value (`"1"`, `"true"` or `"True"`) will cache to a file named `scons_msvc_cache.json` in the user's home directory. If set to a pathname, will use that pathname for the cache.

  Note: this implementation may still be somewhat fragile. In case of problems, remove the cache file - recreating with fresh info normally resolves any issues. &SCons; ignores failures reading or writing the cache file and will silently revert to non-cached behavior in such cases.

  New in 3.1 (experimental). The default cache file name was changed to its present value in 4.4, and contents were expanded.

`QTDIR`

  If using the &t-link-qt; tool, this is the path to the Qt installation to build against. &SCons; respects this setting because it is a long-standing convention in the Qt world, where multiple Qt installations are possible.

### SEE ALSO

- The SCons User Guide at
- The SCons Design Document (old)
- The SCons Cookbook at for examples of how to solve various problems with &SCons;.
- SCons source code on GitHub
- The SCons API Reference (for internal details)

### AUTHORS

Originally: Steven Knight knight@baldmt.com and Anthony Roach aroach@electriceyeball.com.

Since 2010: The SCons Development Team scons-dev@scons.org.