References

Last updated on 2025-04-16 | Edit this page

Running SCons

To run SCons:

BASH

$ scons

SCons will look for a configuration file called SConstruct and will build the default target(s).

To use a configuration file with a different name, use the --sconstruct option e.g.

BASH

$ scons --sconstruct=build-files/analyze

To build a specific target, provide it as an argument e.g.

BASH

$ scons isles.dat

If the target is up-to-date, SCons will print a message like:

OUTPUT

scons: Reading SConscript files ...
scons: done reading SConscript files.
scons: Building targets ...
scons: `isles.dat' is up to date.
scons: done building targets.

To see the actions SCons will run when building a target, without running the actions, use the --dry-run flag e.g.

BASH

$ scons --dry-run isles.dat

Alternatively, use the abbreviation -n.

BASH

$ scons -n isles.dat

Trouble Shooting

TBD

Configuration files

SCons uses Python as the configuration language. Tasks can be defined in Python class/function call syntax.

Tasks:

PYTHON

Command(
    target=["target"],
    source=["source1", "source2"]
    action=["action1", "action2"]
)

Each task has one or more targets, the files to be created, or built.
Each task has one or more sources, the depedencies that are needed to build the target.
Targets and sources can be passed as list via keyword arguments.
Each rule has one or more actions, commands to run to build the target using the sources.
Actions are provided as a list of strings via keyword arguments.

Dependencies:

If any source does not exist then SCons will look for a task to build it.
The order of rebuilding dependencies is declarative. You should not assume that they will be built in the order in which they are listed.
Dependencies must form a directed acyclic graph. A target cannot depend on a dependency which, in turn depends upon, or has a dependency which depends upon, that target.

Comments:

PYTHON

# SCons uses Python for its configuration language. This is a Python comment.

List continuation:

PYTHON

archive = [
    "isles.dat",
    "isles.png",
    "abyss.dat",
    "abyss.png",
    "sierra.dat",
    "sierra.png",
]

If a list of targets, sources, or actions is too long, an SConstruct file can become more difficult to read.
Python allows you to split up a list over multiple lines, to make them easier to read.
Python will combine the multiple lines into a single list

Cleaning targets:

SCons can clean specific targets with the --clean option

BASH

$ scons target --clean

and clean all targets with the . special target

BASH

$ scons . --clean

Alias targets:

SCons can define aliases as short-hand for collections of build targets.

PYTHON

target_nodes = Command(
    target=["target1", "target2"],
    source=["source"],
    action=["action"]
)
Alias("target_alias", target_nodes)

Alias targets are a short-hand for building target lists.

Special variables:

SCons has several special variables available for task construction. A few common use cases are mentioned here.

$SOURCE and $SOURCES[0] denote ‘the first source of the current task’.
$SOURCES denotes ‘the sources of the current task’.
$TARGET and $TARGETS[0] denote ‘the first target of the current task’.
$TARGETS denotes ‘the dependencies of the current task’.
$TARGET.filebase denotes ‘the stem of the first target of the current task’.

Builders:

SCons users can write custom builders for commonly re-used actions.

PYTHON

my_builder = Builder(
    action=["action"]
)
env = Environment(BUILDERS={"MyBuilder": my_builder})
env.MyBuilder(
    target=["target"],
    source=["source"]
)

Psuedo-builders:

SCons users can write custom pseudo-builders to handle common file types or Builder argument parsing.

PYTHON

import pathlib


def count_books(env, name, count_executable="python", count_source="count_words.py"):
    target = [f"{name}.dat"]
    source = [
        pathlib.Path("books") / f"{name}.txt",
        count_source,
    ]
    target_nodes = env.Command(
        target=target,
        source=source,
        action=["${count_executable} ${count_source} ${TARGET} ${SOURCES}"],
        count_executable=count_executable,
        count_source=count_source,
    )
    return target_nodes


env = Environment()
env.AddMethod("CountBooks", count_books)
env.CountBooks("isles")
env.CountBooks("abyss")

Defining and using variables:

SCons uses Python as the configuration language. Variables may be defined in Python syntax.

PYTHON

count_source="wordcount.py"
count_executable=f"python {count_source}"

A variable is assigned a value. For example, count_source is assigned the string "wordcount.py".
f-string syntax allows string construction from variables. The value of count_source will be used in the string construction of count_exectuable.

Suppress printing of actions:

SCons provides several mechanisms to control output. The -Q flag suppresses printing of progress messages. The --silent flag suppresses printing of the command actions. Individual task actions may suppress printing commands with a preceding @ symbol.

PYTHON

target_nodes = Command(
    target=["target"],
    source=["source"],
    action=["@action"],
)
Alias("target", target_nodes)

Prefix an action by @ to instruct SCons not to print that action.

Multiple configuration files:

SCons provides the option to call more than one configuration file with the SConscript function. These are conventionally named SConscript, but could take any file name.

PYTHON

SConscript("SConscript")
SConscript("configuration")

wildcard function:

SCons provides a Glob method to construct lists of files.

PYTHON

text_files=Glob("books/*.txt")

Looks for all files matching a pattern e.g. books/*.txt, and return these in a list.
e.g. text_files is set to ["books/abyss.txt", "books/isles.txt", "books/last.txt", "books/sierra.txt"].

List comprehensions:

Python has a list comprehension feature for constructing lists. In combination with the pathlib module, OS agnostic path manipulation can be performed on lists of files.

PYTHON

import pathlib
text_files = ["books/abyss.txt", "books/isles.txt", "books/last.txt", "books/sierra.txt"]
text_paths = [pathlib.Path(book) for book in text_files]
data_paths = [book.with_suffix("*.dat") for book in text_paths if book.parent == "books" and book.suffix == ".txt"]
data_files = [str(book) for book in book_paths]

Every string that matches books/*.txt in text_paths is replaced by *.dat and the strings are returned in a list.
e.g. if text_files is ["books/abyss.txt", "books/isles.txt", "books/last.txt", "books/sierra.txt"] this sets data_files to ["books/abyss.dat", "books/isles.dat", "books/last.dat", "books/sierra.dat"].
SCons >= 4.6 can operate on pathlib objects natively, so the final conversion back to strings is not strictly necessary.

Default targets:

SCons has a Default function for changing the default target list.

Unless otherwise specified, all targets are part of the default targets list.
If the Default method is called, only those targets explicitly included are part of the default targets list

PYTHON

Default(target_nodes)

Manuals

SCons Documentation includes

Glossary

action: The steps a build manager must take to create or update a file or other object.
assignment: A request that Python stores something in a variable.
builder: An re-useable SCons task definition with a predefined action.
build file: A synonym for configuration file
configuration file: A description of tasks for a build manager. Also called a build file.
build manager: A program, such as SCons, whose main purpose is to build or update software, documentation, web sites, data files, images, and other things.
default target: The target that is built if no target is specified when a build manager is run.
dependency: A synonym for source.
false dependency: This can refer to a dependency that is artificial. e.g. a false dependency is introduced if a data analysis script is added as a dependency to the data files that the script analyses.
function: A Python, SCons, or user-defined function that performs some operation, for example gets a list of files matching a pattern.
Glob: A pattern matching search function provided by SCons: Glob.
incremental build: The feature of a build manager by which it only rebuilds files that, either directory or indirectly, depend on a file that was changed.
Make: A popular build manager, from GNU, created in 1977.
Makefile: A build file used by Make, which, by default, are named Makefile.
prerequisite: A synonym for source.
Python: A commonly used programming language in computational science and engineering.
SCons: A Python-based, open-source build manager based on the ScCons build tool designed for a Software Carpentry Build competition in August 2000: [SCons][scons].
SConstruct: The primary configuration file for the SCons build manager.
SConscript: The conventional name for secondary configuration files for the SCons build manager. Also the generic name for the full set of SCons configuration files.
source: A file that a target depends on. If any of a target’s sources are newer than the target itself, the target needs to be updated. A target’s sources are also called its prerequisites or dependencies. If a target’s sources do not exist, then they need to be built first.
special variable: A reserved substitution variable that SCons will substitute with its value in action strings.
stem: The part of the target that was matched by the pattern rule. If the target is file.dat and the target pattern was %.dat, then the stem $* is file.
target: A thing to be created or updated, for example a file. Targets can have sources that must exist, and be up-to-date, before the target itself can be built or updated.
task: A specification of a target’s sources and what actions need to be executed to build or update the target.
variable: A symbolic name for something in an SCons configuration file.
wildcard: A pattern that can be specified in the Glob function search for files.