5 Permission is hereby granted, free of charge, to any person obtaining
6 a copy of this software and associated documentation files (the
7 "Software"), to deal in the Software without restriction, including
8 without limitation the rights to use, copy, modify, merge, publish,
9 distribute, sublicense, and/or sell copies of the Software, and to
10 permit persons to whom the Software is furnished to do so, subject to
11 the following conditions:
13 The above copyright notice and this permission notice shall be included
14 in all copies or substantial portions of the Software.
16 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY
17 KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
18 WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
19 NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
20 LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
21 OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
22 WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
28 =head1 Separating source and build trees
30 It's often desirable to keep any derived files from the build completely
31 separate from the source files. This makes it much easier to keep track of
32 just what is a source file, and also makes it simpler to handle B<variant>
33 builds, especially if you want the variant builds to co-exist.
35 =head2 Separating build and source directories using the Link command
37 Cons provides a simple mechanism that handles all of these requirements. The
38 C<Link> command is invoked as in this example:
40 Link 'build' => 'src';
42 The specified directories are ``linked'' to the specified source
43 directory. Let's suppose that you setup a source directory, F<src>, with the
44 sub-directories F<world> and F<hello> below it, as in the previous
45 example. You could then substitute for the original build lines the
53 Notice that you treat the F<Conscript> file as if it existed in the build
54 directory. Now if you type the same command as before, you will get the
58 Install build/world/world.h as export/include/world.h
59 cc -Iexport/include -c build/hello/hello.c -o build/hello/hello.o
60 cc -Iexport/include -c build/world/world.c -o build/world/world.o
61 ar r build/world/libworld.a build/world/world.o
62 ar: creating build/world/libworld.a
63 ranlib build/world/libworld.a
64 Install build/world/libworld.a as export/lib/libworld.a
65 cc -o build/hello/hello build/hello/hello.o -Lexport/lib -lworld
66 Install build/hello/hello as export/bin/hello
68 Again, Cons has taken care of the details for you. In particular, you will
69 notice that all the builds are done using source files and object files from
70 the build directory. For example, F<build/world/world.o> is compiled from
71 F<build/world/world.c>, and F<export/include/world.h> is installed from
72 F<build/world/world.h>. This is accomplished on most systems by the simple
73 expedient of ``hard'' linking the required files from each source directory
74 into the appropriate build directory.
76 The links are maintained correctly by Cons, no matter what you do to the
77 source directory. If you modify a source file, your editor may do this ``in
78 place'' or it may rename it first and create a new file. In the latter case,
79 any hard link will be lost. Cons will detect this condition the next time
80 the source file is needed, and will relink it appropriately.
82 You'll also notice, by the way, that B<no> changes were required to the
83 underlying F<Conscript> files. And we can go further, as we shall see in the
86 =head2 Explicit references to the source directory
88 When using the C<Link> command on some operating systems or with some
89 tool chains, it's sometimes useful to have a command actually use
90 the path name to the source directory, not the build directory. For
91 example, on systems that must copy, not "hard link," the F<src/> and
92 F<build/> copies of C<Linked> files, using the F<src/> path of a file
93 name might make an editor aware that a syntax error must be fixed in the
94 source directory, not the build directory.
96 You can tell Cons that you want to use the "source path" for a file by
97 preceding the file name with a ``!'' (exclamation point). For example,
98 if we add a ``!'' to the beginning of a source file:
100 Program $env "foo", "!foo.c"; # Notice initial ! on foo.c
102 Cons will compile the target as follows:
104 cc -c src/foo.c -o build/foo.o
105 cc -o build/foo build/foo.o
107 Notice that Cons has compiled the program from the the F<src/foo.c>
108 source file. Without the initial ``!'', Cons would have compiled the
109 program using the F<build/foo.c> path name.
115 It's often useful to keep any built files completely
116 separate from the source files.
117 In &SCons;, this is usually done by creating one or more separate
118 <emphasis>variant directory trees</emphasis>
119 that are used to hold the built objects files, libraries,
120 and executable programs, etc.
121 for a specific flavor, or variant, of build.
122 &SCons; provides two ways to do this,
123 one through the &SConscript; function that we've already seen,
124 and the second through a more flexible &VariantDir; function.
130 One historical note: the &VariantDir; function
131 used to be called &BuildDir;.
132 That name is still supported
133 but has been deprecated
134 because the &SCons; functionality
135 differs from the model of a "build directory"
136 implemented by other build systems like the GNU Autotools.
141 <title>Specifying a Variant Directory Tree as Part of an &SConscript; Call</title>
145 The most straightforward way to establish a variant directory tree
146 uses the fact that the usual way to
147 set up a build hierarchy is to have an
148 &SConscript; file in the source subdirectory.
149 If you then pass a &variant_dir; argument to the
150 &SConscript; function call:
154 <scons_example name="ex1">
155 <file name="SConstruct" printme="1">
156 SConscript('src/SConscript', variant_dir='build')
158 <file name="src/SConscript">
160 env.Program('hello.c')
162 <file name="src/hello.c">
163 int main() { printf("Hello, world!\n"); }
169 &SCons; will then build all of the files in
170 the &build; subdirectory:
174 <scons_output example="ex1">
175 <scons_output_command>ls src</scons_output_command>
176 <scons_output_command>scons -Q</scons_output_command>
177 <scons_output_command>ls build</scons_output_command>
182 But wait a minute--what's going on here?
183 &SCons; created the object file
184 <filename>build/hello.o</filename>
185 in the &build; subdirectory,
187 But even though our &hello_c; file lives in the &src; subdirectory,
188 &SCons; has actually compiled a
189 <filename>build/hello.c</filename> file
190 to create the object file.
196 What's happened is that &SCons; has <emphasis>duplicated</emphasis>
197 the &hello_c; file from the &src; subdirectory
198 to the &build; subdirectory,
199 and built the program from there.
200 The next section explains why &SCons; does this.
207 <title>Why &SCons; Duplicates Source Files in a Variant Directory Tree</title>
211 &SCons; duplicates source files in variant directory trees
212 because it's the most straightforward way to guarantee a correct build
213 <emphasis>regardless of include-file directory paths,
214 relative references between files,
215 or tool support for putting files in different locations</emphasis>,
216 and the &SCons; philosophy is to, by default,
217 guarantee a correct build in all cases.
223 The most direct reason to duplicate source files
224 in variant directories
225 is simply that some tools (mostly older versions)
226 are written to only build their output files
227 in the same directory as the source files.
228 In this case, the choices are either
229 to build the output file in the source directory
230 and move it to the variant directory,
231 or to duplicate the source files in the variant directory.
238 relative references between files
239 can cause problems if we don't
240 just duplicate the hierarchy of source files
241 in the variant directory.
242 You can see this at work in
243 use of the C preprocessor <literal>#include</literal>
244 mechanism with double quotes, not angle brackets:
254 The <emphasis>de facto</emphasis> standard behavior
255 for most C compilers in this case
256 is to first look in the same directory
257 as the source file that contains the <literal>#include</literal> line,
258 then to look in the directories in the preprocessor search path.
259 Add to this that the &SCons; implementation of
260 support for code repositories
262 means not all of the files
263 will be found in the same directory hierarchy,
264 and the simplest way to make sure
265 that the right include file is found
266 is to duplicate the source files into the variant directory,
267 which provides a correct build
268 regardless of the original location(s) of the source files.
274 Although source-file duplication guarantees a correct build
275 even in these end-cases,
276 it <emphasis>can</emphasis> usually be safely disabled.
277 The next section describes
278 how you can disable the duplication of source files
279 in the variant directory.
286 <title>Telling &SCons; to Not Duplicate Source Files in the Variant Directory Tree</title>
290 In most cases and with most tool sets,
291 &SCons; can place its target files in a build subdirectory
292 <emphasis>without</emphasis>
293 duplicating the source files
294 and everything will work just fine.
295 You can disable the default &SCons; behavior
296 by specifying <literal>duplicate=0</literal>
297 when you call the &SConscript; function:
302 SConscript('src/SConscript', variant_dir='build', duplicate=0)
307 When this flag is specified,
308 &SCons; uses the variant directory
309 like most people expect--that is,
310 the output files are placed in the variant directory
311 while the source files stay in the source directory:
316 % <userinput>ls src</userinput>
319 % <userinput>scons -Q</userinput>
320 cc -c src/hello.c -o build/hello.o
321 cc -o build/hello build/hello.o
322 % <userinput>ls build</userinput>
330 <title>The &VariantDir; Function</title>
334 Use the &VariantDir; function to establish that target
335 files should be built in a separate directory
336 from the source files:
340 <scons_example name="ex_builddir">
341 <file name="SConstruct" printme="1">
342 VariantDir('build', 'src')
344 env.Program('build/hello.c')
346 <file name="src/hello.c">
347 int main() { printf("Hello, world!\n"); }
353 Note that when you're not using
354 an &SConscript; file in the &src; subdirectory,
355 you must actually specify that
356 the program must be built from
357 the <filename>build/hello.c</filename>
358 file that &SCons; will duplicate in the
359 &build; subdirectory.
365 When using the &VariantDir; function directly,
366 &SCons; still duplicates the source files
367 in the variant directory by default:
371 <scons_output example="ex_builddir">
372 <scons_output_command>ls src</scons_output_command>
373 <scons_output_command>scons -Q</scons_output_command>
374 <scons_output_command>ls build</scons_output_command>
379 You can specify the same <literal>duplicate=0</literal> argument
380 that you can specify for an &SConscript; call:
384 <scons_example name="ex_duplicate_0">
385 <file name="SConstruct" printme="1">
386 VariantDir('build', 'src', duplicate=0)
388 env.Program('build/hello.c')
390 <file name="src/hello.c">
391 int main() { printf("Hello, world!\n"); }
397 In which case &SCons;
398 will disable duplication of the source files:
402 <scons_output example="ex_duplicate_0">
403 <scons_output_command>ls src</scons_output_command>
404 <scons_output_command>scons -Q</scons_output_command>
405 <scons_output_command>ls build</scons_output_command>
411 <title>Using &VariantDir; With an &SConscript; File</title>
415 Even when using the &VariantDir; function,
416 it's much more natural to use it with
417 a subsidiary &SConscript; file.
419 <filename>src/SConscript</filename>
424 <scons_example name="example_builddir_sconscript">
425 <file name="SConstruct">
426 VariantDir('build', 'src')
427 SConscript('build/SConscript')
429 <file name="src/SConscript" printme="1">
431 env.Program('hello.c')
433 <file name="src/hello.c">
434 int main() { printf("Hello, world!\n"); }
440 Then our &SConstruct; file could look like:
444 <scons_example_file example="example_builddir_sconscript" name="SConstruct">
445 </scons_example_file>
449 Yielding the following output:
453 <scons_output example="example_builddir_sconscript">
454 <scons_output_command>ls src</scons_output_command>
455 <scons_output_command>scons -Q</scons_output_command>
456 <scons_output_command>ls build</scons_output_command>
461 Notice that this is completely equivalent
462 to the use of &SConscript; that we
463 learned about in the previous section.
470 <title>Using &Glob; with &VariantDir;</title>
474 The &Glob; file name pattern matching function
475 works just as usual when using &VariantDir;.
477 <filename>src/SConscript</filename>
482 <scons_example name="example_glob_builddir_sconscript">
483 <file name="SConstruct">
484 VariantDir('build', 'src')
485 SConscript('build/SConscript')
487 <file name="src/SConscript" printme="1">
489 env.Program('hello', Glob('*.c'))
491 <file name="src/f1.c">
493 int main() { printf(f2()); }
495 <file name="src/f2.c">
496 const char * f2() { return("Hello, world!\n"); }
498 <file name="src/f2.h">
505 Then with the same &SConstruct; file as in the previous section,
506 and source files <filename>f1.c</filename>
507 and <filename>f2.c</filename> in src,
508 we would see the following output:
512 <scons_output example="example_glob_builddir_sconscript">
513 <scons_output_command>ls src</scons_output_command>
514 <scons_output_command>scons -Q</scons_output_command>
515 <scons_output_command>ls build</scons_output_command>
520 The &Glob; function returns Nodes in the
521 <filename>build/</filename> tree, as you'd expect.
530 <title>Why You'd Want to Call &VariantDir; Instead of &SConscript;</title>
534 XXX why call VariantDir() instead of SConscript(variant_dir=)