Dependencies

So far we've seen how SCons handles one-time builds. But the real point of a build tool like SCons is to rebuild only the necessary things when source files change--or, put another way, SCons should not waste time rebuilding things that have already been built. You can see this at work simply be re-invoking SCons after building our simple hello example:

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

The second time it is executed, SCons realizes that the hello program is up-to-date with respect to the current hello.c source file, and avoids rebuilding it. You can see this more clearly by naming the hello program explicitly on the command line:

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

Note that SCons reports "...is up to date" only for target files named explicitly on the command line, to avoid cluttering the output.

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.

MD5 Source File Signatures

By default, SCons keeps track of whether a source file has changed based on the file's contents, not the modification time. This means that you may be surprised by the default SCons behavior if you are used to the Make convention of forcing a rebuild by updating the file's modification time (using the touch command, for example):

         % 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.
      

Even though the file's modification time has changed, SCons realizes that the contents of the hello.c file have not changed, and therefore that the hello program need not be rebuilt. This avoids unnecessary rebuilds when, for example, someone rewrites the contents of a file without making a change. But if the contents of the file really do change, then SCons detects the change and rebuilds the program as required:

         % 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
      

Note that you can, if you wish, specify this default behavior (MD5 signatures) explicitly using the SourceSignatures function as follows:

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

Source File Time Stamps

If you prefer, you can configure SCons to use the modification time of source files, not the file contents, when deciding if something needs to be rebuilt. To do this, call the SourceSignatures function as follows:

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

This makes SCons act like Make when a file's modification time is updated (using the touch command, for example):

         % 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