SCons 4.7.0

Because SCons is written in the Python programming language, you need to have a Python interpreter available on your system to use SCons. Before you try to install Python, check to see if Python is already available on your system by typing python -V (capital 'V') or python --version at your system's command-line prompt. For Linux/Unix/MacOS/BSD type systems this looks like:

$ python -V
Python 3.9.15
    

If you get a version like 2.7.x, you may need to try using the name python3 - current SCons no longer works with Python 2.

You don't actually need to "install" SCons to use it. Nor do you need to "build" it, unless you are interested in producing the SCons documentation, which does use several tools to produce HTML, PDF and other output formats from files in the source tree. All you need to do is call the scons.py driver script in a location that contains an SCons tree, and it will figure out the rest. You can test that like this:

$ python /path/to/unpacked/scripts/scons.py --version
    

In some cases you may need several versions of SCons present on a system at the same time - perhaps you have an older project to build that has not yet been "ported" to a newer SCons version, or maybe you want to test a new SCons release side-by-side with a previous one before switching over. The use of an "uninstalled" package as described in the previous section can be of use for this purpose.

For cleaning up your build tree, SCons provides a "clean" mode, selected by the -c or --clean option when you invoke SCons. SCons selects the same set of targets it would in build mode, but instead of building, removes them. That means you can control what is cleaned in exactly the same way as you control what gets built. If you build the C example above and then invoke scons -c afterwards, the output on POSIX looks like:

% scons
scons: Reading SConscript files ...
scons: done reading SConscript files.
scons: Building targets ...
cc -o hello.o -c hello.c
cc -o hello hello.o
scons: done building targets.
% scons -c
scons: Reading SConscript files ...
scons: done reading SConscript files.
scons: Cleaning targets ...
Removed hello.o
Removed hello
scons: done cleaning targets.

And the output on Windows looks like:

C:\>scons
scons: Reading SConscript files ...
scons: done reading SConscript files.
scons: Building targets ...
cl /Fohello.obj /c hello.c /nologo
link /nologo /OUT:hello.exe hello.obj
embedManifestExeCheck(target, source, env)
scons: done building targets.
C:\>scons -c
scons: Reading SConscript files ...
scons: done reading SConscript files.
scons: Cleaning targets ...
Removed hello.obj
Removed hello.exe
scons: done cleaning targets.

Notice that SCons changes its output to tell you that it is Cleaning targets ... and done cleaning targets.

If you're used to build systems like Make you've already figured out that the SConstruct file is the SCons equivalent of a Makefile. That is, the SConstruct file is the input file that SCons reads to control the build.

You've already seen how SCons prints some messages about what it's doing, surrounding the actual commands used to build the software:

C:\>scons
scons: Reading SConscript files ...
scons: done reading SConscript files.
scons: Building targets ...
cl /Fohello.obj /c hello.c /nologo
link /nologo /OUT:hello.exe hello.obj
embedManifestExeCheck(target, source, env)
scons: done building targets.

These messages emphasize the order in which SCons does its work: all of the configuration files (generically referred to as SConscript files) are read and executed first, and only then are the target files built. Among other benefits, these messages help to distinguish between errors that occur while the configuration files are read, and errors that occur while targets are being built.

One drawback, of course, is that these messages clutter the output. Fortunately, they're easily disabled by using the -Q option when invoking SCons:

C:\>scons -Q
cl /Fohello.obj /c hello.c /nologo
link /nologo /OUT:hello.exe hello.obj
embedManifestExeCheck(target, source, env)

So this User's Guide can focus on what SCons is actually doing, the -Q option will be used to remove these messages from the output of all the remaining examples in this Guide.

You've just seen how to configure SCons to compile a program from a single source file. It's more common, of course, that you'll need to build a program from many input source files, not just one. To do this, you need to put the source files in a Python list (enclosed in square brackets), like so:

Program(['prog.c', 'file1.c', 'file2.c'])
       

A build of the above example would look like:

% scons -Q
cc -o file1.o -c file1.c
cc -o file2.o -c file2.c
cc -o prog.o -c prog.c
cc -o prog prog.o file1.o file2.o

Notice that SCons deduces the output program name from the first source file specified in the list--that is, because the first source file was prog.c, SCons will name the resulting program prog (or prog.exe on a Windows system). If you want to specify a different program name, then (as described in the previous section) you slide the list of source files over to the right to make room for the output program file name. Here is the updated example:

Program('program', ['prog.c', 'file1.c', 'file2.c'])
       

On Linux, a build of this example would look like:

% scons -Q
cc -o file1.o -c file1.c
cc -o file2.o -c file2.c
cc -o prog.o -c prog.c
cc -o program prog.o file1.o file2.o

Or on Windows:

C:\>scons -Q
cl /Fofile1.obj /c file1.c /nologo
cl /Fofile2.obj /c file2.c /nologo
cl /Foprog.obj /c prog.c /nologo
link /nologo /OUT:program.exe prog.obj file1.obj file2.obj
embedManifestExeCheck(target, source, env)

You've now seen two ways to specify the source for a program, one with a list of files:

Program('hello', ['file1.c', 'file2.c'])
    

And one with a single file:

Program('hello', 'hello.c')
    

You can actually put a single file name in a list, too, which you might prefer just for the sake of consistency:

Program('hello', ['hello.c'])
    

SCons functions will accept a single file name in either form. In fact, internally, SCons treats all input as lists of files, but allows you to omit the square brackets to cut down a little on the typing when there's only a single file name.

# The following two calls both work correctly:
Program('program1', 'program1.c')
Program('program2', ['program2.c'])
    

common_sources = ['file1.c', 'file2.c']

# THE FOLLOWING IS INCORRECT AND GENERATES A PYTHON ERROR
# BECAUSE IT TRIES TO ADD A STRING TO A LIST:
Program('program1', common_sources + 'program1.c')

# The following works correctly, because it's adding two
# lists together to make another list.
Program('program2', common_sources + ['program2.c'])
    

One drawback to the use of a Python list for source files is that each file name must be enclosed in quotes (either single quotes or double quotes). This can get cumbersome and difficult to read when the list of file names is long. Fortunately, SCons and Python provide a number of ways to make sure that the SConstruct file stays easy to read.

SCons also allows you to identify the output file and input source files using Python keyword arguments target and source. A keyword argument is an argument preceded by an identifier, of the form name=value, in a function call. The usage looks like this example:

src_files = Split('main.c file1.c file2.c')
Program(target='program', source=src_files)
    

Because the keywords explicitly identify what each argument is, the order does not matter and you can reverse it if you prefer:

src_files = Split('main.c file1.c file2.c')
Program(source=src_files, target='program')
    

Whether or not you choose to use keyword arguments to identify the target and source files, and the order in which you specify them when using keywords, are purely personal choices; SCons functions the same regardless.

In order to compile multiple programs within the same SConstruct file, simply call the Program method multiple times, once for each program you need to build:

Program('foo.c')
Program('bar', ['bar1.c', 'bar2.c'])
       

SCons would then build the programs as follows:

% scons -Q
cc -o bar1.o -c bar1.c
cc -o bar2.o -c bar2.c
cc -o bar bar1.o bar2.o
cc -o foo.o -c foo.c
cc -o foo foo.o

All builder methods return a list of Node objects that identify the target file or files that will be built. These returned Nodes can be passed as arguments to other builder methods.

It's worth mentioning here that SCons maintains a clear distinction between Nodes that represent files and Nodes that represent directories. SCons supports File and Dir functions that, respectively, return a file or directory Node:

hello_c = File('hello.c')
Program(hello_c)

classes = Dir('classes')
Java(classes, 'src')
      

Normally, you don't need to call File or Dir directly, because calling a builder method automatically treats strings as the names of files or directories, and translates them into the Node objects for you. The File and Dir functions can come in handy in situations where you need to explicitly instruct SCons about the type of Node being passed to a builder or other function, or unambiguously refer to a specific file in a directory tree.

There are also times when you may need to refer to an entry in a file system without knowing in advance whether it's a file or a directory. For those situations, SCons also supports an Entry function, which returns a Node that can represent either a file or a directory.

xyzzy = Entry('xyzzy')
    

The returned xyzzy Node will be turned into a file or directory Node the first time it is used by a builder method or other function that requires one vs. the other.

One of the most common things you can do with a Node is use it to print the file name that the node represents. Keep in mind, though, that because the object returned by a builder call is a list of Nodes, you must use Python subscripts to fetch individual Nodes from the list. For example, the following SConstruct file:

object_list = Object('hello.c')
program_list = Program(object_list)
print("The object file is: %s"%object_list[0])
print("The program file is: %s"%program_list[0])
      

Would print the following file names on a POSIX system:

% scons -Q
The object file is: hello.o
The program file is: hello
cc -o hello.o -c hello.c
cc -o hello hello.o

And the following file names on a Windows system:

C:\>scons -Q
The object file is: hello.obj
The program file is: hello.exe
cl /Fohello.obj /c hello.c /nologo
link /nologo /OUT:hello.exe hello.obj
embedManifestExeCheck(target, source, env)

Note that in the above example, the object_list[0] extracts an actual Node object from the list, and the Python print function converts the object to a string for printing.

Printing a Node's name as described in the previous section works because the string representation of a Node object is the name of the file. If you want to do something other than print the name of the file, you can fetch it by using the builtin Python str function. For example, if you want to use the Python os.path.exists to figure out whether a file exists while the SConstruct file is being read and executed, you can fetch the string as follows:

import os.path
program_list = Program('hello.c')
program_name = str(program_list[0])
if not os.path.exists(program_name):
    print("%s does not exist!"%program_name)
      

Which executes as follows on a POSIX system:

% scons -Q
hello does not exist!
cc -o hello.o -c hello.c
cc -o hello hello.o

env.GetBuildPath(file_or_list) returns the path of a Node or a string representing a path. It can also take a list of Nodes and/or strings, and returns the list of paths. If passed a single Node, the result is the same as calling str(node) (see above). The string(s) can have embedded construction variables, which are expanded as usual, using the calling environment's set of variables. The paths can be files or directories, and do not have to exist.

env=Environment(VAR="value")
n=File("foo.c")
print(env.GetBuildPath([n, "sub/dir/$VAR"]))
      

Would print the following file names:

% scons -Q
['foo.c', 'sub/dir/value']
scons: `.' is up to date.

There is also a function version of GetBuildPath which can be called without an Environment; that uses the default SCons Environment to do substitution on any string arguments.

Another aspect of avoiding unnecessary rebuilds is the fundamental build tool behavior of rebuilding things when an input file changes, so that the built software is up to date. By default, SCons keeps track of this through a content signature, or hash, of the contents of each file, although you can easily configure SCons to use the modification times (or time stamps) instead. You can even write your own Python function for deciding if an input file should trigger a rebuild.

Now suppose that our "Hello, World!" program actually has an #include line to include the hello.h file in the compilation:

#include <hello.h>
int
main()
{
    printf("Hello, %s!\n", string);
}
      

And, for completeness, the hello.h file looks like this:

#define string    "world"
      

In this case, we want SCons to recognize that, if the contents of the hello.h file change, the hello program must be recompiled. To do this, we need to modify the SConstruct file like so:

Program('hello.c', CPPPATH='.')
      

Scanning each file for #include lines does take some extra processing time. When you're doing a full build of a large system, the scanning time is usually a very small percentage of the overall time spent on the build. You're most likely to notice the scanning time, however, when you rebuild all or part of a large system: SCons will likely take some extra time to "think about" what must be built before it issues the first build command (or decides that everything is up to date and nothing must be rebuilt).

In practice, having SCons scan files saves time relative to the amount of potential time lost to tracking down subtle problems introduced by incorrect dependencies. Nevertheless, the "waiting time" while SCons scans files can annoy individual developers waiting for their builds to finish. Consequently, SCons lets you cache the implicit dependencies that its scanners find, for use by later builds. You can do this by specifying the --implicit-cache option on the command line:

% scons -Q --implicit-cache hello
cc -o hello.o -c hello.c
cc -o hello hello.o
% scons -Q hello
scons: `hello' is up to date.

If you don't want to specify --implicit-cache on the command line each time, you can make it the default behavior for your build by setting the implicit_cache option in an SConscript file:

SetOption('implicit_cache', 1)
    

SCons does not cache implicit dependencies like this by default because the --implicit-cache causes SCons to simply use the implicit dependencies stored during the last run, without any checking for whether or not those dependencies are still correct. Specifically, this means --implicit-cache instructs SCons to not rebuild "correctly" in the following cases:

SCons has built-in scanners for a number of languages. Sometimes these scanners fail to extract certain implicit dependencies due to limitations of the scanner implementation.

The following example illustrates a case where the built-in C scanner is unable to extract the implicit dependency on a header file.

#define FOO_HEADER <foo.h>
#include FOO_HEADER

int main() {
    return FOO;
}
      

% scons -Q
cc -o hello.o -c -I. hello.c
cc -o hello hello.o
%    [CHANGE CONTENTS OF foo.h]
% scons -Q
scons: `.' is up to date.

Apparently, the scanner does not know about the header dependency. Not being a full-fledged C preprocessor, the scanner does not expand the macro.

Occasionally, it may be useful to specify that a certain file or directory must, if necessary, be built or created before some other target is built, but that changes to that file or directory do not require that the target itself be rebuilt. Such a relationship is called an order-only dependency because it only affects the order in which things must be built--the dependency before the target--but it is not a strict dependency relationship because the target should not change in response to changes in the dependent file.

For example, suppose that you want to create a file every time you run a build that identifies the time the build was performed, the version number, etc., and which is included in every program that you build. The version file's contents will change every build. If you specify a normal dependency relationship, then every program that depends on that file would be rebuilt every time you ran SCons. For example, we could use some Python code in a SConstruct file to create a new version.c file with a string containing the current date every time we run SCons, and then link a program with the resulting object file by listing version.c in the sources:

import time

version_c_text = """
char *date = "%s";
""" % time.ctime(time.time())
open('version.c', 'w').write(version_c_text)

hello = Program(['hello.c', 'version.c'])
      

If we list version.c as an actual source file, though, then the version.o file will get rebuilt every time we run SCons (because the SConstruct file itself changes the contents of version.c) and the hello executable will get re-linked every time (because the version.o file changes):

% scons -Q hello
cc -o hello.o -c hello.c
cc -o version.o -c version.c
cc -o hello hello.o version.o
% sleep 1
% scons -Q hello
cc -o version.o -c version.c
cc -o hello hello.o version.o
% sleep 1
% scons -Q hello
cc -o version.o -c version.c
cc -o hello hello.o version.o

(Note that for the above example to work, we sleep for one second in between each run, so that the SConstruct file will create a version.c file with a time string that's one second later than the previous run.)

The external environment variable settings that the user has in force when executing SCons are available in the Python os.environ dictionary. That syntax means the environ attribute of the os module. In Python, to access the contents of a module you must first import it - so you would include the import os statement to any SConscript file in which you want to use values from the user's external environment.

import os

print("Shell is", os.environ['SHELL'])
     

More usefully, you can use the os.environ dictionary in your SConscript files to initialize construction environments with values from the user's external environment. Read on to the next section for information on how to do this.

It is rare that all of the software in a large, complicated system needs to be built exactly the same way. For example, different source files may need different options enabled on the command line, or different executable programs need to be linked with different libraries. SCons accommodates these different build requirements by allowing you to create and configure multiple construction environments that control how the software is built. A construction environment is an object that has a number of associated construction variables, each with a name and a value, just like a dictionary. (A construction environment also has an attached set of Builder methods, about which we'll learn more later.)

SCons has a bewildering array of construction variables for different types of options when building programs. Sometimes you may not know exactly which variable should be used for a particular option.

Configuring the right options to build programs to work with libraries--especially shared libraries--that are available on POSIX systems can be complex. To help this situation, various utilies with names that end in config return the command-line options for the GNU Compiler Collection (GCC) that are needed to build and link against those libraries; for example, the command-line options to use a library named lib could be found by calling a utility named lib-config.

A more recent convention is that these options are available through the generic pkg-config program, providing a common framework, error handling, and the like, so that all the package creator has to do is provide the set of strings for his particular package.

Sometimes the commands executed to compile object files or link programs (or build other targets) can get very long, long enough to make it difficult for users to distinguish error messages or other important build output from the commands themselves. All of the default $*COM variables that specify the command lines used to build various types of target files have a corresponding $*COMSTR variable that can be set to an alternative string that will be displayed when the target is built.

For example, suppose you want to have SCons display a "Compiling" message whenever it's compiling an object file, and a "Linking" when it's linking an executable. You could write a SConstruct file that looks like:

env = Environment(CCCOMSTR = "Compiling $TARGET",
                  LINKCOMSTR = "Linking $TARGET")
env.Program('foo.c')
       

Which would then yield the output:

% scons -Q
Compiling foo.o
Linking foo
    

SCons performs complete variable substitution on $*COMSTR variables, so they have access to all of the standard variables like $TARGET $SOURCES, etc., as well as any construction variables that happen to be configured in the construction environment used to build a specific target.

Of course, sometimes it's still important to be able to see the exact command that SCons will execute to build a target. For example, you may simply need to verify that SCons is configured to supply the right options to the compiler, or a developer may want to cut-and-paste a compile command to add a few options for a custom test.

One common way to give users control over whether or not SCons should print the actual command line or a short, configured summary is to add support for a VERBOSE command-line variable to your SConstruct file. A simple configuration for this might look like:

env = Environment()
if ARGUMENTS.get('VERBOSE') != '1':
    env['CCCOMSTR'] = "Compiling $TARGET"
    env['LINKCOMSTR'] = "Linking $TARGET"
env.Program('foo.c')
       

By only setting the appropriate $*COMSTR variables if the user specifies VERBOSE=1 on the command line, the user has control over how SCons displays these particular command lines:

% scons -Q
Compiling foo.o
Linking foo
% scons -Q -c
Removed foo.o
Removed foo
% scons -Q VERBOSE=1
cc -o foo.o -c foo.c
cc -o foo foo.o
    

A gentle reminder here: many of the commands for building come in pairs, depending on whether the intent is to build an object for use in a shared library or not. The command strings mirror this, so it may be necessary to set, for example, both CCCOMSTR and SHCCCOMSTR to get the desired results.

Another aspect of providing good build output is to give the user feedback about what SCons is doing even when nothing is being built at the moment. This can be especially true for large builds when most of the targets are already up-to-date. Because SCons can take a long time making absolutely sure that every target is, in fact, up-to-date with respect to a lot of dependency files, it can be easy for users to mistakenly conclude that SCons is hung or that there is some other problem with the build.

One way to deal with this perception is to configure SCons to print something to let the user know what it's "thinking about." The Progress function allows you to specify a string that will be printed for every file that SCons is "considering" while it is traversing the dependency graph to decide what targets are or are not up-to-date.

Progress('Evaluating $TARGET\n')
Program('f1.c')
Program('f2.c')
      

Note that the Progress function does not arrange for a newline to be printed automatically at the end of the string (as does the Python print function), and we must specify the \n that we want printed at the end of the configured string. This configuration, then, will have SCons print that it is Evaluating each file that it encounters in turn as it traverses the dependency graph:

% scons -Q
Evaluating SConstruct
Evaluating f1.c
Evaluating f1.o
cc -o f1.o -c f1.c
Evaluating f1
cc -o f1 f1.o
Evaluating f2.c
Evaluating f2.o
cc -o f2.o -c f2.c
Evaluating f2
cc -o f2 f2.o
Evaluating .

Of course, normally you don't want to add all of these additional lines to your build output, as that can make it difficult for the user to find errors or other important messages. A more useful way to display this progress might be to have the file names printed directly to the user's screen, not to the same standard output stream where build output is printed, and to use a carriage return character (\r) so that each file name gets re-printed on the same line. Such a configuration would look like:

Progress('$TARGET\r',
         file=open('/dev/tty', 'w'),
         overwrite=True)
Program('f1.c')
Program('f2.c')
    

Note that we also specified the overwrite=True argument to the Progress function, which causes SCons to "wipe out" the previous string with space characters before printing the next Progress string. Without the overwrite=True argument, a shorter file name would not overwrite all of the charactes in a longer file name that precedes it, making it difficult to tell what the actual file name is on the output. Also note that we opened up the /dev/tty file for direct access (on POSIX) to the user's screen. On Windows, the equivalent would be to open the con: file name.

Also, it's important to know that although you can use $TARGET to substitute the name of the node in the string, the Progress function does not perform general variable substitution (because there's not necessarily a construction environment involved in evaluating a node like a source file, for example).

You can also specify a list of strings to the Progress function, in which case SCons will display each string in turn. This can be used to implement a "spinner" by having SCons cycle through a sequence of strings:

Progress(['-\r', '\\\r', '|\r', '/\r'], interval=5)
Program('f1.c')
Program('f2.c')
    

Note that here we have also used the interval= keyword argument to have SCons only print a new "spinner" string once every five evaluated nodes. Using an interval= count, even with strings that use $TARGET like our examples above, can be a good way to lessen the work that SCons expends printing Progress strings, while still giving the user feedback that indicates SCons is still working on evaluating the build.

Lastly, you can have direct control over how to print each evaluated node by passing a Python function (or other Python callable) to the Progress function. Your function will be called for each evaluated node, allowing you to implement more sophisticated logic like adding a counter:

screen = open('/dev/tty', 'w')
count = 0
def progress_function(node)
    count += 1
    screen.write('Node %4d: %s\r' % (count, node))

Progress(progress_function)
      

Of course, if you choose, you could completely ignore the node argument to the function, and just print a count, or anything else you wish.

(Note that there's an obvious follow-on question here: how would you find the total number of nodes that will be evaluated so you can tell the user how close the build is to finishing? Unfortunately, in the general case, there isn't a good way to do that, short of having SCons evaluate its dependency graph twice, first to count the total and the second time to actually build the targets. This would be necessary because you can't know in advance which target(s) the user actually requested to be built. The entire build may consist of thousands of Nodes, for example, but maybe the user specifically requested that only a single object file be built.)

SCons, like most build tools, returns zero status to the shell on success and nonzero status on failure. Sometimes it's useful to give more information about the build status at the end of the run, for instance to print an informative message, send an email, or page the poor slob who broke the build.

SCons provides a GetBuildFailures method that you can use in a python atexit function to get a list of objects describing the actions that failed while attempting to build targets. There can be more than one if you're using -j. Here's a simple 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)
      

The atexit.register call registers print_build_failures as an atexit callback, to be called before SCons exits. When that function is called, it calls GetBuildFailures to fetch the list of failed objects. See the man page for the detailed contents of the returned objects; some of the more useful attributes are .node, .errstr, .filename, and .command. The filename is not necessarily the same file as the node; the node is the target that was being built when the error occurred, while the filenameis the file or dir that actually caused the error. Note: only call GetBuildFailures at the end of the build; calling it at any other time is undefined.

Here is a more complete example showing how to turn each element of GetBuildFailures into a string:

# Make the build fail if we pass fail=1 on the command line
if ARGUMENTS.get('fail', 0):
    Command('target', 'source', ['/bin/false'])

def bf_to_str(bf):
    """Convert an element of GetBuildFailures() to a string
    in a useful way."""
    import SCons.Errors
    if bf is None: # unknown targets product None in list
        return '(unknown tgt)'
    elif isinstance(bf, SCons.Errors.StopError):
        return str(bf)
    elif bf.node:
        return str(bf.node) + ': ' + bf.errstr
    elif bf.filename:
        return bf.filename + ': ' + bf.errstr
    return 'unknown failure: ' + bf.errstr
import atexit

def build_status():
    """Convert the build status to a 2-tuple, (status, msg)."""
    from SCons.Script import GetBuildFailures
    bf = GetBuildFailures()
    if bf:
        # bf is normally a list of build failures; if an element is None,
        # it's because of a target that scons doesn't know anything about.
        status = 'failed'
        failures_message = "\n".join(["Failed building %s" % bf_to_str(x)
                           for x in bf if x is not None])
    else:
        # if bf is None, the build completed successfully.
        status = 'ok'
        failures_message = ''
    return (status, failures_message)

def display_build_status():
    """Display the build status.  Called by atexit.
    Here you could do all kinds of complicated things."""
    status, failures_message = build_status()
    if status == 'failed':
       print("FAILED!!!!")  # could display alert, ring bell, etc.
    elif status == 'ok':
       print("Build succeeded.")
    print(failures_message)

atexit.register(display_build_status)
      

When this runs, you'll see the appropriate output:

% scons -Q
scons: `.' is up to date.
Build succeeded.
% scons -Q fail=1
scons: *** [target] Source `source' not found, needed by target `target'.
FAILED!!!!
Failed building target: Source `source' not found, needed by target `target'.

SCons has many command-line options that control its behavior. An SCons command-line option always begins with one or two hyphen (-) characters.

You may want to control various aspects of your build by allowing variable=value values to be specified on the command line. For example, suppose you want to be able to build a debug version of a program by running SCons as follows:

% scons -Q debug=1
    

SCons provides an ARGUMENTS dictionary that stores all of the variable=value assignments from the command line. This allows you to modify aspects of your build in response to specifications on the command line. (Note that unless you want to require a variable always be specified you probably want to use the Python dictionary get method, which allows you to designate a default value to be used if there is no specification on the command line.)

You can install multiple files into a directory simply by calling the Install function multiple times:

env = Environment()
hello = env.Program('hello.c')
goodbye = env.Program('goodbye.c')
env.Install('/usr/bin', hello)
env.Install('/usr/bin', goodbye)
env.Alias('install', '/usr/bin')
      

Or, more succinctly, listing the multiple input files in a list (just like you can do with any other builder):

env = Environment()
hello = env.Program('hello.c')
goodbye = env.Program('goodbye.c')
env.Install('/usr/bin', [hello, goodbye])
env.Alias('install', '/usr/bin')
    

Either of these two examples yields:

% scons -Q install
cc -o goodbye.o -c goodbye.c
cc -o goodbye goodbye.o
Install file: "goodbye" as "/usr/bin/goodbye"
cc -o hello.o -c hello.c
cc -o hello hello.o
Install file: "hello" as "/usr/bin/hello"

The Install method preserves the name of the file when it is copied into the destination directory. If you need to change the name of the file when you copy it, use the InstallAs function:

env = Environment()
hello = env.Program('hello.c')
env.InstallAs('/usr/bin/hello-new', hello)
env.Alias('install', '/usr/bin')
      

This installs the hello program with the name hello-new as follows:

% scons -Q install
cc -o hello.o -c hello.c
cc -o hello hello.o
Install file: "hello" as "/usr/bin/hello-new"

If you have multiple files that all need to be installed with different file names, you can either call the InstallAs function multiple times, or as a shorthand, you can supply same-length lists for both the target and source arguments:

env = Environment()
hello = env.Program('hello.c')
goodbye = env.Program('goodbye.c')
env.InstallAs(['/usr/bin/hello-new',
               '/usr/bin/goodbye-new'],
               [hello, goodbye])
env.Alias('install', '/usr/bin')
      

In this case, the InstallAs function loops through both lists simultaneously, and copies each source file into its corresponding target file name:

% scons -Q install
cc -o goodbye.o -c goodbye.c
cc -o goodbye goodbye.o
Install file: "goodbye" as "/usr/bin/goodbye-new"
cc -o hello.o -c hello.c
cc -o hello hello.o
Install file: "hello" as "/usr/bin/hello-new"

If you need to delete a file, then the Delete factory can be used in much the same way as the Copy factory. For example, if we want to make sure that the temporary file in our last example doesn't exist before we copy to it, we could add Delete to the beginning of the command list:

Command(
    "file.out",
    "file.in",
    action=[
        Delete("tempfile"),
        Copy("tempfile", "$SOURCE"),
        "modify tempfile",
        Copy("$TARGET", "tempfile"),
    ],
)
      

Which then executes as follows:

% scons -Q
Delete("tempfile")
Copy("tempfile", "file.in")
modify tempfile
Copy("file.out", "tempfile")

The Move factory allows you to rename a file or directory. For example, if we don't want to copy the temporary file, we could use:

Command(
    "file.out",
    "file.in",
    action=[
        Copy("tempfile", "$SOURCE"),
        "modify tempfile",
        Move("$TARGET", "tempfile"),
    ],
)
      

Which would execute as:

% scons -Q
Copy("tempfile", "file.in")
modify tempfile
Move("file.out", "tempfile")

If you just need to update the recorded modification time for a file, use the Touch factory:

Command(
    "file.out",
    "file.in",
    action=[
        Copy("$TARGET", "$SOURCE"),
        Touch("$TARGET"),
    ]
)
      

Which executes as:

% scons -Q
Copy("file.out", "file.in")
Touch("file.out")

If you need to create a directory, use the Mkdir factory. For example, if we need to process a file in a temporary directory in which the processing tool will create other files that we don't care about, you could use:

Command(
    "file.out",
    "file.in",
    action=[
        Delete("tempdir"),
        Mkdir("tempdir"),
        Copy("tempdir/${SOURCE.file}", "$SOURCE"),
        "process tempdir",
        Move("$TARGET", "tempdir/output_file"),
        Delete("tempdir"),
    ],
)
      

Which executes as:

% scons -Q
Delete("tempdir")
Mkdir("tempdir")
Copy("tempdir/file.in", "file.in")
process tempdir
Move("file.out", "tempdir/output_file")
scons: *** [file.out] tempdir/output_file: No such file or directory

To change permissions on a file or directory, use the Chmod factory. The permission argument uses POSIX-style permission bits and should typically be expressed as an octal, not decimal, number:

Command(
    "file.out",
    "file.in",
    action=[
        Copy("$TARGET", "$SOURCE"),
        Chmod("$TARGET", 0o755),
    ]
)
      

Which executes:

% scons -Q
Copy("file.out", "file.in")
Chmod("file.out", 0o755)

We've been showing you how to use Action factories in the Command function. You can also execute an Action returned by a factory (or actually, any Action) at the time the SConscript file is read by using the Execute function. For example, if we need to make sure that a directory exists before we build any targets,

Execute(Mkdir('/tmp/my_temp_directory'))
      

Notice that this will create the directory while the SConscript file is being read:

% scons
scons: Reading SConscript files ...
Mkdir("/tmp/my_temp_directory")
scons: done reading SConscript files.
scons: Building targets ...
scons: `.' is up to date.
scons: done building targets.

If you're familiar with Python, you may wonder why you would want to use this instead of just calling the native Python os.mkdir() function. The advantage here is that the Mkdir action will behave appropriately if the user specifies the SCons -n or -q options--that is, it will print the action but not actually make the directory when -n is specified, or make the directory but not print the action when -q is specified.

The Execute function returns the exit status or return value of the underlying action being executed. It will also print an error message if the action fails and returns a non-zero value. SCons will not, however, actually stop the build if the action fails. If you want the build to stop in response to a failure in an action called by Execute, you must do so by explicitly checking the return value and calling the Exit function (or a Python equivalent):

if Execute(Mkdir('/tmp/my_temp_directory')):
    # A problem occurred while making the temp directory.
    Exit(1)
    

By default, SCons removes targets before building them. Sometimes, however, this is not what you want. For example, you may want to update a library incrementally, not by having it deleted and then rebuilt from all of the constituent object files. In such cases, you can use the Precious method to prevent SCons from removing the target before it is built:

  env = Environment(RANLIBCOM='')
  lib = env.Library('foo', ['f1.c', 'f2.c', 'f3.c'])
  env.Precious(lib)
      

Although the output doesn't look any different, SCons does not, in fact, delete the target library before rebuilding it:

% scons -Q
cc -o f1.o -c f1.c
cc -o f2.o -c f2.c
cc -o f3.o -c f3.c
ar rc libfoo.a f1.o f2.o f3.o

SCons will, however, still delete files marked as Precious when the -c option is used.

By default, SCons removes all built targets when invoked with the -c option to clean a source tree of built targets. Sometimes, however, this is not what you want. For example, you may want to remove only intermediate generated files (such as object files), but leave the final targets (the libraries) untouched. In such cases, you can use the NoClean method to prevent SCons from removing a target during a clean:

env = Environment(RANLIBCOM='')
lib = env.Library('foo', ['f1.c', 'f2.c', 'f3.c'])
env.NoClean(lib)
      

Notice that the libfoo.a is not listed as a removed file:

% scons -Q
cc -o f1.o -c f1.c
cc -o f2.o -c f2.c
cc -o f3.o -c f3.c
ar rc libfoo.a f1.o f2.o f3.o
% scons -c
scons: Reading SConscript files ...
scons: done reading SConscript files.
scons: Cleaning targets ...
Removed f1.o
Removed f2.o
Removed f3.o
scons: done cleaning targets.

There may be additional files that you want removed when the -c option is used, but which SCons doesn't know about because they're not normal target files. For example, perhaps a command you invoke creates a log file as part of building the target file you want. You would like the log file cleaned, but you don't want to have to teach SCons that the command "builds" two files.

You can use the Clean function to arrange for additional files to be removed when the -c option is used. Notice, however, that the Clean function takes two arguments, and the second argument is the name of the additional file you want cleaned (foo.log in this example):

t = Command('foo.out', 'foo.in', 'build -o $TARGET $SOURCE')
Clean(t, 'foo.log')
      

The first argument is the target with which you want the cleaning of this additional file associated. In the above example, we've used the return value from the Command function, which represents the foo.out target. Now whenever the foo.out target is cleaned by the -c option, the foo.log file will be removed as well:

% scons -Q
build -o foo.out foo.in
% scons -Q -c
Removed foo.out
Removed foo.log

As we've already seen, the build script at the top of the tree is called SConstruct. The top-level SConstruct file can use the SConscript function to include other subsidiary scripts in the build. These subsidiary scripts can, in turn, use the SConscript function to include still other scripts in the build. By convention, these subsidiary scripts are usually named SConscript. For example, a top-level SConstruct file might arrange for four subsidiary scripts to be included in the build as follows:

SConscript(
    [
        'drivers/display/SConscript',
        'drivers/mouse/SConscript',
        'parser/SConscript',
        'utilities/SConscript',
    ]
)
    

In this case, the SConstruct file lists all of the SConscript files in the build explicitly. (Note, however, that not every directory in the tree necessarily has an SConscript file.) Alternatively, the drivers subdirectory might contain an intermediate SConscript file, in which case the SConscript call in the top-level SConstruct file would look like:

SConscript(['drivers/SConscript', 'parser/SConscript', 'utilities/SConscript'])
    

And the subsidiary SConscript file in the drivers subdirectory would look like:

SConscript(['display/SConscript', 'mouse/SConscript'])
    

Whether you list all of the SConscript files in the top-level SConstruct file, or place a subsidiary SConscript file in intervening directories, or use some mix of the two schemes, is up to you and the needs of your software.

Subsidiary SConscript files make it easy to create a build hierarchy because all of the file and directory names in a subsidiary SConscript files are interpreted relative to the directory in which that SConscript file lives. Typically, this allows the SConscript file containing the instructions to build a target file to live in the same directory as the source files from which the target will be built, making it easy to update how the software is built whenever files are added or deleted (or other changes are made). It also tends to keep scripts more readable as they don't need to be filled with complex paths.

For example, suppose we want to build two programs prog1 and prog2 in two separate directories with the same names as the programs. One typical way to do this would be with a top-level SConstruct file like this:

SConscript(['prog1/SConscript', 'prog2/SConscript'])
      

And subsidiary SConscript files that look like this:

env = Environment()
env.Program('prog1', ['main.c', 'foo1.c', 'foo2.c'])
      

And this:

env = Environment()
env.Program('prog2', ['main.c', 'bar1.c', 'bar2.c'])
      

Then, when we run SCons in the top-level directory, our build looks like:

% scons -Q
cc -o prog1/foo1.o -c prog1/foo1.c
cc -o prog1/foo2.o -c prog1/foo2.c
cc -o prog1/main.o -c prog1/main.c
cc -o prog1/prog1 prog1/main.o prog1/foo1.o prog1/foo2.o
cc -o prog2/bar1.o -c prog2/bar1.c
cc -o prog2/bar2.o -c prog2/bar2.c
cc -o prog2/main.o -c prog2/main.c
cc -o prog2/prog2 prog2/main.o prog2/bar1.o prog2/bar2.o

Notice the following: First, you can have files with the same names in multiple directories, like main.c in the above example. Second, when building, SCons stays in the top-level directory (where the SConstruct file lives) and issues commands that use the path names from the top-level directory to the target and source files within the hierarchy. This works because SCons reads all the SConscript files in one pass, interpreting each in its local context, building up a tree of information, before starting to execute the needed builds in a second pass. This is quite different than some other build tools which implement a heirarcical build by recursing.

If you need to use a file from another directory, it's sometimes more convenient to specify the path to a file in another directory from the top-level SConstruct directory, even when you're using that file in a subsidiary SConscript file in a subdirectory. You can tell SCons to interpret a path name as relative to the top-level SConstruct directory, not the local directory of the SConscript file, by prepending a # (hash mark) in front of the path name:

env = Environment()
env.Program('prog', ['main.c', '#lib/foo1.c', 'foo2.c'])
       

In this example, the lib directory is directly underneath the top-level SConstruct directory. If the above SConscript file is in a subdirectory named src/prog, the output would look like:

% scons -Q
cc -o lib/foo1.o -c lib/foo1.c
cc -o src/prog/foo2.o -c src/prog/foo2.c
cc -o src/prog/main.o -c src/prog/main.c
cc -o src/prog/prog src/prog/main.o lib/foo1.o src/prog/foo2.o

Of course, you can always specify an absolute path name for a file--for example:

env = Environment()
env.Program('prog', ['main.c', '/usr/joe/lib/foo1.c', 'foo2.c'])
       

Which, when executed, would yield:

% scons -Q
cc -o src/prog/foo2.o -c src/prog/foo2.c
cc -o src/prog/main.o -c src/prog/main.c
cc -o /usr/joe/lib/foo1.o -c /usr/joe/lib/foo1.c
cc -o src/prog/prog src/prog/main.o /usr/joe/lib/foo1.o src/prog/foo2.o

When you set up a variant directory SCons conceptually behaves as if you requested a build in that directory. As noted in the previous chapter, all builds actually happen from the top level directory, but as an aid to understanding how SCons operates, think of it as build in place in the variant directory, not build in source but send build artifacts to the variant directory. It turns out in place builds are easier to get right than out of tree builds - so by default SCons simulates an in place build by making the variant directory look just like the source directory. The most straightforward way to do that is by making copies of the files needed for the build.

The most direct reason to duplicate source files in variant directories is simply that some tools (mostly older versions) are written to only build their output files in the same directory as the source files - such tools often don't have any option to specify the output file, and the tool just uses a predefined output file name, or uses a derived variant of the source file name, dropping the result in the same directory. In this case, the choices are either to build the output file in the source directory and move it to the variant directory, or to duplicate the source files in the variant directory.

Additionally, relative references between files can cause problems which are resolved by just duplicating the hierarchy of source files into the variant directory. You can see this at work in use of the C preprocessor #include mechanism with double quotes, not angle brackets:

#include "file.h"
    

The de facto standard behavior for most C compilers in this case is to first look in the same directory as the source file that contains the #include line, then to look in the directories in the preprocessor search path. Add to this that the SCons implementation of support for code repositories (described below) means not all of the files will be found in the same directory hierarchy, and the simplest way to make sure that the right include file is found is to duplicate the source files into the variant directory, which provides a correct build regardless of the original location(s) of the source files.

Although source-file duplication guarantees a correct build even in these edge cases, it can usually be safely disabled. The next section describes how you can disable the duplication of source files in the variant directory.

The variant_dir keyword argument of the SConscript function provides everything we need to show how easy it is to create variant builds using SCons. Suppose, for example, that we want to build a program for both Windows and Linux platforms, but that we want to build it in directory on a network share with separate side-by-side build directories for the Windows and Linux versions of the program. We have to do a little bit of work to construct paths, to make sure unwanted location dependencies don't creep in. The top-relative path reference can be useful here. To avoid writing conditional code based on platform, we can build the variant_dir path dynamically:

platform = ARGUMENTS.get('OS', Platform())

include = "#export/$PLATFORM/include"
lib = "#export/$PLATFORM/lib"
bin = "#export/$PLATFORM/bin"

env = Environment(
    PLATFORM=platform,
    BINDIR=bin,
    INCDIR=include,
    LIBDIR=lib,
    CPPPATH=[include],
    LIBPATH=[lib],
    LIBS='world',
)

Export('env')

env.SConscript('src/SConscript', variant_dir='build/$PLATFORM')
    

This SConstruct file, when run on a Linux system, yields:

% scons -Q OS=linux
Install file: "build/linux/world/world.h" as "export/linux/include/world.h"
cc -o build/linux/hello/hello.o -c -Iexport/linux/include build/linux/hello/hello.c
cc -o build/linux/world/world.o -c -Iexport/linux/include build/linux/world/world.c
ar rc build/linux/world/libworld.a build/linux/world/world.o
ranlib build/linux/world/libworld.a
Install file: "build/linux/world/libworld.a" as "export/linux/lib/libworld.a"
cc -o build/linux/hello/hello build/linux/hello/hello.o -Lexport/linux/lib -lworld
Install file: "build/linux/hello/hello" as "export/linux/bin/hello"

The same SConstruct file on Windows would build:

C:\>scons -Q OS=windows
Install file: "build/windows/world/world.h" as "export/windows/include/world.h"
cl /Fobuild\windows\hello\hello.obj /c build\windows\hello\hello.c /nologo /Iexport\windows\include
cl /Fobuild\windows\world\world.obj /c build\windows\world\world.c /nologo /Iexport\windows\include
lib /nologo /OUT:build\windows\world\world.lib build\windows\world\world.obj
Install file: "build/windows/world/world.lib" as "export/windows/lib/world.lib"
link /nologo /OUT:build\windows\hello\hello.exe /LIBPATH:export\windows\lib world.lib build\windows\hello\hello.obj
embedManifestExeCheck(target, source, env)
Install file: "build/windows/hello/hello.exe" as "export/windows/bin/hello.exe"

It's often useful to allow multiple programmers working on a project to build software from source files and/or derived files that are stored in a centrally-accessible repository, a directory copy of the source code tree. (Note that this is not the sort of repository maintained by a source code management system like BitKeeper, CVS, or Subversion.) You use the Repository method to tell SCons to search one or more central code repositories (in order) for any source files and derived files that are not present in the local build tree:

env = Environment()
env.Program('hello.c')
Repository('/usr/repository1', '/usr/repository2')
      

Multiple calls to the Repository method will simply add repositories to the global list that SCons maintains, with the exception that SCons will automatically eliminate the current directory and any non-existent directories from the list.

The above example specifies that SCons will first search for files under the /usr/repository1 tree and next under the /usr/repository2 tree. SCons expects that any files it searches for will be found in the same position relative to the top-level directory. In the above example, if the hello.c file is not found in the local build tree, SCons will search first for a /usr/repository1/hello.c file and then for a /usr/repository2/hello.c file to use in its place.

So given the SConstruct file above, if the hello.c file exists in the local build directory, SCons will rebuild the hello program as normal:

% scons -Q
cc -o hello.o -c hello.c
cc -o hello hello.o

If, however, there is no local hello.c file, but one exists in /usr/repository1, SCons will recompile the hello program from the source file it finds in the repository:

% scons -Q
cc -o hello.o -c /usr/repository1/hello.c
cc -o hello hello.o

And similarly, if there is no local hello.c file and no /usr/repository1/hello.c, but one exists in /usr/repository2:

% scons -Q
cc -o hello.o -c /usr/repository2/hello.c
cc -o hello hello.o

SCons will also search in repositories for the SConstruct file and any specified SConscript files. This poses a problem, though: how can SCons search a repository tree for an SConstruct file if the SConstruct file itself contains the information about the pathname of the repository? To solve this problem, SCons allows you to specify repository directories on the command line using the -Y option:

% scons -Q -Y /usr/repository1 -Y /usr/repository2
    

When looking for source or derived files, SCons will first search the repositories specified on the command line, and then search the repositories specified in the SConstruct or SConscript files.

If a repository contains not only source files, but also derived files (such as object files, libraries, or executables), SCons will perform its normal MD5 signature calculation to decide if a derived file in a repository is up-to-date, or the derived file must be rebuilt in the local build directory. For the SCons signature calculation to work correctly, a repository tree must contain the .sconsign files that SCons uses to keep track of signature information.

Usually, this would be done by a build integrator who would run SCons in the repository to create all of its derived files and .sconsign files, or who would run SCons in a separate build directory and copy the resulting tree to the desired repository:

% cd /usr/repository1
% scons -Q
cc -o file1.o -c file1.c
cc -o file2.o -c file2.c
cc -o hello.o -c hello.c
cc -o hello hello.o file1.o file2.o

(Note that this is safe even if the SConstruct file lists /usr/repository1 as a repository, because SCons will remove the current build directory from its repository list for that invocation.)

Now, with the repository populated, we only need to create the one local source file we're interested in working with at the moment, and use the -Y option to tell SCons to fetch any other files it needs from the repository:

% cd $HOME/build
% edit hello.c
% scons -Q -Y /usr/repository1
cc -c -o hello.o hello.c
cc -o hello hello.o /usr/repository1/file1.o /usr/repository1/file2.o
    

Notice that SCons realizes that it does not need to rebuild local copies file1.o and file2.o files, but instead uses the already-compiled files from the repository.

If the repository tree contains the complete results of a build, and we try to build from the repository without any files in our local tree, something moderately surprising happens:

% mkdir $HOME/build2
% cd $HOME/build2
% scons -Q -Y /usr/all/repository hello
scons: `hello' is up-to-date.
    

Why does SCons say that the hello program is up-to-date when there is no hello program in the local build directory? Because the repository (not the local directory) contains the up-to-date hello program, and SCons correctly determines that nothing needs to be done to rebuild that up-to-date copy of the file.

There are, however, many times when you want to ensure that a local copy of a file always exists. A packaging or testing script, for example, may assume that certain generated files exist locally. To tell SCons to make a copy of any up-to-date repository file in the local build directory, use the Local function:

env = Environment()
hello = env.Program('hello.c')
Local(hello)
      

If we then run the same command, SCons will make a local copy of the program from the repository copy, and tell you that it is doing so:

% scons -Y /usr/all/repository hello
Local copy of hello from /usr/all/repository/hello
scons: `hello' is up-to-date.
    

(Notice that, because the act of making the local copy is not considered a "build" of the hello file, SCons still reports that it is up-to-date.)