3 .\" Permission is hereby granted, free of charge, to any person obtaining
4 .\" a copy of this software and associated documentation files (the
5 .\" "Software"), to deal in the Software without restriction, including
6 .\" without limitation the rights to use, copy, modify, merge, publish,
7 .\" distribute, sublicense, and/or sell copies of the Software, and to
8 .\" permit persons to whom the Software is furnished to do so, subject to
9 .\" the following conditions:
11 .\" The above copyright notice and this permission notice shall be included
12 .\" in all copies or substantial portions of the Software.
14 .\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY
15 .\" KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
16 .\" WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
17 .\" NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
18 .\" LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
19 .\" OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
20 .\" WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
22 .\" __FILE__ __REVISION__ __DATE__ __DEVELOPER__
24 .TH SCONS 1 "__MONTH_YEAR__"
25 .\" ES - Example Start - indents and turns off line fill
31 .\" EE - Example End - ends indent and turns line fill back on
38 scons \- a software construction tool
54 utility builds software (or other files) by determining which
55 component pieces must be rebuilt and executing the necessary commands to
60 searches for a file named
65 (in that order) in the current directory and reads its
66 configuration from the first file found.
67 An alternate file name may be
74 file can specify subsidiary
75 configuration files using the
79 these subsidiary files are named
81 although any name may be used.
82 (Because of this naming convention,
83 the term "SConscript files"
84 is sometimes used to refer
88 regardless of actual file name.)
90 The configuration files
91 specify the target files to be built, and
92 (optionally) the rules to build those targets. Reasonable default
93 rules exist for building common software components (executable
94 programs, object files, libraries), so that for most software
95 projects, only the target and input files need be specified.
101 looks for a directory named
103 in the directory containing the
107 is added to sys.path,
109 .IR site_scons/site_init.py ,
110 is evaluated if it exists,
112 .I site_scons/site_tools
113 is added to the default toolpath if it exist.
118 options for more details.
121 reads and executes the SConscript files as Python scripts,
122 so you may use normal Python scripting capabilities
123 (such as flow control, data manipulation, and imported Python libraries)
124 to handle complicated build situations.
126 however, reads and executes all of the SConscript files
128 it begins building any targets.
129 To make this obvious,
131 prints the following messages about what it is doing:
135 scons: Reading SConscript files ...
136 scons: done reading SConscript files.
137 scons: Building targets ...
139 scons: done building targets.
144 (everything except the line that reads "cp foo.in foo.out")
145 may be suppressed using the
150 does not automatically propagate
151 the external environment used to execute
153 to the commands used to build target files.
154 This is so that builds will be guaranteed
155 repeatable regardless of the environment
156 variables set at the time
159 This also means that if the compiler or other commands
160 that you want to use to build your target files
161 are not in standard system locations,
163 will not find them unless
164 you explicitly set the PATH
165 to include those locations.
166 Whenever you create an
168 construction environment,
169 you can propagate the value of PATH
170 from your external environment as follows:
174 env = Environment(ENV = {'PATH' : os.environ['PATH']})
177 Similarly, if the commands use external environment variables
178 like $PATH, $HOME, $JAVA_HOME, $LANG, $SHELL, $TERM, etc.,
179 these variables can also be explicitly propagated:
183 env = Environment(ENV = {'PATH' : os.environ['PATH'],
184 'HOME' : os.environ['HOME']})
187 Or you may explicitly propagate the invoking user's
188 complete external environment:
192 env = Environment(ENV = os.environ)
195 This comes at the expense of making your build
196 dependent on the user's environment being set correctly,
197 but it may be more convenient for many configurations.
200 can scan known input files automatically for dependency
201 information (for example, #include statements
202 in C or C++ files) and will rebuild dependent files appropriately
203 whenever any "included" input file changes.
206 ability to define new scanners for unknown input file types.
209 knows how to fetch files automatically from
210 SCCS or RCS subdirectories
211 using SCCS, RCS or BitKeeper.
214 is normally executed in a top-level directory containing a
216 file, optionally specifying
217 as command-line arguments
218 the target file or files to be built.
220 By default, the command
226 will build all target files in or below the current directory.
227 Explicit default targets
228 (to be built when no targets are specified on the command line)
229 may be defined the SConscript file(s)
232 function, described below.
236 targets are specified in the SConscript file(s),
237 all target files in or below the current directory
238 may be built by explicitly specifying
239 the current directory (.)
240 as a command-line target:
246 Building all target files,
247 including any files outside of the current directory,
248 may be specified by supplying a command-line target
249 of the root directory (on POSIX systems):
255 or the path name(s) of the volume(s) in which all the targets
256 should be built (on Windows systems):
262 To build only specific targets,
263 supply them as command-line arguments:
269 in which case only the specified targets will be built
270 (along with any derived files on which they depend).
272 Specifying "cleanup" targets in SConscript files is not usually necessary.
275 flag removes all files
276 necessary to build the specified target:
282 to remove all target files, or:
285 scons -c build export
288 to remove target files under build and export.
289 Additional files or directories to remove can be specified using the
292 Conversely, targets that would normally be removed by the
295 can be prevented from being removed by using the
299 A subset of a hierarchical tree may be built by
300 remaining at the top-level directory (where the
302 file lives) and specifying the subdirectory as the target to be
309 or by changing directory and invoking scons with the
311 option, which traverses up the directory
312 hierarchy until it finds the
314 file, and then builds
315 targets relatively to the current subdirectory:
323 supports building multiple targets in parallel via a
325 option that takes, as its argument, the number
326 of simultaneous tasks that may be spawned:
332 builds four targets in parallel, for example.
335 can maintain a cache of target (derived) files that can
336 be shared between multiple builds. When caching is enabled in a
337 SConscript file, any target files built by
340 to the cache. If an up-to-date target file is found in the cache, it
341 will be retrieved from the cache instead of being rebuilt locally.
342 Caching behavior may be disabled and controlled in other ways by the
344 .BR --cache-disable ,
347 command-line options. The
349 option is useful to prevent multiple builds
350 from trying to update the cache simultaneously.
352 Values of variables to be passed to the SConscript file(s)
353 may be specified on the command line:
359 These variables are available in SConscript files
360 through the ARGUMENTS dictionary,
361 and can be used in the SConscript file(s) to modify
362 the build in any way:
365 if ARGUMENTS.get('debug', 0):
366 env = Environment(CCFLAGS = '-g')
371 The command-line variable arguments are also available
373 indexed by their order on the command line.
374 This allows you to process them in order rather than by name,
376 ARGLIST[0] returns a tuple
377 containing (argname, argvalue).
378 A Python exception is thrown if you
379 try to access a list member that
383 requires Python version 1.5.2 or later.
384 There should be no other dependencies or requirements to run
387 .\" The following paragraph reflects the default tool search orders
388 .\" currently in SCons/Tool/__init__.py. If any of those search orders
389 .\" change, this documentation should change, too.
392 knows how to search for available programming tools
396 searches in order for the
397 Microsoft Visual C++ tools,
398 the MinGW tool chain,
399 the Intel compiler tools,
400 and the PharLap ETS compiler.
403 searches in order for the
406 and the Microsoft Visual C++ tools,
407 On SGI IRIX, IBM AIX, Hewlett Packard HP-UX, and Sun Solaris systems,
409 searches for the native compiler tools
410 (MIPSpro, Visual Age, aCC, and Forte tools respectively)
411 and the GCC tool chain.
412 On all other platforms,
413 including POSIX (Linux and UNIX) platforms,
416 for the GCC tool chain,
417 the Microsoft Visual C++ tools,
418 and the Intel compiler tools.
419 You may, of course, override these default values
420 by appropriate configuration of
421 Environment construction variables.
426 supports the same command-line options as GNU
428 and many of those supported by
433 Ignored for compatibility with non-GNU versions of
437 -c, --clean, --remove
438 Clean up by removing all target files for which a construction
439 command is specified.
440 Also remove any files or directories associated to the construction command
444 Will not remove any targets specified by the
449 .RI --cache-debug= file
450 Print debug information about the
460 the debug information are printed to the standard output.
461 The printed messages describe what signature file names are
462 being looked for in, retrieved from, or written to the
467 --cache-disable, --no-cache
468 Disable the derived-file caching specified by
471 will neither retrieve files from the cache
472 nor copy files to the cache.
475 --cache-force, --cache-populate
478 populate a cache by copying any already-existing, up-to-date
479 derived files to the cache,
480 in addition to files built by this invocation.
481 This is useful to populate a new cache with
482 all the current derived files,
483 or to add to the cache any derived files
484 recently built with caching disabled via the
492 and retrieving a derived file from the cache,
494 that would have been executed to build the file,
495 instead of the usual report,
496 "Retrieved `file' from cache."
497 This will produce consistent output for build logs,
498 regardless of whether a target
499 file was rebuilt or retrieved from the cache.
503 This specifies how the
505 call should use or generate the
506 results of configuration tests.
507 The option should be specified from
508 among the following choices:
512 scons will use its normal dependency mechanisms
513 to decide if a test must be rebuilt or not.
514 This saves time by not running the same configuration tests
515 every time you invoke scons,
516 but will overlook changes in system header files
517 or external commands (such as compilers)
518 if you don't specify those dependecies explicitly.
519 This is the default behavior.
523 If this option is specified,
524 all configuration tests will be re-run
525 regardless of whether the
526 cached results are out of date.
527 This can be used to explicitly
528 force the configuration tests to be updated
529 in response to an otherwise unconfigured change
530 in a system header file or compiler.
534 If this option is specified,
535 no configuration tests will be rerun
536 and all results will be taken from cache.
537 Note that scons will still consider it an error
538 if --config=cache is specified
539 and a necessary test does not
540 yet have any results in the cache.
543 .RI "-C" " directory" ", --directory=" directory
544 Change to the specified
546 before searching for the
551 file, or doing anything
554 options are interpreted
555 relative to the previous one, and the right-most
557 option wins. (This option is nearly
559 .BR "-f directory/SConstruct" ,
560 except that it will search for
565 in the specified directory.)
569 .\" Display dependencies while building target files. Useful for
570 .\" figuring out why a specific file is being rebuilt, as well as
571 .\" general debugging of the build process.
575 Works exactly the same way as the
577 option except for the way default targets are handled.
578 When this option is used and no targets are specified on the command line,
579 all default targets are built, whether or not they are below the current
584 Debug the build process.
586 specifies what type of debugging:
590 Print how many objects are created
591 of the various classes used internally by SCons
592 before and after reading the SConscript files
593 and before and after building targets.
594 This is not supported when run under Python versions earlier than 2.1,
595 when SCons is executed with the Python
598 or when the SCons modules
599 have been compiled with optimization
600 (that is, when executing from
606 A synonym for the newer
609 This will be deprecated in some future release
610 and ultimately removed.
614 Print an explanation of precisely why
616 is deciding to (re-)build any targets.
617 (Note: this does not print anything
624 Instruct the scanner that searches for libraries
625 to print a message about each potential library
626 name it is searching for,
627 and about the actual libraries it finds.
631 Print the include tree after each top-level target is built.
632 This is generally used to find out what files are included by the sources
633 of a given derived file:
636 $ scons --debug=includes foo.o
641 Prints a summary of hits and misses using the Memoizer,
642 an internal subsystem that counts
643 how often SCons uses cached values in memory
644 instead of recomputing them each time they're needed.
645 Only available when using Python 2.2 or later.
649 Prints how much memory SCons uses
650 before and after reading the SConscript files
651 and before and after building targets.
655 A deprecated option preserved for backwards compatibility.
659 Prints a list of the various objects
660 of the various classes used internally by SCons.
661 This only works when run under Python 2.1 or later.
665 Re-run SCons under the control of the
671 Print the raw command line used to build each target
672 before the construction environment variables are substituted.
673 Also shows which targets are being built by this command.
674 Output looks something like this:
676 $ scons --debug=presub
677 Building myprog.o with action(s):
678 $SHCC $SHCFLAGS $SHCCFLAGS $CPPFLAGS $_CPPINCFLAGS -c -o $TARGET $SOURCES
684 Prints an internal Python stack trace
685 when encountering an otherwise unexplained error.
689 A synonym for the newer
692 This will be deprecated in some future release
693 and ultimately removed.
697 Prints various time profiling information:
698 the time spent executing each individual build command;
699 the total build time (time SCons ran from beginning to end);
700 the total time spent reading and executing SConscript files;
701 the total time spent SCons itself spend running
702 (that is, not counting reading and executing SConscript files);
703 and both the total time spent executing all build commands
704 and the elapsed wall-clock time spent executing those build commands.
707 is executed without the
710 the elapsed wall-clock time will typically
711 be slightly longer than the total time spent
712 executing all the build commands,
713 due to the SCons processing that takes place
714 in between executing each command.
722 and your build configuration allows good parallelization,
723 the elapsed wall-clock time should
724 be significantly smaller than the
725 total time spent executing all the build commands,
726 since multiple build commands and
727 intervening SCons processing
728 should take place in parallel.)
732 A synonym for the newer
735 This will be deprecated in some future release
736 and ultimately removed.
739 .RI --diskcheck= types
740 Enable specific checks for
741 whether or not there is a file on disk
742 where the SCons configuration expects a directory
744 and whether or not RCS or SCCS sources exist
745 when searching for source and include files.
748 argument can be set to:
750 to enable all checks explicitly
751 (the default behavior);
753 to disable all such checks;
755 to check that files and directories on disk
756 match SCons' expected configuration;
758 to check for the existence of an RCS source
759 for any missing source or include files;
761 to check for the existence of an SCCS source
762 for any missing source or include files.
763 Multiple checks can be specified separated by commas;
765 .B --diskcheck=sccs,rcs
766 would still check for SCCS and RCS sources,
767 but disable the check for on-disk matches of files and directories.
768 Disabling some or all of these checks
769 can provide a performance boost for large configurations,
770 or when the configuration will check for files and/or directories
771 across networked or shared file systems,
772 at the slight increased risk of an incorrect build
773 or of not handling errors gracefully
774 (if include files really should be
775 found in SCCS or RCS, for example,
776 or if a file really does exist
777 where the SCons configuration expects a directory).
780 .RI --duplicate= ORDER
781 There are three ways to duplicate files in a build tree: hard links,
782 soft (symbolic) links and copies. The default behaviour of SCons is to
783 prefer hard links to soft links to copies. You can specify different
784 behaviours with this option.
794 SCons will attempt to duplicate files using
795 the mechanisms in the specified order.
798 .\" -e, --environment-overrides
799 .\" Variables from the execution environment override construction
800 .\" variables from the SConscript files.
803 .RI -f " file" ", --file=" file ", --makefile=" file ", --sconstruct=" file
806 as the initial SConscript file.
809 options may be specified,
812 will read all of the specified files.
816 Print a local help message for this build, if one is defined in
817 the SConscript file(s), plus a line that describes the
819 option for command-line option help. If no local help message
820 is defined, prints the standard help message about command-line
821 options. Exits after displaying the appropriate message.
825 Print the standard help message about command-line options and
830 Ignore all errors from commands executed to rebuild files.
833 .RI -I " directory" ", --include-dir=" directory
837 imported Python modules. If several
840 are used, the directories are searched in the order specified.
844 Cache implicit dependencies.
847 to use the implicit (scanned) dependencies
848 from the last time it was run
849 instead of scanning the files for implicit dependencies.
850 This can significantly speed up SCons,
851 but with the following limitations:
854 will not detect changes to implicit dependency search paths
856 .BR CPPPATH ", " LIBPATH )
857 that would ordinarily
858 cause different versions of same-named files to be used.
861 will miss changes in the implicit dependencies
862 in cases where a new implicit
863 dependency is added earlier in the implicit dependency search path
865 .BR CPPPATH ", " LIBPATH )
866 than a current implicit dependency with the same name.
869 --implicit-deps-changed
870 Forces SCons to ignore the cached implicit dependencies. This causes the
871 implicit dependencies to be rescanned and recached. This implies
872 .BR --implicit-cache .
875 --implicit-deps-unchanged
876 Force SCons to ignore changes in the implicit dependencies.
877 This causes cached implicit dependencies to always be used.
879 .BR --implicit-cache .
883 Starts SCons in interactive mode.
884 The SConscript files are read once and a
887 Targets may now be rebuilt by typing commands at interactive prompt
888 without having to re-read the SConscript files
889 and re-initialize the dependency graph from scratch.
891 SCons interactive mode supports the following commands:
895 .BI build "[OPTIONS] [TARGETS] ..."
898 (and their dependencies)
907 The following SCons command-line options affect the
913 --cache-disable, --no-cache
914 --cache-force, --cache-populate
920 -n, --no-exec, --just-print, --dry-run, --recon
922 -s, --silent, --quiet
923 --taskmastertrace=FILE
928 Any other SCons command-line options that are specified
930 but have no effect on the
933 (mainly because they affect how the SConscript files are read,
934 which only happens once at the beginning of interactive mode).
937 .BI clean "[OPTIONS] [TARGETS] ..."
940 (and their dependencies)
941 with the specified options.
944 This command is itself a synonym for
949 Exits SCons interactive mode.
950 You can also exit by terminating input
951 (CTRL+D on UNIX or Linux systems,
952 CTRL+Z on Windows systems).
956 Provides a help message about
957 the commands available in SCons interactive mode.
967 .BI shell "[COMMANDLINE]"
968 Executes the specified
974 executes the interactive command interpreter
978 (on UNIX and Linux systems)
982 (on Windows systems).
990 Prints SCons version information.
994 An empty line repeats the last typed command.
995 Command-line editing can be used if the
1000 $ scons --interactive
1001 scons: Reading SConscript files ...
1002 scons: done reading SConscript files.
1003 scons>>> build -n prog
1008 .RI -j " N" ", --jobs=" N
1009 Specifies the number of jobs (commands) to run simultaneously.
1010 If there is more than one
1012 option, the last one is effective.
1016 .\" is specified without an argument,
1018 .\" will not limit the number of
1019 .\" simultaneous jobs.
1023 Continue as much as possible after an error. The target that
1024 failed and those that depend on it will not be remade, but other
1025 targets specified on the command line will still be processed.
1028 .\" .RI -l " N" ", --load-average=" N ", --max-load=" N
1029 .\" No new jobs (commands) will be started if
1030 .\" there are other jobs running and the system load
1031 .\" average is at least
1033 .\" (a floating-point number).
1038 .\" List derived files (targets, dependencies) that would be built,
1039 .\" but do not build them.
1040 .\" [XXX This can probably go away with the right
1041 .\" combination of other options. Revisit this issue.]
1045 .\" List derived files that would be built, with the actions
1046 .\" (commands) that build them. Does not build the files.
1047 .\" [XXX This can probably go away with the right
1048 .\" combination of other options. Revisit this issue.]
1052 .\" List derived files that would be built, plus where the file is
1053 .\" defined (file name and line number). Does not build the files.
1054 .\" [XXX This can probably go away with the right
1055 .\" combination of other options. Revisit this issue.]
1059 Ignored for compatibility with non-GNU versions of
1063 .RI --max-drift= SECONDS
1064 Set the maximum expected drift in the modification time of files to
1066 This value determines how long a file must be unmodified
1067 before its cached content signature
1068 will be used instead of
1069 calculating a new content signature (MD5 checksum)
1070 of the file's contents.
1071 The default value is 2 days, which means a file must have a
1072 modification time of at least two days ago in order to have its
1073 cached content signature used.
1074 A negative value means to never cache the content
1075 signature and to ignore the cached value if there already is one. A value
1076 of 0 means to always use the cached signature,
1077 no matter how old the file is.
1080 .RI --md5-chunksize= KILOBYTES
1081 Set the block size used to compute MD5 signatures to
1083 This value determines the size of the chunks which are read in at once when
1084 computing MD5 signatures. Files below that size are fully stored in memory
1085 before performing the signature computation while bigger files are read in
1086 block-by-block. A huge block-size leads to high memory consumption while a very
1087 small block-size slows down the build considerably.
1089 The default value is to use a chunk size of 64 kilobytes, which should
1090 be appropriate for most uses.
1093 -n, --just-print, --dry-run, --recon
1094 No execute. Print the commands that would be executed to build
1095 any out-of-date target files, but do not execute the commands.
1099 Prevents the automatic addition of the standard
1103 Also prevents loading the
1104 .I site_scons/site_init.py
1105 module if it exists, and prevents adding
1106 .I site_scons/site_tools
1110 .\" .RI -o " file" ", --old-file=" file ", --assume-old=" file
1114 .\" not rebuild anything due to changes in the contents of
1117 .\" .RI --override " file"
1118 .\" Read values to override specific build environment variables
1119 .\" from the specified
1123 .\" Print the data base (construction environments,
1124 .\" Builder and Scanner objects) that are defined
1125 .\" after reading the SConscript files.
1126 .\" After printing, a normal build is performed
1127 .\" as usual, as specified by other command-line options.
1128 .\" This also prints version information
1133 .\" To print the database without performing a build do:
1141 Run SCons under the Python profiler
1142 and save the results in the specified
1144 The results may be analyzed using the Python
1149 Do not run any commands, or print anything. Just return an exit
1150 status that is zero if the specified targets are already up to
1151 date, non-zero otherwise.
1154 Quiets SCons status messages about
1155 reading SConscript files,
1157 and entering directories.
1158 Commands that are executed
1159 to rebuild target files are still printed.
1162 .\" -r, -R, --no-builtin-rules, --no-builtin-variables
1163 .\" Clear the default construction variables. Construction
1164 .\" environments that are created will be completely empty.
1168 Build dependencies in a random order. This is useful when
1169 building multiple trees simultaneously with caching enabled,
1170 to prevent multiple builds from simultaneously trying to build
1171 or retrieve the same target files.
1174 -s, --silent, --quiet
1175 Silent. Do not print commands that are executed to rebuild
1177 Also suppresses SCons status messages.
1180 -S, --no-keep-going, --stop
1181 Ignored for compatibility with GNU
1186 Uses the named dir as the site dir rather than the default
1188 dir. This dir will get prepended to
1191 .IR dir /site_init.py
1192 will get loaded if it exists, and
1194 will get added to the default toolpath.
1197 .RI --stack-size= KILOBYTES
1198 Set the size stack used to run threads to
1200 This value determines the stack size of the threads used to run jobs.
1201 These are the threads that execute the actions of the builders for the
1202 nodes that are out-of-date.
1203 Note that this option has no effect unless the
1205 option, which corresponds to -j and --jobs, is larger than one. Using
1206 a stack size that is too small may cause stack overflow errors. This
1207 usually shows up as segmentation faults that cause scons to abort
1208 before building anything. Using a stack size that is too large will
1209 cause scons to use more memory than required and may slow down the entire
1212 The default value is to use a stack size of 256 kilobytes, which should
1213 be appropriate for most uses. You should not need to increase this value
1214 unless you encounter stack overflow errors.
1218 Ignored for compatibility with GNU
1220 (Touching a file to make it
1221 appear up-to-date is unnecessary when using
1225 .RI --taskmastertrace= file
1226 Prints trace information to the specified
1228 about how the internal Taskmaster object
1229 evaluates and controls the order in which Nodes are built.
1232 may be used to specify the standard output.
1236 Prints a tree of the dependencies
1237 after each top-level target is built.
1238 This prints out some or all of the tree,
1246 Print the entire dependency tree
1247 after each top-level target is built.
1248 This prints out the complete dependency tree,
1249 including implicit dependencies and ignored dependencies.
1253 Restricts the tree output to only derived (target) files,
1258 Prints status information for each displayed node.
1262 Prunes the tree to avoid repeating dependency information
1263 for nodes that have already been displayed.
1264 Any node that has already been displayed
1265 will have its name printed in
1266 .BR "[square brackets]" ,
1267 as an indication that the dependencies
1268 for that node can be found by searching
1269 for the relevant output higher up in the tree.
1272 Multiple options may be specified,
1273 separated by commas:
1276 # Prints only derived files, with status information:
1277 scons --tree=derived,status
1279 # Prints all dependencies of target, with status information
1280 # and pruning dependencies of already-visited Nodes:
1281 scons --tree=all,prune,status target
1285 -u, --up, --search-up
1286 Walks up the directory structure until an
1291 file is found, and uses that
1292 as the top of the directory tree.
1293 If no targets are specified on the command line,
1294 only targets at or below the
1295 current directory will be built.
1299 Works exactly the same way as the
1301 option except for the way default targets are handled.
1302 When this option is used and no targets are specified on the command line,
1303 all default targets that are defined in the SConscript(s) in the current
1304 directory are built, regardless of what directory the resultant targets end
1311 version, copyright information,
1312 list of authors, and any other relevant information.
1316 -w, --print-directory
1317 Print a message containing the working directory before and
1318 after other processing.
1321 --no-print-directory
1322 Turn off -w, even if it was turned on implicitly.
1325 .RI --warn= type ", --warn=no-" type
1326 Enable or disable warnings.
1328 specifies the type of warnings to be enabled or disabled:
1331 --warn=all, --warn=no-all
1332 Enables or disables all warnings.
1335 --warn=cache-write-error, --warn=no-cache-write-error
1336 Enables or disables warnings about errors trying to
1337 write a copy of a built file to a specified
1339 These warnings are disabled by default.
1342 --warn=corrupt-sconsign, --warn=no-corrupt-sconsign
1343 Enables or disables warnings about unfamiliar signature data in
1346 These warnings are enabled by default.
1349 --warn=dependency, --warn=no-dependency
1350 Enables or disables warnings about dependencies.
1351 These warnings are disabled by default.
1354 --warn=deprecated, --warn=no-deprecated
1355 Enables or disables all warnings about use of
1356 currently deprecated features.
1357 These warnings are enabled by default.
1359 .B --warn=no-deprecated
1360 option does not disable warnings about absolutely all deprecated features.
1361 Warnings for some deprecated features that have already been through
1362 several releases with deprecation warnings
1363 may be mandatory for a release or two
1364 before they are officially no longer supported by SCons.
1365 Warnings for some specific deprecated features
1366 may be enabled or disabled individually;
1371 --warn=deprecated-copy, --warn=no-deprecated-copy
1372 Enables or disables warnings about use of the deprecated
1377 --warn=deprecated-source-signatures, --warn=no-deprecated-source-signatures
1378 Enables or disables warnings about use of the deprecated
1379 .B SourceSignatures()
1381 .B env.SourceSignatures()
1385 --warn=deprecated-target-signatures, --warn=no-deprecated-target-signatures
1386 Enables or disables warnings about use of the deprecated
1387 .B TargetSignatures()
1389 .B env.TargetSignatures()
1394 --warn=duplicate-environment, --warn=no-duplicate-environment
1395 Enables or disables warnings about attempts to specify a build
1396 of a target with two different construction environments
1397 that use the same action.
1398 These warnings are enabled by default.
1401 --warn=fortran-cxx-mix, --warn=no-fortran-cxx-mix
1402 Enables or disables the specific warning about linking
1403 Fortran and C++ object files in a single executable,
1404 which can yield unpredictable behavior with some compilers.
1407 --warn=future-deprecated, --warn=no-future-deprecated
1408 Enables or disables warnings about features
1409 that will be deprecated in the future.
1410 These warnings are disabled by default.
1411 Enabling this warning is especially
1412 recommended for projects that redistribute
1413 SCons configurations for other users to build,
1414 so that the project can be warned as soon as possible
1415 about to-be-deprecated features
1416 that may require changes to the configuration.
1419 --warn=link, --warn=no-link
1420 Enables or disables warnings about link steps.
1423 --warn=misleading-keywords, --warn=no-misleading-keywords
1424 Enables or disables warnings about use of the misspelled keywords
1428 when calling Builders.
1431 characters, the correct spellings are
1435 These warnings are enabled by default.
1438 --warn=missing-sconscript, --warn=no-missing-sconscript
1439 Enables or disables warnings about missing SConscript files.
1440 These warnings are enabled by default.
1443 --warn=no-md5-module, --warn=no-no-md5-module
1444 Enables or disables warnings about the version of Python
1445 not having an MD5 checksum module available.
1446 These warnings are enabled by default.
1449 --warn=no-metaclass-support, --warn=no-no-metaclass-support
1450 Enables or disables warnings about the version of Python
1451 not supporting metaclasses when the
1454 These warnings are enabled by default.
1457 --warn=no-object-count, --warn=no-no-object-count
1458 Enables or disables warnings about the
1460 feature not working when
1462 is run with the python
1464 option or from optimized Python (.pyo) modules.
1467 --warn=no-parallel-support, --warn=no-no-parallel-support
1468 Enables or disables warnings about the version of Python
1469 not being able to support parallel builds when the
1472 These warnings are enabled by default.
1475 --warn=python-version, --warn=no-python-version
1476 Enables or disables the warning about running
1477 SCons with a deprecated version of Python.
1478 These warnings are enabled by default.
1481 --warn=reserved-variable, --warn=no-reserved-variable
1482 Enables or disables warnings about attempts to set the
1483 reserved construction variable names
1484 .BR CHANGED_SOURCES ,
1485 .BR CHANGED_TARGETS ,
1490 .BR UNCHANGED_SOURCES
1492 .BR UNCHANGED_TARGETS .
1493 These warnings are disabled by default.
1496 --warn=stack-size, --warn=no-stack-size
1497 Enables or disables warnings about requests to set the stack size
1498 that could not be honored.
1499 These warnings are enabled by default.
1502 .\" .RI --write-filenames= file
1503 .\" Write all filenames considered into
1507 .\" .RI -W " file" ", --what-if=" file ", --new-file=" file ", --assume-new=" file
1508 .\" Pretend that the target
1511 .\" modified. When used with the
1514 .\" show you what would be rebuilt if you were to modify that file.
1520 .\" --warn-undefined-variables
1521 .\" Warn when an undefined variable is referenced.
1524 .RI -Y " repository" ", --repository=" repository ", --srcdir=" repository
1525 Search the specified repository for any input and target
1526 files not found in the local directory hierarchy. Multiple
1528 options may be specified, in which case the
1529 repositories are searched in the order specified.
1531 .SH CONFIGURATION FILE REFERENCE
1532 .\" .SS Python Basics
1533 .\" XXX Adding this in the future would be a help.
1534 .SS Construction Environments
1535 A construction environment is the basic means by which the SConscript
1536 files communicate build information to
1538 A new construction environment is created using the
1549 may be set in a construction environment
1550 either by specifying them as keywords when the object is created
1551 or by assigning them a value after the object is created:
1554 env = Environment(FOO = 'foo')
1559 construction variables may also be set or modified by the
1561 keyword argument, which applies the
1563 method (described below) to the argument value
1564 after all other processing is completed.
1565 This is useful either if the exact content of the flags is unknown
1566 (for example, read from a control file)
1567 or if the flags are distributed to a number of construction variables.
1570 env = Environment(parse_flags = '-Iinclude -DEBUG -lm')
1573 This example adds 'include' to
1580 By default, a new construction environment is
1581 initialized with a set of builder methods
1582 and construction variables that are appropriate
1583 for the current platform.
1584 An optional platform keyword argument may be
1585 used to specify that an environment should
1586 be initialized for a different platform:
1589 env = Environment(platform = 'cygwin')
1590 env = Environment(platform = 'os2')
1591 env = Environment(platform = 'posix')
1592 env = Environment(platform = 'win32')
1595 Specifying a platform initializes the appropriate
1596 construction variables in the environment
1597 to use and generate file names with prefixes
1598 and suffixes appropriate for the platform.
1606 variables from the user's external environment
1607 to the construction environment's
1610 This is so that any executed commands
1611 that use sockets to connect with other systems
1612 (such as fetching source files from
1613 external CVS repository specifications like
1614 .BR :pserver:anonymous@cvs.sourceforge.net:/cvsroot/scons )
1615 will work on Windows systems.
1617 The platform argument may be function or callable object,
1618 in which case the Environment() method
1619 will call the specified argument to update
1620 the new construction environment:
1623 def my_platform(env):
1624 env['VAR'] = 'xyzzy'
1626 env = Environment(platform = my_platform)
1629 Additionally, a specific set of tools
1630 with which to initialize the environment
1631 may be specified as an optional keyword argument:
1634 env = Environment(tools = ['msvc', 'lex'])
1637 Non-built-in tools may be specified using the toolpath argument:
1640 env = Environment(tools = ['default', 'foo'], toolpath = ['tools'])
1643 This looks for a tool specification in tools/foo.py (as well as
1644 using the ordinary default tools for the platform). foo.py should
1645 have two functions: generate(env, **kw) and exists(env).
1649 modifies the passed-in environment
1650 to set up variables so that the tool
1652 it may use any keyword arguments
1653 that the user supplies (see below)
1654 to vary its initialization.
1657 function should return a true
1658 value if the tool is available.
1659 Tools in the toolpath are used before
1660 any of the built-in ones. For example, adding gcc.py to the toolpath
1661 would override the built-in gcc tool.
1662 Also note that the toolpath is
1663 stored in the environment for use
1671 base = Environment(toolpath=['custom_path'])
1672 derived = base.Clone(tools=['custom_tool'])
1673 derived.CustomBuilder()
1676 The elements of the tools list may also
1677 be functions or callable objects,
1678 in which case the Environment() method
1679 will call the specified elements
1680 to update the new construction environment:
1684 env['XYZZY'] = 'xyzzy'
1686 env = Environment(tools = [my_tool])
1689 The individual elements of the tools list
1690 may also themselves be two-element lists of the form
1691 .RI ( toolname ", " kw_dict ).
1692 SCons searches for the
1694 specification file as described above, and
1697 which must be a dictionary, as keyword arguments to the tool's
1702 function can use the arguments to modify the tool's behavior
1703 by setting up the environment in different ways
1704 or otherwise changing its initialization.
1707 # in tools/my_tool.py:
1708 def generate(env, **kw):
1709 # Sets MY_TOOL to the value of keyword argument 'arg1' or 1.
1710 env['MY_TOOL'] = kw.get('arg1', '1')
1715 env = Environment(tools = ['default', ('my_tool', {'arg1': 'abc'})],
1719 The tool definition (i.e. my_tool()) can use the PLATFORM variable from
1720 the environment it receives to customize the tool for different platforms.
1722 If no tool list is specified, then SCons will auto-detect the installed
1723 tools using the PATH variable in the ENV construction variable and the
1724 platform name when the Environment is constructed. Changing the PATH
1725 variable after the Environment is constructed will not cause the tools to
1728 SCons supports the following tool specifications out of the box:
1810 Additionally, there is a "tool" named
1812 which configures the
1813 environment with a default set of tools for the current platform.
1815 On posix and cygwin platforms
1816 the GNU tools (e.g. gcc) are preferred by SCons,
1817 on Windows the Microsoft tools (e.g. msvc)
1818 followed by MinGW are preferred by SCons,
1819 and in OS/2 the IBM tools (e.g. icc) are preferred by SCons.
1823 Build rules are specified by calling a construction
1824 environment's builder methods.
1825 The arguments to the builder methods are
1827 (a list of targets to be built,
1831 (a list of sources to be built,
1832 usually file names).
1834 Because long lists of file names
1835 can lead to a lot of quoting,
1840 and a same-named environment method
1841 that split a single string
1842 into a list, separated on
1843 strings of white-space characters.
1844 (These are similar to the split() member function of Python strings
1845 but work even if the input isn't a string.)
1847 Like all Python arguments,
1848 the target and source arguments to a builder method
1849 can be specified either with or without
1850 the "target" and "source" keywords.
1851 When the keywords are omitted,
1852 the target is first,
1853 followed by the source.
1854 The following are equivalent examples of calling the Program builder method:
1857 env.Program('bar', ['bar.c', 'foo.c'])
1858 env.Program('bar', Split('bar.c foo.c'))
1859 env.Program('bar', env.Split('bar.c foo.c'))
1860 env.Program(source = ['bar.c', 'foo.c'], target = 'bar')
1861 env.Program(target = 'bar', Split('bar.c foo.c'))
1862 env.Program(target = 'bar', env.Split('bar.c foo.c'))
1863 env.Program('bar', source = 'bar.c foo.c'.split())
1866 Target and source file names
1867 that are not absolute path names
1868 (that is, do not begin with
1875 an optional drive letter)
1876 are interpreted relative to the directory containing the
1882 on a path name means that the rest of the file name
1883 is interpreted relative to
1884 the directory containing
1890 is followed by a directory separator character
1891 (slash or backslash).
1896 # The comments describing the targets that will be built
1897 # assume these calls are in a SConscript file in the
1898 # a subdirectory named "subdir".
1900 # Builds the program "subdir/foo" from "subdir/foo.c":
1901 env.Program('foo', 'foo.c')
1903 # Builds the program "/tmp/bar" from "subdir/bar.c":
1904 env.Program('/tmp/bar', 'bar.c')
1906 # An initial '#' or '#/' are equivalent; the following
1907 # calls build the programs "foo" and "bar" (in the
1908 # top-level SConstruct directory) from "subdir/foo.c" and
1909 # "subdir/bar.c", respectively:
1910 env.Program('#foo', 'foo.c')
1911 env.Program('#/bar', 'bar.c')
1913 # Builds the program "other/foo" (relative to the top-level
1914 # SConstruct directory) from "subdir/foo.c":
1915 env.Program('#other/foo', 'foo.c')
1918 When the target shares the same base name
1919 as the source and only the suffix varies,
1920 and if the builder method has a suffix defined for the target file type,
1921 then the target argument may be omitted completely,
1924 will deduce the target file name from
1925 the source file name.
1926 The following examples all build the
1932 (on Windows systems)
1933 from the bar.c source file:
1936 env.Program(target = 'bar', source = 'bar.c')
1937 env.Program('bar', source = 'bar.c')
1938 env.Program(source = 'bar.c')
1939 env.Program('bar.c')
1944 keyword argument may be specified
1945 when calling a Builder.
1947 all source file strings that are not absolute paths
1948 will be interpreted relative to the specified
1950 The following example will build the
1955 program from the files
1961 env.Program('build/prog', ['f1.c', 'f2.c'], srcdir='src')
1964 It is possible to override or add construction variables when calling a
1965 builder method by passing additional keyword arguments.
1966 These overridden or added
1967 variables will only be in effect when building the target, so they will not
1968 affect other parts of the build. For example, if you want to add additional
1969 libraries for just one program:
1972 env.Program('hello', 'hello.c', LIBS=['gl', 'glut'])
1975 or generate a shared library with a non-standard suffix:
1978 env.SharedLibrary('word', 'word.cpp',
1980 LIBSUFFIXES=['.ocx'])
1983 (Note that both the $SHLIBSUFFIX and $LIBSUFFIXES variables must be set
1984 if you want SCons to search automatically
1985 for dependencies on the non-standard library names;
1986 see the descriptions of these variables, below, for more information.)
1988 It is also possible to use the
1990 keyword argument in an override:
1993 env = Program('hello', 'hello.c', parse_flags = '-Iinclude -DEBUG -lm')
1996 This example adds 'include' to
2003 Although the builder methods defined by
2006 methods of a construction environment object,
2007 they may also be called without an explicit environment:
2010 Program('hello', 'hello.c')
2011 SharedLibrary('word', 'word.cpp')
2015 the methods are called internally using a default construction
2016 environment that consists of the tools and values that
2018 has determined are appropriate for the local system.
2020 Builder methods that can be called without an explicit
2021 environment may be called from custom Python modules that you
2022 import into an SConscript file by adding the following
2023 to the Python module:
2026 from SCons.Script import *
2029 All builder methods return a list-like object
2030 containing Nodes that
2031 represent the target or targets that will be built.
2034 is an internal SCons object
2036 build targets or sources.
2038 The returned Node-list object
2039 can be passed to other builder methods as source(s)
2040 or passed to any SCons function or method
2041 where a filename would normally be accepted.
2042 For example, if it were necessary
2045 flag when compiling one specific object file:
2048 bar_obj_list = env.StaticObject('bar.c', CPPDEFINES='-DBAR')
2049 env.Program(source = ['foo.c', bar_obj_list, 'main.c'])
2052 Using a Node in this way
2053 makes for a more portable build
2054 by avoiding having to specify
2055 a platform-specific object suffix
2056 when calling the Program() builder method.
2058 Note that Builder calls will automatically "flatten"
2059 the source and target file lists,
2060 so it's all right to have the bar_obj list
2061 return by the StaticObject() call
2062 in the middle of the source file list.
2063 If you need to manipulate a list of lists returned by Builders
2064 directly using Python,
2065 you can either build the list by hand:
2068 foo = Object('foo.c')
2069 bar = Object('bar.c')
2070 objects = ['begin.o'] + foo + ['middle.o'] + bar + ['end.o']
2071 for object in objects:
2077 function supplied by scons
2078 to create a list containing just the Nodes,
2079 which may be more convenient:
2082 foo = Object('foo.c')
2083 bar = Object('bar.c')
2084 objects = Flatten(['begin.o', foo, 'middle.o', bar, 'end.o'])
2085 for object in objects:
2089 Note also that because Builder calls return
2090 a list-like object, not an actual Python list,
2095 operator to append Builder results to a Python list.
2096 Because the list and the object are different types,
2097 Python will not update the original list in place,
2098 but will instead create a new Node-list object
2099 containing the concatenation of the list
2100 elements and the Builder results.
2101 This will cause problems for any other Python variables
2102 in your SCons configuration
2103 that still hold on to a reference to the original list.
2104 Instead, use the Python
2106 method to make sure the list is updated in-place.
2112 # Do NOT use += as follows:
2114 # object_files += Object('bar.c')
2116 # It will not update the object_files list in place.
2118 # Instead, use the .extend() method:
2119 object_files.extend(Object('bar.c'))
2123 The path name for a Node's file may be used
2124 by passing the Node to the Python-builtin
2129 bar_obj_list = env.StaticObject('bar.c', CPPDEFINES='-DBAR')
2130 print "The path to bar_obj is:", str(bar_obj_list[0])
2133 Note again that because the Builder call returns a list,
2134 we have to access the first element in the list
2135 .B (bar_obj_list[0])
2136 to get at the Node that actually represents
2139 Builder calls support a
2141 keyword argument that
2142 specifies that the Builder's action(s)
2144 after changing directory.
2148 a string or a directory Node,
2149 scons will change to the specified directory.
2152 is not a string or Node
2154 then scons will change to the
2155 target file's directory.
2158 # scons will change to the "sub" subdirectory
2159 # before executing the "cp" command.
2160 env.Command('sub/dir/foo.out', 'sub/dir/foo.in',
2161 "cp dir/foo.in dir/foo.out",
2164 # Because chdir is not a string, scons will change to the
2165 # target's directory ("sub/dir") before executing the
2167 env.Command('sub/dir/foo.out', 'sub/dir/foo.in',
2168 "cp foo.in foo.out",
2172 Note that scons will
2174 automatically modify
2176 construction variables like
2180 when using the chdir
2181 keyword argument--that is,
2182 the expanded file names
2183 will still be relative to
2184 the top-level SConstruct directory,
2185 and consequently incorrect
2186 relative to the chdir directory.
2187 If you use the chdir keyword argument,
2188 you will typically need to supply a different
2194 to use just the filename portion of the
2198 provides the following builder methods:
2200 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2201 '\" BEGIN GENERATED BUILDER DESCRIPTIONS
2203 '\" The descriptions below of the various SCons Builders are generated
2204 '\" from the .xml files that live next to the various Python modules in
2205 '\" the build enginer library. If you're reading this [gnt]roff file
2206 '\" with an eye towards patching this man page, you can still submit
2207 '\" a diff against this text, but it will have to be translated to a
2208 '\" diff against the underlying .xml file before the patch is actually
2209 '\" accepted. If you do that yourself, it will make it easier to
2210 '\" integrate the patch.
2212 '\" BEGIN GENERATED BUILDER DESCRIPTIONS
2213 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2215 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2216 '\" END GENERATED BUILDER DESCRIPTIONS
2218 '\" The descriptions above of the various SCons Builders are generated
2219 '\" from the .xml files that live next to the various Python modules in
2220 '\" the build enginer library. If you're reading this [gnt]roff file
2221 '\" with an eye towards patching this man page, you can still submit
2222 '\" a diff against this text, but it will have to be translated to a
2223 '\" diff against the underlying .xml file before the patch is actually
2224 '\" accepted. If you do that yourself, it will make it easier to
2225 '\" integrate the patch.
2227 '\" END GENERATED BUILDER DESCRIPTIONS
2228 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2232 targets of builder methods automatically depend on their sources.
2233 An explicit dependency can
2234 be specified using the
2236 method of a construction environment (see below).
2241 source files for various programming languages,
2242 so the dependencies do not need to be specified explicitly.
2243 By default, SCons can
2246 Fortran source files with
2248 (POSIX systems only),
2253 and assembly language files with
2255 (POSIX systems only),
2260 for C preprocessor dependencies.
2261 SCons also has default support
2262 for scanning D source files,
2263 You can also write your own Scanners
2264 to add support for additional source file types.
2265 These can be added to the default
2266 Scanner object used by the
2268 .BR StaticObject (),
2271 Builders by adding them
2273 .B SourceFileScanner
2276 See the section "Scanner Objects,"
2277 below, for a more information about
2278 defining your own Scanner objects.
2280 .SS Methods and Functions to Do Things
2281 In addition to Builder methods,
2283 provides a number of other construction environment methods
2284 and global functions to
2285 manipulate the build configuration.
2287 Usually, a construction environment method
2288 and global function with the same name both exist
2289 so that you don't have to remember whether
2290 to a specific bit of functionality
2291 must be called with or without a construction environment.
2292 In the following list,
2293 if you call something as a global function
2296 .RI Function( arguments )
2298 and if you call something through a construction
2299 environment it looks like:
2301 .RI env.Function( arguments )
2303 If you can call the functionality in both ways,
2304 then both forms are listed.
2306 Global functions may be called from custom Python modules that you
2307 import into an SConscript file by adding the following
2308 to the Python module:
2311 from SCons.Script import *
2314 Except where otherwise noted,
2316 construction environment method
2318 provide the exact same functionality.
2319 The only difference is that,
2321 calling the functionality through a construction environment will
2322 substitute construction variables into
2323 any supplied strings.
2327 env = Environment(FOO = 'foo')
2332 In the above example,
2333 the first call to the global
2335 function will actually add a target named
2337 to the list of default targets,
2338 while the second call to the
2340 construction environment method
2341 will expand the value
2342 and add a target named
2344 to the list of default targets.
2345 For more on construction variable expansion,
2346 see the next section on
2347 construction variables.
2349 Construction environment methods
2350 and global functions supported by
2354 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2356 .RI Action( action ", [" cmd/str/fun ", [" var ", ...]] [" option = value ", ...])"
2358 .IR env .Action( action ", [" cmd/str/fun ", [" var ", ...]] [" option = value ", ...])"
2359 Creates an Action object for
2362 See the section "Action Objects,"
2363 below, for a complete explanation of the arguments and behavior.
2367 form of the invocation will expand
2368 construction variables in any argument strings,
2371 argument, at the time it is called
2372 using the construction variables in the
2374 construction environment through which
2379 form delays all variable expansion
2380 until the Action object is actually used.
2382 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2384 .RI AddMethod( object, function ", [" name ])
2386 .RI env.AddMethod( function ", [" name ])
2387 When called with the
2394 as the specified method
2396 When called with the
2397 .BR env.AddMethod ()
2401 to the construction environment
2403 as the specified method
2412 itself is used for the method name.
2417 # Note that the first argument to the function to
2418 # be attached as a method must be the object through
2419 # which the method will be called; the Python
2420 # convention is to call it 'self'.
2421 def my_method(self, arg):
2422 print "my_method() got", arg
2424 # Use the global AddMethod() function to add a method
2425 # to the Environment class. This
2426 AddMethod(Environment, my_method)
2428 env.my_method('arg')
2430 # Add the function as a method, using the function
2431 # name for the method call.
2433 env.AddMethod(my_method, 'other_method_name')
2434 env.other_method_name('another arg')
2437 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2439 .RI AddOption( arguments )
2440 This function adds a new command-line option to be recognized.
2443 are the same as supported by the standard Python
2444 .BR optparse.add_option ()
2445 method (with a few additional capabilities noted below);
2446 see the documentation for
2448 for a thorough discussion of its option-processing capabities.
2449 (Note that although the
2451 module was not a standard module until Python 2.3,
2453 contains a compatible version of the module
2454 that is used to provide identical functionality
2455 when run by earlier Python versions.)
2457 In addition to the arguments and values supported by the
2458 .B optparse.add_option ()
2462 function allows you to set the
2466 (a string with just the question mark)
2467 to indicate that the specified long option(s) take(s) an
2477 may be used to supply the "default"
2478 value that should be used when the
2479 option is specified on the command line
2480 without an explicit argument.
2484 keyword argument is supplied when calling
2486 the option will have a default value of
2489 Once a new command-line option has been added with
2491 the option value may be accessed using
2494 .BR env.GetOption ().
2495 \" NOTE: in SCons 1.x or 2.0, user options will be settable, but not yet.
2496 \" Uncomment this when that works. See tigris issue 2105.
2497 \" The value may also be set, using
2500 \" .BR env.SetOption (),
2501 \" if conditions in a
2503 \" require overriding any default value.
2504 \" Note, however, that a
2505 \" value specified on the command line will
2507 \" override a value set by any SConscript file.
2511 strings for the new option(s)
2512 will be displayed by the
2517 (the latter only if no other help text is
2518 specified in the SConscript files).
2519 The help text for the local options specified by
2521 will appear below the SCons options themselves,
2525 The options will appear in the help text
2526 in the order in which the
2533 AddOption('--prefix',
2535 nargs=1, type='string',
2538 help='installation prefix')
2539 env = Environment(PREFIX = GetOption('prefix'))
2542 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2544 .RI AddPostAction( target ", " action )
2546 .RI env.AddPostAction( target ", " action )
2547 Arranges for the specified
2553 The specified action(s) may be
2554 an Action object, or anything that
2555 can be converted into an Action object
2558 When multiple targets are supplied,
2559 the action may be called multiple times,
2560 once after each action that generates
2561 one or more targets in the list.
2563 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2565 .RI AddPreAction( target ", " action )
2567 .RI env.AddPreAction( target ", " action )
2568 Arranges for the specified
2571 before the specified
2574 The specified action(s) may be
2575 an Action object, or anything that
2576 can be converted into an Action object
2579 When multiple targets are specified,
2580 the action(s) may be called multiple times,
2581 once before each action that generates
2582 one or more targets in the list.
2584 Note that if any of the targets are built in multiple steps,
2585 the action will be invoked just
2586 before the "final" action that specifically
2587 generates the specified target(s).
2588 For example, when building an executable program
2589 from a specified source
2591 file via an intermediate object file:
2594 foo = Program('foo.c')
2595 AddPreAction(foo, 'pre_action')
2600 would be executed before
2602 calls the link command that actually
2603 generates the executable program binary
2605 not before compiling the
2607 file into an object file.
2609 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2611 .RI Alias( alias ", [" targets ", [" action ]])
2613 .RI env.Alias( alias ", [" targets ", [" action ]])
2614 Creates one or more phony targets that
2615 expand to one or more other targets.
2620 can be specified that will be executed
2621 whenever the any of the alias targets are out-of-date.
2622 Returns the Node object representing the alias,
2623 which exists outside of any file system.
2624 This Node object, or the alias name,
2625 may be used as a dependency of any other target,
2626 including another alias.
2628 can be called multiple times for the same
2629 alias to add additional targets to the alias,
2630 or additional actions to the list for this alias.
2636 Alias('install', '/usr/bin')
2637 Alias(['install', 'install-lib'], '/usr/local/lib')
2639 env.Alias('install', ['/usr/local/bin', '/usr/local/lib'])
2640 env.Alias('install', ['/usr/local/man'])
2642 env.Alias('update', ['file1', 'file2'], "update_database $SOURCES")
2645 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2647 .RI AllowSubstExceptions([ exception ", ...])"
2648 Specifies the exceptions that will be allowed
2649 when expanding construction variables.
2651 any construction variable expansions that generate a
2655 exception will expand to a
2657 (a null string) and not cause scons to fail.
2658 All exceptions not in the specified list
2659 will generate an error message
2660 and terminate processing.
2663 .B AllowSubstExceptions
2664 is called multiple times,
2665 each call completely overwrites the previous list
2666 of allowed exceptions.
2671 # Requires that all construction variable names exist.
2672 # (You may wish to do this if you want to enforce strictly
2673 # that all construction variables must be defined before use.)
2674 AllowSubstExceptions()
2676 # Also allow a string containing a zero-division expansion
2677 # like '${1 / 0}' to evalute to ''.
2678 AllowSubstExceptions(IndexError, NameError, ZeroDivisionError)
2681 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2683 .RI AlwaysBuild( target ", ...)"
2685 .RI env.AlwaysBuild( target ", ...)"
2688 so that it is always assumed to be out of date,
2689 and will always be rebuilt if needed.
2692 does not add its target(s) to the default target list,
2693 so the targets will only be built
2694 if they are specified on the command line,
2695 or are a dependent of a target specified on the command line--but
2698 be built if so specified.
2699 Multiple targets can be passed in to a single call to
2702 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2704 .RI env.Append( key = val ", [...])"
2705 Appends the specified keyword arguments
2706 to the end of construction variables in the environment.
2707 If the Environment does not have
2708 the specified construction variable,
2709 it is simply added to the environment.
2710 If the values of the construction variable
2711 and the keyword argument are the same type,
2712 then the two values will be simply added together.
2713 Otherwise, the construction variable
2714 and the value of the keyword argument
2715 are both coerced to lists,
2716 and the lists are added together.
2717 (See also the Prepend method, below.)
2722 env.Append(CCFLAGS = ' -g', FOO = ['foo.yyy'])
2725 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2727 .RI env.AppendENVPath( name ", " newpath ", [" envname ", " sep ", " delete_existing ])
2728 This appends new path elements to the given path in the
2729 specified external environment
2733 any particular path once (leaving the last one it encounters and
2734 ignoring the rest, to preserve path order),
2735 and to help assure this,
2736 will normalize all paths (using
2739 .BR os.path.normcase ).
2740 This can also handle the
2741 case where the given old path variable is a list instead of a
2742 string, in which case a list will be returned instead of a string.
2746 is 0, then adding a path that already exists
2747 will not move it to the end; it will stay where it is in the list.
2752 print 'before:',env['ENV']['INCLUDE']
2753 include_path = '/foo/bar:/foo'
2754 env.AppendENVPath('INCLUDE', include_path)
2755 print 'after:',env['ENV']['INCLUDE']
2759 after: /biz:/foo/bar:/foo
2762 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2764 .RI env.AppendUnique( key = val ", [...], delete_existing=0)"
2765 Appends the specified keyword arguments
2766 to the end of construction variables in the environment.
2767 If the Environment does not have
2768 the specified construction variable,
2769 it is simply added to the environment.
2770 If the construction variable being appended to is a list,
2771 then any value(s) that already exist in the
2772 construction variable will
2774 be added again to the list.
2775 However, if delete_existing is 1,
2776 existing matching values are removed first, so
2777 existing values in the arg list move to the end of the list.
2782 env.AppendUnique(CCFLAGS = '-g', FOO = ['foo.yyy'])
2785 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2788 A factory function that
2789 returns a Builder object
2790 to be used to fetch source files
2792 The returned Builder
2793 is intended to be passed to the
2800 env.SourceCode('.', env.BitKeeper())
2803 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2805 .RI BuildDir( build_dir ", " src_dir ", [" duplicate ])
2807 .RI env.BuildDir( build_dir ", " src_dir ", [" duplicate ])
2808 Deprecated synonyms for
2811 .BR env.VariantDir ().
2814 argument becomes the
2819 .BR env.VariantDir ().
2821 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2823 .RI Builder( action ", [" arguments ])
2825 .RI env.Builder( action ", [" arguments ])
2826 Creates a Builder object for
2829 See the section "Builder Objects,"
2830 below, for a complete explanation of the arguments and behavior.
2834 form of the invocation will expand
2835 construction variables in any arguments strings,
2839 at the time it is called
2840 using the construction variables in the
2842 construction environment through which
2847 form delays all variable expansion
2848 until after the Builder object is actually called.
2850 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2852 .RI CacheDir( cache_dir )
2854 .RI env.CacheDir( cache_dir )
2857 will maintain a cache of derived files in
2859 The derived files in the cache will be shared
2860 among all the builds using the same
2867 disables derived file caching.
2871 will only affect targets built
2872 through the specified construction environment.
2875 sets a global default
2876 that will be used by all targets built
2877 through construction environments
2888 finds a derived file that needs to be rebuilt,
2889 it will first look in the cache to see if a
2890 derived file has already been built
2891 from identical input files and an identical build action
2892 (as incorporated into the MD5 build signature).
2895 will retrieve the file from the cache.
2896 If the derived file is not present in the cache,
2899 then place a copy of the built file in the cache
2900 (identified by its MD5 build signature),
2901 so that it may be retrieved by other
2902 builds that need to build the same derived file
2903 from identical inputs.
2907 may be disabled for any invocation
2916 will place a copy of
2918 derived files in the cache,
2919 even if they already existed
2920 and were not built by this invocation.
2921 This is useful to populate a cache
2924 is added to a build,
2933 "Retrieved `file' from cache,"
2936 option is being used.
2941 will print the action that
2943 have been used to build the file,
2944 without any indication that
2945 the file was actually retrieved from the cache.
2946 This is useful to generate build logs
2947 that are equivalent regardless of whether
2948 a given derived file has been built in-place
2949 or retrieved from the cache.
2953 method can be used to disable caching of specific files. This can be
2954 useful if inputs and/or outputs of some tool are impossible to
2955 predict or prohibitively large.
2957 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2959 .RI Clean( targets ", " files_or_dirs )
2961 .RI env.Clean( targets ", " files_or_dirs )
2962 This specifies a list of files or directories which should be removed
2963 whenever the targets are specified with the
2965 command line option.
2966 The specified targets may be a list
2967 or an individual target.
2971 and create new targets or add files and directories to the
2972 clean list for the specified targets.
2974 Multiple files or directories should be specified
2975 either as separate arguments to the
2977 method, or as a list.
2979 will also accept the return value of any of the construction environment
2985 function overrides calling
2987 for the same target,
2988 and any targets passed to both functions will
2997 Clean('foo', ['bar', 'baz'])
2998 Clean('dist', env.Program('hello', 'hello.c'))
2999 Clean(['foo', 'bar'], 'something_else_to_clean')
3003 installing the project creates a subdirectory for the documentation.
3004 This statement causes the subdirectory to be removed
3005 if the project is deinstalled.
3007 Clean(docdir, os.path.join(docdir, projectname))
3010 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3012 .RI Command( target ", " source ", " action ", [" key = val ", ...])"
3014 .RI env.Command( target ", " source ", " action ", [" key = val ", ...])"
3015 Executes a specific action
3016 (or list of actions)
3017 to build a target file or files.
3018 This is more convenient
3019 than defining a separate Builder object
3020 for a single special-case build.
3022 As a special case, the
3024 keyword argument can
3027 that will be used to scan the sources.
3031 if any of the sources will be directories
3032 that must be scanned on-disk for
3033 changes to files that aren't
3034 already specified in other Builder of function calls.)
3036 Any other keyword arguments specified override any
3037 same-named existing construction variables.
3039 An action can be an external command,
3040 specified as a string,
3041 or a callable Python object;
3042 see "Action Objects," below,
3043 for more complete information.
3044 Also note that a string specifying an external command
3045 may be preceded by an
3048 to suppress printing the command in question,
3052 to ignore the exit status of the external command.
3057 env.Command('foo.out', 'foo.in',
3058 "$FOO_BUILD < $SOURCES > $TARGET")
3060 env.Command('bar.out', 'bar.in',
3062 "$BAR_BUILD < $SOURCES > $TARGET"],
3063 ENV = {'PATH' : '/usr/local/bin/'})
3065 def rename(env, target, source):
3067 os.rename('.tmp', str(target[0]))
3069 env.Command('baz.out', 'baz.in',
3070 ["$BAZ_BUILD < $SOURCES > .tmp",
3077 function will usually assume, by default,
3078 that the specified targets and/or sources are Files,
3079 if no other part of the configuration
3080 identifies what type of entry it is.
3081 If necessary, you can explicitly specify
3082 that targets or source nodes should
3083 be treated as directoriese
3093 env.Command('ddd.list', Dir('ddd'), 'ls -l $SOURCE > $TARGET')
3095 env['DISTDIR'] = 'destination/directory'
3096 env.Command(env.Dir('$DISTDIR')), None, make_distdir)
3100 (Also note that SCons will usually
3101 automatically create any directory necessary to hold a target file,
3102 so you normally don't need to create directories by hand.)
3104 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3106 .RI Configure( env ", [" custom_tests ", " conf_dir ", " log_file ", " config_h ])
3108 .RI env.Configure([ custom_tests ", " conf_dir ", " log_file ", " config_h ])
3109 Creates a Configure object for integrated
3110 functionality similar to GNU autoconf.
3111 See the section "Configure Contexts,"
3112 below, for a complete explanation of the arguments and behavior.
3114 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3116 .RI env.Clone([ key = val ", ...])"
3117 Return a separate copy of a construction environment.
3118 If there are any keyword arguments specified,
3119 they are added to the returned copy,
3120 overwriting any existing values
3127 env3 = env.Clone(CCFLAGS = '-g')
3130 Additionally, a list of tools and a toolpath may be specified, as in
3131 the Environment constructor:
3134 def MyTool(env): env['FOO'] = 'bar'
3135 env4 = env.Clone(tools = ['msvc', MyTool])
3140 keyword argument is also recognized:
3143 # create an environment for compiling programs that use wxWidgets
3144 wx_env = env.Clone(parse_flags = '!wx-config --cflags --cxxflags')
3147 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3149 .RI env.Copy([ key = val ", ...])"
3150 A now-deprecated synonym for
3153 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3155 .RI env.CVS( repository ", " module )
3156 A factory function that
3157 returns a Builder object
3158 to be used to fetch source files
3162 The returned Builder
3163 is intended to be passed to the
3167 The optional specified
3169 will be added to the beginning
3170 of all repository path names;
3171 this can be used, in essence,
3172 to strip initial directory names
3173 from the repository path names,
3174 so that you only have to
3175 replicate part of the repository
3176 directory hierarchy in your
3177 local build directory.
3182 # Will fetch foo/bar/src.c
3183 # from /usr/local/CVSROOT/foo/bar/src.c.
3184 env.SourceCode('.', env.CVS('/usr/local/CVSROOT'))
3186 # Will fetch bar/src.c
3187 # from /usr/local/CVSROOT/foo/bar/src.c.
3188 env.SourceCode('.', env.CVS('/usr/local/CVSROOT', 'foo'))
3191 # from /usr/local/CVSROOT/foo/bar/src.c.
3192 env.SourceCode('.', env.CVS('/usr/local/CVSROOT', 'foo/bar'))
3195 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3197 .RI Decider( function )
3199 .RI env.Decider( function )
3200 Specifies that all up-to-date decisions for
3201 targets built through this construction environment
3202 will be handled by the specified
3206 can be one of the following strings
3207 that specify the type of decision function
3213 Specifies that a target shall be considered out of date and rebuilt
3214 if the dependency's timestamp is newer than the target file's timestamp.
3215 This is the behavior of the classic Make utility,
3218 can be used a synonym for
3219 .BR timestamp-newer .
3223 Specifies that a target shall be considered out of date and rebuilt
3224 if the dependency's timestamp is different than the
3225 timestamp recorded the last time the target was built.
3226 This provides behavior very similar to the classic Make utility
3227 (in particular, files are not opened up so that their
3228 contents can be checksummed)
3229 except that the target will also be rebuilt if a
3230 dependency file has been restored to a version with an
3232 timestamp, such as can happen when restoring files from backup archives.
3236 Specifies that a target shall be considered out of date and rebuilt
3237 if the dependency's content has changed sine the last time
3238 the target was built,
3239 as determined be performing an MD5 checksum
3240 on the dependency's contents
3241 and comparing it to the checksum recorded the
3242 last time the target was built.
3244 can be used as a synonym for
3249 Specifies that a target shall be considered out of date and rebuilt
3250 if the dependency's content has changed sine the last time
3251 the target was built,
3252 except that dependencies with a timestamp that matches
3253 the last time the target was rebuilt will be
3254 assumed to be up-to-date and
3257 This provides behavior very similar
3260 behavior of always checksumming file contents,
3261 with an optimization of not checking
3262 the contents of files whose timestamps haven't changed.
3263 The drawback is that SCons will
3265 detect if a file's content has changed
3266 but its timestamp is the same,
3267 as might happen in an automated script
3270 and runs the build again,
3271 all within a single second.
3278 # Use exact timestamp matches by default.
3279 Decider('timestamp-match')
3281 # Use MD5 content signatures for any targets built
3282 # with the attached construction environment.
3283 env.Decider('content')
3287 In addition to the above already-available functions,
3290 argument may be an actual Python function
3291 that takes the following three arguments:
3295 The Node (file) which
3299 if it has "changed" since the last tme
3300 .I target was built.
3303 The Node (file) being built.
3305 this is what should get rebuilt
3311 Stored information about the state of the
3316 This can be consulted to match various
3317 file characteristics
3318 such as the timestamp,
3319 size, or content signature.
3330 has "changed" since the last time
3334 (indicating that the target
3341 (indicating that the target should
3344 Note that the decision can be made
3345 using whatever criteria are appopriate.
3346 Ignoring some or all of the function arguments
3347 is perfectly normal.
3352 def my_decider(dependency, target, prev_ni):
3353 return not os.path.exists(str(target))
3355 env.Decider(my_decider)
3358 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3360 .RI Default( targets )
3362 .RI env.Default( targets )
3363 This specifies a list of default targets,
3364 which will be built by
3366 if no explicit targets are given on the command line.
3370 and add to the list of default targets.
3372 Multiple targets should be specified as
3373 separate arguments to the
3375 method, or as a list.
3377 will also accept the Node returned by any
3378 of a construction environment's
3384 Default('foo', 'bar', 'baz')
3385 env.Default(['a', 'b', 'c'])
3386 hello = env.Program('hello', 'hello.c')
3394 will clear all default targets.
3397 will add to the (now empty) default-target list
3400 The current list of targets added using the
3402 function or method is available in the
3407 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3409 .RI DefaultEnvironment([ args ])
3410 Creates and returns a default construction environment object.
3411 This construction environment is used internally by SCons
3412 in order to execute many of the global functions in this list,
3413 and to fetch source files transparently
3414 from source code management systems.
3416 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3418 .RI Depends( target ", " dependency )
3420 .RI env.Depends( target ", " dependency )
3421 Specifies an explicit dependency;
3433 (usually the path name of a file or directory)
3435 or a list of strings or Node objects
3436 (such as returned by a Builder call).
3437 This should only be necessary
3438 for cases where the dependency
3439 is not caught by a Scanner
3445 env.Depends('foo', 'other-input-file-for-foo')
3447 mylib = env.Library('mylib.c')
3448 installed_lib = env.Install('lib', mylib)
3449 bar = env.Program('bar.c')
3451 # Arrange for the library to be copied into the installation
3452 # directory before trying to build the "bar" program.
3453 # (Note that this is for example only. A "real" library
3454 # dependency would normally be configured through the $LIBS
3455 # and $LIBPATH variables, not using an env.Depends() call.)
3457 env.Depends(bar, installed_lib)
3460 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3462 .RI env.Dictionary([ vars ])
3463 Returns a dictionary object
3464 containing copies of all of the
3465 construction variables in the environment.
3466 If there are any variable names specified,
3467 only the specified construction
3468 variables are returned in the dictionary.
3473 dict = env.Dictionary()
3474 cc_dict = env.Dictionary('CC', 'CCFLAGS', 'CCCOM')
3477 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3479 .RI Dir( name ", [" directory ])
3481 .RI env.Dir( name ", [" directory ])
3482 This returns a Directory Node,
3483 an object that represents the specified directory
3486 can be a relative or absolute path.
3488 is an optional directory that will be used as the parent directory.
3491 is specified, the current script's directory is used as the parent.
3495 is a list, SCons returns a list of Dir nodes.
3496 Construction variables are expanded in
3499 Directory Nodes can be used anywhere you
3500 would supply a string as a directory name
3501 to a Builder method or function.
3502 Directory Nodes have attributes and methods
3503 that are useful in many situations;
3504 see "File and Directory Nodes," below.
3506 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3508 .RI env.Dump([ key ])
3509 Returns a pretty printable representation of the environment.
3513 should be a string containing the name of the variable of interest.
3518 print env.Dump('CCCOM')
3523 \&'$CC -c -o $TARGET $CCFLAGS $CPPFLAGS $_CPPDEFFLAGS $_CPPINCFLAGS $SOURCES'
3534 'ARCOM': '$AR $ARFLAGS $TARGET $SOURCES\n$RANLIB $RANLIBFLAGS $TARGET',
3537 'ASCOM': '$AS $ASFLAGS -o $TARGET $SOURCES',
3542 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3544 .RI EnsurePythonVersion( major ", " minor )
3546 .RI env.EnsurePythonVersion( major ", " minor )
3547 Ensure that the Python version is at least
3550 print out an error message and exit SCons with a non-zero exit code if the
3551 actual Python version is not late enough.
3556 EnsurePythonVersion(2,2)
3559 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3561 .RI EnsureSConsVersion( major ", " minor ", [" revision ])
3563 .RI env.EnsureSConsVersion( major ", " minor ", [" revision ])
3564 Ensure that the SCons version is at least
3567 .IR major.minor.revision .
3572 print out an error message and exit SCons with a non-zero exit code if the
3573 actual SCons version is not late enough.
3578 EnsureSConsVersion(0,14)
3580 EnsureSConsVersion(0,96,90)
3583 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3585 .RI Environment([ key = value ", ...])"
3587 .RI env.Environment([ key = value ", ...])"
3588 Return a new construction environment
3589 initialized with the specified
3593 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3595 .RI Execute( action ", [" strfunction ", " varlist ])
3597 .RI env.Execute( action ", [" strfunction ", " varlist ])
3598 Executes an Action object.
3601 may be an Action object
3602 (see the section "Action Objects,"
3603 below, for a complete explanation of the arguments and behavior),
3604 or it may be a command-line string,
3606 or executable Python function,
3607 each of which will be converted
3608 into an Action object
3610 The exit value of the command
3611 or return value of the Python function
3616 will print an error message if the executed
3619 exits with or returns a non-zero value.
3624 automatically terminate the build
3628 If you want the build to stop in response to a failed
3631 you must explicitly check for a non-zero return value:
3634 Execute(Copy('file.out', 'file.in'))
3636 if Execute("mkdir sub/dir/ectory"):
3637 # The mkdir failed, don't try to build.
3641 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3645 .RI env.Exit([ value ])
3651 A default exit value of
3654 is used if no value is specified.
3656 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3660 .RI env.Export( vars )
3663 to export a list of variables from the current
3664 SConscript file to all other SConscript files.
3665 The exported variables are kept in a global collection,
3666 so subsequent calls to
3668 will over-write previous exports that have the same name.
3669 Multiple variable names can be passed to
3671 as separate arguments or as a list.
3672 Keyword arguments can be used to provide names and their values.
3673 A dictionary can be used to map variables to a different name when exported.
3674 Both local variables and global variables can be exported.
3680 # Make env available for all SConscript files to Import().
3684 # Make env and package available for all SConscript files:.
3685 Export("env", "package")
3687 # Make env and package available for all SConscript files:
3688 Export(["env", "package"])
3690 # Make env available using the name debug:
3693 # Make env available using the name debug:
3694 Export({"debug":env})
3700 function supports an
3702 argument that makes it easier to to export a variable or
3703 set of variables to a single SConscript file.
3704 See the description of the
3708 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3710 .RI File( name ", [" directory ])
3712 .RI env.File( name ", [" directory ])
3715 an object that represents the specified file
3718 can be a relative or absolute path.
3720 is an optional directory that will be used as the parent directory.
3724 is a list, SCons returns a list of File nodes.
3725 Construction variables are expanded in
3728 File Nodes can be used anywhere you
3729 would supply a string as a file name
3730 to a Builder method or function.
3731 File Nodes have attributes and methods
3732 that are useful in many situations;
3733 see "File and Directory Nodes," below.
3735 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3737 .RI FindFile( file ", " dirs )
3739 .RI env.FindFile( file ", " dirs )
3742 in the path specified by
3745 may be a list of directory names or a single directory name.
3746 In addition to searching for files that exist in the filesytem,
3747 this function also searches for derived files
3748 that have not yet been built.
3753 foo = env.FindFile('foo', ['dir1', 'dir2'])
3756 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3758 .RI FindInstalledFiles( )
3760 .RI env.FindInstalledFiles( )
3761 Returns the list of targets set up by the
3767 This function serves as a convenient method to select the contents of
3773 Install( '/bin', [ 'executable_a', 'executable_b' ] )
3775 # will return the file node list
3776 # [ '/bin/executable_a', '/bin/executable_b' ]
3777 FindInstalledFiles()
3779 Install( '/lib', [ 'some_library' ] )
3781 # will return the file node list
3782 # [ '/bin/executable_a', '/bin/executable_b', '/lib/some_library' ]
3783 FindInstalledFiles()
3786 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3788 .RI FindSourceFiles( node = '"."' )
3790 .RI env.FindSourceFiles( node = '"."' )
3792 Returns the list of nodes which serve as the source of the built files.
3793 It does so by inspecting the dependency tree starting at the optional
3796 which defaults to the '"."'-node. It will then return all leaves of
3798 These are all children which have no further children.
3800 This function is a convenient method to select the contents of a Source
3806 Program( 'src/main_a.c' )
3807 Program( 'src/main_b.c' )
3808 Program( 'main_c.c' )
3810 # returns ['main_c.c', 'src/main_a.c', 'SConstruct', 'src/main_b.c']
3813 # returns ['src/main_b.c', 'src/main_a.c' ]
3814 FindSourceFiles( 'src' )
3818 As you can see build support files (SConstruct in the above example)
3819 will also be returned by this function.
3821 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3823 .RI FindPathDirs( variable )
3825 (actually a callable Python object)
3826 intended to be used as the
3828 of a Scanner object.
3829 The returned object will look up the specified
3831 in a construction environment
3832 and treat the construction variable's value as a list of
3833 directory paths that should be searched
3841 is generally preferable to
3844 for the following reasons:
3845 1) The returned list will contain all appropriate directories
3846 found in source trees
3850 or in code repositories
3856 2) scons will identify expansions of
3858 that evaluate to the same list of directories as,
3859 in fact, the same list,
3860 and avoid re-scanning the directories for files,
3866 def my_scan(node, env, path, arg):
3867 # Code to scan file contents goes here...
3868 return include_files
3870 scanner = Scanner(name = 'myscanner',
3872 path_function = FindPathDirs('MYPATH'))
3875 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3877 .RI Flatten( sequence )
3879 .RI env.Flatten( sequence )
3880 Takes a sequence (that is, a Python list or tuple)
3881 that may contain nested sequences
3882 and returns a flattened list containing
3883 all of the individual elements in any sequence.
3884 This can be helpful for collecting
3885 the lists returned by calls to Builders;
3886 other Builders will automatically
3887 flatten lists specified as input,
3888 but direct Python manipulation of
3889 these lists does not.
3894 foo = Object('foo.c')
3895 bar = Object('bar.c')
3897 # Because `foo' and `bar' are lists returned by the Object() Builder,
3898 # `objects' will be a list containing nested lists:
3899 objects = ['f1.o', foo, 'f2.o', bar, 'f3.o']
3901 # Passing such a list to another Builder is all right because
3902 # the Builder will flatten the list automatically:
3903 Program(source = objects)
3905 # If you need to manipulate the list directly using Python, you need to
3906 # call Flatten() yourself, or otherwise handle nested lists:
3907 for object in Flatten(objects):
3911 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3913 .RI GetBuildFailures()
3914 Returns a list of exceptions for the
3915 actions that failed while
3916 attempting to build targets.
3917 Each element in the returned list is a
3920 with the following attributes
3921 that record various aspects
3922 of the build failure:
3925 The node that was being built
3926 when the build failure occurred.
3929 The numeric exit status
3930 returned by the command or Python function
3931 that failed when trying to build the
3935 The SCons error string
3936 describing the build failure.
3937 (This is often a generic
3938 message like "Error 2"
3939 to indicate that an executed
3940 command exited with a status of 2.)
3943 The name of the file or
3944 directory that actually caused the failure.
3945 This may be different from the
3949 if an attempt to build a target named
3953 directory could not be created,
3964 The SCons Executor object
3967 This can be used to retrieve
3968 the construction environment used
3969 for the failed action.
3972 The actual SCons Action object that failed.
3973 This will be one specific action
3974 out of the possible list of
3975 actions that would have been
3976 executed to build the target.
3979 The actual expanded command that was executed and failed,
3983 and other construction variables.
3986 .BR GetBuildFailures ()
3988 will always return an empty list
3989 until any build failure has occurred,
3991 .BR GetBuildFailures ()
3992 will always return an empty list
3995 files are being read.
3996 Its primary intended use is
3997 for functions that will be
3998 executed before SCons exits
3999 by passing them to the
4001 .BR atexit.register ()
4008 def print_build_failures():
4009 from SCons.Script import GetBuildFailures
4010 for bf in GetBuildFailures():
4011 print "%s failed: %s" % (bf.node, bf.errstr)
4013 atexit.register(print_build_failures)
4016 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4018 .RI GetBuildPath( file ", [" ... ])
4020 .RI env.GetBuildPath( file ", [" ... ])
4023 path name (or names) for the specified
4031 Nodes or strings representing path names.
4033 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4037 .RI env.GetLaunchDir()
4038 Returns the absolute path name of the directory from which
4040 was initially invoked.
4041 This can be useful when using the
4046 options, which internally
4047 change to the directory in which the
4051 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4053 .RI GetOption( name )
4055 .RI env.GetOption( name )
4056 This function provides a way to query the value of
4057 SCons options set on scons command line
4061 The options supported are:
4066 which corresponds to --cache-debug;
4069 which corresponds to --cache-disable;
4072 which corresponds to --cache-force;
4075 which corresponds to --cache-show;
4078 which corresponds to -c, --clean and --remove;
4081 which corresponds to --config;
4084 which corresponds to -C and --directory;
4087 which corresponds to --diskcheck
4090 which corresponds to --duplicate;
4093 which corresponds to -f, --file, --makefile and --sconstruct;
4096 which corresponds to -h and --help;
4099 which corresponds to --ignore-errors;
4102 which corresponds to --implicit-cache;
4104 .B implicit_deps_changed
4105 which corresponds to --implicit-deps-changed;
4107 .B implicit_deps_unchanged
4108 which corresponds to --implicit-deps-unchanged;
4111 which corresponds to --interact and --interactive;
4114 which corresponds to -k and --keep-going;
4117 which corresponds to --max-drift;
4120 which corresponds to -n, --no-exec, --just-print, --dry-run and --recon;
4123 which corresponds to --no-site-dir;
4126 which corresponds to -j and --jobs;
4129 which corresponds to --profile;
4132 which corresponds to -q and --question;
4135 which corresponds to --random;
4138 which corresponds to -Y, --repository and --srcdir;
4141 which corresponds to -s, --silent and --quiet;
4144 which corresponds to --site-dir;
4147 which corresponds to --stack-size;
4149 .B taskmastertrace_file
4150 which corresponds to --taskmastertrace; and
4153 which corresponds to --warn and --warning.
4157 See the documentation for the
4158 corresponding command line object for information about each specific
4161 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4163 .RI Glob( pattern ", [" ondisk ", " source ", " strings ])
4165 .RI env.Glob( pattern ", [" ondisk ", " source ", " strings ])
4166 Returns Nodes (or strings) that match the specified
4168 relative to the directory of the current
4173 form performs string substition on
4175 and returns whatever matches
4176 the resulting expanded pattern.
4180 uses Unix shell style metacharacters for matching:
4183 * matches everything
4184 ? matches any single character
4185 [seq] matches any character in seq
4186 [!seq] matches any char not in seq
4190 If the first character of a filename is a dot,
4191 it must be matched explicitly.
4192 Character matches do
4194 span directory separators.
4203 and source directories
4208 returns a Node (or string, if so configured)
4209 in the local (SConscript) directory
4210 if matching Node is found
4211 anywhere in a corresponding
4212 repository or source directory.
4216 argument may be set to
4218 (or any other non-true value)
4219 to disable the search for matches on disk,
4220 thereby only returning matches among
4221 already-configured File or Dir Nodes.
4222 The default behavior is to
4223 return corresponding Nodes
4224 for any on-disk matches found.
4228 argument may be set to
4230 (or any equivalent value)
4232 when the local directory is a
4234 the returned Nodes should be from the
4235 corresponding source directory,
4236 not the local directory.
4240 argument may be set to
4242 (or any equivalent value)
4245 function return strings, not Nodes,
4246 that represent the matched files or directories.
4247 The returned strings will be relative to
4248 the local (SConscript) directory.
4249 (Note that This may make it easier to perform
4250 arbitrary manipulation of file names,
4251 but if the returned strings are
4252 passed to a different
4255 any Node translation will be relative
4266 Program('foo', Glob('*.c'))
4267 Zip('/tmp/everything', Glob('.??*') + Glob('*'))
4270 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4272 '\".RI GlobalBuilders( flag )
4276 '\"adds the names of the default builders
4277 '\"(Program, Library, etc.)
4278 '\"to the global name space
4279 '\"so they can be called without an explicit construction environment.
4280 '\"(This is the default.)
4284 '\"the names of the default builders are removed
4285 '\"from the global name space
4286 '\"so that an explicit construction environment is required
4287 '\"to call all builders.
4289 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4293 .RI env.Help( text )
4294 This specifies help text to be printed if the
4296 argument is given to
4300 is called multiple times, the text is appended together in the order
4305 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4307 .RI Ignore( target ", " dependency )
4309 .RI env.Ignore( target ", " dependency )
4310 The specified dependency file(s)
4311 will be ignored when deciding if
4312 the target file(s) need to be rebuilt.
4316 to remove a target from the default build.
4317 In order to do this you must specify the directory the target will
4318 be built in as the target, and the file you want to skip building
4321 Note that this will only remove the dependencies listed from
4322 the files built by default. It will still be built if that
4323 dependency is needed by another object being built.
4324 See the third and forth examples below.
4329 env.Ignore('foo', 'foo.c')
4330 env.Ignore('bar', ['bar1.h', 'bar2.h'])
4331 env.Ignore('.','foobar.obj')
4332 env.Ignore('bar','bar/foobar.obj')
4335 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4339 .RI env.Import( vars )
4342 to import a list of variables into the current SConscript file. This
4343 will import variables that were exported with
4349 Variables exported by
4352 Multiple variable names can be passed to
4354 as separate arguments or as a list. The variable "*" can be used
4355 to import all variables.
4361 Import("env", "variable")
4362 Import(["env", "variable"])
4366 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4368 .RI Literal( string )
4370 .RI env.Literal( string )
4373 will be preserved as-is
4374 and not have construction variables expanded.
4376 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4378 .RI Local( targets )
4380 .RI env.Local( targets )
4383 will have copies made in the local tree,
4384 even if an already up-to-date copy
4385 exists in a repository.
4386 Returns a list of the target Node or Nodes.
4388 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4390 \" .RI env.MergeShellPaths( arg ", [" prepend ])
4391 \" Merges the elements of the specified
4393 \" which must be a dictionary, to the construction
4394 \" environment's copy of the shell environment
4396 \" (This is the environment which is passed
4397 \" to subshells spawned by SCons.)
4400 \" must be a single value,
4401 \" so multiple strings must
4402 \" be passed in as a list,
4403 \" not as separate arguments to
4404 \" .BR env.MergeShellPaths ().
4406 \" New values are prepended to the environment variable by default,
4407 \" unless prepend=0 is specified.
4408 \" Duplicate values are always eliminated,
4409 \" since this function calls
4412 \" .B PrependENVPath
4415 \" argument. See those functions for more details.
4420 \" # Prepend a path to the shell PATH.
4421 \" env.MergeShellPaths({'PATH':'/usr/local/bin'} )
4422 \" # Append two dirs to the shell INCLUDE.
4423 \" env.MergeShellPaths({'INCLUDE':['c:/inc1', 'c:/inc2']}, prepend=0 )
4427 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4429 .RI env.MergeFlags( arg ", [" unique ])
4430 Merges the specified
4432 values to the construction environment's construction variables.
4435 argument is not a dictionary,
4436 it is converted to one by calling
4439 before the values are merged.
4442 must be a single value,
4443 so multiple strings must
4444 be passed in as a list,
4445 not as separate arguments to
4446 .BR env.MergeFlags ().
4449 duplicate values are eliminated;
4450 you can, however, specify
4454 When eliminating duplicate values,
4455 any construction variables that end with
4458 keep the left-most unique value.
4459 All other construction variables keep
4460 the right-most unique value.
4465 # Add an optimization flag to $CCFLAGS.
4466 env.MergeFlags('-O3')
4468 # Combine the flags returned from running pkg-config with an optimization
4469 # flag and merge the result into the construction variables.
4470 env.MergeFlags(['!pkg-config gtk+-2.0 --cflags', '-O3'])
4472 # Combine an optimization flag with the flags returned from running pkg-config
4473 # twice and merge the result into the construction variables.
4474 env.MergeFlags(['-O3',
4475 '!pkg-config gtk+-2.0 --cflags --libs',
4476 '!pkg-config libpng12 --cflags --libs'])
4479 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4481 .RI NoCache( target ", ...)"
4483 .RI env.NoCache( target ", ...)"
4484 Specifies a list of files which should
4486 be cached whenever the
4488 method has been activated.
4489 The specified targets may be a list
4490 or an individual target.
4492 Multiple files should be specified
4493 either as separate arguments to the
4495 method, or as a list.
4497 will also accept the return value of any of the construction environment
4502 on directories and other non-File Node types has no effect because
4503 only File Nodes are cached.
4509 NoCache(env.Program('hello', 'hello.c'))
4512 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4514 .RI NoClean( target ", ...)"
4516 .RI env.NoClean( target ", ...)"
4517 Specifies a list of files or directories which should
4519 be removed whenever the targets (or their dependencies)
4520 are specified with the
4522 command line option.
4523 The specified targets may be a list
4524 or an individual target.
4528 and prevent each specified target
4529 from being removed by calls to the
4533 Multiple files or directories should be specified
4534 either as separate arguments to the
4536 method, or as a list.
4538 will also accept the return value of any of the construction environment
4543 for a target overrides calling
4545 for the same target,
4546 and any targets passed to both functions will
4556 NoClean(env.Program('hello', 'hello.c'))
4559 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4561 .RI env.ParseConfig( command ", [" function ", " unique ])
4564 to modify the environment as specified by the output of
4569 .BR env.MergeFlags (),
4570 which expects the output of a typical
4574 and adds the options
4575 to the appropriate construction variables.
4577 duplicate values are not
4578 added to any construction variables;
4585 and the construction variables they affect
4586 are as specified for the
4587 .BR env.ParseFlags ()
4588 method (which this method calls).
4589 See that method's description, below,
4590 for a table of options and construction variables.
4592 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4594 .RI ParseDepends( filename ", [" must_exist ", " only_one ])
4596 .RI env.ParseDepends( filename ", [" must_exist ", " only_one ])
4597 Parses the contents of the specified
4599 as a list of dependencies in the style of
4603 and explicitly establishes all of the listed dependencies.
4612 argument may be set to a non-zero
4615 throw an exception and
4616 generate an error if the file does not exist,
4617 or is otherwise inaccessible.
4621 argument may be set to a non-zero
4624 thrown an exception and
4626 if the file contains dependency
4627 information for more than one target.
4628 This can provide a small sanity check
4629 for files intended to be generated
4630 by, for example, the
4633 which should typically only
4634 write dependency information for
4635 one output file into a corresponding
4641 and all of the files listed therein
4642 will be interpreted relative to
4643 the directory of the
4645 file which calls the
4649 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4651 .RI env.ParseFlags( flags ", ...)"
4652 Parses one or more strings containing
4653 typical command-line flags for GCC tool chains
4654 and returns a dictionary with the flag values
4655 separated into the appropriate SCons construction variables.
4656 This is intended as a companion to the
4657 .BR env.MergeFlags ()
4658 method, but allows for the values in the returned dictionary
4659 to be modified, if necessary,
4660 before merging them into the construction environment.
4662 .BR env.MergeFlags ()
4663 will call this method if its argument is not a dictionary,
4664 so it is usually not necessary to call
4665 .BR env.ParseFlags ()
4666 directly unless you want to manipulate the values.)
4668 If the first character in any string is
4669 an exclamation mark (!),
4670 the rest of the string is executed as a command,
4671 and the output from the command is
4672 parsed as GCC tool chain command-line flags
4673 and added to the resulting dictionary.
4675 Flag values are translated accordig to the prefix found,
4676 and added to the following construction variables:
4679 -arch CCFLAGS, LINKFLAGS
4681 -framework FRAMEWORKS
4682 -frameworkdir= FRAMEWORKPATH
4684 -isysroot CCFLAGS, LINKFLAGS
4688 -mno-cygwin CCFLAGS, LINKFLAGS
4690 -pthread CCFLAGS, LINKFLAGS
4692 -Wa, ASFLAGS, CCFLAGS
4699 + CCFLAGS, LINKFLAGS
4703 Any other strings not associated with options
4704 are assumed to be the names of libraries
4707 construction variable.
4709 Examples (all of which produce the same result):
4712 dict = env.ParseFlags('-O2 -Dfoo -Dbar=1')
4713 dict = env.ParseFlags('-O2', '-Dfoo', '-Dbar=1')
4714 dict = env.ParseFlags(['-O2', '-Dfoo -Dbar=1'])
4715 dict = env.ParseFlags('-O2', '!echo -Dfoo -Dbar=1')
4718 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4721 A factory function that
4722 returns a Builder object
4723 to be used to fetch source files
4724 from the Perforce source code management system.
4725 The returned Builder
4726 is intended to be passed to the
4733 env.SourceCode('.', env.Perforce())
4736 Perforce uses a number of external
4737 environment variables for its operation.
4738 Consequently, this function adds the
4739 following variables from the user's external environment
4740 to the construction environment's
4753 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4755 .RI Platform( string )
4756 Returns a callable object
4757 that can be used to initialize
4758 a construction environment using the
4759 platform keyword of the Environment() method.
4764 env = Environment(platform = Platform('win32'))
4767 .RI env.Platform( string )
4768 Applies the callable object for the specified platform
4770 to the environment through which the method was called.
4773 env.Platform('posix')
4782 variables from the user's external environment
4783 to the construction environment's
4786 This is so that any executed commands
4787 that use sockets to connect with other systems
4788 (such as fetching source files from
4789 external CVS repository specifications like
4790 .BR :pserver:anonymous@cvs.sourceforge.net:/cvsroot/scons )
4791 will work on Windows systems.
4793 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4795 .RI Progress( callable ", [" interval ])
4797 .RI Progress( string ", [" interval ", " file ", " overwrite ])
4799 .RI Progress( list_of_strings ", [" interval ", " file ", " overwrite ])
4800 Allows SCons to show progress made during the build
4801 by displaying a string or calling a function while
4802 evaluating Nodes (e.g. files).
4804 If the first specified argument is a Python callable
4805 (a function or an object that has a
4808 the function will be called
4811 times a Node is evaluated.
4812 The callable will be passed the evaluated Node
4813 as its only argument.
4814 (For future compatibility,
4815 it's a good idea to also add
4819 as arguments to your function or method.
4820 This will prevent the code from breaking
4821 if SCons ever changes the interface
4822 to call the function with additional arguments in the future.)
4824 An example of a simple custom progress function
4825 that prints a string containing the Node name
4829 def my_progress_function(node, *args, **kw):
4830 print 'Evaluating node %s!' % node
4831 Progress(my_progress_function, interval=10)
4834 A more complicated example of a custom progress display object
4835 that prints a string containing a count
4836 every 100 evaluated Nodes.
4840 at the end so that the string
4841 will overwrite itself on a display:
4845 class ProgressCounter:
4847 def __call__(self, node, *args, **kw):
4849 sys.stderr.write('Evaluated %s nodes\\r' % self.count)
4850 Progress(ProgressCounter(), interval=100)
4853 If the first argument
4856 the string will be displayed
4860 The default is to print the string on standard output;
4861 an alternate output stream
4862 may be specified with the
4865 The following will print a series of dots
4866 on the error output,
4867 one dot for every 100 evaluated Nodes:
4871 Progress('.', interval=100, file=sys.stderr)
4874 If the string contains the verbatim substring
4876 it will be replaced with the Node.
4877 Note that, for performance reasons, this is
4879 a regular SCons variable substition,
4880 so you can not use other variables
4881 or use curly braces.
4882 The following example will print the name of
4883 every evaluated Node,
4886 (carriage return) to cause each line to overwritten by the next line,
4889 keyword argument to make sure the previously-printed
4890 file name is overwritten with blank spaces:
4894 Progress('$TARGET\\r', overwrite=True)
4897 If the first argument to
4899 is a list of strings,
4900 then each string in the list will be displayed
4901 in rotating fashion every
4904 This can be used to implement a "spinner"
4905 on the user's screen as follows:
4908 Progress(['-\\r', '\\\\\\r', '|\\r', '/\\r'], interval=5)
4911 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4913 .RI Precious( target ", ...)"
4915 .RI env.Precious( target ", ...)"
4918 as precious so it is not deleted before it is rebuilt. Normally
4920 deletes a target before building it.
4921 Multiple targets can be passed in to a single call to
4924 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4926 .RI env.Prepend( key = val ", [...])"
4927 Appends the specified keyword arguments
4928 to the beginning of construction variables in the environment.
4929 If the Environment does not have
4930 the specified construction variable,
4931 it is simply added to the environment.
4932 If the values of the construction variable
4933 and the keyword argument are the same type,
4934 then the two values will be simply added together.
4935 Otherwise, the construction variable
4936 and the value of the keyword argument
4937 are both coerced to lists,
4938 and the lists are added together.
4939 (See also the Append method, above.)
4944 env.Prepend(CCFLAGS = '-g ', FOO = ['foo.yyy'])
4947 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4949 .RI env.PrependENVPath( name ", " newpath ", [" envname ", " sep ", " delete_existing ])
4950 This appends new path elements to the given path in the
4951 specified external environment
4955 any particular path once (leaving the first one it encounters and
4956 ignoring the rest, to preserve path order),
4957 and to help assure this,
4958 will normalize all paths (using
4961 .BR os.path.normcase ).
4962 This can also handle the
4963 case where the given old path variable is a list instead of a
4964 string, in which case a list will be returned instead of a string.
4968 is 0, then adding a path that already exists
4969 will not move it to the beginning;
4970 it will stay where it is in the list.
4975 print 'before:',env['ENV']['INCLUDE']
4976 include_path = '/foo/bar:/foo'
4977 env.PrependENVPath('INCLUDE', include_path)
4978 print 'after:',env['ENV']['INCLUDE']
4981 The above exmaple will print:
4985 after: /foo/bar:/foo:/biz
4988 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4990 .RI env.PrependUnique( key = val ", delete_existing=0, [...])"
4991 Appends the specified keyword arguments
4992 to the beginning of construction variables in the environment.
4993 If the Environment does not have
4994 the specified construction variable,
4995 it is simply added to the environment.
4996 If the construction variable being appended to is a list,
4997 then any value(s) that already exist in the
4998 construction variable will
5000 be added again to the list.
5001 However, if delete_existing is 1,
5002 existing matching values are removed first, so
5003 existing values in the arg list move to the front of the list.
5008 env.PrependUnique(CCFLAGS = '-g', FOO = ['foo.yyy'])
5011 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
5014 A factory function that
5015 returns a Builder object
5016 to be used to fetch source files
5018 The returned Builder
5019 is intended to be passed to the
5026 env.SourceCode('.', env.RCS())
5031 will fetch source files
5032 from RCS subdirectories automatically,
5034 as demonstrated in the above example
5035 should only be necessary if
5036 you are fetching from
5039 directory as the source files,
5040 or if you need to explicitly specify RCS
5041 for a specific subdirectory.
5043 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
5045 .RI env.Replace( key = val ", [...])"
5046 Replaces construction variables in the Environment
5047 with the specified keyword arguments.
5052 env.Replace(CCFLAGS = '-g', FOO = 'foo.xxx')
5055 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
5057 .RI Repository( directory )
5059 .RI env.Repository( directory )
5062 is a repository to be searched for files.
5066 and each one adds to the list of
5067 repositories that will be searched.
5071 a repository is a copy of the source tree,
5072 from the top-level directory on down,
5074 both source files and derived files
5075 that can be used to build targets in
5076 the local source tree.
5077 The canonical example would be an
5078 official source tree maintained by an integrator.
5079 If the repository contains derived files,
5080 then the derived files should have been built using
5082 so that the repository contains the necessary
5083 signature information to allow
5085 to figure out when it is appropriate to
5086 use the repository copy of a derived file,
5087 instead of building one locally.
5089 Note that if an up-to-date derived file
5090 already exists in a repository,
5094 make a copy in the local directory tree.
5095 In order to guarantee that a local copy
5101 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
5103 .RI Requires( target ", " prerequisite )
5105 .RI env.Requires( target ", " prerequisite )
5106 Specifies an order-only relationship
5107 between the specified target file(s)
5108 and the specified prerequisite file(s).
5109 The prerequisite file(s)
5110 will be (re)built, if necessary,
5113 but the target file(s) do not actually
5114 depend on the prerequisites
5115 and will not be rebuilt simply because
5116 the prerequisite file(s) change.
5121 env.Requires('foo', 'file-that-must-be-built-before-foo')
5124 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
5126 .RI Return([ vars "... , " stop= ])
5128 this stops processing the current SConscript
5129 file and returns to the calling SConscript file
5130 the values of the variables named in the
5133 Multiple strings contaning variable names may be passed to
5135 Any strings that contain white space
5139 keyword argument may be set to a false value
5140 to continue processing the rest of the SConscript
5144 This was the default behavior prior to SCons 0.98.
5145 However, the values returned
5146 are still the values of the variables in the named
5155 # Returns without returning a value.
5158 # Returns the value of the 'foo' Python variable.
5161 # Returns the values of the Python variables 'foo' and 'bar'.
5162 Return("foo", "bar")
5164 # Returns the values of Python variables 'val1' and 'val2'.
5168 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
5170 .RI Scanner( function ", [" argument ", " keys ", " path_function ", " node_class ", " node_factory ", " scan_check ", " recursive ])
5172 .RI env.Scanner( function ", [" argument ", " keys ", " path_function ", " node_class ", " node_factory ", " scan_check ", " recursive ])
5173 Creates a Scanner object for
5176 See the section "Scanner Objects,"
5177 below, for a complete explanation of the arguments and behavior.
5179 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
5182 A factory function that
5183 returns a Builder object
5184 to be used to fetch source files
5186 The returned Builder
5187 is intended to be passed to the
5194 env.SourceCode('.', env.SCCS())
5199 will fetch source files
5200 from SCCS subdirectories automatically,
5202 as demonstrated in the above example
5203 should only be necessary if
5204 you are fetching from
5207 directory as the source files,
5208 or if you need to explicitly specify SCCS
5209 for a specific subdirectory.
5211 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
5213 .RI SConscript( scripts ", [" exports ", " variant_dir ", " duplicate ])
5214 '\" .RI SConscript( scripts ", [" exports ", " variant_dir ", " src_dir ", " duplicate ])
5216 .RI env.SConscript( scripts ", [" exports ", " variant_dir ", " duplicate ])
5217 '\" .RI env.SConscript( scripts ", [" exports ", " variant_dir ", " src_dir ", " duplicate ])
5219 .RI SConscript(dirs= subdirs ", [name=" script ", " exports ", " variant_dir ", " duplicate ])
5220 '\" .RI SConscript(dirs= subdirs ", [name=" script ", " exports ", " variant_dir ", " src_dir ", " duplicate ])
5222 .RI env.SConscript(dirs= subdirs ", [name=" script ", " exports ", " variant_dir ", " duplicate ])
5223 '\" .RI env.SConscript(dirs= subdirs ", [name=" script ", " exports ", " variant_dir ", " src_dir ", " duplicate ])
5227 one or more subsidiary SConscript (configuration) files.
5228 Any variables returned by a called script using
5230 will be returned by the call to
5232 There are two ways to call the
5236 The first way you can call
5238 is to explicitly specify one or more
5240 as the first argument.
5241 A single script may be specified as a string;
5242 multiple scripts must be specified as a list
5243 (either explicitly or as created by
5248 SConscript('SConscript') # run SConscript in the current directory
5249 SConscript('src/SConscript') # run SConscript in the src directory
5250 SConscript(['src/SConscript', 'doc/SConscript'])
5251 config = SConscript('MyConfig.py')
5254 The second way you can call
5256 is to specify a list of (sub)directory names
5263 execute a subsidiary configuration file named
5265 in each of the specified directories.
5266 You may specify a name other than
5268 by supplying an optional
5271 The first three examples below have the same effect
5272 as the first three examples above:
5274 SConscript(dirs='.') # run SConscript in the current directory
5275 SConscript(dirs='src') # run SConscript in the src directory
5276 SConscript(dirs=['src', 'doc'])
5277 SConscript(dirs=['sub1', 'sub2'], name='MySConscript')
5282 argument provides a list of variable names or a dictionary of
5283 named values to export to the
5285 These variables are locally exported only to the specified
5287 and do not affect the global pool of variables used by the
5290 '\"If multiple dirs are provided, each script gets a fresh export.
5295 function to import the variables.
5298 foo = SConscript('sub/SConscript', exports='env')
5299 SConscript('dir/SConscript', exports=['env', 'variable'])
5300 SConscript(dirs='subdir', exports='env variable')
5301 SConscript(dirs=['one', 'two', 'three'], exports='shared_info')
5306 argument is present, it causes an effect equivalent to the
5308 method described below.
5314 '\" arguments are ignored.)
5315 argument is ignored.)
5320 '\" arguments are interpreted relative to the directory of the calling
5321 argument is interpreted relative to the directory of the calling
5324 See the description of the
5326 function below for additional details and restrictions.
5332 '\" .IR src_dir " is not,"
5333 the source directory is the directory in which the
5335 file resides and the
5337 file is evaluated as if it were in the
5341 SConscript('src/SConscript', variant_dir = 'build')
5345 VariantDir('build', 'src')
5346 SConscript('build/SConscript')
5348 This later paradigm is often used when the sources are
5349 in the same directory as the
5352 SConscript('SConscript', variant_dir = 'build')
5356 VariantDir('build', '.')
5357 SConscript('build/SConscript')
5361 '\" .IR variant_dir " and"
5362 '\" .IR src_dir " are both present,"
5363 '\" xxxxx everything is in a state of confusion.
5365 '\" SConscript(dirs = 'src', variant_dir = 'build', src_dir = '.')
5366 '\" runs src/SConscript in build/src, but
5367 '\" SConscript(dirs = 'lib', variant_dir = 'build', src_dir = 'src')
5368 '\" runs lib/SConscript (in lib!). However,
5369 '\" SConscript(dirs = 'src', variant_dir = 'build', src_dir = 'src')
5370 '\" runs src/SConscript in build. Moreover,
5371 '\" SConscript(dirs = 'src/lib', variant_dir = 'build', src_dir = 'src')
5372 '\" runs src/lib/SConscript in build/lib. Moreover,
5373 '\" SConscript(dirs = 'build/src/lib', variant_dir = 'build', src_dir = 'src')
5374 '\" can't find build/src/lib/SConscript, even though it ought to exist.
5376 '\" is equivalent to
5378 '\" ????????????????
5380 '\" and what about this alternative?
5381 '\"TODO??? SConscript('build/SConscript', src_dir='src')
5383 Here are some composite examples:
5386 # collect the configuration information and use it to build src and doc
5387 shared_info = SConscript('MyConfig.py')
5388 SConscript('src/SConscript', exports='shared_info')
5389 SConscript('doc/SConscript', exports='shared_info')
5393 # build debugging and production versions. SConscript
5394 # can use Dir('.').path to determine variant.
5395 SConscript('SConscript', variant_dir='debug', duplicate=0)
5396 SConscript('SConscript', variant_dir='prod', duplicate=0)
5400 # build debugging and production versions. SConscript
5401 # is passed flags to use.
5402 opts = { 'CPPDEFINES' : ['DEBUG'], 'CCFLAGS' : '-pgdb' }
5403 SConscript('SConscript', variant_dir='debug', duplicate=0, exports=opts)
5404 opts = { 'CPPDEFINES' : ['NODEBUG'], 'CCFLAGS' : '-O' }
5405 SConscript('SConscript', variant_dir='prod', duplicate=0, exports=opts)
5409 # build common documentation and compile for different architectures
5410 SConscript('doc/SConscript', variant_dir='build/doc', duplicate=0)
5411 SConscript('src/SConscript', variant_dir='build/x86', duplicate=0)
5412 SConscript('src/SConscript', variant_dir='build/ppc', duplicate=0)
5415 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
5417 .RI SConscriptChdir( value )
5419 .RI env.SConscriptChdir( value )
5422 changes its working directory
5423 to the directory in which each
5424 subsidiary SConscript file lives.
5425 This behavior may be disabled
5426 by specifying either:
5430 env.SConscriptChdir(0)
5435 will stay in the top-level directory
5436 while reading all SConscript files.
5437 (This may be necessary when building from repositories,
5438 when all the directories in which SConscript files may be found
5439 don't necessarily exist locally.)
5440 You may enable and disable
5441 this ability by calling
5450 SConscript('foo/SConscript') # will not chdir to foo
5451 env.SConscriptChdir(1)
5452 SConscript('bar/SConscript') # will chdir to bar
5455 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
5457 .RI SConsignFile([ file , dbm_module ])
5459 .RI env.SConsignFile([ file , dbm_module ])
5462 to store all file signatures
5463 in the specified database
5470 (The actual file name(s) stored on disk
5471 may have an appropriated suffix appended
5476 is not an absolute path name,
5477 the file is placed in the same directory as the top-level
5487 will store file signatures
5490 file in each directory,
5491 not in one global database file.
5492 (This was the default behavior
5493 prior to SCons 0.96.91 and 0.97.)
5497 argument can be used to specify
5498 which Python database module
5499 The default is to use a custom
5501 module that uses pickled
5502 Python data structures,
5503 and which works on all Python versions from 1.5.2 on.
5508 # Explicitly stores signatures in ".sconsign.dblite"
5509 # in the top-level SConstruct directory (the
5510 # default behavior).
5513 # Stores signatures in the file "etc/scons-signatures"
5514 # relative to the top-level SConstruct directory.
5515 SConsignFile("etc/scons-signatures")
5517 # Stores signatures in the specified absolute file name.
5518 SConsignFile("/home/me/SCons/signatures")
5520 # Stores signatures in a separate .sconsign file
5521 # in each directory.
5525 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
5527 .RI env.SetDefault(key = val ", [...])"
5528 Sets construction variables to default values specified with the keyword
5529 arguments if (and only if) the variables are not already set.
5530 The following statements are equivalent:
5533 env.SetDefault(FOO = 'foo')
5535 if 'FOO' not in env: env['FOO'] = 'foo'
5538 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
5540 .RI SetOption( name ", " value )
5542 .RI env.SetOption( name ", " value )
5543 This function provides a way to set a select subset of the scons command
5544 line options from a SConscript file. The options supported are:
5549 which corresponds to -c, --clean and --remove;
5552 which corresponds to --duplicate;
5555 which corresponds to -h and --help;
5558 which corresponds to --implicit-cache;
5561 which corresponds to --max-drift;
5564 which corresponds to -n, --no-exec, --just-print, --dry-run and --recon;
5567 which corresponds to -j and --jobs;
5570 which corresponds to --random; and
5573 which corresponds to --stack-size.
5577 See the documentation for the
5578 corresponding command line object for information about each specific
5584 SetOption('max_drift', 1)
5587 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
5589 .RI SideEffect( side_effect ", " target )
5591 .RI env.SideEffect( side_effect ", " target )
5594 as a side effect of building
5600 can be a list, a file name, or a node.
5601 A side effect is a target file that is created or updated
5602 as a side effect of building other targets.
5603 For example, a Windows PDB
5604 file is created as a side effect of building the .obj
5605 files for a static library,
5606 and various log files are created updated
5607 as side effects of various TeX commands.
5608 If a target is a side effect of multiple build commands,
5610 will ensure that only one set of commands
5611 is executed at a time.
5612 Consequently, you only need to use this method
5613 for side-effect targets that are built as a result of
5614 multiple build commands.
5616 Because multiple build commands may update
5617 the same side effect file,
5622 automatically removed
5628 (Note, however, that the
5630 might be removed as part of
5631 cleaning the directory in which it lives.)
5632 If you want to make sure the
5634 is cleaned whenever a specific
5637 you must specify this explicitly
5644 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
5646 .RI SourceCode( entries ", " builder )
5648 .RI env.SourceCode( entries ", " builder )
5649 Arrange for non-existent source files to
5650 be fetched from a source code management system
5655 may be a Node, string or list of both,
5656 and may represent either individual
5657 source files or directories in which
5658 source files can be found.
5660 For any non-existent source files,
5662 will search up the directory tree
5672 will not use a builder to fetch
5673 source files for the specified
5677 builder has been specified
5678 for a directory higher up the tree.
5682 fetch files from SCCS or RCS subdirectories
5683 without explicit configuration.
5684 This takes some extra processing time
5685 to search for the necessary
5686 source code management files on disk.
5687 You can avoid these extra searches
5688 and speed up your build a little
5689 by disabling these searches as follows:
5692 env.SourceCode('.', None)
5696 Note that if the specified
5698 is one you create by hand,
5699 it must have an associated
5700 construction environment to use
5701 when fetching a source file.
5704 provides a set of canned factory
5705 functions that return appropriate
5706 Builders for various popular
5707 source code management systems.
5708 Canonical examples of invocation include:
5711 env.SourceCode('.', env.BitKeeper('/usr/local/BKsources'))
5712 env.SourceCode('src', env.CVS('/usr/local/CVSROOT'))
5713 env.SourceCode('/', env.RCS())
5714 env.SourceCode(['f1.c', 'f2.c'], env.SCCS())
5715 env.SourceCode('no_source.c', None)
5717 '\"env.SourceCode('.', env.Subversion('file:///usr/local/Subversion'))
5719 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
5721 .RI env.subst( input ", [" raw ", " target ", " source ", " conv ])
5722 Performs construction variable interpolation
5723 on the specified string or sequence argument
5727 leading or trailing white space will
5728 be removed from the result.
5729 and all sequences of white space
5730 will be compressed to a single space character.
5735 character sequences will be stripped from the returned string,
5738 argument may be set to
5740 if you want to preserve white space and
5745 argument may be set to
5747 if you want to strip
5748 all characters between
5754 (as is done for signature calculation).
5756 If the input is a sequence
5758 the individual elements of
5759 the sequence will be expanded,
5760 and the results will be returned as a list.
5767 must be set to lists of
5768 target and source nodes, respectively,
5775 to be available for expansion.
5776 This is usually necessary if you are
5779 from within a Python function used
5782 Returned string values or sequence elements
5783 are converted to their string representation by default.
5787 may specify a conversion function
5788 that will be used in place of
5790 For example, if you want Python objects
5791 (including SCons Nodes)
5792 to be returned as Python objects,
5793 you can use the Python
5795 idiom to pass in an unnamed function
5796 that simply returns its unconverted argument.
5801 print env.subst("The C compiler is: $CC")
5803 def compile(target, source, env):
5804 sourceDir = env.subst("${SOURCE.srcdir}",
5808 source_nodes = env.subst('$EXPAND_TO_NODELIST',
5812 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
5814 '\".RI Subversion( repository ", " module )
5815 '\"A factory function that
5816 '\"returns a Builder object
5817 '\"to be used to fetch source files
5818 '\"from the specified Subversion
5820 '\"The returned Builder
5821 '\"is intended to be passed to the
5825 '\"The optional specified
5827 '\"will be added to the beginning
5828 '\"of all repository path names;
5829 '\"this can be used, in essence,
5830 '\"to strip initial directory names
5831 '\"from the repository path names,
5832 '\"so that you only have to
5833 '\"replicate part of the repository
5834 '\"directory hierarchy in your
5835 '\"local build directory.
5840 '\"# Will fetch foo/bar/src.c
5841 '\"# from /usr/local/Subversion/foo/bar/src.c.
5842 '\"env.SourceCode('.', env.Subversion('file:///usr/local/Subversion'))
5844 '\"# Will fetch bar/src.c
5845 '\"# from /usr/local/Subversion/foo/bar/src.c.
5846 '\"env.SourceCode('.', env.Subversion('file:///usr/local/Subversion', 'foo'))
5848 '\"# Will fetch src.c
5849 '\"# from /usr/local/Subversion/foo/bar/src.c.
5850 '\"env.SourceCode('.', env.Subversion('file:///usr/local/Subversion', 'foo/bar'))
5853 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
5855 .RI SourceSignatures( type )
5857 .RI env.SourceSignatures( type )
5858 Note: Although it is not yet officially deprecated,
5859 use of this function is discouraged.
5862 function for a more flexible and straightforward way
5863 to configure SCons' decision-making.
5866 .BR SourceSignatures ()
5869 how to decide if a source file
5870 (a file that is not built from any other files)
5871 has changed since the last time it
5872 was used to build a particular target file.
5878 If the environment method is used,
5879 the specified type of source signature
5880 is only used when deciding whether targets
5881 built with that environment are up-to-date or must be rebuilt.
5882 If the global function is used,
5883 the specified type of source signature becomes the default
5884 used for all decisions
5885 about whether targets are up-to-date.
5890 decides that a source file has changed
5891 if the MD5 checksum of its contents has changed since
5892 the last time it was used to rebuild a particular target file.
5897 decides that a source file has changed
5898 if its timestamp (modification time) has changed since
5899 the last time it was used to rebuild a particular target file.
5900 (Note that although this is similar to the behavior of Make,
5901 by default it will also rebuild if the dependency is
5903 than the last time it was used to rebuild the target file.)
5905 There is no different between the two behaviors
5911 signatures take longer to compute,
5912 but are more accurate than
5915 The default value is
5918 Note that the default
5919 .BR TargetSignatures ()
5922 .BR SourceSignatures ()
5923 setting for any target files that are used
5924 to build other target files.
5925 Consequently, changing the value of
5926 .BR SourceSignatures ()
5928 affect the up-to-date decision for all files in the build
5929 (or all files built with a specific construction environment
5931 .BR env.SourceSignatures ()
5934 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
5938 .RI env.Split( arg )
5939 Returns a list of file names or other objects.
5941 it will be split on strings of white-space characters
5943 making it easier to write long lists of file names.
5944 If arg is already a list,
5945 the list will be returned untouched.
5946 If arg is any other type of object,
5947 it will be returned as a list
5948 containing just the object.
5953 files = Split("f1.c f2.c f3.c")
5954 files = env.Split("f4.c f5.c f6.c")
5962 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
5964 .RI Tag( node ", " tags )
5965 Annotates file or directory Nodes with
5966 information about how the
5968 Builder should package those files or directories.
5969 All tags are optional.
5974 # makes sure the built library will be installed with 0644 file
5976 Tag( Library( 'lib.c' ), UNIX_ATTR="0644" )
5978 # marks file2.txt to be a documentation file
5979 Tag( 'file2.txt', DOC )
5982 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
5984 .RI TargetSignatures( type )
5986 .RI env.TargetSignatures( type )
5987 Note: Although it is not yet officially deprecated,
5988 use of this function is discouraged.
5991 function for a more flexible and straightforward way
5992 to configure SCons' decision-making.
5995 .BR TargetSignatures ()
5998 how to decide if a target file
6001 built from any other files)
6002 has changed since the last time it
6003 was used to build some other target file.
6013 If the environment method is used,
6014 the specified type of target signature is only used
6015 for targets built with that environment.
6016 If the global function is used,
6017 the specified type of signature becomes the default
6018 used for all target files that
6019 don't have an explicit target signature type
6020 specified for their environments.
6027 decides that a target file has changed
6028 if the MD5 checksum of its contents has changed since
6029 the last time it was used to rebuild some other target file.
6033 MD5 sum the contents
6034 of target files after they're built,
6035 and may decide that it does not need to rebuild
6036 "downstream" target files if a file was
6037 rebuilt with exactly the same contents as the last time.
6042 decides that a target file has changed
6043 if its timestamp (modification time) has changed since
6044 the last time it was used to rebuild some other target file.
6045 (Note that although this is similar to the behavior of Make,
6046 by default it will also rebuild if the dependency is
6048 than the last time it was used to rebuild the target file.)
6053 decides that a target file has changed
6054 as specified by the corresponding
6055 .BR SourceSignatures ()
6062 will treat all input files to a target the same way,
6063 regardless of whether they are source files
6064 or have been built from other files.
6069 decides that a target file has changed
6070 if it has been rebuilt in this invocation
6071 or if its content or timestamp have changed
6072 as specified by the corresponding
6073 .BR SourceSignatures ()
6075 This "propagates" the status of a rebuilt file
6076 so that other "downstream" target files
6077 will always be rebuilt,
6078 even if the contents or the timestamp
6082 signatures are fastest because
6086 signatures take longer to compute,
6087 but are more accurate than
6090 and can prevent unnecessary "downstream" rebuilds
6091 when a target file is rebuilt to the exact same contents
6092 as the previous build.
6095 setting provides the most consistent behavior
6096 when other target files may be rebuilt from
6097 both source and target input files.
6098 The default value is
6101 Because the default setting is
6104 .BR SourceSignatures ()
6105 is generally preferable to
6106 .BR TargetSignatures () ,
6107 so that the up-to-date decision
6108 will be consistent for all files
6109 (or all files built with a specific construction environment).
6111 .BR TargetSignatures ()
6112 provides specific control for how built target files
6113 affect their "downstream" dependencies.
6115 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
6117 .RI Tool( string [, toolpath ", " **kw ])
6118 Returns a callable object
6119 that can be used to initialize
6120 a construction environment using the
6121 tools keyword of the Environment() method.
6122 The object may be called with a construction
6123 environment as an argument,
6124 in which case the object will
6125 add the necessary variables
6126 to the construction environment
6127 and the name of the tool will be added to the
6129 construction variable.
6131 Additional keyword arguments are passed to the tool's
6138 env = Environment(tools = [ Tool('msvc') ])
6142 t(env) # adds 'msvc' to the TOOLS variable
6143 u = Tool('opengl', toolpath = ['tools'])
6144 u(env) # adds 'opengl' to the TOOLS variable
6147 .RI env.Tool( string [, toolpath ", " **kw ])
6148 Applies the callable object for the specified tool
6150 to the environment through which the method was called.
6152 Additional keyword arguments are passed to the tool's
6158 env.Tool('opengl', toolpath = ['build/tools'])
6161 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
6163 .RI Value( value ", [" built_value ])
6165 .RI env.Value( value ", [" built_value ])
6166 Returns a Node object representing the specified Python value. Value
6167 Nodes can be used as dependencies of targets. If the result of
6170 changes between SCons runs, any targets depending on
6173 (This is true even when using timestamps to decide if
6174 files are up-to-date.)
6175 When using timestamp source signatures, Value Nodes'
6176 timestamps are equal to the system time when the Node is created.
6178 The returned Value Node object has a
6180 method that can be used to "build" a Value Node
6181 by setting a new value.
6184 argument can be specified
6185 when the Value Node is created
6186 to indicate the Node should already be considered
6188 There is a corresponding
6190 method that will return the built value of the Node.
6197 def create(target, source, env):
6198 # A function that will write a 'prefix=$SOURCE'
6199 # string into the file name specified as the
6201 f = open(str(target[0]), 'wb')
6202 f.write('prefix=' + source[0].get_contents())
6204 # Fetch the prefix= argument, if any, from the command
6205 # line, and use /usr/local as the default.
6206 prefix = ARGUMENTS.get('prefix', '/usr/local')
6208 # Attach a .Config() builder for the above function action
6209 # to the construction environment.
6210 env['BUILDERS']['Config'] = Builder(action = create)
6211 env.Config(target = 'package-config', source = Value(prefix))
6213 def build_value(target, source, env):
6214 # A function that "builds" a Python Value by updating
6215 # the the Python value with the contents of the file
6216 # specified as the source of the Builder call ($SOURCE).
6217 target[0].write(source[0].get_contents())
6219 output = env.Value('before')
6220 input = env.Value('after')
6222 # Attach a .UpdateValue() builder for the above function
6223 # action to the construction environment.
6224 env['BUILDERS']['UpdateValue'] = Builder(action = build_value)
6225 env.UpdateValue(target = Value(output), source = Value(input))
6228 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
6230 .RI VariantDir( variant_dir ", " src_dir ", [" duplicate ])
6232 .RI env.VariantDir( variant_dir ", " src_dir ", [" duplicate ])
6235 function to create a copy of your sources in another location:
6238 is not found but exists under
6240 the file or directory is copied to
6242 Target files can be built in a different directory
6243 than the original sources by simply refering to the sources (and targets)
6244 within the variant tree.
6247 can be called multiple times with the same
6249 to set up multiple builds with different options
6253 location must be in or underneath the SConstruct file's directory, and
6255 may not be underneath
6257 '\"TODO: Can the above restrictions be clarified or relaxed?
6258 '\"TODO: The latter restriction is clearly not completely right;
6259 '\"TODO: src_dir = '.' works fine with a build dir under it.
6261 The default behavior is for
6263 to physically duplicate the source files in the variant tree.
6264 Thus, a build performed in the variant tree is guaranteed to be identical
6265 to a build performed in the source tree even if
6266 intermediate source files are generated during the build,
6267 or preprocessors or other scanners search for included files
6268 relative to the source file,
6269 or individual compilers or other invoked tools are hard-coded
6270 to put derived files in the same directory as source files.
6272 If possible on the platform,
6273 the duplication is performed by linking rather than copying;
6276 command-line option.
6277 Moreover, only the files needed for the build are duplicated;
6278 files and directories that are not used are not present in
6281 Duplicating the source tree may be disabled by setting the
6283 argument to 0 (zero).
6286 to invoke Builders using the path names of source files in
6288 and the path names of derived files within
6290 This is always more efficient than
6292 and is usually safe for most builds
6293 (but see above for cases that may cause problems).
6297 works most naturally with a subsidiary SConscript file.
6298 However, you would then call the subsidiary SConscript file
6299 not in the source directory, but in the
6301 regardless of the value of
6303 This is how you tell
6305 which variant of a source tree to build:
6308 # run src/SConscript in two variant directories
6309 VariantDir('build/variant1', 'src')
6310 SConscript('build/variant1/SConscript')
6311 VariantDir('build/variant2', 'src')
6312 SConscript('build/variant2/SConscript')
6318 function, described above,
6319 for another way to specify a variant directory
6320 in conjunction with calling a subsidiary SConscript file.
6325 # use names in the build directory, not the source directory
6326 VariantDir('build', 'src', duplicate=0)
6327 Program('build/prog', 'build/source.c')
6331 # this builds both the source and docs in a separate subtree
6332 VariantDir('build', '.', duplicate=0)
6333 SConscript(dirs=['build/src','build/doc'])
6337 # same as previous example, but only uses SConscript
6338 SConscript(dirs='src', variant_dir='build/src', duplicate=0)
6339 SConscript(dirs='doc', variant_dir='build/doc', duplicate=0)
6342 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
6344 .RI WhereIs( program ", [" path ", " pathext ", " reject ])
6346 .RI env.WhereIs( program ", [" path ", " pathext ", " reject ])
6348 Searches for the specified executable
6350 returning the full path name to the program
6352 and returning None if not.
6353 Searches the specified
6355 the value of the calling environment's PATH
6356 (env['ENV']['PATH']),
6357 or the user's current external PATH
6358 (os.environ['PATH'])
6360 On Windows systems, searches for executable
6361 programs with any of the file extensions
6362 listed in the specified
6364 the calling environment's PATHEXT
6365 (env['ENV']['PATHEXT'])
6366 or the user's current PATHEXT
6367 (os.environ['PATHEXT'])
6375 .SS SConscript Variables
6376 In addition to the global functions and methods,
6378 supports a number of Python variables
6379 that can be used in SConscript files
6380 to affect how you want the build to be performed.
6381 These variables may be accessed from custom Python modules that you
6382 import into an SConscript file by adding the following
6383 to the Python module:
6386 from SCons.Script import *
6389 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
6394 arguments specified on the command line.
6395 Each element in the list is a tuple
6397 .RI ( keyword , value )
6403 elements of the tuple
6405 subscripting for element
6409 of the tuple, respectively.
6414 print "first keyword, value =", ARGLIST[0][0], ARGLIST[0][1]
6415 print "second keyword, value =", ARGLIST[1][0], ARGLIST[1][1]
6416 third_tuple = ARGLIST[2]
6417 print "third keyword, value =", third_tuple[0], third_tuple[1]
6418 for key, value in ARGLIST:
6419 # process key and value
6422 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
6425 A dictionary of all the
6427 arguments specified on the command line.
6428 The dictionary is not in order,
6429 and if a given keyword has
6430 more than one value assigned to it
6431 on the command line,
6432 the last (right-most) value is
6440 if ARGUMENTS.get('debug', 0):
6441 env = Environment(CCFLAGS = '-g')
6446 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
6449 A list of the targets which
6451 will actually try to build,
6452 regardless of whether they were specified on
6453 the command line or via the
6456 The elements of this list may be strings
6458 nodes, so you should run the list through the Python
6460 function to make sure any Node path names
6461 are converted to strings.
6463 Because this list may be taken from the
6464 list of targets specified using the
6467 the contents of the list may change
6468 on each successive call to
6473 for additional information.
6478 if 'foo' in BUILD_TARGETS:
6479 print "Don't forget to test the `foo' program!"
6480 if 'special/program' in BUILD_TARGETS:
6481 SConscript('special')
6486 list only contains targets expected listed
6487 on the command line or via calls to the
6492 contain all dependent targets that will be built as
6493 a result of making the sure the explicitly-specified
6494 targets are up to date.
6496 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
6498 COMMAND_LINE_TARGETS
6499 A list of the targets explicitly specified on
6501 If there are no targets specified on the command line,
6503 This can be used, for example,
6504 to take specific actions only
6505 when a certain target or targets
6506 is explicitly being built.
6511 if 'foo' in COMMAND_LINE_TARGETS:
6512 print "Don't forget to test the `foo' program!"
6513 if 'special/program' in COMMAND_LINE_TARGETS:
6514 SConscript('special')
6517 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
6520 A list of the target
6522 that have been specified using the
6525 The elements of the list are nodes,
6526 so you need to run them through the Python
6528 function to get at the path name for each Node.
6533 print str(DEFAULT_TARGETS[0])
6534 if 'foo' in map(str, DEFAULT_TARGETS):
6535 print "Don't forget to test the `foo' program!"
6540 list change on on each successive call to the
6545 print map(str, DEFAULT_TARGETS) # originally []
6547 print map(str, DEFAULT_TARGETS) # now a node ['foo']
6549 print map(str, DEFAULT_TARGETS) # now a node ['foo', 'bar']
6551 print map(str, DEFAULT_TARGETS) # back to []
6554 Consequently, be sure to use
6556 only after you've made all of your
6559 or else simply be careful of the order
6560 of these statements in your SConscript files
6561 so that you don't look for a specific
6562 default target before it's actually been added to the list.
6564 .SS Construction Variables
6565 .\" XXX From Gary Ruben, 23 April 2002:
6566 .\" I think it would be good to have an example with each construction
6567 .\" variable description in the documentation.
6569 .\" CC The C compiler
6570 .\" Example: env["CC"] = "c68x"
6571 .\" Default: env["CC"] = "cc"
6573 .\" CCCOM The command line ...
6575 .\" To generate the compiler line c68x -ps -qq -mr -o $TARGET $SOURCES
6576 .\" env["CC"] = "c68x"
6577 .\" env["CFLAGS"] = "-ps -qq -mr"
6578 .\" env["CCCOM"] = "$CC $CFLAGS -o $TARGET $SOURCES
6580 .\" (I dunno what this is ;-)
6581 A construction environment has an associated dictionary of
6582 .I construction variables
6583 that are used by built-in or user-supplied build rules.
6584 Construction variables must follow the same rules for
6586 the initial character must be an underscore or letter,
6587 followed by any number of underscores, letters, or digits.
6589 A number of useful construction variables are automatically defined by
6590 scons for each supported platform, and additional construction variables
6591 can be defined by the user. The following is a list of the automatically
6592 defined construction variables:
6594 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
6595 '\" BEGIN GENERATED CONSTRUCTION VARIABLE DESCRIPTIONS
6597 '\" The descriptions below of the various SCons construction variables
6598 '\" are generated from the .xml files that live next to the various
6599 '\" Python modules in the build enginer library. If you're reading
6600 '\" this [gnt]roff file with an eye towards patching this man page,
6601 '\" you can still submit a diff against this text, but it will have to
6602 '\" be translated to a diff against the underlying .xml file before the
6603 '\" patch is actually accepted. If you do that yourself, it will make
6604 '\" it easier to integrate the patch.
6606 '\" BEGIN GENERATED CONSTRUCTION VARIABLE DESCRIPTIONS
6607 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
6609 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
6610 '\" END GENERATED CONSTRUCTION VARIABLE DESCRIPTIONS
6612 '\" The descriptions above of the various SCons construction variables
6613 '\" are generated from the .xml files that live next to the various
6614 '\" Python modules in the build enginer library. If you're reading
6615 '\" this [gnt]roff file with an eye towards patching this man page,
6616 '\" you can still submit a diff against this text, but it will have to
6617 '\" be translated to a diff against the underlying .xml file before the
6618 '\" patch is actually accepted. If you do that yourself, it will make
6619 '\" it easier to integrate the patch.
6621 '\" END GENERATED CONSTRUCTION VARIABLE DESCRIPTIONS
6622 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
6625 Construction variables can be retrieved and set using the
6627 method of the construction environment:
6630 dict = env.Dictionary()
6634 or using the [] operator:
6640 Construction variables can also be passed to the construction environment
6644 env = Environment(CC="cc")
6647 or when copying a construction environment using the
6652 env2 = env.Clone(CC="cl.exe")
6655 .SS Configure Contexts
6659 .I configure contexts,
6660 an integrated mechanism similar to the
6661 various AC_CHECK macros in GNU autoconf
6662 for testing for the existence of C header
6663 files, libraries, etc.
6664 In contrast to autoconf,
6666 does not maintain an explicit cache of the tested values,
6667 but uses its normal dependency tracking to keep the checked values
6668 up to date. However, users may override this behaviour with the
6670 command line option.
6672 The following methods can be used to perform checks:
6675 .RI Configure( env ", [" custom_tests ", " conf_dir ", " log_file ", " config_h ", " clean ", " help])
6677 .RI env.Configure([ custom_tests ", " conf_dir ", " log_file ", " config_h ", " clean ", " help])
6678 This creates a configure context, which can be used to perform checks.
6680 specifies the environment for building the tests.
6681 This environment may be modified when performing checks.
6683 is a dictionary containing custom tests.
6684 See also the section about custom tests below.
6685 By default, no custom tests are added to the configure context.
6687 specifies a directory where the test cases are built.
6688 Note that this directory is not used for building
6690 The default value is the directory
6693 specifies a file which collects the output from commands
6694 that are executed to check for the existence of header files, libraries, etc.
6695 The default is the file #/config.log.
6696 If you are using the
6699 you may want to specify a subdirectory under your variant directory.
6701 specifies a C header file where the results of tests
6702 will be written, e.g. #define HAVE_STDIO_H, #define HAVE_LIBM, etc.
6703 The default is to not write a
6706 You can specify the same
6708 file in multiple calls to Configure,
6711 will concatenate all results in the specified file.
6713 uses its normal dependency checking
6714 to decide if it's necessary to rebuild
6718 This means that the file is not necessarily re-built each
6720 but is only rebuilt if its contents will have changed
6721 and some target that depends on the
6723 file is being built.
6729 arguments can be used to suppress execution of the configuration
6734 options are used, respectively.
6735 The default behavior is always to execute
6736 configure context tests,
6737 since the results of the tests may
6738 affect the list of targets to be cleaned
6740 If the configure tests do not affect these,
6741 then you may add the
6747 to avoid unnecessary test execution.
6752 instance has the following associated methods:
6755 .RI SConf.Finish( context )
6758 This method should be called after configuration is done.
6759 It returns the environment as modified
6760 by the configuration checks performed.
6761 After this method is called, no further checks can be performed
6762 with this configuration context.
6763 However, you can create a new
6765 context to perform additional checks.
6766 Only one context should be active at a time.
6768 The following Checks are predefined.
6769 (This list will likely grow larger as time
6770 goes by and developers contribute new useful tests.)
6773 .RI SConf.CheckHeader( context ", " header ", [" include_quotes ", " language ])
6775 .IR sconf .CheckHeader( header ", [" include_quotes ", " language ])
6778 is usable in the specified language.
6781 in which case the last item in the list
6782 is the header file to be checked,
6783 and the previous list items are
6786 lines should precede the
6787 header line being checked for.
6788 The optional argument
6791 a two character string, where the first character denotes the opening
6792 quote and the second character denotes the closing quote.
6793 By default, both characters are " (double quote).
6794 The optional argument
6800 and selects the compiler to be used for the check.
6801 Returns 1 on success and 0 on failure.
6804 .RI SConf.CheckCHeader( context ", " header ", [" include_quotes ])
6806 .IR sconf .CheckCHeader( 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.CheckCXXHeader( context ", " header ", [" include_quotes ])
6832 .IR sconf .CheckCXXHeader( header ", [" include_quotes ])
6833 This is a wrapper around
6834 .B SConf.CheckHeader
6837 is usable in the C++ language.
6840 in which case the last item in the list
6841 is the header file to be checked,
6842 and the previous list items are
6845 lines should precede the
6846 header line being checked for.
6847 The optional argument
6850 a two character string, where the first character denotes the opening
6851 quote and the second character denotes the closing quote (both default
6853 Returns 1 on success and 0 on failure.
6856 .RI SConf.CheckFunc( context, ", " function_name ", [" header ", " language ])
6858 .IR sconf .CheckFunc( function_name ", [" header ", " language ])
6859 Checks if the specified
6860 C or C++ function is available.
6862 is the name of the function to check for.
6865 argument is a string
6869 that will be compiled
6870 to check if the function exists;
6876 char function_name();
6884 and selects the compiler to be used for the check;
6888 .RI SConf.CheckLib( context ", [" library ", " symbol ", " header ", " language ", " autoadd=1 ])
6890 .IR sconf .CheckLib([ library ", " symbol ", " header ", " language ", " autoadd=1 ])
6897 is 1 and the library provides the specified
6899 appends the library to the LIBS construction environment variable.
6901 may also be None (the default),
6904 is checked with the current LIBS variable,
6905 or a list of library names,
6906 in which case each library in the list
6914 .BR SConf.CheckLib ()
6916 you can link against the specified
6924 and selects the compiler to be used for the check;
6926 The default value for
6929 This method returns 1 on success and 0 on error.
6932 .RI SConf.CheckLibWithHeader( context ", " library ", " header ", " language ", [" call ", " autoadd ])
6934 .IR sconf .CheckLibWithHeader( library ", " header ", " language ", [" call ", " autoadd ])
6938 call, this call provides a more sophisticated way to check against libraries.
6941 specifies the library or a list of libraries to check.
6943 specifies a header to check for.
6946 in which case the last item in the list
6947 is the header file to be checked,
6948 and the previous list items are
6951 lines should precede the
6952 header line being checked for.
6954 may be one of 'C','c','CXX','cxx','C++' and 'c++'.
6956 can be any valid expression (with a trailing ';').
6960 the default simply checks that you
6961 can link against the specified
6964 specifies whether to add the library to the environment (only if the check
6965 succeeds). This method returns 1 on success and 0 on error.
6968 .RI SConf.CheckType( context ", " type_name ", [" includes ", " language ])
6970 .IR sconf .CheckType( type_name ", [" includes ", " language ])
6971 Checks for the existence of a type defined by
6974 specifies the typedef name to check for.
6976 is a string containing one or more
6978 lines that will be inserted into the program
6979 that will be run to test for the existence of the type.
6986 and selects the compiler to be used for the check;
6990 sconf.CheckType('foo_type', '#include "my_types.h"', 'C++')
6994 .RI Configure.CheckCC( self )
6995 Checks whether the C compiler (as defined by the CC construction variable) works
6996 by trying to compile a small source file.
6998 By default, SCons only detects if there is a program with the correct name, not
6999 if it is a functioning compiler.
7001 This uses the exact same command than the one used by the object builder for C
7002 source file, so it can be used to detect if a particular compiler flag works or
7006 .RI Configure.CheckCXX( self )
7007 Checks whether the C++ compiler (as defined by the CXX construction variable)
7008 works by trying to compile a small source file. By default, SCons only detects
7009 if there is a program with the correct name, not if it is a functioning compiler.
7011 This uses the exact same command than the one used by the object builder for
7012 CXX source files, so it can be used to detect if a particular compiler flag
7016 .RI Configure.CheckSHCC( self )
7017 Checks whether the C compiler (as defined by the SHCC construction variable) works
7018 by trying to compile a small source file. By default, SCons only detects if
7019 there is a program with the correct name, not if it is a functioning compiler.
7021 This uses the exact same command than the one used by the object builder for C
7022 source file, so it can be used to detect if a particular compiler flag works or
7023 not. This does not check whether the object code can be used to build a shared
7024 library, only that the compilation (not link) succeeds.
7027 .RI Configure.CheckSHCXX( self )
7028 Checks whether the C++ compiler (as defined by the SHCXX construction variable)
7029 works by trying to compile a small source file. By default, SCons only detects
7030 if there is a program with the correct name, not if it is a functioning compiler.
7032 This uses the exact same command than the one used by the object builder for
7033 CXX source files, so it can be used to detect if a particular compiler flag
7034 works or not. This does not check whether the object code can be used to build
7035 a shared library, only that the compilation (not link) succeeds.
7038 Example of a typical Configure usage:
7042 conf = Configure( env )
7043 if not conf.CheckCHeader( 'math.h' ):
7044 print 'We really need math.h!'
7046 if conf.CheckLibWithHeader( 'qt', 'qapp.h', 'c++',
7047 'QApplication qapp(0,0);' ):
7048 # do stuff for qt - usage, e.g.
7049 conf.env.Append( CPPFLAGS = '-DWITH_QT' )
7054 .RI SConf.CheckTypeSize( context ", " type_name ", [" header ", " language ", " expect ])
7056 .IR sconf .CheckTypeSize( type_name ", [" header ", " language ", " expect ])
7057 Checks for the size of a type defined by
7060 specifies the typedef name to check for.
7063 argument is a string
7067 that will be compiled
7068 to check if the function exists;
7069 the default is empty.
7076 and selects the compiler to be used for the check;
7080 argument should be an integer.
7081 If this argument is used,
7082 the function will only check whether the type
7083 given in type_name has the expected size (in bytes).
7085 .B "CheckTypeSize('short', expect = 2)"
7086 will return success only if short is two bytes.
7092 .RI SConf.CheckDeclaration( context ", " symbol ", [" includes ", " language ])
7094 .IR sconf .CheckDeclaration( symbol ", [" includes ", " language ])
7095 Checks if the specified
7099 is a string containing one or more
7101 lines that will be inserted into the program
7102 that will be run to test for the existence of the type.
7109 and selects the compiler to be used for the check;
7113 .RI SConf.Define( context ", " symbol ", [" value ", " comment ])
7115 .IR sconf .Define( symbol ", [" value ", " comment ])
7116 This function does not check for anything, but defines a
7117 preprocessor symbol that will be added to the configuration header file.
7118 It is the equivalent of AC_DEFINE,
7119 and defines the symbol
7123 and the optional comment
7131 conf = Configure( env )
7133 # Puts the following line in the config header file:
7135 conf.Define('A_SYMBOL')
7137 # Puts the following line in the config header file:
7138 # #define A_SYMBOL 1
7139 conf.Define('A_SYMBOL', 1)
7143 Be careful about quoting string values, though:
7147 conf = Configure( env )
7149 # Puts the following line in the config header file:
7150 # #define A_SYMBOL YA
7151 conf.Define('A_SYMBOL', "YA")
7153 # Puts the following line in the config header file:
7154 # #define A_SYMBOL "YA"
7155 conf.Define('A_SYMBOL', '"YA"')
7163 conf = Configure( env )
7165 # Puts the following lines in the config header file:
7166 # /* Set to 1 if you have a symbol */
7167 # #define A_SYMBOL 1
7168 conf.Define('A_SYMBOL', 1, 'Set to 1 if you have a symbol')
7172 You can define your own custom checks.
7173 in addition to the predefined checks.
7174 These are passed in a dictionary to the Configure function.
7175 This dictionary maps the names of the checks
7176 to user defined Python callables
7177 (either Python functions or class instances implementing the
7180 The first argument of the call is always a
7182 instance followed by the arguments,
7183 which must be supplied by the user of the check.
7184 These CheckContext instances define the following methods:
7187 .RI CheckContext.Message( self ", " text )
7189 Usually called before the check is started.
7191 will be displayed to the user, e.g. 'Checking for library X...'
7194 .RI CheckContext.Result( self, ", " res )
7196 Usually called after the check is done.
7198 can be either an integer or a string. In the former case, 'yes' (res != 0)
7199 or 'no' (res == 0) is displayed to the user, in the latter case the
7200 given string is displayed.
7203 .RI CheckContext.TryCompile( self ", " text ", " extension )
7204 Checks if a file with the specified
7206 (e.g. '.c') containing
7208 can be compiled using the environment's
7210 builder. Returns 1 on success and 0 on failure.
7213 .RI CheckContext.TryLink( self ", " text ", " extension )
7214 Checks, if a file with the specified
7216 (e.g. '.c') containing
7218 can be compiled using the environment's
7220 builder. Returns 1 on success and 0 on failure.
7223 .RI CheckContext.TryRun( self ", " text ", " extension )
7224 Checks, if a file with the specified
7226 (e.g. '.c') containing
7228 can be compiled using the environment's
7230 builder. On success, the program is run. If the program
7231 executes successfully
7232 (that is, its return status is 0),
7237 is the standard output of the
7239 If the program fails execution
7240 (its return status is non-zero),
7241 then (0, '') is returned.
7244 .RI CheckContext.TryAction( self ", " action ", [" text ", " extension ])
7245 Checks if the specified
7247 with an optional source file (contents
7254 may be anything which can be converted to a
7261 is the content of the target file.
7267 .RI CheckContext.TryBuild( self ", " builder ", [" text ", " extension ])
7268 Low level implementation for testing specific builds;
7269 the methods above are based on this method.
7270 Given the Builder instance
7274 of a source file with optional
7276 this method returns 1 on success and 0 on failure. In addition,
7278 is set to the build target node, if the build was successful.
7281 Example for implementing and using custom tests:
7284 def CheckQt(context, qtdir):
7285 context.Message( 'Checking for qt ...' )
7286 lastLIBS = context.env['LIBS']
7287 lastLIBPATH = context.env['LIBPATH']
7288 lastCPPPATH= context.env['CPPPATH']
7289 context.env.Append(LIBS = 'qt', LIBPATH = qtdir + '/lib', CPPPATH = qtdir + '/include' )
7290 ret = context.TryLink("""
7292 int main(int argc, char **argv) {
7293 QApplication qapp(argc, argv);
7298 context.env.Replace(LIBS = lastLIBS, LIBPATH=lastLIBPATH, CPPPATH=lastCPPPATH)
7299 context.Result( ret )
7303 conf = Configure( env, custom_tests = { 'CheckQt' : CheckQt } )
7304 if not conf.CheckQt('/usr/lib/qt'):
7305 print 'We really need qt!'
7310 .SS Command-Line Construction Variables
7312 Often when building software,
7313 some variables must be specified at build time.
7314 For example, libraries needed for the build may be in non-standard
7315 locations, or site-specific compiler options may need to be passed to the
7320 object to support overriding construction variables
7321 on the command line:
7323 $ scons VARIABLE=foo
7325 The variable values can also be specified in a text-based SConscript file.
7326 To create a Variables object, call the Variables() function:
7329 .RI Variables([ files "], [" args ])
7330 This creates a Variables object that will read construction variables from
7331 the file or list of filenames specified in
7333 If no files are specified,
7338 then no files will be read.
7339 The optional argument
7342 values that will override anything read from the specified files;
7343 it is primarily intended to be passed the
7345 dictionary that holds variables
7346 specified on the command line.
7350 vars = Variables('custom.py')
7351 vars = Variables('overrides.py', ARGUMENTS)
7352 vars = Variables(None, {FOO:'expansion', BAR:7})
7355 Variables objects have the following methods:
7358 .RI Add( key ", [" help ", " default ", " validator ", " converter ])
7359 This adds a customizable construction variable to the Variables object.
7361 is the name of the variable.
7363 is the help text for the variable.
7365 is the default value of the variable;
7366 if the default value is
7368 and there is no explicit value specified,
7369 the construction variable will
7371 be added to the construction environment.
7373 is called to validate the value of the variable, and should take three
7374 arguments: key, value, and environment.
7375 The recommended way to handle an invalid value is
7376 to raise an exception (see example below).
7378 is called to convert the value before putting it in the environment, and
7379 should take either a value, or the value and environment, as parameters.
7382 must return a value,
7383 which will be converted into a string
7384 before being validated by the
7387 and then added to the environment.
7392 vars.Add('CC', 'The C compiler')
7394 def validate_color(key, val, env):
7395 if not val in ['red', 'blue', 'yellow']:
7396 raise "Invalid color value '%s'" % val
7397 vars.Add('COLOR', validator=valid_color)
7401 .RI AddVariables( list )
7402 A wrapper script that adds
7403 multiple customizable construction variables
7404 to a Variables object.
7406 is a list of tuple or list objects
7407 that contain the arguments
7408 for an individual call to the
7415 ('CC', 'The C compiler'),
7416 ('VALIDATE', 'An option for testing validation',
7417 'notset', validator, None),
7422 .RI Update( env ", [" args ])
7423 This updates a construction environment
7425 with the customized construction variables.
7426 Any specified variables that are
7428 configured for the Variables object
7429 will be saved and may be
7431 .BR UnknownVariables ()
7434 Normally this method is not called directly,
7435 but is called indirectly by passing the Variables object to
7436 the Environment() function:
7439 env = Environment(variables=vars)
7443 The text file(s) that were specified
7444 when the Variables object was created
7445 are executed as Python scripts,
7446 and the values of (global) Python variables set in the file
7447 are added to the construction environment.
7456 .RI UnknownVariables( )
7457 Returns a dictionary containing any
7458 variables that were specified
7459 either in the files or the dictionary
7460 with which the Variables object was initialized,
7461 but for which the Variables object was
7465 env = Environment(variables=vars)
7466 for key, value in vars.UnknownVariables():
7467 print "unknown variable: %s=%s" % (key, value)
7471 .RI Save( filename ", " env )
7472 This saves the currently set variables into a script file named
7474 that can be used on the next invocation to automatically load the current
7475 settings. This method combined with the Variables method can be used to
7476 support caching of variables between runs.
7480 vars = Variables(['variables.cache', 'custom.py'])
7483 vars.Save('variables.cache', env)
7487 .RI GenerateHelpText( env ", [" sort ])
7488 This generates help text documenting the customizable construction
7489 variables suitable to passing in to the Help() function.
7491 is the construction environment that will be used to get the actual values
7492 of customizable variables. Calling with
7496 will cause the output to be sorted
7497 by the specified argument.
7501 should take two arguments
7504 (like the standard Python
7509 Help(vars.GenerateHelpText(env))
7510 Help(vars.GenerateHelpText(env, sort=cmp))
7514 .RI FormatVariableHelpText( env ", " opt ", " help ", " default ", " actual )
7515 This method returns a formatted string
7516 containing the printable help text
7518 It is normally not called directly,
7519 but is called by the
7520 .IR GenerateHelpText ()
7521 method to create the returned help text.
7522 It may be overridden with your own
7523 function that takes the arguments specified above
7524 and returns a string of help text formatted to your liking.
7526 .IR GenerateHelpText ()
7527 will not put any blank lines or extra
7528 characters in between the entries,
7529 so you must add those characters to the returned
7530 string if you want the entries separated.
7533 def my_format(env, opt, help, default, actual):
7534 fmt = "\n%s: default=%s actual=%s (%s)\n"
7535 return fmt % (opt, default. actual, help)
7536 vars.FormatVariableHelpText = my_format
7539 To make it more convenient to work with customizable Variables,
7541 provides a number of functions
7542 that make it easy to set up
7543 various types of Variables:
7546 .RI BoolVariable( key ", " help ", " default )
7547 Return a tuple of arguments
7548 to set up a Boolean option.
7552 have a default value of
7554 and display the specified
7557 The option will interpret the values
7579 .RI EnumVariable( key ", " help ", " default ", " allowed_values ", [" map ", " ignorecase ])
7580 Return a tuple of arguments
7582 whose value may be one
7583 of a specified list of legal enumerated values.
7587 have a default value of
7589 and display the specified
7592 The option will only support those
7598 argument is a dictionary
7599 that can be used to convert
7600 input values into specific legal values
7609 then the values are case-sensitive.
7614 then values will be matched
7620 then values will be matched
7622 and all input values will be
7623 converted to lower case.
7626 .RI ListVariable( key ", " help ", " default ", " names ", [", map ])
7627 Return a tuple of arguments
7629 whose value may be one or more
7630 of a specified list of legal enumerated values.
7634 have a default value of
7636 and display the specified
7639 The option will only support the values
7642 or the values in the
7645 More than one value may be specified,
7646 with all values separated by commas.
7647 The default may be a string of
7648 comma-separated default values,
7649 or a list of the default values.
7652 argument is a dictionary
7653 that can be used to convert
7654 input values into specific legal values
7660 .RI PackageVariable( key ", " help ", " default )
7661 Return a tuple of arguments
7663 whose value is a path name
7664 of a package that may be
7665 enabled, disabled or
7666 given an explicit path name.
7670 have a default value of
7672 and display the specified
7675 The option will support the values
7682 in which case the specified
7685 or the option may be set to an
7687 (typically the path name to a package
7688 that is being enabled).
7689 The option will also support the values
7695 to disable use of the specified option.
7698 .RI PathVariable( key ", " help ", " default ", [" validator ])
7699 Return a tuple of arguments
7701 whose value is expected to be a path name.
7705 have a default value of
7707 and display the specified
7713 that will be called to
7714 verify that the specified path
7717 following ready-made validators:
7718 .BR PathVariable.PathExists
7720 which verifies that the specified path exists;
7721 .BR PathVariable.PathIsFile ,
7722 which verifies that the specified path is an existing file;
7723 .BR PathVariable.PathIsDir ,
7724 which verifies that the specified path is an existing directory;
7725 .BR PathVariable.PathIsDirCreate ,
7726 which verifies that the specified path is a directory
7727 and will create the specified directory if the path does not exist;
7729 .BR PathVariable.PathAccept ,
7730 which simply accepts the specific path name argument without validation,
7731 and which is suitable if you want your users
7732 to be able to specify a directory path that will be
7733 created as part of the build process, for example.
7734 You may supply your own
7737 which must take three arguments
7739 the name of the variable to be set;
7741 the specified value being checked;
7744 the construction environment)
7745 and should raise an exception
7746 if the specified value is not acceptable.
7749 These functions make it
7750 convenient to create a number
7751 of variables with consistent behavior
7752 in a single call to the
7758 BoolVariable('warnings', 'compilation with -Wall and similiar', 1),
7759 EnumVariable('debug', 'debug output and symbols', 'no'
7760 allowed_values=('yes', 'no', 'full'),
7761 map={}, ignorecase=0), # case sensitive
7762 ListVariable('shared',
7763 'libraries to build as shared libraries',
7765 names = list_of_libs),
7766 PackageVariable('x11',
7767 'use X11 installed here (yes = search some places)',
7769 PathVariable('qtdir', 'where the root of Qt is installed', qtdir),
7770 PathVariable('foopath', 'where the foo library is installed', foopath,
7771 PathVariable.PathIsDir),
7776 .SS File and Directory Nodes
7786 Nodes, respectively.
7787 python objects, respectively.
7788 Those objects have several user-visible attributes
7789 and methods that are often useful:
7795 This path is relative to the top-level directory
7799 The build path is the same as the source path if
7804 The absolute build path of the given file or directory.
7814 object representing the
7823 # Get the current build dir's path, relative to top.
7825 # Current dir's absolute path
7827 # Next line is always '.', because it is the top dir's path relative to itself.
7829 File('foo.c').srcnode().path # source path of the given source file.
7831 # Builders also return File objects:
7832 foo = env.Program('foo.c')
7833 print "foo will be built in %s"%foo.path
7840 Node can also be used to create
7841 file and subdirectory Nodes relative to the generating Node.
7844 Node will place the new Nodes within the directory it represents.
7847 node will place the new Nodes within its parent directory
7848 (that is, "beside" the file in question).
7853 (directory) Node and
7858 then these methods are available:
7862 Returns a directory Node for a subdirectory of
7869 Returns a file Node for a file within
7875 .IR d .Entry( name )
7876 Returns an unresolved Node within
7883 Returns a directory named
7885 within the parent directory of
7890 Returns a file named
7892 within the parent directory of
7896 .IR f .Entry( name )
7897 Returns an unresolved Node named
7899 within the parent directory of
7906 # Get a Node for a file within a directory
7907 incl = Dir('include')
7908 f = incl.File('header.h')
7910 # Get a Node for a subdirectory within a directory
7911 dist = Dir('project-3.2.1)
7912 src = dist.Dir('src')
7914 # Get a Node for a file in the same directory
7915 cfile = File('sample.c')
7916 hfile = cfile.File('sample.h')
7920 html = docs.Dir('html')
7921 index = html.File('index.html')
7922 css = index.File('app.css')
7928 can be extended to build different types of targets
7929 by adding new Builder objects
7930 to a construction environment.
7932 you should only need to add a new Builder object
7933 when you want to build a new type of file or other external target.
7934 If you just want to invoke a different compiler or other tool
7935 to build a Program, Object, Library, or any other
7936 type of output file for which
7938 already has an existing Builder,
7939 it is generally much easier to
7940 use those existing Builders
7941 in a construction environment
7942 that sets the appropriate construction variables
7945 Builder objects are created
7951 function accepts the following arguments:
7954 The command line string used to build the target from the source.
7957 a list of strings representing the command
7958 to be executed and its arguments
7959 (suitable for enclosing white space in an argument),
7961 mapping source file name suffixes to
7962 any combination of command line strings
7963 (if the builder should accept multiple source file extensions),
7966 (see the next section);
7967 or a list of any of the above.
7970 takes three arguments:
7972 - a list of source nodes,
7974 - a list of target nodes,
7976 - the construction environment.
7979 The prefix that will be prepended to the target file name.
7980 This may be specified as a:
7990 - a function or other callable that takes
7991 two arguments (a construction environment and a list of sources)
7992 and returns a prefix,
7997 - specifies a mapping from a specific source suffix (of the first
7998 source specified) to a corresponding target prefix. Both the source
7999 suffix and target prefix specifications may use environment variable
8000 substitution, and the target prefix (the 'value' entries in the
8001 dictionary) may also be a callable object. The default target prefix
8002 may be indicated by a dictionary entry with a key value of None.
8007 b = Builder("build_it < $SOURCE > $TARGET",
8010 def gen_prefix(env, sources):
8011 return "file-" + env['PLATFORM'] + '-'
8012 b = Builder("build_it < $SOURCE > $TARGET",
8013 prefix = gen_prefix)
8015 b = Builder("build_it < $SOURCE > $TARGET",
8016 suffix = { None: "file-",
8017 "$SRC_SFX_A": gen_prefix })
8021 The suffix that will be appended to the target file name.
8022 This may be specified in the same manner as the prefix above.
8023 If the suffix is a string, then
8025 will append a '.' to the beginning of the suffix if it's not already
8026 there. The string returned by callable object (or obtained from the
8027 dictionary) is untouched and must append its own '.' to the beginning
8031 b = Builder("build_it < $SOURCE > $TARGET"
8034 def gen_suffix(env, sources):
8035 return "." + env['PLATFORM'] + "-file"
8036 b = Builder("build_it < $SOURCE > $TARGET",
8037 suffix = gen_suffix)
8039 b = Builder("build_it < $SOURCE > $TARGET",
8040 suffix = { None: ".sfx1",
8041 "$SRC_SFX_A": gen_suffix })
8045 When set to any true value, causes
8047 to add the target suffix specified by the
8049 keyword to any target strings
8050 that have a different suffix.
8051 (The default behavior is to leave untouched
8052 any target file name that looks like it already has any suffix.)
8055 b1 = Builder("build_it < $SOURCE > $TARGET"
8057 b2 = Builder("build_it < $SOURCE > $TARGET"
8061 env['BUILDERS']['B1'] = b1
8062 env['BUILDERS']['B2'] = b2
8064 # Builds "foo.txt" because ensure_suffix is not set.
8065 env.B1('foo.txt', 'foo.in')
8067 # Builds "bar.txt.out" because ensure_suffix is set.
8068 env.B2('bar.txt', 'bar.in')
8072 The expected source file name suffix. This may be a string or a list
8076 A Scanner object that
8077 will be invoked to find
8078 implicit dependencies for this target file.
8079 This keyword argument should be used
8080 for Scanner objects that find
8081 implicit dependencies
8082 based only on the target file
8083 and the construction environment,
8086 (See the section "Scanner Objects," below,
8087 for information about creating Scanner objects.)
8090 A Scanner object that
8092 find implicit dependences in
8094 used to build this target file.
8095 This is where you would
8096 specify a scanner to
8099 lines in source files.
8102 Scanner object may be used to
8103 indicate that this Builder
8104 should scan directory trees
8105 for on-disk changes to files
8108 does not know about from other Builder or function calls.
8109 (See the section "Scanner Objects," below,
8110 for information about creating your own Scanner objects.)
8113 A factory function that the Builder will use
8114 to turn any targets specified as strings into SCons Nodes.
8116 SCons assumes that all targets are files.
8117 Other useful target_factory
8120 for when a Builder creates a directory target,
8123 for when a Builder can create either a file
8124 or directory target.
8129 MakeDirectoryBuilder = Builder(action=my_mkdir, target_factory=Dir)
8131 env.Append(BUILDERS = {'MakeDirectory':MakeDirectoryBuilder})
8132 env.MakeDirectory('new_directory', [])
8136 Note that the call to the MakeDirectory Builder
8137 needs to specify an empty source list
8138 to make the string represent the builder's target;
8139 without that, it would assume the argument is the source,
8140 and would try to deduce the target name from it,
8141 which in the absence of an automatically-added prefix or suffix
8142 would lead to a matching target and source name
8143 and a circular dependency.
8146 A factory function that the Builder will use
8147 to turn any sources specified as strings into SCons Nodes.
8149 SCons assumes that all source are files.
8150 Other useful source_factory
8153 for when a Builder uses a directory as a source,
8156 for when a Builder can use files
8157 or directories (or both) as sources.
8162 CollectBuilder = Builder(action=my_mkdir, source_factory=Entry)
8164 env.Append(BUILDERS = {'Collect':CollectBuilder})
8165 env.Collect('archive', ['directory_name', 'file_name'])
8169 A function or list of functions to manipulate the target and source
8170 lists before dependencies are established
8171 and the target(s) are actually built.
8173 can also be a string containing a construction variable to expand
8174 to an emitter function or list of functions,
8175 or a dictionary mapping source file suffixes
8176 to emitter functions.
8177 (Only the suffix of the first source file
8178 is used to select the actual emitter function
8179 from an emitter dictionary.)
8182 takes three arguments:
8184 - a list of source nodes,
8186 - a list of target nodes,
8188 - the construction environment.
8189 An emitter must return a tuple containing two lists,
8190 the list of targets to be built by this builder,
8191 and the list of sources for this builder.
8196 def e(target, source, env):
8197 return (target + ['foo.foo'], source + ['foo.src'])
8199 # Simple association of an emitter function with a Builder.
8200 b = Builder("my_build < $TARGET > $SOURCE",
8203 def e2(target, source, env):
8204 return (target + ['bar.foo'], source + ['bar.src'])
8206 # Simple association of a list of emitter functions with a Builder.
8207 b = Builder("my_build < $TARGET > $SOURCE",
8210 # Calling an emitter function through a construction variable.
8211 env = Environment(MY_EMITTER = e)
8212 b = Builder("my_build < $TARGET > $SOURCE",
8213 emitter = '$MY_EMITTER')
8215 # Calling a list of emitter functions through a construction variable.
8216 env = Environment(EMITTER_LIST = [e, e2])
8217 b = Builder("my_build < $TARGET > $SOURCE",
8218 emitter = '$EMITTER_LIST')
8220 # Associating multiple emitters with different file
8221 # suffixes using a dictionary.
8222 def e_suf1(target, source, env):
8223 return (target + ['another_target_file'], source)
8224 def e_suf2(target, source, env):
8225 return (target, source + ['another_source_file'])
8226 b = Builder("my_build < $TARGET > $SOURCE",
8227 emitter = {'.suf1' : e_suf1,
8232 Specifies whether this builder is allowed to be called multiple times for
8233 the same target file(s). The default is 0, which means the builder
8234 can not be called multiple times for the same target file(s). Calling a
8235 builder multiple times for the same target simply adds additional source
8236 files to the target; it is not allowed to change the environment associated
8237 with the target, specify addition environment overrides, or associate a different
8238 builder with the target.
8241 A construction environment that can be used
8242 to fetch source code using this Builder.
8243 (Note that this environment is
8245 used for normal builds of normal target files,
8246 which use the environment that was
8247 used to call the Builder for the target file.)
8250 A function that returns a list of actions that will be executed to build
8251 the target(s) from the source(s).
8252 The returned action(s) may be
8253 an Action object, or anything that
8254 can be converted into an Action object
8255 (see the next section).
8257 The generator function
8258 takes four arguments:
8260 - a list of source nodes,
8262 - a list of target nodes,
8264 - the construction environment,
8266 - a Boolean value that specifies
8267 whether the generator is being called
8268 for generating a build signature
8269 (as opposed to actually executing the command).
8273 def g(source, target, env, for_signature):
8274 return [["gcc", "-c", "-o"] + target + source]
8276 b = Builder(generator=g)
8284 arguments must not both be used for the same Builder.
8287 Specifies a builder to use when a source file name suffix does not match
8288 any of the suffixes of the builder. Using this argument produces a
8289 multi-stage builder.
8292 Specifies that this builder expects exactly one source file per call. Giving
8293 more than one source file without target files results in implicitely calling
8294 the builder multiple times (once for each source given). Giving multiple
8295 source files together with target files results in a UserError exception.
8303 arguments must not both be used for the same Builder.
8305 .IP source_ext_match
8308 argument is a dictionary,
8309 the default behavior when a builder is passed
8310 multiple source files is to make sure that the
8311 extensions of all the source files match.
8312 If it is legal for this builder to be
8313 called with a list of source files with different extensions,
8314 this check can be suppressed by setting
8318 or some other non-true value.
8323 will use the suffix of the first specified
8324 source file to select the appropriate action from the
8328 In the following example,
8333 from exiting with an error
8334 due to the mismatched suffixes of
8340 b = Builder(action={'.in' : 'build $SOURCES > $TARGET'},
8341 source_ext_match = None)
8343 env = Environment(BUILDERS = {'MyBuild':b})
8344 env.MyBuild('foo.out', ['foo.in', 'foo.extra'])
8348 A construction environment that can be used
8349 to fetch source code using this Builder.
8350 (Note that this environment is
8352 used for normal builds of normal target files,
8353 which use the environment that was
8354 used to call the Builder for the target file.)
8357 b = Builder(action="build < $SOURCE > $TARGET")
8358 env = Environment(BUILDERS = {'MyBuild' : b})
8359 env.MyBuild('foo.out', 'foo.in', my_arg = 'xyzzy')
8363 A directory from which scons
8370 a string or a directory Node,
8371 scons will change to the specified directory.
8374 is not a string or Node
8376 then scons will change to the
8377 target file's directory.
8379 Note that scons will
8381 automatically modify
8383 construction variables like
8387 when using the chdir
8388 keyword argument--that is,
8389 the expanded file names
8390 will still be relative to
8391 the top-level SConstruct directory,
8392 and consequently incorrect
8393 relative to the chdir directory.
8394 Builders created using chdir keyword argument,
8395 will need to use construction variable
8400 to use just the filename portion of the
8404 b = Builder(action="build < ${SOURCE.file} > ${TARGET.file}",
8406 env = Environment(BUILDERS = {'MyBuild' : b})
8407 env.MyBuild('sub/dir/foo.out', 'sub/dir/foo.in')
8411 Python only keeps one current directory
8412 location for all of the threads.
8413 This means that use of the
8421 because individual worker threads spawned
8422 by SCons interfere with each other
8423 when they start changing directory.
8426 Any additional keyword arguments supplied
8427 when a Builder object is created
8428 (that is, when the Builder() function is called)
8429 will be set in the executing construction
8430 environment when the Builder object is called.
8431 The canonical example here would be
8432 to set a construction variable to
8433 the repository of a source code system.
8435 Any additional keyword arguments supplied
8439 will only be associated with the target
8440 created by that particular Builder call
8441 (and any other files built as a
8442 result of the call).
8444 These extra keyword arguments are passed to the
8445 following functions:
8446 command generator functions,
8448 and emitter functions.
8454 function will turn its
8456 keyword argument into an appropriate
8457 internal Action object.
8458 You can also explicity create Action objects
8462 which can then be passed to the
8465 This can be used to configure
8466 an Action object more flexibly,
8467 or it may simply be more efficient
8468 than letting each separate Builder object
8469 create a separate Action
8471 Builder objects need to do the same thing.
8476 returns an appropriate object for the action
8477 represented by the type of the first argument:
8480 If the first argument is already an Action object,
8481 the object is simply returned.
8484 If the first argument is a string,
8485 a command-line Action is returned.
8486 Note that the command-line string
8487 may be preceded by an
8490 to suppress printing of the specified command line,
8494 to ignore the exit status from the specified command:
8497 Action('$CC -c -o $TARGET $SOURCES')
8499 # Doesn't print the line being executed.
8500 Action('@build $TARGET $SOURCES')
8502 # Ignores return value
8503 Action('-build $TARGET $SOURCES')
8505 .\" XXX From Gary Ruben, 23 April 2002:
8506 .\" What would be useful is a discussion of how you execute command
8507 .\" shell commands ie. what is the process used to spawn the shell, pass
8508 .\" environment variables to it etc., whether there is one shell per
8509 .\" environment or one per command etc. It might help to look at the Gnu
8510 .\" make documentation to see what they think is important to discuss about
8511 .\" a build system. I'm sure you can do a better job of organising the
8512 .\" documentation than they have :-)
8515 If the first argument is a list,
8516 then a list of Action objects is returned.
8517 An Action object is created as necessary
8518 for each element in the list.
8521 the list is itself a list,
8522 the internal list is the
8523 command and arguments to be executed via
8525 This allows white space to be enclosed
8526 in an argument by defining
8527 a command in a list within a list:
8530 Action([['cc', '-c', '-DWHITE SPACE', '-o', '$TARGET', '$SOURCES']])
8534 If the first argument is a Python function,
8535 a function Action is returned.
8536 The Python function must take three keyword arguments,
8538 (a Node object representing the target file),
8540 (a Node object representing the source file)
8543 (the construction environment
8544 used for building the target file).
8549 arguments may be lists of Node objects if there is
8550 more than one target file or source file.
8551 The actual target and source file name(s) may
8552 be retrieved from their Node objects
8553 via the built-in Python str() function:
8556 target_file_name = str(target)
8557 source_file_names = map(lambda x: str(x), source)
8560 The function should return
8564 to indicate a successful build of the target file(s).
8565 The function may raise an exception
8566 or return a non-zero exit status
8567 to indicate an unsuccessful build.
8570 def build_it(target = None, source = None, env = None):
8571 # build the target from the source
8574 a = Action(build_it)
8577 If the action argument is not one of the above,
8581 The second argument is optional and is used to define the output
8582 which is printed when the Action is actually performed.
8583 In the absence of this parameter,
8584 or if it's an empty string,
8585 a default output depending on the type of the action is used.
8586 For example, a command-line action will print the executed command.
8587 The argument must be either a Python function or a string.
8590 it's a function that returns a string to be printed
8591 to describe the action being executed.
8592 The function may also be specified by the
8595 Like a function to build a file,
8596 this function must take three keyword arguments:
8598 (a Node object representing the target file),
8600 (a Node object representing the source file)
8603 (a construction environment).
8608 arguments may be lists of Node objects if there is
8609 more than one target file or source file.
8611 In the second case, you provide the string itself.
8612 The string may also be specified by the
8615 The string typically contains variables, notably
8616 $TARGET(S) and $SOURCE(S), or consists of just a single
8617 variable, which is optionally defined somewhere else.
8618 SCons itself heavily uses the latter variant.
8623 def build_it(target, source, env):
8624 # build the target from the source
8627 def string_it(target, source, env):
8628 return "building '%s' from '%s'" % (target[0], source[0])
8630 # Use a positional argument.
8631 f = Action(build_it, string_it)
8632 s = Action(build_it, "building '$TARGET' from '$SOURCE'")
8634 # Alternatively, use a keyword argument.
8635 f = Action(build_it, strfunction=string_it)
8636 s = Action(build_it, cmdstr="building '$TARGET' from '$SOURCE'")
8638 # You can provide a configurable variable.
8639 l = Action(build_it, '$STRINGIT')
8642 The third and succeeding arguments, if present,
8643 may either be a construction variable or a list of construction variables
8644 whose values will be included in the signature of the Action
8645 when deciding whether a target should be rebuilt because the action changed.
8646 The variables may also be specified by a
8649 if both are present, they are combined.
8650 This is necessary whenever you want a target to be rebuilt
8651 when a specific construction variable changes.
8652 This is not often needed for a string action,
8653 as the expanded variables will normally be part of the command line,
8654 but may be needed if a Python function action uses
8655 the value of a construction variable when generating the command line.
8658 def build_it(target, source, env):
8659 # build the target from the 'XXX' construction variable
8660 open(target[0], 'w').write(env['XXX'])
8663 # Use positional arguments.
8664 a = Action(build_it, '$STRINGIT', ['XXX'])
8666 # Alternatively, use a keyword argument.
8667 a = Action(build_it, varlist=['XXX'])
8673 can be passed the following
8674 optional keyword arguments
8675 to modify the Action object's behavior:
8681 keyword argument specifies that
8682 scons will execute the action
8683 after changing to the specified directory.
8687 a string or a directory Node,
8688 scons will change to the specified directory.
8692 is not a string or Node
8694 then scons will change to the
8695 target file's directory.
8697 Note that scons will
8699 automatically modify
8701 construction variables like
8705 when using the chdir
8706 keyword argument--that is,
8707 the expanded file names
8708 will still be relative to
8709 the top-level SConstruct directory,
8710 and consequently incorrect
8711 relative to the chdir directory.
8712 Builders created using chdir keyword argument,
8713 will need to use construction variable
8718 to use just the filename portion of the
8722 a = Action("build < ${SOURCE.file} > ${TARGET.file}",
8734 which specifies a function
8735 that is passed the exit status
8737 from the specified action
8738 and can return an arbitrary
8740 This can be used, for example,
8741 to specify that an Action object's
8742 return value should be ignored
8743 under special conditions
8744 and SCons should, therefore,
8745 consider that the action always suceeds:
8748 def always_succeed(s):
8749 # Always return 0, which indicates success.
8751 a = Action("build < ${SOURCE.file} > ${TARGET.file}",
8752 exitstatfunc=always_succeed)
8759 keyword argument can be used
8760 to specify that the Action can create multiple target files
8761 by processing multiple independent source files simultaneously.
8762 (The canonical example is "batch compilation"
8763 of multiple object files
8764 by passing multiple source files
8765 to a single invocation of a compiler
8766 such as Microsoft's Visual C / C++ compiler.)
8769 argument is any non-False, non-callable Python value,
8770 the configured Action object will cause
8772 to collect all targets built with the Action object
8773 and configured with the same construction environment
8774 into single invocations of the Action object's
8775 command line or function.
8776 Command lines will typically want to use the
8778 construction variable
8782 to only pass to the command line those sources that
8783 have actually changed since their targets were built.
8788 a = Action('build $CHANGED_SOURCES', batch_key=True)
8793 argument may also be
8795 that returns a key that
8796 will be used to identify different
8797 "batches" of target files to be collected
8801 function must take the following arguments:
8807 The construction environment
8808 configured for the target.
8811 The list of targets for a particular configured action.
8814 The list of source for a particular configured action.
8816 The returned key should typically
8817 be a tuple of values derived from the arguments,
8818 using any appropriate logic to decide
8819 how multiple invocations should be batched.
8822 function may decide to return
8823 the value of a specific construction
8829 to batch-build targets
8830 with matching values of that variable,
8831 or perhaps return the
8833 of the entire construction environment,
8837 all targets configured with the same construction environment.
8841 the particular target should
8843 be part of any batched build,
8844 but instead will be built
8845 by a separate invocation of action's
8846 command or function.
8850 def batch_key(action, env, target, source):
8851 tdir = target[0].dir
8852 if tdir.name == 'special':
8853 # Don't batch-build any target
8854 # in the special/ subdirectory.
8856 return (id(action), id(env), tdir)
8857 a = Action('build $CHANGED_SOURCES', batch_key=batch_key)
8860 .SS Miscellaneous Action Functions
8863 supplies a number of functions
8864 that arrange for various common
8865 file and directory manipulations
8867 These are similar in concept to "tasks" in the
8869 although the implementation is slightly different.
8870 These functions do not actually
8871 perform the specified action
8872 at the time the function is called,
8873 but instead return an Action object
8874 that can be executed at the
8876 (In Object-Oriented terminology,
8881 that return Action objects.)
8884 there are two natural ways
8887 are intended to be used.
8891 to perform the action
8892 at the time the SConscript
8896 global function to do so:
8898 Execute(Touch('file'))
8902 you can use these functions
8903 to supply Actions in a list
8907 This can allow you to
8908 perform more complicated
8909 sequences of file manipulation
8911 on platform-specific
8915 env = Environment(TMPBUILD = '/tmp/builddir')
8916 env.Command('foo.out', 'foo.in',
8917 [Mkdir('$TMPBUILD'),
8918 Copy('$TMPBUILD', '${SOURCE.dir}'),
8919 "cd $TMPBUILD && make",
8920 Delete('$TMPBUILD')])
8924 .RI Chmod( dest ", " mode )
8925 Returns an Action object that
8926 changes the permissions on the specified
8928 file or directory to the specified
8933 Execute(Chmod('file', 0755))
8935 env.Command('foo.out', 'foo.in',
8936 [Copy('$TARGET', '$SOURCE'),
8937 Chmod('$TARGET', 0755)])
8941 .RI Copy( dest ", " src )
8942 Returns an Action object
8945 source file or directory to the
8947 destination file or directory.
8951 Execute(Copy('foo.output', 'foo.input'))
8953 env.Command('bar.out', 'bar.in',
8954 Copy('$TARGET', '$SOURCE'))
8958 .RI Delete( entry ", [" must_exist ])
8959 Returns an Action that
8960 deletes the specified
8962 which may be a file or a directory tree.
8963 If a directory is specified,
8964 the entire directory tree
8969 then a Python error will be thrown
8970 if the specified entry does not exist;
8973 that is, the Action will silently do nothing
8974 if the entry does not exist.
8978 Execute(Delete('/tmp/buildroot'))
8980 env.Command('foo.out', 'foo.in',
8981 [Delete('${TARGET.dir}'),
8984 Execute(Delete('file_that_must_exist', must_exist=1))
8990 that creates the specified
8996 Execute(Mkdir('/tmp/outputdir'))
8998 env.Command('foo.out', 'foo.in',
8999 [Mkdir('/tmp/builddir'),
9000 Copy('/tmp/builddir/foo.in', '$SOURCE'),
9001 "cd /tmp/builddir && make",
9002 Copy('$TARGET', '/tmp/builddir/foo.out')])
9006 .RI Move( dest ", " src )
9008 that moves the specified
9010 file or directory to
9017 Execute(Move('file.destination', 'file.source'))
9019 env.Command('output_file', 'input_file',
9021 Move('$TARGET', 'file_created_by_MyBuildAction')])
9027 that updates the modification time
9033 Execute(Touch('file_to_be_touched'))
9035 env.Command('marker', 'input_file',
9040 .SS Variable Substitution
9042 Before executing a command,
9044 performs construction variable interpolation on the strings that make up
9045 the command line of builders.
9046 Variables are introduced by a
9049 Besides construction variables, scons provides the following
9050 variables for each command execution:
9053 The file names of all sources of the build command
9054 that have changed since the target was last built.
9057 The file names of all targets that would be built
9058 from sources that have changed since the target was last built.
9061 The file name of the source of the build command,
9062 or the file name of the first source
9063 if multiple sources are being built.
9066 The file names of the sources of the build command.
9069 The file name of the target being built,
9070 or the file name of the first target
9071 if multiple targets are being built.
9074 The file names of all targets being built.
9076 .IP UNCHANGED_SOURCES
9077 The file names of all sources of the build command
9080 changed since the target was last built.
9082 .IP UNCHANGED_TARGETS
9083 The file names of all targets that would be built
9084 from sources that have
9086 changed since the target was last built.
9088 (Note that the above variables are reserved
9089 and may not be set in a construction environment.)
9092 For example, given the construction variable CC='cc', targets=['foo'], and
9093 sources=['foo.c', 'bar.c']:
9096 action='$CC -c -o $TARGET $SOURCES'
9099 would produce the command line:
9102 cc -c -o foo foo.c bar.c
9105 Variable names may be surrounded by curly braces ({})
9106 to separate the name from the trailing characters.
9107 Within the curly braces, a variable name may have
9108 a Python slice subscript appended to select one
9109 or more items from a list.
9110 In the previous example, the string:
9122 Additionally, a variable name may
9123 have the following special
9124 modifiers appended within the enclosing curly braces
9125 to modify the interpolated string:
9128 The base path of the file name,
9129 including the directory path
9130 but excluding any suffix.
9133 The name of the directory in which the file exists.
9137 minus any directory portion.
9140 Just the basename of the file,
9142 and minus the directory.
9145 Just the file suffix.
9148 The absolute path name of the file.
9151 The POSIX form of the path,
9152 with directories separated by
9156 This is sometimes necessary on Windows systems
9157 when a path references a file on other (POSIX) systems.
9160 The directory and file name to the source file linked to this file through
9162 If this file isn't linked,
9163 it just returns the directory and filename unchanged.
9166 The directory containing the source file linked to this file through
9168 If this file isn't linked,
9169 it just returns the directory part of the filename.
9172 The directory and file name to the source file linked to this file through
9174 If the file does not exist locally but exists in a Repository,
9175 the path in the Repository is returned.
9176 If this file isn't linked, it just returns the
9177 directory and filename unchanged.
9180 The Repository directory containing the source file linked to this file through
9182 If this file isn't linked,
9183 it just returns the directory part of the filename.
9186 For example, the specified target will
9187 expand as follows for the corresponding modifiers:
9190 $TARGET => sub/dir/file.x
9191 ${TARGET.base} => sub/dir/file
9192 ${TARGET.dir} => sub/dir
9193 ${TARGET.file} => file.x
9194 ${TARGET.filebase} => file
9195 ${TARGET.suffix} => .x
9196 ${TARGET.abspath} => /top/dir/sub/dir/file.x
9198 SConscript('src/SConscript', variant_dir='sub/dir')
9199 $SOURCE => sub/dir/file.x
9200 ${SOURCE.srcpath} => src/file.x
9201 ${SOURCE.srcdir} => src
9203 Repository('/usr/repository')
9204 $SOURCE => sub/dir/file.x
9205 ${SOURCE.rsrcpath} => /usr/repository/src/file.x
9206 ${SOURCE.rsrcdir} => /usr/repository/src
9209 Note that curly braces braces may also be used
9210 to enclose arbitrary Python code to be evaluated.
9211 (In fact, this is how the above modifiers are substituted,
9212 they are simply attributes of the Python objects
9213 that represent TARGET, SOURCES, etc.)
9214 See the section "Python Code Substitution," below,
9215 for more thorough examples of
9216 how this can be used.
9218 Lastly, a variable name
9219 may be a callable Python function
9221 construction variable in the environment.
9223 take four arguments:
9225 - a list of target nodes,
9227 - a list of source nodes,
9229 - the construction environment,
9231 - a Boolean value that specifies
9232 whether the function is being called
9233 for generating a build signature.
9234 SCons will insert whatever
9235 the called function returns
9236 into the expanded string:
9239 def foo(target, source, env, for_signature):
9242 # Will expand $BAR to "bar baz"
9243 env=Environment(FOO=foo, BAR="$FOO baz")
9246 You can use this feature to pass arguments to a
9247 Python function by creating a callable class
9248 that stores one or more arguments in an object,
9249 and then uses them when the
9252 Note that in this case,
9253 the entire variable expansion must
9254 be enclosed by curly braces
9255 so that the arguments will
9256 be associated with the
9257 instantiation of the class:
9261 def __init__(self, arg):
9264 def __call__(self, target, source, env, for_signature):
9265 return self.arg + " bar"
9267 # Will expand $BAR to "my argument bar baz"
9268 env=Environment(FOO=foo, BAR="${FOO('my argument')} baz")
9272 The special pseudo-variables
9276 may be used to surround parts of a command line
9279 causing a rebuild--that is,
9280 which are not included in the signature
9281 of target files built with this command.
9286 will be removed from the command line
9287 before it is added to file signatures,
9292 will be removed before the command is executed.
9293 For example, the command line:
9296 echo Last build occurred $( $TODAY $). > $TARGET
9300 would execute the command:
9303 echo Last build occurred $TODAY. > $TARGET
9307 but the command signature added to any target files would be:
9310 echo Last build occurred . > $TARGET
9313 .SS Python Code Substitution
9315 Any python code within
9317 pairs gets evaluated by python 'eval', with the python globals set to
9318 the current environment's set of construction variables.
9319 So in the following case:
9322 env.Command('foo.out', 'foo.in',
9323 '''echo ${COND==1 and 'FOO' or 'BAR'} > $TARGET''')
9325 the command executed will be either
9333 according to the current value of env['COND'] when the command is
9334 executed. The evaluation occurs when the target is being
9335 built, not when the SConscript is being read. So if env['COND'] is changed
9336 later in the SConscript, the final value will be used.
9338 Here's a more interesting example. Note that all of COND, FOO, and
9339 BAR are environment variables, and their values are substituted into
9340 the final command. FOO is a list, so its elements are interpolated
9341 separated by spaces.
9346 env['FOO'] = ['foo1', 'foo2']
9347 env['BAR'] = 'barbar'
9348 env.Command('foo.out', 'foo.in',
9349 'echo ${COND==1 and FOO or BAR} > $TARGET')
9351 # Will execute this:
9352 # echo foo1 foo2 > foo.out
9355 SCons uses the following rules when converting construction variables into
9359 When the value is a string it is interpreted as a space delimited list of
9360 command line arguments.
9363 When the value is a list it is interpreted as a list of command line
9364 arguments. Each element of the list is converted to a string.
9367 Anything that is not a list or string is converted to a string and
9368 interpreted as a single command line argument.
9371 Newline characters (\\n) delimit lines. The newline parsing is done after
9372 all other parsing, so it is not possible for arguments (e.g. file names) to
9373 contain embedded newline characters. This limitation will likely go away in
9374 a future version of SCons.
9382 new file types for implicit dependencies.
9383 Scanner accepts the following arguments:
9387 1) a Python function that will process
9389 and return a list of strings (file names)
9390 representing the implicit
9391 dependencies found in the contents;
9393 2) a dictionary that maps keys
9394 (typically the file suffix, but see below for more discussion)
9395 to other Scanners that should be called.
9397 If the argument is actually a Python function,
9398 the function must take three or four arguments:
9400 def scanner_function(node, env, path):
9402 def scanner_function(node, env, path, arg=None):
9406 argument is the internal
9407 SCons node representing the file.
9410 to fetch the name of the file, and
9411 .B node.get_contents()
9412 to fetch contents of the file.
9413 Note that the file is
9415 guaranteed to exist before the scanner is called,
9416 so the scanner function should check that
9417 if there's any chance that the scanned file
9419 (for example, if it's built from other files).
9423 argument is the construction environment for the scan.
9424 Fetch values from it using the
9430 argument is a tuple (or list)
9431 of directories that can be searched
9433 This will usually be the tuple returned by the
9435 argument (see below).
9439 argument is the argument supplied
9440 when the scanner was created, if any.
9443 The name of the Scanner.
9445 to identify the Scanner internally.
9448 An optional argument that, if specified,
9449 will be passed to the scanner function
9451 and the path function
9455 An optional list that can be used to
9456 determine which scanner should be used for
9458 In the usual case of scanning for file names,
9459 this argument will be a list of suffixes
9460 for the different file types that this
9461 Scanner knows how to scan.
9462 If the argument is a string,
9463 then it will be expanded
9464 into a list by the current environment.
9467 A Python function that takes four or five arguments:
9468 a construction environment,
9469 a Node for the directory containing
9470 the SConscript file in which
9471 the first target was defined,
9472 a list of target nodes,
9473 a list of source nodes,
9474 and an optional argument supplied
9475 when the scanner was created.
9478 returns a tuple of directories
9479 that can be searched for files to be returned
9480 by this Scanner object.
9483 function can be used to return a ready-made
9485 for a given construction variable name,
9486 instead of having to write your own function from scratch.)
9489 The class of Node that should be returned
9490 by this Scanner object.
9491 Any strings or other objects returned
9492 by the scanner function
9493 that are not of this class
9494 will be run through the
9499 A Python function that will take a string
9501 and turn it into the appropriate class of Node
9502 to be returned by this Scanner object.
9505 An optional Python function that takes two arguments,
9506 a Node (file) and a construction environment,
9507 and returns whether the
9508 Node should, in fact,
9509 be scanned for dependencies.
9510 This check can be used to eliminate unnecessary
9511 calls to the scanner function when,
9512 for example, the underlying file
9513 represented by a Node does not yet exist.
9516 An optional flag that
9517 specifies whether this scanner should be re-invoked
9518 on the dependency files returned by the scanner.
9519 When this flag is not set,
9520 the Node subsystem will
9521 only invoke the scanner on the file being scanned,
9522 and not (for example) also on the files
9523 specified by the #include lines
9524 in the file being scanned.
9526 may be a callable function,
9527 in which case it will be called with a list of
9529 should return a list of Nodes
9530 that should be scanned recursively;
9531 this can be used to select a specific subset of
9532 Nodes for additional scanning.
9537 .B SourceFileScanner
9538 object that is used by
9541 .BR SharedObject (),
9545 which scanner should be used
9546 for different file extensions.
9548 .BR SourceFileScanner.add_scanner ()
9549 method to add your own Scanner object
9553 that builds target programs or
9554 libraries from a list of
9555 source files of different types:
9558 def xyz_scan(node, env, path):
9559 contents = node.get_text_contents()
9560 # Scan the contents and return the included files.
9562 XYZScanner = Scanner(xyz_scan)
9564 SourceFileScanner.add_scanner('.xyx', XYZScanner)
9566 env.Program('my_prog', ['file1.c', 'file2.f', 'file3.xyz'])
9569 .SH SYSTEM-SPECIFIC BEHAVIOR
9570 SCons and its configuration files are very portable,
9571 due largely to its implementation in Python.
9572 There are, however, a few portability
9573 issues waiting to trap the unwary.
9575 SCons handles the upper-case
9577 file suffix differently,
9578 depending on the capabilities of
9579 the underlying system.
9580 On a case-sensitive system
9581 such as Linux or UNIX,
9582 SCons treats a file with a
9584 suffix as a C++ source file.
9585 On a case-insensitive system
9587 SCons treats a file with a
9589 suffix as a C source file.
9591 SCons handles the upper-case
9593 file suffix differently,
9594 depending on the capabilities of
9595 the underlying system.
9596 On a case-sensitive system
9597 such as Linux or UNIX,
9598 SCons treats a file with a
9600 suffix as a Fortran source file
9601 that is to be first run through
9602 the standard C preprocessor.
9603 On a case-insensitive system
9605 SCons treats a file with a
9607 suffix as a Fortran source file that should
9609 be run through the C preprocessor.
9610 .SS Windows: Cygwin Tools and Cygwin Python vs. Windows Pythons
9611 Cygwin supplies a set of tools and utilities
9612 that let users work on a
9613 Windows system using a more POSIX-like environment.
9614 The Cygwin tools, including Cygwin Python,
9616 by sharing an ability to interpret UNIX-like path names.
9617 For example, the Cygwin tools
9618 will internally translate a Cygwin path name
9619 like /cygdrive/c/mydir
9620 to an equivalent Windows pathname
9621 of C:/mydir (equivalent to C:\\mydir).
9624 that are built for native Windows execution,
9625 such as the python.org and ActiveState versions,
9626 do not have the Cygwin path name semantics.
9627 This means that using a native Windows version of Python
9628 to build compiled programs using Cygwin tools
9629 (such as gcc, bison, and flex)
9630 may yield unpredictable results.
9631 "Mixing and matching" in this way
9632 can be made to work,
9633 but it requires careful attention to the use of path names
9634 in your SConscript files.
9636 In practice, users can sidestep
9637 the issue by adopting the following rules:
9639 use the Cygwin-supplied Python interpreter
9641 when using Microsoft Visual C/C++
9642 (or some other Windows compiler)
9643 use the python.org or ActiveState version of Python
9645 .SS Windows: scons.bat file
9647 SCons is executed via a wrapper
9650 This has (at least) two ramifications:
9652 First, Windows command-line users
9653 that want to use variable assignment
9655 may have to put double quotes
9656 around the assignments:
9659 scons "FOO=BAR" "BAZ=BLEH"
9662 Second, the Cygwin shell does not
9663 recognize this file as being the same
9666 command issued at the command-line prompt.
9667 You can work around this either by
9670 from the Cygwin command line,
9671 or by creating a wrapper shell
9677 The MinGW bin directory must be in your PATH environment variable or the
9678 PATH variable under the ENV construction variable for SCons
9679 to detect and use the MinGW tools. When running under the native Windows
9680 Python interpreter, SCons will prefer the MinGW tools over the Cygwin
9681 tools, if they are both installed, regardless of the order of the bin
9682 directories in the PATH variable. If you have both MSVC and MinGW
9683 installed and you want to use MinGW instead of MSVC,
9684 then you must explictly tell SCons to use MinGW by passing
9690 to the Environment() function, because SCons will prefer the MSVC tools
9691 over the MinGW tools.
9695 To help you get started using SCons,
9696 this section contains a brief overview of some common tasks.
9698 .SS Basic Compilation From a Single Source File
9702 env.Program(target = 'foo', source = 'foo.c')
9705 Note: Build the file by specifying
9706 the target as an argument
9707 ("scons foo" or "scons foo.exe").
9708 or by specifying a dot ("scons .").
9710 .SS Basic Compilation From Multiple Source Files
9714 env.Program(target = 'foo', source = Split('f1.c f2.c f3.c'))
9717 .SS Setting a Compilation Flag
9720 env = Environment(CCFLAGS = '-g')
9721 env.Program(target = 'foo', source = 'foo.c')
9724 .SS Search The Local Directory For .h Files
9728 need to set CCFLAGS to specify -I options by hand.
9729 SCons will construct the right -I options from CPPPATH.
9732 env = Environment(CPPPATH = ['.'])
9733 env.Program(target = 'foo', source = 'foo.c')
9736 .SS Search Multiple Directories For .h Files
9739 env = Environment(CPPPATH = ['include1', 'include2'])
9740 env.Program(target = 'foo', source = 'foo.c')
9743 .SS Building a Static Library
9747 env.StaticLibrary(target = 'foo', source = Split('l1.c l2.c'))
9748 env.StaticLibrary(target = 'bar', source = ['l3.c', 'l4.c'])
9751 .SS Building a Shared Library
9755 env.SharedLibrary(target = 'foo', source = ['l5.c', 'l6.c'])
9756 env.SharedLibrary(target = 'bar', source = Split('l7.c l8.c'))
9759 .SS Linking a Local Library Into a Program
9762 env = Environment(LIBS = 'mylib', LIBPATH = ['.'])
9763 env.Library(target = 'mylib', source = Split('l1.c l2.c'))
9764 env.Program(target = 'prog', source = ['p1.c', 'p2.c'])
9767 .SS Defining Your Own Builder Object
9769 Notice that when you invoke the Builder,
9770 you can leave off the target file suffix,
9771 and SCons will add it automatically.
9774 bld = Builder(action = 'pdftex < $SOURCES > $TARGET'
9776 src_suffix = '.tex')
9777 env = Environment(BUILDERS = {'PDFBuilder' : bld})
9778 env.PDFBuilder(target = 'foo.pdf', source = 'foo.tex')
9780 # The following creates "bar.pdf" from "bar.tex"
9781 env.PDFBuilder(target = 'bar', source = 'bar')
9784 Note also that the above initialization
9785 overwrites the default Builder objects,
9786 so the Environment created above
9787 can not be used call Builders like env.Program(),
9788 env.Object(), env.StaticLibrary(), etc.
9790 .SS Adding Your Own Builder Object to an Environment
9793 bld = Builder(action = 'pdftex < $SOURCES > $TARGET'
9795 src_suffix = '.tex')
9797 env.Append(BUILDERS = {'PDFBuilder' : bld})
9798 env.PDFBuilder(target = 'foo.pdf', source = 'foo.tex')
9799 env.Program(target = 'bar', source = 'bar.c')
9802 You also can use other Pythonic techniques to add
9803 to the BUILDERS construction variable, such as:
9807 env['BUILDERS]['PDFBuilder'] = bld
9810 .SS Defining Your Own Scanner Object
9812 The following example shows an extremely simple scanner (the
9815 that doesn't use a search path at all
9816 and simply returns the
9817 file names present on any
9819 lines in the scanned file.
9820 This would implicitly assume that all included
9821 files live in the top-level directory:
9826 '\" Note: the \\ in the following are for the benefit of nroff/troff,
9827 '\" not inappropriate doubled escape characters within the r'' raw string.
9828 include_re = re.compile(r'^include\\s+(\\S+)$', re.M)
9830 def kfile_scan(node, env, path, arg):
9831 contents = node.get_text_contents()
9832 includes = include_re.findall(contents)
9835 kscan = Scanner(name = 'kfile',
9836 function = kfile_scan,
9839 scanners = Environment().Dictionary('SCANNERS')
9840 env = Environment(SCANNERS = scanners + [kscan])
9842 env.Command('foo', 'foo.k', 'kprocess < $SOURCES > $TARGET')
9844 bar_in = File('bar.in')
9845 env.Command('bar', bar_in, 'kprocess $SOURCES > $TARGET')
9846 bar_in.target_scanner = kscan
9849 Here is a similar but more complete example that searches
9850 a path of directories
9853 construction variable)
9854 for files that actually exist:
9857 include_re = re.compile(r'^include\\s+(\\S+)$', re.M)
9859 def my_scan(node, env, path, arg):
9860 contents = node.get_text_contents()
9861 includes = include_re.findall(contents)
9865 for inc in includes:
9867 file = dir + os.sep + inc
9868 if os.path.exists(file):
9869 results.append(file)
9873 scanner = Scanner(name = 'myscanner',
9877 path_function = FindPathDirs('MYPATH'),
9879 scanners = Environment().Dictionary('SCANNERS')
9880 env = Environment(SCANNERS = scanners + [scanner])
9885 function used in the previous example returns a function
9886 (actually a callable Python object)
9887 that will return a list of directories
9890 construction variable.
9891 If you need to customize how the search path is derived,
9892 you would provide your own
9894 argument when creating the Scanner object,
9898 # MYPATH is a list of directories to search for files in
9899 def pf(env, dir, target, source, arg):
9900 top_dir = Dir('#').abspath
9903 for p in env['MYPATH']:
9904 results.append(top_dir + os.sep + p)
9907 scanner = Scanner(name = 'myscanner',
9915 .SS Creating a Hierarchical Build
9917 Notice that the file names specified in a subdirectory's
9919 file are relative to that subdirectory.
9925 env.Program(target = 'foo', source = 'foo.c')
9927 SConscript('sub/SConscript')
9932 # Builds sub/foo from sub/foo.c
9933 env.Program(target = 'foo', source = 'foo.c')
9935 SConscript('dir/SConscript')
9940 # Builds sub/dir/foo from sub/dir/foo.c
9941 env.Program(target = 'foo', source = 'foo.c')
9944 .SS Sharing Variables Between SConscript Files
9946 You must explicitly Export() and Import() variables that
9947 you want to share between SConscript files.
9953 env.Program(target = 'foo', source = 'foo.c')
9956 SConscript('subdirectory/SConscript')
9958 subdirectory/SConscript:
9961 env.Program(target = 'foo', source = 'foo.c')
9964 .SS Building Multiple Variants From the Same Source
9966 Use the variant_dir keyword argument to
9967 the SConscript function to establish
9968 one or more separate variant build directory trees
9969 for a given source directory:
9974 cppdefines = ['FOO']
9975 Export("cppdefines")
9976 SConscript('src/SConscript', variant_dir='foo')
9978 cppdefines = ['BAR']
9979 Export("cppdefines")
9980 SConscript('src/SConscript', variant_dir='bar')
9984 Import("cppdefines")
9985 env = Environment(CPPDEFINES = cppdefines)
9986 env.Program(target = 'src', source = 'src.c')
9989 Note the use of the Export() method
9990 to set the "cppdefines" variable to a different
9991 value each time we call the SConscript function.
9993 .SS Hierarchical Build of Two Libraries Linked With a Program
9998 env = Environment(LIBPATH = ['#libA', '#libB'])
10000 SConscript('libA/SConscript')
10001 SConscript('libB/SConscript')
10002 SConscript('Main/SConscript')
10007 env.Library('a', Split('a1.c a2.c a3.c'))
10012 env.Library('b', Split('b1.c b2.c b3.c'))
10017 e = env.Copy(LIBS = ['a', 'b'])
10018 e.Program('foo', Split('m1.c m2.c m3.c'))
10021 The '#' in the LIBPATH directories specify that they're relative to the
10022 top-level directory, so they don't turn into "Main/libA" when they're
10023 used in Main/SConscript.
10025 Specifying only 'a' and 'b' for the library names
10026 allows SCons to append the appropriate library
10027 prefix and suffix for the current platform
10028 (for example, 'liba.a' on POSIX systems,
10029 \&'a.lib' on Windows).
10031 .SS Customizing construction variables from the command line.
10033 The following would allow the C compiler to be specified on the command
10034 line or in the file custom.py.
10037 vars = Variables('custom.py')
10038 vars.Add('CC', 'The C compiler.')
10039 env = Environment(variables=vars)
10040 Help(vars.GenerateHelpText(env))
10043 The user could specify the C compiler on the command line:
10049 or in the custom.py file:
10055 or get documentation on the options:
10060 CC: The C compiler.
10066 .SS Using Microsoft Visual C++ precompiled headers
10068 Since windows.h includes everything and the kitchen sink, it can take quite
10069 some time to compile it over and over again for a bunch of object files, so
10070 Microsoft provides a mechanism to compile a set of headers once and then
10071 include the previously compiled headers in any object file. This
10072 technology is called precompiled headers. The general recipe is to create a
10073 file named "StdAfx.cpp" that includes a single header named "StdAfx.h", and
10074 then include every header you want to precompile in "StdAfx.h", and finally
10075 include "StdAfx.h" as the first header in all the source files you are
10076 compiling to object files. For example:
10080 #include <windows.h>
10081 #include <my_big_header.h>
10086 #include <StdAfx.h>
10091 #include <StdAfx.h>
10093 /* do some stuff */
10098 #include <StdAfx.h>
10100 /* do some other stuff */
10106 env['PCHSTOP'] = 'StdAfx.h'
10107 env['PCH'] = env.PCH('StdAfx.cpp')[0]
10108 env.Program('MyApp', ['Foo.cpp', 'Bar.cpp'])
10111 For more information see the document for the PCH builder, and the PCH and
10112 PCHSTOP construction variables. To learn about the details of precompiled
10113 headers consult the MSDN documention for /Yc, /Yu, and /Yp.
10115 .SS Using Microsoft Visual C++ external debugging information
10117 Since including debugging information in programs and shared libraries can
10118 cause their size to increase significantly, Microsoft provides a mechanism
10119 for including the debugging information in an external file called a PDB
10120 file. SCons supports PDB files through the PDB construction
10126 env['PDB'] = 'MyApp.pdb'
10127 env.Program('MyApp', ['Foo.cpp', 'Bar.cpp'])
10130 For more information see the document for the PDB construction variable.
10135 Specifies the directory that contains the SCons Python module directory
10136 (e.g. /home/aroach/scons-src-0.01/src/engine).
10139 A string of options that will be used by scons in addition to those passed
10140 on the command line.
10151 Steven Knight <knight@baldmt.com>
10153 Anthony Roach <aroach@electriceyeball.com>