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 only works when run under Python 2.1 or later.
593 A synonym for the newer
596 This will be deprecated in some future release
597 and ultimately removed.
601 Print an explanation of precisely why
603 is deciding to (re-)build any targets.
604 (Note: this does not print anything
611 Instruct the scanner that searches for libraries
612 to print a message about each potential library
613 name it is searching for,
614 and about the actual libraries it finds.
618 Print the include tree after each top-level target is built.
619 This is generally used to find out what files are included by the sources
620 of a given derived file:
623 $ scons --debug=includes foo.o
628 Prints a summary of hits and misses using the Memoizer,
629 an internal subsystem that counts
630 how often SCons uses cached values in memory
631 instead of recomputing them each time they're needed.
632 Only available when using Python 2.2 or later.
636 Prints how much memory SCons uses
637 before and after reading the SConscript files
638 and before and after building targets.
642 A deprecated option preserved for backwards compatibility.
646 Prints a list of the various objects
647 of the various classes used internally by SCons.
648 This only works when run under Python 2.1 or later.
652 Re-run SCons under the control of the
658 Print the raw command line used to build each target
659 before the construction environment variables are substituted.
660 Also shows which targets are being built by this command.
661 Output looks something like this:
663 $ scons --debug=presub
664 Building myprog.o with action(s):
665 $SHCC $SHCFLAGS $SHCCFLAGS $CPPFLAGS $_CPPINCFLAGS -c -o $TARGET $SOURCES
671 Prints an internal Python stack trace
672 when encountering an otherwise unexplained error.
676 A synonym for the newer
679 This will be deprecated in some future release
680 and ultimately removed.
684 Prints various time profiling information:
685 the time spent executing each individual build command;
686 the total build time (time SCons ran from beginning to end);
687 the total time spent reading and executing SConscript files;
688 the total time spent SCons itself spend running
689 (that is, not counting reading and executing SConscript files);
690 and both the total time spent executing all build commands
691 and the elapsed wall-clock time spent executing those build commands.
694 is executed without the
697 the elapsed wall-clock time will typically
698 be slightly longer than the total time spent
699 executing all the build commands,
700 due to the SCons processing that takes place
701 in between executing each command.
709 and your build configuration allows good parallelization,
710 the elapsed wall-clock time should
711 be significantly smaller than the
712 total time spent executing all the build commands,
713 since multiple build commands and
714 intervening SCons processing
715 should take place in parallel.)
719 A synonym for the newer
722 This will be deprecated in some future release
723 and ultimately removed.
726 .RI --diskcheck= types
727 Enable specific checks for
728 whether or not there is a file on disk
729 where the SCons configuration expects a directory
731 and whether or not RCS or SCCS sources exist
732 when searching for source and include files.
735 argument can be set to:
737 to enable all checks explicitly
738 (the default behavior);
740 to disable all such checks;
742 to check that files and directories on disk
743 match SCons' expected configuration;
745 to check for the existence of an RCS source
746 for any missing source or include files;
748 to check for the existence of an SCCS source
749 for any missing source or include files.
750 Multiple checks can be specified separated by commas;
752 .B --diskcheck=sccs,rcs
753 would still check for SCCS and RCS sources,
754 but disable the check for on-disk matches of files and directories.
755 Disabling some or all of these checks
756 can provide a performance boost for large configurations,
757 or when the configuration will check for files and/or directories
758 across networked or shared file systems,
759 at the slight increased risk of an incorrect build
760 or of not handling errors gracefully
761 (if include files really should be
762 found in SCCS or RCS, for example,
763 or if a file really does exist
764 where the SCons configuration expects a directory).
767 .RI --duplicate= ORDER
768 There are three ways to duplicate files in a build tree: hard links,
769 soft (symbolic) links and copies. The default behaviour of SCons is to
770 prefer hard links to soft links to copies. You can specify different
771 behaviours with this option.
781 SCons will attempt to duplicate files using
782 the mechanisms in the specified order.
785 .\" -e, --environment-overrides
786 .\" Variables from the execution environment override construction
787 .\" variables from the SConscript files.
790 .RI -f " file" ", --file=" file ", --makefile=" file ", --sconstruct=" file
793 as the initial SConscript file.
797 Print a local help message for this build, if one is defined in
798 the SConscript file(s), plus a line that describes the
800 option for command-line option help. If no local help message
801 is defined, prints the standard help message about command-line
802 options. Exits after displaying the appropriate message.
806 Print the standard help message about command-line options and
811 Ignore all errors from commands executed to rebuild files.
814 .RI -I " directory" ", --include-dir=" directory
818 imported Python modules. If several
821 are used, the directories are searched in the order specified.
825 Cache implicit dependencies.
828 to use the implicit (scanned) dependencies
829 from the last time it was run
830 instead of scanning the files for implicit dependencies.
831 This can significantly speed up SCons,
832 but with the following limitations:
835 will not detect changes to implicit dependency search paths
837 .BR CPPPATH ", " LIBPATH )
838 that would ordinarily
839 cause different versions of same-named files to be used.
842 will miss changes in the implicit dependencies
843 in cases where a new implicit
844 dependency is added earlier in the implicit dependency search path
846 .BR CPPPATH ", " LIBPATH )
847 than a current implicit dependency with the same name.
850 --implicit-deps-changed
851 Forces SCons to ignore the cached implicit dependencies. This causes the
852 implicit dependencies to be rescanned and recached. This implies
853 .BR --implicit-cache .
856 --implicit-deps-unchanged
857 Force SCons to ignore changes in the implicit dependencies.
858 This causes cached implicit dependencies to always be used.
860 .BR --implicit-cache .
863 .RI -j " N" ", --jobs=" N
864 Specifies the number of jobs (commands) to run simultaneously.
865 If there is more than one
867 option, the last one is effective.
871 .\" is specified without an argument,
873 .\" will not limit the number of
874 .\" simultaneous jobs.
878 Continue as much as possible after an error. The target that
879 failed and those that depend on it will not be remade, but other
880 targets specified on the command line will still be processed.
883 .\" .RI -l " N" ", --load-average=" N ", --max-load=" N
884 .\" No new jobs (commands) will be started if
885 .\" there are other jobs running and the system load
886 .\" average is at least
888 .\" (a floating-point number).
893 .\" List derived files (targets, dependencies) that would be built,
894 .\" but do not build them.
895 .\" [XXX This can probably go away with the right
896 .\" combination of other options. Revisit this issue.]
900 .\" List derived files that would be built, with the actions
901 .\" (commands) that build them. Does not build the files.
902 .\" [XXX This can probably go away with the right
903 .\" combination of other options. Revisit this issue.]
907 .\" List derived files that would be built, plus where the file is
908 .\" defined (file name and line number). Does not build the files.
909 .\" [XXX This can probably go away with the right
910 .\" combination of other options. Revisit this issue.]
914 Ignored for compatibility with non-GNU versions of
918 .RI --max-drift= SECONDS
919 Set the maximum expected drift in the modification time of files to
921 This value determines how long a file must be unmodified
922 before its cached content signature
923 will be used instead of
924 calculating a new content signature (MD5 checksum)
925 of the file's contents.
926 The default value is 2 days, which means a file must have a
927 modification time of at least two days ago in order to have its
928 cached content signature used.
929 A negative value means to never cache the content
930 signature and to ignore the cached value if there already is one. A value
931 of 0 means to always use the cached signature,
932 no matter how old the file is.
935 -n, --just-print, --dry-run, --recon
936 No execute. Print the commands that would be executed to build
937 any out-of-date target files, but do not execute the commands.
941 Prevents the automatic addition of the standard
945 Also prevents loading the
946 .I site_scons/site_init.py
947 module if it exists, and prevents adding
948 .I site_scons/site_tools
952 .\" .RI -o " file" ", --old-file=" file ", --assume-old=" file
956 .\" not rebuild anything due to changes in the contents of
959 .\" .RI --override " file"
960 .\" Read values to override specific build environment variables
961 .\" from the specified
965 .\" Print the data base (construction environments,
966 .\" Builder and Scanner objects) that are defined
967 .\" after reading the SConscript files.
968 .\" After printing, a normal build is performed
969 .\" as usual, as specified by other command-line options.
970 .\" This also prints version information
975 .\" To print the database without performing a build do:
983 Run SCons under the Python profiler
984 and save the results in the specified
986 The results may be analyzed using the Python
991 Do not run any commands, or print anything. Just return an exit
992 status that is zero if the specified targets are already up to
993 date, non-zero otherwise.
996 Quiets SCons status messages about
997 reading SConscript files,
999 and entering directories.
1000 Commands that are executed
1001 to rebuild target files are still printed.
1004 .\" -r, -R, --no-builtin-rules, --no-builtin-variables
1005 .\" Clear the default construction variables. Construction
1006 .\" environments that are created will be completely empty.
1010 Build dependencies in a random order. This is useful when
1011 building multiple trees simultaneously with caching enabled,
1012 to prevent multiple builds from simultaneously trying to build
1013 or retrieve the same target files.
1016 -s, --silent, --quiet
1017 Silent. Do not print commands that are executed to rebuild
1019 Also suppresses SCons status messages.
1022 -S, --no-keep-going, --stop
1023 Ignored for compatibility with GNU
1028 Uses the named dir as the site dir rather than the default
1030 dir. This dir will get prepended to
1033 .IR dir /site_init.py
1034 will get loaded if it exists, and
1036 will get added to the default toolpath.
1040 Ignored for compatibility with GNU
1042 (Touching a file to make it
1043 appear up-to-date is unnecessary when using
1047 .RI --taskmastertrace= file
1048 Prints trace information to the specified
1050 about how the internal Taskmaster object
1051 evaluates and controls the order in which Nodes are built.
1054 may be used to specify the standard output.
1058 Prints a tree of the dependencies
1059 after each top-level target is built.
1060 This prints out some or all of the tree,
1068 Print the entire dependency tree
1069 after each top-level target is built.
1070 This prints out the complete dependency tree,
1071 including implicit dependencies and ignored dependencies.
1075 Restricts the tree output to only derived (target) files,
1080 Prints status information for each displayed node.
1084 Prunes the tree to avoid repeating dependency information
1085 for nodes that have already been displayed.
1086 Any node that has already been displayed
1087 will have its name printed in
1088 .BR "[square brackets]" ,
1089 as an indication that the dependencies
1090 for that node can be found by searching
1091 for the relevant output higher up in the tree.
1094 Multiple options may be specified,
1095 separated by commas:
1098 # Prints only derived files, with status information:
1099 scons --tree=derived,status
1101 # Prints all dependencies of target, with status information
1102 # and pruning dependencies of already-visited Nodes:
1103 scons --tree=all,prune,status target
1107 -u, --up, --search-up
1108 Walks up the directory structure until an
1113 file is found, and uses that
1114 as the top of the directory tree.
1115 If no targets are specified on the command line,
1116 only targets at or below the
1117 current directory will be built.
1121 Works exactly the same way as the
1123 option except for the way default targets are handled.
1124 When this option is used and no targets are specified on the command line,
1125 all default targets that are defined in the SConscript(s) in the current
1126 directory are built, regardless of what directory the resultant targets end
1133 version, copyright information,
1134 list of authors, and any other relevant information.
1138 -w, --print-directory
1139 Print a message containing the working directory before and
1140 after other processing.
1143 --no-print-directory
1144 Turn off -w, even if it was turned on implicitly.
1147 .RI --warn= type ", --warn=no-" type
1148 Enable or disable warnings.
1150 specifies the type of warnings to be enabled or disabled:
1153 --warn=all, --warn=no-all
1154 Enables or disables all warnings.
1157 --warn=cache-write-error, --warn=no-cache-write-error
1158 Enables or disables warnings about errors trying to
1159 write a copy of a built file to a specified
1161 These warnings are disabled by default.
1164 --warn=corrupt-sconsign, --warn=no-corrupt-sconsign
1165 Enables or disables warnings about unfamiliar signature data in
1168 These warnings are enabled by default.
1171 --warn=dependency, --warn=no-dependency
1172 Enables or disables warnings about dependencies.
1173 These warnings are disabled by default.
1176 --warn=deprecated, --warn=no-deprecated
1177 Enables or disables warnings about use of deprecated features.
1178 These warnings are enabled by default.
1181 --warn=duplicate-environment, --warn=no-duplicate-environment
1182 Enables or disables warnings about missing SConscript files.
1185 --warn=misleading-keywords, --warn=no-misleading-keywords
1186 Enables or disables warnings about use of the misspelled keywords
1190 when calling Builders.
1193 characters, the correct spellings are
1197 These warnings are enabled by default.
1200 --warn=missing-sconscript, --warn=no-missing-sconscript
1201 Enables or disables warnings about attempts to specify a build
1202 of a target with two different construction environments
1203 that use the same action.
1204 These warnings are enabled by default.
1207 --warn=no-md5-module, --warn=no-no-md5-module
1208 Enables or disables warnings about the version of Python
1209 not having an MD5 checksum module available.
1210 These warnings are enabled by default.
1213 --warn=no-metaclass-support, --warn=no-no-metaclass-support
1214 Enables or disables warnings about the version of Python
1215 not supporting metaclasses when the
1218 These warnings are enabled by default.
1221 --warn=no-parallel-support, --warn=no-no-parallel-support
1222 Enables or disables warnings about the version of Python
1223 not being able to support parallel builds when the
1226 These warnings are enabled by default.
1229 --warn=reserved-variable, --warn=no-reserved-variable
1230 Enables or disables warnings about attempts to set the
1231 reserved construction variable names
1237 These warnings are disabled by default.
1240 .\" .RI --write-filenames= file
1241 .\" Write all filenames considered into
1245 .\" .RI -W " file" ", --what-if=" file ", --new-file=" file ", --assume-new=" file
1246 .\" Pretend that the target
1249 .\" modified. When used with the
1252 .\" show you what would be rebuilt if you were to modify that file.
1258 .\" --warn-undefined-variables
1259 .\" Warn when an undefined variable is referenced.
1262 .RI -Y " repository" ", --repository=" repository ", --srcdir=" repository
1263 Search the specified repository for any input and target
1264 files not found in the local directory hierarchy. Multiple
1266 options may specified, in which case the
1267 repositories are searched in the order specified.
1269 .SH CONFIGURATION FILE REFERENCE
1270 .\" .SS Python Basics
1271 .\" XXX Adding this in the future would be a help.
1272 .SS Construction Environments
1273 A construction environment is the basic means by which the SConscript
1274 files communicate build information to
1276 A new construction environment is created using the
1284 By default, a new construction environment is
1285 initialized with a set of builder methods
1286 and construction variables that are appropriate
1287 for the current platform.
1288 An optional platform keyword argument may be
1289 used to specify that an environment should
1290 be initialized for a different platform:
1293 env = Environment(platform = 'cygwin')
1294 env = Environment(platform = 'os2')
1295 env = Environment(platform = 'posix')
1296 env = Environment(platform = 'win32')
1299 Specifying a platform initializes the appropriate
1300 construction variables in the environment
1301 to use and generate file names with prefixes
1302 and suffixes appropriate for the platform.
1310 variables from the user's external environment
1311 to the construction environment's
1314 This is so that any executed commands
1315 that use sockets to connect with other systems
1316 (such as fetching source files from
1317 external CVS repository specifications like
1318 .BR :pserver:anonymous@cvs.sourceforge.net:/cvsroot/scons )
1319 will work on Windows systems.
1321 The platform argument may be function or callable object,
1322 in which case the Environment() method
1323 will call the specified argument to update
1324 the new construction environment:
1327 def my_platform(env):
1328 env['VAR'] = 'xyzzy'
1330 env = Environment(platform = my_platform)
1333 Additionally, a specific set of tools
1334 with which to initialize the environment
1335 may specified as an optional keyword argument:
1338 env = Environment(tools = ['msvc', 'lex'])
1341 Non-built-in tools may be specified using the toolpath argument:
1344 env = Environment(tools = ['default', 'foo'], toolpath = ['tools'])
1347 This looks for a tool specification in tools/foo.py (as well as
1348 using the ordinary default tools for the platform). foo.py should
1349 have two functions: generate(env, **kw) and exists(env).
1353 modifies the passed-in environment
1354 to set up variables so that the tool
1356 it may use any keyword arguments
1357 that the user supplies (see below)
1358 to vary its initialization.
1361 function should return a true
1362 value if the tool is available.
1363 Tools in the toolpath are used before
1364 any of the built-in ones. For example, adding gcc.py to the toolpath
1365 would override the built-in gcc tool.
1366 Also note that the toolpath is
1367 stored in the environment for use
1375 base = Environment(toolpath=['custom_path'])
1376 derived = base.Clone(tools=['custom_tool'])
1377 derived.CustomBuilder()
1380 The elements of the tools list may also
1381 be functions or callable objects,
1382 in which case the Environment() method
1383 will call the specified elements
1384 to update the new construction environment:
1388 env['XYZZY'] = 'xyzzy'
1390 env = Environment(tools = [my_tool])
1393 The individual elements of the tools list
1394 may also themselves be two-element lists of the form
1395 .RI ( toolname ", " kw_dict ).
1396 SCons searches for the
1398 specification file as described above, and
1401 which must be a dictionary, as keyword arguments to the tool's
1406 function can use the arguments to modify the tool's behavior
1407 by setting up the environment in different ways
1408 or otherwise changing its initialization.
1411 # in tools/my_tool.py:
1412 def generate(env, **kw):
1413 # Sets MY_TOOL to the value of keyword argument 'arg1' or 1.
1414 env['MY_TOOL'] = kw.get('arg1', '1')
1419 env = Environment(tools = ['default', ('my_tool', {'arg1': 'abc'})],
1423 The tool definition (i.e. my_tool()) can use the PLATFORM variable from
1424 the environment it receives to customize the tool for different platforms.
1426 If no tool list is specified, then SCons will auto-detect the installed
1427 tools using the PATH variable in the ENV construction variable and the
1428 platform name when the Environment is constructed. Changing the PATH
1429 variable after the Environment is constructed will not cause the tools to
1432 SCons supports the following tool specifications out of the box:
1508 Additionally, there is a "tool" named
1510 which configures the
1511 environment with a default set of tools for the current platform.
1513 On posix and cygwin platforms
1514 the GNU tools (e.g. gcc) are preferred by SCons,
1515 on Windows the Microsoft tools (e.g. msvc)
1516 followed by MinGW are preferred by SCons,
1517 and in OS/2 the IBM tools (e.g. icc) are preferred by SCons.
1521 Build rules are specified by calling a construction
1522 environment's builder methods.
1523 The arguments to the builder methods are
1525 (a list of target files)
1528 (a list of source files).
1530 Because long lists of file names
1531 can lead to a lot of quoting,
1536 and a same-named environment method
1537 that split a single string
1538 into a list, separated on
1539 strings of white-space characters.
1540 (These are similar to the
1541 string.split() method
1542 from the standard Python library,
1543 but work even if the input isn't a string.)
1545 Like all Python arguments,
1546 the target and source arguments to a builder method
1547 can be specified either with or without
1548 the "target" and "source" keywords.
1549 When the keywords are omitted,
1550 the target is first,
1551 followed by the source.
1552 The following are equivalent examples of calling the Program builder method:
1555 env.Program('bar', ['bar.c', 'foo.c'])
1556 env.Program('bar', Split('bar.c foo.c'))
1557 env.Program('bar', env.Split('bar.c foo.c'))
1558 env.Program(source = ['bar.c', 'foo.c'], target = 'bar')
1559 env.Program(target = 'bar', Split('bar.c foo.c'))
1560 env.Program(target = 'bar', env.Split('bar.c foo.c'))
1561 env.Program('bar', source = string.split('bar.c foo.c'))
1564 When the target shares the same base name
1565 as the source and only the suffix varies,
1566 and if the builder method has a suffix defined for the target file type,
1567 then the target argument may be omitted completely,
1570 will deduce the target file name from
1571 the source file name.
1572 The following examples all build the
1578 (on Windows systems)
1579 from the bar.c source file:
1582 env.Program(target = 'bar', source = 'bar.c')
1583 env.Program('bar', source = 'bar.c')
1584 env.Program(source = 'bar.c')
1585 env.Program('bar.c')
1590 keyword argument may be specified
1591 when calling a Builder.
1593 all source file strings that are not absolute paths
1594 will be interpreted relative to the specified
1596 The following example will build the
1601 program from the files
1607 env.Program('build/prog', ['f1.c', 'f2.c'], srcdir='src')
1610 It is possible to override or add construction variables when calling a
1611 builder method by passing additional keyword arguments.
1612 These overridden or added
1613 variables will only be in effect when building the target, so they will not
1614 affect other parts of the build. For example, if you want to add additional
1615 libraries for just one program:
1618 env.Program('hello', 'hello.c', LIBS=['gl', 'glut'])
1621 or generate a shared library with a non-standard suffix:
1624 env.SharedLibrary('word', 'word.cpp',
1626 LIBSUFFIXES=['.ocx'])
1629 (Note that both the $SHLIBSUFFIX and $LIBSUFFIXES variables must be set
1630 if you want SCons to search automatically
1631 for dependencies on the non-standard library names;
1632 see the descriptions of these variables, below, for more information.)
1634 Although the builder methods defined by
1637 methods of a construction environment object,
1638 they may also be called without an explicit environment:
1641 Program('hello', 'hello.c')
1642 SharedLibrary('word', 'word.cpp')
1646 the methods are called internally using a default construction
1647 environment that consists of the tools and values that
1649 has determined are appropriate for the local system.
1651 Builder methods that can be called without an explicit
1652 environment may be called from custom Python modules that you
1653 import into an SConscript file by adding the following
1654 to the Python module:
1657 from SCons.Script import *
1660 All builder methods return a list of Nodes
1661 that represent the target or targets that will be built.
1664 is an internal SCons object
1666 build targets or sources.
1668 The returned Node(s)
1669 can be passed to other builder methods as source(s)
1670 or passed to any SCons function or method
1671 where a filename would normally be accepted.
1672 For example, if it were necessary
1675 flag when compiling one specific object file:
1678 bar_obj_list = env.StaticObject('bar.c', CPPDEFINES='-DBAR')
1679 env.Program(source = ['foo.c', bar_obj_list, 'main.c'])
1682 Using a Node in this way
1683 makes for a more portable build
1684 by avoiding having to specify
1685 a platform-specific object suffix
1686 when calling the Program() builder method.
1688 Note that Builder calls will automatically "flatten"
1689 the source and target file lists,
1690 so it's all right to have the bar_obj list
1691 return by the StaticObject() call
1692 in the middle of the source file list.
1693 If you need to manipulate a list of lists returned by Builders
1694 directly using Python,
1695 you can either build the list by hand:
1698 foo = Object('foo.c')
1699 bar = Object('bar.c')
1700 objects = ['begin.o'] + foo + ['middle.o'] + bar + ['end.o']
1701 for object in objects:
1708 to create a list containing just the Nodes,
1709 which may be more convenient:
1712 foo = Object('foo.c')
1713 bar = Object('bar.c')
1714 objects = Flatten(['begin.o', foo, 'middle.o', bar, 'end.o'])
1715 for object in objects:
1719 The path name for a Node's file may be used
1720 by passing the Node to the Python-builtin
1725 bar_obj_list = env.StaticObject('bar.c', CPPDEFINES='-DBAR')
1726 print "The path to bar_obj is:", str(bar_obj_list[0])
1729 Note again that because the Builder call returns a list,
1730 we have to access the first element in the list
1731 .B (bar_obj_list[0])
1732 to get at the Node that actually represents
1735 Builder calls support a
1737 keyword argument that
1738 specifies that the Builder's action(s)
1740 after changing directory.
1744 a string or a directory Node,
1745 scons will change to the specified directory.
1748 is not a string or Node
1750 then scons will change to the
1751 target file's directory.
1754 # scons will change to the "sub" subdirectory
1755 # before executing the "cp" command.
1756 env.Command('sub/dir/foo.out', 'sub/dir/foo.in',
1757 "cp dir/foo.in dir/foo.out",
1760 # Because chdir is not a string, scons will change to the
1761 # target's directory ("sub/dir") before executing the
1763 env.Command('sub/dir/foo.out', 'sub/dir/foo.in',
1764 "cp foo.in foo.out",
1768 Note that scons will
1770 automatically modify
1772 construction variables like
1776 when using the chdir
1777 keyword argument--that is,
1778 the expanded file names
1779 will still be relative to
1780 the top-level SConstruct directory,
1781 and consequently incorrect
1782 relative to the chdir directory.
1783 If you use the chdir keyword argument,
1784 you will typically need to supply a different
1790 to use just the filename portion of the
1794 provides the following builder methods:
1796 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1797 '\" BEGIN GENERATED BUILDER DESCRIPTIONS
1799 '\" The descriptions below of the various SCons Builders are generated
1800 '\" from the .xml files that live next to the various Python modules in
1801 '\" the build enginer library. If you're reading this [gnt]roff file
1802 '\" with an eye towards patching this man page, you can still submit
1803 '\" a diff against this text, but it will have to be translated to a
1804 '\" diff against the underlying .xml file before the patch is actually
1805 '\" accepted. If you do that yourself, it will make it easier to
1806 '\" integrate the patch.
1808 '\" BEGIN GENERATED BUILDER DESCRIPTIONS
1809 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1811 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1812 '\" END GENERATED BUILDER DESCRIPTIONS
1814 '\" The descriptions above of the various SCons Builders are generated
1815 '\" from the .xml files that live next to the various Python modules in
1816 '\" the build enginer library. If you're reading this [gnt]roff file
1817 '\" with an eye towards patching this man page, you can still submit
1818 '\" a diff against this text, but it will have to be translated to a
1819 '\" diff against the underlying .xml file before the patch is actually
1820 '\" accepted. If you do that yourself, it will make it easier to
1821 '\" integrate the patch.
1823 '\" END GENERATED BUILDER DESCRIPTIONS
1824 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1827 targets of builder methods automatically depend on their sources.
1828 An explicit dependency can
1829 be specified using the
1831 method of a construction environment (see below).
1836 source files for various programming languages,
1837 so the dependencies do not need to be specified explicitly.
1838 By default, SCons can
1841 Fortran source files with
1843 (POSIX systems only),
1848 and assembly language files with
1850 (POSIX systems only),
1855 for C preprocessor dependencies.
1856 SCons also has default support
1857 for scanning D source files,
1858 You can also write your own Scanners
1859 to add support for additional source file types.
1860 These can be added to the default
1861 Scanner object used by
1867 Builders by adding them
1869 .B SourceFileScanner
1872 See the section "Scanner Objects,"
1873 below, for a more information about
1874 defining your own Scanner objects.
1876 .SS Methods and Functions to Do Things
1877 In addition to Builder methods,
1879 provides a number of other construction environment methods
1880 and global functions to
1881 manipulate the build configuration.
1883 Usually, a construction environment method
1884 and global function with the same name both exist
1885 so that you don't have to remember whether
1886 to a specific bit of functionality
1887 must be called with or without a construction environment.
1888 In the following list,
1889 if you call something as a global function
1892 .RI Function( arguments )
1894 and if you call something through a construction
1895 environment it looks like:
1897 .RI env.Function( arguments )
1899 If you can call the functionality in both ways,
1900 then both forms are listed.
1902 Global functions may be called from custom Python modules that you
1903 import into an SConscript file by adding the following
1904 to the Python module:
1907 from SCons.Script import *
1910 Except where otherwise noted,
1912 construction environment method
1914 provide the exact same functionality.
1915 The only difference is that,
1917 calling the functionality through a construction environment will
1918 substitute construction variables into
1919 any supplied strings.
1922 env = Environment(FOO = 'foo')
1926 the first call to the global
1928 function will actually add a target named
1930 to the list of default targets,
1931 while the second call to the
1933 construction environment method
1934 will expand the value
1935 and add a target named
1937 to the list of default targets.
1938 For more on construction variable expansion,
1939 see the next section on
1940 construction variables.
1942 Construction environment methods
1943 and global functions supported by
1947 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1949 .RI Action( action ", [" strfunction ", " varlist ])
1951 .RI env.Action( action ", [" strfunction ", " varlist ])
1952 Creates an Action object for
1955 See the section "Action Objects,"
1956 below, for a complete explanation of the arguments and behavior.
1960 form of the invocation will expand
1961 construction variables in any arguments strings,
1965 at the time it is called
1966 using the construction variables in the
1968 construction environment through which
1973 form delays all variable expansion
1974 until the Action object is actually used.
1976 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1978 .RI AddPostAction( target ", " action )
1980 .RI env.AddPostAction( target ", " action )
1981 Arranges for the specified
1987 The specified action(s) may be
1988 an Action object, or anything that
1989 can be converted into an Action object
1992 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1994 .RI AddPreAction( target ", " action )
1996 .RI env.AddPreAction( target ", " action )
1997 Arranges for the specified
2000 before the specified
2003 The specified action(s) may be
2004 an Action object, or anything that
2005 can be converted into an Action object
2008 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2010 .RI Alias( alias ", [" targets ", [" action ]])
2012 .RI env.Alias( alias ", [" targets ", [" action ]])
2013 Creates one or more phony targets that
2014 expand to one or more other targets.
2019 can be specified that will be executed
2020 whenever the any of the alias targets are out-of-date.
2021 Returns the Node object representing the alias,
2022 which exists outside of any file system.
2023 This Node object, or the alias name,
2024 may be used as a dependency of any other target,
2025 including another alias.
2027 can be called multiple times for the same
2028 alias to add additional targets to the alias,
2029 or additional actions to the list for this alias.
2033 Alias('install', '/usr/bin')
2034 Alias(['install', 'install-lib'], '/usr/local/lib')
2036 env.Alias('install', ['/usr/local/bin', '/usr/local/lib'])
2037 env.Alias('install', ['/usr/local/man'])
2039 env.Alias('update', ['file1', 'file2'], "update_database $SOURCES")
2042 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2044 .RI AllowSubstExceptions([ exception ", ...])"
2045 Specifies the exceptions that will be allowed
2046 when expanding construction variables.
2048 any construction variable expansions that generate a
2052 exception will expand to a
2054 (a null string) and not cause scons to fail.
2055 All exceptions not in the specified list
2056 will generate an error message
2057 and terminate processing.
2060 .B AllowSubstExceptions
2061 is called multiple times,
2062 each call completely overwrites the previous list
2063 of allowed exceptions.
2067 # Requires that all construction variable names exist.
2068 # (You may wish to do this if you want to enforce strictly
2069 # that all construction variables must be defined before use.)
2070 AllowSubstExceptions()
2072 # Also allow a string containing a zero-division expansion
2073 # like '${1 / 0}' to evalute to ''.
2074 AllowSubstExceptions(IndexError, NameError, ZeroDivisionError)
2077 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2079 .RI AlwaysBuild( target ", ...)"
2081 .RI env.AlwaysBuild( target ", ...)"
2084 so that it is always assumed to be out of date,
2085 and will always be rebuilt if needed.
2088 does not add its target(s) to the default target list,
2089 so the targets will only be built
2090 if they are specified on the command line,
2091 or are a dependent of a target specified on the command line--but
2094 be built if so specified.
2095 Multiple targets can be passed in to a single call to
2098 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2100 .RI env.Append( key = val ", [...])"
2101 Appends the specified keyword arguments
2102 to the end of construction variables in the environment.
2103 If the Environment does not have
2104 the specified construction variable,
2105 it is simply added to the environment.
2106 If the values of the construction variable
2107 and the keyword argument are the same type,
2108 then the two values will be simply added together.
2109 Otherwise, the construction variable
2110 and the value of the keyword argument
2111 are both coerced to lists,
2112 and the lists are added together.
2113 (See also the Prepend method, below.)
2116 env.Append(CCFLAGS = ' -g', FOO = ['foo.yyy'])
2119 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2121 .RI env.AppendENVPath( name ", " newpath ", [" envname ", " sep ])
2122 This appends new path elements to the given path in the
2123 specified external environment
2127 any particular path once (leaving the last one it encounters and
2128 ignoring the rest, to preserve path order),
2129 and to help assure this,
2130 will normalize all paths (using
2133 .BR os.path.normcase ).
2134 This can also handle the
2135 case where the given old path variable is a list instead of a
2136 string, in which case a list will be returned instead of a string.
2140 print 'before:',env['ENV']['INCLUDE']
2141 include_path = '/foo/bar:/foo'
2142 env.AppendENVPath('INCLUDE', include_path)
2143 print 'after:',env['ENV']['INCLUDE']
2147 after: /biz:/foo/bar:/foo
2150 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2152 .RI env.AppendUnique( key = val ", [...])"
2153 Appends the specified keyword arguments
2154 to the end of construction variables in the environment.
2155 If the Environment does not have
2156 the specified construction variable,
2157 it is simply added to the environment.
2158 If the construction variable being appended to is a list,
2159 then any value(s) that already exist in the
2160 construction variable will
2162 be added again to the list.
2165 env.AppendUnique(CCFLAGS = '-g', FOO = ['foo.yyy'])
2168 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2171 A factory function that
2172 returns a Builder object
2173 to be used to fetch source files
2175 The returned Builder
2176 is intended to be passed to the
2181 env.SourceCode('.', env.BitKeeper())
2184 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2186 .RI BuildDir( build_dir ", " src_dir ", [" duplicate ])
2188 .RI env.BuildDir( build_dir ", " src_dir ", [" duplicate ])
2189 This specifies a build directory
2191 in which to build all derived files
2192 that would normally be built under
2194 Multiple build directories can be set up for multiple build variants, for
2197 must be underneath the SConstruct file's directory,
2200 may not be underneath the
2203 The default behavior is for
2205 to duplicate all of the files in the tree underneath
2209 and then build the derived files within the copied tree.
2210 (The duplication is performed by
2212 depending on the platform; see also the
2215 This guarantees correct builds
2216 regardless of whether intermediate source files
2217 are generated during the build,
2218 where preprocessors or other scanners search
2220 or whether individual compilers or other invoked tools
2221 are hard-coded to put derived files in the same directory as source files.
2223 This behavior of making a complete copy of the source tree
2224 may be disabled by setting
2229 to invoke Builders using the
2230 path names of source files in
2232 and the path names of derived files within
2234 This is always more efficient than
2236 and is usually safe for most builds.
2240 may cause build problems
2241 if source files are generated during the build,
2242 if any invoked tools are hard-coded to
2243 put derived files in the same directory as the source files.
2245 Note that specifying a
2247 works most naturally
2248 with a subsidiary SConscript file
2249 in the source directory.
2251 you would then call the subsidiary SConscript file
2252 not in the source directory,
2257 had made a virtual copy of the source tree
2258 regardless of the value of
2260 This is how you tell
2262 which variant of a source tree to build.
2266 BuildDir('build-variant1', 'src')
2267 SConscript('build-variant1/SConscript')
2268 BuildDir('build-variant2', 'src')
2269 SConscript('build-variant2/SConscript')
2275 function, described below,
2277 specify a build directory
2278 in conjunction with calling a subsidiary
2281 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2283 .RI Builder( action ", [" arguments ])
2285 .RI env.Builder( action ", [" arguments ])
2286 Creates a Builder object for
2289 See the section "Builder Objects,"
2290 below, for a complete explanation of the arguments and behavior.
2294 form of the invocation will expand
2295 construction variables in any arguments strings,
2299 at the time it is called
2300 using the construction variables in the
2302 construction environment through which
2307 form delays all variable expansion
2308 until after the Builder object is actually called.
2310 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2312 .RI CacheDir( cache_dir )
2314 .RI env.CacheDir( cache_dir )
2317 will maintain a cache of derived files in
2319 The derived files in the cache will be shared
2320 among all the builds using the same
2328 finds a derived file that needs to be rebuilt,
2329 it will first look in the cache to see if a
2330 derived file has already been built
2331 from identical input files and an identical build action
2332 (as incorporated into the MD5 build signature).
2335 will retrieve the file from the cache.
2336 If the derived file is not present in the cache,
2339 then place a copy of the built file in the cache
2340 (identified by its MD5 build signature),
2341 so that it may be retrieved by other
2342 builds that need to build the same derived file
2343 from identical inputs.
2347 may be disabled for any invocation
2356 will place a copy of
2358 derived files in the cache,
2359 even if they already existed
2360 and were not built by this invocation.
2361 This is useful to populate a cache
2364 is added to a build,
2373 "Retrieved `file' from cache,"
2376 option is being used.
2381 will print the action that
2383 have been used to build the file,
2384 without any indication that
2385 the file was actually retrieved from the cache.
2386 This is useful to generate build logs
2387 that are equivalent regardless of whether
2388 a given derived file has been built in-place
2389 or retrieved from the cache.
2393 method can be used to disable caching of specific files. This can be
2394 useful if inputs and/or outputs of some tool are impossible to
2395 predict or prohibitively large.
2397 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2399 .RI Clean( targets ", " files_or_dirs )
2401 .RI env.Clean( targets ", " files_or_dirs )
2402 This specifies a list of files or directories which should be removed
2403 whenever the targets are specified with the
2405 command line option.
2406 The specified targets may be a list
2407 or an individual target.
2411 and create new targets or add files and directories to the
2412 clean list for the specified targets.
2414 Multiple files or directories should be specified
2415 either as separate arguments to the
2417 method, or as a list.
2419 will also accept the return value of any of the construction environment
2425 function overrides calling
2427 for the same target,
2428 and any targets passed to both functions will
2437 Clean('foo', ['bar', 'baz'])
2438 Clean('dist', env.Program('hello', 'hello.c'))
2439 Clean(['foo', 'bar'], 'something_else_to_clean')
2442 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2444 .RI Command( target ", " source ", " action ", [" key = val ", ...])"
2446 .RI env.Command( target ", " source ", " action ", [" key = val ", ...])"
2447 Executes a specific action
2448 (or list of actions)
2449 to build a target file or files.
2450 This is more convenient
2451 than defining a separate Builder object
2452 for a single special-case build.
2454 As a special case, the
2456 keyword argument can
2459 that will be used to scan the sources.
2463 if any of the sources will be directories
2464 that must be scanned on-disk for
2465 changes to files that aren't
2466 already specified in other Builder of function calls.)
2468 Any other keyword arguments specified override any
2469 same-named existing construction variables.
2471 An action can be an external command,
2472 specified as a string,
2473 or a callable Python object;
2474 see "Action Objects," below,
2475 for more complete information.
2476 Also note that a string specifying an external command
2477 may be preceded by an
2480 to suppress printing the command in question,
2484 to ignore the exit status of the external command.
2488 env.Command('foo.out', 'foo.in',
2489 "$FOO_BUILD < $SOURCES > $TARGET")
2491 env.Command('bar.out', 'bar.in',
2493 "$BAR_BUILD < $SOURCES > $TARGET"],
2494 ENV = {'PATH' : '/usr/local/bin/'})
2496 def rename(env, target, source):
2498 os.rename('.tmp', str(target[0]))
2500 env.Command('baz.out', 'baz.in',
2501 ["$BAZ_BUILD < $SOURCES > .tmp",
2508 function will usually assume, by default,
2509 that the specified targets and/or sources are Files,
2510 if no other part of the configuration
2511 identifies what type of entry it is.
2512 If necessary, you can explicitly specify
2513 that targets or source nodes should
2514 be treated as directoriese
2522 env.Command('ddd.list', Dir('ddd'), 'ls -l $SOURCE > $TARGET')
2524 env['DISTDIR'] = 'destination/directory'
2525 env.Command(env.Dir('$DISTDIR')), None, make_distdir)
2529 (Also note that SCons will usually
2530 automatically create any directory necessary to hold a target file,
2531 so you normally don't need to create directories by hand.)
2533 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2535 .RI Configure( env ", [" custom_tests ", " conf_dir ", " log_file ", " config_h ])
2537 .RI env.Configure([ custom_tests ", " conf_dir ", " log_file ", " config_h ])
2538 Creates a Configure object for integrated
2539 functionality similar to GNU autoconf.
2540 See the section "Configure Contexts,"
2541 below, for a complete explanation of the arguments and behavior.
2543 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2545 .RI env.Clone([ key = val ", ...])"
2546 Return a separate copy of a construction environment.
2547 If there are any keyword arguments specified,
2548 they are added to the returned copy,
2549 overwriting any existing values
2554 env3 = env.Clone(CCFLAGS = '-g')
2557 Additionally, a list of tools and a toolpath may be specified, as in
2558 the Environment constructor:
2561 def MyTool(env): env['FOO'] = 'bar'
2562 env4 = env.Clone(tools = ['msvc', MyTool])
2565 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2567 .RI env.Copy([ key = val ", ...])"
2570 (This will probably be officially deprecated some day.)
2572 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2574 .RI env.CVS( repository ", " module )
2575 A factory function that
2576 returns a Builder object
2577 to be used to fetch source files
2581 The returned Builder
2582 is intended to be passed to the
2586 The optional specified
2588 will be added to the beginning
2589 of all repository path names;
2590 this can be used, in essence,
2591 to strip initial directory names
2592 from the repository path names,
2593 so that you only have to
2594 replicate part of the repository
2595 directory hierarchy in your
2596 local build directory:
2599 # Will fetch foo/bar/src.c
2600 # from /usr/local/CVSROOT/foo/bar/src.c.
2601 env.SourceCode('.', env.CVS('/usr/local/CVSROOT'))
2603 # Will fetch bar/src.c
2604 # from /usr/local/CVSROOT/foo/bar/src.c.
2605 env.SourceCode('.', env.CVS('/usr/local/CVSROOT', 'foo'))
2608 # from /usr/local/CVSROOT/foo/bar/src.c.
2609 env.SourceCode('.', env.CVS('/usr/local/CVSROOT', 'foo/bar'))
2612 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2614 .RI Default( targets )
2616 .RI env.Default( targets )
2617 This specifies a list of default targets,
2618 which will be built by
2620 if no explicit targets are given on the command line.
2624 and add to the list of default targets.
2626 Multiple targets should be specified as
2627 separate arguments to the
2629 method, or as a list.
2631 will also accept the Node returned by any
2632 of a construction environment's
2637 Default('foo', 'bar', 'baz')
2638 env.Default(['a', 'b', 'c'])
2639 hello = env.Program('hello', 'hello.c')
2647 will clear all default targets.
2650 will add to the (now empty) default-target list
2653 The current list of targets added using the
2655 function or method is available in the
2660 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2662 .RI DefaultEnvironment([ args ])
2663 Creates and returns a default construction environment object.
2664 This construction environment is used internally by SCons
2665 in order to execute many of the global functions in this list,
2666 and to fetch source files transparently
2667 from source code management systems.
2669 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2671 .RI Depends( target ", " dependency )
2673 .RI env.Depends( target ", " dependency )
2674 Specifies an explicit dependency;
2675 the target file(s) will be rebuilt
2676 whenever the dependency file(s) has changed.
2677 This should only be necessary
2678 for cases where the dependency
2679 is not caught by a Scanner
2683 env.Depends('foo', 'other-input-file-for-foo')
2686 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2688 .RI env.Dictionary([ vars ])
2689 Returns a dictionary object
2690 containing copies of all of the
2691 construction variables in the environment.
2692 If there are any variable names specified,
2693 only the specified construction
2694 variables are returned in the dictionary.
2697 dict = env.Dictionary()
2698 cc_dict = env.Dictionary('CC', 'CCFLAGS', 'CCCOM')
2701 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2703 .RI Dir( name ", [" directory ])
2705 .RI env.Dir( name ", [" directory ])
2706 This returns a Directory Node,
2707 an object that represents the specified directory
2710 can be a relative or absolute path.
2712 is an optional directory that will be used as the parent directory.
2715 is specified, the current script's directory is used as the parent.
2717 Directory Nodes can be used anywhere you
2718 would supply a string as a directory name
2719 to a Builder method or function.
2720 Directory Nodes have attributes and methods
2721 that are useful in many situations;
2722 see "File and Directory Nodes," below.
2724 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2726 .RI env.Dump([ key ])
2727 Returns a pretty printable representation of the environment.
2731 should be a string containing the name of the variable of interest.
2736 print env.Dump('CCCOM')
2741 '$CC $CCFLAGS $CPPFLAGS $_CPPDEFFLAGS $_CPPINCFLAGS -c -o $TARGET $SOURCES'
2752 'ARCOM': '$AR $ARFLAGS $TARGET $SOURCES\n$RANLIB $RANLIBFLAGS $TARGET',
2755 'ASCOM': '$AS $ASFLAGS -o $TARGET $SOURCES',
2760 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2762 .RI EnsurePythonVersion( major ", " minor )
2764 .RI env.EnsurePythonVersion( major ", " minor )
2765 Ensure that the Python version is at least
2768 print out an error message and exit SCons with a non-zero exit code if the
2769 actual Python version is not late enough.
2772 EnsurePythonVersion(2,2)
2775 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2777 .RI EnsureSConsVersion( major ", " minor ", [" revision ])
2779 .RI env.EnsureSConsVersion( major ", " minor ", [" revision ])
2780 Ensure that the SCons version is at least
2783 .IR major.minor.revision .
2788 print out an error message and exit SCons with a non-zero exit code if the
2789 actual SCons version is not late enough.
2792 EnsureSConsVersion(0,14)
2794 EnsureSConsVersion(0,96,90)
2797 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2799 .RI Environment([ key = value ", ...])"
2801 .RI env.Environment([ key = value ", ...])"
2802 Return a new construction environment
2803 initialized with the specified
2807 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2809 .RI Execute( action ", [" strfunction ", " varlist ])
2811 .RI env.Execute( action ", [" strfunction ", " varlist ])
2812 Executes an Action object.
2815 may be an Action object
2816 (see the section "Action Objects,"
2817 below, for a complete explanation of the arguments and behavior),
2818 or it may be a command-line string,
2820 or executable Python function,
2821 each of which will be converted
2822 into an Action object
2824 The exit value of the command
2825 or return value of the Python function
2828 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2832 .RI env.Exit([ value ])
2838 A default exit value of
2841 is used if no value is specified.
2843 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2847 .RI env.Export( vars )
2850 to export a list of variables from the current
2851 SConscript file to all other SConscript files.
2852 The exported variables are kept in a global collection,
2853 so subsequent calls to
2855 will over-write previous exports that have the same name.
2856 Multiple variable names can be passed to
2858 as separate arguments or as a list. A dictionary can be used to map
2859 variables to a different name when exported. Both local variables and
2860 global variables can be exported.
2865 # Make env available for all SConscript files to Import().
2869 # Make env and package available for all SConscript files:.
2870 Export("env", "package")
2872 # Make env and package available for all SConscript files:
2873 Export(["env", "package"])
2875 # Make env available using the name debug:.
2876 Export({"debug":env})
2882 function supports an
2884 argument that makes it easier to to export a variable or
2885 set of variables to a single SConscript file.
2886 See the description of the
2890 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2892 .RI File( name ", [" directory ])
2894 .RI env.File( name ", [" directory ])
2897 an object that represents the specified file
2900 can be a relative or absolute path.
2902 is an optional directory that will be used as the parent directory.
2904 File Nodes can be used anywhere you
2905 would supply a string as a file name
2906 to a Builder method or function.
2907 File Nodes have attributes and methods
2908 that are useful in many situations;
2909 see "File and Directory Nodes," below.
2911 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2913 .RI FindFile( file ", " dirs )
2915 .RI env.FindFile( file ", " dirs )
2918 in the path specified by
2921 may be a list of file names or a single file name. In addition to searching
2922 for files that exist in the filesytem, this function also searches for
2923 derived files that have not yet been built.
2926 foo = env.FindFile('foo', ['dir1', 'dir2'])
2929 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2931 .RI FindPathDirs( variable )
2933 (actually a callable Python object)
2934 intended to be used as the
2936 of a Scanner object.
2937 The returned object will look up the specified
2939 in a construction environment
2940 and treat the construction variable's value as a list of
2941 directory paths that should be searched
2949 is generally preferable to
2952 for the following reasons:
2953 1) The returned list will contain all appropriate directories
2954 found in source trees
2958 or in code repositories
2964 2) scons will identify expansions of
2966 that evaluate to the same list of directories as,
2967 in fact, the same list,
2968 and avoid re-scanning the directories for files,
2974 def my_scan(node, env, path, arg):
2975 # Code to scan file contents goes here...
2976 return include_files
2978 scanner = Scanner(name = 'myscanner',
2980 path_function = FindPathDirs('MYPATH'))
2983 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2985 .RI Flatten( sequence )
2987 .RI env.Flatten( sequence )
2988 Takes a sequence (that is, a Python list or tuple)
2989 that may contain nested sequences
2990 and returns a flattened list containing
2991 all of the individual elements in any sequence.
2992 This can be helpful for collecting
2993 the lists returned by calls to Builders;
2994 other Builders will automatically
2995 flatten lists specified as input,
2996 but direct Python manipulation of
2997 these lists does not:
3000 foo = Object('foo.c')
3001 bar = Object('bar.c')
3003 # Because `foo' and `bar' are lists returned by the Object() Builder,
3004 # `objects' will be a list containing nested lists:
3005 objects = ['f1.o', foo, 'f2.o', bar, 'f3.o']
3007 # Passing such a list to another Builder is all right because
3008 # the Builder will flatten the list automatically:
3009 Program(source = objects)
3011 # If you need to manipulate the list directly using Python, you need to
3012 # call Flatten() yourself, or otherwise handle nested lists:
3013 for object in Flatten(objects):
3017 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3019 .RI GetBuildPath( file ", [" ... ])
3021 .RI env.GetBuildPath( file ", [" ... ])
3024 path name (or names) for the specified
3032 Nodes or strings representing path names.
3034 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3038 .RI env.GetLaunchDir()
3039 Returns the absolute path name of the directory from which
3042 was initially invoked.
3043 This can be useful when using the
3048 options, which internally
3049 change to the directory in which the
3053 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3055 .RI GetOption( name )
3057 .RI env.GetOption( name )
3058 This function provides a way to query a select subset of the scons command line
3059 options from a SConscript file. See
3061 for a description of the options available.
3063 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3065 '\".RI GlobalBuilders( flag )
3069 '\"adds the names of the default builders
3070 '\"(Program, Library, etc.)
3071 '\"to the global name space
3072 '\"so they can be called without an explicit construction environment.
3073 '\"(This is the default.)
3077 '\"the names of the default builders are removed
3078 '\"from the global name space
3079 '\"so that an explicit construction environment is required
3080 '\"to call all builders.
3082 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3086 .RI env.Help( text )
3087 This specifies help text to be printed if the
3089 argument is given to
3093 is called multiple times, the text is appended together in the order
3098 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3100 .RI Ignore( target ", " dependency )
3102 .RI env.Ignore( target ", " dependency )
3103 The specified dependency file(s)
3104 will be ignored when deciding if
3105 the target file(s) need to be rebuilt.
3108 env.Ignore('foo', 'foo.c')
3109 env.Ignore('bar', ['bar1.h', 'bar2.h'])
3112 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3116 .RI env.Import( vars )
3119 to import a list of variables into the current SConscript file. This
3120 will import variables that were exported with
3126 Variables exported by
3129 Multiple variable names can be passed to
3131 as separate arguments or as a list. The variable "*" can be used
3132 to import all variables.
3137 Import("env", "variable")
3138 Import(["env", "variable"])
3142 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3144 .RI Install( dir ", " source )
3146 .RI env.Install( dir ", " source )
3147 Installs one or more source files or directories
3148 in a destination directory
3150 The names of the specified source files or directories
3151 remain the same within the destination directory.
3154 env.Install(dir = '/usr/local/bin', source = ['foo', 'bar'])
3157 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3159 .RI InstallAs( target ", " source )
3161 .RI env.InstallAs( target ", " source )
3162 Installs one or more source files or directories
3164 allowing changing a file or directory name
3165 as part of the installation.
3166 It is an error if the
3170 arguments list different numbers of files or directories.
3173 env.InstallAs(target = '/usr/local/bin/foo',
3174 source = 'foo_debug')
3175 env.InstallAs(target = ['../lib/libfoo.a', '../lib/libbar.a'],
3176 source = ['libFOO.a', 'libBAR.a'])
3179 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3181 .RI Literal( string )
3183 .RI env.Literal( string )
3186 will be preserved as-is
3187 and not have construction variables expanded.
3189 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3191 .RI Local( targets )
3193 .RI env.Local( targets )
3196 will have copies made in the local tree,
3197 even if an already up-to-date copy
3198 exists in a repository.
3199 Returns a list of the target Node or Nodes.
3201 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3203 .RI env.MergeFlags( arg ", [" unique ])
3204 Merges the specified
3206 values to the construction envrionment's construction variables.
3209 argument is not a dictionary,
3210 it is converted to one by calling
3213 before the values are merged.
3216 must be a single value,
3217 so multiple strings must
3218 be passed in as a list,
3219 not as separate arguments to
3220 .BR env.MergeFlags ().
3223 duplicate values are eliminated;
3224 you can, however, specify
3228 When eliminating duplicate values,
3229 any construction variables that end with
3232 keep the left-most unique value.
3233 All other construction variables keep
3234 the right-most unique value.
3239 # Add an optimization flag to $CCFLAGS.
3240 env.MergeFlags('-O3')
3242 # Combine the flags returned from running pkg-config with an optimization
3243 # flag and merge the result into the construction variables.
3244 env.MergeFlags(['!pkg-config gtk+-2.0 --cflags', '-O3'])
3246 env.MergeFlags(['-O3',
3247 '!pkg-config gtk+-2.0 --cflags --libs',
3248 '!pkg-config libpng12 --cflags --libs'])
3251 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3253 .RI NoCache( target ", ...)"
3255 .RI env.NoCache( target ", ...)"
3256 Specifies a list of files which should
3258 be cached whenever the
3260 method has been activated.
3261 The specified targets may be a list
3262 or an individual target.
3264 Multiple files should be specified
3265 either as separate arguments to the
3267 method, or as a list.
3269 will also accept the return value of any of the construction environment
3274 on directories and other non-File Node types has no effect because
3275 only File Nodes are cached.
3281 NoCache(env.Program('hello', 'hello.c'))
3284 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3286 .RI NoClean( target ", ...)"
3288 .RI env.NoClean( target ", ...)"
3289 Specifies a list of files or directories which should
3291 be removed whenever the targets (or their dependencies)
3292 are specified with the
3294 command line option.
3295 The specified targets may be a list
3296 or an individual target.
3300 and prevent each specified target
3301 from being removed by calls to the
3305 Multiple files or directories should be specified
3306 either as separate arguments to the
3308 method, or as a list.
3310 will also accept the return value of any of the construction environment
3315 for a target overrides calling
3317 for the same target,
3318 and any targets passed to both functions will
3328 NoClean(env.Program('hello', 'hello.c'))
3331 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3333 .RI env.ParseConfig( command ", [" function ", " unique ])
3336 to modify the environment as specified by the output of
3341 .BR env.MergeFlags (),
3342 which expects the output of a typical
3346 and adds the options
3347 to the appropriate construction variables.
3349 duplicate values are not
3350 added to any construction variables;
3357 and the construction variables they affect
3358 are as specified for the
3359 .BR env.ParseFlags ()
3360 method (which thie method calls).
3361 See that method's description, below,
3362 for a table of options and construction variables.
3364 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3366 .RI ParseDepends( filename ", [" must_exist ", " only_one ])
3368 .RI env.ParseDepends( filename ", [" must_exist ", " only_one ])
3369 Parses the contents of the specified
3371 as a list of dependencies in the style of
3375 and explicitly establishes all of the listed dependencies.
3384 argument may be set to a non-zero
3387 throw an exception and
3388 generate an error if the file does not exist,
3389 or is otherwise inaccessible.
3393 argument may be set to a non-zero
3396 thrown an exception and
3398 if the file contains dependency
3399 information for more than one target.
3400 This can provide a small sanity check
3401 for files intended to be generated
3402 by, for example, the
3405 which should typically only
3406 write dependency information for
3407 one output file into a corresponding
3413 and all of the files listed therein
3414 will be interpreted relative to
3415 the directory of the
3417 file which calls the
3421 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3423 .RI env.ParseFlags( flags ", ...)"
3424 Parses one or more strings containing
3425 typical command-line flags for GCC tool chains
3426 and returns a dictionary with the flag values
3427 separated into the appropriate SCons construction variables.
3428 This is intended as a companion to the
3429 .BR env.MergeFlags ()
3430 method, but allows for the values in the returned dictionary
3431 to be modified, if necessary,
3432 before merging them into the construction environment.
3434 .BR env.MergeFlags ()
3435 will call this method if its argument is not a dictionary,
3436 so it is usually not necessary to call
3437 .BR env.ParseFlags ()
3438 directly unless you want to manipulate the values.)
3440 If the first character in any string is
3441 an exclamation mark (!),
3442 the rest of the string is executed as a command,
3443 and the output from the command is
3444 parsed as GCC tool chain command-line flags
3445 and added to the resulting dictionary.
3447 Flag values are translated accordig to the prefix found,
3448 and added to the following construction variables:
3451 -arch CCFLAGS, LINKFLAGS
3453 -framework FRAMEWORKS
3454 -frameworkdir= FRAMEWORKPATH
3456 -isysroot CCFLAGS, LINKFLAGS
3460 -mno-cygwin CCFLAGS, LINKFLAGS
3462 -pthread CCFLAGS, LINKFLAGS
3464 -Wa, ASFLAGS, CCFLAGS
3471 + CCFLAGS, LINKFLAGS
3475 Any other strings not associated with options
3476 are assumed to be the names of libraries
3479 construction variable.
3481 Examples (all of which produce the same result):
3484 dict = env.ParseFlags('-O2 -Dfoo -Dbar=1')
3485 dict = env.ParseFlags('-O2', '-Dfoo', '-Dbar=1')
3486 dict = env.ParseFlags(['-O2', '-Dfoo -Dbar=1'])
3487 dict = env.ParseFlags('-O2', '!echo -Dfoo -Dbar=1')
3490 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3493 A factory function that
3494 returns a Builder object
3495 to be used to fetch source files
3496 from the Perforce source code management system.
3497 The returned Builder
3498 is intended to be passed to the
3503 env.SourceCode('.', env.Perforce())
3506 Perforce uses a number of external
3507 environment variables for its operation.
3508 Consequently, this function adds the
3509 following variables from the user's external environment
3510 to the construction environment's
3523 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3525 .RI Platform( string )
3526 Returns a callable object
3527 that can be used to initialize
3528 a construction environment using the
3529 platform keyword of the Environment() method:
3532 env = Environment(platform = Platform('win32'))
3535 .RI env.Platform( string )
3536 Applies the callable object for the specified platform
3538 to the environment through which the method was called.
3541 env.Platform('posix')
3550 variables from the user's external environment
3551 to the construction environment's
3554 This is so that any executed commands
3555 that use sockets to connect with other systems
3556 (such as fetching source files from
3557 external CVS repository specifications like
3558 .BR :pserver:anonymous@cvs.sourceforge.net:/cvsroot/scons )
3559 will work on Windows systems.
3561 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3563 .RI Precious( target ", ...)"
3565 .RI env.Precious( target ", ...)"
3568 as precious so it is not deleted before it is rebuilt. Normally
3570 deletes a target before building it.
3571 Multiple targets can be passed in to a single call to
3574 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3576 .RI env.Prepend( key = val ", [...])"
3577 Appends the specified keyword arguments
3578 to the beginning of construction variables in the environment.
3579 If the Environment does not have
3580 the specified construction variable,
3581 it is simply added to the environment.
3582 If the values of the construction variable
3583 and the keyword argument are the same type,
3584 then the two values will be simply added together.
3585 Otherwise, the construction variable
3586 and the value of the keyword argument
3587 are both coerced to lists,
3588 and the lists are added together.
3589 (See also the Append method, above.)
3592 env.Prepend(CCFLAGS = '-g ', FOO = ['foo.yyy'])
3595 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3597 .RI env.PrependENVPath( name ", " newpath ", [" envname ", " sep ])
3598 This appends new path elements to the given path in the
3599 specified external environment
3603 any particular path once (leaving the first one it encounters and
3604 ignoring the rest, to preserve path order),
3605 and to help assure this,
3606 will normalize all paths (using
3609 .BR os.path.normcase ).
3610 This can also handle the
3611 case where the given old path variable is a list instead of a
3612 string, in which case a list will be returned instead of a string.
3616 print 'before:',env['ENV']['INCLUDE']
3617 include_path = '/foo/bar:/foo'
3618 env.PrependENVPath('INCLUDE', include_path)
3619 print 'after:',env['ENV']['INCLUDE']
3623 after: /foo/bar:/foo:/biz
3626 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3628 .RI env.PrependUnique( key = val ", [...])"
3629 Appends the specified keyword arguments
3630 to the beginning of construction variables in the environment.
3631 If the Environment does not have
3632 the specified construction variable,
3633 it is simply added to the environment.
3634 If the construction variable being appended to is a list,
3635 then any value(s) that already exist in the
3636 construction variable will
3638 be added again to the list.
3641 env.PrependUnique(CCFLAGS = '-g', FOO = ['foo.yyy'])
3644 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3647 A factory function that
3648 returns a Builder object
3649 to be used to fetch source files
3651 The returned Builder
3652 is intended to be passed to the
3657 env.SourceCode('.', env.RCS())
3662 will fetch source files
3663 from RCS subdirectories automatically,
3665 as demonstrated in the above example
3666 should only be necessary if
3667 you are fetching from
3670 directory as the source files,
3671 or if you need to explicitly specify RCS
3672 for a specific subdirectory.
3674 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3676 .RI env.Replace( key = val ", [...])"
3677 Replaces construction variables in the Environment
3678 with the specified keyword arguments.
3681 env.Replace(CCFLAGS = '-g', FOO = 'foo.xxx')
3684 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3686 .RI Repository( directory )
3688 .RI env.Repository( directory )
3691 is a repository to be searched for files.
3695 and each one adds to the list of
3696 repositories that will be searched.
3700 a repository is a copy of the source tree,
3701 from the top-level directory on down,
3703 both source files and derived files
3704 that can be used to build targets in
3705 the local source tree.
3706 The canonical example would be an
3707 official source tree maintained by an integrator.
3708 If the repository contains derived files,
3709 then the derived files should have been built using
3711 so that the repository contains the necessary
3712 signature information to allow
3714 to figure out when it is appropriate to
3715 use the repository copy of a derived file,
3716 instead of building one locally.
3718 Note that if an up-to-date derived file
3719 already exists in a repository,
3723 make a copy in the local directory tree.
3724 In order to guarantee that a local copy
3730 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3735 what variable(s) to use as the return value(s) of the current SConscript
3736 file. These variables will be returned to the "calling" SConscript file
3737 as the return value(s) of
3739 Multiple variable names should be passed to
3745 Return(["foo", "bar"])
3748 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3750 .RI Scanner( function ", [" argument ", " keys ", " path_function ", " node_class ", " node_factory ", " scan_check ", " recursive ])
3752 .RI env.Scanner( function ", [" argument ", " keys ", " path_function ", " node_class ", " node_factory ", " scan_check ", " recursive ])
3753 Creates a Scanner object for
3756 See the section "Scanner Objects,"
3757 below, for a complete explanation of the arguments and behavior.
3759 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3762 A factory function that
3763 returns a Builder object
3764 to be used to fetch source files
3766 The returned Builder
3767 is intended to be passed to the
3772 env.SourceCode('.', env.SCCS())
3777 will fetch source files
3778 from SCCS subdirectories automatically,
3780 as demonstrated in the above example
3781 should only be necessary if
3782 you are fetching from
3785 directory as the source files,
3786 or if you need to explicitly specify SCCS
3787 for a specific subdirectory.
3789 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3791 .RI SConscript( scripts ", [" exports ", " build_dir ", " src_dir ", " duplicate ])
3793 .RI env.SConscript( scripts ", [" exports ", " build_dir ", " src_dir ", " duplicate ])
3795 .RI SConscript(dirs= subdirs ", [name=" script ", " exports ", " build_dir ", " src_dir ", " duplicate ])
3797 .RI env.SConscript(dirs= subdirs ", [name=" script ", " exports ", " build_dir ", " src_dir ", " duplicate ])
3801 one or more subsidiary SConscript (configuration) files.
3802 There are two ways to call the
3806 The first way you can call
3808 is to explicitly specify one or more
3810 as the first argument.
3811 A single script may be specified as a string;
3812 multiple scripts must be specified as a list
3813 (either explicitly or as created by
3817 The second way you can call
3819 is to specify a list of (sub)directory names
3826 execute a subsidiary configuration file named
3828 in each of the specified directories.
3829 You may specify a name other than
3831 by supplying an optional
3837 argument provides a list of variable names or a dictionary of
3838 named values to export to the
3840 These variables are locally exported only to the specified
3842 and do not affect the
3843 global pool of variables used by
3847 '\"If multiple dirs are provided,
3848 '\"each script gets a fresh export.
3853 function to import the variables.
3857 argument specifies that all of the target files
3858 (for example, object files and executables)
3859 that would normally be built in the subdirectory in which
3861 resides should actually
3865 is interpreted relative to the directory
3866 of the calling SConscript file.
3870 argument specifies that the
3871 source files from which
3872 the target files should be built
3876 is interpreted relative to the directory
3877 of the calling SConscript file.
3881 will link or copy (depending on the platform)
3882 all the source files into the build directory.
3883 This behavior may be disabled by
3884 setting the optional
3887 (it is set to 1 by default),
3890 will refer directly to
3891 the source files in their source directory
3892 when building target files.
3895 is usually safe, and always more efficient
3898 but it may cause build problems in certain end-cases,
3899 such as compiling from source files that
3900 are generated by the build.)
3902 Any variables returned by
3906 will be returned by the call to
3912 SConscript('subdir/SConscript')
3913 foo = SConscript('sub/SConscript', exports='env')
3914 SConscript('dir/SConscript', exports=['env', 'variable'])
3915 SConscript('src/SConscript', build_dir='build', duplicate=0)
3916 SConscript('bld/SConscript', src_dir='src', exports='env variable')
3917 SConscript(dirs=['sub1', 'sub2'])
3918 SConscript(dirs=['sub3', 'sub4'], name='MySConscript')
3921 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3923 .RI SConscriptChdir( value )
3925 .RI env.SConscriptChdir( value )
3928 changes its working directory
3929 to the directory in which each
3930 subsidiary SConscript file lives.
3931 This behavior may be disabled
3932 by specifying either:
3936 env.SConscriptChdir(0)
3941 will stay in the top-level directory
3942 while reading all SConscript files.
3943 (This may be necessary when building from repositories,
3944 when all the directories in which SConscript files may be found
3945 don't necessarily exist locally.)
3947 You may enable and disable
3948 this ability by calling
3955 SConscript('foo/SConscript') # will not chdir to foo
3956 env.SConscriptChdir(1)
3957 SConscript('bar/SConscript') # will chdir to bar
3960 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3962 .RI SConsignFile([ file , dbm_module ])
3964 .RI env.SConsignFile([ file , dbm_module ])
3967 to store all file signatures
3968 in the specified database
3975 (The actual file name(s) stored on disk
3976 may have an appropriated suffix appended
3981 is not an absolute path name,
3982 the file is placed in the same directory as the top-level
3992 will store file signatures
3995 file in each directory,
3996 not in one global database file.
3997 (This was the default behavior
3998 prior to SCons 0.96.91 and 0.97.)
4002 argument can be used to specify
4003 which Python database module
4004 The default is to use a custom
4006 module that uses pickled
4007 Python data structures,
4008 and which works on all Python versions from 1.5.2 on.
4013 # Explicitly stores signatures in ".sconsign.dblite"
4014 # in the top-level SConstruct directory (the
4015 # default behavior).
4018 # Stores signatures in the file "etc/scons-signatures"
4019 # relative to the top-level SConstruct directory.
4020 SConsignFile("etc/scons-signatures")
4022 # Stores signatures in the specified absolute file name.
4023 SConsignFile("/home/me/SCons/signatures")
4025 # Stores signatures in a separate .sconsign file
4026 # in each directory.
4030 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4032 .RI env.SetDefault(key = val ", [...])"
4033 Sets construction variables to default values specified with the keyword
4034 arguments if (and only if) the variables are not already set.
4035 The following statements are equivalent:
4038 env.SetDefault(FOO = 'foo')
4040 if not env.has_key('FOO'): env['FOO'] = 'foo'
4043 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4045 .RI SetOption( name ", " value )
4047 .RI env.SetOption( name ", " value )
4048 This function provides a way to set a select subset of the scons command
4049 line options from a SConscript file. The options supported are:
4051 which corresponds to -c, --clean, and --remove;
4054 corresponds to --duplicate;
4056 which corresponds to --implicit-cache;
4058 which corresponds to --max-drift;
4060 which corresponds to -j and --jobs.
4061 See the documentation for the
4062 corresponding command line object for information about each specific
4066 SetOption('max_drift', 1)
4069 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4071 .RI SideEffect( side_effect ", " target )
4073 .RI env.SideEffect( side_effect ", " target )
4076 as a side effect of building
4082 can be a list, a file name, or a node.
4083 A side effect is a target that is created
4084 as a side effect of building other targets.
4085 For example, a Windows PDB
4086 file is created as a side effect of building the .obj
4087 files for a static library.
4088 If a target is a side effect of multiple build commands,
4090 will ensure that only one set of commands
4091 is executed at a time.
4092 Consequently, you only need to use this method
4093 for side-effect targets that are built as a result of
4094 multiple build commands.
4096 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4098 .RI SourceCode( entries ", " builder )
4100 .RI env.SourceCode( entries ", " builder )
4101 Arrange for non-existent source files to
4102 be fetched from a source code management system
4107 may be a Node, string or list of both,
4108 and may represent either individual
4109 source files or directories in which
4110 source files can be found.
4112 For any non-existent source files,
4114 will search up the directory tree
4124 will not use a builder to fetch
4125 source files for the specified
4129 builder has been specified
4130 for a directory higher up the tree.
4134 fetch files from SCCS or RCS subdirectories
4135 without explicit configuration.
4136 This takes some extra processing time
4137 to search for the necessary
4138 source code management files on disk.
4139 You can avoid these extra searches
4140 and speed up your build a little
4141 by disabling these searches as follows:
4144 env.SourceCode('.', None)
4148 Note that if the specified
4150 is one you create by hand,
4151 it must have an associated
4152 construction environment to use
4153 when fetching a source file.
4156 provides a set of canned factory
4157 functions that return appropriate
4158 Builders for various popular
4159 source code management systems.
4160 Canonical examples of invocation include:
4163 env.SourceCode('.', env.BitKeeper('/usr/local/BKsources'))
4164 env.SourceCode('src', env.CVS('/usr/local/CVSROOT'))
4165 env.SourceCode('/', env.RCS())
4166 env.SourceCode(['f1.c', 'f2.c'], env.SCCS())
4167 env.SourceCode('no_source.c', None)
4169 '\"env.SourceCode('.', env.Subversion('file:///usr/local/Subversion'))
4171 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4173 .RI env.subst( string ", [" raw ", " target ", " source ", " conv ])
4174 Performs construction variable interpolation
4175 on the specified string argument.
4178 leading or trailing white space will
4179 be removed from the result.
4180 and all sequences of white space
4181 will be compressed to a single space character.
4186 character sequences will be stripped from the returned string,
4189 argument may be set to
4191 if you want to preserve white space and
4196 argument may be set to
4198 if you want to strip
4199 all characters between
4205 (as is done for signature calculation).
4212 must be set to lists of
4213 target and source nodes, respectively,
4220 to be available for expansion.
4221 This is usually necessary if you are
4224 from within a Python function used
4228 all returned values are converted
4229 to their string representation.
4233 may specify a conversion function
4234 that will be used in place of
4236 For example, if you want Python objects
4237 (including SCons Nodes)
4238 to be returned as Python objects,
4239 you can use the Python
4241 idiom to pass in an unnamed function
4242 that simply returns its unconverted argument.
4245 print env.subst("The C compiler is: $CC")
4247 def compile(target, source, env):
4248 sourceDir = env.subst("${SOURCE.srcdir}",
4252 source_nodes = env.subst('$EXPAND_TO_NODELIST',
4256 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4258 '\".RI Subversion( repository ", " module )
4259 '\"A factory function that
4260 '\"returns a Builder object
4261 '\"to be used to fetch source files
4262 '\"from the specified Subversion
4264 '\"The returned Builder
4265 '\"is intended to be passed to the
4269 '\"The optional specified
4271 '\"will be added to the beginning
4272 '\"of all repository path names;
4273 '\"this can be used, in essence,
4274 '\"to strip initial directory names
4275 '\"from the repository path names,
4276 '\"so that you only have to
4277 '\"replicate part of the repository
4278 '\"directory hierarchy in your
4279 '\"local build directory:
4282 '\"# Will fetch foo/bar/src.c
4283 '\"# from /usr/local/Subversion/foo/bar/src.c.
4284 '\"env.SourceCode('.', env.Subversion('file:///usr/local/Subversion'))
4286 '\"# Will fetch bar/src.c
4287 '\"# from /usr/local/Subversion/foo/bar/src.c.
4288 '\"env.SourceCode('.', env.Subversion('file:///usr/local/Subversion', 'foo'))
4290 '\"# Will fetch src.c
4291 '\"# from /usr/local/Subversion/foo/bar/src.c.
4292 '\"env.SourceCode('.', env.Subversion('file:///usr/local/Subversion', 'foo/bar'))
4295 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4297 .RI SourceSignatures( type )
4299 .RI env.SourceSignatures( type )
4300 This function tells SCons what type of signature to use for source files:
4304 If the environment method is used,
4305 the specified type of source signature
4306 is only used when deciding whether targets
4307 built with that environment are up-to-date or must be rebuilt.
4308 If the global function is used,
4309 the specified type of source signature becomes the default
4310 used for all decisions
4311 about whether targets are up-to-date.
4313 "MD5" means the signature of a source file
4314 is the MD5 checksum of its contents.
4315 "timestamp" means the signature of a source file
4316 is its timestamp (modification time).
4317 There is no different between the two behaviors
4321 "MD5" signatures take longer to compute,
4322 but are more accurate than "timestamp" signatures.
4323 The default is "MD5".
4325 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4329 .RI env.Split( arg )
4330 Returns a list of file names or other objects.
4332 it will be split on strings of white-space characters
4334 making it easier to write long lists of file names.
4335 If arg is already a list,
4336 the list will be returned untouched.
4337 If arg is any other type of object,
4338 it will be returned as a list
4339 containing just the object.
4342 files = Split("f1.c f2.c f3.c")
4343 files = env.Split("f4.c f5.c f6.c")
4351 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4353 .RI TargetSignatures( type )
4355 .RI env.TargetSignatures( type )
4356 This function tells SCons what type of signatures to use
4361 If the environment method is used,
4362 the specified type of signature is only used
4363 for targets built with that environment.
4364 If the global function is used,
4365 the specified type of signature becomes the default
4366 used for all target files that
4367 don't have an explicit target signature type
4368 specified for their environments.
4370 "build" means the signature of a target file
4371 is made by concatenating all of the
4372 signatures of all its source files.
4373 "content" means the signature of a target
4374 file is an MD5 checksum of its contents.
4375 "build" signatures are usually faster to compute,
4376 but "content" signatures can prevent unnecessary rebuilds
4377 when a target file is rebuilt to the exact same contents
4378 as the previous build.
4379 The default is "build".
4381 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4383 .RI Tool( string [, toolpath ", " **kw ])
4384 Returns a callable object
4385 that can be used to initialize
4386 a construction environment using the
4387 tools keyword of the Environment() method.
4388 The object may be called with a construction
4389 environment as an argument,
4390 in which case the object will
4391 add the necessary variables
4392 to the construction environment
4393 and the name of the tool will be added to the
4395 construction variable.
4397 Additional keyword arguments are passed to the tool's
4402 env = Environment(tools = [ Tool('msvc') ])
4406 t(env) # adds 'msvc' to the TOOLS variable
4407 u = Tool('opengl', toolpath = ['tools'])
4408 u(env) # adds 'opengl' to the TOOLS variable
4411 .RI env.Tool( string [, toolpath ", " **kw ])
4412 Applies the callable object for the specified tool
4414 to the environment through which the method was called.
4416 Additional keyword arguments are passed to the tool's
4422 env.Tool('opengl', toolpath = ['build/tools'])
4425 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4427 .RI Value( value ", [" built_value ])
4429 .RI env.Value( value ", [" built_value ])
4430 Returns a Node object representing the specified Python value. Value
4431 Nodes can be used as dependencies of targets. If the result of
4434 changes between SCons runs, any targets depending on
4436 will be rebuilt. When using timestamp source signatures, Value Nodes'
4437 timestamps are equal to the system time when the Node is created.
4439 The returned Value Node object has a
4441 method that can be used to "build" a Value Node
4442 by setting a new value.
4445 argument can be specified
4446 when the Value Node is created
4447 to indicate the Node should already be considered
4449 There is a corresponding
4451 method that will return the built value of the Node.
4454 def create(target, source, env):
4455 f = open(str(target[0]), 'wb')
4456 f.write('prefix=' + source[0].get_contents())
4458 prefix = ARGUMENTS.get('prefix', '/usr/local')
4460 env['BUILDERS']['Config'] = Builder(action = create)
4461 env.Config(target = 'package-config', source = Value(prefix))
4463 def build_value(target, source, env):
4464 target[0].write(source[0].get_contents())
4466 output = env.Value('before')
4467 input = env.Value('after')
4469 env['BUILDERS']['UpdateValue'] = Builder(action = build_value)
4470 env.UpdateValue(target = Value(output), source = Value(input))
4473 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4475 .RI WhereIs( program ", [" path ", " pathext ", " reject ])
4477 .RI env.WhereIs( program ", [" path ", " pathext ", " reject ])
4479 Searches for the specified executable
4481 returning the full path name to the program
4483 and returning None if not.
4484 Searches the specified
4486 the value of the calling environment's PATH
4487 (env['ENV']['PATH']),
4488 or the user's current external PATH
4489 (os.environ['PATH'])
4491 On Windows systems, searches for executable
4492 programs with any of the file extensions
4493 listed in the specified
4495 the calling environment's PATHEXT
4496 (env['ENV']['PATHEXT'])
4497 or the user's current PATHEXT
4498 (os.environ['PATHEXT'])
4506 .SS SConscript Variables
4507 In addition to the global functions and methods,
4509 supports a number of Python variables
4510 that can be used in SConscript files
4511 to affect how you want the build to be performed.
4512 These variables may be accessed from custom Python modules that you
4513 import into an SConscript file by adding the following
4514 to the Python module:
4517 from SCons.Script import *
4520 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4525 arguments specified on the command line.
4526 Each element in the list is a tuple
4528 .RI ( keyword , value )
4534 elements of the tuple
4536 subscripting for element
4540 of the tuple, respectively.
4543 print "first keyword, value =", ARGLIST[0][0], ARGLIST[0][1]
4544 print "second keyword, value =", ARGLIST[1][0], ARGLIST[1][1]
4545 third_tuple = ARGLIST[2]
4546 print "third keyword, value =", third_tuple[0], third_tuple[1]
4547 for key, value in ARGLIST:
4548 # process key and value
4551 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4554 A dictionary of all the
4556 arguments specified on the command line.
4557 The dictionary is not in order,
4558 and if a given keyword has
4559 more than one value assigned to it
4560 on the command line,
4561 the last (right-most) value is
4567 if ARGUMENTS.get('debug', 0):
4568 env = Environment(CCFLAGS = '-g')
4573 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4576 A list of the targets which
4578 will actually try to build,
4579 regardless of whether they were specified on
4580 the command line or via the
4583 The elements of this list may be strings
4585 nodes, so you should run the list through the Python
4587 function to make sure any Node path names
4588 are converted to strings.
4590 Because this list may be taken from the
4591 list of targets specified using the
4594 the contents of the list may change
4595 on each successive call to
4600 for additional information.
4603 if 'foo' in BUILD_TARGETS:
4604 print "Don't forget to test the `foo' program!"
4605 if 'special/program' in BUILD_TARGETS:
4606 SConscript('special')
4611 list only contains targets expected listed
4612 on the command line or via calls to the
4617 contain all dependent targets that will be built as
4618 a result of making the sure the explicitly-specified
4619 targets are up to date.
4621 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4623 COMMAND_LINE_TARGETS
4624 A list of the targets explicitly specified on
4626 If there are no targets specified on the command line,
4628 This can be used, for example,
4629 to take specific actions only
4630 when a certain target or targets
4631 is explicitly being built:
4634 if 'foo' in COMMAND_LINE_TARGETS:
4635 print "Don't forget to test the `foo' program!"
4636 if 'special/program' in COMMAND_LINE_TARGETS:
4637 SConscript('special')
4640 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4643 A list of the target
4645 that have been specified using the
4648 The elements of the list are nodes,
4649 so you need to run them through the Python
4651 function to get at the path name for each Node.
4654 print str(DEFAULT_TARGETS[0])
4655 if 'foo' in map(str, DEFAULT_TARGETS):
4656 print "Don't forget to test the `foo' program!"
4661 list change on on each successive call to the
4666 print map(str, DEFAULT_TARGETS) # originally []
4668 print map(str, DEFAULT_TARGETS) # now a node ['foo']
4670 print map(str, DEFAULT_TARGETS) # now a node ['foo', 'bar']
4672 print map(str, DEFAULT_TARGETS) # back to []
4675 Consequently, be sure to use
4677 only after you've made all of your
4680 or else simply be careful of the order
4681 of these statements in your SConscript files
4682 so that you don't look for a specific
4683 default target before it's actually been added to the list.
4685 .SS Construction Variables
4686 .\" XXX From Gary Ruben, 23 April 2002:
4687 .\" I think it would be good to have an example with each construction
4688 .\" variable description in the documentation.
4690 .\" CC The C compiler
4691 .\" Example: env["CC"] = "c68x"
4692 .\" Default: env["CC"] = "cc"
4694 .\" CCCOM The command line ...
4696 .\" To generate the compiler line c68x -ps -qq -mr -o $TARGET $SOURCES
4697 .\" env["CC"] = "c68x"
4698 .\" env["CFLAGS"] = "-ps -qq -mr"
4699 .\" env["CCCOM"] = "$CC $CFLAGS -o $TARGET $SOURCES
4701 .\" (I dunno what this is ;-)
4702 A construction environment has an associated dictionary of
4703 .I construction variables
4704 that are used by built-in or user-supplied build rules.
4705 Construction variables must follow the same rules for
4707 the initial character must be an underscore or letter,
4708 followed by any number of underscores, letters, or digits.
4710 A number of useful construction variables are automatically defined by
4711 scons for each supported platform, and additional construction variables
4712 can be defined by the user. The following is a list of the automatically
4713 defined construction variables:
4715 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4716 '\" BEGIN GENERATED CONSTRUCTION VARIABLE DESCRIPTIONS
4718 '\" The descriptions below of the various SCons contruction variables
4719 '\" are generated from the .xml files that live next to the various
4720 '\" Python modules in the build enginer library. If you're reading
4721 '\" this [gnt]roff file with an eye towards patching this man page,
4722 '\" you can still submit a diff against this text, but it will have to
4723 '\" be translated to a diff against the underlying .xml file before the
4724 '\" patch is actually accepted. If you do that yourself, it will make
4725 '\" it easier to integrate the patch.
4727 '\" BEGIN GENERATED CONSTRUCTION VARIABLE DESCRIPTIONS
4728 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4730 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4731 '\" END GENERATED CONSTRUCTION VARIABLE DESCRIPTIONS
4733 '\" The descriptions above of the various SCons contruction variables
4734 '\" are generated from the .xml files that live next to the various
4735 '\" Python modules in the build enginer library. If you're reading
4736 '\" this [gnt]roff file with an eye towards patching this man page,
4737 '\" you can still submit a diff against this text, but it will have to
4738 '\" be translated to a diff against the underlying .xml file before the
4739 '\" patch is actually accepted. If you do that yourself, it will make
4740 '\" it easier to integrate the patch.
4742 '\" END GENERATED CONSTRUCTION VARIABLE DESCRIPTIONS
4743 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4746 Construction variables can be retrieved and set using the
4748 method of the construction environment:
4751 dict = env.Dictionary()
4755 or using the [] operator:
4761 Construction variables can also be passed to the construction environment
4765 env = Environment(CC="cc")
4768 or when copying a construction environment using the
4773 env2 = env.Clone(CC="cl.exe")
4776 .SS Configure Contexts
4780 .I configure contexts,
4781 an integrated mechanism similar to the
4782 various AC_CHECK macros in GNU autoconf
4783 for testing for the existence of C header
4784 files, libraries, etc.
4785 In contrast to autoconf,
4787 does not maintain an explicit cache of the tested values,
4788 but uses its normal dependency tracking to keep the checked values
4789 up to date. However, users may override this behaviour with the
4791 command line option.
4793 The following methods can be used to perform checks:
4796 .RI Configure( env ", [" custom_tests ", " conf_dir ", " log_file ", " config_h ])
4798 .RI env.Configure([ custom_tests ", " conf_dir ", " log_file ", " config_h ])
4799 This creates a configure context, which can be used to perform checks.
4801 specifies the environment for building the tests.
4802 This environment may be modified when performing checks.
4804 is a dictionary containing custom tests.
4805 See also the section about custom tests below.
4806 By default, no custom tests are added to the configure context.
4808 specifies a directory where the test cases are built.
4809 Note that this directory is not used for building
4811 The default value is the directory
4814 specifies a file which collects the output from commands
4815 that are executed to check for the existence of header files, libraries, etc.
4816 The default is the file #/config.log.
4817 If you are using the
4820 you may want to specify a subdirectory under your build directory.
4822 specifies a C header file where the results of tests
4823 will be written, e.g. #define HAVE_STDIO_H, #define HAVE_LIBM, etc.
4824 The default is to not write a
4827 You can specify the same
4829 file in multiple calls to Configure,
4832 will concatenate all results in the specified file.
4834 uses its normal dependency checking
4835 to decide if it's necessary to rebuild
4839 This means that the file is not necessarily re-built each
4841 but is only rebuilt if its contents will have changed
4842 and some target that depends on the
4844 file is being built.
4849 instance has the following associated methods:
4852 .RI Configure.Finish( self )
4853 This method should be called after configuration is done.
4854 It returns the environment as modified
4855 by the configuration checks performed.
4856 After this method is called, no further checks can be performed
4857 with this configuration context.
4858 However, you can create a new
4860 context to perform additional checks.
4861 Only one context should be active at a time.
4863 The following Checks are predefined.
4864 (This list will likely grow larger as time
4865 goes by and developers contribute new useful tests.)
4868 .RI Configure.CheckHeader( self ", " header ", [" include_quotes ", " language ])
4871 is usable in the specified language.
4874 in which case the last item in the list
4875 is the header file to be checked,
4876 and the previous list items are
4879 lines should precede the
4880 header line being checked for.
4881 The optional argument
4884 a two character string, where the first character denotes the opening
4885 quote and the second character denotes the closing quote.
4886 By default, both characters are " (double quote).
4887 The optional argument
4893 and selects the compiler to be used for the check.
4894 Returns 1 on success and 0 on failure.
4897 .RI Configure.CheckCHeader( self ", " header ", [" include_quotes ])
4898 This is a wrapper around
4899 .B Configure.CheckHeader
4902 is usable in the C language.
4905 in which case the last item in the list
4906 is the header file to be checked,
4907 and the previous list items are
4910 lines should precede the
4911 header line being checked for.
4912 The optional argument
4915 a two character string, where the first character denotes the opening
4916 quote and the second character denotes the closing quote (both default
4918 Returns 1 on success and 0 on failure.
4921 .RI Configure.CheckCXXHeader( self ", " header ", [" include_quotes ])
4922 This is a wrapper around
4923 .B Configure.CheckHeader
4926 is usable in the C++ language.
4929 in which case the last item in the list
4930 is the header file to be checked,
4931 and the previous list items are
4934 lines should precede the
4935 header line being checked for.
4936 The optional argument
4939 a two character string, where the first character denotes the opening
4940 quote and the second character denotes the closing quote (both default
4942 Returns 1 on success and 0 on failure.
4945 .RI Configure.CheckFunc( self ", " function_name ", [" header ", " language ])
4946 Checks if the specified
4947 C or C++ function is available.
4949 is the name of the function to check for.
4952 argument is a string
4956 that will be compiled
4957 to check if the function exists;
4963 char function_name();
4971 and selects the compiler to be used for the check;
4975 .RI Configure.CheckLib( self ", [" library ", " symbol ", " header ", " language ", " autoadd=1 ])
4982 is 1 and the library provides the specified
4984 appends the library to the LIBS construction environment variable.
4986 may also be None (the default),
4989 is checked with the current LIBS variable,
4990 or a list of library names,
4991 in which case each library in the list
4999 .BR Configure.CheckLib ()
5001 you can link against the specified
5009 and selects the compiler to be used for the check;
5011 The default value for
5014 This method returns 1 on success and 0 on error.
5017 .RI Configure.CheckLibWithHeader( self ", " library ", " header ", " language ", [" call ", " autoadd ])
5020 .RI Configure.CheckLib
5021 call, this call provides a more sophisticated way to check against libraries.
5024 specifies the library or a list of libraries to check.
5026 specifies a header to check for.
5029 in which case the last item in the list
5030 is the header file to be checked,
5031 and the previous list items are
5034 lines should precede the
5035 header line being checked for.
5037 may be one of 'C','c','CXX','cxx','C++' and 'c++'.
5039 can be any valid expression (with a trailing ';').
5043 the default simply checks that you
5044 can link against the specified
5047 specifies whether to add the library to the environment (only if the check
5048 succeeds). This method returns 1 on success and 0 on error.
5051 .RI Configure.CheckType( self ", " type_name ", [" includes ", " language ])
5052 Checks for the existence of a type defined by
5055 specifies the typedef name to check for.
5057 is a string containing one or more
5059 lines that will be inserted into the program
5060 that will be run to test for the existence of the type.
5067 and selects the compiler to be used for the check;
5071 Example of a typical Configure usage:
5075 conf = Configure( env )
5076 if not conf.CheckCHeader( 'math.h' ):
5077 print 'We really need math.h!'
5079 if conf.CheckLibWithHeader( 'qt', 'qapp.h', 'c++', 'QApplication qapp(0,0);' ):
5080 # do stuff for qt - usage, e.g.
5081 conf.env.Append( CPPFLAGS = '-DWITH_QT' )
5086 You can define your own custom checks.
5087 in addition to the predefined checks.
5088 These are passed in a dictionary to the Configure function.
5089 This dictionary maps the names of the checks
5090 to user defined Python callables
5091 (either Python functions or class instances implementing the
5094 The first argument of the call is always a
5096 instance followed by the arguments,
5097 which must be supplied by the user of the check.
5098 These CheckContext instances define the following methods:
5101 .RI CheckContext.Message( self ", " text )
5103 Usually called before the check is started.
5105 will be displayed to the user, e.g. 'Checking for library X...'
5108 .RI CheckContext.Result( self, ", " res )
5110 Usually called after the check is done.
5112 can be either an integer or a string. In the former case, 'ok' (res != 0)
5113 or 'failed' (res == 0) is displayed to the user, in the latter case the
5114 given string is displayed.
5117 .RI CheckContext.TryCompile( self ", " text ", " extension )
5118 Checks if a file with the specified
5120 (e.g. '.c') containing
5122 can be compiled using the environment's
5124 builder. Returns 1 on success and 0 on failure.
5127 .RI CheckContext.TryLink( self ", " text ", " extension )
5128 Checks, if a file with the specified
5130 (e.g. '.c') containing
5132 can be compiled using the environment's
5134 builder. Returns 1 on success and 0 on failure.
5137 .RI CheckContext.TryRun( self ", " text ", " extension )
5138 Checks, if a file with the specified
5140 (e.g. '.c') containing
5142 can be compiled using the environment's
5144 builder. On success, the program is run. If the program
5145 executes successfully
5146 (that is, its return status is 0),
5151 is the standard output of the
5153 If the program fails execution
5154 (its return status is non-zero),
5155 then (0, '') is returned.
5158 .RI CheckContext.TryAction( self ", " action ", [" text ", " extension ])
5159 Checks if the specified
5161 with an optional source file (contents
5168 may be anything which can be converted to a
5175 is the content of the target file.
5181 .RI CheckContext.TryBuild( self ", " builder ", [" text ", " extension ])
5182 Low level implementation for testing specific builds;
5183 the methods above are based on this method.
5184 Given the Builder instance
5188 of a source file with optional
5190 this method returns 1 on success and 0 on failure. In addition,
5192 is set to the build target node, if the build was successful.
5195 Example for implementing and using custom tests:
5198 def CheckQt(context, qtdir):
5199 context.Message( 'Checking for qt ...' )
5200 lastLIBS = context.env['LIBS']
5201 lastLIBPATH = context.env['LIBPATH']
5202 lastCPPPATH= context.env['CPPPATH']
5203 context.env.Append(LIBS = 'qt', LIBPATH = qtdir + '/lib', CPPPATH = qtdir + '/include' )
5204 ret = context.TryLink("""
5206 int main(int argc, char **argv) {
5207 QApplication qapp(argc, argv);
5212 context.env.Replace(LIBS = lastLIBS, LIBPATH=lastLIBPATH, CPPPATH=lastCPPPATH)
5213 context.Result( ret )
5217 conf = Configure( env, custom_tests = { 'CheckQt' : CheckQt } )
5218 if not conf.CheckQt('/usr/lib/qt'):
5219 print 'We really need qt!'
5224 .SS Construction Variable Options
5226 Often when building software, various options need to be specified at build
5227 time that are not known when the SConstruct/SConscript files are
5228 written. For example, libraries needed for the build may be in non-standard
5229 locations, or site-specific compiler options may need to be passed to the
5232 provides a mechanism for overridding construction variables from the
5233 command line or a text-based SConscript file through an Options
5234 object. To create an Options object, call the Options() function:
5237 .RI Options([ files "], [" args ])
5238 This creates an Options object that will read construction variables from
5239 the file or list of filenames specified in
5241 If no files are specified,
5246 then no files will be read.
5247 The optional argument
5250 values that will override anything read from the specified files;
5251 it is primarily intended to be passed the
5253 dictionary that holds variables
5254 specified on the command line.
5258 opts = Options('custom.py')
5259 opts = Options('overrides.py', ARGUMENTS)
5260 opts = Options(None, {FOO:'expansion', BAR:7})
5263 Options objects have the following methods:
5266 .RI Add( key ", [" help ", " default ", " validator ", " converter ])
5267 This adds a customizable construction variable to the Options object.
5269 is the name of the variable.
5271 is the help text for the variable.
5273 is the default value of the variable;
5274 if the default value is
5276 and there is no explicit value specified,
5277 the construction variable will
5279 be added to the construction environment.
5281 is called to validate the value of the variable, and should take three
5282 arguments: key, value, and environment.
5283 The recommended way to handle an invalid value is
5284 to raise an exception (see example below).
5286 is called to convert the value before putting it in the environment, and
5287 should take either a value, or the value and environment, as parameters.
5290 must return a value,
5291 which will be converted into a string
5292 before being validated by the
5295 and then added to the environment.
5300 opts.Add('CC', 'The C compiler')
5302 def validate_color(key, val, env):
5303 if not val in ['red', 'blue', 'yellow']:
5304 raise "Invalid color value '%s'" % val
5305 opts.Add('COLOR', validator=valid_color)
5309 .RI AddOptions( list )
5310 A wrapper script that adds
5311 multiple customizable construction variables
5312 to an Options object.
5314 is a list of tuple or list objects
5315 that contain the arguments
5316 for an individual call to the
5323 ('CC', 'The C compiler'),
5324 ('VALIDATE', 'An option for testing validation',
5325 'notset', validator, None),
5330 .RI Update( env ", [" args ])
5331 This updates a construction environment
5333 with the customized construction variables. Normally this method is not
5334 called directly, but is called indirectly by passing the Options object to
5335 the Environment() function:
5338 env = Environment(options=opts)
5342 The text file(s) that were specified
5343 when the Options object was created
5344 are executed as Python scripts,
5345 and the values of (global) Python variables set in the file
5346 are added to the construction environment.
5354 .RI Save( filename ", " env )
5355 This saves the currently set options into a script file named
5357 that can be used on the next invocation to automatically load the current
5358 settings. This method combined with the Options method can be used to
5359 support caching of options between runs.
5363 opts = Options(['options.cache', 'custom.py'])
5366 opts.Save('options.cache', env)
5370 .RI GenerateHelpText( env ", [" sort ])
5371 This generates help text documenting the customizable construction
5372 variables suitable to passing in to the Help() function.
5374 is the construction environment that will be used to get the actual values
5375 of customizable variables. Calling with
5379 will cause the output to be sorted
5380 by the specified argument.
5384 should take two arguments
5387 (like the standard Python
5392 Help(opts.GenerateHelpText(env))
5393 Help(opts.GenerateHelpText(env, sort=cmp))
5397 .RI FormatOptionHelpText( env ", " opt ", " help ", " default ", " actual )
5398 This method returns a formatted string
5399 containing the printable help text
5401 It is normally not called directly,
5402 but is called by the
5403 .IR GenerateHelpText ()
5404 method to create the returned help text.
5405 It may be overridden with your own
5406 function that takes the arguments specified above
5407 and returns a string of help text formatted to your liking.
5409 .IR GenerateHelpText ()
5410 will not put any blank lines or extra
5411 characters in between the entries,
5412 so you must add those characters to the returned
5413 string if you want the entries separated.
5416 def my_format(env, opt, help, default, actual):
5417 fmt = "\n%s: default=%s actual=%s (%s)\n"
5418 return fmt % (opt, default. actual, help)
5419 opts.FormatOptionHelpText = my_format
5422 To make it more convenient to work with customizable Options,
5424 provides a number of functions
5425 that make it easy to set up
5426 various types of Options:
5429 .RI BoolOption( key ", " help ", " default )
5430 Return a tuple of arguments
5431 to set up a Boolean option.
5435 have a default value of
5437 and display the specified
5440 The option will interpret the values
5462 .RI EnumOption( key ", " help ", " default ", " allowed_values ", [" map ", " ignorecase ])
5463 Return a tuple of arguments
5465 whose value may be one
5466 of a specified list of legal enumerated values.
5470 have a default value of
5472 and display the specified
5475 The option will only support those
5481 argument is a dictionary
5482 that can be used to convert
5483 input values into specific legal values
5492 then the values are case-sensitive.
5497 then values will be matched
5503 then values will be matched
5505 and all input values will be
5506 converted to lower case.
5509 .RI ListOption( key ", " help ", " default ", " names ", [", map ])
5510 Return a tuple of arguments
5512 whose value may be one or more
5513 of a specified list of legal enumerated values.
5517 have a default value of
5519 and display the specified
5522 The option will only support the values
5525 or the values in the
5528 More than one value may be specified,
5529 with all values separated by commas.
5530 The default may be a string of
5531 comma-separated default values,
5532 or a list of the default values.
5535 argument is a dictionary
5536 that can be used to convert
5537 input values into specific legal values
5543 .RI PackageOption( key ", " help ", " default )
5544 Return a tuple of arguments
5546 whose value is a path name
5547 of a package that may be
5548 enabled, disabled or
5549 given an explicit path name.
5553 have a default value of
5555 and display the specified
5558 The option will support the values
5565 in which case the specified
5568 or the option may be set to an
5570 (typically the path name to a package
5571 that is being enabled).
5572 The option will also support the values
5578 to disable use of the specified option.
5581 .RI PathOption( key ", " help ", " default ", [" validator ])
5582 Return a tuple of arguments
5584 whose value is expected to be a path name.
5588 have a default value of
5590 and display the specified
5596 that will be called to
5597 verify that the specified path
5600 following ready-made validators:
5601 .BR PathOption.PathExists
5603 which verifies that the specified path exists;
5604 .BR PathOption.PathIsFile ,
5605 which verifies that the specified path is an existing file;
5606 .BR PathOption.PathIsDir ,
5607 which verifies that the specified path is an existing directory;
5608 .BR PathOption.PathIsDirCreate ,
5609 which verifies that the specified path is a directory
5610 and will create the specified directory if the path does not exist;
5612 .BR PathOption.PathAccept ,
5613 which simply accepts the specific path name argument without validation,
5614 and which is suitable if you want your users
5615 to be able to specify a directory path that will be
5616 created as part of the build process, for example.
5617 You may supply your own
5620 which must take three arguments
5622 the name of the options variable to be set;
5624 the specified value being checked;
5627 the construction environment)
5628 and should raise an exception
5629 if the specified value is not acceptable.
5632 These functions make it
5633 convenient to create a number
5634 of options with consistent behavior
5635 in a single call to the
5641 BoolOption('warnings', 'compilation with -Wall and similiar', 1),
5642 EnumOption('debug', 'debug output and symbols', 'no'
5643 allowed_values=('yes', 'no', 'full'),
5644 map={}, ignorecase=0), # case sensitive
5645 ListOption('shared',
5646 'libraries to build as shared libraries',
5648 names = list_of_libs),
5649 PackageOption('x11',
5650 'use X11 installed here (yes = search some places)',
5652 PathOption('qtdir', 'where the root of Qt is installed', qtdir),
5653 PathOption('foopath', 'where the foo library is installed', foopath,
5654 PathOption.PathIsDir),
5659 .SS File and Directory Nodes
5669 Nodes, respectively.
5670 python objects, respectively.
5671 Those objects have several user-visible attributes
5672 and methods that are often useful:
5678 This path is relative to the top-level directory
5682 The build path is the same as the source path if
5687 The absolute build path of the given file or directory.
5697 object representing the
5706 # Get the current build dir's path, relative to top.
5708 # Current dir's absolute path
5710 # Next line is always '.', because it is the top dir's path relative to itself.
5712 File('foo.c').srcnode().path # source path of the given source file.
5714 # Builders also return File objects:
5715 foo = env.Program('foo.c')
5716 print "foo will be built in %s"%foo.path
5722 can be extended to build different types of targets
5723 by adding new Builder objects
5724 to a construction environment.
5726 you should only need to add a new Builder object
5727 when you want to build a new type of file or other external target.
5728 If you just want to invoke a different compiler or other tool
5729 to build a Program, Object, Library, or any other
5730 type of output file for which
5732 already has an existing Builder,
5733 it is generally much easier to
5734 use those existing Builders
5735 in a construction environment
5736 that sets the appropriate construction variables
5739 Builder objects are created
5745 function accepts the following arguments:
5748 The command line string used to build the target from the source.
5751 a list of strings representing the command
5752 to be executed and its arguments
5753 (suitable for enclosing white space in an argument),
5755 mapping source file name suffixes to
5756 any combination of command line strings
5757 (if the builder should accept multiple source file extensions),
5760 (see the next section);
5761 or a list of any of the above.
5764 takes three arguments:
5766 - a list of source nodes,
5768 - a list of target nodes,
5770 - the construction environment.
5773 The prefix that will be prepended to the target file name.
5774 This may be specified as a:
5784 - a function or other callable that takes
5785 two arguments (a construction environment and a list of sources)
5786 and returns a prefix,
5791 - specifies a mapping from a specific source suffix (of the first
5792 source specified) to a corresponding target prefix. Both the source
5793 suffix and target prefix specifications may use environment variable
5794 substitution, and the target prefix (the 'value' entries in the
5795 dictionary) may also be a callable object. The default target prefix
5796 may be indicated by a dictionary entry with a key value of None.
5801 b = Builder("build_it < $SOURCE > $TARGET"
5804 def gen_prefix(env, sources):
5805 return "file-" + env['PLATFORM'] + '-'
5806 b = Builder("build_it < $SOURCE > $TARGET",
5807 prefix = gen_prefix)
5809 b = Builder("build_it < $SOURCE > $TARGET",
5810 suffix = { None: "file-",
5811 "$SRC_SFX_A": gen_prefix })
5815 The suffix that will be appended to the target file name.
5816 This may be specified in the same manner as the prefix above.
5817 If the suffix is a string, then
5819 will append a '.' to the beginning of the suffix if it's not already
5820 there. The string returned by callable object (or obtained from the
5821 dictionary) is untouched and must append its own '.' to the beginning
5825 b = Builder("build_it < $SOURCE > $TARGET"
5828 def gen_suffix(env, sources):
5829 return "." + env['PLATFORM'] + "-file"
5830 b = Builder("build_it < $SOURCE > $TARGET",
5831 suffix = gen_suffix)
5833 b = Builder("build_it < $SOURCE > $TARGET",
5834 suffix = { None: ".sfx1",
5835 "$SRC_SFX_A": gen_suffix })
5839 The expected source file name suffix. This may be a string or a list
5843 A Scanner object that
5844 will be invoked to find
5845 implicit dependencies for this target file.
5846 This keyword argument should be used
5847 for Scanner objects that find
5848 implicit dependencies
5849 based only on the target file
5850 and the construction environment,
5853 (See the section "Scanner Objects," below,
5854 for information about creating Scanner objects.)
5857 A Scanner object that
5859 find implicit dependences in
5861 used to build this target file.
5862 This is where you would
5863 specify a scanner to
5866 lines in source files.
5869 Scanner object may be used to
5870 indicate that this Builder
5871 should scan directory trees
5872 for on-disk changes to files
5875 does not know about from other Builder or function calls.
5876 (See the section "Scanner Objects," below,
5877 for information about creating your own Scanner objects.)
5880 A factory function that the Builder will use
5881 to turn any targets specified as strings into SCons Nodes.
5883 SCons assumes that all targets are files.
5884 Other useful target_factory
5887 for when a Builder creates a directory target,
5890 for when a Builder can create either a file
5891 or directory target.
5896 MakeDirectoryBuilder = Builder(action=my_mkdir, target_factory=Dir)
5898 env.Append(BUILDERS = {'MakeDirectory':MakeDirectoryBuilder})
5899 env.MakeDirectory('new_directory', [])
5903 Note that the call to the MakeDirectory Builder
5904 needs to specify an empty source list
5905 to make the string represent the builder's target;
5906 without that, it would assume the argument is the source,
5907 and would try to deduce the target name from it,
5908 which in the absence of an automatically-added prefix or suffix
5909 would lead to a matching target and source name
5910 and a circular dependency.
5913 A factory function that the Builder will use
5914 to turn any sources specified as strings into SCons Nodes.
5916 SCons assumes that all source are files.
5917 Other useful source_factory
5920 for when a Builder uses a directory as a source,
5923 for when a Builder can use files
5924 or directories (or both) as sources.
5929 CollectBuilder = Builder(action=my_mkdir, source_factory=Entry)
5931 env.Append(BUILDERS = {'Collect':CollectBuilder})
5932 env.Collect('archive', ['directory_name', 'file_name'])
5936 A function or list of functions to manipulate the target and source
5937 lists before dependencies are established
5938 and the target(s) are actually built.
5940 can also be a string containing a construction variable to expand
5941 to an emitter function or list of functions,
5942 or a dictionary mapping source file suffixes
5943 to emitter functions.
5944 (Only the suffix of the first source file
5945 is used to select the actual emitter function
5946 from an emitter dictionary.)
5949 takes three arguments:
5951 - a list of source nodes,
5953 - a list of target nodes,
5955 - the construction environment.
5956 An emitter must return a tuple containing two lists,
5957 the list of targets to be built by this builder,
5958 and the list of sources for this builder.
5963 def e(target, source, env):
5964 return (target + ['foo.foo'], source + ['foo.src'])
5966 # Simple association of an emitter function with a Builder.
5967 b = Builder("my_build < $TARGET > $SOURCE",
5970 def e2(target, source, env):
5971 return (target + ['bar.foo'], source + ['bar.src'])
5973 # Simple association of a list of emitter functions with a Builder.
5974 b = Builder("my_build < $TARGET > $SOURCE",
5977 # Calling an emitter function through a construction variable.
5978 env = Environment(MY_EMITTER = e)
5979 b = Builder("my_build < $TARGET > $SOURCE",
5980 emitter = '$MY_EMITTER')
5982 # Calling a list of emitter functions through a construction variable.
5983 env = Environment(EMITTER_LIST = [e, e2])
5984 b = Builder("my_build < $TARGET > $SOURCE",
5985 emitter = '$EMITTER_LIST')
5987 # Associating multiple emitters with different file
5988 # suffixes using a dictionary.
5989 def e_suf1(target, source, env):
5990 return (target + ['another_target_file'], source)
5991 def e_suf2(target, source, env):
5992 return (target, source + ['another_source_file'])
5993 b = Builder("my_build < $TARGET > $SOURCE",
5994 emitter = {'.suf1' : e_suf1,
5999 Specifies whether this builder is allowed to be called multiple times for
6000 the same target file(s). The default is 0, which means the builder
6001 can not be called multiple times for the same target file(s). Calling a
6002 builder multiple times for the same target simply adds additional source
6003 files to the target; it is not allowed to change the environment associated
6004 with the target, specify addition environment overrides, or associate a different
6005 builder with the target.
6008 A construction environment that can be used
6009 to fetch source code using this Builder.
6010 (Note that this environment is
6012 used for normal builds of normal target files,
6013 which use the environment that was
6014 used to call the Builder for the target file.)
6017 A function that returns a list of actions that will be executed to build
6018 the target(s) from the source(s).
6019 The returned action(s) may be
6020 an Action object, or anything that
6021 can be converted into an Action object
6022 (see the next section).
6024 The generator function
6025 takes four arguments:
6027 - a list of source nodes,
6029 - a list of target nodes,
6031 - the construction environment,
6033 - a Boolean value that specifies
6034 whether the generator is being called
6035 for generating a build signature
6036 (as opposed to actually executing the command).
6040 def g(source, target, env, for_signature):
6041 return [["gcc", "-c", "-o"] + target + source]
6043 b = Builder(generator=g)
6051 arguments must not both be used for the same Builder.
6054 Specifies a builder to use when a source file name suffix does not match
6055 any of the suffixes of the builder. Using this argument produces a
6056 multi-stage builder.
6059 Specifies that this builder expects exactly one source file per call. Giving
6060 more than one source files without target files results in implicitely calling
6061 the builder multiple times (once for each source given). Giving multiple
6062 source files together with target files results in a UserError exception.
6070 arguments must not both be used for the same Builder.
6072 .IP source_ext_match
6075 argument is a dictionary,
6076 the default behavior when a builder is passed
6077 multiple source files is to make sure that the
6078 extensions of all the source files match.
6079 If it is legal for this builder to be
6080 called with a list of source files with different extensions,
6081 this check can be suppressed by setting
6085 or some other non-true value.
6090 will use the suffix of the first specified
6091 source file to select the appropriate action from the
6095 In the following example,
6100 from exiting with an error
6101 due to the mismatched suffixes of
6107 b = Builder(action={'.in' : 'build $SOURCES > $TARGET'},
6108 source_ext_match = None)
6110 env = Environment(BUILDERS = {'MyBuild':b})
6111 env.MyBuild('foo.out', ['foo.in', 'foo.extra'])
6115 A construction environment that can be used
6116 to fetch source code using this Builder.
6117 (Note that this environment is
6119 used for normal builds of normal target files,
6120 which use the environment that was
6121 used to call the Builder for the target file.)
6124 b = Builder(action="build < $SOURCE > $TARGET")
6125 env = Environment(BUILDERS = {'MyBuild' : b})
6126 env.MyBuild('foo.out', 'foo.in', my_arg = 'xyzzy')
6130 A directory from which scons
6137 a string or a directory Node,
6138 scons will change to the specified directory.
6141 is not a string or Node
6143 then scons will change to the
6144 target file's directory.
6146 Note that scons will
6148 automatically modify
6150 construction variables like
6154 when using the chdir
6155 keyword argument--that is,
6156 the expanded file names
6157 will still be relative to
6158 the top-level SConstruct directory,
6159 and consequently incorrect
6160 relative to the chdir directory.
6161 Builders created using chdir keyword argument,
6162 will need to use construction variable
6167 to use just the filename portion of the
6171 b = Builder(action="build < ${SOURCE.file} > ${TARGET.file}",
6173 env = Environment(BUILDERS = {'MyBuild' : b})
6174 env.MyBuild('sub/dir/foo.out', 'sub/dir/foo.in')
6178 Python only keeps one current directory
6179 location for all of the threads.
6180 This means that use of the
6188 because individual worker threads spawned
6189 by SCons interfere with each other
6190 when they start changing directory.
6193 Any additional keyword arguments supplied
6194 when a Builder object is created
6195 (that is, when the Builder() function is called)
6196 will be set in the executing construction
6197 environment when the Builder object is called.
6198 The canonical example here would be
6199 to set a construction variable to
6200 the repository of a source code system.
6202 Any additional keyword arguments supplied
6206 will only be associated with the target
6207 created by that particular Builder call
6208 (and any other files built as a
6209 result of the call).
6211 These extra keyword arguments are passed to the
6212 following functions:
6213 command generator functions,
6215 and emitter functions.
6221 function will turn its
6223 keyword argument into an appropriate
6224 internal Action object.
6225 You can also explicity create Action objects
6229 which can then be passed to the
6232 This can be used to configure
6233 an Action object more flexibly,
6234 or it may simply be more efficient
6235 than letting each separate Builder object
6236 create a separate Action
6238 Builder objects need to do the same thing.
6243 returns an appropriate object for the action
6244 represented by the type of the first argument:
6247 If the first argument is already an Action object,
6248 the object is simply returned.
6251 If the first argument is a string,
6252 a command-line Action is returned.
6253 Note that the command line string
6254 may be preceded by an
6257 to suppress printing of the
6258 specified command line,
6262 to ignore the exit status from
6263 the specified command.
6267 Action('$CC -c -o $TARGET $SOURCES')
6269 # Doesn't print the line being executed.
6270 Action('@build $TARGET $SOURCES')
6273 Action('-build $TARGET $SOURCES')
6276 .\" XXX From Gary Ruben, 23 April 2002:
6277 .\" What would be useful is a discussion of how you execute command
6278 .\" shell commands ie. what is the process used to spawn the shell, pass
6279 .\" environment variables to it etc., whether there is one shell per
6280 .\" environment or one per command etc. It might help to look at the Gnu
6281 .\" make documentation to see what they think is important to discuss about
6282 .\" a build system. I'm sure you can do a better job of organising the
6283 .\" documentation than they have :-)
6287 If the first argument is a list,
6288 then a list of Action objects is returned.
6289 An Action object is created as necessary
6290 for each element in the list.
6293 the list is itself a list,
6294 the internal list is the
6295 command and arguments to be executed via
6297 This allows white space to be enclosed
6298 in an argument by defining
6299 a command in a list within a list:
6302 Action([['cc', '-c', '-DWHITE SPACE', '-o', '$TARGET', '$SOURCES']])
6306 If the first argument is a Python function,
6307 a function Action is returned.
6308 The Python function takes three keyword arguments,
6310 (a Node object representing the target file),
6312 (a Node object representing the source file)
6315 (the construction environment
6316 used for building the target file).
6321 arguments may be lists of Node objects if there is
6322 more than one target file or source file.
6323 The actual target and source file name(s) may
6324 be retrieved from their Node objects
6325 via the built-in Python str() function:
6328 target_file_name = str(target)
6329 source_file_names = map(lambda x: str(x), source)
6332 The function should return
6336 to indicate a successful build of the target file(s).
6337 The function may raise an exception
6338 or return a non-zero exit status
6339 to indicate an unsuccessful build.
6342 def build_it(target = None, source = None, env = None):
6343 # build the target from the source
6346 a = Action(build_it)
6349 If the action argument is not one of the above,
6353 The second, optional argument
6354 is used to define the output which is printed
6355 when the Action is actually performed.
6356 In the absence of this parameter, or if it's an
6357 empty string, a default output depending on the type of the action
6358 is used. For example, a command-line action will print
6359 the executed command. The argument is either a python function
6362 In the first case, it's a function that returns
6363 a string to be printed to describe the action being executed.
6364 Like a function to build a file,
6365 this function takes three arguments:
6367 (a Node object representing the target file),
6369 (a Node object representing the source file)
6372 (a construction environment).
6377 arguments may be lists of Node objects if there is
6378 more than one target file or source file.
6380 In the second case, you provide the string itself.
6381 The string typically contains variables, notably
6382 $TARGET(S) and $SOURCE(S), or consists of just a single
6383 variable, which is optionally defined somewhere else.
6384 SCons itself heavily uses the latter variant.
6389 def build_it(target, source, env):
6390 # build the target from the source
6393 def string_it(target, source, env):
6394 return "building '%s' from '%s'" % (target[0], source[0])
6396 # Use a positional argument.
6397 f = Action(build_it, string_it)
6398 s = Action(build_it, "building '$TARGET' from '$SOURCE'")
6400 # Alternatively, use a keyword argument.
6401 f = Action(build_it, strfunction=string_it)
6402 s = Action(build_it, cmdstr="building '$TARGET' from '$SOURCE'")
6404 # You can provide a configurable variable.
6405 l = Action(build_it, '$STRINGIT')
6408 The third, also optional argument
6409 is a list of construction variables
6410 whose values will be included
6411 in the signature of the Action
6412 when deciding whether a target should
6413 be rebuilt because the action changed.
6414 This is necessary whenever you want a target to
6415 be rebuilt when a specific
6416 construction variable changes,
6417 because the underlying Python code for a function
6418 will not change when the value of the construction variable does.
6421 def build_it(target, source, env):
6422 # build the target from the 'XXX' construction variable
6423 open(target[0], 'w').write(env['XXX'])
6426 # Use positional arguments.
6427 a = Action(build_it, '$STRINGIT', ['XXX'])
6429 # Alternatively, use a keyword argument.
6430 a = Action(build_it, varlist=['XXX'])
6439 which specifies that
6440 scons will execute the action
6441 after changing to the specified directory.
6442 If the chdir argument is
6443 a string or a directory Node,
6444 scons will change to the specified directory.
6445 If the chdir argument
6446 is not a string or Node
6448 then scons will change to the
6449 target file's directory.
6451 Note that scons will
6453 automatically modify
6455 construction variables like
6459 when using the chdir
6460 keyword argument--that is,
6461 the expanded file names
6462 will still be relative to
6463 the top-level SConstruct directory,
6464 and consequently incorrect
6465 relative to the chdir directory.
6466 Builders created using chdir keyword argument,
6467 will need to use construction variable
6472 to use just the filename portion of the
6476 a = Action("build < ${SOURCE.file} > ${TARGET.file}",
6486 which specifies a function
6487 that is passed the exit status
6489 from the specified action
6490 and can return an arbitrary
6492 This can be used, for example,
6493 to specify that an Action object's
6494 return value should be ignored
6495 and SCons should, therefore,
6496 consider that the action always suceeds:
6499 def always_succeed(s):
6500 # Always return 0, which indicates success.
6502 a = Action("build < ${SOURCE.file} > ${TARGET.file}",
6503 exitstatfunc=always_succeed)
6506 .SS Miscellaneous Action Functions
6509 supplies a number of functions
6510 that arrange for various common
6511 file and directory manipulations
6513 These are similar in concept to "tasks" in the
6515 although the implementation is slightly different.
6516 These functions do not actually
6517 perform the specified action
6518 at the time the function is called,
6519 but instead return an Action object
6520 that can be executed at the
6522 (In Object-Oriented terminology,
6527 that return Action objects.)
6530 there are two natural ways
6533 are intended to be used.
6537 to perform the action
6538 at the time the SConscript
6542 global function to do so:
6544 Execute(Touch('file'))
6548 you can use these functions
6549 to supply Actions in a list
6553 This can allow you to
6554 perform more complicated
6555 sequences of file manipulation
6557 on platform-specific
6561 env = Environment(TMPBUILD = '/tmp/builddir')
6562 env.Command('foo.out', 'foo.in',
6563 [Mkdir('$TMPBUILD'),
6564 Copy('$TMPBUILD', '${SOURCE.dir}'),
6565 "cd $TMPBUILD && make",
6566 Delete('$TMPBUILD')])
6570 .RI Chmod( dest ", " mode )
6571 Returns an Action object that
6572 changes the permissions on the specified
6574 file or directory to the specified
6579 Execute(Chmod('file', 0755))
6581 env.Command('foo.out', 'foo.in',
6582 [Copy('$TARGET', '$SOURCE'),
6583 Chmod('$TARGET', 0755)])
6587 .RI Copy( dest ", " src )
6588 Returns an Action object
6591 source file or directory to the
6593 destination file or directory.
6597 Execute(Copy('foo.output', 'foo.input'))
6599 env.Command('bar.out', 'bar.in',
6600 Copy('$TARGET', '$SOURCE'))
6604 .RI Delete( entry ", [" must_exist ])
6605 Returns an Action that
6606 deletes the specified
6608 which may be a file or a directory tree.
6609 If a directory is specified,
6610 the entire directory tree
6615 then a Python error will be thrown
6616 if the specified entry does not exist;
6619 that is, the Action will silently do nothing
6620 if the entry does not exist.
6624 Execute(Delete('/tmp/buildroot'))
6626 env.Command('foo.out', 'foo.in',
6627 [Delete('${TARGET.dir}'),
6630 Execute(Delete('file_that_must_exist', must_exist=1))
6636 that creates the specified
6642 Execute(Mkdir('/tmp/outputdir'))
6644 env.Command('foo.out', 'foo.in',
6645 [Mkdir('/tmp/builddir',
6646 Copy('$SOURCE', '/tmp/builddir')
6647 "cd /tmp/builddir && ])
6652 .RI Move( dest ", " src )
6654 that moves the specified
6656 file or directory to
6663 Execute(Move('file.destination', 'file.source'))
6665 env.Command('output_file', 'input_file',
6667 Move('$TARGET', 'file_created_by_MyBuildAction')])
6673 that updates the modification time
6679 Execute(Touch('file_to_be_touched'))
6681 env.Command('marker', 'input_file',
6686 .SS Variable Substitution
6688 Before executing a command,
6690 performs construction variable interpolation on the strings that make up
6691 the command line of builders.
6692 Variables are introduced by a
6695 Besides construction variables, scons provides the following
6696 variables for each command execution:
6699 The file name of the target being built, or the file name of the first
6700 target if multiple targets are being built.
6703 The file names of all targets being built.
6706 The file name of the source of the build command, or the file name of the
6707 first source if multiple sources are being built.
6710 The file names of the sources of the build command.
6712 (Note that the above variables are reserved
6713 and may not be set in a construction environment.)
6716 For example, given the construction variable CC='cc', targets=['foo'], and
6717 sources=['foo.c', 'bar.c']:
6720 action='$CC -c -o $TARGET $SOURCES'
6723 would produce the command line:
6726 cc -c -o foo foo.c bar.c
6729 Variable names may be surrounded by curly braces ({})
6730 to separate the name from the trailing characters.
6731 Within the curly braces, a variable name may have
6732 a Python slice subscript appended to select one
6733 or more items from a list.
6734 In the previous example, the string:
6746 Additionally, a variable name may
6747 have the following special
6748 modifiers appended within the enclosing curly braces
6749 to modify the interpolated string:
6752 The base path of the file name,
6753 including the directory path
6754 but excluding any suffix.
6757 The name of the directory in which the file exists.
6761 minus any directory portion.
6764 Just the basename of the file,
6766 and minus the directory.
6769 Just the file suffix.
6772 The absolute path name of the file.
6775 The POSIX form of the path,
6776 with directories separated by
6780 This is sometimes necessary on Windows systems
6781 when a path references a file on other (POSIX) systems.
6784 The directory and file name to the source file linked to this file
6785 through BuildDir. If this file isn't linked, it just returns the
6786 directory and filename unchanged.
6789 The directory containing the source file linked to this file
6790 through BuildDir. If this file isn't linked, it just returns the
6791 directory part of the filename.
6794 The directory and file name to the source file linked to this file
6795 through BuildDir. If the file does not exist locally but exists in
6796 a Repository, the path in the Repository is returned.
6797 If this file isn't linked, it just returns the
6798 directory and filename unchanged.
6801 The Repository directory containing the source file linked to this file
6802 through BuildDir. If this file isn't linked, it just returns the
6803 directory part of the filename.
6806 For example, the specified target will
6807 expand as follows for the corresponding modifiers:
6810 $TARGET => sub/dir/file.x
6811 ${TARGET.base} => sub/dir/file
6812 ${TARGET.dir} => sub/dir
6813 ${TARGET.file} => file.x
6814 ${TARGET.filebase} => file
6815 ${TARGET.suffix} => .x
6816 ${TARGET.abspath} => /top/dir/sub/dir/file.x
6818 SConscript('src/SConscript', build_dir='sub/dir')
6819 $SOURCE => sub/dir/file.x
6820 ${SOURCE.srcpath} => src/file.x
6821 ${SOURCE.srcdir} => src
6823 Repository('/usr/repository')
6824 $SOURCE => sub/dir/file.x
6825 ${SOURCE.rsrcpath} => /usr/repository/src/file.x
6826 ${SOURCE.rsrcdir} => /usr/repository/src
6829 Note that curly braces braces may also be used
6830 to enclose arbitrary Python code to be evaluated.
6831 (In fact, this is how the above modifiers are substituted,
6832 they are simply attributes of the Python objects
6833 that represent TARGET, SOURCES, etc.)
6834 See the section "Python Code Substitution," below,
6835 for more thorough examples of
6836 how this can be used.
6838 Lastly, a variable name
6839 may be a callable Python function
6841 construction variable in the environment.
6843 take four arguments:
6845 - a list of target nodes,
6847 - a list of source nodes,
6849 - the construction environment,
6851 - a Boolean value that specifies
6852 whether the function is being called
6853 for generating a build signature.
6854 SCons will insert whatever
6855 the called function returns
6856 into the expanded string:
6859 def foo(target, source, env, for_signature):
6862 # Will expand $BAR to "bar baz"
6863 env=Environment(FOO=foo, BAR="$FOO baz")
6866 You can use this feature to pass arguments to a
6867 Python function by creating a callable class
6868 that stores one or more arguments in an object,
6869 and then uses them when the
6872 Note that in this case,
6873 the entire variable expansion must
6874 be enclosed by curly braces
6875 so that the arguments will
6876 be associated with the
6877 instantiation of the class:
6881 def __init__(self, arg):
6884 def __call__(self, target, source, env, for_signature):
6887 # Will expand $BAR to "my argument bar baz"
6888 env=Environment(FOO=foo, BAR="${FOO('my argument')} baz")
6892 The special pseudo-variables
6896 may be used to surround parts of a command line
6899 causing a rebuild--that is,
6900 which are not included in the signature
6901 of target files built with this command.
6906 will be removed from the command line
6907 before it is added to file signatures,
6912 will be removed before the command is executed.
6913 For example, the command line:
6916 echo Last build occurred $( $TODAY $). > $TARGET
6920 would execute the command:
6923 echo Last build occurred $TODAY. > $TARGET
6927 but the command signature added to any target files would be:
6930 echo Last build occurred . > $TARGET
6933 .SS Python Code Substitution
6935 Any python code within
6937 pairs gets evaluated by python 'eval', with the python globals set to
6938 the current environment's set of construction variables.
6939 So in the following case:
6942 env.Command('foo.out', 'foo.in',
6943 '''echo ${COND==1 and 'FOO' or 'BAR'} > $TARGET''')
6945 the command executed will be either
6953 according to the current value of env['COND'] when the command is
6954 executed. The evaluation occurs when the target is being
6955 built, not when the SConscript is being read. So if env['COND'] is changed
6956 later in the SConscript, the final value will be used.
6958 Here's a more interesting example. Note that all of COND, FOO, and
6959 BAR are environment variables, and their values are substituted into
6960 the final command. FOO is a list, so its elements are interpolated
6961 separated by spaces.
6966 env['FOO'] = ['foo1', 'foo2']
6967 env['BAR'] = 'barbar'
6968 env.Command('foo.out', 'foo.in',
6969 'echo ${COND==1 and FOO or BAR} > $TARGET')
6971 # Will execute this:
6972 # echo foo1 foo2 > foo.out
6975 SCons uses the following rules when converting construction variables into
6979 When the value is a string it is interpreted as a space delimited list of
6980 command line arguments.
6983 When the value is a list it is interpreted as a list of command line
6984 arguments. Each element of the list is converted to a string.
6987 Anything that is not a list or string is converted to a string and
6988 interpreted as a single command line argument.
6991 Newline characters (\\n) delimit lines. The newline parsing is done after
6992 all other parsing, so it is not possible for arguments (e.g. file names) to
6993 contain embedded newline characters. This limitation will likely go away in
6994 a future version of SCons.
7002 new file types for implicit dependencies.
7003 Scanner accepts the following arguments:
7007 1) a Python function that will process
7009 and return a list of strings (file names)
7010 representing the implicit
7011 dependencies found in the contents;
7013 2) a dictionary that maps keys
7014 (typically the file suffix, but see below for more discussion)
7015 to other Scanners that should be called.
7017 If the argument is actually a Python function,
7018 the function must take three or four arguments:
7020 def scanner_function(node, env, path):
7022 def scanner_function(node, env, path, arg=None):
7026 argument is the internal
7027 SCons node representing the file.
7030 to fetch the name of the file, and
7031 .B node.get_contents()
7032 to fetch contents of the file.
7033 Note that the file is
7035 guaranteed to exist before the scanner is called,
7036 so the scanner function should check that
7037 if there's any chance that the scanned file
7039 (for example, if it's built from other files).
7043 argument is the construction environment for the scan.
7044 Fetch values from it using the
7050 argument is a tuple (or list)
7051 of directories that can be searched
7053 This will usually be the tuple returned by the
7055 argument (see below).
7059 argument is the argument supplied
7060 when the scanner was created, if any.
7063 The name of the Scanner.
7065 to identify the Scanner internally.
7068 An optional argument that, if specified,
7069 will be passed to the scanner function
7071 and the path function
7075 An optional list that can be used to
7076 determine which scanner should be used for
7078 In the usual case of scanning for file names,
7079 this argument will be a list of suffixes
7080 for the different file types that this
7081 Scanner knows how to scan.
7082 If the argument is a string,
7083 then it will be expanded
7084 into a list by the current environment.
7087 A Python function that takes four or five arguments:
7088 a construction environment,
7089 a Node for the directory containing
7090 the SConscript file in which
7091 the first target was defined,
7092 a list of target nodes,
7093 a list of source nodes,
7094 and an optional argument supplied
7095 when the scanner was created.
7098 returns a tuple of directories
7099 that can be searched for files to be returned
7100 by this Scanner object.
7103 function can be used to return a ready-made
7105 for a given construction variable name,
7106 instead of having to write your own function from scratch.)
7109 The class of Node that should be returned
7110 by this Scanner object.
7111 Any strings or other objects returned
7112 by the scanner function
7113 that are not of this class
7114 will be run through the
7119 A Python function that will take a string
7121 and turn it into the appropriate class of Node
7122 to be returned by this Scanner object.
7125 An optional Python function that takes two arguments,
7126 a Node (file) and a construction environment,
7127 and returns whether the
7128 Node should, in fact,
7129 be scanned for dependencies.
7130 This check can be used to eliminate unnecessary
7131 calls to the scanner function when,
7132 for example, the underlying file
7133 represented by a Node does not yet exist.
7136 An optional flag that
7137 specifies whether this scanner should be re-invoked
7138 on the dependency files returned by the scanner.
7139 When this flag is not set,
7140 the Node subsystem will
7141 only invoke the scanner on the file being scanned,
7142 and not (for example) also on the files
7143 specified by the #include lines
7144 in the file being scanned.
7146 may be a callable function,
7147 in which case it will be called with a list of
7149 should return a list of Nodes
7150 that should be scanned recursively;
7151 this can be used to select a specific subset of
7152 Nodes for additional scanning.
7157 .B SourceFileScanner
7158 object that is used by
7161 .BR SharedObject (),
7165 which scanner should be used
7166 for different file extensions.
7168 .BR SourceFileScanner.add_scanner ()
7169 method to add your own Scanner object
7173 that builds target programs or
7174 libraries from a list of
7175 source files of different types:
7178 def xyz_scan(node, env, path):
7179 contents = node.get_contents()
7180 # Scan the contents and return the included files.
7182 XYZScanner = Scanner(xyz_scan)
7184 SourceFileScanner.add_scanner('.xyx', XYZScanner)
7186 env.Program('my_prog', ['file1.c', 'file2.f', 'file3.xyz'])
7189 .SH SYSTEM-SPECIFIC BEHAVIOR
7190 SCons and its configuration files are very portable,
7191 due largely to its implementation in Python.
7192 There are, however, a few portability
7193 issues waiting to trap the unwary.
7195 SCons handles the upper-case
7197 file suffix differently,
7198 depending on the capabilities of
7199 the underlying system.
7200 On a case-sensitive system
7201 such as Linux or UNIX,
7202 SCons treats a file with a
7204 suffix as a C++ source file.
7205 On a case-insensitive system
7207 SCons treats a file with a
7209 suffix as a C source file.
7211 SCons handles the upper-case
7213 file suffix differently,
7214 depending on the capabilities of
7215 the underlying system.
7216 On a case-sensitive system
7217 such as Linux or UNIX,
7218 SCons treats a file with a
7220 suffix as a Fortran source file
7221 that is to be first run through
7222 the standard C preprocessor.
7223 On a case-insensitive system
7225 SCons treats a file with a
7227 suffix as a Fortran source file that should
7229 be run through the C preprocessor.
7230 .SS Windows: Cygwin Tools and Cygwin Python vs. Windows Pythons
7231 Cygwin supplies a set of tools and utilities
7232 that let users work on a
7233 Windows system using a more POSIX-like environment.
7234 The Cygwin tools, including Cygwin Python,
7236 by sharing an ability to interpret UNIX-like path names.
7237 For example, the Cygwin tools
7238 will internally translate a Cygwin path name
7239 like /cygdrive/c/mydir
7240 to an equivalent Windows pathname
7241 of C:/mydir (equivalent to C:\\mydir).
7244 that are built for native Windows execution,
7245 such as the python.org and ActiveState versions,
7246 do not have the Cygwin path name semantics.
7247 This means that using a native Windows version of Python
7248 to build compiled programs using Cygwin tools
7249 (such as gcc, bison, and flex)
7250 may yield unpredictable results.
7251 "Mixing and matching" in this way
7252 can be made to work,
7253 but it requires careful attention to the use of path names
7254 in your SConscript files.
7256 In practice, users can sidestep
7257 the issue by adopting the following rules:
7259 use the Cygwin-supplied Python interpreter
7261 when using Microsoft Visual C/C++
7262 (or some other Windows compiler)
7263 use the python.org or ActiveState version of Python
7265 .SS Windows: scons.bat file
7267 SCons is executed via a wrapper
7270 This has (at least) two ramifications:
7272 First, Windows command-line users
7273 that want to use variable assignment
7275 may have to put double quotes
7276 around the assignments:
7279 scons "FOO=BAR" "BAZ=BLEH"
7282 Second, the Cygwin shell does not
7283 recognize this file as being the same
7286 command issued at the command-line prompt.
7287 You can work around this either by
7290 from the Cygwin command line,
7291 or by creating a wrapper shell
7297 The MinGW bin directory must be in your PATH environment variable or the
7298 PATH variable under the ENV construction variable for SCons
7299 to detect and use the MinGW tools. When running under the native Windows
7300 Python interpreter, SCons will prefer the MinGW tools over the Cygwin
7301 tools, if they are both installed, regardless of the order of the bin
7302 directories in the PATH variable. If you have both MSVC and MinGW
7303 installed and you want to use MinGW instead of MSVC,
7304 then you must explictly tell SCons to use MinGW by passing
7310 to the Environment() function, because SCons will prefer the MSVC tools
7311 over the MinGW tools.
7315 To help you get started using SCons,
7316 this section contains a brief overview of some common tasks.
7318 .SS Basic Compilation From a Single Source File
7322 env.Program(target = 'foo', source = 'foo.c')
7325 Note: Build the file by specifying
7326 the target as an argument
7327 ("scons foo" or "scons foo.exe").
7328 or by specifying a dot ("scons .").
7330 .SS Basic Compilation From Multiple Source Files
7334 env.Program(target = 'foo', source = Split('f1.c f2.c f3.c'))
7337 .SS Setting a Compilation Flag
7340 env = Environment(CCFLAGS = '-g')
7341 env.Program(target = 'foo', source = 'foo.c')
7344 .SS Search The Local Directory For .h Files
7348 need to set CCFLAGS to specify -I options by hand.
7349 SCons will construct the right -I options from CPPPATH.
7352 env = Environment(CPPPATH = ['.'])
7353 env.Program(target = 'foo', source = 'foo.c')
7356 .SS Search Multiple Directories For .h Files
7359 env = Environment(CPPPATH = ['include1', 'include2'])
7360 env.Program(target = 'foo', source = 'foo.c')
7363 .SS Building a Static Library
7367 env.StaticLibrary(target = 'foo', source = Split('l1.c l2.c'))
7368 env.StaticLibrary(target = 'bar', source = ['l3.c', 'l4.c'])
7371 .SS Building a Shared Library
7375 env.SharedLibrary(target = 'foo', source = ['l5.c', 'l6.c'])
7376 env.SharedLibrary(target = 'bar', source = Split('l7.c l8.c'))
7379 .SS Linking a Local Library Into a Program
7382 env = Environment(LIBS = 'mylib', LIBPATH = ['.'])
7383 env.Library(target = 'mylib', source = Split('l1.c l2.c'))
7384 env.Program(target = 'prog', source = ['p1.c', 'p2.c'])
7387 .SS Defining Your Own Builder Object
7389 Notice that when you invoke the Builder,
7390 you can leave off the target file suffix,
7391 and SCons will add it automatically.
7394 bld = Builder(action = 'pdftex < $SOURCES > $TARGET'
7396 src_suffix = '.tex')
7397 env = Environment(BUILDERS = {'PDFBuilder' : bld})
7398 env.PDFBuilder(target = 'foo.pdf', source = 'foo.tex')
7400 # The following creates "bar.pdf" from "bar.tex"
7401 env.PDFBuilder(target = 'bar', source = 'bar')
7404 Note also that the above initialization
7405 overwrites the default Builder objects,
7406 so the Environment created above
7407 can not be used call Builders like env.Program(),
7408 env.Object(), env.StaticLibrary(), etc.
7410 .SS Adding Your Own Builder Object to an Environment
7413 bld = Builder(action = 'pdftex < $SOURCES > $TARGET'
7415 src_suffix = '.tex')
7417 env.Append(BUILDERS = {'PDFBuilder' : bld})
7418 env.PDFBuilder(target = 'foo.pdf', source = 'foo.tex')
7419 env.Program(target = 'bar', source = 'bar.c')
7422 You also can use other Pythonic techniques to add
7423 to the BUILDERS construction variable, such as:
7427 env['BUILDERS]['PDFBuilder'] = bld
7430 .SS Defining Your Own Scanner Object
7432 The following example shows an extremely simple scanner (the
7435 that doesn't use a search path at all
7436 and simply returns the
7437 file names present on any
7439 lines in the scanned file.
7440 This would implicitly assume that all included
7441 files live in the top-level directory:
7446 '\" Note: the \\ in the following are for the benefit of nroff/troff,
7447 '\" not inappropriate doubled escape characters within the r'' raw string.
7448 include_re = re.compile(r'^include\\s+(\\S+)$', re.M)
7450 def kfile_scan(node, env, path, arg):
7451 contents = node.get_contents()
7452 includes = include_re.findall(contents)
7455 kscan = Scanner(name = 'kfile',
7456 function = kfile_scan,
7459 scanners = Environment().Dictionary('SCANNERS')
7460 env = Environment(SCANNERS = scanners + [kscan])
7462 env.Command('foo', 'foo.k', 'kprocess < $SOURCES > $TARGET')
7464 bar_in = File('bar.in')
7465 env.Command('bar', bar_in, 'kprocess $SOURCES > $TARGET')
7466 bar_in.target_scanner = kscan
7469 Here is a similar but more complete example that searches
7470 a path of directories
7473 construction variable)
7474 for files that actually exist:
7477 include_re = re.compile(r'^include\\s+(\\S+)$', re.M)
7479 def my_scan(node, env, path, arg):
7480 contents = node.get_contents()
7481 includes = include_re.findall(contents)
7485 for inc in includes:
7487 file = dir + os.sep + inc
7488 if os.path.exists(file):
7489 results.append(file)
7493 scanner = Scanner(name = 'myscanner',
7497 path_function = FindPathDirs('MYPATH'),
7499 scanners = Environment().Dictionary('SCANNERS')
7500 env = Environment(SCANNERS = scanners + [scanner])
7505 function used in the previous example returns a function
7506 (actually a callable Python object)
7507 that will return a list of directories
7510 construction variable.
7511 If you need to customize how the search path is derived,
7512 you would provide your own
7514 argument when creating the Scanner object,
7518 # MYPATH is a list of directories to search for files in
7519 def pf(env, dir, target, source, arg):
7520 top_dir = Dir('#').abspath
7522 if env.has_key('MYPATH'):
7523 for p in env['MYPATH']:
7524 results.append(top_dir + os.sep + p)
7527 scanner = Scanner(name = 'myscanner',
7535 .SS Creating a Hierarchical Build
7537 Notice that the file names specified in a subdirectory's
7539 file are relative to that subdirectory.
7545 env.Program(target = 'foo', source = 'foo.c')
7547 SConscript('sub/SConscript')
7552 # Builds sub/foo from sub/foo.c
7553 env.Program(target = 'foo', source = 'foo.c')
7555 SConscript('dir/SConscript')
7560 # Builds sub/dir/foo from sub/dir/foo.c
7561 env.Program(target = 'foo', source = 'foo.c')
7564 .SS Sharing Variables Between SConscript Files
7566 You must explicitly Export() and Import() variables that
7567 you want to share between SConscript files.
7573 env.Program(target = 'foo', source = 'foo.c')
7576 SConscript('subdirectory/SConscript')
7578 subdirectory/SConscript:
7581 env.Program(target = 'foo', source = 'foo.c')
7584 .SS Building Multiple Variants From the Same Source
7586 Use the build_dir keyword argument to
7587 the SConscript function to establish
7588 one or more separate build directories for
7589 a given source directory:
7594 cppdefines = ['FOO']
7595 Export("cppdefines")
7596 SConscript('src/SConscript', build_dir='foo')
7598 cppdefines = ['BAR']
7599 Export("cppdefines")
7600 SConscript('src/SConscript', build_dir='bar')
7604 Import("cppdefines")
7605 env = Environment(CPPDEFINES = cppdefines)
7606 env.Program(target = 'src', source = 'src.c')
7609 Note the use of the Export() method
7610 to set the "cppdefines" variable to a different
7611 value each time we call the SConscript function.
7613 .SS Hierarchical Build of Two Libraries Linked With a Program
7618 env = Environment(LIBPATH = ['#libA', '#libB'])
7620 SConscript('libA/SConscript')
7621 SConscript('libB/SConscript')
7622 SConscript('Main/SConscript')
7627 env.Library('a', Split('a1.c a2.c a3.c'))
7632 env.Library('b', Split('b1.c b2.c b3.c'))
7637 e = env.Copy(LIBS = ['a', 'b'])
7638 e.Program('foo', Split('m1.c m2.c m3.c'))
7641 The '#' in the LIBPATH directories specify that they're relative to the
7642 top-level directory, so they don't turn into "Main/libA" when they're
7643 used in Main/SConscript.
7645 Specifying only 'a' and 'b' for the library names
7646 allows SCons to append the appropriate library
7647 prefix and suffix for the current platform
7648 (for example, 'liba.a' on POSIX systems,
7649 'a.lib' on Windows).
7651 .SS Customizing contruction variables from the command line.
7653 The following would allow the C compiler to be specified on the command
7654 line or in the file custom.py.
7657 opts = Options('custom.py')
7658 opts.Add('CC', 'The C compiler.')
7659 env = Environment(options=opts)
7660 Help(opts.GenerateHelpText(env))
7663 The user could specify the C compiler on the command line:
7669 or in the custom.py file:
7675 or get documentation on the options:
7686 .SS Using Microsoft Visual C++ precompiled headers
7688 Since windows.h includes everything and the kitchen sink, it can take quite
7689 some time to compile it over and over again for a bunch of object files, so
7690 Microsoft provides a mechanism to compile a set of headers once and then
7691 include the previously compiled headers in any object file. This
7692 technology is called precompiled headers. The general recipe is to create a
7693 file named "StdAfx.cpp" that includes a single header named "StdAfx.h", and
7694 then include every header you want to precompile in "StdAfx.h", and finally
7695 include "StdAfx.h" as the first header in all the source files you are
7696 compiling to object files. For example:
7700 #include <windows.h>
7701 #include <my_big_header.h>
7720 /* do some other stuff */
7726 env['PCHSTOP'] = 'StdAfx.h'
7727 env['PCH'] = env.PCH('StdAfx.cpp')[0]
7728 env.Program('MyApp', ['Foo.cpp', 'Bar.cpp'])
7731 For more information see the document for the PCH builder, and the PCH and
7732 PCHSTOP construction variables. To learn about the details of precompiled
7733 headers consult the MSDN documention for /Yc, /Yu, and /Yp.
7735 .SS Using Microsoft Visual C++ external debugging information
7737 Since including debugging information in programs and shared libraries can
7738 cause their size to increase significantly, Microsoft provides a mechanism
7739 for including the debugging information in an external file called a PDB
7740 file. SCons supports PDB files through the PDB construction
7746 env['PDB'] = 'MyApp.pdb'
7747 env.Program('MyApp', ['Foo.cpp', 'Bar.cpp'])
7750 For more information see the document for the PDB construction variable.
7755 Specifies the directory that contains the SCons Python module directory
7756 (e.g. /home/aroach/scons-src-0.01/src/engine).
7759 A string of options that will be used by scons in addition to those passed
7760 on the command line.
7771 Steven Knight <knight@baldmt.com>
7773 Anthony Roach <aroach@electriceyeball.com>