%scons; ]>

The heart of &SCons; is its Build Engine. The &SCons; Build Engine is a Python module that manages dependencies between external objects such as files or database records. The Build Engine is designed to be interface-neutral and easily embeddable in any software system that needs dependency analysis between updatable objects. The key parts of the Build Engine architecture are captured in the following quasi-UML diagram:

The point of &SCons; is to manage dependencies between arbitrary external objects. Consequently, the Build Engine does not restrict or specify the nature of the external objects it manages, but instead relies on subclass of the &Node; class to interact with the external system or systems (file systems, database management systems) that maintain the objects being examined or updated. The Build Engine presents to the software system in which it is embedded a Python API for specifying source (input) and target (output) objects, rules for building/updating objects, rules for scanning objects for dependencies, etc. Above its Python API, the Build Engine is completely interface-independent, and can be encapsulated by any other software that supports embedded Python. Software that chooses to use the Build Engine for dependency management interacts with it through Construction Environments. A Construction Environment consists of a dictionary of environment variables, and one or more associated &Scanner; objects and &Builder; objects. The Python API is used to form these associations. A &Scanner; object specifies how to examine a type of source object (C source file, database record) for dependency information. A &Scanner; object may use variables from the associated Construction Environment to modify how it scans an object: specifying a search path for included files, which field in a database record to consult, etc. A &Builder; object specifies how to update a type of target object: executable program, object file, database field, etc. Like a &Scanner; object, a &Builder; object may use variables from the associated Construction Environment to modify how it builds an object: specifying flags to a compiler, using a different update function, etc. &Scanner; and &Builder; objects will return one or more &Node; objects that represent external objects. &Node; objects are the means by which the Build Engine tracks dependencies: A &Node; may represent a source (input) object that should already exist, or a target (output) object which may be built, or both. The &Node; class is sub-classed to represent external objects of specific type: files, directories, database fields or records, etc. Because dependency information, however, is tracked by the top-level &Node; methods and attributes, dependencies can exist between nodes representing different external object types. For example, building a file could be made dependent on the value of a given field in a database record, or a database table could depend on the contents of an external file. The Build Engine uses a &Job; class (not displayed) to manage the actual work of updating external target objects: spawning commands to build files, submitting the necessary commands to update a database record, etc. The &Job; class has sub-classes to handle differences between spawning jobs in parallel and serially. The Build Engine also uses a &Signature; class (not displayed) to maintain information about whether an external object is up-to-date. Target objects with out-of-date signatures are updated using the appropriate &Builder; object.

More detailed discussion of some of the Build Engine's characteristics:

The Build Engine can be embedded in any other software that supports embedding Python: in a GUI, in a wrapper script that interprets classic Makefile syntax, or in any other software that can translate its dependency representation into the appropriate calls to the Build Engine API. describes in detail the specification for a "Native Python" interface that will drive the &SCons; implementation effort.

When building/updating the objects, the Build Engine operates as a single executable with a complete Directed Acyclic Graph (DAG) of the dependencies in the entire build tree. This is in stark contrast to the commonplace recursive use of Make to handle hierarchical directory-tree builds.

Dependency analysis is carried out via digital signatures (a.k.a. "fingerprints"). Contents of object are examined and reduced to a number that can be stored and compared to see if the object has changed. Additionally, &SCons; uses the same signature technique on the command-lines that are executed to update an object. If the command-line has changed since the last time, then the object must be rebuilt.

The output of Build Engine is customizable through user-defined functions. This could be used to print additional desired information about what &SCons; is doing, or tailor output to a specific build analyzer, GUI, or IDE.

&SCons; detects build failures via the exit status from the tools used to build the target files. By default, a failed exit status (non-zero on UNIX systems) terminates the build with an appropriate error message. An appropriate class from the Python library will interpret build-tool failures via an OS-independent API. If multiple tasks are executing in a parallel build, and one tool returns failure, &SCons; will not initiate any further build tasks, but allow the other build tasks to complete before terminating. A -k command-line option may be used to ignore errors and continue building other targets. In no case will a target that depends on a failed build be rebuilt.

As previously described, the &SCons; Build Engine is interface-independent above its Python API, and can be embedded in any software system that can translate its dependency requirements into the necessary Python calls. The "main" &SCons; interface for implementation purposes, uses Python scripts as configuration files. Because this exposes the Build Engine's Python API to the user, it is current called the "Native Python" interface. This section will also discuss how &SCons; will function in the context of two other interfaces: the &Makefile; interface of the classic &Make; utility, and a hypothetical graphical user interface (GUI).

The Native Python interface is intended to be the primary interface by which users will know &SCons;--that is, it is the interface they will use if they actually type &SCons; at a command-line prompt. In the Native Python interface, &SCons; configuration files are simply Python scripts that directly invoke methods from the Build Engine's Python API to specify target files to be built, rules for building the target files, and dependencies. Additional methods, specific to this interface, are added to handle functionality that is specific to the Native Python interface: reading a subsidiary configuration file; copying target files to an installation directory; etc. Because configuration files are Python scripts, Python flow control can be used to provide very flexible manipulation of objects and dependencies. For example, a function could be used to invoke a common set of methods on a file, and called iteratively over an array of files. As an additional advantage, syntax errors in &SCons; Native Python configuration files will be caught by the Python parser. Target-building does not begin until after all configuration files are read, so a syntax error will not cause a build to fail half-way.

An alternate &SCons; interface would provide backwards compatibility with the classic &Make; utility. This would be done by embedding the &SCons; Build Engine in a Python script that can translate existing &Makefile;s into the underlying calls to the Build Engine's Python API for building and tracking dependencies. Here are approaches to solving some of the issues that arise from marrying these two pieces: &Makefile; suffix rules can be translated into an appropriate &Builder; object with suffix maps from the Construction Environment. Long lists of static dependences appended to a &Makefile; by various "make depend" schemes can be preserved but supplemented by the more accurate dependency information provided by &Scanner; objects. Recursive invocations of &Make; can be avoided by reading up the subsidiary &Makefile; instead. Lest this seem like too outlandish an undertaking, there is a working example of this approach: Gary Holt's &Makepp; utility is a Perl script that provides admirably complete parsing of complicated &Makefile;s around an internal build engine inspired, in part, by the classic Cons utility.

The &SCons; Build Engine is designed from the ground up to be embedded into multiple interfaces. Consequently, embedding the dependency capabilities of &SCons; into graphical interface would be a matter of mapping the GUI's dependency representation (either implicit or explicit) into corresponding calls to the Python API of the &SCons; Build Engine. Note, however, that this proposal leaves the problem of designed a good graphical interface for representing software build dependencies to people with actual GUI design experience...