%version; %scons; %builders-mod; %functions-mod; %tools-mod; %variables-mod; ]> MAN page The SCons Development Team Released &builddate; ©right_years; The SCons Foundation Version &buildversion; MAN page SCONS 1 SCons __VERSION__ SCons __VERSION__ scons a software construction tool scons options name=val targets &scons; orchestrates the construction of software (and other tangible products such as documentation files) by determining which component pieces must be built or rebuilt and invoking the necessary commands to build them. &SCons; offers many features to improve developer productivity such as parallel builds, caching of build artifacts, automatic dependency scanning, and a database of information about previous builds so details do not have to be recalculated each run. &scons; requires Python 3.5 or later to run; there should be no other dependencies or requirements. Support for Python 3.5 is deprecated since &SCons; 4.2 and will be dropped in a future release. The CPython project has retired 3.5: . You set up an &SCons; build system by writing a script that describes things to build (targets), and, if necessary, the rules to build those files (actions). &SCons; comes with a collection of Builder methods which apply premade actions for building many common software components such as executable programs, object files and libraries, so that for many software projects, only the targets and input files (sources) need be specified in a call to a builder. &scons; thus can operate at a level of abstraction above that of pure files. For example if you specify a library target named "foo", &scons; keeps track of the actual operating system dependent filename (such as libfoo.so on a GNU/Linux system), and how to refer to that library in later construction steps that want to use it, so you don't have to specify that precise information yourself. &scons; can also scan automatically for dependency information, such as header files included by source code files, so this does not have to be specified manually. When invoked, &scons; looks for a file named &SConstruct; in the current directory and reads the build configuration from that file (other names are allowed, see for more information). The &SConstruct; file may specify subsidiary configuration files by calling the &f-link-SConscript; 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 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 or, if specified, the directory from the --site-dir option instead, and prepends the ones it finds to the Python module search path (sys.path), thus allowing modules in such directories to be imported in the normal Python way in SConscript files. For each found site directory, (1) if it contains a file site_init.py that file is evaluated, and (2) if it contains a directory site_tools the path to that directory is prepended to the default toolpath. See the --site-dir and --no-site-dir options for details on default paths and controlling the site directories. SConscript files are written in the Python programming language, although it is normally not necessary to be a Python programmer to use &scons; effectively. SConscript files are invoked in a context that makes the facilities described in this manual page available in their local namespace without any special steps. Standard Python scripting capabilities such as flow control, data manipulation, and imported Python libraries are available to use to handle complicated build situations. Other Python files can be made a part of the build system, but they do not automatically have the &SCons; context and need to import it if they need access (described later). &scons; reads and executes all of the included SConscript files before it begins building any targets. To make this clear, &scons; prints the following messages about what it is doing: $ scons foo.out scons: Reading SConscript files ... scons: done reading SConscript files. scons: Building targets ... cp foo.in foo.out scons: done building targets. $ The status messages (lines beginning with the scons: tag) may be suppressed using the -Q option. &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 execution environment by setting the path in the ENV &consvar; in the internal &consenv;: import os env = Environment(ENV={'PATH': os.environ['PATH']}) Similarly, if the commands use specific external environment variables that &scons; does not recognize, they can be propagated into the execution environment: import os env = Environment( ENV={ 'PATH': os.environ['PATH'], 'ANDROID_HOME': os.environ['ANDROID_HOME'], 'ANDROID_NDK_HOME': os.environ['ANDROID_NDK_HOME'], } ) Or you may explicitly propagate the invoking user's complete external environment: import os env = Environment(ENV=os.environ.copy()) This comes at the expense of making your build dependent on the user's environment being set correctly, but it may be more convenient for many configurations. It should not cause problems if done in a build setup which tightly controls how the environment is set up before invoking &scons;, as in many continuous integration setups. &scons; can scan known input file types 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 to support additional 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 ) are consumed. Any variable argument assignments are collected, and remaining arguments are taken as targets to build. Values of variables to be passed to the SConscript files may be specified on the command line: scons debug=1 These variables are available through the &ARGUMENTS; dictionary, and can be used in the SConscript files to modify the build in any way: if ARGUMENTS.get('debug', 0): env = Environment(CCFLAGS='-g') else: env = Environment() The command-line variable arguments are also available in the &ARGLIST; list, indexed by their order on the command line. This allows you to process them in order rather than by name, if necessary. Each &ARGLIST; entry is a tuple containing (argname, argvalue). See for more information. &scons; can maintain a cache of target (derived) files that can be shared between multiple builds. When derived-file caching is enabled in an SConscript file, any target files built by &scons; will be copied to the cache. If an up-to-date target file is found in the cache, it will be retrieved from the cache instead of being rebuilt locally. Caching behavior may be disabled and controlled in other ways by the --cache-force, --cache-disable, --cache-readonly, and --cache-show command-line options. The --random option is useful to prevent multiple builds from trying to update the cache simultaneously. By default, &scons; searches for known programming tools on various systems and initializes itself based on what is found. On Windows systems which identify as win32, &scons; searches in order for the Microsoft Visual C++ tools, the MinGW tool chain, the Intel compiler tools, and the PharLap ETS compiler. On Windows system which identify as cygwin (that is, if &scons; is invoked from a cygwin shell), the order changes to prefer the GCC toolchain over the MSVC tools. On OS/2 systems, &scons; searches in order for the OS/2 compiler, the GCC tool chain, and the Microsoft Visual C++ tools, On SGI IRIX, IBM AIX, Hewlett Packard HP-UX, and Oracle Solaris systems, &scons; searches for the native compiler tools (MIPSpro, Visual Age, aCC, and Forte tools respectively) and the GCC tool chain. On all other platforms, including POSIX (Linux and UNIX) platforms, &scons; searches in order for the GCC tool chain, and the Intel compiler tools. These default values may be overridden by appropriate setting of &consvars;. &SCons; acts on the selected targets, whether the requested operation is build, no-exec or clean. Targets are selected as follows: Targets specified on the command line. These may be files, directories, or phony targets defined using the &f-link-Alias; function. Directory targets are scanned by &scons; for any targets that may be found with a destination in or under that directory. The targets listed on the command line are made available in the &COMMAND_LINE_TARGETS; list. If no targets are specified on the command line, &scons; will select those targets specified in the SConscript files via calls to the &f-link-Default; function. These are known as the default targets, and are made available in the &DEFAULT_TARGETS; list. If no targets are selected by the previous steps, &scons; selects the current directory for scanning, unless command-line options which affect the target scan are detected (-C, -D, -u, -U). Since targets thus selected were not the result of user instructions, this target list is not made available for direct inspection; use the --debug=explain option if they need to be examined. &scons; always adds to the selected targets any intermediate targets which are necessary to build the specified ones. For example, if constructing a shared library or dll from C source files, &scons; will also build the object files which will make up the library. To ignore the default targets specified through calls to &Default; and instead build all target files in or below the current directory specify the current directory (.) as a command-line target: scons . To build all target files, including any files outside of the current directory, supply a command-line target of the root directory (on POSIX systems): scons / or the path name(s) of the volume(s) in which all the targets should be built (on Windows systems): scons C:\ D:\ A subset of a hierarchical tree may be built by remaining at the top-level directory (where the &SConstruct; file lives) and specifying the subdirectory as the target to build: scons src/subdir or by changing directory and invoking scons with the -u option, which traverses up the directory hierarchy until it finds the &SConstruct; file, and then builds targets relatively to the current subdirectory (see also the related -D and -U options): cd src/subdir scons -u . In all cases, more files may be built than are requested, as &scons; needs to make sure any dependent files are built. Specifying "cleanup" targets in SConscript files is usually not necessary. The -c flag removes all selected targets: scons -c . to remove all target files in or under the current directory, or: scons -c build export to remove target files under build and export. Additional files or directories to remove can be specified using the &f-link-Clean; function in the SConscript files. Conversely, targets that would normally be removed by the -c invocation can be retained by calling the &f-link-NoClean; function with those targets. &scons; supports building multiple targets in parallel via a -j option that takes, as its argument, the number of simultaneous tasks that may be spawned: scons -j 4 builds four targets in parallel, for example. In general, &scons; supports the same command-line options as GNU &Make; and many of those supported by cons. -b Ignored for compatibility with non-GNU versions of &Make; -c, --clean, --remove Set clean mode. Clean up by removing the selected targets, well as any files or directories associated with a selected target through calls to the &f-link-Clean; function. Will not remove any targets which are marked for preservation through calls to the &f-link-NoClean; function. While clean mode removes targets rather than building them, work which is done directly in Python code in SConscript files will still be carried out. If it is important to avoid some such work from taking place in clean mode, it should be protected. An SConscript file can determine which mode is active by querying &f-link-GetOption;, as in the call if GetOption("clean"): --cache-debug=file Write debug information about derived-file caching to the specified file. If file is a hyphen (-), the debug information is printed to the standard output. The printed messages describe what signature-file names are being looked for in, retrieved from, or written to the derived-file cache specified by &f-link-CacheDir;. --cache-disable, --no-cache Disable derived-file caching. &scons; will neither retrieve files from the cache nor copy files to the cache. This option can be used to temporarily disable the cache without modifying the build scripts. --cache-force, --cache-populate When using &f-link-CacheDir;, populate a derived-file cache by copying any already-existing, up-to-date derived files to the cache, in addition to files built by this invocation. This is useful to populate a new cache with all the current derived files, or to add to the cache any derived files recently built with caching disabled via the --cache-disable option. --cache-readonly Use the derived-file cache, if enabled, to retrieve files, but do not not update the cache with any files actually built during this invocation. --cache-show When using a derived-file cache show the command that would have been executed to build the file (or the corresponding *COMSTR contents if set) even if the file is retrieved from cache. Without this option, &scons; shows a cache retrieval message if the file is fetched from cache. This allows producing consistent output for build logs, regardless of whether a target file was rebuilt or retrieved from the cache. --config=mode Control how the &f-link-Configure; call should use or generate the results of configuration tests. mode should be one of the following choices: auto &SCons; will use its normal dependency mechanisms to decide if a test must be rebuilt or not. This saves time by not running the same configuration tests every time you invoke scons, but will overlook changes in system header files or external commands (such as compilers) if you don't specify those dependecies explicitly. This is the default behavior. force If this mode is specified, all configuration tests will be re-run regardless of whether the cached results are out of date. This can be used to explicitly force the configuration tests to be updated in response to an otherwise unconfigured change in a system header file or compiler. cache If this mode is specified, no configuration tests will be rerun and all results will be taken from cache. &scons; will report an error if --config=cache is specified and a necessary test does not have any results in the cache. -C directory, --directory=directory Run as if &scons; was started in directory instead of the current working directory. That is, change directory before searching for the &SConstruct;, &Sconstruct;, &sconstruct;, &SConstruct.py;, &Sconstruct.py; or &sconstruct.py; file or doing anything else. When multiple -C options are given, each subsequent non-absolute -C directory is interpreted relative to the preceding one. This option is similar to using -f directory/SConstruct, but -f does not search for any of the predefined &SConstruct; names in the specified directory. See also options -u, -U and -D to change the &SConstruct; search behavior when this option is used. -D Works exactly the same way as the -u option except for the way default targets are handled. When this option is used and no targets are specified on the command line, all default targets are built, whether or not they are below the current directory. --debug=type[,type...] Debug the build process. type specifies the kind of debugging info to emit. Multiple types may be specified, separated by commas. The following types are recognized: action-timestamps Prints additional time profiling information. For each command, shows the absolute start and end times. This may be useful in debugging parallel builds. Implies the --debug=time option. 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 Enable specific checks for whether or not there is a file on disk where the SCons configuration expects a directory (or vice versa) when searching for source and include files. type can be an available diskcheck type or the special tokens all or none. A comma-separated string can be used to select multiple checks. The default setting is all. Current available checks are: match to check that files and directories on disk match SCons' expected configuration. Disabling some or all of these checks can provide a performance boost for large configurations, or when the configuration will check for files and/or directories across networked or shared file systems, at the slight increased risk of an incorrect build or of not handling errors gracefully. --duplicate=ORDER There are three ways to duplicate files in a build tree: hard links, soft (symbolic) links and copies. The default policy is to prefer hard links to soft links to copies. You can specify a different policy with this option. ORDER must be one of hard-soft-copy (the default), soft-hard-copy, hard-copy, soft-copy or copy. &SCons; will attempt to duplicate files using the mechanisms in the specified order. --enable-virtualenv Import virtualenv-related variables to SCons. --experimental=feature Enable experimental features and/or tools. feature can be an available feature name or the special tokens all or none. A comma-separated string can be used to select multiple features. The default setting is none. Current available features are: ninja. No Support offered for any features or tools enabled by this flag. Available since &scons; 4.2. -f file, --file=file, --makefile=file, --sconstruct=file Use file as the initial SConscript file. Multiple -f options may be specified, in which case &scons; will read all of the specified files. -h, --help Print a local help message for this project, if one is defined in the SConscript files (see the &f-link-Help; function), plus a line that refers to the standard &SCons; help message. If no local help message is defined, prints the standard &SCons; help message (as for the -H option) plus help for any local options defined through &f-link-AddOption;. Exits after displaying the appropriate message. Note that use of this option requires &SCons; to process the SConscript files, so syntax errors may cause the help message not to be displayed. --hash-chunksize=KILOBYTES Set the block size used when computing content signatures to KILOBYTES. This value determines the size of the chunks which are read in at once when computing signature hashes. Files below that size are fully stored in memory before performing the signature computation while bigger files are read in block-by-block. A huge block-size leads to high memory consumption while a very small block-size slows down the build considerably. The default value is to use a chunk size of 64 kilobytes, which should be appropriate for most uses. Available since &scons; 4.2. --hash-format=ALGORITHM Set the hashing algorithm used by SCons to ALGORITHM. This value determines the hashing algorithm used in generating content signatures or &f-link-CacheDir; keys. The supported list of values are: md5, sha1, and sha256. However, the Python interpreter used to run SCons must have the corresponding support available in the hashlib module to use the specified algorithm. Specifying this value changes the name of the SConsign database. For example, --hash-format=sha256 will create a SConsign database with name .sconsign_sha256.dblite. If this option is not specified, a the first supported hash format found is selected, and the SConsign database is .sconsign.dblite. Available since &scons; 4.2. -H, --help-options Print the standard help message about &SCons; command-line options and exit. -i, --ignore-errors Ignore all errors from commands executed to rebuild files. -I directory, --include-dir=directory Specifies a directory to search for imported Python modules. If several -I options are used, the directories are searched in the order specified. --ignore-virtualenv Suppress importing virtualenv-related variables to SCons. --implicit-cache Cache implicit dependencies. This causes &scons; to use the implicit (scanned) dependencies from the last time it was run instead of scanning the files for implicit dependencies. This can significantly speed up SCons, but with the following limitations: &scons; will not detect changes to implicit dependency search paths (e.g. 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=sandbox_path When using the &Install; builders, prepend sandbox_path to the installation paths such that all installed files will be placed under that directory. This option is unavailable if one of &b-link-Install;, &b-link-InstallAs; or &b-link-InstallVersionedLib; is not used in the SConscript files. --interactive Starts SCons in interactive mode. The SConscript files are read once and a scons>>> prompt is printed. Targets may now be rebuilt by typing commands at interactive prompt without having to re-read the SConscript files and re-initialize the dependency graph from scratch. SCons interactive mode supports the following commands: build [OPTIONS] [TARGETS] ... Builds the specified TARGETS (and their dependencies) with the specified SCons command-line OPTIONS. b and scons are synonyms for build. The following SCons command-line options affect the build command: --cache-debug=FILE --cache-disable, --no-cache --cache-force, --cache-populate --cache-readonly --cache-show --debug=TYPE -i, --ignore-errors -j N, --jobs=N -k, --keep-going -n, --no-exec, --just-print, --dry-run, --recon -Q -s, --silent, --quiet --taskmastertrace=FILE --tree=OPTIONS Any other SCons command-line options that are specified do not cause errors but have no effect on the build command (mainly because they affect how the SConscript files are read, which only happens once at the beginning of interactive mode). clean [OPTIONS] [TARGETS] ... Cleans the specified TARGETS (and their dependencies) with the specified OPTIONS. c is a synonym. This command is itself a synonym for build --clean exit Exits SCons interactive mode. You can also exit by terminating input ( Ctrl D UNIX or Linux systems, ( Ctrl Z on Windows systems). help [COMMAND] Provides a help message about the commands available in SCons interactive mode. If COMMAND is specified, h and ? are synonyms. shell [COMMANDLINE] Executes the specified COMMANDLINE in a subshell. If no COMMANDLINE is specified, executes the interactive command interpreter specified in the SHELL environment variable (on UNIX and Linux systems) or the COMSPEC environment variable (on Windows systems). sh and ! are synonyms. version Prints SCons version information. An empty line repeats the last typed command. Command-line editing can be used if the readline module is available. $ scons --interactive scons: Reading SConscript files ... scons: done reading SConscript files. scons>>> build -n prog scons>>> exit -j N, --jobs=N Specifies the maximum number of comcurrent jobs (commands) to run. If there is more than one -j option, the last one is effective. -k, --keep-going Continue as much as possible after an error. The target that failed and those that depend on it will not be remade, but other targets specified on the command line will still be processed. -m Ignored for compatibility with non-GNU versions of &Make;. --max-drift=SECONDS Set the maximum expected drift in the modification time of files to SECONDS. This value determines how long a file must be unmodified before its cached 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 A deprecated synonym for --hash-chunksize. Deprecated since &scons; 4.2. -n, --no-exec, --just-print, --dry-run, --recon Set no execute mode. Print the commands that would be executed to build any out-of-date target files, but do not execute the commands. The output is a best effort, as &SCons; cannot always precisely determine what would be built. For example, if a file is generated by a builder action that is later used in the build, that file is not available to scan for dependencies on an unbuilt tree, or may contain out of date information in a built tree. Work which is done directly in Python code in SConscript files, as opposed to work done by builder actions during the build phase, will still be carried out. If it is important to avoid some such work from taking place in no execute mode, it should be protected. An SConscript file can determine which mode is active by querying &f-link-GetOption;, as in the call if GetOption("no_exec"): --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. --package-type=type The type or types of package to create when using the &b-link-Package; builder. In the case of multiple types, type should be a comma-separated string; &SCons; will try to build for all of those packages. Note this option is only available if the &t-link-packaging; tool has been enabled. --profile=file Run SCons under the Python profiler and save the results 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. The build configuration is described by one or more files, known as SConscript files. There must be at least one file for a valid build (&scons; will quit if it does not find one). &scons; by default looks for this file by the name SConstruct in the directory from which you run &scons;, though if necessary, also looks for alternative file names &Sconstruct;, &sconstruct;, &SConstruct.py;, &Sconstruct.py; and &sconstruct.py; in that order. A different file name (which can include a pathname part) may be specified via the -f option. Except for the SConstruct file, these files are not searched for automatically; you add additional configuration files to the build by calling the &f-link-SConscript; function. This allows parts of the build to be conditionally included or excluded at run-time depending on how &scons; is invoked. Each SConscript file in a build configuration is invoked independently in a separate context. This provides necessary isolation so that different parts of the build don't accidentally step on each other. You have to be explicit about sharing information, by using the &f-link-Export; function or the &exports; argument to the &SConscript; function, as well as the &f-link-Return; function in a called SConscript file, and comsume shared information by using the &f-link-Import; function. The following sections describe the various &SCons; facilities that can be used in SConscript files. Quick links: Construction Environments Tools Builder Methods Methods and Functions to do Things SConscript Variables Construction Variables Configure Contexts Command-Line Construction Variables Node Objects A &ConsEnv; is the basic means by which you communicate build information to &SCons;. A new &consenv; is created using the &f-link-Environment; function: env = Environment() &Consenv; attributes called &ConsVars; may be set either by specifying them as keyword arguments when the object is created or by assigning them a value after the object is created. These two are nominally equivalent: env = Environment(FOO='foo') env['FOO'] = 'foo' Note that certain settings which affect tool detection are referenced only when the tools are initializided, so you either need either to supply them as part of the call to &f-link-Environment;, or defer tool initialization. For example, initializing the Microsoft Visual C++ version you wish to use: # initializes msvc to v14.1 env = Environment(MSVC_VERSION="14.1") env = Environment() # msvc tool was initialized to default, does not reinitialize env['MSVC_VERSION'] = "14.1" env = Environment(tools=[]) env['MSVC_VERSION'] = "14.1" # msvc tool initialization was deferred, so will pick up new value env.Tool('default') As a convenience, &consvars; may also be set or modified by the parse_flags keyword argument during object creation, which has the effect of the &f-link-env-MergeFlags; method being applied to the argument value after all other processing is completed. This is useful either if the exact content of the flags is unknown (for example, read from a control file) or if the flags need to be distributed to a number of &consvars;. &f-link-env-ParseFlags; describes how these arguments are distributed to &consvars;. env = Environment(parse_flags='-Iinclude -DEBUG -lm') This example adds 'include' to the CPPPATH &consvar;, 'EBUG' to CPPDEFINES, and 'm' to LIBS. An existing &consenv; can be duplicated by calling the &f-link-env-Clone; method. Without arguments, it will be a copy with the same settings. Otherwise, &f-env-Clone; takes the same arguments as &f-link-Environment;, and uses the arguments to create a modified copy. &SCons; provides a special &consenv; called the &DefEnv;. The &defenv; is used only for global functions, that is, construction activities called without the context of a regular &consenv;. See &f-link-DefaultEnvironment; for more information. By default, a new &consenv; is initialized with a set of builder methods and &consvars; that are appropriate for the current platform. The optional platform keyword argument may be used to specify that the &consenv; should be initialized for a different platform: env = Environment(platform='cygwin') Specifying a platform initializes the appropriate &consvars; in the environment to use and generate file names with prefixes and suffixes appropriate for that platform. Note that the win32 platform adds the SystemDrive and SystemRoot variables from the user's external environment to the &consenv;'s ENV dictionary. This is so that any executed commands that use sockets to connect with other systems will work on Windows systems. The platform argument may be a string value representing one of the pre-defined platforms (aix, cygwin, darwin, hpux, irix, os2, posix, sunos or win32), or it may be be a callable platform object returned by a call to &f-link-Platform; selecting a pre-defined platform, or it may be a user-supplied callable, in which case the &Environment; method will call it to update the new &consenv;: def my_platform(env): env['VAR'] = 'xyzzy' env = Environment(platform=my_platform) Note that supplying a non-default platform or custom fuction for initialization may bypass settings that should happen for the host system and should be used with care. It is most useful in the case where the platform is an alternative for the one that would be auto-detected, such as platform="cygwin" on a system which would otherwise identify as win32. The optional tools and toolpath keyword arguments affect the way tools available to the environment are initialized. See for details. The optional variables keyword argument allows passing a Variables object which will be used in the initialization of the &consenv; See for details. &SCons; has a large number of predefined tools (more properly, tool specifications) which are used to help initialize the &consenv;. An &SCons; tool 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 that builder and all the &consvars; it needs in the associated &consenv;; the tool itself is not called in the process of the build. Normally this happens invisibly: &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, or other preconditions are not met. A specific set of tools with which to initialize an environment when creating it may be specified using the optional keyword argument tools, which takes a list of tool names. This is useful to override the defaults, to specify non-default built-in tools, and to supply added tools: env = Environment(tools=['msvc', 'lex']) Tools can also be directly called by using the &f-link-Tool; method (see below). The tools argument overrides the default tool list, it does not add to it, so be sure to include all the tools you need. For example if you are building a c/c++ program you must specify a tool for at least a compiler and a linker, as in tools=['clang', 'link']. The tool name 'default' can be used to retain the default list. If no tools argument is specified, or if tools includes 'default', then &scons; will auto-detect usable tools, using the execution environment value of PATH (that is, env['ENV']['PATH'] - the external evironment PATH from os.environ is not used) for looking up any backing programs, and the platform name in effect to determine the default tools for that platform. Changing the PATH variable after the &consenv; is constructed will not cause the tools to be re-detected. Additional tools can be added to a project either by placing them in a site_tools subdirectory of a site directory, or in a custom location specified to &scons; by giving the toolpath keyword argument. toolpath also takes a list as its value: env = Environment(tools=['default', 'foo'], toolpath=['tools']) This looks for a tool specification module foo.py in directory tools and in the standard locations, as well as using the ordinary default tools for the platform. Directories specified via toolpath are prepended to the existing tool path. The default tool path is any site_tools directories, so tools in a specified toolpath take priority, followed by tools in a site_tools directory, followed by built-in tools. For example, adding a tool specification module gcc.py to the toolpath directory would override the built-in &t-link-gcc; tool. The tool path is stored in the environment and will be used by subsequent calls to the &f-link-Tool; method, as well as by &f-link-env-Clone;. base = Environment(toolpath=['custom_path']) derived = base.Clone(tools=['custom_tool']) derived.CustomBuilder() A tool specification module must include two functions: generate(env, **kwargs) 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 in the context of env. Usually this means looking up one or more known programs using the PATH from the supplied env, but the tool can make the "exists" decision in any way it chooses. At the moment, user-added tools do not automatically have their exists function called. As a result, it is recommended that the generate function be defensively coded - that is, do not rely on any necessary existence checks already having been performed. This is expected to be a temporary limitation, and the exists function should still be provided. The elements of the tools list may also be functions or callable objects, in which case the &Environment; method will call those objects to update the new &consenv; (see &f-link-Tool; for more details): def my_tool(env): env['XYZZY'] = 'xyzzy' env = Environment(tools=[my_tool]) The individual elements of the tools list may also themselves be lists or tuples of the form (toolname, kw_dict). SCons searches for the toolname specification file as described above, and passes kw_dict, which must be a dictionary, as keyword arguments to the tool's generate function. The generate function can use the arguments to modify the tool's behavior by setting up the environment in different ways or otherwise changing its initialization. # in tools/my_tool.py: def generate(env, **kwargs): # Sets MY_TOOL to the value of keyword 'arg1' '1' if not supplied env['MY_TOOL'] = kwargs.get('arg1', '1') def exists(env): return True # in SConstruct: env = Environment(tools=['default', ('my_tool', {'arg1': 'abc'})], toolpath=['tools']) The tool specification (my_tool in the example) can use the PLATFORM variable from the &consenv; it is passed to customize the tool for different platforms. Tools can be "nested" - that is, they can be located within a subdirectory in the toolpath. A nested tool name uses a dot to represent a directory separator # namespaced builder env = Environment(ENV=os.environ.copy(), tools=['SubDir1.SubDir2.SomeTool']) env.SomeTool(targets, sources) # Search Paths # SCons\Tool\SubDir1\SubDir2\SomeTool.py # SCons\Tool\SubDir1\SubDir2\SomeTool\__init__.py # .\site_scons\site_tools\SubDir1\SubDir2\SomeTool.py # .\site_scons\site_tools\SubDir1\SubDir2\SomeTool\__init__.py SCons supports the following tool specifications out of the box: You tell &scons; what to build by calling Builders, functions which take particular action(s) to produce a particular result type (conventionally described by the builder name such as &b-Program;) when given source files of a particular type. Calling a builder defines one or more targets to the build system; whether the targets are actually built on a given invocation is determined by command-line options, target selection rules, and whether &SCons; determines the target(s) are out of date. &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: env = Environment() print("Builders:", list(env['BUILDERS'])) Builder methods take two required arguments: target and source. Either can be passed as a scalar or as a list. The target and source arguments can be specified either as positional arguments, in which case target comes first, or as keyword arguments, using target= and source=. Although both arguments are nominally required, if there is a single source and the target can be inferred the target argument can be omitted (see below). Builder methods also take a variety of keyword arguments, described below. The builder may add other targets beyond those requested if indicated by an Emitter (see and, for example, &cv-link-PROGEMITTER; for more information). 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 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 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') Keyword arguments that are not specifically recognized are treated as &consvar; overrides, which replace or add those variables on a limited basis. These overrides will only be in effect when building the target of the builder call, and will not affect other parts of the build. For example, if you want to specify some libraries needed by just one program: env.Program('hello', 'hello.c', LIBS=['gl', 'glut']) or generate a shared library with a non-standard suffix: env.SharedLibrary( target='word', source='word.cpp', SHLIBSUFFIX='.ocx', LIBSUFFIXES=['.ocx'], ) Note that both the &cv-link-SHLIBSUFFIX; and &cv-link-LIBSUFFIXES; 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. The optional parse_flags keyword argument is recognized by builders. This works similarly to the &f-link-env-MergeFlags; method, where the argument value is broken into individual settings and merged into the appropriate &consvars;. env.Program('hello', 'hello.c', parse_flags='-Iinclude -DEBUG -lm') This example adds 'include' to CPPPATH, 'EBUG' to CPPDEFINES, and 'm' to LIBS. Although the builder methods defined by &scons; are, in fact, methods of a &consenv; object, many may also be called without an explicit environment: Program('hello', 'hello.c') SharedLibrary('word', 'word.cpp') If called this way, methods will internally use the &defenv; that consists of the tools and values that &scons; has determined are appropriate for the local system. Builder methods that can be called without an explicit environment (indicated in the listing of builders without a leading env.) may be called from custom Python modules that you import into an SConscript file by adding the following to the Python module: from SCons.Script import * Builder methods return a NodeList, a list-like object whose elements are Nodes, &SCons;' internal representation of build targets or sources. See for more information. The returned NodeList object can be passed to other builder methods as source(s) or passed to any &SCons; function or method where a filename would normally be accepted. For example, to add a specific preprocessor define when compiling one specific object file but not the others: bar_obj_list = env.StaticObject('bar.c', CPPDEFINES='-DBAR') env.Program("prog", ['foo.c', bar_obj_list, 'main.c']) Using a Node as in this example makes for a more portable build by avoiding having to specify a platform-specific object suffix when calling the &Program; builder method. The NodeList object is also convenient to pass to the &f-link-Default; function, for the same reason of avoiding a platform-specific name: tgt = env.Program("prog", ["foo.c", "bar.c", "main.c"]) Default(tgt) Builder calls will automatically "flatten" lists passed as source and target, so they are free to contain elements which are themselves lists, such as bar_obj_list returned by the &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 NodeList object containing the concatenation of the list elements and the builder results. This will cause problems for any other Python variables in your SCons configuration that still hold on to a reference to the original list. Instead, use the Python list extend method to make sure the list is updated in-place. Example: object_files = [] # Do NOT use += here: # object_files += Object('bar.c') # # It will not update the object_files list in place. # # Instead, use the list extend method: object_files.extend(Object('bar.c')) The path name for a Node's file may be used by passing the Node to Python's builtin str function: bar_obj_list = env.StaticObject('bar.c', CPPDEFINES='-DBAR') print("The path to bar_obj is:", str(bar_obj_list[0])) Note that because the Builder call returns a NodeList, you have to access the first element in the list, (bar_obj_list[0] in the example) to get at the Node that actually represents the object file. 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. When trying to handle errors that may occur in a builder method, consider that the corresponding Action is executed at a different time than the SConscript file statement calling the builder. It is not useful to wrap a builder call in a try block, since success in the builder call is not the same as the builder itself succeeding. If necessary, a Builder's Action should be coded to exit with a useful exception message indicating the problem in the SConscript files - programmatically recovering from build errors is rarely useful. &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 for more information about defining your own Scanner objects and using the SourceFileScanner object. 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: 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 * A &consenv; has an associated dictionary of &consvars; that are used by built-in or user-supplied build rules. &Consvar; naming must follow the same rules as Python identifier naming: the initial character must be an underscore or letter, followed by any number of underscores, letters, or digits. A &consenv; is not a Python dictionary itself, but it can be indexed like one to access a &consvar;: env["CC"] = "cc" flags = env.get("CPPDEFINES", []) &Consvars; can also be retrieved and set by using the &f-link-Dictionary; method of the &consenv; to create an actual dictionary: cvars = env.Dictionary() cvars["CC"] = "cc" &Consvars; can also be passed to the &consenv; constructor: env = Environment(CC="cc") or when copying a &consenv; using the &f-link-Clone; method: env2 = env.Clone(CC="cl.exe") &Consvars; can also be supplied as keyword arguments to a builder, in which case those settings affect only the work done by that builder call, and not the &consenv; as a whole. This concept is called an override: env.Program('hello', 'hello.c', LIBS=['gl', 'glut']) A number of useful &consvars; are automatically defined by scons for each supported platform, and you can modify these or define any additional &consvars; for your own use, taking care not to overwrite ones which &SCons; is using. The following is a list of the possible automatically defined &consvars;. Note the actual list available at execution time will never include all of these, as the ones detected as not being useful (wrong platform, necessary external command or files not installed, etc.) will not be set up. Correct build setups should be resilient to the possible absence of certain &consvars; before using them, for example by using a &Python; dictionary get method to retrieve the value and taking alternative action if the return indicates the variable is unset. The &f-link-env-Dump; method can be called to examine the &consvars; set in a particular environment. &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(CPPDEFINES="WITH_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() Often when building software, some variables need to be specified at build time. For example, libraries needed for the build may be in non-standard locations, or site-specific compiler options may need to be passed to the compiler. &SCons; provides a &Variables; object to support overriding &consvars; with values obtained from various sources, often from the command line: scons VARIABLE=foo The variable values can also be specified in a configuration file or an SConscript file. To obtain the object for manipulating values, call the &Variables; function: Variables([files, [args]]) If files is a file or list of files, they are executed as Python scripts, and the values of (global) Python variables set in those files are added as &consvars; in the &DefEnv;. If no files are specified, or the files argument is None, then no files will be read (supplying None is necessary if there are no files but you want to specify args as a positional argument). The following example file contents could be used to set an alternative C compiler: CC = 'my_cc' If args is specified, it is a dictionary of values that will override anything read from files. The primary use is to pass the &ARGUMENTS; dictionary that holds variables specified on the command line, allowing you to indicate that if a setting appears on both the command line and in the file(s), the command line setting takes precedence. However, any dictionary can be passed. Examples: vars = Variables('custom.py') vars = Variables('overrides.py', ARGUMENTS) vars = Variables(None, {FOO:'expansion', BAR:7}) Calling &Variables; with no arguments is equivalent to: vars = Variables(files=None, args=ARGUMENTS) Note that since the variables are eventually added as &consvars;, you should choose variable names which do not unintentionally change pre-defined &consvars; that your project will make use of (see ). Variables objects have the following methods: vars.Add(key, [help, default, validator, converter]) Add a customizable &consvar; to the Variables object. key is either the name of the variable, or a tuple (or list), in which case the first item in the tuple is taken as the variable name, and any remaining values are considered aliases for the variable. help is the help text for the variable (default empty string). default is the default value of the variable (default None). If default is None and a value is not specified, the &consvar; will not be added to the &consenv;. As a special case, if key is a tuple (or list) and is the only argument, the tuple is unpacked into the five parameters listed above left to right, with any missing members filled with the respecitive default values. This form allows Add to consume a tuple emitted by the convenience functions BoolVariable, EnumVariable, ListVariable, PackageVariable and PathVariable. If the optional validator is supplied, it is called to validate the value of the variable. A function supplied as a validator must accept three arguments: key, value and env, and should raise an exception with a helpful error message if value is invalid. No return value is expected from the validator. If the optional converter is supplied, it is called to convert the value before putting it in the environment, and should take either a value or a value and environment as parameters. The converter function must return a value, which will be converted into a string and be passed to the validator (if any) and then added to the &consenv;. Examples: vars.Add('CC', help='The C compiler') def valid_color(key, val, env): if not val in ['red', 'blue', 'yellow']: raise Exception("Invalid color value '%s'" % val) vars.Add('COLOR', validator=valid_color) vars.AddVariables(args) A convenience method that adds one or more customizable &consvars; to a Variables object in one call; equivalent to calling &Add; multiple times. The args are tuples (or lists) that contain the arguments for an individual call to the &Add; method. Since tuples are not Python mappings, the arguments cannot use the keyword form, but rather are positional arguments as documented for Add: a required name, the other four optional, but must be in the specified order if used. opt.AddVariables( ("debug", "", 0), ("CC", "The C compiler"), ("VALIDATE", "An option for testing validation", "notset", validator, None), ) vars.Update(env, [args]) Update a &consenv; env with the customized &consvars;. Any specified variables that are not configured for the Variables object will be saved and may be retrieved using the &UnknownVariables; method. Normally this method is not called directly, but rather invoked indirectly by passing the Variables object to the &f-link-Environment; function: env = Environment(variables=vars) vars.UnknownVariables() Returns a dictionary containing any variables that were specified either in the files or the dictionary with which the Variables object was initialized, but for which the Variables object was not configured. env = Environment(variables=vars) for key, value in vars.UnknownVariables(): print("unknown variable: %s=%s" % (key, value)) vars.Save(filename, env) Save the currently set variables into a script file named by filename. Only variables that are set to non-default values are saved. You can load these saved settings on a subsequent run by passing filename to the &Variables; function, providing a way to cache particular settings for reuse. env = Environment() vars = Variables(['variables.cache', 'custom.py']) vars.Add(...) vars.Update(env) vars.Save('variables.cache', env) vars.GenerateHelpText(env, [sort]) Generate help text documenting the customizable construction variables, suitable for passing in to the &f-link-Help; function. env is the &consenv; that will be used to get the actual values of the customizable variables. If the (optional) value of sort is callable, it is used as a comparison function to determine how to sort the added variables. This function must accept two arguments, compare them, and return a negative integer if the first is less-than the second, zero for equality, or a positive integer for greater-than. Optionally a Boolean value of True for sort will cause a standard alphabetical sort to be performed. Help(vars.GenerateHelpText(env)) def cmp(a, b): return (a > b) - (a < b) Help(vars.GenerateHelpText(env, sort=cmp)) vars.FormatVariableHelpText(env, opt, help, default, actual) Returns a formatted string containing the printable help text for one option. It is normally not called directly, but is called by the &GenerateHelpText; method to create the returned help text. It may be overridden with your own function that takes the arguments specified above and returns a string of help text formatted to your liking. Note that &GenerateHelpText; will not put any blank lines or extra characters in between the entries, so you must add those characters to the returned string if you want the entries separated. def my_format(env, opt, help, default, actual): fmt = "\n%s: default=%s actual=%s (%s)\n" return fmt % (opt, default, actual, help) vars.FormatVariableHelpText = my_format To make it more convenient to work with customizable Variables, &scons; provides a number of functions that make it easy to set up various types of Variables. Each of these return a tuple ready to be passed to the &Add; or &AddVariables; method: BoolVariable(key, help, default) 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, ), ) 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.relpath The build path of the given file or directory relative to the root SConstruct file's 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 # Current dir's path relative to the root SConstruct file's directory Dir('.').relpath # Next line is always '.', because it is the top dir's path relative to itself. Dir('#.').path File('foo.c').srcnode().path # source path of the given source file. # Builders also return File objects: 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') &scons; can be extended to build different types of targets by adding new Builder objects to a &consenv;. In general, you should only need to add a new Builder object when you want to build a new type of file or other external target. For output file types &scons; already knows about, you can usually modify the behavior of premade Builders such as &b-link-Program;, &b-link-Object; or &b-link-Library; by changing the &consvars; they use (&cv-link-CC;, &cv-link-LINK;, etc.). In this manner you can, for example, change the compiler to use, which is simpler and less error-prone than writing a new builder. The documentation for each Builder lists which &consvars; it uses. Builder objects are created using the &f-link-Builder; factory function. Once created, a builder is added to an environment by entering it in the &cv-link-BUILDERS; dictionary in that environment (some of the examples in this section illustrate that). The &f-Builder; function accepts the following keyword arguments: action The command used to build the target from the source. action may be a string representing a template command line to execute, a list of strings representing the command to execute with its arguments (suitable for enclosing white space in an argument), a dictionary mapping source file name suffixes to any combination of command line strings (if the builder should accept multiple source file extensions), a Python function, an Action object (see ) or a list of any of the above. An action function must accept three arguments: source, target and env. source is a list of source nodes; target is a list of target nodes; env is the &consenv; to use for context. The action and generator arguments must not both be used for the same Builder. prefix The prefix to prepend to the target file name. prefix may be a string, a function (or other callable) that takes two arguments (a &consenv; and a list of sources) and returns a prefix string, or a dictionary specifying a mapping from a specific source suffix (of the first source specified) to a corresponding target prefix string. For the dictionary form, both the source suffix (key) and target prefix (value) specifications may use environment variable substitution, and the target prefix may also be a callable object. The default target prefix may be indicated by a dictionary entry with a key of None. b = Builder("build_it < $SOURCE > $TARGET", prefix="file-") def gen_prefix(env, sources): return "file-" + env['PLATFORM'] + '-' b = Builder("build_it < $SOURCE > $TARGET", prefix=gen_prefix) b = Builder("build_it < $SOURCE > $TARGET", suffix={None: "file-", "$SRC_SFX_A": gen_prefix}) suffix The suffix to append to the target file name. Specified in the same manner as for prefix above. If the suffix is a string, then &scons; prepends a '.' to the suffix if it's not already there. The string returned by the callable object or obtained from the dictionary is untouched and you need to manually prepend a '.' if one is required. b = Builder("build_it < $SOURCE > $TARGET" suffix="-file") def gen_suffix(env, sources): return "." + env['PLATFORM'] + "-file" b = Builder("build_it < $SOURCE > $TARGET", suffix=gen_suffix) b = Builder("build_it < $SOURCE > $TARGET", suffix={None: ".sfx1", "$SRC_SFX_A": gen_suffix}) ensure_suffix If set to a true value, ensures that targets will end in suffix. Thus, the suffix will also be added to any target strings that have a suffix that is not already suffix. The default behavior (also indicated by a false value) is to leave unchanged any target string that looks like it already has a suffix. b1 = Builder("build_it < $SOURCE > $TARGET" suffix = ".out") b2 = Builder("build_it < $SOURCE > $TARGET" suffix = ".out", ensure_suffix=True) env = Environment() env['BUILDERS']['B1'] = b1 env['BUILDERS']['B2'] = b2 # Builds "foo.txt" because ensure_suffix is not set. env.B1('foo.txt', 'foo.in') # Builds "bar.txt.out" because ensure_suffix is set. env.B2('bar.txt', 'bar.in') src_suffix The expected source file name suffix. src_suffix may be a string or a list of strings. target_scanner A Scanner object that will be invoked to find implicit dependencies for this target file. This keyword argument should be used for Scanner objects that find implicit dependencies based only on the target file and the &consenv;, not for implicit dependencies based on source files. See for information about creating Scanner objects. source_scanner A Scanner object that will be invoked to find implicit dependencies in any source files used to build this target file. This is where you would specify a scanner to find things like #include lines in source files. The pre-built DirScanner Scanner object may be used to indicate that this Builder should scan directory trees for on-disk changes to files that &scons; does not know about from other Builder or function calls. See for information about creating your own Scanner objects. target_factory A factory function that the Builder will use to turn any targets specified as strings into SCons Nodes. By default, SCons assumes that all targets are files. Other useful target_factory values include Dir, for when a Builder creates a directory target, and Entry, for when a Builder can create either a file or directory target. Example: MakeDirectoryBuilder = Builder(action=my_mkdir, target_factory=Dir) env = Environment() env.Append(BUILDERS={'MakeDirectory': MakeDirectoryBuilder}) env.MakeDirectory('new_directory', []) Note that the call to this MakeDirectory Builder needs to specify an empty source list to make the string represent the builder's target; without that, it would assume the argument is the source, and would try to deduce the target name from it, which in the absence of an automatically-added prefix or suffix would lead to a matching target and source name and a circular dependency. source_factory A factory function that the Builder will use to turn any sources specified as strings into SCons Nodes. By default, SCons assumes that all source are files. Other useful source_factory values include Dir, for when a Builder uses a directory as a source, and Entry, for when a Builder can use files or directories (or both) as sources. Example: CollectBuilder = Builder(action=my_mkdir, source_factory=Entry) env = Environment() env.Append(BUILDERS={'Collect': CollectBuilder}) env.Collect('archive', ['directory_name', 'file_name']) emitter A function or list of functions to manipulate the target and source lists before dependencies are established and the target(s) are actually built. emitter can also be a string containing a &consvar; to expand to an emitter function or list of functions, or a dictionary mapping source file suffixes to emitter functions. (Only the suffix of the first source file is used to select the actual emitter function from an emitter dictionary.) A function passed as emitter must accept three arguments: source, target and env. source is a list of source nodes, target is a list of target nodes, env is the &consenv; to use for context. An emitter must return a tuple containing two lists, the list of targets to be built by this builder, and the list of sources for this builder. Example: def e(target, source, env): return (target + ['foo.foo'], source + ['foo.src']) # Simple association of an emitter function with a Builder. b = Builder("my_build < $TARGET > $SOURCE", emitter = e) def e2(target, source, env): return (target + ['bar.foo'], source + ['bar.src']) # Simple association of a list of emitter functions with a Builder. b = Builder("my_build < $TARGET > $SOURCE", emitter = [e, e2]) # Calling an emitter function through a &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 False, which means the builder can not be called multiple times for the same target file(s). Calling a builder multiple times for the same target simply adds additional source files to the target; it is not allowed to change the environment associated with the target, specify additional environment overrides, or associate a different builder with the target. env A &consenv; that can be used to fetch source code using this Builder. (Note that this environment is not used for normal builds of normal target files, which use the environment that was used to call the Builder for the target file.) generator A function that returns a list of actions that will be executed to build the target(s) from the source(s). The returned action(s) may be an Action object, or anything that can be converted into an Action object (see the next section). A function passed as generator must accept four arguments: source, target, env and for_signature. source is a list of source nodes, target is a list of target nodes, env is the &consenv; to use for context, for_signature is 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 False or some other non-true value. In this case, &scons; will use the suffix of the first specified source file to select the appropriate action from the action dictionary. In the following example, the setting of source_ext_match prevents &scons; from exiting with an error due to the mismatched suffixes of foo.in and foo.extra. b = Builder(action={'.in' : 'build $SOURCES > $TARGET'}, source_ext_match=False) env = Environment(BUILDERS={'MyBuild':b}) env.MyBuild('foo.out', ['foo.in', 'foo.extra']) env A &consenv; that can be used to fetch source code using this Builder. (Note that this environment is not used for normal builds of normal target files, which use the environment that was used to call the Builder for the target file.) b = Builder(action="build < $SOURCE > $TARGET") env = Environment(BUILDERS={'MyBuild' : b}) env.MyBuild('foo.out', 'foo.in', my_arg='xyzzy') chdir A directory from which scons will execute the action(s) specified for this Builder. If the chdir argument is a string or a directory Node, scons will change to the specified directory. If the chdir is not a string or Node and is non-zero, then scons will change to the target file's directory. Note that scons will not automatically modify its expansion of &consvars; like $TARGET and $SOURCE when using the chdir keyword argument--that is, the expanded file names will still be relative to the top-level directory containing the &SConstruct; file, and consequently incorrect relative to the chdir directory. Builders created using chdir keyword argument, will need to use &consvar; expansions like ${TARGET.file} and ${SOURCE.file} to use just the filename portion of the targets and source. b = Builder(action="build < ${SOURCE.file} > ${TARGET.file}", chdir=1) env = Environment(BUILDERS={'MyBuild' : b}) env.MyBuild('sub/dir/foo.out', 'sub/dir/foo.in') Python only keeps one current directory location even if there are multiple threads. This means that use of the chdir argument will not work with the SCons -j option, because individual worker threads spawned by SCons interfere with each other when they start changing directory. Any additional keyword arguments supplied when a Builder object is created (that is, when the &f-link-Builder; function is called) will be set in the executing construction environment when the Builder object is called. The canonical example here would be to set a &consvar; to the repository of a source code system. Any 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. The &f-link-Builder; factory function will turn its action keyword argument into an appropriate internal Action object, as will the &f-link-Command; function. You can also explicitly create Action objects for passing to &f-Builder;, or other functions that take actions as arguments, by calling the &f-link-Action; factory function. This may more efficient when multiple Builder objects need to do the same thing rather than letting each of those Builder objects create a separate Action object. It also allows more flexible configuration of an Action object. For example, to control the message printed when the action is taken you need to create the action object using &f-Action;. The &Action; factory function returns an appropriate object for the action represented by the type of the action argument (the first positional parmeter): If action is already an Action object, the object is simply returned. If action is a string, a command-line Action is returned. If such a string begins with @, the command line is not printed. If the string begins with hyphen (-), the exit status from the specified command is ignored, allowing execution to continue even if the command reports failure: Action('$CC -c -o $TARGET $SOURCES') # Doesn't print the line being executed. Action('@build $TARGET $SOURCES') # Ignores return value Action('-build $TARGET $SOURCES') If action is a list, then a list of Action objects is returned. An Action object is created as necessary for each element in the list. If an element within the list is itself a list, the embedded list is taken as the command and arguments to be executed via the command line. This allows white space to be enclosed in an argument rather than taken as a separator by defining a command in a list within a list: Action([['cc', '-c', '-DWHITE SPACE', '-o', '$TARGET', '$SOURCES']]) If action is a callable object, a Function Action is returned. The callable must accept three keyword arguments: target, source and env. target is a Node object representing the target file, source is a Node object representing the source file and env is the &consenv; used for building the target file. The target and source arguments may be lists of Node objects if there is more than one target file or source file. The actual target and source file name(s) may be retrieved from their Node objects via the built-in Python str function: target_file_name = str(target) source_file_names = [str(x) for x in source] The function should return 0 or None to indicate a successful build of the target file(s). The function may raise an exception or return a non-zero exit status to indicate an unsuccessful build. def build_it(target=None, source=None, env=None): # build the target from the source return 0 a = Action(build_it) If action is not one of the above types, no action object is generated and &f-Action; returns None. The environment method form &f-link-env-Action; will expand &consvars; in any argument strings, including action, at the time it is called, using the construction variables in the &consenv; through which it was called. The global function form &f-link-Action; delays variable expansion until the Action object is actually used. The optional second argument to &f-Action; is used to control the output which is printed when the Action is actually performed. If this parameter is omitted, or if the value is an empty string, a default output depending on the type of the action is used. For example, a command-line action will print the executed command. The following argument types are accepted: If output is a string, substitution is performed on the string before it is printed. 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. If output is a function, the function will be called to obtain a string describing the action being executed. The function must accept three keyword arguments: target, source and env, with the same interpretation as for a callable action argument above. If outputis None, output is suppressed entirely. Instead of using a positional argument, the cmdstr keyword argument may be used to specify the output string, or the strfunction keyword argument may be used to specify a function to return the output string. cmdstr=None suppresses output entirely. 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 If chdir is true (the default is False), &SCons; will change directories before executing the action. If the value of chdir is a string or a directory Node, &SCons; will change to the specified directory. Otherwise, if chdir evaluates true, &SCons; will change to the target file's directory. Note that &SCons; will not automatically modify its expansion of &consvars; like &cv-TARGET; and &cv-SOURCE; when using the chdir parameter - that is, the expanded file names will still be relative to the top-level directory containing the &SConstruct; file, and consequently incorrect relative to the chdir directory. Builders created using chdir keyword argument, will need to use &consvar; expansions like ${TARGET.file} and ${SOURCE.file} to use just the filename portion of the targets and source. Example: a = Action("build < ${SOURCE.file} > ${TARGET.file}", chdir=True) exitstatfunc If provided, must be a callable which accepts a single parameter, the exit status (or return value) from the specified action, and which returns an arbitrary or modified value. This can be used, for example, to specify that an Action object's return value should be ignored under special conditions and SCons should, therefore, consider that the action always succeeds. Example: def always_succeed(s): # Always return 0, which indicates success. return 0 a = Action("build < ${SOURCE.file} > ${TARGET.file}", exitstatfunc=always_succeed) batch_key If provided, indicates that the Action can create multiple target files by processing multiple independent source files simultaneously. (The canonical example is "batch compilation" of multiple object files by passing multiple source files to a single invocation of a compiler such as Microsoft's Visual C / C++ compiler.) If the batch_key argument evaluates True and is not a callable object, the configured Action object will cause &scons; to collect all targets built with the Action object and configured with the same &consenv; into single invocations of the Action object's command line or function. Command lines will typically want to use the &cv-CHANGED_SOURCES; &consvar; (and possibly &cv-CHANGED_TARGETS; as well) to only pass to the command line those sources that have actually changed since their targets were built. Example: a = Action('build $CHANGED_SOURCES', batch_key=True) The batch_key argument may also be a callable function that returns a key that will be used to identify different "batches" of target files to be collected for batch building. A batch_key function must accept four parameters: action, env, target and source. The first parameter, action, is the active action object. The second parameter, env, is the &consenv; configured for the target. The target and source parameters are the lists of targets and sources for the configured action. The returned key should typically be a tuple of values derived from the arguments, using any appropriate logic to decide how multiple invocations should be batched. For example, a batch_key function may decide to return the value of a specific &consvar; from env which will cause &scons; to batch-build targets with matching values of that &consvar;, or perhaps return the Python id() of the entire &consenv;, in which case &scons; will batch-build all targets configured with the same &consenv;. Returning None indicates that the particular target should not be part of any batched build, but instead will be built by a separate invocation of action's command or function. Example: def batch_key(action, env, target, source): tdir = target[0].dir if tdir.name == 'special': # Don't batch-build any target # in the special/ subdirectory. return None return (id(action), id(env), tdir) a = Action('build $CHANGED_SOURCES', batch_key=batch_key) &SCons; supplies Action functions that arrange for various common file and directory manipulations to be performed. These are similar in concept to "tasks" in the &Ant; build tool, although the implementation is slightly different. These functions do not actually perform the specified action at the time the function is called, but rather are factory functions which return an Action object that can be executed at the appropriate time. There are two natural ways that these Action Functions are intended to be used. First, if you need to perform the action at the time the SConscript file is being read, you can use the &f-link-Execute; global function: Execute(Touch('file')) Second, you can use these functions to supply Actions in a list for use by the &f-link-env-Command; method. This can allow you to perform more complicated sequences of file manipulation without relying on platform-specific external commands: env = Environment(TMPBUILD='/tmp/builddir') env.Command( target='foo.out', source='foo.in', action=[ Mkdir('$TMPBUILD'), Copy('$TMPBUILD', '${SOURCE.dir}'), "cd $TMPBUILD && make", Delete('$TMPBUILD'), ], ) Chmod(dest, mode) Returns an Action object that changes the permissions on the specified dest file or directory to the specified mode which can be octal or string, similar to the 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")]) The behavior of Chmod is limited on Windows, see the notes in the Python documentation for os.chmod, which is the underlying function. Copy(dest, src) Returns an Action object that will copy the src source file or directory to the dest destination file or directory. Examples: Execute(Copy('foo.output', 'foo.input')) env.Command('bar.out', 'bar.in', Copy('$TARGET', '$SOURCE')) Delete(entry, [must_exist]) Returns an Action that deletes the specified entry, which may be a file or a directory tree. If a directory is specified, the entire directory tree will be removed. If the must_exist flag is set to a true value, then a Python error will be raised if the specified entry does not exist; the default is false, that is, the Action will silently do nothing if the entry does not exist. Examples: Execute(Delete('/tmp/buildroot')) env.Command( 'foo.out', 'foo.in', action=[ Delete('${TARGET.dir}'), MyBuildAction, ], ) Execute(Delete('file_that_must_exist', must_exist=True)) Mkdir(name) Returns an Action that creates the directory name and all needed intermediate directories. name may also be a list of directories to create. Examples: Execute(Mkdir('/tmp/outputdir')) env.Command( 'foo.out', 'foo.in', action=[ Mkdir('/tmp/builddir'), Copy('/tmp/builddir/foo.in', '$SOURCE'), "cd /tmp/builddir && make", Copy('$TARGET', '/tmp/builddir/foo.out'), ], ) Move(dest, src) Returns an Action that moves the specified src file or directory to the specified dest file or directory. Examples: Execute(Move('file.destination', 'file.source')) env.Command( 'output_file', 'input_file', action=[MyBuildAction, Move('$TARGET', 'file_created_by_MyBuildAction')], ) Touch(file) Returns an Action that updates the modification time on the specified file. Examples: Execute(Touch('file_to_be_touched')) env.Command('marker', 'input_file', action=[MyBuildAction, Touch('$TARGET')]) Before executing a command, &scons; performs variable substitution on the string that makes up the action part of the builder. Variables to be interpolated are indicated in the string with a leading $, to distinguish them from plain text which is not to be substituted. The name may be surrounded by curly braces (${}) to separate the name from surrounding characters if necessary. Curly braces are required when you use Python list subscripting/slicing notation on a variable to select one or more items from a list, or access a variable's special attributes, or use Python expression substitution. Besides regular &consvars;, scons provides the following special variables for use in expanding commands: &cv-CHANGED_SOURCES; The file names of all sources of the build command that have changed since the target was last built. &cv-CHANGED_TARGETS; The file names of all targets that would be built from sources that have changed since the target was last built. &cv-SOURCE; The file name of the source of the build command, or the file name of the first source if multiple sources are being built. &cv-SOURCES; The file names of the sources of the build command. &cv-TARGET; The file name of the target being built, or the file name of the first target if multiple targets are being built. &cv-TARGETS; The file names of all targets being built. &cv-UNCHANGED_SOURCES; The file names of all sources of the build command that have not changed since the target was last built. &cv-UNCHANGED_TARGETS; The file names of all targets that would be built from sources that have not changed since the target was last built. These names are reserved and may not be assigned to or used as &consvars;. For example, the following builder call: env = Environment(CC='cc') env.Command( target=['foo'], source=['foo.c', 'bar.c'], action='@echo $CC -c -o $TARGET $SOURCES' ) would produce the following output: cc -c -o foo foo.c bar.c In the previous example, a string ${SOURCES[1]} would expand to: bar.c. A variable name may have the following modifiers appended within the enclosing curly braces to access properties of the interpolated string. These are known as special attributes. base - The base path of the file name, including the directory path but excluding any suffix. dir - The name of the directory in which the file exists. file - The file name, minus any directory portion. filebase - Like file but minus its suffix. suffix - Just the file suffix. abspath - The absolute path name of the file. relpath - The path name of the file relative to the root SConstruct file's directory. posix - The path with directories separated by forward slashes (/). Sometimes necessary on Windows systems when a path references a file on other (POSIX) systems. windows - The path with directories separated by backslashes (\\). Sometimes necessary on POSIX-style systems when a path references a file on other (Windows) systems. win32 is a (deprecated) synonym for windows. srcpath - The directory and file name to the source file linked to this file through &f-VariantDir;(). If this file isn't linked, it just returns the directory and filename unchanged. srcdir - The directory containing the source file linked to this file through &f-VariantDir;(). If this file isn't linked, it just returns the directory part of the filename. rsrcpath - The directory and file name to the source file linked to this file through &f-VariantDir;(). If the file does not exist locally but exists in a Repository, the path in the Repository is returned. If this file isn't linked, it just returns the directory and filename unchanged. rsrcdir - The Repository directory containing the source file linked to this file through &VariantDir;(). If this file isn't linked, it just returns the directory part of the filename. For example, the specified target will expand as follows for the corresponding modifiers: $TARGET => sub/dir/file.x ${TARGET.base} => sub/dir/file ${TARGET.dir} => sub/dir ${TARGET.file} => file.x ${TARGET.filebase} => file ${TARGET.suffix} => .x ${TARGET.abspath} => /top/dir/sub/dir/file.x ${TARGET.relpath} => sub/dir/file.x $TARGET => ../dir2/file.x ${TARGET.abspath} => /top/dir2/file.x ${TARGET.relpath} => ../dir2/file.x SConscript('src/SConscript', variant_dir='sub/dir') $SOURCE => sub/dir/file.x ${SOURCE.srcpath} => src/file.x ${SOURCE.srcdir} => src Repository('/usr/repository') $SOURCE => sub/dir/file.x ${SOURCE.rsrcpath} => /usr/repository/src/file.x ${SOURCE.rsrcdir} => /usr/repository/src Some modifiers can be combined, like ${TARGET.srcpath.base), ${TARGET.file.suffix}, etc. The curly brace notation may also be used to enclose a Python expression to be evaluated. See below for a description. A variable name may also be a 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") As a reminder, this evaluation happens when $BAR is actually used in a builder action. The value of env['BAR'] will be exactly as it was set: "$FOO baz". You can use this feature to pass arguments to a Python function by 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 If a substitutable expression using the notation ${something} does not appear to match one of the other substitution patterns, it is evaluated as a Python expression. This uses Python's eval function, with the globals parameter set to the current environment's set of &consvars;, and the result substituted in. So in the following case: env.Command( 'foo.out', 'foo.in', "echo ${COND==1 and 'FOO' or 'BAR'} > $TARGET" ) the command executed will be either echo FOO > foo.out or echo BAR > foo.out according to the current value of env['COND'] when the command is executed. The evaluation takes place when the target is being built, not when the SConscript is being read. So if env['COND'] is changed later in the SConscript, the final value will be used. Here's a more complete example. Note that all of COND, FOO, and BAR are &consvars;, and their values are substituted into the final command. FOO is a list, so its elements are interpolated separated by spaces. env=Environment() env['COND'] = 1 env['FOO'] = ['foo1', 'foo2'] env['BAR'] = 'barbar' env.Command( 'foo.out', 'foo.in', "echo ${COND==1 and FOO or BAR} > $TARGET" ) will execute: echo foo1 foo2 > foo.out In point of fact, Python expression evaluation is how the special attributes are substituted: they are simply attributes of the Python objects that represent &cv-TARGET;, &cv-SOURCES;, etc., which &SCons; passes to eval which returns the value. &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. Use of the Python eval function is considered to have security implications, since, depending on input sources, arbitrary unchecked strings of code can be executed by the Python interpreter. Although &SCons; makes use of it in a somewhat restricted context, you should be aware of this issue when using the ${python-expression-for-subst} form. Scanner objects are used to scan specific file types for implicit dependencies. &SCons; has a number of pre-built Scanner objects, so it is usually only necessary to set up Scanners for new file types. You do this by calling the &f-link-Scanner; function. The &f-Scanner; function accepts the following arguments, only function is required, the rest are optional: function A Python function that will process a given Node (usually a file) and return a list of Nodes representing the implicit dependencies (file names) found in the contents. The function must accept three required arguments, node, env and path, and an optional fourth, arg. node is the internal &SCons; node representing the file to scan, env is the &consenv; to use during the scan, and path is a tuple of directories that can be searched for files, as generated by the optional path_function (see below). If argument was supplied when the Scanner object was created, it is given as arg when the function is called; since argument is optional, the default is no arg. The function can use 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 file's contents as text. Note that the file is not guaranteed to exist at the time the scanner is called (it could be a generated file, not generated yet), so the scanner function must be tolerant of that. name The name to use for the Scanner. This is mainly used to identify the Scanner internally. The default value is "NONE". argument If specified, will be passed to the scanner function function and the path function path_function when called, as the additional argument each of those functions takes. skeys Scanner key(s) indicating the file types this scanner is associated with. Used internally to select an appropriate scanner. In the usual case of scanning for file names, this argument will be a list of suffixes for the different file types that this Scanner knows how to scan. If skeys is a string, it will be expanded into a list by the current environment. path_function A Python function that takes four or five arguments: a &consenv;, a Node for the directory containing the SConscript file in which the first target was defined, a list of target nodes, a list of source nodes, and the value of argument if it was supplied when the scanner was created. Must return a tuple of directories that can be searched for files to be returned by this Scanner object. (Note that the &f-link-FindPathDirs; function can be used to return a ready-made path_function for a given &consvar; name, instead of having to write your own function from scratch.) node_class The class of Node that should be returned by this Scanner object. Any strings or other objects returned by the scanner function that are not of this class will be run through the function supplied by the node_factory argument. A value of None can be supplied to indicate no conversion; the default is to return File nodes. node_factory A Python function that will take a string or other object and turn it into the appropriate class of Node to be returned by this Scanner object, as indicated by node_class. scan_check A Python function that takes two arguments, a Node (file) and a &consenv;, and returns whether the Node should, in fact, be scanned for dependencies. This check can be used to eliminate unnecessary calls to the scanner function when, for example, the underlying file represented by a Node does not yet exist. recursive Specifies whether this scanner should be re-invoked on the dependency files returned by the scanner. If omitted, the Node subsystem will only invoke the scanner on the file being scanned and not recurse. Recursion is needed when the files returned by the scanner may themselves contain further file dependencies, as in the case of preprocessor #include lines. A value that evaluates true enables recursion; recursive may be a callable function, in which case it will be called with a list of Nodes found and should return a list of Nodes that should be scanned recursively; this can be used to select a specific subset of Nodes for additional scanning. 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']) &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. &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. &scons; handles upper-case Fortran file suffixes 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 as a Fortran source file that is to be first run through the standard C preprocessor, while the lower-case version is not. This matches the convention of gfortran, which may also be followed by other Fortran compilers. This also applies to other naming variants, .FOR, .FTN, .F90, .F95, .F03 and .F08; files suffixed with .FPP and .fpp are both run through the preprocessor, as indicated by the pp part of the name. 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. Run through the C preprocessor here means that a different set of &consvars; will be applied in constructed commands, for example &cv-link-FORTRANPPCOM; and &cv-link-FORTRANPPCOMSTR; instead of &cv-link-FORTRANCOM; and &cv-link-FORTRANCOMSTR;. See the Fortran-related &consvars; for more details. 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 Cygwin's &gcc; for compiling, 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;. On Windows, if &scons; is executed via a wrapper scons.bat batch file, there are (at least) two ramifications. Note this is no longer the default - &scons; installed via Python's pip installer will have an scons.exe which does not have these limitations: First, Windows command-line users that want to use variable assignment on the command line may have to put double quotes around the assignments, otherwise the Windows command shell will consume those as arguments to itself, not to &scons;: scons "FOO=BAR" "BAZ=BLEH" Second, the Cygwin shell does not reognize typing scons at the command line prompt as referring to this weapper. You can work around this either by executing scons.bat (including the extension) from the Cygwin command line, or by creating a wrapper shell script named scons which invokes scons.bat. 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. In general, &scons; is not controlled by environment variables set in the shell used to invoke it, leaving it up to the SConscript file author to import those if desired. However the following variables are imported by &scons; itself if set: SCONS_LIB_DIR Specifies the directory that contains the &scons; Python module directory. Normally &scons; can deduce this, but in some circumstances, such as working with a source release, it may be necessary to specify (for example, /home/aroach/scons-src-0.01/src/engine). SCONSFLAGS A string containing options that will be used by &scons; in addition to those passed on the command line. Can be used to reduce frequent retyping of common options. The contents of SCONSFLAGS are considered before any passed command line options, so the command line can be used to override SCONSFLAGS options if necessary. SCONS_CACHE_MSVC_CONFIG (Windows only). If set, save the shell environment variables generated when setting up the Microsoft Visual C++ compiler (and/or Build Tools) to a cache file, to give these settings, which are relatively 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). 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) Originally: Steven Knight knight@baldmt.com and Anthony Roach aroach@electriceyeball.com. Since 2010: The SCons Development Team scons-dev@scons.org.