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: env = Environment() env.Program('hello.c') int main() { printf("Hello, world!\n"); } scons scons 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 hello scons 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 hello touch hello.c scons 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 hello edit hello.c scons hello Note that you can, if you wish, specify this default behavior (MD5 signatures) explicitly using the &SourceSignatures; function as follows: env = Environment() env.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: env = Environment() env.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 hello touch hello.c scons 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 an "intermediate" target file is 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 hello edit hello.c scons 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: env = Environment() env.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 have &SCons; realize that a dependent target file need not be rebuilt in this situation using the &TargetSignatures; function as follows: env = Environment() env.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 hello edit hello.c scons 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: env = Environment(CPPPATH = '.') hello = env.Program('hello.c') #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; assignment in the &Environment; call 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 hello scons hello edit hello.h scons 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: env = Environment(CPPPATH = ['include', '/home/project/inc']) hello = env.Program('hello.c') int main() { printf("Hello, world!\n"); } Will look like this on POSIX or Linux: scons hello And like this on Windows: scons hello

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 do this either by specifying the &implicit-cache; option on the command line: scons --implicit-cache hello scons hello Or 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 XXX XXX

XXX

XXX

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: env = Environment() hello = env.Program('hello.c') env.Ignore(hello, 'hello.h') % scons hello cc -c hello.c -o hello.o cc -o hello hello.o % scons hello scons: `hello' is up to date. % edit hello.h [CHANGE THE CONTENTS OF hello.h] % scons 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: env = Environment() hello = env.Program('hello.c') env.Ignore(hello, '/usr/include/stdio.h')

On the other hand, sometimes a file depends on another file that has no &SCons; scanner will detect. 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: env = Environment() hello = env.Program('hello.c') env.Depends(hello, 'other_file') % scons hello cc -c hello.c -o hello.o cc -o hello hello.o % scons hello scons: `hello' is up to date. % edit other_file [CHANGE THE CONTENTS OF other_file] % scons hello cc -c hello.c -o hello.o cc -o hello hello.o

XXX

-->