1 .\" Copyright (c) 2001 Steven Knight
3 .\" Permission is hereby granted, free of charge, to any person obtaining
4 .\" a copy of this software and associated documentation files (the
5 .\" "Software"), to deal in the Software without restriction, including
6 .\" without limitation the rights to use, copy, modify, merge, publish,
7 .\" distribute, sublicense, and/or sell copies of the Software, and to
8 .\" permit persons to whom the Software is furnished to do so, subject to
9 .\" the following conditions:
11 .\" The above copyright notice and this permission notice shall be included
12 .\" in all copies or substantial portions of the Software.
14 .\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY
15 .\" KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
16 .\" WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
17 .\" NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
18 .\" LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
19 .\" OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
20 .\" WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
22 .\" __FILE__ __REVISION__ __DATE__ __DEVELOPER__
24 .\" ES - Example Start - indents and turns off line fill
29 .\" EE - Example End - ends intend and turns line fill back on
34 .TH SCONS 1 "December 2001"
36 scons \- software constructor
52 utility builds software (or other files) by determining which
53 component pieces must be rebuilt and executing the necessary commands to
58 searches for a file named
63 (in that order) in the current directory and reads its
64 configuration from the first file found. An alternate file name may be
67 option. If the specified file is not
68 in the local directory,
70 will internally change its working
71 directory (chdir) to the directory containing the file.
73 The configuration file specifies the files to be built, and
74 (optionally) the rules to build those files. Reasonable default
75 rules exist for building common software components (executable
76 programs, object files, libraries), so that for simple software
77 projects, only the target and input files need be specified.
80 can scan known input files automatically for dependency
81 information (for example, #include statements
82 in C or C++ files) and will rebuild dependent files appropriately
83 whenever any "included" input file changes.
86 ability to define new scanners for unknown input file types.
89 is normally executed in a top-level directory containing a
91 file, specifying the target or targets to be built as
92 command-line arguments. The command
98 will build all target files in or below the current directory
105 will build all target files in or below the root directory (i.e.,
106 all files). Specific targets may be supplied:
112 Targets may be omitted from the command line,
113 in which case the targets specified
114 in the configuration file(s) as
116 targets will be built:
122 Specifying "cleanup" targets in configuration files is not
125 flag removes all files
126 necessary to build the specified target:
132 to remove all target files, or:
135 scons -c build export
138 to remove target files under build and export.
140 A subset of a hierarchical tree may be built by
141 remaining at the top-level directory (where the
143 file lives) and specifying the subdirectory as the target to be
150 .\" or changing directory and invoking scons with the
152 .\" option, which traverses up the directory
153 .\" hierarchy until it finds the
155 .\" file, and then builds
156 .\" targets relatively to the current subdirectory:
164 supports building multiple targets in parallel via a
166 option that takes, as its argument, the number
167 of simultaneous tasks that may be spawned:
173 builds four targets in parallel, for example.
175 Values of variables to be passed to the configuration file(s)
176 may be specified on the command line:
182 These variables can be used in the configuration file(s) to modify
183 the build in any way.
186 .\" can maintain a cache of target (derived) files that can
187 .\" be shared between multiple builds. When caching is enabled in a
188 .\" configuration file, any target files built by
191 .\" to the cache. If an up-to-date target file is found in the cache, it
192 .\" will be retrieved from the cache instead of being rebuilt locally.
193 .\" Caching behavior may be disabled and controlled in other ways by the
194 .\" .BR --cache-force ,
195 .\" .BR --cache-disable ,
198 .\" command-line options. The
200 .\" option is useful whenever multiple builds may be
201 .\" trying to update the cache simultaneously.
206 supports the same command-line options as GNU
208 and many of those supported by
213 Ignored for compatibility with non-GNU versions of
217 -c, --clean, --remove
218 Clean up by removing all target files for which a construction
219 command is specified.
222 .\" --cache-disable, --no-cache
223 .\" Disable caching. Will neither retrieve files from cache nor flush
224 .\" files to cache. Has no effect if use of caching is not specified
225 .\" in a configuration file.
228 .\" --cache-force, --cache-populate
229 .\" Populate a cache by forcing any already-existing up-to-date
230 .\" target files to the cache, in addition to files built by this
231 .\" invocation. This is useful to populate a new cache with
232 .\" appropriate target files, or to make available in the cache
233 .\" any target files recently built with caching disabled via the
234 .\" .B --cache-disable
239 .\" When retrieving a target file from a cache, show the command
240 .\" that would have been executed to build the file. This produces
241 .\" consistent output for build logs, regardless of whether a target
242 .\" file was rebuilt or retrieved from cache.
245 .RI "-C" " directory" ", --directory=" directory
246 Change to the specified
248 before searching for the
253 file, or doing anything
256 options are interpreted
257 relative to the previous one, and the right-most
259 option wins. (This option is nearly
261 .BR "-f directory/SConstruct" ,
262 except that it will search for
267 in the specified directory.)
271 .\" Display dependencies while building target files. Useful for
272 .\" figuring out why a specific file is being rebuilt, as well as
273 .\" general debugging of the build process.
277 Print debugging information durring the build process.
279 specifies what type of of debugging information to print. Currently the
280 only supported type is
282 which causes the dependency tree to be printed after each top-level
286 -e, --environment-overrides
287 Variables from the execution environment override construction
288 variables from the configuration files.
291 .RI -f " file" ", --file=" file ", --makefile=" file ", --sconstruct=" file
294 as the initial configuration
297 is in another directory,
299 will change to that directory before building targets.
303 Print a local help message for this build, if one is defined in
304 the configuration file(s), plus a line that describes the
306 option for command-line option help. If no local help message
307 is defined, prints the standard help message about command-line
308 options. Exits after displaying the appropriate message.
312 Print the standard help message about command-line options and
317 Ignore all errors from commands executed to rebuild files.
320 .RI -I " directory" ", --include-dir=" directory
324 imported Python modules. If several
327 are used, the directories are searched in the order specified.
330 .RI -j " N" ", --jobs=" N
331 Specifies the number of jobs (commands) to run simultaneously.
332 If there is more than one
334 option, the last one is effective.
338 .\" is specified without an argument,
340 .\" will not limit the number of
341 .\" simultaneous jobs.
345 Continue as much as possible after an error. The target that
346 failed and those that depend on it will not be remade, but other
347 targets specified on the command line will still be processed.
350 .\" .RI -l " N" ", --load-average=" N ", --max-load=" N
351 .\" No new jobs (commands) will be started if
352 .\" there are other jobs running and the system load
353 .\" average is at least
355 .\" (a floating-point number).
359 .\" List derived files (targets, dependencies) that would be built,
360 .\" but do not build them.
361 .\" [XXX This can probably go away with the right
362 .\" combination of other options. Revisit this issue.]
366 .\" List derived files that would be built, with the actions
367 .\" (commands) that build them. Does not build the files.
368 .\" [XXX This can probably go away with the right
369 .\" combination of other options. Revisit this issue.]
373 .\" List derived files that would be built, plus where the file is
374 .\" defined (file name and line number). Does not build the files.
375 .\" [XXX This can probably go away with the right
376 .\" combination of other options. Revisit this issue.]
380 Ignored for compatibility with non-GNU versions of
384 -n, --just-print, --dry-run, --recon
385 No execute. Print the commands that would be executed to build
386 any out-of-date target files, but do not execute the commands.
389 .\" .RI -o " file" ", --old-file=" file ", --assume-old=" file
393 .\" not rebuild anything due to changes in the contents of
396 .\" .RI --override " file"
397 .\" Read values to override specific build environment variables
398 .\" from the specified
402 .\" Print the data base (construction environments,
403 .\" Builder and Scanner objects) that are defined
404 .\" after reading the configuration files.
405 .\" After printing, a normal build is performed
406 .\" as usual, as specified by other command-line options.
407 .\" This also prints version information
412 .\" To print the database without performing a build do:
420 .\" Do not run any commands, or print anything. Just return an exit
421 .\" status that is zero if the specified targets are already up to
422 .\" date, nonzero otherwise.
425 .\" -r, -R, --no-builtin-rules, --no-builtin-variables
426 .\" Clear the default construction variables. Construction
427 .\" environments that are created will be completely empty.
431 .\" Build dependencies in a random order. This is useful when
432 .\" building multiple trees simultaneously with caching enabled as a
433 .\" way to prevent multiple builds from simultaneously trying to build
434 .\" or retrieve the same target files.
437 -s, --silent, --quiet
438 Silent. Do not print commands that are executed to rebuild
442 -S, --no-keep-going, --stop
443 Ignored for compatibility with GNU
448 Ignored for compatibility with GNU
450 (Touching a file to make it
451 appear up-to-date is unnecessary when using
456 .\" Traverse up directories until an
460 .\" file is found, and use that
461 .\" as the top of the directory tree. Only targets at or below the
462 .\" current directory will be built.
468 version, copyright information,
469 list of authors, and any other relevant information.
473 -w, --print-directory
474 Print a message containing the working directory before and
475 after other processing.
479 Turn off -w, even if it was turned on implicitly.
482 .\" .RI --write-filenames= file
483 .\" Write all filenames considered into
487 .\" .RI -W " file" ", --what-if=" file ", --new-file=" file ", --assume-new=" file
488 .\" Pretend that the target
491 .\" modified. When used with the
494 .\" show you what would be rebuilt if you were to modify that file.
500 .\" --warn-undefined-variables
501 .\" Warn when an undefined variable is referenced.
504 .\" .RI -Y " repository" ", --repository=" repository
505 .\" Search the specified repository for any input and target
506 .\" files not found in the local directory hierarchy. Multiple
508 .\" options may specified, in which case the
509 .\" repositories are searched in the order specified.
511 .SH CONFIGURATION FILE REFERENCE
512 .SS Construction Environments
513 A construction environment is the basic means by which the configuration
514 files communicate build information to
516 A new construction environment is created using the
524 Build rules are specified by calling builder methods on a construction
525 environment. The arguments to the builder methods are target (a list of
526 target files) and source (a list of source files). If a string is given
527 for target or source, then
529 interprets it as a space delimited list
530 of files. The following are examples of calling a builder:
533 env.Program(target = 'bar', source = 'bar.c foo.c')
534 env.Program('bar', 'bar.c foo.c')
535 env.Program('bar', ['bar.c', 'foo.c'])
539 provides the following builders:
542 Builds an object file from one or more C/C++ source files. Source files
543 must have one of the following extensions: .c, .C, .cc, .cpp, .cxx, .c++, .C++.
544 The target object file prefix and suffix (if any) are automatically
548 env.Object(target = 'bar', source = 'bar.c')
552 Builds an executable given one or more object files or C/C++ source
553 files. If any C/C++ source files are given, then they will be automatically
554 compiled to object files. The executable prefix and suffix (if any) are
555 automatically added to the target. Example:
558 env.Program(target = 'bar', source = 'bar.c foo.o')
562 Builds a library given one or more object files or C/C++ source
563 files. If any C/C++ source files are given, then they will be automatically
564 compiled to object files. The library prefix and suffix (if any) are
565 automatically added to the target. Example:
568 env.Library(target = 'bar', source = 'bar.c foo.o')
572 Builds a C source file given a lex (.l) or yacc (.y) input file.
573 The hard-coded suffix .c is
574 automatically added to the target
575 if it is not already present. Example:
578 env.CFile(target = 'foo.c', source = 'foo.l') # builds foo.c
579 env.CFile(target = 'bar', source = 'bar.y') # builds bar.c
582 C/C++ source files are automatically scanned for dependencies by
584 so the dependencies do not need to be provided. In addition, all builder
585 targets automatically depend on their sources. An explicit dependency can
586 be specified using the
588 method of a construction environment (see below).
590 Additional Environment methods include:
593 .RI Command( target ", " source ", " commands )
594 Executes a specific command
595 (or list of commands)
596 to build a target file or files.
597 This is more convenient
598 than defining a separate Builder object
599 for a single special-case build.
602 env.Command('foo.out', 'foo.in',
603 "$FOO_BUILD < $SOURCES > $TARGET")
604 env.Command('bar.out', 'bar.in',
606 "$BAR_BUILD < $SOURCES > $TARGET"])
610 .RI Copy([ key = val ", ...])"
611 Return a separate copy of a construction environment.
612 If there are any keyword arguments specified,
613 they are added to the returned copy,
614 overwriting any existing values
619 env3 = env.Copy(CCFLAGS = '-g')
623 .RI Depends( target ", " dependency )
624 Specifies an explicit dependency;
625 the target file(s) will be rebuilt
626 whenever the dependency file(s) has changed.
627 This should only be necessary
628 for cases where the dependency
629 is not caught by a Scanner
633 env.Depends('foo', 'other-input-file-for-foo')
637 .RI Dictionary([ vars ])
638 Returns a dictionary object
639 containing copies of all of the
640 construction variables in the environment.
641 If there are any variable names specified,
642 only the specified construction
643 variables are returned in the dictionary.
646 dict = env.Dictionary()
647 cc_dict = env.Dictionary('CC', 'CCFLAGS', 'CCCOM')
651 .RI Install( dir ", " source )
652 Installs one or more files in a destination directory.
653 The file names remain the same.
656 env.Install(dir = '/usr/local/bin', source = 'foo bar')
660 .RI InstallAs( target ", " source )
661 Installs one or more files as specific file names,
662 allowing changing a file name as part of the
664 It is an error if the target and source
665 list different numbers of files.
668 env.InstallAs(target = '/usr/local/bin/foo',
669 source = 'foo_debug')
670 env.InstallAs(target = '../lib/libfoo.a ../lib/libbar.a',
671 source = 'libFOO.a libBAR.a')
675 .RI Update( key = val ", [...])"
676 Updates the contents of an environment
677 with the specified keyword arguments.
680 env.Update(CCFLAGS = '-g', FOO = 'foo.xxx')
683 .SS Construction Variables
685 A construction environment has an associated dictionary of construction
686 variables that are used by built-in or user-supplied build rules. A number
687 of useful construction variables are automatically defined by scons for
688 each supported platform, and additional construction variables can be defined
689 by the user. The following is a list of the automatically defined construction
693 The static library command.
696 General options passed to the static library command.
699 The command line used to generate a static library from object files.
702 A list of the available builders.
703 [CFile, Object, Program, Library] by default.
709 General options that are passed to the C compiler.
712 The command line used to compile a C source file to an object file.
715 The list of directories that the C preprocessor will search for include
716 directories. The C/C++ implicit dependency scanner will search these
717 directories for include files. Don't explicitly put include directory
718 arguments in CCFLAGS or CXXFLAGS because the result will be non-portable
719 and the directories will not be searched by the depedency scanner. Note:
720 directory names in CPPPATH will be looked-up relative to the SConscript
721 directory when they are used in a command. To force
723 to look-up a directory relative to the root of the source tree use #:
726 env = Environment(CPPPATH='#/include')
730 The directory look-up can also be forced using the
735 include = Dir('include')
736 env = Environment(CPPPATH=include)
743 General options that are passed to the C++ compiler.
746 The command line used to compile a C++ source file to an object file.
749 A dictionary of environment variables
750 to use when invoking commands.
751 Note that, by default,
755 propogate the environment in force when you
758 to the commands used to build target files.
759 This is so that builds will be guaranteed
760 repeatable regardless of the environment
761 variables set at the time
765 If you want to propogate your
766 environment variables
767 to the commands executed
768 to build target files,
769 you must do so explictly:
773 env = Environment(ENV = os.environ)
777 Note that you can choose only to propogate
778 certain environment variables.
782 environment variable,
785 uses the same utilities
786 as the invoking shell (or other process):
791 env = Environment(ENV = {'PATH' : os.environ['PATH']})
795 The prefix used to specify an include directory on the C compiler command
799 The suffix used to specify an include directory on the C compiler command
803 The lexical analyzer generator.
806 General options passed to the lexical analyzer generator.
809 The command line used to call the lexical analyzer generator
810 to generate a source file.
813 The prefix used to specify a library directory on the linker command line.
816 The suffix used to specify a library directory on the linker command line.
819 The prefix used to specify a library to link on the linker command line.
822 The suffix used to specify a library to link on the linker command line.
825 The prefix used for library file names.
828 The suffix used for library file names.
834 General options passed to the linker.
837 The command line used to link object files into an executable.
840 The prefix used for object file names.
843 The suffix used for object file names.
846 The prefix used for executable file names.
849 The suffix used for executable file names.
852 A list of the available implicit dependency scanners. [CScan] by default.
855 The parser generator.
858 General options passed to the parser generator.
861 The command line used to call the parser generator
862 to generate a source file.
865 Construction variables can be retrieved and set using the
867 method of the construction environment:
870 dict = env.Dictionary()
874 Construction variables can also be passed to the construction environment
878 env = Environment(CC="cc")
881 or when copying a construction environment using the
886 env2 = env.Copy(CC="cl.exe")
892 also provides various additional functions,
893 not associated with a construction environment,
894 that configuration files can use:
897 .RI BuildDir( build_dir ", " src_dir ", [" duplicate ])
898 This specifies a build directory to use for all derived files.
900 specifies the build directory to be used for all derived files that would
901 normally be built under
903 Multiple build directories can be set up for multiple build variants, for
906 will link or copy (depending on the platform) all the source files into the
909 is set to 1 (the default). If
913 will not copy or link any source files, which may cause build problems in
914 certain situations (e.g. C source files that are generated by the
917 is usually safe, and is always more efficient than
921 .RI Default( targets )
922 This specifies a list of default targets. Default targets will be built by
924 if no explicit targets are given on the comamnd line. Multiple targets can
925 be specified either as a space delimited string of target file names or as
927 Target names with white space may be be enclosed in an
928 array to prevent the string from being split into
931 will also accept the return value of any of the ccnstruction environment
936 Default('foo', 'bar', 'baz', ['file with whitespace'])
940 .RI Dir( name ", [" directory ])
941 This returns an object that represents a given directory
944 can be a relative or absolute path.
946 is an optional directory that will be used as the parent directory.
952 to export a list of variables from the current
953 configuration file to all other configuration files. The exported variables
954 are kept in a global collection, so subsequent exports
955 will over-write previous exports that have the same name.
956 Multiple variable names can be passed to
958 in a space delimited string or as seperate arguments. Example:
965 .RI File( name ", [" directory ])
966 This returns an object that represents a given file
969 can be a relative or absolute path.
971 is an optional directory that will be used as the parent directory.
975 This specifies help text to be printed if the
980 will exit after printing out the help text.
986 to import a list of variables into the current configuration file. This
987 will import variables that were exported with
993 Variables exported by
995 have precedence. Multiple variable names can be passed to
997 in a space delimited string or as seperate arguments. Example:
1007 what variable(s) to use as the return value(s) of the current configuration
1008 file. These variables will be returned to the "calling" configuration file
1009 as the return value(s) of
1011 Multiple variable names can be passed to
1013 in a space delimited string or as seperate arguments. Example:
1020 .RI SConscript( script ", [" exports ])
1025 as a configuration file. The optional
1027 argument provides a list of variable names to export to
1028 .IR script ". " exports
1029 can also be a space delimited string of variables names.
1033 function to import the variables. Any variables returned by
1037 will be returned by the call to
1042 SConscript('dir/SConscript')
1043 foo = SConscript('subdir/SConscript', "env")
1047 .RI SetCommandHandler( function )
1049 This registers a user
1052 for interpreting and executing command-line strings.
1053 The function must expect three arguments:
1056 def commandhandler(cmd, args, env):
1060 is the path to the command to be executed.
1062 is that arguments to the command.
1064 is a dictionary of the environment variables
1065 in which the command should be executed.
1070 can be extended by adding new builders to a construction
1071 environment using the
1073 function. Builder accepts the following
1077 The name of the builder. This will be the of the construction environment
1078 method used to create an instance of the builder.
1081 The command line string used to build the target from the source.
1083 can also be a dictionary
1084 mapping source file name suffixes to
1085 any combination of command line strings
1086 (if the builder should accept multiple source file extensions),
1089 (see the next section).
1092 The prefix that will be prepended to the target file name.
1095 The suffix that will be appended to the target file name.
1098 The expected source file name suffix.
1101 Specifies a builder to use when a source file name suffix does not match
1102 any of the suffixes of the builder. Using this argument produces a
1103 multi-stage builder.
1107 The Builder function will turn its
1109 keyword argument into an appropriate
1110 internal Action object.
1111 Occasionally, it may be more efficient
1112 to create an explicit Action object
1113 and use it to initialize multiple
1115 rather than let each separate Builder object
1116 create a separate Action.
1118 The Action method takes a single argument
1119 and returns an appropriate object for the action
1120 represented by the type of the argument:
1123 If the argument is already an Action object,
1124 the object is simply returned.
1127 If the argument is a string,
1128 a command-line Action is returned.
1131 Action('$CC -c -o $TARGET $SOURCES')
1135 If the argument is a Python function,
1136 a function Action is returned.
1137 The Python function takes three keyword arguments,
1139 (the name of the target file),
1141 (the name of the source file)
1144 (the construction environment
1145 used for building the target file).
1150 arguments may be lists of strings if there is
1151 more than one target file or source file.
1153 The function should return
1157 to indicate a successful build of the target file(s).
1158 The function may raise an exception
1159 or return a non-zero exit status
1160 to indicate an unsuccessful build.
1163 def build_it(target = None, source = None, env = None):
1164 # build the target from the source
1167 a = Action(build_it)
1171 If the argument is a list,
1172 then a list of Action objects is returned.
1173 An Action object is created as necessary
1174 for each element in the list.
1176 If the action argument is not one of the above,
1178 .SS Variable Substitution
1180 performs construction variable interpolation on the strings that make up
1181 the command line of builders before executing the command.
1182 Variables are introduced by a
1185 Besides construction variables, scons provides the following
1186 variables for each command execution:
1189 The file name of the target being built, or the file name of the first
1190 target if multiple targets are being built.
1193 The file names of all targets being built.
1196 The file names of the sources of the build command.
1198 For example, given the construction variable CC='cc', targets=['foo'], and
1199 sources=['foo.c', 'bar.c']:
1201 action='$CC -c -o $TARGET $SOURCES'
1203 would produce the command line:
1205 cc -c -o foo foo.c bar.c
1207 Variable names may be surrounded by curly braces ({})
1208 to separate the name from the trailing characters.
1209 Within the curly braces, a variable name may have
1210 a Python slice subscript appended to select one
1211 or more items from a list.
1212 In the previous example, the string:
1220 Additionally, a variable name may
1221 have the following special
1222 modifiers appended within the enclosing curly braces
1223 to modify the interpolated string:
1226 The base path of the file name,
1227 including the directory path
1228 but excluding any suffix.
1231 The name of the directory in which the file exists.
1235 minus any directory portion.
1238 Just the basename of the file,
1240 and minus the directory.
1243 Just the file suffix.
1246 For example, the specified target will
1247 expand as follows for the corresponding modifiers:
1250 $TARGET => sub/dir/file.x
1251 ${TARGET.base} => sub/dir/file
1252 ${TARGET.dir} => sub/dir
1253 ${TARGET.file} => file.x
1254 ${TARGET.filebase} => file
1255 ${TARGET.suffix} => .x
1258 .\" XXX document how to add user defined scanners.
1262 To help you get started using SCons,
1263 here is a brief overview of some common tasks:
1265 .SS Basic Compilation From a Single Source File
1269 env.Program(target = 'foo', source = 'foo.c')
1272 .SS Basic Compilation From Multiple Source Files
1276 env.Program(target = 'foo', source = 'f1.c f2.c f3.c')
1279 .SS Setting a Compilation Flag
1282 env = Environment(CCFLAGS = '-g')
1283 env.Program(target = 'foo', source = 'foo.c')
1286 .SS Search The Local Directory For .h Files
1290 need to specify -I options by hand.
1291 SCons will construct the right -I options from CPPPATH.
1294 env = Environment(CPPPATH = ['.'])
1295 env.Program(target = 'foo', source = 'foo.c')
1298 .SS Search Multiple Directories For .h Files
1301 env = Environment(CPPPATH = ['include1', 'include2'])
1302 env.Program(target = 'foo', source = 'foo.c')
1305 .SS Building a Library
1309 env.Library(target = 'mylib', source = 'l1.c l2.c')
1312 .SS Linking a Local Library Into a Program
1315 env = Environment(LIBS = 'mylib', LIBPATH = ['.'])
1316 env.Library(target = 'mylib', source = 'l1.c l2.c')
1317 env.Program(target = 'prog', source = 'p1.c p2.c')
1320 .SS Defining Your Own Builder Object
1324 specify a "name" keyword argument for the builder,
1325 as that becomes the Environment method name
1326 you use to call the builder.
1327 Notice also that you can leave off the suffixes,
1328 and the builder will add them automatically.
1331 bld = Builder(name = 'PDFBuilder',
1332 action = 'pdftex < $SOURCES > $TARGET'
1334 src_suffix = '.tex')
1335 env = Environment(BUILDERS = [bld])
1336 env.PDFBuilder(target = 'foo.pdf', source = 'foo.tex')
1338 # The following creates "bar.pdf" from "bar.text"
1339 env.PDFBuilder(target = 'bar', source = 'bar')
1342 .SS Creating a Hierarchical Build
1344 Notice that the file names specified in a subdirectory
1345 are relative to that subdirectory.
1351 env.Program(target = 'foo', source = 'foo.c')
1353 SConscript('sub/SConscript')
1358 # Builds sub/foo from sub/foo.c
1359 env.Program(target = 'foo', source = 'foo.c')
1361 SConscript('dir/SConscript')
1366 # Builds sub/dir/foo from sub/dir/foo.c
1367 env.Program(target = 'foo', source = 'foo.c')
1370 .SS Sharing Variables Between SConscript Files
1372 You must explicitly Export() and Import() variables that
1373 you want to share between SConscript files.
1379 env.Program(target = 'foo', source = 'foo.c')
1382 SConscript('subdirectory/SConscript')
1384 subdirectory/SConscript:
1387 env.Program(target = 'foo', source = 'foo.c')
1390 .SS Building Multiple Variants From the Same Source
1392 Use the BuildDir() method to establish
1393 one or more separate build directories for
1394 a given source directory,
1395 then use the SConscript() method
1396 to specify the SConscript files
1397 in the build directories:
1405 BuildDir('foo', 'src')
1406 SConscript('foo/SConscript')
1409 BuildDir('bar', 'src')
1410 SConscript('bar/SConscript')
1415 env = Environment(CCFLAGS = ccflags)
1416 env.Program(target = 'src', source = 'src.c')
1419 Note the use of the Export() method
1420 to set the "ccflags" variable to a different
1421 value for each variant build.
1426 Specifies the directory that contains the SCons Python module directory
1427 (e.g. /home/aroach/scons-src-0.01/src/engine).
1430 A string of options that will be used by scons in addition to those passed
1431 on the command line.
1442 Steven Knight <knight@baldmt.com>
1444 Anthony Roach <aroach@electriceyeball.com>