SCons Build-System

^{this section is based on the introductory pages on the SCons Wiki}

When SCons starts building the project, it creates its own environment with dependency trees, helper functions, builders and other stuff. The SCons environment is built in memory and some parts of it are saved to disk to speed up things on the next start. The definition of the build happens within this abstracted build environment. This often confuses people who used Makefiles, where “environment” is actually the System Environment.

the familiar operating system container with environment variables such as PATH, HOME etc. It is usually accessible via os.environ mapping in Python and therefore in SCons too. SCons does not automatically import any settings from System Environment automatically (like flags for compilers, or paths for tools), because it’s designed to be a cross platform tool with predictable behaviour. If you rely on any system PATHs or environment variables — you need to extract those settings explicitly in your build definition.

when SCons executes, it performs a build definition python script written by the user. By convention, this main script is called SConstruct and is located in the root of the source tree. It is a full featured Python module executed within a specifically prepared environment.

these files are also SCons scripts, but they are placed in subdirectories of the project. Typically they are used to organize hierarchical builds and are included from the main SConstruct file from the project root. Often, all of the actual build definitions reside in SConscript files in the sub-trees of the project.

The SCons buildsystem revolves around the metaphor of a Builder. This is a SCons object that you explicitly invoke from the scripts to define that there is something to build, thereby transforming a source into a target. So the target depends on the sources, and typically those source nodes were created by previous builder invocations. The use of Builders is declarative: it is a statement that a transformation (build step) has to happen, while the knowledge how this can be achieved is kept implicit within the buildsystem.

These are are functors that perform something (execute an external command or call a python function, for instance). A Builder retains a list of Actions needed to update its targets; those Actions are run when needed.

This is the basic building block of the dependency graph, while the arcs are created by using Builders: a Node represents a filesystem object, such as a file or directory which can also be a build result and as such does not exist yet. There are also Alias nodes and Value nodes which represent setting values. The power of SCons is in the fact that dependencies can be tracked and a build strategy can be derived, automatically, based on the structure of this dependency graph. And because the building blocks of that graph are abstract, users can represent the specifics of their build in an uniform way.

when defining a builder, SCons relies on modular scanner components to “understand” the source of the build step. They may scan source files to discover additional dependencies referenced inside. Thus, SCons comes with built-in knowledge about the source files and artefacts to be created by a typical build, and further types can be added through plug-ins.

any further, external component that adds Builders, Scanners and other helpers to SCons environments for use within scripts. There are special tools for configuring the platform to detect libraries and further requirements. Tools do not operate themselves, rather they will configure the build environment to reflect the needs of the specific build.

All key-value settings within a Construction Environment which are used to instruct SCons about builds. Construction Variables can describe compiler flags, locations of commands to execute, and many other characteristics. They are used for text substitution in command template strings for invocation of external commands, relying on the usual $VARIABLE syntax. Since the configuration of a SCons environment is defined by its Construction Variables, sub-environments with special configuration may be created.

SCons computes a signature for elements on the dependency graph using a cryptographic hash function which has the property that the same input repeatably leads to the same signature. The default function is MD5. Signatures are used throughout SCons to identify file contents, build command lines, or to identify cached build artefacts. Signatures are chained to determine if something needs to be re-built.

any Node or “build result” encountered through the definition of the build is a target. The actual build will be triggered by requesting a target, which typically might be just an executable known to reside at some location in the tree, or a target directory where the build is assumed to place build results. Special alias targets may be defined, based on other targets, to set off standard build sequences. Notably, a default target can be defined for the build.

Within our build system, we leverage the power of the Python programming language to create abstractions tailored to the needs of our project. Located in the admin/scons subdirectory, you’ll find a collection of Python modules to provide these building blocks.