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:
1808 Additionally, there is a "tool" named
1810 which configures the
1811 environment with a default set of tools for the current platform.
1813 On posix and cygwin platforms
1814 the GNU tools (e.g. gcc) are preferred by SCons,
1815 on Windows the Microsoft tools (e.g. msvc)
1816 followed by MinGW are preferred by SCons,
1817 and in OS/2 the IBM tools (e.g. icc) are preferred by SCons.
1821 Build rules are specified by calling a construction
1822 environment's builder methods.
1823 The arguments to the builder methods are
1825 (a list of targets to be built,
1829 (a list of sources to be built,
1830 usually file names).
1832 Because long lists of file names
1833 can lead to a lot of quoting,
1838 and a same-named environment method
1839 that split a single string
1840 into a list, separated on
1841 strings of white-space characters.
1842 (These are similar to the
1843 string.split() method
1844 from the standard Python library,
1845 but work even if the input isn't a string.)
1847 Like all Python arguments,
1848 the target and source arguments to a builder method
1849 can be specified either with or without
1850 the "target" and "source" keywords.
1851 When the keywords are omitted,
1852 the target is first,
1853 followed by the source.
1854 The following are equivalent examples of calling the Program builder method:
1857 env.Program('bar', ['bar.c', 'foo.c'])
1858 env.Program('bar', Split('bar.c foo.c'))
1859 env.Program('bar', env.Split('bar.c foo.c'))
1860 env.Program(source = ['bar.c', 'foo.c'], target = 'bar')
1861 env.Program(target = 'bar', Split('bar.c foo.c'))
1862 env.Program(target = 'bar', env.Split('bar.c foo.c'))
1863 env.Program('bar', source = string.split('bar.c foo.c'))
1866 Target and source file names
1867 that are not absolute path names
1868 (that is, do not begin with
1875 an optional drive letter)
1876 are interpreted relative to the directory containing the
1882 on a path name means that the rest of the file name
1883 is interpreted relative to
1884 the directory containing
1890 is followed by a directory separator character
1891 (slash or backslash).
1896 # The comments describing the targets that will be built
1897 # assume these calls are in a SConscript file in the
1898 # a subdirectory named "subdir".
1900 # Builds the program "subdir/foo" from "subdir/foo.c":
1901 env.Program('foo', 'foo.c')
1903 # Builds the program "/tmp/bar" from "subdir/bar.c":
1904 env.Program('/tmp/bar', 'bar.c')
1906 # An initial '#' or '#/' are equivalent; the following
1907 # calls build the programs "foo" and "bar" (in the
1908 # top-level SConstruct directory) from "subdir/foo.c" and
1909 # "subdir/bar.c", respectively:
1910 env.Program('#foo', 'foo.c')
1911 env.Program('#/bar', 'bar.c')
1913 # Builds the program "other/foo" (relative to the top-level
1914 # SConstruct directory) from "subdir/foo.c":
1915 env.Program('#other/foo', 'foo.c')
1918 When the target shares the same base name
1919 as the source and only the suffix varies,
1920 and if the builder method has a suffix defined for the target file type,
1921 then the target argument may be omitted completely,
1924 will deduce the target file name from
1925 the source file name.
1926 The following examples all build the
1932 (on Windows systems)
1933 from the bar.c source file:
1936 env.Program(target = 'bar', source = 'bar.c')
1937 env.Program('bar', source = 'bar.c')
1938 env.Program(source = 'bar.c')
1939 env.Program('bar.c')
1944 keyword argument may be specified
1945 when calling a Builder.
1947 all source file strings that are not absolute paths
1948 will be interpreted relative to the specified
1950 The following example will build the
1955 program from the files
1961 env.Program('build/prog', ['f1.c', 'f2.c'], srcdir='src')
1964 It is possible to override or add construction variables when calling a
1965 builder method by passing additional keyword arguments.
1966 These overridden or added
1967 variables will only be in effect when building the target, so they will not
1968 affect other parts of the build. For example, if you want to add additional
1969 libraries for just one program:
1972 env.Program('hello', 'hello.c', LIBS=['gl', 'glut'])
1975 or generate a shared library with a non-standard suffix:
1978 env.SharedLibrary('word', 'word.cpp',
1980 LIBSUFFIXES=['.ocx'])
1983 (Note that both the $SHLIBSUFFIX and $LIBSUFFIXES variables must be set
1984 if you want SCons to search automatically
1985 for dependencies on the non-standard library names;
1986 see the descriptions of these variables, below, for more information.)
1988 It is also possible to use the
1990 keyword argument in an override:
1993 env = Program('hello', 'hello.c', parse_flags = '-Iinclude -DEBUG -lm')
1996 This example adds 'include' to
2003 Although the builder methods defined by
2006 methods of a construction environment object,
2007 they may also be called without an explicit environment:
2010 Program('hello', 'hello.c')
2011 SharedLibrary('word', 'word.cpp')
2015 the methods are called internally using a default construction
2016 environment that consists of the tools and values that
2018 has determined are appropriate for the local system.
2020 Builder methods that can be called without an explicit
2021 environment may be called from custom Python modules that you
2022 import into an SConscript file by adding the following
2023 to the Python module:
2026 from SCons.Script import *
2029 All builder methods return a list-like object
2030 containing Nodes that
2031 represent the target or targets that will be built.
2034 is an internal SCons object
2036 build targets or sources.
2038 The returned Node-list object
2039 can be passed to other builder methods as source(s)
2040 or passed to any SCons function or method
2041 where a filename would normally be accepted.
2042 For example, if it were necessary
2045 flag when compiling one specific object file:
2048 bar_obj_list = env.StaticObject('bar.c', CPPDEFINES='-DBAR')
2049 env.Program(source = ['foo.c', bar_obj_list, 'main.c'])
2052 Using a Node in this way
2053 makes for a more portable build
2054 by avoiding having to specify
2055 a platform-specific object suffix
2056 when calling the Program() builder method.
2058 Note that Builder calls will automatically "flatten"
2059 the source and target file lists,
2060 so it's all right to have the bar_obj list
2061 return by the StaticObject() call
2062 in the middle of the source file list.
2063 If you need to manipulate a list of lists returned by Builders
2064 directly using Python,
2065 you can either build the list by hand:
2068 foo = Object('foo.c')
2069 bar = Object('bar.c')
2070 objects = ['begin.o'] + foo + ['middle.o'] + bar + ['end.o']
2071 for object in objects:
2077 function supplied by scons
2078 to create a list containing just the Nodes,
2079 which may be more convenient:
2082 foo = Object('foo.c')
2083 bar = Object('bar.c')
2084 objects = Flatten(['begin.o', foo, 'middle.o', bar, 'end.o'])
2085 for object in objects:
2089 Note also that because Builder calls return
2090 a list-like object, not an actual Python list,
2095 operator to append Builder results to a Python list.
2096 Because the list and the object are different types,
2097 Python will not update the original list in place,
2098 but will instead create a new Node-list object
2099 containing the concatenation of the list
2100 elements and the Builder results.
2101 This will cause problems for any other Python variables
2102 in your SCons configuration
2103 that still hold on to a reference to the original list.
2104 Instead, use the Python
2106 method to make sure the list is updated in-place.
2112 # Do NOT use += as follows:
2114 # object_files += Object('bar.c')
2116 # It will not update the object_files list in place.
2118 # Instead, use the .extend() method:
2119 object_files.extend(Object('bar.c'))
2123 The path name for a Node's file may be used
2124 by passing the Node to the Python-builtin
2129 bar_obj_list = env.StaticObject('bar.c', CPPDEFINES='-DBAR')
2130 print "The path to bar_obj is:", str(bar_obj_list[0])
2133 Note again that because the Builder call returns a list,
2134 we have to access the first element in the list
2135 .B (bar_obj_list[0])
2136 to get at the Node that actually represents
2139 Builder calls support a
2141 keyword argument that
2142 specifies that the Builder's action(s)
2144 after changing directory.
2148 a string or a directory Node,
2149 scons will change to the specified directory.
2152 is not a string or Node
2154 then scons will change to the
2155 target file's directory.
2158 # scons will change to the "sub" subdirectory
2159 # before executing the "cp" command.
2160 env.Command('sub/dir/foo.out', 'sub/dir/foo.in',
2161 "cp dir/foo.in dir/foo.out",
2164 # Because chdir is not a string, scons will change to the
2165 # target's directory ("sub/dir") before executing the
2167 env.Command('sub/dir/foo.out', 'sub/dir/foo.in',
2168 "cp foo.in foo.out",
2172 Note that scons will
2174 automatically modify
2176 construction variables like
2180 when using the chdir
2181 keyword argument--that is,
2182 the expanded file names
2183 will still be relative to
2184 the top-level SConstruct directory,
2185 and consequently incorrect
2186 relative to the chdir directory.
2187 If you use the chdir keyword argument,
2188 you will typically need to supply a different
2194 to use just the filename portion of the
2198 provides the following builder methods:
2200 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2201 '\" BEGIN GENERATED BUILDER DESCRIPTIONS
2203 '\" The descriptions below of the various SCons Builders are generated
2204 '\" from the .xml files that live next to the various Python modules in
2205 '\" the build enginer library. If you're reading this [gnt]roff file
2206 '\" with an eye towards patching this man page, you can still submit
2207 '\" a diff against this text, but it will have to be translated to a
2208 '\" diff against the underlying .xml file before the patch is actually
2209 '\" accepted. If you do that yourself, it will make it easier to
2210 '\" integrate the patch.
2212 '\" BEGIN GENERATED BUILDER DESCRIPTIONS
2213 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2215 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2216 '\" END GENERATED BUILDER DESCRIPTIONS
2218 '\" The descriptions above of the various SCons Builders are generated
2219 '\" from the .xml files that live next to the various Python modules in
2220 '\" the build enginer library. If you're reading this [gnt]roff file
2221 '\" with an eye towards patching this man page, you can still submit
2222 '\" a diff against this text, but it will have to be translated to a
2223 '\" diff against the underlying .xml file before the patch is actually
2224 '\" accepted. If you do that yourself, it will make it easier to
2225 '\" integrate the patch.
2227 '\" END GENERATED BUILDER DESCRIPTIONS
2228 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2232 targets of builder methods automatically depend on their sources.
2233 An explicit dependency can
2234 be specified using the
2236 method of a construction environment (see below).
2241 source files for various programming languages,
2242 so the dependencies do not need to be specified explicitly.
2243 By default, SCons can
2246 Fortran source files with
2248 (POSIX systems only),
2253 and assembly language files with
2255 (POSIX systems only),
2260 for C preprocessor dependencies.
2261 SCons also has default support
2262 for scanning D source files,
2263 You can also write your own Scanners
2264 to add support for additional source file types.
2265 These can be added to the default
2266 Scanner object used by the
2268 .BR StaticObject (),
2271 Builders by adding them
2273 .B SourceFileScanner
2276 See the section "Scanner Objects,"
2277 below, for a more information about
2278 defining your own Scanner objects.
2280 .SS Methods and Functions to Do Things
2281 In addition to Builder methods,
2283 provides a number of other construction environment methods
2284 and global functions to
2285 manipulate the build configuration.
2287 Usually, a construction environment method
2288 and global function with the same name both exist
2289 so that you don't have to remember whether
2290 to a specific bit of functionality
2291 must be called with or without a construction environment.
2292 In the following list,
2293 if you call something as a global function
2296 .RI Function( arguments )
2298 and if you call something through a construction
2299 environment it looks like:
2301 .RI env.Function( arguments )
2303 If you can call the functionality in both ways,
2304 then both forms are listed.
2306 Global functions may be called from custom Python modules that you
2307 import into an SConscript file by adding the following
2308 to the Python module:
2311 from SCons.Script import *
2314 Except where otherwise noted,
2316 construction environment method
2318 provide the exact same functionality.
2319 The only difference is that,
2321 calling the functionality through a construction environment will
2322 substitute construction variables into
2323 any supplied strings.
2327 env = Environment(FOO = 'foo')
2332 In the above example,
2333 the first call to the global
2335 function will actually add a target named
2337 to the list of default targets,
2338 while the second call to the
2340 construction environment method
2341 will expand the value
2342 and add a target named
2344 to the list of default targets.
2345 For more on construction variable expansion,
2346 see the next section on
2347 construction variables.
2349 Construction environment methods
2350 and global functions supported by
2354 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2356 .RI Action( action ", [" cmd/str/fun ", [" var ", ...]] [" option = value ", ...])"
2358 .IR env .Action( action ", [" cmd/str/fun ", [" var ", ...]] [" option = value ", ...])"
2359 Creates an Action object for
2362 See the section "Action Objects,"
2363 below, for a complete explanation of the arguments and behavior.
2367 form of the invocation will expand
2368 construction variables in any argument strings,
2371 argument, at the time it is called
2372 using the construction variables in the
2374 construction environment through which
2379 form delays all variable expansion
2380 until the Action object is actually used.
2382 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2384 .RI AddMethod( object, function ", [" name ])
2386 .RI env.AddMethod( function ", [" name ])
2387 When called with the
2394 as the specified method
2396 When called with the
2397 .BR env.AddMethod ()
2401 to the construction environment
2403 as the specified method
2412 itself is used for the method name.
2417 # Note that the first argument to the function to
2418 # be attached as a method must be the object through
2419 # which the method will be called; the Python
2420 # convention is to call it 'self'.
2421 def my_method(self, arg):
2422 print "my_method() got", arg
2424 # Use the global AddMethod() function to add a method
2425 # to the Environment class. This
2426 AddMethod(Environment, my_method)
2428 env.my_method('arg')
2430 # Add the function as a method, using the function
2431 # name for the method call.
2433 env.AddMethod(my_method, 'other_method_name')
2434 env.other_method_name('another arg')
2437 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2439 .RI AddOption( arguments )
2440 This function adds a new command-line option to be recognized.
2443 are the same as supported by the standard Python
2444 .BR optparse.add_option ()
2445 method (with a few additional capabilities noted below);
2446 see the documentation for
2448 for a thorough discussion of its option-processing capabities.
2449 (Note that although the
2451 module was not a standard module until Python 2.3,
2453 contains a compatible version of the module
2454 that is used to provide identical functionality
2455 when run by earlier Python versions.)
2457 In addition to the arguments and values supported by the
2458 .B optparse.add_option ()
2462 function allows you to set the
2466 (a string with just the question mark)
2467 to indicate that the specified long option(s) take(s) an
2477 may be used to supply the "default"
2478 value that should be used when the
2479 option is specified on the command line
2480 without an explicit argument.
2484 keyword argument is supplied when calling
2486 the option will have a default value of
2489 Once a new command-line option has been added with
2491 the option value may be accessed using
2494 .BR env.GetOption ().
2495 \" NOTE: in SCons 1.x or 2.0, user options will be settable, but not yet.
2496 \" Uncomment this when that works. See tigris issue 2105.
2497 \" The value may also be set, using
2500 \" .BR env.SetOption (),
2501 \" if conditions in a
2503 \" require overriding any default value.
2504 \" Note, however, that a
2505 \" value specified on the command line will
2507 \" override a value set by any SConscript file.
2511 strings for the new option(s)
2512 will be displayed by the
2517 (the latter only if no other help text is
2518 specified in the SConscript files).
2519 The help text for the local options specified by
2521 will appear below the SCons options themselves,
2525 The options will appear in the help text
2526 in the order in which the
2533 AddOption('--prefix',
2535 nargs=1, type='string',
2538 help='installation prefix')
2539 env = Environment(PREFIX = GetOption('prefix'))
2542 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2544 .RI AddPostAction( target ", " action )
2546 .RI env.AddPostAction( target ", " action )
2547 Arranges for the specified
2553 The specified action(s) may be
2554 an Action object, or anything that
2555 can be converted into an Action object
2558 When multiple targets are supplied,
2559 the action may be called multiple times,
2560 once after each action that generates
2561 one or more targets in the list.
2563 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2565 .RI AddPreAction( target ", " action )
2567 .RI env.AddPreAction( target ", " action )
2568 Arranges for the specified
2571 before the specified
2574 The specified action(s) may be
2575 an Action object, or anything that
2576 can be converted into an Action object
2579 When multiple targets are specified,
2580 the action(s) may be called multiple times,
2581 once before each action that generates
2582 one or more targets in the list.
2584 Note that if any of the targets are built in multiple steps,
2585 the action will be invoked just
2586 before the "final" action that specifically
2587 generates the specified target(s).
2588 For example, when building an executable program
2589 from a specified source
2591 file via an intermediate object file:
2594 foo = Program('foo.c')
2595 AddPreAction(foo, 'pre_action')
2600 would be executed before
2602 calls the link command that actually
2603 generates the executable program binary
2605 not before compiling the
2607 file into an object file.
2609 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2611 .RI Alias( alias ", [" targets ", [" action ]])
2613 .RI env.Alias( alias ", [" targets ", [" action ]])
2614 Creates one or more phony targets that
2615 expand to one or more other targets.
2620 can be specified that will be executed
2621 whenever the any of the alias targets are out-of-date.
2622 Returns the Node object representing the alias,
2623 which exists outside of any file system.
2624 This Node object, or the alias name,
2625 may be used as a dependency of any other target,
2626 including another alias.
2628 can be called multiple times for the same
2629 alias to add additional targets to the alias,
2630 or additional actions to the list for this alias.
2636 Alias('install', '/usr/bin')
2637 Alias(['install', 'install-lib'], '/usr/local/lib')
2639 env.Alias('install', ['/usr/local/bin', '/usr/local/lib'])
2640 env.Alias('install', ['/usr/local/man'])
2642 env.Alias('update', ['file1', 'file2'], "update_database $SOURCES")
2645 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2647 .RI AllowSubstExceptions([ exception ", ...])"
2648 Specifies the exceptions that will be allowed
2649 when expanding construction variables.
2651 any construction variable expansions that generate a
2655 exception will expand to a
2657 (a null string) and not cause scons to fail.
2658 All exceptions not in the specified list
2659 will generate an error message
2660 and terminate processing.
2663 .B AllowSubstExceptions
2664 is called multiple times,
2665 each call completely overwrites the previous list
2666 of allowed exceptions.
2671 # Requires that all construction variable names exist.
2672 # (You may wish to do this if you want to enforce strictly
2673 # that all construction variables must be defined before use.)
2674 AllowSubstExceptions()
2676 # Also allow a string containing a zero-division expansion
2677 # like '${1 / 0}' to evalute to ''.
2678 AllowSubstExceptions(IndexError, NameError, ZeroDivisionError)
2681 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2683 .RI AlwaysBuild( target ", ...)"
2685 .RI env.AlwaysBuild( target ", ...)"
2688 so that it is always assumed to be out of date,
2689 and will always be rebuilt if needed.
2692 does not add its target(s) to the default target list,
2693 so the targets will only be built
2694 if they are specified on the command line,
2695 or are a dependent of a target specified on the command line--but
2698 be built if so specified.
2699 Multiple targets can be passed in to a single call to
2702 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2704 .RI env.Append( key = val ", [...])"
2705 Appends the specified keyword arguments
2706 to the end of construction variables in the environment.
2707 If the Environment does not have
2708 the specified construction variable,
2709 it is simply added to the environment.
2710 If the values of the construction variable
2711 and the keyword argument are the same type,
2712 then the two values will be simply added together.
2713 Otherwise, the construction variable
2714 and the value of the keyword argument
2715 are both coerced to lists,
2716 and the lists are added together.
2717 (See also the Prepend method, below.)
2722 env.Append(CCFLAGS = ' -g', FOO = ['foo.yyy'])
2725 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2727 .RI env.AppendENVPath( name ", " newpath ", [" envname ", " sep ", " delete_existing ])
2728 This appends new path elements to the given path in the
2729 specified external environment
2733 any particular path once (leaving the last one it encounters and
2734 ignoring the rest, to preserve path order),
2735 and to help assure this,
2736 will normalize all paths (using
2739 .BR os.path.normcase ).
2740 This can also handle the
2741 case where the given old path variable is a list instead of a
2742 string, in which case a list will be returned instead of a string.
2746 is 0, then adding a path that already exists
2747 will not move it to the end; it will stay where it is in the list.
2752 print 'before:',env['ENV']['INCLUDE']
2753 include_path = '/foo/bar:/foo'
2754 env.AppendENVPath('INCLUDE', include_path)
2755 print 'after:',env['ENV']['INCLUDE']
2759 after: /biz:/foo/bar:/foo
2762 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2764 .RI env.AppendUnique( key = val ", [...], delete_existing=0)"
2765 Appends the specified keyword arguments
2766 to the end of construction variables in the environment.
2767 If the Environment does not have
2768 the specified construction variable,
2769 it is simply added to the environment.
2770 If the construction variable being appended to is a list,
2771 then any value(s) that already exist in the
2772 construction variable will
2774 be added again to the list.
2775 However, if delete_existing is 1,
2776 existing matching values are removed first, so
2777 existing values in the arg list move to the end of the list.
2782 env.AppendUnique(CCFLAGS = '-g', FOO = ['foo.yyy'])
2785 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2788 A factory function that
2789 returns a Builder object
2790 to be used to fetch source files
2792 The returned Builder
2793 is intended to be passed to the
2800 env.SourceCode('.', env.BitKeeper())
2803 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2805 .RI BuildDir( build_dir ", " src_dir ", [" duplicate ])
2807 .RI env.BuildDir( build_dir ", " src_dir ", [" duplicate ])
2808 Deprecated synonyms for
2811 .BR env.VariantDir ().
2814 argument becomes the
2819 .BR env.VariantDir ().
2821 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2823 .RI Builder( action ", [" arguments ])
2825 .RI env.Builder( action ", [" arguments ])
2826 Creates a Builder object for
2829 See the section "Builder Objects,"
2830 below, for a complete explanation of the arguments and behavior.
2834 form of the invocation will expand
2835 construction variables in any arguments strings,
2839 at the time it is called
2840 using the construction variables in the
2842 construction environment through which
2847 form delays all variable expansion
2848 until after the Builder object is actually called.
2850 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2852 .RI CacheDir( cache_dir )
2854 .RI env.CacheDir( cache_dir )
2857 will maintain a cache of derived files in
2859 The derived files in the cache will be shared
2860 among all the builds using the same
2867 disables derived file caching.
2871 will only affect targets built
2872 through the specified construction environment.
2875 sets a global default
2876 that will be used by all targets built
2877 through construction environments
2888 finds a derived file that needs to be rebuilt,
2889 it will first look in the cache to see if a
2890 derived file has already been built
2891 from identical input files and an identical build action
2892 (as incorporated into the MD5 build signature).
2895 will retrieve the file from the cache.
2896 If the derived file is not present in the cache,
2899 then place a copy of the built file in the cache
2900 (identified by its MD5 build signature),
2901 so that it may be retrieved by other
2902 builds that need to build the same derived file
2903 from identical inputs.
2907 may be disabled for any invocation
2916 will place a copy of
2918 derived files in the cache,
2919 even if they already existed
2920 and were not built by this invocation.
2921 This is useful to populate a cache
2924 is added to a build,
2933 "Retrieved `file' from cache,"
2936 option is being used.
2941 will print the action that
2943 have been used to build the file,
2944 without any indication that
2945 the file was actually retrieved from the cache.
2946 This is useful to generate build logs
2947 that are equivalent regardless of whether
2948 a given derived file has been built in-place
2949 or retrieved from the cache.
2953 method can be used to disable caching of specific files. This can be
2954 useful if inputs and/or outputs of some tool are impossible to
2955 predict or prohibitively large.
2957 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2959 .RI Clean( targets ", " files_or_dirs )
2961 .RI env.Clean( targets ", " files_or_dirs )
2962 This specifies a list of files or directories which should be removed
2963 whenever the targets are specified with the
2965 command line option.
2966 The specified targets may be a list
2967 or an individual target.
2971 and create new targets or add files and directories to the
2972 clean list for the specified targets.
2974 Multiple files or directories should be specified
2975 either as separate arguments to the
2977 method, or as a list.
2979 will also accept the return value of any of the construction environment
2985 function overrides calling
2987 for the same target,
2988 and any targets passed to both functions will
2997 Clean('foo', ['bar', 'baz'])
2998 Clean('dist', env.Program('hello', 'hello.c'))
2999 Clean(['foo', 'bar'], 'something_else_to_clean')
3002 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3004 .RI Command( target ", " source ", " action ", [" key = val ", ...])"
3006 .RI env.Command( target ", " source ", " action ", [" key = val ", ...])"
3007 Executes a specific action
3008 (or list of actions)
3009 to build a target file or files.
3010 This is more convenient
3011 than defining a separate Builder object
3012 for a single special-case build.
3014 As a special case, the
3016 keyword argument can
3019 that will be used to scan the sources.
3023 if any of the sources will be directories
3024 that must be scanned on-disk for
3025 changes to files that aren't
3026 already specified in other Builder of function calls.)
3028 Any other keyword arguments specified override any
3029 same-named existing construction variables.
3031 An action can be an external command,
3032 specified as a string,
3033 or a callable Python object;
3034 see "Action Objects," below,
3035 for more complete information.
3036 Also note that a string specifying an external command
3037 may be preceded by an
3040 to suppress printing the command in question,
3044 to ignore the exit status of the external command.
3049 env.Command('foo.out', 'foo.in',
3050 "$FOO_BUILD < $SOURCES > $TARGET")
3052 env.Command('bar.out', 'bar.in',
3054 "$BAR_BUILD < $SOURCES > $TARGET"],
3055 ENV = {'PATH' : '/usr/local/bin/'})
3057 def rename(env, target, source):
3059 os.rename('.tmp', str(target[0]))
3061 env.Command('baz.out', 'baz.in',
3062 ["$BAZ_BUILD < $SOURCES > .tmp",
3069 function will usually assume, by default,
3070 that the specified targets and/or sources are Files,
3071 if no other part of the configuration
3072 identifies what type of entry it is.
3073 If necessary, you can explicitly specify
3074 that targets or source nodes should
3075 be treated as directoriese
3085 env.Command('ddd.list', Dir('ddd'), 'ls -l $SOURCE > $TARGET')
3087 env['DISTDIR'] = 'destination/directory'
3088 env.Command(env.Dir('$DISTDIR')), None, make_distdir)
3092 (Also note that SCons will usually
3093 automatically create any directory necessary to hold a target file,
3094 so you normally don't need to create directories by hand.)
3096 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3098 .RI Configure( env ", [" custom_tests ", " conf_dir ", " log_file ", " config_h ])
3100 .RI env.Configure([ custom_tests ", " conf_dir ", " log_file ", " config_h ])
3101 Creates a Configure object for integrated
3102 functionality similar to GNU autoconf.
3103 See the section "Configure Contexts,"
3104 below, for a complete explanation of the arguments and behavior.
3106 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3108 .RI env.Clone([ key = val ", ...])"
3109 Return a separate copy of a construction environment.
3110 If there are any keyword arguments specified,
3111 they are added to the returned copy,
3112 overwriting any existing values
3119 env3 = env.Clone(CCFLAGS = '-g')
3122 Additionally, a list of tools and a toolpath may be specified, as in
3123 the Environment constructor:
3126 def MyTool(env): env['FOO'] = 'bar'
3127 env4 = env.Clone(tools = ['msvc', MyTool])
3132 keyword argument is also recognized:
3135 # create an environment for compiling programs that use wxWidgets
3136 wx_env = env.Clone(parse_flags = '!wx-config --cflags --cxxflags')
3139 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3141 .RI env.Copy([ key = val ", ...])"
3142 A now-deprecated synonym for
3145 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3147 .RI env.CVS( repository ", " module )
3148 A factory function that
3149 returns a Builder object
3150 to be used to fetch source files
3154 The returned Builder
3155 is intended to be passed to the
3159 The optional specified
3161 will be added to the beginning
3162 of all repository path names;
3163 this can be used, in essence,
3164 to strip initial directory names
3165 from the repository path names,
3166 so that you only have to
3167 replicate part of the repository
3168 directory hierarchy in your
3169 local build directory.
3174 # Will fetch foo/bar/src.c
3175 # from /usr/local/CVSROOT/foo/bar/src.c.
3176 env.SourceCode('.', env.CVS('/usr/local/CVSROOT'))
3178 # Will fetch bar/src.c
3179 # from /usr/local/CVSROOT/foo/bar/src.c.
3180 env.SourceCode('.', env.CVS('/usr/local/CVSROOT', 'foo'))
3183 # from /usr/local/CVSROOT/foo/bar/src.c.
3184 env.SourceCode('.', env.CVS('/usr/local/CVSROOT', 'foo/bar'))
3187 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3189 .RI Decider( function )
3191 .RI env.Decider( function )
3192 Specifies that all up-to-date decisions for
3193 targets built through this construction environment
3194 will be handled by the specified
3198 can be one of the following strings
3199 that specify the type of decision function
3205 Specifies that a target shall be considered out of date and rebuilt
3206 if the dependency's timestamp is newer than the target file's timestamp.
3207 This is the behavior of the classic Make utility,
3210 can be used a synonym for
3211 .BR timestamp-newer .
3215 Specifies that a target shall be considered out of date and rebuilt
3216 if the dependency's timestamp is different than the
3217 timestamp recorded the last time the target was built.
3218 This provides behavior very similar to the classic Make utility
3219 (in particular, files are not opened up so that their
3220 contents can be checksummed)
3221 except that the target will also be rebuilt if a
3222 dependency file has been restored to a version with an
3224 timestamp, such as can happen when restoring files from backup archives.
3228 Specifies that a target shall be considered out of date and rebuilt
3229 if the dependency's content has changed sine the last time
3230 the target was built,
3231 as determined be performing an MD5 checksum
3232 on the dependency's contents
3233 and comparing it to the checksum recorded the
3234 last time the target was built.
3236 can be used as a synonym for
3241 Specifies that a target shall be considered out of date and rebuilt
3242 if the dependency's content has changed sine the last time
3243 the target was built,
3244 except that dependencies with a timestamp that matches
3245 the last time the target was rebuilt will be
3246 assumed to be up-to-date and
3249 This provides behavior very similar
3252 behavior of always checksumming file contents,
3253 with an optimization of not checking
3254 the contents of files whose timestamps haven't changed.
3255 The drawback is that SCons will
3257 detect if a file's content has changed
3258 but its timestamp is the same,
3259 as might happen in an automated script
3262 and runs the build again,
3263 all within a single second.
3270 # Use exact timestamp matches by default.
3271 Decider('timestamp-match')
3273 # Use MD5 content signatures for any targets built
3274 # with the attached construction environment.
3275 env.Decider('content')
3279 In addition to the above already-available functions,
3282 argument may be an actual Python function
3283 that takes the following three arguments:
3287 The Node (file) which
3291 if it has "changed" since the last tme
3292 .I target was built.
3295 The Node (file) being built.
3297 this is what should get rebuilt
3303 Stored information about the state of the
3308 This can be consulted to match various
3309 file characteristics
3310 such as the timestamp,
3311 size, or content signature.
3322 has "changed" since the last time
3326 (indicating that the target
3333 (indicating that the target should
3336 Note that the decision can be made
3337 using whatever criteria are appopriate.
3338 Ignoring some or all of the function arguments
3339 is perfectly normal.
3344 def my_decider(dependency, target, prev_ni):
3345 return not os.path.exists(str(target))
3347 env.Decider(my_decider)
3350 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3352 .RI Default( targets )
3354 .RI env.Default( targets )
3355 This specifies a list of default targets,
3356 which will be built by
3358 if no explicit targets are given on the command line.
3362 and add to the list of default targets.
3364 Multiple targets should be specified as
3365 separate arguments to the
3367 method, or as a list.
3369 will also accept the Node returned by any
3370 of a construction environment's
3376 Default('foo', 'bar', 'baz')
3377 env.Default(['a', 'b', 'c'])
3378 hello = env.Program('hello', 'hello.c')
3386 will clear all default targets.
3389 will add to the (now empty) default-target list
3392 The current list of targets added using the
3394 function or method is available in the
3399 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3401 .RI DefaultEnvironment([ args ])
3402 Creates and returns a default construction environment object.
3403 This construction environment is used internally by SCons
3404 in order to execute many of the global functions in this list,
3405 and to fetch source files transparently
3406 from source code management systems.
3408 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3410 .RI Depends( target ", " dependency )
3412 .RI env.Depends( target ", " dependency )
3413 Specifies an explicit dependency;
3425 (usually the path name of a file or directory)
3427 or a list of strings or Node objects
3428 (such as returned by a Builder call).
3429 This should only be necessary
3430 for cases where the dependency
3431 is not caught by a Scanner
3437 env.Depends('foo', 'other-input-file-for-foo')
3439 mylib = env.Library('mylib.c')
3440 installed_lib = env.Install('lib', mylib)
3441 bar = env.Program('bar.c')
3443 # Arrange for the library to be copied into the installation
3444 # directory before trying to build the "bar" program.
3445 # (Note that this is for example only. A "real" library
3446 # dependency would normally be configured through the $LIBS
3447 # and $LIBPATH variables, not using an env.Depends() call.)
3449 env.Depends(bar, installed_lib)
3452 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3454 .RI env.Dictionary([ vars ])
3455 Returns a dictionary object
3456 containing copies of all of the
3457 construction variables in the environment.
3458 If there are any variable names specified,
3459 only the specified construction
3460 variables are returned in the dictionary.
3465 dict = env.Dictionary()
3466 cc_dict = env.Dictionary('CC', 'CCFLAGS', 'CCCOM')
3469 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3471 .RI Dir( name ", [" directory ])
3473 .RI env.Dir( name ", [" directory ])
3474 This returns a Directory Node,
3475 an object that represents the specified directory
3478 can be a relative or absolute path.
3480 is an optional directory that will be used as the parent directory.
3483 is specified, the current script's directory is used as the parent.
3487 is a list, SCons returns a list of Dir nodes.
3488 Construction variables are expanded in
3491 Directory Nodes can be used anywhere you
3492 would supply a string as a directory name
3493 to a Builder method or function.
3494 Directory Nodes have attributes and methods
3495 that are useful in many situations;
3496 see "File and Directory Nodes," below.
3498 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3500 .RI env.Dump([ key ])
3501 Returns a pretty printable representation of the environment.
3505 should be a string containing the name of the variable of interest.
3510 print env.Dump('CCCOM')
3515 \&'$CC $CCFLAGS $CPPFLAGS $_CPPDEFFLAGS $_CPPINCFLAGS -c -o $TARGET $SOURCES'
3526 'ARCOM': '$AR $ARFLAGS $TARGET $SOURCES\n$RANLIB $RANLIBFLAGS $TARGET',
3529 'ASCOM': '$AS $ASFLAGS -o $TARGET $SOURCES',
3534 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3536 .RI EnsurePythonVersion( major ", " minor )
3538 .RI env.EnsurePythonVersion( major ", " minor )
3539 Ensure that the Python version is at least
3542 print out an error message and exit SCons with a non-zero exit code if the
3543 actual Python version is not late enough.
3548 EnsurePythonVersion(2,2)
3551 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3553 .RI EnsureSConsVersion( major ", " minor ", [" revision ])
3555 .RI env.EnsureSConsVersion( major ", " minor ", [" revision ])
3556 Ensure that the SCons version is at least
3559 .IR major.minor.revision .
3564 print out an error message and exit SCons with a non-zero exit code if the
3565 actual SCons version is not late enough.
3570 EnsureSConsVersion(0,14)
3572 EnsureSConsVersion(0,96,90)
3575 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3577 .RI Environment([ key = value ", ...])"
3579 .RI env.Environment([ key = value ", ...])"
3580 Return a new construction environment
3581 initialized with the specified
3585 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3587 .RI Execute( action ", [" strfunction ", " varlist ])
3589 .RI env.Execute( action ", [" strfunction ", " varlist ])
3590 Executes an Action object.
3593 may be an Action object
3594 (see the section "Action Objects,"
3595 below, for a complete explanation of the arguments and behavior),
3596 or it may be a command-line string,
3598 or executable Python function,
3599 each of which will be converted
3600 into an Action object
3602 The exit value of the command
3603 or return value of the Python function
3608 will print an error message if the executed
3611 exits with or returns a non-zero value.
3616 automatically terminate the build
3620 If you want the build to stop in response to a failed
3623 you must explicitly check for a non-zero return value:
3626 Execute(Copy('file.out', 'file.in'))
3628 if Execute("mkdir sub/dir/ectory"):
3629 # The mkdir failed, don't try to build.
3633 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3637 .RI env.Exit([ value ])
3643 A default exit value of
3646 is used if no value is specified.
3648 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3652 .RI env.Export( vars )
3655 to export a list of variables from the current
3656 SConscript file to all other SConscript files.
3657 The exported variables are kept in a global collection,
3658 so subsequent calls to
3660 will over-write previous exports that have the same name.
3661 Multiple variable names can be passed to
3663 as separate arguments or as a list. A dictionary can be used to map
3664 variables to a different name when exported. Both local variables and
3665 global variables can be exported.
3671 # Make env available for all SConscript files to Import().
3675 # Make env and package available for all SConscript files:.
3676 Export("env", "package")
3678 # Make env and package available for all SConscript files:
3679 Export(["env", "package"])
3681 # Make env available using the name debug:.
3682 Export({"debug":env})
3688 function supports an
3690 argument that makes it easier to to export a variable or
3691 set of variables to a single SConscript file.
3692 See the description of the
3696 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3698 .RI File( name ", [" directory ])
3700 .RI env.File( name ", [" directory ])
3703 an object that represents the specified file
3706 can be a relative or absolute path.
3708 is an optional directory that will be used as the parent directory.
3712 is a list, SCons returns a list of File nodes.
3713 Construction variables are expanded in
3716 File Nodes can be used anywhere you
3717 would supply a string as a file name
3718 to a Builder method or function.
3719 File Nodes have attributes and methods
3720 that are useful in many situations;
3721 see "File and Directory Nodes," below.
3723 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3725 .RI FindFile( file ", " dirs )
3727 .RI env.FindFile( file ", " dirs )
3730 in the path specified by
3733 may be a list of directory names or a single directory name.
3734 In addition to searching for files that exist in the filesytem,
3735 this function also searches for derived files
3736 that have not yet been built.
3741 foo = env.FindFile('foo', ['dir1', 'dir2'])
3744 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3746 .RI FindInstalledFiles( )
3748 .RI env.FindInstalledFiles( )
3749 Returns the list of targets set up by the
3755 This function serves as a convenient method to select the contents of
3761 Install( '/bin', [ 'executable_a', 'executable_b' ] )
3763 # will return the file node list
3764 # [ '/bin/executable_a', '/bin/executable_b' ]
3765 FindInstalledFiles()
3767 Install( '/lib', [ 'some_library' ] )
3769 # will return the file node list
3770 # [ '/bin/executable_a', '/bin/executable_b', '/lib/some_library' ]
3771 FindInstalledFiles()
3774 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3776 .RI FindSourceFiles( node = '"."' )
3778 .RI env.FindSourceFiles( node = '"."' )
3780 Returns the list of nodes which serve as the source of the built files.
3781 It does so by inspecting the dependency tree starting at the optional
3784 which defaults to the '"."'-node. It will then return all leaves of
3786 These are all children which have no further children.
3788 This function is a convenient method to select the contents of a Source
3794 Program( 'src/main_a.c' )
3795 Program( 'src/main_b.c' )
3796 Program( 'main_c.c' )
3798 # returns ['main_c.c', 'src/main_a.c', 'SConstruct', 'src/main_b.c']
3801 # returns ['src/main_b.c', 'src/main_a.c' ]
3802 FindSourceFiles( 'src' )
3806 As you can see build support files (SConstruct in the above example)
3807 will also be returned by this function.
3809 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3811 .RI FindPathDirs( variable )
3813 (actually a callable Python object)
3814 intended to be used as the
3816 of a Scanner object.
3817 The returned object will look up the specified
3819 in a construction environment
3820 and treat the construction variable's value as a list of
3821 directory paths that should be searched
3829 is generally preferable to
3832 for the following reasons:
3833 1) The returned list will contain all appropriate directories
3834 found in source trees
3838 or in code repositories
3844 2) scons will identify expansions of
3846 that evaluate to the same list of directories as,
3847 in fact, the same list,
3848 and avoid re-scanning the directories for files,
3854 def my_scan(node, env, path, arg):
3855 # Code to scan file contents goes here...
3856 return include_files
3858 scanner = Scanner(name = 'myscanner',
3860 path_function = FindPathDirs('MYPATH'))
3863 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3865 .RI Flatten( sequence )
3867 .RI env.Flatten( sequence )
3868 Takes a sequence (that is, a Python list or tuple)
3869 that may contain nested sequences
3870 and returns a flattened list containing
3871 all of the individual elements in any sequence.
3872 This can be helpful for collecting
3873 the lists returned by calls to Builders;
3874 other Builders will automatically
3875 flatten lists specified as input,
3876 but direct Python manipulation of
3877 these lists does not.
3882 foo = Object('foo.c')
3883 bar = Object('bar.c')
3885 # Because `foo' and `bar' are lists returned by the Object() Builder,
3886 # `objects' will be a list containing nested lists:
3887 objects = ['f1.o', foo, 'f2.o', bar, 'f3.o']
3889 # Passing such a list to another Builder is all right because
3890 # the Builder will flatten the list automatically:
3891 Program(source = objects)
3893 # If you need to manipulate the list directly using Python, you need to
3894 # call Flatten() yourself, or otherwise handle nested lists:
3895 for object in Flatten(objects):
3899 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3901 .RI GetBuildFailures()
3902 Returns a list of exceptions for the
3903 actions that failed while
3904 attempting to build targets.
3905 Each element in the returned list is a
3908 with the following attributes
3909 that record various aspects
3910 of the build failure:
3913 The node that was being built
3914 when the build failure occurred.
3917 The numeric exit status
3918 returned by the command or Python function
3919 that failed when trying to build the
3923 The SCons error string
3924 describing the build failure.
3925 (This is often a generic
3926 message like "Error 2"
3927 to indicate that an executed
3928 command exited with a status of 2.)
3931 The name of the file or
3932 directory that actually caused the failure.
3933 This may be different from the
3937 if an attempt to build a target named
3941 directory could not be created,
3952 The SCons Executor object
3955 This can be used to retrieve
3956 the construction environment used
3957 for the failed action.
3960 The actual SCons Action object that failed.
3961 This will be one specific action
3962 out of the possible list of
3963 actions that would have been
3964 executed to build the target.
3967 The actual expanded command that was executed and failed,
3971 and other construction variables.
3974 .BR GetBuildFailures ()
3976 will always return an empty list
3977 until any build failure has occurred,
3979 .BR GetBuildFailures ()
3980 will always return an empty list
3983 files are being read.
3984 Its primary intended use is
3985 for functions that will be
3986 executed before SCons exits
3987 by passing them to the
3989 .BR atexit.register ()
3996 def print_build_failures():
3997 from SCons.Script import GetBuildFailures
3998 for bf in GetBuildFailures():
3999 print "%s failed: %s" % (bf.node, bf.errstr)
4001 atexit.register(print_build_failures)
4004 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4006 .RI GetBuildPath( file ", [" ... ])
4008 .RI env.GetBuildPath( file ", [" ... ])
4011 path name (or names) for the specified
4019 Nodes or strings representing path names.
4021 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4025 .RI env.GetLaunchDir()
4026 Returns the absolute path name of the directory from which
4028 was initially invoked.
4029 This can be useful when using the
4034 options, which internally
4035 change to the directory in which the
4039 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4041 .RI GetOption( name )
4043 .RI env.GetOption( name )
4044 This function provides a way to query the value of
4045 SCons options set on scons command line
4049 The options supported are:
4054 which corresponds to --cache-debug;
4057 which corresponds to --cache-disable;
4060 which corresponds to --cache-force;
4063 which corresponds to --cache-show;
4066 which corresponds to -c, --clean and --remove;
4069 which corresponds to --config;
4072 which corresponds to -C and --directory;
4075 which corresponds to --diskcheck
4078 which corresponds to --duplicate;
4081 which corresponds to -f, --file, --makefile and --sconstruct;
4084 which corresponds to -h and --help;
4087 which corresponds to --ignore-errors;
4090 which corresponds to --implicit-cache;
4092 .B implicit_deps_changed
4093 which corresponds to --implicit-deps-changed;
4095 .B implicit_deps_unchanged
4096 which corresponds to --implicit-deps-unchanged;
4099 which corresponds to --interact and --interactive;
4102 which corresponds to -k and --keep-going;
4105 which corresponds to --max-drift;
4108 which corresponds to -n, --no-exec, --just-print, --dry-run and --recon;
4111 which corresponds to --no-site-dir;
4114 which corresponds to -j and --jobs;
4117 which corresponds to --profile;
4120 which corresponds to -q and --question;
4123 which corresponds to --random;
4126 which corresponds to -Y, --repository and --srcdir;
4129 which corresponds to -s, --silent and --quiet;
4132 which corresponds to --site-dir;
4135 which corresponds to --stack-size;
4137 .B taskmastertrace_file
4138 which corresponds to --taskmastertrace; and
4141 which corresponds to --warn and --warning.
4145 See the documentation for the
4146 corresponding command line object for information about each specific
4149 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4151 .RI Glob( pattern ", [" ondisk ", " source ", " strings ])
4153 .RI env.Glob( pattern ", [" ondisk ", " source ", " strings ])
4154 Returns Nodes (or strings) that match the specified
4156 relative to the directory of the current
4161 form performs string substition on
4163 and returns whatever matches
4164 the resulting expanded pattern.
4168 uses Unix shell style metacharacters for matching:
4171 * matches everything
4172 ? matches any single character
4173 [seq] matches any character in seq
4174 [!seq] matches any char not in seq
4178 Character matches do
4180 span directory separators.
4189 and source directories
4194 returns a Node (or string, if so configured)
4195 in the local (SConscript) directory
4196 if matching Node is found
4197 anywhere in a corresponding
4198 repository or source directory.
4202 argument may be set to
4204 (or any other non-true value)
4205 to disable the search for matches on disk,
4206 thereby only returning matches among
4207 already-configured File or Dir Nodes.
4208 The default behavior is to
4209 return corresponding Nodes
4210 for any on-disk matches found.
4214 argument may be set to
4216 (or any equivalent value)
4218 when the local directory is a
4220 the returned Nodes should be from the
4221 corresponding source directory,
4222 not the local directory.
4226 argument may be set to
4228 (or any equivalent value)
4231 function return strings, not Nodes,
4232 that represent the matched files or directories.
4233 The returned strings will be relative to
4234 the local (SConscript) directory.
4235 (Note that This may make it easier to perform
4236 arbitrary manipulation of file names,
4237 but if the returned strings are
4238 passed to a different
4241 any Node translation will be relative
4252 Program('foo', Glob('*.c'))
4255 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4257 '\".RI GlobalBuilders( flag )
4261 '\"adds the names of the default builders
4262 '\"(Program, Library, etc.)
4263 '\"to the global name space
4264 '\"so they can be called without an explicit construction environment.
4265 '\"(This is the default.)
4269 '\"the names of the default builders are removed
4270 '\"from the global name space
4271 '\"so that an explicit construction environment is required
4272 '\"to call all builders.
4274 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4278 .RI env.Help( text )
4279 This specifies help text to be printed if the
4281 argument is given to
4285 is called multiple times, the text is appended together in the order
4290 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4292 .RI Ignore( target ", " dependency )
4294 .RI env.Ignore( target ", " dependency )
4295 The specified dependency file(s)
4296 will be ignored when deciding if
4297 the target file(s) need to be rebuilt.
4301 to remove a target from the default build.
4302 In order to do this you must specify the directory the target will
4303 be built in as the target, and the file you want to skip building
4306 Note that this will only remove the dependencies listed from
4307 the files built by default. It will still be built if that
4308 dependency is needed by another object being built.
4309 See the third and forth examples below.
4314 env.Ignore('foo', 'foo.c')
4315 env.Ignore('bar', ['bar1.h', 'bar2.h'])
4316 env.Ignore('.','foobar.obj')
4317 env.Ignore('bar','bar/foobar.obj')
4320 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4324 .RI env.Import( vars )
4327 to import a list of variables into the current SConscript file. This
4328 will import variables that were exported with
4334 Variables exported by
4337 Multiple variable names can be passed to
4339 as separate arguments or as a list. The variable "*" can be used
4340 to import all variables.
4346 Import("env", "variable")
4347 Import(["env", "variable"])
4351 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4353 .RI Literal( string )
4355 .RI env.Literal( string )
4358 will be preserved as-is
4359 and not have construction variables expanded.
4361 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4363 .RI Local( targets )
4365 .RI env.Local( targets )
4368 will have copies made in the local tree,
4369 even if an already up-to-date copy
4370 exists in a repository.
4371 Returns a list of the target Node or Nodes.
4373 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4375 \" .RI env.MergeShellPaths( arg ", [" prepend ])
4376 \" Merges the elements of the specified
4378 \" which must be a dictionary, to the construction
4379 \" environment's copy of the shell environment
4381 \" (This is the environment which is passed
4382 \" to subshells spawned by SCons.)
4385 \" must be a single value,
4386 \" so multiple strings must
4387 \" be passed in as a list,
4388 \" not as separate arguments to
4389 \" .BR env.MergeShellPaths ().
4391 \" New values are prepended to the environment variable by default,
4392 \" unless prepend=0 is specified.
4393 \" Duplicate values are always eliminated,
4394 \" since this function calls
4397 \" .B PrependENVPath
4400 \" argument. See those functions for more details.
4405 \" # Prepend a path to the shell PATH.
4406 \" env.MergeShellPaths({'PATH':'/usr/local/bin'} )
4407 \" # Append two dirs to the shell INCLUDE.
4408 \" env.MergeShellPaths({'INCLUDE':['c:/inc1', 'c:/inc2']}, prepend=0 )
4412 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4414 .RI env.MergeFlags( arg ", [" unique ])
4415 Merges the specified
4417 values to the construction environment's construction variables.
4420 argument is not a dictionary,
4421 it is converted to one by calling
4424 before the values are merged.
4427 must be a single value,
4428 so multiple strings must
4429 be passed in as a list,
4430 not as separate arguments to
4431 .BR env.MergeFlags ().
4434 duplicate values are eliminated;
4435 you can, however, specify
4439 When eliminating duplicate values,
4440 any construction variables that end with
4443 keep the left-most unique value.
4444 All other construction variables keep
4445 the right-most unique value.
4450 # Add an optimization flag to $CCFLAGS.
4451 env.MergeFlags('-O3')
4453 # Combine the flags returned from running pkg-config with an optimization
4454 # flag and merge the result into the construction variables.
4455 env.MergeFlags(['!pkg-config gtk+-2.0 --cflags', '-O3'])
4457 # Combine an optimization flag with the flags returned from running pkg-config
4458 # twice and merge the result into the construction variables.
4459 env.MergeFlags(['-O3',
4460 '!pkg-config gtk+-2.0 --cflags --libs',
4461 '!pkg-config libpng12 --cflags --libs'])
4464 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4466 .RI NoCache( target ", ...)"
4468 .RI env.NoCache( target ", ...)"
4469 Specifies a list of files which should
4471 be cached whenever the
4473 method has been activated.
4474 The specified targets may be a list
4475 or an individual target.
4477 Multiple files should be specified
4478 either as separate arguments to the
4480 method, or as a list.
4482 will also accept the return value of any of the construction environment
4487 on directories and other non-File Node types has no effect because
4488 only File Nodes are cached.
4494 NoCache(env.Program('hello', 'hello.c'))
4497 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4499 .RI NoClean( target ", ...)"
4501 .RI env.NoClean( target ", ...)"
4502 Specifies a list of files or directories which should
4504 be removed whenever the targets (or their dependencies)
4505 are specified with the
4507 command line option.
4508 The specified targets may be a list
4509 or an individual target.
4513 and prevent each specified target
4514 from being removed by calls to the
4518 Multiple files or directories should be specified
4519 either as separate arguments to the
4521 method, or as a list.
4523 will also accept the return value of any of the construction environment
4528 for a target overrides calling
4530 for the same target,
4531 and any targets passed to both functions will
4541 NoClean(env.Program('hello', 'hello.c'))
4544 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4546 .RI env.ParseConfig( command ", [" function ", " unique ])
4549 to modify the environment as specified by the output of
4554 .BR env.MergeFlags (),
4555 which expects the output of a typical
4559 and adds the options
4560 to the appropriate construction variables.
4562 duplicate values are not
4563 added to any construction variables;
4570 and the construction variables they affect
4571 are as specified for the
4572 .BR env.ParseFlags ()
4573 method (which this method calls).
4574 See that method's description, below,
4575 for a table of options and construction variables.
4577 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4579 .RI ParseDepends( filename ", [" must_exist ", " only_one ])
4581 .RI env.ParseDepends( filename ", [" must_exist ", " only_one ])
4582 Parses the contents of the specified
4584 as a list of dependencies in the style of
4588 and explicitly establishes all of the listed dependencies.
4597 argument may be set to a non-zero
4600 throw an exception and
4601 generate an error if the file does not exist,
4602 or is otherwise inaccessible.
4606 argument may be set to a non-zero
4609 thrown an exception and
4611 if the file contains dependency
4612 information for more than one target.
4613 This can provide a small sanity check
4614 for files intended to be generated
4615 by, for example, the
4618 which should typically only
4619 write dependency information for
4620 one output file into a corresponding
4626 and all of the files listed therein
4627 will be interpreted relative to
4628 the directory of the
4630 file which calls the
4634 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4636 .RI env.ParseFlags( flags ", ...)"
4637 Parses one or more strings containing
4638 typical command-line flags for GCC tool chains
4639 and returns a dictionary with the flag values
4640 separated into the appropriate SCons construction variables.
4641 This is intended as a companion to the
4642 .BR env.MergeFlags ()
4643 method, but allows for the values in the returned dictionary
4644 to be modified, if necessary,
4645 before merging them into the construction environment.
4647 .BR env.MergeFlags ()
4648 will call this method if its argument is not a dictionary,
4649 so it is usually not necessary to call
4650 .BR env.ParseFlags ()
4651 directly unless you want to manipulate the values.)
4653 If the first character in any string is
4654 an exclamation mark (!),
4655 the rest of the string is executed as a command,
4656 and the output from the command is
4657 parsed as GCC tool chain command-line flags
4658 and added to the resulting dictionary.
4660 Flag values are translated accordig to the prefix found,
4661 and added to the following construction variables:
4664 -arch CCFLAGS, LINKFLAGS
4666 -framework FRAMEWORKS
4667 -frameworkdir= FRAMEWORKPATH
4669 -isysroot CCFLAGS, LINKFLAGS
4673 -mno-cygwin CCFLAGS, LINKFLAGS
4675 -pthread CCFLAGS, LINKFLAGS
4677 -Wa, ASFLAGS, CCFLAGS
4684 + CCFLAGS, LINKFLAGS
4688 Any other strings not associated with options
4689 are assumed to be the names of libraries
4692 construction variable.
4694 Examples (all of which produce the same result):
4697 dict = env.ParseFlags('-O2 -Dfoo -Dbar=1')
4698 dict = env.ParseFlags('-O2', '-Dfoo', '-Dbar=1')
4699 dict = env.ParseFlags(['-O2', '-Dfoo -Dbar=1'])
4700 dict = env.ParseFlags('-O2', '!echo -Dfoo -Dbar=1')
4703 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4706 A factory function that
4707 returns a Builder object
4708 to be used to fetch source files
4709 from the Perforce source code management system.
4710 The returned Builder
4711 is intended to be passed to the
4718 env.SourceCode('.', env.Perforce())
4721 Perforce uses a number of external
4722 environment variables for its operation.
4723 Consequently, this function adds the
4724 following variables from the user's external environment
4725 to the construction environment's
4738 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4740 .RI Platform( string )
4741 Returns a callable object
4742 that can be used to initialize
4743 a construction environment using the
4744 platform keyword of the Environment() method.
4749 env = Environment(platform = Platform('win32'))
4752 .RI env.Platform( string )
4753 Applies the callable object for the specified platform
4755 to the environment through which the method was called.
4758 env.Platform('posix')
4767 variables from the user's external environment
4768 to the construction environment's
4771 This is so that any executed commands
4772 that use sockets to connect with other systems
4773 (such as fetching source files from
4774 external CVS repository specifications like
4775 .BR :pserver:anonymous@cvs.sourceforge.net:/cvsroot/scons )
4776 will work on Windows systems.
4778 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4780 .RI Progress( callable ", [" interval ])
4782 .RI Progress( string ", [" interval ", " file ", " overwrite ])
4784 .RI Progress( list_of_strings ", [" interval ", " file ", " overwrite ])
4785 Allows SCons to show progress made during the build
4786 by displaying a string or calling a function while
4787 evaluating Nodes (e.g. files).
4789 If the first specified argument is a Python callable
4790 (a function or an object that has a
4793 the function will be called
4796 times a Node is evaluated.
4797 The callable will be passed the evaluated Node
4798 as its only argument.
4799 (For future compatibility,
4800 it's a good idea to also add
4804 as arguments to your function or method.
4805 This will prevent the code from breaking
4806 if SCons ever changes the interface
4807 to call the function with additional arguments in the future.)
4809 An example of a simple custom progress function
4810 that prints a string containing the Node name
4814 def my_progress_function(node, *args, **kw):
4815 print 'Evaluating node %s!' % node
4816 Progress(my_progress_function, interval=10)
4819 A more complicated example of a custom progress display object
4820 that prints a string containing a count
4821 every 100 evaluated Nodes.
4825 at the end so that the string
4826 will overwrite itself on a display:
4830 class ProgressCounter:
4832 def __call__(self, node, *args, **kw):
4834 sys.stderr.write('Evaluated %s nodes\\r' % self.count)
4835 Progress(ProgressCounter(), interval=100)
4838 If the first argument
4841 the string will be displayed
4845 The default is to print the string on standard output;
4846 an alternate output stream
4847 may be specified with the
4850 The following will print a series of dots
4851 on the error output,
4852 one dot for every 100 evaluated Nodes:
4856 Progress('.', interval=100, file=sys.stderr)
4859 If the string contains the verbatim substring
4861 it will be replaced with the Node.
4862 Note that, for performance reasons, this is
4864 a regular SCons variable substition,
4865 so you can not use other variables
4866 or use curly braces.
4867 The following example will print the name of
4868 every evaluated Node,
4871 (carriage return) to cause each line to overwritten by the next line,
4874 keyword argument to make sure the previously-printed
4875 file name is overwritten with blank spaces:
4879 Progress('$TARGET\\r', overwrite=True)
4882 If the first argument to
4884 is a list of strings,
4885 then each string in the list will be displayed
4886 in rotating fashion every
4889 This can be used to implement a "spinner"
4890 on the user's screen as follows:
4893 Progress(['-\\r', '\\\\\\r', '|\\r', '/\\r'], interval=5)
4896 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4898 .RI Precious( target ", ...)"
4900 .RI env.Precious( target ", ...)"
4903 as precious so it is not deleted before it is rebuilt. Normally
4905 deletes a target before building it.
4906 Multiple targets can be passed in to a single call to
4909 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4911 .RI env.Prepend( key = val ", [...])"
4912 Appends the specified keyword arguments
4913 to the beginning of construction variables in the environment.
4914 If the Environment does not have
4915 the specified construction variable,
4916 it is simply added to the environment.
4917 If the values of the construction variable
4918 and the keyword argument are the same type,
4919 then the two values will be simply added together.
4920 Otherwise, the construction variable
4921 and the value of the keyword argument
4922 are both coerced to lists,
4923 and the lists are added together.
4924 (See also the Append method, above.)
4929 env.Prepend(CCFLAGS = '-g ', FOO = ['foo.yyy'])
4932 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4934 .RI env.PrependENVPath( name ", " newpath ", [" envname ", " sep ", " delete_existing ])
4935 This appends new path elements to the given path in the
4936 specified external environment
4940 any particular path once (leaving the first one it encounters and
4941 ignoring the rest, to preserve path order),
4942 and to help assure this,
4943 will normalize all paths (using
4946 .BR os.path.normcase ).
4947 This can also handle the
4948 case where the given old path variable is a list instead of a
4949 string, in which case a list will be returned instead of a string.
4953 is 0, then adding a path that already exists
4954 will not move it to the beginning;
4955 it will stay where it is in the list.
4960 print 'before:',env['ENV']['INCLUDE']
4961 include_path = '/foo/bar:/foo'
4962 env.PrependENVPath('INCLUDE', include_path)
4963 print 'after:',env['ENV']['INCLUDE']
4966 The above exmaple will print:
4970 after: /foo/bar:/foo:/biz
4973 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4975 .RI env.PrependUnique( key = val ", delete_existing=0, [...])"
4976 Appends the specified keyword arguments
4977 to the beginning of construction variables in the environment.
4978 If the Environment does not have
4979 the specified construction variable,
4980 it is simply added to the environment.
4981 If the construction variable being appended to is a list,
4982 then any value(s) that already exist in the
4983 construction variable will
4985 be added again to the list.
4986 However, if delete_existing is 1,
4987 existing matching values are removed first, so
4988 existing values in the arg list move to the front of the list.
4993 env.PrependUnique(CCFLAGS = '-g', FOO = ['foo.yyy'])
4996 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4999 A factory function that
5000 returns a Builder object
5001 to be used to fetch source files
5003 The returned Builder
5004 is intended to be passed to the
5011 env.SourceCode('.', env.RCS())
5016 will fetch source files
5017 from RCS subdirectories automatically,
5019 as demonstrated in the above example
5020 should only be necessary if
5021 you are fetching from
5024 directory as the source files,
5025 or if you need to explicitly specify RCS
5026 for a specific subdirectory.
5028 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
5030 .RI env.Replace( key = val ", [...])"
5031 Replaces construction variables in the Environment
5032 with the specified keyword arguments.
5037 env.Replace(CCFLAGS = '-g', FOO = 'foo.xxx')
5040 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
5042 .RI Repository( directory )
5044 .RI env.Repository( directory )
5047 is a repository to be searched for files.
5051 and each one adds to the list of
5052 repositories that will be searched.
5056 a repository is a copy of the source tree,
5057 from the top-level directory on down,
5059 both source files and derived files
5060 that can be used to build targets in
5061 the local source tree.
5062 The canonical example would be an
5063 official source tree maintained by an integrator.
5064 If the repository contains derived files,
5065 then the derived files should have been built using
5067 so that the repository contains the necessary
5068 signature information to allow
5070 to figure out when it is appropriate to
5071 use the repository copy of a derived file,
5072 instead of building one locally.
5074 Note that if an up-to-date derived file
5075 already exists in a repository,
5079 make a copy in the local directory tree.
5080 In order to guarantee that a local copy
5086 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
5088 .RI Requires( target ", " prerequisite )
5090 .RI env.Requires( target ", " prerequisite )
5091 Specifies an order-only relationship
5092 between the specified target file(s)
5093 and the specified prerequisite file(s).
5094 The prerequisite file(s)
5095 will be (re)built, if necessary,
5098 but the target file(s) do not actually
5099 depend on the prerequisites
5100 and will not be rebuilt simply because
5101 the prerequisite file(s) change.
5106 env.Requires('foo', 'file-that-must-be-built-before-foo')
5109 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
5111 .RI Return([ vars "... , " stop= ])
5113 this stops processing the current SConscript
5114 file and returns to the calling SConscript file
5115 the values of the variables named in the
5118 Multiple strings contaning variable names may be passed to
5120 Any strings that contain white space
5124 keyword argument may be set to a false value
5125 to continue processing the rest of the SConscript
5129 This was the default behavior prior to SCons 0.98.
5130 However, the values returned
5131 are still the values of the variables in the named
5140 # Returns without returning a value.
5143 # Returns the value of the 'foo' Python variable.
5146 # Returns the values of the Python variables 'foo' and 'bar'.
5147 Return("foo", "bar")
5149 # Returns the values of Python variables 'val1' and 'val2'.
5153 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
5155 .RI Scanner( function ", [" argument ", " keys ", " path_function ", " node_class ", " node_factory ", " scan_check ", " recursive ])
5157 .RI env.Scanner( function ", [" argument ", " keys ", " path_function ", " node_class ", " node_factory ", " scan_check ", " recursive ])
5158 Creates a Scanner object for
5161 See the section "Scanner Objects,"
5162 below, for a complete explanation of the arguments and behavior.
5164 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
5167 A factory function that
5168 returns a Builder object
5169 to be used to fetch source files
5171 The returned Builder
5172 is intended to be passed to the
5179 env.SourceCode('.', env.SCCS())
5184 will fetch source files
5185 from SCCS subdirectories automatically,
5187 as demonstrated in the above example
5188 should only be necessary if
5189 you are fetching from
5192 directory as the source files,
5193 or if you need to explicitly specify SCCS
5194 for a specific subdirectory.
5196 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
5198 .RI SConscript( scripts ", [" exports ", " variant_dir ", " duplicate ])
5199 '\" .RI SConscript( scripts ", [" exports ", " variant_dir ", " src_dir ", " duplicate ])
5201 .RI env.SConscript( scripts ", [" exports ", " variant_dir ", " duplicate ])
5202 '\" .RI env.SConscript( scripts ", [" exports ", " variant_dir ", " src_dir ", " duplicate ])
5204 .RI SConscript(dirs= subdirs ", [name=" script ", " exports ", " variant_dir ", " duplicate ])
5205 '\" .RI SConscript(dirs= subdirs ", [name=" script ", " exports ", " variant_dir ", " src_dir ", " duplicate ])
5207 .RI env.SConscript(dirs= subdirs ", [name=" script ", " exports ", " variant_dir ", " duplicate ])
5208 '\" .RI env.SConscript(dirs= subdirs ", [name=" script ", " exports ", " variant_dir ", " src_dir ", " duplicate ])
5212 one or more subsidiary SConscript (configuration) files.
5213 Any variables returned by a called script using
5215 will be returned by the call to
5217 There are two ways to call the
5221 The first way you can call
5223 is to explicitly specify one or more
5225 as the first argument.
5226 A single script may be specified as a string;
5227 multiple scripts must be specified as a list
5228 (either explicitly or as created by
5233 SConscript('SConscript') # run SConscript in the current directory
5234 SConscript('src/SConscript') # run SConscript in the src directory
5235 SConscript(['src/SConscript', 'doc/SConscript'])
5236 config = SConscript('MyConfig.py')
5239 The second way you can call
5241 is to specify a list of (sub)directory names
5248 execute a subsidiary configuration file named
5250 in each of the specified directories.
5251 You may specify a name other than
5253 by supplying an optional
5256 The first three examples below have the same effect
5257 as the first three examples above:
5259 SConscript(dirs='.') # run SConscript in the current directory
5260 SConscript(dirs='src') # run SConscript in the src directory
5261 SConscript(dirs=['src', 'doc'])
5262 SConscript(dirs=['sub1', 'sub2'], name='MySConscript')
5267 argument provides a list of variable names or a dictionary of
5268 named values to export to the
5270 These variables are locally exported only to the specified
5272 and do not affect the global pool of variables used by the
5275 '\"If multiple dirs are provided, each script gets a fresh export.
5280 function to import the variables.
5283 foo = SConscript('sub/SConscript', exports='env')
5284 SConscript('dir/SConscript', exports=['env', 'variable'])
5285 SConscript(dirs='subdir', exports='env variable')
5286 SConscript(dirs=['one', 'two', 'three'], exports='shared_info')
5291 argument is present, it causes an effect equivalent to the
5293 method described below.
5299 '\" arguments are ignored.)
5300 argument is ignored.)
5305 '\" arguments are interpreted relative to the directory of the calling
5306 argument is interpreted relative to the directory of the calling
5307 .BR SConscript file.
5308 See the description of the
5310 function below for additional details and restrictions.
5313 '\" .IR variant_dir " is present, but"
5314 '\" .IR src_dir " is not,"
5315 .IR variant_dir " is present,"
5316 the source directory is relative to the called
5317 .BR SConscript " file."
5319 SConscript('src/SConscript', variant_dir = 'build')
5323 VariantDir('build', 'src')
5324 SConscript('build/SConscript')
5326 This later paradigm is often used when the sources are
5327 in the same directory as the
5328 .BR SConstruct file:
5330 SConscript('SConscript', variant_dir = 'build')
5334 VariantDir('build', '.')
5335 SConscript('build/SConscript')
5339 '\" .IR variant_dir " and"
5340 '\" .IR src_dir " are both present,"
5341 '\" xxxxx everything is in a state of confusion.
5343 '\" SConscript(dirs = 'src', variant_dir = 'build', src_dir = '.')
5344 '\" runs src/SConscript in build/src, but
5345 '\" SConscript(dirs = 'lib', variant_dir = 'build', src_dir = 'src')
5346 '\" runs lib/SConscript (in lib!). However,
5347 '\" SConscript(dirs = 'src', variant_dir = 'build', src_dir = 'src')
5348 '\" runs src/SConscript in build. Moreover,
5349 '\" SConscript(dirs = 'src/lib', variant_dir = 'build', src_dir = 'src')
5350 '\" runs src/lib/SConscript in build/lib. Moreover,
5351 '\" SConscript(dirs = 'build/src/lib', variant_dir = 'build', src_dir = 'src')
5352 '\" can't find build/src/lib/SConscript, even though it ought to exist.
5354 '\" is equivalent to
5356 '\" ????????????????
5358 '\" and what about this alternative?
5359 '\"TODO??? SConscript('build/SConscript', src_dir='src')
5361 Here are some composite examples:
5364 # collect the configuration information and use it to build src and doc
5365 shared_info = SConscript('MyConfig.py')
5366 SConscript('src/SConscript', exports='shared_info')
5367 SConscript('doc/SConscript', exports='shared_info')
5371 # build debugging and production versions. SConscript
5372 # can use Dir('.').path to determine variant.
5373 SConscript('SConscript', variant_dir='debug', duplicate=0)
5374 SConscript('SConscript', variant_dir='prod', duplicate=0)
5378 # build debugging and production versions. SConscript
5379 # is passed flags to use.
5380 opts = { 'CPPDEFINES' : ['DEBUG'], 'CCFLAGS' : '-pgdb' }
5381 SConscript('SConscript', variant_dir='debug', duplicate=0, exports=opts)
5382 opts = { 'CPPDEFINES' : ['NODEBUG'], 'CCFLAGS' : '-O' }
5383 SConscript('SConscript', variant_dir='prod', duplicate=0, exports=opts)
5387 # build common documentation and compile for different architectures
5388 SConscript('doc/SConscript', variant_dir='build/doc', duplicate=0)
5389 SConscript('src/SConscript', variant_dir='build/x86', duplicate=0)
5390 SConscript('src/SConscript', variant_dir='build/ppc', duplicate=0)
5393 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
5395 .RI SConscriptChdir( value )
5397 .RI env.SConscriptChdir( value )
5400 changes its working directory
5401 to the directory in which each
5402 subsidiary SConscript file lives.
5403 This behavior may be disabled
5404 by specifying either:
5408 env.SConscriptChdir(0)
5413 will stay in the top-level directory
5414 while reading all SConscript files.
5415 (This may be necessary when building from repositories,
5416 when all the directories in which SConscript files may be found
5417 don't necessarily exist locally.)
5418 You may enable and disable
5419 this ability by calling
5428 SConscript('foo/SConscript') # will not chdir to foo
5429 env.SConscriptChdir(1)
5430 SConscript('bar/SConscript') # will chdir to bar
5433 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
5435 .RI SConsignFile([ file , dbm_module ])
5437 .RI env.SConsignFile([ file , dbm_module ])
5440 to store all file signatures
5441 in the specified database
5448 (The actual file name(s) stored on disk
5449 may have an appropriated suffix appended
5454 is not an absolute path name,
5455 the file is placed in the same directory as the top-level
5465 will store file signatures
5468 file in each directory,
5469 not in one global database file.
5470 (This was the default behavior
5471 prior to SCons 0.96.91 and 0.97.)
5475 argument can be used to specify
5476 which Python database module
5477 The default is to use a custom
5479 module that uses pickled
5480 Python data structures,
5481 and which works on all Python versions from 1.5.2 on.
5486 # Explicitly stores signatures in ".sconsign.dblite"
5487 # in the top-level SConstruct directory (the
5488 # default behavior).
5491 # Stores signatures in the file "etc/scons-signatures"
5492 # relative to the top-level SConstruct directory.
5493 SConsignFile("etc/scons-signatures")
5495 # Stores signatures in the specified absolute file name.
5496 SConsignFile("/home/me/SCons/signatures")
5498 # Stores signatures in a separate .sconsign file
5499 # in each directory.
5503 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
5505 .RI env.SetDefault(key = val ", [...])"
5506 Sets construction variables to default values specified with the keyword
5507 arguments if (and only if) the variables are not already set.
5508 The following statements are equivalent:
5511 env.SetDefault(FOO = 'foo')
5513 if not env.has_key('FOO'): env['FOO'] = 'foo'
5516 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
5518 .RI SetOption( name ", " value )
5520 .RI env.SetOption( name ", " value )
5521 This function provides a way to set a select subset of the scons command
5522 line options from a SConscript file. The options supported are:
5527 which corresponds to -c, --clean and --remove;
5530 which corresponds to --duplicate;
5533 which corresponds to -h and --help;
5536 which corresponds to --implicit-cache;
5539 which corresponds to --max-drift;
5542 which corresponds to -n, --no-exec, --just-print, --dry-run and --recon;
5545 which corresponds to -j and --jobs;
5548 which corresponds to --random; and
5551 which corresponds to --stack-size.
5555 See the documentation for the
5556 corresponding command line object for information about each specific
5562 SetOption('max_drift', 1)
5565 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
5567 .RI SideEffect( side_effect ", " target )
5569 .RI env.SideEffect( side_effect ", " target )
5572 as a side effect of building
5578 can be a list, a file name, or a node.
5579 A side effect is a target file that is created or updated
5580 as a side effect of building other targets.
5581 For example, a Windows PDB
5582 file is created as a side effect of building the .obj
5583 files for a static library,
5584 and various log files are created updated
5585 as side effects of various TeX commands.
5586 If a target is a side effect of multiple build commands,
5588 will ensure that only one set of commands
5589 is executed at a time.
5590 Consequently, you only need to use this method
5591 for side-effect targets that are built as a result of
5592 multiple build commands.
5594 Because multiple build commands may update
5595 the same side effect file,
5600 automatically removed
5606 (Note, however, that the
5608 might be removed as part of
5609 cleaning the directory in which it lives.)
5610 If you want to make sure the
5612 is cleaned whenever a specific
5615 you must specify this explicitly
5622 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
5624 .RI SourceCode( entries ", " builder )
5626 .RI env.SourceCode( entries ", " builder )
5627 Arrange for non-existent source files to
5628 be fetched from a source code management system
5633 may be a Node, string or list of both,
5634 and may represent either individual
5635 source files or directories in which
5636 source files can be found.
5638 For any non-existent source files,
5640 will search up the directory tree
5650 will not use a builder to fetch
5651 source files for the specified
5655 builder has been specified
5656 for a directory higher up the tree.
5660 fetch files from SCCS or RCS subdirectories
5661 without explicit configuration.
5662 This takes some extra processing time
5663 to search for the necessary
5664 source code management files on disk.
5665 You can avoid these extra searches
5666 and speed up your build a little
5667 by disabling these searches as follows:
5670 env.SourceCode('.', None)
5674 Note that if the specified
5676 is one you create by hand,
5677 it must have an associated
5678 construction environment to use
5679 when fetching a source file.
5682 provides a set of canned factory
5683 functions that return appropriate
5684 Builders for various popular
5685 source code management systems.
5686 Canonical examples of invocation include:
5689 env.SourceCode('.', env.BitKeeper('/usr/local/BKsources'))
5690 env.SourceCode('src', env.CVS('/usr/local/CVSROOT'))
5691 env.SourceCode('/', env.RCS())
5692 env.SourceCode(['f1.c', 'f2.c'], env.SCCS())
5693 env.SourceCode('no_source.c', None)
5695 '\"env.SourceCode('.', env.Subversion('file:///usr/local/Subversion'))
5697 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
5699 .RI env.subst( input ", [" raw ", " target ", " source ", " conv ])
5700 Performs construction variable interpolation
5701 on the specified string or sequence argument
5705 leading or trailing white space will
5706 be removed from the result.
5707 and all sequences of white space
5708 will be compressed to a single space character.
5713 character sequences will be stripped from the returned string,
5716 argument may be set to
5718 if you want to preserve white space and
5723 argument may be set to
5725 if you want to strip
5726 all characters between
5732 (as is done for signature calculation).
5734 If the input is a sequence
5736 the individual elements of
5737 the sequence will be expanded,
5738 and the results will be returned as a list.
5745 must be set to lists of
5746 target and source nodes, respectively,
5753 to be available for expansion.
5754 This is usually necessary if you are
5757 from within a Python function used
5760 Returned string values or sequence elements
5761 are converted to their string representation by default.
5765 may specify a conversion function
5766 that will be used in place of
5768 For example, if you want Python objects
5769 (including SCons Nodes)
5770 to be returned as Python objects,
5771 you can use the Python
5773 idiom to pass in an unnamed function
5774 that simply returns its unconverted argument.
5779 print env.subst("The C compiler is: $CC")
5781 def compile(target, source, env):
5782 sourceDir = env.subst("${SOURCE.srcdir}",
5786 source_nodes = env.subst('$EXPAND_TO_NODELIST',
5790 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
5792 '\".RI Subversion( repository ", " module )
5793 '\"A factory function that
5794 '\"returns a Builder object
5795 '\"to be used to fetch source files
5796 '\"from the specified Subversion
5798 '\"The returned Builder
5799 '\"is intended to be passed to the
5803 '\"The optional specified
5805 '\"will be added to the beginning
5806 '\"of all repository path names;
5807 '\"this can be used, in essence,
5808 '\"to strip initial directory names
5809 '\"from the repository path names,
5810 '\"so that you only have to
5811 '\"replicate part of the repository
5812 '\"directory hierarchy in your
5813 '\"local build directory.
5818 '\"# Will fetch foo/bar/src.c
5819 '\"# from /usr/local/Subversion/foo/bar/src.c.
5820 '\"env.SourceCode('.', env.Subversion('file:///usr/local/Subversion'))
5822 '\"# Will fetch bar/src.c
5823 '\"# from /usr/local/Subversion/foo/bar/src.c.
5824 '\"env.SourceCode('.', env.Subversion('file:///usr/local/Subversion', 'foo'))
5826 '\"# Will fetch src.c
5827 '\"# from /usr/local/Subversion/foo/bar/src.c.
5828 '\"env.SourceCode('.', env.Subversion('file:///usr/local/Subversion', 'foo/bar'))
5831 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
5833 .RI SourceSignatures( type )
5835 .RI env.SourceSignatures( type )
5836 Note: Although it is not yet officially deprecated,
5837 use of this function is discouraged.
5840 function for a more flexible and straightforward way
5841 to configure SCons' decision-making.
5844 .BR SourceSignatures ()
5847 how to decide if a source file
5848 (a file that is not built from any other files)
5849 has changed since the last time it
5850 was used to build a particular target file.
5856 If the environment method is used,
5857 the specified type of source signature
5858 is only used when deciding whether targets
5859 built with that environment are up-to-date or must be rebuilt.
5860 If the global function is used,
5861 the specified type of source signature becomes the default
5862 used for all decisions
5863 about whether targets are up-to-date.
5868 decides that a source file has changed
5869 if the MD5 checksum of its contents has changed since
5870 the last time it was used to rebuild a particular target file.
5875 decides that a source file has changed
5876 if its timestamp (modification time) has changed since
5877 the last time it was used to rebuild a particular target file.
5878 (Note that although this is similar to the behavior of Make,
5879 by default it will also rebuild if the dependency is
5881 than the last time it was used to rebuild the target file.)
5883 There is no different between the two behaviors
5889 signatures take longer to compute,
5890 but are more accurate than
5893 The default value is
5896 Note that the default
5897 .BR TargetSignatures ()
5900 .BR SourceSignatures ()
5901 setting for any target files that are used
5902 to build other target files.
5903 Consequently, changing the value of
5904 .BR SourceSignatures ()
5906 affect the up-to-date decision for all files in the build
5907 (or all files built with a specific construction environment
5909 .BR env.SourceSignatures ()
5912 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
5916 .RI env.Split( arg )
5917 Returns a list of file names or other objects.
5919 it will be split on strings of white-space characters
5921 making it easier to write long lists of file names.
5922 If arg is already a list,
5923 the list will be returned untouched.
5924 If arg is any other type of object,
5925 it will be returned as a list
5926 containing just the object.
5931 files = Split("f1.c f2.c f3.c")
5932 files = env.Split("f4.c f5.c f6.c")
5940 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
5942 .RI Tag( node ", " tags )
5943 Annotates file or directory Nodes with
5944 information about how the
5946 Builder should package those files or directories.
5947 All tags are optional.
5952 # makes sure the built library will be installed with 0644 file
5954 Tag( Library( 'lib.c' ), UNIX_ATTR="0644" )
5956 # marks file2.txt to be a documentation file
5957 Tag( 'file2.txt', DOC )
5960 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
5962 .RI TargetSignatures( type )
5964 .RI env.TargetSignatures( type )
5965 Note: Although it is not yet officially deprecated,
5966 use of this function is discouraged.
5969 function for a more flexible and straightforward way
5970 to configure SCons' decision-making.
5973 .BR TargetSignatures ()
5976 how to decide if a target file
5979 built from any other files)
5980 has changed since the last time it
5981 was used to build some other target file.
5991 If the environment method is used,
5992 the specified type of target signature is only used
5993 for targets built with that environment.
5994 If the global function is used,
5995 the specified type of signature becomes the default
5996 used for all target files that
5997 don't have an explicit target signature type
5998 specified for their environments.
6005 decides that a target file has changed
6006 if the MD5 checksum of its contents has changed since
6007 the last time it was used to rebuild some other target file.
6011 MD5 sum the contents
6012 of target files after they're built,
6013 and may decide that it does not need to rebuild
6014 "downstream" target files if a file was
6015 rebuilt with exactly the same contents as the last time.
6020 decides that a target file has changed
6021 if its timestamp (modification time) has changed since
6022 the last time it was used to rebuild some other target file.
6023 (Note that although this is similar to the behavior of Make,
6024 by default it will also rebuild if the dependency is
6026 than the last time it was used to rebuild the target file.)
6031 decides that a target file has changed
6032 as specified by the corresponding
6033 .BR SourceSignatures ()
6040 will treat all input files to a target the same way,
6041 regardless of whether they are source files
6042 or have been built from other files.
6047 decides that a target file has changed
6048 if it has been rebuilt in this invocation
6049 or if its content or timestamp have changed
6050 as specified by the corresponding
6051 .BR SourceSignatures ()
6053 This "propagates" the status of a rebuilt file
6054 so that other "downstream" target files
6055 will always be rebuilt,
6056 even if the contents or the timestamp
6060 signatures are fastest because
6064 signatures take longer to compute,
6065 but are more accurate than
6068 and can prevent unnecessary "downstream" rebuilds
6069 when a target file is rebuilt to the exact same contents
6070 as the previous build.
6073 setting provides the most consistent behavior
6074 when other target files may be rebuilt from
6075 both source and target input files.
6076 The default value is
6079 Because the default setting is
6082 .BR SourceSignatures ()
6083 is generally preferable to
6084 .BR TargetSignatures () ,
6085 so that the up-to-date decision
6086 will be consistent for all files
6087 (or all files built with a specific construction environment).
6089 .BR TargetSignatures ()
6090 provides specific control for how built target files
6091 affect their "downstream" dependencies.
6093 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
6095 .RI Tool( string [, toolpath ", " **kw ])
6096 Returns a callable object
6097 that can be used to initialize
6098 a construction environment using the
6099 tools keyword of the Environment() method.
6100 The object may be called with a construction
6101 environment as an argument,
6102 in which case the object will
6103 add the necessary variables
6104 to the construction environment
6105 and the name of the tool will be added to the
6107 construction variable.
6109 Additional keyword arguments are passed to the tool's
6116 env = Environment(tools = [ Tool('msvc') ])
6120 t(env) # adds 'msvc' to the TOOLS variable
6121 u = Tool('opengl', toolpath = ['tools'])
6122 u(env) # adds 'opengl' to the TOOLS variable
6125 .RI env.Tool( string [, toolpath ", " **kw ])
6126 Applies the callable object for the specified tool
6128 to the environment through which the method was called.
6130 Additional keyword arguments are passed to the tool's
6136 env.Tool('opengl', toolpath = ['build/tools'])
6139 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
6141 .RI Value( value ", [" built_value ])
6143 .RI env.Value( value ", [" built_value ])
6144 Returns a Node object representing the specified Python value. Value
6145 Nodes can be used as dependencies of targets. If the result of
6148 changes between SCons runs, any targets depending on
6151 (This is true even when using timestamps to decide if
6152 files are up-to-date.)
6153 When using timestamp source signatures, Value Nodes'
6154 timestamps are equal to the system time when the Node is created.
6156 The returned Value Node object has a
6158 method that can be used to "build" a Value Node
6159 by setting a new value.
6162 argument can be specified
6163 when the Value Node is created
6164 to indicate the Node should already be considered
6166 There is a corresponding
6168 method that will return the built value of the Node.
6175 def create(target, source, env):
6176 # A function that will write a 'prefix=$SOURCE'
6177 # string into the file name specified as the
6179 f = open(str(target[0]), 'wb')
6180 f.write('prefix=' + source[0].get_contents())
6182 # Fetch the prefix= argument, if any, from the command
6183 # line, and use /usr/local as the default.
6184 prefix = ARGUMENTS.get('prefix', '/usr/local')
6186 # Attach a .Config() builder for the above function action
6187 # to the construction environment.
6188 env['BUILDERS']['Config'] = Builder(action = create)
6189 env.Config(target = 'package-config', source = Value(prefix))
6191 def build_value(target, source, env):
6192 # A function that "builds" a Python Value by updating
6193 # the the Python value with the contents of the file
6194 # specified as the source of the Builder call ($SOURCE).
6195 target[0].write(source[0].get_contents())
6197 output = env.Value('before')
6198 input = env.Value('after')
6200 # Attach a .UpdateValue() builder for the above function
6201 # action to the construction environment.
6202 env['BUILDERS']['UpdateValue'] = Builder(action = build_value)
6203 env.UpdateValue(target = Value(output), source = Value(input))
6206 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
6208 .RI VariantDir( variant_dir ", " src_dir ", [" duplicate ])
6210 .RI env.VariantDir( variant_dir ", " src_dir ", [" duplicate ])
6213 function to create a copy of your sources in another location:
6216 is not found but exists under
6218 the file or directory is copied to
6220 Target files can be built in a different directory
6221 than the original sources by simply refering to the sources (and targets)
6222 within the variant tree.
6225 can be called multiple times with the same
6227 to set up multiple builds with different options
6231 location must be in or underneath the SConstruct file's directory, and
6233 may not be underneath
6235 '\"TODO: Can the above restrictions be clarified or relaxed?
6236 '\"TODO: The latter restriction is clearly not completely right;
6237 '\"TODO: src_dir = '.' works fine with a build dir under it.
6239 The default behavior is for
6241 to physically duplicate the source files in the variant tree.
6242 Thus, a build performed in the variant tree is guaranteed to be identical
6243 to a build performed in the source tree even if
6244 intermediate source files are generated during the build,
6245 or preprocessors or other scanners search for included files
6246 relative to the source file,
6247 or individual compilers or other invoked tools are hard-coded
6248 to put derived files in the same directory as source files.
6250 If possible on the platform,
6251 the duplication is performed by linking rather than copying;
6254 command-line option.
6255 Moreover, only the files needed for the build are duplicated;
6256 files and directories that are not used are not present in
6259 Duplicating the source tree may be disabled by setting the
6261 argument to 0 (zero).
6264 to invoke Builders using the path names of source files in
6266 and the path names of derived files within
6268 This is always more efficient than
6270 and is usually safe for most builds
6271 (but see above for cases that may cause problems).
6275 works most naturally with a subsidiary SConscript file.
6276 However, you would then call the subsidiary SConscript file
6277 not in the source directory, but in the
6279 regardless of the value of
6281 This is how you tell
6283 which variant of a source tree to build:
6286 # run src/SConscript in two variant directories
6287 VariantDir('build/variant1', 'src')
6288 SConscript('build/variant1/SConscript')
6289 VariantDir('build/variant2', 'src')
6290 SConscript('build/variant2/SConscript')
6296 function, described above,
6297 for another way to specify a variant directory
6298 in conjunction with calling a subsidiary SConscript file.
6303 # use names in the build directory, not the source directory
6304 VariantDir('build', 'src', duplicate=0)
6305 Program('build/prog', 'build/source.c')
6309 # this builds both the source and docs in a separate subtree
6310 VariantDir('build', '.', duplicate=0)
6311 SConscript(dirs=['build/src','build/doc'])
6315 # same as previous example, but only uses SConscript
6316 SConscript(dirs='src', variant_dir='build/src', duplicate=0)
6317 SConscript(dirs='doc', variant_dir='build/doc', duplicate=0)
6320 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
6322 .RI WhereIs( program ", [" path ", " pathext ", " reject ])
6324 .RI env.WhereIs( program ", [" path ", " pathext ", " reject ])
6326 Searches for the specified executable
6328 returning the full path name to the program
6330 and returning None if not.
6331 Searches the specified
6333 the value of the calling environment's PATH
6334 (env['ENV']['PATH']),
6335 or the user's current external PATH
6336 (os.environ['PATH'])
6338 On Windows systems, searches for executable
6339 programs with any of the file extensions
6340 listed in the specified
6342 the calling environment's PATHEXT
6343 (env['ENV']['PATHEXT'])
6344 or the user's current PATHEXT
6345 (os.environ['PATHEXT'])
6353 .SS SConscript Variables
6354 In addition to the global functions and methods,
6356 supports a number of Python variables
6357 that can be used in SConscript files
6358 to affect how you want the build to be performed.
6359 These variables may be accessed from custom Python modules that you
6360 import into an SConscript file by adding the following
6361 to the Python module:
6364 from SCons.Script import *
6367 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
6372 arguments specified on the command line.
6373 Each element in the list is a tuple
6375 .RI ( keyword , value )
6381 elements of the tuple
6383 subscripting for element
6387 of the tuple, respectively.
6392 print "first keyword, value =", ARGLIST[0][0], ARGLIST[0][1]
6393 print "second keyword, value =", ARGLIST[1][0], ARGLIST[1][1]
6394 third_tuple = ARGLIST[2]
6395 print "third keyword, value =", third_tuple[0], third_tuple[1]
6396 for key, value in ARGLIST:
6397 # process key and value
6400 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
6403 A dictionary of all the
6405 arguments specified on the command line.
6406 The dictionary is not in order,
6407 and if a given keyword has
6408 more than one value assigned to it
6409 on the command line,
6410 the last (right-most) value is
6418 if ARGUMENTS.get('debug', 0):
6419 env = Environment(CCFLAGS = '-g')
6424 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
6427 A list of the targets which
6429 will actually try to build,
6430 regardless of whether they were specified on
6431 the command line or via the
6434 The elements of this list may be strings
6436 nodes, so you should run the list through the Python
6438 function to make sure any Node path names
6439 are converted to strings.
6441 Because this list may be taken from the
6442 list of targets specified using the
6445 the contents of the list may change
6446 on each successive call to
6451 for additional information.
6456 if 'foo' in BUILD_TARGETS:
6457 print "Don't forget to test the `foo' program!"
6458 if 'special/program' in BUILD_TARGETS:
6459 SConscript('special')
6464 list only contains targets expected listed
6465 on the command line or via calls to the
6470 contain all dependent targets that will be built as
6471 a result of making the sure the explicitly-specified
6472 targets are up to date.
6474 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
6476 COMMAND_LINE_TARGETS
6477 A list of the targets explicitly specified on
6479 If there are no targets specified on the command line,
6481 This can be used, for example,
6482 to take specific actions only
6483 when a certain target or targets
6484 is explicitly being built.
6489 if 'foo' in COMMAND_LINE_TARGETS:
6490 print "Don't forget to test the `foo' program!"
6491 if 'special/program' in COMMAND_LINE_TARGETS:
6492 SConscript('special')
6495 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
6498 A list of the target
6500 that have been specified using the
6503 The elements of the list are nodes,
6504 so you need to run them through the Python
6506 function to get at the path name for each Node.
6511 print str(DEFAULT_TARGETS[0])
6512 if 'foo' in map(str, DEFAULT_TARGETS):
6513 print "Don't forget to test the `foo' program!"
6518 list change on on each successive call to the
6523 print map(str, DEFAULT_TARGETS) # originally []
6525 print map(str, DEFAULT_TARGETS) # now a node ['foo']
6527 print map(str, DEFAULT_TARGETS) # now a node ['foo', 'bar']
6529 print map(str, DEFAULT_TARGETS) # back to []
6532 Consequently, be sure to use
6534 only after you've made all of your
6537 or else simply be careful of the order
6538 of these statements in your SConscript files
6539 so that you don't look for a specific
6540 default target before it's actually been added to the list.
6542 .SS Construction Variables
6543 .\" XXX From Gary Ruben, 23 April 2002:
6544 .\" I think it would be good to have an example with each construction
6545 .\" variable description in the documentation.
6547 .\" CC The C compiler
6548 .\" Example: env["CC"] = "c68x"
6549 .\" Default: env["CC"] = "cc"
6551 .\" CCCOM The command line ...
6553 .\" To generate the compiler line c68x -ps -qq -mr -o $TARGET $SOURCES
6554 .\" env["CC"] = "c68x"
6555 .\" env["CFLAGS"] = "-ps -qq -mr"
6556 .\" env["CCCOM"] = "$CC $CFLAGS -o $TARGET $SOURCES
6558 .\" (I dunno what this is ;-)
6559 A construction environment has an associated dictionary of
6560 .I construction variables
6561 that are used by built-in or user-supplied build rules.
6562 Construction variables must follow the same rules for
6564 the initial character must be an underscore or letter,
6565 followed by any number of underscores, letters, or digits.
6567 A number of useful construction variables are automatically defined by
6568 scons for each supported platform, and additional construction variables
6569 can be defined by the user. The following is a list of the automatically
6570 defined construction variables:
6572 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
6573 '\" BEGIN GENERATED CONSTRUCTION VARIABLE DESCRIPTIONS
6575 '\" The descriptions below of the various SCons construction variables
6576 '\" are generated from the .xml files that live next to the various
6577 '\" Python modules in the build enginer library. If you're reading
6578 '\" this [gnt]roff file with an eye towards patching this man page,
6579 '\" you can still submit a diff against this text, but it will have to
6580 '\" be translated to a diff against the underlying .xml file before the
6581 '\" patch is actually accepted. If you do that yourself, it will make
6582 '\" it easier to integrate the patch.
6584 '\" BEGIN GENERATED CONSTRUCTION VARIABLE DESCRIPTIONS
6585 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
6587 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
6588 '\" END GENERATED CONSTRUCTION VARIABLE DESCRIPTIONS
6590 '\" The descriptions above of the various SCons construction variables
6591 '\" are generated from the .xml files that live next to the various
6592 '\" Python modules in the build enginer library. If you're reading
6593 '\" this [gnt]roff file with an eye towards patching this man page,
6594 '\" you can still submit a diff against this text, but it will have to
6595 '\" be translated to a diff against the underlying .xml file before the
6596 '\" patch is actually accepted. If you do that yourself, it will make
6597 '\" it easier to integrate the patch.
6599 '\" END GENERATED CONSTRUCTION VARIABLE DESCRIPTIONS
6600 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
6603 Construction variables can be retrieved and set using the
6605 method of the construction environment:
6608 dict = env.Dictionary()
6612 or using the [] operator:
6618 Construction variables can also be passed to the construction environment
6622 env = Environment(CC="cc")
6625 or when copying a construction environment using the
6630 env2 = env.Clone(CC="cl.exe")
6633 .SS Configure Contexts
6637 .I configure contexts,
6638 an integrated mechanism similar to the
6639 various AC_CHECK macros in GNU autoconf
6640 for testing for the existence of C header
6641 files, libraries, etc.
6642 In contrast to autoconf,
6644 does not maintain an explicit cache of the tested values,
6645 but uses its normal dependency tracking to keep the checked values
6646 up to date. However, users may override this behaviour with the
6648 command line option.
6650 The following methods can be used to perform checks:
6653 .RI Configure( env ", [" custom_tests ", " conf_dir ", " log_file ", " config_h ", " clean ", " help])
6655 .RI env.Configure([ custom_tests ", " conf_dir ", " log_file ", " config_h ", " clean ", " help])
6656 This creates a configure context, which can be used to perform checks.
6658 specifies the environment for building the tests.
6659 This environment may be modified when performing checks.
6661 is a dictionary containing custom tests.
6662 See also the section about custom tests below.
6663 By default, no custom tests are added to the configure context.
6665 specifies a directory where the test cases are built.
6666 Note that this directory is not used for building
6668 The default value is the directory
6671 specifies a file which collects the output from commands
6672 that are executed to check for the existence of header files, libraries, etc.
6673 The default is the file #/config.log.
6674 If you are using the
6677 you may want to specify a subdirectory under your variant directory.
6679 specifies a C header file where the results of tests
6680 will be written, e.g. #define HAVE_STDIO_H, #define HAVE_LIBM, etc.
6681 The default is to not write a
6684 You can specify the same
6686 file in multiple calls to Configure,
6689 will concatenate all results in the specified file.
6691 uses its normal dependency checking
6692 to decide if it's necessary to rebuild
6696 This means that the file is not necessarily re-built each
6698 but is only rebuilt if its contents will have changed
6699 and some target that depends on the
6701 file is being built.
6707 arguments can be used to suppress execution of the configuration
6712 options are used, respectively.
6713 The default behavior is always to execute
6714 configure context tests,
6715 since the results of the tests may
6716 affect the list of targets to be cleaned
6718 If the configure tests do not affect these,
6719 then you may add the
6725 to avoid unnecessary test execution.
6730 instance has the following associated methods:
6733 .RI SConf.Finish( context )
6736 This method should be called after configuration is done.
6737 It returns the environment as modified
6738 by the configuration checks performed.
6739 After this method is called, no further checks can be performed
6740 with this configuration context.
6741 However, you can create a new
6743 context to perform additional checks.
6744 Only one context should be active at a time.
6746 The following Checks are predefined.
6747 (This list will likely grow larger as time
6748 goes by and developers contribute new useful tests.)
6751 .RI SConf.CheckHeader( context ", " header ", [" include_quotes ", " language ])
6753 .IR sconf .CheckHeader( header ", [" include_quotes ", " language ])
6756 is usable in the specified language.
6759 in which case the last item in the list
6760 is the header file to be checked,
6761 and the previous list items are
6764 lines should precede the
6765 header line being checked for.
6766 The optional argument
6769 a two character string, where the first character denotes the opening
6770 quote and the second character denotes the closing quote.
6771 By default, both characters are " (double quote).
6772 The optional argument
6778 and selects the compiler to be used for the check.
6779 Returns 1 on success and 0 on failure.
6782 .RI SConf.CheckCHeader( context ", " header ", [" include_quotes ])
6784 .IR sconf .CheckCHeader( header ", [" include_quotes ])
6785 This is a wrapper around
6786 .B SConf.CheckHeader
6789 is usable in the C language.
6792 in which case the last item in the list
6793 is the header file to be checked,
6794 and the previous list items are
6797 lines should precede the
6798 header line being checked for.
6799 The optional argument
6802 a two character string, where the first character denotes the opening
6803 quote and the second character denotes the closing quote (both default
6805 Returns 1 on success and 0 on failure.
6808 .RI SConf.CheckCXXHeader( context ", " header ", [" include_quotes ])
6810 .IR sconf .CheckCXXHeader( header ", [" include_quotes ])
6811 This is a wrapper around
6812 .B SConf.CheckHeader
6815 is usable in the C++ language.
6818 in which case the last item in the list
6819 is the header file to be checked,
6820 and the previous list items are
6823 lines should precede the
6824 header line being checked for.
6825 The optional argument
6828 a two character string, where the first character denotes the opening
6829 quote and the second character denotes the closing quote (both default
6831 Returns 1 on success and 0 on failure.
6834 .RI SConf.CheckFunc( context, ", " function_name ", [" header ", " language ])
6836 .IR sconf .CheckFunc( function_name ", [" header ", " language ])
6837 Checks if the specified
6838 C or C++ function is available.
6840 is the name of the function to check for.
6843 argument is a string
6847 that will be compiled
6848 to check if the function exists;
6854 char function_name();
6862 and selects the compiler to be used for the check;
6866 .RI SConf.CheckLib( context ", [" library ", " symbol ", " header ", " language ", " autoadd=1 ])
6868 .IR sconf .CheckLib([ library ", " symbol ", " header ", " language ", " autoadd=1 ])
6875 is 1 and the library provides the specified
6877 appends the library to the LIBS construction environment variable.
6879 may also be None (the default),
6882 is checked with the current LIBS variable,
6883 or a list of library names,
6884 in which case each library in the list
6892 .BR SConf.CheckLib ()
6894 you can link against the specified
6902 and selects the compiler to be used for the check;
6904 The default value for
6907 This method returns 1 on success and 0 on error.
6910 .RI SConf.CheckLibWithHeader( context ", " library ", " header ", " language ", [" call ", " autoadd ])
6912 .IR sconf .CheckLibWithHeader( library ", " header ", " language ", [" call ", " autoadd ])
6916 call, this call provides a more sophisticated way to check against libraries.
6919 specifies the library or a list of libraries to check.
6921 specifies a header to check for.
6924 in which case the last item in the list
6925 is the header file to be checked,
6926 and the previous list items are
6929 lines should precede the
6930 header line being checked for.
6932 may be one of 'C','c','CXX','cxx','C++' and 'c++'.
6934 can be any valid expression (with a trailing ';').
6938 the default simply checks that you
6939 can link against the specified
6942 specifies whether to add the library to the environment (only if the check
6943 succeeds). This method returns 1 on success and 0 on error.
6946 .RI SConf.CheckType( context ", " type_name ", [" includes ", " language ])
6948 .IR sconf .CheckType( type_name ", [" includes ", " language ])
6949 Checks for the existence of a type defined by
6952 specifies the typedef name to check for.
6954 is a string containing one or more
6956 lines that will be inserted into the program
6957 that will be run to test for the existence of the type.
6964 and selects the compiler to be used for the check;
6968 sconf.CheckType('foo_type', '#include "my_types.h"', 'C++')
6972 .RI Configure.CheckCC( self )
6973 Checks whether the C compiler (as defined by the CC construction variable) works
6974 by trying to compile a small source file.
6976 By default, SCons only detects if there is a program with the correct name, not
6977 if it is a functioning compiler.
6979 This uses the exact same command than the one used by the object builder for C
6980 source file, so it can be used to detect if a particular compiler flag works or
6984 .RI Configure.CheckCXX( self )
6985 Checks whether the C++ compiler (as defined by the CXX construction variable)
6986 works by trying to compile a small source file. By default, SCons only detects
6987 if there is a program with the correct name, not if it is a functioning compiler.
6989 This uses the exact same command than the one used by the object builder for
6990 CXX source files, so it can be used to detect if a particular compiler flag
6994 .RI Configure.CheckSHCC( self )
6995 Checks whether the C compiler (as defined by the SHCC construction variable) works
6996 by trying to compile a small source file. By default, SCons only detects if
6997 there is a program with the correct name, not if it is a functioning compiler.
6999 This uses the exact same command than the one used by the object builder for C
7000 source file, so it can be used to detect if a particular compiler flag works or
7001 not. This does not check whether the object code can be used to build a shared
7002 library, only that the compilation (not link) succeeds.
7005 .RI Configure.CheckSHCXX( self )
7006 Checks whether the C++ compiler (as defined by the SHCXX construction variable)
7007 works by trying to compile a small source file. By default, SCons only detects
7008 if there is a program with the correct name, not if it is a functioning compiler.
7010 This uses the exact same command than the one used by the object builder for
7011 CXX source files, so it can be used to detect if a particular compiler flag
7012 works or not. This does not check whether the object code can be used to build
7013 a shared library, only that the compilation (not link) succeeds.
7016 Example of a typical Configure usage:
7020 conf = Configure( env )
7021 if not conf.CheckCHeader( 'math.h' ):
7022 print 'We really need math.h!'
7024 if conf.CheckLibWithHeader( 'qt', 'qapp.h', 'c++',
7025 'QApplication qapp(0,0);' ):
7026 # do stuff for qt - usage, e.g.
7027 conf.env.Append( CPPFLAGS = '-DWITH_QT' )
7032 .RI SConf.CheckTypeSize( context ", " type_name ", [" header ", " language ", " expect ])
7034 .IR sconf .CheckTypeSize( type_name ", [" header ", " language ", " expect ])
7035 Checks for the size of a type defined by
7038 specifies the typedef name to check for.
7041 argument is a string
7045 that will be compiled
7046 to check if the function exists;
7047 the default is empty.
7054 and selects the compiler to be used for the check;
7058 argument should be an integer.
7059 If this argument is used,
7060 the function will only check whether the type
7061 given in type_name has the expected size (in bytes).
7063 .B "CheckTypeSize('short', expect = 2)"
7064 will return success only if short is two bytes.
7070 .RI SConf.CheckDeclaration( context ", " symbol ", [" includes ", " language ])
7072 .IR sconf .CheckDeclaration( symbol ", [" includes ", " language ])
7073 Checks if the specified
7077 is a string containing one or more
7079 lines that will be inserted into the program
7080 that will be run to test for the existence of the type.
7087 and selects the compiler to be used for the check;
7091 .RI SConf.Define( context ", " symbol ", [" value ", " comment ])
7093 .IR sconf .Define( symbol ", [" value ", " comment ])
7094 This function does not check for anything, but defines a
7095 preprocessor symbol that will be added to the configuration header file.
7096 It is the equivalent of AC_DEFINE,
7097 and defines the symbol
7101 and the optional comment
7109 conf = Configure( env )
7111 # Puts the following line in the config header file:
7113 conf.Define('A_SYMBOL')
7115 # Puts the following line in the config header file:
7116 # #define A_SYMBOL 1
7117 conf.Define('A_SYMBOL', 1)
7121 Be careful about quoting string values, though:
7125 conf = Configure( env )
7127 # Puts the following line in the config header file:
7128 # #define A_SYMBOL YA
7129 conf.Define('A_SYMBOL', "YA")
7131 # Puts the following line in the config header file:
7132 # #define A_SYMBOL "YA"
7133 conf.Define('A_SYMBOL', '"YA"')
7141 conf = Configure( env )
7143 # Puts the following lines in the config header file:
7144 # /* Set to 1 if you have a symbol */
7145 # #define A_SYMBOL 1
7146 conf.Define('A_SYMBOL', 1, 'Set to 1 if you have a symbol')
7150 You can define your own custom checks.
7151 in addition to the predefined checks.
7152 These are passed in a dictionary to the Configure function.
7153 This dictionary maps the names of the checks
7154 to user defined Python callables
7155 (either Python functions or class instances implementing the
7158 The first argument of the call is always a
7160 instance followed by the arguments,
7161 which must be supplied by the user of the check.
7162 These CheckContext instances define the following methods:
7165 .RI CheckContext.Message( self ", " text )
7167 Usually called before the check is started.
7169 will be displayed to the user, e.g. 'Checking for library X...'
7172 .RI CheckContext.Result( self, ", " res )
7174 Usually called after the check is done.
7176 can be either an integer or a string. In the former case, 'ok' (res != 0)
7177 or 'failed' (res == 0) is displayed to the user, in the latter case the
7178 given string is displayed.
7181 .RI CheckContext.TryCompile( self ", " text ", " extension )
7182 Checks if a file with the specified
7184 (e.g. '.c') containing
7186 can be compiled using the environment's
7188 builder. Returns 1 on success and 0 on failure.
7191 .RI CheckContext.TryLink( self ", " text ", " extension )
7192 Checks, if a file with the specified
7194 (e.g. '.c') containing
7196 can be compiled using the environment's
7198 builder. Returns 1 on success and 0 on failure.
7201 .RI CheckContext.TryRun( self ", " text ", " extension )
7202 Checks, if a file with the specified
7204 (e.g. '.c') containing
7206 can be compiled using the environment's
7208 builder. On success, the program is run. If the program
7209 executes successfully
7210 (that is, its return status is 0),
7215 is the standard output of the
7217 If the program fails execution
7218 (its return status is non-zero),
7219 then (0, '') is returned.
7222 .RI CheckContext.TryAction( self ", " action ", [" text ", " extension ])
7223 Checks if the specified
7225 with an optional source file (contents
7232 may be anything which can be converted to a
7239 is the content of the target file.
7245 .RI CheckContext.TryBuild( self ", " builder ", [" text ", " extension ])
7246 Low level implementation for testing specific builds;
7247 the methods above are based on this method.
7248 Given the Builder instance
7252 of a source file with optional
7254 this method returns 1 on success and 0 on failure. In addition,
7256 is set to the build target node, if the build was successful.
7259 Example for implementing and using custom tests:
7262 def CheckQt(context, qtdir):
7263 context.Message( 'Checking for qt ...' )
7264 lastLIBS = context.env['LIBS']
7265 lastLIBPATH = context.env['LIBPATH']
7266 lastCPPPATH= context.env['CPPPATH']
7267 context.env.Append(LIBS = 'qt', LIBPATH = qtdir + '/lib', CPPPATH = qtdir + '/include' )
7268 ret = context.TryLink("""
7270 int main(int argc, char **argv) {
7271 QApplication qapp(argc, argv);
7276 context.env.Replace(LIBS = lastLIBS, LIBPATH=lastLIBPATH, CPPPATH=lastCPPPATH)
7277 context.Result( ret )
7281 conf = Configure( env, custom_tests = { 'CheckQt' : CheckQt } )
7282 if not conf.CheckQt('/usr/lib/qt'):
7283 print 'We really need qt!'
7288 .SS Command-Line Construction Variables
7290 Often when building software,
7291 some variables must be specified at build time.
7292 For example, libraries needed for the build may be in non-standard
7293 locations, or site-specific compiler options may need to be passed to the
7298 object to support overriding construction variables
7299 on the command line:
7301 $ scons VARIABLE=foo
7303 The variable values can also be specified in a text-based SConscript file.
7304 To create a Variables object, call the Variables() function:
7307 .RI Variables([ files "], [" args ])
7308 This creates a Variables object that will read construction variables from
7309 the file or list of filenames specified in
7311 If no files are specified,
7316 then no files will be read.
7317 The optional argument
7320 values that will override anything read from the specified files;
7321 it is primarily intended to be passed the
7323 dictionary that holds variables
7324 specified on the command line.
7328 vars = Variables('custom.py')
7329 vars = Variables('overrides.py', ARGUMENTS)
7330 vars = Variables(None, {FOO:'expansion', BAR:7})
7333 Variables objects have the following methods:
7336 .RI Add( key ", [" help ", " default ", " validator ", " converter ])
7337 This adds a customizable construction variable to the Variables object.
7339 is the name of the variable.
7341 is the help text for the variable.
7343 is the default value of the variable;
7344 if the default value is
7346 and there is no explicit value specified,
7347 the construction variable will
7349 be added to the construction environment.
7351 is called to validate the value of the variable, and should take three
7352 arguments: key, value, and environment.
7353 The recommended way to handle an invalid value is
7354 to raise an exception (see example below).
7356 is called to convert the value before putting it in the environment, and
7357 should take either a value, or the value and environment, as parameters.
7360 must return a value,
7361 which will be converted into a string
7362 before being validated by the
7365 and then added to the environment.
7370 vars.Add('CC', 'The C compiler')
7372 def validate_color(key, val, env):
7373 if not val in ['red', 'blue', 'yellow']:
7374 raise "Invalid color value '%s'" % val
7375 vars.Add('COLOR', validator=valid_color)
7379 .RI AddVariables( list )
7380 A wrapper script that adds
7381 multiple customizable construction variables
7382 to a Variables object.
7384 is a list of tuple or list objects
7385 that contain the arguments
7386 for an individual call to the
7393 ('CC', 'The C compiler'),
7394 ('VALIDATE', 'An option for testing validation',
7395 'notset', validator, None),
7400 .RI Update( env ", [" args ])
7401 This updates a construction environment
7403 with the customized construction variables.
7404 Any specified variables that are
7406 configured for the Variables object
7407 will be saved and may be
7409 .BR UnknownVariables ()
7412 Normally this method is not called directly,
7413 but is called indirectly by passing the Variables object to
7414 the Environment() function:
7417 env = Environment(variables=vars)
7421 The text file(s) that were specified
7422 when the Variables object was created
7423 are executed as Python scripts,
7424 and the values of (global) Python variables set in the file
7425 are added to the construction environment.
7434 .RI UnknownVariables( )
7435 Returns a dictionary containing any
7436 variables that were specified
7437 either in the files or the dictionary
7438 with which the Variables object was initialized,
7439 but for which the Variables object was
7443 env = Environment(variables=vars)
7444 for key, value in vars.UnknownVariables():
7445 print "unknown variable: %s=%s" % (key, value)
7449 .RI Save( filename ", " env )
7450 This saves the currently set variables into a script file named
7452 that can be used on the next invocation to automatically load the current
7453 settings. This method combined with the Variables method can be used to
7454 support caching of variables between runs.
7458 vars = Variables(['variables.cache', 'custom.py'])
7461 vars.Save('variables.cache', env)
7465 .RI GenerateHelpText( env ", [" sort ])
7466 This generates help text documenting the customizable construction
7467 variables suitable to passing in to the Help() function.
7469 is the construction environment that will be used to get the actual values
7470 of customizable variables. Calling with
7474 will cause the output to be sorted
7475 by the specified argument.
7479 should take two arguments
7482 (like the standard Python
7487 Help(vars.GenerateHelpText(env))
7488 Help(vars.GenerateHelpText(env, sort=cmp))
7492 .RI FormatVariableHelpText( env ", " opt ", " help ", " default ", " actual )
7493 This method returns a formatted string
7494 containing the printable help text
7496 It is normally not called directly,
7497 but is called by the
7498 .IR GenerateHelpText ()
7499 method to create the returned help text.
7500 It may be overridden with your own
7501 function that takes the arguments specified above
7502 and returns a string of help text formatted to your liking.
7504 .IR GenerateHelpText ()
7505 will not put any blank lines or extra
7506 characters in between the entries,
7507 so you must add those characters to the returned
7508 string if you want the entries separated.
7511 def my_format(env, opt, help, default, actual):
7512 fmt = "\n%s: default=%s actual=%s (%s)\n"
7513 return fmt % (opt, default. actual, help)
7514 vars.FormatVariableHelpText = my_format
7517 To make it more convenient to work with customizable Variables,
7519 provides a number of functions
7520 that make it easy to set up
7521 various types of Variables:
7524 .RI BoolVariable( key ", " help ", " default )
7525 Return a tuple of arguments
7526 to set up a Boolean option.
7530 have a default value of
7532 and display the specified
7535 The option will interpret the values
7557 .RI EnumVariable( key ", " help ", " default ", " allowed_values ", [" map ", " ignorecase ])
7558 Return a tuple of arguments
7560 whose value may be one
7561 of a specified list of legal enumerated values.
7565 have a default value of
7567 and display the specified
7570 The option will only support those
7576 argument is a dictionary
7577 that can be used to convert
7578 input values into specific legal values
7587 then the values are case-sensitive.
7592 then values will be matched
7598 then values will be matched
7600 and all input values will be
7601 converted to lower case.
7604 .RI ListVariable( key ", " help ", " default ", " names ", [", map ])
7605 Return a tuple of arguments
7607 whose value may be one or more
7608 of a specified list of legal enumerated values.
7612 have a default value of
7614 and display the specified
7617 The option will only support the values
7620 or the values in the
7623 More than one value may be specified,
7624 with all values separated by commas.
7625 The default may be a string of
7626 comma-separated default values,
7627 or a list of the default values.
7630 argument is a dictionary
7631 that can be used to convert
7632 input values into specific legal values
7638 .RI PackageVariable( key ", " help ", " default )
7639 Return a tuple of arguments
7641 whose value is a path name
7642 of a package that may be
7643 enabled, disabled or
7644 given an explicit path name.
7648 have a default value of
7650 and display the specified
7653 The option will support the values
7660 in which case the specified
7663 or the option may be set to an
7665 (typically the path name to a package
7666 that is being enabled).
7667 The option will also support the values
7673 to disable use of the specified option.
7676 .RI PathVariable( key ", " help ", " default ", [" validator ])
7677 Return a tuple of arguments
7679 whose value is expected to be a path name.
7683 have a default value of
7685 and display the specified
7691 that will be called to
7692 verify that the specified path
7695 following ready-made validators:
7696 .BR PathVariable.PathExists
7698 which verifies that the specified path exists;
7699 .BR PathVariable.PathIsFile ,
7700 which verifies that the specified path is an existing file;
7701 .BR PathVariable.PathIsDir ,
7702 which verifies that the specified path is an existing directory;
7703 .BR PathVariable.PathIsDirCreate ,
7704 which verifies that the specified path is a directory
7705 and will create the specified directory if the path does not exist;
7707 .BR PathVariable.PathAccept ,
7708 which simply accepts the specific path name argument without validation,
7709 and which is suitable if you want your users
7710 to be able to specify a directory path that will be
7711 created as part of the build process, for example.
7712 You may supply your own
7715 which must take three arguments
7717 the name of the variable to be set;
7719 the specified value being checked;
7722 the construction environment)
7723 and should raise an exception
7724 if the specified value is not acceptable.
7727 These functions make it
7728 convenient to create a number
7729 of variables with consistent behavior
7730 in a single call to the
7736 BoolVariable('warnings', 'compilation with -Wall and similiar', 1),
7737 EnumVariable('debug', 'debug output and symbols', 'no'
7738 allowed_values=('yes', 'no', 'full'),
7739 map={}, ignorecase=0), # case sensitive
7740 ListVariable('shared',
7741 'libraries to build as shared libraries',
7743 names = list_of_libs),
7744 PackageVariable('x11',
7745 'use X11 installed here (yes = search some places)',
7747 PathVariable('qtdir', 'where the root of Qt is installed', qtdir),
7748 PathVariable('foopath', 'where the foo library is installed', foopath,
7749 PathVariable.PathIsDir),
7754 .SS File and Directory Nodes
7764 Nodes, respectively.
7765 python objects, respectively.
7766 Those objects have several user-visible attributes
7767 and methods that are often useful:
7773 This path is relative to the top-level directory
7777 The build path is the same as the source path if
7782 The absolute build path of the given file or directory.
7792 object representing the
7801 # Get the current build dir's path, relative to top.
7803 # Current dir's absolute path
7805 # Next line is always '.', because it is the top dir's path relative to itself.
7807 File('foo.c').srcnode().path # source path of the given source file.
7809 # Builders also return File objects:
7810 foo = env.Program('foo.c')
7811 print "foo will be built in %s"%foo.path
7818 Node can also be used to create
7819 file and subdirectory Nodes relative to the generating Node.
7822 Node will place the new Nodes within the directory it represents.
7825 node will place the new Nodes within its parent directory
7826 (that is, "beside" the file in question).
7831 (directory) Node and
7836 then these methods are available:
7840 Returns a directory Node for a subdirectory of
7847 Returns a file Node for a file within
7853 .IR d .Entry( name )
7854 Returns an unresolved Node within
7861 Returns a directory named
7863 within the parent directory of
7868 Returns a file named
7870 within the parent directory of
7874 .IR f .Entry( name )
7875 Returns an unresolved Node named
7877 within the parent directory of
7884 # Get a Node for a file within a directory
7885 incl = Dir('include')
7886 f = incl.File('header.h')
7888 # Get a Node for a subdirectory within a directory
7889 dist = Dir('project-3.2.1)
7890 src = dist.Dir('src')
7892 # Get a Node for a file in the same directory
7893 cfile = File('sample.c')
7894 hfile = cfile.File('sample.h')
7898 html = docs.Dir('html')
7899 index = html.File('index.html')
7900 css = index.File('app.css')
7906 can be extended to build different types of targets
7907 by adding new Builder objects
7908 to a construction environment.
7910 you should only need to add a new Builder object
7911 when you want to build a new type of file or other external target.
7912 If you just want to invoke a different compiler or other tool
7913 to build a Program, Object, Library, or any other
7914 type of output file for which
7916 already has an existing Builder,
7917 it is generally much easier to
7918 use those existing Builders
7919 in a construction environment
7920 that sets the appropriate construction variables
7923 Builder objects are created
7929 function accepts the following arguments:
7932 The command line string used to build the target from the source.
7935 a list of strings representing the command
7936 to be executed and its arguments
7937 (suitable for enclosing white space in an argument),
7939 mapping source file name suffixes to
7940 any combination of command line strings
7941 (if the builder should accept multiple source file extensions),
7944 (see the next section);
7945 or a list of any of the above.
7948 takes three arguments:
7950 - a list of source nodes,
7952 - a list of target nodes,
7954 - the construction environment.
7957 The prefix that will be prepended to the target file name.
7958 This may be specified as a:
7968 - a function or other callable that takes
7969 two arguments (a construction environment and a list of sources)
7970 and returns a prefix,
7975 - specifies a mapping from a specific source suffix (of the first
7976 source specified) to a corresponding target prefix. Both the source
7977 suffix and target prefix specifications may use environment variable
7978 substitution, and the target prefix (the 'value' entries in the
7979 dictionary) may also be a callable object. The default target prefix
7980 may be indicated by a dictionary entry with a key value of None.
7985 b = Builder("build_it < $SOURCE > $TARGET"
7988 def gen_prefix(env, sources):
7989 return "file-" + env['PLATFORM'] + '-'
7990 b = Builder("build_it < $SOURCE > $TARGET",
7991 prefix = gen_prefix)
7993 b = Builder("build_it < $SOURCE > $TARGET",
7994 suffix = { None: "file-",
7995 "$SRC_SFX_A": gen_prefix })
7999 The suffix that will be appended to the target file name.
8000 This may be specified in the same manner as the prefix above.
8001 If the suffix is a string, then
8003 will append a '.' to the beginning of the suffix if it's not already
8004 there. The string returned by callable object (or obtained from the
8005 dictionary) is untouched and must append its own '.' to the beginning
8009 b = Builder("build_it < $SOURCE > $TARGET"
8012 def gen_suffix(env, sources):
8013 return "." + env['PLATFORM'] + "-file"
8014 b = Builder("build_it < $SOURCE > $TARGET",
8015 suffix = gen_suffix)
8017 b = Builder("build_it < $SOURCE > $TARGET",
8018 suffix = { None: ".sfx1",
8019 "$SRC_SFX_A": gen_suffix })
8023 When set to any true value, causes
8025 to add the target suffix specified by the
8027 keyword to any target strings
8028 that have a different suffix.
8029 (The default behavior is to leave untouched
8030 any target file name that looks like it already has any suffix.)
8033 b1 = Builder("build_it < $SOURCE > $TARGET"
8035 b2 = Builder("build_it < $SOURCE > $TARGET"
8039 env['BUILDERS']['B1'] = b1
8040 env['BUILDERS']['B2'] = b2
8042 # Builds "foo.txt" because ensure_suffix is not set.
8043 env.B1('foo.txt', 'foo.in')
8045 # Builds "bar.txt.out" because ensure_suffix is set.
8046 env.B2('bar.txt', 'bar.in')
8050 The expected source file name suffix. This may be a string or a list
8054 A Scanner object that
8055 will be invoked to find
8056 implicit dependencies for this target file.
8057 This keyword argument should be used
8058 for Scanner objects that find
8059 implicit dependencies
8060 based only on the target file
8061 and the construction environment,
8064 (See the section "Scanner Objects," below,
8065 for information about creating Scanner objects.)
8068 A Scanner object that
8070 find implicit dependences in
8072 used to build this target file.
8073 This is where you would
8074 specify a scanner to
8077 lines in source files.
8080 Scanner object may be used to
8081 indicate that this Builder
8082 should scan directory trees
8083 for on-disk changes to files
8086 does not know about from other Builder or function calls.
8087 (See the section "Scanner Objects," below,
8088 for information about creating your own Scanner objects.)
8091 A factory function that the Builder will use
8092 to turn any targets specified as strings into SCons Nodes.
8094 SCons assumes that all targets are files.
8095 Other useful target_factory
8098 for when a Builder creates a directory target,
8101 for when a Builder can create either a file
8102 or directory target.
8107 MakeDirectoryBuilder = Builder(action=my_mkdir, target_factory=Dir)
8109 env.Append(BUILDERS = {'MakeDirectory':MakeDirectoryBuilder})
8110 env.MakeDirectory('new_directory', [])
8114 Note that the call to the MakeDirectory Builder
8115 needs to specify an empty source list
8116 to make the string represent the builder's target;
8117 without that, it would assume the argument is the source,
8118 and would try to deduce the target name from it,
8119 which in the absence of an automatically-added prefix or suffix
8120 would lead to a matching target and source name
8121 and a circular dependency.
8124 A factory function that the Builder will use
8125 to turn any sources specified as strings into SCons Nodes.
8127 SCons assumes that all source are files.
8128 Other useful source_factory
8131 for when a Builder uses a directory as a source,
8134 for when a Builder can use files
8135 or directories (or both) as sources.
8140 CollectBuilder = Builder(action=my_mkdir, source_factory=Entry)
8142 env.Append(BUILDERS = {'Collect':CollectBuilder})
8143 env.Collect('archive', ['directory_name', 'file_name'])
8147 A function or list of functions to manipulate the target and source
8148 lists before dependencies are established
8149 and the target(s) are actually built.
8151 can also be a string containing a construction variable to expand
8152 to an emitter function or list of functions,
8153 or a dictionary mapping source file suffixes
8154 to emitter functions.
8155 (Only the suffix of the first source file
8156 is used to select the actual emitter function
8157 from an emitter dictionary.)
8160 takes three arguments:
8162 - a list of source nodes,
8164 - a list of target nodes,
8166 - the construction environment.
8167 An emitter must return a tuple containing two lists,
8168 the list of targets to be built by this builder,
8169 and the list of sources for this builder.
8174 def e(target, source, env):
8175 return (target + ['foo.foo'], source + ['foo.src'])
8177 # Simple association of an emitter function with a Builder.
8178 b = Builder("my_build < $TARGET > $SOURCE",
8181 def e2(target, source, env):
8182 return (target + ['bar.foo'], source + ['bar.src'])
8184 # Simple association of a list of emitter functions with a Builder.
8185 b = Builder("my_build < $TARGET > $SOURCE",
8188 # Calling an emitter function through a construction variable.
8189 env = Environment(MY_EMITTER = e)
8190 b = Builder("my_build < $TARGET > $SOURCE",
8191 emitter = '$MY_EMITTER')
8193 # Calling a list of emitter functions through a construction variable.
8194 env = Environment(EMITTER_LIST = [e, e2])
8195 b = Builder("my_build < $TARGET > $SOURCE",
8196 emitter = '$EMITTER_LIST')
8198 # Associating multiple emitters with different file
8199 # suffixes using a dictionary.
8200 def e_suf1(target, source, env):
8201 return (target + ['another_target_file'], source)
8202 def e_suf2(target, source, env):
8203 return (target, source + ['another_source_file'])
8204 b = Builder("my_build < $TARGET > $SOURCE",
8205 emitter = {'.suf1' : e_suf1,
8210 Specifies whether this builder is allowed to be called multiple times for
8211 the same target file(s). The default is 0, which means the builder
8212 can not be called multiple times for the same target file(s). Calling a
8213 builder multiple times for the same target simply adds additional source
8214 files to the target; it is not allowed to change the environment associated
8215 with the target, specify addition environment overrides, or associate a different
8216 builder with the target.
8219 A construction environment that can be used
8220 to fetch source code using this Builder.
8221 (Note that this environment is
8223 used for normal builds of normal target files,
8224 which use the environment that was
8225 used to call the Builder for the target file.)
8228 A function that returns a list of actions that will be executed to build
8229 the target(s) from the source(s).
8230 The returned action(s) may be
8231 an Action object, or anything that
8232 can be converted into an Action object
8233 (see the next section).
8235 The generator function
8236 takes four arguments:
8238 - a list of source nodes,
8240 - a list of target nodes,
8242 - the construction environment,
8244 - a Boolean value that specifies
8245 whether the generator is being called
8246 for generating a build signature
8247 (as opposed to actually executing the command).
8251 def g(source, target, env, for_signature):
8252 return [["gcc", "-c", "-o"] + target + source]
8254 b = Builder(generator=g)
8262 arguments must not both be used for the same Builder.
8265 Specifies a builder to use when a source file name suffix does not match
8266 any of the suffixes of the builder. Using this argument produces a
8267 multi-stage builder.
8270 Specifies that this builder expects exactly one source file per call. Giving
8271 more than one source files without target files results in implicitely calling
8272 the builder multiple times (once for each source given). Giving multiple
8273 source files together with target files results in a UserError exception.
8281 arguments must not both be used for the same Builder.
8283 .IP source_ext_match
8286 argument is a dictionary,
8287 the default behavior when a builder is passed
8288 multiple source files is to make sure that the
8289 extensions of all the source files match.
8290 If it is legal for this builder to be
8291 called with a list of source files with different extensions,
8292 this check can be suppressed by setting
8296 or some other non-true value.
8301 will use the suffix of the first specified
8302 source file to select the appropriate action from the
8306 In the following example,
8311 from exiting with an error
8312 due to the mismatched suffixes of
8318 b = Builder(action={'.in' : 'build $SOURCES > $TARGET'},
8319 source_ext_match = None)
8321 env = Environment(BUILDERS = {'MyBuild':b})
8322 env.MyBuild('foo.out', ['foo.in', 'foo.extra'])
8326 A construction environment that can be used
8327 to fetch source code using this Builder.
8328 (Note that this environment is
8330 used for normal builds of normal target files,
8331 which use the environment that was
8332 used to call the Builder for the target file.)
8335 b = Builder(action="build < $SOURCE > $TARGET")
8336 env = Environment(BUILDERS = {'MyBuild' : b})
8337 env.MyBuild('foo.out', 'foo.in', my_arg = 'xyzzy')
8341 A directory from which scons
8348 a string or a directory Node,
8349 scons will change to the specified directory.
8352 is not a string or Node
8354 then scons will change to the
8355 target file's directory.
8357 Note that scons will
8359 automatically modify
8361 construction variables like
8365 when using the chdir
8366 keyword argument--that is,
8367 the expanded file names
8368 will still be relative to
8369 the top-level SConstruct directory,
8370 and consequently incorrect
8371 relative to the chdir directory.
8372 Builders created using chdir keyword argument,
8373 will need to use construction variable
8378 to use just the filename portion of the
8382 b = Builder(action="build < ${SOURCE.file} > ${TARGET.file}",
8384 env = Environment(BUILDERS = {'MyBuild' : b})
8385 env.MyBuild('sub/dir/foo.out', 'sub/dir/foo.in')
8389 Python only keeps one current directory
8390 location for all of the threads.
8391 This means that use of the
8399 because individual worker threads spawned
8400 by SCons interfere with each other
8401 when they start changing directory.
8404 Any additional keyword arguments supplied
8405 when a Builder object is created
8406 (that is, when the Builder() function is called)
8407 will be set in the executing construction
8408 environment when the Builder object is called.
8409 The canonical example here would be
8410 to set a construction variable to
8411 the repository of a source code system.
8413 Any additional keyword arguments supplied
8417 will only be associated with the target
8418 created by that particular Builder call
8419 (and any other files built as a
8420 result of the call).
8422 These extra keyword arguments are passed to the
8423 following functions:
8424 command generator functions,
8426 and emitter functions.
8432 function will turn its
8434 keyword argument into an appropriate
8435 internal Action object.
8436 You can also explicity create Action objects
8440 which can then be passed to the
8443 This can be used to configure
8444 an Action object more flexibly,
8445 or it may simply be more efficient
8446 than letting each separate Builder object
8447 create a separate Action
8449 Builder objects need to do the same thing.
8454 returns an appropriate object for the action
8455 represented by the type of the first argument:
8458 If the first argument is already an Action object,
8459 the object is simply returned.
8462 If the first argument is a string,
8463 a command-line Action is returned.
8464 Note that the command-line string
8465 may be preceded by an
8468 to suppress printing of the specified command line,
8472 to ignore the exit status from the specified command:
8475 Action('$CC -c -o $TARGET $SOURCES')
8477 # Doesn't print the line being executed.
8478 Action('@build $TARGET $SOURCES')
8480 # Ignores return value
8481 Action('-build $TARGET $SOURCES')
8483 .\" XXX From Gary Ruben, 23 April 2002:
8484 .\" What would be useful is a discussion of how you execute command
8485 .\" shell commands ie. what is the process used to spawn the shell, pass
8486 .\" environment variables to it etc., whether there is one shell per
8487 .\" environment or one per command etc. It might help to look at the Gnu
8488 .\" make documentation to see what they think is important to discuss about
8489 .\" a build system. I'm sure you can do a better job of organising the
8490 .\" documentation than they have :-)
8493 If the first argument is a list,
8494 then a list of Action objects is returned.
8495 An Action object is created as necessary
8496 for each element in the list.
8499 the list is itself a list,
8500 the internal list is the
8501 command and arguments to be executed via
8503 This allows white space to be enclosed
8504 in an argument by defining
8505 a command in a list within a list:
8508 Action([['cc', '-c', '-DWHITE SPACE', '-o', '$TARGET', '$SOURCES']])
8512 If the first argument is a Python function,
8513 a function Action is returned.
8514 The Python function must take three keyword arguments,
8516 (a Node object representing the target file),
8518 (a Node object representing the source file)
8521 (the construction environment
8522 used for building the target file).
8527 arguments may be lists of Node objects if there is
8528 more than one target file or source file.
8529 The actual target and source file name(s) may
8530 be retrieved from their Node objects
8531 via the built-in Python str() function:
8534 target_file_name = str(target)
8535 source_file_names = map(lambda x: str(x), source)
8538 The function should return
8542 to indicate a successful build of the target file(s).
8543 The function may raise an exception
8544 or return a non-zero exit status
8545 to indicate an unsuccessful build.
8548 def build_it(target = None, source = None, env = None):
8549 # build the target from the source
8552 a = Action(build_it)
8555 If the action argument is not one of the above,
8559 The second argument is optional and is used to define the output
8560 which is printed when the Action is actually performed.
8561 In the absence of this parameter,
8562 or if it's an empty string,
8563 a default output depending on the type of the action is used.
8564 For example, a command-line action will print the executed command.
8565 The argument must be either a Python function or a string.
8568 it's a function that returns a string to be printed
8569 to describe the action being executed.
8570 The function may also be specified by the
8573 Like a function to build a file,
8574 this function must take three keyword arguments:
8576 (a Node object representing the target file),
8578 (a Node object representing the source file)
8581 (a construction environment).
8586 arguments may be lists of Node objects if there is
8587 more than one target file or source file.
8589 In the second case, you provide the string itself.
8590 The string may also be specified by the
8593 The string typically contains variables, notably
8594 $TARGET(S) and $SOURCE(S), or consists of just a single
8595 variable, which is optionally defined somewhere else.
8596 SCons itself heavily uses the latter variant.
8601 def build_it(target, source, env):
8602 # build the target from the source
8605 def string_it(target, source, env):
8606 return "building '%s' from '%s'" % (target[0], source[0])
8608 # Use a positional argument.
8609 f = Action(build_it, string_it)
8610 s = Action(build_it, "building '$TARGET' from '$SOURCE'")
8612 # Alternatively, use a keyword argument.
8613 f = Action(build_it, strfunction=string_it)
8614 s = Action(build_it, cmdstr="building '$TARGET' from '$SOURCE'")
8616 # You can provide a configurable variable.
8617 l = Action(build_it, '$STRINGIT')
8620 The third and succeeding arguments, if present,
8621 may either be a construction variable or a list of construction variables
8622 whose values will be included in the signature of the Action
8623 when deciding whether a target should be rebuilt because the action changed.
8624 The variables may also be specified by a
8627 if both are present, they are combined.
8628 This is necessary whenever you want a target to be rebuilt
8629 when a specific construction variable changes.
8630 This is not often needed for a string action,
8631 as the expanded variables will normally be part of the command line,
8632 but may be needed if a Python function action uses
8633 the value of a construction variable when generating the command line.
8636 def build_it(target, source, env):
8637 # build the target from the 'XXX' construction variable
8638 open(target[0], 'w').write(env['XXX'])
8641 # Use positional arguments.
8642 a = Action(build_it, '$STRINGIT', ['XXX'])
8644 # Alternatively, use a keyword argument.
8645 a = Action(build_it, varlist=['XXX'])
8651 can be passed the following
8652 optional keyword arguments
8653 to modify the Action object's behavior:
8659 keyword argument specifies that
8660 scons will execute the action
8661 after changing to the specified directory.
8665 a string or a directory Node,
8666 scons will change to the specified directory.
8670 is not a string or Node
8672 then scons will change to the
8673 target file's directory.
8675 Note that scons will
8677 automatically modify
8679 construction variables like
8683 when using the chdir
8684 keyword argument--that is,
8685 the expanded file names
8686 will still be relative to
8687 the top-level SConstruct directory,
8688 and consequently incorrect
8689 relative to the chdir directory.
8690 Builders created using chdir keyword argument,
8691 will need to use construction variable
8696 to use just the filename portion of the
8700 a = Action("build < ${SOURCE.file} > ${TARGET.file}",
8712 which specifies a function
8713 that is passed the exit status
8715 from the specified action
8716 and can return an arbitrary
8718 This can be used, for example,
8719 to specify that an Action object's
8720 return value should be ignored
8721 under special conditions
8722 and SCons should, therefore,
8723 consider that the action always suceeds:
8726 def always_succeed(s):
8727 # Always return 0, which indicates success.
8729 a = Action("build < ${SOURCE.file} > ${TARGET.file}",
8730 exitstatfunc=always_succeed)
8737 keyword argument can be used
8738 to specify that the Action can create multiple target files
8739 by processing multiple independent source files simultaneously.
8740 (The canonical example is "batch compilation"
8741 of multiple object files
8742 by passing multiple source files
8743 to a single invocation of a compiler
8744 such as Microsoft's Visual C / C++ compiler.)
8747 argument is any non-False, non-callable Python value,
8748 the configured Action object will cause
8750 to collect all targets built with the Action object
8751 and configured with the same construction environment
8752 into single invocations of the Action object's
8753 command line or function.
8754 Command lines will typically want to use the
8756 construction variable
8760 to only pass to the command line those sources that
8761 have actually changed since their targets were built.
8766 a = Action('build $CHANGED_SOURCES', batch_key=True)
8771 argument may also be
8773 that returns a key that
8774 will be used to identify different
8775 "batches" of target files to be collected
8779 function must take the following arguments:
8785 The construction environment
8786 configured for the target.
8789 The list of targets for a particular configured action.
8792 The list of source for a particular configured action.
8794 The returned key should typically
8795 be a tuple of values derived from the arguments,
8796 using any appropriate logic to decide
8797 how multiple invocations should be batched.
8800 function may decide to return
8801 the value of a specific construction
8807 to batch-build targets
8808 with matching values of that variable,
8809 or perhaps return the
8811 of the entire construction environment,
8815 all targets configured with the same construction environment.
8819 the particular target should
8821 be part of any batched build,
8822 but instead will be built
8823 by a separate invocation of action's
8824 command or function.
8828 def batch_key(action, env, target, source):
8829 tdir = target[0].dir
8830 if tdir.name == 'special':
8831 # Don't batch-build any target
8832 # in the special/ subdirectory.
8834 return (id(action), id(env), tdir)
8835 a = Action('build $CHANGED_SOURCES', batch_key=batch_key)
8838 .SS Miscellaneous Action Functions
8841 supplies a number of functions
8842 that arrange for various common
8843 file and directory manipulations
8845 These are similar in concept to "tasks" in the
8847 although the implementation is slightly different.
8848 These functions do not actually
8849 perform the specified action
8850 at the time the function is called,
8851 but instead return an Action object
8852 that can be executed at the
8854 (In Object-Oriented terminology,
8859 that return Action objects.)
8862 there are two natural ways
8865 are intended to be used.
8869 to perform the action
8870 at the time the SConscript
8874 global function to do so:
8876 Execute(Touch('file'))
8880 you can use these functions
8881 to supply Actions in a list
8885 This can allow you to
8886 perform more complicated
8887 sequences of file manipulation
8889 on platform-specific
8893 env = Environment(TMPBUILD = '/tmp/builddir')
8894 env.Command('foo.out', 'foo.in',
8895 [Mkdir('$TMPBUILD'),
8896 Copy('$TMPBUILD', '${SOURCE.dir}'),
8897 "cd $TMPBUILD && make",
8898 Delete('$TMPBUILD')])
8902 .RI Chmod( dest ", " mode )
8903 Returns an Action object that
8904 changes the permissions on the specified
8906 file or directory to the specified
8911 Execute(Chmod('file', 0755))
8913 env.Command('foo.out', 'foo.in',
8914 [Copy('$TARGET', '$SOURCE'),
8915 Chmod('$TARGET', 0755)])
8919 .RI Copy( dest ", " src )
8920 Returns an Action object
8923 source file or directory to the
8925 destination file or directory.
8929 Execute(Copy('foo.output', 'foo.input'))
8931 env.Command('bar.out', 'bar.in',
8932 Copy('$TARGET', '$SOURCE'))
8936 .RI Delete( entry ", [" must_exist ])
8937 Returns an Action that
8938 deletes the specified
8940 which may be a file or a directory tree.
8941 If a directory is specified,
8942 the entire directory tree
8947 then a Python error will be thrown
8948 if the specified entry does not exist;
8951 that is, the Action will silently do nothing
8952 if the entry does not exist.
8956 Execute(Delete('/tmp/buildroot'))
8958 env.Command('foo.out', 'foo.in',
8959 [Delete('${TARGET.dir}'),
8962 Execute(Delete('file_that_must_exist', must_exist=1))
8968 that creates the specified
8974 Execute(Mkdir('/tmp/outputdir'))
8976 env.Command('foo.out', 'foo.in',
8977 [Mkdir('/tmp/builddir'),
8978 Copy('/tmp/builddir/foo.in', '$SOURCE'),
8979 "cd /tmp/builddir && make",
8980 Copy('$TARGET', '/tmp/builddir/foo.out')])
8984 .RI Move( dest ", " src )
8986 that moves the specified
8988 file or directory to
8995 Execute(Move('file.destination', 'file.source'))
8997 env.Command('output_file', 'input_file',
8999 Move('$TARGET', 'file_created_by_MyBuildAction')])
9005 that updates the modification time
9011 Execute(Touch('file_to_be_touched'))
9013 env.Command('marker', 'input_file',
9018 .SS Variable Substitution
9020 Before executing a command,
9022 performs construction variable interpolation on the strings that make up
9023 the command line of builders.
9024 Variables are introduced by a
9027 Besides construction variables, scons provides the following
9028 variables for each command execution:
9031 The file names of all sources of the build command
9032 that have changed since the target was last built.
9035 The file names of all targets that would be built
9036 from sources that have changed since the target was last built.
9039 The file name of the source of the build command,
9040 or the file name of the first source
9041 if multiple sources are being built.
9044 The file names of the sources of the build command.
9047 The file name of the target being built,
9048 or the file name of the first target
9049 if multiple targets are being built.
9052 The file names of all targets being built.
9054 .IP UNCHANGED_SOURCES
9055 The file names of all sources of the build command
9058 changed since the target was last built.
9060 .IP UNCHANGED_TARGETS
9061 The file names of all targets that would be built
9062 from sources that have
9064 changed since the target was last built.
9066 (Note that the above variables are reserved
9067 and may not be set in a construction environment.)
9070 For example, given the construction variable CC='cc', targets=['foo'], and
9071 sources=['foo.c', 'bar.c']:
9074 action='$CC -c -o $TARGET $SOURCES'
9077 would produce the command line:
9080 cc -c -o foo foo.c bar.c
9083 Variable names may be surrounded by curly braces ({})
9084 to separate the name from the trailing characters.
9085 Within the curly braces, a variable name may have
9086 a Python slice subscript appended to select one
9087 or more items from a list.
9088 In the previous example, the string:
9100 Additionally, a variable name may
9101 have the following special
9102 modifiers appended within the enclosing curly braces
9103 to modify the interpolated string:
9106 The base path of the file name,
9107 including the directory path
9108 but excluding any suffix.
9111 The name of the directory in which the file exists.
9115 minus any directory portion.
9118 Just the basename of the file,
9120 and minus the directory.
9123 Just the file suffix.
9126 The absolute path name of the file.
9129 The POSIX form of the path,
9130 with directories separated by
9134 This is sometimes necessary on Windows systems
9135 when a path references a file on other (POSIX) systems.
9138 The directory and file name to the source file linked to this file through
9140 If this file isn't linked,
9141 it just returns the directory and filename unchanged.
9144 The directory containing the source file linked to this file through
9146 If this file isn't linked,
9147 it just returns the directory part of the filename.
9150 The directory and file name to the source file linked to this file through
9152 If the file does not exist locally but exists in a Repository,
9153 the path in the Repository is returned.
9154 If this file isn't linked, it just returns the
9155 directory and filename unchanged.
9158 The Repository directory containing the source file linked to this file through
9160 If this file isn't linked,
9161 it just returns the directory part of the filename.
9164 For example, the specified target will
9165 expand as follows for the corresponding modifiers:
9168 $TARGET => sub/dir/file.x
9169 ${TARGET.base} => sub/dir/file
9170 ${TARGET.dir} => sub/dir
9171 ${TARGET.file} => file.x
9172 ${TARGET.filebase} => file
9173 ${TARGET.suffix} => .x
9174 ${TARGET.abspath} => /top/dir/sub/dir/file.x
9176 SConscript('src/SConscript', variant_dir='sub/dir')
9177 $SOURCE => sub/dir/file.x
9178 ${SOURCE.srcpath} => src/file.x
9179 ${SOURCE.srcdir} => src
9181 Repository('/usr/repository')
9182 $SOURCE => sub/dir/file.x
9183 ${SOURCE.rsrcpath} => /usr/repository/src/file.x
9184 ${SOURCE.rsrcdir} => /usr/repository/src
9187 Note that curly braces braces may also be used
9188 to enclose arbitrary Python code to be evaluated.
9189 (In fact, this is how the above modifiers are substituted,
9190 they are simply attributes of the Python objects
9191 that represent TARGET, SOURCES, etc.)
9192 See the section "Python Code Substitution," below,
9193 for more thorough examples of
9194 how this can be used.
9196 Lastly, a variable name
9197 may be a callable Python function
9199 construction variable in the environment.
9201 take four arguments:
9203 - a list of target nodes,
9205 - a list of source nodes,
9207 - the construction environment,
9209 - a Boolean value that specifies
9210 whether the function is being called
9211 for generating a build signature.
9212 SCons will insert whatever
9213 the called function returns
9214 into the expanded string:
9217 def foo(target, source, env, for_signature):
9220 # Will expand $BAR to "bar baz"
9221 env=Environment(FOO=foo, BAR="$FOO baz")
9224 You can use this feature to pass arguments to a
9225 Python function by creating a callable class
9226 that stores one or more arguments in an object,
9227 and then uses them when the
9230 Note that in this case,
9231 the entire variable expansion must
9232 be enclosed by curly braces
9233 so that the arguments will
9234 be associated with the
9235 instantiation of the class:
9239 def __init__(self, arg):
9242 def __call__(self, target, source, env, for_signature):
9243 return self.arg + " bar"
9245 # Will expand $BAR to "my argument bar baz"
9246 env=Environment(FOO=foo, BAR="${FOO('my argument')} baz")
9250 The special pseudo-variables
9254 may be used to surround parts of a command line
9257 causing a rebuild--that is,
9258 which are not included in the signature
9259 of target files built with this command.
9264 will be removed from the command line
9265 before it is added to file signatures,
9270 will be removed before the command is executed.
9271 For example, the command line:
9274 echo Last build occurred $( $TODAY $). > $TARGET
9278 would execute the command:
9281 echo Last build occurred $TODAY. > $TARGET
9285 but the command signature added to any target files would be:
9288 echo Last build occurred . > $TARGET
9291 .SS Python Code Substitution
9293 Any python code within
9295 pairs gets evaluated by python 'eval', with the python globals set to
9296 the current environment's set of construction variables.
9297 So in the following case:
9300 env.Command('foo.out', 'foo.in',
9301 '''echo ${COND==1 and 'FOO' or 'BAR'} > $TARGET''')
9303 the command executed will be either
9311 according to the current value of env['COND'] when the command is
9312 executed. The evaluation occurs when the target is being
9313 built, not when the SConscript is being read. So if env['COND'] is changed
9314 later in the SConscript, the final value will be used.
9316 Here's a more interesting example. Note that all of COND, FOO, and
9317 BAR are environment variables, and their values are substituted into
9318 the final command. FOO is a list, so its elements are interpolated
9319 separated by spaces.
9324 env['FOO'] = ['foo1', 'foo2']
9325 env['BAR'] = 'barbar'
9326 env.Command('foo.out', 'foo.in',
9327 'echo ${COND==1 and FOO or BAR} > $TARGET')
9329 # Will execute this:
9330 # echo foo1 foo2 > foo.out
9333 SCons uses the following rules when converting construction variables into
9337 When the value is a string it is interpreted as a space delimited list of
9338 command line arguments.
9341 When the value is a list it is interpreted as a list of command line
9342 arguments. Each element of the list is converted to a string.
9345 Anything that is not a list or string is converted to a string and
9346 interpreted as a single command line argument.
9349 Newline characters (\\n) delimit lines. The newline parsing is done after
9350 all other parsing, so it is not possible for arguments (e.g. file names) to
9351 contain embedded newline characters. This limitation will likely go away in
9352 a future version of SCons.
9360 new file types for implicit dependencies.
9361 Scanner accepts the following arguments:
9365 1) a Python function that will process
9367 and return a list of strings (file names)
9368 representing the implicit
9369 dependencies found in the contents;
9371 2) a dictionary that maps keys
9372 (typically the file suffix, but see below for more discussion)
9373 to other Scanners that should be called.
9375 If the argument is actually a Python function,
9376 the function must take three or four arguments:
9378 def scanner_function(node, env, path):
9380 def scanner_function(node, env, path, arg=None):
9384 argument is the internal
9385 SCons node representing the file.
9388 to fetch the name of the file, and
9389 .B node.get_contents()
9390 to fetch contents of the file.
9391 Note that the file is
9393 guaranteed to exist before the scanner is called,
9394 so the scanner function should check that
9395 if there's any chance that the scanned file
9397 (for example, if it's built from other files).
9401 argument is the construction environment for the scan.
9402 Fetch values from it using the
9408 argument is a tuple (or list)
9409 of directories that can be searched
9411 This will usually be the tuple returned by the
9413 argument (see below).
9417 argument is the argument supplied
9418 when the scanner was created, if any.
9421 The name of the Scanner.
9423 to identify the Scanner internally.
9426 An optional argument that, if specified,
9427 will be passed to the scanner function
9429 and the path function
9433 An optional list that can be used to
9434 determine which scanner should be used for
9436 In the usual case of scanning for file names,
9437 this argument will be a list of suffixes
9438 for the different file types that this
9439 Scanner knows how to scan.
9440 If the argument is a string,
9441 then it will be expanded
9442 into a list by the current environment.
9445 A Python function that takes four or five arguments:
9446 a construction environment,
9447 a Node for the directory containing
9448 the SConscript file in which
9449 the first target was defined,
9450 a list of target nodes,
9451 a list of source nodes,
9452 and an optional argument supplied
9453 when the scanner was created.
9456 returns a tuple of directories
9457 that can be searched for files to be returned
9458 by this Scanner object.
9461 function can be used to return a ready-made
9463 for a given construction variable name,
9464 instead of having to write your own function from scratch.)
9467 The class of Node that should be returned
9468 by this Scanner object.
9469 Any strings or other objects returned
9470 by the scanner function
9471 that are not of this class
9472 will be run through the
9477 A Python function that will take a string
9479 and turn it into the appropriate class of Node
9480 to be returned by this Scanner object.
9483 An optional Python function that takes two arguments,
9484 a Node (file) and a construction environment,
9485 and returns whether the
9486 Node should, in fact,
9487 be scanned for dependencies.
9488 This check can be used to eliminate unnecessary
9489 calls to the scanner function when,
9490 for example, the underlying file
9491 represented by a Node does not yet exist.
9494 An optional flag that
9495 specifies whether this scanner should be re-invoked
9496 on the dependency files returned by the scanner.
9497 When this flag is not set,
9498 the Node subsystem will
9499 only invoke the scanner on the file being scanned,
9500 and not (for example) also on the files
9501 specified by the #include lines
9502 in the file being scanned.
9504 may be a callable function,
9505 in which case it will be called with a list of
9507 should return a list of Nodes
9508 that should be scanned recursively;
9509 this can be used to select a specific subset of
9510 Nodes for additional scanning.
9515 .B SourceFileScanner
9516 object that is used by
9519 .BR SharedObject (),
9523 which scanner should be used
9524 for different file extensions.
9526 .BR SourceFileScanner.add_scanner ()
9527 method to add your own Scanner object
9531 that builds target programs or
9532 libraries from a list of
9533 source files of different types:
9536 def xyz_scan(node, env, path):
9537 contents = node.get_text_contents()
9538 # Scan the contents and return the included files.
9540 XYZScanner = Scanner(xyz_scan)
9542 SourceFileScanner.add_scanner('.xyx', XYZScanner)
9544 env.Program('my_prog', ['file1.c', 'file2.f', 'file3.xyz'])
9547 .SH SYSTEM-SPECIFIC BEHAVIOR
9548 SCons and its configuration files are very portable,
9549 due largely to its implementation in Python.
9550 There are, however, a few portability
9551 issues waiting to trap the unwary.
9553 SCons handles the upper-case
9555 file suffix differently,
9556 depending on the capabilities of
9557 the underlying system.
9558 On a case-sensitive system
9559 such as Linux or UNIX,
9560 SCons treats a file with a
9562 suffix as a C++ source file.
9563 On a case-insensitive system
9565 SCons treats a file with a
9567 suffix as a C source file.
9569 SCons handles the upper-case
9571 file suffix differently,
9572 depending on the capabilities of
9573 the underlying system.
9574 On a case-sensitive system
9575 such as Linux or UNIX,
9576 SCons treats a file with a
9578 suffix as a Fortran source file
9579 that is to be first run through
9580 the standard C preprocessor.
9581 On a case-insensitive system
9583 SCons treats a file with a
9585 suffix as a Fortran source file that should
9587 be run through the C preprocessor.
9588 .SS Windows: Cygwin Tools and Cygwin Python vs. Windows Pythons
9589 Cygwin supplies a set of tools and utilities
9590 that let users work on a
9591 Windows system using a more POSIX-like environment.
9592 The Cygwin tools, including Cygwin Python,
9594 by sharing an ability to interpret UNIX-like path names.
9595 For example, the Cygwin tools
9596 will internally translate a Cygwin path name
9597 like /cygdrive/c/mydir
9598 to an equivalent Windows pathname
9599 of C:/mydir (equivalent to C:\\mydir).
9602 that are built for native Windows execution,
9603 such as the python.org and ActiveState versions,
9604 do not have the Cygwin path name semantics.
9605 This means that using a native Windows version of Python
9606 to build compiled programs using Cygwin tools
9607 (such as gcc, bison, and flex)
9608 may yield unpredictable results.
9609 "Mixing and matching" in this way
9610 can be made to work,
9611 but it requires careful attention to the use of path names
9612 in your SConscript files.
9614 In practice, users can sidestep
9615 the issue by adopting the following rules:
9617 use the Cygwin-supplied Python interpreter
9619 when using Microsoft Visual C/C++
9620 (or some other Windows compiler)
9621 use the python.org or ActiveState version of Python
9623 .SS Windows: scons.bat file
9625 SCons is executed via a wrapper
9628 This has (at least) two ramifications:
9630 First, Windows command-line users
9631 that want to use variable assignment
9633 may have to put double quotes
9634 around the assignments:
9637 scons "FOO=BAR" "BAZ=BLEH"
9640 Second, the Cygwin shell does not
9641 recognize this file as being the same
9644 command issued at the command-line prompt.
9645 You can work around this either by
9648 from the Cygwin command line,
9649 or by creating a wrapper shell
9655 The MinGW bin directory must be in your PATH environment variable or the
9656 PATH variable under the ENV construction variable for SCons
9657 to detect and use the MinGW tools. When running under the native Windows
9658 Python interpreter, SCons will prefer the MinGW tools over the Cygwin
9659 tools, if they are both installed, regardless of the order of the bin
9660 directories in the PATH variable. If you have both MSVC and MinGW
9661 installed and you want to use MinGW instead of MSVC,
9662 then you must explictly tell SCons to use MinGW by passing
9668 to the Environment() function, because SCons will prefer the MSVC tools
9669 over the MinGW tools.
9673 To help you get started using SCons,
9674 this section contains a brief overview of some common tasks.
9676 .SS Basic Compilation From a Single Source File
9680 env.Program(target = 'foo', source = 'foo.c')
9683 Note: Build the file by specifying
9684 the target as an argument
9685 ("scons foo" or "scons foo.exe").
9686 or by specifying a dot ("scons .").
9688 .SS Basic Compilation From Multiple Source Files
9692 env.Program(target = 'foo', source = Split('f1.c f2.c f3.c'))
9695 .SS Setting a Compilation Flag
9698 env = Environment(CCFLAGS = '-g')
9699 env.Program(target = 'foo', source = 'foo.c')
9702 .SS Search The Local Directory For .h Files
9706 need to set CCFLAGS to specify -I options by hand.
9707 SCons will construct the right -I options from CPPPATH.
9710 env = Environment(CPPPATH = ['.'])
9711 env.Program(target = 'foo', source = 'foo.c')
9714 .SS Search Multiple Directories For .h Files
9717 env = Environment(CPPPATH = ['include1', 'include2'])
9718 env.Program(target = 'foo', source = 'foo.c')
9721 .SS Building a Static Library
9725 env.StaticLibrary(target = 'foo', source = Split('l1.c l2.c'))
9726 env.StaticLibrary(target = 'bar', source = ['l3.c', 'l4.c'])
9729 .SS Building a Shared Library
9733 env.SharedLibrary(target = 'foo', source = ['l5.c', 'l6.c'])
9734 env.SharedLibrary(target = 'bar', source = Split('l7.c l8.c'))
9737 .SS Linking a Local Library Into a Program
9740 env = Environment(LIBS = 'mylib', LIBPATH = ['.'])
9741 env.Library(target = 'mylib', source = Split('l1.c l2.c'))
9742 env.Program(target = 'prog', source = ['p1.c', 'p2.c'])
9745 .SS Defining Your Own Builder Object
9747 Notice that when you invoke the Builder,
9748 you can leave off the target file suffix,
9749 and SCons will add it automatically.
9752 bld = Builder(action = 'pdftex < $SOURCES > $TARGET'
9754 src_suffix = '.tex')
9755 env = Environment(BUILDERS = {'PDFBuilder' : bld})
9756 env.PDFBuilder(target = 'foo.pdf', source = 'foo.tex')
9758 # The following creates "bar.pdf" from "bar.tex"
9759 env.PDFBuilder(target = 'bar', source = 'bar')
9762 Note also that the above initialization
9763 overwrites the default Builder objects,
9764 so the Environment created above
9765 can not be used call Builders like env.Program(),
9766 env.Object(), env.StaticLibrary(), etc.
9768 .SS Adding Your Own Builder Object to an Environment
9771 bld = Builder(action = 'pdftex < $SOURCES > $TARGET'
9773 src_suffix = '.tex')
9775 env.Append(BUILDERS = {'PDFBuilder' : bld})
9776 env.PDFBuilder(target = 'foo.pdf', source = 'foo.tex')
9777 env.Program(target = 'bar', source = 'bar.c')
9780 You also can use other Pythonic techniques to add
9781 to the BUILDERS construction variable, such as:
9785 env['BUILDERS]['PDFBuilder'] = bld
9788 .SS Defining Your Own Scanner Object
9790 The following example shows an extremely simple scanner (the
9793 that doesn't use a search path at all
9794 and simply returns the
9795 file names present on any
9797 lines in the scanned file.
9798 This would implicitly assume that all included
9799 files live in the top-level directory:
9804 '\" Note: the \\ in the following are for the benefit of nroff/troff,
9805 '\" not inappropriate doubled escape characters within the r'' raw string.
9806 include_re = re.compile(r'^include\\s+(\\S+)$', re.M)
9808 def kfile_scan(node, env, path, arg):
9809 contents = node.get_text_contents()
9810 includes = include_re.findall(contents)
9813 kscan = Scanner(name = 'kfile',
9814 function = kfile_scan,
9817 scanners = Environment().Dictionary('SCANNERS')
9818 env = Environment(SCANNERS = scanners + [kscan])
9820 env.Command('foo', 'foo.k', 'kprocess < $SOURCES > $TARGET')
9822 bar_in = File('bar.in')
9823 env.Command('bar', bar_in, 'kprocess $SOURCES > $TARGET')
9824 bar_in.target_scanner = kscan
9827 Here is a similar but more complete example that searches
9828 a path of directories
9831 construction variable)
9832 for files that actually exist:
9835 include_re = re.compile(r'^include\\s+(\\S+)$', re.M)
9837 def my_scan(node, env, path, arg):
9838 contents = node.get_text_contents()
9839 includes = include_re.findall(contents)
9843 for inc in includes:
9845 file = dir + os.sep + inc
9846 if os.path.exists(file):
9847 results.append(file)
9851 scanner = Scanner(name = 'myscanner',
9855 path_function = FindPathDirs('MYPATH'),
9857 scanners = Environment().Dictionary('SCANNERS')
9858 env = Environment(SCANNERS = scanners + [scanner])
9863 function used in the previous example returns a function
9864 (actually a callable Python object)
9865 that will return a list of directories
9868 construction variable.
9869 If you need to customize how the search path is derived,
9870 you would provide your own
9872 argument when creating the Scanner object,
9876 # MYPATH is a list of directories to search for files in
9877 def pf(env, dir, target, source, arg):
9878 top_dir = Dir('#').abspath
9880 if env.has_key('MYPATH'):
9881 for p in env['MYPATH']:
9882 results.append(top_dir + os.sep + p)
9885 scanner = Scanner(name = 'myscanner',
9893 .SS Creating a Hierarchical Build
9895 Notice that the file names specified in a subdirectory's
9897 file are relative to that subdirectory.
9903 env.Program(target = 'foo', source = 'foo.c')
9905 SConscript('sub/SConscript')
9910 # Builds sub/foo from sub/foo.c
9911 env.Program(target = 'foo', source = 'foo.c')
9913 SConscript('dir/SConscript')
9918 # Builds sub/dir/foo from sub/dir/foo.c
9919 env.Program(target = 'foo', source = 'foo.c')
9922 .SS Sharing Variables Between SConscript Files
9924 You must explicitly Export() and Import() variables that
9925 you want to share between SConscript files.
9931 env.Program(target = 'foo', source = 'foo.c')
9934 SConscript('subdirectory/SConscript')
9936 subdirectory/SConscript:
9939 env.Program(target = 'foo', source = 'foo.c')
9942 .SS Building Multiple Variants From the Same Source
9944 Use the variant_dir keyword argument to
9945 the SConscript function to establish
9946 one or more separate variant build directory trees
9947 for a given source directory:
9952 cppdefines = ['FOO']
9953 Export("cppdefines")
9954 SConscript('src/SConscript', variant_dir='foo')
9956 cppdefines = ['BAR']
9957 Export("cppdefines")
9958 SConscript('src/SConscript', variant_dir='bar')
9962 Import("cppdefines")
9963 env = Environment(CPPDEFINES = cppdefines)
9964 env.Program(target = 'src', source = 'src.c')
9967 Note the use of the Export() method
9968 to set the "cppdefines" variable to a different
9969 value each time we call the SConscript function.
9971 .SS Hierarchical Build of Two Libraries Linked With a Program
9976 env = Environment(LIBPATH = ['#libA', '#libB'])
9978 SConscript('libA/SConscript')
9979 SConscript('libB/SConscript')
9980 SConscript('Main/SConscript')
9985 env.Library('a', Split('a1.c a2.c a3.c'))
9990 env.Library('b', Split('b1.c b2.c b3.c'))
9995 e = env.Copy(LIBS = ['a', 'b'])
9996 e.Program('foo', Split('m1.c m2.c m3.c'))
9999 The '#' in the LIBPATH directories specify that they're relative to the
10000 top-level directory, so they don't turn into "Main/libA" when they're
10001 used in Main/SConscript.
10003 Specifying only 'a' and 'b' for the library names
10004 allows SCons to append the appropriate library
10005 prefix and suffix for the current platform
10006 (for example, 'liba.a' on POSIX systems,
10007 \&'a.lib' on Windows).
10009 .SS Customizing construction variables from the command line.
10011 The following would allow the C compiler to be specified on the command
10012 line or in the file custom.py.
10015 vars = Variables('custom.py')
10016 vars.Add('CC', 'The C compiler.')
10017 env = Environment(variables=vars)
10018 Help(vars.GenerateHelpText(env))
10021 The user could specify the C compiler on the command line:
10027 or in the custom.py file:
10033 or get documentation on the options:
10038 CC: The C compiler.
10044 .SS Using Microsoft Visual C++ precompiled headers
10046 Since windows.h includes everything and the kitchen sink, it can take quite
10047 some time to compile it over and over again for a bunch of object files, so
10048 Microsoft provides a mechanism to compile a set of headers once and then
10049 include the previously compiled headers in any object file. This
10050 technology is called precompiled headers. The general recipe is to create a
10051 file named "StdAfx.cpp" that includes a single header named "StdAfx.h", and
10052 then include every header you want to precompile in "StdAfx.h", and finally
10053 include "StdAfx.h" as the first header in all the source files you are
10054 compiling to object files. For example:
10058 #include <windows.h>
10059 #include <my_big_header.h>
10064 #include <StdAfx.h>
10069 #include <StdAfx.h>
10071 /* do some stuff */
10076 #include <StdAfx.h>
10078 /* do some other stuff */
10084 env['PCHSTOP'] = 'StdAfx.h'
10085 env['PCH'] = env.PCH('StdAfx.cpp')[0]
10086 env.Program('MyApp', ['Foo.cpp', 'Bar.cpp'])
10089 For more information see the document for the PCH builder, and the PCH and
10090 PCHSTOP construction variables. To learn about the details of precompiled
10091 headers consult the MSDN documention for /Yc, /Yu, and /Yp.
10093 .SS Using Microsoft Visual C++ external debugging information
10095 Since including debugging information in programs and shared libraries can
10096 cause their size to increase significantly, Microsoft provides a mechanism
10097 for including the debugging information in an external file called a PDB
10098 file. SCons supports PDB files through the PDB construction
10104 env['PDB'] = 'MyApp.pdb'
10105 env.Program('MyApp', ['Foo.cpp', 'Bar.cpp'])
10108 For more information see the document for the PDB construction variable.
10113 Specifies the directory that contains the SCons Python module directory
10114 (e.g. /home/aroach/scons-src-0.01/src/engine).
10117 A string of options that will be used by scons in addition to those passed
10118 on the command line.
10129 Steven Knight <knight@baldmt.com>
10131 Anthony Roach <aroach@electriceyeball.com>