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.
809 options may be specified,
812 will read all of the specified files.
816 Print a local help message for this build, if one is defined in
817 the SConscript file(s), plus a line that describes the
819 option for command-line option help. If no local help message
820 is defined, prints the standard help message about command-line
821 options. Exits after displaying the appropriate message.
825 Print the standard help message about command-line options and
830 Ignore all errors from commands executed to rebuild files.
833 .RI -I " directory" ", --include-dir=" directory
837 imported Python modules. If several
840 are used, the directories are searched in the order specified.
844 Cache implicit dependencies.
847 to use the implicit (scanned) dependencies
848 from the last time it was run
849 instead of scanning the files for implicit dependencies.
850 This can significantly speed up SCons,
851 but with the following limitations:
854 will not detect changes to implicit dependency search paths
856 .BR CPPPATH ", " LIBPATH )
857 that would ordinarily
858 cause different versions of same-named files to be used.
861 will miss changes in the implicit dependencies
862 in cases where a new implicit
863 dependency is added earlier in the implicit dependency search path
865 .BR CPPPATH ", " LIBPATH )
866 than a current implicit dependency with the same name.
869 --implicit-deps-changed
870 Forces SCons to ignore the cached implicit dependencies. This causes the
871 implicit dependencies to be rescanned and recached. This implies
872 .BR --implicit-cache .
875 --implicit-deps-unchanged
876 Force SCons to ignore changes in the implicit dependencies.
877 This causes cached implicit dependencies to always be used.
879 .BR --implicit-cache .
883 Starts SCons in interactive mode.
884 The SConscript files are read once and a
887 Targets may now be rebuilt by typing commands at interactive prompt
888 without having to re-read the SConscript files
889 and re-initialize the dependency graph from scratch.
891 SCons interactive mode supports the following commands:
895 .BI build "[OPTIONS] [TARGETS] ..."
898 (and their dependencies)
907 The following SCons command-line options affect the
913 --cache-disable, --no-cache
914 --cache-force, --cache-populate
920 -n, --no-exec, --just-print, --dry-run, --recon
922 -s, --silent, --quiet
923 --taskmastertrace=FILE
928 Any other SCons command-line options that are specified
930 but have no effect on the
933 (mainly because they affect how the SConscript files are read,
934 which only happens once at the beginning of interactive mode).
937 .BI clean "[OPTIONS] [TARGETS] ..."
940 (and their dependencies)
941 with the specified options.
944 This command is itself a synonym for
949 Exits SCons interactive mode.
950 You can also exit by terminating input
951 (CTRL+D on UNIX or Linux systems,
952 CTRL+Z on Windows systems).
956 Provides a help message about
957 the commands available in SCons interactive mode.
967 .BI shell "[COMMANDLINE]"
968 Executes the specified
974 executes the interactive command interpreter
978 (on UNIX and Linux systems)
982 (on Windows systems).
990 Prints SCons version information.
994 An empty line repeats the last typed command.
995 Command-line editing can be used if the
1000 $ scons --interactive
1001 scons: Reading SConscript files ...
1002 scons: done reading SConscript files.
1003 scons>>> build -n prog
1008 .RI -j " N" ", --jobs=" N
1009 Specifies the number of jobs (commands) to run simultaneously.
1010 If there is more than one
1012 option, the last one is effective.
1016 .\" is specified without an argument,
1018 .\" will not limit the number of
1019 .\" simultaneous jobs.
1023 Continue as much as possible after an error. The target that
1024 failed and those that depend on it will not be remade, but other
1025 targets specified on the command line will still be processed.
1028 .\" .RI -l " N" ", --load-average=" N ", --max-load=" N
1029 .\" No new jobs (commands) will be started if
1030 .\" there are other jobs running and the system load
1031 .\" average is at least
1033 .\" (a floating-point number).
1038 .\" List derived files (targets, dependencies) that would be built,
1039 .\" but do not build them.
1040 .\" [XXX This can probably go away with the right
1041 .\" combination of other options. Revisit this issue.]
1045 .\" List derived files that would be built, with the actions
1046 .\" (commands) that build them. Does not build the files.
1047 .\" [XXX This can probably go away with the right
1048 .\" combination of other options. Revisit this issue.]
1052 .\" List derived files that would be built, plus where the file is
1053 .\" defined (file name and line number). Does not build the files.
1054 .\" [XXX This can probably go away with the right
1055 .\" combination of other options. Revisit this issue.]
1059 Ignored for compatibility with non-GNU versions of
1063 .RI --max-drift= SECONDS
1064 Set the maximum expected drift in the modification time of files to
1066 This value determines how long a file must be unmodified
1067 before its cached content signature
1068 will be used instead of
1069 calculating a new content signature (MD5 checksum)
1070 of the file's contents.
1071 The default value is 2 days, which means a file must have a
1072 modification time of at least two days ago in order to have its
1073 cached content signature used.
1074 A negative value means to never cache the content
1075 signature and to ignore the cached value if there already is one. A value
1076 of 0 means to always use the cached signature,
1077 no matter how old the file is.
1080 .RI --md5-chunksize= KILOBYTES
1081 Set the block size used to compute MD5 signatures to
1083 This value determines the size of the chunks which are read in at once when
1084 computing MD5 signatures. Files below that size are fully stored in memory
1085 before performing the signature computation while bigger files are read in
1086 block-by-block. A huge block-size leads to high memory consumption while a very
1087 small block-size slows down the build considerably.
1089 The default value is to use a chunk size of 64 kilobytes, which should
1090 be appropriate for most uses.
1093 -n, --just-print, --dry-run, --recon
1094 No execute. Print the commands that would be executed to build
1095 any out-of-date target files, but do not execute the commands.
1099 Prevents the automatic addition of the standard
1103 Also prevents loading the
1104 .I site_scons/site_init.py
1105 module if it exists, and prevents adding
1106 .I site_scons/site_tools
1110 .\" .RI -o " file" ", --old-file=" file ", --assume-old=" file
1114 .\" not rebuild anything due to changes in the contents of
1117 .\" .RI --override " file"
1118 .\" Read values to override specific build environment variables
1119 .\" from the specified
1123 .\" Print the data base (construction environments,
1124 .\" Builder and Scanner objects) that are defined
1125 .\" after reading the SConscript files.
1126 .\" After printing, a normal build is performed
1127 .\" as usual, as specified by other command-line options.
1128 .\" This also prints version information
1133 .\" To print the database without performing a build do:
1141 Run SCons under the Python profiler
1142 and save the results in the specified
1144 The results may be analyzed using the Python
1149 Do not run any commands, or print anything. Just return an exit
1150 status that is zero if the specified targets are already up to
1151 date, non-zero otherwise.
1154 Quiets SCons status messages about
1155 reading SConscript files,
1157 and entering directories.
1158 Commands that are executed
1159 to rebuild target files are still printed.
1162 .\" -r, -R, --no-builtin-rules, --no-builtin-variables
1163 .\" Clear the default construction variables. Construction
1164 .\" environments that are created will be completely empty.
1168 Build dependencies in a random order. This is useful when
1169 building multiple trees simultaneously with caching enabled,
1170 to prevent multiple builds from simultaneously trying to build
1171 or retrieve the same target files.
1174 -s, --silent, --quiet
1175 Silent. Do not print commands that are executed to rebuild
1177 Also suppresses SCons status messages.
1180 -S, --no-keep-going, --stop
1181 Ignored for compatibility with GNU
1186 Uses the named dir as the site dir rather than the default
1188 dir. This dir will get prepended to
1191 .IR dir /site_init.py
1192 will get loaded if it exists, and
1194 will get added to the default toolpath.
1197 .RI --stack-size= KILOBYTES
1198 Set the size stack used to run threads to
1200 This value determines the stack size of the threads used to run jobs.
1201 These are the threads that execute the actions of the builders for the
1202 nodes that are out-of-date.
1203 Note that this option has no effect unless the
1205 option, which corresponds to -j and --jobs, is larger than one. Using
1206 a stack size that is too small may cause stack overflow errors. This
1207 usually shows up as segmentation faults that cause scons to abort
1208 before building anything. Using a stack size that is too large will
1209 cause scons to use more memory than required and may slow down the entire
1212 The default value is to use a stack size of 256 kilobytes, which should
1213 be appropriate for most uses. You should not need to increase this value
1214 unless you encounter stack overflow errors.
1218 Ignored for compatibility with GNU
1220 (Touching a file to make it
1221 appear up-to-date is unnecessary when using
1225 .RI --taskmastertrace= file
1226 Prints trace information to the specified
1228 about how the internal Taskmaster object
1229 evaluates and controls the order in which Nodes are built.
1232 may be used to specify the standard output.
1236 Prints a tree of the dependencies
1237 after each top-level target is built.
1238 This prints out some or all of the tree,
1246 Print the entire dependency tree
1247 after each top-level target is built.
1248 This prints out the complete dependency tree,
1249 including implicit dependencies and ignored dependencies.
1253 Restricts the tree output to only derived (target) files,
1258 Prints status information for each displayed node.
1262 Prunes the tree to avoid repeating dependency information
1263 for nodes that have already been displayed.
1264 Any node that has already been displayed
1265 will have its name printed in
1266 .BR "[square brackets]" ,
1267 as an indication that the dependencies
1268 for that node can be found by searching
1269 for the relevant output higher up in the tree.
1272 Multiple options may be specified,
1273 separated by commas:
1276 # Prints only derived files, with status information:
1277 scons --tree=derived,status
1279 # Prints all dependencies of target, with status information
1280 # and pruning dependencies of already-visited Nodes:
1281 scons --tree=all,prune,status target
1285 -u, --up, --search-up
1286 Walks up the directory structure until an
1291 file is found, and uses that
1292 as the top of the directory tree.
1293 If no targets are specified on the command line,
1294 only targets at or below the
1295 current directory will be built.
1299 Works exactly the same way as the
1301 option except for the way default targets are handled.
1302 When this option is used and no targets are specified on the command line,
1303 all default targets that are defined in the SConscript(s) in the current
1304 directory are built, regardless of what directory the resultant targets end
1311 version, copyright information,
1312 list of authors, and any other relevant information.
1316 -w, --print-directory
1317 Print a message containing the working directory before and
1318 after other processing.
1321 --no-print-directory
1322 Turn off -w, even if it was turned on implicitly.
1325 .RI --warn= type ", --warn=no-" type
1326 Enable or disable warnings.
1328 specifies the type of warnings to be enabled or disabled:
1331 --warn=all, --warn=no-all
1332 Enables or disables all warnings.
1335 --warn=cache-write-error, --warn=no-cache-write-error
1336 Enables or disables warnings about errors trying to
1337 write a copy of a built file to a specified
1339 These warnings are disabled by default.
1342 --warn=corrupt-sconsign, --warn=no-corrupt-sconsign
1343 Enables or disables warnings about unfamiliar signature data in
1346 These warnings are enabled by default.
1349 --warn=dependency, --warn=no-dependency
1350 Enables or disables warnings about dependencies.
1351 These warnings are disabled by default.
1354 --warn=deprecated, --warn=no-deprecated
1355 Enables or disables all warnings about use of
1356 currently deprecated features.
1357 These warnings are enabled by default.
1359 .B --warn=no-deprecated
1360 option does not disable warnings about absolutely all deprecated features.
1361 Warnings for some deprecated features that have already been through
1362 several releases with deprecation warnings
1363 may be mandatory for a release or two
1364 before they are officially no longer supported by SCons.
1365 Warnings for some specific deprecated features
1366 may be enabled or disabled individually;
1371 --warn=deprecated-copy, --warn=no-deprecated-copy
1372 Enables or disables warnings about use of the deprecated
1377 --warn=deprecated-source-signatures, --warn=no-deprecated-source-signatures
1378 Enables or disables warnings about use of the deprecated
1379 .B SourceSignatures()
1381 .B env.SourceSignatures()
1385 --warn=deprecated-target-signatures, --warn=no-deprecated-target-signatures
1386 Enables or disables warnings about use of the deprecated
1387 .B TargetSignatures()
1389 .B env.TargetSignatures()
1394 --warn=duplicate-environment, --warn=no-duplicate-environment
1395 Enables or disables warnings about attempts to specify a build
1396 of a target with two different construction environments
1397 that use the same action.
1398 These warnings are enabled by default.
1401 --warn=fortran-cxx-mix, --warn=no-fortran-cxx-mix
1402 Enables or disables the specific warning about linking
1403 Fortran and C++ object files in a single executable,
1404 which can yield unpredictable behavior with some compilers.
1407 --warn=future-deprecated, --warn=no-future-deprecated
1408 Enables or disables warnings about features
1409 that will be deprecated in the future.
1410 These warnings are disabled by default.
1411 Enabling this warning is especially
1412 recommended for projects that redistribute
1413 SCons configurations for other users to build,
1414 so that the project can be warned as soon as possible
1415 about to-be-deprecated features
1416 that may require changes to the configuration.
1419 --warn=link, --warn=no-link
1420 Enables or disables warnings about link steps.
1423 --warn=misleading-keywords, --warn=no-misleading-keywords
1424 Enables or disables warnings about use of the misspelled keywords
1428 when calling Builders.
1431 characters, the correct spellings are
1435 These warnings are enabled by default.
1438 --warn=missing-sconscript, --warn=no-missing-sconscript
1439 Enables or disables warnings about missing SConscript files.
1440 These warnings are enabled by default.
1443 --warn=no-md5-module, --warn=no-no-md5-module
1444 Enables or disables warnings about the version of Python
1445 not having an MD5 checksum module available.
1446 These warnings are enabled by default.
1449 --warn=no-metaclass-support, --warn=no-no-metaclass-support
1450 Enables or disables warnings about the version of Python
1451 not supporting metaclasses when the
1454 These warnings are enabled by default.
1457 --warn=no-object-count, --warn=no-no-object-count
1458 Enables or disables warnings about the
1460 feature not working when
1462 is run with the python
1464 option or from optimized Python (.pyo) modules.
1467 --warn=no-parallel-support, --warn=no-no-parallel-support
1468 Enables or disables warnings about the version of Python
1469 not being able to support parallel builds when the
1472 These warnings are enabled by default.
1475 --warn=python-version, --warn=no-python-version
1476 Enables or disables the warning about running
1477 SCons with a deprecated version of Python.
1478 These warnings are enabled by default.
1481 --warn=reserved-variable, --warn=no-reserved-variable
1482 Enables or disables warnings about attempts to set the
1483 reserved construction variable names
1484 .BR CHANGED_SOURCES ,
1485 .BR CHANGED_TARGETS ,
1490 .BR UNCHANGED_SOURCES
1492 .BR UNCHANGED_TARGETS .
1493 These warnings are disabled by default.
1496 --warn=stack-size, --warn=no-stack-size
1497 Enables or disables warnings about requests to set the stack size
1498 that could not be honored.
1499 These warnings are enabled by default.
1502 .\" .RI --write-filenames= file
1503 .\" Write all filenames considered into
1507 .\" .RI -W " file" ", --what-if=" file ", --new-file=" file ", --assume-new=" file
1508 .\" Pretend that the target
1511 .\" modified. When used with the
1514 .\" show you what would be rebuilt if you were to modify that file.
1520 .\" --warn-undefined-variables
1521 .\" Warn when an undefined variable is referenced.
1524 .RI -Y " repository" ", --repository=" repository ", --srcdir=" repository
1525 Search the specified repository for any input and target
1526 files not found in the local directory hierarchy. Multiple
1528 options may be specified, in which case the
1529 repositories are searched in the order specified.
1531 .SH CONFIGURATION FILE REFERENCE
1532 .\" .SS Python Basics
1533 .\" XXX Adding this in the future would be a help.
1534 .SS Construction Environments
1535 A construction environment is the basic means by which the SConscript
1536 files communicate build information to
1538 A new construction environment is created using the
1549 may be set in a construction environment
1550 either by specifying them as keywords when the object is created
1551 or by assigning them a value after the object is created:
1554 env = Environment(FOO = 'foo')
1559 construction variables may also be set or modified by the
1561 keyword argument, which applies the
1563 method (described below) to the argument value
1564 after all other processing is completed.
1565 This is useful either if the exact content of the flags is unknown
1566 (for example, read from a control file)
1567 or if the flags are distributed to a number of construction variables.
1570 env = Environment(parse_flags = '-Iinclude -DEBUG -lm')
1573 This example adds 'include' to
1580 By default, a new construction environment is
1581 initialized with a set of builder methods
1582 and construction variables that are appropriate
1583 for the current platform.
1584 An optional platform keyword argument may be
1585 used to specify that an environment should
1586 be initialized for a different platform:
1589 env = Environment(platform = 'cygwin')
1590 env = Environment(platform = 'os2')
1591 env = Environment(platform = 'posix')
1592 env = Environment(platform = 'win32')
1595 Specifying a platform initializes the appropriate
1596 construction variables in the environment
1597 to use and generate file names with prefixes
1598 and suffixes appropriate for the platform.
1606 variables from the user's external environment
1607 to the construction environment's
1610 This is so that any executed commands
1611 that use sockets to connect with other systems
1612 (such as fetching source files from
1613 external CVS repository specifications like
1614 .BR :pserver:anonymous@cvs.sourceforge.net:/cvsroot/scons )
1615 will work on Windows systems.
1617 The platform argument may be function or callable object,
1618 in which case the Environment() method
1619 will call the specified argument to update
1620 the new construction environment:
1623 def my_platform(env):
1624 env['VAR'] = 'xyzzy'
1626 env = Environment(platform = my_platform)
1629 Additionally, a specific set of tools
1630 with which to initialize the environment
1631 may be specified as an optional keyword argument:
1634 env = Environment(tools = ['msvc', 'lex'])
1637 Non-built-in tools may be specified using the toolpath argument:
1640 env = Environment(tools = ['default', 'foo'], toolpath = ['tools'])
1643 This looks for a tool specification in tools/foo.py (as well as
1644 using the ordinary default tools for the platform). foo.py should
1645 have two functions: generate(env, **kw) and exists(env).
1649 modifies the passed-in environment
1650 to set up variables so that the tool
1652 it may use any keyword arguments
1653 that the user supplies (see below)
1654 to vary its initialization.
1657 function should return a true
1658 value if the tool is available.
1659 Tools in the toolpath are used before
1660 any of the built-in ones. For example, adding gcc.py to the toolpath
1661 would override the built-in gcc tool.
1662 Also note that the toolpath is
1663 stored in the environment for use
1671 base = Environment(toolpath=['custom_path'])
1672 derived = base.Clone(tools=['custom_tool'])
1673 derived.CustomBuilder()
1676 The elements of the tools list may also
1677 be functions or callable objects,
1678 in which case the Environment() method
1679 will call the specified elements
1680 to update the new construction environment:
1684 env['XYZZY'] = 'xyzzy'
1686 env = Environment(tools = [my_tool])
1689 The individual elements of the tools list
1690 may also themselves be two-element lists of the form
1691 .RI ( toolname ", " kw_dict ).
1692 SCons searches for the
1694 specification file as described above, and
1697 which must be a dictionary, as keyword arguments to the tool's
1702 function can use the arguments to modify the tool's behavior
1703 by setting up the environment in different ways
1704 or otherwise changing its initialization.
1707 # in tools/my_tool.py:
1708 def generate(env, **kw):
1709 # Sets MY_TOOL to the value of keyword argument 'arg1' or 1.
1710 env['MY_TOOL'] = kw.get('arg1', '1')
1715 env = Environment(tools = ['default', ('my_tool', {'arg1': 'abc'})],
1719 The tool definition (i.e. my_tool()) can use the PLATFORM variable from
1720 the environment it receives to customize the tool for different platforms.
1722 If no tool list is specified, then SCons will auto-detect the installed
1723 tools using the PATH variable in the ENV construction variable and the
1724 platform name when the Environment is constructed. Changing the PATH
1725 variable after the Environment is constructed will not cause the tools to
1728 SCons supports the following tool specifications out of the box:
1810 Additionally, there is a "tool" named
1812 which configures the
1813 environment with a default set of tools for the current platform.
1815 On posix and cygwin platforms
1816 the GNU tools (e.g. gcc) are preferred by SCons,
1817 on Windows the Microsoft tools (e.g. msvc)
1818 followed by MinGW are preferred by SCons,
1819 and in OS/2 the IBM tools (e.g. icc) are preferred by SCons.
1823 Build rules are specified by calling a construction
1824 environment's builder methods.
1825 The arguments to the builder methods are
1827 (a list of targets to be built,
1831 (a list of sources to be built,
1832 usually file names).
1834 Because long lists of file names
1835 can lead to a lot of quoting,
1840 and a same-named environment method
1841 that split a single string
1842 into a list, separated on
1843 strings of white-space characters.
1844 (These are similar to the
1845 string.split() method
1846 from the standard Python library,
1847 but work even if the input isn't a string.)
1849 Like all Python arguments,
1850 the target and source arguments to a builder method
1851 can be specified either with or without
1852 the "target" and "source" keywords.
1853 When the keywords are omitted,
1854 the target is first,
1855 followed by the source.
1856 The following are equivalent examples of calling the Program builder method:
1859 env.Program('bar', ['bar.c', 'foo.c'])
1860 env.Program('bar', Split('bar.c foo.c'))
1861 env.Program('bar', env.Split('bar.c foo.c'))
1862 env.Program(source = ['bar.c', 'foo.c'], target = 'bar')
1863 env.Program(target = 'bar', Split('bar.c foo.c'))
1864 env.Program(target = 'bar', env.Split('bar.c foo.c'))
1865 env.Program('bar', source = string.split('bar.c foo.c'))
1868 Target and source file names
1869 that are not absolute path names
1870 (that is, do not begin with
1877 an optional drive letter)
1878 are interpreted relative to the directory containing the
1884 on a path name means that the rest of the file name
1885 is interpreted relative to
1886 the directory containing
1892 is followed by a directory separator character
1893 (slash or backslash).
1898 # The comments describing the targets that will be built
1899 # assume these calls are in a SConscript file in the
1900 # a subdirectory named "subdir".
1902 # Builds the program "subdir/foo" from "subdir/foo.c":
1903 env.Program('foo', 'foo.c')
1905 # Builds the program "/tmp/bar" from "subdir/bar.c":
1906 env.Program('/tmp/bar', 'bar.c')
1908 # An initial '#' or '#/' are equivalent; the following
1909 # calls build the programs "foo" and "bar" (in the
1910 # top-level SConstruct directory) from "subdir/foo.c" and
1911 # "subdir/bar.c", respectively:
1912 env.Program('#foo', 'foo.c')
1913 env.Program('#/bar', 'bar.c')
1915 # Builds the program "other/foo" (relative to the top-level
1916 # SConstruct directory) from "subdir/foo.c":
1917 env.Program('#other/foo', 'foo.c')
1920 When the target shares the same base name
1921 as the source and only the suffix varies,
1922 and if the builder method has a suffix defined for the target file type,
1923 then the target argument may be omitted completely,
1926 will deduce the target file name from
1927 the source file name.
1928 The following examples all build the
1934 (on Windows systems)
1935 from the bar.c source file:
1938 env.Program(target = 'bar', source = 'bar.c')
1939 env.Program('bar', source = 'bar.c')
1940 env.Program(source = 'bar.c')
1941 env.Program('bar.c')
1946 keyword argument may be specified
1947 when calling a Builder.
1949 all source file strings that are not absolute paths
1950 will be interpreted relative to the specified
1952 The following example will build the
1957 program from the files
1963 env.Program('build/prog', ['f1.c', 'f2.c'], srcdir='src')
1966 It is possible to override or add construction variables when calling a
1967 builder method by passing additional keyword arguments.
1968 These overridden or added
1969 variables will only be in effect when building the target, so they will not
1970 affect other parts of the build. For example, if you want to add additional
1971 libraries for just one program:
1974 env.Program('hello', 'hello.c', LIBS=['gl', 'glut'])
1977 or generate a shared library with a non-standard suffix:
1980 env.SharedLibrary('word', 'word.cpp',
1982 LIBSUFFIXES=['.ocx'])
1985 (Note that both the $SHLIBSUFFIX and $LIBSUFFIXES variables must be set
1986 if you want SCons to search automatically
1987 for dependencies on the non-standard library names;
1988 see the descriptions of these variables, below, for more information.)
1990 It is also possible to use the
1992 keyword argument in an override:
1995 env = Program('hello', 'hello.c', parse_flags = '-Iinclude -DEBUG -lm')
1998 This example adds 'include' to
2005 Although the builder methods defined by
2008 methods of a construction environment object,
2009 they may also be called without an explicit environment:
2012 Program('hello', 'hello.c')
2013 SharedLibrary('word', 'word.cpp')
2017 the methods are called internally using a default construction
2018 environment that consists of the tools and values that
2020 has determined are appropriate for the local system.
2022 Builder methods that can be called without an explicit
2023 environment may be called from custom Python modules that you
2024 import into an SConscript file by adding the following
2025 to the Python module:
2028 from SCons.Script import *
2031 All builder methods return a list-like object
2032 containing Nodes that
2033 represent the target or targets that will be built.
2036 is an internal SCons object
2038 build targets or sources.
2040 The returned Node-list object
2041 can be passed to other builder methods as source(s)
2042 or passed to any SCons function or method
2043 where a filename would normally be accepted.
2044 For example, if it were necessary
2047 flag when compiling one specific object file:
2050 bar_obj_list = env.StaticObject('bar.c', CPPDEFINES='-DBAR')
2051 env.Program(source = ['foo.c', bar_obj_list, 'main.c'])
2054 Using a Node in this way
2055 makes for a more portable build
2056 by avoiding having to specify
2057 a platform-specific object suffix
2058 when calling the Program() builder method.
2060 Note that Builder calls will automatically "flatten"
2061 the source and target file lists,
2062 so it's all right to have the bar_obj list
2063 return by the StaticObject() call
2064 in the middle of the source file list.
2065 If you need to manipulate a list of lists returned by Builders
2066 directly using Python,
2067 you can either build the list by hand:
2070 foo = Object('foo.c')
2071 bar = Object('bar.c')
2072 objects = ['begin.o'] + foo + ['middle.o'] + bar + ['end.o']
2073 for object in objects:
2079 function supplied by scons
2080 to create a list containing just the Nodes,
2081 which may be more convenient:
2084 foo = Object('foo.c')
2085 bar = Object('bar.c')
2086 objects = Flatten(['begin.o', foo, 'middle.o', bar, 'end.o'])
2087 for object in objects:
2091 Note also that because Builder calls return
2092 a list-like object, not an actual Python list,
2097 operator to append Builder results to a Python list.
2098 Because the list and the object are different types,
2099 Python will not update the original list in place,
2100 but will instead create a new Node-list object
2101 containing the concatenation of the list
2102 elements and the Builder results.
2103 This will cause problems for any other Python variables
2104 in your SCons configuration
2105 that still hold on to a reference to the original list.
2106 Instead, use the Python
2108 method to make sure the list is updated in-place.
2114 # Do NOT use += as follows:
2116 # object_files += Object('bar.c')
2118 # It will not update the object_files list in place.
2120 # Instead, use the .extend() method:
2121 object_files.extend(Object('bar.c'))
2125 The path name for a Node's file may be used
2126 by passing the Node to the Python-builtin
2131 bar_obj_list = env.StaticObject('bar.c', CPPDEFINES='-DBAR')
2132 print "The path to bar_obj is:", str(bar_obj_list[0])
2135 Note again that because the Builder call returns a list,
2136 we have to access the first element in the list
2137 .B (bar_obj_list[0])
2138 to get at the Node that actually represents
2141 Builder calls support a
2143 keyword argument that
2144 specifies that the Builder's action(s)
2146 after changing directory.
2150 a string or a directory Node,
2151 scons will change to the specified directory.
2154 is not a string or Node
2156 then scons will change to the
2157 target file's directory.
2160 # scons will change to the "sub" subdirectory
2161 # before executing the "cp" command.
2162 env.Command('sub/dir/foo.out', 'sub/dir/foo.in',
2163 "cp dir/foo.in dir/foo.out",
2166 # Because chdir is not a string, scons will change to the
2167 # target's directory ("sub/dir") before executing the
2169 env.Command('sub/dir/foo.out', 'sub/dir/foo.in',
2170 "cp foo.in foo.out",
2174 Note that scons will
2176 automatically modify
2178 construction variables like
2182 when using the chdir
2183 keyword argument--that is,
2184 the expanded file names
2185 will still be relative to
2186 the top-level SConstruct directory,
2187 and consequently incorrect
2188 relative to the chdir directory.
2189 If you use the chdir keyword argument,
2190 you will typically need to supply a different
2196 to use just the filename portion of the
2200 provides the following builder methods:
2202 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2203 '\" BEGIN GENERATED BUILDER DESCRIPTIONS
2205 '\" The descriptions below of the various SCons Builders are generated
2206 '\" from the .xml files that live next to the various Python modules in
2207 '\" the build enginer library. If you're reading this [gnt]roff file
2208 '\" with an eye towards patching this man page, you can still submit
2209 '\" a diff against this text, but it will have to be translated to a
2210 '\" diff against the underlying .xml file before the patch is actually
2211 '\" accepted. If you do that yourself, it will make it easier to
2212 '\" integrate the patch.
2214 '\" BEGIN GENERATED BUILDER DESCRIPTIONS
2215 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2217 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2218 '\" END GENERATED BUILDER DESCRIPTIONS
2220 '\" The descriptions above of the various SCons Builders are generated
2221 '\" from the .xml files that live next to the various Python modules in
2222 '\" the build enginer library. If you're reading this [gnt]roff file
2223 '\" with an eye towards patching this man page, you can still submit
2224 '\" a diff against this text, but it will have to be translated to a
2225 '\" diff against the underlying .xml file before the patch is actually
2226 '\" accepted. If you do that yourself, it will make it easier to
2227 '\" integrate the patch.
2229 '\" END GENERATED BUILDER DESCRIPTIONS
2230 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2234 targets of builder methods automatically depend on their sources.
2235 An explicit dependency can
2236 be specified using the
2238 method of a construction environment (see below).
2243 source files for various programming languages,
2244 so the dependencies do not need to be specified explicitly.
2245 By default, SCons can
2248 Fortran source files with
2250 (POSIX systems only),
2255 and assembly language files with
2257 (POSIX systems only),
2262 for C preprocessor dependencies.
2263 SCons also has default support
2264 for scanning D source files,
2265 You can also write your own Scanners
2266 to add support for additional source file types.
2267 These can be added to the default
2268 Scanner object used by the
2270 .BR StaticObject (),
2273 Builders by adding them
2275 .B SourceFileScanner
2278 See the section "Scanner Objects,"
2279 below, for a more information about
2280 defining your own Scanner objects.
2282 .SS Methods and Functions to Do Things
2283 In addition to Builder methods,
2285 provides a number of other construction environment methods
2286 and global functions to
2287 manipulate the build configuration.
2289 Usually, a construction environment method
2290 and global function with the same name both exist
2291 so that you don't have to remember whether
2292 to a specific bit of functionality
2293 must be called with or without a construction environment.
2294 In the following list,
2295 if you call something as a global function
2298 .RI Function( arguments )
2300 and if you call something through a construction
2301 environment it looks like:
2303 .RI env.Function( arguments )
2305 If you can call the functionality in both ways,
2306 then both forms are listed.
2308 Global functions may be called from custom Python modules that you
2309 import into an SConscript file by adding the following
2310 to the Python module:
2313 from SCons.Script import *
2316 Except where otherwise noted,
2318 construction environment method
2320 provide the exact same functionality.
2321 The only difference is that,
2323 calling the functionality through a construction environment will
2324 substitute construction variables into
2325 any supplied strings.
2329 env = Environment(FOO = 'foo')
2334 In the above example,
2335 the first call to the global
2337 function will actually add a target named
2339 to the list of default targets,
2340 while the second call to the
2342 construction environment method
2343 will expand the value
2344 and add a target named
2346 to the list of default targets.
2347 For more on construction variable expansion,
2348 see the next section on
2349 construction variables.
2351 Construction environment methods
2352 and global functions supported by
2356 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2358 .RI Action( action ", [" cmd/str/fun ", [" var ", ...]] [" option = value ", ...])"
2360 .IR env .Action( action ", [" cmd/str/fun ", [" var ", ...]] [" option = value ", ...])"
2361 Creates an Action object for
2364 See the section "Action Objects,"
2365 below, for a complete explanation of the arguments and behavior.
2369 form of the invocation will expand
2370 construction variables in any argument strings,
2373 argument, at the time it is called
2374 using the construction variables in the
2376 construction environment through which
2381 form delays all variable expansion
2382 until the Action object is actually used.
2384 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2386 .RI AddMethod( object, function ", [" name ])
2388 .RI env.AddMethod( function ", [" name ])
2389 When called with the
2396 as the specified method
2398 When called with the
2399 .BR env.AddMethod ()
2403 to the construction environment
2405 as the specified method
2414 itself is used for the method name.
2419 # Note that the first argument to the function to
2420 # be attached as a method must be the object through
2421 # which the method will be called; the Python
2422 # convention is to call it 'self'.
2423 def my_method(self, arg):
2424 print "my_method() got", arg
2426 # Use the global AddMethod() function to add a method
2427 # to the Environment class. This
2428 AddMethod(Environment, my_method)
2430 env.my_method('arg')
2432 # Add the function as a method, using the function
2433 # name for the method call.
2435 env.AddMethod(my_method, 'other_method_name')
2436 env.other_method_name('another arg')
2439 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2441 .RI AddOption( arguments )
2442 This function adds a new command-line option to be recognized.
2445 are the same as supported by the standard Python
2446 .BR optparse.add_option ()
2447 method (with a few additional capabilities noted below);
2448 see the documentation for
2450 for a thorough discussion of its option-processing capabities.
2451 (Note that although the
2453 module was not a standard module until Python 2.3,
2455 contains a compatible version of the module
2456 that is used to provide identical functionality
2457 when run by earlier Python versions.)
2459 In addition to the arguments and values supported by the
2460 .B optparse.add_option ()
2464 function allows you to set the
2468 (a string with just the question mark)
2469 to indicate that the specified long option(s) take(s) an
2479 may be used to supply the "default"
2480 value that should be used when the
2481 option is specified on the command line
2482 without an explicit argument.
2486 keyword argument is supplied when calling
2488 the option will have a default value of
2491 Once a new command-line option has been added with
2493 the option value may be accessed using
2496 .BR env.GetOption ().
2497 \" NOTE: in SCons 1.x or 2.0, user options will be settable, but not yet.
2498 \" Uncomment this when that works. See tigris issue 2105.
2499 \" The value may also be set, using
2502 \" .BR env.SetOption (),
2503 \" if conditions in a
2505 \" require overriding any default value.
2506 \" Note, however, that a
2507 \" value specified on the command line will
2509 \" override a value set by any SConscript file.
2513 strings for the new option(s)
2514 will be displayed by the
2519 (the latter only if no other help text is
2520 specified in the SConscript files).
2521 The help text for the local options specified by
2523 will appear below the SCons options themselves,
2527 The options will appear in the help text
2528 in the order in which the
2535 AddOption('--prefix',
2537 nargs=1, type='string',
2540 help='installation prefix')
2541 env = Environment(PREFIX = GetOption('prefix'))
2544 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2546 .RI AddPostAction( target ", " action )
2548 .RI env.AddPostAction( target ", " action )
2549 Arranges for the specified
2555 The specified action(s) may be
2556 an Action object, or anything that
2557 can be converted into an Action object
2560 When multiple targets are supplied,
2561 the action may be called multiple times,
2562 once after each action that generates
2563 one or more targets in the list.
2565 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2567 .RI AddPreAction( target ", " action )
2569 .RI env.AddPreAction( target ", " action )
2570 Arranges for the specified
2573 before the specified
2576 The specified action(s) may be
2577 an Action object, or anything that
2578 can be converted into an Action object
2581 When multiple targets are specified,
2582 the action(s) may be called multiple times,
2583 once before each action that generates
2584 one or more targets in the list.
2586 Note that if any of the targets are built in multiple steps,
2587 the action will be invoked just
2588 before the "final" action that specifically
2589 generates the specified target(s).
2590 For example, when building an executable program
2591 from a specified source
2593 file via an intermediate object file:
2596 foo = Program('foo.c')
2597 AddPreAction(foo, 'pre_action')
2602 would be executed before
2604 calls the link command that actually
2605 generates the executable program binary
2607 not before compiling the
2609 file into an object file.
2611 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2613 .RI Alias( alias ", [" targets ", [" action ]])
2615 .RI env.Alias( alias ", [" targets ", [" action ]])
2616 Creates one or more phony targets that
2617 expand to one or more other targets.
2622 can be specified that will be executed
2623 whenever the any of the alias targets are out-of-date.
2624 Returns the Node object representing the alias,
2625 which exists outside of any file system.
2626 This Node object, or the alias name,
2627 may be used as a dependency of any other target,
2628 including another alias.
2630 can be called multiple times for the same
2631 alias to add additional targets to the alias,
2632 or additional actions to the list for this alias.
2638 Alias('install', '/usr/bin')
2639 Alias(['install', 'install-lib'], '/usr/local/lib')
2641 env.Alias('install', ['/usr/local/bin', '/usr/local/lib'])
2642 env.Alias('install', ['/usr/local/man'])
2644 env.Alias('update', ['file1', 'file2'], "update_database $SOURCES")
2647 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2649 .RI AllowSubstExceptions([ exception ", ...])"
2650 Specifies the exceptions that will be allowed
2651 when expanding construction variables.
2653 any construction variable expansions that generate a
2657 exception will expand to a
2659 (a null string) and not cause scons to fail.
2660 All exceptions not in the specified list
2661 will generate an error message
2662 and terminate processing.
2665 .B AllowSubstExceptions
2666 is called multiple times,
2667 each call completely overwrites the previous list
2668 of allowed exceptions.
2673 # Requires that all construction variable names exist.
2674 # (You may wish to do this if you want to enforce strictly
2675 # that all construction variables must be defined before use.)
2676 AllowSubstExceptions()
2678 # Also allow a string containing a zero-division expansion
2679 # like '${1 / 0}' to evalute to ''.
2680 AllowSubstExceptions(IndexError, NameError, ZeroDivisionError)
2683 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2685 .RI AlwaysBuild( target ", ...)"
2687 .RI env.AlwaysBuild( target ", ...)"
2690 so that it is always assumed to be out of date,
2691 and will always be rebuilt if needed.
2694 does not add its target(s) to the default target list,
2695 so the targets will only be built
2696 if they are specified on the command line,
2697 or are a dependent of a target specified on the command line--but
2700 be built if so specified.
2701 Multiple targets can be passed in to a single call to
2704 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2706 .RI env.Append( key = val ", [...])"
2707 Appends the specified keyword arguments
2708 to the end of construction variables in the environment.
2709 If the Environment does not have
2710 the specified construction variable,
2711 it is simply added to the environment.
2712 If the values of the construction variable
2713 and the keyword argument are the same type,
2714 then the two values will be simply added together.
2715 Otherwise, the construction variable
2716 and the value of the keyword argument
2717 are both coerced to lists,
2718 and the lists are added together.
2719 (See also the Prepend method, below.)
2724 env.Append(CCFLAGS = ' -g', FOO = ['foo.yyy'])
2727 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2729 .RI env.AppendENVPath( name ", " newpath ", [" envname ", " sep ", " delete_existing ])
2730 This appends new path elements to the given path in the
2731 specified external environment
2735 any particular path once (leaving the last one it encounters and
2736 ignoring the rest, to preserve path order),
2737 and to help assure this,
2738 will normalize all paths (using
2741 .BR os.path.normcase ).
2742 This can also handle the
2743 case where the given old path variable is a list instead of a
2744 string, in which case a list will be returned instead of a string.
2748 is 0, then adding a path that already exists
2749 will not move it to the end; it will stay where it is in the list.
2754 print 'before:',env['ENV']['INCLUDE']
2755 include_path = '/foo/bar:/foo'
2756 env.AppendENVPath('INCLUDE', include_path)
2757 print 'after:',env['ENV']['INCLUDE']
2761 after: /biz:/foo/bar:/foo
2764 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2766 .RI env.AppendUnique( key = val ", [...], delete_existing=0)"
2767 Appends the specified keyword arguments
2768 to the end of construction variables in the environment.
2769 If the Environment does not have
2770 the specified construction variable,
2771 it is simply added to the environment.
2772 If the construction variable being appended to is a list,
2773 then any value(s) that already exist in the
2774 construction variable will
2776 be added again to the list.
2777 However, if delete_existing is 1,
2778 existing matching values are removed first, so
2779 existing values in the arg list move to the end of the list.
2784 env.AppendUnique(CCFLAGS = '-g', FOO = ['foo.yyy'])
2787 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2790 A factory function that
2791 returns a Builder object
2792 to be used to fetch source files
2794 The returned Builder
2795 is intended to be passed to the
2802 env.SourceCode('.', env.BitKeeper())
2805 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2807 .RI BuildDir( build_dir ", " src_dir ", [" duplicate ])
2809 .RI env.BuildDir( build_dir ", " src_dir ", [" duplicate ])
2810 Deprecated synonyms for
2813 .BR env.VariantDir ().
2816 argument becomes the
2821 .BR env.VariantDir ().
2823 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2825 .RI Builder( action ", [" arguments ])
2827 .RI env.Builder( action ", [" arguments ])
2828 Creates a Builder object for
2831 See the section "Builder Objects,"
2832 below, for a complete explanation of the arguments and behavior.
2836 form of the invocation will expand
2837 construction variables in any arguments strings,
2841 at the time it is called
2842 using the construction variables in the
2844 construction environment through which
2849 form delays all variable expansion
2850 until after the Builder object is actually called.
2852 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2854 .RI CacheDir( cache_dir )
2856 .RI env.CacheDir( cache_dir )
2859 will maintain a cache of derived files in
2861 The derived files in the cache will be shared
2862 among all the builds using the same
2869 disables derived file caching.
2873 will only affect targets built
2874 through the specified construction environment.
2877 sets a global default
2878 that will be used by all targets built
2879 through construction environments
2890 finds a derived file that needs to be rebuilt,
2891 it will first look in the cache to see if a
2892 derived file has already been built
2893 from identical input files and an identical build action
2894 (as incorporated into the MD5 build signature).
2897 will retrieve the file from the cache.
2898 If the derived file is not present in the cache,
2901 then place a copy of the built file in the cache
2902 (identified by its MD5 build signature),
2903 so that it may be retrieved by other
2904 builds that need to build the same derived file
2905 from identical inputs.
2909 may be disabled for any invocation
2918 will place a copy of
2920 derived files in the cache,
2921 even if they already existed
2922 and were not built by this invocation.
2923 This is useful to populate a cache
2926 is added to a build,
2935 "Retrieved `file' from cache,"
2938 option is being used.
2943 will print the action that
2945 have been used to build the file,
2946 without any indication that
2947 the file was actually retrieved from the cache.
2948 This is useful to generate build logs
2949 that are equivalent regardless of whether
2950 a given derived file has been built in-place
2951 or retrieved from the cache.
2955 method can be used to disable caching of specific files. This can be
2956 useful if inputs and/or outputs of some tool are impossible to
2957 predict or prohibitively large.
2959 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2961 .RI Clean( targets ", " files_or_dirs )
2963 .RI env.Clean( targets ", " files_or_dirs )
2964 This specifies a list of files or directories which should be removed
2965 whenever the targets are specified with the
2967 command line option.
2968 The specified targets may be a list
2969 or an individual target.
2973 and create new targets or add files and directories to the
2974 clean list for the specified targets.
2976 Multiple files or directories should be specified
2977 either as separate arguments to the
2979 method, or as a list.
2981 will also accept the return value of any of the construction environment
2987 function overrides calling
2989 for the same target,
2990 and any targets passed to both functions will
2999 Clean('foo', ['bar', 'baz'])
3000 Clean('dist', env.Program('hello', 'hello.c'))
3001 Clean(['foo', 'bar'], 'something_else_to_clean')
3005 installing the project creates a subdirectory for the documentation.
3006 This statement causes the subdirectory to be removed
3007 if the project is deinstalled.
3009 Clean(docdir, os.path.join(docdir, projectname))
3012 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3014 .RI Command( target ", " source ", " action ", [" key = val ", ...])"
3016 .RI env.Command( target ", " source ", " action ", [" key = val ", ...])"
3017 Executes a specific action
3018 (or list of actions)
3019 to build a target file or files.
3020 This is more convenient
3021 than defining a separate Builder object
3022 for a single special-case build.
3024 As a special case, the
3026 keyword argument can
3029 that will be used to scan the sources.
3033 if any of the sources will be directories
3034 that must be scanned on-disk for
3035 changes to files that aren't
3036 already specified in other Builder of function calls.)
3038 Any other keyword arguments specified override any
3039 same-named existing construction variables.
3041 An action can be an external command,
3042 specified as a string,
3043 or a callable Python object;
3044 see "Action Objects," below,
3045 for more complete information.
3046 Also note that a string specifying an external command
3047 may be preceded by an
3050 to suppress printing the command in question,
3054 to ignore the exit status of the external command.
3059 env.Command('foo.out', 'foo.in',
3060 "$FOO_BUILD < $SOURCES > $TARGET")
3062 env.Command('bar.out', 'bar.in',
3064 "$BAR_BUILD < $SOURCES > $TARGET"],
3065 ENV = {'PATH' : '/usr/local/bin/'})
3067 def rename(env, target, source):
3069 os.rename('.tmp', str(target[0]))
3071 env.Command('baz.out', 'baz.in',
3072 ["$BAZ_BUILD < $SOURCES > .tmp",
3079 function will usually assume, by default,
3080 that the specified targets and/or sources are Files,
3081 if no other part of the configuration
3082 identifies what type of entry it is.
3083 If necessary, you can explicitly specify
3084 that targets or source nodes should
3085 be treated as directoriese
3095 env.Command('ddd.list', Dir('ddd'), 'ls -l $SOURCE > $TARGET')
3097 env['DISTDIR'] = 'destination/directory'
3098 env.Command(env.Dir('$DISTDIR')), None, make_distdir)
3102 (Also note that SCons will usually
3103 automatically create any directory necessary to hold a target file,
3104 so you normally don't need to create directories by hand.)
3106 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3108 .RI Configure( env ", [" custom_tests ", " conf_dir ", " log_file ", " config_h ])
3110 .RI env.Configure([ custom_tests ", " conf_dir ", " log_file ", " config_h ])
3111 Creates a Configure object for integrated
3112 functionality similar to GNU autoconf.
3113 See the section "Configure Contexts,"
3114 below, for a complete explanation of the arguments and behavior.
3116 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3118 .RI env.Clone([ key = val ", ...])"
3119 Return a separate copy of a construction environment.
3120 If there are any keyword arguments specified,
3121 they are added to the returned copy,
3122 overwriting any existing values
3129 env3 = env.Clone(CCFLAGS = '-g')
3132 Additionally, a list of tools and a toolpath may be specified, as in
3133 the Environment constructor:
3136 def MyTool(env): env['FOO'] = 'bar'
3137 env4 = env.Clone(tools = ['msvc', MyTool])
3142 keyword argument is also recognized:
3145 # create an environment for compiling programs that use wxWidgets
3146 wx_env = env.Clone(parse_flags = '!wx-config --cflags --cxxflags')
3149 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3151 .RI env.Copy([ key = val ", ...])"
3152 A now-deprecated synonym for
3155 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3157 .RI env.CVS( repository ", " module )
3158 A factory function that
3159 returns a Builder object
3160 to be used to fetch source files
3164 The returned Builder
3165 is intended to be passed to the
3169 The optional specified
3171 will be added to the beginning
3172 of all repository path names;
3173 this can be used, in essence,
3174 to strip initial directory names
3175 from the repository path names,
3176 so that you only have to
3177 replicate part of the repository
3178 directory hierarchy in your
3179 local build directory.
3184 # Will fetch foo/bar/src.c
3185 # from /usr/local/CVSROOT/foo/bar/src.c.
3186 env.SourceCode('.', env.CVS('/usr/local/CVSROOT'))
3188 # Will fetch bar/src.c
3189 # from /usr/local/CVSROOT/foo/bar/src.c.
3190 env.SourceCode('.', env.CVS('/usr/local/CVSROOT', 'foo'))
3193 # from /usr/local/CVSROOT/foo/bar/src.c.
3194 env.SourceCode('.', env.CVS('/usr/local/CVSROOT', 'foo/bar'))
3197 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3199 .RI Decider( function )
3201 .RI env.Decider( function )
3202 Specifies that all up-to-date decisions for
3203 targets built through this construction environment
3204 will be handled by the specified
3208 can be one of the following strings
3209 that specify the type of decision function
3215 Specifies that a target shall be considered out of date and rebuilt
3216 if the dependency's timestamp is newer than the target file's timestamp.
3217 This is the behavior of the classic Make utility,
3220 can be used a synonym for
3221 .BR timestamp-newer .
3225 Specifies that a target shall be considered out of date and rebuilt
3226 if the dependency's timestamp is different than the
3227 timestamp recorded the last time the target was built.
3228 This provides behavior very similar to the classic Make utility
3229 (in particular, files are not opened up so that their
3230 contents can be checksummed)
3231 except that the target will also be rebuilt if a
3232 dependency file has been restored to a version with an
3234 timestamp, such as can happen when restoring files from backup archives.
3238 Specifies that a target shall be considered out of date and rebuilt
3239 if the dependency's content has changed sine the last time
3240 the target was built,
3241 as determined be performing an MD5 checksum
3242 on the dependency's contents
3243 and comparing it to the checksum recorded the
3244 last time the target was built.
3246 can be used as a synonym for
3251 Specifies that a target shall be considered out of date and rebuilt
3252 if the dependency's content has changed sine the last time
3253 the target was built,
3254 except that dependencies with a timestamp that matches
3255 the last time the target was rebuilt will be
3256 assumed to be up-to-date and
3259 This provides behavior very similar
3262 behavior of always checksumming file contents,
3263 with an optimization of not checking
3264 the contents of files whose timestamps haven't changed.
3265 The drawback is that SCons will
3267 detect if a file's content has changed
3268 but its timestamp is the same,
3269 as might happen in an automated script
3272 and runs the build again,
3273 all within a single second.
3280 # Use exact timestamp matches by default.
3281 Decider('timestamp-match')
3283 # Use MD5 content signatures for any targets built
3284 # with the attached construction environment.
3285 env.Decider('content')
3289 In addition to the above already-available functions,
3292 argument may be an actual Python function
3293 that takes the following three arguments:
3297 The Node (file) which
3301 if it has "changed" since the last tme
3302 .I target was built.
3305 The Node (file) being built.
3307 this is what should get rebuilt
3313 Stored information about the state of the
3318 This can be consulted to match various
3319 file characteristics
3320 such as the timestamp,
3321 size, or content signature.
3332 has "changed" since the last time
3336 (indicating that the target
3343 (indicating that the target should
3346 Note that the decision can be made
3347 using whatever criteria are appopriate.
3348 Ignoring some or all of the function arguments
3349 is perfectly normal.
3354 def my_decider(dependency, target, prev_ni):
3355 return not os.path.exists(str(target))
3357 env.Decider(my_decider)
3360 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3362 .RI Default( targets )
3364 .RI env.Default( targets )
3365 This specifies a list of default targets,
3366 which will be built by
3368 if no explicit targets are given on the command line.
3372 and add to the list of default targets.
3374 Multiple targets should be specified as
3375 separate arguments to the
3377 method, or as a list.
3379 will also accept the Node returned by any
3380 of a construction environment's
3386 Default('foo', 'bar', 'baz')
3387 env.Default(['a', 'b', 'c'])
3388 hello = env.Program('hello', 'hello.c')
3396 will clear all default targets.
3399 will add to the (now empty) default-target list
3402 The current list of targets added using the
3404 function or method is available in the
3409 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3411 .RI DefaultEnvironment([ args ])
3412 Creates and returns a default construction environment object.
3413 This construction environment is used internally by SCons
3414 in order to execute many of the global functions in this list,
3415 and to fetch source files transparently
3416 from source code management systems.
3418 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3420 .RI Depends( target ", " dependency )
3422 .RI env.Depends( target ", " dependency )
3423 Specifies an explicit dependency;
3435 (usually the path name of a file or directory)
3437 or a list of strings or Node objects
3438 (such as returned by a Builder call).
3439 This should only be necessary
3440 for cases where the dependency
3441 is not caught by a Scanner
3447 env.Depends('foo', 'other-input-file-for-foo')
3449 mylib = env.Library('mylib.c')
3450 installed_lib = env.Install('lib', mylib)
3451 bar = env.Program('bar.c')
3453 # Arrange for the library to be copied into the installation
3454 # directory before trying to build the "bar" program.
3455 # (Note that this is for example only. A "real" library
3456 # dependency would normally be configured through the $LIBS
3457 # and $LIBPATH variables, not using an env.Depends() call.)
3459 env.Depends(bar, installed_lib)
3462 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3464 .RI env.Dictionary([ vars ])
3465 Returns a dictionary object
3466 containing copies of all of the
3467 construction variables in the environment.
3468 If there are any variable names specified,
3469 only the specified construction
3470 variables are returned in the dictionary.
3475 dict = env.Dictionary()
3476 cc_dict = env.Dictionary('CC', 'CCFLAGS', 'CCCOM')
3479 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3481 .RI Dir( name ", [" directory ])
3483 .RI env.Dir( name ", [" directory ])
3484 This returns a Directory Node,
3485 an object that represents the specified directory
3488 can be a relative or absolute path.
3490 is an optional directory that will be used as the parent directory.
3493 is specified, the current script's directory is used as the parent.
3497 is a list, SCons returns a list of Dir nodes.
3498 Construction variables are expanded in
3501 Directory Nodes can be used anywhere you
3502 would supply a string as a directory name
3503 to a Builder method or function.
3504 Directory Nodes have attributes and methods
3505 that are useful in many situations;
3506 see "File and Directory Nodes," below.
3508 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3510 .RI env.Dump([ key ])
3511 Returns a pretty printable representation of the environment.
3515 should be a string containing the name of the variable of interest.
3520 print env.Dump('CCCOM')
3525 \&'$CC -c -o $TARGET $CCFLAGS $CPPFLAGS $_CPPDEFFLAGS $_CPPINCFLAGS $SOURCES'
3536 'ARCOM': '$AR $ARFLAGS $TARGET $SOURCES\n$RANLIB $RANLIBFLAGS $TARGET',
3539 'ASCOM': '$AS $ASFLAGS -o $TARGET $SOURCES',
3544 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3546 .RI EnsurePythonVersion( major ", " minor )
3548 .RI env.EnsurePythonVersion( major ", " minor )
3549 Ensure that the Python version is at least
3552 print out an error message and exit SCons with a non-zero exit code if the
3553 actual Python version is not late enough.
3558 EnsurePythonVersion(2,2)
3561 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3563 .RI EnsureSConsVersion( major ", " minor ", [" revision ])
3565 .RI env.EnsureSConsVersion( major ", " minor ", [" revision ])
3566 Ensure that the SCons version is at least
3569 .IR major.minor.revision .
3574 print out an error message and exit SCons with a non-zero exit code if the
3575 actual SCons version is not late enough.
3580 EnsureSConsVersion(0,14)
3582 EnsureSConsVersion(0,96,90)
3585 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3587 .RI Environment([ key = value ", ...])"
3589 .RI env.Environment([ key = value ", ...])"
3590 Return a new construction environment
3591 initialized with the specified
3595 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3597 .RI Execute( action ", [" strfunction ", " varlist ])
3599 .RI env.Execute( action ", [" strfunction ", " varlist ])
3600 Executes an Action object.
3603 may be an Action object
3604 (see the section "Action Objects,"
3605 below, for a complete explanation of the arguments and behavior),
3606 or it may be a command-line string,
3608 or executable Python function,
3609 each of which will be converted
3610 into an Action object
3612 The exit value of the command
3613 or return value of the Python function
3618 will print an error message if the executed
3621 exits with or returns a non-zero value.
3626 automatically terminate the build
3630 If you want the build to stop in response to a failed
3633 you must explicitly check for a non-zero return value:
3636 Execute(Copy('file.out', 'file.in'))
3638 if Execute("mkdir sub/dir/ectory"):
3639 # The mkdir failed, don't try to build.
3643 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3647 .RI env.Exit([ value ])
3653 A default exit value of
3656 is used if no value is specified.
3658 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3662 .RI env.Export( vars )
3665 to export a list of variables from the current
3666 SConscript file to all other SConscript files.
3667 The exported variables are kept in a global collection,
3668 so subsequent calls to
3670 will over-write previous exports that have the same name.
3671 Multiple variable names can be passed to
3673 as separate arguments or as a list.
3674 Keyword arguments can be used to provide names and their values.
3675 A dictionary can be used to map variables to a different name when exported.
3676 Both local variables and global variables can be exported.
3682 # Make env available for all SConscript files to Import().
3686 # Make env and package available for all SConscript files:.
3687 Export("env", "package")
3689 # Make env and package available for all SConscript files:
3690 Export(["env", "package"])
3692 # Make env available using the name debug:
3695 # Make env available using the name debug:
3696 Export({"debug":env})
3702 function supports an
3704 argument that makes it easier to to export a variable or
3705 set of variables to a single SConscript file.
3706 See the description of the
3710 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3712 .RI File( name ", [" directory ])
3714 .RI env.File( name ", [" directory ])
3717 an object that represents the specified file
3720 can be a relative or absolute path.
3722 is an optional directory that will be used as the parent directory.
3726 is a list, SCons returns a list of File nodes.
3727 Construction variables are expanded in
3730 File Nodes can be used anywhere you
3731 would supply a string as a file name
3732 to a Builder method or function.
3733 File Nodes have attributes and methods
3734 that are useful in many situations;
3735 see "File and Directory Nodes," below.
3737 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3739 .RI FindFile( file ", " dirs )
3741 .RI env.FindFile( file ", " dirs )
3744 in the path specified by
3747 may be a list of directory names or a single directory name.
3748 In addition to searching for files that exist in the filesytem,
3749 this function also searches for derived files
3750 that have not yet been built.
3755 foo = env.FindFile('foo', ['dir1', 'dir2'])
3758 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3760 .RI FindInstalledFiles( )
3762 .RI env.FindInstalledFiles( )
3763 Returns the list of targets set up by the
3769 This function serves as a convenient method to select the contents of
3775 Install( '/bin', [ 'executable_a', 'executable_b' ] )
3777 # will return the file node list
3778 # [ '/bin/executable_a', '/bin/executable_b' ]
3779 FindInstalledFiles()
3781 Install( '/lib', [ 'some_library' ] )
3783 # will return the file node list
3784 # [ '/bin/executable_a', '/bin/executable_b', '/lib/some_library' ]
3785 FindInstalledFiles()
3788 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3790 .RI FindSourceFiles( node = '"."' )
3792 .RI env.FindSourceFiles( node = '"."' )
3794 Returns the list of nodes which serve as the source of the built files.
3795 It does so by inspecting the dependency tree starting at the optional
3798 which defaults to the '"."'-node. It will then return all leaves of
3800 These are all children which have no further children.
3802 This function is a convenient method to select the contents of a Source
3808 Program( 'src/main_a.c' )
3809 Program( 'src/main_b.c' )
3810 Program( 'main_c.c' )
3812 # returns ['main_c.c', 'src/main_a.c', 'SConstruct', 'src/main_b.c']
3815 # returns ['src/main_b.c', 'src/main_a.c' ]
3816 FindSourceFiles( 'src' )
3820 As you can see build support files (SConstruct in the above example)
3821 will also be returned by this function.
3823 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3825 .RI FindPathDirs( variable )
3827 (actually a callable Python object)
3828 intended to be used as the
3830 of a Scanner object.
3831 The returned object will look up the specified
3833 in a construction environment
3834 and treat the construction variable's value as a list of
3835 directory paths that should be searched
3843 is generally preferable to
3846 for the following reasons:
3847 1) The returned list will contain all appropriate directories
3848 found in source trees
3852 or in code repositories
3858 2) scons will identify expansions of
3860 that evaluate to the same list of directories as,
3861 in fact, the same list,
3862 and avoid re-scanning the directories for files,
3868 def my_scan(node, env, path, arg):
3869 # Code to scan file contents goes here...
3870 return include_files
3872 scanner = Scanner(name = 'myscanner',
3874 path_function = FindPathDirs('MYPATH'))
3877 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3879 .RI Flatten( sequence )
3881 .RI env.Flatten( sequence )
3882 Takes a sequence (that is, a Python list or tuple)
3883 that may contain nested sequences
3884 and returns a flattened list containing
3885 all of the individual elements in any sequence.
3886 This can be helpful for collecting
3887 the lists returned by calls to Builders;
3888 other Builders will automatically
3889 flatten lists specified as input,
3890 but direct Python manipulation of
3891 these lists does not.
3896 foo = Object('foo.c')
3897 bar = Object('bar.c')
3899 # Because `foo' and `bar' are lists returned by the Object() Builder,
3900 # `objects' will be a list containing nested lists:
3901 objects = ['f1.o', foo, 'f2.o', bar, 'f3.o']
3903 # Passing such a list to another Builder is all right because
3904 # the Builder will flatten the list automatically:
3905 Program(source = objects)
3907 # If you need to manipulate the list directly using Python, you need to
3908 # call Flatten() yourself, or otherwise handle nested lists:
3909 for object in Flatten(objects):
3913 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3915 .RI GetBuildFailures()
3916 Returns a list of exceptions for the
3917 actions that failed while
3918 attempting to build targets.
3919 Each element in the returned list is a
3922 with the following attributes
3923 that record various aspects
3924 of the build failure:
3927 The node that was being built
3928 when the build failure occurred.
3931 The numeric exit status
3932 returned by the command or Python function
3933 that failed when trying to build the
3937 The SCons error string
3938 describing the build failure.
3939 (This is often a generic
3940 message like "Error 2"
3941 to indicate that an executed
3942 command exited with a status of 2.)
3945 The name of the file or
3946 directory that actually caused the failure.
3947 This may be different from the
3951 if an attempt to build a target named
3955 directory could not be created,
3966 The SCons Executor object
3969 This can be used to retrieve
3970 the construction environment used
3971 for the failed action.
3974 The actual SCons Action object that failed.
3975 This will be one specific action
3976 out of the possible list of
3977 actions that would have been
3978 executed to build the target.
3981 The actual expanded command that was executed and failed,
3985 and other construction variables.
3988 .BR GetBuildFailures ()
3990 will always return an empty list
3991 until any build failure has occurred,
3993 .BR GetBuildFailures ()
3994 will always return an empty list
3997 files are being read.
3998 Its primary intended use is
3999 for functions that will be
4000 executed before SCons exits
4001 by passing them to the
4003 .BR atexit.register ()
4010 def print_build_failures():
4011 from SCons.Script import GetBuildFailures
4012 for bf in GetBuildFailures():
4013 print "%s failed: %s" % (bf.node, bf.errstr)
4015 atexit.register(print_build_failures)
4018 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4020 .RI GetBuildPath( file ", [" ... ])
4022 .RI env.GetBuildPath( file ", [" ... ])
4025 path name (or names) for the specified
4033 Nodes or strings representing path names.
4035 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4039 .RI env.GetLaunchDir()
4040 Returns the absolute path name of the directory from which
4042 was initially invoked.
4043 This can be useful when using the
4048 options, which internally
4049 change to the directory in which the
4053 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4055 .RI GetOption( name )
4057 .RI env.GetOption( name )
4058 This function provides a way to query the value of
4059 SCons options set on scons command line
4063 The options supported are:
4068 which corresponds to --cache-debug;
4071 which corresponds to --cache-disable;
4074 which corresponds to --cache-force;
4077 which corresponds to --cache-show;
4080 which corresponds to -c, --clean and --remove;
4083 which corresponds to --config;
4086 which corresponds to -C and --directory;
4089 which corresponds to --diskcheck
4092 which corresponds to --duplicate;
4095 which corresponds to -f, --file, --makefile and --sconstruct;
4098 which corresponds to -h and --help;
4101 which corresponds to --ignore-errors;
4104 which corresponds to --implicit-cache;
4106 .B implicit_deps_changed
4107 which corresponds to --implicit-deps-changed;
4109 .B implicit_deps_unchanged
4110 which corresponds to --implicit-deps-unchanged;
4113 which corresponds to --interact and --interactive;
4116 which corresponds to -k and --keep-going;
4119 which corresponds to --max-drift;
4122 which corresponds to -n, --no-exec, --just-print, --dry-run and --recon;
4125 which corresponds to --no-site-dir;
4128 which corresponds to -j and --jobs;
4131 which corresponds to --profile;
4134 which corresponds to -q and --question;
4137 which corresponds to --random;
4140 which corresponds to -Y, --repository and --srcdir;
4143 which corresponds to -s, --silent and --quiet;
4146 which corresponds to --site-dir;
4149 which corresponds to --stack-size;
4151 .B taskmastertrace_file
4152 which corresponds to --taskmastertrace; and
4155 which corresponds to --warn and --warning.
4159 See the documentation for the
4160 corresponding command line object for information about each specific
4163 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4165 .RI Glob( pattern ", [" ondisk ", " source ", " strings ])
4167 .RI env.Glob( pattern ", [" ondisk ", " source ", " strings ])
4168 Returns Nodes (or strings) that match the specified
4170 relative to the directory of the current
4175 form performs string substition on
4177 and returns whatever matches
4178 the resulting expanded pattern.
4182 uses Unix shell style metacharacters for matching:
4185 * matches everything
4186 ? matches any single character
4187 [seq] matches any character in seq
4188 [!seq] matches any char not in seq
4192 If the first character of a filename is a dot,
4193 it must be matched explicitly.
4194 Character matches do
4196 span directory separators.
4205 and source directories
4210 returns a Node (or string, if so configured)
4211 in the local (SConscript) directory
4212 if matching Node is found
4213 anywhere in a corresponding
4214 repository or source directory.
4218 argument may be set to
4220 (or any other non-true value)
4221 to disable the search for matches on disk,
4222 thereby only returning matches among
4223 already-configured File or Dir Nodes.
4224 The default behavior is to
4225 return corresponding Nodes
4226 for any on-disk matches found.
4230 argument may be set to
4232 (or any equivalent value)
4234 when the local directory is a
4236 the returned Nodes should be from the
4237 corresponding source directory,
4238 not the local directory.
4242 argument may be set to
4244 (or any equivalent value)
4247 function return strings, not Nodes,
4248 that represent the matched files or directories.
4249 The returned strings will be relative to
4250 the local (SConscript) directory.
4251 (Note that This may make it easier to perform
4252 arbitrary manipulation of file names,
4253 but if the returned strings are
4254 passed to a different
4257 any Node translation will be relative
4268 Program('foo', Glob('*.c'))
4269 Zip('/tmp/everything', Glob('.??*') + Glob('*'))
4272 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4274 '\".RI GlobalBuilders( flag )
4278 '\"adds the names of the default builders
4279 '\"(Program, Library, etc.)
4280 '\"to the global name space
4281 '\"so they can be called without an explicit construction environment.
4282 '\"(This is the default.)
4286 '\"the names of the default builders are removed
4287 '\"from the global name space
4288 '\"so that an explicit construction environment is required
4289 '\"to call all builders.
4291 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4295 .RI env.Help( text )
4296 This specifies help text to be printed if the
4298 argument is given to
4302 is called multiple times, the text is appended together in the order
4307 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4309 .RI Ignore( target ", " dependency )
4311 .RI env.Ignore( target ", " dependency )
4312 The specified dependency file(s)
4313 will be ignored when deciding if
4314 the target file(s) need to be rebuilt.
4318 to remove a target from the default build.
4319 In order to do this you must specify the directory the target will
4320 be built in as the target, and the file you want to skip building
4323 Note that this will only remove the dependencies listed from
4324 the files built by default. It will still be built if that
4325 dependency is needed by another object being built.
4326 See the third and forth examples below.
4331 env.Ignore('foo', 'foo.c')
4332 env.Ignore('bar', ['bar1.h', 'bar2.h'])
4333 env.Ignore('.','foobar.obj')
4334 env.Ignore('bar','bar/foobar.obj')
4337 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4341 .RI env.Import( vars )
4344 to import a list of variables into the current SConscript file. This
4345 will import variables that were exported with
4351 Variables exported by
4354 Multiple variable names can be passed to
4356 as separate arguments or as a list. The variable "*" can be used
4357 to import all variables.
4363 Import("env", "variable")
4364 Import(["env", "variable"])
4368 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4370 .RI Literal( string )
4372 .RI env.Literal( string )
4375 will be preserved as-is
4376 and not have construction variables expanded.
4378 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4380 .RI Local( targets )
4382 .RI env.Local( targets )
4385 will have copies made in the local tree,
4386 even if an already up-to-date copy
4387 exists in a repository.
4388 Returns a list of the target Node or Nodes.
4390 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4392 \" .RI env.MergeShellPaths( arg ", [" prepend ])
4393 \" Merges the elements of the specified
4395 \" which must be a dictionary, to the construction
4396 \" environment's copy of the shell environment
4398 \" (This is the environment which is passed
4399 \" to subshells spawned by SCons.)
4402 \" must be a single value,
4403 \" so multiple strings must
4404 \" be passed in as a list,
4405 \" not as separate arguments to
4406 \" .BR env.MergeShellPaths ().
4408 \" New values are prepended to the environment variable by default,
4409 \" unless prepend=0 is specified.
4410 \" Duplicate values are always eliminated,
4411 \" since this function calls
4414 \" .B PrependENVPath
4417 \" argument. See those functions for more details.
4422 \" # Prepend a path to the shell PATH.
4423 \" env.MergeShellPaths({'PATH':'/usr/local/bin'} )
4424 \" # Append two dirs to the shell INCLUDE.
4425 \" env.MergeShellPaths({'INCLUDE':['c:/inc1', 'c:/inc2']}, prepend=0 )
4429 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4431 .RI env.MergeFlags( arg ", [" unique ])
4432 Merges the specified
4434 values to the construction environment's construction variables.
4437 argument is not a dictionary,
4438 it is converted to one by calling
4441 before the values are merged.
4444 must be a single value,
4445 so multiple strings must
4446 be passed in as a list,
4447 not as separate arguments to
4448 .BR env.MergeFlags ().
4451 duplicate values are eliminated;
4452 you can, however, specify
4456 When eliminating duplicate values,
4457 any construction variables that end with
4460 keep the left-most unique value.
4461 All other construction variables keep
4462 the right-most unique value.
4467 # Add an optimization flag to $CCFLAGS.
4468 env.MergeFlags('-O3')
4470 # Combine the flags returned from running pkg-config with an optimization
4471 # flag and merge the result into the construction variables.
4472 env.MergeFlags(['!pkg-config gtk+-2.0 --cflags', '-O3'])
4474 # Combine an optimization flag with the flags returned from running pkg-config
4475 # twice and merge the result into the construction variables.
4476 env.MergeFlags(['-O3',
4477 '!pkg-config gtk+-2.0 --cflags --libs',
4478 '!pkg-config libpng12 --cflags --libs'])
4481 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4483 .RI NoCache( target ", ...)"
4485 .RI env.NoCache( target ", ...)"
4486 Specifies a list of files which should
4488 be cached whenever the
4490 method has been activated.
4491 The specified targets may be a list
4492 or an individual target.
4494 Multiple files should be specified
4495 either as separate arguments to the
4497 method, or as a list.
4499 will also accept the return value of any of the construction environment
4504 on directories and other non-File Node types has no effect because
4505 only File Nodes are cached.
4511 NoCache(env.Program('hello', 'hello.c'))
4514 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4516 .RI NoClean( target ", ...)"
4518 .RI env.NoClean( target ", ...)"
4519 Specifies a list of files or directories which should
4521 be removed whenever the targets (or their dependencies)
4522 are specified with the
4524 command line option.
4525 The specified targets may be a list
4526 or an individual target.
4530 and prevent each specified target
4531 from being removed by calls to the
4535 Multiple files or directories should be specified
4536 either as separate arguments to the
4538 method, or as a list.
4540 will also accept the return value of any of the construction environment
4545 for a target overrides calling
4547 for the same target,
4548 and any targets passed to both functions will
4558 NoClean(env.Program('hello', 'hello.c'))
4561 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4563 .RI env.ParseConfig( command ", [" function ", " unique ])
4566 to modify the environment as specified by the output of
4571 .BR env.MergeFlags (),
4572 which expects the output of a typical
4576 and adds the options
4577 to the appropriate construction variables.
4579 duplicate values are not
4580 added to any construction variables;
4587 and the construction variables they affect
4588 are as specified for the
4589 .BR env.ParseFlags ()
4590 method (which this method calls).
4591 See that method's description, below,
4592 for a table of options and construction variables.
4594 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4596 .RI ParseDepends( filename ", [" must_exist ", " only_one ])
4598 .RI env.ParseDepends( filename ", [" must_exist ", " only_one ])
4599 Parses the contents of the specified
4601 as a list of dependencies in the style of
4605 and explicitly establishes all of the listed dependencies.
4614 argument may be set to a non-zero
4617 throw an exception and
4618 generate an error if the file does not exist,
4619 or is otherwise inaccessible.
4623 argument may be set to a non-zero
4626 thrown an exception and
4628 if the file contains dependency
4629 information for more than one target.
4630 This can provide a small sanity check
4631 for files intended to be generated
4632 by, for example, the
4635 which should typically only
4636 write dependency information for
4637 one output file into a corresponding
4643 and all of the files listed therein
4644 will be interpreted relative to
4645 the directory of the
4647 file which calls the
4651 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4653 .RI env.ParseFlags( flags ", ...)"
4654 Parses one or more strings containing
4655 typical command-line flags for GCC tool chains
4656 and returns a dictionary with the flag values
4657 separated into the appropriate SCons construction variables.
4658 This is intended as a companion to the
4659 .BR env.MergeFlags ()
4660 method, but allows for the values in the returned dictionary
4661 to be modified, if necessary,
4662 before merging them into the construction environment.
4664 .BR env.MergeFlags ()
4665 will call this method if its argument is not a dictionary,
4666 so it is usually not necessary to call
4667 .BR env.ParseFlags ()
4668 directly unless you want to manipulate the values.)
4670 If the first character in any string is
4671 an exclamation mark (!),
4672 the rest of the string is executed as a command,
4673 and the output from the command is
4674 parsed as GCC tool chain command-line flags
4675 and added to the resulting dictionary.
4677 Flag values are translated accordig to the prefix found,
4678 and added to the following construction variables:
4681 -arch CCFLAGS, LINKFLAGS
4683 -framework FRAMEWORKS
4684 -frameworkdir= FRAMEWORKPATH
4686 -isysroot CCFLAGS, LINKFLAGS
4690 -mno-cygwin CCFLAGS, LINKFLAGS
4692 -pthread CCFLAGS, LINKFLAGS
4694 -Wa, ASFLAGS, CCFLAGS
4701 + CCFLAGS, LINKFLAGS
4705 Any other strings not associated with options
4706 are assumed to be the names of libraries
4709 construction variable.
4711 Examples (all of which produce the same result):
4714 dict = env.ParseFlags('-O2 -Dfoo -Dbar=1')
4715 dict = env.ParseFlags('-O2', '-Dfoo', '-Dbar=1')
4716 dict = env.ParseFlags(['-O2', '-Dfoo -Dbar=1'])
4717 dict = env.ParseFlags('-O2', '!echo -Dfoo -Dbar=1')
4720 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4723 A factory function that
4724 returns a Builder object
4725 to be used to fetch source files
4726 from the Perforce source code management system.
4727 The returned Builder
4728 is intended to be passed to the
4735 env.SourceCode('.', env.Perforce())
4738 Perforce uses a number of external
4739 environment variables for its operation.
4740 Consequently, this function adds the
4741 following variables from the user's external environment
4742 to the construction environment's
4755 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4757 .RI Platform( string )
4758 Returns a callable object
4759 that can be used to initialize
4760 a construction environment using the
4761 platform keyword of the Environment() method.
4766 env = Environment(platform = Platform('win32'))
4769 .RI env.Platform( string )
4770 Applies the callable object for the specified platform
4772 to the environment through which the method was called.
4775 env.Platform('posix')
4784 variables from the user's external environment
4785 to the construction environment's
4788 This is so that any executed commands
4789 that use sockets to connect with other systems
4790 (such as fetching source files from
4791 external CVS repository specifications like
4792 .BR :pserver:anonymous@cvs.sourceforge.net:/cvsroot/scons )
4793 will work on Windows systems.
4795 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4797 .RI Progress( callable ", [" interval ])
4799 .RI Progress( string ", [" interval ", " file ", " overwrite ])
4801 .RI Progress( list_of_strings ", [" interval ", " file ", " overwrite ])
4802 Allows SCons to show progress made during the build
4803 by displaying a string or calling a function while
4804 evaluating Nodes (e.g. files).
4806 If the first specified argument is a Python callable
4807 (a function or an object that has a
4810 the function will be called
4813 times a Node is evaluated.
4814 The callable will be passed the evaluated Node
4815 as its only argument.
4816 (For future compatibility,
4817 it's a good idea to also add
4821 as arguments to your function or method.
4822 This will prevent the code from breaking
4823 if SCons ever changes the interface
4824 to call the function with additional arguments in the future.)
4826 An example of a simple custom progress function
4827 that prints a string containing the Node name
4831 def my_progress_function(node, *args, **kw):
4832 print 'Evaluating node %s!' % node
4833 Progress(my_progress_function, interval=10)
4836 A more complicated example of a custom progress display object
4837 that prints a string containing a count
4838 every 100 evaluated Nodes.
4842 at the end so that the string
4843 will overwrite itself on a display:
4847 class ProgressCounter:
4849 def __call__(self, node, *args, **kw):
4851 sys.stderr.write('Evaluated %s nodes\\r' % self.count)
4852 Progress(ProgressCounter(), interval=100)
4855 If the first argument
4858 the string will be displayed
4862 The default is to print the string on standard output;
4863 an alternate output stream
4864 may be specified with the
4867 The following will print a series of dots
4868 on the error output,
4869 one dot for every 100 evaluated Nodes:
4873 Progress('.', interval=100, file=sys.stderr)
4876 If the string contains the verbatim substring
4878 it will be replaced with the Node.
4879 Note that, for performance reasons, this is
4881 a regular SCons variable substition,
4882 so you can not use other variables
4883 or use curly braces.
4884 The following example will print the name of
4885 every evaluated Node,
4888 (carriage return) to cause each line to overwritten by the next line,
4891 keyword argument to make sure the previously-printed
4892 file name is overwritten with blank spaces:
4896 Progress('$TARGET\\r', overwrite=True)
4899 If the first argument to
4901 is a list of strings,
4902 then each string in the list will be displayed
4903 in rotating fashion every
4906 This can be used to implement a "spinner"
4907 on the user's screen as follows:
4910 Progress(['-\\r', '\\\\\\r', '|\\r', '/\\r'], interval=5)
4913 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4915 .RI Precious( target ", ...)"
4917 .RI env.Precious( target ", ...)"
4920 as precious so it is not deleted before it is rebuilt. Normally
4922 deletes a target before building it.
4923 Multiple targets can be passed in to a single call to
4926 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4928 .RI env.Prepend( key = val ", [...])"
4929 Appends the specified keyword arguments
4930 to the beginning of construction variables in the environment.
4931 If the Environment does not have
4932 the specified construction variable,
4933 it is simply added to the environment.
4934 If the values of the construction variable
4935 and the keyword argument are the same type,
4936 then the two values will be simply added together.
4937 Otherwise, the construction variable
4938 and the value of the keyword argument
4939 are both coerced to lists,
4940 and the lists are added together.
4941 (See also the Append method, above.)
4946 env.Prepend(CCFLAGS = '-g ', FOO = ['foo.yyy'])
4949 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4951 .RI env.PrependENVPath( name ", " newpath ", [" envname ", " sep ", " delete_existing ])
4952 This appends new path elements to the given path in the
4953 specified external environment
4957 any particular path once (leaving the first one it encounters and
4958 ignoring the rest, to preserve path order),
4959 and to help assure this,
4960 will normalize all paths (using
4963 .BR os.path.normcase ).
4964 This can also handle the
4965 case where the given old path variable is a list instead of a
4966 string, in which case a list will be returned instead of a string.
4970 is 0, then adding a path that already exists
4971 will not move it to the beginning;
4972 it will stay where it is in the list.
4977 print 'before:',env['ENV']['INCLUDE']
4978 include_path = '/foo/bar:/foo'
4979 env.PrependENVPath('INCLUDE', include_path)
4980 print 'after:',env['ENV']['INCLUDE']
4983 The above exmaple will print:
4987 after: /foo/bar:/foo:/biz
4990 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4992 .RI env.PrependUnique( key = val ", delete_existing=0, [...])"
4993 Appends the specified keyword arguments
4994 to the beginning of construction variables in the environment.
4995 If the Environment does not have
4996 the specified construction variable,
4997 it is simply added to the environment.
4998 If the construction variable being appended to is a list,
4999 then any value(s) that already exist in the
5000 construction variable will
5002 be added again to the list.
5003 However, if delete_existing is 1,
5004 existing matching values are removed first, so
5005 existing values in the arg list move to the front of the list.
5010 env.PrependUnique(CCFLAGS = '-g', FOO = ['foo.yyy'])
5013 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
5016 A factory function that
5017 returns a Builder object
5018 to be used to fetch source files
5020 The returned Builder
5021 is intended to be passed to the
5028 env.SourceCode('.', env.RCS())
5033 will fetch source files
5034 from RCS subdirectories automatically,
5036 as demonstrated in the above example
5037 should only be necessary if
5038 you are fetching from
5041 directory as the source files,
5042 or if you need to explicitly specify RCS
5043 for a specific subdirectory.
5045 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
5047 .RI env.Replace( key = val ", [...])"
5048 Replaces construction variables in the Environment
5049 with the specified keyword arguments.
5054 env.Replace(CCFLAGS = '-g', FOO = 'foo.xxx')
5057 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
5059 .RI Repository( directory )
5061 .RI env.Repository( directory )
5064 is a repository to be searched for files.
5068 and each one adds to the list of
5069 repositories that will be searched.
5073 a repository is a copy of the source tree,
5074 from the top-level directory on down,
5076 both source files and derived files
5077 that can be used to build targets in
5078 the local source tree.
5079 The canonical example would be an
5080 official source tree maintained by an integrator.
5081 If the repository contains derived files,
5082 then the derived files should have been built using
5084 so that the repository contains the necessary
5085 signature information to allow
5087 to figure out when it is appropriate to
5088 use the repository copy of a derived file,
5089 instead of building one locally.
5091 Note that if an up-to-date derived file
5092 already exists in a repository,
5096 make a copy in the local directory tree.
5097 In order to guarantee that a local copy
5103 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
5105 .RI Requires( target ", " prerequisite )
5107 .RI env.Requires( target ", " prerequisite )
5108 Specifies an order-only relationship
5109 between the specified target file(s)
5110 and the specified prerequisite file(s).
5111 The prerequisite file(s)
5112 will be (re)built, if necessary,
5115 but the target file(s) do not actually
5116 depend on the prerequisites
5117 and will not be rebuilt simply because
5118 the prerequisite file(s) change.
5123 env.Requires('foo', 'file-that-must-be-built-before-foo')
5126 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
5128 .RI Return([ vars "... , " stop= ])
5130 this stops processing the current SConscript
5131 file and returns to the calling SConscript file
5132 the values of the variables named in the
5135 Multiple strings contaning variable names may be passed to
5137 Any strings that contain white space
5141 keyword argument may be set to a false value
5142 to continue processing the rest of the SConscript
5146 This was the default behavior prior to SCons 0.98.
5147 However, the values returned
5148 are still the values of the variables in the named
5157 # Returns without returning a value.
5160 # Returns the value of the 'foo' Python variable.
5163 # Returns the values of the Python variables 'foo' and 'bar'.
5164 Return("foo", "bar")
5166 # Returns the values of Python variables 'val1' and 'val2'.
5170 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
5172 .RI Scanner( function ", [" argument ", " keys ", " path_function ", " node_class ", " node_factory ", " scan_check ", " recursive ])
5174 .RI env.Scanner( function ", [" argument ", " keys ", " path_function ", " node_class ", " node_factory ", " scan_check ", " recursive ])
5175 Creates a Scanner object for
5178 See the section "Scanner Objects,"
5179 below, for a complete explanation of the arguments and behavior.
5181 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
5184 A factory function that
5185 returns a Builder object
5186 to be used to fetch source files
5188 The returned Builder
5189 is intended to be passed to the
5196 env.SourceCode('.', env.SCCS())
5201 will fetch source files
5202 from SCCS subdirectories automatically,
5204 as demonstrated in the above example
5205 should only be necessary if
5206 you are fetching from
5209 directory as the source files,
5210 or if you need to explicitly specify SCCS
5211 for a specific subdirectory.
5213 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
5215 .RI SConscript( scripts ", [" exports ", " variant_dir ", " duplicate ])
5216 '\" .RI SConscript( scripts ", [" exports ", " variant_dir ", " src_dir ", " duplicate ])
5218 .RI env.SConscript( scripts ", [" exports ", " variant_dir ", " duplicate ])
5219 '\" .RI env.SConscript( scripts ", [" exports ", " variant_dir ", " src_dir ", " duplicate ])
5221 .RI SConscript(dirs= subdirs ", [name=" script ", " exports ", " variant_dir ", " duplicate ])
5222 '\" .RI SConscript(dirs= subdirs ", [name=" script ", " exports ", " variant_dir ", " src_dir ", " duplicate ])
5224 .RI env.SConscript(dirs= subdirs ", [name=" script ", " exports ", " variant_dir ", " duplicate ])
5225 '\" .RI env.SConscript(dirs= subdirs ", [name=" script ", " exports ", " variant_dir ", " src_dir ", " duplicate ])
5229 one or more subsidiary SConscript (configuration) files.
5230 Any variables returned by a called script using
5232 will be returned by the call to
5234 There are two ways to call the
5238 The first way you can call
5240 is to explicitly specify one or more
5242 as the first argument.
5243 A single script may be specified as a string;
5244 multiple scripts must be specified as a list
5245 (either explicitly or as created by
5250 SConscript('SConscript') # run SConscript in the current directory
5251 SConscript('src/SConscript') # run SConscript in the src directory
5252 SConscript(['src/SConscript', 'doc/SConscript'])
5253 config = SConscript('MyConfig.py')
5256 The second way you can call
5258 is to specify a list of (sub)directory names
5265 execute a subsidiary configuration file named
5267 in each of the specified directories.
5268 You may specify a name other than
5270 by supplying an optional
5273 The first three examples below have the same effect
5274 as the first three examples above:
5276 SConscript(dirs='.') # run SConscript in the current directory
5277 SConscript(dirs='src') # run SConscript in the src directory
5278 SConscript(dirs=['src', 'doc'])
5279 SConscript(dirs=['sub1', 'sub2'], name='MySConscript')
5284 argument provides a list of variable names or a dictionary of
5285 named values to export to the
5287 These variables are locally exported only to the specified
5289 and do not affect the global pool of variables used by the
5292 '\"If multiple dirs are provided, each script gets a fresh export.
5297 function to import the variables.
5300 foo = SConscript('sub/SConscript', exports='env')
5301 SConscript('dir/SConscript', exports=['env', 'variable'])
5302 SConscript(dirs='subdir', exports='env variable')
5303 SConscript(dirs=['one', 'two', 'three'], exports='shared_info')
5308 argument is present, it causes an effect equivalent to the
5310 method described below.
5316 '\" arguments are ignored.)
5317 argument is ignored.)
5322 '\" arguments are interpreted relative to the directory of the calling
5323 argument is interpreted relative to the directory of the calling
5326 See the description of the
5328 function below for additional details and restrictions.
5334 '\" .IR src_dir " is not,"
5335 the source directory is the directory in which the
5337 file resides and the
5339 file is evaluated as if it were in the
5343 SConscript('src/SConscript', variant_dir = 'build')
5347 VariantDir('build', 'src')
5348 SConscript('build/SConscript')
5350 This later paradigm is often used when the sources are
5351 in the same directory as the
5354 SConscript('SConscript', variant_dir = 'build')
5358 VariantDir('build', '.')
5359 SConscript('build/SConscript')
5363 '\" .IR variant_dir " and"
5364 '\" .IR src_dir " are both present,"
5365 '\" xxxxx everything is in a state of confusion.
5367 '\" SConscript(dirs = 'src', variant_dir = 'build', src_dir = '.')
5368 '\" runs src/SConscript in build/src, but
5369 '\" SConscript(dirs = 'lib', variant_dir = 'build', src_dir = 'src')
5370 '\" runs lib/SConscript (in lib!). However,
5371 '\" SConscript(dirs = 'src', variant_dir = 'build', src_dir = 'src')
5372 '\" runs src/SConscript in build. Moreover,
5373 '\" SConscript(dirs = 'src/lib', variant_dir = 'build', src_dir = 'src')
5374 '\" runs src/lib/SConscript in build/lib. Moreover,
5375 '\" SConscript(dirs = 'build/src/lib', variant_dir = 'build', src_dir = 'src')
5376 '\" can't find build/src/lib/SConscript, even though it ought to exist.
5378 '\" is equivalent to
5380 '\" ????????????????
5382 '\" and what about this alternative?
5383 '\"TODO??? SConscript('build/SConscript', src_dir='src')
5385 Here are some composite examples:
5388 # collect the configuration information and use it to build src and doc
5389 shared_info = SConscript('MyConfig.py')
5390 SConscript('src/SConscript', exports='shared_info')
5391 SConscript('doc/SConscript', exports='shared_info')
5395 # build debugging and production versions. SConscript
5396 # can use Dir('.').path to determine variant.
5397 SConscript('SConscript', variant_dir='debug', duplicate=0)
5398 SConscript('SConscript', variant_dir='prod', duplicate=0)
5402 # build debugging and production versions. SConscript
5403 # is passed flags to use.
5404 opts = { 'CPPDEFINES' : ['DEBUG'], 'CCFLAGS' : '-pgdb' }
5405 SConscript('SConscript', variant_dir='debug', duplicate=0, exports=opts)
5406 opts = { 'CPPDEFINES' : ['NODEBUG'], 'CCFLAGS' : '-O' }
5407 SConscript('SConscript', variant_dir='prod', duplicate=0, exports=opts)
5411 # build common documentation and compile for different architectures
5412 SConscript('doc/SConscript', variant_dir='build/doc', duplicate=0)
5413 SConscript('src/SConscript', variant_dir='build/x86', duplicate=0)
5414 SConscript('src/SConscript', variant_dir='build/ppc', duplicate=0)
5417 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
5419 .RI SConscriptChdir( value )
5421 .RI env.SConscriptChdir( value )
5424 changes its working directory
5425 to the directory in which each
5426 subsidiary SConscript file lives.
5427 This behavior may be disabled
5428 by specifying either:
5432 env.SConscriptChdir(0)
5437 will stay in the top-level directory
5438 while reading all SConscript files.
5439 (This may be necessary when building from repositories,
5440 when all the directories in which SConscript files may be found
5441 don't necessarily exist locally.)
5442 You may enable and disable
5443 this ability by calling
5452 SConscript('foo/SConscript') # will not chdir to foo
5453 env.SConscriptChdir(1)
5454 SConscript('bar/SConscript') # will chdir to bar
5457 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
5459 .RI SConsignFile([ file , dbm_module ])
5461 .RI env.SConsignFile([ file , dbm_module ])
5464 to store all file signatures
5465 in the specified database
5472 (The actual file name(s) stored on disk
5473 may have an appropriated suffix appended
5478 is not an absolute path name,
5479 the file is placed in the same directory as the top-level
5489 will store file signatures
5492 file in each directory,
5493 not in one global database file.
5494 (This was the default behavior
5495 prior to SCons 0.96.91 and 0.97.)
5499 argument can be used to specify
5500 which Python database module
5501 The default is to use a custom
5503 module that uses pickled
5504 Python data structures,
5505 and which works on all Python versions from 1.5.2 on.
5510 # Explicitly stores signatures in ".sconsign.dblite"
5511 # in the top-level SConstruct directory (the
5512 # default behavior).
5515 # Stores signatures in the file "etc/scons-signatures"
5516 # relative to the top-level SConstruct directory.
5517 SConsignFile("etc/scons-signatures")
5519 # Stores signatures in the specified absolute file name.
5520 SConsignFile("/home/me/SCons/signatures")
5522 # Stores signatures in a separate .sconsign file
5523 # in each directory.
5527 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
5529 .RI env.SetDefault(key = val ", [...])"
5530 Sets construction variables to default values specified with the keyword
5531 arguments if (and only if) the variables are not already set.
5532 The following statements are equivalent:
5535 env.SetDefault(FOO = 'foo')
5537 if not env.has_key('FOO'): env['FOO'] = 'foo'
5540 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
5542 .RI SetOption( name ", " value )
5544 .RI env.SetOption( name ", " value )
5545 This function provides a way to set a select subset of the scons command
5546 line options from a SConscript file. The options supported are:
5551 which corresponds to -c, --clean and --remove;
5554 which corresponds to --duplicate;
5557 which corresponds to -h and --help;
5560 which corresponds to --implicit-cache;
5563 which corresponds to --max-drift;
5566 which corresponds to -n, --no-exec, --just-print, --dry-run and --recon;
5569 which corresponds to -j and --jobs;
5572 which corresponds to --random; and
5575 which corresponds to --stack-size.
5579 See the documentation for the
5580 corresponding command line object for information about each specific
5586 SetOption('max_drift', 1)
5589 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
5591 .RI SideEffect( side_effect ", " target )
5593 .RI env.SideEffect( side_effect ", " target )
5596 as a side effect of building
5602 can be a list, a file name, or a node.
5603 A side effect is a target file that is created or updated
5604 as a side effect of building other targets.
5605 For example, a Windows PDB
5606 file is created as a side effect of building the .obj
5607 files for a static library,
5608 and various log files are created updated
5609 as side effects of various TeX commands.
5610 If a target is a side effect of multiple build commands,
5612 will ensure that only one set of commands
5613 is executed at a time.
5614 Consequently, you only need to use this method
5615 for side-effect targets that are built as a result of
5616 multiple build commands.
5618 Because multiple build commands may update
5619 the same side effect file,
5624 automatically removed
5630 (Note, however, that the
5632 might be removed as part of
5633 cleaning the directory in which it lives.)
5634 If you want to make sure the
5636 is cleaned whenever a specific
5639 you must specify this explicitly
5646 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
5648 .RI SourceCode( entries ", " builder )
5650 .RI env.SourceCode( entries ", " builder )
5651 Arrange for non-existent source files to
5652 be fetched from a source code management system
5657 may be a Node, string or list of both,
5658 and may represent either individual
5659 source files or directories in which
5660 source files can be found.
5662 For any non-existent source files,
5664 will search up the directory tree
5674 will not use a builder to fetch
5675 source files for the specified
5679 builder has been specified
5680 for a directory higher up the tree.
5684 fetch files from SCCS or RCS subdirectories
5685 without explicit configuration.
5686 This takes some extra processing time
5687 to search for the necessary
5688 source code management files on disk.
5689 You can avoid these extra searches
5690 and speed up your build a little
5691 by disabling these searches as follows:
5694 env.SourceCode('.', None)
5698 Note that if the specified
5700 is one you create by hand,
5701 it must have an associated
5702 construction environment to use
5703 when fetching a source file.
5706 provides a set of canned factory
5707 functions that return appropriate
5708 Builders for various popular
5709 source code management systems.
5710 Canonical examples of invocation include:
5713 env.SourceCode('.', env.BitKeeper('/usr/local/BKsources'))
5714 env.SourceCode('src', env.CVS('/usr/local/CVSROOT'))
5715 env.SourceCode('/', env.RCS())
5716 env.SourceCode(['f1.c', 'f2.c'], env.SCCS())
5717 env.SourceCode('no_source.c', None)
5719 '\"env.SourceCode('.', env.Subversion('file:///usr/local/Subversion'))
5721 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
5723 .RI env.subst( input ", [" raw ", " target ", " source ", " conv ])
5724 Performs construction variable interpolation
5725 on the specified string or sequence argument
5729 leading or trailing white space will
5730 be removed from the result.
5731 and all sequences of white space
5732 will be compressed to a single space character.
5737 character sequences will be stripped from the returned string,
5740 argument may be set to
5742 if you want to preserve white space and
5747 argument may be set to
5749 if you want to strip
5750 all characters between
5756 (as is done for signature calculation).
5758 If the input is a sequence
5760 the individual elements of
5761 the sequence will be expanded,
5762 and the results will be returned as a list.
5769 must be set to lists of
5770 target and source nodes, respectively,
5777 to be available for expansion.
5778 This is usually necessary if you are
5781 from within a Python function used
5784 Returned string values or sequence elements
5785 are converted to their string representation by default.
5789 may specify a conversion function
5790 that will be used in place of
5792 For example, if you want Python objects
5793 (including SCons Nodes)
5794 to be returned as Python objects,
5795 you can use the Python
5797 idiom to pass in an unnamed function
5798 that simply returns its unconverted argument.
5803 print env.subst("The C compiler is: $CC")
5805 def compile(target, source, env):
5806 sourceDir = env.subst("${SOURCE.srcdir}",
5810 source_nodes = env.subst('$EXPAND_TO_NODELIST',
5814 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
5816 '\".RI Subversion( repository ", " module )
5817 '\"A factory function that
5818 '\"returns a Builder object
5819 '\"to be used to fetch source files
5820 '\"from the specified Subversion
5822 '\"The returned Builder
5823 '\"is intended to be passed to the
5827 '\"The optional specified
5829 '\"will be added to the beginning
5830 '\"of all repository path names;
5831 '\"this can be used, in essence,
5832 '\"to strip initial directory names
5833 '\"from the repository path names,
5834 '\"so that you only have to
5835 '\"replicate part of the repository
5836 '\"directory hierarchy in your
5837 '\"local build directory.
5842 '\"# Will fetch foo/bar/src.c
5843 '\"# from /usr/local/Subversion/foo/bar/src.c.
5844 '\"env.SourceCode('.', env.Subversion('file:///usr/local/Subversion'))
5846 '\"# Will fetch bar/src.c
5847 '\"# from /usr/local/Subversion/foo/bar/src.c.
5848 '\"env.SourceCode('.', env.Subversion('file:///usr/local/Subversion', 'foo'))
5850 '\"# Will fetch src.c
5851 '\"# from /usr/local/Subversion/foo/bar/src.c.
5852 '\"env.SourceCode('.', env.Subversion('file:///usr/local/Subversion', 'foo/bar'))
5855 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
5857 .RI SourceSignatures( type )
5859 .RI env.SourceSignatures( type )
5860 Note: Although it is not yet officially deprecated,
5861 use of this function is discouraged.
5864 function for a more flexible and straightforward way
5865 to configure SCons' decision-making.
5868 .BR SourceSignatures ()
5871 how to decide if a source file
5872 (a file that is not built from any other files)
5873 has changed since the last time it
5874 was used to build a particular target file.
5880 If the environment method is used,
5881 the specified type of source signature
5882 is only used when deciding whether targets
5883 built with that environment are up-to-date or must be rebuilt.
5884 If the global function is used,
5885 the specified type of source signature becomes the default
5886 used for all decisions
5887 about whether targets are up-to-date.
5892 decides that a source file has changed
5893 if the MD5 checksum of its contents has changed since
5894 the last time it was used to rebuild a particular target file.
5899 decides that a source file has changed
5900 if its timestamp (modification time) has changed since
5901 the last time it was used to rebuild a particular target file.
5902 (Note that although this is similar to the behavior of Make,
5903 by default it will also rebuild if the dependency is
5905 than the last time it was used to rebuild the target file.)
5907 There is no different between the two behaviors
5913 signatures take longer to compute,
5914 but are more accurate than
5917 The default value is
5920 Note that the default
5921 .BR TargetSignatures ()
5924 .BR SourceSignatures ()
5925 setting for any target files that are used
5926 to build other target files.
5927 Consequently, changing the value of
5928 .BR SourceSignatures ()
5930 affect the up-to-date decision for all files in the build
5931 (or all files built with a specific construction environment
5933 .BR env.SourceSignatures ()
5936 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
5940 .RI env.Split( arg )
5941 Returns a list of file names or other objects.
5943 it will be split on strings of white-space characters
5945 making it easier to write long lists of file names.
5946 If arg is already a list,
5947 the list will be returned untouched.
5948 If arg is any other type of object,
5949 it will be returned as a list
5950 containing just the object.
5955 files = Split("f1.c f2.c f3.c")
5956 files = env.Split("f4.c f5.c f6.c")
5964 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
5966 .RI Tag( node ", " tags )
5967 Annotates file or directory Nodes with
5968 information about how the
5970 Builder should package those files or directories.
5971 All tags are optional.
5976 # makes sure the built library will be installed with 0644 file
5978 Tag( Library( 'lib.c' ), UNIX_ATTR="0644" )
5980 # marks file2.txt to be a documentation file
5981 Tag( 'file2.txt', DOC )
5984 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
5986 .RI TargetSignatures( type )
5988 .RI env.TargetSignatures( type )
5989 Note: Although it is not yet officially deprecated,
5990 use of this function is discouraged.
5993 function for a more flexible and straightforward way
5994 to configure SCons' decision-making.
5997 .BR TargetSignatures ()
6000 how to decide if a target file
6003 built from any other files)
6004 has changed since the last time it
6005 was used to build some other target file.
6015 If the environment method is used,
6016 the specified type of target signature is only used
6017 for targets built with that environment.
6018 If the global function is used,
6019 the specified type of signature becomes the default
6020 used for all target files that
6021 don't have an explicit target signature type
6022 specified for their environments.
6029 decides that a target file has changed
6030 if the MD5 checksum of its contents has changed since
6031 the last time it was used to rebuild some other target file.
6035 MD5 sum the contents
6036 of target files after they're built,
6037 and may decide that it does not need to rebuild
6038 "downstream" target files if a file was
6039 rebuilt with exactly the same contents as the last time.
6044 decides that a target file has changed
6045 if its timestamp (modification time) has changed since
6046 the last time it was used to rebuild some other target file.
6047 (Note that although this is similar to the behavior of Make,
6048 by default it will also rebuild if the dependency is
6050 than the last time it was used to rebuild the target file.)
6055 decides that a target file has changed
6056 as specified by the corresponding
6057 .BR SourceSignatures ()
6064 will treat all input files to a target the same way,
6065 regardless of whether they are source files
6066 or have been built from other files.
6071 decides that a target file has changed
6072 if it has been rebuilt in this invocation
6073 or if its content or timestamp have changed
6074 as specified by the corresponding
6075 .BR SourceSignatures ()
6077 This "propagates" the status of a rebuilt file
6078 so that other "downstream" target files
6079 will always be rebuilt,
6080 even if the contents or the timestamp
6084 signatures are fastest because
6088 signatures take longer to compute,
6089 but are more accurate than
6092 and can prevent unnecessary "downstream" rebuilds
6093 when a target file is rebuilt to the exact same contents
6094 as the previous build.
6097 setting provides the most consistent behavior
6098 when other target files may be rebuilt from
6099 both source and target input files.
6100 The default value is
6103 Because the default setting is
6106 .BR SourceSignatures ()
6107 is generally preferable to
6108 .BR TargetSignatures () ,
6109 so that the up-to-date decision
6110 will be consistent for all files
6111 (or all files built with a specific construction environment).
6113 .BR TargetSignatures ()
6114 provides specific control for how built target files
6115 affect their "downstream" dependencies.
6117 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
6119 .RI Tool( string [, toolpath ", " **kw ])
6120 Returns a callable object
6121 that can be used to initialize
6122 a construction environment using the
6123 tools keyword of the Environment() method.
6124 The object may be called with a construction
6125 environment as an argument,
6126 in which case the object will
6127 add the necessary variables
6128 to the construction environment
6129 and the name of the tool will be added to the
6131 construction variable.
6133 Additional keyword arguments are passed to the tool's
6140 env = Environment(tools = [ Tool('msvc') ])
6144 t(env) # adds 'msvc' to the TOOLS variable
6145 u = Tool('opengl', toolpath = ['tools'])
6146 u(env) # adds 'opengl' to the TOOLS variable
6149 .RI env.Tool( string [, toolpath ", " **kw ])
6150 Applies the callable object for the specified tool
6152 to the environment through which the method was called.
6154 Additional keyword arguments are passed to the tool's
6160 env.Tool('opengl', toolpath = ['build/tools'])
6163 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
6165 .RI Value( value ", [" built_value ])
6167 .RI env.Value( value ", [" built_value ])
6168 Returns a Node object representing the specified Python value. Value
6169 Nodes can be used as dependencies of targets. If the result of
6172 changes between SCons runs, any targets depending on
6175 (This is true even when using timestamps to decide if
6176 files are up-to-date.)
6177 When using timestamp source signatures, Value Nodes'
6178 timestamps are equal to the system time when the Node is created.
6180 The returned Value Node object has a
6182 method that can be used to "build" a Value Node
6183 by setting a new value.
6186 argument can be specified
6187 when the Value Node is created
6188 to indicate the Node should already be considered
6190 There is a corresponding
6192 method that will return the built value of the Node.
6199 def create(target, source, env):
6200 # A function that will write a 'prefix=$SOURCE'
6201 # string into the file name specified as the
6203 f = open(str(target[0]), 'wb')
6204 f.write('prefix=' + source[0].get_contents())
6206 # Fetch the prefix= argument, if any, from the command
6207 # line, and use /usr/local as the default.
6208 prefix = ARGUMENTS.get('prefix', '/usr/local')
6210 # Attach a .Config() builder for the above function action
6211 # to the construction environment.
6212 env['BUILDERS']['Config'] = Builder(action = create)
6213 env.Config(target = 'package-config', source = Value(prefix))
6215 def build_value(target, source, env):
6216 # A function that "builds" a Python Value by updating
6217 # the the Python value with the contents of the file
6218 # specified as the source of the Builder call ($SOURCE).
6219 target[0].write(source[0].get_contents())
6221 output = env.Value('before')
6222 input = env.Value('after')
6224 # Attach a .UpdateValue() builder for the above function
6225 # action to the construction environment.
6226 env['BUILDERS']['UpdateValue'] = Builder(action = build_value)
6227 env.UpdateValue(target = Value(output), source = Value(input))
6230 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
6232 .RI VariantDir( variant_dir ", " src_dir ", [" duplicate ])
6234 .RI env.VariantDir( variant_dir ", " src_dir ", [" duplicate ])
6237 function to create a copy of your sources in another location:
6240 is not found but exists under
6242 the file or directory is copied to
6244 Target files can be built in a different directory
6245 than the original sources by simply refering to the sources (and targets)
6246 within the variant tree.
6249 can be called multiple times with the same
6251 to set up multiple builds with different options
6255 location must be in or underneath the SConstruct file's directory, and
6257 may not be underneath
6259 '\"TODO: Can the above restrictions be clarified or relaxed?
6260 '\"TODO: The latter restriction is clearly not completely right;
6261 '\"TODO: src_dir = '.' works fine with a build dir under it.
6263 The default behavior is for
6265 to physically duplicate the source files in the variant tree.
6266 Thus, a build performed in the variant tree is guaranteed to be identical
6267 to a build performed in the source tree even if
6268 intermediate source files are generated during the build,
6269 or preprocessors or other scanners search for included files
6270 relative to the source file,
6271 or individual compilers or other invoked tools are hard-coded
6272 to put derived files in the same directory as source files.
6274 If possible on the platform,
6275 the duplication is performed by linking rather than copying;
6278 command-line option.
6279 Moreover, only the files needed for the build are duplicated;
6280 files and directories that are not used are not present in
6283 Duplicating the source tree may be disabled by setting the
6285 argument to 0 (zero).
6288 to invoke Builders using the path names of source files in
6290 and the path names of derived files within
6292 This is always more efficient than
6294 and is usually safe for most builds
6295 (but see above for cases that may cause problems).
6299 works most naturally with a subsidiary SConscript file.
6300 However, you would then call the subsidiary SConscript file
6301 not in the source directory, but in the
6303 regardless of the value of
6305 This is how you tell
6307 which variant of a source tree to build:
6310 # run src/SConscript in two variant directories
6311 VariantDir('build/variant1', 'src')
6312 SConscript('build/variant1/SConscript')
6313 VariantDir('build/variant2', 'src')
6314 SConscript('build/variant2/SConscript')
6320 function, described above,
6321 for another way to specify a variant directory
6322 in conjunction with calling a subsidiary SConscript file.
6327 # use names in the build directory, not the source directory
6328 VariantDir('build', 'src', duplicate=0)
6329 Program('build/prog', 'build/source.c')
6333 # this builds both the source and docs in a separate subtree
6334 VariantDir('build', '.', duplicate=0)
6335 SConscript(dirs=['build/src','build/doc'])
6339 # same as previous example, but only uses SConscript
6340 SConscript(dirs='src', variant_dir='build/src', duplicate=0)
6341 SConscript(dirs='doc', variant_dir='build/doc', duplicate=0)
6344 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
6346 .RI WhereIs( program ", [" path ", " pathext ", " reject ])
6348 .RI env.WhereIs( program ", [" path ", " pathext ", " reject ])
6350 Searches for the specified executable
6352 returning the full path name to the program
6354 and returning None if not.
6355 Searches the specified
6357 the value of the calling environment's PATH
6358 (env['ENV']['PATH']),
6359 or the user's current external PATH
6360 (os.environ['PATH'])
6362 On Windows systems, searches for executable
6363 programs with any of the file extensions
6364 listed in the specified
6366 the calling environment's PATHEXT
6367 (env['ENV']['PATHEXT'])
6368 or the user's current PATHEXT
6369 (os.environ['PATHEXT'])
6377 .SS SConscript Variables
6378 In addition to the global functions and methods,
6380 supports a number of Python variables
6381 that can be used in SConscript files
6382 to affect how you want the build to be performed.
6383 These variables may be accessed from custom Python modules that you
6384 import into an SConscript file by adding the following
6385 to the Python module:
6388 from SCons.Script import *
6391 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
6396 arguments specified on the command line.
6397 Each element in the list is a tuple
6399 .RI ( keyword , value )
6405 elements of the tuple
6407 subscripting for element
6411 of the tuple, respectively.
6416 print "first keyword, value =", ARGLIST[0][0], ARGLIST[0][1]
6417 print "second keyword, value =", ARGLIST[1][0], ARGLIST[1][1]
6418 third_tuple = ARGLIST[2]
6419 print "third keyword, value =", third_tuple[0], third_tuple[1]
6420 for key, value in ARGLIST:
6421 # process key and value
6424 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
6427 A dictionary of all the
6429 arguments specified on the command line.
6430 The dictionary is not in order,
6431 and if a given keyword has
6432 more than one value assigned to it
6433 on the command line,
6434 the last (right-most) value is
6442 if ARGUMENTS.get('debug', 0):
6443 env = Environment(CCFLAGS = '-g')
6448 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
6451 A list of the targets which
6453 will actually try to build,
6454 regardless of whether they were specified on
6455 the command line or via the
6458 The elements of this list may be strings
6460 nodes, so you should run the list through the Python
6462 function to make sure any Node path names
6463 are converted to strings.
6465 Because this list may be taken from the
6466 list of targets specified using the
6469 the contents of the list may change
6470 on each successive call to
6475 for additional information.
6480 if 'foo' in BUILD_TARGETS:
6481 print "Don't forget to test the `foo' program!"
6482 if 'special/program' in BUILD_TARGETS:
6483 SConscript('special')
6488 list only contains targets expected listed
6489 on the command line or via calls to the
6494 contain all dependent targets that will be built as
6495 a result of making the sure the explicitly-specified
6496 targets are up to date.
6498 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
6500 COMMAND_LINE_TARGETS
6501 A list of the targets explicitly specified on
6503 If there are no targets specified on the command line,
6505 This can be used, for example,
6506 to take specific actions only
6507 when a certain target or targets
6508 is explicitly being built.
6513 if 'foo' in COMMAND_LINE_TARGETS:
6514 print "Don't forget to test the `foo' program!"
6515 if 'special/program' in COMMAND_LINE_TARGETS:
6516 SConscript('special')
6519 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
6522 A list of the target
6524 that have been specified using the
6527 The elements of the list are nodes,
6528 so you need to run them through the Python
6530 function to get at the path name for each Node.
6535 print str(DEFAULT_TARGETS[0])
6536 if 'foo' in map(str, DEFAULT_TARGETS):
6537 print "Don't forget to test the `foo' program!"
6542 list change on on each successive call to the
6547 print map(str, DEFAULT_TARGETS) # originally []
6549 print map(str, DEFAULT_TARGETS) # now a node ['foo']
6551 print map(str, DEFAULT_TARGETS) # now a node ['foo', 'bar']
6553 print map(str, DEFAULT_TARGETS) # back to []
6556 Consequently, be sure to use
6558 only after you've made all of your
6561 or else simply be careful of the order
6562 of these statements in your SConscript files
6563 so that you don't look for a specific
6564 default target before it's actually been added to the list.
6566 .SS Construction Variables
6567 .\" XXX From Gary Ruben, 23 April 2002:
6568 .\" I think it would be good to have an example with each construction
6569 .\" variable description in the documentation.
6571 .\" CC The C compiler
6572 .\" Example: env["CC"] = "c68x"
6573 .\" Default: env["CC"] = "cc"
6575 .\" CCCOM The command line ...
6577 .\" To generate the compiler line c68x -ps -qq -mr -o $TARGET $SOURCES
6578 .\" env["CC"] = "c68x"
6579 .\" env["CFLAGS"] = "-ps -qq -mr"
6580 .\" env["CCCOM"] = "$CC $CFLAGS -o $TARGET $SOURCES
6582 .\" (I dunno what this is ;-)
6583 A construction environment has an associated dictionary of
6584 .I construction variables
6585 that are used by built-in or user-supplied build rules.
6586 Construction variables must follow the same rules for
6588 the initial character must be an underscore or letter,
6589 followed by any number of underscores, letters, or digits.
6591 A number of useful construction variables are automatically defined by
6592 scons for each supported platform, and additional construction variables
6593 can be defined by the user. The following is a list of the automatically
6594 defined construction variables:
6596 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
6597 '\" BEGIN GENERATED CONSTRUCTION VARIABLE DESCRIPTIONS
6599 '\" The descriptions below of the various SCons construction variables
6600 '\" are generated from the .xml files that live next to the various
6601 '\" Python modules in the build enginer library. If you're reading
6602 '\" this [gnt]roff file with an eye towards patching this man page,
6603 '\" you can still submit a diff against this text, but it will have to
6604 '\" be translated to a diff against the underlying .xml file before the
6605 '\" patch is actually accepted. If you do that yourself, it will make
6606 '\" it easier to integrate the patch.
6608 '\" BEGIN GENERATED CONSTRUCTION VARIABLE DESCRIPTIONS
6609 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
6611 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
6612 '\" END GENERATED CONSTRUCTION VARIABLE DESCRIPTIONS
6614 '\" The descriptions above of the various SCons construction variables
6615 '\" are generated from the .xml files that live next to the various
6616 '\" Python modules in the build enginer library. If you're reading
6617 '\" this [gnt]roff file with an eye towards patching this man page,
6618 '\" you can still submit a diff against this text, but it will have to
6619 '\" be translated to a diff against the underlying .xml file before the
6620 '\" patch is actually accepted. If you do that yourself, it will make
6621 '\" it easier to integrate the patch.
6623 '\" END GENERATED CONSTRUCTION VARIABLE DESCRIPTIONS
6624 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
6627 Construction variables can be retrieved and set using the
6629 method of the construction environment:
6632 dict = env.Dictionary()
6636 or using the [] operator:
6642 Construction variables can also be passed to the construction environment
6646 env = Environment(CC="cc")
6649 or when copying a construction environment using the
6654 env2 = env.Clone(CC="cl.exe")
6657 .SS Configure Contexts
6661 .I configure contexts,
6662 an integrated mechanism similar to the
6663 various AC_CHECK macros in GNU autoconf
6664 for testing for the existence of C header
6665 files, libraries, etc.
6666 In contrast to autoconf,
6668 does not maintain an explicit cache of the tested values,
6669 but uses its normal dependency tracking to keep the checked values
6670 up to date. However, users may override this behaviour with the
6672 command line option.
6674 The following methods can be used to perform checks:
6677 .RI Configure( env ", [" custom_tests ", " conf_dir ", " log_file ", " config_h ", " clean ", " help])
6679 .RI env.Configure([ custom_tests ", " conf_dir ", " log_file ", " config_h ", " clean ", " help])
6680 This creates a configure context, which can be used to perform checks.
6682 specifies the environment for building the tests.
6683 This environment may be modified when performing checks.
6685 is a dictionary containing custom tests.
6686 See also the section about custom tests below.
6687 By default, no custom tests are added to the configure context.
6689 specifies a directory where the test cases are built.
6690 Note that this directory is not used for building
6692 The default value is the directory
6695 specifies a file which collects the output from commands
6696 that are executed to check for the existence of header files, libraries, etc.
6697 The default is the file #/config.log.
6698 If you are using the
6701 you may want to specify a subdirectory under your variant directory.
6703 specifies a C header file where the results of tests
6704 will be written, e.g. #define HAVE_STDIO_H, #define HAVE_LIBM, etc.
6705 The default is to not write a
6708 You can specify the same
6710 file in multiple calls to Configure,
6713 will concatenate all results in the specified file.
6715 uses its normal dependency checking
6716 to decide if it's necessary to rebuild
6720 This means that the file is not necessarily re-built each
6722 but is only rebuilt if its contents will have changed
6723 and some target that depends on the
6725 file is being built.
6731 arguments can be used to suppress execution of the configuration
6736 options are used, respectively.
6737 The default behavior is always to execute
6738 configure context tests,
6739 since the results of the tests may
6740 affect the list of targets to be cleaned
6742 If the configure tests do not affect these,
6743 then you may add the
6749 to avoid unnecessary test execution.
6754 instance has the following associated methods:
6757 .RI SConf.Finish( context )
6760 This method should be called after configuration is done.
6761 It returns the environment as modified
6762 by the configuration checks performed.
6763 After this method is called, no further checks can be performed
6764 with this configuration context.
6765 However, you can create a new
6767 context to perform additional checks.
6768 Only one context should be active at a time.
6770 The following Checks are predefined.
6771 (This list will likely grow larger as time
6772 goes by and developers contribute new useful tests.)
6775 .RI SConf.CheckHeader( context ", " header ", [" include_quotes ", " language ])
6777 .IR sconf .CheckHeader( header ", [" include_quotes ", " language ])
6780 is usable in the specified language.
6783 in which case the last item in the list
6784 is the header file to be checked,
6785 and the previous list items are
6788 lines should precede the
6789 header line being checked for.
6790 The optional argument
6793 a two character string, where the first character denotes the opening
6794 quote and the second character denotes the closing quote.
6795 By default, both characters are " (double quote).
6796 The optional argument
6802 and selects the compiler to be used for the check.
6803 Returns 1 on success and 0 on failure.
6806 .RI SConf.CheckCHeader( context ", " header ", [" include_quotes ])
6808 .IR sconf .CheckCHeader( header ", [" include_quotes ])
6809 This is a wrapper around
6810 .B SConf.CheckHeader
6813 is usable in the C language.
6816 in which case the last item in the list
6817 is the header file to be checked,
6818 and the previous list items are
6821 lines should precede the
6822 header line being checked for.
6823 The optional argument
6826 a two character string, where the first character denotes the opening
6827 quote and the second character denotes the closing quote (both default
6829 Returns 1 on success and 0 on failure.
6832 .RI SConf.CheckCXXHeader( context ", " header ", [" include_quotes ])
6834 .IR sconf .CheckCXXHeader( header ", [" include_quotes ])
6835 This is a wrapper around
6836 .B SConf.CheckHeader
6839 is usable in the C++ language.
6842 in which case the last item in the list
6843 is the header file to be checked,
6844 and the previous list items are
6847 lines should precede the
6848 header line being checked for.
6849 The optional argument
6852 a two character string, where the first character denotes the opening
6853 quote and the second character denotes the closing quote (both default
6855 Returns 1 on success and 0 on failure.
6858 .RI SConf.CheckFunc( context, ", " function_name ", [" header ", " language ])
6860 .IR sconf .CheckFunc( function_name ", [" header ", " language ])
6861 Checks if the specified
6862 C or C++ function is available.
6864 is the name of the function to check for.
6867 argument is a string
6871 that will be compiled
6872 to check if the function exists;
6878 char function_name();
6886 and selects the compiler to be used for the check;
6890 .RI SConf.CheckLib( context ", [" library ", " symbol ", " header ", " language ", " autoadd=1 ])
6892 .IR sconf .CheckLib([ library ", " symbol ", " header ", " language ", " autoadd=1 ])
6899 is 1 and the library provides the specified
6901 appends the library to the LIBS construction environment variable.
6903 may also be None (the default),
6906 is checked with the current LIBS variable,
6907 or a list of library names,
6908 in which case each library in the list
6916 .BR SConf.CheckLib ()
6918 you can link against the specified
6926 and selects the compiler to be used for the check;
6928 The default value for
6931 This method returns 1 on success and 0 on error.
6934 .RI SConf.CheckLibWithHeader( context ", " library ", " header ", " language ", [" call ", " autoadd ])
6936 .IR sconf .CheckLibWithHeader( library ", " header ", " language ", [" call ", " autoadd ])
6940 call, this call provides a more sophisticated way to check against libraries.
6943 specifies the library or a list of libraries to check.
6945 specifies a header to check for.
6948 in which case the last item in the list
6949 is the header file to be checked,
6950 and the previous list items are
6953 lines should precede the
6954 header line being checked for.
6956 may be one of 'C','c','CXX','cxx','C++' and 'c++'.
6958 can be any valid expression (with a trailing ';').
6962 the default simply checks that you
6963 can link against the specified
6966 specifies whether to add the library to the environment (only if the check
6967 succeeds). This method returns 1 on success and 0 on error.
6970 .RI SConf.CheckType( context ", " type_name ", [" includes ", " language ])
6972 .IR sconf .CheckType( type_name ", [" includes ", " language ])
6973 Checks for the existence of a type defined by
6976 specifies the typedef name to check for.
6978 is a string containing one or more
6980 lines that will be inserted into the program
6981 that will be run to test for the existence of the type.
6988 and selects the compiler to be used for the check;
6992 sconf.CheckType('foo_type', '#include "my_types.h"', 'C++')
6996 .RI Configure.CheckCC( self )
6997 Checks whether the C compiler (as defined by the CC construction variable) works
6998 by trying to compile a small source file.
7000 By default, SCons only detects if there is a program with the correct name, not
7001 if it is a functioning compiler.
7003 This uses the exact same command than the one used by the object builder for C
7004 source file, so it can be used to detect if a particular compiler flag works or
7008 .RI Configure.CheckCXX( self )
7009 Checks whether the C++ compiler (as defined by the CXX construction variable)
7010 works by trying to compile a small source file. By default, SCons only detects
7011 if there is a program with the correct name, not if it is a functioning compiler.
7013 This uses the exact same command than the one used by the object builder for
7014 CXX source files, so it can be used to detect if a particular compiler flag
7018 .RI Configure.CheckSHCC( self )
7019 Checks whether the C compiler (as defined by the SHCC construction variable) works
7020 by trying to compile a small source file. By default, SCons only detects if
7021 there is a program with the correct name, not if it is a functioning compiler.
7023 This uses the exact same command than the one used by the object builder for C
7024 source file, so it can be used to detect if a particular compiler flag works or
7025 not. This does not check whether the object code can be used to build a shared
7026 library, only that the compilation (not link) succeeds.
7029 .RI Configure.CheckSHCXX( self )
7030 Checks whether the C++ compiler (as defined by the SHCXX construction variable)
7031 works by trying to compile a small source file. By default, SCons only detects
7032 if there is a program with the correct name, not if it is a functioning compiler.
7034 This uses the exact same command than the one used by the object builder for
7035 CXX source files, so it can be used to detect if a particular compiler flag
7036 works or not. This does not check whether the object code can be used to build
7037 a shared library, only that the compilation (not link) succeeds.
7040 Example of a typical Configure usage:
7044 conf = Configure( env )
7045 if not conf.CheckCHeader( 'math.h' ):
7046 print 'We really need math.h!'
7048 if conf.CheckLibWithHeader( 'qt', 'qapp.h', 'c++',
7049 'QApplication qapp(0,0);' ):
7050 # do stuff for qt - usage, e.g.
7051 conf.env.Append( CPPFLAGS = '-DWITH_QT' )
7056 .RI SConf.CheckTypeSize( context ", " type_name ", [" header ", " language ", " expect ])
7058 .IR sconf .CheckTypeSize( type_name ", [" header ", " language ", " expect ])
7059 Checks for the size of a type defined by
7062 specifies the typedef name to check for.
7065 argument is a string
7069 that will be compiled
7070 to check if the function exists;
7071 the default is empty.
7078 and selects the compiler to be used for the check;
7082 argument should be an integer.
7083 If this argument is used,
7084 the function will only check whether the type
7085 given in type_name has the expected size (in bytes).
7087 .B "CheckTypeSize('short', expect = 2)"
7088 will return success only if short is two bytes.
7094 .RI SConf.CheckDeclaration( context ", " symbol ", [" includes ", " language ])
7096 .IR sconf .CheckDeclaration( symbol ", [" includes ", " language ])
7097 Checks if the specified
7101 is a string containing one or more
7103 lines that will be inserted into the program
7104 that will be run to test for the existence of the type.
7111 and selects the compiler to be used for the check;
7115 .RI SConf.Define( context ", " symbol ", [" value ", " comment ])
7117 .IR sconf .Define( symbol ", [" value ", " comment ])
7118 This function does not check for anything, but defines a
7119 preprocessor symbol that will be added to the configuration header file.
7120 It is the equivalent of AC_DEFINE,
7121 and defines the symbol
7125 and the optional comment
7133 conf = Configure( env )
7135 # Puts the following line in the config header file:
7137 conf.Define('A_SYMBOL')
7139 # Puts the following line in the config header file:
7140 # #define A_SYMBOL 1
7141 conf.Define('A_SYMBOL', 1)
7145 Be careful about quoting string values, though:
7149 conf = Configure( env )
7151 # Puts the following line in the config header file:
7152 # #define A_SYMBOL YA
7153 conf.Define('A_SYMBOL', "YA")
7155 # Puts the following line in the config header file:
7156 # #define A_SYMBOL "YA"
7157 conf.Define('A_SYMBOL', '"YA"')
7165 conf = Configure( env )
7167 # Puts the following lines in the config header file:
7168 # /* Set to 1 if you have a symbol */
7169 # #define A_SYMBOL 1
7170 conf.Define('A_SYMBOL', 1, 'Set to 1 if you have a symbol')
7174 You can define your own custom checks.
7175 in addition to the predefined checks.
7176 These are passed in a dictionary to the Configure function.
7177 This dictionary maps the names of the checks
7178 to user defined Python callables
7179 (either Python functions or class instances implementing the
7182 The first argument of the call is always a
7184 instance followed by the arguments,
7185 which must be supplied by the user of the check.
7186 These CheckContext instances define the following methods:
7189 .RI CheckContext.Message( self ", " text )
7191 Usually called before the check is started.
7193 will be displayed to the user, e.g. 'Checking for library X...'
7196 .RI CheckContext.Result( self, ", " res )
7198 Usually called after the check is done.
7200 can be either an integer or a string. In the former case, 'yes' (res != 0)
7201 or 'no' (res == 0) is displayed to the user, in the latter case the
7202 given string is displayed.
7205 .RI CheckContext.TryCompile( self ", " text ", " extension )
7206 Checks if a file with the specified
7208 (e.g. '.c') containing
7210 can be compiled using the environment's
7212 builder. Returns 1 on success and 0 on failure.
7215 .RI CheckContext.TryLink( self ", " text ", " extension )
7216 Checks, if a file with the specified
7218 (e.g. '.c') containing
7220 can be compiled using the environment's
7222 builder. Returns 1 on success and 0 on failure.
7225 .RI CheckContext.TryRun( self ", " text ", " extension )
7226 Checks, if a file with the specified
7228 (e.g. '.c') containing
7230 can be compiled using the environment's
7232 builder. On success, the program is run. If the program
7233 executes successfully
7234 (that is, its return status is 0),
7239 is the standard output of the
7241 If the program fails execution
7242 (its return status is non-zero),
7243 then (0, '') is returned.
7246 .RI CheckContext.TryAction( self ", " action ", [" text ", " extension ])
7247 Checks if the specified
7249 with an optional source file (contents
7256 may be anything which can be converted to a
7263 is the content of the target file.
7269 .RI CheckContext.TryBuild( self ", " builder ", [" text ", " extension ])
7270 Low level implementation for testing specific builds;
7271 the methods above are based on this method.
7272 Given the Builder instance
7276 of a source file with optional
7278 this method returns 1 on success and 0 on failure. In addition,
7280 is set to the build target node, if the build was successful.
7283 Example for implementing and using custom tests:
7286 def CheckQt(context, qtdir):
7287 context.Message( 'Checking for qt ...' )
7288 lastLIBS = context.env['LIBS']
7289 lastLIBPATH = context.env['LIBPATH']
7290 lastCPPPATH= context.env['CPPPATH']
7291 context.env.Append(LIBS = 'qt', LIBPATH = qtdir + '/lib', CPPPATH = qtdir + '/include' )
7292 ret = context.TryLink("""
7294 int main(int argc, char **argv) {
7295 QApplication qapp(argc, argv);
7300 context.env.Replace(LIBS = lastLIBS, LIBPATH=lastLIBPATH, CPPPATH=lastCPPPATH)
7301 context.Result( ret )
7305 conf = Configure( env, custom_tests = { 'CheckQt' : CheckQt } )
7306 if not conf.CheckQt('/usr/lib/qt'):
7307 print 'We really need qt!'
7312 .SS Command-Line Construction Variables
7314 Often when building software,
7315 some variables must be specified at build time.
7316 For example, libraries needed for the build may be in non-standard
7317 locations, or site-specific compiler options may need to be passed to the
7322 object to support overriding construction variables
7323 on the command line:
7325 $ scons VARIABLE=foo
7327 The variable values can also be specified in a text-based SConscript file.
7328 To create a Variables object, call the Variables() function:
7331 .RI Variables([ files "], [" args ])
7332 This creates a Variables object that will read construction variables from
7333 the file or list of filenames specified in
7335 If no files are specified,
7340 then no files will be read.
7341 The optional argument
7344 values that will override anything read from the specified files;
7345 it is primarily intended to be passed the
7347 dictionary that holds variables
7348 specified on the command line.
7352 vars = Variables('custom.py')
7353 vars = Variables('overrides.py', ARGUMENTS)
7354 vars = Variables(None, {FOO:'expansion', BAR:7})
7357 Variables objects have the following methods:
7360 .RI Add( key ", [" help ", " default ", " validator ", " converter ])
7361 This adds a customizable construction variable to the Variables object.
7363 is the name of the variable.
7365 is the help text for the variable.
7367 is the default value of the variable;
7368 if the default value is
7370 and there is no explicit value specified,
7371 the construction variable will
7373 be added to the construction environment.
7375 is called to validate the value of the variable, and should take three
7376 arguments: key, value, and environment.
7377 The recommended way to handle an invalid value is
7378 to raise an exception (see example below).
7380 is called to convert the value before putting it in the environment, and
7381 should take either a value, or the value and environment, as parameters.
7384 must return a value,
7385 which will be converted into a string
7386 before being validated by the
7389 and then added to the environment.
7394 vars.Add('CC', 'The C compiler')
7396 def validate_color(key, val, env):
7397 if not val in ['red', 'blue', 'yellow']:
7398 raise "Invalid color value '%s'" % val
7399 vars.Add('COLOR', validator=valid_color)
7403 .RI AddVariables( list )
7404 A wrapper script that adds
7405 multiple customizable construction variables
7406 to a Variables object.
7408 is a list of tuple or list objects
7409 that contain the arguments
7410 for an individual call to the
7417 ('CC', 'The C compiler'),
7418 ('VALIDATE', 'An option for testing validation',
7419 'notset', validator, None),
7424 .RI Update( env ", [" args ])
7425 This updates a construction environment
7427 with the customized construction variables.
7428 Any specified variables that are
7430 configured for the Variables object
7431 will be saved and may be
7433 .BR UnknownVariables ()
7436 Normally this method is not called directly,
7437 but is called indirectly by passing the Variables object to
7438 the Environment() function:
7441 env = Environment(variables=vars)
7445 The text file(s) that were specified
7446 when the Variables object was created
7447 are executed as Python scripts,
7448 and the values of (global) Python variables set in the file
7449 are added to the construction environment.
7458 .RI UnknownVariables( )
7459 Returns a dictionary containing any
7460 variables that were specified
7461 either in the files or the dictionary
7462 with which the Variables object was initialized,
7463 but for which the Variables object was
7467 env = Environment(variables=vars)
7468 for key, value in vars.UnknownVariables():
7469 print "unknown variable: %s=%s" % (key, value)
7473 .RI Save( filename ", " env )
7474 This saves the currently set variables into a script file named
7476 that can be used on the next invocation to automatically load the current
7477 settings. This method combined with the Variables method can be used to
7478 support caching of variables between runs.
7482 vars = Variables(['variables.cache', 'custom.py'])
7485 vars.Save('variables.cache', env)
7489 .RI GenerateHelpText( env ", [" sort ])
7490 This generates help text documenting the customizable construction
7491 variables suitable to passing in to the Help() function.
7493 is the construction environment that will be used to get the actual values
7494 of customizable variables. Calling with
7498 will cause the output to be sorted
7499 by the specified argument.
7503 should take two arguments
7506 (like the standard Python
7511 Help(vars.GenerateHelpText(env))
7512 Help(vars.GenerateHelpText(env, sort=cmp))
7516 .RI FormatVariableHelpText( env ", " opt ", " help ", " default ", " actual )
7517 This method returns a formatted string
7518 containing the printable help text
7520 It is normally not called directly,
7521 but is called by the
7522 .IR GenerateHelpText ()
7523 method to create the returned help text.
7524 It may be overridden with your own
7525 function that takes the arguments specified above
7526 and returns a string of help text formatted to your liking.
7528 .IR GenerateHelpText ()
7529 will not put any blank lines or extra
7530 characters in between the entries,
7531 so you must add those characters to the returned
7532 string if you want the entries separated.
7535 def my_format(env, opt, help, default, actual):
7536 fmt = "\n%s: default=%s actual=%s (%s)\n"
7537 return fmt % (opt, default. actual, help)
7538 vars.FormatVariableHelpText = my_format
7541 To make it more convenient to work with customizable Variables,
7543 provides a number of functions
7544 that make it easy to set up
7545 various types of Variables:
7548 .RI BoolVariable( key ", " help ", " default )
7549 Return a tuple of arguments
7550 to set up a Boolean option.
7554 have a default value of
7556 and display the specified
7559 The option will interpret the values
7581 .RI EnumVariable( key ", " help ", " default ", " allowed_values ", [" map ", " ignorecase ])
7582 Return a tuple of arguments
7584 whose value may be one
7585 of a specified list of legal enumerated values.
7589 have a default value of
7591 and display the specified
7594 The option will only support those
7600 argument is a dictionary
7601 that can be used to convert
7602 input values into specific legal values
7611 then the values are case-sensitive.
7616 then values will be matched
7622 then values will be matched
7624 and all input values will be
7625 converted to lower case.
7628 .RI ListVariable( key ", " help ", " default ", " names ", [", map ])
7629 Return a tuple of arguments
7631 whose value may be one or more
7632 of a specified list of legal enumerated values.
7636 have a default value of
7638 and display the specified
7641 The option will only support the values
7644 or the values in the
7647 More than one value may be specified,
7648 with all values separated by commas.
7649 The default may be a string of
7650 comma-separated default values,
7651 or a list of the default values.
7654 argument is a dictionary
7655 that can be used to convert
7656 input values into specific legal values
7662 .RI PackageVariable( key ", " help ", " default )
7663 Return a tuple of arguments
7665 whose value is a path name
7666 of a package that may be
7667 enabled, disabled or
7668 given an explicit path name.
7672 have a default value of
7674 and display the specified
7677 The option will support the values
7684 in which case the specified
7687 or the option may be set to an
7689 (typically the path name to a package
7690 that is being enabled).
7691 The option will also support the values
7697 to disable use of the specified option.
7700 .RI PathVariable( key ", " help ", " default ", [" validator ])
7701 Return a tuple of arguments
7703 whose value is expected to be a path name.
7707 have a default value of
7709 and display the specified
7715 that will be called to
7716 verify that the specified path
7719 following ready-made validators:
7720 .BR PathVariable.PathExists
7722 which verifies that the specified path exists;
7723 .BR PathVariable.PathIsFile ,
7724 which verifies that the specified path is an existing file;
7725 .BR PathVariable.PathIsDir ,
7726 which verifies that the specified path is an existing directory;
7727 .BR PathVariable.PathIsDirCreate ,
7728 which verifies that the specified path is a directory
7729 and will create the specified directory if the path does not exist;
7731 .BR PathVariable.PathAccept ,
7732 which simply accepts the specific path name argument without validation,
7733 and which is suitable if you want your users
7734 to be able to specify a directory path that will be
7735 created as part of the build process, for example.
7736 You may supply your own
7739 which must take three arguments
7741 the name of the variable to be set;
7743 the specified value being checked;
7746 the construction environment)
7747 and should raise an exception
7748 if the specified value is not acceptable.
7751 These functions make it
7752 convenient to create a number
7753 of variables with consistent behavior
7754 in a single call to the
7760 BoolVariable('warnings', 'compilation with -Wall and similiar', 1),
7761 EnumVariable('debug', 'debug output and symbols', 'no'
7762 allowed_values=('yes', 'no', 'full'),
7763 map={}, ignorecase=0), # case sensitive
7764 ListVariable('shared',
7765 'libraries to build as shared libraries',
7767 names = list_of_libs),
7768 PackageVariable('x11',
7769 'use X11 installed here (yes = search some places)',
7771 PathVariable('qtdir', 'where the root of Qt is installed', qtdir),
7772 PathVariable('foopath', 'where the foo library is installed', foopath,
7773 PathVariable.PathIsDir),
7778 .SS File and Directory Nodes
7788 Nodes, respectively.
7789 python objects, respectively.
7790 Those objects have several user-visible attributes
7791 and methods that are often useful:
7797 This path is relative to the top-level directory
7801 The build path is the same as the source path if
7806 The absolute build path of the given file or directory.
7816 object representing the
7825 # Get the current build dir's path, relative to top.
7827 # Current dir's absolute path
7829 # Next line is always '.', because it is the top dir's path relative to itself.
7831 File('foo.c').srcnode().path # source path of the given source file.
7833 # Builders also return File objects:
7834 foo = env.Program('foo.c')
7835 print "foo will be built in %s"%foo.path
7842 Node can also be used to create
7843 file and subdirectory Nodes relative to the generating Node.
7846 Node will place the new Nodes within the directory it represents.
7849 node will place the new Nodes within its parent directory
7850 (that is, "beside" the file in question).
7855 (directory) Node and
7860 then these methods are available:
7864 Returns a directory Node for a subdirectory of
7871 Returns a file Node for a file within
7877 .IR d .Entry( name )
7878 Returns an unresolved Node within
7885 Returns a directory named
7887 within the parent directory of
7892 Returns a file named
7894 within the parent directory of
7898 .IR f .Entry( name )
7899 Returns an unresolved Node named
7901 within the parent directory of
7908 # Get a Node for a file within a directory
7909 incl = Dir('include')
7910 f = incl.File('header.h')
7912 # Get a Node for a subdirectory within a directory
7913 dist = Dir('project-3.2.1)
7914 src = dist.Dir('src')
7916 # Get a Node for a file in the same directory
7917 cfile = File('sample.c')
7918 hfile = cfile.File('sample.h')
7922 html = docs.Dir('html')
7923 index = html.File('index.html')
7924 css = index.File('app.css')
7930 can be extended to build different types of targets
7931 by adding new Builder objects
7932 to a construction environment.
7934 you should only need to add a new Builder object
7935 when you want to build a new type of file or other external target.
7936 If you just want to invoke a different compiler or other tool
7937 to build a Program, Object, Library, or any other
7938 type of output file for which
7940 already has an existing Builder,
7941 it is generally much easier to
7942 use those existing Builders
7943 in a construction environment
7944 that sets the appropriate construction variables
7947 Builder objects are created
7953 function accepts the following arguments:
7956 The command line string used to build the target from the source.
7959 a list of strings representing the command
7960 to be executed and its arguments
7961 (suitable for enclosing white space in an argument),
7963 mapping source file name suffixes to
7964 any combination of command line strings
7965 (if the builder should accept multiple source file extensions),
7968 (see the next section);
7969 or a list of any of the above.
7972 takes three arguments:
7974 - a list of source nodes,
7976 - a list of target nodes,
7978 - the construction environment.
7981 The prefix that will be prepended to the target file name.
7982 This may be specified as a:
7992 - a function or other callable that takes
7993 two arguments (a construction environment and a list of sources)
7994 and returns a prefix,
7999 - specifies a mapping from a specific source suffix (of the first
8000 source specified) to a corresponding target prefix. Both the source
8001 suffix and target prefix specifications may use environment variable
8002 substitution, and the target prefix (the 'value' entries in the
8003 dictionary) may also be a callable object. The default target prefix
8004 may be indicated by a dictionary entry with a key value of None.
8009 b = Builder("build_it < $SOURCE > $TARGET"
8012 def gen_prefix(env, sources):
8013 return "file-" + env['PLATFORM'] + '-'
8014 b = Builder("build_it < $SOURCE > $TARGET",
8015 prefix = gen_prefix)
8017 b = Builder("build_it < $SOURCE > $TARGET",
8018 suffix = { None: "file-",
8019 "$SRC_SFX_A": gen_prefix })
8023 The suffix that will be appended to the target file name.
8024 This may be specified in the same manner as the prefix above.
8025 If the suffix is a string, then
8027 will append a '.' to the beginning of the suffix if it's not already
8028 there. The string returned by callable object (or obtained from the
8029 dictionary) is untouched and must append its own '.' to the beginning
8033 b = Builder("build_it < $SOURCE > $TARGET"
8036 def gen_suffix(env, sources):
8037 return "." + env['PLATFORM'] + "-file"
8038 b = Builder("build_it < $SOURCE > $TARGET",
8039 suffix = gen_suffix)
8041 b = Builder("build_it < $SOURCE > $TARGET",
8042 suffix = { None: ".sfx1",
8043 "$SRC_SFX_A": gen_suffix })
8047 When set to any true value, causes
8049 to add the target suffix specified by the
8051 keyword to any target strings
8052 that have a different suffix.
8053 (The default behavior is to leave untouched
8054 any target file name that looks like it already has any suffix.)
8057 b1 = Builder("build_it < $SOURCE > $TARGET"
8059 b2 = Builder("build_it < $SOURCE > $TARGET"
8063 env['BUILDERS']['B1'] = b1
8064 env['BUILDERS']['B2'] = b2
8066 # Builds "foo.txt" because ensure_suffix is not set.
8067 env.B1('foo.txt', 'foo.in')
8069 # Builds "bar.txt.out" because ensure_suffix is set.
8070 env.B2('bar.txt', 'bar.in')
8074 The expected source file name suffix. This may be a string or a list
8078 A Scanner object that
8079 will be invoked to find
8080 implicit dependencies for this target file.
8081 This keyword argument should be used
8082 for Scanner objects that find
8083 implicit dependencies
8084 based only on the target file
8085 and the construction environment,
8088 (See the section "Scanner Objects," below,
8089 for information about creating Scanner objects.)
8092 A Scanner object that
8094 find implicit dependences in
8096 used to build this target file.
8097 This is where you would
8098 specify a scanner to
8101 lines in source files.
8104 Scanner object may be used to
8105 indicate that this Builder
8106 should scan directory trees
8107 for on-disk changes to files
8110 does not know about from other Builder or function calls.
8111 (See the section "Scanner Objects," below,
8112 for information about creating your own Scanner objects.)
8115 A factory function that the Builder will use
8116 to turn any targets specified as strings into SCons Nodes.
8118 SCons assumes that all targets are files.
8119 Other useful target_factory
8122 for when a Builder creates a directory target,
8125 for when a Builder can create either a file
8126 or directory target.
8131 MakeDirectoryBuilder = Builder(action=my_mkdir, target_factory=Dir)
8133 env.Append(BUILDERS = {'MakeDirectory':MakeDirectoryBuilder})
8134 env.MakeDirectory('new_directory', [])
8138 Note that the call to the MakeDirectory Builder
8139 needs to specify an empty source list
8140 to make the string represent the builder's target;
8141 without that, it would assume the argument is the source,
8142 and would try to deduce the target name from it,
8143 which in the absence of an automatically-added prefix or suffix
8144 would lead to a matching target and source name
8145 and a circular dependency.
8148 A factory function that the Builder will use
8149 to turn any sources specified as strings into SCons Nodes.
8151 SCons assumes that all source are files.
8152 Other useful source_factory
8155 for when a Builder uses a directory as a source,
8158 for when a Builder can use files
8159 or directories (or both) as sources.
8164 CollectBuilder = Builder(action=my_mkdir, source_factory=Entry)
8166 env.Append(BUILDERS = {'Collect':CollectBuilder})
8167 env.Collect('archive', ['directory_name', 'file_name'])
8171 A function or list of functions to manipulate the target and source
8172 lists before dependencies are established
8173 and the target(s) are actually built.
8175 can also be a string containing a construction variable to expand
8176 to an emitter function or list of functions,
8177 or a dictionary mapping source file suffixes
8178 to emitter functions.
8179 (Only the suffix of the first source file
8180 is used to select the actual emitter function
8181 from an emitter dictionary.)
8184 takes three arguments:
8186 - a list of source nodes,
8188 - a list of target nodes,
8190 - the construction environment.
8191 An emitter must return a tuple containing two lists,
8192 the list of targets to be built by this builder,
8193 and the list of sources for this builder.
8198 def e(target, source, env):
8199 return (target + ['foo.foo'], source + ['foo.src'])
8201 # Simple association of an emitter function with a Builder.
8202 b = Builder("my_build < $TARGET > $SOURCE",
8205 def e2(target, source, env):
8206 return (target + ['bar.foo'], source + ['bar.src'])
8208 # Simple association of a list of emitter functions with a Builder.
8209 b = Builder("my_build < $TARGET > $SOURCE",
8212 # Calling an emitter function through a construction variable.
8213 env = Environment(MY_EMITTER = e)
8214 b = Builder("my_build < $TARGET > $SOURCE",
8215 emitter = '$MY_EMITTER')
8217 # Calling a list of emitter functions through a construction variable.
8218 env = Environment(EMITTER_LIST = [e, e2])
8219 b = Builder("my_build < $TARGET > $SOURCE",
8220 emitter = '$EMITTER_LIST')
8222 # Associating multiple emitters with different file
8223 # suffixes using a dictionary.
8224 def e_suf1(target, source, env):
8225 return (target + ['another_target_file'], source)
8226 def e_suf2(target, source, env):
8227 return (target, source + ['another_source_file'])
8228 b = Builder("my_build < $TARGET > $SOURCE",
8229 emitter = {'.suf1' : e_suf1,
8234 Specifies whether this builder is allowed to be called multiple times for
8235 the same target file(s). The default is 0, which means the builder
8236 can not be called multiple times for the same target file(s). Calling a
8237 builder multiple times for the same target simply adds additional source
8238 files to the target; it is not allowed to change the environment associated
8239 with the target, specify addition environment overrides, or associate a different
8240 builder with the target.
8243 A construction environment that can be used
8244 to fetch source code using this Builder.
8245 (Note that this environment is
8247 used for normal builds of normal target files,
8248 which use the environment that was
8249 used to call the Builder for the target file.)
8252 A function that returns a list of actions that will be executed to build
8253 the target(s) from the source(s).
8254 The returned action(s) may be
8255 an Action object, or anything that
8256 can be converted into an Action object
8257 (see the next section).
8259 The generator function
8260 takes four arguments:
8262 - a list of source nodes,
8264 - a list of target nodes,
8266 - the construction environment,
8268 - a Boolean value that specifies
8269 whether the generator is being called
8270 for generating a build signature
8271 (as opposed to actually executing the command).
8275 def g(source, target, env, for_signature):
8276 return [["gcc", "-c", "-o"] + target + source]
8278 b = Builder(generator=g)
8286 arguments must not both be used for the same Builder.
8289 Specifies a builder to use when a source file name suffix does not match
8290 any of the suffixes of the builder. Using this argument produces a
8291 multi-stage builder.
8294 Specifies that this builder expects exactly one source file per call. Giving
8295 more than one source file without target files results in implicitely calling
8296 the builder multiple times (once for each source given). Giving multiple
8297 source files together with target files results in a UserError exception.
8305 arguments must not both be used for the same Builder.
8307 .IP source_ext_match
8310 argument is a dictionary,
8311 the default behavior when a builder is passed
8312 multiple source files is to make sure that the
8313 extensions of all the source files match.
8314 If it is legal for this builder to be
8315 called with a list of source files with different extensions,
8316 this check can be suppressed by setting
8320 or some other non-true value.
8325 will use the suffix of the first specified
8326 source file to select the appropriate action from the
8330 In the following example,
8335 from exiting with an error
8336 due to the mismatched suffixes of
8342 b = Builder(action={'.in' : 'build $SOURCES > $TARGET'},
8343 source_ext_match = None)
8345 env = Environment(BUILDERS = {'MyBuild':b})
8346 env.MyBuild('foo.out', ['foo.in', 'foo.extra'])
8350 A construction environment that can be used
8351 to fetch source code using this Builder.
8352 (Note that this environment is
8354 used for normal builds of normal target files,
8355 which use the environment that was
8356 used to call the Builder for the target file.)
8359 b = Builder(action="build < $SOURCE > $TARGET")
8360 env = Environment(BUILDERS = {'MyBuild' : b})
8361 env.MyBuild('foo.out', 'foo.in', my_arg = 'xyzzy')
8365 A directory from which scons
8372 a string or a directory Node,
8373 scons will change to the specified directory.
8376 is not a string or Node
8378 then scons will change to the
8379 target file's directory.
8381 Note that scons will
8383 automatically modify
8385 construction variables like
8389 when using the chdir
8390 keyword argument--that is,
8391 the expanded file names
8392 will still be relative to
8393 the top-level SConstruct directory,
8394 and consequently incorrect
8395 relative to the chdir directory.
8396 Builders created using chdir keyword argument,
8397 will need to use construction variable
8402 to use just the filename portion of the
8406 b = Builder(action="build < ${SOURCE.file} > ${TARGET.file}",
8408 env = Environment(BUILDERS = {'MyBuild' : b})
8409 env.MyBuild('sub/dir/foo.out', 'sub/dir/foo.in')
8413 Python only keeps one current directory
8414 location for all of the threads.
8415 This means that use of the
8423 because individual worker threads spawned
8424 by SCons interfere with each other
8425 when they start changing directory.
8428 Any additional keyword arguments supplied
8429 when a Builder object is created
8430 (that is, when the Builder() function is called)
8431 will be set in the executing construction
8432 environment when the Builder object is called.
8433 The canonical example here would be
8434 to set a construction variable to
8435 the repository of a source code system.
8437 Any additional keyword arguments supplied
8441 will only be associated with the target
8442 created by that particular Builder call
8443 (and any other files built as a
8444 result of the call).
8446 These extra keyword arguments are passed to the
8447 following functions:
8448 command generator functions,
8450 and emitter functions.
8456 function will turn its
8458 keyword argument into an appropriate
8459 internal Action object.
8460 You can also explicity create Action objects
8464 which can then be passed to the
8467 This can be used to configure
8468 an Action object more flexibly,
8469 or it may simply be more efficient
8470 than letting each separate Builder object
8471 create a separate Action
8473 Builder objects need to do the same thing.
8478 returns an appropriate object for the action
8479 represented by the type of the first argument:
8482 If the first argument is already an Action object,
8483 the object is simply returned.
8486 If the first argument is a string,
8487 a command-line Action is returned.
8488 Note that the command-line string
8489 may be preceded by an
8492 to suppress printing of the specified command line,
8496 to ignore the exit status from the specified command:
8499 Action('$CC -c -o $TARGET $SOURCES')
8501 # Doesn't print the line being executed.
8502 Action('@build $TARGET $SOURCES')
8504 # Ignores return value
8505 Action('-build $TARGET $SOURCES')
8507 .\" XXX From Gary Ruben, 23 April 2002:
8508 .\" What would be useful is a discussion of how you execute command
8509 .\" shell commands ie. what is the process used to spawn the shell, pass
8510 .\" environment variables to it etc., whether there is one shell per
8511 .\" environment or one per command etc. It might help to look at the Gnu
8512 .\" make documentation to see what they think is important to discuss about
8513 .\" a build system. I'm sure you can do a better job of organising the
8514 .\" documentation than they have :-)
8517 If the first argument is a list,
8518 then a list of Action objects is returned.
8519 An Action object is created as necessary
8520 for each element in the list.
8523 the list is itself a list,
8524 the internal list is the
8525 command and arguments to be executed via
8527 This allows white space to be enclosed
8528 in an argument by defining
8529 a command in a list within a list:
8532 Action([['cc', '-c', '-DWHITE SPACE', '-o', '$TARGET', '$SOURCES']])
8536 If the first argument is a Python function,
8537 a function Action is returned.
8538 The Python function must take three keyword arguments,
8540 (a Node object representing the target file),
8542 (a Node object representing the source file)
8545 (the construction environment
8546 used for building the target file).
8551 arguments may be lists of Node objects if there is
8552 more than one target file or source file.
8553 The actual target and source file name(s) may
8554 be retrieved from their Node objects
8555 via the built-in Python str() function:
8558 target_file_name = str(target)
8559 source_file_names = map(lambda x: str(x), source)
8562 The function should return
8566 to indicate a successful build of the target file(s).
8567 The function may raise an exception
8568 or return a non-zero exit status
8569 to indicate an unsuccessful build.
8572 def build_it(target = None, source = None, env = None):
8573 # build the target from the source
8576 a = Action(build_it)
8579 If the action argument is not one of the above,
8583 The second argument is optional and is used to define the output
8584 which is printed when the Action is actually performed.
8585 In the absence of this parameter,
8586 or if it's an empty string,
8587 a default output depending on the type of the action is used.
8588 For example, a command-line action will print the executed command.
8589 The argument must be either a Python function or a string.
8592 it's a function that returns a string to be printed
8593 to describe the action being executed.
8594 The function may also be specified by the
8597 Like a function to build a file,
8598 this function must take three keyword arguments:
8600 (a Node object representing the target file),
8602 (a Node object representing the source file)
8605 (a construction environment).
8610 arguments may be lists of Node objects if there is
8611 more than one target file or source file.
8613 In the second case, you provide the string itself.
8614 The string may also be specified by the
8617 The string typically contains variables, notably
8618 $TARGET(S) and $SOURCE(S), or consists of just a single
8619 variable, which is optionally defined somewhere else.
8620 SCons itself heavily uses the latter variant.
8625 def build_it(target, source, env):
8626 # build the target from the source
8629 def string_it(target, source, env):
8630 return "building '%s' from '%s'" % (target[0], source[0])
8632 # Use a positional argument.
8633 f = Action(build_it, string_it)
8634 s = Action(build_it, "building '$TARGET' from '$SOURCE'")
8636 # Alternatively, use a keyword argument.
8637 f = Action(build_it, strfunction=string_it)
8638 s = Action(build_it, cmdstr="building '$TARGET' from '$SOURCE'")
8640 # You can provide a configurable variable.
8641 l = Action(build_it, '$STRINGIT')
8644 The third and succeeding arguments, if present,
8645 may either be a construction variable or a list of construction variables
8646 whose values will be included in the signature of the Action
8647 when deciding whether a target should be rebuilt because the action changed.
8648 The variables may also be specified by a
8651 if both are present, they are combined.
8652 This is necessary whenever you want a target to be rebuilt
8653 when a specific construction variable changes.
8654 This is not often needed for a string action,
8655 as the expanded variables will normally be part of the command line,
8656 but may be needed if a Python function action uses
8657 the value of a construction variable when generating the command line.
8660 def build_it(target, source, env):
8661 # build the target from the 'XXX' construction variable
8662 open(target[0], 'w').write(env['XXX'])
8665 # Use positional arguments.
8666 a = Action(build_it, '$STRINGIT', ['XXX'])
8668 # Alternatively, use a keyword argument.
8669 a = Action(build_it, varlist=['XXX'])
8675 can be passed the following
8676 optional keyword arguments
8677 to modify the Action object's behavior:
8683 keyword argument specifies that
8684 scons will execute the action
8685 after changing to the specified directory.
8689 a string or a directory Node,
8690 scons will change to the specified directory.
8694 is not a string or Node
8696 then scons will change to the
8697 target file's directory.
8699 Note that scons will
8701 automatically modify
8703 construction variables like
8707 when using the chdir
8708 keyword argument--that is,
8709 the expanded file names
8710 will still be relative to
8711 the top-level SConstruct directory,
8712 and consequently incorrect
8713 relative to the chdir directory.
8714 Builders created using chdir keyword argument,
8715 will need to use construction variable
8720 to use just the filename portion of the
8724 a = Action("build < ${SOURCE.file} > ${TARGET.file}",
8736 which specifies a function
8737 that is passed the exit status
8739 from the specified action
8740 and can return an arbitrary
8742 This can be used, for example,
8743 to specify that an Action object's
8744 return value should be ignored
8745 under special conditions
8746 and SCons should, therefore,
8747 consider that the action always suceeds:
8750 def always_succeed(s):
8751 # Always return 0, which indicates success.
8753 a = Action("build < ${SOURCE.file} > ${TARGET.file}",
8754 exitstatfunc=always_succeed)
8761 keyword argument can be used
8762 to specify that the Action can create multiple target files
8763 by processing multiple independent source files simultaneously.
8764 (The canonical example is "batch compilation"
8765 of multiple object files
8766 by passing multiple source files
8767 to a single invocation of a compiler
8768 such as Microsoft's Visual C / C++ compiler.)
8771 argument is any non-False, non-callable Python value,
8772 the configured Action object will cause
8774 to collect all targets built with the Action object
8775 and configured with the same construction environment
8776 into single invocations of the Action object's
8777 command line or function.
8778 Command lines will typically want to use the
8780 construction variable
8784 to only pass to the command line those sources that
8785 have actually changed since their targets were built.
8790 a = Action('build $CHANGED_SOURCES', batch_key=True)
8795 argument may also be
8797 that returns a key that
8798 will be used to identify different
8799 "batches" of target files to be collected
8803 function must take the following arguments:
8809 The construction environment
8810 configured for the target.
8813 The list of targets for a particular configured action.
8816 The list of source for a particular configured action.
8818 The returned key should typically
8819 be a tuple of values derived from the arguments,
8820 using any appropriate logic to decide
8821 how multiple invocations should be batched.
8824 function may decide to return
8825 the value of a specific construction
8831 to batch-build targets
8832 with matching values of that variable,
8833 or perhaps return the
8835 of the entire construction environment,
8839 all targets configured with the same construction environment.
8843 the particular target should
8845 be part of any batched build,
8846 but instead will be built
8847 by a separate invocation of action's
8848 command or function.
8852 def batch_key(action, env, target, source):
8853 tdir = target[0].dir
8854 if tdir.name == 'special':
8855 # Don't batch-build any target
8856 # in the special/ subdirectory.
8858 return (id(action), id(env), tdir)
8859 a = Action('build $CHANGED_SOURCES', batch_key=batch_key)
8862 .SS Miscellaneous Action Functions
8865 supplies a number of functions
8866 that arrange for various common
8867 file and directory manipulations
8869 These are similar in concept to "tasks" in the
8871 although the implementation is slightly different.
8872 These functions do not actually
8873 perform the specified action
8874 at the time the function is called,
8875 but instead return an Action object
8876 that can be executed at the
8878 (In Object-Oriented terminology,
8883 that return Action objects.)
8886 there are two natural ways
8889 are intended to be used.
8893 to perform the action
8894 at the time the SConscript
8898 global function to do so:
8900 Execute(Touch('file'))
8904 you can use these functions
8905 to supply Actions in a list
8909 This can allow you to
8910 perform more complicated
8911 sequences of file manipulation
8913 on platform-specific
8917 env = Environment(TMPBUILD = '/tmp/builddir')
8918 env.Command('foo.out', 'foo.in',
8919 [Mkdir('$TMPBUILD'),
8920 Copy('$TMPBUILD', '${SOURCE.dir}'),
8921 "cd $TMPBUILD && make",
8922 Delete('$TMPBUILD')])
8926 .RI Chmod( dest ", " mode )
8927 Returns an Action object that
8928 changes the permissions on the specified
8930 file or directory to the specified
8935 Execute(Chmod('file', 0755))
8937 env.Command('foo.out', 'foo.in',
8938 [Copy('$TARGET', '$SOURCE'),
8939 Chmod('$TARGET', 0755)])
8943 .RI Copy( dest ", " src )
8944 Returns an Action object
8947 source file or directory to the
8949 destination file or directory.
8953 Execute(Copy('foo.output', 'foo.input'))
8955 env.Command('bar.out', 'bar.in',
8956 Copy('$TARGET', '$SOURCE'))
8960 .RI Delete( entry ", [" must_exist ])
8961 Returns an Action that
8962 deletes the specified
8964 which may be a file or a directory tree.
8965 If a directory is specified,
8966 the entire directory tree
8971 then a Python error will be thrown
8972 if the specified entry does not exist;
8975 that is, the Action will silently do nothing
8976 if the entry does not exist.
8980 Execute(Delete('/tmp/buildroot'))
8982 env.Command('foo.out', 'foo.in',
8983 [Delete('${TARGET.dir}'),
8986 Execute(Delete('file_that_must_exist', must_exist=1))
8992 that creates the specified
8998 Execute(Mkdir('/tmp/outputdir'))
9000 env.Command('foo.out', 'foo.in',
9001 [Mkdir('/tmp/builddir'),
9002 Copy('/tmp/builddir/foo.in', '$SOURCE'),
9003 "cd /tmp/builddir && make",
9004 Copy('$TARGET', '/tmp/builddir/foo.out')])
9008 .RI Move( dest ", " src )
9010 that moves the specified
9012 file or directory to
9019 Execute(Move('file.destination', 'file.source'))
9021 env.Command('output_file', 'input_file',
9023 Move('$TARGET', 'file_created_by_MyBuildAction')])
9029 that updates the modification time
9035 Execute(Touch('file_to_be_touched'))
9037 env.Command('marker', 'input_file',
9042 .SS Variable Substitution
9044 Before executing a command,
9046 performs construction variable interpolation on the strings that make up
9047 the command line of builders.
9048 Variables are introduced by a
9051 Besides construction variables, scons provides the following
9052 variables for each command execution:
9055 The file names of all sources of the build command
9056 that have changed since the target was last built.
9059 The file names of all targets that would be built
9060 from sources that have changed since the target was last built.
9063 The file name of the source of the build command,
9064 or the file name of the first source
9065 if multiple sources are being built.
9068 The file names of the sources of the build command.
9071 The file name of the target being built,
9072 or the file name of the first target
9073 if multiple targets are being built.
9076 The file names of all targets being built.
9078 .IP UNCHANGED_SOURCES
9079 The file names of all sources of the build command
9082 changed since the target was last built.
9084 .IP UNCHANGED_TARGETS
9085 The file names of all targets that would be built
9086 from sources that have
9088 changed since the target was last built.
9090 (Note that the above variables are reserved
9091 and may not be set in a construction environment.)
9094 For example, given the construction variable CC='cc', targets=['foo'], and
9095 sources=['foo.c', 'bar.c']:
9098 action='$CC -c -o $TARGET $SOURCES'
9101 would produce the command line:
9104 cc -c -o foo foo.c bar.c
9107 Variable names may be surrounded by curly braces ({})
9108 to separate the name from the trailing characters.
9109 Within the curly braces, a variable name may have
9110 a Python slice subscript appended to select one
9111 or more items from a list.
9112 In the previous example, the string:
9124 Additionally, a variable name may
9125 have the following special
9126 modifiers appended within the enclosing curly braces
9127 to modify the interpolated string:
9130 The base path of the file name,
9131 including the directory path
9132 but excluding any suffix.
9135 The name of the directory in which the file exists.
9139 minus any directory portion.
9142 Just the basename of the file,
9144 and minus the directory.
9147 Just the file suffix.
9150 The absolute path name of the file.
9153 The POSIX form of the path,
9154 with directories separated by
9158 This is sometimes necessary on Windows systems
9159 when a path references a file on other (POSIX) systems.
9162 The directory and file name to the source file linked to this file through
9164 If this file isn't linked,
9165 it just returns the directory and filename unchanged.
9168 The directory containing the source file linked to this file through
9170 If this file isn't linked,
9171 it just returns the directory part of the filename.
9174 The directory and file name to the source file linked to this file through
9176 If the file does not exist locally but exists in a Repository,
9177 the path in the Repository is returned.
9178 If this file isn't linked, it just returns the
9179 directory and filename unchanged.
9182 The Repository directory containing the source file linked to this file through
9184 If this file isn't linked,
9185 it just returns the directory part of the filename.
9188 For example, the specified target will
9189 expand as follows for the corresponding modifiers:
9192 $TARGET => sub/dir/file.x
9193 ${TARGET.base} => sub/dir/file
9194 ${TARGET.dir} => sub/dir
9195 ${TARGET.file} => file.x
9196 ${TARGET.filebase} => file
9197 ${TARGET.suffix} => .x
9198 ${TARGET.abspath} => /top/dir/sub/dir/file.x
9200 SConscript('src/SConscript', variant_dir='sub/dir')
9201 $SOURCE => sub/dir/file.x
9202 ${SOURCE.srcpath} => src/file.x
9203 ${SOURCE.srcdir} => src
9205 Repository('/usr/repository')
9206 $SOURCE => sub/dir/file.x
9207 ${SOURCE.rsrcpath} => /usr/repository/src/file.x
9208 ${SOURCE.rsrcdir} => /usr/repository/src
9211 Note that curly braces braces may also be used
9212 to enclose arbitrary Python code to be evaluated.
9213 (In fact, this is how the above modifiers are substituted,
9214 they are simply attributes of the Python objects
9215 that represent TARGET, SOURCES, etc.)
9216 See the section "Python Code Substitution," below,
9217 for more thorough examples of
9218 how this can be used.
9220 Lastly, a variable name
9221 may be a callable Python function
9223 construction variable in the environment.
9225 take four arguments:
9227 - a list of target nodes,
9229 - a list of source nodes,
9231 - the construction environment,
9233 - a Boolean value that specifies
9234 whether the function is being called
9235 for generating a build signature.
9236 SCons will insert whatever
9237 the called function returns
9238 into the expanded string:
9241 def foo(target, source, env, for_signature):
9244 # Will expand $BAR to "bar baz"
9245 env=Environment(FOO=foo, BAR="$FOO baz")
9248 You can use this feature to pass arguments to a
9249 Python function by creating a callable class
9250 that stores one or more arguments in an object,
9251 and then uses them when the
9254 Note that in this case,
9255 the entire variable expansion must
9256 be enclosed by curly braces
9257 so that the arguments will
9258 be associated with the
9259 instantiation of the class:
9263 def __init__(self, arg):
9266 def __call__(self, target, source, env, for_signature):
9267 return self.arg + " bar"
9269 # Will expand $BAR to "my argument bar baz"
9270 env=Environment(FOO=foo, BAR="${FOO('my argument')} baz")
9274 The special pseudo-variables
9278 may be used to surround parts of a command line
9281 causing a rebuild--that is,
9282 which are not included in the signature
9283 of target files built with this command.
9288 will be removed from the command line
9289 before it is added to file signatures,
9294 will be removed before the command is executed.
9295 For example, the command line:
9298 echo Last build occurred $( $TODAY $). > $TARGET
9302 would execute the command:
9305 echo Last build occurred $TODAY. > $TARGET
9309 but the command signature added to any target files would be:
9312 echo Last build occurred . > $TARGET
9315 .SS Python Code Substitution
9317 Any python code within
9319 pairs gets evaluated by python 'eval', with the python globals set to
9320 the current environment's set of construction variables.
9321 So in the following case:
9324 env.Command('foo.out', 'foo.in',
9325 '''echo ${COND==1 and 'FOO' or 'BAR'} > $TARGET''')
9327 the command executed will be either
9335 according to the current value of env['COND'] when the command is
9336 executed. The evaluation occurs when the target is being
9337 built, not when the SConscript is being read. So if env['COND'] is changed
9338 later in the SConscript, the final value will be used.
9340 Here's a more interesting example. Note that all of COND, FOO, and
9341 BAR are environment variables, and their values are substituted into
9342 the final command. FOO is a list, so its elements are interpolated
9343 separated by spaces.
9348 env['FOO'] = ['foo1', 'foo2']
9349 env['BAR'] = 'barbar'
9350 env.Command('foo.out', 'foo.in',
9351 'echo ${COND==1 and FOO or BAR} > $TARGET')
9353 # Will execute this:
9354 # echo foo1 foo2 > foo.out
9357 SCons uses the following rules when converting construction variables into
9361 When the value is a string it is interpreted as a space delimited list of
9362 command line arguments.
9365 When the value is a list it is interpreted as a list of command line
9366 arguments. Each element of the list is converted to a string.
9369 Anything that is not a list or string is converted to a string and
9370 interpreted as a single command line argument.
9373 Newline characters (\\n) delimit lines. The newline parsing is done after
9374 all other parsing, so it is not possible for arguments (e.g. file names) to
9375 contain embedded newline characters. This limitation will likely go away in
9376 a future version of SCons.
9384 new file types for implicit dependencies.
9385 Scanner accepts the following arguments:
9389 1) a Python function that will process
9391 and return a list of strings (file names)
9392 representing the implicit
9393 dependencies found in the contents;
9395 2) a dictionary that maps keys
9396 (typically the file suffix, but see below for more discussion)
9397 to other Scanners that should be called.
9399 If the argument is actually a Python function,
9400 the function must take three or four arguments:
9402 def scanner_function(node, env, path):
9404 def scanner_function(node, env, path, arg=None):
9408 argument is the internal
9409 SCons node representing the file.
9412 to fetch the name of the file, and
9413 .B node.get_contents()
9414 to fetch contents of the file.
9415 Note that the file is
9417 guaranteed to exist before the scanner is called,
9418 so the scanner function should check that
9419 if there's any chance that the scanned file
9421 (for example, if it's built from other files).
9425 argument is the construction environment for the scan.
9426 Fetch values from it using the
9432 argument is a tuple (or list)
9433 of directories that can be searched
9435 This will usually be the tuple returned by the
9437 argument (see below).
9441 argument is the argument supplied
9442 when the scanner was created, if any.
9445 The name of the Scanner.
9447 to identify the Scanner internally.
9450 An optional argument that, if specified,
9451 will be passed to the scanner function
9453 and the path function
9457 An optional list that can be used to
9458 determine which scanner should be used for
9460 In the usual case of scanning for file names,
9461 this argument will be a list of suffixes
9462 for the different file types that this
9463 Scanner knows how to scan.
9464 If the argument is a string,
9465 then it will be expanded
9466 into a list by the current environment.
9469 A Python function that takes four or five arguments:
9470 a construction environment,
9471 a Node for the directory containing
9472 the SConscript file in which
9473 the first target was defined,
9474 a list of target nodes,
9475 a list of source nodes,
9476 and an optional argument supplied
9477 when the scanner was created.
9480 returns a tuple of directories
9481 that can be searched for files to be returned
9482 by this Scanner object.
9485 function can be used to return a ready-made
9487 for a given construction variable name,
9488 instead of having to write your own function from scratch.)
9491 The class of Node that should be returned
9492 by this Scanner object.
9493 Any strings or other objects returned
9494 by the scanner function
9495 that are not of this class
9496 will be run through the
9501 A Python function that will take a string
9503 and turn it into the appropriate class of Node
9504 to be returned by this Scanner object.
9507 An optional Python function that takes two arguments,
9508 a Node (file) and a construction environment,
9509 and returns whether the
9510 Node should, in fact,
9511 be scanned for dependencies.
9512 This check can be used to eliminate unnecessary
9513 calls to the scanner function when,
9514 for example, the underlying file
9515 represented by a Node does not yet exist.
9518 An optional flag that
9519 specifies whether this scanner should be re-invoked
9520 on the dependency files returned by the scanner.
9521 When this flag is not set,
9522 the Node subsystem will
9523 only invoke the scanner on the file being scanned,
9524 and not (for example) also on the files
9525 specified by the #include lines
9526 in the file being scanned.
9528 may be a callable function,
9529 in which case it will be called with a list of
9531 should return a list of Nodes
9532 that should be scanned recursively;
9533 this can be used to select a specific subset of
9534 Nodes for additional scanning.
9539 .B SourceFileScanner
9540 object that is used by
9543 .BR SharedObject (),
9547 which scanner should be used
9548 for different file extensions.
9550 .BR SourceFileScanner.add_scanner ()
9551 method to add your own Scanner object
9555 that builds target programs or
9556 libraries from a list of
9557 source files of different types:
9560 def xyz_scan(node, env, path):
9561 contents = node.get_text_contents()
9562 # Scan the contents and return the included files.
9564 XYZScanner = Scanner(xyz_scan)
9566 SourceFileScanner.add_scanner('.xyx', XYZScanner)
9568 env.Program('my_prog', ['file1.c', 'file2.f', 'file3.xyz'])
9571 .SH SYSTEM-SPECIFIC BEHAVIOR
9572 SCons and its configuration files are very portable,
9573 due largely to its implementation in Python.
9574 There are, however, a few portability
9575 issues waiting to trap the unwary.
9577 SCons handles the upper-case
9579 file suffix differently,
9580 depending on the capabilities of
9581 the underlying system.
9582 On a case-sensitive system
9583 such as Linux or UNIX,
9584 SCons treats a file with a
9586 suffix as a C++ source file.
9587 On a case-insensitive system
9589 SCons treats a file with a
9591 suffix as a C source file.
9593 SCons handles the upper-case
9595 file suffix differently,
9596 depending on the capabilities of
9597 the underlying system.
9598 On a case-sensitive system
9599 such as Linux or UNIX,
9600 SCons treats a file with a
9602 suffix as a Fortran source file
9603 that is to be first run through
9604 the standard C preprocessor.
9605 On a case-insensitive system
9607 SCons treats a file with a
9609 suffix as a Fortran source file that should
9611 be run through the C preprocessor.
9612 .SS Windows: Cygwin Tools and Cygwin Python vs. Windows Pythons
9613 Cygwin supplies a set of tools and utilities
9614 that let users work on a
9615 Windows system using a more POSIX-like environment.
9616 The Cygwin tools, including Cygwin Python,
9618 by sharing an ability to interpret UNIX-like path names.
9619 For example, the Cygwin tools
9620 will internally translate a Cygwin path name
9621 like /cygdrive/c/mydir
9622 to an equivalent Windows pathname
9623 of C:/mydir (equivalent to C:\\mydir).
9626 that are built for native Windows execution,
9627 such as the python.org and ActiveState versions,
9628 do not have the Cygwin path name semantics.
9629 This means that using a native Windows version of Python
9630 to build compiled programs using Cygwin tools
9631 (such as gcc, bison, and flex)
9632 may yield unpredictable results.
9633 "Mixing and matching" in this way
9634 can be made to work,
9635 but it requires careful attention to the use of path names
9636 in your SConscript files.
9638 In practice, users can sidestep
9639 the issue by adopting the following rules:
9641 use the Cygwin-supplied Python interpreter
9643 when using Microsoft Visual C/C++
9644 (or some other Windows compiler)
9645 use the python.org or ActiveState version of Python
9647 .SS Windows: scons.bat file
9649 SCons is executed via a wrapper
9652 This has (at least) two ramifications:
9654 First, Windows command-line users
9655 that want to use variable assignment
9657 may have to put double quotes
9658 around the assignments:
9661 scons "FOO=BAR" "BAZ=BLEH"
9664 Second, the Cygwin shell does not
9665 recognize this file as being the same
9668 command issued at the command-line prompt.
9669 You can work around this either by
9672 from the Cygwin command line,
9673 or by creating a wrapper shell
9679 The MinGW bin directory must be in your PATH environment variable or the
9680 PATH variable under the ENV construction variable for SCons
9681 to detect and use the MinGW tools. When running under the native Windows
9682 Python interpreter, SCons will prefer the MinGW tools over the Cygwin
9683 tools, if they are both installed, regardless of the order of the bin
9684 directories in the PATH variable. If you have both MSVC and MinGW
9685 installed and you want to use MinGW instead of MSVC,
9686 then you must explictly tell SCons to use MinGW by passing
9692 to the Environment() function, because SCons will prefer the MSVC tools
9693 over the MinGW tools.
9697 To help you get started using SCons,
9698 this section contains a brief overview of some common tasks.
9700 .SS Basic Compilation From a Single Source File
9704 env.Program(target = 'foo', source = 'foo.c')
9707 Note: Build the file by specifying
9708 the target as an argument
9709 ("scons foo" or "scons foo.exe").
9710 or by specifying a dot ("scons .").
9712 .SS Basic Compilation From Multiple Source Files
9716 env.Program(target = 'foo', source = Split('f1.c f2.c f3.c'))
9719 .SS Setting a Compilation Flag
9722 env = Environment(CCFLAGS = '-g')
9723 env.Program(target = 'foo', source = 'foo.c')
9726 .SS Search The Local Directory For .h Files
9730 need to set CCFLAGS to specify -I options by hand.
9731 SCons will construct the right -I options from CPPPATH.
9734 env = Environment(CPPPATH = ['.'])
9735 env.Program(target = 'foo', source = 'foo.c')
9738 .SS Search Multiple Directories For .h Files
9741 env = Environment(CPPPATH = ['include1', 'include2'])
9742 env.Program(target = 'foo', source = 'foo.c')
9745 .SS Building a Static Library
9749 env.StaticLibrary(target = 'foo', source = Split('l1.c l2.c'))
9750 env.StaticLibrary(target = 'bar', source = ['l3.c', 'l4.c'])
9753 .SS Building a Shared Library
9757 env.SharedLibrary(target = 'foo', source = ['l5.c', 'l6.c'])
9758 env.SharedLibrary(target = 'bar', source = Split('l7.c l8.c'))
9761 .SS Linking a Local Library Into a Program
9764 env = Environment(LIBS = 'mylib', LIBPATH = ['.'])
9765 env.Library(target = 'mylib', source = Split('l1.c l2.c'))
9766 env.Program(target = 'prog', source = ['p1.c', 'p2.c'])
9769 .SS Defining Your Own Builder Object
9771 Notice that when you invoke the Builder,
9772 you can leave off the target file suffix,
9773 and SCons will add it automatically.
9776 bld = Builder(action = 'pdftex < $SOURCES > $TARGET'
9778 src_suffix = '.tex')
9779 env = Environment(BUILDERS = {'PDFBuilder' : bld})
9780 env.PDFBuilder(target = 'foo.pdf', source = 'foo.tex')
9782 # The following creates "bar.pdf" from "bar.tex"
9783 env.PDFBuilder(target = 'bar', source = 'bar')
9786 Note also that the above initialization
9787 overwrites the default Builder objects,
9788 so the Environment created above
9789 can not be used call Builders like env.Program(),
9790 env.Object(), env.StaticLibrary(), etc.
9792 .SS Adding Your Own Builder Object to an Environment
9795 bld = Builder(action = 'pdftex < $SOURCES > $TARGET'
9797 src_suffix = '.tex')
9799 env.Append(BUILDERS = {'PDFBuilder' : bld})
9800 env.PDFBuilder(target = 'foo.pdf', source = 'foo.tex')
9801 env.Program(target = 'bar', source = 'bar.c')
9804 You also can use other Pythonic techniques to add
9805 to the BUILDERS construction variable, such as:
9809 env['BUILDERS]['PDFBuilder'] = bld
9812 .SS Defining Your Own Scanner Object
9814 The following example shows an extremely simple scanner (the
9817 that doesn't use a search path at all
9818 and simply returns the
9819 file names present on any
9821 lines in the scanned file.
9822 This would implicitly assume that all included
9823 files live in the top-level directory:
9828 '\" Note: the \\ in the following are for the benefit of nroff/troff,
9829 '\" not inappropriate doubled escape characters within the r'' raw string.
9830 include_re = re.compile(r'^include\\s+(\\S+)$', re.M)
9832 def kfile_scan(node, env, path, arg):
9833 contents = node.get_text_contents()
9834 includes = include_re.findall(contents)
9837 kscan = Scanner(name = 'kfile',
9838 function = kfile_scan,
9841 scanners = Environment().Dictionary('SCANNERS')
9842 env = Environment(SCANNERS = scanners + [kscan])
9844 env.Command('foo', 'foo.k', 'kprocess < $SOURCES > $TARGET')
9846 bar_in = File('bar.in')
9847 env.Command('bar', bar_in, 'kprocess $SOURCES > $TARGET')
9848 bar_in.target_scanner = kscan
9851 Here is a similar but more complete example that searches
9852 a path of directories
9855 construction variable)
9856 for files that actually exist:
9859 include_re = re.compile(r'^include\\s+(\\S+)$', re.M)
9861 def my_scan(node, env, path, arg):
9862 contents = node.get_text_contents()
9863 includes = include_re.findall(contents)
9867 for inc in includes:
9869 file = dir + os.sep + inc
9870 if os.path.exists(file):
9871 results.append(file)
9875 scanner = Scanner(name = 'myscanner',
9879 path_function = FindPathDirs('MYPATH'),
9881 scanners = Environment().Dictionary('SCANNERS')
9882 env = Environment(SCANNERS = scanners + [scanner])
9887 function used in the previous example returns a function
9888 (actually a callable Python object)
9889 that will return a list of directories
9892 construction variable.
9893 If you need to customize how the search path is derived,
9894 you would provide your own
9896 argument when creating the Scanner object,
9900 # MYPATH is a list of directories to search for files in
9901 def pf(env, dir, target, source, arg):
9902 top_dir = Dir('#').abspath
9904 if env.has_key('MYPATH'):
9905 for p in env['MYPATH']:
9906 results.append(top_dir + os.sep + p)
9909 scanner = Scanner(name = 'myscanner',
9917 .SS Creating a Hierarchical Build
9919 Notice that the file names specified in a subdirectory's
9921 file are relative to that subdirectory.
9927 env.Program(target = 'foo', source = 'foo.c')
9929 SConscript('sub/SConscript')
9934 # Builds sub/foo from sub/foo.c
9935 env.Program(target = 'foo', source = 'foo.c')
9937 SConscript('dir/SConscript')
9942 # Builds sub/dir/foo from sub/dir/foo.c
9943 env.Program(target = 'foo', source = 'foo.c')
9946 .SS Sharing Variables Between SConscript Files
9948 You must explicitly Export() and Import() variables that
9949 you want to share between SConscript files.
9955 env.Program(target = 'foo', source = 'foo.c')
9958 SConscript('subdirectory/SConscript')
9960 subdirectory/SConscript:
9963 env.Program(target = 'foo', source = 'foo.c')
9966 .SS Building Multiple Variants From the Same Source
9968 Use the variant_dir keyword argument to
9969 the SConscript function to establish
9970 one or more separate variant build directory trees
9971 for a given source directory:
9976 cppdefines = ['FOO']
9977 Export("cppdefines")
9978 SConscript('src/SConscript', variant_dir='foo')
9980 cppdefines = ['BAR']
9981 Export("cppdefines")
9982 SConscript('src/SConscript', variant_dir='bar')
9986 Import("cppdefines")
9987 env = Environment(CPPDEFINES = cppdefines)
9988 env.Program(target = 'src', source = 'src.c')
9991 Note the use of the Export() method
9992 to set the "cppdefines" variable to a different
9993 value each time we call the SConscript function.
9995 .SS Hierarchical Build of Two Libraries Linked With a Program
10000 env = Environment(LIBPATH = ['#libA', '#libB'])
10002 SConscript('libA/SConscript')
10003 SConscript('libB/SConscript')
10004 SConscript('Main/SConscript')
10009 env.Library('a', Split('a1.c a2.c a3.c'))
10014 env.Library('b', Split('b1.c b2.c b3.c'))
10019 e = env.Copy(LIBS = ['a', 'b'])
10020 e.Program('foo', Split('m1.c m2.c m3.c'))
10023 The '#' in the LIBPATH directories specify that they're relative to the
10024 top-level directory, so they don't turn into "Main/libA" when they're
10025 used in Main/SConscript.
10027 Specifying only 'a' and 'b' for the library names
10028 allows SCons to append the appropriate library
10029 prefix and suffix for the current platform
10030 (for example, 'liba.a' on POSIX systems,
10031 \&'a.lib' on Windows).
10033 .SS Customizing construction variables from the command line.
10035 The following would allow the C compiler to be specified on the command
10036 line or in the file custom.py.
10039 vars = Variables('custom.py')
10040 vars.Add('CC', 'The C compiler.')
10041 env = Environment(variables=vars)
10042 Help(vars.GenerateHelpText(env))
10045 The user could specify the C compiler on the command line:
10051 or in the custom.py file:
10057 or get documentation on the options:
10062 CC: The C compiler.
10068 .SS Using Microsoft Visual C++ precompiled headers
10070 Since windows.h includes everything and the kitchen sink, it can take quite
10071 some time to compile it over and over again for a bunch of object files, so
10072 Microsoft provides a mechanism to compile a set of headers once and then
10073 include the previously compiled headers in any object file. This
10074 technology is called precompiled headers. The general recipe is to create a
10075 file named "StdAfx.cpp" that includes a single header named "StdAfx.h", and
10076 then include every header you want to precompile in "StdAfx.h", and finally
10077 include "StdAfx.h" as the first header in all the source files you are
10078 compiling to object files. For example:
10082 #include <windows.h>
10083 #include <my_big_header.h>
10088 #include <StdAfx.h>
10093 #include <StdAfx.h>
10095 /* do some stuff */
10100 #include <StdAfx.h>
10102 /* do some other stuff */
10108 env['PCHSTOP'] = 'StdAfx.h'
10109 env['PCH'] = env.PCH('StdAfx.cpp')[0]
10110 env.Program('MyApp', ['Foo.cpp', 'Bar.cpp'])
10113 For more information see the document for the PCH builder, and the PCH and
10114 PCHSTOP construction variables. To learn about the details of precompiled
10115 headers consult the MSDN documention for /Yc, /Yu, and /Yp.
10117 .SS Using Microsoft Visual C++ external debugging information
10119 Since including debugging information in programs and shared libraries can
10120 cause their size to increase significantly, Microsoft provides a mechanism
10121 for including the debugging information in an external file called a PDB
10122 file. SCons supports PDB files through the PDB construction
10128 env['PDB'] = 'MyApp.pdb'
10129 env.Program('MyApp', ['Foo.cpp', 'Bar.cpp'])
10132 For more information see the document for the PDB construction variable.
10137 Specifies the directory that contains the SCons Python module directory
10138 (e.g. /home/aroach/scons-src-0.01/src/engine).
10141 A string of options that will be used by scons in addition to those passed
10142 on the command line.
10153 Steven Knight <knight@baldmt.com>
10155 Anthony Roach <aroach@electriceyeball.com>