Installing Python

Because SCons is written in Python, you must obviously have Python installed on your system to use SCons Before you try to install Python, you should check to see if Python is already available on your system by typing python at your system's command-line prompt. You should see something like the following on a UNIX or Linux system that has Python installed:

       $ python
       Python 2.2.2 (#1, Feb 24 2003, 19:13:11)
       [GCC 3.2.2 20030222 (Red Hat Linux 3.2.2-4)] on linux2
       Type "help", "copyright", "credits" or "license" for more information.
       >>> ^D
    

And on a Windows system with Python installed:

       C:\>python
       Python 2.2.2 (#34, Apr 9 2002, 19:34:33) [MSC 32 bit (Intel)] on win32
       Type "help", "copyright", "credits" or "license" for more information.
       >>> ^Z
    

The >>> is the input prompt for the Python interpreter. The ^D and ^Z represent the CTRL-D and CTRL-Z characters that you will need to type to get out of the interpreter before proceeding to installing SCons.

If Python is not installed on your system, you will see an error message stating something like "command not found" (on UNIX or Linux) or "'python' is not recognized as an internal or external command, operable progam or batch file" (on Windows). In that case, you need to install Python before you can install SCons.

The standard location for information about downloading and installing Python is http://www.python.org/download/. See that page for information about how to download and install Python on your system.

Installing SCons From Pre-Built Packages

SCons comes pre-packaged for installation on a number of systems, including Linux and Windows systems. You do not need to read this entire section, you should only need to read the section appropriate to the type of system you're running on.

        # rpm -Uvh scons-0.96-1.noarch.rpm
      

        # apt-get install scons
      

Building and Installing SCons on Any System

If a pre-built SCons package is not available for your system, then you can still easily build and install SCons using the native Python distutils package.

The first step is to download either the scons-0.96.92.tar.gz or scons-0.96.92.zip, which are available from the SCons download page at http://www.scons.org/download.html.

Unpack the archive you downloaded, using a utility like tar on Linux or UNIX, or WinZip on Windows. This will create a directory called scons-0.96.92, usually in your local directory. Then change your working directory to that directory and install SCons by executing the following commands:

      # cd scons-0.96.92
      # python setup.py install
    

This will build SCons, install the scons script in the default system scripts directory (/usr/local/bin or C:\Python2.2\Scripts), and will install the SCons build engine in an appropriate stand-alone library directory (/usr/local/lib/scons or C:\Python2.2\scons). Because these are system directories, you may need root (on Linux or UNIX) or Administrator (on Windows) privileges to install SCons like this.

        # python setup.py install --version-lib
      

        # python setup.py install --prefix=/opt/scons
      

        $ python setup.py install --prefix=$HOME
      

Building Simple C / C++ Programs

Here's the famous "Hello, World!" program in C:

      int
      main()
      {
          printf("Hello, world!\n");
      }
   

And here's how to build it using SCons. Enter the following into a file named SConstruct:

      Program('hello.c')
   

This minimal configuration file gives SCons two pieces of information: what you want to build (an executable program), and the input file from which you want it built (the hello.c file). Program is a builder_method, a Python call that tells SCons that you want to build an executable program.

That's it. Now run the scons command to build the program. On a POSIX-compliant system like Linux or UNIX, you'll see something like:

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

On a Windows system with the Microsoft Visual C++ compiler, you'll see something like:

      C:\>scons
      scons: Reading SConscript files ...
      scons: done reading SConscript files.
      scons: Building targets ...
      cl /nologo /c hello.c /Fohello.obj
      link /nologo /OUT:hello.exe hello.obj
      scons: done building targets.
   

First, notice that you only need to specify the name of the source file, and that SCons correctly deduces the names of the object and executable files to be built from the base of the source file name.

Second, notice that the same input SConstruct file, without any changes, generates the correct output file names on both systems: hello.o and hello on POSIX systems, hello.obj and hello.exe on Windows systems. This is a simple example of how SCons makes it extremely easy to write portable software builds.

(Note that we won't provide duplicate side-by-side POSIX and Windows output for all of the examples in this guide; just keep in mind that, unless otherwise specified, any of the examples should work equally well on both types of systems.)

Building Object Files

The Program builder method is only one of many builder methods that SCons provides to build different types of files. Another is the Object builder method, which tells SCons to build an object file from the specified source file:

      Object('hello.c')
   

Now when you run the scons command to build the program, it will build just the hello.o object file on a POSIX system:

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

And just the hello.obj object file on a Windows system (with the Microsoft Visual C++ compiler):

      C:\>scons
      scons: Reading SConscript files ...
      scons: done reading SConscript files.
      scons: Building targets ...
      cl /nologo /c hello.c /Fohello.obj
      scons: done building targets.
   

Simple Java Builds

SCons also makes building with Java extremely easy. Unlike the Program and Object builder methods, however, the Java builder method requires that you specify the name of a destination directory in which you want the class files placed, followed by the source directory in which the .java files live:

     Java('classes', 'src')
   

If the src directory contains a single hello.java file, then the output from running the scons command would look something like this (on a POSIX system):

      % scons
      scons: Reading SConscript files ...
      scons: done reading SConscript files.
      scons: Building targets ...
      javac -d classes -sourcepath src src/hello.java
      scons: done building targets.
   

We'll cover Java builds in more detail, including building Java archive (.jar) and other types of file, in the chapter called Java Builds.

Cleaning Up After a Build

When using SCons, it is unnecessary to add special commands or target names to clean up after a build. Instead, you simply use the -c or --clean option when you invoke SCons, and SCons removes the appropriate built files. So if we build our 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 -c -o hello.o 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 /nologo /c hello.c /Fohello.obj
      link /nologo /OUT:hello.exe hello.obj
      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.

The SConstruct File

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.

        # Arrange to build the "hello" program.
        Program('hello.c')    # "hello.c" is the source file.
     

       print "Calling Program('hello.c')"
       Program('hello.c')
       print "Calling Program('goodbye.c')"
       Program('goodbye.c')
       print "Finished calling Program()"
     

       % scons
       scons: Reading SConscript files ...
       Calling Program('hello.c')
       Calling Program('goodbye.c')
       Finished calling Program()
       scons: done reading SConscript files.
       scons: Building targets ...
       cc -c -o goodbye.o goodbye.c
       cc -o goodbye goodbye.o
       cc -c -o hello.o hello.c
       cc -o hello hello.o
       scons: done building targets.
     

Making the SCons Output Less Verbose

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 /nologo /c hello.c /Fohello.obj
      link /nologo /OUT:hello.exe hello.obj
      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 /nologo /c hello.c /Fohello.obj
      link /nologo /OUT:hello.exe hello.obj
   

Because we want this User's Guide to focus on what SCons is actually doing, we're going use the -Q option to remove these messages from the output of all the remaining examples in this Guide.

Specifying the Name of the Target (Output) File

You've seen that when you call the Program builder method, it builds the resulting program with the same base name as the source file. That is, the following call to build an executable program from the hello.c source file will build an executable program named hello on POSIX systems, and an executable program named hello.exe on Windows systems:

       Program('hello.c')
    

If you want to build a program with a different name than the base of the source file name, you simply put the target file name to the left of the source file name:

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

(SCons requires the target file name first, followed by the source file name, so that the order mimics that of an assignment statement in most programming languages, including Python: "program = source files".)

Now SCons will build an executable program named new_hello when run on a POSIX system:

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

And SCons will build an executable program named new_hello.exe when run on a Windows system:

       C:\>scons -Q
       cl /nologo /c hello.c /Fohello.obj
       link /nologo /OUT:new_hello.exe hello.obj
    

Compiling Multiple Source Files

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(['main.c', 'file1.c', 'file2.c'])
    

A build of the above example would look like:

       % scons -Q
       cc -c -o file1.o file1.c
       cc -c -o file2.o file2.c
       cc -c -o main.o main.c
       cc -o main main.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 we've seen in the previous section) you slide the list of source files over to the right to make room for the output program file name. (SCons puts the output file name to the left of the source file names so that the order mimics that of an assignment statement: "program = source files".) This makes our example:

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

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

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

Or on Windows:

       C:\>scons -Q
       cl /nologo /c file1.c /Fofile1.obj
       cl /nologo /c file2.c /Fofile2.obj
       cl /nologo /c main.c /Fomain.obj
       link /nologo /OUT:program.exe main.obj file1.obj file2.obj
    

Specifying Single Files Vs. Lists of Files

We've now shown you 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 could 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.

Although SCons functions are forgiving about whether or not you use a string vs. a list for a single file name, Python itself is more strict about treating lists and strings differently. So where SCons allows either a string or list: # The following two calls both work correctly: Program('program1', 'program1.c') Program('program2', ['program2.c']) Trying to do "Python things" that mix strings and lists will cause errors or lead to incorrect results: 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'])

Making Lists of Files Easier to Read

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.

To make long lists of file names easier to deal with, SCons provides a Split function that takes a quoted list of file names, with the names separated by spaces or other white-space characters, and turns it into a list of separate file names. Using the Split function turns the previous example into:

       Program('program', Split('main.c file1.c file2.c'))
    

(If you're already familiar with Python, you'll have realized that this is similar to the split() method in the Python standard string module. Unlike the string.split() method, however, the Split function does not require a string as input and will wrap up a single non-string object in a list, or return its argument untouched if it's already a list. This comes in handy as a way to make sure arbitrary values can be passed to SCons functions without having to check the type of the variable by hand.)

Putting the call to the Split function inside the Program call can also be a little unwieldy. A more readable alternative is to assign the output from the Split call to a variable name, and then use the variable when calling the Program function:

       list = Split('main.c file1.c file2.c')
       Program('program', list)
    

Lastly, the Split function doesn't care how much white space separates the file names in the quoted string. This allows you to create lists of file names that span multiple lines, which often makes for easier editing:

       list = Split("""main.c
                       file1.c
                       file2.c""")
       Program('program', list)
    

(Note in this example that we used the Python "triple-quote" syntax, which allows a string to contain multiple lines. The three quotes can be either single or double quotes.)

Keyword Arguments

SCons also allows you to identify the output file and input source files using Python keyword arguments. The output file is known as the target, and the source file(s) are known (logically enough) as the source. The Python syntax for this is:

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

Because the keywords explicitly identify what each argument is, you can actually reverse the order if you prefer:

       list = Split('main.c file1.c file2.c')
       Program(source = list, 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.

Compiling Multiple Programs

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 -c -o bar1.o bar1.c
       cc -c -o bar2.o bar2.c
       cc -o bar bar1.o bar2.o
       cc -c -o foo.o foo.c
       cc -o foo foo.o
    

Notice that SCons does not necessarily build the programs in the same order in which you specify them in the SConstruct file. SCons does, however, recognize that the individual object files must be built before the resulting program can be built. We'll discuss this in greater detail in the "Dependencies" section, below.

Sharing Source Files Between Multiple Programs

It's common to re-use code by sharing source files between multiple programs. One way to do this is to create a library from the common source files, which can then be linked into resulting programs. (Creating libraries is discussed in the chapter called Building and Linking with Libraries, below.)

A more straightforward, but perhaps less convenient, way to share source files between multiple programs is simply to include the common files in the lists of source files for each program:

       Program(Split('foo.c common1.c common2.c'))
       Program('bar', Split('bar1.c bar2.c common1.c common2.c'))
    

SCons recognizes that the object files for the common1.c and common2.c source files each only need to be built once, even though the resulting object files are each linked in to both of the resulting executable programs:

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

If two or more programs share a lot of common source files, repeating the common files in the list for each program can be a maintenance problem when you need to change the list of common files. You can simplify this by creating a separate Python list to hold the common file names, and concatenating it with other lists using the Python + operator:

       common = ['common1.c', 'common2.c']
       foo_files = ['foo.c'] + common
       bar_files = ['bar1.c', 'bar2.c'] + common
       Program('foo', foo_files)
       Program('bar', bar_files)
    

This is functionally equivalent to the previous example.

Building Libraries

You build your own libraries by specifying Library instead of Program:

      Library('foo', ['f1.c', 'f2.c', 'f3.c'])
    

SCons uses the appropriate library prefix and suffix for your system. So on POSIX or Linux systems, the above example would build as follows (although ranlib may not be called on all systems):

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

On a Windows system, a build of the above example would look like:

      C:\>scons -Q
      cl /nologo /c f1.c /Fof1.obj
      cl /nologo /c f2.c /Fof2.obj
      cl /nologo /c f3.c /Fof3.obj
      lib /nologo /OUT:foo.lib f1.obj f2.obj f3.obj
    

The rules for the target name of the library are similar to those for programs: if you don't explicitly specify a target library name, SCons will deduce one from the name of the first source file specified, and SCons will add an appropriate file prefix and suffix if you leave them off.

        StaticLibrary('foo', ['f1.c', 'f2.c', 'f3.c'])
      

        SharedLibrary('foo', ['f1.c', 'f2.c', 'f3.c'])
      

        % scons -Q
        cc -c -o f1.os f1.c
        cc -c -o f2.os f2.c
        cc -c -o f3.os f3.c
        cc -shared -o libfoo.so f1.os f2.os f3.os
      

        C:\>scons -Q
        cl /nologo /c f1.c /Fof1.obj
        cl /nologo /c f2.c /Fof2.obj
        cl /nologo /c f3.c /Fof3.obj
        link /nologo /dll /out:foo.dll /implib:foo.lib f1.obj f2.obj f3.obj
        RegServerFunc(target, source, env)
      

Linking with Libraries

Usually, you build a library because you want to link it with one or more programs. You link libraries with a program by specifying the libraries in the $LIBS construction variable, and by specifying the directory in which the library will be found in the $LIBPATH construction variable:

      Library('foo', ['f1.c', 'f2.c', 'f3.c'])
      Program('prog.c', LIBS=['foo', 'bar'], LIBPATH='.')
    

Notice, of course, that you don't need to specify a library prefix (like lib) or suffix (like .a or .lib). SCons uses the correct prefix or suffix for the current system.

On a POSIX or Linux system, a build of the above example would look like:

      % scons -Q
      cc -c -o f1.o f1.c
      cc -c -o f2.o f2.c
      cc -c -o f3.o f3.c
      ar r libfoo.a f1.o f2.o f3.o
      ranlib libfoo.a
      cc -c -o prog.o prog.c
      cc -o prog prog.o -L. -lfoo -lbar
    

On a Windows system, a build of the above example would look like:

      C:\>scons -Q
      cl /nologo /c f1.c /Fof1.obj
      cl /nologo /c f2.c /Fof2.obj
      cl /nologo /c f3.c /Fof3.obj
      lib /nologo /OUT:foo.lib f1.obj f2.obj f3.obj
      cl /nologo /c prog.c /Foprog.obj
      link /nologo /OUT:prog.exe /LIBPATH:. foo.lib bar.lib prog.obj
    

As usual, notice that SCons has taken care of constructing the correct command lines to link with the specified library on each system.

Note also that, if you only have a single library to link with, you can specify the library name in single string, instead of a Python list, so that:

      Program('prog.c', LIBS='foo', LIBPATH='.')
    

is equivalent to:

      Program('prog.c', LIBS=['foo'], LIBPATH='.')
    

This is similar to the way that SCons handles either a string or a list to specify a single source file.

Finding Libraries: the $LIBPATH Construction Variable

By default, the linker will only look in certain system-defined directories for libraries. SCons knows how to look for libraries in directories that you specify with the $LIBPATH construction variable. $LIBPATH consists of a list of directory names, like so:

      Program('prog.c', LIBS = 'm',
                        LIBPATH = ['/usr/lib', '/usr/local/lib'])
    

Using a Python list is preferred because it's portable across systems. Alternatively, you could put all of the directory names in a single string, separated by the system-specific path separator character: a colon on POSIX systems:

      LIBPATH = '/usr/lib:/usr/local/lib'
    

or a semi-colon on Windows systems:

      LIBPATH = 'C:\\lib;D:\\lib'
    

(Note that Python requires that the backslash separators in a Windows path name be escaped within strings.)

When the linker is executed, SCons will create appropriate flags so that the linker will look for libraries in the same directories as SCons. So on a POSIX or Linux system, a build of the above example would look like:

      % scons -Q
      cc -c -o prog.o prog.c
      cc -o prog prog.o -L/usr/lib -L/usr/local/lib -lm
    

On a Windows system, a build of the above example would look like:

      C:\>scons -Q
      cl /nologo /c prog.c /Foprog.obj
      link /nologo /OUT:prog.exe /LIBPATH:\usr\lib /LIBPATH:\usr\local\lib m.lib prog.obj
    

Note again that SCons has taken care of the system-specific details of creating the right command-line options.

Builder Methods Return Lists of Target Nodes

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 source files to other builder methods,

For example, suppose that we want to build the two object files that make up a program with different options. This would mean calling the Object builder once for each object file, specifying the desired options:

    Object('hello.c', CCFLAGS='-DHELLO')
    Object('goodbye.c', CCFLAGS='-DGOODBYE')
    

One way to combine these object files into the resulting program would be to call the Program builder with the names of the object files listed as sources:

    Object('hello.c', CCFLAGS='-DHELLO')
    Object('goodbye.c', CCFLAGS='-DGOODBYE')
    Program(['hello.o', 'goodbye.o'])
    

The problem with listing the names as strings is that our SConstruct file is no longer portable across operating systems. It won't, for example, work on Windows because the object files there would be named hello.obj and goodbye.obj, not hello.o and goodbye.o.

A better solution is to assign the lists of targets returned by the calls to the Object builder to variables, which we can then concatenate in our call to the Program builder:

      hello_list = Object('hello.c', CCFLAGS='-DHELLO')
      goodbye_list = Object('goodbye.c', CCFLAGS='-DGOODBYE')
      Program(hello_list + goodbye_list)
    

This makes our SConstruct file portable again, the build output on Linux looking like:

       % scons -Q
       cc -DGOODBYE -c -o goodbye.o goodbye.c
       cc -DHELLO -c -o hello.o hello.c
       cc -o hello hello.o goodbye.o
    

And on Windows:

       C:\>scons -Q
       cl -DGOODBYE /c goodbye.c /Fogoodbye.obj
       cl -DHELLO /c hello.c /Fohello.obj
       link /nologo /OUT:hello.exe hello.obj goodbye.obj
    

We'll see examples of using the list of nodes returned by builder methods throughout the rest of this guide.

Explicitly Creating File and Directory Nodes

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, repectively, 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.

Printing Node File Names

One of the most common things you can do with a Node is use it to print the file name that the node represents. For example, the following SConstruct file:

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

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

      object_list = Object('hello.c')
      program_list = Program(object_list)
      print "The object file is:", object_list[0]
      print "The program file is:", 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 -c -o hello.o 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 /nologo /c hello.c /Fohello.obj
      link /nologo /OUT:hello.exe hello.obj
    

Using a Node's File Name as a String

Printing a Node's name as described in the previous section works because the string representation of a Node 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 program_name, "does not exist!"
    

Which executes as follows on a POSIX system:

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

Deciding When a Source File Has Changed: the SourceSignatures Function

The other side of avoiding unnecessary rebuilds is the fundamental build tool behavior of rebuilding things when a source file changes, so that the built software is up to date. SCons keeps track of this through a signature for each source file, and allows you to configure whether you want to use the source file contents or the modification time (timestamp) as the signature.

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

         % scons -Q hello
         cc -c -o hello.o hello.c
         cc -o hello hello.o
         % edit hello.c
             [CHANGE THE CONTENTS OF hello.c]
         % scons -Q hello
         cc -c -o hello.o hello.c
         cc -o hello hello.o
      

        Program('hello.c')
        SourceSignatures('MD5')
      

        Program('hello.c')
        SourceSignatures('timestamp')
      

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

Deciding When a Target File Has Changed: the TargetSignatures Function

As you've just seen, SCons uses signatures to decide whether a target file is up to date or must be rebuilt. When a target file depends on another target file, SCons allows you to configure separately how the signatures of "intermediate" target files are used when deciding if a dependent target file must be rebuilt.

         % scons -Q hello
         cc -c -o hello.o hello.c
         cc -o hello hello.o
         % edit hello.c
             [CHANGE THE CONTENTS OF hello.c]
         % scons -Q hello
         cc -c -o hello.o hello.c
         cc -o hello hello.o
      

        Program('hello.c')
        TargetSignatures('build')
      

        Program('hello.c')
        TargetSignatures('content')
      

         % scons -Q hello
         cc -c -o hello.o hello.c
         cc -o hello hello.o
         % edit hello.c
           [CHANGE A COMMENT IN hello.c]
         % scons -Q hello
         cc -c -o hello.o hello.c
         scons: `hello' is up to date.
      

Implicit Dependencies: The $CPPPATH Construction Variable

Now suppose that our "Hello, World!" program actually has a #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 = '.')
      

The $CPPPATH value tells SCons to look in the current directory ('.') for any files included by C source files (.c or .h files). With this assignment in the SConstruct file:

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

First, notice that SCons added the -I. argument from the $CPPPATH variable so that the compilation would find the hello.h file in the local directory.

Second, realize that SCons knows that the hello program must be rebuilt because it scans the contents of the hello.c file for the #include lines that indicate another file is being included in the compilation. SCons records these as implicit dependencies of the target file, Consequently, when the hello.h file changes, SCons realizes that the hello.c file includes it, and rebuilds the resulting hello program that depends on both the hello.c and hello.h files.

Like the $LIBPATH variable, the $CPPPATH variable may be a list of directories, or a string separated by the system-specific path separate character (':' on POSIX/Linux, ';' on Windows). Either way, SCons creates the right command-line options so that the following example:

       Program('hello.c', CPPPATH = ['include', '/home/project/inc'])
    

Will look like this on POSIX or Linux:

       % scons -Q hello
       cc -Iinclude -I/home/project/inc -c -o hello.o hello.c
       cc -o hello hello.o
    

And like this on Windows:

       C:\>scons -Q hello.exe
       cl /nologo /Iinclude /I\home\project\inc /c hello.c /Fohello.obj
       link /nologo /OUT:hello.exe hello.obj
    

Caching Implicit Dependencies

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 -c -o hello.o 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 -Q --implicit-deps-changed hello
         cc -c -o hello.o hello.c
         cc -o hello hello.o
         % scons -Q hello
         scons: `hello' is up to date.
      

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

Ignoring Dependencies: the Ignore Method

Sometimes it makes sense to not rebuild a program, even if a dependency file changes. In this case, you would tell SCons specifically to ignore a dependency as follows:

      hello = Program('hello.c')
      Ignore(hello, 'hello.h')
    

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

Now, the above example is a little contrived, because it's hard to imagine a real-world situation where you wouldn't to rebuild hello if the hello.h file changed. A more realistic example might be if the hello program is being built in a directory that is shared between multiple systems that have different copies of the stdio.h include file. In that case, SCons would notice the differences between the different systems' copies of stdio.h and would rebuild hello each time you change systems. You could avoid these rebuilds as follows:

       hello = Program('hello.c')
       Ignore(hello, '/usr/include/stdio.h')
    

Explicit Dependencies: the Depends Method

On the other hand, sometimes a file depends on another file that is not detected by an SCons scanner. For this situation, SCons allows you to specific explicitly that one file depends on another file, and must be rebuilt whenever that file changes. This is specified using the Depends method:

       hello = Program('hello.c')
       Depends(hello, 'other_file')
    

       % scons -Q hello
       cc -c hello.c -o hello.o
       cc -o hello hello.o
       % scons -Q hello
       scons: `hello' is up to date.
       % edit other_file
           [CHANGE THE CONTENTS OF other_file]
       % scons -Q hello
       cc -c hello.c -o hello.o
       cc -o hello hello.o
    

Multiple Construction Environments

The real advantage of construction environments is that you can create as many different construction environments as you need, each tailored to a different way to build some piece of software or other file. If, for example, we need to build one program with the -O2 flag and another with the -g (debug) flag, we would do this like so:

      opt = Environment(CCFLAGS = '-O2')
      dbg = Environment(CCFLAGS = '-g')

      opt.Program('foo', 'foo.c')

      dbg.Program('bar', 'bar.c')
   

      % scons -Q
      cc -g -c -o bar.o bar.c
      cc -o bar bar.o
      cc -O2 -c -o foo.o foo.c
      cc -o foo foo.o
   

We can even use multiple construction environments to build multiple versions of a single program. If you do this by simply trying to use the Program builder with both environments, though, like this:

      opt = Environment(CCFLAGS = '-O2')
      dbg = Environment(CCFLAGS = '-g')

      opt.Program('foo', 'foo.c')

      dbg.Program('foo', 'foo.c')
   

Then SCons generates the following error:

      % scons -Q
      
      scons: *** Two environments with different actions were specified for the same target: foo.o
      File "SConstruct", line 6, in ?
   

This is because the two Program calls have each implicitly told SCons to generate an object file named foo.o, one with a $CCFLAGS value of -O2 and one with a $CCFLAGS value of -g. SCons can't just decide that one of them should take precedence over the other, so it generates the error. To avoid this problem, we must explicitly specify that each environment compile foo.c to a separately-named object file using the Object builder, like so:

      opt = Environment(CCFLAGS = '-O2')
      dbg = Environment(CCFLAGS = '-g')

      o = opt.Object('foo-opt', 'foo.c')
      opt.Program(o)

      d = dbg.Object('foo-dbg', 'foo.c')
      dbg.Program(d)
   

Notice that each call to the Object builder returns a value, an internal SCons object that represents the object file that will be built. We then use that object as input to the Program builder. This avoids having to specify explicitly the object file name in multiple places, and makes for a compact, readable SConstruct file. Our SCons output then looks like:

      % scons -Q
      cc -g -c -o foo-dbg.o foo.c
      cc -o foo-dbg foo-dbg.o
      cc -O2 -c -o foo-opt.o foo.c
      cc -o foo-opt foo-opt.o
   

Copying Construction Environments

Sometimes you want more than one construction environment to share the same values for one or more variables. Rather than always having to repeat all of the common variables when you create each construction environment, you can use the Copy method to create a copy of a construction environment.

Like the Environment call that creates a construction environment, the Copy method takes construction variable assignments, which will override the values in the copied construction environment. For example, suppose we want to use gcc to create three versions of a program, one optimized, one debug, and one with neither. We could do this by creating a "base" construction environment that sets $CC to gcc, and then creating two copies, one which sets $CCFLAGS for optimization and the other which sets $CCFLAGS for debugging:

      env = Environment(CC = 'gcc')
      opt = env.Copy(CCFLAGS = '-O2')
      dbg = env.Copy(CCFLAGS = '-g')

      env.Program('foo', 'foo.c')

      o = opt.Object('foo-opt', 'foo.c')
      opt.Program(o)

      d = dbg.Object('foo-dbg', 'foo.c')
      dbg.Program(d)
   

Then our output would look like:

      % scons -Q
      gcc -c -o foo.o foo.c
      gcc -o foo foo.o
      gcc -g -c -o foo-dbg.o foo.c
      gcc -o foo-dbg foo-dbg.o
      gcc -O2 -c -o foo-opt.o foo.c
      gcc -o foo-opt foo-opt.o
   

Fetching Values From a Construction Environment

You can fetch individual construction variables using the normal syntax for accessing individual named items in a Python dictionary:

      env = Environment()
      print "CC is:", env['CC']
   

This example SConstruct file doesn't build anything, but because it's actually a Python script, it will print the value of $CC for us:

      % scons -Q
      CC is: cc
      scons: `.' is up to date.
   

A construction environment, however, is actually an object with associated methods, etc. If you want to have direct access to only the dictionary of construction variables, you can fetch this using the Dictionary method:

      env = Environment(FOO = 'foo', BAR = 'bar')
      dict = env.Dictionary()
      for key in ['OBJSUFFIX', 'LIBSUFFIX', 'PROGSUFFIX']:
          print "key = %s, value = %s" % (key, dict[key])
   

This SConstruct file will print the specified dictionary items for us on POSIX systems as follows:

      % scons -Q
      key = OBJSUFFIX, value = .o
      key = LIBSUFFIX, value = .a
      key = PROGSUFFIX, value = 
      scons: `.' is up to date.
   

And on Win32:

      C:\>scons -Q
      key = OBJSUFFIX, value = .obj
      key = LIBSUFFIX, value = .lib
      key = PROGSUFFIX, value = .exe
      scons: `.' is up to date.
   

If you want to loop through and print the values of all of the construction variables in a construction environment, the Python code to do that in sorted order might look something like:

      env = Environment()
      dict = env.Dictionary()
      keys = dict.keys()
      keys.sort()
      for key in keys:
          print "construction variable = '%s', value = '%s'" % (key, dict[key])
   

Expanding Values From a Construction Environment

Another way to get information from a construction environment. is to use the subst method