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 .TH SCONS 1 "__MONTH_YEAR__"
25 .\" ES - Example Start - indents and turns off line fill
31 .\" EE - Example End - ends indent and turns line fill back on
38 scons \- a software construction tool
54 utility builds software (or other files) by determining which
55 component pieces must be rebuilt and executing the necessary commands to
60 searches for a file named
65 (in that order) in the current directory and reads its
66 configuration from the first file found.
67 An alternate file name may be
74 file can specify subsidiary
75 configuration files using the
79 these subsidiary files are named
81 although any name may be used.
82 (Because of this naming convention,
83 the term "SConscript files"
84 is sometimes used to refer
88 regardless of actual file name.)
90 The configuration files
91 specify the target files to be built, and
92 (optionally) the rules to build those targets. Reasonable default
93 rules exist for building common software components (executable
94 programs, object files, libraries), so that for most software
95 projects, only the target and input files need be specified.
101 looks for a directory named
103 in the directory containing the
107 is added to sys.path,
109 .IR site_scons/site_init.py ,
110 is evaluated if it exists,
112 .I site_scons/site_tools
113 is added to the default toolpath if it exist.
118 options for more details.
121 reads and executes the SConscript files as Python scripts,
122 so you may use normal Python scripting capabilities
123 (such as flow control, data manipulation, and imported Python libraries)
124 to handle complicated build situations.
126 however, reads and executes all of the SConscript files
128 it begins building any targets.
129 To make this obvious,
131 prints the following messages about what it is doing:
135 scons: Reading SConscript files ...
136 scons: done reading SConscript files.
137 scons: Building targets ...
139 scons: done building targets.
144 (everything except the line that reads "cp foo.in foo.out")
145 may be suppressed using the
150 does not automatically propagate
151 the external environment used to execute
153 to the commands used to build target files.
154 This is so that builds will be guaranteed
155 repeatable regardless of the environment
156 variables set at the time
159 This also means that if the compiler or other commands
160 that you want to use to build your target files
161 are not in standard system locations,
163 will not find them unless
164 you explicitly set the PATH
165 to include those locations.
166 Whenever you create an
168 construction environment,
169 you can propagate the value of PATH
170 from your external environment as follows:
174 env = Environment(ENV = {'PATH' : os.environ['PATH']})
177 Similarly, if the commands use external environment variables
178 like $PATH, $HOME, $JAVA_HOME, $LANG, $SHELL, $TERM, etc.,
179 these variables can also be explicitly propagated:
183 env = Environment(ENV = {'PATH' : os.environ['PATH'],
184 'HOME' : os.environ['HOME']})
187 Or you may explicitly propagate the invoking user's
188 complete external environment:
192 env = Environment(ENV = os.environ)
195 This comes at the expense of making your build
196 dependent on the user's environment being set correctly,
197 but it may be more convenient for many configurations.
200 can scan known input files automatically for dependency
201 information (for example, #include statements
202 in C or C++ files) and will rebuild dependent files appropriately
203 whenever any "included" input file changes.
206 ability to define new scanners for unknown input file types.
209 knows how to fetch files automatically from
210 SCCS or RCS subdirectories
211 using SCCS, RCS or BitKeeper.
214 is normally executed in a top-level directory containing a
216 file, optionally specifying
217 as command-line arguments
218 the target file or files to be built.
220 By default, the command
226 will build all target files in or below the current directory.
227 Explicit default targets
228 (to be built when no targets are specified on the command line)
229 may be defined the SConscript file(s)
232 function, described below.
236 targets are specified in the SConscript file(s),
237 all target files in or below the current directory
238 may be built by explicitly specifying
239 the current directory (.)
240 as a command-line target:
246 Building all target files,
247 including any files outside of the current directory,
248 may be specified by supplying a command-line target
249 of the root directory (on POSIX systems):
255 or the path name(s) of the volume(s) in which all the targets
256 should be built (on Windows systems):
262 To build only specific targets,
263 supply them as command-line arguments:
269 in which case only the specified targets will be built
270 (along with any derived files on which they depend).
272 Specifying "cleanup" targets in SConscript files is not usually necessary.
275 flag removes all files
276 necessary to build the specified target:
282 to remove all target files, or:
285 scons -c build export
288 to remove target files under build and export.
289 Additional files or directories to remove can be specified using the
292 Conversely, targets that would normally be removed by the
295 can be prevented from being removed by using the
299 A subset of a hierarchical tree may be built by
300 remaining at the top-level directory (where the
302 file lives) and specifying the subdirectory as the target to be
309 or by changing directory and invoking scons with the
311 option, which traverses up the directory
312 hierarchy until it finds the
314 file, and then builds
315 targets relatively to the current subdirectory:
323 supports building multiple targets in parallel via a
325 option that takes, as its argument, the number
326 of simultaneous tasks that may be spawned:
332 builds four targets in parallel, for example.
335 can maintain a cache of target (derived) files that can
336 be shared between multiple builds. When caching is enabled in a
337 SConscript file, any target files built by
340 to the cache. If an up-to-date target file is found in the cache, it
341 will be retrieved from the cache instead of being rebuilt locally.
342 Caching behavior may be disabled and controlled in other ways by the
344 .BR --cache-disable ,
347 command-line options. The
349 option is useful to prevent multiple builds
350 from trying to update the cache simultaneously.
352 Values of variables to be passed to the SConscript file(s)
353 may be specified on the command line:
359 These variables are available in SConscript files
360 through the ARGUMENTS dictionary,
361 and can be used in the SConscript file(s) to modify
362 the build in any way:
365 if ARGUMENTS.get('debug', 0):
366 env = Environment(CCFLAGS = '-g')
371 The command-line variable arguments are also available
373 indexed by their order on the command line.
374 This allows you to process them in order rather than by name,
376 ARGLIST[0] returns a tuple
377 containing (argname, argvalue).
378 A Python exception is thrown if you
379 try to access a list member that
383 requires Python version 1.5.2 or later.
384 There should be no other dependencies or requirements to run
387 .\" The following paragraph reflects the default tool search orders
388 .\" currently in SCons/Tool/__init__.py. If any of those search orders
389 .\" change, this documentation should change, too.
392 knows how to search for available programming tools
396 searches in order for the
397 Microsoft Visual C++ tools,
398 the MinGW tool chain,
399 the Intel compiler tools,
400 and the PharLap ETS compiler.
403 searches in order for the
406 and the Microsoft Visual C++ tools,
407 On SGI IRIX, IBM AIX, Hewlett Packard HP-UX, and Sun Solaris systems,
409 searches for the native compiler tools
410 (MIPSpro, Visual Age, aCC, and Forte tools respectively)
411 and the GCC tool chain.
412 On all other platforms,
413 including POSIX (Linux and UNIX) platforms,
416 for the GCC tool chain,
417 the Microsoft Visual C++ tools,
418 and the Intel compiler tools.
419 You may, of course, override these default values
420 by appropriate configuration of
421 Environment construction variables.
426 supports the same command-line options as GNU
428 and many of those supported by
433 Ignored for compatibility with non-GNU versions of
437 -c, --clean, --remove
438 Clean up by removing all target files for which a construction
439 command is specified.
440 Also remove any files or directories associated to the construction command
444 Will not remove any targets specified by the
449 .RI --cache-debug= file
450 Print debug information about the
460 the debug information are printed to the standard output.
461 The printed messages describe what signature file names are
462 being looked for in, retrieved from, or written to the
467 --cache-disable, --no-cache
468 Disable the derived-file caching specified by
471 will neither retrieve files from the cache
472 nor copy files to the cache.
475 --cache-force, --cache-populate
478 populate a cache by copying any already-existing, up-to-date
479 derived files to the cache,
480 in addition to files built by this invocation.
481 This is useful to populate a new cache with
482 all the current derived files,
483 or to add to the cache any derived files
484 recently built with caching disabled via the
492 and retrieving a derived file from the cache,
494 that would have been executed to build the file,
495 instead of the usual report,
496 "Retrieved `file' from cache."
497 This will produce consistent output for build logs,
498 regardless of whether a target
499 file was rebuilt or retrieved from the cache.
503 This specifies how the
505 call should use or generate the
506 results of configuration tests.
507 The option should be specified from
508 among the following choices:
512 scons will use its normal dependency mechanisms
513 to decide if a test must be rebuilt or not.
514 This saves time by not running the same configuration tests
515 every time you invoke scons,
516 but will overlook changes in system header files
517 or external commands (such as compilers)
518 if you don't specify those dependecies explicitly.
519 This is the default behavior.
523 If this option is specified,
524 all configuration tests will be re-run
525 regardless of whether the
526 cached results are out of date.
527 This can be used to explicitly
528 force the configuration tests to be updated
529 in response to an otherwise unconfigured change
530 in a system header file or compiler.
534 If this option is specified,
535 no configuration tests will be rerun
536 and all results will be taken from cache.
537 Note that scons will still consider it an error
538 if --config=cache is specified
539 and a necessary test does not
540 yet have any results in the cache.
543 .RI "-C" " directory" ", --directory=" directory
544 Change to the specified
546 before searching for the
551 file, or doing anything
554 options are interpreted
555 relative to the previous one, and the right-most
557 option wins. (This option is nearly
559 .BR "-f directory/SConstruct" ,
560 except that it will search for
565 in the specified directory.)
569 .\" Display dependencies while building target files. Useful for
570 .\" figuring out why a specific file is being rebuilt, as well as
571 .\" general debugging of the build process.
575 Works exactly the same way as the
577 option except for the way default targets are handled.
578 When this option is used and no targets are specified on the command line,
579 all default targets are built, whether or not they are below the current
584 Debug the build process.
586 specifies what type of debugging:
590 Print how many objects are created
591 of the various classes used internally by SCons
592 before and after reading the SConscript files
593 and before and after building targets.
594 This is not supported when run under Python versions earlier than 2.1,
595 when SCons is executed with the Python
598 or when the SCons modules
599 have been compiled with optimization
600 (that is, when executing from
606 A synonym for the newer
609 This will be deprecated in some future release
610 and ultimately removed.
614 Print an explanation of precisely why
616 is deciding to (re-)build any targets.
617 (Note: this does not print anything
624 Instruct the scanner that searches for libraries
625 to print a message about each potential library
626 name it is searching for,
627 and about the actual libraries it finds.
631 Print the include tree after each top-level target is built.
632 This is generally used to find out what files are included by the sources
633 of a given derived file:
636 $ scons --debug=includes foo.o
641 Prints a summary of hits and misses using the Memoizer,
642 an internal subsystem that counts
643 how often SCons uses cached values in memory
644 instead of recomputing them each time they're needed.
645 Only available when using Python 2.2 or later.
649 Prints how much memory SCons uses
650 before and after reading the SConscript files
651 and before and after building targets.
655 A deprecated option preserved for backwards compatibility.
659 Prints a list of the various objects
660 of the various classes used internally by SCons.
661 This only works when run under Python 2.1 or later.
665 Re-run SCons under the control of the
671 Print the raw command line used to build each target
672 before the construction environment variables are substituted.
673 Also shows which targets are being built by this command.
674 Output looks something like this:
676 $ scons --debug=presub
677 Building myprog.o with action(s):
678 $SHCC $SHCFLAGS $SHCCFLAGS $CPPFLAGS $_CPPINCFLAGS -c -o $TARGET $SOURCES
684 Prints an internal Python stack trace
685 when encountering an otherwise unexplained error.
689 A synonym for the newer
692 This will be deprecated in some future release
693 and ultimately removed.
697 Prints various time profiling information:
698 the time spent executing each individual build command;
699 the total build time (time SCons ran from beginning to end);
700 the total time spent reading and executing SConscript files;
701 the total time spent SCons itself spend running
702 (that is, not counting reading and executing SConscript files);
703 and both the total time spent executing all build commands
704 and the elapsed wall-clock time spent executing those build commands.
707 is executed without the
710 the elapsed wall-clock time will typically
711 be slightly longer than the total time spent
712 executing all the build commands,
713 due to the SCons processing that takes place
714 in between executing each command.
722 and your build configuration allows good parallelization,
723 the elapsed wall-clock time should
724 be significantly smaller than the
725 total time spent executing all the build commands,
726 since multiple build commands and
727 intervening SCons processing
728 should take place in parallel.)
732 A synonym for the newer
735 This will be deprecated in some future release
736 and ultimately removed.
739 .RI --diskcheck= types
740 Enable specific checks for
741 whether or not there is a file on disk
742 where the SCons configuration expects a directory
744 and whether or not RCS or SCCS sources exist
745 when searching for source and include files.
748 argument can be set to:
750 to enable all checks explicitly
751 (the default behavior);
753 to disable all such checks;
755 to check that files and directories on disk
756 match SCons' expected configuration;
758 to check for the existence of an RCS source
759 for any missing source or include files;
761 to check for the existence of an SCCS source
762 for any missing source or include files.
763 Multiple checks can be specified separated by commas;
765 .B --diskcheck=sccs,rcs
766 would still check for SCCS and RCS sources,
767 but disable the check for on-disk matches of files and directories.
768 Disabling some or all of these checks
769 can provide a performance boost for large configurations,
770 or when the configuration will check for files and/or directories
771 across networked or shared file systems,
772 at the slight increased risk of an incorrect build
773 or of not handling errors gracefully
774 (if include files really should be
775 found in SCCS or RCS, for example,
776 or if a file really does exist
777 where the SCons configuration expects a directory).
780 .RI --duplicate= ORDER
781 There are three ways to duplicate files in a build tree: hard links,
782 soft (symbolic) links and copies. The default behaviour of SCons is to
783 prefer hard links to soft links to copies. You can specify different
784 behaviours with this option.
794 SCons will attempt to duplicate files using
795 the mechanisms in the specified order.
798 .\" -e, --environment-overrides
799 .\" Variables from the execution environment override construction
800 .\" variables from the SConscript files.
803 .RI -f " file" ", --file=" file ", --makefile=" file ", --sconstruct=" file
806 as the initial SConscript file.
810 Print a local help message for this build, if one is defined in
811 the SConscript file(s), plus a line that describes the
813 option for command-line option help. If no local help message
814 is defined, prints the standard help message about command-line
815 options. Exits after displaying the appropriate message.
819 Print the standard help message about command-line options and
824 Ignore all errors from commands executed to rebuild files.
827 .RI -I " directory" ", --include-dir=" directory
831 imported Python modules. If several
834 are used, the directories are searched in the order specified.
838 Cache implicit dependencies.
841 to use the implicit (scanned) dependencies
842 from the last time it was run
843 instead of scanning the files for implicit dependencies.
844 This can significantly speed up SCons,
845 but with the following limitations:
848 will not detect changes to implicit dependency search paths
850 .BR CPPPATH ", " LIBPATH )
851 that would ordinarily
852 cause different versions of same-named files to be used.
855 will miss changes in the implicit dependencies
856 in cases where a new implicit
857 dependency is added earlier in the implicit dependency search path
859 .BR CPPPATH ", " LIBPATH )
860 than a current implicit dependency with the same name.
863 --implicit-deps-changed
864 Forces SCons to ignore the cached implicit dependencies. This causes the
865 implicit dependencies to be rescanned and recached. This implies
866 .BR --implicit-cache .
869 --implicit-deps-unchanged
870 Force SCons to ignore changes in the implicit dependencies.
871 This causes cached implicit dependencies to always be used.
873 .BR --implicit-cache .
877 Starts SCons in interactive mode.
878 The SConscript files are read once and a
881 Targets may now be rebuilt by typing commands at interactive prompt
882 without having to re-read the SConscript files
883 and re-initialize the dependency graph from scratch.
885 SCons interactive mode supports the following commands:
889 .BI build "[OPTIONS] [TARGETS] ..."
892 (and their dependencies)
901 The following SCons command-line options affect the
907 --cache-disable, --no-cache
908 --cache-force, --cache-populate
914 -n, --no-exec, --just-print, --dry-run, --recon
916 -s, --silent, --quiet
917 --taskmastertrace=FILE
922 Any other SCons command-line options that are specified
924 but have no effect on the
927 (mainly because they affect how the SConscript files are read,
928 which only happens once at the beginning of interactive mode).
931 .BI clean "[OPTIONS] [TARGETS] ..."
934 (and their dependencies)
935 with the specified options.
938 This command is itself a synonym for
943 Exits SCons interactive mode.
944 You can also exit by terminating input
945 (CTRL+D on UNIX or Linux systems,
946 CTRL+Z on Windows systems).
950 Provides a help message about
951 the commands available in SCons interactive mode.
961 .BI shell "[COMMANDLINE]"
962 Executes the specified
968 executes the interactive command interpreter
972 (on UNIX and Linux systems)
976 (on Windows systems).
984 Prints SCons version information.
988 An empty line repeats the last typed command.
989 Command-line editing can be used if the
994 $ scons --interactive
995 scons: Reading SConscript files ...
996 scons: done reading SConscript files.
997 scons>>> build -n prog
1002 .RI -j " N" ", --jobs=" N
1003 Specifies the number of jobs (commands) to run simultaneously.
1004 If there is more than one
1006 option, the last one is effective.
1010 .\" is specified without an argument,
1012 .\" will not limit the number of
1013 .\" simultaneous jobs.
1017 Continue as much as possible after an error. The target that
1018 failed and those that depend on it will not be remade, but other
1019 targets specified on the command line will still be processed.
1022 .\" .RI -l " N" ", --load-average=" N ", --max-load=" N
1023 .\" No new jobs (commands) will be started if
1024 .\" there are other jobs running and the system load
1025 .\" average is at least
1027 .\" (a floating-point number).
1032 .\" List derived files (targets, dependencies) that would be built,
1033 .\" but do not build them.
1034 .\" [XXX This can probably go away with the right
1035 .\" combination of other options. Revisit this issue.]
1039 .\" List derived files that would be built, with the actions
1040 .\" (commands) that build them. Does not build the files.
1041 .\" [XXX This can probably go away with the right
1042 .\" combination of other options. Revisit this issue.]
1046 .\" List derived files that would be built, plus where the file is
1047 .\" defined (file name and line number). Does not build the files.
1048 .\" [XXX This can probably go away with the right
1049 .\" combination of other options. Revisit this issue.]
1053 Ignored for compatibility with non-GNU versions of
1057 .RI --max-drift= SECONDS
1058 Set the maximum expected drift in the modification time of files to
1060 This value determines how long a file must be unmodified
1061 before its cached content signature
1062 will be used instead of
1063 calculating a new content signature (MD5 checksum)
1064 of the file's contents.
1065 The default value is 2 days, which means a file must have a
1066 modification time of at least two days ago in order to have its
1067 cached content signature used.
1068 A negative value means to never cache the content
1069 signature and to ignore the cached value if there already is one. A value
1070 of 0 means to always use the cached signature,
1071 no matter how old the file is.
1074 .RI --md5-chunksize= KILOBYTES
1075 Set the block size used to compute MD5 signatures to
1077 This value determines the size of the chunks which are read in at once when
1078 computing MD5 signatures. Files below that size are fully stored in memory
1079 before performing the signature computation while bigger files are read in
1080 block-by-block. A huge block-size leads to high memory consumption while a very
1081 small block-size slows down the build considerably.
1083 The default value is to use a chunk size of 64 kilobytes, which should
1084 be appropriate for most uses.
1087 -n, --just-print, --dry-run, --recon
1088 No execute. Print the commands that would be executed to build
1089 any out-of-date target files, but do not execute the commands.
1093 Prevents the automatic addition of the standard
1097 Also prevents loading the
1098 .I site_scons/site_init.py
1099 module if it exists, and prevents adding
1100 .I site_scons/site_tools
1104 .\" .RI -o " file" ", --old-file=" file ", --assume-old=" file
1108 .\" not rebuild anything due to changes in the contents of
1111 .\" .RI --override " file"
1112 .\" Read values to override specific build environment variables
1113 .\" from the specified
1117 .\" Print the data base (construction environments,
1118 .\" Builder and Scanner objects) that are defined
1119 .\" after reading the SConscript files.
1120 .\" After printing, a normal build is performed
1121 .\" as usual, as specified by other command-line options.
1122 .\" This also prints version information
1127 .\" To print the database without performing a build do:
1135 Run SCons under the Python profiler
1136 and save the results in the specified
1138 The results may be analyzed using the Python
1143 Do not run any commands, or print anything. Just return an exit
1144 status that is zero if the specified targets are already up to
1145 date, non-zero otherwise.
1148 Quiets SCons status messages about
1149 reading SConscript files,
1151 and entering directories.
1152 Commands that are executed
1153 to rebuild target files are still printed.
1156 .\" -r, -R, --no-builtin-rules, --no-builtin-variables
1157 .\" Clear the default construction variables. Construction
1158 .\" environments that are created will be completely empty.
1162 Build dependencies in a random order. This is useful when
1163 building multiple trees simultaneously with caching enabled,
1164 to prevent multiple builds from simultaneously trying to build
1165 or retrieve the same target files.
1168 -s, --silent, --quiet
1169 Silent. Do not print commands that are executed to rebuild
1171 Also suppresses SCons status messages.
1174 -S, --no-keep-going, --stop
1175 Ignored for compatibility with GNU
1180 Uses the named dir as the site dir rather than the default
1182 dir. This dir will get prepended to
1185 .IR dir /site_init.py
1186 will get loaded if it exists, and
1188 will get added to the default toolpath.
1191 .RI --stack-size= KILOBYTES
1192 Set the size stack used to run threads to
1194 This value determines the stack size of the threads used to run jobs.
1195 These are the threads that execute the actions of the builders for the
1196 nodes that are out-of-date.
1197 Note that this option has no effect unless the
1199 option, which corresponds to -j and --jobs, is larger than one. Using
1200 a stack size that is too small may cause stack overflow errors. This
1201 usually shows up as segmentation faults that cause scons to abort
1202 before building anything. Using a stack size that is too large will
1203 cause scons to use more memory than required and may slow down the entire
1206 The default value is to use a stack size of 256 kilobytes, which should
1207 be appropriate for most uses. You should not need to increase this value
1208 unless you encounter stack overflow errors.
1212 Ignored for compatibility with GNU
1214 (Touching a file to make it
1215 appear up-to-date is unnecessary when using
1219 .RI --taskmastertrace= file
1220 Prints trace information to the specified
1222 about how the internal Taskmaster object
1223 evaluates and controls the order in which Nodes are built.
1226 may be used to specify the standard output.
1230 Prints a tree of the dependencies
1231 after each top-level target is built.
1232 This prints out some or all of the tree,
1240 Print the entire dependency tree
1241 after each top-level target is built.
1242 This prints out the complete dependency tree,
1243 including implicit dependencies and ignored dependencies.
1247 Restricts the tree output to only derived (target) files,
1252 Prints status information for each displayed node.
1256 Prunes the tree to avoid repeating dependency information
1257 for nodes that have already been displayed.
1258 Any node that has already been displayed
1259 will have its name printed in
1260 .BR "[square brackets]" ,
1261 as an indication that the dependencies
1262 for that node can be found by searching
1263 for the relevant output higher up in the tree.
1266 Multiple options may be specified,
1267 separated by commas:
1270 # Prints only derived files, with status information:
1271 scons --tree=derived,status
1273 # Prints all dependencies of target, with status information
1274 # and pruning dependencies of already-visited Nodes:
1275 scons --tree=all,prune,status target
1279 -u, --up, --search-up
1280 Walks up the directory structure until an
1285 file is found, and uses that
1286 as the top of the directory tree.
1287 If no targets are specified on the command line,
1288 only targets at or below the
1289 current directory will be built.
1293 Works exactly the same way as the
1295 option except for the way default targets are handled.
1296 When this option is used and no targets are specified on the command line,
1297 all default targets that are defined in the SConscript(s) in the current
1298 directory are built, regardless of what directory the resultant targets end
1305 version, copyright information,
1306 list of authors, and any other relevant information.
1310 -w, --print-directory
1311 Print a message containing the working directory before and
1312 after other processing.
1315 --no-print-directory
1316 Turn off -w, even if it was turned on implicitly.
1319 .RI --warn= type ", --warn=no-" type
1320 Enable or disable warnings.
1322 specifies the type of warnings to be enabled or disabled:
1325 --warn=all, --warn=no-all
1326 Enables or disables all warnings.
1329 --warn=cache-write-error, --warn=no-cache-write-error
1330 Enables or disables warnings about errors trying to
1331 write a copy of a built file to a specified
1333 These warnings are disabled by default.
1336 --warn=corrupt-sconsign, --warn=no-corrupt-sconsign
1337 Enables or disables warnings about unfamiliar signature data in
1340 These warnings are enabled by default.
1343 --warn=dependency, --warn=no-dependency
1344 Enables or disables warnings about dependencies.
1345 These warnings are disabled by default.
1348 --warn=deprecated, --warn=no-deprecated
1349 Enables or disables all warnings about use of deprecated features.
1350 These warnings are enabled by default.
1351 Warnings for some specific deprecated features
1352 may be enabled or disabled individually;
1357 --warn=deprecated-copy, --warn=no-deprecated-copy
1358 Enables or disables warnings about use of the deprecated
1363 --warn=deprecated-source-signatures, --warn=no-deprecated-source-signatures
1364 Enables or disables warnings about use of the deprecated
1365 .B SourceSignatures()
1367 .B env.SourceSignatures()
1371 --warn=deprecated-target-signatures, --warn=no-deprecated-target-signatures
1372 Enables or disables warnings about use of the deprecated
1373 .B TargetSignatures()
1375 .B env.TargetSignatures()
1380 --warn=duplicate-environment, --warn=no-duplicate-environment
1381 Enables or disables warnings about attempts to specify a build
1382 of a target with two different construction environments
1383 that use the same action.
1384 These warnings are enabled by default.
1387 --warn=fortran-cxx-mix, --warn=no-fortran-cxx-mix
1388 Enables or disables the specific warning about linking
1389 Fortran and C++ object files in a single executable,
1390 which can yield unpredictable behavior with some compilers.
1393 --warn=link, --warn=no-link
1394 Enables or disables warnings about link steps.
1397 --warn=misleading-keywords, --warn=no-misleading-keywords
1398 Enables or disables warnings about use of the misspelled keywords
1402 when calling Builders.
1405 characters, the correct spellings are
1409 These warnings are enabled by default.
1412 --warn=missing-sconscript, --warn=no-missing-sconscript
1413 Enables or disables warnings about missing SConscript files.
1414 These warnings are enabled by default.
1417 --warn=no-md5-module, --warn=no-no-md5-module
1418 Enables or disables warnings about the version of Python
1419 not having an MD5 checksum module available.
1420 These warnings are enabled by default.
1423 --warn=no-metaclass-support, --warn=no-no-metaclass-support
1424 Enables or disables warnings about the version of Python
1425 not supporting metaclasses when the
1428 These warnings are enabled by default.
1431 --warn=no-object-count, --warn=no-no-object-count
1432 Enables or disables warnings about the
1434 feature not working when
1436 is run with the python
1438 option or from optimized Python (.pyo) modules.
1441 --warn=no-parallel-support, --warn=no-no-parallel-support
1442 Enables or disables warnings about the version of Python
1443 not being able to support parallel builds when the
1446 These warnings are enabled by default.
1449 --warn=python-version, --warn=no-python-version
1450 Enables or disables the warning about running
1451 SCons with a deprecated version of Python.
1452 These warnings are enabled by default.
1455 --warn=reserved-variable, --warn=no-reserved-variable
1456 Enables or disables warnings about attempts to set the
1457 reserved construction variable names
1463 These warnings are disabled by default.
1466 --warn=stack-size, --warn=no-stack-size
1467 Enables or disables warnings about requests to set the stack size
1468 that could not be honored.
1469 These warnings are enabled by default.
1472 .\" .RI --write-filenames= file
1473 .\" Write all filenames considered into
1477 .\" .RI -W " file" ", --what-if=" file ", --new-file=" file ", --assume-new=" file
1478 .\" Pretend that the target
1481 .\" modified. When used with the
1484 .\" show you what would be rebuilt if you were to modify that file.
1490 .\" --warn-undefined-variables
1491 .\" Warn when an undefined variable is referenced.
1494 .RI -Y " repository" ", --repository=" repository ", --srcdir=" repository
1495 Search the specified repository for any input and target
1496 files not found in the local directory hierarchy. Multiple
1498 options may be specified, in which case the
1499 repositories are searched in the order specified.
1501 .SH CONFIGURATION FILE REFERENCE
1502 .\" .SS Python Basics
1503 .\" XXX Adding this in the future would be a help.
1504 .SS Construction Environments
1505 A construction environment is the basic means by which the SConscript
1506 files communicate build information to
1508 A new construction environment is created using the
1519 may be set in a construction environment
1520 either by specifying them as keywords when the object is created
1521 or by assigning them a value after the object is created:
1524 env = Environment(FOO = 'foo')
1529 construction variables may also be set or modified by the
1531 keyword argument, which applies the
1533 method (described below) to the argument value
1534 after all other processing is completed.
1535 This is useful either if the exact content of the flags is unknown
1536 (for example, read from a control file)
1537 or if the flags are distributed to a number of construction variables.
1540 env = Environment(parse_flags = '-Iinclude -DEBUG -lm')
1543 This example adds 'include' to
1550 By default, a new construction environment is
1551 initialized with a set of builder methods
1552 and construction variables that are appropriate
1553 for the current platform.
1554 An optional platform keyword argument may be
1555 used to specify that an environment should
1556 be initialized for a different platform:
1559 env = Environment(platform = 'cygwin')
1560 env = Environment(platform = 'os2')
1561 env = Environment(platform = 'posix')
1562 env = Environment(platform = 'win32')
1565 Specifying a platform initializes the appropriate
1566 construction variables in the environment
1567 to use and generate file names with prefixes
1568 and suffixes appropriate for the platform.
1576 variables from the user's external environment
1577 to the construction environment's
1580 This is so that any executed commands
1581 that use sockets to connect with other systems
1582 (such as fetching source files from
1583 external CVS repository specifications like
1584 .BR :pserver:anonymous@cvs.sourceforge.net:/cvsroot/scons )
1585 will work on Windows systems.
1587 The platform argument may be function or callable object,
1588 in which case the Environment() method
1589 will call the specified argument to update
1590 the new construction environment:
1593 def my_platform(env):
1594 env['VAR'] = 'xyzzy'
1596 env = Environment(platform = my_platform)
1599 Additionally, a specific set of tools
1600 with which to initialize the environment
1601 may be specified as an optional keyword argument:
1604 env = Environment(tools = ['msvc', 'lex'])
1607 Non-built-in tools may be specified using the toolpath argument:
1610 env = Environment(tools = ['default', 'foo'], toolpath = ['tools'])
1613 This looks for a tool specification in tools/foo.py (as well as
1614 using the ordinary default tools for the platform). foo.py should
1615 have two functions: generate(env, **kw) and exists(env).
1619 modifies the passed-in environment
1620 to set up variables so that the tool
1622 it may use any keyword arguments
1623 that the user supplies (see below)
1624 to vary its initialization.
1627 function should return a true
1628 value if the tool is available.
1629 Tools in the toolpath are used before
1630 any of the built-in ones. For example, adding gcc.py to the toolpath
1631 would override the built-in gcc tool.
1632 Also note that the toolpath is
1633 stored in the environment for use
1641 base = Environment(toolpath=['custom_path'])
1642 derived = base.Clone(tools=['custom_tool'])
1643 derived.CustomBuilder()
1646 The elements of the tools list may also
1647 be functions or callable objects,
1648 in which case the Environment() method
1649 will call the specified elements
1650 to update the new construction environment:
1654 env['XYZZY'] = 'xyzzy'
1656 env = Environment(tools = [my_tool])
1659 The individual elements of the tools list
1660 may also themselves be two-element lists of the form
1661 .RI ( toolname ", " kw_dict ).
1662 SCons searches for the
1664 specification file as described above, and
1667 which must be a dictionary, as keyword arguments to the tool's
1672 function can use the arguments to modify the tool's behavior
1673 by setting up the environment in different ways
1674 or otherwise changing its initialization.
1677 # in tools/my_tool.py:
1678 def generate(env, **kw):
1679 # Sets MY_TOOL to the value of keyword argument 'arg1' or 1.
1680 env['MY_TOOL'] = kw.get('arg1', '1')
1685 env = Environment(tools = ['default', ('my_tool', {'arg1': 'abc'})],
1689 The tool definition (i.e. my_tool()) can use the PLATFORM variable from
1690 the environment it receives to customize the tool for different platforms.
1692 If no tool list is specified, then SCons will auto-detect the installed
1693 tools using the PATH variable in the ENV construction variable and the
1694 platform name when the Environment is constructed. Changing the PATH
1695 variable after the Environment is constructed will not cause the tools to
1698 SCons supports the following tool specifications out of the box:
1778 Additionally, there is a "tool" named
1780 which configures the
1781 environment with a default set of tools for the current platform.
1783 On posix and cygwin platforms
1784 the GNU tools (e.g. gcc) are preferred by SCons,
1785 on Windows the Microsoft tools (e.g. msvc)
1786 followed by MinGW are preferred by SCons,
1787 and in OS/2 the IBM tools (e.g. icc) are preferred by SCons.
1791 Build rules are specified by calling a construction
1792 environment's builder methods.
1793 The arguments to the builder methods are
1795 (a list of targets to be built,
1799 (a list of sources to be built,
1800 usually file names).
1802 Because long lists of file names
1803 can lead to a lot of quoting,
1808 and a same-named environment method
1809 that split a single string
1810 into a list, separated on
1811 strings of white-space characters.
1812 (These are similar to the
1813 string.split() method
1814 from the standard Python library,
1815 but work even if the input isn't a string.)
1817 Like all Python arguments,
1818 the target and source arguments to a builder method
1819 can be specified either with or without
1820 the "target" and "source" keywords.
1821 When the keywords are omitted,
1822 the target is first,
1823 followed by the source.
1824 The following are equivalent examples of calling the Program builder method:
1827 env.Program('bar', ['bar.c', 'foo.c'])
1828 env.Program('bar', Split('bar.c foo.c'))
1829 env.Program('bar', env.Split('bar.c foo.c'))
1830 env.Program(source = ['bar.c', 'foo.c'], target = 'bar')
1831 env.Program(target = 'bar', Split('bar.c foo.c'))
1832 env.Program(target = 'bar', env.Split('bar.c foo.c'))
1833 env.Program('bar', source = string.split('bar.c foo.c'))
1836 Target and source file names
1837 that are not absolute path names
1838 (that is, do not begin with
1845 an optional drive letter)
1846 are interpreted relative to the directory containing the
1852 on a path name means that the rest of the file name
1853 is interpreted relative to
1854 the directory containing
1860 is followed by a directory separator character
1861 (slash or backslash).
1866 # The comments describing the targets that will be built
1867 # assume these calls are in a SConscript file in the
1868 # a subdirectory named "subdir".
1870 # Builds the program "subdir/foo" from "subdir/foo.c":
1871 env.Program('foo', 'foo.c')
1873 # Builds the program "/tmp/bar" from "subdir/bar.c":
1874 env.Program('/tmp/bar', 'bar.c')
1876 # An initial '#' or '#/' are equivalent; the following
1877 # calls build the programs "foo" and "bar" (in the
1878 # top-level SConstruct directory) from "subdir/foo.c" and
1879 # "subdir/bar.c", respectively:
1880 env.Program('#foo', 'foo.c')
1881 env.Program('#/bar', 'bar.c')
1883 # Builds the program "other/foo" (relative to the top-level
1884 # SConstruct directory) from "subdir/foo.c":
1885 env.Program('#other/foo', 'foo.c')
1888 When the target shares the same base name
1889 as the source and only the suffix varies,
1890 and if the builder method has a suffix defined for the target file type,
1891 then the target argument may be omitted completely,
1894 will deduce the target file name from
1895 the source file name.
1896 The following examples all build the
1902 (on Windows systems)
1903 from the bar.c source file:
1906 env.Program(target = 'bar', source = 'bar.c')
1907 env.Program('bar', source = 'bar.c')
1908 env.Program(source = 'bar.c')
1909 env.Program('bar.c')
1914 keyword argument may be specified
1915 when calling a Builder.
1917 all source file strings that are not absolute paths
1918 will be interpreted relative to the specified
1920 The following example will build the
1925 program from the files
1931 env.Program('build/prog', ['f1.c', 'f2.c'], srcdir='src')
1934 It is possible to override or add construction variables when calling a
1935 builder method by passing additional keyword arguments.
1936 These overridden or added
1937 variables will only be in effect when building the target, so they will not
1938 affect other parts of the build. For example, if you want to add additional
1939 libraries for just one program:
1942 env.Program('hello', 'hello.c', LIBS=['gl', 'glut'])
1945 or generate a shared library with a non-standard suffix:
1948 env.SharedLibrary('word', 'word.cpp',
1950 LIBSUFFIXES=['.ocx'])
1953 (Note that both the $SHLIBSUFFIX and $LIBSUFFIXES variables must be set
1954 if you want SCons to search automatically
1955 for dependencies on the non-standard library names;
1956 see the descriptions of these variables, below, for more information.)
1958 It is also possible to use the
1960 keyword argument in an override:
1963 env = Program('hello', 'hello.c', parse_flags = '-Iinclude -DEBUG -lm')
1966 This example adds 'include' to
1973 Although the builder methods defined by
1976 methods of a construction environment object,
1977 they may also be called without an explicit environment:
1980 Program('hello', 'hello.c')
1981 SharedLibrary('word', 'word.cpp')
1985 the methods are called internally using a default construction
1986 environment that consists of the tools and values that
1988 has determined are appropriate for the local system.
1990 Builder methods that can be called without an explicit
1991 environment may be called from custom Python modules that you
1992 import into an SConscript file by adding the following
1993 to the Python module:
1996 from SCons.Script import *
1999 All builder methods return a list-like object
2000 containing Nodes that
2001 represent the target or targets that will be built.
2004 is an internal SCons object
2006 build targets or sources.
2008 The returned Node-list object
2009 can be passed to other builder methods as source(s)
2010 or passed to any SCons function or method
2011 where a filename would normally be accepted.
2012 For example, if it were necessary
2015 flag when compiling one specific object file:
2018 bar_obj_list = env.StaticObject('bar.c', CPPDEFINES='-DBAR')
2019 env.Program(source = ['foo.c', bar_obj_list, 'main.c'])
2022 Using a Node in this way
2023 makes for a more portable build
2024 by avoiding having to specify
2025 a platform-specific object suffix
2026 when calling the Program() builder method.
2028 Note that Builder calls will automatically "flatten"
2029 the source and target file lists,
2030 so it's all right to have the bar_obj list
2031 return by the StaticObject() call
2032 in the middle of the source file list.
2033 If you need to manipulate a list of lists returned by Builders
2034 directly using Python,
2035 you can either build the list by hand:
2038 foo = Object('foo.c')
2039 bar = Object('bar.c')
2040 objects = ['begin.o'] + foo + ['middle.o'] + bar + ['end.o']
2041 for object in objects:
2047 function supplied by scons
2048 to create a list containing just the Nodes,
2049 which may be more convenient:
2052 foo = Object('foo.c')
2053 bar = Object('bar.c')
2054 objects = Flatten(['begin.o', foo, 'middle.o', bar, 'end.o'])
2055 for object in objects:
2059 Note also that because Builder calls return
2060 a list-like object, not an actual Python list,
2065 operator to append Builder results to a Python list.
2066 Because the list and the object are different types,
2067 Python will not update the original list in place,
2068 but will instead create a new Node-list object
2069 containing the concatenation of the list
2070 elements and the Builder results.
2071 This will cause problems for any other Python variables
2072 in your SCons configuration
2073 that still hold on to a reference to the original list.
2074 Instead, use the Python
2076 method to make sure the list is updated in-place.
2082 # Do NOT use += as follows:
2084 # object_files += Object('bar.c')
2086 # It will not update the object_files list in place.
2088 # Instead, use the .extend() method:
2089 object_files.extend(Object('bar.c'))
2093 The path name for a Node's file may be used
2094 by passing the Node to the Python-builtin
2099 bar_obj_list = env.StaticObject('bar.c', CPPDEFINES='-DBAR')
2100 print "The path to bar_obj is:", str(bar_obj_list[0])
2103 Note again that because the Builder call returns a list,
2104 we have to access the first element in the list
2105 .B (bar_obj_list[0])
2106 to get at the Node that actually represents
2109 Builder calls support a
2111 keyword argument that
2112 specifies that the Builder's action(s)
2114 after changing directory.
2118 a string or a directory Node,
2119 scons will change to the specified directory.
2122 is not a string or Node
2124 then scons will change to the
2125 target file's directory.
2128 # scons will change to the "sub" subdirectory
2129 # before executing the "cp" command.
2130 env.Command('sub/dir/foo.out', 'sub/dir/foo.in',
2131 "cp dir/foo.in dir/foo.out",
2134 # Because chdir is not a string, scons will change to the
2135 # target's directory ("sub/dir") before executing the
2137 env.Command('sub/dir/foo.out', 'sub/dir/foo.in',
2138 "cp foo.in foo.out",
2142 Note that scons will
2144 automatically modify
2146 construction variables like
2150 when using the chdir
2151 keyword argument--that is,
2152 the expanded file names
2153 will still be relative to
2154 the top-level SConstruct directory,
2155 and consequently incorrect
2156 relative to the chdir directory.
2157 If you use the chdir keyword argument,
2158 you will typically need to supply a different
2164 to use just the filename portion of the
2168 provides the following builder methods:
2170 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2171 '\" BEGIN GENERATED BUILDER DESCRIPTIONS
2173 '\" The descriptions below of the various SCons Builders are generated
2174 '\" from the .xml files that live next to the various Python modules in
2175 '\" the build enginer library. If you're reading this [gnt]roff file
2176 '\" with an eye towards patching this man page, you can still submit
2177 '\" a diff against this text, but it will have to be translated to a
2178 '\" diff against the underlying .xml file before the patch is actually
2179 '\" accepted. If you do that yourself, it will make it easier to
2180 '\" integrate the patch.
2182 '\" BEGIN GENERATED BUILDER DESCRIPTIONS
2183 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2185 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2186 '\" END GENERATED BUILDER DESCRIPTIONS
2188 '\" The descriptions above of the various SCons Builders are generated
2189 '\" from the .xml files that live next to the various Python modules in
2190 '\" the build enginer library. If you're reading this [gnt]roff file
2191 '\" with an eye towards patching this man page, you can still submit
2192 '\" a diff against this text, but it will have to be translated to a
2193 '\" diff against the underlying .xml file before the patch is actually
2194 '\" accepted. If you do that yourself, it will make it easier to
2195 '\" integrate the patch.
2197 '\" END GENERATED BUILDER DESCRIPTIONS
2198 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2202 targets of builder methods automatically depend on their sources.
2203 An explicit dependency can
2204 be specified using the
2206 method of a construction environment (see below).
2211 source files for various programming languages,
2212 so the dependencies do not need to be specified explicitly.
2213 By default, SCons can
2216 Fortran source files with
2218 (POSIX systems only),
2223 and assembly language files with
2225 (POSIX systems only),
2230 for C preprocessor dependencies.
2231 SCons also has default support
2232 for scanning D source files,
2233 You can also write your own Scanners
2234 to add support for additional source file types.
2235 These can be added to the default
2236 Scanner object used by the
2238 .BR StaticObject (),
2241 Builders by adding them
2243 .B SourceFileScanner
2246 See the section "Scanner Objects,"
2247 below, for a more information about
2248 defining your own Scanner objects.
2250 .SS Methods and Functions to Do Things
2251 In addition to Builder methods,
2253 provides a number of other construction environment methods
2254 and global functions to
2255 manipulate the build configuration.
2257 Usually, a construction environment method
2258 and global function with the same name both exist
2259 so that you don't have to remember whether
2260 to a specific bit of functionality
2261 must be called with or without a construction environment.
2262 In the following list,
2263 if you call something as a global function
2266 .RI Function( arguments )
2268 and if you call something through a construction
2269 environment it looks like:
2271 .RI env.Function( arguments )
2273 If you can call the functionality in both ways,
2274 then both forms are listed.
2276 Global functions may be called from custom Python modules that you
2277 import into an SConscript file by adding the following
2278 to the Python module:
2281 from SCons.Script import *
2284 Except where otherwise noted,
2286 construction environment method
2288 provide the exact same functionality.
2289 The only difference is that,
2291 calling the functionality through a construction environment will
2292 substitute construction variables into
2293 any supplied strings.
2297 env = Environment(FOO = 'foo')
2302 In the above example,
2303 the first call to the global
2305 function will actually add a target named
2307 to the list of default targets,
2308 while the second call to the
2310 construction environment method
2311 will expand the value
2312 and add a target named
2314 to the list of default targets.
2315 For more on construction variable expansion,
2316 see the next section on
2317 construction variables.
2319 Construction environment methods
2320 and global functions supported by
2324 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2326 .RI Action( action ", [" strfunction ", " varlist ])
2328 .RI env.Action( action ", [" strfunction ", " varlist ])
2329 Creates an Action object for
2332 See the section "Action Objects,"
2333 below, for a complete explanation of the arguments and behavior.
2337 form of the invocation will expand
2338 construction variables in any arguments strings,
2342 at the time it is called
2343 using the construction variables in the
2345 construction environment through which
2350 form delays all variable expansion
2351 until the Action object is actually used.
2353 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2355 .RI AddMethod( object, function ", [" name ])
2357 .RI env.AddMethod( function ", [" name ])
2358 When called with the
2365 as the specified method
2367 When called with the
2368 .BR env.AddMethod ()
2372 to the construction environment
2374 as the specified method
2383 itself is used for the method name.
2388 # Note that the first argument to the function to
2389 # be attached as a method must be the object through
2390 # which the method will be called; the Python
2391 # convention is to call it 'self'.
2392 def my_method(self, arg):
2393 print "my_method() got", arg
2395 # Use the global AddMethod() function to add a method
2396 # to the Environment class. This
2397 AddMethod(Environment, my_method)
2399 env.my_method('arg')
2401 # Add the function as a method, using the function
2402 # name for the method call.
2404 env.AddMethod(my_method, 'other_method_name')
2405 env.other_method_name('another arg')
2408 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2410 .RI AddOption( arguments )
2411 This function adds a new command-line option to be recognized.
2414 are the same as supported by the standard Python
2415 .BR optparse.add_option ()
2416 method (with a few additional capabilities noted below);
2417 see the documentation for
2419 for a thorough discussion of its option-processing capabities.
2420 (Note that although the
2422 module was not a standard module until Python 2.3,
2424 contains a compatible version of the module
2425 that is used to provide identical functionality
2426 when run by earlier Python versions.)
2428 In addition to the arguments and values supported by the
2429 .B optparse.add_option ()
2433 function allows you to set the
2437 (a string with just the question mark)
2438 to indicate that the specified long option(s) take(s) an
2448 may be used to supply the "default"
2449 value that should be used when the
2450 option is specified on the command line
2451 without an explicit argument.
2455 keyword argument is supplied when calling
2457 the option will have a default value of
2460 Once a new command-line option has been added with
2462 the option value may be accessed using
2465 .BR env.GetOption ().
2466 \" NOTE: in SCons 1.x or 2.0, user options will be settable, but not yet.
2467 \" Uncomment this when that works. See tigris issue 2105.
2468 \" The value may also be set, using
2471 \" .BR env.SetOption (),
2472 \" if conditions in a
2474 \" require overriding any default value.
2475 \" Note, however, that a
2476 \" value specified on the command line will
2478 \" override a value set by any SConscript file.
2482 strings for the new option(s)
2483 will be displayed by the
2488 (the latter only if no other help text is
2489 specified in the SConscript files).
2490 The help text for the local options specified by
2492 will appear below the SCons options themselves,
2496 The options will appear in the help text
2497 in the order in which the
2504 AddOption('--prefix',
2506 nargs=1, type='string',
2509 help='installation prefix')
2510 env = Environment(PREFIX = GetOption('prefix'))
2513 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2515 .RI AddPostAction( target ", " action )
2517 .RI env.AddPostAction( target ", " action )
2518 Arranges for the specified
2524 The specified action(s) may be
2525 an Action object, or anything that
2526 can be converted into an Action object
2529 When multiple targets are supplied,
2530 the action may be called multiple times,
2531 once after each action that generates
2532 one or more targets in the list.
2534 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2536 .RI AddPreAction( target ", " action )
2538 .RI env.AddPreAction( target ", " action )
2539 Arranges for the specified
2542 before the specified
2545 The specified action(s) may be
2546 an Action object, or anything that
2547 can be converted into an Action object
2550 When multiple targets are specified,
2551 the action(s) may be called multiple times,
2552 once before each action that generates
2553 one or more targets in the list.
2555 Note that if any of the targets are built in multiple steps,
2556 the action will be invoked just
2557 before the "final" action that specifically
2558 generates the specified target(s).
2559 For example, when building an executable program
2560 from a specified source
2562 file via an intermediate object file:
2565 foo = Program('foo.c')
2566 AddPreAction(foo, 'pre_action')
2571 would be executed before
2573 calls the link command that actually
2574 generates the executable program binary
2576 not before compiling the
2578 file into an object file.
2580 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2582 .RI Alias( alias ", [" targets ", [" action ]])
2584 .RI env.Alias( alias ", [" targets ", [" action ]])
2585 Creates one or more phony targets that
2586 expand to one or more other targets.
2591 can be specified that will be executed
2592 whenever the any of the alias targets are out-of-date.
2593 Returns the Node object representing the alias,
2594 which exists outside of any file system.
2595 This Node object, or the alias name,
2596 may be used as a dependency of any other target,
2597 including another alias.
2599 can be called multiple times for the same
2600 alias to add additional targets to the alias,
2601 or additional actions to the list for this alias.
2607 Alias('install', '/usr/bin')
2608 Alias(['install', 'install-lib'], '/usr/local/lib')
2610 env.Alias('install', ['/usr/local/bin', '/usr/local/lib'])
2611 env.Alias('install', ['/usr/local/man'])
2613 env.Alias('update', ['file1', 'file2'], "update_database $SOURCES")
2616 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2618 .RI AllowSubstExceptions([ exception ", ...])"
2619 Specifies the exceptions that will be allowed
2620 when expanding construction variables.
2622 any construction variable expansions that generate a
2626 exception will expand to a
2628 (a null string) and not cause scons to fail.
2629 All exceptions not in the specified list
2630 will generate an error message
2631 and terminate processing.
2634 .B AllowSubstExceptions
2635 is called multiple times,
2636 each call completely overwrites the previous list
2637 of allowed exceptions.
2642 # Requires that all construction variable names exist.
2643 # (You may wish to do this if you want to enforce strictly
2644 # that all construction variables must be defined before use.)
2645 AllowSubstExceptions()
2647 # Also allow a string containing a zero-division expansion
2648 # like '${1 / 0}' to evalute to ''.
2649 AllowSubstExceptions(IndexError, NameError, ZeroDivisionError)
2652 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2654 .RI AlwaysBuild( target ", ...)"
2656 .RI env.AlwaysBuild( target ", ...)"
2659 so that it is always assumed to be out of date,
2660 and will always be rebuilt if needed.
2663 does not add its target(s) to the default target list,
2664 so the targets will only be built
2665 if they are specified on the command line,
2666 or are a dependent of a target specified on the command line--but
2669 be built if so specified.
2670 Multiple targets can be passed in to a single call to
2673 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2675 .RI env.Append( key = val ", [...])"
2676 Appends the specified keyword arguments
2677 to the end of construction variables in the environment.
2678 If the Environment does not have
2679 the specified construction variable,
2680 it is simply added to the environment.
2681 If the values of the construction variable
2682 and the keyword argument are the same type,
2683 then the two values will be simply added together.
2684 Otherwise, the construction variable
2685 and the value of the keyword argument
2686 are both coerced to lists,
2687 and the lists are added together.
2688 (See also the Prepend method, below.)
2693 env.Append(CCFLAGS = ' -g', FOO = ['foo.yyy'])
2696 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2698 .RI env.AppendENVPath( name ", " newpath ", [" envname ", " sep ", " delete_existing ])
2699 This appends new path elements to the given path in the
2700 specified external environment
2704 any particular path once (leaving the last one it encounters and
2705 ignoring the rest, to preserve path order),
2706 and to help assure this,
2707 will normalize all paths (using
2710 .BR os.path.normcase ).
2711 This can also handle the
2712 case where the given old path variable is a list instead of a
2713 string, in which case a list will be returned instead of a string.
2717 is 0, then adding a path that already exists
2718 will not move it to the end; it will stay where it is in the list.
2723 print 'before:',env['ENV']['INCLUDE']
2724 include_path = '/foo/bar:/foo'
2725 env.AppendENVPath('INCLUDE', include_path)
2726 print 'after:',env['ENV']['INCLUDE']
2730 after: /biz:/foo/bar:/foo
2733 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2735 .RI env.AppendUnique( key = val ", [...], delete_existing=0)"
2736 Appends the specified keyword arguments
2737 to the end of construction variables in the environment.
2738 If the Environment does not have
2739 the specified construction variable,
2740 it is simply added to the environment.
2741 If the construction variable being appended to is a list,
2742 then any value(s) that already exist in the
2743 construction variable will
2745 be added again to the list.
2746 However, if delete_existing is 1,
2747 existing matching values are removed first, so
2748 existing values in the arg list move to the end of the list.
2753 env.AppendUnique(CCFLAGS = '-g', FOO = ['foo.yyy'])
2756 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2759 A factory function that
2760 returns a Builder object
2761 to be used to fetch source files
2763 The returned Builder
2764 is intended to be passed to the
2771 env.SourceCode('.', env.BitKeeper())
2774 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2776 .RI BuildDir( build_dir ", " src_dir ", [" duplicate ])
2778 .RI env.BuildDir( build_dir ", " src_dir ", [" duplicate ])
2779 Deprecated synonyms for
2782 .BR env.VariantDir ().
2785 argument becomes the
2790 .BR env.VariantDir ().
2792 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2794 .RI Builder( action ", [" arguments ])
2796 .RI env.Builder( action ", [" arguments ])
2797 Creates a Builder object for
2800 See the section "Builder Objects,"
2801 below, for a complete explanation of the arguments and behavior.
2805 form of the invocation will expand
2806 construction variables in any arguments strings,
2810 at the time it is called
2811 using the construction variables in the
2813 construction environment through which
2818 form delays all variable expansion
2819 until after the Builder object is actually called.
2821 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2823 .RI CacheDir( cache_dir )
2825 .RI env.CacheDir( cache_dir )
2828 will maintain a cache of derived files in
2830 The derived files in the cache will be shared
2831 among all the builds using the same
2838 disables derived file caching.
2842 will only affect targets built
2843 through the specified construction environment.
2846 sets a global default
2847 that will be used by all targets built
2848 through construction environments
2859 finds a derived file that needs to be rebuilt,
2860 it will first look in the cache to see if a
2861 derived file has already been built
2862 from identical input files and an identical build action
2863 (as incorporated into the MD5 build signature).
2866 will retrieve the file from the cache.
2867 If the derived file is not present in the cache,
2870 then place a copy of the built file in the cache
2871 (identified by its MD5 build signature),
2872 so that it may be retrieved by other
2873 builds that need to build the same derived file
2874 from identical inputs.
2878 may be disabled for any invocation
2887 will place a copy of
2889 derived files in the cache,
2890 even if they already existed
2891 and were not built by this invocation.
2892 This is useful to populate a cache
2895 is added to a build,
2904 "Retrieved `file' from cache,"
2907 option is being used.
2912 will print the action that
2914 have been used to build the file,
2915 without any indication that
2916 the file was actually retrieved from the cache.
2917 This is useful to generate build logs
2918 that are equivalent regardless of whether
2919 a given derived file has been built in-place
2920 or retrieved from the cache.
2924 method can be used to disable caching of specific files. This can be
2925 useful if inputs and/or outputs of some tool are impossible to
2926 predict or prohibitively large.
2928 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2930 .RI Clean( targets ", " files_or_dirs )
2932 .RI env.Clean( targets ", " files_or_dirs )
2933 This specifies a list of files or directories which should be removed
2934 whenever the targets are specified with the
2936 command line option.
2937 The specified targets may be a list
2938 or an individual target.
2942 and create new targets or add files and directories to the
2943 clean list for the specified targets.
2945 Multiple files or directories should be specified
2946 either as separate arguments to the
2948 method, or as a list.
2950 will also accept the return value of any of the construction environment
2956 function overrides calling
2958 for the same target,
2959 and any targets passed to both functions will
2968 Clean('foo', ['bar', 'baz'])
2969 Clean('dist', env.Program('hello', 'hello.c'))
2970 Clean(['foo', 'bar'], 'something_else_to_clean')
2973 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2975 .RI Command( target ", " source ", " action ", [" key = val ", ...])"
2977 .RI env.Command( target ", " source ", " action ", [" key = val ", ...])"
2978 Executes a specific action
2979 (or list of actions)
2980 to build a target file or files.
2981 This is more convenient
2982 than defining a separate Builder object
2983 for a single special-case build.
2985 As a special case, the
2987 keyword argument can
2990 that will be used to scan the sources.
2994 if any of the sources will be directories
2995 that must be scanned on-disk for
2996 changes to files that aren't
2997 already specified in other Builder of function calls.)
2999 Any other keyword arguments specified override any
3000 same-named existing construction variables.
3002 An action can be an external command,
3003 specified as a string,
3004 or a callable Python object;
3005 see "Action Objects," below,
3006 for more complete information.
3007 Also note that a string specifying an external command
3008 may be preceded by an
3011 to suppress printing the command in question,
3015 to ignore the exit status of the external command.
3020 env.Command('foo.out', 'foo.in',
3021 "$FOO_BUILD < $SOURCES > $TARGET")
3023 env.Command('bar.out', 'bar.in',
3025 "$BAR_BUILD < $SOURCES > $TARGET"],
3026 ENV = {'PATH' : '/usr/local/bin/'})
3028 def rename(env, target, source):
3030 os.rename('.tmp', str(target[0]))
3032 env.Command('baz.out', 'baz.in',
3033 ["$BAZ_BUILD < $SOURCES > .tmp",
3040 function will usually assume, by default,
3041 that the specified targets and/or sources are Files,
3042 if no other part of the configuration
3043 identifies what type of entry it is.
3044 If necessary, you can explicitly specify
3045 that targets or source nodes should
3046 be treated as directoriese
3056 env.Command('ddd.list', Dir('ddd'), 'ls -l $SOURCE > $TARGET')
3058 env['DISTDIR'] = 'destination/directory'
3059 env.Command(env.Dir('$DISTDIR')), None, make_distdir)
3063 (Also note that SCons will usually
3064 automatically create any directory necessary to hold a target file,
3065 so you normally don't need to create directories by hand.)
3067 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3069 .RI Configure( env ", [" custom_tests ", " conf_dir ", " log_file ", " config_h ])
3071 .RI env.Configure([ custom_tests ", " conf_dir ", " log_file ", " config_h ])
3072 Creates a Configure object for integrated
3073 functionality similar to GNU autoconf.
3074 See the section "Configure Contexts,"
3075 below, for a complete explanation of the arguments and behavior.
3077 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3079 .RI env.Clone([ key = val ", ...])"
3080 Return a separate copy of a construction environment.
3081 If there are any keyword arguments specified,
3082 they are added to the returned copy,
3083 overwriting any existing values
3090 env3 = env.Clone(CCFLAGS = '-g')
3093 Additionally, a list of tools and a toolpath may be specified, as in
3094 the Environment constructor:
3097 def MyTool(env): env['FOO'] = 'bar'
3098 env4 = env.Clone(tools = ['msvc', MyTool])
3103 keyword argument is also recognized:
3106 # create an environment for compiling programs that use wxWidgets
3107 wx_env = env.Clone(parse_flags = '!wx-config --cflags --cxxflags')
3110 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3112 .RI env.Copy([ key = val ", ...])"
3113 A now-deprecated synonym for
3116 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3118 .RI env.CVS( repository ", " module )
3119 A factory function that
3120 returns a Builder object
3121 to be used to fetch source files
3125 The returned Builder
3126 is intended to be passed to the
3130 The optional specified
3132 will be added to the beginning
3133 of all repository path names;
3134 this can be used, in essence,
3135 to strip initial directory names
3136 from the repository path names,
3137 so that you only have to
3138 replicate part of the repository
3139 directory hierarchy in your
3140 local build directory.
3145 # Will fetch foo/bar/src.c
3146 # from /usr/local/CVSROOT/foo/bar/src.c.
3147 env.SourceCode('.', env.CVS('/usr/local/CVSROOT'))
3149 # Will fetch bar/src.c
3150 # from /usr/local/CVSROOT/foo/bar/src.c.
3151 env.SourceCode('.', env.CVS('/usr/local/CVSROOT', 'foo'))
3154 # from /usr/local/CVSROOT/foo/bar/src.c.
3155 env.SourceCode('.', env.CVS('/usr/local/CVSROOT', 'foo/bar'))
3158 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3160 .RI Decider( function )
3162 .RI env.Decider( function )
3163 Specifies that all up-to-date decisions for
3164 targets built through this construction environment
3165 will be handled by the specified
3169 can be one of the following strings
3170 that specify the type of decision function
3176 Specifies that a target shall be considered out of date and rebuilt
3177 if the dependency's timestamp is newer than the target file's timestamp.
3178 This is the behavior of the classic Make utility,
3181 can be used a synonym for
3182 .BR timestamp-newer .
3186 Specifies that a target shall be considered out of date and rebuilt
3187 if the dependency's timestamp is different than the
3188 timestamp recorded the last time the target was built.
3189 This provides behavior very similar to the classic Make utility
3190 (in particular, files are not opened up so that their
3191 contents can be checksummed)
3192 except that the target will also be rebuilt if a
3193 dependency file has been restored to a version with an
3195 timestamp, such as can happen when restoring files from backup archives.
3199 Specifies that a target shall be considered out of date and rebuilt
3200 if the dependency's content has changed sine the last time
3201 the target was built,
3202 as determined be performing an MD5 checksum
3203 on the dependency's contents
3204 and comparing it to the checksum recorded the
3205 last time the target was built.
3207 can be used as a synonym for
3212 Specifies that a target shall be considered out of date and rebuilt
3213 if the dependency's content has changed sine the last time
3214 the target was built,
3215 except that dependencies with a timestamp that matches
3216 the last time the target was rebuilt will be
3217 assumed to be up-to-date and
3220 This provides behavior very similar
3223 behavior of always checksumming file contents,
3224 with an optimization of not checking
3225 the contents of files whose timestamps haven't changed.
3226 The drawback is that SCons will
3228 detect if a file's content has changed
3229 but its timestamp is the same,
3230 as might happen in an automated script
3233 and runs the build again,
3234 all within a single second.
3241 # Use exact timestamp matches by default.
3242 Decider('timestamp-match')
3244 # Use MD5 content signatures for any targets built
3245 # with the attached construction environment.
3246 env.Decider('content')
3250 In addition to the above already-available functions,
3253 argument may be an actual Python function
3254 that takes the following three arguments:
3258 The Node (file) which
3262 if it has "changed" since the last tme
3263 .I target was built.
3266 The Node (file) being built.
3268 this is what should get rebuilt
3274 Stored information about the state of the
3279 This can be consulted to match various
3280 file characteristics
3281 such as the timestamp,
3282 size, or content signature.
3293 has "changed" since the last time
3297 (indicating that the target
3304 (indicating that the target should
3307 Note that the decision can be made
3308 using whatever criteria are appopriate.
3309 Ignoring some or all of the function arguments
3310 is perfectly normal.
3315 def my_decider(dependency, target, prev_ni):
3316 return not os.path.exists(str(target))
3318 env.Decider(my_decider)
3321 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3323 .RI Default( targets )
3325 .RI env.Default( targets )
3326 This specifies a list of default targets,
3327 which will be built by
3329 if no explicit targets are given on the command line.
3333 and add to the list of default targets.
3335 Multiple targets should be specified as
3336 separate arguments to the
3338 method, or as a list.
3340 will also accept the Node returned by any
3341 of a construction environment's
3347 Default('foo', 'bar', 'baz')
3348 env.Default(['a', 'b', 'c'])
3349 hello = env.Program('hello', 'hello.c')
3357 will clear all default targets.
3360 will add to the (now empty) default-target list
3363 The current list of targets added using the
3365 function or method is available in the
3370 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3372 .RI DefaultEnvironment([ args ])
3373 Creates and returns a default construction environment object.
3374 This construction environment is used internally by SCons
3375 in order to execute many of the global functions in this list,
3376 and to fetch source files transparently
3377 from source code management systems.
3379 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3381 .RI Depends( target ", " dependency )
3383 .RI env.Depends( target ", " dependency )
3384 Specifies an explicit dependency;
3396 (usually the path name of a file or directory)
3398 or a list of strings or Node objects
3399 (such as returned by a Builder call).
3400 This should only be necessary
3401 for cases where the dependency
3402 is not caught by a Scanner
3408 env.Depends('foo', 'other-input-file-for-foo')
3410 mylib = env.Library('mylib.c')
3411 installed_lib = env.Install('lib', mylib)
3412 bar = env.Program('bar.c')
3414 # Arrange for the library to be copied into the installation
3415 # directory before trying to build the "bar" program.
3416 # (Note that this is for example only. A "real" library
3417 # dependency would normally be configured through the $LIBS
3418 # and $LIBPATH variables, not using an env.Depends() call.)
3420 env.Depends(bar, installed_lib)
3423 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3425 .RI env.Dictionary([ vars ])
3426 Returns a dictionary object
3427 containing copies of all of the
3428 construction variables in the environment.
3429 If there are any variable names specified,
3430 only the specified construction
3431 variables are returned in the dictionary.
3436 dict = env.Dictionary()
3437 cc_dict = env.Dictionary('CC', 'CCFLAGS', 'CCCOM')
3440 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3442 .RI Dir( name ", [" directory ])
3444 .RI env.Dir( name ", [" directory ])
3445 This returns a Directory Node,
3446 an object that represents the specified directory
3449 can be a relative or absolute path.
3451 is an optional directory that will be used as the parent directory.
3454 is specified, the current script's directory is used as the parent.
3458 is a list, SCons returns a list of Dir nodes.
3459 Construction variables are expanded in
3462 Directory Nodes can be used anywhere you
3463 would supply a string as a directory name
3464 to a Builder method or function.
3465 Directory Nodes have attributes and methods
3466 that are useful in many situations;
3467 see "File and Directory Nodes," below.
3469 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3471 .RI env.Dump([ key ])
3472 Returns a pretty printable representation of the environment.
3476 should be a string containing the name of the variable of interest.
3481 print env.Dump('CCCOM')
3486 \&'$CC $CCFLAGS $CPPFLAGS $_CPPDEFFLAGS $_CPPINCFLAGS -c -o $TARGET $SOURCES'
3497 'ARCOM': '$AR $ARFLAGS $TARGET $SOURCES\n$RANLIB $RANLIBFLAGS $TARGET',
3500 'ASCOM': '$AS $ASFLAGS -o $TARGET $SOURCES',
3505 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3507 .RI EnsurePythonVersion( major ", " minor )
3509 .RI env.EnsurePythonVersion( major ", " minor )
3510 Ensure that the Python version is at least
3513 print out an error message and exit SCons with a non-zero exit code if the
3514 actual Python version is not late enough.
3519 EnsurePythonVersion(2,2)
3522 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3524 .RI EnsureSConsVersion( major ", " minor ", [" revision ])
3526 .RI env.EnsureSConsVersion( major ", " minor ", [" revision ])
3527 Ensure that the SCons version is at least
3530 .IR major.minor.revision .
3535 print out an error message and exit SCons with a non-zero exit code if the
3536 actual SCons version is not late enough.
3541 EnsureSConsVersion(0,14)
3543 EnsureSConsVersion(0,96,90)
3546 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3548 .RI Environment([ key = value ", ...])"
3550 .RI env.Environment([ key = value ", ...])"
3551 Return a new construction environment
3552 initialized with the specified
3556 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3558 .RI Execute( action ", [" strfunction ", " varlist ])
3560 .RI env.Execute( action ", [" strfunction ", " varlist ])
3561 Executes an Action object.
3564 may be an Action object
3565 (see the section "Action Objects,"
3566 below, for a complete explanation of the arguments and behavior),
3567 or it may be a command-line string,
3569 or executable Python function,
3570 each of which will be converted
3571 into an Action object
3573 The exit value of the command
3574 or return value of the Python function
3579 will print an error message if the executed
3582 exits with or returns a non-zero value.
3587 automatically terminate the build
3591 If you want the build to stop in response to a failed
3594 you must explicitly check for a non-zero return value:
3597 Execute(Copy('file.out', 'file.in'))
3599 if Execute("mkdir sub/dir/ectory"):
3600 # The mkdir failed, don't try to build.
3604 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3608 .RI env.Exit([ value ])
3614 A default exit value of
3617 is used if no value is specified.
3619 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3623 .RI env.Export( vars )
3626 to export a list of variables from the current
3627 SConscript file to all other SConscript files.
3628 The exported variables are kept in a global collection,
3629 so subsequent calls to
3631 will over-write previous exports that have the same name.
3632 Multiple variable names can be passed to
3634 as separate arguments or as a list. A dictionary can be used to map
3635 variables to a different name when exported. Both local variables and
3636 global variables can be exported.
3642 # Make env available for all SConscript files to Import().
3646 # Make env and package available for all SConscript files:.
3647 Export("env", "package")
3649 # Make env and package available for all SConscript files:
3650 Export(["env", "package"])
3652 # Make env available using the name debug:.
3653 Export({"debug":env})
3659 function supports an
3661 argument that makes it easier to to export a variable or
3662 set of variables to a single SConscript file.
3663 See the description of the
3667 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3669 .RI File( name ", [" directory ])
3671 .RI env.File( name ", [" directory ])
3674 an object that represents the specified file
3677 can be a relative or absolute path.
3679 is an optional directory that will be used as the parent directory.
3683 is a list, SCons returns a list of File nodes.
3684 Construction variables are expanded in
3687 File Nodes can be used anywhere you
3688 would supply a string as a file name
3689 to a Builder method or function.
3690 File Nodes have attributes and methods
3691 that are useful in many situations;
3692 see "File and Directory Nodes," below.
3694 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3696 .RI FindFile( file ", " dirs )
3698 .RI env.FindFile( file ", " dirs )
3701 in the path specified by
3704 may be a list of directory names or a single directory name.
3705 In addition to searching for files that exist in the filesytem,
3706 this function also searches for derived files
3707 that have not yet been built.
3712 foo = env.FindFile('foo', ['dir1', 'dir2'])
3715 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3717 .RI FindInstalledFiles( )
3719 .RI env.FindInstalledFiles( )
3720 Returns the list of targets set up by the
3726 This function serves as a convenient method to select the contents of
3732 Install( '/bin', [ 'executable_a', 'executable_b' ] )
3734 # will return the file node list
3735 # [ '/bin/executable_a', '/bin/executable_b' ]
3736 FindInstalledFiles()
3738 Install( '/lib', [ 'some_library' ] )
3740 # will return the file node list
3741 # [ '/bin/executable_a', '/bin/executable_b', '/lib/some_library' ]
3742 FindInstalledFiles()
3745 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3747 .RI FindSourceFiles( node = '"."' )
3749 .RI env.FindSourceFiles( node = '"."' )
3751 Returns the list of nodes which serve as the source of the built files.
3752 It does so by inspecting the dependency tree starting at the optional
3755 which defaults to the '"."'-node. It will then return all leaves of
3757 These are all children which have no further children.
3759 This function is a convenient method to select the contents of a Source
3765 Program( 'src/main_a.c' )
3766 Program( 'src/main_b.c' )
3767 Program( 'main_c.c' )
3769 # returns ['main_c.c', 'src/main_a.c', 'SConstruct', 'src/main_b.c']
3772 # returns ['src/main_b.c', 'src/main_a.c' ]
3773 FindSourceFiles( 'src' )
3777 As you can see build support files (SConstruct in the above example)
3778 will also be returned by this function.
3780 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3782 .RI FindPathDirs( variable )
3784 (actually a callable Python object)
3785 intended to be used as the
3787 of a Scanner object.
3788 The returned object will look up the specified
3790 in a construction environment
3791 and treat the construction variable's value as a list of
3792 directory paths that should be searched
3800 is generally preferable to
3803 for the following reasons:
3804 1) The returned list will contain all appropriate directories
3805 found in source trees
3809 or in code repositories
3815 2) scons will identify expansions of
3817 that evaluate to the same list of directories as,
3818 in fact, the same list,
3819 and avoid re-scanning the directories for files,
3825 def my_scan(node, env, path, arg):
3826 # Code to scan file contents goes here...
3827 return include_files
3829 scanner = Scanner(name = 'myscanner',
3831 path_function = FindPathDirs('MYPATH'))
3834 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3836 .RI Flatten( sequence )
3838 .RI env.Flatten( sequence )
3839 Takes a sequence (that is, a Python list or tuple)
3840 that may contain nested sequences
3841 and returns a flattened list containing
3842 all of the individual elements in any sequence.
3843 This can be helpful for collecting
3844 the lists returned by calls to Builders;
3845 other Builders will automatically
3846 flatten lists specified as input,
3847 but direct Python manipulation of
3848 these lists does not.
3853 foo = Object('foo.c')
3854 bar = Object('bar.c')
3856 # Because `foo' and `bar' are lists returned by the Object() Builder,
3857 # `objects' will be a list containing nested lists:
3858 objects = ['f1.o', foo, 'f2.o', bar, 'f3.o']
3860 # Passing such a list to another Builder is all right because
3861 # the Builder will flatten the list automatically:
3862 Program(source = objects)
3864 # If you need to manipulate the list directly using Python, you need to
3865 # call Flatten() yourself, or otherwise handle nested lists:
3866 for object in Flatten(objects):
3870 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3872 .RI GetBuildFailures()
3873 Returns a list of exceptions for the
3874 actions that failed while
3875 attempting to build targets.
3876 Each element in the returned list is a
3879 with the following attributes
3880 that record various aspects
3881 of the build failure:
3884 The node that was being built
3885 when the build failure occurred.
3888 The numeric exit status
3889 returned by the command or Python function
3890 that failed when trying to build the
3894 The SCons error string
3895 describing the build failure.
3896 (This is often a generic
3897 message like "Error 2"
3898 to indicate that an executed
3899 command exited with a status of 2.)
3902 The name of the file or
3903 directory that actually caused the failure.
3904 This may be different from the
3908 if an attempt to build a target named
3912 directory could not be created,
3923 The SCons Executor object
3926 This can be used to retrieve
3927 the construction environment used
3928 for the failed action.
3931 The actual SCons Action object that failed.
3932 This will be one specific action
3933 out of the possible list of
3934 actions that would have been
3935 executed to build the target.
3938 The actual expanded command that was executed and failed,
3942 and other construction variables.
3945 .BR GetBuildFailures ()
3947 will always return an empty list
3948 until any build failure has occurred,
3950 .BR GetBuildFailures ()
3951 will always return an empty list
3954 files are being read.
3955 Its primary intended use is
3956 for functions that will be
3957 executed before SCons exits
3958 by passing them to the
3960 .BR atexit.register ()
3967 def print_build_failures():
3968 from SCons.Script import GetBuildFailures
3969 for bf in GetBuildFailures():
3970 print "%s failed: %s" % (bf.node, bf.errstr)
3972 atexit.register(print_build_failures)
3975 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3977 .RI GetBuildPath( file ", [" ... ])
3979 .RI env.GetBuildPath( file ", [" ... ])
3982 path name (or names) for the specified
3990 Nodes or strings representing path names.
3992 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3996 .RI env.GetLaunchDir()
3997 Returns the absolute path name of the directory from which
3999 was initially invoked.
4000 This can be useful when using the
4005 options, which internally
4006 change to the directory in which the
4010 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4012 .RI GetOption( name )
4014 .RI env.GetOption( name )
4015 This function provides a way to query the value of
4016 SCons options set on scons command line
4020 The options supported are:
4025 which corresponds to --cache-debug;
4028 which corresponds to --cache-disable;
4031 which corresponds to --cache-force;
4034 which corresponds to --cache-show;
4037 which corresponds to -c, --clean and --remove;
4040 which corresponds to --config;
4043 which corresponds to -C and --directory;
4046 which corresponds to --diskcheck
4049 which corresponds to --duplicate;
4052 which corresponds to -f, --file, --makefile and --sconstruct;
4055 which corresponds to -h and --help;
4058 which corresponds to --ignore-errors;
4061 which corresponds to --implicit-cache;
4063 .B implicit_deps_changed
4064 which corresponds to --implicit-deps-changed;
4066 .B implicit_deps_unchanged
4067 which corresponds to --implicit-deps-unchanged;
4070 which corresponds to --interact and --interactive;
4073 which corresponds to -k and --keep-going;
4076 which corresponds to --max-drift;
4079 which corresponds to -n, --no-exec, --just-print, --dry-run and --recon;
4082 which corresponds to --no-site-dir;
4085 which corresponds to -j and --jobs;
4088 which corresponds to --profile;
4091 which corresponds to -q and --question;
4094 which corresponds to --random;
4097 which corresponds to -Y, --repository and --srcdir;
4100 which corresponds to -s, --silent and --quiet;
4103 which corresponds to --site-dir;
4106 which corresponds to --stack-size;
4108 .B taskmastertrace_file
4109 which corresponds to --taskmastertrace; and
4112 which corresponds to --warn and --warning.
4116 See the documentation for the
4117 corresponding command line object for information about each specific
4120 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4122 .RI Glob( pattern ", [" ondisk ", " source ", " strings ])
4124 .RI env.Glob( pattern ", [" ondisk ", " source ", " strings ])
4125 Returns Nodes (or strings) that match the specified
4127 relative to the directory of the current
4132 form performs string substition on
4134 and returns whatever matches
4135 the resulting expanded pattern.
4139 uses Unix shell style metacharacters for matching:
4142 * matches everything
4143 ? matches any single character
4144 [seq] matches any character in seq
4145 [!seq] matches any char not in seq
4149 Character matches do
4151 span directory separators.
4160 and source directories
4165 returns a Node (or string, if so configured)
4166 in the local (SConscript) directory
4167 if matching Node is found
4168 anywhere in a corresponding
4169 repository or source directory.
4173 argument may be set to
4175 (or any other non-true value)
4176 to disable the search for matches on disk,
4177 thereby only returning matches among
4178 already-configured File or Dir Nodes.
4179 The default behavior is to
4180 return corresponding Nodes
4181 for any on-disk matches found.
4185 argument may be set to
4187 (or any equivalent value)
4189 when the local directory is a
4191 the returned Nodes should be from the
4192 corresponding source directory,
4193 not the local directory.
4197 argument may be set to
4199 (or any equivalent value)
4202 function return strings, not Nodes,
4203 that represent the matched files or directories.
4204 The returned strings will be relative to
4205 the local (SConscript) directory.
4206 (Note that This may make it easier to perform
4207 arbitrary manipulation of file names,
4208 but if the returned strings are
4209 passed to a different
4212 any Node translation will be relative
4223 Program('foo', Glob('*.c'))
4226 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4228 '\".RI GlobalBuilders( flag )
4232 '\"adds the names of the default builders
4233 '\"(Program, Library, etc.)
4234 '\"to the global name space
4235 '\"so they can be called without an explicit construction environment.
4236 '\"(This is the default.)
4240 '\"the names of the default builders are removed
4241 '\"from the global name space
4242 '\"so that an explicit construction environment is required
4243 '\"to call all builders.
4245 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4249 .RI env.Help( text )
4250 This specifies help text to be printed if the
4252 argument is given to
4256 is called multiple times, the text is appended together in the order
4261 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4263 .RI Ignore( target ", " dependency )
4265 .RI env.Ignore( target ", " dependency )
4266 The specified dependency file(s)
4267 will be ignored when deciding if
4268 the target file(s) need to be rebuilt.
4272 to remove a target from the default build.
4273 In order to do this you must specify the directory the target will
4274 be built in as the target, and the file you want to skip building
4277 Note that this will only remove the dependencies listed from
4278 the files built by default. It will still be built if that
4279 dependency is needed by another object being built.
4280 See the third and forth examples below.
4285 env.Ignore('foo', 'foo.c')
4286 env.Ignore('bar', ['bar1.h', 'bar2.h'])
4287 env.Ignore('.','foobar.obj')
4288 env.Ignore('bar','bar/foobar.obj')
4291 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4295 .RI env.Import( vars )
4298 to import a list of variables into the current SConscript file. This
4299 will import variables that were exported with
4305 Variables exported by
4308 Multiple variable names can be passed to
4310 as separate arguments or as a list. The variable "*" can be used
4311 to import all variables.
4317 Import("env", "variable")
4318 Import(["env", "variable"])
4322 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4324 .RI Literal( string )
4326 .RI env.Literal( string )
4329 will be preserved as-is
4330 and not have construction variables expanded.
4332 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4334 .RI Local( targets )
4336 .RI env.Local( targets )
4339 will have copies made in the local tree,
4340 even if an already up-to-date copy
4341 exists in a repository.
4342 Returns a list of the target Node or Nodes.
4344 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4346 \" .RI env.MergeShellPaths( arg ", [" prepend ])
4347 \" Merges the elements of the specified
4349 \" which must be a dictionary, to the construction
4350 \" environment's copy of the shell environment
4352 \" (This is the environment which is passed
4353 \" to subshells spawned by SCons.)
4356 \" must be a single value,
4357 \" so multiple strings must
4358 \" be passed in as a list,
4359 \" not as separate arguments to
4360 \" .BR env.MergeShellPaths ().
4362 \" New values are prepended to the environment variable by default,
4363 \" unless prepend=0 is specified.
4364 \" Duplicate values are always eliminated,
4365 \" since this function calls
4368 \" .B PrependENVPath
4371 \" argument. See those functions for more details.
4376 \" # Prepend a path to the shell PATH.
4377 \" env.MergeShellPaths({'PATH':'/usr/local/bin'} )
4378 \" # Append two dirs to the shell INCLUDE.
4379 \" env.MergeShellPaths({'INCLUDE':['c:/inc1', 'c:/inc2']}, prepend=0 )
4383 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4385 .RI env.MergeFlags( arg ", [" unique ])
4386 Merges the specified
4388 values to the construction environment's construction variables.
4391 argument is not a dictionary,
4392 it is converted to one by calling
4395 before the values are merged.
4398 must be a single value,
4399 so multiple strings must
4400 be passed in as a list,
4401 not as separate arguments to
4402 .BR env.MergeFlags ().
4405 duplicate values are eliminated;
4406 you can, however, specify
4410 When eliminating duplicate values,
4411 any construction variables that end with
4414 keep the left-most unique value.
4415 All other construction variables keep
4416 the right-most unique value.
4421 # Add an optimization flag to $CCFLAGS.
4422 env.MergeFlags('-O3')
4424 # Combine the flags returned from running pkg-config with an optimization
4425 # flag and merge the result into the construction variables.
4426 env.MergeFlags(['!pkg-config gtk+-2.0 --cflags', '-O3'])
4428 # Combine an optimization flag with the flags returned from running pkg-config
4429 # twice and merge the result into the construction variables.
4430 env.MergeFlags(['-O3',
4431 '!pkg-config gtk+-2.0 --cflags --libs',
4432 '!pkg-config libpng12 --cflags --libs'])
4435 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4437 .RI NoCache( target ", ...)"
4439 .RI env.NoCache( target ", ...)"
4440 Specifies a list of files which should
4442 be cached whenever the
4444 method has been activated.
4445 The specified targets may be a list
4446 or an individual target.
4448 Multiple files should be specified
4449 either as separate arguments to the
4451 method, or as a list.
4453 will also accept the return value of any of the construction environment
4458 on directories and other non-File Node types has no effect because
4459 only File Nodes are cached.
4465 NoCache(env.Program('hello', 'hello.c'))
4468 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4470 .RI NoClean( target ", ...)"
4472 .RI env.NoClean( target ", ...)"
4473 Specifies a list of files or directories which should
4475 be removed whenever the targets (or their dependencies)
4476 are specified with the
4478 command line option.
4479 The specified targets may be a list
4480 or an individual target.
4484 and prevent each specified target
4485 from being removed by calls to the
4489 Multiple files or directories should be specified
4490 either as separate arguments to the
4492 method, or as a list.
4494 will also accept the return value of any of the construction environment
4499 for a target overrides calling
4501 for the same target,
4502 and any targets passed to both functions will
4512 NoClean(env.Program('hello', 'hello.c'))
4515 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4517 .RI env.ParseConfig( command ", [" function ", " unique ])
4520 to modify the environment as specified by the output of
4525 .BR env.MergeFlags (),
4526 which expects the output of a typical
4530 and adds the options
4531 to the appropriate construction variables.
4533 duplicate values are not
4534 added to any construction variables;
4541 and the construction variables they affect
4542 are as specified for the
4543 .BR env.ParseFlags ()
4544 method (which this method calls).
4545 See that method's description, below,
4546 for a table of options and construction variables.
4548 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4550 .RI ParseDepends( filename ", [" must_exist ", " only_one ])
4552 .RI env.ParseDepends( filename ", [" must_exist ", " only_one ])
4553 Parses the contents of the specified
4555 as a list of dependencies in the style of
4559 and explicitly establishes all of the listed dependencies.
4568 argument may be set to a non-zero
4571 throw an exception and
4572 generate an error if the file does not exist,
4573 or is otherwise inaccessible.
4577 argument may be set to a non-zero
4580 thrown an exception and
4582 if the file contains dependency
4583 information for more than one target.
4584 This can provide a small sanity check
4585 for files intended to be generated
4586 by, for example, the
4589 which should typically only
4590 write dependency information for
4591 one output file into a corresponding
4597 and all of the files listed therein
4598 will be interpreted relative to
4599 the directory of the
4601 file which calls the
4605 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4607 .RI env.ParseFlags( flags ", ...)"
4608 Parses one or more strings containing
4609 typical command-line flags for GCC tool chains
4610 and returns a dictionary with the flag values
4611 separated into the appropriate SCons construction variables.
4612 This is intended as a companion to the
4613 .BR env.MergeFlags ()
4614 method, but allows for the values in the returned dictionary
4615 to be modified, if necessary,
4616 before merging them into the construction environment.
4618 .BR env.MergeFlags ()
4619 will call this method if its argument is not a dictionary,
4620 so it is usually not necessary to call
4621 .BR env.ParseFlags ()
4622 directly unless you want to manipulate the values.)
4624 If the first character in any string is
4625 an exclamation mark (!),
4626 the rest of the string is executed as a command,
4627 and the output from the command is
4628 parsed as GCC tool chain command-line flags
4629 and added to the resulting dictionary.
4631 Flag values are translated accordig to the prefix found,
4632 and added to the following construction variables:
4635 -arch CCFLAGS, LINKFLAGS
4637 -framework FRAMEWORKS
4638 -frameworkdir= FRAMEWORKPATH
4640 -isysroot CCFLAGS, LINKFLAGS
4644 -mno-cygwin CCFLAGS, LINKFLAGS
4646 -pthread CCFLAGS, LINKFLAGS
4648 -Wa, ASFLAGS, CCFLAGS
4655 + CCFLAGS, LINKFLAGS
4659 Any other strings not associated with options
4660 are assumed to be the names of libraries
4663 construction variable.
4665 Examples (all of which produce the same result):
4668 dict = env.ParseFlags('-O2 -Dfoo -Dbar=1')
4669 dict = env.ParseFlags('-O2', '-Dfoo', '-Dbar=1')
4670 dict = env.ParseFlags(['-O2', '-Dfoo -Dbar=1'])
4671 dict = env.ParseFlags('-O2', '!echo -Dfoo -Dbar=1')
4674 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4677 A factory function that
4678 returns a Builder object
4679 to be used to fetch source files
4680 from the Perforce source code management system.
4681 The returned Builder
4682 is intended to be passed to the
4689 env.SourceCode('.', env.Perforce())
4692 Perforce uses a number of external
4693 environment variables for its operation.
4694 Consequently, this function adds the
4695 following variables from the user's external environment
4696 to the construction environment's
4709 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4711 .RI Platform( string )
4712 Returns a callable object
4713 that can be used to initialize
4714 a construction environment using the
4715 platform keyword of the Environment() method.
4720 env = Environment(platform = Platform('win32'))
4723 .RI env.Platform( string )
4724 Applies the callable object for the specified platform
4726 to the environment through which the method was called.
4729 env.Platform('posix')
4738 variables from the user's external environment
4739 to the construction environment's
4742 This is so that any executed commands
4743 that use sockets to connect with other systems
4744 (such as fetching source files from
4745 external CVS repository specifications like
4746 .BR :pserver:anonymous@cvs.sourceforge.net:/cvsroot/scons )
4747 will work on Windows systems.
4749 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4751 .RI Progress( callable ", [" interval ])
4753 .RI Progress( string ", [" interval ", " file ", " overwrite ])
4755 .RI Progress( list_of_strings ", [" interval ", " file ", " overwrite ])
4756 Allows SCons to show progress made during the build
4757 by displaying a string or calling a function while
4758 evaluating Nodes (e.g. files).
4760 If the first specified argument is a Python callable
4761 (a function or an object that has a
4764 the function will be called
4767 times a Node is evaluated.
4768 The callable will be passed the evaluated Node
4769 as its only argument.
4770 (For future compatibility,
4771 it's a good idea to also add
4775 as arguments to your function or method.
4776 This will prevent the code from breaking
4777 if SCons ever changes the interface
4778 to call the function with additional arguments in the future.)
4780 An example of a simple custom progress function
4781 that prints a string containing the Node name
4785 def my_progress_function(node, *args, **kw):
4786 print 'Evaluating node %s!' % node
4787 Progress(my_progress_function, interval=10)
4790 A more complicated example of a custom progress display object
4791 that prints a string containing a count
4792 every 100 evaluated Nodes.
4796 at the end so that the string
4797 will overwrite itself on a display:
4801 class ProgressCounter:
4803 def __call__(self, node, *args, **kw):
4805 sys.stderr.write('Evaluated %s nodes\\r' % self.count)
4806 Progress(ProgressCounter(), interval=100)
4809 If the first argument
4812 the string will be displayed
4816 The default is to print the string on standard output;
4817 an alternate output stream
4818 may be specified with the
4821 The following will print a series of dots
4822 on the error output,
4823 one dot for every 100 evaluated Nodes:
4827 Progress('.', interval=100, file=sys.stderr)
4830 If the string contains the verbatim substring
4832 it will be replaced with the Node.
4833 Note that, for performance reasons, this is
4835 a regular SCons variable substition,
4836 so you can not use other variables
4837 or use curly braces.
4838 The following example will print the name of
4839 every evaluated Node,
4842 (carriage return) to cause each line to overwritten by the next line,
4845 keyword argument to make sure the previously-printed
4846 file name is overwritten with blank spaces:
4850 Progress('$TARGET\\r', overwrite=True)
4853 If the first argument to
4855 is a list of strings,
4856 then each string in the list will be displayed
4857 in rotating fashion every
4860 This can be used to implement a "spinner"
4861 on the user's screen as follows:
4864 Progress(['-\\r', '\\\\\\r', '|\\r', '/\\r'], interval=5)
4867 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4869 .RI Precious( target ", ...)"
4871 .RI env.Precious( target ", ...)"
4874 as precious so it is not deleted before it is rebuilt. Normally
4876 deletes a target before building it.
4877 Multiple targets can be passed in to a single call to
4880 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4882 .RI env.Prepend( key = val ", [...])"
4883 Appends the specified keyword arguments
4884 to the beginning of construction variables in the environment.
4885 If the Environment does not have
4886 the specified construction variable,
4887 it is simply added to the environment.
4888 If the values of the construction variable
4889 and the keyword argument are the same type,
4890 then the two values will be simply added together.
4891 Otherwise, the construction variable
4892 and the value of the keyword argument
4893 are both coerced to lists,
4894 and the lists are added together.
4895 (See also the Append method, above.)
4900 env.Prepend(CCFLAGS = '-g ', FOO = ['foo.yyy'])
4903 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4905 .RI env.PrependENVPath( name ", " newpath ", [" envname ", " sep ", " delete_existing ])
4906 This appends new path elements to the given path in the
4907 specified external environment
4911 any particular path once (leaving the first one it encounters and
4912 ignoring the rest, to preserve path order),
4913 and to help assure this,
4914 will normalize all paths (using
4917 .BR os.path.normcase ).
4918 This can also handle the
4919 case where the given old path variable is a list instead of a
4920 string, in which case a list will be returned instead of a string.
4924 is 0, then adding a path that already exists
4925 will not move it to the beginning;
4926 it will stay where it is in the list.
4931 print 'before:',env['ENV']['INCLUDE']
4932 include_path = '/foo/bar:/foo'
4933 env.PrependENVPath('INCLUDE', include_path)
4934 print 'after:',env['ENV']['INCLUDE']
4937 The above exmaple will print:
4941 after: /foo/bar:/foo:/biz
4944 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4946 .RI env.PrependUnique( key = val ", delete_existing=0, [...])"
4947 Appends the specified keyword arguments
4948 to the beginning of construction variables in the environment.
4949 If the Environment does not have
4950 the specified construction variable,
4951 it is simply added to the environment.
4952 If the construction variable being appended to is a list,
4953 then any value(s) that already exist in the
4954 construction variable will
4956 be added again to the list.
4957 However, if delete_existing is 1,
4958 existing matching values are removed first, so
4959 existing values in the arg list move to the front of the list.
4964 env.PrependUnique(CCFLAGS = '-g', FOO = ['foo.yyy'])
4967 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4970 A factory function that
4971 returns a Builder object
4972 to be used to fetch source files
4974 The returned Builder
4975 is intended to be passed to the
4982 env.SourceCode('.', env.RCS())
4987 will fetch source files
4988 from RCS subdirectories automatically,
4990 as demonstrated in the above example
4991 should only be necessary if
4992 you are fetching from
4995 directory as the source files,
4996 or if you need to explicitly specify RCS
4997 for a specific subdirectory.
4999 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
5001 .RI env.Replace( key = val ", [...])"
5002 Replaces construction variables in the Environment
5003 with the specified keyword arguments.
5008 env.Replace(CCFLAGS = '-g', FOO = 'foo.xxx')
5011 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
5013 .RI Repository( directory )
5015 .RI env.Repository( directory )
5018 is a repository to be searched for files.
5022 and each one adds to the list of
5023 repositories that will be searched.
5027 a repository is a copy of the source tree,
5028 from the top-level directory on down,
5030 both source files and derived files
5031 that can be used to build targets in
5032 the local source tree.
5033 The canonical example would be an
5034 official source tree maintained by an integrator.
5035 If the repository contains derived files,
5036 then the derived files should have been built using
5038 so that the repository contains the necessary
5039 signature information to allow
5041 to figure out when it is appropriate to
5042 use the repository copy of a derived file,
5043 instead of building one locally.
5045 Note that if an up-to-date derived file
5046 already exists in a repository,
5050 make a copy in the local directory tree.
5051 In order to guarantee that a local copy
5057 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
5059 .RI Requires( target ", " prerequisite )
5061 .RI env.Requires( target ", " prerequisite )
5062 Specifies an order-only relationship
5063 between the specified target file(s)
5064 and the specified prerequisite file(s).
5065 The prerequisite file(s)
5066 will be (re)built, if necessary,
5069 but the target file(s) do not actually
5070 depend on the prerequisites
5071 and will not be rebuilt simply because
5072 the prerequisite file(s) change.
5077 env.Requires('foo', 'file-that-must-be-built-before-foo')
5080 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
5082 .RI Return([ vars "... , " stop= ])
5084 this stops processing the current SConscript
5085 file and returns to the calling SConscript file
5086 the values of the variables named in the
5089 Multiple strings contaning variable names may be passed to
5091 Any strings that contain white space
5095 keyword argument may be set to a false value
5096 to continue processing the rest of the SConscript
5100 This was the default behavior prior to SCons 0.98.
5101 However, the values returned
5102 are still the values of the variables in the named
5111 # Returns without returning a value.
5114 # Returns the value of the 'foo' Python variable.
5117 # Returns the values of the Python variables 'foo' and 'bar'.
5118 Return("foo", "bar")
5120 # Returns the values of Python variables 'val1' and 'val2'.
5124 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
5126 .RI Scanner( function ", [" argument ", " keys ", " path_function ", " node_class ", " node_factory ", " scan_check ", " recursive ])
5128 .RI env.Scanner( function ", [" argument ", " keys ", " path_function ", " node_class ", " node_factory ", " scan_check ", " recursive ])
5129 Creates a Scanner object for
5132 See the section "Scanner Objects,"
5133 below, for a complete explanation of the arguments and behavior.
5135 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
5138 A factory function that
5139 returns a Builder object
5140 to be used to fetch source files
5142 The returned Builder
5143 is intended to be passed to the
5150 env.SourceCode('.', env.SCCS())
5155 will fetch source files
5156 from SCCS subdirectories automatically,
5158 as demonstrated in the above example
5159 should only be necessary if
5160 you are fetching from
5163 directory as the source files,
5164 or if you need to explicitly specify SCCS
5165 for a specific subdirectory.
5167 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
5169 .RI SConscript( scripts ", [" exports ", " variant_dir ", " duplicate ])
5170 '\" .RI SConscript( scripts ", [" exports ", " variant_dir ", " src_dir ", " duplicate ])
5172 .RI env.SConscript( scripts ", [" exports ", " variant_dir ", " duplicate ])
5173 '\" .RI env.SConscript( scripts ", [" exports ", " variant_dir ", " src_dir ", " duplicate ])
5175 .RI SConscript(dirs= subdirs ", [name=" script ", " exports ", " variant_dir ", " duplicate ])
5176 '\" .RI SConscript(dirs= subdirs ", [name=" script ", " exports ", " variant_dir ", " src_dir ", " duplicate ])
5178 .RI env.SConscript(dirs= subdirs ", [name=" script ", " exports ", " variant_dir ", " duplicate ])
5179 '\" .RI env.SConscript(dirs= subdirs ", [name=" script ", " exports ", " variant_dir ", " src_dir ", " duplicate ])
5183 one or more subsidiary SConscript (configuration) files.
5184 Any variables returned by a called script using
5186 will be returned by the call to
5188 There are two ways to call the
5192 The first way you can call
5194 is to explicitly specify one or more
5196 as the first argument.
5197 A single script may be specified as a string;
5198 multiple scripts must be specified as a list
5199 (either explicitly or as created by
5204 SConscript('SConscript') # run SConscript in the current directory
5205 SConscript('src/SConscript') # run SConscript in the src directory
5206 SConscript(['src/SConscript', 'doc/SConscript'])
5207 config = SConscript('MyConfig.py')
5210 The second way you can call
5212 is to specify a list of (sub)directory names
5219 execute a subsidiary configuration file named
5221 in each of the specified directories.
5222 You may specify a name other than
5224 by supplying an optional
5227 The first three examples below have the same effect
5228 as the first three examples above:
5230 SConscript(dirs='.') # run SConscript in the current directory
5231 SConscript(dirs='src') # run SConscript in the src directory
5232 SConscript(dirs=['src', 'doc'])
5233 SConscript(dirs=['sub1', 'sub2'], name='MySConscript')
5238 argument provides a list of variable names or a dictionary of
5239 named values to export to the
5241 These variables are locally exported only to the specified
5243 and do not affect the global pool of variables used by the
5246 '\"If multiple dirs are provided, each script gets a fresh export.
5251 function to import the variables.
5254 foo = SConscript('sub/SConscript', exports='env')
5255 SConscript('dir/SConscript', exports=['env', 'variable'])
5256 SConscript(dirs='subdir', exports='env variable')
5257 SConscript(dirs=['one', 'two', 'three'], exports='shared_info')
5262 argument is present, it causes an effect equivalent to the
5264 method described below.
5270 '\" arguments are ignored.)
5271 argument is ignored.)
5276 '\" arguments are interpreted relative to the directory of the calling
5277 argument is interpreted relative to the directory of the calling
5278 .BR SConscript file.
5279 See the description of the
5281 function below for additional details and restrictions.
5284 '\" .IR variant_dir " is present, but"
5285 '\" .IR src_dir " is not,"
5286 .IR variant_dir " is present,"
5287 the source directory is relative to the called
5288 .BR SConscript " file."
5290 SConscript('src/SConscript', variant_dir = 'build')
5294 VariantDir('build', 'src')
5295 SConscript('build/SConscript')
5297 This later paradigm is often used when the sources are
5298 in the same directory as the
5299 .BR SConstruct file:
5301 SConscript('SConscript', variant_dir = 'build')
5305 VariantDir('build', '.')
5306 SConscript('build/SConscript')
5310 '\" .IR variant_dir " and"
5311 '\" .IR src_dir " are both present,"
5312 '\" xxxxx everything is in a state of confusion.
5314 '\" SConscript(dirs = 'src', variant_dir = 'build', src_dir = '.')
5315 '\" runs src/SConscript in build/src, but
5316 '\" SConscript(dirs = 'lib', variant_dir = 'build', src_dir = 'src')
5317 '\" runs lib/SConscript (in lib!). However,
5318 '\" SConscript(dirs = 'src', variant_dir = 'build', src_dir = 'src')
5319 '\" runs src/SConscript in build. Moreover,
5320 '\" SConscript(dirs = 'src/lib', variant_dir = 'build', src_dir = 'src')
5321 '\" runs src/lib/SConscript in build/lib. Moreover,
5322 '\" SConscript(dirs = 'build/src/lib', variant_dir = 'build', src_dir = 'src')
5323 '\" can't find build/src/lib/SConscript, even though it ought to exist.
5325 '\" is equivalent to
5327 '\" ????????????????
5329 '\" and what about this alternative?
5330 '\"TODO??? SConscript('build/SConscript', src_dir='src')
5332 Here are some composite examples:
5335 # collect the configuration information and use it to build src and doc
5336 shared_info = SConscript('MyConfig.py')
5337 SConscript('src/SConscript', exports='shared_info')
5338 SConscript('doc/SConscript', exports='shared_info')
5342 # build debugging and production versions. SConscript
5343 # can use Dir('.').path to determine variant.
5344 SConscript('SConscript', variant_dir='debug', duplicate=0)
5345 SConscript('SConscript', variant_dir='prod', duplicate=0)
5349 # build debugging and production versions. SConscript
5350 # is passed flags to use.
5351 opts = { 'CPPDEFINES' : ['DEBUG'], 'CCFLAGS' : '-pgdb' }
5352 SConscript('SConscript', variant_dir='debug', duplicate=0, exports=opts)
5353 opts = { 'CPPDEFINES' : ['NODEBUG'], 'CCFLAGS' : '-O' }
5354 SConscript('SConscript', variant_dir='prod', duplicate=0, exports=opts)
5358 # build common documentation and compile for different architectures
5359 SConscript('doc/SConscript', variant_dir='build/doc', duplicate=0)
5360 SConscript('src/SConscript', variant_dir='build/x86', duplicate=0)
5361 SConscript('src/SConscript', variant_dir='build/ppc', duplicate=0)
5364 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
5366 .RI SConscriptChdir( value )
5368 .RI env.SConscriptChdir( value )
5371 changes its working directory
5372 to the directory in which each
5373 subsidiary SConscript file lives.
5374 This behavior may be disabled
5375 by specifying either:
5379 env.SConscriptChdir(0)
5384 will stay in the top-level directory
5385 while reading all SConscript files.
5386 (This may be necessary when building from repositories,
5387 when all the directories in which SConscript files may be found
5388 don't necessarily exist locally.)
5389 You may enable and disable
5390 this ability by calling
5399 SConscript('foo/SConscript') # will not chdir to foo
5400 env.SConscriptChdir(1)
5401 SConscript('bar/SConscript') # will chdir to bar
5404 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
5406 .RI SConsignFile([ file , dbm_module ])
5408 .RI env.SConsignFile([ file , dbm_module ])
5411 to store all file signatures
5412 in the specified database
5419 (The actual file name(s) stored on disk
5420 may have an appropriated suffix appended
5425 is not an absolute path name,
5426 the file is placed in the same directory as the top-level
5436 will store file signatures
5439 file in each directory,
5440 not in one global database file.
5441 (This was the default behavior
5442 prior to SCons 0.96.91 and 0.97.)
5446 argument can be used to specify
5447 which Python database module
5448 The default is to use a custom
5450 module that uses pickled
5451 Python data structures,
5452 and which works on all Python versions from 1.5.2 on.
5457 # Explicitly stores signatures in ".sconsign.dblite"
5458 # in the top-level SConstruct directory (the
5459 # default behavior).
5462 # Stores signatures in the file "etc/scons-signatures"
5463 # relative to the top-level SConstruct directory.
5464 SConsignFile("etc/scons-signatures")
5466 # Stores signatures in the specified absolute file name.
5467 SConsignFile("/home/me/SCons/signatures")
5469 # Stores signatures in a separate .sconsign file
5470 # in each directory.
5474 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
5476 .RI env.SetDefault(key = val ", [...])"
5477 Sets construction variables to default values specified with the keyword
5478 arguments if (and only if) the variables are not already set.
5479 The following statements are equivalent:
5482 env.SetDefault(FOO = 'foo')
5484 if not env.has_key('FOO'): env['FOO'] = 'foo'
5487 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
5489 .RI SetOption( name ", " value )
5491 .RI env.SetOption( name ", " value )
5492 This function provides a way to set a select subset of the scons command
5493 line options from a SConscript file. The options supported are:
5498 which corresponds to -c, --clean and --remove;
5501 which corresponds to --duplicate;
5504 which corresponds to -h and --help;
5507 which corresponds to --implicit-cache;
5510 which corresponds to --max-drift;
5513 which corresponds to -n, --no-exec, --just-print, --dry-run and --recon;
5516 which corresponds to -j and --jobs;
5519 which corresponds to --random; and
5522 which corresponds to --stack-size.
5526 See the documentation for the
5527 corresponding command line object for information about each specific
5533 SetOption('max_drift', 1)
5536 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
5538 .RI SideEffect( side_effect ", " target )
5540 .RI env.SideEffect( side_effect ", " target )
5543 as a side effect of building
5549 can be a list, a file name, or a node.
5550 A side effect is a target file that is created or updated
5551 as a side effect of building other targets.
5552 For example, a Windows PDB
5553 file is created as a side effect of building the .obj
5554 files for a static library,
5555 and various log files are created updated
5556 as side effects of various TeX commands.
5557 If a target is a side effect of multiple build commands,
5559 will ensure that only one set of commands
5560 is executed at a time.
5561 Consequently, you only need to use this method
5562 for side-effect targets that are built as a result of
5563 multiple build commands.
5565 Because multiple build commands may update
5566 the same side effect file,
5571 automatically removed
5577 (Note, however, that the
5579 might be removed as part of
5580 cleaning the directory in which it lives.)
5581 If you want to make sure the
5583 is cleaned whenever a specific
5586 you must specify this explicitly
5593 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
5595 .RI SourceCode( entries ", " builder )
5597 .RI env.SourceCode( entries ", " builder )
5598 Arrange for non-existent source files to
5599 be fetched from a source code management system
5604 may be a Node, string or list of both,
5605 and may represent either individual
5606 source files or directories in which
5607 source files can be found.
5609 For any non-existent source files,
5611 will search up the directory tree
5621 will not use a builder to fetch
5622 source files for the specified
5626 builder has been specified
5627 for a directory higher up the tree.
5631 fetch files from SCCS or RCS subdirectories
5632 without explicit configuration.
5633 This takes some extra processing time
5634 to search for the necessary
5635 source code management files on disk.
5636 You can avoid these extra searches
5637 and speed up your build a little
5638 by disabling these searches as follows:
5641 env.SourceCode('.', None)
5645 Note that if the specified
5647 is one you create by hand,
5648 it must have an associated
5649 construction environment to use
5650 when fetching a source file.
5653 provides a set of canned factory
5654 functions that return appropriate
5655 Builders for various popular
5656 source code management systems.
5657 Canonical examples of invocation include:
5660 env.SourceCode('.', env.BitKeeper('/usr/local/BKsources'))
5661 env.SourceCode('src', env.CVS('/usr/local/CVSROOT'))
5662 env.SourceCode('/', env.RCS())
5663 env.SourceCode(['f1.c', 'f2.c'], env.SCCS())
5664 env.SourceCode('no_source.c', None)
5666 '\"env.SourceCode('.', env.Subversion('file:///usr/local/Subversion'))
5668 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
5670 .RI env.subst( input ", [" raw ", " target ", " source ", " conv ])
5671 Performs construction variable interpolation
5672 on the specified string or sequence argument
5676 leading or trailing white space will
5677 be removed from the result.
5678 and all sequences of white space
5679 will be compressed to a single space character.
5684 character sequences will be stripped from the returned string,
5687 argument may be set to
5689 if you want to preserve white space and
5694 argument may be set to
5696 if you want to strip
5697 all characters between
5703 (as is done for signature calculation).
5705 If the input is a sequence
5707 the individual elements of
5708 the sequence will be expanded,
5709 and the results will be returned as a list.
5716 must be set to lists of
5717 target and source nodes, respectively,
5724 to be available for expansion.
5725 This is usually necessary if you are
5728 from within a Python function used
5731 Returned string values or sequence elements
5732 are converted to their string representation by default.
5736 may specify a conversion function
5737 that will be used in place of
5739 For example, if you want Python objects
5740 (including SCons Nodes)
5741 to be returned as Python objects,
5742 you can use the Python
5744 idiom to pass in an unnamed function
5745 that simply returns its unconverted argument.
5750 print env.subst("The C compiler is: $CC")
5752 def compile(target, source, env):
5753 sourceDir = env.subst("${SOURCE.srcdir}",
5757 source_nodes = env.subst('$EXPAND_TO_NODELIST',
5761 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
5763 '\".RI Subversion( repository ", " module )
5764 '\"A factory function that
5765 '\"returns a Builder object
5766 '\"to be used to fetch source files
5767 '\"from the specified Subversion
5769 '\"The returned Builder
5770 '\"is intended to be passed to the
5774 '\"The optional specified
5776 '\"will be added to the beginning
5777 '\"of all repository path names;
5778 '\"this can be used, in essence,
5779 '\"to strip initial directory names
5780 '\"from the repository path names,
5781 '\"so that you only have to
5782 '\"replicate part of the repository
5783 '\"directory hierarchy in your
5784 '\"local build directory.
5789 '\"# Will fetch foo/bar/src.c
5790 '\"# from /usr/local/Subversion/foo/bar/src.c.
5791 '\"env.SourceCode('.', env.Subversion('file:///usr/local/Subversion'))
5793 '\"# Will fetch bar/src.c
5794 '\"# from /usr/local/Subversion/foo/bar/src.c.
5795 '\"env.SourceCode('.', env.Subversion('file:///usr/local/Subversion', 'foo'))
5797 '\"# Will fetch src.c
5798 '\"# from /usr/local/Subversion/foo/bar/src.c.
5799 '\"env.SourceCode('.', env.Subversion('file:///usr/local/Subversion', 'foo/bar'))
5802 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
5804 .RI SourceSignatures( type )
5806 .RI env.SourceSignatures( type )
5807 Note: Although it is not yet officially deprecated,
5808 use of this function is discouraged.
5811 function for a more flexible and straightforward way
5812 to configure SCons' decision-making.
5815 .BR SourceSignatures ()
5818 how to decide if a source file
5819 (a file that is not built from any other files)
5820 has changed since the last time it
5821 was used to build a particular target file.
5827 If the environment method is used,
5828 the specified type of source signature
5829 is only used when deciding whether targets
5830 built with that environment are up-to-date or must be rebuilt.
5831 If the global function is used,
5832 the specified type of source signature becomes the default
5833 used for all decisions
5834 about whether targets are up-to-date.
5839 decides that a source file has changed
5840 if the MD5 checksum of its contents has changed since
5841 the last time it was used to rebuild a particular target file.
5846 decides that a source file has changed
5847 if its timestamp (modification time) has changed since
5848 the last time it was used to rebuild a particular target file.
5849 (Note that although this is similar to the behavior of Make,
5850 by default it will also rebuild if the dependency is
5852 than the last time it was used to rebuild the target file.)
5854 There is no different between the two behaviors
5860 signatures take longer to compute,
5861 but are more accurate than
5864 The default value is
5867 Note that the default
5868 .BR TargetSignatures ()
5871 .BR SourceSignatures ()
5872 setting for any target files that are used
5873 to build other target files.
5874 Consequently, changing the value of
5875 .BR SourceSignatures ()
5877 affect the up-to-date decision for all files in the build
5878 (or all files built with a specific construction environment
5880 .BR env.SourceSignatures ()
5883 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
5887 .RI env.Split( arg )
5888 Returns a list of file names or other objects.
5890 it will be split on strings of white-space characters
5892 making it easier to write long lists of file names.
5893 If arg is already a list,
5894 the list will be returned untouched.
5895 If arg is any other type of object,
5896 it will be returned as a list
5897 containing just the object.
5902 files = Split("f1.c f2.c f3.c")
5903 files = env.Split("f4.c f5.c f6.c")
5911 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
5913 .RI Tag( node ", " tags )
5914 Annotates file or directory Nodes with
5915 information about how the
5917 Builder should package those files or directories.
5918 All tags are optional.
5923 # makes sure the built library will be installed with 0644 file
5925 Tag( Library( 'lib.c' ), UNIX_ATTR="0644" )
5927 # marks file2.txt to be a documentation file
5928 Tag( 'file2.txt', DOC )
5931 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
5933 .RI TargetSignatures( type )
5935 .RI env.TargetSignatures( type )
5936 Note: Although it is not yet officially deprecated,
5937 use of this function is discouraged.
5940 function for a more flexible and straightforward way
5941 to configure SCons' decision-making.
5944 .BR TargetSignatures ()
5947 how to decide if a target file
5950 built from any other files)
5951 has changed since the last time it
5952 was used to build some other target file.
5962 If the environment method is used,
5963 the specified type of target signature is only used
5964 for targets built with that environment.
5965 If the global function is used,
5966 the specified type of signature becomes the default
5967 used for all target files that
5968 don't have an explicit target signature type
5969 specified for their environments.
5976 decides that a target file has changed
5977 if the MD5 checksum of its contents has changed since
5978 the last time it was used to rebuild some other target file.
5982 MD5 sum the contents
5983 of target files after they're built,
5984 and may decide that it does not need to rebuild
5985 "downstream" target files if a file was
5986 rebuilt with exactly the same contents as the last time.
5991 decides that a target file has changed
5992 if its timestamp (modification time) has changed since
5993 the last time it was used to rebuild some other target file.
5994 (Note that although this is similar to the behavior of Make,
5995 by default it will also rebuild if the dependency is
5997 than the last time it was used to rebuild the target file.)
6002 decides that a target file has changed
6003 as specified by the corresponding
6004 .BR SourceSignatures ()
6011 will treat all input files to a target the same way,
6012 regardless of whether they are source files
6013 or have been built from other files.
6018 decides that a target file has changed
6019 if it has been rebuilt in this invocation
6020 or if its content or timestamp have changed
6021 as specified by the corresponding
6022 .BR SourceSignatures ()
6024 This "propagates" the status of a rebuilt file
6025 so that other "downstream" target files
6026 will always be rebuilt,
6027 even if the contents or the timestamp
6031 signatures are fastest because
6035 signatures take longer to compute,
6036 but are more accurate than
6039 and can prevent unnecessary "downstream" rebuilds
6040 when a target file is rebuilt to the exact same contents
6041 as the previous build.
6044 setting provides the most consistent behavior
6045 when other target files may be rebuilt from
6046 both source and target input files.
6047 The default value is
6050 Because the default setting is
6053 .BR SourceSignatures ()
6054 is generally preferable to
6055 .BR TargetSignatures () ,
6056 so that the up-to-date decision
6057 will be consistent for all files
6058 (or all files built with a specific construction environment).
6060 .BR TargetSignatures ()
6061 provides specific control for how built target files
6062 affect their "downstream" dependencies.
6064 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
6066 .RI Tool( string [, toolpath ", " **kw ])
6067 Returns a callable object
6068 that can be used to initialize
6069 a construction environment using the
6070 tools keyword of the Environment() method.
6071 The object may be called with a construction
6072 environment as an argument,
6073 in which case the object will
6074 add the necessary variables
6075 to the construction environment
6076 and the name of the tool will be added to the
6078 construction variable.
6080 Additional keyword arguments are passed to the tool's
6087 env = Environment(tools = [ Tool('msvc') ])
6091 t(env) # adds 'msvc' to the TOOLS variable
6092 u = Tool('opengl', toolpath = ['tools'])
6093 u(env) # adds 'opengl' to the TOOLS variable
6096 .RI env.Tool( string [, toolpath ", " **kw ])
6097 Applies the callable object for the specified tool
6099 to the environment through which the method was called.
6101 Additional keyword arguments are passed to the tool's
6107 env.Tool('opengl', toolpath = ['build/tools'])
6110 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
6112 .RI Value( value ", [" built_value ])
6114 .RI env.Value( value ", [" built_value ])
6115 Returns a Node object representing the specified Python value. Value
6116 Nodes can be used as dependencies of targets. If the result of
6119 changes between SCons runs, any targets depending on
6122 (This is true even when using timestamps to decide if
6123 files are up-to-date.)
6124 When using timestamp source signatures, Value Nodes'
6125 timestamps are equal to the system time when the Node is created.
6127 The returned Value Node object has a
6129 method that can be used to "build" a Value Node
6130 by setting a new value.
6133 argument can be specified
6134 when the Value Node is created
6135 to indicate the Node should already be considered
6137 There is a corresponding
6139 method that will return the built value of the Node.
6146 def create(target, source, env):
6147 # A function that will write a 'prefix=$SOURCE'
6148 # string into the file name specified as the
6150 f = open(str(target[0]), 'wb')
6151 f.write('prefix=' + source[0].get_contents())
6153 # Fetch the prefix= argument, if any, from the command
6154 # line, and use /usr/local as the default.
6155 prefix = ARGUMENTS.get('prefix', '/usr/local')
6157 # Attach a .Config() builder for the above function action
6158 # to the construction environment.
6159 env['BUILDERS']['Config'] = Builder(action = create)
6160 env.Config(target = 'package-config', source = Value(prefix))
6162 def build_value(target, source, env):
6163 # A function that "builds" a Python Value by updating
6164 # the the Python value with the contents of the file
6165 # specified as the source of the Builder call ($SOURCE).
6166 target[0].write(source[0].get_contents())
6168 output = env.Value('before')
6169 input = env.Value('after')
6171 # Attach a .UpdateValue() builder for the above function
6172 # action to the construction environment.
6173 env['BUILDERS']['UpdateValue'] = Builder(action = build_value)
6174 env.UpdateValue(target = Value(output), source = Value(input))
6177 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
6179 .RI VariantDir( variant_dir ", " src_dir ", [" duplicate ])
6181 .RI env.VariantDir( variant_dir ", " src_dir ", [" duplicate ])
6184 function to create a copy of your sources in another location:
6187 is not found but exists under
6189 the file or directory is copied to
6191 Target files can be built in a different directory
6192 than the original sources by simply refering to the sources (and targets)
6193 within the variant tree.
6196 can be called multiple times with the same
6198 to set up multiple builds with different options
6202 location must be in or underneath the SConstruct file's directory, and
6204 may not be underneath
6206 '\"TODO: Can the above restrictions be clarified or relaxed?
6207 '\"TODO: The latter restriction is clearly not completely right;
6208 '\"TODO: src_dir = '.' works fine with a build dir under it.
6210 The default behavior is for
6212 to physically duplicate the source files in the variant tree.
6213 Thus, a build performed in the variant tree is guaranteed to be identical
6214 to a build performed in the source tree even if
6215 intermediate source files are generated during the build,
6216 or preprocessors or other scanners search for included files
6217 relative to the source file,
6218 or individual compilers or other invoked tools are hard-coded
6219 to put derived files in the same directory as source files.
6221 If possible on the platform,
6222 the duplication is performed by linking rather than copying;
6225 command-line option.
6226 Moreover, only the files needed for the build are duplicated;
6227 files and directories that are not used are not present in
6230 Duplicating the source tree may be disabled by setting the
6232 argument to 0 (zero).
6235 to invoke Builders using the path names of source files in
6237 and the path names of derived files within
6239 This is always more efficient than
6241 and is usually safe for most builds
6242 (but see above for cases that may cause problems).
6246 works most naturally with a subsidiary SConscript file.
6247 However, you would then call the subsidiary SConscript file
6248 not in the source directory, but in the
6250 regardless of the value of
6252 This is how you tell
6254 which variant of a source tree to build:
6257 # run src/SConscript in two variant directories
6258 VariantDir('build/variant1', 'src')
6259 SConscript('build/variant1/SConscript')
6260 VariantDir('build/variant2', 'src')
6261 SConscript('build/variant2/SConscript')
6267 function, described above,
6268 for another way to specify a variant directory
6269 in conjunction with calling a subsidiary SConscript file.
6274 # use names in the build directory, not the source directory
6275 VariantDir('build', 'src', duplicate=0)
6276 Program('build/prog', 'build/source.c')
6280 # this builds both the source and docs in a separate subtree
6281 VariantDir('build', '.', duplicate=0)
6282 SConscript(dirs=['build/src','build/doc'])
6286 # same as previous example, but only uses SConscript
6287 SConscript(dirs='src', variant_dir='build/src', duplicate=0)
6288 SConscript(dirs='doc', variant_dir='build/doc', duplicate=0)
6291 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
6293 .RI WhereIs( program ", [" path ", " pathext ", " reject ])
6295 .RI env.WhereIs( program ", [" path ", " pathext ", " reject ])
6297 Searches for the specified executable
6299 returning the full path name to the program
6301 and returning None if not.
6302 Searches the specified
6304 the value of the calling environment's PATH
6305 (env['ENV']['PATH']),
6306 or the user's current external PATH
6307 (os.environ['PATH'])
6309 On Windows systems, searches for executable
6310 programs with any of the file extensions
6311 listed in the specified
6313 the calling environment's PATHEXT
6314 (env['ENV']['PATHEXT'])
6315 or the user's current PATHEXT
6316 (os.environ['PATHEXT'])
6324 .SS SConscript Variables
6325 In addition to the global functions and methods,
6327 supports a number of Python variables
6328 that can be used in SConscript files
6329 to affect how you want the build to be performed.
6330 These variables may be accessed from custom Python modules that you
6331 import into an SConscript file by adding the following
6332 to the Python module:
6335 from SCons.Script import *
6338 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
6343 arguments specified on the command line.
6344 Each element in the list is a tuple
6346 .RI ( keyword , value )
6352 elements of the tuple
6354 subscripting for element
6358 of the tuple, respectively.
6363 print "first keyword, value =", ARGLIST[0][0], ARGLIST[0][1]
6364 print "second keyword, value =", ARGLIST[1][0], ARGLIST[1][1]
6365 third_tuple = ARGLIST[2]
6366 print "third keyword, value =", third_tuple[0], third_tuple[1]
6367 for key, value in ARGLIST:
6368 # process key and value
6371 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
6374 A dictionary of all the
6376 arguments specified on the command line.
6377 The dictionary is not in order,
6378 and if a given keyword has
6379 more than one value assigned to it
6380 on the command line,
6381 the last (right-most) value is
6389 if ARGUMENTS.get('debug', 0):
6390 env = Environment(CCFLAGS = '-g')
6395 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
6398 A list of the targets which
6400 will actually try to build,
6401 regardless of whether they were specified on
6402 the command line or via the
6405 The elements of this list may be strings
6407 nodes, so you should run the list through the Python
6409 function to make sure any Node path names
6410 are converted to strings.
6412 Because this list may be taken from the
6413 list of targets specified using the
6416 the contents of the list may change
6417 on each successive call to
6422 for additional information.
6427 if 'foo' in BUILD_TARGETS:
6428 print "Don't forget to test the `foo' program!"
6429 if 'special/program' in BUILD_TARGETS:
6430 SConscript('special')
6435 list only contains targets expected listed
6436 on the command line or via calls to the
6441 contain all dependent targets that will be built as
6442 a result of making the sure the explicitly-specified
6443 targets are up to date.
6445 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
6447 COMMAND_LINE_TARGETS
6448 A list of the targets explicitly specified on
6450 If there are no targets specified on the command line,
6452 This can be used, for example,
6453 to take specific actions only
6454 when a certain target or targets
6455 is explicitly being built.
6460 if 'foo' in COMMAND_LINE_TARGETS:
6461 print "Don't forget to test the `foo' program!"
6462 if 'special/program' in COMMAND_LINE_TARGETS:
6463 SConscript('special')
6466 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
6469 A list of the target
6471 that have been specified using the
6474 The elements of the list are nodes,
6475 so you need to run them through the Python
6477 function to get at the path name for each Node.
6482 print str(DEFAULT_TARGETS[0])
6483 if 'foo' in map(str, DEFAULT_TARGETS):
6484 print "Don't forget to test the `foo' program!"
6489 list change on on each successive call to the
6494 print map(str, DEFAULT_TARGETS) # originally []
6496 print map(str, DEFAULT_TARGETS) # now a node ['foo']
6498 print map(str, DEFAULT_TARGETS) # now a node ['foo', 'bar']
6500 print map(str, DEFAULT_TARGETS) # back to []
6503 Consequently, be sure to use
6505 only after you've made all of your
6508 or else simply be careful of the order
6509 of these statements in your SConscript files
6510 so that you don't look for a specific
6511 default target before it's actually been added to the list.
6513 .SS Construction Variables
6514 .\" XXX From Gary Ruben, 23 April 2002:
6515 .\" I think it would be good to have an example with each construction
6516 .\" variable description in the documentation.
6518 .\" CC The C compiler
6519 .\" Example: env["CC"] = "c68x"
6520 .\" Default: env["CC"] = "cc"
6522 .\" CCCOM The command line ...
6524 .\" To generate the compiler line c68x -ps -qq -mr -o $TARGET $SOURCES
6525 .\" env["CC"] = "c68x"
6526 .\" env["CFLAGS"] = "-ps -qq -mr"
6527 .\" env["CCCOM"] = "$CC $CFLAGS -o $TARGET $SOURCES
6529 .\" (I dunno what this is ;-)
6530 A construction environment has an associated dictionary of
6531 .I construction variables
6532 that are used by built-in or user-supplied build rules.
6533 Construction variables must follow the same rules for
6535 the initial character must be an underscore or letter,
6536 followed by any number of underscores, letters, or digits.
6538 A number of useful construction variables are automatically defined by
6539 scons for each supported platform, and additional construction variables
6540 can be defined by the user. The following is a list of the automatically
6541 defined construction variables:
6543 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
6544 '\" BEGIN GENERATED CONSTRUCTION VARIABLE DESCRIPTIONS
6546 '\" The descriptions below of the various SCons construction variables
6547 '\" are generated from the .xml files that live next to the various
6548 '\" Python modules in the build enginer library. If you're reading
6549 '\" this [gnt]roff file with an eye towards patching this man page,
6550 '\" you can still submit a diff against this text, but it will have to
6551 '\" be translated to a diff against the underlying .xml file before the
6552 '\" patch is actually accepted. If you do that yourself, it will make
6553 '\" it easier to integrate the patch.
6555 '\" BEGIN GENERATED CONSTRUCTION VARIABLE DESCRIPTIONS
6556 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
6558 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
6559 '\" END GENERATED CONSTRUCTION VARIABLE DESCRIPTIONS
6561 '\" The descriptions above of the various SCons construction variables
6562 '\" are generated from the .xml files that live next to the various
6563 '\" Python modules in the build enginer library. If you're reading
6564 '\" this [gnt]roff file with an eye towards patching this man page,
6565 '\" you can still submit a diff against this text, but it will have to
6566 '\" be translated to a diff against the underlying .xml file before the
6567 '\" patch is actually accepted. If you do that yourself, it will make
6568 '\" it easier to integrate the patch.
6570 '\" END GENERATED CONSTRUCTION VARIABLE DESCRIPTIONS
6571 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
6574 Construction variables can be retrieved and set using the
6576 method of the construction environment:
6579 dict = env.Dictionary()
6583 or using the [] operator:
6589 Construction variables can also be passed to the construction environment
6593 env = Environment(CC="cc")
6596 or when copying a construction environment using the
6601 env2 = env.Clone(CC="cl.exe")
6604 .SS Configure Contexts
6608 .I configure contexts,
6609 an integrated mechanism similar to the
6610 various AC_CHECK macros in GNU autoconf
6611 for testing for the existence of C header
6612 files, libraries, etc.
6613 In contrast to autoconf,
6615 does not maintain an explicit cache of the tested values,
6616 but uses its normal dependency tracking to keep the checked values
6617 up to date. However, users may override this behaviour with the
6619 command line option.
6621 The following methods can be used to perform checks:
6624 .RI Configure( env ", [" custom_tests ", " conf_dir ", " log_file ", " config_h ", " clean ", " help])
6626 .RI env.Configure([ custom_tests ", " conf_dir ", " log_file ", " config_h ", " clean ", " help])
6627 This creates a configure context, which can be used to perform checks.
6629 specifies the environment for building the tests.
6630 This environment may be modified when performing checks.
6632 is a dictionary containing custom tests.
6633 See also the section about custom tests below.
6634 By default, no custom tests are added to the configure context.
6636 specifies a directory where the test cases are built.
6637 Note that this directory is not used for building
6639 The default value is the directory
6642 specifies a file which collects the output from commands
6643 that are executed to check for the existence of header files, libraries, etc.
6644 The default is the file #/config.log.
6645 If you are using the
6648 you may want to specify a subdirectory under your variant directory.
6650 specifies a C header file where the results of tests
6651 will be written, e.g. #define HAVE_STDIO_H, #define HAVE_LIBM, etc.
6652 The default is to not write a
6655 You can specify the same
6657 file in multiple calls to Configure,
6660 will concatenate all results in the specified file.
6662 uses its normal dependency checking
6663 to decide if it's necessary to rebuild
6667 This means that the file is not necessarily re-built each
6669 but is only rebuilt if its contents will have changed
6670 and some target that depends on the
6672 file is being built.
6678 arguments can be used to suppress execution of the configuration
6683 options are used, respectively.
6684 The default behavior is always to execute
6685 configure context tests,
6686 since the results of the tests may
6687 affect the list of targets to be cleaned
6689 If the configure tests do not affect these,
6690 then you may add the
6696 to avoid unnecessary test execution.
6701 instance has the following associated methods:
6704 .RI SConf.Finish( context )
6707 This method should be called after configuration is done.
6708 It returns the environment as modified
6709 by the configuration checks performed.
6710 After this method is called, no further checks can be performed
6711 with this configuration context.
6712 However, you can create a new
6714 context to perform additional checks.
6715 Only one context should be active at a time.
6717 The following Checks are predefined.
6718 (This list will likely grow larger as time
6719 goes by and developers contribute new useful tests.)
6722 .RI SConf.CheckHeader( context ", " header ", [" include_quotes ", " language ])
6724 .IR sconf .CheckHeader( header ", [" include_quotes ", " language ])
6727 is usable in the specified language.
6730 in which case the last item in the list
6731 is the header file to be checked,
6732 and the previous list items are
6735 lines should precede the
6736 header line being checked for.
6737 The optional argument
6740 a two character string, where the first character denotes the opening
6741 quote and the second character denotes the closing quote.
6742 By default, both characters are " (double quote).
6743 The optional argument
6749 and selects the compiler to be used for the check.
6750 Returns 1 on success and 0 on failure.
6753 .RI SConf.CheckCHeader( context ", " header ", [" include_quotes ])
6755 .IR sconf .CheckCHeader( header ", [" include_quotes ])
6756 This is a wrapper around
6757 .B SConf.CheckHeader
6760 is usable in the C language.
6763 in which case the last item in the list
6764 is the header file to be checked,
6765 and the previous list items are
6768 lines should precede the
6769 header line being checked for.
6770 The optional argument
6773 a two character string, where the first character denotes the opening
6774 quote and the second character denotes the closing quote (both default
6776 Returns 1 on success and 0 on failure.
6779 .RI SConf.CheckCXXHeader( context ", " header ", [" include_quotes ])
6781 .IR sconf .CheckCXXHeader( header ", [" include_quotes ])
6782 This is a wrapper around
6783 .B SConf.CheckHeader
6786 is usable in the C++ language.
6789 in which case the last item in the list
6790 is the header file to be checked,
6791 and the previous list items are
6794 lines should precede the
6795 header line being checked for.
6796 The optional argument
6799 a two character string, where the first character denotes the opening
6800 quote and the second character denotes the closing quote (both default
6802 Returns 1 on success and 0 on failure.
6805 .RI SConf.CheckFunc( context, ", " function_name ", [" header ", " language ])
6807 .IR sconf .CheckFunc( function_name ", [" header ", " language ])
6808 Checks if the specified
6809 C or C++ function is available.
6811 is the name of the function to check for.
6814 argument is a string
6818 that will be compiled
6819 to check if the function exists;
6825 char function_name();
6833 and selects the compiler to be used for the check;
6837 .RI SConf.CheckLib( context ", [" library ", " symbol ", " header ", " language ", " autoadd=1 ])
6839 .IR sconf .CheckLib([ library ", " symbol ", " header ", " language ", " autoadd=1 ])
6846 is 1 and the library provides the specified
6848 appends the library to the LIBS construction environment variable.
6850 may also be None (the default),
6853 is checked with the current LIBS variable,
6854 or a list of library names,
6855 in which case each library in the list
6863 .BR SConf.CheckLib ()
6865 you can link against the specified
6873 and selects the compiler to be used for the check;
6875 The default value for
6878 This method returns 1 on success and 0 on error.
6881 .RI SConf.CheckLibWithHeader( context ", " library ", " header ", " language ", [" call ", " autoadd ])
6883 .IR sconf .CheckLibWithHeader( library ", " header ", " language ", [" call ", " autoadd ])
6887 call, this call provides a more sophisticated way to check against libraries.
6890 specifies the library or a list of libraries to check.
6892 specifies a header to check for.
6895 in which case the last item in the list
6896 is the header file to be checked,
6897 and the previous list items are
6900 lines should precede the
6901 header line being checked for.
6903 may be one of 'C','c','CXX','cxx','C++' and 'c++'.
6905 can be any valid expression (with a trailing ';').
6909 the default simply checks that you
6910 can link against the specified
6913 specifies whether to add the library to the environment (only if the check
6914 succeeds). This method returns 1 on success and 0 on error.
6917 .RI SConf.CheckType( context ", " type_name ", [" includes ", " language ])
6919 .IR sconf .CheckType( type_name ", [" includes ", " language ])
6920 Checks for the existence of a type defined by
6923 specifies the typedef name to check for.
6925 is a string containing one or more
6927 lines that will be inserted into the program
6928 that will be run to test for the existence of the type.
6935 and selects the compiler to be used for the check;
6939 .RI Configure.CheckCC( self )
6940 Checks whether the C compiler (as defined by the CC construction variable) works
6941 by trying to compile a small source file.
6943 By default, SCons only detects if there is a program with the correct name, not
6944 if it is a functioning compiler.
6946 This uses the exact same command than the one used by the object builder for C
6947 source file, so it can be used to detect if a particular compiler flag works or
6951 .RI Configure.CheckCXX( self )
6952 Checks whether the C++ compiler (as defined by the CXX construction variable)
6953 works by trying to compile a small source file. By default, SCons only detects
6954 if there is a program with the correct name, not if it is a functioning compiler.
6956 This uses the exact same command than the one used by the object builder for
6957 CXX source files, so it can be used to detect if a particular compiler flag
6961 .RI Configure.CheckSHCC( self )
6962 Checks whether the C compiler (as defined by the SHCC construction variable) works
6963 by trying to compile a small source file. By default, SCons only detects if
6964 there is a program with the correct name, not if it is a functioning compiler.
6966 This uses the exact same command than the one used by the object builder for C
6967 source file, so it can be used to detect if a particular compiler flag works or
6968 not. This does not check whether the object code can be used to build a shared
6969 library, only that the compilation (not link) succeeds.
6972 .RI Configure.CheckSHCXX( self )
6973 Checks whether the C++ compiler (as defined by the SHCXX construction variable)
6974 works by trying to compile a small source file. By default, SCons only detects
6975 if there is a program with the correct name, not if it is a functioning compiler.
6977 This uses the exact same command than the one used by the object builder for
6978 CXX source files, so it can be used to detect if a particular compiler flag
6979 works or not. This does not check whether the object code can be used to build
6980 a shared library, only that the compilation (not link) succeeds.
6983 Example of a typical Configure usage:
6987 conf = Configure( env )
6988 if not conf.CheckCHeader( 'math.h' ):
6989 print 'We really need math.h!'
6991 if conf.CheckLibWithHeader( 'qt', 'qapp.h', 'c++',
6992 'QApplication qapp(0,0);' ):
6993 # do stuff for qt - usage, e.g.
6994 conf.env.Append( CPPFLAGS = '-DWITH_QT' )
6999 .RI SConf.CheckTypeSize( context ", " type_name ", [" header ", " language ", " expect ])
7001 .IR sconf .CheckTypeSize( type_name ", [" header ", " language ", " expect ])
7002 Checks for the size of a type defined by
7005 specifies the typedef name to check for.
7008 argument is a string
7012 that will be compiled
7013 to check if the function exists;
7014 the default is empty.
7021 and selects the compiler to be used for the check;
7025 argument should be an integer.
7026 If this argument is used,
7027 the function will only check whether the type
7028 given in type_name has the expected size (in bytes).
7030 .B "CheckTypeSize('short', expect = 2)"
7031 will return success only if short is two bytes.
7037 .RI SConf.CheckDeclaration( context ", " symbol ", [" includes ", " language ])
7039 .IR sconf .CheckDeclaration( symbol ", [" includes ", " language ])
7040 Checks if the specified
7044 is a string containing one or more
7046 lines that will be inserted into the program
7047 that will be run to test for the existence of the type.
7054 and selects the compiler to be used for the check;
7058 .RI SConf.Define( context ", " symbol ", [" value ", " comment ])
7060 .IR sconf .Define( symbol ", [" value ", " comment ])
7061 This function does not check for anything, but defines a
7062 preprocessor symbol that will be added to the configuration header file.
7063 It is the equivalent of AC_DEFINE,
7064 and defines the symbol
7068 and the optional comment
7076 conf = Configure( env )
7078 # Puts the following line in the config header file:
7080 conf.Define('A_SYMBOL')
7082 # Puts the following line in the config header file:
7083 # #define A_SYMBOL 1
7084 conf.Define('A_SYMBOL', 1)
7088 Be careful about quoting string values, though:
7092 conf = Configure( env )
7094 # Puts the following line in the config header file:
7095 # #define A_SYMBOL YA
7096 conf.Define('A_SYMBOL', "YA")
7098 # Puts the following line in the config header file:
7099 # #define A_SYMBOL "YA"
7100 conf.Define('A_SYMBOL', '"YA"')
7108 conf = Configure( env )
7110 # Puts the following lines in the config header file:
7111 # /* Set to 1 if you have a symbol */
7112 # #define A_SYMBOL 1
7113 conf.Define('A_SYMBOL', 1, 'Set to 1 if you have a symbol')
7117 You can define your own custom checks.
7118 in addition to the predefined checks.
7119 These are passed in a dictionary to the Configure function.
7120 This dictionary maps the names of the checks
7121 to user defined Python callables
7122 (either Python functions or class instances implementing the
7125 The first argument of the call is always a
7127 instance followed by the arguments,
7128 which must be supplied by the user of the check.
7129 These CheckContext instances define the following methods:
7132 .RI CheckContext.Message( self ", " text )
7134 Usually called before the check is started.
7136 will be displayed to the user, e.g. 'Checking for library X...'
7139 .RI CheckContext.Result( self, ", " res )
7141 Usually called after the check is done.
7143 can be either an integer or a string. In the former case, 'ok' (res != 0)
7144 or 'failed' (res == 0) is displayed to the user, in the latter case the
7145 given string is displayed.
7148 .RI CheckContext.TryCompile( self ", " text ", " extension )
7149 Checks if a file with the specified
7151 (e.g. '.c') containing
7153 can be compiled using the environment's
7155 builder. Returns 1 on success and 0 on failure.
7158 .RI CheckContext.TryLink( self ", " text ", " extension )
7159 Checks, if a file with the specified
7161 (e.g. '.c') containing
7163 can be compiled using the environment's
7165 builder. Returns 1 on success and 0 on failure.
7168 .RI CheckContext.TryRun( self ", " text ", " extension )
7169 Checks, if a file with the specified
7171 (e.g. '.c') containing
7173 can be compiled using the environment's
7175 builder. On success, the program is run. If the program
7176 executes successfully
7177 (that is, its return status is 0),
7182 is the standard output of the
7184 If the program fails execution
7185 (its return status is non-zero),
7186 then (0, '') is returned.
7189 .RI CheckContext.TryAction( self ", " action ", [" text ", " extension ])
7190 Checks if the specified
7192 with an optional source file (contents
7199 may be anything which can be converted to a
7206 is the content of the target file.
7212 .RI CheckContext.TryBuild( self ", " builder ", [" text ", " extension ])
7213 Low level implementation for testing specific builds;
7214 the methods above are based on this method.
7215 Given the Builder instance
7219 of a source file with optional
7221 this method returns 1 on success and 0 on failure. In addition,
7223 is set to the build target node, if the build was successful.
7226 Example for implementing and using custom tests:
7229 def CheckQt(context, qtdir):
7230 context.Message( 'Checking for qt ...' )
7231 lastLIBS = context.env['LIBS']
7232 lastLIBPATH = context.env['LIBPATH']
7233 lastCPPPATH= context.env['CPPPATH']
7234 context.env.Append(LIBS = 'qt', LIBPATH = qtdir + '/lib', CPPPATH = qtdir + '/include' )
7235 ret = context.TryLink("""
7237 int main(int argc, char **argv) {
7238 QApplication qapp(argc, argv);
7243 context.env.Replace(LIBS = lastLIBS, LIBPATH=lastLIBPATH, CPPPATH=lastCPPPATH)
7244 context.Result( ret )
7248 conf = Configure( env, custom_tests = { 'CheckQt' : CheckQt } )
7249 if not conf.CheckQt('/usr/lib/qt'):
7250 print 'We really need qt!'
7255 .SS Command-Line Construction Variables
7257 Often when building software,
7258 some variables must be specified at build time.
7259 For example, libraries needed for the build may be in non-standard
7260 locations, or site-specific compiler options may need to be passed to the
7265 object to support overriding construction variables
7266 on the command line:
7268 $ scons VARIABLE=foo
7270 The variable values can also be specified in a text-based SConscript file.
7271 To create a Variables object, call the Variables() function:
7274 .RI Variables([ files "], [" args ])
7275 This creates a Variables object that will read construction variables from
7276 the file or list of filenames specified in
7278 If no files are specified,
7283 then no files will be read.
7284 The optional argument
7287 values that will override anything read from the specified files;
7288 it is primarily intended to be passed the
7290 dictionary that holds variables
7291 specified on the command line.
7295 vars = Variables('custom.py')
7296 vars = Variables('overrides.py', ARGUMENTS)
7297 vars = Variables(None, {FOO:'expansion', BAR:7})
7300 Variables objects have the following methods:
7303 .RI Add( key ", [" help ", " default ", " validator ", " converter ])
7304 This adds a customizable construction variable to the Variables object.
7306 is the name of the variable.
7308 is the help text for the variable.
7310 is the default value of the variable;
7311 if the default value is
7313 and there is no explicit value specified,
7314 the construction variable will
7316 be added to the construction environment.
7318 is called to validate the value of the variable, and should take three
7319 arguments: key, value, and environment.
7320 The recommended way to handle an invalid value is
7321 to raise an exception (see example below).
7323 is called to convert the value before putting it in the environment, and
7324 should take either a value, or the value and environment, as parameters.
7327 must return a value,
7328 which will be converted into a string
7329 before being validated by the
7332 and then added to the environment.
7337 vars.Add('CC', 'The C compiler')
7339 def validate_color(key, val, env):
7340 if not val in ['red', 'blue', 'yellow']:
7341 raise "Invalid color value '%s'" % val
7342 vars.Add('COLOR', validator=valid_color)
7346 .RI AddVariables( list )
7347 A wrapper script that adds
7348 multiple customizable construction variables
7349 to a Variables object.
7351 is a list of tuple or list objects
7352 that contain the arguments
7353 for an individual call to the
7360 ('CC', 'The C compiler'),
7361 ('VALIDATE', 'An option for testing validation',
7362 'notset', validator, None),
7367 .RI Update( env ", [" args ])
7368 This updates a construction environment
7370 with the customized construction variables.
7371 Any specified variables that are
7373 configured for the Variables object
7374 will be saved and may be
7376 .BR UnknownVariables ()
7379 Normally this method is not called directly,
7380 but is called indirectly by passing the Variables object to
7381 the Environment() function:
7384 env = Environment(variables=vars)
7388 The text file(s) that were specified
7389 when the Variables object was created
7390 are executed as Python scripts,
7391 and the values of (global) Python variables set in the file
7392 are added to the construction environment.
7401 .RI UnknownVariables( )
7402 Returns a dictionary containing any
7403 variables that were specified
7404 either in the files or the dictionary
7405 with which the Variables object was initialized,
7406 but for which the Variables object was
7410 env = Environment(variables=vars)
7411 for key, value in vars.UnknownVariables():
7412 print "unknown variable: %s=%s" % (key, value)
7416 .RI Save( filename ", " env )
7417 This saves the currently set variables into a script file named
7419 that can be used on the next invocation to automatically load the current
7420 settings. This method combined with the Variables method can be used to
7421 support caching of variables between runs.
7425 vars = Variables(['variables.cache', 'custom.py'])
7428 vars.Save('variables.cache', env)
7432 .RI GenerateHelpText( env ", [" sort ])
7433 This generates help text documenting the customizable construction
7434 variables suitable to passing in to the Help() function.
7436 is the construction environment that will be used to get the actual values
7437 of customizable variables. Calling with
7441 will cause the output to be sorted
7442 by the specified argument.
7446 should take two arguments
7449 (like the standard Python
7454 Help(vars.GenerateHelpText(env))
7455 Help(vars.GenerateHelpText(env, sort=cmp))
7459 .RI FormatVariableHelpText( env ", " opt ", " help ", " default ", " actual )
7460 This method returns a formatted string
7461 containing the printable help text
7463 It is normally not called directly,
7464 but is called by the
7465 .IR GenerateHelpText ()
7466 method to create the returned help text.
7467 It may be overridden with your own
7468 function that takes the arguments specified above
7469 and returns a string of help text formatted to your liking.
7471 .IR GenerateHelpText ()
7472 will not put any blank lines or extra
7473 characters in between the entries,
7474 so you must add those characters to the returned
7475 string if you want the entries separated.
7478 def my_format(env, opt, help, default, actual):
7479 fmt = "\n%s: default=%s actual=%s (%s)\n"
7480 return fmt % (opt, default. actual, help)
7481 vars.FormatVariableHelpText = my_format
7484 To make it more convenient to work with customizable Variables,
7486 provides a number of functions
7487 that make it easy to set up
7488 various types of Variables:
7491 .RI BoolVariable( key ", " help ", " default )
7492 Return a tuple of arguments
7493 to set up a Boolean option.
7497 have a default value of
7499 and display the specified
7502 The option will interpret the values
7524 .RI EnumVariable( key ", " help ", " default ", " allowed_values ", [" map ", " ignorecase ])
7525 Return a tuple of arguments
7527 whose value may be one
7528 of a specified list of legal enumerated values.
7532 have a default value of
7534 and display the specified
7537 The option will only support those
7543 argument is a dictionary
7544 that can be used to convert
7545 input values into specific legal values
7554 then the values are case-sensitive.
7559 then values will be matched
7565 then values will be matched
7567 and all input values will be
7568 converted to lower case.
7571 .RI ListVariable( key ", " help ", " default ", " names ", [", map ])
7572 Return a tuple of arguments
7574 whose value may be one or more
7575 of a specified list of legal enumerated values.
7579 have a default value of
7581 and display the specified
7584 The option will only support the values
7587 or the values in the
7590 More than one value may be specified,
7591 with all values separated by commas.
7592 The default may be a string of
7593 comma-separated default values,
7594 or a list of the default values.
7597 argument is a dictionary
7598 that can be used to convert
7599 input values into specific legal values
7605 .RI PackageVariable( key ", " help ", " default )
7606 Return a tuple of arguments
7608 whose value is a path name
7609 of a package that may be
7610 enabled, disabled or
7611 given an explicit path name.
7615 have a default value of
7617 and display the specified
7620 The option will support the values
7627 in which case the specified
7630 or the option may be set to an
7632 (typically the path name to a package
7633 that is being enabled).
7634 The option will also support the values
7640 to disable use of the specified option.
7643 .RI PathVariable( key ", " help ", " default ", [" validator ])
7644 Return a tuple of arguments
7646 whose value is expected to be a path name.
7650 have a default value of
7652 and display the specified
7658 that will be called to
7659 verify that the specified path
7662 following ready-made validators:
7663 .BR PathVariable.PathExists
7665 which verifies that the specified path exists;
7666 .BR PathVariable.PathIsFile ,
7667 which verifies that the specified path is an existing file;
7668 .BR PathVariable.PathIsDir ,
7669 which verifies that the specified path is an existing directory;
7670 .BR PathVariable.PathIsDirCreate ,
7671 which verifies that the specified path is a directory
7672 and will create the specified directory if the path does not exist;
7674 .BR PathVariable.PathAccept ,
7675 which simply accepts the specific path name argument without validation,
7676 and which is suitable if you want your users
7677 to be able to specify a directory path that will be
7678 created as part of the build process, for example.
7679 You may supply your own
7682 which must take three arguments
7684 the name of the variable to be set;
7686 the specified value being checked;
7689 the construction environment)
7690 and should raise an exception
7691 if the specified value is not acceptable.
7694 These functions make it
7695 convenient to create a number
7696 of variables with consistent behavior
7697 in a single call to the
7703 BoolVariable('warnings', 'compilation with -Wall and similiar', 1),
7704 EnumVariable('debug', 'debug output and symbols', 'no'
7705 allowed_values=('yes', 'no', 'full'),
7706 map={}, ignorecase=0), # case sensitive
7707 ListVariable('shared',
7708 'libraries to build as shared libraries',
7710 names = list_of_libs),
7711 PackageVariable('x11',
7712 'use X11 installed here (yes = search some places)',
7714 PathVariable('qtdir', 'where the root of Qt is installed', qtdir),
7715 PathVariable('foopath', 'where the foo library is installed', foopath,
7716 PathVariable.PathIsDir),
7721 .SS File and Directory Nodes
7731 Nodes, respectively.
7732 python objects, respectively.
7733 Those objects have several user-visible attributes
7734 and methods that are often useful:
7740 This path is relative to the top-level directory
7744 The build path is the same as the source path if
7749 The absolute build path of the given file or directory.
7759 object representing the
7768 # Get the current build dir's path, relative to top.
7770 # Current dir's absolute path
7772 # Next line is always '.', because it is the top dir's path relative to itself.
7774 File('foo.c').srcnode().path # source path of the given source file.
7776 # Builders also return File objects:
7777 foo = env.Program('foo.c')
7778 print "foo will be built in %s"%foo.path
7785 Node can also be used to create
7786 file and subdirectory Nodes relative to the generating Node.
7789 Node will place the new Nodes within the directory it represents.
7792 node will place the new Nodes within its parent directory
7793 (that is, "beside" the file in question).
7798 (directory) Node and
7803 then these methods are available:
7807 Returns a directory Node for a subdirectory of
7814 Returns a file Node for a file within
7820 .IR d .Entry( name )
7821 Returns an unresolved Node within
7828 Returns a directory named
7830 within the parent directory of
7835 Returns a file named
7837 within the parent directory of
7841 .IR f .Entry( name )
7842 Returns an unresolved Node named
7844 within the parent directory of
7851 # Get a Node for a file within a directory
7852 incl = Dir('include')
7853 f = incl.File('header.h')
7855 # Get a Node for a subdirectory within a directory
7856 dist = Dir('project-3.2.1)
7857 src = dist.Dir('src')
7859 # Get a Node for a file in the same directory
7860 cfile = File('sample.c')
7861 hfile = cfile.File('sample.h')
7865 html = docs.Dir('html')
7866 index = html.File('index.html')
7867 css = index.File('app.css')
7873 can be extended to build different types of targets
7874 by adding new Builder objects
7875 to a construction environment.
7877 you should only need to add a new Builder object
7878 when you want to build a new type of file or other external target.
7879 If you just want to invoke a different compiler or other tool
7880 to build a Program, Object, Library, or any other
7881 type of output file for which
7883 already has an existing Builder,
7884 it is generally much easier to
7885 use those existing Builders
7886 in a construction environment
7887 that sets the appropriate construction variables
7890 Builder objects are created
7896 function accepts the following arguments:
7899 The command line string used to build the target from the source.
7902 a list of strings representing the command
7903 to be executed and its arguments
7904 (suitable for enclosing white space in an argument),
7906 mapping source file name suffixes to
7907 any combination of command line strings
7908 (if the builder should accept multiple source file extensions),
7911 (see the next section);
7912 or a list of any of the above.
7915 takes three arguments:
7917 - a list of source nodes,
7919 - a list of target nodes,
7921 - the construction environment.
7924 The prefix that will be prepended to the target file name.
7925 This may be specified as a:
7935 - a function or other callable that takes
7936 two arguments (a construction environment and a list of sources)
7937 and returns a prefix,
7942 - specifies a mapping from a specific source suffix (of the first
7943 source specified) to a corresponding target prefix. Both the source
7944 suffix and target prefix specifications may use environment variable
7945 substitution, and the target prefix (the 'value' entries in the
7946 dictionary) may also be a callable object. The default target prefix
7947 may be indicated by a dictionary entry with a key value of None.
7952 b = Builder("build_it < $SOURCE > $TARGET"
7955 def gen_prefix(env, sources):
7956 return "file-" + env['PLATFORM'] + '-'
7957 b = Builder("build_it < $SOURCE > $TARGET",
7958 prefix = gen_prefix)
7960 b = Builder("build_it < $SOURCE > $TARGET",
7961 suffix = { None: "file-",
7962 "$SRC_SFX_A": gen_prefix })
7966 The suffix that will be appended to the target file name.
7967 This may be specified in the same manner as the prefix above.
7968 If the suffix is a string, then
7970 will append a '.' to the beginning of the suffix if it's not already
7971 there. The string returned by callable object (or obtained from the
7972 dictionary) is untouched and must append its own '.' to the beginning
7976 b = Builder("build_it < $SOURCE > $TARGET"
7979 def gen_suffix(env, sources):
7980 return "." + env['PLATFORM'] + "-file"
7981 b = Builder("build_it < $SOURCE > $TARGET",
7982 suffix = gen_suffix)
7984 b = Builder("build_it < $SOURCE > $TARGET",
7985 suffix = { None: ".sfx1",
7986 "$SRC_SFX_A": gen_suffix })
7990 When set to any true value, causes
7992 to add the target suffix specified by the
7994 keyword to any target strings
7995 that have a different suffix.
7996 (The default behavior is to leave untouched
7997 any target file name that looks like it already has any suffix.)
8000 b1 = Builder("build_it < $SOURCE > $TARGET"
8002 b2 = Builder("build_it < $SOURCE > $TARGET"
8006 env['BUILDERS']['B1'] = b1
8007 env['BUILDERS']['B2'] = b2
8009 # Builds "foo.txt" because ensure_suffix is not set.
8010 env.B1('foo.txt', 'foo.in')
8012 # Builds "bar.txt.out" because ensure_suffix is set.
8013 env.B2('bar.txt', 'bar.in')
8017 The expected source file name suffix. This may be a string or a list
8021 A Scanner object that
8022 will be invoked to find
8023 implicit dependencies for this target file.
8024 This keyword argument should be used
8025 for Scanner objects that find
8026 implicit dependencies
8027 based only on the target file
8028 and the construction environment,
8031 (See the section "Scanner Objects," below,
8032 for information about creating Scanner objects.)
8035 A Scanner object that
8037 find implicit dependences in
8039 used to build this target file.
8040 This is where you would
8041 specify a scanner to
8044 lines in source files.
8047 Scanner object may be used to
8048 indicate that this Builder
8049 should scan directory trees
8050 for on-disk changes to files
8053 does not know about from other Builder or function calls.
8054 (See the section "Scanner Objects," below,
8055 for information about creating your own Scanner objects.)
8058 A factory function that the Builder will use
8059 to turn any targets specified as strings into SCons Nodes.
8061 SCons assumes that all targets are files.
8062 Other useful target_factory
8065 for when a Builder creates a directory target,
8068 for when a Builder can create either a file
8069 or directory target.
8074 MakeDirectoryBuilder = Builder(action=my_mkdir, target_factory=Dir)
8076 env.Append(BUILDERS = {'MakeDirectory':MakeDirectoryBuilder})
8077 env.MakeDirectory('new_directory', [])
8081 Note that the call to the MakeDirectory Builder
8082 needs to specify an empty source list
8083 to make the string represent the builder's target;
8084 without that, it would assume the argument is the source,
8085 and would try to deduce the target name from it,
8086 which in the absence of an automatically-added prefix or suffix
8087 would lead to a matching target and source name
8088 and a circular dependency.
8091 A factory function that the Builder will use
8092 to turn any sources specified as strings into SCons Nodes.
8094 SCons assumes that all source are files.
8095 Other useful source_factory
8098 for when a Builder uses a directory as a source,
8101 for when a Builder can use files
8102 or directories (or both) as sources.
8107 CollectBuilder = Builder(action=my_mkdir, source_factory=Entry)
8109 env.Append(BUILDERS = {'Collect':CollectBuilder})
8110 env.Collect('archive', ['directory_name', 'file_name'])
8114 A function or list of functions to manipulate the target and source
8115 lists before dependencies are established
8116 and the target(s) are actually built.
8118 can also be a string containing a construction variable to expand
8119 to an emitter function or list of functions,
8120 or a dictionary mapping source file suffixes
8121 to emitter functions.
8122 (Only the suffix of the first source file
8123 is used to select the actual emitter function
8124 from an emitter dictionary.)
8127 takes three arguments:
8129 - a list of source nodes,
8131 - a list of target nodes,
8133 - the construction environment.
8134 An emitter must return a tuple containing two lists,
8135 the list of targets to be built by this builder,
8136 and the list of sources for this builder.
8141 def e(target, source, env):
8142 return (target + ['foo.foo'], source + ['foo.src'])
8144 # Simple association of an emitter function with a Builder.
8145 b = Builder("my_build < $TARGET > $SOURCE",
8148 def e2(target, source, env):
8149 return (target + ['bar.foo'], source + ['bar.src'])
8151 # Simple association of a list of emitter functions with a Builder.
8152 b = Builder("my_build < $TARGET > $SOURCE",
8155 # Calling an emitter function through a construction variable.
8156 env = Environment(MY_EMITTER = e)
8157 b = Builder("my_build < $TARGET > $SOURCE",
8158 emitter = '$MY_EMITTER')
8160 # Calling a list of emitter functions through a construction variable.
8161 env = Environment(EMITTER_LIST = [e, e2])
8162 b = Builder("my_build < $TARGET > $SOURCE",
8163 emitter = '$EMITTER_LIST')
8165 # Associating multiple emitters with different file
8166 # suffixes using a dictionary.
8167 def e_suf1(target, source, env):
8168 return (target + ['another_target_file'], source)
8169 def e_suf2(target, source, env):
8170 return (target, source + ['another_source_file'])
8171 b = Builder("my_build < $TARGET > $SOURCE",
8172 emitter = {'.suf1' : e_suf1,
8177 Specifies whether this builder is allowed to be called multiple times for
8178 the same target file(s). The default is 0, which means the builder
8179 can not be called multiple times for the same target file(s). Calling a
8180 builder multiple times for the same target simply adds additional source
8181 files to the target; it is not allowed to change the environment associated
8182 with the target, specify addition environment overrides, or associate a different
8183 builder with the target.
8186 A construction environment that can be used
8187 to fetch source code using this Builder.
8188 (Note that this environment is
8190 used for normal builds of normal target files,
8191 which use the environment that was
8192 used to call the Builder for the target file.)
8195 A function that returns a list of actions that will be executed to build
8196 the target(s) from the source(s).
8197 The returned action(s) may be
8198 an Action object, or anything that
8199 can be converted into an Action object
8200 (see the next section).
8202 The generator function
8203 takes four arguments:
8205 - a list of source nodes,
8207 - a list of target nodes,
8209 - the construction environment,
8211 - a Boolean value that specifies
8212 whether the generator is being called
8213 for generating a build signature
8214 (as opposed to actually executing the command).
8218 def g(source, target, env, for_signature):
8219 return [["gcc", "-c", "-o"] + target + source]
8221 b = Builder(generator=g)
8229 arguments must not both be used for the same Builder.
8232 Specifies a builder to use when a source file name suffix does not match
8233 any of the suffixes of the builder. Using this argument produces a
8234 multi-stage builder.
8237 Specifies that this builder expects exactly one source file per call. Giving
8238 more than one source files without target files results in implicitely calling
8239 the builder multiple times (once for each source given). Giving multiple
8240 source files together with target files results in a UserError exception.
8248 arguments must not both be used for the same Builder.
8250 .IP source_ext_match
8253 argument is a dictionary,
8254 the default behavior when a builder is passed
8255 multiple source files is to make sure that the
8256 extensions of all the source files match.
8257 If it is legal for this builder to be
8258 called with a list of source files with different extensions,
8259 this check can be suppressed by setting
8263 or some other non-true value.
8268 will use the suffix of the first specified
8269 source file to select the appropriate action from the
8273 In the following example,
8278 from exiting with an error
8279 due to the mismatched suffixes of
8285 b = Builder(action={'.in' : 'build $SOURCES > $TARGET'},
8286 source_ext_match = None)
8288 env = Environment(BUILDERS = {'MyBuild':b})
8289 env.MyBuild('foo.out', ['foo.in', 'foo.extra'])
8293 A construction environment that can be used
8294 to fetch source code using this Builder.
8295 (Note that this environment is
8297 used for normal builds of normal target files,
8298 which use the environment that was
8299 used to call the Builder for the target file.)
8302 b = Builder(action="build < $SOURCE > $TARGET")
8303 env = Environment(BUILDERS = {'MyBuild' : b})
8304 env.MyBuild('foo.out', 'foo.in', my_arg = 'xyzzy')
8308 A directory from which scons
8315 a string or a directory Node,
8316 scons will change to the specified directory.
8319 is not a string or Node
8321 then scons will change to the
8322 target file's directory.
8324 Note that scons will
8326 automatically modify
8328 construction variables like
8332 when using the chdir
8333 keyword argument--that is,
8334 the expanded file names
8335 will still be relative to
8336 the top-level SConstruct directory,
8337 and consequently incorrect
8338 relative to the chdir directory.
8339 Builders created using chdir keyword argument,
8340 will need to use construction variable
8345 to use just the filename portion of the
8349 b = Builder(action="build < ${SOURCE.file} > ${TARGET.file}",
8351 env = Environment(BUILDERS = {'MyBuild' : b})
8352 env.MyBuild('sub/dir/foo.out', 'sub/dir/foo.in')
8356 Python only keeps one current directory
8357 location for all of the threads.
8358 This means that use of the
8366 because individual worker threads spawned
8367 by SCons interfere with each other
8368 when they start changing directory.
8371 Any additional keyword arguments supplied
8372 when a Builder object is created
8373 (that is, when the Builder() function is called)
8374 will be set in the executing construction
8375 environment when the Builder object is called.
8376 The canonical example here would be
8377 to set a construction variable to
8378 the repository of a source code system.
8380 Any additional keyword arguments supplied
8384 will only be associated with the target
8385 created by that particular Builder call
8386 (and any other files built as a
8387 result of the call).
8389 These extra keyword arguments are passed to the
8390 following functions:
8391 command generator functions,
8393 and emitter functions.
8399 function will turn its
8401 keyword argument into an appropriate
8402 internal Action object.
8403 You can also explicity create Action objects
8407 which can then be passed to the
8410 This can be used to configure
8411 an Action object more flexibly,
8412 or it may simply be more efficient
8413 than letting each separate Builder object
8414 create a separate Action
8416 Builder objects need to do the same thing.
8421 returns an appropriate object for the action
8422 represented by the type of the first argument:
8425 If the first argument is already an Action object,
8426 the object is simply returned.
8429 If the first argument is a string,
8430 a command-line Action is returned.
8431 Note that the command line string
8432 may be preceded by an
8435 to suppress printing of the
8436 specified command line,
8440 to ignore the exit status from
8441 the specified command.
8445 Action('$CC -c -o $TARGET $SOURCES')
8447 # Doesn't print the line being executed.
8448 Action('@build $TARGET $SOURCES')
8451 Action('-build $TARGET $SOURCES')
8454 .\" XXX From Gary Ruben, 23 April 2002:
8455 .\" What would be useful is a discussion of how you execute command
8456 .\" shell commands ie. what is the process used to spawn the shell, pass
8457 .\" environment variables to it etc., whether there is one shell per
8458 .\" environment or one per command etc. It might help to look at the Gnu
8459 .\" make documentation to see what they think is important to discuss about
8460 .\" a build system. I'm sure you can do a better job of organising the
8461 .\" documentation than they have :-)
8465 If the first argument is a list,
8466 then a list of Action objects is returned.
8467 An Action object is created as necessary
8468 for each element in the list.
8471 the list is itself a list,
8472 the internal list is the
8473 command and arguments to be executed via
8475 This allows white space to be enclosed
8476 in an argument by defining
8477 a command in a list within a list:
8480 Action([['cc', '-c', '-DWHITE SPACE', '-o', '$TARGET', '$SOURCES']])
8484 If the first argument is a Python function,
8485 a function Action is returned.
8486 The Python function takes three keyword arguments,
8488 (a Node object representing the target file),
8490 (a Node object representing the source file)
8493 (the construction environment
8494 used for building the target file).
8499 arguments may be lists of Node objects if there is
8500 more than one target file or source file.
8501 The actual target and source file name(s) may
8502 be retrieved from their Node objects
8503 via the built-in Python str() function:
8506 target_file_name = str(target)
8507 source_file_names = map(lambda x: str(x), source)
8510 The function should return
8514 to indicate a successful build of the target file(s).
8515 The function may raise an exception
8516 or return a non-zero exit status
8517 to indicate an unsuccessful build.
8520 def build_it(target = None, source = None, env = None):
8521 # build the target from the source
8524 a = Action(build_it)
8527 If the action argument is not one of the above,
8531 The second, optional argument
8532 is used to define the output which is printed
8533 when the Action is actually performed.
8534 In the absence of this parameter, or if it's an
8535 empty string, a default output depending on the type of the action
8536 is used. For example, a command-line action will print
8537 the executed command. The argument is either a python function
8540 In the first case, it's a function that returns
8541 a string to be printed to describe the action being executed.
8542 Like a function to build a file,
8543 this function takes three arguments:
8545 (a Node object representing the target file),
8547 (a Node object representing the source file)
8550 (a construction environment).
8555 arguments may be lists of Node objects if there is
8556 more than one target file or source file.
8558 In the second case, you provide the string itself.
8559 The string typically contains variables, notably
8560 $TARGET(S) and $SOURCE(S), or consists of just a single
8561 variable, which is optionally defined somewhere else.
8562 SCons itself heavily uses the latter variant.
8567 def build_it(target, source, env):
8568 # build the target from the source
8571 def string_it(target, source, env):
8572 return "building '%s' from '%s'" % (target[0], source[0])
8574 # Use a positional argument.
8575 f = Action(build_it, string_it)
8576 s = Action(build_it, "building '$TARGET' from '$SOURCE'")
8578 # Alternatively, use a keyword argument.
8579 f = Action(build_it, strfunction=string_it)
8580 s = Action(build_it, cmdstr="building '$TARGET' from '$SOURCE'")
8582 # You can provide a configurable variable.
8583 l = Action(build_it, '$STRINGIT')
8586 The third, also optional argument
8587 is a list of construction variables
8588 whose values will be included
8589 in the signature of the Action
8590 when deciding whether a target should
8591 be rebuilt because the action changed.
8592 This is necessary whenever you want a target to
8593 be rebuilt when a specific
8594 construction variable changes,
8595 because the underlying Python code for a function
8596 will not change when the value of the construction variable does.
8599 def build_it(target, source, env):
8600 # build the target from the 'XXX' construction variable
8601 open(target[0], 'w').write(env['XXX'])
8604 # Use positional arguments.
8605 a = Action(build_it, '$STRINGIT', ['XXX'])
8607 # Alternatively, use a keyword argument.
8608 a = Action(build_it, varlist=['XXX'])
8617 which specifies that
8618 scons will execute the action
8619 after changing to the specified directory.
8620 If the chdir argument is
8621 a string or a directory Node,
8622 scons will change to the specified directory.
8623 If the chdir argument
8624 is not a string or Node
8626 then scons will change to the
8627 target file's directory.
8629 Note that scons will
8631 automatically modify
8633 construction variables like
8637 when using the chdir
8638 keyword argument--that is,
8639 the expanded file names
8640 will still be relative to
8641 the top-level SConstruct directory,
8642 and consequently incorrect
8643 relative to the chdir directory.
8644 Builders created using chdir keyword argument,
8645 will need to use construction variable
8650 to use just the filename portion of the
8654 a = Action("build < ${SOURCE.file} > ${TARGET.file}",
8664 which specifies a function
8665 that is passed the exit status
8667 from the specified action
8668 and can return an arbitrary
8670 This can be used, for example,
8671 to specify that an Action object's
8672 return value should be ignored
8673 and SCons should, therefore,
8674 consider that the action always suceeds:
8677 def always_succeed(s):
8678 # Always return 0, which indicates success.
8680 a = Action("build < ${SOURCE.file} > ${TARGET.file}",
8681 exitstatfunc=always_succeed)
8684 .SS Miscellaneous Action Functions
8687 supplies a number of functions
8688 that arrange for various common
8689 file and directory manipulations
8691 These are similar in concept to "tasks" in the
8693 although the implementation is slightly different.
8694 These functions do not actually
8695 perform the specified action
8696 at the time the function is called,
8697 but instead return an Action object
8698 that can be executed at the
8700 (In Object-Oriented terminology,
8705 that return Action objects.)
8708 there are two natural ways
8711 are intended to be used.
8715 to perform the action
8716 at the time the SConscript
8720 global function to do so:
8722 Execute(Touch('file'))
8726 you can use these functions
8727 to supply Actions in a list
8731 This can allow you to
8732 perform more complicated
8733 sequences of file manipulation
8735 on platform-specific
8739 env = Environment(TMPBUILD = '/tmp/builddir')
8740 env.Command('foo.out', 'foo.in',
8741 [Mkdir('$TMPBUILD'),
8742 Copy('$TMPBUILD', '${SOURCE.dir}'),
8743 "cd $TMPBUILD && make",
8744 Delete('$TMPBUILD')])
8748 .RI Chmod( dest ", " mode )
8749 Returns an Action object that
8750 changes the permissions on the specified
8752 file or directory to the specified
8757 Execute(Chmod('file', 0755))
8759 env.Command('foo.out', 'foo.in',
8760 [Copy('$TARGET', '$SOURCE'),
8761 Chmod('$TARGET', 0755)])
8765 .RI Copy( dest ", " src )
8766 Returns an Action object
8769 source file or directory to the
8771 destination file or directory.
8775 Execute(Copy('foo.output', 'foo.input'))
8777 env.Command('bar.out', 'bar.in',
8778 Copy('$TARGET', '$SOURCE'))
8782 .RI Delete( entry ", [" must_exist ])
8783 Returns an Action that
8784 deletes the specified
8786 which may be a file or a directory tree.
8787 If a directory is specified,
8788 the entire directory tree
8793 then a Python error will be thrown
8794 if the specified entry does not exist;
8797 that is, the Action will silently do nothing
8798 if the entry does not exist.
8802 Execute(Delete('/tmp/buildroot'))
8804 env.Command('foo.out', 'foo.in',
8805 [Delete('${TARGET.dir}'),
8808 Execute(Delete('file_that_must_exist', must_exist=1))
8814 that creates the specified
8820 Execute(Mkdir('/tmp/outputdir'))
8822 env.Command('foo.out', 'foo.in',
8823 [Mkdir('/tmp/builddir',
8824 Copy('$SOURCE', '/tmp/builddir/foo.in')
8825 "cd /tmp/builddir && make",
8826 Copy('/tmp/builddir/foo.out', '$TARGET')])
8830 .RI Move( dest ", " src )
8832 that moves the specified
8834 file or directory to
8841 Execute(Move('file.destination', 'file.source'))
8843 env.Command('output_file', 'input_file',
8845 Move('$TARGET', 'file_created_by_MyBuildAction')])
8851 that updates the modification time
8857 Execute(Touch('file_to_be_touched'))
8859 env.Command('marker', 'input_file',
8864 .SS Variable Substitution
8866 Before executing a command,
8868 performs construction variable interpolation on the strings that make up
8869 the command line of builders.
8870 Variables are introduced by a
8873 Besides construction variables, scons provides the following
8874 variables for each command execution:
8877 The file name of the target being built, or the file name of the first
8878 target if multiple targets are being built.
8881 The file names of all targets being built.
8884 The file name of the source of the build command, or the file name of the
8885 first source if multiple sources are being built.
8888 The file names of the sources of the build command.
8890 (Note that the above variables are reserved
8891 and may not be set in a construction environment.)
8894 For example, given the construction variable CC='cc', targets=['foo'], and
8895 sources=['foo.c', 'bar.c']:
8898 action='$CC -c -o $TARGET $SOURCES'
8901 would produce the command line:
8904 cc -c -o foo foo.c bar.c
8907 Variable names may be surrounded by curly braces ({})
8908 to separate the name from the trailing characters.
8909 Within the curly braces, a variable name may have
8910 a Python slice subscript appended to select one
8911 or more items from a list.
8912 In the previous example, the string:
8924 Additionally, a variable name may
8925 have the following special
8926 modifiers appended within the enclosing curly braces
8927 to modify the interpolated string:
8930 The base path of the file name,
8931 including the directory path
8932 but excluding any suffix.
8935 The name of the directory in which the file exists.
8939 minus any directory portion.
8942 Just the basename of the file,
8944 and minus the directory.
8947 Just the file suffix.
8950 The absolute path name of the file.
8953 The POSIX form of the path,
8954 with directories separated by
8958 This is sometimes necessary on Windows systems
8959 when a path references a file on other (POSIX) systems.
8962 The directory and file name to the source file linked to this file through
8964 If this file isn't linked,
8965 it just returns the directory and filename unchanged.
8968 The directory containing the source file linked to this file through
8970 If this file isn't linked,
8971 it just returns the directory part of the filename.
8974 The directory and file name to the source file linked to this file through
8976 If the file does not exist locally but exists in a Repository,
8977 the path in the Repository is returned.
8978 If this file isn't linked, it just returns the
8979 directory and filename unchanged.
8982 The Repository directory containing the source file linked to this file through
8984 If this file isn't linked,
8985 it just returns the directory part of the filename.
8988 For example, the specified target will
8989 expand as follows for the corresponding modifiers:
8992 $TARGET => sub/dir/file.x
8993 ${TARGET.base} => sub/dir/file
8994 ${TARGET.dir} => sub/dir
8995 ${TARGET.file} => file.x
8996 ${TARGET.filebase} => file
8997 ${TARGET.suffix} => .x
8998 ${TARGET.abspath} => /top/dir/sub/dir/file.x
9000 SConscript('src/SConscript', variant_dir='sub/dir')
9001 $SOURCE => sub/dir/file.x
9002 ${SOURCE.srcpath} => src/file.x
9003 ${SOURCE.srcdir} => src
9005 Repository('/usr/repository')
9006 $SOURCE => sub/dir/file.x
9007 ${SOURCE.rsrcpath} => /usr/repository/src/file.x
9008 ${SOURCE.rsrcdir} => /usr/repository/src
9011 Note that curly braces braces may also be used
9012 to enclose arbitrary Python code to be evaluated.
9013 (In fact, this is how the above modifiers are substituted,
9014 they are simply attributes of the Python objects
9015 that represent TARGET, SOURCES, etc.)
9016 See the section "Python Code Substitution," below,
9017 for more thorough examples of
9018 how this can be used.
9020 Lastly, a variable name
9021 may be a callable Python function
9023 construction variable in the environment.
9025 take four arguments:
9027 - a list of target nodes,
9029 - a list of source nodes,
9031 - the construction environment,
9033 - a Boolean value that specifies
9034 whether the function is being called
9035 for generating a build signature.
9036 SCons will insert whatever
9037 the called function returns
9038 into the expanded string:
9041 def foo(target, source, env, for_signature):
9044 # Will expand $BAR to "bar baz"
9045 env=Environment(FOO=foo, BAR="$FOO baz")
9048 You can use this feature to pass arguments to a
9049 Python function by creating a callable class
9050 that stores one or more arguments in an object,
9051 and then uses them when the
9054 Note that in this case,
9055 the entire variable expansion must
9056 be enclosed by curly braces
9057 so that the arguments will
9058 be associated with the
9059 instantiation of the class:
9063 def __init__(self, arg):
9066 def __call__(self, target, source, env, for_signature):
9067 return self.arg + " bar"
9069 # Will expand $BAR to "my argument bar baz"
9070 env=Environment(FOO=foo, BAR="${FOO('my argument')} baz")
9074 The special pseudo-variables
9078 may be used to surround parts of a command line
9081 causing a rebuild--that is,
9082 which are not included in the signature
9083 of target files built with this command.
9088 will be removed from the command line
9089 before it is added to file signatures,
9094 will be removed before the command is executed.
9095 For example, the command line:
9098 echo Last build occurred $( $TODAY $). > $TARGET
9102 would execute the command:
9105 echo Last build occurred $TODAY. > $TARGET
9109 but the command signature added to any target files would be:
9112 echo Last build occurred . > $TARGET
9115 .SS Python Code Substitution
9117 Any python code within
9119 pairs gets evaluated by python 'eval', with the python globals set to
9120 the current environment's set of construction variables.
9121 So in the following case:
9124 env.Command('foo.out', 'foo.in',
9125 '''echo ${COND==1 and 'FOO' or 'BAR'} > $TARGET''')
9127 the command executed will be either
9135 according to the current value of env['COND'] when the command is
9136 executed. The evaluation occurs when the target is being
9137 built, not when the SConscript is being read. So if env['COND'] is changed
9138 later in the SConscript, the final value will be used.
9140 Here's a more interesting example. Note that all of COND, FOO, and
9141 BAR are environment variables, and their values are substituted into
9142 the final command. FOO is a list, so its elements are interpolated
9143 separated by spaces.
9148 env['FOO'] = ['foo1', 'foo2']
9149 env['BAR'] = 'barbar'
9150 env.Command('foo.out', 'foo.in',
9151 'echo ${COND==1 and FOO or BAR} > $TARGET')
9153 # Will execute this:
9154 # echo foo1 foo2 > foo.out
9157 SCons uses the following rules when converting construction variables into
9161 When the value is a string it is interpreted as a space delimited list of
9162 command line arguments.
9165 When the value is a list it is interpreted as a list of command line
9166 arguments. Each element of the list is converted to a string.
9169 Anything that is not a list or string is converted to a string and
9170 interpreted as a single command line argument.
9173 Newline characters (\\n) delimit lines. The newline parsing is done after
9174 all other parsing, so it is not possible for arguments (e.g. file names) to
9175 contain embedded newline characters. This limitation will likely go away in
9176 a future version of SCons.
9184 new file types for implicit dependencies.
9185 Scanner accepts the following arguments:
9189 1) a Python function that will process
9191 and return a list of strings (file names)
9192 representing the implicit
9193 dependencies found in the contents;
9195 2) a dictionary that maps keys
9196 (typically the file suffix, but see below for more discussion)
9197 to other Scanners that should be called.
9199 If the argument is actually a Python function,
9200 the function must take three or four arguments:
9202 def scanner_function(node, env, path):
9204 def scanner_function(node, env, path, arg=None):
9208 argument is the internal
9209 SCons node representing the file.
9212 to fetch the name of the file, and
9213 .B node.get_contents()
9214 to fetch contents of the file.
9215 Note that the file is
9217 guaranteed to exist before the scanner is called,
9218 so the scanner function should check that
9219 if there's any chance that the scanned file
9221 (for example, if it's built from other files).
9225 argument is the construction environment for the scan.
9226 Fetch values from it using the
9232 argument is a tuple (or list)
9233 of directories that can be searched
9235 This will usually be the tuple returned by the
9237 argument (see below).
9241 argument is the argument supplied
9242 when the scanner was created, if any.
9245 The name of the Scanner.
9247 to identify the Scanner internally.
9250 An optional argument that, if specified,
9251 will be passed to the scanner function
9253 and the path function
9257 An optional list that can be used to
9258 determine which scanner should be used for
9260 In the usual case of scanning for file names,
9261 this argument will be a list of suffixes
9262 for the different file types that this
9263 Scanner knows how to scan.
9264 If the argument is a string,
9265 then it will be expanded
9266 into a list by the current environment.
9269 A Python function that takes four or five arguments:
9270 a construction environment,
9271 a Node for the directory containing
9272 the SConscript file in which
9273 the first target was defined,
9274 a list of target nodes,
9275 a list of source nodes,
9276 and an optional argument supplied
9277 when the scanner was created.
9280 returns a tuple of directories
9281 that can be searched for files to be returned
9282 by this Scanner object.
9285 function can be used to return a ready-made
9287 for a given construction variable name,
9288 instead of having to write your own function from scratch.)
9291 The class of Node that should be returned
9292 by this Scanner object.
9293 Any strings or other objects returned
9294 by the scanner function
9295 that are not of this class
9296 will be run through the
9301 A Python function that will take a string
9303 and turn it into the appropriate class of Node
9304 to be returned by this Scanner object.
9307 An optional Python function that takes two arguments,
9308 a Node (file) and a construction environment,
9309 and returns whether the
9310 Node should, in fact,
9311 be scanned for dependencies.
9312 This check can be used to eliminate unnecessary
9313 calls to the scanner function when,
9314 for example, the underlying file
9315 represented by a Node does not yet exist.
9318 An optional flag that
9319 specifies whether this scanner should be re-invoked
9320 on the dependency files returned by the scanner.
9321 When this flag is not set,
9322 the Node subsystem will
9323 only invoke the scanner on the file being scanned,
9324 and not (for example) also on the files
9325 specified by the #include lines
9326 in the file being scanned.
9328 may be a callable function,
9329 in which case it will be called with a list of
9331 should return a list of Nodes
9332 that should be scanned recursively;
9333 this can be used to select a specific subset of
9334 Nodes for additional scanning.
9339 .B SourceFileScanner
9340 object that is used by
9343 .BR SharedObject (),
9347 which scanner should be used
9348 for different file extensions.
9350 .BR SourceFileScanner.add_scanner ()
9351 method to add your own Scanner object
9355 that builds target programs or
9356 libraries from a list of
9357 source files of different types:
9360 def xyz_scan(node, env, path):
9361 contents = node.get_contents()
9362 # Scan the contents and return the included files.
9364 XYZScanner = Scanner(xyz_scan)
9366 SourceFileScanner.add_scanner('.xyx', XYZScanner)
9368 env.Program('my_prog', ['file1.c', 'file2.f', 'file3.xyz'])
9371 .SH SYSTEM-SPECIFIC BEHAVIOR
9372 SCons and its configuration files are very portable,
9373 due largely to its implementation in Python.
9374 There are, however, a few portability
9375 issues waiting to trap the unwary.
9377 SCons handles the upper-case
9379 file suffix differently,
9380 depending on the capabilities of
9381 the underlying system.
9382 On a case-sensitive system
9383 such as Linux or UNIX,
9384 SCons treats a file with a
9386 suffix as a C++ source file.
9387 On a case-insensitive system
9389 SCons treats a file with a
9391 suffix as a C source file.
9393 SCons handles the upper-case
9395 file suffix differently,
9396 depending on the capabilities of
9397 the underlying system.
9398 On a case-sensitive system
9399 such as Linux or UNIX,
9400 SCons treats a file with a
9402 suffix as a Fortran source file
9403 that is to be first run through
9404 the standard C preprocessor.
9405 On a case-insensitive system
9407 SCons treats a file with a
9409 suffix as a Fortran source file that should
9411 be run through the C preprocessor.
9412 .SS Windows: Cygwin Tools and Cygwin Python vs. Windows Pythons
9413 Cygwin supplies a set of tools and utilities
9414 that let users work on a
9415 Windows system using a more POSIX-like environment.
9416 The Cygwin tools, including Cygwin Python,
9418 by sharing an ability to interpret UNIX-like path names.
9419 For example, the Cygwin tools
9420 will internally translate a Cygwin path name
9421 like /cygdrive/c/mydir
9422 to an equivalent Windows pathname
9423 of C:/mydir (equivalent to C:\\mydir).
9426 that are built for native Windows execution,
9427 such as the python.org and ActiveState versions,
9428 do not have the Cygwin path name semantics.
9429 This means that using a native Windows version of Python
9430 to build compiled programs using Cygwin tools
9431 (such as gcc, bison, and flex)
9432 may yield unpredictable results.
9433 "Mixing and matching" in this way
9434 can be made to work,
9435 but it requires careful attention to the use of path names
9436 in your SConscript files.
9438 In practice, users can sidestep
9439 the issue by adopting the following rules:
9441 use the Cygwin-supplied Python interpreter
9443 when using Microsoft Visual C/C++
9444 (or some other Windows compiler)
9445 use the python.org or ActiveState version of Python
9447 .SS Windows: scons.bat file
9449 SCons is executed via a wrapper
9452 This has (at least) two ramifications:
9454 First, Windows command-line users
9455 that want to use variable assignment
9457 may have to put double quotes
9458 around the assignments:
9461 scons "FOO=BAR" "BAZ=BLEH"
9464 Second, the Cygwin shell does not
9465 recognize this file as being the same
9468 command issued at the command-line prompt.
9469 You can work around this either by
9472 from the Cygwin command line,
9473 or by creating a wrapper shell
9479 The MinGW bin directory must be in your PATH environment variable or the
9480 PATH variable under the ENV construction variable for SCons
9481 to detect and use the MinGW tools. When running under the native Windows
9482 Python interpreter, SCons will prefer the MinGW tools over the Cygwin
9483 tools, if they are both installed, regardless of the order of the bin
9484 directories in the PATH variable. If you have both MSVC and MinGW
9485 installed and you want to use MinGW instead of MSVC,
9486 then you must explictly tell SCons to use MinGW by passing
9492 to the Environment() function, because SCons will prefer the MSVC tools
9493 over the MinGW tools.
9497 To help you get started using SCons,
9498 this section contains a brief overview of some common tasks.
9500 .SS Basic Compilation From a Single Source File
9504 env.Program(target = 'foo', source = 'foo.c')
9507 Note: Build the file by specifying
9508 the target as an argument
9509 ("scons foo" or "scons foo.exe").
9510 or by specifying a dot ("scons .").
9512 .SS Basic Compilation From Multiple Source Files
9516 env.Program(target = 'foo', source = Split('f1.c f2.c f3.c'))
9519 .SS Setting a Compilation Flag
9522 env = Environment(CCFLAGS = '-g')
9523 env.Program(target = 'foo', source = 'foo.c')
9526 .SS Search The Local Directory For .h Files
9530 need to set CCFLAGS to specify -I options by hand.
9531 SCons will construct the right -I options from CPPPATH.
9534 env = Environment(CPPPATH = ['.'])
9535 env.Program(target = 'foo', source = 'foo.c')
9538 .SS Search Multiple Directories For .h Files
9541 env = Environment(CPPPATH = ['include1', 'include2'])
9542 env.Program(target = 'foo', source = 'foo.c')
9545 .SS Building a Static Library
9549 env.StaticLibrary(target = 'foo', source = Split('l1.c l2.c'))
9550 env.StaticLibrary(target = 'bar', source = ['l3.c', 'l4.c'])
9553 .SS Building a Shared Library
9557 env.SharedLibrary(target = 'foo', source = ['l5.c', 'l6.c'])
9558 env.SharedLibrary(target = 'bar', source = Split('l7.c l8.c'))
9561 .SS Linking a Local Library Into a Program
9564 env = Environment(LIBS = 'mylib', LIBPATH = ['.'])
9565 env.Library(target = 'mylib', source = Split('l1.c l2.c'))
9566 env.Program(target = 'prog', source = ['p1.c', 'p2.c'])
9569 .SS Defining Your Own Builder Object
9571 Notice that when you invoke the Builder,
9572 you can leave off the target file suffix,
9573 and SCons will add it automatically.
9576 bld = Builder(action = 'pdftex < $SOURCES > $TARGET'
9578 src_suffix = '.tex')
9579 env = Environment(BUILDERS = {'PDFBuilder' : bld})
9580 env.PDFBuilder(target = 'foo.pdf', source = 'foo.tex')
9582 # The following creates "bar.pdf" from "bar.tex"
9583 env.PDFBuilder(target = 'bar', source = 'bar')
9586 Note also that the above initialization
9587 overwrites the default Builder objects,
9588 so the Environment created above
9589 can not be used call Builders like env.Program(),
9590 env.Object(), env.StaticLibrary(), etc.
9592 .SS Adding Your Own Builder Object to an Environment
9595 bld = Builder(action = 'pdftex < $SOURCES > $TARGET'
9597 src_suffix = '.tex')
9599 env.Append(BUILDERS = {'PDFBuilder' : bld})
9600 env.PDFBuilder(target = 'foo.pdf', source = 'foo.tex')
9601 env.Program(target = 'bar', source = 'bar.c')
9604 You also can use other Pythonic techniques to add
9605 to the BUILDERS construction variable, such as:
9609 env['BUILDERS]['PDFBuilder'] = bld
9612 .SS Defining Your Own Scanner Object
9614 The following example shows an extremely simple scanner (the
9617 that doesn't use a search path at all
9618 and simply returns the
9619 file names present on any
9621 lines in the scanned file.
9622 This would implicitly assume that all included
9623 files live in the top-level directory:
9628 '\" Note: the \\ in the following are for the benefit of nroff/troff,
9629 '\" not inappropriate doubled escape characters within the r'' raw string.
9630 include_re = re.compile(r'^include\\s+(\\S+)$', re.M)
9632 def kfile_scan(node, env, path, arg):
9633 contents = node.get_contents()
9634 includes = include_re.findall(contents)
9637 kscan = Scanner(name = 'kfile',
9638 function = kfile_scan,
9641 scanners = Environment().Dictionary('SCANNERS')
9642 env = Environment(SCANNERS = scanners + [kscan])
9644 env.Command('foo', 'foo.k', 'kprocess < $SOURCES > $TARGET')
9646 bar_in = File('bar.in')
9647 env.Command('bar', bar_in, 'kprocess $SOURCES > $TARGET')
9648 bar_in.target_scanner = kscan
9651 Here is a similar but more complete example that searches
9652 a path of directories
9655 construction variable)
9656 for files that actually exist:
9659 include_re = re.compile(r'^include\\s+(\\S+)$', re.M)
9661 def my_scan(node, env, path, arg):
9662 contents = node.get_contents()
9663 includes = include_re.findall(contents)
9667 for inc in includes:
9669 file = dir + os.sep + inc
9670 if os.path.exists(file):
9671 results.append(file)
9675 scanner = Scanner(name = 'myscanner',
9679 path_function = FindPathDirs('MYPATH'),
9681 scanners = Environment().Dictionary('SCANNERS')
9682 env = Environment(SCANNERS = scanners + [scanner])
9687 function used in the previous example returns a function
9688 (actually a callable Python object)
9689 that will return a list of directories
9692 construction variable.
9693 If you need to customize how the search path is derived,
9694 you would provide your own
9696 argument when creating the Scanner object,
9700 # MYPATH is a list of directories to search for files in
9701 def pf(env, dir, target, source, arg):
9702 top_dir = Dir('#').abspath
9704 if env.has_key('MYPATH'):
9705 for p in env['MYPATH']:
9706 results.append(top_dir + os.sep + p)
9709 scanner = Scanner(name = 'myscanner',
9717 .SS Creating a Hierarchical Build
9719 Notice that the file names specified in a subdirectory's
9721 file are relative to that subdirectory.
9727 env.Program(target = 'foo', source = 'foo.c')
9729 SConscript('sub/SConscript')
9734 # Builds sub/foo from sub/foo.c
9735 env.Program(target = 'foo', source = 'foo.c')
9737 SConscript('dir/SConscript')
9742 # Builds sub/dir/foo from sub/dir/foo.c
9743 env.Program(target = 'foo', source = 'foo.c')
9746 .SS Sharing Variables Between SConscript Files
9748 You must explicitly Export() and Import() variables that
9749 you want to share between SConscript files.
9755 env.Program(target = 'foo', source = 'foo.c')
9758 SConscript('subdirectory/SConscript')
9760 subdirectory/SConscript:
9763 env.Program(target = 'foo', source = 'foo.c')
9766 .SS Building Multiple Variants From the Same Source
9768 Use the variant_dir keyword argument to
9769 the SConscript function to establish
9770 one or more separate variant build directory trees
9771 for a given source directory:
9776 cppdefines = ['FOO']
9777 Export("cppdefines")
9778 SConscript('src/SConscript', variant_dir='foo')
9780 cppdefines = ['BAR']
9781 Export("cppdefines")
9782 SConscript('src/SConscript', variant_dir='bar')
9786 Import("cppdefines")
9787 env = Environment(CPPDEFINES = cppdefines)
9788 env.Program(target = 'src', source = 'src.c')
9791 Note the use of the Export() method
9792 to set the "cppdefines" variable to a different
9793 value each time we call the SConscript function.
9795 .SS Hierarchical Build of Two Libraries Linked With a Program
9800 env = Environment(LIBPATH = ['#libA', '#libB'])
9802 SConscript('libA/SConscript')
9803 SConscript('libB/SConscript')
9804 SConscript('Main/SConscript')
9809 env.Library('a', Split('a1.c a2.c a3.c'))
9814 env.Library('b', Split('b1.c b2.c b3.c'))
9819 e = env.Copy(LIBS = ['a', 'b'])
9820 e.Program('foo', Split('m1.c m2.c m3.c'))
9823 The '#' in the LIBPATH directories specify that they're relative to the
9824 top-level directory, so they don't turn into "Main/libA" when they're
9825 used in Main/SConscript.
9827 Specifying only 'a' and 'b' for the library names
9828 allows SCons to append the appropriate library
9829 prefix and suffix for the current platform
9830 (for example, 'liba.a' on POSIX systems,
9831 \&'a.lib' on Windows).
9833 .SS Customizing construction variables from the command line.
9835 The following would allow the C compiler to be specified on the command
9836 line or in the file custom.py.
9839 vars = Variables('custom.py')
9840 vars.Add('CC', 'The C compiler.')
9841 env = Environment(variables=vars)
9842 Help(vars.GenerateHelpText(env))
9845 The user could specify the C compiler on the command line:
9851 or in the custom.py file:
9857 or get documentation on the options:
9868 .SS Using Microsoft Visual C++ precompiled headers
9870 Since windows.h includes everything and the kitchen sink, it can take quite
9871 some time to compile it over and over again for a bunch of object files, so
9872 Microsoft provides a mechanism to compile a set of headers once and then
9873 include the previously compiled headers in any object file. This
9874 technology is called precompiled headers. The general recipe is to create a
9875 file named "StdAfx.cpp" that includes a single header named "StdAfx.h", and
9876 then include every header you want to precompile in "StdAfx.h", and finally
9877 include "StdAfx.h" as the first header in all the source files you are
9878 compiling to object files. For example:
9882 #include <windows.h>
9883 #include <my_big_header.h>
9902 /* do some other stuff */
9908 env['PCHSTOP'] = 'StdAfx.h'
9909 env['PCH'] = env.PCH('StdAfx.cpp')[0]
9910 env.Program('MyApp', ['Foo.cpp', 'Bar.cpp'])
9913 For more information see the document for the PCH builder, and the PCH and
9914 PCHSTOP construction variables. To learn about the details of precompiled
9915 headers consult the MSDN documention for /Yc, /Yu, and /Yp.
9917 .SS Using Microsoft Visual C++ external debugging information
9919 Since including debugging information in programs and shared libraries can
9920 cause their size to increase significantly, Microsoft provides a mechanism
9921 for including the debugging information in an external file called a PDB
9922 file. SCons supports PDB files through the PDB construction
9928 env['PDB'] = 'MyApp.pdb'
9929 env.Program('MyApp', ['Foo.cpp', 'Bar.cpp'])
9932 For more information see the document for the PDB construction variable.
9937 Specifies the directory that contains the SCons Python module directory
9938 (e.g. /home/aroach/scons-src-0.01/src/engine).
9941 A string of options that will be used by scons in addition to those passed
9942 on the command line.
9953 Steven Knight <knight@baldmt.com>
9955 Anthony Roach <aroach@electriceyeball.com>