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: Program('hello.c') int main() { printf("Hello, world!\n"); } scons -Q scons -Q 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 scons -Q hello Note that &SCons; reports "...is up to date" only for target files named explicitly on the command line, to avoid cluttering the output.

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.

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 touch hello.c scons -Q hello 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 edit hello.c scons -Q hello 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')

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') int main() { printf("Hello, world!\n"); } This makes &SCons; act like &Make; when a file's modification time is updated (using the &touch; command, for example): scons -Q hello touch hello.c scons -Q hello

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 separately configure how the signatures of "intermediate" target files are used when deciding if a dependent target file must be rebuilt.

Modifying a source file will cause not only its direct target file to be rebuilt, but also the target file(s) that depend on that direct target file. In our example, changing the contents of the &hello_c; file causes the &hello_o; file to be rebuilt, which in turn causes the &hello; program to be rebuilt: scons -Q hello edit hello.c scons -Q hello What's not obvious, though, is that &SCons; internally handles the signature of the target file(s) (&hello_o; in the above example) differently from the signature of the source file (&hello_c;). By default, &SCons; tracks whether a target file must be rebuilt by using a &buildsignature; that consists of the combined signatures of all the files that go into making the target file. This is efficient because the accumulated signatures actually give &SCons; all of the information it needs to decide if the target file is out of date. If you wish, you can specify this default behavior (build signatures) explicitly using the &TargetSignatures; function: Program('hello.c') TargetSignatures('build')

Sometimes a source file can be changed in such a way that the contents of the rebuilt target file(s) will be exactly the same as the last time the file was built. If so, then any other target files that depend on such a built-but-not-changed target file actually need not be rebuilt. You can make &SCons; realize that it does not need to rebuild a dependent target file in this situation using the &TargetSignatures; function as follows: Program('hello.c') TargetSignatures('content') int main() { printf("Hello, world!\n"); } So if, for example, a user were to only change a comment in a C file, then the rebuilt &hello_o; file would be exactly the same as the one previously built (assuming the compiler doesn't put any build-specific information in the object file). &SCons; would then realize that it would not need to rebuild the &hello; program as follows: scons -Q hello edit hello.c scons -Q hello In essence, &SCons; has "short-circuited" any dependent builds when it realizes that a target file has been rebuilt to exactly the same file as the last build. So configured, &SCons; does take some extra processing time to scan the contents of the target (&hello_o;) file, but this may save time if the rebuild that was avoided would have been very time-consuming and expensive.

Now suppose that our "Hello, World!" program actually has a #include line to include the &hello_h; file in the compilation: Program('hello.c', CPPPATH = '.') #include <hello.h> int main() { printf("Hello, %s!\n", string); } #define string "world" And, for completeness, the &hello_h; file looks like this: 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: 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 scons -Q hello edit hello.h scons -Q hello 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']) int main() { printf("Hello, world!\n"); } Will look like this on POSIX or Linux: scons -Q hello And like this on Windows: scons -Q hello.exe

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 scons -Q hello 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)

When using cached implicit dependencies, sometimes you want to "start fresh" and have &SCons; re-scan the files for which it previously cached the dependencies. For example, if you have recently installed a new version of external code that you use for compilation, the external header files will have changed and the previously-cached implicit dependencies will be out of date. You can update them by running &SCons; with the &implicit-deps-changed; option: scons -Q --implicit-deps-changed hello scons -Q hello In this case, &SCons; will re-scan all of the implicit dependencies and cache updated copies of the information.

By default when caching dependencies, &SCons; notices when a file has been modified and re-scans the file for any updated implicit dependency information. Sometimes, however, you may want to force &SCons; to use the cached implicit dependencies, even if the source files changed. This can speed up a build for example, when you have changed your source files but know that you haven't changed any #include lines. In this case, you can use the &implicit-deps-unchanged; option: scons -Q --implicit-deps-unchanged hello scons -Q hello In this case, &SCons; will assume that the cached implicit dependencies are correct and will not bother to re-scan changed files. For typical builds after small, incremental changes to source files, the savings may not be very big, but sometimes every bit of improved performance counts.

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') #include "hello.h" int main() { printf("Hello, %s!\n", string); } #define string "world" % 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')

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

XXX

-->