Older Functions for Deciding When an Input File Has Changed

SCons User Guide 0.98.0
Prev | Chapter 6. Dependencies | Next

# 6.2. Older Functions for Deciding When an Input File Has Changed

SCons still supports two functions that used to be the primary methods for configuring the decision about whether or not an input file has changed. Although they're not officially deprecated yet, their use is discouraged, mainly because they rely on a somewhat confusing distinction between how source files and target files are handled. These functions are documented here mainly in case you encounter them in existing `SConscript` files.

## 6.2.1. The `SourceSignatures` Function

The `SourceSignatures` function is fairly straightforward, and supports two different argument values to configure whether source file changes should be decided using MD5 signatures:

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

Or using time stamps:

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

These are roughly equivalent to specifying `Decider('MD5')` or `Decider('timestamp-match')`, respectively, although it only affects how SCons makes decisions about dependencies on source files--that is, files that are not built from any other files.

## 6.2.2. The `TargetSignatures` Function

The `TargetSignatures` function specifies how SCons decides when a target file has changed when it is used as a dependency of (input to) another target--that is, the `TargetSignatures` function configures how the signatures of "intermediate" target files are used when deciding if a "downstream" target file must be rebuilt. [1]

The `TargetSignatures` function supports the same `'MD5'` and `'timestamp'` argument values that are supported by the `SourceSignatures`, with the same meanings, but applied to target files. That is, in the example:

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

The MD5 checksum of the `hello.o` target file will be used to decide if it has changed since the last time the "downstream" hello target file was built. And in the example:

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

The modification time of the `hello.o` target file will be used to decide if it has changed since the last time the "downstream" hello target file was built.

The `TargetSignatures` function supports two additional argument values: `'source'` and `'build'`. The `'source'` argument specifies that decisions involving whether target files have changed since a previous build should use the same behavior for the decisions configured for source files (using the `SourceSignatures` function). So in the example:

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

All files, both targets and sources, will use modification times when deciding if an input file has changed since the last time a target was built.

Lastly, the `'build'` argument specifies that SCons should examine the build status of a target file and always rebuild a "downstream" target if the target file was itself rebuilt, without re-examining the contents or timestamp of the newly-built target file. If the target file was not rebuilt during this scons invocation, then the target file will be examined the same way as configured by the `SourceSignature` call to decide if it has changed.

This mimics the behavior of `build signatures` in earlier versions of SCons. A `build signature` re-combined signatures of all the input files that went into making the target file, so that the target file itself did not need to have its contents read to compute an MD5 signature. This can improve performance for some configurations, but is generally not as effective as using `Decider('MD5-timestamp')`.

### Notes

[1] | This easily-overlooked distinction between how SCons decides if the target itself must be rebuilt and how the target is then used to decide if a different target must be rebuilt is one of the confusing things that has led to the `TargetSignatures` and `SourceSignatures` functions being replaced by the simpler `Decider` function.

Prev | Home | Next
Dependencies | Up | Implicit Dependencies: The `$CPPPATH` Construction Variable