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 adds looks for a dir named
103 in the dir containing the
107 to sys.path, reads the file
108 .IR site_scons/site_init.py ,
109 and adds the directory
110 .I site_scons/site_tools
111 to the default toolpath, if those exist. See the
115 options for more details.
118 reads and executes the SConscript files as Python scripts,
119 so you may use normal Python scripting capabilities
120 (such as flow control, data manipulation, and imported Python libraries)
121 to handle complicated build situations.
123 however, reads and executes all of the SConscript files
125 it begins building any targets.
126 To make this obvious,
128 prints the following messages about what it is doing:
132 scons: Reading SConscript files ...
133 scons: done reading SConscript files.
134 scons: Building targets ...
136 scons: done building targets.
141 (everything except the line that reads "cp foo.in foo.out")
142 may be suppressed using the
147 does not automatically propagate
148 the external environment used to execute
150 to the commands used to build target files.
151 This is so that builds will be guaranteed
152 repeatable regardless of the environment
153 variables set at the time
156 This also means that if the compiler or other commands
157 that you want to use to build your target files
158 are not in standard system locations,
160 will not find them unless
161 you explicitly set the PATH
162 to include those locations.
163 Whenever you create an
165 construction environment,
166 you can propagate the value of PATH
167 from your external environment as follows:
171 env = Environment(ENV = {'PATH' : os.environ['PATH']})
174 Similarly, if the commands use external environment variables
175 like $PATH, $HOME, $JAVA_HOME, $LANG, $SHELL, $TERM, etc.,
176 these variables can also be explicitly propagated:
180 env = Environment(ENV = {'PATH' : os.environ['PATH'],
181 'HOME' : os.environ['HOME']})
184 Or you may explicitly propagate the invoking user's
185 complete external environment:
189 env = Environment(ENV = os.environ)
192 This comes at the expense of making your build
193 dependent on the user's environment being set correctly,
194 but it may be more convenient for many configurations.
197 can scan known input files automatically for dependency
198 information (for example, #include statements
199 in C or C++ files) and will rebuild dependent files appropriately
200 whenever any "included" input file changes.
203 ability to define new scanners for unknown input file types.
206 knows how to fetch files automatically from
207 SCCS or RCS subdirectories
208 using SCCS, RCS or BitKeeper.
211 is normally executed in a top-level directory containing a
213 file, optionally specifying
214 as command-line arguments
215 the target file or files to be built.
217 By default, the command
223 will build all target files in or below the current directory.
224 Explicit default targets
225 (to be built when no targets are specified on the command line)
226 may be defined the SConscript file(s)
229 function, described below.
233 targets are specified in the SConscript file(s),
234 all target files in or below the current directory
235 may be built by explicitly specifying
236 the current directory (.)
237 as a command-line target:
243 Building all target files,
244 including any files outside of the current directory,
245 may be specified by supplying a command-line target
246 of the root directory (on POSIX systems):
252 or the path name(s) of the volume(s) in which all the targets
253 should be built (on Windows systems):
259 To build only specific targets,
260 supply them as command-line arguments:
266 in which case only the specified targets will be built
267 (along with any derived files on which they depend).
269 Specifying "cleanup" targets in SConscript files is not usually necessary.
272 flag removes all files
273 necessary to build the specified target:
279 to remove all target files, or:
282 scons -c build export
285 to remove target files under build and export.
286 Additional files or directories to remove can be specified using the
289 Conversely, targets that would normally be removed by the
292 can be prevented from being removed by using the
296 A subset of a hierarchical tree may be built by
297 remaining at the top-level directory (where the
299 file lives) and specifying the subdirectory as the target to be
306 or by changing directory and invoking scons with the
308 option, which traverses up the directory
309 hierarchy until it finds the
311 file, and then builds
312 targets relatively to the current subdirectory:
320 supports building multiple targets in parallel via a
322 option that takes, as its argument, the number
323 of simultaneous tasks that may be spawned:
329 builds four targets in parallel, for example.
332 can maintain a cache of target (derived) files that can
333 be shared between multiple builds. When caching is enabled in a
334 SConscript file, any target files built by
337 to the cache. If an up-to-date target file is found in the cache, it
338 will be retrieved from the cache instead of being rebuilt locally.
339 Caching behavior may be disabled and controlled in other ways by the
341 .BR --cache-disable ,
344 command-line options. The
346 option is useful to prevent multiple builds
347 from trying to update the cache simultaneously.
349 Values of variables to be passed to the SConscript file(s)
350 may be specified on the command line:
356 These variables are available in SConscript files
357 through the ARGUMENTS dictionary,
358 and can be used in the SConscript file(s) to modify
359 the build in any way:
362 if ARGUMENTS.get('debug', 0):
363 env = Environment(CCFLAGS = '-g')
368 The command-line variable arguments are also available
370 indexed by their order on the command line.
371 This allows you to process them in order rather than by name,
373 ARGLIST[0] returns a tuple
374 containing (argname, argvalue).
375 A Python exception is thrown if you
376 try to access a list member that
380 requires Python version 1.5.2 or later.
381 There should be no other dependencies or requirements to run
384 .\" The following paragraph reflects the default tool search orders
385 .\" currently in SCons/Tool/__init__.py. If any of those search orders
386 .\" change, this documentation should change, too.
389 knows how to search for available programming tools
393 searches in order for the
394 Microsoft Visual C++ tools,
395 the MinGW tool chain,
396 the Intel compiler tools,
397 and the PharLap ETS compiler.
400 searches in order for the
403 and the Microsoft Visual C++ tools,
404 On SGI IRIX, IBM AIX, Hewlett Packard HP-UX, and Sun Solaris systems,
406 searches for the native compiler tools
407 (MIPSpro, Visual Age, aCC, and Forte tools respectively)
408 and the GCC tool chain.
409 On all other platforms,
410 including POSIX (Linux and UNIX) platforms,
413 for the GCC tool chain,
414 the Microsoft Visual C++ tools,
415 and the Intel compiler tools.
416 You may, of course, override these default values
417 by appropriate configuration of
418 Environment construction variables.
423 supports the same command-line options as GNU
425 and many of those supported by
430 Ignored for compatibility with non-GNU versions of
434 -c, --clean, --remove
435 Clean up by removing all target files for which a construction
436 command is specified.
437 Also remove any files or directories associated to the construction command
441 Will not remove any targets specified by the
446 .RI --cache-debug= file
447 Print debug information about the
457 the debug information are printed to the standard output.
458 The printed messages describe what signature file names are
459 being looked for in, retrieved from, or written to the
464 --cache-disable, --no-cache
465 Disable the derived-file caching specified by
468 will neither retrieve files from the cache
469 nor copy files to the cache.
472 --cache-force, --cache-populate
475 populate a cache by copying any already-existing, up-to-date
476 derived files to the cache,
477 in addition to files built by this invocation.
478 This is useful to populate a new cache with
479 all the current derived files,
480 or to add to the cache any derived files
481 recently built with caching disabled via the
489 and retrieving a derived file from the cache,
491 that would have been executed to build the file,
492 instead of the usual report,
493 "Retrieved `file' from cache."
494 This will produce consistent output for build logs,
495 regardless of whether a target
496 file was rebuilt or retrieved from the cache.
500 This specifies how the
502 call should use or generate the
503 results of configuration tests.
504 The option should be specified from
505 among the following choices:
509 scons will use its normal dependency mechanisms
510 to decide if a test must be rebuilt or not.
511 This saves time by not running the same configuration tests
512 every time you invoke scons,
513 but will overlook changes in system header files
514 or external commands (such as compilers)
515 if you don't specify those dependecies explicitly.
516 This is the default behavior.
520 If this option is specified,
521 all configuration tests will be re-run
522 regardless of whether the
523 cached results are out of date.
524 This can be used to explicitly
525 force the configuration tests to be updated
526 in response to an otherwise unconfigured change
527 in a system header file or compiler.
531 If this option is specified,
532 no configuration tests will be rerun
533 and all results will be taken from cache.
534 Note that scons will still consider it an error
535 if --config=cache is specified
536 and a necessary test does not
537 yet have any results in the cache.
540 .RI "-C" " directory" ", --directory=" directory
541 Change to the specified
543 before searching for the
548 file, or doing anything
551 options are interpreted
552 relative to the previous one, and the right-most
554 option wins. (This option is nearly
556 .BR "-f directory/SConstruct" ,
557 except that it will search for
562 in the specified directory.)
566 .\" Display dependencies while building target files. Useful for
567 .\" figuring out why a specific file is being rebuilt, as well as
568 .\" general debugging of the build process.
572 Works exactly the same way as the
574 option except for the way default targets are handled.
575 When this option is used and no targets are specified on the command line,
576 all default targets are built, whether or not they are below the current
581 Debug the build process.
583 specifies what type of debugging:
587 Print how many objects are created
588 of the various classes used internally by SCons
589 before and after reading the SConscript files
590 and before and after building targets.
591 This is not supported when run under Python versions earlier than 2.1,
592 when SCons is executed with the Python
595 or when the SCons modules
596 have been compiled with optimization
597 (that is, when executing from
603 A synonym for the newer
606 This will be deprecated in some future release
607 and ultimately removed.
611 Print an explanation of precisely why
613 is deciding to (re-)build any targets.
614 (Note: this does not print anything
621 Instruct the scanner that searches for libraries
622 to print a message about each potential library
623 name it is searching for,
624 and about the actual libraries it finds.
628 Print the include tree after each top-level target is built.
629 This is generally used to find out what files are included by the sources
630 of a given derived file:
633 $ scons --debug=includes foo.o
638 Prints a summary of hits and misses using the Memoizer,
639 an internal subsystem that counts
640 how often SCons uses cached values in memory
641 instead of recomputing them each time they're needed.
642 Only available when using Python 2.2 or later.
646 Prints how much memory SCons uses
647 before and after reading the SConscript files
648 and before and after building targets.
652 A deprecated option preserved for backwards compatibility.
656 Prints a list of the various objects
657 of the various classes used internally by SCons.
658 This only works when run under Python 2.1 or later.
662 Re-run SCons under the control of the
668 Print the raw command line used to build each target
669 before the construction environment variables are substituted.
670 Also shows which targets are being built by this command.
671 Output looks something like this:
673 $ scons --debug=presub
674 Building myprog.o with action(s):
675 $SHCC $SHCFLAGS $SHCCFLAGS $CPPFLAGS $_CPPINCFLAGS -c -o $TARGET $SOURCES
681 Prints an internal Python stack trace
682 when encountering an otherwise unexplained error.
686 A synonym for the newer
689 This will be deprecated in some future release
690 and ultimately removed.
694 Prints various time profiling information:
695 the time spent executing each individual build command;
696 the total build time (time SCons ran from beginning to end);
697 the total time spent reading and executing SConscript files;
698 the total time spent SCons itself spend running
699 (that is, not counting reading and executing SConscript files);
700 and both the total time spent executing all build commands
701 and the elapsed wall-clock time spent executing those build commands.
704 is executed without the
707 the elapsed wall-clock time will typically
708 be slightly longer than the total time spent
709 executing all the build commands,
710 due to the SCons processing that takes place
711 in between executing each command.
719 and your build configuration allows good parallelization,
720 the elapsed wall-clock time should
721 be significantly smaller than the
722 total time spent executing all the build commands,
723 since multiple build commands and
724 intervening SCons processing
725 should take place in parallel.)
729 A synonym for the newer
732 This will be deprecated in some future release
733 and ultimately removed.
736 .RI --diskcheck= types
737 Enable specific checks for
738 whether or not there is a file on disk
739 where the SCons configuration expects a directory
741 and whether or not RCS or SCCS sources exist
742 when searching for source and include files.
745 argument can be set to:
747 to enable all checks explicitly
748 (the default behavior);
750 to disable all such checks;
752 to check that files and directories on disk
753 match SCons' expected configuration;
755 to check for the existence of an RCS source
756 for any missing source or include files;
758 to check for the existence of an SCCS source
759 for any missing source or include files.
760 Multiple checks can be specified separated by commas;
762 .B --diskcheck=sccs,rcs
763 would still check for SCCS and RCS sources,
764 but disable the check for on-disk matches of files and directories.
765 Disabling some or all of these checks
766 can provide a performance boost for large configurations,
767 or when the configuration will check for files and/or directories
768 across networked or shared file systems,
769 at the slight increased risk of an incorrect build
770 or of not handling errors gracefully
771 (if include files really should be
772 found in SCCS or RCS, for example,
773 or if a file really does exist
774 where the SCons configuration expects a directory).
777 .RI --duplicate= ORDER
778 There are three ways to duplicate files in a build tree: hard links,
779 soft (symbolic) links and copies. The default behaviour of SCons is to
780 prefer hard links to soft links to copies. You can specify different
781 behaviours with this option.
791 SCons will attempt to duplicate files using
792 the mechanisms in the specified order.
795 .\" -e, --environment-overrides
796 .\" Variables from the execution environment override construction
797 .\" variables from the SConscript files.
800 .RI -f " file" ", --file=" file ", --makefile=" file ", --sconstruct=" file
803 as the initial SConscript file.
807 Print a local help message for this build, if one is defined in
808 the SConscript file(s), plus a line that describes the
810 option for command-line option help. If no local help message
811 is defined, prints the standard help message about command-line
812 options. Exits after displaying the appropriate message.
816 Print the standard help message about command-line options and
821 Ignore all errors from commands executed to rebuild files.
824 .RI -I " directory" ", --include-dir=" directory
828 imported Python modules. If several
831 are used, the directories are searched in the order specified.
835 Cache implicit dependencies.
838 to use the implicit (scanned) dependencies
839 from the last time it was run
840 instead of scanning the files for implicit dependencies.
841 This can significantly speed up SCons,
842 but with the following limitations:
845 will not detect changes to implicit dependency search paths
847 .BR CPPPATH ", " LIBPATH )
848 that would ordinarily
849 cause different versions of same-named files to be used.
852 will miss changes in the implicit dependencies
853 in cases where a new implicit
854 dependency is added earlier in the implicit dependency search path
856 .BR CPPPATH ", " LIBPATH )
857 than a current implicit dependency with the same name.
860 --implicit-deps-changed
861 Forces SCons to ignore the cached implicit dependencies. This causes the
862 implicit dependencies to be rescanned and recached. This implies
863 .BR --implicit-cache .
866 --implicit-deps-unchanged
867 Force SCons to ignore changes in the implicit dependencies.
868 This causes cached implicit dependencies to always be used.
870 .BR --implicit-cache .
874 Starts SCons in interactive mode.
875 The SConscript files are read once and a
878 Targets may now be rebuilt by typing commands at interactive prompt
879 without having to re-read the SConscript files
880 and re-initialize the dependency graph from scratch.
882 SCons interactive mode supports the following commands:
886 .BI build "[OPTIONS] [TARGETS] ..."
889 (and their dependencies)
898 The following SCons command-line options affect the
904 --cache-disable, --no-cache
905 --cache-force, --cache-populate
911 -n, --no-exec, --just-print, --dry-run, --recon
913 -s, --silent, --quiet
914 --taskmastertrace=FILE
919 Any other SCons command-line options that are specified
921 but have no effect on the
924 (mainly because they affect how the SConscript files are read,
925 which only happens once at the beginning of interactive mode).
928 .BI clean "[OPTIONS] [TARGETS] ..."
931 (and their dependencies)
932 with the specified options.
935 This command is itself a synonym for
940 Exits SCons interactive mode.
941 You can also exit by terminating input
942 (CTRL+D on UNIX or Linux systems,
943 CTRL+Z on Windows systems).
947 Provides a help message about
948 the commands available in SCons interactive mode.
958 .BI shell "[COMMANDLINE]"
959 Executes the specified
965 executes the interactive command interpreter
969 (on UNIX and Linux systems)
973 (on Windows systems).
981 Prints SCons version information.
985 An empty line repeats the last typed command.
986 Command-line editing can be used if the
991 $ scons --interactive
992 scons: Reading SConscript files ...
993 scons: done reading SConscript files.
994 scons>>> build -n prog
999 .RI -j " N" ", --jobs=" N
1000 Specifies the number of jobs (commands) to run simultaneously.
1001 If there is more than one
1003 option, the last one is effective.
1007 .\" is specified without an argument,
1009 .\" will not limit the number of
1010 .\" simultaneous jobs.
1014 Continue as much as possible after an error. The target that
1015 failed and those that depend on it will not be remade, but other
1016 targets specified on the command line will still be processed.
1019 .\" .RI -l " N" ", --load-average=" N ", --max-load=" N
1020 .\" No new jobs (commands) will be started if
1021 .\" there are other jobs running and the system load
1022 .\" average is at least
1024 .\" (a floating-point number).
1029 .\" List derived files (targets, dependencies) that would be built,
1030 .\" but do not build them.
1031 .\" [XXX This can probably go away with the right
1032 .\" combination of other options. Revisit this issue.]
1036 .\" List derived files that would be built, with the actions
1037 .\" (commands) that build them. Does not build the files.
1038 .\" [XXX This can probably go away with the right
1039 .\" combination of other options. Revisit this issue.]
1043 .\" List derived files that would be built, plus where the file is
1044 .\" defined (file name and line number). Does not build the files.
1045 .\" [XXX This can probably go away with the right
1046 .\" combination of other options. Revisit this issue.]
1050 Ignored for compatibility with non-GNU versions of
1054 .RI --max-drift= SECONDS
1055 Set the maximum expected drift in the modification time of files to
1057 This value determines how long a file must be unmodified
1058 before its cached content signature
1059 will be used instead of
1060 calculating a new content signature (MD5 checksum)
1061 of the file's contents.
1062 The default value is 2 days, which means a file must have a
1063 modification time of at least two days ago in order to have its
1064 cached content signature used.
1065 A negative value means to never cache the content
1066 signature and to ignore the cached value if there already is one. A value
1067 of 0 means to always use the cached signature,
1068 no matter how old the file is.
1071 -n, --just-print, --dry-run, --recon
1072 No execute. Print the commands that would be executed to build
1073 any out-of-date target files, but do not execute the commands.
1077 Prevents the automatic addition of the standard
1081 Also prevents loading the
1082 .I site_scons/site_init.py
1083 module if it exists, and prevents adding
1084 .I site_scons/site_tools
1088 .\" .RI -o " file" ", --old-file=" file ", --assume-old=" file
1092 .\" not rebuild anything due to changes in the contents of
1095 .\" .RI --override " file"
1096 .\" Read values to override specific build environment variables
1097 .\" from the specified
1101 .\" Print the data base (construction environments,
1102 .\" Builder and Scanner objects) that are defined
1103 .\" after reading the SConscript files.
1104 .\" After printing, a normal build is performed
1105 .\" as usual, as specified by other command-line options.
1106 .\" This also prints version information
1111 .\" To print the database without performing a build do:
1119 Run SCons under the Python profiler
1120 and save the results in the specified
1122 The results may be analyzed using the Python
1127 Do not run any commands, or print anything. Just return an exit
1128 status that is zero if the specified targets are already up to
1129 date, non-zero otherwise.
1132 Quiets SCons status messages about
1133 reading SConscript files,
1135 and entering directories.
1136 Commands that are executed
1137 to rebuild target files are still printed.
1140 .\" -r, -R, --no-builtin-rules, --no-builtin-variables
1141 .\" Clear the default construction variables. Construction
1142 .\" environments that are created will be completely empty.
1146 Build dependencies in a random order. This is useful when
1147 building multiple trees simultaneously with caching enabled,
1148 to prevent multiple builds from simultaneously trying to build
1149 or retrieve the same target files.
1152 -s, --silent, --quiet
1153 Silent. Do not print commands that are executed to rebuild
1155 Also suppresses SCons status messages.
1158 -S, --no-keep-going, --stop
1159 Ignored for compatibility with GNU
1164 Uses the named dir as the site dir rather than the default
1166 dir. This dir will get prepended to
1169 .IR dir /site_init.py
1170 will get loaded if it exists, and
1172 will get added to the default toolpath.
1175 .RI --stack-size= KILOBYTES
1176 Set the size stack used to run threads to
1178 This value determines the stack size of the threads used to run jobs.
1179 These are the threads that execute the actions of the builders for the
1180 nodes that are out-of-date.
1181 Note that this option has no effect unless the
1183 option, which corresponds to -j and --jobs, is larger than one. Using
1184 a stack size that is too small may cause stack overflow errors. This
1185 usually shows up as segmentation faults that cause scons to abort
1186 before building anything. Using a stack size that is too large will
1187 cause scons to use more memory than required and may slow down the entire
1190 The default value is to use a stack size of 256 kilobytes, which should
1191 be appropriate for most uses. You should not need to increase this value
1192 unless you encounter stack overflow errors.
1196 Ignored for compatibility with GNU
1198 (Touching a file to make it
1199 appear up-to-date is unnecessary when using
1203 .RI --taskmastertrace= file
1204 Prints trace information to the specified
1206 about how the internal Taskmaster object
1207 evaluates and controls the order in which Nodes are built.
1210 may be used to specify the standard output.
1214 Prints a tree of the dependencies
1215 after each top-level target is built.
1216 This prints out some or all of the tree,
1224 Print the entire dependency tree
1225 after each top-level target is built.
1226 This prints out the complete dependency tree,
1227 including implicit dependencies and ignored dependencies.
1231 Restricts the tree output to only derived (target) files,
1236 Prints status information for each displayed node.
1240 Prunes the tree to avoid repeating dependency information
1241 for nodes that have already been displayed.
1242 Any node that has already been displayed
1243 will have its name printed in
1244 .BR "[square brackets]" ,
1245 as an indication that the dependencies
1246 for that node can be found by searching
1247 for the relevant output higher up in the tree.
1250 Multiple options may be specified,
1251 separated by commas:
1254 # Prints only derived files, with status information:
1255 scons --tree=derived,status
1257 # Prints all dependencies of target, with status information
1258 # and pruning dependencies of already-visited Nodes:
1259 scons --tree=all,prune,status target
1263 -u, --up, --search-up
1264 Walks up the directory structure until an
1269 file is found, and uses that
1270 as the top of the directory tree.
1271 If no targets are specified on the command line,
1272 only targets at or below the
1273 current directory will be built.
1277 Works exactly the same way as the
1279 option except for the way default targets are handled.
1280 When this option is used and no targets are specified on the command line,
1281 all default targets that are defined in the SConscript(s) in the current
1282 directory are built, regardless of what directory the resultant targets end
1289 version, copyright information,
1290 list of authors, and any other relevant information.
1294 -w, --print-directory
1295 Print a message containing the working directory before and
1296 after other processing.
1299 --no-print-directory
1300 Turn off -w, even if it was turned on implicitly.
1303 .RI --warn= type ", --warn=no-" type
1304 Enable or disable warnings.
1306 specifies the type of warnings to be enabled or disabled:
1309 --warn=all, --warn=no-all
1310 Enables or disables all warnings.
1313 --warn=cache-write-error, --warn=no-cache-write-error
1314 Enables or disables warnings about errors trying to
1315 write a copy of a built file to a specified
1317 These warnings are disabled by default.
1320 --warn=corrupt-sconsign, --warn=no-corrupt-sconsign
1321 Enables or disables warnings about unfamiliar signature data in
1324 These warnings are enabled by default.
1327 --warn=dependency, --warn=no-dependency
1328 Enables or disables warnings about dependencies.
1329 These warnings are disabled by default.
1332 --warn=deprecated, --warn=no-deprecated
1333 Enables or disables all warnings about use of deprecated features.
1334 These warnings are enabled by default.
1335 Warnings for some specific deprecated features
1336 may be enabled or disabled individually;
1339 --warn=deprecated-copy, --warn=no-deprecated-copy
1340 Enables or disables warnings about use of the deprecated
1344 --warn=deprecated-source-signatures, --warn=no-deprecated-source-signatures
1345 Enables or disables warnings about use of the deprecated
1346 SourceSignatures() function
1348 .B env.SourceSignatures()
1351 --warn=deprecated-target-signatures, --warn=no-deprecated-target-signatures
1352 Enables or disables warnings about use of the deprecated
1353 TargetSignatures() function
1355 .B env.TargetSignatures()
1359 --warn=duplicate-environment, --warn=no-duplicate-environment
1360 Enables or disables warnings about attempts to specify a build
1361 of a target with two different construction environments
1362 that use the same action.
1363 These warnings are enabled by default.
1366 --warn=fortran-cxx-mix, --warn=no-fortran-cxx-mix
1367 Enables or disables the specific warning about linking
1368 Fortran and C++ object files in a single executable,
1369 which can yield unpredictable behavior with some compilers.
1372 --warn=link, --warn=no-link
1373 Enables or disables warnings about link steps.
1376 --warn=misleading-keywords, --warn=no-misleading-keywords
1377 Enables or disables warnings about use of the misspelled keywords
1381 when calling Builders.
1384 characters, the correct spellings are
1388 These warnings are enabled by default.
1391 --warn=missing-sconscript, --warn=no-missing-sconscript
1392 Enables or disables warnings about missing SConscript files.
1393 These warnings are enabled by default.
1396 --warn=no-md5-module, --warn=no-no-md5-module
1397 Enables or disables warnings about the version of Python
1398 not having an MD5 checksum module available.
1399 These warnings are enabled by default.
1402 --warn=no-metaclass-support, --warn=no-no-metaclass-support
1403 Enables or disables warnings about the version of Python
1404 not supporting metaclasses when the
1407 These warnings are enabled by default.
1410 --warn=no-object-count, --warn=no-no-object-count
1411 Enables or disables warnings about the
1413 feature not working when
1415 is run with the python
1417 option or from optimized Python (.pyo) modules.
1420 --warn=no-parallel-support, --warn=no-no-parallel-support
1421 Enables or disables warnings about the version of Python
1422 not being able to support parallel builds when the
1425 These warnings are enabled by default.
1428 --warn=python-version, --warn=no-python-version
1429 Enables or disables the warning about running
1430 SCons with a deprecated version of Python.
1431 These warnings are enabled by default.
1434 --warn=reserved-variable, --warn=no-reserved-variable
1435 Enables or disables warnings about attempts to set the
1436 reserved construction variable names
1442 These warnings are disabled by default.
1445 --warn=stack-size, --warn=no-stack-size
1446 Enables or disables warnings about requests to set the stack size
1447 that could not be honored.
1448 These warnings are enabled by default.
1451 .\" .RI --write-filenames= file
1452 .\" Write all filenames considered into
1456 .\" .RI -W " file" ", --what-if=" file ", --new-file=" file ", --assume-new=" file
1457 .\" Pretend that the target
1460 .\" modified. When used with the
1463 .\" show you what would be rebuilt if you were to modify that file.
1469 .\" --warn-undefined-variables
1470 .\" Warn when an undefined variable is referenced.
1473 .RI -Y " repository" ", --repository=" repository ", --srcdir=" repository
1474 Search the specified repository for any input and target
1475 files not found in the local directory hierarchy. Multiple
1477 options may be specified, in which case the
1478 repositories are searched in the order specified.
1480 .SH CONFIGURATION FILE REFERENCE
1481 .\" .SS Python Basics
1482 .\" XXX Adding this in the future would be a help.
1483 .SS Construction Environments
1484 A construction environment is the basic means by which the SConscript
1485 files communicate build information to
1487 A new construction environment is created using the
1498 may be set in a construction environment
1499 either by specifying them as keywords when the object is created
1500 or by assigning them a value after the object is created:
1503 env = Environment(FOO = 'foo')
1508 construction variables may also be set or modified by the
1510 keyword argument, which applies the
1512 method (described below) to the argument value
1513 after all other processing is completed.
1514 This is useful either if the exact content of the flags is unknown
1515 (for example, read from a control file)
1516 or if the flags are distributed to a number of construction variables.
1519 env = Environment(parse_flags = '-Iinclude -DEBUG -lm')
1522 This example adds 'include' to
1529 By default, a new construction environment is
1530 initialized with a set of builder methods
1531 and construction variables that are appropriate
1532 for the current platform.
1533 An optional platform keyword argument may be
1534 used to specify that an environment should
1535 be initialized for a different platform:
1538 env = Environment(platform = 'cygwin')
1539 env = Environment(platform = 'os2')
1540 env = Environment(platform = 'posix')
1541 env = Environment(platform = 'win32')
1544 Specifying a platform initializes the appropriate
1545 construction variables in the environment
1546 to use and generate file names with prefixes
1547 and suffixes appropriate for the platform.
1555 variables from the user's external environment
1556 to the construction environment's
1559 This is so that any executed commands
1560 that use sockets to connect with other systems
1561 (such as fetching source files from
1562 external CVS repository specifications like
1563 .BR :pserver:anonymous@cvs.sourceforge.net:/cvsroot/scons )
1564 will work on Windows systems.
1566 The platform argument may be function or callable object,
1567 in which case the Environment() method
1568 will call the specified argument to update
1569 the new construction environment:
1572 def my_platform(env):
1573 env['VAR'] = 'xyzzy'
1575 env = Environment(platform = my_platform)
1578 Additionally, a specific set of tools
1579 with which to initialize the environment
1580 may be specified as an optional keyword argument:
1583 env = Environment(tools = ['msvc', 'lex'])
1586 Non-built-in tools may be specified using the toolpath argument:
1589 env = Environment(tools = ['default', 'foo'], toolpath = ['tools'])
1592 This looks for a tool specification in tools/foo.py (as well as
1593 using the ordinary default tools for the platform). foo.py should
1594 have two functions: generate(env, **kw) and exists(env).
1598 modifies the passed-in environment
1599 to set up variables so that the tool
1601 it may use any keyword arguments
1602 that the user supplies (see below)
1603 to vary its initialization.
1606 function should return a true
1607 value if the tool is available.
1608 Tools in the toolpath are used before
1609 any of the built-in ones. For example, adding gcc.py to the toolpath
1610 would override the built-in gcc tool.
1611 Also note that the toolpath is
1612 stored in the environment for use
1620 base = Environment(toolpath=['custom_path'])
1621 derived = base.Clone(tools=['custom_tool'])
1622 derived.CustomBuilder()
1625 The elements of the tools list may also
1626 be functions or callable objects,
1627 in which case the Environment() method
1628 will call the specified elements
1629 to update the new construction environment:
1633 env['XYZZY'] = 'xyzzy'
1635 env = Environment(tools = [my_tool])
1638 The individual elements of the tools list
1639 may also themselves be two-element lists of the form
1640 .RI ( toolname ", " kw_dict ).
1641 SCons searches for the
1643 specification file as described above, and
1646 which must be a dictionary, as keyword arguments to the tool's
1651 function can use the arguments to modify the tool's behavior
1652 by setting up the environment in different ways
1653 or otherwise changing its initialization.
1656 # in tools/my_tool.py:
1657 def generate(env, **kw):
1658 # Sets MY_TOOL to the value of keyword argument 'arg1' or 1.
1659 env['MY_TOOL'] = kw.get('arg1', '1')
1664 env = Environment(tools = ['default', ('my_tool', {'arg1': 'abc'})],
1668 The tool definition (i.e. my_tool()) can use the PLATFORM variable from
1669 the environment it receives to customize the tool for different platforms.
1671 If no tool list is specified, then SCons will auto-detect the installed
1672 tools using the PATH variable in the ENV construction variable and the
1673 platform name when the Environment is constructed. Changing the PATH
1674 variable after the Environment is constructed will not cause the tools to
1677 SCons supports the following tool specifications out of the box:
1757 Additionally, there is a "tool" named
1759 which configures the
1760 environment with a default set of tools for the current platform.
1762 On posix and cygwin platforms
1763 the GNU tools (e.g. gcc) are preferred by SCons,
1764 on Windows the Microsoft tools (e.g. msvc)
1765 followed by MinGW are preferred by SCons,
1766 and in OS/2 the IBM tools (e.g. icc) are preferred by SCons.
1770 Build rules are specified by calling a construction
1771 environment's builder methods.
1772 The arguments to the builder methods are
1774 (a list of targets to be built,
1778 (a list of sources to be built,
1779 usually file names).
1781 Because long lists of file names
1782 can lead to a lot of quoting,
1787 and a same-named environment method
1788 that split a single string
1789 into a list, separated on
1790 strings of white-space characters.
1791 (These are similar to the
1792 string.split() method
1793 from the standard Python library,
1794 but work even if the input isn't a string.)
1796 Like all Python arguments,
1797 the target and source arguments to a builder method
1798 can be specified either with or without
1799 the "target" and "source" keywords.
1800 When the keywords are omitted,
1801 the target is first,
1802 followed by the source.
1803 The following are equivalent examples of calling the Program builder method:
1806 env.Program('bar', ['bar.c', 'foo.c'])
1807 env.Program('bar', Split('bar.c foo.c'))
1808 env.Program('bar', env.Split('bar.c foo.c'))
1809 env.Program(source = ['bar.c', 'foo.c'], target = 'bar')
1810 env.Program(target = 'bar', Split('bar.c foo.c'))
1811 env.Program(target = 'bar', env.Split('bar.c foo.c'))
1812 env.Program('bar', source = string.split('bar.c foo.c'))
1815 Target and source file names
1816 that are not absolute path names
1817 (that is, do not begin with
1824 an optional drive letter)
1825 are interpreted relative to the directory containing the
1831 on a path name means that the rest of the file name
1832 is interpreted relative to
1833 the directory containing
1839 is followed by a directory separator character
1840 (slash or backslash).
1845 # The comments describing the targets that will be built
1846 # assume these calls are in a SConscript file in the
1847 # a subdirectory named "subdir".
1849 # Builds the program "subdir/foo" from "subdir/foo.c":
1850 env.Program('foo', 'foo.c')
1852 # Builds the program "/tmp/bar" from "subdir/bar.c":
1853 env.Program('/tmp/bar', 'bar.c')
1855 # An initial '#' or '#/' are equivalent; the following
1856 # calls build the programs "foo" and "bar" (in the
1857 # top-level SConstruct directory) from "subdir/foo.c" and
1858 # "subdir/bar.c", respectively:
1859 env.Program('#foo', 'foo.c')
1860 env.Program('#/bar', 'bar.c')
1862 # Builds the program "other/foo" (relative to the top-level
1863 # SConstruct directory) from "subdir/foo.c":
1864 env.Program('#other/foo', 'foo.c')
1867 When the target shares the same base name
1868 as the source and only the suffix varies,
1869 and if the builder method has a suffix defined for the target file type,
1870 then the target argument may be omitted completely,
1873 will deduce the target file name from
1874 the source file name.
1875 The following examples all build the
1881 (on Windows systems)
1882 from the bar.c source file:
1885 env.Program(target = 'bar', source = 'bar.c')
1886 env.Program('bar', source = 'bar.c')
1887 env.Program(source = 'bar.c')
1888 env.Program('bar.c')
1893 keyword argument may be specified
1894 when calling a Builder.
1896 all source file strings that are not absolute paths
1897 will be interpreted relative to the specified
1899 The following example will build the
1904 program from the files
1910 env.Program('build/prog', ['f1.c', 'f2.c'], srcdir='src')
1913 It is possible to override or add construction variables when calling a
1914 builder method by passing additional keyword arguments.
1915 These overridden or added
1916 variables will only be in effect when building the target, so they will not
1917 affect other parts of the build. For example, if you want to add additional
1918 libraries for just one program:
1921 env.Program('hello', 'hello.c', LIBS=['gl', 'glut'])
1924 or generate a shared library with a non-standard suffix:
1927 env.SharedLibrary('word', 'word.cpp',
1929 LIBSUFFIXES=['.ocx'])
1932 (Note that both the $SHLIBSUFFIX and $LIBSUFFIXES variables must be set
1933 if you want SCons to search automatically
1934 for dependencies on the non-standard library names;
1935 see the descriptions of these variables, below, for more information.)
1937 It is also possible to use the
1939 keyword argument in an override:
1942 env = Program('hello', 'hello.c', parse_flags = '-Iinclude -DEBUG -lm')
1945 This example adds 'include' to
1952 Although the builder methods defined by
1955 methods of a construction environment object,
1956 they may also be called without an explicit environment:
1959 Program('hello', 'hello.c')
1960 SharedLibrary('word', 'word.cpp')
1964 the methods are called internally using a default construction
1965 environment that consists of the tools and values that
1967 has determined are appropriate for the local system.
1969 Builder methods that can be called without an explicit
1970 environment may be called from custom Python modules that you
1971 import into an SConscript file by adding the following
1972 to the Python module:
1975 from SCons.Script import *
1978 All builder methods return a list-like object
1979 containing Nodes that
1980 represent the target or targets that will be built.
1983 is an internal SCons object
1985 build targets or sources.
1987 The returned Node-list object
1988 can be passed to other builder methods as source(s)
1989 or passed to any SCons function or method
1990 where a filename would normally be accepted.
1991 For example, if it were necessary
1994 flag when compiling one specific object file:
1997 bar_obj_list = env.StaticObject('bar.c', CPPDEFINES='-DBAR')
1998 env.Program(source = ['foo.c', bar_obj_list, 'main.c'])
2001 Using a Node in this way
2002 makes for a more portable build
2003 by avoiding having to specify
2004 a platform-specific object suffix
2005 when calling the Program() builder method.
2007 Note that Builder calls will automatically "flatten"
2008 the source and target file lists,
2009 so it's all right to have the bar_obj list
2010 return by the StaticObject() call
2011 in the middle of the source file list.
2012 If you need to manipulate a list of lists returned by Builders
2013 directly using Python,
2014 you can either build the list by hand:
2017 foo = Object('foo.c')
2018 bar = Object('bar.c')
2019 objects = ['begin.o'] + foo + ['middle.o'] + bar + ['end.o']
2020 for object in objects:
2026 function supplied by scons
2027 to create a list containing just the Nodes,
2028 which may be more convenient:
2031 foo = Object('foo.c')
2032 bar = Object('bar.c')
2033 objects = Flatten(['begin.o', foo, 'middle.o', bar, 'end.o'])
2034 for object in objects:
2038 Note also that because Builder calls return
2039 a list-like object, not an actual Python list,
2044 operator to append Builder results to a Python list.
2045 Because the list and the object are different types,
2046 Python will not update the original list in place,
2047 but will instead create a new Node-list object
2048 containing the concatenation of the list
2049 elements and the Builder results.
2050 This will cause problems for any other Python variables
2051 in your SCons configuration
2052 that still hold on to a reference to the original list.
2053 Instead, use the Python
2055 method to make sure the list is updated in-place.
2061 # Do NOT use += as follows:
2063 # object_files += Object('bar.c')
2065 # It will not update the object_files list in place.
2067 # Instead, use the .extend() method:
2068 object_files.extend(Object('bar.c'))
2072 The path name for a Node's file may be used
2073 by passing the Node to the Python-builtin
2078 bar_obj_list = env.StaticObject('bar.c', CPPDEFINES='-DBAR')
2079 print "The path to bar_obj is:", str(bar_obj_list[0])
2082 Note again that because the Builder call returns a list,
2083 we have to access the first element in the list
2084 .B (bar_obj_list[0])
2085 to get at the Node that actually represents
2088 Builder calls support a
2090 keyword argument that
2091 specifies that the Builder's action(s)
2093 after changing directory.
2097 a string or a directory Node,
2098 scons will change to the specified directory.
2101 is not a string or Node
2103 then scons will change to the
2104 target file's directory.
2107 # scons will change to the "sub" subdirectory
2108 # before executing the "cp" command.
2109 env.Command('sub/dir/foo.out', 'sub/dir/foo.in',
2110 "cp dir/foo.in dir/foo.out",
2113 # Because chdir is not a string, scons will change to the
2114 # target's directory ("sub/dir") before executing the
2116 env.Command('sub/dir/foo.out', 'sub/dir/foo.in',
2117 "cp foo.in foo.out",
2121 Note that scons will
2123 automatically modify
2125 construction variables like
2129 when using the chdir
2130 keyword argument--that is,
2131 the expanded file names
2132 will still be relative to
2133 the top-level SConstruct directory,
2134 and consequently incorrect
2135 relative to the chdir directory.
2136 If you use the chdir keyword argument,
2137 you will typically need to supply a different
2143 to use just the filename portion of the
2147 provides the following builder methods:
2149 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2150 '\" BEGIN GENERATED BUILDER DESCRIPTIONS
2152 '\" The descriptions below of the various SCons Builders are generated
2153 '\" from the .xml files that live next to the various Python modules in
2154 '\" the build enginer library. If you're reading this [gnt]roff file
2155 '\" with an eye towards patching this man page, you can still submit
2156 '\" a diff against this text, but it will have to be translated to a
2157 '\" diff against the underlying .xml file before the patch is actually
2158 '\" accepted. If you do that yourself, it will make it easier to
2159 '\" integrate the patch.
2161 '\" BEGIN GENERATED BUILDER DESCRIPTIONS
2162 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2164 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2165 '\" END GENERATED BUILDER DESCRIPTIONS
2167 '\" The descriptions above of the various SCons Builders are generated
2168 '\" from the .xml files that live next to the various Python modules in
2169 '\" the build enginer library. If you're reading this [gnt]roff file
2170 '\" with an eye towards patching this man page, you can still submit
2171 '\" a diff against this text, but it will have to be translated to a
2172 '\" diff against the underlying .xml file before the patch is actually
2173 '\" accepted. If you do that yourself, it will make it easier to
2174 '\" integrate the patch.
2176 '\" END GENERATED BUILDER DESCRIPTIONS
2177 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2181 targets of builder methods automatically depend on their sources.
2182 An explicit dependency can
2183 be specified using the
2185 method of a construction environment (see below).
2190 source files for various programming languages,
2191 so the dependencies do not need to be specified explicitly.
2192 By default, SCons can
2195 Fortran source files with
2197 (POSIX systems only),
2202 and assembly language files with
2204 (POSIX systems only),
2209 for C preprocessor dependencies.
2210 SCons also has default support
2211 for scanning D source files,
2212 You can also write your own Scanners
2213 to add support for additional source file types.
2214 These can be added to the default
2215 Scanner object used by the
2217 .BR StaticObject (),
2220 Builders by adding them
2222 .B SourceFileScanner
2225 See the section "Scanner Objects,"
2226 below, for a more information about
2227 defining your own Scanner objects.
2229 .SS Methods and Functions to Do Things
2230 In addition to Builder methods,
2232 provides a number of other construction environment methods
2233 and global functions to
2234 manipulate the build configuration.
2236 Usually, a construction environment method
2237 and global function with the same name both exist
2238 so that you don't have to remember whether
2239 to a specific bit of functionality
2240 must be called with or without a construction environment.
2241 In the following list,
2242 if you call something as a global function
2245 .RI Function( arguments )
2247 and if you call something through a construction
2248 environment it looks like:
2250 .RI env.Function( arguments )
2252 If you can call the functionality in both ways,
2253 then both forms are listed.
2255 Global functions may be called from custom Python modules that you
2256 import into an SConscript file by adding the following
2257 to the Python module:
2260 from SCons.Script import *
2263 Except where otherwise noted,
2265 construction environment method
2267 provide the exact same functionality.
2268 The only difference is that,
2270 calling the functionality through a construction environment will
2271 substitute construction variables into
2272 any supplied strings.
2276 env = Environment(FOO = 'foo')
2281 In the above example,
2282 the first call to the global
2284 function will actually add a target named
2286 to the list of default targets,
2287 while the second call to the
2289 construction environment method
2290 will expand the value
2291 and add a target named
2293 to the list of default targets.
2294 For more on construction variable expansion,
2295 see the next section on
2296 construction variables.
2298 Construction environment methods
2299 and global functions supported by
2303 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2305 .RI Action( action ", [" strfunction ", " varlist ])
2307 .RI env.Action( action ", [" strfunction ", " varlist ])
2308 Creates an Action object for
2311 See the section "Action Objects,"
2312 below, for a complete explanation of the arguments and behavior.
2316 form of the invocation will expand
2317 construction variables in any arguments strings,
2321 at the time it is called
2322 using the construction variables in the
2324 construction environment through which
2329 form delays all variable expansion
2330 until the Action object is actually used.
2332 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2334 .RI AddMethod( object, function ", [" name ])
2336 .RI env.AddMethod( function ", [" name ])
2337 When called with the
2344 as the specified method
2346 When called with the
2347 .BR env.AddMethod ()
2351 to the construction environment
2353 as the specified method
2362 itself is used for the method name.
2367 # Note that the first argument to the function to
2368 # be attached as a method must be the object through
2369 # which the method will be called; the Python
2370 # convention is to call it 'self'.
2371 def my_method(self, arg):
2372 print "my_method() got", arg
2374 # Use the global AddMethod() function to add a method
2375 # to the Environment class. This
2376 AddMethod(Environment, my_method)
2378 env.my_method('arg')
2380 # Add the function as a method, using the function
2381 # name for the method call.
2383 env.AddMethod(my_method, 'other_method_name')
2384 env.other_method_name('another arg')
2387 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2389 .RI AddOption( arguments )
2390 This function adds a new command-line option to be recognized.
2393 are the same as supported by the standard Python
2394 .BR optparse.add_option ()
2395 method (with a few additional capabilities noted below);
2396 see the documentation for
2398 for a thorough discussion of its option-processing capabities.
2399 (Note that although the
2401 module was not a standard module until Python 2.3,
2403 contains a compatible version of the module
2404 that is used to provide identical functionality
2405 when run by earlier Python versions.)
2407 In addition to the arguments and values supported by the
2408 .B optparse.add_option ()
2412 function allows you to set the
2416 (a string with just the question mark)
2417 to indicate that the specified long option(s) take(s) an
2427 may be used to supply the "default"
2428 value that should be used when the
2429 option is specified on the command line
2430 without an explicit argument.
2434 keyword argument is supplied when calling
2436 the option will have a default value of
2439 Once a new command-line option has been added with
2441 the option value may be accessed using
2444 .BR env.GetOption ().
2445 \" NOTE: in SCons 1.x or 2.0, user options will be settable, but not yet.
2446 \" Uncomment this when that works. See tigris issue 2105.
2447 \" The value may also be set, using
2450 \" .BR env.SetOption (),
2451 \" if conditions in a
2453 \" require overriding any default value.
2454 \" Note, however, that a
2455 \" value specified on the command line will
2457 \" override a value set by any SConscript file.
2461 strings for the new option(s)
2462 will be displayed by the
2467 (the latter only if no other help text is
2468 specified in the SConscript files).
2469 The help text for the local options specified by
2471 will appear below the SCons options themselves,
2475 The options will appear in the help text
2476 in the order in which the
2483 AddOption('--prefix',
2485 nargs=1, type='string',
2488 help='installation prefix')
2489 env = Environment(PREFIX = GetOption('prefix'))
2492 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2494 .RI AddPostAction( target ", " action )
2496 .RI env.AddPostAction( target ", " action )
2497 Arranges for the specified
2503 The specified action(s) may be
2504 an Action object, or anything that
2505 can be converted into an Action object
2508 When multiple targets are supplied,
2509 the action may be called multiple times,
2510 once after each action that generates
2511 one or more targets in the list.
2513 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2515 .RI AddPreAction( target ", " action )
2517 .RI env.AddPreAction( target ", " action )
2518 Arranges for the specified
2521 before the specified
2524 The specified action(s) may be
2525 an Action object, or anything that
2526 can be converted into an Action object
2529 When multiple targets are specified,
2530 the action(s) may be called multiple times,
2531 once before each action that generates
2532 one or more targets in the list.
2534 Note that if any of the targets are built in multiple steps,
2535 the action will be invoked just
2536 before the "final" action that specifically
2537 generates the specified target(s).
2538 For example, when building an executable program
2539 from a specified source
2541 file via an intermediate object file:
2544 foo = Program('foo.c')
2545 AddPreAction(foo, 'pre_action')
2550 would be executed before
2552 calls the link command that actually
2553 generates the executable program binary
2555 not before compiling the
2557 file into an object file.
2559 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2561 .RI Alias( alias ", [" targets ", [" action ]])
2563 .RI env.Alias( alias ", [" targets ", [" action ]])
2564 Creates one or more phony targets that
2565 expand to one or more other targets.
2570 can be specified that will be executed
2571 whenever the any of the alias targets are out-of-date.
2572 Returns the Node object representing the alias,
2573 which exists outside of any file system.
2574 This Node object, or the alias name,
2575 may be used as a dependency of any other target,
2576 including another alias.
2578 can be called multiple times for the same
2579 alias to add additional targets to the alias,
2580 or additional actions to the list for this alias.
2586 Alias('install', '/usr/bin')
2587 Alias(['install', 'install-lib'], '/usr/local/lib')
2589 env.Alias('install', ['/usr/local/bin', '/usr/local/lib'])
2590 env.Alias('install', ['/usr/local/man'])
2592 env.Alias('update', ['file1', 'file2'], "update_database $SOURCES")
2595 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2597 .RI AllowSubstExceptions([ exception ", ...])"
2598 Specifies the exceptions that will be allowed
2599 when expanding construction variables.
2601 any construction variable expansions that generate a
2605 exception will expand to a
2607 (a null string) and not cause scons to fail.
2608 All exceptions not in the specified list
2609 will generate an error message
2610 and terminate processing.
2613 .B AllowSubstExceptions
2614 is called multiple times,
2615 each call completely overwrites the previous list
2616 of allowed exceptions.
2621 # Requires that all construction variable names exist.
2622 # (You may wish to do this if you want to enforce strictly
2623 # that all construction variables must be defined before use.)
2624 AllowSubstExceptions()
2626 # Also allow a string containing a zero-division expansion
2627 # like '${1 / 0}' to evalute to ''.
2628 AllowSubstExceptions(IndexError, NameError, ZeroDivisionError)
2631 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2633 .RI AlwaysBuild( target ", ...)"
2635 .RI env.AlwaysBuild( target ", ...)"
2638 so that it is always assumed to be out of date,
2639 and will always be rebuilt if needed.
2642 does not add its target(s) to the default target list,
2643 so the targets will only be built
2644 if they are specified on the command line,
2645 or are a dependent of a target specified on the command line--but
2648 be built if so specified.
2649 Multiple targets can be passed in to a single call to
2652 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2654 .RI env.Append( key = val ", [...])"
2655 Appends the specified keyword arguments
2656 to the end of construction variables in the environment.
2657 If the Environment does not have
2658 the specified construction variable,
2659 it is simply added to the environment.
2660 If the values of the construction variable
2661 and the keyword argument are the same type,
2662 then the two values will be simply added together.
2663 Otherwise, the construction variable
2664 and the value of the keyword argument
2665 are both coerced to lists,
2666 and the lists are added together.
2667 (See also the Prepend method, below.)
2672 env.Append(CCFLAGS = ' -g', FOO = ['foo.yyy'])
2675 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2677 .RI env.AppendENVPath( name ", " newpath ", [" envname ", " sep ])
2678 This appends new path elements to the given path in the
2679 specified external environment
2683 any particular path once (leaving the last one it encounters and
2684 ignoring the rest, to preserve path order),
2685 and to help assure this,
2686 will normalize all paths (using
2689 .BR os.path.normcase ).
2690 This can also handle the
2691 case where the given old path variable is a list instead of a
2692 string, in which case a list will be returned instead of a string.
2697 print 'before:',env['ENV']['INCLUDE']
2698 include_path = '/foo/bar:/foo'
2699 env.AppendENVPath('INCLUDE', include_path)
2700 print 'after:',env['ENV']['INCLUDE']
2704 after: /biz:/foo/bar:/foo
2707 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2709 .RI env.AppendUnique( key = val ", [...])"
2710 Appends the specified keyword arguments
2711 to the end of construction variables in the environment.
2712 If the Environment does not have
2713 the specified construction variable,
2714 it is simply added to the environment.
2715 If the construction variable being appended to is a list,
2716 then any value(s) that already exist in the
2717 construction variable will
2719 be added again to the list.
2724 env.AppendUnique(CCFLAGS = '-g', FOO = ['foo.yyy'])
2727 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2730 A factory function that
2731 returns a Builder object
2732 to be used to fetch source files
2734 The returned Builder
2735 is intended to be passed to the
2742 env.SourceCode('.', env.BitKeeper())
2745 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2747 .RI BuildDir( build_dir ", " src_dir ", [" duplicate ])
2749 .RI env.BuildDir( build_dir ", " src_dir ", [" duplicate ])
2753 .BR env.VariantDir ().
2756 argument becomes the
2761 .BR env.VariantDir ().
2762 (This will be officially deprecated some day.)
2764 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2766 .RI Builder( action ", [" arguments ])
2768 .RI env.Builder( action ", [" arguments ])
2769 Creates a Builder object for
2772 See the section "Builder Objects,"
2773 below, for a complete explanation of the arguments and behavior.
2777 form of the invocation will expand
2778 construction variables in any arguments strings,
2782 at the time it is called
2783 using the construction variables in the
2785 construction environment through which
2790 form delays all variable expansion
2791 until after the Builder object is actually called.
2793 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2795 .RI CacheDir( cache_dir )
2797 .RI env.CacheDir( cache_dir )
2800 will maintain a cache of derived files in
2802 The derived files in the cache will be shared
2803 among all the builds using the same
2810 disables derived file caching.
2814 will only affect targets built
2815 through the specified construction environment.
2818 sets a global default
2819 that will be used by all targets built
2820 through construction environments
2831 finds a derived file that needs to be rebuilt,
2832 it will first look in the cache to see if a
2833 derived file has already been built
2834 from identical input files and an identical build action
2835 (as incorporated into the MD5 build signature).
2838 will retrieve the file from the cache.
2839 If the derived file is not present in the cache,
2842 then place a copy of the built file in the cache
2843 (identified by its MD5 build signature),
2844 so that it may be retrieved by other
2845 builds that need to build the same derived file
2846 from identical inputs.
2850 may be disabled for any invocation
2859 will place a copy of
2861 derived files in the cache,
2862 even if they already existed
2863 and were not built by this invocation.
2864 This is useful to populate a cache
2867 is added to a build,
2876 "Retrieved `file' from cache,"
2879 option is being used.
2884 will print the action that
2886 have been used to build the file,
2887 without any indication that
2888 the file was actually retrieved from the cache.
2889 This is useful to generate build logs
2890 that are equivalent regardless of whether
2891 a given derived file has been built in-place
2892 or retrieved from the cache.
2896 method can be used to disable caching of specific files. This can be
2897 useful if inputs and/or outputs of some tool are impossible to
2898 predict or prohibitively large.
2900 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2902 .RI Clean( targets ", " files_or_dirs )
2904 .RI env.Clean( targets ", " files_or_dirs )
2905 This specifies a list of files or directories which should be removed
2906 whenever the targets are specified with the
2908 command line option.
2909 The specified targets may be a list
2910 or an individual target.
2914 and create new targets or add files and directories to the
2915 clean list for the specified targets.
2917 Multiple files or directories should be specified
2918 either as separate arguments to the
2920 method, or as a list.
2922 will also accept the return value of any of the construction environment
2928 function overrides calling
2930 for the same target,
2931 and any targets passed to both functions will
2940 Clean('foo', ['bar', 'baz'])
2941 Clean('dist', env.Program('hello', 'hello.c'))
2942 Clean(['foo', 'bar'], 'something_else_to_clean')
2945 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2947 .RI Command( target ", " source ", " action ", [" key = val ", ...])"
2949 .RI env.Command( target ", " source ", " action ", [" key = val ", ...])"
2950 Executes a specific action
2951 (or list of actions)
2952 to build a target file or files.
2953 This is more convenient
2954 than defining a separate Builder object
2955 for a single special-case build.
2957 As a special case, the
2959 keyword argument can
2962 that will be used to scan the sources.
2966 if any of the sources will be directories
2967 that must be scanned on-disk for
2968 changes to files that aren't
2969 already specified in other Builder of function calls.)
2971 Any other keyword arguments specified override any
2972 same-named existing construction variables.
2974 An action can be an external command,
2975 specified as a string,
2976 or a callable Python object;
2977 see "Action Objects," below,
2978 for more complete information.
2979 Also note that a string specifying an external command
2980 may be preceded by an
2983 to suppress printing the command in question,
2987 to ignore the exit status of the external command.
2992 env.Command('foo.out', 'foo.in',
2993 "$FOO_BUILD < $SOURCES > $TARGET")
2995 env.Command('bar.out', 'bar.in',
2997 "$BAR_BUILD < $SOURCES > $TARGET"],
2998 ENV = {'PATH' : '/usr/local/bin/'})
3000 def rename(env, target, source):
3002 os.rename('.tmp', str(target[0]))
3004 env.Command('baz.out', 'baz.in',
3005 ["$BAZ_BUILD < $SOURCES > .tmp",
3012 function will usually assume, by default,
3013 that the specified targets and/or sources are Files,
3014 if no other part of the configuration
3015 identifies what type of entry it is.
3016 If necessary, you can explicitly specify
3017 that targets or source nodes should
3018 be treated as directoriese
3028 env.Command('ddd.list', Dir('ddd'), 'ls -l $SOURCE > $TARGET')
3030 env['DISTDIR'] = 'destination/directory'
3031 env.Command(env.Dir('$DISTDIR')), None, make_distdir)
3035 (Also note that SCons will usually
3036 automatically create any directory necessary to hold a target file,
3037 so you normally don't need to create directories by hand.)
3039 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3041 .RI Configure( env ", [" custom_tests ", " conf_dir ", " log_file ", " config_h ])
3043 .RI env.Configure([ custom_tests ", " conf_dir ", " log_file ", " config_h ])
3044 Creates a Configure object for integrated
3045 functionality similar to GNU autoconf.
3046 See the section "Configure Contexts,"
3047 below, for a complete explanation of the arguments and behavior.
3049 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3051 .RI env.Clone([ key = val ", ...])"
3052 Return a separate copy of a construction environment.
3053 If there are any keyword arguments specified,
3054 they are added to the returned copy,
3055 overwriting any existing values
3062 env3 = env.Clone(CCFLAGS = '-g')
3065 Additionally, a list of tools and a toolpath may be specified, as in
3066 the Environment constructor:
3069 def MyTool(env): env['FOO'] = 'bar'
3070 env4 = env.Clone(tools = ['msvc', MyTool])
3075 keyword argument is also recognized:
3078 # create an environment for compiling programs that use wxWidgets
3079 wx_env = env.Clone(parse_flags = '!wx-config --cflags --cxxflags')
3082 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3084 .RI env.Copy([ key = val ", ...])"
3085 A now-deprecated synonym for
3088 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3090 .RI env.CVS( repository ", " module )
3091 A factory function that
3092 returns a Builder object
3093 to be used to fetch source files
3097 The returned Builder
3098 is intended to be passed to the
3102 The optional specified
3104 will be added to the beginning
3105 of all repository path names;
3106 this can be used, in essence,
3107 to strip initial directory names
3108 from the repository path names,
3109 so that you only have to
3110 replicate part of the repository
3111 directory hierarchy in your
3112 local build directory.
3117 # Will fetch foo/bar/src.c
3118 # from /usr/local/CVSROOT/foo/bar/src.c.
3119 env.SourceCode('.', env.CVS('/usr/local/CVSROOT'))
3121 # Will fetch bar/src.c
3122 # from /usr/local/CVSROOT/foo/bar/src.c.
3123 env.SourceCode('.', env.CVS('/usr/local/CVSROOT', 'foo'))
3126 # from /usr/local/CVSROOT/foo/bar/src.c.
3127 env.SourceCode('.', env.CVS('/usr/local/CVSROOT', 'foo/bar'))
3130 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3132 .RI Decider( function )
3134 .RI env.Decider( function )
3135 Specifies that all up-to-date decisions for
3136 targets built through this construction environment
3137 will be handled by the specified
3141 can be one of the following strings
3142 that specify the type of decision function
3148 Specifies that a target shall be considered out of date and rebuilt
3149 if the dependency's timestamp is newer than the target file's timestamp.
3150 This is the behavior of the classic Make utility,
3153 can be used a synonym for
3154 .BR timestamp-newer .
3158 Specifies that a target shall be considered out of date and rebuilt
3159 if the dependency's timestamp is different than the
3160 timestamp recorded the last time the target was built.
3161 This provides behavior very similar to the classic Make utility
3162 (in particular, files are not opened up so that their
3163 contents can be checksummed)
3164 except that the target will also be rebuilt if a
3165 dependency file has been restored to a version with an
3167 timestamp, such as can happen when restoring files from backup archives.
3171 Specifies that a target shall be considered out of date and rebuilt
3172 if the dependency's content has changed sine the last time
3173 the target was built,
3174 as determined be performing an MD5 checksum
3175 on the dependency's contents
3176 and comparing it to the checksum recorded the
3177 last time the target was built.
3179 can be used as a synonym for
3184 Specifies that a target shall be considered out of date and rebuilt
3185 if the dependency's content has changed sine the last time
3186 the target was built,
3187 except that dependencies with a timestamp that matches
3188 the last time the target was rebuilt will be
3189 assumed to be up-to-date and
3192 This provides behavior very similar
3195 behavior of always checksumming file contents,
3196 with an optimization of not checking
3197 the contents of files whose timestamps haven't changed.
3198 The drawback is that SCons will
3200 detect if a file's content has changed
3201 but its timestamp is the same,
3202 as might happen in an automated script
3205 and runs the build again,
3206 all within a single second.
3213 # Use exact timestamp matches by default.
3214 Decider('timestamp-match')
3216 # Use MD5 content signatures for any targets built
3217 # with the attached construction environment.
3218 env.Decider('content')
3222 In addition to the above already-available functions,
3225 argument may be an actual Python function
3226 that takes the following three arguments:
3230 The Node (file) which
3234 if it has "changed" since the last tme
3235 .I target was built.
3238 The Node (file) being built.
3240 this is what should get rebuilt
3246 Stored information about the state of the
3251 This can be consulted to match various
3252 file characteristics
3253 such as the timestamp,
3254 size, or content signature.
3265 has "changed" since the last time
3269 (indicating that the target
3276 (indicating that the target should
3279 Note that the decision can be made
3280 using whatever criteria are appopriate.
3281 Ignoring some or all of the function arguments
3282 is perfectly normal.
3287 def my_decider(dependency, target, prev_ni):
3288 return not os.path.exists(str(target))
3290 env.Decider(my_decider)
3293 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3295 .RI Default( targets )
3297 .RI env.Default( targets )
3298 This specifies a list of default targets,
3299 which will be built by
3301 if no explicit targets are given on the command line.
3305 and add to the list of default targets.
3307 Multiple targets should be specified as
3308 separate arguments to the
3310 method, or as a list.
3312 will also accept the Node returned by any
3313 of a construction environment's
3319 Default('foo', 'bar', 'baz')
3320 env.Default(['a', 'b', 'c'])
3321 hello = env.Program('hello', 'hello.c')
3329 will clear all default targets.
3332 will add to the (now empty) default-target list
3335 The current list of targets added using the
3337 function or method is available in the
3342 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3344 .RI DefaultEnvironment([ args ])
3345 Creates and returns a default construction environment object.
3346 This construction environment is used internally by SCons
3347 in order to execute many of the global functions in this list,
3348 and to fetch source files transparently
3349 from source code management systems.
3351 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3353 .RI Depends( target ", " dependency )
3355 .RI env.Depends( target ", " dependency )
3356 Specifies an explicit dependency;
3368 (usually the path name of a file or directory)
3370 or a list of strings or Node objects
3371 (such as returned by a Builder call).
3372 This should only be necessary
3373 for cases where the dependency
3374 is not caught by a Scanner
3380 env.Depends('foo', 'other-input-file-for-foo')
3382 mylib = env.Library('mylib.c')
3383 installed_lib = env.Install('lib', mylib)
3384 bar = env.Program('bar.c')
3386 # Arrange for the library to be copied into the installation
3387 # directory before trying to build the "bar" program.
3388 # (Note that this is for example only. A "real" library
3389 # dependency would normally be configured through the $LIBS
3390 # and $LIBPATH variables, not using an env.Depends() call.)
3392 env.Depends(bar, installed_lib)
3395 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3397 .RI env.Dictionary([ vars ])
3398 Returns a dictionary object
3399 containing copies of all of the
3400 construction variables in the environment.
3401 If there are any variable names specified,
3402 only the specified construction
3403 variables are returned in the dictionary.
3408 dict = env.Dictionary()
3409 cc_dict = env.Dictionary('CC', 'CCFLAGS', 'CCCOM')
3412 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3414 .RI Dir( name ", [" directory ])
3416 .RI env.Dir( name ", [" directory ])
3417 This returns a Directory Node,
3418 an object that represents the specified directory
3421 can be a relative or absolute path.
3423 is an optional directory that will be used as the parent directory.
3426 is specified, the current script's directory is used as the parent.
3430 is a list, SCons returns a list of Dir nodes.
3431 Construction variables are expanded in
3434 Directory Nodes can be used anywhere you
3435 would supply a string as a directory name
3436 to a Builder method or function.
3437 Directory Nodes have attributes and methods
3438 that are useful in many situations;
3439 see "File and Directory Nodes," below.
3441 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3443 .RI env.Dump([ key ])
3444 Returns a pretty printable representation of the environment.
3448 should be a string containing the name of the variable of interest.
3453 print env.Dump('CCCOM')
3458 \&'$CC $CCFLAGS $CPPFLAGS $_CPPDEFFLAGS $_CPPINCFLAGS -c -o $TARGET $SOURCES'
3469 'ARCOM': '$AR $ARFLAGS $TARGET $SOURCES\n$RANLIB $RANLIBFLAGS $TARGET',
3472 'ASCOM': '$AS $ASFLAGS -o $TARGET $SOURCES',
3477 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3479 .RI EnsurePythonVersion( major ", " minor )
3481 .RI env.EnsurePythonVersion( major ", " minor )
3482 Ensure that the Python version is at least
3485 print out an error message and exit SCons with a non-zero exit code if the
3486 actual Python version is not late enough.
3491 EnsurePythonVersion(2,2)
3494 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3496 .RI EnsureSConsVersion( major ", " minor ", [" revision ])
3498 .RI env.EnsureSConsVersion( major ", " minor ", [" revision ])
3499 Ensure that the SCons version is at least
3502 .IR major.minor.revision .
3507 print out an error message and exit SCons with a non-zero exit code if the
3508 actual SCons version is not late enough.
3513 EnsureSConsVersion(0,14)
3515 EnsureSConsVersion(0,96,90)
3518 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3520 .RI Environment([ key = value ", ...])"
3522 .RI env.Environment([ key = value ", ...])"
3523 Return a new construction environment
3524 initialized with the specified
3528 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3530 .RI Execute( action ", [" strfunction ", " varlist ])
3532 .RI env.Execute( action ", [" strfunction ", " varlist ])
3533 Executes an Action object.
3536 may be an Action object
3537 (see the section "Action Objects,"
3538 below, for a complete explanation of the arguments and behavior),
3539 or it may be a command-line string,
3541 or executable Python function,
3542 each of which will be converted
3543 into an Action object
3545 The exit value of the command
3546 or return value of the Python function
3549 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3553 .RI env.Exit([ value ])
3559 A default exit value of
3562 is used if no value is specified.
3564 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3568 .RI env.Export( vars )
3571 to export a list of variables from the current
3572 SConscript file to all other SConscript files.
3573 The exported variables are kept in a global collection,
3574 so subsequent calls to
3576 will over-write previous exports that have the same name.
3577 Multiple variable names can be passed to
3579 as separate arguments or as a list. A dictionary can be used to map
3580 variables to a different name when exported. Both local variables and
3581 global variables can be exported.
3587 # Make env available for all SConscript files to Import().
3591 # Make env and package available for all SConscript files:.
3592 Export("env", "package")
3594 # Make env and package available for all SConscript files:
3595 Export(["env", "package"])
3597 # Make env available using the name debug:.
3598 Export({"debug":env})
3604 function supports an
3606 argument that makes it easier to to export a variable or
3607 set of variables to a single SConscript file.
3608 See the description of the
3612 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3614 .RI File( name ", [" directory ])
3616 .RI env.File( name ", [" directory ])
3619 an object that represents the specified file
3622 can be a relative or absolute path.
3624 is an optional directory that will be used as the parent directory.
3628 is a list, SCons returns a list of File nodes.
3629 Construction variables are expanded in
3632 File Nodes can be used anywhere you
3633 would supply a string as a file name
3634 to a Builder method or function.
3635 File Nodes have attributes and methods
3636 that are useful in many situations;
3637 see "File and Directory Nodes," below.
3639 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3641 .RI FindFile( file ", " dirs )
3643 .RI env.FindFile( file ", " dirs )
3646 in the path specified by
3649 may be a list of file names or a single file name. In addition to searching
3650 for files that exist in the filesytem, this function also searches for
3651 derived files that have not yet been built.
3656 foo = env.FindFile('foo', ['dir1', 'dir2'])
3659 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3661 .RI FindInstalledFiles( )
3663 .RI env.FindInstalledFiles( )
3664 Returns the list of targets set up by the
3670 This function serves as a convenient method to select the contents of
3676 Install( '/bin', [ 'executable_a', 'executable_b' ] )
3678 # will return the file node list
3679 # [ '/bin/executable_a', '/bin/executable_b' ]
3680 FindInstalledFiles()
3682 Install( '/lib', [ 'some_library' ] )
3684 # will return the file node list
3685 # [ '/bin/executable_a', '/bin/executable_b', '/lib/some_library' ]
3686 FindInstalledFiles()
3689 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3691 .RI FindSourceFiles( node = '"."' )
3693 .RI env.FindSourceFiles( node = '"."' )
3695 Returns the list of nodes which serve as the source of the built files.
3696 It does so by inspecting the dependency tree starting at the optional
3699 which defaults to the '"."'-node. It will then return all leaves of
3701 These are all children which have no further children.
3703 This function is a convenient method to select the contents of a Source
3709 Program( 'src/main_a.c' )
3710 Program( 'src/main_b.c' )
3711 Program( 'main_c.c' )
3713 # returns ['main_c.c', 'src/main_a.c', 'SConstruct', 'src/main_b.c']
3716 # returns ['src/main_b.c', 'src/main_a.c' ]
3717 FindSourceFiles( 'src' )
3721 As you can see build support files (SConstruct in the above example)
3722 will also be returned by this function.
3724 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3726 .RI FindPathDirs( variable )
3728 (actually a callable Python object)
3729 intended to be used as the
3731 of a Scanner object.
3732 The returned object will look up the specified
3734 in a construction environment
3735 and treat the construction variable's value as a list of
3736 directory paths that should be searched
3744 is generally preferable to
3747 for the following reasons:
3748 1) The returned list will contain all appropriate directories
3749 found in source trees
3753 or in code repositories
3759 2) scons will identify expansions of
3761 that evaluate to the same list of directories as,
3762 in fact, the same list,
3763 and avoid re-scanning the directories for files,
3769 def my_scan(node, env, path, arg):
3770 # Code to scan file contents goes here...
3771 return include_files
3773 scanner = Scanner(name = 'myscanner',
3775 path_function = FindPathDirs('MYPATH'))
3778 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3780 .RI Flatten( sequence )
3782 .RI env.Flatten( sequence )
3783 Takes a sequence (that is, a Python list or tuple)
3784 that may contain nested sequences
3785 and returns a flattened list containing
3786 all of the individual elements in any sequence.
3787 This can be helpful for collecting
3788 the lists returned by calls to Builders;
3789 other Builders will automatically
3790 flatten lists specified as input,
3791 but direct Python manipulation of
3792 these lists does not.
3797 foo = Object('foo.c')
3798 bar = Object('bar.c')
3800 # Because `foo' and `bar' are lists returned by the Object() Builder,
3801 # `objects' will be a list containing nested lists:
3802 objects = ['f1.o', foo, 'f2.o', bar, 'f3.o']
3804 # Passing such a list to another Builder is all right because
3805 # the Builder will flatten the list automatically:
3806 Program(source = objects)
3808 # If you need to manipulate the list directly using Python, you need to
3809 # call Flatten() yourself, or otherwise handle nested lists:
3810 for object in Flatten(objects):
3814 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3816 .RI GetBuildFailures()
3817 Returns a list of exceptions for the
3818 actions that failed while
3819 attempting to build targets.
3820 Each element in the returned list is a
3823 with the following attributes
3824 that record various aspects
3825 of the build failure:
3828 The node that was being built
3829 when the build failure occurred.
3832 The numeric exit status
3833 returned by the command or Python function
3834 that failed when trying to build the
3838 The SCons error string
3839 describing the build failure.
3840 (This is often a generic
3841 message like "Error 2"
3842 to indicate that an executed
3843 command exited with a status of 2.)
3846 The name of the file or
3847 directory that actually caused the failure.
3848 This may be different from the
3852 if an attempt to build a target named
3856 directory could not be created,
3867 The SCons Executor object
3870 This can be used to retrieve
3871 the construction environment used
3872 for the failed action.
3875 The actual SCons Action object that failed.
3876 This will be one specific action
3877 out of the possible list of
3878 actions that would have been
3879 executed to build the target.
3882 The actual expanded command that was executed and failed,
3886 and other construction variables.
3889 .BR GetBuildFailures ()
3891 will always return an empty list
3892 until any build failure has occurred,
3894 .BR GetBuildFailures ()
3895 will always return an empty list
3898 files are being read.
3899 Its primary intended use is
3900 for functions that will be
3901 executed before SCons exits
3902 by passing them to the
3904 .BR atexit.register ()
3911 def print_build_failures():
3912 from SCons.Script import GetBuildFailures
3913 for bf in GetBuildFailures():
3914 print "%s failed: %s" % (bf.node, bf.errstr)
3916 atexit.register(print_build_failures)
3919 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3921 .RI GetBuildPath( file ", [" ... ])
3923 .RI env.GetBuildPath( file ", [" ... ])
3926 path name (or names) for the specified
3934 Nodes or strings representing path names.
3936 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3940 .RI env.GetLaunchDir()
3941 Returns the absolute path name of the directory from which
3943 was initially invoked.
3944 This can be useful when using the
3949 options, which internally
3950 change to the directory in which the
3954 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3956 .RI GetOption( name )
3958 .RI env.GetOption( name )
3959 This function provides a way to query the value of
3960 SCons options set on scons command line
3964 The options supported are:
3970 which corresponds to --cache-debug;
3973 which corresponds to --cache-disable;
3976 which corresponds to --cache-force;
3979 which corresponds to --cache-show;
3982 which corresponds to -c, --clean and --remove;
3985 which corresponds to --config;
3988 which corresponds to -C and --directory;
3991 which corresponds to --diskcheck
3994 which corresponds to --duplicate;
3997 which corresponds to -f, --file, --makefile and --sconstruct;
4000 which corresponds to -h and --help;
4003 which corresponds to --ignore-errors;
4006 which corresponds to --implicit-cache;
4008 .B implicit_deps_changed
4009 which corresponds to --implicit-deps-changed;
4011 .B implicit_deps_unchanged
4012 which corresponds to --implicit-deps-unchanged;
4015 which corresponds to --interact and --interactive;
4018 which corresponds to -k and --keep-going;
4021 which corresponds to --max-drift;
4024 which corresponds to -n, --no-exec, --just-print, --dry-run and --recon;
4027 which corresponds to --no-site-dir;
4030 which corresponds to -j and --jobs;
4033 which corresponds to --profile;
4036 which corresponds to -q and --question;
4039 which corresponds to --random;
4042 which corresponds to -Y, --repository and --srcdir;
4045 which corresponds to -s, --silent and --quiet;
4048 which corresponds to --site-dir;
4051 which corresponds to --stack-size;
4053 .B taskmastertrace_file
4054 which corresponds to --taskmastertrace; and
4057 which corresponds to --warn and --warning.
4061 See the documentation for the
4062 corresponding command line object for information about each specific
4065 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4067 .RI Glob( pattern ", [" ondisk ", " source ", " strings ])
4069 .RI env.Glob( pattern ", [" ondisk ", " source ", " strings ])
4070 Returns Nodes (or strings) that match the specified
4072 relative to the directory of the current
4077 form performs string substition on
4079 and returns whatever matches
4080 the resulting expanded pattern.
4084 uses Unix shell style metacharacters for matching:
4087 * matches everything
4088 ? matches any single character
4089 [seq] matches any character in seq
4090 [!seq] matches any char not in seq
4094 Character matches do
4096 span directory separators.
4105 and source directories
4110 returns a Node (or string, if so configured)
4111 in the local (SConscript) directory
4112 if matching Node is found
4113 anywhere in a corresponding
4114 repository or source directory.
4118 argument may be set to
4120 (or any other non-true value)
4121 to disable the search for matches on disk,
4122 thereby only returning matches among
4123 already-configured File or Dir Nodes.
4124 The default behavior is to
4125 return corresponding Nodes
4126 for any on-disk matches found.
4130 argument may be set to
4132 (or any equivalent value)
4134 when the local directory is a
4136 the returned Nodes should be from the
4137 corresponding source directory,
4138 not the local directory.
4142 argument may be set to
4144 (or any equivalent value)
4147 function return strings, not Nodes,
4148 that represent the matched files or directories.
4149 The returned strings will be relative to
4150 the local (SConscript) directory.
4151 (Note that This may make it easier to perform
4152 arbitrary manipulation of file names,
4153 but if the returned strings are
4154 passed to a different
4157 any Node translation will be relative
4168 Program('foo', Glob('*.c'))
4171 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4173 '\".RI GlobalBuilders( flag )
4177 '\"adds the names of the default builders
4178 '\"(Program, Library, etc.)
4179 '\"to the global name space
4180 '\"so they can be called without an explicit construction environment.
4181 '\"(This is the default.)
4185 '\"the names of the default builders are removed
4186 '\"from the global name space
4187 '\"so that an explicit construction environment is required
4188 '\"to call all builders.
4190 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4194 .RI env.Help( text )
4195 This specifies help text to be printed if the
4197 argument is given to
4201 is called multiple times, the text is appended together in the order
4206 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4208 .RI Ignore( target ", " dependency )
4210 .RI env.Ignore( target ", " dependency )
4211 The specified dependency file(s)
4212 will be ignored when deciding if
4213 the target file(s) need to be rebuilt.
4218 env.Ignore('foo', 'foo.c')
4219 env.Ignore('bar', ['bar1.h', 'bar2.h'])
4222 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4226 .RI env.Import( vars )
4229 to import a list of variables into the current SConscript file. This
4230 will import variables that were exported with
4236 Variables exported by
4239 Multiple variable names can be passed to
4241 as separate arguments or as a list. The variable "*" can be used
4242 to import all variables.
4248 Import("env", "variable")
4249 Import(["env", "variable"])
4253 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4255 .RI Literal( string )
4257 .RI env.Literal( string )
4260 will be preserved as-is
4261 and not have construction variables expanded.
4263 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4265 .RI Local( targets )
4267 .RI env.Local( targets )
4270 will have copies made in the local tree,
4271 even if an already up-to-date copy
4272 exists in a repository.
4273 Returns a list of the target Node or Nodes.
4275 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4277 .RI env.MergeFlags( arg ", [" unique ])
4278 Merges the specified
4280 values to the construction envrionment's construction variables.
4283 argument is not a dictionary,
4284 it is converted to one by calling
4287 before the values are merged.
4290 must be a single value,
4291 so multiple strings must
4292 be passed in as a list,
4293 not as separate arguments to
4294 .BR env.MergeFlags ().
4297 duplicate values are eliminated;
4298 you can, however, specify
4302 When eliminating duplicate values,
4303 any construction variables that end with
4306 keep the left-most unique value.
4307 All other construction variables keep
4308 the right-most unique value.
4313 # Add an optimization flag to $CCFLAGS.
4314 env.MergeFlags('-O3')
4316 # Combine the flags returned from running pkg-config with an optimization
4317 # flag and merge the result into the construction variables.
4318 env.MergeFlags(['!pkg-config gtk+-2.0 --cflags', '-O3'])
4320 # Combine an optimization flag with the flags returned from running pkg-config
4321 # twice and merge the result into the construction variables.
4322 env.MergeFlags(['-O3',
4323 '!pkg-config gtk+-2.0 --cflags --libs',
4324 '!pkg-config libpng12 --cflags --libs'])
4327 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4329 .RI NoCache( target ", ...)"
4331 .RI env.NoCache( target ", ...)"
4332 Specifies a list of files which should
4334 be cached whenever the
4336 method has been activated.
4337 The specified targets may be a list
4338 or an individual target.
4340 Multiple files should be specified
4341 either as separate arguments to the
4343 method, or as a list.
4345 will also accept the return value of any of the construction environment
4350 on directories and other non-File Node types has no effect because
4351 only File Nodes are cached.
4357 NoCache(env.Program('hello', 'hello.c'))
4360 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4362 .RI NoClean( target ", ...)"
4364 .RI env.NoClean( target ", ...)"
4365 Specifies a list of files or directories which should
4367 be removed whenever the targets (or their dependencies)
4368 are specified with the
4370 command line option.
4371 The specified targets may be a list
4372 or an individual target.
4376 and prevent each specified target
4377 from being removed by calls to the
4381 Multiple files or directories should be specified
4382 either as separate arguments to the
4384 method, or as a list.
4386 will also accept the return value of any of the construction environment
4391 for a target overrides calling
4393 for the same target,
4394 and any targets passed to both functions will
4404 NoClean(env.Program('hello', 'hello.c'))
4407 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4409 .RI env.ParseConfig( command ", [" function ", " unique ])
4412 to modify the environment as specified by the output of
4417 .BR env.MergeFlags (),
4418 which expects the output of a typical
4422 and adds the options
4423 to the appropriate construction variables.
4425 duplicate values are not
4426 added to any construction variables;
4433 and the construction variables they affect
4434 are as specified for the
4435 .BR env.ParseFlags ()
4436 method (which this method calls).
4437 See that method's description, below,
4438 for a table of options and construction variables.
4440 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4442 .RI ParseDepends( filename ", [" must_exist ", " only_one ])
4444 .RI env.ParseDepends( filename ", [" must_exist ", " only_one ])
4445 Parses the contents of the specified
4447 as a list of dependencies in the style of
4451 and explicitly establishes all of the listed dependencies.
4460 argument may be set to a non-zero
4463 throw an exception and
4464 generate an error if the file does not exist,
4465 or is otherwise inaccessible.
4469 argument may be set to a non-zero
4472 thrown an exception and
4474 if the file contains dependency
4475 information for more than one target.
4476 This can provide a small sanity check
4477 for files intended to be generated
4478 by, for example, the
4481 which should typically only
4482 write dependency information for
4483 one output file into a corresponding
4489 and all of the files listed therein
4490 will be interpreted relative to
4491 the directory of the
4493 file which calls the
4497 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4499 .RI env.ParseFlags( flags ", ...)"
4500 Parses one or more strings containing
4501 typical command-line flags for GCC tool chains
4502 and returns a dictionary with the flag values
4503 separated into the appropriate SCons construction variables.
4504 This is intended as a companion to the
4505 .BR env.MergeFlags ()
4506 method, but allows for the values in the returned dictionary
4507 to be modified, if necessary,
4508 before merging them into the construction environment.
4510 .BR env.MergeFlags ()
4511 will call this method if its argument is not a dictionary,
4512 so it is usually not necessary to call
4513 .BR env.ParseFlags ()
4514 directly unless you want to manipulate the values.)
4516 If the first character in any string is
4517 an exclamation mark (!),
4518 the rest of the string is executed as a command,
4519 and the output from the command is
4520 parsed as GCC tool chain command-line flags
4521 and added to the resulting dictionary.
4523 Flag values are translated accordig to the prefix found,
4524 and added to the following construction variables:
4527 -arch CCFLAGS, LINKFLAGS
4529 -framework FRAMEWORKS
4530 -frameworkdir= FRAMEWORKPATH
4532 -isysroot CCFLAGS, LINKFLAGS
4536 -mno-cygwin CCFLAGS, LINKFLAGS
4538 -pthread CCFLAGS, LINKFLAGS
4540 -Wa, ASFLAGS, CCFLAGS
4547 + CCFLAGS, LINKFLAGS
4551 Any other strings not associated with options
4552 are assumed to be the names of libraries
4555 construction variable.
4557 Examples (all of which produce the same result):
4560 dict = env.ParseFlags('-O2 -Dfoo -Dbar=1')
4561 dict = env.ParseFlags('-O2', '-Dfoo', '-Dbar=1')
4562 dict = env.ParseFlags(['-O2', '-Dfoo -Dbar=1'])
4563 dict = env.ParseFlags('-O2', '!echo -Dfoo -Dbar=1')
4566 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4569 A factory function that
4570 returns a Builder object
4571 to be used to fetch source files
4572 from the Perforce source code management system.
4573 The returned Builder
4574 is intended to be passed to the
4581 env.SourceCode('.', env.Perforce())
4584 Perforce uses a number of external
4585 environment variables for its operation.
4586 Consequently, this function adds the
4587 following variables from the user's external environment
4588 to the construction environment's
4601 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4603 .RI Platform( string )
4604 Returns a callable object
4605 that can be used to initialize
4606 a construction environment using the
4607 platform keyword of the Environment() method.
4612 env = Environment(platform = Platform('win32'))
4615 .RI env.Platform( string )
4616 Applies the callable object for the specified platform
4618 to the environment through which the method was called.
4621 env.Platform('posix')
4630 variables from the user's external environment
4631 to the construction environment's
4634 This is so that any executed commands
4635 that use sockets to connect with other systems
4636 (such as fetching source files from
4637 external CVS repository specifications like
4638 .BR :pserver:anonymous@cvs.sourceforge.net:/cvsroot/scons )
4639 will work on Windows systems.
4641 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4643 .RI Progress( callable ", [" interval ])
4645 .RI Progress( string ", [" interval ", " file ", " overwrite ])
4647 .RI Progress( list_of_strings ", [" interval ", " file ", " overwrite ])
4648 Allows SCons to show progress made during the build
4649 by displaying a string or calling a function while
4650 evaluating Nodes (e.g. files).
4652 If the first specified argument is a Python callable
4653 (a function or an object that has a
4656 the function will be called
4659 times a Node is evaluated.
4660 The callable will be passed the evaluated Node
4661 as its only argument.
4662 (For future compatibility,
4663 it's a good idea to also add
4667 as arguments to your function or method.
4668 This will prevent the code from breaking
4669 if SCons ever changes the interface
4670 to call the function with additional arguments in the future.)
4672 An example of a simple custom progress function
4673 that prints a string containing the Node name
4677 def my_progress_function(node, *args, **kw):
4678 print 'Evaluating node %s!' % node
4679 Progress(my_progress_function, interval=10)
4682 A more complicated example of a custom progress display object
4683 that prints a string containing a count
4684 every 100 evaluated Nodes.
4688 at the end so that the string
4689 will overwrite itself on a display:
4693 class ProgressCounter:
4695 def __call__(self, node, *args, **kw):
4697 sys.stderr.write('Evaluated %s nodes\\r' % self.count)
4698 Progress(ProgressCounter(), interval=100)
4701 If the first argument
4704 the string will be displayed
4708 The default is to print the string on standard output;
4709 an alternate output stream
4710 may be specified with the
4713 The following will print a series of dots
4714 on the error output,
4715 one dot for every 100 evaluated Nodes:
4719 Progress('.', interval=100, file=sys.stderr)
4722 If the string contains the verbatim substring
4724 it will be replaced with the Node.
4725 Note that, for performance reasons, this is
4727 a regular SCons variable substition,
4728 so you can not use other variables
4729 or use curly braces.
4730 The following example will print the name of
4731 every evaluated Node,
4734 (carriage return) to cause each line to overwritten by the next line,
4737 keyword argument to make sure the previously-printed
4738 file name is overwritten with blank spaces:
4742 Progress('$TARGET\\r', overwrite=True)
4745 If the first argument to
4747 is a list of strings,
4748 then each string in the list will be displayed
4749 in rotating fashion every
4752 This can be used to implement a "spinner"
4753 on the user's screen as follows:
4756 Progress(['-\\r', '\\\\\\r', '|\\r', '/\\r'], interval=5)
4759 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4761 .RI Precious( target ", ...)"
4763 .RI env.Precious( target ", ...)"
4766 as precious so it is not deleted before it is rebuilt. Normally
4768 deletes a target before building it.
4769 Multiple targets can be passed in to a single call to
4772 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4774 .RI env.Prepend( key = val ", [...])"
4775 Appends the specified keyword arguments
4776 to the beginning of construction variables in the environment.
4777 If the Environment does not have
4778 the specified construction variable,
4779 it is simply added to the environment.
4780 If the values of the construction variable
4781 and the keyword argument are the same type,
4782 then the two values will be simply added together.
4783 Otherwise, the construction variable
4784 and the value of the keyword argument
4785 are both coerced to lists,
4786 and the lists are added together.
4787 (See also the Append method, above.)
4792 env.Prepend(CCFLAGS = '-g ', FOO = ['foo.yyy'])
4795 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4797 .RI env.PrependENVPath( name ", " newpath ", [" envname ", " sep ])
4798 This appends new path elements to the given path in the
4799 specified external environment
4803 any particular path once (leaving the first one it encounters and
4804 ignoring the rest, to preserve path order),
4805 and to help assure this,
4806 will normalize all paths (using
4809 .BR os.path.normcase ).
4810 This can also handle the
4811 case where the given old path variable is a list instead of a
4812 string, in which case a list will be returned instead of a string.
4817 print 'before:',env['ENV']['INCLUDE']
4818 include_path = '/foo/bar:/foo'
4819 env.PrependENVPath('INCLUDE', include_path)
4820 print 'after:',env['ENV']['INCLUDE']
4823 The above exmaple will print:
4827 after: /foo/bar:/foo:/biz
4830 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4832 .RI env.PrependUnique( key = val ", [...])"
4833 Appends the specified keyword arguments
4834 to the beginning of construction variables in the environment.
4835 If the Environment does not have
4836 the specified construction variable,
4837 it is simply added to the environment.
4838 If the construction variable being appended to is a list,
4839 then any value(s) that already exist in the
4840 construction variable will
4842 be added again to the list.
4847 env.PrependUnique(CCFLAGS = '-g', FOO = ['foo.yyy'])
4850 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4853 A factory function that
4854 returns a Builder object
4855 to be used to fetch source files
4857 The returned Builder
4858 is intended to be passed to the
4865 env.SourceCode('.', env.RCS())
4870 will fetch source files
4871 from RCS subdirectories automatically,
4873 as demonstrated in the above example
4874 should only be necessary if
4875 you are fetching from
4878 directory as the source files,
4879 or if you need to explicitly specify RCS
4880 for a specific subdirectory.
4882 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4884 .RI env.Replace( key = val ", [...])"
4885 Replaces construction variables in the Environment
4886 with the specified keyword arguments.
4891 env.Replace(CCFLAGS = '-g', FOO = 'foo.xxx')
4894 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4896 .RI Repository( directory )
4898 .RI env.Repository( directory )
4901 is a repository to be searched for files.
4905 and each one adds to the list of
4906 repositories that will be searched.
4910 a repository is a copy of the source tree,
4911 from the top-level directory on down,
4913 both source files and derived files
4914 that can be used to build targets in
4915 the local source tree.
4916 The canonical example would be an
4917 official source tree maintained by an integrator.
4918 If the repository contains derived files,
4919 then the derived files should have been built using
4921 so that the repository contains the necessary
4922 signature information to allow
4924 to figure out when it is appropriate to
4925 use the repository copy of a derived file,
4926 instead of building one locally.
4928 Note that if an up-to-date derived file
4929 already exists in a repository,
4933 make a copy in the local directory tree.
4934 In order to guarantee that a local copy
4940 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4942 .RI Requires( target ", " prerequisite )
4944 .RI env.Requires( target ", " prerequisite )
4945 Specifies an order-only relationship
4946 between the specified target file(s)
4947 and the specified prerequisite file(s).
4948 The prerequisite file(s)
4949 will be (re)built, if necessary,
4952 but the target file(s) do not actually
4953 depend on the prerequisites
4954 and will not be rebuilt simply because
4955 the prerequisite file(s) change.
4960 env.Requires('foo', 'file-that-must-be-built-before-foo')
4963 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4965 .RI Return([ vars "... , " stop= ])
4967 this stops processing the current SConscript
4968 file and returns to the calling SConscript file
4969 the values of the variables named in the
4972 Multiple strings contaning variable names may be passed to
4974 Any strings that contain white space
4978 keyword argument may be set to a false value
4979 to continue processing the rest of the SConscript
4983 This was the default behavior prior to SCons 0.98.
4984 However, the values returned
4985 are still the values of the variables in the named
4994 # Returns without returning a value.
4997 # Returns the value of the 'foo' Python variable.
5000 # Returns the values of the Python variables 'foo' and 'bar'.
5001 Return("foo", "bar")
5003 # Returns the values of Python variables 'val1' and 'val2'.
5007 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
5009 .RI Scanner( function ", [" argument ", " keys ", " path_function ", " node_class ", " node_factory ", " scan_check ", " recursive ])
5011 .RI env.Scanner( function ", [" argument ", " keys ", " path_function ", " node_class ", " node_factory ", " scan_check ", " recursive ])
5012 Creates a Scanner object for
5015 See the section "Scanner Objects,"
5016 below, for a complete explanation of the arguments and behavior.
5018 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
5021 A factory function that
5022 returns a Builder object
5023 to be used to fetch source files
5025 The returned Builder
5026 is intended to be passed to the
5033 env.SourceCode('.', env.SCCS())
5038 will fetch source files
5039 from SCCS subdirectories automatically,
5041 as demonstrated in the above example
5042 should only be necessary if
5043 you are fetching from
5046 directory as the source files,
5047 or if you need to explicitly specify SCCS
5048 for a specific subdirectory.
5050 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
5052 .RI SConscript( scripts ", [" exports ", " variant_dir ", " src_dir ", " duplicate ])
5054 .RI env.SConscript( scripts ", [" exports ", " variant_dir ", " src_dir ", " duplicate ])
5056 .RI SConscript(dirs= subdirs ", [name=" script ", " exports ", " variant_dir ", " src_dir ", " duplicate ])
5058 .RI env.SConscript(dirs= subdirs ", [name=" script ", " exports ", " variant_dir ", " src_dir ", " duplicate ])
5062 one or more subsidiary SConscript (configuration) files.
5063 There are two ways to call the
5067 The first way you can call
5069 is to explicitly specify one or more
5071 as the first argument.
5072 A single script may be specified as a string;
5073 multiple scripts must be specified as a list
5074 (either explicitly or as created by
5078 The second way you can call
5080 is to specify a list of (sub)directory names
5087 execute a subsidiary configuration file named
5089 in each of the specified directories.
5090 You may specify a name other than
5092 by supplying an optional
5098 argument provides a list of variable names or a dictionary of
5099 named values to export to the
5101 These variables are locally exported only to the specified
5103 and do not affect the global pool of variables used by the
5106 '\"If multiple dirs are provided, each script gets a fresh export.
5111 function to import the variables.
5115 argument is present, it causes an effect equivalent to
5120 to be executed prior to reading the
5128 arguments are ignored.)
5133 arguments are interpreted relative to the directory
5134 of the calling SConscript file.
5137 is not specified, the directory of the calling SConscript file is assumed.
5138 See the description of the
5140 function below for additional details and restrictions.
5142 Any variables returned by
5146 will be returned by the call to
5152 SConscript('subdir/SConscript')
5153 foo = SConscript('sub/SConscript', exports='env')
5154 SConscript('dir/SConscript', exports=['env', 'variable'])
5155 SConscript('dir/SConscript', exports='env variable')
5156 SConscript(dirs=['sub1', 'sub2'])
5157 SConscript(dirs=['sub3', 'sub4'], name='MySConscript')
5161 SConscript('bld/SConscript', variant_dir='bld', duplicate=0)
5163 which is equivalent to
5165 VariantDir('bld', '.', duplicate=0)
5166 SConscript('bld/SConscript')
5168 '\"TODO: SConscript('bld/SConscript', src_dir='src', exports='env variable')
5170 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
5172 .RI SConscriptChdir( value )
5174 .RI env.SConscriptChdir( value )
5177 changes its working directory
5178 to the directory in which each
5179 subsidiary SConscript file lives.
5180 This behavior may be disabled
5181 by specifying either:
5185 env.SConscriptChdir(0)
5190 will stay in the top-level directory
5191 while reading all SConscript files.
5192 (This may be necessary when building from repositories,
5193 when all the directories in which SConscript files may be found
5194 don't necessarily exist locally.)
5195 You may enable and disable
5196 this ability by calling
5205 SConscript('foo/SConscript') # will not chdir to foo
5206 env.SConscriptChdir(1)
5207 SConscript('bar/SConscript') # will chdir to bar
5210 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
5212 .RI SConsignFile([ file , dbm_module ])
5214 .RI env.SConsignFile([ file , dbm_module ])
5217 to store all file signatures
5218 in the specified database
5225 (The actual file name(s) stored on disk
5226 may have an appropriated suffix appended
5231 is not an absolute path name,
5232 the file is placed in the same directory as the top-level
5242 will store file signatures
5245 file in each directory,
5246 not in one global database file.
5247 (This was the default behavior
5248 prior to SCons 0.96.91 and 0.97.)
5252 argument can be used to specify
5253 which Python database module
5254 The default is to use a custom
5256 module that uses pickled
5257 Python data structures,
5258 and which works on all Python versions from 1.5.2 on.
5263 # Explicitly stores signatures in ".sconsign.dblite"
5264 # in the top-level SConstruct directory (the
5265 # default behavior).
5268 # Stores signatures in the file "etc/scons-signatures"
5269 # relative to the top-level SConstruct directory.
5270 SConsignFile("etc/scons-signatures")
5272 # Stores signatures in the specified absolute file name.
5273 SConsignFile("/home/me/SCons/signatures")
5275 # Stores signatures in a separate .sconsign file
5276 # in each directory.
5280 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
5282 .RI env.SetDefault(key = val ", [...])"
5283 Sets construction variables to default values specified with the keyword
5284 arguments if (and only if) the variables are not already set.
5285 The following statements are equivalent:
5288 env.SetDefault(FOO = 'foo')
5290 if not env.has_key('FOO'): env['FOO'] = 'foo'
5293 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
5295 .RI SetOption( name ", " value )
5297 .RI env.SetOption( name ", " value )
5298 This function provides a way to set a select subset of the scons command
5299 line options from a SConscript file. The options supported are:
5304 which corresponds to -c, --clean and --remove;
5307 which corresponds to --duplicate;
5310 which corresponds to -h and --help;
5313 which corresponds to --implicit-cache;
5316 which corresponds to --max-drift;
5319 which corresponds to -n, --no-exec, --just-print, --dry-run and --recon;
5322 which corresponds to -j and --jobs;
5325 which corresponds to --random; and
5328 which corresponds to --stack-size.
5332 See the documentation for the
5333 corresponding command line object for information about each specific
5339 SetOption('max_drift', 1)
5342 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
5344 .RI SideEffect( side_effect ", " target )
5346 .RI env.SideEffect( side_effect ", " target )
5349 as a side effect of building
5355 can be a list, a file name, or a node.
5356 A side effect is a target file that is created or updated
5357 as a side effect of building other targets.
5358 For example, a Windows PDB
5359 file is created as a side effect of building the .obj
5360 files for a static library,
5361 and various log files are created updated
5362 as side effects of various TeX commands.
5363 If a target is a side effect of multiple build commands,
5365 will ensure that only one set of commands
5366 is executed at a time.
5367 Consequently, you only need to use this method
5368 for side-effect targets that are built as a result of
5369 multiple build commands.
5371 Because multiple build commands may update
5372 the same side effect file,
5377 automatically removed
5383 (Note, however, that the
5385 might be removed as part of
5386 cleaning the directory in which it lives.)
5387 If you want to make sure the
5389 is cleaned whenever a specific
5392 you must specify this explicitly
5399 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
5401 .RI SourceCode( entries ", " builder )
5403 .RI env.SourceCode( entries ", " builder )
5404 Arrange for non-existent source files to
5405 be fetched from a source code management system
5410 may be a Node, string or list of both,
5411 and may represent either individual
5412 source files or directories in which
5413 source files can be found.
5415 For any non-existent source files,
5417 will search up the directory tree
5427 will not use a builder to fetch
5428 source files for the specified
5432 builder has been specified
5433 for a directory higher up the tree.
5437 fetch files from SCCS or RCS subdirectories
5438 without explicit configuration.
5439 This takes some extra processing time
5440 to search for the necessary
5441 source code management files on disk.
5442 You can avoid these extra searches
5443 and speed up your build a little
5444 by disabling these searches as follows:
5447 env.SourceCode('.', None)
5451 Note that if the specified
5453 is one you create by hand,
5454 it must have an associated
5455 construction environment to use
5456 when fetching a source file.
5459 provides a set of canned factory
5460 functions that return appropriate
5461 Builders for various popular
5462 source code management systems.
5463 Canonical examples of invocation include:
5466 env.SourceCode('.', env.BitKeeper('/usr/local/BKsources'))
5467 env.SourceCode('src', env.CVS('/usr/local/CVSROOT'))
5468 env.SourceCode('/', env.RCS())
5469 env.SourceCode(['f1.c', 'f2.c'], env.SCCS())
5470 env.SourceCode('no_source.c', None)
5472 '\"env.SourceCode('.', env.Subversion('file:///usr/local/Subversion'))
5474 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
5476 .RI env.subst( input ", [" raw ", " target ", " source ", " conv ])
5477 Performs construction variable interpolation
5478 on the specified string or sequence argument
5482 leading or trailing white space will
5483 be removed from the result.
5484 and all sequences of white space
5485 will be compressed to a single space character.
5490 character sequences will be stripped from the returned string,
5493 argument may be set to
5495 if you want to preserve white space and
5500 argument may be set to
5502 if you want to strip
5503 all characters between
5509 (as is done for signature calculation).
5511 If the input is a sequence
5513 the individual elements of
5514 the sequence will be expanded,
5515 and the results will be returned as a list.
5522 must be set to lists of
5523 target and source nodes, respectively,
5530 to be available for expansion.
5531 This is usually necessary if you are
5534 from within a Python function used
5537 Returned string values or sequence elements
5538 are converted to their string representation by default.
5542 may specify a conversion function
5543 that will be used in place of
5545 For example, if you want Python objects
5546 (including SCons Nodes)
5547 to be returned as Python objects,
5548 you can use the Python
5550 idiom to pass in an unnamed function
5551 that simply returns its unconverted argument.
5556 print env.subst("The C compiler is: $CC")
5558 def compile(target, source, env):
5559 sourceDir = env.subst("${SOURCE.srcdir}",
5563 source_nodes = env.subst('$EXPAND_TO_NODELIST',
5567 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
5569 '\".RI Subversion( repository ", " module )
5570 '\"A factory function that
5571 '\"returns a Builder object
5572 '\"to be used to fetch source files
5573 '\"from the specified Subversion
5575 '\"The returned Builder
5576 '\"is intended to be passed to the
5580 '\"The optional specified
5582 '\"will be added to the beginning
5583 '\"of all repository path names;
5584 '\"this can be used, in essence,
5585 '\"to strip initial directory names
5586 '\"from the repository path names,
5587 '\"so that you only have to
5588 '\"replicate part of the repository
5589 '\"directory hierarchy in your
5590 '\"local build directory.
5595 '\"# Will fetch foo/bar/src.c
5596 '\"# from /usr/local/Subversion/foo/bar/src.c.
5597 '\"env.SourceCode('.', env.Subversion('file:///usr/local/Subversion'))
5599 '\"# Will fetch bar/src.c
5600 '\"# from /usr/local/Subversion/foo/bar/src.c.
5601 '\"env.SourceCode('.', env.Subversion('file:///usr/local/Subversion', 'foo'))
5603 '\"# Will fetch src.c
5604 '\"# from /usr/local/Subversion/foo/bar/src.c.
5605 '\"env.SourceCode('.', env.Subversion('file:///usr/local/Subversion', 'foo/bar'))
5608 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
5610 .RI SourceSignatures( type )
5612 .RI env.SourceSignatures( type )
5613 Note: Although it is not yet officially deprecated,
5614 use of this function is discouraged.
5617 function for a more flexible and straightforward way
5618 to configure SCons' decision-making.
5621 .BR SourceSignatures ()
5624 how to decide if a source file
5625 (a file that is not built from any other files)
5626 has changed since the last time it
5627 was used to build a particular target file.
5633 If the environment method is used,
5634 the specified type of source signature
5635 is only used when deciding whether targets
5636 built with that environment are up-to-date or must be rebuilt.
5637 If the global function is used,
5638 the specified type of source signature becomes the default
5639 used for all decisions
5640 about whether targets are up-to-date.
5645 decides that a source file has changed
5646 if the MD5 checksum of its contents has changed since
5647 the last time it was used to rebuild a particular target file.
5652 decides that a source file has changed
5653 if its timestamp (modification time) has changed since
5654 the last time it was used to rebuild a particular target file.
5655 (Note that although this is similar to the behavior of Make,
5656 by default it will also rebuild if the dependency is
5658 than the last time it was used to rebuild the target file.)
5660 There is no different between the two behaviors
5666 signatures take longer to compute,
5667 but are more accurate than
5670 The default value is
5673 Note that the default
5674 .BR TargetSignatures ()
5677 .BR SourceSignatures ()
5678 setting for any target files that are used
5679 to build other target files.
5680 Consequently, changing the value of
5681 .BR SourceSignatures ()
5683 affect the up-to-date decision for all files in the build
5684 (or all files built with a specific construction environment
5686 .BR env.SourceSignatures ()
5689 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
5693 .RI env.Split( arg )
5694 Returns a list of file names or other objects.
5696 it will be split on strings of white-space characters
5698 making it easier to write long lists of file names.
5699 If arg is already a list,
5700 the list will be returned untouched.
5701 If arg is any other type of object,
5702 it will be returned as a list
5703 containing just the object.
5708 files = Split("f1.c f2.c f3.c")
5709 files = env.Split("f4.c f5.c f6.c")
5717 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
5719 .RI Tag( node ", " tags )
5720 Annotates file or directory Nodes with
5721 information about how the
5723 Builder should package those files or directories.
5724 All tags are optional.
5729 # makes sure the built library will be installed with 0644 file
5731 Tag( Library( 'lib.c' ), UNIX_ATTR="0644" )
5733 # marks file2.txt to be a documentation file
5734 Tag( 'file2.txt', DOC )
5737 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
5739 .RI TargetSignatures( type )
5741 .RI env.TargetSignatures( type )
5742 Note: Although it is not yet officially deprecated,
5743 use of this function is discouraged.
5746 function for a more flexible and straightforward way
5747 to configure SCons' decision-making.
5750 .BR TargetSignatures ()
5753 how to decide if a target file
5756 built from any other files)
5757 has changed since the last time it
5758 was used to build some other target file.
5768 If the environment method is used,
5769 the specified type of target signature is only used
5770 for targets built with that environment.
5771 If the global function is used,
5772 the specified type of signature becomes the default
5773 used for all target files that
5774 don't have an explicit target signature type
5775 specified for their environments.
5782 decides that a target file has changed
5783 if the MD5 checksum of its contents has changed since
5784 the last time it was used to rebuild some other target file.
5788 MD5 sum the contents
5789 of target files after they're built,
5790 and may decide that it does not need to rebuild
5791 "downstream" target files if a file was
5792 rebuilt with exactly the same contents as the last time.
5797 decides that a target file has changed
5798 if its timestamp (modification time) has changed since
5799 the last time it was used to rebuild some other target file.
5800 (Note that although this is similar to the behavior of Make,
5801 by default it will also rebuild if the dependency is
5803 than the last time it was used to rebuild the target file.)
5808 decides that a target file has changed
5809 as specified by the corresponding
5810 .BR SourceSignatures ()
5817 will treat all input files to a target the same way,
5818 regardless of whether they are source files
5819 or have been built from other files.
5824 decides that a target file has changed
5825 if it has been rebuilt in this invocation
5826 or if its content or timestamp have changed
5827 as specified by the corresponding
5828 .BR SourceSignatures ()
5830 This "propagates" the status of a rebuilt file
5831 so that other "downstream" target files
5832 will always be rebuilt,
5833 even if the contents or the timestamp
5837 signatures are fastest because
5841 signatures take longer to compute,
5842 but are more accurate than
5845 and can prevent unnecessary "downstream" rebuilds
5846 when a target file is rebuilt to the exact same contents
5847 as the previous build.
5850 setting provides the most consistent behavior
5851 when other target files may be rebuilt from
5852 both source and target input files.
5853 The default value is
5856 Because the default setting is
5859 .BR SourceSignatures ()
5860 is generally preferable to
5861 .BR TargetSignatures () ,
5862 so that the up-to-date decision
5863 will be consistent for all files
5864 (or all files built with a specific construction environment).
5866 .BR TargetSignatures ()
5867 provides specific control for how built target files
5868 affect their "downstream" dependencies.
5870 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
5872 .RI Tool( string [, toolpath ", " **kw ])
5873 Returns a callable object
5874 that can be used to initialize
5875 a construction environment using the
5876 tools keyword of the Environment() method.
5877 The object may be called with a construction
5878 environment as an argument,
5879 in which case the object will
5880 add the necessary variables
5881 to the construction environment
5882 and the name of the tool will be added to the
5884 construction variable.
5886 Additional keyword arguments are passed to the tool's
5893 env = Environment(tools = [ Tool('msvc') ])
5897 t(env) # adds 'msvc' to the TOOLS variable
5898 u = Tool('opengl', toolpath = ['tools'])
5899 u(env) # adds 'opengl' to the TOOLS variable
5902 .RI env.Tool( string [, toolpath ", " **kw ])
5903 Applies the callable object for the specified tool
5905 to the environment through which the method was called.
5907 Additional keyword arguments are passed to the tool's
5913 env.Tool('opengl', toolpath = ['build/tools'])
5916 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
5918 .RI Value( value ", [" built_value ])
5920 .RI env.Value( value ", [" built_value ])
5921 Returns a Node object representing the specified Python value. Value
5922 Nodes can be used as dependencies of targets. If the result of
5925 changes between SCons runs, any targets depending on
5928 (This is true even when using timestamps to decide if
5929 files are up-to-date.)
5930 When using timestamp source signatures, Value Nodes'
5931 timestamps are equal to the system time when the Node is created.
5933 The returned Value Node object has a
5935 method that can be used to "build" a Value Node
5936 by setting a new value.
5939 argument can be specified
5940 when the Value Node is created
5941 to indicate the Node should already be considered
5943 There is a corresponding
5945 method that will return the built value of the Node.
5952 def create(target, source, env):
5953 # A function that will write a 'prefix=$SOURCE'
5954 # string into the file name specified as the
5956 f = open(str(target[0]), 'wb')
5957 f.write('prefix=' + source[0].get_contents())
5959 # Fetch the prefix= argument, if any, from the command
5960 # line, and use /usr/local as the default.
5961 prefix = ARGUMENTS.get('prefix', '/usr/local')
5963 # Attach a .Config() builder for the above function action
5964 # to the construction environment.
5965 env['BUILDERS']['Config'] = Builder(action = create)
5966 env.Config(target = 'package-config', source = Value(prefix))
5968 def build_value(target, source, env):
5969 # A function that "builds" a Python Value by updating
5970 # the the Python value with the contents of the file
5971 # specified as the source of the Builder call ($SOURCE).
5972 target[0].write(source[0].get_contents())
5974 output = env.Value('before')
5975 input = env.Value('after')
5977 # Attach a .UpdateValue() builder for the above function
5978 # action to the construction environment.
5979 env['BUILDERS']['UpdateValue'] = Builder(action = build_value)
5980 env.UpdateValue(target = Value(output), source = Value(input))
5983 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
5985 .RI VariantDir( variant_dir ", " src_dir ", [" duplicate ])
5987 .RI env.VariantDir( variant_dir ", " src_dir ", [" duplicate ])
5990 function to create a copy of your sources in another location:
5993 is not found but exists under
5995 the file or directory is copied to
5997 Target files can be built in a different directory than the original sources
5998 by simply refering to the sources (and targets) within the variant tree.
6001 can be called multiple times with the same
6003 to set up multiple builds with different options
6007 location must be in or underneath the SConstruct file's directory, and
6009 may not be underneath
6011 '\"TODO: Can the above restrictions be clarified or relaxed?
6012 '\"TODO: The latter restriction is clearly not completely right;
6013 '\"TODO: src_dir = '.' works fine with a build dir under it.
6015 The default behavior is for
6017 to physically duplicate the source files in the variant tree.
6018 Thus, a build performed in the variant tree is guaranteed to be identical
6019 to a build performed in the source tree even if
6020 intermediate source files are generated during the build,
6021 or preprocessors or other scanners search for included files
6022 relative to the source file,
6023 or individual compilers or other invoked tools are hard-coded
6024 to put derived files in the same directory as source files.
6026 If possible on the platform,
6027 the duplication is performed by linking rather than copying;
6030 command-line option.
6031 Moreover, only the files needed for the build are duplicated;
6032 files and directories that are not used are not present in
6035 Duplicating the source tree may be disabled by setting the
6040 to invoke Builders using the path names of source files in
6042 and the path names of derived files within
6044 This is always more efficient than
6046 and is usually safe for most builds
6047 (but see above for cases that may cause problems).
6051 works most naturally with a subsidiary SConscript file.
6052 However, you would then call the subsidiary SConscript file
6053 not in the source directory, but in the
6055 regardless of the value of
6057 This is how you tell
6059 which variant of a source tree to build:
6062 # run src/SConscript in two variant directories
6063 VariantDir('build/variant1', 'src')
6064 SConscript('build/variant1/SConscript')
6065 VariantDir('build/variant2', 'src')
6066 SConscript('build/variant2/SConscript')
6072 function, described above,
6073 for another way to specify a variant directory
6074 in conjunction with calling a subsidiary SConscript file.
6079 # use names in the build directory, not the source directory
6080 VariantDir('build', 'src', duplicate=0)
6081 Program('build/prog', 'build/source.c')
6085 # this variant builds both the source and docs
6086 VariantDir('build', '.', duplicate=0)
6087 SConscript(dirs=['build/src','build/doc'])
6091 SConscript(dirs=['build/src','build/doc'],
6092 variant_dir = 'build', duplicate = 0)
6096 SConscript('build/SConscript', variant_dir = 'build', duplicate = 0)
6098 Note that in the last example, the
6100 is not given, so the current directory is assumed, and the
6104 are actually in the same directory, even though the
6106 is treated as if it were in the
6110 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
6112 .RI WhereIs( program ", [" path ", " pathext ", " reject ])
6114 .RI env.WhereIs( program ", [" path ", " pathext ", " reject ])
6116 Searches for the specified executable
6118 returning the full path name to the program
6120 and returning None if not.
6121 Searches the specified
6123 the value of the calling environment's PATH
6124 (env['ENV']['PATH']),
6125 or the user's current external PATH
6126 (os.environ['PATH'])
6128 On Windows systems, searches for executable
6129 programs with any of the file extensions
6130 listed in the specified
6132 the calling environment's PATHEXT
6133 (env['ENV']['PATHEXT'])
6134 or the user's current PATHEXT
6135 (os.environ['PATHEXT'])
6143 .SS SConscript Variables
6144 In addition to the global functions and methods,
6146 supports a number of Python variables
6147 that can be used in SConscript files
6148 to affect how you want the build to be performed.
6149 These variables may be accessed from custom Python modules that you
6150 import into an SConscript file by adding the following
6151 to the Python module:
6154 from SCons.Script import *
6157 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
6162 arguments specified on the command line.
6163 Each element in the list is a tuple
6165 .RI ( keyword , value )
6171 elements of the tuple
6173 subscripting for element
6177 of the tuple, respectively.
6182 print "first keyword, value =", ARGLIST[0][0], ARGLIST[0][1]
6183 print "second keyword, value =", ARGLIST[1][0], ARGLIST[1][1]
6184 third_tuple = ARGLIST[2]
6185 print "third keyword, value =", third_tuple[0], third_tuple[1]
6186 for key, value in ARGLIST:
6187 # process key and value
6190 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
6193 A dictionary of all the
6195 arguments specified on the command line.
6196 The dictionary is not in order,
6197 and if a given keyword has
6198 more than one value assigned to it
6199 on the command line,
6200 the last (right-most) value is
6208 if ARGUMENTS.get('debug', 0):
6209 env = Environment(CCFLAGS = '-g')
6214 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
6217 A list of the targets which
6219 will actually try to build,
6220 regardless of whether they were specified on
6221 the command line or via the
6224 The elements of this list may be strings
6226 nodes, so you should run the list through the Python
6228 function to make sure any Node path names
6229 are converted to strings.
6231 Because this list may be taken from the
6232 list of targets specified using the
6235 the contents of the list may change
6236 on each successive call to
6241 for additional information.
6246 if 'foo' in BUILD_TARGETS:
6247 print "Don't forget to test the `foo' program!"
6248 if 'special/program' in BUILD_TARGETS:
6249 SConscript('special')
6254 list only contains targets expected listed
6255 on the command line or via calls to the
6260 contain all dependent targets that will be built as
6261 a result of making the sure the explicitly-specified
6262 targets are up to date.
6264 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
6266 COMMAND_LINE_TARGETS
6267 A list of the targets explicitly specified on
6269 If there are no targets specified on the command line,
6271 This can be used, for example,
6272 to take specific actions only
6273 when a certain target or targets
6274 is explicitly being built.
6279 if 'foo' in COMMAND_LINE_TARGETS:
6280 print "Don't forget to test the `foo' program!"
6281 if 'special/program' in COMMAND_LINE_TARGETS:
6282 SConscript('special')
6285 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
6288 A list of the target
6290 that have been specified using the
6293 The elements of the list are nodes,
6294 so you need to run them through the Python
6296 function to get at the path name for each Node.
6301 print str(DEFAULT_TARGETS[0])
6302 if 'foo' in map(str, DEFAULT_TARGETS):
6303 print "Don't forget to test the `foo' program!"
6308 list change on on each successive call to the
6313 print map(str, DEFAULT_TARGETS) # originally []
6315 print map(str, DEFAULT_TARGETS) # now a node ['foo']
6317 print map(str, DEFAULT_TARGETS) # now a node ['foo', 'bar']
6319 print map(str, DEFAULT_TARGETS) # back to []
6322 Consequently, be sure to use
6324 only after you've made all of your
6327 or else simply be careful of the order
6328 of these statements in your SConscript files
6329 so that you don't look for a specific
6330 default target before it's actually been added to the list.
6332 .SS Construction Variables
6333 .\" XXX From Gary Ruben, 23 April 2002:
6334 .\" I think it would be good to have an example with each construction
6335 .\" variable description in the documentation.
6337 .\" CC The C compiler
6338 .\" Example: env["CC"] = "c68x"
6339 .\" Default: env["CC"] = "cc"
6341 .\" CCCOM The command line ...
6343 .\" To generate the compiler line c68x -ps -qq -mr -o $TARGET $SOURCES
6344 .\" env["CC"] = "c68x"
6345 .\" env["CFLAGS"] = "-ps -qq -mr"
6346 .\" env["CCCOM"] = "$CC $CFLAGS -o $TARGET $SOURCES
6348 .\" (I dunno what this is ;-)
6349 A construction environment has an associated dictionary of
6350 .I construction variables
6351 that are used by built-in or user-supplied build rules.
6352 Construction variables must follow the same rules for
6354 the initial character must be an underscore or letter,
6355 followed by any number of underscores, letters, or digits.
6357 A number of useful construction variables are automatically defined by
6358 scons for each supported platform, and additional construction variables
6359 can be defined by the user. The following is a list of the automatically
6360 defined construction variables:
6362 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
6363 '\" BEGIN GENERATED CONSTRUCTION VARIABLE DESCRIPTIONS
6365 '\" The descriptions below of the various SCons construction variables
6366 '\" are generated from the .xml files that live next to the various
6367 '\" Python modules in the build enginer library. If you're reading
6368 '\" this [gnt]roff file with an eye towards patching this man page,
6369 '\" you can still submit a diff against this text, but it will have to
6370 '\" be translated to a diff against the underlying .xml file before the
6371 '\" patch is actually accepted. If you do that yourself, it will make
6372 '\" it easier to integrate the patch.
6374 '\" BEGIN GENERATED CONSTRUCTION VARIABLE DESCRIPTIONS
6375 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
6377 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
6378 '\" END GENERATED CONSTRUCTION VARIABLE DESCRIPTIONS
6380 '\" The descriptions above of the various SCons construction variables
6381 '\" are generated from the .xml files that live next to the various
6382 '\" Python modules in the build enginer library. If you're reading
6383 '\" this [gnt]roff file with an eye towards patching this man page,
6384 '\" you can still submit a diff against this text, but it will have to
6385 '\" be translated to a diff against the underlying .xml file before the
6386 '\" patch is actually accepted. If you do that yourself, it will make
6387 '\" it easier to integrate the patch.
6389 '\" END GENERATED CONSTRUCTION VARIABLE DESCRIPTIONS
6390 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
6393 Construction variables can be retrieved and set using the
6395 method of the construction environment:
6398 dict = env.Dictionary()
6402 or using the [] operator:
6408 Construction variables can also be passed to the construction environment
6412 env = Environment(CC="cc")
6415 or when copying a construction environment using the
6420 env2 = env.Clone(CC="cl.exe")
6423 .SS Configure Contexts
6427 .I configure contexts,
6428 an integrated mechanism similar to the
6429 various AC_CHECK macros in GNU autoconf
6430 for testing for the existence of C header
6431 files, libraries, etc.
6432 In contrast to autoconf,
6434 does not maintain an explicit cache of the tested values,
6435 but uses its normal dependency tracking to keep the checked values
6436 up to date. However, users may override this behaviour with the
6438 command line option.
6440 The following methods can be used to perform checks:
6443 .RI Configure( env ", [" custom_tests ", " conf_dir ", " log_file ", " config_h ", " clean ", " help])
6445 .RI env.Configure([ custom_tests ", " conf_dir ", " log_file ", " config_h ", " clean ", " help])
6446 This creates a configure context, which can be used to perform checks.
6448 specifies the environment for building the tests.
6449 This environment may be modified when performing checks.
6451 is a dictionary containing custom tests.
6452 See also the section about custom tests below.
6453 By default, no custom tests are added to the configure context.
6455 specifies a directory where the test cases are built.
6456 Note that this directory is not used for building
6458 The default value is the directory
6461 specifies a file which collects the output from commands
6462 that are executed to check for the existence of header files, libraries, etc.
6463 The default is the file #/config.log.
6464 If you are using the
6467 you may want to specify a subdirectory under your variant directory.
6469 specifies a C header file where the results of tests
6470 will be written, e.g. #define HAVE_STDIO_H, #define HAVE_LIBM, etc.
6471 The default is to not write a
6474 You can specify the same
6476 file in multiple calls to Configure,
6479 will concatenate all results in the specified file.
6481 uses its normal dependency checking
6482 to decide if it's necessary to rebuild
6486 This means that the file is not necessarily re-built each
6488 but is only rebuilt if its contents will have changed
6489 and some target that depends on the
6491 file is being built.
6497 arguments can be used to suppress execution of the configuration
6502 options are used, respectively.
6503 The default behavior is always to execute
6504 configure context tests,
6505 since the results of the tests may
6506 affect the list of targets to be cleaned
6508 If the configure tests do not affect these,
6509 then you may add the
6515 to avoid unnecessary test execution.
6520 instance has the following associated methods:
6523 .RI Configure.Finish()
6524 This method should be called after configuration is done.
6525 It returns the environment as modified
6526 by the configuration checks performed.
6527 After this method is called, no further checks can be performed
6528 with this configuration context.
6529 However, you can create a new
6531 context to perform additional checks.
6532 Only one context should be active at a time.
6534 The following Checks are predefined.
6535 (This list will likely grow larger as time
6536 goes by and developers contribute new useful tests.)
6539 .RI Configure.CheckHeader( header ", [" include_quotes ", " language ])
6542 is usable in the specified language.
6545 in which case the last item in the list
6546 is the header file to be checked,
6547 and the previous list items are
6550 lines should precede the
6551 header line being checked for.
6552 The optional argument
6555 a two character string, where the first character denotes the opening
6556 quote and the second character denotes the closing quote.
6557 By default, both characters are " (double quote).
6558 The optional argument
6564 and selects the compiler to be used for the check.
6565 Returns 1 on success and 0 on failure.
6568 .RI Configure.CheckCHeader( header ", [" include_quotes ])
6569 This is a wrapper around
6570 .B Configure.CheckHeader
6573 is usable in the C language.
6576 in which case the last item in the list
6577 is the header file to be checked,
6578 and the previous list items are
6581 lines should precede the
6582 header line being checked for.
6583 The optional argument
6586 a two character string, where the first character denotes the opening
6587 quote and the second character denotes the closing quote (both default
6589 Returns 1 on success and 0 on failure.
6592 .RI Configure.CheckCXXHeader( header ", [" include_quotes ])
6593 This is a wrapper around
6594 .B Configure.CheckHeader
6597 is usable in the C++ language.
6600 in which case the last item in the list
6601 is the header file to be checked,
6602 and the previous list items are
6605 lines should precede the
6606 header line being checked for.
6607 The optional argument
6610 a two character string, where the first character denotes the opening
6611 quote and the second character denotes the closing quote (both default
6613 Returns 1 on success and 0 on failure.
6616 .RI Configure.CheckFunc( function_name ", [" header ", " language ])
6617 Checks if the specified
6618 C or C++ function is available.
6620 is the name of the function to check for.
6623 argument is a string
6627 that will be compiled
6628 to check if the function exists;
6634 char function_name();
6642 and selects the compiler to be used for the check;
6646 .RI Configure.CheckLib([ library ", " symbol ", " header ", " language ", " autoadd=1 ])
6653 is 1 and the library provides the specified
6655 appends the library to the LIBS construction environment variable.
6657 may also be None (the default),
6660 is checked with the current LIBS variable,
6661 or a list of library names,
6662 in which case each library in the list
6670 .BR Configure.CheckLib ()
6672 you can link against the specified
6680 and selects the compiler to be used for the check;
6682 The default value for
6685 This method returns 1 on success and 0 on error.
6688 .RI Configure.CheckLibWithHeader( library ", " header ", " language ", [" call ", " autoadd ])
6691 .RI Configure.CheckLib
6692 call, this call provides a more sophisticated way to check against libraries.
6695 specifies the library or a list of libraries to check.
6697 specifies a header to check for.
6700 in which case the last item in the list
6701 is the header file to be checked,
6702 and the previous list items are
6705 lines should precede the
6706 header line being checked for.
6708 may be one of 'C','c','CXX','cxx','C++' and 'c++'.
6710 can be any valid expression (with a trailing ';').
6714 the default simply checks that you
6715 can link against the specified
6718 specifies whether to add the library to the environment (only if the check
6719 succeeds). This method returns 1 on success and 0 on error.
6722 .RI Configure.CheckType( type_name ", [" includes ", " language ])
6723 Checks for the existence of a type defined by
6726 specifies the typedef name to check for.
6728 is a string containing one or more
6730 lines that will be inserted into the program
6731 that will be run to test for the existence of the type.
6738 and selects the compiler to be used for the check;
6742 Example of a typical Configure usage:
6746 conf = Configure( env )
6747 if not conf.CheckCHeader( 'math.h' ):
6748 print 'We really need math.h!'
6750 if conf.CheckLibWithHeader( 'qt', 'qapp.h', 'c++', 'QApplication qapp(0,0);' ):
6751 # do stuff for qt - usage, e.g.
6752 conf.env.Append( CPPFLAGS = '-DWITH_QT' )
6757 .RI Configure.CheckTypeSize( type_name ", [" header ", " language ", " expect ])
6758 Checks for the size of a type defined by
6761 specifies the typedef name to check for.
6764 argument is a string
6768 that will be compiled
6769 to check if the function exists;
6770 the default is empty.
6777 and selects the compiler to be used for the check;
6781 argument should be an integer.
6782 If this argument is used,
6783 the function will only check whether the type
6784 given in type_name has the expected size (in bytes).
6786 .B "CheckTypeSize('short', expect = 2)"
6787 will return success only if short is two bytes.
6793 .RI Configure.CheckDeclaration( symbol ", [" includes ", " language ])
6794 Checks if the specified
6798 is a string containing one or more
6800 lines that will be inserted into the program
6801 that will be run to test for the existence of the type.
6808 and selects the compiler to be used for the check;
6812 .RI Configure.Define( symbol ", [" value ", " comment ])
6813 This function does not check for anything, but defines a
6814 preprocessor symbol that will be added to the configuration header file.
6815 It is the equivalent of AC_DEFINE,
6816 and defines the symbol
6820 and the optional comment
6828 conf = Configure( env )
6830 # Puts the following line in the config header file:
6832 conf.Define('A_SYMBOL')
6834 # Puts the following line in the config header file:
6835 # #define A_SYMBOL 1
6836 conf.Define('A_SYMBOL', 1)
6840 Be careful about quoting string values, though:
6844 conf = Configure( env )
6846 # Puts the following line in the config header file:
6847 # #define A_SYMBOL YA
6848 conf.Define('A_SYMBOL', "YA")
6850 # Puts the following line in the config header file:
6851 # #define A_SYMBOL "YA"
6852 conf.Define('A_SYMBOL', '"YA"')
6860 conf = Configure( env )
6862 # Puts the following lines in the config header file:
6863 # /* Set to 1 if you have a symbol */
6864 # #define A_SYMBOL 1
6865 conf.Define('A_SYMBOL', 1, 'Set to 1 if you have a symbol')
6869 You can define your own custom checks.
6870 in addition to the predefined checks.
6871 These are passed in a dictionary to the Configure function.
6872 This dictionary maps the names of the checks
6873 to user defined Python callables
6874 (either Python functions or class instances implementing the
6877 The first argument of the call is always a
6879 instance followed by the arguments,
6880 which must be supplied by the user of the check.
6881 These CheckContext instances define the following methods:
6884 .RI CheckContext.Message( self ", " text )
6886 Usually called before the check is started.
6888 will be displayed to the user, e.g. 'Checking for library X...'
6891 .RI CheckContext.Result( self, ", " res )
6893 Usually called after the check is done.
6895 can be either an integer or a string. In the former case, 'ok' (res != 0)
6896 or 'failed' (res == 0) is displayed to the user, in the latter case the
6897 given string is displayed.
6900 .RI CheckContext.TryCompile( self ", " text ", " extension )
6901 Checks if a file with the specified
6903 (e.g. '.c') containing
6905 can be compiled using the environment's
6907 builder. Returns 1 on success and 0 on failure.
6910 .RI CheckContext.TryLink( self ", " text ", " extension )
6911 Checks, if a file with the specified
6913 (e.g. '.c') containing
6915 can be compiled using the environment's
6917 builder. Returns 1 on success and 0 on failure.
6920 .RI CheckContext.TryRun( self ", " text ", " extension )
6921 Checks, if a file with the specified
6923 (e.g. '.c') containing
6925 can be compiled using the environment's
6927 builder. On success, the program is run. If the program
6928 executes successfully
6929 (that is, its return status is 0),
6934 is the standard output of the
6936 If the program fails execution
6937 (its return status is non-zero),
6938 then (0, '') is returned.
6941 .RI CheckContext.TryAction( self ", " action ", [" text ", " extension ])
6942 Checks if the specified
6944 with an optional source file (contents
6951 may be anything which can be converted to a
6958 is the content of the target file.
6964 .RI CheckContext.TryBuild( self ", " builder ", [" text ", " extension ])
6965 Low level implementation for testing specific builds;
6966 the methods above are based on this method.
6967 Given the Builder instance
6971 of a source file with optional
6973 this method returns 1 on success and 0 on failure. In addition,
6975 is set to the build target node, if the build was successful.
6978 Example for implementing and using custom tests:
6981 def CheckQt(context, qtdir):
6982 context.Message( 'Checking for qt ...' )
6983 lastLIBS = context.env['LIBS']
6984 lastLIBPATH = context.env['LIBPATH']
6985 lastCPPPATH= context.env['CPPPATH']
6986 context.env.Append(LIBS = 'qt', LIBPATH = qtdir + '/lib', CPPPATH = qtdir + '/include' )
6987 ret = context.TryLink("""
6989 int main(int argc, char **argv) {
6990 QApplication qapp(argc, argv);
6995 context.env.Replace(LIBS = lastLIBS, LIBPATH=lastLIBPATH, CPPPATH=lastCPPPATH)
6996 context.Result( ret )
7000 conf = Configure( env, custom_tests = { 'CheckQt' : CheckQt } )
7001 if not conf.CheckQt('/usr/lib/qt'):
7002 print 'We really need qt!'
7007 .SS Command-Line Construction Variables
7009 Often when building software,
7010 some variables must be specified at build time.
7011 For example, libraries needed for the build may be in non-standard
7012 locations, or site-specific compiler options may need to be passed to the
7017 object to support overriding construction variables
7018 on the command line:
7020 $ scons VARIABLE=foo
7022 The variable values can also be specified in a text-based SConscript file.
7023 To create a Variables object, call the Variables() function:
7026 .RI Variables([ files "], [" args ])
7027 This creates a Variables object that will read construction variables from
7028 the file or list of filenames specified in
7030 If no files are specified,
7035 then no files will be read.
7036 The optional argument
7039 values that will override anything read from the specified files;
7040 it is primarily intended to be passed the
7042 dictionary that holds variables
7043 specified on the command line.
7047 vars = Variables('custom.py')
7048 vars = Variables('overrides.py', ARGUMENTS)
7049 vars = Variables(None, {FOO:'expansion', BAR:7})
7052 Variables objects have the following methods:
7055 .RI Add( key ", [" help ", " default ", " validator ", " converter ])
7056 This adds a customizable construction variable to the Variables object.
7058 is the name of the variable.
7060 is the help text for the variable.
7062 is the default value of the variable;
7063 if the default value is
7065 and there is no explicit value specified,
7066 the construction variable will
7068 be added to the construction environment.
7070 is called to validate the value of the variable, and should take three
7071 arguments: key, value, and environment.
7072 The recommended way to handle an invalid value is
7073 to raise an exception (see example below).
7075 is called to convert the value before putting it in the environment, and
7076 should take either a value, or the value and environment, as parameters.
7079 must return a value,
7080 which will be converted into a string
7081 before being validated by the
7084 and then added to the environment.
7089 vars.Add('CC', 'The C compiler')
7091 def validate_color(key, val, env):
7092 if not val in ['red', 'blue', 'yellow']:
7093 raise "Invalid color value '%s'" % val
7094 vars.Add('COLOR', validator=valid_color)
7098 .RI AddVariables( list )
7099 A wrapper script that adds
7100 multiple customizable construction variables
7101 to a Variables object.
7103 is a list of tuple or list objects
7104 that contain the arguments
7105 for an individual call to the
7112 ('CC', 'The C compiler'),
7113 ('VALIDATE', 'An option for testing validation',
7114 'notset', validator, None),
7119 .RI Update( env ", [" args ])
7120 This updates a construction environment
7122 with the customized construction variables.
7123 Any specified variables that are
7125 configured for the Variables object
7126 will be saved and may be
7128 .BR UnknownVariables ()
7131 Normally this method is not called directly,
7132 but is called indirectly by passing the Variables object to
7133 the Environment() function:
7136 env = Environment(variables=vars)
7140 The text file(s) that were specified
7141 when the Variables object was created
7142 are executed as Python scripts,
7143 and the values of (global) Python variables set in the file
7144 are added to the construction environment.
7153 .RI UnknownVariables( )
7154 Returns a dictionary containing any
7155 variables that were specified
7156 either in the files or the dictionary
7157 with which the Variables object was initialized,
7158 but for which the Variables object was
7162 env = Environment(variables=vars)
7163 for key, value in vars.UnknownVariables():
7164 print "unknown variable: %s=%s" % (key, value)
7168 .RI Save( filename ", " env )
7169 This saves the currently set variables into a script file named
7171 that can be used on the next invocation to automatically load the current
7172 settings. This method combined with the Variables method can be used to
7173 support caching of variables between runs.
7177 vars = Variables(['variables.cache', 'custom.py'])
7180 vars.Save('variables.cache', env)
7184 .RI GenerateHelpText( env ", [" sort ])
7185 This generates help text documenting the customizable construction
7186 variables suitable to passing in to the Help() function.
7188 is the construction environment that will be used to get the actual values
7189 of customizable variables. Calling with
7193 will cause the output to be sorted
7194 by the specified argument.
7198 should take two arguments
7201 (like the standard Python
7206 Help(vars.GenerateHelpText(env))
7207 Help(vars.GenerateHelpText(env, sort=cmp))
7211 .RI FormatVariableHelpText( env ", " opt ", " help ", " default ", " actual )
7212 This method returns a formatted string
7213 containing the printable help text
7215 It is normally not called directly,
7216 but is called by the
7217 .IR GenerateHelpText ()
7218 method to create the returned help text.
7219 It may be overridden with your own
7220 function that takes the arguments specified above
7221 and returns a string of help text formatted to your liking.
7223 .IR GenerateHelpText ()
7224 will not put any blank lines or extra
7225 characters in between the entries,
7226 so you must add those characters to the returned
7227 string if you want the entries separated.
7230 def my_format(env, opt, help, default, actual):
7231 fmt = "\n%s: default=%s actual=%s (%s)\n"
7232 return fmt % (opt, default. actual, help)
7233 vars.FormatVariableHelpText = my_format
7236 To make it more convenient to work with customizable Variables,
7238 provides a number of functions
7239 that make it easy to set up
7240 various types of Variables:
7243 .RI BoolVariable( key ", " help ", " default )
7244 Return a tuple of arguments
7245 to set up a Boolean option.
7249 have a default value of
7251 and display the specified
7254 The option will interpret the values
7276 .RI EnumVariable( key ", " help ", " default ", " allowed_values ", [" map ", " ignorecase ])
7277 Return a tuple of arguments
7279 whose value may be one
7280 of a specified list of legal enumerated values.
7284 have a default value of
7286 and display the specified
7289 The option will only support those
7295 argument is a dictionary
7296 that can be used to convert
7297 input values into specific legal values
7306 then the values are case-sensitive.
7311 then values will be matched
7317 then values will be matched
7319 and all input values will be
7320 converted to lower case.
7323 .RI ListVariable( key ", " help ", " default ", " names ", [", map ])
7324 Return a tuple of arguments
7326 whose value may be one or more
7327 of a specified list of legal enumerated values.
7331 have a default value of
7333 and display the specified
7336 The option will only support the values
7339 or the values in the
7342 More than one value may be specified,
7343 with all values separated by commas.
7344 The default may be a string of
7345 comma-separated default values,
7346 or a list of the default values.
7349 argument is a dictionary
7350 that can be used to convert
7351 input values into specific legal values
7357 .RI PackageVariable( key ", " help ", " default )
7358 Return a tuple of arguments
7360 whose value is a path name
7361 of a package that may be
7362 enabled, disabled or
7363 given an explicit path name.
7367 have a default value of
7369 and display the specified
7372 The option will support the values
7379 in which case the specified
7382 or the option may be set to an
7384 (typically the path name to a package
7385 that is being enabled).
7386 The option will also support the values
7392 to disable use of the specified option.
7395 .RI PathVariable( key ", " help ", " default ", [" validator ])
7396 Return a tuple of arguments
7398 whose value is expected to be a path name.
7402 have a default value of
7404 and display the specified
7410 that will be called to
7411 verify that the specified path
7414 following ready-made validators:
7415 .BR PathVariable.PathExists
7417 which verifies that the specified path exists;
7418 .BR PathVariable.PathIsFile ,
7419 which verifies that the specified path is an existing file;
7420 .BR PathVariable.PathIsDir ,
7421 which verifies that the specified path is an existing directory;
7422 .BR PathVariable.PathIsDirCreate ,
7423 which verifies that the specified path is a directory
7424 and will create the specified directory if the path does not exist;
7426 .BR PathVariable.PathAccept ,
7427 which simply accepts the specific path name argument without validation,
7428 and which is suitable if you want your users
7429 to be able to specify a directory path that will be
7430 created as part of the build process, for example.
7431 You may supply your own
7434 which must take three arguments
7436 the name of the variable to be set;
7438 the specified value being checked;
7441 the construction environment)
7442 and should raise an exception
7443 if the specified value is not acceptable.
7446 These functions make it
7447 convenient to create a number
7448 of variables with consistent behavior
7449 in a single call to the
7455 BoolVariable('warnings', 'compilation with -Wall and similiar', 1),
7456 EnumVariable('debug', 'debug output and symbols', 'no'
7457 allowed_values=('yes', 'no', 'full'),
7458 map={}, ignorecase=0), # case sensitive
7459 ListVariable('shared',
7460 'libraries to build as shared libraries',
7462 names = list_of_libs),
7463 PackageVariable('x11',
7464 'use X11 installed here (yes = search some places)',
7466 PathVariable('qtdir', 'where the root of Qt is installed', qtdir),
7467 PathVariable('foopath', 'where the foo library is installed', foopath,
7468 PathVariable.PathIsDir),
7473 .SS File and Directory Nodes
7483 Nodes, respectively.
7484 python objects, respectively.
7485 Those objects have several user-visible attributes
7486 and methods that are often useful:
7492 This path is relative to the top-level directory
7496 The build path is the same as the source path if
7501 The absolute build path of the given file or directory.
7511 object representing the
7520 # Get the current build dir's path, relative to top.
7522 # Current dir's absolute path
7524 # Next line is always '.', because it is the top dir's path relative to itself.
7526 File('foo.c').srcnode().path # source path of the given source file.
7528 # Builders also return File objects:
7529 foo = env.Program('foo.c')
7530 print "foo will be built in %s"%foo.path
7537 Node can also be used to create
7538 file and subdirectory Nodes relative to the generating Node.
7541 Node will place the new Nodes within the directory it represents.
7544 node will place the new Nodes within its parent directory
7545 (that is, "beside" the file in question).
7550 (directory) Node and
7555 then these methods are available:
7559 Returns a directory Node for a subdirectory of
7566 Returns a file Node for a file within
7572 .IR d .Entry( name )
7573 Returns an unresolved Node within
7580 Returns a directory named
7582 within the parent directory of
7587 Returns a file named
7589 within the parent directory of
7593 .IR f .Entry( name )
7594 Returns an unresolved Node named
7596 within the parent directory of
7603 # Get a Node for a file within a directory
7604 incl = Dir('include')
7605 f = incl.File('header.h')
7607 # Get a Node for a subdirectory within a directory
7608 dist = Dir('project-3.2.1)
7609 src = dist.Dir('src')
7611 # Get a Node for a file in the same directory
7612 cfile = File('sample.c')
7613 hfile = cfile.File('sample.h')
7617 html = docs.Dir('html')
7618 index = html.File('index.html')
7619 css = index.File('app.css')
7625 can be extended to build different types of targets
7626 by adding new Builder objects
7627 to a construction environment.
7629 you should only need to add a new Builder object
7630 when you want to build a new type of file or other external target.
7631 If you just want to invoke a different compiler or other tool
7632 to build a Program, Object, Library, or any other
7633 type of output file for which
7635 already has an existing Builder,
7636 it is generally much easier to
7637 use those existing Builders
7638 in a construction environment
7639 that sets the appropriate construction variables
7642 Builder objects are created
7648 function accepts the following arguments:
7651 The command line string used to build the target from the source.
7654 a list of strings representing the command
7655 to be executed and its arguments
7656 (suitable for enclosing white space in an argument),
7658 mapping source file name suffixes to
7659 any combination of command line strings
7660 (if the builder should accept multiple source file extensions),
7663 (see the next section);
7664 or a list of any of the above.
7667 takes three arguments:
7669 - a list of source nodes,
7671 - a list of target nodes,
7673 - the construction environment.
7676 The prefix that will be prepended to the target file name.
7677 This may be specified as a:
7687 - a function or other callable that takes
7688 two arguments (a construction environment and a list of sources)
7689 and returns a prefix,
7694 - specifies a mapping from a specific source suffix (of the first
7695 source specified) to a corresponding target prefix. Both the source
7696 suffix and target prefix specifications may use environment variable
7697 substitution, and the target prefix (the 'value' entries in the
7698 dictionary) may also be a callable object. The default target prefix
7699 may be indicated by a dictionary entry with a key value of None.
7704 b = Builder("build_it < $SOURCE > $TARGET"
7707 def gen_prefix(env, sources):
7708 return "file-" + env['PLATFORM'] + '-'
7709 b = Builder("build_it < $SOURCE > $TARGET",
7710 prefix = gen_prefix)
7712 b = Builder("build_it < $SOURCE > $TARGET",
7713 suffix = { None: "file-",
7714 "$SRC_SFX_A": gen_prefix })
7718 The suffix that will be appended to the target file name.
7719 This may be specified in the same manner as the prefix above.
7720 If the suffix is a string, then
7722 will append a '.' to the beginning of the suffix if it's not already
7723 there. The string returned by callable object (or obtained from the
7724 dictionary) is untouched and must append its own '.' to the beginning
7728 b = Builder("build_it < $SOURCE > $TARGET"
7731 def gen_suffix(env, sources):
7732 return "." + env['PLATFORM'] + "-file"
7733 b = Builder("build_it < $SOURCE > $TARGET",
7734 suffix = gen_suffix)
7736 b = Builder("build_it < $SOURCE > $TARGET",
7737 suffix = { None: ".sfx1",
7738 "$SRC_SFX_A": gen_suffix })
7742 When set to any true value, causes
7744 to add the target suffix specified by the
7746 keyword to any target strings
7747 that have a different suffix.
7748 (The default behavior is to leave untouched
7749 any target file name that looks like it already has any suffix.)
7752 b1 = Builder("build_it < $SOURCE > $TARGET"
7754 b2 = Builder("build_it < $SOURCE > $TARGET"
7758 env['BUILDERS']['B1'] = b1
7759 env['BUILDERS']['B2'] = b2
7761 # Builds "foo.txt" because ensure_suffix is not set.
7762 env.B1('foo.txt', 'foo.in')
7764 # Builds "bar.txt.out" because ensure_suffix is set.
7765 env.B2('bar.txt', 'bar.in')
7769 The expected source file name suffix. This may be a string or a list
7773 A Scanner object that
7774 will be invoked to find
7775 implicit dependencies for this target file.
7776 This keyword argument should be used
7777 for Scanner objects that find
7778 implicit dependencies
7779 based only on the target file
7780 and the construction environment,
7783 (See the section "Scanner Objects," below,
7784 for information about creating Scanner objects.)
7787 A Scanner object that
7789 find implicit dependences in
7791 used to build this target file.
7792 This is where you would
7793 specify a scanner to
7796 lines in source files.
7799 Scanner object may be used to
7800 indicate that this Builder
7801 should scan directory trees
7802 for on-disk changes to files
7805 does not know about from other Builder or function calls.
7806 (See the section "Scanner Objects," below,
7807 for information about creating your own Scanner objects.)
7810 A factory function that the Builder will use
7811 to turn any targets specified as strings into SCons Nodes.
7813 SCons assumes that all targets are files.
7814 Other useful target_factory
7817 for when a Builder creates a directory target,
7820 for when a Builder can create either a file
7821 or directory target.
7826 MakeDirectoryBuilder = Builder(action=my_mkdir, target_factory=Dir)
7828 env.Append(BUILDERS = {'MakeDirectory':MakeDirectoryBuilder})
7829 env.MakeDirectory('new_directory', [])
7833 Note that the call to the MakeDirectory Builder
7834 needs to specify an empty source list
7835 to make the string represent the builder's target;
7836 without that, it would assume the argument is the source,
7837 and would try to deduce the target name from it,
7838 which in the absence of an automatically-added prefix or suffix
7839 would lead to a matching target and source name
7840 and a circular dependency.
7843 A factory function that the Builder will use
7844 to turn any sources specified as strings into SCons Nodes.
7846 SCons assumes that all source are files.
7847 Other useful source_factory
7850 for when a Builder uses a directory as a source,
7853 for when a Builder can use files
7854 or directories (or both) as sources.
7859 CollectBuilder = Builder(action=my_mkdir, source_factory=Entry)
7861 env.Append(BUILDERS = {'Collect':CollectBuilder})
7862 env.Collect('archive', ['directory_name', 'file_name'])
7866 A function or list of functions to manipulate the target and source
7867 lists before dependencies are established
7868 and the target(s) are actually built.
7870 can also be a string containing a construction variable to expand
7871 to an emitter function or list of functions,
7872 or a dictionary mapping source file suffixes
7873 to emitter functions.
7874 (Only the suffix of the first source file
7875 is used to select the actual emitter function
7876 from an emitter dictionary.)
7879 takes three arguments:
7881 - a list of source nodes,
7883 - a list of target nodes,
7885 - the construction environment.
7886 An emitter must return a tuple containing two lists,
7887 the list of targets to be built by this builder,
7888 and the list of sources for this builder.
7893 def e(target, source, env):
7894 return (target + ['foo.foo'], source + ['foo.src'])
7896 # Simple association of an emitter function with a Builder.
7897 b = Builder("my_build < $TARGET > $SOURCE",
7900 def e2(target, source, env):
7901 return (target + ['bar.foo'], source + ['bar.src'])
7903 # Simple association of a list of emitter functions with a Builder.
7904 b = Builder("my_build < $TARGET > $SOURCE",
7907 # Calling an emitter function through a construction variable.
7908 env = Environment(MY_EMITTER = e)
7909 b = Builder("my_build < $TARGET > $SOURCE",
7910 emitter = '$MY_EMITTER')
7912 # Calling a list of emitter functions through a construction variable.
7913 env = Environment(EMITTER_LIST = [e, e2])
7914 b = Builder("my_build < $TARGET > $SOURCE",
7915 emitter = '$EMITTER_LIST')
7917 # Associating multiple emitters with different file
7918 # suffixes using a dictionary.
7919 def e_suf1(target, source, env):
7920 return (target + ['another_target_file'], source)
7921 def e_suf2(target, source, env):
7922 return (target, source + ['another_source_file'])
7923 b = Builder("my_build < $TARGET > $SOURCE",
7924 emitter = {'.suf1' : e_suf1,
7929 Specifies whether this builder is allowed to be called multiple times for
7930 the same target file(s). The default is 0, which means the builder
7931 can not be called multiple times for the same target file(s). Calling a
7932 builder multiple times for the same target simply adds additional source
7933 files to the target; it is not allowed to change the environment associated
7934 with the target, specify addition environment overrides, or associate a different
7935 builder with the target.
7938 A construction environment that can be used
7939 to fetch source code using this Builder.
7940 (Note that this environment is
7942 used for normal builds of normal target files,
7943 which use the environment that was
7944 used to call the Builder for the target file.)
7947 A function that returns a list of actions that will be executed to build
7948 the target(s) from the source(s).
7949 The returned action(s) may be
7950 an Action object, or anything that
7951 can be converted into an Action object
7952 (see the next section).
7954 The generator function
7955 takes four arguments:
7957 - a list of source nodes,
7959 - a list of target nodes,
7961 - the construction environment,
7963 - a Boolean value that specifies
7964 whether the generator is being called
7965 for generating a build signature
7966 (as opposed to actually executing the command).
7970 def g(source, target, env, for_signature):
7971 return [["gcc", "-c", "-o"] + target + source]
7973 b = Builder(generator=g)
7981 arguments must not both be used for the same Builder.
7984 Specifies a builder to use when a source file name suffix does not match
7985 any of the suffixes of the builder. Using this argument produces a
7986 multi-stage builder.
7989 Specifies that this builder expects exactly one source file per call. Giving
7990 more than one source files without target files results in implicitely calling
7991 the builder multiple times (once for each source given). Giving multiple
7992 source files together with target files results in a UserError exception.
8000 arguments must not both be used for the same Builder.
8002 .IP source_ext_match
8005 argument is a dictionary,
8006 the default behavior when a builder is passed
8007 multiple source files is to make sure that the
8008 extensions of all the source files match.
8009 If it is legal for this builder to be
8010 called with a list of source files with different extensions,
8011 this check can be suppressed by setting
8015 or some other non-true value.
8020 will use the suffix of the first specified
8021 source file to select the appropriate action from the
8025 In the following example,
8030 from exiting with an error
8031 due to the mismatched suffixes of
8037 b = Builder(action={'.in' : 'build $SOURCES > $TARGET'},
8038 source_ext_match = None)
8040 env = Environment(BUILDERS = {'MyBuild':b})
8041 env.MyBuild('foo.out', ['foo.in', 'foo.extra'])
8045 A construction environment that can be used
8046 to fetch source code using this Builder.
8047 (Note that this environment is
8049 used for normal builds of normal target files,
8050 which use the environment that was
8051 used to call the Builder for the target file.)
8054 b = Builder(action="build < $SOURCE > $TARGET")
8055 env = Environment(BUILDERS = {'MyBuild' : b})
8056 env.MyBuild('foo.out', 'foo.in', my_arg = 'xyzzy')
8060 A directory from which scons
8067 a string or a directory Node,
8068 scons will change to the specified directory.
8071 is not a string or Node
8073 then scons will change to the
8074 target file's directory.
8076 Note that scons will
8078 automatically modify
8080 construction variables like
8084 when using the chdir
8085 keyword argument--that is,
8086 the expanded file names
8087 will still be relative to
8088 the top-level SConstruct directory,
8089 and consequently incorrect
8090 relative to the chdir directory.
8091 Builders created using chdir keyword argument,
8092 will need to use construction variable
8097 to use just the filename portion of the
8101 b = Builder(action="build < ${SOURCE.file} > ${TARGET.file}",
8103 env = Environment(BUILDERS = {'MyBuild' : b})
8104 env.MyBuild('sub/dir/foo.out', 'sub/dir/foo.in')
8108 Python only keeps one current directory
8109 location for all of the threads.
8110 This means that use of the
8118 because individual worker threads spawned
8119 by SCons interfere with each other
8120 when they start changing directory.
8123 Any additional keyword arguments supplied
8124 when a Builder object is created
8125 (that is, when the Builder() function is called)
8126 will be set in the executing construction
8127 environment when the Builder object is called.
8128 The canonical example here would be
8129 to set a construction variable to
8130 the repository of a source code system.
8132 Any additional keyword arguments supplied
8136 will only be associated with the target
8137 created by that particular Builder call
8138 (and any other files built as a
8139 result of the call).
8141 These extra keyword arguments are passed to the
8142 following functions:
8143 command generator functions,
8145 and emitter functions.
8151 function will turn its
8153 keyword argument into an appropriate
8154 internal Action object.
8155 You can also explicity create Action objects
8159 which can then be passed to the
8162 This can be used to configure
8163 an Action object more flexibly,
8164 or it may simply be more efficient
8165 than letting each separate Builder object
8166 create a separate Action
8168 Builder objects need to do the same thing.
8173 returns an appropriate object for the action
8174 represented by the type of the first argument:
8177 If the first argument is already an Action object,
8178 the object is simply returned.
8181 If the first argument is a string,
8182 a command-line Action is returned.
8183 Note that the command line string
8184 may be preceded by an
8187 to suppress printing of the
8188 specified command line,
8192 to ignore the exit status from
8193 the specified command.
8197 Action('$CC -c -o $TARGET $SOURCES')
8199 # Doesn't print the line being executed.
8200 Action('@build $TARGET $SOURCES')
8203 Action('-build $TARGET $SOURCES')
8206 .\" XXX From Gary Ruben, 23 April 2002:
8207 .\" What would be useful is a discussion of how you execute command
8208 .\" shell commands ie. what is the process used to spawn the shell, pass
8209 .\" environment variables to it etc., whether there is one shell per
8210 .\" environment or one per command etc. It might help to look at the Gnu
8211 .\" make documentation to see what they think is important to discuss about
8212 .\" a build system. I'm sure you can do a better job of organising the
8213 .\" documentation than they have :-)
8217 If the first argument is a list,
8218 then a list of Action objects is returned.
8219 An Action object is created as necessary
8220 for each element in the list.
8223 the list is itself a list,
8224 the internal list is the
8225 command and arguments to be executed via
8227 This allows white space to be enclosed
8228 in an argument by defining
8229 a command in a list within a list:
8232 Action([['cc', '-c', '-DWHITE SPACE', '-o', '$TARGET', '$SOURCES']])
8236 If the first argument is a Python function,
8237 a function Action is returned.
8238 The Python function takes three keyword arguments,
8240 (a Node object representing the target file),
8242 (a Node object representing the source file)
8245 (the construction environment
8246 used for building the target file).
8251 arguments may be lists of Node objects if there is
8252 more than one target file or source file.
8253 The actual target and source file name(s) may
8254 be retrieved from their Node objects
8255 via the built-in Python str() function:
8258 target_file_name = str(target)
8259 source_file_names = map(lambda x: str(x), source)
8262 The function should return
8266 to indicate a successful build of the target file(s).
8267 The function may raise an exception
8268 or return a non-zero exit status
8269 to indicate an unsuccessful build.
8272 def build_it(target = None, source = None, env = None):
8273 # build the target from the source
8276 a = Action(build_it)
8279 If the action argument is not one of the above,
8283 The second, optional argument
8284 is used to define the output which is printed
8285 when the Action is actually performed.
8286 In the absence of this parameter, or if it's an
8287 empty string, a default output depending on the type of the action
8288 is used. For example, a command-line action will print
8289 the executed command. The argument is either a python function
8292 In the first case, it's a function that returns
8293 a string to be printed to describe the action being executed.
8294 Like a function to build a file,
8295 this function takes three arguments:
8297 (a Node object representing the target file),
8299 (a Node object representing the source file)
8302 (a construction environment).
8307 arguments may be lists of Node objects if there is
8308 more than one target file or source file.
8310 In the second case, you provide the string itself.
8311 The string typically contains variables, notably
8312 $TARGET(S) and $SOURCE(S), or consists of just a single
8313 variable, which is optionally defined somewhere else.
8314 SCons itself heavily uses the latter variant.
8319 def build_it(target, source, env):
8320 # build the target from the source
8323 def string_it(target, source, env):
8324 return "building '%s' from '%s'" % (target[0], source[0])
8326 # Use a positional argument.
8327 f = Action(build_it, string_it)
8328 s = Action(build_it, "building '$TARGET' from '$SOURCE'")
8330 # Alternatively, use a keyword argument.
8331 f = Action(build_it, strfunction=string_it)
8332 s = Action(build_it, cmdstr="building '$TARGET' from '$SOURCE'")
8334 # You can provide a configurable variable.
8335 l = Action(build_it, '$STRINGIT')
8338 The third, also optional argument
8339 is a list of construction variables
8340 whose values will be included
8341 in the signature of the Action
8342 when deciding whether a target should
8343 be rebuilt because the action changed.
8344 This is necessary whenever you want a target to
8345 be rebuilt when a specific
8346 construction variable changes,
8347 because the underlying Python code for a function
8348 will not change when the value of the construction variable does.
8351 def build_it(target, source, env):
8352 # build the target from the 'XXX' construction variable
8353 open(target[0], 'w').write(env['XXX'])
8356 # Use positional arguments.
8357 a = Action(build_it, '$STRINGIT', ['XXX'])
8359 # Alternatively, use a keyword argument.
8360 a = Action(build_it, varlist=['XXX'])
8369 which specifies that
8370 scons will execute the action
8371 after changing to the specified directory.
8372 If the chdir argument is
8373 a string or a directory Node,
8374 scons will change to the specified directory.
8375 If the chdir argument
8376 is not a string or Node
8378 then scons will change to the
8379 target file's directory.
8381 Note that scons will
8383 automatically modify
8385 construction variables like
8389 when using the chdir
8390 keyword argument--that is,
8391 the expanded file names
8392 will still be relative to
8393 the top-level SConstruct directory,
8394 and consequently incorrect
8395 relative to the chdir directory.
8396 Builders created using chdir keyword argument,
8397 will need to use construction variable
8402 to use just the filename portion of the
8406 a = Action("build < ${SOURCE.file} > ${TARGET.file}",
8416 which specifies a function
8417 that is passed the exit status
8419 from the specified action
8420 and can return an arbitrary
8422 This can be used, for example,
8423 to specify that an Action object's
8424 return value should be ignored
8425 and SCons should, therefore,
8426 consider that the action always suceeds:
8429 def always_succeed(s):
8430 # Always return 0, which indicates success.
8432 a = Action("build < ${SOURCE.file} > ${TARGET.file}",
8433 exitstatfunc=always_succeed)
8436 .SS Miscellaneous Action Functions
8439 supplies a number of functions
8440 that arrange for various common
8441 file and directory manipulations
8443 These are similar in concept to "tasks" in the
8445 although the implementation is slightly different.
8446 These functions do not actually
8447 perform the specified action
8448 at the time the function is called,
8449 but instead return an Action object
8450 that can be executed at the
8452 (In Object-Oriented terminology,
8457 that return Action objects.)
8460 there are two natural ways
8463 are intended to be used.
8467 to perform the action
8468 at the time the SConscript
8472 global function to do so:
8474 Execute(Touch('file'))
8478 you can use these functions
8479 to supply Actions in a list
8483 This can allow you to
8484 perform more complicated
8485 sequences of file manipulation
8487 on platform-specific
8491 env = Environment(TMPBUILD = '/tmp/builddir')
8492 env.Command('foo.out', 'foo.in',
8493 [Mkdir('$TMPBUILD'),
8494 Copy('$TMPBUILD', '${SOURCE.dir}'),
8495 "cd $TMPBUILD && make",
8496 Delete('$TMPBUILD')])
8500 .RI Chmod( dest ", " mode )
8501 Returns an Action object that
8502 changes the permissions on the specified
8504 file or directory to the specified
8509 Execute(Chmod('file', 0755))
8511 env.Command('foo.out', 'foo.in',
8512 [Copy('$TARGET', '$SOURCE'),
8513 Chmod('$TARGET', 0755)])
8517 .RI Copy( dest ", " src )
8518 Returns an Action object
8521 source file or directory to the
8523 destination file or directory.
8527 Execute(Copy('foo.output', 'foo.input'))
8529 env.Command('bar.out', 'bar.in',
8530 Copy('$TARGET', '$SOURCE'))
8534 .RI Delete( entry ", [" must_exist ])
8535 Returns an Action that
8536 deletes the specified
8538 which may be a file or a directory tree.
8539 If a directory is specified,
8540 the entire directory tree
8545 then a Python error will be thrown
8546 if the specified entry does not exist;
8549 that is, the Action will silently do nothing
8550 if the entry does not exist.
8554 Execute(Delete('/tmp/buildroot'))
8556 env.Command('foo.out', 'foo.in',
8557 [Delete('${TARGET.dir}'),
8560 Execute(Delete('file_that_must_exist', must_exist=1))
8566 that creates the specified
8572 Execute(Mkdir('/tmp/outputdir'))
8574 env.Command('foo.out', 'foo.in',
8575 [Mkdir('/tmp/builddir',
8576 Copy('$SOURCE', '/tmp/builddir/foo.in')
8577 "cd /tmp/builddir && make",
8578 Copy('/tmp/builddir/foo.out', '$TARGET')])
8582 .RI Move( dest ", " src )
8584 that moves the specified
8586 file or directory to
8593 Execute(Move('file.destination', 'file.source'))
8595 env.Command('output_file', 'input_file',
8597 Move('$TARGET', 'file_created_by_MyBuildAction')])
8603 that updates the modification time
8609 Execute(Touch('file_to_be_touched'))
8611 env.Command('marker', 'input_file',
8616 .SS Variable Substitution
8618 Before executing a command,
8620 performs construction variable interpolation on the strings that make up
8621 the command line of builders.
8622 Variables are introduced by a
8625 Besides construction variables, scons provides the following
8626 variables for each command execution:
8629 The file name of the target being built, or the file name of the first
8630 target if multiple targets are being built.
8633 The file names of all targets being built.
8636 The file name of the source of the build command, or the file name of the
8637 first source if multiple sources are being built.
8640 The file names of the sources of the build command.
8642 (Note that the above variables are reserved
8643 and may not be set in a construction environment.)
8646 For example, given the construction variable CC='cc', targets=['foo'], and
8647 sources=['foo.c', 'bar.c']:
8650 action='$CC -c -o $TARGET $SOURCES'
8653 would produce the command line:
8656 cc -c -o foo foo.c bar.c
8659 Variable names may be surrounded by curly braces ({})
8660 to separate the name from the trailing characters.
8661 Within the curly braces, a variable name may have
8662 a Python slice subscript appended to select one
8663 or more items from a list.
8664 In the previous example, the string:
8676 Additionally, a variable name may
8677 have the following special
8678 modifiers appended within the enclosing curly braces
8679 to modify the interpolated string:
8682 The base path of the file name,
8683 including the directory path
8684 but excluding any suffix.
8687 The name of the directory in which the file exists.
8691 minus any directory portion.
8694 Just the basename of the file,
8696 and minus the directory.
8699 Just the file suffix.
8702 The absolute path name of the file.
8705 The POSIX form of the path,
8706 with directories separated by
8710 This is sometimes necessary on Windows systems
8711 when a path references a file on other (POSIX) systems.
8714 The directory and file name to the source file linked to this file through
8716 If this file isn't linked,
8717 it just returns the directory and filename unchanged.
8720 The directory containing the source file linked to this file through
8722 If this file isn't linked,
8723 it just returns the directory part of the filename.
8726 The directory and file name to the source file linked to this file through
8728 If the file does not exist locally but exists in a Repository,
8729 the path in the Repository is returned.
8730 If this file isn't linked, it just returns the
8731 directory and filename unchanged.
8734 The Repository directory containing the source file linked to this file through
8736 If this file isn't linked,
8737 it just returns the directory part of the filename.
8740 For example, the specified target will
8741 expand as follows for the corresponding modifiers:
8744 $TARGET => sub/dir/file.x
8745 ${TARGET.base} => sub/dir/file
8746 ${TARGET.dir} => sub/dir
8747 ${TARGET.file} => file.x
8748 ${TARGET.filebase} => file
8749 ${TARGET.suffix} => .x
8750 ${TARGET.abspath} => /top/dir/sub/dir/file.x
8752 SConscript('src/SConscript', variant_dir='sub/dir')
8753 $SOURCE => sub/dir/file.x
8754 ${SOURCE.srcpath} => src/file.x
8755 ${SOURCE.srcdir} => src
8757 Repository('/usr/repository')
8758 $SOURCE => sub/dir/file.x
8759 ${SOURCE.rsrcpath} => /usr/repository/src/file.x
8760 ${SOURCE.rsrcdir} => /usr/repository/src
8763 Note that curly braces braces may also be used
8764 to enclose arbitrary Python code to be evaluated.
8765 (In fact, this is how the above modifiers are substituted,
8766 they are simply attributes of the Python objects
8767 that represent TARGET, SOURCES, etc.)
8768 See the section "Python Code Substitution," below,
8769 for more thorough examples of
8770 how this can be used.
8772 Lastly, a variable name
8773 may be a callable Python function
8775 construction variable in the environment.
8777 take four arguments:
8779 - a list of target nodes,
8781 - a list of source nodes,
8783 - the construction environment,
8785 - a Boolean value that specifies
8786 whether the function is being called
8787 for generating a build signature.
8788 SCons will insert whatever
8789 the called function returns
8790 into the expanded string:
8793 def foo(target, source, env, for_signature):
8796 # Will expand $BAR to "bar baz"
8797 env=Environment(FOO=foo, BAR="$FOO baz")
8800 You can use this feature to pass arguments to a
8801 Python function by creating a callable class
8802 that stores one or more arguments in an object,
8803 and then uses them when the
8806 Note that in this case,
8807 the entire variable expansion must
8808 be enclosed by curly braces
8809 so that the arguments will
8810 be associated with the
8811 instantiation of the class:
8815 def __init__(self, arg):
8818 def __call__(self, target, source, env, for_signature):
8819 return self.arg + " bar"
8821 # Will expand $BAR to "my argument bar baz"
8822 env=Environment(FOO=foo, BAR="${FOO('my argument')} baz")
8826 The special pseudo-variables
8830 may be used to surround parts of a command line
8833 causing a rebuild--that is,
8834 which are not included in the signature
8835 of target files built with this command.
8840 will be removed from the command line
8841 before it is added to file signatures,
8846 will be removed before the command is executed.
8847 For example, the command line:
8850 echo Last build occurred $( $TODAY $). > $TARGET
8854 would execute the command:
8857 echo Last build occurred $TODAY. > $TARGET
8861 but the command signature added to any target files would be:
8864 echo Last build occurred . > $TARGET
8867 .SS Python Code Substitution
8869 Any python code within
8871 pairs gets evaluated by python 'eval', with the python globals set to
8872 the current environment's set of construction variables.
8873 So in the following case:
8876 env.Command('foo.out', 'foo.in',
8877 '''echo ${COND==1 and 'FOO' or 'BAR'} > $TARGET''')
8879 the command executed will be either
8887 according to the current value of env['COND'] when the command is
8888 executed. The evaluation occurs when the target is being
8889 built, not when the SConscript is being read. So if env['COND'] is changed
8890 later in the SConscript, the final value will be used.
8892 Here's a more interesting example. Note that all of COND, FOO, and
8893 BAR are environment variables, and their values are substituted into
8894 the final command. FOO is a list, so its elements are interpolated
8895 separated by spaces.
8900 env['FOO'] = ['foo1', 'foo2']
8901 env['BAR'] = 'barbar'
8902 env.Command('foo.out', 'foo.in',
8903 'echo ${COND==1 and FOO or BAR} > $TARGET')
8905 # Will execute this:
8906 # echo foo1 foo2 > foo.out
8909 SCons uses the following rules when converting construction variables into
8913 When the value is a string it is interpreted as a space delimited list of
8914 command line arguments.
8917 When the value is a list it is interpreted as a list of command line
8918 arguments. Each element of the list is converted to a string.
8921 Anything that is not a list or string is converted to a string and
8922 interpreted as a single command line argument.
8925 Newline characters (\\n) delimit lines. The newline parsing is done after
8926 all other parsing, so it is not possible for arguments (e.g. file names) to
8927 contain embedded newline characters. This limitation will likely go away in
8928 a future version of SCons.
8936 new file types for implicit dependencies.
8937 Scanner accepts the following arguments:
8941 1) a Python function that will process
8943 and return a list of strings (file names)
8944 representing the implicit
8945 dependencies found in the contents;
8947 2) a dictionary that maps keys
8948 (typically the file suffix, but see below for more discussion)
8949 to other Scanners that should be called.
8951 If the argument is actually a Python function,
8952 the function must take three or four arguments:
8954 def scanner_function(node, env, path):
8956 def scanner_function(node, env, path, arg=None):
8960 argument is the internal
8961 SCons node representing the file.
8964 to fetch the name of the file, and
8965 .B node.get_contents()
8966 to fetch contents of the file.
8967 Note that the file is
8969 guaranteed to exist before the scanner is called,
8970 so the scanner function should check that
8971 if there's any chance that the scanned file
8973 (for example, if it's built from other files).
8977 argument is the construction environment for the scan.
8978 Fetch values from it using the
8984 argument is a tuple (or list)
8985 of directories that can be searched
8987 This will usually be the tuple returned by the
8989 argument (see below).
8993 argument is the argument supplied
8994 when the scanner was created, if any.
8997 The name of the Scanner.
8999 to identify the Scanner internally.
9002 An optional argument that, if specified,
9003 will be passed to the scanner function
9005 and the path function
9009 An optional list that can be used to
9010 determine which scanner should be used for
9012 In the usual case of scanning for file names,
9013 this argument will be a list of suffixes
9014 for the different file types that this
9015 Scanner knows how to scan.
9016 If the argument is a string,
9017 then it will be expanded
9018 into a list by the current environment.
9021 A Python function that takes four or five arguments:
9022 a construction environment,
9023 a Node for the directory containing
9024 the SConscript file in which
9025 the first target was defined,
9026 a list of target nodes,
9027 a list of source nodes,
9028 and an optional argument supplied
9029 when the scanner was created.
9032 returns a tuple of directories
9033 that can be searched for files to be returned
9034 by this Scanner object.
9037 function can be used to return a ready-made
9039 for a given construction variable name,
9040 instead of having to write your own function from scratch.)
9043 The class of Node that should be returned
9044 by this Scanner object.
9045 Any strings or other objects returned
9046 by the scanner function
9047 that are not of this class
9048 will be run through the
9053 A Python function that will take a string
9055 and turn it into the appropriate class of Node
9056 to be returned by this Scanner object.
9059 An optional Python function that takes two arguments,
9060 a Node (file) and a construction environment,
9061 and returns whether the
9062 Node should, in fact,
9063 be scanned for dependencies.
9064 This check can be used to eliminate unnecessary
9065 calls to the scanner function when,
9066 for example, the underlying file
9067 represented by a Node does not yet exist.
9070 An optional flag that
9071 specifies whether this scanner should be re-invoked
9072 on the dependency files returned by the scanner.
9073 When this flag is not set,
9074 the Node subsystem will
9075 only invoke the scanner on the file being scanned,
9076 and not (for example) also on the files
9077 specified by the #include lines
9078 in the file being scanned.
9080 may be a callable function,
9081 in which case it will be called with a list of
9083 should return a list of Nodes
9084 that should be scanned recursively;
9085 this can be used to select a specific subset of
9086 Nodes for additional scanning.
9091 .B SourceFileScanner
9092 object that is used by
9095 .BR SharedObject (),
9099 which scanner should be used
9100 for different file extensions.
9102 .BR SourceFileScanner.add_scanner ()
9103 method to add your own Scanner object
9107 that builds target programs or
9108 libraries from a list of
9109 source files of different types:
9112 def xyz_scan(node, env, path):
9113 contents = node.get_contents()
9114 # Scan the contents and return the included files.
9116 XYZScanner = Scanner(xyz_scan)
9118 SourceFileScanner.add_scanner('.xyx', XYZScanner)
9120 env.Program('my_prog', ['file1.c', 'file2.f', 'file3.xyz'])
9123 .SH SYSTEM-SPECIFIC BEHAVIOR
9124 SCons and its configuration files are very portable,
9125 due largely to its implementation in Python.
9126 There are, however, a few portability
9127 issues waiting to trap the unwary.
9129 SCons handles the upper-case
9131 file suffix differently,
9132 depending on the capabilities of
9133 the underlying system.
9134 On a case-sensitive system
9135 such as Linux or UNIX,
9136 SCons treats a file with a
9138 suffix as a C++ source file.
9139 On a case-insensitive system
9141 SCons treats a file with a
9143 suffix as a C source file.
9145 SCons handles the upper-case
9147 file suffix differently,
9148 depending on the capabilities of
9149 the underlying system.
9150 On a case-sensitive system
9151 such as Linux or UNIX,
9152 SCons treats a file with a
9154 suffix as a Fortran source file
9155 that is to be first run through
9156 the standard C preprocessor.
9157 On a case-insensitive system
9159 SCons treats a file with a
9161 suffix as a Fortran source file that should
9163 be run through the C preprocessor.
9164 .SS Windows: Cygwin Tools and Cygwin Python vs. Windows Pythons
9165 Cygwin supplies a set of tools and utilities
9166 that let users work on a
9167 Windows system using a more POSIX-like environment.
9168 The Cygwin tools, including Cygwin Python,
9170 by sharing an ability to interpret UNIX-like path names.
9171 For example, the Cygwin tools
9172 will internally translate a Cygwin path name
9173 like /cygdrive/c/mydir
9174 to an equivalent Windows pathname
9175 of C:/mydir (equivalent to C:\\mydir).
9178 that are built for native Windows execution,
9179 such as the python.org and ActiveState versions,
9180 do not have the Cygwin path name semantics.
9181 This means that using a native Windows version of Python
9182 to build compiled programs using Cygwin tools
9183 (such as gcc, bison, and flex)
9184 may yield unpredictable results.
9185 "Mixing and matching" in this way
9186 can be made to work,
9187 but it requires careful attention to the use of path names
9188 in your SConscript files.
9190 In practice, users can sidestep
9191 the issue by adopting the following rules:
9193 use the Cygwin-supplied Python interpreter
9195 when using Microsoft Visual C/C++
9196 (or some other Windows compiler)
9197 use the python.org or ActiveState version of Python
9199 .SS Windows: scons.bat file
9201 SCons is executed via a wrapper
9204 This has (at least) two ramifications:
9206 First, Windows command-line users
9207 that want to use variable assignment
9209 may have to put double quotes
9210 around the assignments:
9213 scons "FOO=BAR" "BAZ=BLEH"
9216 Second, the Cygwin shell does not
9217 recognize this file as being the same
9220 command issued at the command-line prompt.
9221 You can work around this either by
9224 from the Cygwin command line,
9225 or by creating a wrapper shell
9231 The MinGW bin directory must be in your PATH environment variable or the
9232 PATH variable under the ENV construction variable for SCons
9233 to detect and use the MinGW tools. When running under the native Windows
9234 Python interpreter, SCons will prefer the MinGW tools over the Cygwin
9235 tools, if they are both installed, regardless of the order of the bin
9236 directories in the PATH variable. If you have both MSVC and MinGW
9237 installed and you want to use MinGW instead of MSVC,
9238 then you must explictly tell SCons to use MinGW by passing
9244 to the Environment() function, because SCons will prefer the MSVC tools
9245 over the MinGW tools.
9249 To help you get started using SCons,
9250 this section contains a brief overview of some common tasks.
9252 .SS Basic Compilation From a Single Source File
9256 env.Program(target = 'foo', source = 'foo.c')
9259 Note: Build the file by specifying
9260 the target as an argument
9261 ("scons foo" or "scons foo.exe").
9262 or by specifying a dot ("scons .").
9264 .SS Basic Compilation From Multiple Source Files
9268 env.Program(target = 'foo', source = Split('f1.c f2.c f3.c'))
9271 .SS Setting a Compilation Flag
9274 env = Environment(CCFLAGS = '-g')
9275 env.Program(target = 'foo', source = 'foo.c')
9278 .SS Search The Local Directory For .h Files
9282 need to set CCFLAGS to specify -I options by hand.
9283 SCons will construct the right -I options from CPPPATH.
9286 env = Environment(CPPPATH = ['.'])
9287 env.Program(target = 'foo', source = 'foo.c')
9290 .SS Search Multiple Directories For .h Files
9293 env = Environment(CPPPATH = ['include1', 'include2'])
9294 env.Program(target = 'foo', source = 'foo.c')
9297 .SS Building a Static Library
9301 env.StaticLibrary(target = 'foo', source = Split('l1.c l2.c'))
9302 env.StaticLibrary(target = 'bar', source = ['l3.c', 'l4.c'])
9305 .SS Building a Shared Library
9309 env.SharedLibrary(target = 'foo', source = ['l5.c', 'l6.c'])
9310 env.SharedLibrary(target = 'bar', source = Split('l7.c l8.c'))
9313 .SS Linking a Local Library Into a Program
9316 env = Environment(LIBS = 'mylib', LIBPATH = ['.'])
9317 env.Library(target = 'mylib', source = Split('l1.c l2.c'))
9318 env.Program(target = 'prog', source = ['p1.c', 'p2.c'])
9321 .SS Defining Your Own Builder Object
9323 Notice that when you invoke the Builder,
9324 you can leave off the target file suffix,
9325 and SCons will add it automatically.
9328 bld = Builder(action = 'pdftex < $SOURCES > $TARGET'
9330 src_suffix = '.tex')
9331 env = Environment(BUILDERS = {'PDFBuilder' : bld})
9332 env.PDFBuilder(target = 'foo.pdf', source = 'foo.tex')
9334 # The following creates "bar.pdf" from "bar.tex"
9335 env.PDFBuilder(target = 'bar', source = 'bar')
9338 Note also that the above initialization
9339 overwrites the default Builder objects,
9340 so the Environment created above
9341 can not be used call Builders like env.Program(),
9342 env.Object(), env.StaticLibrary(), etc.
9344 .SS Adding Your Own Builder Object to an Environment
9347 bld = Builder(action = 'pdftex < $SOURCES > $TARGET'
9349 src_suffix = '.tex')
9351 env.Append(BUILDERS = {'PDFBuilder' : bld})
9352 env.PDFBuilder(target = 'foo.pdf', source = 'foo.tex')
9353 env.Program(target = 'bar', source = 'bar.c')
9356 You also can use other Pythonic techniques to add
9357 to the BUILDERS construction variable, such as:
9361 env['BUILDERS]['PDFBuilder'] = bld
9364 .SS Defining Your Own Scanner Object
9366 The following example shows an extremely simple scanner (the
9369 that doesn't use a search path at all
9370 and simply returns the
9371 file names present on any
9373 lines in the scanned file.
9374 This would implicitly assume that all included
9375 files live in the top-level directory:
9380 '\" Note: the \\ in the following are for the benefit of nroff/troff,
9381 '\" not inappropriate doubled escape characters within the r'' raw string.
9382 include_re = re.compile(r'^include\\s+(\\S+)$', re.M)
9384 def kfile_scan(node, env, path, arg):
9385 contents = node.get_contents()
9386 includes = include_re.findall(contents)
9389 kscan = Scanner(name = 'kfile',
9390 function = kfile_scan,
9393 scanners = Environment().Dictionary('SCANNERS')
9394 env = Environment(SCANNERS = scanners + [kscan])
9396 env.Command('foo', 'foo.k', 'kprocess < $SOURCES > $TARGET')
9398 bar_in = File('bar.in')
9399 env.Command('bar', bar_in, 'kprocess $SOURCES > $TARGET')
9400 bar_in.target_scanner = kscan
9403 Here is a similar but more complete example that searches
9404 a path of directories
9407 construction variable)
9408 for files that actually exist:
9411 include_re = re.compile(r'^include\\s+(\\S+)$', re.M)
9413 def my_scan(node, env, path, arg):
9414 contents = node.get_contents()
9415 includes = include_re.findall(contents)
9419 for inc in includes:
9421 file = dir + os.sep + inc
9422 if os.path.exists(file):
9423 results.append(file)
9427 scanner = Scanner(name = 'myscanner',
9431 path_function = FindPathDirs('MYPATH'),
9433 scanners = Environment().Dictionary('SCANNERS')
9434 env = Environment(SCANNERS = scanners + [scanner])
9439 function used in the previous example returns a function
9440 (actually a callable Python object)
9441 that will return a list of directories
9444 construction variable.
9445 If you need to customize how the search path is derived,
9446 you would provide your own
9448 argument when creating the Scanner object,
9452 # MYPATH is a list of directories to search for files in
9453 def pf(env, dir, target, source, arg):
9454 top_dir = Dir('#').abspath
9456 if env.has_key('MYPATH'):
9457 for p in env['MYPATH']:
9458 results.append(top_dir + os.sep + p)
9461 scanner = Scanner(name = 'myscanner',
9469 .SS Creating a Hierarchical Build
9471 Notice that the file names specified in a subdirectory's
9473 file are relative to that subdirectory.
9479 env.Program(target = 'foo', source = 'foo.c')
9481 SConscript('sub/SConscript')
9486 # Builds sub/foo from sub/foo.c
9487 env.Program(target = 'foo', source = 'foo.c')
9489 SConscript('dir/SConscript')
9494 # Builds sub/dir/foo from sub/dir/foo.c
9495 env.Program(target = 'foo', source = 'foo.c')
9498 .SS Sharing Variables Between SConscript Files
9500 You must explicitly Export() and Import() variables that
9501 you want to share between SConscript files.
9507 env.Program(target = 'foo', source = 'foo.c')
9510 SConscript('subdirectory/SConscript')
9512 subdirectory/SConscript:
9515 env.Program(target = 'foo', source = 'foo.c')
9518 .SS Building Multiple Variants From the Same Source
9520 Use the variant_dir keyword argument to
9521 the SConscript function to establish
9522 one or more separate variant build directory trees
9523 for a given source directory:
9528 cppdefines = ['FOO']
9529 Export("cppdefines")
9530 SConscript('src/SConscript', variant_dir='foo')
9532 cppdefines = ['BAR']
9533 Export("cppdefines")
9534 SConscript('src/SConscript', variant_dir='bar')
9538 Import("cppdefines")
9539 env = Environment(CPPDEFINES = cppdefines)
9540 env.Program(target = 'src', source = 'src.c')
9543 Note the use of the Export() method
9544 to set the "cppdefines" variable to a different
9545 value each time we call the SConscript function.
9547 .SS Hierarchical Build of Two Libraries Linked With a Program
9552 env = Environment(LIBPATH = ['#libA', '#libB'])
9554 SConscript('libA/SConscript')
9555 SConscript('libB/SConscript')
9556 SConscript('Main/SConscript')
9561 env.Library('a', Split('a1.c a2.c a3.c'))
9566 env.Library('b', Split('b1.c b2.c b3.c'))
9571 e = env.Copy(LIBS = ['a', 'b'])
9572 e.Program('foo', Split('m1.c m2.c m3.c'))
9575 The '#' in the LIBPATH directories specify that they're relative to the
9576 top-level directory, so they don't turn into "Main/libA" when they're
9577 used in Main/SConscript.
9579 Specifying only 'a' and 'b' for the library names
9580 allows SCons to append the appropriate library
9581 prefix and suffix for the current platform
9582 (for example, 'liba.a' on POSIX systems,
9583 \&'a.lib' on Windows).
9585 .SS Customizing construction variables from the command line.
9587 The following would allow the C compiler to be specified on the command
9588 line or in the file custom.py.
9591 vars = Variables('custom.py')
9592 vars.Add('CC', 'The C compiler.')
9593 env = Environment(variables=vars)
9594 Help(vars.GenerateHelpText(env))
9597 The user could specify the C compiler on the command line:
9603 or in the custom.py file:
9609 or get documentation on the options:
9620 .SS Using Microsoft Visual C++ precompiled headers
9622 Since windows.h includes everything and the kitchen sink, it can take quite
9623 some time to compile it over and over again for a bunch of object files, so
9624 Microsoft provides a mechanism to compile a set of headers once and then
9625 include the previously compiled headers in any object file. This
9626 technology is called precompiled headers. The general recipe is to create a
9627 file named "StdAfx.cpp" that includes a single header named "StdAfx.h", and
9628 then include every header you want to precompile in "StdAfx.h", and finally
9629 include "StdAfx.h" as the first header in all the source files you are
9630 compiling to object files. For example:
9634 #include <windows.h>
9635 #include <my_big_header.h>
9654 /* do some other stuff */
9660 env['PCHSTOP'] = 'StdAfx.h'
9661 env['PCH'] = env.PCH('StdAfx.cpp')[0]
9662 env.Program('MyApp', ['Foo.cpp', 'Bar.cpp'])
9665 For more information see the document for the PCH builder, and the PCH and
9666 PCHSTOP construction variables. To learn about the details of precompiled
9667 headers consult the MSDN documention for /Yc, /Yu, and /Yp.
9669 .SS Using Microsoft Visual C++ external debugging information
9671 Since including debugging information in programs and shared libraries can
9672 cause their size to increase significantly, Microsoft provides a mechanism
9673 for including the debugging information in an external file called a PDB
9674 file. SCons supports PDB files through the PDB construction
9680 env['PDB'] = 'MyApp.pdb'
9681 env.Program('MyApp', ['Foo.cpp', 'Bar.cpp'])
9684 For more information see the document for the PDB construction variable.
9689 Specifies the directory that contains the SCons Python module directory
9690 (e.g. /home/aroach/scons-src-0.01/src/engine).
9693 A string of options that will be used by scons in addition to those passed
9694 on the command line.
9705 Steven Knight <knight@baldmt.com>
9707 Anthony Roach <aroach@electriceyeball.com>