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
1489 These warnings are disabled by default.
1492 --warn=stack-size, --warn=no-stack-size
1493 Enables or disables warnings about requests to set the stack size
1494 that could not be honored.
1495 These warnings are enabled by default.
1498 .\" .RI --write-filenames= file
1499 .\" Write all filenames considered into
1503 .\" .RI -W " file" ", --what-if=" file ", --new-file=" file ", --assume-new=" file
1504 .\" Pretend that the target
1507 .\" modified. When used with the
1510 .\" show you what would be rebuilt if you were to modify that file.
1516 .\" --warn-undefined-variables
1517 .\" Warn when an undefined variable is referenced.
1520 .RI -Y " repository" ", --repository=" repository ", --srcdir=" repository
1521 Search the specified repository for any input and target
1522 files not found in the local directory hierarchy. Multiple
1524 options may be specified, in which case the
1525 repositories are searched in the order specified.
1527 .SH CONFIGURATION FILE REFERENCE
1528 .\" .SS Python Basics
1529 .\" XXX Adding this in the future would be a help.
1530 .SS Construction Environments
1531 A construction environment is the basic means by which the SConscript
1532 files communicate build information to
1534 A new construction environment is created using the
1545 may be set in a construction environment
1546 either by specifying them as keywords when the object is created
1547 or by assigning them a value after the object is created:
1550 env = Environment(FOO = 'foo')
1555 construction variables may also be set or modified by the
1557 keyword argument, which applies the
1559 method (described below) to the argument value
1560 after all other processing is completed.
1561 This is useful either if the exact content of the flags is unknown
1562 (for example, read from a control file)
1563 or if the flags are distributed to a number of construction variables.
1566 env = Environment(parse_flags = '-Iinclude -DEBUG -lm')
1569 This example adds 'include' to
1576 By default, a new construction environment is
1577 initialized with a set of builder methods
1578 and construction variables that are appropriate
1579 for the current platform.
1580 An optional platform keyword argument may be
1581 used to specify that an environment should
1582 be initialized for a different platform:
1585 env = Environment(platform = 'cygwin')
1586 env = Environment(platform = 'os2')
1587 env = Environment(platform = 'posix')
1588 env = Environment(platform = 'win32')
1591 Specifying a platform initializes the appropriate
1592 construction variables in the environment
1593 to use and generate file names with prefixes
1594 and suffixes appropriate for the platform.
1602 variables from the user's external environment
1603 to the construction environment's
1606 This is so that any executed commands
1607 that use sockets to connect with other systems
1608 (such as fetching source files from
1609 external CVS repository specifications like
1610 .BR :pserver:anonymous@cvs.sourceforge.net:/cvsroot/scons )
1611 will work on Windows systems.
1613 The platform argument may be function or callable object,
1614 in which case the Environment() method
1615 will call the specified argument to update
1616 the new construction environment:
1619 def my_platform(env):
1620 env['VAR'] = 'xyzzy'
1622 env = Environment(platform = my_platform)
1625 Additionally, a specific set of tools
1626 with which to initialize the environment
1627 may be specified as an optional keyword argument:
1630 env = Environment(tools = ['msvc', 'lex'])
1633 Non-built-in tools may be specified using the toolpath argument:
1636 env = Environment(tools = ['default', 'foo'], toolpath = ['tools'])
1639 This looks for a tool specification in tools/foo.py (as well as
1640 using the ordinary default tools for the platform). foo.py should
1641 have two functions: generate(env, **kw) and exists(env).
1645 modifies the passed-in environment
1646 to set up variables so that the tool
1648 it may use any keyword arguments
1649 that the user supplies (see below)
1650 to vary its initialization.
1653 function should return a true
1654 value if the tool is available.
1655 Tools in the toolpath are used before
1656 any of the built-in ones. For example, adding gcc.py to the toolpath
1657 would override the built-in gcc tool.
1658 Also note that the toolpath is
1659 stored in the environment for use
1667 base = Environment(toolpath=['custom_path'])
1668 derived = base.Clone(tools=['custom_tool'])
1669 derived.CustomBuilder()
1672 The elements of the tools list may also
1673 be functions or callable objects,
1674 in which case the Environment() method
1675 will call the specified elements
1676 to update the new construction environment:
1680 env['XYZZY'] = 'xyzzy'
1682 env = Environment(tools = [my_tool])
1685 The individual elements of the tools list
1686 may also themselves be two-element lists of the form
1687 .RI ( toolname ", " kw_dict ).
1688 SCons searches for the
1690 specification file as described above, and
1693 which must be a dictionary, as keyword arguments to the tool's
1698 function can use the arguments to modify the tool's behavior
1699 by setting up the environment in different ways
1700 or otherwise changing its initialization.
1703 # in tools/my_tool.py:
1704 def generate(env, **kw):
1705 # Sets MY_TOOL to the value of keyword argument 'arg1' or 1.
1706 env['MY_TOOL'] = kw.get('arg1', '1')
1711 env = Environment(tools = ['default', ('my_tool', {'arg1': 'abc'})],
1715 The tool definition (i.e. my_tool()) can use the PLATFORM variable from
1716 the environment it receives to customize the tool for different platforms.
1718 If no tool list is specified, then SCons will auto-detect the installed
1719 tools using the PATH variable in the ENV construction variable and the
1720 platform name when the Environment is constructed. Changing the PATH
1721 variable after the Environment is constructed will not cause the tools to
1724 SCons supports the following tool specifications out of the box:
1804 Additionally, there is a "tool" named
1806 which configures the
1807 environment with a default set of tools for the current platform.
1809 On posix and cygwin platforms
1810 the GNU tools (e.g. gcc) are preferred by SCons,
1811 on Windows the Microsoft tools (e.g. msvc)
1812 followed by MinGW are preferred by SCons,
1813 and in OS/2 the IBM tools (e.g. icc) are preferred by SCons.
1817 Build rules are specified by calling a construction
1818 environment's builder methods.
1819 The arguments to the builder methods are
1821 (a list of targets to be built,
1825 (a list of sources to be built,
1826 usually file names).
1828 Because long lists of file names
1829 can lead to a lot of quoting,
1834 and a same-named environment method
1835 that split a single string
1836 into a list, separated on
1837 strings of white-space characters.
1838 (These are similar to the
1839 string.split() method
1840 from the standard Python library,
1841 but work even if the input isn't a string.)
1843 Like all Python arguments,
1844 the target and source arguments to a builder method
1845 can be specified either with or without
1846 the "target" and "source" keywords.
1847 When the keywords are omitted,
1848 the target is first,
1849 followed by the source.
1850 The following are equivalent examples of calling the Program builder method:
1853 env.Program('bar', ['bar.c', 'foo.c'])
1854 env.Program('bar', Split('bar.c foo.c'))
1855 env.Program('bar', env.Split('bar.c foo.c'))
1856 env.Program(source = ['bar.c', 'foo.c'], target = 'bar')
1857 env.Program(target = 'bar', Split('bar.c foo.c'))
1858 env.Program(target = 'bar', env.Split('bar.c foo.c'))
1859 env.Program('bar', source = string.split('bar.c foo.c'))
1862 Target and source file names
1863 that are not absolute path names
1864 (that is, do not begin with
1871 an optional drive letter)
1872 are interpreted relative to the directory containing the
1878 on a path name means that the rest of the file name
1879 is interpreted relative to
1880 the directory containing
1886 is followed by a directory separator character
1887 (slash or backslash).
1892 # The comments describing the targets that will be built
1893 # assume these calls are in a SConscript file in the
1894 # a subdirectory named "subdir".
1896 # Builds the program "subdir/foo" from "subdir/foo.c":
1897 env.Program('foo', 'foo.c')
1899 # Builds the program "/tmp/bar" from "subdir/bar.c":
1900 env.Program('/tmp/bar', 'bar.c')
1902 # An initial '#' or '#/' are equivalent; the following
1903 # calls build the programs "foo" and "bar" (in the
1904 # top-level SConstruct directory) from "subdir/foo.c" and
1905 # "subdir/bar.c", respectively:
1906 env.Program('#foo', 'foo.c')
1907 env.Program('#/bar', 'bar.c')
1909 # Builds the program "other/foo" (relative to the top-level
1910 # SConstruct directory) from "subdir/foo.c":
1911 env.Program('#other/foo', 'foo.c')
1914 When the target shares the same base name
1915 as the source and only the suffix varies,
1916 and if the builder method has a suffix defined for the target file type,
1917 then the target argument may be omitted completely,
1920 will deduce the target file name from
1921 the source file name.
1922 The following examples all build the
1928 (on Windows systems)
1929 from the bar.c source file:
1932 env.Program(target = 'bar', source = 'bar.c')
1933 env.Program('bar', source = 'bar.c')
1934 env.Program(source = 'bar.c')
1935 env.Program('bar.c')
1940 keyword argument may be specified
1941 when calling a Builder.
1943 all source file strings that are not absolute paths
1944 will be interpreted relative to the specified
1946 The following example will build the
1951 program from the files
1957 env.Program('build/prog', ['f1.c', 'f2.c'], srcdir='src')
1960 It is possible to override or add construction variables when calling a
1961 builder method by passing additional keyword arguments.
1962 These overridden or added
1963 variables will only be in effect when building the target, so they will not
1964 affect other parts of the build. For example, if you want to add additional
1965 libraries for just one program:
1968 env.Program('hello', 'hello.c', LIBS=['gl', 'glut'])
1971 or generate a shared library with a non-standard suffix:
1974 env.SharedLibrary('word', 'word.cpp',
1976 LIBSUFFIXES=['.ocx'])
1979 (Note that both the $SHLIBSUFFIX and $LIBSUFFIXES variables must be set
1980 if you want SCons to search automatically
1981 for dependencies on the non-standard library names;
1982 see the descriptions of these variables, below, for more information.)
1984 It is also possible to use the
1986 keyword argument in an override:
1989 env = Program('hello', 'hello.c', parse_flags = '-Iinclude -DEBUG -lm')
1992 This example adds 'include' to
1999 Although the builder methods defined by
2002 methods of a construction environment object,
2003 they may also be called without an explicit environment:
2006 Program('hello', 'hello.c')
2007 SharedLibrary('word', 'word.cpp')
2011 the methods are called internally using a default construction
2012 environment that consists of the tools and values that
2014 has determined are appropriate for the local system.
2016 Builder methods that can be called without an explicit
2017 environment may be called from custom Python modules that you
2018 import into an SConscript file by adding the following
2019 to the Python module:
2022 from SCons.Script import *
2025 All builder methods return a list-like object
2026 containing Nodes that
2027 represent the target or targets that will be built.
2030 is an internal SCons object
2032 build targets or sources.
2034 The returned Node-list object
2035 can be passed to other builder methods as source(s)
2036 or passed to any SCons function or method
2037 where a filename would normally be accepted.
2038 For example, if it were necessary
2041 flag when compiling one specific object file:
2044 bar_obj_list = env.StaticObject('bar.c', CPPDEFINES='-DBAR')
2045 env.Program(source = ['foo.c', bar_obj_list, 'main.c'])
2048 Using a Node in this way
2049 makes for a more portable build
2050 by avoiding having to specify
2051 a platform-specific object suffix
2052 when calling the Program() builder method.
2054 Note that Builder calls will automatically "flatten"
2055 the source and target file lists,
2056 so it's all right to have the bar_obj list
2057 return by the StaticObject() call
2058 in the middle of the source file list.
2059 If you need to manipulate a list of lists returned by Builders
2060 directly using Python,
2061 you can either build the list by hand:
2064 foo = Object('foo.c')
2065 bar = Object('bar.c')
2066 objects = ['begin.o'] + foo + ['middle.o'] + bar + ['end.o']
2067 for object in objects:
2073 function supplied by scons
2074 to create a list containing just the Nodes,
2075 which may be more convenient:
2078 foo = Object('foo.c')
2079 bar = Object('bar.c')
2080 objects = Flatten(['begin.o', foo, 'middle.o', bar, 'end.o'])
2081 for object in objects:
2085 Note also that because Builder calls return
2086 a list-like object, not an actual Python list,
2091 operator to append Builder results to a Python list.
2092 Because the list and the object are different types,
2093 Python will not update the original list in place,
2094 but will instead create a new Node-list object
2095 containing the concatenation of the list
2096 elements and the Builder results.
2097 This will cause problems for any other Python variables
2098 in your SCons configuration
2099 that still hold on to a reference to the original list.
2100 Instead, use the Python
2102 method to make sure the list is updated in-place.
2108 # Do NOT use += as follows:
2110 # object_files += Object('bar.c')
2112 # It will not update the object_files list in place.
2114 # Instead, use the .extend() method:
2115 object_files.extend(Object('bar.c'))
2119 The path name for a Node's file may be used
2120 by passing the Node to the Python-builtin
2125 bar_obj_list = env.StaticObject('bar.c', CPPDEFINES='-DBAR')
2126 print "The path to bar_obj is:", str(bar_obj_list[0])
2129 Note again that because the Builder call returns a list,
2130 we have to access the first element in the list
2131 .B (bar_obj_list[0])
2132 to get at the Node that actually represents
2135 Builder calls support a
2137 keyword argument that
2138 specifies that the Builder's action(s)
2140 after changing directory.
2144 a string or a directory Node,
2145 scons will change to the specified directory.
2148 is not a string or Node
2150 then scons will change to the
2151 target file's directory.
2154 # scons will change to the "sub" subdirectory
2155 # before executing the "cp" command.
2156 env.Command('sub/dir/foo.out', 'sub/dir/foo.in',
2157 "cp dir/foo.in dir/foo.out",
2160 # Because chdir is not a string, scons will change to the
2161 # target's directory ("sub/dir") before executing the
2163 env.Command('sub/dir/foo.out', 'sub/dir/foo.in',
2164 "cp foo.in foo.out",
2168 Note that scons will
2170 automatically modify
2172 construction variables like
2176 when using the chdir
2177 keyword argument--that is,
2178 the expanded file names
2179 will still be relative to
2180 the top-level SConstruct directory,
2181 and consequently incorrect
2182 relative to the chdir directory.
2183 If you use the chdir keyword argument,
2184 you will typically need to supply a different
2190 to use just the filename portion of the
2194 provides the following builder methods:
2196 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2197 '\" BEGIN GENERATED BUILDER DESCRIPTIONS
2199 '\" The descriptions below of the various SCons Builders are generated
2200 '\" from the .xml files that live next to the various Python modules in
2201 '\" the build enginer library. If you're reading this [gnt]roff file
2202 '\" with an eye towards patching this man page, you can still submit
2203 '\" a diff against this text, but it will have to be translated to a
2204 '\" diff against the underlying .xml file before the patch is actually
2205 '\" accepted. If you do that yourself, it will make it easier to
2206 '\" integrate the patch.
2208 '\" BEGIN GENERATED BUILDER DESCRIPTIONS
2209 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2211 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2212 '\" END GENERATED BUILDER DESCRIPTIONS
2214 '\" The descriptions above of the various SCons Builders are generated
2215 '\" from the .xml files that live next to the various Python modules in
2216 '\" the build enginer library. If you're reading this [gnt]roff file
2217 '\" with an eye towards patching this man page, you can still submit
2218 '\" a diff against this text, but it will have to be translated to a
2219 '\" diff against the underlying .xml file before the patch is actually
2220 '\" accepted. If you do that yourself, it will make it easier to
2221 '\" integrate the patch.
2223 '\" END GENERATED BUILDER DESCRIPTIONS
2224 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2228 targets of builder methods automatically depend on their sources.
2229 An explicit dependency can
2230 be specified using the
2232 method of a construction environment (see below).
2237 source files for various programming languages,
2238 so the dependencies do not need to be specified explicitly.
2239 By default, SCons can
2242 Fortran source files with
2244 (POSIX systems only),
2249 and assembly language files with
2251 (POSIX systems only),
2256 for C preprocessor dependencies.
2257 SCons also has default support
2258 for scanning D source files,
2259 You can also write your own Scanners
2260 to add support for additional source file types.
2261 These can be added to the default
2262 Scanner object used by the
2264 .BR StaticObject (),
2267 Builders by adding them
2269 .B SourceFileScanner
2272 See the section "Scanner Objects,"
2273 below, for a more information about
2274 defining your own Scanner objects.
2276 .SS Methods and Functions to Do Things
2277 In addition to Builder methods,
2279 provides a number of other construction environment methods
2280 and global functions to
2281 manipulate the build configuration.
2283 Usually, a construction environment method
2284 and global function with the same name both exist
2285 so that you don't have to remember whether
2286 to a specific bit of functionality
2287 must be called with or without a construction environment.
2288 In the following list,
2289 if you call something as a global function
2292 .RI Function( arguments )
2294 and if you call something through a construction
2295 environment it looks like:
2297 .RI env.Function( arguments )
2299 If you can call the functionality in both ways,
2300 then both forms are listed.
2302 Global functions may be called from custom Python modules that you
2303 import into an SConscript file by adding the following
2304 to the Python module:
2307 from SCons.Script import *
2310 Except where otherwise noted,
2312 construction environment method
2314 provide the exact same functionality.
2315 The only difference is that,
2317 calling the functionality through a construction environment will
2318 substitute construction variables into
2319 any supplied strings.
2323 env = Environment(FOO = 'foo')
2328 In the above example,
2329 the first call to the global
2331 function will actually add a target named
2333 to the list of default targets,
2334 while the second call to the
2336 construction environment method
2337 will expand the value
2338 and add a target named
2340 to the list of default targets.
2341 For more on construction variable expansion,
2342 see the next section on
2343 construction variables.
2345 Construction environment methods
2346 and global functions supported by
2350 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2352 .RI Action( action ", [" cmd/str/fun ", [" var ", ...]] [" option = value ", ...])"
2354 .IR env .Action( action ", [" cmd/str/fun ", [" var ", ...]] [" option = value ", ...])"
2355 Creates an Action object for
2358 See the section "Action Objects,"
2359 below, for a complete explanation of the arguments and behavior.
2363 form of the invocation will expand
2364 construction variables in any argument strings,
2367 argument, at the time it is called
2368 using the construction variables in the
2370 construction environment through which
2375 form delays all variable expansion
2376 until the Action object is actually used.
2378 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2380 .RI AddMethod( object, function ", [" name ])
2382 .RI env.AddMethod( function ", [" name ])
2383 When called with the
2390 as the specified method
2392 When called with the
2393 .BR env.AddMethod ()
2397 to the construction environment
2399 as the specified method
2408 itself is used for the method name.
2413 # Note that the first argument to the function to
2414 # be attached as a method must be the object through
2415 # which the method will be called; the Python
2416 # convention is to call it 'self'.
2417 def my_method(self, arg):
2418 print "my_method() got", arg
2420 # Use the global AddMethod() function to add a method
2421 # to the Environment class. This
2422 AddMethod(Environment, my_method)
2424 env.my_method('arg')
2426 # Add the function as a method, using the function
2427 # name for the method call.
2429 env.AddMethod(my_method, 'other_method_name')
2430 env.other_method_name('another arg')
2433 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2435 .RI AddOption( arguments )
2436 This function adds a new command-line option to be recognized.
2439 are the same as supported by the standard Python
2440 .BR optparse.add_option ()
2441 method (with a few additional capabilities noted below);
2442 see the documentation for
2444 for a thorough discussion of its option-processing capabities.
2445 (Note that although the
2447 module was not a standard module until Python 2.3,
2449 contains a compatible version of the module
2450 that is used to provide identical functionality
2451 when run by earlier Python versions.)
2453 In addition to the arguments and values supported by the
2454 .B optparse.add_option ()
2458 function allows you to set the
2462 (a string with just the question mark)
2463 to indicate that the specified long option(s) take(s) an
2473 may be used to supply the "default"
2474 value that should be used when the
2475 option is specified on the command line
2476 without an explicit argument.
2480 keyword argument is supplied when calling
2482 the option will have a default value of
2485 Once a new command-line option has been added with
2487 the option value may be accessed using
2490 .BR env.GetOption ().
2491 \" NOTE: in SCons 1.x or 2.0, user options will be settable, but not yet.
2492 \" Uncomment this when that works. See tigris issue 2105.
2493 \" The value may also be set, using
2496 \" .BR env.SetOption (),
2497 \" if conditions in a
2499 \" require overriding any default value.
2500 \" Note, however, that a
2501 \" value specified on the command line will
2503 \" override a value set by any SConscript file.
2507 strings for the new option(s)
2508 will be displayed by the
2513 (the latter only if no other help text is
2514 specified in the SConscript files).
2515 The help text for the local options specified by
2517 will appear below the SCons options themselves,
2521 The options will appear in the help text
2522 in the order in which the
2529 AddOption('--prefix',
2531 nargs=1, type='string',
2534 help='installation prefix')
2535 env = Environment(PREFIX = GetOption('prefix'))
2538 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2540 .RI AddPostAction( target ", " action )
2542 .RI env.AddPostAction( target ", " action )
2543 Arranges for the specified
2549 The specified action(s) may be
2550 an Action object, or anything that
2551 can be converted into an Action object
2554 When multiple targets are supplied,
2555 the action may be called multiple times,
2556 once after each action that generates
2557 one or more targets in the list.
2559 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2561 .RI AddPreAction( target ", " action )
2563 .RI env.AddPreAction( target ", " action )
2564 Arranges for the specified
2567 before the specified
2570 The specified action(s) may be
2571 an Action object, or anything that
2572 can be converted into an Action object
2575 When multiple targets are specified,
2576 the action(s) may be called multiple times,
2577 once before each action that generates
2578 one or more targets in the list.
2580 Note that if any of the targets are built in multiple steps,
2581 the action will be invoked just
2582 before the "final" action that specifically
2583 generates the specified target(s).
2584 For example, when building an executable program
2585 from a specified source
2587 file via an intermediate object file:
2590 foo = Program('foo.c')
2591 AddPreAction(foo, 'pre_action')
2596 would be executed before
2598 calls the link command that actually
2599 generates the executable program binary
2601 not before compiling the
2603 file into an object file.
2605 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2607 .RI Alias( alias ", [" targets ", [" action ]])
2609 .RI env.Alias( alias ", [" targets ", [" action ]])
2610 Creates one or more phony targets that
2611 expand to one or more other targets.
2616 can be specified that will be executed
2617 whenever the any of the alias targets are out-of-date.
2618 Returns the Node object representing the alias,
2619 which exists outside of any file system.
2620 This Node object, or the alias name,
2621 may be used as a dependency of any other target,
2622 including another alias.
2624 can be called multiple times for the same
2625 alias to add additional targets to the alias,
2626 or additional actions to the list for this alias.
2632 Alias('install', '/usr/bin')
2633 Alias(['install', 'install-lib'], '/usr/local/lib')
2635 env.Alias('install', ['/usr/local/bin', '/usr/local/lib'])
2636 env.Alias('install', ['/usr/local/man'])
2638 env.Alias('update', ['file1', 'file2'], "update_database $SOURCES")
2641 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2643 .RI AllowSubstExceptions([ exception ", ...])"
2644 Specifies the exceptions that will be allowed
2645 when expanding construction variables.
2647 any construction variable expansions that generate a
2651 exception will expand to a
2653 (a null string) and not cause scons to fail.
2654 All exceptions not in the specified list
2655 will generate an error message
2656 and terminate processing.
2659 .B AllowSubstExceptions
2660 is called multiple times,
2661 each call completely overwrites the previous list
2662 of allowed exceptions.
2667 # Requires that all construction variable names exist.
2668 # (You may wish to do this if you want to enforce strictly
2669 # that all construction variables must be defined before use.)
2670 AllowSubstExceptions()
2672 # Also allow a string containing a zero-division expansion
2673 # like '${1 / 0}' to evalute to ''.
2674 AllowSubstExceptions(IndexError, NameError, ZeroDivisionError)
2677 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2679 .RI AlwaysBuild( target ", ...)"
2681 .RI env.AlwaysBuild( target ", ...)"
2684 so that it is always assumed to be out of date,
2685 and will always be rebuilt if needed.
2688 does not add its target(s) to the default target list,
2689 so the targets will only be built
2690 if they are specified on the command line,
2691 or are a dependent of a target specified on the command line--but
2694 be built if so specified.
2695 Multiple targets can be passed in to a single call to
2698 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2700 .RI env.Append( key = val ", [...])"
2701 Appends the specified keyword arguments
2702 to the end of construction variables in the environment.
2703 If the Environment does not have
2704 the specified construction variable,
2705 it is simply added to the environment.
2706 If the values of the construction variable
2707 and the keyword argument are the same type,
2708 then the two values will be simply added together.
2709 Otherwise, the construction variable
2710 and the value of the keyword argument
2711 are both coerced to lists,
2712 and the lists are added together.
2713 (See also the Prepend method, below.)
2718 env.Append(CCFLAGS = ' -g', FOO = ['foo.yyy'])
2721 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2723 .RI env.AppendENVPath( name ", " newpath ", [" envname ", " sep ", " delete_existing ])
2724 This appends new path elements to the given path in the
2725 specified external environment
2729 any particular path once (leaving the last one it encounters and
2730 ignoring the rest, to preserve path order),
2731 and to help assure this,
2732 will normalize all paths (using
2735 .BR os.path.normcase ).
2736 This can also handle the
2737 case where the given old path variable is a list instead of a
2738 string, in which case a list will be returned instead of a string.
2742 is 0, then adding a path that already exists
2743 will not move it to the end; it will stay where it is in the list.
2748 print 'before:',env['ENV']['INCLUDE']
2749 include_path = '/foo/bar:/foo'
2750 env.AppendENVPath('INCLUDE', include_path)
2751 print 'after:',env['ENV']['INCLUDE']
2755 after: /biz:/foo/bar:/foo
2758 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2760 .RI env.AppendUnique( key = val ", [...], delete_existing=0)"
2761 Appends the specified keyword arguments
2762 to the end of construction variables in the environment.
2763 If the Environment does not have
2764 the specified construction variable,
2765 it is simply added to the environment.
2766 If the construction variable being appended to is a list,
2767 then any value(s) that already exist in the
2768 construction variable will
2770 be added again to the list.
2771 However, if delete_existing is 1,
2772 existing matching values are removed first, so
2773 existing values in the arg list move to the end of the list.
2778 env.AppendUnique(CCFLAGS = '-g', FOO = ['foo.yyy'])
2781 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2784 A factory function that
2785 returns a Builder object
2786 to be used to fetch source files
2788 The returned Builder
2789 is intended to be passed to the
2796 env.SourceCode('.', env.BitKeeper())
2799 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2801 .RI BuildDir( build_dir ", " src_dir ", [" duplicate ])
2803 .RI env.BuildDir( build_dir ", " src_dir ", [" duplicate ])
2804 Deprecated synonyms for
2807 .BR env.VariantDir ().
2810 argument becomes the
2815 .BR env.VariantDir ().
2817 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2819 .RI Builder( action ", [" arguments ])
2821 .RI env.Builder( action ", [" arguments ])
2822 Creates a Builder object for
2825 See the section "Builder Objects,"
2826 below, for a complete explanation of the arguments and behavior.
2830 form of the invocation will expand
2831 construction variables in any arguments strings,
2835 at the time it is called
2836 using the construction variables in the
2838 construction environment through which
2843 form delays all variable expansion
2844 until after the Builder object is actually called.
2846 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2848 .RI CacheDir( cache_dir )
2850 .RI env.CacheDir( cache_dir )
2853 will maintain a cache of derived files in
2855 The derived files in the cache will be shared
2856 among all the builds using the same
2863 disables derived file caching.
2867 will only affect targets built
2868 through the specified construction environment.
2871 sets a global default
2872 that will be used by all targets built
2873 through construction environments
2884 finds a derived file that needs to be rebuilt,
2885 it will first look in the cache to see if a
2886 derived file has already been built
2887 from identical input files and an identical build action
2888 (as incorporated into the MD5 build signature).
2891 will retrieve the file from the cache.
2892 If the derived file is not present in the cache,
2895 then place a copy of the built file in the cache
2896 (identified by its MD5 build signature),
2897 so that it may be retrieved by other
2898 builds that need to build the same derived file
2899 from identical inputs.
2903 may be disabled for any invocation
2912 will place a copy of
2914 derived files in the cache,
2915 even if they already existed
2916 and were not built by this invocation.
2917 This is useful to populate a cache
2920 is added to a build,
2929 "Retrieved `file' from cache,"
2932 option is being used.
2937 will print the action that
2939 have been used to build the file,
2940 without any indication that
2941 the file was actually retrieved from the cache.
2942 This is useful to generate build logs
2943 that are equivalent regardless of whether
2944 a given derived file has been built in-place
2945 or retrieved from the cache.
2949 method can be used to disable caching of specific files. This can be
2950 useful if inputs and/or outputs of some tool are impossible to
2951 predict or prohibitively large.
2953 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2955 .RI Clean( targets ", " files_or_dirs )
2957 .RI env.Clean( targets ", " files_or_dirs )
2958 This specifies a list of files or directories which should be removed
2959 whenever the targets are specified with the
2961 command line option.
2962 The specified targets may be a list
2963 or an individual target.
2967 and create new targets or add files and directories to the
2968 clean list for the specified targets.
2970 Multiple files or directories should be specified
2971 either as separate arguments to the
2973 method, or as a list.
2975 will also accept the return value of any of the construction environment
2981 function overrides calling
2983 for the same target,
2984 and any targets passed to both functions will
2993 Clean('foo', ['bar', 'baz'])
2994 Clean('dist', env.Program('hello', 'hello.c'))
2995 Clean(['foo', 'bar'], 'something_else_to_clean')
2998 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3000 .RI Command( target ", " source ", " action ", [" key = val ", ...])"
3002 .RI env.Command( target ", " source ", " action ", [" key = val ", ...])"
3003 Executes a specific action
3004 (or list of actions)
3005 to build a target file or files.
3006 This is more convenient
3007 than defining a separate Builder object
3008 for a single special-case build.
3010 As a special case, the
3012 keyword argument can
3015 that will be used to scan the sources.
3019 if any of the sources will be directories
3020 that must be scanned on-disk for
3021 changes to files that aren't
3022 already specified in other Builder of function calls.)
3024 Any other keyword arguments specified override any
3025 same-named existing construction variables.
3027 An action can be an external command,
3028 specified as a string,
3029 or a callable Python object;
3030 see "Action Objects," below,
3031 for more complete information.
3032 Also note that a string specifying an external command
3033 may be preceded by an
3036 to suppress printing the command in question,
3040 to ignore the exit status of the external command.
3045 env.Command('foo.out', 'foo.in',
3046 "$FOO_BUILD < $SOURCES > $TARGET")
3048 env.Command('bar.out', 'bar.in',
3050 "$BAR_BUILD < $SOURCES > $TARGET"],
3051 ENV = {'PATH' : '/usr/local/bin/'})
3053 def rename(env, target, source):
3055 os.rename('.tmp', str(target[0]))
3057 env.Command('baz.out', 'baz.in',
3058 ["$BAZ_BUILD < $SOURCES > .tmp",
3065 function will usually assume, by default,
3066 that the specified targets and/or sources are Files,
3067 if no other part of the configuration
3068 identifies what type of entry it is.
3069 If necessary, you can explicitly specify
3070 that targets or source nodes should
3071 be treated as directoriese
3081 env.Command('ddd.list', Dir('ddd'), 'ls -l $SOURCE > $TARGET')
3083 env['DISTDIR'] = 'destination/directory'
3084 env.Command(env.Dir('$DISTDIR')), None, make_distdir)
3088 (Also note that SCons will usually
3089 automatically create any directory necessary to hold a target file,
3090 so you normally don't need to create directories by hand.)
3092 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3094 .RI Configure( env ", [" custom_tests ", " conf_dir ", " log_file ", " config_h ])
3096 .RI env.Configure([ custom_tests ", " conf_dir ", " log_file ", " config_h ])
3097 Creates a Configure object for integrated
3098 functionality similar to GNU autoconf.
3099 See the section "Configure Contexts,"
3100 below, for a complete explanation of the arguments and behavior.
3102 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3104 .RI env.Clone([ key = val ", ...])"
3105 Return a separate copy of a construction environment.
3106 If there are any keyword arguments specified,
3107 they are added to the returned copy,
3108 overwriting any existing values
3115 env3 = env.Clone(CCFLAGS = '-g')
3118 Additionally, a list of tools and a toolpath may be specified, as in
3119 the Environment constructor:
3122 def MyTool(env): env['FOO'] = 'bar'
3123 env4 = env.Clone(tools = ['msvc', MyTool])
3128 keyword argument is also recognized:
3131 # create an environment for compiling programs that use wxWidgets
3132 wx_env = env.Clone(parse_flags = '!wx-config --cflags --cxxflags')
3135 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3137 .RI env.Copy([ key = val ", ...])"
3138 A now-deprecated synonym for
3141 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3143 .RI env.CVS( repository ", " module )
3144 A factory function that
3145 returns a Builder object
3146 to be used to fetch source files
3150 The returned Builder
3151 is intended to be passed to the
3155 The optional specified
3157 will be added to the beginning
3158 of all repository path names;
3159 this can be used, in essence,
3160 to strip initial directory names
3161 from the repository path names,
3162 so that you only have to
3163 replicate part of the repository
3164 directory hierarchy in your
3165 local build directory.
3170 # Will fetch foo/bar/src.c
3171 # from /usr/local/CVSROOT/foo/bar/src.c.
3172 env.SourceCode('.', env.CVS('/usr/local/CVSROOT'))
3174 # Will fetch bar/src.c
3175 # from /usr/local/CVSROOT/foo/bar/src.c.
3176 env.SourceCode('.', env.CVS('/usr/local/CVSROOT', 'foo'))
3179 # from /usr/local/CVSROOT/foo/bar/src.c.
3180 env.SourceCode('.', env.CVS('/usr/local/CVSROOT', 'foo/bar'))
3183 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3185 .RI Decider( function )
3187 .RI env.Decider( function )
3188 Specifies that all up-to-date decisions for
3189 targets built through this construction environment
3190 will be handled by the specified
3194 can be one of the following strings
3195 that specify the type of decision function
3201 Specifies that a target shall be considered out of date and rebuilt
3202 if the dependency's timestamp is newer than the target file's timestamp.
3203 This is the behavior of the classic Make utility,
3206 can be used a synonym for
3207 .BR timestamp-newer .
3211 Specifies that a target shall be considered out of date and rebuilt
3212 if the dependency's timestamp is different than the
3213 timestamp recorded the last time the target was built.
3214 This provides behavior very similar to the classic Make utility
3215 (in particular, files are not opened up so that their
3216 contents can be checksummed)
3217 except that the target will also be rebuilt if a
3218 dependency file has been restored to a version with an
3220 timestamp, such as can happen when restoring files from backup archives.
3224 Specifies that a target shall be considered out of date and rebuilt
3225 if the dependency's content has changed sine the last time
3226 the target was built,
3227 as determined be performing an MD5 checksum
3228 on the dependency's contents
3229 and comparing it to the checksum recorded the
3230 last time the target was built.
3232 can be used as a synonym for
3237 Specifies that a target shall be considered out of date and rebuilt
3238 if the dependency's content has changed sine the last time
3239 the target was built,
3240 except that dependencies with a timestamp that matches
3241 the last time the target was rebuilt will be
3242 assumed to be up-to-date and
3245 This provides behavior very similar
3248 behavior of always checksumming file contents,
3249 with an optimization of not checking
3250 the contents of files whose timestamps haven't changed.
3251 The drawback is that SCons will
3253 detect if a file's content has changed
3254 but its timestamp is the same,
3255 as might happen in an automated script
3258 and runs the build again,
3259 all within a single second.
3266 # Use exact timestamp matches by default.
3267 Decider('timestamp-match')
3269 # Use MD5 content signatures for any targets built
3270 # with the attached construction environment.
3271 env.Decider('content')
3275 In addition to the above already-available functions,
3278 argument may be an actual Python function
3279 that takes the following three arguments:
3283 The Node (file) which
3287 if it has "changed" since the last tme
3288 .I target was built.
3291 The Node (file) being built.
3293 this is what should get rebuilt
3299 Stored information about the state of the
3304 This can be consulted to match various
3305 file characteristics
3306 such as the timestamp,
3307 size, or content signature.
3318 has "changed" since the last time
3322 (indicating that the target
3329 (indicating that the target should
3332 Note that the decision can be made
3333 using whatever criteria are appopriate.
3334 Ignoring some or all of the function arguments
3335 is perfectly normal.
3340 def my_decider(dependency, target, prev_ni):
3341 return not os.path.exists(str(target))
3343 env.Decider(my_decider)
3346 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3348 .RI Default( targets )
3350 .RI env.Default( targets )
3351 This specifies a list of default targets,
3352 which will be built by
3354 if no explicit targets are given on the command line.
3358 and add to the list of default targets.
3360 Multiple targets should be specified as
3361 separate arguments to the
3363 method, or as a list.
3365 will also accept the Node returned by any
3366 of a construction environment's
3372 Default('foo', 'bar', 'baz')
3373 env.Default(['a', 'b', 'c'])
3374 hello = env.Program('hello', 'hello.c')
3382 will clear all default targets.
3385 will add to the (now empty) default-target list
3388 The current list of targets added using the
3390 function or method is available in the
3395 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3397 .RI DefaultEnvironment([ args ])
3398 Creates and returns a default construction environment object.
3399 This construction environment is used internally by SCons
3400 in order to execute many of the global functions in this list,
3401 and to fetch source files transparently
3402 from source code management systems.
3404 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3406 .RI Depends( target ", " dependency )
3408 .RI env.Depends( target ", " dependency )
3409 Specifies an explicit dependency;
3421 (usually the path name of a file or directory)
3423 or a list of strings or Node objects
3424 (such as returned by a Builder call).
3425 This should only be necessary
3426 for cases where the dependency
3427 is not caught by a Scanner
3433 env.Depends('foo', 'other-input-file-for-foo')
3435 mylib = env.Library('mylib.c')
3436 installed_lib = env.Install('lib', mylib)
3437 bar = env.Program('bar.c')
3439 # Arrange for the library to be copied into the installation
3440 # directory before trying to build the "bar" program.
3441 # (Note that this is for example only. A "real" library
3442 # dependency would normally be configured through the $LIBS
3443 # and $LIBPATH variables, not using an env.Depends() call.)
3445 env.Depends(bar, installed_lib)
3448 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3450 .RI env.Dictionary([ vars ])
3451 Returns a dictionary object
3452 containing copies of all of the
3453 construction variables in the environment.
3454 If there are any variable names specified,
3455 only the specified construction
3456 variables are returned in the dictionary.
3461 dict = env.Dictionary()
3462 cc_dict = env.Dictionary('CC', 'CCFLAGS', 'CCCOM')
3465 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3467 .RI Dir( name ", [" directory ])
3469 .RI env.Dir( name ", [" directory ])
3470 This returns a Directory Node,
3471 an object that represents the specified directory
3474 can be a relative or absolute path.
3476 is an optional directory that will be used as the parent directory.
3479 is specified, the current script's directory is used as the parent.
3483 is a list, SCons returns a list of Dir nodes.
3484 Construction variables are expanded in
3487 Directory Nodes can be used anywhere you
3488 would supply a string as a directory name
3489 to a Builder method or function.
3490 Directory Nodes have attributes and methods
3491 that are useful in many situations;
3492 see "File and Directory Nodes," below.
3494 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3496 .RI env.Dump([ key ])
3497 Returns a pretty printable representation of the environment.
3501 should be a string containing the name of the variable of interest.
3506 print env.Dump('CCCOM')
3511 \&'$CC $CCFLAGS $CPPFLAGS $_CPPDEFFLAGS $_CPPINCFLAGS -c -o $TARGET $SOURCES'
3522 'ARCOM': '$AR $ARFLAGS $TARGET $SOURCES\n$RANLIB $RANLIBFLAGS $TARGET',
3525 'ASCOM': '$AS $ASFLAGS -o $TARGET $SOURCES',
3530 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3532 .RI EnsurePythonVersion( major ", " minor )
3534 .RI env.EnsurePythonVersion( major ", " minor )
3535 Ensure that the Python version is at least
3538 print out an error message and exit SCons with a non-zero exit code if the
3539 actual Python version is not late enough.
3544 EnsurePythonVersion(2,2)
3547 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3549 .RI EnsureSConsVersion( major ", " minor ", [" revision ])
3551 .RI env.EnsureSConsVersion( major ", " minor ", [" revision ])
3552 Ensure that the SCons version is at least
3555 .IR major.minor.revision .
3560 print out an error message and exit SCons with a non-zero exit code if the
3561 actual SCons version is not late enough.
3566 EnsureSConsVersion(0,14)
3568 EnsureSConsVersion(0,96,90)
3571 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3573 .RI Environment([ key = value ", ...])"
3575 .RI env.Environment([ key = value ", ...])"
3576 Return a new construction environment
3577 initialized with the specified
3581 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3583 .RI Execute( action ", [" strfunction ", " varlist ])
3585 .RI env.Execute( action ", [" strfunction ", " varlist ])
3586 Executes an Action object.
3589 may be an Action object
3590 (see the section "Action Objects,"
3591 below, for a complete explanation of the arguments and behavior),
3592 or it may be a command-line string,
3594 or executable Python function,
3595 each of which will be converted
3596 into an Action object
3598 The exit value of the command
3599 or return value of the Python function
3604 will print an error message if the executed
3607 exits with or returns a non-zero value.
3612 automatically terminate the build
3616 If you want the build to stop in response to a failed
3619 you must explicitly check for a non-zero return value:
3622 Execute(Copy('file.out', 'file.in'))
3624 if Execute("mkdir sub/dir/ectory"):
3625 # The mkdir failed, don't try to build.
3629 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3633 .RI env.Exit([ value ])
3639 A default exit value of
3642 is used if no value is specified.
3644 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3648 .RI env.Export( vars )
3651 to export a list of variables from the current
3652 SConscript file to all other SConscript files.
3653 The exported variables are kept in a global collection,
3654 so subsequent calls to
3656 will over-write previous exports that have the same name.
3657 Multiple variable names can be passed to
3659 as separate arguments or as a list. A dictionary can be used to map
3660 variables to a different name when exported. Both local variables and
3661 global variables can be exported.
3667 # Make env available for all SConscript files to Import().
3671 # Make env and package available for all SConscript files:.
3672 Export("env", "package")
3674 # Make env and package available for all SConscript files:
3675 Export(["env", "package"])
3677 # Make env available using the name debug:.
3678 Export({"debug":env})
3684 function supports an
3686 argument that makes it easier to to export a variable or
3687 set of variables to a single SConscript file.
3688 See the description of the
3692 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3694 .RI File( name ", [" directory ])
3696 .RI env.File( name ", [" directory ])
3699 an object that represents the specified file
3702 can be a relative or absolute path.
3704 is an optional directory that will be used as the parent directory.
3708 is a list, SCons returns a list of File nodes.
3709 Construction variables are expanded in
3712 File Nodes can be used anywhere you
3713 would supply a string as a file name
3714 to a Builder method or function.
3715 File Nodes have attributes and methods
3716 that are useful in many situations;
3717 see "File and Directory Nodes," below.
3719 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3721 .RI FindFile( file ", " dirs )
3723 .RI env.FindFile( file ", " dirs )
3726 in the path specified by
3729 may be a list of directory names or a single directory name.
3730 In addition to searching for files that exist in the filesytem,
3731 this function also searches for derived files
3732 that have not yet been built.
3737 foo = env.FindFile('foo', ['dir1', 'dir2'])
3740 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3742 .RI FindInstalledFiles( )
3744 .RI env.FindInstalledFiles( )
3745 Returns the list of targets set up by the
3751 This function serves as a convenient method to select the contents of
3757 Install( '/bin', [ 'executable_a', 'executable_b' ] )
3759 # will return the file node list
3760 # [ '/bin/executable_a', '/bin/executable_b' ]
3761 FindInstalledFiles()
3763 Install( '/lib', [ 'some_library' ] )
3765 # will return the file node list
3766 # [ '/bin/executable_a', '/bin/executable_b', '/lib/some_library' ]
3767 FindInstalledFiles()
3770 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3772 .RI FindSourceFiles( node = '"."' )
3774 .RI env.FindSourceFiles( node = '"."' )
3776 Returns the list of nodes which serve as the source of the built files.
3777 It does so by inspecting the dependency tree starting at the optional
3780 which defaults to the '"."'-node. It will then return all leaves of
3782 These are all children which have no further children.
3784 This function is a convenient method to select the contents of a Source
3790 Program( 'src/main_a.c' )
3791 Program( 'src/main_b.c' )
3792 Program( 'main_c.c' )
3794 # returns ['main_c.c', 'src/main_a.c', 'SConstruct', 'src/main_b.c']
3797 # returns ['src/main_b.c', 'src/main_a.c' ]
3798 FindSourceFiles( 'src' )
3802 As you can see build support files (SConstruct in the above example)
3803 will also be returned by this function.
3805 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3807 .RI FindPathDirs( variable )
3809 (actually a callable Python object)
3810 intended to be used as the
3812 of a Scanner object.
3813 The returned object will look up the specified
3815 in a construction environment
3816 and treat the construction variable's value as a list of
3817 directory paths that should be searched
3825 is generally preferable to
3828 for the following reasons:
3829 1) The returned list will contain all appropriate directories
3830 found in source trees
3834 or in code repositories
3840 2) scons will identify expansions of
3842 that evaluate to the same list of directories as,
3843 in fact, the same list,
3844 and avoid re-scanning the directories for files,
3850 def my_scan(node, env, path, arg):
3851 # Code to scan file contents goes here...
3852 return include_files
3854 scanner = Scanner(name = 'myscanner',
3856 path_function = FindPathDirs('MYPATH'))
3859 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3861 .RI Flatten( sequence )
3863 .RI env.Flatten( sequence )
3864 Takes a sequence (that is, a Python list or tuple)
3865 that may contain nested sequences
3866 and returns a flattened list containing
3867 all of the individual elements in any sequence.
3868 This can be helpful for collecting
3869 the lists returned by calls to Builders;
3870 other Builders will automatically
3871 flatten lists specified as input,
3872 but direct Python manipulation of
3873 these lists does not.
3878 foo = Object('foo.c')
3879 bar = Object('bar.c')
3881 # Because `foo' and `bar' are lists returned by the Object() Builder,
3882 # `objects' will be a list containing nested lists:
3883 objects = ['f1.o', foo, 'f2.o', bar, 'f3.o']
3885 # Passing such a list to another Builder is all right because
3886 # the Builder will flatten the list automatically:
3887 Program(source = objects)
3889 # If you need to manipulate the list directly using Python, you need to
3890 # call Flatten() yourself, or otherwise handle nested lists:
3891 for object in Flatten(objects):
3895 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3897 .RI GetBuildFailures()
3898 Returns a list of exceptions for the
3899 actions that failed while
3900 attempting to build targets.
3901 Each element in the returned list is a
3904 with the following attributes
3905 that record various aspects
3906 of the build failure:
3909 The node that was being built
3910 when the build failure occurred.
3913 The numeric exit status
3914 returned by the command or Python function
3915 that failed when trying to build the
3919 The SCons error string
3920 describing the build failure.
3921 (This is often a generic
3922 message like "Error 2"
3923 to indicate that an executed
3924 command exited with a status of 2.)
3927 The name of the file or
3928 directory that actually caused the failure.
3929 This may be different from the
3933 if an attempt to build a target named
3937 directory could not be created,
3948 The SCons Executor object
3951 This can be used to retrieve
3952 the construction environment used
3953 for the failed action.
3956 The actual SCons Action object that failed.
3957 This will be one specific action
3958 out of the possible list of
3959 actions that would have been
3960 executed to build the target.
3963 The actual expanded command that was executed and failed,
3967 and other construction variables.
3970 .BR GetBuildFailures ()
3972 will always return an empty list
3973 until any build failure has occurred,
3975 .BR GetBuildFailures ()
3976 will always return an empty list
3979 files are being read.
3980 Its primary intended use is
3981 for functions that will be
3982 executed before SCons exits
3983 by passing them to the
3985 .BR atexit.register ()
3992 def print_build_failures():
3993 from SCons.Script import GetBuildFailures
3994 for bf in GetBuildFailures():
3995 print "%s failed: %s" % (bf.node, bf.errstr)
3997 atexit.register(print_build_failures)
4000 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4002 .RI GetBuildPath( file ", [" ... ])
4004 .RI env.GetBuildPath( file ", [" ... ])
4007 path name (or names) for the specified
4015 Nodes or strings representing path names.
4017 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4021 .RI env.GetLaunchDir()
4022 Returns the absolute path name of the directory from which
4024 was initially invoked.
4025 This can be useful when using the
4030 options, which internally
4031 change to the directory in which the
4035 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4037 .RI GetOption( name )
4039 .RI env.GetOption( name )
4040 This function provides a way to query the value of
4041 SCons options set on scons command line
4045 The options supported are:
4050 which corresponds to --cache-debug;
4053 which corresponds to --cache-disable;
4056 which corresponds to --cache-force;
4059 which corresponds to --cache-show;
4062 which corresponds to -c, --clean and --remove;
4065 which corresponds to --config;
4068 which corresponds to -C and --directory;
4071 which corresponds to --diskcheck
4074 which corresponds to --duplicate;
4077 which corresponds to -f, --file, --makefile and --sconstruct;
4080 which corresponds to -h and --help;
4083 which corresponds to --ignore-errors;
4086 which corresponds to --implicit-cache;
4088 .B implicit_deps_changed
4089 which corresponds to --implicit-deps-changed;
4091 .B implicit_deps_unchanged
4092 which corresponds to --implicit-deps-unchanged;
4095 which corresponds to --interact and --interactive;
4098 which corresponds to -k and --keep-going;
4101 which corresponds to --max-drift;
4104 which corresponds to -n, --no-exec, --just-print, --dry-run and --recon;
4107 which corresponds to --no-site-dir;
4110 which corresponds to -j and --jobs;
4113 which corresponds to --profile;
4116 which corresponds to -q and --question;
4119 which corresponds to --random;
4122 which corresponds to -Y, --repository and --srcdir;
4125 which corresponds to -s, --silent and --quiet;
4128 which corresponds to --site-dir;
4131 which corresponds to --stack-size;
4133 .B taskmastertrace_file
4134 which corresponds to --taskmastertrace; and
4137 which corresponds to --warn and --warning.
4141 See the documentation for the
4142 corresponding command line object for information about each specific
4145 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4147 .RI Glob( pattern ", [" ondisk ", " source ", " strings ])
4149 .RI env.Glob( pattern ", [" ondisk ", " source ", " strings ])
4150 Returns Nodes (or strings) that match the specified
4152 relative to the directory of the current
4157 form performs string substition on
4159 and returns whatever matches
4160 the resulting expanded pattern.
4164 uses Unix shell style metacharacters for matching:
4167 * matches everything
4168 ? matches any single character
4169 [seq] matches any character in seq
4170 [!seq] matches any char not in seq
4174 Character matches do
4176 span directory separators.
4185 and source directories
4190 returns a Node (or string, if so configured)
4191 in the local (SConscript) directory
4192 if matching Node is found
4193 anywhere in a corresponding
4194 repository or source directory.
4198 argument may be set to
4200 (or any other non-true value)
4201 to disable the search for matches on disk,
4202 thereby only returning matches among
4203 already-configured File or Dir Nodes.
4204 The default behavior is to
4205 return corresponding Nodes
4206 for any on-disk matches found.
4210 argument may be set to
4212 (or any equivalent value)
4214 when the local directory is a
4216 the returned Nodes should be from the
4217 corresponding source directory,
4218 not the local directory.
4222 argument may be set to
4224 (or any equivalent value)
4227 function return strings, not Nodes,
4228 that represent the matched files or directories.
4229 The returned strings will be relative to
4230 the local (SConscript) directory.
4231 (Note that This may make it easier to perform
4232 arbitrary manipulation of file names,
4233 but if the returned strings are
4234 passed to a different
4237 any Node translation will be relative
4248 Program('foo', Glob('*.c'))
4251 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4253 '\".RI GlobalBuilders( flag )
4257 '\"adds the names of the default builders
4258 '\"(Program, Library, etc.)
4259 '\"to the global name space
4260 '\"so they can be called without an explicit construction environment.
4261 '\"(This is the default.)
4265 '\"the names of the default builders are removed
4266 '\"from the global name space
4267 '\"so that an explicit construction environment is required
4268 '\"to call all builders.
4270 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4274 .RI env.Help( text )
4275 This specifies help text to be printed if the
4277 argument is given to
4281 is called multiple times, the text is appended together in the order
4286 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4288 .RI Ignore( target ", " dependency )
4290 .RI env.Ignore( target ", " dependency )
4291 The specified dependency file(s)
4292 will be ignored when deciding if
4293 the target file(s) need to be rebuilt.
4297 to remove a target from the default build.
4298 In order to do this you must specify the directory the target will
4299 be built in as the target, and the file you want to skip building
4302 Note that this will only remove the dependencies listed from
4303 the files built by default. It will still be built if that
4304 dependency is needed by another object being built.
4305 See the third and forth examples below.
4310 env.Ignore('foo', 'foo.c')
4311 env.Ignore('bar', ['bar1.h', 'bar2.h'])
4312 env.Ignore('.','foobar.obj')
4313 env.Ignore('bar','bar/foobar.obj')
4316 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4320 .RI env.Import( vars )
4323 to import a list of variables into the current SConscript file. This
4324 will import variables that were exported with
4330 Variables exported by
4333 Multiple variable names can be passed to
4335 as separate arguments or as a list. The variable "*" can be used
4336 to import all variables.
4342 Import("env", "variable")
4343 Import(["env", "variable"])
4347 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4349 .RI Literal( string )
4351 .RI env.Literal( string )
4354 will be preserved as-is
4355 and not have construction variables expanded.
4357 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4359 .RI Local( targets )
4361 .RI env.Local( targets )
4364 will have copies made in the local tree,
4365 even if an already up-to-date copy
4366 exists in a repository.
4367 Returns a list of the target Node or Nodes.
4369 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4371 \" .RI env.MergeShellPaths( arg ", [" prepend ])
4372 \" Merges the elements of the specified
4374 \" which must be a dictionary, to the construction
4375 \" environment's copy of the shell environment
4377 \" (This is the environment which is passed
4378 \" to subshells spawned by SCons.)
4381 \" must be a single value,
4382 \" so multiple strings must
4383 \" be passed in as a list,
4384 \" not as separate arguments to
4385 \" .BR env.MergeShellPaths ().
4387 \" New values are prepended to the environment variable by default,
4388 \" unless prepend=0 is specified.
4389 \" Duplicate values are always eliminated,
4390 \" since this function calls
4393 \" .B PrependENVPath
4396 \" argument. See those functions for more details.
4401 \" # Prepend a path to the shell PATH.
4402 \" env.MergeShellPaths({'PATH':'/usr/local/bin'} )
4403 \" # Append two dirs to the shell INCLUDE.
4404 \" env.MergeShellPaths({'INCLUDE':['c:/inc1', 'c:/inc2']}, prepend=0 )
4408 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4410 .RI env.MergeFlags( arg ", [" unique ])
4411 Merges the specified
4413 values to the construction environment's construction variables.
4416 argument is not a dictionary,
4417 it is converted to one by calling
4420 before the values are merged.
4423 must be a single value,
4424 so multiple strings must
4425 be passed in as a list,
4426 not as separate arguments to
4427 .BR env.MergeFlags ().
4430 duplicate values are eliminated;
4431 you can, however, specify
4435 When eliminating duplicate values,
4436 any construction variables that end with
4439 keep the left-most unique value.
4440 All other construction variables keep
4441 the right-most unique value.
4446 # Add an optimization flag to $CCFLAGS.
4447 env.MergeFlags('-O3')
4449 # Combine the flags returned from running pkg-config with an optimization
4450 # flag and merge the result into the construction variables.
4451 env.MergeFlags(['!pkg-config gtk+-2.0 --cflags', '-O3'])
4453 # Combine an optimization flag with the flags returned from running pkg-config
4454 # twice and merge the result into the construction variables.
4455 env.MergeFlags(['-O3',
4456 '!pkg-config gtk+-2.0 --cflags --libs',
4457 '!pkg-config libpng12 --cflags --libs'])
4460 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4462 .RI NoCache( target ", ...)"
4464 .RI env.NoCache( target ", ...)"
4465 Specifies a list of files which should
4467 be cached whenever the
4469 method has been activated.
4470 The specified targets may be a list
4471 or an individual target.
4473 Multiple files should be specified
4474 either as separate arguments to the
4476 method, or as a list.
4478 will also accept the return value of any of the construction environment
4483 on directories and other non-File Node types has no effect because
4484 only File Nodes are cached.
4490 NoCache(env.Program('hello', 'hello.c'))
4493 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4495 .RI NoClean( target ", ...)"
4497 .RI env.NoClean( target ", ...)"
4498 Specifies a list of files or directories which should
4500 be removed whenever the targets (or their dependencies)
4501 are specified with the
4503 command line option.
4504 The specified targets may be a list
4505 or an individual target.
4509 and prevent each specified target
4510 from being removed by calls to the
4514 Multiple files or directories should be specified
4515 either as separate arguments to the
4517 method, or as a list.
4519 will also accept the return value of any of the construction environment
4524 for a target overrides calling
4526 for the same target,
4527 and any targets passed to both functions will
4537 NoClean(env.Program('hello', 'hello.c'))
4540 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4542 .RI env.ParseConfig( command ", [" function ", " unique ])
4545 to modify the environment as specified by the output of
4550 .BR env.MergeFlags (),
4551 which expects the output of a typical
4555 and adds the options
4556 to the appropriate construction variables.
4558 duplicate values are not
4559 added to any construction variables;
4566 and the construction variables they affect
4567 are as specified for the
4568 .BR env.ParseFlags ()
4569 method (which this method calls).
4570 See that method's description, below,
4571 for a table of options and construction variables.
4573 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4575 .RI ParseDepends( filename ", [" must_exist ", " only_one ])
4577 .RI env.ParseDepends( filename ", [" must_exist ", " only_one ])
4578 Parses the contents of the specified
4580 as a list of dependencies in the style of
4584 and explicitly establishes all of the listed dependencies.
4593 argument may be set to a non-zero
4596 throw an exception and
4597 generate an error if the file does not exist,
4598 or is otherwise inaccessible.
4602 argument may be set to a non-zero
4605 thrown an exception and
4607 if the file contains dependency
4608 information for more than one target.
4609 This can provide a small sanity check
4610 for files intended to be generated
4611 by, for example, the
4614 which should typically only
4615 write dependency information for
4616 one output file into a corresponding
4622 and all of the files listed therein
4623 will be interpreted relative to
4624 the directory of the
4626 file which calls the
4630 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4632 .RI env.ParseFlags( flags ", ...)"
4633 Parses one or more strings containing
4634 typical command-line flags for GCC tool chains
4635 and returns a dictionary with the flag values
4636 separated into the appropriate SCons construction variables.
4637 This is intended as a companion to the
4638 .BR env.MergeFlags ()
4639 method, but allows for the values in the returned dictionary
4640 to be modified, if necessary,
4641 before merging them into the construction environment.
4643 .BR env.MergeFlags ()
4644 will call this method if its argument is not a dictionary,
4645 so it is usually not necessary to call
4646 .BR env.ParseFlags ()
4647 directly unless you want to manipulate the values.)
4649 If the first character in any string is
4650 an exclamation mark (!),
4651 the rest of the string is executed as a command,
4652 and the output from the command is
4653 parsed as GCC tool chain command-line flags
4654 and added to the resulting dictionary.
4656 Flag values are translated accordig to the prefix found,
4657 and added to the following construction variables:
4660 -arch CCFLAGS, LINKFLAGS
4662 -framework FRAMEWORKS
4663 -frameworkdir= FRAMEWORKPATH
4665 -isysroot CCFLAGS, LINKFLAGS
4669 -mno-cygwin CCFLAGS, LINKFLAGS
4671 -pthread CCFLAGS, LINKFLAGS
4673 -Wa, ASFLAGS, CCFLAGS
4680 + CCFLAGS, LINKFLAGS
4684 Any other strings not associated with options
4685 are assumed to be the names of libraries
4688 construction variable.
4690 Examples (all of which produce the same result):
4693 dict = env.ParseFlags('-O2 -Dfoo -Dbar=1')
4694 dict = env.ParseFlags('-O2', '-Dfoo', '-Dbar=1')
4695 dict = env.ParseFlags(['-O2', '-Dfoo -Dbar=1'])
4696 dict = env.ParseFlags('-O2', '!echo -Dfoo -Dbar=1')
4699 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4702 A factory function that
4703 returns a Builder object
4704 to be used to fetch source files
4705 from the Perforce source code management system.
4706 The returned Builder
4707 is intended to be passed to the
4714 env.SourceCode('.', env.Perforce())
4717 Perforce uses a number of external
4718 environment variables for its operation.
4719 Consequently, this function adds the
4720 following variables from the user's external environment
4721 to the construction environment's
4734 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4736 .RI Platform( string )
4737 Returns a callable object
4738 that can be used to initialize
4739 a construction environment using the
4740 platform keyword of the Environment() method.
4745 env = Environment(platform = Platform('win32'))
4748 .RI env.Platform( string )
4749 Applies the callable object for the specified platform
4751 to the environment through which the method was called.
4754 env.Platform('posix')
4763 variables from the user's external environment
4764 to the construction environment's
4767 This is so that any executed commands
4768 that use sockets to connect with other systems
4769 (such as fetching source files from
4770 external CVS repository specifications like
4771 .BR :pserver:anonymous@cvs.sourceforge.net:/cvsroot/scons )
4772 will work on Windows systems.
4774 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4776 .RI Progress( callable ", [" interval ])
4778 .RI Progress( string ", [" interval ", " file ", " overwrite ])
4780 .RI Progress( list_of_strings ", [" interval ", " file ", " overwrite ])
4781 Allows SCons to show progress made during the build
4782 by displaying a string or calling a function while
4783 evaluating Nodes (e.g. files).
4785 If the first specified argument is a Python callable
4786 (a function or an object that has a
4789 the function will be called
4792 times a Node is evaluated.
4793 The callable will be passed the evaluated Node
4794 as its only argument.
4795 (For future compatibility,
4796 it's a good idea to also add
4800 as arguments to your function or method.
4801 This will prevent the code from breaking
4802 if SCons ever changes the interface
4803 to call the function with additional arguments in the future.)
4805 An example of a simple custom progress function
4806 that prints a string containing the Node name
4810 def my_progress_function(node, *args, **kw):
4811 print 'Evaluating node %s!' % node
4812 Progress(my_progress_function, interval=10)
4815 A more complicated example of a custom progress display object
4816 that prints a string containing a count
4817 every 100 evaluated Nodes.
4821 at the end so that the string
4822 will overwrite itself on a display:
4826 class ProgressCounter:
4828 def __call__(self, node, *args, **kw):
4830 sys.stderr.write('Evaluated %s nodes\\r' % self.count)
4831 Progress(ProgressCounter(), interval=100)
4834 If the first argument
4837 the string will be displayed
4841 The default is to print the string on standard output;
4842 an alternate output stream
4843 may be specified with the
4846 The following will print a series of dots
4847 on the error output,
4848 one dot for every 100 evaluated Nodes:
4852 Progress('.', interval=100, file=sys.stderr)
4855 If the string contains the verbatim substring
4857 it will be replaced with the Node.
4858 Note that, for performance reasons, this is
4860 a regular SCons variable substition,
4861 so you can not use other variables
4862 or use curly braces.
4863 The following example will print the name of
4864 every evaluated Node,
4867 (carriage return) to cause each line to overwritten by the next line,
4870 keyword argument to make sure the previously-printed
4871 file name is overwritten with blank spaces:
4875 Progress('$TARGET\\r', overwrite=True)
4878 If the first argument to
4880 is a list of strings,
4881 then each string in the list will be displayed
4882 in rotating fashion every
4885 This can be used to implement a "spinner"
4886 on the user's screen as follows:
4889 Progress(['-\\r', '\\\\\\r', '|\\r', '/\\r'], interval=5)
4892 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4894 .RI Precious( target ", ...)"
4896 .RI env.Precious( target ", ...)"
4899 as precious so it is not deleted before it is rebuilt. Normally
4901 deletes a target before building it.
4902 Multiple targets can be passed in to a single call to
4905 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4907 .RI env.Prepend( key = val ", [...])"
4908 Appends the specified keyword arguments
4909 to the beginning of construction variables in the environment.
4910 If the Environment does not have
4911 the specified construction variable,
4912 it is simply added to the environment.
4913 If the values of the construction variable
4914 and the keyword argument are the same type,
4915 then the two values will be simply added together.
4916 Otherwise, the construction variable
4917 and the value of the keyword argument
4918 are both coerced to lists,
4919 and the lists are added together.
4920 (See also the Append method, above.)
4925 env.Prepend(CCFLAGS = '-g ', FOO = ['foo.yyy'])
4928 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4930 .RI env.PrependENVPath( name ", " newpath ", [" envname ", " sep ", " delete_existing ])
4931 This appends new path elements to the given path in the
4932 specified external environment
4936 any particular path once (leaving the first one it encounters and
4937 ignoring the rest, to preserve path order),
4938 and to help assure this,
4939 will normalize all paths (using
4942 .BR os.path.normcase ).
4943 This can also handle the
4944 case where the given old path variable is a list instead of a
4945 string, in which case a list will be returned instead of a string.
4949 is 0, then adding a path that already exists
4950 will not move it to the beginning;
4951 it will stay where it is in the list.
4956 print 'before:',env['ENV']['INCLUDE']
4957 include_path = '/foo/bar:/foo'
4958 env.PrependENVPath('INCLUDE', include_path)
4959 print 'after:',env['ENV']['INCLUDE']
4962 The above exmaple will print:
4966 after: /foo/bar:/foo:/biz
4969 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4971 .RI env.PrependUnique( key = val ", delete_existing=0, [...])"
4972 Appends the specified keyword arguments
4973 to the beginning of construction variables in the environment.
4974 If the Environment does not have
4975 the specified construction variable,
4976 it is simply added to the environment.
4977 If the construction variable being appended to is a list,
4978 then any value(s) that already exist in the
4979 construction variable will
4981 be added again to the list.
4982 However, if delete_existing is 1,
4983 existing matching values are removed first, so
4984 existing values in the arg list move to the front of the list.
4989 env.PrependUnique(CCFLAGS = '-g', FOO = ['foo.yyy'])
4992 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4995 A factory function that
4996 returns a Builder object
4997 to be used to fetch source files
4999 The returned Builder
5000 is intended to be passed to the
5007 env.SourceCode('.', env.RCS())
5012 will fetch source files
5013 from RCS subdirectories automatically,
5015 as demonstrated in the above example
5016 should only be necessary if
5017 you are fetching from
5020 directory as the source files,
5021 or if you need to explicitly specify RCS
5022 for a specific subdirectory.
5024 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
5026 .RI env.Replace( key = val ", [...])"
5027 Replaces construction variables in the Environment
5028 with the specified keyword arguments.
5033 env.Replace(CCFLAGS = '-g', FOO = 'foo.xxx')
5036 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
5038 .RI Repository( directory )
5040 .RI env.Repository( directory )
5043 is a repository to be searched for files.
5047 and each one adds to the list of
5048 repositories that will be searched.
5052 a repository is a copy of the source tree,
5053 from the top-level directory on down,
5055 both source files and derived files
5056 that can be used to build targets in
5057 the local source tree.
5058 The canonical example would be an
5059 official source tree maintained by an integrator.
5060 If the repository contains derived files,
5061 then the derived files should have been built using
5063 so that the repository contains the necessary
5064 signature information to allow
5066 to figure out when it is appropriate to
5067 use the repository copy of a derived file,
5068 instead of building one locally.
5070 Note that if an up-to-date derived file
5071 already exists in a repository,
5075 make a copy in the local directory tree.
5076 In order to guarantee that a local copy
5082 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
5084 .RI Requires( target ", " prerequisite )
5086 .RI env.Requires( target ", " prerequisite )
5087 Specifies an order-only relationship
5088 between the specified target file(s)
5089 and the specified prerequisite file(s).
5090 The prerequisite file(s)
5091 will be (re)built, if necessary,
5094 but the target file(s) do not actually
5095 depend on the prerequisites
5096 and will not be rebuilt simply because
5097 the prerequisite file(s) change.
5102 env.Requires('foo', 'file-that-must-be-built-before-foo')
5105 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
5107 .RI Return([ vars "... , " stop= ])
5109 this stops processing the current SConscript
5110 file and returns to the calling SConscript file
5111 the values of the variables named in the
5114 Multiple strings contaning variable names may be passed to
5116 Any strings that contain white space
5120 keyword argument may be set to a false value
5121 to continue processing the rest of the SConscript
5125 This was the default behavior prior to SCons 0.98.
5126 However, the values returned
5127 are still the values of the variables in the named
5136 # Returns without returning a value.
5139 # Returns the value of the 'foo' Python variable.
5142 # Returns the values of the Python variables 'foo' and 'bar'.
5143 Return("foo", "bar")
5145 # Returns the values of Python variables 'val1' and 'val2'.
5149 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
5151 .RI Scanner( function ", [" argument ", " keys ", " path_function ", " node_class ", " node_factory ", " scan_check ", " recursive ])
5153 .RI env.Scanner( function ", [" argument ", " keys ", " path_function ", " node_class ", " node_factory ", " scan_check ", " recursive ])
5154 Creates a Scanner object for
5157 See the section "Scanner Objects,"
5158 below, for a complete explanation of the arguments and behavior.
5160 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
5163 A factory function that
5164 returns a Builder object
5165 to be used to fetch source files
5167 The returned Builder
5168 is intended to be passed to the
5175 env.SourceCode('.', env.SCCS())
5180 will fetch source files
5181 from SCCS subdirectories automatically,
5183 as demonstrated in the above example
5184 should only be necessary if
5185 you are fetching from
5188 directory as the source files,
5189 or if you need to explicitly specify SCCS
5190 for a specific subdirectory.
5192 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
5194 .RI SConscript( scripts ", [" exports ", " variant_dir ", " duplicate ])
5195 '\" .RI SConscript( scripts ", [" exports ", " variant_dir ", " src_dir ", " duplicate ])
5197 .RI env.SConscript( scripts ", [" exports ", " variant_dir ", " duplicate ])
5198 '\" .RI env.SConscript( scripts ", [" exports ", " variant_dir ", " src_dir ", " duplicate ])
5200 .RI SConscript(dirs= subdirs ", [name=" script ", " exports ", " variant_dir ", " duplicate ])
5201 '\" .RI SConscript(dirs= subdirs ", [name=" script ", " exports ", " variant_dir ", " src_dir ", " duplicate ])
5203 .RI env.SConscript(dirs= subdirs ", [name=" script ", " exports ", " variant_dir ", " duplicate ])
5204 '\" .RI env.SConscript(dirs= subdirs ", [name=" script ", " exports ", " variant_dir ", " src_dir ", " duplicate ])
5208 one or more subsidiary SConscript (configuration) files.
5209 Any variables returned by a called script using
5211 will be returned by the call to
5213 There are two ways to call the
5217 The first way you can call
5219 is to explicitly specify one or more
5221 as the first argument.
5222 A single script may be specified as a string;
5223 multiple scripts must be specified as a list
5224 (either explicitly or as created by
5229 SConscript('SConscript') # run SConscript in the current directory
5230 SConscript('src/SConscript') # run SConscript in the src directory
5231 SConscript(['src/SConscript', 'doc/SConscript'])
5232 config = SConscript('MyConfig.py')
5235 The second way you can call
5237 is to specify a list of (sub)directory names
5244 execute a subsidiary configuration file named
5246 in each of the specified directories.
5247 You may specify a name other than
5249 by supplying an optional
5252 The first three examples below have the same effect
5253 as the first three examples above:
5255 SConscript(dirs='.') # run SConscript in the current directory
5256 SConscript(dirs='src') # run SConscript in the src directory
5257 SConscript(dirs=['src', 'doc'])
5258 SConscript(dirs=['sub1', 'sub2'], name='MySConscript')
5263 argument provides a list of variable names or a dictionary of
5264 named values to export to the
5266 These variables are locally exported only to the specified
5268 and do not affect the global pool of variables used by the
5271 '\"If multiple dirs are provided, each script gets a fresh export.
5276 function to import the variables.
5279 foo = SConscript('sub/SConscript', exports='env')
5280 SConscript('dir/SConscript', exports=['env', 'variable'])
5281 SConscript(dirs='subdir', exports='env variable')
5282 SConscript(dirs=['one', 'two', 'three'], exports='shared_info')
5287 argument is present, it causes an effect equivalent to the
5289 method described below.
5295 '\" arguments are ignored.)
5296 argument is ignored.)
5301 '\" arguments are interpreted relative to the directory of the calling
5302 argument is interpreted relative to the directory of the calling
5303 .BR SConscript file.
5304 See the description of the
5306 function below for additional details and restrictions.
5309 '\" .IR variant_dir " is present, but"
5310 '\" .IR src_dir " is not,"
5311 .IR variant_dir " is present,"
5312 the source directory is relative to the called
5313 .BR SConscript " file."
5315 SConscript('src/SConscript', variant_dir = 'build')
5319 VariantDir('build', 'src')
5320 SConscript('build/SConscript')
5322 This later paradigm is often used when the sources are
5323 in the same directory as the
5324 .BR SConstruct file:
5326 SConscript('SConscript', variant_dir = 'build')
5330 VariantDir('build', '.')
5331 SConscript('build/SConscript')
5335 '\" .IR variant_dir " and"
5336 '\" .IR src_dir " are both present,"
5337 '\" xxxxx everything is in a state of confusion.
5339 '\" SConscript(dirs = 'src', variant_dir = 'build', src_dir = '.')
5340 '\" runs src/SConscript in build/src, but
5341 '\" SConscript(dirs = 'lib', variant_dir = 'build', src_dir = 'src')
5342 '\" runs lib/SConscript (in lib!). However,
5343 '\" SConscript(dirs = 'src', variant_dir = 'build', src_dir = 'src')
5344 '\" runs src/SConscript in build. Moreover,
5345 '\" SConscript(dirs = 'src/lib', variant_dir = 'build', src_dir = 'src')
5346 '\" runs src/lib/SConscript in build/lib. Moreover,
5347 '\" SConscript(dirs = 'build/src/lib', variant_dir = 'build', src_dir = 'src')
5348 '\" can't find build/src/lib/SConscript, even though it ought to exist.
5350 '\" is equivalent to
5352 '\" ????????????????
5354 '\" and what about this alternative?
5355 '\"TODO??? SConscript('build/SConscript', src_dir='src')
5357 Here are some composite examples:
5360 # collect the configuration information and use it to build src and doc
5361 shared_info = SConscript('MyConfig.py')
5362 SConscript('src/SConscript', exports='shared_info')
5363 SConscript('doc/SConscript', exports='shared_info')
5367 # build debugging and production versions. SConscript
5368 # can use Dir('.').path to determine variant.
5369 SConscript('SConscript', variant_dir='debug', duplicate=0)
5370 SConscript('SConscript', variant_dir='prod', duplicate=0)
5374 # build debugging and production versions. SConscript
5375 # is passed flags to use.
5376 opts = { 'CPPDEFINES' : ['DEBUG'], 'CCFLAGS' : '-pgdb' }
5377 SConscript('SConscript', variant_dir='debug', duplicate=0, exports=opts)
5378 opts = { 'CPPDEFINES' : ['NODEBUG'], 'CCFLAGS' : '-O' }
5379 SConscript('SConscript', variant_dir='prod', duplicate=0, exports=opts)
5383 # build common documentation and compile for different architectures
5384 SConscript('doc/SConscript', variant_dir='build/doc', duplicate=0)
5385 SConscript('src/SConscript', variant_dir='build/x86', duplicate=0)
5386 SConscript('src/SConscript', variant_dir='build/ppc', duplicate=0)
5389 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
5391 .RI SConscriptChdir( value )
5393 .RI env.SConscriptChdir( value )
5396 changes its working directory
5397 to the directory in which each
5398 subsidiary SConscript file lives.
5399 This behavior may be disabled
5400 by specifying either:
5404 env.SConscriptChdir(0)
5409 will stay in the top-level directory
5410 while reading all SConscript files.
5411 (This may be necessary when building from repositories,
5412 when all the directories in which SConscript files may be found
5413 don't necessarily exist locally.)
5414 You may enable and disable
5415 this ability by calling
5424 SConscript('foo/SConscript') # will not chdir to foo
5425 env.SConscriptChdir(1)
5426 SConscript('bar/SConscript') # will chdir to bar
5429 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
5431 .RI SConsignFile([ file , dbm_module ])
5433 .RI env.SConsignFile([ file , dbm_module ])
5436 to store all file signatures
5437 in the specified database
5444 (The actual file name(s) stored on disk
5445 may have an appropriated suffix appended
5450 is not an absolute path name,
5451 the file is placed in the same directory as the top-level
5461 will store file signatures
5464 file in each directory,
5465 not in one global database file.
5466 (This was the default behavior
5467 prior to SCons 0.96.91 and 0.97.)
5471 argument can be used to specify
5472 which Python database module
5473 The default is to use a custom
5475 module that uses pickled
5476 Python data structures,
5477 and which works on all Python versions from 1.5.2 on.
5482 # Explicitly stores signatures in ".sconsign.dblite"
5483 # in the top-level SConstruct directory (the
5484 # default behavior).
5487 # Stores signatures in the file "etc/scons-signatures"
5488 # relative to the top-level SConstruct directory.
5489 SConsignFile("etc/scons-signatures")
5491 # Stores signatures in the specified absolute file name.
5492 SConsignFile("/home/me/SCons/signatures")
5494 # Stores signatures in a separate .sconsign file
5495 # in each directory.
5499 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
5501 .RI env.SetDefault(key = val ", [...])"
5502 Sets construction variables to default values specified with the keyword
5503 arguments if (and only if) the variables are not already set.
5504 The following statements are equivalent:
5507 env.SetDefault(FOO = 'foo')
5509 if not env.has_key('FOO'): env['FOO'] = 'foo'
5512 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
5514 .RI SetOption( name ", " value )
5516 .RI env.SetOption( name ", " value )
5517 This function provides a way to set a select subset of the scons command
5518 line options from a SConscript file. The options supported are:
5523 which corresponds to -c, --clean and --remove;
5526 which corresponds to --duplicate;
5529 which corresponds to -h and --help;
5532 which corresponds to --implicit-cache;
5535 which corresponds to --max-drift;
5538 which corresponds to -n, --no-exec, --just-print, --dry-run and --recon;
5541 which corresponds to -j and --jobs;
5544 which corresponds to --random; and
5547 which corresponds to --stack-size.
5551 See the documentation for the
5552 corresponding command line object for information about each specific
5558 SetOption('max_drift', 1)
5561 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
5563 .RI SideEffect( side_effect ", " target )
5565 .RI env.SideEffect( side_effect ", " target )
5568 as a side effect of building
5574 can be a list, a file name, or a node.
5575 A side effect is a target file that is created or updated
5576 as a side effect of building other targets.
5577 For example, a Windows PDB
5578 file is created as a side effect of building the .obj
5579 files for a static library,
5580 and various log files are created updated
5581 as side effects of various TeX commands.
5582 If a target is a side effect of multiple build commands,
5584 will ensure that only one set of commands
5585 is executed at a time.
5586 Consequently, you only need to use this method
5587 for side-effect targets that are built as a result of
5588 multiple build commands.
5590 Because multiple build commands may update
5591 the same side effect file,
5596 automatically removed
5602 (Note, however, that the
5604 might be removed as part of
5605 cleaning the directory in which it lives.)
5606 If you want to make sure the
5608 is cleaned whenever a specific
5611 you must specify this explicitly
5618 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
5620 .RI SourceCode( entries ", " builder )
5622 .RI env.SourceCode( entries ", " builder )
5623 Arrange for non-existent source files to
5624 be fetched from a source code management system
5629 may be a Node, string or list of both,
5630 and may represent either individual
5631 source files or directories in which
5632 source files can be found.
5634 For any non-existent source files,
5636 will search up the directory tree
5646 will not use a builder to fetch
5647 source files for the specified
5651 builder has been specified
5652 for a directory higher up the tree.
5656 fetch files from SCCS or RCS subdirectories
5657 without explicit configuration.
5658 This takes some extra processing time
5659 to search for the necessary
5660 source code management files on disk.
5661 You can avoid these extra searches
5662 and speed up your build a little
5663 by disabling these searches as follows:
5666 env.SourceCode('.', None)
5670 Note that if the specified
5672 is one you create by hand,
5673 it must have an associated
5674 construction environment to use
5675 when fetching a source file.
5678 provides a set of canned factory
5679 functions that return appropriate
5680 Builders for various popular
5681 source code management systems.
5682 Canonical examples of invocation include:
5685 env.SourceCode('.', env.BitKeeper('/usr/local/BKsources'))
5686 env.SourceCode('src', env.CVS('/usr/local/CVSROOT'))
5687 env.SourceCode('/', env.RCS())
5688 env.SourceCode(['f1.c', 'f2.c'], env.SCCS())
5689 env.SourceCode('no_source.c', None)
5691 '\"env.SourceCode('.', env.Subversion('file:///usr/local/Subversion'))
5693 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
5695 .RI env.subst( input ", [" raw ", " target ", " source ", " conv ])
5696 Performs construction variable interpolation
5697 on the specified string or sequence argument
5701 leading or trailing white space will
5702 be removed from the result.
5703 and all sequences of white space
5704 will be compressed to a single space character.
5709 character sequences will be stripped from the returned string,
5712 argument may be set to
5714 if you want to preserve white space and
5719 argument may be set to
5721 if you want to strip
5722 all characters between
5728 (as is done for signature calculation).
5730 If the input is a sequence
5732 the individual elements of
5733 the sequence will be expanded,
5734 and the results will be returned as a list.
5741 must be set to lists of
5742 target and source nodes, respectively,
5749 to be available for expansion.
5750 This is usually necessary if you are
5753 from within a Python function used
5756 Returned string values or sequence elements
5757 are converted to their string representation by default.
5761 may specify a conversion function
5762 that will be used in place of
5764 For example, if you want Python objects
5765 (including SCons Nodes)
5766 to be returned as Python objects,
5767 you can use the Python
5769 idiom to pass in an unnamed function
5770 that simply returns its unconverted argument.
5775 print env.subst("The C compiler is: $CC")
5777 def compile(target, source, env):
5778 sourceDir = env.subst("${SOURCE.srcdir}",
5782 source_nodes = env.subst('$EXPAND_TO_NODELIST',
5786 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
5788 '\".RI Subversion( repository ", " module )
5789 '\"A factory function that
5790 '\"returns a Builder object
5791 '\"to be used to fetch source files
5792 '\"from the specified Subversion
5794 '\"The returned Builder
5795 '\"is intended to be passed to the
5799 '\"The optional specified
5801 '\"will be added to the beginning
5802 '\"of all repository path names;
5803 '\"this can be used, in essence,
5804 '\"to strip initial directory names
5805 '\"from the repository path names,
5806 '\"so that you only have to
5807 '\"replicate part of the repository
5808 '\"directory hierarchy in your
5809 '\"local build directory.
5814 '\"# Will fetch foo/bar/src.c
5815 '\"# from /usr/local/Subversion/foo/bar/src.c.
5816 '\"env.SourceCode('.', env.Subversion('file:///usr/local/Subversion'))
5818 '\"# Will fetch bar/src.c
5819 '\"# from /usr/local/Subversion/foo/bar/src.c.
5820 '\"env.SourceCode('.', env.Subversion('file:///usr/local/Subversion', 'foo'))
5822 '\"# Will fetch src.c
5823 '\"# from /usr/local/Subversion/foo/bar/src.c.
5824 '\"env.SourceCode('.', env.Subversion('file:///usr/local/Subversion', 'foo/bar'))
5827 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
5829 .RI SourceSignatures( type )
5831 .RI env.SourceSignatures( type )
5832 Note: Although it is not yet officially deprecated,
5833 use of this function is discouraged.
5836 function for a more flexible and straightforward way
5837 to configure SCons' decision-making.
5840 .BR SourceSignatures ()
5843 how to decide if a source file
5844 (a file that is not built from any other files)
5845 has changed since the last time it
5846 was used to build a particular target file.
5852 If the environment method is used,
5853 the specified type of source signature
5854 is only used when deciding whether targets
5855 built with that environment are up-to-date or must be rebuilt.
5856 If the global function is used,
5857 the specified type of source signature becomes the default
5858 used for all decisions
5859 about whether targets are up-to-date.
5864 decides that a source file has changed
5865 if the MD5 checksum of its contents has changed since
5866 the last time it was used to rebuild a particular target file.
5871 decides that a source file has changed
5872 if its timestamp (modification time) has changed since
5873 the last time it was used to rebuild a particular target file.
5874 (Note that although this is similar to the behavior of Make,
5875 by default it will also rebuild if the dependency is
5877 than the last time it was used to rebuild the target file.)
5879 There is no different between the two behaviors
5885 signatures take longer to compute,
5886 but are more accurate than
5889 The default value is
5892 Note that the default
5893 .BR TargetSignatures ()
5896 .BR SourceSignatures ()
5897 setting for any target files that are used
5898 to build other target files.
5899 Consequently, changing the value of
5900 .BR SourceSignatures ()
5902 affect the up-to-date decision for all files in the build
5903 (or all files built with a specific construction environment
5905 .BR env.SourceSignatures ()
5908 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
5912 .RI env.Split( arg )
5913 Returns a list of file names or other objects.
5915 it will be split on strings of white-space characters
5917 making it easier to write long lists of file names.
5918 If arg is already a list,
5919 the list will be returned untouched.
5920 If arg is any other type of object,
5921 it will be returned as a list
5922 containing just the object.
5927 files = Split("f1.c f2.c f3.c")
5928 files = env.Split("f4.c f5.c f6.c")
5936 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
5938 .RI Tag( node ", " tags )
5939 Annotates file or directory Nodes with
5940 information about how the
5942 Builder should package those files or directories.
5943 All tags are optional.
5948 # makes sure the built library will be installed with 0644 file
5950 Tag( Library( 'lib.c' ), UNIX_ATTR="0644" )
5952 # marks file2.txt to be a documentation file
5953 Tag( 'file2.txt', DOC )
5956 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
5958 .RI TargetSignatures( type )
5960 .RI env.TargetSignatures( type )
5961 Note: Although it is not yet officially deprecated,
5962 use of this function is discouraged.
5965 function for a more flexible and straightforward way
5966 to configure SCons' decision-making.
5969 .BR TargetSignatures ()
5972 how to decide if a target file
5975 built from any other files)
5976 has changed since the last time it
5977 was used to build some other target file.
5987 If the environment method is used,
5988 the specified type of target signature is only used
5989 for targets built with that environment.
5990 If the global function is used,
5991 the specified type of signature becomes the default
5992 used for all target files that
5993 don't have an explicit target signature type
5994 specified for their environments.
6001 decides that a target file has changed
6002 if the MD5 checksum of its contents has changed since
6003 the last time it was used to rebuild some other target file.
6007 MD5 sum the contents
6008 of target files after they're built,
6009 and may decide that it does not need to rebuild
6010 "downstream" target files if a file was
6011 rebuilt with exactly the same contents as the last time.
6016 decides that a target file has changed
6017 if its timestamp (modification time) has changed since
6018 the last time it was used to rebuild some other target file.
6019 (Note that although this is similar to the behavior of Make,
6020 by default it will also rebuild if the dependency is
6022 than the last time it was used to rebuild the target file.)
6027 decides that a target file has changed
6028 as specified by the corresponding
6029 .BR SourceSignatures ()
6036 will treat all input files to a target the same way,
6037 regardless of whether they are source files
6038 or have been built from other files.
6043 decides that a target file has changed
6044 if it has been rebuilt in this invocation
6045 or if its content or timestamp have changed
6046 as specified by the corresponding
6047 .BR SourceSignatures ()
6049 This "propagates" the status of a rebuilt file
6050 so that other "downstream" target files
6051 will always be rebuilt,
6052 even if the contents or the timestamp
6056 signatures are fastest because
6060 signatures take longer to compute,
6061 but are more accurate than
6064 and can prevent unnecessary "downstream" rebuilds
6065 when a target file is rebuilt to the exact same contents
6066 as the previous build.
6069 setting provides the most consistent behavior
6070 when other target files may be rebuilt from
6071 both source and target input files.
6072 The default value is
6075 Because the default setting is
6078 .BR SourceSignatures ()
6079 is generally preferable to
6080 .BR TargetSignatures () ,
6081 so that the up-to-date decision
6082 will be consistent for all files
6083 (or all files built with a specific construction environment).
6085 .BR TargetSignatures ()
6086 provides specific control for how built target files
6087 affect their "downstream" dependencies.
6089 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
6091 .RI Tool( string [, toolpath ", " **kw ])
6092 Returns a callable object
6093 that can be used to initialize
6094 a construction environment using the
6095 tools keyword of the Environment() method.
6096 The object may be called with a construction
6097 environment as an argument,
6098 in which case the object will
6099 add the necessary variables
6100 to the construction environment
6101 and the name of the tool will be added to the
6103 construction variable.
6105 Additional keyword arguments are passed to the tool's
6112 env = Environment(tools = [ Tool('msvc') ])
6116 t(env) # adds 'msvc' to the TOOLS variable
6117 u = Tool('opengl', toolpath = ['tools'])
6118 u(env) # adds 'opengl' to the TOOLS variable
6121 .RI env.Tool( string [, toolpath ", " **kw ])
6122 Applies the callable object for the specified tool
6124 to the environment through which the method was called.
6126 Additional keyword arguments are passed to the tool's
6132 env.Tool('opengl', toolpath = ['build/tools'])
6135 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
6137 .RI Value( value ", [" built_value ])
6139 .RI env.Value( value ", [" built_value ])
6140 Returns a Node object representing the specified Python value. Value
6141 Nodes can be used as dependencies of targets. If the result of
6144 changes between SCons runs, any targets depending on
6147 (This is true even when using timestamps to decide if
6148 files are up-to-date.)
6149 When using timestamp source signatures, Value Nodes'
6150 timestamps are equal to the system time when the Node is created.
6152 The returned Value Node object has a
6154 method that can be used to "build" a Value Node
6155 by setting a new value.
6158 argument can be specified
6159 when the Value Node is created
6160 to indicate the Node should already be considered
6162 There is a corresponding
6164 method that will return the built value of the Node.
6171 def create(target, source, env):
6172 # A function that will write a 'prefix=$SOURCE'
6173 # string into the file name specified as the
6175 f = open(str(target[0]), 'wb')
6176 f.write('prefix=' + source[0].get_contents())
6178 # Fetch the prefix= argument, if any, from the command
6179 # line, and use /usr/local as the default.
6180 prefix = ARGUMENTS.get('prefix', '/usr/local')
6182 # Attach a .Config() builder for the above function action
6183 # to the construction environment.
6184 env['BUILDERS']['Config'] = Builder(action = create)
6185 env.Config(target = 'package-config', source = Value(prefix))
6187 def build_value(target, source, env):
6188 # A function that "builds" a Python Value by updating
6189 # the the Python value with the contents of the file
6190 # specified as the source of the Builder call ($SOURCE).
6191 target[0].write(source[0].get_contents())
6193 output = env.Value('before')
6194 input = env.Value('after')
6196 # Attach a .UpdateValue() builder for the above function
6197 # action to the construction environment.
6198 env['BUILDERS']['UpdateValue'] = Builder(action = build_value)
6199 env.UpdateValue(target = Value(output), source = Value(input))
6202 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
6204 .RI VariantDir( variant_dir ", " src_dir ", [" duplicate ])
6206 .RI env.VariantDir( variant_dir ", " src_dir ", [" duplicate ])
6209 function to create a copy of your sources in another location:
6212 is not found but exists under
6214 the file or directory is copied to
6216 Target files can be built in a different directory
6217 than the original sources by simply refering to the sources (and targets)
6218 within the variant tree.
6221 can be called multiple times with the same
6223 to set up multiple builds with different options
6227 location must be in or underneath the SConstruct file's directory, and
6229 may not be underneath
6231 '\"TODO: Can the above restrictions be clarified or relaxed?
6232 '\"TODO: The latter restriction is clearly not completely right;
6233 '\"TODO: src_dir = '.' works fine with a build dir under it.
6235 The default behavior is for
6237 to physically duplicate the source files in the variant tree.
6238 Thus, a build performed in the variant tree is guaranteed to be identical
6239 to a build performed in the source tree even if
6240 intermediate source files are generated during the build,
6241 or preprocessors or other scanners search for included files
6242 relative to the source file,
6243 or individual compilers or other invoked tools are hard-coded
6244 to put derived files in the same directory as source files.
6246 If possible on the platform,
6247 the duplication is performed by linking rather than copying;
6250 command-line option.
6251 Moreover, only the files needed for the build are duplicated;
6252 files and directories that are not used are not present in
6255 Duplicating the source tree may be disabled by setting the
6257 argument to 0 (zero).
6260 to invoke Builders using the path names of source files in
6262 and the path names of derived files within
6264 This is always more efficient than
6266 and is usually safe for most builds
6267 (but see above for cases that may cause problems).
6271 works most naturally with a subsidiary SConscript file.
6272 However, you would then call the subsidiary SConscript file
6273 not in the source directory, but in the
6275 regardless of the value of
6277 This is how you tell
6279 which variant of a source tree to build:
6282 # run src/SConscript in two variant directories
6283 VariantDir('build/variant1', 'src')
6284 SConscript('build/variant1/SConscript')
6285 VariantDir('build/variant2', 'src')
6286 SConscript('build/variant2/SConscript')
6292 function, described above,
6293 for another way to specify a variant directory
6294 in conjunction with calling a subsidiary SConscript file.
6299 # use names in the build directory, not the source directory
6300 VariantDir('build', 'src', duplicate=0)
6301 Program('build/prog', 'build/source.c')
6305 # this builds both the source and docs in a separate subtree
6306 VariantDir('build', '.', duplicate=0)
6307 SConscript(dirs=['build/src','build/doc'])
6311 # same as previous example, but only uses SConscript
6312 SConscript(dirs='src', variant_dir='build/src', duplicate=0)
6313 SConscript(dirs='doc', variant_dir='build/doc', duplicate=0)
6316 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
6318 .RI WhereIs( program ", [" path ", " pathext ", " reject ])
6320 .RI env.WhereIs( program ", [" path ", " pathext ", " reject ])
6322 Searches for the specified executable
6324 returning the full path name to the program
6326 and returning None if not.
6327 Searches the specified
6329 the value of the calling environment's PATH
6330 (env['ENV']['PATH']),
6331 or the user's current external PATH
6332 (os.environ['PATH'])
6334 On Windows systems, searches for executable
6335 programs with any of the file extensions
6336 listed in the specified
6338 the calling environment's PATHEXT
6339 (env['ENV']['PATHEXT'])
6340 or the user's current PATHEXT
6341 (os.environ['PATHEXT'])
6349 .SS SConscript Variables
6350 In addition to the global functions and methods,
6352 supports a number of Python variables
6353 that can be used in SConscript files
6354 to affect how you want the build to be performed.
6355 These variables may be accessed from custom Python modules that you
6356 import into an SConscript file by adding the following
6357 to the Python module:
6360 from SCons.Script import *
6363 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
6368 arguments specified on the command line.
6369 Each element in the list is a tuple
6371 .RI ( keyword , value )
6377 elements of the tuple
6379 subscripting for element
6383 of the tuple, respectively.
6388 print "first keyword, value =", ARGLIST[0][0], ARGLIST[0][1]
6389 print "second keyword, value =", ARGLIST[1][0], ARGLIST[1][1]
6390 third_tuple = ARGLIST[2]
6391 print "third keyword, value =", third_tuple[0], third_tuple[1]
6392 for key, value in ARGLIST:
6393 # process key and value
6396 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
6399 A dictionary of all the
6401 arguments specified on the command line.
6402 The dictionary is not in order,
6403 and if a given keyword has
6404 more than one value assigned to it
6405 on the command line,
6406 the last (right-most) value is
6414 if ARGUMENTS.get('debug', 0):
6415 env = Environment(CCFLAGS = '-g')
6420 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
6423 A list of the targets which
6425 will actually try to build,
6426 regardless of whether they were specified on
6427 the command line or via the
6430 The elements of this list may be strings
6432 nodes, so you should run the list through the Python
6434 function to make sure any Node path names
6435 are converted to strings.
6437 Because this list may be taken from the
6438 list of targets specified using the
6441 the contents of the list may change
6442 on each successive call to
6447 for additional information.
6452 if 'foo' in BUILD_TARGETS:
6453 print "Don't forget to test the `foo' program!"
6454 if 'special/program' in BUILD_TARGETS:
6455 SConscript('special')
6460 list only contains targets expected listed
6461 on the command line or via calls to the
6466 contain all dependent targets that will be built as
6467 a result of making the sure the explicitly-specified
6468 targets are up to date.
6470 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
6472 COMMAND_LINE_TARGETS
6473 A list of the targets explicitly specified on
6475 If there are no targets specified on the command line,
6477 This can be used, for example,
6478 to take specific actions only
6479 when a certain target or targets
6480 is explicitly being built.
6485 if 'foo' in COMMAND_LINE_TARGETS:
6486 print "Don't forget to test the `foo' program!"
6487 if 'special/program' in COMMAND_LINE_TARGETS:
6488 SConscript('special')
6491 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
6494 A list of the target
6496 that have been specified using the
6499 The elements of the list are nodes,
6500 so you need to run them through the Python
6502 function to get at the path name for each Node.
6507 print str(DEFAULT_TARGETS[0])
6508 if 'foo' in map(str, DEFAULT_TARGETS):
6509 print "Don't forget to test the `foo' program!"
6514 list change on on each successive call to the
6519 print map(str, DEFAULT_TARGETS) # originally []
6521 print map(str, DEFAULT_TARGETS) # now a node ['foo']
6523 print map(str, DEFAULT_TARGETS) # now a node ['foo', 'bar']
6525 print map(str, DEFAULT_TARGETS) # back to []
6528 Consequently, be sure to use
6530 only after you've made all of your
6533 or else simply be careful of the order
6534 of these statements in your SConscript files
6535 so that you don't look for a specific
6536 default target before it's actually been added to the list.
6538 .SS Construction Variables
6539 .\" XXX From Gary Ruben, 23 April 2002:
6540 .\" I think it would be good to have an example with each construction
6541 .\" variable description in the documentation.
6543 .\" CC The C compiler
6544 .\" Example: env["CC"] = "c68x"
6545 .\" Default: env["CC"] = "cc"
6547 .\" CCCOM The command line ...
6549 .\" To generate the compiler line c68x -ps -qq -mr -o $TARGET $SOURCES
6550 .\" env["CC"] = "c68x"
6551 .\" env["CFLAGS"] = "-ps -qq -mr"
6552 .\" env["CCCOM"] = "$CC $CFLAGS -o $TARGET $SOURCES
6554 .\" (I dunno what this is ;-)
6555 A construction environment has an associated dictionary of
6556 .I construction variables
6557 that are used by built-in or user-supplied build rules.
6558 Construction variables must follow the same rules for
6560 the initial character must be an underscore or letter,
6561 followed by any number of underscores, letters, or digits.
6563 A number of useful construction variables are automatically defined by
6564 scons for each supported platform, and additional construction variables
6565 can be defined by the user. The following is a list of the automatically
6566 defined construction variables:
6568 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
6569 '\" BEGIN GENERATED CONSTRUCTION VARIABLE DESCRIPTIONS
6571 '\" The descriptions below of the various SCons construction variables
6572 '\" are generated from the .xml files that live next to the various
6573 '\" Python modules in the build enginer library. If you're reading
6574 '\" this [gnt]roff file with an eye towards patching this man page,
6575 '\" you can still submit a diff against this text, but it will have to
6576 '\" be translated to a diff against the underlying .xml file before the
6577 '\" patch is actually accepted. If you do that yourself, it will make
6578 '\" it easier to integrate the patch.
6580 '\" BEGIN GENERATED CONSTRUCTION VARIABLE DESCRIPTIONS
6581 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
6583 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
6584 '\" END GENERATED CONSTRUCTION VARIABLE DESCRIPTIONS
6586 '\" The descriptions above of the various SCons construction variables
6587 '\" are generated from the .xml files that live next to the various
6588 '\" Python modules in the build enginer library. If you're reading
6589 '\" this [gnt]roff file with an eye towards patching this man page,
6590 '\" you can still submit a diff against this text, but it will have to
6591 '\" be translated to a diff against the underlying .xml file before the
6592 '\" patch is actually accepted. If you do that yourself, it will make
6593 '\" it easier to integrate the patch.
6595 '\" END GENERATED CONSTRUCTION VARIABLE DESCRIPTIONS
6596 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
6599 Construction variables can be retrieved and set using the
6601 method of the construction environment:
6604 dict = env.Dictionary()
6608 or using the [] operator:
6614 Construction variables can also be passed to the construction environment
6618 env = Environment(CC="cc")
6621 or when copying a construction environment using the
6626 env2 = env.Clone(CC="cl.exe")
6629 .SS Configure Contexts
6633 .I configure contexts,
6634 an integrated mechanism similar to the
6635 various AC_CHECK macros in GNU autoconf
6636 for testing for the existence of C header
6637 files, libraries, etc.
6638 In contrast to autoconf,
6640 does not maintain an explicit cache of the tested values,
6641 but uses its normal dependency tracking to keep the checked values
6642 up to date. However, users may override this behaviour with the
6644 command line option.
6646 The following methods can be used to perform checks:
6649 .RI Configure( env ", [" custom_tests ", " conf_dir ", " log_file ", " config_h ", " clean ", " help])
6651 .RI env.Configure([ custom_tests ", " conf_dir ", " log_file ", " config_h ", " clean ", " help])
6652 This creates a configure context, which can be used to perform checks.
6654 specifies the environment for building the tests.
6655 This environment may be modified when performing checks.
6657 is a dictionary containing custom tests.
6658 See also the section about custom tests below.
6659 By default, no custom tests are added to the configure context.
6661 specifies a directory where the test cases are built.
6662 Note that this directory is not used for building
6664 The default value is the directory
6667 specifies a file which collects the output from commands
6668 that are executed to check for the existence of header files, libraries, etc.
6669 The default is the file #/config.log.
6670 If you are using the
6673 you may want to specify a subdirectory under your variant directory.
6675 specifies a C header file where the results of tests
6676 will be written, e.g. #define HAVE_STDIO_H, #define HAVE_LIBM, etc.
6677 The default is to not write a
6680 You can specify the same
6682 file in multiple calls to Configure,
6685 will concatenate all results in the specified file.
6687 uses its normal dependency checking
6688 to decide if it's necessary to rebuild
6692 This means that the file is not necessarily re-built each
6694 but is only rebuilt if its contents will have changed
6695 and some target that depends on the
6697 file is being built.
6703 arguments can be used to suppress execution of the configuration
6708 options are used, respectively.
6709 The default behavior is always to execute
6710 configure context tests,
6711 since the results of the tests may
6712 affect the list of targets to be cleaned
6714 If the configure tests do not affect these,
6715 then you may add the
6721 to avoid unnecessary test execution.
6726 instance has the following associated methods:
6729 .RI SConf.Finish( context )
6732 This method should be called after configuration is done.
6733 It returns the environment as modified
6734 by the configuration checks performed.
6735 After this method is called, no further checks can be performed
6736 with this configuration context.
6737 However, you can create a new
6739 context to perform additional checks.
6740 Only one context should be active at a time.
6742 The following Checks are predefined.
6743 (This list will likely grow larger as time
6744 goes by and developers contribute new useful tests.)
6747 .RI SConf.CheckHeader( context ", " header ", [" include_quotes ", " language ])
6749 .IR sconf .CheckHeader( header ", [" include_quotes ", " language ])
6752 is usable in the specified language.
6755 in which case the last item in the list
6756 is the header file to be checked,
6757 and the previous list items are
6760 lines should precede the
6761 header line being checked for.
6762 The optional argument
6765 a two character string, where the first character denotes the opening
6766 quote and the second character denotes the closing quote.
6767 By default, both characters are " (double quote).
6768 The optional argument
6774 and selects the compiler to be used for the check.
6775 Returns 1 on success and 0 on failure.
6778 .RI SConf.CheckCHeader( context ", " header ", [" include_quotes ])
6780 .IR sconf .CheckCHeader( header ", [" include_quotes ])
6781 This is a wrapper around
6782 .B SConf.CheckHeader
6785 is usable in the C language.
6788 in which case the last item in the list
6789 is the header file to be checked,
6790 and the previous list items are
6793 lines should precede the
6794 header line being checked for.
6795 The optional argument
6798 a two character string, where the first character denotes the opening
6799 quote and the second character denotes the closing quote (both default
6801 Returns 1 on success and 0 on failure.
6804 .RI SConf.CheckCXXHeader( context ", " header ", [" include_quotes ])
6806 .IR sconf .CheckCXXHeader( header ", [" include_quotes ])
6807 This is a wrapper around
6808 .B SConf.CheckHeader
6811 is usable in the C++ language.
6814 in which case the last item in the list
6815 is the header file to be checked,
6816 and the previous list items are
6819 lines should precede the
6820 header line being checked for.
6821 The optional argument
6824 a two character string, where the first character denotes the opening
6825 quote and the second character denotes the closing quote (both default
6827 Returns 1 on success and 0 on failure.
6830 .RI SConf.CheckFunc( context, ", " function_name ", [" header ", " language ])
6832 .IR sconf .CheckFunc( function_name ", [" header ", " language ])
6833 Checks if the specified
6834 C or C++ function is available.
6836 is the name of the function to check for.
6839 argument is a string
6843 that will be compiled
6844 to check if the function exists;
6850 char function_name();
6858 and selects the compiler to be used for the check;
6862 .RI SConf.CheckLib( context ", [" library ", " symbol ", " header ", " language ", " autoadd=1 ])
6864 .IR sconf .CheckLib([ library ", " symbol ", " header ", " language ", " autoadd=1 ])
6871 is 1 and the library provides the specified
6873 appends the library to the LIBS construction environment variable.
6875 may also be None (the default),
6878 is checked with the current LIBS variable,
6879 or a list of library names,
6880 in which case each library in the list
6888 .BR SConf.CheckLib ()
6890 you can link against the specified
6898 and selects the compiler to be used for the check;
6900 The default value for
6903 This method returns 1 on success and 0 on error.
6906 .RI SConf.CheckLibWithHeader( context ", " library ", " header ", " language ", [" call ", " autoadd ])
6908 .IR sconf .CheckLibWithHeader( library ", " header ", " language ", [" call ", " autoadd ])
6912 call, this call provides a more sophisticated way to check against libraries.
6915 specifies the library or a list of libraries to check.
6917 specifies a header to check for.
6920 in which case the last item in the list
6921 is the header file to be checked,
6922 and the previous list items are
6925 lines should precede the
6926 header line being checked for.
6928 may be one of 'C','c','CXX','cxx','C++' and 'c++'.
6930 can be any valid expression (with a trailing ';').
6934 the default simply checks that you
6935 can link against the specified
6938 specifies whether to add the library to the environment (only if the check
6939 succeeds). This method returns 1 on success and 0 on error.
6942 .RI SConf.CheckType( context ", " type_name ", [" includes ", " language ])
6944 .IR sconf .CheckType( type_name ", [" includes ", " language ])
6945 Checks for the existence of a type defined by
6948 specifies the typedef name to check for.
6950 is a string containing one or more
6952 lines that will be inserted into the program
6953 that will be run to test for the existence of the type.
6960 and selects the compiler to be used for the check;
6964 sconf.CheckType('foo_type', '#include "my_types.h"', 'C++')
6968 .RI Configure.CheckCC( self )
6969 Checks whether the C compiler (as defined by the CC construction variable) works
6970 by trying to compile a small source file.
6972 By default, SCons only detects if there is a program with the correct name, not
6973 if it is a functioning compiler.
6975 This uses the exact same command than the one used by the object builder for C
6976 source file, so it can be used to detect if a particular compiler flag works or
6980 .RI Configure.CheckCXX( self )
6981 Checks whether the C++ compiler (as defined by the CXX construction variable)
6982 works by trying to compile a small source file. By default, SCons only detects
6983 if there is a program with the correct name, not if it is a functioning compiler.
6985 This uses the exact same command than the one used by the object builder for
6986 CXX source files, so it can be used to detect if a particular compiler flag
6990 .RI Configure.CheckSHCC( self )
6991 Checks whether the C compiler (as defined by the SHCC construction variable) works
6992 by trying to compile a small source file. By default, SCons only detects if
6993 there is a program with the correct name, not if it is a functioning compiler.
6995 This uses the exact same command than the one used by the object builder for C
6996 source file, so it can be used to detect if a particular compiler flag works or
6997 not. This does not check whether the object code can be used to build a shared
6998 library, only that the compilation (not link) succeeds.
7001 .RI Configure.CheckSHCXX( self )
7002 Checks whether the C++ compiler (as defined by the SHCXX construction variable)
7003 works by trying to compile a small source file. By default, SCons only detects
7004 if there is a program with the correct name, not if it is a functioning compiler.
7006 This uses the exact same command than the one used by the object builder for
7007 CXX source files, so it can be used to detect if a particular compiler flag
7008 works or not. This does not check whether the object code can be used to build
7009 a shared library, only that the compilation (not link) succeeds.
7012 Example of a typical Configure usage:
7016 conf = Configure( env )
7017 if not conf.CheckCHeader( 'math.h' ):
7018 print 'We really need math.h!'
7020 if conf.CheckLibWithHeader( 'qt', 'qapp.h', 'c++',
7021 'QApplication qapp(0,0);' ):
7022 # do stuff for qt - usage, e.g.
7023 conf.env.Append( CPPFLAGS = '-DWITH_QT' )
7028 .RI SConf.CheckTypeSize( context ", " type_name ", [" header ", " language ", " expect ])
7030 .IR sconf .CheckTypeSize( type_name ", [" header ", " language ", " expect ])
7031 Checks for the size of a type defined by
7034 specifies the typedef name to check for.
7037 argument is a string
7041 that will be compiled
7042 to check if the function exists;
7043 the default is empty.
7050 and selects the compiler to be used for the check;
7054 argument should be an integer.
7055 If this argument is used,
7056 the function will only check whether the type
7057 given in type_name has the expected size (in bytes).
7059 .B "CheckTypeSize('short', expect = 2)"
7060 will return success only if short is two bytes.
7066 .RI SConf.CheckDeclaration( context ", " symbol ", [" includes ", " language ])
7068 .IR sconf .CheckDeclaration( symbol ", [" includes ", " language ])
7069 Checks if the specified
7073 is a string containing one or more
7075 lines that will be inserted into the program
7076 that will be run to test for the existence of the type.
7083 and selects the compiler to be used for the check;
7087 .RI SConf.Define( context ", " symbol ", [" value ", " comment ])
7089 .IR sconf .Define( symbol ", [" value ", " comment ])
7090 This function does not check for anything, but defines a
7091 preprocessor symbol that will be added to the configuration header file.
7092 It is the equivalent of AC_DEFINE,
7093 and defines the symbol
7097 and the optional comment
7105 conf = Configure( env )
7107 # Puts the following line in the config header file:
7109 conf.Define('A_SYMBOL')
7111 # Puts the following line in the config header file:
7112 # #define A_SYMBOL 1
7113 conf.Define('A_SYMBOL', 1)
7117 Be careful about quoting string values, though:
7121 conf = Configure( env )
7123 # Puts the following line in the config header file:
7124 # #define A_SYMBOL YA
7125 conf.Define('A_SYMBOL', "YA")
7127 # Puts the following line in the config header file:
7128 # #define A_SYMBOL "YA"
7129 conf.Define('A_SYMBOL', '"YA"')
7137 conf = Configure( env )
7139 # Puts the following lines in the config header file:
7140 # /* Set to 1 if you have a symbol */
7141 # #define A_SYMBOL 1
7142 conf.Define('A_SYMBOL', 1, 'Set to 1 if you have a symbol')
7146 You can define your own custom checks.
7147 in addition to the predefined checks.
7148 These are passed in a dictionary to the Configure function.
7149 This dictionary maps the names of the checks
7150 to user defined Python callables
7151 (either Python functions or class instances implementing the
7154 The first argument of the call is always a
7156 instance followed by the arguments,
7157 which must be supplied by the user of the check.
7158 These CheckContext instances define the following methods:
7161 .RI CheckContext.Message( self ", " text )
7163 Usually called before the check is started.
7165 will be displayed to the user, e.g. 'Checking for library X...'
7168 .RI CheckContext.Result( self, ", " res )
7170 Usually called after the check is done.
7172 can be either an integer or a string. In the former case, 'ok' (res != 0)
7173 or 'failed' (res == 0) is displayed to the user, in the latter case the
7174 given string is displayed.
7177 .RI CheckContext.TryCompile( self ", " text ", " extension )
7178 Checks if a file with the specified
7180 (e.g. '.c') containing
7182 can be compiled using the environment's
7184 builder. Returns 1 on success and 0 on failure.
7187 .RI CheckContext.TryLink( self ", " text ", " extension )
7188 Checks, if a file with the specified
7190 (e.g. '.c') containing
7192 can be compiled using the environment's
7194 builder. Returns 1 on success and 0 on failure.
7197 .RI CheckContext.TryRun( self ", " text ", " extension )
7198 Checks, if a file with the specified
7200 (e.g. '.c') containing
7202 can be compiled using the environment's
7204 builder. On success, the program is run. If the program
7205 executes successfully
7206 (that is, its return status is 0),
7211 is the standard output of the
7213 If the program fails execution
7214 (its return status is non-zero),
7215 then (0, '') is returned.
7218 .RI CheckContext.TryAction( self ", " action ", [" text ", " extension ])
7219 Checks if the specified
7221 with an optional source file (contents
7228 may be anything which can be converted to a
7235 is the content of the target file.
7241 .RI CheckContext.TryBuild( self ", " builder ", [" text ", " extension ])
7242 Low level implementation for testing specific builds;
7243 the methods above are based on this method.
7244 Given the Builder instance
7248 of a source file with optional
7250 this method returns 1 on success and 0 on failure. In addition,
7252 is set to the build target node, if the build was successful.
7255 Example for implementing and using custom tests:
7258 def CheckQt(context, qtdir):
7259 context.Message( 'Checking for qt ...' )
7260 lastLIBS = context.env['LIBS']
7261 lastLIBPATH = context.env['LIBPATH']
7262 lastCPPPATH= context.env['CPPPATH']
7263 context.env.Append(LIBS = 'qt', LIBPATH = qtdir + '/lib', CPPPATH = qtdir + '/include' )
7264 ret = context.TryLink("""
7266 int main(int argc, char **argv) {
7267 QApplication qapp(argc, argv);
7272 context.env.Replace(LIBS = lastLIBS, LIBPATH=lastLIBPATH, CPPPATH=lastCPPPATH)
7273 context.Result( ret )
7277 conf = Configure( env, custom_tests = { 'CheckQt' : CheckQt } )
7278 if not conf.CheckQt('/usr/lib/qt'):
7279 print 'We really need qt!'
7284 .SS Command-Line Construction Variables
7286 Often when building software,
7287 some variables must be specified at build time.
7288 For example, libraries needed for the build may be in non-standard
7289 locations, or site-specific compiler options may need to be passed to the
7294 object to support overriding construction variables
7295 on the command line:
7297 $ scons VARIABLE=foo
7299 The variable values can also be specified in a text-based SConscript file.
7300 To create a Variables object, call the Variables() function:
7303 .RI Variables([ files "], [" args ])
7304 This creates a Variables object that will read construction variables from
7305 the file or list of filenames specified in
7307 If no files are specified,
7312 then no files will be read.
7313 The optional argument
7316 values that will override anything read from the specified files;
7317 it is primarily intended to be passed the
7319 dictionary that holds variables
7320 specified on the command line.
7324 vars = Variables('custom.py')
7325 vars = Variables('overrides.py', ARGUMENTS)
7326 vars = Variables(None, {FOO:'expansion', BAR:7})
7329 Variables objects have the following methods:
7332 .RI Add( key ", [" help ", " default ", " validator ", " converter ])
7333 This adds a customizable construction variable to the Variables object.
7335 is the name of the variable.
7337 is the help text for the variable.
7339 is the default value of the variable;
7340 if the default value is
7342 and there is no explicit value specified,
7343 the construction variable will
7345 be added to the construction environment.
7347 is called to validate the value of the variable, and should take three
7348 arguments: key, value, and environment.
7349 The recommended way to handle an invalid value is
7350 to raise an exception (see example below).
7352 is called to convert the value before putting it in the environment, and
7353 should take either a value, or the value and environment, as parameters.
7356 must return a value,
7357 which will be converted into a string
7358 before being validated by the
7361 and then added to the environment.
7366 vars.Add('CC', 'The C compiler')
7368 def validate_color(key, val, env):
7369 if not val in ['red', 'blue', 'yellow']:
7370 raise "Invalid color value '%s'" % val
7371 vars.Add('COLOR', validator=valid_color)
7375 .RI AddVariables( list )
7376 A wrapper script that adds
7377 multiple customizable construction variables
7378 to a Variables object.
7380 is a list of tuple or list objects
7381 that contain the arguments
7382 for an individual call to the
7389 ('CC', 'The C compiler'),
7390 ('VALIDATE', 'An option for testing validation',
7391 'notset', validator, None),
7396 .RI Update( env ", [" args ])
7397 This updates a construction environment
7399 with the customized construction variables.
7400 Any specified variables that are
7402 configured for the Variables object
7403 will be saved and may be
7405 .BR UnknownVariables ()
7408 Normally this method is not called directly,
7409 but is called indirectly by passing the Variables object to
7410 the Environment() function:
7413 env = Environment(variables=vars)
7417 The text file(s) that were specified
7418 when the Variables object was created
7419 are executed as Python scripts,
7420 and the values of (global) Python variables set in the file
7421 are added to the construction environment.
7430 .RI UnknownVariables( )
7431 Returns a dictionary containing any
7432 variables that were specified
7433 either in the files or the dictionary
7434 with which the Variables object was initialized,
7435 but for which the Variables object was
7439 env = Environment(variables=vars)
7440 for key, value in vars.UnknownVariables():
7441 print "unknown variable: %s=%s" % (key, value)
7445 .RI Save( filename ", " env )
7446 This saves the currently set variables into a script file named
7448 that can be used on the next invocation to automatically load the current
7449 settings. This method combined with the Variables method can be used to
7450 support caching of variables between runs.
7454 vars = Variables(['variables.cache', 'custom.py'])
7457 vars.Save('variables.cache', env)
7461 .RI GenerateHelpText( env ", [" sort ])
7462 This generates help text documenting the customizable construction
7463 variables suitable to passing in to the Help() function.
7465 is the construction environment that will be used to get the actual values
7466 of customizable variables. Calling with
7470 will cause the output to be sorted
7471 by the specified argument.
7475 should take two arguments
7478 (like the standard Python
7483 Help(vars.GenerateHelpText(env))
7484 Help(vars.GenerateHelpText(env, sort=cmp))
7488 .RI FormatVariableHelpText( env ", " opt ", " help ", " default ", " actual )
7489 This method returns a formatted string
7490 containing the printable help text
7492 It is normally not called directly,
7493 but is called by the
7494 .IR GenerateHelpText ()
7495 method to create the returned help text.
7496 It may be overridden with your own
7497 function that takes the arguments specified above
7498 and returns a string of help text formatted to your liking.
7500 .IR GenerateHelpText ()
7501 will not put any blank lines or extra
7502 characters in between the entries,
7503 so you must add those characters to the returned
7504 string if you want the entries separated.
7507 def my_format(env, opt, help, default, actual):
7508 fmt = "\n%s: default=%s actual=%s (%s)\n"
7509 return fmt % (opt, default. actual, help)
7510 vars.FormatVariableHelpText = my_format
7513 To make it more convenient to work with customizable Variables,
7515 provides a number of functions
7516 that make it easy to set up
7517 various types of Variables:
7520 .RI BoolVariable( key ", " help ", " default )
7521 Return a tuple of arguments
7522 to set up a Boolean option.
7526 have a default value of
7528 and display the specified
7531 The option will interpret the values
7553 .RI EnumVariable( key ", " help ", " default ", " allowed_values ", [" map ", " ignorecase ])
7554 Return a tuple of arguments
7556 whose value may be one
7557 of a specified list of legal enumerated values.
7561 have a default value of
7563 and display the specified
7566 The option will only support those
7572 argument is a dictionary
7573 that can be used to convert
7574 input values into specific legal values
7583 then the values are case-sensitive.
7588 then values will be matched
7594 then values will be matched
7596 and all input values will be
7597 converted to lower case.
7600 .RI ListVariable( key ", " help ", " default ", " names ", [", map ])
7601 Return a tuple of arguments
7603 whose value may be one or more
7604 of a specified list of legal enumerated values.
7608 have a default value of
7610 and display the specified
7613 The option will only support the values
7616 or the values in the
7619 More than one value may be specified,
7620 with all values separated by commas.
7621 The default may be a string of
7622 comma-separated default values,
7623 or a list of the default values.
7626 argument is a dictionary
7627 that can be used to convert
7628 input values into specific legal values
7634 .RI PackageVariable( key ", " help ", " default )
7635 Return a tuple of arguments
7637 whose value is a path name
7638 of a package that may be
7639 enabled, disabled or
7640 given an explicit path name.
7644 have a default value of
7646 and display the specified
7649 The option will support the values
7656 in which case the specified
7659 or the option may be set to an
7661 (typically the path name to a package
7662 that is being enabled).
7663 The option will also support the values
7669 to disable use of the specified option.
7672 .RI PathVariable( key ", " help ", " default ", [" validator ])
7673 Return a tuple of arguments
7675 whose value is expected to be a path name.
7679 have a default value of
7681 and display the specified
7687 that will be called to
7688 verify that the specified path
7691 following ready-made validators:
7692 .BR PathVariable.PathExists
7694 which verifies that the specified path exists;
7695 .BR PathVariable.PathIsFile ,
7696 which verifies that the specified path is an existing file;
7697 .BR PathVariable.PathIsDir ,
7698 which verifies that the specified path is an existing directory;
7699 .BR PathVariable.PathIsDirCreate ,
7700 which verifies that the specified path is a directory
7701 and will create the specified directory if the path does not exist;
7703 .BR PathVariable.PathAccept ,
7704 which simply accepts the specific path name argument without validation,
7705 and which is suitable if you want your users
7706 to be able to specify a directory path that will be
7707 created as part of the build process, for example.
7708 You may supply your own
7711 which must take three arguments
7713 the name of the variable to be set;
7715 the specified value being checked;
7718 the construction environment)
7719 and should raise an exception
7720 if the specified value is not acceptable.
7723 These functions make it
7724 convenient to create a number
7725 of variables with consistent behavior
7726 in a single call to the
7732 BoolVariable('warnings', 'compilation with -Wall and similiar', 1),
7733 EnumVariable('debug', 'debug output and symbols', 'no'
7734 allowed_values=('yes', 'no', 'full'),
7735 map={}, ignorecase=0), # case sensitive
7736 ListVariable('shared',
7737 'libraries to build as shared libraries',
7739 names = list_of_libs),
7740 PackageVariable('x11',
7741 'use X11 installed here (yes = search some places)',
7743 PathVariable('qtdir', 'where the root of Qt is installed', qtdir),
7744 PathVariable('foopath', 'where the foo library is installed', foopath,
7745 PathVariable.PathIsDir),
7750 .SS File and Directory Nodes
7760 Nodes, respectively.
7761 python objects, respectively.
7762 Those objects have several user-visible attributes
7763 and methods that are often useful:
7769 This path is relative to the top-level directory
7773 The build path is the same as the source path if
7778 The absolute build path of the given file or directory.
7788 object representing the
7797 # Get the current build dir's path, relative to top.
7799 # Current dir's absolute path
7801 # Next line is always '.', because it is the top dir's path relative to itself.
7803 File('foo.c').srcnode().path # source path of the given source file.
7805 # Builders also return File objects:
7806 foo = env.Program('foo.c')
7807 print "foo will be built in %s"%foo.path
7814 Node can also be used to create
7815 file and subdirectory Nodes relative to the generating Node.
7818 Node will place the new Nodes within the directory it represents.
7821 node will place the new Nodes within its parent directory
7822 (that is, "beside" the file in question).
7827 (directory) Node and
7832 then these methods are available:
7836 Returns a directory Node for a subdirectory of
7843 Returns a file Node for a file within
7849 .IR d .Entry( name )
7850 Returns an unresolved Node within
7857 Returns a directory named
7859 within the parent directory of
7864 Returns a file named
7866 within the parent directory of
7870 .IR f .Entry( name )
7871 Returns an unresolved Node named
7873 within the parent directory of
7880 # Get a Node for a file within a directory
7881 incl = Dir('include')
7882 f = incl.File('header.h')
7884 # Get a Node for a subdirectory within a directory
7885 dist = Dir('project-3.2.1)
7886 src = dist.Dir('src')
7888 # Get a Node for a file in the same directory
7889 cfile = File('sample.c')
7890 hfile = cfile.File('sample.h')
7894 html = docs.Dir('html')
7895 index = html.File('index.html')
7896 css = index.File('app.css')
7902 can be extended to build different types of targets
7903 by adding new Builder objects
7904 to a construction environment.
7906 you should only need to add a new Builder object
7907 when you want to build a new type of file or other external target.
7908 If you just want to invoke a different compiler or other tool
7909 to build a Program, Object, Library, or any other
7910 type of output file for which
7912 already has an existing Builder,
7913 it is generally much easier to
7914 use those existing Builders
7915 in a construction environment
7916 that sets the appropriate construction variables
7919 Builder objects are created
7925 function accepts the following arguments:
7928 The command line string used to build the target from the source.
7931 a list of strings representing the command
7932 to be executed and its arguments
7933 (suitable for enclosing white space in an argument),
7935 mapping source file name suffixes to
7936 any combination of command line strings
7937 (if the builder should accept multiple source file extensions),
7940 (see the next section);
7941 or a list of any of the above.
7944 takes three arguments:
7946 - a list of source nodes,
7948 - a list of target nodes,
7950 - the construction environment.
7953 The prefix that will be prepended to the target file name.
7954 This may be specified as a:
7964 - a function or other callable that takes
7965 two arguments (a construction environment and a list of sources)
7966 and returns a prefix,
7971 - specifies a mapping from a specific source suffix (of the first
7972 source specified) to a corresponding target prefix. Both the source
7973 suffix and target prefix specifications may use environment variable
7974 substitution, and the target prefix (the 'value' entries in the
7975 dictionary) may also be a callable object. The default target prefix
7976 may be indicated by a dictionary entry with a key value of None.
7981 b = Builder("build_it < $SOURCE > $TARGET"
7984 def gen_prefix(env, sources):
7985 return "file-" + env['PLATFORM'] + '-'
7986 b = Builder("build_it < $SOURCE > $TARGET",
7987 prefix = gen_prefix)
7989 b = Builder("build_it < $SOURCE > $TARGET",
7990 suffix = { None: "file-",
7991 "$SRC_SFX_A": gen_prefix })
7995 The suffix that will be appended to the target file name.
7996 This may be specified in the same manner as the prefix above.
7997 If the suffix is a string, then
7999 will append a '.' to the beginning of the suffix if it's not already
8000 there. The string returned by callable object (or obtained from the
8001 dictionary) is untouched and must append its own '.' to the beginning
8005 b = Builder("build_it < $SOURCE > $TARGET"
8008 def gen_suffix(env, sources):
8009 return "." + env['PLATFORM'] + "-file"
8010 b = Builder("build_it < $SOURCE > $TARGET",
8011 suffix = gen_suffix)
8013 b = Builder("build_it < $SOURCE > $TARGET",
8014 suffix = { None: ".sfx1",
8015 "$SRC_SFX_A": gen_suffix })
8019 When set to any true value, causes
8021 to add the target suffix specified by the
8023 keyword to any target strings
8024 that have a different suffix.
8025 (The default behavior is to leave untouched
8026 any target file name that looks like it already has any suffix.)
8029 b1 = Builder("build_it < $SOURCE > $TARGET"
8031 b2 = Builder("build_it < $SOURCE > $TARGET"
8035 env['BUILDERS']['B1'] = b1
8036 env['BUILDERS']['B2'] = b2
8038 # Builds "foo.txt" because ensure_suffix is not set.
8039 env.B1('foo.txt', 'foo.in')
8041 # Builds "bar.txt.out" because ensure_suffix is set.
8042 env.B2('bar.txt', 'bar.in')
8046 The expected source file name suffix. This may be a string or a list
8050 A Scanner object that
8051 will be invoked to find
8052 implicit dependencies for this target file.
8053 This keyword argument should be used
8054 for Scanner objects that find
8055 implicit dependencies
8056 based only on the target file
8057 and the construction environment,
8060 (See the section "Scanner Objects," below,
8061 for information about creating Scanner objects.)
8064 A Scanner object that
8066 find implicit dependences in
8068 used to build this target file.
8069 This is where you would
8070 specify a scanner to
8073 lines in source files.
8076 Scanner object may be used to
8077 indicate that this Builder
8078 should scan directory trees
8079 for on-disk changes to files
8082 does not know about from other Builder or function calls.
8083 (See the section "Scanner Objects," below,
8084 for information about creating your own Scanner objects.)
8087 A factory function that the Builder will use
8088 to turn any targets specified as strings into SCons Nodes.
8090 SCons assumes that all targets are files.
8091 Other useful target_factory
8094 for when a Builder creates a directory target,
8097 for when a Builder can create either a file
8098 or directory target.
8103 MakeDirectoryBuilder = Builder(action=my_mkdir, target_factory=Dir)
8105 env.Append(BUILDERS = {'MakeDirectory':MakeDirectoryBuilder})
8106 env.MakeDirectory('new_directory', [])
8110 Note that the call to the MakeDirectory Builder
8111 needs to specify an empty source list
8112 to make the string represent the builder's target;
8113 without that, it would assume the argument is the source,
8114 and would try to deduce the target name from it,
8115 which in the absence of an automatically-added prefix or suffix
8116 would lead to a matching target and source name
8117 and a circular dependency.
8120 A factory function that the Builder will use
8121 to turn any sources specified as strings into SCons Nodes.
8123 SCons assumes that all source are files.
8124 Other useful source_factory
8127 for when a Builder uses a directory as a source,
8130 for when a Builder can use files
8131 or directories (or both) as sources.
8136 CollectBuilder = Builder(action=my_mkdir, source_factory=Entry)
8138 env.Append(BUILDERS = {'Collect':CollectBuilder})
8139 env.Collect('archive', ['directory_name', 'file_name'])
8143 A function or list of functions to manipulate the target and source
8144 lists before dependencies are established
8145 and the target(s) are actually built.
8147 can also be a string containing a construction variable to expand
8148 to an emitter function or list of functions,
8149 or a dictionary mapping source file suffixes
8150 to emitter functions.
8151 (Only the suffix of the first source file
8152 is used to select the actual emitter function
8153 from an emitter dictionary.)
8156 takes three arguments:
8158 - a list of source nodes,
8160 - a list of target nodes,
8162 - the construction environment.
8163 An emitter must return a tuple containing two lists,
8164 the list of targets to be built by this builder,
8165 and the list of sources for this builder.
8170 def e(target, source, env):
8171 return (target + ['foo.foo'], source + ['foo.src'])
8173 # Simple association of an emitter function with a Builder.
8174 b = Builder("my_build < $TARGET > $SOURCE",
8177 def e2(target, source, env):
8178 return (target + ['bar.foo'], source + ['bar.src'])
8180 # Simple association of a list of emitter functions with a Builder.
8181 b = Builder("my_build < $TARGET > $SOURCE",
8184 # Calling an emitter function through a construction variable.
8185 env = Environment(MY_EMITTER = e)
8186 b = Builder("my_build < $TARGET > $SOURCE",
8187 emitter = '$MY_EMITTER')
8189 # Calling a list of emitter functions through a construction variable.
8190 env = Environment(EMITTER_LIST = [e, e2])
8191 b = Builder("my_build < $TARGET > $SOURCE",
8192 emitter = '$EMITTER_LIST')
8194 # Associating multiple emitters with different file
8195 # suffixes using a dictionary.
8196 def e_suf1(target, source, env):
8197 return (target + ['another_target_file'], source)
8198 def e_suf2(target, source, env):
8199 return (target, source + ['another_source_file'])
8200 b = Builder("my_build < $TARGET > $SOURCE",
8201 emitter = {'.suf1' : e_suf1,
8206 Specifies whether this builder is allowed to be called multiple times for
8207 the same target file(s). The default is 0, which means the builder
8208 can not be called multiple times for the same target file(s). Calling a
8209 builder multiple times for the same target simply adds additional source
8210 files to the target; it is not allowed to change the environment associated
8211 with the target, specify addition environment overrides, or associate a different
8212 builder with the target.
8215 A construction environment that can be used
8216 to fetch source code using this Builder.
8217 (Note that this environment is
8219 used for normal builds of normal target files,
8220 which use the environment that was
8221 used to call the Builder for the target file.)
8224 A function that returns a list of actions that will be executed to build
8225 the target(s) from the source(s).
8226 The returned action(s) may be
8227 an Action object, or anything that
8228 can be converted into an Action object
8229 (see the next section).
8231 The generator function
8232 takes four arguments:
8234 - a list of source nodes,
8236 - a list of target nodes,
8238 - the construction environment,
8240 - a Boolean value that specifies
8241 whether the generator is being called
8242 for generating a build signature
8243 (as opposed to actually executing the command).
8247 def g(source, target, env, for_signature):
8248 return [["gcc", "-c", "-o"] + target + source]
8250 b = Builder(generator=g)
8258 arguments must not both be used for the same Builder.
8261 Specifies a builder to use when a source file name suffix does not match
8262 any of the suffixes of the builder. Using this argument produces a
8263 multi-stage builder.
8266 Specifies that this builder expects exactly one source file per call. Giving
8267 more than one source files without target files results in implicitely calling
8268 the builder multiple times (once for each source given). Giving multiple
8269 source files together with target files results in a UserError exception.
8277 arguments must not both be used for the same Builder.
8279 .IP source_ext_match
8282 argument is a dictionary,
8283 the default behavior when a builder is passed
8284 multiple source files is to make sure that the
8285 extensions of all the source files match.
8286 If it is legal for this builder to be
8287 called with a list of source files with different extensions,
8288 this check can be suppressed by setting
8292 or some other non-true value.
8297 will use the suffix of the first specified
8298 source file to select the appropriate action from the
8302 In the following example,
8307 from exiting with an error
8308 due to the mismatched suffixes of
8314 b = Builder(action={'.in' : 'build $SOURCES > $TARGET'},
8315 source_ext_match = None)
8317 env = Environment(BUILDERS = {'MyBuild':b})
8318 env.MyBuild('foo.out', ['foo.in', 'foo.extra'])
8322 A construction environment that can be used
8323 to fetch source code using this Builder.
8324 (Note that this environment is
8326 used for normal builds of normal target files,
8327 which use the environment that was
8328 used to call the Builder for the target file.)
8331 b = Builder(action="build < $SOURCE > $TARGET")
8332 env = Environment(BUILDERS = {'MyBuild' : b})
8333 env.MyBuild('foo.out', 'foo.in', my_arg = 'xyzzy')
8337 A directory from which scons
8344 a string or a directory Node,
8345 scons will change to the specified directory.
8348 is not a string or Node
8350 then scons will change to the
8351 target file's directory.
8353 Note that scons will
8355 automatically modify
8357 construction variables like
8361 when using the chdir
8362 keyword argument--that is,
8363 the expanded file names
8364 will still be relative to
8365 the top-level SConstruct directory,
8366 and consequently incorrect
8367 relative to the chdir directory.
8368 Builders created using chdir keyword argument,
8369 will need to use construction variable
8374 to use just the filename portion of the
8378 b = Builder(action="build < ${SOURCE.file} > ${TARGET.file}",
8380 env = Environment(BUILDERS = {'MyBuild' : b})
8381 env.MyBuild('sub/dir/foo.out', 'sub/dir/foo.in')
8385 Python only keeps one current directory
8386 location for all of the threads.
8387 This means that use of the
8395 because individual worker threads spawned
8396 by SCons interfere with each other
8397 when they start changing directory.
8400 Any additional keyword arguments supplied
8401 when a Builder object is created
8402 (that is, when the Builder() function is called)
8403 will be set in the executing construction
8404 environment when the Builder object is called.
8405 The canonical example here would be
8406 to set a construction variable to
8407 the repository of a source code system.
8409 Any additional keyword arguments supplied
8413 will only be associated with the target
8414 created by that particular Builder call
8415 (and any other files built as a
8416 result of the call).
8418 These extra keyword arguments are passed to the
8419 following functions:
8420 command generator functions,
8422 and emitter functions.
8428 function will turn its
8430 keyword argument into an appropriate
8431 internal Action object.
8432 You can also explicity create Action objects
8436 which can then be passed to the
8439 This can be used to configure
8440 an Action object more flexibly,
8441 or it may simply be more efficient
8442 than letting each separate Builder object
8443 create a separate Action
8445 Builder objects need to do the same thing.
8450 returns an appropriate object for the action
8451 represented by the type of the first argument:
8454 If the first argument is already an Action object,
8455 the object is simply returned.
8458 If the first argument is a string,
8459 a command-line Action is returned.
8460 Note that the command-line string
8461 may be preceded by an
8464 to suppress printing of the specified command line,
8468 to ignore the exit status from the specified command:
8471 Action('$CC -c -o $TARGET $SOURCES')
8473 # Doesn't print the line being executed.
8474 Action('@build $TARGET $SOURCES')
8476 # Ignores return value
8477 Action('-build $TARGET $SOURCES')
8479 .\" XXX From Gary Ruben, 23 April 2002:
8480 .\" What would be useful is a discussion of how you execute command
8481 .\" shell commands ie. what is the process used to spawn the shell, pass
8482 .\" environment variables to it etc., whether there is one shell per
8483 .\" environment or one per command etc. It might help to look at the Gnu
8484 .\" make documentation to see what they think is important to discuss about
8485 .\" a build system. I'm sure you can do a better job of organising the
8486 .\" documentation than they have :-)
8489 If the first argument is a list,
8490 then a list of Action objects is returned.
8491 An Action object is created as necessary
8492 for each element in the list.
8495 the list is itself a list,
8496 the internal list is the
8497 command and arguments to be executed via
8499 This allows white space to be enclosed
8500 in an argument by defining
8501 a command in a list within a list:
8504 Action([['cc', '-c', '-DWHITE SPACE', '-o', '$TARGET', '$SOURCES']])
8508 If the first argument is a Python function,
8509 a function Action is returned.
8510 The Python function must take three keyword arguments,
8512 (a Node object representing the target file),
8514 (a Node object representing the source file)
8517 (the construction environment
8518 used for building the target file).
8523 arguments may be lists of Node objects if there is
8524 more than one target file or source file.
8525 The actual target and source file name(s) may
8526 be retrieved from their Node objects
8527 via the built-in Python str() function:
8530 target_file_name = str(target)
8531 source_file_names = map(lambda x: str(x), source)
8534 The function should return
8538 to indicate a successful build of the target file(s).
8539 The function may raise an exception
8540 or return a non-zero exit status
8541 to indicate an unsuccessful build.
8544 def build_it(target = None, source = None, env = None):
8545 # build the target from the source
8548 a = Action(build_it)
8551 If the action argument is not one of the above,
8555 The second argument is optional and is used to define the output
8556 which is printed when the Action is actually performed.
8557 In the absence of this parameter,
8558 or if it's an empty string,
8559 a default output depending on the type of the action is used.
8560 For example, a command-line action will print the executed command.
8561 The argument must be either a Python function or a string.
8564 it's a function that returns a string to be printed
8565 to describe the action being executed.
8566 The function may also be specified by the
8569 Like a function to build a file,
8570 this function must take three keyword arguments:
8572 (a Node object representing the target file),
8574 (a Node object representing the source file)
8577 (a construction environment).
8582 arguments may be lists of Node objects if there is
8583 more than one target file or source file.
8585 In the second case, you provide the string itself.
8586 The string may also be specified by the
8589 The string typically contains variables, notably
8590 $TARGET(S) and $SOURCE(S), or consists of just a single
8591 variable, which is optionally defined somewhere else.
8592 SCons itself heavily uses the latter variant.
8597 def build_it(target, source, env):
8598 # build the target from the source
8601 def string_it(target, source, env):
8602 return "building '%s' from '%s'" % (target[0], source[0])
8604 # Use a positional argument.
8605 f = Action(build_it, string_it)
8606 s = Action(build_it, "building '$TARGET' from '$SOURCE'")
8608 # Alternatively, use a keyword argument.
8609 f = Action(build_it, strfunction=string_it)
8610 s = Action(build_it, cmdstr="building '$TARGET' from '$SOURCE'")
8612 # You can provide a configurable variable.
8613 l = Action(build_it, '$STRINGIT')
8616 The third and succeeding arguments, if present,
8617 may either be a construction variable or a list of construction variables
8618 whose values will be included in the signature of the Action
8619 when deciding whether a target should be rebuilt because the action changed.
8620 The variables may also be specified by a
8623 if both are present, they are combined.
8624 This is necessary whenever you want a target to be rebuilt
8625 when a specific construction variable changes.
8626 This is not often needed for a string action,
8627 as the expanded variables will normally be part of the command line,
8628 but may be needed if a Python function action uses
8629 the value of a construction variable when generating the command line.
8632 def build_it(target, source, env):
8633 # build the target from the 'XXX' construction variable
8634 open(target[0], 'w').write(env['XXX'])
8637 # Use positional arguments.
8638 a = Action(build_it, '$STRINGIT', ['XXX'])
8640 # Alternatively, use a keyword argument.
8641 a = Action(build_it, varlist=['XXX'])
8650 which specifies that
8651 scons will execute the action
8652 after changing to the specified directory.
8653 If the chdir argument is
8654 a string or a directory Node,
8655 scons will change to the specified directory.
8656 If the chdir argument
8657 is not a string or Node
8659 then scons will change to the
8660 target file's directory.
8662 Note that scons will
8664 automatically modify
8666 construction variables like
8670 when using the chdir
8671 keyword argument--that is,
8672 the expanded file names
8673 will still be relative to
8674 the top-level SConstruct directory,
8675 and consequently incorrect
8676 relative to the chdir directory.
8677 Builders created using chdir keyword argument,
8678 will need to use construction variable
8683 to use just the filename portion of the
8687 a = Action("build < ${SOURCE.file} > ${TARGET.file}",
8697 which specifies a function
8698 that is passed the exit status
8700 from the specified action
8701 and can return an arbitrary
8703 This can be used, for example,
8704 to specify that an Action object's
8705 return value should be ignored
8706 and SCons should, therefore,
8707 consider that the action always suceeds:
8710 def always_succeed(s):
8711 # Always return 0, which indicates success.
8713 a = Action("build < ${SOURCE.file} > ${TARGET.file}",
8714 exitstatfunc=always_succeed)
8717 .SS Miscellaneous Action Functions
8720 supplies a number of functions
8721 that arrange for various common
8722 file and directory manipulations
8724 These are similar in concept to "tasks" in the
8726 although the implementation is slightly different.
8727 These functions do not actually
8728 perform the specified action
8729 at the time the function is called,
8730 but instead return an Action object
8731 that can be executed at the
8733 (In Object-Oriented terminology,
8738 that return Action objects.)
8741 there are two natural ways
8744 are intended to be used.
8748 to perform the action
8749 at the time the SConscript
8753 global function to do so:
8755 Execute(Touch('file'))
8759 you can use these functions
8760 to supply Actions in a list
8764 This can allow you to
8765 perform more complicated
8766 sequences of file manipulation
8768 on platform-specific
8772 env = Environment(TMPBUILD = '/tmp/builddir')
8773 env.Command('foo.out', 'foo.in',
8774 [Mkdir('$TMPBUILD'),
8775 Copy('$TMPBUILD', '${SOURCE.dir}'),
8776 "cd $TMPBUILD && make",
8777 Delete('$TMPBUILD')])
8781 .RI Chmod( dest ", " mode )
8782 Returns an Action object that
8783 changes the permissions on the specified
8785 file or directory to the specified
8790 Execute(Chmod('file', 0755))
8792 env.Command('foo.out', 'foo.in',
8793 [Copy('$TARGET', '$SOURCE'),
8794 Chmod('$TARGET', 0755)])
8798 .RI Copy( dest ", " src )
8799 Returns an Action object
8802 source file or directory to the
8804 destination file or directory.
8808 Execute(Copy('foo.output', 'foo.input'))
8810 env.Command('bar.out', 'bar.in',
8811 Copy('$TARGET', '$SOURCE'))
8815 .RI Delete( entry ", [" must_exist ])
8816 Returns an Action that
8817 deletes the specified
8819 which may be a file or a directory tree.
8820 If a directory is specified,
8821 the entire directory tree
8826 then a Python error will be thrown
8827 if the specified entry does not exist;
8830 that is, the Action will silently do nothing
8831 if the entry does not exist.
8835 Execute(Delete('/tmp/buildroot'))
8837 env.Command('foo.out', 'foo.in',
8838 [Delete('${TARGET.dir}'),
8841 Execute(Delete('file_that_must_exist', must_exist=1))
8847 that creates the specified
8853 Execute(Mkdir('/tmp/outputdir'))
8855 env.Command('foo.out', 'foo.in',
8856 [Mkdir('/tmp/builddir'),
8857 Copy('/tmp/builddir/foo.in', '$SOURCE'),
8858 "cd /tmp/builddir && make",
8859 Copy('$TARGET', '/tmp/builddir/foo.out')])
8863 .RI Move( dest ", " src )
8865 that moves the specified
8867 file or directory to
8874 Execute(Move('file.destination', 'file.source'))
8876 env.Command('output_file', 'input_file',
8878 Move('$TARGET', 'file_created_by_MyBuildAction')])
8884 that updates the modification time
8890 Execute(Touch('file_to_be_touched'))
8892 env.Command('marker', 'input_file',
8897 .SS Variable Substitution
8899 Before executing a command,
8901 performs construction variable interpolation on the strings that make up
8902 the command line of builders.
8903 Variables are introduced by a
8906 Besides construction variables, scons provides the following
8907 variables for each command execution:
8910 The file name of the target being built, or the file name of the first
8911 target if multiple targets are being built.
8914 The file names of all targets being built.
8917 The file name of the source of the build command, or the file name of the
8918 first source if multiple sources are being built.
8921 The file names of the sources of the build command.
8923 (Note that the above variables are reserved
8924 and may not be set in a construction environment.)
8927 For example, given the construction variable CC='cc', targets=['foo'], and
8928 sources=['foo.c', 'bar.c']:
8931 action='$CC -c -o $TARGET $SOURCES'
8934 would produce the command line:
8937 cc -c -o foo foo.c bar.c
8940 Variable names may be surrounded by curly braces ({})
8941 to separate the name from the trailing characters.
8942 Within the curly braces, a variable name may have
8943 a Python slice subscript appended to select one
8944 or more items from a list.
8945 In the previous example, the string:
8957 Additionally, a variable name may
8958 have the following special
8959 modifiers appended within the enclosing curly braces
8960 to modify the interpolated string:
8963 The base path of the file name,
8964 including the directory path
8965 but excluding any suffix.
8968 The name of the directory in which the file exists.
8972 minus any directory portion.
8975 Just the basename of the file,
8977 and minus the directory.
8980 Just the file suffix.
8983 The absolute path name of the file.
8986 The POSIX form of the path,
8987 with directories separated by
8991 This is sometimes necessary on Windows systems
8992 when a path references a file on other (POSIX) systems.
8995 The directory and file name to the source file linked to this file through
8997 If this file isn't linked,
8998 it just returns the directory and filename unchanged.
9001 The directory containing the source file linked to this file through
9003 If this file isn't linked,
9004 it just returns the directory part of the filename.
9007 The directory and file name to the source file linked to this file through
9009 If the file does not exist locally but exists in a Repository,
9010 the path in the Repository is returned.
9011 If this file isn't linked, it just returns the
9012 directory and filename unchanged.
9015 The Repository directory containing the source file linked to this file through
9017 If this file isn't linked,
9018 it just returns the directory part of the filename.
9021 For example, the specified target will
9022 expand as follows for the corresponding modifiers:
9025 $TARGET => sub/dir/file.x
9026 ${TARGET.base} => sub/dir/file
9027 ${TARGET.dir} => sub/dir
9028 ${TARGET.file} => file.x
9029 ${TARGET.filebase} => file
9030 ${TARGET.suffix} => .x
9031 ${TARGET.abspath} => /top/dir/sub/dir/file.x
9033 SConscript('src/SConscript', variant_dir='sub/dir')
9034 $SOURCE => sub/dir/file.x
9035 ${SOURCE.srcpath} => src/file.x
9036 ${SOURCE.srcdir} => src
9038 Repository('/usr/repository')
9039 $SOURCE => sub/dir/file.x
9040 ${SOURCE.rsrcpath} => /usr/repository/src/file.x
9041 ${SOURCE.rsrcdir} => /usr/repository/src
9044 Note that curly braces braces may also be used
9045 to enclose arbitrary Python code to be evaluated.
9046 (In fact, this is how the above modifiers are substituted,
9047 they are simply attributes of the Python objects
9048 that represent TARGET, SOURCES, etc.)
9049 See the section "Python Code Substitution," below,
9050 for more thorough examples of
9051 how this can be used.
9053 Lastly, a variable name
9054 may be a callable Python function
9056 construction variable in the environment.
9058 take four arguments:
9060 - a list of target nodes,
9062 - a list of source nodes,
9064 - the construction environment,
9066 - a Boolean value that specifies
9067 whether the function is being called
9068 for generating a build signature.
9069 SCons will insert whatever
9070 the called function returns
9071 into the expanded string:
9074 def foo(target, source, env, for_signature):
9077 # Will expand $BAR to "bar baz"
9078 env=Environment(FOO=foo, BAR="$FOO baz")
9081 You can use this feature to pass arguments to a
9082 Python function by creating a callable class
9083 that stores one or more arguments in an object,
9084 and then uses them when the
9087 Note that in this case,
9088 the entire variable expansion must
9089 be enclosed by curly braces
9090 so that the arguments will
9091 be associated with the
9092 instantiation of the class:
9096 def __init__(self, arg):
9099 def __call__(self, target, source, env, for_signature):
9100 return self.arg + " bar"
9102 # Will expand $BAR to "my argument bar baz"
9103 env=Environment(FOO=foo, BAR="${FOO('my argument')} baz")
9107 The special pseudo-variables
9111 may be used to surround parts of a command line
9114 causing a rebuild--that is,
9115 which are not included in the signature
9116 of target files built with this command.
9121 will be removed from the command line
9122 before it is added to file signatures,
9127 will be removed before the command is executed.
9128 For example, the command line:
9131 echo Last build occurred $( $TODAY $). > $TARGET
9135 would execute the command:
9138 echo Last build occurred $TODAY. > $TARGET
9142 but the command signature added to any target files would be:
9145 echo Last build occurred . > $TARGET
9148 .SS Python Code Substitution
9150 Any python code within
9152 pairs gets evaluated by python 'eval', with the python globals set to
9153 the current environment's set of construction variables.
9154 So in the following case:
9157 env.Command('foo.out', 'foo.in',
9158 '''echo ${COND==1 and 'FOO' or 'BAR'} > $TARGET''')
9160 the command executed will be either
9168 according to the current value of env['COND'] when the command is
9169 executed. The evaluation occurs when the target is being
9170 built, not when the SConscript is being read. So if env['COND'] is changed
9171 later in the SConscript, the final value will be used.
9173 Here's a more interesting example. Note that all of COND, FOO, and
9174 BAR are environment variables, and their values are substituted into
9175 the final command. FOO is a list, so its elements are interpolated
9176 separated by spaces.
9181 env['FOO'] = ['foo1', 'foo2']
9182 env['BAR'] = 'barbar'
9183 env.Command('foo.out', 'foo.in',
9184 'echo ${COND==1 and FOO or BAR} > $TARGET')
9186 # Will execute this:
9187 # echo foo1 foo2 > foo.out
9190 SCons uses the following rules when converting construction variables into
9194 When the value is a string it is interpreted as a space delimited list of
9195 command line arguments.
9198 When the value is a list it is interpreted as a list of command line
9199 arguments. Each element of the list is converted to a string.
9202 Anything that is not a list or string is converted to a string and
9203 interpreted as a single command line argument.
9206 Newline characters (\\n) delimit lines. The newline parsing is done after
9207 all other parsing, so it is not possible for arguments (e.g. file names) to
9208 contain embedded newline characters. This limitation will likely go away in
9209 a future version of SCons.
9217 new file types for implicit dependencies.
9218 Scanner accepts the following arguments:
9222 1) a Python function that will process
9224 and return a list of strings (file names)
9225 representing the implicit
9226 dependencies found in the contents;
9228 2) a dictionary that maps keys
9229 (typically the file suffix, but see below for more discussion)
9230 to other Scanners that should be called.
9232 If the argument is actually a Python function,
9233 the function must take three or four arguments:
9235 def scanner_function(node, env, path):
9237 def scanner_function(node, env, path, arg=None):
9241 argument is the internal
9242 SCons node representing the file.
9245 to fetch the name of the file, and
9246 .B node.get_contents()
9247 to fetch contents of the file.
9248 Note that the file is
9250 guaranteed to exist before the scanner is called,
9251 so the scanner function should check that
9252 if there's any chance that the scanned file
9254 (for example, if it's built from other files).
9258 argument is the construction environment for the scan.
9259 Fetch values from it using the
9265 argument is a tuple (or list)
9266 of directories that can be searched
9268 This will usually be the tuple returned by the
9270 argument (see below).
9274 argument is the argument supplied
9275 when the scanner was created, if any.
9278 The name of the Scanner.
9280 to identify the Scanner internally.
9283 An optional argument that, if specified,
9284 will be passed to the scanner function
9286 and the path function
9290 An optional list that can be used to
9291 determine which scanner should be used for
9293 In the usual case of scanning for file names,
9294 this argument will be a list of suffixes
9295 for the different file types that this
9296 Scanner knows how to scan.
9297 If the argument is a string,
9298 then it will be expanded
9299 into a list by the current environment.
9302 A Python function that takes four or five arguments:
9303 a construction environment,
9304 a Node for the directory containing
9305 the SConscript file in which
9306 the first target was defined,
9307 a list of target nodes,
9308 a list of source nodes,
9309 and an optional argument supplied
9310 when the scanner was created.
9313 returns a tuple of directories
9314 that can be searched for files to be returned
9315 by this Scanner object.
9318 function can be used to return a ready-made
9320 for a given construction variable name,
9321 instead of having to write your own function from scratch.)
9324 The class of Node that should be returned
9325 by this Scanner object.
9326 Any strings or other objects returned
9327 by the scanner function
9328 that are not of this class
9329 will be run through the
9334 A Python function that will take a string
9336 and turn it into the appropriate class of Node
9337 to be returned by this Scanner object.
9340 An optional Python function that takes two arguments,
9341 a Node (file) and a construction environment,
9342 and returns whether the
9343 Node should, in fact,
9344 be scanned for dependencies.
9345 This check can be used to eliminate unnecessary
9346 calls to the scanner function when,
9347 for example, the underlying file
9348 represented by a Node does not yet exist.
9351 An optional flag that
9352 specifies whether this scanner should be re-invoked
9353 on the dependency files returned by the scanner.
9354 When this flag is not set,
9355 the Node subsystem will
9356 only invoke the scanner on the file being scanned,
9357 and not (for example) also on the files
9358 specified by the #include lines
9359 in the file being scanned.
9361 may be a callable function,
9362 in which case it will be called with a list of
9364 should return a list of Nodes
9365 that should be scanned recursively;
9366 this can be used to select a specific subset of
9367 Nodes for additional scanning.
9372 .B SourceFileScanner
9373 object that is used by
9376 .BR SharedObject (),
9380 which scanner should be used
9381 for different file extensions.
9383 .BR SourceFileScanner.add_scanner ()
9384 method to add your own Scanner object
9388 that builds target programs or
9389 libraries from a list of
9390 source files of different types:
9393 def xyz_scan(node, env, path):
9394 contents = node.get_contents()
9395 # Scan the contents and return the included files.
9397 XYZScanner = Scanner(xyz_scan)
9399 SourceFileScanner.add_scanner('.xyx', XYZScanner)
9401 env.Program('my_prog', ['file1.c', 'file2.f', 'file3.xyz'])
9404 .SH SYSTEM-SPECIFIC BEHAVIOR
9405 SCons and its configuration files are very portable,
9406 due largely to its implementation in Python.
9407 There are, however, a few portability
9408 issues waiting to trap the unwary.
9410 SCons handles the upper-case
9412 file suffix differently,
9413 depending on the capabilities of
9414 the underlying system.
9415 On a case-sensitive system
9416 such as Linux or UNIX,
9417 SCons treats a file with a
9419 suffix as a C++ source file.
9420 On a case-insensitive system
9422 SCons treats a file with a
9424 suffix as a C source file.
9426 SCons handles the upper-case
9428 file suffix differently,
9429 depending on the capabilities of
9430 the underlying system.
9431 On a case-sensitive system
9432 such as Linux or UNIX,
9433 SCons treats a file with a
9435 suffix as a Fortran source file
9436 that is to be first run through
9437 the standard C preprocessor.
9438 On a case-insensitive system
9440 SCons treats a file with a
9442 suffix as a Fortran source file that should
9444 be run through the C preprocessor.
9445 .SS Windows: Cygwin Tools and Cygwin Python vs. Windows Pythons
9446 Cygwin supplies a set of tools and utilities
9447 that let users work on a
9448 Windows system using a more POSIX-like environment.
9449 The Cygwin tools, including Cygwin Python,
9451 by sharing an ability to interpret UNIX-like path names.
9452 For example, the Cygwin tools
9453 will internally translate a Cygwin path name
9454 like /cygdrive/c/mydir
9455 to an equivalent Windows pathname
9456 of C:/mydir (equivalent to C:\\mydir).
9459 that are built for native Windows execution,
9460 such as the python.org and ActiveState versions,
9461 do not have the Cygwin path name semantics.
9462 This means that using a native Windows version of Python
9463 to build compiled programs using Cygwin tools
9464 (such as gcc, bison, and flex)
9465 may yield unpredictable results.
9466 "Mixing and matching" in this way
9467 can be made to work,
9468 but it requires careful attention to the use of path names
9469 in your SConscript files.
9471 In practice, users can sidestep
9472 the issue by adopting the following rules:
9474 use the Cygwin-supplied Python interpreter
9476 when using Microsoft Visual C/C++
9477 (or some other Windows compiler)
9478 use the python.org or ActiveState version of Python
9480 .SS Windows: scons.bat file
9482 SCons is executed via a wrapper
9485 This has (at least) two ramifications:
9487 First, Windows command-line users
9488 that want to use variable assignment
9490 may have to put double quotes
9491 around the assignments:
9494 scons "FOO=BAR" "BAZ=BLEH"
9497 Second, the Cygwin shell does not
9498 recognize this file as being the same
9501 command issued at the command-line prompt.
9502 You can work around this either by
9505 from the Cygwin command line,
9506 or by creating a wrapper shell
9512 The MinGW bin directory must be in your PATH environment variable or the
9513 PATH variable under the ENV construction variable for SCons
9514 to detect and use the MinGW tools. When running under the native Windows
9515 Python interpreter, SCons will prefer the MinGW tools over the Cygwin
9516 tools, if they are both installed, regardless of the order of the bin
9517 directories in the PATH variable. If you have both MSVC and MinGW
9518 installed and you want to use MinGW instead of MSVC,
9519 then you must explictly tell SCons to use MinGW by passing
9525 to the Environment() function, because SCons will prefer the MSVC tools
9526 over the MinGW tools.
9530 To help you get started using SCons,
9531 this section contains a brief overview of some common tasks.
9533 .SS Basic Compilation From a Single Source File
9537 env.Program(target = 'foo', source = 'foo.c')
9540 Note: Build the file by specifying
9541 the target as an argument
9542 ("scons foo" or "scons foo.exe").
9543 or by specifying a dot ("scons .").
9545 .SS Basic Compilation From Multiple Source Files
9549 env.Program(target = 'foo', source = Split('f1.c f2.c f3.c'))
9552 .SS Setting a Compilation Flag
9555 env = Environment(CCFLAGS = '-g')
9556 env.Program(target = 'foo', source = 'foo.c')
9559 .SS Search The Local Directory For .h Files
9563 need to set CCFLAGS to specify -I options by hand.
9564 SCons will construct the right -I options from CPPPATH.
9567 env = Environment(CPPPATH = ['.'])
9568 env.Program(target = 'foo', source = 'foo.c')
9571 .SS Search Multiple Directories For .h Files
9574 env = Environment(CPPPATH = ['include1', 'include2'])
9575 env.Program(target = 'foo', source = 'foo.c')
9578 .SS Building a Static Library
9582 env.StaticLibrary(target = 'foo', source = Split('l1.c l2.c'))
9583 env.StaticLibrary(target = 'bar', source = ['l3.c', 'l4.c'])
9586 .SS Building a Shared Library
9590 env.SharedLibrary(target = 'foo', source = ['l5.c', 'l6.c'])
9591 env.SharedLibrary(target = 'bar', source = Split('l7.c l8.c'))
9594 .SS Linking a Local Library Into a Program
9597 env = Environment(LIBS = 'mylib', LIBPATH = ['.'])
9598 env.Library(target = 'mylib', source = Split('l1.c l2.c'))
9599 env.Program(target = 'prog', source = ['p1.c', 'p2.c'])
9602 .SS Defining Your Own Builder Object
9604 Notice that when you invoke the Builder,
9605 you can leave off the target file suffix,
9606 and SCons will add it automatically.
9609 bld = Builder(action = 'pdftex < $SOURCES > $TARGET'
9611 src_suffix = '.tex')
9612 env = Environment(BUILDERS = {'PDFBuilder' : bld})
9613 env.PDFBuilder(target = 'foo.pdf', source = 'foo.tex')
9615 # The following creates "bar.pdf" from "bar.tex"
9616 env.PDFBuilder(target = 'bar', source = 'bar')
9619 Note also that the above initialization
9620 overwrites the default Builder objects,
9621 so the Environment created above
9622 can not be used call Builders like env.Program(),
9623 env.Object(), env.StaticLibrary(), etc.
9625 .SS Adding Your Own Builder Object to an Environment
9628 bld = Builder(action = 'pdftex < $SOURCES > $TARGET'
9630 src_suffix = '.tex')
9632 env.Append(BUILDERS = {'PDFBuilder' : bld})
9633 env.PDFBuilder(target = 'foo.pdf', source = 'foo.tex')
9634 env.Program(target = 'bar', source = 'bar.c')
9637 You also can use other Pythonic techniques to add
9638 to the BUILDERS construction variable, such as:
9642 env['BUILDERS]['PDFBuilder'] = bld
9645 .SS Defining Your Own Scanner Object
9647 The following example shows an extremely simple scanner (the
9650 that doesn't use a search path at all
9651 and simply returns the
9652 file names present on any
9654 lines in the scanned file.
9655 This would implicitly assume that all included
9656 files live in the top-level directory:
9661 '\" Note: the \\ in the following are for the benefit of nroff/troff,
9662 '\" not inappropriate doubled escape characters within the r'' raw string.
9663 include_re = re.compile(r'^include\\s+(\\S+)$', re.M)
9665 def kfile_scan(node, env, path, arg):
9666 contents = node.get_contents()
9667 includes = include_re.findall(contents)
9670 kscan = Scanner(name = 'kfile',
9671 function = kfile_scan,
9674 scanners = Environment().Dictionary('SCANNERS')
9675 env = Environment(SCANNERS = scanners + [kscan])
9677 env.Command('foo', 'foo.k', 'kprocess < $SOURCES > $TARGET')
9679 bar_in = File('bar.in')
9680 env.Command('bar', bar_in, 'kprocess $SOURCES > $TARGET')
9681 bar_in.target_scanner = kscan
9684 Here is a similar but more complete example that searches
9685 a path of directories
9688 construction variable)
9689 for files that actually exist:
9692 include_re = re.compile(r'^include\\s+(\\S+)$', re.M)
9694 def my_scan(node, env, path, arg):
9695 contents = node.get_contents()
9696 includes = include_re.findall(contents)
9700 for inc in includes:
9702 file = dir + os.sep + inc
9703 if os.path.exists(file):
9704 results.append(file)
9708 scanner = Scanner(name = 'myscanner',
9712 path_function = FindPathDirs('MYPATH'),
9714 scanners = Environment().Dictionary('SCANNERS')
9715 env = Environment(SCANNERS = scanners + [scanner])
9720 function used in the previous example returns a function
9721 (actually a callable Python object)
9722 that will return a list of directories
9725 construction variable.
9726 If you need to customize how the search path is derived,
9727 you would provide your own
9729 argument when creating the Scanner object,
9733 # MYPATH is a list of directories to search for files in
9734 def pf(env, dir, target, source, arg):
9735 top_dir = Dir('#').abspath
9737 if env.has_key('MYPATH'):
9738 for p in env['MYPATH']:
9739 results.append(top_dir + os.sep + p)
9742 scanner = Scanner(name = 'myscanner',
9750 .SS Creating a Hierarchical Build
9752 Notice that the file names specified in a subdirectory's
9754 file are relative to that subdirectory.
9760 env.Program(target = 'foo', source = 'foo.c')
9762 SConscript('sub/SConscript')
9767 # Builds sub/foo from sub/foo.c
9768 env.Program(target = 'foo', source = 'foo.c')
9770 SConscript('dir/SConscript')
9775 # Builds sub/dir/foo from sub/dir/foo.c
9776 env.Program(target = 'foo', source = 'foo.c')
9779 .SS Sharing Variables Between SConscript Files
9781 You must explicitly Export() and Import() variables that
9782 you want to share between SConscript files.
9788 env.Program(target = 'foo', source = 'foo.c')
9791 SConscript('subdirectory/SConscript')
9793 subdirectory/SConscript:
9796 env.Program(target = 'foo', source = 'foo.c')
9799 .SS Building Multiple Variants From the Same Source
9801 Use the variant_dir keyword argument to
9802 the SConscript function to establish
9803 one or more separate variant build directory trees
9804 for a given source directory:
9809 cppdefines = ['FOO']
9810 Export("cppdefines")
9811 SConscript('src/SConscript', variant_dir='foo')
9813 cppdefines = ['BAR']
9814 Export("cppdefines")
9815 SConscript('src/SConscript', variant_dir='bar')
9819 Import("cppdefines")
9820 env = Environment(CPPDEFINES = cppdefines)
9821 env.Program(target = 'src', source = 'src.c')
9824 Note the use of the Export() method
9825 to set the "cppdefines" variable to a different
9826 value each time we call the SConscript function.
9828 .SS Hierarchical Build of Two Libraries Linked With a Program
9833 env = Environment(LIBPATH = ['#libA', '#libB'])
9835 SConscript('libA/SConscript')
9836 SConscript('libB/SConscript')
9837 SConscript('Main/SConscript')
9842 env.Library('a', Split('a1.c a2.c a3.c'))
9847 env.Library('b', Split('b1.c b2.c b3.c'))
9852 e = env.Copy(LIBS = ['a', 'b'])
9853 e.Program('foo', Split('m1.c m2.c m3.c'))
9856 The '#' in the LIBPATH directories specify that they're relative to the
9857 top-level directory, so they don't turn into "Main/libA" when they're
9858 used in Main/SConscript.
9860 Specifying only 'a' and 'b' for the library names
9861 allows SCons to append the appropriate library
9862 prefix and suffix for the current platform
9863 (for example, 'liba.a' on POSIX systems,
9864 \&'a.lib' on Windows).
9866 .SS Customizing construction variables from the command line.
9868 The following would allow the C compiler to be specified on the command
9869 line or in the file custom.py.
9872 vars = Variables('custom.py')
9873 vars.Add('CC', 'The C compiler.')
9874 env = Environment(variables=vars)
9875 Help(vars.GenerateHelpText(env))
9878 The user could specify the C compiler on the command line:
9884 or in the custom.py file:
9890 or get documentation on the options:
9901 .SS Using Microsoft Visual C++ precompiled headers
9903 Since windows.h includes everything and the kitchen sink, it can take quite
9904 some time to compile it over and over again for a bunch of object files, so
9905 Microsoft provides a mechanism to compile a set of headers once and then
9906 include the previously compiled headers in any object file. This
9907 technology is called precompiled headers. The general recipe is to create a
9908 file named "StdAfx.cpp" that includes a single header named "StdAfx.h", and
9909 then include every header you want to precompile in "StdAfx.h", and finally
9910 include "StdAfx.h" as the first header in all the source files you are
9911 compiling to object files. For example:
9915 #include <windows.h>
9916 #include <my_big_header.h>
9935 /* do some other stuff */
9941 env['PCHSTOP'] = 'StdAfx.h'
9942 env['PCH'] = env.PCH('StdAfx.cpp')[0]
9943 env.Program('MyApp', ['Foo.cpp', 'Bar.cpp'])
9946 For more information see the document for the PCH builder, and the PCH and
9947 PCHSTOP construction variables. To learn about the details of precompiled
9948 headers consult the MSDN documention for /Yc, /Yu, and /Yp.
9950 .SS Using Microsoft Visual C++ external debugging information
9952 Since including debugging information in programs and shared libraries can
9953 cause their size to increase significantly, Microsoft provides a mechanism
9954 for including the debugging information in an external file called a PDB
9955 file. SCons supports PDB files through the PDB construction
9961 env['PDB'] = 'MyApp.pdb'
9962 env.Program('MyApp', ['Foo.cpp', 'Bar.cpp'])
9965 For more information see the document for the PDB construction variable.
9970 Specifies the directory that contains the SCons Python module directory
9971 (e.g. /home/aroach/scons-src-0.01/src/engine).
9974 A string of options that will be used by scons in addition to those passed
9975 on the command line.
9986 Steven Knight <knight@baldmt.com>
9988 Anthony Roach <aroach@electriceyeball.com>