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 "December 2005"
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.
96 reads and executes the SConscript files as Python scripts,
97 so you may use normal Python scripting capabilities
98 (such as flow control, data manipulation, and imported Python libraries)
99 to handle complicated build situations.
101 however, reads and executes all of the SConscript files
103 it begins building any targets.
104 To make this obvious,
106 prints the following messages about what it is doing:
110 scons: Reading SConscript files ...
111 scons: done reading SConscript files.
112 scons: Building targets ...
114 scons: done building targets.
119 (everything except the line that reads "cp foo.in foo.out")
120 may be suppressed using the
125 does not automatically propagate
126 the external environment used to execute
128 to the commands used to build target files.
129 This is so that builds will be guaranteed
130 repeatable regardless of the environment
131 variables set at the time
134 This also means that if the compiler or other commands
135 that you want to use to build your target files
136 are not in standard system locations,
138 will not find them unless
139 you explicitly set the PATH
140 to include those locations.
141 Whenever you create an
143 construction environment,
144 you can propagate the value of PATH
145 from your external environment as follows:
149 env = Environment(ENV = {'PATH' : os.environ['PATH']})
152 Similarly, if the commands use external environment variables
153 like $PATH, $HOME, $JAVA_HOME, $LANG, $SHELL, $TERM, etc.,
154 these variables can also be explicitly propagated:
158 env = Environment(ENV = {'PATH' : os.environ['PATH'],
159 'HOME' : os.environ['HOME']})
162 Or you may explicitly propagate the invoking user's
163 complete external environment:
167 env = Environment(ENV = os.environ['PATH'])
170 This comes at the expense of making your build
171 dependent on the user's environment being set correctly,
172 but it may be more convenient for many configurations.
175 can scan known input files automatically for dependency
176 information (for example, #include statements
177 in C or C++ files) and will rebuild dependent files appropriately
178 whenever any "included" input file changes.
181 ability to define new scanners for unknown input file types.
184 knows how to fetch files automatically from
185 SCCS or RCS subdirectories
186 using SCCS, RCS or BitKeeper.
189 is normally executed in a top-level directory containing a
191 file, optionally specifying
192 as command-line arguments
193 the target file or files to be built.
195 By default, the command
201 will build all target files in or below the current directory.
202 Explicit default targets
203 (to be built when no targets are specified on the command line)
204 may be defined the SConscript file(s)
207 function, described below.
211 targets are specified in the SConscript file(s),
212 all target files in or below the current directory
213 may be built by explicitly specifying
214 the current directory (.)
215 as a command-line target:
221 Building all target files,
222 including any files outside of the current directory,
223 may be specified by supplying a command-line target
224 of the root directory (on POSIX systems):
230 or the path name(s) of the volume(s) in which all the targets
231 should be built (on Windows systems):
237 To build only specific targets,
238 supply them as command-line arguments:
244 in which case only the specified targets will be built
245 (along with any derived files on which they depend).
247 Specifying "cleanup" targets in SConscript files is not
250 flag removes all files
251 necessary to build the specified target:
257 to remove all target files, or:
260 scons -c build export
263 to remove target files under build and export.
264 Additional files or directories to remove can be specified using the
267 Conversely, targets that would normally be removed by the
270 can be prevented from being removed by using the
274 A subset of a hierarchical tree may be built by
275 remaining at the top-level directory (where the
277 file lives) and specifying the subdirectory as the target to be
284 or by changing directory and invoking scons with the
286 option, which traverses up the directory
287 hierarchy until it finds the
289 file, and then builds
290 targets relatively to the current subdirectory:
298 supports building multiple targets in parallel via a
300 option that takes, as its argument, the number
301 of simultaneous tasks that may be spawned:
307 builds four targets in parallel, for example.
310 can maintain a cache of target (derived) files that can
311 be shared between multiple builds. When caching is enabled in a
312 SConscript file, any target files built by
315 to the cache. If an up-to-date target file is found in the cache, it
316 will be retrieved from the cache instead of being rebuilt locally.
317 Caching behavior may be disabled and controlled in other ways by the
319 .BR --cache-disable ,
322 command-line options. The
324 option is useful to prevent multiple builds
325 from trying to update the cache simultaneously.
327 Values of variables to be passed to the SConscript file(s)
328 may be specified on the command line:
334 These variables are available in SConscript files
335 through the ARGUMENTS dictionary,
336 and can be used in the SConscript file(s) to modify
337 the build in any way:
340 if ARGUMENTS.get('debug', 0):
341 env = Environment(CCFLAGS = '-g')
346 The command-line variable arguments are also available
348 indexed by their order on the command line.
349 This allows you to process them in order rather than by name,
351 ARGLIST[0] returns a tuple
352 containing (argname, argvalue).
353 A Python exception is thrown if you
354 try to access a list member that
358 requires Python version 1.5.2 or later.
359 There should be no other dependencies or requirements to run
362 .\" The following paragraph reflects the default tool search orders
363 .\" currently in SCons/Tool/__init__.py. If any of those search orders
364 .\" change, this documentation should change, too.
367 knows how to search for available programming tools
371 searches in order for the
372 Microsoft Visual C++ tools,
373 the MinGW tool chain,
374 the Intel compiler tools,
375 and the PharLap ETS compiler.
378 searches in order for the
381 and the Microsoft Visual C++ tools,
382 On SGI IRIX, IBM AIX, Hewlett Packard HP-UX, and Sun Solaris systems,
384 searches for the native compiler tools
385 (MIPSpro, Visual Age, aCC, and Forte tools respectively)
386 and the GCC tool chain.
387 On all other platforms,
388 including POSIX (Linux and UNIX) platforms,
391 for the GCC tool chain,
392 the Microsoft Visual C++ tools,
393 and the Intel compiler tools.
394 You may, of course, override these default values
395 by appropriate configuration of
396 Environment construction variables.
401 supports the same command-line options as GNU
403 and many of those supported by
408 Ignored for compatibility with non-GNU versions of
412 -c, --clean, --remove
413 Clean up by removing all target files for which a construction
414 command is specified.
415 Also remove any files or directories associated to the construction command
419 Will not remove any targets specified by the
424 .RI --cache-debug= file
425 Print debug information about the
435 the debug information are printed to the standard output.
436 The printed messages describe what signature file names are
437 being looked for in, retrieved from, or written to the
442 --cache-disable, --no-cache
443 Disable the derived-file caching specified by
446 will neither retrieve files from the cache
447 nor copy files to the cache.
450 --cache-force, --cache-populate
453 populate a cache by copying any already-existing, up-to-date
454 derived files to the cache,
455 in addition to files built by this invocation.
456 This is useful to populate a new cache with
457 all the current derived files,
458 or to add to the cache any derived files
459 recently built with caching disabled via the
467 and retrieving a derived file from the cache,
469 that would have been executed to build the file,
470 instead of the usual report,
471 "Retrieved `file' from cache."
472 This will produce consistent output for build logs,
473 regardless of whether a target
474 file was rebuilt or retrieved from the cache.
478 This specifies how the
480 call should use or generate the
481 results of configuration tests.
482 The option should be specified from
483 among the following choices:
487 scons will use its normal dependency mechanisms
488 to decide if a test must be rebuilt or not.
489 This saves time by not running the same configuration tests
490 every time you invoke scons,
491 but will overlook changes in system header files
492 or external commands (such as compilers)
493 if you don't specify those dependecies explicitly.
494 This is the default behavior.
498 If this option is specified,
499 all configuration tests will be re-run
500 regardless of whether the
501 cached results are out of date.
502 This can be used to explicitly
503 force the configuration tests to be updated
504 in response to an otherwise unconfigured change
505 in a system header file or compiler.
509 If this option is specified,
510 no configuration tests will be rerun
511 and all results will be taken from cache.
512 Note that scons will still consider it an error
513 if --config=cache is specified
514 and a necessary test does not
515 yet have any results in the cache.
518 .RI "-C" " directory" ", --directory=" directory
519 Change to the specified
521 before searching for the
526 file, or doing anything
529 options are interpreted
530 relative to the previous one, and the right-most
532 option wins. (This option is nearly
534 .BR "-f directory/SConstruct" ,
535 except that it will search for
540 in the specified directory.)
544 .\" Display dependencies while building target files. Useful for
545 .\" figuring out why a specific file is being rebuilt, as well as
546 .\" general debugging of the build process.
550 Works exactly the same way as the
552 option except for the way default targets are handled.
553 When this option is used and no targets are specified on the command line,
554 all default targets are built, whether or not they are below the current
559 Debug the build process.
561 specifies what type of debugging:
565 Print how many objects are created
566 of the various classes used internally by SCons
567 before and after reading the SConscript files
568 and before and after building targets.
569 This only works when run under Python 2.1 or later.
573 Print the dependency tree
574 after each top-level target is built. This prints out only derived files.
578 Print an explanation of precisely why
580 is deciding to (re-)build any targets.
581 (Note: this does not print anything
588 Instruct the scanner that searches for libraries
589 to print a message about each potential library
590 name it is searching for,
591 and about the actual libraries it finds.
595 Print the include tree after each top-level target is built.
596 This is generally used to find out what files are included by the sources
597 of a given derived file:
600 $ scons --debug=includes foo.o
605 Prints a summary of hits and misses in the Memoizer,
606 the internal SCons subsystem for caching
607 various values in memory instead of
608 recomputing them each time they're needed.
612 Prints how much memory SCons uses
613 before and after reading the SConscript files
614 and before and after building targets.
618 Disables use of the Memoizer,
619 the internal SCons subsystem for caching
620 various values in memory instead of
621 recomputing them each time they're needed.
622 This provides more accurate counts of the
623 underlying function calls in the
624 Python profiler output when using the
627 (When the Memoizer is used,
628 the profiler counts all
629 memoized functions as being executed
630 by the Memoizer's wrapper calls.)
634 Prints a list of the various objects
635 of the various classes used internally by SCons.
636 This only works when run under Python 2.1 or later.
640 Re-run SCons under the control of the
646 Print the raw command line used to build each target
647 before the construction environment variables are substituted.
648 Also shows which targets are being built by this command.
649 Output looks something like this:
651 $ scons --debug=presub
652 Building myprog.o with action(s):
653 $SHCC $SHCCFLAGS $CPPFLAGS $_CPPINCFLAGS -c -o $TARGET $SOURCES
659 Prints an internal Python stack trace
660 when encountering an otherwise unexplained error.
664 Print the dependency tree along with status information. This is the
665 same as the debug=tree option, but additional status information is
666 provided for each node in the tree.
670 Prints various time profiling information: the time spent
671 executing each build command, the total build time, the total time spent
672 executing build commands, the total time spent executing SConstruct and
673 SConscript files, and the total time spent executing SCons itself.
677 Print the dependency tree
678 after each top-level target is built. This prints out the complete
679 dependency tree including implicit dependencies and ignored
683 .RI --diskcheck= types
684 Enable specific checks for
685 whether or not there is a file on disk
686 where the SCons configuration expects a directory
688 and whether or not RCS or SCCS sources exist
689 when searching for source and include files.
692 argument can be set to:
694 to enable all checks explicitly
695 (the default behavior);
697 to disable all such checks;
699 to check that files and directories on disk
700 match SCons' expected configuration;
702 to check for the existence of an RCS source
703 for any missing source or include files;
705 to check for the existence of an SCCS source
706 for any missing source or include files.
707 Multiple checks can be specified separated by commas;
709 .B --diskcheck=sccs,rcs
710 would still check for SCCS and RCS sources,
711 but disable the check for on-disk matches of files and directories.
712 Disabling some or all of these checks
713 can provide a performance boost for large configurations,
714 or when the configuration will check for files and/or directories
715 across networked or shared file systems,
716 at the slight increased risk of an incorrect build
717 or of not handling errors gracefully
718 (if include files really should be
719 found in SCCS or RCS, for example,
720 or if a file really does exist
721 where the SCons configuration expects a directory).
724 .\" -e, --environment-overrides
725 .\" Variables from the execution environment override construction
726 .\" variables from the SConscript files.
729 .RI -f " file" ", --file=" file ", --makefile=" file ", --sconstruct=" file
732 as the initial SConscript file.
736 Print a local help message for this build, if one is defined in
737 the SConscript file(s), plus a line that describes the
739 option for command-line option help. If no local help message
740 is defined, prints the standard help message about command-line
741 options. Exits after displaying the appropriate message.
745 Print the standard help message about command-line options and
750 Ignore all errors from commands executed to rebuild files.
753 .RI -I " directory" ", --include-dir=" directory
757 imported Python modules. If several
760 are used, the directories are searched in the order specified.
764 Cache implicit dependencies. This can cause
766 to miss changes in the implicit dependencies in cases where a new implicit
767 dependency is added earlier in the implicit dependency search path
768 (e.g. CPPPATH) than a current implicit dependency with the same name.
771 --implicit-deps-changed
772 Force SCons to ignore the cached implicit dependencies. This causes the
773 implicit dependencies to be rescanned and recached. This implies
774 .BR --implicit-cache .
777 --implicit-deps-unchanged
778 Force SCons to ignore changes in the implicit dependencies.
779 This causes cached implicit dependencies to always be used.
781 .BR --implicit-cache .
784 .RI -j " N" ", --jobs=" N
785 Specifies the number of jobs (commands) to run simultaneously.
786 If there is more than one
788 option, the last one is effective.
792 .\" is specified without an argument,
794 .\" will not limit the number of
795 .\" simultaneous jobs.
799 Continue as much as possible after an error. The target that
800 failed and those that depend on it will not be remade, but other
801 targets specified on the command line will still be processed.
804 .\" .RI -l " N" ", --load-average=" N ", --max-load=" N
805 .\" No new jobs (commands) will be started if
806 .\" there are other jobs running and the system load
807 .\" average is at least
809 .\" (a floating-point number).
812 .RI --duplicate= ORDER
813 There are three ways to duplicate files in a build tree: hard links,
814 soft (symbolic) links and copies. The default behaviour of SCons is to
815 prefer hard links to soft links to copies. You can specify different
816 behaviours with this option.
826 SCons will attempt to duplicate files using
827 the mechanisms in the specified order.
832 .\" List derived files (targets, dependencies) that would be built,
833 .\" but do not build them.
834 .\" [XXX This can probably go away with the right
835 .\" combination of other options. Revisit this issue.]
839 .\" List derived files that would be built, with the actions
840 .\" (commands) that build them. Does not build the files.
841 .\" [XXX This can probably go away with the right
842 .\" combination of other options. Revisit this issue.]
846 .\" List derived files that would be built, plus where the file is
847 .\" defined (file name and line number). Does not build the files.
848 .\" [XXX This can probably go away with the right
849 .\" combination of other options. Revisit this issue.]
853 Ignored for compatibility with non-GNU versions of
857 .RI --max-drift= SECONDS
858 Set the maximum expected drift in the modification time of files to
860 This value determines how long a file must be unmodified
861 before its cached content signature
862 will be used instead of
863 calculating a new content signature (MD5 checksum)
864 of the file's contents.
865 The default value is 2 days, which means a file must have a
866 modification time of at least two days ago in order to have its
867 cached content signature used.
868 A negative value means to never cache the content
869 signature and to ignore the cached value if there already is one. A value
870 of 0 means to always use the cached signature,
871 no matter how old the file is.
874 -n, --just-print, --dry-run, --recon
875 No execute. Print the commands that would be executed to build
876 any out-of-date target files, but do not execute the commands.
879 .\" .RI -o " file" ", --old-file=" file ", --assume-old=" file
883 .\" not rebuild anything due to changes in the contents of
886 .\" .RI --override " file"
887 .\" Read values to override specific build environment variables
888 .\" from the specified
892 .\" Print the data base (construction environments,
893 .\" Builder and Scanner objects) that are defined
894 .\" after reading the SConscript files.
895 .\" After printing, a normal build is performed
896 .\" as usual, as specified by other command-line options.
897 .\" This also prints version information
902 .\" To print the database without performing a build do:
910 Run SCons under the Python profiler
911 and save the results in the specified
913 The results may be analyzed using the Python
918 Do not run any commands, or print anything. Just return an exit
919 status that is zero if the specified targets are already up to
920 date, non-zero otherwise.
923 Quiets SCons status messages about
924 reading SConscript files,
926 and entering directories.
927 Commands that are executed
928 to rebuild target files are still printed.
931 .\" -r, -R, --no-builtin-rules, --no-builtin-variables
932 .\" Clear the default construction variables. Construction
933 .\" environments that are created will be completely empty.
937 Build dependencies in a random order. This is useful when
938 building multiple trees simultaneously with caching enabled,
939 to prevent multiple builds from simultaneously trying to build
940 or retrieve the same target files.
943 -s, --silent, --quiet
944 Silent. Do not print commands that are executed to rebuild
946 Also suppresses SCons status messages.
949 -S, --no-keep-going, --stop
950 Ignored for compatibility with GNU
955 Ignored for compatibility with GNU
957 (Touching a file to make it
958 appear up-to-date is unnecessary when using
962 .RI --taskmastertrace= file
963 Prints trace information to the specified
965 about how the internal Taskmaster object
966 evaluates and controls the order in which Nodes are built.
969 may be used to specify the standard output.
972 -u, --up, --search-up
973 Walks up the directory structure until an
978 file is found, and uses that
979 as the top of the directory tree.
980 If no targets are specified on the command line,
981 only targets at or below the
982 current directory will be built.
986 Works exactly the same way as the
988 option except for the way default targets are handled.
989 When this option is used and no targets are specified on the command line,
990 all default targets that are defined in the SConscript(s) in the current
991 directory are built, regardless of what directory the resultant targets end
998 version, copyright information,
999 list of authors, and any other relevant information.
1003 -w, --print-directory
1004 Print a message containing the working directory before and
1005 after other processing.
1008 .RI --warn= type ", --warn=no-" type
1009 Enable or disable warnings.
1011 specifies the type of warnings to be enabled or disabled:
1014 --warn=all, --warn=no-all
1015 Enables or disables all warnings.
1018 --warn=dependency, --warn=no-dependency
1019 Enables or disables warnings about dependencies.
1020 These warnings are disabled by default.
1023 --warn=deprecated, --warn=no-deprecated
1024 Enables or disables warnings about use of deprecated features.
1025 These warnings are enabled by default.
1028 --warn=missing-sconscript, --warn=no-missing-sconscript
1029 Enables or disables warnings about missing SConscript files.
1030 These warnings are enabled by default.
1033 --no-print-directory
1034 Turn off -w, even if it was turned on implicitly.
1037 .\" .RI --write-filenames= file
1038 .\" Write all filenames considered into
1042 .\" .RI -W " file" ", --what-if=" file ", --new-file=" file ", --assume-new=" file
1043 .\" Pretend that the target
1046 .\" modified. When used with the
1049 .\" show you what would be rebuilt if you were to modify that file.
1055 .\" --warn-undefined-variables
1056 .\" Warn when an undefined variable is referenced.
1059 .RI -Y " repository" ", --repository=" repository
1060 Search the specified repository for any input and target
1061 files not found in the local directory hierarchy. Multiple
1063 options may specified, in which case the
1064 repositories are searched in the order specified.
1066 .SH CONFIGURATION FILE REFERENCE
1067 .\" .SS Python Basics
1068 .\" XXX Adding this in the future would be a help.
1069 .SS Construction Environments
1070 A construction environment is the basic means by which the SConscript
1071 files communicate build information to
1073 A new construction environment is created using the
1081 By default, a new construction environment is
1082 initialized with a set of builder methods
1083 and construction variables that are appropriate
1084 for the current platform.
1085 An optional platform keyword argument may be
1086 used to specify that an environment should
1087 be initialized for a different platform:
1090 env = Environment(platform = 'cygwin')
1091 env = Environment(platform = 'os2')
1092 env = Environment(platform = 'posix')
1093 env = Environment(platform = 'win32')
1096 Specifying a platform initializes the appropriate
1097 construction variables in the environment
1098 to use and generate file names with prefixes
1099 and suffixes appropriate for the platform.
1107 variables from the user's external environment
1108 to the construction environment's
1111 This is so that any executed commands
1112 that use sockets to connect with other systems
1113 (such as fetching source files from
1114 external CVS repository specifications like
1115 .BR :pserver:anonymous@cvs.sourceforge.net:/cvsroot/scons )
1116 will work on Windows systems.
1118 The platform argument may be function or callable object,
1119 in which case the Environment() method
1120 will call the specified argument to update
1121 the new construction environment:
1124 def my_platform(env):
1125 env['VAR'] = 'xyzzy'
1127 env = Environment(platform = my_platform)
1130 Additionally, a specific set of tools
1131 with which to initialize the environment
1132 may specified as an optional keyword argument:
1135 env = Environment(tools = ['msvc', 'lex'])
1138 Non-built-in tools may be specified using the toolpath argument:
1141 env = Environment(tools = ['default', 'foo'], toolpath = ['tools'])
1144 This looks for a tool specification in tools/foo.py (as well as
1145 using the ordinary default tools for the platform). foo.py should
1146 have two functions: generate(env, **kw) and exists(env).
1150 modifies the passed-in environment
1151 to set up variables so that the tool
1153 it may use any keyword arguments
1154 that the user supplies (see below)
1155 to vary its initialization.
1158 function should return a true
1159 value if the tool is available.
1160 Tools in the toolpath are used before
1161 any of the built-in ones. For example, adding gcc.py to the toolpath
1162 would override the built-in gcc tool.
1163 Also note that the toolpath is
1164 stored in the environment for use
1172 base = Environment(toolpath=['custom_path'])
1173 derived = base.Copy(tools=['custom_tool'])
1174 derived.CustomBuilder()
1177 The elements of the tools list may also
1178 be functions or callable objects,
1179 in which case the Environment() method
1180 will call the specified elements
1181 to update the new construction environment:
1185 env['XYZZY'] = 'xyzzy'
1187 env = Environment(tools = [my_tool])
1190 The individual elements of the tools list
1191 may also themselves be two-element lists of the form
1192 .RI ( toolname ", " kw_dict ).
1193 SCons searches for the
1195 specification file as described above, and
1198 which must be a dictionary, as keyword arguments to the tool's
1203 function can use the arguments to modify the tool's behavior
1204 by setting up the environment in different ways
1205 or otherwise changing its initialization.
1208 # in tools/my_tool.py:
1209 def generate(env, **kw):
1210 # Sets MY_TOOL to the value of keyword argument 'arg1' or 1.
1211 env['MY_TOOL'] = kw.get('arg1', '1')
1216 env = Environment(tools = ['default', ('my_tool', {'arg1': 'abc'})],
1220 The tool definition (i.e. my_tool()) can use the PLATFORM variable from
1221 the environment it receives to customize the tool for different platforms.
1223 If no tool list is specified, then SCons will auto-detect the installed
1224 tools using the PATH variable in the ENV construction variable and the
1225 platform name when the Environment is constructed. Changing the PATH
1226 variable after the Environment is constructed will not cause the tools to
1229 SCons supports the following tool specifications out of the box:
1305 Additionally, there is a "tool" named
1307 which configures the
1308 environment with a default set of tools for the current platform.
1310 On posix and cygwin platforms
1311 the GNU tools (e.g. gcc) are preferred by SCons,
1312 on Windows the Microsoft tools (e.g. msvc)
1313 followed by MinGW are preferred by SCons,
1314 and in OS/2 the IBM tools (e.g. icc) are preferred by SCons.
1318 Build rules are specified by calling a construction
1319 environment's builder methods.
1320 The arguments to the builder methods are
1322 (a list of target files)
1325 (a list of source files).
1327 Because long lists of file names
1328 can lead to a lot of quoting,
1333 and a same-named environment method
1334 that split a single string
1335 into a list, separated on
1336 strings of white-space characters.
1337 (These are similar to the
1338 string.split() method
1339 from the standard Python library,
1340 but work even if the input isn't a string.)
1342 Like all Python arguments,
1343 the target and source arguments to a builder method
1344 can be specified either with or without
1345 the "target" and "source" keywords.
1346 When the keywords are omitted,
1347 the target is first,
1348 followed by the source.
1349 The following are equivalent examples of calling the Program builder method:
1352 env.Program('bar', ['bar.c', 'foo.c'])
1353 env.Program('bar', Split('bar.c foo.c'))
1354 env.Program('bar', env.Split('bar.c foo.c'))
1355 env.Program(source = ['bar.c', 'foo.c'], target = 'bar')
1356 env.Program(target = 'bar', Split('bar.c foo.c'))
1357 env.Program(target = 'bar', env.Split('bar.c foo.c'))
1358 env.Program('bar', source = string.split('bar.c foo.c'))
1361 When the target shares the same base name
1362 as the source and only the suffix varies,
1363 and if the builder method has a suffix defined for the target file type,
1364 then the target argument may be omitted completely,
1367 will deduce the target file name from
1368 the source file name.
1369 The following examples all build the
1375 (on Windows systems)
1376 from the bar.c source file:
1379 env.Program(target = 'bar', source = 'bar.c')
1380 env.Program('bar', source = 'bar.c')
1381 env.Program(source = 'bar.c')
1382 env.Program('bar.c')
1385 It is possible to override or add construction variables when calling a
1386 builder method by passing additional keyword arguments.
1387 These overridden or added
1388 variables will only be in effect when building the target, so they will not
1389 affect other parts of the build. For example, if you want to add additional
1390 libraries for just one program:
1393 env.Program('hello', 'hello.c', LIBS=['gl', 'glut'])
1396 or generate a shared library with a non-standard suffix:
1399 env.SharedLibrary('word', 'word.cpp',
1401 LIBSUFFIXES=['.ocx'])
1404 (Note that both the $SHLIBSUFFIX and $LIBSUFFIXES variables must be set
1405 if you want SCons to search automatically
1406 for dependencies on the non-standard library names;
1407 see the descriptions of these variables, below, for more information.)
1409 Although the builder methods defined by
1412 methods of a construction environment object,
1413 they may also be called without an explicit environment:
1416 Program('hello', 'hello.c')
1417 SharedLibrary('word', 'word.cpp')
1421 the methods are called internally using a default construction
1422 environment that consists of the tools and values that
1424 has determined are appropriate for the local system.
1426 Builder methods that can be called without an explicit
1427 environment may be called from custom Python modules that you
1428 import into an SConscript file by adding the following
1429 to the Python module:
1432 from SCons.Script import *
1435 All builder methods return a list of Nodes
1436 that represent the target or targets that will be built.
1439 is an internal SCons object
1441 build targets or sources.
1443 The returned Node(s)
1444 can be passed to other builder methods as source(s)
1445 or passed to any SCons function or method
1446 where a filename would normally be accepted.
1447 For example, if it were necessary
1450 flag when compiling one specific object file:
1453 bar_obj_list = env.StaticObject('bar.c', CPPDEFINES='-DBAR')
1454 env.Program(source = ['foo.c', bar_obj_list, 'main.c'])
1457 Using a Node in this way
1458 makes for a more portable build
1459 by avoiding having to specify
1460 a platform-specific object suffix
1461 when calling the Program() builder method.
1463 Note that Builder calls will automatically "flatten"
1464 the source and target file lists,
1465 so it's all right to have the bar_obj list
1466 return by the StaticObject() call
1467 in the middle of the source file list.
1468 If you need to manipulate a list of lists returned by Builders
1469 directly using Python,
1470 you can either build the list by hand:
1473 foo = Object('foo.c')
1474 bar = Object('bar.c')
1475 objects = ['begin.o'] + foo + ['middle.o'] + bar + ['end.o']
1476 for object in objects:
1483 to create a list containing just the Nodes,
1484 which may be more convenient:
1487 foo = Object('foo.c')
1488 bar = Object('bar.c')
1489 objects = Flatten(['begin.o', foo, 'middle.o', bar, 'end.o'])
1490 for object in objects:
1494 The path name for a Node's file may be used
1495 by passing the Node to the Python-builtin
1500 bar_obj_list = env.StaticObject('bar.c', CPPDEFINES='-DBAR')
1501 print "The path to bar_obj is:", str(bar_obj_list[0])
1504 Note again that because the Builder call returns a list,
1505 we have to access the first element in the list
1506 .B (bar_obj_list[0])
1507 to get at the Node that actually represents
1510 Builder calls support a
1512 keyword argument that
1513 specifies that the Builder's action(s)
1515 after changing directory.
1519 a string or a directory Node,
1520 scons will change to the specified directory.
1523 is not a string or Node
1525 then scons will change to the
1526 target file's directory.
1529 # scons will change to the "sub" subdirectory
1530 # before executing the "cp" command.
1531 env.Command('sub/dir/foo.out', 'sub/dir/foo.in',
1532 "cp dir/foo.in dir/foo.out",
1535 # Because chdir is not a string, scons will change to the
1536 # target's directory ("sub/dir") before executing the
1538 env.Command('sub/dir/foo.out', 'sub/dir/foo.in',
1539 "cp foo.in foo.out",
1543 Note that scons will
1545 automatically modify
1547 construction variables like
1551 when using the chdir
1552 keyword argument--that is,
1553 the expanded file names
1554 will still be relative to
1555 the top-level SConstruct directory,
1556 and consequently incorrect
1557 relative to the chdir directory.
1558 If you use the chdir keyword argument,
1559 you will typically need to supply a different
1565 to use just the filename portion of the
1569 provides the following builder methods:
1571 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1572 '\" BEGIN GENERATED BUILDER DESCRIPTIONS
1574 '\" The descriptions below of the various SCons Builders are generated
1575 '\" from the .xml files that live next to the various Python modules in
1576 '\" the build enginer library. If you're reading this [gnt]roff file
1577 '\" with an eye towards patching this man page, you can still submit
1578 '\" a diff against this text, but it will have to be translated to a
1579 '\" diff against the underlying .xml file before the patch is actually
1580 '\" accepted. If you do that yourself, it will make it easier to
1581 '\" integrate the patch.
1583 '\" BEGIN GENERATED BUILDER DESCRIPTIONS
1584 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1586 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1587 '\" END GENERATED BUILDER DESCRIPTIONS
1589 '\" The descriptions above of the various SCons Builders are generated
1590 '\" from the .xml files that live next to the various Python modules in
1591 '\" the build enginer library. If you're reading this [gnt]roff file
1592 '\" with an eye towards patching this man page, you can still submit
1593 '\" a diff against this text, but it will have to be translated to a
1594 '\" diff against the underlying .xml file before the patch is actually
1595 '\" accepted. If you do that yourself, it will make it easier to
1596 '\" integrate the patch.
1598 '\" END GENERATED BUILDER DESCRIPTIONS
1599 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1602 targets of builder methods automatically depend on their sources.
1603 An explicit dependency can
1604 be specified using the
1606 method of a construction environment (see below).
1611 source files for various programming languages,
1612 so the dependencies do not need to be specified explicitly.
1613 By default, SCons can
1616 Fortran source files with
1618 (POSIX systems only),
1623 and assembly language files with
1625 (POSIX systems only),
1630 for C preprocessor dependencies.
1631 SCons also has default support
1632 for scanning D source files,
1633 You can also write your own Scanners
1634 to add support for additional source file types.
1635 These can be added to the default
1636 Scanner object used by
1642 Builders by adding them
1644 .B SourceFileScanner
1647 See the section "Scanner Objects,"
1648 below, for a more information about
1649 defining your own Scanner objects.
1651 .SS Methods and Functions to Do Things
1652 In addition to Builder methods,
1654 provides a number of other construction environment methods
1655 and global functions to
1656 manipulate the build configuration.
1658 Usually, a construction environment method
1659 and global function with the same name both exist
1660 so that you don't have to remember whether
1661 to a specific bit of functionality
1662 must be called with or without a construction environment.
1663 In the following list,
1664 if you call something as a global function
1667 .RI Function( arguments )
1669 and if you call something through a construction
1670 environment it looks like:
1672 .RI env.Function( arguments )
1674 If you can call the functionality in both ways,
1675 then both forms are listed.
1677 Global functions may be called from custom Python modules that you
1678 import into an SConscript file by adding the following
1679 to the Python module:
1682 from SCons.Script import *
1685 Except where otherwise noted,
1687 construction environment method
1689 provide the exact same functionality.
1690 The only difference is that,
1692 calling the functionality through a construction environment will
1693 substitute construction variables into
1694 any supplied strings.
1697 env = Environment(FOO = 'foo')
1701 the first call to the global
1703 function will actually add a target named
1705 to the list of default targets,
1706 while the second call to the
1708 construction environment method
1709 will expand the value
1710 and add a target named
1712 to the list of default targets.
1713 For more on construction variable expansion,
1714 see the next section on
1715 construction variables.
1717 Construction environment methods
1718 and global functions supported by
1722 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1724 .RI Action( action ", [" strfunction ", " varlist ])
1726 .RI env.Action( action ", [" strfunction ", " varlist ])
1727 Creates an Action object for
1730 See the section "Action Objects,"
1731 below, for a complete explanation of the arguments and behavior.
1735 form of the invocation will expand
1736 construction variables in any arguments strings,
1740 at the time it is called
1741 using the construction variables in the
1743 construction environment through which
1748 form delays all variable expansion
1749 until the Action object is actually used.
1751 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1753 .RI AddPostAction( target ", " action )
1755 .RI env.AddPostAction( target ", " action )
1756 Arranges for the specified
1762 The specified action(s) may be
1763 an Action object, or anything that
1764 can be converted into an Action object
1767 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1769 .RI AddPreAction( target ", " action )
1771 .RI env.AddPreAction( target ", " action )
1772 Arranges for the specified
1775 before the specified
1778 The specified action(s) may be
1779 an Action object, or anything that
1780 can be converted into an Action object
1783 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1785 .RI Alias( alias ", [" targets ", [" action ]])
1787 .RI env.Alias( alias ", [" targets ", [" action ]])
1788 Creates one or more phony targets that
1789 expand to one or more other targets.
1794 can be specified that will be executed
1795 whenever the any of the alias targets are out-of-date.
1796 Returns the Node object representing the alias,
1797 which exists outside of any file system.
1798 This Node object, or the alias name,
1799 may be used as a dependency of any other target,
1800 including another alias.
1802 can be called multiple times for the same
1803 alias to add additional targets to the alias,
1804 or additional actions to the list for this alias.
1808 Alias('install', '/usr/bin')
1809 Alias(['install', 'install-lib'], '/usr/local/lib')
1811 env.Alias('install', ['/usr/local/bin', '/usr/local/lib'])
1812 env.Alias('install', ['/usr/local/man'])
1814 env.Alias('update', ['file1', 'file2'], "update_database $SOURCES")
1817 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1819 .RI AlwaysBuild( target ", ...)"
1821 .RI env.AlwaysBuild( target ", ...)"
1824 so that it is always assumed to be out of date,
1825 and will always be rebuilt if needed.
1828 does not add its target(s) to the default target list,
1829 so the targets will only be built
1830 if they are specified on the command line,
1831 or are a dependent of a target specified on the command line--but
1834 be built if so specified.
1835 Multiple targets can be passed in to a single call to
1838 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1840 .RI env.Append( key = val ", [...])"
1841 Appends the specified keyword arguments
1842 to the end of construction variables in the environment.
1843 If the Environment does not have
1844 the specified construction variable,
1845 it is simply added to the environment.
1846 If the values of the construction variable
1847 and the keyword argument are the same type,
1848 then the two values will be simply added together.
1849 Otherwise, the construction variable
1850 and the value of the keyword argument
1851 are both coerced to lists,
1852 and the lists are added together.
1853 (See also the Prepend method, below.)
1856 env.Append(CCFLAGS = ' -g', FOO = ['foo.yyy'])
1859 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1861 .RI env.AppendENVPath( name ", " newpath ", [" envname ", " sep ])
1862 This appends new path elements to the given path in the
1863 specified external environment
1867 any particular path once (leaving the last one it encounters and
1868 ignoring the rest, to preserve path order),
1869 and to help assure this,
1870 will normalize all paths (using
1873 .BR os.path.normcase ).
1874 This can also handle the
1875 case where the given old path variable is a list instead of a
1876 string, in which case a list will be returned instead of a string.
1880 print 'before:',env['ENV']['INCLUDE']
1881 include_path = '/foo/bar:/foo'
1882 env.AppendENVPath('INCLUDE', include_path)
1883 print 'after:',env['ENV']['INCLUDE']
1887 after: /biz:/foo/bar:/foo
1890 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1892 .RI env.AppendUnique( key = val ", [...])"
1893 Appends the specified keyword arguments
1894 to the end of construction variables in the environment.
1895 If the Environment does not have
1896 the specified construction variable,
1897 it is simply added to the environment.
1898 If the construction variable being appended to is a list,
1899 then any value(s) that already exist in the
1900 construction variable will
1902 be added again to the list.
1905 env.AppendUnique(CCFLAGS = '-g', FOO = ['foo.yyy'])
1908 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1911 A factory function that
1912 returns a Builder object
1913 to be used to fetch source files
1915 The returned Builder
1916 is intended to be passed to the
1921 env.SourceCode('.', env.BitKeeper())
1924 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1926 .RI BuildDir( build_dir ", " src_dir ", [" duplicate ])
1928 .RI env.BuildDir( build_dir ", " src_dir ", [" duplicate ])
1929 This specifies a build directory
1931 in which to build all derived files
1932 that would normally be built under
1934 Multiple build directories can be set up for multiple build variants, for
1937 must be underneath the SConstruct file's directory,
1940 may not be underneath the
1943 The default behavior is for
1945 to duplicate all of the files in the tree underneath
1949 and then build the derived files within the copied tree.
1950 (The duplication is performed by
1952 depending on the platform; see also the
1955 This guarantees correct builds
1956 regardless of whether intermediate source files
1957 are generated during the build,
1958 where preprocessors or other scanners search
1960 or whether individual compilers or other invoked tools
1961 are hard-coded to put derived files in the same directory as source files.
1963 This behavior of making a complete copy of the source tree
1964 may be disabled by setting
1969 to invoke Builders using the
1970 path names of source files in
1972 and the path names of derived files within
1974 This is always more efficient than
1976 and is usually safe for most builds.
1980 may cause build problems
1981 if source files are generated during the build,
1982 if any invoked tools are hard-coded to
1983 put derived files in the same directory as the source files.
1985 Note that specifying a
1987 works most naturally
1988 with a subsidiary SConscript file
1989 in the source directory.
1991 you would then call the subsidiary SConscript file
1992 not in the source directory,
1997 had made a virtual copy of the source tree
1998 regardless of the value of
2000 This is how you tell
2002 which variant of a source tree to build.
2006 BuildDir('build-variant1', 'src')
2007 SConscript('build-variant1/SConscript')
2008 BuildDir('build-variant2', 'src')
2009 SConscript('build-variant2/SConscript')
2015 function, described below,
2017 specify a build directory
2018 in conjunction with calling a subsidiary
2021 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2023 .RI Builder( action ", [" arguments ])
2025 .RI env.Builder( action ", [" arguments ])
2026 Creates a Builder object for
2029 See the section "Builder Objects,"
2030 below, for a complete explanation of the arguments and behavior.
2034 form of the invocation will expand
2035 construction variables in any arguments strings,
2039 at the time it is called
2040 using the construction variables in the
2042 construction environment through which
2047 form delays all variable expansion
2048 until after the Builder object is actually called.
2050 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2052 .RI CacheDir( cache_dir )
2054 .RI env.CacheDir( cache_dir )
2057 will maintain a cache of derived files in
2059 The derived files in the cache will be shared
2060 among all the builds using the same
2068 finds a derived file that needs to be rebuilt,
2069 it will first look in the cache to see if a
2070 derived file has already been built
2071 from identical input files and an identical build action
2072 (as incorporated into the MD5 build signature).
2075 will retrieve the file from the cache.
2076 If the derived file is not present in the cache,
2079 then place a copy of the built file in the cache
2080 (identified by its MD5 build signature),
2081 so that it may be retrieved by other
2082 builds that need to build the same derived file
2083 from identical inputs.
2087 may be disabled for any invocation
2096 will place a copy of
2098 derived files in the cache,
2099 even if they already existed
2100 and were not built by this invocation.
2101 This is useful to populate a cache
2104 is added to a build,
2113 "Retrieved `file' from cache,"
2116 option is being used.
2121 will print the action that
2123 have been used to build the file,
2124 without any indication that
2125 the file was actually retrieved from the cache.
2126 This is useful to generate build logs
2127 that are equivalent regardless of whether
2128 a given derived file has been built in-place
2129 or retrieved from the cache.
2131 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2133 .RI Clean( targets ", " files_or_dirs )
2135 .RI env.Clean( targets ", " files_or_dirs )
2136 This specifies a list of files or directories which should be removed
2137 whenever the targets are specified with the
2139 command line option.
2140 The specified targets may be a list
2141 or an individual target.
2145 and create new targets or add files and directories to the
2146 clean list for the specified targets.
2148 Multiple files or directories should be specified
2149 either as separate arguments to the
2151 method, or as a list.
2153 will also accept the return value of any of the construction environment
2159 function overrides calling
2161 for the same target,
2162 and any targets passed to both functions will
2171 Clean('foo', ['bar', 'baz'])
2172 Clean('dist', env.Program('hello', 'hello.c'))
2173 Clean(['foo', 'bar'], 'something_else_to_clean')
2176 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2178 .RI Command( target ", " source ", " action ", [" key = val ", ...])"
2180 .RI env.Command( target ", " source ", " action ", [" key = val ", ...])"
2181 Executes a specific action
2182 (or list of actions)
2183 to build a target file or files.
2184 This is more convenient
2185 than defining a separate Builder object
2186 for a single special-case build.
2188 As a special case, the
2190 keyword argument can
2193 that will be used to scan the sources.
2197 if any of the sources will be directories
2198 that must be scanned on-disk for
2199 changes to files that aren't
2200 already specified in other Builder of function calls.)
2202 Any other keyword arguments specified override any
2203 same-named existing construction variables.
2205 An action can be an external command,
2206 specified as a string,
2207 or a callable Python object;
2208 see "Action Objects," below,
2209 for more complete information.
2210 Also note that a string specifying an external command
2211 may be preceded by an
2214 to suppress printing the command in question,
2218 to ignore the exit status of the external command.
2222 env.Command('foo.out', 'foo.in',
2223 "$FOO_BUILD < $SOURCES > $TARGET")
2225 env.Command('bar.out', 'bar.in',
2227 "$BAR_BUILD < $SOURCES > $TARGET"],
2228 ENV = {'PATH' : '/usr/local/bin/'})
2230 def rename(env, target, source):
2232 os.rename('.tmp', str(target[0]))
2234 env.Command('baz.out', 'baz.in',
2235 ["$BAZ_BUILD < $SOURCES > .tmp",
2241 function will usually assume, by default,
2242 that the specified targets and/or sources are Files,
2243 if no other part of the configuration
2244 identifies what type of entry it is.
2245 If necessary, you can explicitly specify
2246 that targets or source nodes should
2247 be treated as directoriese
2255 env.Command('ddd.list', Dir('ddd'), 'ls -l $SOURCE > $TARGET')
2257 env['DISTDIR'] = 'destination/directory'
2258 env.Command(env.Dir('$DISTDIR')), None, make_distdir)
2261 (Also note that SCons will usually
2262 automatically create any directory necessary to hold a target file,
2263 so you normally don't need to create directories by hand.)
2265 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2267 .RI Configure( env ", [" custom_tests ", " conf_dir ", " log_file ", " config_h ])
2269 .RI env.Configure([ custom_tests ", " conf_dir ", " log_file ", " config_h ])
2270 Creates a Configure object for integrated
2271 functionality similar to GNU autoconf.
2272 See the section "Configure Contexts,"
2273 below, for a complete explanation of the arguments and behavior.
2275 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2277 .RI env.Copy([ key = val ", ...])"
2278 Return a separate copy of a construction environment.
2279 If there are any keyword arguments specified,
2280 they are added to the returned copy,
2281 overwriting any existing values
2286 env3 = env.Copy(CCFLAGS = '-g')
2289 Additionally, a list of tools and a toolpath may be specified, as in
2290 the Environment constructor:
2293 def MyTool(env): env['FOO'] = 'bar'
2294 env4 = env.Copy(tools = ['msvc', MyTool])
2297 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2299 .RI env.CVS( repository ", " module )
2300 A factory function that
2301 returns a Builder object
2302 to be used to fetch source files
2306 The returned Builder
2307 is intended to be passed to the
2311 The optional specified
2313 will be added to the beginning
2314 of all repository path names;
2315 this can be used, in essence,
2316 to strip initial directory names
2317 from the repository path names,
2318 so that you only have to
2319 replicate part of the repository
2320 directory hierarchy in your
2321 local build directory:
2324 # Will fetch foo/bar/src.c
2325 # from /usr/local/CVSROOT/foo/bar/src.c.
2326 env.SourceCode('.', env.CVS('/usr/local/CVSROOT'))
2328 # Will fetch bar/src.c
2329 # from /usr/local/CVSROOT/foo/bar/src.c.
2330 env.SourceCode('.', env.CVS('/usr/local/CVSROOT', 'foo'))
2333 # from /usr/local/CVSROOT/foo/bar/src.c.
2334 env.SourceCode('.', env.CVS('/usr/local/CVSROOT', 'foo/bar'))
2337 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2339 .RI Default( targets )
2341 .RI env.Default( targets )
2342 This specifies a list of default targets,
2343 which will be built by
2345 if no explicit targets are given on the command line.
2349 and add to the list of default targets.
2351 Multiple targets should be specified as
2352 separate arguments to the
2354 method, or as a list.
2356 will also accept the Node returned by any
2357 of a construction environment's
2362 Default('foo', 'bar', 'baz')
2363 env.Default(['a', 'b', 'c'])
2364 hello = env.Program('hello', 'hello.c')
2372 will clear all default targets.
2375 will add to the (now empty) default-target list
2378 The current list of targets added using the
2380 function or method is available in the
2385 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2387 .RI DefaultEnvironment([ args ])
2388 Creates and returns a default construction environment object.
2389 This construction environment is used internally by SCons
2390 in order to execute many of the global functions in this list,
2391 and to fetch source files transparently
2392 from source code management systems.
2394 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2396 .RI Depends( target ", " dependency )
2398 .RI env.Depends( target ", " dependency )
2399 Specifies an explicit dependency;
2400 the target file(s) will be rebuilt
2401 whenever the dependency file(s) has changed.
2402 This should only be necessary
2403 for cases where the dependency
2404 is not caught by a Scanner
2408 env.Depends('foo', 'other-input-file-for-foo')
2411 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2413 .RI env.Dictionary([ vars ])
2414 Returns a dictionary object
2415 containing copies of all of the
2416 construction variables in the environment.
2417 If there are any variable names specified,
2418 only the specified construction
2419 variables are returned in the dictionary.
2422 dict = env.Dictionary()
2423 cc_dict = env.Dictionary('CC', 'CCFLAGS', 'CCCOM')
2426 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2428 .RI Dir( name ", [" directory ])
2430 .RI env.Dir( name ", [" directory ])
2431 This returns a Directory Node,
2432 an object that represents the specified directory
2435 can be a relative or absolute path.
2437 is an optional directory that will be used as the parent directory.
2440 is specified, the current script's directory is used as the parent.
2442 Directory Nodes can be used anywhere you
2443 would supply a string as a directory name
2444 to a Builder method or function.
2445 Directory Nodes have attributes and methods
2446 that are useful in many situations;
2447 see "File and Directory Nodes," below.
2449 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2451 .RI env.Dump([ key ])
2452 Returns a pretty printable representation of the environment.
2456 should be a string containing the name of the variable of interest.
2461 print env.Dump('CCCOM')
2465 '$CC $CCFLAGS $CPPFLAGS $_CPPDEFFLAGS $_CPPINCFLAGS -c -o $TARGET $SOURCES'
2475 'ARCOM': '$AR $ARFLAGS $TARGET $SOURCES\n$RANLIB $RANLIBFLAGS $TARGET',
2478 'ASCOM': '$AS $ASFLAGS -o $TARGET $SOURCES',
2483 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2485 .RI EnsurePythonVersion( major ", " minor )
2487 .RI env.EnsurePythonVersion( major ", " minor )
2488 Ensure that the Python version is at least
2491 print out an error message and exit SCons with a non-zero exit code if the
2492 actual Python version is not late enough.
2495 EnsurePythonVersion(2,2)
2498 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2500 .RI EnsureSConsVersion( major ", " minor ", [" revision ])
2502 .RI env.EnsureSConsVersion( major ", " minor ", [" revision ])
2503 Ensure that the SCons version is at least
2506 .IR major.minor.revision .
2511 print out an error message and exit SCons with a non-zero exit code if the
2512 actual SCons version is not late enough.
2515 EnsureSConsVersion(0,14)
2517 EnsureSConsVersion(0,96,90)
2520 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2522 .RI Environment([ key = value ", ...])"
2524 .RI env.Environment([ key = value ", ...])"
2525 Return a new construction environment
2526 initialized with the specified
2530 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2532 .RI Execute( action ", [" strfunction ", " varlist ])
2534 .RI env.Execute( action ", [" strfunction ", " varlist ])
2535 Executes an Action object.
2538 may be an Action object
2539 (see the section "Action Objects,"
2540 below, for a complete explanation of the arguments and behavior),
2541 or it may be a command-line string,
2543 or executable Python function,
2544 each of which will be converted
2545 into an Action object
2547 The exit value of the command
2548 or return value of the Python function
2551 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2555 .RI env.Exit([ value ])
2561 A default exit value of
2564 is used if no value is specified.
2566 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2570 .RI env.Export( vars )
2573 to export a list of variables from the current
2574 SConscript file to all other SConscript files.
2575 The exported variables are kept in a global collection,
2576 so subsequent calls to
2578 will over-write previous exports that have the same name.
2579 Multiple variable names can be passed to
2581 as separate arguments or as a list. A dictionary can be used to map
2582 variables to a different name when exported. Both local variables and
2583 global variables can be exported.
2588 # Make env available for all SConscript files to Import().
2592 # Make env and package available for all SConscript files:.
2593 Export("env", "package")
2595 # Make env and package available for all SConscript files:
2596 Export(["env", "package"])
2598 # Make env available using the name debug:.
2599 Export({"debug":env})
2605 function supports an
2607 argument that makes it easier to to export a variable or
2608 set of variables to a single SConscript file.
2609 See the description of the
2613 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2615 .RI File( name ", [" directory ])
2617 .RI env.File( name ", [" directory ])
2620 an object that represents the specified file
2623 can be a relative or absolute path.
2625 is an optional directory that will be used as the parent directory.
2627 File Nodes can be used anywhere you
2628 would supply a string as a file name
2629 to a Builder method or function.
2630 File Nodes have attributes and methods
2631 that are useful in many situations;
2632 see "File and Directory Nodes," below.
2634 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2636 .RI FindFile( file ", " dirs )
2638 .RI env.FindFile( file ", " dirs )
2641 in the path specified by
2644 may be a list of file names or a single file name. In addition to searching
2645 for files that exist in the filesytem, this function also searches for
2646 derived files that have not yet been built.
2649 foo = env.FindFile('foo', ['dir1', 'dir2'])
2652 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2654 .RI Flatten( sequence )
2656 .RI env.Flatten( sequence )
2657 Takes a sequence (that is, a Python list or tuple)
2658 that may contain nested sequences
2659 and returns a flattened list containing
2660 all of the individual elements in any sequence.
2661 This can be helpful for collecting
2662 the lists returned by calls to Builders;
2663 other Builders will automatically
2664 flatten lists specified as input,
2665 but direct Python manipulation of
2666 these lists does not:
2669 foo = Object('foo.c')
2670 bar = Object('bar.c')
2672 # Because `foo' and `bar' are lists returned by the Object() Builder,
2673 # `objects' will be a list containing nested lists:
2674 objects = ['f1.o', foo, 'f2.o', bar, 'f3.o']
2676 # Passing such a list to another Builder is all right because
2677 # the Builder will flatten the list automatically:
2678 Program(source = objects)
2680 # If you need to manipulate the list directly using Python, you need to
2681 # call Flatten() yourself, or otherwise handle nested lists:
2682 for object in Flatten(objects):
2686 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2688 .RI GetBuildPath( file ", [" ... ])
2690 .RI env.GetBuildPath( file ", [" ... ])
2693 path name (or names) for the specified
2701 Nodes or strings representing path names.
2703 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2707 .RI env.GetLaunchDir()
2708 Returns the absolute path name of the directory from which
2711 was initially invoked.
2712 This can be useful when using the
2717 options, which internally
2718 change to the directory in which the
2722 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2724 .RI GetOption( name )
2726 .RI env.GetOption( name )
2727 This function provides a way to query a select subset of the scons command line
2728 options from a SConscript file. See
2730 for a description of the options available.
2732 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2734 '\".RI GlobalBuilders( flag )
2738 '\"adds the names of the default builders
2739 '\"(Program, Library, etc.)
2740 '\"to the global name space
2741 '\"so they can be called without an explicit construction environment.
2742 '\"(This is the default.)
2746 '\"the names of the default builders are removed
2747 '\"from the global name space
2748 '\"so that an explicit construction environment is required
2749 '\"to call all builders.
2751 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2755 .RI env.Help( text )
2756 This specifies help text to be printed if the
2758 argument is given to
2762 is called multiple times, the text is appended together in the order
2767 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2769 .RI Ignore( target ", " dependency )
2771 .RI env.Ignore( target ", " dependency )
2772 The specified dependency file(s)
2773 will be ignored when deciding if
2774 the target file(s) need to be rebuilt.
2777 env.Ignore('foo', 'foo.c')
2778 env.Ignore('bar', ['bar1.h', 'bar2.h'])
2781 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2785 .RI env.Import( vars )
2788 to import a list of variables into the current SConscript file. This
2789 will import variables that were exported with
2795 Variables exported by
2798 Multiple variable names can be passed to
2800 as separate arguments or as a list. The variable "*" can be used
2801 to import all variables.
2806 Import("env", "variable")
2807 Import(["env", "variable"])
2811 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2813 .RI Install( dir ", " source )
2815 .RI env.Install( dir ", " source )
2816 Installs one or more source files or directories
2817 in a destination directory
2819 The names of the specified source files or directories
2820 remain the same within the destination directory.
2823 env.Install(dir = '/usr/local/bin', source = ['foo', 'bar'])
2826 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2828 .RI InstallAs( target ", " source )
2830 .RI env.InstallAs( target ", " source )
2831 Installs one or more source files or directories
2833 allowing changing a file or directory name
2834 as part of the installation.
2835 It is an error if the
2839 arguments list different numbers of files or directories.
2842 env.InstallAs(target = '/usr/local/bin/foo',
2843 source = 'foo_debug')
2844 env.InstallAs(target = ['../lib/libfoo.a', '../lib/libbar.a'],
2845 source = ['libFOO.a', 'libBAR.a'])
2848 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2850 .RI Literal( string )
2852 .RI env.Literal( string )
2855 will be preserved as-is
2856 and not have construction variables expanded.
2858 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2860 .RI Local( targets )
2862 .RI env.Local( targets )
2865 will have copies made in the local tree,
2866 even if an already up-to-date copy
2867 exists in a repository.
2868 Returns a list of the target Node or Nodes.
2870 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2872 .RI env.MergeFlags( arg ", [" unique ])
2873 Merges the specified
2875 values to the construction envrionment's construction variables.
2878 argument is not a dictionary,
2879 it is converted to one by calling
2882 before the values are merged.
2885 must be a single value,
2886 so multiple strings must
2887 be passed in as a list,
2888 not as separate arguments to
2889 .BR env.MergeFlags ().
2892 duplicate values are eliminated;
2893 you can, however, specify
2897 When eliminating duplicate values,
2898 any construction variables that end with
2901 keep the left-most unique value.
2902 All other construction variables keep
2903 the right-most unique value.
2908 # Add an optimization flag to $CCFLAGS.
2909 env.MergeFlags('-O3')
2911 # Combine the flags returned from running pkg-config with an optimization
2912 # flag and merge the result into the construction variables.
2913 env.MergeFlags(['!pkg-config gtk+-2.0 --cflags', '-O3'])
2915 env.MergeFlags(['-O3',
2916 '!pkg-config gtk+-2.0 --cflags --libs',
2917 '!pkg-config libpng12 --cflags --libs'])
2920 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2922 .RI NoClean( target ", ...)"
2924 .RI env.NoClean( target ", ...)"
2925 Specifies a list of files or directories which should
2927 be removed whenever the targets (or their dependencies)
2928 are specified with the
2930 command line option.
2931 The specified targets may be a list
2932 or an individual target.
2936 and prevent each specified target
2937 from being removed by calls to the
2941 Multiple files or directories should be specified
2942 either as separate arguments to the
2944 method, or as a list.
2946 will also accept the return value of any of the construction environment
2951 for a target overrides calling
2953 for the same target,
2954 and any targets passed to both functions will
2964 NoClean(env.Program('hello', 'hello.c'))
2967 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2969 .RI env.ParseConfig( command ", [" function ", " unique ])
2972 to modify the environment as specified by the output of
2977 .BR env.MergeFlags (),
2978 which expects the output of a typical
2982 and adds the options
2983 to the appropriate construction variables.
2985 duplicate values are not
2986 added to any construction variables;
2993 and the construction variables they affect
2994 are as specified for the
2995 .BR env.ParseFlags ()
2996 method (which thie method calls).
2997 See that method's description, below,
2998 for a table of options and construction variables.
3000 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3002 .RI ParseDepends( filename ", [" must_exist ])
3004 .RI env.ParseDepends( filename ", [" must_exist " " only_one ])
3005 Parses the contents of the specified
3007 as a list of dependencies in the style of
3011 and explicitly establishes all of the listed dependencies.
3020 argument may be set to a non-zero
3023 throw an exception and
3024 generate an error if the file does not exist,
3025 or is otherwise inaccessible.
3029 argument may be set to a non-zero
3032 thrown an exception and
3034 if the file contains dependency
3035 information for more than one target.
3036 This can provide a small sanity check
3037 for files intended to be generated
3038 by, for example, the
3041 which should typically only
3042 write dependency information for
3043 one output file into a corresponding
3049 and all of the files listed therein
3050 will be interpreted relative to
3051 the directory of the
3053 file which calls the
3057 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3059 .RI env.ParseFlags( flags ", ...)"
3060 Parses one or more strings containing
3061 typical command-line flags for GCC tool chains
3062 and returns a dictionary with the flag values
3063 separated into the appropriate SCons construction variables.
3064 This is intended as a companion to the
3065 .BR env.MergeFlags ()
3066 method, but allows for the values in the returned dictionary
3067 to be modified, if necessary,
3068 before merging them into the construction environment.
3070 .BR env.MergeFlags ()
3071 will call this method if its argument is not a dictionary,
3072 so it is usually not necessary to call
3073 .BR env.ParseFlags ()
3074 directly unless you want to manipulate the values.)
3076 If the first character in any string is
3077 an exclamation mark (!),
3078 the rest of the string is executed as a command,
3079 and the output from the command is
3080 parsed as GCC tool chain command-line flags
3081 and added to the resulting dictionary.
3083 Flag values are translated accordig to the prefix found,
3084 and added to the following construction variables:
3087 -arch CCFLAGS, LINKFLAGS
3089 -framework FRAMEWORKS
3090 -frameworkdir= FRAMEWORKPATH
3092 -isysroot CCFLAGS, LINKFLAGS
3096 -mno-cygwin CCFLAGS, LINKFLAGS
3098 -pthread CCFLAGS, LINKFLAGS
3099 -Wa, ASFLAGS, CCFLAGS
3106 + CCFLAGS, LINKFLAGS
3109 Any other strings not associated with options
3110 are assumed to be the names of libraries
3113 construction variable.
3115 Examples (all of which produce the same result):
3118 dict = env.ParseFlags('-O2 -Dfoo -Dbar=1')
3119 dict = env.ParseFlags('-O2', '-Dfoo', '-Dbar=1')
3120 dict = env.ParseFlags(['-O2', '-Dfoo -Dbar=1'])
3121 dict = env.ParseFlags('-O2', '!echo -Dfoo -Dbar=1')
3124 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3127 A factory function that
3128 returns a Builder object
3129 to be used to fetch source files
3130 from the Perforce source code management system.
3131 The returned Builder
3132 is intended to be passed to the
3137 env.SourceCode('.', env.Perforce())
3140 Perforce uses a number of external
3141 environment variables for its operation.
3142 Consequently, this function adds the
3143 following variables from the user's external environment
3144 to the construction environment's
3157 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3159 .RI Platform( string )
3160 Returns a callable object
3161 that can be used to initialize
3162 a construction environment using the
3163 platform keyword of the Environment() method:
3166 env = Environment(platform = Platform('win32'))
3169 .RI env.Platform( string )
3170 Applies the callable object for the specified platform
3172 to the environment through which the method was called.
3175 env.Platform('posix')
3184 variables from the user's external environment
3185 to the construction environment's
3188 This is so that any executed commands
3189 that use sockets to connect with other systems
3190 (such as fetching source files from
3191 external CVS repository specifications like
3192 .BR :pserver:anonymous@cvs.sourceforge.net:/cvsroot/scons )
3193 will work on Windows systems.
3195 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3197 .RI Precious( target ", ...)"
3199 .RI env.Precious( target ", ...)"
3202 as precious so it is not deleted before it is rebuilt. Normally
3204 deletes a target before building it.
3205 Multiple targets can be passed in to a single call to
3208 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3210 .RI env.Prepend( key = val ", [...])"
3211 Appends the specified keyword arguments
3212 to the beginning of construction variables in the environment.
3213 If the Environment does not have
3214 the specified construction variable,
3215 it is simply added to the environment.
3216 If the values of the construction variable
3217 and the keyword argument are the same type,
3218 then the two values will be simply added together.
3219 Otherwise, the construction variable
3220 and the value of the keyword argument
3221 are both coerced to lists,
3222 and the lists are added together.
3223 (See also the Append method, above.)
3226 env.Prepend(CCFLAGS = '-g ', FOO = ['foo.yyy'])
3229 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3231 .RI env.PrependENVPath( name ", " newpath ", [" envname ", " sep ])
3232 This appends new path elements to the given path in the
3233 specified external environment
3237 any particular path once (leaving the first one it encounters and
3238 ignoring the rest, to preserve path order),
3239 and to help assure this,
3240 will normalize all paths (using
3243 .BR os.path.normcase ).
3244 This can also handle the
3245 case where the given old path variable is a list instead of a
3246 string, in which case a list will be returned instead of a string.
3250 print 'before:',env['ENV']['INCLUDE']
3251 include_path = '/foo/bar:/foo'
3252 env.PrependENVPath('INCLUDE', include_path)
3253 print 'after:',env['ENV']['INCLUDE']
3257 after: /foo/bar:/foo:/biz
3260 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3262 .RI env.PrependUnique( key = val ", [...])"
3263 Appends the specified keyword arguments
3264 to the beginning of construction variables in the environment.
3265 If the Environment does not have
3266 the specified construction variable,
3267 it is simply added to the environment.
3268 If the construction variable being appended to is a list,
3269 then any value(s) that already exist in the
3270 construction variable will
3272 be added again to the list.
3275 env.PrependUnique(CCFLAGS = '-g', FOO = ['foo.yyy'])
3278 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3281 A factory function that
3282 returns a Builder object
3283 to be used to fetch source files
3285 The returned Builder
3286 is intended to be passed to the
3291 env.SourceCode('.', env.RCS())
3296 will fetch source files
3297 from RCS subdirectories automatically,
3299 as demonstrated in the above example
3300 should only be necessary if
3301 you are fetching from
3304 directory as the source files,
3305 or if you need to explicitly specify RCS
3306 for a specific subdirectory.
3308 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3310 .RI env.Replace( key = val ", [...])"
3311 Replaces construction variables in the Environment
3312 with the specified keyword arguments.
3315 env.Replace(CCFLAGS = '-g', FOO = 'foo.xxx')
3318 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3320 .RI Repository( directory )
3322 .RI env.Repository( directory )
3325 is a repository to be searched for files.
3329 and each one adds to the list of
3330 repositories that will be searched.
3334 a repository is a copy of the source tree,
3335 from the top-level directory on down,
3337 both source files and derived files
3338 that can be used to build targets in
3339 the local source tree.
3340 The canonical example would be an
3341 official source tree maintained by an integrator.
3342 If the repository contains derived files,
3343 then the derived files should have been built using
3345 so that the repository contains the necessary
3346 signature information to allow
3348 to figure out when it is appropriate to
3349 use the repository copy of a derived file,
3350 instead of building one locally.
3352 Note that if an up-to-date derived file
3353 already exists in a repository,
3357 make a copy in the local directory tree.
3358 In order to guarantee that a local copy
3364 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3369 what variable(s) to use as the return value(s) of the current SConscript
3370 file. These variables will be returned to the "calling" SConscript file
3371 as the return value(s) of
3373 Multiple variable names should be passed to
3379 Return(["foo", "bar"])
3382 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3384 .RI Scanner( function ", [" argument ", " keys ", " path_function ", " node_class ", " node_factory ", " scan_check ", " recursive ])
3386 .RI env.Scanner( function ", [" argument ", " keys ", " path_function ", " node_class ", " node_factory ", " scan_check ", " recursive ])
3387 Creates a Scanner object for
3390 See the section "Scanner Objects,"
3391 below, for a complete explanation of the arguments and behavior.
3393 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3396 A factory function that
3397 returns a Builder object
3398 to be used to fetch source files
3400 The returned Builder
3401 is intended to be passed to the
3406 env.SourceCode('.', env.SCCS())
3411 will fetch source files
3412 from SCCS subdirectories automatically,
3414 as demonstrated in the above example
3415 should only be necessary if
3416 you are fetching from
3419 directory as the source files,
3420 or if you need to explicitly specify SCCS
3421 for a specific subdirectory.
3423 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3425 .RI SConscript( scripts ", [" exports ", " build_dir ", " src_dir ", " duplicate ])
3427 .RI env.SConscript( scripts ", [" exports ", " build_dir ", " src_dir ", " duplicate ])
3429 .RI SConscript(dirs= subdirs ", [name=" script ", " exports ", " build_dir ", " src_dir ", " duplicate ])
3431 .RI env.SConscript(dirs= subdirs ", [name=" script ", " exports ", " build_dir ", " src_dir ", " duplicate ])
3435 one or more subsidiary SConscript (configuration) files.
3436 There are two ways to call the
3440 The first way you can call
3442 is to explicitly specify one or more
3444 as the first argument.
3445 A single script may be specified as a string;
3446 multiple scripts must be specified as a list
3447 (either explicitly or as created by
3451 The second way you can call
3453 is to specify a list of (sub)directory names
3460 execute a subsidiary configuration file named
3462 in each of the specified directories.
3463 You may specify a name other than
3465 by supplying an optional
3471 argument provides a list of variable names or a dictionary of
3472 named values to export to the
3474 These variables are locally exported only to the specified
3476 and do not affect the
3477 global pool of variables used by
3481 '\"If multiple dirs are provided,
3482 '\"each script gets a fresh export.
3487 function to import the variables.
3491 argument specifies that all of the target files
3492 (for example, object files and executables)
3493 that would normally be built in the subdirectory in which
3495 resides should actually
3499 is interpreted relative to the directory
3500 of the calling SConscript file.
3504 argument specifies that the
3505 source files from which
3506 the target files should be built
3510 is interpreted relative to the directory
3511 of the calling SConscript file.
3515 will link or copy (depending on the platform)
3516 all the source files into the build directory.
3517 This behavior may be disabled by
3518 setting the optional
3521 (it is set to 1 by default),
3524 will refer directly to
3525 the source files in their source directory
3526 when building target files.
3529 is usually safe, and always more efficient
3532 but it may cause build problems in certain end-cases,
3533 such as compiling from source files that
3534 are generated by the build.)
3536 Any variables returned by
3540 will be returned by the call to
3546 SConscript('subdir/SConscript')
3547 foo = SConscript('sub/SConscript', exports='env')
3548 SConscript('dir/SConscript', exports=['env', 'variable'])
3549 SConscript('src/SConscript', build_dir='build', duplicate=0)
3550 SConscript('bld/SConscript', src_dir='src', exports='env variable')
3551 SConscript(dirs=['sub1', 'sub2'])
3552 SConscript(dirs=['sub3', 'sub4'], name='MySConscript')
3555 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3557 .RI SConscriptChdir( value )
3559 .RI env.SConscriptChdir( value )
3562 changes its working directory
3563 to the directory in which each
3564 subsidiary SConscript file lives.
3565 This behavior may be disabled
3566 by specifying either:
3570 env.SConscriptChdir(0)
3575 will stay in the top-level directory
3576 while reading all SConscript files.
3577 (This may be necessary when building from repositories,
3578 when all the directories in which SConscript files may be found
3579 don't necessarily exist locally.)
3581 You may enable and disable
3582 this ability by calling
3589 SConscript('foo/SConscript') # will not chdir to foo
3590 env.SConscriptChdir(1)
3591 SConscript('bar/SConscript') # will chdir to bar
3594 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3596 .RI SConsignFile([ file , dbm_module ])
3598 .RI env.SConsignFile([ file , dbm_module ])
3601 to store all file signatures
3602 in the specified database
3609 (The actual file name(s) stored on disk
3610 may have an appropriated suffix appended
3615 is not an absolute path name,
3616 the file is placed in the same directory as the top-level
3626 will store file signatures
3629 file in each directory,
3630 not in one global database file.
3631 (This was the default behavior
3632 prior to SCons 0.96.91 and 0.97.)
3636 argument can be used to specify
3637 which Python database module
3638 The default is to use a custom
3640 module that uses pickled
3641 Python data structures,
3642 and which works on all Python versions from 1.5.2 on.
3647 # Explicitly stores signatures in ".sconsign.dblite"
3648 # in the top-level SConstruct directory (the
3649 # default behavior).
3652 # Stores signatures in the file "etc/scons-signatures"
3653 # relative to the top-level SConstruct directory.
3654 SConsignFile("etc/scons-signatures")
3656 # Stores signatures in the specified absolute file name.
3657 SConsignFile("/home/me/SCons/signatures")
3659 # Stores signatures in a separate .sconsign file
3660 # in each directory.
3664 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3666 .RI env.SetDefault(key = val ", [...])"
3667 Sets construction variables to default values specified with the keyword
3668 arguments if (and only if) the variables are not already set.
3669 The following statements are equivalent:
3672 env.SetDefault(FOO = 'foo')
3674 if not env.has_key('FOO'): env['FOO'] = 'foo'
3677 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3679 .RI SetOption( name ", " value )
3681 .RI env.SetOption( name ", " value )
3682 This function provides a way to set a select subset of the scons command
3683 line options from a SConscript file. The options supported are:
3685 which corresponds to -c, --clean, and --remove;
3688 corresponds to --duplicate;
3690 which corresponds to --implicit-cache;
3692 which corresponds to --max-drift;
3694 which corresponds to -j and --jobs.
3695 See the documentation for the
3696 corresponding command line object for information about each specific
3700 SetOption('max_drift', 1)
3703 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3705 .RI SideEffect( side_effect ", " target )
3707 .RI env.SideEffect( side_effect ", " target )
3710 as a side effect of building
3716 can be a list, a file name, or a node.
3717 A side effect is a target that is created
3718 as a side effect of building other targets.
3719 For example, a Windows PDB
3720 file is created as a side effect of building the .obj
3721 files for a static library.
3722 If a target is a side effect of multiple build commands,
3724 will ensure that only one set of commands
3725 is executed at a time.
3726 Consequently, you only need to use this method
3727 for side-effect targets that are built as a result of
3728 multiple build commands.
3730 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3732 .RI SourceCode( entries ", " builder )
3734 .RI env.SourceCode( entries ", " builder )
3735 Arrange for non-existent source files to
3736 be fetched from a source code management system
3741 may be a Node, string or list of both,
3742 and may represent either individual
3743 source files or directories in which
3744 source files can be found.
3746 For any non-existent source files,
3748 will search up the directory tree
3758 will not use a builder to fetch
3759 source files for the specified
3763 builder has been specified
3764 for a directory higher up the tree.
3768 fetch files from SCCS or RCS subdirectories
3769 without explicit configuration.
3770 This takes some extra processing time
3771 to search for the necessary
3772 source code management files on disk.
3773 You can avoid these extra searches
3774 and speed up your build a little
3775 by disabling these searches as follows:
3778 env.SourceCode('.', None)
3782 Note that if the specified
3784 is one you create by hand,
3785 it must have an associated
3786 construction environment to use
3787 when fetching a source file.
3790 provides a set of canned factory
3791 functions that return appropriate
3792 Builders for various popular
3793 source code management systems.
3794 Canonical examples of invocation include:
3797 env.SourceCode('.', env.BitKeeper('/usr/local/BKsources'))
3798 env.SourceCode('src', env.CVS('/usr/local/CVSROOT'))
3799 env.SourceCode('/', env.RCS())
3800 env.SourceCode(['f1.c', 'f2.c'], env.SCCS())
3801 env.SourceCode('no_source.c', None)
3803 '\"env.SourceCode('.', env.Subversion('file:///usr/local/Subversion'))
3805 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3807 .RI env.subst( string ", [" raw ", " target ", " source ", " conv ])
3808 Performs construction variable interpolation
3809 on the specified string argument.
3812 leading or trailing white space will
3813 be removed from the result.
3814 and all sequences of white space
3815 will be compressed to a single space character.
3820 character sequences will be stripped from the returned string,
3823 argument may be set to
3825 if you want to preserve white space and
3830 argument may be set to
3832 if you want to strip
3833 all characters between
3839 (as is done for signature calculation).
3846 must be set to lists of
3847 target and source nodes, respectively,
3854 to be available for expansion.
3855 This is usually necessary if you are
3858 from within a Python function used
3862 all returned values are converted
3863 to their string representation.
3867 may specify a conversion function
3868 that will be used in place of
3870 For example, if you want Python objects
3871 (including SCons Nodes)
3872 to be returned as Python objects,
3873 you can use the Python
3875 idiom to pass in an unnamed function
3876 that simply returns its unconverted argument.
3879 print env.subst("The C compiler is: $CC")
3881 def compile(target, source, env):
3882 sourceDir = env.subst("${SOURCE.srcdir}",
3886 source_nodes = env.subst('$EXPAND_TO_NODELIST',
3890 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3892 '\".RI Subversion( repository ", " module )
3893 '\"A factory function that
3894 '\"returns a Builder object
3895 '\"to be used to fetch source files
3896 '\"from the specified Subversion
3898 '\"The returned Builder
3899 '\"is intended to be passed to the
3903 '\"The optional specified
3905 '\"will be added to the beginning
3906 '\"of all repository path names;
3907 '\"this can be used, in essence,
3908 '\"to strip initial directory names
3909 '\"from the repository path names,
3910 '\"so that you only have to
3911 '\"replicate part of the repository
3912 '\"directory hierarchy in your
3913 '\"local build directory:
3916 '\"# Will fetch foo/bar/src.c
3917 '\"# from /usr/local/Subversion/foo/bar/src.c.
3918 '\"env.SourceCode('.', env.Subversion('file:///usr/local/Subversion'))
3920 '\"# Will fetch bar/src.c
3921 '\"# from /usr/local/Subversion/foo/bar/src.c.
3922 '\"env.SourceCode('.', env.Subversion('file:///usr/local/Subversion', 'foo'))
3924 '\"# Will fetch src.c
3925 '\"# from /usr/local/Subversion/foo/bar/src.c.
3926 '\"env.SourceCode('.', env.Subversion('file:///usr/local/Subversion', 'foo/bar'))
3929 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3931 .RI SourceSignatures( type )
3933 .RI env.SourceSignatures( type )
3934 This function tells SCons what type of signature to use for source files:
3938 If the environment method is used,
3939 the specified type of source signature
3940 is only used when deciding whether targets
3941 built with that environment are up-to-date or must be rebuilt.
3942 If the global function is used,
3943 the specified type of source signature becomes the default
3944 used for all decisions
3945 about whether targets are up-to-date.
3947 "MD5" means the signature of a source file
3948 is the MD5 checksum of its contents.
3949 "timestamp" means the signature of a source file
3950 is its timestamp (modification time).
3951 There is no different between the two behaviors
3955 "MD5" signatures take longer to compute,
3956 but are more accurate than "timestamp" signatures.
3957 The default is "MD5".
3959 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3963 .RI env.Split( arg )
3964 Returns a list of file names or other objects.
3966 it will be split on strings of white-space characters
3968 making it easier to write long lists of file names.
3969 If arg is already a list,
3970 the list will be returned untouched.
3971 If arg is any other type of object,
3972 it will be returned as a list
3973 containing just the object.
3976 files = Split("f1.c f2.c f3.c")
3977 files = env.Split("f4.c f5.c f6.c")
3985 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3987 .RI TargetSignatures( type )
3989 .RI env.TargetSignatures( type )
3990 This function tells SCons what type of signatures to use
3995 If the environment method is used,
3996 the specified type of signature is only used
3997 for targets built with that environment.
3998 If the global function is used,
3999 the specified type of signature becomes the default
4000 used for all target files that
4001 don't have an explicit target signature type
4002 specified for their environments.
4004 "build" means the signature of a target file
4005 is made by concatenating all of the
4006 signatures of all its source files.
4007 "content" means the signature of a target
4008 file is an MD5 checksum of its contents.
4009 "build" signatures are usually faster to compute,
4010 but "content" signatures can prevent unnecessary rebuilds
4011 when a target file is rebuilt to the exact same contents
4012 as the previous build.
4013 The default is "build".
4015 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4017 .RI Tool( string [, toolpath ", " **kw ])
4018 Returns a callable object
4019 that can be used to initialize
4020 a construction environment using the
4021 tools keyword of the Environment() method.
4022 The object may be called with a construction
4023 environment as an argument,
4024 in which case the object will
4025 add the necessary variables
4026 to the construction environment
4027 and the name of the tool will be added to the
4029 construction variable.
4031 Additional keyword arguments are passed to the tool's
4036 env = Environment(tools = [ Tool('msvc') ])
4040 t(env) # adds 'msvc' to the TOOLS variable
4041 u = Tool('opengl', toolpath = ['tools'])
4042 u(env) # adds 'opengl' to the TOOLS variable
4045 .RI env.Tool( string [, toolpath ", " **kw ])
4046 Applies the callable object for the specified tool
4048 to the environment through which the method was called.
4050 Additional keyword arguments are passed to the tool's
4056 env.Tool('opengl', toolpath = ['build/tools'])
4059 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4061 .RI Value( value ", [" built_value ])
4063 .RI env.Value( value ", [" built_value ])
4064 Returns a Node object representing the specified Python value. Value
4065 Nodes can be used as dependencies of targets. If the result of
4068 changes between SCons runs, any targets depending on
4070 will be rebuilt. When using timestamp source signatures, Value Nodes'
4071 timestamps are equal to the system time when the Node is created.
4073 The returned Value Node object has a
4075 method that can be used to "build" a Value Node
4076 by setting a new value.
4079 argument can be specified
4080 when the Value Node is created
4081 to indicate the Node should already be considered
4083 There is a corresponding
4085 method that will return the built value of the Node.
4088 def create(target, source, env):
4089 f = open(str(target[0]), 'wb')
4090 f.write('prefix=' + source[0].get_contents())
4092 prefix = ARGUMENTS.get('prefix', '/usr/local')
4094 env['BUILDERS']['Config'] = Builder(action = create)
4095 env.Config(target = 'package-config', source = Value(prefix))
4097 def build_value(target, source, env):
4098 target[0].write(source[0].get_contents())
4100 output = env.Value('before')
4101 input = env.Value('after')
4103 env['BUILDERS']['UpdateValue'] = Builder(action = build_value)
4104 env.UpdateValue(target = Value(output), source = Value(input))
4107 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4109 .RI WhereIs( program ", [" path ", " pathext ", " reject ])
4111 .RI env.WhereIs( program ", [" path ", " pathext ", " reject ])
4113 Searches for the specified executable
4115 returning the full path name to the program
4117 and returning None if not.
4118 Searches the specified
4120 the value of the calling environment's PATH
4121 (env['ENV']['PATH']),
4122 or the user's current external PATH
4123 (os.environ['PATH'])
4125 On Windows systems, searches for executable
4126 programs with any of the file extensions
4127 listed in the specified
4129 the calling environment's PATHEXT
4130 (env['ENV']['PATHEXT'])
4131 or the user's current PATHEXT
4132 (os.environ['PATHEXT'])
4140 .SS SConscript Variables
4141 In addition to the global functions and methods,
4143 supports a number of Python variables
4144 that can be used in SConscript files
4145 to affect how you want the build to be performed.
4146 These variables may be accessed from custom Python modules that you
4147 import into an SConscript file by adding the following
4148 to the Python module:
4151 from SCons.Script import *
4154 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4159 arguments specified on the command line.
4160 Each element in the list is a tuple
4162 .RI ( keyword , value )
4168 elements of the tuple
4170 subscripting for element
4174 of the tuple, respectively.
4177 print "first keyword, value =", ARGLIST[0][0], ARGLIST[0][1]
4178 print "second keyword, value =", ARGLIST[1][0], ARGLIST[1][1]
4179 third_tuple = ARGLIST[2]
4180 print "third keyword, value =", third_tuple[0], third_tuple[1]
4181 for key, value in ARGLIST:
4182 # process key and value
4185 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4188 A dictionary of all the
4190 arguments specified on the command line.
4191 The dictionary is not in order,
4192 and if a given keyword has
4193 more than one value assigned to it
4194 on the command line,
4195 the last (right-most) value is
4201 if ARGUMENTS.get('debug', 0):
4202 env = Environment(CCFLAGS = '-g')
4207 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4210 A list of the targets which
4212 will actually try to build,
4213 regardless of whether they were specified on
4214 the command line or via the
4217 The elements of this list may be strings
4219 nodes, so you should run the list through the Python
4221 function to make sure any Node path names
4222 are converted to strings.
4224 Because this list may be taken from the
4225 list of targets specified using the
4228 the contents of the list may change
4229 on each successive call to
4234 for additional information.
4237 if 'foo' in BUILD_TARGETS:
4238 print "Don't forget to test the `foo' program!"
4239 if 'special/program' in BUILD_TARGETS:
4240 SConscript('special')
4245 list only contains targets expected listed
4246 on the command line or via calls to the
4251 contain all dependent targets that will be built as
4252 a result of making the sure the explicitly-specified
4253 targets are up to date.
4255 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4257 COMMAND_LINE_TARGETS
4258 A list of the targets explicitly specified on
4260 If there are no targets specified on the command line,
4262 This can be used, for example,
4263 to take specific actions only
4264 when a certain target or targets
4265 is explicitly being built:
4268 if 'foo' in COMMAND_LINE_TARGETS:
4269 print "Don't forget to test the `foo' program!"
4270 if 'special/program' in COMMAND_LINE_TARGETS:
4271 SConscript('special')
4274 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4277 A list of the target
4279 that have been specified using the
4282 The elements of the list are nodes,
4283 so you need to run them through the Python
4285 function to get at the path name for each Node.
4288 print str(DEFAULT_TARGETS[0])
4289 if 'foo' in map(str, DEFAULT_TARGETS):
4290 print "Don't forget to test the `foo' program!"
4295 list change on on each successive call to the
4300 print map(str, DEFAULT_TARGETS) # originally []
4302 print map(str, DEFAULT_TARGETS) # now a node ['foo']
4304 print map(str, DEFAULT_TARGETS) # now a node ['foo', 'bar']
4306 print map(str, DEFAULT_TARGETS) # back to []
4309 Consequently, be sure to use
4311 only after you've made all of your
4314 or else simply be careful of the order
4315 of these statements in your SConscript files
4316 so that you don't look for a specific
4317 default target before it's actually been added to the list.
4319 .SS Construction Variables
4320 .\" XXX From Gary Ruben, 23 April 2002:
4321 .\" I think it would be good to have an example with each construction
4322 .\" variable description in the documentation.
4324 .\" CC The C compiler
4325 .\" Example: env["CC"] = "c68x"
4326 .\" Default: env["CC"] = "cc"
4328 .\" CCCOM The command line ...
4330 .\" To generate the compiler line c68x -ps -qq -mr -o $TARGET $SOURCES
4331 .\" env["CC"] = "c68x"
4332 .\" env["CFLAGS"] = "-ps -qq -mr"
4333 .\" env["CCCOM"] = "$CC $CFLAGS -o $TARGET $SOURCES
4335 .\" (I dunno what this is ;-)
4336 A construction environment has an associated dictionary of
4337 .I construction variables
4338 that are used by built-in or user-supplied build rules.
4339 Construction variables must follow the same rules for
4341 the initial character must be an underscore or letter,
4342 followed by any number of underscores, letters, or digits.
4344 A number of useful construction variables are automatically defined by
4345 scons for each supported platform, and additional construction variables
4346 can be defined by the user. The following is a list of the automatically
4347 defined construction variables:
4349 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4350 '\" BEGIN GENERATED CONSTRUCTION VARIABLE DESCRIPTIONS
4352 '\" The descriptions below of the various SCons contruction variables
4353 '\" are generated from the .xml files that live next to the various
4354 '\" Python modules in the build enginer library. If you're reading
4355 '\" this [gnt]roff file with an eye towards patching this man page,
4356 '\" you can still submit a diff against this text, but it will have to
4357 '\" be translated to a diff against the underlying .xml file before the
4358 '\" patch is actually accepted. If you do that yourself, it will make
4359 '\" it easier to integrate the patch.
4361 '\" BEGIN GENERATED CONSTRUCTION VARIABLE DESCRIPTIONS
4362 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4364 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4365 '\" END GENERATED CONSTRUCTION VARIABLE DESCRIPTIONS
4367 '\" The descriptions above of the various SCons contruction variables
4368 '\" are generated from the .xml files that live next to the various
4369 '\" Python modules in the build enginer library. If you're reading
4370 '\" this [gnt]roff file with an eye towards patching this man page,
4371 '\" you can still submit a diff against this text, but it will have to
4372 '\" be translated to a diff against the underlying .xml file before the
4373 '\" patch is actually accepted. If you do that yourself, it will make
4374 '\" it easier to integrate the patch.
4376 '\" END GENERATED CONSTRUCTION VARIABLE DESCRIPTIONS
4377 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4380 Construction variables can be retrieved and set using the
4382 method of the construction environment:
4385 dict = env.Dictionary()
4389 or using the [] operator:
4395 Construction variables can also be passed to the construction environment
4399 env = Environment(CC="cc")
4402 or when copying a construction environment using the
4407 env2 = env.Copy(CC="cl.exe")
4410 .SS Configure Contexts
4414 .I configure contexts,
4415 an integrated mechanism similar to the
4416 various AC_CHECK macros in GNU autoconf
4417 for testing for the existence of C header
4418 files, libraries, etc.
4419 In contrast to autoconf,
4421 does not maintain an explicit cache of the tested values,
4422 but uses its normal dependency tracking to keep the checked values
4423 up to date. However, users may override this behaviour with the
4425 command line option.
4427 The following methods can be used to perform checks:
4430 .RI Configure( env ", [" custom_tests ", " conf_dir ", " log_file ", " config_h ])
4432 .RI env.Configure([ custom_tests ", " conf_dir ", " log_file ", " config_h ])
4433 This creates a configure context, which can be used to perform checks.
4435 specifies the environment for building the tests.
4436 This environment may be modified when performing checks.
4438 is a dictionary containing custom tests.
4439 See also the section about custom tests below.
4440 By default, no custom tests are added to the configure context.
4442 specifies a directory where the test cases are built.
4443 Note that this directory is not used for building
4445 The default value is the directory
4448 specifies a file which collects the output from commands
4449 that are executed to check for the existence of header files, libraries, etc.
4450 The default is the file #/config.log.
4451 If you are using the
4454 you may want to specify a subdirectory under your build directory.
4456 specifies a C header file where the results of tests
4457 will be written, e.g. #define HAVE_STDIO_H, #define HAVE_LIBM, etc.
4458 The default is to not write a
4461 You can specify the same
4463 file in multiple calls to Configure,
4466 will concatenate all results in the specified file.
4468 uses its normal dependency checking
4469 to decide if it's necessary to rebuild
4473 This means that the file is not necessarily re-built each
4475 but is only rebuilt if its contents will have changed
4476 and some target that depends on the
4478 file is being built.
4483 instance has the following associated methods:
4486 .RI Configure.Finish( self )
4487 This method should be called after configuration is done.
4488 It returns the environment as modified
4489 by the configuration checks performed.
4490 After this method is called, no further checks can be performed
4491 with this configuration context.
4492 However, you can create a new
4494 context to perform additional checks.
4495 Only one context should be active at a time.
4497 The following Checks are predefined.
4498 (This list will likely grow larger as time
4499 goes by and developers contribute new useful tests.)
4502 .RI Configure.CheckHeader( self ", " header ", [" include_quotes ", " language ])
4505 is usable in the specified language.
4508 in which case the last item in the list
4509 is the header file to be checked,
4510 and the previous list items are
4513 lines should precede the
4514 header line being checked for.
4515 The optional argument
4518 a two character string, where the first character denotes the opening
4519 quote and the second character denotes the closing quote.
4520 By default, both characters are " (double quote).
4521 The optional argument
4527 and selects the compiler to be used for the check.
4528 Returns 1 on success and 0 on failure.
4531 .RI Configure.CheckCHeader( self ", " header ", [" include_quotes ])
4532 This is a wrapper around
4533 .B Configure.CheckHeader
4536 is usable in the C language.
4539 in which case the last item in the list
4540 is the header file to be checked,
4541 and the previous list items are
4544 lines should precede the
4545 header line being checked for.
4546 The optional argument
4549 a two character string, where the first character denotes the opening
4550 quote and the second character denotes the closing quote (both default
4552 Returns 1 on success and 0 on failure.
4555 .RI Configure.CheckCXXHeader( self ", " header ", [" include_quotes ])
4556 This is a wrapper around
4557 .B Configure.CheckHeader
4560 is usable in the C++ language.
4563 in which case the last item in the list
4564 is the header file to be checked,
4565 and the previous list items are
4568 lines should precede the
4569 header line being checked for.
4570 The optional argument
4573 a two character string, where the first character denotes the opening
4574 quote and the second character denotes the closing quote (both default
4576 Returns 1 on success and 0 on failure.
4579 .RI Configure.CheckFunc( self ", " function_name ", [" header ", " language ])
4580 Checks if the specified
4581 C or C++ function is available.
4583 is the name of the function to check for.
4586 argument is a string
4590 that will be compiled
4591 to check if the function exists;
4597 char function_name();
4605 and selects the compiler to be used for the check;
4609 .RI Configure.CheckLib( self ", [" library ", " symbol ", " header ", " language ", " autoadd=1 ])
4616 is 1 and the library provides the specified
4618 appends the library to the LIBS construction environment variable.
4620 may also be None (the default),
4623 is checked with the current LIBS variable,
4624 or a list of library names,
4625 in which case each library in the list
4633 .BR Configure.CheckLib ()
4635 you can link against the specified
4643 and selects the compiler to be used for the check;
4645 The default value for
4648 This method returns 1 on success and 0 on error.
4651 .RI Configure.CheckLibWithHeader( self ", " library ", " header ", " language ", [" call ", " autoadd ])
4654 .RI Configure.CheckLib
4655 call, this call provides a more sophisticated way to check against libraries.
4658 specifies the library or a list of libraries to check.
4660 specifies a header to check for.
4663 in which case the last item in the list
4664 is the header file to be checked,
4665 and the previous list items are
4668 lines should precede the
4669 header line being checked for.
4671 may be one of 'C','c','CXX','cxx','C++' and 'c++'.
4673 can be any valid expression (with a trailing ';').
4677 the default simply checks that you
4678 can link against the specified
4681 specifies whether to add the library to the environment (only if the check
4682 succeeds). This method returns 1 on success and 0 on error.
4685 .RI Configure.CheckType( self ", " type_name ", [" includes ", " language ])
4686 Checks for the existence of a type defined by
4689 specifies the typedef name to check for.
4691 is a string containing one or more
4693 lines that will be inserted into the program
4694 that will be run to test for the existence of the type.
4701 and selects the compiler to be used for the check;
4705 Example of a typical Configure usage:
4709 conf = Configure( env )
4710 if not conf.CheckCHeader( 'math.h' ):
4711 print 'We really need math.h!'
4713 if conf.CheckLibWithHeader( 'qt', 'qapp.h', 'c++', 'QApplication qapp(0,0);' ):
4714 # do stuff for qt - usage, e.g.
4715 conf.env.Append( CPPFLAGS = '-DWITH_QT' )
4720 You can define your own custom checks.
4721 in addition to the predefined checks.
4722 These are passed in a dictionary to the Configure function.
4723 This dictionary maps the names of the checks
4724 to user defined Python callables
4725 (either Python functions or class instances implementing the
4728 The first argument of the call is always a
4730 instance followed by the arguments,
4731 which must be supplied by the user of the check.
4732 These CheckContext instances define the following methods:
4735 .RI CheckContext.Message( self ", " text )
4737 Usually called before the check is started.
4739 will be displayed to the user, e.g. 'Checking for library X...'
4742 .RI CheckContext.Result( self, ", " res )
4744 Usually called after the check is done.
4746 can be either an integer or a string. In the former case, 'ok' (res != 0)
4747 or 'failed' (res == 0) is displayed to the user, in the latter case the
4748 given string is displayed.
4751 .RI CheckContext.TryCompile( self ", " text ", " extension )
4752 Checks if a file with the specified
4754 (e.g. '.c') containing
4756 can be compiled using the environment's
4758 builder. Returns 1 on success and 0 on failure.
4761 .RI CheckContext.TryLink( self ", " text ", " extension )
4762 Checks, if a file with the specified
4764 (e.g. '.c') containing
4766 can be compiled using the environment's
4768 builder. Returns 1 on success and 0 on failure.
4771 .RI CheckContext.TryRun( self ", " text ", " extension )
4772 Checks, if a file with the specified
4774 (e.g. '.c') containing
4776 can be compiled using the environment's
4778 builder. On success, the program is run. If the program
4779 executes successfully
4780 (that is, its return status is 0),
4785 is the standard output of the
4787 If the program fails execution
4788 (its return status is non-zero),
4789 then (0, '') is returned.
4792 .RI CheckContext.TryAction( self ", " action ", [" text ", " extension ])
4793 Checks if the specified
4795 with an optional source file (contents
4802 may be anything which can be converted to a
4809 is the content of the target file.
4815 .RI CheckContext.TryBuild( self ", " builder ", [" text ", " extension ])
4816 Low level implementation for testing specific builds;
4817 the methods above are based on this method.
4818 Given the Builder instance
4822 of a source file with optional
4824 this method returns 1 on success and 0 on failure. In addition,
4826 is set to the build target node, if the build was successful.
4829 Example for implementing and using custom tests:
4832 def CheckQt(context, qtdir):
4833 context.Message( 'Checking for qt ...' )
4834 lastLIBS = context.env['LIBS']
4835 lastLIBPATH = context.env['LIBPATH']
4836 lastCPPPATH= context.env['CPPPATH']
4837 context.env.Append(LIBS = 'qt', LIBPATH = qtdir + '/lib', CPPPATH = qtdir + '/include' )
4838 ret = context.TryLink("""
4840 int main(int argc, char **argv) {
4841 QApplication qapp(argc, argv);
4846 context.env.Replace(LIBS = lastLIBS, LIBPATH=lastLIBPATH, CPPPATH=lastCPPPATH)
4847 context.Result( ret )
4851 conf = Configure( env, custom_tests = { 'CheckQt' : CheckQt } )
4852 if not conf.CheckQt('/usr/lib/qt'):
4853 print 'We really need qt!'
4858 .SS Construction Variable Options
4860 Often when building software, various options need to be specified at build
4861 time that are not known when the SConstruct/SConscript files are
4862 written. For example, libraries needed for the build may be in non-standard
4863 locations, or site-specific compiler options may need to be passed to the
4866 provides a mechanism for overridding construction variables from the
4867 command line or a text-based SConscript file through an Options
4868 object. To create an Options object, call the Options() function:
4871 .RI Options([ files "], [" args ])
4872 This creates an Options object that will read construction variables from
4873 the file or list of filenames specified in
4875 If no files are specified,
4880 then no files will be read.
4881 The optional argument
4884 values that will override anything read from the specified files;
4885 it is primarily intended to be passed the
4887 dictionary that holds variables
4888 specified on the command line.
4892 opts = Options('custom.py')
4893 opts = Options('overrides.py', ARGUMENTS)
4894 opts = Options(None, {FOO:'expansion', BAR:7})
4897 Options objects have the following methods:
4900 .RI Add( key ", [" help ", " default ", " validator ", " converter ])
4901 This adds a customizable construction variable to the Options object.
4903 is the name of the variable.
4905 is the help text for the variable.
4907 is the default value of the variable;
4908 if the default value is
4910 and there is no explicit value specified,
4911 the construction variable will
4913 be added to the construction environment.
4915 is called to validate the value of the variable, and should take three
4916 arguments: key, value, and environment.
4917 The recommended way to handle an invalid value is
4918 to raise an exception (see example below).
4920 is called to convert the value before putting it in the environment, and
4921 should take a single argument: value.
4924 must return a value,
4925 which will be converted into a string
4926 before being validated by the
4929 and then added to the environment.
4934 opts.Add('CC', 'The C compiler')
4936 def validate_color(key, val, env):
4937 if not val in ['red', 'blue', 'yellow']:
4938 raise "Invalid color value '%s'" % val
4939 opts.Add('COLOR', validator=valid_color)
4943 .RI AddOptions( list )
4944 A wrapper script that adds
4945 multiple customizable construction variables
4946 to an Options object.
4948 is a list of tuple or list objects
4949 that contain the arguments
4950 for an individual call to the
4957 ('CC', 'The C compiler'),
4958 ('VALIDATE', 'An option for testing validation',
4959 'notset', validator, None),
4964 .RI Update( env ", [" args ])
4965 This updates a construction environment
4967 with the customized construction variables. Normally this method is not
4968 called directly, but is called indirectly by passing the Options object to
4969 the Environment() function:
4972 env = Environment(options=opts)
4976 The text file(s) that were specified
4977 when the Options object was created
4978 are executed as Python scripts,
4979 and the values of (global) Python variables set in the file
4980 are added to the construction environment.
4988 .RI Save( filename ", " env )
4989 This saves the currently set options into a script file named
4991 that can be used on the next invocation to automatically load the current
4992 settings. This method combined with the Options method can be used to
4993 support caching of options between runs.
4997 opts = Options(['options.cache', 'custom.py'])
5000 opts.Save('options.cache', env)
5004 .RI GenerateHelpText( env ", [" sort ])
5005 This generates help text documenting the customizable construction
5006 variables suitable to passing in to the Help() function.
5008 is the construction environment that will be used to get the actual values
5009 of customizable variables. Calling with
5013 will cause the output to be sorted
5014 by the specified argument.
5018 should take two arguments
5021 (like the standard Python
5026 Help(opts.GenerateHelpText(env))
5027 Help(opts.GenerateHelpText(env, sort=cmp))
5031 .RI FormatOptionHelpText( env ", " opt ", " help ", " default ", " actual )
5032 This method returns a formatted string
5033 containing the printable help text
5035 It is normally not called directly,
5036 but is called by the
5037 .IR GenerateHelpText ()
5038 method to create the returned help text.
5039 It may be overridden with your own
5040 function that takes the arguments specified above
5041 and returns a string of help text formatted to your liking.
5043 .IR GenerateHelpText ()
5044 will not put any blank lines or extra
5045 characters in between the entries,
5046 so you must add those characters to the returned
5047 string if you want the entries separated.
5050 def my_format(env, opt, help, default, actual):
5051 fmt = "\n%s: default=%s actual=%s (%s)\n"
5052 return fmt % (opt, default. actual, help)
5053 opts.FormatOptionHelpText = my_format
5056 To make it more convenient to work with customizable Options,
5058 provides a number of functions
5059 that make it easy to set up
5060 various types of Options:
5063 .RI BoolOption( key ", " help ", " default )
5064 Return a tuple of arguments
5065 to set up a Boolean option.
5069 have a default value of
5071 and display the specified
5074 The option will interpret the values
5096 .RI EnumOption( key ", " help ", " default ", " allowed_values ", [" map ", " ignorecase ])
5097 Return a tuple of arguments
5099 whose value may be one
5100 of a specified list of legal enumerated values.
5104 have a default value of
5106 and display the specified
5109 The option will only support those
5115 argument is a dictionary
5116 that can be used to convert
5117 input values into specific legal values
5126 then the values are case-sensitive.
5131 then values will be matched
5137 then values will be matched
5139 and all input values will be
5140 converted to lower case.
5143 .RI ListOption( key ", " help ", " default ", " names ", [", map ])
5144 Return a tuple of arguments
5146 whose value may be one or more
5147 of a specified list of legal enumerated values.
5151 have a default value of
5153 and display the specified
5156 The option will only support the values
5159 or the values in the
5162 More than one value may be specified,
5163 with all values separated by commas.
5164 The default may be a string of
5165 comma-separated default values,
5166 or a list of the default values.
5169 argument is a dictionary
5170 that can be used to convert
5171 input values into specific legal values
5177 .RI PackageOption( key ", " help ", " default )
5178 Return a tuple of arguments
5180 whose value is a path name
5181 of a package that may be
5182 enabled, disabled or
5183 given an explicit path name.
5187 have a default value of
5189 and display the specified
5192 The option will support the values
5199 in which case the specified
5202 or the option may be set to an
5204 (typically the path name to a package
5205 that is being enabled).
5206 The option will also support the values
5212 to disable use of the specified option.
5215 .RI PathOption( key ", " help ", " default ", [" validator ])
5216 Return a tuple of arguments
5218 whose value is expected to be a path name.
5222 have a default value of
5224 and display the specified
5230 that will be called to
5231 verify that the specified path
5234 following ready-made validators:
5235 .BR PathOption.PathExists
5237 which verifies that the specified path exists;
5238 .BR PathOption.PathIsFile ,
5239 which verifies that the specified path is an existing file;
5240 .BR PathOption.PathIsDir ,
5241 which verifies that the specified path is an existing directory;
5243 .BR PathOption.PathIsDirCreate ,
5244 which verifies that the specified path is a directory,
5245 and will create the specified directory if the path does not exist.
5246 You may supply your own
5249 which must take three arguments
5251 the name of the options variable to be set;
5253 the specified value being checked;
5256 the construction environment)
5257 and should raise an exception
5258 if the specified value is not acceptable.
5261 These functions make it
5262 convenient to create a number
5263 of options with consistent behavior
5264 in a single call to the
5270 BoolOption('warnings', 'compilation with -Wall and similiar', 1),
5271 EnumOption('debug', 'debug output and symbols', 'no'
5272 allowed_values=('yes', 'no', 'full'),
5273 map={}, ignorecase=0), # case sensitive
5274 ListOption('shared',
5275 'libraries to build as shared libraries',
5277 names = list_of_libs),
5278 PackageOption('x11',
5279 'use X11 installed here (yes = search some places)',
5281 PathOption('qtdir', 'where the root of Qt is installed', qtdir),
5282 PathOption('foopath', 'where the foo library is installed', foopath,
5283 PathOption.PathIsDir),
5288 .SS File and Directory Nodes
5298 Nodes, respectively.
5299 python objects, respectively.
5300 Those objects have several user-visible attributes
5301 and methods that are often useful:
5307 This path is relative to the top-level directory
5311 The build path is the same as the source path if
5316 The absolute build path of the given file or directory.
5326 object representing the
5335 # Get the current build dir's path, relative to top.
5337 # Current dir's absolute path
5339 # Next line is always '.', because it is the top dir's path relative to itself.
5341 File('foo.c').srcnode().path # source path of the given source file.
5343 # Builders also return File objects:
5344 foo = env.Program('foo.c')
5345 print "foo will be built in %s"%foo.path
5351 can be extended to build different types of targets
5352 by adding new Builder objects
5353 to a construction environment.
5355 you should only need to add a new Builder object
5356 when you want to build a new type of file or other external target.
5357 If you just want to invoke a different compiler or other tool
5358 to build a Program, Object, Library, or any other
5359 type of output file for which
5361 already has an existing Builder,
5362 it is generally much easier to
5363 use those existing Builders
5364 in a construction environment
5365 that sets the appropriate construction variables
5368 Builder objects are created
5374 function accepts the following arguments:
5377 The command line string used to build the target from the source.
5380 a list of strings representing the command
5381 to be executed and its arguments
5382 (suitable for enclosing white space in an argument),
5384 mapping source file name suffixes to
5385 any combination of command line strings
5386 (if the builder should accept multiple source file extensions),
5389 (see the next section);
5390 or a list of any of the above.
5393 takes three arguments:
5395 - a list of source nodes,
5397 - a list of target nodes,
5399 - the construction environment.
5402 The prefix that will be prepended to the target file name.
5403 This may be specified as a:
5413 - a function or other callable that takes
5414 two arguments (a construction environment and a list of sources)
5415 and returns a prefix,
5420 - specifies a mapping from a specific source suffix (of the first
5421 source specified) to a corresponding target prefix. Both the source
5422 suffix and target prefix specifications may use environment variable
5423 substitution, and the target prefix (the 'value' entries in the
5424 dictionary) may also be a callable object. The default target prefix
5425 may be indicated by a dictionary entry with a key value of None.
5430 b = Builder("build_it < $SOURCE > $TARGET"
5433 def gen_prefix(env, sources):
5434 return "file-" + env['PLATFORM'] + '-'
5435 b = Builder("build_it < $SOURCE > $TARGET",
5436 prefix = gen_prefix)
5438 b = Builder("build_it < $SOURCE > $TARGET",
5439 suffix = { None: "file-",
5440 "$SRC_SFX_A": gen_prefix })
5444 The suffix that will be appended to the target file name.
5445 This may be specified in the same manner as the prefix above.
5446 If the suffix is a string, then
5448 will append a '.' to the beginning of the suffix if it's not already
5449 there. The string returned by callable object (or obtained from the
5450 dictionary) is untouched and must append its own '.' to the beginning
5454 b = Builder("build_it < $SOURCE > $TARGET"
5457 def gen_suffix(env, sources):
5458 return "." + env['PLATFORM'] + "-file"
5459 b = Builder("build_it < $SOURCE > $TARGET",
5460 suffix = gen_suffix)
5462 b = Builder("build_it < $SOURCE > $TARGET",
5463 suffix = { None: ".sfx1",
5464 "$SRC_SFX_A": gen_suffix })
5468 The expected source file name suffix. This may be a string or a list
5472 A Scanner object that
5473 will be invoked to find
5474 implicit dependencies for this target file.
5475 This keyword argument should be used
5476 for Scanner objects that find
5477 implicit dependencies
5478 based only on the target file
5479 and the construction environment,
5482 (See the section "Scanner Objects," below,
5483 for information about creating Scanner objects.)
5486 A Scanner object that
5488 find implicit dependences in
5490 used to build this target file.
5491 This is where you would
5492 specify a scanner to
5495 lines in source files.
5498 Scanner object may be used to
5499 indicate that this Builder
5500 should scan directory trees
5501 for on-disk changes to files
5504 does not know about from other Builder or function calls.
5505 (See the section "Scanner Objects," below,
5506 for information about creating your own Scanner objects.)
5509 A factory function that the Builder will use
5510 to turn any targets specified as strings into SCons Nodes.
5512 SCons assumes that all targets are files.
5513 Other useful target_factory
5516 for when a Builder creates a directory target,
5519 for when a Builder can create either a file
5520 or directory target.
5525 MakeDirectoryBuilder = Builder(action=my_mkdir, target_factory=Dir)
5527 env.Append(BUILDERS = {'MakeDirectory':MakeDirectoryBuilder})
5528 env.MakeDirectory('new_directory', [])
5531 Note that the call to the MakeDirectory Builder
5532 needs to specify an empty source list
5533 to make the string represent the builder's target;
5534 without that, it would assume the argument is the source,
5535 and would try to deduce the target name from it,
5536 which in the absence of an automatically-added prefix or suffix
5537 would lead to a matching target and source name
5538 and a circular dependency.
5541 A factory function that the Builder will use
5542 to turn any sources specified as strings into SCons Nodes.
5544 SCons assumes that all source are files.
5545 Other useful source_factory
5548 for when a Builder uses a directory as a source,
5551 for when a Builder can use files
5552 or directories (or both) as sources.
5557 CollectBuilder = Builder(action=my_mkdir, source_factory=Entry)
5559 env.Append(BUILDERS = {'Collect':CollectBuilder})
5560 env.Collect('archive', ['directory_name', 'file_name'])
5564 A function or list of functions to manipulate the target and source
5565 lists before dependencies are established
5566 and the target(s) are actually built.
5568 can also be a string containing a construction variable to expand
5569 to an emitter function or list of functions,
5570 or a dictionary mapping source file suffixes
5571 to emitter functions.
5572 (Only the suffix of the first source file
5573 is used to select the actual emitter function
5574 from an emitter dictionary.)
5577 takes three arguments:
5579 - a list of source nodes,
5581 - a list of target nodes,
5583 - the construction environment.
5584 An emitter must return a tuple containing two lists,
5585 the list of targets to be built by this builder,
5586 and the list of sources for this builder.
5591 def e(target, source, env):
5592 return (target + ['foo.foo'], source + ['foo.src'])
5594 # Simple association of an emitter function with a Builder.
5595 b = Builder("my_build < $TARGET > $SOURCE",
5598 def e2(target, source, env):
5599 return (target + ['bar.foo'], source + ['bar.src'])
5601 # Simple association of a list of emitter functions with a Builder.
5602 b = Builder("my_build < $TARGET > $SOURCE",
5605 # Calling an emitter function through a construction variable.
5606 env = Environment(MY_EMITTER = e)
5607 b = Builder("my_build < $TARGET > $SOURCE",
5608 emitter = '$MY_EMITTER')
5610 # Calling a list of emitter functions through a construction variable.
5611 env = Environment(EMITTER_LIST = [e, e2])
5612 b = Builder("my_build < $TARGET > $SOURCE",
5613 emitter = '$EMITTER_LIST')
5615 # Associating multiple emitters with different file
5616 # suffixes using a dictionary.
5617 def e_suf1(target, source, env):
5618 return (target + ['another_target_file'], source)
5619 def e_suf2(target, source, env):
5620 return (target, source + ['another_source_file'])
5621 b = Builder("my_build < $TARGET > $SOURCE",
5622 emitter = {'.suf1' : e_suf1,
5627 Specifies whether this builder is allowed to be called multiple times for
5628 the same target file(s). The default is 0, which means the builder
5629 can not be called multiple times for the same target file(s). Calling a
5630 builder multiple times for the same target simply adds additional source
5631 files to the target; it is not allowed to change the environment associated
5632 with the target, specify addition environment overrides, or associate a different
5633 builder with the target.
5636 A construction environment that can be used
5637 to fetch source code using this Builder.
5638 (Note that this environment is
5640 used for normal builds of normal target files,
5641 which use the environment that was
5642 used to call the Builder for the target file.)
5645 A function that returns a list of actions that will be executed to build
5646 the target(s) from the source(s).
5647 The returned action(s) may be
5648 an Action object, or anything that
5649 can be converted into an Action object
5650 (see the next section).
5652 The generator function
5653 takes four arguments:
5655 - a list of source nodes,
5657 - a list of target nodes,
5659 - the construction environment,
5661 - a Boolean value that specifies
5662 whether the generator is being called
5663 for generating a build signature
5664 (as opposed to actually executing the command).
5668 def g(source, target, env, for_signature):
5669 return [["gcc", "-c", "-o"] + target + source]
5671 b = Builder(generator=g)
5679 arguments must not both be used for the same Builder.
5682 Specifies a builder to use when a source file name suffix does not match
5683 any of the suffixes of the builder. Using this argument produces a
5684 multi-stage builder.
5687 Specifies that this builder expects exactly one source file per call. Giving
5688 more than one source files without target files results in implicitely calling
5689 the builder multiple times (once for each source given). Giving multiple
5690 source files together with target files results in a UserError exception.
5698 arguments must not both be used for the same Builder.
5700 .IP source_ext_match
5703 argument is a dictionary,
5704 the default behavior when a builder is passed
5705 multiple source files is to make sure that the
5706 extensions of all the source files match.
5707 If it is legal for this builder to be
5708 called with a list of source files with different extensions,
5709 this check can be suppressed by setting
5713 or some other non-true value.
5718 will use the suffix of the first specified
5719 source file to select the appropriate action from the
5723 In the following example,
5728 from exiting with an error
5729 due to the mismatched suffixes of
5735 b = Builder(action={'.in' : 'build $SOURCES > $TARGET'},
5736 source_ext_match = None)
5738 env = Environment(BUILDERS = {'MyBuild':b})
5739 env.MyBuild('foo.out', ['foo.in', 'foo.extra'])
5743 A construction environment that can be used
5744 to fetch source code using this Builder.
5745 (Note that this environment is
5747 used for normal builds of normal target files,
5748 which use the environment that was
5749 used to call the Builder for the target file.)
5752 b = Builder(action="build < $SOURCE > $TARGET")
5753 env = Environment(BUILDERS = {'MyBuild' : b})
5754 env.MyBuild('foo.out', 'foo.in', my_arg = 'xyzzy')
5758 A directory from which scons
5765 a string or a directory Node,
5766 scons will change to the specified directory.
5769 is not a string or Node
5771 then scons will change to the
5772 target file's directory.
5774 Note that scons will
5776 automatically modify
5778 construction variables like
5782 when using the chdir
5783 keyword argument--that is,
5784 the expanded file names
5785 will still be relative to
5786 the top-level SConstruct directory,
5787 and consequently incorrect
5788 relative to the chdir directory.
5789 Builders created using chdir keyword argument,
5790 will need to use construction variable
5795 to use just the filename portion of the
5799 b = Builder(action="build < ${SOURCE.file} > ${TARGET.file}",
5801 env = Environment(BUILDERS = {'MyBuild' : b})
5802 env.MyBuild('sub/dir/foo.out', 'sub/dir/foo.in')
5806 Python only keeps one current directory
5807 location for all of the threads.
5808 This means that use of the
5816 because individual worker threads spawned
5817 by SCons interfere with each other
5818 when they start changing directory.
5821 Any additional keyword arguments supplied
5822 when a Builder object is created
5823 (that is, when the Builder() function is called)
5824 will be set in the executing construction
5825 environment when the Builder object is called.
5826 The canonical example here would be
5827 to set a construction variable to
5828 the repository of a source code system.
5830 Any additional keyword arguments supplied
5834 will only be associated with the target
5835 created by that particular Builder call
5836 (and any other files built as a
5837 result of the call).
5839 These extra keyword arguments are passed to the
5840 following functions:
5841 command generator functions,
5843 and emitter functions.
5849 function will turn its
5851 keyword argument into an appropriate
5852 internal Action object.
5853 You can also explicity create Action objects
5857 which can then be passed to the
5860 This can be used to configure
5861 an Action object more flexibly,
5862 or it may simply be more efficient
5863 than letting each separate Builder object
5864 create a separate Action
5866 Builder objects need to do the same thing.
5871 returns an appropriate object for the action
5872 represented by the type of the first argument:
5875 If the first argument is already an Action object,
5876 the object is simply returned.
5879 If the first argument is a string,
5880 a command-line Action is returned.
5881 Note that the command line string
5882 may be preceded by an
5885 to suppress printing of the
5886 specified command line,
5890 to ignore the exit status from
5891 the specified command.
5895 Action('$CC -c -o $TARGET $SOURCES')
5897 # Doesn't print the line being executed.
5898 Action('@build $TARGET $SOURCES')
5901 Action('-build $TARGET $SOURCES')
5904 .\" XXX From Gary Ruben, 23 April 2002:
5905 .\" What would be useful is a discussion of how you execute command
5906 .\" shell commands ie. what is the process used to spawn the shell, pass
5907 .\" environment variables to it etc., whether there is one shell per
5908 .\" environment or one per command etc. It might help to look at the Gnu
5909 .\" make documentation to see what they think is important to discuss about
5910 .\" a build system. I'm sure you can do a better job of organising the
5911 .\" documentation than they have :-)
5915 If the first argument is a list,
5916 then a list of Action objects is returned.
5917 An Action object is created as necessary
5918 for each element in the list.
5921 the list is itself a list,
5922 the internal list is the
5923 command and arguments to be executed via
5925 This allows white space to be enclosed
5926 in an argument by defining
5927 a command in a list within a list:
5930 Action([['cc', '-c', '-DWHITE SPACE', '-o', '$TARGET', '$SOURCES']])
5934 If the first argument is a Python function,
5935 a function Action is returned.
5936 The Python function takes three keyword arguments,
5938 (a Node object representing the target file),
5940 (a Node object representing the source file)
5943 (the construction environment
5944 used for building the target file).
5949 arguments may be lists of Node objects if there is
5950 more than one target file or source file.
5951 The actual target and source file name(s) may
5952 be retrieved from their Node objects
5953 via the built-in Python str() function:
5956 target_file_name = str(target)
5957 source_file_names = map(lambda x: str(x), source)
5960 The function should return
5964 to indicate a successful build of the target file(s).
5965 The function may raise an exception
5966 or return a non-zero exit status
5967 to indicate an unsuccessful build.
5970 def build_it(target = None, source = None, env = None):
5971 # build the target from the source
5974 a = Action(build_it)
5977 If the action argument is not one of the above,
5981 The second, optional argument
5982 is used to define the output which is printed
5983 when the Action is actually performed.
5984 In the absence of this parameter, or if it's an
5985 empty string, a default output depending on the type of the action
5986 is used. For example, a command-line action will print
5987 the executed command. The argument is either a python function
5990 In the first case, it's a function that returns
5991 a string to be printed to describe the action being executed.
5992 Like a function to build a file,
5993 this function takes three arguments:
5995 (a Node object representing the target file),
5997 (a Node object representing the source file)
6000 (a construction environment).
6005 arguments may be lists of Node objects if there is
6006 more than one target file or source file.
6008 In the second case, you provide the string itself.
6009 The string typically contains variables, notably
6010 $TARGET(S) and $SOURCE(S), or consists of just a single
6011 variable, which is optionally defined somewhere else.
6012 SCons itself heavily uses the latter variant.
6017 def build_it(target, source, env):
6018 # build the target from the source
6021 def string_it(target, source, env):
6022 return "building '%s' from '%s'" % (target[0], source[0])
6024 # Use a positional argument.
6025 f = Action(build_it, string_it)
6026 s = Action(build_it, "building '$TARGET' from '$SOURCE'")
6028 # Alternatively, use a keyword argument.
6029 f = Action(build_it, strfunction=string_it)
6030 s = Action(build_it, cmdstr="building '$TARGET' from '$SOURCE'")
6032 # You can provide a configurable variable.
6033 l = Action(build_it, '$STRINGIT')
6036 The third, also optional argument
6037 is a list of construction variables
6038 whose values will be included
6039 in the signature of the Action
6040 when deciding whether a target should
6041 be rebuilt because the action changed.
6042 This is necessary whenever you want a target to
6043 be rebuilt when a specific
6044 construction variable changes,
6045 because the underlying Python code for a function
6046 will not change when the value of the construction variable does.
6049 def build_it(target, source, env):
6050 # build the target from the 'XXX' construction variable
6051 open(target[0], 'w').write(env['XXX'])
6054 # Use positional arguments.
6055 a = Action(build_it, '$STRINGIT', ['XXX'])
6057 # Alternatively, use a keyword argument.
6058 a = Action(build_it, varlist=['XXX'])
6067 which specifies that
6068 scons will execute the action
6069 after changing to the specified directory.
6070 If the chdir argument is
6071 a string or a directory Node,
6072 scons will change to the specified directory.
6073 If the chdir argument
6074 is not a string or Node
6076 then scons will change to the
6077 target file's directory.
6079 Note that scons will
6081 automatically modify
6083 construction variables like
6087 when using the chdir
6088 keyword argument--that is,
6089 the expanded file names
6090 will still be relative to
6091 the top-level SConstruct directory,
6092 and consequently incorrect
6093 relative to the chdir directory.
6094 Builders created using chdir keyword argument,
6095 will need to use construction variable
6100 to use just the filename portion of the
6104 a = Action("build < ${SOURCE.file} > ${TARGET.file}",
6114 which specifies a function
6115 that is passed the exit status
6117 from the specified action
6118 and can return an arbitrary
6120 This can be used, for example,
6121 to specify that an Action object's
6122 return value should be ignored
6123 and SCons should, therefore,
6124 consider that the action always suceeds:
6127 def always_succeed(s):
6128 # Always return 0, which indicates success.
6130 a = Action("build < ${SOURCE.file} > ${TARGET.file}",
6131 exitstatfunc=always_succeed)
6134 .SS Miscellaneous Action Functions
6137 supplies a number of functions
6138 that arrange for various common
6139 file and directory manipulations
6141 These are similar in concept to "tasks" in the
6143 although the implementation is slightly different.
6144 These functions do not actually
6145 perform the specified action
6146 at the time the function is called,
6147 but instead return an Action object
6148 that can be executed at the
6150 (In Object-Oriented terminology,
6155 that return Action objects.)
6158 there are two natural ways
6161 are intended to be used.
6165 to perform the action
6166 at the time the SConscript
6170 global function to do so:
6172 Execute(Touch('file'))
6176 you can use these functions
6177 to supply Actions in a list
6181 This can allow you to
6182 perform more complicated
6183 sequences of file manipulation
6185 on platform-specific
6189 env = Environment(TMPBUILD = '/tmp/builddir')
6190 env.Command('foo.out', 'foo.in',
6191 [Mkdir('$TMPBUILD'),
6192 Copy('$TMPBUILD', '${SOURCE.dir}'),
6193 "cd $TMPBUILD && make",
6194 Delete('$TMPBUILD')])
6198 .RI Chmod( dest ", " mode )
6199 Returns an Action object that
6200 changes the permissions on the specified
6202 file or directory to the specified
6207 Execute(Chmod('file', 0755))
6209 env.Command('foo.out', 'foo.in',
6210 [Copy('$TARGET', '$SOURCE'),
6211 Chmod('$TARGET', 0755)])
6215 .RI Copy( dest ", " src )
6216 Returns an Action object
6219 source file or directory to the
6221 destination file or directory.
6225 Execute(Copy('foo.output', 'foo.input'))
6227 env.Command('bar.out', 'bar.in',
6228 Copy('$TARGET', '$SOURCE'))
6232 .RI Delete( entry ", [" must_exist ])
6233 Returns an Action that
6234 deletes the specified
6236 which may be a file or a directory tree.
6237 If a directory is specified,
6238 the entire directory tree
6243 then a Python error will be thrown
6244 if the specified entry does not exist;
6247 that is, the Action will silently do nothing
6248 if the entry does not exist.
6252 Execute(Delete('/tmp/buildroot'))
6254 env.Command('foo.out', 'foo.in',
6255 [Delete('${TARGET.dir}'),
6258 Execute(Delete('file_that_must_exist', must_exist=1))
6264 that creates the specified
6270 Execute(Mkdir('/tmp/outputdir'))
6272 env.Command('foo.out', 'foo.in',
6273 [Mkdir('/tmp/builddir',
6274 Copy('$SOURCE', '/tmp/builddir')
6275 "cd /tmp/builddir && ])
6280 .RI Move( dest ", " src )
6282 that moves the specified
6284 file or directory to
6291 Execute(Move('file.destination', 'file.source'))
6293 env.Command('output_file', 'input_file',
6295 Move('$TARGET', 'file_created_by_MyBuildAction')])
6301 that updates the modification time
6307 Execute(Touch('file_to_be_touched'))
6309 env.Command('marker', 'input_file',
6314 .SS Variable Substitution
6316 Before executing a command,
6318 performs construction variable interpolation on the strings that make up
6319 the command line of builders.
6320 Variables are introduced by a
6323 Besides construction variables, scons provides the following
6324 variables for each command execution:
6327 The file name of the target being built, or the file name of the first
6328 target if multiple targets are being built.
6331 The file names of all targets being built.
6334 The file name of the source of the build command, or the file name of the
6335 first source if multiple sources are being built.
6338 The file names of the sources of the build command.
6340 (Note that the above variables are reserved
6341 and may not be set in a construction environment.)
6344 For example, given the construction variable CC='cc', targets=['foo'], and
6345 sources=['foo.c', 'bar.c']:
6348 action='$CC -c -o $TARGET $SOURCES'
6351 would produce the command line:
6354 cc -c -o foo foo.c bar.c
6357 Variable names may be surrounded by curly braces ({})
6358 to separate the name from the trailing characters.
6359 Within the curly braces, a variable name may have
6360 a Python slice subscript appended to select one
6361 or more items from a list.
6362 In the previous example, the string:
6374 Additionally, a variable name may
6375 have the following special
6376 modifiers appended within the enclosing curly braces
6377 to modify the interpolated string:
6380 The base path of the file name,
6381 including the directory path
6382 but excluding any suffix.
6385 The name of the directory in which the file exists.
6389 minus any directory portion.
6392 Just the basename of the file,
6394 and minus the directory.
6397 Just the file suffix.
6400 The absolute path name of the file.
6403 The POSIX form of the path,
6404 with directories separated by
6408 This is sometimes necessary on Windows systems
6409 when a path references a file on other (POSIX) systems.
6412 The directory and file name to the source file linked to this file
6413 through BuildDir. If this file isn't linked, it just returns the
6414 directory and filename unchanged.
6417 The directory containing the source file linked to this file
6418 through BuildDir. If this file isn't linked, it just returns the
6419 directory part of the filename.
6422 The directory and file name to the source file linked to this file
6423 through BuildDir. If the file does not exist locally but exists in
6424 a Repository, the path in the Repository is returned.
6425 If this file isn't linked, it just returns the
6426 directory and filename unchanged.
6429 The Repository directory containing the source file linked to this file
6430 through BuildDir. If this file isn't linked, it just returns the
6431 directory part of the filename.
6434 For example, the specified target will
6435 expand as follows for the corresponding modifiers:
6438 $TARGET => sub/dir/file.x
6439 ${TARGET.base} => sub/dir/file
6440 ${TARGET.dir} => sub/dir
6441 ${TARGET.file} => file.x
6442 ${TARGET.filebase} => file
6443 ${TARGET.suffix} => .x
6444 ${TARGET.abspath} => /top/dir/sub/dir/file.x
6446 SConscript('src/SConscript', build_dir='sub/dir')
6447 $SOURCE => sub/dir/file.x
6448 ${SOURCE.srcpath} => src/file.x
6449 ${SOURCE.srcdir} => src
6451 Repository('/usr/repository')
6452 $SOURCE => sub/dir/file.x
6453 ${SOURCE.rsrcpath} => /usr/repository/src/file.x
6454 ${SOURCE.rsrcdir} => /usr/repository/src
6457 Lastly, a variable name
6458 may be a callable Python function
6460 construction variable in the environment.
6462 take four arguments:
6464 - a list of target nodes,
6466 - a list of source nodes,
6468 - the construction environment,
6470 - a Boolean value that specifies
6471 whether the function is being called
6472 for generating a build signature.
6473 SCons will insert whatever
6474 the called function returns
6475 into the expanded string:
6478 def foo(target, source, env, for_signature):
6481 # Will expand $BAR to "bar baz"
6482 env=Environment(FOO=foo, BAR="$FOO baz")
6485 You can use this feature to pass arguments to a
6486 Python function by creating a callable class
6487 that stores one or more arguments in an object,
6488 and then uses them when the
6491 Note that in this case,
6492 the entire variable expansion must
6493 be enclosed by curly braces
6494 so that the arguments will
6495 be associated with the
6496 instantiation of the class:
6500 def __init__(self, arg):
6503 def __call__(self, target, source, env, for_signature):
6506 # Will expand $BAR to "my argument bar baz"
6507 env=Environment(FOO=foo, BAR="${FOO('my argument')} baz")
6511 The special pseudo-variables
6515 may be used to surround parts of a command line
6518 causing a rebuild--that is,
6519 which are not included in the signature
6520 of target files built with this command.
6525 will be removed from the command line
6526 before it is added to file signatures,
6531 will be removed before the command is executed.
6532 For example, the command line:
6535 echo Last build occurred $( $TODAY $). > $TARGET
6539 would execute the command:
6542 echo Last build occurred $TODAY. > $TARGET
6546 but the command signature added to any target files would be:
6549 echo Last build occurred . > $TARGET
6552 SCons uses the following rules when converting construction variables into
6556 When the value is a string it is interpreted as a space delimited list of
6557 command line arguments.
6560 When the value is a list it is interpreted as a list of command line
6561 arguments. Each element of the list is converted to a string.
6564 Anything that is not a list or string is converted to a string and
6565 interpreted as a single command line argument.
6568 Newline characters (\\n) delimit lines. The newline parsing is done after
6569 all other parsing, so it is not possible for arguments (e.g. file names) to
6570 contain embedded newline characters. This limitation will likely go away in
6571 a future version of SCons.
6579 new file types for implicit dependencies.
6580 Scanner accepts the following arguments:
6583 A Python function that will process
6585 and return a list of strings (file names)
6586 representing the implicit
6587 dependencies found in the contents.
6588 The function takes three or four arguments:
6590 def scanner_function(node, env, path):
6592 def scanner_function(node, env, path, arg):
6596 argument is the internal
6597 SCons node representing the file.
6600 to fetch the name of the file, and
6601 .B node.get_contents()
6602 to fetch contents of the file.
6603 Note that the file is
6605 guaranteed to exist before the scanner is called,
6606 so the scanner function should check that
6607 if there's any chance that the scanned file
6609 (for example, if it's built from other files).
6613 argument is the construction environment for the scan.
6614 Fetch values from it using the
6620 argument is a tuple (or list)
6621 of directories that can be searched
6623 This will usually be the tuple returned by the
6625 argument (see below).
6629 argument is the argument supplied
6630 when the scanner was created, if any.
6633 The name of the Scanner.
6635 to identify the Scanner internally.
6638 An optional argument that, if specified,
6639 will be passed to the scanner function
6641 and the path function
6645 An optional list that can be used to
6646 determine which scanner should be used for
6648 In the usual case of scanning for file names,
6649 this argument will be a list of suffixes
6650 for the different file types that this
6651 Scanner knows how to scan.
6652 If the argument is a string,
6653 then it will be expanded
6654 into a list by the current environment.
6657 A Python function that takes four or five arguments:
6658 a construction environment,
6659 a Node for the directory containing
6660 the SConscript file in which
6661 the first target was defined,
6662 a list of target nodes,
6663 a list of source nodes,
6664 and an optional argument supplied
6665 when the scanner was created.
6668 returns a tuple of directories
6669 that can be searched for files to be returned
6670 by this Scanner object.
6673 The class of Node that should be returned
6674 by this Scanner object.
6675 Any strings or other objects returned
6676 by the scanner function
6677 that are not of this class
6678 will be run through the
6683 A Python function that will take a string
6685 and turn it into the appropriate class of Node
6686 to be returned by this Scanner object.
6689 An optional Python function that takes two arguments,
6690 a Node (file) and a construction environment,
6691 and returns whether the
6692 Node should, in fact,
6693 be scanned for dependencies.
6694 This check can be used to eliminate unnecessary
6695 calls to the scanner function when,
6696 for example, the underlying file
6697 represented by a Node does not yet exist.
6700 An optional flag that
6701 specifies whether this scanner should be re-invoked
6702 on the dependency files returned by the scanner.
6703 When this flag is not set,
6704 the Node subsystem will
6705 only invoke the scanner on the file being scanned,
6706 and not (for example) also on the files
6707 specified by the #include lines
6708 in the file being scanned.
6710 may be a callable function,
6711 in which case it will be called with a list of
6713 should return a list of Nodes
6714 that should be scanned recursively;
6715 this can be used to select a specific subset of
6716 Nodes for additional scanning.
6721 .B SourceFileScanner
6722 object that is used by
6725 .BR SharedObject (),
6729 which scanner should be used
6730 for different file extensions.
6732 .BR SourceFileScanner.add_scanner ()
6733 method to add your own Scanner object
6737 that builds target programs or
6738 libraries from a list of
6739 source files of different types:
6742 def xyz_scan(node, env, path):
6743 contents = node.get_contents()
6744 # Scan the contents and return the included files.
6746 XYZScanner = Scanner(xyz_scan)
6748 SourceFileScanner.add_scanner('.xyx', XYZScanner)
6750 env.Program('my_prog', ['file1.c', 'file2.f', 'file3.xyz'])
6753 .SH SYSTEM-SPECIFIC BEHAVIOR
6754 SCons and its configuration files are very portable,
6755 due largely to its implementation in Python.
6756 There are, however, a few portability
6757 issues waiting to trap the unwary.
6759 SCons handles the upper-case
6761 file suffix differently,
6762 depending on the capabilities of
6763 the underlying system.
6764 On a case-sensitive system
6765 such as Linux or UNIX,
6766 SCons treats a file with a
6768 suffix as a C++ source file.
6769 On a case-insensitive system
6771 SCons treats a file with a
6773 suffix as a C source file.
6775 SCons handles the upper-case
6777 file suffix differently,
6778 depending on the capabilities of
6779 the underlying system.
6780 On a case-sensitive system
6781 such as Linux or UNIX,
6782 SCons treats a file with a
6784 suffix as a Fortran source file
6785 that is to be first run through
6786 the standard C preprocessor.
6787 On a case-insensitive system
6789 SCons treats a file with a
6791 suffix as a Fortran source file that should
6793 be run through the C preprocessor.
6794 .SS Windows: Cygwin Tools and Cygwin Python vs. Windows Pythons
6795 Cygwin supplies a set of tools and utilities
6796 that let users work on a
6797 Windows system using a more POSIX-like environment.
6798 The Cygwin tools, including Cygwin Python,
6800 by sharing an ability to interpret UNIX-like path names.
6801 For example, the Cygwin tools
6802 will internally translate a Cygwin path name
6803 like /cygdrive/c/mydir
6804 to an equivalent Windows pathname
6805 of C:/mydir (equivalent to C:\\mydir).
6808 that are built for native Windows execution,
6809 such as the python.org and ActiveState versions,
6810 do not have the Cygwin path name semantics.
6811 This means that using a native Windows version of Python
6812 to build compiled programs using Cygwin tools
6813 (such as gcc, bison, and flex)
6814 may yield unpredictable results.
6815 "Mixing and matching" in this way
6816 can be made to work,
6817 but it requires careful attention to the use of path names
6818 in your SConscript files.
6820 In practice, users can sidestep
6821 the issue by adopting the following rules:
6823 use the Cygwin-supplied Python interpreter
6825 when using Microsoft Visual C/C++
6826 (or some other Windows compiler)
6827 use the python.org or ActiveState version of Python
6829 .SS Windows: scons.bat file
6831 SCons is executed via a wrapper
6834 This has (at least) two ramifications:
6836 First, Windows command-line users
6837 that want to use variable assignment
6839 may have to put double quotes
6840 around the assignments:
6843 scons "FOO=BAR" "BAZ=BLEH"
6846 Second, the Cygwin shell does not
6847 recognize this file as being the same
6850 command issued at the command-line prompt.
6851 You can work around this either by
6854 from the Cygwin command line,
6855 or by creating a wrapper shell
6861 The MinGW bin directory must be in your PATH environment variable or the
6862 PATH variable under the ENV construction variable for SCons
6863 to detect and use the MinGW tools. When running under the native Windows
6864 Python interpreter, SCons will prefer the MinGW tools over the Cygwin
6865 tools, if they are both installed, regardless of the order of the bin
6866 directories in the PATH variable. If you have both MSVC and MinGW
6867 installed and you want to use MinGW instead of MSVC,
6868 then you must explictly tell SCons to use MinGW by passing
6874 to the Environment() function, because SCons will prefer the MSVC tools
6875 over the MinGW tools.
6879 To help you get started using SCons,
6880 this section contains a brief overview of some common tasks.
6882 .SS Basic Compilation From a Single Source File
6886 env.Program(target = 'foo', source = 'foo.c')
6889 Note: Build the file by specifying
6890 the target as an argument
6891 ("scons foo" or "scons foo.exe").
6892 or by specifying a dot ("scons .").
6894 .SS Basic Compilation From Multiple Source Files
6898 env.Program(target = 'foo', source = Split('f1.c f2.c f3.c'))
6901 .SS Setting a Compilation Flag
6904 env = Environment(CCFLAGS = '-g')
6905 env.Program(target = 'foo', source = 'foo.c')
6908 .SS Search The Local Directory For .h Files
6912 need to set CCFLAGS to specify -I options by hand.
6913 SCons will construct the right -I options from CPPPATH.
6916 env = Environment(CPPPATH = ['.'])
6917 env.Program(target = 'foo', source = 'foo.c')
6920 .SS Search Multiple Directories For .h Files
6923 env = Environment(CPPPATH = ['include1', 'include2'])
6924 env.Program(target = 'foo', source = 'foo.c')
6927 .SS Building a Static Library
6931 env.StaticLibrary(target = 'foo', source = Split('l1.c l2.c'))
6932 env.StaticLibrary(target = 'bar', source = ['l3.c', 'l4.c'])
6935 .SS Building a Shared Library
6939 env.SharedLibrary(target = 'foo', source = ['l5.c', 'l6.c'])
6940 env.SharedLibrary(target = 'bar', source = Split('l7.c l8.c'))
6943 .SS Linking a Local Library Into a Program
6946 env = Environment(LIBS = 'mylib', LIBPATH = ['.'])
6947 env.Library(target = 'mylib', source = Split('l1.c l2.c'))
6948 env.Program(target = 'prog', source = ['p1.c', 'p2.c'])
6951 .SS Defining Your Own Builder Object
6953 Notice that when you invoke the Builder,
6954 you can leave off the target file suffix,
6955 and SCons will add it automatically.
6958 bld = Builder(action = 'pdftex < $SOURCES > $TARGET'
6960 src_suffix = '.tex')
6961 env = Environment(BUILDERS = {'PDFBuilder' : bld})
6962 env.PDFBuilder(target = 'foo.pdf', source = 'foo.tex')
6964 # The following creates "bar.pdf" from "bar.tex"
6965 env.PDFBuilder(target = 'bar', source = 'bar')
6968 Note also that the above initialization
6969 overwrites the default Builder objects,
6970 so the Environment created above
6971 can not be used call Builders like env.Program(),
6972 env.Object(), env.StaticLibrary(), etc.
6974 .SS Adding Your Own Builder Object to an Environment
6977 bld = Builder(action = 'pdftex < $SOURCES > $TARGET'
6979 src_suffix = '.tex')
6981 env.Append(BUILDERS = {'PDFBuilder' : bld})
6982 env.PDFBuilder(target = 'foo.pdf', source = 'foo.tex')
6983 env.Program(target = 'bar', source = 'bar.c')
6986 You also can use other Pythonic techniques to add
6987 to the BUILDERS construction variable, such as:
6991 env['BUILDERS]['PDFBuilder'] = bld
6994 .SS Defining Your Own Scanner Object
6999 '\" Note: the \\ in the following are for the benefit of nroff/troff,
7000 '\" not inappropriate doubled escape characters within the r'' raw string.
7001 include_re = re.compile(r'^include\\s+(\\S+)$', re.M)
7003 def kfile_scan(node, env, path, arg):
7004 contents = node.get_contents()
7005 includes = include_re.findall(contents)
7008 kscan = Scanner(name = 'kfile',
7009 function = kfile_scan,
7012 scanners = Environment().Dictionary('SCANNERS')
7013 env = Environment(SCANNERS = scanners + [kscan])
7015 env.Command('foo', 'foo.k', 'kprocess < $SOURCES > $TARGET')
7017 bar_in = File('bar.in')
7018 env.Command('bar', bar_in, 'kprocess $SOURCES > $TARGET')
7019 bar_in.target_scanner = kscan
7022 .SS Creating a Hierarchical Build
7024 Notice that the file names specified in a subdirectory's
7026 file are relative to that subdirectory.
7032 env.Program(target = 'foo', source = 'foo.c')
7034 SConscript('sub/SConscript')
7039 # Builds sub/foo from sub/foo.c
7040 env.Program(target = 'foo', source = 'foo.c')
7042 SConscript('dir/SConscript')
7047 # Builds sub/dir/foo from sub/dir/foo.c
7048 env.Program(target = 'foo', source = 'foo.c')
7051 .SS Sharing Variables Between SConscript Files
7053 You must explicitly Export() and Import() variables that
7054 you want to share between SConscript files.
7060 env.Program(target = 'foo', source = 'foo.c')
7063 SConscript('subdirectory/SConscript')
7065 subdirectory/SConscript:
7068 env.Program(target = 'foo', source = 'foo.c')
7071 .SS Building Multiple Variants From the Same Source
7073 Use the build_dir keyword argument to
7074 the SConscript function to establish
7075 one or more separate build directories for
7076 a given source directory:
7081 cppdefines = ['FOO']
7082 Export("cppdefines")
7083 SConscript('src/SConscript', build_dir='foo')
7085 cppdefines = ['BAR']
7086 Export("cppdefines")
7087 SConscript('src/SConscript', build_dir='bar')
7091 Import("cppdefines")
7092 env = Environment(CPPDEFINES = cppdefines)
7093 env.Program(target = 'src', source = 'src.c')
7096 Note the use of the Export() method
7097 to set the "cppdefines" variable to a different
7098 value each time we call the SConscript function.
7100 .SS Hierarchical Build of Two Libraries Linked With a Program
7105 env = Environment(LIBPATH = ['#libA', '#libB'])
7107 SConscript('libA/SConscript')
7108 SConscript('libB/SConscript')
7109 SConscript('Main/SConscript')
7114 env.Library('a', Split('a1.c a2.c a3.c'))
7119 env.Library('b', Split('b1.c b2.c b3.c'))
7124 e = env.Copy(LIBS = ['a', 'b'])
7125 e.Program('foo', Split('m1.c m2.c m3.c'))
7128 The '#' in the LIBPATH directories specify that they're relative to the
7129 top-level directory, so they don't turn into "Main/libA" when they're
7130 used in Main/SConscript.
7132 Specifying only 'a' and 'b' for the library names
7133 allows SCons to append the appropriate library
7134 prefix and suffix for the current platform
7135 (for example, 'liba.a' on POSIX systems,
7136 'a.lib' on Windows).
7138 .SS Customizing contruction variables from the command line.
7140 The following would allow the C compiler to be specified on the command
7141 line or in the file custom.py.
7144 opts = Options('custom.py')
7145 opts.Add('CC', 'The C compiler.')
7146 env = Environment(options=opts)
7147 Help(opts.GenerateHelpText(env))
7150 The user could specify the C compiler on the command line:
7156 or in the custom.py file:
7162 or get documentation on the options:
7173 .SS Using Microsoft Visual C++ precompiled headers
7175 Since windows.h includes everything and the kitchen sink, it can take quite
7176 some time to compile it over and over again for a bunch of object files, so
7177 Microsoft provides a mechanism to compile a set of headers once and then
7178 include the previously compiled headers in any object file. This
7179 technology is called precompiled headers. The general recipe is to create a
7180 file named "StdAfx.cpp" that includes a single header named "StdAfx.h", and
7181 then include every header you want to precompile in "StdAfx.h", and finally
7182 include "StdAfx.h" as the first header in all the source files you are
7183 compiling to object files. For example:
7187 #include <windows.h>
7188 #include <my_big_header.h>
7207 /* do some other stuff */
7213 env['PCHSTOP'] = 'StdAfx.h'
7214 env['PCH'] = env.PCH('StdAfx.cpp')[0]
7215 env.Program('MyApp', ['Foo.cpp', 'Bar.cpp'])
7218 For more information see the document for the PCH builder, and the PCH and
7219 PCHSTOP construction variables. To learn about the details of precompiled
7220 headers consult the MSDN documention for /Yc, /Yu, and /Yp.
7222 .SS Using Microsoft Visual C++ external debugging information
7224 Since including debugging information in programs and shared libraries can
7225 cause their size to increase significantly, Microsoft provides a mechanism
7226 for including the debugging information in an external file called a PDB
7227 file. SCons supports PDB files through the PDB construction
7233 env['PDB'] = 'MyApp.pdb'
7234 env.Program('MyApp', ['Foo.cpp', 'Bar.cpp'])
7237 For more information see the document for the PDB construction variable.
7242 Specifies the directory that contains the SCons Python module directory
7243 (e.g. /home/aroach/scons-src-0.01/src/engine).
7246 A string of options that will be used by scons in addition to those passed
7247 on the command line.
7258 Steven Knight <knight@baldmt.com>
7260 Anthony Roach <aroach@electriceyeball.com>