SconsProcessOverview

SCons processes the commands in the SConstruct in order as they appear. These commands build a dependency tree. The dependency tree contains Node Objects that correspond to some sort of object to be built. Which Nodes to build in the dependency tree is determined by the command line arguments given by the user.

We now have a family of trees (a forest) that represent the topmost files to build. All of the files that are out of date are built. This process recurses to ensure all subsequent Nodes are built as needed.

The following is pseudo code for the overall process that SCons follows:

Pseudo Code

Read SConstruct as a Python script:
# Default Environment object is created.
# Tools do their checks and modify the Environment object.
# Regular Python code is executed as usual.
# SConscript() calls cause referenced SConscript files to be
# read/executed immediately.
# Methods of Environment object are used to update the dependency
# tree and manipulate SCons state.
# After the file is read, we have:
# a global dependency tree of the entire system,
# consisting of a tree of Node objects. A Node is usually a
# filesystem object, but can be an Alias or a Value node.
# Each Node contains:
# - a pointer to the corresponding Environment object
# - a command to execute to build that node,
# - a list of dependencies.
# Note the dependency tree may not be complete at this point;
# for example, source files which are generated as part of the build
# will be scanned for more dependencies before building the targets that depend on them.
command line arguments are "expanded" into a list of Nodes that we want built
# if the argument is a file, then a single file is built
# if the argument is a directory, then everything within that directory is built
# if an argument is an Alias, then everything the Alias names is built
# There are also default targets; ones specified with Default() and -u/-U and if nothing else, '.'.
if there is nothing to build, we're done
foreach Node:
recursively build all of its dependencies
check source dependencies for the Node
# check the .sconsign file
# use MD5 or signature method
if out of date, or MD5 mismatch
build the target using its associated command(s) and Environment
# The commands in the Node do the actual work in the build phase,
# normally by expanding an Env variable and passing it to a shell.

Categories of Commands

The commands you can use in the SConstruct or SConscript files can be categorized in by their intent:

Node Commands

These commands are used to create Nodes. They all return a Node or a list of Nodes.

Nodes are created by:

building a target

naming an existing target

specifying a pseudo target

composition of other existing targets

These commands actually build stuff. They can affect files and directories on the file-system. Note they only define how to build, but don't actually do anything (i.e. on the filesystem) at the time they are called. The actual building is only done if the target is part of the final target Node list (see the process above).

Admin/Bookkeeping Commands

These commands are for "admin" or bookkeeping purposes. They provide the "glue" between the various bits of the build system. Or from another perspective, they allow the entire build system to be decomposed into separate but coordinated parts.

Creates an Action object for the specified action. These are similar in concept to "tasks" in the Ant build tool, although the implementation is slightly different. These functions do not actually perform the specified action at the time the function is called, but instead return an Action object that can be executed at the appropriate time.