# 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; is an extensible open source build system that 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 (requires the ninja package).

Changed in version 4.3.0: support for &Python; 3.5 is removed. The CPython project retired 3.5 in Sept 2020: .

Changed in version 4.8.0: support for &Python; 3.6 is deprecated and will be removed in a future &SCons; release. The CPython project retired 3.6 in Sept 2021: .

You set up an &SCons; build 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 supply 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; operates at a level of abstraction above that of pure filenames. For example if you specify a shared library target named "foo", &SCons; keeps track of the actual operating system dependent filename (such as `libfoo.so` on a GNU/Linux system and `foo.dll` on Windows), and gives you a handle to refer to that target in other steps, so you don't have to use system-specific strings 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 decide if a file has changed since the last build, although other algorithms can be used 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 also cached, so that changes to build instructions (changing flags, etc.) or to the build tools themselves (e.g. a compiler upgrade) can also trigger a rebuild.

&SCons; supports separated source and build directories (also called "out-of-tree builds") through the definition of variant directories Using a separated build directory helps keep the source directory clean of artifacts when doing searches, allows setting up differing builds ("variants") without conflicts, and allows resetting the build by just removing the build directory (note that SCons does have a "clean" mode as well). See the &f-link-VariantDir; description for more details.

When invoked, &scons; looks for a file describing the build configuration in the current directory and reads that in. The file is by default named &SConstruct;, although some variants of that, or a developer-chosen name, are also accepted (see sconscript_files). If found, the currrent directory is set as the project top directory. Certain command-line options specify alternate places to look for &SConstruct; (see `-C`, `-D`, `-u` and `-U`), which will set the project top directory to the path found. A path to the build configuration can also be specified with the `-f` option, which leaves the current directory as the project top directory.

The build configuration may be split into multiple files: the &SConstruct; file can specify additional configuration files by calling the &f-link-SConscript; function, and any file thus invoked may include further files in the same way. 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 so that &scons; has a picture of the complete dependency tree when it begins considering what needs building. Each SConscript file is processed in a separate context so settings made in one script do not leak into another; information can however be shared explicitly between scripts.

Before reading the SConscript files, &scons; looks for a site directory - a directory named `site_scons` is searched for in various system directories and in the project top directory, or if the `--site-dir` option is given, checks only for that directory. Found site directories are prepended 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. For many tasks, the simple syntax can be understood from examples, so it is normally not necessary to be a &Python; programmer to use &SCons; effectively. &SConscript; files are executed in a context that makes the facilities described in this manual page directly available (that is, no need to `import`). Standard &Python; scripting capabilities such as flow control, data manipulation, and imported &Python; modules are available to use in more complicated build configurations. 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. Progress messages show this behavior (the state change lines - those beginning with the `scons:` tag - may be suppressed using the `-Q` option):

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

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 or malicious settings, temporary debug values that are no longer needed, or a developer having different settings than another (or than the CI pipeline). Environment variables needed for the proper operation of such commands must be set in the execution environment explicitly, either by assigning the desired values, or by picking those values individually or collectively out of environment variables exposed by the &Python; `os.environ` dictionary (as external program inputs they should be validate before use). The execution environment for a given &consenv; is its &cv-link-ENV; value. A small number of environment variables are picked up automatically by &scons; itself (see environment).

In particular, if a compiler or other external command needed to build a target file is not in &scons;' idea of a standard system location, it will not be found at runtime unless you explicitly add the location into the execution environment's `PATH` element. This is a particular consideration on Windows platforms, where it is common for a command to install into an app-specific location and depend on setting `PATH` in order for them to be found, which does not automatically work for &SCons;.

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'],
            'MODULEPATH': os.environ['MODULEPATH'],
            'PKG_CONFIG_PATH': os.environ['PKG_CONFIG_PATH'],
        }
    )

Or you can 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 some 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.

The above fragments are intended to illustrate a concept. It is normally not a good idea to wipe out the entire default value of the execution environment (`env["ENV"]`), as it may carry important information for the execution of build commands.

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

See commandline_construction_variables 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 &MSVC; 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 &MSVC; 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) and macOS platforms, &scons; searches in order for the GCC tool chain, and the Intel compiler tools. The defaul tool selection can be pre-empted through the use of the `tools` argument to &consenv; creation methods, explcitly calling the &f-link-Tool; loader, the through the setting of various 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 project top directory 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. 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

json

- Write info to a JSON file for any of the following debug options if they are enabled: memory, count, time, action-timestamps

  The default output file is `scons_stats.json`

  The file name/path can be modified by using &f-link-DebugOptions; for example `DebugOptions(json='path/to/file.json')`

      $ scons --debug=memory,json 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

- Run &scons; under control of the `pdb` &Python; debugger.

      $ scons --debug=pdb
      > /usr/lib/python3.11/site-packages/SCons/Script/Main.py(869)_main()
      -> options = parser.values
      (Pdb)

  `pdb` will stop at the beginning of the &scons; main routine on startup. The search path (`sys.path`) at that point will include the location of the running &scons;, but not of the project itself. If you need to set breakpoints in your project files, you will either need to add to the path, or use absolute pathnames when referring to project files. A `.pdbrc` file in the project root can be used to add the current directory to the search path to avoid having to enter it by hand, along these lines:

      sys.path.append('.')

  Due to the implementation of the `pdb` module, the `break`, `tbreak` and `clear` commands only understand references to filenames which have a `.py` extension. (although the suffix itself can be omitted), except if you use an absolute path. As a special exception to that rule, the names &SConstruct; and &SConscript; are recognized without needing the `.py` extension.

  Changed in version 4.6.0: The names &SConstruct; and &SConscript; are now recognized without requiring `.py` suffix.

  Changed in version 4.8.0: The name `SCsub` is now recognized without requiring `.py` suffix.

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

sconscript

- Enables output indicating entering and exiting each SConscript file.

`--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` (New in version 4.2), `legacy_sched` (New in version 4.6.0).

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

`--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.1.

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

  &SCons; cannot perform &f-link-Configure; checks in no-exec mode, as they would make changes to the filesystem (see &cv-link-CONFIGUREDIR; and &cv-link-CONFIGURELOG;). It can use stored information from a previous build, if it is not out of date, so a "priming" build may make subsequent no-exec runs more useful.

`--no-site-dir`

- Do not read site directories. Neither the standard site directories (`site_scons`) nor the path specified via a previous `--site-dir` option are added to the module search path `sys.path`, searched for a `site_init.py` file, or have their `site_tools` directory included in the tool search path. Can be overridden by a subequent `--site-dir` option.

`--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 `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 included in the tool search path. The option is not additive - if given more than once, the last `path` wins.

  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 project top directory. 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.

cache-cleanup-error

- Warnings about errors when a file retrieved from the derived-file cache could not be removed.

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-reserved-variable

- Warnings about construction variables which are currently allowed, but will become reserved variables in a future release.

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.

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.

  Note the "no-" prefix is part of the name of this warning. Add an additional "-no" to disable.

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.

  Note the "no-" prefix is part of the name of this warning. Add an additional "-no" to disable.

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-built

- 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
- Functions and Environment Methods
- 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 &MSVC; 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 tools for details.

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

#### Tools

&SCons; has many included tool modules (more properly, tool specification modules) which are used to help initialize the &consenv; prior to building, and more can be written to suit a particular purpose, or added from external sources (a repository of constributed tools is available). More information on writing custom tools can be found in the Extending SCons section and specifically Tool Modules.

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 module 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. Tool setup happens when a &consenv; is constructed, and in the basic case needs no intervention - platform-specific lists of default tools are used to examine the specific capabilities of that platform and configure the environment, skipping those tools which are not applicable.

If necessary, a specific set of tools to initialize in an environment during creation may be specified using the optional keyword argument `tools`. `tools` must be a list, even if there are one (or zero) tools. This is useful to override the defaults, to specify non-default built-in tools, and to cause added tools to be called:

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

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']`.

If the `tools` argument is omitted, or if `tools` includes the reserved name `'default'`, then &SCons; will auto-detect usable tools, using the search path from the execution environment (that is, ``env`['ENV']['PATH']`) for looking up any external programs, and the platform name in effect to determine the default tools for that platform. Note the contents of &PATH; from the external environment `os.environ` is not used. Changing the `PATH` in the execution environment after the &consenv; is constructed will not cause the tools to be re-detected.

Tools can also be directly called by using the &f-link-Tool; method (see below).

&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 project top directory 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 project top directory, 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 builder_objects 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 node_objects 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 scanner_objects for more information about defining your own Scanner objects and using the `SourceFileScanner` object.

#### &SCons; Functions and Environment Methods

&SCons; provides a variety of &consenv; methods and global functions to manipulate the build configuration. Often, a &consenv; method and a global function with the same name exist for convenience. In this section, both forms are shown if the function can be called in either way. The documentation style for these is as follows:

    Function(arguments, [optional arguments, ...])  # Global function
    env.Function(arguments, [optional arguments, ...])  # Environment method

In these function signatures, arguments in brackets (`[]`) are optional, and ellipses (`...`) indicate possible repetition. Positional vs. keyword arguments are usually detailed in the following text, not in the signature itself. The &Python; positional-only (`/`) and keyword-only (`*`) markers are not used.

When the &Python; `keyword=value` style is shown, it can have two meanings. If the keyword argument is known to the function, the value is the default for that argument if it is omitted. If the keyword is unknown to the function, some methods treat it as a &consvar; assignment; otherwise an exception is raised for an unknown argument.

A global function and a same-named &consenv; method have the same base functionality, with two key differences:

1. &Consenv; methods that change the environment act on the environment instance from which they are called, while the corresponding global function acts on a special “hidden” &consenv; called the Default Environment. In some cases, the global function may take an initial argument giving the object to operate on.

2. String-valued arguments (including strings in list-valued arguments) are subject to construction variable expansion by the environment method form; variable expansion is not immediately performed in the global function. For example, `Default('$MYTARGET')` adds `'$MYTARGET'` to the list of default targets, while if the value in `env` of `MYTARGET` is `'mine'`, `env.Default('$MYTARGET'` adds `'mine'` to the default targets. For more details on &consvar; expansion, see the &Consvars; section.

Global functions are automatically in scope inside &SConscript; files. If your project adds &Python; modules that you include via the &Python; `import` statement from an &SConscript; file, such code will need to add the functions to that module’s global scope explicitly. You can do that by adding the following import to the &Python; module: `from SCons.Script import *`.

&SCons; provides the following &consenv; methods and global functions. The list can be augmented on a project basis using &f-link-AddMethod;

#### SConscript Variables

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

&ARGLIST;

- A list of the variable=value build variable arguments specified on the command line. Each element in the list is a tuple consisting of the variable and its value. The separate variable 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. Examples:

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

  The values obtained from &ARGLIST; (or from &ARGUMENTS;) are always strings since they originate from outside the &SCons; process. As "untrusted data", they should be validated before usage, and may need conversion to an appropriate type.

&ARGUMENTS;

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

  Example:

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

  See also &ARGLIST;.

&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 &DEFAULT_TARGETS; 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 has 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 a certain targets is explicitly requested for building.

  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

&ConsVars; are key-value pairs used to store information in a &consenv; that is needed needed for builds using that environment. &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. The convention is to use uppercase for all letters for easier visual identification.

&Consvars; are used to hold many different types of information. For example, the &cv-link-CPPDEFINES; variable is how to tell a C/C++ compiler about preprocessor macros you need for your build. The tool discovery that &SCons; performs will cause the &cv-link-CXX; variable to hold the name of the C++ compiler, if one was detected on the system, but you can give it a different value to force a compiler command of a different name to be used. Some variables contain lists of filename suffixes that are recognized by a particular compiler chain. &cv-link-BUILDERS; contains a mapping of configured Builder names (e.g. &b-link-Textfile;) to the actual Builder instance to call when that Builder is used. &Consvars; may include references to other &consvars;: the same tool which set up the C/C++ compiler will also set up an "action string", describing how to invoke that compiler, in &cv-link-CXXCOM;, which contains other &consvars; using `$VARIABLE` syntax. These references will be expanded and replaced on use (see Variable Substitution).

&Consvars; are referenced as if they were keys and values in a &Python; dictionary:

    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"

in the previous example, since `cvars` is an external copy, the value of &cv-CC; in the &consenv; itself is not changed by the assignment.

&Consvars; can set by passing them as keyword arguments when creating a new &consenv;:

    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'])

Many useful &consvars; are automatically defined by &SCons;, tuned to the specific platform in use, and you can modify these or define any additional &consvars; for use in your own Builders, Scanners and other tools. Take care not to overwrite ones which &SCons; is using. The following is a list of predefined &consvars;. Pay attention to whether the values are ones you may be expected to set vs. ones that are set to expected values by internal tools and other initializations and probably should not be modified.

Note the actual list available at execution time will never include all of these, as the ones detected as not being applicable (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 checks (see details below). The default value is `None`, to indicate there are no custom checks in 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, funcargs]`)

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

  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. If this is not possible, the optional `funcargs` argument can be used to specify a string containing an argument list with the same number and type of arguments as the prototype. The arguments can simply be constant values of the correct type. Modern C/C++ compilers reject implicit function declarations and may also reject function calls whose arguments are not type compatible with the prototype.

  Changed in version 4.7.0: added the `funcargs`.

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

    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, specialized information needs to be conveyed at build time to override the defaults in the build scripts. Command-line arguments (like `--implcit-cache`) and giving names of build targets are two ways to do that. Another is to provide variable-assignment arguments on the command line. For the particular case where you want to specify new values for &consvars;, &SCons; provides a &Variables; object to simplify collecting those and updating a &consenv; with the values. The typical calling style looks like:

    scons VARIABLE=foo

Variables specified in the above way can be manually processed by accessing the &ARGUMENTS; dictionary (or &ARGLIST; list), but using a &Variables; object allows you to describe anticipated variables, convert them to a suitable type if necessary, validate the values are within defined constraints, and define defaults, help messages and aliases. This is conceptually similar to the structure of options (see &f-link-AddOption;). It also allows obtaining values from a saved variables file, or from a custom dictionary in an &SConscript; file. The processed variables can then be applied to the desired &consenv;.

Roughly speaking, arguments are used to convey information to the &SCons; program about how it should behave; variables are used to convey information to the build (although &SCons; does not enforce any such constraint).

To obtain an object for manipulating variables, call the &Variables; factory function:

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

- If `files` is a filename or list of filenames, they are considered to be &Python; scripts which will be executed to set variables when the `Update` method is called - this allows the use of &Python; syntax in the assignments. A file can be the result of an earlier call to the &Save; method. If `files` is not specified, or the `files` argument is `None`, then no files will be read. Supplying `None` is required if there are no files but you want to specify `args` as a positional argument; this can be omitted if using the keyword argument style. If any of `files` is missing, it is silently skipped.

  Either of the following example file contents could be used to set an alternative C compiler:

      CC = 'my_cc'
      CC = os.environ.get('CC')

  If `args` is specified, it must be a dictionary. The key-value pairs from `args` will be added to those obtained from `files`, if any. Keys from `args` take precendence over same-named keys from `files`. If omittted, the default is the &ARGUMENTS; dictionary that holds build variables specified on the command line. Using &ARGUMENTS; allows you to indicate that if a setting appears on both the command line and in the file(s), the command line setting is preferred. However, any dictionary can be passed. Examples:

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

  Calling &Variables; with no arguments is equivalent to:

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

A &Variables; object serves as a container for descriptions of variables, which are added by calling methods of the object. Each variable consists of a name (which will become a &consvar;), aliases for the name, a help message, a default value, and functions to validate and convert values. Once the object is asked to process variables, it matches up data from the input sources it was given with the definitions, and generates key-value pairs which are added to the specified &consenv;, except that if any variable was described to have a default of `None`, it is not added to the construction environment unless it appears in the input sources. Otherwise, a variable not in the input sources is added using its default value.

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 construction_variables for a reference), since variables obtained have values overridden, not merged.

Also note there is currently no way to use the &Variables; mechanism to define a variable which the user is required to supply; if necessary this can be implemented by accessing &ARGUMENTS; directly, although that only applies to the command line, not to any stored-values files.

A Variables object has the following methods:

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

- Add a customizable &consvar; to the &Variables; object. `key` is either the name of the variable, or a sequence of strings, in which case the first item in the sequence is taken as the variable name, and any remaining values are considered aliases for the variable. `key` is mandatory, there is no default. `help` is the help text for the variable (defaults to an empty string). `default` is the default value of the variable (defaults to `None`).

  If the optional `validator` argument is supplied, it is a callback function to validate the value of the variable when the variables are processed (that is, when the &Update; method runs). A validator function 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` argument is supplied, it is a callback function to convert the value into one suitable for adding to the &consenv;. A converter function must accept the `value` argument, and may declare `env` as a second argument if it needs access to the &consenv; while validating - the function will be called appropriately. The converter is called before the validator; it must return a value, which is then passed to the `validator` (if any) for checking. In general, the converter should not fail, leaving validation checks to the validator, although if an operation is impossible to complete or there is no separate validator it can raise a ValueError.

  Substitution will be performed on the variable value before the converter and validator are called, unless the optional `subst` parameter is false (default `True`). Suppressing substitution may be useful if the variable value looks like a &consvar; reference (e.g. `$VAR`) and the validator and/or converter should see it unexpanded.

  As a special case, if `key` is a sequence and is the only argument to &Add;, it is unpacked into the five parameters `key`, `help`, `default`, `validator` and `converter`, with any missing members from the right filled in with the respective default values. This form allows it to consume a tuple emitted by the convenience functions &BoolVariable;, &EnumVariable;, &ListVariable;, &PackageVariable; and &PathVariable;.

  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)

  Changed in version 4.8.0: added the `subst` parameter.

`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. Each `args` member must be a tuple that contains the arguments for an individual call to the &Add; method using the "special case" form; the other calling styles (individual positional arguments and/or keyword arguments) are not supported.

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

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

- Process the input sources recorded when the &Variables; object was initialized and update `env` with the customized &consvars;. The names of any variables in the input sources that are not configured in the &Variables; object are recorded and may be retrieved using the &UnknownVariables; method.

  If the optional `args` argument is provided, it is a dictionary of variables to use in place of the one saved when &Variables; was called.

  Normally, &Update; 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 in the `files` and/or `args` parameters when &Variables; was called, but the object was not actually configured for. This information is not available until the `Update` method has run.

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

`vars`.`Save`(`filename, env`)

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

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

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

- Return a formatted string with the help text collected from all the variables configured in this &Variables; object. This string is suitable for passing in to the &f-link-Help; function. The generated string include an indication of the actual value in the environment given by `env`.

  If the optional `sort` parameter is set to a callable value, 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 if equal, or a positive integer if greater-than. If `sort` is not callable, but is set to `True`, an alphabetical sort is performed. The default is `False` (unsorted).

      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 the single option `opt`. 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 describe custom variables, &SCons; provides some pre-defined variable types, acessible through factory functions that generate a tuple appropriate for directly passing to the &Add; or &AddVariables; method:

`BoolVariable`(`key, help, default`)

- Set up a Boolean variable. The variable will use the specified name `key`, have a default value of `default`, and `help` will form the descriptive part of the help text. The variable 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]`)

- Set up a variable whose value may only be from a specified list ("enumeration") of values. The variable will have the name `key`, have a default value of `default` and `help` will form the descriptive part of the help text. Any value that is not in `allowed_values` will raise an error, except that the optional `map` argument is a dictionary that can be used to map additional names into a particular name in the `allowed_values` list. If the value of optional `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, validator]`)

- Set up a variable whose value may be one or more from a specified list of values. The variable will have the name `key`, have a default value of `default`, and `help` will form the descriptive part of the help text. Any value that is not in `names` or the special values `all` or `none` will raise an error. More than one value may be specified, separated by commas. `default` may be specified either as a string of comma-separated value, or as a list of 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).

  The optional `validator` argument can be used to specify a custom validator callback function, as described for `Add`. The default is to use an internal validator routine.

  New in 4.8.0: `validator`.

`PackageVariable`(`key, help, default`)

- Set up a variable for a package, where if the variable is specified, the &consvar; named by `key` will end with a value of `True`, `False`, or a user-specified value. For example, a package could be a third-party software component, the build could use the information to exclude the package, include the package in the standard way, or include the package using a specified directory path to find the package files.

  The variable will have a default value `default`, and `help` will form the descriptive part of the help text. The variable supports (case-insensitive) truthy values `1`, `yes`, `true`, `on`, `enable` and `search` to indicate the package is "enabled", and the (case-insensitive) falsy values `0`, `no`, `false`, `off` and `disable` to indicate the package is "disabled".

  The value of the variable may also be set to an arbitrary string, which is taken to be the path name to the package that is being enabled. The validator will raise an exception if this path does not exist in the filesystem.

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

- Set up a variable whose value is expected to be a path name. The &consvar; named by `key` will have have a default value of `default`, and `help` will form the descriptive part of the help text.

  An optional `validator` argument may be specified. The validator 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 Nodes and Directory Nodes, respectively. Such 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 project top directory. 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 project top 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 project top 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 Filesystem 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. Use only to specify Scanner objects that find implicit dependencies based on the target file and &consenv;, not for implicit dependencies based on source files (use source_scanner for those). See scanner_objects for information about creating your own 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. Use to 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 scanner_objects 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 (that is, the default factory is &File;). 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:

      def my_mkdir(target, source, env):
          # target[0] will be a Dir node for 'new_directory'

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

  Note that the call to the `MakeDirectory` Builder needs to specify an empty source list to make the filename string represent the builder's target. &SCons; assumes a single positional argument to a builder 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 (that is, the default factory is &File;). 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:

      def collect(target, source, env):
          # target[0] will default to a File node for 'archive' (no target_factory)
          # source[0] will be a Dir node for 'directory_name'

      CollectBuilder = Builder(action=collect, source_factory=Dir)
      env = Environment()
      env.Append(BUILDERS={'Collect': CollectBuilder})
      env.Collect('archive', 'directory_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 project top directory, 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=True)
      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 project top directory, 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 &MSVC;. 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 and on WebAssembly platforms, 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 (including the `$` or `${ }`) 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 project top 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 function which can process ("scan") a given Node (usually a file) and return a list of Nodes representing any implicit dependencies (usually files) which will be tracked for the Node. 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. If the scanner-argument parameter was supplied when the Scanner object was created, it is passed as the `arg` parameter to the scanner function when it is called. Since `argument` is optional, the scanner function may be called without an `arg` parameter.

  The scanner function can make use of `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 scanner function should account for any directories listed in the `path` parameter when determining the existence of possible dependencies. External tools such as the C/C++ preprocessor are given lists of directories to search for source file inclusion directives (e.g. `#include "myheader.h"`). That list is generated from the relevant path variable (e.g. &cv-link-CPPPATH; for C/C++). The Scanner can be directed to pass the same list on to the scanner function via the `path` parameter so it can search in the same places. The Scanner is enabled to pass this list via the path_function argument at Scanner creation time.

  Instead of a scanner function, you can supply a dictionary as the `function` parameter. The dictionary must 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`.

  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.

  While many scanner functions operate on source code files by looking for known patterns in the code, they can really do anything they need to. For example, the &b-link-Program; Builder is assigned a target_scanner which examines the list of libraries supplied for the build (&cv-link-LIBS;) and decides whether to add them as dependencies, it does not look inside the built binary.

  It is up to the scanner function to decide whether or not to generate an &SCons; dependency for candidates identified by scanning. Dependencies are a key part of &SCons; operation, enabling both rebuild determination and correct ordering of builds. It is particularly important that generated files which are dependencies are added into the Node graph, or use-before-create failures are likely. However, not everything may need to be tracked as a dependency. In some cases, implementation-provided header files change infrequently but are included very widely, so tracking them in the &SCons; node graph could become quite expensive for limited benefit - consider for example the C standard header file `string.h`. The scanner function is not passed any special information to help make this choice, so the decision making encoded in the scanner function must be carefully considered.

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

- If specified, a function to generate paths to pass to the scanner function to search while generating dependencies. The function must take 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 (since `argument` is optional, the function may be called without this argument, the `path_function` should be prepared for this). Must return a tuple of directories that can be searched for files to be returned by this Scanner object.

  The &f-link-FindPathDirs; function can be called to return a ready-made `path_function` for a given &consvar; name, which is often easier than writing your own function from scratch. For example, `path_function=FindPathDirs('CPPPATH')` means the scanner function will be called with the paths extracted from &cv-CPPPATH; in the &consenv; `env`, and passed as the `path` parameter to the scanner function.

`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

Custom tools can be added to a project either by placing them in the `site_tools` subdirectory of a configured site directory, or in a location specified by the `toolpath` keyword argument to &f-link-Environment;. You have to arrange to call a tool to put it into effect, either as part of the list given to the `tools` keyword argument at &consenv; initialization, or by calling &f-link-env-Tool;.

The `toolpath` parameter takes a list of path strings, and the `tools` parameter takes a list of tools, which are often strings:

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

This looks for a tool specification module `foo` in directory `tools` and in the standard locations, as well as using the ordinary default tools for the platform.

When looking up tool specification modules, directories specified via `toolpath` are considered before the existing tool path (`site_tools` subdirectories of the default or specified site directories), which are in turn considered before 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 `toolpath` is saved in the environment and will be used by subsequent calls to the &f-link-env-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 is a form of &Python; module, looked up internally using the &Python; import mechanism, so a tool can consist either of a single &Python; 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. A tool specification module has two required entry points:

`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. Take care not to overwrite &consvars; which may have been explicitly set by the user; retain and/or append instead. For example:

      def generate(env):
          ...
          if 'MYTOOL' not in env:
              env['MYTOOL'] = env.Detect("mytool")
          flags = env.get('MYTOOLFLAGS', SCons.Util.CLVar())
          env.AppendUnique(MYTOOLFLAGS='--myarg')
          ...

  The `generate` function may use any keyword arguments that the user supplies via `kwargs` to vary its initialization.

`exists`(`env`)

- Return a truthy value if the tool can be called in the context of `env`, else return a falsy value. 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.

An element of the `tools` list may also be a function or other callable object (including a Tool object returned by a previous call to &f-link-Tool;) in which case the &f-link-Environment; function will directly call that object to update the new &consenv;. No tool lookup is done in this case.

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

    env = Environment(tools=[my_tool])

An element of the `tools` list may also be a two-element list or tuple of the form `(toolname, kw_dict)`. SCons searches for the a tool specification module `toolname` 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 those 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' or '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 &MSVC; (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 &MSVC; 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.