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 --cache-disable, --no-cache
425 Disable the derived-file caching specified by
428 will neither retrieve files from the cache
429 nor copy files to the cache.
432 --cache-force, --cache-populate
435 populate a cache by copying any already-existing, up-to-date
436 derived files to the cache,
437 in addition to files built by this invocation.
438 This is useful to populate a new cache with
439 all the current derived files,
440 or to add to the cache any derived files
441 recently built with caching disabled via the
449 and retrieving a derived file from the cache,
451 that would have been executed to build the file,
452 instead of the usual report,
453 "Retrieved `file' from cache."
454 This will produce consistent output for build logs,
455 regardless of whether a target
456 file was rebuilt or retrieved from the cache.
460 This specifies how the
462 call should use or generate the
463 results of configuration tests.
464 The option should be specified from
465 among the following choices:
469 scons will use its normal dependency mechanisms
470 to decide if a test must be rebuilt or not.
471 This saves time by not running the same configuration tests
472 every time you invoke scons,
473 but will overlook changes in system header files
474 or external commands (such as compilers)
475 if you don't specify those dependecies explicitly.
476 This is the default behavior.
480 If this option is specified,
481 all configuration tests will be re-run
482 regardless of whether the
483 cached results are out of date.
484 This can be used to explicitly
485 force the configuration tests to be updated
486 in response to an otherwise unconfigured change
487 in a system header file or compiler.
491 If this option is specified,
492 no configuration tests will be rerun
493 and all results will be taken from cache.
494 Note that scons will still consider it an error
495 if --config=cache is specified
496 and a necessary test does not
497 yet have any results in the cache.
500 .RI "-C" " directory" ", --directory=" directory
501 Change to the specified
503 before searching for the
508 file, or doing anything
511 options are interpreted
512 relative to the previous one, and the right-most
514 option wins. (This option is nearly
516 .BR "-f directory/SConstruct" ,
517 except that it will search for
522 in the specified directory.)
526 .\" Display dependencies while building target files. Useful for
527 .\" figuring out why a specific file is being rebuilt, as well as
528 .\" general debugging of the build process.
532 Works exactly the same way as the
534 option except for the way default targets are handled.
535 When this option is used and no targets are specified on the command line,
536 all default targets are built, whether or not they are below the current
541 Debug the build process.
543 specifies what type of debugging:
547 Print how many objects are created
548 of the various classes used internally by SCons
549 before and after reading the SConscript files
550 and before and after building targets.
551 This only works when run under Python 2.1 or later.
555 Print the dependency tree
556 after each top-level target is built. This prints out only derived files.
560 Print an explanation of precisely why
562 is deciding to (re-)build any targets.
563 (Note: this does not print anything
570 Instruct the scanner that searches for libraries
571 to print a message about each potential library
572 name it is searching for,
573 and about the actual libraries it finds.
577 Print the include tree after each top-level target is built.
578 This is generally used to find out what files are included by the sources
579 of a given derived file:
582 $ scons --debug=includes foo.o
587 Prints a summary of hits and misses in the Memoizer,
588 the internal SCons subsystem for caching
589 various values in memory instead of
590 recomputing them each time they're needed.
594 Prints how much memory SCons uses
595 before and after reading the SConscript files
596 and before and after building targets.
600 Disables use of the Memoizer,
601 the internal SCons subsystem for caching
602 various values in memory instead of
603 recomputing them each time they're needed.
604 This provides more accurate counts of the
605 underlying function calls in the
606 Python profiler output when using the
609 (When the Memoizer is used,
610 the profiler counts all
611 memoized functions as being executed
612 by the Memoizer's wrapper calls.)
616 Prints a list of the various objects
617 of the various classes used internally by SCons.
618 This only works when run under Python 2.1 or later.
622 Re-run SCons under the control of the
628 Print the raw command line used to build each target
629 before the construction environment variables are substituted.
630 Also shows which targets are being built by this command.
631 Output looks something like this:
633 $ scons --debug=presub
634 Building myprog.o with action(s):
635 $SHCC $SHCCFLAGS $CPPFLAGS $_CPPINCFLAGS -c -o $TARGET $SOURCES
641 Prints an internal Python stack trace
642 when encountering an otherwise unexplained error.
646 Print the dependency tree along with status information. This is the
647 same as the debug=tree option, but additional status information is
648 provided for each node in the tree.
652 Prints various time profiling information: the time spent
653 executing each build command, the total build time, the total time spent
654 executing build commands, the total time spent executing SConstruct and
655 SConscript files, and the total time spent executing SCons itself.
659 Print the dependency tree
660 after each top-level target is built. This prints out the complete
661 dependency tree including implicit dependencies and ignored
665 .RI --diskcheck= types
666 Enable specific checks for
667 whether or not there is a file on disk
668 where the SCons configuration expects a directory
670 and whether or not RCS or SCCS sources exist
671 when searching for source and include files.
674 argument can be set to:
676 to enable all checks explicitly
677 (the default behavior);
679 to disable all such checks;
681 to check that files and directories on disk
682 match SCons' expected configuration;
684 to check for the existence of an RCS source
685 for any missing source or include files;
687 to check for the existence of an SCCS source
688 for any missing source or include files.
689 Multiple checks can be specified separated by commas;
691 .B --diskcheck=sccs,rcs
692 would still check for SCCS and RCS sources,
693 but disable the check for on-disk matches of files and directories.
694 Disabling some or all of these checks
695 can provide a performance boost for large configurations,
696 or when the configuration will check for files and/or directories
697 across networked or shared file systems,
698 at the slight increased risk of an incorrect build
699 or of not handling errors gracefully
700 (if include files really should be
701 found in SCCS or RCS, for example,
702 or if a file really does exist
703 where the SCons configuration expects a directory).
706 .\" -e, --environment-overrides
707 .\" Variables from the execution environment override construction
708 .\" variables from the SConscript files.
711 .RI -f " file" ", --file=" file ", --makefile=" file ", --sconstruct=" file
714 as the initial SConscript file.
718 Print a local help message for this build, if one is defined in
719 the SConscript file(s), plus a line that describes the
721 option for command-line option help. If no local help message
722 is defined, prints the standard help message about command-line
723 options. Exits after displaying the appropriate message.
727 Print the standard help message about command-line options and
732 Ignore all errors from commands executed to rebuild files.
735 .RI -I " directory" ", --include-dir=" directory
739 imported Python modules. If several
742 are used, the directories are searched in the order specified.
746 Cache implicit dependencies. This can cause
748 to miss changes in the implicit dependencies in cases where a new implicit
749 dependency is added earlier in the implicit dependency search path
750 (e.g. CPPPATH) than a current implicit dependency with the same name.
753 --implicit-deps-changed
754 Force SCons to ignore the cached implicit dependencies. This causes the
755 implicit dependencies to be rescanned and recached. This implies
756 .BR --implicit-cache .
759 --implicit-deps-unchanged
760 Force SCons to ignore changes in the implicit dependencies.
761 This causes cached implicit dependencies to always be used.
763 .BR --implicit-cache .
766 .RI -j " N" ", --jobs=" N
767 Specifies the number of jobs (commands) to run simultaneously.
768 If there is more than one
770 option, the last one is effective.
774 .\" is specified without an argument,
776 .\" will not limit the number of
777 .\" simultaneous jobs.
781 Continue as much as possible after an error. The target that
782 failed and those that depend on it will not be remade, but other
783 targets specified on the command line will still be processed.
786 .\" .RI -l " N" ", --load-average=" N ", --max-load=" N
787 .\" No new jobs (commands) will be started if
788 .\" there are other jobs running and the system load
789 .\" average is at least
791 .\" (a floating-point number).
794 .RI --duplicate= ORDER
795 There are three ways to duplicate files in a build tree: hard links,
796 soft (symbolic) links and copies. The default behaviour of SCons is to
797 prefer hard links to soft links to copies. You can specify different
798 behaviours with this option.
808 SCons will attempt to duplicate files using
809 the mechanisms in the specified order.
814 .\" List derived files (targets, dependencies) that would be built,
815 .\" but do not build them.
816 .\" [XXX This can probably go away with the right
817 .\" combination of other options. Revisit this issue.]
821 .\" List derived files that would be built, with the actions
822 .\" (commands) that build them. Does not build the files.
823 .\" [XXX This can probably go away with the right
824 .\" combination of other options. Revisit this issue.]
828 .\" List derived files that would be built, plus where the file is
829 .\" defined (file name and line number). Does not build the files.
830 .\" [XXX This can probably go away with the right
831 .\" combination of other options. Revisit this issue.]
835 Ignored for compatibility with non-GNU versions of
839 .RI --max-drift= SECONDS
840 Set the maximum expected drift in the modification time of files to
842 This value determines how long a file must be unmodified
843 before its cached content signature
844 will be used instead of
845 calculating a new content signature (MD5 checksum)
846 of the file's contents.
847 The default value is 2 days, which means a file must have a
848 modification time of at least two days ago in order to have its
849 cached content signature used.
850 A negative value means to never cache the content
851 signature and to ignore the cached value if there already is one. A value
852 of 0 means to always use the cached signature,
853 no matter how old the file is.
856 -n, --just-print, --dry-run, --recon
857 No execute. Print the commands that would be executed to build
858 any out-of-date target files, but do not execute the commands.
861 .\" .RI -o " file" ", --old-file=" file ", --assume-old=" file
865 .\" not rebuild anything due to changes in the contents of
868 .\" .RI --override " file"
869 .\" Read values to override specific build environment variables
870 .\" from the specified
874 .\" Print the data base (construction environments,
875 .\" Builder and Scanner objects) that are defined
876 .\" after reading the SConscript files.
877 .\" After printing, a normal build is performed
878 .\" as usual, as specified by other command-line options.
879 .\" This also prints version information
884 .\" To print the database without performing a build do:
892 Run SCons under the Python profiler
893 and save the results in the specified
895 The results may be analyzed using the Python
900 Do not run any commands, or print anything. Just return an exit
901 status that is zero if the specified targets are already up to
902 date, non-zero otherwise.
905 Quiets SCons status messages about
906 reading SConscript files,
908 and entering directories.
909 Commands that are executed
910 to rebuild target files are still printed.
913 .\" -r, -R, --no-builtin-rules, --no-builtin-variables
914 .\" Clear the default construction variables. Construction
915 .\" environments that are created will be completely empty.
919 Build dependencies in a random order. This is useful when
920 building multiple trees simultaneously with caching enabled,
921 to prevent multiple builds from simultaneously trying to build
922 or retrieve the same target files.
925 -s, --silent, --quiet
926 Silent. Do not print commands that are executed to rebuild
928 Also suppresses SCons status messages.
931 -S, --no-keep-going, --stop
932 Ignored for compatibility with GNU
937 Ignored for compatibility with GNU
939 (Touching a file to make it
940 appear up-to-date is unnecessary when using
944 .RI --taskmastertrace= file
945 Prints trace information to the specified
947 about how the internal Taskmaster object
948 evaluates and controls the order in which Nodes are built.
951 may be used to specify the standard output.
954 -u, --up, --search-up
955 Walks up the directory structure until an
960 file is found, and uses that
961 as the top of the directory tree.
962 If no targets are specified on the command line,
963 only targets at or below the
964 current directory will be built.
968 Works exactly the same way as the
970 option except for the way default targets are handled.
971 When this option is used and no targets are specified on the command line,
972 all default targets that are defined in the SConscript(s) in the current
973 directory are built, regardless of what directory the resultant targets end
980 version, copyright information,
981 list of authors, and any other relevant information.
985 -w, --print-directory
986 Print a message containing the working directory before and
987 after other processing.
990 .RI --warn= type ", --warn=no-" type
991 Enable or disable warnings.
993 specifies the type of warnings to be enabled or disabled:
996 --warn=all, --warn=no-all
997 Enables or disables all warnings.
1000 --warn=dependency, --warn=no-dependency
1001 Enables or disables warnings about dependencies.
1002 These warnings are disabled by default.
1005 --warn=deprecated, --warn=no-deprecated
1006 Enables or disables warnings about use of deprecated features.
1007 These warnings are enabled by default.
1010 --warn=missing-sconscript, --warn=no-missing-sconscript
1011 Enables or disables warnings about missing SConscript files.
1012 These warnings are enabled by default.
1015 --no-print-directory
1016 Turn off -w, even if it was turned on implicitly.
1019 .\" .RI --write-filenames= file
1020 .\" Write all filenames considered into
1024 .\" .RI -W " file" ", --what-if=" file ", --new-file=" file ", --assume-new=" file
1025 .\" Pretend that the target
1028 .\" modified. When used with the
1031 .\" show you what would be rebuilt if you were to modify that file.
1037 .\" --warn-undefined-variables
1038 .\" Warn when an undefined variable is referenced.
1041 .RI -Y " repository" ", --repository=" repository
1042 Search the specified repository for any input and target
1043 files not found in the local directory hierarchy. Multiple
1045 options may specified, in which case the
1046 repositories are searched in the order specified.
1048 .SH CONFIGURATION FILE REFERENCE
1049 .\" .SS Python Basics
1050 .\" XXX Adding this in the future would be a help.
1051 .SS Construction Environments
1052 A construction environment is the basic means by which the SConscript
1053 files communicate build information to
1055 A new construction environment is created using the
1063 By default, a new construction environment is
1064 initialized with a set of builder methods
1065 and construction variables that are appropriate
1066 for the current platform.
1067 An optional platform keyword argument may be
1068 used to specify that an environment should
1069 be initialized for a different platform:
1072 env = Environment(platform = 'cygwin')
1073 env = Environment(platform = 'os2')
1074 env = Environment(platform = 'posix')
1075 env = Environment(platform = 'win32')
1078 Specifying a platform initializes the appropriate
1079 construction variables in the environment
1080 to use and generate file names with prefixes
1081 and suffixes appropriate for the platform.
1089 variables from the user's external environment
1090 to the construction environment's
1093 This is so that any executed commands
1094 that use sockets to connect with other systems
1095 (such as fetching source files from
1096 external CVS repository specifications like
1097 .BR :pserver:anonymous@cvs.sourceforge.net:/cvsroot/scons )
1098 will work on Windows systems.
1100 The platform argument may be function or callable object,
1101 in which case the Environment() method
1102 will call the specified argument to update
1103 the new construction environment:
1106 def my_platform(env):
1107 env['VAR'] = 'xyzzy'
1109 env = Environment(platform = my_platform)
1112 Additionally, a specific set of tools
1113 with which to initialize the environment
1114 may specified as an optional keyword argument:
1117 env = Environment(tools = ['msvc', 'lex'])
1120 Non-built-in tools may be specified using the toolpath argument:
1123 env = Environment(tools = ['default', 'foo'], toolpath = ['tools'])
1126 This looks for a tool specification in tools/foo.py (as well as
1127 using the ordinary default tools for the platform). foo.py should
1128 have two functions: generate(env, **kw) and exists(env).
1132 modifies the passed-in environment
1133 to set up variables so that the tool
1135 it may use any keyword arguments
1136 that the user supplies (see below)
1137 to vary its initialization.
1140 function should return a true
1141 value if the tool is available.
1142 Tools in the toolpath are used before
1143 any of the built-in ones. For example, adding gcc.py to the toolpath
1144 would override the built-in gcc tool.
1145 Also note that the toolpath is
1146 stored in the environment for use
1154 base = Environment(toolpath=['custom_path'])
1155 derived = base.Copy(tools=['custom_tool'])
1156 derived.CustomBuilder()
1159 The elements of the tools list may also
1160 be functions or callable objects,
1161 in which case the Environment() method
1162 will call the specified elements
1163 to update the new construction environment:
1167 env['XYZZY'] = 'xyzzy'
1169 env = Environment(tools = [my_tool])
1172 The individual elements of the tools list
1173 may also themselves be two-element lists of the form
1174 .RI ( toolname ", " kw_dict ).
1175 SCons searches for the
1177 specification file as described above, and
1180 which must be a dictionary, as keyword arguments to the tool's
1185 function can use the arguments to modify the tool's behavior
1186 by setting up the environment in different ways
1187 or otherwise changing its initialization.
1190 # in tools/my_tool.py:
1191 def generate(env, **kw):
1192 # Sets MY_TOOL to the value of keyword argument 'arg1' or 1.
1193 env['MY_TOOL'] = kw.get('arg1', '1')
1198 env = Environment(tools = ['default', ('my_tool', {'arg1': 'abc'})],
1202 The tool definition (i.e. my_tool()) can use the PLATFORM variable from
1203 the environment it receives to customize the tool for different platforms.
1205 If no tool list is specified, then SCons will auto-detect the installed
1206 tools using the PATH variable in the ENV construction variable and the
1207 platform name when the Environment is constructed. Changing the PATH
1208 variable after the Environment is constructed will not cause the tools to
1211 SCons supports the following tool specifications out of the box:
1287 Additionally, there is a "tool" named
1289 which configures the
1290 environment with a default set of tools for the current platform.
1292 On posix and cygwin platforms
1293 the GNU tools (e.g. gcc) are preferred by SCons,
1294 on Windows the Microsoft tools (e.g. msvc)
1295 followed by MinGW are preferred by SCons,
1296 and in OS/2 the IBM tools (e.g. icc) are preferred by SCons.
1300 Build rules are specified by calling a construction
1301 environment's builder methods.
1302 The arguments to the builder methods are
1304 (a list of target files)
1307 (a list of source files).
1309 Because long lists of file names
1310 can lead to a lot of quoting,
1315 and a same-named environment method
1316 that split a single string
1317 into a list, separated on
1318 strings of white-space characters.
1319 (These are similar to the
1320 string.split() method
1321 from the standard Python library,
1322 but work even if the input isn't a string.)
1324 Like all Python arguments,
1325 the target and source arguments to a builder method
1326 can be specified either with or without
1327 the "target" and "source" keywords.
1328 When the keywords are omitted,
1329 the target is first,
1330 followed by the source.
1331 The following are equivalent examples of calling the Program builder method:
1334 env.Program('bar', ['bar.c', 'foo.c'])
1335 env.Program('bar', Split('bar.c foo.c'))
1336 env.Program('bar', env.Split('bar.c foo.c'))
1337 env.Program(source = ['bar.c', 'foo.c'], target = 'bar')
1338 env.Program(target = 'bar', Split('bar.c foo.c'))
1339 env.Program(target = 'bar', env.Split('bar.c foo.c'))
1340 env.Program('bar', source = string.split('bar.c foo.c'))
1343 When the target shares the same base name
1344 as the source and only the suffix varies,
1345 and if the builder method has a suffix defined for the target file type,
1346 then the target argument may be omitted completely,
1349 will deduce the target file name from
1350 the source file name.
1351 The following examples all build the
1357 (on Windows systems)
1358 from the bar.c source file:
1361 env.Program(target = 'bar', source = 'bar.c')
1362 env.Program('bar', source = 'bar.c')
1363 env.Program(source = 'bar.c')
1364 env.Program('bar.c')
1367 It is possible to override or add construction variables when calling a
1368 builder method by passing additional keyword arguments.
1369 These overridden or added
1370 variables will only be in effect when building the target, so they will not
1371 affect other parts of the build. For example, if you want to add additional
1372 libraries for just one program:
1375 env.Program('hello', 'hello.c', LIBS=['gl', 'glut'])
1378 or generate a shared library with a non-standard suffix:
1381 env.SharedLibrary('word', 'word.cpp',
1383 LIBSUFFIXES=['.ocx'])
1386 (Note that both the $SHLIBSUFFIX and $LIBSUFFIXES variables must be set
1387 if you want SCons to search automatically
1388 for dependencies on the non-standard library names;
1389 see the descriptions of these variables, below, for more information.)
1391 Although the builder methods defined by
1394 methods of a construction environment object,
1395 they may also be called without an explicit environment:
1398 Program('hello', 'hello.c')
1399 SharedLibrary('word', 'word.cpp')
1403 the methods are called internally using a default construction
1404 environment that consists of the tools and values that
1406 has determined are appropriate for the local system.
1408 Builder methods that can be called without an explicit
1409 environment may be called from custom Python modules that you
1410 import into an SConscript file by adding the following
1411 to the Python module:
1414 from SCons.Script import *
1417 All builder methods return a list of Nodes
1418 that represent the target or targets that will be built.
1421 is an internal SCons object
1423 build targets or sources.
1425 The returned Node(s)
1426 can be passed to other builder methods as source(s)
1427 or passed to any SCons function or method
1428 where a filename would normally be accepted.
1429 For example, if it were necessary
1432 flag when compiling one specific object file:
1435 bar_obj_list = env.StaticObject('bar.c', CPPDEFINES='-DBAR')
1436 env.Program(source = ['foo.c', bar_obj_list, 'main.c'])
1439 Using a Node in this way
1440 makes for a more portable build
1441 by avoiding having to specify
1442 a platform-specific object suffix
1443 when calling the Program() builder method.
1445 Note that Builder calls will automatically "flatten"
1446 the source and target file lists,
1447 so it's all right to have the bar_obj list
1448 return by the StaticObject() call
1449 in the middle of the source file list.
1450 If you need to manipulate a list of lists returned by Builders
1451 directly using Python,
1452 you can either build the list by hand:
1455 foo = Object('foo.c')
1456 bar = Object('bar.c')
1457 objects = ['begin.o'] + foo + ['middle.o'] + bar + ['end.o']
1458 for object in objects:
1465 to create a list containing just the Nodes,
1466 which may be more convenient:
1469 foo = Object('foo.c')
1470 bar = Object('bar.c')
1471 objects = Flatten(['begin.o', foo, 'middle.o', bar, 'end.o'])
1472 for object in objects:
1476 The path name for a Node's file may be used
1477 by passing the Node to the Python-builtin
1482 bar_obj_list = env.StaticObject('bar.c', CPPDEFINES='-DBAR')
1483 print "The path to bar_obj is:", str(bar_obj_list[0])
1486 Note again that because the Builder call returns a list,
1487 we have to access the first element in the list
1488 .B (bar_obj_list[0])
1489 to get at the Node that actually represents
1492 Builder calls support a
1494 keyword argument that
1495 specifies that the Builder's action(s)
1497 after changing directory.
1501 a string or a directory Node,
1502 scons will change to the specified directory.
1505 is not a string or Node
1507 then scons will change to the
1508 target file's directory.
1511 # scons will change to the "sub" subdirectory
1512 # before executing the "cp" command.
1513 env.Command('sub/dir/foo.out', 'sub/dir/foo.in',
1514 "cp dir/foo.in dir/foo.out",
1517 # Because chdir is not a string, scons will change to the
1518 # target's directory ("sub/dir") before executing the
1520 env.Command('sub/dir/foo.out', 'sub/dir/foo.in',
1521 "cp foo.in foo.out",
1525 Note that scons will
1527 automatically modify
1529 construction variables like
1533 when using the chdir
1534 keyword argument--that is,
1535 the expanded file names
1536 will still be relative to
1537 the top-level SConstruct directory,
1538 and consequently incorrect
1539 relative to the chdir directory.
1540 If you use the chdir keyword argument,
1541 you will typically need to supply a different
1547 to use just the filename portion of the
1551 provides the following builder methods:
1553 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1554 '\" BEGIN GENERATED BUILDER DESCRIPTIONS
1556 '\" The descriptions below of the various SCons Builders are generated
1557 '\" from the .xml files that live next to the various Python modules in
1558 '\" the build enginer library. If you're reading this [gnt]roff file
1559 '\" with an eye towards patching this man page, you can still submit
1560 '\" a diff against this text, but it will have to be translated to a
1561 '\" diff against the underlying .xml file before the patch is actually
1562 '\" accepted. If you do that yourself, it will make it easier to
1563 '\" integrate the patch.
1565 '\" BEGIN GENERATED BUILDER DESCRIPTIONS
1566 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1568 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1569 '\" END GENERATED BUILDER DESCRIPTIONS
1571 '\" The descriptions above of the various SCons Builders are generated
1572 '\" from the .xml files that live next to the various Python modules in
1573 '\" the build enginer library. If you're reading this [gnt]roff file
1574 '\" with an eye towards patching this man page, you can still submit
1575 '\" a diff against this text, but it will have to be translated to a
1576 '\" diff against the underlying .xml file before the patch is actually
1577 '\" accepted. If you do that yourself, it will make it easier to
1578 '\" integrate the patch.
1580 '\" END GENERATED BUILDER DESCRIPTIONS
1581 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1584 targets of builder methods automatically depend on their sources.
1585 An explicit dependency can
1586 be specified using the
1588 method of a construction environment (see below).
1593 source files for various programming languages,
1594 so the dependencies do not need to be specified explicitly.
1595 By default, SCons can
1598 Fortran source files with
1600 (POSIX systems only),
1605 and assembly language files with
1607 (POSIX systems only),
1612 for C preprocessor dependencies.
1613 SCons also has default support
1614 for scanning D source files,
1615 You can also write your own Scanners
1616 to add support for additional source file types.
1617 These can be added to the default
1618 Scanner object used by
1624 Builders by adding them
1626 .B SourceFileScanner
1629 See the section "Scanner Objects,"
1630 below, for a more information about
1631 defining your own Scanner objects.
1633 .SS Methods and Functions to Do Things
1634 In addition to Builder methods,
1636 provides a number of other construction environment methods
1637 and global functions to
1638 manipulate the build configuration.
1640 Usually, a construction environment method
1641 and global function with the same name both exist
1642 so that you don't have to remember whether
1643 to a specific bit of functionality
1644 must be called with or without a construction environment.
1645 In the following list,
1646 if you call something as a global function
1649 .RI Function( arguments )
1651 and if you call something through a construction
1652 environment it looks like:
1654 .RI env.Function( arguments )
1656 If you can call the functionality in both ways,
1657 then both forms are listed.
1659 Global functions may be called from custom Python modules that you
1660 import into an SConscript file by adding the following
1661 to the Python module:
1664 from SCons.Script import *
1667 Except where otherwise noted,
1669 construction environment method
1671 provide the exact same functionality.
1672 The only difference is that,
1674 calling the functionality through a construction environment will
1675 substitute construction variables into
1676 any supplied strings.
1679 env = Environment(FOO = 'foo')
1683 the first call to the global
1685 function will actually add a target named
1687 to the list of default targets,
1688 while the second call to the
1690 construction environment method
1691 will expand the value
1692 and add a target named
1694 to the list of default targets.
1695 For more on construction variable expansion,
1696 see the next section on
1697 construction variables.
1699 Construction environment methods
1700 and global functions supported by
1704 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1706 .RI Action( action ", [" strfunction ", " varlist ])
1708 .RI env.Action( action ", [" strfunction ", " varlist ])
1709 Creates an Action object for
1712 See the section "Action Objects,"
1713 below, for a complete explanation of the arguments and behavior.
1715 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1717 .RI AddPostAction( target ", " action )
1719 .RI env.AddPostAction( target ", " action )
1720 Arranges for the specified
1726 The specified action(s) may be
1727 an Action object, or anything that
1728 can be converted into an Action object
1731 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1733 .RI AddPreAction( target ", " action )
1735 .RI env.AddPreAction( target ", " action )
1736 Arranges for the specified
1739 before the specified
1742 The specified action(s) may be
1743 an Action object, or anything that
1744 can be converted into an Action object
1747 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1749 .RI Alias( alias ", [" targets ", [" action ]])
1751 .RI env.Alias( alias ", [" targets ", [" action ]])
1752 Creates one or more phony targets that
1753 expand to one or more other targets.
1758 can be specified that will be executed
1759 whenever the any of the alias targets are out-of-date.
1760 Returns the Node object representing the alias,
1761 which exists outside of any file system.
1762 This Node object, or the alias name,
1763 may be used as a dependency of any other target,
1764 including another alias.
1766 can be called multiple times for the same
1767 alias to add additional targets to the alias,
1768 or additional actions to the list for this alias.
1772 Alias('install', '/usr/bin')
1773 Alias(['install', 'install-lib'], '/usr/local/lib')
1775 env.Alias('install', ['/usr/local/bin', '/usr/local/lib'])
1776 env.Alias('install', ['/usr/local/man'])
1778 env.Alias('update', ['file1', 'file2'], "update_database $SOURCES")
1781 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1783 .RI AlwaysBuild( target ", ...)"
1785 .RI env.AlwaysBuild( target ", ...)"
1788 so that it is always assumed to be out of date,
1789 and will always be rebuilt if needed.
1792 does not add its target(s) to the default target list,
1793 so the targets will only be built
1794 if they are specified on the command line,
1795 or are a dependent of a target specified on the command line--but
1798 be built if so specified.
1799 Multiple targets can be passed in to a single call to
1802 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1804 .RI env.Append( key = val ", [...])"
1805 Appends the specified keyword arguments
1806 to the end of construction variables in the environment.
1807 If the Environment does not have
1808 the specified construction variable,
1809 it is simply added to the environment.
1810 If the values of the construction variable
1811 and the keyword argument are the same type,
1812 then the two values will be simply added together.
1813 Otherwise, the construction variable
1814 and the value of the keyword argument
1815 are both coerced to lists,
1816 and the lists are added together.
1817 (See also the Prepend method, below.)
1820 env.Append(CCFLAGS = ' -g', FOO = ['foo.yyy'])
1823 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1825 .RI env.AppendENVPath( name ", " newpath ", [" envname ", " sep ])
1826 This appends new path elements to the given path in the
1827 specified external environment
1831 any particular path once (leaving the last one it encounters and
1832 ignoring the rest, to preserve path order),
1833 and to help assure this,
1834 will normalize all paths (using
1837 .BR os.path.normcase ).
1838 This can also handle the
1839 case where the given old path variable is a list instead of a
1840 string, in which case a list will be returned instead of a string.
1844 print 'before:',env['ENV']['INCLUDE']
1845 include_path = '/foo/bar:/foo'
1846 env.AppendENVPath('INCLUDE', include_path)
1847 print 'after:',env['ENV']['INCLUDE']
1851 after: /biz:/foo/bar:/foo
1854 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1856 .RI env.AppendUnique( key = val ", [...])"
1857 Appends the specified keyword arguments
1858 to the end of construction variables in the environment.
1859 If the Environment does not have
1860 the specified construction variable,
1861 it is simply added to the environment.
1862 If the construction variable being appended to is a list,
1863 then any value(s) that already exist in the
1864 construction variable will
1866 be added again to the list.
1869 env.AppendUnique(CCFLAGS = '-g', FOO = ['foo.yyy'])
1872 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1875 A factory function that
1876 returns a Builder object
1877 to be used to fetch source files
1879 The returned Builder
1880 is intended to be passed to the
1885 env.SourceCode('.', env.BitKeeper())
1888 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1890 .RI BuildDir( build_dir ", " src_dir ", [" duplicate ])
1892 .RI env.BuildDir( build_dir ", " src_dir ", [" duplicate ])
1893 This specifies a build directory
1895 in which to build all derived files
1896 that would normally be built under
1898 Multiple build directories can be set up for multiple build variants, for
1901 must be underneath the SConstruct file's directory,
1904 may not be underneath the
1907 The default behavior is for
1909 to duplicate all of the files in the tree underneath
1913 and then build the derived files within the copied tree.
1914 (The duplication is performed by
1916 depending on the platform; see also the
1919 This guarantees correct builds
1920 regardless of whether intermediate source files
1921 are generated during the build,
1922 where preprocessors or other scanners search
1924 or whether individual compilers or other invoked tools
1925 are hard-coded to put derived files in the same directory as source files.
1927 This behavior of making a complete copy of the source tree
1928 may be disabled by setting
1933 to invoke Builders using the
1934 path names of source files in
1936 and the path names of derived files within
1938 This is always more efficient than
1940 and is usually safe for most builds.
1944 may cause build problems
1945 if source files are generated during the build,
1946 if any invoked tools are hard-coded to
1947 put derived files in the same directory as the source files.
1949 Note that specifying a
1951 works most naturally
1952 with a subsidiary SConscript file
1953 in the source directory.
1955 you would then call the subsidiary SConscript file
1956 not in the source directory,
1961 had made a virtual copy of the source tree
1962 regardless of the value of
1964 This is how you tell
1966 which variant of a source tree to build.
1970 BuildDir('build-variant1', 'src')
1971 SConscript('build-variant1/SConscript')
1972 BuildDir('build-variant2', 'src')
1973 SConscript('build-variant2/SConscript')
1979 function, described below,
1981 specify a build directory
1982 in conjunction with calling a subsidiary
1985 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1987 .RI Builder( action ", [" arguments ])
1989 .RI env.Builder( action ", [" arguments ])
1990 Creates a Builder object for
1993 See the section "Builder Objects,"
1994 below, for a complete explanation of the arguments and behavior.
1996 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1998 .RI CacheDir( cache_dir )
2000 .RI env.CacheDir( cache_dir )
2003 will maintain a cache of derived files in
2005 The derived files in the cache will be shared
2006 among all the builds using the same
2014 finds a derived file that needs to be rebuilt,
2015 it will first look in the cache to see if a
2016 derived file has already been built
2017 from identical input files and an identical build action
2018 (as incorporated into the MD5 build signature).
2021 will retrieve the file from the cache.
2022 If the derived file is not present in the cache,
2025 then place a copy of the built file in the cache
2026 (identified by its MD5 build signature),
2027 so that it may be retrieved by other
2028 builds that need to build the same derived file
2029 from identical inputs.
2033 may be disabled for any invocation
2042 will place a copy of
2044 derived files in the cache,
2045 even if they already existed
2046 and were not built by this invocation.
2047 This is useful to populate a cache
2050 is added to a build,
2059 "Retrieved `file' from cache,"
2062 option is being used.
2067 will print the action that
2069 have been used to build the file,
2070 without any indication that
2071 the file was actually retrieved from the cache.
2072 This is useful to generate build logs
2073 that are equivalent regardless of whether
2074 a given derived file has been built in-place
2075 or retrieved from the cache.
2077 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2079 .RI Clean( targets ", " files_or_dirs )
2081 .RI env.Clean( targets ", " files_or_dirs )
2082 This specifies a list of files or directories which should be removed
2083 whenever the targets are specified with the
2085 command line option.
2086 The specified targets may be a list
2087 or an individual target.
2091 and create new targets or add files and directories to the
2092 clean list for the specified targets.
2094 Multiple files or directories should be specified
2095 either as separate arguments to the
2097 method, or as a list.
2099 will also accept the return value of any of the construction environment
2105 function overrides calling
2107 for the same target,
2108 and any targets passed to both functions will
2117 Clean('foo', ['bar', 'baz'])
2118 Clean('dist', env.Program('hello', 'hello.c'))
2119 Clean(['foo', 'bar'], 'something_else_to_clean')
2122 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2124 .RI Command( target ", " source ", " action ", [" key = val ", ...])"
2126 .RI env.Command( target ", " source ", " action ", [" key = val ", ...])"
2127 Executes a specific action
2128 (or list of actions)
2129 to build a target file or files.
2130 This is more convenient
2131 than defining a separate Builder object
2132 for a single special-case build.
2134 As a special case, the
2136 keyword argument can
2139 that will be used to scan the sources.
2143 if any of the sources will be directories
2144 that must be scanned on-disk for
2145 changes to files that aren't
2146 already specified in other Builder of function calls.)
2148 Any other keyword arguments specified override any
2149 same-named existing construction variables.
2151 An action can be an external command,
2152 specified as a string,
2153 or a callable Python object;
2154 see "Action Objects," below,
2155 for more complete information.
2156 Also note that a string specifying an external command
2157 may be preceded by an
2160 to suppress printing the command in question,
2164 to ignore the exit status of the external command.
2168 env.Command('foo.out', 'foo.in',
2169 "$FOO_BUILD < $SOURCES > $TARGET")
2171 env.Command('bar.out', 'bar.in',
2173 "$BAR_BUILD < $SOURCES > $TARGET"],
2174 ENV = {'PATH' : '/usr/local/bin/'})
2176 def rename(env, target, source):
2178 os.rename('.tmp', str(target[0]))
2180 env.Command('baz.out', 'baz.in',
2181 ["$BAZ_BUILD < $SOURCES > .tmp",
2187 function will usually assume, by default,
2188 that the specified targets and/or sources are Files,
2189 if no other part of the configuration
2190 identifies what type of entry it is.
2191 If necessary, you can explicitly specify
2192 that targets or source nodes should
2193 be treated as directoriese
2201 env.Command('ddd.list', Dir('ddd'), 'ls -l $SOURCE > $TARGET')
2203 env['DISTDIR'] = 'destination/directory'
2204 env.Command(env.Dir('$DISTDIR')), None, make_distdir)
2207 (Also note that SCons will usually
2208 automatically create any directory necessary to hold a target file,
2209 so you normally don't need to create directories by hand.)
2211 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2213 .RI Configure( env ", [" custom_tests ", " conf_dir ", " log_file ", " config_h ])
2215 .RI env.Configure([ custom_tests ", " conf_dir ", " log_file ", " config_h ])
2216 Creates a Configure object for integrated
2217 functionality similar to GNU autoconf.
2218 See the section "Configure Contexts,"
2219 below, for a complete explanation of the arguments and behavior.
2221 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2223 .RI env.Copy([ key = val ", ...])"
2224 Return a separate copy of a construction environment.
2225 If there are any keyword arguments specified,
2226 they are added to the returned copy,
2227 overwriting any existing values
2232 env3 = env.Copy(CCFLAGS = '-g')
2235 Additionally, a list of tools and a toolpath may be specified, as in
2236 the Environment constructor:
2239 def MyTool(env): env['FOO'] = 'bar'
2240 env4 = env.Copy(tools = ['msvc', MyTool])
2243 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2245 .RI env.CVS( repository ", " module )
2246 A factory function that
2247 returns a Builder object
2248 to be used to fetch source files
2252 The returned Builder
2253 is intended to be passed to the
2257 The optional specified
2259 will be added to the beginning
2260 of all repository path names;
2261 this can be used, in essence,
2262 to strip initial directory names
2263 from the repository path names,
2264 so that you only have to
2265 replicate part of the repository
2266 directory hierarchy in your
2267 local build directory:
2270 # Will fetch foo/bar/src.c
2271 # from /usr/local/CVSROOT/foo/bar/src.c.
2272 env.SourceCode('.', env.CVS('/usr/local/CVSROOT'))
2274 # Will fetch bar/src.c
2275 # from /usr/local/CVSROOT/foo/bar/src.c.
2276 env.SourceCode('.', env.CVS('/usr/local/CVSROOT', 'foo'))
2279 # from /usr/local/CVSROOT/foo/bar/src.c.
2280 env.SourceCode('.', env.CVS('/usr/local/CVSROOT', 'foo/bar'))
2283 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2285 .RI Default( targets )
2287 .RI env.Default( targets )
2288 This specifies a list of default targets,
2289 which will be built by
2291 if no explicit targets are given on the command line.
2295 and add to the list of default targets.
2297 Multiple targets should be specified as
2298 separate arguments to the
2300 method, or as a list.
2302 will also accept the Node returned by any
2303 of a construction environment's
2308 Default('foo', 'bar', 'baz')
2309 env.Default(['a', 'b', 'c'])
2310 hello = env.Program('hello', 'hello.c')
2318 will clear all default targets.
2321 will add to the (now empty) default-target list
2324 The current list of targets added using the
2326 function or method is available in the
2331 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2333 .RI DefaultEnvironment([ args ])
2334 Creates and returns a default construction environment object.
2335 This construction environment is used internally by SCons
2336 in order to execute many of the global functions in this list,
2337 and to fetch source files transparently
2338 from source code management systems.
2340 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2342 .RI Depends( target ", " dependency )
2344 .RI env.Depends( target ", " dependency )
2345 Specifies an explicit dependency;
2346 the target file(s) will be rebuilt
2347 whenever the dependency file(s) has changed.
2348 This should only be necessary
2349 for cases where the dependency
2350 is not caught by a Scanner
2354 env.Depends('foo', 'other-input-file-for-foo')
2357 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2359 .RI env.Dictionary([ vars ])
2360 Returns a dictionary object
2361 containing copies of all of the
2362 construction variables in the environment.
2363 If there are any variable names specified,
2364 only the specified construction
2365 variables are returned in the dictionary.
2368 dict = env.Dictionary()
2369 cc_dict = env.Dictionary('CC', 'CCFLAGS', 'CCCOM')
2372 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2374 .RI Dir( name ", [" directory ])
2376 .RI env.Dir( name ", [" directory ])
2377 This returns a Directory Node,
2378 an object that represents the specified directory
2381 can be a relative or absolute path.
2383 is an optional directory that will be used as the parent directory.
2386 is specified, the current script's directory is used as the parent.
2388 Directory Nodes can be used anywhere you
2389 would supply a string as a directory name
2390 to a Builder method or function.
2391 Directory Nodes have attributes and methods
2392 that are useful in many situations;
2393 see "File and Directory Nodes," below.
2395 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2397 .RI env.Dump([ key ])
2398 Returns a pretty printable representation of the environment.
2402 should be a string containing the name of the variable of interest.
2407 print env.Dump('CCCOM')
2411 '$CC $CCFLAGS $CPPFLAGS $_CPPDEFFLAGS $_CPPINCFLAGS -c -o $TARGET $SOURCES'
2421 'ARCOM': '$AR $ARFLAGS $TARGET $SOURCES\n$RANLIB $RANLIBFLAGS $TARGET',
2424 'ASCOM': '$AS $ASFLAGS -o $TARGET $SOURCES',
2429 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2431 .RI EnsurePythonVersion( major ", " minor )
2433 .RI env.EnsurePythonVersion( major ", " minor )
2434 Ensure that the Python version is at least
2437 print out an error message and exit SCons with a non-zero exit code if the
2438 actual Python version is not late enough.
2441 EnsurePythonVersion(2,2)
2444 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2446 .RI EnsureSConsVersion( major ", " minor ", [" revision ])
2448 .RI env.EnsureSConsVersion( major ", " minor ", [" revision ])
2449 Ensure that the SCons version is at least
2452 .IR major.minor.revision .
2457 print out an error message and exit SCons with a non-zero exit code if the
2458 actual SCons version is not late enough.
2461 EnsureSConsVersion(0,14)
2463 EnsureSConsVersion(0,96,90)
2466 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2468 .RI Environment([ key = value ", ...])"
2470 .RI env.Environment([ key = value ", ...])"
2471 Return a new construction environment
2472 initialized with the specified
2476 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2478 .RI Execute( action ", [" strfunction ", " varlist ])
2480 .RI env.Execute( action ", [" strfunction ", " varlist ])
2481 Executes an Action object.
2484 may be an Action object
2485 (see the section "Action Objects,"
2486 below, for a complete explanation of the arguments and behavior),
2487 or it may be a command-line string,
2489 or executable Python function,
2490 each of which will be converted
2491 into an Action object
2493 The exit value of the command
2494 or return value of the Python function
2497 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2501 .RI env.Exit([ value ])
2507 A default exit value of
2510 is used if no value is specified.
2512 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2516 .RI env.Export( vars )
2519 to export a list of variables from the current
2520 SConscript file to all other SConscript files.
2521 The exported variables are kept in a global collection,
2522 so subsequent calls to
2524 will over-write previous exports that have the same name.
2525 Multiple variable names can be passed to
2527 as separate arguments or as a list. A dictionary can be used to map
2528 variables to a different name when exported. Both local variables and
2529 global variables can be exported.
2534 # Make env available for all SConscript files to Import().
2538 # Make env and package available for all SConscript files:.
2539 Export("env", "package")
2541 # Make env and package available for all SConscript files:
2542 Export(["env", "package"])
2544 # Make env available using the name debug:.
2545 Export({"debug":env})
2551 function supports an
2553 argument that makes it easier to to export a variable or
2554 set of variables to a single SConscript file.
2555 See the description of the
2559 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2561 .RI File( name ", [" directory ])
2563 .RI env.File( name ", [" directory ])
2566 an object that represents the specified file
2569 can be a relative or absolute path.
2571 is an optional directory that will be used as the parent directory.
2573 File Nodes can be used anywhere you
2574 would supply a string as a file name
2575 to a Builder method or function.
2576 File Nodes have attributes and methods
2577 that are useful in many situations;
2578 see "File and Directory Nodes," below.
2580 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2582 .RI FindFile( file ", " dirs )
2584 .RI env.FindFile( file ", " dirs )
2587 in the path specified by
2590 may be a list of file names or a single file name. In addition to searching
2591 for files that exist in the filesytem, this function also searches for
2592 derived files that have not yet been built.
2595 foo = env.FindFile('foo', ['dir1', 'dir2'])
2598 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2600 .RI Flatten( sequence )
2602 .RI env.Flatten( sequence )
2603 Takes a sequence (that is, a Python list or tuple)
2604 that may contain nested sequences
2605 and returns a flattened list containing
2606 all of the individual elements in any sequence.
2607 This can be helpful for collecting
2608 the lists returned by calls to Builders;
2609 other Builders will automatically
2610 flatten lists specified as input,
2611 but direct Python manipulation of
2612 these lists does not:
2615 foo = Object('foo.c')
2616 bar = Object('bar.c')
2618 # Because `foo' and `bar' are lists returned by the Object() Builder,
2619 # `objects' will be a list containing nested lists:
2620 objects = ['f1.o', foo, 'f2.o', bar, 'f3.o']
2622 # Passing such a list to another Builder is all right because
2623 # the Builder will flatten the list automatically:
2624 Program(source = objects)
2626 # If you need to manipulate the list directly using Python, you need to
2627 # call Flatten() yourself, or otherwise handle nested lists:
2628 for object in Flatten(objects):
2632 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2634 .RI GetBuildPath( file ", [" ... ])
2636 .RI env.GetBuildPath( file ", [" ... ])
2639 path name (or names) for the specified
2647 Nodes or strings representing path names.
2649 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2653 .RI env.GetLaunchDir()
2654 Returns the absolute path name of the directory from which
2657 was initially invoked.
2658 This can be useful when using the
2663 options, which internally
2664 change to the directory in which the
2668 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2670 .RI GetOption( name )
2672 .RI env.GetOption( name )
2673 This function provides a way to query a select subset of the scons command line
2674 options from a SConscript file. See
2676 for a description of the options available.
2678 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2680 '\".RI GlobalBuilders( flag )
2684 '\"adds the names of the default builders
2685 '\"(Program, Library, etc.)
2686 '\"to the global name space
2687 '\"so they can be called without an explicit construction environment.
2688 '\"(This is the default.)
2692 '\"the names of the default builders are removed
2693 '\"from the global name space
2694 '\"so that an explicit construction environment is required
2695 '\"to call all builders.
2697 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2701 .RI env.Help( text )
2702 This specifies help text to be printed if the
2704 argument is given to
2708 is called multiple times, the text is appended together in the order
2713 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2715 .RI Ignore( target ", " dependency )
2717 .RI env.Ignore( target ", " dependency )
2718 The specified dependency file(s)
2719 will be ignored when deciding if
2720 the target file(s) need to be rebuilt.
2723 env.Ignore('foo', 'foo.c')
2724 env.Ignore('bar', ['bar1.h', 'bar2.h'])
2727 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2731 .RI env.Import( vars )
2734 to import a list of variables into the current SConscript file. This
2735 will import variables that were exported with
2741 Variables exported by
2744 Multiple variable names can be passed to
2746 as separate arguments or as a list. The variable "*" can be used
2747 to import all variables.
2752 Import("env", "variable")
2753 Import(["env", "variable"])
2757 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2759 .RI Install( dir ", " source )
2761 .RI env.Install( dir ", " source )
2762 Installs one or more files in a destination directory.
2763 The file names remain the same.
2766 env.Install(dir = '/usr/local/bin', source = ['foo', 'bar'])
2769 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2771 .RI InstallAs( target ", " source )
2773 .RI env.InstallAs( target ", " source )
2774 Installs one or more files as specific file names,
2775 allowing changing a file name as part of the
2777 It is an error if the target and source
2778 list different numbers of files.
2781 env.InstallAs(target = '/usr/local/bin/foo',
2782 source = 'foo_debug')
2783 env.InstallAs(target = ['../lib/libfoo.a', '../lib/libbar.a'],
2784 source = ['libFOO.a', 'libBAR.a'])
2787 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2789 .RI Literal( string )
2791 .RI env.Literal( string )
2794 will be preserved as-is
2795 and not have construction variables expanded.
2797 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2799 .RI Local( targets )
2801 .RI env.Local( targets )
2804 will have copies made in the local tree,
2805 even if an already up-to-date copy
2806 exists in a repository.
2807 Returns a list of the target Node or Nodes.
2809 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2811 .RI env.MergeFlags( arg ", [" unique ])
2812 Merges the specified
2814 values to the construction envrionment's construction variables.
2817 argument is not a dictionary,
2818 it is converted to one by calling
2821 before the values are merged.
2824 must be a single value,
2825 so multiple strings must
2826 be passed in as a list,
2827 not as separate arguments to
2828 .BR env.MergeFlags ().
2831 duplicate values are eliminated;
2832 you can, however, specify
2836 When eliminating duplicate values,
2837 any construction variables that end with
2840 keep the left-most unique value.
2841 All other construction variables keep
2842 the right-most unique value.
2847 # Add an optimization flag to $CCFLAGS.
2848 env.MergeFlags('-O3')
2850 # Combine the flags returned from running pkg-config with an optimization
2851 # flag and merge the result into the construction variables.
2852 env.MergeFlags(['!pkg-config gtk+-2.0 --cflags', '-O3'])
2854 env.MergeFlags(['-O3',
2855 '!pkg-config gtk+-2.0 --cflags --libs',
2856 '!pkg-config libpng12 --cflags --libs'])
2859 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2861 .RI NoClean( target ", ...)"
2863 .RI env.NoClean( target ", ...)"
2864 Specifies a list of files or directories which should
2866 be removed whenever the targets (or their dependencies)
2867 are specified with the
2869 command line option.
2870 The specified targets may be a list
2871 or an individual target.
2875 and prevent each specified target
2876 from being removed by calls to the
2880 Multiple files or directories should be specified
2881 either as separate arguments to the
2883 method, or as a list.
2885 will also accept the return value of any of the construction environment
2890 for a target overrides calling
2892 for the same target,
2893 and any targets passed to both functions will
2903 NoClean(env.Program('hello', 'hello.c'))
2906 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2908 .RI env.ParseConfig( command ", [" function ", " unique ])
2911 to modify the environment as specified by the output of
2916 .BR env.MergeFlags (),
2917 which expects the output of a typical
2921 and adds the options
2922 to the appropriate construction variables.
2924 duplicate values are not
2925 added to any construction variables;
2932 and the construction variables they affect
2933 are as specified for the
2934 .BR env.ParseFlags ()
2935 method (which thie method calls).
2936 See that method's description, below,
2937 for a table of options and construction variables.
2939 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2941 .RI ParseDepends( filename ", [" must_exist ])
2943 .RI env.ParseDepends( filename ", [" must_exist " " only_one ])
2944 Parses the contents of the specified
2946 as a list of dependencies in the style of
2950 and explicitly establishes all of the listed dependencies.
2959 argument may be set to a non-zero
2962 throw an exception and
2963 generate an error if the file does not exist,
2964 or is otherwise inaccessible.
2968 argument may be set to a non-zero
2971 thrown an exception and
2973 if the file contains dependency
2974 information for more than one target.
2975 This can provide a small sanity check
2976 for files intended to be generated
2977 by, for example, the
2980 which should typically only
2981 write dependency information for
2982 one output file into a corresponding
2988 and all of the files listed therein
2989 will be interpreted relative to
2990 the directory of the
2992 file which calls the
2996 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2998 .RI env.ParseFlags( flags ", ...)"
2999 Parses one or more strings containing
3000 typical command-line flags for GCC tool chains
3001 and returns a dictionary with the flag values
3002 separated into the appropriate SCons construction variables.
3003 This is intended as a companion to the
3004 .BR env.MergeFlags ()
3005 method, but allows for the values in the returned dictionary
3006 to be modified, if necessary,
3007 before merging them into the construction environment.
3009 .BR env.MergeFlags ()
3010 will call this method if its argument is not a dictionary,
3011 so it is usually not necessary to call
3012 .BR env.ParseFlags ()
3013 directly unless you want to manipulate the values.)
3015 If the first character in any string is
3016 an exclamation mark (!),
3017 the rest of the string is executed as a command,
3018 and the output from the command is
3019 parsed as GCC tool chain command-line flags
3020 and added to the resulting dictionary.
3022 Flag values are translated accordig to the prefix found,
3023 and added to the following construction variables:
3026 -arch CCFLAGS, LINKFLAGS
3028 -framework FRAMEWORKS
3029 -frameworkdir= FRAMEWORKPATH
3031 -isysroot CCFLAGS, LINKFLAGS
3035 -mno-cygwin CCFLAGS, LINKFLAGS
3037 -pthread CCFLAGS, LINKFLAGS
3038 -Wa, ASFLAGS, CCFLAGS
3045 + CCFLAGS, LINKFLAGS
3048 Any other strings not associated with options
3049 are assumed to be the names of libraries
3052 construction variable.
3054 Examples (all of which produce the same result):
3057 dict = env.ParseFlags('-O2 -Dfoo -Dbar=1')
3058 dict = env.ParseFlags('-O2', '-Dfoo', '-Dbar=1')
3059 dict = env.ParseFlags(['-O2', '-Dfoo -Dbar=1'])
3060 dict = env.ParseFlags('-O2', '!echo -Dfoo -Dbar=1')
3063 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3066 A factory function that
3067 returns a Builder object
3068 to be used to fetch source files
3069 from the Perforce source code management system.
3070 The returned Builder
3071 is intended to be passed to the
3076 env.SourceCode('.', env.Perforce())
3079 Perforce uses a number of external
3080 environment variables for its operation.
3081 Consequently, this function adds the
3082 following variables from the user's external environment
3083 to the construction environment's
3096 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3098 .RI Platform( string )
3099 Returns a callable object
3100 that can be used to initialize
3101 a construction environment using the
3102 platform keyword of the Environment() method:
3105 env = Environment(platform = Platform('win32'))
3108 .RI env.Platform( string )
3109 Applies the callable object for the specified platform
3111 to the environment through which the method was called.
3114 env.Platform('posix')
3123 variables from the user's external environment
3124 to the construction environment's
3127 This is so that any executed commands
3128 that use sockets to connect with other systems
3129 (such as fetching source files from
3130 external CVS repository specifications like
3131 .BR :pserver:anonymous@cvs.sourceforge.net:/cvsroot/scons )
3132 will work on Windows systems.
3134 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3136 .RI Precious( target ", ...)"
3138 .RI env.Precious( target ", ...)"
3141 as precious so it is not deleted before it is rebuilt. Normally
3143 deletes a target before building it.
3144 Multiple targets can be passed in to a single call to
3147 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3149 .RI env.Prepend( key = val ", [...])"
3150 Appends the specified keyword arguments
3151 to the beginning of construction variables in the environment.
3152 If the Environment does not have
3153 the specified construction variable,
3154 it is simply added to the environment.
3155 If the values of the construction variable
3156 and the keyword argument are the same type,
3157 then the two values will be simply added together.
3158 Otherwise, the construction variable
3159 and the value of the keyword argument
3160 are both coerced to lists,
3161 and the lists are added together.
3162 (See also the Append method, above.)
3165 env.Prepend(CCFLAGS = '-g ', FOO = ['foo.yyy'])
3168 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3170 .RI env.PrependENVPath( name ", " newpath ", [" envname ", " sep ])
3171 This appends new path elements to the given path in the
3172 specified external environment
3176 any particular path once (leaving the first one it encounters and
3177 ignoring the rest, to preserve path order),
3178 and to help assure this,
3179 will normalize all paths (using
3182 .BR os.path.normcase ).
3183 This can also handle the
3184 case where the given old path variable is a list instead of a
3185 string, in which case a list will be returned instead of a string.
3189 print 'before:',env['ENV']['INCLUDE']
3190 include_path = '/foo/bar:/foo'
3191 env.PrependENVPath('INCLUDE', include_path)
3192 print 'after:',env['ENV']['INCLUDE']
3196 after: /foo/bar:/foo:/biz
3199 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3201 .RI env.PrependUnique( key = val ", [...])"
3202 Appends the specified keyword arguments
3203 to the beginning of construction variables in the environment.
3204 If the Environment does not have
3205 the specified construction variable,
3206 it is simply added to the environment.
3207 If the construction variable being appended to is a list,
3208 then any value(s) that already exist in the
3209 construction variable will
3211 be added again to the list.
3214 env.PrependUnique(CCFLAGS = '-g', FOO = ['foo.yyy'])
3217 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3220 A factory function that
3221 returns a Builder object
3222 to be used to fetch source files
3224 The returned Builder
3225 is intended to be passed to the
3230 env.SourceCode('.', env.RCS())
3235 will fetch source files
3236 from RCS subdirectories automatically,
3238 as demonstrated in the above example
3239 should only be necessary if
3240 you are fetching from
3243 directory as the source files,
3244 or if you need to explicitly specify RCS
3245 for a specific subdirectory.
3247 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3249 .RI env.Replace( key = val ", [...])"
3250 Replaces construction variables in the Environment
3251 with the specified keyword arguments.
3254 env.Replace(CCFLAGS = '-g', FOO = 'foo.xxx')
3257 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3259 .RI Repository( directory )
3261 .RI env.Repository( directory )
3264 is a repository to be searched for files.
3268 and each one adds to the list of
3269 repositories that will be searched.
3273 a repository is a copy of the source tree,
3274 from the top-level directory on down,
3276 both source files and derived files
3277 that can be used to build targets in
3278 the local source tree.
3279 The canonical example would be an
3280 official source tree maintained by an integrator.
3281 If the repository contains derived files,
3282 then the derived files should have been built using
3284 so that the repository contains the necessary
3285 signature information to allow
3287 to figure out when it is appropriate to
3288 use the repository copy of a derived file,
3289 instead of building one locally.
3291 Note that if an up-to-date derived file
3292 already exists in a repository,
3296 make a copy in the local directory tree.
3297 In order to guarantee that a local copy
3303 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3308 what variable(s) to use as the return value(s) of the current SConscript
3309 file. These variables will be returned to the "calling" SConscript file
3310 as the return value(s) of
3312 Multiple variable names should be passed to
3318 Return(["foo", "bar"])
3321 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3323 .RI Scanner( function ", [" argument ", " keys ", " path_function ", " node_class ", " node_factory ", " scan_check ", " recursive ])
3325 .RI env.Scanner( function ", [" argument ", " keys ", " path_function ", " node_class ", " node_factory ", " scan_check ", " recursive ])
3326 Creates a Scanner object for
3329 See the section "Scanner Objects,"
3330 below, for a complete explanation of the arguments and behavior.
3332 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3335 A factory function that
3336 returns a Builder object
3337 to be used to fetch source files
3339 The returned Builder
3340 is intended to be passed to the
3345 env.SourceCode('.', env.SCCS())
3350 will fetch source files
3351 from SCCS subdirectories automatically,
3353 as demonstrated in the above example
3354 should only be necessary if
3355 you are fetching from
3358 directory as the source files,
3359 or if you need to explicitly specify SCCS
3360 for a specific subdirectory.
3362 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3364 .RI SConscript( scripts ", [" exports ", " build_dir ", " src_dir ", " duplicate ])
3366 .RI env.SConscript( scripts ", [" exports ", " build_dir ", " src_dir ", " duplicate ])
3368 .RI SConscript(dirs= subdirs ", [name=" script ", " exports ", " build_dir ", " src_dir ", " duplicate ])
3370 .RI env.SConscript(dirs= subdirs ", [name=" script ", " exports ", " build_dir ", " src_dir ", " duplicate ])
3374 one or more subsidiary SConscript (configuration) files.
3375 There are two ways to call the
3379 The first way you can call
3381 is to explicitly specify one or more
3383 as the first argument.
3384 A single script may be specified as a string;
3385 multiple scripts must be specified as a list
3386 (either explicitly or as created by
3390 The second way you can call
3392 is to specify a list of (sub)directory names
3399 execute a subsidiary configuration file named
3401 in each of the specified directories.
3402 You may specify a name other than
3404 by supplying an optional
3410 argument provides a list of variable names or a dictionary of
3411 named values to export to the
3413 These variables are locally exported only to the specified
3415 and do not affect the
3416 global pool of variables used by
3420 '\"If multiple dirs are provided,
3421 '\"each script gets a fresh export.
3426 function to import the variables.
3430 argument specifies that all of the target files
3431 (for example, object files and executables)
3432 that would normally be built in the subdirectory in which
3434 resides should actually
3438 is interpreted relative to the directory
3439 of the calling SConscript file.
3443 argument specifies that the
3444 source files from which
3445 the target files should be built
3449 is interpreted relative to the directory
3450 of the calling SConscript file.
3454 will link or copy (depending on the platform)
3455 all the source files into the build directory.
3456 This behavior may be disabled by
3457 setting the optional
3460 (it is set to 1 by default),
3463 will refer directly to
3464 the source files in their source directory
3465 when building target files.
3468 is usually safe, and always more efficient
3471 but it may cause build problems in certain end-cases,
3472 such as compiling from source files that
3473 are generated by the build.)
3475 Any variables returned by
3479 will be returned by the call to
3485 SConscript('subdir/SConscript')
3486 foo = SConscript('sub/SConscript', exports='env')
3487 SConscript('dir/SConscript', exports=['env', 'variable'])
3488 SConscript('src/SConscript', build_dir='build', duplicate=0)
3489 SConscript('bld/SConscript', src_dir='src', exports='env variable')
3490 SConscript(dirs=['sub1', 'sub2'])
3491 SConscript(dirs=['sub3', 'sub4'], name='MySConscript')
3494 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3496 .RI SConscriptChdir( value )
3498 .RI env.SConscriptChdir( value )
3501 changes its working directory
3502 to the directory in which each
3503 subsidiary SConscript file lives.
3504 This behavior may be disabled
3505 by specifying either:
3509 env.SConscriptChdir(0)
3514 will stay in the top-level directory
3515 while reading all SConscript files.
3516 (This may be necessary when building from repositories,
3517 when all the directories in which SConscript files may be found
3518 don't necessarily exist locally.)
3520 You may enable and disable
3521 this ability by calling
3528 SConscript('foo/SConscript') # will not chdir to foo
3529 env.SConscriptChdir(1)
3530 SConscript('bar/SConscript') # will chdir to bar
3533 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3535 .RI SConsignFile([ file , dbm_module ])
3537 .RI env.SConsignFile([ file , dbm_module ])
3540 to store all file signatures
3541 in the specified database
3548 (The actual file name(s) stored on disk
3549 may have an appropriated suffix appended
3554 is not an absolute path name,
3555 the file is placed in the same directory as the top-level
3565 will store file signatures
3568 file in each directory,
3569 not in one global database file.
3570 (This was the default behavior
3571 prior to SCons 0.96.91 and 0.97.)
3575 argument can be used to specify
3576 which Python database module
3577 The default is to use a custom
3579 module that uses pickled
3580 Python data structures,
3581 and which works on all Python versions from 1.5.2 on.
3586 # Explicitly stores signatures in ".sconsign.dblite"
3587 # in the top-level SConstruct directory (the
3588 # default behavior).
3591 # Stores signatures in the file "etc/scons-signatures"
3592 # relative to the top-level SConstruct directory.
3593 SConsignFile("etc/scons-signatures")
3595 # Stores signatures in the specified absolute file name.
3596 SConsignFile("/home/me/SCons/signatures")
3598 # Stores signatures in a separate .sconsign file
3599 # in each directory.
3603 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3605 .RI env.SetDefault(key = val ", [...])"
3606 Sets construction variables to default values specified with the keyword
3607 arguments if (and only if) the variables are not already set.
3608 The following statements are equivalent:
3611 env.SetDefault(FOO = 'foo')
3613 if not env.has_key('FOO'): env['FOO'] = 'foo'
3616 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3618 .RI SetOption( name ", " value )
3620 .RI env.SetOption( name ", " value )
3621 This function provides a way to set a select subset of the scons command
3622 line options from a SConscript file. The options supported are:
3624 which corresponds to -c, --clean, and --remove;
3627 corresponds to --duplicate;
3629 which corresponds to --implicit-cache;
3631 which corresponds to --max-drift;
3633 which corresponds to -j and --jobs.
3634 See the documentation for the
3635 corresponding command line object for information about each specific
3639 SetOption('max_drift', 1)
3642 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3644 .RI SideEffect( side_effect ", " target )
3646 .RI env.SideEffect( side_effect ", " target )
3649 as a side effect of building
3655 can be a list, a file name, or a node.
3656 A side effect is a target that is created
3657 as a side effect of building other targets.
3658 For example, a Windows PDB
3659 file is created as a side effect of building the .obj
3660 files for a static library.
3661 If a target is a side effect of multiple build commands,
3663 will ensure that only one set of commands
3664 is executed at a time.
3665 Consequently, you only need to use this method
3666 for side-effect targets that are built as a result of
3667 multiple build commands.
3669 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3671 .RI SourceCode( entries ", " builder )
3673 .RI env.SourceCode( entries ", " builder )
3674 Arrange for non-existent source files to
3675 be fetched from a source code management system
3680 may be a Node, string or list of both,
3681 and may represent either individual
3682 source files or directories in which
3683 source files can be found.
3685 For any non-existent source files,
3687 will search up the directory tree
3697 will not use a builder to fetch
3698 source files for the specified
3702 builder has been specified
3703 for a directory higher up the tree.
3707 fetch files from SCCS or RCS subdirectories
3708 without explicit configuration.
3709 This takes some extra processing time
3710 to search for the necessary
3711 source code management files on disk.
3712 You can avoid these extra searches
3713 and speed up your build a little
3714 by disabling these searches as follows:
3717 env.SourceCode('.', None)
3721 Note that if the specified
3723 is one you create by hand,
3724 it must have an associated
3725 construction environment to use
3726 when fetching a source file.
3729 provides a set of canned factory
3730 functions that return appropriate
3731 Builders for various popular
3732 source code management systems.
3733 Canonical examples of invocation include:
3736 env.SourceCode('.', env.BitKeeper('/usr/local/BKsources'))
3737 env.SourceCode('src', env.CVS('/usr/local/CVSROOT'))
3738 env.SourceCode('/', env.RCS())
3739 env.SourceCode(['f1.c', 'f2.c'], env.SCCS())
3740 env.SourceCode('no_source.c', None)
3742 '\"env.SourceCode('.', env.Subversion('file:///usr/local/Subversion'))
3744 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3746 .RI env.subst( string ", [" raw ", " target ", " source ", " conv ])
3747 Performs construction variable interpolation
3748 on the specified string argument.
3751 leading or trailing white space will
3752 be removed from the result.
3753 and all sequences of white space
3754 will be compressed to a single space character.
3759 character sequences will be stripped from the returned string,
3762 argument may be set to
3764 if you want to preserve white space and
3769 argument may be set to
3771 if you want to strip
3772 all characters between
3778 (as is done for signature calculation).
3785 must be set to lists of
3786 target and source nodes, respectively,
3793 to be available for expansion.
3794 This is usually necessary if you are
3797 from within a Python function used
3801 all returned values are converted
3802 to their string representation.
3806 may specify a conversion function
3807 that will be used in place of
3809 For example, if you want Python objects
3810 (including SCons Nodes)
3811 to be returned as Python objects,
3812 you can use the Python
3814 idiom to pass in an unnamed function
3815 that simply returns its unconverted argument.
3818 print env.subst("The C compiler is: $CC")
3820 def compile(target, source, env):
3821 sourceDir = env.subst("${SOURCE.srcdir}",
3825 source_nodes = env.subst('$EXPAND_TO_NODELIST',
3829 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3831 '\".RI Subversion( repository ", " module )
3832 '\"A factory function that
3833 '\"returns a Builder object
3834 '\"to be used to fetch source files
3835 '\"from the specified Subversion
3837 '\"The returned Builder
3838 '\"is intended to be passed to the
3842 '\"The optional specified
3844 '\"will be added to the beginning
3845 '\"of all repository path names;
3846 '\"this can be used, in essence,
3847 '\"to strip initial directory names
3848 '\"from the repository path names,
3849 '\"so that you only have to
3850 '\"replicate part of the repository
3851 '\"directory hierarchy in your
3852 '\"local build directory:
3855 '\"# Will fetch foo/bar/src.c
3856 '\"# from /usr/local/Subversion/foo/bar/src.c.
3857 '\"env.SourceCode('.', env.Subversion('file:///usr/local/Subversion'))
3859 '\"# Will fetch bar/src.c
3860 '\"# from /usr/local/Subversion/foo/bar/src.c.
3861 '\"env.SourceCode('.', env.Subversion('file:///usr/local/Subversion', 'foo'))
3863 '\"# Will fetch src.c
3864 '\"# from /usr/local/Subversion/foo/bar/src.c.
3865 '\"env.SourceCode('.', env.Subversion('file:///usr/local/Subversion', 'foo/bar'))
3868 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3870 .RI SourceSignatures( type )
3872 .RI env.SourceSignatures( type )
3873 This function tells SCons what type of signature to use for source files:
3877 If the environment method is used,
3878 the specified type of source signature
3879 is only used when deciding whether targets
3880 built with that environment are up-to-date or must be rebuilt.
3881 If the global function is used,
3882 the specified type of source signature becomes the default
3883 used for all decisions
3884 about whether targets are up-to-date.
3886 "MD5" means the signature of a source file
3887 is the MD5 checksum of its contents.
3888 "timestamp" means the signature of a source file
3889 is its timestamp (modification time).
3890 There is no different between the two behaviors
3894 "MD5" signatures take longer to compute,
3895 but are more accurate than "timestamp" signatures.
3896 The default is "MD5".
3898 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3902 .RI env.Split( arg )
3903 Returns a list of file names or other objects.
3905 it will be split on strings of white-space characters
3907 making it easier to write long lists of file names.
3908 If arg is already a list,
3909 the list will be returned untouched.
3910 If arg is any other type of object,
3911 it will be returned as a list
3912 containing just the object.
3915 files = Split("f1.c f2.c f3.c")
3916 files = env.Split("f4.c f5.c f6.c")
3924 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3926 .RI TargetSignatures( type )
3928 .RI env.TargetSignatures( type )
3929 This function tells SCons what type of signatures to use
3934 If the environment method is used,
3935 the specified type of signature is only used
3936 for targets built with that environment.
3937 If the global function is used,
3938 the specified type of signature becomes the default
3939 used for all target files that
3940 don't have an explicit target signature type
3941 specified for their environments.
3943 "build" means the signature of a target file
3944 is made by concatenating all of the
3945 signatures of all its source files.
3946 "content" means the signature of a target
3947 file is an MD5 checksum of its contents.
3948 "build" signatures are usually faster to compute,
3949 but "content" signatures can prevent unnecessary rebuilds
3950 when a target file is rebuilt to the exact same contents
3951 as the previous build.
3952 The default is "build".
3954 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3956 .RI Tool( string [, toolpath ", " **kw ])
3957 Returns a callable object
3958 that can be used to initialize
3959 a construction environment using the
3960 tools keyword of the Environment() method.
3961 The object may be called with a construction
3962 environment as an argument,
3963 in which case the object will
3964 add the necessary variables
3965 to the construction environment
3966 and the name of the tool will be added to the
3968 construction variable.
3970 Additional keyword arguments are passed to the tool's
3975 env = Environment(tools = [ Tool('msvc') ])
3979 t(env) # adds 'msvc' to the TOOLS variable
3980 u = Tool('opengl', toolpath = ['tools'])
3981 u(env) # adds 'opengl' to the TOOLS variable
3984 .RI env.Tool( string [, toolpath ", " **kw ])
3985 Applies the callable object for the specified tool
3987 to the environment through which the method was called.
3989 Additional keyword arguments are passed to the tool's
3995 env.Tool('opengl', toolpath = ['build/tools'])
3998 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4002 .RI env.Value( value )
4003 Returns a Node object representing the specified Python value. Value
4004 nodes can be used as dependencies of targets. If the result of
4007 changes between SCons runs, any targets depending on
4009 will be rebuilt. When using timestamp source signatures, Value nodes'
4010 timestamps are equal to the system time when the node is created.
4013 def create(target, source, env):
4014 f = open(str(target[0]), 'wb')
4015 f.write('prefix=' + source[0].get_contents())
4017 prefix = ARGUMENTS.get('prefix', '/usr/local')
4019 env['BUILDERS']['Config'] = Builder(action = create)
4020 env.Config(target = 'package-config', source = Value(prefix))
4023 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4025 .RI WhereIs( program ", [" path ", " pathext ", " reject ])
4027 .RI env.WhereIs( program ", [" path ", " pathext ", " reject ])
4029 Searches for the specified executable
4031 returning the full path name to the program
4033 and returning None if not.
4034 Searches the specified
4036 the value of the calling environment's PATH
4037 (env['ENV']['PATH']),
4038 or the user's current external PATH
4039 (os.environ['PATH'])
4041 On Windows systems, searches for executable
4042 programs with any of the file extensions
4043 listed in the specified
4045 the calling environment's PATHEXT
4046 (env['ENV']['PATHEXT'])
4047 or the user's current PATHEXT
4048 (os.environ['PATHEXT'])
4056 .SS SConscript Variables
4057 In addition to the global functions and methods,
4059 supports a number of Python variables
4060 that can be used in SConscript files
4061 to affect how you want the build to be performed.
4062 These variables may be accessed from custom Python modules that you
4063 import into an SConscript file by adding the following
4064 to the Python module:
4067 from SCons.Script import *
4070 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4075 arguments specified on the command line.
4076 Each element in the list is a tuple
4078 .RI ( keyword , value )
4084 elements of the tuple
4086 subscripting for element
4090 of the tuple, respectively.
4093 print "first keyword, value =", ARGLIST[0][0], ARGLIST[0][1]
4094 print "second keyword, value =", ARGLIST[1][0], ARGLIST[1][1]
4095 third_tuple = ARGLIST[2]
4096 print "third keyword, value =", third_tuple[0], third_tuple[1]
4097 for key, value in ARGLIST:
4098 # process key and value
4101 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4104 A dictionary of all the
4106 arguments specified on the command line.
4107 The dictionary is not in order,
4108 and if a given keyword has
4109 more than one value assigned to it
4110 on the command line,
4111 the last (right-most) value is
4117 if ARGUMENTS.get('debug', 0):
4118 env = Environment(CCFLAGS = '-g')
4123 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4126 A list of the targets which
4128 will actually try to build,
4129 regardless of whether they were specified on
4130 the command line or via the
4133 The elements of this list may be strings
4135 nodes, so you should run the list through the Python
4137 function to make sure any Node path names
4138 are converted to strings.
4140 Because this list may be taken from the
4141 list of targets specified using the
4144 the contents of the list may change
4145 on each successive call to
4150 for additional information.
4153 if 'foo' in BUILD_TARGETS:
4154 print "Don't forget to test the `foo' program!"
4155 if 'special/program' in BUILD_TARGETS:
4156 SConscript('special')
4161 list only contains targets expected listed
4162 on the command line or via calls to the
4167 contain all dependent targets that will be built as
4168 a result of making the sure the explicitly-specified
4169 targets are up to date.
4171 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4173 COMMAND_LINE_TARGETS
4174 A list of the targets explicitly specified on
4176 If there are no targets specified on the command line,
4178 This can be used, for example,
4179 to take specific actions only
4180 when a certain target or targets
4181 is explicitly being built:
4184 if 'foo' in COMMAND_LINE_TARGETS:
4185 print "Don't forget to test the `foo' program!"
4186 if 'special/program' in COMMAND_LINE_TARGETS:
4187 SConscript('special')
4190 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4193 A list of the target
4195 that have been specified using the
4198 The elements of the list are nodes,
4199 so you need to run them through the Python
4201 function to get at the path name for each Node.
4204 print str(DEFAULT_TARGETS[0])
4205 if 'foo' in map(str, DEFAULT_TARGETS):
4206 print "Don't forget to test the `foo' program!"
4211 list change on on each successive call to the
4216 print map(str, DEFAULT_TARGETS) # originally []
4218 print map(str, DEFAULT_TARGETS) # now a node ['foo']
4220 print map(str, DEFAULT_TARGETS) # now a node ['foo', 'bar']
4222 print map(str, DEFAULT_TARGETS) # back to []
4225 Consequently, be sure to use
4227 only after you've made all of your
4230 or else simply be careful of the order
4231 of these statements in your SConscript files
4232 so that you don't look for a specific
4233 default target before it's actually been added to the list.
4235 .SS Construction Variables
4236 .\" XXX From Gary Ruben, 23 April 2002:
4237 .\" I think it would be good to have an example with each construction
4238 .\" variable description in the documentation.
4240 .\" CC The C compiler
4241 .\" Example: env["CC"] = "c68x"
4242 .\" Default: env["CC"] = "cc"
4244 .\" CCCOM The command line ...
4246 .\" To generate the compiler line c68x -ps -qq -mr -o $TARGET $SOURCES
4247 .\" env["CC"] = "c68x"
4248 .\" env["CFLAGS"] = "-ps -qq -mr"
4249 .\" env["CCCOM"] = "$CC $CFLAGS -o $TARGET $SOURCES
4251 .\" (I dunno what this is ;-)
4252 A construction environment has an associated dictionary of
4253 .I construction variables
4254 that are used by built-in or user-supplied build rules.
4255 Construction variables must follow the same rules for
4257 the initial character must be an underscore or letter,
4258 followed by any number of underscores, letters, or digits.
4260 A number of useful construction variables are automatically defined by
4261 scons for each supported platform, and additional construction variables
4262 can be defined by the user. The following is a list of the automatically
4263 defined construction variables:
4265 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4266 '\" BEGIN GENERATED CONSTRUCTION VARIABLE DESCRIPTIONS
4268 '\" The descriptions below of the various SCons contruction variables
4269 '\" are generated from the .xml files that live next to the various
4270 '\" Python modules in the build enginer library. If you're reading
4271 '\" this [gnt]roff file with an eye towards patching this man page,
4272 '\" you can still submit a diff against this text, but it will have to
4273 '\" be translated to a diff against the underlying .xml file before the
4274 '\" patch is actually accepted. If you do that yourself, it will make
4275 '\" it easier to integrate the patch.
4277 '\" BEGIN GENERATED CONSTRUCTION VARIABLE DESCRIPTIONS
4278 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4280 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4281 '\" END GENERATED CONSTRUCTION VARIABLE DESCRIPTIONS
4283 '\" The descriptions above of the various SCons contruction variables
4284 '\" are generated from the .xml files that live next to the various
4285 '\" Python modules in the build enginer library. If you're reading
4286 '\" this [gnt]roff file with an eye towards patching this man page,
4287 '\" you can still submit a diff against this text, but it will have to
4288 '\" be translated to a diff against the underlying .xml file before the
4289 '\" patch is actually accepted. If you do that yourself, it will make
4290 '\" it easier to integrate the patch.
4292 '\" END GENERATED CONSTRUCTION VARIABLE DESCRIPTIONS
4293 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4296 Construction variables can be retrieved and set using the
4298 method of the construction environment:
4301 dict = env.Dictionary()
4305 or using the [] operator:
4311 Construction variables can also be passed to the construction environment
4315 env = Environment(CC="cc")
4318 or when copying a construction environment using the
4323 env2 = env.Copy(CC="cl.exe")
4326 .SS Configure Contexts
4330 .I configure contexts,
4331 an integrated mechanism similar to the
4332 various AC_CHECK macros in GNU autoconf
4333 for testing for the existence of C header
4334 files, libraries, etc.
4335 In contrast to autoconf,
4337 does not maintain an explicit cache of the tested values,
4338 but uses its normal dependency tracking to keep the checked values
4339 up to date. However, users may override this behaviour with the
4341 command line option.
4343 The following methods can be used to perform checks:
4346 .RI Configure( env ", [" custom_tests ", " conf_dir ", " log_file ", " config_h ])
4348 .RI env.Configure([ custom_tests ", " conf_dir ", " log_file ", " config_h ])
4349 This creates a configure context, which can be used to perform checks.
4351 specifies the environment for building the tests.
4352 This environment may be modified when performing checks.
4354 is a dictionary containing custom tests.
4355 See also the section about custom tests below.
4356 By default, no custom tests are added to the configure context.
4358 specifies a directory where the test cases are built.
4359 Note that this directory is not used for building
4361 The default value is the directory
4364 specifies a file which collects the output from commands
4365 that are executed to check for the existence of header files, libraries, etc.
4366 The default is the file #/config.log.
4367 If you are using the
4370 you may want to specify a subdirectory under your build directory.
4372 specifies a C header file where the results of tests
4373 will be written, e.g. #define HAVE_STDIO_H, #define HAVE_LIBM, etc.
4374 The default is to not write a
4377 You can specify the same
4379 file in multiple calls to Configure,
4382 will concatenate all results in the specified file.
4384 uses its normal dependency checking
4385 to decide if it's necessary to rebuild
4389 This means that the file is not necessarily re-built each
4391 but is only rebuilt if its contents will have changed
4392 and some target that depends on the
4394 file is being built.
4399 instance has the following associated methods:
4402 .RI Configure.Finish( self )
4403 This method should be called after configuration is done.
4404 It returns the environment as modified
4405 by the configuration checks performed.
4406 After this method is called, no further checks can be performed
4407 with this configuration context.
4408 However, you can create a new
4410 context to perform additional checks.
4411 Only one context should be active at a time.
4413 The following Checks are predefined.
4414 (This list will likely grow larger as time
4415 goes by and developers contribute new useful tests.)
4418 .RI Configure.CheckHeader( self ", " header ", [" include_quotes ", " language ])
4421 is usable in the specified language.
4424 in which case the last item in the list
4425 is the header file to be checked,
4426 and the previous list items are
4429 lines should precede the
4430 header line being checked for.
4431 The optional argument
4434 a two character string, where the first character denotes the opening
4435 quote and the second character denotes the closing quote.
4436 By default, both characters are " (double quote).
4437 The optional argument
4443 and selects the compiler to be used for the check.
4444 Returns 1 on success and 0 on failure.
4447 .RI Configure.CheckCHeader( self ", " header ", [" include_quotes ])
4448 This is a wrapper around
4449 .B Configure.CheckHeader
4452 is usable in the C language.
4455 in which case the last item in the list
4456 is the header file to be checked,
4457 and the previous list items are
4460 lines should precede the
4461 header line being checked for.
4462 The optional argument
4465 a two character string, where the first character denotes the opening
4466 quote and the second character denotes the closing quote (both default
4468 Returns 1 on success and 0 on failure.
4471 .RI Configure.CheckCXXHeader( self ", " header ", [" include_quotes ])
4472 This is a wrapper around
4473 .B Configure.CheckHeader
4476 is usable in the C++ language.
4479 in which case the last item in the list
4480 is the header file to be checked,
4481 and the previous list items are
4484 lines should precede the
4485 header line being checked for.
4486 The optional argument
4489 a two character string, where the first character denotes the opening
4490 quote and the second character denotes the closing quote (both default
4492 Returns 1 on success and 0 on failure.
4495 .RI Configure.CheckFunc( self ", " function_name ", [" header ", " language ])
4496 Checks if the specified
4497 C or C++ function is available.
4499 is the name of the function to check for.
4502 argument is a string
4506 that will be compiled
4507 to check if the function exists;
4513 char function_name();
4521 and selects the compiler to be used for the check;
4525 .RI Configure.CheckLib( self ", [" library ", " symbol ", " header ", " language ", " autoadd=1 ])
4532 is 1 and the library provides the specified
4534 appends the library to the LIBS construction environment variable.
4536 may also be None (the default),
4539 is checked with the current LIBS variable,
4540 or a list of library names,
4541 in which case each library in the list
4549 .BR Configure.CheckLib ()
4551 you can link against the specified
4559 and selects the compiler to be used for the check;
4561 The default value for
4564 This method returns 1 on success and 0 on error.
4567 .RI Configure.CheckLibWithHeader( self ", " library ", " header ", " language ", [" call ", " autoadd ])
4570 .RI Configure.CheckLib
4571 call, this call provides a more sophisticated way to check against libraries.
4574 specifies the library or a list of libraries to check.
4576 specifies a header to check for.
4579 in which case the last item in the list
4580 is the header file to be checked,
4581 and the previous list items are
4584 lines should precede the
4585 header line being checked for.
4587 may be one of 'C','c','CXX','cxx','C++' and 'c++'.
4589 can be any valid expression (with a trailing ';').
4593 the default simply checks that you
4594 can link against the specified
4597 specifies whether to add the library to the environment (only if the check
4598 succeeds). This method returns 1 on success and 0 on error.
4601 .RI Configure.CheckType( self ", " type_name ", [" includes ", " language ])
4602 Checks for the existence of a type defined by
4605 specifies the typedef name to check for.
4607 is a string containing one or more
4609 lines that will be inserted into the program
4610 that will be run to test for the existence of the type.
4617 and selects the compiler to be used for the check;
4621 Example of a typical Configure usage:
4625 conf = Configure( env )
4626 if not conf.CheckCHeader( 'math.h' ):
4627 print 'We really need math.h!'
4629 if conf.CheckLibWithHeader( 'qt', 'qapp.h', 'c++', 'QApplication qapp(0,0);' ):
4630 # do stuff for qt - usage, e.g.
4631 conf.env.Append( CPPFLAGS = '-DWITH_QT' )
4636 You can define your own custom checks.
4637 in addition to the predefined checks.
4638 These are passed in a dictionary to the Configure function.
4639 This dictionary maps the names of the checks
4640 to user defined Python callables
4641 (either Python functions or class instances implementing the
4644 The first argument of the call is always a
4646 instance followed by the arguments,
4647 which must be supplied by the user of the check.
4648 These CheckContext instances define the following methods:
4651 .RI CheckContext.Message( self ", " text )
4653 Usually called before the check is started.
4655 will be displayed to the user, e.g. 'Checking for library X...'
4658 .RI CheckContext.Result( self, ", " res )
4660 Usually called after the check is done.
4662 can be either an integer or a string. In the former case, 'ok' (res != 0)
4663 or 'failed' (res == 0) is displayed to the user, in the latter case the
4664 given string is displayed.
4667 .RI CheckContext.TryCompile( self ", " text ", " extension )
4668 Checks if a file with the specified
4670 (e.g. '.c') containing
4672 can be compiled using the environment's
4674 builder. Returns 1 on success and 0 on failure.
4677 .RI CheckContext.TryLink( self ", " text ", " extension )
4678 Checks, if a file with the specified
4680 (e.g. '.c') containing
4682 can be compiled using the environment's
4684 builder. Returns 1 on success and 0 on failure.
4687 .RI CheckContext.TryRun( self ", " text ", " extension )
4688 Checks, if a file with the specified
4690 (e.g. '.c') containing
4692 can be compiled using the environment's
4694 builder. On success, the program is run. If the program
4695 executes successfully
4696 (that is, its return status is 0),
4701 is the standard output of the
4703 If the program fails execution
4704 (its return status is non-zero),
4705 then (0, '') is returned.
4708 .RI CheckContext.TryAction( self ", " action ", [" text ", " extension ])
4709 Checks if the specified
4711 with an optional source file (contents
4718 may be anything which can be converted to a
4725 is the content of the target file.
4731 .RI CheckContext.TryBuild( self ", " builder ", [" text ", " extension ])
4732 Low level implementation for testing specific builds;
4733 the methods above are based on this method.
4734 Given the Builder instance
4738 of a source file with optional
4740 this method returns 1 on success and 0 on failure. In addition,
4742 is set to the build target node, if the build was successful.
4745 Example for implementing and using custom tests:
4748 def CheckQt(context, qtdir):
4749 context.Message( 'Checking for qt ...' )
4750 lastLIBS = context.env['LIBS']
4751 lastLIBPATH = context.env['LIBPATH']
4752 lastCPPPATH= context.env['CPPPATH']
4753 context.env.Append(LIBS = 'qt', LIBPATH = qtdir + '/lib', CPPPATH = qtdir + '/include' )
4754 ret = context.TryLink("""
4756 int main(int argc, char **argv) {
4757 QApplication qapp(argc, argv);
4762 context.env.Replace(LIBS = lastLIBS, LIBPATH=lastLIBPATH, CPPPATH=lastCPPPATH)
4763 context.Result( ret )
4767 conf = Configure( env, custom_tests = { 'CheckQt' : CheckQt } )
4768 if not conf.CheckQt('/usr/lib/qt'):
4769 print 'We really need qt!'
4774 .SS Construction Variable Options
4776 Often when building software, various options need to be specified at build
4777 time that are not known when the SConstruct/SConscript files are
4778 written. For example, libraries needed for the build may be in non-standard
4779 locations, or site-specific compiler options may need to be passed to the
4782 provides a mechanism for overridding construction variables from the
4783 command line or a text-based SConscript file through an Options
4784 object. To create an Options object, call the Options() function:
4787 .RI Options([ files "], [" args ])
4788 This creates an Options object that will read construction variables from
4789 the file or list of filenames specified in
4791 If no files are specified,
4796 then no files will be read.
4797 The optional argument
4800 values that will override anything read from the specified files;
4801 it is primarily intended to be passed the
4803 dictionary that holds variables
4804 specified on the command line.
4808 opts = Options('custom.py')
4809 opts = Options('overrides.py', ARGUMENTS)
4810 opts = Options(None, {FOO:'expansion', BAR:7})
4813 Options objects have the following methods:
4816 .RI Add( key ", [" help ", " default ", " validator ", " converter ])
4817 This adds a customizable construction variable to the Options object.
4819 is the name of the variable.
4821 is the help text for the variable.
4823 is the default value of the variable;
4824 if the default value is
4826 and there is no explicit value specified,
4827 the construction variable will
4829 be added to the construction environment.
4831 is called to validate the value of the variable, and should take three
4832 arguments: key, value, and environment.
4833 The recommended way to handle an invalid value is
4834 to raise an exception (see example below).
4836 is called to convert the value before putting it in the environment, and
4837 should take a single argument: value.
4840 must return a value,
4841 which will be converted into a string
4842 before being validated by the
4845 and then added to the environment.
4850 opts.Add('CC', 'The C compiler')
4852 def validate_color(key, val, env):
4853 if not val in ['red', 'blue', 'yellow']:
4854 raise "Invalid color value '%s'" % val
4855 opts.Add('COLOR', validator=valid_color)
4859 .RI AddOptions( list )
4860 A wrapper script that adds
4861 multiple customizable construction variables
4862 to an Options object.
4864 is a list of tuple or list objects
4865 that contain the arguments
4866 for an individual call to the
4873 ('CC', 'The C compiler'),
4874 ('VALIDATE', 'An option for testing validation',
4875 'notset', validator, None),
4880 .RI Update( env ", [" args ])
4881 This updates a construction environment
4883 with the customized construction variables. Normally this method is not
4884 called directly, but is called indirectly by passing the Options object to
4885 the Environment() function:
4888 env = Environment(options=opts)
4892 The text file(s) that were specified
4893 when the Options object was created
4894 are executed as Python scripts,
4895 and the values of (global) Python variables set in the file
4896 are added to the construction environment.
4904 .RI Save( filename ", " env )
4905 This saves the currently set options into a script file named
4907 that can be used on the next invocation to automatically load the current
4908 settings. This method combined with the Options method can be used to
4909 support caching of options between runs.
4913 opts = Options(['options.cache', 'custom.py'])
4916 opts.Save('options.cache', env)
4920 .RI GenerateHelpText( env ", [" sort ])
4921 This generates help text documenting the customizable construction
4922 variables suitable to passing in to the Help() function.
4924 is the construction environment that will be used to get the actual values
4925 of customizable variables. Calling with
4929 will cause the output to be sorted
4930 by the specified argument.
4934 should take two arguments
4937 (like the standard Python
4942 Help(opts.GenerateHelpText(env))
4943 Help(opts.GenerateHelpText(env, sort=cmp))
4947 .RI FormatOptionHelpText( env ", " opt ", " help ", " default ", " actual )
4948 This method returns a formatted string
4949 containing the printable help text
4951 It is normally not called directly,
4952 but is called by the
4953 .IR GenerateHelpText ()
4954 method to create the returned help text.
4955 It may be overridden with your own
4956 function that takes the arguments specified above
4957 and returns a string of help text formatted to your liking.
4959 .IR GenerateHelpText ()
4960 will not put any blank lines or extra
4961 characters in between the entries,
4962 so you must add those characters to the returned
4963 string if you want the entries separated.
4966 def my_format(env, opt, help, default, actual):
4967 fmt = "\n%s: default=%s actual=%s (%s)\n"
4968 return fmt % (opt, default. actual, help)
4969 opts.FormatOptionHelpText = my_format
4972 To make it more convenient to work with customizable Options,
4974 provides a number of functions
4975 that make it easy to set up
4976 various types of Options:
4979 .RI BoolOption( key ", " help ", " default )
4980 Return a tuple of arguments
4981 to set up a Boolean option.
4985 have a default value of
4987 and display the specified
4990 The option will interpret the values
5012 .RI EnumOption( key ", " help ", " default ", " allowed_values ", [" map ", " ignorecase ])
5013 Return a tuple of arguments
5015 whose value may be one
5016 of a specified list of legal enumerated values.
5020 have a default value of
5022 and display the specified
5025 The option will only support those
5031 argument is a dictionary
5032 that can be used to convert
5033 input values into specific legal values
5042 then the values are case-sensitive.
5047 then values will be matched
5053 then values will be matched
5055 and all input values will be
5056 converted to lower case.
5059 .RI ListOption( key ", " help ", " default ", " names ", [", map ])
5060 Return a tuple of arguments
5062 whose value may be one or more
5063 of a specified list of legal enumerated values.
5067 have a default value of
5069 and display the specified
5072 The option will only support the values
5075 or the values in the
5078 More than one value may be specified,
5079 with all values separated by commas.
5080 The default may be a string of
5081 comma-separated default values,
5082 or a list of the default values.
5085 argument is a dictionary
5086 that can be used to convert
5087 input values into specific legal values
5093 .RI PackageOption( key ", " help ", " default )
5094 Return a tuple of arguments
5096 whose value is a path name
5097 of a package that may be
5098 enabled, disabled or
5099 given an explicit path name.
5103 have a default value of
5105 and display the specified
5108 The option will support the values
5115 in which case the specified
5118 or the option may be set to an
5120 (typically the path name to a package
5121 that is being enabled).
5122 The option will also support the values
5128 to disable use of the specified option.
5131 .RI PathOption( key ", " help ", " default ", [" validator ])
5132 Return a tuple of arguments
5134 whose value is expected to be a path name.
5138 have a default value of
5140 and display the specified
5146 that will be called to
5147 verify that the specified path
5150 following ready-made validators:
5151 .BR PathOption.PathExists
5153 which verifies that the specified path exists;
5154 .BR PathOption.PathIsFile ,
5155 which verifies that the specified path is an existing file;
5156 .BR PathOption.PathIsDir ,
5157 which verifies that the specified path is an existing directory;
5159 .BR PathOption.PathIsDirCreate ,
5160 which verifies that the specified path is a directory,
5161 and will create the specified directory if the path does not exist.
5162 You may supply your own
5165 which must take three arguments
5167 the name of the options variable to be set;
5169 the specified value being checked;
5172 the construction environment)
5173 and should raise an exception
5174 if the specified value is not acceptable.
5177 These functions make it
5178 convenient to create a number
5179 of options with consistent behavior
5180 in a single call to the
5186 BoolOption('warnings', 'compilation with -Wall and similiar', 1),
5187 EnumOption('debug', 'debug output and symbols', 'no'
5188 allowed_values=('yes', 'no', 'full'),
5189 map={}, ignorecase=0), # case sensitive
5190 ListOption('shared',
5191 'libraries to build as shared libraries',
5193 names = list_of_libs),
5194 PackageOption('x11',
5195 'use X11 installed here (yes = search some places)',
5197 PathOption('qtdir', 'where the root of Qt is installed', qtdir),
5198 PathOption('foopath', 'where the foo library is installed', foopath,
5199 PathOption.PathIsDir),
5204 .SS File and Directory Nodes
5214 Nodes, respectively.
5215 python objects, respectively.
5216 Those objects have several user-visible attributes
5217 and methods that are often useful:
5223 This path is relative to the top-level directory
5227 The build path is the same as the source path if
5232 The absolute build path of the given file or directory.
5242 object representing the
5251 # Get the current build dir's path, relative to top.
5253 # Current dir's absolute path
5255 # Next line is always '.', because it is the top dir's path relative to itself.
5257 File('foo.c').srcnode().path # source path of the given source file.
5259 # Builders also return File objects:
5260 foo = env.Program('foo.c')
5261 print "foo will be built in %s"%foo.path
5267 can be extended to build different types of targets
5268 by adding new Builder objects
5269 to a construction environment.
5271 you should only need to add a new Builder object
5272 when you want to build a new type of file or other external target.
5273 If you just want to invoke a different compiler or other tool
5274 to build a Program, Object, Library, or any other
5275 type of output file for which
5277 already has an existing Builder,
5278 it is generally much easier to
5279 use those existing Builders
5280 in a construction environment
5281 that sets the appropriate construction variables
5284 Builder objects are created
5290 function accepts the following arguments:
5293 The command line string used to build the target from the source.
5296 a list of strings representing the command
5297 to be executed and its arguments
5298 (suitable for enclosing white space in an argument),
5300 mapping source file name suffixes to
5301 any combination of command line strings
5302 (if the builder should accept multiple source file extensions),
5305 (see the next section);
5306 or a list of any of the above.
5309 takes three arguments:
5311 - a list of source nodes,
5313 - a list of target nodes,
5315 - the construction environment.
5318 The prefix that will be prepended to the target file name.
5319 This may be specified as a:
5329 - a function or other callable that takes
5330 two arguments (a construction environment and a list of sources)
5331 and returns a prefix,
5336 - specifies a mapping from a specific source suffix (of the first
5337 source specified) to a corresponding target prefix. Both the source
5338 suffix and target prefix specifications may use environment variable
5339 substitution, and the target prefix (the 'value' entries in the
5340 dictionary) may also be a callable object. The default target prefix
5341 may be indicated by a dictionary entry with a key value of None.
5346 b = Builder("build_it < $SOURCE > $TARGET"
5349 def gen_prefix(env, sources):
5350 return "file-" + env['PLATFORM'] + '-'
5351 b = Builder("build_it < $SOURCE > $TARGET",
5352 prefix = gen_prefix)
5354 b = Builder("build_it < $SOURCE > $TARGET",
5355 suffix = { None: "file-",
5356 "$SRC_SFX_A": gen_prefix })
5360 The suffix that will be appended to the target file name.
5361 This may be specified in the same manner as the prefix above.
5362 If the suffix is a string, then
5364 will append a '.' to the beginning of the suffix if it's not already
5365 there. The string returned by callable object (or obtained from the
5366 dictionary) is untouched and must append its own '.' to the beginning
5370 b = Builder("build_it < $SOURCE > $TARGET"
5373 def gen_suffix(env, sources):
5374 return "." + env['PLATFORM'] + "-file"
5375 b = Builder("build_it < $SOURCE > $TARGET",
5376 suffix = gen_suffix)
5378 b = Builder("build_it < $SOURCE > $TARGET",
5379 suffix = { None: ".sfx1",
5380 "$SRC_SFX_A": gen_suffix })
5384 The expected source file name suffix. This may be a string or a list
5388 A Scanner object that
5389 will be invoked to find
5390 implicit dependencies for this target file.
5391 This keyword argument should be used
5392 for Scanner objects that find
5393 implicit dependencies
5394 based only on the target file
5395 and the construction environment,
5398 (See the section "Scanner Objects," below,
5399 for information about creating Scanner objects.)
5402 A Scanner object that
5404 find implicit dependences in
5406 used to build this target file.
5407 This is where you would
5408 specify a scanner to
5411 lines in source files.
5414 Scanner object may be used to
5415 indicate that this Builder
5416 should scan directory trees
5417 for on-disk changes to files
5420 does not know about from other Builder or function calls.
5421 (See the section "Scanner Objects," below,
5422 for information about creating your own Scanner objects.)
5425 A factory function that the Builder will use
5426 to turn any targets specified as strings into SCons Nodes.
5428 SCons assumes that all targets are files.
5429 Other useful target_factory
5432 for when a Builder creates a directory target,
5435 for when a Builder can create either a file
5436 or directory target.
5441 MakeDirectoryBuilder = Builder(action=my_mkdir, target_factory=Dir)
5443 env.Append(BUILDERS = {'MakeDirectory':MakeDirectoryBuilder})
5444 env.MakeDirectory('new_directory', [])
5447 Note that the call to the MakeDirectory Builder
5448 needs to specify an empty source list
5449 to make the string represent the builder's target;
5450 without that, it would assume the argument is the source,
5451 and would try to deduce the target name from it,
5452 which in the absence of an automatically-added prefix or suffix
5453 would lead to a matching target and source name
5454 and a circular dependency.
5457 A factory function that the Builder will use
5458 to turn any sources specified as strings into SCons Nodes.
5460 SCons assumes that all source are files.
5461 Other useful source_factory
5464 for when a Builder uses a directory as a source,
5467 for when a Builder can use files
5468 or directories (or both) as sources.
5473 CollectBuilder = Builder(action=my_mkdir, source_factory=Entry)
5475 env.Append(BUILDERS = {'Collect':CollectBuilder})
5476 env.Collect('archive', ['directory_name', 'file_name'])
5480 A function or list of functions to manipulate the target and source
5481 lists before dependencies are established
5482 and the target(s) are actually built.
5484 can also be a string containing a construction variable to expand
5485 to an emitter function or list of functions,
5486 or a dictionary mapping source file suffixes
5487 to emitter functions.
5488 (Only the suffix of the first source file
5489 is used to select the actual emitter function
5490 from an emitter dictionary.)
5493 takes three arguments:
5495 - a list of source nodes,
5497 - a list of target nodes,
5499 - the construction environment.
5500 An emitter must return a tuple containing two lists,
5501 the list of targets to be built by this builder,
5502 and the list of sources for this builder.
5507 def e(target, source, env):
5508 return (target + ['foo.foo'], source + ['foo.src'])
5510 # Simple association of an emitter function with a Builder.
5511 b = Builder("my_build < $TARGET > $SOURCE",
5514 def e2(target, source, env):
5515 return (target + ['bar.foo'], source + ['bar.src'])
5517 # Simple association of a list of emitter functions with a Builder.
5518 b = Builder("my_build < $TARGET > $SOURCE",
5521 # Calling an emitter function through a construction variable.
5522 env = Environment(MY_EMITTER = e)
5523 b = Builder("my_build < $TARGET > $SOURCE",
5524 emitter = '$MY_EMITTER')
5526 # Calling a list of emitter functions through a construction variable.
5527 env = Environment(EMITTER_LIST = [e, e2])
5528 b = Builder("my_build < $TARGET > $SOURCE",
5529 emitter = '$EMITTER_LIST')
5531 # Associating multiple emitters with different file
5532 # suffixes using a dictionary.
5533 def e_suf1(target, source, env):
5534 return (target + ['another_target_file'], source)
5535 def e_suf2(target, source, env):
5536 return (target, source + ['another_source_file'])
5537 b = Builder("my_build < $TARGET > $SOURCE",
5538 emitter = {'.suf1' : e_suf1,
5543 Specifies whether this builder is allowed to be called multiple times for
5544 the same target file(s). The default is 0, which means the builder
5545 can not be called multiple times for the same target file(s). Calling a
5546 builder multiple times for the same target simply adds additional source
5547 files to the target; it is not allowed to change the environment associated
5548 with the target, specify addition environment overrides, or associate a different
5549 builder with the target.
5552 A construction environment that can be used
5553 to fetch source code using this Builder.
5554 (Note that this environment is
5556 used for normal builds of normal target files,
5557 which use the environment that was
5558 used to call the Builder for the target file.)
5561 A function that returns a list of actions that will be executed to build
5562 the target(s) from the source(s).
5563 The returned action(s) may be
5564 an Action object, or anything that
5565 can be converted into an Action object
5566 (see the next section).
5568 The generator function
5569 takes four arguments:
5571 - a list of source nodes,
5573 - a list of target nodes,
5575 - the construction environment,
5577 - a Boolean value that specifies
5578 whether the generator is being called
5579 for generating a build signature
5580 (as opposed to actually executing the command).
5584 def g(source, target, env, for_signature):
5585 return [["gcc", "-c", "-o"] + target + source]
5587 b = Builder(generator=g)
5595 arguments must not both be used for the same Builder.
5598 Specifies a builder to use when a source file name suffix does not match
5599 any of the suffixes of the builder. Using this argument produces a
5600 multi-stage builder.
5603 Specifies that this builder expects exactly one source file per call. Giving
5604 more than one source files without target files results in implicitely calling
5605 the builder multiple times (once for each source given). Giving multiple
5606 source files together with target files results in a UserError exception.
5614 arguments must not both be used for the same Builder.
5616 .IP source_ext_match
5619 argument is a dictionary,
5620 the default behavior when a builder is passed
5621 multiple source files is to make sure that the
5622 extensions of all the source files match.
5623 If it is legal for this builder to be
5624 called with a list of source files with different extensions,
5625 this check can be suppressed by setting
5629 or some other non-true value.
5634 will use the suffix of the first specified
5635 source file to select the appropriate action from the
5639 In the following example,
5644 from exiting with an error
5645 due to the mismatched suffixes of
5651 b = Builder(action={'.in' : 'build $SOURCES > $TARGET'},
5652 source_ext_match = None)
5654 env = Environment(BUILDERS = {'MyBuild':b})
5655 env.MyBuild('foo.out', ['foo.in', 'foo.extra'])
5659 A construction environment that can be used
5660 to fetch source code using this Builder.
5661 (Note that this environment is
5663 used for normal builds of normal target files,
5664 which use the environment that was
5665 used to call the Builder for the target file.)
5668 b = Builder(action="build < $SOURCE > $TARGET")
5669 env = Environment(BUILDERS = {'MyBuild' : b})
5670 env.MyBuild('foo.out', 'foo.in', my_arg = 'xyzzy')
5674 A directory from which scons
5681 a string or a directory Node,
5682 scons will change to the specified directory.
5685 is not a string or Node
5687 then scons will change to the
5688 target file's directory.
5690 Note that scons will
5692 automatically modify
5694 construction variables like
5698 when using the chdir
5699 keyword argument--that is,
5700 the expanded file names
5701 will still be relative to
5702 the top-level SConstruct directory,
5703 and consequently incorrect
5704 relative to the chdir directory.
5705 Builders created using chdir keyword argument,
5706 will need to use construction variable
5711 to use just the filename portion of the
5715 b = Builder(action="build < ${SOURCE.file} > ${TARGET.file}",
5717 env = Environment(BUILDERS = {'MyBuild' : b})
5718 env.MyBuild('sub/dir/foo.out', 'sub/dir/foo.in')
5722 Python only keeps one current directory
5723 location for all of the threads.
5724 This means that use of the
5732 because individual worker threads spawned
5733 by SCons interfere with each other
5734 when they start changing directory.
5737 Any additional keyword arguments supplied
5738 when a Builder object is created
5739 (that is, when the Builder() function is called)
5740 will be set in the executing construction
5741 environment when the Builder object is called.
5742 The canonical example here would be
5743 to set a construction variable to
5744 the repository of a source code system.
5746 Any additional keyword arguments supplied
5750 will only be associated with the target
5751 created by that particular Builder call
5752 (and any other files built as a
5753 result of the call).
5755 These extra keyword arguments are passed to the
5756 following functions:
5757 command generator functions,
5759 and emitter functions.
5765 function will turn its
5767 keyword argument into an appropriate
5768 internal Action object.
5769 You can also explicity create Action objects
5773 which can then be passed to the
5776 This can be used to configure
5777 an Action object more flexibly,
5778 or it may simply be more efficient
5779 than letting each separate Builder object
5780 create a separate Action
5782 Builder objects need to do the same thing.
5787 returns an appropriate object for the action
5788 represented by the type of the first argument:
5791 If the first argument is already an Action object,
5792 the object is simply returned.
5795 If the first argument is a string,
5796 a command-line Action is returned.
5797 Note that the command line string
5798 may be preceded by an
5801 to suppress printing of the
5802 specified command line,
5806 to ignore the exit status from
5807 the specified command.
5811 Action('$CC -c -o $TARGET $SOURCES')
5813 # Doesn't print the line being executed.
5814 Action('@build $TARGET $SOURCES')
5817 Action('-build $TARGET $SOURCES')
5820 .\" XXX From Gary Ruben, 23 April 2002:
5821 .\" What would be useful is a discussion of how you execute command
5822 .\" shell commands ie. what is the process used to spawn the shell, pass
5823 .\" environment variables to it etc., whether there is one shell per
5824 .\" environment or one per command etc. It might help to look at the Gnu
5825 .\" make documentation to see what they think is important to discuss about
5826 .\" a build system. I'm sure you can do a better job of organising the
5827 .\" documentation than they have :-)
5831 If the first argument is a list,
5832 then a list of Action objects is returned.
5833 An Action object is created as necessary
5834 for each element in the list.
5837 the list is itself a list,
5838 the internal list is the
5839 command and arguments to be executed via
5841 This allows white space to be enclosed
5842 in an argument by defining
5843 a command in a list within a list:
5846 Action([['cc', '-c', '-DWHITE SPACE', '-o', '$TARGET', '$SOURCES']])
5850 If the first argument is a Python function,
5851 a function Action is returned.
5852 The Python function takes three keyword arguments,
5854 (a Node object representing the target file),
5856 (a Node object representing the source file)
5859 (the construction environment
5860 used for building the target file).
5865 arguments may be lists of Node objects if there is
5866 more than one target file or source file.
5867 The actual target and source file name(s) may
5868 be retrieved from their Node objects
5869 via the built-in Python str() function:
5872 target_file_name = str(target)
5873 source_file_names = map(lambda x: str(x), source)
5876 The function should return
5880 to indicate a successful build of the target file(s).
5881 The function may raise an exception
5882 or return a non-zero exit status
5883 to indicate an unsuccessful build.
5886 def build_it(target = None, source = None, env = None):
5887 # build the target from the source
5890 a = Action(build_it)
5893 If the action argument is not one of the above,
5897 The second, optional argument
5898 is used to define the output which is printed
5899 when the Action is actually performed.
5900 In the absence of this parameter, or if it's an
5901 empty string, a default output depending on the type of the action
5902 is used. For example, a command-line action will print
5903 the executed command. The argument is either a python function
5906 In the first case, it's a function that returns
5907 a string to be printed to describe the action being executed.
5908 Like a function to build a file,
5909 this function takes three arguments:
5911 (a Node object representing the target file),
5913 (a Node object representing the source file)
5916 (a construction environment).
5921 arguments may be lists of Node objects if there is
5922 more than one target file or source file.
5924 In the second case, you provide the string itself.
5925 The string typically contains variables, notably
5926 $TARGET(S) and $SOURCE(S), or consists of just a single
5927 variable, which is optionally defined somewhere else.
5928 SCons itself heavily uses the latter variant.
5933 def build_it(target, source, env):
5934 # build the target from the source
5937 def string_it(target, source, env):
5938 return "building '%s' from '%s'" % (target[0], source[0])
5940 # Use a positional argument.
5941 f = Action(build_it, string_it)
5942 s = Action(build_it, "building '$TARGET' from '$SOURCE'")
5944 # Alternatively, use a keyword argument.
5945 f = Action(build_it, strfunction=string_it)
5946 s = Action(build_it, cmdstr="building '$TARGET' from '$SOURCE'")
5948 # You can provide a configurable variable.
5949 l = Action(build_it, '$STRINGIT')
5952 The third, also optional argument
5953 is a list of construction variables
5954 whose values will be included
5955 in the signature of the Action
5956 when deciding whether a target should
5957 be rebuilt because the action changed.
5958 This is necessary whenever you want a target to
5959 be rebuilt when a specific
5960 construction variable changes,
5961 because the underlying Python code for a function
5962 will not change when the value of the construction variable does.
5965 def build_it(target, source, env):
5966 # build the target from the 'XXX' construction variable
5967 open(target[0], 'w').write(env['XXX'])
5970 # Use positional arguments.
5971 a = Action(build_it, '$STRINGIT', ['XXX'])
5973 # Alternatively, use a keyword argument.
5974 a = Action(build_it, varlist=['XXX'])
5983 which specifies that
5984 scons will execute the action
5985 after changing to the specified directory.
5986 If the chdir argument is
5987 a string or a directory Node,
5988 scons will change to the specified directory.
5989 If the chdir argument
5990 is not a string or Node
5992 then scons will change to the
5993 target file's directory.
5995 Note that scons will
5997 automatically modify
5999 construction variables like
6003 when using the chdir
6004 keyword argument--that is,
6005 the expanded file names
6006 will still be relative to
6007 the top-level SConstruct directory,
6008 and consequently incorrect
6009 relative to the chdir directory.
6010 Builders created using chdir keyword argument,
6011 will need to use construction variable
6016 to use just the filename portion of the
6020 a = Action("build < ${SOURCE.file} > ${TARGET.file}",
6030 which specifies a function
6031 that is passed the exit status
6033 from the specified action
6034 and can return an arbitrary
6036 This can be used, for example,
6037 to specify that an Action object's
6038 return value should be ignored
6039 and SCons should, therefore,
6040 consider that the action always suceeds:
6043 def always_succeed(s):
6044 # Always return 0, which indicates success.
6046 a = Action("build < ${SOURCE.file} > ${TARGET.file}",
6047 exitstatfunc=always_succeed)
6050 .SS Miscellaneous Action Functions
6053 supplies a number of functions
6054 that arrange for various common
6055 file and directory manipulations
6057 These are similar in concept to "tasks" in the
6059 although the implementation is slightly different.
6060 These functions do not actually
6061 perform the specified action
6062 at the time the function is called,
6063 but instead return an Action object
6064 that can be executed at the
6066 (In Object-Oriented terminology,
6071 that return Action objects.)
6074 there are two natural ways
6077 are intended to be used.
6081 to perform the action
6082 at the time the SConscript
6086 global function to do so:
6088 Execute(Touch('file'))
6092 you can use these functions
6093 to supply Actions in a list
6097 This can allow you to
6098 perform more complicated
6099 sequences of file manipulation
6101 on platform-specific
6105 env = Environment(TMPBUILD = '/tmp/builddir')
6106 env.Command('foo.out', 'foo.in',
6107 [Mkdir('$TMPBUILD'),
6108 Copy('$TMPBUILD', '${SOURCE.dir}'),
6109 "cd $TMPBUILD && make",
6110 Delete('$TMPBUILD')])
6114 .RI Chmod( dest ", " mode )
6115 Returns an Action object that
6116 changes the permissions on the specified
6118 file or directory to the specified
6123 Execute(Chmod('file', 0755))
6125 env.Command('foo.out', 'foo.in',
6126 [Copy('$TARGET', '$SOURCE'),
6127 Chmod('$TARGET', 0755)])
6131 .RI Copy( dest ", " src )
6132 Returns an Action object
6135 source file or directory to the
6137 destination file or directory.
6141 Execute(Copy('foo.output', 'foo.input'))
6143 env.Command('bar.out', 'bar.in',
6144 Copy('$TARGET', '$SOURCE'))
6148 .RI Delete( entry ", [" must_exist ])
6149 Returns an Action that
6150 deletes the specified
6152 which may be a file or a directory tree.
6153 If a directory is specified,
6154 the entire directory tree
6159 then a Python error will be thrown
6160 if the specified entry does not exist;
6163 that is, the Action will silently do nothing
6164 if the entry does not exist.
6168 Execute(Delete('/tmp/buildroot'))
6170 env.Command('foo.out', 'foo.in',
6171 [Delete('${TARGET.dir}'),
6174 Execute(Delete('file_that_must_exist', must_exist=1))
6180 that creates the specified
6186 Execute(Mkdir('/tmp/outputdir'))
6188 env.Command('foo.out', 'foo.in',
6189 [Mkdir('/tmp/builddir',
6190 Copy('$SOURCE', '/tmp/builddir')
6191 "cd /tmp/builddir && ])
6196 .RI Move( dest ", " src )
6198 that moves the specified
6200 file or directory to
6207 Execute(Move('file.destination', 'file.source'))
6209 env.Command('output_file', 'input_file',
6211 Move('$TARGET', 'file_created_by_MyBuildAction')])
6217 that updates the modification time
6223 Execute(Touch('file_to_be_touched'))
6225 env.Command('marker', 'input_file',
6230 .SS Variable Substitution
6232 Before executing a command,
6234 performs construction variable interpolation on the strings that make up
6235 the command line of builders.
6236 Variables are introduced by a
6239 Besides construction variables, scons provides the following
6240 variables for each command execution:
6243 The file name of the target being built, or the file name of the first
6244 target if multiple targets are being built.
6247 The file names of all targets being built.
6250 The file name of the source of the build command, or the file name of the
6251 first source if multiple sources are being built.
6254 The file names of the sources of the build command.
6256 (Note that the above variables are reserved
6257 and may not be set in a construction environment.)
6260 For example, given the construction variable CC='cc', targets=['foo'], and
6261 sources=['foo.c', 'bar.c']:
6264 action='$CC -c -o $TARGET $SOURCES'
6267 would produce the command line:
6270 cc -c -o foo foo.c bar.c
6273 Variable names may be surrounded by curly braces ({})
6274 to separate the name from the trailing characters.
6275 Within the curly braces, a variable name may have
6276 a Python slice subscript appended to select one
6277 or more items from a list.
6278 In the previous example, the string:
6290 Additionally, a variable name may
6291 have the following special
6292 modifiers appended within the enclosing curly braces
6293 to modify the interpolated string:
6296 The base path of the file name,
6297 including the directory path
6298 but excluding any suffix.
6301 The name of the directory in which the file exists.
6305 minus any directory portion.
6308 Just the basename of the file,
6310 and minus the directory.
6313 Just the file suffix.
6316 The absolute path name of the file.
6319 The POSIX form of the path,
6320 with directories separated by
6324 This is sometimes necessary on Windows systems
6325 when a path references a file on other (POSIX) systems.
6328 The directory and file name to the source file linked to this file
6329 through BuildDir. If this file isn't linked, it just returns the
6330 directory and filename unchanged.
6333 The directory containing the source file linked to this file
6334 through BuildDir. If this file isn't linked, it just returns the
6335 directory part of the filename.
6338 The directory and file name to the source file linked to this file
6339 through BuildDir. If the file does not exist locally but exists in
6340 a Repository, the path in the Repository is returned.
6341 If this file isn't linked, it just returns the
6342 directory and filename unchanged.
6345 The Repository directory containing the source file linked to this file
6346 through BuildDir. If this file isn't linked, it just returns the
6347 directory part of the filename.
6350 For example, the specified target will
6351 expand as follows for the corresponding modifiers:
6354 $TARGET => sub/dir/file.x
6355 ${TARGET.base} => sub/dir/file
6356 ${TARGET.dir} => sub/dir
6357 ${TARGET.file} => file.x
6358 ${TARGET.filebase} => file
6359 ${TARGET.suffix} => .x
6360 ${TARGET.abspath} => /top/dir/sub/dir/file.x
6362 SConscript('src/SConscript', build_dir='sub/dir')
6363 $SOURCE => sub/dir/file.x
6364 ${SOURCE.srcpath} => src/file.x
6365 ${SOURCE.srcdir} => src
6367 Repository('/usr/repository')
6368 $SOURCE => sub/dir/file.x
6369 ${SOURCE.rsrcpath} => /usr/repository/src/file.x
6370 ${SOURCE.rsrcdir} => /usr/repository/src
6373 Lastly, a variable name
6374 may be a callable Python function
6376 construction variable in the environment.
6378 take four arguments:
6380 - a list of target nodes,
6382 - a list of source nodes,
6384 - the construction environment,
6386 - a Boolean value that specifies
6387 whether the function is being called
6388 for generating a build signature.
6389 SCons will insert whatever
6390 the called function returns
6391 into the expanded string:
6394 def foo(target, source, env, for_signature):
6397 # Will expand $BAR to "bar baz"
6398 env=Environment(FOO=foo, BAR="$FOO baz")
6401 You can use this feature to pass arguments to a
6402 Python function by creating a callable class
6403 that stores one or more arguments in an object,
6404 and then uses them when the
6407 Note that in this case,
6408 the entire variable expansion must
6409 be enclosed by curly braces
6410 so that the arguments will
6411 be associated with the
6412 instantiation of the class:
6416 def __init__(self, arg):
6419 def __call__(self, target, source, env, for_signature):
6422 # Will expand $BAR to "my argument bar baz"
6423 env=Environment(FOO=foo, BAR="${FOO('my argument')} baz")
6427 The special pseudo-variables
6431 may be used to surround parts of a command line
6434 causing a rebuild--that is,
6435 which are not included in the signature
6436 of target files built with this command.
6441 will be removed from the command line
6442 before it is added to file signatures,
6447 will be removed before the command is executed.
6448 For example, the command line:
6451 echo Last build occurred $( $TODAY $). > $TARGET
6455 would execute the command:
6458 echo Last build occurred $TODAY. > $TARGET
6462 but the command signature added to any target files would be:
6465 echo Last build occurred . > $TARGET
6468 SCons uses the following rules when converting construction variables into
6472 When the value is a string it is interpreted as a space delimited list of
6473 command line arguments.
6476 When the value is a list it is interpreted as a list of command line
6477 arguments. Each element of the list is converted to a string.
6480 Anything that is not a list or string is converted to a string and
6481 interpreted as a single command line argument.
6484 Newline characters (\\n) delimit lines. The newline parsing is done after
6485 all other parsing, so it is not possible for arguments (e.g. file names) to
6486 contain embedded newline characters. This limitation will likely go away in
6487 a future version of SCons.
6495 new file types for implicit dependencies.
6496 Scanner accepts the following arguments:
6499 A Python function that will process
6501 and return a list of strings (file names)
6502 representing the implicit
6503 dependencies found in the contents.
6504 The function takes three or four arguments:
6506 def scanner_function(node, env, path):
6508 def scanner_function(node, env, path, arg):
6512 argument is the internal
6513 SCons node representing the file.
6516 to fetch the name of the file, and
6517 .B node.get_contents()
6518 to fetch contents of the file.
6519 Note that the file is
6521 guaranteed to exist before the scanner is called,
6522 so the scanner function should check that
6523 if there's any chance that the scanned file
6525 (for example, if it's built from other files).
6529 argument is the construction environment for the scan.
6530 Fetch values from it using the
6536 argument is a tuple (or list)
6537 of directories that can be searched
6539 This will usually be the tuple returned by the
6541 argument (see below).
6545 argument is the argument supplied
6546 when the scanner was created, if any.
6549 The name of the Scanner.
6551 to identify the Scanner internally.
6554 An optional argument that, if specified,
6555 will be passed to the scanner function
6557 and the path function
6561 An optional list that can be used to
6562 determine which scanner should be used for
6564 In the usual case of scanning for file names,
6565 this argument will be a list of suffixes
6566 for the different file types that this
6567 Scanner knows how to scan.
6568 If the argument is a string,
6569 then it will be expanded
6570 into a list by the current environment.
6573 A Python function that takes four or five arguments:
6574 a construction environment,
6575 a Node for the directory containing
6576 the SConscript file in which
6577 the first target was defined,
6578 a list of target nodes,
6579 a list of source nodes,
6580 and an optional argument supplied
6581 when the scanner was created.
6584 returns a tuple of directories
6585 that can be searched for files to be returned
6586 by this Scanner object.
6589 The class of Node that should be returned
6590 by this Scanner object.
6591 Any strings or other objects returned
6592 by the scanner function
6593 that are not of this class
6594 will be run through the
6599 A Python function that will take a string
6601 and turn it into the appropriate class of Node
6602 to be returned by this Scanner object.
6605 An optional Python function that takes two arguments,
6606 a Node (file) and a construction environment,
6607 and returns whether the
6608 Node should, in fact,
6609 be scanned for dependencies.
6610 This check can be used to eliminate unnecessary
6611 calls to the scanner function when,
6612 for example, the underlying file
6613 represented by a Node does not yet exist.
6616 An optional flag that
6617 specifies whether this scanner should be re-invoked
6618 on the dependency files returned by the scanner.
6619 When this flag is not set,
6620 the Node subsystem will
6621 only invoke the scanner on the file being scanned,
6622 and not (for example) also on the files
6623 specified by the #include lines
6624 in the file being scanned.
6626 may be a callable function,
6627 in which case it will be called with a list of
6629 should return a list of Nodes
6630 that should be scanned recursively;
6631 this can be used to select a specific subset of
6632 Nodes for additional scanning.
6637 .B SourceFileScanner
6638 object that is used by
6641 .BR SharedObject (),
6645 which scanner should be used
6646 for different file extensions.
6648 .BR SourceFileScanner.add_scanner ()
6649 method to add your own Scanner object
6653 that builds target programs or
6654 libraries from a list of
6655 source files of different types:
6658 def xyz_scan(node, env, path):
6659 contents = node.get_contents()
6660 # Scan the contents and return the included files.
6662 XYZScanner = Scanner(xyz_scan)
6664 SourceFileScanner.add_scanner('.xyx', XYZScanner)
6666 env.Program('my_prog', ['file1.c', 'file2.f', 'file3.xyz'])
6669 .SH SYSTEM-SPECIFIC BEHAVIOR
6670 SCons and its configuration files are very portable,
6671 due largely to its implementation in Python.
6672 There are, however, a few portability
6673 issues waiting to trap the unwary.
6675 SCons handles the upper-case
6677 file suffix differently,
6678 depending on the capabilities of
6679 the underlying system.
6680 On a case-sensitive system
6681 such as Linux or UNIX,
6682 SCons treats a file with a
6684 suffix as a C++ source file.
6685 On a case-insensitive system
6687 SCons treats a file with a
6689 suffix as a C source file.
6691 SCons handles the upper-case
6693 file suffix differently,
6694 depending on the capabilities of
6695 the underlying system.
6696 On a case-sensitive system
6697 such as Linux or UNIX,
6698 SCons treats a file with a
6700 suffix as a Fortran source file
6701 that is to be first run through
6702 the standard C preprocessor.
6703 On a case-insensitive system
6705 SCons treats a file with a
6707 suffix as a Fortran source file that should
6709 be run through the C preprocessor.
6710 .SS Windows: Cygwin Tools and Cygwin Python vs. Windows Pythons
6711 Cygwin supplies a set of tools and utilities
6712 that let users work on a
6713 Windows system using a more POSIX-like environment.
6714 The Cygwin tools, including Cygwin Python,
6716 by sharing an ability to interpret UNIX-like path names.
6717 For example, the Cygwin tools
6718 will internally translate a Cygwin path name
6719 like /cygdrive/c/mydir
6720 to an equivalent Windows pathname
6721 of C:/mydir (equivalent to C:\\mydir).
6724 that are built for native Windows execution,
6725 such as the python.org and ActiveState versions,
6726 do not have the Cygwin path name semantics.
6727 This means that using a native Windows version of Python
6728 to build compiled programs using Cygwin tools
6729 (such as gcc, bison, and flex)
6730 may yield unpredictable results.
6731 "Mixing and matching" in this way
6732 can be made to work,
6733 but it requires careful attention to the use of path names
6734 in your SConscript files.
6736 In practice, users can sidestep
6737 the issue by adopting the following rules:
6739 use the Cygwin-supplied Python interpreter
6741 when using Microsoft Visual C/C++
6742 (or some other Windows compiler)
6743 use the python.org or ActiveState version of Python
6745 .SS Windows: scons.bat file
6747 SCons is executed via a wrapper
6750 This has (at least) two ramifications:
6752 First, Windows command-line users
6753 that want to use variable assignment
6755 may have to put double quotes
6756 around the assignments:
6759 scons "FOO=BAR" "BAZ=BLEH"
6762 Second, the Cygwin shell does not
6763 recognize this file as being the same
6766 command issued at the command-line prompt.
6767 You can work around this either by
6770 from the Cygwin command line,
6771 or by creating a wrapper shell
6777 The MinGW bin directory must be in your PATH environment variable or the
6778 PATH variable under the ENV construction variable for SCons
6779 to detect and use the MinGW tools. When running under the native Windows
6780 Python interpreter, SCons will prefer the MinGW tools over the Cygwin
6781 tools, if they are both installed, regardless of the order of the bin
6782 directories in the PATH variable. If you have both MSVC and MinGW
6783 installed and you want to use MinGW instead of MSVC,
6784 then you must explictly tell SCons to use MinGW by passing
6790 to the Environment() function, because SCons will prefer the MSVC tools
6791 over the MinGW tools.
6795 To help you get started using SCons,
6796 this section contains a brief overview of some common tasks.
6798 .SS Basic Compilation From a Single Source File
6802 env.Program(target = 'foo', source = 'foo.c')
6805 Note: Build the file by specifying
6806 the target as an argument
6807 ("scons foo" or "scons foo.exe").
6808 or by specifying a dot ("scons .").
6810 .SS Basic Compilation From Multiple Source Files
6814 env.Program(target = 'foo', source = Split('f1.c f2.c f3.c'))
6817 .SS Setting a Compilation Flag
6820 env = Environment(CCFLAGS = '-g')
6821 env.Program(target = 'foo', source = 'foo.c')
6824 .SS Search The Local Directory For .h Files
6828 need to set CCFLAGS to specify -I options by hand.
6829 SCons will construct the right -I options from CPPPATH.
6832 env = Environment(CPPPATH = ['.'])
6833 env.Program(target = 'foo', source = 'foo.c')
6836 .SS Search Multiple Directories For .h Files
6839 env = Environment(CPPPATH = ['include1', 'include2'])
6840 env.Program(target = 'foo', source = 'foo.c')
6843 .SS Building a Static Library
6847 env.StaticLibrary(target = 'foo', source = Split('l1.c l2.c'))
6848 env.StaticLibrary(target = 'bar', source = ['l3.c', 'l4.c'])
6851 .SS Building a Shared Library
6855 env.SharedLibrary(target = 'foo', source = ['l5.c', 'l6.c'])
6856 env.SharedLibrary(target = 'bar', source = Split('l7.c l8.c'))
6859 .SS Linking a Local Library Into a Program
6862 env = Environment(LIBS = 'mylib', LIBPATH = ['.'])
6863 env.Library(target = 'mylib', source = Split('l1.c l2.c'))
6864 env.Program(target = 'prog', source = ['p1.c', 'p2.c'])
6867 .SS Defining Your Own Builder Object
6869 Notice that when you invoke the Builder,
6870 you can leave off the target file suffix,
6871 and SCons will add it automatically.
6874 bld = Builder(action = 'pdftex < $SOURCES > $TARGET'
6876 src_suffix = '.tex')
6877 env = Environment(BUILDERS = {'PDFBuilder' : bld})
6878 env.PDFBuilder(target = 'foo.pdf', source = 'foo.tex')
6880 # The following creates "bar.pdf" from "bar.tex"
6881 env.PDFBuilder(target = 'bar', source = 'bar')
6884 Note also that the above initialization
6885 overwrites the default Builder objects,
6886 so the Environment created above
6887 can not be used call Builders like env.Program(),
6888 env.Object(), env.StaticLibrary(), etc.
6890 .SS Adding Your Own Builder Object to an Environment
6893 bld = Builder(action = 'pdftex < $SOURCES > $TARGET'
6895 src_suffix = '.tex')
6897 env.Append(BUILDERS = {'PDFBuilder' : bld})
6898 env.PDFBuilder(target = 'foo.pdf', source = 'foo.tex')
6899 env.Program(target = 'bar', source = 'bar.c')
6902 You also can use other Pythonic techniques to add
6903 to the BUILDERS construction variable, such as:
6907 env['BUILDERS]['PDFBuilder'] = bld
6910 .SS Defining Your Own Scanner Object
6915 '\" Note: the \\ in the following are for the benefit of nroff/troff,
6916 '\" not inappropriate doubled escape characters within the r'' raw string.
6917 include_re = re.compile(r'^include\\s+(\\S+)$', re.M)
6919 def kfile_scan(node, env, path, arg):
6920 contents = node.get_contents()
6921 includes = include_re.findall(contents)
6924 kscan = Scanner(name = 'kfile',
6925 function = kfile_scan,
6928 scanners = Environment().Dictionary('SCANNERS')
6929 env = Environment(SCANNERS = scanners + [kscan])
6931 env.Command('foo', 'foo.k', 'kprocess < $SOURCES > $TARGET')
6933 bar_in = File('bar.in')
6934 env.Command('bar', bar_in, 'kprocess $SOURCES > $TARGET')
6935 bar_in.target_scanner = kscan
6938 .SS Creating a Hierarchical Build
6940 Notice that the file names specified in a subdirectory's
6942 file are relative to that subdirectory.
6948 env.Program(target = 'foo', source = 'foo.c')
6950 SConscript('sub/SConscript')
6955 # Builds sub/foo from sub/foo.c
6956 env.Program(target = 'foo', source = 'foo.c')
6958 SConscript('dir/SConscript')
6963 # Builds sub/dir/foo from sub/dir/foo.c
6964 env.Program(target = 'foo', source = 'foo.c')
6967 .SS Sharing Variables Between SConscript Files
6969 You must explicitly Export() and Import() variables that
6970 you want to share between SConscript files.
6976 env.Program(target = 'foo', source = 'foo.c')
6979 SConscript('subdirectory/SConscript')
6981 subdirectory/SConscript:
6984 env.Program(target = 'foo', source = 'foo.c')
6987 .SS Building Multiple Variants From the Same Source
6989 Use the build_dir keyword argument to
6990 the SConscript function to establish
6991 one or more separate build directories for
6992 a given source directory:
6997 cppdefines = ['FOO']
6998 Export("cppdefines")
6999 SConscript('src/SConscript', build_dir='foo')
7001 cppdefines = ['BAR']
7002 Export("cppdefines")
7003 SConscript('src/SConscript', build_dir='bar')
7007 Import("cppdefines")
7008 env = Environment(CPPDEFINES = cppdefines)
7009 env.Program(target = 'src', source = 'src.c')
7012 Note the use of the Export() method
7013 to set the "cppdefines" variable to a different
7014 value each time we call the SConscript function.
7016 .SS Hierarchical Build of Two Libraries Linked With a Program
7021 env = Environment(LIBPATH = ['#libA', '#libB'])
7023 SConscript('libA/SConscript')
7024 SConscript('libB/SConscript')
7025 SConscript('Main/SConscript')
7030 env.Library('a', Split('a1.c a2.c a3.c'))
7035 env.Library('b', Split('b1.c b2.c b3.c'))
7040 e = env.Copy(LIBS = ['a', 'b'])
7041 e.Program('foo', Split('m1.c m2.c m3.c'))
7044 The '#' in the LIBPATH directories specify that they're relative to the
7045 top-level directory, so they don't turn into "Main/libA" when they're
7046 used in Main/SConscript.
7048 Specifying only 'a' and 'b' for the library names
7049 allows SCons to append the appropriate library
7050 prefix and suffix for the current platform
7051 (for example, 'liba.a' on POSIX systems,
7052 'a.lib' on Windows).
7054 .SS Customizing contruction variables from the command line.
7056 The following would allow the C compiler to be specified on the command
7057 line or in the file custom.py.
7060 opts = Options('custom.py')
7061 opts.Add('CC', 'The C compiler.')
7062 env = Environment(options=opts)
7063 Help(opts.GenerateHelpText(env))
7066 The user could specify the C compiler on the command line:
7072 or in the custom.py file:
7078 or get documentation on the options:
7089 .SS Using Microsoft Visual C++ precompiled headers
7091 Since windows.h includes everything and the kitchen sink, it can take quite
7092 some time to compile it over and over again for a bunch of object files, so
7093 Microsoft provides a mechanism to compile a set of headers once and then
7094 include the previously compiled headers in any object file. This
7095 technology is called precompiled headers. The general recipe is to create a
7096 file named "StdAfx.cpp" that includes a single header named "StdAfx.h", and
7097 then include every header you want to precompile in "StdAfx.h", and finally
7098 include "StdAfx.h" as the first header in all the source files you are
7099 compiling to object files. For example:
7103 #include <windows.h>
7104 #include <my_big_header.h>
7123 /* do some other stuff */
7129 env['PCHSTOP'] = 'StdAfx.h'
7130 env['PCH'] = env.PCH('StdAfx.cpp')[0]
7131 env.Program('MyApp', ['Foo.cpp', 'Bar.cpp'])
7134 For more information see the document for the PCH builder, and the PCH and
7135 PCHSTOP construction variables. To learn about the details of precompiled
7136 headers consult the MSDN documention for /Yc, /Yu, and /Yp.
7138 .SS Using Microsoft Visual C++ external debugging information
7140 Since including debugging information in programs and shared libraries can
7141 cause their size to increase significantly, Microsoft provides a mechanism
7142 for including the debugging information in an external file called a PDB
7143 file. SCons supports PDB files through the PDB construction
7149 env['PDB'] = 'MyApp.pdb'
7150 env.Program('MyApp', ['Foo.cpp', 'Bar.cpp'])
7153 For more information see the document for the PDB construction variable.
7158 Specifies the directory that contains the SCons Python module directory
7159 (e.g. /home/aroach/scons-src-0.01/src/engine).
7162 A string of options that will be used by scons in addition to those passed
7163 on the command line.
7174 Steven Knight <knight@baldmt.com>
7176 Anthony Roach <aroach@electriceyeball.com>