SCONS(1)

📦

version 4.11.1 · 11 versions

4.11.1 · arch rolling, fedora 44 (latest)
4.5.2 · opensuse-leap 16.0
4.5.2 · epel 9
4.8.1 · alpine 3.22
4.10.0 · alpine 3.23
4.0.1 · ubuntu jammy
4.9.1 · fedora 43
4.11.0 · epel 10, fedora 43, fedora 44
4.5.2 · ubuntu noble
4.10.1 · alpine 3.24, fedora 44
4.4.0 · debian bookworm

, in arch rolling, fedora 44

💅 SCONS(1) — the SCons manual, but make it make sense 💅

SCons 4.11.1 · manual page energy · bestie edition ✨

🌸 NAME 🌸

scons — a software construction tool 🛠️✨

🎀 SYNOPSIS 🎀

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

🦋 DESCRIPTION 🦋

okay so. SCons is an extensible open source build system, and what it does is orchestrate the construction of software — and honestly not just software, also other tangible products like documentation files, because it's versatile like that 💖. It figures out which component pieces actually need to be built or rebuilt, and then it invokes the necessary commands to build them. No cap.

SCons comes with a bunch of features that are genuinely giving developer productivity, like:

parallel builds 🔥
caching of build artifacts
automatic dependency scanning 👑
and a whole database of info about previous builds, so the details don't have to be recalculated every single run. Obsessed.

scons requires Python 3.7 or later to run. And bestie, there should be no other dependencies or requirements — unless you're using the experimental Ninja tool, which needs the ninja package. That's it, that's the whole requirement list 💅.

Changed in version 4.3.0: support for Python 3.5 is removed. The CPython project retired 3.5 in Sept 2020: https://peps.python.org/pep-0478

Changed in version 4.9.0: support for Python 3.6 is removed. The CPython project retired 3.6 in Sept 2021: https://peps.python.org/pep-0494

Changed in version 4.11.0: support for Python 3.7 is deprecated and will be removed in a future SCons release. The CPython project retired 3.7 in June 2023: https://peps.python.org/pep-0537

Changed in version 4.11.0: support for Python 3.8 is deprecated and will be removed in a future SCons release. The CPython project retired 3.8 in Sept 2024: https://peps.python.org/pep-0569

so here's the whole vibe of how you actually use this thing. You set up an SCons build by writing a script that describes the things you want to build (targets), and if necessary, the rules to build those files (actions). SCons ships with a collection of Builder methods that supply premade Actions for building loads of common software components — executable programs, object files, libraries, all of it 🫶. Which means for a lot of software projects, you literally only need to specify the targets and the input files (sources) in a call to a builder. That's it. Main character energy, honestly.

SCons operates at a level of abstraction above that of pure filenames. Like — example — if you specify a shared library target named "foo", SCons keeps track of the actual operating-system-dependent filename (so libfoo.so on a GNU/Linux system, foo.dll on Windows 🪟), and it gives you a handle to refer to that target in other steps. So you never have to hand-write system-specific strings yourself. Iconic behaviour.

SCons can also scan automatically for dependency information — think header files included by source code files, e.g. #include preprocessor directives in C or C++ files — so those implicit dependencies don't have to be specified manually 🙈. And you can define new scanners to support additional input file types, because of course you can ✨.

Information about the files involved in the build — including a cryptographic hash of the contents of source files — gets cached for later reuse. By default that hash (the content signature) is what's used to decide if a file has changed since the last build, though you can use other algorithms by selecting an appropriate Decider function. Implicit dependency files are also part of the out-of-date computation. And the scanned implicit dependency information can optionally be cached and used to speed up future builds 🔥. A hash of each executed build action (the build signature) is cached too, so changes to build instructions (changing flags, whatever) or to the build tools themselves (hello, compiler upgrade 👋) can also trigger a rebuild. It's thorough. It's giving diligence.

SCons supports separated source and build directories (also called "out-of-tree builds") through the definition of variant directories. Using a separated build directory keeps your source directory clean of artifacts when you're doing searches, lets you set up differing builds ("variants") without conflicts, and lets you reset the build by just removing the build directory. (Note that SCons does have a "clean" mode as well 🧼.) See the VariantDir description for more details.

When you invoke it, scons looks for a file describing the build configuration in the current directory and reads that in. By default that file is named SConstruct, although some variants of that name — or a developer-chosen name — are also accepted (see the section called "SConscript Files"). If it finds one, the current directory is set as the project top directory. Certain command-line options specify alternate places to look for SConstruct (see -C, -D, -u and -U), and those will set the project top directory to the path that was found. You can also specify a path to the build configuration with the -f option, which leaves the current directory as the project top directory 💅.

The build configuration may be split into multiple files: the SConstruct file can specify additional configuration files by calling the SConscript function, and any file thus invoked may include further files in the same way 🌀. By convention, these subsidiary files are named SConscript, although any name may be used. And because of that naming convention, the term SConscript files is used generically to refer to the complete set of configuration files for a project (yes, including the SConstruct file), regardless of the actual file names or how many there are.

A hierarchical build is not recursive — all the SConscript files are processed in a single pass, so that scons has a picture of the complete dependency tree when it begins considering what needs building 🌈. Each SConscript file is processed in a separate context, so settings made in one script don't leak into another. Information can however be shared explicitly between scripts. Boundaries, but consensual ones.

Before reading the SConscript files, scons looks for a site directory — a directory named site_scons is searched for in various system directories and in the project top directory, or, if the --site-dir option is given, it checks only for that directory 👀. Found site directories are prepended to the Python module search path (sys.path), which means modules in such directories can be imported the normal Python way in SConscript files.

For each found site directory:

if it contains a file site_init.py, that file is evaluated, and
if it contains a directory site_tools, the path to that directory is prepended to the default toolpath.

See the --site-dir and --no-site-dir options for details on default paths and controlling the site directories 💖.

SConscript files are written in the Python programming language 🐍. For many tasks the simple syntax can be understood from examples, so it's normally not necessary to be a Python programmer to use SCons effectively. The SConscript files are executed in a context that makes the facilities described in this manual page directly available — that is, no need to import anything. Standard Python scripting capabilities like flow control, data manipulation, and imported Python modules are all available for more complicated build configurations ✨. Other Python files can be made part of the build system, but they don't automatically get the SCons context and need to import it if they want access (described later).

SCons reads and executes all of the included SConscript files before it begins building any targets. Progress messages show this behaviour — the state change lines, those beginning with the scons: tag, may be suppressed using the -Q option:

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

okay now, to assure reproducible builds, SCons uses a restricted execution environment for running the external commands used to build targets, rather than propagating the full environment that was in effect when scons was called 😤. This helps avoid problems like:

picking up accidental or malicious settings 💀
temporary debug values that are no longer needed
a developer having different settings than another developer (or than the CI pipeline 😭)

Environment variables needed for those commands to work properly must be set in the execution environment explicitly — either by assigning the desired values, or by picking those values individually or collectively out of the environment variables exposed by the Python os.environ dictionary (and since they're external program inputs, they should be validated before use 👑). The execution environment for a given construction environment is its $ENV value. A small number of environment variables are picked up automatically by scons itself (see the section called "ENVIRONMENT").

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

One example approach is to extract the entire PATH environment variable and set that into the execution environment:

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

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

import os

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

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

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

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

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

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

so those variables are all sitting there in the ARGUMENTS dictionary, and bestie you can use them in the SConscript files to change the build any way you want:

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

and the command-line variable arguments also show up in the ARGLIST list, indexed by their order on the command line 🫶 so if you need to process them in order instead of by name, that's your girl. Every ARGLIST entry is a tuple with the name and the value in it. iykyk.

peep the section called "Command-Line Construction Variables" for more on that 💖

okay so scons can also keep a cache of target (derived) files that gets shared between multiple builds ✨ when derived-file caching is enabled in an SConscript file, any target files built by scons get copied to the cache. And if an up-to-date target file is already in the cache? it gets retrieved from the cache instead of being rebuilt locally, no cap. Caching behavior can be disabled and controlled in other ways by the --cache-force, --cache-disable, --cache-readonly, and --cache-show command-line options. and the --random option is lowkey iconic for stopping multiple builds from all trying to update the cache at the same time 💅

By default, scons goes looking for known programming tools on various systems and initializes itself based on whatever it finds. Here's the whole rundown, bestie, saving you the chaos:

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, the GCC tools, the LLVM/clang tools, and the PharLap ETS compiler.
On Windows systems 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 FreeBSD and OpenBSD, scons searches in order for the LLVM/clang tools, the GCC tool chain, and the Intel compiler tools.
On all other platforms, including POSIX (Linux and UNIX) and macOS platforms, scons searches in order for the GCC tool chain, the LLVM/clang tools, and the Intel compiler tools. 🌈

The default tool selection can be pre-empted through the use of the tools argument to construction environment creation methods, by explicitly calling the Tool loader, or through the setting of various construction variables. periodt.

🎯 Target Selection 🎯

SCons acts on the selected targets, whether the requested operation is build, no-exec or clean. Targets get selected like this:

Targets specified on the command line. These may be files, directories, or phony targets defined using the 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 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 directory for target scanning are present (-C, -D, -u, -U). Since targets thus selected were not the result of user instructions, this target list is not made available for direct inspection; use the --debug=explain option if they need to be examined.
scons always adds to the selected targets any intermediate targets which are necessary to build the specified ones. For example, if constructing a shared library or dll from C source files, scons will also build the object files which will make up the library. 💅

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

scons .

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

scons /

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

scons C:\ D:\

A subset of a hierarchical tree may be built by remaining at the project top directory and specifying the subdirectory as the target to build:

scons src/subdir

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

cd src/subdir
scons -u .

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

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

scons -c .

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

scons -c build export

to remove target files under build and export. Additional files or directories to remove can be specified using the Clean function in the SConscript files. Conversely, targets that would normally be removed by the -c invocation can be retained by calling the NoClean function with those targets. ✨

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

scons -j 4

builds four targets in parallel, for example. 🔥

✨ OPTIONS ✨

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

-b — Ignored for compatibility with non-GNU versions of Make. (literally just vibes, it does nothing 🙈)
-c, --clean, --remove — Set clean mode. Clean up by removing the selected targets, as well as any files or directories associated with a selected target through calls to the Clean function. Will not remove any targets which are marked for preservation through calls to the 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 GetOption, as in the call:

if GetOption("clean"):

⚠️ fr fr, Python code in your SConscript files still runs in clean mode — protect it if that's a problem for you.

--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 standard output. The messages describe cache operations, such as which build signature is being searched for, retrieved, or stored in the cache specified by 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 allows temporarily disabling the cache without modifying build scripts. 🙈
--cache-force, --cache-populate — When using CacheDir, populate a derived-file cache by copying any existing, up-to-date derived files to it, in addition to files built during this invocation. This is useful for initializing a new cache with current derived files or adding files that were 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 update the cache with any files built during this invocation.
--cache-show — When using a derived-file cache, display 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 the cache. Without this option, scons shows a cache retrieval message. This ensures consistent output in build logs, regardless of whether the file was rebuilt or retrieved from the cache. 💅
--config=mode — Control how the Configure call should use or generate the results of configuration tests. mode should be 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 dependencies explicitly. This is the default behavior. ✨
- force — If this mode is specified, all configuration tests will be re-run regardless of whether the cached results are out-of-date. This can be used to explicitly force the configuration tests to be updated in response to an otherwise unconfigured change in a system header file or compiler.
- cache — If this mode is specified, no configuration tests will be rerun and all results will be taken from cache. scons will report an error if --config=cache is specified and a necessary test does not have any results in the cache. 💀
-C directory, --directory=directory — Run as if scons was started in directory instead of the current working directory. That is, change directory before searching for the SConstruct, Sconstruct, sconstruct, SConstruct.py, Sconstruct.py or sconstruct.py file or doing anything else. When multiple -C options are given, each subsequent non-absolute -C directory is interpreted relative to the preceding one. See also options -u, -U and -D to change the SConstruct search behavior when this option is used. 🌸
-D — Works exactly the same way as the -u option except for the way default targets are handled. When this option is used and no targets are specified on the command line, all default targets are built, whether or not they are below the current directory.
--debug=type[,type...] — Debug the build process. type specifies the kind of debugging info to emit. Multiple types may be specified, separated by commas. The following types are recognized:
- action-timestamps — Prints additional time profiling information. For each command, shows the absolute start and end times. This may be useful in debugging parallel builds. Implies the --debug=time option. ⭐

✨ New in version 3.1.

count — prints how many objects get created across the various classes SCons uses internally, before and after reading the SConscript files, and before and after building targets. Heads up though bestie 💀 this one 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 you're executing from *.pyo files).
duplicate — prints a line for every unlink/relink (or copy) of a file in a variant directory from its source file. It also throws in debugging info for unlinking stale variant directory files, plus unlinking old targets before they get built. 🦋
explain — prints an explanation of why scons is deciding to (re-)build the targets it selects for building. It's literally giving "why are we here" energy. 🔍
findlibs — instructs the scanner that searches for libraries to print a message about each potential library name it's searching for, and about the actual libraries it finds.
includes — prints the include tree after each top-level target is built. Generally used to find out what files are included by the sources of a given derived file:

    $ scons --debug=includes foo.o

json — writes info to a JSON file for any of the following debug options, if they're enabled: memory, count, time, action-timestamps.

The default output file is scons_stats.json

You can change the file name/path by using DebugOptions, for example DebugOptions(json='path/to/file.json')

    $ scons --debug=memory,json foo.o

memoizer — prints a summary of hits and misses using the Memoizer, an internal subsystem that counts how often SCons uses cached values in memory instead of recomputing them each time they're needed. 💅
memory — prints how much memory SCons uses before and after reading the SConscript files, and before and after building targets.
objects — prints a list of the various objects of the various classes used internally by SCons.
pdb — runs scons under the control of the pdb Python debugger. 🐛

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

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

    sys.path.append('.')

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

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

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

prepare — prints 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 — prints the raw command line used to build each target before the construction environment variables are substituted. Also shows which targets are being built by this command. Output looks something like this:

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

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 SConscript function

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

sconscript — enables output indicating entering and exiting each SConscript file.

--diskcheck=type — enables specific checks for whether or not there is a file on disk where the SCons configuration expects a directory (or the other way around) when it's searching for source and include files. type can be an available diskcheck type or the special tokens all or none. A comma-separated string can be used to select multiple checks. The default setting is all.

Current available checks are:

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

Disabling some or all of these checks can provide a performance boost for large configurations, or when the configuration will check for files and/or directories across networked or shared file systems — at the slight increased risk of an incorrect build or of not handling errors gracefully. ⚠️

--duplicate=ORDER — there are three ways to duplicate files in a build tree: hard links, soft (symbolic) links and copies. The default policy is to prefer hard links to soft links to copies. You can specify a different policy with this option. ORDER must be one of hard-soft-copy (the default), soft-hard-copy, hard-copy, soft-copy or copy. SCons will attempt to duplicate files using the mechanisms in the specified order. ✨
--enable-virtualenv — Import virtualenv-related variables to SCons.
--experimental=feature — enable experimental features and/or tools. feature can be an available feature name or the special tokens all or none. A comma-separated string can be used to select multiple features. The default setting is none.

Current available features are ninja (new in version 4.2) and legacy_sched_deprecated (new in, and deprecated since, version 4.11.0). 👑

Note The legacy scheduler is not strictly an experimental feature. The feature flag selects the job scheduler which was the SCons default prior to version 4.7. The feature flag was introduced as legacy_sched in version 4.7. The legacy scheduler is due to be removed in a future release, so the feature flag is now deprecated. In version 4.11.0, it was renamed to legacy_sched_deprecated, so that existing users will receive a signal — due to the nature of experimental feature flags it is not possible to use the standard SCons deprecation warning mechanism here.

Caution 🚨 Experimental features come with no compatibility promises — a given feature could change significantly in a future release, or disappear completely.

Option added in version 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 Help function), plus a line that refers to the standard SCons help message. If no local help message is defined, it prints the standard SCons help message (as for the -H option) plus help for any local options defined through 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.

New in version 4.1.

--hash-format=ALGORITHM — set the hashing algorithm used by SCons to ALGORITHM. This value determines the hashing algorithm used in generating content signatures, build signatures and CacheDir keys.

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

If you don't pass this option at all, SCons just vibes and picks the first supported hash format it can find. Usually that's MD5 bestie, but on a FIPS-compliant system running a Python older than 3.9, SHA1 or SHA256 gets picked as the default instead. Python 3.9 and onwards clients? They always default to MD5, even in FIPS mode. Periodt.

Specifying this option also changes the name of the SConsign database. The default database is .sconsign.dblite, but the second this option shows up, ALGORITHM gets baked into the name to show it's different — even if the argument is md5. Like, --hash-format=sha256 uses a SConsign database named .sconsign_sha256.dblite. Iconic behavior tbh.

New in version 4.1.

-H, --help-options — prints the standard help message about SCons command-line options and then dips out. That's it, that's the whole job.
-i, --ignore-errors — every single error from commands executed to rebuild files? Ignored. All of them. No cap, it does not care.
-I directory, --include-dir=directory — tells SCons where to look for imported Python modules. Stack up several -I options and it searches those directories in the exact order you listed them. Order matters, bestie. 🫶
--ignore-virtualenv — stops virtualenv-related variables from being imported into SCons. Not today, venv. 💅
--implicit-cache — caches your implicit dependencies. Instead of scanning files fresh every time, SCons reuses the implicit (scanned) dependencies from the last run. It can speed SCons up significantly, but there are limitations, and they are real:
- 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 entirely. Everything gets rescanned and recached. And heads up: this implies --implicit-cache.
--implicit-deps-unchanged — forces SCons to ignore changes in the implicit dependencies, so the cached ones are always used. Also implies --implicit-cache, in case you were wondering. 🌸
--install-sandbox=sandbox_path — when you're using the Install builders, this prepends sandbox_path to the installation paths so every installed file lands under that directory instead. Cute, contained, sandboxed. 🎀 But heads up: this option is unavailable if one of Install, InstallAs or InstallVersionedLib is not used in the SConscript files.
--interactive — starts SCons in interactive mode, aka the group chat of build tools. The SConscript files get read once, and then you get a scons>>> prompt. After that you can rebuild targets by typing commands at the interactive prompt, without having to re-read the SConscript files and re-initialize the dependency graph from scratch. Main character energy fr.

SCons interactive mode supports the following commands:

build [OPTIONS] [TARGETS] ... — builds the specified TARGETS (and their dependencies) with the specified SCons command-line OPTIONS. And yes, 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 you specify don't throw errors, they just do nothing for the build command — mainly because those options affect how the SConscript files are read, and that only happens once at the beginning of interactive mode. Sorry babe. 🙈

clean [OPTIONS] [TARGETS] ... — cleans the specified TARGETS (and their dependencies) with the specified OPTIONS. c is a synonym. And plot twist: this command is itself a synonym for build --clean.
exit — exits SCons interactive mode. You can also exit by terminating input (Ctrl+D on UNIX or Linux systems, Ctrl+Z on Windows systems). Say bye girlie. 👋
help [COMMAND] — gives you 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 given, it executes the interactive command interpreter specified in the SHELL environment variable (on UNIX and Linux systems) or the COMSPEC environment variable (on Windows systems). Also, sh and ! are synonyms.
version — prints SCons version information. Slay. ✨

An empty line repeats the last typed command. And command-line editing can be used if the readline module is available. Chef's kiss.

$ scons --interactive
scons: Reading SConscript files ...
scons: done reading SConscript files.
scons>>> build -n prog
scons>>> exit

-j N, --jobs=N — sets the maximum number of concurrent jobs (commands) to run. If there's more than one -j option floating around, the last one wins.
-k, --keep-going — keeps going as much as possible after an error. The target that failed and everything depending on it will not be remade, but the other targets you specified on the command line still get processed. Resilient queen. 👑
-m — ignored for compatibility with non-GNU versions of Make. It's just there, sitting quietly.
--max-drift=SECONDS — sets the maximum expected drift in the modification time of files to SECONDS. This value decides how long a file has to be unmodified before its cached content signature gets used instead of calculating a brand new content signature (hash) of the file's contents. The default is 2 days, meaning a file needs a modification time of at least two days ago to have its cached content signature used. A negative value means never cache the content signature and ignore any cached value that already exists. A value of 0 means always use the cached signature, no matter how old the file is. Choose your fighter. 🦋
--md5-chunksize=KILOBYTES — a deprecated synonym for --hash-chunksize.

Changed in version 4.2: deprecated.

-n, --no-exec, --just-print, --dry-run, --recon — sets no-exec mode. It prints the commands that would be executed to build any out-of-date targets, but does not actually execute them. ✨

Only target building is suppressed — any work in the build system that is done directly (in regular Python code) will still be carried out. You can add guards around code that shouldn't run in no-exec mode by checking the value of the option at run time with GetOption:

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

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

Also: SCons cannot perform Configure checks in no-exec mode, because they would make changes to the filesystem (see $CONFIGUREDIR and $CONFIGURELOG). It can use stored information from a previous build, if it's not out-of-date, so a "priming" build may make subsequent no-exec runs more useful.

--no-site-dir — do not read site directories. Neither the standard site directories (site_scons) nor the path specified via a previous --site-dir option get added to the module search path sys.path, searched for a site_init.py file, or have their site_tools directory included in the tool search path. Can be overridden by a subsequent --site-dir option, though. 💅
--package-type=type — the type of package to create when using the Package builder. Multiple types can be specified with a comma-separated string, and in that case SCons will try to build for all of those package types. Note this option is only available if the packaging tool has been enabled. 🎁
--profile=file — runs SCons under the Python profiler and saves the results to file. The results may then be analyzed using the Python pstats module. Data girlies rise. 📊
-q, --question — runs no commands and prints nothing. Just returns an exit status that's zero if the specified targets are already up-to-date, and non-zero otherwise. It's giving silent but deadly. 🤫
-Q — suppresses status messages about reading SConscript files, building targets and entering directories. Commands that are actually executed to rebuild target files are still printed, so you're not totally in the dark.
--random — builds dependencies in a random order. Useful when building multiple trees simultaneously with caching enabled, because it stops multiple builds from all trying to build or retrieve the same target files at the same time. Chaos, but make it strategic. 🎲
-s, --silent, --quiet — silent mode. Doesn't print the commands that are executed to rebuild target files, and also suppresses SCons status messages. Shhh. 🤐
-S, --no-keep-going, --stop — ignored for compatibility with GNU Make. (Yes, it's the opposite twin of -k. No, it's not doing anything about it.)
--site-dir=path — uses path as the site directory instead of searching the whole list of default site directories. That directory gets prepended to sys.path, the module path/site_init.py will be loaded if it exists, and path/site_tools gets included in the tool search path. And no, the option is not additive — give it more than once and the last path wins.

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

Windows:

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

ok so heads up bestie 💀 older versions of the docs listed a different path for the "system" site directory. It's still checked, but using it is discouraged, so like… don't:

%ALLUSERSPROFILE%/Application Data/scons/site_scons

Mac OS X:

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

Solaris:

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

Linux, HPUX, and other Posix-like systems:

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

✨ the rest of the options, we're so close 🫶

--stack-size=KILOBYTES — sets the stack size used to run threads, in KILOBYTES. This is literally the stack size of the threads that run your jobs, the ones executing the actions of the builders for the nodes that are out-of-date. Big caveat bestie: this option does nothing unless your number of concurrent build jobs is bigger than one (aka set by -j N or --jobs=N on the command line, or SetOption in a script).

go too small and you'll get stack overflow errors 😭 which usually show up as segmentation faults that make scons abort before it even builds anything. Go too big and scons eats more memory than it needs and might slow the whole build down. The default is a stack size of 256 kilobytes, which should be fine for basically everyone. You should not need to raise this value unless you're hitting stack overflow errors, periodt.

-t, --touch — ignored, kept around for compatibility with GNU Make. (Touching a file just to make it look up-to-date? Not a thing you need when you're using scons 💅)
--taskmastertrace=file — prints trace info to the file you name, showing how the internal Taskmaster object evaluates and controls the order in which Nodes are built. A file name of - means standard output, iconic.
--tree=type[,type...] — prints a tree of the dependencies after each top-level target is built. Some or all of the tree, in various formats, depending on the type you pick:
- all — print the entire dependency tree after each top-level target is built. That's the complete tree, including implicit dependencies and ignored dependencies.
- derived — restricts the tree output to only derived (target) files, no source files.
- linedraw — draws the tree output using Unicode line-drawing characters instead of plain ASCII text. This one acts as a modifier to the type(s) you selected. If you specify it alone, with no type at all, it behaves as if all had been specified.

New in version 4.0. ✨

status — prints status information for each displayed node.
prune — prunes the tree so we're not repeating dependency info for nodes that already showed up. Any node already displayed gets its name printed in [square brackets], which means "hey, the dependencies for this one are up higher in the tree, go look there."

You can stack multiple type choices, comma-separated:

# 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 it finds an SConstruct, Sconstruct, sconstruct, SConstruct.py, Sconstruct.py or sconstruct.py file, and uses that as the project top directory. And if you didn't name any targets on the command line, only targets at or below the current directory get built.
-U — works exactly the same way as -u, except for how default targets are handled. With this one, when no targets are specified on the command line, all default targets defined in the SConscript file(s) in the current directory get built, no matter what directory the resulting targets end up in. 😌
-v, --version — print the scons version, copyright info, list of authors, and any other relevant info. Then exit.
-w, --print-directory — prints a message with the working directory before and after other processing.
--no-print-directory — turns off -w, even if it got turned on implicitly. 🚫
--warn=type, --warn=no-type — enable or disable warnings (prefix with no- to disable). --warning is a synonym, btw. The type says which warnings you're toggling:
- all — all warnings.
- cache-version — warnings about the derived-file cache directory specified by CacheDir not using the latest configuration info. Enabled by default.
- cache-write-error — warnings about errors trying to write a copy of a built file to a derived-file cache specified by CacheDir. Disabled by default.
- cache-cleanup-error — warnings about errors when a file retrieved from the derived-file cache could not be removed.
- corrupt-sconsign — warnings about unfamiliar signature data in .sconsign files. Enabled by default.
- dependency — warnings about dependencies. Disabled by default.
- deprecated — warnings about use of currently deprecated features. Enabled by default. Careful tho: not all deprecation warnings can be disabled with --warn=no-deprecated, because some deprecated features that are late in the deprecation cycle may have been designated as mandatory warnings, and those 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 construction environments that use the same action. Enabled by default.
- fortran-cxx-mix — warnings about linking Fortran and C++ object files in a single executable, which can yield unpredictable behavior with some compilers. 💀
- future-reserved-variable — warnings about construction variables which are currently allowed, but will become reserved variables in a future release.
- future-deprecated — warnings about features that will be deprecated in the future. Disabled by default. Enabling future deprecation warnings is recommended for projects that redistribute SCons configurations for other users to build, so the project gets warned ASAP 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, in Builder calls. The correct spelling is the singular form, even though target and source can themselves refer to lists of names or nodes. 🙈
- 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.

bestie note: the no- prefix is part of the name of this warning. Add another -no to disable it. yes really. 😭

no-parallel-support — warnings about the version of Python not being able to support parallel builds when the -j option is used. Enabled by default.

same deal: the no- prefix is part of the name. Add another -no to disable.

python-version — warnings about running SCons using a version of Python that has been deprecated. Enabled by default.
reserved-variable — warnings about attempts to set the reserved construction variable names $CHANGED_SOURCES, $CHANGED_TARGETS, $TARGET, $TARGETS, $SOURCE, $SOURCES, $UNCHANGED_SOURCES or $UNCHANGED_TARGETS. Disabled by default.
stack-size — warnings about requests to set the stack size that could not be honored. Enabled by default.
target-not-built — warnings about a build rule not building the expected targets. Disabled by default.

-Y repository, --repository=repository, --srcdir=repository — search repository for any input and target files not found in the local directory hierarchy. You can stack multiple -Y options, and the repositories get searched in the order you gave them. See Repository for more info. 🌸

📜 SCONSCRIPT FILE REFERENCE 📜

🧚 SConscript Files 🧚

okay so your build config is described by one or more files, and we call them SConscript files. There has to be at least one for a valid build — scons will straight up quit if it doesn't find one, no cap.

By default, scons looks for this file under the name SConstruct, in the directory you ran scons from. But if necessary, it also looks for the alternative file names Sconstruct, sconstruct, SConstruct.py, Sconstruct.py and sconstruct.py, in that order. 🎀

You can point it at a totally different file name (which can include a pathname part) via the -f option.

here's the thing bestie: except for the SConstruct file, these files are not searched for automatically. You add extra configuration files to the build by calling the SConscript function. Which is lowkey iconic because it means parts of the build can be conditionally included or excluded at run-time, depending on how scons is invoked. 💅

Okay bestie, sit down, get comfy, this is the part where we talk about how all your SConscript files do their own little thing in their own little bubble 💖

Every SConscript file in a build configuration gets invoked independently in a separate context. This is giving ✨healthy boundaries✨ — it's there so different parts of your build don't accidentally step on each other's toes. You have to be explicit about sharing info, bestie. That means using the Export function or the exports argument to the SConscript function, plus the Return function in a called SConscript file, and then consuming that shared info with the Import function. No sneaky side-channel gossip, mmkay? 🙈

The following sections describe the various SCons facilities that can be used in SConscript files. Quick links, for the girlies who like to jump around:

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

🎀 Construction Environments 🎀

A Construction Environment is the basic means by which you communicate build information to SCons. It's literally the main character of your build setup, no cap. You make a brand new one with the Environment function:

env = Environment()

Construction environment attributes, called Construction Variables, can be set either by passing them as keyword arguments when the object is created, or by assigning them a value after the object already exists. These two are nominally equivalent, fr fr:

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

⚠️ Okay but here's the tea: certain settings that affect tool detection are only referenced when the tools get initialized. So you either gotta supply them as part of the call to Environment, or defer tool initialization. iykyk.

Like, say you're initializing the Microsoft Visual C++ version you wanna 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')

See how the middle one just… doesn't work? 💀 That's the deferred-init moment. Slay responsibly.

As a convenience, construction variables may also be set or modified by the parse_flags keyword argument during object creation. This has the effect of the 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 (like when you read them from a control file) or if the flags need to be distributed across a bunch of construction variables. env.ParseFlags describes how these arguments get distributed to construction variables:

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

This example adds 'include' to the $CPPPATH construction variable, 'EBUG' to $CPPDEFINES, and 'm' to $LIBS. 🫶

An existing construction environment can be duplicated by calling the env.Clone method. Without arguments, it'll be a copy with the same settings, chef's kiss. Otherwise, env.Clone takes the same arguments as Environment, and uses the arguments to create a modified copy.

SCons provides a special construction environment called the Default Environment. The default environment is used only for global functions — that is, build requests called without the context of a regular construction environment. See DefaultEnvironment for more info.

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

env = Environment(platform='cygwin')

Specifying a platform initializes the appropriate construction variables in the environment to use and generate file names with prefixes and suffixes appropriate for that platform. It's giving glow-up for a different OS. 🌈

💡 Note that the win32 platform adds the SystemDrive and SystemRoot variables from the user's external environment to the construction environment's ENV dictionary. This is so that any executed commands that use sockets to connect with other systems 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 a callable platform object returned by a call to Platform selecting a pre-defined platform, or it may be a user-supplied callable. In that last case, the Environment method will call it to update the new construction environment:

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

env = Environment(platform=my_platform)

🚨 Supplying a non-default platform or a custom function for initialization may bypass settings that should happen for the host system, and should be used with care. The place it really shines is when the platform is an alternative for the one that would be auto-detected — like 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. Peep the section called “Tools” for the deets. 👀

The optional variables keyword argument lets you pass a Variables object which will be used in the initialization of the construction environment. See the section called “Command-Line Construction Variables” for details.

🛠️ Tools 🛠️

SCons has so many included tool modules (more properly, tool specification modules) which are used to help initialize the construction environment before building, and you can write even more to suit a particular purpose, or add them from external sources (there's literally a repository of contributed tools, bestie). More info on writing custom tools lives in the Extending SCons section and specifically Tool Modules.

An SCons tool is only responsible for setup. Like, if an SConscript file declares it needs to construct an object file from a C-language source file by calling the Object builder, then a tool module representing an available C compiler needs to have run first — to set up that builder and all the construction variables it needs in the associated construction environment. The tool itself is not called in the process of the build. Tool setup happens when a construction environment is constructed, and in the basic case it needs zero intervention: platform-specific lists of default tools are used to examine the specific capabilities of that platform and configure the environment, skipping those tools which aren't applicable. ✨

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

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

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

If the tools argument is omitted, or if tools includes the reserved name 'default', then SCons will auto-detect usable tools, using the search path from the execution environment (that is, env['ENV']['PATH']) for looking up any external programs, and the platform name in effect to determine the default tools for that platform.

Heads up: the contents of PATH from the external environment os.environ is not used. And changing the PATH in the execution environment after the construction environment is constructed will not cause the tools to be re-detected. One and done, bestie. 💅

Tools can also be directly called by using the Tool method (see below).

SCons supports the following tool specifications out of the box:

🦋 `386asm`

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

Sets: $AS, $ASCOM, $ASFLAGS, $ASPPCOM, $ASPPFLAGS.
Uses: $CC, $CPPFLAGS, $_CPPDEFFLAGS, $_CPPINCFLAGS.

🦋 `aixc++`

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

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

🦋 `aixcc`

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

Sets: $CC, $CCVERSION, $SHCC.

🦋 `aixf77`

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

Sets: $F77, $SHF77.

🦋 `aixlink`

Sets construction variables for the IBM Visual Age linker.

Sets: $LINKFLAGS, $SHLIBSUFFIX, $SHLINKFLAGS.

🦋 `applelink`

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

Sets: $APPLELINK_COMPATIBILITY_VERSION, $APPLELINK_CURRENT_VERSION, $APPLELINK_NO_COMPATIBILITY_VERSION, $APPLELINK_NO_CURRENT_VERSION, $FRAMEWORKPATHPREFIX, $LDMODULECOM, $LDMODULEFLAGS, $LDMODULEPREFIX, $LDMODULESUFFIX, $LINKCOM, $SHLINKCOM, $SHLINKFLAGS, $_APPLELINK_COMPATIBILITY_VERSION, $_APPLELINK_CURRENT_VERSION, $_FRAMEWORKPATH, $_FRAMEWORKS.
Uses: $FRAMEWORKSFLAGS.

🦋 `ar`

Sets construction variables for the ar library archiver.

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

🦋 `as`

Sets construction variables for the as assembler.

Sets: $AS, $ASCOM, $ASFLAGS, $ASPPCOM, $ASPPFLAGS.
Uses: $CC, $CPPFLAGS, $_CPPDEFFLAGS, $_CPPINCFLAGS.

🦋 `bcc32`

Sets construction variables for the bcc32 compiler.

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

🦋 `cc`

Sets construction variables for generic POSIX C compilers.

Sets: $CC, $CCCOM, $CCDEPFLAGS, $CCFLAGS, $CFILESUFFIX, $CFLAGS, $CPPDEFPREFIX, $CPPDEFSUFFIX, $FRAMEWORKPATH, $FRAMEWORKS, $INCPREFIX, $INCSUFFIX, $SHCC, $SHCCCOM, $SHCCFLAGS, $SHCFLAGS, $SHOBJSUFFIX.
Uses: $CCCOMSTR, $PLATFORM, $SHCCCOMSTR.

🦋 `clang`

Set construction variables for the Clang C compiler.

Sets: $CC, $CCDEPFLAGS, $CCVERSION, $SHCCFLAGS.

🦋 `clangxx`

Set construction variables for the Clang C++ compiler.

Sets: $CXX, $CXXVERSION, $SHCXXFLAGS, $SHOBJSUFFIX, $STATIC_AND_SHARED_OBJECTS_ARE_THE_SAME.

🦋 `compilation_db`

Sets up CompilationDatabase builder which generates a clang tooling compatible compilation database.

Sets: $COMPILATIONDB_COMSTR, $COMPILATIONDB_PATH_FILTER, $COMPILATIONDB_USE_ABSPATH.

🦋 `cvf`

Sets construction variables for the Compaq Visual Fortran compiler.

Sets: $FORTRAN, $FORTRANCOM, $FORTRANMODDIR, $FORTRANMODDIRPREFIX, $FORTRANMODDIRSUFFIX, $FORTRANPPCOM, $OBJSUFFIX, $SHFORTRANCOM, $SHFORTRANPPCOM.

Uses: $CPPFLAGS, $FORTRANFLAGS, $SHFORTRANFLAGS, $_CPPDEFFLAGS, $_FORTRANINCFLAGS, $_FORTRANMODFLAG.

🌸 cXX 🌸

okay so this one wires up all the construction variables for your generic POSIX C++ compilers. nothing spicy, just the plumbing bestie 💅

Sets: $CPPDEFPREFIX, $CPPDEFSUFFIX, $CXX, $CXXCOM, $CXXFILESUFFIX, $CXXFLAGS, $INCPREFIX, $INCSUFFIX, $OBJSUFFIX, $SHCXX, $SHCXXCOM, $SHCXXFLAGS, $SHOBJSUFFIX.

Uses: $CXXCOMSTR, $SHCXXCOMSTR.

🐧 cyglink 🐧

sets construction variables for the cygwin linker/loader. cygwin girlies rise 🫶

Sets: $IMPLIBPREFIX, $IMPLIBSUFFIX, $LDMODULEVERSIONFLAGS, $LINKFLAGS, $RPATHPREFIX, $RPATHSUFFIX, $SHLIBPREFIX, $SHLIBSUFFIX, $SHLIBVERSIONFLAGS, $SHLINKCOM, $SHLINKFLAGS, $_LDMODULEVERSIONFLAGS, $_SHLIBVERSIONFLAGS.

✨ default ✨

sets construction variables for a default list of Tool modules.

⚠️ okay listen — use default in your tools list if you want to keep the original defaults, because the tools parameter is treated as a literal statement of the tools to be made available in that construction environment. it's not an addition, bestie, it's a whole replacement. no cap.

so the default tool list? not static. it depends on your platform and on what software you actually have installed. some tools won't even initialize if the underlying command isn't found, and some tools get picked from a list of choices on a first-found basis. want to see what you ended up with? peek at the $TOOLS construction variable in the construction environment 👀

on all platforms, the tools from this list get selected if their respective conditions are met: filesystem;, wix, lex, yacc, rpcgen, swig, jar, javac, javah, rmic, dvipdf, dvips, gs, tex, latex, pdflatex, pdftex, tar, zip, textfile.

on Linux systems, the default tools list selects (first-found):

a C compiler from gcc, intelc, icc, cc
a C++ compiler from g++, intelc, icc, cXX
an assembler from gas, nasm, masm
a linker from gnulink, ilink
a Fortran compiler from gfortran, g77, ifort, ifl, f95, f90, f77
and a static archiver ar

it also selects all found from the list m4, rpm.

on Windows systems, the default tools list selects (first-found):

a C compiler from msvc, mingw, gcc, intelc, icl, icc, cc, bcc32
a C++ compiler from msvc, intelc, icc, g++, cXX, bcc32
an assembler from masm, nasm, gas, 386asm
a linker from mslink, gnulink, ilink, linkloc, ilink32
a Fortran compiler from gfortran, g77, ifl, cvf, f95, f90, fortran
and a static archiver from mslib, ar, tlib

it also selects all found from the list msvs, midl.

on MacOS systems, the default tools list selects (first-found):

a C compiler from gcc, cc
a C++ compiler from g++, cXX
an assembler as
a linker from applelink, gnulink
a Fortran compiler from gfortran, f95, f90, g77
and a static archiver ar

it also selects all found from the list m4, rpm.

on the BSD systems whose base compiler is LLVM/clang (FreeBSD and OpenBSD), the default tools list matches the Linux one except that the C compiler is selected (first-found) from clang, gcc, intelc, icc, cc and the C++ compiler from clangxx, g++, intelc, icc, cXX.

default lists for other platforms? go examine the scons source code, it's right there in SCons/Tool/__init__.py 🕵️‍♀️

🍓 dmd 🍓

sets construction variables for the D language compiler DMD. yes we support D, we contain multitudes 💜

Sets: $DC, $DCOM, $DDEBUG, $DDEBUGPREFIX, $DDEBUGSUFFIX, $DFILESUFFIX, $DFLAGPREFIX, $DFLAGS, $DFLAGSUFFIX, $DINCPREFIX, $DINCSUFFIX, $DLIB, $DLIBCOM, $DLIBDIRPREFIX, $DLIBDIRSUFFIX, $DLIBFLAGPREFIX, $DLIBFLAGSUFFIX, $DLIBLINKPREFIX, $DLIBLINKSUFFIX, $DLINK, $DLINKCOM, $DLINKFLAGPREFIX, $DLINKFLAGS, $DLINKFLAGSUFFIX, $DPATH, $DRPATHPREFIX, $DRPATHSUFFIX, $DVERPREFIX, $DVERSIONS, $DVERSUFFIX, $SHDC, $SHDCOM, $SHDLIBVERSIONFLAGS, $SHDLINK, $SHDLINKCOM, $SHDLINKFLAGS.

📚 docbook 📚

this tool is doing the absolute most to make working with Docbook in SCons a little easier 🫶 it hands you several toolchains for creating different output formats, like HTML or PDF. inside the package there's a distribution of the Docbook XSL stylesheets as of version 1.76.1. and as long as you don't specify your own stylesheets for customization, these official versions get picked as default... which should reduce the inevitable setup hassles for you. iconic behaviour, honestly ✨

implicit dependencies to images and XIncludes get detected automatically if you meet the HTML requirements. the additional stylesheet utils/xmldepend.xsl by Paul DuBois is used for this purpose 🌈

⚠️ note, that there is no support for XML catalog resolving offered! this tool calls the XSLT processors and PDF renderers with the stylesheets you specified, that's it. the rest lies in your hands and you still have to know what you're doing when resolving names via a catalog. iykyk 💀

for activating the tool docbook, you have to add its name to the Environment constructor, like this:

env = Environment(tools=['docbook'])

on its startup, the docbook tool tries to find a required xsltproc processor, and a PDF renderer, e.g. fop. so make sure that these are added to your system's environment PATH and can be called directly without specifying their full path 👑

for the most basic processing of Docbook to HTML, you need to have installed

the Python lxml binding to libxml2, or
a standalone XSLT processor, currently detected are xsltproc, saxon, saxon-xslt and xalan.

rendering to PDF requires you to have one of the applications fop or xep installed.

creating a HTML or PDF document is very simple and straightforward. say

env = Environment(tools=['docbook'])
env.DocbookHtml('manual.html', 'manual.xml')
env.DocbookPdf('manual.pdf', 'manual.xml')

to get both outputs from your XML source manual.xml. as a shortcut, you can give the stem of the filenames alone, like this:

env = Environment(tools=['docbook'])
env.DocbookHtml('manual')
env.DocbookPdf('manual')

and get the same result. target and source lists are also supported:

env = Environment(tools=['docbook'])
env.DocbookHtml(['manual.html','reference.html'], ['manual.xml','reference.xml'])

or even

env = Environment(tools=['docbook'])
env.DocbookHtml(['manual','reference'])

Important whenever you leave out the list of sources, you may not specify a file extension! the Tool uses the given names as file stems, and adds the suffixes for target and source files accordingly. don't try it, it will not go well 🙈

the rules given above are valid for the Builders DocbookHtml, DocbookPdf, DocbookEpub, DocbookSlidesPdf and DocbookXInclude. for the DocbookMan transformation you can specify a target name, but the actual output names are automatically set from the refname entries in your XML source.

the Builders DocbookHtmlChunked, DocbookHtmlhelp and DocbookSlidesHtml are special, in that:

they create a large set of files, where the exact names and their number depend on the content of the source file, and
the main target is always named index.html, i.e. the output name for the XSL transformation is not picked up by the stylesheets.

as a result, there is simply no use in specifying a target HTML name. so the basic syntax for these builders is always:

env = Environment(tools=['docbook'])
env.DocbookHtmlhelp('manual')

if you want to use a specific XSL file, you can set the additional xsl parameter to your Builder call as follows:

env.DocbookHtml('other.html', 'manual.xml', xsl='html.xsl')

since this may get tedious if you always use the same local naming for your customized XSL files, e.g. html.xsl for HTML and pdf.xsl for PDF output, a set of variables for setting the default XSL name is provided. these are:

DOCBOOK_DEFAULT_XSL_HTML
DOCBOOK_DEFAULT_XSL_HTMLCHUNKED
DOCBOOK_DEFAULT_XSL_HTMLHELP
DOCBOOK_DEFAULT_XSL_PDF
DOCBOOK_DEFAULT_XSL_EPUB
DOCBOOK_DEFAULT_XSL_MAN
DOCBOOK_DEFAULT_XSL_SLIDESPDF
DOCBOOK_DEFAULT_XSL_SLIDESHTML

and you can set them when constructing your environment:

env = Environment(
    tools=['docbook'],
    DOCBOOK_DEFAULT_XSL_HTML='html.xsl',
    DOCBOOK_DEFAULT_XSL_PDF='pdf.xsl',
)
env.DocbookHtml('manual')  # now uses html.xsl

Sets: $DOCBOOK_DEFAULT_XSL_EPUB, $DOCBOOK_DEFAULT_XSL_HTML, $DOCBOOK_DEFAULT_XSL_HTMLCHUNKED, $DOCBOOK_DEFAULT_XSL_HTMLHELP, $DOCBOOK_DEFAULT_XSL_MAN, $DOCBOOK_DEFAULT_XSL_PDF, $DOCBOOK_DEFAULT_XSL_SLIDESHTML, $DOCBOOK_DEFAULT_XSL_SLIDESPDF, $DOCBOOK_FOP, $DOCBOOK_FOPCOM, $DOCBOOK_FOPFLAGS, $DOCBOOK_XMLLINT, $DOCBOOK_XMLLINTCOM, $DOCBOOK_XMLLINTFLAGS, $DOCBOOK_XSLTPROC, $DOCBOOK_XSLTPROCCOM, $DOCBOOK_XSLTPROCFLAGS, $DOCBOOK_XSLTPROCPARAMS.

Uses: $DOCBOOK_FOPCOMSTR, $DOCBOOK_XMLLINTCOMSTR, $DOCBOOK_XSLTPROCCOMSTR.

🎀 dvi 🎀

attaches the DVI builder to the construction environment. that's it, that's the whole vibe. short queen 💅

📄 dvipdf 📄

sets construction variables for the dvipdf utility.

Sets: $DVIPDF, $DVIPDFCOM, $DVIPDFFLAGS.

Uses: $DVIPDFCOMSTR.

🦋 dvips 🦋

sets construction variables for the dvips utility.

Sets: $DVIPS, $DVIPSFLAGS, $PSCOM, $PSPREFIX, $PSSUFFIX.

Uses: $PSCOMSTR.

⭐ f03 ⭐

set construction variables for generic POSIX Fortran 03 compilers.

Sets: $F03, $F03COM, $F03FLAGS, $F03PPCOM, $SHF03, $SHF03COM, $SHF03FLAGS, $SHF03PPCOM, $_F03INCFLAGS.

Uses: $F03COMSTR, $F03PPCOMSTR, $FORTRANCOMMONFLAGS, $SHF03COMSTR, $SHF03PPCOMSTR.

💜 f08 💜

set construction variables for generic POSIX Fortran 08 compilers. newer fortran, same energy ✨

Sets: $F08, $F08COM, $F08FLAGS, $F08PPCOM, $SHF08, $SHF08COM, $SHF08FLAGS, $SHF08PPCOM, $_F08INCFLAGS.

Uses: $F08COMSTR, $F08PPCOMSTR, $FORTRANCOMMONFLAGS, $SHF08COMSTR, $SHF08PPCOMSTR.

🌟 f77 🌟

set construction variables for generic POSIX Fortran 77 compilers. the OG. the blueprint. we respect her 🫶

Sets: $F77, $F77COM, $F77FILESUFFIXES, $F77FLAGS, $F77PPCOM, $F77PPFILESUFFIXES, $FORTRAN, $FORTRANCOM, $FORTRANFLAGS, $SHF77, $SHF77COM, $SHF77FLAGS, $SHF77PPCOM, $SHFORTRAN, $SHFORTRANCOM, $SHFORTRANFLAGS, $SHFORTRANPPCOM, $_F77INCFLAGS.

Uses: $F77COMSTR, $F77PPCOMSTR, $FORTRANCOMMONFLAGS, $FORTRANCOMSTR, $FORTRANFLAGS, $FORTRANPPCOMSTR, $SHF77COMSTR, $SHF77PPCOMSTR, $SHFORTRANCOMSTR, $SHFORTRANFLAGS, $SHFORTRANPPCOMSTR.

`f90` 🌈

okay so this one sets up the construction variables for your generic POSIX Fortran 90 compilers. slay.

Sets: $F90, $F90COM, $F90FLAGS, $F90PPCOM, $SHF90, $SHF90COM, $SHF90FLAGS, $SHF90PPCOM, $_F90INCFLAGS.

Uses: $F90COMSTR, $F90PPCOMSTR, $FORTRANCOMMONFLAGS, $SHF90COMSTR, $SHF90PPCOMSTR.

`f95` ✨

same vibe, but for generic POSIX Fortran 95 compilers 💅

Sets: $F95, $F95COM, $F95FLAGS, $F95PPCOM, $SHF95, $SHF95COM, $SHF95FLAGS, $SHF95PPCOM, $_F95INCFLAGS.

Uses: $F95COMSTR, $F95PPCOMSTR, $FORTRANCOMMONFLAGS, $SHF95COMSTR, $SHF95PPCOMSTR.

`fortran` 🧚

sets construction variables for generic POSIX Fortran compilers, periodt.

Sets: $FORTRAN, $FORTRANCOM, $FORTRANFLAGS, $SHFORTRAN, $SHFORTRANCOM, $SHFORTRANFLAGS, $SHFORTRANPPCOM.

Uses: $CPPFLAGS, $FORTRANCOMSTR, $FORTRANPPCOMSTR, $SHFORTRANCOMSTR, $SHFORTRANPPCOMSTR, $_CPPDEFFLAGS.

`g++` 💜

bestie this one is literally just for the g++ C++ compiler, no notes.

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

`g77` 🎀

sets stuff up for the g77 Fortran compiler.

Sets: $F77, $F77COM, $F77FILESUFFIXES, $F77PPCOM, $F77PPFILESUFFIXES, $FORTRAN, $FORTRANCOM, $FORTRANPPCOM, $SHF77, $SHF77COM, $SHF77FLAGS, $SHF77PPCOM, $SHFORTRAN, $SHFORTRANCOM, $SHFORTRANFLAGS, $SHFORTRANPPCOM.

Uses: $F77FLAGS, $FORTRANCOMMONFLAGS, $FORTRANFLAGS.

`gas` ⛽

sets the construction variables for the gas assembler. it calls the as tool, iykyk.

Sets: $AS.

`gcc` 🌸

sets construction variables for the gcc C compiler 🫶

Sets: $CC, $CCDEPFLAGS, $CCVERSION, $SHCCFLAGS.

`gdc` 🦋

sets construction variables for the D language compiler GDC. it's giving a lot of variables, but we love her for it.

`gettext` 🌍

a whole toolset for internationalization and localization of software you're building with SCons. the toolset loads these tools:

xgettext — pulls internationalized messages out of source code into POT file(s) 📝
msginit — initializes PO files during the initial translation of a project
msgmerge — updates PO files that already contain translated messages
msgfmt — compiles textual PO files into binary installable MO files

when you enable gettext, it internally loads all the tools listed above, so bestie you're encouraged to go read their individual documentation 💖

each of those tools brings its own builder(s), which you can use for particular activities related to software internationalization. you might, however, be interested in the top-level Translate builder 👑

to use the gettext tools, add the 'gettext' tool to your construction environment:

env = Environment(tools=['default', 'gettext'])

`gfortran` 🔥

sets construction variables for the GNU Fortran compiler. calls the fortran Tool module to set variables.

Sets: $F77, $F90, $F95, $FORTRAN, $SHF77, $SHF77FLAGS, $SHF90, $SHF90FLAGS, $SHF95, $SHF95FLAGS, $SHFORTRAN, $SHFORTRANFLAGS.

`gnulink` 🔗

sets construction variables for the GNU linker/loader.

Sets: $LDMODULEVERSIONFLAGS, $RPATHPREFIX, $RPATHSUFFIX, $SHLIBVERSIONFLAGS, $SHLINKFLAGS, $_LDMODULESONAME, $_SHLIBSONAME.

`gs` 👻

not me getting ghostscript energy. this Tool sets the construction variables you need to work with the Ghostscript software. it also registers an appropriate Action with the PDF Builder, so the conversion from PS/EPS to PDF happens automatically for the TeX/LaTeX toolchain ✨ and finally, it adds an explicit Gs Builder for Ghostscript to the environment.

Sets: $GS, $GSCOM, $GSFLAGS.

Uses: $GSCOMSTR.

`hpc++` 💻

sets construction variables for the compilers aCC on HP/UX systems.

`hpcc` 🖥️

sets construction variables for aCC compilers on HP/UX systems. calls the cXX tool for additional variables.

Sets: $CXX, $CXXVERSION, $SHCXXFLAGS.

`hplink` 🔌

sets construction variables for the linker on HP/UX systems.

Sets: $LINKFLAGS, $SHLIBSUFFIX, $SHLINKFLAGS.

`icc` 🧊

sets construction variables for the icc compiler on OS/2 systems.

Sets: $CC, $CCCOM, $CFILESUFFIX, $CPPDEFPREFIX, $CPPDEFSUFFIX, $CXXCOM, $CXXFILESUFFIX, $INCPREFIX, $INCSUFFIX.

Uses: $CCFLAGS, $CFLAGS, $CPPFLAGS, $_CPPDEFFLAGS, $_CPPINCFLAGS.

`icl` 🟦

sets construction variables for the Intel C/C++ compiler. calls the intelc Tool module to set its variables.

`ifl` 🟪

sets construction variables for the Intel Fortran compiler.

Sets: $FORTRAN, $FORTRANCOM, $FORTRANPPCOM, $SHFORTRANCOM, $SHFORTRANPPCOM.

Uses: $CPPFLAGS, $FORTRANFLAGS, $_CPPDEFFLAGS, $_FORTRANINCFLAGS.

`ifort` ⚡

sets construction variables for newer versions of the Intel Fortran compiler for Linux 🐧

Sets: $F77, $F90, $F95, $FORTRAN, $SHF77, $SHF77FLAGS, $SHF90, $SHF90FLAGS, $SHF95, $SHF95FLAGS, $SHFORTRAN, $SHFORTRANFLAGS.

`ilink` ⛓️

sets construction variables for the ilink linker on OS/2 systems.

Sets: $LIBDIRPREFIX, $LIBDIRSUFFIX, $LIBLINKPREFIX, $LIBLINKSUFFIX, $LINK, $LINKCOM, $LINKFLAGS.

`ilink32` ⛓️⛓️

sets construction variables for the Borland ilink32 linker.

Sets: $LIBDIRPREFIX, $LIBDIRSUFFIX, $LIBLINKPREFIX, $LIBLINKSUFFIX, $LINK, $LINKCOM, $LINKFLAGS.

`install` 📦

sets construction variables for file and directory installation. the girlies love a good install.

Sets: $INSTALL, $INSTALLSTR.

`intelc` 💠

sets construction variables for the Intel C/C++ compiler (Linux and Windows, version 7 and later). calls the gcc or msvc (on Linux and Windows, respectively) tool to set underlying variables.

Sets: $AR, $CC, $CXX, $INTEL_C_COMPILER_VERSION, $LINK.

`jar` 🫙

sets construction variables for the jar utility.

Sets: $JAR, $JARCOM, $JARFLAGS, $JARSUFFIX.

Uses: $JARCOMSTR.

`javac` ☕

sets construction variables for the javac compiler.

Sets: $JAVABOOTCLASSPATH, $JAVAC, $JAVACCOM, $JAVACFLAGS, $JAVACLASSPATH, $JAVACLASSSUFFIX, $JAVAINCLUDES, $JAVASOURCEPATH, $JAVASUFFIX.

Uses: $JAVACCOMSTR.

`javah` ☕🌿

sets construction variables for the javah tool.

Sets: $JAVACLASSSUFFIX, $JAVAH, $JAVAHCOM, $JAVAHFLAGS.

Uses: $JAVACLASSPATH, $JAVAHCOMSTR.

`latex` 📄

sets construction variables for the latex utility. academic girlie behavior, we respect it 💅

Sets: $LATEX, $LATEXCOM, $LATEXFLAGS.

Uses: $LATEXCOMSTR.

`ldc` 🅳

sets construction variables for the D language compiler LDC2.

`lex` 🔍

sets construction variables for the lex lexical analyzer.

Sets: $LEX, $LEXCOM, $LEXFLAGS, $LEXUNISTD.

Uses: $LEXCOMSTR, $LEXFLAGS, $LEX_HEADER_FILE, $LEX_TABLES_FILE.

`link` 🔗✨

sets construction variables for generic POSIX linkers. this is a "smart" linker tool — it picks a compiler to complete the linking based on the types of source files. main character energy fr fr 👑

Sets: $LDMODULE, $LDMODULECOM, $LDMODULEFLAGS, $LDMODULENOVERSIONSYMLINKS, $LDMODULEPREFIX, $LDMODULESUFFIX, $LDMODULEVERSION, $LDMODULEVERSIONFLAGS, $LIBDIRPREFIX, $LIBDIRSUFFIX, $LIBLINKPREFIX, $LIBLINKSUFFIX, $LINK, $LINKCOM, $LINKFLAGS, $SHLIBSUFFIX, $SHLINK, $SHLINKCOM, $SHLINKFLAGS, $__LDMODULEVERSIONFLAGS, $__SHLIBVERSIONFLAGS.

Uses: $LDMODULECOMSTR, $LINKCOMSTR, $SHLINKCOMSTR.

`linkloc` 🧷

sets construction variables for the LinkLoc linker for the Phar Lap ETS embedded operating system.

Sets: $LIBDIRPREFIX, $LIBDIRSUFFIX, $LIBLINKPREFIX, $LIBLINKSUFFIX, $LINK, $LINKCOM, $LINKFLAGS, $SHLINK, $SHLINKCOM, $SHLINKFLAGS.

Uses: $LINKCOMSTR, $SHLINKCOMSTR.

`m4` 🪄

sets construction variables for the m4 macro processor.

Sets: $M4, $M4COM, $M4FLAGS.

Uses: $M4COMSTR.

`masm` 🧱

sets construction variables for the Microsoft assembler.

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

Uses: $ASCOMSTR, $ASPPCOMSTR, $CPPFLAGS, $_CPPDEFFLAGS, $_CPPINCFLAGS.

`midl` 🪟

sets construction variables for the Microsoft IDL compiler.

Sets: $MIDL, $MIDLCOM, $MIDLFLAGS.

Uses: $MIDLCOMSTR.

`mingw` 🐧🪟

sets construction variables for MinGW (Minimal Gnu on Windows).

Sets: $AS, $CC, $CXX, $LDMODULECOM, $LIBPREFIX, $LIBSUFFIX, $OBJSUFFIX, $RC, $RCCOM, $RCFLAGS, $RCINCFLAGS, $RCINCPREFIX, $RCINCSUFFIX, $SHCCFLAGS, $SHCXXFLAGS, $SHLINKCOM, $SHLINKFLAGS, $SHOBJSUFFIX, $WINDOWSDEFPREFIX, $WINDOWSDEFSUFFIX.

Uses: $RCCOMSTR, $SHLINKCOMSTR.

`msgfmt` 🈯

this tool is part of the gettext toolset. it gives SCons an interface to the msgfmt(1) command by setting up the MOFiles builder, which generates binary message catalog (MO) files from a textual translation description (PO files) 💖

Sets: $MOSUFFIX, $MSGFMT, $MSGFMTCOM, $MSGFMTCOMSTR, $MSGFMTFLAGS, $POSUFFIX.

Uses: $LINGUAS_FILE.

`msginit` 🌱

this tool is a part of the scons gettext toolset. it gives SCons an interface to the msginit(1) program, by setting up the POInit builder, which creates a new PO file, initializing the meta information with values from the construction environment (or options).

Sets: $MSGINIT, $MSGINITCOM, $MSGINITCOMSTR, $MSGINITFLAGS, $POAUTOINIT, $POCREATE_ALIAS, $POSUFFIX, $POTSUFFIX, $_MSGINITLOCALE.

Uses: $LINGUAS_FILE, $POAUTOINIT, $POTDOMAIN.

`msgmerge` 🔀

this tool is a part of the scons gettext toolset. it gives SCons an interface to the msgmerge(1) command, by setting up the POUpdate builder, which merges two Uniform style .po files together 🌸

mslib 🏛️

okay so this one sets up the construction variables for the Microsoft mslib library archiver. bestie really said "librarian vibes".

Sets: $AR, $ARCOM, $ARFLAGS, $LIBPREFIX, $LIBSUFFIX.
Uses: $ARCOMSTR.

mslink 🔗

sets construction variables for the Microsoft linker. it's giving glue-it-all-together energy.

Sets: $LDMODULE, $LDMODULECOM, $LDMODULEFLAGS, $LDMODULEPREFIX, $LDMODULESUFFIX, $LIBDIRPREFIX, $LIBDIRSUFFIX, $LIBLINKPREFIX, $LIBLINKSUFFIX, $LINK, $LINKCOM, $LINKFLAGS, $REGSVR, $REGSVRCOM, $REGSVRFLAGS, $SHLINK, $SHLINKCOM, $SHLINKFLAGS, $WINDOWSDEFPREFIX, $WINDOWSDEFSUFFIX, $WINDOWSEXPPREFIX, $WINDOWSEXPSUFFIX, $WINDOWSPROGMANIFESTPREFIX, $WINDOWSPROGMANIFESTSUFFIX, $WINDOWSSHLIBMANIFESTPREFIX, $WINDOWSSHLIBMANIFESTSUFFIX, $WINDOWS_INSERT_DEF.
Uses: $LDMODULECOMSTR, $LINKCOMSTR, $REGSVRCOMSTR, $SHLINKCOMSTR.

mssdk 🪟

sets variables for Microsoft Platform SDK and/or Windows SDK. and here's the ✨plot twist✨: unlike most other Tool modules, mssdk does not set construction variables — it sets the environment variables in the environment SCons uses to execute the Microsoft toolchain: %INCLUDE%, %LIB%, %LIBPATH% and %PATH%. not me being different on purpose 💅

Uses: $MSSDK_DIR, $MSSDK_VERSION, $MSVS_VERSION.

msvc 🛠️

sets construction variables for the Microsoft Visual C++ compiler. the OG windows compiler bestie.

Sets: $BUILDERS, $CC, $CCCOM, $CCDEPFLAGS, $CCFLAGS, $CCPCHFLAGS, $CCPDBFLAGS, $CFILESUFFIX, $CFLAGS, $CPPDEFPREFIX, $CPPDEFSUFFIX, $CXX, $CXXCOM, $CXXFILESUFFIX, $CXXFLAGS, $INCPREFIX, $INCSUFFIX, $OBJPREFIX, $OBJSUFFIX, $PCHCOM, $PCHPDBFLAGS, $RC, $RCCOM, $RCFLAGS, $SHCC, $SHCCCOM, $SHCCFLAGS, $SHCFLAGS, $SHCXX, $SHCXXCOM, $SHCXXFLAGS, $SHOBJPREFIX, $SHOBJSUFFIX.
Uses: $CCCOMSTR, $CXXCOMSTR, $MSVC_NOTFOUND_POLICY, $MSVC_SCRIPTERROR_POLICY, $MSVC_SCRIPT_ARGS, $MSVC_SDK_VERSION, $MSVC_SPECTRE_LIBS, $MSVC_TOOLSET_VERSION, $MSVC_USE_SCRIPT, $MSVC_USE_SCRIPT_ARGS, $MSVC_USE_SETTINGS, $MSVC_VERSION, $PCH, $PCHSTOP, $PDB, $SHCCCOMSTR, $SHCXXCOMSTR.

msvs 🎀

sets construction variables for Microsoft Visual Studio.

Sets: $MSVSBUILDCOM, $MSVSCLEANCOM, $MSVSENCODING, $MSVSPROJECTCOM, $MSVSREBUILDCOM, $MSVSSCONS, $MSVSSCONSCOM, $MSVSSCONSCRIPT, $MSVSSCONSFLAGS, $MSVSSOLUTIONCOM.

mwcc 🍓

sets construction variables for the Metrowerks CodeWarrior compiler.

Sets: $CC, $CCCOM, $CFILESUFFIX, $CPPDEFPREFIX, $CPPDEFSUFFIX, $CXX, $CXXCOM, $CXXFILESUFFIX, $INCPREFIX, $INCSUFFIX, $MWCW_VERSION, $MWCW_VERSIONS, $SHCC, $SHCCCOM, $SHCCFLAGS, $SHCFLAGS, $SHCXX, $SHCXXCOM, $SHCXXFLAGS.
Uses: $CCCOMSTR, $CXXCOMSTR, $SHCCCOMSTR, $SHCXXCOMSTR.

mwld 🔧

sets construction variables for the Metrowerks CodeWarrior linker.

Sets: $AR, $ARCOM, $LIBDIRPREFIX, $LIBDIRSUFFIX, $LIBLINKPREFIX, $LIBLINKSUFFIX, $LINK, $LINKCOM, $SHLINK, $SHLINKCOM, $SHLINKFLAGS.

nasm 🦋

sets construction variables for the nasm Netwide Assembler.

Sets: $AS, $ASCOM, $ASFLAGS, $ASPPCOM, $ASPPFLAGS.
Uses: $ASCOMSTR, $ASPPCOMSTR.

ninja 🥷

sets up the Ninja builder, which generates a ninja build file, and then optionally runs ninja. honestly? iconic.

⚠️ Note — This is an experimental feature. This functionality is subject to change and/or removal without a deprecation cycle.

Sets: $IMPLICIT_COMMAND_DEPENDENCIES, $NINJA_ALIAS_NAME, $NINJA_CMD_ARGS, $NINJA_COMPDB_EXPAND, $NINJA_DEPFILE_PARSE_FORMAT, $NINJA_DIR, $NINJA_DISABLE_AUTO_RUN, $NINJA_ENV_VAR_CACHE, $NINJA_FILE_NAME, $NINJA_FORCE_SCONS_BUILD, $NINJA_GENERATED_SOURCE_ALIAS_NAME, $NINJA_GENERATED_SOURCE_SUFFIXES, $NINJA_MSVC_DEPS_PREFIX, $NINJA_POOL, $NINJA_REGENERATE_DEPS, $NINJA_SCONS_DAEMON_KEEP_ALIVE, $NINJA_SCONS_DAEMON_PORT, $NINJA_SYNTAX, $_NINJA_REGENERATE_DEPS_FUNC.
Uses: $AR, $ARCOM, $ARFLAGS, $CC, $CCCOM, $CCDEPFLAGS, $CCFLAGS, $CXX, $CXXCOM, $ESCAPE, $LINK, $LINKCOM, $PLATFORM, $PRINT_CMD_LINE_FUNC, $PROGSUFFIX, $RANLIB, $RANLIBCOM, $SHCCCOM, $SHCXXCOM, $SHLINK, $SHLINKCOM.

packaging 📦

sets construction variables for the Package Builder. If this tool is enabled, the --package-type command-line option is made available. yesss we love a tool that unlocks a whole CLI flag.

pdf 📄

sets construction variables for the Portable Document Format builder.

Sets: $PDFPREFIX, $PDFSUFFIX.

pdflatex 🧚

sets construction variables for the pdflatex utility.

Sets: $LATEXRETRIES, $PDFLATEX, $PDFLATEXCOM, $PDFLATEXFLAGS.
Uses: $PDFLATEXCOMSTR.

pdftex ✨

sets construction variables for the pdftex utility.

Sets: $LATEXRETRIES, $PDFLATEX, $PDFLATEXCOM, $PDFLATEXFLAGS, $PDFTEX, $PDFTEXCOM, $PDFTEXFLAGS.
Uses: $PDFLATEXCOMSTR, $PDFTEXCOMSTR.

python 🐍

Loads the Python source scanner into the invoking environment. When loaded, the scanner will attempt to find implicit dependencies for any Python source files in the list of sources provided to an Action that uses this environment. it's giving "i read your imports so you don't have to" energy fr.

Available since scons 4.0..

(yes, that's literally how it's written — two dots, we don't make the rules 💀)

rmic 💜

sets construction variables for the rmic utility.

Sets: $JAVACLASSSUFFIX, $RMIC, $RMICCOM, $RMICFLAGS.
Uses: $RMICCOMSTR.

rpcgen 🌈

sets construction variables for building with RPCGEN.

Sets: $RPCGEN, $RPCGENCLIENTFLAGS, $RPCGENFLAGS, $RPCGENHEADERFLAGS, $RPCGENSERVICEFLAGS, $RPCGENXDRFLAGS.

sgiar 🦖

sets construction variables for the SGI library archiver.

Sets: $AR, $ARCOMSTR, $ARFLAGS, $LIBPREFIX, $LIBSUFFIX, $SHLINK, $SHLINKFLAGS.
Uses: $ARCOMSTR, $SHLINKCOMSTR.

sgic++ 🦖✨

sets construction variables for the SGI C++ compiler.

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

sgicc 🦖💙

sets construction variables for the SGI C compiler.

Sets: $CXX, $SHOBJSUFFIX.

sgilink 🦖🔗

sets construction variables for the SGI linker.

Sets: $LINK, $RPATHPREFIX, $RPATHSUFFIX, $SHLINKFLAGS.

sunar ☀️

sets construction variables for the Sun library archiver.

Sets: $AR, $ARCOM, $ARFLAGS, $LIBPREFIX, $LIBSUFFIX.
Uses: $ARCOMSTR.

sunc++ ☀️➕➕

sets construction variables for the Sun C++ compiler.

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

suncc ☀️💙

sets construction variables for the Sun C compiler.

Sets: $CXX, $SHCCFLAGS, $SHOBJPREFIX, $SHOBJSUFFIX.

sunf77 ☀️7️⃣7️⃣

Set construction variables for the Sun f77 Fortran compiler.

Sets: $F77, $FORTRAN, $SHF77, $SHF77FLAGS, $SHFORTRAN, $SHFORTRANFLAGS.

sunf90 ☀️9️⃣0️⃣

Set construction variables for the Sun f90 Fortran compiler.

Sets: $F90, $FORTRAN, $SHF90, $SHF90FLAGS, $SHFORTRAN, $SHFORTRANFLAGS.

sunf95 ☀️9️⃣5️⃣

Set construction variables for the Sun f95 Fortran compiler.

Sets: $F95, $FORTRAN, $SHF95, $SHF95FLAGS, $SHFORTRAN, $SHFORTRANFLAGS.

sunlink ☀️🔗

sets construction variables for the Sun linker.

Sets: $RPATHPREFIX, $RPATHSUFFIX, $SHLINKFLAGS.

swig 🧣

sets construction variables for the SWIG interface compiler.

Sets: $SWIG, $SWIGCFILESUFFIX, $SWIGCOM, $SWIGCXXFILESUFFIX, $SWIGDIRECTORSUFFIX, $SWIGFLAGS, $SWIGINCPREFIX, $SWIGINCSUFFIX, $SWIGPATH, $SWIGVERSION, $_SWIGINCFLAGS.
Uses: $SWIGCOMSTR.

tar 🗜️

sets construction variables for the tar archiver.

Sets: $TAR, $TARCOM, $TARFLAGS, $TARSUFFIX.
Uses: $TARCOMSTR.

tex 📚

sets construction variables for the TeX formatter and typesetter.

Sets: $BIBTEX, $BIBTEXCOM, $BIBTEXFLAGS, $LATEX, $LATEXCOM, $LATEXFLAGS, $MAKEINDEX, $MAKEINDEXCOM, $MAKEINDEXFLAGS, $TEX, $TEXCOM, $TEXFLAGS.
Uses: $BIBTEXCOMSTR, $LATEXCOMSTR, $MAKEINDEXCOMSTR, $TEXCOMSTR.

textfile 📝

Set construction variables for the Textfile and Substfile builders.

Sets: $FILE_ENCODING, $LINESEPARATOR, $SUBSTFILEPREFIX, $SUBSTFILESUFFIX, $TEXTFILEPREFIX, $TEXTFILESUFFIX.
Uses: $SUBST_DICT.

tlib 🫙

sets construction variables for the Borland tlib library archiver.

Sets: $AR, $ARCOM, $ARFLAGS, $LIBPREFIX, $LIBSUFFIX.
Uses: $ARCOMSTR.

xgettext 🌍

This tool is a part of the gettext toolset. It provides SCons an interface to the xgettext(1) program, which extracts internationalized messages from source code. The tool sets up the POTUpdate builder to make PO Template files. so it's the one finding every translatable string like a lil detective 🔍

Sets: $POTSUFFIX, $POTUPDATE_ALIAS, $XGETTEXTCOM, $XGETTEXTCOMSTR, $XGETTEXTFLAGS, $XGETTEXTFROM, $XGETTEXTFROMPREFIX, $XGETTEXTFROMSUFFIX, $XGETTEXTPATH, $XGETTEXTPATHPREFIX, $XGETTEXTPATHSUFFIX, $_XGETTEXTDOMAIN, $_XGETTEXTFROMFLAGS, $_XGETTEXTPATHFLAGS.
Uses: $POTDOMAIN.

yacc 🐉

sets construction variables for the yacc parser generator.

Sets: $YACC, $YACCCOM, $YACCFLAGS, $YACCHFILESUFFIX, $YACCHXXFILESUFFIX, $YACCVCGFILESUFFIX, $YACC_GRAPH_FILE_SUFFIX.
Uses: $YACCCOMSTR, $YACCFLAGS, $YACC_GRAPH_FILE, $YACC_HEADER_FILE.

zip 🤐

sets construction variables for the zip archiver.

Sets: $ZIP, $ZIPCOM, $ZIPCOMPRESSION, $ZIPFLAGS, $ZIPSUFFIX.
Uses: $ZIPCOMSTR.

🌟 Builder Methods 🌟

Builder methods are special functions used to declare relationships in the build dependency graph. okay so listen — calling a Builder does not build anything directly, bestie. instead it records:

the target or targets (what you want built),
the sources (what it's built from),
and the construction environment to use for build settings.

The builder itself will typically have information about producing targets which is also used, except Command, where the caller is responsible for specifying the action. then the SCons job runner later decides if and when to initiate a build using this information. it's giving "i'm just writing it down, the runner does the actual slaying" 💅

All true Builder methods share the same function calling syntax. For the sake of brevity, this common signature is not included in the listing of Builders. Pseudo-Builders have more flexibility in how they are called, and do not necessarily follow this convention, as described in the text of the respective entries.

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

The target and source arguments can be specified either as positional or keyword arguments. Some additional keyword arguments are recognized for all builders, and any unknown keyword arguments are treated as temporary construction variable assignments. You can specify sources and targets as a scalar or a list, composed of either strings or nodes. For convenience, the Split method can be used to split a single whitespace-separated string into a list.

so basically: positional or keyword, scalar or list, strings or nodes, and mystery kwargs become temp variables. fr fr, the flexibility is unmatched 🫶

okay so bestie, SCons can resolve paths to sources and targets that you specify in several different forms. the target and source arguments can be scalar (a string or a Node) or a collection (of strings or Nodes). ✨

Nodes always work, because they're the result of a previous successful path resolution — if a path string got resolved correctly, it's stored internally as a Node in the dependency graph. 💅
Plain file names (no pathname separators) are searched for in the current directory.
Absolute paths (they begin with a pathname separator) get resolved by walking the path components starting from the root of the filesystem or current volume.
Relative paths (no leading pathname separator) are resolved by walking the path components starting from the current directory.
Top-relative paths are relative paths whose first character is #. They get walked starting from the project top-level directory (usually, the directory where the SConstruct file is found). Top-relative paths are always relative paths, so that initial character can be followed by a pathname separator — which is ignored and does not affect resolution. 🫶
UNC paths (Windows) start with exactly two pathname separators. They take the form \\server_name\share_name\file_path. The file_path portion is looked up as an absolute path starting from the root of the resource described by \\server_name\share_name. Since UNC paths are never relative, the top-relative path form does not apply. 🙅‍♀️
URL-style strings and Python pathlib objects are not recognized. 💀

The "current directory" for relative path resolution has options, bestie. SCons by default changes to the directory containing the SConscript file (including SConstruct) it is currently processing. Use of the SConscriptChdir function toggles the default behavior off/on. The srcdir builder argument affects where source file paths are looked for (see details below). Specifying one or more source code repositories via the Repository function or the -Y/--repository option tells SCons to look additional places after the actual current directory. The concept of current directory changes for targets (and in some cases sources) if a variant directory is set up using the VariantDir function or the variant_dir= parameter to the SConscript function. These options do not affect top-relative paths.

Note On Windows, DOS paths may begin with a volume or drive letter followed by the volume separator (:). The remainder of the path is absolute or relative; if the volume specifier is present, resolution starts at the root of the specified drive for absolute paths and the current directory on the specified drive for relative paths. If the specified drive letter is different from the current drive, a relative path is missing context: since SCons is a console (command-line) application, it may inherit state from the terminal it was started in, including saved current directories for other drives; SCons has no way of knowing what those would be. Use of a drive letter in the path also precludes the use of the top-relative form. 😭

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

Additional examples of source and target paths:

Note Top-relative paths only work where SCons will interpret the path (see examples). The string must first be converted to a relative or absolute path to be used in other contexts (such as pure Python code that does not involve an SCons API call). A suitable string can be extracted from the Node created from a top-relative path. Additionally, some paths are handled by SCons but are not directly build participants, so are not evaluated for the # since no Nodes are created. You can explicitly create a File or Dir node to force evaluation, such as when specifying a path to the derived-file cache: CacheDir(Dir('#cache')). iykyk ✨

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

# os.path.exists() is pure Python, so this fails:
if os.path.exists('#inc/foo.h'):
    env.Append(CPPPATH='#inc')

# create a Node to make it work:
if os.path.exists(File('#inc/foo.h')):
    env.Append(CPPPATH='#inc')

If SCons can deduce the target name from the source(s), the target argument may be omitted. If the Builder supports it, SCons will take the base name of the first source file and use it as the base name of the target, adding the appropriate prefix/suffix. For Builders designated as single-source, a separate target is built for each source file. If multiple sources are passed to a single-source builder, the target argument must be omitted, and each target will be given a name deduced from the corresponding source file. 👑

The optional srcdir keyword argument specifies that source file strings that are not absolute or top-relative paths are to be interpreted relative to the value of 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, rather than looking for them in the directory of the SConscript file being evaluated.

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

The optional parse_flags keyword argument causes behavior similar to the env.MergeFlags method, where the argument value is broken into individual settings and merged into the appropriate construction variables. The following example adds 'include' to the $CPPPATH construction variable, 'EBUG' to $CPPDEFINES, and 'm' to $LIBS:

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

The optional chdir keyword argument specifies that the Builder's action(s) should be executed after changing directory. If the chdir argument is a path string or a directory Node, scons will change to the specified directory. If the chdir is not a string or Node and evaluates true, then scons will change to the target file's directory. The original directory is restored after the action is complete. 🔄

# scons will change to the "sub/dir" subdirectory
# before executing the Copy action function
env.Command(
    target='sub/dir/foo.out',
    source='sub/dir/foo.in',
    action=Copy('${TARGET.file}', '${SOURCE.file}'),
    chdir='sub/dir',
)

# Here, chdir is not a string, so scons will change to the
# target's directory ("sub/dir") to execute the action.
env.Command('
    target='sub/dir/foo.out',
    source='sub/dir/foo.in',
    action=Copy('${TARGET.file}', '${SOURCE.file}'),
    chdir=True
)

Warning Python only tracks one current directory location, even if there are multiple executing threads. This means that use of the chdir argument will not work with SCons in multi-threaded mode (the -j option), because individual worker threads spawned by SCons interfere with each other when they start changing directory. 💀

Note SCons does not account for chdir when it expands construction variables like $TARGET and $SOURCE, so they will be 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}, which expand to the filename portion of the target and source. 😭

Keyword arguments that are not specifically recognized are treated as construction variable 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 $SHLIBSUFFIX and $LIBSUFFIXES construction variables must be set if you want scons to search automatically for dependencies on the non-standard library names; see the descriptions of these variables for more information. 🧚

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

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

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

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

from SCons.Script import *

A builder may add additional targets beyond those requested if an attached Emitter chooses to do so (see the section called “Builder Objects” for more information. $PROGEMITTER is an example). For example, the GNU linker takes a command-line argument -Map=mapfile, which causes it to produce a linker map file in addition to the executable file actually being linked. If the Program builder's emitter is configured to add this mapfile if the option is set, then two targets will be returned when you only provided for one. 💅✨

okay so because of literally all of that, builder methods always hand you back a NodeList — a list-like object where every element is a Node. And a Node? That's SCons's internal representation of build targets or sources (peep the section called “Node Objects” for the whole lore ✨). The NodeList you get back can be passed to other builder methods as the source(s), or to any other SCons function or method where a path string would normally be accepted. it just works 💅

So say you wanna add one specific preprocessor define when compiling one 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 like this makes for a way more portable build, because you skip having to specify a platform-specific object suffix when you call the Program builder method. main character energy 🌈

The NodeList object is also convenient to pass to the Default function, for the exact same reason — no platform-specific name needed:

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

The Node representing the explicitly-requested target is always the first element of the returned NodeList, and you can retrieve it with list indexing (like bar_obj_list[0]). Want the path name for a Node's file? Just use Python's string constructor str (like str(bar_obj_list[0])). 🫶

Builder calls will automatically "flatten" lists you pass as source and target, so those lists are free to contain elements that are themselves lists — like bar_obj_list returned by the StaticObject call. But if you need to manipulate a list-of-lists returned by builders directly in Python code, you've got options, bestie. You can 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 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))

Note — Since builder calls return a list-like object, not an actual Python list, it is not appropriate to use the Python add operator (+ or +=) to append builder results to a Python list 😭. Because the list and the object are different types, Python will not update the original list in place — it 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'))

bar_obj_list = env.StaticObject('bar.c', CPPDEFINES='-DBAR')
print("The path to bar_obj is:", str(bar_obj_list[0]))

All targets of builder methods automatically depend on their sources. SCons scans source files in various programming languages for known dependency indications (e.g. #include directives for sources that will be fed to the C preprocessor), which largely eliminates the need for explicit dependency specification. You can also specify an explicit dependency using the env.Depends method of a construction environment, though this is discouraged unless the dependency cannot reliably be detected by an existing scanner. fr fr, save it for the edge cases

By default, SCons can scan C source files, C++ source files, Fortran source files with specific file extensions (.F (POSIX systems only), .fpp, or .FPP) and assembly language files with specific file extensions (.S (POSIX systems only), .spp, or .SPP) for C preprocessor dependencies. SCons also has default support for scanning D, Java, SWIG and LaTeX source files. so many languages, so little time ✨

Builders are created at runtime for efficiency and added to the construction environment as methods. SCons provides templates for many Builders for known build types, and additional Builders can be written to add to a project. The templates usually exist in Tool specification modules, which, when run, can probe for the presence of required external tools — like a compiler binary — and for other necessary conditions, before instantiating the Builder. The Builders available in a given construction environment therefore vary with the type of platform, how the platform is provisioned, and the tools selected for loading. The available builder methods are registered as key-value pairs in the $BUILDERS attribute of the construction environment. Although a Builder is created as a method of a construction environment, they may also be called as a global function. A Builder called this way will internally use the Default Environment to look up construction variables:

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

Builders called in the global function style are automatically in scope inside SConscript files. They are not in scope in project-specific Python modules that you include via the Python import statement from an SConscript file, and you will need to add them to that module's global scope explicitly. You can do that by adding the following import to the Python module: from SCons.Script import *.

The following builder methods have templates in the SCons core software distribution. 👑

CFile(), `env.CFile()`

Builds a C source file given a lex (.l) or yacc (.y) input file. The suffix specified by the $CFILESUFFIX construction variable (.c by default) is automatically added to the target if it is not already present. Example:

# builds foo.c
env.CFile(target='foo.c', source='foo.l')

# builds bar.c
env.CFile(target='bar', source='bar.y')

Command(), `env.Command()`

So plot twist: there is actually no Builder named Command 💀. Instead, the term "Command Builder" refers to a function which, on each call, creates and calls an anonymous Builder. This is useful for "one-off" builds where a full Builder is not needed. And since the anonymous Builder is never hooked into the standard Builder framework, an Action must always be specified. See the Command function description for the calling syntax and details.

CompilationDatabase(), `env.CompilationDatabase()`

CompilationDatabase is a special builder which adds a target to create a JSON formatted compilation database compatible with clang tooling (see the LLVM specification[1]). This database is suitable for consumption by various tools and editors who can use it to obtain build and dependency information which otherwise would be internal to SCons. The builder does not require any source files to be specified — rather, it arranges to emit information about all of the C, C++ and assembler source/output pairs identified in the build that are not excluded by the optional filter $COMPILATIONDB_PATH_FILTER. The target is subject to the usual SCons target selection rules.

Called with no arguments, the builder will default to a target name of compile_commands.json.
Called with a single positional argument, scons will "deduce" the target name from that source argument, giving it the same name, and then ignore the source. This is the usual way to call the builder if a non-default target name is wanted.
Called with either the target= or source= keyword arguments, the value of the argument is taken as the target name. Called with both, the target= value is used and source= is ignored. Called with multiple sources, the source list will be ignored, since there is no way to deduce what the intent was; in this case the default target name will be used.

Note — You must load the compilation_db tool prior to specifying any part of your build, or some source/output files will not show up in the compilation database. ⚠️

Available since scons 4.0.

CXXFile(), `env.CXXFile()`

Builds a C++ source file given a lex (.ll) or yacc (.yy) input file. The suffix specified by the $CXXFILESUFFIX construction variable (.cc by default) is automatically added to the target if it is not already present. Example:

# builds foo.cc
env.CXXFile(target='foo.cc', source='foo.ll')

# builds bar.cc
env.CXXFile(target='bar', source='bar.yy')

DocbookEpub(), `env.DocbookEpub()`

A pseudo-Builder, providing a Docbook toolchain for EPUB output. 🦋

env = Environment(tools=['docbook'])
env.DocbookEpub('manual.epub', 'manual.xml')

or simply

env = Environment(tools=['docbook'])
env.DocbookEpub('manual')

DocbookHtml(), `env.DocbookHtml()`

A pseudo-Builder, providing a Docbook toolchain for HTML output. 💖

env = Environment(tools=['docbook'])
env.DocbookHtml('manual.html', 'manual.xml')

or simply

env = Environment(tools=['docbook'])
env.DocbookHtml('manual')

DocbookHtmlChunked(), `env.DocbookHtmlChunked()`

A pseudo-Builder providing a Docbook toolchain for chunked HTML output. It supports the base.dir parameter. The chunkfast.xsl file (requires "EXSLT") is used as the default stylesheet. Basic syntax:

env = Environment(tools=['docbook'])
env.DocbookHtmlChunked('manual')

where manual.xml is the input file.

If you use the root.filename parameter in your own stylesheets you have to specify the new target name. This ensures that the dependencies get correct, especially for the cleanup via “scons -c”:

env = Environment(tools=['docbook'])
env.DocbookHtmlChunked('mymanual.html', 'manual', xsl='htmlchunk.xsl')

Some basic support for the base.dir parameter is provided. You can add the base_dir keyword to your Builder call, and the given prefix gets prepended to all the created filenames:

env = Environment(tools=['docbook'])
env.DocbookHtmlChunked('manual', xsl='htmlchunk.xsl', base_dir='output/')

Make sure that you don't forget the trailing slash for the base folder, else your files get renamed only! 😭 do not forget the slash

DocbookHtmlhelp(), `env.DocbookHtmlhelp()`

A pseudo-Builder, providing a Docbook toolchain for HTMLHELP output. Its basic syntax is:

env = Environment(tools=['docbook'])
env.DocbookHtmlhelp('manual')

where manual.xml is the input file. 📄✨

Okay and if you're out here using the root.filename parameter in your own stylesheets?? bestie you have to specify the new target name, like it's not optional, the vibes demand it. Why? because that's what makes the dependencies come out right — especially for the cleanup pass with scons -c 💅:

env = Environment(tools=['docbook'])
env.DocbookHtmlhelp('mymanual.html', 'manual', xsl='htmlhelp.xsl')

There's also some basic support for the base.dir parameter 🫶 you can drop a base_dir keyword into your Builder call, and whatever prefix you give it gets prepended to all the created filenames:

env = Environment(tools=['docbook'])
env.DocbookHtmlhelp('manual', xsl='htmlhelp.xsl', base_dir='output/')

⚠️ Not me begging you: do not forget the trailing slash on the base folder. If you forget it, your files don't get moved into the folder — they just get renamed. RENAMED. 😭 single most common heartbreak in this house.

DocbookMan(), env.DocbookMan() — a pseudo-Builder that hands you a whole Docbook toolchain for Man page output 📖 the basic syntax is giving:

env = Environment(tools=['docbook'])
env.DocbookMan('manual')

where manual.xml is the input file. And heads up, bestie: you can specify a target name, but the actual output names get set automatically from the refname entries in your XML source. So like, the XML is the main character here, not you 🎀

DocbookPdf(), env.DocbookPdf() — a pseudo-Builder giving you the Docbook toolchain for PDF output 🌸

env = Environment(tools=['docbook'])
env.DocbookPdf('manual.pdf', 'manual.xml')

or honestly just

env = Environment(tools=['docbook'])
env.DocbookPdf('manual')

DocbookSlidesHtml(), env.DocbookSlidesHtml() — a pseudo-Builder for the Docbook toolchain that spits out HTML slides 🎀✨

env = Environment(tools=['docbook'])
env.DocbookSlidesHtml('manual')

If you're using the titlefoil.html parameter in your own stylesheets, you have to give the new target name — this is the thing that keeps the dependencies correct, especially for cleanup via scons -c 💅:

env = Environment(tools=['docbook'])
env.DocbookSlidesHtml('mymanual.html','manual', xsl='slideshtml.xsl')

And there's some basic support for the base.dir parameter too 🫶 add the base_dir keyword to your Builder call and the given prefix gets prepended to all the created filenames:

env = Environment(tools=['docbook'])
env.DocbookSlidesHtml('manual', xsl='slideshtml.xsl', base_dir='output/')

⚠️ Again for the people in the back: don't forget the trailing slash for the base folder, or your files get renamed only. Renamed. Only. 😭

DocbookSlidesPdf(), env.DocbookSlidesPdf() — a pseudo-Builder serving the Docbook toolchain for PDF slides output 🦋

env = Environment(tools=['docbook'])
env.DocbookSlidesPdf('manual.pdf', 'manual.xml')

or simply

env = Environment(tools=['docbook'])
env.DocbookSlidesPdf('manual')

DocbookXInclude(), env.DocbookXInclude() — a pseudo-Builder for resolving XIncludes in a separate processing step, no cap 🧚✨

env = Environment(tools=['docbook'])
env.DocbookXInclude('manual_xincluded.xml', 'manual.xml')

DocbookXslt(), env.DocbookXslt() — a pseudo-Builder that applies a given XSL transformation to the input file 🌈

env = Environment(tools=['docbook'])
env.DocbookXslt('manual_transformed.xml', 'manual.xml', xsl='transform.xslt')

📌 note bestie: this builder requires the xsl parameter to be set. Like, it's not going anywhere without it. Periodt.

DVI(), env.DVI() — builds a .dvi file from a .tex, .ltx or .latex input file 🔥 Now here's the tea: if the source file suffix is .tex, scons is gonna peek inside the file contents. If it finds the string \documentclass or \documentstyle, the file gets assumed to be a LaTeX file and the target is built by invoking the $LATEXCOM command line. Otherwise? the $TEXCOM command line gets used, simple as that. And if it's a LaTeX file, the DVI builder method also goes and examines the contents of the .aux file and invokes the $BIBTEX command line if the string bibdata shows up, starts $MAKEINDEX to generate an index if a .ind file is found, and will examine the contents of the .log file and re-run the $LATEXCOM command if the log file says it's necessary. She's thorough like that 💅

The suffix .dvi (hard-coded within TeX itself, iconic behaviour) is automatically added to the target if it's not already present. Examples:

# builds from aaa.tex
env.DVI(target = 'aaa.dvi', source = 'aaa.tex')
# builds bbb.dvi
env.DVI(target = 'bbb', source = 'bbb.ltx')
# builds from ccc.latex
env.DVI(target = 'ccc.dvi', source = 'ccc.latex')

Gs(), env.Gs() — a Builder for explicitly calling the gs executable 👑 depending on the underlying OS, the different names gs, gsos2 and gswin32c are tried.

env = Environment(tools=['gs'])
env.Gs(
    'cover.jpg',
    'scons-scons.pdf',
    GSFLAGS='-dNOPAUSE -dBATCH -sDEVICE=jpeg -dFirstPage=1 -dLastPage=1 -q',
)

Install(), env.Install() — installs one or more source files or directories into the specified target, which must be a directory 📁 the names of the specified source files or directories stay the same inside the destination directory. Sources can be given as a string or as a node returned by a builder.

env.Install(target='/usr/local/bin', source=['foo', 'bar'])

💀 Now listen, this is the part that gets everybody. If the target paths you chose for the Install builder (and the related InstallAs and InstallVersionedLib builders) live outside the project tree — like in that example up there — they may not get selected for "building" by default. Why? because in the absence of other instructions, scons builds targets that are underneath the top directory (the directory that contains the SConstruct file, usually the current directory). So use command line targets or the Default function in this case. You've been warned, bestie 🫶

If the --install-sandbox option is given, the target directory will be prefixed by the directory path specified. Super useful for testing installation behavior without actually installing to a "live" location in the system 🧪✨

See also FindInstalledFiles. And for more thoughts on installation, see the User Guide — particularly the section on Command-Line Targets and the chapters on Installing Files and on Alias Targets 📚

InstallAs(), env.InstallAs() — installs one or more source files or directories to specific names, letting you change a file or directory name as part of the installation 🎀 It is an error if the target and source arguments list different numbers of files or directories. No mismatched counts allowed, she said what she said.

env.InstallAs(target='/usr/local/bin/foo',
              source='foo_debug')
env.InstallAs(target=['../lib/libfoo.a', '../lib/libbar.a'],
              source=['libFOO.a', 'libBAR.a'])

See the note under Install 👆 (yes, the outside-the-tree one, it still applies)

InstallVersionedLib(), env.InstallVersionedLib() — installs a versioned shared library 🔥 the symlinks appropriate to the architecture will be generated based on symlinks of the source library.

env.InstallVersionedLib(target='/usr/local/bin/foo',
                        source='libxyz.1.5.2.so')

See the note under Install 👆 (same one, still applies, still important)

Jar(), env.Jar() — builds a Java archive (.jar) file from the specified list of sources 🫙 Any directories in the source list will be searched for .class files. Any .java files in the source list will be compiled to .class files by calling the Java Builder.

If the $JARCHDIR value is set, the jar command will change to the specified directory using the -C option. If $JARCHDIR is not set explicitly, SCons will use the top of any subdirectory tree in which Java .class were built by the Java Builder.

And if the contents of any of the source files begin with the string Manifest-Version, the file is assumed to be a manifest and is passed to the jar command with the m option set 📜

env.Jar(target = 'foo.jar', source = 'classes')

env.Jar(target = 'bar.jar',
        source = ['bar1.java', 'bar2.java'])

Java(), env.Java() — builds one or more Java class files ☕️ sources can be any combination of explicit .java files, or directory trees which will be scanned for .java files.

SCons will parse each source .java file to find the classes (including inner classes 👀 yes, inner ones too) defined within that file, and from that figure out the target .class files that will be created. Those class files get placed underneath the specified target directory.

SCons will also search each Java file for the Java package name, which it assumes can be found on a line beginning with the string package in the first column. The resulting .class files will be placed in a directory reflecting the specified package name. For example, the file Foo.java defining a single public Foo class and containing a package name of sub.dir will generate a corresponding sub/dir/Foo.class class file. It's giving organized 💅

Examples:

env.Java(target='classes', source='src')
env.Java(target='classes', source=['src1', 'src2'])
env.Java(target='classes', source=['File1.java', 'File2.java'])

Java source files can use the native encoding for the underlying OS 🌍 but since SCons compiles in simple ASCII mode by default, the compiler will generate warnings about unmappable characters, which may lead to errors as the file is processed further 😭 In this case, the user must specify the LANG environment variable to tell the compiler what encoding is used. And for portability, it's best if the encoding is hard-coded, so that the compilation works when run on a system with a different encoding:

env = Environment()
env['ENV']['LANG'] = 'en_GB.UTF-8'

JavaH(), env.JavaH() — builds C header and source files for implementing Java native methods 🧬 The target can be either a directory in which the header files will be written, or a header file name which will contain all of the definitions. The source can be the names of .class files, the names of .java files to be compiled into .class files by calling the Java builder method, or the objects returned from the Java builder method. Flexible queen 💅

If the construction variable $JAVACLASSDIR is set — either in the environment or in the call to the JavaH builder method itself — then the value of the variable will be stripped from the beginning of any .class file names. So clean ✨

Examples:

# builds java_native.h
classes = env.Java(target="classdir", source="src")
env.JavaH(target="java_native.h", source=classes)

# builds include/package_foo.h and include/package_bar.h
env.JavaH(target="include", source=["package/foo.class", "package/bar.class"])

# builds export/foo.h and export/bar.h
env.JavaH(
    target="export",
    source=["classes/foo.class", "classes/bar.class"],
    JAVACLASSDIR="classes",
)

okay bestie, important heads up ⚠️ — Java versions starting with 10.0 literally do NOT use the javah command for generating JNI headers/sources anymore, and fr fr they removed the command entirely (see Java Enhancement Proposal JEP 313[2]), which makes this tool harder to use for that purpose. And here's the sneaky part: SCons may autodiscover a javah belonging to an older release if there are multiple Java versions on the system, which will lead to incorrect results. 💀 So if you wanna use this with a newer Java, override the default values of $JAVAH (make it contain the path to the javac) and $JAVAHFLAGS (at least a -h flag) and pls note that generating headers with javac requires supplying source .java files only, not .class files.

`Library()`, `env.Library()` 🎀

A synonym for the StaticLibrary builder method. Same vibe, different name, it's giving alias energy ✨

`LoadableModule()`, `env.LoadableModule()` 🦋

On most systems, this is the same as SharedLibrary. On Mac OS X (Darwin) platforms tho, this creates a loadable module bundle. 🍎

`M4()`, `env.M4()` 🌸

Builds an output file from an M4 input file. This uses a default $M4FLAGS value of -E, which considers all warnings to be fatal and stops on the first warning when using the GNU version of m4. 😤

Example:

env.M4(target = 'foo.c', source = 'foo.c.m4')

`MOFiles()`, `env.MOFiles()` 💜

This builder is set up by the msgfmt tool. The builder compiles PO files to MO files. MOFiles is a single-source builder. The source parameter can also be omitted if $LINGUAS_FILE is set. 👑

Example 1. Create pl.mo and en.mo by compiling pl.po and en.po:

env.MOFiles(['pl', 'en'])

Example 2. Compile files for languages defined in LINGUAS file:

env.MOFiles(LINGUAS_FILE=True)

Example 3. Create pl.mo and en.mo by compiling pl.po and en.po plus files for languages defined in LINGUAS file:

env.MOFiles(['pl', 'en'], LINGUAS_FILE=True)

Example 4. Compile files for languages defined in LINGUAS file (another version):

env['LINGUAS_FILE'] = True
env.MOFiles()

`MSVSProject()`, `env.MSVSProject()` 🔥

Build a Microsoft Visual C++ project file and solution file. 🪟

Builds a Microsoft Visual C++ project file based on the version of Visual Studio (or to be more precise, of MSBuild) that is configured: either the latest installed version, or the version specified by $MSVC_VERSION in the current construction environment. For Visual Studio 6.0 a .dsp file is generated. For Visual Studio versions 2002-2008, a .vcproj file is generated. For Visual Studio 2010 and later a .vcxproj file is generated. Note there are multiple versioning schemes involved in the Microsoft compilation environment — see the description of $MSVC_VERSION for equivalences. And also note: SCons does not know how to construct project files for other languages (e.g. .csproj for C#, .vbproj for Visual Basic or .pyproject for Python). 🙈

For the .vcxproj file, the underlying format is the MSBuild XML Schema, and the details conform to:

https://learn.microsoft.com/en-us/cpp/build/reference/vcxproj-file-structure[3]

The generated solution file enables Visual Studio to understand the project structure, and allows building it using MSBuild to call back to SCons. The project file encodes a toolset version that has been selected by SCons as described above. Since recent Visual Studio versions support multiple concurrent toolsets, use $MSVC_VERSION to select the desired one if it does not match the SCons default. The project file also includes entries which describe how to call SCons to build the project from within Visual Studio (or from an MSBuild command line). In some situations SCons may generate this incorrectly — notably when using the scons-local distribution, which is not installed in a way that matches the default invocation line. If so, the $SCONS_HOME construction variable can be used to describe the right way to locate the SCons code so that it can be imported. 🫶

By default, a matching solution file for the project is also generated. This behavior may be disabled by specifying auto_build_solution=0 to the MSVSProject builder. The solution file can also be independently generated by calling the MSVSSolution builder, such as in the case where a solution should describe multiple projects. See the MSVSSolution description for further information. 💅

The MSVSProject builder accepts several keyword arguments describing lists of filenames to be placed into the project file. Currently, srcs, incs, localincs, resources, and misc are recognized. The names are intended to be self-explanatory, but bestie pls note that the filenames need to be specified as strings, not as SCons File Nodes (for example if you generate files for inclusion by using the Glob function, the results should be converted to a list of strings before passing them to MSVSProject). This is because Visual Studio and MSBuild know literally nothing about SCons Node types. 😭 Each of the filename lists are individually optional, but at least one list must be specified for the resulting project file to be non-empty.

In addition to the above lists of values, the following values may be specified as keyword arguments:

`target` 🎯

The name of the target .dsp or .vcproj file. The correct suffix for the version of Visual Studio must be used, but the $MSVSPROJECTSUFFIX construction variable will be defined to the correct value (see example below).

`variant` 🌈

The name of this particular variant. Except for Visual Studio 6 projects, this can also be a list of variant names. These are typically things like "Debug" or "Release", but really can be anything you want. For Visual Studio 7 projects, they may also specify a target platform separated from the variant name by a | (vertical pipe) character: Debug|Xbox. The default target platform is Win32. Multiple calls to MSVSProject with different variants are allowed; all variants will be added to the project file with their appropriate build targets and sources.

`cmdargs` ⌨️

Additional command line arguments for the different variants. The number of cmdargs entries must match the number of variant entries, or be empty (not specified). If you give only one, it will automatically be propagated to all variants.

`cppdefines` 📝

Preprocessor definitions for the different variants. The number of cppdefines entries must match the number of variant entries, or be empty (not specified). If you give only one, it will automatically be propagated to all variants. If you don't give this parameter, SCons will use the invoking environment's $CPPDEFINES entry for all variants.

`cppflags` 🚩

Compiler flags for the different variants. If a /std:c++ flag is found then /Zc:__cplusplus is appended to the flags if not already found, this ensures that Intellisense uses the /std:c++ switch. The number of cppflags entries must match the number of variant entries, or be empty (not specified). If you give only one, it will automatically be propagated to all variants. If you don't give this parameter, SCons will combine the invoking environment's $CCFLAGS, $CXXFLAGS, $CPPFLAGS entries for all variants.

`cpppaths` 📂

Compiler include paths for the different variants. The number of cpppaths entries must match the number of variant entries, or be empty (not specified). If you give only one, it will automatically be propagated to all variants. If you don't give this parameter, SCons will use the invoking environment's $CPPPATH entry for all variants.

`buildtarget` 🛠️

An optional string, node, or list of strings or nodes (one per build variant), to tell the Visual Studio debugger what output target to use in what build variant. The number of buildtarget entries must match the number of variant entries.

`runfile` 🏃

The name of the file that Visual Studio 7 and later will run and debug. This appears as the value of the Output field in the resulting Microsoft Visual C++ project file. If this is not specified, the default is the same as the specified buildtarget value.

Note 🚨 SCons and Microsoft Visual Studio understand projects in different ways, and the mapping is sometimes imperfect: - Because SCons always executes its build commands from the directory in which the SConstruct file is located, if you generate a project file in a different directory than the directory of the SConstruct file, users will not be able to double-click on the file name in compilation error messages displayed in the Visual Studio console output window. This can be remedied by adding the Microsoft Visual C++ /FC compiler option to the $CCFLAGS variable so that the compiler will print the full path name of any files that cause compilation errors. - If the project file is only used to teach the Visual Studio project browser about the file layout there should be no issues. However, Visual Studio should not be used to make changes to the project structure, build options, etc. as these will (a) not feed back to the SCons description of the project and (b) be lost if SCons regenerates the project file. The SConscript files should remain the definitive description of the build. 💯

And okay bestie, real talk about the whole "project file drives MSBuild" sitch 💅 — if you let the project file run the show (like when you pick "build" from the Visual Studio interface), you straight up lose that direct control over target selection and command-line options you'd totally have if you launched the build right from SCons. Why? Because all of it gets hard-coded into the project file with the exact values you passed to the MSVSProject call. Not the vibe. BUT — you can claw some of that control back by defining multiple variants and firing off multiple MSVSProject calls to line up different build targets, arguments, defines, flags and paths for each variant. Slay 💅.

And if the build gets split into a solution with a bunch of MSBuild projects? The mapping gets e v e n more strained 😭. In that case it is important not to set Visual Studio to do parallel builds — because it'll then launch the separate project builds in parallel, and SCons does not work well if you call it that way. Instead, set up the SCons build for parallel building — peep the SetOption function for how to do this with num_jobs. 🫶

Example usage:

barsrcs = ['bar.cpp']
barincs = ['bar.h']
barlocalincs = ['StdAfx.h']
barresources = ['bar.rc', 'resource.h']
barmisc = ['bar_readme.txt']

dll = env.SharedLibrary(target='bar.dll', source=barsrcs)
buildtarget = [s for s in dll if str(s).endswith('dll')]
env.MSVSProject(
    target='Bar' + env['MSVSPROJECTSUFFIX'],
    srcs=barsrcs,
    incs=barincs,
    localincs=barlocalincs,
    resources=barresources,
    misc=barmisc,
    buildtarget=buildtarget,
    variant='Release',
)

`DebugSettings` 🎀

A dictionary of debug settings that get written to the .vcproj.user or the .vcxproj.user file, depending on the version installed. Same energy as cmdargs — you can specify a DebugSettings dictionary per variant. If you only give one, it will be propagated to all variants. Iconic ✨

Changed in version 2.4: Added the optional DebugSettings parameter.

Currently, only Visual Studio v9.0 and Visual Studio version v11 are implemented — for other versions, no file is generated. To generate the user file, you just need to add a DebugSettings dictionary to the environment with the right parameters for your MSVS version. If the dictionary is empty, or does not contain any good value, no file will be generated 💀.

Following is a more contrived example, involving the setup of a project for variants and DebugSettings:

# Assuming you store your defaults in a file
vars = Variables('variables.py')
msvcver = vars.args.get('vc', '9')

# Check command args to force one Microsoft Visual Studio version
if msvcver == '9' or msvcver == '11':
    env = Environment(MSVC_VERSION=msvcver + '.0', MSVC_BATCH=False)
else:
    env = Environment()

AddOption(
    '--userfile',
    action='store_true',
    dest='userfile',
    default=False,
    help="Create Visual C++ project file",
)

#
# 1. Configure your Debug Setting dictionary with options you want in the list
# of allowed options, for instance if you want to create a user file to launch
# a specific application for testing your dll with Microsoft Visual Studio 2008 (v9):
#
V9DebugSettings = {
    'Command': 'c:\\myapp\\using\\thisdll.exe',
    'WorkingDirectory': 'c:\\myapp\\using\\',
    'CommandArguments': '-p password',
    # 'Attach':'false',
    # 'DebuggerType':'3',
    # 'Remote':'1',
    # 'RemoteMachine': None,
    # 'RemoteCommand': None,
    # 'HttpUrl': None,
    # 'PDBPath': None,
    # 'SQLDebugging': None,
    # 'Environment': '',
    # 'EnvironmentMerge':'true',
    # 'DebuggerFlavor': None,
    # 'MPIRunCommand': None,
    # 'MPIRunArguments': None,
    # 'MPIRunWorkingDirectory': None,
    # 'ApplicationCommand': None,
    # 'ApplicationArguments': None,
    # 'ShimCommand': None,
    # 'MPIAcceptMode': None,
    # 'MPIAcceptFilter': None,
}

#
# 2. Because there are a lot of different options depending on the Microsoft
# Visual Studio version, if you use more than one version you have to
# define a dictionary per version, for instance if you want to create a user
# file to launch a specific application for testing your dll with Microsoft
# Visual Studio 2012 (v11):
#
V10DebugSettings = {
    'LocalDebuggerCommand': 'c:\\myapp\\using\\thisdll.exe',
    'LocalDebuggerWorkingDirectory': 'c:\\myapp\\using\\',
    'LocalDebuggerCommandArguments': '-p password',
    # 'LocalDebuggerEnvironment': None,
    # 'DebuggerFlavor': 'WindowsLocalDebugger',
    # 'LocalDebuggerAttach': None,
    # 'LocalDebuggerDebuggerType': None,
    # 'LocalDebuggerMergeEnvironment': None,
    # 'LocalDebuggerSQLDebugging': None,
    # 'RemoteDebuggerCommand': None,
    # 'RemoteDebuggerCommandArguments': None,
    # 'RemoteDebuggerWorkingDirectory': None,
    # 'RemoteDebuggerServerName': None,
    # 'RemoteDebuggerConnection': None,
    # 'RemoteDebuggerDebuggerType': None,
    # 'RemoteDebuggerAttach': None,
    # 'RemoteDebuggerSQLDebugging': None,
    # 'DeploymentDirectory': None,
    # 'AdditionalFiles': None,
    # 'RemoteDebuggerDeployDebugCppRuntime': None,
    # 'WebBrowserDebuggerHttpUrl': None,
    # 'WebBrowserDebuggerDebuggerType': None,
    # 'WebServiceDebuggerHttpUrl': None,
    # 'WebServiceDebuggerDebuggerType': None,
    # 'WebServiceDebuggerSQLDebugging': None,
}

#
# 3. Select the dictionary you want depending on the version of Visual Studio
# Files you want to generate.
#
if not env.GetOption('userfile'):
    dbgSettings = None
elif env.get('MSVC_VERSION', None) == '9.0':
    dbgSettings = V9DebugSettings
elif env.get('MSVC_VERSION', None) == '11.0':
    dbgSettings = V10DebugSettings
else:
    dbgSettings = None

#
# 4. Add the dictionary to the DebugSettings keyword.
#
barsrcs = ['bar.cpp', 'dllmain.cpp', 'stdafx.cpp']
barincs = ['targetver.h']
barlocalincs = ['StdAfx.h']
barresources = ['bar.rc', 'resource.h']
barmisc = ['ReadMe.txt']

dll = env.SharedLibrary(target='bar.dll', source=barsrcs)

env.MSVSProject(
    target='Bar' + env['MSVSPROJECTSUFFIX'],
    srcs=barsrcs,
    incs=barincs,
    localincs=barlocalincs,
    resources=barresources,
    misc=barmisc,
    buildtarget=[dll[0]] * 2,
    variant=('Debug|Win32', 'Release|Win32'),
    cmdargs=f'vc={msvcver}',
    DebugSettings=(dbgSettings, {}),
)

`MSVSSolution()`, `env.MSVSSolution()` 🌈

Build a Microsoft Visual Studio Solution file. Fr fr.

It builds a Visual Studio solution file based on whichever version of Visual Studio is configured: either the latest installed version, or the version specified by $MSVC_VERSION in the construction environment. For Visual Studio 6, a .dsw file is generated. For Visual Studio .NET 2002 and later, it will generate a .sln file. Heads up though — there are multiple versioning schemes involved in the Microsoft compilation environment, so go check the description of $MSVC_VERSION for the equivalences 👀.

The solution file is a container for one or more projects, and follows the format described at https://learn.microsoft.com/en-us/visualstudio/extensibility/internals/solution-dot-sln-file[4].

The following values must be specified:

target — the name of the target .dsw or .sln file. You gotta use the correct suffix for your version of Visual Studio, but $MSVSSOLUTIONSUFFIX will be defined to the correct value for you (see the example below 💖).
variant — the name of this particular variant, or a list of variant names (the list version is only supported for MSVS 7 solutions). These are typically things like "Debug" or "Release", but honestly they can be anything you want. For MSVS 7 they may also specify a target platform, like this: "Debug|Xbox". Default platform is Win32.
projects — a list of project file names, or Project nodes returned by calls to the MSVSProject Builder, to be placed into the solution file. Note that these filenames need to be specified as strings, NOT as SCons File Nodes. Why? Because the solution file will be interpreted by MSBuild and by Visual Studio, which know nothing about SCons Node types. Sorry bestie, them's the rules 🙈.

In addition to the mandatory arguments above, the following optional values may be specified as keyword arguments:

auto_filter_projects — under certain circumstances, solution file names or solution file nodes may be present in the projects argument list. When solution file names or nodes are present in the projects argument list, the generated solution file may contain erroneous Project records, resulting in VS IDE error messages when opening the generated solution file 😭. By default, an exception is raised when a solution file name or solution file node is detected in the projects argument list.

The accepted values for auto_filter_projects are:

None — an exception is raised when a solution file name or solution file node is detected in the projects argument list.

None is the default value.

True or evaluates True — automatically remove solution file names and solution file nodes from the projects argument list.
False or evaluates False — leave the solution file names and solution file nodes in the projects argument list. An exception is not raised.

When you open that generated solution file in the VS IDE, bestie, the IDE will very likely be like "um these Project records are erroneous, not supported, or need to be modified" — so heads up, that's just a thing that happens. 🙈

Example Usage:

env.MSVSSolution(
    target="Bar" + env["MSVSSOLUTIONSUFFIX"],
    projects=["bar" + env["MSVSPROJECTSUFFIX"]],
    variant="Release",
)

Ninja(), env.Ninja() 🥷

A special builder that literally just adds a target to create a Ninja build file. It does not require any source files to be specified. Iconic behavior honestly.

Note 💀 This is an experimental feature. To enable it you must use one of the following methods:

# On the command line
--experimental=ninja

# Or in your SConstruct
SetOption('experimental', 'ninja')

This functionality is subject to change and/or removal without a deprecation cycle. So like… don't build your whole life on it, fr fr. 😭

To use this tool you need to install the Python ninja package, because the tool by default depends on being able to do an import of the package. This can be done via:

python -m pip install ninja

Okay so the target-name lore:

If called with no arguments, the builder defaults to a target name of ninja.build.
If called with a single positional argument, SCons will "deduce" the target name from that source argument, giving it the same name, and then ignore the source. This is the usual way to call the builder if you want a non-default target name.
If called with either the target= or source= keyword arguments, the value of the argument is taken as the target name. If you call it with both, the target= value wins and source= gets ignored. If you call it with multiple sources, the source list gets ignored entirely, since there's no way to deduce what the intent was — in that case the default target name is used.

Available since scons 4.2. 🎀

Object(), env.Object() 🧸

A synonym for the StaticObject builder method. That's it, that's the whole vibe. Short king.

Package(), env.Package() 📦

Builds software distribution packages. A package is a container format which includes files to install along with metadata. Packaging is optional, and must be enabled by specifying the packaging tool. For example:

env = Environment(tools=['default', 'packaging'])

SCons can build packages in a number of well known packaging formats. The target package type may be selected with the $PACKAGETYPE construction variable or the --package-type command line option. The package type may be a list, in which case SCons will attempt to build packages for each type in the list. Example:

env.Package(PACKAGETYPE=['src_zip', 'src_targz'], ...other args...)

The currently supported packagers are:

msi — Microsoft Installer package
rpm — RPM Package Manager package
ipkg — Itsy Package Management package
tarbz2 — bzip2-compressed tar file
targz — gzip-compressed tar file
tarxz — xz-compressed tar file
zip — zip file
src_tarbz2 — bzip2-compressed tar file suitable as source to another packager
src_targz — gzip-compressed tar file suitable as source to another packager
src_tarxz — xz-compressed tar file suitable as source to another packager
src_zip — zip file suitable as source to another packager

The file list to include in the package may be specified with the source keyword argument. If omitted, the FindInstalledFiles function is called behind the scenes to select all files that have an Install, InstallAs or InstallVersionedLib Builder attached. If the target keyword argument is omitted, the target name(s) will be deduced from the package type(s).

The metadata comes partly from attributes of the files to be packaged, and partly from packaging tags. Tags can be passed as keyword arguments to the Package builder call, and may also be attached to files (or more accurately, Nodes representing files) with the Tag function. Some package-level tags are mandatory, and will lead to errors if omitted. The mandatory tags vary depending on the package type. So like… read the room (and the package type) before you skip tags. 💅

While packaging, the builder uses a temporary location named by the value of the $PACKAGEROOT variable — the package sources are copied there before packaging. ✨

Packaging example:

env = Environment(tools=["default", "packaging"])
env.Install("/bin/", "my_program")
env.Package(
    NAME="foo",
    VERSION="1.2.3",
    PACKAGEVERSION=0,
    PACKAGETYPE="rpm",
    LICENSE="gpl",
    SUMMARY="balalalalal",
    DESCRIPTION="this should be really really long",
    X_RPM_GROUP="Application/fu",
    SOURCE_URL="https://foo.org/foo-1.2.3.tar.gz",
)

In this example, the target /bin/my_program created by the Install call would not be built by default since it is not under the project top directory. However, since no source is specified to the Package builder, it is selected for packaging by the default sources rule. Since packaging is done using $PACKAGEROOT, no write is actually done to the system's /bin directory, and the target will be selected since after rebasing to underneath $PACKAGEROOT it is now under the top directory of the project. No cap, it works out. 🫶

PCH(), env.PCH() 🧠

Builds a Microsoft Visual C++ precompiled header. Calling this builder returns a list of two target nodes: the PCH as the first element, and the object file as the second element. Normally the object file is ignored. The PCH builder is generally used in conjunction with the $PCH construction variable to force object files to use the precompiled header:

env['PCH'] = env.PCH('StdAfx.cpp')[0]

Note ⚠️ This builder is specific to the PCH implementation in Microsoft Visual C++. Other compiler chains also implement precompiled header support, but PCH does not work with them at this time. As a result, the builder is only generated into the construction environment when Microsoft Visual C++ is being used as the compiler.

Note 💀 The builder only works correctly in a C++ project. The Microsoft implementation distinguishes between precompiled headers from C and C++. Use of the builder will cause the PCH generation to happen with a flag that tells cl.exe all of the files are C++ files; if that PCH file is then supplied when compiling a C source file, cl.exe will fail the build with a compatibility violation. Not a cute look.

If possible, arrange the project so that a C++ source file passed to the PCH builder is not also included in the list of sources to be otherwise compiled in the project. SCons will correctly track that file in the dependency tree as a result of the PCH call, and (for MSVC 11.0 and greater) automatically add the corresponding object file to the link line. If the source list is automatically generated, for example using the Glob function, it may be necessary to remove that file from the list. Bestie, just pluck it out. 🌸

PDF(), env.PDF() 🦋

Builds a .pdf file from a .dvi input file (or, by extension, a .tex, .ltx, or .latex input file). The suffix specified by the $PDFSUFFIX construction variable (.pdf by default) is added automatically to the target if it is not already present. PDF is a single-source builder. Example:

# builds from aaa.tex
env.PDF(target = 'aaa.pdf', source = 'aaa.tex')
# builds bbb.pdf from bbb.dvi
env.PDF(target = 'bbb', source = 'bbb.dvi')

POInit(), env.POInit() 🌈

This builder is set up by the msginit tool. The builder initializes missing PO file(s) if $POAUTOINIT is set. If $POAUTOINIT is not set (the default), POInit prints instruction for the user (such as a translator), telling how the PO file should be initialized. In normal projects you should not use POInit and use POUpdate instead. POUpdate chooses intelligently between msgmerge(1) and msginit(1). POInit always uses msginit(1) and should be regarded as builder for special purposes or for temporary use (e.g. for quick, one time initialization of a bunch of PO files) or for tests. POInit is a single-source builder. The source parameter can also be omitted if $LINGUAS_FILE is set.

So like, it's the "quick lil side quest" version. Use POUpdate for the main-character run. 👑

Target nodes that you define through POInit are not built by default — they get Ignored from the '.' node, lowkey ghosting the default build 💅 — but they do get added to a special Alias called 'po-create' (that's the default name, you can rename it whenever). Wanna change that alias name? Set the $POCREATE_ALIAS construction variable, easy. And every single PO file you define through POInit can be initialized in one go with scons po-create. Iconic.

Example 1. Initialize en.po and pl.po from messages.pot:

env.POInit(['en', 'pl']) # messages.pot --> [en.po, pl.po]

Example 2. Initialize en.po and pl.po from foo.pot:

env.POInit(['en', 'pl'], ['foo']) # foo.pot --> [en.po, pl.po]

Example 3. Initialize en.po and pl.po from foo.pot, but this time using the $POTDOMAIN construction variable:

env.POInit(['en', 'pl'], POTDOMAIN='foo') # foo.pot --> [en.po, pl.po]

Example 4. Initialize PO files for whatever languages are defined in the LINGUAS file. These files get initialized from the template messages.pot:

env.POInit(LINGUAS_FILE=True)  # needs 'LINGUAS' file

Example 5. Initialize en.po and pl.pl PO files plus files for the languages defined in the LINGUAS file. Again, everything initializes from the template messages.pot:

env.POInit(['en', 'pl'], LINGUAS_FILE=True)

Example 6. You can preconfigure your environment first and then initialize the PO files, bestie:

env['POAUTOINIT'] = True
env['LINGUAS_FILE'] = True
env['POTDOMAIN'] = 'foo'
env.POInit()

which has same efect as:

env.POInit(POAUTOINIT=True, LINGUAS_FILE=True, POTDOMAIN='foo')

PostScript(), env.PostScript()

Builds a .ps file from a .dvi input file — or, by extension, from a .tex, .ltx, or .latex input file. The suffix specified by the $PSSUFFIX construction variable (.ps by default, duh) gets added automatically to the target if it's not already there. PostScript is a single-source builder. Periodt. Example:

# builds from aaa.tex
env.PostScript(target = 'aaa.ps', source = 'aaa.tex')
# builds bbb.ps from bbb.dvi
env.PostScript(target = 'bbb', source = 'bbb.dvi')

POTUpdate(), env.POTUpdate()

This builder gets set up by the xgettext tool, which is part of the gettext toolset. It updates the target POT file if it exists, or creates it if it doesn't — no cap. 🫶

The target node is not selected for building by default (like, scons . won't touch it), only on demand — i.e. when that given POT file is required, or when you invoke the special alias. This builder adds its target node (say, messages.pot) to a special alias (pot-update by default, peep $POTUPDATE_ALIAS) so you can update/create them super easily with scons pot-update. 🌸

The file is not written until there is no real change in the internationalized messages (or in comments that enter the POT file).

Note 💀 You may see xgettext(1) being invoked by the xgettext tool even if there is no real change in the internationalized messages (so the POT file isn't actually being updated). This happens every time a source file has changed. In such case we invoke xgettext(1) and compare its output with the content of the POT file to decide whether the file should be updated or not.

Example 1. Let's create a po/ directory and drop this following SConstruct script in there:

# SConstruct in 'po/' subdir
env = Environment(tools=['default', 'xgettext'])
env.POTUpdate(['foo'], ['../a.cpp', '../b.cpp'])
env.POTUpdate(['bar'], ['../c.cpp', '../d.cpp'])

Then invoke scons a few times:

$ scons             # Does not create foo.pot nor bar.pot
$ scons foo.pot     # Updates or creates foo.pot
$ scons pot-update  # Updates or creates foo.pot and bar.pot
$ scons -c          # Does not clean foo.pot nor bar.pot.

and the results shall be exactly as the comments above say. Slay. ✨

Example 2. The target argument can be omitted, in which case the default target name messages.pot is used. The target may also be overridden by setting the $POTDOMAIN construction variable, or by providing it as an override to the POTUpdate builder:

# SConstruct script
env = Environment(tools=['default', 'xgettext'])
env['POTDOMAIN'] = "foo"
env.POTUpdate(source=["a.cpp", "b.cpp"])  # Creates foo.pot ...
env.POTUpdate(POTDOMAIN="bar", source=["c.cpp", "d.cpp"])  # and bar.pot

Example 3. The source parameter may also be omitted, if it's specified in a separate file — for example POTFILES.in:

# POTFILES.in in 'po/' subdirectory
../a.cpp
../b.cpp
# end of file

The name of the file (POTFILES.in) containing the list of sources is provided via $XGETTEXTFROM:

# SConstruct file in 'po/' subdirectory
env = Environment(tools=['default', 'xgettext'])
env.POTUpdate(XGETTEXTFROM='POTFILES.in')

Example 4. You can use $XGETTEXTPATH to define the source search path. Assume, for example, that you have files a.cpp, b.cpp, po/SConstruct, po/POTFILES.in. Then your POT-related files could look like this:

# POTFILES.in in 'po/' subdirectory
a.cpp
b.cpp
# end of file

# SConstruct file in 'po/' subdirectory
env = Environment(tools=['default', 'xgettext'])
env.POTUpdate(XGETTEXTFROM='POTFILES.in', XGETTEXTPATH='../')

Example 5. Multiple search directories may be defined as a list, i.e. XGETTEXTPATH=['dir1', 'dir2', ...]. The order in the list determines the search order of source files, and the path to the first file found is the one that gets used. 🦋

Let's create a 0/1/po/SConstruct script:

# SConstruct file in '0/1/po/' subdirectory
env = Environment(tools=['default', 'xgettext'])
env.POTUpdate(XGETTEXTFROM='POTFILES.in', XGETTEXTPATH=['../', '../../'])

and 0/1/po/POTFILES.in:

# POTFILES.in in '0/1/po/' subdirectory
a.cpp
# end of file

Write two *.cpp files — the first one is 0/a.cpp:

/* 0/a.cpp */
gettext("Hello from ../../a.cpp")

and the second is 0/1/a.cpp:

/* 0/1/a.cpp */
gettext("Hello from ../a.cpp")

then run scons. You'll obtain 0/1/po/messages.pot with the message "Hello from ../a.cpp". When you reverse the order in $XGETTEXTFOM, i.e. when you write the SConscript as

# SConstruct file in '0/1/po/' subdirectory
env = Environment(tools=['default', 'xgettext'])
env.POTUpdate(XGETTEXTFROM='POTFILES.in', XGETTEXTPATH=['../../', '../'])

then the messages.pot will contain the msgid "Hello from ../../a.cpp" line and not msgid "Hello from ../a.cpp". Main character energy in the search path, honestly. 💅

POUpdate(), env.POUpdate()

This builder is set up by the msgmerge tool, part of the gettext toolset. It updates PO files with msgmerge(1), or initializes missing PO files exactly as described in the documentation of the msginit tool and the POInit builder (see also $POAUTOINIT). POUpdate is a single-source builder. The source parameter can also be omitted if $LINGUAS_FILE is set. 👑

The target nodes are not selected for building by default (like scons ., nope). Instead, they're added automatically to a special Alias ('po-update' by default). That alias name may be changed through the $POUPDATE_ALIAS construction variable. You can easily update PO files in your project by running scons po-update. Note that POUpdate does not add its targets to the po-create alias the way POInit does. Different builder, different vibe. 🎀

Example 1. Update en.po and pl.po from the messages.pot template (see also $POTDOMAIN), assuming that the latter exists or that there's a rule to build it (see POTUpdate):

env.POUpdate(['en','pl'])  # messages.pot --> [en.po, pl.po]

Example 2. Update en.po and pl.po from the foo.pot template:

env.POUpdate(['en', 'pl'], ['foo'])  # foo.pot -->  [en.po, pl.pl]

Example 3. Update en.po and pl.po from foo.pot (another version):

env.POUpdate(['en', 'pl'], POTDOMAIN='foo')  # foo.pot -- > [en.po, pl.pl]

Example 4. Update files for languages defined in the LINGUAS file. The files are updated from the messages.pot template:

env.POUpdate(LINGUAS_FILE=True)  # needs 'LINGUAS' file

Example 5. Same as above, but updating from the foo.pot template:

env.POUpdate(LINGUAS_FILE=True, source=['foo'])

Example 6. Update en.po and pl.po plus files for languages defined in the LINGUAS file. The files are updated from the messages.pot template:

# produce 'en.po', 'pl.po' + files defined in 'LINGUAS':
env.POUpdate(['en', 'pl' ], LINGUAS_FILE=True)

Example 7. Use $POAUTOINIT to automatically initialize a PO file if it doesn't exist:

env.POUpdate(LINGUAS_FILE=True, POAUTOINIT=True)

Example 8. Update PO files for languages defined in the LINGUAS file. The files are updated from the foo.pot template. All necessary settings are pre-configured via the environment.

env['POAUTOINIT'] = True
env['LINGUAS_FILE'] = True
env['POTDOMAIN'] = 'foo'
env.POUpdate()

Program(), env.Program()

Builds an executable given one or more object files, or C, C++, D, or Fortran source files. If you throw any C, C++, D or Fortran source files at it, they'll automatically be compiled to object files using the Object builder method — go read that builder method's description for the list of legal source file suffixes and how they get interpreted, iykyk. 😌

The target executable file prefix, specified by the $PROGPREFIX construction variable (nothing by default), and the suffix, specified by the $PROGSUFFIX construction variable (.exe on Windows systems by default, nothing on POSIX systems), are automatically added to the target if not already present. Example:

env.Program(target='foo', source=['foo.o', 'bar.c', 'baz.f'])

ProgramAllAtOnce(), env.ProgramAllAtOnce()

Builds an executable from D sources without first creating individual objects for each file. 🔥

D sources can be compiled file-by-file just like C and C++ sources are, and D is integrated into the scons Object and Program builders for this model of build. But D code can do whole-source meta-programming (some of the testing frameworks do this, bestie). For that, it is imperative that all sources are compiled and linked in a single call to the D compiler. This builder serves that purpose.

env.ProgramAllAtOnce('executable', ['mod_a.d, mod_b.d', 'mod_c.d'])

This command will compile the modules mod_a, mod_b, and mod_c in a single compilation process, no object files created first, we're just going straight there, bestie. Lowkey important: some of the D compilers will create executable.o and others will not. That's just how it is. 🙈

RES(), `env.RES()`

Builds a Microsoft Visual C++ resource file. Okay so real talk: this builder method only even shows up when Microsoft Visual C++ or MinGW is your compiler. The .res suffix (or .o for MinGW, quirky ik) gets added to the target name if you didn't give one. The source file gets scanned for implicit dependencies as though it were a C file. Example:

env.RES('resource.rc')

RMIC(), `env.RMIC()`

Builds stub and skeleton class files for remote objects, sourcing from Java .class files. The target here is a directory, and it's relative to that directory where the stub and skeleton class files get written. Your source can be the names of .class files, or the objects returned from the Java builder method.

If the construction variable $JAVACLASSDIR is set — either in the environment or right there in the call to the RMIC builder method itself — then that variable's value gets stripped from the beginning of any .class file names. Chef's kiss, very tidy.

classes = env.Java(target='classdir', source='src')
env.RMIC(target='outdir1', source=classes)
env.RMIC(
    target='outdir2',
    source=['package/foo.class', 'package/bar.class'],
)
env.RMIC(
    target='outdir3',
    source=['classes/foo.class', 'classes/bar.class'],
    JAVACLASSDIR='classes',
)

RPCGenClient(), `env.RPCGenClient()`

Generates an RPC client stub (_clnt.c) file from a specified RPC (.x) source file. Because rpcgen only builds output files in the local directory, the command will be executed in the source file's directory by default. (Always working in its own little local era, we respect it.)

# Builds src/rpcif_clnt.c
env.RPCGenClient('src/rpcif.x')

RPCGenHeader(), `env.RPCGenHeader()`

Generates an RPC header (.h) file from a specified RPC (.x) source file. And yeah, because rpcgen only builds output files in the local directory, the command gets executed in the source file's directory by default.

# Builds src/rpcif.h
env.RPCGenHeader('src/rpcif.x')

RPCGenService(), `env.RPCGenService()`

Generates an RPC server-skeleton (_svc.c) file from a specified RPC (.x) source file. Same deal, the rpcgen local-directory thing means the command runs in the source file's directory by default.

# Builds src/rpcif_svc.c
env.RPCGenClient('src/rpcif.x')

RPCGenXDR(), `env.RPCGenXDR()`

Generates an RPC XDR routine (_xdr.c) file from a specified RPC (.x) source file. And once again bestie, rpcgen only builds output files in the local directory, so the command will be executed in the source file's directory by default.

# Builds src/rpcif_xdr.c
env.RPCGenClient('src/rpcif.x')

SharedLibrary(), `env.SharedLibrary()`

Builds a shared library from one or more object files and/or C, C++, D or Fortran source files. Any source files you list in the source parameter get automatically compiled into object files suitable for use in a shared library. Any object files you list in source must have been built for a shared library (that's your cue to use the SharedObject builder method). And if there's any mismatch? scons will raise an error. No cap, it will yell. 😭

The target library file prefix, specified by the $SHLIBPREFIX construction variable (by default lib on POSIX systems, nothing on Windows systems), and the suffix, specified by the $SHLIBSUFFIX construction variable (by default .dll on Windows systems, .so on POSIX systems), are automatically added (if not already present) to the target name to make up the library filename. On a POSIX system, if the $SHLIBVERSION construction variable is set, it gets appended (following a period) to the resulting library name. Cute.

Example:

env.SharedLibrary(target='bar', source=['bar.c', 'foo.o'])

On Windows systems, the SharedLibrary builder method will always build an import library (.lib) in addition to the shared library (.dll), adding a .lib library with the same basename if there isn't already a .lib file explicitly listed in the targets.

On Cygwin systems, the SharedLibrary builder method will always build an import library (.dll.a) in addition to the shared library (.dll), adding a .dll.a library with the same basename if there isn't already a .dll.a file explicitly listed in the targets.

On some platforms, there's a distinction between a shared library (loaded automatically by the system to resolve external references) and a loadable module (explicitly loaded by user action). For maximum portability, use the LoadableModule builder for the latter. K thx.

If $SHLIBVERSION is defined, a versioned shared library is created. This does three things: modifies $SHLINKFLAGS as required, adds the version number to the library name, and creates any symbolic links that are needed. It's giving organized. ✨

env.SharedLibrary(target='bar', source=['bar.c', 'foo.o'], SHLIBVERSION='1.5.2')

On a POSIX system, supplying a simple version string (no dots) creates exactly one symbolic link: SHLIBVERSION="1" would create (for example) library libbar.so.1 and symbolic link libbar.so. Supplying a dotted version string will create two symbolic links (irrespective of the number of segments in the version): SHLIBVERSION="1.5.2" for the same library would create library libbar.so.1.5.2 and symbolic links libbar.so and libbar.so.1. A Darwin (OSX) system creates one symlink in either case — for the second example the library would be libbar.1.5.2.dylib and the link would be libbar.dylib.

On Windows systems, specifying the register=1 keyword argument will cause the .dll to be registered after it is built. The command that is run is determined by the $REGSVR construction variable (regsvr32 by default), and the flags passed are determined by $REGSVRFLAGS. By default, $REGSVRFLAGS includes the /s option, to prevent dialogs from popping up and requiring user attention when it is run. If you change $REGSVRFLAGS, be sure to include the /s option. For example,

env.SharedLibrary(target='bar', source=['bar.cxx', 'foo.obj'], register=1)

will register bar.dll as a COM object when it is done linking it.

SharedObject(), `env.SharedObject()`

Builds an object file intended for inclusion in a shared library. Source files must have one of the same set of extensions specified for the StaticObject builder method. The target object file prefix, specified by the $SHOBJPREFIX construction variable (by default, the same as $OBJPREFIX), and suffix, specified by the $SHOBJSUFFIX construction variable, are automatically added to the target if they're not already present. SharedObject is a single-source builder. Examples:

env.SharedObject(target='ddd', source='ddd.c')
env.SharedObject(target='eee.o', source='eee.cpp')
env.SharedObject(target='fff.obj', source='fff.for')
env.SharedObject(source=Glob('*.c'))

On some platforms building a shared object requires additional compiler option(s) (e.g. -fPIC for gcc) in addition to those needed to build a normal (static) object. If shared and static objects differ, SCons will allow only shared objects to be linked into a shared library, and will use a different suffix for shared objects to help indicate and track the difference. It's literally keeping receipts. 💅

Source files will be scanned according to the suffix mappings in the SourceFileScanner object. See the manpage section "Scanner Objects" for more information.

StaticLibrary(), `env.StaticLibrary()`

Builds a static library given one or more object files or C, C++, D or Fortran source files. If any source files are given, they get automatically compiled to object files. The static library file prefix, specified by the $LIBPREFIX construction variable (by default lib on POSIX systems, nothing on Windows systems), and suffix, specified by the $LIBSUFFIX construction variable (by default .lib on Windows systems, .a on POSIX systems), are automatically added to the target if not already present. Example:

env.StaticLibrary(target='bar', source=['bar.c', 'foo.o'])

Any object files listed in the source must have been built for a static library (that is, using the StaticObject builder method). scons will raise an error if there is any mismatch. 🚨 Watch out for that one.

StaticObject(), `env.StaticObject()`

Builds a static object file from one or more C, C++, D, or Fortran source files. The file extension mapping goes like this:

.asm — assembly language file
.ASM — assembly language file
.c — C file
.C — Windows: C file, POSIX: C++ file
.cc — C++ file
.cpp — C++ file
.cxx — C++ file
.cxx — C++ file
.c++ — C++ file
.C++ — C++ file
.d — D file
.f — Fortran file
.F — Windows: Fortran file, POSIX: Fortran file + C pre-processor
.for — Fortran file
.FOR — Fortran file
.fpp — Fortran file + C pre-processor
.FPP — Fortran file + C pre-processor
.m — Object C file
.mm — Object C++ file
.s — assembly language file
.S — Windows: assembly language file, ARM: CodeSourcery Sourcery Lite
.sx — assembly language file + C pre-processor, POSIX: assembly language file + C pre-processor
.spp — assembly language file + C pre-processor
.SPP — assembly language file + C pre-processor

The target object file prefix, specified by the $OBJPREFIX construction variable (empty string by default), and suffix, specified by the $OBJSUFFIX construction variable (.obj on Windows systems, .o on POSIX systems), are automatically added to the target if not already present. StaticObject is a single-source builder. Examples:

env.StaticObject(target='aaa', source='aaa.c')
env.StaticObject(target='bbb.o', source='bbb.c++')
env.StaticObject(target='ccc.obj', source='ccc.f')
env.StaticObject(source=Glob('*.c'))

Source files will be scanned according to the suffix mappings in the SourceFileScanner object. Wanna know what that even means? Go peek at the manpage section "Scanner Objects" for more info, bestie. 💅

✨ `Substfile()`, `env.Substfile()` ✨

Okay so the Substfile builder takes a template — one file, or a whole set of files (or nodes, she's flexible 🫶) — and spits out a single text file, swapping text around using the $SUBST_DICT construction variable (if it's set, that is). If you hand her a set of sources, they get concatenated into the target file, separated by the value of the $LINESEPARATOR construction variable — and listen, that separator does not get emitted after the last file's content. Nested lists of source files? Flattened, periodt. Also peep Textfile if you want the cousin builder. 🌸

By default the target file encoding is "utf-8" and you can change it with $FILE_ENCODING. Examples:

If you give her just one source file name and it's got a .in suffix, that suffix gets stripped and whatever's left of the name becomes the default target name. Iconic behavior. ✨

The prefix and suffix from the $SUBSTFILEPREFIX and $SUBSTFILESUFFIX construction variables (both an empty string by default) get automatically added to the target — but only if they're not already there. She checks. 👑

If a construction variable named $SUBST_DICT is present, it can be either a Python dictionary or a sequence of (key, value) tuples. Here's the tea: if it's a dictionary, it gets converted into a list of tuples with unspecified order, so if one key is a prefix of another key, or if one substitution could get further expanded by another substitution — bestie, it is simply unpredictable whether the expansion will even occur. 💀

Any occurrences of a key in the source get replaced by the corresponding value, which may be a Python callable function or a string. If the value is a callable, it's called with no arguments to get a string. Strings are subst-expanded, and that result replaces the key. No cap.

env = Environment(tools=['default'])

env['prefix'] = '/usr/bin'
script_dict = {'@prefix@': '/bin', '@exec_prefix@': '$prefix'}
env.Substfile('script.in', SUBST_DICT=script_dict)

conf_dict = {'%VERSION%': '1.2.3', '%BASE%': 'MyProg'}
env.Substfile('config.h.in', conf_dict, SUBST_DICT=conf_dict)

# UNPREDICTABLE - one key is a prefix of another
bad_foo = {'$foo': '$foo', '$foobar': '$foobar'}
env.Substfile('foo.in', SUBST_DICT=bad_foo)

# PREDICTABLE - keys are applied longest first
good_foo = [('$foobar', '$foobar'), ('$foo', '$foo')]
env.Substfile('foo.in', SUBST_DICT=good_foo)

# UNPREDICTABLE - one substitution could be further expanded
bad_bar = {'@bar@': '@soap@', '@soap@': 'lye'}
env.Substfile('bar.in', SUBST_DICT=bad_bar)

# PREDICTABLE - substitutions are expanded in order
good_bar = (('@bar@', '@soap@'), ('@soap@', 'lye'))
env.Substfile('bar.in', SUBST_DICT=good_bar)

# the SUBST_DICT may be in common (and not an override)
substutions = {}
subst = Environment(tools=['textfile'], SUBST_DICT=substitutions)
substitutions['@foo@'] = 'foo'
subst['SUBST_DICT']['@bar@'] = 'bar'
subst.Substfile(
    'pgm1.c',
    [Value('#include "@foo@.h"'), Value('#include "@bar@.h"'), "common.in", "pgm1.in"],
)
subst.Substfile(
    'pgm2.c',
    [Value('#include "@foo@.h"'), Value('#include "@bar@.h"'), "common.in", "pgm2.in"],
)

📦 `Tar()`, `env.Tar()` 📦

Builds a tar archive out of the files and/or directories you tell her about. Here's the special little thing about her: unlike most builder methods, you can call the Tar builder method multiple times for a given target — every extra call just adds to the list of entries that'll get built into the archive. 🎀 Any source directories get scanned for changes to any on-disk files, whether or not scons even knows about them from other Builder or function calls. She's thorough like that.

env.Tar('src.tar', 'src')

# Create the stuff.tar file.
env.Tar('stuff', ['subdir1', 'subdir2'])
# Also add "another" to the stuff.tar file.
env.Tar('stuff', 'another')

# Set TARFLAGS to create a gzip-filtered archive.
env = Environment(TARFLAGS = '-c -z')
env.Tar('foo.tar.gz', 'foo')

# Also set the suffix to .tgz.
env = Environment(TARFLAGS = '-c -z',
                  TARSUFFIX = '.tgz')
env.Tar('foo')

📝 `Textfile()`, `env.Textfile()` 📝

The Textfile builder makes a single text file from a template that's just a list of strings, replacing text using the $SUBST_DICT construction variable (if it's set) — and heads up, Substfile has the full description of how that replacement works, so go read that. The strings get separated in the target file using the value of the $LINESEPARATOR construction variable, and the line separator is not emitted after the last string. Nested lists of source strings? Flattened, naturally. 🦋 And the source strings don't literally have to be Python strings — they can be Nodes, or Python objects that convert cleanly to Value nodes. Versatile queen.

The prefix and suffix from the $TEXTFILEPREFIX and $TEXTFILESUFFIX construction variables (by default an empty string and .txt, respectively 🌈) get automatically added to the target if they're not already present.

By default the target file encoding is "utf-8" and can be changed with $FILE_ENCODING. Examples:

# builds/writes foo.txt
env.Textfile(target='foo.txt', source=['Goethe', 42, 'Schiller'])

# builds/writes bar.txt
env.Textfile(target='bar', source=['lalala', 'tanteratei'], LINESEPARATOR='|*')

# nested lists are flattened automatically
env.Textfile(target='blob', source=['lalala', ['Goethe', 42, 'Schiller'], 'tanteratei'])

# files may be used as input by wrapping them in File()
env.Textfile(
    target='concat',  # concatenate files with a marker between
    source=[File('concat1'), File('concat2')],
    LINESEPARATOR='====================\n',
)

Results, bestie — look what she made ✨:

foo.txt

      Goethe
      42
      Schiller

bar.txt

      lalala|*tanteratei

blob.txt

      lalala
      Goethe
      42
      Schiller
      tanteratei

🌍 `Translate()`, `env.Translate()` 🌍

This pseudo-Builder is part of the gettext toolset. She extracts internationalized messages from source files, updates the POT template (if necessary), and then updates PO translations (if necessary). If $POAUTOINIT is set, missing PO files get automatically created — i.e. without a translator person having to intervene at all. 💅 The variables $LINGUAS_FILE and $POTDOMAIN are taken into account too. And every other construction variable used by POTUpdate and POUpdate works here as well.

Example 1. The simplest way is to specify input files and output languages inline in a SCons script when invoking Translate:

# SConscript in 'po/' directory
env = Environment(tools=["default", "gettext"])
env['POAUTOINIT'] = True
env.Translate(['en', 'pl'], ['../a.cpp', '../b.cpp'])

Example 2. If you wish, you may also stick to the conventional style known from autotools — that is, using POTFILES.in and LINGUAS files to specify the targets and sources:

# LINGUAS
en pl
# end

# POTFILES.in
a.cpp
b.cpp
# end

# SConscript
env = Environment(tools=["default", "gettext"])
env['POAUTOINIT'] = True
env['XGETTEXTPATH'] = ['../']
env.Translate(LINGUAS_FILE=True, XGETTEXTFROM='POTFILES.in')

The last approach is perhaps the recommended one, ngl. It lets you easily split internationalization/localization across separate SCons scripts, where a script in the source tree is responsible for translations (from sources to PO files) and script(s) under variant directories handle compilation of PO to MO files plus installation of MO files. The "gluing factor" that synchronizes these two scripts is the content of the LINGUAS file. Now note this, bestie: the updated POT and PO files are usually going to be committed back to the repository, so they must be updated within the source directory — and not in variant directories. 🙈 Additionally, the file listing of the po/ directory contains the LINGUAS file, so the source tree looks familiar to translators and they may work with the project in their usual way. 😌

Example 3. Let's prepare a development tree as below

 project/
  + SConstruct
  + build/
  + src/
      + po/
          + SConscript
          + SConscript.i18n
          + POTFILES.in
          + LINGUAS

with build being the variant directory. Write the top-level SConstruct script as follows

# SConstruct
env = Environment(tools=["default", "gettext"])
VariantDir('build', 'src', duplicate=False)
env['POAUTOINIT'] = True
SConscript('src/po/SConscript.i18n', exports='env')
SConscript('build/po/SConscript', exports='env')

the src/po/SConscript.i18n as

# src/po/SConscript.i18n
Import('env')
env.Translate(LINGUAS_FILE=True, XGETTEXTFROM='POTFILES.in', XGETTEXTPATH=['../'])

and the src/po/SConscript

# src/po/SConscript
Import('env')
env.MOFiles(LINGUAS_FILE=True)

Such a setup produces POT and PO files under the source tree in src/po/ and binary MO files under the variant tree in build/po/. This way the POT and PO files are separated from other output files, which must not be committed back to source repositories (e.g. MO files).

Note — In the above example, the PO files are not updated, nor created automatically when you issue the command scons ... The files must be updated (created) by hand via scons po-update, and then MO files can be compiled by running scons .. 💀

🪟 `TypeLibrary()`, `env.TypeLibrary()` 🪟

Builds a Windows type library (.tlb) file from an input IDL file (.idl). And as a lil bonus, she'll also build the associated interface stub and proxy source files, naming them according to the base name of the .idl file. Like, for example:

env.TypeLibrary(source="foo.idl")

Will create foo.tlb, foo.h, foo_i.c, foo_p.c and foo_data.c files. Obsessed with her honestly. 🫶

💖 `Zip()`, `env.Zip()` 💖

okay bestie, this one builds a zip archive of whatever files and/or directories you point it at. 🗜️✨

And here's the cute lil plot twist: unlike basically every other builder method, the Zip builder method can be called multiple times for a given target — every extra call just adds more stuff onto the list of entries that'll be built into the archive. No cap. 💅 Also, any source directories get scanned for changes to any on-disk files, regardless of whether or not scons even knows about them from other Builder or function calls. 👀

env.Zip('src.zip', 'src')

# Create the stuff.zip file.
env.Zip('stuff', ['subdir1', 'subdir2'])
# Also add "another" to the stuff.tar file.
env.Zip('stuff', 'another')

🌈 SCons Functions and Environment Methods 🌈

okay so SCons hands you a whole drawer of construction environment methods and global functions so you can fiddle with your build configuration. Often there's a construction environment method and a global function with the same name, just existing for convenience. In this section, both forms are shown if the function can be called either way. ✨ The documentation style for these goes like this:

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

In these function signatures, arguments in brackets ([]) are optional, and the ellipses (...) mean "could repeat, bestie". Positional vs. keyword arguments are usually spelled out in the text below, not in the signature itself. And the Python positional-only (/) and keyword-only (*) markers? Not used. 🙈

When the Python keyword=value style shows up, it can mean two different things:

If the keyword argument is known to the function, the value is the default for that argument when you omit it.
If the keyword is unknown to the function, some methods treat it as a construction variable assignment; otherwise, an exception gets raised for an unknown argument. 💀

A global function and a same-named construction environment method are doing the same base job, with two key differences:

Construction environment methods that read from or change the environment act on the environment instance they were called from. The corresponding global functions read from a special "hidden" construction environment called the Default Environment. In some cases, a global function may take an extra initial argument giving it the object to operate on.
String-valued arguments (including strings sitting inside list-valued arguments) are subject to construction variable expansion by the environment method form. That variable expansion is not immediately performed in the global function. For example, Default('$MYTARGET') adds '$MYTARGET' to the list of default targets, while if the value in env of MYTARGET is 'mine', env.Default('$MYTARGET' adds 'mine' to the default targets. For more deets on construction variable expansion, check the Construction variables section. 📖

Global functions are automatically in scope inside SConscript files. But listen — if your project adds Python modules that you bring in via the Python import statement from an SConscript file, that code will need to add the functions to that module's global scope explicitly. You do that by adding the following import to the Python module: from SCons.Script import *. 🐍

SCons provides the following construction environment methods and global functions. The list can be added to on a project basis using AddMethod. 👑💅

`Action(action, [output, [var, ...]] [key=value, ...])`, `env.Action(action, [output, [var, ...]] [key=value, ...])`

A factory function that creates an Action object for the specified action. Peep the manpage section "Action Objects" for the complete explanation of the arguments and behavior. ✨

Heads up, bestie 📣 — the env.Action form of the invocation expands construction variables in any argument strings (including the action argument) at the time it's called, using the construction variables in the construction environment that env.Action was called through. The Action global function form delays all variable expansion until the Action object is actually used. Big difference, ok? 💖

`AddMethod(object, function, [name])`, `env.AddMethod(function, [name])`

Adds function to an object as a method. function will be called with an instance object as the first argument, just like for other methods. If name is given, it's used as the name of the new method — otherwise the name of function is used. 🎀

When the global function AddMethod is called, the object to add the method to must be passed as the first argument. Typically that's Environment, in order to create a method which applies to all construction environments subsequently constructed. When you call it using the env.AddMethod form, the method gets added to the specified construction environment only. Added methods propagate through env.Clone calls. 🦋

More examples:

# Function to add must accept an instance argument.
# The Python convention is to call this 'self'.
def my_method(self, arg):
    print("my_method() got", arg)

# Use the global function to add a method to the Environment class:
AddMethod(Environment, my_method)
env = Environment()
env.my_method('arg')

# Use the optional name argument to set the name of the method:
env.AddMethod(my_method, 'other_method_name')
env.other_method_name('another arg')

`AddOption(opt_str, ..., attr=value, ...)`

Adds a local (project-specific) command-line option. One or more opt_str values are the strings representing how the option can be called, and the keyword arguments define attributes of the option. For the most part these are the same as for the OptionParser.add_option method in the standard Python library module optparse, but with a few extra capabilities noted below. See the optparse documentation[5] for a thorough discussion of its option-processing capabilities. All options added through AddOption get dropped into a special "Local Options" option group. 💅

On top of the arguments and values supported by the optparse add_option method, AddOption lets you set the nargs keyword value to the string '?' (question mark) to indicate that the option argument for that option string may be omitted. If the option string is present on the command line but has no matching option argument, the value of the const keyword argument is produced as the value of the option. If the option string is omitted from the command line, the value of the default keyword argument is produced, as usual — and if there's no default keyword argument in the AddOption call, None is produced. 🙈

optparse recognizes abbreviations of long option names, as long as they can be unambiguously resolved. For example, if add_option is called to define a --devicename option, it'll also recognize --device, --dev and so forth, as long as there's no other option that could also match to the same abbreviation. Options added via AddOption do not support the automatic recognition of abbreviations. Instead, to allow specific abbreviations, include them as synonyms in the AddOption call itself. 👀

Once a new command-line option has been added with AddOption, the option value may be accessed using GetOption or env.GetOption. If the settable=True argument was supplied in the AddOption call, the value may also be set later using SetOption or env.SetOption, if conditions in an SConscript file require overriding any default value. Note however that a value specified on the command line will always override a value set in an SConscript file. 🔥

Changed in 4.8.0: added the settable keyword argument to enable an added option to be settable via SetOption. ✨

Help text for an option is a combination of the string supplied in the help keyword argument to AddOption and information collected from the other keyword arguments. Such help is displayed if the -h command line option is used (but not with -H). Help for all local options is displayed under the separate heading Local Options. The options are unsorted — they'll appear in the help text in the order in which the AddOption calls occur. 📜

Example:

AddOption(
    '--prefix',
    dest='prefix',
    nargs=1,
    type='string',
    action='store',
    metavar='DIR',
    help='installation prefix',
)
env = Environment(PREFIX=GetOption('prefix'))

For that example, the following help text would be produced:

Local Options:
  --prefix=DIR                installation prefix

Help text for local options may be unavailable if the Help function has been called — see the Help documentation for details. 🫶

Note ⚠️ Prior to version 4.11.0, the behavior when options added by AddOption are specified with whitespace was undefined and discouraged. Such usage covers both the use of a space as the separator (--opt arg vs --opt=arg), and where the number of option arguments (nargs) is specified as greater than one. While this issue has been corrected, developers should be aware of it in case the project is built with an older SCons version. 😭

`AddPostAction(target, action)`, `env.AddPostAction(target, action)`

Arranges for the specified action to be performed after the specified target has been built. action may be an Action object, or anything that can be converted into an Action object. See the manpage section "Action Objects" for a complete explanation. 🎀

When multiple targets are supplied, the action may be called multiple times — once after each action that generates one or more targets in the list. 💅

foo = Program('foo.c')
# remove execute permission from binary:
AddPostAction(foo, Chmod('$TARGET', "a-x"))

If a target is an Alias, action is associated with the action of the alias, if specified. 🌸

`AddPreAction(target, action)`, `env.AddPreAction(target, action)`

Arranges for the specified action to be performed before the specified target is built. action may be an Action object, or anything that can be converted into an Action object. See the manpage section "Action Objects" for a complete explanation. ✨

When multiple targets are specified, the action(s) may be called multiple times — once before each action that generates one or more targets in the list. 🦋

Note that if any of the targets are built in multiple steps, the action will be invoked just before the action step that specifically generates the specified target(s). It may not always be obvious if the process is multi-step — for example, if you use the Program builder to construct an executable program from a .c source file, scons builds an intermediate object file first; the pre-action is invoked after this step and just before the link command to generate the executable program binary. Example:

foo = Program('foo.c')
AddPreAction(foo, 'echo "Running pre-action"')

$ scons -Q
gcc -o foo.o -c foo.c
echo "Running pre-action"
Running pre-action
gcc -o foo foo.o

If a target is an Alias, action is associated with the action of the alias, if specified. ✨

💖 `Alias(alias, [source, [action]])`, `env.Alias(alias, [source, [action]])` 💖

Create an Alias node that can be used as a reference to zero or more other targets, specified by the optional source parameter. Aliases provide a way to give a shorter or more descriptive name to specific targets, and to group multiple targets under a single name 💅. The alias name, or an Alias Node object, may be used as a dependency of any other target, including another alias. Slay.

alias and source may each be a string or Node object, or a list of strings or Node objects; if Nodes are used for alias they must be Alias nodes. If source is omitted, the alias is created but has no reference; if selected for building this will result in a “Nothing to be done.” message 😭. An empty alias can be used to define the alias in a visible place in the project; it can later be appended to in a subsidiary SConscript file with the actual target(s) to refer to. The optional action parameter specifies an action or list of actions that will be executed whenever any of the alias targets are out-of-date.

Alias can be called for an existing alias, which appends the alias and/or action arguments to the existing lists for that alias.

Returns a list of Alias Node objects representing the alias(es), which exist outside of any physical file system. 🦋 The alias name space is separate from the name space for tangible targets; to avoid confusion do not reuse target names as alias names.

Examples:

Alias('install')
Alias('install', '/usr/bin')
Alias(['install', 'install-lib'], '/usr/local/lib')

env.Alias('install', ['/usr/local/bin', '/usr/local/lib'])
env.Alias('install', ['/usr/local/man'])

env.Alias('update', ['file1', 'file2'], "update_database $SOURCES")

🎀 `AllowSubstExceptions([exception, ...])` 🎀

Specifies the exceptions that will be ignored when expanding construction variables. By default, any construction variable expansions that generate a NameError or IndexError exception will expand to a '' (an empty string) and not cause scons to fail. All exceptions not in the specified list will generate an error message and terminate processing.

If AllowSubstExceptions is called multiple times, each call completely overwrites the previous list of ignored exceptions. Calling it with no arguments means no exceptions will be ignored.

Example:

# Requires that all construction variable names exist.
# (You may wish to do this if you want to enforce strictly
# that all construction variables must be defined before use.)
AllowSubstExceptions()

# Also allow a string containing a zero-division expansion
# like '${1 / 0}' to evaluate to ''.
AllowSubstExceptions(IndexError, NameError, ZeroDivisionError)

✨ `AlwaysBuild(target, ...)`, `env.AlwaysBuild(target, ...)` ✨

Marks each given target so that it is always assumed to be out-of-date, and will always be rebuilt if needed. Periodt. Note, however, that AlwaysBuild does not add its target(s) to the default target list, so the targets will only be built if they are specified on the command line, or are a dependent of a target specified on the command line — but they will always be built if so specified 😌. Multiple targets can be passed in to a single call to AlwaysBuild.

🫶 `env.Append(key=val, [...])` 🫶

Appends value(s) intelligently to construction variables in env. The construction variables and values to add to them are passed as key=val pairs (Python keyword arguments). env.Append is designed to allow adding values without having to think about the data type of an existing construction variable 🧠. Regular Python syntax can also be used to manipulate the construction variable, but for that you may need to know the types involved, for example pure Python lets you directly "add" two lists of strings, but adding a string to a list or a list to a string requires different syntax — things Append takes care of. Some pre-defined construction variables do have type expectations based on how SCons will use them: for example $CPPDEFINES is often a string or a list of strings, but can also be a list of tuples or a dictionary; while $LIBEMITTER is expected to be a callable or list of callables, and $BUILDERS is expected to be a dictionary. Consult the documentation for the various construction variables for more details 💜.

The following descriptions apply to both the Append and Prepend methods, as well as their Unique variants, with the differences being the insertion point of the added values and whether duplication is allowed.

val can be almost any type. If env does not have a construction variable named key, then key is simply stored with a value of val. Otherwise, val is combined with the existing value, possibly converting into an appropriate type which can hold the expanded contents. There are a few special cases to be aware of 👀. Normally, when two strings are combined, the result is a new string containing their concatenation (and you are responsible for supplying any needed separation); however, the contents of $CPPDEFINES will be post-processed by adding a prefix and/or suffix to each entry when the command line is produced, so SCons keeps them separate — appending a string will result in a separate string entry, not a combined string. For $CPPDEFINES, as well as $LIBS, and the various *PATH variables, SCons will amend the variable by supplying the compiler-specific syntax (e.g. prepending a -D or /D prefix for $CPPDEFINES), so you should omit this syntax when adding values to these variables. Examples (gcc syntax shown in the expansion of CPPDEFINES):

env = Environment(CXXFLAGS="-std=c11", CPPDEFINES="RELEASE")
print(f"CXXFLAGS = {env['CXXFLAGS']}, CPPDEFINES = {env['CPPDEFINES']}")
# notice including a leading space in CXXFLAGS addition
env.Append(CXXFLAGS=" -O", CPPDEFINES="EXTRA")
print(f"CXXFLAGS = {env['CXXFLAGS']}, CPPDEFINES = {env['CPPDEFINES']}")
print("CPPDEFINES will expand to", env.subst('$_CPPDEFFLAGS'))

$ scons -Q
CXXFLAGS = -std=c11, CPPDEFINES = RELEASE
CXXFLAGS = -std=c11 -O, CPPDEFINES = deque(['RELEASE', 'EXTRA'])
CPPDEFINES will expand to -DRELEASE -DEXTRA
scons: `.' is up to date.

Because $CPPDEFINES is intended for command-line specification of C/C++ preprocessor macros, additional syntax is accepted when adding to it. The preprocessor accepts arguments to predefine a macro name by itself (-DFOO for most compilers, /DFOO for Microsoft C++), which gives it an implicit value of 1, or can be given with a replacement value (-DBAR=TEXT). SCons follows these rules when adding to $CPPDEFINES:

A string is split on spaces, giving an easy way to enter multiple macros in one addition. Use an = to specify a valued macro.
A tuple is treated as a valued macro. Use the value None if the macro should not have a value. It is an error to supply more than two elements in such a tuple.
A list is processed in order, adding each item without further interpretation. In this case, space-separated strings are not split.
A dictionary is processed in order, adding each key-value pair as a valued macro. Use the value None if the macro should not have a value.

Examples:

env = Environment(CPPDEFINES="FOO")
print("CPPDEFINES =", env['CPPDEFINES'])
env.Append(CPPDEFINES="BAR=1")
print("CPPDEFINES =", env['CPPDEFINES'])
env.Append(CPPDEFINES=[("OTHER", 2)])
print("CPPDEFINES =", env['CPPDEFINES'])
env.Append(CPPDEFINES={"EXTRA": "arg"})
print("CPPDEFINES =", env['CPPDEFINES'])
print("CPPDEFINES will expand to", env.subst('$_CPPDEFFLAGS'))

$ scons -Q
CPPDEFINES = FOO
CPPDEFINES = deque(['FOO', 'BAR=1'])
CPPDEFINES = deque(['FOO', 'BAR=1', ('OTHER', 2)])
CPPDEFINES = deque(['FOO', 'BAR=1', ('OTHER', 2), ('EXTRA', 'arg')])
CPPDEFINES will expand to -DFOO -DBAR=1 -DOTHER=2 -DEXTRA=arg
scons: `.' is up to date.

Examples of adding multiple macros:

env = Environment()
env.Append(CPPDEFINES=[("ONE", 1), "TWO", ("THREE", )])
print("CPPDEFINES =", env['CPPDEFINES'])
env.Append(CPPDEFINES={"FOUR": 4, "FIVE": None})
print("CPPDEFINES =", env['CPPDEFINES'])
print("CPPDEFINES will expand to", env.subst('$_CPPDEFFLAGS'))

$ scons -Q
CPPDEFINES = [('ONE', 1), 'TWO', ('THREE',)]
CPPDEFINES = deque([('ONE', 1), 'TWO', ('THREE',), ('FOUR', 4), ('FIVE', None)])
CPPDEFINES will expand to -DONE=1 -DTWO -DTHREE -DFOUR=4 -DFIVE
scons: `.' is up to date.

Changed in version 4.5: clarified the use of tuples vs. other types, handling is now consistent across the four functions.

env = Environment()
env.Append(CPPDEFINES=("MACRO1", "MACRO2"))
print("CPPDEFINES =", env['CPPDEFINES'])
env.Append(CPPDEFINES=[("MACRO3", "MACRO4")])
print("CPPDEFINES =", env['CPPDEFINES'])
print("CPPDEFINES will expand to", env.subst('$_CPPDEFFLAGS'))

$ scons -Q
CPPDEFINES = ('MACRO1', 'MACRO2')
CPPDEFINES = deque(['MACRO1', 'MACRO2', ('MACRO3', 'MACRO4')])
CPPDEFINES will expand to -DMACRO1 -DMACRO2 -DMACRO3=MACRO4
scons: `.' is up to date.

See $CPPDEFINES for more details 🌸.

Appending a string val to a dictionary-typed construction variable enters val as the key in the dictionary, and None as its value. Using a tuple type to supply a key-value pair only works for the special case of $CPPDEFINES described above. 💅
Okay so most combinations of types just work and you never have to think about it, but ngl some combos genuinely do not make sense and Python will just raise an exception at you. Not a vibe, but there it is. 😭
When you're using env.Append to modify construction variables that are path specifications (conventionally, the names of those end in PATH), bestie please add the values as a list of strings, even if you're only adding a single string. It's giving "trust me." Same energy goes for adding library names to $LIBS. ✨

env.Append(CPPPATH=["#/include"])

See also env.AppendUnique, env.Prepend and env.PrependUnique.

`env.AppendENVPath(name, newpath, [envname, sep, delete_existing=False])`

Appends directory paths from newpath to a search-path entry name in construction variable envname in the current environment (env). If envname isn't given, the default is "ENV" (peep $ENV). envname is expected to refer to a dictionary-like object, and if it doesn't already exist in env, it gets created as an initially empty dict. 🫶

newpath can be a string, a directory node, or a list of strings. If it's a string, it may contain multiple paths separated by the system path separator (os.pathsep), or, if you specify one, by the value of sep. Top-relative path strings (the ones starting with #) are recognized. The type of the existing value of name is preserved — no surprise type-swaps here. 💜

Paths will only appear once. Duplicates inside newpath get removed, and it preserves the last occurrence so the path order stays correct. If delete_existing is true (that's the default), existing duplicates are removed before appending; otherwise, new duplicates are just skipped. During comparisons, paths are normalized, which avoids issues with case differences (on case-insensitive filesystems) and with relative paths that might refer back to the same directory. The stored values are not modified by this process. ✨

Example:

print('before:', env['ENV']['INCLUDE'])
include_path = '/foo/bar:/foo'
env.AppendENVPath('INCLUDE', include_path)
print('after:', env['ENV']['INCLUDE'])

Yields:

before: /foo:/biz
after: /biz:/foo/bar:/foo

`env.AppendUnique(key=val, [...], [delete_existing=False])`

Appends values to construction variables in the current construction environment, but maintaining uniqueness ✨. Works like env.Append, except values that would become duplicates just… don't get added. Iconic behavior honestly. If delete_existing is set to a true value, then for any duplicate, the existing instance of val is first removed, and then val is appended — which has the effect of moving it to the end. 👑

Example:

env.AppendUnique(CCFLAGS='-g', FOO=['foo.yyy'])

See also env.Append, env.Prepend and env.PrependUnique.

`Builder(action, [arguments])`, `env.Builder(action, [arguments])`

Creates a Builder object for the specified action. Head over to the manpage section "Builder Objects" for the full explanation of the arguments and behavior. 🎀

Note that the env.Builder() form of the invocation will expand construction variables in any argument strings, including the action argument, at the time it is called — using the construction variables in the env construction environment through which env.Builder was called. The Builder form delays all variable expansion until after the Builder object is actually called. Timing is everything, bestie. 💅

`CacheDir(cache_dir, custom_class=None)`, `env.CacheDir(cache_dir, custom_class=None)`

Directs scons to maintain a derived-file cache in cache_dir. Cached files are shared across builds that specify the same cache_dir. Setting cache_dir to None disables caching. 🍓

The environment method env.CacheDir applies caching only to targets built through that specific construction environment. The global function CacheDir sets a default that applies to all targets unless it gets overridden by an environment-specific call.

Caching behavior can be customized by passing a subclass of SCons.CacheDir.CacheDir as the optional custom_class parameter. If it's omitted or set to None, SCons uses the default class.

When caching is enabled and scons needs to rebuild a derived file, it first checks the cache for a matching build signature (that means identical inputs and build actions). If it finds one, the file is retrieved from the cache. Otherwise, scons builds the file and stores a copy in the cache under its build signature. ✨

By default, scons reports Retrieved 'file' from cache on cache hits. Use the --cache-show option to hide that the cache was involved and display the normal build string instead, for consistent log output.

Disable caching for a specific invocation with the --cache-disable option. To allow retrieval but prevent updates, use --cache-readonly.

The --cache-force option copies all derived files into the cache, even pre-existing ones. This helps populate a new cache or update it after building with cache updating disabled (--cache-disable or --cache-readonly).

Use NoCache to exclude specific files from caching, like ones with unpredictable inputs or outputs, or excessively large output files.

SCons does not provide built-in tools for cache management. You will need to handle pruning, expiration, access control, and other maintenance tasks manually. No one's coming to do it for you, bestie. 😭

`Clean(targets, files)`, `env.Clean(targets, files)`

Sets additional files for removal when any of targets are selected for cleaning (that's the -c command line option). targets and files can each be a single filename or node, or a list of filenames or nodes. These can refer to files or directories. Calling this method repeatedly has an additive effect. 🧚

The related NoClean method has higher priority: any target specified to NoClean will not be cleaned even if it's also given as a files parameter to Clean.

Examples:

Clean('foo', ['bar', 'baz'])
Clean('dist', env.Program('hello', 'hello.c'))
Clean(['foo', 'bar'], 'something_else_to_clean')

SCons does not directly track directories as targets — they are created if needed and not normally removed in clean mode. In this example, installing the project creates a subdirectory for the documentation. The Clean call ensures that the subdirectory is removed if the project is uninstalled.

Clean(docdir, os.path.join(docdir, projectname))

`env.Clone([key=val, ...])`

Returns an independent copy of a construction environment. If there are any unrecognized keyword arguments specified, they get added as construction variables in the copy, overwriting any existing values for those keywords. Go read the manpage section "Construction Environments" for more details. 🌈

Example:

env2 = env.Clone()
env3 = env.Clone(CCFLAGS='-g')

A list of tools and a toolpath may be specified, just like in the Environment constructor:

def MyTool(env):
    env['FOO'] = 'bar'

env4 = env.Clone(tools=['msvc', MyTool])

The parse_flags keyword argument is also recognized, to allow merging command-line style arguments into the appropriate construction variables (see env.MergeFlags).

# create an environment for compiling programs that use wxWidgets
wx_env = env.Clone(parse_flags='!wx-config --cflags --cxxflags')

The variables keyword argument is also recognized, which lets you (re)initialize construction variables from a Variables object. 👑

Changed in version 4.8.0: the variables parameter was added.

`Command(target, source, action, [key=val, ...])`, `env.Command(target, source, action, [key=val, ...])`

Creates an anonymous builder and calls it, which records action to build target from source into the dependency tree. For a single special-case build, this is lowkey more convenient than defining and adding a whole new named Builder. 💅

The Command function accepts the source_scanner and target_scanner keyword arguments, which specify custom scanners for the given sources or targets. The value must be a Scanner object. For example, the global DirScanner object can be used if any of the sources will be directories that must be scanned on-disk for changes to files that aren't already specified in other Builder or function calls. 🔍

The Command function also accepts the source_factory and target_factory keyword arguments, which specify factory functions to create SCons Nodes from any sources or targets specified as strings. If any sources or targets are already Node objects, they are not further transformed, even if a factory is specified for them. The default for each is the Entry factory. ✨

These four arguments, if given, are used in the creation of the Builder. Other Builder-specific keyword arguments are not recognized as such. Peep the manpage section "Builder Objects" for more info on how these arguments work in a Builder.

Any remaining keyword arguments are passed on to the generated builder when it is called, and behave as described in the manpage section "Builder Methods". In short: recognized arguments have their specified meanings, while the rest are used to override any same-named existing construction variables from the construction environment. 🎀

action can be an external command, specified as a string, or a callable Python object; see the manpage section "Action Objects" for the complete picture. Also note that a string specifying an external command may be preceded by an at-sign (@) to suppress printing the command in question, or by a hyphen (-) to ignore the exit status of the external command. 💜

Examples:

env.Command(
    target='foo.out',
    source='foo.in',
    action="$FOO_BUILD < $SOURCES > $TARGET"
)

env.Command(
    target='bar.out',
    source='bar.in',
    action=["rm -f $TARGET", "$BAR_BUILD < $SOURCES > $TARGET"],
    ENV={'PATH': '/usr/local/bin/'},
)

import os
def rename(env, target, source):
    os.rename('.tmp', target[0])

env.Command(
    target='baz.out',
    source='baz.in',
    action=["$BAZ_BUILD < $SOURCES > .tmp", rename],
)

okay so quick lil disclaimer about Command before we move on: it's gonna assume by default that the targets and/or sources you hand it are Files, unless some other part of your config is like "no bestie, these are something else." And if you do need to be explicit? You can say "these are directories actually" by using the Dir or env.Dir functions. 💅

Examples, because seeing it is believing:

env.Command('ddd.list', Dir('ddd'), 'ls -l $SOURCE > $TARGET')

env['DISTDIR'] = 'destination/directory'
env.Command(env.Dir('$DISTDIR')), None, make_distdir)

Also, and this is the good news part: SCons will usually just automatically create any directory it needs to hold a target file. So you normally do not need to hand-create directories. Let it cook. ✨

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

Creates a Configure object so you get integrated functionality similar to what GNU autoconf does. Head over to the manpage section "Configure Contexts" for the full rundown of the arguments and behavior, okay? iykyk. 🫶

🦋 `DebugOptions([json])`

Lets you set values for SCons's debug options. Literally the only value supported right now is json, and it sets the path to the JSON file that gets created when you pass the --debug=json argument. 💖

DebugOptions(json='#/build/output/scons_stats.json')

New in version 4.6.0. ⭐

💀 `Decider(function)`, `env.Decider(function)`

This one is the vibe check for your targets: it says that all the up-to-date decisions for targets built through this construction environment get handled by function. And function can be either the name of a function, or one of these strings that map to a predefined decider function:

"content"

Specifies that a target gets considered out-of-date and rebuilt if the dependency's content has changed since the last time the target was built. How does it know? It runs a checksum on the dependency's contents using the selected hash function, then compares that to the checksum recorded the last time the target was built. content is the default decider, bestie. 👑

Changed in version 4.1: the decider got renamed to content because the hash function is now selectable. The old name, MD5, can still be used as a synonym, but it's deprecated. ⚠️

"content-timestamp"

Specifies that a target gets considered out-of-date and rebuilt if the dependency's content has changed since the last time the target was built — except that dependencies with a timestamp that matches the last time the target was rebuilt get assumed up-to-date and are not rebuilt. So you get behavior very similar to the content way of always checksumming file contents, but with the little optimization of not checking contents of files whose timestamps haven't changed. The trade-off? SCons will not detect it if a file's content changed but its timestamp stayed the same. When does that even happen? Think an automated script that runs a build, updates a file, then runs the build again — all within a single second. 😭

Changed in version 4.1: renamed to content-timestamp since the hash function is now selectable. The former name, MD5-timestamp, can still be used as a synonym, but it's deprecated. ⚠️

"timestamp-newer"

Specifies that a target gets considered out-of-date and rebuilt if the dependency's timestamp is newer than the target file's timestamp. This is literally the behavior of the classic Make utility, and make can be used as a synonym for timestamp-newer. 🎀

"timestamp-match"

Specifies that a target gets considered out-of-date and rebuilt if the dependency's timestamp is different than the timestamp recorded the last time the target was built. Behavior is very similar to classic Make (specifically: files don't get opened up so their contents can be checksummed), except the target will also be rebuilt if a dependency file got restored to a version with an earlier timestamp — like what can happen when you restore files from backup archives. 🙈

Examples:

# Use exact timestamp matches by default.
Decider('timestamp-match')

# Use hash content signatures for any targets built
# with the attached construction environment.
env.Decider('content')

And here's the fun part: on top of all those already-available functions, the function argument can also be a Python function that you supply. A function like that has to accept these four arguments:

dependency — the Node (file) that should cause the target to be rebuilt if it has "changed" since the last time target was built.
target — the Node (file) being built. In the normal case, this is the thing that should get rebuilt if the dependency has "changed."
prev_ni — stored information about the state of the dependency the last time the target was built. You can consult this to match various file characteristics, like the timestamp, size, or content signature.
repo_node — if set, use this Node instead of the one specified by dependency to determine whether the dependency has changed. This argument is optional, so it should be written as a default argument (typically written as repo_node=None). A caller will normally only set this if the target only exists in a Repository.

Your function should return a value that evaluates True if the dependency has "changed" since the last time the target was built (meaning: yeah, rebuild the target), and a value that evaluates False otherwise (meaning: no rebuild needed). And ngl, the decision can be made using whatever criteria you feel like — ignoring some or all of the function arguments is perfectly normal. slay. 💅

Example:

def my_decider(dependency, target, prev_ni, repo_node=None):
    return not os.path.exists(str(target))

env.Decider(my_decider)

🌸 `Default(target[, ...])`, `env.Default(target[, ...])`

Sets the default targets for the SCons target selection mechanism. Call Default at all — even once — and SCons stops using its built-in algorithm for figuring out default targets and starts using the default target list you defined instead. (Peep the manpage section "Target Selection" for that whole story.)

target can be one or more strings, a list of strings, a NodeList as returned by a Builder, or None. A string target can be the name of a file or directory, or a target previously defined by a call to Alias — and heads up, if you define the alias later, it'll still create the alias, but it will not be recognized as a default. Calls to Default are additive. And a target of None will clear out any existing default target list; after that, subsequent calls to Default add to the (now empty) default target list like normal. 🧹

Both forms of this call affect the same global list of default targets; the construction environment method applies construction variable expansion to the targets.

The current list of targets you've added using Default is available in the DEFAULT_TARGETS list (see below).

Examples:

Default('foo', 'bar', 'baz')
env.Default(['a', 'b', 'c'])
hello = env.Program('hello', 'hello.c')
env.Default(hello)

💜 `DefaultEnvironment([key=value, ...])`

Instantiates and returns the global construction environment object. The Default Environment is what SCons uses internally whenever it executes a global function, or the global form of a Builder method, that needs access to a construction environment.

On the first call, the arguments are interpreted just like they would be for the Environment function. Here's the tea though: the Default Environment is a singleton. Subsequent calls to DefaultEnvironment return the already-constructed object, and any keyword arguments you pass are silently ignored. 💀

The Default Environment can be modified after instantiation, similar to other construction environments — although some construction environment methods may be unavailable. And modifying the Default Environment has no effect on any other construction environment, whether it's already existing or newly constructed. Keep your vibes separate, bestie. 🦋

You don't have to explicitly call DefaultEnvironment — SCons instantiates the default environment automatically when the build phase begins, if it hasn't already been done. But calling it explicitly gives you the opportunity to affect and examine its contents. And FYI, instantiation happens even if nothing in the build system appears to use it, because of internal uses.

And here's a lil performance tip that's very much ✨optimization✨ coded: if your project's SConscript files don't use global functions or Builders, you can snag a small performance gain by calling DefaultEnvironment with an empty tools list — like DefaultEnvironment(tools=[]). This avoids the tool initialization cost for the Default Environment, which is mainly of interest in the test suite, where scons gets launched over and over in a short time period. 🔥

🎀 `Depends(target, dependency)`, `env.Depends(target, dependency)`

Specifies an explicit dependency — so the target will get rebuilt whenever the dependency has changed. Both the specified target and dependency can be a string (usually the path name of a file or directory), or Node objects, or a list of strings or Node objects (like the kind a Builder call returns). You should only need this for cases where the dependency isn't caught by a Scanner for the file.

Example:

env.Depends('foo', 'other-input-file-for-foo')

mylib = env.Library('mylib.c')
installed_lib = env.Install('lib', mylib)
bar = env.Program('bar.c')

# Arrange for the library to be copied into the installation
# directory before trying to build the "bar" program.
# (Note that this is for example only.  A "real" library
# dependency would normally be configured through the $LIBS
# and $LIBPATH variables, not using an env.Depends() call.)

env.Depends(bar, installed_lib)

🕵️ `env.Detect(progs)`

okay so you've got a whole roster of possible executable names and you just want the first one that's actually there — that's env.Detect, no cap. ✨

progs can be a single string or a list of strings. flex either way 💅
It returns the first value from progs that was found, or None if nothing turned up. 🫶
The search works by checking the paths in the execution environment — that's env['ENV']['PATH'], literally.
On Windows systems it additionally applies the filename suffixes found in the execution environment (env['ENV']['PATHEXT']), but it will not include any such extension in the return value. so you get the bare name back, no .exe shenanigans. 🙈
env.Detect is a wrapper around env.WhereIs. iykyk. 🦋

📖 `env.Dictionary([var, ...], [as_dict=])`

Returns an object containing construction variables from env. Here's the tea on how it behaves 👑

If var is omitted → all the construction variables come back with their values, in a dict. the whole vibe. 🌈
If var is specified and as_dict is true → the specified construction variables are returned in a dict.
Otherwise — and this is the default, kept around for backwards compatibility — only the values are returned: as a scalar if one var is given, or as a list if multiples.

Example:

cvars = env.Dictionary()
cc_values = env.Dictionary('CC', 'CCFLAGS', 'CCCOM')

Note 💀 The object returned by env.Dictionary should be treated as a read-only view into the construction variables. Some construction variables require special internal handling, and modifying them through the env.Dictionary object can bypass that handling and cause data inconsistencies. The primary use of env.Dictionary is for diagnostic purposes — it is used widely by test cases specifically because it bypasses the special handling so that behavior can be verified.

Changed in 4.9.0: as_dict added. 🎀

📁 `Dir(name, [directory])`, `env.Dir(name, [directory])`

Returns Directory Node(s). A Directory Node is an object that represents a directory. yes bestie, it's a whole object, not just a string. ✨

name can be a relative or absolute path, or a list of such paths.
directory is an optional directory that will be used as the parent directory. If no directory is specified, the current script's directory is used as the parent.
If name is a single pathname, the corresponding node is returned. If name is a list, SCons returns a list of nodes.
Construction variables are expanded in name. 🪄

Directory Nodes can be used anywhere you would supply a string as a directory name to a Builder method or function. Directory Nodes have attributes and methods that are useful in many situations; see manpage section "Filesystem Nodes" for more information. 👑

🖨️ `env.Dump([var, ...], [format=TYPE])`

Serialize construction variables from env to a string. 💫

If var is omitted → all the construction variables are serialized.
If one or more var values are supplied → only those variables and their values are serialized.

The optional format string selects the serialization format:

pretty — Returns a pretty-printed representation of the construction variables; the result will look like a Python dict (this is the default). 💖
json — Returns a JSON-formatted representation of the variables. The variables will be presented as a JSON object literal, the JSON equivalent of a Python dict.

Changed in 4.9.0: More than one key can be specified. The returned string always looks like a dict (or equivalent in other formats); previously a single key serialized only the value, not the key with the value. 📌

Examples: this SConstruct

env = Environment()
print(env.Dump('CCCOM'))
print(env.Dump('CC', 'CCFLAGS', format='json'))

will print something like:

{'CCCOM': '$CC -o $TARGET -c $CFLAGS $CCFLAGS $_CCCOMCOM $SOURCES'}
{
    "CC": "gcc",
    "CCFLAGS": []
}

While this SConstruct:

env = Environment()
print(env.Dump())

will print something like:

{ 'AR': 'ar',
  'ARCOM': '$AR $ARFLAGS $TARGET $SOURCES\n$RANLIB $RANLIBFLAGS $TARGET',
  'ARFLAGS': ['r'],
  'AS': 'as',
  'ASCOM': '$AS $ASFLAGS -o $TARGET $SOURCES',
  'ASFLAGS': [],
  ...

🐍 `EnsurePythonVersion(major, minor)`

Ensure that the Python version is at least major.minor. This function will print out an error message and exit SCons with a non-zero exit code if the actual Python version is not late enough. so like, it's a vibe check for your interpreter. 🌸

Example:

EnsurePythonVersion(2,2)

🛠️ `EnsureSConsVersion(major, minor, [revision])`

Ensure that the SCons version is at least major.minor, or major.minor.revision if revision is specified. This function will print out an error message and exit SCons with a non-zero exit code if the actual SCons version is not late enough. 🫶

Examples:

EnsureSConsVersion(0,14)

EnsureSConsVersion(0,96,90)

🌱 `Environment([key=value, ...])`, `env.Environment([key=value, ...])`

Return a new construction environment initialized with the specified key=value pairs. 💅

Heads up: the keyword arguments parse_flags, platform, toolpath, tools and variables are specially recognized and do not lead to construction variable creation. See the manpage section "Construction Environments" for more details. 👑

⚡ `Execute(action, [actionargs ...])`, `env.Execute(action, [actionargs ...])`

Executes an Action. 🔥

action may be an Action object, or it may be a command-line string, a list of commands, or an executable Python function — each of which will first be converted into an Action object and then executed. Any additional arguments to Execute are passed on to the Action factory function which actually creates the Action object (see the manpage section Action Objects for a description). Example:

Execute(Copy('file.out', 'file.in'))

Execute performs its action immediately, as part of the SConscript-reading phase. There are no sources or targets declared in an Execute call, so any objects it manipulates will not be tracked as part of the SCons dependency graph. In the example above, neither file.out nor file.in will be tracked objects. 😭

Execute returns the exit value of the command or return value of the Python function. scons prints an error message if the executed action fails (exits with or returns a non-zero value), however it does not automatically terminate the build for such a failure. If you want the build to stop in response to a failed Execute call, you must explicitly check for a non-zero return value:

if Execute("mkdir sub/dir/ectory"):
    # The mkdir failed, don't try to build.
    Exit(1)

🚪 `Exit([value])`

This tells scons to exit immediately with the specified value. A default exit value of 0 (zero) is used if no value is specified. bye bestie, we're out ✌️

📤 `Export([vars...], [key=value...])`, `env.Export([vars...], [key=value...])`

Exports variables for sharing with other SConscript files. The variables are added to a global collection where they can be imported by other SConscript files. 🌍

vars may be one or more strings, or a list of strings. If any string contains whitespace, it is split automatically into individual strings.
Each string must match the name of a variable that is in scope during evaluation of the current SConscript file, or an exception is raised. 💀

A vars argument may also be a dictionary or individual keyword arguments; in accordance with Python syntax rules, keyword arguments must come after any non-keyword arguments. The dictionary/keyword form can be used to map the local name of a variable to a different name to be used for imports. See the Examples for an illustration of the syntax. 💫

Export calls are cumulative. Specifying a previously exported variable will replace the previous value in the collection. Both local variables and global variables can be exported. ✨

To use an exported variable, an SConscript must call Import to bring it into its own scope. Importing creates an additional reference to the object that was originally exported, so if that object is mutable, changes made will be visible to other users of that object. 👀

Examples:

env = Environment()
# Make env available for all SConscript files to Import().
Export("env")

package = 'my_name'
# Make env and package available for all SConscript files:.
Export("env", "package")

# Make env and package available for all SConscript files:
Export(["env", "package"])

# Make env available using the name debug:
Export(debug=env)

# Make env available using the name debug:
Export({"debug": env})

Note that the SConscript function also supports an exports argument that allows exporting one or more variables to the SConscript files invoked by that call (only). See the description of that function for details. 📝

📄 `File(name, [directory])`, `env.File(name, [directory])`

Returns File Node(s). A File Node is an object that represents a file. 💖

name can be a relative or absolute path, or a list of such paths.
directory is an optional directory that will be used as the parent directory. If no directory is specified, the current script's directory is used as the parent.
If name is a single pathname, the corresponding node is returned. If name is a list, SCons returns a list of nodes.
Construction variables are expanded in name. 🪄

File Nodes can be used anywhere you would supply a string as a file name to a Builder method or function. File Nodes have attributes and methods that are useful in many situations; see manpage section "Filesystem Nodes" for more information. 👑

🔎 `FindFile(file, dirs)`, `env.FindFile(file, dirs)`

Search for file in the path specified by dirs. dirs may be a list of directory names or a single directory name. In addition to searching for files that exist in the filesystem, this function also searches for derived files that have not yet been built. 🤯 iconic behavior honestly.

Example:

# Searches for 'foo' in 'dir1' and 'dir2', returning the node if found
foo = env.FindFile('foo', ['dir1', 'dir2'])

📦 `FindInstalledFiles()`, `env.FindInstalledFiles()`

Return the list of targets set up by the Install and InstallAs builders. This function serves as a convenient method to select the contents of a binary package. 📦✨

The list is populated as Install and InstallAs are executed — that is, the return reflects builder calls already seen but not any calls that may occur later. so don't come for it about future installs bestie 🫶

Example:

Install('/bin', ['executable_a', 'executable_b'])

# Returns the file node list
# ['/bin/executable_a', '/bin/executable_b']
FindInstalledFiles()

Install('/lib', ['some_library'])

# Returns the file node list
# ['/bin/executable_a', '/bin/executable_b', '/lib/some_library']
FindInstalledFiles()

see how it just keeps stacking?? every Install() call adds to the pile and FindInstalledFiles() hands you the whole receipts list 💅 iconic behaviour honestly.

🫶 `FindPathDirs(variable)`

okay bestie so this one gives you back a callable object that you use as the path_function of a Scanner object. when it gets called, it goes and looks up the variable you named in the construction environment, then treats whatever value it finds as a list of directory paths to search — exactly like how $CPPPATH or $LIBPATH work 🎀

and like, using FindPathDirs is generally the move over writing your own path_function, because it already handles the classic SCons scanning situations correctly and efficiently:

it returns all the right directories from source trees when you're using a variant directory, and from repositories when Repository or the -Y/--repository option is in effect 🌈
it peeps when different values of variable actually resolve to the same directory list, and then it reuses that result instead of rescanning the same directories over and over — no redundant work, no wasted vibes ✨

Example, because yes:

def my_scan(node, env, path, arg):
    # Code to scan file contents goes here...
    return include_files

scanner = Scanner(
    name='myscanner', function=my_scan, path_function=FindPathDirs('MYPATH')
)

🌸 `FindSourceFiles([node])`, `env.FindSourceFiles([node])`

returns the list of nodes that represent the sources of your built files 💖 it figures this out by recursively poking through the dependency tree, starting at the optional argument node, which defaults to the current directory ("."). then it hands back all the leaf nodes — meaning the files with no further dependencies hanging off them 🔥 this is literally the convenient way to select the contents of a source package, periodt.

Example:

Program('src/main_a.c')
Program('src/main_b.c')
Program('main_c.c')

# returns ['main_c.c', 'src/main_a.c', 'SConstruct', 'src/main_b.c']
FindSourceFiles()

# returns ['src/main_b.c', 'src/main_a.c' ]
FindSourceFiles('src')

heads up: build support files that live in the tree (like SConstruct up there 👀) get returned too. not a bug, just the way it is, bestie.

💜 `Flatten(sequence)`, `env.Flatten(sequence)`

takes a sequence — that is, a Python list or tuple 🐍 — that might have nested sequences all up in there, and returns one flat list with all the individual elements from any sequence inside it. why do you care? because it's lowkey a lifesaver when you're collecting the lists that Builders give back: other Builders will automatically flatten lists you pass as input, but if you're doing direct Python manipulation of those lists, that flattening does not happen for you 🙈

Examples:

foo = Object('foo.c')
bar = Object('bar.c')

# Because `foo' and `bar' are lists returned by the Object() Builder,
# `objects' will be a list containing nested lists:
objects = ['f1.o', foo, 'f2.o', bar, 'f3.o']

# Passing such a list to another Builder is all right because
# the Builder will flatten the list automatically:
Program(source = objects)

# If you need to manipulate the list directly using Python, you need to
# call Flatten() yourself, or otherwise handle nested lists:
for object in Flatten(objects):
    print(str(object))

😭 `GetBuildFailures()`

returns a list of exceptions for the actions that failed while it was trying to build targets 💀 every single element in that returned list is a BuildError object, and each one has these attributes recording the various aspects of the failure, so let's go down the list:

.node — the node that was being built when the build failure happened.
.status — the numeric exit status returned by the command or Python function that failed when trying to build the specified Node.
.errstr — the SCons error string describing the build failure. (this is often some generic message like "Error 2", just to indicate that an executed command exited with a status of 2.)
.filename — the name of the file or directory that actually caused the failure. this can be different from the .node attribute! for example, if an attempt to build a target named sub/dir/target fails because the sub/dir directory could not be created, then .node will be sub/dir/target but .filename will be sub/dir 👀
.executor — the SCons Executor object for the target Node being built. you can use this to retrieve the construction environment used for the failed action 🧚
.action — the actual SCons Action object that failed. this will be one specific action out of the possible list of actions that would have been executed to build the target.
.command — the actual expanded command that was executed and failed, after expansion of $TARGET, $SOURCE, and other construction variables 🔥

very important bestie: the GetBuildFailures function will always return an empty list until some build failure has actually occurred. which means GetBuildFailures will always return an empty list while the SConscript files are being read 📭 its primary intended use is for functions that get executed before SCons exits — you set that up by passing them to the standard Python atexit.register function.

Example:

import atexit

def print_build_failures():
    from SCons.Script import GetBuildFailures
    for bf in GetBuildFailures():
        print("%s failed: %s" % (bf.node, bf.errstr))

atexit.register(print_build_failures)

✨ `GetBuildPath(file, [...])`, `env.GetBuildPath(file, [...])`

returns the scons path name (or names) for the file (or files) you specified 💫 and the file or files you hand over can be scons Nodes or strings representing path names — dealer's choice, she's flexible 🎀

🌈 `GetLaunchDir()`

returns the absolute path name of the directory from which scons was initially invoked 📍 this one is super useful when you're using the -u, -U, or -D options, because those internally change to the directory where the SConstruct file is found — so this is how you remember where you actually started, bestie 🫶 iykyk.

💖 `GetOption(name)`, `env.GetOption(name)` 💖

okay bestie, so you wanna query the value of the settable option name? It might have been set on the command line, via option defaults, or by using the SetOption function. The list below shows the corresponding command-line arguments that could affect the value. Options are stored using the indicated type. Also, name can be the destination variable name from a project-specific option added using the AddOption function — as long as that addition has been processed prior to the GetOption call in the SConscript files. ✨

Here's the whole rundown, bestie:

cache_debug — command-line argument: --cache-debug. Notes: String (filename). 🍓
cache_disable — command-line argument: --cache-disable, --no-cache. Notes: Boolean. 💅
cache_force — command-line argument: --cache-force, --cache-populate. Notes: Boolean. 🌸
cache_readonly — command-line argument: --cache-readonly. Notes: Boolean. 🦋
cache_show — command-line argument: --cache-show. Notes: Boolean. 🌈
clean — command-line argument: -c, --clean, --remove. Notes: Boolean. 🧚
climb_up — command-line argument: -D, -U, -u, --up, --search_up. Notes: Integer. 1 means -u was given, 2 is -D, 3 is -U. 👑
config — command-line argument: --config. Notes: String. ⭐
debug — command-line argument: --debug. Notes: List. 💜
directory — command-line argument: -C, --directory. Notes: List (paths). 🎀
diskcheck — command-line argument: --diskcheck. Notes: List. 🔥
duplicate — command-line argument: --duplicate. Notes: String. 🌸
enable_virtualenv — command-line argument: --enable-virtualenv. Notes: Boolean. 💖
experimental — command-line argument: --experimental. Notes: Set. Since 4.2. ✨
file — command-line argument: -f, --file, --makefile, --sconstruct. Notes: List (filenames). 🍓
hash_chunksize — command-line argument: --hash-chunksize. Notes: Integer. Supersedes md5_chunksize. Since 4.2. 💅
hash_format — command-line argument: --hash-format. Notes: String. Since 4.2. 🌸
help — command-line argument: -h, --help. Notes: Boolean. 🦋
ignore_errors — command-line argument: -i, --ignore-errors. Notes: Boolean. 🌈
ignore_virtualenv — command-line argument: --ignore-virtualenv. Notes: Boolean. 🧚
implicit_cache — command-line argument: --implicit-cache. Notes: Boolean. 👑
implicit_deps_changed — command-line argument: --implicit-deps-changed. Notes: Boolean. ⭐
implicit_deps_unchanged — command-line argument: --implicit-deps-unchanged. Notes: Boolean. 💜
include_dir — command-line argument: -I, --include-dir. Notes: List (paths). 🎀
install_sandbox — command-line argument: --install-sandbox. Notes: String (filename). Available only if the install tool has been called 🔥
keep_going — command-line argument: -k,. Notes: Boolean. 💖

okay bestie we're still in the ✨ variable table ✨ trenches, don't scroll away on me 💅

…and that last row's option list wraps up with --keep-going. Now the rest of the crew, one by one 🫶

max_drift — CLI version: --max-drift — Integer.
md5_chunksize — CLI version: --hash-chunksize — Integer. It's been superseded by hash_chunksize and deprecated since 4.2, so like… it's giving legacy, move on bestie 💀
no_exec — CLI versions: -n, --no-exec, --just-print, --dry-run, --recon — Boolean. (four whole aliases, she's an icon, she contains multitudes 👑)
no_progress — CLI version: -Q — Boolean.
num_jobs — CLI versions: -j, --jobs — Integer.
package_type — CLI version: --package-type — String. Heads up: available only if the packaging tool has been called 🫠
profile_file — CLI version: --profile — String (filename).
question — CLI versions: -q, --question — Boolean.
random — CLI version: --random — Boolean.
repository — CLI versions: -Y, --repository, --srcdir — List (paths).
silent — CLI versions: -s, --silent, --quiet — Boolean.
site_dir — CLI versions: --site-dir, --no-site-dir — String (path), False or None.
stack_size — CLI version: --stack-size — Integer.
taskmastertrace_file — CLI version: --taskmastertrace — String (filename).
tree_printers — CLI version: --tree — List.
warn — CLI versions: --warn, --warning — List.

GetSConsVersion()

Hands you the current SCons version as a Tuple[int, int, int] — that's major, minor, and revision, in that order, respectfully ✨ Added in 4.8.0, so if you don't see it, you're on an ancient build, no cap.

Glob(pattern, [ondisk=True, source=False, strings=False, exclude=None]) env.Glob(pattern, [ondisk=True, source=False, strings=False, exclude=None])

Returns a possibly empty list of Nodes (or strings, we'll get there) that match the pathname specification pattern. And pattern can be absolute, top-relative, or — the vibe in like 99% of cases — relative to the directory of the current SConscript file. 🦋

Glob matches both files that actually live on disk and Nodes SCons already knows about, even if the file behind them isn't on disk yet. The environment-method form (env.Glob) does string substitution on pattern and gives you back whatever matches the resulting expanded pattern. And the results come out sorted — which is unlike the similar Python glob.glob function, and it's sorted on purpose so that your build order stays stable. (stable build order is main character energy, the flaky builds could never 🌈)

So pattern can contain POSIX-style shell metacharacters for matching, and here's the whole menu:

* — matches everything
? — matches any single character
[seq] — matches any character in seq (and seq can be a list or a range)
[!seq] — matches any character not in seq

Want a literal match instead of a spicy wildcard one? Wrap the metacharacter in brackets to escape its normal behavior. Like, '[?]' matches the character '?'. iconic. 💅

Filenames starting with a dot get handled specially — they can only be matched by patterns that start with a dot (or that have a dot immediately following a pathname separator character, i.e. a slash), and the metacharacters will not match them. Also: metacharacter matches do not span directory separators. Periodt. 🚫

Glob understands repositories (peep the Repository function) and source directories (peep the VariantDir function), and it returns a Node — or a string, if you configured it that way — matched in the local (SConscript) directory if a matching Node turns up anywhere in a corresponding repository or source directory.

Now the optional args, one by one, because they all hit different 🎀

If the optional ondisk argument evaluates false, the search for matches on disk is disabled, and only matches from already-configured File or Dir Nodes come back. The default is to return Nodes for matches found on disk too.
If the optional source argument evaluates true, and the local directory is a variant directory, then Glob returns Nodes from the corresponding source directory instead of the local directory.
If the optional strings argument evaluates true, Glob returns matches as strings rather than Nodes. Those returned strings will be relative to the local (SConscript) directory. And this is the part where I grab you by the shoulders bestie: while this may make it easier to do arbitrary manipulation of file names, it loses the context SCons would have had in the Node — so if you pass those returned strings to a different SConscript file, any Node translation over there will be relative to that SConscript directory, not to the original one. 😭

The optional exclude argument 💅 can be a pattern, or a whole list of patterns, that describes files or dirs you wanna filter OUT of the match list. Anything matching even one of the patterns you listed gets yeeted from the results 🫶 (and yeah, these patterns use the same syntax as the pattern argument — same glow, same rules ✨).

Examples, bestie:

Program("foo", Glob("*.c"))
Zip("/tmp/everything", Glob(".??*") + Glob("*"))
sources = Glob("*.cpp", exclude=["os_*_specific_*.cpp"]) \
    + Glob("os_%s_specific_*.cpp" % currentOS)

Help(text, append=False, local_only=False), env.Help(text, append=False, local_only=False) — adds text to the help message that shows up when scons gets called with -h or --help. 💖

On the first call to Help, if append is False (which is the default, girly), any help text that was already there gets discarded, no cap. The default help text is the help for the scons command itself, plus help collected from any project-local AddOption calls. That's the help you'd see if Help had never been called at all. If append is True, then text is appended onto the existing help text instead. And if local_only is also True (it defaults to False), then the project-local help from AddOption calls is preserved in the help message — but the scons command help is not. 🙈

Any calls to Help after the first one just ignore the append and local_only keyword arguments entirely and always append to the help text that already exists. periodt.

Changed in 4.6.0: added local_only. 💅

Ignore(target, dependency), env.Ignore(target, dependency) — tells SCons to ignore dependency when it's deciding whether target needs to be rebuilt. Both target and dependency can each be a single filename or Node, or a list of filenames or Nodes. 🦋

Ignore can also be used to remove a target from the default build: just pass the directory the target will be built in as target, and the file you want to skip selecting for building as dependency. But listen — this only removes the target from the default target selection algorithm. If it's a dependency of some other object being built, SCons still builds it like normal. No escaping that. See the third and fourth examples below. 👇

Examples:

env.Ignore('foo', 'foo.c')
env.Ignore('bar', ['bar1.h', 'bar2.h'])
env.Ignore('.', 'foobar.obj')
env.Ignore('bar', 'bar/foobar.obj')

Import(vars...), env.Import(vars...) — imports variables into the scope of the SConscript file you're currently in. 🌈

vars has to be strings representing names of variables that were previously exported, either by the Export function or by the exports argument to the SConscript function. And heads up: variables exported by the SConscript call take precedence. 👑

You can pass multiple variable names to Import as separate arguments, as a list of strings, or just as words inside one space-separated string. And the wildcard "*" can be used to import all the available variables, because why not. ✨

If the variable you imported is mutable, then changes you make locally will be reflected in the object the variable is bound to. This is what lets subsidiary SConscript files contribute to building something up — like, say, a construction environment. Obsessed.

Examples:

Import("env")
Import("env", "variable")
Import(["env", "variable"])
Import("*")

Literal(string), env.Literal(string) — the string you give it will be preserved exactly as-is and will not have construction variables expanded. it's giving "hands off, I said what I said." 💀
Local(targets), env.Local(targets) — makes copies of the specified targets in the local tree, even if an already up-to-date copy exists in a repository. Returns a list of the target Node or Nodes. 🎀
env.MergeFlags(arg, [unique]) — merges values from arg into the construction variables in env. If arg is a dictionary, then each key-value pair is a construction variable name and the corresponding flags to merge in. If arg isn't a dictionary, MergeFlags tries to convert it into one before merging anything. 🧚

env.ParseFlags is what does that conversion, so anything being converted is subject to the same limitations: ParseFlags knows which construction variables certain flags should go to — but not all of them, and only for GCC and compatible compiler chains. Also, arg has to be a single object, so if you wanna pass multiple strings, you gotta wrap them in a list. 🫶

If unique is true (and, bestie, that's the default), duplicate values are not retained. When there is duplication, any construction variable names ending in PATH keep the left-most value, so the path search order doesn't get messed up. Every other construction variable keeps the right-most value instead. If unique is false, values get appended even if they're straight-up duplicates. 🙈

Examples:

# Add an optimization flag to $CCFLAGS.
env.MergeFlags({'CCFLAGS': '-O3'})

# Combine the flags returned from running pkg-config with an optimization
# flag and merge the result into the construction variables.
env.MergeFlags(['!pkg-config gtk+-2.0 --cflags', '-O3'])

# Combine an optimization flag with the flags returned from running pkg-config
# for two distinct packages and merge into the construction variables.
env.MergeFlags(
    [
        '-O3',
        '!pkg-config gtk+-2.0 --cflags --libs',
        '!pkg-config libpng12 --cflags --libs',
    ]
)

NoCache(target, ...), env.NoCache(target, ...) — gives you a list of files that should not be cached whenever the CacheDir method has been activated. The targets you specify can be a list, or just a single target. ✨

For multiple files, list them either as separate arguments to the NoCache method or as one list. NoCache will also happily accept the return value of any of the construction environment Builder methods. 🌸

Calling NoCache on directories and other non-File Node types does nothing, because only File Nodes get cached. That's the rule. 💅

Examples:

NoCache('foo.elf')
NoCache(env.Program('hello', 'hello.c'))

NoClean(targets, ...), env.NoClean(targets, ...) — names files or directories that should not be removed whenever a specified target (or its dependencies) is selected and clean mode is active (that's the -c command-line option, iykyk). targets can be one or more file or directory names or nodes, and/or lists of names or nodes. And yes, you can call NoClean multiple times. 🦋

Calling NoClean for a target overrides calling Clean for that same target — so any targets passed to both functions will not be removed in clean mode. No take-backsies.

Examples:

NoClean('foo.elf')
NoClean(env.Program('hello', 'hello.c'))

env.ParseConfig(command, [function, unique]) — updates the current construction environment with values pulled out of the output of running an external command, by handing that output to a helper function. 🌈

command may be a string, or a list of strings, representing the command and its arguments. If function is omitted or is None, then env.MergeFlags gets used. By default, duplicate values are not added to any construction variables — but you can pass unique=False to let duplicates in. 👑

command gets executed using the SCons execution environment (meaning: the construction variable $ENV in the current construction environment). So if command needs extra info to work right, that info has to be set in the execution environment. For example, pkg-config might need a custom value set in the PKG_CONFIG_PATH environment variable. 💅

env.MergeFlags needs to understand the output command produces in order to distribute it to the correct construction variables. It uses a separate function to do that processing — check env.ParseFlags for the details, including a table of options and their corresponding construction variables. If you wanna process the output of command a different way instead, you can supply a custom function, which must accept three arguments: the construction environment to modify, a string argument containing the output from running command, and the optional unique flag. 🎀

ParseDepends(filename, [must_exist, only_one]), env.ParseDepends(filename, [must_exist, only_one]) — parses the contents of filename as a list of dependencies in the style of Make or mkdep, and explicitly establishes every single one of the listed dependencies. 🌸

By default, it's not an error if filename doesn't exist. The optional must_exist argument can be set to True to make SCons raise an exception if the file doesn't exist, or is otherwise unreachable. 🙈

The optional only_one argument can be set to True to have SCons raise an exception if the file contains dependency info for more than one target. That's a tiny sanity check 🔍 for files meant to be generated by stuff like the gcc -M flag, which should typically only write dependency info for one output file into a corresponding .d file. cute little safety net.

filename, plus every file listed inside it, gets interpreted relative to the directory of the SConscript file that calls the ParseDepends function. 💖

env.ParseFlags(flags, ...) — parses one or more strings containing typical command-line flags for GCC-style tool chains, and returns a dictionary with the flag values sorted into the appropriate SCons construction variables. ⭐

It's meant as a companion to the env.MergeFlags method, but it lets you modify the values in the returned dictionary before merging them into the construction environment, in case that's something you need. (And note: env.MergeFlags calls this method whenever its argument isn't a dictionary, so you usually don't need to call env.ParseFlags directly — unless you specifically wanna mess with the values. 😌)

If the first character in any string is an exclamation mark (!), then the rest of that string gets executed as a command, and the output from that command is parsed as GCC tool chain command-line flags and added to the resulting dictionary. That's how you call a *-config command — the kind that's typical of the POSIX programming environment, like pkg-config. Heads up though: that command is executed using the SCons execution environment, so if it needs extra information, that information has to be provided explicitly. See ParseConfig for the full tea. ☕

Flag values are translated according to the prefix found, and added to the following construction variables: 👇

-arch — that's a CCFLAGS and LINKFLAGS situation 💅
-D — goes straight into CPPDEFINES fr
-framework — FRAMEWORKS, obviously 🍓
-frameworkdir= — FRAMEWORKPATH
-fmerge-all-constants — CCFLAGS, LINKFLAGS
-fopenmp — CCFLAGS, LINKFLAGS
-fsanitize — CCFLAGS, LINKFLAGS
-include — CCFLAGS
-imacros — CCFLAGS
-isysroot — CCFLAGS, LINKFLAGS
-isystem — CCFLAGS
-iquote — CCFLAGS
-idirafter — CCFLAGS
-I — CPPPATH, bestie
-l — LIBS
-L — LIBPATH
-mno-cygwin — CCFLAGS, LINKFLAGS
-mwindows — LINKFLAGS
-openmp — CCFLAGS, LINKFLAGS
-pthread — CCFLAGS, LINKFLAGS
-std= — CFLAGS
-stdlib= — CXXFLAGS
-Wa, — ASFLAGS, CCFLAGS
-Wl,-rpath= — RPATH
-Wl,-R, — RPATH
-Wl,-R — RPATH
-Wl, — LINKFLAGS
-Wp, — CPPFLAGS
- — CCFLAGS
+ — CCFLAGS, LINKFLAGS

Anything else that's just vibing there with no option attached? SCons assumes it's a library name and yeets it into the $LIBS construction variable. iconic 💖

Examples, and the way they ALL give you the same result is lowkey satisfying:

dict = env.ParseFlags('-O2 -Dfoo -Dbar=1')
dict = env.ParseFlags('-O2', '-Dfoo', '-Dbar=1')
dict = env.ParseFlags(['-O2', '-Dfoo -Dbar=1'])
dict = env.ParseFlags('-O2', '!echo -Dfoo -Dbar=1')

✨ `Platform(plat)`, `env.Platform(plat)` ✨

When you call it as a global function, it hands you back a callable platform object — and which one you get is chosen by plat (it defaults to the detected platform for your current system, no cap). Then you can use that object to initialize a construction environment by passing it as the platform keyword argument to the Environment function. main character energy 🫶

Example:

env = Environment(platform=Platform('win32'))

But when you call it as a method on an environment? It calls the platform object that plat points to, and updates that environment. slay.

env.Platform('posix')

Want the full tea? See the manpage section "Construction Environments" for all the details 🦋

✨ `Precious(target, ...)`, `env.Precious(target, ...)` ✨

Marks target as precious so it does not get deleted before it's rebuilt. Normally SCons deletes a target before building it — but precious ones get spared 💀 You can pass multiple targets in a single call, and they can be strings and/or nodes. It returns a list of the affected target nodes, periodt.

✨ `env.Prepend(key=val, [...])` ✨

Prepends values to construction variables in the current construction environment. Works like env.Append (see that for details, bestie), except the values get added to the front rather than the end of whatever the construction variable already was. it's giving "front of the line" 😌

Example:

env.Prepend(CCFLAGS='-g ', FOO=['foo.yyy'])

See also env.Append, env.AppendUnique and env.PrependUnique 🌸

✨ `env.PrependENVPath(name, newpath, [envname, sep, delete_existing=True])` ✨

Prepends directory paths from newpath onto a search-path entry called name in construction variable envname in the current environment (env). If envname isn't given, the default is "ENV" (see $ENV). envname is expected to point at a dictionary-like object — and if it doesn't exist in env, it gets created as an initially empty dict. no biggie.

newpath can be a string, a directory node, or a list of strings. If it's a string, it may contain multiple paths separated by the system path separator (os.pathsep), or by the value of sep if you specified one. Top-relative path strings (the ones starting with #) are recognized. The type of the existing value of name is preserved, fr fr.

Paths will only show up once. Duplicate paths in newpath get removed, and the first occurrence is kept so the path order stays intact. If delete_existing is true (which is the default), existing duplicates get removed before prepending — otherwise, new duplicates just get skipped. During all the comparisons, paths get normalized, so you don't run into issues with case differences (on case-insensitive filesystems) or with relative paths that might refer back to the same directory. The stored values are not modified by this process. 💅

Example:

print('before:', env['ENV']['INCLUDE'])
include_path = '/foo/bar:/foo'
env.PrependENVPath('INCLUDE', include_path)
print('after:', env['ENV']['INCLUDE'])

Yields:

before: /biz:/foo
after: /foo/bar:/foo:/biz

✨ `env.PrependUnique(key=val, [...], [delete_existing=False])` ✨

Prepends values to construction variables in the current construction environment, while maintaining uniqueness. Works like env.Append, except values go to the front rather than the end of the construction variable, and any values that would become duplicates just... don't get added. obsessed with the restraint ✨

If delete_existing is set to a true value, then for any duplicate, the existing instance of val is first removed, then val is inserted — which has the effect of moving it to the front. iconic.

Example:

env.PrependUnique(CCFLAGS='-g', FOO=['foo.yyy'])

See also env.Append, env.AppendUnique and env.Prepend 💖

✨ `Progress(callable, [interval])`, `Progress(string, [interval, file, overwrite])`, `Progress(list_of_strings, [interval, file, overwrite])` ✨

Lets SCons show you the progress being made during the build — by displaying a string or calling a function while it evaluates Nodes (e.g. files). the way it keeps you updated 🥹

If the first argument is a Python callable (a function, or an object with a __call__ method), that function gets called once every interval times a Node is evaluated (default 1). The callable gets passed the evaluated Node as its only argument. (For future compatibility, it's a good idea to also add *args and **kwargs to your function or method signatures — this prevents your code from breaking if SCons ever changes the interface to call the function with additional arguments down the line. just a heads up 🫶)

Here's a simple custom progress function that prints a string with the Node name every 10 Nodes:

def my_progress_function(node, *args, **kwargs):
    print('Evaluating node %s!' % node)
Progress(my_progress_function, interval=10)

And here's a more complicated custom progress display object that prints a string with a count every 100 evaluated Nodes. Note the use of \r (a carriage return) at the end so the string overwrites itself on your display — chef's kiss:

import sys
class ProgressCounter(object):
    count = 0
    def __call__(self, node, *args, **kw):
        self.count += 100
        sys.stderr.write('Evaluated %s nodes\r' % self.count)

Progress(ProgressCounter(), interval=100)

If the first argument to Progress is a string or a list of strings, it's taken as text to be displayed every interval evaluated Nodes. And if it's a list of strings, each string in the list gets displayed in rotating fashion every interval evaluated Nodes. a literal spinner, we love to see it 🌀

By default it prints to standard output. You can specify a different output stream with the file keyword argument — but the caller has to pass it already opened, bestie.

This one prints a series of dots on the error output, one dot for every 100 evaluated Nodes:

import sys
Progress('.', interval=100, file=sys.stderr)

If the string contains the verbatim substring $TARGET, it gets replaced with the Node. But note — for performance reasons, this is not a regular SCons variable substitution, so you can't use other variables or use curly braces. sorry babe 😭

This next example prints the name of every evaluated Node, using a carriage return (\r) to cause each line to be overwritten by the next line, and the overwrite keyword argument (default False) to make sure the previously-printed file name gets overwritten with blank spaces:

import sys
Progress('$TARGET\r', overwrite=True)

You can also use a list of strings to implement a "spinner" on the user's screen, changing every five evaluated Nodes:

Progress(['-\r', '\\\r', '|\r', '/\r'], interval=5)

✨ `Pseudo(target, ...)`, `env.Pseudo(target, ...)` ✨

Marks target as a pseudo target — meaning it doesn't represent the production of any physical target file. And if any pseudo target does exist? SCons will abort the build with an error. no pressure 💀 You can pass multiple targets in a single call, and they can be strings and/or Nodes. Returns a list of the affected target nodes.

Pseudo might come in handy alongside a builder call (like Command) that doesn't create a physical target, where the behavior would be wrong if the target accidentally existed. It's similar in concept to the GNU make .PHONY target. SCons also provides a powerful target alias capability (see Alias) which may give you more flexibility in a lot of situations when you're defining target names that aren't directly built. options on options, we love it 🌈

✨ `PyPackageDir(modulename)`, `env.PyPackageDir(modulename)` ✨

Finds the location of modulename, which can be a string or a sequence of strings — each one representing the name of a Python module. Construction variables get expanded in modulename. It returns a Directory Node (see Dir), or a list of Directory Nodes if modulename is a sequence. And None gets returned for any module that isn't found. 🙈

When you use a Tool module that's installed as a Python module, you need to specify a toolpath argument to Tool, Environment or Clone — because tools outside the standard project locations (site_scons/site_tools) won't be found otherwise. Using PyPackageDir lets this path be discovered at runtime instead of hardcoding the path. so much cleaner, honestly 👑

Example:

env = Environment(
    tools=["default", "ExampleTool"],
    toolpath=[PyPackageDir("example_tool")]
)

✨ `env.Replace(key=val, [...])` ✨

Replaces construction variables in the Environment with the specified keyword arguments. out with the old, in with the new 💅

Example:

env.Replace(CCFLAGS='-g', FOO='foo.xxx')

🌟 `Repository(directory)`, `env.Repository(directory)` 🌟

So picture this: you're setting up directory as a repository to be searched for files that contribute to the build. Bestie, that's it, that's the vibe check. 💖

Multiple calls to Repository are allowed, and repositories get searched in the order you gave them. Heads up though: repositories specified via command-line option have higher priority. 👑

In scons, a repository is a partial or complete copy of the source tree, from the top-level directory down, containing source files that can be used to build targets in the current worktree. Repositories can also contain derived files. Like, example: an official source tree maintained by an integrator. If a repository contains derived files, they should be the result of building with SCons, so a signature database (sconsign) is present in the repository, allowing better decisions on whether they're up-to-date or not. 🫶

✨ Important note: if an up-to-date derived file already exists in a repository, scons will not make a copy in the local directory tree. If you need a local copy to be made, use the Local method.

💅 `Requires(target, prerequisite)`, `env.Requires(target, prerequisite)` 💅

OK so this one specifies an order-only relationship between target and prerequisite. The prerequisites will be (re)built, if necessary, before the target file(s) — but the target file(s) do not actually depend on the prerequisites and will not be rebuilt simply because the prerequisite file(s) change. It's giving "we're just ordering things, not committing to anything" energy. 😌

target and prerequisite may each be a string or Node, or a list of strings or Nodes. If there are multiple target values, the prerequisite(s) are added to each one. Returns a list of the affected target nodes. 🌸

Example:

env.Requires('foo', 'file-that-must-be-built-before-foo')

🎀 `Return([vars..., stop=True])` 🎀

This one returns to the calling SConscript, optionally returning the values of variables named in vars. Multiple strings containing variable names may be passed to Return. A string containing white space is split into individual variable names. 🦋

It returns the value if one variable is specified, else returns a tuple of values. Returns an empty tuple if vars is omitted. ✨

By default Return stops processing the current SConscript and returns immediately. The optional stop keyword argument may be set to a false value to continue processing the rest of the SConscript file after the Return call (this was the default behavior prior to SCons 0.98). However — and this is the part everyone forgets — the values returned are still the values of the variables in the named vars at the point Return was called. 😭

Examples:

# Returns no values (evaluates False)
Return()

# Returns the value of the 'foo' Python variable.
Return("foo")

# Returns the values of the Python variables 'foo' and 'bar'.
Return("foo", "bar")

# Returns the values of Python variables 'val1' and 'val2'.
Return('val1 val2')

🌈 `Scanner(function, [name, argument, skeys, path_function, node_class, node_factory, scan_check, recursive])`, `env.Scanner(function, [name, argument, skeys, path_function, node_class, node_factory, scan_check, recursive])` 🌈

Creates a Scanner object for the specified function. See manpage section "Scanner Objects" for a complete explanation of the arguments and behavior. Go read that one, it's a whole thing. 🔥

👑 `SConscript(scriptnames, [exports, variant_dir, duplicate, must_exist])`, `env.SConscript(scriptnames, [exports, variant_dir, duplicate, must_exist])`, `SConscript(dirs=subdirs, [name=scriptname, exports, variant_dir, duplicate, must_exist])`, `env.SConscript(dirs=subdirs, [name=scriptname, exports, variant_dir, duplicate, must_exist])` 👑

Executes subsidiary SConscript (build configuration) file(s). There are two ways to call the SConscript function, bestie, so let's go. 💀

💖 The first calling style 💖

You supply one or more SConscript file names as the first positional argument, which can be a string or a list of strings. If there is a second positional argument, it is treated as if the exports keyword argument had been given (see below). Main character behavior. ✨

Examples:

SConscript('SConscript')  # run SConscript in the current directory
SConscript('src/SConscript')  # run SConscript in the src directory
SConscript(['src/SConscript', 'doc/SConscript'])
SConscript(Split('src/SConscript doc/SConscript'))
config = SConscript('MyConfig.py')

🦋 The second calling style 🦋

You omit the positional argument naming the script and instead specify directory names using the dirs keyword argument. The value can be a string or list of strings. In this case, scons will execute a subsidiary configuration file named SConscript (by default) in each of the specified directories. You may specify a name other than SConscript by supplying an optional name=scriptname keyword argument. The first three examples below have the same effect as the first three examples above. So cute, so symmetrical. 🎀

SConscript(dirs='.')  # run SConscript in the current directory
SConscript(dirs='src')  # run SConscript in the src directory
SConscript(dirs=['src', 'doc'])
SConscript(dirs=['sub1', 'sub2'], name='MySConscript')

💜 The `exports` keyword 💜

The optional exports keyword argument specifies variables to make available for use by the called SConscripts, which are evaluated in an isolated context and otherwise do not have access to local variables from the calling SConscript. (Isolation, but make it cute. 🫶)

The value may be a string or list of strings representing variable names, or a dictionary mapping local names to the names they can be imported by. For the first (scriptnames) calling style, a second positional argument will also be interpreted as exports; the second (directory) calling style accepts no positional arguments and must use the keyword form. These variables are locally exported only to the called SConscript file(s), and take precedence over any same-named variables in the global pool managed by the Export function. The subsidiary SConscript files must use the Import function to import the variables into their local scope. 👑

Examples:

foo = SConscript('sub/SConscript', exports='env')
SConscript('dir/SConscript', exports=['env', 'variable'])
SConscript(dirs='subdir', exports='env variable')
SConscript(dirs=['one', 'two', 'three'], exports='shared_info')

🌸 The `variant_dir` keyword 🌸

If the optional variant_dir argument is present, it causes an effect equivalent to the VariantDir function, but in effect only within the scope of the SConscript call. The variant_dir argument is interpreted relative to the directory of the calling SConscript file. The source directory is the directory in which the called SConscript file resides and the SConscript file is evaluated as if it were in the variant_dir directory. Thus:

SConscript('src/SConscript', variant_dir='build')

is equivalent to:

VariantDir('build', 'src')
SConscript('build/SConscript')

If the sources are in the same directory as the SConstruct,

SConscript('SConscript', variant_dir='build')

is equivalent to:

VariantDir('build', '.')
SConscript('build/SConscript')

🍓 The `duplicate` keyword 🍓

The optional duplicate argument is interpreted as for VariantDir. If the variant_dir argument is omitted, the duplicate argument is ignored. See the description of VariantDir for additional details and restrictions. 👀

🧚 The `must_exist` keyword 🧚

If the optional must_exist is True (the default), an exception is raised if a requested SConscript file is not found. To allow missing scripts to be silently ignored (the default behavior prior to SCons version 3.1), pass must_exist=False in the SConscript call.

🔥 Changed in 4.6.0: must_exist now defaults to True.

💫 Composite examples, because we love a vibe 💫

# collect the configuration information and use it to build src and doc
shared_info = SConscript('MyConfig.py')
SConscript('src/SConscript', exports='shared_info')
SConscript('doc/SConscript', exports='shared_info')

# build debugging and production versions.  SConscript
# can use Dir('.').path to determine variant.
SConscript('SConscript', variant_dir='debug', duplicate=0)
SConscript('SConscript', variant_dir='prod', duplicate=0)

# build debugging and production versions.  SConscript
# is passed flags to use.
opts = { 'CPPDEFINES' : ['DEBUG'], 'CCFLAGS' : '-pgdb' }
SConscript('SConscript', variant_dir='debug', duplicate=0, exports=opts)
opts = { 'CPPDEFINES' : ['NODEBUG'], 'CCFLAGS' : '-O' }
SConscript('SConscript', variant_dir='prod', duplicate=0, exports=opts)

# build common documentation and compile for different architectures
SConscript('doc/SConscript', variant_dir='build/doc', duplicate=0)
SConscript('src/SConscript', variant_dir='build/x86', duplicate=0)
SConscript('src/SConscript', variant_dir='build/ppc', duplicate=0)

⭐ What it returns ⭐

SConscript returns the values of any variables named by the executed SConscript file(s) in arguments to the Return function. If a single SConscript call causes multiple scripts to be executed, the return value is a tuple containing the returns of each of the scripts. If an executed script does not explicitly call Return, it returns None. Periodt. 💅

🌺 `SConscriptChdir(value)` 🌺

By default, scons changes its working directory to the directory in which each subsidiary SConscript file lives while reading and processing that script. This behavior may be disabled by specifying an argument which evaluates false, in which case scons will stay in the top-level directory while reading all SConscript files. (This may be necessary when building from repositories, when all the directories in which SConscript files may be found don't necessarily exist locally.) You may enable and disable this ability by calling SConscriptChdir multiple times. It's giving toggle energy. 🔄

Example:

SConscriptChdir(False)
SConscript('foo/SConscript')  # will not chdir to foo
SConscriptChdir(True)
SConscript('bar/SConscript')  # will chdir to bar

💖 `SConsignFile([name, dbm_module])`, `env.SConsignFile([name, dbm_module])` 💖

Specify where to store the SCons signature database, and which database format to use. This may be useful to specify alternate database files and/or file locations for different types of builds. Your signatures, your rules, your location. ✨

The optional name argument is the base name of the database file(s). The database lands relative to the directory that holds the top-level SConstruct file, unless name is an absolute path name. The default is .sconsign. Bestie listen: the actual database file(s) chilling on disk may have an appropriate suffix tacked on by whichever dbm_module got chosen, and they may also include the name of the hash format (peep --hash-format for that one). ✨

The optional dbm_module argument says which Python database module we're using to read/write the file. Tiny lil catch: the module has to be imported first, and only then do you pass the imported module name as the argument. The default is a custom SCons.dblite module that uses pickled Python data structures — and it works on all Python versions, iconic behavior honestly 🫶. Want other available types? Go read the documentation of the Python dbm module, it's giving options.

If you call it with no arguments at all, the database defaults to .sconsign.dblite in the top directory of the project — which is also the default if SConsignFile is never called. Same vibe either way, no cap.

The setting is global, so the only actual difference between the global function form and the environment method form is variable expansion on name. And heads up 💀 — there should only be one active call to this function/method in a given build setup.

If name is set to None, scons will store file signatures in a separate .sconsign file in each directory, not in a single combined database file. This is a backwards-compatibility measure keeping alive the behavior that was the default prior to SCons 0.97 (i.e. before 2008, ancient history fr fr). Use of this mode is deprecated and should not be used in new projects.

Deprecated since version 4.11.0: the signature-file-per-directory mode is deprecated and will be removed in a future release. 💀 Don't build your whole personality on it, it's on the way out.

Examples:

# Explicitly stores signatures in ".sconsign.dblite"
# in the top-level SConstruct directory (the default behavior).
SConsignFile()

# Stores signatures in the file "etc/scons-signatures"
# relative to the top-level SConstruct directory.
# SCons will add a database suffix to this name.
SConsignFile("etc/scons-signatures")

# Stores signatures in the specified absolute file name.
# SCons will add a database suffix to this name.
SConsignFile("/home/me/SCons/signatures")

# Stores signatures in a separate .sconsign file
# in each directory.
SConsignFile(None)

# Stores signatures in a GNU dbm format .sconsign file
import dbm.gnu
SConsignFile(dbm_module=dbm.gnu)

`env.SetDefault(key=val, [...])`

Okay so this one sets construction variables to default values specified with the keyword arguments — but only if, and only if, those variables aren't already set. It's a vibe check before assigning, basically. The following statements are equivalent, literally:

env.SetDefault(FOO='foo')
if 'FOO' not in env:
    env['FOO'] = 'foo'

See? Same thing, one's just cuter. 💅

`SetOption(name, value)`, `env.SetOption(name, value)`

Sets option variable name to value. The settable options have corresponding command-line options, as shown in the table, which you can use for one-time overrides — and a value set via the command line takes precedence over one set with SetOption. Periodt, command line wins.

And not just SConscript files, bestie: SetOption calls can also be placed in a site_init.py file. Your current value can be queried with GetOption, in case you forgot what you did 🙈.

The behavior of the options is described in the manpage entry for the associated command-line option. The value parameter is mandatory — no skipping it. For boolean option values (the ones where the command-line option does not take an option-argument), use a value which evaluates to true (e.g. True, 1) or false (e.g. False, 0). Keep it simple.

Now here's the part that trips people: options which affect the reading and processing of SConscript files are not settable using SetOption, since those files have to be read in order to find the SetOption call in the first place. Chicken-and-egg situation, it's giving paradox 🦋. Can't set the thing that decides how we read the thing.

For project-specific options (sometimes called local options) added via an AddOption call, SetOption is allowed only after the AddOption call has completed successfully, and only if that call included the settable=True keyword argument. No settable=True, no deal. ✨

the settable variables + their flag besties 🫶

okay so here's the whole lineup — every settable name, the command-line argument it vibes with, and the lil note about its type:

clean — command-line: -c, --clean, --remove — Boolean
diskcheck — command-line: --diskcheck — List
duplicate — command-line: --duplicate — String
experimental — command-line: --experimental — Set. Since 4.2.
hash_chunksize — command-line: --hash-chunksize — Integer. Supersedes md5_chunksize. Since 4.2
hash_format — command-line: --hash-format — String. Since 4.2
help — command-line: -h, --help — Boolean
implicit_cache — command-line: --implicit-cache — Boolean
implicit_deps_changed — command-line: --implicit-deps-changed — Boolean. Also sets implicit_cache. Settable since 4.2
implicit_deps_unchanged — command-line: --implicit-deps-unchanged — Boolean. Also sets implicit_cache. Settable since 4.2
max_drift — command-line: --max-drift — Integer
md5_chunksize — command-line: --hash-chunksize — Integer. Superseded by hash_chunksize. Deprecated since 4.2
no_exec — command-line: -n, --no-exec, --just-print, --dry-run, --recon — Boolean
no_progress — command-line: -Q — Boolean. See [6]
num_jobs — command-line: -j, --jobs — Integer
random — command-line: --random — Boolean
silent — command-line: -s, --silent, --quiet — Boolean
stack_size — command-line: --stack-size — Integer
warn — command-line: --warn — List

[a] If no_progress is set via SetOption in an SConscript file (but not if set in a site_init.py file) there will still be an initial status message about reading SConscript files since SCons has to start reading them before it can see the SetOption.

😭 yes bestie, that's the tea — the [6] in the table and the [a] down here are the same lil footnote, she just got two names, main character energy fr fr.

Example ✨:

SetOption('max_drift', 0)

`SideEffect(side_effect, target)`, `env.SideEffect(side_effect, target)` 🦋

y'all this one declares side_effect as a side effect of building target. 🎀 and both side_effect and target can be a list, a file name, or a node — flexible queen behavior.

so like, a side effect is a target file that gets created or updated as a side effect of building other targets. the iconic example: a Windows PDB file is created as a side effect of building the .obj files for a static library, and various log files are created/updated as side effects of various TeX commands. 👑

now here's the important part, ngl: if a target is a side effect of multiple build commands, scons will make sure that only one set of commands is executed at a time. which means — you only actually need this method for side-effect targets that are built as a result of multiple build commands. periodt. 💅

and because multiple build commands may update the same side effect file, by default the side_effect target is not automatically removed when the target is removed by the -c option. 🙈 (note though, bestie — the side_effect might still get removed as part of cleaning the directory in which it lives, so don't come for me.) if you want to make sure the side_effect is cleaned whenever a specific target is cleaned, you have to specify this explicitly with the Clean or env.Clean function. no shortcuts, iykyk. 🔥

🫶 and what does it give back? this function returns the list of side effect Node objects that were successfully added. if the list of side effects contained any side effects that had already been added, they are not added and included in the returned list — so a lil bit of dedupe energy happening there, and you'll see it in what comes back. 🌸

🦋 `Split(arg)`, `env.Split(arg)`

okay bestie listen — Split is the "idk how many words are in here, you figure it out" move and it always eats 💖

If arg is a string → it splits on whitespace and hands back a list of strings with the whitespace gone. This is the most common case, and it's perf for turning a pile of filenames into a list instead of you having to type them out as individually quoted words.
If arg is a list or tuple → you get that list or tuple back unchanged. zero touching.
If arg is any other type of object → you just get a list containing that one object.

ngl, those non-string cases don't actually do any splitting at all — the whole point is that they let you hand an argument variable to Split without type-checking it first. no cap ✨

Example:

files = Split("f1.c f2.c f3.c")
files = env.Split("f4.c f5.c f6.c")
files = Split("""
    f7.c
    f8.c
    f9.c
""")

🌸 `env.subst(input, [raw, target, source, conv])`

This one does construction variable interpolation (a.k.a. substitution, a.k.a. the glow-up machine) on input, and input can be a string or a sequence. Substitutable elements look like ${expression}, tho if there's no ambiguity in recognizing the element you can yeet the braces. And if you want a literal $, you write $$. iconic behavior 💅

By default:

leading or trailing white space gets deleted from the result
every run of white space gets squished down to a single space character
and any $( and $) character sequences get stripped right out of the returned string

The optional raw argument:

raw=1 — keeps white space and $(-$) sequences exactly as they are.
raw=2 — the above, plus it discards all characters between any $( and $) pairs (which is what happens when signature calculation does it).

If input is a sequence (list or tuple), every element of the sequence gets expanded, and the results come back to you as a list.

The optional target and source keyword arguments must be set to lists of target and source nodes, respectively — you only need them if you want $TARGET, $TARGETS, $SOURCE and $SOURCES to be available for expansion. fr fr this is usually necessary if you're calling env.subst from inside a Python function that's being used as an SCons action. 🔥

Returned string values (or sequence elements) get converted to their string representation by default. The optional conv argument lets you swap in a different conversion function in place of the default one. so like, if you want Python objects (including SCons Nodes 🫶) returned as Python objects, you can use a Python lambda expression to pass in an unnamed function that just returns its unconverted argument. slay.

Example:

print(env.subst("The C compiler is: $CC"))

def compile(target, source, env):
    sourceDir = env.subst(
        "${SOURCE.srcdir}",
        target=target,
        source=source
    )

source_nodes = env.subst('$EXPAND_TO_NODELIST', conv=lambda x: x)

🎀 `Tag(node, tags)`

Tag annotates file or directory Nodes with info about how the Package Builder should package those files or directories. All Node-level tags are optional, so no pressure bb.

Examples:

# makes sure the built library will be installed with 644 file access mode
Tag(Library('lib.c'), UNIX_ATTR="0o644")

# marks file2.txt to be a documentation file
Tag('file2.txt', DOC)

💜 `Tool(name, [toolpath, key=value, ...])`, `env.Tool(name, [toolpath, key=value, ...])`

Tool locates the tool specification module named name and returns a callable tool object for that tool. Here's the tea on the two forms:

With the environment method form (env.Tool), the tool object is automatically called before the method returns, so it updates env, and name gets appended to the $TOOLS construction variable in that environment.
With the global function form (Tool), the tool object is constructed but not called — it has no environment context to update — so you have to take that returned object and arrange for the call yourself.

The tool module is searched for in the tool search paths (peep the Tools section in the manual page for the details 👀) and also in any paths you specify with the optional toolpath parameter, which has to be a list of strings. If you skip toolpath, then whatever toolpath was supplied when the environment was created gets used — if there was one.

Any leftover keyword arguments get saved in the tool object and passed along to the tool module's generate function when the tool object actually gets called. That generate function can update the construction environment with construction variables and set up any other initialization needed to use the mechanisms the tool describes, and it can use those extra arguments to help guide what it does.

Changed in version 4.2: env.Tool now returns the tool object — previously it did not return (i.e. it returned None).

Examples:

env.Tool('gcc')
env.Tool('opengl', toolpath=['build/tools'])

The returned tool object can be passed to an Environment or Clone call as part of the tools keyword argument — in that case the tool gets applied to the environment being constructed. Or you can call it directly, and then you must pass a construction environment to update as the argument. Either way, the $TOOLS construction variable gets updated too. 💅

Examples:

env = Environment(tools=[Tool('msvc')])

env = Environment()
msvctool = Tool('msvc')
msvctool(env)  # adds 'msvc' to the TOOLS variable
gltool = Tool('opengl', toolpath = ['tools'])
gltool(env)  # adds 'opengl' to the TOOLS variable

✨ `ValidateOptions([throw_exception=False])`

ValidateOptions checks that every option you specified on the command line is either an SCons built-in option or defined via calls to AddOption. SCons is gonna trip on unknown options eventually anyway, but calling this lets the build "fail fast" before it runs a bunch of expensive logic further down. main character energy fr 🔥

Call this function only after the last AddOption call in your SConscript logic. heads up: some tools call AddOption, so if you're getting error messages for arguments that they add, you need to make sure those tools are loaded before you call ValidateOptions. 🙈

If there are any unknown command line options, ValidateOptions prints an error message and exits with an error exit status. But if the optional throw_exception argument is True (the default is False), a SConsBadOptionError is raised instead — which gives your SConscript logic a chance to catch that exception and handle invalid options however you want. Note that this exception name needs to be imported (see the example below 👇).

A super common build problem is typos (or thinkos) — a user enters an option that's just a little off the expected value, or maybe a different word with a similar meaning. It can be useful to abort the build before it goes too far down the wrong path. For example:

$ scons --complier=mingw  # the correct flag is --compiler

Here SCons could go off and run a whole bunch of configure steps using the default value of --compiler, since the misspelled option means it never got supplied the intended value — and that costs developer time trying to track down why the configure logic made the "wrong" choices. 😭 The example below shows catching this:

from SCons.Script.SConsOptions import SConsBadOptionError

AddOption(
    '--compiler',
    dest='compiler',
    action='store',
    default='gcc',
    type='string',
)

# ... other SConscript logic ...

try:
    ValidateOptions(throw_exception=True)
except SConsBadOptionError as e:
    print(f"ValidateOptions detects a fail: ", e.opt_str)
    Exit(3)

New in version 4.5.0

🧚 `Value(value, [built_value], [name])`, `env.Value(value, [built_value], [name])`

Value returns a Node object that represents the Python value you passed in. Value Nodes can be used as dependencies of targets 🫶 and if the string representation of a Value Node changes between SCons runs, it's considered out-of-date and any targets depending on it get rebuilt. And since Value Nodes have no filesystem representation, timestamps aren't used at all — the timestamp deciders do the same content-based up-to-date check instead. lowkey iconic.

The optional built_value argument can be specified when the Value Node is created, to indicate the Node should already be considered "built."

The optional name parameter can be provided as an alternative name for the resulting Value node — this is advised if the value parameter can't be converted to a string.

Value Nodes have a write method that can be used to "build" a Value Node by setting a new value, and the corresponding read method returns the built value of the Node. 💖

Changed in version 4.0: the name parameter was added.

Examples:

env = Environment()

def create(target, source, env):
    """Action function to create a file from a Value.

    Writes 'prefix=$SOURCE' into the file name given as $TARGET.
    """
    with open(target[0], 'wb') as f:
        f.write(b'prefix=' + source[0].get_contents() + b'\n')

# Fetch the prefix= argument, if any, from the command line.
# Use /usr/local as the default.
prefix = ARGUMENTS.get('prefix', '/usr/local')

# Attach builder named Config to the construction environment
# using the 'create' action function above.
env['BUILDERS']['Config'] = Builder(action=create)
env.Config(target='package-config', source=Value(prefix))

def build_value(target, source, env):
    """Action function to "build" a Value.

    Writes contents of $SOURCE into $TARGET, thus updating if it existed.
    """
    target[0].write(source[0].get_contents())

output = env.Value('before')
input = env.Value('after')

# Attach a builder named UpdateValue to the construction environment
# using the 'build_value' action function above.
env['BUILDERS']['UpdateValue'] = Builder(action=build_value)
env.UpdateValue(target=Value(output), source=Value(input))

VariantDir(variant_dir, src_dir, [duplicate]), env.VariantDir(variant_dir, src_dir, [duplicate]) — okay so this one sets up a mapping that defines a variant build directory living at variant_dir 💫. Heads up bestie: src_dir must not be underneath variant_dir — that's a hard no 🙅‍♀️. And like, a VariantDir mapping is global, even when you call it as env.VariantDir. (yes the env version still goes global, it's giving main character energy). You can call VariantDir multiple times with the same src_dir to set up multiple variant builds with different options, which is lowkey the whole point ✨.

So variant_dir can honestly be any convenient location you want, but — and this is the catch — if it's not under the project top directory, the normal target selection rules will not pick targets in the variant directory unless you explicitly specify them. No cap, you gotta name them yourself.

When files under variant_dir get referenced, SCons backfills the missing files from src_dir as needed to create a complete build tree 🧚. By default, SCons physically duplicates source files, subsidiary SConscript files, and any needed directory structure into the variant directory. Which makes a build in the variant directory equivalent to a build in the source tree — even when intermediate source files are generated, scanners search for included files using source-relative paths, or tools are hard-coded to emit derived files beside their sources. Iconic, honestly. Only the files SCons determines are needed for the build get duplicated into variant_dir, so it's not just dumping everything. And where possible, duplication is performed by linking rather than copying, which is the efficient queen behaviour 💅. The duplication strategy can be adjusted using the --duplicate command-line option or SetOption.

If the duplicate argument is set to False, SCons does not duplicate source files. Instead it automatically invokes builders using the original source paths from src_dir and derived file paths in variant_dir. This is more efficient than duplicating and is safe for most builds; if it causes problems, use duplicate=True (the default) 🫶.

Note — when you switch an existing variant directory from duplicating to non-duplicating, the previously duplicated source files are not automatically removed 😭. SCons will continue to prefer these stale copies over the original sources, possibly preventing detection of changes to the originals. To avoid this issue, clean the build tree before switching. After the switch, SCons no longer tracks duplicated files in the variant directory and will not remove them during cleaning. So like… clean first, bestie. Trust.

Variant directories can also be established using the SConscript function in conjunction with calling a subsidiary SConscript file.

Examples:

# use names in the build directory, not the source directory
VariantDir('build', 'src', duplicate=False)
Program('build/prog', 'build/source.c')

# this builds both the source and docs in a separate subtree
VariantDir('build', '.', duplicate=False)
SConscript(dirs=['build/src', 'build/doc'])

# same as previous example, but only uses SConscript
SConscript(dirs='src', variant_dir='build/src', duplicate=False)
SConscript(dirs='doc', variant_dir='build/doc', duplicate=False)

VariantDir works most naturally when used with a subsidiary SConscript file, fr fr. The subsidiary SConscript must be called as if it were in variant_dir, regardless of the value of duplicate. Use the exports keyword argument to pass parameters or an appropriately configured environment object so the subsidiary SConscript can pick up the right settings for that variant build. The SConscript must Import these exported values before using them 🔑.

env1 = Environment(...settings for variant1...)
env2 = Environment(...settings for variant2...)

# run src/SConscript by using the variant dir paths
VariantDir('build/variant1', 'src')
SConscript('build/variant1/SConscript', exports={"env": env1})
VariantDir('build/variant2', 'src')
SConscript('build/variant2/SConscript', exports={"env": env2})

Virtualenv() — if the SCons process is running inside a Python virtual environment, this returns the path to the directory where that environment is stored 🌸. If it's not, you get an empty string. And plot twist: you can just treat the result as a boolean value if you don't actually need the path. Slay.
WhereIs(program, [path, pathext, reject]), env.WhereIs(program, [path, pathext, reject]) — searches for the specified executable program, returning the full path to the program, or None if it can't find it 🕵️‍♀️.

When called as a construction environment method, it searches the paths in the path keyword argument, or if that's None (the default) the paths listed in the construction environment (env['ENV']['PATH']). The external environment's path list (os.environ['PATH']) is used as a fallback if the key env['ENV']['PATH'] does not exist.

On Windows systems, it searches for executable programs with any of the file extensions listed in the pathext keyword argument, or if None (the default) the pathname extensions listed in the construction environment (env['ENV']['PATHEXT']). The external environment's pathname extensions list (os.environ['PATHEXT']) is used as a fallback if the key env['ENV']['PATHEXT'] does not exist.

When called as a global function, it uses the external environment's path os.environ['PATH'] and path extensions os.environ['PATHEXT'], respectively, if path and pathext are None.

And it will not select any path name or names in the optional reject list. Not today, rejected paths 💀.

✨ SConscript Variables ✨

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

🌈 `ARGLIST`

A list of the variable=value build variable arguments specified on the command line. Each element in the list is a tuple consisting of the variable and its value 📝. The separate variable and value elements of the tuple can be accessed by subscripting for elements [0] and [1] of the tuple, or — more readably — by using tuple unpacking. Examples:

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

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

💖 `ARGUMENTS`

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

Example:

if ARGUMENTS.get("debug", ""):
    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 Default function 🎯. It does not contain any dependent targets that scons selects for building as a result of making sure the specified targets are up to date, if those targets did not appear on the command line. And the list is empty if neither command line targets nor Default calls are present.

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

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

Example:

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

🌸 `COMMAND_LINE_TARGETS`

A list of the targets explicitly specified on the command line 💅. If there are command line targets, this list has the same contents as BUILD_TARGETS. If there are no targets specified on the command line, this list is empty. The elements of this list are strings. This can be used, for example, to take specific actions only when a certain target(s) are explicitly requested for building. It's giving "only do the special thing when asked" energy ✨.

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 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 changes 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 😭. Order matters, bestie, don't get caught out.

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

from SCons.Script import *

💖 Construction Variables 💖

Okay bestie, this is where it gets good. ✨

Construction Variables are key-value pairs used to store information in a construction environment that is needed for builds using that environment. Naming rules? Same as Python identifier naming, no exceptions: the initial character must be an underscore or letter, followed by any number of underscores, letters, or digits. The convention (and honestly the vibe) is to use uppercase for all letters so you can spot them instantly. 👑

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

Construction variables are referenced as if they were keys and values in a Python dictionary:

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

Construction variables can also be retrieved and set by using the Dictionary method of the construction environment to create an actual dictionary:

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

in the previous example, since cvars is an external copy, the value of $CC in the construction environment itself is not changed by the assignment. <- important, don't get caught lacking 🫶

Construction variables can set by passing them as keyword arguments when creating a new construction environment:

env = Environment(CC="cc")

or when copying a construction environment using the Clone method:

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

Construction variables 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 construction environment as a whole. This concept is called an override:

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

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

Note the actual list available at execution time will never include all of these, as the ones detected as not being applicable (wrong platform, necessary external command or files not installed, etc.) will not be set up. Correct build setups should be resilient to the possible absence of certain construction variables 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 env.Dump method can be called to examine the construction variables set in a particular environment.

__LDMODULEVERSIONFLAGS — this construction variable automatically introduces $_LDMODULEVERSIONFLAGS if $LDMODULEVERSION is set. Otherwise, it evaluates to an empty string.
__SHLIBVERSIONFLAGS — this construction variable automatically introduces $_SHLIBVERSIONFLAGS if $SHLIBVERSION is set. Otherwise, it evaluates to an empty string.
APPLELINK_COMPATIBILITY_VERSION — on Mac OS X this is used to set the linker flag -compatibility_version.

The value is specified as X[.Y[.Z]] where X is between 1 and 65535, Y can be omitted or between 1 and 255, Z can be omitted or between 1 and 255. This value will be derived from $SHLIBVERSION if not specified. The lowest digit will be dropped and replaced by a 0. 💀

If the $APPLELINK_NO_COMPATIBILITY_VERSION is set then no -compatibility_version will be output.

See MacOS's ld manpage for more details.

_APPLELINK_COMPATIBILITY_VERSION — a macro (by default a generator function) used to create the linker flags to specify apple's linker's -compatibility_version flag. The default generator uses $APPLELINK_COMPATIBILITY_VERSION and $APPLELINK_NO_COMPATIBILITY_VERSION and $SHLIBVERSION to determine the correct flag.
APPLELINK_CURRENT_VERSION — on Mac OS X this is used to set the linker flag -current_version.

The value is specified as X[.Y[.Z]] where X is between 1 and 65535, Y can be omitted or between 1 and 255, Z can be omitted or between 1 and 255. This value will be set to $SHLIBVERSION if not specified.

If the $APPLELINK_NO_CURRENT_VERSION is set then no -current_version will be output.

See MacOS's ld manpage for more details.

_APPLELINK_CURRENT_VERSION — a macro (by default a generator function) used to create the linker flags to specify apple's linker's -current_version flag. The default generator uses $APPLELINK_CURRENT_VERSION and $APPLELINK_NO_CURRENT_VERSION and $SHLIBVERSION to determine the correct flag.
APPLELINK_NO_COMPATIBILITY_VERSION — set this to any True (1|True|non-empty string) value to disable adding -compatibility_version flag when generating versioned shared libraries.

This overrides $APPLELINK_COMPATIBILITY_VERSION.

APPLELINK_NO_CURRENT_VERSION — set this to any True (1|True|non-empty string) value to disable adding -current_version flag when generating versioned shared libraries.

This overrides $APPLELINK_CURRENT_VERSION.

AR — the static library archiver.
ARCHITECTURE — specifies the system architecture for which the package is being built. The default is the system architecture of the machine on which SCons is running. This is used to fill in the Architecture: field in an Ipkg control file, and the BuildArch: field in the RPM .spec file, as well as forming part of the name of a generated RPM package file.

See the Package builder.

ARCOM — the command line used to generate a static library from object files.
ARCOMSTR — the string displayed when a static library is generated from object files. If this is not set, then $ARCOM (the command line) is displayed.

env = Environment(ARCOMSTR = "Archiving $TARGET")

ARFLAGS — general options passed to the static library archiver.
AS — the assembler.
ASCOM — the command line used to generate an object file from an assembly-language source file.
ASCOMSTR — the string displayed when an object file is generated from an assembly-language source file. If this is not set, then $ASCOM (the command line) is displayed.

env = Environment(ASCOMSTR = "Assembling $TARGET")

ASFLAGS — general options passed to the assembler.
ASPPCOM — the command line used to assemble an assembly-language source file into an object file after first running the file through the C preprocessor. Any options specified in the $ASFLAGS and $CPPFLAGS construction variables are included on this command line.
ASPPCOMSTR — the string displayed when an object file is generated from an assembly-language source file after first running the file through the C preprocessor. If this is not set, then $ASPPCOM (the command line) is displayed.

env = Environment(ASPPCOMSTR = "Assembling $TARGET")

ASPPFLAGS — general options when an assembling an assembly-language source file into an object file after first running the file through the C preprocessor. The default is to use the value of $ASFLAGS.
BIBTEX — the bibliography generator for the TeX formatter and typesetter and the LaTeX structured formatter and typesetter.
BIBTEXCOM — the command line used to call the bibliography generator for the TeX formatter and typesetter and the LaTeX structured formatter and typesetter.
BIBTEXCOMSTR — the string displayed when generating a bibliography for TeX or LaTeX. If this is not set, then $BIBTEXCOM (the command line) is displayed.

env = Environment(BIBTEXCOMSTR = "Generating bibliography $TARGET")

BIBTEXFLAGS — general options passed to the bibliography generator for the TeX formatter and typesetter and the LaTeX structured formatter and typesetter.
BUILDERS — a dictionary mapping the names of the builders available through the construction environment to underlying Builder objects. Custom builders need to be added to this to make them available.

A platform-dependent default list of builders such as Program, Library etc. is used to populate this construction variable when the construction environment is initialized via the presence/absence of the tools those builders depend on. $BUILDERS can be examined to learn which builders will actually be available at run-time. 👀

Note that if you initialize this construction variable through assignment when the construction environment is created, that value for $BUILDERS will override any defaults:

bld = Builder(action='foobuild < $SOURCE > $TARGET')
env = Environment(BUILDERS={'NewBuilder': bld})

To instead use a new Builder object in addition to the default Builders, add your new Builder object like this:

env = Environment()
env.Append(BUILDERS={'NewBuilder': bld})

or this:

env = Environment()
env['BUILDERS']['NewBuilder'] = bld

CACHEDIR_CLASS — the class type that SCons should use when instantiating a new CacheDir in this construction environment. Must be a subclass of the SCons.CacheDir.CacheDir class.
CC — the C compiler.

👑 `CCCOM`

The command line that compiles a C source file into a (static) object file. Everything you put in $CFLAGS, $CCFLAGS and $CPPFLAGS gets sprinkled onto this command line too, bestie. Want shared objects instead? Go look at $SHCCCOM 🦋

💅 `CCCOMSTR`

Set this and it's the string that gets shown when a C source file compiles to a (static) object file. Don't set it? Then $CCCOM (the whole command line) gets displayed instead. Compiling to shared objects? That's $SHCCCOMSTR ✨

env = Environment(CCCOMSTR = "Compiling static object $TARGET")

`CCDEPFLAGS`

Options you pass to the C or C++ compiler so it spits out a list of dependency files.

This one only gets set by compilers that actually support it, no cap. Currently that's gcc, clang, and msvc. 🙈

🌸 `CCFLAGS`

General options passed to the C and C++ compilers. Compiling to shared objects? Peep $SHCCFLAGS 💜

`CCPCHFLAGS`

Options tacked onto the compiler command line so precompiled headers work. The default value expands to the right Microsoft Visual C++ command-line options when the $PCH construction variable is set. (Yes, the original says "expands expands" — iconic typo, we keep it 💀)

🎀 `CCPDBFLAGS`

Options added to the compiler command line to support storing debugging info in a Microsoft Visual C++ PDB file. Default value expands to the right Microsoft Visual C++ command-line options when the $PDB construction variable is set.

The Microsoft Visual C++ compiler option SCons uses by default to generate PDB info is /Z7. Why is that the moment? Because it plays nice with parallel (-j) builds — it embeds the debug info right in the intermediate object files instead of sharing one single PDB file across a bunch of object files. It's also literally the only way to get debug info embedded into a static library. If you use /Zi instead you may get better link-time performance, but parallel builds will no longer work. So. Choose wisely 🫶

You can generate PDB files with the /Zi switch by overriding the default $CCPDBFLAGS variable like this:

env['CCPDBFLAGS'] = ['${(PDB and "/Zi /Fd%s" % File(PDB)) or ""}']

Or, alternative vibe: use /Zi to put the debugging information in a separate .pdb file for each object file by overriding $CCPDBFLAGS like this:

env['CCPDBFLAGS'] = '/Zi /Fd${TARGET}.pdb'

`CCVERSION`

The version number of the C compiler. May or may not be set, depending on which specific C compiler you're using. It's giving "we'll see" 😌

`CFILESUFFIX`

The suffix for C source files. The internal CFile builder uses this when it generates C files from Lex (.l) or YACC (.y) input files. The default suffix is, of course, .c (lower case, we're not shouting). On case-insensitive systems (like Windows), SCons also treats .C (upper case) files as C files. 🌈

`CFLAGS`

General options passed to the C compiler (C only, not C++, okay bestie, read the fine print). Compiling to shared objects? $SHCFLAGS is right there 💖

⭐ `CHANGE_SPECFILE`

A hook for modifying the file that controls the packaging build — that's the .spec for RPM, the control for Ipkg, and the .wxs for MSI. If you set it, the function gets called after the SCons template for that file has been written.

See the Package builder. 🍓

🚫 `CHANGED_SOURCES`

A reserved variable name that may not be set or used in a construction environment. Not up for negotiation. (See the manpage section "Variable Substitution" for more info.)

🚫 `CHANGED_TARGETS`

Also a reserved variable name that may not be set or used in a construction environment. Same energy. (See the manpage section "Variable Substitution" for more info.)

`CHANGELOG`

The name of a file containing the changelog text you want included in the package. It goes in as the %changelog section of the RPM .spec file.

See the Package builder. 📦

`COMPILATIONDB_COMSTR`

The string displayed when the CompilationDatabase builder's action runs. That's it, that's the whole vibe. ✨

`COMPILATIONDB_PATH_FILTER`

A string that tells CompilationDatabase to only include entries where the output member matches the pattern in the filter string — using fnmatch, which means glob-style wildcards. 🦋

Default value is an empty string '', which disables filtering (aka let it all in).

`COMPILATIONDB_USE_ABSPATH`

A boolean flag telling CompilationDatabase whether to write the file and output members in the compilation database using absolute or relative paths.

Default is False (so: relative paths). Periodt. 👑

`_concat`

A function used to produce variables like $_CPPINCFLAGS. It takes four mandatory arguments, plus up to 4 additional optional ones:

a prefix to concatenate onto each element
a list of elements
a suffix to concatenate onto each element
an environment for variable interpolation
(optional) a function that will be called to transform the list before concatenation
(optional) a target (you can use TARGET)
(optional) a source (you can use SOURCE)
(optional) an affect_signature flag, which wraps a non-empty returned value with $( and $) to indicate the contents should not affect the signature of the generated command line

env['_CPPINCFLAGS'] = '${_concat(INCPREFIX, CPPPATH, INCSUFFIX, __env__, RDirs, TARGET, SOURCE, affect_signature=False)}'

🌟 `CONFIGUREDIR`

The name of the directory where Configure context test files get written. Default is .sconf_temp, sitting in the top-level directory that contains the SConstruct file.

Using variant directories and don't want your configure check results shared between variants? Then set $CONFIGUREDIR and $CONFIGURELOG so they're unique per variant directory. iykyk 💅

`CONFIGURELOG`

The name of the Configure context log file. Default is config.log, in the top-level directory containing the SConstruct file.

Same deal as above — if variant directories are in use and you don't want the configure check results shared between variants, set $CONFIGUREDIR and $CONFIGURELOG so they're unique per variant directory. 🎀

`_CPPDEFFLAGS`

An automatically-generated construction variable holding the C preprocessor command-line options that define values. The value of $_CPPDEFFLAGS is made by prepending $CPPDEFPREFIX and appending $CPPDEFSUFFIX to each definition in $CPPDEFINES. Automatic queen behavior ✨

💜 `CPPDEFINES`

A platform-independent way to specify C preprocessor macro definitions. The definitions get added to command lines through the automatically-generated $_CPPDEFFLAGS construction variable, which is built according to whatever's inside $CPPDEFINES:

If $CPPDEFINES is a string, the values of the $CPPDEFPREFIX and $CPPDEFSUFFIX construction variables get prepended and appended to each definition in $CPPDEFINES, split on whitespace.

# Adds -Dxyz to POSIX compiler command lines,
# and /Dxyz to Microsoft Visual C++ command lines.
env = Environment(CPPDEFINES='xyz')

If $CPPDEFINES is a list, the values of $CPPDEFPREFIX and $CPPDEFSUFFIX get prepended and appended to each element in the list. If any element is a tuple (or list), then the first item of that tuple is the macro name and the second is the macro definition. If the definition isn't omitted or None, the name and definition get combined into a single name=definition item before the prepending/appending.

# Adds -DB=2 -DA to POSIX compiler command lines,
# and /DB=2 /DA to Microsoft Visual C++ command lines.
env = Environment(CPPDEFINES=[('B', 2), 'A'])

If $CPPDEFINES is a dictionary, the values of $CPPDEFPREFIX and $CPPDEFSUFFIX get prepended and appended to each key from the dictionary. If the value for a key isn't None, then the key (macro name) and the value (macro definition) get combined into a single name=definition item before the prepending/appending.

# Adds -DA -DB=2 to POSIX compiler command lines,
# or /DA /DB=2 to Microsoft Visual C++ command lines.
env = Environment(CPPDEFINES={'B':2, 'A':None})

Depending on how contents get added to $CPPDEFINES, it may be transformed into a compound type — like a list containing strings, tuples and/or dictionaries. SCons can correctly expand that compound type, no stress 💖

Heads up bestie: SCons may call the compiler via a shell. If a macro definition contains characters such as spaces that mean something to the shell, or is intended to be a string value, you may need to use the shell's quoting syntax so the shell doesn't interpret it before the preprocessor even sees it. Function-like macros are not supported via this mechanism (and some compilers don't even implement that functionality via the command lines). When quoting: remember one set of quote characters is used to define a Python string, and then quotes embedded inside that would get eaten by the shell unless escaped. These examples may help illustrate:

env = Environment(CPPDEFINES=['USE_ALT_HEADER=\\"foo_alt.h\\"'])
env = Environment(CPPDEFINES=[('USE_ALT_HEADER', '\\"foo_alt.h\\"')])

:Changed in version 4.5: SCons no longer sorts $CPPDEFINES values entered in dictionary form. Python now preserves dictionary keys in the order they're entered, so it's no longer necessary to sort them to ensure a stable command line. Slay 🎉

`CPPDEFPREFIX`

The prefix used to specify preprocessor macro definitions on the C compiler command line. Gets prepended to each definition in the $CPPDEFINES construction variable when the $_CPPDEFFLAGS variable is automatically generated. 🌸

`CPPDEFSUFFIX`

The suffix used to specify preprocessor macro definitions on the C compiler command line. Gets appended to each definition in the $CPPDEFINES construction variable when the $_CPPDEFFLAGS variable is automatically generated. 💅

CPPFLAGS — the C preprocessor options you specify, bestie. These get sprinkled into literally any command that touches the C preprocessor, which is a lot more than you'd think: not just the C and C++ source compiles via $CCCOM, $SHCCCOM, $CXXCOM and $SHCXXCOM, but also $FORTRANPPCOM, $SHFORTRANPPCOM, $F77PPCOM and $SHF77PPCOM (the Fortran compile lines), and $ASPPCOM, the assembly line — all of those after each file gets run through the C preprocessor first. Heads up bestie: this variable does not hold the -I (or similar) include-search-path options that scons auto-generates from $CPPPATH. Scroll down to $_CPPINCFLAGS for the variable that expands into those. 💖
_CPPINCFLAGS — the ✨automatically-generated✨ construction variable holding the C preprocessor command-line options that say which directories to search for includes. $_CPPINCFLAGS gets built by prepending $INCPREFIX and appending $INCSUFFIX to every single directory in $CPPPATH. She does the math so you don't have to. 🎀
CPPPATH — the list of directories the C preprocessor searches for include directories. The C/C++ implicit dependency scanner also searches these for include files. And ngl, hard advice incoming: it's generally not advised to shove include directory directives straight into $CCFLAGS or $CXXFLAGS, because (a) the result is non-portable and (b) the dependency scanner won't search those directories. $CPPPATH should be a list of path strings, or a single string — not a pathname list joined by the Python os.pathsep character. K?

Note that directory names in $CPPPATH get looked up relative to the directory of the SConscript file when they're used in a command. Wanna force scons to look up a directory relative to the root of the source tree instead? Use the # prefix:

env = Environment(CPPPATH='#/include')

You can also force that lookup with the Dir function:

include = Dir('include')
env = Environment(CPPPATH=include)

The directory list lands on command lines through the automatically-generated $_CPPINCFLAGS construction variable, which is built by prepending and appending the values of the $INCPREFIX and $INCSUFFIX construction variables to each directory in $CPPPATH. Any command line you define that needs the $CPPPATH directory list should include $_CPPINCFLAGS:

env = Environment(CCCOM="my_compiler $_CPPINCFLAGS -c -o $TARGET $SOURCE")

CPPSUFFIXES — the list of suffixes of files that get scanned for C preprocessor implicit dependencies (the #include lines, iykyk). The default list is:

[".c", ".C", ".cxx", ".cpp", ".c++", ".cc",
 ".h", ".H", ".hxx", ".hpp", ".hh",
 ".F", ".fpp", ".FPP",
 ".m", ".mm",
 ".S", ".spp", ".SPP"]

CXX — the C++ compiler. See also $SHCXX for compiling to shared objects. 👑
CXXCOM — the command line used to compile a C++ source file to an object file. Anything you put in $CXXFLAGS and $CPPFLAGS rides along on this command line. See also $SHCXXCOM for compiling to shared objects.
CXXCOMSTR — if you set it, this is the string displayed when a C++ source file compiles to a (static) object file. If you don't set it, then $CXXCOM (the actual command line) gets displayed instead. See also $SHCXXCOMSTR for compiling to shared objects.

env = Environment(CXXCOMSTR = "Compiling static object $TARGET")

CXXFILESUFFIX — the suffix for C++ source files. The internal CXXFile builder uses this when generating C++ files from Lex (.ll) or YACC (.yy) input files. Default suffix is .cc. SCons also treats files with the suffixes .cpp, .cxx, .c++, and .C++ as C++ files, and files with .mm suffixes as Objective-C++ files. On case-sensitive systems (Linux, UNIX, and other POSIX-alikes), SCons also treats .C (upper case) files as C++ files. Case sensitivity said "it's giving chaos" but we move. 🦋
CXXFLAGS — general options passed to the C++ compiler. By default this includes the value of $CCFLAGS, so setting $CCFLAGS hits both C and C++ compilation. Want C++-specific flags only? You gotta set or override the value of $CXXFLAGS yourself. See also $SHCXXFLAGS for compiling to shared objects.
CXXVERSION — the version number of the C++ compiler. This may or may not be set, depending on the specific C++ compiler being used. She's mysterious like that. 🙈
DC — the D compiler to use. SCons ships tool modules for three D compilation systems: DMD (dmd), the reference compiler; LDC (ldc), the LLVM-based D compiler; and GDC (gdc), from the GNU Compiler Collection — searched in that order. Need to prefer a specific compiler? Use a tool specifier. See also $SHDC for compiling to shared objects.
DCOM — the command line used to compile a D file to an object file. Any options you specify in the $DFLAGS construction variable get included on this command line. See also $SHDCOM for compiling to shared objects. And see also the ProgramAllAtOnce builder for how to compile directly to an executable without making intermediate object files. ⭐
DCOMSTR — if set, the string displayed when a D source file compiles to an object file. If not set, then $DCOM (the command line) is displayed. See also $SHDCOMSTR for compiling to shared objects.
DDEBUG — debug tags to enable when compiling.
DDEBUGPREFIX — prefix used for debug tags from $DDEBUG. Defaults vary by D compiler.
DDEBUGSUFFIX — suffix used for debug tags from $DDEBUG.
DESCRIPTION — a long description of the project being packaged. This gets included in the relevant section of the file that controls the packaging build. See the Package builder.
DESCRIPTION_lang — a language-specific long description for the specified lang. This is used to populate a %description -l section of an RPM .spec file. See the Package builder. 🌈
DFILESUFFIX — file suffix for D source files. Default is .d.
DFLAGPREFIX — prefix added to each element of $DFLAGS.
DFLAGS — general options that are passed to the D compiler.
DFLAGSUFFIX — suffix added to each element of $DFLAGS.
DI_FILE_DIR — path to search for D interface files, which are translations of C header files.
DI_FILE_DIR_PREFIX — prefix added to the name of the D interface file directory from $DI_FILE_DIR.
DI_FILE_DIR_SUFFFIX — suffix added to the name of the D interface file directory from $DI_FILE_DIR. (Yes, that's really how it's spelled — three F's, no cap, she's an icon. 👑)
DI_FILE_SUFFIX — suffix for D interface files, which are translations of C header files. Default is .di.
DINCPREFIX — prefix added to each path in $DPATH.
DINCSUFFIX — suffix added to each path in $DPATH.
Dir — a function that converts a string into a Dir instance relative to the target being built.
Dirs — a function that converts a list of strings into a list of Dir instances relative to the target being built. (Plural, obvs. 💅)
DLIB — name of the static library tool for D code.
DLIBCOM — the command line to use when linking a static library.
DLIBDIRPREFIX — the command-line prefix for library search directories from $LIBPATH when linking D code.
DLIBDIRSUFFIX — the command-line suffix for library search directories from $LIBPATH when linking D code.
DLIBFLAGPREFIX — prefix added to each element of $DLIBFLAGS.
DLIBFLAGS — the flags to pass to the library tool.
DLIBFLAGSUFFIX — suffix added to each element of $DLIBFLAGS.
DLIBLINKPREFIX — prefix added to each library name from $LIBS.
DLIBLINKSUFFIX — suffix added to each library name from $LIBS.
DLINK — name of the linker to use for linking systems including D sources. See also $SHDLINK for linking shared objects.
DLINKCOM — the command line to use when linking systems including D sources. See also $SHDLINKCOM for linking shared objects.
DLINKFLAGPREFIX — prefix added to each element of $DLINKFLAGS.
DLINKFLAGS — linker flags. See also $SHDLINKFLAGS for linking shared objects.
DLINKFLAGSUFFIX — suffix added to each element of $DLINKFLAGS.
DOCBOOK_DEFAULT_XSL_EPUB — the default XSLT file for the DocbookEpub builder within the current environment, if no other XSLT gets specified via keyword. 📚
DOCBOOK_DEFAULT_XSL_HTML — the default XSLT file for the DocbookHtml builder within the current environment, if no other XSLT gets specified via keyword.
DOCBOOK_DEFAULT_XSL_HTMLCHUNKED — the default XSLT file for the DocbookHtmlChunked builder within the current environment, if no other XSLT gets specified via keyword.
DOCBOOK_DEFAULT_XSL_HTMLHELP — the default XSLT file for the DocbookHtmlhelp builder within the current environment, if no other XSLT gets specified via keyword.
DOCBOOK_DEFAULT_XSL_MAN — the default XSLT file for the DocbookMan builder within the current environment, if no other XSLT gets specified via keyword.
DOCBOOK_DEFAULT_XSL_PDF — the default XSLT file for the DocbookPdf builder within the current environment, if no other XSLT gets specified via keyword.
DOCBOOK_DEFAULT_XSL_SLIDESHTML — the default XSLT file for the DocbookSlidesHtml builder within the current environment, if no other XSLT gets specified via keyword.
DOCBOOK_DEFAULT_XSL_SLIDESPDF — the default XSLT file for the DocbookSlidesPdf builder within the current environment, if no other XSLT gets specified via keyword.
DOCBOOK_FOP — the path to the PDF renderer fop or xep, if one of them is installed. And plot twist: fop gets checked first. 🫶
DOCBOOK_FOPCOM — the full command-line for the PDF renderer fop or xep.
DOCBOOK_FOPCOMSTR — the string displayed when a renderer like fop or xep is used to create PDF output from an XML file.
DOCBOOK_FOPFLAGS — additional command-line flags for the PDF renderer fop or xep.
DOCBOOK_XMLLINT — the path to the external executable xmllint, if it's installed. Careful bestie: this is only used as a last fallback for resolving XIncludes, if no lxml Python binding can be imported in the current system. 🧚
DOCBOOK_XMLLINTCOM — the full command-line for the external executable xmllint.
DOCBOOK_XMLLINTCOMSTR — the string displayed when xmllint is used to resolve XIncludes for a given XML file.
DOCBOOK_XMLLINTFLAGS — additional command-line flags for the external executable xmllint. ✨
DOCBOOK_XSLTPROC — the path to the external executable xsltproc (or saxon, xalan), assuming one of them is even installed on your machine. Heads up bestie: this only kicks in as the last fallback for XSL transformations, i.e. only if no lxml Python binding can be imported in the current system. So it's the backup-backup, the emergency outfit in the back of the closet. 💅
DOCBOOK_XSLTPROCCOM — the full command-line for that external executable xsltproc (or saxon, xalan). The whole thing, spelled out.
DOCBOOK_XSLTPROCCOMSTR — the string that gets displayed when xsltproc is used to transform an XML file via a given XSLT stylesheet. It's the ✨pretty face✨ of the command.
DOCBOOK_XSLTPROCFLAGS — extra command-line flags for the external executable xsltproc (or saxon, xalan). Season to taste.
DOCBOOK_XSLTPROCPARAMS — extra parameters that are not meant for the XSLT processor executable itself, but for the XSL processing. Genuinely a different thing, do not confuse them. By default, they get appended at the end of the command line for saxon and saxon-xslt, respectively.
DPATH — list of paths to search for import modules.
DRPATHPREFIX — the prefix added to rpath entries when generating shared objects.
DRPATHSUFFIX — the suffix added to rpath entries when generating shared objects.
DSUFFIXES — the list of suffixes of files that will be scanned for imported D package files. The default list is ['.d']. That's it, that's the list, she's minimal and she's thriving.
DVERPREFIX — prefix added to each element of $DVERSIONS.
DVERSIONS — list of version tags to enable when compiling. Enabling tags, one by one, like turning on lights in a house. 🏠
DVERSUFFIX — suffix added to each element of $DVERSIONS.
DVIPDF — the TeX DVI file to PDF file converter. Glow-up pipeline: DVI in, PDF out. 💖
DVIPDFCOM — the command line used to convert TeX DVI files into a PDF file.
DVIPDFCOMSTR — the string displayed when a TeX DVI file is converted into a PDF file. If this is not set, then $DVIPDFCOM (the command line) is displayed. So either you decorate the message or you get the raw command, no in-between, no third option.
DVIPDFFLAGS — general options passed to the TeX DVI file to PDF file converter.
DVIPS — the TeX DVI file to PostScript converter. Same energy, different destination.
DVIPSFLAGS — general options passed to the TeX DVI file to PostScript converter.
ENV — the execution environment: a dictionary of environment variables used when SCons invokes external commands to build targets defined in this construction environment. When $ENV gets passed to a command, every list value is assumed to be a path list and gets joined using the search path separator. Any other non-string values get coerced to a string. No stragglers allowed. 🫶

Note that by default SCons does not propagate the environment in effect when you execute scons (the "shell environment") to the execution environment. Why? So that builds are guaranteed repeatable no matter what environment variables were set at the time scons was invoked. That's the whole point. So if you want a shell environment variable to reach the commands executed to build target files, you have to do it explicitly, yourself, with your own two hands.

A common example is the system PATH environment variable, so that scons will find utilities the same way as the invoking shell (or other process):

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

Although it is usually not recommended, you can propagate the entire shell environment in one go:

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

Not recommended, bestie. It's giving "I set up reproducibility once and then never again." Do it explicitly. 🚫

ESCAPE — a function that will be called to escape shell special characters in command lines. The function should take one argument: the command line string to escape; and it should return the escaped command line. One in, one out, character-for-character honest work. ✨
F03 — the Fortran 03 compiler. You should normally set the $FORTRAN variable, which specifies the default Fortran compiler for all Fortran versions. You only need to set $F03 if you need to use a specific compiler or compiler version for Fortran 03 files. Don't be out here setting $F03 for fun, okay?
F03COM — the command line used to compile a Fortran 03 source file to an object file. You only need to set $F03COM if you need to use a specific command line for Fortran 03 files. You should normally set the $FORTRANCOM variable, which specifies the default command line for all Fortran versions.
F03COMSTR — if set, the string displayed when a Fortran 03 source file is compiled to an object file. If not set, then $F03COM or $FORTRANCOM (the command line) is displayed.
F03FILESUFFIXES — the list of file extensions for which the F03 dialect will be used. By default, this is ['.f03'].
F03FLAGS — general user-specified options that are passed to the Fortran 03 compiler. Note that this variable does not contain -I (or similar) include search path options that scons generates automatically from $F03PATH. See $_F03INCFLAGS below for the variable that expands to those options. You only need to set $F03FLAGS if you need to define specific user options for Fortran 03 files. You should normally set the $FORTRANFLAGS variable, which specifies the user-specified options passed to the default Fortran compiler for all Fortran versions.
_F03INCFLAGS — an automatically-generated construction variable containing the Fortran 03 compiler command-line options for specifying directories to be searched for include files. The value of $_F03INCFLAGS is created by appending $INCPREFIX and $INCSUFFIX to the beginning and the end of each directory in $F03PATH. She builds herself. Iconic. 👑
F03PATH — the list of directories that the Fortran 03 compiler will search for include directories. The implicit dependency scanner will search these directories for include files. Don't explicitly put include directory arguments in $F03FLAGS, because the result will be non-portable and the directories won't be searched by the dependency scanner. Two Ls in one move, we don't. 😭

Note: directory names in $F03PATH are looked-up relative to the SConscript directory when they are used in a command. To force scons to look up a directory relative to the root of the source tree, use #:

You only need to set $F03PATH if you need to define a specific include path for Fortran 03 files. You should normally set the $FORTRANPATH variable, which specifies the include path for the default Fortran compiler for all Fortran versions.

env = Environment(F03PATH='#/include')

The directory lookup can also be forced using the Dir() function:

include = Dir('include')
env = Environment(F03PATH=include)

The directory list gets added to command lines through the automatically-generated $_F03INCFLAGS construction variable, which is constructed by appending the values of the $INCPREFIX and $INCSUFFIX construction variables to the beginning and the end of each directory in $F03PATH. Any command lines you define that need the F03PATH directory list should include $_F03INCFLAGS:

env = Environment(F03COM="my_compiler $_F03INCFLAGS -c -o $TARGET $SOURCE")

F03PPCOM — the command line used to compile a Fortran 03 source file to an object file after first running the file through the C preprocessor. Any options specified in the $F03FLAGS and $CPPFLAGS construction variables are included on this command line. You only need to set $F03PPCOM if you need to use a specific C-preprocessor command line for Fortran 03 files. You should normally set the $FORTRANPPCOM variable, which specifies the default C-preprocessor command line for all Fortran versions.
F03PPCOMSTR — if set, the string displayed when a Fortran 03 source file is compiled to an object file after first running the file through the C preprocessor. If not set, then $F03PPCOM or $FORTRANPPCOM (the command line) is displayed.
F03PPFILESUFFIXES — the list of file extensions for which the compilation + preprocessor pass for the F03 dialect will be used. By default, this is empty. Yes, empty. The void. She's giving nothing and that's on purpose. 💀
F08 — the Fortran 08 compiler. You should normally set the $FORTRAN variable, which specifies the default Fortran compiler for all Fortran versions. You only need to set $F08 if you need to use a specific compiler or compiler version for Fortran 08 files. (Yes, it's the same speech as F03. The rules don't change just because the year did. 📅)
F08COM — the command line used to compile a Fortran 08 source file to an object file. You only need to set $F08COM if you need to use a specific command line for Fortran 08 files. You should normally set the $FORTRANCOM variable, which specifies the default command line for all Fortran versions.
F08COMSTR — if set, the string displayed when a Fortran 08 source file is compiled to an object file. If not set, then $F08COM or $FORTRANCOM (the command line) is displayed.
F08FILESUFFIXES — the list of file extensions for which the F08 dialect will be used. By default, this is ['.f08'].
F08FLAGS — general user-specified options that are passed to the Fortran 08 compiler. Note that this variable does not contain -I (or similar) include search path options that scons generates automatically from $F08PATH. See $_F08INCFLAGS below for the variable that expands to those options. You only need to set $F08FLAGS if you need to define specific user options for Fortran 08 files. You should normally set the $FORTRANFLAGS variable, which specifies the user-specified options passed to the default Fortran compiler for all Fortran versions.
_F08INCFLAGS — an automatically-generated construction variable containing the Fortran 08 compiler command-line options for specifying directories to be searched for include files. The value of $_F08INCFLAGS is created by appending $INCPREFIX and $INCSUFFIX to the beginning and the end of each directory in $F08PATH. Autogenerated and unbothered. ✨
F08PATH — the list of directories that the Fortran 08 compiler will search for include directories. The implicit dependency scanner will search these directories for include files. Don't explicitly put include directory arguments in $F08FLAGS, because the result will be non-portable and the directories won't be searched by the dependency scanner. Note: directory names in $F08PATH are looked-up relative to the SConscript directory when they are used in a command. To force scons to look up a directory relative to the root of the source tree, use #:

You only need to set $F08PATH if you need to define a specific include path for Fortran 08 files. You should normally set the $FORTRANPATH variable, which specifies the include path for the default Fortran compiler for all Fortran versions.

env = Environment(F08PATH='#/include')

The directory lookup can also be forced using the Dir() function:

include = Dir('include')
env = Environment(F08PATH=include)

The directory list gets bolted onto command lines through the auto-magically generated $_F08INCFLAGS construction variable 💫 — it's built by gluing the values of $INCPREFIX and $INCSUFFIX onto the front and back of every single directory in $F08PATH. So any command lines you write yourself that need that F08PATH directory list? Gotta include $_F08INCFLAGS, bestie:

env = Environment(F08COM="my_compiler $_F08INCFLAGS -c -o $TARGET $SOURCE")

`F08PPCOM` 🛠️

The command line used to compile a Fortran 08 source file into an object file, but only after the file first gets run through the C preprocessor. Any options you specified in the $F08FLAGS and $CPPFLAGS construction variables get included on this command line too. You only need to set $F08PPCOM if you need a specific C-preprocessor command line for Fortran 08 files specifically — normally you'd set the $FORTRANPPCOM variable instead, since that one specifies the default C-preprocessor command line for all Fortran versions. ✨

`F08PPCOMSTR` 💬

If you set this, it's the string displayed when a Fortran 08 source file gets compiled to an object file after first running the file through the C preprocessor. If you don't set it, then $F08PPCOM or $FORTRANPPCOM (aka the command line itself) is what gets displayed.

`F08PPFILESUFFIXES` 📁

The list of file extensions for which the compile + preprocessor pass for the F08 dialect will be used. By default, this is empty.

`F77` 👑

The Fortran 77 compiler. You should normally set the $FORTRAN variable, which specifies the default Fortran compiler for all Fortran versions. You only need to set $F77 if you need a specific compiler or compiler version just for Fortran 77 files.

`F77COM` 🛠️

The command line used to compile a Fortran 77 source file to an object file. You only need to set $F77COM if you need a specific command line for Fortran 77 files. You should normally set the $FORTRANCOM variable, which specifies the default command line for all Fortran versions.

`F77COMSTR` 💬

If set, the string displayed when a Fortran 77 source file is compiled to an object file. If not set, then $F77COM or $FORTRANCOM (the command line) is displayed.

`F77FILESUFFIXES` 📁

The list of file extensions for which the F77 dialect will be used. By default, this is ['.f77']

`F77FLAGS` 🚩

General user-specified options that get passed to the Fortran 77 compiler. Heads up: this variable does not contain -I (or similar) include search path options — scons generates those automatically from $F77PATH. Peep $_F77INCFLAGS below for the variable that expands to those options. You only need to set $F77FLAGS if you need to define specific user options for Fortran 77 files. You should normally set the $FORTRANFLAGS variable, which specifies the user-specified options passed to the default Fortran compiler for all Fortran versions.

`_F77INCFLAGS` 💫

An automatically-generated construction variable containing the Fortran 77 compiler command-line options for specifying directories to be searched for include files. The value of $_F77INCFLAGS is created by appending $INCPREFIX and $INCSUFFIX to the beginning and end of each directory in $F77PATH.

`F77PATH` 🔍

The list of directories that the Fortran 77 compiler will search for include directories. The implicit dependency scanner will search these directories for include files. Do not explicitly put include directory arguments in $F77FLAGS — the result will be non-portable and the directories won't be searched by the dependency scanner. 📢

Note: directory names in $F77PATH get looked-up relative to the SConscript directory when they're used in a command. To force scons to look up a directory relative to the root of the source tree, use #: You only need to set $F77PATH if you need to define a specific include path for Fortran 77 files. You should normally set the $FORTRANPATH variable, which specifies the include path for the default Fortran compiler for all Fortran versions.

env = Environment(F77PATH='#/include')

The directory lookup can also be forced using the Dir() function:

include = Dir('include')
env = Environment(F77PATH=include)

The directory list gets added to command lines through the automatically-generated $_F77INCFLAGS construction variable, which is constructed by appending the values of the $INCPREFIX and $INCSUFFIX construction variables to the beginning and end of each directory in $F77PATH. Any command lines you define that need the F77PATH directory list should include $_F77INCFLAGS:

env = Environment(F77COM="my_compiler $_F77INCFLAGS -c -o $TARGET $SOURCE")

`F77PPCOM` 🛠️

The command line used to compile a Fortran 77 source file to an object file after first running the file through the C preprocessor. Any options specified in the $F77FLAGS and $CPPFLAGS construction variables are included on this command line. You only need to set $F77PPCOM if you need to use a specific C-preprocessor command line for Fortran 77 files. You should normally set the $FORTRANPPCOM variable, which specifies the default C-preprocessor command line for all Fortran versions.

`F77PPCOMSTR` 💬

If set, the string displayed when a Fortran 77 source file is compiled to an object file after first running the file through the C preprocessor. If not set, then $F77PPCOM or $FORTRANPPCOM (the command line) is displayed.

`F77PPFILESUFFIXES` 📁

The list of file extensions for which the compilation + preprocessor pass for the F77 dialect will be used. By default, this is empty.

`F90` 👑

The Fortran 90 compiler. You should normally set the $FORTRAN variable, which specifies the default Fortran compiler for all Fortran versions. You only need to set $F90 if you need to use a specific compiler or compiler version for Fortran 90 files.

`F90COM` 🛠️

The command line used to compile a Fortran 90 source file to an object file. You only need to set $F90COM if you need to use a specific command line for Fortran 90 files. You should normally set the $FORTRANCOM variable, which specifies the default command line for all Fortran versions.

`F90COMSTR` 💬

If set, the string displayed when a Fortran 90 source file is compiled to an object file. If not set, then $F90COM or $FORTRANCOM (the command line) is displayed.

`F90FILESUFFIXES` 📁

The list of file extensions for which the F90 dialect will be used. By default, this is ['.f90']

`F90FLAGS` 🚩

General user-specified options that are passed to the Fortran 90 compiler. Note that this variable does not contain -I (or similar) include search path options that scons generates automatically from $F90PATH. See $_F90INCFLAGS below for the variable that expands to those options. You only need to set $F90FLAGS if you need to define specific user options for Fortran 90 files. You should normally set the $FORTRANFLAGS variable, which specifies the user-specified options passed to the default Fortran compiler for all Fortran versions.

`_F90INCFLAGS` 💫

An automatically-generated construction variable containing the Fortran 90 compiler command-line options for specifying directories to be searched for include files. The value of $_F90INCFLAGS is created by appending $INCPREFIX and $INCSUFFIX to the beginning and end of each directory in $F90PATH.

`F90PATH` 🔍

The list of directories that the Fortran 90 compiler will search for include directories. The implicit dependency scanner will search these directories for include files. Don't explicitly put include directory arguments in $F90FLAGS — the result will be non-portable and the directories won't be searched by the dependency scanner. Note: directory names in $F90PATH will be looked-up relative to the SConscript directory when they are used in a command. To force scons to lookup a directory relative to the root of the source tree, use #: You only need to set $F90PATH if you need to define a specific include path for Fortran 90 files. You should normally set the $FORTRANPATH variable, which specifies the include path for the default Fortran compiler for all Fortran versions.

env = Environment(F90PATH='#/include')

The directory lookup can also be forced using the Dir() function:

include = Dir('include')
env = Environment(F90PATH=include)

The directory list will be added to command lines through the automatically-generated $_F90INCFLAGS construction variable, which is constructed by appending the values of the $INCPREFIX and $INCSUFFIX construction variables to the beginning and end of each directory in $F90PATH. Any command lines you define that need the F90PATH directory list should include $_F90INCFLAGS:

env = Environment(F90COM="my_compiler $_F90INCFLAGS -c -o $TARGET $SOURCE")

`F90PPCOM` 🛠️

The command line used to compile a Fortran 90 source file to an object file after first running the file through the C preprocessor. Any options specified in the $F90FLAGS and $CPPFLAGS construction variables are included on this command line. You only need to set $F90PPCOM if you need to use a specific C-preprocessor command line for Fortran 90 files. You should normally set the $FORTRANPPCOM variable, which specifies the default C-preprocessor command line for all Fortran versions.

`F90PPCOMSTR` 💬

If set, the string displayed when a Fortran 90 source file is compiled after first running the file through the C preprocessor. If not set, then $F90PPCOM or $FORTRANPPCOM (the command line) is displayed.

`F90PPFILESUFFIXES` 📁

The list of file extensions for which the compilation + preprocessor pass for the F90 dialect will be used. By default, this is empty.

`F95` 👑

The Fortran 95 compiler. You should normally set the $FORTRAN variable, which specifies the default Fortran compiler for all Fortran versions. You only need to set $F95 if you need to use a specific compiler or compiler version for Fortran 95 files.

`F95COM` 🛠️

The command line used to compile a Fortran 95 source file to an object file. You only need to set $F95COM if you need to use a specific command line for Fortran 95 files. You should normally set the $FORTRANCOM variable, which specifies the default command line for all Fortran versions.

`F95COMSTR`

If you set this, it's the string that gets shown when a Fortran 95 source file is compiled into an object file. Not set? Then $F95COM or $FORTRANCOM (aka the actual command line) gets displayed instead. no secrets here bestie 💅

`F95FILESUFFIXES`

The list of file extensions where the F95 dialect gets used. Default is ['.f95'] — that's the whole guest list, periodt.

`F95FLAGS`

General user-specified options that get passed straight to the Fortran 95 compiler. Heads up: this variable does not contain -I (or similar) include search path options — scons generates those automatically from $F95PATH. Peep $_F95INCFLAGS below for the variable that expands into those. You only need to set $F95FLAGS if you genuinely need specific user options for Fortran 95 files. Normally you'd set the $FORTRANFLAGS variable instead, which is the user-specified options passed to the default Fortran compiler for all Fortran versions. ✨

`_F95INCFLAGS`

An automatically-generated construction variable holding the Fortran 95 compiler command-line options for specifying directories to search for include files. The value of $_F95INCFLAGS is created by appending $INCPREFIX and $INCSUFFIX to the beginning and end of each directory in $F95PATH. it's giving auto-generated, not you-generated 🎀

`F95PATH`

The list of directories the Fortran 95 compiler searches for include directories. The implicit dependency scanner will search these directories for include files. Do not explicitly put include directory arguments in $F95FLAGS — the result will be non-portable and the directories won't be searched by the dependency scanner. 😭

Note: directory names in $F95PATH get looked-up relative to the SConscript directory when they're used in a command. To force scons to look up a directory relative to the root of the source tree, use #:

You only need to set $F95PATH if you need a specific include path for Fortran 95 files. Normally you'd set the $FORTRANPATH variable, which is the include path for the default Fortran compiler for all Fortran versions.

env = Environment(F95PATH='#/include')

The directory lookup can also be forced using the Dir() function:

include = Dir('include')
env = Environment(F95PATH=include)

The directory list gets added to command lines through the automatically-generated $_F95INCFLAGS construction variable, which is constructed by appending the values of the $INCPREFIX and $INCSUFFIX construction variables to the beginning and end of each directory in $F95PATH. Any command lines you define that need the F95PATH directory list should include $_F95INCFLAGS:

env = Environment(F95COM="my_compiler $_F95INCFLAGS -c -o $TARGET $SOURCE")

`F95PPCOM`

The command line used to compile a Fortran 95 source file to an object file after first running the file through the C preprocessor. Any options specified in the $F95FLAGS and $CPPFLAGS construction variables are included on this command line. You only need to set $F95PPCOM if you need a specific C-preprocessor command line for Fortran 95 files. Normally you'd set the $FORTRANPPCOM variable, which is the default C-preprocessor command line for all Fortran versions. 💖

`F95PPCOMSTR`

If you set this, it's the string shown when a Fortran 95 source file is compiled to an object file after first running the file through the C preprocessor. If it's not set, then $F95PPCOM or $FORTRANPPCOM (the command line) is displayed. 🌸

`F95PPFILESUFFIXES`

The list of file extensions for which the compilation + preprocessor pass for the F95 dialect gets used. By default, this is empty. literally an empty list, she said "no thank you" 🙈

`File`

A function that converts a string into a File instance relative to the target being built. short king of a function fr fr

`FILE_ENCODING`

File encoding used for files written by Textfile and Substfile. Set to "utf-8" by default. 💜

New in version 4.5.0.

`FORTRAN`

The default Fortran compiler for all versions of Fortran. the moment, the icon, the legend 👑

`FORTRANCOM`

The command line used to compile a Fortran source file to an object file. By default, any options specified in the $FORTRANFLAGS, $_FORTRANMODFLAG, and $_FORTRANINCFLAGS construction variables are included on this command line.

`FORTRANCOMMONFLAGS`

General user-specified options passed to the Fortran compiler. Similar to $FORTRANFLAGS, but this construction variable is applied to all dialects. she's everybody's friend 🫶

New in version 4.4.

`FORTRANCOMSTR`

If you set this, it's the string displayed when a Fortran source file is compiled to an object file. Not set? Then $FORTRANCOM (the command line) is displayed instead.

`FORTRANFILESUFFIXES`

The list of file extensions for which the FORTRAN dialect gets used. By default, this is ['.f', '.for', '.ftn'] — three whole suffixes, she ate ✨

`FORTRANFLAGS`

General user-specified options for the FORTRAN dialect that get passed to the Fortran compiler. Note that this variable does not contain -I (or similar) include or module search path options that scons generates automatically from $FORTRANPATH. See $_FORTRANINCFLAGS and $_FORTRANMODFLAG for the construction variables that expand those options. iykyk 💅

`_FORTRANINCFLAGS`

An automatically-generated construction variable containing the Fortran compiler command-line options for specifying directories to search for include files and module files. The value of $_FORTRANINCFLAGS is created by respectively prepending and appending $INCPREFIX and $INCSUFFIX to the beginning and end of each directory in $FORTRANPATH.

`FORTRANMODDIR`

Directory location where the Fortran compiler should place any module files it generates. This variable is empty by default. Some Fortran compilers will internally append this directory in the search path for module files as well. sneaky little extra behaviour, we love to see it 🌈

`FORTRANMODDIRPREFIX`

The prefix used to specify a module directory on the Fortran compiler command line. This gets prepended to the beginning of the directory in the $FORTRANMODDIR construction variable when the $_FORTRANMODFLAG variable is automatically generated.

`FORTRANMODDIRSUFFIX`

The suffix used to specify a module directory on the Fortran compiler command line. This gets appended to the end of the directory in the $FORTRANMODDIR construction variable when the $_FORTRANMODFLAG variable is automatically generated.

`_FORTRANMODFLAG`

An automatically-generated construction variable containing the Fortran compiler command-line option for specifying the directory location where the Fortran compiler should place any module files that happen to get generated during compilation. The value of $_FORTRANMODFLAG is created by respectively prepending and appending $FORTRANMODDIRPREFIX and $FORTRANMODDIRSUFFIX to the beginning and end of the directory in $FORTRANMODDIR. ✨

`FORTRANMODPREFIX`

The module file prefix used by the Fortran compiler. SCons assumes the Fortran compiler follows the quasi-standard naming convention for module files of module_name.mod. Because of that, this variable is left empty by default. For situations where the compiler doesn't necessarily follow the normal convention, you may use this variable. Its value gets appended to every module file name as scons attempts to resolve dependencies. 🦋

`FORTRANMODSUFFIX`

The module file suffix used by the Fortran compiler. SCons assumes the Fortran compiler follows the quasi-standard naming convention for module files of module_name.mod. Because of that, this variable is set to ".mod" by default. For situations where the compiler doesn't necessarily follow the normal convention, you may use this variable. Its value gets appended to every module file name as scons attempts to resolve dependencies. 🦋

`FORTRANPATH`

The list of directories the Fortran compiler searches for include files and (for some compilers) module files. The Fortran implicit dependency scanner searches these directories for include files (but not module files, since they're autogenerated and, as such, may not actually exist at the time the scan takes place). Don't explicitly put include directory arguments in FORTRANFLAGS — the result will be non-portable and the directories won't be searched by the dependency scanner. 😭

Note: directory names in FORTRANPATH get looked-up relative to the SConscript directory when they're used in a command. To force scons to look up a directory relative to the root of the source tree, use #:

env = Environment(FORTRANPATH='#/include')

The directory look-up can also be forced using the Dir() function:

include = Dir('include')
env = Environment(FORTRANPATH=include)

The directory list gets added to command lines through the automatically-generated $_FORTRANINCFLAGS construction variable, which is constructed by respectively prepending and appending the values of the $INCPREFIX and $INCSUFFIX construction variables to the beginning and end of each directory in $FORTRANPATH. Any command lines you define that need the FORTRANPATH directory list should include $_FORTRANINCFLAGS:

env = Environment(FORTRANCOM="my_compiler $_FORTRANINCFLAGS -c -o $TARGET $SOURCE")

`FORTRANPPCOM`

The command line used to compile a Fortran source file to an object file after first running the file through the C preprocessor. By default, any options specified in the $FORTRANFLAGS, $CPPFLAGS, $_CPPDEFFLAGS, $_FORTRANMODFLAG, and $_FORTRANINCFLAGS construction variables are included on this command line. that's a whole stack of flags and she's carrying all of them 💅

`FORTRANPPCOMSTR`

If you set this, it's the string displayed when a Fortran source file is compiled to an object file after first running the file through the C preprocessor. If not set, then $FORTRANPPCOM (the command line) is displayed. 🎀

`FORTRANPPFILESUFFIXES`

The list of file extensions for which the compilation + preprocessor pass for the FORTRAN dialect gets used. By default, this is ['.fpp', '.FPP'].

`FORTRANSUFFIXES`

The list of suffixes of files that get scanned for Fortran implicit dependencies (INCLUDE lines and USE statements). The default list is:

[".f", ".F", ".for", ".FOR", ".ftn", ".FTN", ".fpp", ".FPP",
".f77", ".F77", ".f90", ".F90", ".f95", ".F95"]

fourteen suffixes and not one of them is doing too much, we stan a thorough queen 👑

🌸 `FRAMEWORKPATH`

okay so on Mac OS X with gcc, this is a list holding all the paths to search for frameworks 💅. The compiler uses it to find framework-style includes like #include <Fmwk/Header.h>. The linker uses it to find user-specified frameworks when linking (peep $FRAMEWORKS bestie). Like, for example:

env.AppendUnique(FRAMEWORKPATH='#myframeworkdir')

will add

... -Fmyframeworkdir

to the compiler and linker command lines. no cap.

✨ `_FRAMEWORKPATH`

On Mac OS X with gcc, an automatically-generated construction variable holding the linker command-line options that correspond to $FRAMEWORKPATH. It's giving auto-magic 🪄.

`FRAMEWORKPATHPREFIX`

On Mac OS X with gcc, the prefix to be used for the FRAMEWORKPATH entries (see $FRAMEWORKPATH). The default value is -F. yes literally just -F 💀.

`FRAMEWORKPREFIX`

On Mac OS X with gcc, the prefix to be used for linking in frameworks (see $FRAMEWORKS). The default value is -framework. periodt.

`FRAMEWORKS`

On Mac OS X with gcc, a list of the framework names to be linked into a program or shared library or bundle. The default value is the empty list. for example:

env.AppendUnique(FRAMEWORKS=Split('System Cocoa SystemConfiguration'))

`_FRAMEWORKS`

On Mac OS X with gcc, an automatically-generated construction variable holding the linker command-line options for linking with FRAMEWORKS. she's generated, she's not your problem 🎀.

`FRAMEWORKSFLAGS`

On Mac OS X with gcc, general user-supplied frameworks options to be added at the end of a command line building a loadable module. (This has been largely superseded by the $FRAMEWORKPATH, $FRAMEWORKPATHPREFIX, $FRAMEWORKPREFIX and $FRAMEWORKS variables described above.) like... she's a legacy queen, respect her but maybe use the new ones 🫶.

`GS`

The Ghostscript program used to, for example, convert PostScript to PDF files.

`GSCOM`

The full Ghostscript command line used for the conversion process. Its default value is "$GS $GSFLAGS -sOutputFile=$TARGET $SOURCES".

`GSCOMSTR`

The string displayed when Ghostscript is called for the conversion process. If this is not set (the default), then $GSCOM (the command line) is displayed.

`GSFLAGS`

General options passed to the Ghostscript program, when converting PostScript to PDF files for example. Its default value is "-dNOPAUSE -dBATCH -sDEVICE=pdfwrite".

`HOST_ARCH`

The name of the host hardware architecture used to create this construction environment. The platform code sets this when initializing (see $PLATFORM and the platform argument to Environment). Note the detected name of the architecture may not be identical to that returned by the Python platform.machine method. 🙈

On the win32 platform, if the Microsoft Visual C++ compiler is available, msvc tool setup is done using $HOST_ARCH and $TARGET_ARCH. Changing the values at any later time will not cause the tool to be reinitialized. Valid host arch values are x86 and arm for 32-bit hosts and amd64, arm64, and x86_64 for 64-bit hosts.

Should be considered immutable. $HOST_ARCH is not currently used by other platforms, but the option is reserved to do so in future.

ok so bestie do NOT go changing this one mid-build, she's frozen for a reason 💀

`HOST_OS`

The name of the host operating system for the platform used to create this construction environment. The platform code sets this when initializing (see $PLATFORM and the platform argument to Environment).

Should be considered immutable. $HOST_OS is not currently used by SCons, but the option is reserved to do so in future. she's reserved, she's waiting for her moment ✨.

`IDLSUFFIXES`

The list of suffixes of files that will be scanned for IDL implicit dependencies (#include or import lines). The default list is:

[".idl", ".IDL"]

`IMPLIBNOVERSIONSYMLINKS`

Used to override $SHLIBNOVERSIONSYMLINKS/$LDMODULENOVERSIONSYMLINKS when creating versioned import library for a shared library/loadable module. If not defined, then $SHLIBNOVERSIONSYMLINKS/$LDMODULENOVERSIONSYMLINKS is used to determine whether to disable symlink generation or not. so she's the boss override, but only when she shows up 👑

`IMPLIBPREFIX`

The prefix used for import library names. For example, cygwin uses import libraries (libfoo.dll.a) in pair with dynamic libraries (cygfoo.dll). The cyglink linker sets $IMPLIBPREFIX to 'lib' and $SHLIBPREFIX to 'cyg'. it's giving cygwin lore 🌈.

`IMPLIBSUFFIX`

The suffix used for import library names. For example, cygwin uses import libraries (libfoo.dll.a) in pair with dynamic libraries (cygfoo.dll). The cyglink linker sets $IMPLIBSUFFIX to '.dll.a' and $SHLIBSUFFIX to '.dll'. see above, same cygwin energy 💜.

`IMPLIBVERSION`

Used to override $SHLIBVERSION/$LDMODULEVERSION when generating versioned import library for a shared library/loadable module. If undefined, the $SHLIBVERSION/$LDMODULEVERSION is used to determine the version of versioned import library. another override queen, iconic 💅.

`IMPLICIT_COMMAND_DEPENDENCIES`

okay this one's a whole main character, listen up. Controls how SCons adds implicit dependencies from action strings (the commands executed to build targets). These implicit dependencies allow SCons to trigger target rebuilds when the compilers, tools, or scripts that affect build outcomes change (for example, when a new version of a compiler is installed). By default, SCons adds an implicit dependency on the executable represented by the first argument of the command line. This executable is first checked as a path; if not found, it is searched for in the execution environment's search path (env['ENV']['PATH']). fr fr.

If $IMPLICIT_COMMAND_DEPENDENCIES is set to a falsy value ("none", "false", "no", "off", "0" or integer 0), no implicit dependencies from action strings are added. If set to an integer value greater than 1, or to "all", additional command-line arguments are checked. A numeric value N checks the first N arguments, while "all" checks every argument. A checked argument beyond the first is added as a dependency if it is an absolute path or it refers to an existing file in the filesystem; unlike the first argument, these additional arguments are not searched using the execution environment's search path. All other values of $IMPLICIT_COMMAND_DEPENDENCIES are treated the same as the default. The value of $IMPLICIT_COMMAND_DEPENDENCIES is subject to substitution before it is used, so it can contain a construction variable reference. 🦋

Action strings may be segmented with a logical AND operator (&&), indicating each segment is executed sequentially, but only if the previous segment succeeded. If $IMPLICIT_COMMAND_DEPENDENCIES is set to "all" or an integer greater than 1, each segment is treated as a separate command line for computing dependencies; otherwise, only the first segment is checked.

`INCPREFIX`

The prefix used to specify an include directory on the C compiler command line. This will be prepended to each directory in the $CPPPATH and $FORTRANPATH construction variables when the $_CPPINCFLAGS and $_FORTRANINCFLAGS variables are automatically generated. she's little but she does so much 🎀.

`INCSUFFIX`

The suffix used to specify an include directory on the C compiler command line. This will be appended to each directory in the $CPPPATH and $FORTRANPATH construction variables when the $_CPPINCFLAGS and $_FORTRANINCFLAGS variables are automatically generated.

`INSTALL`

A function to be called to install a file into a destination file name. The default function copies the file into the destination (and sets the destination file's mode and permission bits to match the source file's). The function takes the following arguments:

def install(dest, source, env):

dest is the path name of the destination file. source is the path name of the source file. env is the construction environment (a dictionary of construction values) in force for this file installation.

`INSTALLSTR`

The string displayed when a file is installed into a destination file name. The default is:

Install file: "$SOURCE" as "$TARGET"

cute, right? 💖

`INTEL_C_COMPILER_VERSION`

Set by the intelc Tool to the major version number of the Intel C compiler selected for use.

`JAR`

The Java archive tool.

`JARCHDIR`

The directory to which the Java archive tool should change (using the -C option).

`JARCOM`

The command line used to call the Java archive tool.

`JARCOMSTR`

The string displayed when the Java archive tool is called. If this is not set, then $JARCOM (the command line) is displayed.

env = Environment(JARCOMSTR="JARchiving $SOURCES into $TARGET")

`JARFLAGS`

General options passed to the Java archive tool. By default, this is set to cf to create the necessary jar file. cf bestie, that's the whole vibe ✨.

`JARSUFFIX`

The suffix for Java archives: .jar by default.

`JAVABOOTCLASSPATH`

Specifies the location of the bootstrap class files. Can be specified as a string or Node object, or as a list of strings or Node objects.

The value will be added to the JDK command lines via the -bootclasspath option, which requires a system-specific search path separator. This will be supplied by SCons as needed when it constructs the command line if $JAVABOOTCLASSPATH is provided in list form. If $JAVABOOTCLASSPATH is a single string containing search path separator characters (: for POSIX systems or ; for Windows), it will not be modified; and so is inherently system-specific; to supply the path in a system-independent manner, give $JAVABOOTCLASSPATH as a list of paths instead.

Note Can only be used when compiling for releases prior to JDK 9. so if you're on JDK 9 or later... she's not invited 😭

`JAVAC`

The Java compiler.

`JAVACCOM`

The command line used to compile a directory tree containing Java source files to corresponding Java class files. Any options specified in the $JAVACFLAGS construction variable are included on this command line.

`JAVACCOMSTR`

The string displayed when compiling a directory tree of Java source files to corresponding Java class files. If this is not set, then $JAVACCOM (the command line) is displayed.

env = Environment(JAVACCOMSTR="Compiling class files $TARGETS from $SOURCES")

`JAVACFLAGS`

General options that are passed to the Java compiler.

`JAVACLASSDIR`

The directory in which Java class files may be found. This is stripped from the beginning of any Java .class file names supplied to the JavaH builder. she's literally just here to trim the front off 💅.

`JAVACLASSPATH` 🔍

Tells the JDK tools where to go look for classes. You can hand it a string or a Node object, or a whole list of strings and/or Node objects — dealer's choice, bestie.

Class path entries can be all kinds of things: directory names you want searched for class files or packages, pathnames pointing at archives (.jar or .zip) that have classes in them, or paths that end in a "base name wildcard" character (*), which matches files in that directory that have a .jar suffix. Wanna know the deets? Go read the Java documentation, she's got you.

The value gets tacked onto the JDK command lines through the -classpath option, which — surprise — needs a system-specific search path separator. SCons will supply that separator as needed when it builds the command line, if $JAVACLASSPATH shows up in list form. But if $JAVACLASSPATH is a single string with search path separator characters in it (: for POSIX systems, or ; for Windows), SCons splits it on the separator into a list of individual paths for dependency-scanning purposes. It will not be modified for JDK command-line usage though, so a string like that is inherently system-specific 💀. Want the path in a system-independent way? Give $JAVACLASSPATH as a list of paths, periodt.

Note 🫶 SCons always supplies -sourcepath when it invokes the Java compiler javac, no matter what $JAVASOURCEPATH is set to — because it passes the path(s) to the source(s) supplied in the call to the Java builder via -sourcepath. Straight from the docs of the standard Java toolkit for javac: "If not compiling code for modules, if the --source-path or -sourcepath option is not specified, then the user class path is also searched for source files." But since -sourcepath is always supplied, javac will not go poking through the contents of $JAVACLASSPATH when it's hunting for sources. iykyk.

`JAVACLASSSUFFIX` 🎀

The suffix for Java class files. Defaults to .class.

`JAVAH` ✨

The Java generator for C header and stub files.

`JAVAHCOM` 💖

The command line used to generate C header and stub files from Java classes. Any options you put in the $JAVAHFLAGS construction variable get included on this command line too.

`JAVAHCOMSTR` 🌸

The string that gets displayed when C header and stub files are generated from Java classes. If this one isn't set, then $JAVAHCOM (the command line itself) is what shows up.

env = Environment(JAVAHCOMSTR="Generating header/stub file(s) $TARGETS from $SOURCES")

`JAVAHFLAGS` 🦋

General options passed to the C header and stub file generator for Java classes.

`JAVAINCLUDES` 💅

Include path for Java header files (think jni.h).

`JAVAPROCESSORPATH` 👑

Specifies where the annotation processor class files live. Can be a string or a Node object, or a list of strings or Node objects.

The value gets added to the JDK command lines via the -processorpath option, which — you guessed it — needs a system-specific search path separator. SCons supplies that as needed when it constructs the command line if $JAVAPROCESSORPATH is given in list form. If $JAVAPROCESSORPATH is a single string with search path separator characters in it (: for POSIX systems or ; for Windows), it will not be modified — which means it's inherently system-specific 😭. To supply the path in a system-independent way, give $JAVAPROCESSORPATH as a list of paths instead.

New in version 4.5.0 ⭐

`JAVASOURCEPATH` 🌈

Specifies the list of directories that'll be searched for input (source) .java files. Can be a string or a Node object, or a list of strings or Node objects.

The value gets added to the JDK command lines via the -sourcepath option, which needs a system-specific search path separator. SCons supplies it as needed when it constructs the command line if $JAVASOURCEPATH is provided in list form. But if $JAVASOURCEPATH is a single string with search path separator characters in it (: for POSIX systems or ; for Windows), it will not be modified, and so it's inherently system-specific; to supply the path in a system-independent manner, give $JAVASOURCEPATH as a list of paths instead.

Heads up though: those specified directories only get added to the command line via the -sourcepath option. SCons does not currently search the $JAVASOURCEPATH directories looking for dependent .java files. Noted. 📝

`JAVASUFFIX` 💜

The suffix for Java files. Defaults to .java.

`JAVAVERSION` 🔥

Specifies the Java version being used by the Java builder. Set this to say which version of Java the javac compiler is targeting. Sometimes you need to, because Java 1.5 switched up the file names it creates for nested anonymous inner classes, which can cause a mismatch with the files SCons expects javac to generate. Setting $JAVAVERSION to a version greater than 1.4 makes SCons realize that a build with such a compiler is actually up-to-date. The default is 1.4.

Now, this isn't primarily meant for picking one version of the Java compiler over another, but it does have that effect on the Windows platform. A more precise approach is to set $JAVAC (and related construction variables for related utilities) to the path of the specific Java compiler you want, if that's not the default compiler. On non-Windows platforms, the alternatives system might give you a way to adjust the default Java compiler without having to spell out explicit paths. 🧚

`LATEX` 🎀

The LaTeX structured formatter and typesetter.

`LATEXCOM` ✨

The command line used to call the LaTeX structured formatter and typesetter.

`LATEXCOMSTR` 💖

The string displayed when calling the LaTeX structured formatter and typesetter. If this isn't set, then $LATEXCOM (the command line) is displayed instead.

env = Environment(LATEXCOMSTR = "Building $TARGET from LaTeX input $SOURCES")

`LATEXFLAGS` 🦋

General options passed to the LaTeX structured formatter and typesetter.

`LATEXRETRIES` 🌸

The max number of times LaTeX will be re-run if the .log produced by the $LATEXCOM command says there are undefined references. Default behaviour is to try to resolve undefined references by re-running LaTeX up to three times.

`LATEXSUFFIXES` 💅

The list of suffixes of files that get scanned for LaTeX implicit dependencies (\include or \import files). The default list is:

[".tex", ".ltx", ".latex"]

`LDMODULE` 👑

The linker for building loadable modules. By default, this is the same as $SHLINK.

`LDMODULECOM` 🌈

The command line for building loadable modules. On Mac OS X, this uses the $LDMODULE, $LDMODULEFLAGS and $FRAMEWORKSFLAGS variables. On other systems, it's the same as $SHLINK.

`LDMODULECOMSTR` ⭐

If set, the string displayed when building loadable modules. If not set, then $LDMODULECOM (the command line) is displayed.

`LDMODULEEMITTER` 🫶

Contains the emitter specification for the LoadableModule builder. The manpage section "Builder Objects" has the general info on specifying emitters.

`LDMODULEFLAGS` 💜

General user options passed to the linker for building loadable modules.

`LDMODULENOVERSIONSYMLINKS` 🎀

Tells the LoadableModule builder not to automatically create symlinks for versioned modules. Defaults to $SHLIBNOVERSIONSYMLINKS.

`LDMODULEPREFIX` ✨

The prefix used for loadable module file names. On Mac OS X, this is null; on other systems, it's the same as $SHLIBPREFIX.

`_LDMODULESONAME` 🔍

A macro that automatically generates a loadable module's $SONAME based on $TARGET, $LDMODULEVERSION and $LDMODULESUFFIX. Used by the LoadableModule builder when the linker tool supports SONAME (like gnulink).

`LDMODULESUFFIX` 🌸

The suffix used for loadable module file names. On Mac OS X, this is null; on other systems, it's the same as $SHLIBSUFFIX.

`LDMODULEVERSION` 💖

When this construction variable is defined, a versioned loadable module gets created by the LoadableModule builder. That activates $_LDMODULEVERSIONFLAGS, which modifies $LDMODULECOM as required, adds the version number to the library name, and creates the symlinks that are needed. $LDMODULEVERSION versions should be specified in the same format as $SHLIBVERSION.

`_LDMODULEVERSIONFLAGS` 🦋

This macro automatically introduces extra flags to $LDMODULECOM when building a versioned LoadableModule (that is, when $LDMODULEVERSION is set). $_LDMODULEVERSIONFLAGS usually adds $SHLIBVERSIONFLAGS plus some extra dynamically generated options (like -Wl,-soname=$_LDMODULESONAME). It goes unused by plain (unversioned) loadable modules.

`LDMODULEVERSIONFLAGS` 💅

Extra flags added to $LDMODULECOM when building a versioned LoadableModule. These flags are only used when $LDMODULEVERSION is set.

`LEX` 👑

The lexical analyzer generator.

`LEX_HEADER_FILE` 🌈

If supplied, generate a C header file with the name taken from this variable. It gets emitted as a --header-file= command-line option. Use this in preference to jamming --header-file= into $LEXFLAGS directly. Trust.

`LEX_TABLES_FILE` ⭐

If supplied, write the lex tables to a file with the name taken from this variable. It gets emitted as a --tables-file= command-line option. Use this in preference to jamming --tables-file= into $LEXFLAGS directly.

`LEXCOM` 🎀

The command line used to call the lexical analyzer generator to generate a source file.

`LEXCOMSTR` ✨

The string displayed when generating a source file with the lexical analyzer generator. If this isn't set, then $LEXCOM (the command line) is displayed.

env = Environment(LEXCOMSTR="Lex'ing $TARGET from $SOURCES")

`LEXFLAGS` 💖

General options passed to the lexical analyzer generator. On top of just passing the value along during invocation, the lex tool also inspects this construction variable for options that cause extra output files to be generated, and adds those to the target list. Recognized for this purpose are the GNU flex options --header-file= and --tables-file=; the output file is named by the option argument. 🔍

Careful, bestie 😭 Files specified by --header-file= and --tables-file= may not be properly handled by SCons in all situations. Consider using $LEX_HEADER_FILE and $LEX_TABLES_FILE instead.

LEXUNISTD — Windows-only, bestie! 💻 It's used just in Windows environments to set a lex flag so that unistd.h doesn't get included at all. The default value is --nounistd. no cap.
_LIBDIRFLAGS — an auto-magically generated construction variable stuffed with the linker command-line options that say "hey, search these directories for libraries" ✨. The value of $_LIBDIRFLAGS gets made by prepending and appending $LIBDIRPREFIX and $LIBDIRSUFFIX (respectively, in that order, iykyk) to every single directory in $LIBPATH.
LIBDIRPREFIX — the prefix you use to point at a library directory on the linker command line. It gets prepended to each directory in the $LIBPATH construction variable whenever $_LIBDIRFLAGS is auto-generated. 🎀
LIBDIRSUFFIX — the suffix version of the same energy: it's what marks a library directory on the linker command line. It gets appended to each directory in $LIBPATH when $_LIBDIRFLAGS is auto-generated. 💫
LIBEMITTER — holds the emitter specification for the StaticLibrary builder. If you wanna know the general lore on specifying emitters, that lives in the "Builder Objects" section of this manpage. 👑
_LIBFLAGS — another auto-generated construction variable, this time carrying the linker command-line options for the libraries you're linking against your target. The value of $_LIBFLAGS is built by prepending and appending $LIBLINKPREFIX and $LIBLINKSUFFIX (respectively!) to each filename in $LIBS. 🦋
LIBLINKPREFIX — the prefix used to specify a library to link on the linker command line. It gets prepended to each library in $LIBS whenever $_LIBFLAGS is automatically generated.
LIBLINKSUFFIX — same vibe, other end: the suffix used to specify a library to link on the linker command line. It gets appended to each library in $LIBS whenever $_LIBFLAGS is auto-generated. 💅
LIBLITERALPREFIX — okay so if your linker supports command-line syntax telling it that the argument naming a library should be searched for literally (like, no modifications, untouched, main character behavior), you set $LIBLITERALPREFIX to that indicator. Example: the GNU linker follows this rule — “-l:foo searches the library path for a filename called foo, without converting it to libfoo.so or libfoo.a.” So if $LIBLITERALPREFIX is set, SCons will not transform a string-valued entry in $LIBS that starts with that string. The entry still gets surrounded with $LIBLINKPREFIX and $LIBLINKSUFFIX on the command line tho. This is useful, for instance, when you want to force a static library to be used even though both a static and dynamic one exist and the linker's policy is to prefer the dynamic ones. Compared with the example over in $LIBS:

env.Append(LIBS=":libmylib.a")

this lets the linker select that specific (static) library name if it finds it in the library search path. And heads up, this is different from using a File object to specify the static library, because the File route bypasses the library search path entirely. 🙈

LIBPATH — the list of directories that get searched for libraries specified by the $LIBS construction variable. $LIBPATH should be a list of path strings, or a single string — not a pathname list joined together with the Python os.pathsep character. 🚫

Do not put library search directives directly into $LINKFLAGS or $SHLINKFLAGS, bestie — the result will be non-portable and we do not want that energy. 💀

Note: directory names in $LIBPATH are looked up relative to the directory of the SConscript file when they're used in a command. If you want to force scons to look up a directory relative to the root of the source tree, use the # prefix, like:

env = Environment(LIBPATH='#/libs')

You can force that directory lookup with the Dir function too:

libs = Dir('libs')
env = Environment(LIBPATH=libs)

The directory list gets added to command lines through the automatically-generated $_LIBDIRFLAGS construction variable, which is constructed by prepending and appending the values of $LIBDIRPREFIX and $LIBDIRSUFFIX to each directory in $LIBPATH. Any command lines you define yourself that need the $LIBPATH directory list should include $_LIBDIRFLAGS, like this:

env = Environment(LINKCOM="my_linker $_LIBDIRFLAGS $_LIBFLAGS -o $TARGET $SOURCE")

LIBPREFIX — the prefix used for (static) library file names. A default value is set for each platform (posix, win32, os2, etc.), but that value gets overridden by individual tools (ar, mslib, sgiar, sunar, tlib, etc.) so it reflects whatever the libraries they create are actually named. 🧚
LIBPREFIXES — a list of every legal prefix for library file names on the current platform. When SCons goes searching for library dependencies, it looks for files with these prefixes, the base library name, and suffixes from the $LIBSUFFIXES list. 🔍
LIBS — the list of libraries that get added to the link line, for linking with any executable program, shared library, or loadable module created by the construction environment or override. 🫶

For portability, a string-valued library name should include only the base library name — no prefixes like lib, no suffixes like .so or .dll. SCons will try to strip prefixes from the $LIBPREFIXES list and suffixes from the $LIBSUFFIXES list, but depending on that behavior makes your build less portable: for example, on a POSIX system, no attempt is made to strip a suffix like .dll. Library name strings in $LIBS should not include a path component — instead use $LIBPATH to point the compiler at those paths, plus any default paths the linker searches in. If $LIBLITERALPREFIX is set to a non-empty string, then a string-valued $LIBS entry that starts with $LIBLITERALPREFIX will cause the rest of the entry to be searched for unmodified, but still respecting normal library search paths (this is the exception to the guideline above about leaving off the prefix/suffix from the library name). ✨

If a $LIBS entry is a Node object (either returned by a previous Builder call, or produced by an explicit call to File), the pathname from that Node gets added to $_LIBFLAGS, and therefore to the link line, unmodified — with no $LIBLINKPREFIX or $LIBLINKSUFFIX added. Entries like that are searched for literally (including any path component); the library search paths are not used. Like so:

env.Append(LIBS=File('/tmp/mylib.so'))

For every Builder call that causes linking with libraries, SCons adds the libraries from the $LIBS setting in effect at that moment into the dependency graph as dependencies of the target being generated. 🔗

The library list gets transformed into command-line arguments through the auto-generated $_LIBFLAGS construction variable, which is constructed by prepending and appending the values of $LIBLINKPREFIX and $LIBLINKSUFFIX to each library name.

Any command lines you define yourself that need the libraries from $LIBS should include $_LIBFLAGS (as well as $_LIBDIRFLAGS) rather than $LIBS. For example:

env = Environment(LINKCOM="my_linker $_LIBDIRFLAGS $_LIBFLAGS -o $TARGET $SOURCE")

LIBSUFFIX — the suffix used for (static) library file names. A default value is set for each platform (posix, win32, os2, etc.), but the value gets overridden by individual tools (ar, mslib, sgiar, sunar, tlib, etc.) to reflect the names of the libraries they create. 💜
LIBSUFFIXES — a list of all the legal suffixes for library file names on the current platform. When SCons searches for library dependencies, it looks for files with prefixes from the $LIBPREFIXES list, the base library name, and these suffixes. 🌈
LICENSE — the abbreviated name, preferably the SPDX code, of the license this project is released under (GPL-3.0, LGPL-2.1, BSD-2-Clause, etc.). Go check http://www.opensource.org/licenses/alphabetical[7] for a list of license names and SPDX codes. 📜

See the Package builder.

LINESEPARATOR — the separator used by the Substfile and Textfile builders. This value sits between sources when the target is being constructed. It defaults to the current system's line separator. 🎀
LINGUAS_FILE — $LINGUAS_FILE defines the file(s) holding the list of additional linguas to be processed by the POInit, POUpdate or MOFiles builders. It also affects the Translate builder. If the variable holds a string, that string is the name of the list file. And $LINGUAS_FILE can be a list of file names too. If $LINGUAS_FILE is set to a non-string truthy value, the list gets read from the file named LINGUAS. 🗂️
LINK — the linker, bestie. See also $SHLINK for linking shared objects. 🔗

On POSIX systems (the ones using the link tool), you should normally not change this value, because it defaults to a "smart" linker tool that picks a compiler driver matching the type of source files in use. So like, if you set $CXX to a specific compiler name and you're compiling C++ sources, the smartlink function automatically selects that same compiler for linking. iconic.

LINKCOM — the command line used to link object files into an executable. See also $SHLINKCOM for linking shared objects. 💅
LINKCOMSTR — if it's set, this is the string displayed when object files get linked into an executable. If it's not set, then $LINKCOM (the command line) is displayed instead. See also $SHLINKCOMSTR for linking shared objects. ✨

env = Environment(LINKCOMSTR = "Linking $TARGET")

LINKFLAGS — general user options passed to the linker. Quick note: this variable should not contain -l (or similar) options for linking with the libraries listed in $LIBS, and also not -L (or similar) library search path options that scons generates automatically from $LIBPATH. Check $_LIBFLAGS above for the variable that expands to library-link options, and $_LIBDIRFLAGS above for the variable that expands to library search path options. See also $SHLINKFLAGS for linking shared objects. 🚧
M4 — the M4 macro preprocessor. 🌀
M4COM — the command line used to pass files through the M4 macro preprocessor.
M4COMSTR — the string displayed when a file is passed through the M4 macro preprocessor. If this isn't set, then $M4COM (the command line) gets displayed. 👀
M4FLAGS — general options passed to the M4 macro preprocessor. 🎀

🌸 `MAKEINDEX` 🌸

The makeindex generator, bestie — it's for the TeX formatter and typesetter and the LaTeX structured formatter and typesetter. Two whole formatters, one little generator carrying them both. Iconic, honestly. 👑

🎀 `MAKEINDEXCOM` 🎀

The command line that gets used to call the makeindex generator for the TeX formatter and typesetter and the LaTeX structured formatter and typesetter. That's the whole thing.

💖 `MAKEINDEXCOMSTR` 💖

The string that gets displayed when we call that makeindex generator for the TeX formatter and typesetter and the LaTeX structured formatter and typesetter. If you don't set this? Then $MAKEINDEXCOM — the actual command line — is what shows up instead. So it's giving "if u didn't dress it up, it's wearing the default". 💅

✨ `MAKEINDEXFLAGS` ✨

General options passed along to the makeindex generator for the TeX formatter and typesetter and the LaTeX structured formatter and typesetter. 💫

🔥 `MAXLINELENGTH` 🔥

The maximum number of characters allowed on an external command line. That's it, that's the limit.

On Win32 systems: link lines that are longer than this many characters get linked via a temporary file name. Not asking permission, just doing it. 🪟

💜 `MIDL` 💜

The Microsoft IDL compiler. Short king. 👑

🎀 `MIDLCOM` 🎀

The command line used to pass files to the Microsoft IDL compiler.

🌈 `MIDLCOMSTR` 🌈

The string displayed when the Microsoft IDL compiler gets called. Not set? Then $MIDLCOM — the command line — is displayed, as always. The defaults are consistent, we love to see it. 💅

🦋 `MIDLFLAGS` 🦋

General options passed to the Microsoft IDL compiler.

🍓 `MOSUFFIX` 🍓

Suffix used for MO files — default is '.mo'. See the msgfmt tool and the MOFiles builder for the whole situation. 🫶

⭐ `MSGFMT` ⭐

Absolute path to the msgfmt(1) binary, found by Detect(). See the msgfmt tool and the MOFiles builder. ✨

💖 `MSGFMTCOM` 💖

Complete command line to run the msgfmt(1) program. See the msgfmt tool and the MOFiles builder.

🎀 `MSGFMTCOMSTR` 🎀

String to display when msgfmt(1) is invoked. Default: '' — which means "print $MSGFMTCOM". See the msgfmt tool and the MOFiles builder. 💫

🌸 `MSGFMTFLAGS` 🌸

Additional flags to msgfmt(1). See the msgfmt tool and the MOFiles builder.

🦋 `MSGINIT` 🦋

Path to the msginit(1) program (found via Detect). See the msginit tool and the POInit builder. 🫶

💜 `MSGINITCOM` 💜

Complete command line to run the msginit(1) program. See the msginit tool and the POInit builder.

✨ `MSGINITCOMSTR` ✨

String to display when msginit(1) is invoked. The default is an empty string, which will print the command line ($MSGINITCOM). See the msginit tool and the POInit builder. 👑

🎀 `MSGINITFLAGS` 🎀

List of additional flags to msginit(1). Default: []. See the msginit tool and the POInit builder.

🔮 `_MSGINITLOCALE` 🔮

Internal "macro", okay, the quotes are theirs not mine — it's air-quoting itself. 🙈

It computes the locale (language) name based on the target filename. Default: '${TARGET.filebase}'.

See the msginit tool and the POInit builder.

💖 `MSGMERGE` 💖

Absolute path to the msgmerge(1) binary as found by Detect(). See the msgmerge tool and the POUpdate builder. ⭐

🌈 `MSGMERGECOM` 🌈

Complete command line to run the msgmerge(1) command. See the msgmerge tool and the POUpdate builder.

🧚 `MSGMERGECOMSTR` 🧚

String to be displayed when msgmerge(1) is invoked. The default is an empty string, which will print the command line ($MSGMERGECOM). See the msgmerge tool and the POUpdate builder. 💫

🍓 `MSGMERGEFLAGS` 🍓

Additional flags to the msgmerge(1) command. See the msgmerge tool and the POUpdate builder.

👑 `MSSDK_DIR` 👑

The directory containing the Microsoft SDK — either Platform SDK or Windows SDK, whichever one — to be used for compilation. 🪟

💅 `MSSDK_VERSION` 💅

The version string of the Microsoft SDK (either Platform SDK or Windows SDK) to be used for compilation. Supported versions include 6.1, 6.0A, 6.0, 2003R2 and 2003R1. Like, those are the ones on the list, bestie. Not making it up.

🔥 `MSVC_BATCH` 🔥

When set to any true value, this specifies that SCons should batch compilation of object files when calling the Microsoft Visual C++ compiler. 🚀

Here's the whole vibe: all compilations of source files from the same source directory that generate target files in a same output directory and were configured in SCons using the same construction environment will be built in a single call to the compiler. Only source files that have changed since their object files were built will be passed to each compiler invocation — and that's via the $CHANGED_SOURCES construction variable. 📦

Any compilations where the object (target) file base name (minus the .obj) does not match the source file base name will be compiled separately. No grouping for those ones. Sorry. 🙈

💀 `MSVC_NOTFOUND_POLICY` 💀

Specify the scons behavior when the Microsoft Visual C++ compiler is not detected. This is the "what do we do when nobody's home" variable. 🏚️

The $MSVC_NOTFOUND_POLICY specifies the scons behavior when no msvc versions are detected or when the requested msvc version is not detected.

The valid values for $MSVC_NOTFOUND_POLICY and the corresponding scons behavior are:

'Error' or 'Exception' — Raise an exception when no msvc versions are detected or when the requested msvc version is not detected.
'Warning' or 'Warn' — Issue a warning and continue when no msvc versions are detected or when the requested msvc version is not detected. Depending on usage, this could result in build failure(s).
'Ignore' or 'Suppress' — Take no action and continue when no msvc versions are detected or when the requested msvc version is not detected. Depending on usage, this could result in build failure(s).

Not me double-checking: yes, Warning/Warn and Ignore/Suppress can both end in build failure(s) depending on usage. That's not a typo, that's just the warning label on the box. 😭

Note: in addition to the camel case values shown above, lower case and upper case values are accepted as well. Case-insensitive queen. 👑

The $MSVC_NOTFOUND_POLICY is applied when any of the following conditions are satisfied:

$MSVC_VERSION is specified, the default tools list is implicitly defined (i.e., the tools list is not specified), and the default tools list contains one or more of the msvc tools.
$MSVC_VERSION is specified, the default tools list is explicitly specified (e.g., tools=['default']), and the default tools list contains one or more of the msvc tools.
A non-default tools list is specified that contains one or more of the msvc tools (e.g., tools=['msvc', 'mslink']).

The $MSVC_NOTFOUND_POLICY is ignored when any of the following conditions are satisfied:

$MSVC_VERSION is not specified and the default tools list is implicitly defined (i.e., the tools list is not specified).
$MSVC_VERSION is not specified and the default tools list is explicitly specified (e.g., tools=['default']).
A non-default tool list is specified that does not contain any of the msvc tools (e.g., tools=['mingw']).

Important usage details:

$MSVC_NOTFOUND_POLICY must be passed as an argument to the Environment constructor when an msvc tool (e.g., msvc, msvs, etc.) is loaded via the default tools list or via a tools list passed to the Environment constructor. Otherwise, $MSVC_NOTFOUND_POLICY must be set before the first msvc tool is loaded into the environment.

When $MSVC_NOTFOUND_POLICY is not specified, the default scons behavior is to issue a warning and continue subject to the conditions listed above. The default scons behavior may change in the future. 👀

New in version 4.4.

🎀 `MSVC_SCRIPT_ARGS` 🎀

Pass user-defined arguments to the Microsoft Visual C++ batch file determined via autodetection. 🛠️

$MSVC_SCRIPT_ARGS is available for msvc batch file arguments that do not have first-class support via construction variables or when there is an issue with the appropriate construction variable validation. When available, it is recommended to use the appropriate construction variables (e.g., $MSVC_TOOLSET_VERSION) rather than $MSVC_SCRIPT_ARGS arguments. Like, use the nice dedicated variable when there is one, bestie. That's the move. 💅

The valid values for $MSVC_SCRIPT_ARGS are: None, a string, or a list of strings.

The $MSVC_SCRIPT_ARGS value is converted to a scalar string (i.e., "flattened"). The resulting scalar string, if not empty, is passed as an argument to the msvc batch file determined via autodetection subject to the validation conditions listed below.

$MSVC_SCRIPT_ARGS is ignored when the value is None and when the result from argument conversion is an empty string. The validation conditions below do not apply in that case.

An exception is raised when any of the following conditions are satisfied:

$MSVC_SCRIPT_ARGS is specified for Visual Studio 2013 and earlier.
Multiple SDK version arguments (e.g., '10.0.20348.0') are specified in $MSVC_SCRIPT_ARGS.
$MSVC_SDK_VERSION is specified and an SDK version argument (e.g., '10.0.20348.0') is specified in $MSVC_SCRIPT_ARGS. Multiple SDK version declarations via $MSVC_SDK_VERSION and $MSVC_SCRIPT_ARGS are not allowed.
Multiple toolset version arguments (e.g., '-vcvars_ver=14.29') are specified in $MSVC_SCRIPT_ARGS.
$MSVC_TOOLSET_VERSION is specified and a toolset version argument (e.g., '-vcvars_ver=14.29') is specified in $MSVC_SCRIPT_ARGS. Multiple toolset version declarations via $MSVC_TOOLSET_VERSION and $MSVC_SCRIPT_ARGS are not allowed.
Multiple spectre library arguments (e.g., '-vcvars_spectre_libs=spectre') are specified in $MSVC_SCRIPT_ARGS.
$MSVC_SPECTRE_LIBS is enabled and a spectre library argument (e.g., '-vcvars_spectre_libs=spectre') is specified in $MSVC_SCRIPT_ARGS. Multiple spectre library declarations via $MSVC_SPECTRE_LIBS and $MSVC_SCRIPT_ARGS are not allowed.
Multiple UWP arguments (e.g., uwp or store) are specified in $MSVC_SCRIPT_ARGS.
$MSVC_UWP_APP is enabled and a UWP argument (e.g., uwp or store) is specified in $MSVC_SCRIPT_ARGS. Multiple UWP declarations via $MSVC_UWP_APP and $MSVC_SCRIPT_ARGS are not allowed.

Basically: don't say the same thing twice. Two ways in, one way out. 🚫

Example 1 — A Visual Studio 2022 build with an SDK version and a toolset version specified with a string argument:

env = Environment(MSVC_VERSION='14.3', MSVC_SCRIPT_ARGS='10.0.20348.0 -vcvars_ver=14.29.30133')

Example 2 — A Visual Studio 2022 build with an SDK version and a toolset version specified with a list argument:

env = Environment(MSVC_VERSION='14.3', MSVC_SCRIPT_ARGS=['10.0.20348.0', '-vcvars_ver=14.29.30133'])

Important usage details:

$MSVC_SCRIPT_ARGS must be passed as an argument to the Environment constructor when an msvc tool (e.g., msvc, msvs, etc.) is loaded via the default tools list or via a tools list passed to the Environment constructor. Otherwise, $MSVC_SCRIPT_ARGS must be set before the first msvc tool is loaded into the environment. ⏰
Other than checking for multiple declarations as described above, $MSVC_SCRIPT_ARGS arguments are not validated. Like, at all. No vibe check, no nothing. 💀
- Erroneous, inconsistent, and/or version incompatible $MSVC_SCRIPT_ARGS arguments are likely to result in build failures for reasons that are not readily apparent and may be difficult to diagnose. The burden is on the user to ensure that the arguments provided to the msvc batch file are valid, consistent and compatible with the version of msvc selected. Bestie, that's on you. 😭

New in version 4.4

MSVC_SCRIPTERROR_POLICY

Specify the scons behavior when Microsoft Visual C++ batch file errors are detected. ✨ drama control ✨

The $MSVC_SCRIPTERROR_POLICY specifies the scons behavior when msvc batch file errors are detected. When $MSVC_SCRIPTERROR_POLICY is not specified, the default scons behavior is to suppress msvc batch file error messages.

The root cause of msvc build failures may be difficult to diagnose. In these situations, setting the scons behavior to issue a warning when msvc batch file errors are detected may produce additional diagnostic information. tea ☕ spilled by the compiler itself, iconic

The valid values for $MSVC_SCRIPTERROR_POLICY and the corresponding scons behavior are:

'Error' or 'Exception' — Raise an exception when msvc batch file errors are detected. full main-character meltdown mode 💅
'Warning' or 'Warn' — Issue a warning when msvc batch file errors are detected.
'Ignore' or 'Suppress' — Suppress msvc batch file error messages. shhh, we don't talk about it 🙈

New in version 4.4

Note: in addition to the camel case values shown above, lower case and upper case values are accepted as well. case-insensitive queen 👑

Example 1 — A Visual Studio 2022 build with user-defined script arguments:

env = environment(MSVC_VERSION='14.3', MSVC_SCRIPT_ARGS=['8.1', 'store', '-vcvars_ver=14.1'])
env.Program('hello', ['hello.c'], CCFLAGS='/MD', LIBS=['kernel32', 'user32', 'runtimeobject'])

Example 1 — Output fragment:

...
link /nologo /OUT:_build001\hello.exe kernel32.lib user32.lib runtimeobject.lib _build001\hello.obj
LINK : fatal error LNK1104: cannot open file 'MSVCRT.lib'
...

Example 2 — A Visual Studio 2022 build with user-defined script arguments and the script error policy set to issue a warning when msvc batch file errors are detected:

env = environment(MSVC_VERSION='14.3', MSVC_SCRIPT_ARGS=['8.1', 'store', '-vcvars_ver=14.1'], MSVC_SCRIPTERROR_POLICY='warn')
env.Program('hello', ['hello.c'], CCFLAGS='/MD', LIBS=['kernel32', 'user32', 'runtimeobject'])

Example 2 — Output fragment:

...
scons: warning: vc script errors detected:
[ERROR:vcvars.bat] The UWP Application Platform requires a Windows 10 SDK.
[ERROR:vcvars.bat] WindowsSdkDir = "C:\Program Files (x86)\Windows Kits\8.1\"
[ERROR:vcvars.bat] host/target architecture is not supported : { x64 , x64 }
...
link /nologo /OUT:_build001\hello.exe kernel32.lib user32.lib runtimeobject.lib _build001\hello.obj
LINK : fatal error LNK1104: cannot open file 'MSVCRT.lib'

Important usage details:

$MSVC_SCRIPTERROR_POLICY must be passed as an argument to the Environment constructor when an msvc tool (e.g., msvc, msvs, etc.) is loaded via the default tools list or via a tools list passed to the Environment constructor. Otherwise, $MSVC_SCRIPTERROR_POLICY must be set before the first msvc tool is loaded into the environment. timing is literally everything, bestie ⏰
Due to scons implementation details, not all Windows system environment variables are propagated to the environment in which the msvc batch file is executed. Depending on Visual Studio version and installation options, non-fatal msvc batch file error messages may be generated for ancillary tools which may not affect builds with the msvc compiler. For this reason, caution is recommended when setting the script error policy to raise an exception (e.g., 'Error'). do not just yeet it to Error, I'm begging 🫶

New in version 4.4

MSVC_SDK_VERSION

Build with a specific version of the Microsoft Software Development Kit (SDK). SDK: the sequel 🎀

The valid values for $MSVC_SDK_VERSION are: None or a string containing the requested SDK version (e.g., '10.0.20348.0').

$MSVC_SDK_VERSION is ignored when the value is None and when the value is an empty string. The validation conditions below do not apply. empty string said "no thoughts, head empty" 🙈

An exception is raised when any of the following conditions are satisfied:

$MSVC_SDK_VERSION is specified for Visual Studio 2013 and earlier.
$MSVC_SDK_VERSION is specified and an SDK version argument is specified in $MSVC_SCRIPT_ARGS. Multiple SDK version declarations via $MSVC_SDK_VERSION and $MSVC_SCRIPT_ARGS are not allowed. pick ONE, we are not doing polyamory with SDK versions 💅
The $MSVC_SDK_VERSION specified does not match any of the supported formats:
- '10.0.XXXXX.Y' [SDK 10.0]
- '8.1' [SDK 8.1]
The system folder for the corresponding $MSVC_SDK_VERSION version is not found. The requested SDK version does not appear to be installed. girl where is it 😭
The $MSVC_SDK_VERSION version does not appear to support the requested platform type (i.e., UWP or Desktop). The requested SDK version platform type components do not appear to be installed.
The $MSVC_SDK_VERSION version is 8.1, the platform type is UWP, and the build tools selected are from Visual Studio 2017 and later (i.e., $MSVC_VERSION must be '14.0' or $MSVC_TOOLSET_VERSION must be '14.0').

Example 1 — A Visual Studio 2022 build with a specific Windows SDK version:

env = Environment(MSVC_VERSION='14.3', MSVC_SDK_VERSION='10.0.20348.0')

Example 2 — A Visual Studio 2022 build with a specific SDK version for the Universal Windows Platform:

env = Environment(MSVC_VERSION='14.3', MSVC_SDK_VERSION='10.0.20348.0', MSVC_UWP_APP=True)

Important usage details:

$MSVC_SDK_VERSION must be passed as an argument to the Environment constructor when an msvc tool (e.g., msvc, msvs, etc.) is loaded via the default tools list or via a tools list passed to the Environment constructor. Otherwise, $MSVC_SDK_VERSION must be set before the first msvc tool is loaded into the environment.
Should a SDK 10.0 version be installed that does not follow the naming scheme above, the SDK version will need to be specified via $MSVC_SCRIPT_ARGS until the version number validation format can be extended. weird naming? go the back way, iykyk
Should an exception be raised indicating that the SDK version is not found, verify that the requested SDK version is installed with the necessary platform type components.
There is a known issue with the Microsoft libraries when the target architecture is ARM64 and a Windows 11 SDK (version '10.0.22000.0' and later) is used with the v141 build tools and older v142 toolsets (versions '14.28.29333' and earlier). Should build failures arise with these combinations of settings due to unresolved symbols in the Microsoft libraries, $MSVC_SDK_VERSION may be employed to specify a Windows 10 SDK (e.g., '10.0.20348.0') for the build. not a bug in your code, bestie, it's the libraries being messy 💀

New in version 4.4

MSVC_SPECTRE_LIBS

Build with the spectre-mitigated Microsoft Visual C++ libraries. spooky name, very serious security business 🧚

The valid values for $MSVC_SPECTRE_LIBS are: True, False, or None.

When $MSVC_SPECTRE_LIBS is enabled (i.e., True), the Microsoft Visual C++ environment will include the paths to the spectre-mitigated implementations of the Microsoft Visual C++ libraries.

An exception is raised when any of the following conditions are satisfied:

$MSVC_SPECTRE_LIBS is enabled for Visual Studio 2015 and earlier.
$MSVC_SPECTRE_LIBS is enabled and a spectre library argument is specified in $MSVC_SCRIPT_ARGS. Multiple spectre library declarations via $MSVC_SPECTRE_LIBS and $MSVC_SCRIPT_ARGS are not allowed. again babe, one or the other ✋
$MSVC_SPECTRE_LIBS is enabled and the platform type is UWP. There are no spectre-mitigated libraries for Universal Windows Platform (UWP) applications or components. they literally do not exist, i cannot manifest them for you 😭

Example — A Visual Studio 2022 build with spectre mitigated Microsoft Visual C++ libraries:

env = Environment(MSVC_VERSION='14.3', MSVC_SPECTRE_LIBS=True)

Important usage details:

$MSVC_SPECTRE_LIBS must be passed as an argument to the Environment constructor when an msvc tool (e.g., msvc, msvs, etc.) is loaded via the default tools list or via a tools list passed to the Environment constructor. Otherwise, $MSVC_SPECTRE_LIBS must be set before the first msvc tool is loaded into the environment.
Additional compiler switches (e.g., /Qspectre) are necessary for including spectre mitigations when building user artifacts. Refer to the Visual Studio documentation for details. this variable just sets up the paths, it does not do the whole job for you 💅
The existence of the spectre libraries host architecture and target architecture folders are not verified when $MSVC_SPECTRE_LIBS is enabled which could result in build failures. The burden is on the user to ensure the requisite libraries with spectre mitigations are installed. no verification, all vibes, and therefore all consequences are yours 🫶

New in version 4.4

MSVC_TOOLSET_VERSION

Build with a specific Microsoft Visual C++ toolset version.

Specifying $MSVC_TOOLSET_VERSION does not affect the autodetection and selection of msvc instances. The $MSVC_TOOLSET_VERSION is applied after an msvc instance is selected. This could be the default version of msvc if $MSVC_VERSION is not specified. it's giving "chose your fighter first, then your fit" 👑

The valid values for $MSVC_TOOLSET_VERSION are: None or a string containing the requested toolset version (e.g., '14.29').

$MSVC_TOOLSET_VERSION is ignored when the value is None and when the value is an empty string. The validation conditions below do not apply.

An exception is raised when any of the following conditions are satisfied:

$MSVC_TOOLSET_VERSION is specified for Visual Studio 2015 and earlier.
$MSVC_TOOLSET_VERSION is specified and a toolset version argument is specified in $MSVC_SCRIPT_ARGS. Multiple toolset version declarations via $MSVC_TOOLSET_VERSION and $MSVC_SCRIPT_ARGS are not allowed. one toolset. ONE. SLASH THAT DUPLICATE 💅

ok ALSO — and this is the part that lowkey ruins people's whole afternoon, bestie — here's exactly when things go 💀 and you get an error:

the $MSVC_TOOLSET_VERSION you handed over does not match any of the supported formats:
- 'XX.Y'
- 'XX.YY'
- 'XX.YY.ZZZZZ'
- 'XX.YY.Z' to 'XX.YY.ZZZZ' — [scons extension not directly supported by the msvc batch files and may be removed in the future]
- 'XX.YY.ZZ.N' [SxS format]
- 'XX.YY.ZZ.NN' [SxS format]
the major msvc version prefix (that's the 'XX.Y' bit) of the $MSVC_TOOLSET_VERSION you specified is for Visual Studio 2013 and earlier (like '12.0'). it's giving ancient.
the major msvc version prefix (again, the 'XX.Y' part) of your $MSVC_TOOLSET_VERSION is greater than the msvc version you selected (e.g. '99.0'). ma'am that toolset does not exist.
there's no system folder for the $MSVC_TOOLSET_VERSION version you asked for. in normal-people words: the toolset version you requested does not appear to be installed. 😭

Toolset selection details:

when $MSVC_TOOLSET_VERSION is not an SxS version number and not a full toolset version number: the first toolset version, ranked in descending order, that matches the $MSVC_TOOLSET_VERSION prefix gets selected.
when $MSVC_TOOLSET_VERSION is specified using the major msvc version prefix (i.e., 'XX.Y') and that major msvc version is the one belonging to the latest release of Visual Studio, the toolset version that gets selected may not be the same as the default Microsoft Visual C++ toolset version.

fr fr, in the latest release of Visual Studio, the default Microsoft Visual C++ toolset version is not necessarily the toolset with the largest version number. iykyk.

Example 1 — a default Visual Studio build with a partial toolset version specified:

env = Environment(MSVC_TOOLSET_VERSION='14.2')

Example 2 — a default Visual Studio build with a partial toolset version specified:

env = Environment(MSVC_TOOLSET_VERSION='14.29')

Example 3 — a Visual Studio 2022 build with a full toolset version specified:

env = Environment(MSVC_VERSION='14.3', MSVC_TOOLSET_VERSION='14.29.30133')

Example 4 — a Visual Studio 2022 build with an SxS toolset version specified:

env = Environment(MSVC_VERSION='14.3', MSVC_TOOLSET_VERSION='14.29.16.11')

Important usage details:

$MSVC_TOOLSET_VERSION must be passed as an argument to the Environment constructor when an msvc tool (e.g. msvc, msvs, etc.) is loaded via the default tools list or via a tools list passed to the Environment constructor. otherwise, $MSVC_TOOLSET_VERSION has to be set before the first msvc tool is loaded into the environment. no exceptions, periodt.
The existence of the toolset host architecture and target architecture folders are not verified when $MSVC_TOOLSET_VERSION is specified which could result in build failures. The burden is on the user to ensure the requisite toolset target architecture build tools are installed.

🫶 bestie that's the whole vibe of these Windows vars: SCons trusts you and will absolutely let you build a broken setup. you're the main character AND the adult here.

New in version 4.4 ✨

🎀 `MSVC_USE_SCRIPT`

Use a batch script to set up the Microsoft Visual C++ compiler. old-school but iconic.

If it's set to the name of a Visual Studio .bat file (e.g. vcvars.bat), SCons will run that batch file instead of the auto-detected one, and extract the relevant variables from the result (typically %INCLUDE%, %LIB%, and %PATH%) for supplying to the build. this is soooo useful for forcing the use of a compiler version that SCons does not detect. $MSVC_USE_SCRIPT_ARGS provides arguments passed to this script.

Setting $MSVC_USE_SCRIPT to None bypasses the Visual Studio autodetection entirely — use this if you are running SCons in a Visual Studio cmd window and importing the shell's environment variables. that is, if you are sure everything is set correctly already and you don't want SCons to change anything.

$MSVC_USE_SCRIPT ignores $MSVC_VERSION and $TARGET_ARCH. yes really. it's giving "i don't see you."

Changed in version 4.4: new $MSVC_USE_SCRIPT_ARGS provides a way to pass arguments.

💅 `MSVC_USE_SCRIPT_ARGS`

Provides arguments passed to the script $MSVC_USE_SCRIPT. that's the whole thing. short queen.

New in version 4.4 ✨

🦋 `MSVC_USE_SETTINGS`

Use a dictionary to set up the Microsoft Visual C++ compiler.

$MSVC_USE_SETTINGS is ignored when $MSVC_USE_SCRIPT is defined and/or when $MSVC_USE_SETTINGS is set to None.

The dictionary is used to populate the environment with the relevant variables (typically %INCLUDE%, %LIB%, and %PATH%) for supplying to the build. this is useful to force the use of a compiler environment that SCons does not configure correctly. it's an alternative to manually configuring the environment when you're bypassing Visual Studio autodetection entirely by setting $MSVC_USE_SCRIPT to None. chef's kiss.

Here's an example of configuring a build environment using the Microsoft Visual C++ compiler included in the Microsoft SDK on a 64-bit host and building for a 64-bit architecture:

# Microsoft SDK 6.0 (MSVC 8.0): 64-bit host and 64-bit target
msvc_use_settings = {
    "PATH": [
        "C:\\Program Files\\Microsoft SDKs\\Windows\\v6.0\\VC\\Bin\\x64",
        "C:\\Program Files\\Microsoft SDKs\\Windows\\v6.0\\Bin\\x64",
        "C:\\Program Files\\Microsoft SDKs\\Windows\\v6.0\\Bin",
        "C:\\Windows\\Microsoft.NET\\Framework\\v2.0.50727",
        "C:\\Windows\\system32",
        "C:\\Windows",
        "C:\\Windows\\System32\\Wbem",
        "C:\\Windows\\System32\\WindowsPowerShell\\v1.0\\"
    ],
    "INCLUDE": [
        "C:\\Program Files\\Microsoft SDKs\\Windows\\v6.0\\VC\\Include",
        "C:\\Program Files\\Microsoft SDKs\\Windows\\v6.0\\VC\\Include\\Sys",
        "C:\\Program Files\\Microsoft SDKs\\Windows\\v6.0\\Include",
        "C:\\Program Files\\Microsoft SDKs\\Windows\\v6.0\\Include\\gl",
    ],
    "LIB": [
        "C:\\Program Files\\Microsoft SDKs\\Windows\\v6.0\\VC\\Lib\\x64",
        "C:\\Program Files\\Microsoft SDKs\\Windows\\v6.0\\Lib\\x64",
    ],
    "LIBPATH": [],
    "VSCMD_ARG_app_plat": [],
    "VCINSTALLDIR": [],
    "VCToolsInstallDir": []
}

# Specifying MSVC_VERSION is recommended
env = Environment(MSVC_VERSION='8.0', MSVC_USE_SETTINGS=msvc_use_settings)

Important usage details:

$MSVC_USE_SETTINGS must be passed as an argument to the Environment constructor when an msvc tool (e.g. msvc, msvs, etc.) is loaded via the default tools list or via a tools list passed to the Environment constructor. otherwise, $MSVC_USE_SETTINGS has to be set before the first msvc tool is loaded into the environment.
The dictionary content requirements are based on the internal msvc implementation and therefore may change at any time. The burden is on the user to ensure the dictionary contents are minimally sufficient to ensure successful builds.

💀 "may change at any time" — that's not a vibe, that's a warning label. if a future SCons release wants different keys, your dict is on its own.

New in version 4.4 ✨

⭐ `MSVC_UWP_APP`

Build with the Universal Windows Platform (UWP) application Microsoft Visual C++ libraries.

The valid values for $MSVC_UWP_APP are: True, '1', False, '0', or None.

When $MSVC_UWP_APP is enabled (i.e., True or '1'), the Microsoft Visual C++ environment will be set up to point to the Windows Store compatible libraries and Microsoft Visual C++ runtimes. In doing so, any libraries that are built will be able to be used in a UWP App and published to the Windows Store. slay, ship it to the store 🫶

An exception is raised when any of the following conditions are satisfied:

$MSVC_UWP_APP is enabled for Visual Studio 2013 and earlier.
$MSVC_UWP_APP is enabled and a UWP argument is specified in $MSVC_SCRIPT_ARGS. Multiple UWP declarations via $MSVC_UWP_APP and $MSVC_SCRIPT_ARGS are not allowed.

Example — a Visual Studio 2022 build for the Universal Windows Platform:

env = Environment(MSVC_VERSION='14.3', MSVC_UWP_APP=True)

Important usage details:

$MSVC_UWP_APP must be passed as an argument to the Environment constructor when an msvc tool (e.g., msvc, msvs, etc.) is loaded via the default tools list or via a tools list passed to the Environment constructor. otherwise, $MSVC_UWP_APP has to be set before the first msvc tool is loaded into the environment.
The existence of the UWP libraries is not verified when $MSVC_UWP_APP is enabled which could result in build failures. The burden is on the user to ensure the requisite UWP libraries are installed.

👑 `MSVC_VERSION`

A string to select the preferred version of Microsoft Visual C++. if the version you specified is unavailable and/or unknown to SCons, a warning is issued showing the versions actually discovered, and the build will eventually fail indicating a missing compiler binary. if $MSVC_VERSION is not set, SCons will (by default) select the latest version of Microsoft Visual C++ installed on your system (excluding any preview versions). no pre-releases, we're not doing betas today.

Note In order to take effect, $MSVC_VERSION must be set before the initial Microsoft Visual C++ compiler discovery takes place. Discovery happens, at the latest, during the first call to the Environment function, unless a tools list is specified which excludes the entire Microsoft Visual C++ toolchain — that is, omits "defaults" and any specific tool module that refers to parts of the toolchain (msvc, mslink, masm, midl and msvs). In this case, detection is deferred until any one of those tool modules is invoked manually. The following two examples illustrate this:

# MSVC_VERSION set as Environment is created
env = Environment(MSVC_VERSION='14.2')

# Initialization deferred with empty tools, triggered manually
env = Environment(tools=[])
env['MSVC_VERSION'] = '14.2
env.Tool('msvc')
env.Tool('mslink')
env.Tool('msvs')

The valid values for $MSVC_VERSION represent major versions of the compiler, except that versions ending in Exp refer to "Express" or "Express for Desktop" Visual Studio editions. Values that do not look like a valid compiler version string are not supported.

🌸 tl;dr: set it early or it simply won't count. timing is everything, bestie.

Okay so real talk, $MSVC_VERSION has a whole family tree and you're gonna want to know who's who 💖 The original does this as a big table, but we're doing it as a list so it actually fits in your terminal, bestie. Quick key: 'x' is just a placeholder for a single digit that can wiggle around. No cap.

"14.5" — Visual C++ Version 14.5x, _MSVC_VER 195x, Visual Studio Product Visual Studio 2026, MSBuild / Visual Studio 18.x ✨
"14.3" — Visual C++ Version 14.3x, _MSVC_VER 193x, Visual Studio Product Visual Studio 2022, MSBuild / Visual Studio 17.x, 17.1x
"14.2" — Visual C++ Version 14.2x, _MSVC_VER 192x, Visual Studio Product Visual Studio 2019, MSBuild / Visual Studio 16.x, 16.1x
"14.1" — Visual C++ Version 14.1 or 14.1x, _MSVC_VER 191x, Visual Studio Product Visual Studio 2017, MSBuild / Visual Studio 15.x
"14.1Exp" — Visual C++ Version 14.1 or 14.1x, _MSVC_VER 191x, Visual Studio Product Visual Studio 2017 Express, MSBuild / Visual Studio 15.x 🎀
"14.0" — Visual C++ Version 14.0, _MSVC_VER 1900, Visual Studio Product Visual Studio 2015, MSBuild / Visual Studio 14.0
"14.0Exp" — Visual C++ Version 14.0, _MSVC_VER 1900, Visual Studio Product Visual Studio 2015 Express, MSBuild / Visual Studio 14.0
"12.0" — Visual C++ Version 12.0, _MSVC_VER 1800, Visual Studio Product Visual Studio 2013, MSBuild / Visual Studio 12.0
"12.0Exp" — Visual C++ Version 12.0, _MSVC_VER 1800, Visual Studio Product Visual Studio 2013 Express, MSBuild / Visual Studio 12.0
"11.0" — Visual C++ Version 11.0, _MSVC_VER 1700, Visual Studio Product Visual Studio 2012, MSBuild / Visual Studio 11.0 🦋
"11.0Exp" — Visual C++ Version 11.0, _MSVC_VER 1700, Visual Studio Product Visual Studio 2012 Express, MSBuild / Visual Studio 11.0
"10.0" — Visual C++ Version 10.0, _MSVC_VER 1600, Visual Studio Product Visual Studio 2010, MSBuild / Visual Studio 10.0
"10.0Exp" — Visual C++ Version 10.0, _MSVC_VER 1600, Visual Studio Product Visual C++ Express 2010, MSBuild / Visual Studio 10.0
"9.0" — Visual C++ Version 9.0, _MSVC_VER 1500, Visual Studio Product Visual Studio 2008, MSBuild / Visual Studio 9.0
"9.0Exp" — Visual C++ Version 9.0, _MSVC_VER 1500, Visual Studio Product Visual C++ Express 2008, MSBuild / Visual Studio 9.0 🌸
"8.0" — Visual C++ Version 8.0, _MSVC_VER 1400, Visual Studio Product Visual Studio 2005, MSBuild / Visual Studio 8.0
"8.0Exp" — Visual C++ Version 8.0, _MSVC_VER 1400, Visual Studio Product Visual C++ Express 2005, MSBuild / Visual Studio 8.0
"7.1" — Visual C++ Version 7.1, _MSVC_VER 1300, Visual Studio Product Visual Studio .NET 2003, MSBuild / Visual Studio 7.1
"7.0" — Visual C++ Version 7.0, _MSVC_VER 1200, Visual Studio Product Visual Studio .NET 2002, MSBuild / Visual Studio 7.0
"6.0" — Visual C++ Version 6.0, _MSVC_VER 1100, Visual Studio Product Visual Studio 6.0, MSBuild / Visual Studio 6.0 💅

Twenty entries, zero gaps — this is literally the whole mapping, bestie, so you can look up exactly which key maps to which _MSVC_VER value and which MSBuild / Visual Studio version lines up with it. Screenshot it, bookmark it, whatever, it's yours now 🫶

└───────────┴───────────────────────────┴───────────┴───────────────┴──────────────────────────────┘

...and that's the table wrapping up bestie, we're free 💅✨

Note — two things you genuinely need to know:

It is not necessary to install a Visual Studio IDE to build with SCons (for example, you can install only Build Tools) — but when a Visual Studio IDE is installed, additional builders such as MSVSSolution and MSVSProject become available, and they correspond to the specified versions.
Versions ending in Exp refer to the historical "Express" or "Express for Desktop" Visual Studio editions, which had feature limitations compared to the full editions. It is only necessary to specify the Exp suffix to select the express edition when both express and non-express editions of the same product are installed simultaneously. The Exp suffix is unnecessary, but accepted, when only the express edition is installed.

The compilation environment can be further or more precisely specified through the use of several other construction variables: see the descriptions of $MSVC_TOOLSET_VERSION, $MSVC_SDK_VERSION, $MSVC_USE_SCRIPT, $MSVC_USE_SCRIPT_ARGS, and $MSVC_USE_SETTINGS. 🫶

👑 `MSVS`

When the Microsoft Visual Studio tools are initialized, they set up this dictionary with the following keys:

VERSION — the version of MSVS being used (can be set via $MSVC_VERSION)
VERSIONS — the available versions of MSVS installed
VCINSTALLDIR — installed directory of Microsoft Visual C++
VSINSTALLDIR — installed directory of Visual Studio
FRAMEWORKDIR — installed directory of the .NET framework
FRAMEWORKVERSIONS — list of installed versions of the .NET framework, sorted latest to oldest.
FRAMEWORKVERSION — latest installed version of the .NET framework
FRAMEWORKSDKDIR — installed location of the .NET SDK.
PLATFORMSDKDIR — installed location of the Platform SDK.
PLATFORMSDK_MODULES — dictionary of installed Platform SDK modules, where the dictionary keys are keywords for the various modules, and the values are 2-tuples where the first is the release date, and the second is the version number.

If a value is not set, it was not available in the registry. Visual Studio 2017 and later do not use the registry for primary storage of this information, so typically for these versions only PROJECTSUFFIX and SOLUTIONSUFFIX will be set. 😭 (rip registry, you served us well)

🌈 `MSVS_ARCH`

Sets the architecture for which the generated project(s) should build. 🏗️

The default value is x86. amd64 is also supported by SCons for most Visual Studio versions. Since Visual Studio 2015 arm is supported, and since Visual Studio 2017 arm64 is supported. Trying to set $MSVS_ARCH to an architecture that's not supported for a given Visual Studio version will generate an error. 🚨

🎀 `MSVS_PROJECT_GUID`

The string placed in a generated Microsoft Visual C++ project file as the value of the ProjectGUID attribute. There is no default value. If not defined, a new GUID is generated. ✨

🦋 `MSVS_SCC_AUX_PATH`

The path name placed in a generated Microsoft Visual C++ project file as the value of the SccAuxPath attribute if the MSVS_SCC_PROVIDER construction variable is also set. There is no default value.

💜 `MSVS_SCC_CONNECTION_ROOT`

The root path of projects in your SCC workspace, i.e the path under which all project and solution files will be generated. It is used as a reference path from which the relative paths of the generated Microsoft Visual C++ project and solution files are computed. The relative project file path is placed as the value of the SccLocalPath attribute of the project file and as the values of the SccProjectFilePathRelativizedFromConnection[i] (where [i] ranges from 0 to the number of projects in the solution) attributes of the GlobalSection(SourceCodeControl) section of the Microsoft Visual Studio solution file. Similarly, the relative solution file path is placed as the values of the SccLocalPath[i] (where [i] ranges from 0 to the number of projects in the solution) attributes of the GlobalSection(SourceCodeControl) section of the Microsoft Visual Studio solution file. This is used only if the MSVS_SCC_PROVIDER construction variable is also set. The default value is the current working directory. 🫡

🌸 `MSVS_SCC_PROJECT_NAME`

The project name placed in a generated Microsoft Visual C++ project file as the value of the SccProjectName attribute if the MSVS_SCC_PROVIDER construction variable is also set. In this case the string is also placed in the SccProjectName0 attribute of the GlobalSection(SourceCodeControl) section of the Microsoft Visual Studio solution file. There is no default value.

⭐ `MSVS_SCC_PROVIDER`

The string placed in a generated Microsoft Visual C++ project file as the value of the SccProvider attribute. The string is also placed in the SccProvider0 attribute of the GlobalSection(SourceCodeControl) section of the Microsoft Visual Studio solution file. There is no default value.

🔥 `MSVS_VERSION`

Set the preferred version of Microsoft Visual Studio to use. 👑

If $MSVS_VERSION is not set, SCons will (by default) select the latest version of Visual Studio installed on your system. So, if you have version 6 and version 7 (MSVS .NET) installed, it will prefer version 7. You can override this by specifying the $MSVS_VERSION variable when initializing the Environment, setting it to the appropriate version ('6.0' or '7.0', for example). If the specified version isn't installed, tool initialization will fail. 💀

Deprecated since 1.3.0: $MSVS_VERSION is deprecated in favor of $MSVC_VERSION. As a transitional aid, if $MSVS_VERSION is set and $MSVC_VERSION is not, $MSVC_VERSION will be initialized to the value of $MSVS_VERSION. An error is raised if both are set and have different values. 🚨

🎀 `MSVSBUILDCOM`

The build command line placed in a generated Microsoft Visual C++ project file. The default is to have Visual Studio invoke SCons with any specified build targets.

🧚 `MSVSCLEANCOM`

The clean command line placed in a generated Microsoft Visual C++ project file. The default is to have Visual Studio invoke SCons with the -c option to remove any specified targets. 🧹

💅 `MSVSENCODING`

The encoding string placed in a generated Microsoft Visual C++ project file. The default is encoding Windows-1252.

🌈 `MSVSPROJECTCOM`

The action used to generate Microsoft Visual C++ project files.

🦋 `MSVSPROJECTSUFFIX`

The suffix used for Microsoft Visual C++ project (DSP) files. The default value is .vcxproj when using Visual Studio 2010 and later, .vcproj when using Visual Studio versions between 2002 and 2008, and .dsp when using Visual Studio 6.0.

⭐ `MSVSREBUILDCOM`

The rebuild command line placed in a generated Microsoft Visual C++ project file. The default is to have Visual Studio invoke SCons with any specified rebuild targets.

🌸 `MSVSSCONS`

The SCons used in generated Microsoft Visual C++ project files. The default is the version of SCons being used to generate the project file.

💜 `MSVSSCONSCOM`

The default SCons command used in generated Microsoft Visual C++ project files.

🫶 `MSVSSCONSCRIPT`

The sconscript file (that is, SConstruct or SConscript file) that will be invoked by Microsoft Visual C++ project files (through the $MSVSSCONSCOM variable). The default is the same sconscript file that contains the call to MSVSProject to build the project file.

✨ `MSVSSCONSFLAGS`

The SCons flags used in generated Microsoft Visual C++ project files.

🎀 `MSVSSOLUTIONCOM`

The action used to generate Microsoft Visual Studio solution files.

🦋 `MSVSSOLUTIONSUFFIX`

The suffix used for Microsoft Visual Studio solution (DSW) files. The default value is .sln when using Visual Studio version 7.x (.NET 2002) and later, and .dsw when using Visual Studio 6.0.

🔥 `MT`

The program used on Windows systems to embed manifests into DLLs and EXEs. See also $WINDOWS_EMBED_MANIFEST.

⭐ `MTEXECOM`

The Windows command line used to embed manifests into executables. See also $MTSHLIBCOM.

🌈 `MTFLAGS`

Flags passed to the $MT manifest embedding program (Windows only).

🌸 `MTSHLIBCOM`

The Windows command line used to embed manifests into shared libraries (DLLs). See also $MTEXECOM.

💜 `MWCW_VERSION`

The version number of the MetroWerks CodeWarrior C compiler to be used.

🧚 `MWCW_VERSIONS`

A list of installed versions of the MetroWerks CodeWarrior C compiler on this system.

💅 `NAME`

Specifies the name of the project to package.

See the Package builder.

🎀 `NINJA_ALIAS_NAME`

The name of the alias target which will cause SCons to create the ninja build file, and then (optionally) run ninja. The default value is generate-ninja.

🌈 `NINJA_CMD_ARGS`

A string which will pass arguments through SCons to the ninja command when scons executes ninja. Has no effect if $NINJA_DISABLE_AUTO_RUN is set.

This value can also be passed on the command line:

scons NINJA_CMD_ARGS=-v
or
scons NINJA_CMD_ARGS="-v -j 3"

🦋 `NINJA_COMPDB_EXPAND`

Boolean value to instruct ninja to expand the command line arguments normally put into response files. If true, prevents unexpanded lines in the compilation database like "gcc @rsp_file" and instead yields expanded lines like "gcc -c -o myfile.o myfile.c -Ia -DXYZ".

Ninja's compdb tool added the -x flag in Ninja V1.9.0. 👑

⭐ `NINJA_DEPFILE_PARSE_FORMAT`

Determines the type of format ninja should expect when parsing header include depfiles. Can be msvc, gcc, or clang. The msvc option corresponds to /showIncludes format, and gcc or clang correspond to -MMD -MF.

🌸 `NINJA_DIR`

The builddir value. Propagates directly into the generated ninja build file. From Ninja's docs: " A directory for some Ninja output files. ... (You can also store other build output in this directory.) " The default value is .ninja. 🥷

NINJA_DISABLE_AUTO_RUN — Boolean, default False. If you set it true, SCons will not auto-run ninja after it makes the ninja build file for you. Lowkey a "chill, I'll drive" setting.

If you don't explicitly set it, it'll get set to True for you if --disable_execute_ninja or SetOption('disable_execute_ninja', True) shows up. 👑

NINJA_ENV_VAR_CACHE — A string that sets the environment for any environment variables that differ between the OS environment and the SCons execution environment.

It's compatible with the default shell of the operating system. 🐚

If you don't set it explicitly, SCons generates it on the fly from the execution environment stored in the current construction environment (like env['ENV']), specifically where those values differ from the existing shell.

NINJA_FILE_NAME — The filename for the generated Ninja build file. Default is ninja.build. 🥷
NINJA_FORCE_SCONS_BUILD — If true, it makes the build nodes call back to scons instead of using ninja to build them. It's meant to be passed to the environment on the builder invocation. Super useful when you've got a build node doing something that just does not translate into ninja. 💅
NINJA_GENERATED_SOURCE_ALIAS_NAME — A string matching the name of a user-defined alias that represents a list of all generated sources. This stops the auto-detection of generated sources from $NINJA_GENERATED_SOURCE_SUFFIXES. Then all the other source files get made to depend on this in the ninja build file, which forces the generated sources to be built first. ✨
NINJA_GENERATED_SOURCE_SUFFIXES — The list of source file suffixes that are generated by SCons build steps. Every source file matching these suffixes gets added to the _generated_sources alias in the output ninja build file. Then all other source files get made to depend on this in the ninja build file, forcing the generated sources to build first. 🎀
NINJA_MSVC_DEPS_PREFIX — The msvc_deps_prefix string. It propagates directly into the generated ninja build file. Straight from Ninja's docs: it "defines the string which should be stripped from msvc's /showIncludes output". 📎
NINJA_POOL — Sets the ninja_pool for this target, or for all targets in scope, for this env var.
NINJA_REGENERATE_DEPS — A generator function used to create a ninja depfile which includes all the files that would require SCons to be invoked if they change. Or, like, just a list of said files. 🗒️
_NINJA_REGENERATE_DEPS_FUNC — Internal value used to specify the function to call with argument env to generate the list of files which, if changed, would require the ninja build file to be regenerated.
NINJA_SCONS_DAEMON_KEEP_ALIVE — The number of seconds for the SCons daemon launched by ninja to stay alive. (Default: 180000) 🫶
NINJA_SCONS_DAEMON_PORT — The TCP/IP port for the SCons daemon to listen on. NOTE: you cannot use a port that's already being listened to on your build machine. (Default: random number between 10000,60000) 🎲
NINJA_SYNTAX — The path to a custom ninja_syntax.py file used in generation. The tool currently assumes you have ninja installed as a Python module and grabs the syntax file from that installation if $NINJA_SYNTAX isn't explicitly set.
no_import_lib — When set to non-zero, suppresses creation of a corresponding Windows static import lib by the SharedLibrary builder when used with MinGW, Microsoft Visual Studio or Metrowerks. This also suppresses creation of an export (.exp) file when using Microsoft Visual Studio. 🚫
OBJPREFIX — The prefix used for (static) object file names.
OBJSUFFIX — The suffix used for (static) object file names.
PACKAGEROOT — Specifies the directory where all files in the resulting archive will be placed, if applicable. The default value is "$NAME-$VERSION". 📦

See the Package builder.

PACKAGETYPE — Selects the package type to build when using the Package builder. It can be a string or a list of strings. See the documentation for the builder for the currently supported types.

$PACKAGETYPE can be overridden with the --package-type command line option.

See the Package builder.

PACKAGEVERSION — The version of the package (not the underlying project). This is currently only used by the rpm packager, and it should reflect changes in the packaging, not the underlying project code itself.

See the Package builder.

PCH — A node for the Microsoft Visual C++ precompiled header that gets used when compiling object files. This variable is ignored by tools other than Microsoft Visual C++. When it's defined, SCons adds options to the compiler command line to make it use the precompiled header, and also sets up the dependencies for the PCH file. Examples:

env['PCH'] = File('StdAfx.pch')
env['PCH'] = env.PCH('pch.cc')[0]

PCHCOM — The command line used by the PCH builder to generate a precompiled header.
PCHCOMSTR — The string displayed when generating a precompiled header. If it's not set, then $PCHCOM (the command line) is displayed.
PCHPDBFLAGS — A construction variable that, when expanded, adds the /yD flag to the command line only if the $PDB construction variable is set. 🧠
PCHSTOP — This variable specifies how much of a source file is precompiled. It's ignored by tools other than Microsoft Visual C++, or when the PCH variable isn't being used. When this variable is defined, it must be a string that's the name of the header included at the end of the precompiled portion of the source files — or the empty string if the "#pragma hrdstop" construct is being used:

env['PCHSTOP'] = 'StdAfx.h'

PDB — The Microsoft Visual C++ PDB file that stores debugging information for object files, shared libraries, and programs. This variable is ignored by tools other than Microsoft Visual C++. When it's defined, SCons adds options to the compiler and linker command line to make them generate external debugging information, and also sets up the dependencies for the PDB file. Example:

env['PDB'] = 'hello.pdb'

The Microsoft Visual C++ compiler switch SCons uses by default to generate PDB info is /Z7. This works correctly with parallel (-j) builds because it embeds the debug information in the intermediate object files, instead of sharing a single PDB file between multiple object files. It's also the only way to get debug information embedded into a static library. Using /Zi instead may give you improved link-time performance, though parallel builds will no longer work. You can generate PDB files with the /Zi switch by overriding the default $CCPDBFLAGS variable — see that variable's entry for specific examples. 💀

PDFLATEX — The pdflatex utility.
PDFLATEXCOM — The command line used to call the pdflatex utility.
PDFLATEXCOMSTR — The string displayed when calling the pdflatex utility. If this isn't set, then $PDFLATEXCOM (the command line) is displayed.

env = Environment(PDFLATEX;COMSTR = "Building $TARGET from LaTeX input $SOURCES")

PDFLATEXFLAGS — General options passed to the pdflatex utility.
PDFPREFIX — The prefix used for PDF file names.
PDFSUFFIX — The suffix used for PDF file names.
PDFTEX — The pdftex utility.
PDFTEXCOM — The command line used to call the pdftex utility.
PDFTEXCOMSTR — The string displayed when calling the pdftex utility. If this isn't set, then $PDFTEXCOM (the command line) is displayed.

env = Environment(PDFTEXCOMSTR = "Building $TARGET from TeX input $SOURCES")

PDFTEXFLAGS — General options passed to the pdftex utility.
PKGCHK — On Solaris systems, the package-checking program that gets used (along with $PKGINFO) to look for installed versions of the Sun PRO C++ compiler. The default is /usr/sbin/pgkchk. 🌞
PKGINFO — On Solaris systems, the package information program that gets used (along with $PKGCHK) to look for installed versions of the Sun PRO C++ compiler. The default is pkginfo.
PLATFORM — The name of the platform used to create this construction environment. SCons sets this when initializing the platform, which by default is auto-detected (see the platform argument to Environment). 🖥️

env = Environment(tools=[])
if env['PLATFORM'] == 'cygwin':
    Tool('mingw')(env)
else:
    Tool('msvc')(env)

POAUTOINIT — The $POAUTOINIT variable, if set to True (or a non-zero numeric value), lets the msginit tool automatically initialize missing PO files with msginit(1). This applies to both the POInit and POUpdate builders (and others that use either of them).
POCREATE_ALIAS — Common alias for all PO files created with the POInit builder (default: 'po-create'). See the msginit tool and POInit builder. 💖
POSUFFIX — Suffix used for PO files (default: '.po'). See the msginit tool and POInit builder.
POTDOMAIN — The $POTDOMAIN defines the default domain, used to generate the POT filename as $POTDOMAIN.pot when no POT file name is provided by the user. This applies to the POTUpdate, POInit and POUpdate builders (and builders that use them, e.g. Translate). Normally, if $POTDOMAIN isn't defined, the builders use messages.pot as the default POT file name.
POTSUFFIX — Suffix used for PO Template files (default: '.pot'). See the xgettext tool and POTUpdate builder.
POTUPDATE_ALIAS — Name of the common phony target for all PO Templates created with POUpdate (default: 'pot-update'). See the xgettext tool and POTUpdate builder.
POUPDATE_ALIAS — Common alias for all PO files being defined with the POUpdate builder (default: 'po-update'). See the msgmerge tool and POUpdate builder.
PRINT_CMD_LINE_FUNC — The function to print command lines as they're executed. It gets called unless command printing is disabled by the -q/--question or -s/--silent options. The function is called with four arguments: s, target, source and env. s is the command line string to be executed, target is the target(s) being built, source is the source(s) used, and env is the environment being used. 📢

Any or all of the arguments can be used in composing the message. source and target will be lists of nodes, and need to be suitably converted for printing (see example). The default, used if the variable is not set or set to None, is to print only the string s, equivalent to:

def print_cmd_line(s, target, source, env):
    sys.stdout.write(s + "\n")

This example uses the source and target parameters to format a custom message:

def print_cmd_line(s, target, source, env):
    sys.stdout.write(
        "Building %s -> %s...\n"
        % (
            ' and '.join([str(x) for x in source]),
            ' and '.join([str(x) for x in target]),
        )
    )

env = Environment(PRINT_CMD_LINE_FUNC=print_cmd_line)
env.Program('foo', ['foo.c', 'bar.c'])

This prints:

...
scons: Building targets ...
Building bar.c -> bar.o...
Building foo.c -> foo.o...
Building foo.o and bar.o -> foo...
scons: done building targets.

Another possible use for a print function is to show a very brief message on the console while logging the full command line to a file.

PROGEMITTER — holds the emitter spec for the Program builder 💫. The manpage section "Builder Objects" has the whole rundown on how to specify emitters.
PROGPREFIX — the prefix used for executable file names.
PROGSUFFIX — the suffix used for executable file names.
PSCOM — the command line that turns TeX DVI files into a PostScript file 🎀.
PSCOMSTR — the string shown when a TeX DVI file gets converted into a PostScript file. If you don't set it, then $PSCOM (the command line) is what gets displayed.
PSPREFIX — the prefix used for PostScript file names.
PSSUFFIX — the prefix used for PostScript file names. (yes bestie, the manpage really does say prefix here, we are simply not touching it 🙈)
RANLIB — the archive indexer.
RANLIBCOM — the command line used to index a static library archive.
RANLIBCOMSTR — the string shown when a static library archive gets indexed. If it's not set, then $RANLIBCOM (the command line) is displayed.

env = Environment(RANLIBCOMSTR = "Indexing $TARGET")

RANLIBFLAGS — general options passed to the archive indexer.
RC — the resource compiler used to build a Microsoft Visual C++ resource file.
RCCOM — the command line used to build a Microsoft Visual C++ resource file.
RCCOMSTR — the string shown when invoking the resource compiler to build a Microsoft Visual C++ resource file. If it's not set, then $RCCOM (the command line) is displayed.
RCFLAGS — the flags passed to the resource compiler by the RES builder.
RCINCFLAGS — an automatically-generated construction variable holding the command-line options that specify directories for the resource compiler to search 🔍. The value of $RCINCFLAGS gets built by prepending $RCINCPREFIX and appending $RCINCSUFFIX to the start and end of each directory in $CPPPATH.
RCINCPREFIX — the prefix (flag) used to specify an include directory on the resource compiler command line. This gets prepended to the start of each directory in the $CPPPATH construction variable when $RCINCFLAGS is expanded.
RCINCSUFFIX — the suffix used to specify an include directory on the resource compiler command line. This gets appended to the end of each directory in the $CPPPATH construction variable when $RCINCFLAGS is expanded.
RDirs — a function that converts a string into a list of Dir instances by searching the repositories 🧚.
REGSVR — the program used on Windows systems to register a newly-built DLL library whenever the SharedLibrary builder is passed a keyword argument of register=True.
REGSVRCOM — the command line used on Windows systems to register a newly-built DLL library whenever the SharedLibrary builder is passed a keyword argument of register=True.
REGSVRCOMSTR — the string shown when registering a newly-built DLL file. If it's not set, then $REGSVRCOM (the command line) is displayed.
REGSVRFLAGS — flags passed to the DLL registration program on Windows systems when a newly-built DLL library gets registered. By default this includes the /s that stops dialog boxes from popping up and demanding user attention 🫶.
RMIC — the Java RMI stub compiler.
RMICCOM — the command line used to compile stub and skeleton class files from Java classes that contain RMI implementations. Any options specified in the $RMICFLAGS construction variable are included on this command line.
RMICCOMSTR — the string shown when compiling stub and skeleton class files from Java classes that contain RMI implementations. If it's not set, then $RMICCOM (the command line) is displayed.

env = Environment(
    RMICCOMSTR="Generating stub/skeleton class files $TARGETS from $SOURCES"
)

RMICFLAGS — general options passed to the Java RMI stub compiler.
RPATH — a list of paths to search for shared libraries when running programs 🔥. Currently it's only used in the GNU (gnulink), IRIX (sgilink) and Sun (sunlink) linkers. It's ignored on platforms and toolchains that don't support it. Heads up: the paths you add to RPATH are not transformed by scons in any way — if you want an absolute path, you have to make it absolute yourself.
_RPATH — an automatically-generated construction variable holding the rpath flags to use when linking a program with shared libraries. The value of $_RPATH gets built by prepending $RPATHPREFIX and appending $RPATHSUFFIX to the start and end of each directory in $RPATH.
RPATHPREFIX — the prefix used to specify a directory to be searched for shared libraries when running programs. This gets prepended to the start of each directory in the $RPATH construction variable when the $_RPATH variable is automatically generated.
RPATHSUFFIX — the suffix used to specify a directory to be searched for shared libraries when running programs. This gets appended to the end of each directory in the $RPATH construction variable when the $_RPATH variable is automatically generated.
RPCGEN — the RPC protocol compiler.
RPCGENCLIENTFLAGS — options passed to the RPC protocol compiler when generating client side stubs. These are in addition to any flags specified in the $RPCGENFLAGS construction variable.
RPCGENFLAGS — general options passed to the RPC protocol compiler.
RPCGENHEADERFLAGS — options passed to the RPC protocol compiler when generating a header file. These are in addition to any flags specified in the $RPCGENFLAGS construction variable.
RPCGENSERVICEFLAGS — options passed to the RPC protocol compiler when generating server side stubs. These are in addition to any flags specified in the $RPCGENFLAGS construction variable.
RPCGENXDRFLAGS — options passed to the RPC protocol compiler when generating XDR routines. These are in addition to any flags specified in the $RPCGENFLAGS construction variable.
SCANNERS — a list of the available implicit dependency scanners 👑. You can add new file scanners by appending to this list, though the more flexible glow-up approach is to associate scanners with a specific Builder. Peep the manpage sections "Builder Objects" and "Scanner Objects" for more.
SCONS_HOME — the (optional) path to the SCons library directory, initialized from the external environment. If it's set, it's used to construct a shorter and more efficient search path in the $MSVSSCONS command line executed from C++ project files ✨.
SHCC — the C compiler used for generating shared-library objects. See also $CC for compiling to static objects.
SHCCCOM — the command line used to compile a C source file to a shared-library object file. Any options specified in the $SHCFLAGS, $SHCCFLAGS and $CPPFLAGS construction variables are included on this command line. See also $CCCOM for compiling to static objects.
SHCCCOMSTR — if set, the string shown when a C source file is compiled to a shared object file. If it's not set, then $SHCCCOM (the command line) is displayed. See also $CCCOMSTR for compiling to static objects.

env = Environment(SHCCCOMSTR = "Compiling shared object $TARGET")

SHCCFLAGS — options passed to the C and C++ compilers to generate shared-library objects. See also $CCFLAGS for compiling to static objects.
SHCFLAGS — options passed to the C compiler (only; not C++) to generate shared-library objects. See also $CFLAGS for compiling to static objects.
SHCXX — the C++ compiler used for generating shared-library objects. See also $CXX for compiling to static objects.
SHCXXCOM — the command line used to compile a C++ source file to a shared-library object file. Any options specified in the $SHCXXFLAGS and $CPPFLAGS construction variables are included on this command line. See also $CXXCOM for compiling to static objects.
SHCXXCOMSTR — if set, the string shown when a C++ source file is compiled to a shared object file. If it's not set, then $SHCXXCOM (the command line) is displayed. See also $CXXCOMSTR for compiling to static objects.

env = Environment(SHCXXCOMSTR = "Compiling shared object $TARGET")

SHCXXFLAGS — options passed to the C++ compiler to generate shared-library objects. See also $CXXFLAGS for compiling to static objects.
SHDC — the name of the compiler to use when compiling D source destined to be in a shared object. See also $DC for compiling to static objects 🌸.
SHDCOM — the command line to use when compiling code to be part of shared objects. See also $DCOM for compiling to static objects.
SHDCOMSTR — if set, the string shown when a D source file is compiled to a (shared) object file. If it's not set, then $SHDCOM (the command line) is displayed. See also $DCOMSTR for compiling to static objects.
SHDLIBVERSIONFLAGS — extra flags added to $SHDLINKCOM when building a versioned SharedLibrary. These flags are only used when $SHLIBVERSION is set 💅.

SHDLINK

The linker bestie you call when you're turning dlang code into shared objects. Also peek at $DLINK if you're doing static objects instead, iykyk. 💅

SHDLINKCOM

The actual command line that generates those shared objects. And yep, $DLINKCOM is the one for linking static objects. ✨

SHDLINKFLAGS

The flags you hand over when generating a shared object for the D language. $DLINKFLAGS is the matching vibe for static objects, bestie. 🎀

SHELL

A string naming the shell program that gets passed to the $SPAWN function. Want the tea on this one? Go read the $SPAWN construction variable. 🦋

SHELL_ENV_GENERATORS

OK this one is a hook, and it's giving main character energy fr fr. It lets you mod the execution environment before a command line from an action actually runs, via the spawner function that $SPAWN defines. So you can do substitution based on targets and sources, pull values from the construction environment, sneak in extra environment variables, all of it. 💖

The value has to be a list (or any other iterable) of functions, and each one generates or alters the execution environment dictionary. Here's the flow, no cap:

The first function gets handed a copy of the initial execution environment ($ENV in the current construction environment).
The dictionary it returns gets passed to the next function.
That keeps going until the iterable is exhausted, and the final result gets returned for the command spawner to use.

And the original execution environment? Not modified. Untouched. Iconic behavior honestly. 👑

Every single function you put in $SHELL_ENV_GENERATORS has to accept four arguments and return a dictionary:

env — the construction environment for this action
target — the list of targets associated with this action
source — the list of sources associated with this action
shell_env — the current dictionary after iterating any previous $SHELL_ENV_GENERATORS functions. You can compare this to the original execution environment, available as env['ENV'], to detect any changes. 🔍

Example, because a vibe check with code hits different:

def custom_shell_env(env, target, source, shell_env):
    """customize shell_env if desired"""
    if str(target[0]) == 'special_target':
        shell_env['SPECIAL_VAR'] = env.subst('SOME_VAR', target=target, source=source)
    return shell_env

env["SHELL_ENV_GENERATORS"] = [custom_shell_env]

Available since 4.4, so if you're on an older version this whole thing is not it. 😭

SHF03

The Fortran 03 compiler used for generating shared-library objects. Normally you'd just set $SHFORTRAN, which is the default Fortran compiler for all Fortran versions. You only bother with $SHF03 if you specifically need a particular compiler or compiler version for Fortran 03 files. Periodt. 💅

SHF03COM

The command line that compiles a Fortran 03 source file into a shared-library object file. Only set $SHF03COM if you need a specific command line just for Fortran 03 files. Otherwise set $SHFORTRANCOM, which is the default command line for all Fortran versions. 🌸

SHF03COMSTR

If you set it, this is the string displayed when a Fortran 03 source file gets compiled to a shared-library object file. If you don't set it, then $SHF03COM or $SHFORTRANCOM (the command line itself) gets displayed instead. ✨

SHF03FLAGS

Options passed to the Fortran 03 compiler to generated shared-library objects. Only set $SHF03FLAGS if you need specific user options for Fortran 03 files. Normally you set $FORTRANCOMMONFLAGS, which is the user-specified options passed to the default Fortran compiler for all Fortran versions. 🦋

SHF03PPCOM

The command line that compiles a Fortran 03 source file to a shared-library object file after first running the file through the C preprocessor. Any options in $SHF03FLAGS and $CPPFLAGS get included on this command line too. Only set $SHF03PPCOM if you need a specific C-preprocessor command line for Fortran 03 files. Normally: $SHFORTRANPPCOM, the default C-preprocessor command line for all Fortran versions. 🔥

SHF03PPCOMSTR

If set, the string displayed when a Fortran 03 source file is compiled to a shared-library object file after first running the file through the C preprocessor. If not set, then $SHF03PPCOM or $SHFORTRANPPCOM (the command line) gets displayed. 💜

SHF08

The Fortran 08 compiler used for generating shared-library objects. Normally set $SHFORTRAN — the default Fortran compiler for all Fortran versions. You only need $SHF08 when you require a specific compiler or compiler version for Fortran 08 files. 👑

SHF08COM

The command line used to compile a Fortran 08 source file to a shared-library object file. Only set $SHF08COM if you need a specific command line for Fortran 08 files. Normally it's $SHFORTRANCOM, the default command line for all Fortran versions. 🍓

SHF08COMSTR

If set, the string displayed when a Fortran 08 source file is compiled to a shared-library object file. If not set, then $SHF08COM or $SHFORTRANCOM (the command line) shows up instead. ✨

SHF08FLAGS

Options passed to the Fortran 08 compiler to generated shared-library objects. Only set $SHF08FLAGS if you need specific user options for Fortran 08 files. Otherwise set $FORTRANCOMMONFLAGS, the user-specified options passed to the default Fortran compiler for all Fortran versions. 🌈

SHF08PPCOM

The command line used to compile a Fortran 08 source file to a shared-library object file after first running the file through the C preprocessor. Any options in $SHF08FLAGS and $CPPFLAGS are included on this command line. Only set $SHF08PPCOM if you need a specific C-preprocessor command line for Fortran 08 files. Normally: $SHFORTRANPPCOM — the default C-preprocessor command line for all Fortran versions. 💅

SHF08PPCOMSTR

If set, the string displayed when a Fortran 08 source file is compiled to a shared-library object file after first running the file through the C preprocessor. If not set, then $SHF08PPCOM or $SHFORTRANPPCOM (the command line) is what's shown. 💖

SHF77

The Fortran 77 compiler used for generating shared-library objects. You should normally set $SHFORTRAN, which specifies the default Fortran compiler for all Fortran versions. You only need $SHF77 if you need a specific compiler or compiler version for Fortran 77 files. 🎀

SHF77COM

The command line used to compile a Fortran 77 source file to a shared-library object file. Only set $SHF77COM if you need a specific command line for Fortran 77 files. Normally set $SHFORTRANCOM, the default command line for all Fortran versions. 🦋

SHF77COMSTR

If set, the string displayed when a Fortran 77 source file is compiled to a shared-library object file. If not set, then $SHF77COM or $SHFORTRANCOM (the command line) is displayed. ⭐

SHF77FLAGS

Options that are passed to the Fortran 77 compiler to generated shared-library objects. Only set $SHF77FLAGS if you need to define specific user options for Fortran 77 files. Normally it's $FORTRANCOMMONFLAGS — the user-specified options passed to the default Fortran compiler for all Fortran versions. 💜

SHF77PPCOM

The command line used to compile a Fortran 77 source file to a shared-library object file after first running the file through the C preprocessor. Any options specified in $SHF77FLAGS and $CPPFLAGS are included on this command line. Only set $SHF77PPCOM if you need a specific C-preprocessor command line for Fortran 77 files. Normally: $SHFORTRANPPCOM, the default C-preprocessor command line for all Fortran versions. 🔥

SHF77PPCOMSTR

If set, the string displayed when a Fortran 77 source file is compiled to a shared-library object file after first running the file through the C preprocessor. If not set, then $SHF77PPCOM or $SHFORTRANPPCOM (the command line) is displayed. 🌸

SHF90

The Fortran 90 compiler used for generating shared-library objects. Normally set $SHFORTRAN, which specifies the default Fortran compiler for all Fortran versions. You only need $SHF90 if you need a specific compiler or compiler version for Fortran 90 files. 👑

SHF90COM

The command line used to compile a Fortran 90 source file to a shared-library object file. Only set $SHF90COM if you need a specific command line for Fortran 90 files. Normally set $SHFORTRANCOM, which specifies the default command line for all Fortran versions. 🫶

SHF90COMSTR

If set, the string displayed when a Fortran 90 source file is compiled to a shared-library object file. If not set, then $SHF90COM or $SHFORTRANCOM (the command line) is displayed. ✨

SHF90FLAGS

Options that are passed to the Fortran 90 compiler to generated shared-library objects. Only set $SHF90FLAGS if you need to define specific user options for Fortran 90 files. Normally you set $FORTRANCOMMONFLAGS, which specifies the user-specified options passed to the default Fortran compiler for all Fortran versions. 💅

SHF90PPCOM

The command line used to compile a Fortran 90 source file to a shared-library object file after first running the file through the C preprocessor. Any options specified in $SHF90FLAGS and $CPPFLAGS construction variables are included on this command line. Only set $SHF90PPCOM if you need to use a specific C-preprocessor command line for Fortran 90 files. Normally set $SHFORTRANPPCOM, which specifies the default C-preprocessor command line for all Fortran versions. 💜

SHF90PPCOMSTR

If set, the string displayed when a Fortran 90 source file is compiled to a shared-library object file after first running the file through the C preprocessor. If not set, then $SHF90PPCOM or $SHFORTRANPPCOM (the command line) is displayed. 🦋

SHF95 — the Fortran 95 compiler that makes your shared-library objects. ✨ ngl you should be setting $SHFORTRAN instead, because that one sets the default Fortran compiler for every Fortran version. Only bother with $SHF95 when you truly need one specific compiler or compiler version just for Fortran 95 files. 💅
SHF95COM — the command line that compiles a Fortran 95 source file into a shared-library object file. Again, only set $SHF95COM if you need a special command line for Fortran 95 files specifically. Normally you're setting $SHFORTRANCOM, bestie — that's the default command line for all Fortran versions. 🫶
SHF95COMSTR — if you set this, it's the string that gets displayed when a Fortran 95 source file is compiled to a shared-library object file. If you don't set it? Then $SHF95COM or $SHFORTRANCOM (aka the command line) gets shown instead. 🎀
SHF95FLAGS — options passed to the Fortran 95 compiler for generating shared-library objects. Only needed if you want specific user options for Fortran 95 files specifically. Normally you'd set $FORTRANCOMMONFLAGS, which is the user-specified options passed to the default Fortran compiler for all Fortran versions. lowkey cleaner that way. 💖
SHF95PPCOM — the command line that compiles a Fortran 95 source file to a shared-library object file, after first running that file through the C preprocessor. Any options in $SHF95FLAGS and $CPPFLAGS get included on this command line. Only set $SHF95PPCOM if you need a specific C-preprocessor command line for Fortran 95 files. Normally it's $SHFORTRANPPCOM — the default C-preprocessor command line for all Fortran versions. ✨
SHF95PPCOMSTR — if set, the string displayed when a Fortran 95 source file is compiled to a shared-library object file after first running the file through the C preprocessor. If not set, $SHF95PPCOM or $SHFORTRANPPCOM (the command line) shows up instead. 🌸
SHFORTRAN — the default Fortran compiler used for generating shared-library objects. that's the whole job. 🦋
SHFORTRANCOM — the command line that compiles a Fortran source file to a shared-library object file. By default, any options in $SHFORTRANFLAGS, $_FORTRANMODFLAG, and $_FORTRANINCFLAGS are included on this command line. Also peep $FORTRANCOM. 💅
SHFORTRANCOMSTR — if set, the string displayed when a Fortran source file is compiled to a shared-library object file. If not set, $SHFORTRANCOM (the command line) is shown. 🎀
SHFORTRANFLAGS — options passed to the Fortran compiler to generate shared-library objects. 🔥
SHFORTRANPPCOM — the command line that compiles a Fortran source file to a shared-library object file after first running the file through the C preprocessor. By default, any options in $SHFORTRANFLAGS, $CPPFLAGS, $_CPPDEFFLAGS, $_FORTRANMODFLAG, and $_FORTRANINCFLAGS are included on this command line. See also $SHFORTRANCOM. ✨
SHFORTRANPPCOMSTR — if set, the string displayed when a Fortran source file is compiled to a shared-library object file after first running the file through the C preprocessor. If not set, $SHFORTRANPPCOM (the command line) is displayed. 🌈
SHLIBEMITTER — holds the emitter specification for the SharedLibrary builder. The manpage section "Builder Objects" has the general tea on specifying emitters. iykyk. 👑
SHLIBNOVERSIONSYMLINKS — tells the SharedLibrary builder to not create symlinks for versioned shared libraries. that's it, that's the vibe. 💜
SHLIBPREFIX — the prefix used for shared library file names. 🍓
_SHLIBSONAME — a macro that automatically generates a shared library's $SONAME based on $TARGET, $SHLIBVERSION and $SHLIBSUFFIX. Used by the SharedLibrary builder when the linker tool supports SONAME (like gnulink). iconic. ⭐
SHLIBSUFFIX — the suffix used for shared library file names. 🌸
SHLIBVERSION — when this construction variable is defined, a versioned shared library gets created by the SharedLibrary builder. That activates $_SHLIBVERSIONFLAGS and therefore modifies $SHLINKCOM as needed, adds the version number to the library name, and creates all the symlinks that are needed. $SHLIBVERSION versions are specified as alphanumeric, decimal-delimited values which can be recognized by the regular expression "\w+[\.\w+]*". Example valid $SHLIBVERSION values include '1', '1.2.3', and '1.2.gitaa412c8b'. slay. 💅
_SHLIBVERSIONFLAGS — this macro automatically introduces extra flags to $SHLINKCOM when building a versioned SharedLibrary (that is, when $SHLIBVERSION is set). $_SHLIBVERSIONFLAGS usually adds $SHLIBVERSIONFLAGS and some extra dynamically generated options (such as -Wl,-soname=$_SHLIBSONAME). It's unused by "plain" (unversioned) shared libraries. 🙈
SHLIBVERSIONFLAGS — extra flags added to $SHLINKCOM when building a versioned SharedLibrary. These flags are only used when $SHLIBVERSION is set. periodt. ✨
SHLINK — the linker for programs that use shared libraries. See also $LINK for linking static objects.

On POSIX systems (those using the link tool), you should normally not change this value, because it defaults to a "smart" linker tool which selects a compiler driver matching the type of source files in use. So for example, if you set $SHCXX to a specific compiler name, and you're compiling C++ sources, the smartlink function will automatically select the same compiler for linking. no cap, it's doing all that. 🧚

SHLINKCOM — the command line used to link programs using shared libraries. See also $LINKCOM for linking static objects. 💖
SHLINKCOMSTR — the string displayed when programs using shared libraries are linked. If this is not set, then $SHLINKCOM (the command line) is displayed. See also $LINKCOMSTR for linking static objects.

env = Environment(SHLINKCOMSTR = "Linking shared $TARGET")

SHLINKFLAGS — general user options passed to the linker for programs using shared libraries. Big heads up: this variable should not contain -l (or similar) options for linking with the libraries listed in $LIBS, and it should not contain -L (or similar) include search path options that scons generates automatically from $LIBPATH. See $_LIBFLAGS above for the variable that expands to library-link options, and $_LIBDIRFLAGS above for the variable that expands to library search path options. See also $LINKFLAGS for linking static objects. 💅
SHOBJPREFIX — the prefix used for shared object file names. 🎀
SHOBJSUFFIX — the suffix used for shared object file names. 🌸
SONAME — the name of a versioned shared library/loadable module. If you specify it, it's an explicit statement of the name; if you leave it unspecified, the value gets generated. Watch out bestie: $SONAME and $SOVERSION may not both be specified in the same construction environment or override. 👀

# Will cause libtest.so.2 to exist and be a symlink to libtest.so.0.1.2
env.SharedLibrary('test', 'test.c', SHLIBVERSION='0.1.2', SONAME='libtest.so.2')

This variable is used by toolchains that support versioned shared objects.

SOURCE — a reserved variable name that may not be set or used in a construction environment. (Peep the manpage section "Variable Substitution" for more.) 🚫
SOURCE_URL — the URL (web address) of the location from which the project was retrieved. This is used to fill in the Source: field in the controlling information for Ipkg and RPM packages.

See the Package builder. 📦

SOURCES — a reserved variable name that may not be set or used in a construction environment. (Again, the manpage section "Variable Substitution" has more info.) 🚫
SOVERSION — version string used in construction of $SONAME. The version is added to the base library name (test in the example below). And again: $SONAME and $SOVERSION may not both be specified in the same construction environment or override. 👑

# SONAME will be libtest.so.2, and will be a symlink to libtest.so.0.1.2
env.SharedLibrary('test', 'test.c', SHLIBVERSION='0.1.2', SOVERSION='2')

This variable is used by toolchains that support versioned shared objects.

SPAWN — a command interpreter function that will be called to execute command line strings. The function must accept five arguments:

def spawn(shell, escape, cmd, args, env):

shell is a string naming the shell program to use, escape is a function that can be called to escape shell special characters in the command line, cmd is the path to the command to be executed, args holds the arguments to the command and env is a dictionary of environment variables defining the execution environment in which the command should be executed. fr fr, that's the whole signature. ✨

STATIC_AND_SHARED_OBJECTS_ARE_THE_SAME — when this variable is true, static objects and shared objects are assumed to be the same; that is, SCons does not check for linking static objects into a shared library. 💀
SUBST_DICT — the dictionary used by the Substfile or Textfile builders for substitution values. It can be anything acceptable to the dict() constructor, so in addition to a dictionary, lists of tuples are also acceptable. 🫶
SUBSTFILEPREFIX — the prefix used for Substfile file names, an empty string by default. 🎀
SUBSTFILESUFFIX — the suffix used for Substfile file names, an empty string by default. 🎀
SUMMARY — a short summary of what the project is about. It's used to fill in the Summary: field in the controlling information for Ipkg and RPM packages, and as the Description: field in MSI packages.

See the Package builder. 📦

SWIG — the name of the SWIG compiler to use. 🐍
SWIGCFILESUFFIX — the suffix that will be used for intermediate C source files generated by SWIG. The default value is '_wrap$CFILESUFFIX' — that is, the concatenation of the string _wrap and the current C suffix $CFILESUFFIX. By default, this value is used whenever the -c++ option is not specified as part of the $SWIGFLAGS construction variable. 💅
SWIGCOM — the command line used to call SWIG. ✨
SWIGCOMSTR — the string displayed when calling SWIG. If this is not set, then $SWIGCOM (the command line) is displayed. 🌈

`SWIGCXXFILESUFFIX` ✨

the suffix bestie, the suffix 💅 it's what gets slapped onto the intermediate C++ source files that SWIG generates. default value? '_wrap$CXXFILESUFFIX' — which is literally just the string _wrap concatenated with your current C++ suffix, $CXXFILESUFFIX. and by default this value is used whenever the -c++ option shows up as part of the $SWIGFLAGS construction variable. that's it, that's the whole vibe 🎀

`SWIGDIRECTORSUFFIX` 🦋

the suffix used for intermediate C++ header files generated by SWIG. heads up though — these only get generated for C++ code when SWIG's directors feature is turned on. default value is _wrap.h.

`SWIGFLAGS` 🌸

the general-options bucket that gets passed to SWIG. this is where you set your target language (-python, -perl5, -tcl, etc.) and whatever other options you wanna hand SWIG — like -c++ to generate C++ code instead of C code. your one-stop flag shop, iykyk 💖

`_SWIGINCFLAGS` 🫶

an automatically-generated construction variable holding the SWIG command-line options that specify directories to search for included files. the value of $_SWIGINCFLAGS is built by respectively prepending and appending $SWIGINCPREFIX and $SWIGINCSUFFIX to the beginning and end of each directory in $SWIGPATH. the machine handles it, you just vibe ✨

`SWIGINCPREFIX` 🌈

the prefix used to specify an include directory on the SWIG command line. it gets prepended to the beginning of each directory in the $SWIGPATH construction variable whenever the $_SWIGINCFLAGS variable is automatically generated.

`SWIGINCSUFFIX` ⭐

the suffix used to specify an include directory on the SWIG command line. it gets appended to the end of each directory in the $SWIGPATH construction variable whenever the $_SWIGINCFLAGS variable is automatically generated.

`SWIGOUTDIR` 👑

tells SWIG which output directory to drop its generated language-specific files into. SCons uses this to figure out which files the SWIG call is gonna generate, and it gets translated into the swig -outdir option on the command line. slay 🎀

`SWIGPATH` 💜

the list of directories SWIG will search for included files. SCons' SWIG implicit dependency scanner searches these same directories for include files. default value is an empty list.

⚠️ do NOT explicitly put include-directory arguments in $SWIGFLAGS — the result will be non-portable and the directories won't be searched by the dependency scanner. not the move bestie 😭

note: directory names in $SWIGPATH get looked up relative to the SConscript directory when they're used in a command. to force scons to look a directory up relative to the root of the source tree, use a top-relative path (#):

env = Environment(SWIGPATH='#/include')

the directory lookup can also be forced using the Dir() function:

include = Dir('include')
env = Environment(SWIGPATH=include)

the directory list gets added to command lines through the automatically-generated $_SWIGINCFLAGS construction variable, which is constructed by respectively prepending and appending the values of $SWIGINCPREFIX and $SWIGINCSUFFIX to the beginning and end of each directory in $SWIGPATH. any command lines you define that need the SWIGPATH directory list should include $_SWIGINCFLAGS:

env = Environment(SWIGCOM="my_swig -o $TARGET $_SWIGINCFLAGS $SOURCES")

`SWIGVERSION` 🌸

the detected version string of the SWIG tool. cute little string, tells you what you're working with 💅

`TAR` 🧚

the tar archiver.

`TARCOM` ✨

the command line used to call the tar archiver.

`TARCOMSTR` 🎀

the string displayed when archiving files using the tar archiver. if this isn't set, then $TARCOM (the command line) is displayed instead. for example:

env = Environment(TARCOMSTR = "Archiving $TARGET")

`TARFLAGS` 🦋

general options passed to the tar archiver.

`TARGET` 👑

a reserved variable name that may not be set or used in a construction environment. (peep the manpage section "Variable Substitution" for more info). it's reserved bb, hands off 🙈

`TARGET_ARCH` 🔥

the name of the hardware architecture that objects created using this construction environment should target. you can set it when you create a construction environment by passing it as a keyword argument in the Environment call.

on the win32 platform, if the Microsoft Visual C++ compiler is available, msvc tool setup is done using $HOST_ARCH and $TARGET_ARCH. if no value is specified, it gets set to the same value as $HOST_ARCH. changing the value after the environment is initialized will not cause the tool to be reinitialized — no take-backs bestie 😤. compiled objects will be in the target architecture if the compilation system supports generating for that target. the latest compiler that can fulfill the requirement gets selected, unless a different version is directed by the value of the $MSVC_VERSION construction variable.

on the win32/msvc combo, valid target arch values are x86, arm, i386 for 32-bit targets, and amd64, arm64, x86_64 and ia64 (Itanium) for 64-bit targets. for example, if you want to compile 64-bit binaries, you'd set TARGET_ARCH='x86_64' when creating the construction environment. but note: not all target architectures are supported for all Visual Studio / MSVC versions. check the relevant Microsoft documentation, fr fr.

$TARGET_ARCH is not currently used by other compilation tools, but the option is reserved to do so in future.

`TARGET_OS` 💀

the name of the operating system that objects created using this construction environment should target. you can set it when creating a construction environment by passing it as a keyword argument in the Environment call;.

$TARGET_OS is not currently used by SCons, but the option is reserved to do so in future.

`TARGETS` 🫶

a reserved variable name that may not be set or used in a construction environment. (see the manpage section "Variable Substitution" for more information). reserved, okay? we do not touch 🙅‍♀️

`TARSUFFIX` 🌈

the suffix used for tar file names.

`TEMPFILE` 💖

holds a callable object that gets invoked to transform long command lines (string or list) into an alternate form. length limits on various operating systems can cause long command lines to fail when calling out to a shell to run the command. most often this hits linking, when there are many object files and/or libraries to link — but it can also affect other compilation steps that have lots and lots of arguments. $TEMPFILE is not called directly; it's typically embedded inside another construction variable, to be expanded when used. example:

env["TEMPFILE"] = TempFileMunge
env["LINKCOM"] = "${TEMPFILE('$LINK $TARGET $SOURCES', '$LINKCOMSTR')}"

the SCons default value for $TEMPFILE, TempFileMunge, does command substitution on the passed command line, calculates whether modification is needed, then puts all but the first word (assumed to be the command name) of the resulting list into a temporary file (sometimes called a response file or command file), and returns a new command line consisting of the command name plus an appropriately formatted reference to that temporary file. iconic behaviour honestly 🎀

a replacement for the default tempfile object would need to do fundamentally the same thing, including taking into account the values of $MAXLINELENGTH, $TEMPFILEPREFIX, $TEMPFILESUFFIX, $TEMPFILEARGJOIN, $TEMPFILEDIR and $TEMPFILEARGESCFUNC. if a particular use case requires a different transformation than the default, it's recommended to copy the mechanism and define a new construction variable, then rewrite the relevant *COM variable(s) to use it — that way you avoid possibly disrupting existing uses of $TEMPFILE. protect the existing vibes, bestie 🫶

`TEMPFILEARGESCFUNC` 🌸

the default argument escape function is SCons.Subst.quote_spaces. if you need to apply extra operations on a command argument (fix Windows slashes, normalize paths, etc.) before writing it to the temporary file, you can set the $TEMPFILEARGESCFUNC variable to a custom function. the function must accept a single string argument and return a new string with any modifications applied. example:

import sys
import re
from SCons.Subst import quote_spaces

WINPATHSEP_RE = re.compile(r"\\([^\"'\\]|$)")

def tempfile_arg_esc_func(arg):
    arg = quote_spaces(arg)
    if sys.platform != "win32":
        return arg
    # GCC requires double Windows slashes, let's use UNIX separator
    return WINPATHSEP_RE.sub(r"/\1", arg)

env["TEMPFILEARGESCFUNC"] = tempfile_arg_esc_func

`TEMPFILEARGJOIN` ✨

the string used to join the arguments passed to $TEMPFILE when the command line exceeds the limit set by $MAXLINELENGTH. default value is a space. however, for MSVC / MSLINK the default is a line separator as defined by os.linesep. note that this value is used literally and is not expanded by the subst logic. literally literally 💅

`TEMPFILEDIR` 🦋

the directory to create the long-lines temporary file in. if unset, the Python tempfile module chooses the directory based on the TMPDIR, TEMP or TMP environment variables. if the default path causes processing errors, set $TEMPFILEDIR to a safer alternative. for example, on Windows the default temporary file path contains the username — and if that username contains non-7-bit-ASCII characters, there may be decoding errors when opening the path to the temporary file 😭. see also $TEMPFILEENCODING.

`TEMPFILEENCODING` 💜

by default, the long-lines temporary file (aka "response file") created by the $TEMPFILE function gets encoded in the Python default encoding, UTF-8. if the external command that reads the response file runs into decoding errors (usually when that command depends on Windows legacy code pages, and a pathname in the response file — or the response file path itself — can't be represented in the 7-bit ASCII character set), set this variable to the appropriate codec. see also $TEMPFILEDIR.

new in version 4.10.0 ⭐

`TEMPFILEPREFIX` 🌈

the prefix for the name of the temporary file used to store command lines exceeding $MAXLINELENGTH. the prefix must include the compiler syntax to actually include and process the file. the default prefix is '@', which works for the Microsoft Visual C++ and GNU toolchains on Windows. set this appropriately for other toolchains — for example '-@' for the diab compiler, or '-via' for the ARM toolchain. know your toolchain, bestie, iykyk 🔥

TEMPFILESUFFIX — okay so when a command line is longer than $MAXLINELENGTH, SCons stashes it in a temporary file, right? This is the suffix for that file's name. And bestie, listen — you gotta include the dot ('.') yourself if you want one, because it will not get added automatically. default is .lnk 💅
TEX — the TeX formatter and typesetter. that's it, that's the whole vibe 🎀
TEXCOM — the command line used to call the TeX formatter and typesetter.
TEXCOMSTR — the string that gets displayed when calling the TeX formatter and typesetter. If you don't set this, then $TEXCOM (the command line) is what shows up. no cap.

env = Environment(TEXCOMSTR = "Building $TARGET from TeX input $SOURCES")

TEXFLAGS — general options passed to the TeX formatter and typesetter. the little extras, the seasoning ✨
TEXINPUTS — list of directories that the LaTeX program will search for include directories. The LaTeX implicit dependency scanner will search these directories for \include and \import files. 👑
TEXTFILEPREFIX — the prefix used for Textfile file names, an empty string by default.
TEXTFILESUFFIX — the suffix used for Textfile file names; .txt by default. 🍓
TOOLS — a list of the names of the Tool specification modules that were actually initialized in the current construction environment. This may be useful as a diagnostic aid to see if a tool did (or did not) run. The value is informative and is not guaranteed to be complete. so like, use it as a hint, not as gospel, fr fr.
UNCHANGED_SOURCES — a reserved variable name that may not be set or used in a construction environment. (See the manpage section "Variable Substitution" for more information). hands off, bestie 🙈
UNCHANGED_TARGETS — a reserved variable name that may not be set or used in a construction environment. (See the manpage section "Variable Substitution" for more information). same energy, also hands off 💀
VENDOR — the person or organization who supply the packaged software. This is used to fill in the Vendor: field in the controlling information for RPM packages, and the Manufacturer: field in the controlling information for MSI packages.

See the Package builder.

VERSION — the version of the project, specified as a string. 🏷️

See the Package builder.

VSWHERE — specify the location of vswhere.exe.

vswhere.exe is distributed with Microsoft Visual Studio and Build Tools since the 2017 edition, but it's also available as a standalone installation. It allows queries to obtain detailed information about installations of 2017 and later editions. SCons makes use of this info to figure out the state of compiler support for those editions. iconic behavior tbh.

Setting the $VSWHERE variable to the path to a specific vswhere.exe binary causes SCons to use that binary. If it's not set, SCons will search for one, looking in the following locations in order, using the first found ($VSWHERE is updated with the location):

%ProgramFiles(x86)%\Microsoft Visual Studio\Installer
%ProgramFiles%\Microsoft Visual Studio\Installer
%ChocolateyInstall%\bin
%LOCALAPPDATA%\Microsoft\WinGet\Links
%USERPROFILE%\scoop\shims
%SCOOP%\shims

Note — for this to actually take effect, $VSWHERE must be set before the initial Microsoft Visual C++ compiler discovery takes place. Discovery happens, at the latest, during the first call to the Environment function, unless a tools list is specified which excludes the entire Microsoft Visual C++ toolchain — that is, omits "defaults" and any specific tool module that refers to parts of the toolchain (msvc, mslink, masm, midl and msvs). In this case, detection is deferred until any one of those tool modules is invoked manually. The following two examples illustrate this:

# VSWHERE set as Environment is created
env = Environment(VSWHERE='c:/my/path/to/vswhere')

# Initialization deferred with empty tools, triggered manually
env = Environment(tools=[])
env['VSWHERE'] = r'c:/my/vswhere/install/location/vswhere.exe'
env.Tool('msvc')
env.Tool('mslink')
env.Tool('msvs')

so like, timing is everything, periodt ⏰

WINDOWS_EMBED_MANIFEST — set to True to embed the compiler-generated manifest (normally ${TARGET}.manifest) into all Windows executables and DLLs built with this environment, as a resource during their link step. This is done using $MT and $MTEXECOM and $MTSHLIBCOM. See also $WINDOWS_INSERT_MANIFEST. 🪟
WINDOWS_INSERT_DEF — if set to true, a library build of a Windows shared library (.dll file) will include a reference to the corresponding module-definition file at the same time, if a module-definition file isn't already listed as a build target. The name of the module-definition file will be constructed from the base name of the library and the construction variables $WINDOWSDEFSUFFIX and $WINDOWSDEFPREFIX. The default is to not add a module-definition file. The module-definition file is not created by this directive, and must be supplied by the developer. so you gotta bring your own, bestie 🫶
WINDOWS_INSERT_MANIFEST — if set to true, scons will add the manifest file generated by Microsoft Visual C++ 8.0 and later to the target list so SCons will be aware they were generated. In the case of an executable, the manifest file name is constructed using $WINDOWSPROGMANIFESTSUFFIX and $WINDOWSPROGMANIFESTPREFIX. In the case of a shared library, the manifest file name is constructed using $WINDOWSSHLIBMANIFESTSUFFIX and $WINDOWSSHLIBMANIFESTPREFIX. See also $WINDOWS_EMBED_MANIFEST.
WINDOWSDEFPREFIX — the prefix used for a Windows linker module-definition file name. Defaults to empty.
WINDOWSDEFSUFFIX — the suffix used for a Windows linker module-definition file name. Defaults to .def.
WINDOWSEXPPREFIX — the prefix used for Windows linker exports file names. Defaults to empty.
WINDOWSEXPSUFFIX — the suffix used for Windows linker exports file names. Defaults to .exp.
WINDOWSPROGMANIFESTPREFIX — the prefix used for executable program manifest files generated by Microsoft Visual C++. Defaults to empty.
WINDOWSPROGMANIFESTSUFFIX — the suffix used for executable program manifest files generated by Microsoft Visual C++. Defaults to .manifest. ✨
WINDOWSSHLIBMANIFESTPREFIX — the prefix used for shared library manifest files generated by Microsoft Visual C++. Defaults to empty.
WINDOWSSHLIBMANIFESTSUFFIX — the suffix used for shared library manifest files generated by Microsoft Visual C++. Defaults to .manifest. ✨
X_IPK_DEPENDS — this is used to fill in the Depends: field in the controlling information for Ipkg packages.

See the Package builder.

X_IPK_DESCRIPTION — this is used to fill in the Description: field in the controlling information for Ipkg packages. The default value is "$SUMMARY\n$DESCRIPTION" 🎀
X_IPK_MAINTAINER — this is used to fill in the Maintainer: field in the controlling information for Ipkg packages.
X_IPK_PRIORITY — this is used to fill in the Priority: field in the controlling information for Ipkg packages.
X_IPK_SECTION — this is used to fill in the Section: field in the controlling information for Ipkg packages.
X_MSI_LANGUAGE — this is used to fill in the Language: attribute in the controlling information for MSI packages.

See the Package builder.

X_MSI_LICENSE_TEXT — the text of the software license in RTF format. Carriage return characters will be replaced with the RTF equivalent \\par.

See the Package builder.

X_MSI_UPGRADE_CODE — TODO 😭 (yes, that's literally what it says, we don't make the rules)
X_RPM_AUTOREQPROV — this is used to fill in the AutoReqProv: field in the RPM .spec file.

See the Package builder.

X_RPM_BUILD — internal, but overridable. 🔧
X_RPM_BUILDREQUIRES — this is used to fill in the BuildRequires: field in the RPM .spec file. Note this should only be used on a host managed by rpm as the dependencies will not be resolvable at build time otherwise. so like, read the room before you use this one.
X_RPM_BUILDROOT — internal, but overridable. 🔧
X_RPM_CLEAN — internal, but overridable. 🔧
X_RPM_CONFLICTS — this is used to fill in the Conflicts: field in the RPM .spec file.
X_RPM_DEFATTR — this value is used as the default attributes for the files in the RPM package. The default value is "(-,root,root)".
X_RPM_DISTRIBUTION — this is used to fill in the Distribution: field in the RPM .spec file.
X_RPM_EPOCH — this is used to fill in the Epoch: field in the RPM .spec file.
X_RPM_EXCLUDEARCH — this is used to fill in the ExcludeArch: field in the RPM .spec file.
X_RPM_EXLUSIVEARCH — this is used to fill in the ExclusiveArch: field in the RPM .spec file. (yes the variable name is spelled exactly like that, don't come for me 💅)
X_RPM_EXTRADEFS — a list used to supply extra definitions or flags to be added to the RPM .spec file. Each item is added as-is with a carriage return appended. This is useful if some specific RPM feature not otherwise anticipated by SCons needs to be turned on or off. Note if this variable is omitted, SCons will by default supply the value '%global debug_package %{nil}' to disable debug package generation. To enable debug package generation, include this variable set either to None, or to a custom list that does not include the default line. 👑

New in version 3.1.

env.Package(
    NAME="foo",
    ...
    X_RPM_EXTRADEFS=[
        "%define _unpackaged_files_terminate_build 0"
        "%define _missing_doc_files_terminate_build 0"
    ],
    ...
)

X_RPM_GROUP — this is used to fill in the Group: field in the RPM .spec file.
X_RPM_GROUP_lang — this is used to fill in the Group(lang): field in the RPM .spec file. Note that lang is not literal and should be replaced by the appropriate language code. 🦋
X_RPM_ICON — this is used to fill in the Icon: field in the RPM .spec file.
X_RPM_INSTALL — internal, but overridable. 🔧
X_RPM_PACKAGER — this is used to fill in the Packager: field in the RPM .spec file.
X_RPM_POSTINSTALL — this is used to fill in the %post: section in the RPM .spec file.
X_RPM_POSTUNINSTALL — this is used to fill in the %postun: section in the RPM .spec file.
X_RPM_PREFIX — this is used to fill in the Prefix: field in the RPM .spec file.
X_RPM_PREINSTALL — this is used to fill in the %pre: section in the RPM .spec file.
X_RPM_PREP — internal, but overridable. 🔧

💅 `X_RPM_PREUNINSTALL`

Bestie, this one fills in the %preun: section of the RPM .spec file. That's it, that's the whole job. 🎀

✨ `X_RPM_PROVIDES`

Fills in the Provides: field in the RPM .spec file. Slay.

🌸 `X_RPM_REQUIRES`

Fills in the Requires: field in the RPM .spec file.

🦋 `X_RPM_SERIAL`

Fills in the Serial: field in the RPM .spec file.

🌈 `X_RPM_URL`

Fills in the Url: field in the RPM .spec file.

💖 `XGETTEXT`

The path to the xgettext(1) program — SCons finds it via Detect(). See the xgettext tool and the POTUpdate builder.

👑 `XGETTEXTCOM`

The complete xgettext command line. See the xgettext tool and the POTUpdate builder.

🫶 `XGETTEXTCOMSTR`

The string that gets shown when the xgettext(1) command is invoked (default: '', which literally means "print $XGETTEXTCOM"). See the xgettext tool and the POTUpdate builder.

🧚 `_XGETTEXTDOMAIN`

An internal "macro". It generates the xgettext domain name from source and target (default: '${TARGET.filebase}').

⭐ `XGETTEXTFLAGS`

Extra flags to hand off to xgettext(1). See the xgettext tool and the POTUpdate builder.

🍓 `XGETTEXTFROM`

The name of the file that holds the list of xgettext(1)'s source files. Autotools girlies know this one as POTFILES.in, so in most cases you're gonna set XGETTEXTFROM="POTFILES.in" right here. The $XGETTEXTFROM files have the same syntax and semantics as the well-known GNU POTFILES.in. See the xgettext tool and the POTUpdate builder.

💜 `_XGETTEXTFROMFLAGS`

Internal "macro". It generates the list of -D<dir> flags from the $XGETTEXTPATH list.

🎀 `XGETTEXTFROMPREFIX`

This flag is used to add a single $XGETTEXTFROM file to xgettext(1)'s command line (default: '-f').

🌸 `XGETTEXTFROMSUFFIX`

(default: '') — yeah bestie, it's just an empty string by default. 🙈

🦋 `XGETTEXTPATH`

A list of directories where xgettext(1) will look for source files (default: []).

Note: this variable works only together with $XGETTEXTFROM. They're a package deal, no cap.

See also the xgettext tool and the POTUpdate builder.

🔥 `_XGETTEXTPATHFLAGS`

Internal "macro". It generates the list of -f<file> flags from $XGETTEXTFROM.

✨ `XGETTEXTPATHPREFIX`

This flag is used to add a single search path to xgettext(1)'s command line (default: '-D').

💫 `XGETTEXTPATHSUFFIX`

(default: '')

💅 `YACC`

The parser generator. That's the whole vibe.

🔥 `YACC_GRAPH_FILE`

If you supply it, a graph of the automaton gets written to a file with the name taken from this variable. It'll be emitted as a --graph= command-line option. Use this instead of sticking --graph= into $YACCFLAGS directly, okay? It's the better way, fr fr.

New in version 4.4.0.

👑 `YACC_GRAPH_FILE_SUFFIX`

Previously this was specified by $YACCVCGFILESUFFIX.

This is the suffix of the file containing a graph of the grammar automaton, used when the -g option (or --graph= without an option-argument) shows up in $YACCFLAGS. Heads up though: setting this variable just tells SCons how to construct the graph filename for tracking purposes — it does not touch the actual generated filename. Different yacc tools have emitted different formats at different times, so set this to match whatever your parser generator actually produces.

New in version 4.6.0.

🦋 `YACC_HEADER_FILE`

If you supply it, a header file gets generated with the name taken from this variable. It'll be emitted as a --header= command-line option. Prefer this over putting --header= in $YACCFLAGS directly. 💖

New in version 4.4.0.

🌈 `YACCCOM`

The command line used to call the parser generator to generate a source file.

🎀 `YACCCOMSTR`

The string displayed when generating a source file using the parser generator. If this isn't set, then $YACCCOM (the command line) gets displayed instead.

env = Environment(YACCCOMSTR="Yacc'ing $TARGET from $SOURCES")

⭐ `YACCFLAGS`

General options passed to the parser generator. And here's the tea: besides passing the value on during invocation, the yacc tool also examines this construction variable for options that cause extra output files to be generated, and adds those to the target list. Iconic behavior honestly.

If the -d option is present in $YACCFLAGS, scons assumes the call will also create a header file with the suffix defined by $YACCHFILESUFFIX if the yacc source file ends in a .y suffix, or a file with the suffix defined by $YACCHXXFILESUFFIX if the yacc source file ends in a .yy suffix. The header will have the same base name as the requested target. This is only correct if the executable is bison (or win_bison). If you're using Berkeley yacc (byacc), y.tab.h is always written — avoid the -d in this case and use $YACC_HEADER_FILE instead. 💀

If a -g option is present, scons assumes the call will also create a graph file with the suffix defined by $YACCVCGFILESUFFIX.

If a -v option is present, scons assumes the call will also create an output debug file with the suffix .output.

Also recognized are the GNU bison options --header (and its deprecated synonym --defines), which is similar to -d but lets you explicitly name the output header file through an option argument; and --graph, which is similar to -g but lets you explicitly name the output graph file through an option argument. The file suffixes described for -d and -g above are not applied if these are used in the option=argument form.

Note that files specified by --header= and --graph= may not be properly handled by SCons in all situations, and using those in $YACCFLAGS should be considered legacy support only. Consider using $YACC_HEADER_FILE and $YACC_GRAPH_FILE instead if the files need to be explicitly named (new in version 4.4.0).

🧚 `YACCHFILESUFFIX`

The suffix of the C header file generated by the parser generator when the -d option (or --header without an option-argument) is used in $YACCFLAGS. Note that setting this variable tells SCons how to construct the header filename for tracking purposes — it does not affect the actual generated filename. Set this to match what your parser generator produces. The default value is .h.

🫶 `YACCHXXFILESUFFIX`

The suffix of the C++ header file generated by the parser generator when the -d option (or --header without an option-argument) is used in $YACCFLAGS. Note that setting this variable tells SCons how to construct the header filename for tracking purposes — it does not affect the actual generated filename. Set this to match what your parser generator produces. The default value is .hpp.

🙈 `YACCVCGFILESUFFIX`

Obsoleted, bestie. Use $YACC_GRAPH_FILE_SUFFIX instead. The value here is used only if $YACC_GRAPH_FILE_SUFFIX is not set. The default value is .gv.

Changed in version 4.6.0: deprecated. The default value changed from .vcg (bison stopped generating .vcg output with version 2.4, back in 2006). Ancient history. 🦕

🍓 `ZIP`

The zip compression and file packaging utility.

✨ `ZIP_OVERRIDE_TIMESTAMP`

An optional timestamp which overrides the last modification time of the file when it's stored inside the Zip archive. It's a tuple of six values:

Year (>= 1980)
Month (one-based)
Day of month (one-based)
Hours (zero-based)
Minutes (zero-based)
Seconds (zero-based)

💜 `ZIPCOM`

The command line used to call the zip utility, or the internal Python function used to create a zip archive.

🌈 `ZIPCOMPRESSION`

The compression flag from the Python zipfile module, used by the internal Python function to control whether the zip archive is compressed or not. The default value is zipfile.ZIP_DEFLATED, which creates a compressed zip archive. This value has no effect if the zipfile module is unavailable.

🎀 `ZIPCOMSTR`

The string displayed when archiving files using the zip utility. If this isn't set, then $ZIPCOM (the command line or internal Python function) gets displayed.

env = Environment(ZIPCOMSTR = "Zipping $TARGET")

👑 `ZIPFLAGS`

General options passed to the zip utility.

🦋 `ZIPROOT`

An optional zip root directory (default empty). The filenames stored in the zip file will be relative to this directory, if given. Otherwise, the filenames are relative to the current directory of the command. For instance:

env = Environment()
env.Zip('foo.zip', 'subdir1/subdir2/file1', ZIPROOT='subdir1')

will produce a zip file foo.zip containing a file with the name subdir2/file1 rather than subdir1/subdir2/file1. See how that works? chef's kiss. 💅

💖 `ZIPSUFFIX`

The suffix used for zip file names.

🛠️ Configure Contexts 🛠️

So SCons ships with an integrated autoconfiguration mechanism (inspired by GNU Autoconf but intrinsic to SCons, so it's built-in, not bolted on) for checking whether the external stuff your build needs actually exists — C header files, libraries, all of that. You can use it to:

build optional features only if support for them is available,
abort the build quickly if required elements are missing,
or just tune the build to the specific build platform.

The whole mechanism is portable across platforms. Periodt.

You activate the configuration system by creating a configure context, which holds all the accumulated info while the checks are being performed. Then you request the checks you want, and then you transfer that info into the regular build environment. Optionally, a configure header that C or C++ code can include can also be generated. And here's a fun difference: SCons does not maintain an explicit cache of the tested values (unlike Autoconf) — it uses its normal dependency tracking to keep the checked values up to date instead. You can override this behavior 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])

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 checks. The context includes a local construction environment (available as context.env) which is used when running the checks and which can be updated with the check results. Only one context may be active at a time, but a new context can be created after the active one is completed. For the global function form, the required env describes the initial values for the context's local construction environment; for the construction environment method form, the instance provides the values.

custom_tests specifies a dictionary containing custom checks (see the details below). The default value is None, to indicate there are no custom checks in the configure context.

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

log_file</p> — this one picks the file where all the receipts land 💅 like, every command that gets run to check whether a header file exists, whether a library exists, all that jazz, its output gets collected in here. Default is "#/config.log". And bestie, if you're doing variant directories, you might wanna stash the log file for a given build down under that build's variant directory. Just a thought 🎀

config_h</p> — this names a C header file where the test results get written out, so your build can just include it and know things. The results look like lines such as #define HAVE_GETADDRINFO 1, #define HAVE_INTTYPES_H 1, etc. Default is None, which means no configure header gets created at all, no cap. The convention has been to call this configure header config.h. You can specify the same config_h file across multiple calls to Configure, and in that case SCons will concatenate all the results into the specified file, slay. But note 👀 SCons uses its normal dependency tracking to decide if it's even necessary to rebuild the configure header. Which means the file is not necessarily rebuilt every single time scons is run — it only gets rebuilt if its contents will have changed and some target that depends on the configure header is being built. Efficient queen ✨

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. Default behavior is to always execute configure context tests, because the results of those tests may affect the list of targets to be cleaned or the help text. So if your configure tests don't affect those things, you may add the clean=False or help=False arguments (or both) to dodge unnecessary test execution. Go off 🫶

💀 Changed in version 4.0: raises an exception on an attempt to create a new context when there is an active context. One at a time, babe, we're monogamous here.

context.Finish()

Must be called after configuration is complete. Though it's required, this isn't enforced — except if Configure is called again while there's still an active context, in which case an exception gets raised. Rude but fair 😭

It returns the context's construction environment as modified during the course of running the configuration checks — the original environment is unchanged; typically the returned environment is used to replace the original. 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. New context, new you, main character energy 👑

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++", call="QApplication qapp(0,0);"):
    # do stuff for qt - usage, e.g.
    conf.env.Append(CPPDEFINES="WITH_QT")
env = conf.Finish()

A configure context has the following predefined methods which can be used to perform checks. Where language is an optional parameter, it specifies the programming language of the check, currently a choice of C or C++. The spellings accepted for C are "C" or "c"; for C++ the value can be "CXX", "cxx", "C++" or "c++". If language is omitted, "C" is assumed. Cute and flexible, we love options 💖

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

Check if header can be used when building this project. A generated stub program in the specified language is built to check. Ya girl doesn't guess, she compiles 🔥

header may also 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 directives should precede the header line being checked for. The optional argument include_quotes specifies the characters wrapping the header name — only the first two are considered. Essentially, this is how you swap the default double-quotes ("") out for angle brackets (<>). Glow up for your includes 💅

Returns a boolean indicating success or failure. If a configure header was requested, the result is recorded in it in the form of a preprocessor macro in the case of success, or an informative comment in the case of failure. Receipts either way 🎀

context.CheckCHeader(header, [include_quotes])

Check if header is usable when compiling a C language program. This is a wrapper around CheckHeader — see its entry for details. Shortcut queen ✨

context.CheckCXXHeader(header, [include_quotes])

Check if header is usable when compiling a C++ language program. This is a wrapper around CheckHeader — see its entry for details. Same vibe, C++ edition 🦋

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

Check if function_name is usable in the context's local environment, using the compiler specified by language — that is, can a check referencing it be compiled using the current values of $CFLAGS, $CPPFLAGS, $LIBS or other relevant construction variables. Basically: does this function actually exist for you, right here, right now 🙈

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

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

If header is supplied, it should not include the standard header file that declares function_name, and it should include a dummy prototype similar to the default case. If this is not possible, the optional funcargs argument can be used to specify a string containing an argument list with the same number and type of arguments as the prototype. The arguments can simply be constant values of the correct type. Important ⚠️ modern C/C++ compilers reject implicit function declarations and may also reject function calls whose arguments are not type compatible with the prototype. So like, don't test them with lie detector energy, be accurate bestie.

💖 Changed in version 4.7.0: added the funcargs.

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

Check if library can be used to build this project (see also CheckLibWithHeader). A small stub program is generated and linked against library by the compiler selected by language. If symbol is specified, the stub will contain a reference to that symbol, to check if it is actually provided by the library. If supplied, the text of header is included at the top of the stub; it must be syntactically correct in language. No sloppy syntax allowed, periodt 💅

Note that if symbol is given, the stub will be generated with an old-style prototype, as it has no knowledge of the actual prototype (e.g. char sin(); instead of double sin(double x);). Such usage is no longer legal under C23 and later. 💀 Old-school and lowkey illegal now, sorry.

The remaining arguments should be specified in keyword style. If extra_libs is specified, it is a list of additional libraries to include when linking the stub program (usually, dependencies of the library being checked). If autoadd is true (the default), and the link succeeds, the library is added to the $LIBS construction variable in the context. If append is true (the default), an added library is appended, otherwise it is prepended. If unique is true, and the library would otherwise be added but is already present in $LIBS in the configure context, it will not be added again. The default is False. Nobody wants duplicates in $LIBS, we're not that girl 🎀

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

Returns a boolean indicating success or failure.

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

✨ Changed in version 4.9.0: added the extra_libs parameter.

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

Check if library can be used to build this project, when a header file must be included to use library (see also CheckLib). The first three arguments can be given as either positional or keyword arguments. library specifies a library or list of libraries to check (the default is None), header specifies a header file or list of header files to include in the test program. If header is a list, 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 default is to include no header text. Iconic little combo move 🌸

The remaining parameters should be specified in keyword style. If provided, call is a code fragment to compile as the stub test, replacing the auto-generated stub. The fragment must be a valid expression in language. If not supplied, the default checks the ability to link against the specified library. extra_libs can be used to add additional libraries to link against (usually, dependencies of the library under test). If autoadd is true (the default), the first library that passes the check is added to the $LIBS construction variable in the configure context and the method returns. If append is true (the default), an added library is appended, otherwise it is prepended. If unique is true, and the library would otherwise be added but is already present in $LIBS in the configure context, it will not be added again. The default is False.

Returns a boolean indicating success or failure.

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

✨ Changed in version 4.9.0: added the extra_libs parameter.

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

Check whether type_name is defined via a typedef. includes is a string containing one or more #include lines that will be placed at the top of the stub program that will be compiled to perform the check. Returns a boolean indicating success or failure. If a configure header was requested, the result is recorded in it in the form of a preprocessor macro in the case of success, or an informative comment in the case of failure. Is it a real type or are we delulu? Now you'll know 🔍✨

Example:

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

context.CheckTypeSize(type_name, [header, language, expect]) — bestie, this one checks the size of a type. 🦋 type_name is a typedef (or a built-in type, whatever). The optional header arg is a string that gets plopped at the top of the stub program that gets compiled for the check — default is empty. If the type is found, the check slays and hands you back the size of the type; if not, you get zero. And if you pass the optional expect (an integer), the check only counts as a win when the size it found matches that number exactly. Fr fr, no fudging.

Example:

CheckTypeSize('short', expect=2)

This returns the size 2 only if short is genuinely, actually two bytes. 💅

context.CheckCC() — checks whether the C compiler (the one defined by the $CC construction variable) actually works, by trying to compile a tiny source file. It's giving rigor: by default SCons itself only detects whether there's a program with the right name sitting there, not whether it's a functioning compiler. Returns a boolean, success or failure. 👑

The test program gets built with the same command line that the Object builder uses for C source files, so by setting the relevant construction variables you can use it to detect whether particular compiler flags will be accepted or rejected by the compiler. Periodt.

context.CheckCXX() — same energy as above but for C++: checks whether the C++ compiler (as defined by the $CXX construction variable) works, by trying to compile a small source file. Again, more rigorous than the default — SCons itself only detects a program with the correct name normally, not a functioning compiler. Returns a boolean indicating success or failure. ✨

The test program is built with the same command line the Object builder uses for C++ source files, so tweaking the relevant construction variables lets it detect if particular compiler flags will be accepted or rejected. 🌸

context.CheckSHCC() — checks whether the shared-object C compiler (defined by the $SHCC construction variable) works, by trying to compile a small source file. Yes, it's the rigorous one again: by default SCons itself only detects if there's a program with the correct name, not if it's a functioning compiler. Returns a boolean indicating success or failure. 🎀

The test program gets built with the same command line that the SharedObject builder uses for C source files, so by setting relevant construction variables you can detect whether particular compiler flags will be accepted or rejected by the compiler. Heads up though: this does not check whether a shared library/dll can actually be created. Not the same thing, iykyk.

context.CheckSHCXX() — the shared-object C++ compiler version (as defined by the $SHCXX construction variable), checked by trying to compile a small source file. Rigorous mode once more: SCons by default only detects a program with the correct name, not a functioning compiler. Returns a boolean indicating success or failure. 🫶

The test program is built with the same command line the SharedObject builder uses for C++ source files, so setting relevant construction variables lets you detect if particular compiler flags will be accepted or rejected by the compiler. Also: this does not check whether a shared library/dll can be created. 💀

context.CheckProg(prog_name) — checks if prog_name exists in the path SCons will use at build time, aka context.env['ENV']['PATH']. Returns a string containing the path to the program, or None on failure. Short, sweet, iconic. 💜
context.CheckDeclaration(symbol, [includes, language]) — checks if the specified symbol is declared. includes is a string containing one or more #include lines that get inserted into the program that will be run to test for the existence of the symbol. 🌈

Returns a boolean indicating success or failure.

context.CheckMember(aggregate_member, [header, language]) — checks for the existence of a member of a C/C++ struct or class. aggregate_member specifies the struct/class and the member to check for. header is a string containing one or more #include lines inserted into the program that will be run to test for the existence of the member. Example:

sconf.CheckMember('struct tm.tm_sec', '#include <time.h>')

Returns a boolean indicating success or failure. 🌟

Added in 4.4.0. 🎉

context.Define(symbol, [value, comment]) — okay so this one does not check for anything at all. It's the opposite vibe: it forces the definition of a preprocessor macro that gets added to the configure header. name is the macro's identifier. If value is given, it will be used as the macro replacement value. If value is a string and needs to display with quotes, the quotes need to be included, as in '"string"'. If the optional comment is given, it gets inserted as a comment above the macro definition (suitable comment marks will be added automatically). This is analogous to using AC_DEFINE in Autoconf. 💅

Examples:

env = Environment()
conf = Configure(env)

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

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

Examples of quoting string values:

env = Environment()
conf = Configure(env)

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

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

Example including comment:

env = Environment()
conf = Configure(env)

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

🌟 Custom Checks & The Check Context 🌟

You can define your own custom checks on top of the predefined ones, bestie — build your own little check empire. 👑 To enable custom checks, pass a dictionary to the Configure function as the custom_tests parameter. The dictionary maps the names of the checks to the custom check callables (either a Python function or an instance of a class implementing a __call__ method). Each custom check gets called with a CheckContext instance as the first parameter, followed by the remaining arguments — and those remaining arguments have to be supplied by whoever uses the check. 🫶

Important distinction: a CheckContext is not the same as a configure context; rather it is an instance of a class which contains a configure context (available as chk_ctx.sconf). A CheckContext provides the following methods which custom checks can make use of:

chk_ctx.Message(text) — displays text as an indicator of progress. For example: Checking for library X..... Usually called before the check is started. 🎀
chk_ctx.Result(res) — displays a result message as an indicator of progress. If res is an integer, displays yes if res evaluates true or no if false. If res is a string, it's displayed as-is. Usually called after the check has completed. ✨
chk_ctx.TryCompile(text, extension='') — checks if a file containing text and given the specified extension (e.g. '.c') can be compiled to an object file using the environment's Object builder. Returns a boolean indicating success or failure. 🔥
chk_ctx.TryLink(text, extension='') — checks if a file containing text and given the specified extension (e.g. '.c') can be compiled to an executable program using the environment's Program builder. Returns a boolean indicating success or failure. 💖
chk_ctx.TryRun(text, extension='') — checks if a file containing text and given the specified extension (e.g. '.c') can be compiled to an executable program using the environment's Program builder and then actually run. Execution is only attempted if the build succeeds. If the program executes successfully (that is, its return status is 0), you get a tuple (True, outputStr) back, where outputStr is the standard output of the program. If the program fails execution (its return status is non-zero), then (False, '') is what you get. 😭
chk_ctx.TryAction(action, [text, extension='']) — checks if the specified action with an optional source file (contents text, given extension extension) can be executed. action may be anything which can be converted to an Action Object. On success you get a tuple (True, outputStr), where outputStr is the content of the target file. On failure, (False, '') comes back. 🦋
chk_ctx.TryBuild(builder, [text, extension='']) — the low level implementation for testing specific builds; the methods above are all based on this one. Given the Builder instance builder and the optional text of a source file with optional extension, returns a boolean indicating success or failure. Bonus: chk_ctx.lastTarget is set to the build target node if the build was successful. 🌸

Example of implementing and using custom checks:

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

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

🎀 Command-Line Construction Variables 🎀

SCons depends on information stored in construction variables to control how targets are built. It's often necessary to pass specialized information at build time to override the variables in the build scripts. This can be done through variable-assignment arguments on the command line and/or in stored variable files. 💅

okay bestie, real talk: sometimes you wanna specify new values for construction variables, and SCons is like "bet, here's a Variables object" so you don't have to babysit the whole thing by hand. It makes collecting those values and updating a construction environment with them so much less cursed. It helps you process command lines like this:

scons VARIABLE=foo OTHERVAR=bar

Now, variables that show up on the command line can always be handled manually, no cap — you just iterate the ARGUMENTS dictionary or the ARGLIST list. But using a Variables object lets you describe anticipated variables, do the necessary type conversion, validate that values meet your defined constraints, and specify default values, help messages and aliases. It's giving a somewhat similar interface to option handling (peep AddOption for that one). A Variables object also lets you obtain values from a saved variables file, or from a custom dictionary inside an SConscript file. Then the processed variables get applied to whatever construction environment you want. ✨

Conceptually? command-line targets control what to build, command-line variables (and variable files) control how to build, and command-line options control how SCons operates — although, and this is important, SCons does not enforce that separation. 🙈

To get yourself an object for manipulating variables, call the Variables factory function:

Variables([files, [args]])

So like:

If files is a filename or a list of filenames, they get executed as Python scripts to set saved variables when the Update method is called. This is what allows Python syntax in the assignments, which is lowkey iconic. A variables file can itself be the result of an earlier call to the Save method. If files isn't specified, or the files argument is None, then no files will be processed. Supplying None is required if there are no files but you want to specify args as a positional argument — or you can just use keyword arguments to dodge that whole situation. And if any of files is missing, it gets silently skipped (no drama, no error).

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

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

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

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

Calling Variables with no arguments is equivalent to:

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

A Variables object is a container for variable descriptions, which you add by calling the Add or AddVariables methods. A variable description consists of a name, a list of aliases for the name, a help message, a default value, and functions to validate and convert values. Processing of input sources is deferred until the Update method is called — and at that point the variables get added to the specified construction environment, using the name as the construction variable name. Heads up: any aliases are not added.

Variables from the input sources that don't match any names or aliases from the variable descriptions in this object are skipped — except that a dictionary of their names and values is made available in the unknown attribute of the Variables object. You can also snag that list via the UnknownVariables method. If a variable description has a default value other than None and does not appear in the input sources, it gets added to the construction environment with its default value. A list of variables that got set from their defaults and not from the input sources is available as the defaulted attribute of the Variables object.

💀 Careful bestie: the unknown variables and defaulted information is not available until the Update method has run. No peeking early.

Since the variables are eventually added as construction variables, you should choose variable names which do not unintentionally change pre-defined construction variables that your project will make use of (see the section called “Construction Variables” for a reference) — because the specified values are assigned, not merged, to the respective construction variables. 😭

The Variables subsystem does not directly support a way to define a variable the user must supply, but you can simulate it by using a validator function and specifying a default value which the validator will reject, resulting in an invalid value error message (the convenience methods EnumVariable and ListVariable make this relatively straightforward). 🎀

A Variables object has the following methods:

💅 `vars.Add`

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

Add a customizable construction variable to the Variables object. key is either the name of the variable, or a sequence of strings — in which case the first item in the sequence is taken as the variable name, and any remaining values are considered aliases for the variable. key is mandatory, the other fields are optional.

help is the help text for the variable (default is an empty string).
default is the value assigned to the variable in the construction environment if no value is provided in the input sources. If default is None (the default), the variable is not added to the construction environment unless explicitly set in the input sources. The default value can be of the intended type, or a string that the converter can transform into that type.
If the validator argument is supplied, it's a callback function to validate the value of the variable. The validator is called when the Update method is called. A validator must accept three arguments: key, value, and env. It should raise an exception (with a helpful error message) if the value is invalid; no return value is expected.
If the converter argument is supplied, it's a callback function to transform the value into the format desired for the construction environment. A converter is called before the validator. It must return a value, which is then passed to the validator (if any). A converter must accept at least a value argument, and may optionally accept env as a second argument if it needs access to the construction environment. In general, the converter should not fail, leaving validation checks to the validator — although if an operation is impossible to complete or there is no separate validator, it can raise a ValueError.
If the subst argument is supplied, it's a boolean that indicates whether to perform substitution on the value before passing it to the converter and validator functions. The default is True. Suppressing substitution may be useful if the variable value looks like a construction variable reference (e.g. $VAR) and the validator and/or converter should see it unexpanded.

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

Examples:

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

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

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

🌸 Changed in version 4.8.0: added the subst parameter.

🧁 `vars.AddVariables`

vars.AddVariables(args)

A convenience method that adds one or more customizable construction variables to a Variables object in one call; equivalent to calling Add multiple times. Each args member must be a tuple that contains the arguments for an individual call to the Add method using the "special case" form; the other calling styles (individual positional arguments and/or keyword arguments) are not supported.

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

✨ `vars.FormatVariableHelpText`

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

Returns a formatted string containing the printable help text for the single variable opt. All of the arguments must be supplied except aliases, which is optional. env is the construction environment containing the variable values (env is not used by the standard implementation of FormatVariableHelpText); var is the name of the variable; help is the text of the initial help message when the variable was added to the Variables object; default is the default value assigned when the variable was added to the Variables object; actual is the value as assigned in env (which may be the same as default, if none of the input sources assign to the variable); and aliases are any alias names for the variable, which if omitted defaults to an empty list.

FormatVariableHelpText is normally not called directly, but by GenerateHelpText, which does the work of obtaining the necessary values. You can patch in your own function that takes the same function signature in order to customize the appearance of variable help messages. Example:

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

vars.FormatVariableHelpText = my_format

🫶 Note that GenerateHelpText will not put any blank lines or extra characters between the entries, so you must add those characters to the returned string if you want the entries separated. iykyk.

👑 `vars.GenerateHelpText`

vars.GenerateHelpText(env, [sort])

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

vars.Save(filename, env) — drops all your currently-set variables into a script file called filename. Then later, bestie, you just hand that file to the Variables function and boom, your settings come right back. It's the ultimate "save my progress" move, caching specific variable settings so you never have to re-type them. And here's the thing: only variables that got set to non-default values get saved. Each chosen variable becomes a Python assignment statement. Oh, and heads up — whatever was previously in that save file? Not preserved. Unless it was used to populate the Variables object, that is. 🙈

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

vars.UnknownVariables() — returns a dictionary of any variables that were specified in the files and/or args parameters back when you called Variables, but that the object was never actually configured for. Like, you fed it stuff it doesn't know about? It's keeping receipts. ✨ Just know this info isn't available until Update has run. Patience, bestie.

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

vars.Update(env, [args]) — processes all the input sources it recorded when the Variables object was first initialized, and updates env with your customized construction variables. Any variable names in the input sources that aren't configured in the Variables object get noted, and you can grab them later with UnknownVariables. 👑

If you pass the optional args argument, it's gotta be a dictionary of variables — and it'll be used in place of the one saved when the Variables object was created.

Okay but fr, you usually don't call Update yourself. It gets invoked indirectly when you pass the Variables object to the Environment function:

env = Environment(..., variables=vars)

A Variables object also hands you two data attributes you can read for extra tea. Both only have values if Update has run before. 💅

vars.defaulted — a list of variable names that were set in the construction environment from the default values in the variable descriptions. Translation: variables that have a default value and were not defined in the input sources.
vars.unknown — a dictionary of variables that were specified in the input sources but have no matching variable definitions. Same info that UnknownVariables gives back, just in attribute form.

Added in 4.9.0: the defaulted attribute. 🎀

SCons ships with five pre-defined variable types, and you get them through factory functions that generate a tuple, ready to pass straight into Add or AddVariables. So convenient, honestly.

BoolVariable(key, help, default) — sets up a Boolean variable named key. It'll have a default value of default, and help becomes the descriptive part of your help text. It reads the command-line values y, yes, t, true, 1, on and all as true, and the values n, no, f, false, 0, off and none as false. Periodt.
EnumVariable(key, help, default, allowed_values, [map, ignorecase]) — sets up a variable named key whose value can only be picked from a specified list (an "enumeration") of values. Default value is default, help forms the descriptive bit. Any value not in allowed_values raises an error — except, the optional map argument is a dictionary you can use to map extra names onto a particular name in the allowed_values list. If the optional ignorecase is 0 (the default), values are considered case-sensitive. If ignorecase is 1, values get matched case-insensitively. If ignorecase is 2, values get matched case-insensitively and all input values get converted to lower case. 🌸
ListVariable(key, help, default, names, [map, validator]) — sets up a variable named key whose value can be one or more choices from a specified list of values. Default value is default, help is the descriptive part. Any value not in names — or the special values all or none — raises an error. Use a comma separator to specify multiple values, bestie. And default can be either a string of comma-separated values, or a Python list of values. Your call. 🦋

The optional map argument is a dictionary that can convert input values into specific legal values in the names list. (Quick note: those extra values you accept through a map do not show up in the generated help message. Sneaky.)

The optional validator argument lets you specify a custom validator callback function, exactly like the one described for Add. The default is to use an internal validator routine.

Added in 4.8.0: the validator parameter. ✨

PackageVariable(key, help, default) — sets up a variable named key to help control a build component, like a software package. It's similar to a BoolVariable, but it can also specify a path string to give the build extra info — say, the path to a config file describing the package, or a directory holding the package headers and libraries. Default value is default, and help becomes the descriptive part of the help text.

Any of the (case-insensitive) strings 1, yes, true, on, enable or search can indicate the package is "enabled", and can also be used as the value of default. A value of boolean True gets produced — except for the special case described for a path string.

Any of the (case-insensitive) strings 0, no, false, off or disable can indicate the package is "disabled", and can also be used as the value of default. A value of boolean False gets produced.

A string that's neither an enabling nor a disabling string is considered a "path string". You can give a path string when specifying the variable, and you can also use it as the value of default. A path string must refer to an existing filesystem path, but any further meaning is left up to the build system to decide. The path string is what gets produced. And here's the special case, so listen up: if default is a path string, and the variable is specified with an enabling string, then the default path string gets produced, rather than True. 💖

PathVariable(key, help, default, [validator]) — sets up a variable named key to hold a path string. Default value is default, and help is the descriptive part of the help text.

The optional validator parameter describes a callback function that gets called to verify the specified path is acceptable. SCons hands you these ready-made validators, slay:

PathVariable.PathExists — verifies the specified path exists. (This is the default behavior if you don't supply a validator.)
PathVariable.PathIsFile — verifies the specified path exists and is a regular file.
PathVariable.PathIsDir — verifies the specified path exists and is a directory.
PathVariable.PathIsDirCreate — verifies the specified path exists and is a directory; if it does not exist, creates the directory. 👑
PathVariable.PathAccept — accepts the specific path name argument without validation. Perfect for when you want your users to be able to specify a directory path that'll be created as part of the build process, for example.

You can also supply your own validator function, bestie. It's gotta accept three arguments: key, the name of the variable to be set; val, the specified value being checked; and env, the construction environment. And it should raise an exception if the specified value isn't acceptable. No pressure.

These functions make it super convenient to create a whole bunch of variables with consistent behavior in one single call to the AddVariables method:

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

🌈 Node Objects 🌈

SCons represents all the objects that are sources or targets of build operations as Nodes — which are internal data structures, bestie. Sneaky little things. There are a few user-visible types of nodes: File Nodes, Directory Nodes, Value Nodes and Alias Nodes. Some node types have public attributes and methods, which we're about to get into below. Every single node type has a global function and a matching environment method to create instances: File, Dir, Value and Alias. Iconic. ✨

🎀 Filesystem Nodes 🎀

okay so the File and Dir functions/methods hand you back File Nodes and Directory Nodes respectively 💅. These Filesystem Nodes are the little reps for build components that map to an entry in your computer's filesystem — and ngl, it literally does not matter whether that entry actually exists yet at the moment the Node gets created 🫶.

You usually do not need to go out here manually creating filesystem Nodes, bestie, because any time you hand a string over as the target or source of a Builder, SCons just makes the Nodes it needs to fill in the dependency graph ✨. Builders return the target Node(s) as a list, and you can do whatever you want with that list. BUT — since filesystem Nodes come with some genuinely useful public attributes and methods you can use in SConscript files, it's sometimes lowkey appropriate to create them yourself, outside the regular context of a Builder call 👑

The following attributes spill the tea about a Node:

node.path — the build path of the given file or directory 🌸. This path is relative to the project top directory. The build path is the same as the source path if variant_dir is not being used.
node.abspath — the absolute build path of the given file or directory 📍.
node.relpath — the build path of the given file or directory relative to the project top directory 🗺️.
node.srcnode() — the srcnode method returns another File or Directory Node representing the source path of the given File or Directory Node 🦋.

Examples, bestie:

# Get the current build dir's path, relative to top.
Dir('.').path

# Current dir's absolute path
Dir('.').abspath

# Current dir's path relative to the project top directory
Dir('.').relpath

# Next line is always '.', because it is the top dir's path relative to itself.
Dir('#.').path

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

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

periodt ✨

Filesystem Node objects also have methods to create new Filesystem Nodes relative to the original Node 👯. And there are times when you gotta refer to an entry in a filesystem without knowing in advance whether it's a file or a directory — for that whole vibe, there's an Entry method on filesystem node objects, which returns a Node that can represent either a file or a directory 🌈.

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

node.Dir(name) — returns a directory Node name which is a subdirectory of the directory represented by node 📁.
node.File(name) — returns a file Node name in the directory represented by node 📄.
node.Entry(name) — returns an unresolved Node name in the directory represented by node ❓.

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

node.Dir(name) — returns a Node name for a directory in the parent directory of the file represented by node 📁.
node.File(name) — returns a Node name for a file in the parent directory of the file represented by node 📄.
node.Entry(name) — returns an unresolved Node name in the parent directory of the file represented by node ❓.

For example:

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

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

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

# Combined example
docs = Dir('docs')
html = docs.Dir('html')
index = html.File('index.html')
css = index.File('app.css')

🌈 Value and Alias Nodes 🌈

SCons also serves up two other Node types to represent objects that won't have an equivalent filesystem entry 👀. These Nodes always need to be created explicitly — no shortcut, sorry bestie.

The Alias method returns an Alias Node ✨. Aliases are virtual objects — they will not themselves result in physical objects being constructed, but they do get entered into the dependency graph related to their sources. An alias gets checked for up-to-date-ness by checking if its sources are up-to-date 🔍. An alias is built by making sure its sources have been built, and if any building took place, applying any Actions that are defined as part of the alias 💅.

⚠️ An Alias call creates an entry in the alias namespace, which is used for disambiguation. If an alias source has a string-valued name, it will be resolved to a filesystem entry Node — unless it's found in the alias namespace, in which case it resolves to the matching alias Node. So the order of Alias calls is significant 😭. An alias can refer to another alias, but only if the other alias has previously been created. No time travel, queen 👑.

The Value method returns a Value Node 🍓. Value nodes are often used for generated data that won't have any corresponding filesystem entry, but will be used to determine whether a build target is out-of-date, or to include as part of a build Action 🔥. Common examples are timestamp strings, revision control version strings, and other run-time generated strings ⏰.

A Value Node can also be the target of a builder 💖.

🚀 EXTENDING SCONS 🚀

SCons was designed to be extensible through provided facilities, so changing the code of SCons itself is only rarely needed to customize its behavior 🧚. A bunch of the main operations use callable objects which can be supplemented by writing your own 🫶. Builders, Scanners and Tools each use a kind of plugin system, letting you easily drop in new ones ✨. Info about creating Builder Objects and Scanner Objects shows up in the following sections. The instructions SCons actually uses to construct things are called Actions, and it's easy to create Action Objects and hand them to the objects that need to know about those actions (besides Builders, see AddPostAction, AddPreAction and Alias for some examples of other places that take Actions 👀). Action Objects are also described below. Adding new Tool modules is described in Tool Modules 🔧.

🔨 Builder Objects 🔨

scons can be extended to build additional types of targets by adding new Builder objects to a construction environment 💪. 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 just modify the behavior of premade Builders like Program, Object or Library by changing the construction variables that control their behavior ($CC, $LINK, etc.) 🎛️. That way you can, for example, change the compiler to use — which is simpler and less error-prone than writing a whole new builder. No cap, the documentation for each Builder lists which construction variables it uses 📚.

Builder objects are created using the Builder factory function 🏭. Once created, a builder is added to a construction environment by registering it in the $BUILDERS dictionary in that environment (some of the examples in this section show how 👇). Doing so automatically triggers SCons to add a method with the name of the builder to the environment ✨.

The Builder function accepts the following keyword arguments:

action — the command used to build the target from the source 🔨. action may be a string representing a template command line to execute, a list of strings representing the command to execute with its arguments (suitable for enclosing white space in an argument), a dictionary mapping source file name suffixes to any combination of command line strings (if the builder should accept multiple source file extensions), a Python function, an Action object (see Action Objects) or a list of any of the above.

An action function must accept three arguments: source, target and env. source is a list of source nodes; target is a list of target nodes; env is the construction environment 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 construction environment 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 ✅. So, 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 🙈.

and that's where we're at, bestie — more coming, don't go anywhere 💖

src_suffix — the suffix you expect source files to have 💖. Can be a single string or a list of strings, no cap.
target_scanner — a Scanner object that gets invoked to sniff out implicit dependencies for this target file. Use it only for Scanner objects that figure out implicit deps from the target file + the construction environment. Do NOT use it for deps that come from source files — that's a source_scanner job, bestie 🙈. Peep the section called “Scanner Objects” for how to build your own Scanner objects.
source_scanner — a Scanner object that gets invoked to find implicit dependencies inside any source files used to build this target file 🦋. This is the one you reach for when you need to find stuff like #include lines in source files. The pre-built DirScanner Scanner object can be used to say "hey, this Builder should scan directory trees for on-disk changes to files that scons doesn't know about from other Builder or function calls." See the section called “Scanner Objects” for how to make your own Scanner objects, iykyk.
target_factory — a factory function the Builder uses to turn any targets given as strings into SCons Nodes ✨. By default SCons assumes every target is a file (so the default factory is File). Other iconic target_factory values: Dir for when a Builder makes a directory target, and Entry for when a Builder can make either a file or a directory target 👑

Example:

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

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

Heads up bestie — that call to the MakeDirectory Builder has to pass an empty source list so the filename string counts as the builder's target 💀. SCons assumes a single positional argument to a builder is the source, and would try to deduce the target name from it, which — with no automatically-added prefix or suffix — would give you a matching target and source name and a big ol' circular dependency. Not the vibe. 🚫

source_factory — a factory function the Builder uses to turn any sources given as strings into SCons Nodes 🌸. By default SCons assumes all sources are files (so the default factory is File). Other useful source_factory values: Dir for when a Builder uses a directory as a source, and Entry for when a Builder can use files or directories (or both) as sources 🫶.

Example:

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

CollectBuilder = Builder(action=collect, source_factory=Dir)
env = Environment()
env.Append(BUILDERS={'Collect': CollectBuilder})
env.Collect('archive', 'directory_name')

emitter — a function (or a list of functions) that messes with the target and source lists before dependencies get established and before the target(s) actually get built 💅. It can also be a string holding a construction variable that expands 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 pick the actual emitter function out of an emitter dictionary — that's the rule, periodt.)

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 construction environment to use for context.

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

Example:

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

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

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

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

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

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

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

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

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

multi — says whether this builder is allowed to be called multiple times for the same target file(s) 💖. The default is False, which means it can not be called multiple times for the same target file(s). Calling a builder multiple times for the same target just adds extra source files to the target — that's it. It is not allowed to change the environment associated with the target, specify additional environment overrides, or associate a different builder with the target. No sneaky business 🚫.
env — a construction environment that can be used to fetch source code using this Builder. (Quick note: this environment is not used for normal builds of normal target files — those 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 literally anything that can be converted into an Action object (peep 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 construction environment to use for context, and for_signature is a Boolean that tells the function whether it's being called to generate a build signature (as opposed to actually running the command) 🧚. Since the build signature is what decides whether something gets rebuilt, the function should leave out any elements that don't affect whether a rebuild should be triggered whenever for_signature is true. Little optimization moment 💅.

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. Pick one, bestie.

src_builder — names a builder to use when a source file name suffix doesn't match any of the suffixes of the builder 🌈. Using this argument produces a multi-stage builder.
single_source — declares 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 gets passed multiple source files is to make sure all the source file extensions match 🎀. If it's legal for this builder to be called with a list of source files with different extensions, you can suppress that check by setting source_ext_match to False or some other non-true value. In that case, scons will use the suffix of the first specified source file to select the appropriate action from the action dictionary. iykyk.

In the following example, the setting of source_ext_match keeps 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 construction environment that can be used to fetch source code using this Builder. (Again, this environment is not used for normal builds of normal target files — those 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 that specified directory. If chdir is not a string or Node and is non-zero, then scons will change to the target file's directory.

Big note bestie: scons will not automatically modify its expansion of construction variables like $TARGET and $SOURCE when you use the chdir keyword argument 😭 — that is, the expanded file names will still be relative to the project top directory, and consequently incorrect relative to the chdir directory. Builders created using the chdir keyword argument will need to use construction variable expansions like ${TARGET.file} and ${SOURCE.file} to use just the filename portion of the targets and source 👑.

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

🚨 Warning

Okay so first, a lil warning about threads 🫶 — Python only tracks one current directory location, even if there are multiple executing threads. Which literally means the chdir argument will not work with SCons in multi-threaded mode (that's the -j option, bestie 😭), because individual worker threads spawned by SCons interfere with each other when they start changing directory. Not a vibe. 💀

Any additional keyword arguments you supply when a Builder object is created (aka when the Builder function gets called) will be set in the executing construction environment when the Builder object is called. The canonical example here would be setting a construction variable to the repository of a source code system. 👑

And any such keyword arguments supplied when a Builder object is called will only be associated with the target created by that particular Builder call (plus any other files built as a result of the call). These extra keyword arguments get passed to these three: command generator functions, function Actions, and emitter functions. ✨

🚨 Debugging lore drop: when you're debugging errors in a custom builder method, remember the builder's Action is executed asynchronously — the builder call in the SConscript only instructs SCons what you want built, while the actual building is scheduled later (if necessary) by the taskmaster. So wrapping a builder call in a try block is not useful, because success in the builder call is not the same as the build itself succeeding. If you need it, code a builder's Action to exit with a useful error message indicating the problem in the SConscript file. Attempting programmatic recovery from build errors is rarely useful. Periodt. 💅

🎀 Action Objects 🎀

The Builder factory function will turn its action keyword argument into an appropriate internal Action object, and so will the Command function. You can also explicitly create Action objects — for passing to Builder or other functions that take actions as arguments — by calling the Action factory function. This may be 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 lets you configure an Action object more flexibly. For example, to control the message printed when the action is taken, you need to create the action object using Action. 🌸

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

If action is already an Action object — the object is simply returned. No notes. ✅
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 construction environment 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 Action returns None. 🫥

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

The optional second argument to Action is used to control the output which is printed when the Action is actually performed. If this parameter is omitted, or if the value is an empty string, a default output depending on the type of the action is used. For example, a command-line action will print the executed command. The following argument types are accepted:

If the second argument is a string, or if the cmdstr keyword argument is supplied, the string defines what is printed. Substitution is performed on the string before it is printed. The string typically contains substitutable variables, notably $TARGET(S) and $SOURCE(S), or consists of just a single variable which is optionally defined somewhere else. SCons itself heavily uses the latter variant. 🔥
If the second argument is a function, or if the strfunction keyword argument is supplied, the function will be called to obtain the string to be printed when the action is performed. The function must accept three keyword arguments: target, source and env, with the same interpretation as for a callable action argument above. The function is responsible for handling any required substitutions.
If the second argument is None, or if cmdstr=None is supplied, output is suppressed entirely. 🤫

⚠️ The cmdstr and strfunction keyword arguments may not both be supplied in a single call to Action. Pick one, bestie, you can't have both. 💅

Printing of action strings is affected by the setting of $PRINT_CMD_LINE_FUNC.

Examples:

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

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

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

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

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

Any additional positional arguments, if present, may either be construction variables or lists of construction variables whose values will be included in the signature of the Action (the build signature) 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 construction variable 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 construction variable 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 construction variables like $TARGET and $SOURCE when using the chdir parameter — that is, the expanded file names will still be relative to the project top directory, and consequently incorrect relative to the chdir directory. Builders created using the chdir keyword argument will need to use construction variable 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`

Okay so if you pass this, it means your Action is that girl who can build a whole bunch of target files at once by chewing through multiple independent source files at the same time. 💅 (The canonical example is "batch compilation" — yeeting multiple object files at one single compiler invocation, like Microsoft Visual C++ does. Werk.)

If batch_key evaluates True and it's not a callable object, then the configured Action object makes scons collect every target built with that Action object and configured with the same construction environment, and slam them all into single invocations of that Action object's command line or function. ✨

Command lines will typically want to use the $CHANGED_SOURCES construction variable (and maybe $CHANGED_TARGETS too, bestie) so you only hand over the sources that have literally actually changed since their targets got built. No cap.

Example:

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

But wait, there's more. The batch_key argument can also be a callable function that returns a key used to identify different "batches" of target files to collect up 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 construction environment 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 whatever logic is appropriate to decide how multiple invocations should get batched together. 🌸 For example, a batch_key function might decide to return the value of a specific construction variable from env, which causes scons to batch-build targets that have matching values of that construction variable. Or it might return the Python id() of the entire construction environment, in which case scons will batch-build all targets configured with the same construction environment. 🦋

Returning None indicates that that particular target should not be part of any batched build — instead it gets built by a separate invocation of action's command or function. Main character behavior. 👑

Example:

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

Miscellaneous Action Functions 🎀

SCons supplies Action functions that arrange for all kinds of common file and directory manipulations to happen. These are conceptually similar to "tasks" in the Ant build tool, even though the implementation is a little different. 😌

Important glow-up note: these functions do not actually do the thing at the time you call them. They're factory functions — they hand you back an Action object that gets executed at the appropriate time. So don't be surprised when nothing happens immediately. She's just pre-gaming. 🍓

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

First: if you need to perform the action right then, while the SConscript file is being read, you can use the Execute global function:

Execute(Touch('file'))

Second: you can use these functions to supply Actions in a list for use by the env.Command method. This lets you perform more complicated sequences of file manipulation without relying on any platform-specific external commands. Slay. 🌈

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 a string — just like the POSIX chmod command. 💅

Examples:

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

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

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

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

The behavior of Chmod is limited on Windows and on WebAssembly platforms — see the notes in the Python documentation for os.chmod[8], which is the underlying function. 📝

`Copy(dest, src)`

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

Examples:

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

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

`Delete(entry, [must_exist])`

Returns an Action that deletes the specified entry, which may be a file or a directory tree. 😭 If a directory is specified, the entire directory tree gets removed. (Dramatic, but that's what you asked for.)

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 — meaning 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 the intermediate directories it needs along the way. ✨ 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. 🎀 (Yes, like the real touch. No, it does not give the file feelings.)

Examples:

Execute(Touch('file_to_be_touched'))

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

Variable Substitution 💖

Before executing a command, scons performs parameter expansion (that's substitution, bestie) on the string that makes up the action part of the builder. The format of a substitutable parameter is ${expression}. 🌸

If expression refers to a variable, the braces in ${expression} can be omitted — unless the variable name is immediately followed by a character that could be interpreted as part of the name, or by Python syntax like [ (for indexing/slicing) or . (for attribute access — peep Special Attributes below). 👀

If expression refers to a construction variable, it (including the $ or ${ }) is replaced with the value of that variable in the construction environment at the time of execution. ⭐ If expression looks like a variable name but is not defined in the construction environment, it gets replaced with an empty string. If expression refers to one of the Special Variables (see below), the corresponding value of that variable is substituted. expression may also be a Python expression to be evaluated — see Python Code Substitution below for the deets.

SCons uses the following rules when converting construction variables into command line strings:

If the value is a string it is interpreted as space delimited command line arguments.
If the value is a list it is interpreted as a list of command line arguments. Each element of the list is converted to a string.
Anything that is not a list or string is converted to a string and interpreted as a single command line argument.
Newline characters (\n) delimit lines. The newline parsing is done after all other parsing, so it is not possible for arguments (e.g. file names) to contain embedded newline characters. 💀
For a literal $ use $$. For example, $$FOO will be left in the final string as $FOO.

When a build action is executed, a hash of the command line is saved, together with other information about the target(s) built by the action, for future use in rebuild determination. This is called the build signature (or build action signature). 🔥

The escape sequence $( subexpression $) may be used to indicate parts of a command line that may change without causing a rebuild — that is, which are not to be included when calculating the build signature. All text from $( up to and including the matching $) will be removed from the command line before it is added to the build signature, while only the $( and $) will be removed before the command is executed. Periodt.

For example, the command line string:

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

would execute the command:

echo Last build occurred $TODAY. > $TARGET

but the build signature added to any target files would be computed from:

echo Last build occurred  . > $TARGET

While construction variables are normally swapped in directly, if a construction variable's value is a callable Python object — like a function, or a class packing a __call__ method — bestie, that object gets called during substitution. 💅

That callable has got to accept four arguments: target, source, env and for_signature. Let's break it down:

source is a list of source nodes
target is a list of target nodes
env is the construction environment to use for context
for_signature is a boolean value that tells the callable if it's being called for the purpose of generating a build signature

And because the build signature is what decides rebuilds, any variable elements that don't affect whether a rebuild should be triggered should be left out of the returned string when for_signature is true. (Peep $( and $) above for the syntax, iykyk.)

SCons will drop whatever the callable returns straight 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")

Quick reminder, bestie: substitution happens when $BAR is actually used in a builder action. So env['BAR'] will be exactly what you set it to: "$FOO baz". That makes debugging lowkey treacherous 😭 — the substituted result isn't available while the SConscript files are being interpreted, so <italic>print</italic> can't see it either. But you can do the substitution on demand by calling the env.subst method for exactly this purpose. 🫶

You can also use this feature to pass arguments to a callable variable — just make a callable class that stores the passed arguments in the instance, then uses them inside __call__ when the instance gets called. ⚠️ Note that in this case, the entire variable expansion has to be wrapped in curly braces, so the arguments get associated with the instantiation of the class:

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

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

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

✨ Substitution: Special Variables ✨

Besides regular construction variables, scons serves up the following Special Variables for use in expanding commands, and they eat every time 🔥

$CHANGED_SOURCES — The file names of all sources of the build command that have changed since the target was last built.
$CHANGED_TARGETS — The file names of all targets that would be built from sources that have changed since the target was last built.
$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.
$SOURCES — The file names of the sources of the build command.
$TARGET — The file name of the target being built, or the file name of the first target if multiple targets are being built.
$TARGETS — The file names of all targets being built.
$UNCHANGED_SOURCES — The file names of all sources of the build command that have not changed since the target was last built.
$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 🚫 — no assigning to them, no using them as construction variables. SCons computes them in a context-dependent manner and they are not retrieved from a construction environment. Periodt.

For example, this 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

And in that same example, a string like ${SOURCES[1]} would expand to: bar.c. 🦋

💖 Substitution: Special Attributes 💖

A variable name can have the following modifiers tacked on inside the enclosing curly braces, to access properties of the interpolated string. These are the special attributes, bestie:

base — The base path of the file name, including the directory path but excluding any suffix.
dir — The name of the directory in which the file exists.
file — The file name, minus any directory portion.
filebase — Like file but minus its suffix.
suffix — Just the file suffix.
abspath — The absolute path name of the file.
relpath — The path name of the file relative to the project top directory.
posix — The path with directories separated by forward slashes (/). Sometimes necessary on Windows systems when a path references a file on other (POSIX) systems.
windows — The path with directories separated by backslashes (\\). Sometimes necessary on POSIX-style systems when a path references a file on other (Windows) systems. win32 is a (deprecated) synonym for windows.
srcpath — The directory and file name to the source file linked to this file through 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 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 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.

Check it — the specified target expands like this 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 even be combined, like ${TARGET.srcpath.base), ${TARGET.file.suffix}, etc. 🌈

🎀 Python Code Substitution 🎀

If a substitutable expression using the notation ${expression} doesn't appear to match any of the other substitution patterns, it gets evaluated as a Python expression. 🙈 This uses Python's eval function, with the globals parameter set to the current environment's set of construction variables, and the result is substituted in.

So in this 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

echo BAR > foo.out

depending on the current value of env['COND'] when the command is executed. ⏰ And bestie, 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, that final value is the one that gets used.

Here's a more complete example — note that COND, FOO, and BAR are all construction variables, and their values get substituted into the final command. FOO is a list, so its elements get 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

And honestly, the way that Python expression evaluation is how the special attributes are substituted is iconic — they're simply attributes of the Python objects that represent $TARGET, $SOURCES, etc., which SCons hands over to eval, which returns the value. 👑

⚠️ Caution: Use of the Python eval function is considered to have security implications, since, depending on input sources, arbitrary unchecked strings of code can be executed by the Python interpreter. Although SCons makes use of it in a somewhat restricted context, you should be aware of this issue when using the ${python-expression-for-subst} form. 💀

🌸 Scanner Objects 🌸

Scanner objects are used to scan specific file types for implicit dependencies — think embedded preprocessor/compiler directives that cause other files to be included during processing. 🧚

SCons ships with a number of pre-built Scanner objects, so it's usually only necessary to set up Scanners for new file types. You do this by calling the Scanner factory function. 🫶

Scanner accepts the following arguments — only function is required; the rest are optional:

function — okay so this is the actual worker bee 🐝. It's a function that "scans" a given Node (usually a file) and hands back a list of Nodes for any implicit dependencies (usually files) that'll get tracked for that Node. It must take three required arguments — node, env and path — plus an optional fourth, arg. Here's the breakdown, bestie: node is the internal SCons node repping the file you're scanning, env is the construction environment to use during the scan, and path is a tuple of directories that can be searched for files, generated by the optional scanner path_function. And if the argument parameter was supplied when the Scanner object was created? That gets passed as the arg parameter when the function is called. But argument is optional, so heads up: your scanner function might get called with no arg at all 🙈.

Inside the function you've got tools ✨: str(node) fetches the name of the file, node.dir fetches the directory the file lives in, node.get_contents() fetches the file contents as bytes, and node.get_text_contents() fetches them as text.

The scanner function should account for any directories listed in the path parameter when it's figuring out whether possible dependencies exist. External tools like the C/C++ preprocessor get handed lists of directories to search for source file inclusion directives (e.g. #include "myheader.h"). That list gets generated from the relevant path variable (e.g. $CPPPATH for C/C++). And the Scanner can be told to pass that same list on to the scanner function via the path parameter so it can search in the same places 🎯. You enable that at Scanner creation time via the path_function argument.

Now, instead of a scanner function, you can hand it a dictionary as the function parameter 👀. The dictionary must map keys (like file suffixes) to other Scanner objects. A Scanner created this way acts as a dispatcher: its skeys parameter gets automatically populated with the dictionary's keys, which signals that the Scanner handles Nodes that'd be selected by those keys; then the mapping gets used to pass the file along to a different Scanner — one that wouldn't have been selected to handle that Node based on its own skeys.

Note that the file to scan is not guaranteed to exist when the scanner is called — it could be a generated file that hasn't been generated yet — so your scanner function has to be tolerant of that. No cap.

While lots of scanner functions work on source code files by hunting for known patterns in the code, they can genuinely do whatever they need to 🤷. Like, the Program Builder gets assigned a target_scanner which examines the list of libraries supplied for the build ($LIBS) and decides whether to add them as dependencies — it does not look inside the built binary. Iconic behaviour honestly.

It's up to the scanner function to decide whether or not to generate an SCons dependency for candidates it identifies by scanning. Dependencies are a key part of how SCons operates, enabling both rebuild determination and correct ordering of builds. It's particularly important that generated files which are dependencies get added into the Node graph, or use-before-create failures are likely 💀. But not everything needs tracking as a dependency. In some cases, implementation-provided header files change infrequently but get included very widely, so tracking them in the SCons node graph could get quite expensive for limited benefit — think, for example, the C standard header file string.h. The scanner function isn't passed any special info to help make that choice, so the decision-making encoded in the scanner function must be carefully considered 🧠.

name — the name to use for the Scanner. It's mainly used to identify the Scanner internally. Default value is "NONE".
argument — if specified, gets passed to the scanner function function and the path function path_function when they're called, as the optional parameter each of those functions takes.
skeys — Scanner key(s) indicating the file types this scanner is associated with. Used internally to pick 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 this Scanner knows how to scan. If skeys is a string, it gets expanded into a list by the current environment 💫.
path_function — if specified, a function to generate paths to pass to the scanner function to search while generating dependencies. The function must take five arguments: a construction environment, 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 (and since argument is optional, the function may be called without this argument, so path_function should be prepared for that, fr fr). It must return a tuple of directories that can be searched for files to be returned by this Scanner object.

The FindPathDirs function can be called to return a ready-made path_function for a given construction variable name, which is often easier than writing your own function from scratch 🫶. For example, path_function=FindPathDirs('CPPPATH') means the scanner function will get called with the paths extracted from $CPPPATH in the construction environment env, passed as the path parameter to the scanner function.

node_class — the class of Node that should be returned by this Scanner object. Any strings or other objects returned by the scanner function that aren't of this class get 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 takes a string or other object and turns it into the appropriate class of Node to be returned by this Scanner object, as indicated by node_class.
scan_check — a Python function taking two arguments, a Node (file) and a construction environment, and returning whether the Node should, in fact, be scanned for dependencies. This check can eliminate unnecessary calls to the scanner function when, for example, the underlying file represented by a Node doesn't exist yet 👻.
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 won't recurse. Recursion is needed when the files returned by the scanner may themselves contain further file dependencies — like with preprocessor #include lines 👑. A value that evaluates true enables recursion; recursive may be a callable function, in which case it gets called with a list of Nodes found and should return a list of Nodes that should be scanned recursively; that's how you select a specific subset of Nodes for additional scanning.

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

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

XYZScanner = Scanner(xyz_scan)

SourceFileScanner.add_scanner('.xyz', XYZScanner)

env.Program('my_prog', ['file1.c', 'file2.f', 'file3.xyz'])

🛠️ Tool Modules 🛠️

Custom tools can be added to a project either by dropping them in the site_tools subdirectory of a configured site directory, or in a location you specify with the toolpath keyword argument to Environment 🌸. You then have to arrange to call a tool to put it into effect — either as part of the list given to the tools keyword argument at construction environment initialization, or by calling env.Tool.

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

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

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

When looking up tool specification modules, directories specified via toolpath are considered before the existing tool path (site_tools subdirectories of the default or specified site directories), which are in turn considered before built-in tools 🔥. For example, adding a tool specification module gcc.py to the toolpath directory would override the built-in gcc tool. The toolpath is saved in the environment and will be used by subsequent calls to the env.Tool method, as well as by env.Clone.

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

A tool specification module is a form of Python module, looked up internally using the Python import mechanism, so a tool can consist either of a single Python file taking the name of the tool (e.g. mytool.py) or a directory taking the name of the tool (e.g. mytool/) which contains at least an __init__.py file 📁. A tool specification module has two required entry points:

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

Modify the construction environment env to set up necessary construction variables, Builders, Emitters, etc., so the facilities represented by the tool can be executed 🫡. Take care not to overwrite construction variables which may have been explicitly set by the user; retain and/or append instead. For example:

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

generate — this one may use any keyword arguments that the user hands over via kwargs to switch up how it initializes stuff.
exists(env) — return a truthy value if the tool can actually be called in the context of env, otherwise hand back a falsy value. Usually that means looking up one or more known programs using the PATH from the env you gave it, but fr the tool can make that exists decision literally any way it wants.

Note — rn, user-added tools do not automatically have their exists function called. So the recommendation is that you write your generate function defensively, bestie: don't just assume any necessary existence checks already happened, because they didn't. This is expected to be a temporary limitation, and you should still provide the exists function anyway. 🫶

An element of the tools list can also be a function or some other callable object (including a Tool object that came back from a previous call to Tool), and in that case the Environment function will directly call that object to update the new construction environment. No tool lookup happens in this case, periodt.

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

env = Environment(tools=[my_tool])

An element of the tools list can also be a two-element list or tuple shaped like (toolname, kw_dict). SCons searches for the tool specification module toolname like we described above, then passes kw_dict — which must be a dictionary, no exceptions — as keyword arguments to the tool's generate function. The generate function can use those arguments to change up the tool's behavior by setting up the environment in different ways or otherwise switching up its initialization. 💅

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

def exists(env):
    return True

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

The tool specification (my_tool in that example) can use the $PLATFORM variable from the construction environment it's passed to customize the tool for different platforms. 🌈

Tools can be "nested" too — meaning they can live inside a subdirectory in the toolpath. A nested tool name uses a dot to represent a directory separator, and honestly that's giving very much filesystem energy:

# namespaced builder
env = Environment(ENV=os.environ.copy(), tools=['SubDir1.SubDir2.SomeTool'])
env.SomeTool(targets, sources)

# Search Paths
# SCons\Tool\SubDir1\SubDir2\SomeTool.py
# SCons\Tool\SubDir1\SubDir2\SomeTool\__init__.py
# .\site_scons\site_tools\SubDir1\SubDir2\SomeTool.py
# .\site_scons\site_tools\SubDir1\SubDir2\SomeTool\__init__.py

🌍 SYSTEM-SPECIFIC BEHAVIOR 🌍

scons and its configuration files are super portable, mostly because it's implemented in Python. But there are a few portability issues just lurking, waiting to trap the unwary. 🙈

🎀 .C File Suffix 🎀

scons handles the upper-case .C file suffix differently depending on what the underlying system can do. On a case-sensitive system like Linux or UNIX, scons treats a file with a .C suffix as a C++ source file. On a case-insensitive system like Windows, scons treats a file with a .C suffix as a C source file. Same letters, completely different vibe check. 💀

🧚 Fortran File Suffixes 🧚

There are several ways source file suffixes impact how SCons behaves when you're working with Fortran language code (not all of them are system-specific, but they're all included here for completeness, because we do not gatekeep).

Since the Fortran language has evolved through multiple standards editions, projects might need to handle files from different language generations differently. So for this, SCons dispatches to a different compiler dialect setup (expressed as a set of construction variables) depending on the file suffix. By default, all of these setups start out the same, but individual construction variables can be modified as needed to tune a given dialect. Each of these dialects has a tool specification module whose documentation describes the construction variables associated with that dialect:

.f (as well as .for and .ftn) in fortran; (construction variables start with FORTRAN)
.f77 in f77; (construction variables start with F77)
.f90 in f90; (construction variables start with F90)
.f95 in f95; (construction variables start with F95)
.f03 in f03; (construction variables start with F03)
.f08 in f08 (construction variables start with F08).

While SCons recognizes multiple internal dialects based on filename suffixes, the convention of the various available Fortran compilers is to assign an actual meaning to only two of these suffixes:

.f (as well as .for and .ftn) refers to the fixed-format source code that was the only available option in FORTRAN 77 and earlier.
.f90 refers to free-format source code, which became available as of the Fortran 90 standard.

Some compilers recognize suffixes which correspond to Fortran specifications later than F90 as equivalent to .f90 for this purpose, while some do not — check the documentation for your compiler, no cap. An occasionally suggested policy suggestion is to use only .f and .f90 as Fortran filename suffixes. The fixed/free form determination can usually be controlled explicitly with compiler flags (e.g. -ffixed-form for gfortran), overriding any assumption that may be made based on the source file suffix.

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

For dialects from F90 on (including the generic FORTRAN dialect), a suffix of .mod is recognized for Fortran modules. These files are a side effect of compiling a Fortran source file containing module declarations, and they must be available when other code which declares that it uses the module gets processed. SCons does not currently have integrated support for submodules, introduced in the Fortran 2008 standard — the invoked compiler will produce results, but SCons will not recognize .smod files as tracked objects. 😭

On a case-sensitive system such as Linux or UNIX, a file with an upper-cased suffix from the set .F, .FOR, .FTN, .F90, .F95, .F03 and .F08 is treated as a Fortran source file which shall first be run through the standard C preprocessor. The lower-cased versions of these suffixes do not trigger this behavior. On systems which do not distinguish between upper and lower case in filenames, this behavior is not available, but files suffixed with either .FPP or .fpp are always passed to the preprocessor first. This matches the convention of gfortran from the GNU Compiler Collection, and is also followed by certain other Fortran compilers. For these two suffixes, the generic FORTRAN dialect will be selected.

SCons itself does not invoke the preprocessor — that is handled by the compiler — but it adds construction variables which are applicable to the preprocessor run. You can see this difference by examining $FORTRANPPCOM and $FORTRANPPCOMSTR, which are used instead of $FORTRANCOM and $FORTRANCOMSTR for that dialect. ✨

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

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

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

In practice, users can sidestep the whole issue by adopting these guidelines:

When using Cygwin's gcc for compiling, use the Cygwin-supplied Python interpreter to run scons.
When using Microsoft Visual C++ (or some other "native" Windows compiler), use the python.org, Microsoft Store, ActiveState or other native version of Python to run scons.

This discussion largely applies to the msys2 environment as well (with the use of the mingw compiler toolchain), in particular the recommendation to use the msys2 version of Python if you're running scons from inside an msys2 shell.

🦋 Windows: `scons.bat` file 🦋

On Windows, if scons is executed via a wrapper scons.bat batch file, there are (at least) two ramifications. Note this is no longer the default — scons installed via Python's pip installer will have a scons.exe which does not have these limitations:

First, Windows command-line users that want to use variable assignment on the command line may have to put double quotes around the assignments, otherwise the Windows command shell will consume those as arguments to itself, not to scons:

scons "FOO=BAR" "BAZ=BLEH"

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

⭐ MinGW ⭐

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

✨ ENVIRONMENT ✨

Okay so here's the tea bestie: scons is not generally controlled by the environment variables you set in the shell you used to invoke it. It just… leaves all that up to whoever wrote the SConscript file, letting them import whatever they want if they feel like it. main character energy of the SConscript authors tbh.

BUT. 💅 The following variables are imported by scons itself if you've set them:

SCONS_LIB_DIR — tells scons where the directory containing the scons Python module directory lives. Normally scons can figure this out on its own, but sometimes — like when you're working with a source release — you gotta spell it out yourself (for example, /home/aroach/scons-src-0.01/src/engine). 🗂️
SCONSFLAGS — a string of options that scons will use on top of whatever you pass on the command line. This is your "stop retyping the same flags every single time" bestie. Important detail though: the contents of SCONSFLAGS get considered before any command-line options, so if you need to override something in SCONSFLAGS, the command line is right there to do it. 👑
SCONS_CACHE_MSVC_CONFIG — (Windows only 🪟). If you set this, the shell environment variables that get generated while setting up the Microsoft Visual C++ compiler (and/or Build Tools) get saved to a cache file, so those settings persist across scons invocations. Generating that info is genuinely kind of expensive, so this option can help performance where scons gets run a lot — think Continuous Integration setups. ⚡
- If you set it to a True-like value ("1", "true" or "True"), it caches to a file named scons_msvc_cache.json in the user's home directory. 🏠
- If you set it to a pathname, it uses that pathname for the cache.
- > Heads up bestie: this implementation may still be somewhat fragile. If problems show up, just remove the cache file — recreating it with fresh info normally resolves any issues. SCons ignores failures reading or writing the cache file and will silently revert to non-cached behavior in those cases. 🙈
- New in 3.1 (experimental). The default cache file name was changed to its present value in 4.4, and contents were expanded. 📝

🫶 SEE ALSO 🫶

The SCons User Guide at https://scons.org/doc/production/HTML/scons-user.html
The SCons Design Document (old)
The SCons Cookbook at https://scons-cookbook.readthedocs.io for examples of how to solve various problems with SCons. 🍳
SCons source code on GitHub[9] 🔥
The SCons API Reference https://scons.org/doc/production/HTML/scons-api/index.html (for internal details)

👑 AUTHORS 👑

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

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

🌈 AUTHOR 🌈

The SCons Development Team

🎀 COPYRIGHT 🎀

📎 NOTES 📎

LLVM specification — https://clang.llvm.org/docs/JSONCompilationDatabase.html
JEP 313 — https:openjdk.java.net/jeps/313
https://learn.microsoft.com/en-us/cpp/build/reference/vcxproj-file-structure — https://learn.microsoft.com/en-us/cpp/build/reference/vcxproj-file-structure
https://learn.microsoft.com/en-us/visualstudio/extensibility/internals/solution-dot-sln-file — https://learn.microsoft.com/en-us/visualstudio/extensibility/internals/solution-dot-sln-file
optparse documentation — https://docs.python.org/3/library/optparse.html
If no_progress is set via SetOption in an SConscript file (but not if set in a site_init.py file) there will still be an initial status message about reading SConscript files since SCons has to start reading them before it can see the SetOption. 😭
http://www.opensource.org/licenses/alphabetical — http://www.opensource.org/licenses/alphabetical
os.chmod — https://docs.python.org/3/library/os.html#os.chmod
on GitHub — https://github.com/SCons/scons

And that's the whole page bestie, we made it, absolutely ate and left no crumbs. ✨ This was SCons 4.11, released Wed, 26 Aug 2026 21:18:42 -0700 — yes the man page is literally called SCONS(1) and yes we read every single word of it. go build something iconic. 💅🦋🌸

📦 where this page comes from

arch rolling: scons 4.11.1-1 · MIT
fedora 44: python3-scons 4.11.1-1.fc44 · MIT AND DocBook-Stylesheet
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-11-03: a language model's rewrite of the original, under its terms

SCONS(1)

💅 SCONS(1) — the SCons manual, but make it make sense 💅

🌸 NAME 🌸

🎀 SYNOPSIS 🎀

🦋 DESCRIPTION 🦋

🎯 Target Selection 🎯

✨ OPTIONS ✨

✨ the rest of the options, we're so close 🫶

📜 SCONSCRIPT FILE REFERENCE 📜

🧚 SConscript Files 🧚

🎀 Construction Environments 🎀

🛠️ Tools 🛠️

🦋 386asm

🦋 aixc++

🦋 aixcc

🦋 aixf77

🦋 aixlink

🦋 applelink

🦋 ar

🦋 as

🦋 bcc32

🦋 cc

🦋 clang

🦋 clangxx

🦋 compilation_db

🦋 cvf

🌸 cXX 🌸

🐧 cyglink 🐧

✨ default ✨

🍓 dmd 🍓

📚 docbook 📚

🎀 dvi 🎀

📄 dvipdf 📄

🦋 dvips 🦋

⭐ f03 ⭐

💜 f08 💜

🌟 f77 🌟

f90 🌈

f95 ✨

fortran 🧚

g++ 💜

g77 🎀

gas ⛽

gcc 🌸

gdc 🦋

gettext 🌍

gfortran 🔥

gnulink 🔗

gs 👻

hpc++ 💻

hpcc 🖥️

hplink 🔌

icc 🧊

icl 🟦

ifl 🟪

ifort ⚡

ilink ⛓️

ilink32 ⛓️⛓️

install 📦

intelc 💠

jar 🫙

javac ☕

javah ☕🌿

latex 📄

ldc 🅳

lex 🔍

link 🔗✨

linkloc 🧷

m4 🪄

masm 🧱

midl 🪟

mingw 🐧🪟

msgfmt 🈯

msginit 🌱

msgmerge 🔀

mslib 🏛️

mslink 🔗

mssdk 🪟

msvc 🛠️

msvs 🎀

🦋 `386asm`

🦋 `aixc++`

🦋 `aixcc`

🦋 `aixf77`

🦋 `aixlink`

🦋 `applelink`

🦋 `ar`

🦋 `as`

🦋 `bcc32`

🦋 `cc`

🦋 `clang`

🦋 `clangxx`

🦋 `compilation_db`

🦋 `cvf`

`f90` 🌈

`f95` ✨

`fortran` 🧚

`g++` 💜

`g77` 🎀

`gas` ⛽

`gcc` 🌸

`gdc` 🦋

`gettext` 🌍

`gfortran` 🔥

`gnulink` 🔗

`gs` 👻

`hpc++` 💻

`hpcc` 🖥️

`hplink` 🔌

`icc` 🧊

`icl` 🟦

`ifl` 🟪

`ifort` ⚡

`ilink` ⛓️

`ilink32` ⛓️⛓️

`install` 📦

`intelc` 💠

`jar` 🫙

`javac` ☕

`javah` ☕🌿

`latex` 📄

`ldc` 🅳

`lex` 🔍

`link` 🔗✨

`linkloc` 🧷

`m4` 🪄

`masm` 🧱

`midl` 🪟

`mingw` 🐧🪟

`msgfmt` 🈯

`msginit` 🌱

`msgmerge` 🔀

CFile(), `env.CFile()`

Command(), `env.Command()`

CompilationDatabase(), `env.CompilationDatabase()`

CXXFile(), `env.CXXFile()`

DocbookEpub(), `env.DocbookEpub()`

DocbookHtml(), `env.DocbookHtml()`

DocbookHtmlChunked(), `env.DocbookHtmlChunked()`

DocbookHtmlhelp(), `env.DocbookHtmlhelp()`

`Library()`, `env.Library()` 🎀

`LoadableModule()`, `env.LoadableModule()` 🦋

`M4()`, `env.M4()` 🌸

`MOFiles()`, `env.MOFiles()` 💜

`MSVSProject()`, `env.MSVSProject()` 🔥

`target` 🎯

`variant` 🌈

`cmdargs` ⌨️

`cppdefines` 📝

`cppflags` 🚩

`cpppaths` 📂

`buildtarget` 🛠️

`runfile` 🏃

`DebugSettings` 🎀

`MSVSSolution()`, `env.MSVSSolution()` 🌈

RES(), `env.RES()`

RMIC(), `env.RMIC()`

RPCGenClient(), `env.RPCGenClient()`

RPCGenHeader(), `env.RPCGenHeader()`

RPCGenService(), `env.RPCGenService()`