3 Copyright (c) 2001, 2002, 2003 Steven Knight
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.
26 <section id="sect-principles">
27 <title>General Principles</title>
30 <title>Keyword arguments</title>
34 All methods and functions in this API will support the use of keyword
35 arguments in calls, for the sake of explicitness and readability.
36 For brevity in the hands of experts, most methods and functions
37 will also support positional arguments for their most-commonly-used
38 arguments. As an explicit example, the following two lines will each
39 arrange for an executable program named <filename>foo</filename> (or
40 <filename>foo.exe</filename> on a Win32 system) to be compiled from
41 the <filename>foo.c</filename> source file:
46 env.Program(target = 'foo', source = 'foo.c')
48 env.Program('foo', 'foo.c')
54 <title>Internal object representation</title>
58 All methods and functions use internal (Python) objects that
59 represent the external objects (files, for example) for which they
60 perform dependency analysis.
66 All methods and functions in this API that accept an external object
67 as an argument will accept <emphasis>either</emphasis> a string
68 description or an object reference. For example, the two following
69 two-line examples are equivalent:
74 env.Object(target = 'foo.o', source = 'foo.c')
75 env.Program(target = 'foo', 'foo.o') # builds foo from foo.o
77 foo_obj = env.Object(target = 'foo.o', source = 'foo.c')
78 env.Program(target = 'foo', foo_obj) # builds foo from foo.o
87 <section id="sect-envs">
88 <title>&ConsEnvs</title>
92 A &consenv; is the basic means by which a software system interacts
93 with the &SCons; Python API to control a build process.
99 A &consenv; is an object with associated methods for generating target
100 files of various types (&Builder; objects), other associated object
101 methods for automatically determining dependencies from the contents
102 of various types of source files (&Scanner; objects), and a dictionary
103 of values used by these methods.
109 Passing no arguments to the &Environment; instantiation creates a
110 &consenv; with default values for the current platform:
119 <title>&Consvars;</title>
123 A &consenv; has an associated dictionary of &consvars; that control how
124 the build is performed. By default, the &Environment; method creates
125 a &consenv; with values that make most software build "out of the box"
126 on the host system. These default values will be generated at the
127 time &SCons; is installed using functionality similar to that provided
131 It would be nice if we could avoid re-inventing the wheel here by
132 using some other Python-based tool &Autoconf replacement--like what
133 was supposed to come out of the Software Carpentry configuration
134 tool contest. It will probably be most efficient to roll our own
135 logic initially and convert if something better does come along.
138 At a minimum, there will be pre-configured sets of default values
139 that will provide reasonable defaults for UNIX and Windows NT.
145 The default &consenv; values may be overridden when a new &consenv; is
146 created by specifying keyword arguments:
151 env = Environment(CC = 'gcc',
153 CPPPATH = ['.', 'src', '/usr/include'],
154 LIBPATH = ['/usr/lib', '.'])
160 <title>Fetching &consvars;</title>
164 A copy of the dictionary of &consvars; can be returned using
165 the &Dictionary; method:
171 dict = env.Dictionary()
176 If any arguments are supplied, then just the corresponding value(s)
182 ccflags = env.Dictionary('CCFLAGS')
183 cc, ld = env.Dictionary('CC', 'LD')
189 <title>Copying a &consenv;</title>
193 A method exists to return a copy of an existing environment, with
194 any overridden values specified as keyword arguments to the method:
200 debug = env.Copy(CCFLAGS = '-g')
206 <title>Multiple &consenvs;</title>
210 Different external objects often require different build
211 characteristics. Multiple &consenvs; may be defined, each with
217 env = Environment(CCFLAGS = '')
218 debug = Environment(CCFLAGS = '-g')
219 env.Make(target = 'hello', source = 'hello.c')
220 debug.Make(target = 'hello-debug', source = 'hello.c')
225 Dictionaries of values from multiple &consenvs; may be passed to the
226 &Environment; instantiation or the &Copy; method, in which case the
227 last-specified dictionary value wins:
232 env1 = Environment(CCFLAGS = '-O', LDFLAGS = '-d')
233 env2 = Environment(CCFLAGS = '-g')
234 new = Environment(env1.Dictionary(), env2.Dictionary())
239 The <varname>new</varname> environment in the above example retains
240 <literal>LDFLAGS = '-d'</literal> from the <varname>env1</varname>
241 environment, and <literal>CCFLAGS = '-g'</literal> from the
242 <varname>env2</varname> environment.
250 OS environment variables
251 compilers and options,
252 aliases for commands,
255 environment overrides a la Cons
259 cross compilation via selection of tool+options
261 paths for header files (specify alternate path)
263 accomodate smart compilers that can tell you
264 "I know how to turn .c or .ccp into .o",
265 "I know how to turn .f into .o"
272 <title>Variable substitution</title>
276 Within a construction command, any variable from the &consenv; may
277 be interpolated by prefixing the name of the construction with
283 MyBuilder = Builder(command = "$XX $XXFLAGS -c $_INPUTS -o $target")
285 env.Command(targets = 'bar.out', sources = 'bar.in',
286 command = "sed '1d' < $source > $target")
291 Variable substitution is recursive: the command line is expanded
292 until no more substitutions can be made.
298 Variable names following the <symbol>$</symbol> may be enclosed in
299 braces. This can be used to concatenate an interpolated value with an
300 alphanumeric character:
305 VerboseBuilder = Builder(command = "$XX -${XXFLAGS}v > $target")
310 The variable within braces may contain a pair of parentheses
311 after a Python function name to be evaluated (for example,
312 <literal>${map()}</literal>). &SCons; will interpolate the return
313 value from the function (presumably a string):
318 env = Environment(FUNC = myfunc)
319 env.Command(target = 'foo.out', source = 'foo.in',
320 command = "${FUNC($<)}")
325 If a referenced variable is not defined in the &consenv;,
326 the null string is interpolated.
332 The following special variables can also be used:
339 <term><literal>$targets</literal></term>
343 All target file names. If multiple targets are specified in an
344 array, <literal>$targets</literal> expands to the entire list of
345 targets, separated by a single space.
351 Individual targets from a list may be extracted by enclosing
352 the <literal>targets</literal> keyword in braces and using the
353 appropriate Python array index or slice:
358 ${targets[0]} # expands to the first target
360 ${targets[1:]} # expands to all but the first target
362 ${targets[1:-1]} # expands to all but the first and last targets
369 <term><literal>$target</literal></term>
373 A synonym for <literal>${targets[0]}</literal>, the first target
381 <term><literal>$sources</literal></term>
385 All input file names. Any input file names that
386 are used anywhere else on the current command
387 line (via <literal>${sources[0]}</literal>,
388 <literal>${sources{[1]}</literal>, etc.) are removed from the
399 Any of the above special variables may be enclosed in braces and
400 followed immediately by one of the following attributes to select just
401 a portion of the expanded path name:
408 <term><literal>.base</literal></term>
412 Basename: the directory plus the file name, minus any file suffix.
419 <term><literal>.dir</literal></term>
423 The directory in which the file lives. This is a relative path,
431 <term><literal>.file</literal></term>
435 The file name, minus any directory portion.
442 <term><literal>.suffix</literal></term>
446 The file name suffix (that is, the right-most dot in the file name,
447 and all characters to the right of that).
454 <term><literal>.filebase</literal></term>
458 The file name (no directory portion), minus any file suffix.
465 <term><literal>.abspath</literal></term>
469 The absolute path to the file.
483 <section id="sect-builders">
484 <title>&Builder; Objects</title>
488 By default, &SCons; supplies (and uses) a number of pre-defined
498 <entry>&Object;</entry>
499 <entry>compile or assemble an object file</entry>
503 <entry>&Library;</entry>
504 <entry>archive files into a library</entry>
508 <entry>&SharedLibrary;</entry>
509 <entry>archive files into a shared library</entry>
513 <entry>&Program;</entry>
514 <entry>link objects and/or libraries into an executable</entry>
518 <entry>&MakeBuilder;</entry>
519 <entry>build according to file suffixes; see below</entry>
527 &Library; and &SharedLibrary; have nearly identical
528 semantics, just different
529 tools and &consenvs (paths, etc.) that they use.
530 In other words, you can construct a shared library
531 using just the &Library; &Builder; object
532 with a different environment.
533 I think that's a better way to do it.
539 A &consenv; can be explicitly initialized with associated &Builder;
540 objects that will be bound to the &consenv; object:
545 env = Environment(BUILDERS = ['Object', 'Program'])
550 &Builder; objects bound to a &consenv; can be called directly as
551 methods. When invoked, a &Builder; object returns a (list of) objects
557 obj = env.Object(target ='hello.o', source = 'hello.c')
558 lib = env.Library(target ='libfoo.a',
559 source = ['aaa.c', 'bbb.c'])
560 slib = env.SharedLibrary(target ='libbar.so',
561 source = ['xxx.c', 'yyy.c'])
562 prog = env.Program(target ='hello',
563 source = ['hello.o', 'libfoo.a', 'libbar.so'])
567 <title>Specifying multiple inputs</title>
571 Multiple input files that go into creating a target file may be passed
572 in as a single string, with the individual file names separated by
578 env.Library(target = 'foo.a', source = 'aaa.c bbb.c ccc.c')
579 env.Object(target = 'yyy.o', source = 'yyy.c')
580 env.Program(target = 'bar', source = 'xxx.c yyy.o foo.a')
585 Alternatively, multiple input files that go into creating a target
586 file may be passed in as an array. This allows input files to be
587 specified using their object representation:
592 env.Library(target = 'foo.a', source = ['aaa.c', 'bbb.c', 'ccc.c'])
593 yyy_obj = env.Object(target = 'yyy.o', source = 'yyy.c')
594 env.Program(target = 'bar', source = ['xxx.c', yyy_obj, 'foo.a'])
599 Individual string elements within an array of input files are
600 <emphasis>not</emphasis> further split into white-space separated
601 file names. This allows file names that contain white space to
602 be specified by putting the value into an array:
605 env.Program(target = 'foo', source = ['an input file.c'])
613 <title>Specifying multiple targets</title>
617 Conversely, the generated target may be a string listing multiple
618 files separated by white space:
623 env.Object(target = 'grammar.o y.tab.h', source = 'grammar.y')
628 An array of multiple target files can be used to mix string and object
629 representations, or to accomodate file names that contain white space:
634 env.Program(target = ['my program'], source = 'input.c')
640 <title>File prefixes and suffixes</title>
644 For portability, if the target file name does not already have an
645 appropriate file prefix or suffix, the &Builder; objects will
646 append one appropriate for the file type on the current system:
651 # builds 'hello.o' on UNIX, 'hello.obj' on Windows NT:
652 obj = env.Object(target ='hello', source = 'hello.c')
654 # builds 'libfoo.a' on UNIX, 'foo.lib' on Windows NT:
655 lib = env.Library(target ='foo', source = ['aaa.c', 'bbb.c'])
657 # builds 'libbar.so' on UNIX, 'bar.dll' on Windows NT:
658 slib = env.SharedLibrary(target ='bar', source = ['xxx.c', 'yyy.c'])
660 # builds 'hello' on UNIX, 'hello.exe' on Windows NT:
661 prog = env.Program(target ='hello',
662 source = ['hello.o', 'libfoo.a', 'libbar.so'])
668 <title>&Builder; object exceptions</title>
672 &Builder; objects raise the following exceptions on error:
675 LIST THESE ONCE WE FIGURE OUT WHAT THEY ARE FROM CODING THEM.
682 <title>User-defined &Builder; objects</title>
686 Users can define additional &Builder; objects for specific external
687 object types unknown to &SCons;. A &Builder; object may build its
688 target by executing an external command:
693 WebPage = Builder(command = 'htmlgen $HTMLGENFLAGS $sources > $target',
700 Alternatively, a &Builder; object may also build its target by
701 executing a Python function:
707 # [code to update the object]
710 OtherBuilder1 = Builder(function = update,
711 src_suffix = ['.in', '.input'])
716 An optional argument to pass to the function may be specified:
721 def update_arg(dest, arg):
722 # [code to update the object]
725 OtherBuilder2 = Builder(function = update_arg,
726 function_arg = 'xyzzy',
727 src_suffix = ['.in', '.input'])
732 Both an external command and an internal function may be specified,
733 in which case the function will be called to build the object first,
734 followed by the command line.
739 NEED AN EXAMPLE HERE.
744 User-defined &Builder; objects can be used like the default &Builder;
745 objects to initialize &consenvs;.
750 WebPage = Builder(command = 'htmlgen $HTMLGENFLAGS $sources > $target',
753 env = Environment(BUILDERS = ['WebPage'])
754 env.WebPage(target = 'foo.html', source = 'foo.in')
755 # Builds 'bar.html' on UNIX, 'bar.htm' on Windows NT:
756 env.WebPage(target = 'bar', source = 'bar.in')
761 The command-line specification can interpolate variables from the
762 &consenv;; see "Variable substitution," above.
768 A &Builder; object may optionally be initialized with a list of:
776 the prefix of the target file (e.g., 'lib' for libraries)
784 the suffix of the target file (e.g., '.a' for libraries)
792 the expected suffixes of the input files
793 (e.g., '.o' for object files)
801 These arguments are used in automatic
802 dependency analysis and to generate output file names that don't
803 have suffixes supplied explicitly.
809 <title>Copying &Builder; Objects</title>
813 A &Copy; method exists to return a copy of an existing &Builder;
814 object, with any overridden values specified as keyword arguments to
820 build = Builder(function = my_build)
821 build_out = build.Copy(suffix = '.out')
826 Typically, &Builder; objects will be supplied by a tool-master or
827 administrator through a shared &consenv;.
833 <title>Special-purpose build rules</title>
837 A pre-defined &Command; builder exists to associate a target file with
838 a specific command or list of commands for building the file:
843 env.Command(target = 'foo.out', source =
844 command = 'foo.in', "foo.process $sources > $target")
846 commands = [ "bar.process -o .tmpfile $sources",
847 "mv .tmpfile $target" ]
848 env.Command(target = 'bar.out', source = 'bar.in', command = commands)
852 This is useful when it's too cumbersome to create a &Builder;
853 object just to build a single file in a special way.
859 <title>The &MakeBuilder; &Builder;</title>
863 A pre-defined &Builder; object named &MakeBuilder; exists to make
864 simple builds as easy as possible for users, at the expense of
865 sacrificing some build portability.
871 The following minimal example builds the 'hello' program from the
872 'hello.c' source file:
877 Environment().Make('hello', 'hello.c')
882 Users of the &MakeBuilder; &Builder; object are not required to
883 understand intermediate steps involved in generating a file--for
884 example, the distinction between compiling source code into an object
885 file, and then linking object files into an executable. The details
886 of intermediate steps are handled by the invoked method. Users that
887 need to, however, can specify intermediate steps explicitly:
893 env.Make(target = 'hello.o', source = 'hello.c')
894 env.Make(target = 'hello', source = 'hello.o')
899 The &MakeBuilder; method understands the file suffixes specified and
900 "does the right thing" to generate the target object and program
901 files, respectively. It does this by examining the specified output
902 suffixes for the &Builder; objects bound to the environment.
908 Because file name suffixes in the target and source file names
909 must be specified, the &MakeBuilder; method can't be used
910 portably across operating systems. In other words, for the
911 example above, the &MakeBuilder; builder will not generate
912 <filename>hello.exe</filename> on Windows NT.
919 <title>&Builder; maps</title>
922 Do we even need this anymore?
923 Now that the individual builders
924 have specified <literal>suffix</literal>
925 and <literal>src_suffix</literal> values,
926 all of the information we need to support
927 the &MakeBuilder; builder is right there in the environment.
928 I think this is a holdover from before I
929 added the <literal>suffix</literal> arguments.
930 If you want &MakeBuilder; to do something different,
931 you set it up with another environment...
936 The <function>env.Make</function> method "does the right thing" to
937 build different file types because it uses a dictionary from the
938 &consenv; that maps file suffixes to the appropriate &Builder; object.
939 This &BUILDERMAP; can be initialized at instantiation:
944 env = Environment(BUILDERMAP = {
954 With the &BUILDERMAP; properly initialized, the
955 <function>env.Make</function> method can be used to build additional
961 env.Make(target = 'index.html', source = 'index.input')
966 &Builder; objects referenced in the &BUILDERMAP; do not need to be
967 listed separately in the &BUILDERS; variable. The &consenv; will
968 bind the union of the &Builder; objects listed in both variables.
974 YYY support scanners which detect files which haven't been generated yet
984 <section id="sect-deps">
985 <title>Dependencies</title>
988 <title>Automatic dependencies</title>
992 By default, &SCons; assumes that a target file has <literal>automatic
993 dependencies</literal> on the:
1000 <member>tool used to build the target file</member>
1002 <member>contents of the input files</member>
1004 <member>command line used to build the target file</member>
1011 If any of these changes, the target file will be rebuilt.
1017 <title>Implicit dependencies</title>
1021 Additionally, &SCons; can scan the contents of files for
1022 <literal>implicit dependencies</literal> on other files. For
1023 example, &SCons; will scan the contents of a <filename>.c</filename>
1024 file and determine that any object created from it is
1025 dependent on any <filename>.h</filename> files specified via
1026 <literal>#include</literal>. &SCons;, therefore, "does the right
1027 thing" without needing to have these dependencies listed explicitly:
1034 env.Program('hello', 'hello.c')
1036 #include "hello_string.h"
1039 printf("%s\n", STRING);
1041 % cat > hello_string.h
1042 #define STRING "Hello, world!\n"
1044 gcc -c hello.c -o hello.o
1045 gcc -o hello hello.c
1048 % cat > hello_string.h
1049 #define STRING "Hello, world, hello!\n"
1051 gcc -c hello.c -o hello.o
1052 gcc -o hello hello.c
1054 Hello, world, hello!
1061 <title>Ignoring dependencies</title>
1065 Undesirable <literal>automatic dependencies</literal> or
1066 <literal>implicit dependencies</literal> may be ignored:
1071 env.Program(target = 'bar', source = 'bar.c')
1072 env.Ignore('bar', '/usr/bin/gcc', 'version.h')
1077 In the above example, the <filename>bar</filename> program will not
1078 be rebuilt if the <filename>/usr/bin/gcc</filename> compiler or the
1079 <filename>version.h</filename> file change.
1085 <title>Explicit dependencies</title>
1089 Dependencies that are unknown to &SCons; may be specified explicitly
1090 in an &SCons; configuration file:
1095 env.Dependency(target = 'output1', dependency = 'input_1 input_2')
1096 env.Dependency(target = 'output2', dependency = ['input_1', 'input_2'])
1097 env.Dependency(target = 'output3', dependency = ['white space input'])
1099 env.Dependency(target = 'output_a output_b', dependency = 'input_3')
1100 env.Dependency(target = ['output_c', 'output_d'], dependency = 'input_4')
1101 env.Dependency(target = ['white space output'], dependency = 'input_5')
1106 Just like the <literal>target</literal> keyword argument, the
1107 <literal>dependency</literal> keyword argument may be specified as a
1108 string of white-space separated file names, or as an array.
1114 A dependency on an &SCons; configuration file itself may be specified
1115 explicitly to force a rebuild whenever the configuration file changes:
1120 env.Dependency(target = 'archive.tar.gz', dependency = 'SConstruct')
1129 <section id="sect-scanners">
1130 <title>&Scanner; Objects</title>
1134 Analagous to the previously-described &Builder; objects, &SCons;
1135 supplies (and uses) &Scanner; objects to search the contents of
1136 a file for implicit dependency files:
1145 <entry>CScan</entry>
1146 <entry>scan .{c,C,cc,cxx,cpp} files for #include dependencies</entry>
1155 A &consenv; can be explicitly initialized with
1156 associated &Scanner; objects:
1161 env = Environment(SCANNERS = ['CScan', 'M4Scan'])
1166 &Scanner; objects bound to a &consenv; can be
1167 associated directly with specified files:
1172 env.CScan('foo.c', 'bar.c')
1173 env.M4Scan('input.m4')
1177 <title>User-defined &Scanner; objects</title>
1181 A user may define a &Scanner; object to scan a type of file for
1182 implicit dependencies:
1187 def scanner1(file_contents):
1188 # search for dependencies
1189 return dependency_list
1191 FirstScan = Scanner(function = scanner1)
1196 The scanner function must return a list of dependencies that its finds
1197 based on analyzing the file contents it is passed as an argument.
1203 The scanner function, when invoked, will be passed the calling
1204 environment. The scanner function can use &consenvs; from the passed
1205 environment to affect how it performs its dependency scan--the
1206 canonical example being to use some sort of search-path construction
1207 variable to look for dependency files in other directories:
1212 def scanner2(file_contents, env):
1213 path = env.{'SCANNERPATH'} # XXX
1214 # search for dependencies using 'path'
1215 return dependency_list
1217 SecondScan = Scanner(function = scanner2)
1222 The user may specify an additional argument when the &Scanner; object
1223 is created. When the scanner is invoked, the additional argument
1224 will be passed to the scanner funciton, which can be used in any way
1225 the scanner function sees fit:
1230 def scanner3(file_contents, env, arg):
1231 # skip 'arg' lines, then search for dependencies
1232 return dependency_list
1234 Skip_3_Lines_Scan = Scanner(function = scanner2, argument = 3)
1235 Skip_6_Lines_Scan = Scanner(function = scanner2, argument = 6)
1241 <title>Copying &Scanner; Objects</title>
1245 A method exists to return a copy of an existing &Scanner; object,
1246 with any overridden values specified as keyword arguments to the
1252 scan = Scanner(function = my_scan)
1253 scan_path = scan.Copy(path = '%SCANNERPATH')
1258 Typically, &Scanner; objects will be supplied by a tool-master or
1259 administrator through a shared &consenv;.
1265 <title>&Scanner; maps</title>
1268 If the &BUILDERMAP; proves unnecessary,
1269 we could/should get rid of this one, too,
1270 by adding a parallel <literal>src_suffix</literal>
1271 argument to the &Scanner; factory...
1277 Each &consenv; has a &SCANNERMAP;, a dictionary that associates
1278 different file suffixes with a scanner object that can be used to
1279 generate a list of dependencies from the contents of that file. This
1280 &SCANNERMAP; can be initialized at instantiation:
1285 env = Environment(SCANNERMAP = {
1294 &Scanner; objects referenced in the &SCANNERMAP; do not need to
1295 be listed separately in the &SCANNERS; variable. The &consenv;
1296 will bind the union of the &Scanner; objects listed
1307 <section id="sect-targets">
1308 <title>Targets</title>
1312 The methods in the build engine API described so far merely
1313 establish associations that describe file dependencies, how a
1314 file should be scanned, etc. Since the real point is to actually
1315 <emphasis>build</emphasis> files, &SCons; also has methods that
1316 actually direct the build engine to build, or otherwise manipulate,
1322 <title>Building targets</title>
1325 One or more targets may be built as follows:
1330 env.Build(target = ['foo', 'bar'])
1335 Note that specifying a directory (or other collective object) will
1336 cause all subsidiary/dependent objects to be built as well:
1341 env.Build(target = '.')
1343 env.Build(target = 'builddir')
1348 By default, &SCons; explicitly removes a target file before
1349 invoking the underlying function or command(s) to build it.
1355 <title>Removing targets</title>
1359 A "cleanup" operation of removing generated (target) files is
1360 performed as follows:
1365 env.Clean(target = ['foo', 'bar'])
1370 Like the &Build; method, the &Clean; method may be passed a
1371 directory or other collective object, in which case the subsidiary
1372 target objects under the directory will be removed:
1377 env.Clean(target = '.')
1379 env.Clean(target = 'builddir')
1384 (The directories themselves are not removed.)
1390 <title>Suppressing cleanup removal of build-targets</title>
1394 By default, &SCons; explicitly removes all build-targets
1395 when invoked to perform "cleanup". Files that should not be
1396 removed during "cleanup" can be specified via the
1402 env.Library(target = 'libfoo.a', source = ['aaa.c', 'bbb.c', 'ccc.c'])
1403 env.NoClean('libfoo.a')
1408 The NoClean operation has precedence over the Clean operation.
1409 A target that is specified as both Clean and NoClean, will not
1410 be removed during a clean.
1412 In the following example, target 'foo' will not be removed
1416 env.Clean(target = 'foo')
1426 <title>Suppressing build-target removal</title>
1430 As mentioned, by default, &SCons; explicitly removes a target
1431 file before invoking the underlying function or command(s) to build
1432 it. Files that should not be removed before rebuilding can be
1433 specified via the &Precious; method:
1438 env.Library(target = 'libfoo.a', source = ['aaa.c', 'bbb.c', 'ccc.c'])
1439 env.Precious('libfoo.a')
1445 <title>Default targets</title>
1449 The user may specify default targets that will be built if there are no
1450 targets supplied on the command line:
1455 env.Default('install', 'src')
1460 Multiple calls to the &Default; method (typically one per &SConscript;
1461 file) append their arguments to the list of default targets.
1467 <title>File installation</title>
1471 Files may be installed in a destination directory:
1476 env.Install('/usr/bin', 'program1', 'program2')
1481 Files may be renamed on installation:
1486 env.InstallAs('/usr/bin/xyzzy', 'xyzzy.in')
1491 Multiple files may be renamed on installation by specifying
1492 equal-length lists of target and source files:
1497 env.InstallAs(['/usr/bin/foo', '/usr/bin/bar'],
1498 ['foo.in', 'bar.in'])
1504 <title>Target aliases</title>
1508 In order to provide convenient "shortcut" target names that expand to
1509 a specified list of targets, aliases may be established:
1514 env.Alias(alias = 'install',
1515 targets = ['/sbin', '/usr/lib', '/usr/share/man'])
1520 In this example, specifying a target of <literal>install</literal>
1521 will cause all the files in the associated directories to be built
1522 (that is, installed).
1528 An &Alias; may include one or more other &Aliases; in its list:
1533 env.Alias(alias = 'libraries', targets = ['lib'])
1534 env.Alias(alias = 'programs', targets = ['libraries', 'src'])
1543 <section id="sect-custom">
1544 <title>Customizing output</title>
1547 Take this whole section with a grain of salt.
1548 I whipped it up without a great deal of thought
1549 to try to add a "competitive advantage"
1550 for the second round of the Software Carpentry contest.
1551 In particular, hard-coding the
1552 analysis points and the keywords that specify them
1554 but I can't think of another way it would be
1556 I dunno, maybe this is fine as it is...
1561 The &SCons; API supports the ability to customize, redirect, or
1562 suppress its printed output through user-defined functions.
1563 &SCons; has several pre-defined points in its build process at
1564 which it calls a function to (potentially) print output. User-defined
1565 functions can be specified for these call-back points when &Build;
1566 or &Clean;is invoked:
1571 env.Build(target = '.',
1572 on_analysis = dump_dependency,
1573 pre_update = my_print_command,
1574 post_update = my_error_handler)
1575 on_error = my_error_handler)
1580 The specific call-back points are:
1587 <term><literal>on_analysis</literal></term>
1591 Called for every object, immediately after the object has been
1592 analyzed to see if it's out-of-date. Typically used to print a
1593 trace of considered objects for debugging of unexpected dependencies.
1600 <term><literal>pre_update</literal></term>
1604 Called for every object that has been determined to be out-of-date
1605 before its update function or command is executed. Typically used
1606 to print the command being called to update a target.
1613 <term><literal>post_update</literal></term>
1617 Called for every object after its update function or command has
1618 been executed. Typically used to report that a top-level specified
1619 target is up-to-date or was not remade.
1626 <term><literal>on_error</literal></term>
1630 Called for every error returned by an update function or command.
1631 Typically used to report errors with some string that will be
1632 identifiable to build-analysis tools.
1642 Functions for each of these call-back points all take the same
1648 my_dump_dependency(target, level, status, update, dependencies)
1653 where the arguments are:
1660 <term><literal>target</literal></term>
1664 The target object being considered.
1671 <term><literal>level</literal></term>
1675 Specifies how many levels the dependency analysis has
1676 recursed in order to consider the <literal>target</literal>.
1677 A value of <literal>0</literal> specifies a top-level
1678 <literal>target</literal> (that is, one passed to the
1679 &Build; or &Clean; method). Objects which a top-level
1680 <literal>target</literal> is directly dependent upon have a
1681 <literal>level</literal> of <1>, their direct dependencies have a
1682 <literal>level</literal> of <2>, etc. Typically used to indent
1683 output to reflect the recursive levels.
1690 <term><literal>status</literal></term>
1694 A string specifying the current status of the target
1695 (<literal>"unknown"</literal>, <literal>"built"</literal>,
1696 <literal>"error"</literal>, <literal>"analyzed"</literal>, etc.). A
1697 complete list will be enumerated and described during implementation.
1704 <term><literal>update</literal></term>
1708 The command line or function name that will be (or has been) executed
1709 to update the <literal>target</literal>.
1716 <term><literal>dependencies</literal></term>
1720 A list of direct dependencies of the target.
1732 <section id="separate">
1733 <title>Separate source and build trees</title>
1736 I've never liked Cons' use of the name <literal>Link</literal>
1737 for this functionality,
1738 mainly because the term is overloaded
1739 with linking object files into an executable.
1740 Yet I've never come up with anything better.
1745 Also, I made this an &Environment; method because
1746 it logically belongs in the API reference
1747 (the build engine needs to know about it),
1748 and I thought it was clean to have
1749 everything in the build-engine API
1750 be called through an &Environment; object.
1751 But <literal>&Link</literal> isn't really
1752 associated with a specific environment
1753 (the &Cons; classic implementation just
1754 leaves it as a bare function call),
1755 so maybe we should just follow that example
1756 and not call it through an environment...
1761 &SCons; allows target files to be built completely separately from
1762 the source files by "linking" a build directory to an underlying
1768 env.Link('build', 'src')
1770 SConscript('build/SConscript')
1775 &SCons; will copy (or hard link) necessary files (including the
1776 &SConscript; file) into the build directory hierarchy. This allows the
1777 source directory to remain uncluttered by derived files.
1785 <section id="sect-variant">
1786 <title>Variant builds</title>
1790 The &Link; method may be used in conjunction with multiple
1791 &consenvs; to support variant builds. The following
1792 &SConstruct; and &SConscript; files would build separate debug and
1793 production versions of the same program side-by-side:
1800 env.Link('build/debug', 'src')
1801 env.Link('build/production', 'src')
1803 SConscript('build/debug/SConscript', Export(env))
1805 SConscript('build/production/SConscript', Export(env))
1806 % cat src/SConscript
1807 env = Environment(CCFLAGS = flags)
1808 env.Program('hello', 'hello.c')
1813 The following example would build the appropriate program for the current
1814 compilation platform, without having to clean any directories of object
1815 or executable files for other architectures:
1821 build_platform = os.path.join('build', sys.platform)
1822 Link(build_platform, 'src')
1823 SConscript(os.path.join(build_platform, 'SConscript'))
1824 % cat src/SConscript
1826 env.Program('hello', 'hello.c')
1833 <section id="sect-repositories">
1834 <title>Code repositories</title>
1837 Like &Link;, &Repository; and &Local; are part of the
1838 API reference, but not really tied to any specific environment.
1839 Is it better to be consistent about calling
1840 everything in the API through an environment,
1841 or to leave these independent so as
1842 not to complicate their calling interface?
1847 &SCons; may use files from one or more shared code repositories in order
1848 to build local copies of changed target files. A repository would
1849 typically be a central directory tree, maintained by an integrator,
1850 with known good libraries and executables.
1855 Repository('/home/source/1.1', '/home/source/1.0')
1860 Specified repositories will be searched in-order for any file
1861 (configuration file, input file, target file) that does not exist
1862 in the local directory tree. When building a local target file,
1863 &SCons; will rewrite path names in the build command to use the
1864 necessary repository files. This includes modifying lists of
1865 <option>-I</option> or <option>-L</option> flags to specify an
1866 appropriate set of include paths for dependency analysis.
1871 &SCons; will modify the Python <varname>sys.path</varname> variable to
1872 reflect the addition of repositories to the search path, so that any
1873 imported modules or packages necessary for the build can be found in a
1874 repository, as well.
1879 If an up-to-date target file is found in a code repository, the file
1880 will not be rebuilt or copied locally. Files that must exist locally
1881 (for example, to run tests) may be specified:
1886 Local('program', 'libfoo.a')
1891 in which case &SCons; will copy or link an up-to-date copy of the
1892 file from the appropriate repository.
1900 <section id="sect-caching">
1901 <title>Derived-file caching</title>
1904 There should be extensions to this part of the API for
1905 auxiliary functions like cleaning the cache.
1910 &SCons; can maintain a cache directory of target files which may be
1911 shared among multiple builds. This reduces build times by allowing
1912 developers working on a project together to share common target
1918 Cache('/var/tmp/build.cache/i386')
1923 When a target file is generated, a copy is added to the cache.
1924 When generating a target file, if &SCons; determines that a file
1925 that has been built with the exact same dependencies already exists
1926 in the specified cache, &SCons; will copy the cached file rather
1927 than re-building the target.
1932 Command-line options exist to modify the &SCons; caching behavior
1933 for a specific build, including disabling caching, building
1934 dependencies in random order, and displaying commands as if cached
1943 <section id="sect-jobs">
1944 <title>Job management</title>
1947 This has been completely superseded by
1948 the more sophisticated &Task; manager
1949 that Anthony Roach has contributed.
1950 I need to write that up...
1955 A simple API exists to inform the Build Engine how many jobs may
1956 be run simultaneously: