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 .\" ES - Example Start - indents and turns off line fill
29 .\" EE - Example End - ends indent and turns line fill back on
34 .TH SCONS 1 "__MONTH_YEAR__"
36 scons \- a software construction tool
52 utility builds software (or other files) by determining which
53 component pieces must be rebuilt and executing the necessary commands to
58 searches for a file named
63 (in that order) in the current directory and reads its
64 configuration from the first file found.
65 An alternate file name may be
72 file can specify subsidiary
73 configuration files using the
77 these subsidiary files are named
79 although any name may be used.
80 (Because of this naming convention,
81 the term "SConscript files"
82 is sometimes used to refer
86 regardless of actual file name.)
88 The configuration files
89 specify the target files to be built, and
90 (optionally) the rules to build those targets. Reasonable default
91 rules exist for building common software components (executable
92 programs, object files, libraries), so that for most software
93 projects, only the target and input files need be specified.
99 adds looks for a dir named
101 in the dir containing the
105 to sys.path, reads the file
106 .IR site_scons/site_init.py ,
107 and adds the directory
108 .I site_scons/site_tools
109 to the default toolpath, if those exist. See the
113 options for more details.
116 reads and executes the SConscript files as Python scripts,
117 so you may use normal Python scripting capabilities
118 (such as flow control, data manipulation, and imported Python libraries)
119 to handle complicated build situations.
121 however, reads and executes all of the SConscript files
123 it begins building any targets.
124 To make this obvious,
126 prints the following messages about what it is doing:
130 scons: Reading SConscript files ...
131 scons: done reading SConscript files.
132 scons: Building targets ...
134 scons: done building targets.
139 (everything except the line that reads "cp foo.in foo.out")
140 may be suppressed using the
145 does not automatically propagate
146 the external environment used to execute
148 to the commands used to build target files.
149 This is so that builds will be guaranteed
150 repeatable regardless of the environment
151 variables set at the time
154 This also means that if the compiler or other commands
155 that you want to use to build your target files
156 are not in standard system locations,
158 will not find them unless
159 you explicitly set the PATH
160 to include those locations.
161 Whenever you create an
163 construction environment,
164 you can propagate the value of PATH
165 from your external environment as follows:
169 env = Environment(ENV = {'PATH' : os.environ['PATH']})
172 Similarly, if the commands use external environment variables
173 like $PATH, $HOME, $JAVA_HOME, $LANG, $SHELL, $TERM, etc.,
174 these variables can also be explicitly propagated:
178 env = Environment(ENV = {'PATH' : os.environ['PATH'],
179 'HOME' : os.environ['HOME']})
182 Or you may explicitly propagate the invoking user's
183 complete external environment:
187 env = Environment(ENV = os.environ)
190 This comes at the expense of making your build
191 dependent on the user's environment being set correctly,
192 but it may be more convenient for many configurations.
195 can scan known input files automatically for dependency
196 information (for example, #include statements
197 in C or C++ files) and will rebuild dependent files appropriately
198 whenever any "included" input file changes.
201 ability to define new scanners for unknown input file types.
204 knows how to fetch files automatically from
205 SCCS or RCS subdirectories
206 using SCCS, RCS or BitKeeper.
209 is normally executed in a top-level directory containing a
211 file, optionally specifying
212 as command-line arguments
213 the target file or files to be built.
215 By default, the command
221 will build all target files in or below the current directory.
222 Explicit default targets
223 (to be built when no targets are specified on the command line)
224 may be defined the SConscript file(s)
227 function, described below.
231 targets are specified in the SConscript file(s),
232 all target files in or below the current directory
233 may be built by explicitly specifying
234 the current directory (.)
235 as a command-line target:
241 Building all target files,
242 including any files outside of the current directory,
243 may be specified by supplying a command-line target
244 of the root directory (on POSIX systems):
250 or the path name(s) of the volume(s) in which all the targets
251 should be built (on Windows systems):
257 To build only specific targets,
258 supply them as command-line arguments:
264 in which case only the specified targets will be built
265 (along with any derived files on which they depend).
267 Specifying "cleanup" targets in SConscript files is not
270 flag removes all files
271 necessary to build the specified target:
277 to remove all target files, or:
280 scons -c build export
283 to remove target files under build and export.
284 Additional files or directories to remove can be specified using the
287 Conversely, targets that would normally be removed by the
290 can be prevented from being removed by using the
294 A subset of a hierarchical tree may be built by
295 remaining at the top-level directory (where the
297 file lives) and specifying the subdirectory as the target to be
304 or by changing directory and invoking scons with the
306 option, which traverses up the directory
307 hierarchy until it finds the
309 file, and then builds
310 targets relatively to the current subdirectory:
318 supports building multiple targets in parallel via a
320 option that takes, as its argument, the number
321 of simultaneous tasks that may be spawned:
327 builds four targets in parallel, for example.
330 can maintain a cache of target (derived) files that can
331 be shared between multiple builds. When caching is enabled in a
332 SConscript file, any target files built by
335 to the cache. If an up-to-date target file is found in the cache, it
336 will be retrieved from the cache instead of being rebuilt locally.
337 Caching behavior may be disabled and controlled in other ways by the
339 .BR --cache-disable ,
342 command-line options. The
344 option is useful to prevent multiple builds
345 from trying to update the cache simultaneously.
347 Values of variables to be passed to the SConscript file(s)
348 may be specified on the command line:
354 These variables are available in SConscript files
355 through the ARGUMENTS dictionary,
356 and can be used in the SConscript file(s) to modify
357 the build in any way:
360 if ARGUMENTS.get('debug', 0):
361 env = Environment(CCFLAGS = '-g')
366 The command-line variable arguments are also available
368 indexed by their order on the command line.
369 This allows you to process them in order rather than by name,
371 ARGLIST[0] returns a tuple
372 containing (argname, argvalue).
373 A Python exception is thrown if you
374 try to access a list member that
378 requires Python version 1.5.2 or later.
379 There should be no other dependencies or requirements to run
382 .\" The following paragraph reflects the default tool search orders
383 .\" currently in SCons/Tool/__init__.py. If any of those search orders
384 .\" change, this documentation should change, too.
387 knows how to search for available programming tools
391 searches in order for the
392 Microsoft Visual C++ tools,
393 the MinGW tool chain,
394 the Intel compiler tools,
395 and the PharLap ETS compiler.
398 searches in order for the
401 and the Microsoft Visual C++ tools,
402 On SGI IRIX, IBM AIX, Hewlett Packard HP-UX, and Sun Solaris systems,
404 searches for the native compiler tools
405 (MIPSpro, Visual Age, aCC, and Forte tools respectively)
406 and the GCC tool chain.
407 On all other platforms,
408 including POSIX (Linux and UNIX) platforms,
411 for the GCC tool chain,
412 the Microsoft Visual C++ tools,
413 and the Intel compiler tools.
414 You may, of course, override these default values
415 by appropriate configuration of
416 Environment construction variables.
421 supports the same command-line options as GNU
423 and many of those supported by
428 Ignored for compatibility with non-GNU versions of
432 -c, --clean, --remove
433 Clean up by removing all target files for which a construction
434 command is specified.
435 Also remove any files or directories associated to the construction command
439 Will not remove any targets specified by the
444 .RI --cache-debug= file
445 Print debug information about the
455 the debug information are printed to the standard output.
456 The printed messages describe what signature file names are
457 being looked for in, retrieved from, or written to the
462 --cache-disable, --no-cache
463 Disable the derived-file caching specified by
466 will neither retrieve files from the cache
467 nor copy files to the cache.
470 --cache-force, --cache-populate
473 populate a cache by copying any already-existing, up-to-date
474 derived files to the cache,
475 in addition to files built by this invocation.
476 This is useful to populate a new cache with
477 all the current derived files,
478 or to add to the cache any derived files
479 recently built with caching disabled via the
487 and retrieving a derived file from the cache,
489 that would have been executed to build the file,
490 instead of the usual report,
491 "Retrieved `file' from cache."
492 This will produce consistent output for build logs,
493 regardless of whether a target
494 file was rebuilt or retrieved from the cache.
498 This specifies how the
500 call should use or generate the
501 results of configuration tests.
502 The option should be specified from
503 among the following choices:
507 scons will use its normal dependency mechanisms
508 to decide if a test must be rebuilt or not.
509 This saves time by not running the same configuration tests
510 every time you invoke scons,
511 but will overlook changes in system header files
512 or external commands (such as compilers)
513 if you don't specify those dependecies explicitly.
514 This is the default behavior.
518 If this option is specified,
519 all configuration tests will be re-run
520 regardless of whether the
521 cached results are out of date.
522 This can be used to explicitly
523 force the configuration tests to be updated
524 in response to an otherwise unconfigured change
525 in a system header file or compiler.
529 If this option is specified,
530 no configuration tests will be rerun
531 and all results will be taken from cache.
532 Note that scons will still consider it an error
533 if --config=cache is specified
534 and a necessary test does not
535 yet have any results in the cache.
538 .RI "-C" " directory" ", --directory=" directory
539 Change to the specified
541 before searching for the
546 file, or doing anything
549 options are interpreted
550 relative to the previous one, and the right-most
552 option wins. (This option is nearly
554 .BR "-f directory/SConstruct" ,
555 except that it will search for
560 in the specified directory.)
564 .\" Display dependencies while building target files. Useful for
565 .\" figuring out why a specific file is being rebuilt, as well as
566 .\" general debugging of the build process.
570 Works exactly the same way as the
572 option except for the way default targets are handled.
573 When this option is used and no targets are specified on the command line,
574 all default targets are built, whether or not they are below the current
579 Debug the build process.
581 specifies what type of debugging:
585 Print how many objects are created
586 of the various classes used internally by SCons
587 before and after reading the SConscript files
588 and before and after building targets.
589 This is not supported when run under Python versions earlier than 2.1,
590 when SCons is executed with the Python
593 or when the SCons modules
594 have been compiled with optimization
595 (that is, when executing from
601 A synonym for the newer
604 This will be deprecated in some future release
605 and ultimately removed.
609 Print an explanation of precisely why
611 is deciding to (re-)build any targets.
612 (Note: this does not print anything
619 Instruct the scanner that searches for libraries
620 to print a message about each potential library
621 name it is searching for,
622 and about the actual libraries it finds.
626 Print the include tree after each top-level target is built.
627 This is generally used to find out what files are included by the sources
628 of a given derived file:
631 $ scons --debug=includes foo.o
636 Prints a summary of hits and misses using the Memoizer,
637 an internal subsystem that counts
638 how often SCons uses cached values in memory
639 instead of recomputing them each time they're needed.
640 Only available when using Python 2.2 or later.
644 Prints how much memory SCons uses
645 before and after reading the SConscript files
646 and before and after building targets.
650 A deprecated option preserved for backwards compatibility.
654 Prints a list of the various objects
655 of the various classes used internally by SCons.
656 This only works when run under Python 2.1 or later.
660 Re-run SCons under the control of the
666 Print the raw command line used to build each target
667 before the construction environment variables are substituted.
668 Also shows which targets are being built by this command.
669 Output looks something like this:
671 $ scons --debug=presub
672 Building myprog.o with action(s):
673 $SHCC $SHCFLAGS $SHCCFLAGS $CPPFLAGS $_CPPINCFLAGS -c -o $TARGET $SOURCES
679 Prints an internal Python stack trace
680 when encountering an otherwise unexplained error.
684 A synonym for the newer
687 This will be deprecated in some future release
688 and ultimately removed.
692 Prints various time profiling information:
693 the time spent executing each individual build command;
694 the total build time (time SCons ran from beginning to end);
695 the total time spent reading and executing SConscript files;
696 the total time spent SCons itself spend running
697 (that is, not counting reading and executing SConscript files);
698 and both the total time spent executing all build commands
699 and the elapsed wall-clock time spent executing those build commands.
702 is executed without the
705 the elapsed wall-clock time will typically
706 be slightly longer than the total time spent
707 executing all the build commands,
708 due to the SCons processing that takes place
709 in between executing each command.
717 and your build configuration allows good parallelization,
718 the elapsed wall-clock time should
719 be significantly smaller than the
720 total time spent executing all the build commands,
721 since multiple build commands and
722 intervening SCons processing
723 should take place in parallel.)
727 A synonym for the newer
730 This will be deprecated in some future release
731 and ultimately removed.
734 .RI --diskcheck= types
735 Enable specific checks for
736 whether or not there is a file on disk
737 where the SCons configuration expects a directory
739 and whether or not RCS or SCCS sources exist
740 when searching for source and include files.
743 argument can be set to:
745 to enable all checks explicitly
746 (the default behavior);
748 to disable all such checks;
750 to check that files and directories on disk
751 match SCons' expected configuration;
753 to check for the existence of an RCS source
754 for any missing source or include files;
756 to check for the existence of an SCCS source
757 for any missing source or include files.
758 Multiple checks can be specified separated by commas;
760 .B --diskcheck=sccs,rcs
761 would still check for SCCS and RCS sources,
762 but disable the check for on-disk matches of files and directories.
763 Disabling some or all of these checks
764 can provide a performance boost for large configurations,
765 or when the configuration will check for files and/or directories
766 across networked or shared file systems,
767 at the slight increased risk of an incorrect build
768 or of not handling errors gracefully
769 (if include files really should be
770 found in SCCS or RCS, for example,
771 or if a file really does exist
772 where the SCons configuration expects a directory).
775 .RI --duplicate= ORDER
776 There are three ways to duplicate files in a build tree: hard links,
777 soft (symbolic) links and copies. The default behaviour of SCons is to
778 prefer hard links to soft links to copies. You can specify different
779 behaviours with this option.
789 SCons will attempt to duplicate files using
790 the mechanisms in the specified order.
793 .\" -e, --environment-overrides
794 .\" Variables from the execution environment override construction
795 .\" variables from the SConscript files.
798 .RI -f " file" ", --file=" file ", --makefile=" file ", --sconstruct=" file
801 as the initial SConscript file.
805 Print a local help message for this build, if one is defined in
806 the SConscript file(s), plus a line that describes the
808 option for command-line option help. If no local help message
809 is defined, prints the standard help message about command-line
810 options. Exits after displaying the appropriate message.
814 Print the standard help message about command-line options and
819 Ignore all errors from commands executed to rebuild files.
822 .RI -I " directory" ", --include-dir=" directory
826 imported Python modules. If several
829 are used, the directories are searched in the order specified.
833 Cache implicit dependencies.
836 to use the implicit (scanned) dependencies
837 from the last time it was run
838 instead of scanning the files for implicit dependencies.
839 This can significantly speed up SCons,
840 but with the following limitations:
843 will not detect changes to implicit dependency search paths
845 .BR CPPPATH ", " LIBPATH )
846 that would ordinarily
847 cause different versions of same-named files to be used.
850 will miss changes in the implicit dependencies
851 in cases where a new implicit
852 dependency is added earlier in the implicit dependency search path
854 .BR CPPPATH ", " LIBPATH )
855 than a current implicit dependency with the same name.
858 --implicit-deps-changed
859 Forces SCons to ignore the cached implicit dependencies. This causes the
860 implicit dependencies to be rescanned and recached. This implies
861 .BR --implicit-cache .
864 --implicit-deps-unchanged
865 Force SCons to ignore changes in the implicit dependencies.
866 This causes cached implicit dependencies to always be used.
868 .BR --implicit-cache .
871 .RI -j " N" ", --jobs=" N
872 Specifies the number of jobs (commands) to run simultaneously.
873 If there is more than one
875 option, the last one is effective.
879 .\" is specified without an argument,
881 .\" will not limit the number of
882 .\" simultaneous jobs.
886 Continue as much as possible after an error. The target that
887 failed and those that depend on it will not be remade, but other
888 targets specified on the command line will still be processed.
891 .\" .RI -l " N" ", --load-average=" N ", --max-load=" N
892 .\" No new jobs (commands) will be started if
893 .\" there are other jobs running and the system load
894 .\" average is at least
896 .\" (a floating-point number).
901 .\" List derived files (targets, dependencies) that would be built,
902 .\" but do not build them.
903 .\" [XXX This can probably go away with the right
904 .\" combination of other options. Revisit this issue.]
908 .\" List derived files that would be built, with the actions
909 .\" (commands) that build them. Does not build the files.
910 .\" [XXX This can probably go away with the right
911 .\" combination of other options. Revisit this issue.]
915 .\" List derived files that would be built, plus where the file is
916 .\" defined (file name and line number). Does not build the files.
917 .\" [XXX This can probably go away with the right
918 .\" combination of other options. Revisit this issue.]
922 Ignored for compatibility with non-GNU versions of
926 .RI --max-drift= SECONDS
927 Set the maximum expected drift in the modification time of files to
929 This value determines how long a file must be unmodified
930 before its cached content signature
931 will be used instead of
932 calculating a new content signature (MD5 checksum)
933 of the file's contents.
934 The default value is 2 days, which means a file must have a
935 modification time of at least two days ago in order to have its
936 cached content signature used.
937 A negative value means to never cache the content
938 signature and to ignore the cached value if there already is one. A value
939 of 0 means to always use the cached signature,
940 no matter how old the file is.
943 -n, --just-print, --dry-run, --recon
944 No execute. Print the commands that would be executed to build
945 any out-of-date target files, but do not execute the commands.
949 Prevents the automatic addition of the standard
953 Also prevents loading the
954 .I site_scons/site_init.py
955 module if it exists, and prevents adding
956 .I site_scons/site_tools
960 .\" .RI -o " file" ", --old-file=" file ", --assume-old=" file
964 .\" not rebuild anything due to changes in the contents of
967 .\" .RI --override " file"
968 .\" Read values to override specific build environment variables
969 .\" from the specified
973 .\" Print the data base (construction environments,
974 .\" Builder and Scanner objects) that are defined
975 .\" after reading the SConscript files.
976 .\" After printing, a normal build is performed
977 .\" as usual, as specified by other command-line options.
978 .\" This also prints version information
983 .\" To print the database without performing a build do:
991 Run SCons under the Python profiler
992 and save the results in the specified
994 The results may be analyzed using the Python
999 Do not run any commands, or print anything. Just return an exit
1000 status that is zero if the specified targets are already up to
1001 date, non-zero otherwise.
1004 Quiets SCons status messages about
1005 reading SConscript files,
1007 and entering directories.
1008 Commands that are executed
1009 to rebuild target files are still printed.
1012 .\" -r, -R, --no-builtin-rules, --no-builtin-variables
1013 .\" Clear the default construction variables. Construction
1014 .\" environments that are created will be completely empty.
1018 Build dependencies in a random order. This is useful when
1019 building multiple trees simultaneously with caching enabled,
1020 to prevent multiple builds from simultaneously trying to build
1021 or retrieve the same target files.
1024 -s, --silent, --quiet
1025 Silent. Do not print commands that are executed to rebuild
1027 Also suppresses SCons status messages.
1030 -S, --no-keep-going, --stop
1031 Ignored for compatibility with GNU
1036 Uses the named dir as the site dir rather than the default
1038 dir. This dir will get prepended to
1041 .IR dir /site_init.py
1042 will get loaded if it exists, and
1044 will get added to the default toolpath.
1048 Ignored for compatibility with GNU
1050 (Touching a file to make it
1051 appear up-to-date is unnecessary when using
1055 .RI --taskmastertrace= file
1056 Prints trace information to the specified
1058 about how the internal Taskmaster object
1059 evaluates and controls the order in which Nodes are built.
1062 may be used to specify the standard output.
1066 Prints a tree of the dependencies
1067 after each top-level target is built.
1068 This prints out some or all of the tree,
1076 Print the entire dependency tree
1077 after each top-level target is built.
1078 This prints out the complete dependency tree,
1079 including implicit dependencies and ignored dependencies.
1083 Restricts the tree output to only derived (target) files,
1088 Prints status information for each displayed node.
1092 Prunes the tree to avoid repeating dependency information
1093 for nodes that have already been displayed.
1094 Any node that has already been displayed
1095 will have its name printed in
1096 .BR "[square brackets]" ,
1097 as an indication that the dependencies
1098 for that node can be found by searching
1099 for the relevant output higher up in the tree.
1102 Multiple options may be specified,
1103 separated by commas:
1106 # Prints only derived files, with status information:
1107 scons --tree=derived,status
1109 # Prints all dependencies of target, with status information
1110 # and pruning dependencies of already-visited Nodes:
1111 scons --tree=all,prune,status target
1115 -u, --up, --search-up
1116 Walks up the directory structure until an
1121 file is found, and uses that
1122 as the top of the directory tree.
1123 If no targets are specified on the command line,
1124 only targets at or below the
1125 current directory will be built.
1129 Works exactly the same way as the
1131 option except for the way default targets are handled.
1132 When this option is used and no targets are specified on the command line,
1133 all default targets that are defined in the SConscript(s) in the current
1134 directory are built, regardless of what directory the resultant targets end
1141 version, copyright information,
1142 list of authors, and any other relevant information.
1146 -w, --print-directory
1147 Print a message containing the working directory before and
1148 after other processing.
1151 --no-print-directory
1152 Turn off -w, even if it was turned on implicitly.
1155 .RI --warn= type ", --warn=no-" type
1156 Enable or disable warnings.
1158 specifies the type of warnings to be enabled or disabled:
1161 --warn=all, --warn=no-all
1162 Enables or disables all warnings.
1165 --warn=cache-write-error, --warn=no-cache-write-error
1166 Enables or disables warnings about errors trying to
1167 write a copy of a built file to a specified
1169 These warnings are disabled by default.
1172 --warn=corrupt-sconsign, --warn=no-corrupt-sconsign
1173 Enables or disables warnings about unfamiliar signature data in
1176 These warnings are enabled by default.
1179 --warn=dependency, --warn=no-dependency
1180 Enables or disables warnings about dependencies.
1181 These warnings are disabled by default.
1184 --warn=deprecated, --warn=no-deprecated
1185 Enables or disables warnings about use of deprecated features.
1186 These warnings are enabled by default.
1189 --warn=duplicate-environment, --warn=no-duplicate-environment
1190 Enables or disables warnings about missing SConscript files.
1193 --warn=misleading-keywords, --warn=no-misleading-keywords
1194 Enables or disables warnings about use of the misspelled keywords
1198 when calling Builders.
1201 characters, the correct spellings are
1205 These warnings are enabled by default.
1208 --warn=missing-sconscript, --warn=no-missing-sconscript
1209 Enables or disables warnings about attempts to specify a build
1210 of a target with two different construction environments
1211 that use the same action.
1212 These warnings are enabled by default.
1215 --warn=no-md5-module, --warn=no-no-md5-module
1216 Enables or disables warnings about the version of Python
1217 not having an MD5 checksum module available.
1218 These warnings are enabled by default.
1221 --warn=no-metaclass-support, --warn=no-no-metaclass-support
1222 Enables or disables warnings about the version of Python
1223 not supporting metaclasses when the
1226 These warnings are enabled by default.
1229 --warn=no-parallel-support, --warn=no-no-parallel-support
1230 Enables or disables warnings about the version of Python
1231 not being able to support parallel builds when the
1234 These warnings are enabled by default.
1237 --warn=reserved-variable, --warn=no-reserved-variable
1238 Enables or disables warnings about attempts to set the
1239 reserved construction variable names
1245 These warnings are disabled by default.
1248 .\" .RI --write-filenames= file
1249 .\" Write all filenames considered into
1253 .\" .RI -W " file" ", --what-if=" file ", --new-file=" file ", --assume-new=" file
1254 .\" Pretend that the target
1257 .\" modified. When used with the
1260 .\" show you what would be rebuilt if you were to modify that file.
1266 .\" --warn-undefined-variables
1267 .\" Warn when an undefined variable is referenced.
1270 .RI -Y " repository" ", --repository=" repository ", --srcdir=" repository
1271 Search the specified repository for any input and target
1272 files not found in the local directory hierarchy. Multiple
1274 options may specified, in which case the
1275 repositories are searched in the order specified.
1277 .SH CONFIGURATION FILE REFERENCE
1278 .\" .SS Python Basics
1279 .\" XXX Adding this in the future would be a help.
1280 .SS Construction Environments
1281 A construction environment is the basic means by which the SConscript
1282 files communicate build information to
1284 A new construction environment is created using the
1292 By default, a new construction environment is
1293 initialized with a set of builder methods
1294 and construction variables that are appropriate
1295 for the current platform.
1296 An optional platform keyword argument may be
1297 used to specify that an environment should
1298 be initialized for a different platform:
1301 env = Environment(platform = 'cygwin')
1302 env = Environment(platform = 'os2')
1303 env = Environment(platform = 'posix')
1304 env = Environment(platform = 'win32')
1307 Specifying a platform initializes the appropriate
1308 construction variables in the environment
1309 to use and generate file names with prefixes
1310 and suffixes appropriate for the platform.
1318 variables from the user's external environment
1319 to the construction environment's
1322 This is so that any executed commands
1323 that use sockets to connect with other systems
1324 (such as fetching source files from
1325 external CVS repository specifications like
1326 .BR :pserver:anonymous@cvs.sourceforge.net:/cvsroot/scons )
1327 will work on Windows systems.
1329 The platform argument may be function or callable object,
1330 in which case the Environment() method
1331 will call the specified argument to update
1332 the new construction environment:
1335 def my_platform(env):
1336 env['VAR'] = 'xyzzy'
1338 env = Environment(platform = my_platform)
1341 Additionally, a specific set of tools
1342 with which to initialize the environment
1343 may specified as an optional keyword argument:
1346 env = Environment(tools = ['msvc', 'lex'])
1349 Non-built-in tools may be specified using the toolpath argument:
1352 env = Environment(tools = ['default', 'foo'], toolpath = ['tools'])
1355 This looks for a tool specification in tools/foo.py (as well as
1356 using the ordinary default tools for the platform). foo.py should
1357 have two functions: generate(env, **kw) and exists(env).
1361 modifies the passed-in environment
1362 to set up variables so that the tool
1364 it may use any keyword arguments
1365 that the user supplies (see below)
1366 to vary its initialization.
1369 function should return a true
1370 value if the tool is available.
1371 Tools in the toolpath are used before
1372 any of the built-in ones. For example, adding gcc.py to the toolpath
1373 would override the built-in gcc tool.
1374 Also note that the toolpath is
1375 stored in the environment for use
1383 base = Environment(toolpath=['custom_path'])
1384 derived = base.Clone(tools=['custom_tool'])
1385 derived.CustomBuilder()
1388 The elements of the tools list may also
1389 be functions or callable objects,
1390 in which case the Environment() method
1391 will call the specified elements
1392 to update the new construction environment:
1396 env['XYZZY'] = 'xyzzy'
1398 env = Environment(tools = [my_tool])
1401 The individual elements of the tools list
1402 may also themselves be two-element lists of the form
1403 .RI ( toolname ", " kw_dict ).
1404 SCons searches for the
1406 specification file as described above, and
1409 which must be a dictionary, as keyword arguments to the tool's
1414 function can use the arguments to modify the tool's behavior
1415 by setting up the environment in different ways
1416 or otherwise changing its initialization.
1419 # in tools/my_tool.py:
1420 def generate(env, **kw):
1421 # Sets MY_TOOL to the value of keyword argument 'arg1' or 1.
1422 env['MY_TOOL'] = kw.get('arg1', '1')
1427 env = Environment(tools = ['default', ('my_tool', {'arg1': 'abc'})],
1431 The tool definition (i.e. my_tool()) can use the PLATFORM variable from
1432 the environment it receives to customize the tool for different platforms.
1434 If no tool list is specified, then SCons will auto-detect the installed
1435 tools using the PATH variable in the ENV construction variable and the
1436 platform name when the Environment is constructed. Changing the PATH
1437 variable after the Environment is constructed will not cause the tools to
1440 SCons supports the following tool specifications out of the box:
1516 Additionally, there is a "tool" named
1518 which configures the
1519 environment with a default set of tools for the current platform.
1521 On posix and cygwin platforms
1522 the GNU tools (e.g. gcc) are preferred by SCons,
1523 on Windows the Microsoft tools (e.g. msvc)
1524 followed by MinGW are preferred by SCons,
1525 and in OS/2 the IBM tools (e.g. icc) are preferred by SCons.
1529 Build rules are specified by calling a construction
1530 environment's builder methods.
1531 The arguments to the builder methods are
1533 (a list of target files)
1536 (a list of source files).
1538 Because long lists of file names
1539 can lead to a lot of quoting,
1544 and a same-named environment method
1545 that split a single string
1546 into a list, separated on
1547 strings of white-space characters.
1548 (These are similar to the
1549 string.split() method
1550 from the standard Python library,
1551 but work even if the input isn't a string.)
1553 Like all Python arguments,
1554 the target and source arguments to a builder method
1555 can be specified either with or without
1556 the "target" and "source" keywords.
1557 When the keywords are omitted,
1558 the target is first,
1559 followed by the source.
1560 The following are equivalent examples of calling the Program builder method:
1563 env.Program('bar', ['bar.c', 'foo.c'])
1564 env.Program('bar', Split('bar.c foo.c'))
1565 env.Program('bar', env.Split('bar.c foo.c'))
1566 env.Program(source = ['bar.c', 'foo.c'], target = 'bar')
1567 env.Program(target = 'bar', Split('bar.c foo.c'))
1568 env.Program(target = 'bar', env.Split('bar.c foo.c'))
1569 env.Program('bar', source = string.split('bar.c foo.c'))
1572 When the target shares the same base name
1573 as the source and only the suffix varies,
1574 and if the builder method has a suffix defined for the target file type,
1575 then the target argument may be omitted completely,
1578 will deduce the target file name from
1579 the source file name.
1580 The following examples all build the
1586 (on Windows systems)
1587 from the bar.c source file:
1590 env.Program(target = 'bar', source = 'bar.c')
1591 env.Program('bar', source = 'bar.c')
1592 env.Program(source = 'bar.c')
1593 env.Program('bar.c')
1598 keyword argument may be specified
1599 when calling a Builder.
1601 all source file strings that are not absolute paths
1602 will be interpreted relative to the specified
1604 The following example will build the
1609 program from the files
1615 env.Program('build/prog', ['f1.c', 'f2.c'], srcdir='src')
1618 It is possible to override or add construction variables when calling a
1619 builder method by passing additional keyword arguments.
1620 These overridden or added
1621 variables will only be in effect when building the target, so they will not
1622 affect other parts of the build. For example, if you want to add additional
1623 libraries for just one program:
1626 env.Program('hello', 'hello.c', LIBS=['gl', 'glut'])
1629 or generate a shared library with a non-standard suffix:
1632 env.SharedLibrary('word', 'word.cpp',
1634 LIBSUFFIXES=['.ocx'])
1637 (Note that both the $SHLIBSUFFIX and $LIBSUFFIXES variables must be set
1638 if you want SCons to search automatically
1639 for dependencies on the non-standard library names;
1640 see the descriptions of these variables, below, for more information.)
1642 Although the builder methods defined by
1645 methods of a construction environment object,
1646 they may also be called without an explicit environment:
1649 Program('hello', 'hello.c')
1650 SharedLibrary('word', 'word.cpp')
1654 the methods are called internally using a default construction
1655 environment that consists of the tools and values that
1657 has determined are appropriate for the local system.
1659 Builder methods that can be called without an explicit
1660 environment may be called from custom Python modules that you
1661 import into an SConscript file by adding the following
1662 to the Python module:
1665 from SCons.Script import *
1668 All builder methods return a list of Nodes
1669 that represent the target or targets that will be built.
1672 is an internal SCons object
1674 build targets or sources.
1676 The returned Node(s)
1677 can be passed to other builder methods as source(s)
1678 or passed to any SCons function or method
1679 where a filename would normally be accepted.
1680 For example, if it were necessary
1683 flag when compiling one specific object file:
1686 bar_obj_list = env.StaticObject('bar.c', CPPDEFINES='-DBAR')
1687 env.Program(source = ['foo.c', bar_obj_list, 'main.c'])
1690 Using a Node in this way
1691 makes for a more portable build
1692 by avoiding having to specify
1693 a platform-specific object suffix
1694 when calling the Program() builder method.
1696 Note that Builder calls will automatically "flatten"
1697 the source and target file lists,
1698 so it's all right to have the bar_obj list
1699 return by the StaticObject() call
1700 in the middle of the source file list.
1701 If you need to manipulate a list of lists returned by Builders
1702 directly using Python,
1703 you can either build the list by hand:
1706 foo = Object('foo.c')
1707 bar = Object('bar.c')
1708 objects = ['begin.o'] + foo + ['middle.o'] + bar + ['end.o']
1709 for object in objects:
1716 to create a list containing just the Nodes,
1717 which may be more convenient:
1720 foo = Object('foo.c')
1721 bar = Object('bar.c')
1722 objects = Flatten(['begin.o', foo, 'middle.o', bar, 'end.o'])
1723 for object in objects:
1727 The path name for a Node's file may be used
1728 by passing the Node to the Python-builtin
1733 bar_obj_list = env.StaticObject('bar.c', CPPDEFINES='-DBAR')
1734 print "The path to bar_obj is:", str(bar_obj_list[0])
1737 Note again that because the Builder call returns a list,
1738 we have to access the first element in the list
1739 .B (bar_obj_list[0])
1740 to get at the Node that actually represents
1743 Builder calls support a
1745 keyword argument that
1746 specifies that the Builder's action(s)
1748 after changing directory.
1752 a string or a directory Node,
1753 scons will change to the specified directory.
1756 is not a string or Node
1758 then scons will change to the
1759 target file's directory.
1762 # scons will change to the "sub" subdirectory
1763 # before executing the "cp" command.
1764 env.Command('sub/dir/foo.out', 'sub/dir/foo.in',
1765 "cp dir/foo.in dir/foo.out",
1768 # Because chdir is not a string, scons will change to the
1769 # target's directory ("sub/dir") before executing the
1771 env.Command('sub/dir/foo.out', 'sub/dir/foo.in',
1772 "cp foo.in foo.out",
1776 Note that scons will
1778 automatically modify
1780 construction variables like
1784 when using the chdir
1785 keyword argument--that is,
1786 the expanded file names
1787 will still be relative to
1788 the top-level SConstruct directory,
1789 and consequently incorrect
1790 relative to the chdir directory.
1791 If you use the chdir keyword argument,
1792 you will typically need to supply a different
1798 to use just the filename portion of the
1802 provides the following builder methods:
1804 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1805 '\" BEGIN GENERATED BUILDER DESCRIPTIONS
1807 '\" The descriptions below of the various SCons Builders are generated
1808 '\" from the .xml files that live next to the various Python modules in
1809 '\" the build enginer library. If you're reading this [gnt]roff file
1810 '\" with an eye towards patching this man page, you can still submit
1811 '\" a diff against this text, but it will have to be translated to a
1812 '\" diff against the underlying .xml file before the patch is actually
1813 '\" accepted. If you do that yourself, it will make it easier to
1814 '\" integrate the patch.
1816 '\" BEGIN GENERATED BUILDER DESCRIPTIONS
1817 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1819 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1820 '\" END GENERATED BUILDER DESCRIPTIONS
1822 '\" The descriptions above of the various SCons Builders are generated
1823 '\" from the .xml files that live next to the various Python modules in
1824 '\" the build enginer library. If you're reading this [gnt]roff file
1825 '\" with an eye towards patching this man page, you can still submit
1826 '\" a diff against this text, but it will have to be translated to a
1827 '\" diff against the underlying .xml file before the patch is actually
1828 '\" accepted. If you do that yourself, it will make it easier to
1829 '\" integrate the patch.
1831 '\" END GENERATED BUILDER DESCRIPTIONS
1832 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1835 targets of builder methods automatically depend on their sources.
1836 An explicit dependency can
1837 be specified using the
1839 method of a construction environment (see below).
1844 source files for various programming languages,
1845 so the dependencies do not need to be specified explicitly.
1846 By default, SCons can
1849 Fortran source files with
1851 (POSIX systems only),
1856 and assembly language files with
1858 (POSIX systems only),
1863 for C preprocessor dependencies.
1864 SCons also has default support
1865 for scanning D source files,
1866 You can also write your own Scanners
1867 to add support for additional source file types.
1868 These can be added to the default
1869 Scanner object used by
1875 Builders by adding them
1877 .B SourceFileScanner
1880 See the section "Scanner Objects,"
1881 below, for a more information about
1882 defining your own Scanner objects.
1884 .SS Methods and Functions to Do Things
1885 In addition to Builder methods,
1887 provides a number of other construction environment methods
1888 and global functions to
1889 manipulate the build configuration.
1891 Usually, a construction environment method
1892 and global function with the same name both exist
1893 so that you don't have to remember whether
1894 to a specific bit of functionality
1895 must be called with or without a construction environment.
1896 In the following list,
1897 if you call something as a global function
1900 .RI Function( arguments )
1902 and if you call something through a construction
1903 environment it looks like:
1905 .RI env.Function( arguments )
1907 If you can call the functionality in both ways,
1908 then both forms are listed.
1910 Global functions may be called from custom Python modules that you
1911 import into an SConscript file by adding the following
1912 to the Python module:
1915 from SCons.Script import *
1918 Except where otherwise noted,
1920 construction environment method
1922 provide the exact same functionality.
1923 The only difference is that,
1925 calling the functionality through a construction environment will
1926 substitute construction variables into
1927 any supplied strings.
1930 env = Environment(FOO = 'foo')
1934 the first call to the global
1936 function will actually add a target named
1938 to the list of default targets,
1939 while the second call to the
1941 construction environment method
1942 will expand the value
1943 and add a target named
1945 to the list of default targets.
1946 For more on construction variable expansion,
1947 see the next section on
1948 construction variables.
1950 Construction environment methods
1951 and global functions supported by
1955 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1957 .RI Action( action ", [" strfunction ", " varlist ])
1959 .RI env.Action( action ", [" strfunction ", " varlist ])
1960 Creates an Action object for
1963 See the section "Action Objects,"
1964 below, for a complete explanation of the arguments and behavior.
1968 form of the invocation will expand
1969 construction variables in any arguments strings,
1973 at the time it is called
1974 using the construction variables in the
1976 construction environment through which
1981 form delays all variable expansion
1982 until the Action object is actually used.
1984 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1986 .RI AddMethod( object, function ", [" name ])
1988 .RI env.AddMethod( function ", [" name ])
1989 When called with the
1996 as the specified method
1998 When called with the
1999 .BR env.AddMethod ()
2003 to the construction environment
2005 as the specified method
2014 itself is used for the method name.
2019 # Note that the first argument to the function to
2020 # be attached as a method must be the object through
2021 # which the method will be called; the Python
2022 # convention is to call it 'self'.
2023 def my_method(self, arg):
2024 print "my_method() got", arg
2026 # Use the global AddMethod() function to add a method
2027 # to the Environment class. This
2028 AddMethod(Environment, my_method)
2030 env.my_method('arg')
2032 # Add the function as a method, using the function
2033 # name for the method call.
2035 env.AddMethod(my_method, 'other_method_name')
2036 env.other_method_name('another arg')
2039 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2041 .RI AddOption( arguments )
2042 This function adds a new command-line option to be recognized.
2045 are the same as supported by the standard Python
2046 .BR optparse.add_option ()
2047 method (with a few additional capabilities noted below);
2048 see the documentation for
2050 for a thorough discussion of its option-processing capabities.
2051 (Note that although the
2053 module was not a standard module until Python 2.3,
2055 contains a compatible version of the module
2056 that is used to provide identical functionality
2057 when run by earlier Python versions.)
2059 In addition to the arguments and values supported by the
2060 .B optparse.add_option ()
2064 function allows you to set the
2068 (a string with just the question mark)
2069 to indicate that the specified long option(s) take(s) an
2079 may be used to supply the "default"
2080 value that should be used when the
2081 option is specified on the command line
2082 without an explicit argument.
2086 keyword argument is supplied when calling
2088 the option will have a default value of
2091 Once a new command-line option has been added with
2093 the option value may be accessed using
2096 .BR env.GetOption ().
2097 The value may also be set, using
2100 .BR env.SetOption (),
2103 require overriding any default value.
2104 Note, however, that a
2105 value specified on the command line will
2107 override a value set by any SConscript file.
2111 strings for the new option(s)
2112 will be displayed by the
2117 (the latter only if no other help text is
2118 specified in the SConscript files).
2119 The help text for the local options specified by
2121 will appear below the SCons options themselves,
2125 The options will appear in the help text
2126 in the order in which the
2133 AddOption('--prefix',
2135 nargs=1, type='string',
2138 help='installation prefix')
2139 env = Environment(PREFIX = GetOption('prefix'))
2142 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2144 .RI AddPostAction( target ", " action )
2146 .RI env.AddPostAction( target ", " action )
2147 Arranges for the specified
2153 The specified action(s) may be
2154 an Action object, or anything that
2155 can be converted into an Action object
2158 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2160 .RI AddPreAction( target ", " action )
2162 .RI env.AddPreAction( target ", " action )
2163 Arranges for the specified
2166 before the specified
2169 The specified action(s) may be
2170 an Action object, or anything that
2171 can be converted into an Action object
2174 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2176 .RI Alias( alias ", [" targets ", [" action ]])
2178 .RI env.Alias( alias ", [" targets ", [" action ]])
2179 Creates one or more phony targets that
2180 expand to one or more other targets.
2185 can be specified that will be executed
2186 whenever the any of the alias targets are out-of-date.
2187 Returns the Node object representing the alias,
2188 which exists outside of any file system.
2189 This Node object, or the alias name,
2190 may be used as a dependency of any other target,
2191 including another alias.
2193 can be called multiple times for the same
2194 alias to add additional targets to the alias,
2195 or additional actions to the list for this alias.
2201 Alias('install', '/usr/bin')
2202 Alias(['install', 'install-lib'], '/usr/local/lib')
2204 env.Alias('install', ['/usr/local/bin', '/usr/local/lib'])
2205 env.Alias('install', ['/usr/local/man'])
2207 env.Alias('update', ['file1', 'file2'], "update_database $SOURCES")
2210 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2212 .RI AllowSubstExceptions([ exception ", ...])"
2213 Specifies the exceptions that will be allowed
2214 when expanding construction variables.
2216 any construction variable expansions that generate a
2220 exception will expand to a
2222 (a null string) and not cause scons to fail.
2223 All exceptions not in the specified list
2224 will generate an error message
2225 and terminate processing.
2228 .B AllowSubstExceptions
2229 is called multiple times,
2230 each call completely overwrites the previous list
2231 of allowed exceptions.
2236 # Requires that all construction variable names exist.
2237 # (You may wish to do this if you want to enforce strictly
2238 # that all construction variables must be defined before use.)
2239 AllowSubstExceptions()
2241 # Also allow a string containing a zero-division expansion
2242 # like '${1 / 0}' to evalute to ''.
2243 AllowSubstExceptions(IndexError, NameError, ZeroDivisionError)
2246 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2248 .RI AlwaysBuild( target ", ...)"
2250 .RI env.AlwaysBuild( target ", ...)"
2253 so that it is always assumed to be out of date,
2254 and will always be rebuilt if needed.
2257 does not add its target(s) to the default target list,
2258 so the targets will only be built
2259 if they are specified on the command line,
2260 or are a dependent of a target specified on the command line--but
2263 be built if so specified.
2264 Multiple targets can be passed in to a single call to
2267 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2269 .RI env.Append( key = val ", [...])"
2270 Appends the specified keyword arguments
2271 to the end of construction variables in the environment.
2272 If the Environment does not have
2273 the specified construction variable,
2274 it is simply added to the environment.
2275 If the values of the construction variable
2276 and the keyword argument are the same type,
2277 then the two values will be simply added together.
2278 Otherwise, the construction variable
2279 and the value of the keyword argument
2280 are both coerced to lists,
2281 and the lists are added together.
2282 (See also the Prepend method, below.)
2287 env.Append(CCFLAGS = ' -g', FOO = ['foo.yyy'])
2290 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2292 .RI env.AppendENVPath( name ", " newpath ", [" envname ", " sep ])
2293 This appends new path elements to the given path in the
2294 specified external environment
2298 any particular path once (leaving the last one it encounters and
2299 ignoring the rest, to preserve path order),
2300 and to help assure this,
2301 will normalize all paths (using
2304 .BR os.path.normcase ).
2305 This can also handle the
2306 case where the given old path variable is a list instead of a
2307 string, in which case a list will be returned instead of a string.
2312 print 'before:',env['ENV']['INCLUDE']
2313 include_path = '/foo/bar:/foo'
2314 env.AppendENVPath('INCLUDE', include_path)
2315 print 'after:',env['ENV']['INCLUDE']
2319 after: /biz:/foo/bar:/foo
2322 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2324 .RI env.AppendUnique( key = val ", [...])"
2325 Appends the specified keyword arguments
2326 to the end of construction variables in the environment.
2327 If the Environment does not have
2328 the specified construction variable,
2329 it is simply added to the environment.
2330 If the construction variable being appended to is a list,
2331 then any value(s) that already exist in the
2332 construction variable will
2334 be added again to the list.
2339 env.AppendUnique(CCFLAGS = '-g', FOO = ['foo.yyy'])
2342 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2345 A factory function that
2346 returns a Builder object
2347 to be used to fetch source files
2349 The returned Builder
2350 is intended to be passed to the
2357 env.SourceCode('.', env.BitKeeper())
2360 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2362 .RI BuildDir( build_dir ", " src_dir ", [" duplicate ])
2364 .RI env.BuildDir( build_dir ", " src_dir ", [" duplicate ])
2365 This specifies a build directory
2367 in which to build all derived files
2368 that would normally be built under
2370 Multiple build directories can be set up for multiple build variants, for
2373 must be underneath the SConstruct file's directory,
2376 may not be underneath the
2379 The default behavior is for
2381 to duplicate all of the files in the tree underneath
2385 and then build the derived files within the copied tree.
2386 (The duplication is performed by
2388 depending on the platform; see also the
2391 This guarantees correct builds
2392 regardless of whether intermediate source files
2393 are generated during the build,
2394 where preprocessors or other scanners search
2396 or whether individual compilers or other invoked tools
2397 are hard-coded to put derived files in the same directory as source files.
2399 This behavior of making a complete copy of the source tree
2400 may be disabled by setting
2405 to invoke Builders using the
2406 path names of source files in
2408 and the path names of derived files within
2410 This is always more efficient than
2412 and is usually safe for most builds.
2416 may cause build problems
2417 if source files are generated during the build,
2418 if any invoked tools are hard-coded to
2419 put derived files in the same directory as the source files.
2421 Note that specifying a
2423 works most naturally
2424 with a subsidiary SConscript file
2425 in the source directory.
2427 you would then call the subsidiary SConscript file
2428 not in the source directory,
2433 had made a virtual copy of the source tree
2434 regardless of the value of
2436 This is how you tell
2438 which variant of a source tree to build.
2442 BuildDir('build-variant1', 'src')
2443 SConscript('build-variant1/SConscript')
2444 BuildDir('build-variant2', 'src')
2445 SConscript('build-variant2/SConscript')
2451 function, described below,
2453 specify a build directory
2454 in conjunction with calling a subsidiary
2457 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2459 .RI Builder( action ", [" arguments ])
2461 .RI env.Builder( action ", [" arguments ])
2462 Creates a Builder object for
2465 See the section "Builder Objects,"
2466 below, for a complete explanation of the arguments and behavior.
2470 form of the invocation will expand
2471 construction variables in any arguments strings,
2475 at the time it is called
2476 using the construction variables in the
2478 construction environment through which
2483 form delays all variable expansion
2484 until after the Builder object is actually called.
2486 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2488 .RI CacheDir( cache_dir )
2490 .RI env.CacheDir( cache_dir )
2493 will maintain a cache of derived files in
2495 The derived files in the cache will be shared
2496 among all the builds using the same
2503 disables derived file caching.
2507 will only affect targets built
2508 through the specified construction environment.
2511 sets a global default
2512 that will be used by all targets built
2513 through construction environments
2524 finds a derived file that needs to be rebuilt,
2525 it will first look in the cache to see if a
2526 derived file has already been built
2527 from identical input files and an identical build action
2528 (as incorporated into the MD5 build signature).
2531 will retrieve the file from the cache.
2532 If the derived file is not present in the cache,
2535 then place a copy of the built file in the cache
2536 (identified by its MD5 build signature),
2537 so that it may be retrieved by other
2538 builds that need to build the same derived file
2539 from identical inputs.
2543 may be disabled for any invocation
2552 will place a copy of
2554 derived files in the cache,
2555 even if they already existed
2556 and were not built by this invocation.
2557 This is useful to populate a cache
2560 is added to a build,
2569 "Retrieved `file' from cache,"
2572 option is being used.
2577 will print the action that
2579 have been used to build the file,
2580 without any indication that
2581 the file was actually retrieved from the cache.
2582 This is useful to generate build logs
2583 that are equivalent regardless of whether
2584 a given derived file has been built in-place
2585 or retrieved from the cache.
2589 method can be used to disable caching of specific files. This can be
2590 useful if inputs and/or outputs of some tool are impossible to
2591 predict or prohibitively large.
2593 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2595 .RI Clean( targets ", " files_or_dirs )
2597 .RI env.Clean( targets ", " files_or_dirs )
2598 This specifies a list of files or directories which should be removed
2599 whenever the targets are specified with the
2601 command line option.
2602 The specified targets may be a list
2603 or an individual target.
2607 and create new targets or add files and directories to the
2608 clean list for the specified targets.
2610 Multiple files or directories should be specified
2611 either as separate arguments to the
2613 method, or as a list.
2615 will also accept the return value of any of the construction environment
2621 function overrides calling
2623 for the same target,
2624 and any targets passed to both functions will
2633 Clean('foo', ['bar', 'baz'])
2634 Clean('dist', env.Program('hello', 'hello.c'))
2635 Clean(['foo', 'bar'], 'something_else_to_clean')
2638 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2640 .RI Command( target ", " source ", " action ", [" key = val ", ...])"
2642 .RI env.Command( target ", " source ", " action ", [" key = val ", ...])"
2643 Executes a specific action
2644 (or list of actions)
2645 to build a target file or files.
2646 This is more convenient
2647 than defining a separate Builder object
2648 for a single special-case build.
2650 As a special case, the
2652 keyword argument can
2655 that will be used to scan the sources.
2659 if any of the sources will be directories
2660 that must be scanned on-disk for
2661 changes to files that aren't
2662 already specified in other Builder of function calls.)
2664 Any other keyword arguments specified override any
2665 same-named existing construction variables.
2667 An action can be an external command,
2668 specified as a string,
2669 or a callable Python object;
2670 see "Action Objects," below,
2671 for more complete information.
2672 Also note that a string specifying an external command
2673 may be preceded by an
2676 to suppress printing the command in question,
2680 to ignore the exit status of the external command.
2685 env.Command('foo.out', 'foo.in',
2686 "$FOO_BUILD < $SOURCES > $TARGET")
2688 env.Command('bar.out', 'bar.in',
2690 "$BAR_BUILD < $SOURCES > $TARGET"],
2691 ENV = {'PATH' : '/usr/local/bin/'})
2693 def rename(env, target, source):
2695 os.rename('.tmp', str(target[0]))
2697 env.Command('baz.out', 'baz.in',
2698 ["$BAZ_BUILD < $SOURCES > .tmp",
2705 function will usually assume, by default,
2706 that the specified targets and/or sources are Files,
2707 if no other part of the configuration
2708 identifies what type of entry it is.
2709 If necessary, you can explicitly specify
2710 that targets or source nodes should
2711 be treated as directoriese
2721 env.Command('ddd.list', Dir('ddd'), 'ls -l $SOURCE > $TARGET')
2723 env['DISTDIR'] = 'destination/directory'
2724 env.Command(env.Dir('$DISTDIR')), None, make_distdir)
2728 (Also note that SCons will usually
2729 automatically create any directory necessary to hold a target file,
2730 so you normally don't need to create directories by hand.)
2732 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2734 .RI Configure( env ", [" custom_tests ", " conf_dir ", " log_file ", " config_h ])
2736 .RI env.Configure([ custom_tests ", " conf_dir ", " log_file ", " config_h ])
2737 Creates a Configure object for integrated
2738 functionality similar to GNU autoconf.
2739 See the section "Configure Contexts,"
2740 below, for a complete explanation of the arguments and behavior.
2742 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2744 .RI env.Clone([ key = val ", ...])"
2745 Return a separate copy of a construction environment.
2746 If there are any keyword arguments specified,
2747 they are added to the returned copy,
2748 overwriting any existing values
2755 env3 = env.Clone(CCFLAGS = '-g')
2758 Additionally, a list of tools and a toolpath may be specified, as in
2759 the Environment constructor:
2762 def MyTool(env): env['FOO'] = 'bar'
2763 env4 = env.Clone(tools = ['msvc', MyTool])
2766 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2768 .RI env.Copy([ key = val ", ...])"
2771 (This will probably be officially deprecated some day.)
2773 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2775 .RI env.CVS( repository ", " module )
2776 A factory function that
2777 returns a Builder object
2778 to be used to fetch source files
2782 The returned Builder
2783 is intended to be passed to the
2787 The optional specified
2789 will be added to the beginning
2790 of all repository path names;
2791 this can be used, in essence,
2792 to strip initial directory names
2793 from the repository path names,
2794 so that you only have to
2795 replicate part of the repository
2796 directory hierarchy in your
2797 local build directory.
2802 # Will fetch foo/bar/src.c
2803 # from /usr/local/CVSROOT/foo/bar/src.c.
2804 env.SourceCode('.', env.CVS('/usr/local/CVSROOT'))
2806 # Will fetch bar/src.c
2807 # from /usr/local/CVSROOT/foo/bar/src.c.
2808 env.SourceCode('.', env.CVS('/usr/local/CVSROOT', 'foo'))
2811 # from /usr/local/CVSROOT/foo/bar/src.c.
2812 env.SourceCode('.', env.CVS('/usr/local/CVSROOT', 'foo/bar'))
2815 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2817 .RI Decider( function )
2819 .RI env.Decider( function )
2820 Specifies that all up-to-date decisions for
2821 targets built through this construction environment
2822 will be handled by the specified
2826 can be one of the following strings
2827 that specify the type of decision function
2832 Specifies that a target shall be considered out of date and rebuilt
2833 if the dependency's timestamp is newer than the target file's timestamp.
2834 This is the behavior of the classic Make utility,
2837 can be used a synonym for
2838 .BR timestamp-newer .
2842 Specifies that a target shall be considered out of date and rebuilt
2843 if the dependency's timestamp is different than the
2844 timestamp recorded the last time the target was built.
2845 This provides behavior very similar to the classic Make utility
2846 (in particular, files are not opened up so that their
2847 contents can be checksummed)
2848 except that the target will also be rebuilt if a
2849 dependency file has been restored to a version with an
2851 timestamp, such as can happen when restoring files from backup archives.
2855 Specifies that a target shall be considered out of date and rebuilt
2856 if the dependency's content has changed sine the last time
2857 the target was built,
2858 as determined be performing an MD5 checksum
2859 on the dependency's contents
2860 and comparing it to the checksum recorded the
2861 last time the target was built.
2863 can be used as a synonym for
2868 Specifies that a target shall be considered out of date and rebuilt
2869 if the dependency's content has changed sine the last time
2870 the target was built,
2871 except that dependencies with a timestamp that matches
2872 the last time the target was rebuilt will be
2873 assumed to be up-to-date and
2876 This provides behavior very similar
2879 behavior of always checksumming file contents,
2880 with an optimization of not checking
2881 the contents of files whose timestamps haven't changed.
2882 The drawback is that SCons will
2884 detect if a file's content has changed
2885 but its timestamp is the same,
2886 as might happen in an automated script
2889 and runs the build again,
2890 all within a single second.
2896 # Use exact timestamp matches by default.
2897 Decider('timestamp-match')
2899 # Use MD5 content signatures for any targets built
2900 # with the attached construction environment.
2901 env.Decider('content')
2904 In addition to the above already-available functions,
2907 argument may be an actual Python function
2908 that takes the following three arguments:
2911 The Node (file) which
2915 if it has "changed" since the last tme
2916 .I target was built.
2919 The Node (file) being built.
2921 this is what should get rebuilt
2927 Stored information about the state of the
2932 This can be consulted to match various
2933 file characteristics
2934 such as the timestamp,
2935 size, or content signature.
2944 has "changed" since the last time
2948 (indicating that the target
2955 (indicating that the target should
2958 Note that the decision can be made
2959 using whatever criteria are appopriate.
2960 Ignoring some or all of the function arguments
2961 is perfectly normal.
2966 def my_decider(dependency, target, prev_ni):
2967 return not os.path.exists(str(target))
2969 env.Decider(my_decider)
2972 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2974 .RI Default( targets )
2976 .RI env.Default( targets )
2977 This specifies a list of default targets,
2978 which will be built by
2980 if no explicit targets are given on the command line.
2984 and add to the list of default targets.
2986 Multiple targets should be specified as
2987 separate arguments to the
2989 method, or as a list.
2991 will also accept the Node returned by any
2992 of a construction environment's
2998 Default('foo', 'bar', 'baz')
2999 env.Default(['a', 'b', 'c'])
3000 hello = env.Program('hello', 'hello.c')
3008 will clear all default targets.
3011 will add to the (now empty) default-target list
3014 The current list of targets added using the
3016 function or method is available in the
3021 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3023 .RI DefaultEnvironment([ args ])
3024 Creates and returns a default construction environment object.
3025 This construction environment is used internally by SCons
3026 in order to execute many of the global functions in this list,
3027 and to fetch source files transparently
3028 from source code management systems.
3030 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3032 .RI Depends( target ", " dependency )
3034 .RI env.Depends( target ", " dependency )
3035 Specifies an explicit dependency;
3036 the target file(s) will be rebuilt
3037 whenever the dependency file(s) has changed.
3038 This should only be necessary
3039 for cases where the dependency
3040 is not caught by a Scanner
3046 env.Depends('foo', 'other-input-file-for-foo')
3049 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3051 .RI env.Dictionary([ vars ])
3052 Returns a dictionary object
3053 containing copies of all of the
3054 construction variables in the environment.
3055 If there are any variable names specified,
3056 only the specified construction
3057 variables are returned in the dictionary.
3062 dict = env.Dictionary()
3063 cc_dict = env.Dictionary('CC', 'CCFLAGS', 'CCCOM')
3066 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3068 .RI Dir( name ", [" directory ])
3070 .RI env.Dir( name ", [" directory ])
3071 This returns a Directory Node,
3072 an object that represents the specified directory
3075 can be a relative or absolute path.
3077 is an optional directory that will be used as the parent directory.
3080 is specified, the current script's directory is used as the parent.
3082 Directory Nodes can be used anywhere you
3083 would supply a string as a directory name
3084 to a Builder method or function.
3085 Directory Nodes have attributes and methods
3086 that are useful in many situations;
3087 see "File and Directory Nodes," below.
3089 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3091 .RI env.Dump([ key ])
3092 Returns a pretty printable representation of the environment.
3096 should be a string containing the name of the variable of interest.
3101 print env.Dump('CCCOM')
3106 '$CC $CCFLAGS $CPPFLAGS $_CPPDEFFLAGS $_CPPINCFLAGS -c -o $TARGET $SOURCES'
3117 'ARCOM': '$AR $ARFLAGS $TARGET $SOURCES\n$RANLIB $RANLIBFLAGS $TARGET',
3120 'ASCOM': '$AS $ASFLAGS -o $TARGET $SOURCES',
3125 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3127 .RI EnsurePythonVersion( major ", " minor )
3129 .RI env.EnsurePythonVersion( major ", " minor )
3130 Ensure that the Python version is at least
3133 print out an error message and exit SCons with a non-zero exit code if the
3134 actual Python version is not late enough.
3139 EnsurePythonVersion(2,2)
3142 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3144 .RI EnsureSConsVersion( major ", " minor ", [" revision ])
3146 .RI env.EnsureSConsVersion( major ", " minor ", [" revision ])
3147 Ensure that the SCons version is at least
3150 .IR major.minor.revision .
3155 print out an error message and exit SCons with a non-zero exit code if the
3156 actual SCons version is not late enough.
3161 EnsureSConsVersion(0,14)
3163 EnsureSConsVersion(0,96,90)
3166 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3168 .RI Environment([ key = value ", ...])"
3170 .RI env.Environment([ key = value ", ...])"
3171 Return a new construction environment
3172 initialized with the specified
3176 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3178 .RI Execute( action ", [" strfunction ", " varlist ])
3180 .RI env.Execute( action ", [" strfunction ", " varlist ])
3181 Executes an Action object.
3184 may be an Action object
3185 (see the section "Action Objects,"
3186 below, for a complete explanation of the arguments and behavior),
3187 or it may be a command-line string,
3189 or executable Python function,
3190 each of which will be converted
3191 into an Action object
3193 The exit value of the command
3194 or return value of the Python function
3197 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3201 .RI env.Exit([ value ])
3207 A default exit value of
3210 is used if no value is specified.
3212 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3216 .RI env.Export( vars )
3219 to export a list of variables from the current
3220 SConscript file to all other SConscript files.
3221 The exported variables are kept in a global collection,
3222 so subsequent calls to
3224 will over-write previous exports that have the same name.
3225 Multiple variable names can be passed to
3227 as separate arguments or as a list. A dictionary can be used to map
3228 variables to a different name when exported. Both local variables and
3229 global variables can be exported.
3235 # Make env available for all SConscript files to Import().
3239 # Make env and package available for all SConscript files:.
3240 Export("env", "package")
3242 # Make env and package available for all SConscript files:
3243 Export(["env", "package"])
3245 # Make env available using the name debug:.
3246 Export({"debug":env})
3252 function supports an
3254 argument that makes it easier to to export a variable or
3255 set of variables to a single SConscript file.
3256 See the description of the
3260 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3262 .RI File( name ", [" directory ])
3264 .RI env.File( name ", [" directory ])
3267 an object that represents the specified file
3270 can be a relative or absolute path.
3272 is an optional directory that will be used as the parent directory.
3274 File Nodes can be used anywhere you
3275 would supply a string as a file name
3276 to a Builder method or function.
3277 File Nodes have attributes and methods
3278 that are useful in many situations;
3279 see "File and Directory Nodes," below.
3281 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3283 .RI FindFile( file ", " dirs )
3285 .RI env.FindFile( file ", " dirs )
3288 in the path specified by
3291 may be a list of file names or a single file name. In addition to searching
3292 for files that exist in the filesytem, this function also searches for
3293 derived files that have not yet been built.
3298 foo = env.FindFile('foo', ['dir1', 'dir2'])
3301 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3303 .RI FindInstalledFiles( )
3305 .RI env.FindInstalledFiles( )
3306 Returns the list of targets setup by the
3312 This function serves as a convenient method to select the contents of
3318 Install( '/bin', [ 'executable_a', 'executable_b' ] )
3320 # will return the file node list
3321 # [ '/bin/executable_a', '/bin/executable_b' ]
3322 FindInstalledFiles()
3324 Install( '/lib', [ 'some_library' ] )
3326 # will return the file node list
3327 # [ '/bin/executable_a', '/bin/executable_b', '/lib/some_library' ]
3328 FindInstalledFiles()
3331 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3333 .RI FindSourceFiles( node = '"."' )
3335 .RI env.FindSourceFiles( node = '"."' )
3337 Returns the list of nodes which serve as the source of the built files.
3338 It does so by inspecting the dependency tree starting at the optional
3341 which defaults to the '"."'-node. It will then return all leafs of
3343 These are all children which have no further children.
3345 This function is a convenient method to select the contents of a Source
3351 Program( 'src/main_a.c' )
3352 Program( 'src/main_b.c' )
3353 Program( 'main_c.c' )
3355 # returns ['main_c.c', 'src/main_a.c', 'SConstruct', 'src/main_b.c']
3358 # returns ['src/main_b.c', 'src/main_a.c' ]
3359 FindSourceFiles( 'src' )
3362 As you can see build support files (SConstruct in the above example)
3363 will also be returned by this function.
3365 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3367 .RI FindPathDirs( variable )
3369 (actually a callable Python object)
3370 intended to be used as the
3372 of a Scanner object.
3373 The returned object will look up the specified
3375 in a construction environment
3376 and treat the construction variable's value as a list of
3377 directory paths that should be searched
3385 is generally preferable to
3388 for the following reasons:
3389 1) The returned list will contain all appropriate directories
3390 found in source trees
3394 or in code repositories
3400 2) scons will identify expansions of
3402 that evaluate to the same list of directories as,
3403 in fact, the same list,
3404 and avoid re-scanning the directories for files,
3410 def my_scan(node, env, path, arg):
3411 # Code to scan file contents goes here...
3412 return include_files
3414 scanner = Scanner(name = 'myscanner',
3416 path_function = FindPathDirs('MYPATH'))
3419 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3421 .RI Flatten( sequence )
3423 .RI env.Flatten( sequence )
3424 Takes a sequence (that is, a Python list or tuple)
3425 that may contain nested sequences
3426 and returns a flattened list containing
3427 all of the individual elements in any sequence.
3428 This can be helpful for collecting
3429 the lists returned by calls to Builders;
3430 other Builders will automatically
3431 flatten lists specified as input,
3432 but direct Python manipulation of
3433 these lists does not.
3438 foo = Object('foo.c')
3439 bar = Object('bar.c')
3441 # Because `foo' and `bar' are lists returned by the Object() Builder,
3442 # `objects' will be a list containing nested lists:
3443 objects = ['f1.o', foo, 'f2.o', bar, 'f3.o']
3445 # Passing such a list to another Builder is all right because
3446 # the Builder will flatten the list automatically:
3447 Program(source = objects)
3449 # If you need to manipulate the list directly using Python, you need to
3450 # call Flatten() yourself, or otherwise handle nested lists:
3451 for object in Flatten(objects):
3455 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3457 .RI GetBuildPath( file ", [" ... ])
3459 .RI env.GetBuildPath( file ", [" ... ])
3462 path name (or names) for the specified
3470 Nodes or strings representing path names.
3472 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3476 .RI env.GetLaunchDir()
3477 Returns the absolute path name of the directory from which
3480 was initially invoked.
3481 This can be useful when using the
3486 options, which internally
3487 change to the directory in which the
3491 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3493 .RI GetOption( name )
3495 .RI env.GetOption( name )
3496 This function provides a way to query a select subset of the scons command line
3497 options from a SConscript file. See
3499 for a description of the options available.
3501 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3503 '\".RI GlobalBuilders( flag )
3507 '\"adds the names of the default builders
3508 '\"(Program, Library, etc.)
3509 '\"to the global name space
3510 '\"so they can be called without an explicit construction environment.
3511 '\"(This is the default.)
3515 '\"the names of the default builders are removed
3516 '\"from the global name space
3517 '\"so that an explicit construction environment is required
3518 '\"to call all builders.
3520 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3524 .RI env.Help( text )
3525 This specifies help text to be printed if the
3527 argument is given to
3531 is called multiple times, the text is appended together in the order
3536 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3538 .RI Ignore( target ", " dependency )
3540 .RI env.Ignore( target ", " dependency )
3541 The specified dependency file(s)
3542 will be ignored when deciding if
3543 the target file(s) need to be rebuilt.
3548 env.Ignore('foo', 'foo.c')
3549 env.Ignore('bar', ['bar1.h', 'bar2.h'])
3552 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3556 .RI env.Import( vars )
3559 to import a list of variables into the current SConscript file. This
3560 will import variables that were exported with
3566 Variables exported by
3569 Multiple variable names can be passed to
3571 as separate arguments or as a list. The variable "*" can be used
3572 to import all variables.
3578 Import("env", "variable")
3579 Import(["env", "variable"])
3583 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3585 .RI Literal( string )
3587 .RI env.Literal( string )
3590 will be preserved as-is
3591 and not have construction variables expanded.
3593 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3595 .RI Local( targets )
3597 .RI env.Local( targets )
3600 will have copies made in the local tree,
3601 even if an already up-to-date copy
3602 exists in a repository.
3603 Returns a list of the target Node or Nodes.
3605 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3607 .RI env.MergeFlags( arg ", [" unique ])
3608 Merges the specified
3610 values to the construction envrionment's construction variables.
3613 argument is not a dictionary,
3614 it is converted to one by calling
3617 before the values are merged.
3620 must be a single value,
3621 so multiple strings must
3622 be passed in as a list,
3623 not as separate arguments to
3624 .BR env.MergeFlags ().
3627 duplicate values are eliminated;
3628 you can, however, specify
3632 When eliminating duplicate values,
3633 any construction variables that end with
3636 keep the left-most unique value.
3637 All other construction variables keep
3638 the right-most unique value.
3643 # Add an optimization flag to $CCFLAGS.
3644 env.MergeFlags('-O3')
3646 # Combine the flags returned from running pkg-config with an optimization
3647 # flag and merge the result into the construction variables.
3648 env.MergeFlags(['!pkg-config gtk+-2.0 --cflags', '-O3'])
3650 env.MergeFlags(['-O3',
3651 '!pkg-config gtk+-2.0 --cflags --libs',
3652 '!pkg-config libpng12 --cflags --libs'])
3655 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3657 .RI NoCache( target ", ...)"
3659 .RI env.NoCache( target ", ...)"
3660 Specifies a list of files which should
3662 be cached whenever the
3664 method has been activated.
3665 The specified targets may be a list
3666 or an individual target.
3668 Multiple files should be specified
3669 either as separate arguments to the
3671 method, or as a list.
3673 will also accept the return value of any of the construction environment
3678 on directories and other non-File Node types has no effect because
3679 only File Nodes are cached.
3685 NoCache(env.Program('hello', 'hello.c'))
3688 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3690 .RI NoClean( target ", ...)"
3692 .RI env.NoClean( target ", ...)"
3693 Specifies a list of files or directories which should
3695 be removed whenever the targets (or their dependencies)
3696 are specified with the
3698 command line option.
3699 The specified targets may be a list
3700 or an individual target.
3704 and prevent each specified target
3705 from being removed by calls to the
3709 Multiple files or directories should be specified
3710 either as separate arguments to the
3712 method, or as a list.
3714 will also accept the return value of any of the construction environment
3719 for a target overrides calling
3721 for the same target,
3722 and any targets passed to both functions will
3732 NoClean(env.Program('hello', 'hello.c'))
3735 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3737 .RI env.ParseConfig( command ", [" function ", " unique ])
3740 to modify the environment as specified by the output of
3745 .BR env.MergeFlags (),
3746 which expects the output of a typical
3750 and adds the options
3751 to the appropriate construction variables.
3753 duplicate values are not
3754 added to any construction variables;
3761 and the construction variables they affect
3762 are as specified for the
3763 .BR env.ParseFlags ()
3764 method (which thie method calls).
3765 See that method's description, below,
3766 for a table of options and construction variables.
3768 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3770 .RI ParseDepends( filename ", [" must_exist ", " only_one ])
3772 .RI env.ParseDepends( filename ", [" must_exist ", " only_one ])
3773 Parses the contents of the specified
3775 as a list of dependencies in the style of
3779 and explicitly establishes all of the listed dependencies.
3788 argument may be set to a non-zero
3791 throw an exception and
3792 generate an error if the file does not exist,
3793 or is otherwise inaccessible.
3797 argument may be set to a non-zero
3800 thrown an exception and
3802 if the file contains dependency
3803 information for more than one target.
3804 This can provide a small sanity check
3805 for files intended to be generated
3806 by, for example, the
3809 which should typically only
3810 write dependency information for
3811 one output file into a corresponding
3817 and all of the files listed therein
3818 will be interpreted relative to
3819 the directory of the
3821 file which calls the
3825 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3827 .RI env.ParseFlags( flags ", ...)"
3828 Parses one or more strings containing
3829 typical command-line flags for GCC tool chains
3830 and returns a dictionary with the flag values
3831 separated into the appropriate SCons construction variables.
3832 This is intended as a companion to the
3833 .BR env.MergeFlags ()
3834 method, but allows for the values in the returned dictionary
3835 to be modified, if necessary,
3836 before merging them into the construction environment.
3838 .BR env.MergeFlags ()
3839 will call this method if its argument is not a dictionary,
3840 so it is usually not necessary to call
3841 .BR env.ParseFlags ()
3842 directly unless you want to manipulate the values.)
3844 If the first character in any string is
3845 an exclamation mark (!),
3846 the rest of the string is executed as a command,
3847 and the output from the command is
3848 parsed as GCC tool chain command-line flags
3849 and added to the resulting dictionary.
3851 Flag values are translated accordig to the prefix found,
3852 and added to the following construction variables:
3855 -arch CCFLAGS, LINKFLAGS
3857 -framework FRAMEWORKS
3858 -frameworkdir= FRAMEWORKPATH
3860 -isysroot CCFLAGS, LINKFLAGS
3864 -mno-cygwin CCFLAGS, LINKFLAGS
3866 -pthread CCFLAGS, LINKFLAGS
3868 -Wa, ASFLAGS, CCFLAGS
3875 + CCFLAGS, LINKFLAGS
3879 Any other strings not associated with options
3880 are assumed to be the names of libraries
3883 construction variable.
3885 Examples (all of which produce the same result):
3888 dict = env.ParseFlags('-O2 -Dfoo -Dbar=1')
3889 dict = env.ParseFlags('-O2', '-Dfoo', '-Dbar=1')
3890 dict = env.ParseFlags(['-O2', '-Dfoo -Dbar=1'])
3891 dict = env.ParseFlags('-O2', '!echo -Dfoo -Dbar=1')
3894 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3897 A factory function that
3898 returns a Builder object
3899 to be used to fetch source files
3900 from the Perforce source code management system.
3901 The returned Builder
3902 is intended to be passed to the
3909 env.SourceCode('.', env.Perforce())
3912 Perforce uses a number of external
3913 environment variables for its operation.
3914 Consequently, this function adds the
3915 following variables from the user's external environment
3916 to the construction environment's
3929 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3931 .RI Platform( string )
3932 Returns a callable object
3933 that can be used to initialize
3934 a construction environment using the
3935 platform keyword of the Environment() method.
3940 env = Environment(platform = Platform('win32'))
3943 .RI env.Platform( string )
3944 Applies the callable object for the specified platform
3946 to the environment through which the method was called.
3949 env.Platform('posix')
3958 variables from the user's external environment
3959 to the construction environment's
3962 This is so that any executed commands
3963 that use sockets to connect with other systems
3964 (such as fetching source files from
3965 external CVS repository specifications like
3966 .BR :pserver:anonymous@cvs.sourceforge.net:/cvsroot/scons )
3967 will work on Windows systems.
3969 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3971 .RI Progress( callable ", [" interval ])
3973 .RI Progress( string ", [" interval ", " file ", " overwrite ])
3975 .RI Progress( list_of_strings ", [" interval ", " file ", " overwrite ])
3976 Allows SCons to show progress made during the build
3977 by displaying a string or calling a function while
3978 evaluating Nodes (e.g. files).
3980 If the first specified argument is a Python callable
3981 (a function or an object that has a
3984 the function will be called
3987 times a Node is evaluated.
3988 The callable will be passed the evaluated Node
3989 as its only argument.
3990 (For future compatibility,
3991 it's a good idea to also add
3995 as arguments to your function or method.
3996 This will prevent the code from breaking
3997 if SCons ever changes the interface
3998 to call the function with additional arguments in the future.)
4000 An example of a simple custom progress function
4001 that prints a string containing the Node name
4005 def my_progress_function(node, *args, **kw):
4006 print 'Evaluating node %s!' % node
4007 Progress(my_progress_function, interval=10)
4010 A more complicated example of a custom progress display object
4011 that prints a string containing a count
4012 every 100 evaluated Nodes.
4016 at the end so that the string
4017 will overwrite itself on a display:
4021 class ProgressCounter:
4023 def __call__(self, node, *args, **kw):
4025 sys.stderr.write('Evaluated %s nodes\\r' % self.count)
4026 Progress(ProgressCounter(), interval=100)
4029 If the first argument
4032 the string will be displayed
4036 The default is to print the string on standard output;
4037 an alternate output stream
4038 may be specified with the
4041 The following will print a series of dots
4042 on the error output,
4043 one dot for every 100 evaluated Nodes:
4047 Progress('.', interval=100, file=sys.stderr)
4050 If the string contains the verbatim substring
4052 it will be replaced with the Node.
4053 Note that, for performance reasons, this is
4055 a regular SCons variable substition,
4056 so you can not use other variables
4057 or use curly braces.
4058 The following example will print the name of
4059 every evaluated Node,
4062 (carriage return) to cause each line to overwritten by the next line,
4065 keyword argument to make sure the previously-printed
4066 file name is overwritten with blank spaces:
4070 Progress('$TARGET\\r', overwrite=True)
4073 If the first argument to
4075 is a list of strings,
4076 then each string in the list will be displayed
4077 in rotating fashion every
4080 This can be used to implement a "spinner"
4081 on the user's screen as follows:
4084 Progress(['-\\r', '\\\\\\r', '|\\r', '/\\r'], interval=5)
4087 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4089 .RI Precious( target ", ...)"
4091 .RI env.Precious( target ", ...)"
4094 as precious so it is not deleted before it is rebuilt. Normally
4096 deletes a target before building it.
4097 Multiple targets can be passed in to a single call to
4100 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4102 .RI env.Prepend( key = val ", [...])"
4103 Appends the specified keyword arguments
4104 to the beginning of construction variables in the environment.
4105 If the Environment does not have
4106 the specified construction variable,
4107 it is simply added to the environment.
4108 If the values of the construction variable
4109 and the keyword argument are the same type,
4110 then the two values will be simply added together.
4111 Otherwise, the construction variable
4112 and the value of the keyword argument
4113 are both coerced to lists,
4114 and the lists are added together.
4115 (See also the Append method, above.)
4120 env.Prepend(CCFLAGS = '-g ', FOO = ['foo.yyy'])
4123 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4125 .RI env.PrependENVPath( name ", " newpath ", [" envname ", " sep ])
4126 This appends new path elements to the given path in the
4127 specified external environment
4131 any particular path once (leaving the first one it encounters and
4132 ignoring the rest, to preserve path order),
4133 and to help assure this,
4134 will normalize all paths (using
4137 .BR os.path.normcase ).
4138 This can also handle the
4139 case where the given old path variable is a list instead of a
4140 string, in which case a list will be returned instead of a string.
4145 print 'before:',env['ENV']['INCLUDE']
4146 include_path = '/foo/bar:/foo'
4147 env.PrependENVPath('INCLUDE', include_path)
4148 print 'after:',env['ENV']['INCLUDE']
4151 The above exmaple will print:
4155 after: /foo/bar:/foo:/biz
4158 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4160 .RI env.PrependUnique( key = val ", [...])"
4161 Appends the specified keyword arguments
4162 to the beginning of construction variables in the environment.
4163 If the Environment does not have
4164 the specified construction variable,
4165 it is simply added to the environment.
4166 If the construction variable being appended to is a list,
4167 then any value(s) that already exist in the
4168 construction variable will
4170 be added again to the list.
4175 env.PrependUnique(CCFLAGS = '-g', FOO = ['foo.yyy'])
4178 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4181 A factory function that
4182 returns a Builder object
4183 to be used to fetch source files
4185 The returned Builder
4186 is intended to be passed to the
4193 env.SourceCode('.', env.RCS())
4198 will fetch source files
4199 from RCS subdirectories automatically,
4201 as demonstrated in the above example
4202 should only be necessary if
4203 you are fetching from
4206 directory as the source files,
4207 or if you need to explicitly specify RCS
4208 for a specific subdirectory.
4210 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4212 .RI env.Replace( key = val ", [...])"
4213 Replaces construction variables in the Environment
4214 with the specified keyword arguments.
4219 env.Replace(CCFLAGS = '-g', FOO = 'foo.xxx')
4222 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4224 .RI Repository( directory )
4226 .RI env.Repository( directory )
4229 is a repository to be searched for files.
4233 and each one adds to the list of
4234 repositories that will be searched.
4238 a repository is a copy of the source tree,
4239 from the top-level directory on down,
4241 both source files and derived files
4242 that can be used to build targets in
4243 the local source tree.
4244 The canonical example would be an
4245 official source tree maintained by an integrator.
4246 If the repository contains derived files,
4247 then the derived files should have been built using
4249 so that the repository contains the necessary
4250 signature information to allow
4252 to figure out when it is appropriate to
4253 use the repository copy of a derived file,
4254 instead of building one locally.
4256 Note that if an up-to-date derived file
4257 already exists in a repository,
4261 make a copy in the local directory tree.
4262 In order to guarantee that a local copy
4268 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4270 .RI Return([ vars "... , " stop= ])
4272 this stops processing the current SConscript
4273 file and returns to the calling SConscript file
4274 the values of the variables named in the
4277 Multiple strings contaning variable names may be passed to
4279 Any strings that contain white space
4283 keyword argument may be set to a false value
4284 to continue processing the rest of the SConscript
4288 This was the default behavior prior to SCons 0.98.
4289 However, the values returned
4290 are still the values of the variables in the named
4299 # Returns without returning a value.
4302 # Returns the value of the 'foo' Python variable.
4305 # Returns the values of the Python variables 'foo' and 'bar'.
4306 Return("foo", "bar")
4308 # Returns the values of Python variables 'val1' and 'val2'.
4312 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4314 .RI Scanner( function ", [" argument ", " keys ", " path_function ", " node_class ", " node_factory ", " scan_check ", " recursive ])
4316 .RI env.Scanner( function ", [" argument ", " keys ", " path_function ", " node_class ", " node_factory ", " scan_check ", " recursive ])
4317 Creates a Scanner object for
4320 See the section "Scanner Objects,"
4321 below, for a complete explanation of the arguments and behavior.
4323 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4326 A factory function that
4327 returns a Builder object
4328 to be used to fetch source files
4330 The returned Builder
4331 is intended to be passed to the
4338 env.SourceCode('.', env.SCCS())
4343 will fetch source files
4344 from SCCS subdirectories automatically,
4346 as demonstrated in the above example
4347 should only be necessary if
4348 you are fetching from
4351 directory as the source files,
4352 or if you need to explicitly specify SCCS
4353 for a specific subdirectory.
4355 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4357 .RI SConscript( scripts ", [" exports ", " build_dir ", " src_dir ", " duplicate ])
4359 .RI env.SConscript( scripts ", [" exports ", " build_dir ", " src_dir ", " duplicate ])
4361 .RI SConscript(dirs= subdirs ", [name=" script ", " exports ", " build_dir ", " src_dir ", " duplicate ])
4363 .RI env.SConscript(dirs= subdirs ", [name=" script ", " exports ", " build_dir ", " src_dir ", " duplicate ])
4367 one or more subsidiary SConscript (configuration) files.
4368 There are two ways to call the
4372 The first way you can call
4374 is to explicitly specify one or more
4376 as the first argument.
4377 A single script may be specified as a string;
4378 multiple scripts must be specified as a list
4379 (either explicitly or as created by
4383 The second way you can call
4385 is to specify a list of (sub)directory names
4392 execute a subsidiary configuration file named
4394 in each of the specified directories.
4395 You may specify a name other than
4397 by supplying an optional
4403 argument provides a list of variable names or a dictionary of
4404 named values to export to the
4406 These variables are locally exported only to the specified
4408 and do not affect the
4409 global pool of variables used by
4413 '\"If multiple dirs are provided,
4414 '\"each script gets a fresh export.
4419 function to import the variables.
4423 argument specifies that all of the target files
4424 (for example, object files and executables)
4425 that would normally be built in the subdirectory in which
4427 resides should actually
4431 is interpreted relative to the directory
4432 of the calling SConscript file.
4436 argument specifies that the
4437 source files from which
4438 the target files should be built
4442 is interpreted relative to the directory
4443 of the calling SConscript file.
4447 will link or copy (depending on the platform)
4448 all the source files into the build directory.
4449 This behavior may be disabled by
4450 setting the optional
4453 (it is set to 1 by default),
4456 will refer directly to
4457 the source files in their source directory
4458 when building target files.
4461 is usually safe, and always more efficient
4464 but it may cause build problems in certain end-cases,
4465 such as compiling from source files that
4466 are generated by the build.)
4468 Any variables returned by
4472 will be returned by the call to
4478 SConscript('subdir/SConscript')
4479 foo = SConscript('sub/SConscript', exports='env')
4480 SConscript('dir/SConscript', exports=['env', 'variable'])
4481 SConscript('src/SConscript', build_dir='build', duplicate=0)
4482 SConscript('bld/SConscript', src_dir='src', exports='env variable')
4483 SConscript(dirs=['sub1', 'sub2'])
4484 SConscript(dirs=['sub3', 'sub4'], name='MySConscript')
4487 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4489 .RI SConscriptChdir( value )
4491 .RI env.SConscriptChdir( value )
4494 changes its working directory
4495 to the directory in which each
4496 subsidiary SConscript file lives.
4497 This behavior may be disabled
4498 by specifying either:
4502 env.SConscriptChdir(0)
4507 will stay in the top-level directory
4508 while reading all SConscript files.
4509 (This may be necessary when building from repositories,
4510 when all the directories in which SConscript files may be found
4511 don't necessarily exist locally.)
4512 You may enable and disable
4513 this ability by calling
4522 SConscript('foo/SConscript') # will not chdir to foo
4523 env.SConscriptChdir(1)
4524 SConscript('bar/SConscript') # will chdir to bar
4527 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4529 .RI SConsignFile([ file , dbm_module ])
4531 .RI env.SConsignFile([ file , dbm_module ])
4534 to store all file signatures
4535 in the specified database
4542 (The actual file name(s) stored on disk
4543 may have an appropriated suffix appended
4548 is not an absolute path name,
4549 the file is placed in the same directory as the top-level
4559 will store file signatures
4562 file in each directory,
4563 not in one global database file.
4564 (This was the default behavior
4565 prior to SCons 0.96.91 and 0.97.)
4569 argument can be used to specify
4570 which Python database module
4571 The default is to use a custom
4573 module that uses pickled
4574 Python data structures,
4575 and which works on all Python versions from 1.5.2 on.
4580 # Explicitly stores signatures in ".sconsign.dblite"
4581 # in the top-level SConstruct directory (the
4582 # default behavior).
4585 # Stores signatures in the file "etc/scons-signatures"
4586 # relative to the top-level SConstruct directory.
4587 SConsignFile("etc/scons-signatures")
4589 # Stores signatures in the specified absolute file name.
4590 SConsignFile("/home/me/SCons/signatures")
4592 # Stores signatures in a separate .sconsign file
4593 # in each directory.
4597 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4599 .RI env.SetDefault(key = val ", [...])"
4600 Sets construction variables to default values specified with the keyword
4601 arguments if (and only if) the variables are not already set.
4602 The following statements are equivalent:
4605 env.SetDefault(FOO = 'foo')
4607 if not env.has_key('FOO'): env['FOO'] = 'foo'
4610 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4612 .RI SetOption( name ", " value )
4614 .RI env.SetOption( name ", " value )
4615 This function provides a way to set a select subset of the scons command
4616 line options from a SConscript file. The options supported are:
4618 which corresponds to -c, --clean and --remove;
4620 which corresponds to --duplicate;
4622 which corresponds to -h and --help;
4624 which corresponds to --implicit-cache;
4626 which corresponds to --max-drift;
4628 which corresponds to -n, --no-exec, --just-print, --dry-run and --recon;
4630 which corresponds to -j and --jobs.
4632 which corresponds to --random.
4633 See the documentation for the
4634 corresponding command line object for information about each specific
4640 SetOption('max_drift', 1)
4643 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4645 .RI SideEffect( side_effect ", " target )
4647 .RI env.SideEffect( side_effect ", " target )
4650 as a side effect of building
4656 can be a list, a file name, or a node.
4657 A side effect is a target that is created
4658 as a side effect of building other targets.
4659 For example, a Windows PDB
4660 file is created as a side effect of building the .obj
4661 files for a static library.
4662 If a target is a side effect of multiple build commands,
4664 will ensure that only one set of commands
4665 is executed at a time.
4666 Consequently, you only need to use this method
4667 for side-effect targets that are built as a result of
4668 multiple build commands.
4670 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4672 .RI SourceCode( entries ", " builder )
4674 .RI env.SourceCode( entries ", " builder )
4675 Arrange for non-existent source files to
4676 be fetched from a source code management system
4681 may be a Node, string or list of both,
4682 and may represent either individual
4683 source files or directories in which
4684 source files can be found.
4686 For any non-existent source files,
4688 will search up the directory tree
4698 will not use a builder to fetch
4699 source files for the specified
4703 builder has been specified
4704 for a directory higher up the tree.
4708 fetch files from SCCS or RCS subdirectories
4709 without explicit configuration.
4710 This takes some extra processing time
4711 to search for the necessary
4712 source code management files on disk.
4713 You can avoid these extra searches
4714 and speed up your build a little
4715 by disabling these searches as follows:
4718 env.SourceCode('.', None)
4722 Note that if the specified
4724 is one you create by hand,
4725 it must have an associated
4726 construction environment to use
4727 when fetching a source file.
4730 provides a set of canned factory
4731 functions that return appropriate
4732 Builders for various popular
4733 source code management systems.
4734 Canonical examples of invocation include:
4737 env.SourceCode('.', env.BitKeeper('/usr/local/BKsources'))
4738 env.SourceCode('src', env.CVS('/usr/local/CVSROOT'))
4739 env.SourceCode('/', env.RCS())
4740 env.SourceCode(['f1.c', 'f2.c'], env.SCCS())
4741 env.SourceCode('no_source.c', None)
4743 '\"env.SourceCode('.', env.Subversion('file:///usr/local/Subversion'))
4745 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4747 .RI env.subst( string ", [" raw ", " target ", " source ", " conv ])
4748 Performs construction variable interpolation
4749 on the specified string argument.
4752 leading or trailing white space will
4753 be removed from the result.
4754 and all sequences of white space
4755 will be compressed to a single space character.
4760 character sequences will be stripped from the returned string,
4763 argument may be set to
4765 if you want to preserve white space and
4770 argument may be set to
4772 if you want to strip
4773 all characters between
4779 (as is done for signature calculation).
4786 must be set to lists of
4787 target and source nodes, respectively,
4794 to be available for expansion.
4795 This is usually necessary if you are
4798 from within a Python function used
4802 all returned values are converted
4803 to their string representation.
4807 may specify a conversion function
4808 that will be used in place of
4810 For example, if you want Python objects
4811 (including SCons Nodes)
4812 to be returned as Python objects,
4813 you can use the Python
4815 idiom to pass in an unnamed function
4816 that simply returns its unconverted argument.
4821 print env.subst("The C compiler is: $CC")
4823 def compile(target, source, env):
4824 sourceDir = env.subst("${SOURCE.srcdir}",
4828 source_nodes = env.subst('$EXPAND_TO_NODELIST',
4832 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4834 '\".RI Subversion( repository ", " module )
4835 '\"A factory function that
4836 '\"returns a Builder object
4837 '\"to be used to fetch source files
4838 '\"from the specified Subversion
4840 '\"The returned Builder
4841 '\"is intended to be passed to the
4845 '\"The optional specified
4847 '\"will be added to the beginning
4848 '\"of all repository path names;
4849 '\"this can be used, in essence,
4850 '\"to strip initial directory names
4851 '\"from the repository path names,
4852 '\"so that you only have to
4853 '\"replicate part of the repository
4854 '\"directory hierarchy in your
4855 '\"local build directory.
4860 '\"# Will fetch foo/bar/src.c
4861 '\"# from /usr/local/Subversion/foo/bar/src.c.
4862 '\"env.SourceCode('.', env.Subversion('file:///usr/local/Subversion'))
4864 '\"# Will fetch bar/src.c
4865 '\"# from /usr/local/Subversion/foo/bar/src.c.
4866 '\"env.SourceCode('.', env.Subversion('file:///usr/local/Subversion', 'foo'))
4868 '\"# Will fetch src.c
4869 '\"# from /usr/local/Subversion/foo/bar/src.c.
4870 '\"env.SourceCode('.', env.Subversion('file:///usr/local/Subversion', 'foo/bar'))
4873 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4875 .RI SourceSignatures( type )
4877 .RI env.SourceSignatures( type )
4880 how to decide if a source file
4881 (a file that is not built from any other files)
4882 has changed since the last time it
4883 was used to build a particular target file.
4889 If the environment method is used,
4890 the specified type of source signature
4891 is only used when deciding whether targets
4892 built with that environment are up-to-date or must be rebuilt.
4893 If the global function is used,
4894 the specified type of source signature becomes the default
4895 used for all decisions
4896 about whether targets are up-to-date.
4901 decides that a source file has changed
4902 if the MD5 checksum of its contents has changed since
4903 the last time it was used to rebuild a particular target file.
4908 decides that a source file has changed
4909 if its timestamp (modification time) is newer than
4910 the last time it was used to rebuild a particular target file.
4912 There is no different between the two behaviors
4918 signatures take longer to compute,
4919 but are more accurate than
4922 The default value is
4925 Note that the default
4926 .BR TargetSignatures ()
4929 .BR SourceSignatures ()
4930 setting for any target files that are used
4931 to build other target files.
4932 Consequently, changing the value of
4933 .BR SourceSignatures ()
4935 affect the up-to-date decision for all files in the build
4936 (or all files built with a specific construction environment
4938 .BR env.SourceSignatures ()
4941 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4945 .RI env.Split( arg )
4946 Returns a list of file names or other objects.
4948 it will be split on strings of white-space characters
4950 making it easier to write long lists of file names.
4951 If arg is already a list,
4952 the list will be returned untouched.
4953 If arg is any other type of object,
4954 it will be returned as a list
4955 containing just the object.
4960 files = Split("f1.c f2.c f3.c")
4961 files = env.Split("f4.c f5.c f6.c")
4969 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4971 .RI Tag( node ", " tags )
4972 Annotates file or directory Nodes with
4973 information about how the
4975 Builder should package those files or directories.
4976 All tags are optional.
4981 # makes sure the built library will be installed with 0644 file
4983 Tag( Library( 'lib.c' ), UNIX_ATTR="0644" )
4985 # marks file2.txt to be a documentation file
4986 Tag( 'file2.txt', DOC )
4991 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4993 .RI TargetSignatures( type )
4995 .RI env.TargetSignatures( type )
4998 how to decide if a target file
5001 built from any other files)
5002 has changed since the last time it
5003 was used to build some other target file.
5013 If the environment method is used,
5014 the specified type of target signature is only used
5015 for targets built with that environment.
5016 If the global function is used,
5017 the specified type of signature becomes the default
5018 used for all target files that
5019 don't have an explicit target signature type
5020 specified for their environments.
5027 decides that a target file has changed
5028 if the MD5 checksum of its contents has changed since
5029 the last time it was used to rebuild some other target file.
5033 MD5 sum the contents
5034 of target files after they're built,
5035 and may decide that it does not need to rebuild
5036 "downstream" target files if a file was
5037 rebuilt with exactly the same contents as the last time.
5042 decides that a target file has changed
5043 if its timestamp (modification time) is newer than
5044 the last time it was used to rebuild some other target file.
5049 decides that a target file has changed
5050 as specified by the corresponding
5051 .BR SourceSignatures ()
5058 will treat all input files to a target the same way,
5059 regardless of whether they are source files
5060 or have been built from other files.
5065 decides that a target file has changed
5066 if it has been rebuilt in this invocation
5067 or if its content or timestamp have changed
5068 as specified by the corresponding
5069 .BR SourceSignatures ()
5071 This "propagates" the status of a rebuilt file
5072 so that other "downstream" target files
5073 will always be rebuilt,
5074 even if the contents or the timestamp
5078 signatures are fastest because
5082 signatures take longer to compute,
5083 but are more accurate than
5086 and can prevent unnecessary "downstream" rebuilds
5087 when a target file is rebuilt to the exact same contents
5088 as the previous build.
5091 setting provides the most consistent behavior
5092 when other target files may be rebuilt from
5093 both source and target input files.
5094 The default value is
5097 Because the default setting is
5100 .BR SourceSignatures ()
5101 is generally preferable to
5102 .BR TargetSignatures () ,
5103 so that the up-to-date decision
5104 will be consistent for all files
5105 (or all files built with a specific construction environment).
5107 .BR TargetSignatures ()
5108 provides specific control for how built target files
5109 affect their "downstream" dependencies.
5111 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
5113 .RI Tool( string [, toolpath ", " **kw ])
5114 Returns a callable object
5115 that can be used to initialize
5116 a construction environment using the
5117 tools keyword of the Environment() method.
5118 The object may be called with a construction
5119 environment as an argument,
5120 in which case the object will
5121 add the necessary variables
5122 to the construction environment
5123 and the name of the tool will be added to the
5125 construction variable.
5127 Additional keyword arguments are passed to the tool's
5134 env = Environment(tools = [ Tool('msvc') ])
5138 t(env) # adds 'msvc' to the TOOLS variable
5139 u = Tool('opengl', toolpath = ['tools'])
5140 u(env) # adds 'opengl' to the TOOLS variable
5143 .RI env.Tool( string [, toolpath ", " **kw ])
5144 Applies the callable object for the specified tool
5146 to the environment through which the method was called.
5148 Additional keyword arguments are passed to the tool's
5154 env.Tool('opengl', toolpath = ['build/tools'])
5157 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
5159 .RI Value( value ", [" built_value ])
5161 .RI env.Value( value ", [" built_value ])
5162 Returns a Node object representing the specified Python value. Value
5163 Nodes can be used as dependencies of targets. If the result of
5166 changes between SCons runs, any targets depending on
5169 (This is true even when using timestamps to decide if
5170 files are up-to-date.)
5171 When using timestamp source signatures, Value Nodes'
5172 timestamps are equal to the system time when the Node is created.
5174 The returned Value Node object has a
5176 method that can be used to "build" a Value Node
5177 by setting a new value.
5180 argument can be specified
5181 when the Value Node is created
5182 to indicate the Node should already be considered
5184 There is a corresponding
5186 method that will return the built value of the Node.
5193 def create(target, source, env):
5194 # A function that will write a 'prefix=$SOURCE'
5195 # string into the file name specified as the
5197 f = open(str(target[0]), 'wb')
5198 f.write('prefix=' + source[0].get_contents())
5200 # Fetch the prefix= argument, if any, from the command
5201 # line, and use /usr/local as the default.
5202 prefix = ARGUMENTS.get('prefix', '/usr/local')
5204 # Attach a .Config() builder for the above function action
5205 # to the construction environment.
5206 env['BUILDERS']['Config'] = Builder(action = create)
5207 env.Config(target = 'package-config', source = Value(prefix))
5209 def build_value(target, source, env):
5210 # A function that "builds" a Python Value by updating
5211 # the the Python value with the contents of the file
5212 # specified as the source of the Builder call ($SOURCE).
5213 target[0].write(source[0].get_contents())
5215 output = env.Value('before')
5216 input = env.Value('after')
5218 # Attach a .UpdateValue() builder for the above function
5219 # action to the construction environment.
5220 env['BUILDERS']['UpdateValue'] = Builder(action = build_value)
5221 env.UpdateValue(target = Value(output), source = Value(input))
5224 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
5226 .RI WhereIs( program ", [" path ", " pathext ", " reject ])
5228 .RI env.WhereIs( program ", [" path ", " pathext ", " reject ])
5230 Searches for the specified executable
5232 returning the full path name to the program
5234 and returning None if not.
5235 Searches the specified
5237 the value of the calling environment's PATH
5238 (env['ENV']['PATH']),
5239 or the user's current external PATH
5240 (os.environ['PATH'])
5242 On Windows systems, searches for executable
5243 programs with any of the file extensions
5244 listed in the specified
5246 the calling environment's PATHEXT
5247 (env['ENV']['PATHEXT'])
5248 or the user's current PATHEXT
5249 (os.environ['PATHEXT'])
5257 .SS SConscript Variables
5258 In addition to the global functions and methods,
5260 supports a number of Python variables
5261 that can be used in SConscript files
5262 to affect how you want the build to be performed.
5263 These variables may be accessed from custom Python modules that you
5264 import into an SConscript file by adding the following
5265 to the Python module:
5268 from SCons.Script import *
5271 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
5276 arguments specified on the command line.
5277 Each element in the list is a tuple
5279 .RI ( keyword , value )
5285 elements of the tuple
5287 subscripting for element
5291 of the tuple, respectively.
5296 print "first keyword, value =", ARGLIST[0][0], ARGLIST[0][1]
5297 print "second keyword, value =", ARGLIST[1][0], ARGLIST[1][1]
5298 third_tuple = ARGLIST[2]
5299 print "third keyword, value =", third_tuple[0], third_tuple[1]
5300 for key, value in ARGLIST:
5301 # process key and value
5304 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
5307 A dictionary of all the
5309 arguments specified on the command line.
5310 The dictionary is not in order,
5311 and if a given keyword has
5312 more than one value assigned to it
5313 on the command line,
5314 the last (right-most) value is
5322 if ARGUMENTS.get('debug', 0):
5323 env = Environment(CCFLAGS = '-g')
5328 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
5331 A list of the targets which
5333 will actually try to build,
5334 regardless of whether they were specified on
5335 the command line or via the
5338 The elements of this list may be strings
5340 nodes, so you should run the list through the Python
5342 function to make sure any Node path names
5343 are converted to strings.
5345 Because this list may be taken from the
5346 list of targets specified using the
5349 the contents of the list may change
5350 on each successive call to
5355 for additional information.
5360 if 'foo' in BUILD_TARGETS:
5361 print "Don't forget to test the `foo' program!"
5362 if 'special/program' in BUILD_TARGETS:
5363 SConscript('special')
5368 list only contains targets expected listed
5369 on the command line or via calls to the
5374 contain all dependent targets that will be built as
5375 a result of making the sure the explicitly-specified
5376 targets are up to date.
5378 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
5380 COMMAND_LINE_TARGETS
5381 A list of the targets explicitly specified on
5383 If there are no targets specified on the command line,
5385 This can be used, for example,
5386 to take specific actions only
5387 when a certain target or targets
5388 is explicitly being built.
5393 if 'foo' in COMMAND_LINE_TARGETS:
5394 print "Don't forget to test the `foo' program!"
5395 if 'special/program' in COMMAND_LINE_TARGETS:
5396 SConscript('special')
5399 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
5402 A list of the target
5404 that have been specified using the
5407 The elements of the list are nodes,
5408 so you need to run them through the Python
5410 function to get at the path name for each Node.
5415 print str(DEFAULT_TARGETS[0])
5416 if 'foo' in map(str, DEFAULT_TARGETS):
5417 print "Don't forget to test the `foo' program!"
5422 list change on on each successive call to the
5427 print map(str, DEFAULT_TARGETS) # originally []
5429 print map(str, DEFAULT_TARGETS) # now a node ['foo']
5431 print map(str, DEFAULT_TARGETS) # now a node ['foo', 'bar']
5433 print map(str, DEFAULT_TARGETS) # back to []
5436 Consequently, be sure to use
5438 only after you've made all of your
5441 or else simply be careful of the order
5442 of these statements in your SConscript files
5443 so that you don't look for a specific
5444 default target before it's actually been added to the list.
5446 .SS Construction Variables
5447 .\" XXX From Gary Ruben, 23 April 2002:
5448 .\" I think it would be good to have an example with each construction
5449 .\" variable description in the documentation.
5451 .\" CC The C compiler
5452 .\" Example: env["CC"] = "c68x"
5453 .\" Default: env["CC"] = "cc"
5455 .\" CCCOM The command line ...
5457 .\" To generate the compiler line c68x -ps -qq -mr -o $TARGET $SOURCES
5458 .\" env["CC"] = "c68x"
5459 .\" env["CFLAGS"] = "-ps -qq -mr"
5460 .\" env["CCCOM"] = "$CC $CFLAGS -o $TARGET $SOURCES
5462 .\" (I dunno what this is ;-)
5463 A construction environment has an associated dictionary of
5464 .I construction variables
5465 that are used by built-in or user-supplied build rules.
5466 Construction variables must follow the same rules for
5468 the initial character must be an underscore or letter,
5469 followed by any number of underscores, letters, or digits.
5471 A number of useful construction variables are automatically defined by
5472 scons for each supported platform, and additional construction variables
5473 can be defined by the user. The following is a list of the automatically
5474 defined construction variables:
5476 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
5477 '\" BEGIN GENERATED CONSTRUCTION VARIABLE DESCRIPTIONS
5479 '\" The descriptions below of the various SCons contruction variables
5480 '\" are generated from the .xml files that live next to the various
5481 '\" Python modules in the build enginer library. If you're reading
5482 '\" this [gnt]roff file with an eye towards patching this man page,
5483 '\" you can still submit a diff against this text, but it will have to
5484 '\" be translated to a diff against the underlying .xml file before the
5485 '\" patch is actually accepted. If you do that yourself, it will make
5486 '\" it easier to integrate the patch.
5488 '\" BEGIN GENERATED CONSTRUCTION VARIABLE DESCRIPTIONS
5489 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
5491 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
5492 '\" END GENERATED CONSTRUCTION VARIABLE DESCRIPTIONS
5494 '\" The descriptions above of the various SCons contruction variables
5495 '\" are generated from the .xml files that live next to the various
5496 '\" Python modules in the build enginer library. If you're reading
5497 '\" this [gnt]roff file with an eye towards patching this man page,
5498 '\" you can still submit a diff against this text, but it will have to
5499 '\" be translated to a diff against the underlying .xml file before the
5500 '\" patch is actually accepted. If you do that yourself, it will make
5501 '\" it easier to integrate the patch.
5503 '\" END GENERATED CONSTRUCTION VARIABLE DESCRIPTIONS
5504 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
5507 Construction variables can be retrieved and set using the
5509 method of the construction environment:
5512 dict = env.Dictionary()
5516 or using the [] operator:
5522 Construction variables can also be passed to the construction environment
5526 env = Environment(CC="cc")
5529 or when copying a construction environment using the
5534 env2 = env.Clone(CC="cl.exe")
5537 .SS Configure Contexts
5541 .I configure contexts,
5542 an integrated mechanism similar to the
5543 various AC_CHECK macros in GNU autoconf
5544 for testing for the existence of C header
5545 files, libraries, etc.
5546 In contrast to autoconf,
5548 does not maintain an explicit cache of the tested values,
5549 but uses its normal dependency tracking to keep the checked values
5550 up to date. However, users may override this behaviour with the
5552 command line option.
5554 The following methods can be used to perform checks:
5557 .RI Configure( env ", [" custom_tests ", " conf_dir ", " log_file ", " config_h ])
5559 .RI env.Configure([ custom_tests ", " conf_dir ", " log_file ", " config_h ])
5560 This creates a configure context, which can be used to perform checks.
5562 specifies the environment for building the tests.
5563 This environment may be modified when performing checks.
5565 is a dictionary containing custom tests.
5566 See also the section about custom tests below.
5567 By default, no custom tests are added to the configure context.
5569 specifies a directory where the test cases are built.
5570 Note that this directory is not used for building
5572 The default value is the directory
5575 specifies a file which collects the output from commands
5576 that are executed to check for the existence of header files, libraries, etc.
5577 The default is the file #/config.log.
5578 If you are using the
5581 you may want to specify a subdirectory under your build directory.
5583 specifies a C header file where the results of tests
5584 will be written, e.g. #define HAVE_STDIO_H, #define HAVE_LIBM, etc.
5585 The default is to not write a
5588 You can specify the same
5590 file in multiple calls to Configure,
5593 will concatenate all results in the specified file.
5595 uses its normal dependency checking
5596 to decide if it's necessary to rebuild
5600 This means that the file is not necessarily re-built each
5602 but is only rebuilt if its contents will have changed
5603 and some target that depends on the
5605 file is being built.
5610 instance has the following associated methods:
5613 .RI Configure.Finish( self )
5614 This method should be called after configuration is done.
5615 It returns the environment as modified
5616 by the configuration checks performed.
5617 After this method is called, no further checks can be performed
5618 with this configuration context.
5619 However, you can create a new
5621 context to perform additional checks.
5622 Only one context should be active at a time.
5624 The following Checks are predefined.
5625 (This list will likely grow larger as time
5626 goes by and developers contribute new useful tests.)
5629 .RI Configure.CheckHeader( self ", " header ", [" include_quotes ", " language ])
5632 is usable in the specified language.
5635 in which case the last item in the list
5636 is the header file to be checked,
5637 and the previous list items are
5640 lines should precede the
5641 header line being checked for.
5642 The optional argument
5645 a two character string, where the first character denotes the opening
5646 quote and the second character denotes the closing quote.
5647 By default, both characters are " (double quote).
5648 The optional argument
5654 and selects the compiler to be used for the check.
5655 Returns 1 on success and 0 on failure.
5658 .RI Configure.CheckCHeader( self ", " header ", [" include_quotes ])
5659 This is a wrapper around
5660 .B Configure.CheckHeader
5663 is usable in the C language.
5666 in which case the last item in the list
5667 is the header file to be checked,
5668 and the previous list items are
5671 lines should precede the
5672 header line being checked for.
5673 The optional argument
5676 a two character string, where the first character denotes the opening
5677 quote and the second character denotes the closing quote (both default
5679 Returns 1 on success and 0 on failure.
5682 .RI Configure.CheckCXXHeader( self ", " header ", [" include_quotes ])
5683 This is a wrapper around
5684 .B Configure.CheckHeader
5687 is usable in the C++ language.
5690 in which case the last item in the list
5691 is the header file to be checked,
5692 and the previous list items are
5695 lines should precede the
5696 header line being checked for.
5697 The optional argument
5700 a two character string, where the first character denotes the opening
5701 quote and the second character denotes the closing quote (both default
5703 Returns 1 on success and 0 on failure.
5706 .RI Configure.CheckFunc( self ", " function_name ", [" header ", " language ])
5707 Checks if the specified
5708 C or C++ function is available.
5710 is the name of the function to check for.
5713 argument is a string
5717 that will be compiled
5718 to check if the function exists;
5724 char function_name();
5732 and selects the compiler to be used for the check;
5736 .RI Configure.CheckLib( self ", [" library ", " symbol ", " header ", " language ", " autoadd=1 ])
5743 is 1 and the library provides the specified
5745 appends the library to the LIBS construction environment variable.
5747 may also be None (the default),
5750 is checked with the current LIBS variable,
5751 or a list of library names,
5752 in which case each library in the list
5760 .BR Configure.CheckLib ()
5762 you can link against the specified
5770 and selects the compiler to be used for the check;
5772 The default value for
5775 This method returns 1 on success and 0 on error.
5778 .RI Configure.CheckLibWithHeader( self ", " library ", " header ", " language ", [" call ", " autoadd ])
5781 .RI Configure.CheckLib
5782 call, this call provides a more sophisticated way to check against libraries.
5785 specifies the library or a list of libraries to check.
5787 specifies a header to check for.
5790 in which case the last item in the list
5791 is the header file to be checked,
5792 and the previous list items are
5795 lines should precede the
5796 header line being checked for.
5798 may be one of 'C','c','CXX','cxx','C++' and 'c++'.
5800 can be any valid expression (with a trailing ';').
5804 the default simply checks that you
5805 can link against the specified
5808 specifies whether to add the library to the environment (only if the check
5809 succeeds). This method returns 1 on success and 0 on error.
5812 .RI Configure.CheckType( self ", " type_name ", [" includes ", " language ])
5813 Checks for the existence of a type defined by
5816 specifies the typedef name to check for.
5818 is a string containing one or more
5820 lines that will be inserted into the program
5821 that will be run to test for the existence of the type.
5828 and selects the compiler to be used for the check;
5832 Example of a typical Configure usage:
5836 conf = Configure( env )
5837 if not conf.CheckCHeader( 'math.h' ):
5838 print 'We really need math.h!'
5840 if conf.CheckLibWithHeader( 'qt', 'qapp.h', 'c++', 'QApplication qapp(0,0);' ):
5841 # do stuff for qt - usage, e.g.
5842 conf.env.Append( CPPFLAGS = '-DWITH_QT' )
5847 You can define your own custom checks.
5848 in addition to the predefined checks.
5849 These are passed in a dictionary to the Configure function.
5850 This dictionary maps the names of the checks
5851 to user defined Python callables
5852 (either Python functions or class instances implementing the
5855 The first argument of the call is always a
5857 instance followed by the arguments,
5858 which must be supplied by the user of the check.
5859 These CheckContext instances define the following methods:
5862 .RI CheckContext.Message( self ", " text )
5864 Usually called before the check is started.
5866 will be displayed to the user, e.g. 'Checking for library X...'
5869 .RI CheckContext.Result( self, ", " res )
5871 Usually called after the check is done.
5873 can be either an integer or a string. In the former case, 'ok' (res != 0)
5874 or 'failed' (res == 0) is displayed to the user, in the latter case the
5875 given string is displayed.
5878 .RI CheckContext.TryCompile( self ", " text ", " extension )
5879 Checks if a file with the specified
5881 (e.g. '.c') containing
5883 can be compiled using the environment's
5885 builder. Returns 1 on success and 0 on failure.
5888 .RI CheckContext.TryLink( self ", " text ", " extension )
5889 Checks, if a file with the specified
5891 (e.g. '.c') containing
5893 can be compiled using the environment's
5895 builder. Returns 1 on success and 0 on failure.
5898 .RI CheckContext.TryRun( self ", " text ", " extension )
5899 Checks, if a file with the specified
5901 (e.g. '.c') containing
5903 can be compiled using the environment's
5905 builder. On success, the program is run. If the program
5906 executes successfully
5907 (that is, its return status is 0),
5912 is the standard output of the
5914 If the program fails execution
5915 (its return status is non-zero),
5916 then (0, '') is returned.
5919 .RI CheckContext.TryAction( self ", " action ", [" text ", " extension ])
5920 Checks if the specified
5922 with an optional source file (contents
5929 may be anything which can be converted to a
5936 is the content of the target file.
5942 .RI CheckContext.TryBuild( self ", " builder ", [" text ", " extension ])
5943 Low level implementation for testing specific builds;
5944 the methods above are based on this method.
5945 Given the Builder instance
5949 of a source file with optional
5951 this method returns 1 on success and 0 on failure. In addition,
5953 is set to the build target node, if the build was successful.
5956 Example for implementing and using custom tests:
5959 def CheckQt(context, qtdir):
5960 context.Message( 'Checking for qt ...' )
5961 lastLIBS = context.env['LIBS']
5962 lastLIBPATH = context.env['LIBPATH']
5963 lastCPPPATH= context.env['CPPPATH']
5964 context.env.Append(LIBS = 'qt', LIBPATH = qtdir + '/lib', CPPPATH = qtdir + '/include' )
5965 ret = context.TryLink("""
5967 int main(int argc, char **argv) {
5968 QApplication qapp(argc, argv);
5973 context.env.Replace(LIBS = lastLIBS, LIBPATH=lastLIBPATH, CPPPATH=lastCPPPATH)
5974 context.Result( ret )
5978 conf = Configure( env, custom_tests = { 'CheckQt' : CheckQt } )
5979 if not conf.CheckQt('/usr/lib/qt'):
5980 print 'We really need qt!'
5985 .SS Construction Variable Options
5987 Often when building software, various options need to be specified at build
5988 time that are not known when the SConstruct/SConscript files are
5989 written. For example, libraries needed for the build may be in non-standard
5990 locations, or site-specific compiler options may need to be passed to the
5993 provides a mechanism for overridding construction variables from the
5994 command line or a text-based SConscript file through an Options
5995 object. To create an Options object, call the Options() function:
5998 .RI Options([ files "], [" args ])
5999 This creates an Options object that will read construction variables from
6000 the file or list of filenames specified in
6002 If no files are specified,
6007 then no files will be read.
6008 The optional argument
6011 values that will override anything read from the specified files;
6012 it is primarily intended to be passed the
6014 dictionary that holds variables
6015 specified on the command line.
6019 opts = Options('custom.py')
6020 opts = Options('overrides.py', ARGUMENTS)
6021 opts = Options(None, {FOO:'expansion', BAR:7})
6024 Options objects have the following methods:
6027 .RI Add( key ", [" help ", " default ", " validator ", " converter ])
6028 This adds a customizable construction variable to the Options object.
6030 is the name of the variable.
6032 is the help text for the variable.
6034 is the default value of the variable;
6035 if the default value is
6037 and there is no explicit value specified,
6038 the construction variable will
6040 be added to the construction environment.
6042 is called to validate the value of the variable, and should take three
6043 arguments: key, value, and environment.
6044 The recommended way to handle an invalid value is
6045 to raise an exception (see example below).
6047 is called to convert the value before putting it in the environment, and
6048 should take either a value, or the value and environment, as parameters.
6051 must return a value,
6052 which will be converted into a string
6053 before being validated by the
6056 and then added to the environment.
6061 opts.Add('CC', 'The C compiler')
6063 def validate_color(key, val, env):
6064 if not val in ['red', 'blue', 'yellow']:
6065 raise "Invalid color value '%s'" % val
6066 opts.Add('COLOR', validator=valid_color)
6070 .RI AddOptions( list )
6071 A wrapper script that adds
6072 multiple customizable construction variables
6073 to an Options object.
6075 is a list of tuple or list objects
6076 that contain the arguments
6077 for an individual call to the
6084 ('CC', 'The C compiler'),
6085 ('VALIDATE', 'An option for testing validation',
6086 'notset', validator, None),
6091 .RI Update( env ", [" args ])
6092 This updates a construction environment
6094 with the customized construction variables. Normally this method is not
6095 called directly, but is called indirectly by passing the Options object to
6096 the Environment() function:
6099 env = Environment(options=opts)
6103 The text file(s) that were specified
6104 when the Options object was created
6105 are executed as Python scripts,
6106 and the values of (global) Python variables set in the file
6107 are added to the construction environment.
6115 .RI Save( filename ", " env )
6116 This saves the currently set options into a script file named
6118 that can be used on the next invocation to automatically load the current
6119 settings. This method combined with the Options method can be used to
6120 support caching of options between runs.
6124 opts = Options(['options.cache', 'custom.py'])
6127 opts.Save('options.cache', env)
6131 .RI GenerateHelpText( env ", [" sort ])
6132 This generates help text documenting the customizable construction
6133 variables suitable to passing in to the Help() function.
6135 is the construction environment that will be used to get the actual values
6136 of customizable variables. Calling with
6140 will cause the output to be sorted
6141 by the specified argument.
6145 should take two arguments
6148 (like the standard Python
6153 Help(opts.GenerateHelpText(env))
6154 Help(opts.GenerateHelpText(env, sort=cmp))
6158 .RI FormatOptionHelpText( env ", " opt ", " help ", " default ", " actual )
6159 This method returns a formatted string
6160 containing the printable help text
6162 It is normally not called directly,
6163 but is called by the
6164 .IR GenerateHelpText ()
6165 method to create the returned help text.
6166 It may be overridden with your own
6167 function that takes the arguments specified above
6168 and returns a string of help text formatted to your liking.
6170 .IR GenerateHelpText ()
6171 will not put any blank lines or extra
6172 characters in between the entries,
6173 so you must add those characters to the returned
6174 string if you want the entries separated.
6177 def my_format(env, opt, help, default, actual):
6178 fmt = "\n%s: default=%s actual=%s (%s)\n"
6179 return fmt % (opt, default. actual, help)
6180 opts.FormatOptionHelpText = my_format
6183 To make it more convenient to work with customizable Options,
6185 provides a number of functions
6186 that make it easy to set up
6187 various types of Options:
6190 .RI BoolOption( key ", " help ", " default )
6191 Return a tuple of arguments
6192 to set up a Boolean option.
6196 have a default value of
6198 and display the specified
6201 The option will interpret the values
6223 .RI EnumOption( key ", " help ", " default ", " allowed_values ", [" map ", " ignorecase ])
6224 Return a tuple of arguments
6226 whose value may be one
6227 of a specified list of legal enumerated values.
6231 have a default value of
6233 and display the specified
6236 The option will only support those
6242 argument is a dictionary
6243 that can be used to convert
6244 input values into specific legal values
6253 then the values are case-sensitive.
6258 then values will be matched
6264 then values will be matched
6266 and all input values will be
6267 converted to lower case.
6270 .RI ListOption( key ", " help ", " default ", " names ", [", map ])
6271 Return a tuple of arguments
6273 whose value may be one or more
6274 of a specified list of legal enumerated values.
6278 have a default value of
6280 and display the specified
6283 The option will only support the values
6286 or the values in the
6289 More than one value may be specified,
6290 with all values separated by commas.
6291 The default may be a string of
6292 comma-separated default values,
6293 or a list of the default values.
6296 argument is a dictionary
6297 that can be used to convert
6298 input values into specific legal values
6304 .RI PackageOption( key ", " help ", " default )
6305 Return a tuple of arguments
6307 whose value is a path name
6308 of a package that may be
6309 enabled, disabled or
6310 given an explicit path name.
6314 have a default value of
6316 and display the specified
6319 The option will support the values
6326 in which case the specified
6329 or the option may be set to an
6331 (typically the path name to a package
6332 that is being enabled).
6333 The option will also support the values
6339 to disable use of the specified option.
6342 .RI PathOption( key ", " help ", " default ", [" validator ])
6343 Return a tuple of arguments
6345 whose value is expected to be a path name.
6349 have a default value of
6351 and display the specified
6357 that will be called to
6358 verify that the specified path
6361 following ready-made validators:
6362 .BR PathOption.PathExists
6364 which verifies that the specified path exists;
6365 .BR PathOption.PathIsFile ,
6366 which verifies that the specified path is an existing file;
6367 .BR PathOption.PathIsDir ,
6368 which verifies that the specified path is an existing directory;
6369 .BR PathOption.PathIsDirCreate ,
6370 which verifies that the specified path is a directory
6371 and will create the specified directory if the path does not exist;
6373 .BR PathOption.PathAccept ,
6374 which simply accepts the specific path name argument without validation,
6375 and which is suitable if you want your users
6376 to be able to specify a directory path that will be
6377 created as part of the build process, for example.
6378 You may supply your own
6381 which must take three arguments
6383 the name of the options variable to be set;
6385 the specified value being checked;
6388 the construction environment)
6389 and should raise an exception
6390 if the specified value is not acceptable.
6393 These functions make it
6394 convenient to create a number
6395 of options with consistent behavior
6396 in a single call to the
6402 BoolOption('warnings', 'compilation with -Wall and similiar', 1),
6403 EnumOption('debug', 'debug output and symbols', 'no'
6404 allowed_values=('yes', 'no', 'full'),
6405 map={}, ignorecase=0), # case sensitive
6406 ListOption('shared',
6407 'libraries to build as shared libraries',
6409 names = list_of_libs),
6410 PackageOption('x11',
6411 'use X11 installed here (yes = search some places)',
6413 PathOption('qtdir', 'where the root of Qt is installed', qtdir),
6414 PathOption('foopath', 'where the foo library is installed', foopath,
6415 PathOption.PathIsDir),
6420 .SS File and Directory Nodes
6430 Nodes, respectively.
6431 python objects, respectively.
6432 Those objects have several user-visible attributes
6433 and methods that are often useful:
6439 This path is relative to the top-level directory
6443 The build path is the same as the source path if
6448 The absolute build path of the given file or directory.
6458 object representing the
6467 # Get the current build dir's path, relative to top.
6469 # Current dir's absolute path
6471 # Next line is always '.', because it is the top dir's path relative to itself.
6473 File('foo.c').srcnode().path # source path of the given source file.
6475 # Builders also return File objects:
6476 foo = env.Program('foo.c')
6477 print "foo will be built in %s"%foo.path
6483 can be extended to build different types of targets
6484 by adding new Builder objects
6485 to a construction environment.
6487 you should only need to add a new Builder object
6488 when you want to build a new type of file or other external target.
6489 If you just want to invoke a different compiler or other tool
6490 to build a Program, Object, Library, or any other
6491 type of output file for which
6493 already has an existing Builder,
6494 it is generally much easier to
6495 use those existing Builders
6496 in a construction environment
6497 that sets the appropriate construction variables
6500 Builder objects are created
6506 function accepts the following arguments:
6509 The command line string used to build the target from the source.
6512 a list of strings representing the command
6513 to be executed and its arguments
6514 (suitable for enclosing white space in an argument),
6516 mapping source file name suffixes to
6517 any combination of command line strings
6518 (if the builder should accept multiple source file extensions),
6521 (see the next section);
6522 or a list of any of the above.
6525 takes three arguments:
6527 - a list of source nodes,
6529 - a list of target nodes,
6531 - the construction environment.
6534 The prefix that will be prepended to the target file name.
6535 This may be specified as a:
6545 - a function or other callable that takes
6546 two arguments (a construction environment and a list of sources)
6547 and returns a prefix,
6552 - specifies a mapping from a specific source suffix (of the first
6553 source specified) to a corresponding target prefix. Both the source
6554 suffix and target prefix specifications may use environment variable
6555 substitution, and the target prefix (the 'value' entries in the
6556 dictionary) may also be a callable object. The default target prefix
6557 may be indicated by a dictionary entry with a key value of None.
6562 b = Builder("build_it < $SOURCE > $TARGET"
6565 def gen_prefix(env, sources):
6566 return "file-" + env['PLATFORM'] + '-'
6567 b = Builder("build_it < $SOURCE > $TARGET",
6568 prefix = gen_prefix)
6570 b = Builder("build_it < $SOURCE > $TARGET",
6571 suffix = { None: "file-",
6572 "$SRC_SFX_A": gen_prefix })
6576 The suffix that will be appended to the target file name.
6577 This may be specified in the same manner as the prefix above.
6578 If the suffix is a string, then
6580 will append a '.' to the beginning of the suffix if it's not already
6581 there. The string returned by callable object (or obtained from the
6582 dictionary) is untouched and must append its own '.' to the beginning
6586 b = Builder("build_it < $SOURCE > $TARGET"
6589 def gen_suffix(env, sources):
6590 return "." + env['PLATFORM'] + "-file"
6591 b = Builder("build_it < $SOURCE > $TARGET",
6592 suffix = gen_suffix)
6594 b = Builder("build_it < $SOURCE > $TARGET",
6595 suffix = { None: ".sfx1",
6596 "$SRC_SFX_A": gen_suffix })
6600 When set to any true value, causes
6602 to add the target suffix specified by the
6604 keyword to any target strings
6605 that have a different suffix.
6606 (The default behavior is to leave untouched
6607 any target file name that looks like it already has any suffix.)
6610 b1 = Builder("build_it < $SOURCE > $TARGET"
6612 b2 = Builder("build_it < $SOURCE > $TARGET"
6616 env['BUILDERS']['B1'] = b1
6617 env['BUILDERS']['B2'] = b2
6619 # Builds "foo.txt" because ensure_suffix is not set.
6620 env.B1('foo.txt', 'foo.in')
6622 # Builds "bar.txt.out" because ensure_suffix is set.
6623 env.B2('bar.txt', 'bar.in')
6627 The expected source file name suffix. This may be a string or a list
6631 A Scanner object that
6632 will be invoked to find
6633 implicit dependencies for this target file.
6634 This keyword argument should be used
6635 for Scanner objects that find
6636 implicit dependencies
6637 based only on the target file
6638 and the construction environment,
6641 (See the section "Scanner Objects," below,
6642 for information about creating Scanner objects.)
6645 A Scanner object that
6647 find implicit dependences in
6649 used to build this target file.
6650 This is where you would
6651 specify a scanner to
6654 lines in source files.
6657 Scanner object may be used to
6658 indicate that this Builder
6659 should scan directory trees
6660 for on-disk changes to files
6663 does not know about from other Builder or function calls.
6664 (See the section "Scanner Objects," below,
6665 for information about creating your own Scanner objects.)
6668 A factory function that the Builder will use
6669 to turn any targets specified as strings into SCons Nodes.
6671 SCons assumes that all targets are files.
6672 Other useful target_factory
6675 for when a Builder creates a directory target,
6678 for when a Builder can create either a file
6679 or directory target.
6684 MakeDirectoryBuilder = Builder(action=my_mkdir, target_factory=Dir)
6686 env.Append(BUILDERS = {'MakeDirectory':MakeDirectoryBuilder})
6687 env.MakeDirectory('new_directory', [])
6691 Note that the call to the MakeDirectory Builder
6692 needs to specify an empty source list
6693 to make the string represent the builder's target;
6694 without that, it would assume the argument is the source,
6695 and would try to deduce the target name from it,
6696 which in the absence of an automatically-added prefix or suffix
6697 would lead to a matching target and source name
6698 and a circular dependency.
6701 A factory function that the Builder will use
6702 to turn any sources specified as strings into SCons Nodes.
6704 SCons assumes that all source are files.
6705 Other useful source_factory
6708 for when a Builder uses a directory as a source,
6711 for when a Builder can use files
6712 or directories (or both) as sources.
6717 CollectBuilder = Builder(action=my_mkdir, source_factory=Entry)
6719 env.Append(BUILDERS = {'Collect':CollectBuilder})
6720 env.Collect('archive', ['directory_name', 'file_name'])
6724 A function or list of functions to manipulate the target and source
6725 lists before dependencies are established
6726 and the target(s) are actually built.
6728 can also be a string containing a construction variable to expand
6729 to an emitter function or list of functions,
6730 or a dictionary mapping source file suffixes
6731 to emitter functions.
6732 (Only the suffix of the first source file
6733 is used to select the actual emitter function
6734 from an emitter dictionary.)
6737 takes three arguments:
6739 - a list of source nodes,
6741 - a list of target nodes,
6743 - the construction environment.
6744 An emitter must return a tuple containing two lists,
6745 the list of targets to be built by this builder,
6746 and the list of sources for this builder.
6751 def e(target, source, env):
6752 return (target + ['foo.foo'], source + ['foo.src'])
6754 # Simple association of an emitter function with a Builder.
6755 b = Builder("my_build < $TARGET > $SOURCE",
6758 def e2(target, source, env):
6759 return (target + ['bar.foo'], source + ['bar.src'])
6761 # Simple association of a list of emitter functions with a Builder.
6762 b = Builder("my_build < $TARGET > $SOURCE",
6765 # Calling an emitter function through a construction variable.
6766 env = Environment(MY_EMITTER = e)
6767 b = Builder("my_build < $TARGET > $SOURCE",
6768 emitter = '$MY_EMITTER')
6770 # Calling a list of emitter functions through a construction variable.
6771 env = Environment(EMITTER_LIST = [e, e2])
6772 b = Builder("my_build < $TARGET > $SOURCE",
6773 emitter = '$EMITTER_LIST')
6775 # Associating multiple emitters with different file
6776 # suffixes using a dictionary.
6777 def e_suf1(target, source, env):
6778 return (target + ['another_target_file'], source)
6779 def e_suf2(target, source, env):
6780 return (target, source + ['another_source_file'])
6781 b = Builder("my_build < $TARGET > $SOURCE",
6782 emitter = {'.suf1' : e_suf1,
6787 Specifies whether this builder is allowed to be called multiple times for
6788 the same target file(s). The default is 0, which means the builder
6789 can not be called multiple times for the same target file(s). Calling a
6790 builder multiple times for the same target simply adds additional source
6791 files to the target; it is not allowed to change the environment associated
6792 with the target, specify addition environment overrides, or associate a different
6793 builder with the target.
6796 A construction environment that can be used
6797 to fetch source code using this Builder.
6798 (Note that this environment is
6800 used for normal builds of normal target files,
6801 which use the environment that was
6802 used to call the Builder for the target file.)
6805 A function that returns a list of actions that will be executed to build
6806 the target(s) from the source(s).
6807 The returned action(s) may be
6808 an Action object, or anything that
6809 can be converted into an Action object
6810 (see the next section).
6812 The generator function
6813 takes four arguments:
6815 - a list of source nodes,
6817 - a list of target nodes,
6819 - the construction environment,
6821 - a Boolean value that specifies
6822 whether the generator is being called
6823 for generating a build signature
6824 (as opposed to actually executing the command).
6828 def g(source, target, env, for_signature):
6829 return [["gcc", "-c", "-o"] + target + source]
6831 b = Builder(generator=g)
6839 arguments must not both be used for the same Builder.
6842 Specifies a builder to use when a source file name suffix does not match
6843 any of the suffixes of the builder. Using this argument produces a
6844 multi-stage builder.
6847 Specifies that this builder expects exactly one source file per call. Giving
6848 more than one source files without target files results in implicitely calling
6849 the builder multiple times (once for each source given). Giving multiple
6850 source files together with target files results in a UserError exception.
6858 arguments must not both be used for the same Builder.
6860 .IP source_ext_match
6863 argument is a dictionary,
6864 the default behavior when a builder is passed
6865 multiple source files is to make sure that the
6866 extensions of all the source files match.
6867 If it is legal for this builder to be
6868 called with a list of source files with different extensions,
6869 this check can be suppressed by setting
6873 or some other non-true value.
6878 will use the suffix of the first specified
6879 source file to select the appropriate action from the
6883 In the following example,
6888 from exiting with an error
6889 due to the mismatched suffixes of
6895 b = Builder(action={'.in' : 'build $SOURCES > $TARGET'},
6896 source_ext_match = None)
6898 env = Environment(BUILDERS = {'MyBuild':b})
6899 env.MyBuild('foo.out', ['foo.in', 'foo.extra'])
6903 A construction environment that can be used
6904 to fetch source code using this Builder.
6905 (Note that this environment is
6907 used for normal builds of normal target files,
6908 which use the environment that was
6909 used to call the Builder for the target file.)
6912 b = Builder(action="build < $SOURCE > $TARGET")
6913 env = Environment(BUILDERS = {'MyBuild' : b})
6914 env.MyBuild('foo.out', 'foo.in', my_arg = 'xyzzy')
6918 A directory from which scons
6925 a string or a directory Node,
6926 scons will change to the specified directory.
6929 is not a string or Node
6931 then scons will change to the
6932 target file's directory.
6934 Note that scons will
6936 automatically modify
6938 construction variables like
6942 when using the chdir
6943 keyword argument--that is,
6944 the expanded file names
6945 will still be relative to
6946 the top-level SConstruct directory,
6947 and consequently incorrect
6948 relative to the chdir directory.
6949 Builders created using chdir keyword argument,
6950 will need to use construction variable
6955 to use just the filename portion of the
6959 b = Builder(action="build < ${SOURCE.file} > ${TARGET.file}",
6961 env = Environment(BUILDERS = {'MyBuild' : b})
6962 env.MyBuild('sub/dir/foo.out', 'sub/dir/foo.in')
6966 Python only keeps one current directory
6967 location for all of the threads.
6968 This means that use of the
6976 because individual worker threads spawned
6977 by SCons interfere with each other
6978 when they start changing directory.
6981 Any additional keyword arguments supplied
6982 when a Builder object is created
6983 (that is, when the Builder() function is called)
6984 will be set in the executing construction
6985 environment when the Builder object is called.
6986 The canonical example here would be
6987 to set a construction variable to
6988 the repository of a source code system.
6990 Any additional keyword arguments supplied
6994 will only be associated with the target
6995 created by that particular Builder call
6996 (and any other files built as a
6997 result of the call).
6999 These extra keyword arguments are passed to the
7000 following functions:
7001 command generator functions,
7003 and emitter functions.
7009 function will turn its
7011 keyword argument into an appropriate
7012 internal Action object.
7013 You can also explicity create Action objects
7017 which can then be passed to the
7020 This can be used to configure
7021 an Action object more flexibly,
7022 or it may simply be more efficient
7023 than letting each separate Builder object
7024 create a separate Action
7026 Builder objects need to do the same thing.
7031 returns an appropriate object for the action
7032 represented by the type of the first argument:
7035 If the first argument is already an Action object,
7036 the object is simply returned.
7039 If the first argument is a string,
7040 a command-line Action is returned.
7041 Note that the command line string
7042 may be preceded by an
7045 to suppress printing of the
7046 specified command line,
7050 to ignore the exit status from
7051 the specified command.
7055 Action('$CC -c -o $TARGET $SOURCES')
7057 # Doesn't print the line being executed.
7058 Action('@build $TARGET $SOURCES')
7061 Action('-build $TARGET $SOURCES')
7064 .\" XXX From Gary Ruben, 23 April 2002:
7065 .\" What would be useful is a discussion of how you execute command
7066 .\" shell commands ie. what is the process used to spawn the shell, pass
7067 .\" environment variables to it etc., whether there is one shell per
7068 .\" environment or one per command etc. It might help to look at the Gnu
7069 .\" make documentation to see what they think is important to discuss about
7070 .\" a build system. I'm sure you can do a better job of organising the
7071 .\" documentation than they have :-)
7075 If the first argument is a list,
7076 then a list of Action objects is returned.
7077 An Action object is created as necessary
7078 for each element in the list.
7081 the list is itself a list,
7082 the internal list is the
7083 command and arguments to be executed via
7085 This allows white space to be enclosed
7086 in an argument by defining
7087 a command in a list within a list:
7090 Action([['cc', '-c', '-DWHITE SPACE', '-o', '$TARGET', '$SOURCES']])
7094 If the first argument is a Python function,
7095 a function Action is returned.
7096 The Python function takes three keyword arguments,
7098 (a Node object representing the target file),
7100 (a Node object representing the source file)
7103 (the construction environment
7104 used for building the target file).
7109 arguments may be lists of Node objects if there is
7110 more than one target file or source file.
7111 The actual target and source file name(s) may
7112 be retrieved from their Node objects
7113 via the built-in Python str() function:
7116 target_file_name = str(target)
7117 source_file_names = map(lambda x: str(x), source)
7120 The function should return
7124 to indicate a successful build of the target file(s).
7125 The function may raise an exception
7126 or return a non-zero exit status
7127 to indicate an unsuccessful build.
7130 def build_it(target = None, source = None, env = None):
7131 # build the target from the source
7134 a = Action(build_it)
7137 If the action argument is not one of the above,
7141 The second, optional argument
7142 is used to define the output which is printed
7143 when the Action is actually performed.
7144 In the absence of this parameter, or if it's an
7145 empty string, a default output depending on the type of the action
7146 is used. For example, a command-line action will print
7147 the executed command. The argument is either a python function
7150 In the first case, it's a function that returns
7151 a string to be printed to describe the action being executed.
7152 Like a function to build a file,
7153 this function takes three arguments:
7155 (a Node object representing the target file),
7157 (a Node object representing the source file)
7160 (a construction environment).
7165 arguments may be lists of Node objects if there is
7166 more than one target file or source file.
7168 In the second case, you provide the string itself.
7169 The string typically contains variables, notably
7170 $TARGET(S) and $SOURCE(S), or consists of just a single
7171 variable, which is optionally defined somewhere else.
7172 SCons itself heavily uses the latter variant.
7177 def build_it(target, source, env):
7178 # build the target from the source
7181 def string_it(target, source, env):
7182 return "building '%s' from '%s'" % (target[0], source[0])
7184 # Use a positional argument.
7185 f = Action(build_it, string_it)
7186 s = Action(build_it, "building '$TARGET' from '$SOURCE'")
7188 # Alternatively, use a keyword argument.
7189 f = Action(build_it, strfunction=string_it)
7190 s = Action(build_it, cmdstr="building '$TARGET' from '$SOURCE'")
7192 # You can provide a configurable variable.
7193 l = Action(build_it, '$STRINGIT')
7196 The third, also optional argument
7197 is a list of construction variables
7198 whose values will be included
7199 in the signature of the Action
7200 when deciding whether a target should
7201 be rebuilt because the action changed.
7202 This is necessary whenever you want a target to
7203 be rebuilt when a specific
7204 construction variable changes,
7205 because the underlying Python code for a function
7206 will not change when the value of the construction variable does.
7209 def build_it(target, source, env):
7210 # build the target from the 'XXX' construction variable
7211 open(target[0], 'w').write(env['XXX'])
7214 # Use positional arguments.
7215 a = Action(build_it, '$STRINGIT', ['XXX'])
7217 # Alternatively, use a keyword argument.
7218 a = Action(build_it, varlist=['XXX'])
7227 which specifies that
7228 scons will execute the action
7229 after changing to the specified directory.
7230 If the chdir argument is
7231 a string or a directory Node,
7232 scons will change to the specified directory.
7233 If the chdir argument
7234 is not a string or Node
7236 then scons will change to the
7237 target file's directory.
7239 Note that scons will
7241 automatically modify
7243 construction variables like
7247 when using the chdir
7248 keyword argument--that is,
7249 the expanded file names
7250 will still be relative to
7251 the top-level SConstruct directory,
7252 and consequently incorrect
7253 relative to the chdir directory.
7254 Builders created using chdir keyword argument,
7255 will need to use construction variable
7260 to use just the filename portion of the
7264 a = Action("build < ${SOURCE.file} > ${TARGET.file}",
7274 which specifies a function
7275 that is passed the exit status
7277 from the specified action
7278 and can return an arbitrary
7280 This can be used, for example,
7281 to specify that an Action object's
7282 return value should be ignored
7283 and SCons should, therefore,
7284 consider that the action always suceeds:
7287 def always_succeed(s):
7288 # Always return 0, which indicates success.
7290 a = Action("build < ${SOURCE.file} > ${TARGET.file}",
7291 exitstatfunc=always_succeed)
7294 .SS Miscellaneous Action Functions
7297 supplies a number of functions
7298 that arrange for various common
7299 file and directory manipulations
7301 These are similar in concept to "tasks" in the
7303 although the implementation is slightly different.
7304 These functions do not actually
7305 perform the specified action
7306 at the time the function is called,
7307 but instead return an Action object
7308 that can be executed at the
7310 (In Object-Oriented terminology,
7315 that return Action objects.)
7318 there are two natural ways
7321 are intended to be used.
7325 to perform the action
7326 at the time the SConscript
7330 global function to do so:
7332 Execute(Touch('file'))
7336 you can use these functions
7337 to supply Actions in a list
7341 This can allow you to
7342 perform more complicated
7343 sequences of file manipulation
7345 on platform-specific
7349 env = Environment(TMPBUILD = '/tmp/builddir')
7350 env.Command('foo.out', 'foo.in',
7351 [Mkdir('$TMPBUILD'),
7352 Copy('$TMPBUILD', '${SOURCE.dir}'),
7353 "cd $TMPBUILD && make",
7354 Delete('$TMPBUILD')])
7358 .RI Chmod( dest ", " mode )
7359 Returns an Action object that
7360 changes the permissions on the specified
7362 file or directory to the specified
7367 Execute(Chmod('file', 0755))
7369 env.Command('foo.out', 'foo.in',
7370 [Copy('$TARGET', '$SOURCE'),
7371 Chmod('$TARGET', 0755)])
7375 .RI Copy( dest ", " src )
7376 Returns an Action object
7379 source file or directory to the
7381 destination file or directory.
7385 Execute(Copy('foo.output', 'foo.input'))
7387 env.Command('bar.out', 'bar.in',
7388 Copy('$TARGET', '$SOURCE'))
7392 .RI Delete( entry ", [" must_exist ])
7393 Returns an Action that
7394 deletes the specified
7396 which may be a file or a directory tree.
7397 If a directory is specified,
7398 the entire directory tree
7403 then a Python error will be thrown
7404 if the specified entry does not exist;
7407 that is, the Action will silently do nothing
7408 if the entry does not exist.
7412 Execute(Delete('/tmp/buildroot'))
7414 env.Command('foo.out', 'foo.in',
7415 [Delete('${TARGET.dir}'),
7418 Execute(Delete('file_that_must_exist', must_exist=1))
7424 that creates the specified
7430 Execute(Mkdir('/tmp/outputdir'))
7432 env.Command('foo.out', 'foo.in',
7433 [Mkdir('/tmp/builddir',
7434 Copy('$SOURCE', '/tmp/builddir')
7435 "cd /tmp/builddir && ])
7440 .RI Move( dest ", " src )
7442 that moves the specified
7444 file or directory to
7451 Execute(Move('file.destination', 'file.source'))
7453 env.Command('output_file', 'input_file',
7455 Move('$TARGET', 'file_created_by_MyBuildAction')])
7461 that updates the modification time
7467 Execute(Touch('file_to_be_touched'))
7469 env.Command('marker', 'input_file',
7474 .SS Variable Substitution
7476 Before executing a command,
7478 performs construction variable interpolation on the strings that make up
7479 the command line of builders.
7480 Variables are introduced by a
7483 Besides construction variables, scons provides the following
7484 variables for each command execution:
7487 The file name of the target being built, or the file name of the first
7488 target if multiple targets are being built.
7491 The file names of all targets being built.
7494 The file name of the source of the build command, or the file name of the
7495 first source if multiple sources are being built.
7498 The file names of the sources of the build command.
7500 (Note that the above variables are reserved
7501 and may not be set in a construction environment.)
7504 For example, given the construction variable CC='cc', targets=['foo'], and
7505 sources=['foo.c', 'bar.c']:
7508 action='$CC -c -o $TARGET $SOURCES'
7511 would produce the command line:
7514 cc -c -o foo foo.c bar.c
7517 Variable names may be surrounded by curly braces ({})
7518 to separate the name from the trailing characters.
7519 Within the curly braces, a variable name may have
7520 a Python slice subscript appended to select one
7521 or more items from a list.
7522 In the previous example, the string:
7534 Additionally, a variable name may
7535 have the following special
7536 modifiers appended within the enclosing curly braces
7537 to modify the interpolated string:
7540 The base path of the file name,
7541 including the directory path
7542 but excluding any suffix.
7545 The name of the directory in which the file exists.
7549 minus any directory portion.
7552 Just the basename of the file,
7554 and minus the directory.
7557 Just the file suffix.
7560 The absolute path name of the file.
7563 The POSIX form of the path,
7564 with directories separated by
7568 This is sometimes necessary on Windows systems
7569 when a path references a file on other (POSIX) systems.
7572 The directory and file name to the source file linked to this file
7573 through BuildDir. If this file isn't linked, it just returns the
7574 directory and filename unchanged.
7577 The directory containing the source file linked to this file
7578 through BuildDir. If this file isn't linked, it just returns the
7579 directory part of the filename.
7582 The directory and file name to the source file linked to this file
7583 through BuildDir. If the file does not exist locally but exists in
7584 a Repository, the path in the Repository is returned.
7585 If this file isn't linked, it just returns the
7586 directory and filename unchanged.
7589 The Repository directory containing the source file linked to this file
7590 through BuildDir. If this file isn't linked, it just returns the
7591 directory part of the filename.
7594 For example, the specified target will
7595 expand as follows for the corresponding modifiers:
7598 $TARGET => sub/dir/file.x
7599 ${TARGET.base} => sub/dir/file
7600 ${TARGET.dir} => sub/dir
7601 ${TARGET.file} => file.x
7602 ${TARGET.filebase} => file
7603 ${TARGET.suffix} => .x
7604 ${TARGET.abspath} => /top/dir/sub/dir/file.x
7606 SConscript('src/SConscript', build_dir='sub/dir')
7607 $SOURCE => sub/dir/file.x
7608 ${SOURCE.srcpath} => src/file.x
7609 ${SOURCE.srcdir} => src
7611 Repository('/usr/repository')
7612 $SOURCE => sub/dir/file.x
7613 ${SOURCE.rsrcpath} => /usr/repository/src/file.x
7614 ${SOURCE.rsrcdir} => /usr/repository/src
7617 Note that curly braces braces may also be used
7618 to enclose arbitrary Python code to be evaluated.
7619 (In fact, this is how the above modifiers are substituted,
7620 they are simply attributes of the Python objects
7621 that represent TARGET, SOURCES, etc.)
7622 See the section "Python Code Substitution," below,
7623 for more thorough examples of
7624 how this can be used.
7626 Lastly, a variable name
7627 may be a callable Python function
7629 construction variable in the environment.
7631 take four arguments:
7633 - a list of target nodes,
7635 - a list of source nodes,
7637 - the construction environment,
7639 - a Boolean value that specifies
7640 whether the function is being called
7641 for generating a build signature.
7642 SCons will insert whatever
7643 the called function returns
7644 into the expanded string:
7647 def foo(target, source, env, for_signature):
7650 # Will expand $BAR to "bar baz"
7651 env=Environment(FOO=foo, BAR="$FOO baz")
7654 You can use this feature to pass arguments to a
7655 Python function by creating a callable class
7656 that stores one or more arguments in an object,
7657 and then uses them when the
7660 Note that in this case,
7661 the entire variable expansion must
7662 be enclosed by curly braces
7663 so that the arguments will
7664 be associated with the
7665 instantiation of the class:
7669 def __init__(self, arg):
7672 def __call__(self, target, source, env, for_signature):
7673 return self.arg + " bar"
7675 # Will expand $BAR to "my argument bar baz"
7676 env=Environment(FOO=foo, BAR="${FOO('my argument')} baz")
7680 The special pseudo-variables
7684 may be used to surround parts of a command line
7687 causing a rebuild--that is,
7688 which are not included in the signature
7689 of target files built with this command.
7694 will be removed from the command line
7695 before it is added to file signatures,
7700 will be removed before the command is executed.
7701 For example, the command line:
7704 echo Last build occurred $( $TODAY $). > $TARGET
7708 would execute the command:
7711 echo Last build occurred $TODAY. > $TARGET
7715 but the command signature added to any target files would be:
7718 echo Last build occurred . > $TARGET
7721 .SS Python Code Substitution
7723 Any python code within
7725 pairs gets evaluated by python 'eval', with the python globals set to
7726 the current environment's set of construction variables.
7727 So in the following case:
7730 env.Command('foo.out', 'foo.in',
7731 '''echo ${COND==1 and 'FOO' or 'BAR'} > $TARGET''')
7733 the command executed will be either
7741 according to the current value of env['COND'] when the command is
7742 executed. The evaluation occurs when the target is being
7743 built, not when the SConscript is being read. So if env['COND'] is changed
7744 later in the SConscript, the final value will be used.
7746 Here's a more interesting example. Note that all of COND, FOO, and
7747 BAR are environment variables, and their values are substituted into
7748 the final command. FOO is a list, so its elements are interpolated
7749 separated by spaces.
7754 env['FOO'] = ['foo1', 'foo2']
7755 env['BAR'] = 'barbar'
7756 env.Command('foo.out', 'foo.in',
7757 'echo ${COND==1 and FOO or BAR} > $TARGET')
7759 # Will execute this:
7760 # echo foo1 foo2 > foo.out
7763 SCons uses the following rules when converting construction variables into
7767 When the value is a string it is interpreted as a space delimited list of
7768 command line arguments.
7771 When the value is a list it is interpreted as a list of command line
7772 arguments. Each element of the list is converted to a string.
7775 Anything that is not a list or string is converted to a string and
7776 interpreted as a single command line argument.
7779 Newline characters (\\n) delimit lines. The newline parsing is done after
7780 all other parsing, so it is not possible for arguments (e.g. file names) to
7781 contain embedded newline characters. This limitation will likely go away in
7782 a future version of SCons.
7790 new file types for implicit dependencies.
7791 Scanner accepts the following arguments:
7795 1) a Python function that will process
7797 and return a list of strings (file names)
7798 representing the implicit
7799 dependencies found in the contents;
7801 2) a dictionary that maps keys
7802 (typically the file suffix, but see below for more discussion)
7803 to other Scanners that should be called.
7805 If the argument is actually a Python function,
7806 the function must take three or four arguments:
7808 def scanner_function(node, env, path):
7810 def scanner_function(node, env, path, arg=None):
7814 argument is the internal
7815 SCons node representing the file.
7818 to fetch the name of the file, and
7819 .B node.get_contents()
7820 to fetch contents of the file.
7821 Note that the file is
7823 guaranteed to exist before the scanner is called,
7824 so the scanner function should check that
7825 if there's any chance that the scanned file
7827 (for example, if it's built from other files).
7831 argument is the construction environment for the scan.
7832 Fetch values from it using the
7838 argument is a tuple (or list)
7839 of directories that can be searched
7841 This will usually be the tuple returned by the
7843 argument (see below).
7847 argument is the argument supplied
7848 when the scanner was created, if any.
7851 The name of the Scanner.
7853 to identify the Scanner internally.
7856 An optional argument that, if specified,
7857 will be passed to the scanner function
7859 and the path function
7863 An optional list that can be used to
7864 determine which scanner should be used for
7866 In the usual case of scanning for file names,
7867 this argument will be a list of suffixes
7868 for the different file types that this
7869 Scanner knows how to scan.
7870 If the argument is a string,
7871 then it will be expanded
7872 into a list by the current environment.
7875 A Python function that takes four or five arguments:
7876 a construction environment,
7877 a Node for the directory containing
7878 the SConscript file in which
7879 the first target was defined,
7880 a list of target nodes,
7881 a list of source nodes,
7882 and an optional argument supplied
7883 when the scanner was created.
7886 returns a tuple of directories
7887 that can be searched for files to be returned
7888 by this Scanner object.
7891 function can be used to return a ready-made
7893 for a given construction variable name,
7894 instead of having to write your own function from scratch.)
7897 The class of Node that should be returned
7898 by this Scanner object.
7899 Any strings or other objects returned
7900 by the scanner function
7901 that are not of this class
7902 will be run through the
7907 A Python function that will take a string
7909 and turn it into the appropriate class of Node
7910 to be returned by this Scanner object.
7913 An optional Python function that takes two arguments,
7914 a Node (file) and a construction environment,
7915 and returns whether the
7916 Node should, in fact,
7917 be scanned for dependencies.
7918 This check can be used to eliminate unnecessary
7919 calls to the scanner function when,
7920 for example, the underlying file
7921 represented by a Node does not yet exist.
7924 An optional flag that
7925 specifies whether this scanner should be re-invoked
7926 on the dependency files returned by the scanner.
7927 When this flag is not set,
7928 the Node subsystem will
7929 only invoke the scanner on the file being scanned,
7930 and not (for example) also on the files
7931 specified by the #include lines
7932 in the file being scanned.
7934 may be a callable function,
7935 in which case it will be called with a list of
7937 should return a list of Nodes
7938 that should be scanned recursively;
7939 this can be used to select a specific subset of
7940 Nodes for additional scanning.
7945 .B SourceFileScanner
7946 object that is used by
7949 .BR SharedObject (),
7953 which scanner should be used
7954 for different file extensions.
7956 .BR SourceFileScanner.add_scanner ()
7957 method to add your own Scanner object
7961 that builds target programs or
7962 libraries from a list of
7963 source files of different types:
7966 def xyz_scan(node, env, path):
7967 contents = node.get_contents()
7968 # Scan the contents and return the included files.
7970 XYZScanner = Scanner(xyz_scan)
7972 SourceFileScanner.add_scanner('.xyx', XYZScanner)
7974 env.Program('my_prog', ['file1.c', 'file2.f', 'file3.xyz'])
7977 .SH SYSTEM-SPECIFIC BEHAVIOR
7978 SCons and its configuration files are very portable,
7979 due largely to its implementation in Python.
7980 There are, however, a few portability
7981 issues waiting to trap the unwary.
7983 SCons handles the upper-case
7985 file suffix differently,
7986 depending on the capabilities of
7987 the underlying system.
7988 On a case-sensitive system
7989 such as Linux or UNIX,
7990 SCons treats a file with a
7992 suffix as a C++ source file.
7993 On a case-insensitive system
7995 SCons treats a file with a
7997 suffix as a C source file.
7999 SCons handles the upper-case
8001 file suffix differently,
8002 depending on the capabilities of
8003 the underlying system.
8004 On a case-sensitive system
8005 such as Linux or UNIX,
8006 SCons treats a file with a
8008 suffix as a Fortran source file
8009 that is to be first run through
8010 the standard C preprocessor.
8011 On a case-insensitive system
8013 SCons treats a file with a
8015 suffix as a Fortran source file that should
8017 be run through the C preprocessor.
8018 .SS Windows: Cygwin Tools and Cygwin Python vs. Windows Pythons
8019 Cygwin supplies a set of tools and utilities
8020 that let users work on a
8021 Windows system using a more POSIX-like environment.
8022 The Cygwin tools, including Cygwin Python,
8024 by sharing an ability to interpret UNIX-like path names.
8025 For example, the Cygwin tools
8026 will internally translate a Cygwin path name
8027 like /cygdrive/c/mydir
8028 to an equivalent Windows pathname
8029 of C:/mydir (equivalent to C:\\mydir).
8032 that are built for native Windows execution,
8033 such as the python.org and ActiveState versions,
8034 do not have the Cygwin path name semantics.
8035 This means that using a native Windows version of Python
8036 to build compiled programs using Cygwin tools
8037 (such as gcc, bison, and flex)
8038 may yield unpredictable results.
8039 "Mixing and matching" in this way
8040 can be made to work,
8041 but it requires careful attention to the use of path names
8042 in your SConscript files.
8044 In practice, users can sidestep
8045 the issue by adopting the following rules:
8047 use the Cygwin-supplied Python interpreter
8049 when using Microsoft Visual C/C++
8050 (or some other Windows compiler)
8051 use the python.org or ActiveState version of Python
8053 .SS Windows: scons.bat file
8055 SCons is executed via a wrapper
8058 This has (at least) two ramifications:
8060 First, Windows command-line users
8061 that want to use variable assignment
8063 may have to put double quotes
8064 around the assignments:
8067 scons "FOO=BAR" "BAZ=BLEH"
8070 Second, the Cygwin shell does not
8071 recognize this file as being the same
8074 command issued at the command-line prompt.
8075 You can work around this either by
8078 from the Cygwin command line,
8079 or by creating a wrapper shell
8085 The MinGW bin directory must be in your PATH environment variable or the
8086 PATH variable under the ENV construction variable for SCons
8087 to detect and use the MinGW tools. When running under the native Windows
8088 Python interpreter, SCons will prefer the MinGW tools over the Cygwin
8089 tools, if they are both installed, regardless of the order of the bin
8090 directories in the PATH variable. If you have both MSVC and MinGW
8091 installed and you want to use MinGW instead of MSVC,
8092 then you must explictly tell SCons to use MinGW by passing
8098 to the Environment() function, because SCons will prefer the MSVC tools
8099 over the MinGW tools.
8103 To help you get started using SCons,
8104 this section contains a brief overview of some common tasks.
8106 .SS Basic Compilation From a Single Source File
8110 env.Program(target = 'foo', source = 'foo.c')
8113 Note: Build the file by specifying
8114 the target as an argument
8115 ("scons foo" or "scons foo.exe").
8116 or by specifying a dot ("scons .").
8118 .SS Basic Compilation From Multiple Source Files
8122 env.Program(target = 'foo', source = Split('f1.c f2.c f3.c'))
8125 .SS Setting a Compilation Flag
8128 env = Environment(CCFLAGS = '-g')
8129 env.Program(target = 'foo', source = 'foo.c')
8132 .SS Search The Local Directory For .h Files
8136 need to set CCFLAGS to specify -I options by hand.
8137 SCons will construct the right -I options from CPPPATH.
8140 env = Environment(CPPPATH = ['.'])
8141 env.Program(target = 'foo', source = 'foo.c')
8144 .SS Search Multiple Directories For .h Files
8147 env = Environment(CPPPATH = ['include1', 'include2'])
8148 env.Program(target = 'foo', source = 'foo.c')
8151 .SS Building a Static Library
8155 env.StaticLibrary(target = 'foo', source = Split('l1.c l2.c'))
8156 env.StaticLibrary(target = 'bar', source = ['l3.c', 'l4.c'])
8159 .SS Building a Shared Library
8163 env.SharedLibrary(target = 'foo', source = ['l5.c', 'l6.c'])
8164 env.SharedLibrary(target = 'bar', source = Split('l7.c l8.c'))
8167 .SS Linking a Local Library Into a Program
8170 env = Environment(LIBS = 'mylib', LIBPATH = ['.'])
8171 env.Library(target = 'mylib', source = Split('l1.c l2.c'))
8172 env.Program(target = 'prog', source = ['p1.c', 'p2.c'])
8175 .SS Defining Your Own Builder Object
8177 Notice that when you invoke the Builder,
8178 you can leave off the target file suffix,
8179 and SCons will add it automatically.
8182 bld = Builder(action = 'pdftex < $SOURCES > $TARGET'
8184 src_suffix = '.tex')
8185 env = Environment(BUILDERS = {'PDFBuilder' : bld})
8186 env.PDFBuilder(target = 'foo.pdf', source = 'foo.tex')
8188 # The following creates "bar.pdf" from "bar.tex"
8189 env.PDFBuilder(target = 'bar', source = 'bar')
8192 Note also that the above initialization
8193 overwrites the default Builder objects,
8194 so the Environment created above
8195 can not be used call Builders like env.Program(),
8196 env.Object(), env.StaticLibrary(), etc.
8198 .SS Adding Your Own Builder Object to an Environment
8201 bld = Builder(action = 'pdftex < $SOURCES > $TARGET'
8203 src_suffix = '.tex')
8205 env.Append(BUILDERS = {'PDFBuilder' : bld})
8206 env.PDFBuilder(target = 'foo.pdf', source = 'foo.tex')
8207 env.Program(target = 'bar', source = 'bar.c')
8210 You also can use other Pythonic techniques to add
8211 to the BUILDERS construction variable, such as:
8215 env['BUILDERS]['PDFBuilder'] = bld
8218 .SS Defining Your Own Scanner Object
8220 The following example shows an extremely simple scanner (the
8223 that doesn't use a search path at all
8224 and simply returns the
8225 file names present on any
8227 lines in the scanned file.
8228 This would implicitly assume that all included
8229 files live in the top-level directory:
8234 '\" Note: the \\ in the following are for the benefit of nroff/troff,
8235 '\" not inappropriate doubled escape characters within the r'' raw string.
8236 include_re = re.compile(r'^include\\s+(\\S+)$', re.M)
8238 def kfile_scan(node, env, path, arg):
8239 contents = node.get_contents()
8240 includes = include_re.findall(contents)
8243 kscan = Scanner(name = 'kfile',
8244 function = kfile_scan,
8247 scanners = Environment().Dictionary('SCANNERS')
8248 env = Environment(SCANNERS = scanners + [kscan])
8250 env.Command('foo', 'foo.k', 'kprocess < $SOURCES > $TARGET')
8252 bar_in = File('bar.in')
8253 env.Command('bar', bar_in, 'kprocess $SOURCES > $TARGET')
8254 bar_in.target_scanner = kscan
8257 Here is a similar but more complete example that searches
8258 a path of directories
8261 construction variable)
8262 for files that actually exist:
8265 include_re = re.compile(r'^include\\s+(\\S+)$', re.M)
8267 def my_scan(node, env, path, arg):
8268 contents = node.get_contents()
8269 includes = include_re.findall(contents)
8273 for inc in includes:
8275 file = dir + os.sep + inc
8276 if os.path.exists(file):
8277 results.append(file)
8281 scanner = Scanner(name = 'myscanner',
8285 path_function = FindPathDirs('MYPATH'),
8287 scanners = Environment().Dictionary('SCANNERS')
8288 env = Environment(SCANNERS = scanners + [scanner])
8293 function used in the previous example returns a function
8294 (actually a callable Python object)
8295 that will return a list of directories
8298 construction variable.
8299 If you need to customize how the search path is derived,
8300 you would provide your own
8302 argument when creating the Scanner object,
8306 # MYPATH is a list of directories to search for files in
8307 def pf(env, dir, target, source, arg):
8308 top_dir = Dir('#').abspath
8310 if env.has_key('MYPATH'):
8311 for p in env['MYPATH']:
8312 results.append(top_dir + os.sep + p)
8315 scanner = Scanner(name = 'myscanner',
8323 .SS Creating a Hierarchical Build
8325 Notice that the file names specified in a subdirectory's
8327 file are relative to that subdirectory.
8333 env.Program(target = 'foo', source = 'foo.c')
8335 SConscript('sub/SConscript')
8340 # Builds sub/foo from sub/foo.c
8341 env.Program(target = 'foo', source = 'foo.c')
8343 SConscript('dir/SConscript')
8348 # Builds sub/dir/foo from sub/dir/foo.c
8349 env.Program(target = 'foo', source = 'foo.c')
8352 .SS Sharing Variables Between SConscript Files
8354 You must explicitly Export() and Import() variables that
8355 you want to share between SConscript files.
8361 env.Program(target = 'foo', source = 'foo.c')
8364 SConscript('subdirectory/SConscript')
8366 subdirectory/SConscript:
8369 env.Program(target = 'foo', source = 'foo.c')
8372 .SS Building Multiple Variants From the Same Source
8374 Use the build_dir keyword argument to
8375 the SConscript function to establish
8376 one or more separate build directories for
8377 a given source directory:
8382 cppdefines = ['FOO']
8383 Export("cppdefines")
8384 SConscript('src/SConscript', build_dir='foo')
8386 cppdefines = ['BAR']
8387 Export("cppdefines")
8388 SConscript('src/SConscript', build_dir='bar')
8392 Import("cppdefines")
8393 env = Environment(CPPDEFINES = cppdefines)
8394 env.Program(target = 'src', source = 'src.c')
8397 Note the use of the Export() method
8398 to set the "cppdefines" variable to a different
8399 value each time we call the SConscript function.
8401 .SS Hierarchical Build of Two Libraries Linked With a Program
8406 env = Environment(LIBPATH = ['#libA', '#libB'])
8408 SConscript('libA/SConscript')
8409 SConscript('libB/SConscript')
8410 SConscript('Main/SConscript')
8415 env.Library('a', Split('a1.c a2.c a3.c'))
8420 env.Library('b', Split('b1.c b2.c b3.c'))
8425 e = env.Copy(LIBS = ['a', 'b'])
8426 e.Program('foo', Split('m1.c m2.c m3.c'))
8429 The '#' in the LIBPATH directories specify that they're relative to the
8430 top-level directory, so they don't turn into "Main/libA" when they're
8431 used in Main/SConscript.
8433 Specifying only 'a' and 'b' for the library names
8434 allows SCons to append the appropriate library
8435 prefix and suffix for the current platform
8436 (for example, 'liba.a' on POSIX systems,
8437 'a.lib' on Windows).
8439 .SS Customizing contruction variables from the command line.
8441 The following would allow the C compiler to be specified on the command
8442 line or in the file custom.py.
8445 opts = Options('custom.py')
8446 opts.Add('CC', 'The C compiler.')
8447 env = Environment(options=opts)
8448 Help(opts.GenerateHelpText(env))
8451 The user could specify the C compiler on the command line:
8457 or in the custom.py file:
8463 or get documentation on the options:
8474 .SS Using Microsoft Visual C++ precompiled headers
8476 Since windows.h includes everything and the kitchen sink, it can take quite
8477 some time to compile it over and over again for a bunch of object files, so
8478 Microsoft provides a mechanism to compile a set of headers once and then
8479 include the previously compiled headers in any object file. This
8480 technology is called precompiled headers. The general recipe is to create a
8481 file named "StdAfx.cpp" that includes a single header named "StdAfx.h", and
8482 then include every header you want to precompile in "StdAfx.h", and finally
8483 include "StdAfx.h" as the first header in all the source files you are
8484 compiling to object files. For example:
8488 #include <windows.h>
8489 #include <my_big_header.h>
8508 /* do some other stuff */
8514 env['PCHSTOP'] = 'StdAfx.h'
8515 env['PCH'] = env.PCH('StdAfx.cpp')[0]
8516 env.Program('MyApp', ['Foo.cpp', 'Bar.cpp'])
8519 For more information see the document for the PCH builder, and the PCH and
8520 PCHSTOP construction variables. To learn about the details of precompiled
8521 headers consult the MSDN documention for /Yc, /Yu, and /Yp.
8523 .SS Using Microsoft Visual C++ external debugging information
8525 Since including debugging information in programs and shared libraries can
8526 cause their size to increase significantly, Microsoft provides a mechanism
8527 for including the debugging information in an external file called a PDB
8528 file. SCons supports PDB files through the PDB construction
8534 env['PDB'] = 'MyApp.pdb'
8535 env.Program('MyApp', ['Foo.cpp', 'Bar.cpp'])
8538 For more information see the document for the PDB construction variable.
8543 Specifies the directory that contains the SCons Python module directory
8544 (e.g. /home/aroach/scons-src-0.01/src/engine).
8547 A string of options that will be used by scons in addition to those passed
8548 on the command line.
8559 Steven Knight <knight@baldmt.com>
8561 Anthony Roach <aroach@electriceyeball.com>