%scons; %builders-mod; %functions-mod; %tools-mod; %variables-mod; ]> The source code for large software projects rarely stays in a single directory, but is nearly always divided into a hierarchy of directories. Organizing a large software build using &SCons; involves creating a hierarchy of build scripts using the &SConscript; function.

As we've already seen, the build script at the top of the tree is called &SConstruct;. The top-level &SConstruct; file can use the &SConscript; function to include other subsidiary scripts in the build. These subsidiary scripts can, in turn, use the &SConscript; function to include still other scripts in the build. By convention, these subsidiary scripts are usually named &SConscript;. For example, a top-level &SConstruct; file might arrange for four subsidiary scripts to be included in the build as follows: SConscript(['drivers/display/SConscript', 'drivers/mouse/SConscript', 'parser/SConscript', 'utilities/SConscript']) In this case, the &SConstruct; file lists all of the &SConscript; files in the build explicitly. (Note, however, that not every directory in the tree necessarily has an &SConscript; file.) Alternatively, the drivers subdirectory might contain an intermediate &SConscript; file, in which case the &SConscript; call in the top-level &SConstruct; file would look like: SConscript(['drivers/SConscript', 'parser/SConscript', 'utilities/SConscript']) And the subsidiary &SConscript; file in the drivers subdirectory would look like: SConscript(['display/SConscript', 'mouse/SConscript']) Whether you list all of the &SConscript; files in the top-level &SConstruct; file, or place a subsidiary &SConscript; file in intervening directories, or use some mix of the two schemes, is up to you and the needs of your software.

Subsidiary &SConscript; files make it easy to create a build hierarchy because all of the file and directory names in a subsidiary &SConscript; files are interpreted relative to the directory in which the &SConscript; file lives. Typically, this allows the &SConscript; file containing the instructions to build a target file to live in the same directory as the source files from which the target will be built, making it easy to update how the software is built whenever files are added or deleted (or other changes are made). For example, suppose we want to build two programs &prog1; and &prog2; in two separate directories with the same names as the programs. One typical way to do this would be with a top-level &SConstruct; file like this: SConscript(['prog1/SConscript', 'prog2/SConscript']) env = Environment() env.Program('prog1', ['main.c', 'foo1.c', 'foo2.c']) env = Environment() env.Program('prog2', ['main.c', 'bar1.c', 'bar2.c']) x x x x x x And subsidiary &SConscript; files that look like this: And this: Then, when we run &SCons; in the top-level directory, our build looks like: scons -Q Notice the following: First, you can have files with the same names in multiple directories, like main.c in the above example. Second, unlike standard recursive use of &Make;, &SCons; stays in the top-level directory (where the &SConstruct; file lives) and issues commands that use the path names from the top-level directory to the target and source files within the hierarchy.

If you need to use a file from another directory, it's sometimes more convenient to specify the path to a file in another directory from the top-level &SConstruct; directory, even when you're using that file in a subsidiary &SConscript; file in a subdirectory. You can tell &SCons; to interpret a path name as relative to the top-level &SConstruct; directory, not the local directory of the &SConscript; file, by appending a &hash; (hash mark) to the beginning of the path name: SConscript('src/prog/SConscript') env = Environment() env.Program('prog', ['main.c', '#lib/foo1.c', 'foo2.c']) x x x In this example, the lib directory is directly underneath the top-level &SConstruct; directory. If the above &SConscript; file is in a subdirectory named src/prog, the output would look like: scons -Q (Notice that the lib/foo1.o object file is built in the same directory as its source file. See , below, for information about how to build the object file in a different subdirectory.)

Of course, you can always specify an absolute path name for a file--for example: SConscript('src/prog/SConscript') env = Environment() env.Program('prog', ['main.c', '__ROOT__/usr/joe/lib/foo1.c', 'foo2.c']) x x x Which, when executed, would yield: scons -Q (As was the case with top-relative path names, notice that the /usr/joe/lib/foo1.o object file is built in the same directory as its source file. See , below, for information about how to build the object file in a different subdirectory.)

In the previous example, each of the subsidiary &SConscript; files created its own construction environment by calling &Environment; separately. This obviously works fine, but if each program must be built with the same construction variables, it's cumbersome and error-prone to initialize separate construction environments in the same way over and over in each subsidiary &SConscript; file. &SCons; supports the ability to export variables from a parent &SConscript; file to its subsidiary &SConscript; files, which allows you to share common initialized values throughout your build hierarchy.

There are two ways to export a variable, such as a construction environment, from an &SConscript; file, so that it may be used by other &SConscript; files. First, you can call the &Export; function with a list of variables, or a string of white-space separated variable names. Each call to &Export; adds one or more variables to a global list of variables that are available for import by other &SConscript; files. env = Environment() Export('env') You may export more than one variable name at a time: env = Environment() debug = ARGUMENTS['debug'] Export('env', 'debug') Because white space is not legal in Python variable names, the &Export; function will even automatically split a string into separate names for you: Export('env debug') Second, you can specify a list of variables to export as a second argument to the &SConscript; function call: SConscript('src/SConscript', 'env') Or as the &exports; keyword argument: SConscript('src/SConscript', exports='env') These calls export the specified variables to only the listed &SConscript; files. You may, however, specify more than one &SConscript; file in a list: SConscript(['src1/SConscript', 'src2/SConscript'], exports='env') This is functionally equivalent to calling the &SConscript; function multiple times with the same &exports; argument, one per &SConscript; file.

Once a variable has been exported from a calling &SConscript; file, it may be used in other &SConscript; files by calling the &Import; function: Import('env') env.Program('prog', ['prog.c']) The &Import; call makes the env construction environment available to the &SConscript; file, after which the variable can be used to build programs, libraries, etc. Like the &Export; function, the &Import; function can be used with multiple variable names: Import('env', 'debug') env = env.Clone(DEBUG = debug) env.Program('prog', ['prog.c']) And the &Import; function will similarly split a string along white-space into separate variable names: Import('env debug') env = env.Clone(DEBUG = debug) env.Program('prog', ['prog.c']) Lastly, as a special case, you may import all of the variables that have been exported by supplying an asterisk to the &Import; function: Import('*') env = env.Clone(DEBUG = debug) env.Program('prog', ['prog.c']) If you're dealing with a lot of &SConscript; files, this can be a lot simpler than keeping arbitrary lists of imported variables in each file.

Sometimes, you would like to be able to use information from a subsidiary &SConscript; file in some way. For example, suppose that you want to create one library from source files scattered throughout a number of subsidiary &SConscript; files. You can do this by using the &Return; function to return values from the subsidiary &SConscript; files to the calling file. If, for example, we have two subdirectories &foo; and &bar; that should each contribute a source file to a Library, what we'd like to be able to do is collect the object files from the subsidiary &SConscript; calls like this: env = Environment() Export('env') objs = [] for subdir in ['foo', 'bar']: o = SConscript('%s/SConscript' % subdir) objs.append(o) env.Library('prog', objs) Import('env') obj = env.Object('foo.c') Return('obj') Import('env') obj = env.Object('bar.c') Return('obj') void foo(void) { printf("foo/foo.c\n"); } void bar(void) { printf("bar/bar.c\n"); } We can do this by using the &Return; function in the foo/SConscript file like this: (The corresponding bar/SConscript file should be pretty obvious.) Then when we run &SCons;, the object files from the subsidiary subdirectories are all correctly archived in the desired library: scons -Q