# SCons &buildversion;

MAN page

Steven Knight Steven Knight and the SCons Development Team

2004 - 2020

2004 - 2020 The SCons Foundation

version &buildversion;

## SCons &buildversion;

MAN page

SCONS

1 SCons __VERSION__ SCons __VERSION__

scons

a software construction tool

      scons
      options
      name=val
      targets

### DESCRIPTION

&scons; orchestrates the construction of software (and other tangible products such as documentation files) by determining which component pieces must be built or rebuilt and invoking the necessary commands to build them.

You instruct &scons; by writing a configuration file which specifies the files to be built (targets), and, if necessary, the rules to build those files. Premade rules exist for building many common software components such as executable programs, object files, libraries, so that for many software projects, only the target and input files need be specified.

When invoked, &scons; searches for a file named &SConstruct; (it also checks alternate spellings &Sconstruct;, &sconstruct;, &SConstruct.py; &Sconstruct.py; and &sconstruct.py; in that order) in the current directory and reads its configuration from that file. An alternate file name may be specified via the `-f` option. The &SConstruct; file can specify subsidiary configuration files by calling the &SConscriptFunc; function. 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 often 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.

Before reading the SConscript files, &scons; looks for a directory named `site_scons` in various system directories and in the directory containing the &SConstruct; file and prepends the ones it finds to the Python module search path (`sys.path`), thus allowing modules in such directories to be imported in the normal Python way in SConscript files. For each found site directory, if it contains a file `site_init.py` it is evaluated, and if it contains a directory `site_tools` the path to it 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.

&scons; configuration files are written in the Python programming language, although it is normally not necessary to be a Python programmer to use &scons; effectively. Standard Python scripting capabilities such as flow control, data manipulation, and imported Python libraries are available to use to handle complicated build situations.

&scons; reads and executes all of the SConscript files before it begins building any targets. To make this clear, &scons; prints the following messages about what it is doing:

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

The status messages (lines beginning with the `scons:` tag) may be suppressed using the `-Q` option.

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

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

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

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

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

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

This comes at the expense of making your build dependent on the user's environment being set correctly, but it may be more convenient for many configurations. It should not cause problems if done in a build setup which tightly controls how the environment is set up before invoking &scons;, as in many continuous integration setups.

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

&scons; is normally executed in a top-level directory containing an &SConstruct; file. When &scons; is invoked, the command line (including the contents of the &SCONSFLAGS; environment variable, if set) is processed. Command-line options (see options) are consumed. Any variable argument assignments are collected, and remaining arguments are taken as the targets to build.

Values of variables to be passed to the SConscript files may be specified on the command line:

    scons debug=1

These variables are available through the &ARGUMENTS; dictionary, and can be used in the SConscript files to modify the build in any way:

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

The command-line variable arguments are also available in the &ARGLIST; list, indexed by their order on the command line. This allows you to process them in order rather than by name, if necessary. Each &ARGLIST; entry is a tuple containing (`argname`, `argvalue`).

Targets on the command line may be files, directories, or phony targets defined using the &Alias; function. The command line targets are made available in the &COMMAND_LINE_TARGETS; list.

If no targets are specified on the command line, &scons; will build the default targets. The default targets are those specified in the SConscript files via calls to the &Default; function; if none, the default targets are those target files in or below the current directory. Targets specified via the &Default; function are available in the &DEFAULT_TARGETS; list.

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

    scons .

To build all target files, including any files outside of the current directory, supply a command-line target of the root directory (on POSIX systems):

    scons /

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

    scons C:\ D:\

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

    scons src/subdir

or by changing directory and invoking scons with the `-u` option, which traverses up the directory hierarchy until it finds the &SConstruct; file, and then builds targets relatively to the current subdirectory (see also the related `-D` and `-U` options):

    cd src/subdir
    scons -u .

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

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

    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 &Clean; function in the SConscript files. Conversely, targets that would normally be removed by the `-c` invocation can be retained by calling the &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.

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

By default, &scons; searches for known programming tools on various systems and initializes itself based on what is found. On Windows systems which identify as win32, &scons; searches in order for the Microsoft Visual C++ tools, the MinGW tool chain, the Intel compiler tools, and the PharLap ETS compiler. On Windows system which identify as cygwin (that is, if &scons; is invoked from a cygwin shell), the order changes to prefer the GCC toolchain over the MSVC tools. On OS/2 systems, &scons; searches in order for the OS/2 compiler, the GCC tool chain, and the Microsoft Visual C++ tools, On SGI IRIX, IBM AIX, Hewlett Packard HP-UX, and Oracle Solaris systems, &scons; searches for the native compiler tools (MIPSpro, Visual Age, aCC, and Forte tools respectively) and the GCC tool chain. On all other platforms, including POSIX (Linux and UNIX) platforms, &scons; searches in order for the GCC tool chain, and the Intel compiler tools. These default values may be overridden by appropriate setting of &consvars;.

&scons; requires Python 3.5 or higher. There should be no other dependencies or requirements to run &scons;, although the `pywin32` Python package is strongly recommended if running on Windows systems.

### OPTIONS

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

`-b`

- Ignored for compatibility with non-GNU versions of &Make;

`-c`, `--clean`, `--remove`

- Clean up by removing all target files for which a construction command is specified. Also remove any files or directories associated to the construction command using the &Clean; function. Will not remove any targets specified by the &NoClean; function.

-`-cache-debug=`file``

- 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 and retrieving a file from it, show the command that would have been executed to build the file. Without this option, &scons; reports `"Retrieved `file' 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 &Configure; call should use or generate the results of configuration tests. `mode`should be specified from among 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 option is specified, all configuration tests will be re-run regardless of whether the cached results are out of date. This can be used to explicitly force the configuration tests to be updated in response to an otherwise unconfigured change in a system header file or compiler.

cache

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

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

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

`-D`

- Works exactly the same way as the `-u` option except for the way default targets are handled. When this option is used and no targets are specified on the command line, all default targets are built, whether or not they are below the current directory.

`--debug=`type`[`,type`...]`

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

  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.

  Available since &scons; 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 variant file from its source file. Includes debugging info for unlinking stale variant files, as well as unlinking old targets before building them.

explain

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

findlibs

- Instruct the scanner that searches for libraries to print a message about each potential library name it is searching for, and about the actual libraries it finds.

includes

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

      $ scons --debug=includes foo.o

memoizer

- Prints a summary of hits and misses using the Memoizer, an internal subsystem that counts how often SCons uses cached values in memory instead of recomputing them each time they're needed.

memory

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

objects

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

pdb

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

prepare

- Print a line each time any target (internal or external) is prepared for building. &scons; prints this for each target it considers, even if that target is up to date (see also `--debug=explain`). This can help debug problems with targets that aren't being built; it shows whether &scons; is at least considering them or not.

presub

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

      $ scons --debug=presub
      Building myprog.o with action(s):
        $SHCC $SHCFLAGS $SHCCFLAGS $CPPFLAGS $_CPPINCFLAGS -c -o $TARGET $SOURCES
      ...

stacktrace

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

time

- Prints various time profiling information:

  - The time spent executing each individual build command

  - The total build time (time SCons ran from beginning to end)

  - The total time spent reading and executing SConscript files

  - The total time SCons itself spent running (that is, not counting reading and executing SConscript files)

  - The total time spent executing all build commands

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

  - The time spent processing each file passed to the &SConscriptFunc; function

  (When &scons; is executed without the `-j` option, the elapsed wall-clock time will typically be slightly longer than the total time spent executing all the build commands, due to the SCons processing that takes place in between executing each command. When &scons; is executed with the `-j` option, and your build configuration allows good parallelization, the elapsed wall-clock time should be significantly smaller than the total time spent executing all the build commands, since multiple build commands and intervening SCons processing should take place in parallel.)

`--diskcheck=`type`[`,type`...]`

- Enable specific checks for whether or not there is a file on disk where the SCons configuration expects a directory (or vice versa), and whether or not RCS or SCCS sources exist when searching for source and include files. The `type` argument can be set to:

  all

- Enable all checks explicitly (the default behavior).

none

- Disable all such checks.

match

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

rcs

- Check for the existence of an RCS source for any missing source or include files.

sccs

- Check for the existence of an SCCS source for any missing source or include files.

Multiple checks can be specified separated by commas. for example, `--diskcheck=sccs,rcs` would still check for SCCS and RCS sources, but disable the check for on-disk matches of files and directories. Disabling some or all of these checks can provide a performance boost for large configurations, or when the configuration will check for files and/or directories across networked or shared file systems, at the slight increased risk of an incorrect build or of not handling errors gracefully (if include files really should be found in SCCS or RCS, for example, or if a file really does exist where the SCons configuration expects a directory).

`--duplicate=`ORDER``

- There are three ways to duplicate files in a build tree: hard links, soft (symbolic) links and copies. The default behaviour of SCons is to prefer hard links to soft links to copies. You can specify different behaviours with this option. `ORDER` must be one of hard-soft-copy (the default), soft-hard-copy, hard-copy, soft-copy or copy. SCons will attempt to duplicate files using the mechanisms in the specified order.

`--enable-virtualenv`

- Import virtualenv-related variables to SCons.

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

`-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. `CPPPATH`, `LIBPATH`) that would ordinarily cause different versions of same-named files to be used.

  &scons; will miss changes in the implicit dependencies in cases where a new implicit dependency is added earlier in the implicit dependency search path (e.g. `CPPPATH`, `LIBPATH`) than a current implicit dependency with the same name.

`--implicit-deps-changed`

- Forces SCons to ignore the cached implicit dependencies. This causes the implicit dependencies to be rescanned and recached. This implies `--implicit-cache`.

`--implicit-deps-unchanged`

- Force SCons to ignore changes in the implicit dependencies. This causes cached implicit dependencies to always be used. This implies `--implicit-cache`.

`--install-sandbox=`path``

- When using the &Install; functions, prepend `path` to the installation paths such that all installed files will be placed underneath `path`.

`--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 content signature will be used instead of calculating a new content signature (MD5 checksum) of the file's contents. The default value is 2 days, which means a file must have a modification time of at least two days ago in order to have its cached content signature used. A negative value means to never cache the content signature and to ignore the cached value if there already is one. A value of 0 means to always use the cached signature, no matter how old the file is.

`--md5-chunksize=`KILOBYTES``

- Set the block size used to compute MD5 signatures to `KILOBYTES`. This value determines the size of the chunks which are read in at once when computing MD5 signatures. Files below that size are fully stored in memory before performing the signature computation while bigger files are read in block-by-block. A huge block-size leads to high memory consumption while a very small block-size slows down the build considerably.

  The default value is to use a chunk size of 64 kilobytes, which should be appropriate for most uses.

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

- No execute. Print the commands that would be executed to build any out-of-date target files, but do not execute the commands.

`--no-site-dir`

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

`--profile=`file``

- Run SCons under the Python profiler and save the results in the specified `file`. The results may be analyzed using the Python pstats module.

`-q`, `--question`

- Do not run any commands, or print anything. Just return an exit status that is zero if the specified targets are already up to date, non-zero otherwise.

`-Q`

- Quiets SCons status messages about reading SConscript files, building targets and entering directories. Commands that are executed to rebuild target files are still printed.

`--random`

- Build dependencies in a random order. This is useful when building multiple trees simultaneously with caching enabled, to prevent multiple builds from simultaneously trying to build or retrieve the same target files.

`-s`, `--silent`, `--quiet`

- Silent. Do not print commands that are executed to rebuild target files. Also suppresses SCons status messages.

`-S`, `--no-keep-going`, `--stop`

- Ignored for compatibility with GNU &Make;

`--site-dir=`dir``

- Uses the named `dir` as the site directory rather than the default site_scons directories. This directory will be prepended to `sys.path`, the module ``dir`/site_init.py` will be loaded if it exists, and ``dir`/site_tools` will be added to the default toolpath.

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

  Windows:

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

Mac OS X:

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

Solaris:

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

Linux, HPUX, and other Posix-like systems:

-     /usr/share/scons/site_scons
      $HOME/.scons/site_scons
      ./site_scons

`--stack-size=`KILOBYTES``

- Set the size stack used to run threads to `KILOBYTES`. This value determines the stack size of the threads used to run jobs. These 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.

  Available since &scons; 4.0.

status

- Prints status information for each displayed node.

prune

- Prunes the tree to avoid repeating dependency information for nodes that have already been displayed. Any node that has already been displayed will have its name printed in [square brackets], as an indication that the dependencies for that node can be found by searching for the relevant output higher up in the tree.

Multiple `type` choices may be specified, separated by commas:

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

    # Prints all dependencies of target, with status information
    # and pruning dependencies of already-visited Nodes:
    scons --tree=all,prune,status target

`-u`, `--up`, `--search-up`

- Walks up the directory structure until an &SConstruct;, &Sconstruct;, &sconstruct;, &SConstruct.py;, &Sconstruct.py; or &sconstruct.py; file is found, and uses that as the top of the directory tree. If no targets are specified on the command line, only targets at or below the current directory will be built.

`-U`

- Works exactly the same way as the `-u` option except for the way default targets are handled. When this option is used and no targets are specified on the command line, all default targets that are defined in the SConscript(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 no- prefix) warnings. `type` specifies the type of warnings to be enabled or disabled:

  all

- All warnings.

cache-version

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

cache-write-error

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

corrupt-sconsign

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

dependency

- Warnings about dependencies. These warnings are disabled by default.

deprecated

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

duplicate-environment

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

fortran-cxx-mix

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

future-deprecated

- Warnings about features that will be deprecated in the future. Such warnings are disabled by default. Enabling future deprecation warnings is recommended for projects that redistribute SCons configurations for other users to build, so that the project can be warned as soon as possible about to-be-deprecated features that may require changes to the configuration.

link

- Warnings about link steps.

misleading-keywords

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

missing-sconscript

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

no-object-count

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

no-parallel-support

- Warnings about the version of Python not being able to support parallel builds when the `-j` option is used. These warnings are enabled by default.

python-version

- Warnings about running SCons with a deprecated version of Python. These warnings are enabled by default.

reserved-variable

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

stack-size

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

target_not_build

- Warnings about a build rule not building the expected targets. These warnings are disabled by default.

`-Y `repository``, `--repository=`repository``, `--srcdir=`repository``

- Search the specified `repository` for any input and target files not found in the local directory hierarchy. Multiple `-Y` options may be specified, in which case the repositories are searched in the order specified.

### CONFIGURATION FILE REFERENCE

#### Construction Environments

A &ConsEnv; is the basic means by which SConscript files 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:

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

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-Environment;, and uses the arguments to create a modified copy.

&SCons; also 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.

As a convenience, &consvars; may also be set or modified by the `parse_flags` keyword argument, which applies the &f-link-env-MergeFlags; method (described below) to the argument value after all other processing is completed. This is useful either if the exact content of the flags is unknown (for example, read from a control file) or if the flags need to be distributed to a number of &consvars;.

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

This example adds 'include' to the `CPPPATH` &consvar; 'EBUG' to `CPPDEFINES`, and 'm' to `LIBS`. &f-link-env-ParseFlags; describes how these arguments are distributed to &consvars;.

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

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

Specifying a platform initializes the appropriate &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 (such as fetching source files from external CVS repository specifications like `:pserver:anonymous@cvs.sourceforge.net:/cvsroot/scons`) will work on Windows systems.

The `platform` argument may be a function or callable object, 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)

#### Tools

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

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

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

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

The `tools` argument overrides the default tool list, it does not add to it, so be sure to include all the tools you need. For example if you are building a c/c++ program you must specify a tool for at least a compiler and a linker, as in `tools=['clang', 'link']`. The tool name `'default'` can be used to retain the default list.

If no `tools` list is specified, or the list includes `'default'`, then &scons; will detect usable tools, using the value of `PATH` in the `ENV` &consvar; (not the external `PATH` from `os.environ`) for looking up any backing programs, and the platform name in effect to determine the default tools for that platform. Changing the `PATH` variable after the &consenv; is constructed will not cause the tools to be redetected.

To help locate added tools, specify the `toolpath` keyword argument:

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

This looks for a tool specification in `tools/foo.py` as well as using the ordinary default tools for the platform.

Tools in the toolpath are used in preference to any of the built-in ones. For example, adding a tool `gcc.py` to the toolpath directory would override the built-in gcc tool. The toolpath is stored in the environment and will be picked up by subsequent calls to the &f-Clone; and &f-Tool; methods:

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

A tool specification must include two functions:

`generate`(`env, **kwargs`)

- Modifies the environment referenced by `env` to set up variables so that the facilities represented by the tool can be executed. It may use any keyword arguments that the user supplies in `kwargs` to vary its initialization.

`exists`(`env`)

- Return `True` if the tool can be called. 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.

The elements of the `tools` list may also be functions or callable objects, in which case the &Environment; method will call those objects to update the new &consenv; (see &f-link-Tool; for more details):

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

    env = Environment(tools=[my_tool])

The individual elements of the `tools` list may also themselves be lists or tuples of the form (`toolname`, `kw_dict`). SCons searches for the `toolname` specification file as described above, and passes `kw_dict`, which must be a dictionary, as keyword arguments to the tool's `generate` function. The `generate` function can use the arguments to modify the tool's behavior by setting up the environment in different ways or otherwise changing its initialization.

    # in tools/my_tool.py:
    def generate(env, **kwargs):
      # Sets MY_TOOL to the value of keyword 'arg1' '1' if not supplied
      env['MY_TOOL'] = kwargs.get('arg1', '1')

    def exists(env):
      return True

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

The tool definition (`my_tool` in the example) can use the `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, 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

SCons supports the following tool specifications out of the box:

#### Builder Methods

You tell &scons; what to build by calling Builders, functions which know to take a particular action to produce a particular result type when given source files of a particular type. &scons; defines a number of builders, and you can also write your own. Builders are attached to a &consenv; as methods, and the available builder methods are listed as key-value pairs in the `BUILDERS` attribute of the &consenv;. The available builders can be displayed like this for debugging purposes:

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

Builder methods always take two arguments: `target` (a target or a list of targets to be built) and `source` (a source or list of sources to be used as input when building), although in some circumstances, the target argument can actually 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, &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 target and source arguments to a builder method can be specified either as positional arguments, in which case the target comes first, or as keyword arguments, using `target=` and `source=`. 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())

Python follows the POSIX pathname convention for path strings: if a string begins with the operating system pathname separator (on Windows both the slash and backslash separator work, 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.

&scons; recognizes a third way to specify path strings: if the string begins with the # character it is top-relative - it works like a relative path but the search follows down from the directory containing the top-level &SConstruct; rather than from the current directory. The # is allowed to 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.

Target and source pathnames can be absolute, relative, or top-relative. Relative pathnames are searched considering the directory of the SConscript file currently being processed as the "current directory".

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

As a convenience, a `srcdir` keyword argument may be specified when calling a Builder. When specified, all source file strings that are not absolute paths or top-relative paths will 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')

It is possible to override (replace or add) &consvars; when calling a builder method by passing them as keyword arguments. These overrides will only be in effect when building that target, 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('word', 'word.cpp',
                      SHLIBSUFFIX='.ocx',
                      LIBSUFFIXES=['.ocx'])

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

It is also possible to use the `parse_flags` keyword argument in an override, to merge command-line style arguments into the appropriate &consvars; (see &f-link-env-MergeFlags;).

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

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

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

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

In this case, the methods are called internally using a default construction environment 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 may be called from custom Python modules that you import into an SConscript file by adding the following to the Python module:

    from SCons.Script import *

All builder methods return a list-like object containing Nodes that will be built. A Node is an internal SCons object which represents build targets or sources.

The returned Node-list object can be passed to other builder methods as source(s) or passed to any &SCons; function or method where a filename would normally be accepted. For example, if it were necessary to add a specific preprocessor define when compiling one specific object file:

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

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

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 &StaticObject; call above. 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))

&SCons; builder calls return a list-like object, not an actual Python list, so 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 Node-list 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 again that because the Builder call returns a list, we have to access the first element in the list (`(bar_obj_list[0])`) to get at the Node that actually represents the object file.

Builder calls support a `chdir` keyword argument that specifies that the Builder's action(s) should be executed after changing directory. If the `chdir` argument is a string or a directory Node, scons will change to the specified directory. If the `chdir` is not a string or Node and is non-zero, then scons will change to the target file's directory.

    # scons will change to the "sub" subdirectory
    # before executing the "cp" command.
    env.Command('sub/dir/foo.out', 'sub/dir/foo.in',
                "cp dir/foo.in dir/foo.out",
                chdir='sub')

    # Because chdir is not a string, scons will change to the
    # target's directory ("sub/dir") before executing the
    # "cp" command.
    env.Command('sub/dir/foo.out', 'sub/dir/foo.in',
                "cp foo.in foo.out",
                chdir=1)

Note that &SCons; will not automatically modify its expansion of &consvars; like `$TARGET` and `$SOURCE` when using the `chdir` keyword argument--that is, the expanded file names will still be relative to the top-level directory where &SConstruct; was found, and consequently incorrect relative to the chdir directory. If you use the `chdir` keyword argument, you will typically need to supply a different command line using expansions like `${TARGET.file}` and `${SOURCE.file}` to use just the filename portion of the targets and source.

&scons; predefines the following builder methods. 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 to that &consenv;.

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.

#### Methods and Functions To Do Things

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

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

    Function(arguments, [optional arguments])

and the &consenv; method looks like:

    env.Function(arguments, [optional arguments])

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

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

    Default('$FOO')

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

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

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

    from SCons.Script import *

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

#### SConscript Variables

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

&ARGLIST;

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

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

&ARGUMENTS;

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

  Example:

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

&BUILD_TARGETS;

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

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

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

  Example:

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

&COMMAND_LINE_TARGETS;

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

  Example:

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

&DEFAULT_TARGETS;

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

  Example:

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

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

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

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

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

    from SCons.Script import *

#### Construction Variables

A &consenv; has an associated dictionary of &consvars; that are used by built-in or user-supplied build rules. &Consvar; naming must follow the same rules as for Python identifiers: the initial character must be an underscore or letter, followed by any number of underscores, letters, or digits.

A &consenv; is not a Python dictionary, but it can be indexed like one to access a &consvar;:

    env["CC"] = "cc"

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

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

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

    env = Environment(CC="cc")

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

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

A number of useful &consvars; are automatically defined by scons for each supported platform, and additional &consvars; can be defined by the user. The following is a list of the possible automatically defined &consvars;. The actual list available at execution time will not include all of these, as the ones detected as not being useful (wrong platform, necessary external command or files not installed, etc.) will not be set up. :

#### 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 (since 4.0, &scons; will raise an exception on an attempt to create a new context when there is an active context), 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.

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

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

  `log_file` specifies a file which collects the output from commands that are executed to check for the existence of header files, libraries, etc. The default is `#/config.log`. If you are using the &VariantDir; function, you may want to specify a subdirectory under your 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.

`SConf`.`Finish`(`context`)

`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(CPPFLAGS="-DWITH_QT")
    env = conf.Finish()

A &configure_context; has the following predefined methods which can be used to perform checks. Where `language` is a required or optional parameter, the choice can currently be C or C++. The spellings accepted for C are C or c; for C++ the value can be CXX, cxx, C++ or c++.

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

`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). The optional argument `language` should be either C or C++ and selects the compiler to be used for the check. Returns a boolean indicating success or failure.

`SConf`.`CheckCHeader`(`context, header, [include_quotes]`)

`context`.`CheckCHeader`(`header, [include_quotes]`)

- This is a wrapper around `SConf.CheckHeader` which checks if `header` is usable in the C 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.

`SConf`.`CheckCXXHeader`(`context, header, [include_quotes]`)

`context`.`CheckCXXHeader`(`header, [include_quotes]`)

- This is a wrapper around `SConf.CheckHeader` which checks if `header` is usable in the C++ 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.

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

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

- Checks if the specified C or C++ library function is available based on the context's local environment settings (that is, using the values of `CFLAGS`, `CPPFLAGS`, `LIBS` or other relevant &consvars;).

  `function_name` is the name of the function to check for. The optional `header` argument is a string that will be placed at the top of the test file that will be compiled to check if the function exists; the default is:

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

  Returns an empty string on success, a string containing an error message on failure.

`SConf`.`CheckLib`(`context, [library, symbol, header, language, autoadd=True]`)

`context`.`CheckLib`(`[library, symbol, header, language, autoadd=True]`)

- Checks if `library` provides `symbol`. If `autoadd` is true (the default) and the library provides the specified `symbol`, appends the library to the `LIBS` &consvar; `library` may also be `None` (the default), in which case `symbol` is checked with the current `LIBS` variable, or a list of library names, in which case each library in the list will be checked for `symbol`. If `symbol` is not set or is `None`, then `SConf.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`. Returns a boolean indicating success or failure.

`SConf`.`CheckLibWithHeader`(`context, library, header, language, [call, autoadd=True]`)

`context`.`CheckLibWithHeader`(`library, header, language, [call, autoadd=True]`)

- Provides a more sophisticated way to check against libraries then the `SConf.CheckLib` call. `library` specifies the library or a list of libraries to check. `header` specifies a header to check for. `header` may be a list, in which case the last item in the list is the header file to be checked, and the previous list items are header files whose `#include` lines should precede the header line being checked for. `call` can be any valid expression (with a trailing ';'). If `call` is not set, the default simply checks that you can link against the specified `library`. `autoadd` (default true) specifies whether to add the library to the environment if the check succeeds. Returns a boolean indicating success or failure.

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

`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 an empty string on success, a string containing an error message on failure.

`SConf`.`CheckCC`(`context`)

`context`.`CheckCC`()

- Checks whether the C compiler (as defined by the `CC` &consvar;) works by trying to compile a small source file. Returns a boolean indicating success or failure.

  By default, SCons only detects if there is a program with the correct name, not if it is a functioning compiler.

  This uses the exact same command as the one used by the object builder for C source files, so it can be used to detect if a particular compiler flag works or not.

`SConf`.`CheckCXX`(`context`)

`context`.`CheckCXX`()

- Checks whether the C++ compiler (as defined by the `CXX` &consvar;) works by trying to compile a small source file. By default, SCons only detects if there is a program with the correct name, not if it is a functioning compiler. Returns a boolean indicating success or failure.

  This uses the exact same command as the one used by the object builder for C++ source files, so it can be used to detect if a particular compiler flag works or not.

`SConf`.`CheckSHCC`(`context`)

`context`.`CheckSHCC`()

- Checks whether the shared-object C compiler (as defined by the `SHCC` &consvar;) works by trying to compile a small source file. By default, SCons only detects if there is a program with the correct name, not if it is a functioning compiler. Returns a boolean indicating success or failure.

  This uses the exact same command as the one used by the object builder for C source file, so it can be used to detect if a particular compiler flag works or not. This does not check whether the object code can be used to build a shared library, only that the compilation (not link) succeeds.

`SConf`.`CheckSHCXX`(`context`)

`context`.`CheckSHCXX`()

- Checks whether the shared-object C++ compiler (as defined by the `SHCXX` &consvar;) works by trying to compile a small source file. By default, SCons only detects if there is a program with the correct name, not if it is a functioning compiler. Returns a boolean indicating success or failure.

  This uses the exact same command as the one used by the object builder for C++ source files, so it can be used to detect if a particular compiler flag works or not. This does not check whether the object code can be used to build a shared library, only that the compilation (not link) succeeds.

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

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

  For example,

      CheckTypeSize('short', expect=2)

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

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

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

`SConf`.`Define`(`context, symbol, [value, comment]`)

`context`.`Define`(`symbol, [value, comment]`)

- This function does not check for anything, but defines a preprocessor symbol that will be added to the configuration header file. It is the equivalent of `AC_DEFINE`, and defines the symbol `name` with the optional `value` and the optional comment `comment`.

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

  Be careful about quoting string values, though:

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

  For 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 the predefined checks. You pass a dictionary of these to the &Configure; function as the `custom_tests` argument. This dictionary maps the names of the checks to the user defined Python callables (either Python functions or class instances implementing a `__call__` method). Each custom check will be called with a first argument of a CheckContext, instance followed by the arguments, which must be supplied by the user of the check. A CheckContext instance defines the following methods:

`context`.`Message`(`text`)

- Displays a message, as an indicator of progess. `text` will be displayed, e.g. `Checking for library X...`. Usually called before the check is started.

`context`.`Result`(`res`)

- Displays a result message, as an indicator of progress. `res` can be either an integer or a string. If an integer, displays `yes` (if `res` evaluates `True`) or `no` (if `res` evaluates `False`). If a string, it is displayed as-is. Usually called after the check has completed.

`context`.`TryCompile`(`text, extension=''`)

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

`context`.`TryLink`(`text, extension=''`)

- Checks, if a file with the specified `extension` (e.g. '.c') containing `text` can be compiled using the environment's &Program; builder. Returns a boolean indicating success or failure.

`context`.`TryRun`(`text, extension=''`)

- Checks if a file with the specified `extension` (e.g. '.c') containing `text` can be compiled using the environment's &Program; builder. On success, the program is run. If the program executes successfully (that is, its return status is 0), a tuple (1, outputStr) is returned, where `outputStr` is the standard output of the program. If the program fails execution (its return status is non-zero), then (0, '') is returned.

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

- Checks if the specified `action` with an optional source file (contents `text`, extension `extension`) can be executed. `action` may be anything which can be converted to a &scons; Action. On success, (1, outputStr) is returned, where `outputStr` is the content of the target file. On failure (0, '') is returned.

`context`.`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, `context.lastTarget` is set to the build target node if the build was successful.

Example of implementing and using custom tests:

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

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

#### Command-Line Construction Variables

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

    scons VARIABLE=foo

The variable values can also be specified in an SConscript file.

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

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

- If `files` is a file or list of files, those are executed as Python scripts, and the values of (global) Python variables set in those files are added as &consvars; in the &DefEnv;. If no files are specified, or the `files` argument is `None`, then no files will be read. The following example file contents could be used to set an alternative C compiler:

      CC = 'my_cc'

  If `args` is specified, it is a dictionary of values that will override anything read from `files`. it is primarily intended to be passed the &ARGUMENTS; dictionary that holds variables specified on the command line. Example:

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

Variables objects have the following methods:

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

- Add a customizable &consvar; to the Variables object. `key` is the name of the variable. `help` is the help text for the variable. `default` is the default value of the variable; if the default value is `None` and there is no explicit value specified, the &consvar; will not be added to the &consenv;. If set, `validator` is called to validate the value of the variable. A function supplied as a validator shall accept arguments: `key`, `value`, and `env`. The recommended way to handle an invalid value is to raise an exception (see example below). If set, `converter` is called to convert the value before putting it in the environment, and should take either a value, or the value and environment, as parameters. The converter function must return a value, which will be converted into a string before being validated by the `validator` (if any) and then added to the &consenv;.

  Examples:

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

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

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

`vars`.`AddVariables`(`args`)

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

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

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

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

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

      env = Environment(variables=vars)

`vars`.`UnknownVariables`()

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

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

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

- Save the currently set variables into a script file named by `filename` that can be used on the next invocation to automatically load the current settings. This method combined with the Variables method can be used to support caching of variables between runs.

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

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

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

      Help(vars.GenerateHelpText(env))

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

  `PathVariable`.`PathExists`

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

`PathVariable`.`PathIsFile`

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

`PathVariable`.`PathIsDir`

- Verify that the specified path exists and is a directory.

`PathVariable`.`PathIsDirCreate`

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

`PathVariable`.`PathAccept`

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

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

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

    vars.AddVariables(
        BoolVariable(
            "warnings",
            help="compilation with -Wall and similar",
            default=1,
        ),
        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,
        ),
    )

#### File and Directory Nodes

The &f-link-File; and &f-link-Dir; functions/methods return File and Directory Nodes, respectively. Such nodes are Python objects with several user-visible attributes and methods that are often useful to access in SConscript files:

`n`.`path`

- The build path of the given file or directory. This path is relative to the top-level directory (where the &SConstruct; file is found). The build path is the same as the source path if variant_dir is not being used.

`n`.`abspath`

- The absolute build path of the given file or directory.

`n`.`srcnode`()

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

For example:

    # Get the current build dir's path, relative to top.
    Dir('.').path
    # Current dir's absolute path
    Dir('.').abspath
    # Next line is always '.', because it is the top dir's path relative to itself.
    Dir('#.').path
    File('foo.c').srcnode().path   # source path of the given source file.

    # Builders also return File objects:
    foo = env.Program('foo.c')
    print("foo will be built in", foo.path)

File and Directory Node objects have methods to create File and Directory Nodes relative to the original Node.

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

`d`.`Dir`(`name`)

- Returns a directory Node for a subdirectory of `d` named `name`.

`d`.`File`(`name`)

- Returns a file Node for a file within `d` named `name`.

`d`.`Entry`(`name`)

- Returns an unresolved Node within `d` named `name`.

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

`f`.`Dir`(`name`)

- Returns a directory named `name` within the parent directory of `f`.

`f`.`File`(`name`)

- Returns a file named `name` within the parent directory of `f`.

`f`.`Entry`(`name`)

- Returns an unresolved Node named `name` within the parent directory of `f`.

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

### EXTENDING SCONS

#### 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. If you just want to invoke a different compiler or other tool to build &Program;, &Object;, &Library;, or any other type of output file for which &scons; already has an existing Builder, it is generally much easier to use those existing Builders in a &consenv; that sets the appropriate &consvars; (`CC`, `LINK`, etc.).

Builder objects are created using the &f-link-Builder; factory function. The &f-Builder; function accepts the following keyword arguments:

`action`

- The command line string used to build the target from the source. `action` can also be: a list of strings representing the command to be executed and 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 the next section); or a list of any of the above.

  An action function takes three arguments:

  - `source` - a list of source nodes;.
  - `target` - a list of target nodes;.
  - `env` - the &consenv;.

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

`prefix`

- The prefix that will be prepended to the target file name. `prefix` may be:

  - a string

  - a callable object - a function or other callable that takes two arguments (a &consenv; and a list of sources) and returns a prefix

  - a dictionary - specifies a mapping from a specific source suffix (of the first source specified) to a corresponding target prefix. Both the source suffix and target prefix specifications may use environment variable substitution, and the target prefix (the 'value' entries in the dictionary) may also be a callable object. The default target prefix may be indicated by a dictionary entry with a key value 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 that will be appended to the target file name. This may be specified in the same manner as the prefix above. If the suffix is a string, then &scons; will append a '.' to the beginning of the suffix if it's not already there. The string returned by callable object (or obtained from the dictionary) is untouched and must append its own '.' to the beginning if one is desired.

      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`

- When set to any true value, causes &scons; to add the target suffix specified by the `suffix` keyword to any target strings that have a different suffix. (The default behavior is to leave untouched any target file name that looks like it already has any suffix.)

      b1 = Builder("build_it < $SOURCE > $TARGET"
                   suffix = ".out")
      b2 = Builder("build_it < $SOURCE > $TARGET"
                   suffix = ".out",
                   ensure_suffix)
      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. This may be a string or a list of strings.

`target_scanner`

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

`source_scanner`

- A Scanner object that will be invoked to find implicit dependencies in any source files used to build this target file. This is where you would specify a scanner to find things like `#include` lines in source files. The pre-built `DirScanner` Scanner object may be used to indicate that this Builder should scan directory trees for on-disk changes to files that &scons; does not know about from other Builder or function calls. See 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. Other useful target_factory values include Dir, for when a Builder creates a directory target, and Entry, for when a Builder can create either a file or directory target.

  Example:

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

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

`source_factory`

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

  Example:

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

`emitter`

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

  An emitter function takes three arguments:

  - `source` - a list of source nodes.
  - `target` - a list of target nodes.
  - `env` - the &consenv;.

  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 &consvar;.
      env = Environment(MY_EMITTER=e)
      b = Builder("my_build < $TARGET > $SOURCE",
                  emitter='$MY_EMITTER')

      # Calling a list of emitter functions through a &consvar;.
      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("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 `0`, 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).

  The generator function takes four arguments:

  - `source` - A list of source nodes;.
  - `target` - A list of target nodes;.
  - `env` - the &consenv;.
  - `for_signature` - A Boolean value that specifies whether the generator is being called for generating a build signature (as opposed to actually executing the command).

  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 `None` or some other non-true value. When `source_ext_match` is disable, &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 = None)

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

`env`

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

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

`chdir`

- A directory from which scons will execute the action(s) specified for this Builder. If the `chdir` argument is a string or a directory Node, scons will change to the specified directory. If the `chdir` is not a string or Node and is non-zero, then scons will change to the target file's directory.

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

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

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

Any additional keyword arguments supplied when a Builder object is created (that is, when the &f-link-Builder; function is called) will be set in the executing construction environment when the Builder object is called. The canonical example here would be to set a &consvar; to the repository of a source code system.

Any additional 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; function will turn its `action` keyword argument into an appropriate internal Action object. 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 can be used to configure an Action object more flexibly, or it may simply be more efficient than letting each separate Builder object create a separate Action when multiple Builder objects need to do the same thing.

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

- If the action argument is already an Action object, the object is simply returned.

- If the action argument is a string, a command-line Action is returned. If such a string begins with @, it indicates printing of the command line is to be suppressed. If the string begins with - (hyphen), it indicates the exit status from the specified command is to be 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 the action argument 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 internal 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 the action argument is a Python function, a function Action is returned. The Python function must accept three keyword arguments:

  - `target` - a Node object representing the target file.
  - `source` - a Node object representing the source file.
  - `env` - 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 the action argument is not one of the above types, `None` is returned.

As usual the environment method form &f-link-env-Action; will expand &consvars; in any argument strings, including the action argument, 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 second argument to &f-Action; is optional and is used to define the output which is printed when the Action is actually performed. In the absence of this parameter, or if it's 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 argument must be either a Python function or a string:

- If the output argument is a function, it must return a string describing the action being executed. A function may also be specified using the `strfunction` keyword argument. The function must accept these three keyword arguments:

  - `source` - a Node object representing the source file.
  - `target` - a Node object representing the target file.
  - `env` - the &consenv;.

  The `target` and `source` arguments may be lists of Node objects if there is more than one target file or source file.

- If the output argument is a string, substitution is performed on it before it is printed. The output string may also be specified using the `cmdstr` keyword argument. The string typically contains 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.

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

- Specifies that scons will execute the action after changing to the specified directory. If the `chdir` argument is a string or a directory Node, scons will change to the specified directory. If the `chdir` argument 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 &cv-TARGET; and &cv-SOURCE; when using the `chdir` keyword argument--that is, the expanded file names will still be relative to the top-level directory containing the &SConstruct; file, and consequently incorrect relative to the chdir directory. Builders created using `chdir` keyword argument, will need to use &consvar; expansions like `${TARGET.file}` and `${SOURCE.file}` to use just the filename portion of the targets and source. Example:

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

`exitstatfunc`

- A function that is passed the exit status (or return value) from the specified action and can return 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`

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

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

  The `batch_key` argument may also be a callable function that returns a key that will be used to identify different "batches" of target files to be collected for batch building. A `batch_key` function must accept the following arguments:

  - `action` - The action object.
  - `env` - The &consenv; configured for the target.
  - `target` - The list of targets for a particular configured action.
  - `source` - The list of source for a particular 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 construction variable from the `env` argument which will cause &scons; to batch-build targets with matching values of that variable, 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 a number of 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.

In practice, 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 to do so:

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

`Copy`(`dest, src`)

- Returns an Action object that will copy the `src` source file or directory to the `dest` destination file or directory. 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`(`dir`)

- Returns an Action that creates the specified directory `dir`. 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 &consvar; substitution on the string that makes up the command line of the builder. &Consvars; to be interpolated are indicated in the string with a leading `$`, to distinguish them from plain text which is not to be substituted. Besides regular &consvars;, scons provides the following special variables for each command execution:

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

Note that the above variables are reserved and may not be assigned to in the &consenv;.

For example, given the &consvars; `CC='cc'`, `targets=['foo']` and `sources=['foo.c', 'bar.c']`:

    action='$CC -c -o $TARGET $SOURCES'

would produce the command line:

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

Variable names may be surrounded by curly braces ({}) to separate the name from surrounding characters which are not part of the name. Within the curly braces, a variable name may use Python list subscripting/slicing notation to select one or more items from a list. In the previous example, the string: `${SOURCES[1]}` would produce:

    bar.c

Additionally, a variable name may have the following modifiers appended within the enclosing curly braces to access properties of the interpolated string:

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

    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

Modifiers can be combined, like `${TARGET.base.windows}`, `${TARGET.srcpath.base)`, `${TARGET.file.suffix}`, etc.

Note that curly braces braces may also be used to enclose arbitrary Python code to be evaluated. (In fact, this is how the above modifiers are substituted, they are simply attributes of the Python objects that represent &cv-TARGET;, &cv-SOURCES;, etc.) See python_code_substitution below for more thorough examples of how this can be used.

Lastly, a variable name may be a callable Python function associated with a &consvar; in the environment. The function should accept four arguments:

- `target` - a list of target nodes
- `source` - a list of source nodes
- `env` - the &consenv;
- `for_signature` - a Boolean value that specifies whether the function is being called for generating a build signature.

SCons will insert whatever the called function returns into the expanded string:

    def foo(target, source, env, for_signature):
        return "bar"

    # Will expand $BAR to "bar baz"
    env=Environment(FOO=foo, BAR="$FOO baz")

You can use this feature to pass arguments to a Python function by creating a callable class that stores one or more arguments in an object, and then uses them when the `__call__()` method is called. Note that in this case, the entire variable expansion must be enclosed by curly braces so that the arguments will be associated with the instantiation of the class:

    class foo:
        def __init__(self, arg):
            self.arg = arg

        def __call__(self, target, source, env, for_signature):
            return self.arg + " bar"

    # Will expand $BAR to "my argument bar baz"
    env=Environment(FOO=foo, BAR="${FOO('my argument')} baz")

The special pseudo-variables $( and $) may be used to surround parts of a command line that may change without causing a rebuild--that is, which are not included in the signature of target files built with this command. All text between $( and $) will be removed from the command line before it is added to file signatures, and the $( and $) will be removed before the command is executed. For example, the command line:

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

would execute the command:

    echo Last build occurred $TODAY. > $TARGET

but the command signature added to any target files would be:

    echo Last build occurred  . > $TARGET

#### Python Code Substitution

Any Python code within curly braces ({}) and introduced by the variable prefix `$` will be evaluated using the Python `eval` statement, with the Python globals set to the current environment's set of &consvars;, and the result substituted in. So in the following case:

    env['COND'] = 0
    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 interesting 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'] = 0
    env['FOO'] = ['foo1', 'foo2']
    env['BAR'] = 'barbar'
    env.Command('foo.out', 'foo.in',
        'echo ${COND==1 and FOO or BAR} > $TARGET')

    # Will execute this:
    #  echo foo1 foo2 > foo.out

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

string

- When the value is a string it is interpreted as a space delimited list of command line arguments.

list

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

other

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

newline

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

#### Scanner Objects

You can use the &f-link-Scanner; function to define objects to scan new file types for implicit dependencies. The &f-Scanner; function accepts the following arguments:

`function`

- This can be either:

  - a Python function that will process the Node (file) and return a list of File Nodes representing the implicit dependencies (file names) found in the contents; or:

  - a dictionary that maps keys (typically the file suffix, but see below for more discussion) to other Scanners that should be called.

  If the argument is a Python function, the function must accept three required arguments and an optional fourth:

  - `node` - The internal &SCons; node representing the file. Use `str`(`node`) to fetch the name of the file, and `node`.`get_contents`() to fetch the contents of the file as bytes or `node`.`get_text_contents`() to fetch the contents as text. Note that the file is not guaranteed to exist before the scanner is called, so the scanner function should check that if there's any chance that the scanned file might not exist (for example, if it's built from other files).
  - `env` - The &consenv; for the scan.
  - `path` - A tuple (or list) of directories that can be searched for files. This will usually be the tuple returned by the `path_function` argument (see below).
  - `arg` - The argument supplied when the scanner was created, if any (default `None`.

`name`

- The name of the Scanner. This is mainly used to identify the Scanner internally.

`argument`

- An optional argument that, if specified, will be passed to the scanner function (described above) and the path function (specified below).

`skeys`

- An optional list that can be used to determine which scanner should be used for a given Node. 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 the argument is a string, then it will be expanded into a list by the current environment.

`path_function`

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

`node_class`

- The class of Node that should be returned by this Scanner object. Any strings or other objects returned by the scanner function that are not of this class will be run through the function supplied by the `node_factory` argument.

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

`scan_check`

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

- An optional flag that specifies whether this scanner should be re-invoked on the dependency files returned by the scanner. When this flag is not set, the Node subsystem will only invoke the scanner on the file being scanned, and not (for example) also on the files specified by the `#include` lines in the file being scanned. 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.

Note that &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 for different file extensions. 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'])

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

#### .F file suffix

&scons; handles the upper-case `.F` 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 `.F` suffix as a Fortran source file that is to be first run through the standard C preprocessor. On a case-insensitive system such as Windows, &scons; treats a file with a `.F` suffix as a Fortran source file that should not be run through the C preprocessor.

#### 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 more POSIX-like environment. The Cygwin tools, including Cygwin Python, do this, in part, by sharing an ability to interpret UNIX-like 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 have 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 rules: When using &gcc;, use the Cygwin-supplied Python interpreter to run &scons;; when using Microsoft Visual C/C++ (or some other Windows compiler) use the python.org or Microsoft Store or ActiveState version of Python to run &scons;.

#### Windows: `scons.bat` file

On Windows systems, &scons; is executed via a wrapper `scons.bat` file. This has (at least) two ramifications:

First, Windows command-line users that want to use variable assignment on the command line may have to put double quotes around the assignments:

    scons "FOO=BAR" "BAZ=BLEH"

Second, the Cygwin shell does not recognize this file as being the same as an &scons; command issued at the command-line prompt. You can work around this either by executing `scons.bat` from the Cygwin command line, or by creating a wrapper shell script named `scons`.

#### 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 of options that will be used by &scons; in addition to those passed on the command line.

`SCONS_CACHE_MSVC_CONFIG`

- (Windows only). If set, save the shell environment variables generated when setting up the Microsoft Visual C++ compiler (and/or Build Tools) to a file to give these settings, which are expensive to generate, persistence across &scons; invocations. Use of this option is primarily intended to aid performance in tightly controlled Continuous Integration setups.

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

  Note: use this cache with caution as it might be somewhat fragile: while each major toolset version (e.g. Visual Studio 2017 vs 2019) and architecture pair will get separate cache entries, if toolset updates cause a change to settings within a given release series, &scons; will not detect the change and will reuse old settings. Remove the cache file in case of problems with this. &scons; will ignore failures reading or writing the file and will silently revert to non-cached behavior in such cases.

  Available since &scons; 3.1 (experimental).

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